Invoking the API requester from a z/OS application

Understand the structure of the COBOL or PL/I z/OS application, how to compile it, run it and extend it. 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 contains more helpful information. Ensure that you follow the steps for the language you chose for your application.
Invoking the API requester from a z/OS application consists of the following steps that must be completed in this sequence:
  1. Preparing the COBOL application
  2. Compiling the COBOL program
  3. Running the COBOL application as part of the IBM z/OS Connect API requester tutorial
  4. Extending the COBOL application as part of the z/OS Connect API requester tutorial

Preparing the COBOL application

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

Before you begin

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

About this task

The following sections in the COBOL application (BAQHRBKZ) include comments to describe how the code functions:

Data division

Working Storage Section

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

One API-INFO copybook, RBKnnI01, is generated for each 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.

One operation request data structure, RBKnnQ01, is generated for each operation. The program populates these structures before it calls the API operation.

Linkage section
One operation response data structure, RBKnnP01, is generated for each operation. The Host API populates these structures after the call to the API operation returns.
Note: These structures are located in the Linkage Section because the COBOL program does not own the backing storage. The Host API owns the storage and it frees that storage when requested to do so by the BAQFREE verb. For more information, see X-FREE.

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

Procedure division

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 or X-EXEC.

A-MAINLINE SECTION
The initial processing section that receives any input that was provided in the JCL PARM statement. B-INIT is called to set up the connection, then the C-EXECUTE is called followed by the X-FREE and X-TERM utility functions to terminate cleanly.
B-INIT
Calls the utility routine X-INIT to get a Host API connection to a IBM® 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.
CA-GET-ALL-REDBOOKS
Performs the processing that prepares a request to the getAllRedbooks operation of the endpoint API application, calls BAQEXEC to make the request, and processes the response by using CAA-GET-EACH-REDBOOK and CAAA-GET-EACH-AUTHOR. For more information about BAQEXEC, see X-EXEC.
CB-GET-REDBOOK
Prepares a request, sends that request, and processes the response. However, unlike CA-GET-ALL-REDBOOKS it contains comments that help you to write the code to perform this operation.
CC-CREATE-REDBOOK
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 by 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. The BAQINIT verb creates a connection to the IBM z/OS Connect Server.
X-PUT-DATA-AREA-ELEMENT
A common routine that you 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 operation that is defined in the calling section.
X-GET-DATA-AREA-ELEMENT
A common routine that 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 calls BAQFREE to free any storage allocated by BAQEXEC.
X-TERM
A common routine that frees the connection to z/OS Connect.

Compiling the COBOL program

Procedure

  1. To compile the COBOL program, transfer the code from COBOL/BAQHRBKZ to a suitable z/OS PDS used for COBOL source.
  2. Transfer the generated copybooks. Copy the files from RedbookApi/build/generated/zosConnectRequester/structures/COBOL/operation/RBKnnx01 to a suitable z/OS PDS used for COBOL copybooks.
  3. Compile and link the program with the output-linked load module made available in a PDS that is available to the JCL that runs the BAQHBRKZ application.

Running the COBOL application as part of the IBM 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 the COBOL application as part of the IBM z/OS Connect API requester (OpenAPI 3.0) tutorial.

Procedure

  1. Configure the JCL to run the tutorial sample. For more information, see Configuring other z/OS applications to access IBM z/OS Connect zosConnect-3.0 for API calls.
  2. Submit the JCL and review the job output. A list of Redbooks is printed in the SYSOUT job output element.
  3. View the output of the job and messages.log of the z/OS Connect Server for any failure messages.

What to do next

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

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

About this task

Start the tutorial by passing the parameter GRBK. Complete the tasks that are contained in the copybook to create a working section. Complete the code by reading the tutorial procedure, referencing the z/OS Connect documentation, and reviewing comments in the section CA-GET-ALL-REDBOOKS.

Procedure

  1. With the z/OS application processing the GARB parameter correctly, look at the COBOL Program BAQHRBKZ in the section CB-GET-REDBOOK.
  2. With parameter GRBK now working, review the section CC-CREATE-REDBOOK, which is started with parameter CRBK.
    Complete the code to call the API endpoint operation createRedbook to create a new Redbook entry. Then, use parameter GARB to check that the new Redbook entry is returned.