© 2013 IBM Corporation

®

IMS

Calling out from IMS applications: methods and best practices

Ben JohnsonJack Yuan

April 18, 2013

With THANKS toDave CameronKen BlackmanHimakar Chennapragada

IMS

2

Customers running IMS have a variety of computer hardware and network configurations installed, typically employing IMS as a repository for information.

Some customers also use IMS as one of their application platforms in Enterprise resource planning (ERP) systems that integrate internal and external management information.

Why call out?

© 2013 IBM Corporation

®

IMS

Overview of 7 IMS callout methods

IMS

4

IMSA-PGMAGU IOPCBISRT ALTPCB

IMSA/IMSB(MSC) PGM-B

IMS-Managed ALTPCB Callout

GU IOPCBISRT IOPCB

CLIENT

UOW1

UOW2

IMS

5

IMSA-PGMAGU IOPCB

ISRT ALTPCB

CPI-C TP-ACMRCVCMSEND

CMDEALAPPC/IMSCMALLC Allocate TP-AType=NONE/CONFIRMCMSEND SEND_DATACMDEAL DeAllocate

ConversationA

CLIENT

ISRT IOPCB

UOW1

IMS LU6.2Descriptor

UOW2

CPI-C/APPC Synchronous

CMALLC Allocate TP-BType=NONE/CONFIRM/SYNCPTCMSEND SEND_DATACMRCV RECEIVE_and_WAITCMDEAL DeAllocate

ConversationB

UOW1

CPI-C TP-BCMRCV CMSEND CMDEAL

Callout using APPC

APPC Asynchronous

IMS

6

IMSA-PGMAGU IOPCB

MQCONN MQ-BMQPUT NO-SYNCPOINT

MQGET NO-SYNCPOINTMQDISC

MBMQGETMQPUT

MQDISC

Queue

messages

Synchronous Callout with WebSphere MQ API

CLIENT

ISRT IOPCB

IMS Managed

UOW1

IMS

7

Service

IMSA-PGMAGU IOPCBEXEC SQL:

