Problem solve Get help with specific problems with your technologies, process and projects.

The CICS transaction gateway server basics and tuning

This tip will cover some CTG server basics including a few breadcrumbs about tuning and problem determination.

The CICS Transaction Gateway server is a relatively simple piece of software performing the task of converting clients' TCP/IP requests into CICS EXCI calls. In my experience it does this job well with little fuss, although sometimes it's kind of a black box that makes it hard to figure out what's going on in there. Of course, being written in Java and running in MVS Unix Systems Services (USS) doesn't help. This article will cover some CTG server basics including a few breadcrumbs about tuning and problem determination.

CTG can run by itself or inside of Websphere on the host. I'm most familiar running it as a started task. The JCL for the started task simply invokes the Unix USS shell through proc BPXBATCH. Passed to the shell is the name of the CTG startup script. The IBM supplied script is ctgstart. You may also include command line parameters to control CTG's behavior, including:

  • Listening port number
  • Paths for STDOUT and STDERR
  • Trace and debugging features
  • Number of worker threads

    More on CICS:

    Introductionto the CICS transaction gateway

    CICS statisticsrecords

    By default CTG writes logs and error messages to STDERR and STDOUT in the USS file system. We've tried changing the JCL and CTG to write its log messages out SYSOUT to no avail. Therefore, you will have to get into a USS utility like ISHELL or OMVS to look at STDERR and STDOUT for debugging.

    CTG behavior is controlled through a couple of parameter files. In addition to the above attributes, CTG.INI contains some parameters that cannot be changed from the command line. CTG also reads environment variable files. The environment variable files look more like UNIX scripts and can be used to tailor CTG to your environment. Note that you can put comments in both parameter and variable files with a hash mark ("#") in column 1. For those who want a GUI IBM supplies an X-Windows application, the chief advantage of which is the tool edits the parameters and should always save a valid INI file.

    CTG communicates with CICS through the External Call Interface (EXCI). The connection you define for CTG in your CICS looks a lot like the IRC MRO links defined between regions. You can have specific or generic connections. According to the manual specific links have a small performance advantage but the generic ones work just fine. Like MRO, CTG can use EXCI pipes to talk to CICS regions on other machines through Cross-Coupling Facility (XCF). However, I've seen presentations indicating there's a significant performance hit for doing so.

    IBM provides a mechanism for controlling CTG EXCI pipes through user replaceable module (URM) DFHXCURM. Note that DFHXCURM is an EXCI URM and is not CTG specific. If you have other products or batch jobs that use EXCI, any code you write for DFHXCURM to control the gateway's pipe usage needs to be able to distinguish between them and CTG. DFHXCURM is also limited in its ability to monitor and control pipe allocation. Be sure to consult the manual to make sure you can make it do what you want it to.

    There used to be a 100 pipe per CTG limit until CICS/TS 2.3 raised it to 250. This is hard limit and the only way to get around it is by starting multiple CTG's. Fortunately, CTG supports port sharing, so you can start multiple CTG's on the same LPAR all listening on the same port.

    I do have some advice about setting the maxconnect parameter. Maxconnect controls the maximum number of connection threads CTG starts. Connection threads own the EXCI pipes and CTG starts them as needed according to system activity. If CTG communicates with more than one CICS a connection thread may end up owning more than one EXCI pipe. However, if CTG talks to one CICS exclusively, as is typically done in production, there will be one connection thread for each EXCI pipe. Therefore, if your CTG talks to one region you should set maxconnect to the number of pipes you plan to use. Otherwise, set maxconnect to the quantity of pipes divided by the number of regions CTG will talk to.

    As mentioned earlier, debugging CTG can be difficult. A few years ago I had a situation where the dang thing wouldn't come up and refused tell me why. In desperation I got into TSO, used OMVS to get into the USS shell and started it right there. I finally got the information I needed to figure out the problem written to my screen. Things are a little better now as there are some traces you can turn on. Be judicious, however, because the traces do create a lot of output that can significantly degrade CTG performance.

    I've also found the CTG trace to be useful. If you take an SVC dump of CTG, for instance, with the MVS DUMP command, you can format a CTG trace with CICS' IPCS verb exit DFHPDxxx (where "xxx" is your CICS release level). You will see one trace table for every communication thread. The format and meaning of the entries is documented in the External Interfaces Guide. While this helps a lot there are a few return codes that aren't documented anywhere except a CICS manual.

    You also must be careful how you take the SVC dump. When CTG starts it spawns a new process as a "hidden" MVS address space. In my experience this new address space's name has a 1 appended to the main CTG's name. For instance, if CTGA is the started task, the spawned process' name will be CTGA1. If the original CTG's name is eight bytes long the partner address space will have the same name. Be sure to include both address spaces in your dump command by specifying something like, "DUMP JOBNAME=(CTGA,CTGA1),END"

    The CTG server has different layers of security, varying from none to requiring a user ID and password for every input message. This last option is the most secure but can cause performance problems as CTG beats up the RACF database. It also runs the risk of passing unencrypted passwords over the network. A better option might be CTG's support for the Secure Sockets Layer (SSL). With SSL CTG builds a trust relationship with each server it communicates with through an exchange of certificates. After the trust relationship is established CTG can establish a user's identity from the logon ID supplied in the input message.

    There are a couple of other security pitfalls to watch out for. CICS invokes link security as CTG forwards the message. This means that each user coming through CTG must be authorized for resource DFHEXCI in the SURROGATE class. It also means CTG must be authorized to execute every transaction that passes through it. Finally, while CTG may check a user's credentials, it does not check transaction authority, CICS does that. Therefore, you may run into situations where a user gets all the way through CTG just to get rejected at CICS because he or she wasn't authorized to use the transaction.

    For being so simple the CTG server does something very useful. It allows clients to communicate with mainframe CICS programs through a small API. Even better, the CICS programs access the input stream in a communications area and can usually be ignorant of who sent them the message and how. All this works as a bridge between the past and future while CICS continues to prove its worth as an enterprise transaction server.


Dig Deeper on IBM system z and mainframe systems