Order Number: AA-Q88CF-TE
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
© 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.
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.
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.
The manual contains the following chapters and appendices:
|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.|
Compaq welcomes your comments on this manual. Please send us your comments by email to firstname.lastname@example.org .
Include the title of the manual, section and page numbers with your comments or suggestions.
Table 1 describes the conventions used in this guide.
|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.|
The reading path to follow when using the Reliable Transaction Router information set is show in Figure 1.
Figure 1 RTR Reading Path
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:
% rtr start http_server
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.
|Server Operating System||File Location|
|Windows||RTR Installation Directory|
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:
% rtr call rtr_send_to_server '"Message text"'/channel=c
$ rtr call rtr_send_to_server """Message text"""/channel=c
C:\ rtr call rtr_send_to_server """Message text"""/channel=c
C:\ rtr call rtr_send_to_server \"Message text\"/channel=c
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 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. RTR>
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
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:
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:
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:|
To execute several commands remotely on the same nodes, use the SET ENVIRONMENT command to save typing.
% 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.