@OTMA_MAP

Copyright © Cloud Software Group, Inc. All Rights Reserved

@OTMA_MAP

Register and allocate storage for use with the @OTMA_MAP table. (TBL)

Table Definition

@OTMA_MAP has the following fields:

Table: @OTMA_MAP Type: MAP Unit: OTMA IDgen: Y

Parameter Name Typ Syn Len Dc Cls Reference ' Event Rule Typ Acc

---------------- - -- --- -- - ---------------- ' ---------------- - -

_ ADDRESS B 4 0 A ' _

_ ' _

| ----- EXTERNAL ----|----------- Metadata Definition -------------

Field Name Xsyn Xlen Xdec Offset Key Typ Syn Len Dec Rqd Default

---------------- ---- ---- -- ------ - - -- ---- -- - ---------------

_ KEY B 4 0 0 P I B 4 0

_ FUNCTION C 4 0 0 C 4 0

_ ANCHOR B 8 0 4 B 8 0

_ RETURNCODE B 4 0 12 B 4 0

_ REASON1 B 4 0 16 B 4 0

_ REASON2 B 4 0 20 B 4 0

_ REASON3 B 4 0 24 B 4 0

_ REASON4 B 4 0 28 B 4 0

_ GROUP_NAME C 8 0 32 C 8 0

_ MEMBER_NAME C 16 0 40 C 16 0

_ PARTNER_NAME C 16 0 56 C 16 0

_ SESSIONS B 4 0 72 B 4 0

_ TPIPE_PREFIX C 4 0 76 C 4 0

_ SESSION_HANDLE B 8 0 80 B 8 0

_ PROC_OPT B 1 0 88 B 2 0

_ DUMMY_FILLER B 3 0 89 B 2 0

_ TRANSACTION C 8 0 92 C 8 0

_ PRF_NAME C 8 0 100 C 8 0

_ LTERM C 8 0 108 C 8 0

_ MODNAME C 8 0 116 C 8 0

_ SEND_BUFFER@ B 4 0 124 B 4 0

_ SEND_BUFFER_LEN B 4 0 128 B 4 0

_ SEND_SEG_LIST B 4 0 132 B 4 0

_ RECEIVE_BUFFER@ B 4 0 136 B 4 0

_ RECV_BUFFER_LEN B 4 0 140 B 4 0

_ RECEIVED_LEN B 4 0 144 B 4 0

_ RECV_SEG_LIST B 4 0 148 B 4 0

_ CONTEXTID_PART1 B 8 0 152 B 8 0

_ CONTEXTID_PART2 B 8 0 160 B 8 0

_ ERROR_MESSAGE V 120 0 168 V 120 0

Fields

FUNCTION

The function code: OPEN, ALLO, SEND, FREE, or CLOS.

ANCHOR

A field initialized to zero before the OPEN call and filled in by the otma_open function call.

RETURNCODE, REASON1, REASON2, REASON3,
REASON4

Status information for the transaction.

GROUP_NAME

The XCF group name.

MEMBER_NAME

The member name for this client.

PARTNER_NAME

The member name for the OTMA server (IMS).

SESSIONS

The number of parallel sessions to be supported with IMS. The only valid value is 1.

TPIPE_PREFIX

The TPIPE name prefix.

SESSION_HANDLE

The session identifier for the subsequent otma_send_receive. It is filled in by the otma_allocate function call.

PROC_OPT

The processing options for the subsequent otma_send_receive call. The supported options are (can be NULL, to use the defaults):

Bit 0 (SyncOnReturn): This option tells IMS to process the message without the RRS context token; in this case, the user ID is obtained when RRS CTXRDTA is invoked.

Bit 1 (SyncLevel1): With this option, the OTMA send-then-commit (Commit Mode 1) SYNCLEVEL 1 is used instead of the default SYNCLEVEL 0.

TRANSACTION

The name of the IMS transaction or command to be sent to IMS.

PRF_NAME

The name of the RACF group name for transactions and commands.

LTERM

The lterm name. On input it is passed to IMS. It is updated on output to the lterm field returned by IMS. Can be blank in both cases.

MODNAME

The modname. On input, it is passed to IMS. It is updated on output to the modname field returned by IMS. Can be blank in both cases. If the input modname is DFSM01, DFSM02, or DFSM05, it is treated as blanks.

SEND_BUFFER@

The pointer to the data to be sent to IMS. When a NULL is specified for TRANSACTION, the transaction name or command must appear, followed by a blank, followed by the data, in this buffer when it is being sent to IMS.

SEND_BUFFER_LEN

The length of the send data.

SEND_SEG_LIST

The pointer to an array of lengths of message segments to be sent to IMS. The first element is the count of the following segment lengths. If a single segment is to be sent, either the first element or the address of the array can be zero.

