Invoking a Web Service from an IMS Application - IMS UG October 2012 Hartford

©2012 IBM Corporation

Invoking a Web Service from

an IMS Application

IMS User Group

Steve Nathan

[email protected]

2

IMS Regional User Group

Invoking a Web Service from an IMS Application

Disclaimer

© Copyright IBM Corporation [current year]. 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

3



Acknowledgement

� This presentation was originally prepared by Ken

Blackman

– IBM Advanced Technical Solutions (ATS)

– [email protected]

4



Agenda

� Introduction

� Asynchronous Callout

– IMS ALTPCB

– WebSphere MQ Using ESAF

– APPC/IMS

� Synchronous Callout

– IMS ICAL

– DB2 Stored Procedures

– DB2 Attach Facility


– CPI-C/APPC

– RYO Using TCP/IP

5



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

bind, invoke

SOAP

WSDL

publish

UDDI

Broker

Service

Registry

WSDL

Application

find

Service

Requester

ClientWeb

Service

Service

Provider

IMS

3 basic components:- Service Provider- Service Broker- Service Requestor

The entire industry is agreeing

on one set of standards !!

6



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

7



Introduction – Asynchronous Model

READ_DATA

Message+appl-token

PROCESS_DATA

SEND_DATA

Message+appl-token

IMS Application

GU IOPCB

SEND_DATAMessage+Token

Message+Token

CLIENT

IMS Application

GU IOPCBReply+Token

ISRT ALTPCB to

CLIENT

Reply+Token

MSG-Q

MSG-Q

CLIENTIMS/non-IMS

READ_DATA

Message+Token

PROCESS_DATA

SEND_DATA

Reply+Token

MSG-Q

MSG-Q

TWO IMS Units of Work (UOW)

UOW1

UOW2

8



Introduction – Synchronous Model

IMS Application

GU IOPCB

SEND_DATA

Message

READ_with_WAIT

RECEIVE REPLY

ISRT IOPCB to

CLIENT

Message READ_DATA

Message

PROCESS_DATA

SEND_DATA

Reply

CLIENT

Reply

MSG-Q CLIENTIMS/non-IMS

MSG-Q

ONE IMS Unit of Work (UOW)UOW1

9



Introduction – Service Flow Concept

Program A

CLIENT

Program n

10



Introduction – Stored Procedure Concept

CLIENT

Stored Procedure

Get Data 1

Get Data 2

11



Introduction – Callout Destinations

� IMS TM Resource Adapter via IMS Connect

z/OS1

z/OS2

Linux for System z

Windows / AIX / Solaris / Linux

and z/OS

WebSphere

Application

Server

IMS Resource

Adapter

WebSphere

Application

Server

IMS Resource

Adapter

WebSphere

Application

Server

IMS Resource

Adapter

IMS

TCP/IP

XCF

XCF

IMS

IMS

IMS Connect

IMS Connect

IMS Connect

Local

12




� IMS SOAP Gateway via IMS Connect

IMS

OT

MA

XML

Web Service Clients,

e.g. Microsoft .Net,

SAP, Java, etc..

SOAPIMS

SOAP

Gateway

Windows,AIX,zLinux

Connect

IMS

XML

Adapter

IMS

App

z/os

DB

OT

MA

IMS

SOAP

Gateway

Web Service Clients,

e.g. Microsoft .Net,

SAP, Java, etc..

SOAP

XML

13




� IMS SOAP Gateway via IMS Connect (Call In)SOAP XML Byte array

Connect

Microsoft.NET Client

IMS

IMS SOAP Gateway

XML

Adapter

Adapter

Task

Manager

IMS

AppTCP/IPHTTP/SOAP

XML

Converters

IMS Web

Service

32 0IVTNO DISPLAY LAST1

<?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>

<?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>

<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>

<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>

93 0

ENTRY WAS DISPLAYED

DISPLAY

LAST1 FIRST1

8-111-11111

D01/R01 0001

14



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

15



