Developing z/OS applications to call APIs

The following steps demonstrate how to call an operation of an API from a COBOL program, by using the communication stub.

1. Include the BAQRINFO data structure.
   Add the line COPY BAQRINFO into the WORKING-STORAGE-SECTION of your z/OS application program.

   COPY BAQRINFO

2. Include the request data structure, response data structure, and the API information file that have been generated for the operation you want to call.
   Assuming that the request data structure is API00Q01, the response data structure is API00P01, and the API information file is API00I01, insert the following code snippet:

   
   01 REQUEST.
         COPY API00Q01.
   01 RESPONSE.
         COPY API00P01.
   01 API-INFO.
         COPY API00I01.
   

3. Declare variables for the request, response, and communication stub.
   The following table shows the variables that you need to declare for the request and response. You can choose your own variable names.

   Table 3. Variables to declare

   Variables for COBOL	Description
   BAQ-REQUEST-PTR	Pointer to the storage for request messages.
   BAQ-REQUEST-LEN	Size of the storage for request messages.
   BAQ-RESPONSE-PTR	Pointer to the storage for the response message.
   BAQ-RESPONSE-LEN	Size of the storage for the response message.
   COMM-STUB-PGM-NAME	Program name of the communication stub. The value of the variable must be set to BAQCSTUB.
   COMM-TERM-PGM-NAME	Used to close the reusable connection of BAQCSTUB after IMS unloads the application module. The value of the variable must be set to BAQCTERM.

   For example, insert the following code snippet:

   
   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.
   77 COMM-STUB-PGM-NAME          PIC X(8) VALUE 'BAQCSTUB'.
   77 COMM-TERM-PGM-NAME          PIC X(8) VALUE 'BAQCTERM'.

   Note: If the request or response message is empty, you must set the pointer to NULL and set the storage size to 0, for example, for an empty COBOL request, set BAQ-REQUEST-PTR to NULL and set BAQ-REQUEST-LEN to 0.
4. Populate values for the request.
   1. Assuming Xtext is a parameter in the request data structure API00Q01, insert the following code line:

      MOVE 'How are you' TO Xtext

      Tip: To populate values for a request that contains fields of array or string, you can refer to Sample: Specifying values for arrays and strings.
   2. Specify values for the variables that have been declared for the request and response in Step 3.

      
      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. Call the communication stub with the required parameters.

   In this example, dynamic linkage is used by the CALL identifier statement, where identifier is a variable that is called COMM-STUB-PGM-NAME for the BAQCSTUB load module. The variable is declared in Step 3 with the value of 'BAQCSTUB'.

   
   CALL COMM-STUB-PGM-NAME USING
         BY REFERENCE API-INFO
         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.
   

6. Retrieve the values from the response.

   
   IF BAQ-SUCCESS THEN
           DISPLAY "The program call is successful. "
        ELSE
           EVALUATE TRUE
             WHEN BAQ-ERROR-IN-API
               DISPLAY "API RETURN ERROR: " BAQ-STATUS-CODE
               DISPLAY "API RETURN ERROR MESSAGE: "
                  BAQ-STATUS-MESSAGE(1:BAQ-STATUS-MESSAGE-LEN)
             WHEN BAQ-ERROR-IN-ZCEE
               DISPLAY "Z/OS CONNECT RETURN ERROR: " BAQ-STATUS-CODE
               DISPLAY "SERVER RETURN ERROR MESSAGE: "
                  BAQ-STATUS-MESSAGE(1:BAQ-STATUS-MESSAGE-LEN)
             WHEN BAQ-ERROR-IN-STUB
               DISPLAY "STUB RETURN ERROR: " BAQ-STATUS-CODE
               DISPLAY "STUB RETURN ERROR MESSAGE: "
                  BAQ-STATUS-MESSAGE(1:BAQ-STATUS-MESSAGE-LEN)
           END-EVALUATE
        END-IF.
   

   A return code and a status code are included in the BAQ-RESPONSE-INFO structure. BAQ-RETURN-CODE indicates whether the request was successful or not, and if not where the error originated. In a COBOL program, the special variable RETURN-CODE is set to the value of BAQ-RETURN-CODE. BAQ-STATUS-CODE gives the HTTP status response code. In the sample code, details of the success or failure of the call are written to the job log. For more information about error handling, see Error handling for API requester calls.

7. If you have any long-running API requester applications that use the IMS or z/OS communication stub and cached connections, you must close and clear the cached connection by calling the BAQCTERM function.
   A program that issues one or more API requester calls must call BAQCTERM when it completes its API requester work. If BAQCTERM is not called, the connection that was used by BAQCSTUB is not closed and the memory it owns is not reusable until the IMS or z/OS communication process ends. The following example shows how to call the BAQCTERM function at the logical end of your application.

   CALL COMM-TERM-PGM-NAME USING
         BY REFERENCE BAQ-RESPONSE-INFO.
   
   IF BAQ-SUCCESS THEN
           DISPLAY "The BAQCSTUB connection has been terminated."
        ELSE
           EVALUATE TRUE
             WHEN BAQ-ERROR-IN-API
               DISPLAY "API RETURN ERROR: " BAQ-STATUS-CODE
               DISPLAY "API RETURN ERROR MESSAGE: "
                  BAQ-STATUS-MESSAGE(1:BAQ-STATUS-MESSAGE-LEN)
             WHEN BAQ-ERROR-IN-ZCEE
               DISPLAY "Z/OS CONNECT RETURN ERROR: " BAQ-STATUS-CODE
               DISPLAY "SERVER RETURN ERROR MESSAGE: "
                  BAQ-STATUS-MESSAGE(1:BAQ-STATUS-MESSAGE-LEN)
             WHEN BAQ-ERROR-IN-STUB
               DISPLAY "STUB RETURN ERROR: " BAQ-STATUS-CODE
               DISPLAY "STUB RETURN ERROR MESSAGE: "
                  BAQ-STATUS-MESSAGE(1:BAQ-STATUS-MESSAGE-LEN)
           END-EVALUATE
        END-IF.
   

   As in step 6, if the BAQCSTUB connection ends successfully, the job log indicates that the connection termination is successful; otherwise, the job log displays the detailed error message.