Reliable Transaction Router
System Manager's Manual

DO

The DO command executes an operating system command.

Format

DO [operating-system-command]

Command Qualifiers	Defaults
/CLUSTER	/NOCLUSTER
/NODE[=node-list]	/NODE=default-node
/OUTPUT[=filespec]	/OUTPUT=stdout

Description

The DO command enables an operating system command to be executed from RTR. By using the /NODE and /CLUSTER qualifiers, the command can be executed on one or more remote nodes. (Note that the SPAWN command does not have this ability).
The DO command is only suitable for commands producing line-oriented output; use SPAWN to execute a local operating system command that produces screen-oriented output (for example, the OpenVMS MONITOR SYSTEM command, or screen mode editors).

Parameters

DCL-command
The operating system command that you want to execute.

Qualifiers

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

Related commands

SPAWN

Examples

#1
RTR> DO/CLUSTER SHOW TIME

This command shows the time on all nodes in a OpenVMS cluster.

#2
RTR> DO/NODE=(TR2,TR1) SHOW LOGICAL MYLOGICAL

This command examines the logical name MYLOGICAL on nodes TR2 and TR1.

#3
RTR> SET ENVIRONMENT/NODE=(TR2,TR1) RTR> DO SHOW TIME RTR> DO SHOW LOGICAL MYLOGICAL

Use the SET ENVIRONMENT command if a series of DCL commands are to be issued on the same nodes.

#4
RTR> DO/NODE=(TR2,TR1) "ps"

This command displays the processes running on Compaq Tru64 UNIX nodes TR2 and TR1.

DUMP JOURNAL

The DUMP JOURNAL command displays information from the current RTR journal.

Format

DUMP JOURNAL

Command Qualifiers	Defaults
/BEFORE[=date]	Today
/COMMIT_SEQUENCE_NUMBER	all CSNs
=csn
/FACILITY[=facility-name]	/FACILITY="*"
/FINAL_STATE=final-state	None
/FULL	/NOFULL
/MESSAGE_NUMBER=msg_nbr	All messages
/NODE[=node-list]	/NODE=default-node
/OUTPUT[=filespec]	/OUTPUT=stdout
/PARTITION=partition	None
/RAW_DATA=filename	None
/RECORD_CLASS=record-class-type	None
/SINCE[=date]	Today
/STATISTICS	None
/TID=tid	All TIDs
/USER=username	All users

Description

The DUMP JOURNAL command dumps (that is, displays or sends to a file) the contents of an RTR journal file.
The command can display transaction messages that were written in text format, up to 256 bytes.

Qualifiers

/BEFORE[=date]
Selects only those transactions whose timestamp is before the specified date. Default is the current date.
/COMMIT_SEQUENCE_NUMBER=CSNs
The Commit Sequence Number (CSN) is used in the RTR mechanism controlling transaction sequencing across multiple servers. The CSNs for transactions are displayed by the DUMP JOURNAL command. When this qualifier is used, only those transactions that have the specified CSN number are selected.
/FACILITY[=facility-name]

all facilities (D)
Selects only those transactions belonging to the specified facility. Facility-name can contain wildcards (*, % and ?), in which case all matching facilities are displayed.
If /FACILITY is not specified, journal information for all facilities is displayed.
/FINAL_STATE=final_state
Selects transactions whose final state matches that specified. Final state can be one of:
VOTED
COMMIT
ABORT
SEND
EXCEPTION
PREPARE
PRI_DONE
PRI_FORGET
PRI_START
PARTITION
SEC_DONE
DONE

/FULL