RECEIVE_BUFFER@

The pointer to the buffer to receive the reply message from IMS.

RECV_BUFFER_LEN

The length of the buffer available to receive the message.

RECEIVED_LEN

The length of data received in the receive buffer. It should equal the sum of the segment lengths.

RECV_SEG_LIST

The pointer to an array to hold the number of segments sent by IMS.

On send, the first element must be set to the number of elements in the array. If a single segment is to be received, either the first element or the address of the array can be zero, in which case all segments are received contiguously without indication of segmentation boundaries.

On receive, the first element is the count of the following segment lengths and must be set by the client to indicate the maximum length of the array. It is modified by the receive.

CONTEXTID

The Distributed Sync Point Context ID from RRS or NULL.

For an unauthorized caller (as is the case with the TIBCO Object Service Broker implementation), OTMA invokes the CTXSWCH call to disassociate the token and to validate if the token is current for a task. When OTMA receives a response from IMS, it switches the context back onto the task before returning control to the caller.

ERROR_MESSAGE

An error or information message from IMS.

Security

Access to @OTMA_MAP is controlled using normal TIBCO Object Service Broker security manager tools. Refer to the Security manual.

Usage Notes

The appropriate fields of the @OTMA_MAP map table must be set up before requesting an OTMA function. The following lists the required fields for each of the functions. After setting up the fields, you invoke the $OTMA tool:

OTMA_OPEN

OTMA_OPEN invokes the otma_open interface call to connect with IMS. The required fields in the @OTMA MAP table are:

FUNCTION

OPEN

GROUP_NAME

The XCF group name.

MEMBER_NAME

The member name for this client.

PARTNER_NAME

The member name for the IMS OTMA server.

SESSIONS

The number of parallel sessions to be supported with IMS. The only valid value is 1.

TPIPE_PREFIX

The prefix for the TPIPE name.

Return values are in the RETURNCODE and REASONx fields:

0

XCF JOIN was successful, client-bid was sent, and acknowledgment received.

4

IMS is not ready. Try again later.

8

Your XCF group and member are already active.

12

A system error occurred.

For the complete description of each error, see the IBM IMS Open Transaction Manager Access Guide and Reference manual.

OTMA_ALLOC

OTMA_ALLOC invokes the otma_allocate interface call to create an independent session to exchange messages. The required fields in the @OTMA_MAP table are:

FUNCTION

ALLO

TRANSACTION

A name for the IMS transaction or command to be sent to IMS.

PROC_OPT

The SyncOnReturn and SyncLevel1 processing options you want for the subsequent otma_send_receive call, in bits 0 and 1. You select the option by turning on the bit.

PRF_NAME

The name of the RACF group name for OTMA transactions and commands.

Return values are in the RETURNCODE and REASONx fields:

0

Success.

4

Session limit reached.

8

Null anchor.

OTMA_SEND_RECEIVE

OTMA_SEND_RECEIVE invokes the otma_send_receive interface call to initiate a message exchange with IMS. The required fields in the @OTMA_MAP table are:

FUNCTION

SEND

LTERM

The lterm name.

MODNAME

The modname.

SEND_BUFFER@

A pointer to the buffer containing the IMS transaction or command data to be sent to IMS.

SEND_BUFFER_LEN

The size of the send buffer desired.

SEND_SEG_LIST

A pointer to an array of lengths of message segments to be sent to IMS.

RECEIVE_BUFFER@

A pointer to the buffer to receive the reply message from IMS.

RECV_BUFFER_LEN

The size of the receive buffer desired.

RECV_SEG_LIST

The pointer to an array to hold the number of segments sent by IMS.

CONTEXT_ID

A field containing NULL or the Distributed Sync Point Context ID from RRS.

Return values are in the RETURNCODE and REASON fields:

0

Normal completion.

8

No anchor, bad session handle, or segment too large.

12

Send failed.

16

Receive was cancelled.

20

Error from IMS.

OTMA_FREE

OTMA_FREE invokes the interface call otma_free to free an independent session created by otma_allocate. The required fields are already set in the @OTMA_MAP table.

Return values are in the RETURNCODE and REASON fields:

0

Success.

4

No allocated session.

8

Incorrect anchor.

OTMA_CLOSE

OTMA_CLOSE invokes the interface call otma_close to free storage for communication and leave the XCF group. The required fields are already set in the @OTMA_MAP table.

Return values are in the RETURNCODE and REASON fields:

0

Success.

4

Null anchor.

8

Cannot leave XCF group.

