MainframeMaster
MainframeMaster

COBOL Tutorial

Progress0 of 0 lessons

COBOL Web Services

Web services in COBOL enable COBOL programs to communicate with web-based services and APIs over HTTP/HTTPS. This includes consuming REST APIs, SOAP services, and creating web services that can be called by other applications. On mainframes, CICS provides web service support, allowing COBOL programs to act as both web service clients and servers. Modern COBOL (2014) includes JSON and XML support, making web service integration more straightforward and enabling mainframe COBOL applications to integrate with modern web-based systems.

What are Web Services?

Web services enable applications to communicate over the web:

  • REST APIs: Use HTTP methods (GET, POST, PUT, DELETE) with JSON or XML
  • SOAP services: Use XML with structured protocols and WSDL definitions
  • HTTP/HTTPS: Communication over standard web protocols
  • Platform independent: Services can be called from any platform
  • Language independent: Services work across programming languages

Web services allow COBOL programs to integrate with modern systems, mobile apps, web applications, and cloud services.

CICS Web Services

CICS provides web service support for COBOL programs on mainframes:

CICS WEB Commands

CICS provides EXEC CICS WEB commands for HTTP operations:

cobol
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
       *> Open HTTP connection
       EXEC CICS WEB OPEN
           HOST('api.example.com')
           PORTNUMBER(443)
           SCHEME('HTTPS')
       END-EXEC
       
       *> Send HTTP GET request
       EXEC CICS WEB SEND
           GET
           PATH('/api/customers/12345')
           MEDIATYPE('application/json')
       END-EXEC
       
       *> Receive HTTP response
       EXEC CICS WEB RECEIVE
           INTO(WS-RESPONSE-BUFFER)
           LENGTH(WS-RESPONSE-LENGTH)
           MEDIATYPE(WS-RESPONSE-TYPE)
       END-EXEC
       
       *> Close connection
       EXEC CICS WEB CLOSE
       END-EXEC

CICS handles the HTTP protocol, allowing COBOL programs to focus on business logic.

Example: Calling a REST API

cobol
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
       WORKING-STORAGE SECTION.
       01  WS-RESPONSE-BUFFER  PIC X(5000).
       01  WS-RESPONSE-LENGTH  PIC 9(6).
       01  WS-RESPONSE-TYPE    PIC X(50).
       01  WS-HTTP-STATUS      PIC 9(3).
       01  WS-CUSTOMER-DATA.
           05  CUSTOMER-ID     PIC 9(5).
           05  CUSTOMER-NAME   PIC X(30).
           05  CUSTOMER-EMAIL  PIC X(50).
       
       PROCEDURE DIVISION.
       CALL-REST-API.
           *> Open HTTPS connection
           EXEC CICS WEB OPEN
               HOST('api.example.com')
               PORTNUMBER(443)
               SCHEME('HTTPS')
           END-EXEC
           
           *> Send GET request
           EXEC CICS WEB SEND
               GET
               PATH('/api/customers/12345')
               MEDIATYPE('application/json')
           END-EXEC
           
           *> Receive response
           EXEC CICS WEB RECEIVE
               INTO(WS-RESPONSE-BUFFER)
               LENGTH(WS-RESPONSE-LENGTH)
               MEDIATYPE(WS-RESPONSE-TYPE)
               STATUSCODE(WS-HTTP-STATUS)
           END-EXEC
           
           *> Check HTTP status
           IF WS-HTTP-STATUS = 200
               *> Parse JSON response
               JSON PARSE WS-RESPONSE-BUFFER 
                   INTO WS-CUSTOMER-DATA
               
               DISPLAY "Customer: " CUSTOMER-NAME
               DISPLAY "Email: " CUSTOMER-EMAIL
           ELSE
               DISPLAY "HTTP Error: " WS-HTTP-STATUS
           END-IF
           
           *> Close connection
           EXEC CICS WEB CLOSE
           END-EXEC
           
           EXIT.

Working with JSON

COBOL 2014 includes built-in JSON support for REST APIs:

Parsing JSON Responses

