pxfgetenv

Date:: 10-20-2011

NAME

PXFGETENV - Returns a value for the environment name

SYNOPSIS

SUBROUTINE PXFGETENV(name, lenname, value, lenval, ierror)
CHARACTER* n name, value
INTEGER lenname, lenval, ierror

IMPLEMENTATION

Cray Linux Environment (CLE)

DESCRIPTION

The PXFGETENV subroutine uses the getenv() function to search the environment list for a name in a string of the form name=value.

If name matches a name in the list, the character representation of value is stored in the value character argument and the number of characters in value is stored in lenval. If the length of the value to be placed in value is larger than the declared length of value, the value string is truncated on the right and stored in value. The nontruncated length is stored in lenval and ierror is set to etrunc. If the length of the value is shorter than the declared size of value, the value string is stored with left justification and filled with blanks on the right. lenval is set to the shorter length of the value string.

If name is found but has no value, blanks are stored in value and lenval is set to zero. If name cannot be found, EINVAL is returned in ierror.

When using the Cray Fortran compiler, all arguments must be of default kind unless documented otherwise. The default kind is KIND=4 for integer, real, complex, and logical arguments.

The following is a list of valid arguments for this routine:

name

An input character variable or array element containing the name of an environment variable.

lenname

An input integer variable containing the length of name in characters. If lenname is zero, the trailing blanks are removed. The declared length of the input name is decremented by the number of blanks removed. If lenname is zero and name is all blanks, the input name is a null string.

value

An output character variable or array element containing the value of the environment variable name.

lenval

An output integer variable containing the length of value in characters. If name is found but has no value, lenval is zero and value contains all blanks to indicate a null string. If the value representation is truncated to be stored in value, lenval contains the nontruncated length of value. If the value representation is shorter than the length of value, lenval contains the shorter length.

ierror

An output integer variable containing the status:

EINVAL: If name is not in the environment list.
ETRUNC: If the declared length of value is insufficient to contain the string to be returned. The value of name is truncated to fit in value, and lenval contains the original length of the value of name before truncation.
Zero: getenv is successful (if name is found).

EXAMPLES

In this example, PXFGETENV searches for a string containing SHELL=value.

     program testpxf
     character*24 namea, nameb
     integer lena, lenb, ier
c set input arguments
     ier = 0
     lena=0
     lenb=0
     namea='SHELL'
     nameb=' '
     CALL PXFGETENV (namea, lena, nameb, lenb, ier)
     print *,'TEST results:'
c print input arguments
     print *,'namea=-',namea,'-'
     print *,'lena=',lena
c print output arguments
     print *,'nameb=-',nameb,'-'
     print *,'lenb=',lenb
     print *,'ier=',ier
     end

If the string is found, it may return:

TEST results:
namea=-SHELL
lena=0
nameb=-/bin/csh
lenb=8
ier=0