PROMPTMFILE()

Fortran version:

    CHARACTER*16 FUNCTION  PROMPTMFILE( PROMPT, FMODE, DEFAULT, CALLER )
      CHARACTER*(*) PROMPT         !  prompt for user
      INTEGER       FMODE          !  file opening-mode
      CHARACTER*(*) DEFAULT        !  default logical file name
      CHARACTER*(*) CALLER         !  caller-name for logging messages

C version: none

Summary:

For interactive use -- not for modeling nor for programs that will be driven by scripts! For modeling or script driven programs, use OPEN3(), instead.

Prompts user for logical file name, then uses OPEN3() to open the I/O API file associated with it according to the indicated FMODE:

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

If environment variable PROMPTFLAG is set to "N", returns the logical name contained in DEFAULT without prompting the user.

Logs the value returned, for tracking and validation purposes.

Returns

logical name for the file opened, or
'NONE', provided that '"NONE"' occurs within the prompt.

For Fortran-90 declarations and interface checking:

    USE M3UTILIO

See also:

GETDFILE(),
GETEFILE(),
PROMPTDFILE(), and
PROMPTFFILE().

See also OPEN3(), PROMPTDFILE(), and PROMPTFFILE().

Preconditions:

USE M3UTILIO or INCLUDE 'IODECL3.EXT' and INCLUDE 'FDESC3.EXT'

setenv <lname> <pathname> for the file before program launch.

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

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

Must not be called for new (FSNEW3) on a file already open.

Fortran Usage:

To get a logical name from the user, and open an optional output file with the indicated description:

    ...
    USE M3UTILIO
    ...
    CHARACTER*16  FNAME
    ...
    ... set up file description if FDESC3 COMMONs...
    FNAME = PROMPTMFILE( 
   &        'Enter optional file name for FOO (or "NONE")',
   &        FSUNKN3, 'FOO', 'me' )
    IF ( FNAME .EQ. 'NONE" ) THEN
        ... user doesn't want output foo-file
    END IF
    ...

C Usage: don't.

Previous: PROMPTFFILE

Next: READSMET

Up: Utility Routines

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