ENVSTR() and envstrc()

Fortran version:

ENVSTR() is a Fortran wrapper calling the C envstrc()

    SUBROUTINE ENVSTR( LNAME, DESCRIP, DEFAULT, EVALUE, STATUS )
        CHARACTER*(*)    LNAME   ! logical name to evaluate
        CHARACTER*(*)    DESCRIP ! description of the value
        CHARACTER*(*)    DEFAULT ! default value (if LNAME not set, or empty)
        CHARACTER*(*)    EVALUE  ! result
        INTEGER          STATUS  ! for error/default-case detection

C version:

void envstrc( const char * lname        ,   /* logical name */
               const char * description ,   /* description */
               const char * defaultval  ,   /* default value */
               char       * evalue      ,   /* result buffer */
               int        * status      ,   /* error/default-case  */
               int          elen /* length of the "evalue" buffer */
	       )

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 a CHARACTER string. 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. Returns STATUS indicating the nature of the DEFAULT returned. STATUS takes the following values:

For Fortran-90 declarations and interface checking:

    USE M3UTILIO
    

NOTE: envstrc() null-terminates the returned value iff its length is at most elen. Otherwise, it padds from the end of the value up to elen with ASCII NULLs (i.e., its behavior is the same as strncpy() ).

See also

ENVDBLE,
ENVINT,
ENVREAL,
ENVYN,
NAMEVAL, and
SETENVVAR.

Preconditions:

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

LNAME, DESCRIP, and EQNAME have length at most 256. (NOTE: POSIX says that environment variables may have lengths this long.)

Fortran Usage:

Get a program-control parameter for logical name 'FOO' which defaults to 17.0D0, generating appropriate log messages, etc.:
...
setenv FOO /work/qux/data
...
/mydirectory/myprogram
... 
    ...
    CHARACTER*256  FOO
    INTEGER        STATUS
    ...
    CALL ENVSTR( 'FOO', 
 &             'Some control parameter or other, called FOO',
 &             '/tmp/bar/whatever' ,
 &             FOO ,
 &             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 ;
char   value[ 257 ] ;
...
envstrc( "FOO", 
                  "Here is where I put a description",
                  "some_default",
                  value,
                  & status ) )
if ( status > 0 ) 
    {
    ... stuff for bad (non-string?) 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: ENVREAL

Next: ENVYN

Up: Utility Routines

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