Asynchronous Callout –IMS ALTPCB to IMS Application

IMS Application 1

GU IOPCB

ISRT ALTPCB to

IMS Application 2

Message+Token

Message+Token

CLIENT

IMS Application 3

GU IOPCBReply+Token

ISRT ALTPCB to

CLIENT

Reply+Token

MSG-Q

MSG-Q

IMS Application Service

IMS Application 2

GU IOPCBMessage+Token

ISRT ALTPCB to

IMS Application 3

Reply+TokenMSG-Q

MSG-Q

THREE IMS Units of Work (UOW)

UOW1

UOW3

UOW2

16



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

17



Asynchronous Callout –IMS ALTPCB to IMS Connect RYO Application

IMS Application 1

GU IOPCB

ISRT ALTPCB to

IMS Connect

Message+Token

CLIENT

IMS Application 2

GU IOPCBReply+Token

ISRT ALTPCB to

CLIENT

MSG-Q

MSG-Q

IMS Connect Client

Connect

Write

Resume TPIPE

Read

Message+Token

Write

ACK

Send-Only

Reply+Token

MSG-Q

MSG-Q

TWO IMS Units of Work (UOW) + ICON Client UOW

UOW1

UOW3

UOW2

IMS Connect

18



Asynchronous Callout –IMS ALTPCB to IMS TM Resource Adapter

WebSphere Application ServerIMS

IMS TM Resource Adapter

EJB

6. MSG1

IMS

Co

nn

ect

2. ISRT ALTPCB (IC4JEJB)

TP1

MSG1

MSG2

1. ReceiveAsync(TP1)

3.Send

MSG1

1.ResumeTPIPE(TP1)

4.receive MSG1

5.sendACK

0. Start

IMS App1

IMS App2

Initiating

Client

RESUME TPIPE

Single WaitAlt ClientID= TP1

DFSYDTx

(new definition)IC4JEJB

TYPE = IMSCON

TMEMBER=SM01

TPIPE=TP1

SMEM=Y

7. send New Msg

“Single wait ”

Commit then Send (CM0)

Sync-Level=CONFIRM

Execution timeout

IMS App1

MDB

OR

WIN, AIX, SOLARIS, LINUX, etc.

Web

Service

19



Asynchronous Callout –IMS ALTPCB to IMS SOAP Gateway

IMS

IMS App1

Win, AIX, , Linux, z/OS.

:

ISRT ALTPCB

IMSSOAP1

SYNCPT Starts..

IMS SOAP Gateway Server

RESUME TPIPE TP3

IMS

Connect

IMS App2

RECEIVE InXMLMsg1

SEND OutXMLMsg

Initiating

Client

1

2

345

67

XML

Adapter

Msg1

Msg2

TP3

DFSYDTx

IMSSOAP1

TYPE = IMSCON

TMEMBER=SM01

TPIPE=TP3

SMEM=Y

ADAPTER = HWSXMLA0

CONVERTR=SOAPIT

“Single wait ”

5.sendACK

SOAPIT

XML

Converter

Connection

Bundle(CBA)

TPIPE = TP1,TP3

Web

Service

20



Rational Developer for System z (RDz)

Rational Developer for System z (RDz) 7.1.1

Mapping

Metadata

WSDL

From web

service

Meet-in-Middle Compiled Generation Wizard

IMS Callout

Correlator

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.

Compiled

Converters

LanguageStructures(e.g. COBOLCopybooks)From IMSCallout app

21



Asynchronous Callout –IMS ALTPCP to WebSphere MQ IMS Bridge

IMS Application 1

GU IOPCB

ISRT ALTPCB to

MQ IMS Bridge(YPRX0 + MQDRU)

Message+Token

CLIENT

IMS Application 2

GU IOPCBReply+Token

ISRT ALTPCB to

CLIENT

MSG-Q

MSG-Q

MSG-Q

MSG-Q

TWO IMS Units of Work (UOW) + 2MQ QM UOWs + MQ Application UOW

