ENVYN() and envync()

Fortran version:

ENVGET() is the Fortran-90-generic (I/O API-3.2 or later only) that calls the following (or various other routines), as determined by the argument-list:

ENVYN() is a Fortran wrapper calling the C envync() 

LOGICAL FUNCTION ENVYN( LNAME, DESCRIP, DEFAULT, STATUS )
    CHARACTER*(*), INTENT(IN   ) :: LNAME   ! logical name to evaluate
    CHARACTER*(*), INTENT(IN   ) :: DESCRIP ! description of the value
    LOGICAL      , INTENT(IN   ) :: DEFAULT ! default value (if LNAME not set, or empty)
    INTEGER      , INTENT(  OUT) :: STATUS  !  for distinguishing error/default-value cases

C version: 

int envync( const char * lname       , 
            const char * description , 
            int          defaultval  ,
            int        * status )

Summary:

This function is a shell around the getenv() system call: find, log, and return the value of shell variable/logical name LNAME in the environment , interpret it as a logical TRUE or FALSE according to whether the first character of the value is (after upcasing) either 'T' or 'Y' (for TRUE) or 'F' or 'N' (for FALSE). Returns the DEFAULT if the logical name is not defined, is defined but has an empty value, or has an improper value. Writes a message to the log indicating the value returned -- and if the value was improper, writes a warning notice.

Treats ".T"... and ".F"... as though they were "T"... and "F"..., respectively.

Returns DEFAULT in case that LNAME not defined, that LNAME is defined but has an empty value, or that the value of LNAME does not begin with 'T' or 'Y' (for TRUE) or 'F' or 'N' (for FALSE).

STATUS takes the following values:

For Fortran-90 declarations and interface checking: 

    USE M3UTILIO

See also

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

Preconditions:

#include "iodecl3.h" if called from C.

LNAME and DESCRIP have length at most 512 for I/O API-3.0 or earlier, 65535 for I/O API-3.1. (NOTE: POSIX says that environment variables with lengths at least 512 must be supported.)

Fortran Usage:

Get a program-control flag for logical name 'FOOFLAG' which defaults to FALSE, generating appropriate log messages, etc.: 
...
setenv FOOFLAG True
...
/mydirectory/myprogram
... 

    ...
    USE M3UTILIO
    ...
    LOGICAL        ENVYN
    LOGICAL        FOOFLAG
    INTEGER        STATUS
    ...
    FOOFLAG = ENVYN( 'FOOFLAG', 
 &             'Some flag or other, called FOO',
 &             .FALSE. ,
 &             STATUS )
    IF ( STATUS .GT. 0 ) THEN
        ... bad value for FOOFLAG; do something.
    END IF
    ...

C Usage:

As above, but distinguish the various kinds of default cases. 
#include "iodecl3.h"
...
int status, value ;
value =  envync( "FOOOFLAG", 
                 "Here is where I put a description",
                 0 ,
                 & status ) )
if ( status > 0 ) 
    {
    ... stuff for bad value of this environment variable 
    }
else if ( status == -1 ) 
    {
    ... stuff for empty-but-defined FOO
    }
else if ( status == -2 ) 
    {
    ... stuff for not-defined-at-all FOO
    }

if ( value ) 
    {
    ... stuff for FOOFLAG TRUE
    }
else{
    ...stuff for FOOFLAG FALSE
    }
...

Previous: ENVSTR

Next: FIND1, FIND2, FIND3, FIND4

Up: Utility Routines

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