Index Go backward to Get Mode Go up to 3.2 The "Get" Function Go forward to 3.3 Adding a New Dataset

3.2.2 getxxx Function Tools

OPeNDAP provides several tools with which to construct your getxxx function. The tools fall into two broad classes:

• loaddods, the function used to dereference an OPeNDAP URL, and
• a set of Matlab utility functions, useful for the sorts of operations likely to be needed by a getxxx function.

The loaddods Function

The loaddods³ function is the OPeNDAP client for the Matlab browser. Can't exec program: /usr/local/bin/giftext.pl The function accepts a URL from the user, sends it out over the internet, and creates Matlab scalars, vectors, and matrices to hold the data that is returned from that request. The loaddods.m help file contains several examples of its use. (Type help loaddods at the Matlab command prompt.)

The function is called like this:

function values = loaddods([switches,] URL [per-url switches] [, URL [per-url switches]])

switches

These options are all off by default except for -v which is on by default.

-v:

Verbose output. (This option is on by default; use +v to disable it).

-g:

Use the Tcl/Tk progress and error reporting GUI. (This displays a bar graph showing transmission activity, and is not to be confused with the OPeNDAP Matlab GUI. See OPeNDAP User Guide for more information about this feature.).

-k:

This switch causes loaddods to concatenate two or more variables with same name. When reading from multi-file datasets, use this option to concatenate the values read from several accesses into a single Matlab variable. This is intended for getxxx functions which build up lists of URLs and pass them to loaddods for evaluation.

You must supply the URLs whose variables are to be concatenated in a single invocation of loaddods. The -k switch will not work across two or more calls to loaddods. That is,

loaddods('-k', '<URL1> <URL2') 

will work, while calling loaddods twice with -k (once for URL1 and once for URL2) won't work.

-n:

This command switch causes Matlab variable names to be built using the complete name of the variable, including all the constructor types which contain it. Without -n, variables are named using the name of the leaf variable. This means, for example, that two separate Structures who each happen to have a member with the same name will create a name conflict.

-s:

Return a vector of variable names along with the variables themselves. The -s option can only be used when assigning the values accessed by loaddods to a vector. If -s is used in this situation, then the first variable in the vector will be set to a vector of strings which name the successive variables.

-V:

Print version information for loaddods and any programs it uses.

-t[abclmpstu]:

Enable HTTP tracing (only for the hardcore...).

-F:

Force all string variables to be translated to float. The -F option is needed when reading from datasets that return as string values that should be interned as numbers.

CAUTION: This is a change from previous versions of loaddods and introduces potential incompatibilities with version 1.5 and prior. In other words you'll need to change your software if it used version 1.5 or earlier.

-p:

Recognize the DDMMSS strings and convert them (takes precedence over -F).

-A:

The -A option provides a way to access the DAS object of a dataset. Given with a URL, -A will cause all attributes to be interned in the Matlab workspace. Given with -c only the contents of named attribute container⁴ in a dataset will be interned. The latter is much safer since many DAS objects contain long names and names that repeat in several containers. Choosing an attribute container known to have `Matlab safe' identifiers is a good idea. (See OPeNDAP User Guide for more information about the DAS structure, and attributes in general.) Note that the attributes are interned into the Matlab workspace under their own names, not the name of the container⁵.

NOTE: While DAS objects are separate from the DDS (data) objects in OPeNDAP, once loaddods reads the information from the writeval client program they are treated no differently than data objects. Each attribute container is interned as if it was a Structure variable in the
DDS object.

per-url switches

These options are all off by default.

-r var:new name.:

Rename a variable. The -r option provides a way to rename variables so that variables read will not overwrite ones already present in a Matlab session.

-c expr:

Supply a constraint without using the ? notation.

URL

The loaddods function should be called with a OPeNDAP URL which references data, in which case the command will access the dataset and create Matlab data structures to hold those data. If the URL argument is a * or ?, loaddods will cause Netscape to start up and open the default OPeNDAP URL-builder. If the * or ? is followed by a URL, then that URL will be used instead of the URL builder. Finally, when called without an argument, the command will wait for a URL to be passed to it by Netscape or another program⁶.

loaddap

The loaddods function is at the core of the OPeNDAP Matlab GUI. However, for backwards compatibility, it was originally written not to take advantage of the advanced data structures now available in Matlab. The loaddap function is a newer version, that makes use of Matlab data structures in an attempt to preserve the structure of datasets.

For example, if the target dataset contains three arrays in a structure, the loaddods function will bring them in as three arrays. The loaddap function will import the data as three arrays in a structure, corresponding to the original arrangement.

The use of loaddap is identical in all other respects to loaddods.

If you find that the OPeNDAP Matlab GUI is more work than is necessary for your application, and you use the command-line client, you might consider using loaddap.

Utility Functions

Several functions used in the OPeNDAP Matlab GUI are general enough to be of use to people who have to write new getxxx functions⁷. This section contains a short list of some of the functions likely to be useful. The list is not complete, since the whole collection is Can't exec program: /usr/local/bin/giftext.pl fairly fluid, as new datasets are constantly being added to the archive. We encourage function writers to browse the OPeNDAP Matlab GUI directories before starting in on what may seem like a common problem.

Many of the utility functions are listed below. Use the Matlab help command for details of their invocation.

day2year

Converts an integer day into a decimal year.

dods_dbk

Removes trailing blanks from a string, and translates http escape sequences (e.g. %20) into underscores, so that Surface%20Temperature gets translated into Surface_Temperature.

dods_ddt

("de-dot") Removes the parent structure name from compound names. For example, Cast.Temperature is changed to Temperature. Actually, it removes all of a string up to and including the right-most period.

findnew

This function returns the position of non-duplicate data in a vector. It is useful for pruning duplicate information from a string or vector.

isleap

Accepts an integer year AD, and returns 1 if it is a leap year according to Pope Gregory's newfangled calendar.

mminmax

Finds the minimum and maximum of a vector or a matrix, and returns them in a two-element vector. The function is robust with respect to NaN.

strntok

Given a string and a token separator, quickly extracts tokens from short input strings.

year2day

Converts a decimal year into an integer day. (Note that 1985.0 will return day 0. To convert to the more common calendrical representation, where days are numbered from one, you must add one to the returned day integer.)