Access to CICS From WebSphere Application Server Using CICS Transaction Gateway

By Elena Nanos

Most organizations today are trying to maintain a delicate balance

between staying competitive and meet-ing demanding business needs, while keeping development costs down. To help meet customer demands and pro-tect your investment in CICS legacy applications, IBM continues to enhance CICS Transaction Gateway (CTG), which runs on z/OS, Linux, Linux on System z, AIX, Solaris, HP-UX, and Windows. This article provides an overview of architectural choices using different CTG topology to integrate CICS and WebSphere Application Server (WAS) on z/OS and distributed platforms, modes of implementation, and J2EE Connection Architecture (JCA) resource adapters. It also examines the tools available for problem determination

and monitoring, and new enhancements in CTG V7.1 and V7.2. To help you determine the best way to access CICS from WAS, this article also covers a new offering in WAS on z/OS V7 called WebSphere Application Server for z/OS Optimized Local Adapters (WOLA). This new method of cross-memory local communications between WAS for z/OS and CICS has bi-directional capability, so you can leverage WAS Enterprise JavaBean (EJB) assets as local services from CICS.

Overview CTG is a set of client and server soft-ware components that enable a Java application to invoke services in an attached CICS server. Remote Java cli-ents can call CICS applications using ECI Support and Distribute Program Link (DPL) using COMMAREA or channels and containers (if supported, depending on the CICS and CTG level). CTG is a widely used J2EE connec-tor for CICS Transaction Server (CICS TS) and, in conjunction with WAS, pro-vides a high-performing, secure, scal-able, tightly integrated access method in CICS. CTG is scalable, performs well with minimum overhead, and usually doesn’t require any changes to existing CICS applications. By using CTG, you can expand the value of your existing CICS legacy applications and take advantage of WAS functionality. CTG provides a range of networking options and a choice of Java and non-Java client programming interfaces. The client application can be a Java applica-tion or non-Java application using either

C, C++, COBOL, or COM interfaces.

JCA and CTG Topology Before we delve into CTG topology and available resource adapters, let‘s review JCA, which defines a standard for connecting Java 2 Enterprise Edition (J2EE) to heterogeneous Enterprise Information Systems (EISs) such as CICS. The architecture defines a set of scalable, secure, and transactional mechanisms that enable the integration of EISs with application servers and enterprise applications. WAS, as a pro-prietary J2EE application server, can be extended to support the resource adapt-er architecture and is then assured of seamless connectivity to multiple EISs. IBM provides a standard resource adapter with the capability to plug into any application server that supports the connector architecture. The Qualities of Service (QoS) provided by the JCA vary, depending on the topology in use. Figure 1 shows CTG and WAS topology choices. With topology 1, WAS and CTG are deployed on a distributed platform. Both ECI and External Presentation Interface (EPI) resource adapters can be used in this configuration. To exploit CTG V7, WAS must be at V6.1 or high-er. With topology 2, WAS is deployed on a distributed platform and CTG is on z/OS. Using this configuration, you can exploit CTG V7 with WAS V6.0 using CTG remote mode. This topology offers several advantages:

• CTG scalability and availability enhancements

• IP workload management functions, including Sysplex Distributor and TCP/IP port sharing

• Two-Phase Commit (TPC) support• Optimized TCP/IP networking, which

provides faster response times in high-bandwidth networks

• Storm drain avoidance for fine-grained control of health updates to Workload Manager (WLM)

• Extended real-time monitoring of CTG, which provides advanced capac-ity planning and problem determina-tion facilities

• Interval-based statistics and offline recording to System Management Facility (SMF)

• Ability to reduce the CPU cost of the gateway daemon processing, which is written in the Java language, by exploiting System z Application Assist Processor (zAAP) specialty engines. Figure 1: Topology Choices With CTG and WAS

4 2   •   z / J o u r n a l   •   D e c e m b e r   2 0 0 9 / J a n u a r y   2 0 1 0 z / J o u r n a l   •   D e c e m b e r   2 0 0 9 / J a n u a r y   2 0 1 0   •   4 2

(Specifically, using the External Call Interface [EXCI] protocol, 40 percent of the workload is zAAP-eligible. While using CTG V7.2 and the IP Interconnectivity (IPIC) protocol, 90 percent of the workload is zAAP-eli-gible.)

