API Requester batch

To call APIs from Cobol batch program, I've explored the z/OS web enablement toolkit.

You can find the github of this project here : Github zOS-Client-Web-Enablement-Toolkit

Also, in the SYS1.SAMPLIB, you can find 2 Cobol programs samples : HWTHXCB1 and HWTHXCB2 The first one, to execute a GET command, the second one, for a POST.

At the beginning of each program, you will find the JCL to compile and execute the programs.

One special thing to take care is that it use the POSIX variable set to ON. In the sample JCL, at the GO step, you can find it in the PARM.

My goal was to produce a sub-program, in order to concentrate all the different way of calling an API in one place, and then to allow the projects only to pass the incoming data through the linkage section and get back the result.

After doing so, the PARM option was not the good way to set the POSIX ON, so I've set a CEEOPTS DD card statement in the step executing my main batch program. Also, if you keep the code of HWTHXCB2 for the POST, it use an input file called SYSIN that you can define as a temporary dataset using &&

Sample code available here : Cobol API Batch

API Requester CICS

As seen in the previous paragraph, the POSIX has to be set to ON to use the z/Os web enablement toolkit. On CICS, it is set to OFF and it seems not that simple to change that.

I changed my mind not to keep the same solution both for batch and CICS and I explored the EXEC CICS WEB commands that are designed to call REST API.

First thing, where to find source samples ?

Luckily, I've found the github of the Walmart Labs : Github Walmart Labs

And I could produce a minimum sub-program to test looking like this, here using an EXEC CICS WRITE to pass the Authentication in the header :

           EXEC CICS WEB OPEN
                HOST         (DFH-URI)
                HOSTLENGTH   (URL-HOST-NAME-LENGTH)
                PORTNUMBER   (URL-PORT)
                SCHEME       (URL-SCHEME)
                SESSTOKEN    (SESSION-TOKEN)
                NOHANDLE
           END-EXEC.

           IF EIBRESP NOT = DFHRESP(NORMAL)
              DISPLAY "WEB OPEN ERROR"
              DISPLAY "EIBRESP : " EIBRESP
              DISPLAY "EIBRESP2 : " EIBRESP2
              GOBACK
           END-IF.

           EVALUATE DFH-METHOD
                 WHEN "GET"
                   MOVE DFHVALUE(GET)    TO WEB-METHOD
                 WHEN "PUT"
                   MOVE DFHVALUE(PUT)    TO WEB-METHOD
                 WHEN "POST"
                   MOVE DFHVALUE(POST)   TO WEB-METHOD
                 WHEN OTHER
                   Display "DFH-METHOD non prevu, GET par defaut"
                   MOVE DFHVALUE(GET)  TO WEB-METHOD
           END-EVALUATE.

           MOVE W-SERVICE-LENGTH TO WEB-PATH-LENGTH
           
           MOVE "Authorization"              TO W-HEADER
           MOVE LENGTH OF W-HEADER           TO W-HEADER-LEN
           MOVE "Basic xxxxxxxxxxxxxxxxxxxxxx" TO W-HEADER-VALUE
           MOVE LENGTH OF W-HEADER-VALUE     TO W-HEADER-VALUE-LEN

           EXEC CICS WEB WRITE
                      HTTPHEADER   (W-HEADER)
                      NAMELENGTH   (W-HEADER-LEN)
                      SESSTOKEN    (SESSION-TOKEN)
                      VALUE        (W-HEADER-VALUE)
                      VALUELENGTH  (W-HEADER-VALUE-LEN)
           END-EXEC

           IF EIBRESP NOT = DFHRESP(NORMAL)
              DISPLAY "WEB WRITE ERROR"
              DISPLAY "EIBRESP             : " EIBRESP
              DISPLAY "EIBRESP2            : " EIBRESP2
              GOBACK
           END-IF

           IF DFH-METHOD = "GET"
               EXEC CICS WEB CONVERSE
                    SESSTOKEN     (SESSION-TOKEN)
                    METHOD        (WEB-METHOD)
                    PATH          (DFH-SERVICE)
                    PATHLENGTH    (WEB-PATH-LENGTH)
                    INTO          (CONVERSE-RESPONSE)
                    TOLENGTH      (CONVERSE-LENGTH)
                    STATUSCODE    (WEB-STATUS-CODE)
                    STATUSLEN     (WEB-STATUS-ABSTIME-LENGTH)
                    STATUSTEXT    (WEB-STATUS-ABSTIME)
                    NOHANDLE
               END-EXEC
           ELSE

               IF  DFH-MEDIA(1:8) EQUAL "text/xml"
                 Display "cliconvert"
                 MOVE DFHVALUE(CLICONVERT)      TO CLIENT-CONVERT
               ELSE
                 Display "NOcliconvert"
                 MOVE DFHVALUE(NOCLICONVERT)    TO CLIENT-CONVERT
               END-IF

               EXEC CICS WEB CONVERSE
                        SESSTOKEN  (SESSION-TOKEN)
                        PATH       (DFH-SERVICE)
                        PATHLENGTH (WEB-PATH-LENGTH)
                        METHOD     (WEB-METHOD)
                        MEDIATYPE  (DFH-MEDIA)
                        FROM       (DFH-MESSAGE)
                        FROMLENGTH (RECEIVE-LENGTH)
                        INTO       (CONVERSE-RESPONSE)
                        TOLENGTH   (CONVERSE-LENGTH)
                        MAXLENGTH  (CONVERSE-LENGTH)
                        STATUSCODE (WEB-STATUS-CODE)
                        STATUSLEN  (WEB-STATUS-TEXT-LENGTH)
                        STATUSTEXT (WEB-STATUS-TEXT)
                        CLIENTCONV (CLIENT-CONVERT)
                        NOHANDLE
                END-EXEC

                IF EIBRESP = DFHRESP(NORMAL)
                    DISPLAY " WEB-STATUS-CODE : " WEB-STATUS-CODE
                    DISPLAY " WEB-STATUS-TEXT : " WEB-STATUS-TEXT

                END-IF
           END-IF.



           IF EIBRESP NOT = DFHRESP(NORMAL)
              DISPLAY "WEB CONVERSE ERROR"
              DISPLAY "EIBRESP  : " EIBRESP
              DISPLAY "EIBRESP2 : " EIBRESP2
              GOBACK
           ELSE
              DISPLAY "CONVERSE-RESPONSE : " CONVERSE-RESPONSE
           END-IF.
           MOVE SPACES             TO DFH-REPONSE.
           MOVE CONVERSE-RESPONSE  TO DFH-REPONSE.

           DISPLAY  "WEB CLOSE".

           EXEC CICS WEB CLOSE
                SESSTOKEN( SESSION-TOKEN )
                NOHANDLE
           END-EXEC.

           IF EIBRESP NOT = DFHRESP(NORMAL)
              DISPLAY "WEB CLOSE ERROR"
              DISPLAY "EIBRESP  : " EIBRESP
              DISPLAY "EIBRESP2 : " EIBRESP2
              GOBACK
           END-IF.

To manage EIBRESP and EIBRESP2 value and return the corresponding error, you can take a look at the IBM documentation, here for the WEB CONVERSE command : IBM doc WEB CONVERSE

Sample code available here : Cobol API CICS