Reliable Transaction Router
System Manager's Manual

Note

The /KEYn=keysegdesc qualifier is an alternative to using the /xxx_OF_FIELD qualifier.

/LENGTH_OF_FIELD=key-field-length

/LENGTH_OF_FIELD=4 (D)

Specifies the length of the key field in the enqueued messages in bytes. Use this qualifier only if the key field type is string , since the key length is in all other cases implied by the key type. The default value for key-length is four bytes.

/LOW_BOUND=low-bound

/LOW_BOUND=min-val-for-key-type (D)

Specifies the lower bound of the key range that the server handles. The interpretation of low-bound depends on the key type. If the key is of type string , it is interpreted as text, otherwise it is interpreted as a numeric value. The default for low-bound is the smallest possible value that can fit in the specified key type.

If the key bound value length is less than the key length (given in /LENGTH_OF_FIELD), the key bound will automatically be null-padded to the required length.

/NODE[=node-list]

/NODE=default-node (D)

Specifies that the command is executed on all nodes specified in node-list . If node-list is omitted, the command is executed only on the node where the command was issued.

/OFFSET_OF_KEY=offset

/OFFSET_OF_KEY=0 (D)

Specifies the offset of the key within the messages in bytes. The default is zero, that is, the key is at the start of the messages. The qualifier /KEYn must be used to specify more than one key segment definition.

/OUTPUT[=filespec]

/OUTPUT=stdout (D)

Specifies that the resulting information is written to the file filespec . If /OUTPUT or filespec is omitted, the standard or default output is used.

/PARTITION_NAME=partition-name

Enables a system manager to specify a particular named partition.

/PREPARE_EXPLICIT

/NOPREPARE_EXPLICIT

Specifies that the flag RTR_F_OPE_EXPLICIT_PREPARE is set in the call to rtr_open_channel() . This qualifier specifies that the server will receive prepare messages (messages of type rtr_mt_prepare ).

/RECIPIENT_NAME=rcpnam

/RECIPIENT_NAME=null (D)

Specifies an optional name for broadcast reception to be associated with the channel. Only broadcasts matching this name are delivered on the channel. To receive named events, the correct event number must also be specified.

RECIPIENT_NAME is case sensitive. If /RECIPIENT_NAME is supplied without a qualifier value, its value defaults to the value of /CHANNEL_NAME. Not supplying the /RECIPIENT_NAME qualifier has the same effect as specifying a null string. Wildcard characters cannot be used for this qualifier. (Senders of broadcasts can use wildcards when specifying /RECIPIENT_SPEC).

/SERVER

/NOSERVER (D)

Specifies that the RTR_F_OPE_SERVER flag is set in the call to rtr_open_channel() . Use this qualifier to declare the channel as a server.

/SHADOW

/NOSHADOW (D)

Valid for server channels only. The /SHADOW qualifier specifies that the RTR_F_OPE_SHADOW flag is set in the call to rtr_open_channel() . The server is part of a shadow pair.

/STANDBY (D)

/NOSTANDBY

Valid for server channels only. The /NOSTANDBY qualifier specifies that the flag RTR_F_OPE_NOSTANDBY is set in the call to rtr_open_channel() , and the server may not be (or have) standbys. By default, servers may have standbys.

/TR_CALL_OUT

/NOTR_CALL_OUT (D)

Specifies that the RTR_F_OPE_TR_CALL_OUT flag is set in the call to rtr_open_channel() , and the server is a router callout server. By default, a server is not a router callout server.

/TYPE_OF_FIELD=key-field-type

/TYPE_OF_FIELD=UNSIGNED (D)

Specifies the field type of the key. The key-type must be one of UNSIGNED, SIGNED or STRING. The default is UNSIGNED.

Related commands

CALL RTR_CLOSE_CHANNEL

Examples

This command opens a server channel called RTR$DEFAULT_CHANNEL that may not have concurrent servers, explicitly accepts transactions and listens for all RTR events.


RTR> CALL RTR_OPEN_CHANNEL/SERVER/NOCONCURRENT/ACCEPT_EXPLICIT/EVENTS=RTR %RTR-S-OK, Normal successful completion

This command opens a client channel called FIN1CHAN.


RTR> CALL RTR_OPEN_CHANNEL/CLIENT/CHANNEL=FIN1CHAN %RTR-S-OK, Normal successful completion

CALL RTR_PREPARE_TX

The CALL RTR_PREPARE_TX command causes a command server to execute the rtr_prepare_tx() routine and to display the returned status.

Format

CALL RTR_PREPARE_TX

