Order Number: AA-Q88CE-TE

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

Revision/Update Information: This manual supersedes Version 3.1D of the System Manager's Manual

Software Version: Reliable Transaction Router, Version 3.2

Compaq Computer Corporation
Houston, Texas

COMPAQ COMPUTER CORPORATION SHALL NOT BE LIABLE FOR TECHNICAL OR EDITORIAL ERRORS OR OMISSIONS CONTAINED HEREIN, NOR FOR INCIDENTAL OR CONSEQUENTIAL DAMAGES RESULTING FROM THE FURNISHING, PERFORMANCE, OR USE OF THIS MATERIAL. THIS INFORMATION IS PROVIDED "AS IS" AND COMPAQ COMPUTER CORPORATION DISCLAIMS ANY WARRANTIES, EXPRESS, IMPLIED OR STATUTORY AND EXPRESSLY DISCLAIMS THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR PARTICULAR PURPOSE, GOOD TITLE AND AGAINST INFRINGEMENT. This publication contains information protected by copyright. No part of this publication may be photocopied or reproduced in any form without prior written consent from Compaq Computer Corporation.

Copyright ©1999 Digital Equipment Corporation

The software described in this guide is furnished under a license agreement or nondisclosue agreement. The software may be used or copied only in accordance with the terms of the agreement.

Compaq and the Compaq logo are registered in the United States Patent and Trademark Office.

The following are trademarks of Compaq Computer Corporation: AlphaGeneration, AlphaServer, AlphaStation, Compaq Internet Personal Tunnel, DEC, DECconnect, DECdtm, DECnet, DIGITAL, OpenVMS, PATHWORKS, POLYCENTER, Reliable Transaction Router, TruCluster, Tru64 UNIX, VAX, and VMScluster.

The following are third-party trademarks:

AIX and IBM are registered trademarks of International Business Machines Corporation.
Encina is a registered trademark of Transarc Corporation.
Hewlett-Packard and HP-UX are registered trademarks of Hewlett-Packard Company.
Intel is a trademark of Intel Corporation.
Microsoft, Microsoft Access, Microsoft SQL Server, Internet Explorer, :MS--DOS, Visual Basic, Visual C++, Windows, Windows 95, Windows 98, and Windows NT are trademarks or registered trademarks of Microsoft Corporation.
Netscape, Netscape Communicator, and Netscape Navigator are registered trademarks of Netscape Communications Corporation.
Oracle, ORACLE7, PL/SQL, SQL*Net, AND SQL*Plus are trademarks or registered trademarks of Oracle Corporation.
Solaris, SPARCstation, SUN, SunOS, and Sunlink are trademarks or registered trademarks of Sun Microsystems, Inc.
UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company, Ltd.

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

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 the first chapters of the Application Programmer's Reference Manual for a overall description of RTR.

Structure of Document

The manual contains the following chapters and appendices:

• Chapter 1 is an introduction to the RTR Command Line Interface (CLI) and tells you 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 gives an overview of RTR's Transaction Management tools.
• Chapter 5 describes how the RTR monitor is used to continuously observe the performance and operation of RTR and applications using RTR.
• Chapter 6 describes how to use the CLI interface to RTR API calls and contains a complete description of all RTR commands, listed alphabetically.
• Appendix A tells you how to create your own monitor pictures for special monitoring needs.
• Appendix B describes server shadowing and recovery.
• Appendix C describes how to use RTR with XA and ORACLE.
• Appendix D contains a list of all the error messages that can be returned by the RTR CLI.
• Appendix E contains a list of all messages that RTR can write to the RTR log.

Related Documentation

