Most RTR commands can be issued either locally (the default) or on one or more remote nodes.

If you use the TCP/IP protocol to activate RTR's remote command capability, you must configure RSHELL for your users. You must start and configure daemons to accept remote commands and authorize users.

If you use DECnet, you must have proxy access which involves an authorization step on target systems and remote task objects must be enabled. Refer to your operating system documentation for more information.

To specify remote node names explicitly, use a command such as:

RTR> command/node=node-list

For example, this command starts RTR on three nodes, nodeA, nodeB, and nodeC:

RTR> start rtr/node=(nodeA,nodeB,nodeC)

To specify remote nodes implicitly, if, for example, the command is to be executed on every node in a recognized cluster, use a command of the following form:

RTR> command/cluster

Remote commands in group mode fail unless groups are the same on the local and the remote nodes. If you are using group mode, the first command or remote command in any sequence should be SET MODE /GROUP.

To enable the remote command capability in RTR, use the following:

On this operating system:	Use:
OpenVMS	SYSMAN Utility
UNIX	rsc
Windows	remote shell (rsh)

To execute several commands remotely on the same nodes but minimize typing, use the SET ENVIRONMENT command.

The following example stops RTR from taking transactions on the two specified nodes, nodeA and nodeC. The RTRACP will continue to run.

% RTR RTR> set environment/node=(nodeA, nodeC) RTR> stop rtr

For more details on the above commands, see the description of the SET ENVIRONMENT command in the reference section of this manual.

RTR command and http servers started during an interactive Windows session do not survive a user logout of that session. After user logout from an interactive Windows session, the machine is no longer accessible to the RTR web browser.

To avoid this, enable remote shell (rsh) access to the Windows system; the http server can then be started with a remote RTR command directed at the system of interest. Windows rsh functionality is available from third parties, and with the Microsoft NT V4.0 Server Resource kit.

This chapter describes how to configure and start an RTR environment. Recovery journals, router load balancing and callout servers are also discussed.

2.1 Introduction

Before RTR applications can run, RTR must be started and the application's facility must be defined on each node of the application's environment. This is done by issuing the START RTR and CREATE FACILITY commands on each participating node. There are several ways to accomplish this:

• Log in to each node in turn and issue the commands interactively.
• Log in to one node and use the remote command capability to configure all the nodes from one session, where your system supports this capability. See Section 1.4 for more information.
• Include the necessary commands in a startup script or command file on each node so the commands are automatically executed when the nodes are booted.

The first two methods are more suited to a development or test environment, while the last method is more suited to a production environment.

The remaining sections contain examples of the commands used to start and configure RTR. Section 8.2 gives syntax details of the RTR commands.

2.2 Setting Up---An Example

The following example assumes that RTR has been started on the eight-node system shown in Figure 2-1.

Figure 2-1 RTR Configuration

In Figure 2-1, the application client processes run on the frontend nodes FE1, FE2 and FE3, and the server application processes run on the backend nodes BE1, BE2 and BE3. Nodes TR1 and TR2 are routers and have no application processes running on them. Figure 2-1 shows all possible connections, but a frontend connects to only one router at a time.

2.2.1 Starting RTR and Creating a Facility

Example 2-1 shows the START RTR commands that must be issued on each node to start this configuration. Commands are issued first on node FE1, then on FE2, and on FE3 for frontends followed by TR1 and TR2 for routers, and finally BE1, BE2, and BE3 for backends.

Example 2-1 Local Configuration of Each Node

% rtr (1) RTR> start rtr (2) RTR> create facility funds_transfer/frontend=(FE1,FE2,FE3) - _RTR> /router=(TR1, TR2) - (3) _RTR> /backend=(BE1, BE2, BE3)

1. Starts the RTR CLI.
2. Starts the RTRACP process.
3. This command issued on each node in the configuration creates a facility in which nodes FE1, FE2, and FE3 are frontends, nodes TR1 and TR2 are routers, and nodes BE1, BE2, and BE3 are backends. (The hyphen (-) at the end of command lines is a continuation character that retains the context for the command until it is ended with a carriage return.)

