PUBLIC INCLUDE FILES

There are 3 Fortran and 3 C public include files in the I/O API, with the following sorts of content Each of these include files has extensive in-line documentation as to the meaning of the structures it defines. These include files can be found in/env/proj/ioapi on the Environmental Programs workstations and in /home/xcc/m3io on sequoia. On some of these systems (notably the Crays and DEC Alphas), it is sufficient to include the following directive as part of the "f77" command to get the Fortran compiler to search for the INCLUDE files in the indicated directory.
-I/env/proj/ioapi (on the workstation cluster), or
-I/home/xcc/m3io (on sequoia)
However, the current Sun and SGI compilers requires that the INCLUDE files be visible to "f77" in the same directory as your Fortran source. For those platforms, it is recommended that you execute the commands below, so that the Fortran compiler will have access to the needed INCLUDE files.
ln -s /env/proj/ioapi/PARMS3.EXT .
ln -s /env/proj/ioapi/FDESC3.EXT .
ln -s /env/proj/ioapi/IODECL3.EXT .


PARMS3.EXT
parms3.h

contain dimensioning parameters (e.g., maximum number of files open at a time) and standard file-type, grid-type, (etc.) "magic number parameter" values for the Models-3 I/O API. There are also the standard values for BADVAL3, IMISS3, and CMISS3 for bad or "missing" reals, integers, and character strings. All of these parameter values are thoroughly described by comments in the PARMS3.EXT source code. The dimensioning constants are:
MXDLEN3 description line length
NAMLEN3 name length (file and variable names, etc.)
MXFILE3 maximum number of open files
MXVARS3 maximum number of variables per file
MXDESC3 maximum number of lines per file description
MXLAYS3 maximum number of layers in a vertical grid
The "magic number parameters" are:
CUSTOM3 file type: user-structured custom
GRDDED3 ...gridded data
BNDARY3 ...boundary-condition data
IDDATA3 ...ID-referenced (e.g., observational) data
PROFIL3 ...rawinsonde vertical profile
GRNEST3 ...nested-grid or multi-grid data
SMATRX3 ...sparse matrix
DCTNRY3 ...file-structure-template dictionary
M3INT basic data type integer
M3REAL ... real
M3DBLE ... double precision
FSREAD3 open file as old read-only
FSRDWR3 ...old read-write
FSNEW3 ...new (read-write)
FSUNKN3 ...unknown (read_write)
FSCREA3 ...create/truncate (read_write)
LATGRD3 horizontal coordinate system type: lat-lon coordinates
LAMGRD3 ...Lambert coordinates
MERGRD3 ...Mercator coordinates
STEGRD3 ...(general tangent) Stereographic coordinates
UTMGRD3 ...UTM (Universal Transverse Mercator) coordinates
POLGRD3 ...(secant) Polar Stereographic coordinates
TRMGRD3 ...general Transverse Mercator coordinates
EQMGRD3 ...general Equatorial Mercator coordinates
VGSGPH3 Vertical coordinate type: hydrostatic sigma-P
VGSGPN3 ...nonhydrostatic sigma-P
VGSIGZ3 ...sigma-Z
VGPRES3 ...pressure (mb)
VGZVAL3 ...Z (m above terrain)
VGHVAL3 ...H (m above sea level)
ALLAYS3 read or write "all layers"
ALLVAR3 "...all variables"
BADVAL3 "bad" or "missing" REAL value
AMISS3 test value: "bad" iff < AMISS3
IMISS3 "bad" or "missing" INTEGER value
CMISS3 "bad" or "missing" CHARACTER STRING value

Source for PARMS3.EXT

Source for parms3.h


FDESC3.EXT
fdesc3.h

contain Fortran data structures (COMMONs) and C typedefs for a Models-3 file description. These files have extensive documentation describing the function of each part of a file description. The data structures they contain are used to pass data between OPEN3() (when in a mode that may involve file-creation), DESC3() , and (for dictionary files only) READ3() and WRITE3() . BDESC3 is used to store the non-character-string data, and CDESC3 is used to store the character-string data (recall that the Fortran 77 standard prohibits character and non-character data in the same common). In particular, these data structures store the following file-attributes:

Source for FDESC3.EXT

Source for fdesc3.h


IODECL3.EXT
iodecl3.h

contain declarations (function prototypes) and usage comments for the Fortran and C bindings respectively, for the Models-3 I/O API. "iodecl3.h" also contains function prototypes for those associated utility and date-and-time-manipulation functions which are callable from C. Actually, IODECL3.EXT should probably be considered a short tutorial on usage of the I/O API in its own right.

Source for IODECL3.EXT

Source for iodecl3.h


ATDSC3.EXT and atdsc3.h

contains Fortran data structures and C typedefs for augmented file descriptions used by I/O API file type TSRIES3 (timeseries), which have multiple named REAL attributes per variable. (Each variable represents a stream-network link). Based upon FDESC33.EXT. Requires PARMS3.EXT for dimensioning. Used to pass data between OPEN3() (when in a mode which may involve file-creation), DESC3(), and their callers, and provides name-based syntax for that purpose.

Should only be used as a name based argument passing mechanism; the user should have local variables to/from which this data structure is copied immediately prior to or immediately after calls which set or use these COMMONs, since their values are subject to change at ny time by the I/O API. Contains

Source for ATDSC3.EXT

Source for atdsc3.h


PARMS3.EXT and parms3.h

FDESC3.EXT and fdesc3.h

IODECL3.EXT and iodecl3.h

ATDSC3.EXT and atdsc3.h

Previous: Data Types Supported

Next: Public I/O routine CHECK3

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