FILES, LOGICAL NAMES AND PHYSICAL NAMES

In dealing with the files, programs using the I/O API refer to files by logical names, instead of forcing the programmer and program-user to deal with hard-coded file names or hard-coded unit numbers. One of the consequences of this is that multiple copies of a program executing at the same time do not interfere with each other, since each execution has its own separate "space" for environment variables. As a modeler, you can define your own logical names as properties of a program (or even prompt the user for his own preferred logical names at run time) and then at run-time connect up the logical names to any "real" file name you want to, using the UNIX csh setenv command. For programming purposes, the significant facts are that names should not contain blanks (except at the end: 'BAR ' is OK; 'B AR' is not), and are at most 16 characters long. Logical names (environment variables) may also be used to control program options and flags; in that case, the routines ENVDBLE , ENVINT , ENVREAL , ENVSTR , ENVYN , and NAMEVAL() may be used to get the value associated with the an environment variable.

The I/O API also uses a standard set of logical names LOGFILE, SCENDESC, and EXECUTION_ID for the program's log, the scenario/run description file, and the run's execution ID. Routine DSCGRID() uses a grid and coordinate description file with logical name GRIDDESC .

When you run a program that uses the I/O API, you begin with a sequence of setenv commands that set the values for the program's logical names, much as you begin a (normal) Cray Fortran program with a sequence of ASSIGN commands for its files. For example, if myprogram has logical names FOO and BAR that I want to connect up to files somedata.mymodel and otherdata.whatever from directory /tmp/mydir, the script for the program would look something like: 

    ...
    setenv  FOO  /tmp/mydir/somedata.mymodel
    setenv  BAR  /tmp/mydir/otherdata.whatever
    /user/mydir/myprogram
    ...

Note that you can declare file properties by various prefixes and suffixes. You may have to quote this value, so that setenv works correctly:

"volatile"
add a trailing (and quoted)  -v to the value of the logical name
setenv QUX "/tmp/mydir/volatiledata.mymodel -v"

"native binary"
add the prefix BIN: to the value of the logical name
setenv FOO BIN:/tmp/mydir/cmaq.conc.US36_CRO.2015233.dat

"buffered"
setenv BAR BUFFERED
where BUFFERED indicates the status of a "virtual" file that never is part of the file system.

"PVM coupling-mode"
either add a prefix  virtual(and use quotes), or (for I/O API-3.2 or later) add the prefix PVM: to the value of the logical name (which is then a PVM-mailbox name constructed by the system, and not a file-system path):
setenv FOO virtual my_file_spec1
or
setenv FOO PVM:my_file_spec2

"PnetCDF distributed"
add the prefix MPI: to the value of the logical name
setenv FOO MPI:/tmp/mydir/cmaq.conc.US36_CRO.2015233.ncf

Next Section: Standard environment variables

Up: Conventions

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