Developing Outbound APIs Requesters Applications

IBM z/OS Connect EE V3.
Developing
Outbound API
Requesters
Applications
Lab Version Date: May 30, 2020

ZCONEE - z/OS Connect EE V3.0
Table of Contents
Overview ................................................................................................................................................... 4
RESTful API Requester to a CICS RESTful API ....................................................................................... 5
Generate the API requester artifacts from a Swagger document ................................................................................... 5
Review the application programs ............................................................................................................................ 11
Compile and link-edit the application programs ....................................................................................................... 15
Test the API requester application programs ............................................................................................................ 16
RESTful API Requester to a MQ One-Way RESTful API............................................................................ 19
Generate the API requester artifacts from a Swagger document ................................................................................. 19
RESTful API Requester from a CICS application .................................................................................... 32
Generate the API requester artifacts from a Swagger document ................................................................................. 32
Summary ............................................................................................................................................... 49
Overview 2 of 49
© Copyright IBM Corporation 2018, 2020 All rights reserved
Mitch Johnson (mitchj@us.ibm.com)
General Exercise Information and Guidelines
 The Windows artifacts for this exercise are in directory c:\z\apiRequester. Open a DOS command
prompt Window and go to this directory using a change directory command, e.g. cd \z\apiRequester
 Viewing or changing the contents of a file can easily be done by opening the Windows Explorer and
going to directory c:\z\apiRequester. One this folder is display you can select a file and right mouse
button click and select the Open with EditPad Lite option to open a file for viewing.
 This exercise requires using TSO user USER1 and the TSO password for this user will be provided by
the lab instructor.
 This exercise primarily uses data sets USER1.ZCEE.CNTL and USER.ZCEE.SOURCE.
 Please note that there may be minor differences between the screen shots in this exercise versus what
you see when performing this exercise. These differences should not impact the completion of this
exercise.
 Any time you have any questions about the use of IBM z/OS Explorer, 3270 screens, features or tools do
not hesitate to ask the instructor for assistance.
Important: The REST API provider applications used in this exercise access a CICS container
application and MQ. These APIs were developed using the instructions provided in other exercises
in this workshop. The REST API providers could have just as easily have been anywhere in the
cloud on any remote system as long as the Swagger document for the REST API was available.
Overview 3 of 49
Overview
These exercises demonstrate the steps required to enable COBOL programs to invoke RESTful APIs. There are
two samples provided to do this. One sample uses RESTful APIs to access a CICS program and the other uses
RESTful APIs to interact with an MQ queue. Note that even though these APIs are hosted in z/OS Connect EE
server these same steps could be followed to access APIs hosted anywhere in the cloud.
The process starts with the Swagger document that describes the API which the COBOL program will invoke.
The Swagger document is used by the z/OS Connect EE build toolkit to (1) generate the COBOL copy books
included in the COBOL program to invoke the API (2) as well as an API requester archive file (ARA) which is
deployed to a z/OS Connect EE server.
The diagram shows this process at a high level. The copy books generated by the z/OS Connect EE build
toolkit will be integrated into a COBOL program to provide (1) the COBOL representation of the request and
response messages and to identity (2) the HTTP method to be used in the RESTful request. The API requester
archive file will be deployed to a z/OS Connect EE server and used to convert (1) the COBOL request and
response messages to JSON messages and to invoke (2) the outbound RESTful request and wait for the
response.
In this exercise the COBOL program will be compiled and executed in a batch environment. The only
differences between batch and CICS and IMS is the configuration required for connecting to the z/OS Connect
EE server. Consult the z/OS Connect EE Knowledge Center for information how this is done for CICS and
IMS.
If you have completed either the developing APIs exercise for MVS Batch, DB2 or MQ you can start with
section RESTful API Requester to a CICS on page 5.
Overview 4 of 49
RESTful API Requester to a CICS RESTful API
In this section an API requester will be developed and tested where the target API accesses a CICS Container
application. The batch programs will insert records (POST), retrieve records (GET), update record (PUT) and
delete records (DELETE) in a VSAM data set.
Generate the API requester artifacts from a Swagger document

