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.

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

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

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 directs RTR to write a log message to a log file.

Format

LOG

Description

The LOG command specifies a defined log entry to be written to its log messages. You can write log messages to the operator console and to a maximum of four log files. Log files must be periodically purged to avoid difficulties with full disks. Use SET LOG to specify a new file and delete the old one.

If neither the /OPERATOR nor the /FILE qualifier is specified, logging is suppressed.

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

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 .

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 (D)

Specifies the size of the journal file in 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, 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 (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 (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.

The MONITOR command displays a monitor picture on the screen.

Format

MONITOR [monitor-filespec]

Description

The MONITOR command allows certain RTR status variables to be continuously displayed on your terminal.

The individual items displayed in the monitor picture can be defined interactively using DISPLAY commands and then executed using a MONITOR/RESUME command.

You can also put the DISPLAY commands into a file (called a monitor file) and then issue a MONITOR monitor-filespec command.

See Chapter 6 for a description of standard monitor pictures.

Parameters

monitor-filespec

Specifies a file containing DISPLAY commands. Monitor file names are of the form monitor-filespec.mon

This file can specify either a user-defined display or one of the standard displays supplied with RTR. If monitor-filespec contains only the file-name portion of a file specification, the RTR utility first searches the platform-specific location for a standard monitor file.

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.

/COUNT=nr-updates

/COUNT=infinite (D)

Specifies how many times the RTR utility updates the screen before exiting or returning to the RTR> prompt.

The default is that RTR updates the screen until CTRL-Z, CTRL-Y or another RTR command is entered. Use the /COUNT qualifier when the /OUTPUT qualifier is being used to redirect output to a file. In this case, nr-updates specifies how many screen images are written to the file.

/FACILITY=facility-name

/NOFACILITY (D)

Specifies the name of the facility to be monitored. This is only meaningful if at least one facility counter is displayed.

/IDENTIFICATION=process-id

/NOIDENTIFICATION (D)

Specifies the hexadecimal process-id of the process to be monitored. This is only meaningful if at least one process counter is to be displayed.

/INTERVAL[=delay-seconds]

/INTERVAL=2 (D)

Specifies how frequently RTR updates the screen. Delay-seconds is the number of seconds that RTR waits after completing one screen update before starting the next. Note that the interval between updates will always be slightly longer than Delay-seconds , depending on the complexity of the display and the number of nodes being monitored.

/LINK=link-name

/NOLINK (D)

Specifies the node name for the link to be monitored. This is only meaningful if at least one link counter is to be displayed.

/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

/NOPARTITION (D)

Specifies the names of the partitions to be monitored.

/RESUME

/NORESUME (D)

Re-executes the last MONITOR command. The qualifiers /OUTPUT, /INTERVAL and /COUNT may be used with /RESUME. All other qualifiers are ignored. Use this qualifier to reset all the averages currently being displayed. It is also useful if monitoring is resumed after issuing one or more RTR commands.

/VERIFY

/NOVERIFY (D)

Specifies that the contents of monitor-filespec are echoed on stdout . This is useful when developing monitor files to find the exact location of syntax errors.