|
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;
|