Understanding the Gateway daemon
CICS TG is implemented in remote mode when the client application and CICS TG are running on different machines and the Gateway daemon listens on a specific port for incoming client requests. This is also called a 3-tier solution.
In a remote mode configuration, the CICS Transaction Gateway runs a process known as a Gateway daemon, which listens on a specific port, receives requests from remote client applications, forwards those requests to specific CICS servers, and communicates the result back to the remote client application.
This chapter provides insight into the Gateway daemon process and allows you to understand the implication of different Gateway daemon configurations. It also describes how to influence the management of connections and thread resources in the Gateway daemon.
It also provides insight into the system dependencies of the Gateway daemon configuration, allowing you to perform basic tuning suggestions to improve Gateway daemon performance.
All the formulas that are provided are based on observations, and they provide a general guideline to configure the system. Every configuration has different requirements, and so your configuration must be verified with the Gateway statistics or the operating system tools. Some values that are provided are subject to change, based on the level of the operating system where the Gateway daemon is running.
The following topics are covered in this chapter:
5.1 Three-tier concepts
CICS TG can be used in two modes: local and remote. There are also a number of possible combinations of implementing the networking and system infrastructure between the client applications, CICS TG components, and CICS servers. The different combinations are referred to as topologies.
Remote mode operation uses the Gateway daemon as a long-running process. The Gateway daemon listens on a specified port for incoming requests (using a TCP/IP connection), then it forwards those requests to a CICS server using one of the listed protocols: EXCI, IPIC, TCPIP, or SNA.
Figure 5-1 shows different topologies. Topology 2 and 3 show a remote mode configuration where the Gateway daemon is representing the middle tier of a 3-tier solution.
Figure 5-1 CICS TG topology examples
The client applications, using a CICS TG API, are able to invoke CICS programs through the Gateway daemon. However, the connection between the client applications and the Gateway is not always implicitly created. ECI V2, ESI V2, .NET, and Java base class applications need to manage the connection by using explicit open and close, API calls. Java EE application servers have managed connection factories, with a pool of cached connections already created.
Figure 5-2 on page 69 shows the connections management based on the APIs and technology used.
Figure 5-2 Flow of control through a Gateway daemon
The Gateway daemon is designed to act as a network concentrator, able to serve potentially many remote applications through relatively restricted CICS connections. The client can connect in various ways. When the Gateway daemon uses IPIC connections, almost all of the run time takes place with the Java virtual machine (JVM). Other protocols require additional native runtime components as shown in Example 5-2 on page 85.
Figure 5-3 CICS TG components related to CICS communication protocols
5.2 Gateway daemon resources
This section describes the resources that the Gateway daemon needs to satisfy the client requests.
5.2.1 Protocol handlers
This section discusses the protocol handlers.
TCP and SSL
The Transmission Control Protocol (TCP) and Secure Sockets Layer (SSL) protocol handlers represent the entry point to the Gateway daemon for remote client applications. The Gateway daemon provides two connection protocols: TCP and SSL. Use SSL connectivity when the data between the client and the Gateway daemon must be secure. Table 5-1 summarizes the API restrictions using SSL.
Table 5-1 Remote API components and connection protocol support
|
Remote mode applications
|
TCP
|
SSL
|
|
All APIs in Java
|
Yes
|
Yes
|
|
All APIs in JCA
|
Yes
|
Yes
|
|
.NET
|
Yes
|
With SupportPac CA761
|
|
ECI v2
|
Yes
|
No
|
|
ESI v2
|
Yes
|
No
|
Protocol handlers are defined in the GATEWAY section of the configuration file. You need to define the port where the Gateway will listen, and the bind parameter if you have more than one active IP address.
|
Note: You can have at most one TCP and one SSL handler.
|
To verify that SSL security is enabled on the Gateway daemon, check the following points:
•Whether the SSL ciphers have been enabled in the Gateway daemon. The following message is written to the Gateway daemon information log:
CTG8489I The following cipher suites are provided by JSSE: with all the cipher suites supported
•If the SSL protocol handler is successfully started on the configured port, you will see the following message in the Gateway daemon information log:
CTG6524I Successfully started handler for the ssl: protocol on port 8573
For additional clarification about security, see Chapter 8, “Security” on page 131, and for implementation, see 10.4, “Configure secure connections” on page 186.
Statistics and administration handlers
On all platforms, CICS TG provides statistics information about the status and the activities performed by the Gateway daemon. It can help you in tuning the Gateway daemon configuration and for post-processing analysis of the information collected by the statistics engine of the Gateway daemon. To enable the statistics, define the statsapi statistics API protocol handler, in the GATEWAY section of the CICS TG configuration file.
You can display the statistics using the administration interface (CICS Explorer for example) or retrieve the information using statistics APIs in a user program.
To verify that the statsapi port is enabled on the Gateway daemon, check the following message in the Gateway daemon information log:
CTG6524I Successfully started handler for the statsapi: protocol on port 2989
If the Gateway daemon is installed on multiplatforms, we need also to define an additional handler for administering the Gateway daemon. When an administrative request is received by a Gateway daemon from the ctgadmin command, it is processed by a restricted handler. On Multiplatforms, this handler is defined in the Gateway daemon section using the parameter ctgadmin.
To verify that the admin port is enabled on the Gateway daemon, check the following message in the Gateway daemon error log:
CTG8455I Successfully started the local administration handler on port 2810
5.2.2 The threading model
The Gateway daemon uses two thread pools to maintain the link between the client request and the target CICS. When an application opens a connection to a Gateway daemon, a connection manager thread is allocated. This thread represents the active application connection. When the application sends a flow, the Gateway daemon needs to send the request to CICS, allocating a worker thread to represent the active request to CICS. The Gateway daemon can handle multiple requests simultaneously, at the capacity that is configured in the Gateway daemon configuration file.
Connection manager threads manage the connections from a particular remote client. When a connection manager thread receives a request, it allocates a worker thread from a pool of available worker threads to run the request, and it remains allocated. The worker thread is allocated to process CICS requests on behalf of connection manager threads. When a worker thread finishes the processing, it returns to the pool of available worker threads. The connection manager threads can be deallocated if an explicit close is issued, or it can be just reused by a new request.
For each connected client, one connection manager thread is used in the Gateway daemon. This thread is held until the client closes the connection, or the Gateway times out the connection. To perform an ECI request using an allocated connection manager thread, a thread must be allocated from the worker thread pool for the duration of the ECI request.
Figure 5-4 shows the interactions between the different threads.
Figure 5-4 The threading model through the Gateway daemon
It is important to consider the thread limits in the system when setting the number of connection manager and worker threads. The limit for the system threads is set so high that it cannot be realistically reached; the real limit is driven by the amount of virtual memory available to the process and by the CPU capacity.
On z/OS, this might be restricted by the total number of MVS Task Control Blocks (one is created for each UNIX System Services thread). This limit is governed by the UNIX System Services parameters MAXTHREADS and MAXTHREADTASKS in the BPXPRMxx member of SYS1.PARMLIB. The Gateway daemon creates the connection manager and worker threads using the UNIX System Services thread facility. The total number of threads in use by the Gateway daemon can be displayed using the MVS system command /D OMVS,L,PID=nnnn, where nnnn is the process ID of the JVM running the Gateway daemon, as displayed using the SDSF PS menu option. Consider also the UNIX System Services parameter MAXPROCUSER. It specifies the maximum number of processes that a single user (same UID) can have concurrently active. If a Gateway daemon is started with a user with a UID of 0, it is not limited by the MAXPROCUSER value (a superuser is always allowed to run so that it can be invoked to solve a problem).
To display the current UNIX configuration setting, you can also run the MVS system command /D OMVS,OPTIONS.
To temporarily modify the settings for MAXTHREADS and MAXTHREADTASKS, use the /SETOMVS MAXTHREADS=nn or /SETOMVS MAXTHREADTASKS=nn commands. To permanently change the values, modify the BPXPRMxx member.
5.2.3 Estimating the number of connection manager threads
The best way to calculate the number of required connection manager threads depends on whether you are using a Java EE application or a base Java application. With Java EE applications, the number of connection manager threads depends on the size of the connection pool defined in the connection factory of the JCA connection pools.
WebSphere Application Server maintains a pool of open TCP/IP connections to the Gateway daemon. The number of connections in the pool, at any time, depends on the number of concurrent requests for the CICS server defined by the connection factory and how quickly it is configured to close inactive connections.
To avoid a resource shortage when WebSphere Application Server is running under high load, control your setting of maxconnect. The maxconnect setting is in the Gateway daemon initialization file. It must be greater than or equal to maximum connections in the connection pool. If you are using multiple WebSphere Application Server instances or multiple resource adapters, maxconnect must be greater than or equal to the sum of the connections for all of the connection factories.
For remote client applications (Java base classes, ECIv2, and .NET), which must explicitly manage the connections to the Gateway daemon (open-flow-close method), the number of connections in use depends on the design of the user application. For example, the general sequence of events for an application with Java base class is to open a connection using JavaGateway.open(), issue any number of requests through JavaGateway.flow(), and close the connection using JavaGateway.close(). Each instance of a JavaGateway object maintains one TCP/IP socket between an open and a close. The number of connection manager threads must be greater than or equal to the concurrent number of JavaGateway objects that have been opened by the user’s applications.
It is possible to configure the Gateway daemon so that an application will wait for a connection manager’s threads to become free. The connecttimeout parameter in the Gateway daemon configuration file controls this value. Only consider reducing the connection manager threads available in the pool and relying on this timeout if applications open and close connections frequently.
A thorough evaluation of the maximum number and the initial number of connection manager threads avoids redundant storage allocation and any additional CPU workload due to the management of inactive threads. A thorough evaluation of the maximum number and the initial number of connection manager threads can make the CICS TG startup time faster.
In the configuration file, you control the maximum number of connection manager threads with the parameter maxconnect.
The configuration parameter, initconnect, identifies the number of connection manager threads created at the Gateway daemon startup.
|
Note: For CICS TG Desktop Edition, 5 is the maximum value of maxconnect and initconnect.
|
5.2.4 Estimating the number of worker threads
The number of worker threads depends on the concurrent number of requests from remote clients and on the numbers of CICS sessions available to process the incoming requests. When a worker thread has finished processing the request, it returns to the pool of available worker threads. For this reason, there is no need to code the maximum number of worker threads higher than the maximum of connection manager threads.
When considering the CICS TG maximum number of worker threads, take into account how the following CICS Transaction Server (CICS TS) configuration parameters affect the Gateway daemon:
•MAXTASKS in CICS TS: The Gateway daemon cannot start more mirror transactions than CICS TS can concurrently run. If you have more than one CICS TS, you need to consider how the workload is distributed.
•TRANCLASS in CICS TS: The mirror transactions that the Gateway daemon attaches in CICS TS can be controlled by the number of concurrent running tasks defined in a particular transaction class. You must also take into account the PURGETHRESHOLD value, in the TRANCLASS definition.
•Regardless of the solution you decide to use to connect to CICS TS (IPIC, EXCI, or ECI over IP), you cannot exceed the upper limit of the protocol connection definition. This aspect will be described later in this chapter.
•Remember that CICS TS can be configured to have multiple connections with other CICS TS. To process the distributed program link (DPL) requests sent by the Gateway daemon, you might need to send the request to another CICS system, such as an Application Owner Region (AOR). This kind of topology can introduce additional elements that must be considered.
•The application can also invoke some processes in CICS TS that create affinities or need sequential access to resources. Any possible constraint has to be taken into account.
If the number of communication manager threads is higher than the worker threads, it is possible that the Gateway daemon is queuing for free worker threads. You can establish how long your request will queue for an available worker thread by specifying the workertimeout parameter in the CICS Transaction Gateway daemon configuration file.
In the configuration file, you control the maximum number of worker threads with the parameter maxworker.
The configuration parameter, initworker, identifies the number of worker manager threads created at the Gateway daemon during initialization.
|
Note: For CICS TG Desktop Edition, 5 is the maximum value of the maxworker and initworker.
|
5.3 Connecting to CICS servers
This section describes the main implications that must be evaluated when configuring the Gateway daemon depending on the protocols selected to connect to CICS TS.
The storage implications with the different protocols used are expanded in 5.4, “System resources” on page 78.
For selection guidelines based on the protocol that is used to connect the Gateway to a CICS TS, see Chapter 1, “Basic concepts” on page 3 and Chapter 4, “Connecting to CICS” on page 43.
5.3.1 All platforms: IPIC
The Gateway daemon can connect to CICS TS using IPIC protocol, independent of where the CICS TG is installed. It can be secured with SSL.
IPIC provides ECI access to CICS applications over the TCP/IP protocol, supporting both COMMAREA and CICS channel applications.
You can configure the IPIC connection in the IPICSERVER section of the configuration file and it needs to match the CICS TS definition. Figure 5-5 shows the relationship between the different elements.
Figure 5-5 Relationship between CICS TG and CICS TS definitions for an IPIC connection
When you are configuring the number of worker threads, you need to take the sendsessions parameter into account. If you have multiple IPIC server definitions, remember to add the sendsessions number to the worker thread count to allow the Gateway to manage all the sessions.
The sendsessions parameter, in the IPICSERVER section of the configuration file, specifies the number of simultaneous CICS tasks that are allowed over the CICS connection. You must specify the same number for the value in the receivecount parameter of the IPCONN definition on the CICS server. If you do not specify a value or specify a lower value in receivecount than the value specified in the sendsessions parameter, the value used might be reduced.
You can also find a benefit using the CICS IPCONN autoinstall. During the first connection from CICS TG to CICS, CICS creates the IPCONN definition. Unlike autoinstall for other resources, autoinstall for IPCONN resources does not require model definitions, although they are advised.
Client applications usually flow data in ASCII format and the CICS user program is able to manage data in EBCDIC in the COMMAREA. The CICS mirror program (DFHMIRS) invokes the services of the data conversion program (DFHCCNV) to perform the necessary code page conversion of the COMMAREA.
The CICS channel and container solution allows you to send and receive more than 32 KB of application data in a single ECI request. This ability requires you to consider additional points when you are configuring your Gateway.
The data conversion model, used by channel applications, is controlled by the application developer using simple API commands, and DFHCNV is not needed anymore. CICS TS uses z/OS Unicode Services instead. You can check whether the z/OS Unicode Services are correctly implemented using the following z/OS system command:
D UNI,ALL
Consider the performance and storage allocation implications of passing a large amount of data through channels. For example, when a large amount of data is to be passed to a remote program or transaction, it might affect performance.
If your applications need to use a container size greater than 1 MB, it might be necessary to increase the JVM resources and the memory size for the Gateway daemon and CICS. A channel might use more storage than a COMMAREA designed to pass the same data because container data can be held in more than one place. COMMAREAs are accessed by pointers. The data in containers is copied between programs.
For the complete list of benefits of using channel and container technology, see the CICS TS Information Center topic, Benefits of channels.
IPIC on CICS TG for z/OS specific items
IPIC can benefit from the System z Application Assist Processor (zAAP) because the IPIC workload can be offloaded to these processors. Offloading the IPIC workload significantly reduces the CPU cost per transaction. Although EXCI is limited to 32-K payloads using a COMMAREA, IPIC payloads can be as large as you need, using channels and containers.
When the EXCI layer is loaded, the maximum number of worker threads is capped at 250. Specifying CTG_EXCI_INIT=YES and maxworker to more than 250 will cause the following message to be issued during the Gateway daemon startup and the value of the maxworker is reduced to be equal to the EXCI logon limit (LOGONLIM):
CTG6406W the maximum worker threads has been reduced to the EXCI logon limit 250
IPIC connections to CICS are not limited by LOGONLIM because they do not use EXCI pipes. But if the EXCI layer is loaded, it is assumed that the EXCI connections will be used, so the maxworker restriction is applied. To allow IPIC to use more than 250 worker threads, CTG_EXCI_INIT=NO must be set to prevent the EXCI layer being loaded.
|
Note: Applications can only use ESI with CICS TG for z/OS when the CICS connection is IPIC.
|
5.3.2 Multiplatform and Desktop Edition specific: TCPIP
CICS TS has no way to limit the number of concurrent requests that are sent to a TCP/IP connection. Applications in error can submit an excessive number of requests to a server. In this event, to prevent runaway conditions and avoid a possible denial of service attack that can affect CICS TS, it is suggested to code an accurate number of worker threads.
The maxrequests parameter can also be used to prevent this situation.
|
Note: TCPIP is the name of a driver type and it is not TCP/IP, the transport.
|
5.3.3 Multiplatform and Desktop Edition specific: SNA
Using an SNA connection, the maxrequests parameter in the ctg.ini file must be the same or more than the number of sessions defined in CICS.
The first value, in the CICS session parameter, is the maximum number of sessions that can be supported. The second value specifies the number of contention-winner sessions (CICS-owned sessions). These values are negotiated during change number of sessions (CNOS) flows. When the sessions are actually bound, the negotiated values depend on the settings specified in the partner SNA node.
This solution also requires a supported SNA provider product (for example, IBM Communications Server) to be installed and configured in the same machine where CICS TG is installed.
|
Note: CICS TG Desktop Edition runs only in 2-tier remote mode.
|
5.3.4 z/OS specific: EXCI
The external CICS interface (EXCI) is used by the Gateway daemon for z/OS to send requests to the CICS TS region using cross-memory services.
To load the code to support the EXCI protocol, you need to set the environment variable CTG_EXCI_INIT to YES. At this point, the Gateway will also load the EXCI options table, DFHXCOPT. There is no suffixed version of this program, so the first DFHXCOPT table in the STEPLIB concatenation is loaded.
DFHXCOPT allows you to specify whether you want the surrogate-user check, whether you want the timeout value for requests over EXCI, and whether the trace is active.
|
Tip: Specify ABENDBKOUT=YES in DFHXCOPT if you want to back out updates made by a long-running mirror following a transaction abend.
|
When a request is sent over an EXCI connection, a pipe is allocated; the Gateway does not perform any deallocate after it flows the initial ECI request for a given worker thread.
An EXCI pipe stays allocated for the lifetime of the thread. An EXCI pipe is only deallocated if one of the following events occurs:
•An error is received by the Gateway worker thread on an Open_Pipe call (such as when a CICS connection has been closed).
•The Gateway daemon terminates.
•The worker thread allocates another pipe to a different CICS applid, and the CTG_PIPE_REUSE environment variable is set to ONE.
Every address space that uses EXCI pipes, such as a Gateway daemon, is limited to a maximum number of pipes that it can allocate to all attached CICS regions. The EXCI pipe limit is governed by the z/OS system-wide LOGONLIM parameter and the upper limit is 250.
|
Note: To modify the LOGONLIM, you need to modify the SYS1.PARMLIB(DFHSSIxx) member.
|
Also, consider that deallocating an EXCI pipe has a cost in terms of CPU consumption. For this reason, it is important to select the best way for your installation to reuse the EXCI pipe.
This is governed by the parameter CTG_PIPE_REUSE.
CTG_PIPE_REUSE=ALL means that the pipes will be permanently allocated to a particular CICS server and are not available for use with other CICS servers. It is suggested that CTG_PIPE_REUSE=ALL is only specified when the Gateway daemon uses EXCI connections to one CICS server. If you do specify CTG_PIPE_REUSE=ALL and EXCI connections to more than one CICS server are defined, ensure that you do not run out of EXCI pipes by limiting the number of worker threads that can allocate the pipes. To ensure that you do not run out of EXCI pipes by limiting the number of worker threads that can allocate the pipes, use this formula to configure the number of worker threads:
MaxWorkers <= Pipes Limit / Number of servers
CTG_PIPE_REUSE=ONE means that if requests are made to multiple CICS servers, the pipe will be deallocated and another pipe will be allocated, before the call to the second CICS server takes place.
If subsequent requests are made to the same CICS server, no pipe deallocation and reallocation will take place. In this case, consider using the following formula:
MaxWorkers <= Pipes Limit
For all connected Gateway daemons, on z/OS, the CICS region requires both a CONNECTION definition and a SESSIONS definition. The CONNECTION definition identifies the remote system, and the SESSIONS definition associated with this connection determines the properties of the sessions.
The maximum pipe usage in a CICS region is also limited by the RECEIVECOUNT parameter defined in the CICS MRO SESSIONS definition (this can be up to 999).
5.4 System resources
This section describes how the Gateway daemon interacts with system components and important considerations when you configure it.
5.4.1 Gateway daemon runtime environment
During startup, the Gateway daemon uses a combination of the configuration file and an environment variable to form the runtime environment and to successfully start the required processes. When needed, you can also pass some override parameters to the Gateway daemon.
Table 5-2 shows the different resources involved in the Gateway daemon startup.
Table 5-2 Gateway startup resources
|
Platform
|
Configuration file location
|
Environment variable
|
Override
|
|
z/OS
|
Specified in CICSCLI in the environment variable.
|
Specified in the DD STDENV
|
- In the EXEC PARM at ctgstart level
or
- CTGSTART_OPTS
in the environment variable |
|
Windows
|
Default to <product_data_path>/ctg.ini. It can be changed using the CICSCLI environment variable.
|
Specify as a system environment variable
|
- Using the utility ctgservice -R or
- starting the cicscli - R process
|
|
UNIX/Linux
|
Default to <install_path>/bin/ctg.ini. It can be changed using CICSCLI environment variable.
|
- Specify as environment variable
or
- in CTGDCONF, if ctgd start is used. The default ctgd configuration file is <install_path>/bin/ctgd.conf
|
- Starting the cicscli process
or
- CTGD_PARMS environment variable
|
Java Runtime Environment is required to use the CICS TG core components. Use the latest Java update for your Java Runtime Environment (JRE) on Multiplatform and Desktop Edition. For z/OS, use the IBM SDK for z/OS, Java Technology Edition.
The Gateway daemon for z/OS can be started using CTGBATCH, which invokes the z/OS UNIX script, ctgstart, as a batch job. It is still possible to start the Gateway in the UNIX System Services environment; however, you cannot benefit from the z/OS facilities, such as the visibility of the logs in System Display and Search Facility (SDSF), z/OS console commands, and Gateway daemon-specific storage size of the address space.
The Gateway daemon for UNIX or Linux can be started as a background process, using the ctgd start command, and it runs under a specific user ID.
The Gateway daemon for Windows runs as a service that is started manually by default.
5.4.2 Information available at run time
The CICS TG has numerous log files. Table 5-3 on page 80 summarizes where the locations of the log files based on the platform.
The Client daemon log, Gateway daemon info log, and Gateway daemon error logs are available.
Table 5-3 Location of log files
|
Operating system
|
Log name
|
Default location
|
Override location
|
|
Windows
|
Client daemon log
|
<product_data_path> directory. By default, it is C:ProgramDataIBMCICS Transaction Gatewaycicscli.log
|
logfile=<filename> in the CLIENT section of the configuration file
|
|
Client daemon info log
|
<product_data_path> directory. By default, it is C:ProgramDataIBMCICS Transaction Gatewaycicscli.log
|
logfileinfo=<filename> in the CLIENT section of the configuration file
|
|
|
Gateway daemon error log
|
<product_data_path> directory. By default, it is C:ProgramDataIBMCICS Transaction Gatewaycicstg.log
|
||
|
Gateway daemon info log
|
<product_data_path> directory. By default, it is C:ProgramDataIBMCICS Transaction Gatewaycicstg.log
|
||
|
On UNIX and Linux platforms
|
Client daemon log
|
By default, it is /var/cicscli/cicscli.log
|
logfile=<filename> in the CLIENT section
|
|
Client daemon info log
|
<product_data_path> directory. By default, it is /var/cicscli/cicscli.log
|
logfileinfo=<filename> in the CLIENT section
|
|
|
Gateway daemon info log
|
console
|
Specify in the GATEWAY section of the configuration file [email protected]=<file> to have [email protected]=filename=<name> active
|
|
|
Gateway daemon error log
|
console
|
Specify in the GATEWAY section of the configuration file [email protected]=<file> to have [email protected]=filename=<name> active
|
|
|
z/OS
|
Gateway daemon log
|
JES Joblog
|
STDOUT and STDERR DD statements in the Gateway daemon startup job
|
The Gateway daemon log handler allows you to specify the maximum log size also.
5.4.3 Gateway daemon memory requirements
To avoid out-of-memory conditions in the Gateway daemon, you need to carefully consider many elements. Most of the Gateway daemon resources are allocated in the Java heap and Java stack, and you can control them using the parameters -Xmx and -Xss.
The JVM maintains two memory areas: the Java heap, and the native (or system) heap. These two heaps have different purposes and are maintained by different mechanisms.
The Java heap contains the instances of Java objects and it is maintained by garbage collection. In the z/OS environment, the maximum size of the Java heap is preallocated during JVM startup as one contiguous area, even if the minimum heap size setting is lower. But in other platforms, the Java heap is incrementally acquired; for this reason, it must be carefully sized.
The Java heap is a repository for active, orphaned objects and free memory. When an object can no longer be reached from any object referenced in the running program, the object can be garbage-collected.
When the JVM cannot allocate an object from the heap because of lack of contiguous space, a memory allocation fault occurs, and the garbage collector is called. This process is a normal process invoked to tidy up the heap storage, but it consumes CPU time. For this reason, a meticulous evaluation of the heap storage is important. In effect, the heap size determines how often and how long the JVM spends performing the garbage collection.
The -Xgcpolicy options control the behavior of the garbage collector. For CICS Transaction Gateway, the best performance is provided by optthruput. The Gateway daemon default is also optthruput.
To tune the heap size, review the maximum and average SE_CHEAPGCMIN statistic value, through a workload cycle, as a percentage of SE_SHEAPMAX to ensure that the value is in the range of 40% - 70%. If the percentage is over 70%, increase the maximum heap size. If the percentage is under 40%, reduce the maximum heap size.
The system, or native heap, is allocated by using the malloc and free mechanisms of the operating system. Native heap is used for the underlying implementation of particular Java objects, such as the allocation of the Java threads.
5.5 z/OS specific resources
This section describes the z/OS specific resources and how to evaluate their correct usage.
5.5.1 Region size consideration in CICS TG for z/OS
Gateway daemon for z/OS memory management is complex. Several concepts are required to better tune the Gateway configuration.
An easy way to estimate the real amount of native heap required by the Gateway daemon at run time is to set the initial and maximum number of connection managers and worker threads to the same. This forces the Gateway daemon to create all the threads at startup and you can verify the actual storage consumption and act accordingly.
This suggestion will give you a reasonable sizing of the memory needed by your Gateway daemon. After that, you can start to tune the storage requirement more carefully.
Table 5-4 describes a base suggestion about how to evaluate the necessary storage allocation. This table represents a guideline, not an accurate formula, and the values can change depending on environmental factors, such as operating system release or Language Environment runtime options.
Table 5-4 Observed use of memory in a 31-bit Gateway daemon
|
Storage type
|
Usage
|
|
Native
|
356 KB per thread
|
|
Java heap
|
300 KB per IPIC session
|
|
Java heap
|
1.6 KB per thread
|
|
Java heap
|
4800 KB core Gateway daemon
|
The Java heap can be modified at the Gateway daemon startup by using the -Xmx option. The default heap size specified by the CICS Transaction Gateway is 128 MB, and this is typically increased for production configurations.
The JVM is a z/OS UNIX process that runs in its own Language Environment enclave. The JVM Heap, control blocks, and other data areas are handled by the Language Environment heap and it is governed by the Language Environment HEAP runtime option. Language Environment stack is allocated per thread with an initial size and can grow, according to the ANYHEAP runtime option values.
CTGBATCH runtime options, provided by default, are shown in Example 5-1, and you can override these parameters with the Language Environment runtime option specification at the Gateway daemon startup. Any change in the runtime option must be carefully evaluated.
Example 5-1 Default CTGBATCH runtime options
(ABTERMENC(ABEND),ALL31(ON),ERRCOUNT(0),
STORAGE(NONE,NONE,NONE ,0K),
TRAP(ON,SPIE),LIBSTACK(4K,4K,FREE),
STACK(128K,128K,ANY,KEEP),
ANYHEAP(16K,8K,ANY,FREE),
BELOWHEAP(8K,4K,FREE),
HEAP(32K,32K,ANY,KEEP,8K,4K),
RPTOPTS(OFF),RPTSTG(OFF),POSIX(ON),
TERMTHDACT(UADUMP),NOUSRHDLR)
Java heap can be modified at the Gateway daemon startup by using the -Xmx option. The default heap size specified by the CICS Transaction Gateway is 128 MB.
There are no options with which you can manage the native heap because this is done by the Gateway daemon for you. You only need to define enough region size to allocate the native heap requested.
JVM is constructed in its own Language Environment enclave, created by the Language Environment pre-init module. The JVM is a z/OS UNIX process. The JVM Heap, controlblocks, and other data areas are handled by Language Environment heap and it is governed by the Language Environment HEAP runtime option.
The JVM Heap and native storage used by the Gateway daemon is all managed by Language Environment.
The storage allocated by Language Environment is constrained by the Gateway daemon address space storage. For a 31-bit Gateway daemon, address space storage is set by the REGION parameter in the JCL (EXEC or JOB statement).
The following parameters can also limit the values that you can choose for the REGION parameter:
•The ASSIZEMAX parameter of the OMVS segment of a RACF user ID; for more information see z/OS V1R13.0 Security Server RACF Command Language Reference, SA22-7687-16:
•The UNIX System Services MAXASSIZE parameter is specified in SYS1.PARMLIB(BPXPRMxx); for more information, see the UNIX System Services Planning. The value specified for ASSIZEMAX overrides any value provided by the MAXASSIZE parameter.
•If you use REGION=0M, the actual region size used is governed by the optional implementation of the system exit routine IEFUSI.
If you decide to set REGION=0M, it indicates that the address space must be given as much memory as possible, which can result in a system abend878 or abend80A.
The local system queue area (LSQA) grows from the top to the bottom and REGION size grows from the bottom to the top. The free storage that is available is in the middle of the two. If there is no limit in the REGION size, it can grow until it reaches the LSQA limit, causing an abend.
Abend878 and abend80A happen if there is not enough contiguous MVS storage available to satisfy an MVS GETMAIN request. This potential problem is illustrated in Figure 5-6 on page 84.
Figure 5-6 Typical memory allocation for a 31-bit Gateway daemon address space on z/OS
Footnote 1 in Figure 5-6 shows that for LSQA/SWA/229/230", the size normally grows to a high-water-mark and then remains constant.
|
Note: Java.lang.OutOfMemory is not always a sign of insufficient heap. If there is an error in the thread creation, it manifests, in Java, as out of memory.
|
For more information about memory usage, see the topic, Avoiding out of memory conditions for additional suggestions, in the CICS TG Information Center:
5.5.2 Storage and EXCI in the Gateway daemon for z/OS
The EXCI support in the Gateway influence the storage allocation needs.
When EXCI is enabled (by default), the following formula to calculate potential maximum virtual storage requirements of the Gateway daemons is in operation:
70000 + (heap max/ 1024) + (128 * maxconnect) + (1200 * maxworker)
When EXCI is disabled (environment variable CTG_EXCI_INIT=NO), the following formula is in operation:
70000 + (heap max/ 1024) + (128 * maxconnect) + (650 * maxworker)
|
Note: The TRACESZE defined in DFHXCOPT will be allocated as 16 Kb if the trace is OFF. Carefully consider the size of the trace because it will be allocated for each of the worker threads.
|
5.5.3 Using a 64-bit Gateway daemon on z/OS
If you run your Gateway with large numbers of clients and large container payloads (that require a heap size more than 2048 MB), consider using a 64-bit z/OS Gateway. This is possible implementing the 64-bit Java technology, using the 64-bit JDK.
Configuring the Gateway to run as a 64-bit z/OS Gateway, consider the z/OS JCL parameter MEMLIMIT. It sets the limit on how much virtual storage above the bar the Gateway can use. If you do not set MEMLIMIT, the system default is 0, which means that no address space can use virtual storage above the bar. You can set an installation default MEMLIMIT through SMFPRMxx in PARMLIB or by using the IEFUSI exit.
You can also benefit from the -Xcompressedrefs Java option. It allows you to compress references. The JVM stores all references to objects, classes, threads, and monitors as 32-bit values. The -Xcompressedrefs and -Xnocompressedrefs command-line options enable or disable compressed references in a 64-bit JVM. Only 64-bit JVMs recognize these options.
A command-line option can be used with -Xcompressedrefs to allocate the heap specified with the -Xmx option, in a memory range of your choice. This option is -Xgc:preferredHeapBase=<address>, where <address> is the base memory address for the heap.
In Example 5-2, the heap storage of 2048 MB is located at the 4 GB mark. This leaves the lowest 4 GB of address space for use by other processes, and the references are kept in the 64-bit storage.
Example 5-2 Heap storage at 4 GB mark example
CTGSTART_OPTS=-j-Xms256M -j-Xmx2048M -j-Xgc:preferredHeapBase=0x100000000 -j-Xcompressedrefs
For a detailed explanation about tips for Java on z/OS, see this website:
The 64-bit z/OS Gateway implementation also permits the use of z/OS large pages. The z/OS large page provides better performance by decreasing the number of translation lookaside buffer (TLB) misses that an application can incur. The large page support increases the page size from 4 KB to 1 MB. It was introduced in z/OS V1R10 for the IBM z10™ EC models. You need to check your hardware level and operating system level for the support of z/OS large pages. When large pages are used in addition to the existing 4 KB page size, they are expected to reduce memory management overhead for maximizing applications.
To implement these large pages, you need to specify the amount of real storage to be used for managing them. Management is done by coding the keyword LFArea in IEASYSxx, as shown in Example 5-3 on page 86.
Example 5-3 Coding for z/OS large page
LFArea=(xx%| xxxxxxM | xxxxxxG)
xx% - Percentage of online storage at IPL to be used for large pages
xxxxxxM or xxxxxxG – Amount of online storage at IPL to be used for large pages
Large pages are backed by 256 contiguous 4 KB real storage frames. Large pages will not be pageable. For this reason, you need to estimate the real storage usage.
With z/OS V1R13, a new command was introduced that lets you display the LFAREA current usage, as shown in Example 5-4.
Example 5-4 New command to display the amount of LFAREA
D VIRTSTOR,LFAREA
IAR019I 11.34.10 DISPLAY VIRTSTOR 846
SOURCE = 00
TOTAL LFAREA = 100M
LFAREA AVAILABLE = 100M
LFAREA ALLOCATED (1M) = 0M
LFAREA ALLOCATED (4K) = 0M
MAX LFAREA ALLOCATED (1M) = 12M
MAX LFAREA ALLOCATED (4K) = 0M
For an additional description of large pages, see z/OS Version 1 Release 13 Implementation, SG24-7946.
5.6 z/OS Workload Manager suggestions for CICS TG for z/OS
MVS Workload Manager provides a solution for managing workload distribution, workload balancing, and distributing resources to competing workloads.
Workload management allows you to make the best use of your resources, maintain the highest possible throughput, and achieve the best possible system responsiveness. With workload management, you define performance goals and assign a business importance to each goal.
This section will describe parameters that can influence the Gateway daemon performance.
5.6.1 WLM system-provided special service classes
WLM provides service classes for various system and subsystem address spaces; one of them is called SYSSTC. Started tasks in SYSSTC are assigned a high dispatching priority. If the default service class is left blank, these started tasks are assigned to SYSSTC. For this reason, CICS TG can benefit from this workload association when started as a procedure, without any change in WLM service class association.
The main point is that CICS TG must not be run in the BATCH service class. For maximized utilization of your resources, remember that the Gateway daemon is an important address space that provides workload to CICS, and it must not be considered as a batch job.
5.6.2 Storage Critical option
In a constant Gateway daemon workload, the WLM storage critical parameter has no effect. However, if Gateway daemons do not receive workload during the night, the storage can be stolen from the region. Then, when the workload flow starts again, it can cause a delay until the system gets back the stolen pages. You can assign long-term storage protection to critical address space by using the Storage Critical option of the WLM policy.
With this option, WLM protects an address space by restricting the storage donation to other address spaces. This option can be useful for an address space that needs to retain virtual pages in main storage during long periods of inactivity because it cannot afford paging delays when it becomes active again. Without this function, if main storage enters contention, a stealing algorithm steals the pages least referenced. With long-term storage protection assigned, this transaction address space loses main storage (by stealing) only from transactions of equal or greater importance that need the storage to meet performance goals. The storage of protected service classes is only taken when z/OS runs short on main storage.
5.6.3 MAXCPUTIME
If your Gateway daemon is running for a long time, and it is serving a large workload, you need to consider the z/OS UNIX parameter MAXCPUTIME. z/OS WLM can suspend the Gateway daemon address space if the maximum CPU time provisioned for an address space is exceeded.
MAXCPUTIME is a time limit (in seconds) limiting the CPU time that a process is allowed to use. It is applicable to all the processes that run as daemons (in UNIX System Services terms, a daemon is a process that is started in the background), and therefore, the Gateway daemon is also subject to these limitations.
You can set a system-wide MAXCPUTIME limit in the BPXPRMxx member, or you can set the limit for the Gateway daemon user ID. Use the RACF commands ADDUSER or ALTUSER to specify the CPUTIMEMAX limit on a per-process basis, for example:
ALTUSER userid OMVS(CPUTIMEMAX(nnnn))
Alternatively, specify the parameter CPUTIMEMAX in the OMVS segment for the RACF user ID of the Gateway daemon.
5.7 Statistics
CICS Transaction Gateway is a key part of your IT infrastructure. It is therefore essential to optimize your CICS TG system efficiency to eliminate resource bottlenecks and to improve productivity.
The statistics produced by CICS TG allow you to analyze the CICS TG status in the following areas:
•Ensure optimal performance of CICS TG.
•Use your hardware assets optimally.
•Focus on CICS TG resource utilization.
Statistics are available in all CICS TG products, and they can be displayed through modify commands on z/OS and through the ctgadmin command-line tool on other platforms. They are also available for use by external tools, such as the CICS TG plug-in for CICS Explorer and IBM Tivoli OMEGAMON XE for CICS.
CICS TG also provides a mechanism to record interval and end-of-day statistics to System Management Facility (SMF) on z/OS and to an XML file on other platforms. CICS TG SMF records can be analyzed using CICS Performance Analyzer, or by writing your own program to format the statistical records.
For detailed information about the statistics feature, see Exploring Systems Monitoring for CICS Transaction Gateway V7.1 for z/OS, SG24-7562.
..................Content has been hidden....................
You can't read the all page of ebook, please click here login for view all page.