ENVDBLE(), BENVDBLE(), and envdblec()

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

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

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

C version:

double envdblec( const char * lname       , 
                 const char * description , 
                 double       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 double precision. 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)

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),
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:

For Fortran-90 declarations and interface checking:

    USE M3UTILIO

Example: get a program-control parameter for logical name 'FOO' which defaults to 17.0D0, generating appropriate log messages, etc.:

...
setenv FOO 23.9876543212345
...
/mydirectory/myprogram
...

    ...
    INTEGER        FOO
    INTEGER        STATUS
    ...
    FOO = ENVDBLE( 'FOO', 
 &             'Some control parameter or other, called FOO',
 &             17.0D0 ,
 &             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 = envdblec( "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: DSCGRID

Next: ENVINT

Up: Utility Routines

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