Environment-LIST() Functions

Fortran version:

Generic form, returns INTEGER, REAL, or CHARACTER*(*) arrays (I/O API-3.1 or later, only), or REAL*8 arrays (I/O API-3.2 or later, only)

    LOGICAL FUNCTION ENVLIST( ENAME, EDESC, NMAX, NCNT, *LIST )
        CHARACTER*(*), INTENT(IN   ) :: ENAME   !  in:  environment variable for the list
        CHARACTER*(*), INTENT(IN   ) :: EDESC   !  in:  environment variable description
        INTEGER      , INTENT(IN   ) :: NMAX    !  in:  dimension for list
        INTEGER      , INTENT(  OUT) :: NCNT    ! out:  actual number of entries in list
        INTEGER      , INTENT(  OUT) :: ILIST( NMAX )    ! out:  array of values found
        REAL         , INTENT(  OUT) :: RLIST( NMAX )    ! out:  array of values found
        REAL*8       , INTENT(  OUT) :: DLIST( NMAX )    ! out:  array of values found
        CHARACTER*(*), INTENT(  OUT) :: SLIST( NMAX ) ]  ! out:  array of string values found

Type-specific forms: (all I/O API versions)

    LOGICAL FUNCTION INTLIST( ENAME, EDESC, NMAX, NCNT, ILIST )
    LOGICAL FUNCTION REALIST( ENAME, EDESC, NMAX, NCNT, RLIST )
    LOGICAL FUNCTION DBLLIST( ENAME, EDESC, NMAX, NCNT, DLIST )   !!  I/O API 3.2 only
    LOGICAL FUNCTION STRLIST( ENAME, EDESC, NMAX, NCNT, SLIST )
        CHARACTER*(*), INTENT(IN   ) :: ENAME   !  in:  environment variable for the list
        CHARACTER*(*), INTENT(IN   ) :: EDESC   !  in:  environment variable description
        INTEGER      , INTENT(IN   ) :: NMAX    !  in:  dimension for list
        INTEGER      , INTENT(  OUT) :: NCNT    ! out:  actual number of entries in list
        INTEGER      , INTENT(  OUT) :: ILIST( NMAX )    ! out:  array of values found
        REAL         , INTENT(  OUT) :: RLIST( NMAX )    ! out:  array of values found
        REAL*8       , INTENT(  OUT) :: DLIST( NMAX )    ! out:  array of values found
        CHARACTER*(*), INTENT(  OUT) :: SLIST( NMAX )    ! out:  array of string values found

NO C versions:

Roll your own out of standard library function strtok().

Summary:

Looks at the value of the indicated environment variable, parses and evaluates it as a (blank- or) comma-delimited list of the indicated type, counts the number of entries and returns the count in NCNT and the values in the array [I|R|S]LIST. Environment-variable lists may have an optional LIST: prefix, followed by a sequence of comma-delimited values. Blanks are not significant (and are skipped).

I/O API-3.2 and later also now support blank-delimited lists. Previous versions require comma-delimited lists.

Return FALSE if ENAME is a bad environment variable, if there are no entries in the list or if the list does not parse and evaluate correctly, or if the array would have overflowed (i.e., has more than NMAX entries). If FALSE:

NCNT=NMAX
the list overflowed (more than NMAX values in the environment-variable value)
NCNT=0
either a bad environment variable or an empty list from the environment
Otherwise
formatting error on some list entry

NOTE: It is a serious offense against good software engineering principles to use something meaningless (like a blank) as the EDESC description-argument. Doing so may justifiably be taken as an attempt to make the code unreadable and unusable by anyone except the original author.

For Fortran-90 declarations and interface checking:

    USE M3UTILIO

See also

ENVGET (generic environment-value routine, I/O API-3.2 or later),
ENVDBLE,
ENVINT,
ENVREAL,
ENVSTR,
ENVYN,
NAMEVAL; and
SETENVVAR() for setting environment variables from within a program
.

Preconditions:

setenv <logical name> [LIST:]<quoted, comma-delimited list of integers, reals, or strings>

String-length of the comma-delimited list is at most 65535 (or for the pre-2014 version, 511) characters.
There are at most NMAX entries in the list.

Fortran Usage:

Generic form: compiler will select INTLIST() in this case, because the LIST argument is INTEGER:

    ...
    USE M3UTILIO
    ...
    INTEGER, PARAMETER :: NMAX = ...
    ...
    INTEGER         ILIST( NMAX )
    REAL            RLIST( NMAX )
    CHARACTER*16    CLIST( NMAX )
    INTEGER         NCNT
    ...
    IF ( .NOT. ENVLIST( 'MYINTLIST', 
 &                 'This is my comma-delimited list of INTEGERs', 
 &                 NMAX, NCNT, ILIST ) ) THEN
        !! either bad environment variable, invalid INTEGERs
        !! in the list, list had no entries, or list overflowed
        ...
    END IF
    ...
    IF ( .NOT. ENVLIST( 'MYREALLIST', 
 &                 'This is my comma-delimited list of REALs', 
 &                 NMAX, NCNT, RLIST ) ) THEN
    ...
    IF ( .NOT. ENVLIST( 'MYCHARLIST', 
 &                 'This is my comma-delimited list of CHAR-strings', 
 &                 NMAX, NCNT, CLIST ) ) THEN
        ...
    ...

Type-specific form, for an INTEGER list:

    ...
    USE M3UTILIO
    ...
    INTEGER     NMAX
    PARAMETER ( NMAX = ... )
    ...
    INTEGER     ILIST( NMAX )
    INTEGER     NCNT
    ...
    IF ( .NOT. INTLIST( 'MYINTLIST', 
 &                 'This is my comma-delimited list of INTEGERs', 
 &                 NMAX, NCNT, ILIST ) ) THEN
        !! either bad environment variable, invalid INTEGERs
        !! in the list, list had no entries, or list overflowed
        ...
    END IF
    ...

C Usage:

don't

Previous: LEN2

Next: LOCATC, LOCAT1, LOCAT2, LOCAT3, LOCAT4, LOCATR1, LOCATR2, LOCATR3, LOCATR4

Up: Utility Routines

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