Troubleshooting
Problem
This note describes environment variables and explains commands used to provide their definition and support.
Resolving The Problem
Environment variables are character strings of the form name=value that are stored in an environment space outside of the program. The strings are stored in a temporary space associated with the job.
Environment variables on the operating system are provided to support X/Open single UNIX specification (formerly Spec 1170) environment parameters for a job. The operating system allows 1024 environment variables per job. The variables are scoped to the environment of the active job. The Add Environment Variable (ADDENVVAR) command provides documentation for setting environment variables within a job. The system API Reference manual contains a section for Environment Variables APIs.
Environment variables have the following characteristics:
There is no default set of environment variables when a job starts.
Environment variables are extended to a new job created using the submit job (SBMJOB) command, provided the submitting job has environment variables.
The temporary space where the environment variables are stored allows read and write access. Therefore, it is possible for the space to be corrupted. This could occur if a programmer accesses the space directly rather than using the environment variables APIs.
Environment variables are used primarily for jobs which run under QSHELL (AS/400 UNIX Shell support) or Java. Read the API documentation to determine the variables that are respected by each support group. A common variable across both is the PATH environment variable. This variable provides a mechanism to identify to a job the various paths which can be searched by the application to resolve to a path object (File, sub-directory or symbolic link).
The analogy of a directory path list is the library list for the job. In a UNIX or POSIX environment, jobs contain paths for locating objects (files and/or sub-directory). Unfortunately, operating system job structure does not provide a means for resolving what paths have been set for object resolution. The system resolves paths based on the current directory for the job. By circumvention, the path environment variable can be used to set the current directory for a job. The following environment variable commands provide a mechanism for doing this:
Environment variables on the operating system are provided to support X/Open single UNIX specification (formerly Spec 1170) environment parameters for a job. The operating system allows 1024 environment variables per job. The variables are scoped to the environment of the active job. The Add Environment Variable (ADDENVVAR) command provides documentation for setting environment variables within a job. The system API Reference manual contains a section for Environment Variables APIs.
Environment variables have the following characteristics:
There is no default set of environment variables when a job starts.
Environment variables are extended to a new job created using the submit job (SBMJOB) command, provided the submitting job has environment variables.
The temporary space where the environment variables are stored allows read and write access. Therefore, it is possible for the space to be corrupted. This could occur if a programmer accesses the space directly rather than using the environment variables APIs.
Environment variables are used primarily for jobs which run under QSHELL (AS/400 UNIX Shell support) or Java. Read the API documentation to determine the variables that are respected by each support group. A common variable across both is the PATH environment variable. This variable provides a mechanism to identify to a job the various paths which can be searched by the application to resolve to a path object (File, sub-directory or symbolic link).
The analogy of a directory path list is the library list for the job. In a UNIX or POSIX environment, jobs contain paths for locating objects (files and/or sub-directory). Unfortunately, operating system job structure does not provide a means for resolving what paths have been set for object resolution. The system resolves paths based on the current directory for the job. By circumvention, the path environment variable can be used to set the current directory for a job. The following environment variable commands provide a mechanism for doing this:
| o | ADDENVVAR - Add Environment Variable command |
| o | CHGENVVAR - Change Environment Variable command |
| o | WRKENVVAR - Work Environment Variable command |
The following is information associated with a job's environment variable.
| 1. | The variable can be set using the ADDENVVAR command or the PUTENV API. There is no reasonable limit to the size of an environment variable when set by the PUTENV API. |
| 2. | The variable can be changed using the CHGENVVAR command or the PUTENV API. |
| 3. | There is an INITENV API which will initialize an environment variable. |
| 4. | The scope of the variable is the job and the environment in which the job will run. An environment variable may be set in a remote OS/400 job via programming controls. Here is how: Create a program which sets an environment variable. When the job is activated, issue a call to the program. This will cause the environment variable to be set under the correct job. See example at the end of this note. |
| 5. | A job may have 1024 environment variables. |
| 6. | The environment variable of a job may be displayed via the WRKENVVAR command. |
| 7. | The environment variable is CCSID sensitive. The default CCSID is *JOB. |
Environment variables for a batch job could be defined accordingly:
//BCHJOB JOBD(PATHLIB/PATHJOBD)
ADDENVVAR ENVVAR(PATH) VALUE('/QIBM/PRODDATA/LOTUS/NOTES:/QIBM/USE RDATA/LOTUS/NOTES:/anypath/NOTES/DATA')
CALL PGM(PATHLIB/PATHPGM) PARM('/bashir7/notes/data/names.nsf')
Alternately, you could submit a job and set its environment via the following command. Note that environment variables would have to be set prior to running this command.
Create a program that will set the program variable. We will call this program pathlib/setenvvar. The set environment variable program would be passed two parameters. One is the name of a user space which contains the environment variables. The second parameter would be the call parameters for the program pathlib/pathpgm. In this example, the following could be done to set a path environment variable and pass control to program pathlib/pathpgm.
SBMJOB CMD(CALL PGM(pathlib/setenvvar) PARM(usrspcnam ('/Bashir7/notes/data/admin.nsf'))) JOB(*JOBD) JOBD(PATHLIB/PATHJOBD) USER(USRPATH) CPYENVVAR(*YES)
The parameter, usrspcnam, is the qualified name of a user space that contains the path environment variables. The path list would be set in the user space via the user space APIs documented in the User Space API section of the System API Manual. The APIs are:
QUSCRTUS - Create User Space
QUSCHGUS - Change User Space
QUSDLTUS - Delete User Space
QUSPTRUS - Retrieve pointer to User Space
QUSRTVUS - Retrieve User Space
//BCHJOB JOBD(PATHLIB/PATHJOBD)
ADDENVVAR ENVVAR(PATH) VALUE('/QIBM/PRODDATA/LOTUS/NOTES:/QIBM/USE RDATA/LOTUS/NOTES:/anypath/NOTES/DATA')
CALL PGM(PATHLIB/PATHPGM) PARM('/bashir7/notes/data/names.nsf')
Alternately, you could submit a job and set its environment via the following command. Note that environment variables would have to be set prior to running this command.
Create a program that will set the program variable. We will call this program pathlib/setenvvar. The set environment variable program would be passed two parameters. One is the name of a user space which contains the environment variables. The second parameter would be the call parameters for the program pathlib/pathpgm. In this example, the following could be done to set a path environment variable and pass control to program pathlib/pathpgm.
SBMJOB CMD(CALL PGM(pathlib/setenvvar) PARM(usrspcnam ('/Bashir7/notes/data/admin.nsf'))) JOB(*JOBD) JOBD(PATHLIB/PATHJOBD) USER(USRPATH) CPYENVVAR(*YES)
The parameter, usrspcnam, is the qualified name of a user space that contains the path environment variables. The path list would be set in the user space via the user space APIs documented in the User Space API section of the System API Manual. The APIs are:
QUSCRTUS - Create User Space
QUSCHGUS - Change User Space
QUSDLTUS - Delete User Space
QUSPTRUS - Retrieve pointer to User Space
QUSRTVUS - Retrieve User Space
A sample program is provided in the knowledge center on how to display an environment variable and change the variable to a new value in a program:
[{"Type":"MASTER","Line of Business":{"code":"LOB68","label":"Power HW"},"Business Unit":{"code":"BU070","label":"IBM Infrastructure"},"Product":{"code":"SWG60","label":"IBM i"},"ARM Category":[{"code":"a8m0z0000000CHjAAM","label":"Job and Work Management"}],"ARM Case Number":"","Platform":[{"code":"PF012","label":"IBM i"}],"Version":"All Versions"}]
Historical Number
13584851
Was this topic helpful?
Document Information
More support for:
IBM i
Component:
Job and Work Management
Software version:
All Versions
Operating system(s):
IBM i
Document number:
642515
Modified date:
01 April 2025
UID
nas8N1018267
Manage My Notification Subscriptions