cddrs(3)

NAME
cddrs - CDMS C DRS wrapper functions for accessing DRS, GrADS (GRIB), and netCDF datafiles.

SYNOPSIS (C ROUTINES)

#include "cddrs.h"

int cw_aslun(int lu, char* dictfil, int lud, char* datfil, int istat)

int cw_cllun(int lu)

int cw_cluvdb(void)

int cw_drstest(int ierr)

int cw_get_fileid(int lu)

int cw_getdat(int lu, void* a, int isize)

int cw_getcdim(int idim, char* source, char* name, char* title, char* units, int* dtype, int reqlen, float* var, int* retlen)

int cw_getedim(int idim, char* dsrc, char* dna, char* dti, char* dun, int* dtype, int* dlen, float* df, float* dl)

int cw_getelemd(int* type, int* bpe)

int cw_getname(char* source, char* name, char* title, char* units, char* date, char* time, char* typed, int* nd)

int cw_getnd(int* nd)

int cw_getrge2(int lu, int idim, double elem1, double elem2, int* ind1, int* ind2, float* dlow, float* dhigh)

int cw_getslab(int lu, int rank, int* order, float* fe, float* le, float* cycle, void* data, int* datadim)

int cw_inqdict(int lu, int oper)

int cw_inqlun(int lu, char* datafile, int* nvar, float* version)

int cw_majority(CwMajority majority)

int cw_set_dimension_option(CwExtensionOption option)

int cw_set_string_option(CwExtensionOption option)

int cw_setdim(int n, char* dna, char* dun, int idim, double df, double dl)

int cw_seterr(int ierrlun, int reportlevel)

int cw_setname(char* source, char* name, char* title, char* units, char* typed)

int cw_setvdim(int n, char* dso, char* dna, char* dti, char* dun, double df, double dl)

DESCRIPTION
These routines provide read-only access to data in DRS, netCDF, and GrADS (GRIB) format. For backward compatibility, the routines are identical to the read and inquiry routines in the DRS library, prefixed with cw_. The routines cw_majority, cw_set_dimension_option, cw_set_string_option, and cw_get_fileid have no DRS counterparts. In general, any return argument may be set to NULL (0), in which case no value is returned. Additionally, the following values are treated as null values for input arguments:

CW_STRING_NULL
    null string
CW_FLOAT_NULL
    null float
CW_NULL_INT
    null integer argument

FUNCTION DESCRIPTIONS

int cw_aslun(int lu, char* dictfil, int lud, char* datfil, int istat)

Open a DRS, netCDF, GrADS, or GRIB file. lu and lud are the FORTRAN logical units to be associated with the dictionary file and data file respectively. For subsequent calls, the dictionary file lu is used to identify the file. dictfil and datfil are the pathnames of the dictionary and data file, respectively. For netCDF files, only the dictionary file lu and dictfil are specified; lud and datfil are ignored. Similarly, for GrADS files, lu is specified, and dictfil is the pathname of the GrADS control file; the lud and datfil parameters are ignored. istat is either IDRS_READ or IDRS_EXTEND. The function returns 0 on success, a non-zero status on failure.

int cw_cllun(int lu)

Close a file. lu is the logical unit of the dictionary file.

int cw_cluvdb(void)

Reset the VDB to null values.

int cw_drstest(int ierr)

Test for a fatal error. The function returns true if the error number ierr is fatal, false otherwise.

int cw_get_fileid(int lu)

Get the cdunif fileid. This allows calls to be made directly to the cdunif interface, on which the cddrs functions are based.

int cw_getdat(int lu, void* var, int isize)

Read data for a variable. lu is the dictionary logical unit. Data is returned in var. isize is size of var in bytes. The name of the variable to read is specified with cw_setname. The range and ordering of the data to be read are specified by one or more calls to cw_setdim and cw_setvdim.

int cw_getcdim(int idim, char* source, char* name, char* title, char* units, int* dtype, int reqlen, float* var, int* retlen)

Get dimension values and name strings for a dimension. idim is the 1-origin dimension number. The function returns the source (comment) string, variable name, long title, and variable units. The dimension type dtype is returned as IDRS_EQUALLY_SPACED or IDRS_VECTOR. (Note: this may be modified via function cw_set_dimension_option.) reqlen is the maximum number of elements to be retrieved. Dimension values are returned in var, provided that reqlen is sufficiently large. retlen is set to the actual number of elements returned.

int cw_getedim(int idim, char* source, char* name, char* title, char* units, int* dtype, int* dlen, float* df, float* dl)

