Home
Guides
Sign in
Start typing to search…

z/OS CICS Reverse API Cobol Client Deployment

Installing Generated Clients

This guide provides step-by-step instructions for compiling and deploying an OpenLegacy-generated COBOL program with HTTP API support on IBM z/OS CICS.

Prerequisites:

  • z/OS Version - Minimum: z/OS 2.3 or higher
  • CICS Version - Minimum: CICS Transaction Server 6.1
  • COBOL Compiler Version - Minimum: IBM Enterprise COBOL for z/OS version 6.4
  • Required Libraries and Runtime:
    • z/OS Language Environment runtime installed and configured
    • CICS runtime load libraries are accessible in the environment
  • User Permissions:
    • Read access to source, copybooks, and CICS copy libraries
    • Write access to temporary and load library datasets
    • Execution permissions in CICS for running the load module
    • RACF or equivalent security permissions for compilation, dataset access, and CICS
  • OLREVAPY program compiled:
    To download the OLREVAPY.cbl, please visit the OpenLegacy Download Portal. The file is located under Adapters -> z/OS CICS COBOL . For user access, please contact your OpenLegacy Customer Success representative.

Integrating the Generated COBOL Client into Your Application

The generated COBOL client includes four essential components. Follow these steps to adapt and incorporate it into your program:

Key Components of the COBOL Client

This COBOL module is a generated CICS client created by OpenLegacy’s Reverse API project.

Its main function is to act as a “bridge” between legacy mainframe data structures and modern APIs via OpenLegacy middleware.

Program Structure:

        IDENTIFICATION DIVISION.
      * Please Provide a valid PROGRAM-ID
        PROGRAM-ID. xxxxxxxx.
      ********************************************************
      *             OpenLegacy Hub CICS Client               *
      ********************************************************
      *       Licensed Materials - Property of OpenLegacy    *
      *          "Restricted Materials of OpenLegacy"        *
      *           (C) Copyright OpenLegacy 2015-2025         *
      ********************************************************
      * OpenLegacy Core Version: 5.0.113
      * OpenLegacy DTF Version: 3.0.18
      ********************************************************

       DATA DIVISION.
       WORKING-STORAGE SECTION.
          COPY OLAPICPY.

       LINKAGE SECTION.
       01 DFHCOMMAREA.
        ....
        ....
        ....

        PROCEDURE DIVISION.
      *      MOVE "URIMAP:/URI_MAP" TO OLREVAPI-URL.

      *      MOVE "http//:API_SERVER"
      *        TO OLREVAPI-URL.
            MOVE "/method-path" TO OLREVAPI-SERVICE-PATH.
            CALL OLREVAPI USING
                BY REFERENCE OLREVAPI-CALL-VARS
                BY REFERENCE DFHCOMMAREA
                BY VALUE LENGTH OF DFHCOMMAREA
                BY REFERENCE DFHCOMMAREA
                BY VALUE LENGTH OF DFHCOMMAREA
              RETURNING OLREVAPI-RESULT.

       END-PROGRAM.
            EXEC CICS RETURN END-EXEC.

       END PROGRAM xxxxxxxx.

  • IDENTIFICATION DIVISION

    • Includes program name (PROGRAM-ID.), generation info, licensing, and OpenLegacy core/DTF versions.
    • Set PROGRAM-ID as needed for your deployment.

  • DATA DIVISION

    • WORKING-STORAGE SECTION
      • Uses COPY OLAPICPY. to include the OpenLegacy API interface.
      • The copybook defines variables and connection fields for REST API calls.

  • LINKAGE SECTION

    • Contains the DFHCOMMAREA structure:
      • Automatically generated by OpenLegacy based on your API schema.
      • Includes all business data fields required by your OpenLegacy Reverse API project (e.g., account ID, name, type, currency, balance, etc.).

  • PROCEDURE DIVISION

    • Handles interaction with OpenLegacy API infrastructure:
      • Sets API endpoint and service path variables.
      • Calls the OLREVAPI routine - marshals DFHCOMMAREA data to the API and receives results.
      • Processes result and completes with EXEC CICS RETURN END-EXEC.