With topology 3, WAS and CTG both run on z/OS. CTG runs on the same Logical Partition (LPAR) as WAS for z/OS and only the CICS ECI resource adapter is supported. This solution pro-vides many of the same benefits as topology 2, plus CTG can run under WAS for z/OS JVM, using cross-memo-ry communication for substantial per-formance improvements.

Modes of Operation There are two modes of operation with CTG and WAS: local and remote. In local mode, CTG runs inside WAS for z/OS servants such as Java Virtual Machines (JVMs). Using CTG in local mode is desirable if you want to use Resource Recovery Services (RRS) for optimized TCP recovery, automatic ThreadIdentity, and the lowest path length. When CTG is on the same LPAR as WAS for z/OS, it’s more efficient to use the CTG classes in WAS for z/OS for gateway functionality. This mode lets WAS for z/OS manage the connections and threads, and reduces communica-tions overhead using cross-memory communication. Figure 2 demonstrates running CTG in local mode. It’s possible to run in a local mode when WAS is deployed on Linux on System z. This configuration provides a highly flexible, scalable environment based on the virtualization capabilities of IBM z/VM and Linux systems. One of the advantages of this configuration is that you can use the IBM HiperSockets hardware feature to provide a highly efficient, cross-memory transport for TCP/IP-based communication into CICS. The JCA QoS for this configura-tion is the same as described for topol-ogy 1 (see Figure 3). Remote mode of operation is when CTG runs stand-alone and has gateway daemon. On z/OS, it runs under z/OS UNIX System Services as a started task. Using the gateway in stand-alone mode on z/OS allows building of a High Availability (HA) configuration. It also provides support for remote clients, Secure Sockets Layer (SSL) support, systems monitoring statistics, and SMF recording. Figure 4 demonstrates run-

ning CTG in remote mode.

Resource Adapters CTG uses the CICS ECI resource adapter, which is a system-level software driver that a Java application uses to connect to an EIS. A resource adapter is installed into an application server and provides connectivity between the EIS, the application server, and the enter-prise application. These adapters come with CTG and are installed under WAS for z/OS when running in a local mode. The Resource Adapter Archives (RAR files) are supplied in the <install_path>/deployable directory. The following resource adapters are

provided for use with CTG on z/OS:

• cicseci.rar: This CICS ECI non-XA resource adapter provides one-phase transactional support (known as local transaction support) when deployed into WAS on any supported platform. This adapter avoids the overhead of unnecessary XA flows.

• cicsecixa.rar: The CICS ECI XA resource adapter provides two-phase transactional global support when deployed into WAS on any supported platform. It should be used when there are updates to two or more resource managers (i.e., CICS and DB2) as part of a global transaction. This adapter

Figure 2: CTG in Local Mode

Figure 3: CTG and WAS on Linux on System z

4 3   •   z / J o u r n a l   •   D e c e m b e r   2 0 0 9 / J a n u a r y   2 0 1 0 z / J o u r n a l   •   D e c e m b e r   2 0 0 9 / J a n u a r y   2 0 1 0   •   4 3

has more overhead.

A word of caution about using a non-XA resource adapter: If your appli-cation is doing read-only in CICS, you may wish to consider turning the CICS call into a SYNCONRETURN call to prevent RRS from coordinating a unit of work, since EXCI calls to CICS always participate in TPC, even if CICS is doing read-only. (IBM recommends wrapping the call to CICS inside a UOWAction object and passing it to UOWManager.runUnderUOW with U O W _ T Y P E _ L O C A L _TRANSACTION. This applies only to calls from container-managed transac-tions marked as transactional if the requests are non-transactional [NotSupported or Never]; then syncon-return calls will be issued to CICS any-way.) Rollback exceptions in WAS can occur for z/OS global transactions using the non-XA resource adapter and include CICS read-only calls in Message-Driven Bean (MDB) Unit Of Work (UOW) that also does updates to WebSphere MQ (WMQ) and DB2. You can address this issue by separating CICS calls in a local transaction UOW. When using the CTG in a local mode with WAS for z/OS, either cicseci.rar or cicseciXA.rar can be used; both support the RRS transaction support in WAS for z/OS.

EXCI Pipes Once you have a working CTG con-figuration, you can start focusing on tuning. EXCI pipe settings can impact your throughput rate and performance.