/NOFULL (D)
Specifies that the command dumps detailed information (in logged sequence) about each journal record including the record header and each individual state of the transaction. At the end, the command also dumps the final state of each transaction followed by statistics.
If /FULL is not specified, only brief information is displayed.
/MESSAGE_NUMBER=message_number
This qualifier is only valid when used in conjunction with the /TID and /RAW_DATA qualifiers. Message data is not output unless a raw data file has been specified. Message_number can contain wildcards (*, % and ?), in which case all matching facilities are displayed.
For each selected transaction, message data for each specified message is collected and output to the file specified by the /RAW_DATA qualifier.
If no message is specified, the default is that all messages for each qualifying transaction are selected.
/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.
/PARTITION=partition_name
Selects only those transactions contained in the specified partition.
/RAW_DATA=filename
Writes the unedited content of each selected message for each selected transaction to the specified file. Message data contained in this file is application specific, and is not interpreted in any way by RTR. It is the responsibility of the application programmer to develop any necessary tools for viewing the contents of this file.
This qualifier is valid only when used in conjunction with the /MESSAGE_NUMBER qualifier.
For each message, the raw data file contains a message header, a variable-length string representing the transaction identifier, and finally the message data. The message header is defined in the rtr.h include file, and is specified as follows:
typedef struct rtr_raw_data_header_t { rtr_uns_32_t message_number; rtr_uns_32_t message_length; rtr_uns_32_t tid_length; rtr_uns_8_t reserved[256]; };
Reading of the raw data file can be done as follows:

Read the header ( sizeof rtr_raw_data_header_t ).
Read the transaction identifier ( tid_length bytes) followed by reading the message data ( message_length bytes), which positions the file offset to the beginning of the next record, or
Read the rest of the record by reading in tid_length + message_length bytes, which again positions the file offset to the beginning of the next record, or
Skip this message and position directly ( lseek ) to the header of the next message at current offset + tid_length + message_length bytes.

/RECORD_CLASS=record_class_type
Selects transactions which match the specified journal-record-class type.
record_class_type may be one of the following:
VOTED
COMMIT
ABORT
INFO
SEND
EXCEPTION
PREPARE
PRI_DONE
PRI_FORGET
PRI_START
PARTITION
SEC_DONE
DONE

/SINCE[=date]
Selects only those transactions whose timestamp is after the specified date. Default is the current date.
/STATISTICS
Displays a brief summary of the journal contents, and the number of transactions that may be used for restart and shadow recovery.
/TID=tid

All TIDs (D)
Specifies that the command displays only the information pertaining to this particular transaction ID ( tid ). tid is the seven-field numeric identifier used by RTR to uniquely identify a transaction.
DUMP JOURNAL /TID ="3bd01f10,0,0,0,0,1f4c,2d740001"
The quotes enclosing the tid are required. Substituting an asterisk for any one or more of the seven numeric components is permitted as wildcard selection.
If /TID is not specified, log information for all TIDs is displayed.
/USER[=user-id]

/all users (D)
Specifies that the command displays only the information transactions initiated by this particular user-id . User-id may contain wildcards (*, %, and ?), in which case all matching user IDs will be displayed.
If /USER is not specified, log information for all users is displayed.

Related commands

CREATE JOURNAL
DELETE JOURNAL
SHOW JOURNAL
MONITOR JOURNAL

Examples


