demo of consuming a rest api from an ims program using z ... · demo of consuming a rest api from...

Demo of consuminga REST API from an IMS programusing z/OS Connect EEAymeric Affouard [email protected]

IBM

November 2019

Session HD – Wellington B

mailto:[email protected]

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


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



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


v

v


§ 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



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


API provider

RESTfulendpoint


Implementation steps


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


API requester scenario


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


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)


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


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


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.


Test the solution

Delete one contact of the PhoneBook:

The deleted contact has been archived in the IBM Cloudantdatabase.


Summary and more information


§ 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



z/OS Connect EE V3 components review



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/


http://ibm.biz/zosconnect-open-beta

http://ibm.biz/zosconnect-tooling-download

http://ibm.biz/zosconnect-kc

http://ibm.biz/zosconnect-kc

http://ibm.biz/zosconnect-dw-answers

http://ibm.biz/zcee-beta-forum

https://developer.ibm.com/mainframe/docs/

Please submit your session feedback!

• Do it online at http://conferences.gse.org.uk/2019/feedback/HD

• This session is HD

http://conferences.gse.org.uk/2019/feedback/nn

demo of consuming a rest api from an ims program using z ... · demo of consuming a rest api from...

Documents