Command Qualifiers	Defaults
/CHANNEL_NAME=channel-name	/CHANNEL_NAME=RTR$DEFAULT_CHANNEL
/DATA[=data]	/DATA=0
/NODE[=node-list]	/NODE=default-node
/OUTPUT[=filespec]	/OUTPUT=stdout
/REASON[=reason]	/REASON=0

Description

The CALL RTR_PREPARE_TX command causes a command server to call the rtr_prepare_tx() routine using values supplied on the command line.
The numeric status returned from the call is then converted to its textual representation and displayed.
The rtr_prepare_tx() routine itself is described in the C Application Programmer's Reference Manual.
The prototype of rtr_prepare_tx() is:
rtr_status_t rtr_prepare_tx ( rtr_channel_t channel, rtr_pre_flag_t flags, rtr_reason_t reason rtr_msgbuf_t pmsg rtr_msglen_t msglen ) ;
Table 7-8 shows the correspondence between values you supply on the command line and the C language parameter values produced and used for the call.

Table 7-8 Parameters for rtr_prepare_tx
C Parameter name C Parameter Value Command Line Specification

channel /CHANNEL_NAME=name

flags RTR_NO_FLAGS [none] [D]

reason RTR_NO_REASON /NOREASON [D]

reason_value /REASON=reason_value

pmsg, msglen / DATA=data

The CALL RTR_PREPARE_TX command causes a command server to execute the rtr_prepare_tx() routine using the values supplied on the command line. The numeric status returned from the call is then converted to its textual representation and displayed.
The CALL RTR_PREPARE_TX command can only be used in the context of nested transactions ( rtr_start_tx was called with the parameter join_txid not equal to NOJOIN_TXID). If this call returns RTR_STS_OK, the first (prepare) phase of the RTR 2PC protocol has been initiated.
The message type associated with this command is rtr_mt_prepared . Similar to the message types rtr_mt_accepted and rtr_mt_rejected , the rtr_mt_prepared message type returns data of type rtr_status_data_t in the user buffer. In this case, the status field of rtr_status_data_t is always RTR_STS_OK, and the reason field contains the same reason mask that would be returned in the rtr_mt_accepted message type for the same transaction if the transaction were to be accepted.
Only when the rtr_mt_prepared message is delivered can the operator be sure that all participants of the nested transaction are ready to commit. Alternatively, calling rtr_prepare_tx can result in the message rtr_mt_rejected being delivered if one of the participating servers votes to reject the nested transaction.
The rtr_mt_prepared message is only delivered to the console if rtr_prepare_tx is called.
A call to rtr_prepare_tx must be followed at some point by a call to rtr_accept_tx (or rtr_reject_tx ), which in this context implements the commit phase of the 2PC. Generally, rtr_prepare_tx and rtr_accept_tx will be called by the foreign TM directly, not by the operator.

**Table 7-8 Parameters for rtr_prepare_tx**
C Parameter name	C Parameter Value	Command Line Specification
channel		/CHANNEL_NAME=name
flags	RTR_NO_FLAGS	[none] [D]
reason	RTR_NO_REASON	/NOREASON [D]
	reason_value	/REASON=reason_value
pmsg, msglen		/ DATA=data

Qualifiers

/CHANNEL_NAME=channel_name

/CHANNEL_NAME=RTR$DEFAULT_CHANNEL
Specifies the channel for which the operation is to be performed.
The command server uses a combination of the channel_name and the window from which the call was issued to uniquely identify which channel to use.
channel_name is not case sensitive.
The default channel name is RTR$DEFAULT_CHANNEL.
/DATA[=data]

/DATA=0
The data parameter can be used to pass an ASCII string to RTR that will be saved in the local journal. This string is not sent to the routers or backends, and is used only during recovery when it is passed back to the client application. RTR does not interpret or modify this data in any way. The maximum size of the data parameter is defined as RTR_MAX_BLOB_LEN and is set to 2048 bytes.
/NODE[=node-list]

/NODE=default-node (D)
Specifies that the command is executed on all nodes specified in node-list . If node-list is omitted, the command is executed only on the node where the command was issued.
/OUTPUT[=filespec]

/OUTPUT=stdout (D)
Specifies that the resulting information is written to the file filespec . If /OUTPUT or filespec is omitted, the standard or default output is used.
/REASON[=reason]

/REASON=0
Use /REASON to supply a value for the reason parameter in the call to rtr_prepare_tx() .
The reason parameter to rtr_prepare_tx() is used in place of the reason parameter in the subsequent rtr_accept_tx call() (that is, the reason field in the call to rtr_accept_tx call() or rtr_reject_tx() which follows a call to rtr_prepare_tx() is ignored). The default value for /REASON is 0.

