Using environment variables

This topic describes environment variables that affect the z/OS® XL C/C++ environment. You can use environment variables to define the characteristics of a specific environment. They may be set, retrieved, and used during the execution of a z/OS XL C/C++ program.

The following environment variables affect the z/OS XL C/C++ environment if they are on when an application program runs. The variables that begin with _EDC_ and _CEE_ are described in detail in Environment variables specific to the z/OS XL C/C++ library. See Locale source files for more information on the locale-related environment variables.

Note: The settings of these variables affect your environment even if you are using the C++ I/O stream classes. For more detailed information on I/O streaming and the Standard C++ I/O stream classes, see Standard C++ Library Reference. For information on environment variables used in z/OS UNIX System Services, see z/OS UNIX System Services Command Reference and z/OS UNIX System Services User's Guide.

_BIDIATTR

Used to specify the attributes which will determine the way the bidirectional layout transformation takes place, as shown in the following example. If _BIDIATTR is not specified or contains erroneous values, the default values will be used. For a detailed description of the bidirectional layout transformation, see Bidirectional language support.

export _BIDIATTR="@ls typeoftext=visual:implicit, orientation=ltr:ltr,
     numerals=nominal:national"

_BIDION

Used to specify if iconv will perform bidirectional layout transformation beside the basic main function (code page conversion). The value of this variable is either set to TRUE to activate the bidirectional layout transformation, or FALSE to prevent the bidirectional layout transformation. If this variable is not defined in the environment it defaults to FALSE.

_BPXK_AUTOCVT

Activates or deactivates automatic text conversion of tagged UNIX file system files. The value of this environment variable is interrogated during initialization of the C main(), and at each pthread initialization in order to set the autoconversion state for the thread. The autoconversion state for the thread is looked at by the logical file system (LFS) when determining if automatic text conversion should be performed during read/write operations to tagged UNIX file system files.

The default autoconversion state is unset, meaning that the LFS must look to the BPXPRMxx AUTOCVT parameter, which is ON, OFF, or ALL. When set to a valid value, this environment variable overrides the BPXPRMxx AUTOCVT parameter.

Restriction: When _BPXK_AUTOCVT is ON, automatic conversion can only take place between IBM-1047 and ISO8859-1 code sets. Other CCSID pairs are not supported for automatic text conversion. To request automatic conversion for any CCSID pairs that Unicode service supports, set _BPXK_AUTOCVT to ALL.

During main() initialization, the following behavior is defined for this environment variable:

Setting: Autoconversion State for the Thread
ON: Activates the automatic conversion of tagged files for Enhanced ASCII. This affects conversion for I/O for regular, pipe, and character special files that are tagged.
OFF: Deactivates the automatic conversion of tagged files.
ALL: Activates the automatic conversion of tagged files that are supported by z/OS UNICODE. This affects conversion for I/O for regular and pipe files that are tagged. If the conversion is between EBCDIC and ASCII, it also affects conversion for I/O for character special files.
<other>: Treated as unset. Autoconversion defers to BPXPRMxx AUTOCVT parameter.

Changing the value of this environment variable using setenv(), putenv(), or clearenv() during execution of the application will behave in the following manner:

Ignored after the first pthread create, although getenv() might show otherwise. The autoconversion state will remain unchanged.
Deleting or clearing the environment variable, or setting the value to an invalid value before the first pthread create will change the autoconversion state to unset.
Has no effect on initially untagged UNIX file system files that have already been opened using fopen() or freopen() on the current thread and FILETAG(AUTOCVT,) is in effect. These files were specifically marked, or not marked, for automatic text conversion, at the file descriptor level, at the time they were opened. The text conversion state for the already opened file descriptors depended on whether or not autoconversion for the thread was activated or deactivated at the time of the open.
The standard streams may have already been setup for automatic text conversion, before the main() begins execution, using EBCDIC CCSID 1047 as the File CCSID. Therefore, changing the autoconversion state using one of these methods will not affect the standard streams. Specifically, an application running with ASCII CCSID 819 as the Program CCSID will continue to have text conversion with the standard streams.