1. DUMP JOURNAL Final Tx States =================================== TX #1 facility name = test_facility txid = 3bd01f10,0,0,0,0,1f4c,2d740001 tx start = Mon Oct 19 20:52:54 1998 fe user = smith.28924 final tx state = EXCEPTION number of enqs = 1 num of records = 3 commit_seq_nr = 1 Journal Record Statistics =================================== total records processed = 3 send = 1 prepare = 0 vote = 1 commit = 0 abort = 0 pri_done = 0 sec_done = 0 pri_forget = 0 sec_down = 0 pri_start = 0 dtx_info = 0 partition = 0 exception = 1 others = 0 restart recovery txns = 0 shadow recovery txns = 0 2. DUMP JOURNAL/FULL/TID= 3bd01f10,0,0,0,0,1f4c,2d740001 Record #1 Entry (2,16666) Facility name = test_facility Txid = 3bd01f10,0,0,0,0,1f4c,2d740001 Tx start = Mon Oct 19 20:52:54 1998 FE user name = smith.28924 Record class = send Record version = 19980401 PJR address = (1,16398) Record state: kr_id = 16777216 first_kr_enq = 1 enq_nr = 1 buflen = 104 Message: Offset Bytes Text 000000 41 41 41 41 00 00 00 00 00 00 00 00 00 00 00 00 AAAA............ 000010 00 00 00 00 01 00 00 00 00 00 00 00 00 00 00 00 ................ 000020 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 000030 00 00 00 00 00 00 00 00 01 00 00 00 01 00 00 00 ................ 000040 68 00 00 00 00 00 00 00 30 31 32 33 34 35 36 37 h.......01234567 000050 38 39 30 31 32 33 34 35 36 37 38 39 30 31 32 33 8901234567890123 000060 34 35 36 37 38 39 30 31 45678901 Record #2 Entry (2,16666) Facility name = test_facility Txid = 3bd01f10,0,0,0,0,1f4c,2d740001 Tx start = Mon Oct 19 20:52:54 1998 FE user name = smith.28924 Record class = vote Record version = 19980401 PJR address = (1,16398) Record state: kr_id = 83886080 first_kr_enq = 1 nr_kr_enqs = 1 nr_tx_enqs = 1 state = VOTED kr_state = PRI_LONE commit_seq_nr = 1 Record #3 Entry (2,16666) Facility name = test_facility Txid = 3bd01f10,0,0,0,0,1f4c,2d740001 Tx start = Mon Oct 19 20:52:54 1998 FE user name = smith.28924 Record class = exception Record version = 19980401 Final Tx States =================================== TX #1 facility name = test_facility txid = 3bd01f10,0,0,0,0,1f4c,2d740001 tx start = Mon Oct 19 20:52:54 1998 fe user = smith.28924 final tx state = EXCEPTION number of enqs = 1 num of records = 3 commit_seq_nr = 1 Journal Record Statistics =================================== total records processed = 3 send = 1 vote = 1 commit = 0 abort = 0 pri_done = 0 sec_done = 0 pri_forget = 0 sec_down = 0 pri_start = 0 dtx_info = 0 partition = 0 exception = 1 others = 0 restart recovery txns = 0 shadow recovery txns = 0

 
1. DUMP JOURNAL 
 
Final Tx States 
 =================================== 
 
    TX  #1 
        facility name   =  test_facility 
        txid            =  3bd01f10,0,0,0,0,1f4c,2d740001 
        tx start        =  Mon Oct 19 20:52:54 1998 
        fe user         =  smith.28924 
        final tx state  =  EXCEPTION 
        number of enqs  =  1 
        num of records  =  3 
        commit_seq_nr   =  1 
 
 
   Journal Record Statistics 
 =================================== 
  total records processed   =  3 
   send      =  1 
   prepare   =  0 
   vote      =  1 
   commit     =  0 
   abort      =  0 
   pri_done   =  0 
   sec_done   =  0 
   pri_forget =  0 
   sec_down   =  0 
   pri_start  =  0 
   dtx_info   =  0 
   partition  =  0 
   exception  =  1 
   others     =  0 
 
 restart recovery txns   =  0 
 shadow recovery txns    =  0 
 
2. DUMP JOURNAL/FULL/TID= 3bd01f10,0,0,0,0,1f4c,2d740001 
 