UOW1

UOW5

UOW2 & UOW4

WebSphere MQQueue

Manager

IMS Bridge

XCF Read

MQPUT

MQGET

XCF Write

UOW3

MQ Appl

MQCONN

MQOPEN

MQGETMessage+Token

MQPUT1Reply+Token

MQCOMMIT

MQDISC

MQ

MSG-Q

22



Asynchronous Callout –IMS ALTPCB to OTMA C/I Application

IMS Application 1

GU IOPCB

ISRT ALTPCB to

IMS Application 2

Message+Token

Message+Token

CLIENT

IMS Application 3

GU IOPCBReply+Token

ISRT ALTPCB to

CLIENT

Reply+Token

MSG-Q

MSG-Q

OTMA C/I

Application

otma_create

otma_open

otma_receive_asyncMessage+Token

otma_send_async

Reply+Token

otma_close

MSG-Q

MSG-Q

UOW1

UOW3

UOW2

TWO IMS Units of Work (UOW) +

OTMA C/I Application UOW

23



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

24



Asynchronous Callout –WebSphere MQ Using ESAF

IMS MPP1/BMP1

GU IOPCB

MQCONN

MQPUT1

MQDISC

Message+Token

CLIENT

IMS BMP2

MQCONN

MQOPEN

MQGET w/WAIT

ISRT ALTPCB

IMS SYNC

Reply+Token

MSG-Q

MSG-Q

UOW1

UOW3

UOW2

MQ ApplMQCONN

MQOPEN

MQGETMessage+Token

MQPUT1Reply+Token

MQCOMMIT

MQDISC

MQ

MSG-Q

TWO IMS Units of Work (UOW) + MQ Application UOW

25



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

26



Asynchronous Callout –APPC/IMS

IMS Application 1

GU IOPCB

ISRT ALTPCB

(LU 6.2 Descriptor)

Message+Token

CLIENT

IMS Application 2

GU IOPCBReply+Token

ISRT ALTPCB to

CLIENT

MSG-Q

MSG-Q

MSG-Q

MSG-Q

TWO IMS Units of Work (UOW) + 2 APPC/MVS UOWs + APPC Appl UOW

UOW1

UOW5

UOW2 & UOW4

APPC/IMS

CMALLOCAlloc TP-B

Type=NONE/

CONFIRM

CMSEND

CMDEALL

CMRCVSend data to

IMS

CMDEAL

UOW3

IMS/non-IMS

LU 6.2 TP-B

CMRCV

Process Data

CMDEAL

CMALLOC

CMSEND

CMDEAL

Session

Conv A

Session

Conv B

27



Synchronous Callout

� ICAL– IMS TM Resource Adapter– SOAP Gateway– RYO

� 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

28



Synchronous Callout –IMS ICAL


– 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

29





– 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 the Correlation Token

30





– 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

– The IMS Connect Client maintains the Correlation Token

31





–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

32





– 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

33




OTMADescriptor 1

IMS Application 2

Send flow

Receive flow

IMS

IMS Application 3

IMS Application 1

OTMADescriptor 2

OTMADescriptor 3

WebSphere Application Server

IMSSOAP

Gateway

IMS ConnectRoll-your-own

Application

EJB / MDB

Web ServiceProvider

IMS TM Resource Adapter

IMS Connect

34





– 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

35




�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

36





– 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

37




� 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

38




RYO Application

ACK

Response

1

5

6

IMS Connect IMS

IMS Application

2

IAPMDI27 JOHN DOE .

Resume TPIPE TPIPE1

ICAL SENDRECV OTMDEST1

JOHN DOE

JOHN DOE

Request

TPIPE TPIPE1

34

7 89

1234567812345678

10

39





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

40





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+)

41




� 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

42




� /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 TYPE TRAN/STEP PROGRAM STATUS CLASS

1 MPP1A TP APOL11 APOL1 WAIT-CALLOUT 1

TMEMBER HWS TPIPE: TPIPE1