Related commands

CALL RTR_OPEN_CHANNEL
CALL RTR_REJECT_TX

Examples

Prepare the current transaction with a reason of 42.


RTR> CALL RTR_PREPARE_TX /REASON=42 %RTR-S-OK, normal successful completion

CALL RTR_RECEIVE_MESSAGE

The CALL RTR_RECEIVE_MESSAGE command causes a command server to execute the rtr_receive_message() routine and to display the returned status.

Format

CALL RTR_RECEIVE_MESSAGE

Command Qualifiers	Defaults
/CHANNEL_NAME=channel-name	/CHANNEL_NAME=RTR$DEFAULT_CHANNEL
/CLUSTER	/NOCLUSTER
/NODE[=node-list]	/NODE=default-node
/OUTPUT[=filespec]	/OUTPUT=stdout
/TIMEOUT_MS=timoutms	/TIMEOUT_MS=infinite

Description

The CALL RTR_RECEIVE_MESSAGE command causes a command server to call the rtr_receive_message() routine using values supplied on the command line.
The numeric status returned from the call is then converted to its textual representation and displayed.
The rtr_receive_message() routine itself is described in the C Application Programmer's Reference Manual.
The prototype of rtr_receive_message() is:
rtr_status_t rtr_receive_message ( rtr_channel_t *pchannel, rtr_rcv_flag_t flags, rtr_channel_t *prcvchan, rtr_msgbuf_t pmsg, rtr_msglen_t maxlen, rtr_timout_t timoutms, rtr_msgsb_t *pmsgsb ) ;
Table 7-9 shows the correspondence between values you supply on the command line and the C language parameter values produced and used for the call.

Table 7-9 Parameters for rtr_receive_message
C Parameter Name C Parameter Value Command Line Specification

pchannel [displayed]

flags RTR_NO_FLAGS [none] [D]

prcvchan /CHANNEL=channel_name

pmsg [message displayed, if any]

maxlen RTR_MAX_MSGLEN [reasonable limit for display]

timoutms /TIMEOUT_MS=timoutms

pmsgsb [relevant fields displayed]

For all messages received, RTR displays the contents of the message status block ( msgsb ) as follows:

Message type (for example, rtr_mt_opened , rtr_mt_msgn )
Message length in bytes
Transaction ID, user handle, and event number are shown if they are relevant for the message type.

For message types that place a status code and reason code in the user buffer, the status code is converted to text and both are shown.
For all other message types, the contents of the user buffer are displayed in hexadecimal and ASCII text.

**Table 7-9 Parameters for rtr_receive_message**
C Parameter Name	C Parameter Value	Command Line Specification
pchannel		[displayed]
flags	RTR_NO_FLAGS	[none] [D]
prcvchan		/CHANNEL=channel_name
pmsg		[message displayed, if any]
maxlen	RTR_MAX_MSGLEN	[reasonable limit for display]
timoutms		/TIMEOUT_MS=timoutms
pmsgsb		[relevant fields displayed]

Qualifiers

/CHANNEL_NAME=channel_name

/CHANNEL_NAME=RTR$DEFAULT_CHANNEL
Specifies one or more channels from which a message may be received. To specify two or more channels, enter a comma-separated list, such as /CHANNEL_NAME=(CHAN1,CHAN2,CHAN5). Channel names may include wildcard characters.
channel_name is not case sensitive.
Entering the qualifier without a value (that is, /CHANNEL) is equivalent to /CHANNEL=RTR$DEFAULT_CHANNEL. Omitting the qualifier altogether is equivalent to /CHANNEL=* (that is, receive a message on any defined channel).
The command server uses a combination of the channel-name and the window from which the call was issued to uniquely identify which channel to use.
Note that this qualifier sets up the prcvchan parameter on the call to rtr_receive_message .
/CLUSTER

/NOCLUSTER (D)
Specifies that the command is executed on all the nodes in the cluster.
If neither /NODE nor /CLUSTER is specified, the command is executed on the nodes specified by the latest SET ENVIRONMENT command. If no SET ENVIRONMENT command has been entered, the command is executed only on the node where the command was issued.

Note
In environments that do not support remote command capability, the /CLUSTER qualifier causes the relevant command to be executed on the local node only. See Section 1.4 for more information.

/NODE[=node-list]

/NODE=default-node (D)
Specifies that the command is executed on all nodes specified in node-list . If node-list is omitted, the command is executed only on the node where the command was issued.
/OUTPUT[=filespec]

