Example 8-2 DUMP JOURNAL Full Output

RTR> DUMP JOURNAL/FULL %RTR-W-JOUINUSE, journal is locked by another user Record #1 Entry (1,507918) Facility name = test Record class = partition Record version = 30210304 Partition name = p_test Key range ID = 16777216 (0x1000000) No. of Segments = 1 Low bound(s) = 0 High bound(s) = 4294967295 Segment Number Offset Length Type 1 0 4 unsigned longword Record #2 Entry (2,508441) Facility name = test Txid = bb802010,0,0,0,0,bb802010,c0d90944 Tx start = Fri Jan 25 11:11:35 2002 FE user name = user1.30557 Partition name = p_test Record class = send Record version = 30210304 PJR address = (1,507918) Record state: kr_id = 16777216 first_kr_enq = 1 enq_nr = 1 buflen = 10 Message: Offset Bytes Text 000000 6D 65 73 73 61 67 65 20 31 00 message 1. Record #3 Entry (2,508441) Facility name = test Txid = bb802010,0,0,0,0,bb802010,c0d90944 Tx start = Fri Jan 25 11:11:35 2002 FE user name = user1.30557 Partition name = p_test Record class = send Record version = 30210304 PJR address = (1,507918) Record state: kr_id = 16777216 first_kr_enq = 1 enq_nr = 2 buflen = 10 Message: Offset Bytes Text 000000 6D 65 73 73 61 67 65 20 32 00 message 2. Final Tx States =================================== TX #1 facility name = test txid = bb802010,0,0,0,0,bb802010,c0d90944 partition names = p_test tx start = Fri Jan 25 11:11:35 2002 fe user = user1.30557 final tx state = rtr_tx_jnl_sending number of enqs = 2 num of records = 2 commit_seq_nr = 0 Journal Record Statistics =================================== total records processed = 3 send = 2 prepare = 0 prepared = 0 vote = 0 commit = 0 abort = 0 pri_done = 0 sec_done = 0 pri_forget = 0 sec_down = 0 pri_start = 0 dtx_info = 0 partition = 1 exception = 0 others = 0 restart recovery txns = 0 shadow recovery txns = 0

The EXECUTE command executes a file containing RTR commands.

Format

EXECUTE filespec

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

The EXIT command exits from the RTR prompt.

Note This command is not available in the RTR web browser interface.

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.

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

Format

EXTEND FACILITY [facility_name]

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

Defining Nodes and Roles in Each Facility For a new router node, define all its backend nodes. For a new backend node, define all its router nodes. For a new router node, define only those frontends to which it will connect. For a new frontend node, define only those routers to which it will connect.

Multiple EXTEND FACILITY commands are additive; that is, a second EXTEND FACILITY command does not supersede a previous command or remove roles, it only adds them.

For use of anonymous clients (wildcards), see the CREATE FACILITY command.

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.8, Router Load Balancing and Flow Control.

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

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.

The FLUSH NAME_CACHE command flushes RTR's internal network name cache.

Note This command is not available in the RTR web browser interface.

Format

FLUSH NAME_CACHE

Description

The FLUSH NAME_CACHE command removes information for all known nodes from RTR's internal network name cache.

Network links could become unstable if a Distributed Name Service (DNS) was configured improperly or the service was slow in responding. During extreme DNS latency, RTR could timeout the connections to nodes waiting for a DNS response. To avoid these problems, RTR has implemented an internal node-name-to-id cache; this reduces RTR's exposure to degraded name servers. The contents of the cache can then be deleted using the command FLUSH NAME_CACHE.

FLUSH NAME_CACHE can be used if the network has been reconfigured or nodes have changed their addresses.

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

See CREATE JOURNAL; INITIALIZE is only retained for compatibility reasons.

The LOG command enters a message in a log file.

Note This command is not available in the RTR web browser interface.

Format

LOG

Description

The LOG command lets you enter text that is written to the current log file. You can write log messages to the operator console or to a log file, but not both simultaneously.

To view which is the current log file, use the SHOW LOG command. To view the contents of the log file, use an editor such as Edt, Notepad, or vi, depending on your operating system. The log file is an ASCII text file. To establish which is the log file, use the SET LOG command. Log files must be periodically purged to avoid difficulties with full disks. If neither the /OPERATOR nor the /FILE qualifier is specified, logging is suppressed. Use the SET LOG command to specify a new file and close the old one.

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

Related commands

• SHOW LOG
• SET LOG

Examples

 RTR> LOG/OUTPUT=RTRLOG.LOG "Message check here"
      

This command tells RTR to write a log message to the file RTRLOG.LOG.

 RTR> LOG/CLUSTER="Check for this message to see if 
logging is working"
      

This command tells RTR to write log messages to all members of a cluster.

 RTR> LOG/NODE=hostname "Message check HERE"
      

This command tells RTR to write a defined log message to the log file on the node hostname .

For an example of the contents of a log file, see the SET LOG command.

The MODIFY JOURNAL command specifies the desired and maximum allowed sizes of RTR's recovery journal.

Format

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

Description

The MODIFY JOURNAL command specifies how the size of RTR recovery journal files on the specified disks can be modified. The target or minimum size is specified using the /BLOCKS qualifier. The maximum allowed size is specified using the /MAXIMUM_BLOCKS qualifier. /BLOCKS and /MAXIMUM_BLOCKS are positional qualifiers, so journal files need not be the same size on each disk.

RTR only uses journal files on nodes that are configured to run servers, that is, on backends and on routers with callout servers.

Note that the MODIFY JOURNAL command does not cause immediate journal file extension. Actual file size modifications take place on demand (by the RTRACP) within the limits defined by the MODIFY JOURNAL command.

The MODIFY JOURNAL command assumes that a journal already exists for the node. If a journal does not exist, an error message is output.

In contrast to the CREATE JOURNAL command, the MODIFY JOURNAL command is normally entered interactively, not automatically from a startup command procedure.

Parameters

disk-1 ... disk-n

Specifies a list of disk names where journal files are modified.

Refer to the CREATE JOURNAL command for information about disks used for journal files.

Qualifiers

/BLOCKS[=nr-blocks]

/BLOCKS=1000 or current-value (D)

Specifies the size of the journal file in blocks. This qualifier can be applied locally to each disk or globally for all disks. If the number of blocks has been specified in a CREATE JOURNAL command, the default is the current value.

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

/MAXIMUM_BLOCKS[=nr-blocks]

/MAXIMUM_BLOCKS=1000 or current-value (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. If the maximum number of blocks has been specified in a CREATE JOURNAL command, the default is the current value.

/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

• CREATE JOURNAL
• INITIALIZE JOURNAL
• SHOW JOURNAL

Example

 RTR> MODIFY JOURNAL "/dev/rz3a" /BLOCK=2000 /MAXIMUM_BLOCKS=20000
      

This command specifies that the desired size of the journal file is 2000 blocks, and the maximum journal file size is 20,000 blocks.

OpenVMS example

 RTR> MODIFY JOURNAL DISK1$:/BLOCKS=3000/MAXIMUM_BLOCKS=20000
      

This command specifies that the desired size of the journal file is 3000 blocks, and the maximum journal file size is 20,000 blocks.