Invoking the API requester from a CICS application

Understand the structure of the CICS® COBOL or PL/I application, how to compile it, run it and extend it. Both the COBOL and PL/I programs are functionally the same.

zosConnect-3.0 Applies to zosConnect-3.0.

Started task Applies to z/OS Connect Servers run by using a z/OS started task procedure.

Note: The following steps are similar for both COBOL and PL/I and use sample files with a common name, BAQHRBKZ, which has further helpful information. Make sure that you are following the steps for the language you have chosen for your application.
Invoking the API requester from a CICS application consists of the following steps, which must be completed in this sequence:
  1. The CICS COBOL application
  2. Configuring CICS for the z/OS Connect API requester tutorial
  3. Compiling the CICS COBOL program
  4. Running the CICS COBOL application as part of the z/OS Connect API requester tutorial
  5. Extending the CICS COBOL application as part of the z/OS Connect API requester tutorial

The CICS COBOL application

Understand the structure of the CICS COBOL application and how to compile it.

Before you begin

All tasks in the API requester tutorial topic must first be completed. Creating an IBM z/OS Connect API requester project and z/OS application

About this task

The CICS COBOL application (BAQHRBKC) has many comments to describe what the code is doing and has sections that are detailed in this topic:

For more information about Host API, see Understanding the Host API.

DATA DIVISION

Working Storage Section

The copybooks BAQHAREC and BAQHCONC are referenced. These contain the static data structures that are used by the Host API. For more information about where these copybooks are located, see Understanding the Host API.

The generated API-INFO copybooks are referenced, RBKnnI01, one per operation to be called. The API-INFO data structures contain static data that tells z/OS Connect the path and method of the operation to call, and the name of the API.

The generated operation request data structures, RBKnnQ01, are referenced, one per operation. These are populated by the program before calling the API operation.

Linkage section
The generated operation response data structures, RBKnnP01, are referenced, one per operation. These are populated by the Host API after the call to the API operation has returned via z/OS Connect.
Note: These are located in the Linkage Section as the COBOL program does not own the backing storage, the Host API does, and it frees that storage when requested to do so by the BAQFREE verb. For more information, see X-FREE.

PROCEDURE DIVISON

The Procedure division uses common sections that run the Host API callable functions in a reusable way. These common sections are prefixed with X-. For example, X-INIT, X-EXEC.
A-MAINLINE SECTION

This is the initial processing section and receives any terminal input that is associated with the transaction invocation. B-INIT-TX is then called to set up the transaction. Then, the transaction executioner C-EXECUTE-TX is called followed by the X-FREE and X-TERM utility functions to terminate cleanly.

B-INIT-TX

Sets the CICS ABEND handler and calls the utility routine X-INIT to get a Host API connection to a z/OS Connect Server instance.

C-EXECUTE
Based on the invocation transaction, one of CA-GET-ALL-REDBOOKS, CB-GET-REDBOOK, CC-CREATE-REDBOOK, CD-PATCH-REDBOOK, or CE-MERGE-REDBOOK is called.
C-EXECUTE-TX

Based on the invocation transaction one of CA-GET-ALL-REDBOOKS, CB-GET-REDBOOK, or CC-CREATE-REDBOOK is called.

CA-GET-ALL-REDBOOKS

This section performs processing to prepare a request to operation getAllRedbooks of the endpoint API application, makes the call via BAQEXEC and processes the response by using CAA-GET-EACH-REDBOOK and CAAA-GET-EACH-AUTHOR. For more information BAQEXEC, see X-EXEC.

CB-GET-REDBOOK

This section must also prepare a request, run that request, and process the response. However, unlike CA-GET-ALL-REDBOOKS it contains TODO's comments that help you, the CICS application developer, write the code to perform this operation.

CC-CREATE-REDBOOK

This section is also to be written by you, to create a new Redbook by calling the createRedbook operation of the endpoint API application. You write CCAA-PUT-EACH-AUTHOR and X-PUT-DATA-AREA-ELEMENT to build the request authors Data Area using the BAQPUTN verb. However, there are even fewer TODOs to help you!

CD-PATCH-REDBOOK

This section shows an example of using RFC6902 to update a Redbook entity on a field-by-field bases.

CE-MERGE-REDBOOK

This section shows an example of using RFC7396 to update a Redbook entity on a field-by-field bases.