Changing the value of this environment variable using any other mechanism is ignored, although getenv() might show otherwise. You can use setenv() with a value of NULL to delete an environment variable.

_BPXK_CCSIDS

Defines the EBCDIC<->ASCII pair of coded character set IDs (CCSIDS) to be used when converting text data, and for automatic tagging new or empty UNIX file system files. The syntax of the environment variable value is as follows, where e is the EBCDIC CCSID and a is the ASCII CCSID.

_BPXK_CCSIDS=(e,a)

Language Environment C/C++ applications will initialize with the default IBM-1047<->ISO8859-1 pair. This is equivalent to specifying: _BPXK_CCSIDS=(1047,819) before running the application.

The value of this environment variable is interrogated during initialization of the C main(), and at each pthread initialization in order to set the Program CCSID for the thread. For the main(), the Program CCSID is set to the ASCII value of the pair when the main() is part of an ASCII compile unit, otherwise it is set to the EBCDIC value of the pair. The Program CCSID for a thread is set based on the compiled codeset of the thread start routine. When ASCII, the ASCII value of the CCSID pair is used, else the EBCDIC value.

Note: Starting from z/OS V2R1, environment variable _BPXK_PCCSID is introduced to represent Program CCSID. The behavior of _BPXK_CCSIDS of the existing programs will not be affected unless _BPXK_PCCSID is set. If both _BPXK_CCSIDS and _BPXK_PCCSID are set before a program runs, _BPXK_PCCSID is used as the initial value of program CCSID. When a program is running, the CCSID of a thread can be affected by calling setenv() or putenv() with either of the two environment variables.

Changing the value of this environment variable using setenv(), putenv(), or clearenv() during execution of the application will behave in the following manner:

Ignored after the first pthread create, although getenv() might show otherwise. The current CCSID pair used for conversion & tagging purposes will remain unchanged.
Deleting or clearing the environment variable before the first pthread create will result in the default CCSID pair (1047,819) being used for conversion and tagging purposes.
Using improper syntax before the first pthread create will result in the CCSID pair being set to (0,0). This will prevent any further conversion.
Has no effect on initially untagged new or empty UNIX file system files that have already been opened using fopen(), fropen(), or popen() on the current thread and FILETAG(,AUTOTAG) is in effect. These files were setup for tagging upon first write at the time they were opened. The File CCSID was set to what the Program CCSID was at the time of the open.
The standard streams may have already been setup for automatic text conversion, before the main() begins execution, using EBCDIC CCSID 1047 as the File CCSID, therefore changing the CCSID pair using one of these methods will not affect the standard streams.

Note: Changing the value of this environment variable using any other mechanism is ignored, although getenv() might show otherwise. You can use setenv() with a value of NULL to delete an environment variable.

_BPXK_PCCSID

Identifies the program CCSID for the running thread or user. It can be used to override the internal default of 1047 (EBCDIC). Any value between 0 and 65535 can be assigned. However, to avoid any subsequent errors, only values that are supported by Unicode Services can be used. Setting or unsetting this variable has no effect when translation for a file has started. When unset, the internal value of the program CCSID reverts back to the default of 1047.

_BPXK_SIGDANGER

Set to either YES or NO, this variable modifies the process termination mechanism used during UNIX System Services Shutdown. During Shutdown the kernel sends a signal to each non-permanent non-blocking process. If _BPXK_SIGDANGER is not in the environment, or if its value is not YES, then SIGTERM is sent to these processes. If _BPXK_SIGDANGER is present in the environment and has the value YES then signal SIGDANGER will be sent instead of SIGTERM. The default action for SIGTERM is to terminate the process, but the default action for SIGDANGER is to ignore the signal. The application may register a SIGDANGER signal catcher function to handle shutdowns. If the process does not end in a short while after being sent the first signal, the kernel will send SIGKILL to the process. If the process does not end in a short while after the second signal is sent, the process will be brought down using CALLRTM ABTERM=YES.