The first step is to use to use the API’s Swagger document to generate the artifacts required for the COBOL API
client application and the API requester archive file. The Swagger document was obtained from the server
where the API is hosted. All the files mention in this section are in directory c:/z/apiRequester/cscvinc on your
workstation.
The z/OS Connect EE build toolkit (ZCONBT) is a Java application shipped with z/OS Connect EE as a zip file
and can be installed on a workstation or in OMVS. Anywhere a Java runtime is available. In this exercise the
build toolkit will on Windows.
___1. Begin by reviewing the API’s Swagger document for the CICS container-based API. Using a CICS container
has implications which will be explored later. In the meantime, this document identifies the types of HTTP
methods supported as well as the path of each HTTP method. It also the contents each method’s request JSON
message and the response JSON message field contents and field types. This is the blue print for invoking the
API.
{
"swagger": "2.0",
"info": {
"description": "",
"version": "1.0.0",
"title": "cscvinc"
},
"basePath": "/cscvinc",
"schemes": [
"https",
"http"
],
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"paths": {
"/employee": {
"post": {
"operationId": "postCscvincService",
"parameters": [
{
"in": "body",
"name": "postCscvincService_request",
"description": "request body",
"required": true,
"schema":
RESTful{ API Requester to a CICS RESTful API 5 of 49
© Copyright IBM "#/definitions/postCscvincService_request"
"$ref": Corporation 2018, 2020 All rights reserved
} Mitch Johnson (mitchj@us.ibm.com)
},
Tech-Tip: Instructions for installing the z/OS Connect EE build toolkit can be found at URL
https://www.ibm.com/support/knowledgecenter/en/SS4SVW_3.0.0/com.ibm.zosconnect.doc/installing/bt_install.html
___2. Next review the input parameters that will be passed to the z/OS Connect EE build toolkit in a properties file.
This file is cscvinc.properties see its below:
apiDescriptionFile=./cscvinc.json 1
dataStructuresLocation=./syslib 2
apiInfoFileLocation=./syslib 3
logFileDirectory=./logs 4
language=COBOL 5
connectionRef=cscvincAPI 6
requesterPrefix=csc 7
1. Identifies the Swagger document that describes the API

2. Provides the directory where the generated COBOL copybooks representing the request and response
messages will be written.
3. Provides the directory where the generated COBOL copybook with invocation details of the API will
be written.
4. Provides the directory where a log file will be written.
5. Identifies the target language.
6. Identifies the corresponding zosconnect_endpointConnection element define in the z/OS Connect EE
server’s server.xml file.
7. Provides a 3-character prefix to be used for all generated copybooks
___3. View file cscvincAPI.bat which contains this one line.
c:\z\zconbt\bin\zconbt.bat -p=./cscvinc.properties -f=./cscvinc.ara
This is batch command file that when executed invokes the z/OS Connect EE build toolkit (zconbt). The -p
switch identifies the input properties file and the -f switch identifies the name of the generate API requester
archive file. The API requester archive (ARA) file will be deployed and made available to the z/OS Connect
EE server in directory …/resources/zosconnect/apiRequsters.
___4. On the workstation desktop, locate the Command Prompt icon and double click on it to open a DOS session that
will allow commands to be entered.
___5. Use the change directory command (cd) to change to directory C:\z\api\Requester\cscvinc, e.g.
cd c:\z\apiRequester\cscvinc
RESTful API Requester to a CICS RESTful API 6 of 49

___6. Enter command cscvincAPI.bat in the DOS command prompt window and you should see output like the
below:
BAQB0000I: z/OS Connect Enterprise Edition Build Toolkit Version 1.2 (20200408-1120).
BAQB0008I: Creating API requester archive from configuration file ./cscvinc.properties.
BAQB0040I: The generated API requester is automatically named cscvincapi_1.0.0 based on the title
cscvincapi and version 1.0.0 of the API to be called.
BAQB0015I: Start processing operation (operationId: getCscvincSelectService, relativePath:
/employee/{employee}, method: GET).
DFHPI9586W A reserved word "address" has been detected in the input document, it has been changed to
"Xaddress".
DFHPI9586W A reserved word "date" has been detected in the input document, it has been changed to
"Xdate".
BAQB0016I: Successfully processed operation (operationId: getCscvincSelectService, relativePath:
/employee/{employee}, method: GET).
BAQB0015I: Start processing operation (operationId: putCscvincUpdateService, relativePath:
/employee/{employee}, method: PUT).
"Xaddress".
DFHPI9586W A reserved word "date" has been detected in the input document, it has been changed to
"Xdate".
BAQB0016I: Successfully processed operation (operationId: putCscvincUpdateService, relativePath:
/employee/{employee}, method: PUT).
BAQB0015I: Start processing operation (operationId: postCscvincInsertService, relativePath:
/employee/{employee}, method: POST).
"Xaddress".
BAQB0016I: Successfully processed operation (operationId: postCscvincInsertService, relativePath:
/employee/{employee}, method: POST).
BAQB0015I: Start processing operation (operationId: deleteCscvincDeleteService, relativePath:
/employee/{employee}, method: DELETE).
BAQB0016I: Successfully processed operation (operationId: deleteCscvincDeleteService, relativePath:
/employee/{employee}, method: DELETE).
Total 4 operation(s) (success: 4, ignored: 0) defined in api description file: ./cscvinc.json

------ Successfully processed operation(s) ------
operationId: getCscvincSelectService, basePath: /cscvincapi, relativePath: /employee/{employee},
method: GET
- request data structure : CSC00Q01
- response data structure : CSC00P01
- api info file : CSC00I01
operationId: putCscvincUpdateService, basePath: /cscvincapi, relativePath: /employee/{employee},

method: PUT
operationId: postCscvincInsertService, basePath: /cscvincapi, relativePath: /employee/{employee},

method: POST
operationId: deleteCscvincDeleteService, basePath: /cscvincapi, relativePath: /employee/{employee},

method: DELETE
BAQB0009I: Successfully created API requester archive file ./cscvinc.ara.

Note that each HTTP method defined in the Swagger document will cause the generation of up to three copy
books. One for the request message(Q01), one for the response message(P01) and one for the API details(I01).
The copy book names are based on the requesterPrefix property (e.g. csc) and use an ascending sequence
number sequence to differentiate between methods. Also note that there may be fewer than three copy books
generated. For example, if there is no response message or no request message for a specific method a copy
book may not be generated.
___7. Now explore a sample snippet of the copy book for the request message of a PUT method. Use EditPad Lite to
open file c:\z\apiRequester\cscvinc\syslib\CSC00Q01. Scroll down until you see something like the code below.
06 RespBody.
09 cscvincSelectServiceOp-num PIC S9(9) COMP-5 SYNC.
09 cscvincSelectServiceOperatio.
12 Container1.
15 RESPONSE-CONTAINER2-num PIC S9(9) COMP-5 SYNC.
Important: The sequence numbers assigned to a copy book seem to be arbitrary. When you compile
15 RESPONSE-CONTAINER.
the sample programs later
18inCEIBRESP-num
this exercise verify the copy books included for aCOMP-5
PIC S9(9) particular method has
SYNC.
the same sequence numbers as generated when you invoke the toolkit.
18 CEIBRESP PIC S9(8) DISPLAY.
18 CEIBRESP2-num PIC S9(9) COMP-5 SYNC.
18 CEIBRESP2 PIC S9(8) DISPLAY.
18 userIdentity-num PIC S9(9) COMP-5 SYNC.
18 userIdentity.
21 userIdentity2-length PIC S9999 COMP-5 SYNC.
21 userIdentity2 PIC X(8).
18 fileArea2-num PIC S9(9) COMP-5 SYNC.
18 fileArea.
21 employeeNumber-num PIC S9(9) COMP-5 SYNC.
21 employeeNumber.
24 employeeNumber2-length PIC S9999 COMP-5 SYNC.
24 employeeNumber2 PIC X(6).
21 employeeName-num PIC S9(9)COMP-5 SYNC.
21 employeeName.
24 employeeName2-length PIC S9999 COMP-5 SYNC.
24 employeeName2 PIC X(20).
Note that each variable has an associated length (e.g. employeeNumber2-length). The length of a variable is
required since there is no delimiter between the variables in storage. The runtime needs to know the size of a
variable at execution time so the request and response messages can be properly converted to and from JSON
name/value pairs.
For this API, the Swagger document included an additional variable for the number of occurrences of a variable,
(e.g. employeeNumber-num). In this exercise we will set the number of each variable to one.
Tech-Tip: This additional variable was included for this API because the target program is a
CICS container enabled program and a CICS channel can have multiple occurrences of the same
container. The z/OS Connect EE API requester support needs to know number of each variable is
being sent (and returned). This behavior is not unique to CICS.
The corresponding response message (c:\z\apiRequester\cscvinc\syslib\CSC00P01) will have a similar layout.

___8. The corresponding API information copy book (c:\z\apiRequester\cscvinc\syslib\CSC00I01) has contents
providing the API name and the path to be used for the method:
03 BAQ-APINAME PIC X(255)
VALUE 'cscvincapi_1.0.0'.
03 BAQ-APINAME-LEN PIC S9(9) COMP-5 SYNC
VALUE 16.
03 BAQ-APIPATH PIC X(255)
VALUE '%2Fcscvincapi%2Femployee%2F%7Bemployee%7D'.
03 BAQ-APIPATH-LEN PIC S9(9) COMP-5 SYNC
VALUE 41.
03 BAQ-APIMETHOD PIC X(255)
VALUE 'GET'.
03 BAQ-APIMETHOD-LEN PIC S9(9) COMP-5 SYNC
VALUE 3.
Deploy the API Requester Archive file to the z/OS Connect EE server
Next make the API requester archive file available to the z/OS Connect EE server.
The API requester archive (ARA) file needs to be deployed to the API requester directory. In this case the target
directory is /var/ats/zosconnect/servers/zceeapir/resources/zosconnect/apiRequesters.
___1. Open a DOS command session and change to directory c:\z\apiRequester\cscvinc, e.g cd
c:\z\apiRequester\cscvinc
___2. Use the z/OS Connect EE RESTful administrative interface to deploy the ARA files by using the cURL
command embedded in command file deployCscvinc.bat. Invoke this command file to deploy the cscvinc API
archive file.
c:\z\apiRequester\cscvinc>curl -X POST --user Fred:fredpwd --data-binary @cscvin

c.ara --header "Content-Type: application/zip" --insecure https://wg31.washingt
on.ibm.com:9483/zosConnect/apiRequesters
{"name":"cscvincapi_1.0.0","version":"1.0.0","description":"","status":"Started","
apiRequesterUrl":"https:\/\/wg31.washington.ibm.com:9483\/zosConnect\/apiRequeste
rs\/cscvinc_1.0.0","connection":"cscvincAPI"}
Tech-Tip: If a REST client tool like cURL or Postman was not available then ARA file could
have been deployed using FTP to upload the file in binary mode to the apiRequesters directory.
Tech-Tip: If an ARA needs to be redeployed, the cURL command with a PUT method can be
used to stop the API requester
curl -X PUT --user Fred:fredpwd --insecure
https://wg31.washington.ibm.com:9483/zosConnect/apiRequesters/cscvinc_1.0.0?status=stopped
And the cURL command with a DELETE method can be used to delete the API requester.
curl -X DELETE --user Fred:fredpwd --insecure
https://wg31.washington.ibm.com:9483/zosConnect/apiRequesters/cscvinc_1.0.0
otherwise the redeployment of the ARA file will fail.

___3. The z/OS Connect EE server has the configuration below already included.
<server description="API Requester">


<featureManager>
<feature>zosconnect:apiRequester-1.0</feature>
</featureManager>
<zosconnect_endpointConnection id="cscvincAPI" 1
host="http://wg31.washington.ibm.com"
port="9120"
basicAuthRef="myBasicAuth"
connectionTimeout="10s"
receiveTimeout="20s" />
<zosconnect_authData id="myBasicAuth" 2
user="Fred"
password="fredpwd" />
</server>
1. Identifies the system which hosts the target API as well as any security information and time out
parameters. Note that the ID of this element matches the value connectionRef property used when the
ARA was generated by the z/OS Connect build toolkit.
2. The target server uses basic authentication, so we are simply provided a user identity and password.
The password can be encrypted in the server.xml file or TLS used for security.
Tech-Tip: The endpointConnection element specifies the host and port of the target API
provider. This z/OS Connect server performs the conversion of the COBOL data structure to
JSON and then acts as a JSON REST client to the target API provider. Which for this
example, is the same z/OS Connect server. The REST client loops back to itself when
invoking the API. This would rarely happen in a real-world environment. This is why this
host and port is also used by the API requester client in its environment variables.
Move the COBOL copy books to a MVS data set

Next make the generated COBOL copy books available for including into the COBOL program.
The generated COBOL copy books need to be available in an MVS data set which is included in the compiler
SYSLIB concatenation sequence. In the data set is USER1.ZCEE. SOURCE. Use a DOS command prompt
session and the commands below to move the copy books file to this data set. Authenticate as user USER1
(password USER1).
___1. Open a DOS command prompt and use the change directory command to go to directory
C:\z\apiRequester\cscvinc\syslib, e.g. cd \z\apiRequester\cscvinc\syslib
___2. Start a file transfer session with the WG31 host using the ftp command, e.g. ftp wg31

___3. Logon as USER1 and then use the cd command to change to directory to data set USER1.ZCEE. SOURCE, e.g.
cd zcee.source
___4. Toggle prompting off by entering command prompt
___5. Perform multiple put requests by using the multiple put command, mput csc*
___6. When the last transfer has completed enter the quit command.
c:\z\apiRequester\cscvinc>cd syslib
c:\z\apiRequester\cscvinc\syslib>ftp wg31.washington.ibm.com
Connected to wg31.washington.ibm.com.
220-FTP 16:26:23 on 2018-02-15.
220 Connection will close if idle for more than 200 minutes.
User (wg31.washington.ibm.com:(none)): user1
331 Send password please. user1
Password:
230 USER1 is logged on. Working directory is "USER1.".
ftp> cd zcee.source
250 The working directory "USER1.ZCEE.SOURCE" is a partitioned data set
ftp> prompt
Interactive mode Off .
ftp> mput CSC*
200 Port request OK.
125 Storing data set USER1.ZCEE.SOURCE(CSC00I01)
250 Transfer completed successfully.
ftp: 533 bytes sent in 0.32Seconds 1.66Kbytes/sec.
sent in 0.10Seconds 110.89Kbytes/sec.
…….
125 Storing data set USER1.ZCEE.SOURCE(CSC03P01)
125 Storing data set USER1.ZCEE.SOURCE(CSC03Q01)
ftp> quit
Review the application programs

Now that the copy books have been generated and are available in a data set the next step is compile and link
edit the application programs. The source for the application programs are in USER1.ZCEE.SOURCE.
Member DELTAPI invokes the DELETE method, member GETAPI invokes the GET method, POSTAPI
invokes the POST method and PUTAPI invokes the PUT method.
Tech-Tip: Data set USER1.ZCEE.SOURCE can be accessed either by using the IBM z/OS
Explorer or by using the Personal Communication icon on the desktop and logging on to TSO and
use ISPF option 3.4 to access this data set. If you have any questions about either method, ask the
instructor.

___1. Back in the IBM z/OS Explorer session switch to the Remote System Explorer perspective (see page Error!
Bookmark not defined.) and expand data set USER1.ZCEE.SOURCE in the Remote System view to display a
list of its members.
___2. Begin by reviewing the application programs GETAPI. Open member GETAPI in USER1.ZCEE. SOURCE and
review its contents by selecting the member and right- mouse button clicking and selecting the Open option.
Scroll down until you see these lines of code.
These lines of code copy into the source the required z/OS Connect EE copy book (BAQRINFO) and the copy
books generated by the z/OS Connect EE build tool kit. If when you generated the copy book earlier in the
exercise and the sequence number used for the GET method was not 02 then you need to change the COBOL
source to match sequence generated when you invoke the ZCONBT tool.
* Copy API Requester required copybook
COPY BAQRINFO.
* Request and Response

01 API-REQUEST.
COPY CSC00Q01.
01 API_RESPONSE.
COPY CSC00P01.
* Structure with the API information
01 API-INFO-OPER1.
COPY CSC00I01.

___3. Scroll down further until you find this code which provides the contents of the request message.
*---------------------------------------------------------------*
* Set up the data for the API Requester call *
*------------------- --------------------------------------------*
MOVE employee of PARM-DATA TO employee IN API-REQUEST.
MOVE LENGTH of employee in API-REQUEST to
employee-length IN API-REQUEST.
*---------------------------------------------------------------*
* Initialize API Requester PTRs & LENs *
*---------------------------------------------------------------*
* Use pointer and length to specify the location of
* request and response segment.
* This procedure is general and necessary.
SET BAQ-REQUEST-PTR TO ADDRESS OF API-REQUEST.
MOVE LENGTH OF API-REQUEST TO BAQ-REQUEST-LEN.
SET BAQ-RESPONSE-PTR TO ADDRESS OF API_RESPONSE.
MOVE LENGTH OF API_RESPONSE TO BAQ-RESPONSE-LEN.
The GET method only requires one variable and it is provided as a path parameter, e.g.
/cscvinc/employee/{numb}.
___4. Scroll down further and you will the call to the z/OS Connect API requester stub module.
*---------------------------------------------------------------*
* Call the communication stub *
*---------------------------------------------------------------*
* Call the subsystem-supplied stub code to send
* API request to zCEE
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.
* The BAQ-RETURN-CODE field in 'BAQRINFO' indicates whether this
* API call is successful.
Note that the parameters are being passed by reference. This means that the z/OS Connect API requester stub
will have direct access to the program storage for both accessing data and making changes (i.e. the response
message).

___5. Scroll down further and you will see the code where the application displays the results in the response
message.
IF BAQ-SUCCESS THEN
DISPLAY "EmployeeNumber: " employeeNumber2 of API_RESPONSE
DISPLAY "EmployeeName: " employeeName2 of API_RESPONSE
DISPLAY "Address: " Xaddress2 of API_RESPONSE
DISPLAY "Phone: " phone2 of API_RESPONSE
DISPLAY "Date: " Xdate2 of API_RESPONSE
DISPLAY "Amount: " amount2 of API_RESPONSE
MOVE CEIBRESP of API_RESPONSE to EIBRESP
MOVE CEIBRESP2 of API_RESPONSE to EIBRESP2
DISPLAY "EIBRESP: " EIBRESP
DISPLAY "EIBRESP2: " EIBRESP2
DISPLAY "USERID: " userIdentity2
Close member GETAPI and open member POSTAPI. The code for this program is very similar to the code for
GETAPI with the exception that all variables are provided in a JSON request message. Scroll down and find the
code below.
*---------------------------------------------------------------*
*---------------------------------------------------------------*
MOVE 1 to cscvincInsertServiceOp-num in API-REQUEST
REQUEST2-num in API-REQUEST
fileArea2-num in API-REQUEST
employeeNumber-num in API-REQUEST
employeeName-num in API-REQUEST
Xaddress-num in API-REQUEST
phoneNumber-num in API-REQUEST
startDate-num in API-REQUEST
amount-num in API-REQUEST.
MOVE employeeNumber of PARM-DATA TO employeeNumber2

IN API-REQUEST.
MOVE LENGTH of employeeNumber2 in API-REQUEST to
employeeNumber2-length IN API-REQUEST.
MOVE "John" TO employeeName2 IN API-REQUEST.

MOVE LENGTH of employeeName2 in API-REQUEST to
employeeName2-length IN API-REQUEST.
In this case the number of each occurrences of a property name must be provided (1) and then the, the
length of the property value and finally the property value moved to the request copy book.
___6. Explore members DELTAPI and PUTAPI and their corresponding copy books to see the code which is common
(variable housekeeping, calls to the z/OS Connect stub, etc.) regardless of the method being invoked.

Compile and link-edit the application programs

The applications programs now are ready to be compiled and link-edited.
___1. Submit the job in member CSCVINC in data set USER1.ZCEE.CNTL.
//COMPILE EXEC IGYWCL,LNGPRFX=SYS1.ECOBOL,PARM.COBOL='NODYNAM

//COBOL.SYSIN DD DISP=SHR,DSN=USER1.ZCEE.SOURCE(POSTAPI)
//COBOL.SYSLIB DD DISP=SHR,DSN=USER1.ZCEE.SOURCE
// DD DISP=SHR,DSN=ZCEE30.SBAQCOB
//LKED.SYSLMOD DD DISP=SHR,DSN=USER1.ZCEE.LOADLIB(POSTAPI)
//COMPILE EXEC IGYWCL,LNGPRFX=SYS1.ECOBOL,PARM.COBOL='NODYNAM
//COBOL.SYSIN DD DISP=SHR,DSN=USER1.ZCEE.SOURCE(GETAPI)
//LKED.SYSLMOD DD DISP=SHR,DSN=USER1.ZCEE.LOADLIB(GETAPI)
//COMPILE EXEC IGYWCL,LNGPRFX=SYS1.ECOBOL,PARM.COBOL='NODYNAM'
//COBOL.SYSIN DD DISP=SHR,DSN=USER1.ZCEE.SOURCE(PUTAPI)
//LKED.SYSLMOD DD DISP=SHR,DSN=USER1.ZCEE.LOADLIB(PUTAPI)
//COBOL.SYSIN DD DISP=SHR,DSN=USER1.ZCEE.SOURCE(DELTAPI)
//LKED.SYSLMOD DD DISP=SHR,DSN=USER1.ZCEE.LOADLIB(DELTAPI)
Note that the CALL statement in each of this program uses a variable for the program name z/OS Connect EE
stub program (BAQCSTUB). This means that this program will by dynamically linked at execution. The load
module library containing BAQSCTUB (ZCEE30.SBAQLIB) must be available in the STEPLIB concatenation
sequence when the program is executed.
This job should complete with a zero-return code.

Tech Tip: To submit a job when using the IBM z/OS Explorer select the member and right
mouse button click and select the Submit option. Or if the member is currently opened simply right
mouse button click and select the Submit option. Click the Locate Job button on the Job
Confirmation pop-up. This will display the job output in the Retrieved Job section under JES in
the Remote Systems view. The job’s output can be viewed right mouse button clicking and
selecting the Open option.

Test the API requester application programs
The JCL to execute these programs can be found in USER1.ZCEE.CNTL, the member names in this data set
match the program names. The members are DELTAPI, GETAPI, POSTAPI and PUTAPI.
___1. Submit the job in member GETAPI in USER1.ZCEE.CNTL.

//GETAPI EXEC PGM=GETAPI,PARM='111111'
//STEPLIB DD DISP=SHR,DSN=USER1.ZCEE.LOADLIB
// DD DISP=SHR,DSN=ZCEE30.SBAQLIB
//SYSPRINT DD SYSOUT=*
//CEEOPTS DD *
POSIX(ON),
ENVAR("BAQURI=wg31.washington.ibm.com",
"BAQPORT=9120")
___2. The job should complete with a condition code of 200 and have the following output for SYSPRINT.
EmployeeNumber: 111111
EmployeeName: C. BAKER
Address: OTTAWA, ONTARIO
Phone: 51212003
Date: 26 11 81
Amount: $0011.00
EIBRESP: 00000000
EIBRESP2: 00000000
USERID: CICSUSER
HTTP CODE: 0000000200
___3.
Tech-Tip: An HTTP code of 200 indicates success. For an explanation of HTTP codes see URL
https://en.wikipedia.org/wiki/List_of_HTTP_status_codes
___3. Change the PARM=’111111’ to PARM=’000000’ and resubmit. This time should receive a 404 return code and
the output should look like this:
Error code: 0000000404

Error
msg:{"cscvincSelectServiceOperationResponse":{"Container1":{"RESPONSE_CONTAINER":{"CEI
BRESP2":80,"fileArea":{"date
":"","employeeName":"","amount":"","address":"","phone":"","employeeNumber":"000000"},
"userIdentity":"CICSUSER","CEIBRESP":13}}}}
The EIBRESP and EIBRESP2 values are from a CICS program and the response codes received when a EXEC
CICS READ fails with a Not Found condition.

The target API was developed using z/OS Connect and had a response code mapping that checked the values of
EIBRESP and EIBRESP2 and if this error occurred, the API was to return an HTTP 404 return code.
//POSTAPI EXEC PGM=POSTAPI,PARM='323232'

//CEEOPTS DD *
POSIX(ON),
"BAQPORT=9120")
___4. Submit the job in member POSTAPI in USER1.ZCEE.CNTL.
___5. The job should complete with a condition code of 200 and have the following output for SYSPRINT.
EIBRESP: 00000000
EIBRESP2: 00000000
USERID: CICSUSER
HTTP CODE: 0000000200
This job added a record for employee 323232.
___6. Edit member GETAPI and change the PARM value to 323232 and submit the job.
EmployeeNumber: 323232
EmployeeName: John
Address: Apex
Phone: 0065
Date: 11 22 65
Amount: $1000.65
EIBRESP: 00000000
EIBRESP2: 00000000
USERID: CICSUSER
HTTP CODE: 0000000200
___7. Member DELTAPI in USER.ZCEE.CNTL will delete a record and PUTAPI will update an existing record.
Submit these jobs and observe the results. Or if you want to modify the request messages in POSTAPI and
PUTAPI and recompile and relink these programs and observe the results when different values are provided.

The available records are listed below:
numb name addrx Phone datex amount

000100 S. D. BORMAN SURREY, ENGLAND 32156778 26 11 81 $0100.11
000102 J. T. CZAYKOWSI WARWICK, ENGLAND 98356183 26 11 81 $1111.11
000104 M. B. DOMBEY LONDON,ENGLAND 12846293 26 11 81 $0999.99
000106 A. I. HICKSON CROYDON, ENGLAND 19485673 26 11 81 $0087.71
000111 ALAN TULIP SARATOGA,CALIFORNIA 46120753 01 02 74 $0111.11
000762 SUSAN MALAIKA SAN JOSE,CALIFORNIA 22312121 01 06 74 $0000.00
000983 J. S. TILLING WASHINGTON, DC 34512120 21 04 75 $9999.99
001222 D.J.VOWLES BOBLINGEN, GERMANY 70315551 10 04 73 $3349.99
001781 TINA J YOUNG SINDELFINGEN,GERMANY 70319990 21 06 77 $0009.99
003210 B.A. WALKER NICE, FRANCE 12345670 26 11 81 $3349.99
003214 PHIL CONWAY SUNNYVALE, CAL. 34112120 00 06 73 $0009.99
003890 BRIAN HARDER NICE FRANCE 00000000 28 05 74 $0009.99
004004 JANET FOUCHE DUBLIN, IRELAND 71112121 02 11 73 $1259.99
004445 DR. P. JOHNSON SOUTH BEND, S.DAK. 61212120 26 11 81 $0009.99
004878 ADRIAN JONES SUNNYVALE, CALIF. 32212120 10 06 73 $5399.99
005005 A. E. DALTON SAN FRANCISCO, CA. 00000001 01 08 73 $0009.99
005444 ROS READER SARATOGA, CALIF. 67712120 20 10 74 $0809.99
005581 PETE ROBBINS BOSTON, MASS. 41312120 11 04 74 $0259.99
006016 SIR MICHAEL ROBERTS NEW DELHI, INDIA 70331211 21 05 74 $0009.88
006670 IAN HALL NEW YORK, N.Y. 21212120 31 01 75 $3509.88
006968 J.A.L. STAINFORTH WARWICK, ENGLAND 56713821 26 11 81 $0009.88
007007 ANDREW WHARMBY STUTTGART, GERMANY 70311000 10 10 75 $5009.88
007248 M. J. AYRES REDWOOD CITY, CALF. 33312121 11 10 75 $0009.88
007779 MRS. A. STEWART SAN JOSE, CALIF. 41512120 03 01 75 $0009.88
009000 P. E. HAVERCAN WATERLOO, ONTARIO 09876543 21 01 75 $9000.00
100000 M. ADAMS TORONTO, ONTARIO 03415121 26 11 81 $0010.00
111111 C. BAKER OTTAWA, ONTARIO 51212003 26 11 81 $0011.00
200000 S. P. RUSSELL GLASGOW, SCOTLAND 63738290 26 11 81 $0020.00
222222 DR E. GRIFFITHS FRANKFURT, GERMANY 20034151 26 11 81 $0022.00
300000 V. J. HARRIS NEW YORK, U.S. 64739801 26 11 81 $0030.00
333333 J.D. HENRY CARDIFF, WALES 78493020 26 11 81 $0033.00
400000 C. HUNT MILAN, ITALY 25363738 26 11 81 $0040.00
444444 D. JACOBS CALGARY, ALBERTA 77889820 26 11 81 $0044.00
500000 P. KINGSLEY MADRID, SPAIN 44454640 26 11 81 $0000.00
555555 S.J. LAZENBY KINGSTON, N.Y. 39944420 26 11 81 $0005.00
600000 M.F. MASON DUBLIN, IRELAND 12398780 26 11 81 $0010.00
666666 R. F. WALLER LA HULPE, BRUSSELS 42983840 26 11 81 $0016.00
700000 M. BRANDON DALLAS, TEXAS 57984320 26 11 81 $0002.00
777777 L.A. FARMER WILLIAMSBURG, VIRG. 91876131 26 11 81 $0027.00
800000 P. LUPTON WESTEND, LONDON 24233389 26 11 81 $0030.00
888888 P. MUNDY NORTHAMPTON, ENG. 23691639 26 11 81 $0038.00
900000 D.S. RENSHAW TAMPA, FLA. 35668120 26 11 81 $0040.00
999999 ANJI STEVENS RALEIGH, N.Y. 84591639 26 11 81 $0049.00
Summary
You have use the z/OS Connect build toolkit to generate an API requester archive file and the COBOL copy
books that must be included in the COBOL application program when accessing the API requester archive file
in a z/OS Connect server. The COBOL applications have been compiled and link-edited and the target API has
been tested using various RESTful methods

RESTful API Requester to a MQ One-Way RESTful API

In this section an API requester will be developed and tested where the target API accesses a MQ queue. The
batch programs will be put messages (POST) to the queue, do non-destructive gets (GET) and destructive gets
(DELETE) of messages from the same queue.

where the API is hosted. All the files mention in this section are in directory c:/z/apiRequester/mqapi on your
workstation.
https://www.ibm.com/support/knowledgecenter/en/SS4SVW_3.0.0/com.ibm.zosconnect.doc/instal
ling/bt_install.html
___1. Begin by reviewing the API’s Swagger document for the MQ one-way API. This document identifies the types
of HTTP methods supported as well as the path of each HTTP method. It also the contents each method’s
request JSON message and the response JSON message field contents and field types. This is the blue print for
invoking the API.
{
"swagger": "2.0",
"info": {
"description": "",
"version": "1.0.0",
"title": "mqapi"
},
"basePath": "/mqapi",
"schemes": [
"https",
"http"
],
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"paths": {
"/queue": {
"get": {
"tags": [
"mqapi"
],
"operationId": "getMqGet",
"parameters": [
RESTful API Requester to a MQ One-Way RESTful API 19 of 49

This file is mqapi.properties see its below:
apiDescriptionFile=./mqapi.json 1
language=COBOL 5
connectionRef=mqapi 6
requesterPrefix=mq 7

2. Provides the directory where the generated COBOL copybooks representing the request and response
3. Provides the directory where the generated COBOL copybook with invocation details of the API will
be written.
4. Provides the directory where a log file will be written.
___3. View file mqAPI.bat which contains this one line.
c:\z\zconbt\bin\zconbt.bat -p=./mqapi.properties -f=./mqapi.ara
archive file. The API requester archive (ARA) file will be uploaded and make available to the z/OS Connect
EE server in directory …/resources/zosconnect/apiRequsters.
___5. Use the change directory command (cd) to change to directory apiRequester/mqapi, e.g.
cd c:\z\apiRequester\mqapi

___6. Enter command mqAPI.bat in the DOS command prompt window and you should see output like the below:
c:\z\apiRequester\mqapi>c:\z\software\zconbt\bin\zconbt.bat -p=./mqapi.properties -
f=./mqapi.ara
BAQB0008I: Creating API requester archive from configuration file ./mqapi.properties.
BAQB0040I: The generated API requester is automatically named mqapi_1.0.0 based on the title
mqapi and version 1.0.0 of the API to be called.
BAQB0015I: Start processing operation (operationId: getMqGetService, relativePath: /queue,
method: GET).
BAQB0016I: Successfully processed operation (operationId: getMqGetService, relativePath:
/queue, method: GET).
BAQB0015I: Start processing operation (operationId: postMqPutService, relativePath: /queue,
method: POST).
BAQB0016I: Successfully processed operation (operationId: postMqPutService, relativePath:
/queue, method: POST).
Total 2 operation(s) (success: 2, ignored: 0) defined in api description file: ./mqapi.json

operationId: getMqGetService, basePath: /mqapi, relativePath: /queue, method: GET
- request data structure : No data structure needs to be generated.
- response data structure : MQ000P01
- api info file : MQ000I01
operationId: postMqPutService, basePath: /mqapi, relativePath: /queue, method: POST

- request data structure : MQ001Q01
- response data structure : No data structure needs to be generated.
- api info file : MQ001I01
BAQB0009I: Successfully created API requester archive file ./mqapi.ara.
Note that each HTTP method defined in the Swagger document will normally cause the generation of up to
three copy books. One for the request message(Q01), one for the response message(P01) and one for the API
details(I01). For this API only two copy books were generated for the messages. One for either the request
message or one for the response message. In this case the API did not require both types for any method. Also
note that the copy book names are based on the requesterPrefix property (e.g. mq) and use an ascending
sequence number sequence to differentiate between methods.
the sample programs later in this exercise verify the copy books included for a particular method has

___7. Now explore a sample snippet of the copy book for the request message of a PUT method. Use EditPad Lite to
open file c:\z\apiRequester\mqapi\syslib\MQ001Q01. Scroll down until you see something like the code below.
06 ReqBody.
09 MQMESSAGE2-num PIC S9(9) COMP-5 SYNC.
09 MQMESSAGE.
12 STAT-num PIC S9(9) COMP-5 SYNC.
12 STAT.
15 STAT2-length PIC S9999 COMP-5 SYNC.
15 STAT2 PIC X(1).
12 NUMB-num PIC S9(9) COMP-5 SYNC.
12 NUMB.
15 NUMB2-length PIC S9999 COMP-5 SYNC.
15 NUMB2 PIC X(6).
12 NAME-num PIC S9(9) COMP-5 SYNC.
12 NAME.
15 NAME2-length PIC S9999 COMP-5 SYNC.
Note that each variable has an associated length (e.g. STAT2-length). The length of a variable is required since
there is no delimiter between the variables in storage. The runtime needs to know the size of a variable at
execution time so the request and response messages can be properly converted to and from JSON name/value
pairs.
A response message (c:\z\apiRequester\mqapi\syslib\MQ000P01) will have a similar layout.
___8. An API information copy book (c:\z\apiRequester\mqapi\syslib\MQ001I01) has contents providing the API
name and the path to be used for the method:
VALUE 'mqapi_1.0.0'.
VALUE 11.
VALUE '%2Fmqapi%2Fqueue'.
VALUE 16.
VALUE 'GET'.
VALUE 3.

___1. Open a DOS command session and change to directory C:\z\apiRequester\mqapi, e.g cd
\z\apiRequester\mqapi
command embedded in command file deployMqapi.bat. Invoke this command file to deploy the MQ API
archive file.
c:\z\apiRequester\mqapi>curl -X POST --user Fred:fredpwd --data-binary @mqapi.ara

--header "Content-Type: application/zip" --insecure
https://wg31.washington.ibm.com:9483/zosConnect/apiRequesters
{"name":"mqapi_1.0.0","version":"1.0.0","description":"","status":"Started"
,"apiRequesterUrl":"https:\/\/wg31.washington.ibm.com:9483\/zosConnect\/apiReque
sters\/mqapi_1.0.0","connection":"mqapi"}
Tech-Tip: If a REST client tool like cURL or Postman was not available then ARA file could
have been deployed using FTP to upload the file in binary mode to the apiRequesters directory.
Tech-Tip: If an ARA needs to be redeployed, the cURL command with a PUT method can be used to
stop the API requester
curl -X PUT --user Fred:fredpwd --insecure
https://wg31.washington.ibm.com:9483/zosConnect/apiRequesters/mqapi_1.0.0?status=stopped
curl -X DELETE --user Fred:fredpwd --insecure
https://wg31.washington.ibm.com:9483/zosConnect/apiRequesters/mqapi_1.0.0

___2. The z/OS Connect EE server where the API requester will be installed has the configuration below in its
server.xml file.

<featureManager>
</featureManager>
<zosconnect_endpointConnection id="mqapi" 1
host="http://wg31.washington.ibm.com"
port="9120"
user="Fred"
</server>
2. The target server uses basic authentication, so we are simply provided a user identity and password.
The password can be encrypted and/or TLS can be used for security.
Tech-Tip: The host and port in the endpointConnection element specifies the host and port of
the target API provider. Normally the z/OS Connect server performs the conversion of the
COBOL data structure to JSON and then acts as a JSON REST client to the target API provider.
In this exercise the target API provider is the same z/OS Connect server. This is why this host
and port is also used by the batch API requester client in its environment variables.


SYSLIB concatenation sequence. In the data set is USER1.ZCEE.SOURCE. Use a DOS command prompt
(password USER1).
C:\z\apiRequester\fileaqueue\syslib, e.g. cd \z\apiRequester\mqapi\syslib
___3. Logon as USER1 and then use the cd command to change to directory to data set USER1.ZCEE.SOURCE, e.g.
cd zcee.source
___5. Perform multiple put request by using the multiple put command, mput imq*
c:\z\apiRequester\cscvinc>cd syslib
c:\z\apiRequester\cscvinc\syslib>ftp wg31.washington.ibm.com
220-FTP 16:26:23 on 2018-02-15.
Password:
ftp> cd zcee.source
ftp> prompt
ftp> mput MQ*
125 Storing data set USER1.ZCEE.SOURCE(MQ000I01)
sent in 0.10Seconds 110.89Kbytes/sec.
…….
125 Storing data set USER1.ZCEE.SOURCE(MQ01I01)
ftp> quit


edit the application programs. The source for the application programs are in USER1.ZCEE. SOURCE.
Member DELMQAPI invokes the DELETE method, member GETMQAPI invokes the GET method and
PSTMQAPI invokes the POST method. No changes need to be made to these programs.
Explorer filter or by using the Personal Communication icon on the desktop and logging on to
TSO and use ISPF option 3.4 to access this data set. If you have any questions about either method
ask the instructor.
___1. Begin by reviewing the application programs MQGET. Browse data set USER1.ZCEE. SOURCE and open
member MQGET. Scroll down until you see these lines of code.

COPY BAQRINFO.

01 API-REQUEST.
10 FILLER PIC X(1).
01 API_RESPONSE.
COPY MQ000P01.
01 API-INFO-OPER1.
COPY MQ000I01.
books generated by the z/OS Connect EE build tool kit. If when you generated the copy book earlier in the
exercise and the sequence number used for the GET method was not 02 then you need to change the COBOL
source to match sequence generated when you invoke the ZCONBT tool.
*---------------------------------------------------------------*
*---------------------------------------------------------------*

message).
___3. Scroll down further and you will see the code where the application displays the results in the response
message.
IF BAQ-SUCCESS THEN
DISPLAY "NUMB: " numb of API_RESPONSE
DISPLAY "NAME: " name of API_RESPONSE
DISPLAY "ADDRX: " addrx of API_RESPONSE
DISPLAY "PHONE: " phone of API_RESPONSE
DISPLAY "DATEX: " datex of API_RESPONSE
DISPLAY "AMOUNT: " amount of API_RESPONSE
DISPLAY "HTTP CODE: " BAQ-STATUS-CODE
___4. Exit member MQGET and open member MQPUT. The code for this program is very similar to the code for
MQGET with the exception that all variables are provided in a JSON request message. Scroll down and find the
code below.
*---------------------------------------------------------------*
*---------------------------------------------------------------*
MOVE 1 to MQMESSAGE2-num.
MOVE "837367" TO numb2 IN API-REQUEST.
MOVE LENGTH of numb2 in API-REQUEST to
numb2-length IN API-REQUEST.
MOVE "John" TO name2 IN API-REQUEST.

MOVE LENGTH of name2 in API-REQUEST to
name2-length IN API-REQUEST.
MOVE "Apex" TO addrx2 IN API-REQUEST.

MOVE LENGTH of addrx2 in API-REQUEST to
addrx2-length IN API-REQUEST.
MOVE "0065" TO phone2 IN API-REQUEST.

MOVE LENGTH of phone2 in API-REQUEST to
phone2-length IN API-REQUEST.
MOVE "11 22 65" TO datex2 IN API-REQUEST.

MOVE LENGTH of datex2 in API-REQUEST to
datex2-length IN API-REQUEST.
MOVE "$1000.65" TO amount2 IN API-REQUEST.

MOVE LENGTH of amount2 in API-REQUEST to
amount2-length IN API-REQUEST.
In this case the length of the property value and finally the property value moved to the request copy book.

The applications programs now are ready to be compiled and link-edited.
___1. Submit the job in member APIRMQ in data set USER1.ZCEE.CNTL.
//USER1S JOB MSGCLASS=H,NOTIFY=&SYSUID

//* JCLLIB ORDER=SYS1.ECOBOL.SIGYPROC
//COBOL.SYSIN DD DISP=SHR,DSN=USER1.ZCEE.SOURCE(MQGET)
//LKED.SYSLMOD DD DISP=SHR,DSN=USER1.ZCEE.LOADLIB(MQGET)
//COBOL.SYSIN DD DISP=SHR,DSN=USER1.ZCEE.SOURCE(MQPUT)
//LKED.SYSLMOD DD DISP=SHR,DSN=USER1.ZCEE.LOADLIB(MQPUT)
module library containing BAQSCTUB (ZCEE30.SBAQLIB) must be available in the STEPLIB concatenation
sequence when the program is executed.
The execution of this job should complete with at most a 4-return code.

The JCL to execute these programs can be found in USER1.ZCEE.CNTL, the member names in this data set
match the program names. The members are DLTMQAPI, GETMQAPI and PSTMQAPI.
___1. Submit the job in member MQGET in USER1.ZCEE.CNTL.

//GETAPI EXEC PGM=MQGET
//CEEOPTS DD *
POSIX(ON),
"BAQPORT=9120")
___2. The job should complete with a condition of 200 (HTTP success) and have the following output for SYSPRINT.
NUMB: 000100
NAME: S. D. BORMAN
ADDRX: SURREY, ENGLAND
PHONE: 32156778
DATEX: 26 11 81
AMOUNT: $0100.11
HTTP CODE: 0000000200
Tech-Tip: An HTTP code of 200 indicates success. For an explanation of HTTP codes see URL
___3. Member MQPUT in USER.ZCEE.CNTL will invokes a POST HTTP method which will put a message on the
queue. Submit this job for execution and observe the results. The POST method for this API does not return a
response message.
HTTP CODE: 0000000204
Tech-Tip: An HTTP code of 204 indicates that the server processed the request and is not
returning any content. For an explanation of HTTP codes see URL

___4. Confirm by opening the MQExplorer icon on the desktop and browsing the messages in the
ZCONN2.DEFAULT.MQZCEE.QUEUE queue.
 Select QMZ1 under Queue Managers and right mouse button click
 Select the Connect option.
 Once connected, expand the Queues folder and select ZCONN2.DEFAULT.MQZEE.QUEUE and
right mouse button click and select the Browse Messages option.

___5. Your see a list of the messages currently in the queue, something like the list below:

RESTful API Requester from a CICS application
In this section a CICS based API requester will be developed and tested. The target API accessed from the CICS
application is used to approve loan requests. The API uses the contents of JSON request to determine if a loan
can be approved. The results are returned in a response message including the explanation if the loan is denied.
The rules for rejecting a loan can be for any one of the following:
 If the credit score of the borrower is less than 300.

 If the yearly repayment amount is more than 30% of the borrower’s income.
 If the income of the borrower is less than $24,000.
 If the age of the borrower is more than 65 years.
 The loan amount is more than $1,000,000.
.

where the API is hosted. All the files mention in this section are in directory c:/z/apiRequester/miniloan on your
workstation.
RESTful API Requester from a CICS application 32 of 49

___9. Begin by reviewing the API’s Swagger document for the API. This document identifies the types of HTTP
methods supported as well as the path of each HTTP method. It also the contents each method’s request JSON
message and the response JSON message field contents and field types. This is the blue print for invoking the
API.
"swagger": "2.0",
"info": {
"description": "",
"version": "1.0.0",
"title": "miniloancics"
},
"basePath": "/miniloancics",
"schemes": [
"https",
"http"
],
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"paths": {
"/loan": {
"post": {
"tags": [
"miniloancics"
https://www.ibm.com/support/knowledgecenter/en/SS4SVW_3.0.0/com.ibm.zosconnect.doc/instal
ling/bt_install.html

This file is miniloan.properties, see its contents below:
1
apiDescriptionFile=miniloan.json
language=COBOL 5
connectionRef=miniloancicsAPI 6
requesterPrefix=min 7

2. Identifies the location where the generated COBOL copybooks representing the request and response
3. Identifies the location where the generated COBOL copybook with invocation details of the API will
be written.
4. Provides the location where a log file will be written.
___11. View file miniloanAPI.bat which contains this one line.
c:\z\zconbt\bin\zconbt.bat -p=./miniloan.properties -f=./miniloan.ara
archive file. The API requester archive (ARA) file will be deployed and made available to the z/OS Connect
EE server in directory …/resources/zosconnect/apiRequesters.
___13. Use the change directory command (cd) to change to directory C:\z\api\Requester\cscvinc, e.g.
cd c:\z\apiRequester\miniloan

___14. Enter command miniloanAPI.bat in the DOS command prompt window and you should see output like the
below:
c:\z\apiRequester\miniloan>c:\z\software\zconbt\bin\zconbt.bat -p=./miniloan.properties -
f=./miniloan.ara
BAQB0008I: Creating API requester archive from configuration file ./miniloan.properties.
BAQB0040I: The generated API requester is automatically named miniloan_1.0.0 based on the title
miniloan and version 1.0.0 of the API to be called.
BAQB0015I: Start processing operation (operationId: postMiniloanService, relativePath: /loan, method:
POST).
BAQB0016I: Successfully processed operation (operationId: postMiniloanService, relativePath: /loan,
method: POST).
Total 1 operation(s) (success: 1, ignored: 0) defined in api description file: miniloan.json

operationId: postMiniloanService, basePath: /miniloan, relativePath: /loan, method: POST
- request data structure : MIN00Q01
- response data structure : MIN00P01
- api info file : MIN00I01
BAQB0009I: Successfully created API requester archive file ./miniloan.ara.
Note that each HTTP method defined in the Swagger document will cause the generation of up to three copy
books. One for the request message(Q01), one for the response message(P01) and one for the API details(I01).
The copy book names are based on the requesterPrefix property (e.g. MIN) and use an ascending sequence
number sequence to differentiate between methods. Also note that there may be fewer than three copy books
generated. For example, if there is no response message or no request message for a specific method a copy
book may not be generated.
the sample programs later in this exercise verify the copy books included for a particular method has

___15. Now explore a sample snippet of the copy book for the request message of a POST method. Use EditPad Lite to
open file c:\z\apiRequester\minloan\syslib\MIN00Q01. Scroll down until you see something like the code
below.
06 ReqBody.
09 MINILOAN-COMMAREA2-num PIC S9(9) COMP-5 SYNC.
09 MINILOAN-COMMAREA.
12 name-num PIC S9(9) COMP-5 SYNC.
12 name.
15 name2-length PIC S9999 COMP-5 SYNC.
15 name2 PIC X(20).
12 creditScore-num PIC S9(9) COMP-5 SYNC.
12 creditScore PIC 9(18) DISPLAY.
12 yearlyIncome-num PIC S9(9) COMP-5 SYNC.
12 yearlyIncome PIC 9(18) DISPLAY.
12 age-num PIC S9(9) COMP-5 SYNC.
12 age PIC 9(10) DISPLAY.
12 amount-num PIC S9(9) COMP-5 SYNC.
12 amount PIC 9(18) DISPLAY.
12 effectiveDate-num PIC S9(9) COMP-5 SYNC.
12 effectiveDate.
15 effectiveDate2-length PIC S9999 COMP-5 SYNC.
15 effectiveDate2 PIC X(8).
12 yearlyRepayment-num PIC S9(9) COMP-5 SYNC.
12 yearlyRepayment PIC 9(18) DISPLAY.
Note that each variable has an associated length (e.g. name2-length). The length of a variable is required since
there is no delimiter between the variables in storage. The runtime needs to know the size of a variable at
execution time, so the request and response messages can be properly converted to and from JSON name/value
pairs.
For this API, the Swagger document included an additional variable for the number of occurrences of a variable,
(e.g. name-num). In this exercise we will set the number of each variable to one.
The corresponding response message (c:\z\apiRequester\miniloan\syslib\MIN00P01) will have a similar layout.

___16. The corresponding API information copy book (c:\z\apiRequester\miniloan\syslib\MIN00I01) has contents
providing the API name and the path to be used for the method:
VALUE 'miniloancics_1.0.0'.
VALUE 18.
VALUE '%2Fminiloancics%2Floan'.
VALUE 22.
VALUE 'POST'.
VALUE 4.
___5. Open a DOS command session and change to directory c:\z\apiRequester\cscvinc, e.g cd
c:\z\apiRequester\cscvinc
command embedded in command file deployMiniloan.bat. Invoke this command file to deploy the miniloan
API archive file.
C:\z\apiRequester\miniloan>curl -X POST --user user1:user1 --data-binary @minilo

an.ara --header "Content-Type: application/zip" --insecure https://wg31.washing
ton.ibm.com:9483/zosConnect/apiRequesters/miniloan
{"name":"miniloancics_1.0.0","version":"1.0.0","description":"","status":"Starte
d","apiRequesterUrl":"https:\/\/wg31.washington.ibm.com:9483\/zosConnect\/apiReq
uesters\/miniloancics_1.0.0","connection":"miniloancicsAPI"}
Tech-Tip: If a REST client tool like cURL or Postman was not available then ARA file could have
been deployed using FTP to upload the file in binary mode to the apiRequesters directory.
Tech-Tip: If an ARA needs to be redeployed, the cURL command with a PUT method can be used to stop
the API requester
curl -X PUT --user USER1:USER1 --insecure
https://wg31.washington.ibm.com:9483/zosConnect/apiRequesters/miniloan_1.0.0?status=stopped
curl -X DELETE --user USER1:USER1 --insecure
https://wg31.washington.ibm.com:9483/zosConnect/apiRequesters/miniloan_1.0.0

___7. The z/OS Connect EE server where the API requester will be installed has the configuration below.
<featureManager>
</featureManager>
<zosconnect_endpointConnection id="miniloancicsAPI" 1
host="https://wg31.washington.ibm.com"
port="9120"
user="Fred"
</server>
Tech-Tip: Explicitly defining the apiRequesters element for an API Requester prevents use of the
RESTful administrative interface to manage the API requester.

___8. The API requester stubs uses the BAQURIMP resource defined to CICS to locate the z/OS Connect EE server
where the request will be sent.

SYSLIB concatenation sequence. In the data set is USER1.ZCEE. SOURCE. Use a DOS command prompt
(password USER1).
C:\z\apiRequester\cscvinc\syslib, e.g. cd \z\apiRequester\miniloan\syslib
___9. Logon as USER1 and then use the cd command to change to directory to data set USER1.ZCEE. SOURCE, e.g.
cd zcee.source
___11. Perform multiple put requests by using the multiple put command, mput min*
c:\z\apiRequester\miniloan>cd syslib
c:\z\apiRequester\miniloan\syslib>ftp wg31.washington.ibm.com
220-FTP 16:26:23 on 2018-02-15.
Password:
ftp> cd zcee.source
ftp> prompt
ftp> mput MIN*
125 Storing data set USER1.ZCEE.SOURCE(MIN00I01)
125 Storing data set USER1.ZCEE.SOURCE(MIN00P01)
125 Storing data set USER1.ZCEE.SOURCE(MIN00Q01)
ftp> quit


edit the application program.
Explorer filter or by using the Personal Communication icon on the desktop and logging on to
TSO and use ISPF option 3.4 to access this data set. If you have any questions about either
method, ask the instructor.
___1. Back in the IBM z/OS Explorer session switch to the Remote System Explorer perspective (see page Error!
Bookmark not defined.) and expand data set USER1.ZCEE.SOURCE in the Remote System view to display a
list of its members.
___2. Begin by reviewing the application programs LOANAPIR. Open member LOANAPIR in USER1.ZCEE.
SOURCE and review its contents by selecting the member and right- mouse button clicking and selecting the
Open option. Scroll down until you see these lines of code.
books generated by the z/OS Connect EE build tool kit.

COPY BAQRINFO.

01 API-REQUEST.
COPY MIN01Q01.
01 API_RESPONSE.
COPY MIN01P01.
01 API-INFO-OPER1.
COPY MIN01I01.

Scroll down further until you find this code which sets the contents of the request message and invoke the API.
WHEN DFHENTER
MOVE NAMEI to NAME2 in API-REQUEST
MOVE LENGTH of NAME2 in API-REQUEST to
NAME2-length in API-REQUEST
MOVE AGEI to AGE in API-REQUEST
MOVE CRDSCREI to CREDITSCORE in API-REQUEST
MOVE INCOMEI to YEARLYINCOME in API-REQUEST
MOVE AMOUNTI to AMOUNT in API-REQUEST
MOVE YRPAYMNTI
To YEARLYREPAYMENT in API-REQUEST
MOVE 1 to MINILOAN-COMMAREA2-num IN API-REQUEST
MOVE 1 to NAME-num IN API-REQUEST
MOVE 1 to CREDITSCORE-num IN API-REQUEST
MOVE 1 to YEARLYINCOME-num IN API-REQUEST
MOVE 1 to AGE-num IN API-REQUEST
MOVE 1 to AMOUNT-num IN API-REQUEST
MOVE 1 to YEARLYREPAYMENT-num IN API-REQUEST
PERFORM INVOKE-API
___3. Scroll down further to see the CICS commands to display the results on the screen.
IF BAQ-SUCCESS THEN
IF APPROVED2 in API-RESPONSE = 'T'
MOVE 'Loan approved' to approvedo
ELSE
MOVE 'Loan not approved' to approvedo
END-IF
MOVE UID2 TO UIDO
MOVE MESSAGES2(1) TO MSG1O
ELSE
….
END-IF.
EXEC CICS SEND CONTROL ERASE END-EXEC
EXEC CICS SEND MAP('MINIMAP')
MAPSET('MINIMAP')
FREEKB ERASE END-EXEC
EXEC CICS RETURN TRANSID ('APIR')
COMMAREA (COMMAREA-BUFFER) END-EXEC.

INVOKE-API SECTION.
*---------------------------------------------------------------*
* Initialize API Requester PTRs & LENs *
*---------------------------------------------------------------*
* Use pointer and length to specify the location of
* request and response segment.
* This procedure is general and necessary.
SET BAQ-REQUEST-PTR TO ADDRESS OF API-REQUEST
MOVE LENGTH OF API-REQUEST TO BAQ-REQUEST-LEN
SET BAQ-RESPONSE-PTR TO ADDRESS OF API-RESPONSE
MOVE LENGTH OF API-RESPONSE TO BAQ-RESPONSE-LEN
*---------------------------------------------------------------*
*---------------------------------------------------------------*
CHECK-API-ERROR SECTION.
* Some error happened in API, z/OS Connect EE server
* or communication stub. 'BAQ-STATUS-CODE' and
* 'BAQ-STATUS-MESSAGE' contain the detailed information
* of this error.
DISPLAY "Error code: " BAQ-STATUS-CODE
DISPLAY "Error msg:" BAQ-STATUS-MESSAGE
MOVE BAQ-STATUS-CODE TO EM-CODE
MOVE BAQ-STATUS-MESSAGE TO EM-DETAIL
EVALUATE TRUE
* When error happens in API, BAQ-RETURN-CODE is BAQ-ERROR-IN-API.
* BAQ-STATUS-CODE is the HTTP response code of API.
WHEN BAQ-ERROR-IN-API
MOVE 'API' TO EM-ORIGIN
* When error happens in server, BAQ-RETURN-CODE is
* BAQ-ERROR-IN-ZCEE
* BAQ-STATUS-CODE is the HTTP response code of
* z/OS Connect EE server.
WHEN BAQ-ERROR-IN-ZCEE
MOVE 'ZCEE' TO EM-ORIGIN
* When error happens in communication stub, BAQ-RETURN-CODE is
* BAQ-ERROR-IN-STUB, BAQ-STATUS-CODE is the error code of STUB.
WHEN BAQ-ERROR-IN-STUB
MOVE 'STUB' TO EM-ORIGIN
END-EVALUATE

message).

The applications programs now are ready to be compiled and link edited.
___2. Submit the job in member LOANAPIR in data set USER1.ZCEE.CNTL.

module library containing the CICS version of BAQSCTUB (SBAQLIB1) must be available in the DFHRPL
concatenation sequence when the program is executed.
//COMPILE EXEC IGYWCL,LNGPRFX=IGY610,

// PARM.COBOL='LIB,NODYNAM,CICS,SIZE(4000K)'
//COBOL.STEPLIB DD
// DD DISP=SHR,DSN=CICSTS54.CICS.SDFHLOAD
//COBOL.SYSIN DD DISP=SHR,DSN=USER1.ZCEE.SOURCE(LOANAPIR)
//COBOL.SYSLIB DD DISP=SHR,DSN=USER1.ODM.JCL
// DD DISP=SHR,DSN=USER1.ZCEE.SOURCE
// DD DISP=SHR,DSN=CICSTS54.CICS.SDFHCOB
//LKED.SYSLMOD DD DISP=SHR,DSN=USER1.ZCEE.LOADLIB(LOANAPIR)
//LKED.CICSLIB DD DISP=SHR,DSN=CICSTS54.CICS.SDFHLOAD
//LKED.SYSIN DD *
INCLUDE CICSLIB(DFHELII)
This job should complete with a zero-return code.

Tech Tip: To submit a job when using the IBM z/OS Explorer select the member and right
mouse button click and select the Submit option. Or if the member is currently opened simply right
mouse button click and select the Submit option. Click the Locate Job button on the Job
Confirmation pop-up. This will display the job output in the Retrieved Job section under JES in
the Remote Systems view. The job’s output can be viewed right mouse button clicking and
selecting the Open option.


___1. In a new or existing 3270 session start a session with CICS, clear the screen and enter CICS transaction CEDF
to start a CICS execution diagnostic facility (EDF).
___2. Clear the screen again and enter CICS transaction APIR.
___3. Use the F9 key to set a stop condition. Set a stop on EXEC CICS WEB OPEN commands.

___4. Use the F4 key to suppress the intervening EDF displays. Eventually EDF will stop on a task termination
screen. Ensure the Reply is set to Yes and press Enter to continue.
___5. Enter the information shown below and press Enter.

___6. Suppress the EDF displays again using the F4 key. Eventually there will be EXEC CICS WEB OPEN request.
___7. Keep pressing the Enter key until the EXEC CICS WEB WRITE EDF screen is displayed.

___8. Press the Enter key until the EXEC CICS WEB CONVERSE EDF screen is displayed.
___9. Keep pressing Enter until the results of the loan application is displayed.
___10. Repeat loan applications with and/or without EDF to see the results of various scenarios.

Summary
You have use the z/OS Connect build toolkit to generate an API requester archive file and the COBOL copy
books that must be included in the COBOL application program when accessing the API requester archive file
in a z/OS Connect server. The COBOL applications have been compiled and link edited, and the target API has
been tested using various RESTful methods
Summary 49 of 49

Developing Outbound APIs Requesters Applications

Uploaded by

Copyright:

Available Formats

Developing Outbound APIs Requesters Applications

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Developing Outbound APIs Requesters Applications

Uploaded by

Copyright:

Available Formats

IBM z/OS Connect EE V3.

Lab Version Date: May 30, 2020

General Exercise Information and Guidelines

 This exercise primarily uses data sets USER1.ZCEE.CNTL and USER.ZCEE.SOURCE.

RESTful API Requester to a CICS RESTful API

Generate the API requester artifacts from a Swagger document

1. Identifies the Swagger document that describes the API

___3. View file cscvincAPI.bat which contains this one line.

c:\z\zconbt\bin\zconbt.bat -p=./cscvinc.properties -f=./cscvinc.ara

RESTful API Requester to a CICS RESTful API 6 of 49

Total 4 operation(s) (success: 4, ignored: 0) defined in api description file: ./cscvinc.json

operationId: putCscvincUpdateService, basePath: /cscvincapi, relativePath: /employee/{employee},

operationId: postCscvincInsertService, basePath: /cscvincapi, relativePath: /employee/{employee},

operationId: deleteCscvincDeleteService, basePath: /cscvincapi, relativePath: /employee/{employee},

BAQB0009I: Successfully created API requester archive file ./cscvinc.ara.

RESTful API Requester to a CICS RESTful API 7 of 49

The corresponding response message (c:\z\apiRequester\cscvinc\syslib\CSC00P01) will have a similar layout.

c:\z\apiRequester\cscvinc>curl -X POST --user Fred:fredpwd --data-binary @cscvin

RESTful API Requester to a CICS RESTful API 9 of 49

<server description="API Requester">

Move the COBOL copy books to a MVS data set

RESTful API Requester to a CICS RESTful API 10 of 49

___4. Toggle prompting off by entering command prompt

Review the application programs

RESTful API Requester to a CICS RESTful API 11 of 49

* Request and Response

RESTful API Requester to a CICS RESTful API 12 of 49

RESTful API Requester to a CICS RESTful API 13 of 49

MOVE employeeNumber of PARM-DATA TO employeeNumber2

MOVE "John" TO employeeName2 IN API-REQUEST.

RESTful API Requester to a CICS RESTful API 14 of 49

Compile and link-edit the application programs

___1. Submit the job in member CSCVINC in data set USER1.ZCEE.CNTL.

//COMPILE EXEC IGYWCL,LNGPRFX=SYS1.ECOBOL,PARM.COBOL='NODYNAM

This job should complete with a zero-return code.

RESTful API Requester to a CICS RESTful API 15 of 49

Test the API requester application programs

___1. Submit the job in member GETAPI in USER1.ZCEE.CNTL.

Error code: 0000000404

RESTful API Requester to a CICS RESTful API 16 of 49

//POSTAPI EXEC PGM=POSTAPI,PARM='323232'

___4. Submit the job in member POSTAPI in USER1.ZCEE.CNTL.

This job added a record for employee 323232.

RESTful API Requester to a CICS RESTful API 17 of 49

The available records are listed below:

numb name addrx Phone datex amount

RESTful API Requester to a CICS RESTful API 18 of 49

RESTful API Requester to a MQ One-Way RESTful API

Generate the API requester artifacts from a Swagger document

RESTful API Requester to a MQ One-Way RESTful API 19 of 49

1. Identifies the Swagger document that describes the API

___3. View file mqAPI.bat which contains this one line.

c:\z\zconbt\bin\zconbt.bat -p=./mqapi.properties -f=./mqapi.ara

RESTful API Requester to a MQ One-Way RESTful API 20 of 49

Total 2 operation(s) (success: 2, ignored: 0) defined in api description file: ./mqapi.json

operationId: postMqPutService, basePath: /mqapi, relativePath: /queue, method: POST

BAQB0009I: Successfully created API requester archive file ./mqapi.ara.

RESTful API Requester to a MQ One-Way RESTful API 21 of 49

RESTful API Requester to a MQ One-Way RESTful API 22 of 49

c:\z\apiRequester\mqapi>curl -X POST --user Fred:fredpwd --data-binary @mqapi.ara