Record  #1                  Entry (2,16666) 
        Facility name   =  test_facility 
        Txid            =  3bd01f10,0,0,0,0,1f4c,2d740001 
        Tx start        =  Mon Oct 19 20:52:54 1998 
        FE user name    =  smith.28924 
        Record class    =  send 
        Record version  =  19980401 
        PJR address     =  (1,16398) 
        Record state: 
            kr_id           =  16777216         first_kr_enq    =  1 
            enq_nr          =  1                buflen          =  104 
 
        Message: 
    Offset  Bytes                                            Text 
    000000  41 41 41 41 00 00 00 00 00 00 00 00 00 00 00 00  AAAA............ 
    000010  00 00 00 00 01 00 00 00 00 00 00 00 00 00 00 00  ................ 
    000020  00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................ 
    000030  00 00 00 00 00 00 00 00 01 00 00 00 01 00 00 00  ................ 
    000040  68 00 00 00 00 00 00 00 30 31 32 33 34 35 36 37  h.......01234567 
    000050  38 39 30 31 32 33 34 35 36 37 38 39 30 31 32 33  8901234567890123 
    000060  34 35 36 37 38 39 30 31                          45678901 
 
    Record  #2                  Entry (2,16666) 
        Facility name   =  test_facility 
        Txid            =  3bd01f10,0,0,0,0,1f4c,2d740001 
        Tx start        =  Mon Oct 19 20:52:54 1998 
        FE user name    =  smith.28924 
        Record class    =  vote 
        Record version  =  19980401 
        PJR address     =  (1,16398) 
        Record state: 
            kr_id           =  83886080         first_kr_enq    =  1 
            nr_kr_enqs      =  1                nr_tx_enqs      =  1 
            state           =  VOTED    kr_state        =  PRI_LONE 
            commit_seq_nr   =  1 
 
    Record  #3                  Entry (2,16666) 
        Facility name   =  test_facility 
        Txid            =  3bd01f10,0,0,0,0,1f4c,2d740001 
        Tx start        =  Mon Oct 19 20:52:54 1998 
        FE user name    =  smith.28924 
        Record class    =  exception 
        Record version  =  19980401 
 
 
    Final Tx States 
 =================================== 
 
    TX  #1 
        facility name   =  test_facility 
        txid            =  3bd01f10,0,0,0,0,1f4c,2d740001 
        tx start        =  Mon Oct 19 20:52:54 1998 
        fe user         =  smith.28924 
        final tx state  =  EXCEPTION 
        number of enqs  =  1 
        num of records  =  3 
        commit_seq_nr   =  1 
 
 
   Journal Record Statistics 
 =================================== 
  total records processed   =  3 
   send      =  1 
   vote      =  1 
   commit     =  0 
   abort      =  0 
   pri_done   =  0 
   sec_done   =  0 
   pri_forget =  0 
   sec_down   =  0 
   pri_start  =  0 
   dtx_info   =  0 
   partition  =  0 
   exception  =  1 
   others     =  0 
 
 restart recovery txns   =  0 
 shadow recovery txns    =  0

EXECUTE

The EXECUTE command executes a file containing RTR commands.

Format

EXECUTE filespec

Command Qualifiers	Defaults
/VERIFY	/NOVERIFY

Description

The EXECUTE command reads a file containing RTR commands and executes them. This command also has the form @filespec .

Parameters

filespec
Specifies the name of the file containing commands to be executed.

Qualifiers

/VERIFY

/NOVERIFY (D)
Specifies that the commands being executed and the resulting information is displayed on the terminal.

Examples


RTR> execute facility_startup

This command executes the file facility_startup . This file might contain commands such as:


start rtr create journal create facility funding/fontend=(node1,node2)/router=(node3)...

EXIT

The EXIT command exits from the RTR prompt.

Format

EXIT

Description

The EXIT command exits from the RTR prompt and returns control to the operating system prompt. The command has no parameters or qualifiers. Same as QUIT.

EXTEND FACILITY

The EXTEND FACILITY command adds new nodes or roles (or both) to an existing facility definition.

Format

EXTEND FACILITY [facility_name]

Command Qualifiers	Defaults
/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
/ROUTER=router-list	/NOROUTER

Description

The EXTEND FACILITY command extends the configuration of an RTR facility. New nodes and roles can be added to a facility definition using the EXTEND FACILITY command. Thus a new node can be introduced into a facility, or a new role can be added to an existing node (for example, a router node can be extended to have a backend role).

Notes:
New router nodes must have all backend nodes defined and new 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.

When using this command, the facility being extended may temporarily lose quorum until the affected nodes agree upon the new facility definition. During this time, server applications will not be presented with any new transactions.
The RTR MONITOR QUORUM displays a monitor picture which allows the quorum negotiations to be followed after a TRIM or EXTEND of a facility. Once quorum has been attained, the participating nodes return to state qrt .
As with the CREATE FACILITY command, superfluous nodes or roles can be specified. That is, you may specify backend nodes on a node that has only a frontend role, and frontend nodes may be specified on a node that has only a backend role. This permits a single RTR management command to be issued on many nodes, and each node accepts only those parts of the command which are relevant to it.
For example, in a two-node facility called facnam , the node FE has the frontend role only. Node FETRBE , which has frontend, router and backend roles, can be created as follows:
$ RTR RTR> SET ENVIRONMENT /NODE=(FE,FETRBE) RTR> CREATE FACILITY facnam /FRONTEND=(FE,FETRBE) - /ROUTER=FETRBE - /BACKEND=FETRBE
A new frontend NFE can be added to this facility as follows:
$ RTR RTR> SET ENVIRONMENT /NODE=(FETRBE,NFE) RTR> EXTEND FACILITY facnam /FRONTEND=NFE - /ROUTER=FETRBE

