Environment variables: local and remote mode

Environment variables available for use with local mode and remote mode topologies.

AUTH_USERID_PASSWORD

Specifies whether the user ID and password is authenticated with the External Security Manager (ESM) such as RACF®. This setting applies exclusively to EXCI connections to CICS®. Set this variable to YES to enable authentication by the ESM. Set it to NO if authentication by the ESM is not required. If the variable is set to any value other than NO, authentication is enabled. If the variable is not set, authentication is not enabled.

If you set this variable see also Configuring for client certificate mapping.

COLUMNS

Specifies the maximum line-length for messages output to the console when CICS Transaction Gateway is started. If this variable is not set, the line-length is set to 40 columns. The minimum line-length is 40 columns. The maximum possible line-length is 160 columns.

CTG_EXCI_INIT

Specifies whether or not EXCI is loaded. If this variable is set to YES, EXCI is loaded. If the variable is set to NO, EXCI is not loaded. The default value is YES.

If EXCI is not active:

An information message is logged.
Attempts to make EXCI calls result in an ECI_ERR_NO_CICS return code.
Attempts to use an EXCI server result in a communications failure count being incremented.
ListSystems calls do not include EXCI servers.

CTG_JNI_TRACE

Sets the name of the JNI trace file. This environment variable only defines the name of the JNI trace file; it does not enable trace. The default file name is ctgjni.trc. JNI trace is output as plain text, and there is no requirement to use a particular extension for the file name.

CTG_JNI_TRACE_ON

Specifies whether or not JNI trace is enabled. Set this environment variable to YES to enable JNI trace when the CICS Transaction Gateway is started. Tracing is not enabled if the variable is set to any value other than YES.

CTG_MIXEDCASE_PW

Specifies whether or not mixed-case passwords are authenticated. Set this environment variable to YES to enable mixed-case passwords to be authenticated by an external security manager such as RACF. If you enable support for mixed-case passwords, you must also set environment variable AUTH_USERID_PASSWORD to YES. CTG_MIXEDCASE_PW must be set to YES to allow password phrases to be authenticated.

If CTG_MIXEDCASE_PW is set to NO, CICS Transaction Gateway converts all passwords to upper case before authenticating with the ESM.

Valid values are YES|NO. Any other value is treated as not valid, and the default value used instead.

CTG_PIPE_REUSE

Specifies whether all allocated EXCI pipes are reused by CICS Transaction Gateway, or only a maximum of one is reused per worker thread.

ALL

Reuse all allocated pipes. This is the default.

Specify this option if maximum throughput is the priority.

If the pipe that is allocated to a given worker thread is not for the correct server for the next ECI request, using this pipe model, the pipe remains allocated and a new pipe is allocated for the new server connection on that worker thread. This model limits the maximum number of worker threads to the EXCI pipe limit divided by the maximum number of servers.

ONE

Reuse a maximum of one allocated EXCI pipe for each worker thread.

Specify this option if the maximum number of concurrent worker threads is the priority.

If the pipe that is allocated to a given worker thread is not for the correct server for the next ECI request, using this pipe model, the pipe is deallocated and then reallocated to the new server. This model limits the maximum number of worker threads to the EXCI pipe limit.

Abbreviations are not allowed. An unrecognized value causes the default of ALL to be used.

CTG_SWAPPABLE

Specifies whether the address space where CICS Transaction Gateway runs is swappable or nonswappable. Do not set this environment variable unless CICS Transaction Gateway runs in local mode. If you do not set the environment variable, CICS Transaction Gateway runs in a nonswappable address space. If you set the environment variable to YES, CICS Transaction Gateway runs in a swappable address space.

If a Java™ Client application makes an ECI request while CICS Transaction Gateway is swapped out, the request fails with these error messages:

CCL6668E: Initial handshake flow failed 
CCL6666E: Unable to flow request to the Gateway

To avoid this, CICS Transaction Gateway is made nonswappable after the first ECI request has been successfully flowed. CICS Transaction Gateway can still be swapped out before the first ECI request is flowed. If this happens, ECI requests fail until IBM® z/OS® swaps CICS Transaction Gateway back in.

Nonswappable mode: You are recommended to run CICS Transaction Gateway in a nonswappable address space, unless it is running in local mode. (It always runs in swappable mode under IBM WebSphere® Application Server.) To make CICS Transaction Gateway nonswappable, ensure that the user running the CICS Transaction Gateway process has READ access to the BPX.STOR.SWAP FACILITY class. No other action is required. If CICS Transaction Gateway cannot be made nonswappable, a log message is output, and CICS Transaction Gateway runs in a swappable address space.
Swappable mode: You are advised to run CICS Transaction Gateway in a swappable address space if it will run in local mode. To do this, set the CTG_SWAPPABLE environment variable to YES. If you set this variable to any other value CICS Transaction Gateway runs in a nonswappable address space.

When an application makes an address space nonswappable, it might cause additional real storage in the system to be converted to preferred storage. Because preferred storage cannot be configured offline, using this service can reduce the ability of the installation to re-configure storage in the future. For more information see IBM z/OS UNIX System Services Planning, GA22-7800.

DFHJVPIPE

Specifies the name of the specific pipe that CICS Transaction Gateway uses for EXCI calls. If this variable is not set, or is set to a blank value by a command such as export DFHJVPIPE="", CICS Transaction Gateway uses a generic pipe.

DFHJVSYSTEM_nn

Specifies the name and description of an EXCI connected CICS server to be returned in response to a request for the list systems function. You can set up to 100 environment variables of the form DFHJVSYSTEM_nn, where nn ranges from 00 to 99. They are listed in order from 00 to 99 with missing numbers ignored. This function call takes a maximum number of systems returned value; if the number of systems defined exceeds that value the call returns the error ECI_ERR_MORE_SYSTEMS.

The value is a string containing the APPLID of the CICS system, followed by a hyphen (-), followed by a description of the CICS system. The description must not be more than 60 bytes long. For example if you specify:

DFHJVSYSTEM_00=MYCICS-Test CICS system

List systems returns details of a CICS system called MYCICS with description Test CICS system.

DFHJVTOKENPROVIDER_nn

Specify the token providers that CICS Transaction Gateway client applications can use to authorise themselves to connect to the CICS Transaction Server for z/OS. You can define multiple token providers by separating them with a comma. The JWT is validated against each token provider and stops processing further on a successful validation. If a token provider name is set and if it is not defined in the configuration file, then the CICS Transaction Gateway fails to start. If no token provider is specified or the parameter is omitted, then the CICS TG userid is sent to the CICS Transaction Server for z/OS.

You can set up environment variable DFHJVTOKENPROVIDER_nn with token providers, where nncorresponds to the EXCI server environment variable DFHJVSYSTEM_nn. The value is the list of token providers separated by a comma(,). For example if you specify:

DFHJVTOKENPROVIDER_00=TOKENPROVIDERA,TOKENPROVIDERB

Corresponds to the EXCI server DFHJVSYSTEM_00=MYCICS-Test CICS system.

STEPLIB

Specifies the library containing the default EXCI options and the EXCI load modules. Ensure that the STEPLIB environment variable includes any load library that contains EXCI options table DFHXCOPT ahead of the CICS EXCI load library SDFHEXCI in the concatenation order, because the default table supplied is contained in SDFHEXCI.

The maximum length of this field is 200 characters.