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 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 6-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 6-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, then the global coordinating TM for this transaction is a foreign TM. In this case, rtr_start_tx() must be called to start a transaction (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 an client FTM channel, may be relaxed in a future release.) When a nested transaction is started (join_txid not equal to NOJOIN_TXID), then 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, then 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 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.

/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-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 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 timout of 5000 milliseconds.

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

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

CLEAR/ALL removes all the displayed items from the screen, and is useful when commencing 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 commencing 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 an RTR facility and ready 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 other the participating nodes).

The command must be issued on all participating nodes before any application programs using the facility are started.

Note Router nodes must have all backend nodes defined and Backend nodes must have all router nodes defined. Routers need only be defined with the frontends that they can connect to. Frontends need only be defined with the routers they can connect to.

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 thirty-one 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, then backend-list must be enclosed in parentheses.

Backend-node is either the name of a node or @file-spec, where file-spec 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.6, 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 call-out servers running on them.

Role-list is a list of roles separated by commas. If role-list contains more than one role then 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 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.

/FRONTEND=frontend-list

/NOFRONTEND (D)

Frontend-list is a list of frontend-nodes separated by commas. If there is more than one frontend-node, then frontend-list must be enclosed in parentheses.

Frontend-node is either the name of a node or @file-spec, where file-spec specifies a text file containing a frontend-list on each line.

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

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

/REPLY_CHECKSUM

/NOREPLY_CHECKSUM (D)

Specifies that the reply consistency check (or Response Matching) feature for replayed messages is enabled. It is a check for reply consistency during a replay of a reply to client message.

RTR can enable, disable and display this feature.

/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, then router-list must be enclosed in parentheses.

If /NOBALANCE is specified with the CREATE FACILITY command, then 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 @file-spec, where file-spec specifies a text file containing a router-list on each line.

Related commands

• DELETE FACILITY
• EXTEND FACILITY
• SHOW FACILITY
• TRIM FACILITY

Examples

See Chapter 2, Starting and Setting Up RTR, for examples of how to use the CREATE FACILITY command.

Create RTR's 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 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.

/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 call-out servers.

Parameters

disk-1, ... disk-n

Specifies a list of disk names where the new journal is to reside.

If no disks are specified then the issuer's current default disk will be used.

Spreading the journal over more than one physical disk can improve performance if I/O to the journal file becomes a bottleneck.

Table 6-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 in order 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.

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

/MAXIMUM_BLOCKS[=nr-blocks]

/MAXIMUM_BLOCKS=1000 (D)

Specifies the maximum size that the journal file can use. This qualifier can be applied locally to each disk or globally for all disks.

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

/SUPERSEDE

/NOSUPERSEDE (D)

Specifies how to handle the case where a journal already exists.

If /SUPERSEDE is specified, then 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), then 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/MAX_BLOCK=10000, -
 _RTR> DISK2$:/BLOCK=2000/MAX_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.