CICS Web & API Integration

What is Web & API Integration?

Web & API Integration is a CICS facility that enables applications to participate in web-based architectures using HTTP protocols. It provides the capability for CICS programs to act as web services, consume external web services, and integrate with modern web technologies.

This integration capability allows CICS to bridge the gap between traditional mainframe applications and contemporary web-based systems, enabling organizations to modernize their applications while maintaining the reliability and transaction integrity that CICS provides.

HTTP Server & Client Roles

CICS Web & API Integration supports both server and client roles, allowing flexible integration scenarios. Understanding these roles is essential for designing effective web-enabled CICS applications.

HTTP Server Role

When acting as an HTTP server, CICS can:

• Receive HTTP requests from web clients
• Process requests using CICS applications
• Return HTTP responses with appropriate status codes
• Handle various HTTP methods (GET, POST, PUT, DELETE)
• Manage request/response headers and content

HTTP Client Role

When acting as an HTTP client, CICS can:

• Send HTTP requests to external web services
• Consume RESTful APIs and web services
• Handle various HTTP response codes
• Process response data and headers
• Integrate with external systems and services

Dual Role Capability

CICS applications can simultaneously act as both server and client:

• Receive requests from web clients (server role)
• Call external web services to process requests (client role)
• Return processed results to original clients
• Enable complex integration scenarios
• Support microservices architectures

URIMAP Definitions

URIMAP definitions are essential for configuring web-enabled CICS applications. They define how HTTP requests are routed to CICS programs and specify the mapping between web URLs and CICS resources.

URIMAP Components

A URIMAP definition consists of several key components:

• URI Path: The web URL path that maps to the CICS resource
• HTTP Method: The HTTP method (GET, POST, PUT, DELETE) to handle
• CICS Resource: The CICS program or transaction to execute
• Security Settings: Authentication and authorization requirements
• Content Handling: How request/response content is processed

URIMAP Configuration

URIMAP definitions are configured using RDO commands:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
RDO Commands for URIMAP Setup:
 
DEFINE URIMAP(CUSTOMER-API) -
       GROUP(WEBGROUP) -
       URIPATH('/api/customers') -
       METHOD(GET) -
       PROGRAM(CUSTINQ) -
       TRANSACTION(CUST) -
       SECURITY(USERID) -
       AUTHENTICATE(YES) -
       CONTENTTYPE(JSON)
 
DEFINE URIMAP(CUSTOMER-CREATE) -
       GROUP(WEBGROUP) -
       URIPATH('/api/customers') -
       METHOD(POST) -
       PROGRAM(CUSTADD) -
       TRANSACTION(CUST) -
       SECURITY(USERID) -
       AUTHENTICATE(YES) -
       CONTENTTYPE(JSON)
 
DEFINE URIMAP(CUSTOMER-UPDATE) -
       GROUP(WEBGROUP) -
       URIPATH('/api/customers/:id') -
       METHOD(PUT) -
       PROGRAM(CUSTUPD) -
       TRANSACTION(CUST) -
       SECURITY(USERID) -
       AUTHENTICATE(YES) -
       CONTENTTYPE(JSON)

URI Path Patterns

URIMAP supports various URI path patterns:

• Static Paths: Fixed URL paths like '/api/customers'
• Parameterized Paths: Dynamic paths like '/api/customers/:id'
• Query Parameters: Support for URL query parameters
• Path Variables: Extract values from URL paths
• Wildcard Support: Pattern matching for flexible routing

WEBSERVICE & PIPELINE Resources

WEBSERVICE and PIPELINE resources are essential components of CICS Web & API Integration. They define how web services are configured and how request/response processing flows through the system.

WEBSERVICE Resources

WEBSERVICE resources define the configuration for web service operations:

• Service Definition: WSDL or OpenAPI specification
• Binding Configuration: Protocol and transport settings
• Security Settings: Authentication and encryption requirements
• Error Handling: Fault response configuration
• Performance Settings: Timeout and connection parameters

PIPELINE Resources

PIPELINE resources define the processing flow for web service requests:

• Input Processing: Request validation and transformation
• Business Logic: CICS program execution
• Output Processing: Response formatting and validation
• Error Handling: Fault processing and recovery
• Logging and Monitoring: Request/response tracking

Resource Configuration

WEBSERVICE and PIPELINE resources are configured using RDO commands:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
RDO Commands for Web Service Setup:
 
DEFINE WEBSERVICE(CUST-SERVICE) -
       GROUP(WEBGROUP) -
       WSDL(CUSTSERVICE.WSDL) -
       BINDING(SOAP11) -
       SECURITY(USERID) -
       TIMEOUT(300) -
       DESCRIPTION('Customer Web Service')
 
