Reliable Transaction Router
System Manager's Manual

If /FORMAT is specified without fmt-string , RTR automatically generates a format string. The format string is generated using the parameters given for the qualifiers /SIGNED, /UNSIGNED, /STRING and /LENGTH. The following table shows permitted values for these qualifiers when using /FORMAT without fmt-string .

Table 7-15 Generated Format Strings
Data Type With /LENGTH= With /NOLENGTH

STRING =n, "%nC" "%nC" where
n=strlen(string)

SIGNED =1, "%SB" "%SL"

SIGNED =2, "%SW" "%SL"

SIGNED =4, "%SL" "%SL"

UNSIGNED =1, "%UB" "%SL"

UNSIGNED =2, "%UW" "%SL"

UNSIGNED =4, "%UL" "%SL"

**Table 7-15 Generated Format Strings**
Data Type	With /LENGTH=	With /NOLENGTH
STRING	=n, "%nC"	"%nC" where n=strlen(string)
SIGNED	=1, "%SB"	"%SL"
SIGNED	=2, "%SW"	"%SL"
SIGNED	=4, "%SL"	"%SL"
UNSIGNED	=1, "%UB"	"%SL"
UNSIGNED	=2, "%UW"	"%SL"
UNSIGNED	=4, "%UL"	"%SL"

Refer to the C Application Programmer's Reference Manual, section "Defining a Message Format Description" for information on constructing an fmt-string parameter.

/LENGTH_OF_FIELD=field-length

Enter the size of the message field that you want to define. The default for string types is the length of the message entered, plus one (for the zero termination byte). The default for signed and unsigned types is four. This is a positional qualifier; it must immediately follow the message field that it refers to.

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

/READONLY

/NOREADONLY

The /READONLY qualifier sets the flag RTR_F_SEN_READONLY in the call rtr_send_to_server() . No entry is made in the journal file.

/RETURN_TO_SENDER

/NORETURN_TO_SENDER

The /RETURN_TO_SENDER qualifier sets the flag
RTR_F_SEN_RETURN_TO_SENDER in the call rtr_send_to_server() .

/TYPE_OF_DATA=STRING|SIGNED|UNSIGNED

/TYPE_OF_DATA=STRING (D)

Enter the data type of the message field that you want to define. The default is the string type. This is a positional qualifier; it must immediately follow the message field that it refers to.

Examples

This command sends a message to a server. The message is type string (the default).


RTR> CALL RTR_SEND_TO_SERVER "Get that info for me, please" %RTR-S-OK, Normal successful completion

CALL RTR_START_TX

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

Format

CALL RTR_START_TX

Command Qualifiers	Defaults
/CHANNEL_NAME=channel-name	/CHANNEL_NAME=RTR$DEFAULT_CHANNEL
/CLUSTER	/NOCLUSTER
/JOIN_TXID=txid-number	/NOJOIN_TXID
/NODE[=node-list]	/NODE=default-node
/OUTPUT[=filespec]	/OUTPUT=stdout
/TIMEOUT_MS=timoutms	/TIMEOUT_MS=Infinity
/TXID_TYPE=txid-type	/TXID_TYPE=RTR

Description

The CALL RTR_START_TX command causes a command server to call the rtr_start_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_start_tx() routine itself is described in the C Application Programmer's Reference Manual.
The prototype of rtr_start_tx() is:
rtr_status_t rtr_start_tx ( rtr_channel_t channel, rtr_sta_flag_t flags, rtr_timout_t timoutms, rtr_channel_t joinchan ) ;
Table 7-16 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-16 Parameters for rtr_start_tx
C Parameter Name C Parameter Value Command Line Specification

channel /CHANNEL_NAME=name

flags RTR_NO_FLAGS [none] [D]

timoutms /TIMEOUT_MS=timoutms

joinchan /JOIN_CHANNEL=channel-name

Nested Transaction Usage
If the FOREIGN_TM qualifier is specified for channel, the global coordinating TM for this transaction is a foreign TM. In this case, rtr_start_tx() must be called to start a transaction. It cannot be started implicitly on first call to rtr_send_to_server() and the join_txid parameter must be specified. The txid_type parameter defaults to RTR if not specified. (This restriction, that classic transactions without a prepare phase cannot be executed on a client FTM channel, may be relaxed in a future release.)

When a nested transaction is started ( join_txid not equal to NOJOIN_TXID), that transaction is given a new RTR TXID (which the operator can retrieve by calling rtr_get_tid ). The foreign TXID passed in join_txid is used only to identify the transaction for the foreign TM (for example, when the foreign TM goes through recovery and requests RTR to return all transactions in PREPARED state).

