IMS Nordic RUG IMS Callout - IMS UG May 2013 Stockholm
-
Upload
ibm-ims -
Category
Technology
-
view
431 -
download
0
description
Transcript of IMS Nordic RUG IMS Callout - IMS UG May 2013 Stockholm
© 2013 IBM Corporation
Integrating IMS Applications in the Enterprise
Betty Patterson – May 2013
IMS Chief Architect
IBM Silicon Valley Laboratory
© 2013 IBM Corporation2
Availability. References in this presentation to IBM products, programs, or services do not imply that they will be available in all countries in which IBM operates.
Acknowledgements and Disclaimers
© 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.
IBM, the IBM logo, ibm.com, IMS, DB2, CICS and WebSphere MQ 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
Other company, product, or service names may be trademarks or service marks of others.
The workshops, sessions and materials have been prepared by IBM or the session speakers and reflect their own views. They are provided for informational purposes only, and are neither intended to, nor shall have the effect of being, legal or other guidance or advice to any participant. 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. IBM shall not be responsible for any damages arising out of the use of, or otherwise related to, this presentation or any other materials. 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 the applicable license agreement governing the use of IBM software.
All customer examples described are presented as illustrations of how those customers have used IBM products and the results they may have achieved. Actual environmental costs and performance characteristics may vary by customer. Nothing contained in these materials is intended to, nor shall have the effect of, stating or implying that any activities undertaken by you will result in any specific sales, revenue growth or other results.
© 2013 IBM Corporation3
IMS SOA Integration Suitehttp://www.ibm.com/software/data/ims/toolkit/
Modernize, reuse and expand IMS transaction
Open and direct access to IMS Data
IMSTM
IMSDB
C
Java
MFS
DL/I Data
IMS ConnectAPI
IMS Enterprise SuiteSOAP
Gateway
IMS TMResourceAdapter
IMS MFS Web Solutions
IMS Web 2.0Solutions
XML Data
PL/ICOBOL
Full Java EE, web service and SOA access
to and from IMS transactions
Light-weight web service provider and
consumer solution for IMS
Simplify use of writing IMS Connect User-
written applications
Modernize, web and SOA enabled MFS-
based IMS transactions
Create feeds and integrate IMS
transactions with Web 2.0 app
WebSphere Write and run IMS application in Java
to leverage new skills
IMS Web 2.0Solutions
IMS Open DB and Universal JDBC drivers
IMS Explorer for Dev
IMS Universal DB Resource
Adapter
WebSphere
Create feeds and integrate IMS data with Web 2.0 app
Access IMS Data using SQL directly from System z and distributed platforms via IMS Connect
Store and Retrieve XML data from IMS DB
Provide visual view of IMS data and generate metadata classes for new application development
Access IMS Data from Java EE app
IMS DBWeb Services
Expose an IMS database query as Web Services
No additional cost for IMS license usersLeverage open standards
© 2013 IBM Corporation4
or Print utilityIMS Performance Analyzer IMS Problem Investigator
Inbound Connectivity to IMS TM
IMS Connect
OTMA
IMS DB &XML DB
IMS
WebSphere ServersWAS, WESB, WTX,
WMB, BPM
IMS SOAP Gateway
WebSphere DataPower
Connect API (Java, C)
WMQMQ Client
RYO Client
MobileWeb
ServiceConsumer
IMS TM Resource Adapter
WAS – WebSphere Application ServerWOLA - WebSphere z/OS Optimized Local AdaptersWESB – WebSphere Enterprise Service BusWTX – WebSphere Transformation ExtenderWMB – WebSphere Message BrokerBPM - IBM Business Process Manager (BPM) Advanced
IBM MashupCenter /
WebSphere sMash
Web 2.0 Client
DB2
WOLA
JCA
JMS or MQ API
SOAP over IP
WMB & DataPower
MQ IMS Bridge
MQ Trigger Monitor
IMSIMSCONNECTCONNECTExtensionsExtensions
Archivejournal
XCF
TCP/IP
Cloud
IMS APP IMS
Catalog
© 2013 IBM Corporation5
IMS Connect
OTMA
IMS DB &XML DB
IMS
DB2
WOLA
Outbound Connectivity from IMS TM Asynchronous and synchronous capabilities
IMS TM Resource Adapter
WAS
IMS SOAP Gateway
WMQMQ Server
RYO Server
Web ServiceProvider
Event ProcessingWBE, WBM
WAS – WebSphere Application ServerWOLA - WebSphere z/OS Optimized Local AdaptersWBE – WebSphere Business EventsWBM – WebSphere Business MonitorWMB – WebSphere Message BrokerRYO Server - .Net, BizTalk, Oracle SP, SAP, PayPal services, and any application server, etc.
WMB
IMS APP IMS
Catalog
DB2 for z/OSGatewayAny DB2
Platform
WebSphereDataPower
© 2013 IBM Corporation6
IMS Callout Techniques
Asynchronous callout using insert to ALTPCB via OTMA Synchronous Callout using ICAL Asynchronous program switch Synchronous program switch (IMS 13) Callout via External Subystem Attach Facility
– DB2 Stored Procedure– WebSphere MQ – Websphere Optimized Local Adapter
User Written TCP/IP Synchronous Advanced Program-to-Program Communication (APPC)
© 2013 IBM Corporation7
IMS Callout
Enable IMS applications as Service Requesters– IMS Application can be an integration focal point in the enterprise– Interoperate with business logic outside the IMS environment
– Callout to Java EE apps (EJB and MDB) and Web Services using WebSphere Application Server and IMS TM Resource Adapter
– Callout to Web services providers (e.g. Microsoft .NET) using SOAP Gateway
– Callout to other applications
Two Flavors– Asynchronous
– Synchronous
© 2013 IBM Corporation8
Asynchronous Callout
Asynchronous Callout– IMS application invokes external applications without waiting for
response.• DL/I ISRT ALTPCB • Destination can be
– Another IMS application (program switch)– An OTMA destination
> Sent to any OTMA clients, such as IMS Connect or WMQ > Tpipe name specified via DRU exits or OTMA descriptor.
– Any response sent back is a new transaction
© 2013 IBM Corporation9
Synchronous Callout
Synchronous Callout– IMS application invokes external application and waits for the
response.• DL/I ICAL• Supports timeout capability and large messages• Secondary application is not in the same two-phase commit
scope– IMS application waits until the response is returned or the
request receives a timeout
– Callout response is sent back to the same transaction that initiated it
© 2013 IBM Corporation10
IMS Asynchronous and Synchronous Callout
Sync Callout Response
Callout Request
Async Callout Response
IMS Application 1
IMS Application 2
Async: ISRT ALTPCBSync: ICAL
© 2013 IBM Corporation11
IMS Synchronous Callout
© 2013 IBM Corporation12
IMS Synchronous Callout Overview IMS 10 added DLI “ICAL” call for synchronous callout request
Timeout support to optionally terminate callout request and free the dependent region
Enhanced IMS commands to view synchronous callout status and stop the callout processing
Support messages larger than 32K without segmentation
Provide management of the correlation of a synchronous callout request and response
Enhanced OTMA Resume TPIPE/Send Only protocol and Routing Descriptor function for retrieving synchronous callout requests and sending responses
© 2013 IBM Corporation13
IMS application - DL/I ICAL
CALL 'AIBTDLI' USING ICAL, AIB, REQ-AREA, RESP-AREA.
where:• ICAL is the call verb (available on AIBTDLI only) and SENDRECV is the sub-function code• REQ-AREA is the Request data area for sync callout• RESP-AREA is the Response data area for returned data
Note: REQ-AREA and RESP-AREA do not specify LLZZ, data can be > 32K
For example:
ICAL
IOAreas
© 2013 IBM Corporation14
IMS application - DL/I ICAL …• AIB
– AIBSFUNC = SENDRECV– AIBRSNM1 = 8 byte OTMA Descriptor name– AIBRSFLD = Timeout value
• 4 byte field for time value in 100th seconds. System default is 10 sec.
– AIBOALEN = Request area length• As an input parameter: 4 byte field contains the length of the request area• As an 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• As an input parameter: 4 byte field contains the length of the response
area• As an 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.
© 2013 IBM Corporation15
IMS application - DL/I ICAL…
Descriptor name
Timeout
Request Area LengthResponse Area Length
Output return codes
AIBFor example:
© 2013 IBM Corporation16
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=5000
OTMA Destination Routing Descriptor IMS OTMA Destination Routing Descriptors externalize the routing definitions and
specifications for callout messages without IMS user exits. It is read and initialized at IMS startup.
– Use ‘D’ descriptor type in DFSYDTx member of IMS.PROCLIB.
• IMS 11 provides Type-2 UPDATE commands to dynamically create, update, or query the descriptors
UPDATE OTMADESC NAME(OTMASYN) SET(SYNTIMER(5000))
For example:
For example:
D SOAPGW1 TYPE=IMSCON TMEMBER=HWS1 TPIPE=HWS2SOAPD SOAPGW1 ADAPTER=XMLADPTR CONVERTR=XMLCNVTR SYNTIMER=2000
© 2013 IBM Corporation17
Callout with IMS TM Resource Adapter
© 2013 IBM Corporation18
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 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
© 2013 IBM Corporation19
Callout to WebSphere Java EE application using IMS TM Resource Adapter
A Java Message-driven bean (MDB) can be written to listen for callout requests from IMS via IMS TM Resource Adapter
IMS TM Resource Adapter implements the JCA Inbound specification and deliver callout messages to MDB using standardinterfaces– Hides the low-level IMS Connect and OTMA protocols
– Use Resume Tpipe Auto (with alternate client ID) with Wait-forever
– Handles the correlation token internally
– User specifies the callout properties using the ActivationSpec
– Can process responses from MDBs concurrently
– Auto reconnect to IMS Connect
© 2013 IBM Corporation20
Callout with IMS TM Resource Adapter Callout to WAS MDB using IMS TM Resource Adapter
– Support JCA Inbound– Retrieve Asynchronous callout, Synchronous callout messages as well
as Asynchronous output messages from IMS and deliver to WAS MDB
WebSphere Application Server
IMS Connect
z/OS
IMSIMS Application
2 ICAL SENDRECV ICODEST1HELLO FROM IMS
HELLO FROM WEBSPHERE MDB
TPIPE ICOPIPE1
Message Driven Bean (MDB)
Response
1
3
Activate
HELLO FROM IMSonMessage
HELLO FROM WEBSPHERE MDB
IMS TM
Resource Adapter
Initiating Client
ICODEST1ICOTPIPE1HWS1
OTMA Descriptor
Web Service, EJB or MDB
HWS1
© 2013 IBM Corporation21
Callout with IMS SOAP Gateway
© 2013 IBM Corporation22
IMS Enterprise Suite SOAP Gateway Overview A Light-weight Web Service solution for IMS without the need of
a Java EE server
Integrates IMS assets into the Service-Oriented Architecture (SOA)
Provides end-to-end interactions between IMS transactions and web services clients in an On Demand environment
Enables IMS as Provider and Consumer of Web Services
Secure
Tooling support– Utilizes Rational Developer for System z tooling to create converters
for transforming XML messages to IMS messages and vice versa
– No need to change existing IMS application code
© 2013 IBM Corporation23
IMS application development and modernization: Rational Developer for System z (RDz) Eclipse-based application development tool for modernizing and developing System z
applications– COBOL, PL/I, C, C++, HL Assembler, Java
– Supports IMS, CICS, Batch, USS, etc..
– Interactive access to z/OS system
– Access PDS and run JCL from your workstation
Premier IBM Integrated Development Environment for development and test of IMS applications – Drag-and-drop code snippet function for IMS DLI calls
Also supports IMS SOA enablement– Enables CICS and IMS applications for Web Services
and SOA
– Built-in wizard for SOAP Gateway and Web 2.0
– Generate XML COBOL/PLI converters for XML transformation
– Generate WSDL, correlator files for Web Services access
© 2013 IBM Corporation24
ExecutionExecution
GenerationGeneration
<SOAP><LL><ZZ><DATA>
SOAP clientsXML
Adapter
AdapterTask
Manager
XMLConverters
IMS ConnectIMS
IMSApp
z/OS
LLZZTRCDDATA
LLZZDATA
TCP/IP
<LL><ZZ><TRCD><DATA>
<LL><ZZ>DATA>
SOAP Gateway
HTTP SOAP
endpoint
Gatewayconnector
SOAPprocessor
UDDI Registry
Java Client
.NET Client
HTTP/SOAP
<SOAP><LL><ZZ><TRCD><DATA>
RD/z Bottom-Up Wizard
WSDL
CorrelatorFile
Publish
RD/zGenerate
Existing COBOLCopybook
XMLDocument
Log
…/server/logs/imssoap.log
Development Environment
Development environment
Runtime environment
IMS SOAP Gateway Development & Runtime (Provider)
<XMLDocument>
<XMLDocument>
© 2013 IBM Corporation25
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
6 7
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
© 2013 IBM Corporation26
Callout with SOAP Gateway – Generate artifacts Use Rational Developer for System z (RDz) to generate callout artifacts
– Meet-in-the-middle• Maps WSDL with COBOL data structures
– Generates XML Converters • Runs in IMS Connect• Converts callout request from bytes to XML and vice versa
– Generates Correlator file• Used by SOAP Gateway to identify which Web Service to invoke at
runtime and specify callout properties– Deploy WSDL
• Contains URL address for the outbound web service
© 2013 IBM Corporation27
COBOL Application with ICAL
Descriptor name
Timeout
Request Area LengthResponse Area Length
Output return codes
ICAL
AIB
IOAreas
© 2013 IBM Corporation28
Asynchronous Callout with Response
IMS
IMS App1
z/OS
z/OS, zLinux, Win, AIX etc..
:ISRT ALTPCB IMSSOAP1
SYNCPT Starts..
IMS Enterprise Suite SOAP Gateway Server
IMS Connect
IMS App2
WebService
A
InitiatingClient
XMLAdapter
Msg1Msg2
TPIPE
DFSYDTxIMSSOAP1 TYPE = IMSCON TMEMBER=SM01TPIPE=TP3 SMEM=YADAPTER = HWSXMLA0CONVERTR=SOAPIT
Send ACK
SOAPXMLConverter
Connection Bundle(CBA)TPIPE = TP1,TP3…
1
2
3
46
78
Runtime Environment
5
Receive Callout Request in XML
Send Callout Response in XML
© 2013 IBM Corporation29
IMS Application
Existing Business Logic
Business Event support with SOAP Gateway IMS application sends out a business event data using ISRT ALTPCB
call RDz generates artifacts to convert IMS business events data to
WBE/WBM formats SOAP Gateway emits business events data asynchronously to WBM
and WBE
CapturePoint
DEST1EV1HWS1
Descriptor
IMS Connect
IMSOTMA
TPIPE EV1
Send Event
WebSphere Business Events
BytesEvent Action
WebSphere Business Monitor
SOAP Gateway
XMLPayload SOAP
XML Adapter
XML Converter
REST
WebSphere Application Server
WSDL
ISRT ALTPCB
IBM Confidential
© 2013 IBM Corporation30
Managing Callout
© 2013 IBM Corporation31
Enhanced IMS commands /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
/DIS TMEMBER TPIPE – WAIT-S (WT-S)
• The transaction pipe is waiting for an ACK or NAK for a synchronous callout message
/DIS TMEMBER TPIPE SYNC– Display the detailed sync callout
message count and status
/PSTOP – Clear the wait in the region
– Dequeues synchronous callout messages from the TPIPE
/STOP REG ABDUMP– Clear the wait in the region and
terminate the application program
/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
Note: The stop commands return AIBRETRN = 100 and AIBREASN = 10C to ICAL
© 2013 IBM Corporation32
Sample Commands outputAfter ICAL request is sent …
RegionStatus
TPIPEStatus
© 2013 IBM Corporation33
Some Callout Considerations Monitor synchronous callout processing
Minimize resource contention– Try to issue ICAL requests before obtaining locks
Define appropriate number of dependent regions– You may want additional transaction classes to segregate workloads
Define timeout values for ICAL and/or OTMA descriptors
Manage commit, backout and timeout -- UOWs are independent
Multiple response messages from synchronous program switch
© 2013 IBM Corporation34
IMS 13 Callout Enhancements
© 2013 IBM Corporation35
Synchronous Program Switch Extend IMS Synchronous Callout to invoke another IMS Application
– Synchronous flows use DL/I ICAL– Asynchronous flows still use DL/I ISRT
OTMA Descriptor defines the destinationBenefits
– Provides a single DL/I call to request a synchronous service regardless of where that service resides
– Simplifies integration and improves usability
ICAL DEST1
ICAL TRANB
TRANAIMS CTL Region
IMS Connect
WebSphereIMS TMRA
IMS SOAPGateway
TCP/IPRYO pgm
OTMA
MSG-Q
Destination Descriptor
TYPE(IMSCON)
TRANBGU IOPCB
ISRT IOPCB
Destination Descriptor
TYPE(IMSTRAN)
12
3
4
56
7
GU, IOPCB
Applications can issue multiple ICALs to different destination TYPEs
Synchronous calloutSynchronous program switch
WebSphereDataPower
© 2013 IBM Corporation36
Retrieve Truncated Messages New ICAL “RECEIVE” subfunction code
– With an expanded response area• Retrieves the response message after an ICAL “SENDRECV” is
issued with an inadequate response area specification and gets partial data (AIB RC X’100’, AIB RS X’00C’)
– IMS keeps a copy of the entire response message in the control region private storage• Until a subsequent ICAL “SENDRECV”, syncpoint, or application
termination Benefit
– Provides the ability to complete the retrieval of a reply message that had been truncated due to a too small output area • Without having to re-issue a complete ICAL “SENDRECV” and
associated network transmission costs
© 2013 IBM Corporation37
Async Callout to WebSphere MQ via MQ Bridge OTMA Descriptor enhancements
– New TYPE=MQSERIES to define WebSphere MQ destination• Provides asynchronous callout and messaging support (DL/I ISRT ALTPCB)
– New option to allow exits to be called to override descriptor• Applies to all destination descriptors
Benefits– Eliminates need to write an OTMA user exit to recognize an MQ destination – Simplifies integration and improves usability
IMS Application
WebSphereMQ
IMSOTMA
© 2013 IBM Corporation38
Thank You!
© 2013 IBM Corporation39
Additional Reference Material
© 2013 IBM Corporation40
Diagnostics for Synchronous Callout The following diagnostics information is logged in the IMS log records:
– Synch Callout requests and responses – Logged with OTMA 6701 ID=YOUT (for request) and ID=YRSP (for response)
• Matched by Sync Callout CORTKN, also includes LCRE token• Note: no 01 or 03 log records since ICAL does not use IMS message queues
– ICAL timeout• Logged with 67D0 (includes LCRE token)
– Sync Callout late reply• Logged with 6701 ID=YNAK
– Resume TPIPE • Logged with 6701
– Client ACK / NAK response to Sync Callout request• Logged with OTMA 6701 ID=YACK/YNAK (includes CORTKN)
– IMS Connect generated NAK (when external app or server went away or timed out)
• Logged with OTMA 6701 ID=YNAK (includes LCRE token)
© 2013 IBM Corporation41
Callout Techniques
© 2013 IBM Corporation42
© 2013 IBM Corporation43
© 2013 IBM Corporation44
© 2013 IBM Corporation45
© 2013 IBM Corporation46
© 2013 IBM Corporation47
© 2013 IBM Corporation48
© 2013 IBM Corporation49
Callout with IMS TM Resource Adapter
© 2013 IBM Corporation50
IMS TM Resource Adapter
Rapid IMS SOA enablement with IBM tooling - Rational Application Developer (RAD)
Easy-to-use application development tool
Graphical and source editors
Modernize your IMS application– Provider
• Parse existing IMS application source and generates Web app, EJBand Web Service
• No need to change IMS application
– Consumer• Generate MDB/EJB to
consume IMS callout requests
IMS App Source(COBOL, PLI, MFS, C)
*Also available in WID, RDz, RSA
© 2013 IBM Corporation51
Callout with IMS TM RA – Sample MDB codepublic class IMSCalloutIVPMDBBean implements javax.ejb.MessageDrivenBean,
com.ibm.j2ca.base.ExtendedInboundListener {::
public javax.resource.cci.Record onMessage(javax.resource.cci.Record arg0, javax.resource.cci.InteractionSpec arg1)throws javax.resource.ResourceException {
SYNCCALLOUTREQUEST request = new SYNCCALLOUTREQUEST();SYNCCALLOUTRESPONSE response = new SYNCCALLOUTRESPONSE();
// Requestrequest.setBytes(((IMSInputStreamRecord)event).getBytes());
System.out.println("Synchronous callout request from IMS: " +request.getSync__callout__request__str());
// Responseresponse.setSync__callout__response__str("HELLO FROM WEBSPHERE MDB");
System.out.println("Synchronous callout response from WAS MDB: " + response.getSync__callout__response__str());
return response;}
}
© 2013 IBM Corporation52
TPIPEName
IMS Connect connection info and Datastore
name
Callout with IMS TM RA – Deploy the RAR/Configure ActivationSpec
© 2013 IBM Corporation53
Callout with IMS TM RA – Deploy the MDB
© 2013 IBM Corporation54
Callout with IMS SOAP Gateway
© 2013 IBM Corporation55
Descriptor, SOAP configurationOTMA Descriptor
Descriptor name XML ConverterXML Adapter
TPIPE
SOAP Deployment
External WSDL
Connection Bundle
© 2013 IBM Corporation56
SOAP Configuration …
Connection Bundle
SOAP Properties
TPIPE
Thread Policy
© 2013 IBM Corporation57
Callout with Roll Your Own Application
© 2013 IBM Corporation58
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
© 2013 IBM Corporation59
RYO Application
ACK
Response
1
3
4
IMS Connect
z/OS
IMS
IMS Application
2
Example: Callout with RYOInitiating Client
Resume TPIPE TPIPE1
ICAL SENDRECV OTMDEST1HELLO FROM IMSHELLO FROM IMS
Request
TPIPE TPIPE1
HELLO FROM RYOHELLO FROM RYO
OTMDEST1TPIPE1HWS1
HWS1
OTMA Descriptor
© 2013 IBM Corporation60
Callout with RYO – Sample codepublic byte[] retrieveCalloutRequest() {
int irmLen = 96;int totalLength = 4 + 4 + irmLen;
ByteArrayOutputStream bout = new ByteArrayOutputStream();DataOutputStream out = new DataOutputStream(bout);
out.writeInt(totalLength); // Total message lengthout.writeShort(irmLen); // IRM LLout.writeByte(3); // Architecture level 3out.writeByte(0x80); // F0 - Retrieve Sync callout only messageout.writeBytes("*SAMPL1*"); // Exit IDout.writeInt(0); // Reservedout.writeByte(0x10); // F5 - Resume Tpipe Singleout.writeByte(0x64); // Timeout - 2 minutesout.writeByte(0x10); // Persistent socketout.writeByte(0); // Reservedout.writeBytes(clientID); // Client IDout.writeByte(0); // F1out.writeByte(0x40); // F2 - Commit mode 0out.writeByte(0x01); // F3 - SyncLevel 1out.writeByte('R'); // F4 - Resume Tpipeout.writeBytes(" "); // blank tran codeout.writeBytes(datastore); // datastore idout.writeBytes(" "); // blank lterm nameout.writeBytes(userID); // user idout.writeBytes(group); // groupout.writeBytes(password); // passwordout.writeBytes(" "); // blank APPL IDout.writeBytes(" "); // blank Alt Client IDout.writeShort((short)4); // End of message LLout.writeShort((short)0); // End of message ZZ
return bout.toByteArray();}
© 2013 IBM Corporation61
Callout with RYO – Sample code …public String processCalloutRequest(byte[] messageBytes) {
ByteArrayInputStream bain = new ByteArrayInputStream(messageBytes);DataInputStream in = new DataInputStream(bain);
int msg_llll = in.readInt();
short ll = in.readShort();short zz = in.readShort();byte[] irmIDBytes = new byte[8];in.readFully(irmIDBytes);String irmID = new String(irmIDBytes,"ascii");
if (irmID.equals("*REQSTS*")) { // error// read return code and reason codethis.requestReturnCode = in.readInt();this.requestReasonCode = in.readInt();return null;
} else if (irmID.equals("*CORTHN*")) {byte[] corrBytes = new byte[ll-12];in.readFully(corrBytes);this.correlationToken = corrBytes;
}
int data_llll = in.readInt();if (data_llll <= 0) return null;
byte[] data_bytes = new byte[data_llll-4];in.readFully(data_bytes);String message = new String(data_bytes,"ascii");
byte[] csmokyBytes = new byte[12];in.readFully(csmokyBytes);
return message;}
© 2013 IBM Corporation62
Callout with RYO – Sample code …public byte[] buildCalloutResponse(String data, byte[] corrToken) {
int irmLen = 160; int totalLength = 4 + 4 + irmLen;if ((data != null) && (data.length() > 0)) { totalLength += data.length() + 4; }ByteArrayOutputStream bout = new ByteArrayOutputStream();DataOutputStream out = new DataOutputStream(bout);out.writeInt(totalLength); // Total message lengthout.writeShort(irmLen); // IRM LLout.writeByte(3); // Architecture level 3out.writeByte(0); // F0out.writeBytes("*SAMPL1*"); // Exit IDout.writeInt(0); // Reservedout.writeByte(0); // F5out.writeByte('Z'); // Timeout - No Waitout.writeByte(0x10); // Persistent socketout.writeByte(0); // Reservedout.writeBytes(clientID); // Client IDout.writeByte(0); // F1out.writeByte(0x40); // F2 - Commit mode 0out.writeByte(0x01); // F3 - SyncLevel 1out.writeByte('M'); // F4 - Sync callout responseout.writeBytes(" "); // blank tran codeout.writeBytes(datastore); // datastore idout.writeBytes(" "); // blank lterm nameout.writeBytes(userID); // user idout.writeBytes(group); // groupout.writeBytes(password); // passwordout.writeBytes(" "); // blank APPL IDout.writeBytes(" "); // blank Alt Client IDout.writeBytes(" "); // blank Adapter nameout.writeBytes(" "); // blank Converter nameout.writeBytes(" "); // blank MOD nameout.write(corrToken); // corrleation tokenout.writeInt(data.length()+4);out.writeBytes(data); // Dataout.writeShort((short)4); // End of message LLout.writeShort((short)0); // End of message ZZreturn bout.toByteArray();
}
© 2013 IBM Corporation63
IMS Connect API Provides simplified API to build User-written 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