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 ('').

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 ('').

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