cddrs(3)

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

SYNOPSIS (FORTRAN ROUTINES)

#include "drsdef.h"
    #include "fcddrs.h"

    integer function cw_aslun(lu, dictfil, lud, datfil, istat)
        integer lu
        character*1024 dictfil (Unix), character*248 dictfil (Cray)
        integer lud
        character*1024 datfil (Unix), character*248 datfil (Cray)

    integer function cw_cllun(lu)
        integer lu

    integer function cw_cluvdb(void)

    logical function cw_drstest(ierr)
        integer ierr

    integer function cw_getdat(lu, a, isize)
        integer lu
        real a(*)
        integer isize

    integer function cw_getcdim(idim, source, name, title, units, dtype, reqlen, var, retlen)
        integer idim
        character*120 source
        character*16 name
        character*80 title
        character*40 units
        integer dtype
        integer reqlen
        real var(*)
        integer retlen

    integer function cw_getedim(idim, dsrc, dna, dti, dun, dtype, dlen, df, dl)
        integer idim
        character*120 dsrc
        character*16 dna
        character*80 dti
        character*40 dun
        integer dtype
        integer dlen
        real df
        real dl

    integer function cw_getelemd(etype, bpe)
        integer etype
        integer bpe

    integer function cw_getname(source, name, title, units, date, time, typed, nd)
        character*120 source
        character*16 name
        character*80 title
        character*40 units
        character*8 date
        character*8 time
        character*8 typed
        integer nd

    integer function cw_getnd(nd)
        integer nd

    integer function cw_getrge2(lu, idim, elem1, elem2, ind1, ind2, dlow, dhigh)
        integer lu
        integer idim
        real elem1
        real elem2
        integer ind1
        integer ind2
        real dlow
        real dhigh

    integer function cw_getslab(lu, rank, order, fe, le, cycle, data, datadim)
        integer lu
        integer rank
        integer order(rank)
        real fe(rank)
        real le(rank)
        real cycle(rank)
        real data(*)
        real datadim(rank)

    integer function cw_inqdict(lu, oper)
        integer lu
        integer oper

    integer function cw_inqlun(lu, datafile, nvar, version)
        integer lu
        character*1024 datafile (Unix), character*248 (Cray)
        integer nvar
        real version

    integer function cw_majority(majority)
        integer majority

    integer function cw_setdim(n, dna, dun, idim, df, dl)
        integer n
        character*16 dna
        character*40 dun
        integer idim
        real df
        real dl

    integer function cw_seterr(ierrlun, reportlevel)
        integer ierrlun
        integer reportLevel

    integer function cw_setname(source, name, title, units, typed)
        character*120 source
        character*16 name
        character*80 title
        character*40 units
        character*8 typed

    integer function cw_setvdim(n, dso, dna, dti, dun, df, dl)
        integer n
        character*120 dso
        character*16 dna
        character*80 dti
        character*40 dun
        real df
        real 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_. One routine, cw_majority, has no counterpart in DRS. In general, any return argument which is set to NULL (0) will be ignored. 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

integer function cw_aslun(lu, dictfil, lud, datfil, 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.

integer function cw_cllun(lu)

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

integer function cw_cluvdb(void)

Reset the VDB to null values.

logical function cw_drstest(ierr)

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

integer function cw_getdat(lu, var, 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.

integer function cw_getcdim(idim, source, name, title, units, dtype, reqlen, var, 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. 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.

integer function cw_getedim(idim, source, name, title, units, dtype, idim, df, 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. 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.

integer function cw_getelemd(type, 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

integer function cw_getname(source, name, title, units, date, time, typed, 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.

integer function cw_getnd(nd)

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

integer function cw_getrge2(lu, idim, elem1, elem2, ind1, ind2, dlow, 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].

integer function cw_getslab(lu, rank, order, fe, le, cycle, data, 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.

integer function cw_inqdict(lu, 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.

integer function cw_inqlun(lu, datafile, nvar, 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.

integer function cw_majority(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).

integer function cw_setdim(n, dna, dun, idim, df, dl)

Specify the range of values to be read for a dimension. n is the 1-origin dimension number. dna is the name of the dimension. dun is the (optional) units field. 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.

integer function cw_seterr(ierrlun, 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.

integer function cw_setname(source, name, title, units, 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.

integer function cw_setvdim(n, dso, dna, dti, dun, df, dl)

Specify the range of values to be read for a dimension. n is the 1-origin dimension number. dna is the 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. 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 including "drsdef.h" and "fcddrs.h" in every routine that calls a cddrs function, and compiling with the option -DCDCOMPAT. This causes all DRS FORTRAN 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/fcddrs.h
    FORTRAN 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:

    f77 -w -I$PCMDI/include -o prog prog.F -L$PCMDI/lib -lcdms -ldrs \
    	-L/usr/local/netcdf-2.3.2/libsrc -lnetcdf

This illustrates use of the compatibility flag:

    f77 -w -I$PCMDI/include -DCDCOMPAT -o prog prog.F -L$PCMDI/lib -lcdms -ldrs \
    	-L/usr/local/netcdf-2.3.2/libsrc -lnetcdf

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

BUGS
C*n datatypes for n greater than 1 are not properly handled. Output routines should be incorporated for ease of porting.