An EXCI pipe is a virtual session used for cross-memory communica-tions; the EXCI itself is the Application Program Interface (API) used by the batch client, such as the CTG. The maximum number of pipes the EXCI can use was raised to 250. In CTG V6.0, a new enhancement was introduced to reuse EXCI pipes. The CICS J2EE connectors, when run in conjunction with WAS for z/OS, create a cache of EXCI pipes instantiat-ed inside the WAS servant address space. The CTG creates and controls this cache. In addition to the EXCI pipe cache, WebSphere controls a pool of connections obtained from the J2C Connection Factory, the attributes of which are set during deployment of the CICS resource adapter. In WAS, EXCI pipes can be opti-mized based on throughput or concur-rency. Usage can be controlled by configuring the following WAS envi-ronment variables:

• CTG_PIPE_REUSE=ONE lets you allocate one pipe per thread. With this setting, the maximum concurrent number of threads depends on the maximum available number of pipes. The EXCI cache should be limited to one pipe per thread (of the servant region) to avoid pipes being allocated beyond the CICS EXCI pipe limit. Also, using this setting will prevent WAS on z/OS from allocating more pipes than there are threads in the ser-vant region.

• CTG_PIPE_REUSE=ALL lets you reuse all the pipes. Using this setting,

maximum concurrent threads is equal to the maximum number of pipes divided by the number of servers. If you need predictable usage, consider using this setting. This model provides optimum performance, but once a pipe has been allocated, it remains allocated to this particular region and isn’t available for use with other CICS regions.

If you’d like to be alerted when approaching a limit on EXCI pipes in CICS, you can use CICS user-replicable exit, DFHXCURM, to write a warning message to the console.

IPIC With CICS TS 3.2, IBM introduced a new IPIC option that provides CICS communications support over TCP/IP as an alternative to that provided over InterSystem Communication (ISC) and Multi-Region Operation (MRO). Shortly after CICS TS V3.2 became gen-erally available, IBM delivered CTG V7.1, the first release to support IP con-nectivity from the gateway daemon or the resource adapter directly to CICS TS V3.2 or higher. With CTG V7.1 came much-antici-pated support for channels and contain-ers. The IPIC option now lets you send and receive more than 32KB of applica-tion data in a single ECI request and provides additional transaction tracking capabilities. Also, the IPIC networking capabilities of CICS TS provide addi-tional support for SSL and XA TPC connections directly from WAS into CICS and have a fully zAAP-enabled code path. Another important benefit of using IPIC is that WAS on z/OS and CICS need not reside in the same LPAR because XA requests are sent directly to CICS from the CICS ECI XA resource adapter.

CTG V7.2 CTG V 7.2, available since late 2008, runs Java 5 and supports WAS V6.1 and V7.0. When used in remote mode only, it requires the correct resource adapter for the level of WebSphere being used, and also WAS for multi-platforms V6.0, V6.1, and V7.0. CTG V7.2 delivered improved inte-gration for new and existing client run-time environments and a new type of remote client support using the capabil-ities of the gateway daemon. A set of C run-time libraries and language bind-ings were provided, enabling lightweight Figure 4: CTG in Remote Mode

4 4   •   z / J o u r n a l   •   D e c e m b e r   2 0 0 9 / J a n u a r y   2 0 1 0 z / J o u r n a l   •   D e c e m b e r   2 0 0 9 / J a n u a r y   2 0 1 0   •   4 4

client support for ECI requests from remote client environments providing access to CICS COMMAREA-based applications. This support enables potential use in a wide variety of client run-time environments, including C++, COBOL, and Microsoft .NET. CTG for z/OS V7.2 delivers enhanced capability to build HA system architec-ture by integrating with the z/OS Sysplex Distributor and RRS. New features can help your company improve your avail-ability and have greater control in man-aging your overall infrastructure. You can now extend cloned gateway config-urations across the Parallel Sysplex when providing XA support for global transactions from WAS. You should be aware of some impor-tant restrictions when using CTG V7.2 in a Sysplex environment:

• The CICS Transaction Gateway instance must run on the same LPAR as the CICS region to which it’s send-ing requests if you’re using EXCI CICS server connections with the ECI resource adapter, global transactions, or a remote client application with extended Logical Unit of Work (LUW) requests.

• An IPIC connection between CTG and CICS region must not be load bal-anced through any TCP/IP port shar-ing or load balancing software.

