IMS Callout to Services GSE BENELUX IMS User Group Meeting The (R)Evolution Continues June 2013 - Antwerp Belgium Steve Nathan - snathan@us.ibm.com ©2013 IBM Corporation GSE BENELUX IMS User Group Meeting – June 2013 Disclaimer © Copyright IBM Corporation 2013. All rights reserved. U.S. Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. THE INFORMATION CONTAINED IN THIS PRESENTATION IS PROVIDED FOR INFORMATIONAL PURPOSES ONLY. WHILE EFFORTS WERE MADE TO VERIFY THE COMPLETENESS AND ACCURACY OF THE INFORMATION CONTAINED IN THIS PRESENTATION, IT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. IN ADDITION, THIS INFORMATION IS BASED ON IBM’S CURRENT PRODUCT PLANS AND STRATEGY, WHICH ARE SUBJECT TO CHANGE BY IBM WITHOUT NOTICE. IBM SHALL NOT BE RESPONSIBLE FOR ANY DAMAGES ARISING OUT OF THE USE OF, OR OTHERWISE RELATED TO, THIS PRESENTATION OR ANY OTHER DOCUMENTATION. NOTHING CONTAINED IN THIS PRESENTATION IS INTENDED TO, NOR SHALL HAVE THE EFFECT OF, CREATING ANY WARRANTIES OR REPRESENTATIONS FROM IBM (OR ITS SUPPLIERS OR LICENSORS), OR ALTERING THE TERMS AND CONDITIONS OF ANY AGREEMENT OR LICENSE GOVERNING THE USE OF IBM PRODUCTS AND/OR SOFTWARE. IBM, the IBM logo, ibm.com, and IMS are trademarks or registered trademarks of International Business Machines Corporation in the United States, other countries, or both. If these and other IBM trademarked terms are marked on their first occurrence in this information with a trademark symbol (® or ™), these symbols indicate U.S. registered or common law trademarks owned by IBM at the time this information was published. Such trademarks may also be registered or common law trademarks in other countries. A current list of IBM trademarks is available on the Web at “Copyright and trademark information” at www.ibm.com/legal/copytrade.shtml IMS Callout to Services 2 GSE BENELUX IMS User Group Meeting – June 2013 Acknowledgement This presentation was originally prepared by Ken Blackman – IBM Advanced Technical Solutions (ATS) – kblackm@us.ibm.com IMS Callout to Services 3 GSE BENELUX IMS User Group Meeting – June 2013 Agenda Introduction Asynchronous Callout – – – – – IMS ALTPCB WebSphere MQ Using ESAF APPC/IMS WebSphere Optimized Local Adapters for WAS z/OS Using ESAF WebSphere Optimized Local Adapters for WAS z/OS Using OTMA Synchronous Callout – – – – – – IMS ICAL DB2 Stored Procedures DB2 Attach Facility WebSphere MQ Using ESAF CPI-C/APPC RYO Using TCP/IP IMS Callout to Services 4 GSE BENELUX IMS User Group Meeting – June 2013 Introduction – Web Service Definition – Standards based type of service – Software component (callable piece of code) that is capable of being access (described, published, and located) via standard network protocols such as SOAP over HTTP • Independent of platforms or programming language IMS Callout to Services UDDI Registry Service Broker publish find WSDL WSDL IMS bind, invoke Service Provider Service Requester Web Service SOAP Client Application The entire industry is agreeing on one set of standards !! 3 basic components: - Service Provider - Service Broker - Service Requestor 5 GSE BENELUX IMS User Group Meeting – June 2013 Introduction – Callout Techniques IMS applications can code communication API calls – DL/I ISRT ALTPCB – DL/I ICAL – SQL calls to DB2 stored procedures – WebSphere MQ calls – CPI-C/APPC calls – TCP/IP sockets calls IMS Callout to Services 6 GSE BENELUX IMS User Group Meeting – June 2013 Introduction – Asynchronous Model CLIENT MSG-Q IMS Application MSG-Q GU IOPCB SEND_DATA Message+Token Message+Token UOW1 CLIENT IMS/non-IMS READ_DATA READ_DATA Message+appl-token Message+Token PROCESS_DATA PROCESS_DATA IMS Application MSG-Q GU IOPCB MSG-Q Reply+Token Reply+Token ISRT ALTPCB to CLIENT UOW2 IMS Callout to Services SEND_DATA SEND_DATA Reply+Token Message+appl-token TWO IMS Units of Work (UOW) 7 GSE BENELUX IMS User Group Meeting – June 2013 Introduction – Synchronous Model CLIENT CLIENT MSG-Q IMS Application IMS/non-IMS GU IOPCB Message SEND_DATA Message READ_with_WAIT MSG-Q RECEIVE REPLY READ_DATA Message PROCESS_DATA Reply SEND_DATA Reply ISRT IOPCB to CLIENT UOW1 IMS Callout to Services ONE IMS Unit of Work (UOW) 8 GSE BENELUX IMS User Group Meeting – June 2013 Introduction – Service Flow Concept CLIENT Program A Program n IMS Callout to Services 9 GSE BENELUX IMS User Group Meeting – June 2013 Introduction – Stored Procedure Concept CLIENT Stored Procedure Get Data 1 Get Data 2 IMS Callout to Services 10 GSE BENELUX IMS User Group Meeting – June 2013 Introduction – Callout Destinations IMS TM Resource Adapter via IMS Connect Windows / AIX / Solaris / Linux andWebSphere z/OS z/OS1 XCF IMS IMS Connect Application Server IMS Resource Adapter IMS Connect IMS z/OS2 WebSphere Application Server IMS Resource Adapter IMS Connect IMS Linux for System z WebSphere Application Server IMS Resource Adapter IMS Callout to Services TCP/IP XCF Local 11 GSE BENELUX IMS User Group Meeting – June 2013 Introduction – Callout Destinations IMS SOAP Gateway via IMS Connect Web Service Clients, e.g. Microsoft .Net, SAP, Java, etc.. SOAP IMS z/os IMS SOAP Gateway IMS Connect XML OTMA XML Adapter XML Web Service Clients, e.g. Microsoft .Net, SAP, Java, etc.. IMS Callout to Services OTMA Windows, AIX,zLinux IMS App DB SOAP IMS SOAP Gateway 12 GSE BENELUX IMS User Group Meeting – June 2013 Introduction – Callout Destinations IMS SOAP Gateway via IMS Connect (Call In) SOAP <?xml version="1.0"?> <soap:Envelope> <soap:Body> <INPUTMSG> <in_ll>32</in_ll><in_zz>0</in_zz> <in_trcd>IVTNO</in_trcd> <in_cmd>DISPLAY</in_cmd> <in_name1>LAST1</in_name1> </INPUTMSG> </soap:Body> </soap:Envelope> Microsoft .NET Client XML <INPUTMSG> <in_ll>32</in_ll><in_zz>0</in_zz> <in_trcd>IVTNO</in_trcd> <in_cmd>DISPLAY</in_cmd> <in_name1>LAST1</in_name1> </INPUTMSG> IMS 32 0IVTNO IMS App TCP/IP IMS Web Service <cbl:OUTPUTMSG> <out_ll>93</out_ll><out_zz>0</out_zz> <out_msg>ENTRY WAS DISPLAYED</out_msg> <out_cmd>DISPLAY</out_cmd> <out_name1>LAST1</out_name1> <out_name2>FIRST1</out_name2> <out_extn>8-111-1111</out_extn> <out_zip>D01/R01</out_zip> <out_segno>0001</out_segno> </cbl:OUTPUTMSG> IMS Callout to Services DISPLAY LAST1 Adapter Task Manager IMS SOAP Gateway HTTP/SOAP <?xml version="1.0"?> <soap:Envelope> <soap:Body> <cbl:OUTPUTMSG> <out_ll>93</out_ll><out_zz>0</out_zz> <out_msg>ENTRY WAS DISPLAYED</out_msg> <out_cmd>DISPLAY</out_cmd> <out_name1>LAST1</out_name1> <out_name2>FIRST1</out_name2> <out_extn>8-111-1111</out_extn> <out_zip>D01/R01</out_zip> <out_segno>0001</out_segno> </cbl:OUTPUTMSG> </soap:Body> </soap:Envelope> Connect Byte array XML Adapter XML Converters 93 0 ENTRY WAS DISPLAYED DISPLAY LAST1 FIRST1 8-111-11111 D01/R01 0001 13 GSE BENELUX IMS User Group Meeting – June 2013 Asynchronous Callout – IMS ALTPCB IMS DL/I API call – CHNG, ISRT, PURG to ALTPCB Provides for program-to-program communication – Workflow model Destination can be – Another IMS transaction – An OTMA Client • IMS Connect – RYO including IMS Connect API – IMS TM Resource Adapter in a JEE environment – IMS SOAP Gateway • WebSphere MQ • OTMA C/I – APPC/IMS Applications manage the response correlation There is no coordinated commit IMS Callout to Services 14 GSE BENELUX IMS User Group Meeting – June 2013 Asynchronous Callout – IMS ALTPCB to IMS Application CLIENT IMS Application 1 MSG-Q GU IOPCB ISRT ALTPCB to IMS Application 2 MSG-Q Message+Token IMS Application Service IMS Application 2 GU IOPCB Message+Token Message+Token UOW1 ISRT ALTPCB to IMS Application 3 IMS Application 3 MSG-Q GU IOPCB MSG-Q Reply+Token Reply+Token Reply+Token ISRT ALTPCB to CLIENT UOW3 IMS Callout to Services UOW2 THREE IMS Units of Work (UOW) 15 GSE BENELUX IMS User Group Meeting – June 2013 Asynchronous Callout – IMS ALTPCB to OTMA Destination and attributes can be determined by OTMA Exit – DFSYPRX0 – OTMA Destination Resolution Exit – DRU – OTMA User Data Formatting Exit Destination and attributes can be determined by OTMA Descriptors in DFSYDTx for IMS Connect DFSYDTx member of IMS.PROCLIB – – – – – – TYPE: Destination type (IMSCON) TMEMBER: OTMA Target Client TPIPE: Destination Name SMEM: Supermember name ADAPTER: Type of IMS Connect Adapter CONVERTR: Routine called by Adapter IMS Callout to Services 16 GSE BENELUX IMS User Group Meeting – June 2013 Asynchronous Callout – IMS ALTPCB to IMS Connect RYO Application CLIENT IMS Application 1 MSG-Q IMS Connect GU IOPCB MSG-Q ISRT ALTPCB to IMS Connect IMS Connect Client Connect Write Resume TPIPE Message+Token Read UOW1 Message+Token IMS Application 2 MSG-Q GU IOPCB Reply+Token ISRT ALTPCB to CLIENT UOW3 IMS Callout to Services Write MSG-Q ACK Send-Only Reply+Token UOW2 TWO IMS Units of Work (UOW) + ICON Client UOW 17 GSE BENELUX IMS User Group Meeting – June 2013 Asynchronous Callout – IMS ALTPCB to IMS TM Resource Adapter Initiating Client IMS WebSphere Application Server 0. Start IMS App1 IMS App1 1. ReceiveAsync(TP1) Web Service “Single wait ” 6. MSG1 5.sendACK OR 7. send New Msg IMS Connect EJB RESUME TPIPE 1.ResumeTPIPE(TP1) Single Wait Alt ClientID= TP1 4.receive MSG1 2. ISRT ALTPCB (IC4JEJB) 3.Send MSG1 TP1 MSG1 MSG2 IMS App2 MDB IMS TM Resource Adapter WIN, AIX, SOLARIS, LINUX, etc. Commit then Send (CM0) Sync-Level=CONFIRM Execution timeout IMS Callout to Services DFSYDTx (new definition) IC4JEJB TYPE = IMSCON TMEMBER=SM01 TPIPE=TP1 SMEM=Y 18 GSE BENELUX IMS User Group Meeting – June 2013 Asynchronous Callout – IMS ALTPCB to IMS SOAP Gateway DFSYDTx Win, AIX, , Linux, z/OS. IMS SOAP Gateway Server IMS Connect 1 RESUME TPIPE TP3 “Single wait ” 4 RECEIVE InXMLMsg1 5 Web Service IMSSOAP1 TYPE = IMSCON TMEMBER=SM01 TPIPE=TP3 SMEM=Y ADAPTER = HWSXMLA0 CONVERTR=SOAPIT Msg1 Msg2 5.sendACK 6 SEND OutXMLMsg 7 SOAPIT XML Converter IMS 2 IMS App1 TP3 XML Adapter Initiating Client 3 : ISRT ALTPCB IMSSOAP1 SYNCPT Starts.. IMS App2 Connection Bundle(CBA) TPIPE = TP1,TP3 IMS Callout to Services 19 GSE BENELUX IMS User Group Meeting – June 2013 Rational Developer for System z (RDz) Language Structures (e.g. COBOL Copybooks) From IMS Callout app Meet-in-Middle Compiled Generation Wizard Rational Developer for System z (RDz) 7.1.1 Compiled Converters WSDL From web service Mapping Metadata IMS Callout Correlator IMS Callout to Services IMS Callout Compiled Converters generated from manually specified mappings between the request and response XML Schemas and existing or newly hand-coded language structures. In addition, a WSID and Web Service operation name will be added by the converter to the request message. The WSID is used to map to a particular IMS Callout correlator at runtime. IMS Callout runtime deployment metadata for mapping a particular web service as well as properties for invoking the web service. 20 GSE BENELUX IMS User Group Meeting – June 2013 Asynchronous Callout – IMS ALTPCP to WebSphere MQ IMS Bridge IMS Application 1 CLIENT MSG-Q GU IOPCB MSG-Q ISRT ALTPCB to MQ IMS Bridge IMS Bridge XCF Read (YPRX0 + MQDRU) (Descriptor – IMS13) Message+Token MQ Appl MQCONN WebSphere MQ Queue Manager MQPUT MQ MSG-Q MQOPEN MQGET Message+Token UOW1 MQPUT1 IMS Application 2 MSG-Q GU IOPCB Reply+Token MSG-Q MQGET XCF Write Reply+Token MQCOMMIT MQDISC ISRT ALTPCB to CLIENT UOW5 IMS Callout to Services UOW2 & UOW4 UOW3 TWO IMS Units of Work (UOW) + 2MQ QM UOWs + MQ Application UOW 21 GSE BENELUX IMS User Group Meeting – June 2013 Asynchronous Callout – IMS ALTPCB to OTMA C/I Application CLIENT IMS Application 1 MSG-Q GU IOPCB ISRT ALTPCB to IMS Application 2 MSG-Q Message+Token OTMA C/I Application otma_create otma_open Message+Token UOW1 otma_receive_async Message+Token IMS Application 3 MSG-Q GU IOPCB MSG-Q otma_send_async Reply+Token Reply+Token Reply+Token ISRT ALTPCB to CLIENT UOW3 IMS Callout to Services otma_close UOW2 TWO IMS Units of Work (UOW) + OTMA C/I Application UOW 22 GSE BENELUX IMS User Group Meeting – June 2013 Asynchronous Callout – WebSphere MQ Using ESAF EASF = External Subsystem Interface Provides for program-to-program communication – Workflow model IMS application issues MQ API IMS provides syncpoint coordination within a transaction Applications manage the response correlation There is no coordinated commit IMS Callout to Services 23 GSE BENELUX IMS User Group Meeting – June 2013 Asynchronous Callout – WebSphere MQ Using ESAF CLIENT IMS MPP1/BMP1 MSG-Q Message+Token GU IOPCB MQCONN MQPUT1 MQDISC MQ MSG-Q Message+Token MQPUT1 Reply+Token IMS BMP2 MQCONN MQOPEN MQGET w/WAIT ISRT ALTPCB IMS SYNC UOW3 IMS Callout to Services MQOPEN MQGET UOW1 MSG-Q MQ Appl MQCONN MQCOMMIT Reply+Token MQDISC UOW2 TWO IMS Units of Work (UOW) + MQ Application UOW 24 GSE BENELUX IMS User Group Meeting – June 2013 Asynchronous Callout – APPC/IMS IMS DL/I API call – CHNG, ISRT, PURG to ALTPCB Provides for program-to-program communication – Workflow model IMS provides syncpoint coordination within a transaction Applications manage the response correlation There is no coordinated commit DFS62DTx member of IMS.PROCLIB – – – – – – – LUNAME: Destination TPNAME: Application Program MODE: VTAM Mode Table SYNCLEVEL: Conversation State Change Protocol OUTBND: Local LU SIDE: Side Information Entry CONVTYPE: Basic or Mapped IMS Callout to Services 25 GSE BENELUX IMS User Group Meeting – June 2013 Asynchronous Callout – APPC/IMS CLIENT IMS Application 1 MSG-Q GU IOPCB APPC/IMS MSG-Q CMALLOC ISRT ALTPCB (LU 6.2 Descriptor) Message+Token UOW1 IMS Application 2 MSG-Q GU IOPCB Reply+Token IMS/non-IMS Alloc TP-B Type=NONE/ CONFIRM CMSEND CMDEALL MSG-Q CMRCV Send data to IMS LU 6.2 TP-B Session Conv A CMRCV Process Data CMDEAL Session CMALLOC Conv B CMSEND CMDEAL CMDEAL ISRT ALTPCB to CLIENT UOW5 IMS Callout to Services UOW2 & UOW4 UOW3 TWO IMS Units of Work (UOW) + 2 APPC/MVS UOWs + APPC Appl UOW 26 GSE BENELUX IMS User Group Meeting – June 2013 Asynchronous Callout – WOLA Using ESAF WOLA = WebSphere Optimized Local Adapters for WAS z/OS – Direct IIOP communication between IMS and WAS on same z/OS – Requires WAS 7.0.0.12 Invokes EJB in WAS IMS application issues WOLA API IMS provides syncpoint coordination within a transaction Applications manage the response correlation There is no coordinated commit IMS Callout to Services 27 GSE BENELUX IMS User Group Meeting – June 2013 Asynchronous Callout – WOLA Using ESAF CLIENT IMS MSG-Q MPP1/BMP1/IFP1 Message+Token GU IOPCB WAS EJB WOLA WOLA API API’s UOW1 IMS BMP2 MSG-Q WOLA APIs ISRT ALTPCB IMS SYNC Reply+Token UOW2 UOW3 IMS Callout to Services TWO IMS Units of Work (UOW) + EJB Application UOW 28 GSE BENELUX IMS User Group Meeting – June 2013 Asynchronous Callout – WOLA Using ALTPCB and OTMA WOLA = WebSphere Optimized Local Adapters for WAS z/OS – Has an OTMA Client – Requires WAS 7.0.0.12 – WAS 8.0.0.0 and PM57240 support messages > 32K Invokes EJB in WAS IMS application issues CHNG/ISRT/PURG IMS provides syncpoint coordination within a transaction Applications manage the response correlation There IS coordinated commit – WAS 8.0.0.4 and PM71314 support Synclevel Syncpoint (2PC) using RRS IMS Callout to Services 29 GSE BENELUX IMS User Group Meeting – June 2013 Asynchronous Callout – IMS ALTPCB to WOLA CLIENT IMS Application 1 MSG-Q GU IOPCB ISRT ALTPCB to WOLA MSG-Q Message+Token WAS EJB WOLA APIs Message+Token UOW1 IMS Application 3 MSG-Q GU IOPCB MSG-Q Reply+Token Reply+Token ISRT ALTPCB to CLIENT UOW3 IMS Callout to Services UOW2 TWO IMS Units of Work (UOW) + EJB Application UOW OR 2PC 30 GSE BENELUX IMS User Group Meeting – June 2013 Synchronous Callout ICAL – – – – IMS TM Resource Adapter SOAP Gateway RYO IMS Transaction (IMS 13) DB2 Stored Procedures DB2 Attach WebSphere MQ Using ESAF WebSphere MQ Using CSQBSTUB WebSphere MQ Using CSQBRSTB + RRS CPI-C/APPC RYO Using TCP/IP IMS Callout to Services 31 GSE BENELUX IMS User Group Meeting – June 2013 Synchronous Callout – IMS ICAL Synchronous Callout – IMS supports synchronous callout from an IMS application using OTMA – Invoked with a new IMS call – ICAL – Application will issue the call and wait for a reply – First support is for IMS Connect – Also supported for IMS Java programs IMS Callout to Services 32 GSE BENELUX IMS User Group Meeting – June 2013 Synchronous Callout – IMS ICAL Synchronous Callout – The OTMA Client will do a Resume TPIPE specifying that it wants synchronous callout messages – OTMA sends the synchronous callout request to the OTMA Client when it is available – The OTMA Client must send an ACK (or NAK) for the request message – The OTMA Client will send the reply via a special Send-Only message – The OTMA Client is responsible for maintaining a Correlator Token IMS Callout to Services 33 GSE BENELUX IMS User Group Meeting – June 2013 Synchronous Callout – IMS ICAL Synchronous Callout – IMS Connect supports OTMA synchronous callout • • • • • Supported by IMS TM Resource Adapter Supported by IMS SOAP Gateway Supported by IMS Connect API for Java and C/C++ Supported for RYO IMS Connect Clients Supported by IMS Connect Extensions – The IMS Connect Client will do a Resume TPIPE specifying that it wants synchronous callout messages – The IMS Connect Client will send the reply via a Send-Only message IMS Callout to Services 34 GSE BENELUX IMS User Group Meeting – June 2013 Synchronous Callout – IMS ICAL Synchronous Callout – The IMS Connect Client maintains the Correlator Token • IMS TM Resource Adapter • IMS SOAP Gateway • IMS Connect API for Java and C/C++ • RYO IMS Connect Clients IMS Callout to Services 35 GSE BENELUX IMS User Group Meeting – June 2013 Synchronous Callout – IMS ICAL Synchronous Callout – The synchronous callout design is provided for IMS TM users • It does not provide support for BMP or JBP applications running in a DBCTL environment – OTMA Descriptors are required to define the target destination • Supermember is supported for availability and failover – Only the AIBTDLI call interface is supported • Supports messages larger than 32K without segmentation IMS Callout to Services 36 GSE BENELUX IMS User Group Meeting – June 2013 Synchronous Callout – IMS ICAL Synchronous Callout – The following will not be supported in the first phase of the synchronous callout support • Shared Queues with FE and BE are different systems • Two phase commit (distributed sync point) • IMS application will not be able to specify a password for authenticating the external server on a per request basis IMS Callout to Services 37 GSE BENELUX IMS User Group Meeting – June 2013 Synchronous Callout – IMS ICAL IMS WebSphere Application Server EJB / MDB IMS TM Resource Adapter IMS Application 1 OTMA Descriptor 1 IMS Connect Roll-your-own Application Web Service Provider IMS Connect OTMA Descriptor 2 OTMA Descriptor 3 IMS SOAP Gateway IMS Application 2 IMS Application 3 Send flow Receive flow IMS Callout to Services 38 GSE BENELUX IMS User Group Meeting – June 2013 Synchronous Callout – IMS ICAL Synchronous Callout – The first thing to do is define and setup OTMA Descriptors for each synchronous callout destination – Use different TPIPEs for asynchronous output messages and synchronous callout messages – Use different TPIPEs for synchronous callout request messages for each client • IMS TM Resource Adapter clients • IMS SOAP Gateway clients • RYO application clients • IMS Connect API clients IMS Callout to Services 39 GSE BENELUX IMS User Group Meeting – June 2013 Synchronous Callout – IMS ICAL Synchronous Callout – Use ‘D’ descriptor type in DFSYDTx – D destname keywords • destname is the destination name in the AIB – Keywords are • TYPE=IMSCON (only supported by ICON at this time) • TMEMBER=name • TPIPE=name • SMEM=YES|NO • ADAPTER=adapname • CONVERTR=convname • SYNTIMER=timeout IMS Callout to Services 40 GSE BENELUX IMS User Group Meeting – June 2013 Synchronous Callout – IMS ICAL Synchronous Callout – The IMS application uses the AIBTDLI call for the synchronous request – CALL 'AIBTDLI' USING ICAL, AIB, REQ-AREA, RESP-AREA. • ICAL is new call • AIB is an AIB control block • REQ-AREA is the Request data area for synchronous callout • RESP-AREA is the Response data area for returned data IMS Callout to Services 41 GSE BENELUX IMS User Group Meeting – June 2013 Synchronous Callout – IMS ICAL Synchronous Callout AIB – AIBSFUNC = SENDRECV – AIBRSNM1 = 8 byte OTMA Descriptor name – AIBRSFLD = Timeout value – AIBOALEN = Request area length • Input parameter: 4 byte field containing the length of the request area • Output parameter: Actual length of the response message • Updated by IMS only when partial data is returned ‒ AIB return code x'100', AIB reason code x'00C‘ – AIBOAUSE = Response area length • Input parameter: 4 byte field contains the length of the response area • Output parameter: Length of the response message placed in the response area • When partial data is returned because the response area is not large enough, AIBOAUSE contains the length of data returned in the response area and AIBOALEN contains the actual length of the response message IMS Callout to Services 42 GSE BENELUX IMS User Group Meeting – June 2013 Synchronous Callout – IMS ICAL Prior to IMS 13 if a response to a synchronous callout request was larger than the Response Area it was truncated – The application had to allocated a larger Response Area and re-issue the ICAL In IMS 13 a copy of the entire message is kept in the IMS Control Region – New ICAL AIBSFUNC “RECEIVE” can be used to retrieve the entire message without reissuing the ICAL SENDRECV call IMS Callout to Services 43 GSE BENELUX IMS User Group Meeting – June 2013 Synchronous Callout – IMS ICAL Synchronous Callout Timeout – If both the AIB and the Descriptor have a timeout value the lower of the two values will be used – If only one has a timeout value that one will be used – If neither has a timeout value the default value of 10 seconds will be used – The valid range is between 0 and 999999 in hundredths of a second • The maximum is about 2.7 hours IMS Callout to Services 44 GSE BENELUX IMS User Group Meeting – June 2013 Synchronous Callout – IMS ICAL IAPMDI27 JOHN DOE RYO Application IMS Connect Resume TPIPE TPIPE1 . IMS IMS Application TPIPE TPIPE1 1 ICAL SENDRECV OTMDEST1 JOHN DOE Request 4 3 7 8 2 JOHN DOE 5 ACK Response 6 12345678 9 12345678 10 IMS Callout to Services 45 GSE BENELUX IMS User Group Meeting – June 2013 Synchronous Callout – IMS ICAL Synchronous Callout 1. IMS Connect Client issues Resume TPIPE 2. The IMS application issues the synchronous request using the ICAL call 3. OTMA breaks the message into 32K segments 4. IMS Connect combines the data and sends it to the IMS Connect Client including the Correlation Token 5. The IMS Connect Client must ACK or NAK the synchronous output message IMS Callout to Services 46 GSE BENELUX IMS User Group Meeting – June 2013 Synchronous Callout – IMS ICAL Synchronous Callout 6. The IMS Connect Client sends the synchronous response message as a “send-only” message (Send-Only with ACK is supported) 7. IMS Connect breaks the message into 32K pieces to send to OTMA via XCF 8. OTMA combines all of the data and returns it to the IMS application in the Response Area 9. The IMS application processes the synchronous response 10. IMS optionally ACKs the response message (IMS 12+) IMS Callout to Services 47 GSE BENELUX IMS User Group Meeting – June 2013 Synchronous Callout – IMS ICAL Holding IMS locks during ICAL – While the ICAL is in progress IMS is still holding all of the database locks that were obtained before the call – Good programming practice would to be do as few database updates as possible before the ICAL • Zero is the ideal number ‒ For positional database locks held for reads consider the use of the DL/I RLSE call which is described in the notes below IMS Callout to Services 48 GSE BENELUX IMS User Group Meeting – June 2013 Synchronous Callout – IMS ICAL /DISPLAY ACTIVE REGION – New status for region waiting on synchronous callout response •WAIT-CALLOUT – Continuation line for region waiting on synchronous callout response •TMEMBER name TPIPE: tpipename REGID JOBNAME 1 MPP1A TYPE TP JMPRGN JBPRGN BATCHREG FPRGN DBTRGN DBRZCSAJ DLIZCSAJ *08213/165100* JMP JBP BMP FP DBT DBRC DLS TRAN/STEP PROGRAM STATUS CLASS 1 APOL11 APOL1 WAIT-CALLOUT TMEMBER HWS TPIPE: TPIPE1 NONE NONE NONE NONE NONE IMS Callout to Services 49 GSE BENELUX IMS User Group Meeting – June 2013 Synchronous Callout – IMS ICAL /DIS TMEMBER TPIPE ALL SYNC new fields – OPT ( for both asynchronous and synchronous calls) • • • • • N – Noauto O – One A – Auto W – Auto one ‘-’ -- no RT – MODE ( for both asynchronous and synchronous calls) • • • • S – Sync messages B – Both Async and Sync messages A – Async messages ‘-’ – no RT – SYNCOT ( only for synchronous calls) • No. of active ICAL syncallout messages – NO_COT (only for synchronous calls) • Number of messages waiting for response and/or WT-S status IMS Callout to Services 50 GSE BENELUX IMS User Group Meeting – June 2013 Synchronous Callout – IMS ICAL Effect of commands for IMS synchronous callout – /PSTOP • Clear the wait in the region • Dequeues synchronous callout messages from the TPIPE – /STOP TMEMBER TPIPE • Clear state of all messages for the TPIPE – /STOP OTMA • Clear all the ICAL messages for all the TPIPEs. • New ICAL synchronous callout requests rejected – These commands return to ICAL • AIBRETRN = 100 • AIBREASN = 10C IMS Callout to Services 51 GSE BENELUX IMS User Group Meeting – June 2013 Synchronous Callout – IMS ICAL – IMS TM Resource Adapter The IMS TM Resource Adapter running in a JEE environment supports synchronous callout via ICAL – WebSphere Enterprise Java Bean (EJB) • EJB would be coded to use IMS TM Resource Adapter’s Resume TPIPE and Send-Only function • Correlation Token would be sent back with the response message – WebSphere Message Driven Bean (MDB) • MDB would be deployed to listen to callout requests using IMS TM Resource Adapter JCA 1.5 Inbound support • IMS TM Resource Adapter internally ‒ Implements Resume TPIPE and Send-Only protocols and manages Correlation Token on behalf of the MDB ‒ Implements JCA 1.5 Work management contract to provide concurrent processing • Working with Rational Application Developer and WebSphere Integration Developer tooling to generate MDB and SCA exports IMS Callout to Services 52 GSE BENELUX IMS User Group Meeting – June 2013 Synchronous Callout – IMS ICAL – IMS TM Resource Adapter - EJB z/OS WebSphere Application Server IMS TM RA EJB SYNC_RECEIVE_A SYNCOUTPUT TPS Resume TPIPE TPS CORTKN Data SYNC_SEND CORTKN Data Data Send_ONLY CORTKN TPS Connect HWS1 ACK TM/CTL Services IMS OTMA CORTKN IMS Application Program DEST1 TPS HWS1 ICAL DEST1 Request Response Data IMS Callout to Services 53 GSE BENELUX IMS User Group Meeting – June 2013 Synchronous Callout – IMS ICAL – IMS TM Resource Adapter - MDB z/OS WebSphere Application Server IMS IMS TM RA MDB ACTIVATE Resume TPIPE TPS CORTKN Data HWS1 ACK Data Data Connect Send_ONLY CORTKN TPS OTMA EJB Service TM/CTL Services IMS Application Program DEST1 TPS HWS1 ICAL DEST1 Request Response Data IMS Callout to Services 54 GSE BENELUX IMS User Group Meeting – June 2013 Synchronous Callout – IMS ICAL – IMS SOAP Gateway The IMS SOAP Gateway supports synchronous callout via ICAL – IMS SOAP Gateway provides built-in function to listen to callout request and invoke Web service providers • Implements Resume TPIPE and Send-Only protocols and manages Correlation Token • Correlates callout requests to Web service providers – Support for concurrent processing provided by built-in threading mechanism – Rational Developer for System z generates callout artifacts and XML converters for IMS SOAP Gateway and IMS Connect IMS Callout to Services 55 GSE BENELUX IMS User Group Meeting – June 2013 Synchronous Callout – IMS ICAL – IMS SOAP Gateway z/OS IMS Web Service IMS SOAP Gateway Resume TPIPE TPS XML Connect ACK HWS1 Send_ONLY XML IMS HWSXMLA0 TPS OTMA XML CORTKN TM/CTL Services DEST1 TPS HWS1 HWSXMLA0 XMLCNV1D Application Program ICAL DEST1 Request data Response CORTKN XML XML Converter XMLCNV1D data Connection Bundle TPS IMS Callout to Services 56 GSE BENELUX IMS User Group Meeting – June 2013 Synchronous Callout – IMS ICAL – IMS SOAP Gateway Error Scenarios Initiating Client z/OS IMS SOAP Gateway IMS Connect IMS HWS1 Resume TPIPE Web Service Provider 0 TPIPE Request X1 X3 HELLO FROM IMS HELLO FROM IMS 2 3 1 ICAL SENDRECV OTMDEST1 HELLO FROM IMS X2 ACK XML Converter Response HELLO FROM WEB SERVICE IMS Application RESUME 4 X4 HELLO FROM WEB SERVICE X6 X5 HELLO FROM WEB SERVICE XML Adapter Correlator X1: ICAL cannot be sent out X2: ICAL time out X3: late ACK received after time out X4: XML converter in error IMS Callout to Services X5: external server already commit before time out X6: external server already commit, but IMS fails to process the response 57 GSE BENELUX IMS User Group Meeting – June 2013 Synchronous Callout – IMS ICAL – RYO IMS Synchronous Callout ICAL destinations can be user written IMS Connect TCP/IP Clients – WRITE Resume TPIPE specifying Synchronous Callout messages are requested – READ to get the Correlation Token + the request message – WRITE ACK for the request message – WRITE to send Correlation Token + reply message • This is a Send-Only message marked as a synchronous reply • Send-Only with ACK is also supported – READ to get ACK (optional) – The IMS Connect API for Java and C/C++ can also be used for RYO IMS Connect synchronous callout clients IMS Callout to Services 58 GSE BENELUX IMS User Group Meeting – June 2013 Synchronous Callout – IMS ICAL – RYO z/OS IMS TCP/IP RYO Resume TPIPE TPS IMS TPS Connect ACK Send_ONLY CToken HWS1 Data IMS Callout to Services OTMA CToken Data TM/CTL Services Application Program DEST1 TPS HWS1 ICAL DEST1 Request Response 59 GSE BENELUX IMS User Group Meeting – June 2013 Synchronous Callout – IMS ICAL – IMS 13 DL/I ICAL support from previous IMS releases – Provided synchronous callout to resources outside IMS z/OS IMS WebSphere MPP/JMP/IFP/BMP/JBP IMS TM resource adapter OTMA TM/CTL Services IMS IMS SOAP GATEWAY Application Program ICAL DB Services Connect TCP/IP user-written Client IMS Callout to Services OTMA Descriptor OTMA Descriptor Database 60 GSE BENELUX IMS User Group Meeting – June 2013 Synchronous Callout – IMS ICAL – IMS 13 Synchronous Program Switch IMS 13 allows an IMS application program to synchronously call and wait for a reply from another IMS application program – Within the calling program’s Unit of Work WebSphere IMS TM services IMS TM resource adapter Application Program IMS IMS SOAP GATEWAY Connect IMS dependent region OTMA IMS DB services Database ICAL TCP/IP user-written Client MPP, JMP IFP, MD BMP IMS Callout to Services 61 GSE BENELUX IMS User Group Meeting – June 2013 Synchronous Callout – IMS ICAL – IMS 13 Synchronous Program Switch An enhancement to the DL/I ICAL to invoke another IMS application – In the same IMS – In a different IMS • In a Shared Queues back-end • Across an MSC link … and synchronously receive the response back during the same UOW IMS Callout to Services 62 GSE BENELUX IMS User Group Meeting – June 2013 Synchronous Callout – IMS ICAL – IMS 13 Synchronous Program Switch The target transaction can be a … – IFP – MPP – Message Driven BMP – JMP The target can run in … – IMS TM/DB – IMS TM IMS Callout to Services 63 GSE BENELUX IMS User Group Meeting – June 2013 Synchronous Callout – IMS ICAL – IMS 13 Synchronous Program Switch IMS internally schedules the transaction initiated by the ICAL as an OTMA transaction – Uses a new type of OTMA destination descriptor • TYPE=IMSTRAN – Keywords • • • • • • • LTERMOVR – IOPCB LTERM Override name TMEMBER – TMEMBER to queue late reply SMEM (YES/NO) – TMEMBER is a Supermember TPIPE – TPIPE to queue late reply SYNCTP – TPIPE is synchronized EXIT (YES/NO) – DFSCMUX0 can override late message parameters REPLYCHK (YES/NO) – called program always replies to IOCPB – If “yes” and program ends without replying caller gets special return and reason and extended reason codes • SYNTIMER – timeout value IMS Callout to Services 64 GSE BENELUX IMS User Group Meeting – June 2013 Synchronous Callout – IMS ICAL – IMS 13 Synchronous Program Switch In the AIB call the AIBRSNM1 specifies the Descriptor name – The transaction code is found after the llzz in the Request area – Mutli-segment input and output is supported IMS Callout to Services 65 GSE BENELUX IMS User Group Meeting – June 2013 Synchronous Callout – IMS ICAL – IMS 13 Synchronous Program Switch Considerations – To use synchronous program switch in a shared queues environment, all of the participating IMS systems must be Version 13 or later and have a MINVERS value of 13.1 – New design implications • • • • • • • • Timeout values Transaction Expiration Late Responses LTERM Override ALTPCB destinations Multiple ICALs Recursive requests Holding database locks across an ICAL request – Increased importance for performance tooling IMS Callout to Services 66 GSE BENELUX IMS User Group Meeting – June 2013 Synchronous Callout – IMS ICAL – IMS 13 Synchronous Program Switch Usage examples – Applications can issue multiple ICALs to different destination TYPEs • Synchronous callout • Synchronous program switch OTMA IMS CTL Region WebSphere IMS TMRA IMS SOAP Gateway 1 IMS Connect TCP/IP RYO pgm TRANA 3 2 Destination Descriptor TYPE(IMSCON) Destination Descriptor TYPE(IMSTRAN) GU, IOPCB ICAL DEST1 4 MSG-Q 7 5 6 ICAL TRANB TRANB GU IOPCB ISRT IOPCB IMS Callout to Services 67 GSE BENELUX IMS User Group Meeting – June 2013 Synchronous Callout – DB2 Stored Procedures Open Standards API calls Provides for program-to-program communication – supports synchronous communication Provides distributed coordinated commit – IMS is the coordinator via ESAF Requires DB2 SSM IMSID= member of IMS.PROCLIB • • • • • • • SST: Subsystem Type SSN: Subsystem Name LIT: Language Interface Token ESMT: External Subsystem Module Table RTT: Resource Translation Table REO: Region Error Option - “R”, “Q”, or “A” CRC: Subsystem Recognition Character IMS Callout to Services 68 GSE BENELUX IMS User Group Meeting – June 2013 Synchronous Callout – DB2 Stored Procedures CLIENT IMSA Program1 GU IOPCB EXEC SQL: CALL PROC ( :aaa : bbb … data DB2 Stored Procedure User Defined Function (UDF) ISRT IOPCB IMS Managed UOW1 IMS Callout to Services 69 GSE BENELUX IMS User Group Meeting – June 2013 Synchronous Callout – DB2 Attach Facility Open Standards API calls Provides for program-to-program communication – Supports synchronous communication Provides distributed coordinated commit – IMS is coordinator via RRS Requires DB2 and RRS IMS Callout to Services 70 GSE BENELUX IMS User Group Meeting – June 2013 Synchronous Callout – DB2 Attach Facility IMS Control RRS=Y SSM IMSID=. member of IMS.PROCLIB SST=DB2,SSN=DB2E,COORD=RRS DFSJVMMS member of IMS.PROCLIB -Djava.class.path= > /usr/lpp/db2/db2710/classes: > /usr/lpp/db2/db2710/classes/db2j2classes.zip DFSJVMEV member of IMS.PROCLIB LIBPATH=/usr/lpp/db2/db2710/lib DFSJMP or DFSJBP members of IMS.PROCLIB //DFSDB2AF DD DISP=SHR,DSN=IMS.SDFSRESL // DD DISP=SHR,DSN=DSNxxx.DSNLOAD (must all be APF authorized libraries) IMS Callout to Services 71 GSE BENELUX IMS User Group Meeting – June 2013 Synchronous Callout – DB2 Attach Facility CLIENT IMSA Program1 IMS-Java JMP/JBP JDBC: : DB2 CALL PROC ( :aaa : bbb … data Stored Procedure Web Service User Defined Function (UDF) ISRT IOPCB RRS Managed UOW1 IMS Callout to Services 72 GSE BENELUX IMS User Group Meeting – June 2013 Synchronous Callout – WebSphere MQ Considerations Open Standards API calls Provides for program-to-program communication Possible distributed coordinated commit Requires Queue partner SSM IMSID= member of IMS.PROCLIB – – – – – – – SST: Subsystem Type SSN: Subsystem Name LIT: Language Interface Token ESMT: External Subsystem Module Table (CSQQESMT) RTT: Resource Translation Table -Not Used by MQ REO: Region Error Option - “R”, “Q”, or “A” CRC: Subsystem Recognition Character - Not Used by MQ IMS Callout to Services 73 GSE BENELUX IMS User Group Meeting – June 2013 Synchronous Callout – WebSphere MQ Using ESAF (CSQQSTUB) CLIENT IMS MPP1/BMP1 MSG-Q GU IOPCB Message+Correlid MQCONN MQ MSG-Q MQPUT1 Not in syncpoint MQ Appl MQCONN MQOPEN MQGET Message+Correlid MQOPEN MQGET w/WAIT Correlid set Reply+Correlid MQPUT1 Reply+ Correlid Index on Correlid MQCOMMIT MQCLOSE MSG-Q MQDISC MQDISC ISRT IOPCB UOW1 IMS Callout to Services UOW2 ONE IMS Unit of Work (UOW) + MQ Application UOW 74 GSE BENELUX IMS User Group Meeting – June 2013 Synchronous Callout – WebSphere MQ Using ESAF (CSQBSTUB) CLIENT IMS MPP1/BMP1 MSG-Q GU IOPCB MQCONN (once) MQOPENs (once) Message+Correlid MQ MSG-Q MQ Appl MQCONN MQOPEN MQGET MQPUT Not in syncpoint Message+Correlid Reply+Correlid MQGET w/WAIT Correlid set MQPUT1 Reply+ Correlid Index on Correlid MQCOMMIT MQCMIT MSG-Q ISRT IOPCB MQDISC UOW2 UOW1 IMS Callout to Services ONE IMS Unit of Work (UOW) + MQ Application UOW 75 GSE BENELUX IMS User Group Meeting – June 2013 Synchronous Callout – WebSphere MQ Using ESAF (CSQBRSTB) CLIENT IMS MPP1/BMP1 MSG-Q GU IOPCB MQCONN (once) MQOPEN (once) Message+Correlid MQ MSG-Q MQ Appl MQCONN MQOPEN MQGET MQPUT1 Not in syncpoint Message+Correlid Reply+Correlid MQGET w/WAIT Correlid set MQPUT1 Reply+ Correlid Index on Correlid MQCOMMIT MQCMIT MSG-Q MQDISC ISRT IOPCB ONE RRS UOW – NOT TESTED RRS UOW1 IMS Callout to Services 76 GSE BENELUX IMS User Group Meeting – June 2013 Synchronous Callout – CPI-C/APPC Considerations Open Standards API calls Protocol for program-to-program communication IMS supports synchronous communication – Can be single UOW or multiple UOWs Protocol supports distributed coordinated commit IMS participates in coordinated commit – Coordinator or participant via RRS Requires APPC partner IMS Callout to Services 77 GSE BENELUX IMS User Group Meeting – June 2013 Synchronous Callout – CPI-C/APPC CLIENT MSG-Q IMSA-PGMA IMSA/IMSB/non-IMS LU6.2 TP-B GU IOPCB CMALLC Allocate TP-B Type=NONE/CONFIRM/SYNCPT CMSEND SEND_DATA CMRCV RECEIVE_and_WAIT CMDEAL DeAllocate MSG-Q Conversation CMRCV RECEIVE Session CMSEND SEND_DATA CMDEAL DeAllocate ISRT IOPCB UOW1 IMS Callout to Services 78 GSE BENELUX IMS User Group Meeting – June 2013 Synchronous Callout – RYO TCP/IP Considerations Open Standards API calls RYO protocol for program-to-program communication Protocol does not support coordinated commit – IMS does not participate in coordinated commit Requires TCP/IP partner IMS Callout to Services 79 GSE BENELUX IMS User Group Meeting – June 2013 Synchronous Callout – RYO Using TCP/IP CLIENT IMSA-PGMA TCP/IP-B GU IOPCB Socket Socket Connect - TCP/IP-B datagrams READ_DATA WRITE_DATA WAIT READ_DATA Connect – TCP/IP-C Connection WRITE_DATA CLOSE CLOSE ISRT IOPCB UOW1 IMS Callout to Services UOW2 80 GSE BENELUX IMS User Group Meeting – June 2013 Summary – IMS Callout Techniques Asynchronous Callout – IMS ALTPCB – WebSphere MQ Using ESAF – APPC/IMS Synchronous Callout – – – – – – IMS ICAL DB2 Stored Procedures DB2 Attach Facility WebSphere MQ Using ESAF CPI-C/APPC RYO Using TCP/IP IMS Callout to Services 81