Environment Variables for the I/O API

Standard I/O API environment variables

The following are standard environment variables supported or used by the I/O API. These should be set using setenv, for example, if you are using csh). Note that for environment variables with multi-word values (i.e., values containing blanks), you will need to quote the value in order for setenv to handle it correctly—for example:

        setenv  EXECUTION_ID  'This run will pling the Inghams'
        setenv  MYLIST        '1, 2, 3, 4, 5, 6, 7'
    

• LOGFILE is the physical pathname for the program log. If this logical name is present, the indicated file is opened for output; otherwise, Fortran standard output to UNIT 6 for the log is assumed. This log file is used throughout the I/O API; also, its unit number is returned by calls to INIT3().
  This facility was provided for use with (now-obsolete) devices like CalComp plotters that hijack STDOUT.

• SCENFILE is the physical pathname for the scenario description file. If present, the contents of this file will be copied into the "update description" of files opened for writing during this program execution. The file may have up to MXDESC3=60 lines of length at most MXDLIN3=80.

• GRIDDESC is the logical name for the ASCII horizontal coordinate and grid description files used by utility routines DSCGRID() and DSCOORD().

• EXECUTION_ID is provided for use in tracking the system ID of the current execution, and if present, it is copied into the "execution ID" field of files opened for writing during this program execution. It is a character string of length at most MXDLIN3=80. with default value CMISS3="????????????????"

• IOAPI_ISPH (REAL*8 value) tells the system which GCTP-sphere to use (the default is the GRS 1980 geodetic spheroid): see STDSPHERES and SPHERENAMES in MODULE MODGCTP and routines SETSPHERE, INITSPHERES, and SPHEREDAT, This environment variable is also used by a number of m3tools programs that call these routines; see either the manual-pages for these programs or the PRECONDITIONS sections of their respective splash-screens.

• IOAPI_CHECK_HEADERS (LOGICAL Y/N) controls whether consistency and validity checks are turned on for files being created (value begins with 'Y' or 'y'), or not. The default value is 'N', indicating that the check will not take place.

• IOAPI_OFFSET_64 (LOGICAL Y/N) controls a netCDF limitation: by default, netCDF cannot handle output time steps larger than 2 GB. If this is turned on (setenv IOAPI_OFFSET_64 YES), then netCDF is told to create files that can have timesteps larger than 2 GB. Note that MXVARS3=2048 variables on a 100×100×25 grid (or 21 variables on a 1000×1000×25 grid) occupies slightly less than 2GB, so we're talking "quite large" model runs in order to need this...).
  The default value is N for I/O API versions 3.1 or earlier, or 3.2 before Dec. 25, 2017, and Y for 3.2 thereafter.
  Older versions of NetCDF still have a 2GB per variable per time step limitation, by the way—though it is worth noting that for your model to use single arrays larger than 2GB, you will have to compile it with the "64-bit medium memory model", which is not the default for the Intel, GNU, or Portland Group compilers: see the installation-doc section about Intel memory models.

• IOAPI_LOG_WRITE (LOGICAL Y/N) controls whether a log message is written for each successful WRITE3() operation (messages are always written for failures). The default value is 'Y', indicating that the log messages will be generated.

• IOAPI_KEEP_NSTEPS (INTEGER value with default 2) controls how many time steps of data will be kept in active PVM mailboxes for I/O API coupling-mode virtual files

• PROMPTFLAG (LOGICAL Y/N, with default N) controls whether routines GETDBLE(), GETMENU(), GETNUM(), GETREAL(), GETSTR(), GETYN(), PROMPTFFILE(), and PROMPTMFILE(), prompt the user for the value requested, or not. Setting PROMPTFLAG to "N" can be used, in conjunction with the selection of "smart" defaults within programs, to make it easier to write scripts for running various programs that insist on using these prompt-style interactive-orented routines.

The following environment variables are for I/O API-3.2 or later only:

• IOAPI_CFMETA (LOGICAL Y/N, with default N) controls whether CF compliant metadata will be written to the headers of newly-created files.

• IOAPI_CMAQMETA (NONE (default), ENV, or <path to ASCII CMAQ metadata input file>
  controls whether standard CMAQ metadata will be written to the headers of newly-created files.

• IOAPI_SMOKEMETA (NONE (default), ENV, or <path to ASCII SMOKE metadata input file>
  controls whether SMOKE-standard metadata will be written to the headers of newly-created files (currently stubbed-in but not yet turned on by the SMOKE developers, 10/2015).

• SNOOPTRY3, SNOOPSECS3 control the number of re-tries and the delay between re-tries (secs) for I/O API snoop-mode operation.
  Note that snoop-mode must be enabled in the Makefile when you build libioapi.a
  SNOOPTRY3 = 0 gives unlimited re-tries.
  SNOOPTRY3 < 0 or SNOOPSECS3 ≤ 0 turn off snoop mode.

• MPAS_VERBOSE Y N [N] controls verbose diagnostic output in MODULE MODMPASFIO

• MPAS_CHKFILL Y N [Y] controls input "hole-detection" checks against netCDF fill-values for intput read by MODULE MODMPASFIO routine READMPAS()

OpenMP Parallel Control

Generally, all OpenMP parallel programs use environment variable OMP_NUM_THREADS to control how many parallel threads/processors are used for program execution. In particular, this applies to "m3tools" programs M3AGMASK, M3AGMAX, M3COMBO, M3TPROC and VERTINTEGRAL for I/O API version 3.1 later than Nov. 21, 2013, and programs built with I/O API routines BILIN(), BMATVEC(), DMATVEC, CBARNES1(), and CBARNESN() using I/O API versions later than Sept. 12, 2014.

I/O API Environment-Variable Routines

Routine SETENVVAR() can be used to set environment variables from within the currently-executing program.

For single-valued environment variables of various types. ENVDBLE(), ENVINT(), ENVREAL() , ENVSTR(), and ENVYN() can be used from programs to find values of types DOUBLE PRECISION, INTEGER, REAL, CHARACTER string, or LOGICAL.
For I/O API-3.2 or later, ENVGET() is a generic routine for single-value environment variables of any of these types.
These routines contain a "description" argument, which is copied to the program log for audit-trail reasons, and which is useful for program self-description. Subverting this mechanism by using a blank or ASCII-null description should be considered a serious offense against modeling integrity.

For environment variables whose values are comma-delimited lists INTLIST(), REALLIST(), DBLLIST(), and STRLIST() are type-specific for lists of types INTEGER, REAL, REAL*8 or CHARACTER string; for I/O API-3.2 or later, ENVLIST() is the generic.
All of thes routines log the value retrieved, convert it to the indicated type, and return the number of values and the array of values retrieved to the caller.

Routine NAMEVAL(), which performs a similar function for CHARACTER STRINGs, but does not log the transaction, is used internally by the I/O API; this should not be used by modeling codes, for log-integrity reasons.

Next Section: Grids and Coordinate Systems

Up: Conventions

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