Developing the client application to call the contacts API

Now you can develop the client IMS or z/OS® application to call the contacts API. To call the API, the client application must include the generated request and response data structures and the API information file to communicate with the IBM® z/OS Connect server.

In this scenario, a sample client application is provided. You can get the sample application from the hlq.SBAQSAMP data set. The sample program name is BAQPHBKI (for IMS), or BAQPHBKB (for other applications). This sample application tries to call the contacts API to invoke the phonebook service. Ensure that you have completed all of the prerequisites for the API requester scenario.

A description of the sample programs are as follows:
  • BAQPHBKI - A sample IMS message processing program (MPP). Work with your IMS system programmer or check the IMS product documentation for instructions on how to define this sample as an MPP to IMS as well as a transaction code through which to invoke it.
  • BAQPHBKB - A sample z/OS batch program.
The names of the generated artifacts for the GET operation are as follows:
  • The request copybook: PHB01Q01
  • The response copybook: PHB01P01
  • The API information file: PHB01I01
Tip: You can find the detailed information about the operations in the generated phonebook-summary.txt file.
The following information walks you through the sample code that demonstrates the steps to call a REST API from an IMS or z/OS application:
  1. For the GET operation to be called, include the generated request data structure, response data structure, and the API information file.
    01  REQUEST.
    COPY PHB01Q01.
01  RESPONSE.
    COPY PHB01P01.
01  API-INFO-OPER1.
    COPY PHB01I01.
  2. Declare variables for the request and response. For more information about the variables, see Variables to declare.
    01 BAQ-REQUEST-PTR             USAGE POINTER.
01 BAQ-REQUEST-LEN             PIC S9(9) COMP-5 SYNC.
01 BAQ-RESPONSE-PTR            USAGE POINTER.
01 BAQ-RESPONSE-LEN            PIC S9(9) COMP-5 SYNC.
  3. Specify the stub program name. 
    77 COMM-STUB-PGM-NAME          PIC X(8) VALUE 'BAQCSTUB'.
  4. Prepare the data for call.
    SET BAQ-REQUEST-PTR TO ADDRESS OF REQUEST
MOVE LENGTH OF REQUEST TO BAQ-REQUEST-LEN
SET BAQ-RESPONSE-PTR TO ADDRESS OF RESPONSE
MOVE LENGTH OF RESPONSE TO BAQ-RESPONSE-LEN
  5. Populate the values for the request.
    MOVE IN-LAST-NAME TO lastName of REQUEST
MOVE 10 TO lastName-length OF REQUEST
  6. Call the communication stub.
    CALL COMM-STUB-PGM-NAME USING
      BY REFERENCE API-INFO-OPER1
      BY REFERENCE BAQ-REQUEST-INFO
      BY REFERENCE BAQ-REQUEST-PTR
      BY REFERENCE BAQ-REQUEST-LEN
      BY REFERENCE BAQ-RESPONSE-INFO
      BY REFERENCE BAQ-RESPONSE-PTR
      BY REFERENCE BAQ-RESPONSE-LEN.
  7. Retrieve the values from the response, when the call is returned.
     IF BAQ-SUCCESS THEN
              DISPLAY "PHBKAPI SUCCESS "
              DISPLAY "Out Message: "
                      OUT-MESSAGE2(1:OUT-MESSAGE2-length)
              DISPLAY "First Name: "
                      OUT-FIRST-NAME2(1:OUT-FIRST-NAME2-length)
              DISPLAY "Extension: "
                      OUT-EXTENSION2(1:OUT-EXTENSION2-length)
              DISPLAY "ZipCode: "
                      OUT-ZIP-CODE2(1:OUT-FIRST-NAME2-length)

Errors might come from the API, the IBM z/OS Connect server, or the z/OS subsystems. A return code and a status code are included in the response message to provide the error detail. In a COBOL program, the special variable RETURN-CODE is set to the value of BAQ-RETURN-CODE. For more information about error handling, see Error handling for API requester calls.