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

Not defining Web services in a CICS SOA

Expert Robert Crawford discusses how to use the Web services binding directory to work around defining Web services in a CICS SOA, or service-oriented architecture.

With each great leap into new programming models, CICS systems programmers find themselves defining new and, frankly, weird resources. In the early 1980s, we had the new-fangled DB2 plans. The object-oriented world introduced us to Java, Enterprise JavaBeans and Cobra Servers. CICS Transaction Server 3.2 brought with it pipelines and Web services on the mainframe for the support of service-oriented architecture (SOA). What follows is a brief explanation of how to let your application programmers do the work for you.

The pipeline
From my experience with Web services, it seems that the central resource definition is the pipeline. A pipeline is a logical construct that includes an extensible markup language (XML) file describing how incoming or outgoing Simple Object Access Protocol (SOAP) messages should be processed. Within the configuration file is a list of programs called message handlers. Each message handler's place and data tag specifies when it gets its mitts on the SOAP message as it flows into or out of CICS.

While the pipeline metaphor is apt, I tend to think of it more like an assembly line, where each message handler gets a chance to read or potentially insert XML text into the message before passing it on to the next handler. For example, an outbound message handler might insert security credentials into the header before CICS sends the XML to the server. Conversely, another message handler might extract and authenticate security credentials from an inbound message for resource authorization.

The configuration file syntax diagram as supplied in the CICS Web Services Guide can be daunting for the XML-challenged. Fortunately, IBM supplies a few examples in directory /usr/lpp/cicsts/samples/pipelines.

A pipeline's definition
The Resource Definition Online (RDO) pipeline definition must include the fully qualified configuration file name. But there are a couple of other attributes necessary to round out the definition.

First is the Web services binding directory (WSDIR). Not surprisingly, this attribute points to a directory containing Web service bind files that name the services and tell CICS how to transform SOAP messages from or into language structures. They may also specify a service's location or the program supposed to ultimately process a request.

Second is the "shelf" directory. Inside the shelf directory you will see a subdirectory for each of your regions. Inside each subdirectory are more directories containing working copies of the configuration and bind files defined to that CICS. This is analogous to the process, allowing you to move a program into a DFHRPL library, then issue a new copy command to make it effective. In this case, when a new Web service is installed or refreshed, CICS copies it into the shelf directory. Thereafter you can replace the files in their original locations as many times as you want without impacting the application. Later, when you're ready to use them, a pipeline scan asks CICS to rebuild the Web services and copy the new files into the shelf directory.

Not defining Web services
The WSDIR parameter points to a directory containing any number of bind files. When CICS installs or scans a pipeline, it looks through the WSDIR directory and creates (or replaces) a Web service for every valid bind file it finds.

What took me a while to notice was that one pipeline works for any number of Web services with the same message-handling requirements. The good news is that this makes system management a little easier, as only a few configuration files need be messed with.

The one-to-many relationship between pipelines and Web services has a couple of configuration and change control implications:

  • The test system is likely to have Web services with the same name in different stages of development. This can be easily managed by creating one pipeline definition for each CICS, pointing to a WSDIR unique for that region. When the pipeline is installed or scanned, the bind files particular to that region will be read and Web services created. If you're lucky, you may also get away with having one set of configuration files for all of development.
  • In production you will most likely want to work with one set of configuration and bind files, so you wouldn't need a unique directory for each region. Instead you can put bind files with the same message handling requirements into one directory and define a pipeline referring to that directory. This keeps the number of required definitions to a minimum. In fact, with Web service definition driven by bind files, the pipeline definitions needn't ever change except when you have new message handler requirements.
  • If the application team puts a version number in the Web service name, you can copy bind files to production early, where they will not be built until CICS bounces or someone does a pipeline scan. In fact, it wouldn't hurt to create the Web services early, as they will not be used until the application asks for them. Note that this may not work so well when CICS is the service provider, because the name must be known by the requester.

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.