MODULES AND PUBLIC INCLUDE FILES

There are five Fortran MODULEs, and three primary (and one additional) public matching pairs of Fortran and C 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.

Each of the Fortran include files is structured so that it conforms both to the "fixed" and "free" Fortran source formats, using the method recommended by the ISO Fortran-Standards committee. Note, however, that CMAQ and SMOKE use a non-Standard "fixed-132" source format that is not compatible with either of these Standard formats; for this reason, there is a script, ioapi/fix_src.csh that can convert these INCLUDE files into the format required of CMAQ and SMOKE. The make fixed_src command creates a directory ioapi/fixed_src/ and uses this script to put the converted INCLUDE-files into it.

As of Novenber, 2004, new Fortran-9x MODULE M3UTILIO is the recommended way to provide 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, UNC, 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 UNC, MCNC, 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

Deprecated for I/O API 3.0 and later (i.e., post-2004): USE M3UTILIO instead.

These include-files 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 AMISS3, 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
M3INT8 ... 64-bit integer (I/O API-3.2 or later only)
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 Conformal Conic 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
ALBGRD3 ...Albers Equal-Area Conic coordinates
LEQGRD3 ...Lambert Equal-Area coordinates
SINUGRD3 ...Sinusoidal Equal-Area coordinates (I/O API-3.1 or 3.2, post-May 5, 2015).
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 fill value
AMISS3  test value: "bad" iff <value> < AMISS3
IMISS3  "bad" or "missing" INTEGER value
CMISS3  "bad" or "missing" CHARACTER string value
LITTLE_ENDIAN=1234, BIG_ENDIAN=4321, PDP_ENDIAN=3412: byte-order tokens for function GET_ENDIAN(), which returns the current-machine byte-order.

Source for PARMS3.EXT

Source for parms3.h

Back to Contents


FDESC3.EXT
fdesc3.h

Deprecated for I/O API 3.0 and later (i.e., post-2004): USE M3UTILIO instead.

These include-files 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

Deprecated for I/O API 3.0 and later (i.e., post-2004): USE M3UTILIO instead.

These include-files contain declarations, INTERFACEs, 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 could 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

Obsolete/unused: TSRIES3 files were never taken intp production usage. Deprecated for I/O API version 3.2 and later.

These include-files contain 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