| Previous | Contents | Index |
channel_name is not case sensitive. The default channel name is RTR$DEFAULT_CHANNEL.
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.
In environments that do not support clustering, the /CLUSTER qualifier causes the relevant command to be executed on the local node only. |
/EVENTS=(RTR, n , TO, m , USER, p , TO, q )
where n , m , p and q are event numbers. The default is to listen to no events.
A TM identifier can also be passed in as parameter. It must be in the range of 0 to 65535. Default value is 0.
Operators or script programs using nested transactions should specify a TM identifier, particularly if more than one process opens RTR client channels using the same FTM on the one node, or if different types of FTMs are used on the same node. When a process that has open FTM client channels fails, the FTM must be able to find out from RTR what state the transactions are in that were active in that process. Thus the FTM must be able to identify itself to RTR so RTR can find out what transactions were active for that FTM channel. Generally, FTM client channels opened in the same process (and for the same FTM) can have a common TM identifier, but FTM client channels opened in separate processes should have different TM identifiers.
Calling CALL RTR_OPEN_CHANNEL with the FOREIGN_TM qualifier specified will cause a local journal scan to occur if a journal has not already been opened on that node.
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.
The syntax of the keyn qualifier is:
/KEYn= (type_of_key=[signed|unsigned|string], -
length_of_key=nnnn, -
offset_of_key=nnnn, -
low_bound=low-bound-string, -
high_bound=high_bound_string)
|
type_of_key= Specifies the field type of the key. The key-type must be either unsigned , signed or string . The default is unsigned .
length_of_key=nnnn Specifies the length of the key field in enqueued messages in bytes. Use this qualifier only if the key field type is string , since the key length is in other cases implied by the key type. The default value for key-length is four bytes.
offset_of_key=nnnn 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.
low_bound= Specifies the lower bound of the key range that servers in the partition will service. 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_key ), the key bound will automatically be null-padded to the required length.
high_bound= Specifies the upper bound of the key range that servers in the partition will service. The interpretation of high-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 high-bound is the largest 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_key ), the key bound will automatically be null-padded to the required length.
The /KEYn=keysegdesc qualifier is an alternative to using the /xxx_OF_FIELD qualifier. |
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.
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).
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
|
The CALL RTR_PREPARE_TX command causes a command server to execute the rtr_prepare_tx() routine and to display the returned status.
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 |
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.
/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.
Prepare the current transaction with a reason of 42.
RTR> CALL RTR_PREPARE_TX /REASON=42
%RTR-S-OK, normal successful completion
|
The CALL RTR_RECEIVE_MESSAGE command causes a command server to execute the rtr_receive_message() routine and to display the returned status.
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 |
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.
/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 clustering, the /CLUSTER qualifier causes the relevant command to be executed on the local node only./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.
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.
|
| Previous | Next | Contents | Index |