CICS COBOL HTTP Client

Owned by Gidi Shalev
Last updated: Sept 30, 2020
2 min read

The API Caller generates an HTTP client for each Endpoint, based on its unique identifier (Endpoint ID) together with its related request and response models.

Generated Files

HTTPCLNT.CBL

The HTTPCLNT.CBL file is an autogenerated example program, written in COBOL, which utilizes CICS WEB API and is therefore suitable to run in a CICS environment.

It is important to note that:

  1. PROGRAM-ID is a unique program name and should be changed according to the organization’s standards before compilation on the legacy system.

  2. The HTTP-STATUS-CODE and HTTP-STATUS-TEXT which are declared as part of the WORKING-STORAGE section, are populated by the actual target Endpoint HTTP response code and message, delegated by the proxy component back to the mainframe.
    For more information see: https://openlegacy.atlassian.net/wiki/spaces/RDKB/pages/203554827

  3. When creating Endpoint metadata, a unique identifier (UUID) is assigned to it.
    This identifier is embedded within each client that is being autogenerated, and can be found in the program’s WORKING-STORAGE section.

    See ENDPOINT-ID-VALUE field

  4. The OPN-URIMAP field value should be specified according to the URIMAP that was configured to call the proxy endpoint.

  5. Each program refers to its request and response models using the COPY statement, and can be found in the program’s WORKING-STORAGE section under the Request and Response copybooks comment.
    Note that the names REQUEST and RESPONSE will change according to the name of the member that was used for compilation.

  6. Because business logic is derived from the organization’s business rules in calling a target API, OpenLegacy does not assume or generate any logic. Instead, it leaves a placeholder for logic at the beginning of the PROCEDURE DIVISION section.

  7. On each call to the proxy endpoint, the Endpoint ID is sent as an HTTP header, This is critical and, therefore, it is generated under the AUTO-GENERATED DO NOT EDIT block.
    See EXEC CICS WEB WRITE block.

Useful Links:

  1. IBM CICS Web Converse

  2. IBM CICS Web Open

  3. IBM CICS Web Close

  4. IBM CICS Web Write Http Header

REQUEST.CPY

The REQUEST.CPY file represents the Endpoint request model.

RESPONSE.CPY

The RESPONSE.CPY file represents the Endpoint response model.
It will always contain:

  1. STATUS-CODE

    • The response code that was delegated from the target API, unless an error occurred

  2. STATUS MESSAGE

    • The response message that was delegated from the target API, unless an error occurred

It may also contain:
RESPONSES

  • A data structure that contains response models based on the metadata provided.

Each status code that may be returned from the target API has a corresponding response model that describes it.
Each response model may contain a HEADERS sections as well.