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

 #include <qp0z1170.h>

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

The Qp0zPutEnv() function is an IBM^® i 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.

Authorities and Locks

None.

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

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.

[EINVAL]

The value specified for the argument is not correct.

A function was passed incorrect argument values, or an operation was attempted on an object and the operation specified is not supported for that type of object.

An argument value is not valid, out of range, or NULL. 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.

[ Back to top | UNIX-Type APIs | APIs by category ]