Reliable Transaction Router

Reliable Transaction Router

System Manager's Manual

Order Number: AA-Q88CF-TE

August, 2001

This manual describes how to configure, manage and monitor Reliable Transaction Router, Version 4.1 (RTR).

Revision/Update Information: This manual supersedes the Reliable Transaction Router System Manager's Manual, Version 4.0 .

Software Version: Reliable Transaction Router, Version 4.1

Compaq Computer Corporation
Houston, Texas

© 2001 Compaq Computer Corporation

Compaq, the Compaq logo, DEC, and VAX Registered in U.S. Patent and Trademark Office.

DECnet, OpenVMS, and Tru64 are trademarks of Compaq Information Technologies Group, L.P. in the United States and other countries.

Microsoft, MS-DOS, Visual C++, Windows, and Windows NT are trademarks of Microsoft Corporation in the United States and other countries.
Intel is a trademark of Intel Corporation in the United States and other countries.
UNIX is a registered trademark of The Open Group in the United States and other countries..

All other product names mentioned herein may be trademarks of their respective companies.

Confidential computer software. Valid license from Compaq or authorized sublicensor required for possession, use, or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S.Government under vendor's standard commercial license.

Compaq shall not be liable for technical or editorial errors or omissions contained herein. The information in this publication is provided "as is" without warranty of any kind and is subject to change without notice. The warranties for Compaq products are set forth in the express limited warrant statements accompanying such products. Nothing herein should be construed as constituting an additional warranty.

Contents Index


Purpose of this Manual

This manual describes how to configure, manage and monitor the operation of Reliable Transaction Router (RTR) using the RTR Command Line Interface (CLI) and the Web Browser Interface.

Intended Audience

The System Manager's Manual is intended for persons who perform system management functions to configure, test, monitor and maintain RTR applications.

The reader is assumed to be familiar with their operating system, but not necessarily experienced with RTR operations.

New users of RTR are encouraged to read RTR Getting Started for an introduction and general overview of RTR.

Structure of Document

The manual contains the following chapters and appendices:

Related Documentation

Document Content
For all users:  
Reliable Transaction Router Getting Started Provides an overview of RTR technology concepts and solutions.
RTR Commands Card Lists all RTR commands, their qualifiers and defaults.
Reliable Transaction Router Release Notes Describes new features, changes, and known restrictions for RTR.
For the system manager:  
Reliable Transaction Router Installation Guide Describes how to install RTR on all supported platforms.
Reliable Transaction Router System Manager's Manual Describes how to configure, manage, and monitor RTR.
Reliable Transaction Router Migration Guide Explains how to migrate from RTR Version 2 to RTR Version 3 (OpenVMS only).
For the application programmer:  
Reliable Transaction Router Application Design Guide Describes how to design application programs for use with RTR, illustrated with both the C and C++ interfaces.
Reliable Transaction Router C++ Foundation Classes Describes the object-oriented C++ interface that can be used to implement RTR object-oriented applications.
Reliable Transaction Router C Application Programmer's Reference Manual Explains how to design and code RTR applications using the C programming language; contains full descriptions of the basic RTR API calls.

Reader's Comments

Compaq welcomes your comments on this manual. Please send us your comments by email to .

Include the title of the manual, section and page numbers with your comments or suggestions.


Table 1 describes the conventions used in this guide.

Table 1 Conventions Used in this Guide
Convention Meaning
Some operating systems differentiate between lowercase and uppercase characters. For these systems, examples, syntax descriptions, function definitions, and literal strings that appear in text must be typed exactly as shown. Commands typed to the RTR CLI are not case sensitive unless enclosed in quote marks
# A number sign (#) is the default operating system superuser prompt.
% A percent sign (%) is the default operating system user prompt on UNIX systems.
$ A dollar sign ($) is the default operating system user prompt on OpenVMS systems.
[Return] In examples, a boxed symbol indicates that you must press the named key on the keyboard.
Ctrl/C This symbol indicates that you must press the Ctrl key while you simultaneously press another key (in this case, C).
user input In interactive examples, this typeface indicates input entered by the user.
italic text Italic text emphasizes important information, indicates variables, and indicates complete titles of manuals. Italic text also represents information that can vary in system messages (for example, internal error number), command lines (for example, /PRODUCER= name), and command parameters in text.
boldface text Boldface text represents the introduction of a new term or the name of an argument, an attribute, or a reason.
UPPERCASE TEXT Uppercase text indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege.
system output This typeface is used in interactive and code examples to indicate system output.
[y] In a prompt, square brackets indicate that the enclosed item is the default response. For example, [y] means the default response is Yes.
text | A vertical bar next to the text | indicates changes or additions since the previous version of this document.

Reading Path

The reading path to follow when using the Reliable Transaction Router information set is show in Figure 1.

Figure 1 RTR Reading Path

Chapter 1

For a general introduction to Reliable Transaction Router (RTR) Version 4.1, you should read Reliable Transaction Router Getting Started. Additional information about RTR is available in the Reliable Transaction Router C Application Programmer's Reference Manual.

To use RTR, you must first install the RTR software and your application. See the Reliable Transaction Router Installation Guide for instructions on how to install RTR.

1.1 Initial Setup

RTR applications use the API calls described in the Reliable Transaction Router C Application Programmer's Reference Manual and the Reliable Transaction Router C++ Foundation Classes. Before an RTR application can be used, RTR must be started on every node in your RTR network. You do this by issuing a START RTR command on each node. You may decide to include the START RTR command in a startup command procedure for each node. This allows RTR to be started whenever a node is booted.