The commands shown in Example 2-1 could also be included in each node's startup script or put in a command procedure used to start the application.

Frontends and backends need to know about the routers to which they are connected, but frontends don't need to know about backends or other frontends, nor backends about frontends or other backends. In creating facilities, RTR ignores superfluous node names so that you can use the same CREATE FACILITY command on every node in an RTR configuration. This helps to simplify maintenance of startup command procedures.

For example, the same RTR CREATE FACILITY command shown in Example 2-2 can be issued on all nodes in the configuration. When issued on FE1, RTR ignores the list of backends because nodes only need to know about the nodes in the neighboring layers of the configuration, thus FE1 does not need to know about BE1.

Example 2-2 illustrates how to use RTR remote commands to start the same configuration. The SET ENVIRONMENT command is used to send commands to several RTR nodes.

Example 2-2 Remote Setup from One Node

% rtr RTR> set environment/node=(FE1, FE2, FE3, TR1, TR2, BE1, BR2, BR3) RTR> start rtr RTR> create facility funds_transfer/frontend=(FE1, FE2, FE3) - _RTR> /router=(TR1, TR2) - _RTR> /backend=(BE1, BE2, BE3)

This enters the commands on every node in the configuration. You must have an account with the necessary privileges on any node where the command is to execute.

Use the SHOW RTR command to find out if RTR has been started on a particular node.

Use the SHOW FACILITY command to see which facilities have been created and use the SHOW LINK comand to see how they are configured. The full syntax of these commands is given in Chapter 8. You can view the effect of these commands with the RTR web browser.

Every RTR backend must have a journal; an application with a callout server (which runs on the router) should have a journal on the router. The journal is used by the backend that must have physical access to the journal.

RTR writes data to journal files to be able to recover (that is, replay) partially executed transactions after a backend node failure. The journal file must be placed on a disk that is visible to nodes running RTR. If you locate your journal on a non-local disk, and the node accessing that disk goes down, RTR cannot access transactions in that journal until the failed node comes back up.

The amount of space required for the journal depends upon the:

• Size of the messages in a transaction
• Number of messages in the transaction
• Rate of generation of transactions
• Maximum time a shadow site can be out of commission

To size a journal, use the following rough estimates as guidelines:

• Allow 140 bytes per inbound message (C++ API SendApplicationMessage or C API rtr_send_to_server() call).
• Allow 140 bytes per transaction (C++ API AcceptTransaction or C API rtr_accept_tx() call).
• Allow 512 bytes per journal file for internal header information.
• Add an amount to accomodate your application message size.

Use of large transactions generally causes poor performance, not only for initial processing and recording in the database, but also during recovery. Large transactions fill up the RTR journal more quickly than small ones.

The /MAXIMUM_BLOCKS qualifier on the CREATE JOURNAL command controls how large a journal may become. The /MAXIMUM_BLOCKS qualifier defines the maximum number of blocks which the journal is allowed to occupy on any one disk. RTR does not check if this amount of space is actually available, as the disk space specified by /MAXIMUM_BLOCKS is used only on demand by RTR when insufficient space is available in the space allocated by the /BLOCKS qualifier.

The number of blocks specified by the /BLOCKS qualifier specifies the maximum size of the journal that RTR attempts to use. The actual number of blocks used may vary, depending upon the load on RTR.

The command MODIFY JOURNAL also accepts the /BLOCKS and /MAXIMUM_BLOCKS qualifiers.

Journal file extension occurs on demand when RTR detects that a "write to journal" would otherwise fail due to lack of space. Journal file truncation takes place periodically when enough free blocks are detected.

Refer to MODIFY JOURNAL for the syntax of the MODIFY JOURNAL command.

