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
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.
- 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 request copybook:
- The response copybook:
- The API information file:
- 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.
- Declare variables for the request and response. For more information about the variables, see
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.
- Specify the stub program name.
77 COMM-STUB-PGM-NAME PIC X(8) VALUE 'BAQCSTUB'.
- Prepare the data for
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
- Populate the values for the
MOVE IN-LAST-NAME TO lastName of REQUEST MOVE 10 TO lastName-length OF REQUEST
- Call the communication
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.
- Retrieve the values from the response, when the call is
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.