Qp0zGetEnv()--Get Value of Environment Variable (Extended)

Syntax

 #include <qp0z1170.h>

 char *Qp0zGetEnv(const char *name, int *ccsid);

  Service Program Name: QP0ZCPA

  Default Public Authority: *USE

  Threadsafe: Yes. See Usage Notes for more information.

The Qp0zGetEnv() function is an IBM^® i extension to the standard getenv() function. Qp0zGetEnv() searches the job-level environment list for a string of the form name=value. The value and the CCSID (coded character set identifier) associated with the environment variable name are returned.

Authorities and Locks

None.

Parameters

name: (Input) The name of an environment variable.
ccsid: (Output) The CCSID for the named environment variable.

Return Value

value	Qp0zGetEnv() successfully found the environment string. The value returned is a pointer to the string containing the `value` for the specified `name` in the current environment.
NULL	Qp0zGetEnv() could not find the environment string. The errno variable is set to indicate the error.

Error Conditions

If Qp0zGetEnv() 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.

[ENOENT]

No such path or directory.

The directory or a component of the path name specified does not exist.

A named file or directory does not exist or is an empty string.

No entry found for name specified.

[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

Although Qp0zGetEnv() 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.
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
Qp0zPutEnv()--Change or Add Environment Variable (Extended)
Qp0zPutSysEnv()--Change or Add a System-Level Environment

Example

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

API introduced: V3R6

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