Reliable Transaction Router
System Manager's Manual

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-list (D)

Specifies that the command is executed on all nodes specified in node-list. If node-list is omitted then 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.
Note that only one key segment definition is allowed.

/OUTPUT[=file-spec]

/OUTPUT=stdout (D)

Specifies that the resulting information is written to the file file-spec. If /OUTPUT or file-spec is omitted then 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() .

/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. (Note that 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, then its value defaults to the value of /CHANNEL_NAME. Not supplying the /RECIPIENT_NAME qualifier has the same effect as specifying a null string. Wild card 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 if you want to declare the channel as a server.

/SHADOW

/NOSHADOW (D)

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

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) standby(s). By default, servers may have standby(s).

/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 call-out server. By default a server is not a router call-out 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 open 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-list
/OUTPUT[=file-spec]	/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 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 6-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 6-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 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, then 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 TX were the TX to be accepted.
Only when the rtr_mt_prepared message is delivered, can the operator be sure that all participants of the nested TX 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 TX.
The rtr_mt_prepared message is only delivered to the console if the 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 6-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-list (D)
Specifies that the command is executed on all nodes specified in node-list. If node-list is omitted then the command is executed only on the node where the command was issued.
/OUTPUT[=file-spec]

/OUTPUT=stdout (D)
Specifies that the resulting information is written to the file file-spec. If /OUTPUT or file-spec is omitted then 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 for 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-list
/OUTPUT[=file-spec]	/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 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 6-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 6-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:

the message type (for example, rtr_mt_opened, rtr_mt_msgn).
the message length in bytes
the transaction ID, user handle, are 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 hexadecimal and ASCII text.

**Table 6-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, e.g. /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 then the command is executed on the nodes specified by the latest SET ENVIRONMENT command. If no SET ENVIRONMENT command has been entered then the command is executed only on the node where the command was issued.
Note: In environments that do not support clustering, use of the /CLUSTER qualifier will cause the relevant command to be executed on the local node only.
/NODE[=node-list]

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

/OUTPUT=stdout (D)
Specifies that the resulting information is written to the file file-spec. If /OUTPUT or file-spec is omitted then 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 _MESSAGEcommands 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.

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-list
/OUTPUT[=file-spec]	/OUTPUT=stdout
/REASON[=rsnsts]	/REASON=0
/RETRY	/NORETRY (D)

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 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 6-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 6-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 6-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 then the command is executed on the nodes specified by the latest SET ENVIRONMENT command. If no SET ENVIRONMENT command has been entered then the command is executed only on the node where the command was issued.
Note: In environments that do not support clustering, use of the /CLUSTER qualifier will cause the relevant command to be executed on the local node only.
/RETRY

/NORETRY (D)
Use /RETRY to specify the flags parameter as RTR_F_REJ_RETRY in the call rtr_reject_tx() .
The default for 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() .
/NODE[=node-list]

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

/OUTPUT=stdout (D)
Specifies that the resulting information is written to the file file-spec. If /OUTPUT or file-spec is omitted then 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 for 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() .

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

/NODE[=node-list]

/NODE=default-node-list (D)

/OFFSET_OF_KEY=offset

/OFFSET_OF_KEY=0 (D)

/OUTPUT[=file-spec]

/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-list (D)

/OUTPUT[=file-spec]

/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-list (D)

/OUTPUT[=file-spec]

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

/RETRY

/NORETRY (D)

/NODE[=node-list]

/NODE=default-node-list (D)

/OUTPUT[=file-spec]

/OUTPUT=stdout (D)

/REASON[=reason]

/REASON=0

Related Commands

Examples

Reliable Transaction Router
System Manager's Manual