cdunif(3)

NAME
cdunif - CDMS uniform I/O functions for accessing DRS, GrADS (GRIB), HDF, and netCDF datafiles.

SYNOPSIS

#include "cdunif.h"

int cuopenread(const char* controlpath, const char* datapath)

int cuclose(int fileid)

int cuinquire(int fileid, int* ngdims, int* nvars, int* natts, int* recdim)

int cudimid(int fileid, int varid, const char* name)

int cudiminq(int fileid, int dimid, char* dimname, char* dimunits, CuType* dataType, CuDimType* dimtype, int* varid, long* length)

int cudimget(int fileid, int dimid, void* values)

int cuvarid(int fileid, const char* name)

int cuvarinq(int fileid, int varid, char* name, CuType* datatype, int* ndims, int dimids[], int* natts)

int cuvarget(int fileid, int varid, const long start[], const long count[], void* value)

int cuvargets(int fileid, int varid, const long order[], const long start[], const long count[], const long stride[], CuType cast, void* values)

int cuattinq(int fileid, int varid, const char* name, CuType* datatype, int* len)

int cuattget(int fileid, int varid, const char* name, void* value)

int cuattname(int fileid, int varid, int attnum, char* name)

int cutypelen(CuType datatype)

int cusetlu(int lu1, int lu2)

void cuseterropts(int erropts)

int cugeterr(void)

DESCRIPTION

These routines implement a uniform, read-only interface to data and metadata contained in CDMS data files. Via this interface, CDMS supports access to DRS, GrADS (GRIB), HDF scientific datasets, and netCDF files. GRIB files can be read only if a GrADS control file is also supplied.

The cdunif interface is modeled very closely on the UCAR netCDF interface; in many cases there are functions in netCDF whose prototype is identical except for name. The exceptions are the cuopenread, cudimid, and cudiminq functions. Also, there are several functions with no counterpart in the netCDF API: cudimget, cusetlu, cuvargets, cuseterropts, and cugeterr.

The logical model for metadata in cdunif is very similar to that of netCDF. A file contains a set of variables, dimensions, and attributes. Variables are identified by integer ID or name; variable IDs range from 0 to (number of variables)-1. Attributes are also identified by number or name, and can be global or related to a variable.

Dimensions are treated somewhat differently than in netCDF. Some of the file formats supported by cdunif, notably DRS, support dimensions which are local to a given variable - they are not shared by different variables and do not have unique names relative to other dimensions. Consequently, the distinction is made between local and global dimensions, which can be shared (DRS vector dimensions are global).

Also, every dimension has an associated coordinate vector, which can be retrieved with cudimget. Like netCDF, dimensions are identified by name or numeric ID; both local and global dimensions have unique numeric IDs, which are sequential integers starting at 0.

DATATYPES
The cdunif interface supports the following datatypes: byte, char, short, int, long, float, double, and long double. These datatypes correspond to the C datatypes.

byte and char are both 8-bit datatypes; the difference is that arrays of chars are assumed to be null-terminated.

Note that the datatype of a variable in cdunif describes the data as it will be retrieved from the datafile, as opposed to the internal physical format of the data. This convention allows use of the cutypelen function to allocate memory for data retrieval.

The include file cdunif.h defines an enumeration type CuType, which can have the values CuByte, CuChar, CuShort, CuInt, CuLong, CuFloat, CuDouble, or CuLongDouble.

FUNCTION DESCRIPTIONS

int cuopenread(const char* controlpath, const char* datapath)

Opens an existing CDMS file for read or inquiry.

For DRS files, the controlpath is the full pathname of the DRS dictionary file, and the datapath is the pathname of the data file. If the datapath is NULL (char* 0), then the data file is assumed to have the same name as the controlpath, with a '.dat' extension instead.

For GrADS files, the controlpath is the GrADS data descriptor file, and the datapath is ignored.

For netCDF and HDF files, the controlpath is the full pathname of the file, and the datapath is ignored.

The function returns the CDMS fileid on success, -1 on error.

int cuclose(int fileid)

Closes an open CDMS file. The function returns 0 on success, -1 on failure.

int cuinquire(int fileid, int* ndims, int* nvars, int* natts, int* recdim)

Returns information about an open CDMS file. ngdims is the total number of dimensions, both global and local, in the file. nvars is the number of variables in the file, natts is the number of global attributes in the file. For netCDF files, recdim is the dimension number of the unlimited dimension; for other file types, recdim will return with a value of -1. To suppress return of a specific value, set the argument to NULL (int* 0). The function returns 0 on success, -1 on error.

int cudimid(int fileid, int varid, const char* name)

Returns the ID of a dimension of a variable, or -1 if an error occurs. If varid is CU_GLOBAL, then only global (shared) dimensions are searched.

int cudiminq(int fileid, int dimid, char* dimname, char* dimunits, CuType* datatype, CuDimType* dimtype, int* varid, long* length)