The channel on which a nested transaction is started must be opened as a client channel, which implies the node is defined with the FE role. However, a journal is required on that node. If there are no other facilities on that node with the BE role defined, RTR will behave as an honorary BE, causing the journal to be opened locally.

**Table 7-16 Parameters for rtr_start_tx**
C Parameter Name	C Parameter Value	Command Line Specification
channel		/CHANNEL_NAME=name
flags	RTR_NO_FLAGS	[none] [D]
timoutms		/TIMEOUT_MS=timoutms
joinchan		/JOIN_CHANNEL=channel-name

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 clustering, the /CLUSTER qualifier causes the relevant command to be executed on the local node only.

/JOIN_TXID=txid-number

/NOJOIN_TXID
The format of the txid-number depends on the TXID_TYPE:
TXID_TYPE Format of txid-number ----------------------------------------------------------- RTR 7 integers of 4 bytes each, separated by commas DDTM 4 integers of 4 bytes each, separated by commas XA Character-string up to 128 bytes of 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.
/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=Infinity (D)
The timoutms argument defines a timeout for the transaction, in milliseconds. The default value is an infinite timeout. /TIMEOUT_MS specifies an immediate timeout (timeout if no message to receive).
/TXID_TYPE=txid-type

/TXID_TYPE=RTR (D)
Possible values for TXID_TYPE parameter are RTR, DDTM and XA.

Related commands

CALL RTR_REJECT_TX
CALL RTR_ACCEPT_TX

Examples

This command starts a new transaction with a timeout of 5000 milliseconds.


RTR> CALL RTR_START_TX /TIMEOUT_MS=5000 %RTR-S-OK, Normal successful completion

CLEAR

The CLEAR command interactively removes one or more displayed items from a monitor picture.

Format

CLEAR

Command Qualifiers	Defaults
/ALL	/NOALL
/X[=column]	Column of previous item
/Y[=row]	Next free row

Description

The CLEAR command enables you to interactively remove one or all of the displayed items from a monitor picture. The picture can then be redisplayed using the MONITOR/RESUME command. See Chapter 6, RTR Monitoring, for a full discussion of monitor pictures.
CLEAR/ALL removes all the displayed items from the screen, and is useful when starting interactive definition of a new picture.

Either /ALL , or /X and /Y must be given.

Qualifiers

/ALL

/NOALL (D)
Specifies that all the items are to be removed from the monitor picture. This is usually used when starting the interactive definition of a new picture.
/X=column

/Y=row
Specify that the item in position ( column , row ) is to be removed from the monitor picture. This enables mistakes to be corrected when interactively modifying monitor pictures.
It can also be used to remove unwanted items from predefined monitor pictures.

Related commands

MONITOR
SHOW DISPLAY
DISPLAY NUMERIC
DISPLAY BAR
DISPLAY TEXT

Examples

See Section A.1, Interactive Definition of a Monitor Picture, for an example of how to use the CLEAR command.

CREATE FACILITY

The CREATE FACILITY command creates an RTR facility and prepares it for transaction traffic.

Format

CREATE FACILITY [facility_name]

Command Qualifiers	Defaults
/ALL_ROLES=node-list	/NOALL_ROLES
/BACKEND=backend-list	/NOBACKEND
/BALANCE	/NOBALANCE
/CALL_OUT=role-list	/NOCALL_OUT
/CLUSTER	/NOCLUSTER
/FRONTEND=frontend-list	/NOFRONTEND
/NODE[=node-list]	/NODE=default-node
/OUTPUT[=filespec]	/OUTPUT=stdout
/RESOURCE_MANAGER	None
=resource-list
/ROUTER=router-list	/NOROUTER

Description

The CREATE FACILITY command configures (defines on a node) an RTR facility and readies it for transaction traffic (that is, establishes links to the other participating nodes). Links may be established some time after the command executes.
The command must be issued on all participating nodes before any application programs using the facility are started.

Note
If the local node has the frontend or backend role, all router nodes must also be defined.

If the local node has the router role, all frontend and backend nodes must also be defined.

If a node has multiple roles, both of the above rules apply.

Do not create a large number of facilities with ad hoc names only for testing purposes. See the discussion in Section 3.6.7.

Parameters

facility_name
Specifies the name of the facility to be created.
Any application program which uses this facility must specify the same name when it calls rtr_open_channel() .
Facility names can contain up to 31 characters. Letters, numbers and underline characters are all valid, but the first character of a facility name must be a letter.
Facility names are not case sensitive.
The default value for facility_name is RTR$DEFAULT_FACILITY .
The /ROUTER qualifier, and at least one of /FRONTEND or /BACKEND must be specified.

Qualifiers

/ALL_ROLES=node-list

