CEEENV—Process environmental variables
CEEENV processes environment variables
depending on the function code passed in as input. Based on the input
to this function, CEEENV can do the following:
- Obtain the value for an existing environment variable
- Create a new environment variable with a value
- Clear all environment variables
- Delete an existing environment variable
- Overwrite the value for an existing environment variable
Syntax >>-CEEENV--(--function_code--,--name_length--,--name--,---------> >--value_length--,--value--,--fc--)----------------------------><
- function_code (input)
- A fullword binary integer containing the function code of one
of the following values:
- 1
- Searches the environment table for environment variables specified by name and if found returns a pointer to value.
- 2
- Adds an environment variable to the environment table. It does not overwrite an existing environment variable.
- 3
- Clears all environment variables from the environment table.
- 4
- Deletes an environment variable from the environment table.
- 5
- Overwrites an existing environment variable in the environment table and adds the environment variable if it does not exist.
- name_length (input)
- A fullword binary integer containing the length of the name for the environment variable. If the request is for function code 3, this argument is ignored.
- name (input)
- Specifies the name of an environment variable. If the request is for function code 3, this argument is ignored.
- value_length (input/output)
- A fullword binary integer containing the length of the value for the environment variable. This argument is input for setting or modifying an environment variable and is output for getting an environment variable value. If the request is for function code 3 or 4, this argument is ignored.
- value (input/output)
- A field that contains the address of a string that contains the value of the environment variable. This argument is input for setting or modifying an environment variable and is output for getting an environment variable value. If the request is for function code 3 or 4, this argument is ignored. For function code 1 (get), the value address is 0 (NULL) if the name is not found in the environment.
- fc (output)
- A 12-byte feedback code, optional in some languages,
that indicates the result of this service. If you choose to omit this
parameter, refer to Invoking callable services for the
appropriate syntax to indicate that the feedback code was omitted.
Code Severity Message number Message text CEE000 0 — The service completed successfully. CEE51O 3 5176 Not enough memory available. CEE51P 3 5177 Bad input character detected for name or value. CEE51Q 3 5178 Bad address detected for the ENVAR anchor or environment variable array. CEE51R 3 5179 A parameter to the environment variable processing routine contained a value that was not valid. CEE51S 0 5180 The specified environment variable name already exists.
Usage notes
- The environment array is searched sequentially and the first occurrence of name is used.
- Because an application can manipulate the environment using the environ pointer, Language Environment® cannot guarantee a single instance of any particular environment variable.
- For a function code 1 request, the storage returned for the value character string is supplied by Language Environment. There is one buffer per thread, making it the user's responsibility to use or save the value before the next call for a function code 1 on that thread.
- Specifying 0 for value_length with function code 2 or 5 results in the environment variable being removed from the environment.
- Applications should not define environment variables that begin with the characters "_BPXK_", "_EDC_", or "_CEE_" because there might be conflicts with variable names reserved for z/OS® that begin with those characters.
- name and value are copied into storage owned by Language Environment.
- If a function code 1 request is made and the variable name is not found in the environment, value_length is set to 0 upon return.
- A NULL character in name is not valid and causes feedback code CEE51P to be returned.
- A NULL character in value is interpreted as a string terminator. If a NULL character is imbedded, CEEENV will truncate the value string at the last character preceding the NULL.
Examples
- Following is an example of CEEENV called by C/C++.
/*Module/File Name: EDCENV */ /*********************************************************************/ /* */ /* THIS EXAMPLE CALLS CEEENV TO CLEAR THE ENVIRONMENT VARIABLE */ /* ARRAY, SET AN ENVIRONMENT VARIABLE AND THEN GET THE VARIABLE */ /* FROM THE ARRAY. */ /* */ /*********************************************************************/ #include <stdio.h> #include <stdlib.h> #include <leawi.h> int main(void) { _INT4 func_code; _INT4 name_len; _POINTER name = (_POINTER)malloc(255); _INT4 value_len; _POINTER value_ptr; _FEEDBACK fc; char value[255]; /* Clearing all the environment variables */ func_code = 3; CEEENV(func_code,name_len,name,value_len,value_ptr,fc); /* Setting a new environment variable */ func_code = 2; strcpy(name,"ENVAR1"); strcpy(value,"DEFAULT"); name_len = strlen(name); value_len = strlen(value); value_ptr = value; CEEENV(func_code,name_len,name,value_len,value_ptr,fc); /* Getting the value of the new variable */ func_code = 1; strcpy(name,"ENVAR1"); strcpy(value,""); value_ptr = value; CEEENV(func_code,name_len,name,value_len,value_ptr,fc); if (value_len != 0) printf("$%s=%s\n",name,value_ptr); else printf("$%s not found\n",name); } - Following is an example of CEEENV called by COBOL.
CBL LIB,QUOTE **************************************************************** *Module/File Name: IGZTENV **************************************************************** ** Function: CEEENV - Process environment variables * ** * ** This example calls CEEENV to clear the environment * ** variable array, set an environment variable and then get * ** the variable from the array. * ** * **************************************************************** IDENTIFICATION DIVISION. PROGRAM-ID. IGZTENV. DATA DIVISION. WORKING-STORAGE SECTION. 01 FUNCCODE PIC 9(9) BINARY. 01 NAMELEN PIC 9(9) BINARY. 01 VALUELEN PIC 9(9) BINARY. 01 NAME PIC X(255). 01 VALPTR POINTER. 01 FC. 02 CONDITION-TOKEN-VALUE. COPY CEEIGZCT. 03 CASE-1-CONDITION-ID. 04 SEVERITY PIC S9(4) BINARY. 04 MSG-NO PIC S9(4) BINARY. 03 CASE-SEV-CTL PIC X. 03 FACILITY-ID PIC XXX. 02 I-S-INFO PIC S9(9) BINARY. 01 VAL PIC X(255). LINKAGE SECTION. 01 VAR PIC X(5000). PROCEDURE DIVISION. MAIN-PROG. ************************************************* ** Clear environment array ************************************************* MOVE 3 TO FUNCCODE. CALL "CEEENV" USING FUNCCODE, NAMELEN, NAME, VALUELEN, VALPTR, FC. ************************************************* ** Set an environment variable ************************************************* MOVE 2 TO FUNCCODE. MOVE "ENVAR1" TO NAME. MOVE "DEFAULT" TO VAL. MOVE 6 TO NAMELEN. MOVE 7 TO VALUELEN. SET VALPTR TO ADDRESS OF VAL. CALL "CEEENV" USING FUNCCODE, NAMELEN, NAME, VALUELEN, VALPTR, FC. ************************************************* ** Get the environment variable ************************************************* MOVE 1 TO FUNCCODE. MOVE " " TO VAL. MOVE 0 TO VALUELEN. CALL "CEEENV" USING FUNCCODE, NAMELEN, NAME, VALUELEN, VALPTR, FC. IF VALUELEN NOT = 0 THEN SET ADDRESS OF VAR TO VALPTR DISPLAY NAME(1:NAMELEN) "=" VAR(1:VALUELEN) ELSE DISPLAY NAME " NOT FOUND" END-IF. GOBACK. - Following is an example of CEEENV called by PL/I.
*PROCESS MACRO; /***************************************************/ /*Module/File Name: IBMENV */ /*******************************************************************/ /** **/ /** Function: CEEENV - process environment variables **/ /** **/ /** This example calls CEEENV to clear the environment variable **/ /** array, set an environment variable and then get the variable **/ /** from the array. **/ /** **/ /*******************************************************************/ PLIENV: PROCEDURE OPTIONS (MAIN) REORDER; %INCLUDE CEEIBMAW; %INCLUDE CEEIBMCT; DECLARE FUNC_CODE REAL FIXED BINARY(31,0); DECLARE NAME_LEN REAL FIXED BINARY(31,0); DECLARE VALUE_LEN REAL FIXED BINARY(31,0); DECLARE NAME CHAR(255) INIT(''); DECLARE VALUE CHAR(255) INIT(''); DECLARE VALUE2 CHAR(255) BASED(VALUE_PTR); DECLARE VALUE_PTR POINTER; DECLARE 01 LE_FEEDBACK_CODE, 03 MSGSEV REAL FIXED BINARY(15,0), 03 MSGNO REAL FIXED BINARY(15,0), 03 FLAGS, 05 CASE BIT(2), 05 SEVERITY BIT(3), 05 CONTROL BIT(3), 03 FACID CHAR(3), 03 ISI REAL FIXED BINARY(31,0); DECLARE MSG_STRING CHAR(255) VARYING; DECLARE MSG_DEST REAL FIXED BINARY(31,0); DECLARE SUBSTR BUILTIN; DECLARE SYSPRINT FILE PRINT; MSG_DEST = 2; /***************************************/ /* Clear all the environment variables */ /***************************************/ FUNC_CODE = 3; CALL CEEENV(FUNC_CODE, NAME_LEN, NAME, VALUE_LEN, VALUE_PTR, LE_FEEDBACK_CODE); /***************************************/ /* Set an environment variable */ /***************************************/ FUNC_CODE = 2; NAME = 'ENVAR1'; VALUE = 'DEFAULT'; VALUE_PTR = ADDR(VALUE); NAME_LEN = 6; VALUE_LEN = 7; CALL CEEENV(FUNC_CODE, NAME_LEN, NAME, VALUE_LEN, VALUE_PTR, LE_FEEDBACK_CODE); /***************************************/ /* Get the variable, to see if added */ /***************************************/ FUNC_CODE = 1; NAME = 'ENVAR1'; VALUE = ''; NAME_LEN = 6; VALUE_LEN = 0; CALL CEEENV(FUNC_CODE, NAME_LEN, NAME, VALUE_LEN, VALUE_PTR, LE_FEEDBACK_CODE); IF VALUE_LEN ^= 0 THEN DO; MSG_STRING = SUBSTR(NAME,1,NAME_LEN) || '=' || SUBSTR(VALUE2,1,VALUE_LEN); PUT SKIP LIST(MSG_STRING); END; ELSE DO; MSG_STRING = 'SET REQUEST UNSUCCESSFUL'; PUT SKIP LIST(MSG_STRING); END; END PLIENV;