Fortran-90 MODULE MODATTS3

New for I/O API-3.2!! Developed from (and extends) I/O API-3.1 MODULE MATXATTS.

Summary

Fortran-90 style MODULE MODATTS3 uses the I/O API "extra-attributes" interface to provide CF-compliant CF-convention geospatial metadata, and CMAQ-standard, and SMOKE-standard metadata for newly-created I/O API files and input-grid and output-grid metadata for I/O API matrix-files, in terms of Models-3 I/O API map projection and grid description conventions.

Note that adding metadata to a file to which data have already been written may entail substantial overhead (both of time and disk-space): the "system" will have to make a new copy of the file with both the new metadata and the existing data, and then rename it behind the scenes.

The following m3tools programs examine their input files to see whether CMAQ metadata is present; if so they examine environment variable COPY_META (default TRUE) to determine whether or not to copy that metadata to their output file(s):

m3combo
m3cple
m3interp
m3tproc
m3tshift
m3wndw
m3xtract

USAGE of MODULE MODATTS3

Matrix Attributes for geospatial-transform matrices
Geospatial-transform metadata gives the grid description for both the input and the output map projection and grid for a matrix:
GDTYP, P_ALP, P_BET, P_GAM, XCENT, YCENT, XORIG, YORIG, XCELL, YCELL, NCOLS, NROWS,
This module contains generic routines for setting, retrieving, and checking input-grid, output-grid, or both input- and output-grid metadata for files used to store geospatial transform matrices:
INITMTXATT()
stores input and/or output grid description to internal state variables.
SETMTXATT()
stores input and/or output grid description to an M3IO file-header.
GETMTXATT()
retrieves input and/or output grid description (as stored by SETMTXATT()) from an M3IO file-header.
CHKMTXATT()
compares input and/or output grid description (as stored by SETMTXATT()) from an M3IO file-header with grid description(s) supplied as arguments.

CF-Convention Metadata
See http://cfconventions.org/.
CF metadata is used by the global climate community as well as by a number of third-party applications.

Turned on by setenv IOAPI_CFMETA YES [default NO]. If turned on, all newly-created files will be given this metadata in their file headers and in CF specified auxilliary variables. (These last should not have been necessary if the CF authors had actually known what they were doing with netCDF; it is the reason for the restrictions on SETCF() below.).

Also, LOGICAL FUNCTION SETCF(FNAME) creates CF metadata in the file with logical name FNAME, provided it is opened for output.
This routine needs to be called before any data is written to the file.

"Standard" CMAQ Metadata
Turned on/off by setenv IOAPI_CMAQMETA... with the following values:
NONE: turned off [default]

ENV: get metadata from environment variables. These include both the standard CMAQ environment variables, as well as the following new environment variables (whose values are described below):
PROJECT, CASE, EPISODE, SPONSOR, CMAQVERS, MCIPVERS, EMISVERS, METVERS, CMAQCFG, MCIPCFG, EMISCFG, ICBCCFG, METCFG
Note that the values of these in setenv statements need to be quoted, in order to preserve blanks and other white-space.

path-name: get metadata from the indicated structured ASCII file. This file should consist of lines of the form
<name> = <value>
for the following set of names (also described below):
PROJECT, CASE, EPISODE, SPONSOR, CMAQVERS, MCIPVERS, EMISVERS, METVERS, CMAQCFG, MCIPCFG, EMISCFG, ICBCCFG, METCFG,SYNC_TOP, MAXSYNC, MINSYNC, WB_DUST, ERODE_AGLAND, WBDUST_BELD, LTNG_NO, KZMIN, ILDEPV, MOSAIC, ABFLUX, HGBIDI, SFC_HONO, BIOGEMIS, PT3DEMIS, CLD_DIAG, AERDIAG, PHOTDIAG, SSEMDIAG, DUSTEM_DIAG, LTNGDIAG, B3GTS_DIAG, PT3DDIAG, PT3DFRAC
This module contains definitions for CMAQ metadata-objects, and generic routines for setting, retrieving, and logging such metadata:
INITCMAQ()
stores metadata into internal state variables, and turns on CMAQ-metadata output for newly created files. Can be called automatically (as above) or manually, optionally with user specified metadata-object.
ISCMAQ()
Checks whether an M3IO file header contains CMAQ metadata.
GETCMAQ()
Retrieves CMAQ metadata from an M3IO file-header, and optionally places it in a user supplied CMAQ-metadata object.
SETCMAQ()
Stores CMAQ metadata to an M3IO file-header, optionally from a user supplied CMAQ-metadata object.
LOGCMAQ()
Writes structured ASCII IOAPI_CFMETA-format metadata to either program-log or to a user specified output file, optionally from a user supplied CMAQ-metadata object.

"Unstructured text-file" Metadata
Turned on/off by either a call to INITMTEXT() with the relevant text-data content, or by setenv IOAPI_TEXTMETA... with the following values:
NONE: turned off [default]