Returns the name, units (or an empty string if none), datatype, dimension type (CuGlobalDim or CuLocalDim), associated variable for local dimensions (or CU_GLOBAL if global), and length (number of elements) of a dimension. datatype is the datatype of the coordinate vector for this dimension, or CuFloat if no such vector exists. Set any return arguments to NULL to suppress a return value. Character arrays may be dimensioned CU_MAX_NAME to guarantee enough memory for the return argument. The function returns 0 on success, -1 on error.

int cudimget(int fileid, int dimid, void* values)

Returns the values of the associated coordinate vector, if any, or the float array <0.0, 1.0, ..., (float)(dimlen-1)>, where dimlen is the length of the dimension. Function value is 0 on success, -1 on failure.

int cuvarid(int fileid, const char* name)

Returns the ID of a variable with name name. The function returns 0 on success, -1 on error.

int cuvarinq(int fileid, int varid, char* name, CuType* datatype, int* ndims, int dimids[], int* natts)

Returns the name, datatype, number of dimensions, dimension IDs, and number of attributes associated with a variable. dimids[] should be dimensioned CU_MAX_VAR_DIMS. It is returned as an array of length ndims, of dimension IDs for the variable. If a parameter is set to NULL, no value is returned for that parameter. The function returns 0 on success, -1 on error.

int cuvarget(int fileid, int varid, const long start[], const long count[], void* value)

Reads a hyperslab of data. The region of the hyperslab is specified by the arrays start and count. start is an array of 0-origin starting indices for each dimension of the variable. count is the number of values to read in that dimension, starting at start. The function returns 0 on success, -1 on error.

int cuvargets(int fileid, int varid, const long order[], const long start[], const long count[], const long stride[], CuType cast, void* values)

Reads a generalized hyperslab of data. The region of the hyperslab is specified by the arrays start and count. start is an array of 0-origin starting indices for each dimension of the variable. count is the number of values to read in that dimension, starting at start. If start[i]+count[i] is greater than the length of the i-th dimension, the data returned will be wrapped modulo the length of the dimension. start and count have dimension ordering as specified by the order argument.

The data is returned with dimensions ordered <order[0], order[1], ..., order[ndims-1]>, relative to the order of dimensions as defined in the file. Dimension indices start at 0. If order is NULL, it defaults to <0, 1,

stride is an array of strides for each dimension. For example, if stride[i] is 2, every other value along the i-th dimension is returned. Similarly, if stride[i] is -1, the direction of data retrieved along that dimension is reversed. A NULL stride argument defaults to <1, 1, ..., 1>, that is, all data values in the region are returned.

The cast argument specifies the datatype to which data should be cast on return. It is one of the CuType values (see DATATYPES above). If cast is NULL, no casting is performed.

The data is returned in the array values. The function returns 0 on success, -1 on error.

int cuattinq(int fileid, int varid, const char* name, CuType* datatype, int* len)

Returns the datatype, and number of elements (not byte length) of an attribute of a variable. datatype is one of CuByte, CuChar, CuShort, CuInt, CuLong, CuFloat, CuDouble, or CuLongDouble. Note: if the datatype is CuChar, the element count len is the number of characters in the character string, which may or may not include a null-terminating character, depending on the underlying file format. If a return parameter is set to NULL, no value is returned for that parameter. The function returns 0 on success, -1 on error.

int cuattget(int fileid, int varid, const char* name, void* value)

Returns the value of an attribute of a variable, in value. The function returns 0 on success, -1 on error.

int cuattname(int fileid, int varid, int attnum, char* name)

Returns the name of attribute attnum of a variable. If varid is CU_GLOBAL, then a global attribute is retrieved. The function returns 0 on success, -1 on error.

int cutypelen(CuType datatype)

Returns the byte length of a datatype, or -1 if an error occurred.

int cusetlu(int lu1, int lu2)

Sets the logical unit numbers to be used if the file is in DRS format. This function should be used if other Fortran logical unit numbers are in use, to avoid conflicts when accessing DRS files. If this function is not used, cdunif will by default choose two free logical unit numbers between 51 and 98. If either lu1 or lu2 is already in use for Fortran I/O, an error will occur on the call to cuopenread for a DRS file. Logical units are ignored for non-DRS files. Use of unit numbers 0, 5, and 6, should be avoided, as they may conflict with system defaults. The function returns 0 on success, -1 on error.

void cuseterropts(int erropts)

Set the error processing options. The CU_VERBOSE option causes errors to be reported; the CU_FATAL option causes an immediate exit after a fatal error has occurred. Default is CU_VERBOSE.

int cugeterr(void)

Returns the value of the most recent error.

SEE ALSO
netcdf(3), hdf(1), cdms(3).

BUGS

The cdunif interface implements hyperslab access to data only; no record-oriented access is currently provided.