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 |