cdms(3)

NAME
CDMS - Climate Data Management System C application programming interface

SYNOPSIS

#include "cdms.h"

long cdDimGetDouble(long dsetid, long dimid, long start, long count, long stride, double modulus, double *values)

long cdNdimIntersect(long dsetid, long varid, const long order[], const double first[], const double last[], const double modulus[], cdIntersectPolicy policy, long start[], long count[], long stride[])

long cdSlabRead(long dsetid, long varid, const long order[], const double first[], const double last[], const double modulus[], cdIntersectPolicy policy, cdType cast, void *values)

DESCRIPTION

These routines implement a read-write interface to data and metadata contained in the Climate Data Management System.

DATATYPES
The CDMS 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 CDMS 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 cdms.h defines an enumeration type cdType, which can have the values cdByte, cdChar, cdShort, cdInt, cdLong, cdFloat, cdDouble, cdLongDouble, or cdCharTime.

FUNCTION DESCRIPTIONS

long cdDimGetDouble(long dsetid, long dimid, long start, long count, long stride, double modulus, double values[])

Retrieves a dimension, as an array of doubles.

dsetid is the dataset ID, and dimid is the dimension ID.

start is the 0-origin index of the first value of the dimension to be retrieved. count values are retrieved, with stride as the increment between successive indices.

If start + count is outside the range of dimension indices, then values are returned wrapped modulo the length of the dimension. In this case, if modulus is a positive value, it is added to the values returned when wraparound occurs.

The dimension values are returned in values. The function returns 1 on success, 0 on failure.

long cdNdimIntersect(long dsetid, long varid, const long order[], const double first[], const double last[], const double modulus[], cdIntersectPolicy policy, long start[], long count[], long stride[])

Maps a generalized hyperslab to indices. dsetid is the dataset ID, and varid is the variable ID.

The region of the hyperslab is specified by the arrays first and last. first is an array of doubles specifying the first value of the interval in coordinate space; last is the array of last values of the interval, for each dimension of the variable. first and last have dimension ordering as specified by the order argument.

The indices corresponding to the hyperslab are returned in arrays start, count, and stride. These arrays can be used to calculate memory requirements, and to read the data via cuvargets.

The remaining arguments are defined as in cdSlabRead.

The function returns 1 on success, 0 on error.

long cdSlabRead(long dsetid, long varid, const long order[], const double first[], const double last[], const double modulus[], cdIntersectPolicy policy, cdType cast, void *values)

Reads a generalized hyperslab of data. dsetid is the dataset ID, and varid is the variable ID.

The region of the hyperslab is specified by the arrays first and last. first is an array of doubles specifying the first value of the interval in coordinate space; last is the array of last values of the interval, for each dimension of the variable. first and last 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, ..., ndims-1>, indicating no transposition.

modulus is an array which specifies how the data is to be wrapped. If the value of modulus[i] is strictly positive, the i-th dimension topology is treated as circular, and the interval wraps around modulo the value of modulus[i]. Otherwise if modulus[i] is 0.0, the dimension topology is assumed to be linear, and the data corresponds to the intersection of the interval [first[i], last[i]] with the dimension in coordinate space. If modulus is NULL, it defaults to <0.0, 0.0, ..., 0.0>, that is, no wraparound is performed. The dimension order of modulus corresponds to that of the order argument.

policy indicates how the interval and dimension are intersected. If policy has the value cdRange, the values in the intersection of the closed interval [first[i], last[i]] are returned. policy may also have the value cdRoundNearest, in which case the first and last values are rounded to the nearest dimension points, which may lie outside the closed interval [first[i], last[i]].

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 1 on success, 0 on error.

SEE ALSO
cdunif(3).

BUGS