Configure CICS to access IBM z/OS Connect to call APIs

To enable CICS® applications to call APIs through IBM z/OS Connect, enable the IBM z/OS Connect Host API in the CICS region.

About this task

The IBM z/OS Connect Host API is a module that establishes HTTP connections with the IBM z/OS Connect server, transfers data between z/OS applications and IBM z/OS Connect, and handles completion, reason and status codes that are issued by IBM z/OS Connect. Before your CICS applications can make RESTful API calls, you must configure the Host API in your CICS region.

To set up the IBM z/OS Connect Host API in CICS, you must have the following resources in your CICS region:

A TDQUEUE resource with the name BAQH
This resource defines the transient data queue that is used by the IBM z/OS Connect Host API to log Host API error messages. By default, messages are printed to DD BAQHMSG in the CICS job log.
A URIMAP resource with the name BAQHZCON
This resource handles HTTP client requests from the Host API to the IBM z/OS Connect server.
Multiple PROGRAM resources with the name BAQ*
These resource definitions specify attributes for the IBM z/OS Connect Host API callable interface. By default, these programs are defined as threadsafe.

Sample resources are supplied with IBM z/OS Connect and are provided in a CSD group with the name BAQHCSD.

It is recommended that you use the resources as supplied. Based on the topology you want to use and your CICS and IBM z/OS Connect environment, you will need to modify the attributes of the BAQHZCON URIMAP resource definition.

Procedure

  1. Import the BAQHAPI CSD group into your CICS system by using the DFHCSDUP utility program.
    The supplied BAQHCSD CSD is provided in the hlq.SBAQSAMP data set.
    1. Edit the job control statements that you can use to invoke DFHCSDUP. Include a DD statement that references the hlq.SBAQSAMP data set.
    2. Run the DFHCSDUP utility program.
  2. Modify the BAQHZCON URIMAP resource definition, based on the topology you want to use and system environment.
    1. Specify the host and port of IBM z/OS Connect.
      Note: The HOST attribute and the PORT attribute are mandatory attributes that you must specify based on your IBM z/OS Connect server configuration.
    2. To secure this connection with basic authentication or client authentication, see How to configure basic authentication from CICS or How to configure an AT-TLS connection from CICS.
    3. By default, connection pooling is enabled to keep the connection between CICS and the IBM z/OS Connect server open as a persistent connection. It is set up with the SOCKETCLOSE attribute value set to 30s, which means CICS closes the socket when the socket is idle for 30s.
      If needed, you can specify the SOCKETCLOSE value of 0 to disable connection pooling. For more information about connection pooling in CICS, see Connection pooling for HTTP client performance in the CICS documentation.
  3. Install the BAQH, BAQHZCON, and BAQ* resource definitions in your CICS system.
  4. Define and install a new CICS LIBRARY to include the hlq.SBAQLIB1 data set.

    You have two options to do this:

    • Add a DD statement that references the hlq.SBAQLIB1 data set in the CICS static load LIBRARY concatenation, DFHRPL.

      Note that when CICS is running, changes to DFHRPL are not possible without stopping and restarting CICS.

    • Use a dynamic LIBRARY concatenation to add the load library to CICS.
  5. Setting timeout for CICS to send a request to and receive the response from the IBM z/OS Connect server.

    The IBM z/OS Connect Host API uses CICS web API to communicate with the IBM z/OS Connect server. You can specify DTIMOUT on the TRANSACTION definition to control the timeout of sending a request to IBM z/OS Connect and specify RTIMOUT on the PROFILE definition to control the timeout of waiting a response from IBM z/OS Connect. For more information, see WEB CONVERSE in the CICS documentation.

    Note: Set the same time zone settings for IBM z/OS Connect and the z/OS Application invoking the RESTful API by using the API requester feature. Set time zone settings using the TZ environment variable in the STDENV JCL procedure. For more information on TZ settings, see z/OS Command Format.