• Release Notes
• Installation Guide
• Application Programmer's Reference Manual
• Application Design Guide
• Migration Guide

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.
filesystem	In text, this typeface indicates the exact name of a command, routine, partition, pathname, directory, or file. This typeface is also used in interactive examples and other screen displays.
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 a command, an argument, an attribute, or a reason.
[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.
HTML	Red HTML text indicates changes or additions since the previous version of this document.

For a general introduction to Reliable Transaction Router, Version 3.2 (RTR), you should read the introductory chapter in the Reliable Transaction Router Application Design Guide. Additional information about the Reliable Transaction Router is available in the Reliable Transaction Router Application Programmer's Reference Manual.

In order to use RTR, you must install the RTR software and your application. See the Reliable Transaction Router Installation Guide for instructions for installing RTR.

1.1 Getting Started

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

Many applications can use RTR at the same time without interfering with one another. This is achieved by defining a separate facility for each application. A facility can be thought of as an application's own runtime environment of RTR. (In addition, distributed RTR applications may start and execute many transactions. RTR is capable of massively parallel operation.)

Before application processes are started, a facility must be defined using the CREATE FACILITY command. You may wish to include the CREATE FACILITY command to 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 6.

1.2 Entering Commands

RTR is started, configured and maintained by using the RTR Command Line Interface (CLI). The RTR CLI is used to start, set up and monitor the operation of RTR.

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, for example:

% 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: these 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 filenames of some operating systems; such filenames must be enclosed in quotation marks to ensure that RTR does not interpret the filename 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 running on most UNIX platforms, additional single quotation marks are required when entering quoted items such as filenames. Compare the following commands.

% rtr RTR> show facility/output="/usr/users/test/fac_output.lis"

% rtr show facility/output='"/usr/users/test/fac_output.lis"'

The first command works for OpenVMS systems but not on UNIX. The second command uses single quotation marks outside of double quotations to be correctly interpreted on UNIX systems.

1.3 Online Help

You can get information about the RTR CLI by using the HELP command. Entering the following command:

% rtr help

displays a complete list of help topics on your terminal.

If you require additional information then enter the topic directly on the same line, for example:

% rtr help show

The help command can also be used to find out about errors returned by RTR. The folowing 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, that 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.4 Command Procedures

RTR commands can also be written in a command file and then executed as a procedure using the EXECUTE file-spec or @file-spec commands. For example:

% rtr execute createfacil

or:

% rtr @createfacil

or at the RTR prompt:

% rtr RTR> execute createfacil

or:

RTR> @createfacil

1.5 Remote Commands

Most RTR commands can be issued either locally (the default) or on one or more remote nodes. To be able to issue commands to a remote node you must have an account on that node with the necessary access privileges. Refer to your operating system documentation for information on how to set up the access privileges.

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

Examples:

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

This command starts RTR on the three nodes.

If several commands need to be executed remotely on the same nodes then the set environment command can be used 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 6.2.

This chapter describes how to configure and start an RTR environment. Recovery journals, router load balancing and call-out 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:

• You can log on to each node in turn and issue the commands interactively.
• You can log on to one node and use the remote command capability to configure all the nodes from one session.
• You can 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, the last method more suited to a production environment.

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

2.2 Setting Up---An Example

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

Figure 2-1 Configuration Example

In this example, the application client processes run on the nodes FE1, FE2 and FE3. The servers run on BE1, BE2 and BE3. Nodes TR1 and TR2 are routers and have no application processes running on them. This diagram shows all possible connections. The frontend connects to only one router at a time.

Example 2-1 shows the commands that have to 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 RTR> start rtr RTR> create facility funds_transfer/frontend=FE1 - _RTR> /router=(TR1, TR2)

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

% rtr RTR> start rtr RTR> create facility funds_transfer/router=(TR1, TR2) - _RTR> /backend=BE1

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.

Note that nodes only need to know about the nodes in the neighbouring layers of the hierarchy, thus FE1 does not need to know about BE1. Superfluous node names are ignored. This allows you to issue the same CREATE FACILITY command on every node to simplify the maintenance of startup command procedures.

Example 2-2 illustrates how to use RTR remote commands to start the same configuration. The set environment command is used to send subsequent commands to a number of RTR nodes.

Example 2-2 Remote Setup from one Node

% rtr RTR> set environment/node= - _RTR> (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)

You can enter the commands shown in Example 2-2 on any of the nodes in the configuration. However, you must have an account with the necessary privileges on the other nodes.

To find out if RTR has been started on a particular node, use the SHOW RTR command.

To find out which facilities have been created (if any) and how they are configured you can use the SHOW FACILITY and SHOW LINK commands. The full syntax of these commands is given in Chapter 6.

2.3 Creating a Recovery Journal

RTR writes data to journal files to be able to recover (that is, replay) partially executed transactions after a backend node failure.

For performance reasons, the journal may be spread across several disks. Specify the location and size of the journal using the CREATE JOURNAL command.

The CREATE JOURNAL command must be issued on each node where an application server will run. That is, on each backend node and on any router nodes where router call-out servers will run. 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.