Note: The program should not use the environ external variable to put this or any other "_BPXK_" environment variable into its own environment. The Kernel will not be told about the environment variable setting when it is added to the environment this way. The program should use an environ pointer to put this variable into the environment of a new process created with spawn() or exec(). In this case the kernel will notice _BPXK_ environment variables being created for a new program image. In addition, the kernel will correctly detect _BPXK_ environment variables generated into child processes created via fork() and spawn().

_CEE_DLLLOAD_XPCOMPAT

Used to indicate whether certain 31 bit XPLINK DLL application initialization compatibility behaviors should be disabled.

_CEE_DMPTARG

Used to specify the directory in which Language Environment® dumps (CEEDUMPs) are written for applications that are running as the result of a fork, exec, or spawn. This environment variable is ignored if the application is not run as a result of a fork, exec, or spawn. Additionally _CEE_DMPTARG can be used to direct the CEEDUMPs output to a specific sysout class.

_CEE_ENVFILE

Used to specify a file from which to read environment variables.

_CEE_ENVFILE_COMMENT

Used to define the comment character to be checked for when z/OS XL C/C++ reads subsequent records from the file.

_CEE_ENVFILE_CONTINUATION

Used to define the continuation character to be checked for when z/OS XL C/C++ reads subsequent records from the file.

_CEE_ENVFILE_S

Used to specify a file from which to read environment variables, stripping trailing white space from each NAME=VALUE line read.

_CEE_HEAP_MANAGER

Used to specify the DLL name for the Vendor Heap Manager to be used during execution of the application.

_CEE_REALLOC_CONTROL

Used to specify the lower bound for the tolerance percentage to be applied and specify the percentage that the storage request will be increased if the request is greater than or equal to the lower bound specified.

_CEE_RUNOPTS

Used to specify Language Environment runtime options to a program invoked by using one of the exec functions, such as a program which is invoked from one of the z/OS UNIX shells.

_EDC_ADD_ERRNO2

Appends errno2 information to the output of perror() and strerror().

_EDC_ANSI_OPEN_DEFAULT

Affects the characteristics of MVS text files opened with the default attributes.

_EDC_AUTOCVT_BINARY

If automatic file conversion is enabled ( _BPXK_AUTOCVT=ON and running with FILETAG(AUTOCVT) runtime option), this environment variable activates or deactivates automatic conversion of untagged UNIX file system files opened in binary mode and not opened for record I/O.

_EDC_BYTE_SEEK

Specifies that fseek() and ftell() should use relative byte offsets.

_EDC_CLEAR_SCREEN

Affects the behavior of output text terminal files.

_EDC_COMPAT

Specifies that C/C++ should use specific functional behavior from previous releases of C/370™.

_EDC_CONTEXT_GUARD

Allows the user to control the method used to handle the guard page for AMODE 64 user context stacks.

_EDC_C99_NAN

Sets the binary floating-point representation behavior of infinite value and Not a Number for the printf family of functions

_EDC_DLL_DIAG

Indicates if additional DLL diagnostic information should be generated upon failure for the following DLL functions: dllload(), dlopen(), dllqueryfn(), dllqueryvar(), dlsym(), dllfree(), and dlclose() . _EDC_DLL_DIAG has no effect on implicit DLLs. If _EDC_DLL_DIAG is not set by the user, it will default to QUIET.

_EDC_EOVERFLOW

Sets the behavior of the ftell(), fseek(), fstat(), lstat(), stat(), and mmap() functions. By default these functions will not check for the EOVERFLOW error condition. Setting _EDC_EOVERFLOW to YES enables testing for this condition, and, if overflow is detected, setting errno to EOVERFLOW and returning an error.

_EDC_ERRNO_DIAG

Indicates if additional diagnostic information should be generated, when the perror() or strerror() functions are called to produce an error message.

_EDC_FLUSH_STDOUT_PIPE

Flushes the stdout stream when the stdin stream is being read. Both stdin and stdout must be pipes.

_EDC_FLUSH_STDOUT_SOCKET

Flushes the stdout stream when the stdin stream is being read. Both stdin and stdout must be sockets.

_EDC_GLOBAL_STREAMS

Allows the C standard streams stdin, stdout and stderr to have global behavior. _EDC_GLOBAL_STREAMS is not supported in AMODE 64.