Parameters

facility_name
Specifies the name of the facility to be extended.
Any application program that uses this facility must specify the same name when it calls the 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.
The default value for facility_name is RTR$DEFAULT_FACILITY .
The /ROUTER qualifier, and at least one /FRONTEND or /BACKEND qualifier must be specified.
An EXTEND FACILITY command executed on a node where the facility is not defined is interpreted as a CREATE FACILITY command.
To maintain consistency in a facility, the following rules apply when adding nodes or roles or both:

If a frontend role is added, the node where it is added must know about at least one router of the facility.
If a backend role is added, the node where it is added must know about all routers of the facility. If any router nodes are not known by a backend, problems can occur in achieving quorum.
If a router role is added, the node upon which it is added must know about all backends of the facility. If not all backend nodes are known by a router, problems will occur in achieving quorum. At least one frontend must be defined on a node that has the router role.
To have a consistent facility definition across all nodes in the facility (and thus avoid problems in attaining quorum), the command to add a router role must be executed on all relevant nodes, that is, the node gaining the router role and all backend nodes.

Qualifiers

/BACKEND=backend-list

/NOBACKEND (D)
Specifies the names of the added 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 file containing a backend-list on each line.
/BALANCE

/NOBALANCE (D)
Specifies that load balancing is enabled for frontend/router connections across the facility.
For load balancing to function correctly, /BALANCE must be defined on all routers, as well as on those frontends requiring 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 EXTEND FACILITY command. Note that this preference is subject to the router being available and quorate.
For more details on frontend load balancing, see Section 2.7, Router Load Balancing.
/CALL_OUT[=role-list]

/NOCALL_OUT (D)
Specifies which node types are to have callout servers running on them.
Role-list is a comma-separated list of roles. 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)
Specifies the names of the added nodes that act as frontends in this facility. 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.
/ROUTER=router-list

/NOROUTER (D)
Specifies the names of the added 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 EXTEND 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 .
filespec specifies a text file containing a router-list on each line.

Related commands

CREATE FACILITY
DELETE FACILITY
SHOW FACILITY
TRIM FACILITY

Examples

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

Contents

Index

Reliable Transaction RouterSystem Manager's Manual

DO

Format

Description

Parameters

DCL-command

Qualifiers

/CLUSTER

/NOCLUSTER (D)

/NODE[=node-list]

/NODE=default-node (D)

/OUTPUT[=filespec]

/OUTPUT=stdout (D)

Related commands

Examples

DUMP JOURNAL

Format

Description

Qualifiers

/BEFORE[=date]

/COMMIT_SEQUENCE_NUMBER=CSNs

/FACILITY[=facility-name]

all facilities (D)

/FINAL_STATE=final_state

/FULL

/NOFULL (D)

/MESSAGE_NUMBER=message_number

/NODE[=node-list]

/NODE=default-node (D)

/OUTPUT[=filespec]

/OUTPUT=stdout (D)

/PARTITION=partition_name

/RAW_DATA=filename

/RECORD_CLASS=record_class_type

/SINCE[=date]

/STATISTICS

/TID=tid

All TIDs (D)

/USER[=user-id]

/all users (D)

Related commands

Examples

EXECUTE

Format

Description

Parameters

filespec

Qualifiers

/VERIFY

/NOVERIFY (D)

Examples

EXIT

Format

Description

EXTEND FACILITY

Format

Description

Parameters

facility_name

Qualifiers

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

/ROUTER=router-list

/NOROUTER (D)

Related commands

Examples

Reliable Transaction Router
System Manager's Manual