ENVINT(), BENVINT(), ENVINT8(), BENVINT8(), envintc(), and envint64c()

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:
ENVINT() is a Fortran wrapper calling the C envintc()
BENVINT() also has MINVALO, MAXVAL arguments (I/O API-3.2 or later only)

INTEGER FUNCTION ENVINT( LNAME, DESCRIP, DEFAULT, STAT )
    CHARACTER*(*), INTENT(IN   ) :: LNAME   ! logical name to evaluate
    CHARACTER*(*), INTENT(IN   ) :: DESC    ! description of the value
    INTEGER      , INTENT(IN   ) :: DEFAULT ! default value (if LNAME not set, or empty)
    INTEGER      , INTENT(  OUT) :: STAT    ! for error/default-case detection

INTEGER FUNCTION BENVINT( LNAME, DESCRIP, MINVAL, MAXVAL, DEFAULT, STAT )
    CHARACTER*(*), INTENT(IN   ) :: LNAME   ! logical name to evaluate
    CHARACTER*(*), INTENT(IN   ) :: DESC    ! description of the value
    INTEGER      , INTENT(IN   ) :: MINVAL
    INTEGER      , INTENT(IN   ) :: MAXVAL
    INTEGER      , INTENT(IN   ) :: DEFAULT ! default value (if LNAME not set, or empty)
    INTEGER      , INTENT(  OUT) :: STAT    ! for error/default-case detection
INTEGER FUNCTION ENVINT8( LNAME, DESCRIP, DEFAULT, STAT )
    CHARACTER*(*), INTENT(IN   ) :: LNAME   ! logical name to evaluate
    CHARACTER*(*), INTENT(IN   ) :: DESC    ! description of the value
    INTEGER(8)   , INTENT(IN   ) :: DEFAULT ! default value (if LNAME not set, or empty)
    INTEGER      , INTENT(  OUT) :: STAT    ! for error/default-case detection

INTEGER FUNCTION BENVINT8( LNAME, DESCRIP, MINVAL, MAXVAL, DEFAULT, STAT )
    CHARACTER*(*), INTENT(IN   ) :: LNAME   ! logical name to evaluate
    CHARACTER*(*), INTENT(IN   ) :: DESC    ! description of the value
    INTEGER(8)   , INTENT(IN   ) :: MINVAL
    INTEGER(8)   , INTENT(IN   ) :: MAXVAL
    INTEGER(8)   , INTENT(IN   ) :: DEFAULT ! default value (if LNAME not set, or empty)
    INTEGER      , INTENT(  OUT) :: STAT    ! for error/default-case detection

C version:

int envintc( const char * lname       , 
             const char * description , 
             int          defaultval  ,
             int        * status )
int envintc( 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 , and interpret it as an integer. 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. STAT takes the following values:

1 for improperly formatted value (e.g., something alphabetic), returning DEFAULT
0 for normal value
-1 for environment value set but empty (returning DEFAULT)
-2 for environment value not set (returning DEFAULT)

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,
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 parameter for logical name 'FOO' which defaults to 17, generating appropriate log messages, etc.:

...
setenv FOO 23
...
/mydirectory/myprogram
...

    ...
    INTEGER        FOO
    INTEGER        STATUS
    ...
    FOO = ENVINT( 'FOO', 
 &             'Some control parameter or other, called FOO',
 &             17 ,
 &             STATUS )
    IF ( STATUS .GT. 0 ) THEN
        ... bad value for FOO; do something.
    END IF
    ...

C Usage:

Same as above, but test for different kinds of defaults as well:

#include "iodecl3.h"
...
int   status, value ;
...
value =  envintc( "FOO", 
                 "Here is where I put a description",
                 17 ,
                 & status ) )
if ( status  0 ) 
    {
    ... stuff for bad (non-integer) value of environment variable FOO
    }
else if ( status == -1 ) 
    {
    ... stuff for empty-but-defined FOO
    }
else if ( status == -2 ) 
    {
    ... stuff for not-defined-at-all FOO
    }
... 
use value...

Previous: ENVDBLE

Next: ENVREAL

Up: Utility Routines

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