The daily edition.

Scope and Overview

This article covers CICS Web Services implementation and operational mechanics in Rocket Enterprise Developer / Enterprise Server 12.0 for Linux/UNIX.

In enterprise application modernization, CICS applications frequently need to expose existing business logic as service endpoints (provider mode) or consume external network APIs (requester mode) across SOAP and JSON protocols. Rocket Enterprise Server implements mainframe-compatible CICS Web Services, orchestrating network transport, XML/JSON parsing, and COBOL copybook structure transformation through a modular pipeline architecture.

The PIPELINE Architecture and Dynamic Resource Installation

At the core of CICS Web Services is the PIPELINE resource, defined and administered in Enterprise Server Common Web Administration (ESCWA) or via resource definitions. As detailed in the CICS Pipeline Resource documentation, a PIPELINE defines the chain of handler programs that process request and response messages.

The sequence and behavior of these handler programs are governed by an XML pipeline configuration file (CONFIGFILE attribute, such as basicsoap11provider.xml or custom XML configurations). Rather than requiring manual definition of each individual web service and URL endpoint, Enterprise Server implements an automated installation workflow centered around the PIPELINE's Web Directory (WSDIR) attribute:

1. Automated WEBSERVICE Generation: When a PIPELINE resource is installed or the region starts, Enterprise Server scans the directory specified by WSDIR for Web service binding files. As documented in CWS Resources, the runtime automatically creates and installs a dynamic WEBSERVICE resource for every valid binding file (.modsvi or .wsbind) located in that folder.
2. Automated URIMAP Generation: For provider applications, the installation process automatically generates an associated URIMAP resource with USAGE(PIPELINE). This maps the incoming HTTP endpoint path directly to the PIPELINE and target WEBSERVICE.

While administrators can explicitly define a web service using DEFINE WEBSERVICE:

DEFINE WEBSERVICE(SAMPWEB) GROUP(SAMPGRP)
       DESCRIPTION(Sample WEBSERVICE provider)
       PIPELINE(EXPIPE01)
       MODSVI($SAMPDIR/webservices/modsvi/provider/sample.modsvi)

manual definition is rarely necessary because WSDIR auto-discovery handles resource lifecycle registration automatically.

Binding Files and Data Transformation (.modsvi vs. .wsbind)

A WEBSERVICE resource encapsulates the binding definition that transforms data between wire protocols (SOAP XML or JSON) and COBOL data structures:

• MODSVI Format: Beginning in Enterprise Developer 11.0 and continued in 12.0, binding files are generated in MODSVI format with a .modsvi extension using utilities such as ls2ws, ws2ls, ls2js, and js2ls.
• Legacy Compatibility: If an application utilizes .wsbind files generated on a mainframe or in earlier Enterprise Developer releases, Enterprise Server processes them interchangeably.
• WSDL Runtime Behavior: Although a WSDL file can be referenced in the service description, Enterprise Server relies entirely on the .modsvi binding file at runtime; active schema validation against the WSDL document is bypassed for execution efficiency.

Operational Prerequisites and Troubleshooting Diagnostics

Operating CICS Web Services introduces several strict operational requirements and diagnostic mechanisms outlined in Troubleshooting (CICS Web Service):

1. Mandatory Resource Groups

The enterprise server region startup list must include both the DFHWEB and DFHPIPE system resource groups. If these groups are omitted, CICS web service infrastructure programs fail to load during region initialization.

2. CCSID Conversion Table Dependency

During region startup, Enterprise Server initializes character conversion tables. If required CCSID tables are missing or misconfigured, the console logs:

CASSI0017W ES support for CICS WEBSERVICES is disabled. CCSID tables not found

When this occurs, CICS Web Services support is completely disabled across the region, and PIPELINE and WEBSERVICE resources will not appear in ESCWA.

3. JSON Requester Architectural Exception

While SOAP requesters utilize PIPELINE and WEBSERVICE resources, CICS requester applications invoking outbound JSON services bypass the PIPELINE architecture entirely. Instead, they use the JSON linkable interface, which requires a BUNDLE resource containing a JSONTRANSFRM definition.

4. Diagnostic Logging via the CPIO Transient Data Queue

When PIPELINE installation fails to dynamically generate a WEBSERVICE or URIMAP, error details are directed to the CPIO Transient Data Queue (TDQ). Administrators can extract the entire error log by executing the CPIO CICS transaction, which writes a comprehensive report to the Enterprise Server system work directory. Furthermore, enabling Trace Application Handler on an active WEBSERVICE in ESCWA dumps the raw received message, parsed structure, and byte-level COBOL field mapping to disk.

Documentation Takeaway

In Rocket Enterprise Server 12.0, CICS Web Services automate deployment by dynamically generating WEBSERVICE and URIMAP definitions whenever a PIPELINE scans its WSDIR binding directory; operational reliability hinges on having DFHWEB, DFHPIPE, and CCSID conversion tables loaded at startup, with the CPIO transient data queue serving as the primary diagnostic tool when automated binding fails.