Embed Size (px)
DESCRIPTION
Citation preview
®
IMS
Calling out from IMS applications: methods and best practices
© 2013 IBM Corporation
IMS User Group Meeting
Sept 11, 2013
Jack Yuan – [email protected]
IMS
Why call out?
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.
IMS
Asynchronous Model
READ_DATA
Message+appl-token
IMS Application
GU IOPCB
SEND_DATAMessage+Token
Message+Token
CLIENT
MSG-Q CLIENTIMS/non-IMS
READ_DATAMessage+Token
MSG-Q
3
PROCESS_DATA
SEND_DATA
Message+appl-token
IMS Application
GU IOPCBReply+Token
ISRT ALTPCB to
CLIENT
Reply+Token
MSG-Q
PROCESS_DATA
SEND_DATA
Reply+Token
MSG-Q
TWO IMS Units of Work (UOW)
UOW1
UOW2
IMS
Synchronous Model
IMS Application
GU IOPCB
SEND_DATA
Message
Message READ_DATA
Message
CLIENT
MSG-Q CLIENTIMS/non-IMS
4
Message
READ_with_WAIT
RECEIVE REPLY
ISRT IOPCB to
CLIENT
PROCESS_DATA
SEND_DATA
ReplyReply
MSG-Q
ONE IMS Unit of Work (UOW)UOW1
IMS
Topics
� Overview of 7 IMS callout methods
� Deep-dive of the DL/I ICAL call for callout and program switch
� Best practices
� Case study
� Summary
5
� Summary
®
IMS
Overview of 7 IMS callout methods
© 2013 IBM Corporation
IMS
IMSA-PGMAGU IOPCBISRT ALTPCB
#1 IMS-Managed ALTPCB Callout (program to program switch)
CLIENT
7
IMSA/IMSB(MSC) PGM-B
GU IOPCB
ISRT IOPCB
UOW1
UOW2
IMS
IMSA-PGMA
GU IOPCB
ISRT ALTPCB
CPI-C TP-ACMRCV
CMSEND
CMDEALAPPC/IMS
CMALLC Allocate TP-A
Type=NONE/CONFIRM
ConversationA
CLIENT
IMS LU6.2
Descriptor
#2 Callout using APPC
APPC Asynchronous
8
Type=NONE/CONFIRM
CMSEND SEND_DATA
CMDEAL DeAllocate
ISRT IOPCB
UOW1 UOW2
CPI-C/APPC Synchronous
CMALLC Allocate TP-B
Type=NONE/CONFIRM/SYNCPT
CMSEND SEND_DATA
CMRCV RECEIVE_and_WAIT
CMDEAL DeAllocate
ConversationB
UOW1
CPI-C TP-BCMRCV
CMSEND
CMDEAL
IMS
IMSA-PGMAGU IOPCB
MQCONN MQ-BMQPUT NO-SYNCPOINT
#3 Callout with WebSphere MQ API
CLIENT
9
MQPUT NO-SYNCPOINT
MQGET NO-SYNCPOINT
MQDISCMBMQGETMQPUT
MQDISC
Queue
messages
ISRT IOPCB
IMS Managed
UOW1
IMS
IMSA-PGMAGU IOPCBEXEC SQL:
CALL PROC ( :aaa : bbb … DB2 stored procedure
#4 DB2 Stored Procedure via ESAF
CLIENT
10
Service
User-defined function (UDF)
data
ISRT IOPCB
IMS Managed
UOW1
IMS
Socket
Connect - TCP/IP-BWRITE_DATA
#5 User-Written TCP/IP Synchronous callout
CLIENT IMSA-PGMA
GU IOPCB
11
READ_DATA
WRITE_DATA
CLOSE
WRITE_DATA
READ_DATA
CLOSE
TCP/IP-BREAD_DATA
Socket
Connect -TCP/IP-C
Connection
datagrams
ISRT IOPCB
UOW1
UOW2
IMS
IMS-ApplGU IOPCBISRT ALTPCB
OTMA
Descriptor
#6 Asynchronous callout via OTMA
CLIENT
12
Descriptor TMEMBER
TPIPE IMS Connect
Socket
Message TCP/IP-BResume_TPIPEREAD_DATA
ACK
ISRT IOPCB
UOW1
UOW2
IMS
IMS-ApplGU IOPCBICAL
OTMA
Descriptor TMEMBER
TPIPE
#7 Synchronous callout using DL/I ICAL
CLIENT
SEND_DATA
RECEIVE_DATA
13
TPIPEIMS Connect
Socket
Message TCP/IP-BResume_TPIPEREAD_DATA(COR_ID)
ACK
SEND_DATA(COR_ID)
ISRT IOPCB
UOW1
UOW2
RECEIVE_DATA
®
IMS
Synchronous callout using DL/I ICAL
Deep-dive
© 2013 IBM Corporation
Deep-dive
IMS
DL/I ICAL call provides the capability to callout to resources outside IMS synchronously
z/OS
IMS
OT
MA
TM/CTL
WebSphere
IMS TM resource adapterApplication Program
MPP/JMP/IFP/BMP/JBP
15
IMS SOAP GATEWAY
Database
DB
Services
OT
MA
TM/CTL
Services
IMS
Connect
TCP/IP
user-written Client
Program
ICAL
OTMADescriptor
OTMADescriptor
IMS
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.
16
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 listener in WAS or distributed application
IMS
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
17
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
� Leverage asynchronous flow, although appears synchronous to IMS application
– Based on OTMA Resume TPIPE/Send Only protocol function for retrieving synchronous callout requests and sending responses.
IMS
Steps to have a synchronous callout application using ICAL
STEP 1:
STEP 2:
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)
18
STEP 2:
STEP 3:
STEP 4:
Setup IMS (OTMA destination descriptor)
Setup IMS application (COBOL, PL/I, REXX, C, JAVA…..)
Setup the external application or server for callout messages
IMS
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. SOAP Gateway Appl.
19
� TCP/IP application connects to IMS Connect
� Need to understand IMS Connect and OTMA protocols
SystemRoll-your-own Appl.
� Supports the high performance IMS Callout solution, and DataPower’s hardware 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
Setting up OTMA destination descriptor in IMS PROCLIB
D destname keywords
Where:
destname is destination names and can be masked by ending in an *
� 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.
20
destname is destination names and can be masked by ending in an *
keywords are: TYPE=IMSCON
TMEMBER=name
TPIPE-name
SMEM=YES|NO
ADAPTER=adapname
CONVERTR=convname
SYNTIMER=timeout (If both ICAL & Descriptor specify timeout, the lower value is used)
D OTMDEST1 TYPE=IMSCON TMEMBER=HWS1 TPIPE=TPIPE1 SYNTIMER=500 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
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
For example: UPDATE OTMADESC NAME(OTMDEST1) SET(SYNTIMER(800))
QRY OTMADESC NAME(OTMDEST1) SHOW(ALL)
21
– CREATE OTMADESC
– UPDATE OTMADESC
– QUERY OTMADESC
– DELETE OTMADESC
IMS
Prepare your IMS application for the DL/I ICAL
The format of the ICAL call for a synchronous callout request:
22
>>-ICAL--aib---request_area---response_area-----------------><
IMS
COBOL Application with ICAL
Descriptor name
Request Area Length
Response Area Length
ICAL
AIB
23
Timeout
Response Area Length
Output return codes
IOAreas
IMS
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 100 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
//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 010000 00050
01000
L DATA HELLO FROM IMS
E OK
24
� 47-51 The response area length nnnnn The length of the response area for the output message (ICAL). Our example is 1000 bytes
--------------------------------------------------------------------------------
SEGMENT =(HELLO FROM IMS )
................................................................................
CALL=ICAL
SEGMENT =(HELLO FROM WS )
COMP RET CODE=OK
IOPCB LTERM= RET CODE= RACFUSER=PSAPP99 .
0003 0003 0000
AIB BLOCK AIBOALEN = 0002, AIBOAUSE = 0006, RETURN CODE = 0000, REASON
IMS
25
IMS
WebSphere and IMS TM Resource Adapter
� 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
26
WAS/WPS/WTX/WMB/WESB
IMS TMIMS TM
resourceresource
adapteradapter
WebService
TCP/IP
WebComponent
EnterpriseBean
IMS
Connect
IMS DB *
IMS
IMS App
Rational Application
Developer (RAD) or
WebSphere Integration
Developer (WID)
IMS app
Source
(COBOL, PLI,
C, MFS)
Generates
* Binary, text or XML data
IMS
27
IMS
Synchronous Callout Flow
IMS
IMS App1
z/OS
z/OS, zLinux, Win, AIX etc..
DL/I ICALDescriptor nameTimeout
IMS Enterprise Suite SOAP Gateway Server
IMS
Connect
Receive Callout Request in XML
Web
Service
A
XML
Adapter
Msg1
Msg2
TPIPE
Send ACK
1
2
3
5
Development & Runtime Environment
4
28
Send Callout Response in XML
XML
Converter67
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
29
IMS
IMS Synchronous Callout Overview for RYO client
RYO Application
1
IMS Connect
z/OS
IMS
IMS Application
Initiating Client
Resume TPIPE TPIPE1
Request
TPIPE TPIPE1
HWS1
OTMA Descriptor
3030
ACK
Response
3
4
2 ICAL SENDRECV OTMDEST1HELLO FROM IMSHELLO FROM IMS
Request
HELLO FROM RYO
HELLO FROM RYO
OTMDEST1TPIPE1HWS1
IMS
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
31
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
32
IMS
IMS Connect API - Overview
IMS Connect
API
Client
Application IMS Connect
API
Client
Application
IMS Connect
Client Application
IMS Connect
Windows or z/OS
O
T IMS AppIMS App
z/OS
33
Connect
API
T
M
A
IMS AppIMS App
Connection
And
TMInteraction
property
files
IMS
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
34
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
35
IMS
Inbound / Outbound DataPower flow for IMS Callout
DataPower XI52, XI50B, XB62
IMS
Ca
llou
t Fro
nt S
ide
Ha
nd
ler
Transformation
Request
Inbound Rule
IMS V12
IMS
application
IMS
Connect
36
Response
Multi-Protocol Gateway
Transformation
IMS
Ca
llou
t Fro
nt S
ide
Ha
nd
ler
Outbound Rule
application
..
ICAL
(synchronous)
TPIPE
Serv
ices
WS
Proxy
IMS
Solution Highlights
• The IMS callout connection is a DataPower “Front SideHandler” that can retrieve IMS callout messages and sendresponse data.
• The handler internally creates one or more IMS Connect dedicated persistent socket connections to the host system, using Enterprise Suite V2.2 IMS Connect API in Java.
3737
using Enterprise Suite V2.2 IMS Connect API in Java.
• The handler communicates with IMS Connect via a new DataPower dedicated user message exit, HWSDPWR1.
• For shared queue environment, user can choose to create multiple IMS Callout connections, one for each IMS datastore.
IBM Confidential
®
IMS
Synchronous program switch in IMS V13
© 2013 IBM Corporation
IMS
Synchronous Program Switch
� New capability that enhances the DL/I ICAL support
– Allows an IMS application program to synchronously call and wait for a reply from another IMS application program
• Within the calling program’s UOW
IMS dependent WebSphere
39
Database
IMS DB
services
IMS dependent
regionIMS TM
services
MPP, JMPIFP, BMP,
JBP
OTMA
Application
Program
ICALIMS SOAP GATEWAY
IMS
Connect
TCP/IP
user-written Client
WebSphere
IMS TM resource adapter
IMS
Synchronous Program Switch…
� Benefits
– Modernization of the IMS application infrastructure
• Provides an internal service flow of IMS transactions to complete a business process
– In the same IMS or a different IMS
– Implementation of a Process Server or Broker inside IMS
40
– Implementation of a Process Server or Broker inside IMS
• Reduces unnecessary network traffic when accessing multiple applications
in the same IMS or IMSplex
WASApplication
WASIMS
Connect
IMS
MPPx
MPP4
MPP2
MPP3
ICALICALICALICAL
WASApplication
WASIMS
ConnectIMS
MPP4
MPP2
MPP3
MPP1
MPP1
®
IMS
Calling out from IMS applications:
Best Practices
© 2013 IBM Corporation
IMS
Choose the asynchronous callout method to avoid tying up IMS regions while the callout request is processed
Sync Callout Response
Callout RequestIMS Application 1
Async: ISRT ALTPCBSync: ICAL
42
Async Callout Response
IMS Application 2
IMS
Evaluate if the two-phase commit process is needed to ensure data
consistency for your callout application
z/OS Resource Manager
IMS transaction
Business Logic X
GettingRequest
IMS
z/OS Apps & Data
43
Orchestration
Logic X
Sending Answer
IMS
Business Logic Y DB2
IMS
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 IMS strategic direction)
44
� Using ICAL DL/I call (This is the IMS strategic direction)
IMS
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.
45
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
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
46
� 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
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.
47
IMS applications.
®
IMS
Case Study
© 2013 IBM Corporation
IMS
IMS Callout Project for a customer in Europe
� New Credit card package
– New services in the distributed environment to be called from IMS existing Apps
� POC phase
– Tried synchronous callout first, then tried the asynchronous callout to MQSeries
� Evaluation phase – 1st approach: Synchronous integration of new services in IMS Applications
49
– 1st approach: Synchronous integration of new services in IMS Applications
• Pros: Easier for the application development
• Cons: More difficult to operate with timeout management, longer region occupancy, potential IMS queuing for new requests
– 2nd Approach: Existing IMS Apps calling new services Asynchronously
• Pros: used by many customers, almost no affect to IMS system
• Cons: Change in the end to end view of business IMS transaction
� Final decision
– They chose the asynchronous callout method.
®
IMS
Summary
© 2013 IBM Corporation
IMS
FunctionMethod
AsynchronousCommunication
Synchronous Communication
CoordinatedCommit and rollback
IMS program switch
�APPC/CPI-C � �z/OS TCP/IP stack
�ESAF to MQ
Table 1. Key functionalities supported by each callout method
51
ESAF to MQ
� �ESAF to DB2 for z/OS
� �ALTPCB OTMA
�ICAL call
�
IMS
Table 2. By looking at some of the supported service providers and environments
TargetMethod
IMS Appl.
APPC/CPI-C Appl.
DB2 for z/OS Appl.
MQ Series Appl.
Websphere Appl. with TMRA
TCP/IP Appl.
SOAP Appl. with Soap Gateway
Datapower Appl.
IMS program switch
�APPC/CPI-C �z/OS
�
52
z/OS TCP/IP stack
�ESAF to MQ �ESAF to DB2 for z/OS
�ALTPCB OTMA � � � �ICAL call
� � � � �
* The IMS application calls the service provider indirectly.
IMS
Summary of callout highlights
1. When choosing a synchronous or asynchronous callout method, consider your needs for scalability and performance.
2. The ICAL DL/I call has been available for synchronous callout since IMS Version 10.
3. All messages that use the ICAL callout method go through IMS Connect.
53
IMS Connect.
4. IMS Version 13 expands the ICAL DL/I call to support synchronous program switch function to “call out” to other IMS application program.
