Matlab GUI Documentation -- 3.2 The "Get" Function

3 Adding Your Own Datasets to the OPeNDAP Matlab GUI

getxxx Function Modes" alt="3.2.1 getxxx Function Modes" src="http://opendap.org/icons/ts-next.gif"> Index

3.2 The "Get" Function

The getxxx function, another Matlab program, serves as the connection between the OPeNDAP browser and individual datasets, hiding their idiosyncracies and providing a uniform interface between the browser and the data. Some get functions may serve for more than one dataset, such as getrectg.m, a function that works for a number of gridded datasets. The getxxx function can be named anything, but Can't exec program: /usr/local/bin/giftext.pl convention dictates that the name be of the form getxxx.m, where xxx is some sequence of characters that indicates the dataset (or class of datasets) for which the getxxx function is used. Note that several getxxx functions are provided with the OPeNDAP Matlab GUI; be careful to avoid those names.

A getxxx function has 3 modes of operation (or 3 subroutines). Each mode receives the same input arguments, although for some arguments and some datasets, not all the incoming information will be used. The modes differ in their action, and in the data they return to the calling function. The input arguments to the getxxx function are as follows:

function [arg1,...] = getxxx (mode, ranges, dataset, vars, stride, num_urls, georange, variables, archive, whichurl, url_info)

mode: A string argument which may be cat (short for `catalog'), datasize, or get. The return values of this function differ depending on the mode argument. They are outlined in the following sections.
ranges: A 4x2 matrix containing the current user-selected longitude, latitude, depth and time ranges. The first column is the minimum and the second the maximum.
dataset: An index number into an ordered list of datasets contained within the browser. You can use this to check whether the dataset is the same one as was specified in the previous request.
vars: A vector of indexes into an ordered list of user-selectable variables contained within the browser. You can use this to check whether the request has changed since the last request made, but use the variable list for the names of the requested variables.
stride: A user-selected subsampling interval for gridded datasets. A stride value of two requests every other data value, three gets you every third, and so on.
num_urls: The number of URLs in a data request.
georange: A two-element vector indicating the geographic orientation and ranges of the browser display -- typically this will be [-180 180] or [0 360] but can be set to other values.
variablelist: A character array of the variable names selected by the user.
archive: The name of the archive.m file for the selected dataset.
whichurl: - For a "catalog" mode request, this is a structure containing information about the data to be found at the URL. For a "get" mode request, this is an index into a list of URLs that comprise a data request. The list will have been returned by a cat mode request to the getxxx function.

In some modes, a particular input argument will not contain valid information. For example, the input number of URLs is not valid for a catalog request, since part of the function of the catalog mode is to determine the number of URLs needed to satisfy a request. However, all arguments are passed in each time for the sake of consistency.

Tom Sgouros, December 21, 2004