Environment Variable APIs

Environment variables are character strings of the form "name=value". There are two types of environment variables:

• Job-level environment variables. The job-level environment variables are stored in an environment space outside of the program associated with the job. They can be manipulated by using the getenv(), putenv(), Qp0zDltEnv(), Qp0zGetEnv(), Qp0zInitEnv(), and Qp0zPutEnv() APIs, as well as the CL commands ADDENVVAR, CHGENVVAR, RMVENVVAR, and WRKENVVAR. These variables exist for the duration of the job or until they are deleted. There is a limit of 4095 job-level environment variables.
  
  
• System-level environment variables. The system-level environment variables are stored in a global environment space that is persistent across IPLs and is not associated to a particular job. They can be manipulated by using the Qp0zDltSysEnv(), Qp0zGetAllSysEnv(), Qp0zGetSysEnv(), and Qp0zPutSysEnv() APIs, as well as the CL commands ADDENVVAR, CHGENVVAR, RMVENVVAR, and WRKENVVAR. These variables exist until they are deleted. There is a limit of 4095 system-level environment variables.

When a job calls one of the job-level environment variable APIs or CL commands for the first time, it inherits the system-level environment variables onto its job-level environment space. Any changes to job-level and system-level environment variables are then independent of one another.

The temporary space where the job-level 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 using the environ array rather than using the environment variable APIs. If the space is corrupted, subsequent calls using the APIs will have unpredictable results.

The environment variable APIs are:

• getenv() (Get value of environment variable) searches the job-level environment list for a string of the form name=value, where name is the environment variable and value is the value of the variable.
• putenv() (Change or add environment variable) sets the value of a job-level environment variable by changing an existing variable or creating a new one.
• Qp0zDltEnv() (Delete an environment variable) deletes a single job-level environment variable or deletes all environment variables from the current job.
• Qp0zDltSysEnv() (Delete a system-level environment variable) deletes a single system-level environment variable or deletes all system-level environment variables.
• Qp0zGetAllSysEnv() (Get all system-level environment variables) fills in the list_buf with a list of all the system-level environment variables.
• Qp0zGetEnv() (Get value of environment variable (extended)) is an i5/OS extension to the standard getenv() function.
• Qp0zGetSysEnv() (Get value of system-level environment variable) gets the value of a system-level environment variable name by searching the system-level environment variable list for a string of the form name=value.
• Qp0zInitEnv() (Initialize environment for variables) sets the external variable environ to a pointer to the current environment list.
• Qp0zPutEnv() (Change or add environment variable (extended)) is an i5/OS extension to the standard putenv() function.
• Qp0zPutSysEnv() (Change or add a system-level environment variable) sets the value of a system-level environment variable by altering an existing variable or creating a new variable.

Note: These functions use header (include) files from the library QSYSINC, which is optionally installable. Make sure QSYSINC is installed on your system before using any of the functions. See Header Files for UNIX-Type Functions for the file and member name of each header file.