/OUTPUT=stdout (D)
Specifies that the resulting information is written to the file filespec . If /OUTPUT or filespec is omitted, the standard or default output is used.
/TIMEOUT_MS=timoutms

/TIMEOUT_MS=0 (D)
The timoutms argument defines a timeout for the receive, in milliseconds. The default value is an infinite timeout. /TIMEOUT_MS specifies an immediate timeout.

Examples

The following example shows two CALL RTR_RECEIVE_MESSAGE commands on RTR$DEFAULT_CHANNEL.


RTR> CALL RTR_RECEIVE_MESSAGE /TIMEOUT_MS %RTR-S-OK, normal successful completion channel name: RTR$DEFAULT_CHANNEL msgsb msgtype: rtr_mt_rtr_event msglen: 0 evtnum: 113 (RTR_EVTNUM_SRRECOVERCMPL) RTR> CALL RTR_RECEIVE_MESSAGE /TIMEOUT_MS %RTR-S-OK, normal successful completion channel name: RTR$DEFAULT_CHANNEL msgsb msgtype: rtr_mt_msg1 msglen: 55 usrhdl: 0 tid: 1fe5c,495a4,0,0,1bf80,84,36 message offset bytes text 000000 54 68 69 73 20 69 73 20 74 68 65 20 6D 65 73 73 This is the mess 000010 61 67 65 20 74 65 78 74 2E 20 53 6F 6D 65 20 64 age text. Some d 000020 69 67 69 74 73 20 68 65 72 65 3A 20 31 32 33 34 igits here: 1234 000030 35 36 37 38 39 30 00 567890.

 RTR> CALL RTR_RECEIVE_MESSAGE /TIMEOUT_MS
 %RTR-S-OK, normal successful completion
 channel name:  RTR$DEFAULT_CHANNEL
 msgsb
   msgtype:     rtr_mt_rtr_event
   msglen:      0
   evtnum:      113     (RTR_EVTNUM_SRRECOVERCMPL)
 RTR> CALL RTR_RECEIVE_MESSAGE /TIMEOUT_MS
 %RTR-S-OK, normal successful completion
 channel name:  RTR$DEFAULT_CHANNEL
 msgsb
   msgtype:     rtr_mt_msg1
   msglen:      55
   usrhdl:  0
   tid:         1fe5c,495a4,0,0,1bf80,84,36  
 message 
   offset  bytes                                            text
   000000  54 68 69 73 20 69 73 20 74 68 65 20 6D 65 73 73  This is the mess
   000010  61 67 65 20 74 65 78 74 2E 20 53 6F 6D 65 20 64  age text. Some d
   000020  69 67 69 74 73 20 68 65 72 65 3A 20 31 32 33 34  igits here: 1234
   000030  35 36 37 38 39 30 00                             567890.

CALL RTR_REJECT_TX

The CALL RTR_REJECT_TX command causes a command server to execute the rtr_reject_tx() routine and to display the returned status.

Format

CALL RTR_REJECT_TX

Command Qualifiers	Defaults
/CHANNEL_NAME=channel-name	/CHANNEL_NAME=RTR$DEFAULT_CHANNEL
/CLUSTER	/NOCLUSTER
/NODE[=node-list]	/NODE=default-node
/OUTPUT[=filespec]	/OUTPUT=stdout
/REASON[=reason]	/REASON=0
/RETRY	/NORETRY

Description

The CALL RTR_REJECT_TX command causes a command server to call the rtr_reject_tx() routine using values supplied on the command line.
The numeric status returned from the call is then converted to its textual representation and displayed.
The rtr_reject_tx() routine itself is described in the C Application Programmer's Reference Manual.
The prototype of rtr_reject_tx() is:
rtr_status_t rtr_reject_tx ( rtr_channel_t channel, rtr_rej_flag_t flags, rtr_reason_t reason ) ;
Table 7-10 shows the correspondence between values you supply on the command line and the C language parameter values produced and used for the call.

Table 7-10 Parameters for rtr_reject_tx
C Parameter Name C Parameter Value Command Line Specification

channel /CHANNEL_NAME=name

flags RTR_NO_FLAGS [none] [D]

RTR_F_REJ_RETRY /RETRY

reason RTR_NO_REASON /NOREASON [D]

reason_value /REASON=reason_value

**Table 7-10 Parameters for rtr_reject_tx**
C Parameter Name	C Parameter Value	Command Line Specification
channel		/CHANNEL_NAME=name
flags	RTR_NO_FLAGS	[none] [D]
	RTR_F_REJ_RETRY	/RETRY
reason	RTR_NO_REASON	/NOREASON [D]
	reason_value	/REASON=reason_value

