Qp0zPutEnv()--Change or Add Environment Variable (Extended)

#include <qp0z1170.h>

int Qp0zPutEnv(const char *string, int ccsid);

The Qp0zPutEnv() function is an OS/400 extension to the standard putenv() function. Qp0zPutEnv() sets the value of an environment variable by altering an existing variable or creating a new variable. In addition, it specifies a CCSID (coded character set identifier) to be associated with the environment variable.

The string parameter points to a string of the form name=value, where name is the environment variable and value is the new value for it.

The name cannot contain a blank. For example,

   PATH NAME=/my_lib/joe_user

is not valid because of the blank between PATH and NAME. The name can contain an equal (=) symbol, but the system interprets all characters following the first equal symbol as being the value of the environment variable. For example,

   PATH=NAME=/my_lib/joe_user

will result in a value of 'NAME=/my_lib/joe_user' for the variable PATH.

Parameters

string

(Input) A pointer to the name=value string.

ccsid

(Input) A CCSID to be associated with this environment variable. If 0 is specified, the default CCSID for the job is used.

Return Value

0

Qp0zPutEnv() was successful.

-1

Qp0zPutEnv() was not successful. The errno variable is set to indicate the error.

Error Conditions

If Qp0zPutEnv() is not successful, errno indicates one of the following errors.

[EDAMAGE]

A damaged object was encountered.

A referenced object is damaged. The object cannot be used.

[EFAULT]

The address used for an argument is not correct.

In attempting to use an argument in a call, the system detected an address that is not valid.

While attempting to access a parameter passed to this function, the system detected an address that is not valid.

[ERROR_INVALID_PARAMETER]

An invalid parameter was found.

A parameter passed to this function is not valid.

For example, the string may not be in the correct format.

[ENOMEM]

Storage allocation request failed.

A function needed to allocate storage, but no storage is available.

There is not enough memory to perform the requested function. (There is a limit of 4095 environment variables per job.)

[EUNKNOWN]

Unknown system state.

The operation failed because of an unknown system state. See any messages in the job log and correct any errors that are indicated, then retry the operation.

Usage Notes

1. Although Qp0zPutEnv() is threadsafe, if a thread calls an environment variable function while another thread is accessing an environment variable from the environ array the thread may see undefined results. The environ array can be accessed directly or by using a pointer returned from the getenv() or Qp0zGetEnv() functions. The environment contents are only protected during calls to the environment variable functions.

2. No translation is done based on the CCSID. The CCSID is just stored and retrieved as an integer value associated with each environment variable.

Related Information

• The <qp0z1170.h> file (see Header Files for UNIX-Type Functions)
• getenv()--Get Value of Environment Variable
• putenv()--Change or Add Environment Variable
• Qp0zDltEnv()--Delete an Environment Variable
• Qp0zDltSysEnv()--Delete a System-Level Environment Variable
• Qp0zGetAllSysEnv()--Get All System-Level Environment Variables
• Qp0zGetSysEnv()--Get Value of System-Level Environment Variable
• Qp0zInitEnv()--Initialize Environment for Variables
• Qp0zPutSysEnv()--Change or Add a System-Level Environment Variable

Example

See the example of using putenv() in putenv()--Change or Add Environment Variable.