Environment variables: local and remote mode
Environment variables available for use with local mode and remote mode topologies.
- 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.
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.
- 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.
- 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.
- 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.
- 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.
- Specifies whether all allocated EXCI pipes are reused by CICS Transaction Gateway, or only
a maximum of one is reused per worker thread.
- 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.
- 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.
- 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:
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.
CCL6668E: Initial handshake flow failed CCL6666E: Unable to flow request to the Gateway
- 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.
- 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.
- 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:
List systems returns details of a CICS system called
DFHJVSYSTEM_00=MYCICS-Test CICS system
Test CICS system.
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:
Corresponds to the EXCI server DFHJVSYSTEM_00=MYCICS-Test CICS system.
- 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.