MODULES AND PUBLIC INCLUDE FILES

There are 2 Fortran MODULEs, and 3 Fortran and 3 C public include files in the I/O API, with the following sorts of content:

Each of the include files has extensive in-line documentation as to the meaning of the structures it defines.

New Fortran-9x MODULE M3UTILIO provides an alternate interface to these INCLUDE> files, as well as explicit interfaces to a large number of additional I/O API public routines, in a way that gets around difficulties caused by the interaction of Fortran-9x USE <module> and Fortran (77/90/95) INCLUDE statements. It also provides a way of ensuring the consistency of user compiled code with library compiled code for "exotic" I/O API versions with modified data-structure-dimensioning parameters.


NOTICE: The EDSS/Models-3 I/O API depends in an essential manner upon the I/O API source code. ANY CHANGES to INCLUDE files are likely to result in very obscure, difficult-to-diagnose bugs caused by an inconsistency between standard libioapi.a object-libraries and whatever code is compiled with the resulting modified INCLUDE-file(s).

By making any changes to any of these INCLUDE files, the user explicitly agrees that in the case any assistance is required of MCNC, BAMS, or of the I/O API author, Carlie J. Coats, Jr., as a result of such changes, The user and/or his project or contract agrees to reimburse MCNC and/or BAMS and/or the I/O API author, Carlie J. Coats, Jr., at a rate triple the normal contract rate for the services required. Back to Contents


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.

Note: Note that preserving the integrity of these dimensioning parameters is crucial to the integrity of executables built using the I/O API library, and therefore the license has a provision that when these values have been modified (as some parties are wont to do), and when as a result, the party involved requests support for problems caused by the changes to these parameters, the party who modified these values agrees to pay triple-time rates for that support. In this environment, where parties may have changed these parameters unbeknownst to the modeler, checking for the integrity of such model-builds is very important.

The public I/O API routine IOPARMS3 is provided as a means for user/model-level code to check the integrity of these dimensioning parameters.

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)
VGWRFEM ...WRF EM dry sigma-P
VGWRFNM ...WRF NMM vertical coordinate
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

Back to Contents


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

Back to Contents


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

Back to Contents


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 Back to Contents


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