®IMS      What is New in IMS Callout                 Jack Yuan           jackyuan@us.ibm.com                              ...
IMSWhen IMS was created in 1968…..                                  2
IMSToday, IMS is everywhere...                              3
IMSIMS for future….                   Customers running IMS have a variety of computer hardware and network               ...
IMSAgenda Seven IMS callout techniques Using DL/I ICAL call for SendReceive for callout Using DL/I ICAL call for Receive U...
® IMSOverview of 7 IMS callout techniques                                © 2012 IBM Corporation
IMS      7
IMS      8
IMS      9
IMS      10
IMS      11
IMS      12
IMS      13
®IMS      DL/I ICAL call for SendRecv                                    © 2012 IBM Corporation
IMS   DL/I ICAL support provided synchronous callout capability to   resources outside IMS                                ...
IMSIMS Synchronous Callout Overview    New DLI ICAL call for synchronous callout request    Support messages larger than 3...
IMSV10 Synchronous Callout with Multiple IMS Applications           WebSphere                             IMS        Appli...
IMSSynchronous Callout response can be back from a different IMS Connect orIMS Connect DataStore                       IMS...
IMSRestrictions    No distributed 2PC support    IMS userid and password would not be propagated by IMS to external server...
IMSIMS application - DL/I ICAL           CALL AIBTDLI USING ICAL, AIB, REQ-AREA, RESP-AREA.           where:           • I...
IMSIMS application - DL/I ICAL …       AIB        – AIBSFUNC = SENDRECV        – AIBRSNM1 = 8 byte OTMA Descriptor name   ...
IMSIMS application - DL/I ICAL…      For example:AIB                                       Descriptor                     ...
IMSOTMA Destination Routing Descriptor  IMS 10 OTMA Destination Routing Descriptors externalize the routing  definitions a...
IMSDFSDDLT0   DFSDDLT0 supports ICAL    S1111 1 1 1  1IOPCB         AIB    L        ICAL SENDRECV OTMDEST1 005000 00028 00...
IMSIMS application can callout to external application  IMS application can callout to one of the following:  – User-writt...
IMSCallout with RYO – Flow diagram                                                         Initiating Client              ...
IMSCallout with IMS TM RA – Flow Diagram (MDB)                                                                            ...
IMSCallout with IMS TM RA – Flow Diagram (EJB)                                                                            ...
IMS  Callout with IMS SOAP Gateway – Flow Diagram                                                                         ...
IMSEnhanced IMS commands   /DISPLAY ACTIVE REGION                         /PSTOP                                          ...
IMS/DISPLAY TMEMBER TPIPE SYNC      Since every “Resume Tpipe on Hold Queue” request is remembered and tracked by OTMA,   ...
IMSDiagnostics for Synchronous Callout   Incorrect OTMA descriptor name specified in the ICAL AIB   IMS Connect and IMS no...
IMSA 6701 log record for a callout message, and a 67D0 log record for time-out                                            ...
®IMSDL/I ICAL for Receive in IMS V13                              © 2012 IBM Corporation
IMSSupport for Truncated Messages New “RECEIVE” subfunction code – With an expanded response area   • Retrieves the respon...
IMSICAL subfunction RECEIVEFormat:  • >>-ICAL--aib--response area-----------------------------------------><AIB– AIBSFUNC ...
IMSICAL sub-function RECEIVE … Usage example:    ICAL --aib—request area, response area     AIBSFUNC (SENDRECV)     AIBOAU...
IMSICAL sub-function RECEIVE … ICAL “RECEIVE” is only valid if previous ICAL “SENDRECV” failed Response data is available ...
® IMSSynchronous program switch in IMS V13                                 © 2012 IBM Corporation
IMSSynchronous Program Switch New capability that enhances the DL/I ICAL support – Allows an IMS application program to sy...
IMSSynchronous Program Switch… Benefits – Modernization of the IMS application infrastructure   • Provides an internal ser...
IMSHighlights Automatic invocation of OTMA – Without requiring OTMA to be defined or commands to be issued – New OTMA dest...
IMSRestrictions No ICAL support for BMP or JBP applications running in DBCTL environments – ICAL is part of the IMS TM cap...
IMSRestrictions … Exit routines – DFSYIOE0 (OTMA Input/Output Edit Exit routine)   • Not called when processing synchronou...
IMSSynchronous Program Switch – The Details An enhancement to the DL/I ICAL to invoke another IMS application – In the sam...
IMSThe DL/I ICAL callSame Format>>-ICAL--aib--request_area--response_area----------------------><Call Name   DB/DC   DBCTL...
IMSThe DL/I ICAL Call … Examples of common Return codes for synchronous program switch – Full list in the IMS documentatio...
IMSThe DL/I ICAL Call … Continues to use OTMA Destination Routing Descriptors    – Which externalize the routing definitio...
IMSOTMA destination routing descriptor for DL/I ICAL TYPE= IMSTRAN  – Required for synchronous program switch requests Sup...
IMSOTMA destination routing descriptor for DL/I ICAL … Type-2 commands can also be used to update, create, delete, or quer...
IMSOTMA Support for Synchronous Program SwitchesNon-XCF related OTMA services are used– Internal invocation of OTMA servic...
IMSOTMA Support for Synchronous Program Switches …                                                  52
IMSIMS Commands /DIS ACTIVE REGION – Displays the target transaction for the synchronous program switch – Displays the cal...
IMSIMS Commands …  /PSTOP REGION rgn# SYNC tran name …  – Allows a program in a wait state to terminate  /STOP TMEMBER DFS...
IMSMessages and Status Codes Messages – DFS4687E ERROR PROCESSING SYNC PROGRAM SWITCH   • Provides information about a pro...
IMSSecurity Considerations Security for ICAL is similar to CHNG/ISRT DLI calls – Based on transaction security specificati...
IMSSecurity Considerations …    If the ICAL is authorized to do the synchronous program switch …         • Even when DFSYI...
IMSShared Queues Support  IMS leverages the APPC/OTMA XCF shared queues (SQ) function  – For both request and response mes...
IMSMSC Support IMS supports sending an ICAL request to an MSC back-end system – MSC/VTAM – MSC/TCPIP with IMS Connect (int...
IMSTransaction expiration for the target transaction  Transaction expiration for targets of synchronous program switches  ...
IMSApplication Examples Applications can issue multiple ICALs to different destination TYPEs – Synchronous callout – Synch...
IMSApplication Examples…  The IMS application environment supports recursive requests  – ICAL to ICAL    • Across a single...
IMSMigration/Setup Considerations For Non-shared queues – Synchronous program switch is a base function of IMS 13 For Shar...
IMS      64
Upcoming SlideShare
Loading in …5
×

What's new in ims callout

1,237 views

Published on

Published in: Technology
0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total views
1,237
On SlideShare
0
From Embeds
0
Number of Embeds
3
Actions
Shares
0
Downloads
35
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

What's new in ims callout

  1. 1. ®IMS What is New in IMS Callout Jack Yuan jackyuan@us.ibm.com © 2012 IBM Corporation
  2. 2. IMSWhen IMS was created in 1968….. 2
  3. 3. IMSToday, IMS is everywhere... 3
  4. 4. IMSIMS for future…. Customers running IMS have a variety of computer hardware and network configuration installed, typically employing IMS as a repository for information. Customers are regarding IMS as one of their Enterprise resource planning (ERP) application platforms which must integrate internal and external management information across the entire organization, embracing finance/accounting, manufacturing, sales and service, customer relationship management, etc. In some scenarios, IMS acts as the client and needs to make callout requests to obtain information from the external applications or systems. 4
  5. 5. IMSAgenda Seven IMS callout techniques Using DL/I ICAL call for SendReceive for callout Using DL/I ICAL call for Receive Using DLI ICAL call for synchronous program switch 5
  6. 6. ® IMSOverview of 7 IMS callout techniques © 2012 IBM Corporation
  7. 7. IMS 7
  8. 8. IMS 8
  9. 9. IMS 9
  10. 10. IMS 10
  11. 11. IMS 11
  12. 12. IMS 12
  13. 13. IMS 13
  14. 14. ®IMS DL/I ICAL call for SendRecv © 2012 IBM Corporation
  15. 15. IMS DL/I ICAL support provided synchronous callout capability to resources outside IMS z/OSWebSphere IMS MPP/JMP/IFP/BMP/JBPIMS TM resource adapter Application OTMA TM/CTL Program Services ICAL DB IMS IMS SOAP GATEWAY Services Connect TCP/IP OTMA OTMA Database user-written Client Descriptor Descriptor 15
  16. 16. IMSIMS Synchronous Callout Overview New DLI ICAL call for synchronous callout request Support messages larger than 32K without segmentation – No need to build data in LLZZ format Leverage the OTMA destination descriptor function to point to the IMS Connect for the callout message Does not go through IMS Message Queue, and the synchronous callout message/response are not recovered. Timeout support to optionally terminate callout request and free the dependent region Provide management of the correlation of a synchronous callout request and response Enhanced IMS commands to view synchronous callout status and stop the callout processing Enhanced OTMA Resume TPIPE/Send Only protocol function for retrieving synchronous callout requests and sending responses 16
  17. 17. IMSV10 Synchronous Callout with Multiple IMS Applications WebSphere IMS Application Server EJB / IMS TM MDB Resource Adapter IMS Application 1 OTMA Descriptor 1 IMS Connect IMS Roll-your-own IMS Application 2 Connect OTMA Application Descriptor 2 OTMA IMS Application 3 Descriptor 3 IMSWeb Service SOAP Provider Gateway Send flow Receive flow 17
  18. 18. IMSSynchronous Callout response can be back from a different IMS Connect orIMS Connect DataStore IMS Connect #1 TPIPE1 TCP/IP Client IMS IMS Application Application DLI ICAL call w/ OTMA Send-Receive Descriptor TPIPE1 IMS Connect #2 Send flow Receive flow 18
  19. 19. IMSRestrictions No distributed 2PC support IMS userid and password would not be propagated by IMS to external server Shared queues environment is supported only if FE=BE 19
  20. 20. IMSIMS application - DL/I ICAL CALL AIBTDLI USING ICAL, AIB, REQ-AREA, RESP-AREA. where: • ICAL is new call verb (available on AIBTDLI only) and SENDRECV is the new 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: ICALIOAreas 20
  21. 21. IMSIMS application - DL/I ICAL … AIB – AIBSFUNC = SENDRECV – AIBRSNM1 = 8 byte OTMA Descriptor name – AIBRSFLD = Timeout value • 4 byte field for time value 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 x100, AIB reason code x00C‘). – 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. 21
  22. 22. IMSIMS application - DL/I ICAL… For example:AIB Descriptor name Request Area Length Response Area Length Timeout Output return codes 22
  23. 23. IMSOTMA Destination Routing Descriptor IMS 10 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. D destname keywords Where: 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) For example: D OTMDEST1 TYPE=IMSCON TMEMBER=HWS1 TPIPE=TPIPE1 SYNTIMER=500 D SOAPGW1 TYPE=IMSCON TMEMBER=HWS1 TPIPE=HWS2SOAP D SOAPGW1 ADAPTER=XMLADPTR CONVERTR=XMLCNVTR SYNTIMER=200 IMS 11 provides Type-2 commands to dynamically create, update, or query the descriptors For example: UPDATE OTMADESC NAME(OTMDEST1) SET(SYNTIMER(600)) 23
  24. 24. IMSDFSDDLT0 DFSDDLT0 supports ICAL S1111 1 1 1 1IOPCB AIB L ICAL SENDRECV OTMDEST1 005000 00028 00030 L DATA HELLO FROM IMS Output shows response, AIBOALEN (actual), AIBOAUSE (returned), AIBRETRN, AIBREASN, AIBERRXT CALL=ICAL SEGMENT =(HELLO FROM RYO) COMP RET CODE=OK IOPCB LTERM= RET CODE= RACFUSER=AUTPSB1 . 0001 0001 AIB BLOCK AIBOALEN = 000E, AIBOAUSE = 000E, 0000 0000 0000 RETURN CODE = 0000, REASON CODE = 0000, ERROR EXTSN = 0000 If a timeout occurred, a return code 256 and reason code 260 would be returned. 24
  25. 25. IMSIMS application can callout to external application IMS application can callout to one of the following: – User-written (RYO) IMS Connect application – Java EE apps (MDB or EJB) running in WebSphere Application Server (WAS) using IMS TM Resource Adapter (IMS TM RA) – Web services providers using IMS SOAP Gateway 25
  26. 26. IMSCallout with RYO – Flow diagram Initiating Client z/OS RYO Application IMS Connect IMS HWS1 Resume TPIPE TPIPE IMS Application 1 TPIPE1 TPIPE1 OTMA Descriptor Request OTMDEST1 2 ICAL SENDRECV OTMDEST1 TPIPE1 JACK’S CREDIT CARD # HWS1 ACK 3 Response 4 1111-2222-3333 1111-2223-3333 26
  27. 27. IMSCallout with IMS TM RA – Flow Diagram (MDB) Initiating Client WebSphere Application Server z/OS IMS Connect IMS Message Driven HWS1 Bean (MDB) TPIPE IMS Application ICOPIPE1 IMS TM Resource Adapter Activate 1 OTMA Descriptor 2 ICAL SENDRECV ICODEST1 ICODEST1 onMessage HELLO FROM IMS ICOTPIPE1 HWS1 Web HELLO FROM IMSServiceor EJB HELLO FROM Response 3 HELLO FROM WEBSPHERE MDB WEBSPHERE MDB 27
  28. 28. IMSCallout with IMS TM RA – Flow Diagram (EJB) z/OS WebSphere Application Server IMS Java IMS Application TMSYNC_RECEIVE_ RACALLOUT TPS Resume TPIPE TPS IMS TM/CTL Application Services Program CORTKN Data Connect TPS DEST1 ICAL TPS OTMA HWS1 HWS1 DEST1CORTKN Data ACK Request Send_ONLYSYNC_SEND Response Data CORTKN DataCORTKN 28
  29. 29. IMS Callout with IMS SOAP Gateway – Flow Diagram Initiating Client z/OS IMS SOAP Gateway IMS Connect IMS HWS1 TPIPE IMS Application Server start 1 SGPIPE02 Request OTMA DescriptorWeb Service 2 ICAL SENDRECV OTMDEST1 OTMDEST1 HELLO FROM IMS SGPIPE02 HELLO FROM IMS XML HELLO HWS1 Adapter FROM IMS 3 HWSXMLA0 HELLOD XML Converter Response 4 HELLO FROM WEB SERVICE HELLO FROM HELLO WEB SERVICE FROM WEB SERVICE Correlator 29
  30. 30. IMSEnhanced IMS commands /DISPLAY ACTIVE REGION /PSTOP – Clear the wait in the region – New status for region waiting on synchronous callout response – Dequeues synchronous callout messages from the TPIPE • WAIT-CALLOUT – Continuation line for region waiting on /STOP REG ABDUMP synchronous callout response – Clear the wait in the region and terminate the • TMEMBER name TPIPE: tpipename application program /DIS TMEMBER TPIPE /STOP TMEMBER TPIPE – Clear state of all messages for the TPIPE except – WAIT-S WAIT for response • The transaction pipe is waiting for an ACK or NAK for a synchronous callout /STOP OTMA message – 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 30
  31. 31. IMS/DISPLAY TMEMBER TPIPE SYNC Since every “Resume Tpipe on Hold Queue” request is remembered and tracked by OTMA, OTMA will queue the unprocessed requests. Issuing the /DISPLAY TMEMBER TPIPE SYNC command can show the number of queued “Resume Tpipe on Hold Queue” requests and the active Resume Tpipe status. /DIS TMEM HWS1 TPIPE ALL SYNC DFS000I MBR/TPIP ENQCT DEQCT QCT INPCT OPT MODE SYNCOT NO-RSP RTQ STATUS SMEM DFS000I -CLIENT01 1 0 1 0 N A 0 0 2 WAIT_H In this example, the current active resume tpipe request has the No-AUTO option, async mode. And this tpipe is currently waiting for ACK or NAK. There are 2 queued Resume Tpipes requests on the queue to be processed later. /STOP OTMA or bringing down the OTMA client – HWS1, IMS will clear the active resume tpipe request and all the queued resume tpipe requests. 31
  32. 32. IMSDiagnostics for Synchronous Callout Incorrect OTMA descriptor name specified in the ICAL AIB IMS Connect and IMS not connected. Issue /DIS TMEMBER x TPIPE y SYNC The following diagnostics information is logged in the IMS log records: – Synch Callout requests and responses 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) 32
  33. 33. IMSA 6701 log record for a callout message, and a 67D0 log record for time-out 33
  34. 34. ®IMSDL/I ICAL for Receive in IMS V13 © 2012 IBM Corporation
  35. 35. IMSSupport for Truncated Messages New “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 13 keeps a copy of the entire response message in the control region private storage • Until a subsequent ICAL “SENDRECV”, syncpoint, or application termination Addresses – Partial response message due to inadequate application specification Benefit – Provides the ability to complete the retrieval of a reply message • Without having to re-issue a complete ICAL “SENDRECV” and associated network transmission costs 35
  36. 36. IMSICAL subfunction RECEIVEFormat: • >>-ICAL--aib--response area-----------------------------------------><AIB– AIBSFUNC value “RECEIVE”– AIBOAUSE is used as an input and output parameter based on AIBSFUNC • For the “RECEIVE” call – Contains the length of the response area– AIBOALEN = request area length • Used as an output parameter for “RECEIVE” – When complete response is returned in response area, this field is 0 – If partial data is returned (AIB RC X100, RS X00C), this field contains the actual length of the response message 36
  37. 37. IMSICAL sub-function RECEIVE … Usage example: ICAL --aib—request area, response area AIBSFUNC (SENDRECV) AIBOAUSE – Response area length CALL is issued AIBRETRN=x’100’, AIBREASN=’00C’ × Specified length of the output response area is too small × AIBOAUSE= length of the data that was returned in the response area × AIBOALEN = the actual length of the entire response message Using the value in the previous AIBOALEN and leveraging the new support which keeps the message in IMS CTL region private, retrieve the entire response: ICAL --aib— response area Where response area has been expanded to contain the entire message AIBSFUNC (RECEIVE) AIBOAUSE – new response area length CALL is issued successfully AIBOAUSE – length of the response in the response area AIBOALEN – set to 0 because the call successfully returned the entire response 37
  38. 38. IMSICAL sub-function RECEIVE … ICAL “RECEIVE” is only valid if previous ICAL “SENDRECV” failed Response data is available for retrieval until: – A new ICAL call with sub-function code SENDRECV is issued – When the IMS application reaches a syncpoint • Checkpoint for an BMP application – Abnormal termination 38
  39. 39. ® IMSSynchronous program switch in IMS V13 © 2012 IBM Corporation
  40. 40. IMSSynchronous 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 UOWWebSphere IMS dependent IMS TM IMS DBIMS TM resource adapter services region services Application Database IMS Program IMS SOAP GATEWAY Connect OTMA ICAL TCP/IP user-written Client MPP, JMP IFP, BMP, JBP 40
  41. 41. IMSSynchronous 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 • Reduces unnecessary network traffic when accessing multiple applications in the same IMS or IMSplex IMS IMS IMS WAS Connect IMS WAS Connect MPP1 MPPx MPP1 ICAL WAS MPP2 WAS MPP2 ICAL Application MPP3 Application ICAL MPP3 MPP4 ICAL MPP4 41
  42. 42. IMSHighlights Automatic invocation of OTMA – Without requiring OTMA to be defined or commands to be issued – New OTMA destination descriptor TYPE • IMSTRAN Enhancements to the DL/I ICAL – Allows an IMS transaction to be the target destination • Accepts multi-segment requests/responses – Provides additional AIB return and reason codes Support for Late Reply messages – Can be purged or rerouted Security authorization – Ensures userid of program issuing ICAL can access the target transaction 42
  43. 43. IMSRestrictions No ICAL support for BMP or JBP applications running in DBCTL environments – ICAL is part of the IMS TM capability IMS application program issuing ICAL for a synchronous program switch – Can be a protected transaction • But the target transaction of the ICAL is not part of the RRS commit scope The switched-to program (target of the ICAL) – Has read-only access to the main storage data base (MSDB) – Cannot be an IMS Conversational transaction – Does not invoke IMS Message Format Service (MFS) 43
  44. 44. IMSRestrictions … Exit routines – DFSYIOE0 (OTMA Input/Output Edit Exit routine) • Not called when processing synchronous program switch messages and responses – Increases the transparency of using OTMA • Can be called for a late response being routed to an OTMA destination – To build or override the 1K OTMA user message data prefix in the response header – DFSBSEX0 (Build Security Environment Exit routine) • Not invoked for target transactions of the synchronous program switch – DFSMSCE0 (TM and MSC Message Routing and Control User exit routine ) • Not invoked for the DL/I ICAL synchronous program switch Use of new ICAL capability in a Shared Queues environment – Requires all IMS systems to be at IMS 13 and DBRC MINVERS of 13.1 44
  45. 45. IMSSynchronous Program Switch – The Details An enhancement to the DL/I ICAL to invoke another IMS application – In the same IMS MPP1 Shared MPP2 ICAL IMS2 Msg Queues – In a different IMS IMS1 ICAL MPP3 ICAL • In a Shared Queues back-end MSC IMS X MPP4 • Across an MSC link – And synchronously receive the response back during the same unit of work Where IMS internally schedules the transaction initiated by the ICAL call as an OTMA transaction – Uses a new type of OTMA destination descriptor (TYPE=IMSTRAN) which has been introduced specifically for synchronous program switch support And the target transaction can be – An IFP, MPP, BMP, JMP, or JBP in the IMS TM or TM/DB environments 45
  46. 46. IMSThe DL/I ICAL callSame Format>>-ICAL--aib--request_area--response_area----------------------><Call Name DB/DC DBCTL DCCTL DB Batch TM BatchICAL X X Request Data (example of multi-segment): LLZZ+Trancode+Data LLZZ+Data Response Data in multi-segment: LLZZ+Data LLZZ+Data LLZZ+Data LLZZ+Data 46
  47. 47. IMSThe DL/I ICAL Call … Examples of common Return codes for synchronous program switch – Full list in the IMS documentation Return Code Reason Code Extended Reason code Brief Description (Hex) (Hex) (Hex) 0100 000C 0000 Partial data returned 0100 0100 0000 Error message returned 0100 0104 0020 ICAL timed out 0100 010C 0000 /PSTOP cmd issued 0100 0110 0000 Invalid trancode 0100 0110 0004 Security violation 0100 0110 0005 DFSYICAL stopped 0100 0110 0020 Input length invalid 0100 0110 0031 Trans is stopped 0100 0110 0061 Target trans does not insert back to IOPCB If the ICAL “SENDRECV” receives a partial data status – The new ICAL “RECEIVE” subfunction can retrieve the entire message • Discussed in the OTMA Enhancements section 47
  48. 48. IMSThe DL/I ICAL Call … Continues to use OTMA Destination Routing Descriptors – Which externalize the routing definitions and specifications for callout messages and synchronous program switch messages – Allowing up to 510 destination routing descriptor entries defined in DFSYDTx member of IMS.PROCLIB – With new TYPE= IMSTRAN for synchronous program switches D entry_name keywords Where entry_name is descriptor entry name and can be masked by ending in an * keywords are: TYPE=IMSTRAN LTERMOVR=name TMEMBER=name TPIPE-name SMEM=NO|YES EXIT= NO|YES REPLYCHK=YES|NO SYNCTP=NO|YES SYNTIMER=timeout value For example: D OTMDEST1 TYPE=IMSTRAN SYNTIMER=500 D OTMDEST2 TYPE=IMSTRAN TMEMBER=SCOTTHWS1 TPIPE=BRYCE EXIT=YES 48
  49. 49. IMSOTMA destination routing descriptor for DL/I ICAL TYPE= IMSTRAN – Required for synchronous program switch requests Supported parameters for TYPE=IMSTRAN are as follows: LTERMOVR = Specifies a value to override the LTERM name in the target IMS application program’s I/O PCB TMEMBER= A 1- to 16-character OTMA TMEMBER name. Optional when TYPE=IMSTRAN. When specified, IMS queues the late response of a synchronous program switch to this OTMA TMEMBER (otherwise the late reply is purged) TPIPE= is required when TMEMBER= is specified. TPIPE= A 1- to 8-character TPIPE name. Optional unless TMEMBER is specified for late replies. SMEM= Specifies whether (YES) or not (NO) the TMEMBER is a supermember. Optional parameter. EXIT= Specifies whether (YES) or not (NO) the IMS user exit (DFSCMUX0) can override the descriptor routing information for late messages when TYPE=IMSTRAN. Optional parameter. REPLYCHK= Specifies whether (YES) or not (NO) IMS application replies to the IOPCB. If YES and the target application does not reply to the IOPCB nor message switches to another transaction, IMS returns a bad return code X’0100’, reason code X’0110’, and extended reason code X’0061’ instead of a timeout to the ICAL call. SYNCTP = Specifies whether (YES) or (NO) a synchronous TPIPE is to be created with recoverable sequence numbers for input and output messages. Optional parameter. Primarily used with WebSphere MQ and can apply to late response messages SYNTIMER= Specifies the ICAL timeout value for synchronous program switch. Optional parameter. If timeout value is also specified in the AIB interface, IMS compares the timeout values and selects the lower value. – The other existing parameters OTMA destination descriptors are not applicable for TYPE=IMSTRAN 49
  50. 50. IMSOTMA destination routing descriptor for DL/I ICAL … Type-2 commands can also be used to update, create, delete, or query the descriptor entries for synchronous program switch For example: UPDATE OTMADESC NAME(OTMDEST1) SET(SYNTIMER(800)) QRY OTMADESC NAME(OTMDEST1) SHOW(ALL) – CREATE OTMADESC and UPDATE OTMADESC • New optional sub-parameters for SET – SYNCTP, REPLYCHK, EXIT, and LTRMOVR – QUERY OTMADESC • Includes information for the optional new parameters – SYNCTP, REPLYCHK, EXIT, and LTRMOVR 50
  51. 51. IMSOTMA Support for Synchronous Program SwitchesNon-XCF related OTMA services are used– Internal invocation of OTMA services to process the target transaction request • Without specifying OTMA=Y in the DFSPBxxx member of IMS PROCLIB and without issuing /START OTMA command – No need to start the XCF connection with any OTMA client for the synchronous program switch– The target transaction is processed as an OTMA transaction • If authorization is required, IMS checks to see if user can access target • Using OTMA send-then-commit (CM1) protocol with SyncLevel=CONFIRM – Target transaction of the ICAL is processed as an OTMA transaction • IMS creates an internal OTMA member DFSYICAL and internal tpipe DFSTPIPE to process the transaction – And generates internal ACK/NAK for the CONFIRM request 51
  52. 52. IMSOTMA Support for Synchronous Program Switches … 52
  53. 53. IMSIMS Commands /DIS ACTIVE REGION – Displays the target transaction for the synchronous program switch – Displays the calculated end time of the ICAL • Based on the timeout value 53
  54. 54. IMSIMS Commands … /PSTOP REGION rgn# SYNC tran name … – Allows a program in a wait state to terminate /STOP TMEMBER DFSYICAL [ TPIPE DFSTPIPE ] – Stops all of the synchronous program switches in this IMS /START TMEMBER DFSYICAL [ INPUT flood_limit ] – Starts synchronous program switches after a /STOP command • Optional use of the INPUT keyword provides a flood control value /DISPLAY OTMA – Displays the big picture of OTMA members, even when OTMA is stopped – New user status: • SYNC P2P • SYNC P2P+FLOOD /DISPLAY TMEMBER DFSYICAL TPIPE DFSTPIPE SYNC – Displays information about the tpipes created for the synchronous program switches – Displays the total number of executed synchronous program switches, 54
  55. 55. IMSMessages and Status Codes Messages – DFS4687E ERROR PROCESSING SYNC PROGRAM SWITCH • Provides information about a processing failure – DFS1190I REGION nnnn NOT WAITING ON yyyyyyyy xxxxxxxx • Indicates that a /PSTOP command might have been issued in error Application program status Codes – A1 • CHNG call was issued using a descriptor with TYPE=IMSTRAN • OTMA ALTPCB output destination specified reserved name DFSYICAL – AX • An OTMA user exit (DFSYPRX0, DFSYDRU0, or client DRU exit) returned invalid routing information 55
  56. 56. IMSSecurity Considerations Security for ICAL is similar to CHNG/ISRT DLI calls – Based on transaction security specifications (TRN) • RACF and/or DFSCTRN0 are used for user authorization checking to determine if the ICAL can invoke the target transaction – Unless OTMA security is set to NONE If the ICAL is authorized to do the synchronous program switch – Target transaction is scheduled as an OTMA transaction with the default OTMA security level of FULL • Security level can be changed by issuing the command: – /SECURE OTMA NONE, or – /SECURE OTMA TMEMBER DFSYICAL CHECK|NONE 56
  57. 57. IMSSecurity Considerations … If the ICAL is authorized to do the synchronous program switch … • Even when DFSYICAL does not yet exist in the system or when the target is in another IMS system – You can issue /SECURE OTMA… to preset the security levelThe transaction security specification of TRAN_A The default OTMA security level of ICAL TRAN_B FULL is used to process TRAN_B inTRAN_A will be used to perform thesecurity authorization for the ICAL. the region. Optionally, issue /SECURE OTMA TMEMBER DFSYICAL CHECK|NONE ahead of time 57
  58. 58. IMSShared Queues Support IMS leverages the APPC/OTMA XCF shared queues (SQ) function – For both request and response messages – Specifying AOS= and/or RRS= in the IMS PROCLIB members is not required • ICAL automatically and always uses AOS=X (SL1 uses XCF) – Compatible with any existing AOS= and RRS= currently set for other transactions FE IMS BE IMS AOS=X LTERM GU IOPCB GU IOPCB LU62 ICAL CM1, SL1 …. OTMA ISRT IOPCB BMP ISRT IOPCB Shr Q Requires DBRC MINVERS of 13.1 for all members of the SQ group Otherwise ICAL will get a rejection RC RS Extended Reason Explanation Request message is rejected. The synchronous program switch was executed in X’0100 X’0100’ X’0115’ the Shared Queues environment, but the IMS systems in the Shared Queues do not have the same MINVERS value of 13.1. 58
  59. 59. IMSMSC Support IMS supports sending an ICAL request to an MSC back-end system – MSC/VTAM – MSC/TCPIP with IMS Connect (introduced in IMS 12) LTERM LU62 GU IOPCB GU IOPCB OTMA ICAL MSC …. BMP ISRT IOPCB ISRT IOPCB 59
  60. 60. IMSTransaction expiration for the target transaction Transaction expiration for targets of synchronous program switches (new) – Uses the timeout value of the synchronous program switch • ICAL timeout value is carried in the OTMA header – Invoked during application GU time TRAN_A ICAL 1 3 TRAN_B 2 ICAL times out!! Application issuing ICAL receives a Transaction Expiration is detected during timeout with: Application GU: - AIB return code X’00000100’ - Input message is discarded - reason code X’00000104’ - A 67D0 log record is written - extended reason code X’00000020’ - No symptom dump - No DFS554 message issued. 60
  61. 61. IMSApplication Examples Applications can issue multiple ICALs to different destination TYPEs – Synchronous callout – Synchronous program switch OTMA IMS CTL Region TRANA WebSphere IMS TMRA IMS 1 GU, IOPCB IMS SOAP Connect Gateway Destination 2 Descriptor 3 TYPE(IMSCON) ICAL DEST1 TCP/IP RYO pgm Destination 4 ICAL TRANB Descriptor TYPE(IMSTRAN) 7 5 TRANB MSG-Q 6 GU IOPCB ISRT IOPCB 61
  62. 62. IMSApplication Examples… The IMS application environment supports recursive requests – ICAL to ICAL • Across a single or multiple IMS systems FE IMS BE IMS or Local IMS TRANA APOL12LTERM GU, IOPCB GU, IOPCB 1 SQ ICAL to SKS2LU62 2 3OTMA ICAL requestBMP 7 SQ, ISRT IOPCB 8 ISRT, IOPCB SKS2 MSC, Local 6 GU, IOPCB (FE=BE) ICAL to SKS1 SKS1 4 ISRT IOPCB GU, IOPCB ISRT IOPCB 5 62
  63. 63. IMSMigration/Setup Considerations For Non-shared queues – Synchronous program switch is a base function of IMS 13 For Shared Queues – DBRC minimum version (MINVERS) value of 13.1 is required to enable the synchronous program switch function • Even if it is a single-system Shared Queues environment The MSC remote IMS does not need to be an IMS 13 system New OTMA trace table entries – Documented in the IMS Diagnosis Guide under “OTMA Diagnostic Aids” 63
  64. 64. IMS 64

×