Add Environment Variable (ADDENVVAR)

Where allowed to run: All environments (*ALL)
Threadsafe: Yes
Parameters
Examples
Error messages

The Add Environment Variable (ADDENVVAR) command adds an environment variable consisting of a character string in the form 'environment variable name=environment variable value'. Environment variables can be used, for example, to specify configuration values to application programs on systems that are compliant with the Single UNIX Specification.

If you are not ready to set the environment variable value, you can use this command to add an environment variable with a null value. You can then use the Add Environment Variable (ADDENVVAR) or Change Environment Variable (CHGENVVAR) command to associate the environment value with the environment variable name.

Restriction: You must have *JOBCTL special authority to use this command to add system-level environment variables.

Top

Parameters

Keyword Description Choices Notes
ENVVAR Environment variable Character value Required, Positional 1
VALUE Initial value Character value, *NULL Optional, Positional 2
CCSID Coded character set ID 1-65535, *JOB, *HEX Optional, Positional 3
LEVEL Level *JOB, *SYS Optional
REPLACE Replace existing entry *NO, *YES Optional
Top

Environment variable (ENVVAR)

Specifies the name of the environment variable to be added. If an environment variable by this name currently exists at the specified level (LEVEL parameter), error message CPFA980 is issued, unless the REPLACE(*YES) option is used, in which case the variable is set to the new value specified.

ADDENVVAR limits environment variable name to a maximum of 128 bytes in length. Valid values include all EBCDIC characters except the equal sign (=), the null-terminator (X'00') and blank (X'40'). The name must be enclosed in apostrophes if it contains any non-alphanumeric character. If an apostrophe is intended, two apostrophes must be used ('').

Note: The case is preserved when lowercase characters are specified.

This is a required parameter.

Top

Initial value (VALUE)

Specifies the environment variable value.

The possible values are:

*NULL
The value of the environment variable is the null character (X'00').
environment-variable-value
Specify the value of the environment variable. ADDENVVAR limits value to a maximum of 1024 bytes in length. Valid values include all EBCDIC characters. The value must be enclosed in apostrophes if it contains any non-alphanumeric character or blanks. If an apostrophe is intended, two apostrophes must be used ('').

Note: The case is preserved when lowercase characters are specified.

Top

Coded character set ID (CCSID)

Specifies the coded character set identifier (CCSID) of the text supplied on the ENVVAR and the VALUE parameters. This value is stored with the environment variable.

The possible values are:

*JOB
The CCSID of the text is assumed to be the CCSID of the job running this command.
*HEX
The CCSID of 65535 is stored with this environment variable.
coded-character-set-identifier
Specify the CCSID to be stored with the environment variable. Valid values range from 1 through 65535.
Top

Level (LEVEL)

Specifies the level of the environment variable.

The possible values are:

*JOB
This is a job-level environment variable.
*SYS
This is a system-level environment variable.
Top

Replace existing entry (REPLACE)

Specifies whether the value of an existing environment variable should be reset to the new value.

The possible values are:

*NO
Do not replace. If an environment variable with the specified name (ENVVAR parameter) exists at the specified level (LEVEL parameter), error message CPFA980 is issued.
*YES
Replace. If an environment variable with the specified name (ENVVAR parameter) exists at the specified level (LEVEL parameter), its value will be replaced by the new value.
Top

Examples

Example 1: Add an Environment Variable with CCSID 37

ADDENVVAR   ENVVAR(altdir)  VALUE('/mydir/dir2') CCSID(37)

This command adds the environment variable named altdir with the value /mydir/dir2 to the environment variables for the job. The value 37 is stored with the environment variable to indicate its CCSID.

Example 2: Set an Environment Variable to Null

ADDENVVAR   ENVVAR(LIBPATH)  VALUE(*NULL)

This command adds the environment variable named LIBPATH with the null (x'00) character value to the environment variables for the job.

Example 3: Add a System-level Environment Variable

ADDENVVAR   ENVVAR(homedir)  VALUE('/home')  LEVEL(*SYS)

This command adds a system-level environment variable named homedir with value /home.

Example 4: Reset a Job-level Environment Variable

ADDENVVAR   ENVVAR(altdir)  VALUE('/mydir/dir3')  REPLACE(*YES)

This command replaces the existing value of the variable altdir with the new value of /mydir/dir3.

Top

Error messages

*ESCAPE Messages

CPFA980
Environment variable name exists.
CPFA982
ENVVAR character not valid.
CPFA983
Unexpected error occurred.
CPFA984
Maximum number of environment variables exist.
CPFA98E
*JOBCTL special authority required to update system-level environment variables.
CPF3BCA
CCSID &1 not supported.
Top