ENVREAL(), BENVREAL(), and envrealc()

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

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

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

C version:

float envrealc( const char * lname       , 
                const char * description , 
                float        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 REAL. 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, 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,
ENVINT,
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.0, generating appropriate log messages, etc.:

...
setenv FOOFLAG True
...
/mydirectory/myprogram
...

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

C Usage:

Same as above, but test for defaults as well:

#include "iodecl3.h"
...
int    status ;
double value ;
...
value = envrealc( "FOO", 
                  "Here is where I put a description",
                  17.0 ,
                  & 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: ENVINT

Next: ENVSTR

Up: Utility Routines

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