RTR> show journal/files/full RTR journal:- Disk: /dev/rz3a Blocks: 2500 Allocated: 1253 Maximum: 3500 File: //rtrjnl/anders/BRONZE.J00 RTR>

See Section 5.3, RTR Journal System, for information on how to calculate the size of the journal. Preferably, create your RTR journal on a disk in a recognized cluster.

To improve performance, the journal may be striped across several disks. Specify the location and size of the journal using the CREATE JOURNAL command.

Issue the CREATE JOURNAL command on each node where an application server will run, that is, on each backend node and on any router nodes where you intend to run router callout servers. It must be issued after installing RTR and before creating any facilities. It may be issued again later to alter the size or location of the journal to improve performance. Use the MODIFY JOURNAL command to adjust journal sizes.

The current maxima for the size of a journal are:

Number of 512-bytes blocks per disk: 524288
(This is max_segments_per_disk * disk_blocks_per_segment , or 16384 bytes times 32.)
Number of disks per journal: 16.

With fast shadow recovery, a node becomes primary active or secondary active as soon as it has copied all the transactions from the remembering node. Whether it becomes primary or secondary depends on its priority (established with the SET PARTITION/PRIORITY command). However, a large backlog of unprocessed transactions could cause what looks like a dual-site outage if a node immediately becomes primary active, because it must process the backlog before processing new transactions. Thus RTR ensures that a node processing a fast-recovery backlog becomes secondary active until it has caught up with the primary.

Only when it has caught up will it change to primary active state. MONITOR QUEUES includes the delay, in seconds, between when transactions arrive on a backend and when they are processed by a server application.

2.5 Changing Membership of a Facility

Using TRIM FACILITY

Use the TRIM FACILITY command to change RTR facility membership.

When using EXTEND FACILITY and TRIM FACILITY commands, make sure that the command is issued on all nodes that are affected. That is, all backend nodes must be informed when router configurations are changed and all router nodes must be informed when backend or frontend configurations are changed. For use of anonymous clients, see the description in the CREATE FACILITY command. In Figure 2-1, assume that the FE3 node is being removed from the funds_transfer facility. Since FE3 is a frontend for this facility, only the routers (TR1 and TR2) need be reconfigured.

Example 2-3 shows the commands necessary to achieve this reconfiguration.

Example 2-3 Reconfiguration Using TRIM FACILITY

% rtr RTR> set environment/node=FE3 (1) %RTR-S-COMARESEN, commands sent by default to node FE3 RTR> delete facility funds_transfer (2) %RTR-S-FACDELETE, facility funds_transfer deleted RTR> stop rtr/node=FE3 (3) %RTR-S-RTRSTOP, RTR stopped on node FE3 RTR> set environment/node=(TR1,TR2) (4) %RTR-S-COMARESEN, commands sent by default to node TR1 %RTR-S-COMARESEN, commands sent by default to node TR2 RTR> trim facility funds_transfer/frontend=FE3 (5) %RTR-S-FACTRIMMED, facility funds_transfer trimmed ----TR1------------------------------------------------------------- %RTR-S-FACTRIMMED, facility funds_transfer trimmed ----TR2------------------------------------------------------------- RTR>

1. Subsequent commands are executed on node FE3.
2. The facility is deleted on node FE3.
3. RTR is stopped on node FE3, the node being excluded from the network. To prevent transactions from being interrupted or aborted, application processes should be stopped in an orderly manner before issuing the STOP RTR command. Alternatively, a STOP RTR/ABORT command will force application processes using RTR to exit, aborting or interrupting any outstanding transactions. Active transactions will be sent to an existing shadow or standby node.
4. Subsequent commands are executed on nodes TR1 and TR2.
5. Node FE3 is removed from the facilities defined on nodes TR1 and TR2.

Using EXTEND FACILITY

In the example in Figure 2-1, assume that a new router node TR3 and new frontend FE4 are being added to the facility funds_transfer . The extended configuration is shown in Figure 2-2. This diagram shows the possible frontend to router connections. The frontend connects to only one router at a time.

