Reliable Transaction Router

Reliable Transaction Router

System Manager's Manual

Order Number: AA-Q88CE-TE


June, 1999

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


June, 1999

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


Preface

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:

Related Documentation

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.


Chapter 1
Introduction

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

Note

For convenience, the user prompt for the operating system is shown here as the "%" symbol. Your system may have a different prompt.

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.

Note

The /CLUSTER and /NOCLUSTER command qualifiers refer to cluster support. These qualifiers are for operating systems that fully support clustering. Use of the /CLUSTER qualifier on systems that do not have clustering causes the relevant command to be executed on the local node only. For example Windows 95 systems do not support clustering.

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.


Chapter 2
Starting and Setting Up RTR

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:

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.

Cautionary Note for Journals

  • The CREATE JOURNAL/SUPERSEDE command deletes the contents of any existing journal files. If transaction recovery is required, DO NOT ISSUE this command after a failure.
  • Do not make backup copies of journal files without first making the original journal file read-only or the journal files will be considered spurious by RTR because it sees journal files that it did not create. In this case RTR will issue a %RTR-F-SPUJOUFIL error message.
  • The operator should move any duplicate copies of journal files to a location other than the rtrjnl/groupname directory so that RTR will see only the one it created.
  • Track duplicate copies of journal files in the log file to prevent RTR seeing more than the one it created and issuing the SPUJOUFIL error message.
  • If it is determined that a journal is SPURIOUS by means other than improper copying, then a backup copy followed by a destruction of the transactions contained in a journal can be performed by the CREATE JOURNAL/SUPERCEDE command.


Next Contents Index