Qualifiers

/CHANNEL_NAME=channel_name

/CHANNEL_NAME=RTR$DEFAULT_CHANNEL
Specifies the channel for which the operation is to be performed.
The command server uses a combination of the channel_name and the window from which the call was issued to uniquely identify which channel to use.
channel_name is not case sensitive.
The default channel name is RTR$DEFAULT_CHANNEL.
/CLUSTER

/NOCLUSTER (D)
Specifies that the command is executed on all the nodes in the cluster.
If neither /NODE nor /CLUSTER is specified, the command is executed on the nodes specified by the latest SET ENVIRONMENT command. If no SET ENVIRONMENT command has been entered, the command is executed only on the node where the command was issued.

Note
In environments that do not support remote command capability, the /CLUSTER qualifier causes the relevant command to be executed on the local node only. See Section 1.4 for more information.

/NODE[=node-list]

/NODE=default-node (D)
Specifies that the command is executed on all nodes specified in node-list . If node-list is omitted, the command is executed only on the node where the command was issued.
/OUTPUT[=filespec]

/OUTPUT=stdout (D)
Specifies that the resulting information is written to the file filespec . If /OUTPUT or filespec is omitted, the standard or default output is used.
/REASON[=reason]

/REASON=0
Use /REASON to supply a value for the reason parameter in the call to rtr_reject_tx() .
The default value for /REASON is 0, which causes the command server to use the value RTR_NO_REASON for the reason parameter in the call to rtr_reject_tx() .
/RETRY

/NORETRY (D)
Use /RETRY to specify the flags parameter as RTR_F_REJ_RETRY in the call rtr_reject_tx() .
The default value for /RETRY is /NORETRY, which causes the command server to use the value RTR_NO_FLAGS for the flags parameter in the call to rtr_reject_tx() .

Related commands

CALL RTR_OPEN_CHANNEL
CALL RTR_ACCEPT_TX

Examples

Reject the current transaction with a reason of 42.


RTR> CALL RTR_REJECT_TX /REASON=42 %RTR-S-OK, normal successful completion

Contents

Index

Reliable Transaction RouterSystem Manager's Manual

/LENGTH_OF_FIELD=key-field-length

/LENGTH_OF_FIELD=4 (D)

/LOW_BOUND=low-bound

/LOW_BOUND=min-val-for-key-type (D)

/NODE[=node-list]

/NODE=default-node (D)

/OFFSET_OF_KEY=offset

/OFFSET_OF_KEY=0 (D)

/OUTPUT[=filespec]

/OUTPUT=stdout (D)

/PARTITION_NAME=partition-name

/PREPARE_EXPLICIT

/NOPREPARE_EXPLICIT

/RECIPIENT_NAME=rcpnam

/RECIPIENT_NAME=null (D)

/SERVER

/NOSERVER (D)

/SHADOW

/NOSHADOW (D)

/STANDBY (D)

/NOSTANDBY

/TR_CALL_OUT

/NOTR_CALL_OUT (D)

/TYPE_OF_FIELD=key-field-type

/TYPE_OF_FIELD=UNSIGNED (D)

Related commands

Examples

CALL RTR_PREPARE_TX

Format

Description

Qualifiers

/CHANNEL_NAME=channel_name

/CHANNEL_NAME=RTR$DEFAULT_CHANNEL

/DATA[=data]

/DATA=0

/NODE[=node-list]

/NODE=default-node (D)

/OUTPUT[=filespec]

/OUTPUT=stdout (D)

/REASON[=reason]

/REASON=0

Related commands

Examples

CALL RTR_RECEIVE_MESSAGE

Format

Description

Qualifiers

/CHANNEL_NAME=channel_name

/CHANNEL_NAME=RTR$DEFAULT_CHANNEL

/CLUSTER

/NOCLUSTER (D)

/NODE[=node-list]

/NODE=default-node (D)

/OUTPUT[=filespec]

/OUTPUT=stdout (D)

/TIMEOUT_MS=timoutms

/TIMEOUT_MS=0 (D)

Examples

CALL RTR_REJECT_TX

Format

Description

Qualifiers

/CHANNEL_NAME=channel_name

/CHANNEL_NAME=RTR$DEFAULT_CHANNEL

/CLUSTER

/NOCLUSTER (D)

/NODE[=node-list]

/NODE=default-node (D)

/OUTPUT[=filespec]

/OUTPUT=stdout (D)

/REASON[=reason]

/REASON=0

/RETRY

/NORETRY (D)

Related commands

Examples

Reliable Transaction Router
System Manager's Manual