JMPRGN JMP NONE

JBPRGN JBP NONE

BATCHREG BMP NONE

FPRGN FP NONE

DBTRGN DBT NONE

DBRZCSAJ DBRC

DLIZCSAJ DLS

*08213/165100*

43




� /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

44




� 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

45



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

46



Synchronous Callout –IMS ICAL – IMS TM Resource Adapter - EJB

IMS

TM

RA

z/OS

IMS

TM/CTL

ServicesIMS

Connect

HWS1

EJB

Application Program

ICAL

DEST1

Resume TPIPE TPS

OT

MA

TPS DEST1TPSHWS1

ACK

Send_ONLY

SYNC_RECEIVE_ASYNCOUTPUT TPS

SYNC_SEND


CORTKN Data

CORTKN Data

Request

Response

CORTKN Data

CORTKN Data

47



Synchronous Callout –IMS ICAL – IMS TM Resource Adapter - MDB

IMS

TM

RA

z/OS

IMS

TM/CTL

ServicesIMS

Connect

HWS1

MDB

Application Program

ICAL

DEST1

Resume TPIPE TPS

OT

MA

TPS DEST1TPSHWS1

ACK

Send_ONLY

ACTIVATE


EJB

Service

CORTKN Data

CORTKN Data

Request

Response

Data

Data

48



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

49




Web

Service

IMS

SOAP

Gateway

z/OS

IMS

TM/CTL

ServicesIMS

Connect

HWS1

Application Program

ICAL

DEST1

Resume TPIPE TPS

OT

MA

TPS

DEST1TPSHWS1HWSXMLA0XMLCNV1DACK

Send_ONLY HWSXMLA0

XML ConverterXMLCNV1D

CORTKN XML

CORTKN XML

Request

data

Response

data

XML

XML

Connection BundleTPS

50




Web ServiceProvider

IMS SOAP Gateway

Response

0

4

IMS Connect

z/OS

IMS

IMS Application

1

Resume TPIPE

ICAL SENDRECV OTMDEST1

HELLO FROM IMS

HELLO FROM IMS

Request

HELLO FROM WEB SERVICE

HELLO FROM

WEB SERVICE

RESUME

TPIPE

HELLO

FROM IMS

HELLO FROM

WEB SERVICE

3

Initiating Client

HWS1

XML

Adapter

XML

Converter

Correlator

2 ACKX3

X1

X2

X4

X5 X6

X5: external server already commit before time out

X6: external server already commit, but IMS fails to

process the response

X1: ICAL cannot be sent out

X2: ICAL time out

X3: late ACK received after time out

X4: XML converter in error

Error Scenarios

51



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

52



Synchronous Callout –IMS ICAL – RYO

z/OS

IMS

TM/CTL

ServicesIMS

Connect

HWS1

TCP/IP

RYO

Application Program

ICAL

DEST1

Resume TPIPE TPS

OT

MA

TPSDEST1TPSHWS1

ACKSend_ONLY

CToken Data

CToken Data

Request

Response

53



Synchronous Callout –IMS ICAL – IMS 13 Enhancements

� IMS Synchronous Callout with ICAL to another IMS transaction

– Both run under a single Unit of Work

� Retrieval of truncated synchronous response

– If Response buffer is too small OTMA returns truncated response and the real length of the response message

– IMS application can now ask for the rest of the response message

54



Synchronous Callout –DB2 Stored Procedures

� Open Standards API calls


– 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

55



Synchronous Callout –DB2 Stored Procedures

IMSAProgram1

GU IOPCB

EXEC SQL:

CALL PROC ( :aaa : bbb …DB2

Stored Procedure

User Defined Function

(UDF)

data

CLIENT

ISRT IOPCB

IMS Managed

UOW1

56



Synchronous Callout –DB2 Attach Facility



– Supports synchronous communication

� Provides distributed coordinated commit

– IMS is coordinator via RRS

� Requires DB2 and RRS

57




� 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)

