Writing an application that calls the Host API

Use the following procedure to develop a z/OS application to call an OpenAPI 2.0 or an OpenAPI 3.0 defined API by using the IBM® z/OS® Connect Host API.

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.

Before you begin

Before you begin developing your z/OS application to use the zosconnect:oasRequester-1.0 feature in zosConnect-3.0, make sure that you complete the following steps:

If you plan to use the zosConnect-3.0 feature with an OpenAPI 2.0 document, create a new z/OS application rather than modifying an existing one. There are significant differences between the communication stub and the Host API, which makes modifying an existing application complex. However, you can reuse relevant content from your existing z/OS application that is built for the zosConnect-2.0 feature by copying it into the new z/OS application.

About this task

The following procedure demonstrates how to call the getAllRedbooks operation of the sample Redbook API from a COBOL program, by using the z/OS Connect Host API. An example COBOL program is shown that calls the operation to return all the books available. For more information, see the README in the A launch icon to indicate a link opens a new tab or window. OpenAPI 3 API requester Sample.

Procedure

  1. In the Working Storage section of your program, add COPY instructions for the following copybooks.
    • BAQHAREC and BAQHCONC copybooks.
    • The BAQ-API-INFO data structure that was generated for the REST API operation that you want to call. The default format of the copybook name is APInnI01.
    • The generated REST API request data structure. Depending on your API operation semantics, there might not be a request data structure. The default format of the copybook name is APInnQ01.
    For example,
    
       WORKING-STORAGE SECTION.
 
      * API requester Host API required copybooks
       COPY BAQHAREC.
       COPY BAQHCONC.
 
      * API-INFO for Operation getAllRedbooks
       COPY RBK04I01.
 
      * Request structure for Operation getAllRedbooks
       COPY RBK04Q01.
 
  2. In the Linkage Section of your program, add a COPY instruction for the generated REST API response data. Depending on your API operation semantics, there might not be a response structure. The default format of the copybook name is APInnP01.
    For example, 
    
       LINKAGE SECTION.
 
      * Response structure for Operation getAllRedbooks
       COPY RBK04P01.
    The response data structure is located in the Linkage Section because the z/OS Connect Host API manages the storage for the response.
  3. Code the Procedure Division.
    In the Procedure Division, the sample code is organized into several sections to show the usage of the z/OS Connect Host API callable verbs.

    Depending on your z/OS applications execution environment, you can loop through all sections for every request or perform a single initialization, then loop across the normal processing, and finally terminate.

    The Initialization Section calls BAQINIT to acquire a connection to the z/OS Connect Server that is used to process the request. The termination Section calls BAQTERM to release the connection. If the execution environment is CICS® then CICS manages a connection pool on behalf of z/OS Connect.

    For example, 
    
       PROCEDURE DIVISION.
      *----------------------------------------------------------------*
      * A-Mainline
      *----------------------------------------------------------------*
       A-MAINLINE SECTION.
       A-010.

           PERFORM B-INIT.
 
           PERFORM C-EXECUTE.
 
           PERFORM X-TERM.
 
       A-999.
           STOP RUN.
  4. Call BAQINIT to acquire the connection.

    In Section B-INIT, a call is made to BAQINIT to acquire the connection to a z/OS Connect Server. From CICS, a predefined URIMAP called BAQHZCON, is used to locate the server. The name of the URIMAP can be overridden. For more information, see Overriding the URIMAP in a CICS application. From other execution environments, the Language Environment variables BAQHOST and BAQPORT are used.

    Every verb of the z/OS Connect Host API takes the first parameter as a reference to the BAQ-ZCONNECT-AREA. This data structure is used to communicate the effectiveness of the call and sets a completion code that indicates Success, Warning, Error, Severe or Critical. For unsuccessful completion codes, the reason code and message contain more detailed information to identify whether the problem occurred in the Host API call or in the z/OS Connect Server.

    For example, 
    
       B-INIT SECTION.
       B-010.
      * Initialise the Host API
           CALL BAQ-INIT-NAME USING BY REFERENCE BAQ-ZCONNECT-AREA.
 
      * Check for bad initialization
           IF NOT BAQ-SUCCESS THEN
              MOVE BAQ-ZCON-COMPLETION-CODE TO WS-CC9
              MOVE BAQ-ZCON-REASON-CODE TO WS-RC9
              STRING WS-PROGRAM
                 '--INIT failed'
                 '-CC-' WS-CC9
                 '-RC-' WS-RC9
                 DELIMITED BY '>'
                 INTO WS-DISPLAY-MSG
 
              DISPLAY WS-DISPLAY-MSG
              DISPLAY BAQ-ZCON-RETURN-MESSAGE
           END-IF.
 
       B-999.
           EXIT.
    A list of parameters can be supplied in the BAQ-ZCONNECT-AREA that is passed to the Host API, which enables capabilities such as dynamic routing to z/OS Connect Servers from CICS. For more information, see Enabling trace in the Host API for IMS and z/OS applications.
  5. Prepare the request.
    When the connection is established to z/OS Connect Server, you then prepare the request data for the API operation. The address of the request data structure is set in BAQ-REQUEST-AREA. The default name of the generated structure is in the form BAQBASE-APInnQ01 and is copied from the APInnQ01 copybook. The length of this generated data structure must also be set.

    Any API data that the called API operation requires is also set. In this example, the author's name is set.

    For example,
    
       C-EXECUTE SECTION.
       C-010.
      * Prepare the request for sending
           SET BAQ-REQ-BASE-ADDRESS TO ADDRESS OF BAQBASE-RBK04Q01.
           MOVE LENGTH OF BAQBASE-RBK04Q01 TO BAQ-REQ-BASE-LENGTH.
 
      * Find all the Redbooks for a specific author
           MOVE 1 TO Xauthor-existence OF BAQBASE-RBK04Q01.
           MOVE "Lydia Parziale" TO Xauthor2 OF BAQBASE-RBK04Q01.
           MOVE 14 TO Xauthor2-length OF BAQBASE-RBK04Q01.
    Note: The BAQ-REQUEST-AREA can also contain a list of parameters that are used by a z/OS Connect Server to modify the call to the API operation, such as JWT, or OAuth security details.

    If the API operation does not require a request data structure set the request parameters as follows:

               SET BAQ-REQ-BASE-ADDRESS TO NULL.
           MOVE 0 TO BAQ-REQ-BASE-LENGTH.
    If the request data structure contains arrays that are mapped to Data Areas, the BAQPUTN (Put Next) verb must be called to put any required Data Elements into the named Data Area. When the request has Data Areas, the field with a -num suffix is used to specify how many elements are contained within the Data Area, including 0 if there are none. The name of the Data Area is then specified in the field with the -dataarea suffix and is then used when calling the BAQPUTN verb to add each Data Element to the Data Area.
    Note:
    • Data Area names should be between 1 and 16 characters and consist of the following allowed characters A-Z a-z 0-9 $ @ # / % & ? ! : | " = , ; < > . - _
    • Leading and embedded blank characters are not permitted in the name.
    • If the name is fewer than 16 characters, it should be padded with trailing blanks up to 16 characters.
    • The name must not start with the prefix BAQ.
    In the Redbook API example, the createRedbook operation defines a request structure of a book that contains an array of authors. For this operation, the Gradle build generates the following BAQBASE-RBK01Q01 structure to describe the request data: 
             01 BAQBASE-RBK01Q01.
            ...
           03 requestBody.
              06 Xtitle2-length                PIC S9999 COMP-5 SYNC.
              06 Xtitle2                       PIC X(80).
 
              06 authors-num                   PIC S9(9) COMP-5 SYNC.
              06 authors-dataarea              PIC X(16).
            ...
    A further 01 Level language structure is generated to describe the author data that is contained within the Data Area. RBK01Q01-authors provides the representation of a single author:
             01 RBK01Q01-authors.
           03 authors-length                PIC S9999 COMP-5 SYNC.
           03 authors                       PIC X(40).

    By adding each author to the authors-dataarea, using the BAQPUTN Host API verb, dynamic length arrays can be prepared and only the storage that is needed is used for the number of required elements. However, if only a few elements are expected in the array then the Gradle build option inlineMaxOccursLimit can be set.

    For example, if inlineMaxOccursLimit is set to 10 and the maxItems property in the OpenAPI schema for an array type is 10 or less, then the generated language structure contains the array type inline. If maxItems is greater than inlineMaxOccursLimit, a Data Area is used.

    This code example is from the createRedbook operation that creates a new Redbook in the store. Here, you must put each author of the new book into the authors Data Area before calling the BAQEXEC verb. For example, 
          * Create a new book that has 10 authors
           MOVE 10 TO authors-num OF BAQBASE-RBK01Q01.

      * Name the Data Area where the author information will be put
           MOVE "AUTHOR-DATA-AREA" TO authors-dataarea
                                   OF BAQBASE-RBK01Q01.

      * Setup the variables to add authors to the new Data Area
           SET WS-ELEMENT TO ADDRESS OF RBK01Q01-authors.
           MOVE LENGTH OF RBK01Q01-authors TO WS-ELEMENT-LENGTH.
           MOVE authors-dataarea OF BAQBASE-RBK01Q01
                                 TO WS-DATA-AREA-NAME.

      * Prepare the first author
           MOVE 14 TO authors-length OF RBK01Q01-authors.
           MOVE "Lydia Parziale" TO authors OF RBK01Q01-authors.

      * Add the first author to the Data Area
           CALL BAQ-PUTN-NAME USING
                          BY REFERENCE BAQ-ZCONNECT-AREA
                          WS-DATA-AREA-NAME
                          BY REFERENCE WS-ELEMENT
                          BY REFERENCE WS-ELEMENT-LENGTH
                          RETURNING WS-BAQ-RC.
      
      * Prepare the second author
           MOVE 10 TO authors-length OF RBK01Q01-authors.
           MOVE "Luiz Fadel" TO authors OF RBK01Q01-authors.

      * Add the second author to the Data Area
           CALL BAQ-PUTN-NAME USING
                          BY REFERENCE BAQ-ZCONNECT-AREA
                          WS-DATA-AREA-NAME
                          BY REFERENCE WS-ELEMENT
                          BY REFERENCE WS-ELEMENT-LENGTH
                          RETURNING WS-BAQ-RC.
      ...
    In this example the call to the BAQPUTN verb is repeated for as many authors as the Redbook has.
  6. Call the API operation.

    The COBOL program uses the BAQEXEC verb to call the API operation. This verb takes references to the BAQ-ZCONNECT-AREA, BAQ-API-INFO-APInnI01, BAQ-REQUEST-AREA, and BAQ-RESPONSE-AREA data structures. BAQ-ZCONNECT-AREA is used to communicate the status of the call. BAQ-API-INFO-APInnI01 contains static data that is generated by the Gradle build and contains the metadata for the API operation. BAQ-REQUEST-AREA locates the API operation request data and BAQ-RESPONSE-AREA contains the status of the call from z/OS Connect to the API endpoint and a reference to any returned data.

    The BAQEXEC verb contacts the z/OS Connect Server and passes any API operation request data in binary (COBOL language structure) form where z/OS Connect transforms the binary data to a JSON payload for the request, or Path or Query parameters that match the OpenAPI description of the operation. z/OS Connect then locates the API endpoint by using the <zosconnect_endpointConnection> configuration element in server.xml and makes the request. The zosconnect_endpointConnection element can be referenced by the connectionRef property of the server.xml webApplication definition of the API or associated with the connectionRef attribute in the Gradle plug-in properties file. For more information about defining the zosconnect_endpointConnection element, see Configuring a connection from IBM z/OS Connect to the API endpoint. For more ramifications about the <zosconnect_endpointConnection> configuration element, see zosconnect_endpointConnection. Any JSON response is then transformed back to the binary matching the generated COBOL response language structure for the returned HTTP Status Code.

    If the call fails for any reason, the BAQ-ZCONNECT-AREA data structure contains details of the problem. Also, any Data Areas that were added to the request by calling BAQPUTN remains in memory. They will only be freed when a call to BAQEXEC succeeds or BAQFREE or BAQTERM are called.

    For example,
    
       C-020.
      * Call the API
           CALL BAQ-EXEC-NAME USING
                           BY REFERENCE BAQ-ZCONNECT-AREA
                           BY REFERENCE BAQ-API-INFO-RBK04I01
                           BY REFERENCE BAQ-REQUEST-AREA
                           BY REFERENCE BAQ-RESPONSE-AREA.
 
           IF NOT BAQ-SUCCESS THEN
              MOVE BAQ-ZCON-COMPLETION-CODE TO WS-CC9
              MOVE BAQ-ZCON-REASON-CODE TO WS-RC9
 
              EVALUATE TRUE
                 WHEN BAQ-WARNING
                    MOVE "API RETURN WARNING" TO WS-FAIL-TYPE
                 WHEN BAQ-ERROR
                    MOVE "API RETURN ERROR  " TO WS-FAIL-TYPE
                 WHEN BAQ-SEVERE
                    MOVE "API RETURN SEVERE " TO WS-FAIL-TYPE
              END-EVALUATE
 
              MOVE BAQ-ZCON-COMPLETION-CODE TO WS-CC9
              MOVE BAQ-ZCON-REASON-CODE TO WS-RC9
 
              STRING WS-PROGRAM
                 '--EXEC failed'
                 WS-FAIL-TYPE
                 '-CC-' WS-CC9
                 '-RC-' WS-RC9
                 DELIMITED BY '>'
                 INTO WS-DISPLAY-MSG
 
              DISPLAY WS-DISPLAY-MSG  
              DISPLAY BAQ-ZCON-RETURN-MESSAGE
             
           END-IF.
  7. Retrieve the values from the response.

    When the call to the API operation succeeds, any returned response can be used. A successful call from the z/OS Connect Host API perspective is any API operation HTTP status code that is described in the OpenAPI definition for the operation.

    For example, a 404 (NOTFOUND), if described in the OpenAPI definition for the API operation, is seen as a successful call to the API endpoint with the response data transformed for the COBOL application. Further evaluation of BAQ-RESPONSE-AREA is required to find out the success of the API endpoint call.

    If the API operation response contains an HTTP status code that is not described in the OpenAPI definition then the BAQ-RESPONSE-AREA contains any response that the operation provides in the field BAQ-RESP-STATUS-MESSAGE, with the HTTP status code given in BAQ-RESP-STATUS-CODE.

    An OpenAPI 3.0 operation can describe multiple HTTP response codes that can be returned from the BAQEXEC call. The Gradle build transforms each one of these responses from JSON to a binary language structure. The OpenAPI 3.0 specification allows defining the responses specifically, such as 200 or 404, or by using wild cards such as 2XX or 4XX, or default.

    For each defined response for the API operation in the OpenAPI 3.0 definition, the application interprets the returned data. This data can be different for each defined response, so the application language structures are also different. The Gradle build creates one 01 level language structure per defined response for the operation. Therefore, the Host API must tell the COBOL application where the returned data is located in memory and how to access it. To enable this access, the BAQBASE-APInnP01 response language structure follows the following form with two 03 fields per defined operation response.
    • The names of the fields are in the form responseCodeXXX-num, or -existence, and responseCodeXXX-dataarea.
    • XXX is the response code, such as 200, 4XX, or Def (default).
    • If the response is an array type, then the field is -num and states how many elements are returned within the Data Area, including 0.
    • If the response is an Object type, then the field is -existence and contains either 0 or 1 to specify whether an object was returned in the Data Area.
    • z/OS Connect generates the value in the -dataarea field or the application to use when accessing the Data Area. The field contains the name of the Data Area that must be referenced to address the Data Element that is described by the generated language structure.

    In the Redbook API example, the getAllRedbooks operation defines two responses: A 200, which returns an array of books, and a 404 when no books are found. For this operation, the Gradle build generates the following BAQBASE-RBK04P01 structure to describe the two valid responses.

      
         01 BAQBASE-RBK04P01.

           03 responseCode200-num PIC S9(9) COMP-5 SYNC.
           03 responseCode200-dataarea PIC X(16).

           03 responseCode404-existence PIC S9(9) COMP-5 SYNC.
           03 responseCode404-dataarea PIC X(16).

    Further 01 Level language structures are generated to describe the data that is contained within each Data Area. RBK04P01-responseCode200 provides the representation of a book, and RBK04P01-responseCode404, an error message structure.

    
         01 RBK04P01-responseCode200.
           03 responseCode200.
             06 Xtitle-length PIC S9999 COMP-5 SYNC.
             06 Xtitle PIC X(80).
        
             06 authors-num PIC S9(9) COMP-5 SYNC.
             06 authors-dataarea PIC X(16).

             06 Xstatus-length PIC S9999 COMP-5 SYNC.
             06 Xstatus PIC X(9).
             06 formNumber PIC X(12).
             ...

    The array of authors is also described by the Data Area concept and further 01 Level data structures are generated to describe each element type returned. The BAQGETN (Get Next) verb is used to retrieve these elements in the same way each element was retrieved for the 200 response code. This technique allows for dynamic length arrays where storage is used for the number of elements with no waste. However, if only a few elements are expected in the API then the Gradle build option inlineMaxOccursLimit can be set. For example, if inlineMaxOccursLimit is set to 10 and the maxItems property in the OpenAPI schema for an array type is 10 or less, then the generated language structure contains the array type inline. If maxItems is greater than inlineMaxOccursLimit, a Data Area is used.

    
         01 RBK04P01-responseCode404.
           03 responseCode404.
             06 Xmessage-length PIC S9999 COMP-5 SYNC.
             06 Xmessage PIC X(50).

             06 authorsBooks-num PIC S9(9) COMP-5 SYNC.
             06 authorsBooks-dataarea PIC X(16).

    These response language structures in the RBK04P01 copybook are all located in the LINKAGE SECTION of the COBOL program and hence must be addressed by using the storage that a successful BAQEXEC Host API call returns.

    The Host API returns the address of the BAQBASE-RBK04P01 language structure in the BAQ-RESPONSE-AREA field BAQ-RESP-BASE-ADDRESS, so the COBOL program sets the address of BAQBASE-RBK04P01 to that storage. Also, the value of the HTTP status code that the API operation returns is contained in the BAQ-RESPONSE-AREA field BAQ-RESP-STATUS-CODE.

  8. Examine the status code to determine the returned data structure.

    In the Redbook API example, if the status code is 200, then an array of Books is returned, with an individual book represented by 01 Level RBK04P01-responseCode200. For more information about processing the good response, see COBOL Paragraph C-040. Otherwise, a 404 response was returned and the API operation returned an error that is represented by the 01 Level RBK04P01-responseCode404 structure. Check responseCode404-existence is greater than 0 and if so, check the RBK04P01-responseCode404 language structure to obtain the returned Data Area for the API operation status code.

    These values are checked by using the BAQGETN verb of the Host API. The name of the Data Area to retrieve is given with a USAGE POINTER field to contain the address for the returned error element and a COMP-5 binary field to contain the length of the element.

    For example,
    
      * The address of a returned Data Area Element
       01 WS-ELEMENT                    USAGE POINTER VALUE NULL.

      * Length of element for BAQGETN call.
       01 WS-ELEMENT-LENGTH  PIC 9(9) COMP-5.

    When the BAQGETN call returns successfully, WS-ELEMENT contains the location of the RBK04P01-responseCode404 language structure. Set the address of this structure to WS-ELEMENT and then the language structure fields can be used to display the error structure returned by the API operation.

    
       C-030.
      * Successful call, address the base structure
           SET ADDRESS OF BAQBASE-RBK04P01 to BAQ-RESP-BASE-ADDRESS.
 
      * The API endpoint has returned and the HTTP Status Code could
      * be 200 (OK) to indicate a successful return of some Redbooks
      * or another code that indicates an error has been returned
 
           IF BAQ-RESP-STATUS-CODE NOT EQUAL 200 THEN
              IF responseCode404-existence > 0 THEN
                 
                 MOVE responseCode404-dataarea TO
                    WS-DATA-AREA-NAME

                 MOVE LENGTH OF RBK04P01-responseCode404 TO
                    WS-ELEMENT-LENGTH

      * The REST API sent an Error message
                 CALL BAQ-GETN-NAME USING
                         BY REFERENCE BAQ-ZCONNECT-AREA
                         WS-DATA-AREA-NAME
                         BY REFERENCE WS-ELEMENT
                         BY REFERENCE WS-ELEMENT-LENGTH
  
                 IF NOT BAQ-SUCCESS THEN
                    MOVE BAQ-ZCON-COMPLETION-CODE TO WS-CC9
                    MOVE BAQ-ZCON-REASON-CODE TO WS-RC9
                    STRING WS-PROGRAM
                       '--GETN failed'
                       '-CC-' WS-CC9
                       '-RC-' WS-RC9
                       DELIMITED BY '>'
                       INTO WS-DISPLAY-MSG
 
                    DISPLAY WS-DISPLAY-MSG
                    DISPLAY BAQ-ZCON-RETURN-MESSAGE

                    STOP RUN
                 END-IF
 
                 SET ADDRESS OF RBK04P01-responseCode404 to WS-ELEMENT.
                 MOVE BAQ-RESP-STATUS-CODE TO WS-STATUS-CODE
                 STRING WS-PROGRAM
                  '--EXEC Redbook API returned HTTP Status Code '
                  WS-STATUS-CODE
                  ' MESSAGE ' Xmessage
                  DELIMITED BY SIZE
                  INTO WS-DISPLAY-MSG
 
                DISPLAY WS-DISPLAY-MSG
              ELSE
                 STRING WS-PROGRAM
                  '--EXEC REST EP return HTTP Status Code '
                  WS-STATUS-CODE
                  DELIMITED BY SIZE
                  INTO WS-DISPLAY-MSG
 
                DISPLAY WS-DISPLAY-MSG
              END-IF
           END-IF.

    If the API operation status code is 200 and the BAQBASE-RBK04P01 field responseCode200-num is greater than 0, then call a BAQGETN verb in a PERFORM VARYING loop to call Section CAA-GET-EACH-REDBOOK for each element of the array. 

    
       C-040.
           IF BAQ-RESP-STATUS-CODE = 200 THEN
              IF responseCode200-num > 0 THEN

                 MOVE LENGTH OF RBK04P01-responseCode200 TO 
                     WS-ELEMENT-LENGTH
                 
                 DISPLAY 'Redbook Store Inventory'
                 PERFORM CAA-GET-EACH-REDBOOK VARYING WS-INDEX
                 FROM 1 BY 1
                 UNTIL WS-INDEX > responseCode200-num
 
              ELSE
                 STRING WS-PROGRAM
                 '--EXEC REST EP - No Redbooks returned'
                DELIMITED BY SIZE
                INTO WS-DISPLAY-MSG
 
                DISPLAY WS-DISPLAY-MSG
              END-IF
           END-IF.
    BAQGETN is passed the name of the Data Area that references the returned Redbook elements and every time the verb is called, the next Redbook (represented by language structure RBK04P01-responseCode200) is returned with the address that the language structure must be addressed with in field WS-ELEMENT.
    Note:
    • Optional fields as described in the OpenAPI definition for the API operation are generated with a sibling field of the same name but suffixed with -existence. If the value of this sibling field is 0, then the field does not exist.
    • If your API property names are long, the -existence suffix can be generated in a shortened form of -exists, by setting the shortSuffix option in the API requester Gradle project options.yaml file. For more information, see The API requester Gradle plug-in properties and options - shortSuffix.
    
      *----------------------------------------------------------------*
      * CAA-GET-EACH-REDBOOK
      *
      * Gets each Redbook returned by the API endpoint by using
      * BAQGETN (Get Next) and displays the book details.
      *----------------------------------------------------------------*
       CAA-GET-EACH-REDBOOK SECTION.
       CA-010.
           CALL BAQ-GETN-NAME USING
             BY REFERENCE BAQ-ZCONNECT-AREA
             responseCode200-dataarea
             BY REFERENCE WS-ELEMENT
             BY REFERENCE WS-ELEMENT-LENGTH
 
           IF NOT BAQ-SUCCESS THEN
              MOVE BAQ-ZCON-COMPLETION-CODE TO WS-CC9
              MOVE BAQ-ZCON-REASON-CODE TO WS-RC9
              STRING WS-PROGRAM
                 '--GETN failed'
                 '-CC-' WS-CC9
                 '-RC-' WS-RC9
                 DELIMITED BY '>'
                 INTO WS-DISPLAY-MSG
 
              DISPLAY WS-DISPLAY-MSG
              DISPLAY BAQ-ZCON-RETURN-MESSAGE
 
              STOP RUN
           END-IF.
 
           SET ADDRESS OF RBK04P01-responseCode200 to WS-ELEMENT.
           
           DISPLAY OPERATION ' Redbook number ' WS-INDEX.

           STRING OPERATION ' Title '
                 Xtitle OF RBK04P01-responseCode200
                    (1:Xtitle-length OF RBK04P01-responseCode200)
           DELIMITED BY SIZE
           INTO WS-DISPLAY-MSG.

           DISPLAY WS-DISPLAY-MSG.
 
       CA-999.
           EXIT.
  9. Optional: Release the storage that was allocated.
    When the data that the API operation returns is processed, the Host API can release the storage that it allocated by calling BAQFREE. This is an optional step as BAQTERM will also free the allocated storage when the program terminates.
    For example,
    
       C-050.
      * Free Storage acquired by BAQEXEC
           CALL BAQ-FREE-NAME USING BY REFERENCE BAQ-ZCONNECT-AREA.
  10. Terminate the connection.
    After the API operation is called, terminate the connection to the z/OS Connect Server by calling the BAQTERM verb of the Host API.
    Note: In CICS, the termination of the connection releases the connection to the connection pool that was used by the URIMAP, so the next BAQINIT call to acquire a connection is quicker because the cached connection from the pool is used.
    For example,
    
      *----------------------------------------------------------------*
      * X-TERM
      *
      * Terminates the connection to z/OS Connect using BAQTERM.
      *----------------------------------------------------------------*
       X-TERM SECTION.
       X-010.
      * Terminate the connection
           CALL BAQ-TERM-NAME USING BY REFERENCE BAQ-ZCONNECT-AREA.
 
           IF NOT BAQ-SUCCESS THEN
              MOVE BAQ-ZCON-COMPLETION-CODE TO WS-CC9
              MOVE BAQ-ZCON-REASON-CODE TO WS-RC9
              STRING WS-PROGRAM
                 '--TERM failed'
                 WS-FAIL-TYPE
                 '-CC-' WS-CC9
                 '-RC-' WS-RC9
                 DELIMITED BY '>'
                 INTO WS-DISPLAY-MSG

              DISPLAY WS-DISPLAY-MSG
              DISPLAY BAQ-ZCON-RETURN-MESSAGE
           END-IF.
 
       X-999.
           EXIT.

