Chapter 14 Key Takeaways

The Core Principle

Your COBOL programs are already services. The web service infrastructure just gives the outside world a way to call them. The COBOL program does not know or care whether it was invoked by a 3270 terminal, an MRO request from another CICS region, or an HTTP request from a mobile app. The pipeline, URIMAP, and TCPIPSERVICE handle protocol and data transformation — the business logic stays clean.

Service Provider Mode (Section 14.2–14.3)

  1. Four resources define a CICS web service provider. TCPIPSERVICE (the TCP/IP listener), URIMAP (the URI-to-program router), PIPELINE (the transformation engine), and WEBSERVICE (the data mapping). Configure them correctly and your existing COBOL program is a REST or SOAP service.

  2. Separation of concerns is non-negotiable. The COBOL business logic program must not contain web-specific commands (EXEC CICS WEB RECEIVE/SEND). The pipeline handles protocol; the program handles business logic. Mixing them creates coupling that will cost you later.

  3. Use different CICS transactions for different channels. Map web service requests to a separate transaction (e.g., AINQ) from 3270 requests (e.g., INQY). This enables separate WLM classification, RACF security profiles, and monitoring metrics per channel.

  4. DFHLS2JS generates JSON mappings from existing COBOL copybooks. Use MAPPING-LEVEL=3.0 for proper decimal handling and trimmed strings. The output is a WSBIND file that the pipeline uses at runtime.

SOAP Services (Section 14.4)

  1. SOAP is mandatory where industry standards require it. Inter-bank messaging (ISO 20022), healthcare (HL7), financial messaging (SWIFT/FpML), and many government interfaces mandate SOAP with WSDL contracts. Don't fight the standard.

  2. DFHWS2LS generates COBOL from WSDL; DFHLS2WS generates WSDL from COBOL. Top-down (WSDL-first) when implementing an external standard. Bottom-up (COBOL-first) when exposing existing programs.

  3. Don't convert working SOAP services to REST for no reason. If a SOAP service is deployed, stable, and meets performance requirements, leave it. Convert only when consumer demand or a new mandate requires it.

Service Requester Mode (Section 14.5)

  1. External service calls hold CICS tasks. Every outbound HTTP call occupies a MAXTASK slot for the duration of the call. If the external service is slow or unresponsive, those tasks pile up. Set aggressive timeouts and implement circuit-breaker logic.

  2. Connection pooling is essential for high-volume requester scenarios. The SOCKETCLOSE parameter on client URIMAPs keeps TCP connections alive for reuse. SecureFirst measured a 70ms improvement per call by eliminating repeated TLS negotiation.

  3. Always design for external service failure. Try live, fall back to cache, degrade gracefully. The credit score lookup pattern — live service → cached DB2 value → manual review flag — is the template for every external dependency.

Data Transformation (Section 14.6)

  1. The WSBIND file is the runtime transformation artifact. Generated by the CICS assistants (DFHJS2LS, DFHLS2JS, DFHWS2LS, DFHLS2WS), the WSBIND contains precompiled mapping rules. Never edit it directly — regenerate from source.

  2. REDEFINES is the most common DFHLS2JS failure. If your COBOL copybook uses REDEFINES, create a wrapper copybook with a flat structure and a thin wrapper program that maps between them. At SecureFirst, 30% of copybooks needed wrappers.

  3. Use channels and containers for payloads over 32KB. COMMAREA has a 32KB limit. Channels have no practical limit. For ISO 20022 messages and large transaction history responses, channels are not optional — they're required.

Performance and Security (Section 14.7)

  1. JSON transformation is fast; XML transformation is not. DFHJSON adds less than 1ms for typical payloads under 5KB. DFHPITP (XML) adds 2–10x more for equivalent sizes. For large ISO 20022 messages, XML parsing can dominate response time.

  2. Never expose CICS directly to the internet. Always place an API gateway in front. The API gateway handles DDoS protection, OAuth2 validation, rate limiting, and request validation — things CICS is not designed to do.

  3. Identity propagation maps external identities to RACF user IDs. The COBOL program runs under the mapped RACF ID, inheriting the user's permissions for DB2, VSAM, and transaction access. Same security model as 3270 — different front door.

  4. Input validation must happen in the COBOL program. JSON schema validation catches format errors. COBOL validation catches business logic errors (invalid account combinations, amounts exceeding limits, unauthorized operations). Both layers are needed.

The Evolution Path

  1. Start simple, graduate when you hit limits. CICS native pipelines for the first few services. CICS Liberty when you have Java skills and need more sophisticated HTTP handling. z/OS Connect EE when you have dozens of services and need centralized API management. Most organizations don't need z/OS Connect EE on day one.

The Big Picture

Web services don't replace COBOL — they amplify it. The business logic that has been running reliably for decades is now accessible from mobile apps, partner systems, cloud services, and anything else that speaks HTTP. The COBOL programs are the most stable, best-tested component in your architecture. The web service layer's job is to present them to a world that has standardized on REST and JSON.

The best CICS web service architecture is the one where nobody on the consuming side knows — or needs to know — that COBOL is behind the endpoint.