A mortgage application arrives from a bank's customer portal. The portal is a modern React application running on a cloud server. The actual mortgage logic, the eligibility rules, the rate tables, the credit assessment, lives in a COBOL program in a CICS region that has been running, battle-tested, for twenty years. The two systems need to talk.
Rewriting the COBOL program is not on the table. Rewriting the portal to speak CICS protocols is not feasible. What is needed is a layer that lets the modern application call the mainframe program using a standard protocol it already understands, without either side knowing much about the other's internal world.
CICS web services provide that layer. A CICS region can expose existing COBOL programs as SOAP web services, reachable over HTTP from any platform. It can also call external web services from within CICS transactions, making a COBOL program an HTTP client. Neither the service provider nor the service consumer needs to change its core logic to participate. The translation is handled entirely by CICS infrastructure.
This post assumes you have read Architecture: CICS and Explained: COBOL. It covers how CICS processes inbound and outbound web service requests, the resource definitions that make it work, and how a SOAP message maps to a COBOL program's data structures.
The Big Picture: Provider and Requester
CICS web services operate in two directions. In provider mode, CICS receives an inbound HTTP/SOAP request from an external caller, maps it to a CICS transaction and COBOL program, executes the program, and returns the response as a SOAP message. The COBOL program is the service. External applications are the consumers.
In requester mode, a CICS transaction initiates an outbound HTTP/SOAP call to an external web service. The COBOL program is the consumer. The external system is the provider. CICS handles the SOAP construction, the HTTP transmission, and the response parsing on behalf of the COBOL program.
Both directions use the same core infrastructure: the pipeline. The pipeline is CICS's processing chain for web service messages. Understanding the pipeline is the key to understanding how CICS web services work.
The CICS Resource Stack
Four CICS resource definitions work together to enable web services. Each has a distinct role. Configuring them correctly is what most of the operational work of CICS web services consists of.
TCPIPSERVICE
The TCPIPSERVICE is the network listener. It opens a TCP/IP port and accepts inbound HTTP connections. A TCPIPSERVICE definition specifies the port number, the protocol (HTTP or HTTPS), and optional security settings such as SSL certificates. A CICS region typically has one or a few TCPIPSERVICE definitions: one for plain HTTP on an internal port and one for HTTPS on a secure port.
All inbound web service requests arrive through a TCPIPSERVICE. The definition identifies the port but does not know anything about which services are available or what the URL paths mean. That routing is done by the URIMAP.
URIMAP
The URIMAP maps an inbound URL path to the CICS resources that should handle it. A URIMAP with `USAGE(PIPELINE)` matches an incoming request URI against its `PATH` attribute and directs the request to a named PIPELINE and WEBSERVICE resource. The path matching supports wildcards, so a single URIMAP can route all requests under `/services/payments/*` to the payments pipeline.
CICS can create URIMAPs automatically when a PIPELINE is installed, derived from the web service binding files in the pickup directory. This dynamic creation means adding a new web service does not always require manually defining a URIMAP: dropping a new binding file into the pickup directory and issuing `PERFORM PIPELINE SCAN` is sufficient.
PIPELINE
The PIPELINE resource defines the processing chain for messages: which message handlers run, in what order, and how they are configured. Every inbound request and every outbound response passes through the pipeline in sequence. The pipeline is defined in an XML configuration file stored in z/OS UNIX System Services, referenced by the PIPELINE resource's `CONFIGFILE` attribute.
The configuration file lists handler programs for each stage of processing. IBM supplies standard handlers for SOAP 1.1 and SOAP 1.2 processing. Custom handlers can be inserted at any point in the chain: for authentication, logging, message validation, or header manipulation. A handler is a CICS program that receives the message in a channel/container structure, processes it, and returns it to the pipeline for the next handler.
A service provider pipeline and a service requester pipeline have different configurations. The provider configuration includes the inbound transport handler (which reads the HTTP request) followed by the SOAP handler (which parses the SOAP envelope) followed by the application handler (which invokes the COBOL program). The requester configuration reverses this: the application handler builds the SOAP request, the SOAP handler wraps it in a SOAP envelope, and the transport handler sends it over HTTP.
WEBSERVICE
The WEBSERVICE resource is the bridge between the SOAP message and the COBOL program. It references a web service binding file (`wsbind`), a binary file generated by the CICS web services assistant tool (`DFHLS2WS` or `DFHWS2LS`). The binding file contains the mapping rules that tell CICS how to transform the XML content of a SOAP body into a COBOL commarea or container structure, and how to transform the commarea result back into XML for the response.
The WEBSERVICE definition also names the CICS program to execute (for provider mode) and references the WSDL that describes the service's interface. CICS uses the binding file at runtime to perform the data transformation: no code in the COBOL program needs to parse XML or construct SOAP envelopes. The program works entirely in its natural data structures.
The Web Services Assistant: DFHLS2WS and DFHWS2LS
The most complex part of setting up a CICS web service is generating the binding file that maps between the COBOL data structure and the XML schema. IBM provides two utility programs to handle this, collectively called the CICS web services assistant.
DFHLS2WS (Language Structure to Web Service) takes a COBOL copybook or a PL/I data structure and generates two outputs: a WSDL file describing the service interface, and a `wsbind` binding file containing the runtime mapping rules. This is the bottom-up approach: you start with an existing COBOL program and expose it as a web service without changing the program at all. The copybook that describes the program's commarea becomes the schema for the web service's input and output messages.
DFHWS2LS (Web Service to Language Structure) takes an existing WSDL and generates the COBOL copybook and `wsbind` file. This is the top-down approach: the web service interface is designed first, and CICS generates the data structures that match it. The generated copybook is then used in the COBOL program's Linkage Section.
In both cases, the `wsbind` file is the runtime artifact. It is placed in the PIPELINE's pickup directory (`WSDIR`). When the PIPELINE is installed or scanned, CICS reads the `wsbind` file, creates the WEBSERVICE and URIMAP resources automatically, and is ready to handle requests. No CICS restart is needed.
How a SOAP Request Becomes a Commarea
The transformation from SOAP XML to COBOL commarea is the core runtime operation of CICS web services. It happens inside the application handler stage of the provider pipeline, driven by the `wsbind` mapping rules.
An inbound SOAP request arrives at the CICS region. The transport handler reads the HTTP headers and places the HTTP body into a CICS container. The SOAP handler parses the SOAP envelope, validates the structure, extracts the `
` element, and places its content into a channel container named `DFHWS-DATA`.The application handler takes the XML content of `DFHWS-DATA` and uses the `wsbind` mapping to convert it field by field into a binary COBOL commarea. An XML element `
The COBOL program runs exactly as it would for any other LINK call. It reads its input from `DFHCOMMAREA`, applies the business logic, writes results back into `DFHCOMMAREA`, and issues `EXEC CICS RETURN`. It has no knowledge that the call originated from a SOAP request.
On return, the process reverses. The application handler reads the output commarea, applies the `wsbind` mapping in the reverse direction, and generates XML. The SOAP handler wraps the XML in a SOAP envelope. The transport handler constructs an HTTP response with the correct headers and returns it to the caller. The caller receives a well-formed SOAP response.
CICS as a Service Requester
In requester mode, a CICS COBOL program calls an external web service as part of its transaction logic. The program does not construct SOAP XML or make HTTP calls directly. Instead, it places its request data into a CICS container and invokes the pipeline infrastructure, which handles the rest.
The typical pattern uses the `EXEC CICS INVOKE WEBSERVICE` command, introduced in more recent CICS releases as the cleaner alternative to manually managing the pipeline flow:
*> Place request data in a container
EXEC CICS PUT CONTAINER('DFHWS-DATA')
FROM(WS-REQUEST-AREA)
FLENGTH(LENGTH OF WS-REQUEST-AREA)
CHANNEL('PAYREQCHAN')
END-EXEC
*> Invoke the external web service
EXEC CICS INVOKE WEBSERVICE('FRAUDSVC')
CHANNEL('PAYREQCHAN')
RESP(WS-RESP)
RESP2(WS-RESP2)
END-EXEC
*> Read the response
EXEC CICS GET CONTAINER('DFHWS-DATA')
INTO(WS-RESPONSE-AREA)
FLENGTH(WS-RESP-LENGTH)
CHANNEL('PAYREQCHAN')
END-EXECCICS takes the data from `DFHWS-DATA`, applies the requester `wsbind` mapping to generate a SOAP request, sends it over HTTP to the endpoint defined in the WEBSERVICE resource's URI, waits for the response, parses the SOAP response back into binary data, and places the result in `DFHWS-DATA`. The COBOL program reads the binary result exactly as it would read any other container. No XML handling appears anywhere in the COBOL program.
SOAP vs REST in CICS
CICS web services, as described so far, are SOAP-based. SOAP is the native protocol: CICS has deep SOAP support, WSDL tooling, and the `wsbind` mapping infrastructure built around it. Most existing CICS web service integrations in production today use SOAP.
REST support in CICS is provided through the HTTP support in CICS web support and through z/OS Connect, which is covered in the next post. CICS can receive and send plain HTTP requests without SOAP envelopes, and COBOL programs can be exposed as REST APIs, but the tooling and resource model differs from the SOAP pipeline model.
For new integrations, z/OS Connect is the preferred approach for REST APIs. For existing SOAP-based integrations, the pipeline model remains the standard. Many production mainframe environments run both: SOAP pipelines for legacy system-to-system integrations established over the past two decades, and z/OS Connect for new REST APIs added as part of modernization programs.
Failure Modes
The most common provider failure is a pipeline configuration error. The PIPELINE resource installs successfully but the configuration file references a handler program that does not exist, or the `wsbind` file in the pickup directory is corrupt or mismatched with the COBOL copybook. CICS disables the PIPELINE and logs message `DFHPI` errors. The CICS messages and the pipeline trace (`CETR` with pipeline domain tracing) are the diagnostic tools.
A SOAP fault is the protocol-level error response. If the COBOL program abends, if the SOAP body is malformed, or if a validation handler rejects the request, CICS constructs a SOAP fault message and returns it as the HTTP response body with HTTP status 500. The fault includes a fault code and string that identify the failure. Examining the SOAP fault body is the first step when a web service caller reports failures.
In requester mode, the common failure is a timeout. The PIPELINE configuration specifies how long CICS waits for a response from the external service. If the external service does not respond within that window, CICS returns a timeout condition to the COBOL program via the RESP code. The COBOL program must handle this condition and decide whether to retry, roll back, or return an error. If the timeout fires before the external service has processed the request, the program has no way of knowing whether the request was acted on, which is a design concern for any idempotency-sensitive operation.
URIMAP or WEBSERVICE not installed produces an HTTP 404 from CICS. This happens when the pipeline scan has not been run after a new `wsbind` file was placed in the pickup directory, or when the WEBSERVICE resource was not installed due to a binding file error. Running `CEMT PERFORM PIPELINE(name) SCAN` forces a rescan without requiring a CICS restart.
The Full Architecture
Summary
CICS web services give existing COBOL programs a standards-based interface to the outside world without requiring those programs to change. The pipeline processes every inbound and outbound message through a configurable chain of handlers: transport, SOAP envelope parsing, and the `wsbind`-driven data transformation that converts XML to binary commarea and back. The COBOL program never sees XML. It works with the same commarea structures it has always used.
Four resources make this work. The TCPIPSERVICE opens the network port. The URIMAP routes incoming URLs to the right pipeline. The PIPELINE defines the handler chain and its configuration. The WEBSERVICE holds the `wsbind` mapping and names the target program. Together they form a clean separation: the transport concern is separate from the routing concern, which is separate from the message processing concern, which is separate from the business logic itself.
For new REST-based integrations, z/OS Connect extends this model with an API gateway layer that maps REST calls to CICS programs and MQ queues without requiring SOAP at all. That is the subject of the next post.
Part of the Mainframe Decoded series — IBM Z and z/OS, clearly explained for engineers.