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 .
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
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
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
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
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