• A gateway daemon in a gateway group can be started in any LPAR in the Sysplex, but you must ensure the same RRS logging group is used in each LPAR.

EXCI user-replaceable module DFHXCURM and CICS request exit IBM made several enhancements to help you build an HA solution with CTG; you can now use EXCI user-replaceable module DFHXCURM, which enables you to retry an EXCI request to another CICS region when an EXCI error occurs. EXCI calls DFHXCURM every time it needs to open a new “pipe” to CICS for an initial ECI call for each thread or on pipe re-allocation (if using CTG_PIPE_REUSE=ONE). Note that DFHXCURM is limited to EXCI/COMMAREA requests only. IBM also provides a “DFHXCURM” equivalent with CICS TG 7.2, which supports IPIC. It’s a Java-based user exit called “cicsrequestexit” that allows requests to be redirected. This exit has some advantages over DFHXCURM, but it’s available in remote mode only.

A CICS request exit also can be used to enable dynamic selection of CICS servers for workload balancing. SupportPac CA1T provides a configu-rable failover solution using CICS request exits and offers the ability to build an HA solution and request vali-dation policies.

Tuning Statistics CTG is no longer a “black box,” and starting with CTG 7.0, new monitoring capabilities were introduced using remote mode. CTG V7.0 introduced real-time monitoring capabilities and provided the ability to analyze system utilization metrics and perform online problem determination. It enables access to key statistics about gateway daemon, CICS status, connections, threads, and protocol handlers. This is the first CTG release that lets you retrieve online statistics by issuing a z/OS system MODIFY command against the gateway daemon address space or use an API to do it program-matically. CTG V7.1 further extended real-time monitoring and provides advanced capacity planning and problem deter-mination facilities, and added SMF111 records and analysis via CICS Performance Analyzer (PA) V2.1. With CICS PA SupportPac CP12, you can now use Excel to chart statistical data such as average response times, time-out counts, and peak thread usage indi-cators. Figure 5 shows sample output. CTG 7.1 also enables you to do advanced workload monitoring and get point-of-origin information and trans-action correlation for IPIC requests

using CICSPlex System Manager (SM). Each Java client application can have its own APPLID and APPLID qualifier uniquely identifying it to the gateway daemon. This information can then be used as part of the original data func-tionality, which is part of the new IPIC functionality. New transaction monitor-ing exits can be configured in remote and local mode. This provides an infra-structure for tracing transactions and monitoring the CTG. CTG 7.2 further enhances monitor-ing capabilities and can now integrate with the CICS Explorer, a common, intuitive Eclipse Rich Client Platform (RCP)-based environment for systems administration. Also, a new Java API for systems monitoring is provided, enabling access to the CTG run-time statistics from remote Java clients. For more information on CTG mon-itoring, please refer to IBM Redbook Exploring Systems Monitoring for CICS Transaction Gateway V7.1 for z/OS at www.redbooks.ibm.com/abstracts/sg247562.html?Open.

CTG SupportPac CH51 Monitoring Utility If you’re running CTG in local mode and can’t take advantage of monitoring capabilities available in remote mode only, consider using SupportPac CH51, which is a simple monitoring utility based on the CTG request monitoring exits. It’s designed for auditing purposes and to analyze performance-related issues. This support pac is applicable to CTG in local and remote mode. The output of the exit is kept to a minimum so the performance impact is as low as possible. The utility generates

Figure 5: Performance Data Using CICS PA

4 5   •   z / J o u r n a l   •   D e c e m b e r   2 0 0 9 / J a n u a r y   2 0 1 0 z / J o u r n a l   •   D e c e m b e r   2 0 0 9 / J a n u a r y   2 0 1 0   •   4 5

a one-line message for each ECI request that flows through the gateway. This message lists the total response time for gateway processing along with the CICS call response time and individual details about each request (see Figure 6).

Problem Determination When running CTG in local mode under WAS on z/OS to debug EXCI call-related issues, you have these options:

• Set J2C trace: You can do this via the WAS administrators console by set-ting “WAS.j2c*=all” in Application servers > server > Logging and Tracing > Change Log Detail Levels. WAS server restart is needed to pick up this change. To verify that J2C trace is enabled, check for message BBOO0222I: TRAS0017I: The start-up trace state is *=info:WAS.j2c*=all.