cobol
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
       WORKING-STORAGE SECTION.
       01  JSON-RESPONSE       PIC X(500) VALUE 
           '{"customerId":12345,"name":"John Smith","email":"john@example.com"}'.
       
       01  CUSTOMER-DATA.
           05  CUSTOMER-ID     PIC 9(5).
           05  CUSTOMER-NAME   PIC X(30).
           05  CUSTOMER-EMAIL  PIC X(50).
       
       PROCEDURE DIVISION.
       PARSE-JSON.
           *> Parse JSON into COBOL structure
           JSON PARSE JSON-RESPONSE INTO CUSTOMER-DATA
           
           DISPLAY "Customer ID: " CUSTOMER-ID
           DISPLAY "Name: " CUSTOMER-NAME
           DISPLAY "Email: " CUSTOMER-EMAIL
           
           STOP RUN.

Generating JSON Requests

cobol
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
       WORKING-STORAGE SECTION.
       01  CUSTOMER-DATA.
           05  CUSTOMER-ID     PIC 9(5) VALUE 12345.
           05  CUSTOMER-NAME   PIC X(30) VALUE 'JOHN SMITH'.
           05  CUSTOMER-EMAIL  PIC X(50) VALUE 'john@example.com'.
       
       01  JSON-REQUEST       PIC X(500).
       
       PROCEDURE DIVISION.
       GENERATE-JSON.
           *> Generate JSON from COBOL data
           JSON GENERATE JSON-REQUEST FROM CUSTOMER-DATA
           
           DISPLAY "JSON Request: " JSON-REQUEST
           *> Output: {"customerId":12345,"name":"JOHN SMITH","email":"john@example.com"}
           
           *> Send JSON in HTTP POST request
           EXEC CICS WEB SEND
               POST
               PATH('/api/customers')
               FROM(JSON-REQUEST)
               LENGTH(FUNCTION LENGTH(JSON-REQUEST))
               MEDIATYPE('application/json')
           END-EXEC
           
           STOP RUN.

Working with XML

COBOL 2014 includes XML support for SOAP services:

Parsing XML Responses

cobol
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
       WORKING-STORAGE SECTION.
       01  XML-RESPONSE        PIC X(500) VALUE 
           '12345John Smith'.
       
       01  CUSTOMER-XML.
           05  CUSTOMER-ID     PIC 9(5).
           05  CUSTOMER-NAME   PIC X(30).
       
       PROCEDURE DIVISION.
       PARSE-XML.
           *> Parse XML into COBOL structure
           XML PARSE XML-RESPONSE INTO CUSTOMER-XML
           
           DISPLAY "Customer ID: " CUSTOMER-ID
           DISPLAY "Name: " CUSTOMER-NAME
           
           STOP RUN.

Generating XML Requests

cobol
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
       WORKING-STORAGE SECTION.
       01  CUSTOMER-XML.
           05  CUSTOMER-ID     PIC 9(5) VALUE 12345.
           05  CUSTOMER-NAME   PIC X(30) VALUE 'JOHN SMITH'.
       
       01  XML-REQUEST         PIC X(500).
       
       PROCEDURE DIVISION.
       GENERATE-XML.
           *> Generate XML from COBOL data
           XML GENERATE XML-REQUEST FROM CUSTOMER-XML
           
           DISPLAY "XML Request: " XML-REQUEST
           
           *> Send XML in SOAP request
           EXEC CICS WEB SEND
               POST
               PATH('/soap/service')
               FROM(XML-REQUEST)
               LENGTH(FUNCTION LENGTH(XML-REQUEST))
               MEDIATYPE('application/xml')
           END-EXEC
           
           STOP RUN.

REST vs SOAP

Understanding the differences:

REST vs SOAP Comparison
AspectRESTSOAP
Data formatTypically JSONXML
ProtocolHTTP methods (GET, POST, PUT, DELETE)HTTP with XML envelope
ComplexitySimpler, lightweightMore structured, heavier
DefinitionOpenAPI/SwaggerWSDL (Web Services Description Language)
Use casesModern APIs, mobile appsEnterprise services, legacy systems
COBOL supportJSON PARSE/GENERATE (COBOL 2014)XML PARSE/GENERATE (COBOL 2014)