Results

The COBOL application program uses the Host API to call the specified operation of the API endpoint.

What to do next

  • Develop functionality in your z/OS application that checks the completion codes and reason codes after calling a Host API verb. For more information, see Error handling for API requester calls.
  • Compile and run your z/OS application program to call the API. For more information, see Testing z/OS applications for API calls.
  • If the API that you want to call is secured with OAuth 2.0, a JWT, or an API key, you must make other modifications to your z/OS application to help ensure that the required parameters are provided in the API request. For more information, see Calling secured APIs.
  • When a CICS application is developed to call an API endpoint, the z/OS Connect Server that is used to process the request can be chosen at run time within the CICS application. This option allows for splitting of workloads between servers, for example, based on business area. For more information, see Overriding the URIMAP in a CICS application.
  • When a z/OS application is developed to call an API endpoint, the z/OS Connect Server that is used to process the request can be chosen at run time within the z/OS application. This option allows for splitting of workloads between servers, for example, based on business area.
  • When you develop your z/OS application to call APIs, make sure that dynamic linkage is used, where possible, between the z/OS application code and the Host API supplied by z/OS Connect.
  • You might want to learn how to use additionalProperties to send or receive additional properties from any valid JSON type by using a COBOL or PL/I array structure. For more information, see Using additionalProperties.
  • You might want to learn how to use PATCH to perform partial updates in your applications. See procedures CD-PATCH-REDBOOK and CE-MERGE-REDBOOK for examples on how to update a Redbook by using RFC6902 and RFC 7396 patch documents. For more information, see Using the PATCH HTTP method in an application.