This general macro is the assembler interface to the getenv,
setenv, and unsetenv functions, which get and set the
values of the environment list variables of a process, or remove variables
from the environment list of a process.
Format
- label
- A symbolic name can be assigned to the macro statement.
- FUNCTION
- This parameter specifies one of the following functions to perform on the
environment list for the process:
- GET
- Searches the environment list for a variable name and returns a pointer to
a string containing its associated value.
- SET
- Adds or changes the value of an environment variable. Only the
private environment list of the process is changed; the global default
environment list is not changed.
- UNSET
- Deletes an environment variable. Only the private environment list
of the process is changed; the global default environment list is not
changed.
Entry Requirements
- Register R1 must contain the address of a parameter list. The
format and contents of the parameter list depend on the value of the FUNCTION
parameter:
- GET
- The parameter list consists of one fullword, that contains the address of
a string containing the environment variable name. The string must not
include any bytes containing the values X'00' or C'=' and must
end with a byte containing the value X'00'.
- SET
- The parameter list consists of three fullwords:
- The address of a string containing the name of the environment variable to
be added or changed. The string must not include any bytes containing
the values X'00' or C'=' and must end with a byte containing
the value X'00'.
- The address of a string containing the value to be associated with the
name of the environment variable. The string must not include any bytes
containing the value X'00' and must end with a byte containing the
value X'00'.
- A change flag. If the change flag contains the value 0
(X'00000000'), and the environment variable named by the first
parameter already exists, its value will not be changed. Otherwise (the
change flag contains a nonzero value), the previous value of an existing
environment variable will be changed to the new value given by the second
parameter. If the environment variable does not already exist, it will
be added to the environment list regardless of the value of the change
flag.
- UNSET
- The parameter list consists of one fullword, which contains the address of
a string containing the environment variable name. The string must not
include any bytes containing the values X'00' or C'=' and must
end with a byte containing the value X'00'.
- Callers from the control program (CP) must be in supervisor state, in
31-bit mode, operating in key 0, and in the ECB virtual memory (EVM).
Return Conditions
- In the CP, the contents of register 7 (R7) will not be preserved across
this macro call.
- The contents of R15 depend on the value of the FUNCTION parameter and the
success or failure of the function that is being performed:
- GET
- If the environment variable exists, R15 contains the address of a string
containing its value. The string does not include any bytes that
contain the value X'00', and ends with a byte that contains the value
X'00'. The ECB should not change the value of this string;
any such modification will have results that cannot be predicted.
The program must be in 31-bit mode to view the data.
If the environment variable does not exist, R15 contains the value
F'0'.
- SET
- If the requested SET function was performed, R15 contains the value
F'0'. R15 contains the value F'-1' if the parameter was
incorrect. R15 contains the value F'-2' if it was unable to
obtain storage to obtain the environment list.
- Note:
- The SET function is considered successful when the change flag is set to zero
and prevents a change to the value of a preexisting environment
variable. Possible reasons for failure include not having the ability
to allocate memory for a new environment variable, or being passed a parameter
list that is not valid.
- UNSET
- If the environment variable is removed from the environment list or was
not present in the environment list, R15 contains the value
F'0'. If the UNSET function is not successful (for example, the
parameter list passed to it was not valid), R15 contains the value
F'-1'.
- All other registers are unchanged.
Programming Considerations
- The functions provided by this macro are equivalent to the
getenv, setenv, and unsetenv C library
functions.
- Environment variable names are case sensitive; that is, e and E name
two different environment variables.
- This macro does not require that the ECB has previously initialized a C
run-time environment and does not cause a C run-time environment to be
created.
- If the ECB creates a new ECB by calling the CRESC macro or the
system C library function, the new ECB inherits a copy
of the environment list of the parent process. The child ECB cannot
change the environment list for the parent process.
- The values of the following environment variables are used during
initialization of the C run-time environment:
- If called from the CP, this macro expects R13 to point to a stack.
- This macro affects the environment list owned by the ECB that has control
of the I-stream on which the CENVC macro is called.
- Callers of this macro must be in the EVM.
- Callers of this macro must be in 31-bit mode.
Examples
*
* Set an environment variable.
*
LA R1,VARNAME Set the address of the name ...
ST R1,PLIST as the 1st parameter.
LA R1,SETVAL Set the address of the value ...
ST R1,PLIST+4 as the 2nd parameter.
L R1,CHNGFLG Set the change flag
ST R1,PLIST+8 as the 3nd parameter.
LA R1,PLIST Point R1 to the beginning of the plist.
CENVC FUNCTION=SET Call CENVC to set the variable.
LTR R15,R15 Was the SET successful?
BNZ ERROR1 No, branch to error routine.
*
* Get the value of the environment variable that was just set.
*
LA R1,VARNAME Set the address of the name ...
ST R1,PLIST as the parameter.
LA R1,PLIST Point R1 to the beginning of the plist.
CENVC FUNCTION=GET Call CENVC to get the value
LTR R15,R15 Was it found?
BZ ERROR2 No, branch to error routine.
*
* Delete the environment variable.
*
LA R1,VARNAME Set the address of the name ...
ST R1,PLIST as the parameter.
LA R1,PLIST Point R1 to the beginning of the plist.
CENVC FUNCTION=UNSET Call CENVC to delete the variable.
LTR R15,R15 Was the UNSET successful?
BNZ ERROR1 No, branch to error routine.
·
·
·
PLIST EQU EBW064
VARNAME DC C'GREETING',XL1'00'
SETVAL DC C'Hello, world!',XL1'15',XL1'00'
CHNGFLG DC F'1'