6 Accessing the DDS object

6 Accessing the DDS object

The Data Descriptor Structure (DDS) is a data structure used by the DODS software to describe datasets and subsets of those datasets. The DDS may be thought of as the declarations for the data structures that will hold data requested by some DODS client. Part of the job of a DODS server is to build a suitable DDS for a specific dataset and to send it to the client. Depending on the data access API in use, this may involve reading part of the dataset and inferring the DDS. Other APIs may require the server simply to read some ancillary data file with the DDS in it.

For the client, the DDS object includes methods for reading the persistent form of the object sent from a server. This includes parsing the ASCII representation of the object and, possibly, reading data received from a server into a data object.

Note that the class DDS is used to instantiate both DDS and DataDDS objects. A DDS that is empty (contains no actual data) is used by servers to send structural information to the client. The same DDS can be treated as a DataDDS when data values are bound to the variables it defines.

For a complete description of the DDS layout and protocol, please refer to The OPeNDAP User Guide and The DODS Toolkit Programmer's Guide.

The DDS has an ASCII representation, which is what is transmitted from a DODS server to a client. Here is the DDS representation of an entire dataset containing a time series of worldwide grids of sea surface temperatures:

Dataset {
    Grid {
      ARRAY:
	 Int32 sst[time = 404][lat = 180][lon = 360];
      MAPS:
	 Float64 time[time = 404];
	 Float64 lat[lat = 180];
	 Float64 lon[lon = 360];
    } sst;
} weekly;

If the data request to this dataset includes a constraint expression, the corresponding DDS might be different. For example, if the request was only for northern hemisphere data at a specific time, the above DDS might be modified to appear like this:

Dataset {
    Grid {
      ARRAY:
	 Int32 sst[time = 1][lat = 90][lon = 360];
      MAPS:
	 Float64 time[time = 1];
	 Float64 lat[lat = 90];
	 Float64 lon[lon = 360];
    } sst;
} weekly;

The constraint has narrowed the area of interest; the range of latitude values has been halved and there is only one time value in the returned array.

See The OPeNDAP User Guide , The DODS Toolkit Reference for descriptions of the DODS data types.

Reading data from a DDS object is the heart of writing your own OPeNDAP client. To integrate the information contained in the DDS, you must do two things. First you must decide how the data type hierarchy that is part of the DAP can be represented in your client application. Some client applications cannot represent all possible DAP data types directly. Where possible the client developer should strive to support as many data types as possible to facilitate access to the wide variety of data accessible through OPeNDAP servers. In practice, once you know how to map variables from the DAP into your client application, writing code to build the DDS instance is easy.

else if (get_dds) {
    for (int j = 0; j < times; ++j) {
	DDS dds;
	try {
	    url->request_dds(dds);
	}
	catch (Error &e) {
	    e.display_message();
	    delete url; url = 0;
	    continue;	// Goto the next URL or exit the loop.
	}

	if (verbose) {
	    fprintf( stderr, "Server version: %s\n",
			     url->get_version().c_str() ) ; 
	    fprintf( stderr, "DDS:\n" ) ;
	}

	dds.print(stdout);
    }
}

Above, the Connect method request_dds is called, passing a reference to a DDS object. Following is an example from the C++ Matlab client illustrates a simple traversal of the DDS object returned from the connect::request_data method.

static void
process_data(Connect &url, DDS &dds)
{
   if (verbose)
       cerr << "Server version: " << url.server_version() << endl;

   for (DDS::Vars_iter i = dds.var_begin(); i != dds.var_end(); i++) {
       BaseType *v = *i ;
       v->print_decl(cout, "", true);
       smart_newline(cout, v->type());
   }
}

In the C++ DAP classes STL iterators are used to iterate over the members (i.e., variables) in the DDS object. The iterator i references pointers to the top-level BaseType objects held by the DDS. See Jouspurtis[1] for information about the Standard Template Library and STL iterators. The The DODS Toolkit Programmer's Guide provides a description for the each of the data types, and the methods available to operate on them.

6 Accessing the DDS object