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

• Chapter 1 provides an introduction to the RTR Web Browser Interface and Command Line Interface (CLI) and explains how to use local and remote commands and command procedures.
• Chapter 2 explains how to start and configure RTR.
• Chapter 3 describes RTR's Partition Management.
• Chapter 4 provides an overview of RTR's Transaction Management tools.
• Chapter 5 describes server shadowing and recovery.
• Chapter 6 describes how the RTR monitor is used to continuously observe the performance and operation of RTR and applications using RTR.
• Chapter 7 describes how to use the CLI interface to RTR API calls and contains a complete description of all RTR commands, listed alphabetically.
• Appendix A explains how to create your own monitor pictures for special monitoring needs.
• Appendix B explains how to customize the appearance of HTML pages generated by RTR. It also explains server security.
• Appendix C describes how to use RTR with XA in an ORACLE environment.
• Appendix D identifies ways to diagnose and correct problems in RTR networks.
• Appendix E contains a list of all the error messages that can be returned by the RTR CLI.
• Appendix F contains a list of all messages that RTR can write to the RTR log.

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 rtrdoc@compaq.com .

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

Conventions

Table 1 describes the conventions used in this guide.

Table 1 Conventions Used in this Guide

Convention	Meaning
UPPERCASE lowercase	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

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:

   /access=read_only
   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
   OpenVMS	RTR$DIRECTORY
   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.

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

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:

• On UNIX

  % rtr call rtr_send_to_server '"Message text"'/channel=c

• On OpenVMS

  $ rtr call rtr_send_to_server """Message text"""/channel=c

• On Windows Systems

  C:\ rtr call rtr_send_to_server """Message text"""/channel=c

  
  or

  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>

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

or:

% rtr @createfacil

or at the RTR prompt:

% rtr RTR> execute createfacil

or:

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.

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.