ENVSTR() and envstrc()

Fortran version:

ENVSTR() is a Fortran wrapper calling the C envstrc()
ENVGET() is the Fortran-90-generic (I/O API-3.2 or later only)

SUBROUTINE ENVSTR( LNAME, DESCRIP, DEFAULT, EVALUE, STATUS )
    CHARACTER*(*), INTENT(IN   ) :: LNAME   ! logical name to evaluate
    CHARACTER*(*), INTENT(IN   ) :: DESCRIP ! description of the value
    CHARACTER*(*), INTENT(IN   ) :: DEFAULT ! default value (if LNAME not set, or empty)
    CHARACTER*(*), INTENT(IN   ) :: EVALUE  ! result
    INTEGER      , INTENT(  OUT) :: 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:

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

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

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,
ENVYN,
NAMEVAL; and
SETENVVAR() for setting environment variables from within a program
.

Preconditions:

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

LNAME, DESCRIP, and EQNAME have length at most 65535 bytes for I/O API-3.1 or later (512 bytes for 3.0 or earlier; note that POSIX says environment-variable values with lengths up to 512 must be supported, though most Linux systems allow arbitrary lengths.)

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