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

Dynamic routing for CICS Web services

This tip describes the benefits of dynamic routing for Web services and how to route Web workloads dynamically in CICS.

Dynamic routing has been a tried-and-true CICS asset for years. It exploits CICS' flexibility to provide better availability, performance and efficiency. Even as IBM adds new functionality, systems programmers find ways to include this important strategy.

More on CICS and web services:
Improve CICS Web services security

Ensuring CICS security with the Web Services Security standard

Manage CICS workloads with transaction classes

Why dynamically route Web services
At first it may seem that Web workloads don't need to be dynamically managed. Web traffic, in the form of HTTP over TCP/IP, may be routed through sysplex distributor, which wisely chooses a target LPAR based on processor availability. On the individual LPAR, a systems programmer provides multiple regions that share the same TCP/IP port, any of which can host the service. This redundancy and semi-intelligent routing ensure perpetual availability and performance for the application.

Most of the time, that is. The aforementioned configuration doesn't do a very good job of accounting for region health while making routing decisions. For instance, it doesn't make sense to route a request for a DB2 application to a CICS that isn't connected to the database management system. The same thing is true for sending work to regions that are short on storage or damaged by storage violations. Making better routing decisions requires at least one level of indirection through something that understands and monitors CICS health.

A listening region (LR) can provide the needed indirection. The traditional LR owns the TCP/IP service and port through which incoming messages arrive. Web services require a little more work, although the basic idea remains the same.

Web service provider flow
When CICS receives an incoming message on a Web service port, it starts the transaction CWXN. CWXN gets enough of the incoming message to match the embedded Uniform Resource Identifier (URI) with a URIMAP definition and retrieve the target Web service's attributes. With the attributes in hand, CWXN uses the Web services bind file (WSBIND) and pipeline configuration file to suss out what to do next. If the bind file names a pipeline transaction, CWXN attaches it. Otherwise, CWXN starts the default, CPIH.

The pipeline transaction gets the rest of the incoming request off of the socket. As it parses the XML, it calls any message header handlers specified in the pipeline configuration file. In addition, CICS will authenticate any security context that may be included in the header.

Message header handlers can, among other things, specify a new transaction or user ID for the Web request. Likewise, the authenticated security identity in the inbound message forces a change in the security context for the rest of pipeline processing. Either circumstance causes CICS start a third transaction to make the context or transaction switch.

Ultimately, no matter the security context or the transaction ID, CICS links into the application program that is intended to provide the Web service. The application program returns the reply, which must travel back up the pipeline chain before CICS boots it back out into the network.

Opportunities for dynamic routing
There are a couple of opportunities for workload distribution since CICS supports both dynamic transaction routing (DTR) as well as distributed program link (DPL). Transaction routing is easily taken care of by defining the pipeline or application transaction as dynamically routable. For DPL, defining the pipeline transactions as local but the target program as routable ensures the request stays on the LR until Web services links to the target application program, thus invoking DPL. The choice itself has some interesting consequences.

DTR probably fits closer to the original intent of an LR, i.e., a region that does little else but talk to the network and decide where to send work. For Web services, a few more things may run in the LR, such as the message header processors, but the application work is done elsewhere.

But, as always, there are implications. Depending on where the routing happens, the Web service and pipeline definitions must be installed on the application-owning region (AOR), to which the LR sends the request. It also means the Simple Object Access Protocol (SOAP) message and the accompanying containers must be passed over the multi-region operation (MRO) link between the LR and AOR. SOAP messages tend to be big, which may be okay for a local cross-memory connection but could spell trouble if the data has to go to another LPAR via Cross-system Coupling Facility (XCF).

The DPL approach is cleaner for several reasons. First, only the application data as already parsed from the incoming request and context containers needs to be sent over the MRO links. Second, all the processing particular to Web services is isolated in the LR and the AOR doesn't need to know anything about it. In fact, the AOR acts as a true server, handling an inbound DPL request, no matter what the source, and providing the output in a container passed back to the LR. However, all the processing to break down the input message work breaks the traditional model of an LR as a lightweight traffic cop. The LR will also be on the hook for the non-trivial of building the outbound SOAP message.

ABOUT THE AUTHOR: For 24 years, Robert Crawford has worked off and on as a CICS systems programmer. He is experienced in debugging and tuning applications and has written in COBOL, Assembler and C++ using VSAM, DLI and DB2.

What did you think of this feature? Write to's Matt Stansberry about your data center concerns at

Dig Deeper on IBM system z and mainframe systems

Start the conversation

Send me notifications when other members comment.

Please create a username to comment.