KFOPEN()

Fortran version:

    LOGICAL FUNCTION  KFOPEN( FNAME, FSTATUS, PGNAME, KFCOUNT )
        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
        INTEGER      , INTENT(  OUT) :: KFCOUNT( * )  !  gridded event counts

C version:

See Also:

OPEN3(), for opening "normal" I/O API data files.

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.

Summary:

    FSREAD3==1 for read-only,
    FSRDWR3==2 for read/write/update of existing files,
    FSNEW3 ==3 for read/write of new files,
    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).

Returns current gridded event count in BUFFER, which should previously have been declared as in integer array dimensioned with the current columns and rows:

    INTEGER     KFCOUNT( NCOLS3D, NROWS3D )
    

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 COMMONs 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".

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.

May be called multiple times for a file (provided you don't attempt to go from readonly to any read/write status), or subsequent to an OPEN3() call on the same file, in which case it simply returns the event-count information in BUFFER. Except as a means of reading the gridded event count, deprecated in favor of inclusion of the similar functionality into OPEN3().

KFOPEN() is OpenMP thread-safe.

Preconditions:

INCLUDE 'IODECL3.EXT' and INCLUDE 'FDESC3.EXT' for Fortran.

FNAME must have length at most 16.

For FSREAD3 or FSRDWR3, file must already exist.

For FSNEW3, file must not already exist.

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().

KFOPEN() must not be called for read/write/update (FSRDWR3, FSNEW3, FSUNK3, or FSCREA3) on a file already open for read-only (FSREAD3).

KFOPEN() must not be called for new (FSNEW3) on a file already open or that already exists.

Fortran Usage:

    ...
    INCLUDE 'IODECL3.EXT'
    INCLUDE 'PARMS3.EXT'
    INCLUDE 'FDESC3.EXT'
    ...
    INTEGER  MYCOUNT ( NCOLS, NROWS )
    INTEGER  KFCOUNTA( NCOLS, NROWS )
    INTEGER  KFCOUNTB( NCOLS, NROWS )
    ...
    IF ( KFOPEN( 'MYFILE', FSREAD3, 'Myprogram', MYCOUNT ) ) THEN
C              MYFILE successfully opened for read-only
C              MYCOUNT is initialized with gridded event-counts from MYFILE
C              (numbers of events existing at each column and row)
        ...
    ELSE
C           Could not open MYFILE for read-only. See program log 
C           for further info.
        ...
    END IF
    ...
C       <Fill in the file's description to variables in FDESC3.EXT&gt;
    SDATE3D = 1988021
    ...
    IF ( KFOPEN( 'AFILE', FSNEW3, 'Myprogram', KFCOUNTA ) ) THEN
C              AFILE successfully opened as a new file
C              KFCOUNTA is initialized with zeros
        ...
    ELSE
C           Could not open AFILE as a new file:  probably AFILE already
C           exists.  See program log for further info.
        ...
    END IF
    ...
    ...
C       <Fill in the file's description to variables in FDESC3.EXT&gt;
    SDATE3D = 1988022
    ...
    IF ( KFOPEN( 'BFILE', FSUNKN3, 'Myprogram', KFCOUNTB ) ) THEN
C              BFILE successfully opened as unknown
C              KFCOUNTB is initialized with gridded event-counts
C              (which is zero if a new file was created)
        ...
    ELSE
C           Could not open BFILE as unknown:  probably BFILE already
C           exists and has a different description than you gave.
C           See program log for further info.
        ...
    END IF
    ...

C Usage:

Next: KFREAD

Up: Public I/O Routines

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