FILES: Variables, Layers, and Time Steps

All files manipulated by the I/O API have multiple variables . Variables are arrays of data values that have additional structure, are referenced by name (character strings of length at most 16), and have units-designations (also (character strings of length at most 16) and text descriptions ((character strings of length at most 80). For storing and retrieving metadata, and for storing ID-tables, indexes, etc. in structured datatypes (those requiring "all-variable" READ3() and WRITE3() operations) such as ID-referenced, vertical profile, and sparse matrix, it is legal for the number of variables to be zero. Variable-names should begin with an (upper or lower case) alphabetic character which may be followed by alphabetic, numeric, or or the underscore character _. Case is significant. (netCDF also permits the "minus" and "period" characters; however, these break the construction of algebraic formulas, etc., in PAVE and other analysis and visualization packages, and should not be used.)

Names, units-designations, and text descriptions are stored in the file-headers and may be accessed via the FDESC data structures after a call to DESC3(). The reverse procedure is used to create new files: store the file's description in the FDESC data structures, and then call OPEN3().

For C programmers: The IOAPI_Cdesc3 fields (gdnam, upnam, execn, fdesc[], updsc[], vname[], units[], and vdesc[] are blank-padded character arrays (padded to a length of NAMLEN3=16 for name fields and MXDLEN3=80 for description variables), not null-terminated C strings. On the other hand, file name and variable name arguments to read3c(), write3c(), interp3c(), and xtract3c() should be null-terminated C strings.
Fortran::C string-conversion routines fstr2cstr(), name2cstr(), cstr2fstr() are very useful for passing character strings in a mixed-language programming situation.

Within a file, all the variables have the same dimensions, horizontal coordinate system and horizontal grid structure, number of layers and vertical grid structure, time step structure, and type of data structure, although they may have different basic data type.

There are three (or four) kinds of basic data type which individual variables may have, as indicated by the following "magic number" parameters defined in PARMS3.EXT , and stored in the VTYPE3D arrays of FDESC3.EXT :

M3INT for (32-bit) integer variables
M3INT8 for (64-bit) integer variables (I/O API-3.2 oir later, only)
M3REAL for real (single precision) variables
M3DBLE for double precision variables

Layers range from 1 to NLAYS3D, where NLAYS3D is the attribute in FDESC3 file descriptions for the number of layers. Vertical coordinate and vertical grid descriptions found in FDESC data structures fully characterize the layering structure of files, at least for the standard set of vertical coordinate types.

There are also three kinds of time-step structure supported, discriminated on the basis of the time step TSTEP3D, and stored according to Models-3 date and time conventions, and found in FDESC file descriptions . These kinds of time step structure are:

Time-independent. The file's time-step attribute is set to zero. Routines which deal with time-independent files ignore the date and time arguments.
Time-stepped. The file has a starting date, a starting time, and a positive time step. Read and write requests must be for some positive integer multiple of the time step from the starting date and time, or they will fail.
Circular-buffer. The file keeps only two "records", the "even" part and the "odd" part (useful, for example, for "restart" files where you're only interested in the last good data in the file). The file's description has a starting date, a starting time, and a negative time step (set to the negative of the actual time step); read and write requests must be for some positive integer multiple of the time step from the starting date and time -- and must be for a time step actually present -- or they will fail.

There are eight types of data structure currently supported by the I/O API. Data structure type is indicated by "magic number" values for FTYPE3D in file descriptions such as those found in FDESC3.EXT. Definitions for these magic numbers are found in PARMS3.EXT . The data types, together with the names of the magic numbers, are:

Previous Section: Calling from C

Next Section: Disk files and "buffered" virtual files

Up: Conventions

To: Models-3/EDSS I/O API: The Help Pages