/NOALL_ROLES (D)
Specifies the names of the nodes that are to act as frontend, router and backend in this facility.
Note that the definition order of nodes may be significant. This applies to the order of router node definitions when frontend load balancing is not enabled. Nodes defined with the /ROUTER qualifier have the higher priority and are followed by nodes defined by the /ALL_ROLES qualifier. For example, in this definition:
$ RTR CREATE FACILITY /ALL_ROLES=mynode /ROUTER=(anode,bnode)
The router nodes are in definition order anode, bnode, mynode for all frontends except mynode . (Any node that has both frontend and router roles selects its own router first.)
/BACKEND=backend-list

/NOBACKEND (D)
Specifies the names of the nodes that are to act as backends for this facility.
Backend-list is a list of backend-nodes separated by commas. If there is more than one backend-node , backend-list must be enclosed in parentheses.
Backend-node is either the name of a node or @filespec , where filespec specifies a text file containing a backend-list on each line.
/BALANCE

/NOBALANCE (D)
Specifies that load balancing is enabled for the frontend of the transaction router listed with /ROUTER. See Section 2.7, Router Load Balancing, for details on load balancing.
It has no significance on a backend node, and will be ignored if specified.
The default behavior (/NOBALANCE) is for a frontend to connect to the preferred router . Preferred routers are defined by the order specified in the /ROUTER qualifier of the CREATE FACILITY command. Note that this preference is subject to the router being available and quorate.
/CALL_OUT[=role-list]

/NOCALL_OUT (D)
Specifies which node types are to have callout servers running on them.
Role-list is a list of roles separated by commas. If role-list contains more than one role it must be enclosed in parentheses.
Role is one of the keywords ROUTER or BACKEND .
The default for role-list is (ROUTER,BACKEND) .
/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.

/FRONTEND=frontend-list

/NOFRONTEND (D)
Frontend-list is a list of frontend-nodes separated by commas. If there is more than one frontend-node , frontend-list must be enclosed in parentheses.
Frontend-node is either the name of a node or @filespec , where filespec specifies a text file containing a frontend-list on each line.
/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.
/RESOURCE_MANAGER=resource-list
Specifies a list of defined resource managers that this facility may reference. Server applications using this facility and resource manager will receive any recovered transactions when the facility is created. See Appendix C for further information.
/ROUTER=router-list

/NOROUTER (D)
Specifies the names of the nodes that act as routers for this facility.
Router-list is a list of router-nodes separated by commas. If there is more than one router-node , router-list must be enclosed in parentheses.
If /NOBALANCE is specified with the CREATE FACILITY command, the order in which router nodes are specified with the /ROUTER qualifier defines the preferred routing order.
Router-node is either the name of a node or @filespec , where filespec specifies a text file containing a router-list on each line.

Related commands

DELETE FACILITY
EXTEND FACILITY
SHOW FACILITY
TRIM FACILITY

CREATE JOURNAL

The CREATE JOURNAL command creates the RTR recovery journal.

Format

CREATE JOURNAL [disk-1] ... [,disk-n]

Command Qualifiers	Defaults
/BLOCKS=nr-blocks	/BLOCKS=1000
/CLUSTER	/NOCLUSTER
/MAXIMUM_BLOCKS=nr-blocks	/MAXIMUM_BLOCKS=1000
/NODE[=node-list]	/NODE=default-node
/OUTPUT[=filespec]	/OUTPUT=stdout
/SUPERSEDE	/NOSUPERSEDE

Description

The CREATE JOURNAL command creates RTR's recovery journal files on the specified disks. The target size of the files is specified using the /BLOCKS qualifier (512-byte blocks). The RTR journaling system will attempt to keep the journal file to this size.
The /MAXIMUM_BLOCKS qualifier specifies the maximum size that the journal file can extend to; the RTR journaling system will not extend the journal file beyond this size. If the journal file grows to the maximum size specified, RTR processing stops because transactions cannot be safeguarded if they cannot be written to the journal file.
/BLOCKS and /MAXIMUM_BLOCKS are positional qualifiers, so the journal files need not have the same size on each disk.
The CREATE JOURNAL command checks that a journal does not already exist for the node. An error occurs if a journal does exist, unless the /SUPERSEDE qualifier is specified.
When the /SUPERSEDE qualifier is specified, any previously existing journal files are deleted. For this reason the CREATE JOURNAL/SUPERSEDE command should not be issued on a node being started up after a failure if the transactions interrupted by the failure need to be recovered. The CREATE JOURNAL command is normally entered interactively, not automatically from a startup command procedure.
RTR only uses journal files on nodes that are configured to run servers, that is, on backends and on routers with callout servers.

Parameters

