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
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
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:
- data type
- FTYPE3D data structure type for the
variables in this file
- variables, their units and
descriptions
- NVARS3D number of variables
- VNAME3D list of names for variables
- UNITS3D list of units for variables
- VDESC3D list of text-descriptions for
variables
- VTYPE3D list of
basic data types
for variables
- coordinate and grid description
- GDNAM3D grid name
- GDTYP3D horizontal coordinate system
type, using token values
LATGRD3, etc., defined in
PARMS3.EXT, above
- P_ALP3D first map projection descriptive
parameter
- P_BET3D second map projection descriptive
parameter
- P_GAM3D third map projection descriptive
parameter
- XCENT3D longitude for coordinate system
origin (where X = 0)
- YCENT3D latitude for coordinate system
origin (where Y = 0)
- XORIG3D X-coordinate for lower-left
(southwest) corner of the
grid
- YORIG3D Y-coordinate for lower-left corner of
the grid
- XCELL3D X-coordinate grid cell size
- YCELL3D Y-coordinate grid cell size
- NCOLS3D number of horizontal grid columns
- NROWS3D number of horizontal grid rows
- NLAYS3D number of vertical grid layers
- NTHIK3D boundary perimeter thickness (cells)
- VGTYP3D vertical coordinate type
- VGTOP3D model-top, for sigma coord types
- VGLVS3D array of vertical coordinate
grid level values
- time step structure
- SDATE3D file start date YYYYDDD
- STIME3D file start time HHMMSS
- TSTEP3D file time step HHMMSS
- MXREC3D maximum time step record number
(1,2,...)
- file description and history
- FDESC3D (text) file description
- CDATE3D file-creation date
- CTIME3D file-creation time
- WDATE3D last-update date
- WTIME3D last-update time
- UPNAM3D name of last program writing to
this file
- EXECN3D value of environment variable
EXECUTION_ID
- UPDSC3D (text) update description
Source for FDESC3.EXT
Source for fdesc3.h
Back to Contents
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
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
- NATTS3D( MXVARS3 ):
number of attributes for the indicated variable
- ATNAM3D( MXATTS3, MXVARS3 ):
attribute-names for the indicated attribute of the
indicated variable
- :
values of the indicated attribute of the
indicated variable
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