CALL PROC ( :aaa : bbb … DB2 stored procedure

User-defined function (UDF)

data

DB2 Stored Procedure via ESAFSynchronous

CLIENT

ISRT IOPCB

IMS Managed

UOW1

IMS

8

READ_DATAWRITE_DATA

CLOSE

Socket Connect - TCP/IP-BWRITE_DATAREAD_DATA

CLOSE

TCP/IP-BREAD_DATASocketConnect -TCP/IP-C

Connection

datagrams

User-Written TCP/IP Synchronous callout

CLIENT IMSA-PGMAGU IOPCB

ISRT IOPCB

UOW1

UOW2

IMS

9

IMS-ApplGU IOPCBISRT ALTPCB

OTMA Descriptor TMEMBER TPIPE IMS Connect

Socket

Message

Asynchronous callout via OTMA

TCP/IP-BResume_TPIPEREAD_DATAACK

CLIENT

ISRT IOPCB

UOW1

UOW2

IMS

10

IMS-ApplGU IOPCBICAL OTMA

Descriptor TMEMBER TPIPE

IMS Connect

Socket

Message

Synchronous callout using DL/I ICAL

TCP/IP-BResume_TPIPEREAD_DATA(COR_ID)ACKSEND_DATA(COR_ID)

CLIENT

ISRT IOPCB

UOW1

UOW2

SEND_DATA

RECEIVE_DATA

IMS

11

Summary of IMS callout methods

ICAL

ISRT ALTCB OTMA

ESAF/

DB2

ESAF/

MQSeries

TCP/IP

Sockets

Using

APPC

IMS program switch

Data-

Power

IMS SOAP

Gateway

TCP/IP

App.

WebSp.

TMRAMQ.

App.

DB2 App.

APPC/

CPI-C App

IMS

App.

Coordi-nated

Commit/backout

Sync.

Comm.

Async.

Comm.

* * *

*

* * *

: indirect call

methods

Attribute&EndPoint

© 2013 IBM Corporation

®

IMS

Synchronous callout using DL/I ICALDeep-dive

IMS

13

DL/I ICAL call provides the capability to callout to resources outside IMS synchronously

IMS SOAP GATEWAY

z/OSIMS

Database

DBServices

OTM

A

TM/CTLServices

IMS

Connect

TCP/IP

user-written Client

WebSphere

IMS TM resource adapterApplication Program

ICAL

MPP/JMP/IFP/BMP/JBP

OTMADescriptor

OTMADescriptor

IMS

14

Overview - IMS Synchronous Callout using DL/I ICAL

� It is a SYNCHRONOUS call in your IMS application.– Need to change your existing IMS application or create a new

IMS application

� Does not go through IMS Message Queue, and the synchronous callout message/response are not recovered.

� Does not support 2 phase commit support using RRS

� Callout message needs to go through IMS Connect

– It does not go through MQSeries support

IMS

15

Overview - IMS Synchronous Callout using DL/I ICAL…

� Supports messages larger than 32K without segmentation– No need to build data in LLZZ format

� Timeout support to optionally terminate callout request and free the dependent region

� IMS commands enhanced to view synchronous callout status and stop the callout processing

� Limited security credentials propagated by IMS to external server

� If a shared queues back-end IMS does not have an IMS Connect connection, the back-end IMS cannot process DL/I ICAL for callout

� IMS listener in WAS or distributed application. – Based on OTMA Resume TPIPE/Send Only protocol function for

retrieving synchronous callout requests and sending responses. So we Leverage asynchronous flow, although appears synchronous to IMS application

IMS

16

Steps to have a synchronous callout application using ICAL

STEP 1:

STEP 2:

STEP 3:

STEP 4:

Determine the external application (WebSphere TMRA, TCP/IP roll-your-own application, TCP/IP application using IMS Connect API, or IMS Soap Gateway application)

Setup IMS (OTMA destination descriptor)

Setup IMS application (COBOL, PL/I, REXX, C, JAVA…..)

Setup the external application or server for callout messages

IMS

17

Determine the external application

Database Management

� A light-weight Web Service solution for IMS without the need of a Java EE server

� Java EE apps (MDB or EJB) running in WebSphere Application Server (WAS) using IMS TM Resource Adapter (IMS TM RA)

Transaction ManagementWebSphere MDB/EJB appl.

� TCP/IP application connects to IMS Connect

� Need to understand IMS Connect and OTMA protocols

SOAP Gateway Appl.

SystemRoll-your-own Appl.

� Supports the high performance IMS Callout solution, and DataPower’shardware acceleration for XML processing.

Roll-your-own w/ DataPower

� A simplified callable interface for interaction with IMS Connect

� Addresses the complexities of writing RYO applications

Roll-your-own w/ ICON API

IMS

18

Setting up OTMA destination descriptor in IMS PROCLIB

D destname keywordsWhere:

destname is destination names and can be masked by ending in an *keywords are: TYPE=IMSCON

TMEMBER=nameTPIPE-nameSMEM=YES|NOADAPTER=adapnameCONVERTR=convnameSYNTIMER=timeout (If both ICAL & Descriptor specify timeout, the lower value is used)

D OTMDEST1 TYPE=IMSCON TMEMBER=HWS1 TPIPE=TPIPE1 SYNTIMER=500

� The OTMA Destination Routing Descriptors were introduced in IMS 10. They externalize the routing definitions and specifications for callout messages without IMS user exits. Descriptors are read and initialized at IMS startup.

– Use ‘D’ descriptor type in DFSYDTx member of IMS.PROCLIB.

For example:D SOAPGW1 TYPE=IMSCON TMEMBER=HWS1 TPIPE=HWS2SOAPD SOAPGW1 ADAPTER=XMLADPTR CONVERTR=XMLCNVTR SYNTIMER=200

D SANDY01 TYPE=IMSCON TMEMBER=HWS2 TPIPE=TPIPE2

IMS

19

IMS type-2 commands for OTMA destination routing descriptors

� Type-2 commands can also be used to update, create, delete, or query the descriptor entries

– CREATE OTMADESC

– UPDATE OTMADESC

– QUERY OTMADESC

– DELETE OTMADESC

For example: UPDATE OTMADESC NAME(OTMDEST1) SET(SYNTIMER(800))

QRY OTMADESC NAME(OTMDEST1) SHOW(ALL)

IMS

20

Prepare your IMS application for the DL/I ICAL

>>-ICAL--aib---request_area---response_area-----------------><

The format of the ICAL call for a synchronous callout request:

IMS

21

COBOL Application with ICAL

Descriptor name

Timeout

Request Area LengthResponse Area Length

Output return codes

ICAL

AIB

IOAreas

IMS

22

BMP with DDLT0 tool

� 25-32 a destination name in OTMA destination descriptor name, 8–byte character field (ICAL). Our example is JOHNSON1

� 34-39 The wait time for the synchronous call to be processed, 6–byte character field with a range from 1 to 999999 (ICAL), our example is 8 seconds

� 41-45 The input message length nnnnn The length of the input data in the request area (ICAL). Our example is 50 bytes

� 47-51 The response area length nnnnn The length of the response area for the output message (ICAL). Our example is 1000 bytes

//JACK EXEC DDLT0,PSBNAME=PSAPP99,TYPE=BMP,IMSID=TEST, // QUAL=IMSTSYS,NBA=50 //SYSIN DD * S1111 1 1 1 1IOPCB AIB L ICAL SENDRECV JOHNSON1 000800 00050 01000 L DATA CREDIT CARD NUMBER FOR JACK E OK

--------------------------------------------------------------------------------SEGMENT =(CREDIT CARD NUMBER FOR JACK ) ................................................................................CALL=ICAL

SEGMENT =(111222333444 )

COMP RET CODE=OK IOPCB LTERM= RET CODE= RACFUSER=PSAPP99 .

0003 0003 0000 AIB BLOCK AIBOALEN = 0002, AIBOAUSE = 0006, RETURN CODE = 0000, REASON

IMS

23

IMS

24

WebSphere and IMS TM Resource Adapter

WAS/WPS/WTX/WMB/WESB

IMS TMIMS TMresourceresourceadapteradapter

WebService

TCP/IP

WebComponent

EnterpriseBean

IMS Connect

IMS DB *

IMS

IMS App

� Enable an IMS transaction as Web Service with full SOA support– Integrate with a variety of Java EE or WebSphere-based servers with built-in QoS

support (2PC, connection pooling, security management)

– Java EE Connector Architecture (JCA/J2C) compliant

– Recommended when Java EE server (e.g. WAS) is already in-use

– Supports rapid application development with Rational tooling

Rational Application Developer (RAD) orWebSphere Integration Developer (WID)

IMS app Source (COBOL, PLI, C, MFS)

Generates

* Binary, text or XML data

IMS

25

IMS

26

Synchronous Callout Flow

IMS

IMS App1

z/OSz/OS, zLinux, Win, AIX etc..

DL/I ICALDescriptor nameTimeout

IMS Enterprise Suite SOAP Gateway Server

IMS Connect

Receive Callout Request in XML

Send Callout Response in XML

WebService

A

XMLAdapter

Msg1Msg2

TPIPE

Send ACK

XMLConverter

1

2

3

5

67

Development & Runtime Environment

4

ExecutionExecution

GenerationGeneration

RD/z Meet-In-The-MiddleWizard

Existing WSDL

CorrelatorFile

RD/zGenerateTask

Existing COBOLCopybook

Development environment

Error Handling: If Web Services returns a Web Service Fault error, SOAP Gateway sends an error response with the Fault message to the DLI call

IMS

27

IMS

2828

IMS Synchronous Callout Overview for RYO client

RYO Application

ACK

Response

1

3

4

IMS Connect

z/OS

IMS

IMS Application

2

Initiating Client

Resume TPIPE TPIPE1

ICAL SENDRECV OTMDEST1HELLO FROM IMSHELLO FROM IMS

Request

TPIPE TPIPE1

HELLO FROM RYOHELLO FROM RYO

OTMDEST1TPIPE1HWS1

HWS1

OTMA Descriptor

IMS

29

Callout with RYO - Programming

1. Issue Resume TPIPE request

– CM0, Synclevel Confirm, RT Auto/Single, timeout

– Resume TPIPE on client ID or alternate client ID

2. Receive the callout request and correlation token

3. Send an ACK to acknowledge the callout request– Alternately, you may send a NAK to stop the callout request

4. Send an response back to IMS with correlation token– Commit Mode 0, Send-Only

– Alternately, an error response maybe sent in case of error situation

IMS

30

IMS

31

IMS Connect API

IMS Connect

API

Client Application IMS

Connect API

Client Application

IMS Connect

API

Client Application

IMS Connect

Windows or z/OS

OTMA

IMS AppIMS AppIMS App

z/OS

Connection And

TMInteractionproperty

files

load

IMS

32

IMS Connect API

� Provides simplified API to build roll-your-own IMS Connect client application to invoke IMS transactions from Java and C environments

� Shields users from IMS Connect protocol (IRM, CSM, RSM, etc.) and low-level socket communications

� Recommend to use in RYO client application that does not run in an application server

� Value

– Extends the value of IMS resources by allowing easy access from new Java or C-based applications

– Simplifies migration of existing applications from SNA to TCP/IP

– Simplifies development of new applications to access IMS transactions

IMS

33

IMS

34

Inbound / Outbound DataPower flow for IMS Callout

Response

DataPower XI52, XI50B, XB62

Multi-Protocol Gateway

Transformation

IMS

Callout Front S

ide Handler

Transformation

Request

Outbound Rule

Inbound Rule

IMS V12

IMS

application

..

ICAL

(synchronous)

IMS

Connect

TPIPE

Ser

vice

sS

ervi

ces

WS

Proxy

© 2013 IBM Corporation

®

IMS

Calling out from IMS applications:Best Practices

With THANKS toDave Cameron

IMS

36

Choose the asynchronous callout method to avoid tying up IMS regions while the callout request is processed

Sync Callout Response

Callout Request

Async Callout Response

IMS Application 1

IMS Application 2

Async: ISRT ALTPCBSync: ICAL

IMS

37

Choose a synchronous callout method that is scalable and provides good performance for your installation

� Using APPC/CPI-C

� Using TCP/IP socket calls

� Using ESAF/MQSeries

� Using ESAF/DB2

� Using ICAL DL/I call (This is the newest solution offered by IMS)

IMS

38

Best practices for using ICAL DL/I call from IMS applications

� Design synchronous callout applications to minimize resource contention

– After an IMS application issues an ICAL call for a synchronous callout, it waits in the IMS dependent region until either the response is received from the external application or the timeout interval expires. While waiting, all of the resources that the application program has accumulated during the current unit of work are held.

– To avoid excessive resource contention, have the application program issue the ICAL DL/I call as early as possible, before too many resources are obtained.

IMS

39

Best practices for using ICAL DL/I call from IMS applications…

� Define an appropriate number of IMS dependent regions

– When many IMS applications use synchronous callout, especially with slow external service providers, it may become necessary to increase the number of IMS dependent regions. This comes with the concerns of more resources and greater chances for resource contention.

� Define appropriate timeout values on the ICAL call

– The synchronous callout request also allows for setting a timeout value so if the callout response is delayed the IMS application will receive return and reason codes indicating the timeout and the application can decide whether to proceed without the callout information or to retry the callout request. The timeout value must be balanced between allowing sufficient time for the callout request to be processed and protecting the IMS dependent region from being held up.

IMS

40

Best practices for using ICAL DL/I call from IMS applications…

� Manage high volume and multiple destinations with OTMA destination descriptors

– If high volumes of callout requests are anticipated then the service provider should make retrieval requests to different destinations and separate descriptors can be used to route callout requests to these separate destinations. This can improve throughput, but might add complexity to the IMS applications.

© 2013 IBM Corporation

®

IMS

Things to Know

IMS

42

Summary of callout highlights

1. Calling out from IMS applications can integrate IMS data and applications with many modern enterprise architectures, such as ERP systems, service oriented architectures (SOA), and so forth.

2. When choosing a synchronous or asynchronous callout method, consider your needs for scalability and performance.

3. The ICAL DL/I call has been available for synchronous callout since IMS Version 10.

4. All messages that use the ICAL callout method go through IMS Connect.

5. IMS Version 13 expands the ICAL DL/I call to support synchronous program switch function to “call out” to other IMS application program.