About OLAPICPY Copybook:

       01  OLREVAPI PIC X(8) VALUE "OLREVAPI".
       01  OLREVAPI-CALL-VARS.
           05  OLREVAPI-VERSION PIC X(2) VALUE X"0100".
           05  OLREVAPI-URL PIC X(512) VALUE SPACES.
           05  OLREVAPI-SERVICE-PATH PIC X(128) VALUE SPACES.
           05  OLREVAPI-API-KEY PIC X(32) VALUE SPACES.
           05  OLREVAPI-HTTP-STATUS PIC S9(4) COMP VALUE 0.
           05  OLREVAPI-HTTP-STATUS-TEXT PIC X(256) VALUE SPACES.
           05  OLREVAPI-RESP PIC S9(8) COMP VALUE 0.
           05  OLREVAPI-RESP2 PIC S9(8) COMP VALUE 0.
           05  OLREVAPI-PHASE PIC X(20) VALUE SPACES.
           05  OLREVAPI-ABEND-ON-ERROR-FLAG PIC X VALUE "Y".
           05  OLREVAPI-ABEND-ON-HTTP-FLAG PIC X VALUE "Y".
           05  OLREVAPI-VERBOSE  PIC X VALUE SPACE.
               88  OLREVAPI-IS-VERBOSE VALUE "Y".
       01  OLREVAPI-RESULT PIC S9(8) COMP VALUE 0.
  • Core Elements:
    • OLREVAPI: identifier literal (often used to route/control the program flow).
    • OLREVAPI-CALL-VARS main structure for API invocation, includes:
      • OLREVAPI-VERSION: version of the API bridge.
      • OLREVAPI-URL: complete endpoint URL or URIMAP reference.
      • OLREVAPI-SERVICE-PATH: relative API path (e.g., /accountDetails).
      • OLREVAPI-API-KEY: bearer/token for secured endpoints.
      • OLREVAPI-HTTP-STATUS and OLREVAPI-HTTP-STATUS-TEXT: status response from API.
      • OLREVAPI-RESP and OLREVAPI-RESP2: custom response codes/fields.
      • OLREVAPI-PHASE: call or flow status indicator.
      • Control flags for error/HTTP control, verbosity, etc.
        • OLREVAPI-ABEND-ON-ERROR-FLAG halts program on errors if "Y".
        • OLREVAPI-VERBOSE enables detailed logging if "Y".
      • OLREVAPI-RESULT — overall process result code.

How It Works:

  • Every CICS COBOL client generated by OpenLegacy includes the OLAPICPY copybook.
  • The main program copies in OLAPICPY for standardized, reusable API infrastructure.
  • Data and control info (endpoints, keys, phases) are set in OLAPICPY fields before calling OLREVAPI.
  • After the call, the results (including status, data, errors) are accessed via OLAPICPY.

Instructions for COBOL Developers

Overview: JCL Job Template for Compiling OpenLegacy COBOL CICS Client

This JCL template is designed to compile a COBOL CICS client program generated by OpenLegacy.
It uses an external PROC (COBCICS6) for the actual compile and link steps, and specifies datasets and parameters for program input and output.

//${memberName} JOB NOTIFY=&SYSUID
//MYLIB JCLLIB ORDER=(OLS0009.PROCS.JCL)
//COMPILE EXEC PROC=COBCICS6,
//  PGMLIB=${filterValue}.CICS.PGMLIB,
//  GOPGM=${memberName}
//COBOL.SYSIN DD DSN=${datasetName}(&GOPGM),DISP=SHR
//COBOL.SYSLIB DD DSN=${datasetName},DISP=SHR

Key Points

  • Procedure: COBCICS6 (found in OLS0009.PROCS.JCL)

    • Built for CICS Transaction Server 6.1; uses IBM Enterprise COBOL 6.4 compiler and correct runtime/link libraries.
    • Manages COBOL compile, CICS translation, and link-edit in one step.

  • Parameterization:

    • ${memberName} — COBOL source/program name.
    • ${targetLib} — Load library for output module.
    • ${sourcePDS} — Source PDS containing the COBOL source.
    • ${copybookPDS} — Library containing required copybooks (OLAPICPY etc).

  • Customization:

    • Change variable placeholders to match your site's standards and datasets.

  • COPYBOOK Availability:

    • Ensure all referenced copybooks are in ${copybookPDS} and correctly allocated to COBOL.SYSLIB DD.

  • Compatibility:

    • The template leverages site procedures for maintainability and easy upgrades.
    • Optimized for programs generated by OpenLegacy targeting CICS and REST API integrations.

Summary:
Use this template format for OpenLegacy COBOL clients destined for CICS environments, ensuring you specify the procedure, source, copybook, and target libraries according to your site's naming conventions and dataset structure.

Updated 1 day ago