Qp0zPutSysEnv()--Change or Add a System-Level Environment Variable

#include <qp0z1170.h>

int Qp0zPutSysEnv(const char *string, int ccsid,
                  void *reserved);

Qp0zPutSysEnv() function sets the value of a system-level 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.

reserved

(Input) Reserved for future use. Currently, the only allowed value is NULL.

Authorities

*JOBCTL special authority is required to add or change a system-level environment variable.

Return Value

0

Qp0zPutSysEnv() was successful.

errval

Qp0zPutSysEnv() was not successful. errval is set to indicate the error.

Error Conditions

If Qp0zPutSysEnv() is not successful, errval indicates one of the following errors.

[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 parameter was not in the correct format or the value for the reserved parameter was not NULL.

[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 system-level environment variables.)

[EOPNOTSUPP]

Operation not supported.

The operation, though supported in general, is not supported for the requested object or the requested arguments.

This error is returned if the environment variable that is being added is QIBM_CHILD_JOB_SNDINQMSG. See spawn() in or spawnp() in for details on QIBM_CHILD_JOB_SNDINQMSG.

[EPERM]

Operation not permitted.

You must have appropriate privileges or be the owner of the object or other resource to do the requested operation.

You must have *JOBCTL special authority to add or change system-level environment variables.

[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. 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
• Qp0zGetEnv()--Get Value of Environment Variable (Extended)
• Qp0zGetSysEnv()--Get Value of System-Level Environment Variable
• Qp0zInitEnv()--Initialize Environment for Variables
• Qp0zPutEnv()--Change or Add Environment Variable (Extended)

Example

The following example uses Qp0zPutSysEnv(), Qp0zGetSysEnv(), and Qp0zDltSysEnv().

#include <stdio.h>
#include <errno.h>
#include <stdlib.h>
#include <qp0z1170.h>

int main(int argc, char **argv)
{
 char     *var1  = "PATH=/:/home";
 char     *name1 = "PATH";
 char     *val1  = NULL;
 int      rc, ccsid, size;

 /* Add the system-level variable PATH */
 /* using default ccsid                */
 ccsid = 0;
 rc = Qp0zPutSysEnv(var1, ccsid, NULL);
 if(rc != 0)
 {
   printf("Error from Qp0zPutSysEnv while adding <%s>\n",var1);
   printf("errno = %d\n",rc);
   return rc;
 }

 printf("<%s> added to system-level env var list\n",var1);

 /* Get the value of the variable PATH */
 size = 100;
 val1 = (char *)malloc(size);

 rc = Qp0zGetSysEnv(name1, val1, &size, &ccsid, NULL);
 if(rc == ENOSPC)
 {
  /* The buffer size was not enough to get the value */
  /* Increase the buffer to size                     */
  val1 = (char *)realloc(val1, size);
  rc = Qp0zGetSysEnv(name1, val1, &size, &ccsid, NULL);
 }

 if(rc != 0)
 {
  printf("Error from Qp0zGetSysEnv while retrieving");
  printf("<%s>, errno = %d\n", name1, rc);
  return rc;
 }

 printf("<%s> retrieved, value is <%s>\n",name1,val1);

 /* Delete the PATH variable */
 rc = Qp0zDltSysEnv(name1, NULL);
 if(rc != 0)
 {
  printf("Error from Qp0zDltSysEnv while deleting");
  printf("<%s>, errno = %d\n", name1, rc);
  return rc;
 }

 printf("<%s> deleted from system-level env var list\n",name1);

 return 0;
}

Output:

 <PATH=/:/home> added to system-level variable list
 <PATH> retrieved, value is </:/home>
 <PATH> deleted from system-level variable list

For other examples, see the two-part example in Appendix A for saving and restoring system-level environment variables.