Demo of consuminga REST API from an IMS programusing z/OS Connect EEAymeric Affouard [email protected]
IBM
November 2019
Session HD – Wellington B
2 © 2017 IBM Corporation2 © 2017 IBM Corporation
• z/OS Connect EE overview
• API requester• IMS scenario
• Summary and more information
Contents
3 © 2017 IBM Corporation3 © 2017 IBM Corporation3 © 2017 IBM Corporation3 © 2017 IBM Corporation
What is z/OS Connect EE?
z/OS Connect EE is IBM’s strategic solution for creating and deploying natural REST APIs for z/OS assets in a unified manner across different
subsystems with integrated security and scalability
IBM Client Center Montpellier
z/OS Connect EE is normally deployed with an API management solution which supports the entire API lifecycle from creation, security
and management
4 © 2017 IBM Corporation4 © 2017 IBM Corporation
z/OS Connect EE V3
DataConversion
DiscoveryFunction
AuditFunction
LoggingFunction
GranularAuthorization
CICS
IMS
DB2
Custom
REST client
RESTJSON
Batch using WOLA APIs to host a service
MQ
4
WAS z/OS
3rd Party
Service Provider
z/OS Connect EE V3 runtime server
1. Liberty is provided as a runtime. 2. Backend connectivity is provided with "service
provider" code.
3. ‘Interceptors" and provide function that is called for each request that arrives.
4. Both the "service provider" and "interceptor" interfaces are extensible.
1
3
2
4
Liberty z/OS Runtime
IBM Client Center Montpellier
5 © 2017 IBM Corporation5 © 2017 IBM Corporation5 © 2017 IBM Corporation5 © 2017 IBM Corporation
z/OS Connect EE V3
APIs to and from the mainframe
Comprehensive subsystem support and unified tooling
Point-and-click API creation
• Create services to CICS and IMS using a common API Toolkit • Support for applications with complex data structures• New CICS Service Provider that uses IPIC (TCP/IP) protocol and supports multi-
container channels and cross LPAR connectivity• Call external APIs from your mainframe applications• Simple integration into enterprise API management solutions
IBM Client Center Montpellier
v
v
6 © 2017 IBM Corporation6 © 2017 IBM Corporation6 © 2017 IBM Corporation6 © 2017 IBM Corporation
§ CICS, IMS or other z/OS applications can call RESTful APIs using z/OS Connect EE§ Artifacts created using z/OS Connect EE Build Toolkit§ Minimum changes to application§ Configurable security (e.g OAuth 2.0)
API requester - Introduction
IBM Client Center Montpellier
7 © 2017 IBM Corporation7 © 2017 IBM Corporation
z/OS Connect EE V3
DataConversion
AuditFunction
LoggingFunction
GranularAuthorization
CICS
IMS
z/OS Application
RESTJSON
7
CommsStub
z/OS Connect EE runtime server
1. Liberty is provided as a runtime. 2. Backend connectivity is provided with a
"communication stub" code.
3. "Interceptors" provide functions that is called for each request that arrives.
4. "Interceptor" interface is extensible.
1
3
2
4
Liberty z/OS Runtime
IBM Client Center Montpellier
API provider
RESTfulendpoint
8 © 2017 IBM Corporation8 © 2017 IBM Corporation8 © 2017 IBM Corporation8 © 2017 IBM Corporation
Implementation steps
IBM Client Center Montpellier
API provider
z/OS LPAR
z/OS Address Space z/OS Connect EE
RESTfulendpoint
server.xml
z/OS application
1. Install supplied resources in z/OS address space (including communication stub)
2. Generate the API requester artifacts (copybooks and API requester archive)
3. Configure connection between z/OS Connect EE and API provider
4. Deploy the API requester archive (.ara file)
5. Update z/OS application with copybooks and call to communication stub
HTTP(s) endpoint
Communicationstub
API requesterarchive
9 © 2017 IBM Corporation9 © 2017 IBM Corporation
API requester scenario
10 © 2017 IBM Corporation10 © 2017 IBM Corporation10 © 2017 IBM Corporation10 © 2017 IBM Corporation
PhoneBook API Requester with IMS
z/OS
IMS TM
IVTNO STUB
API provider
RESTfulendpoint
API requesterarchive
httpsjson
z/OS Connect EE
httpsbinary Cloudant
Implementation of the archived contact feature for the DELETE operation.The contact will be archived in IBM Cloudant.
Archiving the contact in NoSQL DBbefore deleting it from the IMS DB
11 © 2017 IBM Corporation11 © 2017 IBM Corporation11 © 2017 IBM Corporation11 © 2017 IBM Corporation
Step 0 – Install the BAQCSTUB in IMSBROWSE IMSCFG.IMSC.PROCLIB(DFSMPR) - 01.23 Line 0000000000 Col 001 080 ********************************* Top of Data **********************************// PROC SOUT='*',RGN=4M, // CL1=001,CL2=000,CL3=000,CL4=000, // OPT=N,OVLA=0,SPIE=0,VALCK=0,TLIM=00, // PCB=000,PRLD=,STIMER=,SOD=,DBLDL=, // NBA=5,OBA=6,IMSID=,AGN=TRAN01,VSFX=,VFREE=, // SSM=,PREINIT=LE,ALTID=,PWFI=Y, // APARM=,LOCKMAX=,APPLFE= //* //MPR EXEC PGM=DFSRRC00,REGION=&RGN, // TIME=1440,DPRTY=(12,0), // PARM=(MSG,&CL1&CL2&CL3&CL4, // &OPT&OVLA&SPIE&VALCK&TLIM&PCB, // &PRLD,&STIMER,&SOD,&DBLDL,&NBA, // &OBA,&IMSID,&AGN,&VSFX,&VFREE, // &SSM,&PREINIT,&ALTID,&PWFI, // '&APARM',&LOCKMAX,&APPLFE) //* //STEPLIB DD DSN=IMSCFG.&PLEX..PGMLIB,DISP=SHR // DD DSN=IMSCFG.&PLEX..PGMLIB.CBLSQL,DISP=SHR //* DD DSN=DEBUG.V14.IMSTMBAT.SCEERUN,DISP=SHR // DD DSN=IMSCFG.&IMSID..SDFSRESL,DISP=SHR // DD DSN=SHARED.GCADMIN.ZCEE.SBAQLIB,DISP=SHR // DD DISP=SHR,DSN=IMSETO.V3R1.SIZTLOAD //PROCLIB DD DSN=IMSCFG.&PLEX..PROCLIB,DISP=SHR //PRINTER DD SYSOUT=&SOUT,LRECL=4096 //*SYSUDUMP DD SYSOUT=&SOUT,LRECL=121,RECFM=VBA, //* SPACE=(125,(2500,100),RLSE,,ROUND) //SYSTSPRT DD SYSOUT=* //SYSTSIN DD DUMMY //SYSEXEC DD DSN=IMSCFG.&PLEX..EXEC,DISP=SHR //DFSESL DD DSN=IMSCFG.&IMSID..SDFSRESL,DISP=SHR // DD DISP=SHR,DSN=DB2.V11.SDSNLOAD // DD DSN=WMQ.V7R1M0.SCSQANLE,DISP=SHR // DD DSN=WMQ.V7R1M0.SCSQAUTH,DISP=SHR //CEEOPTS DD *
POSIX(ON), ENVAR("BAQURI=9.212.143.123", "BAQPORT=50780")
/*
PROCLIB of the IMS regionsMPR PROC
Add the BAQCSTUB load module to the STEPLIB concatenation
Add the CEEOPTS DD statement to point to the z/OS Connect EE server
12 © 2017 IBM Corporation12 © 2017 IBM Corporation12 © 2017 IBM Corporation12 © 2017 IBM Corporation12
Step 1: Generate API artifacts with Build Toolkit (1/2)
Swagger 2.0 description of the API Provider (IBM Cloudant)
13 © 2017 IBM Corporation13 © 2017 IBM Corporation13 © 2017 IBM Corporation13 © 2017 IBM Corporation
Step 1: Generate API artifacts with Build Toolkit (2/2)
Copybooks for JSON data
Copybook for API Info
ARA file
./zconbt -p=./archivedContacts.properties -f=./Archived-Contacts-API_V1.0.0.araBAQB0000I: z/OS Connect Enterprise Edition Build Toolkit Version 1.0 BAQB0008I: Creating API requester archive from configuration file./archivedContacts.properties…
Alan builds the artifacts for the API requester using the z/OS Connect EE Build Toolkit
The Build Toolkit creates artifacts from the swagger 2.0 definition of the API Provider
14 © 2017 IBM Corporation14 © 2017 IBM Corporation14 © 2017 IBM Corporation14 © 2017 IBM Corporation
Step 2 – Deploy the .ARA file on the z/OS Connect EE server
<apiRequester name="Archived-Contacts-API_1.0.0"connectionRef="archivedContactsAPI"requireAuth="false"requireSecure="false"runGlobalInterceptors="false"/>
<zosconnect_endpointConnectionid="archivedContactsAPI"connectionTimeout="10s"host="http://10.3.20.228"port="9088"receiveTimeout="20s"/>
Modifications in the server.xml:
IBM Cloudant’s host & port
15 © 2017 IBM Corporation15 © 2017 IBM Corporation15 © 2017 IBM Corporation15 © 2017 IBM Corporation
Step 3 – Update and compile the Cobol program
* PROCEDURE TO DELETE PHONEBOOK ENTRYDELETE-CONTACT-ENTRY.
MOVE IN-LAST-NAME TO LAST-NAME-SSA1.CALL "CBLTDLI"USING GHU, DBPCB, PHONEBOOK-SEG, PHONEBOOK-SSA1.
IF DBSTAT = SPACESTHENCALL "CBLTDLI"USING DLET, DBPCB, PHONEBOOK-SEG
IF DBSTAT = SPACESTHENMOVE DELETED TO OUT-MESSAGEPERFORM ARCHIVE-CONTACTTHRU ARCHIVE-CONTACT-END
MOVE IN-COMMAND TO OUT-COMMANDMOVE PHONEBOOK-SEG(1:37) TO OUT-RECORDMOVE '0001' TO OUT-SEGMENT-NO
ELSEMOVE DELETE-FAILED TO OUT-MESSAGEDISPLAY 'DELETE-CONTACT - BAD DLET STATUS CODE: 'DBSTAT
END-IFELSEMOVE DELETE-FAILED TO OUT-MESSAGEIF DBSTAT NOT = GE AND DBSTAT NOT = GBTHENDISPLAY 'DELETE-CONTACT - BAD GHU STATUS CODE: 'DBSTAT
END-IFEND-IF.
PERFORM INSERT-IO THRU INSERT-IO-END.DELETE-CONTACT-ENTRY-END.
* PROCEDURE TO ARCHIVE PHONEBOOK ENTRYARCHIVE-CONTACT.
*---------------------------------------------------------------** Set up the data for the API Requester call **---------------------------------------------------------------*
MOVE 1 TO lastName-num IN REQUEST.MOVE LENGTH OF LAST-NAME TO lastName2-length IN REQUEST.MOVE LAST-NAME TO lastName2 IN REQUEST.MOVE 1 TO firstName-num IN REQUEST.MOVE LENGTH OF FIRST-NAME TO firstName2-length IN REQUEST.MOVE FIRST-NAME TO firstName2 IN REQUEST.MOVE 1 TO telExtension-num IN REQUEST.MOVE LENGTH OF EXTENSION TO telExtension2-length IN REQUEST.MOVE EXTENSION TO telExtension2 IN REQUEST.MOVE 1 TO zipCode-num IN REQUEST.MOVE LENGTH OF ZIP-CODE TO zipCode2-length IN REQUEST.MOVE ZIP-CODE TO zipCode2 IN 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 REQUEST.MOVE LENGTH OF REQUEST TO BAQ-REQUEST-LEN.SET BAQ-RESPONSE-PTR TO ADDRESS OF RESPONSE.MOVE LENGTH OF RESPONSE TO BAQ-RESPONSE-LEN.
*---------------------------------------------------------------** Call the communication stub **---------------------------------------------------------------** Call the subsystem-supplied stub code to send* API request to zCEE
CALL COMM-STUB-PGM-NAME USINGBY REFERENCE API-INFO-OPER0BY REFERENCE BAQ-REQUEST-INFOBY REFERENCE BAQ-REQUEST-PTRBY REFERENCE BAQ-REQUEST-LENBY REFERENCE BAQ-RESPONSE-INFOBY REFERENCE BAQ-RESPONSE-PTRBY REFERENCE BAQ-RESPONSE-LEN.
* The BAQ-RETURN-CODE field in 'BAQRINFO' indicates whether this* API call is successful.
* When BAQ-RETURN-CODE is 'BAQ-SUCCESS', response is* successfully returned and fields in RESPONSE copybook* can be obtained. Display the translation result.
IF BAQ-SUCCESS THENMOVE DELETED-AR TO OUT-MESSAGE
* Otherwise, 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.
ELSEDISPLAY "Error code: " BAQ-STATUS-CODEDISPLAY "Error msg:" BAQ-STATUS-MESSAGE
END-IF.ARCHIVE-CONTACT-END.
16 © 2017 IBM Corporation16 © 2017 IBM Corporation16 © 2017 IBM Corporation16 © 2017 IBM Corporation
Test the solution
Delete one contact of the PhoneBook:
The deleted contact has been archived in the IBM Cloudantdatabase.
17 © 2017 IBM Corporation17 © 2017 IBM Corporation
Summary and more information
18 © 2017 IBM Corporation18 © 2017 IBM Corporation18 © 2017 IBM Corporation18 © 2017 IBM Corporation
§ Applications on CICS, IMS and batch programs can call RESTful APIs using z/OS Connect EE V3
z/OS Connect EE V3 Overview – API requester
IBM Client Center Montpellier
19 © 2017 IBM Corporation19 © 2017 IBM Corporation19 © 2017 IBM Corporation19 © 2017 IBM Corporation
z/OS Connect EE V3 components review
IBM Client Center Montpellier
20 © 2017 IBM Corporation20 © 2017 IBM Corporation20 © 2017 IBM Corporation20 © 2017 IBM Corporation
z/OS Connect EE V3 Resources
Downloads
Explore the docs
Where to get help
z/OS Connect EE open beta runtime
z/OS Connect EE workstation tooling
z/OS Connect EE Knowledge Center
z/OS Connect EE Developer Center
dW Answers
z/OS Connect EE open beta forum
ibm.biz/zosconnect-open-beta
ibm.biz/zosconnect-tooling-download
ibm.biz/zosconnect-kc
ibm.biz/zosconnectdc
ibm.biz/zosconnect-dw-answers
ibm.biz/zcee-beta-forum
z/OS Connect EE Articles and blogs https://developer.ibm.com/mainframe/docs/
IBM Client Center Montpellier
Please submit your session feedback!
• Do it online at http://conferences.gse.org.uk/2019/feedback/HD
• This session is HD