Get dimension limits and name strings for a dimension. idim is the 1-origin dimension number. The function returns the source (comment) string, variable name, long title, and variable units. The dimension type dtype is returned as IDRS_EQUALLY_SPACED or IDRS_VECTOR. (Note: this may be modified via function cw_set_dimension_option.) dlen is the length of the dimension. df and dl are returned as the first and last values, respectively, of dimension idim of the variable just read or inquired.

int cw_getelemd(int* type, int* bpe)

Retrieve the variable datatype description. bpe is the number of bytes per element as defined on the current host. type is returned as one of the following:

    IDRS_ASCII
        ASCII characters
    IDRS_CRAY_R16
        Cray 16-byte floating-point
    IDRS_CRAY_R8
        Cray 8-byte floating-point
    IDRS_I1
        one-byte integer
    IDRS_I2
        two-byte integer
    IDRS_I4
        four-byte integer
    IDRS_I8
        eight-byte integer
    IDRS_IEEE_R16
        IEEE 16-byte floating-point
    IDRS_IEEE_R4
        IEEE four-byte floating-point
    IDRS_IEEE_R8
        IEEE eight-byte floating-point
    IDRS_USER
        user-defined

int cw_getname(char* source, char* name, char* title, char* units, char* date, char* time, char* typed, int* nd)

Get the source, name, title, and units of the variable just read or inquired. date and time are the date and time at which the variable was written. typed is the datatype of the variable, as it will (by default) be retrieved. nd is the number of dimensions of the variable.

int cw_getnd(int* nd)

Get the number of dimensions, nd, of the current variable.

int cw_getrge2(int lu, int idim, double elem1, double elem2, int* ind1, int* ind2, float* dlow, float* dhigh)

Map a range of coordinates to a range of indices. lu is the logical unit for the current variable. idim is the 1-origin dimension number. elem1 and elem2 are the endpoints of the range of coordinates to be mapped. ind1 and ind2 are set to corresponding first and last indices for the specified coordinate range. The actual coordinate range that DRS would retrieve is [dlow,dhigh].

int cw_getslab(int lu, int rank, int* order, float* fe, float* le, float* cycle, void* data, int* datadim)

Read data for a variable, with optional wraparound. lu is the dictionary logical unit. order is an array, of length rank, specifying how the dimensions are to be transposed on data retrieval. Dimension numbers are 1-origin; order[i] specifies the i-th file dimension to be retrieved. If order = [1,2,...,rank], then the data will be read with the same dimension order as in the file. fe is an array, of length rank, of the first coordinate of each dimension range; f[i] corresponds to file dimension order[i]. Similarly, le is the array, of length rank, of coordinates of the last elements of the dimension range, for each dimension. cycle is the array of cycle lengths for each dimension. If cycle[i] is nonzero, the ith (user) dimension is treated as circular, with length cycle[i]. For example, a longitude dimension which is written in the file with range 0.0 to 359.0 can be retrieved with a range fe[i]=-180.0, le[i]=180.0, and cycle[i]=360.0. Note that wraparound and retrieval of duplicate data at the endpoints are handled correctly. Set cycle[i] to 0.0 to specify no wraparound in the i-th (user) dimension. Data is returned in var. datadim is an array of length rank, whose i-th element is the length of the i-th user dimension of var. datadim[i] can be larger than the number of elements actually retrieved into the i-th dimension. This permits a multi-dimensional var array to be statically allocated, if desired.

int cw_inqdict(int lu, int oper)

Inquire a variable. If oper is IDRS_GETFIRSTVAR, the VDB is set for the first variable that matches the naming information specified in the most recent cw_setname call. If oper is IDRS_GETNEXTVAR, the VDB is set for the next matching variable. The function returns 0 on success, IDRS_NOMOREVARS if no matching variable was found, or a non-zero status on failure.

int cw_inqlun(int lu, char* datafile, int* nvar, float* version)

Inquire a file. datafile is the name of the associated datafile (DRS, GrADS, GRIB). nvar is the number of variables in the file. version is the version number of the file format.

int cw_majority(CwMajority majority)

Set the data majority. By default, cddrs follows the FORTRAN majority convention : the first dimension varies most rapidly. Consequently, in C programs, dimension numbers are reversed with respect to the actual dimensions of a multi-dimensional variable. Calling cw_majority with majority CW_C_MAJORITY cause cddrs to follow the C majority convention - the first dimension varies least rapidly. majority is either CW_C_MAJORITY or CW_FORTRAN_MAJORITY (default).

int cw_set_dimension_option(CwExtensionOption option)