X-INIT

A common routine that is used to call the Host API BAQINIT verb possibly passing a URIMAP Parameter if one has been set up. The BAQINIT verb creates a WEB pooled connection from CICS to the z/OS Connect Server defined by the supplied or default URIMAP.

X-PUT-DATA-AREA-ELEMENT

A common routine that you will write to put a Data Element into a Data Area. The section calls BAQPUTN, passing the Data Area name, element address, and element size that is defined in the calling section.

X-EXEC

A common routine that is used to call the Host API BAQEXEC for any given operation that has been defined by the calling section.

X-GET-DATA-AREA-ELEMENT

A common routine is used to get the next element from a Data Area provided by the BAQEXEC response. The section calls BAQGETN passing the Data Area name and element size that is defined in the calling section.

X-FREE

A common routine that frees any storage that is allocated by BAQEXEC by calling BAQFREE.

X-TERM

A common routine the frees the CICS web connection to z/OS Connect back to a pool for future use by using BAQTERM. CICS maintains the z/OS Connect connection for a specific period to allow for quicker reuse of the connection again with BAQINIT.

Compiling the CICS COBOL program

Procedure

  1. To compile the CICS COBOL program, transfer the code from COBOL/BAQHRBKC to a suitable z/OS PDS used for copybooks.
  2. Transfer the generated copybooks from RedbookApi/build/generated/zosConnectRequester/structures/COBOL/’operation’/RBKnnx01 to a suitable z/OS PDS used for copybooks.
  3. Compile and link the program by using your appropriate site CICS compilation JCL. With the output-linked load module made available in a PDS that is in the CICS region DFHRPL PDS concatenation.

Configuring CICS for the z/OS Connect API requester tutorial

Before you begin

The following tasks must be completed.

About this task

The CICS region in which you are planning to run the tutorial must be configured with the tutorial program and transaction definitions. Use the following steps to process the CSD file provided in the tutorial. The BAQHRBKD CSD file is provided in the CSD subfolder of the tutorial. This CSD defines the program BAQHRBKC, and three transactions that call it, to CICS in the group BAQHRBKG.

Procedure

  1. Copy the example commands in the BAQHRBKD CSD file to an existing JCL file that runs DFHCSDUP.
  2. Submit this JCL to update the tutorial CICS region's CSD with the tutorial definitions.

What to do next

Deploy a z/OS Connect Server to run the z/OS Connect API requester tutorial.

Running the CICS COBOL application as part of the z/OS Connect API requester tutorial

Before you begin

The following tasks must be completed.

About this task

This task takes you through the steps to run to the CICS COBOL application as part of the z/OS ConnectAPI requester (OpenAPI 3.0) tutorial.

Procedure

  1. Logon on to your CICS region and run the transaction GARB. A list of 10 Redbooks® is displayed on the workstation. Browse the TDQ BAQH (DD BAQHMSG) for any possible errors if the list of 10 Redbooks is not displayed.
  2. View the CICS region Job output CEEMSG for debug trace of the GARB transaction execution.
  3. View the messages.log of the IBM® z/OS Connect Server for any failure messages.

What to do next

You have completed the first operation of the z/OS ConnectAPI requester tutorial.

If you would like to extend the CICS COBOL application, see Extending the CICS COBOL application as part of the z/OS Connect API requester tutorial.

For more information on z/OS ConnectAPI requester, see Developing an API requester.

Extending the CICS COBOL application as part of the z/OS Connect API requester tutorial

Before you begin

The following tasks must be completed.

About this task

There are two more transactions in the tutorial program, GRBK, and CRBK. However, they aren't fully implemented and contain several tasks for you to complete to create a working transaction. By reading the tutorial procedure, referencing the z/OS Connect documentation, and reviewing the section CA-GET-ALL-REDBOOKS you are able to complete the required code.

Procedure

  1. Implement the Get Redbook operation by looking at the COBOL Program BAQHRBKC in section CB-GET-REDBOOK and following the comments in the section.
  2. Next, review the section CC-CREATE-REDBOOK, which is started with transaction CRBK. This sections comments are more terse, but with the knowledge you have gained, complete the code to call the API endpoint operation createRedbook to create a new Redbook entry. Then, use transaction GARB to check that your new Redbook entry is returned.