• Set CTG trace: You can do this via WAS admin console by setting gate-way.T.trace custom Property to ‘on’ at Application servers > Process

Definition > Servant > Java Virtual Machine > Custom Properties.

• Run CTG client launch test: You can use the IBM launchClient tool for WAS to test CTG connectivity run-ning J2EE application clients. The launchClient batch command starts the application client run-time that initializes the client run-time, loads the class, and runs the main method of the application client program.

Welcome, WOLA If you’re just starting to develop new interfaces between CICS and WAS for z/OS and are looking for an alternative to CTG (and the costs associated with the license), new functionality in WAS for z/OS V7 may be an alternative, depending on requirements and if con-nectivity between WAS and CICS is on the same LPAR. WOLA is a new function provided with WAS for z/OS maintenance level 7.0.0.4. It provides cross-memory local communications between WAS for z/OS and external address spaces such as

CICS, as well as batch programs and UNIX Systems Services programs. Key advantages:

• Efficient cross-memory transfer from WAS to the external address space or from the external address space into WAS

• Bi-directional capability: You can leverage WAS EJB assets as local ser-vices from external address spaces such as CICS or batch programs. CTG provides only outbound to CICS sup-port.

• Security propagation: From WAS, you can flow the user ID, servant ID, or EJB role ID into the external address space; or from the external address space, you can flow the client ID or, in the case of CICS, the CICS region ID or the CICS task userid.

• Transaction propagation: When oper-ating from CICS into WAS, WAS can participate in a CICS UOW for TPC processing. However, in the initial release of WOLA in Version 7.0.0.4, transaction processing isn’t supported for flows from WAS into CICS, other-wise known as “outbound” from WAS.

CTG vs. WOLA Key differences between CTG and WOLA include:

• CTG provides the ability to access CICS resources from WAS in another LPAR, or platform. WOLA is used only for same-LPAR, cross-memory.

• WOLA can’t route requests to differ-ent CICS regions on different LPARs in the event of a region loss locally. CTG is designed to support HA archi-tecture.

• CTG provides the ability for CICS to participate in TPC; WOLA currently supports only outbound from WAS into CICS.

• CTG uses CICS EXCI API; WOLA has its own API. Some custom code exploiting the WOLA APIs is needed.

IBM positions WOLA not as a replacement for CTG, but as a comple-ment to CTG. Figure 7 highlights advan-tages of using WOLA and CTG. For more information, refer to IBM techdoc WP101490, “A Brief Introduction to WebSphere for z/OS Optimized Local Adapters,” available at www-03.ibm.com/support/techdocs/atsmastr.nsf/WebIndex/WP101490.

Conclusion

Figure 6: Sample CH51 Monitoring Utility Output

Figure 7: Relative Advantages of WOLA and CTG

4 6   •   z / J o u r n a l   •   D e c e m b e r   2 0 0 9 / J a n u a r y   2 0 1 0 z / J o u r n a l   •   D e c e m b e r   2 0 0 9 / J a n u a r y   2 0 1 0   •   4 6

CTG lets you evolve applications without re-inventing the existing busi-ness logic. IBM continues to enhance CTG functionality, performance, avail-ability, system management, and moni-toring. CTG support for JCA allows J2EE applications running in WAS to exploit proven qualities of CICS. Using the JCA simplifies application develop-ment by providing a familiar, standard interface that programmatically manages transactions, connections, and security. Z

AcknowledgementThanks to Phil Wakelin from IBM CICS Strategy and Planning and Don Bagwell from IBM Advanced Technical Support for their help reviewing the article and providing advice on its technical content.

About the Author Elena Nanos is a certified solution expert in CICS Web enablement, WebSphere Application Server ND administration, and MQSeries. She has 27 years of experience in infrastructure support, system architecture, integration, and middleware planning, implementation, and support. She specializes in WebSphere for z/OS, MQSeries, CICS TS, and CTG. She has published numerous technical articles and presented at IBM conferences.Email: elena.nanos@comcast.net

Callout: WOLA is a new method of cross-memory local communications between WAS for z/OS and external address spaces such as CICS.

4 7   •   z / J o u r n a l   •   D e c e m b e r   2 0 0 9 / J a n u a r y   2 0 1 0 z / J o u r n a l   •   D e c e m b e r   2 0 0 9 / J a n u a r y   2 0 1 0   •   4 7