®
© 2011 IBM Corporation
San Ramon IMS User Group
IMS OTMA BasicsJuly 19, 2012
2
IMS OTMA BasicsSan Ramon IMS User Group
OTMA supports z/OS XCF for communication withother z/OS applications
IMS
Database
Transaction manager
IMS APP
Database manager
OT
MA
XCF
z/OSWebSphere MQIMS BridgeOTMAClient
z/OSIMS ConnectOTMAClient
z/OS
z/OSDB2 SPDSNAIMSOTMA C/I
OTMA Clients
3
IMS OTMA BasicsSan Ramon IMS User Group
IntroductionIMSA
OTMANM=IMSAOTMA
IMSBOTMANM=IMSBOTMA
XCF GROUPGRNAME=GR1
XCF GROUPGRNAME=GR2
DS1
DS2
DS3
IMSCONNECT
IMS BridgeQueue
StorageClass
WebSphereMQSeries
TMEMBER1
TMEMBER2
TMEMBER3
TMEMBER4
Names are not definedin any IMS GEN
TPIPE's
4
IMS OTMA BasicsSan Ramon IMS User Group
XCF
� If OTMA clients start before OTMA (or if OTMA leaves the XCF group) they are notified when OTMA joins/rejoins the XCF group and they can automatically connect/reconnect to OTMA
– MQSeries and IMS Connect do this
5
IMS OTMA BasicsSan Ramon IMS User Group
How IMS Connect uses OTMA
IMS Connect
IMS
OTMA
CM1
CM0
CM1 : Commit then SendCM0 : Send then commit
None
Confirm
SyncPt
Without Resync
6
IMS OTMA BasicsSan Ramon IMS User Group
How MQSeries uses OTMA
MQSeries
IMS
OTMA
CM1
CM0
CM1 : Commit then SendCM0 : Send then commit
None
Confirm
SyncPtconfirmonly
Persistent
NonePersistent
7
IMS OTMA BasicsSan Ramon IMS User Group
How DB2 uses OTMA
DB2 (DSNAIMS)
IMS
OTMA
CM1
CM0
CM1 : Commit then SendCM0 : Send then commit
None
Confirm
SyncPt
8
IMS OTMA BasicsSan Ramon IMS User Group
TPIPEs (Transaction Pipes)
� Control blocks are dynamically created by IMS
� TPIPE name must be unique only within a client
(multiple clients can use the same TPIPE name)
– IMS recognizes TPIPEs as XCFmember .TPIPEname
� A TPIPE name cannot be the same name as an
IMS transaction
� The OTMA Client manages the use of TPIPEs
– Idle cleanup
9
IMS OTMA BasicsSan Ramon IMS User Group
TPIPEs (Transaction Pipes)
� OTMA equivalent of LTERMs
� Input (IOPCB) TPIPE names are specified by the client– For IMS Connect for CM1 messages it is the TCP/IP Port which
received the input message
– For IMS Connect for CM0 messages it is the ICON Client Name• This could lead to MANY TPIPEs!!!
– For MQSeries there are 2 TPIPEs per IMS Bridge Queue• One for “asynchronous” messages (CM0)• One for “synchronous” messages (CM1)• The name is a 3-character user supplied prefix and a 5-digit number
– It is a 2-character prefix if using MQSeries shared queues
– If the TPIPE does not exist it is created
10
IMS OTMA BasicsSan Ramon IMS User Group
TPIPEs (Transaction Pipes)
� There are two types of TPIPEs: SYNChronized and Non-SYNChronized– SYNChronized TPIPEs exchange sequence numbers and can
be resynchronized across failures
– Empty SYNChronized TPIPEs will survive an IMS warm start but will be deleted during an IMS cold start
– Empty Non-SYNChronized TPIPEs will be deleted during an IMS warm start
– MQSeries uses SYNChronized TPIPEs for CM0 messages
• Messages on SYNChronized TPIPEs are considered “recoverable”by MQSeries
– IMS Connect only uses and supports Non-SYNChronized TPIPEs
11
IMS OTMA BasicsSan Ramon IMS User Group
Client Interface
� OTMA Commit Mode
– Commit Mode 0 – commit then send
– Commit Mode 1 – send then commit
– Specified by the OTMA client on each input message
– Determines how IOPCB output messages are sent
– Similar to APPC-IMS Commit Mode
12
IMS OTMA BasicsSan Ramon IMS User Group
Client Interface� OTMA Synclevel
– Specified by the OTMA client on each input message
– Determines how output messages are acknowledged by the OTMA client
– Synclevel 0 (SL0) - None
• The output message is not acknowledged – no ACK/NAK
– Synclevel 1 (SL1) - Confirm
• The OTMA client must send an ACK/NAK for the output message– Dequeue the output message (CM0)
– Complete syncpoint – (CM1)
• MQSeries always uses SL1
– Synclevel 2 (SL2) - Syncpoint
• The OTMA client is participating in 2-phase commit
13
IMS OTMA BasicsSan Ramon IMS User Group
Client Interface� OTMA Commit Mode
– Commit Mode 0 (CM0) - Commit-then-send
• Output is queued
• IMS sends the output after syncpoint is complete
• Queued on a control block called a QAB (Queue Anchor Block)
– The destination name is x’FEFFFFFFaaaaaaaa’
> aaaaaaaa is the address of a CLB associated with the QAB
> Not the address of the QAB control block
• OTMA always requires an ACK to dequeue the output message
– Synclevel 1
• ALTPCB output messages are always Commit Mode 0
• MQSeries calls these “asynchronous” messages
– The output is “asynchronous” from syncpoint completion
14
IMS OTMA BasicsSan Ramon IMS User Group
Client Interface
� OTMA Commit Mode
– Commit Mode 1 (CM1) - Send-then-commit
• IMS sends the IOPCB output and may wait for an ACK before
syncpoint is complete
– Synch level 0 (None) – no ACK – continue syncpoint
– Synch level 1 (Confirm) – wait for ACK
– Synch level 2 (Synchpoint) – wait for ACK + RRS
• Increases region occupancy
• MQSeries calls these “synchronous” messages
– The output message is “synchronous” with syncpoint completion
15
IMS OTMA BasicsSan Ramon IMS User Group
Send-then -commit message (synch level = NONE)
OTMAclient IMS Application
Transaction Trans. insertedto SMB
GU.ISRT to IOPCB.Syn Point starts
Output sent w/o response requested.
DB committed
Commit Confirmed
16
IMS OTMA BasicsSan Ramon IMS User Group
Send-then -commit message (synch level = CONFIRM)
OTMA client IMS Application
Transaction Trans. insertedto SMB
GU.ISRT to IOPCB.Syn Point startsOutput sent
& response requested.
Transaction completes
DB committedCommit Confirmed
ACK
17
IMS OTMA BasicsSan Ramon IMS User Group
Send-then -commit message (synch level = CONFIRM)
OTMA client IMS Application
Transaction Trans. insertedto SMB
GU.ISRT to IOPCB.Syn Point startsOutput sent &
response requested.
DB backout
Commit Aborted
NACKDFS555I
18
IMS OTMA BasicsSan Ramon IMS User Group
OTMA client IMS Application
Transaction Trans. insertedto SMB
GU.ISRT to IOPCB.Syn Point starts
Output sent & response requested.
DB committed
ACK
Output enqueuedto tpipe
Output dequeued
Commit-then -send message
19
IMS OTMA BasicsSan Ramon IMS User Group
OTMA client IMS Application
Transaction Trans. insertedto SMB
GU.ISRT to IOPCB.Syn Point starts
Output sent & response requested.
DB committed
NACK
Output enqueuedto tpipe
Output is still on the queue and will be resent.
Commit-then -send message
20
IMS OTMA BasicsSan Ramon IMS User Group
DFSPBxxx Parameters
� OTMA=Y/N (autostart OTMA)
� OTMA=M – Do not recover /STA OTMA during /ERE
• Can also be accomplished by /STA OTMA NOCHECK
• This is so that the customer can ALWAYS manually start OTMA
when they are ready to process messages
21
IMS OTMA BasicsSan Ramon IMS User Group
DFSPBxxx Parameters
� GRNAME=XCF group for the IMS Control Region and OTMA clients to join
� APPLID1=XCF member name of the IMS Control Region
� OTMANM=XCF member name of IMS (overrides APPLID1)
� USERVAR=XCF member name of IMS - only if RSR or XRF
22
IMS OTMA BasicsSan Ramon IMS User Group
DFSPBxxx Parameters
� OTMAASY=Y/N/S
– For CM1 messages
• used multiple program-to-program switch environment to ensure that only the response transaction is scheduled synchronously
� OTMAMD=Y/N
– Allow DFSYPRX0 to override OTMA output client if OTMA input
23
IMS OTMA BasicsSan Ramon IMS User Group
DFSPBxxx Parameters
� OTMASP=Y/N
– Set the default output TPIPE to SYNChronized
� OTMASE=C,F,N,P
– Provide the default OTMA security level
– If not coded default displays as ‘X’ which is really ‘F’
24
IMS OTMA BasicsSan Ramon IMS User Group
Setup OTMA Client and Destination Descriptors
� DFSYDTx in IMS.PROCLIB– M control cards – Client Descriptor
• M xxxxxxxxxxxxxxxx• Define an OTMA Destination Resolution Exit name for each client
– M xxxxxxxxxxxxxxxx DRU=
– This can be overridden by the OTMA Client at connect time
• Define Flood Control Limit – INPT=– maximum number of input messages
• Define Maximum TPIPEs – MAXTP=– maximum number of TPIPES that IMS creates for an OTMA
• Define CM1 ACK Timeout Value – T/O=– synclevel=confirm or synclevel=syncpt
25
IMS OTMA BasicsSan Ramon IMS User Group
Setup OTMA Client and Destination Descriptors..
� DFSYDTx– D control cards – Destination Descriptor ALTPCB
• TYPE=
• TMEMBER=
• TPIPE=• SMEM=
• SYNTIMER=
• ADAPTER=• CONVERTR=
– MQSeries not currently supported
26
IMS OTMA BasicsSan Ramon IMS User Group
Setup OTMA Client and Destination Descriptors..
� Dynamic Descriptors
–– With IMS 11, descriptors can be managed dynamicallyWith IMS 11, descriptors can be managed dynamically
•• CREATE OTMADESCCREATE OTMADESC
– Used to create a new OTMA message routing descriptor
•• UPDATE OTMADESCUPDATE OTMADESC
– Used to modify an existing destination routing descriptor
•• DELETE OTMADESCDELETE OTMADESC
– Used to remove an existing destination routing descriptor
•• QUERY OTMADESCQUERY OTMADESC– Used to display the characteristics of a specific destination routing
descriptor
27
IMS OTMA BasicsSan Ramon IMS User Group
Setup
� Start (and stop) OTMA via command
– /STA OTMA (like /STA DC)
– /STO OTMA (like /STO DC)
� Set OTMA security via command
– /SEC OTMA xxxx (NONE, PROFILE, CHECK, FULL)
– /SEC OTMA xxxx TMEMBER yyyy
� There are no SYSGEN requirements for OTMA
28
IMS OTMA BasicsSan Ramon IMS User Group
Client Interface
� OTMA Input Message
– The input message may be:
• An IMS command
• An ACK or NACK to an output message
• An OTMA protocol command
– Client Bid, Resync, etc.
– The input message may not be:
• A message to an IMS LTERM
29
IMS OTMA BasicsSan Ramon IMS User Group
Client Interface
� OTMA Input Message – The input message may be:
• an IMS transaction– A “send-receive” IMS transaction
– A “send-only” IMS transaction
> Avoids DFS082 if IMS RESPONSE or CM1 transaction does not reply
> Any IOPCB output will be put on the hold queue and must be retrieved separately
> “Send-only with ACK” will cause OTMA to acknowledge the input message when
it has been queued
– A transaction input message is in the form llzzTRANCODE DATAllzzDATA
• A request to retrieve asynchronous output
– “Resume TPIPE”
– More later
30
IMS OTMA BasicsSan Ramon IMS User Group
Transaction Expiration
� Transaction Expiration
– Distributed applications may timeout transactions
• Not under IMS control
– IMS still processes the transaction
• No one is interested in the output
– This uses unnecessary resources
• Network resources
• CPU / storage / IO
• Dependent region occupancy
31
IMS OTMA BasicsSan Ramon IMS User Group
Transaction Expiration
� Transaction Expiration
– Input message expiration = input message timeout
• Allows OTMA input messages to expire and be deleted prior to processing
• OTMA input messages can specify a timeout value in the OTMA header in one of two ways– An expiration STCK time
> Supported by IMS Connect
– An elapsed time value
– Transaction level input message timeout for OTMA and non-OTMA messages was introduced in IMS 11
32
IMS OTMA BasicsSan Ramon IMS User Group
Transaction Expiration
� Transaction Expiration
– Input message expiration is checked three times
• When the input message is first received
– OTMA only
– Expiry � NAK x’34’
• When the input message is enqueued to the transaction
– OTMA only
– Expiry � NAK x’34’
• GU IOPCB
– OTMA and non-OTMA (IMS 11)
– Expiry � pseudoabend U0243 & DFS555I/DFS2224I
• An x’67D0’ log record is written for all expirations
33
IMS OTMA BasicsSan Ramon IMS User Group
OTMA Exits
� DFSYIOE0: Input/output edit exit– Used to modify the length or data of a segment
– Can cancel a segment or a message
• Can not return a message to the OTMA Client
– Gets the address of the OTMA prefix User Data
• The User Data can be updated– The User Data length cannot be changed
– Can provide IOPCB LTERM override name on input
• Default is the TPIPE name
– Can provide IOPCB MODNAME override name on input
– Can provide MODNAME override name on output
34
IMS OTMA BasicsSan Ramon IMS User Group
OTMA Exits
� OTMA Output Routing Exits– There are two IMS OTMA output routing exits
• DFSYPRX0: Was known as the “Pre-Routing Exit”– Now properly called the “Destination Resolution Exit”
• DFSYDRU0: Was known as the “Destination Resolution Exit”– Now properly called the ”OTMA User Data Formatting Exit”
– Invoked for CHNG call to modifiable ALTPCB
– Invoked for ISRT call to static ALTPCB
– Invoked in XM mode so no SVCs or IMS services
– Invoked even if the input message was not from OTMA
• This allows asynchronous output to OTMA
– Not invoked for ISRT to IOPCB
35
IMS OTMA BasicsSan Ramon IMS User Group
OTMA Exits
� DFSYPRX0– RC=0: Input message came from OTMA, destination is same
or different OTMA client or input message did not come from OTMA, output is not OTMA
• If source is OTMA and destination is a different OTMA client OTMAMD=Y must be set– If OTMAMD is not ‘Y’ the application can receive an ‘AX’ status
– RC=4: message originally did not come from OTMA, but destination is OTMA
• Need to set XCF member name of the OTMA client
– RC=8: message came from OTMA, but destination is not OTMA
36
IMS OTMA BasicsSan Ramon IMS User Group
OTMA Exits
� DFSYDRU0
– Each OTMA client can have their own exit
• Each client may want their OTMA user data formatted differently
– The name of the exit for a client can be specified in DFSYDTx
in the IMS PROCLIB
• If the specified module can not be found name is set to blanks
• The default DFSYDRU0 is invoked if it exists
37
IMS OTMA BasicsSan Ramon IMS User Group
OTMA Exits
� DFSYDRU0 – RC=0: destination is the original OTMA TPIPE
– RC=4: destination is non-OTMA LTERM
– RC=8: destination is new OTMA Client (need to specify)
• The new client DRU0 exit will then be invoked
– RC=12: destination is invalid
• A1 status on CHNG call• Can also be used to indicate any error in module processing
38
IMS OTMA BasicsSan Ramon IMS User Group
Resume TPIPE
� IMS OTMA Asynchronous Output types
– There are three types of OTMA Asynchronous Output
• ALTPCB output
• NAKed IOPCB output
• IOPCB output from Send-Only messages
– There are two places these messages can be queued
• On the normal output queue
• On the asynchronous output queue (hold queue)
– This queue exists only if the OTMA client supports it and says so at
connection time
> Only IMS Connect currently supports this feature
39
IMS OTMA BasicsSan Ramon IMS User Group
Supermember
IMSConnect
ClientSYSPLEX
DISTRIBUTOR
ICON1SMEMBER=SME1
ICON2SMEMBER=SME1
OTMA
ICON1.TPIPE1
ICON2.TPIPE1
SME1.TPIPE1
IMS
Send-Only
Send-Only
Resume TPIPE
Resume TPIPE
Send-Only is sent to ICON1 and output is queued to SME1.TPIPE1
Resume TPIPE is sent to ICON2 and output is found on SME1.TPIPE1
1
3
2
4
40
IMS OTMA BasicsSan Ramon IMS User Group
Supermember
IMSConnect
Client
Send-Only
Resume TPIPE
SYSPLEXDISTRIBUTOR
ICON1SMEMBER
=SME1
OTMA
IMSSend-Only
Resume TPIPE
ICON2SMEMBER
=SME1 OTMA
IMS
CF
IMS SQ
ICON1.TPIPE1
ICON2.TPIPE1
SME1.TPIPE1
Super member alsoworks in an IMS Shared Queues environment
1
2
3 4
41
IMS OTMA BasicsSan Ramon IMS User Group
Security
� There are two kinds of IMS OTMA Security
– OTMA Client Bid security
– OTMA Message security
– Each OTMA client also has its own OTMA security
considerations
42
IMS OTMA BasicsSan Ramon IMS User Group
Security
� OTMA Client Bid Security
– A Client Bid command is the OTMA client request to IMS to start a connection
– If OTMA security is set to NONE there is no Client Bid security
– If OTMA security is not NONE the OTMA Client must pass a UTOKEN in the OTMA header in the Client Bid
• A UTOKEN means that the USERID of the OTMA Client has been
previously verified
– IMS uses the UTOKEN to build an ACEE
• If this fails the Client Bid is rejected
– NAK
43
IMS OTMA BasicsSan Ramon IMS User Group
Security
� OTMA Message Security
– If OTMA security is set to NONE there is no Message security
• There is no checking of the RACF TIMS Class for user authority to
execute an IMS transaction
– DFSCTRN0 is invoked if it exists and can enforce security
• There is no checking the RACF CIMS Class for user authority to
issue an IMS command
– DFSCCMD0 is invoked if it exists and can enforce security
• There is no RACF checking for CHNG calls, AUTH calls or DeferredConversation Program-to-Program Message Switches
– DFSCTRN0 is invoked if it exists and can enforce security
– DFSCTES0 is invoked if it exists and can enforce security
44
IMS OTMA BasicsSan Ramon IMS User Group
IMS V12: Single ACEEs for the same User
IMS Connect
1
Sysplexdistributor
RACF IDAUSER
RACF IDAUSER
ACEEAUSER
WMQ
RACF IDAUSER
TCP/IPNetwork
AUSER
ACEEAUSER
ACEEAUSER
– More storage
– More RACF calls to create an instance of an ACEE
– Possible security exposure if a change has to be made to a user profile
• Different versions of the ACEE based on which OTMA client is used
IMS
Connect
2
IMS 11
ACEEAUSER
IMS 12
Solution
Single ACEE cache
45
IMS OTMA BasicsSan Ramon IMS User Group
OTMA ACEE Reduction for Multiple OTMA Clients
� New maximum ACEE aging value during client-bid– 999999 seconds (11.5 days)
• Previously 68 years• Range: 300 seconds to 999999 seconds
– If OTMA receives a value less than 300, the value is reset to 0 and OTMA will not refresh ACEEs
� A cached ACEE has an aging value based on the OTMA member client with the lowest value
46
IMS OTMA BasicsSan Ramon IMS User Group
Security
� IMS Security Enhancements
– Resume TPIPE Security
• RIMS SAF/RACF security resource class
– Security definition association between TPIPE name and Userid/Group that can access the TPIPE
• OTMA security exit DFSYTRUX
– Always invoked after the call to SAF/RACF
– Can override the decision of SAF/RACF
– Invoked even if new RIMS security resource class is not defined
47
IMS OTMA BasicsSan Ramon IMS User Group
OTMA Restrictions � The following restrictions are listed in the Open
Transaction Manager Guide and Reference– The maximum total length of all prefixes for an OTMA message is 4096 bytes. This length does not
include any application data.
– Existing IMS application programs that use SETO calls might not run as expected. APPC/IMS application programs using SETO calls might require modification to use implicit OTMA support.
– IMS conversational and Fast Path transactions must be defined as send-then-commit. Existing Fast Path applications can run with OTMA.
– A transaction from an IMS terminal (for example, a SLU 2 terminal) cannot route output directly to a client, but must use an OTMA Prerouting exit routine (DFSYPRX0).
– OTMA does not support the IMS Message Format Service (MFS). However, the MFS message output descriptor (MOD) name can be specified by the client in the prefix of an OTMA message.
– OTMA does not support IMS Front-End Switch.
– OTMA messages cannot be encrypted.
– All user IDs must be verified by RACF, unless the client specifies no security checking in the security-data section of the message prefix.
– IMS modules that contain XCF macros must be reassembled for new releases of IMS.
– OTMA has read only access to MSDB. No update access is available to MSDB from OTMA.
– OTMA does not operate in the IMS DBCTL environment.
– OTMA does not allow IMS terminal control commands like but not limited to /FORMAT, /HOLD, /RCL, and /SIGN commands. /LOCK & /UNLOCK for DATABASE, PROGRAM, and TRANSACTION are now allowed in IMS 10.
48
IMS OTMA BasicsSan Ramon IMS User Group
Conclusion
� IMS OTMA is used by many customers and clients
around the world
� This has not been a complete list of functions and
features – but it does cover the important ones
� OTMA will continue to be enhanced in the future
Top Related