Set the dimension option portability flag. option may be CW_STANDARD (the default) or CW_EXTENDED. By default, a call to cw_getcdim or cw_getedim returns a dimension type of IDRS_EQUALLY_SPACED or IDRS_VECTOR. If this function is called with option CW_EXTENDED, the following dimension types will instead be returned: CW_SHARED, indicating that there is a coordinate variable in the file representing the values of this dimension, CW_IMPLICIT_SHARED, indicating that there is no such variable, but the dimension is shared (global) nonetheless, and IDRS_LOCAL, indicating that the dimension is not shared. This model better supports formats such as GrADS, which can have implicitly defined, shared dimensions. The values of such a dimension may be retrieved using cw_getcdim, but NOT using cw_getdat or cw_getslab. The extension option stays in effect until the next call to cw_set_dimension_option, if any, The function returns IDRS_SUCCESS on success, -1 on error.

int cw_set_string_option(CwExtensionOption option)

Set the string option portability flag. option may be CW_STANDARD (the default) or CW_EXTENDED. By default, name arguments have length IDRS_NAMELEN, as defined in drscdf.h. Similarly, source, title, units, date, time, and typed arguments have length IDRS_SOURCELEN, IDRS_TITLELEN, IDRS_UNITSLEN, IDRS_DATELEN, IDRS_TIMELEN, and IDRS_TYPELEN, respectively. If this function is called with option CW_EXTENDED, these function arguments can have length up to CW_MAX_NAME characters, including the null terminator, and memory should be allocated accordingly. This applies to the following arguments: source, name, title, units, date, time, and typed, in functions cw_getcdim, cw_getedim, cw_getname, cw_setdim, cw_setname, and cw_setvdim. The extension option stays in effect until the next call to cw_set_string_option, if any, The function returns IDRS_SUCCESS on success, -1 on error.

int cw_setdim(int n, char* dna, char* dun, int idim, double df, double dl)

Specify the range of values to be read for a dimension. n is the 1-origin dimension number. dna is the (optional) name of the dimension. dun is the (optional) units field. If both dna and dun are set to null (0), then the range is set for the i-th dimension as defined in the file, respective of the data majority. idim is for backward compatibility only, and should be set to 0. df and dl are the first and last values of the range of values to be read.

int cw_seterr(int ierrlun, int reportlevel)

Set the error reporting level. reportlevel may be set to IDRS_NOREPORT to suppress error reporting, or IDRS_WARNING to report errors. ierrlun is provided for backward compatibility only; all errors are written to stderr.

int cw_setname(char* source, char* name, char* title, char* units, char* typed)

Specify the name and (optionally) the other name fields of the variable to be read. name is the name of the variable to be read. source, title, and units may be specified, but must match the corresponding field of the variable if specified. typed is the requested datatype of the variable. An error occurs if the data cannot be returned as the requested type.

int cw_setvdim(int n, char* dso, char* dna, char* dti, char* dun, double df, double dl)

Specify the range of values to be read for a dimension. n is the 1-origin dimension number. dna is the (optional) name of the dimension. dso, dti, and dun are optional source, title, and units fields. If specified, they must match exactly the corresponding variable fields. If dso, dna, dti, and dun, are all set to null (0), then the range is set for the i-th dimension as defined in the file, respective of the data majority. df and dl are the first and last values of the range of values to be read.

PORTING FROM DRS
Since the template of each cddrs call is identical to its DRS counterpart, porting a code with DRS calls to cddrs consists of prefixing all DRS read and inquiry routines with "cw_"; the arguments need not be modified. This can be accomplished most readily, if there are no write routines in the source file, by compiling with the option -DCDCOMPAT. This causes all DRS C routines to be redefined, by the preprocessor, to their cddrs equivalent. If any of the following routines appear within the source file, the above option should not be used: Putdat, Putdic, Putvdim, Setdate, or Setrep.

FILES
$PCMDI/include/cddrs.h
    cddrs include file
$PCMDI/lib/libcdms.a
    CDMS library
$PCMDI/lib/libdrs.a
    DRS library

COMPILATION
The following illustrates the basic compilation and link command:

    acc -I$PCMDI/include -o prog prog.c -L$PCMDI/lib -lcdms -ldrs \
        -L/usr/local/netcdf-2.3.2/libsrc -lnetcdf -lF77 -lc -lm

This illustrates use of the compatibility flag:

    acc -DCDCOMPAT -I$PCMDI/include -o prog prog.c -L$PCMDI/lib \
        -lcdms -ldrs -L/usr/local/netcdf-2.3.2/libsrc -lnetcdf -lF77 -lc -lm

SEE ALSO
cdunif(3), fcddrs(3).

BUGS
C*n datatypes for n greater than 1 are not properly handled. DRS output routines should be incorporated, to make porting easier.