MODULES AND PUBLIC INCLUDE FILES

There are six 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:

• MODULE M3UTILIO: dimensions, constants, declarations, interface blocks. Includes all the public Fortran include-files (below), and is the preferred way of accessing them from Fortran program code.

• MODULE MODATTS3: parameters and routines for saving metadata for CF compliance, geospatial transforms, and CMAQ and SMOKE runs.

• MODULE MODGCTP: PARAMETERs and routines for geospatial transforms and interpolation.

• MODULE MODNCFIO: PARAMETERs and function declarations for netCDF and for PnetCDF, if PnetCDF/MPI distributed-I/O is enabled.
  Can be used to replace INCLUDE-files NETCDF.EXT, netcdf.inc, and/or pnetcdf.inc.
  Also includes "raw netCDF" get-description routine DESCNCVAR() and read/write-a-variable generic routines READNCVAR() and WRITENCVAR()

• MODULE MODWRFIO: routines for opening or creating, reading, and writing WRF netCDF files.

• MODULE MODMPASFIO: parameters and state variables for MPAS unstructured grid specification; routines for opening, reading, and writing MPAS-format-netCDF files; MPAS-grid utility routines.

• PARMS3.EXT and parms3.h: dimensions and constants
• FDESC3.EXT and fdesc3.h: file description data structures
• IODECL3.EXT and iodecl3.h: function declarations

• ATDSC3.EXT and atdsc3.h: Extra attributes for TSERIES3 files

• NOTE: STATE3.EXT and STATE3V.EXT are private include-files, for internal I/OP API use only.
  Not to be used for model or other application codes.

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.
It is strongly suggested that you USE this MODULE, rather than including the INCLUDE-files directly.

---

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:

• data type
  • FTYPE3D data structure type for the variables in this file
• variables, their units and descriptions
  • NVARS3D number of variables
  • VNAME3D(MXVARS3) array of names for variables
  • UNITS3D(MXVARS3) array of units for variables
  • VDESC3D(MXVARS3) array of text-descriptions for variables
  • VTYPE3D(MXVARS3) array 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(MXLAYS3) 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(MXDESC3) (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

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

• NATTS3D( MXVARS3 ): number of attributes for the indicated variable
• ATNAM3D( MXATTS3, MXVARS3 ): attribute-names for the indicated attribute of the indicated variable
• FATTS3D: values of the indicated attribute of the indicated variable

Source for ATDSC3.EXT

Source for atdsc3.h Back to Contents

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