_EDC_IEEEV1_COMPATIBILITY_ENV

Used to access original versions of the fdlibm functions when the value of _EDC_IEEEV1_COMPATIBILITY_ENV is set to ON.

_EDC_IO_ABEND

Controls if the runtime library should attempt to recover from an abend issued during OS I/O processing.

_EDC_IO_TRACE

Indicates which files to perform file I/O tracing on, the level of detail to provide for file I/O tracing, and the trace buffer size to use for each file.

_EDC_POPEN

Specifies that popen() uses spawn() instead of fork().

_EDC_PTHREAD_BACKOUT

Controls the behavior of threads in abnormal termination by determining whether to call Resource Recovery Services to backout in-flight units of recovery.

_EDC_PTHREAD_YIELD

Used to control when pthread_yield() and sched_yield() will allow a thread to give up control of a processor so that another thread may have the opportunity to run.

_EDC_PTHREAD_YIELD_MAX

Allows a user program to define the max yield (wait) time for a particular thread.

_EDC_PUTENV_COPY

Copies the putenv() string into storage owned by Language Environment.

_EDC_RRDS_HIDE_KEY

Relevant for VSAM RRDS files opened in record mode. Enables calls to fread() that specify a pointer to a character string and do not append the Relative Record Number to the beginning of the string.

_EDC_STOR_INCREMENT

Sets the size of increments to the internal library storage subpool acquired above the 16M line. _EDC_STOR_INCREMENT is not supported in AMODE 64 applications. In AMODE 64 applications, this environment variable is replaced by the IOHEAP64 runtime option.

_EDC_STOR_INCREMENT_B

Sets the size of increments to the internal library storage subpool acquired below the 16M line. _EDC_STOR_INCREMENT_B is not supported in AMODE 64 applications. In AMODE 64 applications, this environment variable is replaced by the IOHEAP64 runtime option.

_EDC_STOR_INITIAL

Sets the initial size of the internal library storage subpool acquired above the 16M line. _EDC_STOR_INITIAL is not supported in AMODE 64 applications. In AMODE 64 applications, this environment variable is replaced by the IOHEAP64 runtime option.

_EDC_STOR_INITIAL_B

Sets the initial size of the internal library storage subpool acquired below the 16M line. _EDC_STOR_INITIAL_B is not supported in AMODE 64 applications. In AMODE 64 applications, this environment variable is replaced by the IOHEAP64 runtime option.

_EDC_STRPTM_STD

Indicates changes to strptime() that are provided for UNIX standard compliance.

_EDC_SUSV3

Indicates behavioral changes that are provided for SUSV3 compliance in an error path. The affected interfaces are typically setting errno to values that were not used before and, in some cases, returning failure for conditions that had not been tested before SUSV3. By default the affected interfaces will not check for these conditions. When the value of _EDC_SUSV3 is set to 1, the SUSV3 behavior is enabled. When the value of _EDC_SUSV3 is set to 2, all the behaviors protected by _EDC_SUSV3=1 are exposed, and pole error related behaviors specified by SUSV3 will be enabled.

_EDC_UMASK_DFLT

Allows the user to control how the C library sets the default umask used when the program runs.

_EDC_ZERO_RECLEN

Enables processing of zero-length records in an MVS data set opened in variable format.

_ICONV_MODE

Selects the behavior mode for iconv_open(), iconv(), and iconv_close() family of functions.

_ICONV_TECHNIQUE

Determines the conversion technique used by Unicode Conversion Services. For more information regarding the Unicode conversion Services value, see z/OS Unicode Services User's Guide and Reference.

_ICONV_UCS2

Tells iconv_open(Y, X) what type of conversion method to setup when there is a choice between "direct" conversion from X to Y and "indirect" X to UCS-2 to Y. This variable is ignored when using Unicode Conversion Services.

_ICONV_UCS2_PREFIX

Tells iconv_open() what z/OS dataset name prefix to use to find UCS-2 tables if they cannot be found in the HFS. This variable is ignored when using Unicode Conversion Services.

LANG