path-name: get metadata from the indicated structured ASCII file. This file should consist of lines of length at most MXDLEN3=80 characters.

If active, the resulting text metadata can be found in the following MODULE-variables in MODULE MODATTS3: 
              LOGICAL,                   PUBLIC, PROTECTED, SAVE :: TEXTMETA          !!  text-file metadata active?
              INTEGER,                   PUBLIC, PROTECTED, SAVE :: TEXT_MLINES       !!  number of lines in TEXT_MDATA( :,: )
              CHARACTER*80, ALLOCATABLE, PUBLIC, PROTECTED, SAVE :: TEXT_MDATA( : )   !!  (TEXT_MLINES)
For newly created files, the data will be stored in global attribute TEXT_MDATA; if you wish to look at this metadata for an "old" file from within a program, use routine INQATT3() to find the size of the metadata, ALLOCATE a buffer for it, and then read it with RDATTC() and process it as desired. (You could use WRATTC() to fake the operation of all this, if you wish :-) )

This module contains definitions for routines for initializing and setting such metadata:

INITMTEXT()
reads metadata from the file into internal state variable TEXT_MDATA Can be called automatically (as above) or manually.
SETMTEXT()
Stores text metadata from state variable TEXT_MDATA to an M3IO file-header.
ENDMTEXT()
Turns text metadata off and deallocates TEXT_MDATA
NOTE that the netCDF get-text-attribute routines do not check string-sizes nor pad with blanks the way the Fortran standard suggests they should.

NOTE ALSO that the standard UNIX/Linux utility fold can be used to create 80-column text files from text-files with longer line-lengths.

"Standard" SMOKE Metadata
Not yet implemented.

Definitions and Declarations in MODULE MODATTS3

LOGICAL, PUBLIC, PROTECTED :: MATXMETA
TRUE if and only if matrix-metadata is turned on, and available in the module

LOGICAL, PUBLIC, PROTECTED :: CFMETA
TRUE if and only if CF-metadata is turned on, and available in the module

LOGICAL, PUBLIC, PROTECTED :: CMAQMETA
TRUE if and only if CMAQ-metadata is turned on, and available in the module

LOGICAL, PUBLIC, PROTECTED :: TEXTMETA
TRUE if and only if ASCII text-file metadata is turned on, and available in the module.