FUNCTION	The function code: OPEN, ALLO, SEND, FREE, or CLOS.
ANCHOR	A field initialized to zero before the OPEN call and filled in by the otma_open function call.
RETURNCODE, REASON1, REASON2, REASON3, REASON4	Status information for the transaction.
GROUP_NAME	The XCF group name.
MEMBER_NAME	The member name for this client.
PARTNER_NAME	The member name for the OTMA server (IMS).
SESSIONS	The number of parallel sessions to be supported with IMS. The only valid value is 1.
TPIPE_PREFIX	The TPIPE name prefix.
SESSION_HANDLE	The session identifier for the subsequent otma_send_receive. It is filled in by the otma_allocate function call.
PROC_OPT	The processing options for the subsequent otma_send_receive call. The supported options are (can be NULL, to use the defaults): Bit 0 (SyncOnReturn): This option tells IMS to process the message without the RRS context token; in this case, the user ID is obtained when RRS CTXRDTA is invoked. Bit 1 (SyncLevel1): With this option, the OTMA send-then-commit (Commit Mode 1) SYNCLEVEL 1 is used instead of the default SYNCLEVEL 0.
TRANSACTION	The name of the IMS transaction or command to be sent to IMS.
PRF_NAME	The name of the RACF group name for transactions and commands.
LTERM	The lterm name. On input it is passed to IMS. It is updated on output to the lterm field returned by IMS. Can be blank in both cases.
MODNAME	The modname. On input, it is passed to IMS. It is updated on output to the modname field returned by IMS. Can be blank in both cases. If the input modname is DFSM01, DFSM02, or DFSM05, it is treated as blanks.
SEND_BUFFER@	The pointer to the data to be sent to IMS. When a NULL is specified for TRANSACTION, the transaction name or command must appear, followed by a blank, followed by the data, in this buffer when it is being sent to IMS.
SEND_BUFFER_LEN	The length of the send data.
SEND_SEG_LIST	The pointer to an array of lengths of message segments to be sent to IMS. The first element is the count of the following segment lengths. If a single segment is to be sent, either the first element or the address of the array can be zero.
RECEIVE_BUFFER@	The pointer to the buffer to receive the reply message from IMS.
RECV_BUFFER_LEN	The length of the buffer available to receive the message.
RECEIVED_LEN	The length of data received in the receive buffer. It should equal the sum of the segment lengths.
RECV_SEG_LIST	The pointer to an array to hold the number of segments sent by IMS. On send, the first element must be set to the number of elements in the array. If a single segment is to be received, either the first element or the address of the array can be zero, in which case all segments are received contiguously without indication of segmentation boundaries. On receive, the first element is the count of the following segment lengths and must be set by the client to indicate the maximum length of the array. It is modified by the receive.
CONTEXTID	The Distributed Sync Point Context ID from RRS or NULL. For an unauthorized caller (as is the case with the TIBCO Object Service Broker implementation), OTMA invokes the CTXSWCH call to disassociate the token and to validate if the token is current for a task. When OTMA receives a response from IMS, it switches the context back onto the task before returning control to the caller.
ERROR_MESSAGE	An error or information message from IMS.

FUNCTION	OPEN
GROUP_NAME	The XCF group name.
MEMBER_NAME	The member name for this client.
PARTNER_NAME	The member name for the IMS OTMA server.
SESSIONS	The number of parallel sessions to be supported with IMS. The only valid value is 1.
TPIPE_PREFIX	The prefix for the TPIPE name.

0	XCF JOIN was successful, client-bid was sent, and acknowledgment received.
4	IMS is not ready. Try again later.
8	Your XCF group and member are already active.
12	A system error occurred.

FUNCTION	ALLO
TRANSACTION	A name for the IMS transaction or command to be sent to IMS.
PROC_OPT	The SyncOnReturn and SyncLevel1 processing options you want for the subsequent otma_send_receive call, in bits 0 and 1. You select the option by turning on the bit.
PRF_NAME	The name of the RACF group name for OTMA transactions and commands.

FUNCTION	SEND
LTERM	The lterm name.
MODNAME	The modname.
SEND_BUFFER@	A pointer to the buffer containing the IMS transaction or command data to be sent to IMS.
SEND_BUFFER_LEN	The size of the send buffer desired.
SEND_SEG_LIST	A pointer to an array of lengths of message segments to be sent to IMS.
RECEIVE_BUFFER@	A pointer to the buffer to receive the reply message from IMS.
RECV_BUFFER_LEN	The size of the receive buffer desired.
RECV_SEG_LIST	The pointer to an array to hold the number of segments sent by IMS.
CONTEXT_ID	A field containing NULL or the Distributed Sync Point Context ID from RRS.

0	Normal completion.
8	No anchor, bad session handle, or segment too large.
12	Send failed.
16	Receive was cancelled.
20	Error from IMS.