After RTR is started, you must create RTR's recovery journal files on specified disks. Use the CREATE JOURNAL command to create the files.

A separate facility must be defined for each application. An RTR facility is the user-defined name for a configuration that provides the mapping between nodes and roles for a given application. Before application processes are started, use the CREATE FACILITY command to define a facility. You may choose to include the CREATE FACILITY command in the command procedure used to start the application.

The rest of this chapter explains how to use RTR commands. The START RTR and CREATE FACILITY commands are described in detail in Chapter 2 and Chapter 7.

1.2 Entering Commands

RTR is started, configured, and maintained by using either the RTR web browser interface or the RTR Command Line Interface (CLI). The commands available using the browser interface or the CLI are used to start, set up, and monitor the operation of RTR. The following sections describe how to use each of the interfaces.

1.2.1 Web Browser Interface

To begin accessing the web-based management functions, follow these steps:

  1. Start the HTTP server on the target computer system by using the following command:

     % rtr start http_server

    This command must be issued for each user of the management features. The system manager can issue the command on behalf of each user when the system starts up, or each user can issue the command by logging in to the target system or by issuing a remote command such as rsh .
    The following qualifier is accepted:

    The servers can be started in read-only mode. In this mode they honor only the equivalent of command line interface commands SHOW and MONITOR requests.
  2. Start the browser interface by opening the file rtr_main.html . This file is located in one of the following operating system-dependent directories where RTR is installed:
    Server Operating System File Location
    UNIX /rtr
    Windows RTR Installation Directory

    If RTR is not installed on the computer where the browser is running, use the URL http://<hostname>:46000/rtr_main.html to download RTR from a system where the HTTP server has been started.
  3. When the introductory screen appears, enter the name of the node or a comma-separated list of computers on which you want to manage RTR.
  4. A system status screen is displayed, along with a menu of commands which are available through the web browser interface. Figure 1-1 shows the introductory screen.

Figure 1-1 Web Browser Interface

Most of the commands accepted by the command line interface are also available through the web browser interface. The browser interface provides context-sensitive help for all available commands where user input is required.


In the browser interface, node lists are built from the contents of the local hosts file. Compaq recommends that you add the names and addresses of current and potential nodes in your configuration to the local hosts file.

For information about server security and customizing the appearance of the RTR web browser interface, see Appendix B.

1.2.2 Command Line Interface (CLI)

The RTR CLI is accessed by entering RTR at the operating system prompt. Commands can either be entered on the same line as the RTR verb:

 % rtr command

or, when several commands are to be entered at the RTR prompt:

 % rtr
 RTR> start rtr
 RTR> create journal


For convenience, the user prompt for the operating system is shown here as the percent (%) symbol. Your system may show a different prompt.

The RTR CLI accepts commands that you type and can process procedures consisting of RTR commands.

Most RTR commands accept qualifiers which are indicated by the forward slash (/) character. For example, many RTR commands accept the /OUTPUT qualifier; it directs the output from the command to a file.

The forward slash (/) character may also appear in the file names of some operating systems; such file names must be enclosed in quotation marks to ensure that RTR does not interpret the file name as a command qualifier.

When RTR commands are entered on a single line, you may need to use extra quotation characters, depending on the operating system in use. For example, when you enter the following command at the RTR prompt, it takes the following format:

RTR> call rtr_send_to_server "Message text"/channel=c 

If you enter the above command from the operating system command line, you must use additional quotation marks:

1.2.3 Online Help for RTR CLI

You can get information about the RTR CLI by using the HELP command. The following command displays a complete list of help topics on your terminal.

 % rtr help

If you require additional information, enter the topic directly on the same line.

 % rtr help show

The HELP command can also be used to identify errors returned by RTR. The following sequence returns the error identifier:

 % rtr help errors error-identification

where error-identification is the identification part of the returned error. The following sequence returns an error message, RTRALRSTA , which can then be explained by the help errors rtralrsta command option:

 %  rtr             
 RTR> start rtr
 %RTR-F-RTRALRSTA, rtr already started
 RTR> help errors rtralrsta
 RTR already started
     Explanation: RTR was already running when the "START RTR" command
     was executed. This error message is displayed by the RTR utility.

1.3 Command Procedures

RTR commands can also be written in a command file and then executed as a procedure using the EXECUTE filespec or @filespec commands.

 % rtr execute createfacil


 % rtr @createfacil

or at the RTR prompt:

 % rtr
 RTR> execute createfacil


 RTR> @createfacil

1.4 Remote Commands

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

If you use a 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. Remote task objects must be enabled.

Refer to your operating system documentation for more information.

To specify the remote node names explicitly:

 RTR> command/node=node-list

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

  RTR> command/cluster

This command starts RTR on three nodes:

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

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.


The /CLUSTER and /NOCLUSTER command qualifiers refer to cluster support. These qualifiers are used in operating systems such as OpenVMS that fully support clustering and that support the remote command capability. Using the /CLUSTER qualifier on systems that do not support clustering causes the relevant command to be executed on the local node only. For example, certain Windows systems do not support clustering.

To enable the remote command capability, use the following:
On this operating system: Use:
OpenVMS SYSMAN Utility
UNIX rsc
Windows remote shell

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

For example:

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

This example shows the use of the SET ENVIRONMENT command to stop RTR on Node A and Node C. More details concerning the commands used in the above examples are contained in Section 7.2.

Next Contents Index