disk-1, ... disk-n
Specifies a list of disk names where the new journal is to reside.
If no disks are specified, the issuer's current default disk is used.
Spreading the journal over more than one physical disk can improve performance if I/O to the journal file becomes a bottleneck.

Table 7-17 Platform-Specific Information
Platform Journal Root Finding Disks Notes

UNIX /rtrjnl Use df Enter disk names as thay appear in /dev . Enclose disk names in quotes and separate names with commas. The journals reside in subdirectories of the /rtrjnl .

OpenVMS [RTRJNL] Use SHOW DEVICE If the SYSTEM account has insufficient disk quota for journal file creation, you must have the EXQUOTA privilege for the command to complete successfully.

**Table 7-17 Platform-Specific Information**
Platform	Journal Root	Finding Disks	Notes
UNIX	/rtrjnl	Use `df`	Enter disk names as thay appear in `/dev` . Enclose disk names in quotes and separate names with commas. The journals reside in subdirectories of the `/rtrjnl` .
OpenVMS	[RTRJNL]	Use SHOW DEVICE	If the SYSTEM account has insufficient disk quota for journal file creation, you must have the EXQUOTA privilege for the command to complete successfully.

Qualifiers

/BLOCKS[=nr-blocks]

/BLOCKS=1000 (D)
Specifies the target size of the journal file in 512-byte blocks. This qualifier can be applied locally to each disk or globally for all disks. The maximum number of blocks that can be specified is 524287 blocks on a single disk.
/MAXIMUM_BLOCKS[=nr-blocks]

/MAXIMUM_BLOCKS=1000 (D)
Specifies the maximum size that the journal file can use, up to 524287 blocks on each disk. This qualifier can be applied locally to each disk or globally for all disks.
/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.
/SUPERSEDE

/NOSUPERSEDE (D)
Specifies how to handle the case where a journal already exists.
If /SUPERSEDE is specified, a journal is created whether or not a journal previously existed (unless the previously existing journal is currently in use). The previous contents of the journal, if any, are destroyed.
If /NOSUPERSEDE is specified (default), a journal is created only if no journal previously existed.

Related commands

DELETE JOURNAL
MODIFY JOURNAL
SHOW JOURNAL

Examples


RTR> CREATE JOURNAL /SUPERSEDE DISK1$:/BLOCK=1000/MAXIMUM_BLOCK=10000, - _RTR> DISK2$:/BLOCK=2000/MAXIMUM_BLOCK=200000

Previous Next Contents Index

Reliable Transaction RouterSystem Manager's Manual

/LENGTH_OF_FIELD=field-length

/NODE[=node-list]

/NODE=default-node (D)

/OUTPUT[=filespec]

/OUTPUT=stdout (D)

/READONLY

/NOREADONLY

/RETURN_TO_SENDER

/NORETURN_TO_SENDER

/TYPE_OF_DATA=STRING|SIGNED|UNSIGNED

/TYPE_OF_DATA=STRING (D)

Examples

CALL RTR_START_TX

Format

Description

Qualifiers

/CHANNEL_NAME=channel_name

/CHANNEL_NAME=RTR$DEFAULT_CHANNEL

/CLUSTER

/NOCLUSTER (D)

/JOIN_TXID=txid-number

/NOJOIN_TXID

/NODE[=node-list]

/NODE=default-node (D)

/OUTPUT[=filespec]

/OUTPUT=stdout (D)

/TIMEOUT_MS=timoutms

/TIMEOUT_MS=Infinity (D)

/TXID_TYPE=txid-type

/TXID_TYPE=RTR (D)

Related commands

Examples

CLEAR

Format

Description

Qualifiers

/ALL

/NOALL (D)

/X=column

/Y=row

Related commands

Examples

CREATE FACILITY

Format

Description

Parameters

facility_name

Qualifiers

/ALL_ROLES=node-list

/NOALL_ROLES (D)

/BACKEND=backend-list

/NOBACKEND (D)

/BALANCE

/NOBALANCE (D)

/CALL_OUT[=role-list]

/NOCALL_OUT (D)

/CLUSTER

/NOCLUSTER (D)

/FRONTEND=frontend-list

/NOFRONTEND (D)

/NODE[=node-list]

/NODE=default-node (D)

/OUTPUT[=filespec]

/OUTPUT=stdout (D)

/RESOURCE_MANAGER=resource-list

/ROUTER=router-list

/NOROUTER (D)

Related commands

CREATE JOURNAL

Format

Description

Parameters

disk-1, ... disk-n

Qualifiers

/BLOCKS[=nr-blocks]

/BLOCKS=1000 (D)

/MAXIMUM_BLOCKS[=nr-blocks]

/MAXIMUM_BLOCKS=1000 (D)

/CLUSTER

Reliable Transaction Router
System Manager's Manual