hp Reliable Transaction Router

System Manager's Manual

Order Number: AA-Q88CG-TE

April 2003

This manual describes how to configure, manage, and monitor HP Reliable Transaction Router.

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

Software Version: Reliable Transaction Router Version 4.2

Hewlett-Packard Company Palo Alto, California

Microsoft, MS-DOS, Windows, and Windows NT are US registered trademarks of Microsoft Corporation.

Intel is a US registered trademark of Intel Corporation.

UNIX is a registered trademark of The Open Group.

Confidential computer software. Valid license from HP and/or its subsidiaries 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 commercial license.

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

Contents Index

Preface

Purpose of this Manual

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

Intended Audience

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

Readers are assumed to be familiar with the operating systems on which RTR and its applications are running.

For an introduction and general overview of RTR, read the Reliable Transaction Router Getting Started manual.

Structure of Document

The manual contains the following chapters and appendices:

Chapter 1 introduces the RTR web browser, the RTR Command Line Interface (CLI) and the RTR online help system, and explains how to use local commands, command procedures, and remote commands.
Chapter 2 explains how to configure and start RTR.
Chapter 3 describes how to use RTR to manage partitions.
Chapter 4 provides information on managing transactions with RTR.
Chapter 5 describes RTR server shadowing and recovery.
Chapter 6 identifies ways to diagnose and correct problems in RTR networks.
Chapter 7 describes how to use RTR to monitor and observe the performance and operation of RTR and applications that use RTR.
Chapter 8 describes all RTR commands. Commands are 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 RTR web browser HTML pages, and explains server security.
Appendix C describes how to use RTR with XA in an ORACLE environment.
Appendix D contains the list of messages that can be returned by RTR, by either the RTR browser interface, the RTR CLI, or by applications that run RTR.
Appendix E contains a list of all messages that RTR can write to the RTR log.

**Table 1 RTR Documents**
Document	Content
For all users:
Reliable Transaction Router Release Notes ¹	Describes new features, changes, and known restrictions for RTR.
Reliable Transaction Router Getting Started	Provides an overview of RTR technology and solutions, and includes the glossary that defines all RTR terms.
Reliable Transaction Router Commands	A pocket-sized handbook that lists all RTR commands, their qualifiers and defaults.
Reliable Transaction Router Software Product Description	Describes product features.


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 or 4 (OpenVMS only).

For the application programmer:
Reliable Transaction Router Application Design Guide	Describes how to design application programs for use with RTR, with both 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 and the RTR C API. Contains full descriptions of the basic RTR API calls.

Reader's Comments

HP welcomes your comments on this manual. Please send us your comments by email to rtrdoc@hp.com .

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

Conventions

Table 2 describes the conventions used in this guide.

Table 2 Conventions Used in this Guide
Convention Meaning

UPPERCASE
lowercase Some operating systems differentiate between lowercase and uppercase characters. For these systems, you must enter examples, syntax descriptions, function definitions, and literal strings exactly as shown. Commands typed to the RTR CLI are not case sensitive unless enclosed in quotation marks.

# A number sign (#) is the default operating system superuser prompt on UNIX systems.

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

- In command line examples, a hyphen (-) is the continuation character, allowing a long comand to be continued on the following line.

**Table 2 Conventions Used in this Guide**
Convention	Meaning
UPPERCASE lowercase	Some operating systems differentiate between lowercase and uppercase characters. For these systems, you must enter examples, syntax descriptions, function definitions, and literal strings exactly as shown. Commands typed to the RTR CLI are not case sensitive unless enclosed in quotation marks.
#	A number sign (#) is the default operating system superuser prompt on UNIX systems.
%	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 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.
-	In command line examples, a hyphen (-) is the continuation character, allowing a long comand to be continued on the following line.

Reading Path

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

Figure 1 RTR Reading Path

Chapter 1
Introduction

For a general introduction to Reliable Transaction Router (RTR), read the Reliable Transaction Router Getting Started manual. This is a prerequisite before using this manual for the system manager. Additional information about RTR is available in the other documents in the Reliable Transaction Router information set and from the RTR web browser and command line interfaces.

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

RTR applications can use the C API calls described in the Reliable Transaction Router C Application Programmer's Reference Manual and the C++ API classes described in the Reliable Transaction Router C++ Foundation Classes manual.

1.1 Initial Setup

