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

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.

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.

/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
      

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

Format

CLEAR

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.

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

Format

CREATE FACILITY [facility_name]

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

/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

The CREATE JOURNAL command creates the RTR recovery journal.

Format

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

Description

The CREATE JOURNAL command creates RTR's recovery journal files on the specified disks. The target or minimum size of the files is specified using the /BLOCKS qualifier (512-byte blocks). The RTR journaling system extends the journal up to /MAXIMUM_BLOCKS as needed, or trims the journal to /BLOCKS to keep the journal file to this size. Specifying large block values can cause the command to take a long time to complete.

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 often entered 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.

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

/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
      

This command deletes any existing journal files and then creates new ones on DISK1$ and DISK2$. The target sizes of the journal files are 1000 and 2000 blocks, and the maximum sizes are 10,000 and 200,000 blocks respectively.

 RTR> CREATE JOURNAL "/dev/rz3a", "/dev/rz2c" /BLOCK=1000 /MAXIMUM_BLOCK=2000
      

This command creates journal files on /dev/rz3a and /dev/rz2c . The target sizes of the journal files is 1000 blocks and the maximum size of the journal on /dev/rz2c is 2000 blocks.