Figure 2-2 Extend Configuration

All backend nodes must be informed when router configurations are changed. Because TR3 will be a router for the FE3 and FE4 frontends, these nodes must also be informed of its presence. Likewise, TR3 must be informed about FE3 and FE4, and all BEs must be informed of the new TR3.

Example 2-4 shows the EXTEND FACILITY command used for this reconfiguration.

Example 2-4 Reconfiguration Using EXTEND FACILITY

% RTR RTR> sho fac (1) ----BE1----------------------------------------------------------------- Facilities on node BE1 in group "user" at Wed Sep 25 13:53:03 2002 Facility Frontend Router Backend funds_transfer no no yes ----BE2----------------------------------------------------------------- Facilities on node BE2 in group "user" at Wed Sep 25 13:53:03 2002 Facility Frontend Router Backend funds_transfer no no yes ----BE3----------------------------------------------------------------- Facilities on node BE3 in group "user" at Wed Sep 25 13:53:03 2002 Facility Frontend Router Backend funds_transfer no no yes ----TR1----------------------------------------------------------------- Facilities on node TR1 in group "user" at Wed Sep 25 13:53:03 2002 Facility Frontend Router Backend funds_transfer no yes no ----TR2----------------------------------------------------------------- Facilities on node TR2 in group "user" at Wed Sep 25 13:53:03 2002 Facility Frontend Router Backend funds_transfer no yes no ----FE1----------------------------------------------------------------- Facilities on node FE1 in group "user" at Wed Sep 25 13:53:03 2002 Facility Frontend Router Backend funds_transfer yes no no ----FE2----------------------------------------------------------------- Facilities on node FE2 in group "user" at Wed Sep 25 13:53:03 2002 Facility Frontend Router Backend funds_transfer yes no no ----FE3----------------------------------------------------------------- Facilities on node FE3 in group "user" at Wed Sep 25 13:53:03 2002 Facility Frontend Router Backend funds_transfer yes no no RTR> start rtr /node=(TR3,FE4) (2) RTR> set environment/node= - (3) _RTR> (FE1,FE2,FE3,TR1,TR2,BE1,BE2,BE3,TR3,FE4) %RTR-S-COMARESEN, commands sent by default to node FE1 %RTR-S-COMARESEN, commands sent by default to node FE2 %RTR-S-COMARESEN, commands sent by default to node FE3 %RTR-S-COMARESEN, commands sent by default to node TR1 %RTR-S-COMARESEN, commands sent by default to node TR2 %RTR-S-COMARESEN, commands sent by default to node BE1 %RTR-S-COMARESEN, commands sent by default to node BE2 %RTR-S-COMARESEN, commands sent by default to node BE3 %RTR-S-COMARESEN, commands sent by default to node TR3 %RTR-S-COMARESEN, commands sent by default to node FE4 RTR> extend facility funds_transfer - (4) _RTR> /router=TR3/frontend=(FE3,FE4) - _RTR> /backend=(BE1,BE2,BE3) . . . ----TR3---------------------------------------------------------------- %RTR-S-FACEXTENDED, facility funds_transfer extended ----FE4---------------------------------------------------------------- %RTR-S-FACEXTENDED, facility funds_transfer extended -------------------------------------------------------------------------- RTR> extend facility funds_transfer - (5) _RTR> /router=TR1/frontend=(FE4) . . . RTR> sho fac funds_transfer ----TR3----------------------------------------------------------------- Facilities on node TR3 in group "user" at Wed Sep 25 13:52:16 2002 Facility Frontend Router Backend funds_transfer no yes no ----FE4----------------------------------------------------------------- Facilities on node FE4 in group "user" at Wed Sep 25 14:04:49 2002 Facility Frontend Router Backend funds_transfer yes no no ---------------------------------------------------------------------------