ims otma - ims ug july 2012 san ramon

®

© 2011 IBM Corporation

San Ramon IMS User Group

IMS OTMA BasicsJuly 19, 2012

Ken [email protected]

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


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


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


How IMS Connect uses OTMA

IMS Connect

IMS

OTMA

CM1

CM0

CM1 : Commit then SendCM0 : Send then commit

None

Confirm

SyncPt

Without Resync

6


How MQSeries uses OTMA

MQSeries

IMS

OTMA

CM1

CM0


None

Confirm

SyncPtconfirmonly

Persistent

NonePersistent

7


How DB2 uses OTMA

DB2 (DSNAIMS)

IMS

OTMA

CM1

CM0


None

Confirm

SyncPt

8


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



� 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



� 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


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


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


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


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


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


Send-then -commit message (synch level = CONFIRM)

OTMA client IMS Application


GU.ISRT to IOPCB.Syn Point startsOutput sent

& response requested.

Transaction completes

DB committedCommit Confirmed

ACK

17


Send-then -commit message (synch level = CONFIRM)



GU.ISRT to IOPCB.Syn Point startsOutput sent &

response requested.

DB backout

Commit Aborted

NACKDFS555I

18





Output sent & response requested.

DB committed

ACK

Output enqueuedto tpipe

Output dequeued

Commit-then -send message

19





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


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


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


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


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


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


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


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


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


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


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


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




– 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




– 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


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


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


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


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


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


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


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


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


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


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


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 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


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


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


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


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

ims otma - ims ug july 2012 san ramon

Technology

mqseries ims

otma ims db2dsnaimsotma

otma mqseries

queued ims

thencommit ims

otma imsmqseriesotma

ims cold start

ims bridge queue