The I/O API function OPEN3 was created to open both new and existing files. OPEN3 is a FORTRAN logical function that returns TRUE when it succeeds and FALSE when it fails.
LOGICAL FUNCTION OPEN3( FNAME, FSTATUS, PGNAME )
where: CHARACTER*(*) FNAME: file name for query
INTEGER FSTATUS: see possible values in Table 4.3
CHARACTER*(*) PGNAME: name of calling program
This function maintains considerable audit trail information in the file header automatically, as well as automates various logging activities. The arguments to OPEN3 are the name of the file, an integer FSTATUS indicating the type of open operation, and the caller's name for logging and audit-trail purposes. OPEN3 can be called many times for the same file. FSTATUS values are defined for CMAQ in PARMS3.EXT and are also listed in Table 4.3.
Table 4.3. Possible values for OPEN(3) FSTATUS
| FSTATUS | Value | Description |
|---|---|---|
| FSREAD3 | 1 | for READ-ONLY access to an existing file |
| FSRDWR3 | 2 | for READ/WRITE/UPDATE access to an existing file |
| FSNEW3 | 3 | for READ/WRITE access to create a new file (file must not yet exist) |
| FSUNKN3 | 4 | for READ/WRITE/UPDATE access to a file whose existence is unknown |
| FSCREA3 | 5 | for CREATE/TRUNCATE/READ/WRITE access to files |
In the last three cases, “new” “unknown” and “create/truncate,” the code developer may fill in the file description from the INCLUDE file FDESC3.EXT to define the structure for the file, and then call OPEN3. If the file doesn't exist in either of these cases, OPEN3 will use the information to create a new file according to your specifications, and open it for read/write access. In the "unknown" case, if the file already exists, OPEN3 will perform a consistency check between your supplied file description and the description found in the file's own header, and will return TRUE (and leave the file open) only if the two are consistent.
An example of OPEN3 function is listed below (from the CMAQ INITSCEN subroutine). This program segment checks for the existence of a CCTM concentration (CTM_CONC_1) file, which if found will be open read-write-update. If the CCTM CONC file is not found, a warning message will be generated.
IF ( .NOT. OPEN3( CTM_CONC_1, FSRDWR3, PNAME ) ) THEN
MSG = 'Could not open ' // CTM_CONC_1 // ' file for update - '
& // 'try to open new'
CALL M3MESG( MSG )
END IF
To get a file description (i.e., I/O API file type, dimensions, start date, start time, etc.), can be optained bye using DESC3. When DESC3 is called, the complete file description is placed in the standard file description data structures in FDESC3.EXT . Note that the file must have been opened prior to calling DESC3. A typical call might look like this:
IF ( .NOT. DESC3( ' myfile' ) ) THEN
... error message
ELSE
... DESC3 commons now contain the file description
END IF