Error Handling in Web Services

Proper error handling is crucial for web services:

HTTP Status Code Handling

cobol
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
       WORKING-STORAGE SECTION.
       01  WS-HTTP-STATUS      PIC 9(3).
       01  WS-ERROR-RESPONSE   PIC X(1000).
       
       PROCEDURE DIVISION.
       HANDLE-HTTP-ERROR.
           EXEC CICS WEB RECEIVE
               INTO(WS-RESPONSE-BUFFER)
               STATUSCODE(WS-HTTP-STATUS)
           END-EXEC
           
           EVALUATE WS-HTTP-STATUS
               WHEN 200
                   DISPLAY "Success"
                   PERFORM PROCESS-RESPONSE
               WHEN 400
                   DISPLAY "Bad Request - check request format"
                   PERFORM HANDLE-CLIENT-ERROR
               WHEN 401
                   DISPLAY "Unauthorized - check credentials"
                   PERFORM HANDLE-AUTH-ERROR
               WHEN 404
                   DISPLAY "Not Found - resource does not exist"
                   PERFORM HANDLE-NOT-FOUND
               WHEN 500
                   DISPLAY "Server Error - service unavailable"
                   PERFORM HANDLE-SERVER-ERROR
               WHEN OTHER
                   DISPLAY "Unexpected HTTP status: " WS-HTTP-STATUS
                   PERFORM HANDLE-UNKNOWN-ERROR
           END-EVALUATE.

Parsing Error Responses

cobol
1
2
3
4
5
6
7
8
9
10
11
12
       *> Parse error JSON response
       01  ERROR-RESPONSE.
           05  ERROR-CODE      PIC X(10).
           05  ERROR-MESSAGE   PIC X(100).
       
       PROCEDURE DIVISION.
       PARSE-ERROR.
           IF WS-HTTP-STATUS NOT = 200
               JSON PARSE WS-RESPONSE-BUFFER INTO ERROR-RESPONSE
               DISPLAY "Error Code: " ERROR-CODE
               DISPLAY "Error Message: " ERROR-MESSAGE
           END-IF.

COBOL as Web Service Provider

COBOL programs can expose web services using CICS:

cobol
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
       *> COBOL program acting as web service provider
       PROCEDURE DIVISION.
       WEB-SERVICE-ENTRY.
           *> Receive HTTP request
           EXEC CICS WEB RECEIVE
               INTO(WS-REQUEST-BUFFER)
               LENGTH(WS-REQUEST-LENGTH)
               MEDIATYPE(WS-REQUEST-TYPE)
           END-EXEC
           
           *> Parse JSON request
           JSON PARSE WS-REQUEST-BUFFER INTO WS-REQUEST-DATA
           
           *> Process business logic
           PERFORM PROCESS-REQUEST
           
           *> Generate JSON response
           JSON GENERATE WS-RESPONSE-BUFFER FROM WS-RESPONSE-DATA
           
           *> Send HTTP response
           EXEC CICS WEB SEND
               FROM(WS-RESPONSE-BUFFER)
               LENGTH(FUNCTION LENGTH(WS-RESPONSE-BUFFER))
               MEDIATYPE('application/json')
               STATUSCODE(200)
           END-EXEC
           
           EXIT.

This allows external applications to call mainframe COBOL programs via HTTP, making mainframe functionality available as web services.

Best Practices for Web Services

Follow these best practices:

  • Handle HTTP status codes: Always check status codes and handle errors appropriately
  • Validate responses: Validate JSON/XML responses before parsing
  • Handle timeouts: Implement timeout handling for network operations
  • Secure connections: Use HTTPS for sensitive data
  • Error handling: Provide meaningful error messages and logging
  • Validate input: Validate request data before processing
  • Use appropriate formats: JSON for REST, XML for SOAP
  • Document APIs: Document web service interfaces and data formats
  • Test thoroughly: Test with various scenarios including errors
  • Consider performance: Be aware of network latency and response times

Common Web Service Patterns

Pattern 1: REST API Client