LOGICAL, PUBLIC, PROTECTED :: SMOKEMETA
TRUE if and only if SMOKE-metadata is turned on, and available in the module
SMOKE-metadata is not yet implemented, and may never be ;-(

 
TYPE CMETA_T
Derived data type for standard CMAQ metadata objects. See this section of the CMAQ Wiki for more information
The fields are the following:
INTEGER :: VERSION3
Version-number for the CMAQ-metadata data dictionary
CHARACTER*32 :: PROJECT
Current modeling-project name
CHARACTER*32 :: CASE
Current modeling-case name
CHARACTER*32 :: EPISODE
Current modeling-episode name
CHARACTER*32 :: SPONSOR
Current modeling-project sponsor's name
CHARACTER*32 :: CMAQVERS
CMAQ model version
CHARACTER*32 :: MCIPVERS
MCIP model version
CHARACTER*32 :: EMISVERS
Current emissions model name and version
CHARACTER*256 :: METVERS
Current meteorology-model name and version
CHARACTER*256 :: CMAQCFG
CMAQ configuration (as text)
CHARACTER*256 :: MCIPCFG
MCIP configuration (as text)
CHARACTER*256 :: EMISCFG
Emissions-model configuration (as text)
CHARACTER*256 :: ICBCCFG
IC/BC configuration (as text)
CHARACTER*256 :: METCFG
Meteorology-model configuration (as text)
CHARACTER*512 :: LTNGNO
"inline" or path for lightning file LTNG_NO, or ...
CHARACTER*512 :: OCEAN
Path for file OCEAN_1
CHARACTER*512 :: EMIS
Path for file EMIS_1
CHARACTER*512 :: GCBDY
Path for file BNDY_GASC_1
CHARACTER*512 :: AEBDY
Path for file BNDY_AERO_1
CHARACTER*512 :: NRBDY
Path for file BNDY_NONR_1
CHARACTER*512 ::TRBDY
Path for file BNDY_TRAC_1
CHARACTER*512 ::GCINIT
Path for file INIT_GASC_1
CHARACTER*512 :: AEINIT
Path for file INIT_AERO_1
CHARACTER*512 ::NRINIT
Path for file INIT_NONR_1
CHARACTER*512 :: TRINIT
Path for file INIT_TRAC_1
CHARACTER*512 ::GCNML
Path for file gc_matrix_nml
CHARACTER*512 :: AENML
Path for file ae_matrix_nml
CHARACTER*512 :: NRNML
Path for file nr_matrix_nml
CHARACTER*512 :: TRNML
Path for file tr_matrix_nml
CHARACTER*512 :: GRDCRO2
Path for file GRID_CRO_2D
CHARACTER*512 :: GRDDOT2
Path for file GRID_DOT_2D
CHARACTER*512 :: METCRO2
Path for file MET_CRO_2D
CHARACTER*512 :: METCRO3
Path for file MET_CRO_3D
CHARACTER*512 :: METDOT3
Path for file MET_DOT_3D
CHARACTER*512 :: METBDY3
Path for file MET_BDY_3D
CHARACTER*512 :: XJDATA
Path for file XJ_DATA
CHARACTER*512 :: GSPRO
Path for file GSPRO
CHARACTER*512 :: B3GRD
Path for file B3GRD
CHARACTER*512 :: SOILINP
Path for file SOILINP
CHARACTER*512 :: CSQYDATA
Path for file CSQY_DATA
REAL :: SYNC_TOP
Value of CMAQ environment variable SIGMA_SYNC_TOP:
top sigma level thru which sync step determined
INTEGER :: MAXSYNC
Value of CMAQ environment variable CTM_MAXSYNC:
max sync time step (sec)
INTEGER :: MINSYNC
Value of CMAQ environment variable CTM_MINSYNC:
min sync time step (sec)
INTEGER :: EMISDATE
Value of CMAQ environment variable EMISDATE:
(non-standard-format) Gregorian date for emissions inputs (YYYYMMDD)
INTEGER :: EMISDATE
Value of CMAQ environment variable EMISDATE:
Date for layer-fraction inputs (YYYYDDD)
CHARACTER*8 :: WBDUST_BELD
Value of CMAQ environment variable CTM_WBDUST_BELD:
Flag " landuse database for identifying dust source regions [ default: BELD3 ]"

For the following, environment values should be "T" or "F", Internally, these values are stored accordng to C conventions:
1 represents LOGICAL TRUE
0 represents LOGICAL FALSE
IMISS3=-9999 represents "Missing"
INTEGER :: CTM_CKSUM
Value of CMAQ environment variable CTM_CKSUM:
Flag " Do CKSUM() every time step?"
INTEGER :: WB_DUST
Value of CMAQ environment variable CTM_WB_DUST:
Flag " use in-line wind-borne dust computation?"
INTEGER :: ERODE_AGLAND
Value of CMAQ environment variable CTM_ERODE_AGLAND:
Flag " use in-line wind-borne dust computation?"
INTEGER :: LTNGPARAM
Value of CMAQ environment variable CTM_LTNGPARAM:
Flag " in-line lightning NOx computation?"
INTEGER :: CTM_WVEL
Value of CMAQ environment variable CTM_WVEL:
Flag " output the CCTM-calculated vertical velocities?"
INTEGER :: KZMIN
Value of CMAQ environment variable KZMIN:
Flag " use Min Kz option in edyintb?"
INTEGER :: ILDEPV
Value of CMAQ environment variable CTM_ILDEPV:
Flag " Is in-line deposition-velocity calculation active?"
INTEGER :: MOSAIC
Value of CMAQ environment variable CTM_MOSAIC:
Flag " use landuse specific deposition velocities?"
INTEGER :: ABFLUX
Value of CMAQ environment variable CTM_ABFLUX:
Flag " Use Ammonia bi-directional flux for in-line deposition velocities?"
INTEGER :: HGBIDI
Value of CMAQ environment variable CTM_HGBIDI:
Flag " use Mercury bi-directional flux for in-line deposition velocities?"
INTEGER :: SFC_HONO
Value of CMAQ environment variable CTM_SFC_HONO:
Flag " Use Surface HONO interaction in deposition velocities?"
INTEGER :: BIOGEMIS
Value of CMAQ environment variable CTM_BIOGEMIS:
Flag " Are in-line biogenic emissions active?"
INTEGER :: PT3DEMIS
Value of CMAQ environment variable CTM_PT3DEMIS:
Flag " Is in-line plume rise active?"
INTEGER :: CLD_DIAG
Value of CMAQ environment variable CLD_DIAG:
Flag " write cloud diagnostic file?"
INTEGER :: AERDIAG
Value of CMAQ environment variable CTM_AERDIAG:
Flag " write aerosol diagnostic file?"
INTEGER :: PHOTDIAG
Value of CMAQ environment variable CTM_PHOTDIAG:
Flag " write photolysis diagnostic file?"
INTEGER :: SSEMDIAG
Value of CMAQ environment variable CTM_SSEMDIAG:
Flag " write sea-salt emissions diagnostic file?"
INTEGER :: DUSTEM_DIAG
Value of CMAQ environment variable CTM_DUSTEM_DIAG:
Flag " write windblown dust emissions diagnostic file?"
INTEGER :: LTNGDIAG
Value of CMAQ environment variable LTNGDIAG:
Flag " write lightning diagnostic file?"
INTEGER :: B3GTS_DIAG
Value of CMAQ environment variable B3GTS_DIAG:
Flag " write beis mass emissions diagnostic file?"
INTEGER :: PT3DDIAG
Value of CMAQ environment variable PT3DDIAG:
Flag " write 3d point source emissions diagnostic file?"
INTEGER :: PT3DFRAC
Value of CMAQ environment variable PT3DFRAC:
Flag " write layer fractions diagnostic?"

TYPE SMETA_T
Derived data type for standard SMOKE metadata objects, if that ever happens (currently, only a dummy implementation).
The fields are the following:
INTEGER :: VERSION
Version-number for the SMOKE-metadata data dictionary

TYPE( CMETA_T ), PUBLIC, PROTECTED :: CMAQ_MDATA
Module state-object for CMAQ metadata. If CMAQMETA, holds standard CMAQ metadata.

INTEGER, PUBLIC, PROTECTED :: TEXT_MLINES
Number of lines of ASCII text metadata. Negative if ASCII text-file metadata not active

CHARACTER*80, PUBLIC, PROTECTED :: TEXT_MDATA( TEXT_MLINES )
Structured-ASCII file metadata.

 
TYPE( SMETA_T ), PUBLIC, PROTECTED :: SMOKE_MDATA
Module state-object for SMOKE metadata. If SMOKEMETA, holds standard SMOKE metadata.

 
INTEGER, PARAMETER :: INGRD3
Token to use in matrix-attribute calls to indicate that the grid whose metadata is being accessed is an input grid for the matrix.

INTEGER, PARAMETER :: OUTGRD3
Token to use in matrix-attribute calls to indicate that the grid whose metadata is being accessed is an output grid for the matrix.

 
GETMTXATT()
get input or output grid description attributes for matrix-files and return as arguments:
Generic with forms for matrix-input-only, matrix-output-only, matrix-input-and-output metadata

INITMTXATT()
set state-variables for input and output grid description attributes for matrix-file.

SETMTXATT()
set or check input and output grid description attributes from arguments for matrix-files: if file is NEW, set the attributes; else check them. Retains these attributes in PRIVATE state-variables in the module.:
Generic with forms for matrix-input-only, matrix-output-only, matrix-input-and-output metadata

CHKMTXATT()
check input or output grid description attributes for matrix-files against attributes from the argument list. Return .TRUE. if they match, .FALSE. otherwise.:
Generic with forms for matrix-input-only, matrix-output-only, matrix-input-and-output metadata

ENDMTXATT()
turn off input and output grid description attributes from INITMTXATT() or SETMTXATT()

 
INITCF()
turns on CF-metadata for all new files created

SETCF()
writes CF-metadata for a specific file.

ENDCF()
turns off writing CF metadata for new files created subsequently.

 
INITCMAQ()
turns on CMAQ-metadata for all new files created

ISCMAQ()
Checks whether CMAQ-metadata exists in a specified file

GETCMAQ()
reads CMAQ-metadata from a specific file.

LOGCMAQ()
print human readable CMAQ-metadata.

SETCMAQ()
writes CMAQ-metadata for a specific file.

ENDCMAQ()
turns off writing CMAQ metadata for new files created subsequently.

 
INITMTEXT()
turns on text-file metadata for all new files created

SETMTEXT()
writes text-file metadatametadata for a specific file.

ENDMTEXT()
turns off writing text-file metadatametadata for new files created subsequently.

 
INITSMOKE()
turns on SMOKE-metadata for all new files created

GETSMOKE()
reads SMOKE-metadata from a specific file.

SETSMOKE()
writes SMOKE-metadata for a specific file.

ENDSMOKE()
turns off writing SMOKE metadata for new files created subsequently.

INITMTXATT

    SUBROUTINE  INITMTXATT(                                             &
            GDNAM1, GDTYP1, P_ALP1, P_BET1, P_GAM1, XCENT1, YCENT1,     &
                    XORIG1, YORIG1, XCELL1, YCELL1, NCOLS1, NROWS1,     &
            GDNAM2, GDTYP2, P_ALP2, P_BET2, P_GAM2, XCENT2, YCENT2,     &
                    XORIG2, YORIG2, XCELL2, YCELL2, NCOLS2, NROWS2 )

        CHARACTER( LEN=* ), INTENT( IN ) :: GDNAM1, GDNAM2
        INTEGER           , INTENT( IN ) :: GDTYP1, GDTYP2
        REAL*8            , INTENT( IN ) :: P_ALP1, P_ALP2
        REAL*8            , INTENT( IN ) :: P_BET1, P_BET2
        REAL*8            , INTENT( IN ) :: P_GAM1, P_GAM2
        REAL*8            , INTENT( IN ) :: XCENT1, XCENT2
        REAL*8            , INTENT( IN ) :: YCENT1, YCENT2
        REAL*8            , INTENT( IN ) :: XORIG1, XORIG2
        REAL*8            , INTENT( IN ) :: YORIG1, YORIG2
        REAL*8            , INTENT( IN ) :: XCELL1, XCELL2
        REAL*8            , INTENT( IN ) :: YCELL1, YCELL2
        INTEGER           , INTENT( IN ) :: NCOLS1, NCOLS2
        INTEGER           , INTENT( IN ) :: NROWS1, NROWS2
The first set of arguments GDNAM1 ... NROWS1 are for the matrix-input grid; the last set of arguments GDNAM2 ... NROWS2 for the matrix-output grid.

Back to Contents

GETMTXATT

    GENERIC INTERFACE:
    LOGICAL FUNCTION  GETMTXATT( FNAME, IMODE, GDNAM,                       &
                                 GDTYP, P_ALP, P_BET, P_GAM, XCENT, YCENT,  &
                                 XORIG, YORIG, XCELL, YCELL, NCOLS, NROWS )

        CHARACTER( LEN=* ), INTENT(  IN ):: FNAME  !! logical file name
        INTEGER           , INTENT(  IN ):: IMODE  !! INGRD3 or OUTGRD3
        CHARACTER( LEN=* ), INTENT( OUT ):: GDNAM  !! grid name
        INTEGER           , INTENT( OUT ):: GDTYP  !! map projection type
        REAL*8            , INTENT( OUT ):: P_ALP  !! map projection parameters...
        REAL*8            , INTENT( OUT ):: P_BET  !!  "
        REAL*8            , INTENT( OUT ):: P_GAM  !!  "
        REAL*8            , INTENT( OUT ):: XCENT  !!  "
        REAL*8            , INTENT( OUT ):: YCENT  !!  "
        REAL*8            , INTENT( OUT ):: XORIG  !! Grid origin
        REAL*8            , INTENT( OUT ):: YORIG  !!  "
        REAL*8            , INTENT( OUT ):: XCELL  !! Grid cell-size
        REAL*8            , INTENT( OUT ):: YCELL  !!  "
        INTEGER           , INTENT( OUT ):: NCOLS  !! Grid dimension
        INTEGER           , INTENT( OUT ):: NROWS  !!  "

    LOGICAL FUNCTION  GETMTXATT( FNAME,                                 &
            GDNAM1, GDTYP1, P_ALP1, P_BET1, P_GAM1, XCENT1, YCENT1,     &
                    XORIG1, YORIG1, XCELL1, YCELL1, NCOLS1, NROWS1,     &
            GDNAM2, GDTYP2, P_ALP2, P_BET2, P_GAM2, XCENT2, YCENT2,     &
                    XORIG2, YORIG2, XCELL2, YCELL2, NCOLS2, NROWS2 )

        CHARACTER( LEN=* ), INTENT(IN   ) :: FNAME
        CHARACTER( LEN=* ), INTENT(  OUT) :: GDNAM1, GDNAM2
        INTEGER           , INTENT(  OUT) :: GDTYP1, GDTYP2
        REAL*8            , INTENT(  OUT) :: P_ALP1, P_ALP2
        REAL*8            , INTENT(  OUT) :: P_BET1, P_BET2
        REAL*8            , INTENT(  OUT) :: P_GAM1, P_GAM2
        REAL*8            , INTENT(  OUT) :: XCENT1, XCENT2
        REAL*8            , INTENT(  OUT) :: YCENT1, YCENT2
        REAL*8            , INTENT(  OUT) :: XORIG1, XORIG2
        REAL*8            , INTENT(  OUT) :: YORIG1, YORIG2
        REAL*8            , INTENT(  OUT) :: XCELL1, XCELL2
        REAL*8            , INTENT(  OUT) :: YCELL1, YCELL2
        INTEGER           , INTENT(  OUT) :: NCOLS1, NCOLS2
        INTEGER           , INTENT(  OUT) :: NROWS1, NROWS2
GDNAM1 ... NROWS1 are for the matrix-input grid; GDNAM2 ... NROWS2 for the matrix-output grid.

Back to Contents

SETMTXATT

    GENERIC INTERFACE:
    LOGICAL FUNCTION  SETMTXATT( FNAME, IMODE, GDNAM,                       &
                                 GDTYP, P_ALP, P_BET, P_GAM, XCENT, YCENT,  &
                                 XORIG, YORIG, XCELL, YCELL, NCOLS, NROWS )

        CHARACTER( LEN=* ), INTENT( IN ):: FNAME  !! logical file name
        INTEGER           , INTENT( IN ):: IMODE  !! INGRD3 or OUTGRD3
        CHARACTER( LEN=* ), INTENT( IN ):: GDNAM  !! grid name
        INTEGER           , INTENT( IN ):: GDTYP  !! map projection type
        REAL*8            , INTENT( IN ):: P_ALP  !! map projection parameters...
        REAL*8            , INTENT( IN ):: P_BET  !!  "
        REAL*8            , INTENT( IN ):: P_GAM  !!  "
        REAL*8            , INTENT( IN ):: XCENT  !!  "
        REAL*8            , INTENT( IN ):: YCENT  !!  "
        REAL*8            , INTENT( IN ):: XORIG  !! Grid origin
        REAL*8            , INTENT( IN ):: YORIG  !!  "
        REAL*8            , INTENT( IN ):: XCELL  !! Grid cell-size
        REAL*8            , INTENT( IN ):: YCELL  !!  "
        INTEGER           , INTENT( IN ):: NCOLS  !! Grid dimension
        INTEGER           , INTENT( IN ):: NROWS  !!  "

    LOGICAL FUNCTION  SETMTXATT( FNAME,                                 &
            GDNAM1, GDTYP1, P_ALP1, P_BET1, P_GAM1, XCENT1, YCENT1,     &
                    XORIG1, YORIG1, XCELL1, YCELL1, NCOLS1, NROWS1,     &
            GDNAM2, GDTYP2, P_ALP2, P_BET2, P_GAM2, XCENT2, YCENT2,     &
                    XORIG2, YORIG2, XCELL2, YCELL2, NCOLS2, NROWS2 )

        CHARACTER( LEN=* ), INTENT( IN ) :: FNAME
        CHARACTER( LEN=* ), INTENT( IN ) :: GDNAM1, GDNAM2
        INTEGER           , INTENT( IN ) :: GDTYP1, GDTYP2
        REAL*8            , INTENT( IN ) :: P_ALP1, P_ALP2
        REAL*8            , INTENT( IN ) :: P_BET1, P_BET2
        REAL*8            , INTENT( IN ) :: P_GAM1, P_GAM2
        REAL*8            , INTENT( IN ) :: XCENT1, XCENT2
        REAL*8            , INTENT( IN ) :: YCENT1, YCENT2
        REAL*8            , INTENT( IN ) :: XORIG1, XORIG2
        REAL*8            , INTENT( IN ) :: YORIG1, YORIG2
        REAL*8            , INTENT( IN ) :: XCELL1, XCELL2
        REAL*8            , INTENT( IN ) :: YCELL1, YCELL2
        INTEGER           , INTENT( IN ) :: NCOLS1, NCOLS2
        INTEGER           , INTENT( IN ) :: NROWS1, NROWS2

    LOGICAL FUNCTION  SETMTXATT3( FNAME )

        CHARACTER( LEN=* ), INTENT( IN ) :: FNAME
GDNAM1 ... NROWS1 are for the matrix-input grid; GDNAM2 ... NROWS2 for the matrix-output grid.

Back to Contents

CHKMTXATT

    GENERIC INTERFACE:
    LOGICAL FUNCTION  CHKMTXATT( FNAME, IMODE, GDNAM,                          &
                                 GDTYP, P_ALP, P_BET, P_GAM, XCENT, YCENT,     &
                                 XORIG, YORIG, XCELL, YCELL, NCOLS, NROWS )

        CHARACTER( LEN=* ), INTENT( IN ):: FNAME  !! logical file name
        INTEGER           , INTENT( IN ):: IMODE  !! INGRD3 or OUTGRD3
        CHARACTER( LEN=* ), INTENT( IN ):: GDNAM  !! grid name
        INTEGER           , INTENT( IN ):: GDTYP  !! map projection type
        REAL*8            , INTENT( IN ):: P_ALP  !! map projection parameters...
        REAL*8            , INTENT( IN ):: P_BET  !!  "
        REAL*8            , INTENT( IN ):: P_GAM  !!  "
        REAL*8            , INTENT( IN ):: XCENT  !!  "
        REAL*8            , INTENT( IN ):: YCENT  !!  "
        REAL*8            , INTENT( IN ):: XORIG  !! Grid origin
        REAL*8            , INTENT( IN ):: YORIG  !!  "
        REAL*8            , INTENT( IN ):: XCELL  !! Grid cell-size
        REAL*8            , INTENT( IN ):: YCELL  !!  "
        INTEGER           , INTENT( IN ):: NCOLS  !! Grid dimension
        INTEGER           , INTENT( IN ):: NROWS  !!  "

    LOGICAL FUNCTION  CHKMTXATT( FNAME,                             &
           GDNAM1, GDTYP1, P_ALP1, P_BET1, P_GAM1, XCENT1, YCENT1,  &
                   XORIG1, YORIG1, XCELL1, YCELL1, NCOLS1, NROWS1,  &
           GDNAM2, GDTYP2, P_ALP2, P_BET2, P_GAM2, XCENT2, YCENT2,  &
                   XORIG2, YORIG2, XCELL2, YCELL2, NCOLS2, NROWS2 )

        CHARACTER( LEN=* ), INTENT(IN   ) :: FNAME
        CHARACTER( LEN=* ), INTENT(IN   ) :: GDNAM1, GDNAM2
        INTEGER           , INTENT(IN   ) :: GDTYP1, GDTYP2
        REAL*8            , INTENT(IN   ) :: P_ALP1, P_ALP2
        REAL*8            , INTENT(IN   ) :: P_BET1, P_BET2
        REAL*8            , INTENT(IN   ) :: P_GAM1, P_GAM2
        REAL*8            , INTENT(IN   ) :: XCENT1, XCENT2
        REAL*8            , INTENT(IN   ) :: YCENT1, YCENT2
        REAL*8            , INTENT(IN   ) :: XORIG1, XORIG2
        REAL*8            , INTENT(IN   ) :: YORIG1, YORIG2
        REAL*8            , INTENT(IN   ) :: XCELL1, XCELL2
        REAL*8            , INTENT(IN   ) :: YCELL1, YCELL2
        INTEGER           , INTENT(IN   ) :: NCOLS1, NCOLS2
        INTEGER           , INTENT(IN   ) :: NROWS1, NROWS2

    LOGICAL FUNCTION  CHKMTXATT3( FNAME )

        CHARACTER( LEN=* ), INTENT( IN ):: FNAME
GDNAM1 ... NROWS1 are for the matrix-input grid; GDNAM2 ... NROWS2 for the matrix-output grid.

Back to Contents

ENDMTXATT

    LOGICAL FUNCTION  ENDMTXATT( )
Turns off input and output grid description attributes from INITMTXATT() or SETMTXATT(): sets MATXMETA = .FALSE..

Back to Contents

INITCF

    SUBROUTINE  INITCF()
Turns on writing CF-compliant metadata for all new I/O API files subsequently created by the calling program.

Back to Contents

SETCF

    GENERIC INTERFACE:
    SUBROUTINE  SETCF( FNAME )
    SUBROUTINE  SETCF( FID )

        CHARACTER( LEN=* ), INTENT( IN ) :: FNAME
        INTEGER           , INTENT( IN ) :: FID
FNAME must be the logical name of an I/O API file currently open for output, or else FID must be the internal file-index for a file currently being opened for output.

Back to Contents

ENDCF

    SUBROUTINE  ENDCF()
Turns off writing CF-compliant metadata for new I/O API files subsequently opened by the calling program: sets CFMETA = .FALSE..

Back to Contents

INITCMAQ

    GENERIC INTERFACE:
    LOGICAL FUNCTION  INITCMAQ()
    LOGICAL FUNCTION  INITCMAQ( MDATA )

        TYPE(CMETA_T) , INTENT( IN ) :: MDATA
Initializes internal state variables holding CMAQ-standard metadata from either the standard-format text file with logical name IOAPI_CMAQMETA, from the program-environment if IOAPI_CMAQMETA=="ENV" or from the argument MDATA.

IOAPI_CMAQMETA should be either NONE to turn off CMAQ metadata (the default), or the path for a structured-ASCII file with format [TBD].

Back to Contents

ISCMAQ

    LOGICAL FUNCTION  ISCMAQ( FNAME )

        CHARACTER( LEN=* ), INTENT( IN ) :: FNAME
Returns TRUE if the specified file's header contains CMAQ metadata.

Back to Contents

GETCMAQ

    GENERIC INTERFACE:
    LOGICAL FUNCTION  GETCMAQ( FNAME )
    LOGICAL FUNCTION  GETCMAQ( FNAME, MDATA )

        CHARACTER( LEN=* ), INTENT( IN ) :: FNAME
        TYPE(CMETA_T)     , INTENT( IN ) :: MDATA
Reads CMAQ-standard metadata from the header of file FNAME and puts it either into CMAQ-metadata object MDATA (if present) or into CMAQ-metadata module variable CMAQ_MDATA. If successful, sets CMAQMETA to TRUE.

FNAME must be the logical name of an I/O API file currently open for input.

Back to Contents

LOGCMAQ

    GENERIC INTERFACE:
    LOGICAL FUNCTION  LOGCMAQ(  )
    LOGICAL FUNCTION  LOGCMAQ( FNAME )
    LOGICAL FUNCTION  LOGCMAQ( MDATA )
    LOGICAL FUNCTION  LOGCMAQ( FNAME, MDATA )

        CHARACTER(LEN=*), INTENT( IN ) :: FNAME
        TYPE(CMETA_T)   , INTENT( IN ) :: MDATA
Writes CMAQ-standard metadata either from metadata-object MDATA (if present) or CMAQ-metadata module variable CMAQ_MDATA (otherwise) either to a structured-ASCII output file FNAME (if present) or to the program log (otherwise).

If present, FNAME must be the logical name for the structured-ASCII output file.

Back to Contents

SETCMAQ

    GENERIC INTERFACE:
    LOGICAL FUNCTION  SETCMAQ( FID )
    LOGICAL FUNCTION  SETCMAQ( FID, MDATA  )
    LOGICAL FUNCTION  SETCMAQ( FNAME )
    LOGICAL FUNCTION  SETCMAQ( FNAME, MDATA )

        INTEGER           , INTENT( IN ) :: FID
        CHARACTER( LEN=* ), INTENT( IN ) :: FNAME
        TYPE(CMETA_T)     , INTENT( IN ) :: MDATA
Writes CMAQ-standard metadata either from metadata-object MDATA (if available) or CMAQ-metadata module variable CMAQ_MDATA (otherwise) to the header of I/O API file with either logical name FNAME or STATE3 file-index FID.
NOTE: the last two forms are the ones intended for modeler-use; the first two should be considered as internal to the I/O API, and is the one called automatically.

If IOAPI_CMAQMETA is not NONE, the first form is called automatically as part of the file-creation process.

PRECONDITION: FNAME must be the logical name of an I/O API file being opened or currently open for output.

Back to Contents

ENDCMAQ

    SUBROUTINE  ENDCMAQ()
Turns off CMAQ-standard metadata: sets MODULE-variable CMAQMETA = .FALSE..

Back to Contents

INITMTEXT

    GENERIC INTERFACE:
    LOGICAL FUNCTION  INITMTEXT()
    LOGICAL FUNCTION  INITMTEXT( NLINES, LINES )

        INTEGER           , INTENT( IN ) :: NLINES
        CHARACTER( LEN=* ), INTENT( IN ) :: LINES( NLINES )
Initializes internal state variables holding structured-text metadata from the 80-col-format text file with logical name IOAPI_TEXTMETA or from the arguments. The first (no-arguments) form is automatically called before opening any newly-created files. The second (explicit arguments) form must be called before opening any new files.

Environment variable IOAPI_TEXTMETA should be either NONE to turn off text metadata (the default), or the path for the ASCII file.

Back to Contents

SETMTEXT

    LOGICAL FUNCTION  SETMTEXT( FID )
        INTEGER           , INTENT( IN ) :: FID
Writes text-file metadata to attribute TEXT_MDATA in the header of [P]netCDF I/O API files open for writing. If text-file metadata is active, this is automatically called for newly-created files.

Back to Contents

ENDMTEXT

    SUBROUTINE  ENDMTEXT()
Turns off text-file metadata: sets MODULE-variable TEXTMETA = .FALSE. and deallocates TEXT_MDATA.

Back to Contents

INITSMOKE

    GENERIC INTERFACE:
    LOGICAL FUNCTION  INITSMOKE( )
    LOGICAL FUNCTION  INITSMOKE( MDATA )

        TYPE(SMETA_T)     , INTENT( IN ) :: MDATA
Initializes internal state variables holding SMOKE-standard metadata.

Back to Contents

GETSMOKE

    GENERIC INTERFACE:
    LOGICAL FUNCTION  GETSMOKE( FNAME )
    LOGICAL FUNCTION  GETSMOKE( FNAME, MDATA )

        CHARACTER(LEN=*), INTENT( IN ) :: FNAME
        TYPE(SMETA_T)   , INTENT( IN ) :: MDATA
Reads SMOKE-standard metadata from the header of file FNAME and puts it either into SMOKE-metadata object MDATA or into SMOKE-metadata module variable SMOKE_MDATA. If successful, sets SMOKEMETA to TRUE.

FNAME must be the logical name of an I/O API file currently open for input.

Back to Contents

SETSMOKE

    GENERIC INTERFACE:
    LOGICAL FUNCTION  SETSMOKE( FID )
    LOGICAL FUNCTION  SETSMOKE( FNAME )
    LOGICAL FUNCTION  SETSMOKE( FNAME, MDATA )

        INTEGER           , INTENT( IN ) :: FID
        CHARACTER( LEN=* ), INTENT( IN ) :: FNAME
        TYPE(SMETA_T)     , INTENT( IN ) :: MDATA
Writes SMOKE-standard metadata either from metadata-object MDATA (if available) or SMOKE-metadata module variable SMOKE_MDATA (otherwise) to the header of I/O API file with either logical name FNAME or file-index FID.
NOTE: the last two forms are the ones intended for modeler-use; the first should be considered as internal to the I/O API, and is the one called automatically.

If SMOKEMETA is TRUE, the first form is called automatically as part of the file-creation process.

PRECONDITION: FNAME must be the logical name of an I/O API file being opened or currently open for output.

Back to Contents

ENDSMOKE

    SUBROUTINE  ENDSMOKE()
Turns off SMOKE-standard metadata: sets SMOKEMETA = .FALSE..

Back to Contents

To: Models-3/EDSS I/O API: The Help Pages

Send comments to

Carlie J. Coats, Jr.
carlie@jyarborough.com