DEFINE PIPELINE(CUST-PIPELINE) -
       GROUP(WEBGROUP) -
       WEBSERVICE(CUST-SERVICE) -
       INPUTPROGRAM(CUSTINPUT) -
       PROGRAM(CUSTMAIN) -
       OUTPUTPROGRAM(CUSTOUTPUT) -
       ERRORPROGRAM(CUSTERROR)

TLS/SSL in CICS

Transport Layer Security (TLS) and Secure Sockets Layer (SSL) are critical for securing web communications in CICS. Understanding how to configure and manage these security protocols is essential for production deployments.

TLS/SSL Components

TLS/SSL implementation in CICS involves several components:

• Digital Certificates: X.509 certificates for server/client authentication
• Key Rings: z/OS key rings containing certificates and private keys
• Cipher Suites: Encryption algorithms and protocols
• Certificate Validation: Certificate chain verification
• Security Protocols: TLS 1.2, TLS 1.3 support

Certificate Management

Proper certificate management is essential for TLS/SSL security:

• Obtain certificates from trusted Certificate Authorities (CAs)
• Store certificates and private keys in z/OS key rings
• Configure certificate expiration monitoring
• Implement certificate renewal procedures
• Manage certificate revocation lists (CRLs)

TLS/SSL Configuration

TLS/SSL is configured through various CICS parameters:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
TLS/SSL Configuration Parameters:
 
# System Initialization Table (SIT) Parameters
SSL=YES                    # Enable SSL/TLS support
SSLKEYRING=KEYRING1        # Default key ring name
SSLCIPHER=HIGH            # Cipher strength requirement
SSLVERIFY=REQUIRED        # Client certificate verification
 
# URIMAP SSL Parameters
DEFINE URIMAP(SECURE-API) -
       GROUP(WEBGROUP) -
       URIPATH('/api/secure') -
       METHOD(GET) -
       PROGRAM(SECUREPG) -
       SSL(YES) -
       SSLKEYRING(KEYRING1) -
       SSLVERIFY(REQUIRED)

Web Service Programming

Programming web services in CICS requires understanding of HTTP processing, content handling, and web service protocols. This section covers the essential programming techniques for web-enabled CICS applications.

HTTP Request Processing

CICS programs can process HTTP requests using various commands:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
       IDENTIFICATION DIVISION.
       PROGRAM-ID. WEB-CUSTOMER-SERVICE.
       
       ENVIRONMENT DIVISION.
       DATA DIVISION.
       
       WORKING-STORAGE SECTION.
       01  HTTP-REQUEST.
           05  REQUEST-METHOD        PIC X(10).
           05  REQUEST-URI           PIC X(255).
           05  REQUEST-HEADERS       PIC X(1000).
           05  REQUEST-BODY          PIC X(1000).
       
       01  HTTP-RESPONSE.
           05  RESPONSE-STATUS       PIC S9(4) COMP VALUE 200.
           05  RESPONSE-HEADERS      PIC X(1000).
           05  RESPONSE-BODY         PIC X(1000).
       
       01  CUSTOMER-DATA.
           05  CUSTOMER-ID           PIC X(10).
           05  CUSTOMER-NAME         PIC X(50).
           05  CUSTOMER-EMAIL        PIC X(100).
       
       PROCEDURE DIVISION.
       
       MAIN-LOGIC.
           PERFORM PROCESS-HTTP-REQUEST
           PERFORM EXECUTE-BUSINESS-LOGIC
           PERFORM GENERATE-HTTP-RESPONSE
           
           EXEC CICS RETURN END-EXEC
       
       PROCESS-HTTP-REQUEST.
           EXEC CICS WEB READ
               HTTPMETHOD(REQUEST-METHOD)
               URIPATH(REQUEST-URI)
               HTTPHEADER(REQUEST-HEADERS)
               HTTPBODY(REQUEST-BODY)
           END-EXEC
       
       EXECUTE-BUSINESS-LOGIC.
           IF REQUEST-METHOD = 'GET'
               PERFORM HANDLE-GET-REQUEST
           ELSE IF REQUEST-METHOD = 'POST'
               PERFORM HANDLE-POST-REQUEST
           ELSE IF REQUEST-METHOD = 'PUT'
               PERFORM HANDLE-PUT-REQUEST
           ELSE IF REQUEST-METHOD = 'DELETE'
               PERFORM HANDLE-DELETE-REQUEST
           END-IF
       
       GENERATE-HTTP-RESPONSE.
           EXEC CICS WEB SEND
               HTTPSTATUS(RESPONSE-STATUS)
               HTTPHEADER(RESPONSE-HEADERS)
               HTTPBODY(RESPONSE-BODY)
           END-EXEC.

Content Type Handling

CICS supports various content types for web services:

• JSON: JavaScript Object Notation for data exchange
• XML: Extensible Markup Language for structured data
• Text: Plain text content for simple responses
• Binary: Binary data for file transfers
• Form Data: HTML form submission data

Knowledge Check: CICS Web & API Integration