cobol
1
2
3
4
5
6
7
8
9
10
11
       *> Call REST API and parse JSON response
       PERFORM OPEN-HTTP-CONNECTION
       PERFORM SEND-HTTP-GET
       PERFORM RECEIVE-HTTP-RESPONSE
       IF HTTP-STATUS = 200
           JSON PARSE RESPONSE-BUFFER INTO DATA-STRUCTURE
           PERFORM PROCESS-DATA
       ELSE
           PERFORM HANDLE-HTTP-ERROR
       END-IF
       PERFORM CLOSE-HTTP-CONNECTION

Pattern 2: SOAP Service Client

cobol
1
2
3
4
5
6
7
8
9
10
       *> Call SOAP service and parse XML response
       PERFORM BUILD-SOAP-REQUEST
       PERFORM SEND-HTTP-POST
       PERFORM RECEIVE-HTTP-RESPONSE
       IF HTTP-STATUS = 200
           XML PARSE RESPONSE-BUFFER INTO DATA-STRUCTURE
           PERFORM PROCESS-DATA
       ELSE
           PERFORM HANDLE-SOAP-ERROR
       END-IF

Pattern 3: Web Service Provider

cobol
1
2
3
4
5
6
       *> Receive request, process, send response
       PERFORM RECEIVE-HTTP-REQUEST
       JSON PARSE REQUEST-BUFFER INTO REQUEST-DATA
       PERFORM BUSINESS-LOGIC
       JSON GENERATE RESPONSE-BUFFER FROM RESPONSE-DATA
       PERFORM SEND-HTTP-RESPONSE

Explain Like I'm 5: Web Services

Think of web services like ordering food:

  • REST API is like calling a restaurant - you tell them what you want (request), they prepare it, and bring it to you (response)
  • JSON is like writing your order on a simple note - easy to read and understand
  • SOAP is like a formal letter with lots of structure - more detailed but also more complex
  • CICS web services is like having a phone system that connects your COBOL program to the restaurant - it handles the calling part
  • Error handling is like what happens when the restaurant is closed or doesn't have what you want - you need to handle those situations

So web services are like ways for your COBOL program to "call" other programs on the internet and get information back - just like ordering food from a restaurant!

Practice Exercises

Complete these exercises to reinforce your understanding:

Exercise 1: JSON Parsing

Create a program that receives a JSON string containing customer data, parses it using JSON PARSE, and displays the customer information.

Exercise 2: JSON Generation

Create a program that generates a JSON string from COBOL data structures representing a product, then displays the generated JSON.

Exercise 3: HTTP Status Handling

Create a program that simulates receiving different HTTP status codes and handles each appropriately with meaningful error messages.

Exercise 4: REST API Call Pattern

Design a program structure for calling a REST API: opening connection, sending GET request, receiving response, parsing JSON, and handling errors.

Exercise 5: Web Service Provider

Design a COBOL program that acts as a web service provider: receives JSON request, processes it, and returns JSON response with appropriate HTTP status.

Test Your Knowledge

1. What does CICS provide for COBOL web services?

  • HTTP client libraries
  • EXEC CICS WEB commands for HTTP operations
  • JSON parsing only
  • XML parsing only

2. Which COBOL standard added JSON and XML support?

  • COBOL 85
  • COBOL 2002
  • COBOL 2014
  • COBOL 74

3. What format do REST APIs typically use?

  • XML only
  • JSON typically
  • Binary
  • CSV

4. What format do SOAP services use?

  • JSON
  • XML
  • CSV
  • Binary

5. How do you parse JSON in COBOL 2014?

  • Using JSON READ
  • Using JSON PARSE
  • Using JSON DECODE
  • Using JSON EXTRACT

6. Can COBOL programs be web service providers?

  • No, only consumers
  • Yes, using CICS web services
  • Only with special compilers
  • Only for SOAP services

Related Concepts

Related Concepts

External Interfaces

Learn about interfacing with external systems

Modern COBOL

Understanding modern COBOL features

JSON Support

Learn about JSON in COBOL

XML Support

Understanding XML in COBOL

Related Pages