Determines the locale to use for the locale categories when neither the LC_ALL environment variable nor the individual locale environment variables specify locale information. This environment variable does not interact with the language setting for messages.

LC_ALL

Determine the locale to be used to override any values for locale categories specified by the settings of the LANG environment variable or any individual locale environment variables.

LC_COLLATE

Determines the behavior of ranges, equivalence classes, and multicharacter collating elements.

LC_CTYPE

Determines the locale for the interpretation of byte sequences of text data as characters (for example, single-byte versus multibyte characters in arguments and input files).

LC_MESSAGES

Determines the language in which messages are to be written.

LC_MONETARY

Determines the locale category for monetary-related numeric formatting information.

LC_NUMERIC

Determines the locale category for numeric formatting (for example, thousands separator and radix character) information.

LC_TIME

Determines the locale category for date and time formatting information.

LC_TOD

Determines the locale category for time of day and Daylight Savings Time formatting information.

LIBPATH

Allows an absolute or relative pathname to be searched when loading a DLL. If the input filename contains a slash (/), it is used as is to locate the DLL. If the input filename does not contain a slash, then LIBPATH is used to determine the pathname to load. LIBPATH specifies a list of directories separated by colons. If the LIBPATH begins or ends with a colon, then the working directory is also searched first or last, depending on the position of the stand-alone colon. The "::" specification can only occur at the beginning or end of the list of directories. If you are running POSIX(ON), then UNIX file system is searched first followed by MVS. If you are running POSIX(OFF), then MVS is searched first followed by UNIX file system. This double search can be avoided by using unambiguous DLL names.

LOCPATH

Tells the setlocale() function the name of the directory in the UNIX file system from which to load the locale object files. It specifies a colon separated list of UNIX file system directories.

If LOCPATH is defined, setlocale() searches UNIX file system directories in the order specified by LOCPATH for locale object files it requires. Locale object files in the UNIX file system are produced by the localedef utility running under z/OS UNIX.

If LOCPATH is not defined and setlocale() is called by a POSIX program, setlocale() looks in the default UNIX file system locale directory, /usr/lib/nls/locale, for locale object files it requires. If setlocale() does not find a locale object it requires in the UNIX file system, it converts the locale name to a PDS member name and searches locale PDS load libraries associated with the program calling setlocale().

Note: XPLINK locales have an .xplink suffix added to the end of the locale name. For more information about XPLINK locale names, see Locale naming conventions

PATH

The set of UNIX file system directories that some z/OS XL C/C++ functions, such as EXECVP, use in trying to locate an executable. The directories are separated by a colon (:) delimiter. If the pathname contains a slash, the PATH environment variable will not be used.

__POSIX_SYSTEM

Determines the behavior of the system() function when the POSIX(ON) runtime option has been specified. If __POSIX_SYSTEM=NO, then system() behaves as in Language Environment/370 1.2: it creates a nested enclave within the same process as the invoker (allowing such things as sharing of memory files). Otherwise, system() performs a fork() and exec(), and the target program runs in a separate process (preventing such things as sharing of memory files).

Restriction:__POSIX_SYSTEM=NO is not supported in AMODE 64 applications.

__POSIX_TMPNAM

Determines the behavior of the tmpnam() function when the POSIX(ON) runtime option has been specified. If the __POSIX_TMPNAM environment variable is set to NO, tmpnam() behaves as if it was called under POSIX(OFF). Otherwise, tmpnam() generates a unique file name in the UNIX file system.

STEPLIB

Determines the STEPLIB environment that is created for an executable file. It can be a sequence of MVS data set names separated by a colon (:), or can contain the value CURRENT or NONE. If you do not want a STEPLIB environment propagated to the environment of the executable file, specify NONE. The STEPLIB environment variable defaults to the value CURRENT, which will propagate your current environment to that of the executable file. See z/OS UNIX System Services Command Reference for more information on the use of the STEPLIB variable and changing the search order for z/OS programs.

TZ or _TZ

Time zone information. The TZ and _TZ environment variables are typically set when you start a shell session, either through /etc/profile or .profile in your home directory. For more information, see Customizing a time zone.