Before an RTR application can be used, RTR must be started on every node that is defined as part of your RTR configuration. You do this by issuing a START RTR command on each node. You can include the START RTR command in a startup command procedure, script or .bat file for each node, starting RTR whenever a node is booted. For details on how to use such procedures, see your operating system documentation.

After RTR is started, you must create RTR's recovery journal files on specified disks. Use the RTR CREATE JOURNAL command to create journal files. You should also create a log file to log RTR messages with the RTR SET LOG command.

A separate facility must be defined for each application. An RTR facility is the user-defined name that provides the mapping between nodes and roles for a given application. Before starting application processes, use the RTR 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. For examples of configurations, see the Reliable Transaction Router Getting Started manual.

1.2 Administering RTR and RTR Applications

RTR is started, configured, and maintained by using either the RTR web browser interface or the RTR Command Line Interface (CLI). Either interface is used to start, set up, and monitor the operation of RTR. An application written with the C++ API can also start RTR. For more information on system management from an application, see the Reliable Transaction Router C++ Foundation Classes manual.

1.2.1 RTR Web Browser Interface

To access the RTR web-based system management functions, follow these steps:

From the OpenVMS or Tru64 UNIX system prompt, 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.
Operating System Prompt Symbol
The user prompt for the operating system is shown here as the percent (%) symbol. Your system may show a different prompt.

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 .
On Windows, with RTR installed, click Start then Programs then Compaq then RTR then Reliable Transaction Router. The RTR command window will be displayed. Start the http server with the start http_server command.
(The following qualifier to the start http_server command starts the servers as read-only:
/access=read_only
Read-only servers execute only the equivalent of the command-line-interface commands SHOW and MONITOR.)

Start the RTR Manager browser 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 display the RTR Manager screen from a system where the HTTP server has been started.

The RTR node dialog box, Figure 1-1, appears. Enter the name of the node where you will run RTR. To enter multiple node names, separate them with commas.
Figure 1-1 RTR Node Dialog Box
The RTR Security dialog box, Figure 1-2, appears. Enter your username and password. This dialog box may appear twice, as it is controlled by the browser interface, Microsoft Internet Explorer or Netscape Navigator.

Figure 1-2 RTR Security Dialog Box
The RTR Manager screen, Figure 1-3, appears.
Figure 1-3 RTR Manager Interface

Most of the commands accepted by the command line interface are also available through the RTR Manager screen when you click on the RTR Command link. In addition, the browser interface provides context-sensitive help for all available commands where user input is required, informational popups on certain headings such as "Resource," and details of a facility, partition, link, or transaction with links through browser popups. For example, to see details of a defined partition, click on the "show partition x details" popup seen when placing your mouse on a blue-underlined partition name.

Node Lists

In the browser interface, node lists are built from the contents of the local hosts file. You should add the names and addresses of current and potential nodes in your configuration to the local hosts file. In some cases you must enter the fully-qualified path name such as http://node.domain , to reach the node you want to manage, in facility definitions, and when using a web browser.

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

1.2.2 Command Line Interface (CLI)

You access the RTR CLI by entering RTR at the operating system prompt. You can enter commands on the same line as the RTR verb or you can enter several commands at the RTR prompt. For example, this example shows a one-line command:

% rtr command

This example shows a multiple-line set of commands:

% 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, 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 marks, depending on the operating system in use. For example, when you enter the following command at the RTR prompt, use 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. For example,

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:

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

or

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

1.2.3 Online Help for the RTR CLI

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

% rtr help

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

% rtr help show

You can also use the HELP ERRORS command to further explain errors returned by RTR.

% rtr help errors error-identification

where error-identification identifies the returned error.

In the following example, a message is received with the identifier RTRALRSTA and a brief explanation. Further explanation can be obtained by using the help errors rtralrsta command.

% 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 be written in a command file, script, .cmd or .bat file and then executed as a procedure using the RTR EXECUTE filespec or @filespec commands.

For example, on a UNIX or Windows system:

% rtr execute createfacil

or:

% rtr @createfacil

or at the RTR prompt:

% rtr RTR> execute createfacil

or on an OpenVMS system:

RTR> @createfacil

Batch Procedure/Command File Restriction

The last line of a batch procedure or command file must explicitly end with <CRLF> added by pressing the Enter/Return key when creating the procedure. Without the explicit <CRLF>, RTR ignores the line. The workaround is to add a comment to the end of the file or to explicitly add <CRLF> to the end of the last line of the batch procedure.

Contents

Index