NAMEVAL()

Fortran version:

    SUBROUTINE NAMEVAL( LNAME, EQNAME )
        CHARACTER*(*), INTENT(IN   ) :: LNAME   ! logical name to evaluate
        CHARACTER*(*), INTENT(  OUT) :: EQNAME  ! value of LNAME from the environment

NO C version:

!! just do the system call getenv() directly !!

Summary:

This routine is a FORTRAN-callable shell around the getenv() system call: find the value of shell variable/logical name LNAME in the environment and return it in EQNAME. This is not only used within the I/O API internally (to deal with logical names of files) but is also useful for retrieving the values of environment-variable flags used to control the mode of operation of programs: since you can call NAMEVAL() from anywhere, you don't have to make special provisions to pass the flags from the program-initialization module to the computational modules where they are actually used; the computational modules can evalutate the flags directly.

Note that NAMEVAL() does not generate log-messages, unlike the ENV*() routines below.

Returns EQNAME=LNAME in case of failure.

Case-sensitive for UNIX (but insensitive for VMS, where environment variable names themselves are case-insensitive).

See also specialized routines for getting DOUBLE PRECISION, INTEGER, REAL, CHARACTER-STRING, or LOGICAL values from the environment, respectively, together with error-status and log-reporting:

ENVGET() (generic environment-value routine, I/O API-3.2 or later),
ENVLIST() (generic environment-list routine, I/O API-3.1 or later)
INTLIST(), REALIST(), STRLIST(): type specific environment-list routines,
ENVDBLE(),
ENVINT(),
ENVREAL(),
ENVSTR(),
ENVYN(); and
SETENVVAR() for setting environment variables from within a program
.

Preconditions:

EQNAME long enough to hold LNAME's value. Values with lengths of up to 65535 bytes for I/O API-3.2 or later are supported. Values whose lengths exceed this limit will be truncated safely. (NOTE: ...up to 512 bytes for I/O API-3.1 and before; POSIX says that environment variables may have lengths this long.)

Fortran Usage:

a program-control flag which has value "ON" when set and which defaults to FALSE:

    ...
    CHARACTER*256  EQNAME
    LOGICAL        FLAG
    ...
    CALL NAMEVAL( 'FOOFLAG', EQNAME ) ) THEN
    IF ( EQNAME .EQ. 'FOOFLAG' ) THEN
        !!  ...NAMEVAL() failed, since EQNAME=LNAME. Maybe M3EXIT()? 
        FLAG = .FALSE.
    ELSE
        !!  ...EQNAME contains value of environment variable "FOO"
        CALL UPCASE( EQNAME )       !  makes it into ALLCAPS
        IF ( EQNAME .EQ. 'ON' ) THEN
            !!  ...foo-flag should be set
            FLAG = .TRUE.
        ELSE
            !!  ...foo-flag should be turned off
            FLAG = .FALSE.
        END IF
    END IF
    ...

C Usage:

Don't; use system call getenv() directly.

Previous: M3WARN

Next: POLY

Up: Utility Routines

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