58




Web

Service

IMSAProgram1

IMS-Java JMP/JBP

JDBC:

:CALL PROC ( :aaa : bbb …

data

CLIENT

ISRT IOPCB

RRS Managed

UOW1

DB2 Stored Procedure

User Defined Function

(UDF)

59



Synchronous Callout –WebSphere MQ Considerations



� 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

60



Synchronous Callout –WebSphere MQ Using ESAF (CSQQSTUB)

IMS MPP1/BMP1

GU IOPCB

MQCONN

MQPUT1

Not in syncpoint

MQOPEN

MQGET w/WAIT

Correlid set

MQCLOSE

MQDISC

ISRT IOPCB

Message+Correlid

CLIENT

Reply+Correlid

MSG-Q

MSG-Q

UOW1

UOW2

MQ ApplMQCONN

MQOPEN

MQGETMessage+Correlid

MQPUT1Reply+ Correlid

MQCOMMIT

MQDISC

MQ

MSG-Q

ONE IMS Unit of Work (UOW) +

MQ Application UOW

Index on Correlid

61



Synchronous Callout –WebSphere MQ Using ESAF (CSQBSTUB)

IMS MPP1/BMP1

GU IOPCB

MQCONN (once)

MQOPENs (once)

MQPUT

Not in syncpoint

MQGET w/WAIT

Correlid set

MQCMIT

ISRT IOPCB

Message+Correlid

CLIENT

Reply+Correlid

MSG-Q

MSG-Q

UOW1

UOW2

MQ ApplMQCONN

MQOPEN



MQCOMMIT

MQDISC

MQ

MSG-Q

ONE IMS Unit of Work (UOW) + MQ Application UOW

Index on Correlid

62



Synchronous Callout –WebSphere MQ Using ESAF (CSQBRSTB)

IMS MPP1/BMP1

GU IOPCB

MQCONN (once)

MQOPEN (once)

MQPUT1

Not in syncpoint

MQGET w/WAIT

Correlid set

MQCMIT

ISRT IOPCB

Message+Correlid

CLIENT

Reply+Correlid

MSG-Q

MSG-Q

RRS UOW1

MQ ApplMQCONN

MQOPEN



MQCOMMIT

MQDISC

MQ

MSG-Q

ONE RRS UOW – NOT TESTED

Index on Correlid

63



Synchronous Callout –CPI-C/APPC Considerations


� 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

64



Synchronous Callout –CPI-C/APPC

CLIENT

IMSA-PGMAIMSA/IMSB/non-IMS

LU6.2TP-B

GU IOPCB

CMALLC Allocate TP-B

Type=NONE/CONFIRM/SYNCPT

CMSEND SEND_DATA

CMRCV RECEIVE_and_WAIT

CMDEAL DeAllocate

ISRT IOPCB

Session

Conversation

UOW1

MSG-Q

CMRCV RECEIVE

CMSEND SEND_DATA

CMDEAL DeAllocateMSG-Q

65



Synchronous Callout –RYO TCP/IP Considerations


� RYO protocol for program-to-program communication

� Protocol does not support coordinated commit

– IMS does not participate in coordinated commit

� Requires TCP/IP partner

66



Synchronous Callout –RYO Using TCP/IP

GU IOPCB

Socket

Connect - TCP/IP-B

WRITE_DATA

WAIT

READ_DATA

CLOSE

ISRT IOPCB

TCP/IP-B

Socket

Connect – TCP/IP-C

READ_DATA

WRITE_DATA

CLOSE

Connection

datagrams

CLIENT IMSA-PGMA

UOW1 UOW2

67



Summary – IMS Callout Techniques

� Asynchronous Callout

– IMS ALTPCB


– APPC/IMS


– IMS ICAL

– DB2 Stored Procedures

– DB2 Attach Facility


– CPI-C/APPC

– RYO Using TCP/IP

Technology

Invoking a Web Service from an IMS Application - IMS UG October 2012 Hartford