LOGICAL FUNCTION OPEN3( FNAME, FSTATUS, PGNAME ) CHARACTER*(*), INTENT(IN ) :: FNAME ! file name for query INTEGER , INTENT(IN ) :: FSTATUS ! FSREAD3, FSRDWR3, FSNEW3, FSUNKN3, FSCREA3 CHARACTER*(*), INTENT(IN ) :: PGNAME ! name of calling program
int open3c( const char * fname , const IOAPI_Bdesc3 * bdesc , const IOAPI_Cdesc3 * cdesc , int fstatus , const char * pgname ) ;
PROMPTMFILE()
,
which is a (text-mode interactive) wrapper around OPEN3()
that
prompts the user for the logical name of the file to be opened.
Also see GETDFILE()
and
GETEFILE()
, for opening
Fortran sequential and direct access files by logical name.
FNAME
, with file mode/status
FSTATUS
of one of
the following
"magic number" tokens
(defined in INCLUDE-file
PARMS3.EXT):
FSREAD3==1 for read-only, FSRDWR3==2 for read/write/update of existing files, FSNEW3 ==3 for read/write of new files (file must not already exist), FSUNKN3==4 for read/write/update of unknown (new vs. old) files. If file does not exist, create it; else check for consistency with user-supplied file description. FSCREA3==5 for create/truncate/read/write of files. If file exists, delete it; then create a new (empty) file according to the user-supplied file description
If FNAME is being opened for write, copies
scenario description from file
with logical name SCENDESC
, name PGNAME
of
the caller, and value of environment
variable EXECUTION_ID
to the file's history
(maintained in the file header).
May be called multiple times for a file (provided you don't attempt to go from readonly to any read/write status).
If file may possibly be created (i.e., if the access mode is either
FSNEW3
, FSUNKN3
, or FSCREA3
),
the user must supply a file description in the COMMON
s
in INCLUDE-file
FDESC3.EXT (for
Fortran) or in the data structures pointed to by arguments
bdesc
and cdesc
(for C). In the latter
case, the file description struct pointers are only required when
the file is being opened "new" or "unknown".
"Normal" modeling usage should be to open input files as
FSREAD3
and output files as FSUNKN3
. If
you open output files as FSNEW3
, you must take care to
remove pre-existing files before running your program.
NOTE: Joan Novak (EPA) and Ed Bilicki (MCNC)
have declared as a software standard that modeling programs
may not use FSCREA3
as the mode for opening
files. FSCREA3
is reserved for use by
analysis/data extraction programs only.
USE M3UTILIO
or
INCLUDE 'IODECL3.EXT'
and
INCLUDE 'FDESC3.EXT'
for Fortran, or #include "iodecl3.h"
and
#include "fdesc3.h"
for C.
FNAME
must have length at most 16.
For FSREAD3
or FSRDWR3
, file must already exist.
For FSNEW3
, file must not already exist.
For FSUNKN3
, if the file already exists, the file type,
dimensions, time step and variables supplied by the caller must
match those on the file. The caller-supplied starting date and time
must be a legal output time step in the time step sequence found on
the file: for example, if the starting time from the file header
is 1997012:120000, and the time step is one hour (10000), then
opening this file FSUNKN3
with a caller-supplied
starting date and time of 1997012:180000 is OK (that would be
time step number 7 for the file-header time step sequence) but
a caller-supplied 1997011:120000 is not, since it is before the
starting date and time from the file itself.
For FSNEW3
, FSUNKN3
, or
FSCREA3
, caller must supply file description (which
must follow Models-3 date and time
conventions).
I/O API must already be initialized by a call to INIT3() or init3c().
OPEN3()
must not be called for read/write/update
(FSRDWR3, FSNEW3, FSUNK3
, or FSCREA3
) on a
file already open for read-only (FSREAD3
).
OPEN3()
must not be called for new
(FSNEW3
) on a file already open (if the file
already exists, that contradicts the "new").
USE M3UTILIO
See the sample programs for usage examples.
... USE M3UTILIO ... IF ( OPEN3( 'MYFILE', FSREAD3, 'Myprogram' ) ) THEN !! MYFILE successfully opened for read-only ... ELSE !! Could not open MYFILE for read-only. See program log !! for further info. ... END IF ... !! <Fill in the file's description to variables in FDESC3.EXT> SDATE3D = 1988021 ... IF ( OPEN3( 'AFILE', FSNEW3, 'Myprogram' ) ) THEN !! AFILE successfully opened as a new file ... ELSE !! Could not open AFILE as a new file: probably AFILE already !! exists. See program log for further info. ... END IF ... ... !! <Fill in the file's description to variables in FDESC3.EXT> SDATE3D = 1988022 ... IF ( OPEN3( 'BFILE', FSUNKN3, 'Myprogram' ) ) THEN !! BFILE successfully opened as unknown ... ELSE !! Could not open BFILE as unknown: probably BFILE already !! exists and has a different description than you gave. !! See program log for further info. ... END IF ...
... #include "iodecl3.h" ... IOAPI_Bdesc3 bdesc ; IOAPI_Cdesc3 cdesc ; ... /* put file description in bdesc and cdesc. Then: */ if ( open3c( "MYFILE", &bdesc, &cdesc, FSREAD3, "Myprogram" ) ) { /* MYFILE successfully opened for read-only */ ... } ... /* etc... */
To: Models-3/EDSS I/O API: The Help Pages