Compaq AA-Q88CE-TE User Manual

ReliableTransactionRouter
SystemManager’sManual

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.

© Digital Equipment Corporation 1999. All Rights Reserved..
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.

This document was prepared using VAX DOCUMENT, Version 2.1.

Contents

Preface ............................................................ xi

1 Introduction

1.1 Getting Started ............................................. 1–1

1.2 Entering Commands . ........................................ 1–1

1.3 Online Help ................................................ 1–2

1.4 Command Procedures ........................................ 1–3

1.5 Remote Commands . . ........................................ 1–3

2 Starting and Setting Up RTR

2.1 Introduction ................................................ 2–1

2.2 Setting Up—An Example ...................................... 2–1

2.3 Creating a Recovery Journal . . . ................................ 2–3

2.4 Changing a Facility . . ........................................ 2–4

2.5 Setting up Callout Servers ..................................... 2–7

2.6 Router Load Balancing........................................ 2–8

2.7 RTR Privileges .............................................. 2–9

2.8 RTR ACP Virtual Memory Sizing ................................ 2–10

2.8.1 OpenVMS Virtual Memory Sizing ............................ 2–10

2.8.2 UNIX Virtual Memory Sizing ................................ 2–12

2.9 Network Transports . . ........................................ 2–13

2.9.1 Specifying the Link Transport Protocol . ....................... 2–13

2.9.2 Using RTR with DHCP and Internet Tunnels ................... 2–14

2.9.3 Interoperation with RTR Version 2 Using DECnet ............... 2–15

2.10 Network Protocol Selection on OpenVMS . . ....................... 2–16

2.11 Running RTR as a Service on Windows NT . ....................... 2–16

2.11.1 Customizing the RTR Windows NT Service ..................... 2–17

2.11.2 Files Created by the RTR Windows NT Service . . . ............... 2–17

2.12 How RTR Selects Processing-states (Roles) for Nodes . ............... 2–18

2.12.1 Role Assignment for Backend Node Partitions ................... 2–18

2.12.2 Router Selection . . ........................................ 2–21

3 Partition Management

3.1 Overview . . ................................................ 3–1

3.1.1 What is a Partition? ....................................... 3–1

3.1.2 What is Partition Management? ............................. 3–1

3.2 Partition Naming ............................................ 3–2

3.2.1 Default Partition Names . . . ................................ 3–2

3.2.2 Programmer Supplied Names ............................... 3–2

3.2.3 System Manager Supplied Partition Names..................... 3–2

3.2.4 Name Format and Scope . . . ................................ 3–2

iii

3.3 Life Cycle of a Partition . . . .................................... 3–2

3.3.1 Implicit Partition Creation .................................. 3–3

3.3.2 Explicit Partition Creation .................................. 3–3

3.3.3 Persistence of Partition Definitions ........................... 3–3

3.4 Binding Server Channels to Named Partitions . . ................... 3–3

3.5 Entering Partition Commands .................................. 3–4

3.5.1 Command Line Usage . .................................... 3–4

3.5.2 Programmed Partition Management .......................... 3–4

3.6 Managing Partitions ......................................... 3–5

3.6.1 Controlling Shadowing . .................................... 3–5

3.6.1.1 Command Line Example ................................ 3–5

3.6.1.2 Programming Information . . . ............................ 3–5

3.6.2 Controlling Transaction Presentation.......................... 3–6

3.6.2.1 Command Line Example ................................ 3–6

3.6.2.2 Programming Information . . . ............................ 3–6

3.6.3 Controlling Recovery . . .................................... 3–6

3.6.3.1 Command Line Example ................................ 3–7

3.6.3.2 Programming Information . . . ............................ 3–7

3.6.4 Controlling the Active Site .................................. 3–7

3.6.4.1 Command Line Example ................................ 3–7

3.6.4.2 Programming Information . . . ............................ 3–8

3.6.5 Controlling Failover . . . .................................... 3–8

3.6.5.1 Command Line Example ................................ 3–8

3.6.5.2 Programming Information . . . ............................ 3–8

3.6.6 Controlling Transaction Replay . . ............................ 3–9

3.6.6.1 Command Line Example ................................ 3–9

3.6.6.2 Programming Information . . . ............................ 3–9

3.7 Displaying Partition Information ................................ 3–10

3.7.0.1 Command Line Example ................................ 3–10

4 Transaction Management

4.1 Overview .................................................. 4–1

4.1.0.1 Command Line Examples . . . ............................ 4–2

4.1.1 Exception Transactions .................................... 4–2

4.1.2 Transaction State Changes ................................. 4–3

5 RTR Monitoring

5.1 Introduction ................................................ 5–1

5.2 Standard Monitor Pictures . .................................... 5–1

5.2.1 Monitor ACCFAIL (Link Acceptance Failures) ................... 5–4

5.2.2 Monitor ACP2APP ........................................ 5–5

5.2.3 Monitor Active ........................................... 5–6

5.2.4 Monitor APP2ACP ........................................ 5–6

5.2.5 Monitor Broadcast ........................................ 5–6

5.2.6 Monitor Calls ............................................ 5–7

5.2.7 Monitor Channel ......................................... 5–7

5.2.8 Monitor Connects ......................................... 5–7

5.2.9 Monitor Event ........................................... 5–8

5.2.10 Monitor Facility .......................................... 5–8

5.2.11 Monitor Flow ............................................ 5–9

5.2.12 Monitor Group ........................................... 5–9

5.2.13 Monitor IPC . ............................................ 5–10

iv

5.2.14 Monitor IPCRATE ........................................ 5–10

5.2.15 Monitor Journal . . ........................................ 5–10

5.2.16 Monitor Link ............................................ 5–11

5.2.17 Monitor Netbytes . ........................................ 5–11

5.2.18 Monitor Netstat . . ........................................ 5–12

5.2.19 Monitor Partit . . . ........................................ 5–12

5.2.20 Monitor Queues . . ........................................ 5–13

5.2.21 Monitor Quorum . ........................................ 5–13

5.2.22 Monitor Recovery . ........................................ 5–13

5.2.23 Monitor Rejects . . ........................................ 5–14

5.2.24 Monitor Rejhist . . ........................................ 5–15

5.2.25 Monitor Response . ........................................ 5–15

5.2.26 Monitor Rolequorum ...................................... 5–16

5.2.27 Monitor Routers . . ........................................ 5–16

5.2.28 Monitor Routing . . ........................................ 5–16

5.2.29 Monitor RSCBE . . ........................................ 5–17

5.2.30 Monitor RTR ............................................ 5–17

5.2.31 Monitor Stalls . . . ........................................ 5–18

5.2.32 Monitor System . . ........................................ 5–19

5.2.33 Monitor TPS ............................................ 5–20

5.2.34 Monitor Traffic . . . ........................................ 5–20

5.2.35 Monitor Trans . . . ........................................ 5–20

5.2.36 Monitor V2CALLS ........................................ 5–21

5.2.37 Monitor XA ............................................. 5–21

6 RTR Command Line Interface

6.1 Introduction ................................................ 6–1

6.2 RTR Command Reference ..................................... 6–1

ADD FACILITY ............................................. 6–2

CALL RTR_ACCEPT_TX ...................................... 6–3

CALL RTR_BROADCAST_EVENT .............................. 6–6

CALL RTR_CLOSE_CHANNEL ................................ 6–10

CALL RTR_ERROR_TEXT .................................... 6–12

CALL RTR_GET_TID ........................................ 6–13

CALL RTR_OPEN_CHANNEL . ................................ 6–15

CALL RTR_PREPARE_TX ..................................... 6–22

CALL RTR_RECEIVE_MESSAGE ............................... 6–25

CALL RTR_REJECT_TX ...................................... 6–28

CALL RTR_REPLY_TO_CLIENT................................ 6–31

CALL RTR_REQUEST_INFO . . ................................ 6–35

CALL RTR_SEND_TO_SERVER ................................ 6–38

CALL RTR_START_TX ....................................... 6–42

CLEAR.................................................... 6–45

CREATE FACILITY . . ........................................ 6–47

CREATE JOURNAL . ........................................ 6–51

CREATE PARTITION ........................................ 6–54

DEFINE /KEY .............................................. 6–57

DELETE FACILITY . . ........................................ 6–61

DELETE JOURNAL . ........................................ 6–63

DELETE PARTITION ........................................ 6–65

v

DISPLAY BAR . . ............................................ 6–67

DISPLAY NUMERIC ......................................... 6–72

DISPLAY STRING........................................... 6–77

DISPLAY SYMBOLIC ........................................ 6–81

DISPLAY TEXT . ............................................ 6–83

DO....................................................... 6–86

FLUSH NAME_CACHE . . . .................................... 6–88

EXECUTE ................................................. 6–89

EXIT . .................................................... 6–90

EXTEND FACILITY ......................................... 6–91

INITIALIZE JOURNAL . . . .................................... 6–95

LOG...................................................... 6–96

MODIFY JOURNAL ......................................... 6–98

MONITOR ................................................. 6–100

QUIT . .................................................... 6–103

RECALL .................................................. 6–104

REGISTER RESOURCE MANAGER (REGISTER RM) ............... 6–105

SCROLL................................................... 6–107

SET ENVIRONMENT ........................................ 6–108

SET FACILITY . ............................................ 6–109

SET LINK ................................................. 6–112

SETLOG.................................................. 6–116

SET MODE ................................................ 6–118

SET NODE ................................................ 6–120

SET PARTITION ............................................ 6–122

SET TRANSACTION ......................................... 6–125

SHOW CHANNEL ........................................... 6–129

SHOW CLIENT . ............................................ 6–131

SHOW DISPLAY ............................................ 6–133

SHOW ENVIRONMENT . . .................................... 6–135

SHOW FACILITY ........................................... 6–136

SHOW JOURNAL ........................................... 6–140

SHOW KEY ................................................ 6–142

SHOW LINK . . . ............................................ 6–144

SHOW LOG ................................................ 6–146

SHOW MODE . . ............................................ 6–148

SHOW NODE . . ............................................ 6–150

SHOW PARTITION .......................................... 6–152

SHOW PROCESS ........................................... 6–156

SHOW REQUESTER ......................................... 6–158

SHOW RESOURCE MANAGER (SHOW RM) . . . ................... 6–159

SHOW RTR ................................................ 6–161

SHOW SEGMENT ........................................... 6–163

SHOW SERVER. ............................................ 6–165

SHOW TRANSACTION . . . .................................... 6–168

SPAWN ................................................... 6–171

STARTRTR................................................ 6–172

vi

STOP RTR . ................................................ 6–177

TRIM FACILITY ............................................ 6–179

UNREGISTER RESOURCE MANAGER (UNREGISTER RM) . . ....... 6–182

A Creating Monitor Pictures

A.1 Interactive Definition of a Monitor Picture . ....................... A–2

A.2 Substitution Symbols . ........................................ A–3

A.3 Arithmetic Expressions and Operators............................ A–3

B Server Shadowing and Recovery

B.1 Primary and Secondary Roles . . ................................ B–1

B.2 Automatic Features . . ........................................ B–1

B.2.1 Shadow Events . . ........................................ B–1

B.3 The RTR Journal System ...................................... B–2

B.4 Shadow Site Failure and Journaling ............................. B–3

B.4.1 Maximum Journal Size .................................... B–4

B.5 Standby for Shadows . ........................................ B–4

B.6 Performance ................................................ B–4

B.7 Shadows in Action . . . ........................................ B–5

B.8 Application Considerations .................................... B–5

B.9 Server States ............................................... B–6

B.10 Client States ............................................... B–8

B.11 Partition States ............................................. B–9

C XA Support

C.1 Introduction ................................................ C–1

C.1.1 MONITOR XA . . . ........................................ C–1

C.1.2 New Qualifier to CREATE FACILITY Command . . ............... C–1

C.1.3 Modified RTR API ........................................ C–2

C.1.4 RTR Open Channel ....................................... C–2

C.2 Microsoft DTC Support ....................................... C–2

D RTR Utility Error Messages

E RTR log messages

Index

Examples

2–1 Local Configuration of each Node ............................. 2–2

2–2 Remote Setup from one Node ................................ 2–3

2–3 Reconfiguration Using Delete and Create Facility . ............... 2–5

2–4 Reconfiguration Using Extend Facility . . ....................... 2–7

2–5 Configuration of Callout Servers ............................. 2–8

A–1 Interactive Picture Definition................................ A–2

A–2 Arithmetic Operators Examples .............................. A–4

vii

Figures

2–1 Configuration Example .................................... 2–2

2–2 Extend Configuration Example . . ............................ 2–6

A–1 Interactively Defined Monitor Picture ......................... A–3

B–1 Four Node Shadow/Standby Configuration. . . ................... B–4

B–2 Server States ............................................ B–7

B–3 Client States ............................................ B–8

B–4 Router Partition States .................................... B–9

Tables

1 Conventions Used in this Guide . ............................ xiii

4–19 Valid Transaction State Transitions ........................... 4–3

5–1 Standard Monitor Pictures .................................. 5–2

5–2 MONITOR GROUP Fields .................................. 5–9

5–3 Monitor Partition States ................................... 5–12

5–4 Monitor Recovery States ................................... 5–14

5–5 MONITOR REJECTS Fields ................................ 5–14

5–6 MONITOR REJHIST Fields................................. 5–15

6–1 Parameters for rtr_accept_tx ................................ 6–3

6–2 Parameters for rtr_broadcast_event ........................... 6–7

6–3 Generated Format Strings .................................. 6–8

6–4 Parameters for rtr_close_channel . ............................ 6–10

6–5 Parameters for rtr_error_text................................ 6–12

6–6 Parameters for rtr_get_tid .................................. 6–13

6–7 Parameters for rtr_open_channel . ............................ 6–16

6–8 Parameters for rtr_prepare_tx . . . ............................ 6–22

6–9 Parameters for rtr_receive_message........................... 6–25

6–10 Parameters for rtr_reject_tx ................................. 6–28

6–11 Parameters for rtr_reply_to_client ............................ 6–32

6–12 Generated Format Strings .................................. 6–33

6–13 Parameters for rtr_request_info . . ............................ 6–35

6–14 Parameters for rtr_send_to_server ............................ 6–39

6–15 Generated Format Strings .................................. 6–40

6–16 Parameters for rtr_start_tx ................................. 6–42

6–17 Platform Specific Information . . . ............................ 6–52

6–18 Key names . . ............................................ 6–57

6–19 Valid Transaction State Changes . ............................ 6–127

6–20 Key-Range States ......................................... 6–152

6–21 Router Partition States .................................... 6–153

6–22 Key-range States ......................................... 6–165

6–23 Server Flags . ............................................ 6–166

6–24 Transaction Invocation Types................................ 6–168

6–25 Key-Range States ......................................... 6–169

A–1 Information Classes . . . .................................... A–1

A–2 Substitution symbols . . .................................... A–3

viii

A–3 Arithmetic Operators in Display Commands .................... A–4

ix

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.

Preface

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

xi

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

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

[e-mail]

Conventions

Table 1 describes the conventions used in this guide.

.

xii

Table 1 Conventions Used in this Guide

Convention Meaning

UPPERCASE
lowercase

# A number sign (#) is the default operating system superuser

% A percent sign (% ) is the default operating system user prompt on

$ A dollar sign ($) is the default operating system user prompt on

Return

Ctrl/C This symbol indicates that you must press the Ctrl key while you

user input

filesystem

italic text Italic text emphasizes important information, indicates variables,

boldface text Boldface text represents the introduction of a new term or the

[y]

text A vertical bar next to the text | indicates changes or additions

HTML Red HTML text indicates changes or additions since the previous

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

prompt.

UNIX systems.

OpenVMS systems.
In examples, a boxed symbol indicates that you must press the

named key on the keyboard.

simultaneously press another key (in this case, C).
In interactive examples, this typeface indicates input entered by

the user.
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.

and indicates complete titles of manuals. Italic text also
represents information that can vary in system messages (for
example, Internal error
/PRODUCER=

name of a command, an argument, an attribute, or a reason.
In a prompt, square brackets indicate that the enclosed item is the

default response. For example,
Yes.

since the previous version of this document.

version of this document.

name

number

), and command parameters in text.

), command lines (for example,

[y]

means the default response is

xiii

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

RTR

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

START RTR

command in a startup command procedure for each node, so that RTR is

Introduction

command on each node. You may wish to include the

1

START

Before application processes are started, a facility must be defined using 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

CREATE FACILITY

command. You may wish to include the

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

Commands can either be entered on the same line as the RTR verb, for example:

% rtr command

CREATE FACILITY

RTR

at the operating system prompt.

START RTR

Introduction 1–1

and

Introduction

1.2 Entering Commands

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

Note

% 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

1–2 Introduction

Introduction

1.3 Online Help

where
The following sequence returns an error message,
explained by the

error-identification

help errors rtralrsta

% 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

% rtr execute createfacil

or:

EXECUTE file-specor@file-spec

is the identification part of the returned error.

RTRALRSTA

command option:

, that can then be

commands. For example:

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

Introduction 1–3

Introduction

1.5 Remote Commands

This command starts RTR on the three nodes.

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

For example:

% RTR
RTR> set environment/node=(nodeA, nodeC)
RTR> stop rtr

Note

command can be used to save typing.

This example shows the use of the
Node A and Node C. More details concerning the commands used in the above
examples are contained in Section 6.2.

set environment

command to stop rtr on

1–4 Introduction

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

is done by issuing the
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.

Starting and Setting Up RTR

must be defined on each node of the application’s environment. This

start rtr

and

create facility

commands on each

2

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.

Starting and Setting Up RTR 2–1

Starting and Setting Up RTR

2.2 Setting Up—An Example

Figure 2–1 Configuration Example

F r o n t e n d R o u t e r s ( T R )

F E 1

s ( F E )

B a c k e n d s ( B E )

B E 1

T R 1

F E 2

B E 2

T R 2

F E 3

SMM_CONFIG_EX 01−99

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

B E 3

% 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
on every node to simplify the maintenance of startup command procedures.

CREATE FACILITY

command

2–2 Starting and Setting Up RTR

Starting and Setting Up RTR

2.2 Setting Up—An Example

Example 2–2 illustrates how to use RTR remote commands to start the same
configuration. The
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.

set environment

command is used to send subsequent

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

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

SHOW FACILITY

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

The

CREATE JOURNAL

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

command must be issued on each node where an application

MODIFY JOURNAL

Cautionary Note for Journals

and

SHOW LINK

SHOW RTR

commands. The full syntax of

CREATE JOURNAL

command to adjust journal sizes.

command.

• The

• Do not make backup copies of journal files without first making the

CREATE JOURNAL/SUPERSEDE

existing journal files. If transaction recovery is required, DO NOT
ISSUE this command after a failure.

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

command deletes the contents of any

%RTR-F-SPUJOUFIL

error message.

Starting and Setting Up RTR 2–3

Starting and Setting Up RTR

2.3 Creating a Recovery Journal

• The operator should move any duplicate copies of journal files to a
location other than the
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

JOURNAL/SUPERCEDE

2.4 Changing a Facility

RTR facilities can be altered either by deleting and re-creating them using the

delete facility create facility
extend facility

With sufficient redundancy in a system, facility modification can be carried out
with minimal interruption to the application.

and

rtrjnl/groupname

command.

commands. Alternatively, you can use the

trim facility

directory so that RTR will

CREATE

commands.

Note

The RTR facility defines the nodes used by an application, and the roles
(frontend, router, backend) they may assume. You do not need to change
facility definitions in the event of node or link failures.

In the example in Figure 2–1, assume that the FE3 node is being removed from
the FUNDS_TRANSFER facility. Since FE3 is a frontend for this facility, only
the routers (TR1 and TR2) need be reconfigured. The routers can be reconfigured
one after another, so that the service provided to the remaining frontends (FE1
and FE2) is not interrupted.

Example 2–3 shows the
are issued from node BE1 (for example), in order to achieve this reconfiguration.

delete facility

and

create facility

commands that

2–4 Starting and Setting Up RTR

Starting and Setting Up RTR

2.4 Changing a Facility

Example 2–3 Reconfiguration Using Delete and Create Facility

% rtr
RTR> stop rtr/node=FE3
RTR> delete facility funds_transfer/node=TR2

RTR> create facility funds_transfer/node=TR2 -

1

2

3

_RTR> /frontend=(FE1,FE2) ­_RTR> /router=TR2 )

RTR> delete facility funds_transfer/node=TR1
RTR> create facility funds_transfer/node=TR1 -

4

5

_RTR> /frontend=(FE1,FE2) ­_RTR> /router=TR1 )

1

RTR is stopped on node FE3, the node being excluded from the network.
In order to prevent transactions being interrupted or aborted, application
processes should be stopped in an orderly manner before issuing the ’stop rtr’
command. Alternatively, a

stop rtr /abort

command will force application
processes using RTR to exit, aborting or interrupting any outstanding
transactions.

2

The facility is deleted on node TR2. Any frontends that were connected to
TR2 will connect to the remaining router, node TR1.

3

The facility is created on node TR2, excluding node FE3 from the frontend
list. This facility has started when the start message appears in the RTR log.

4

The facility is deleted from node TR1. Frontends FE1 and FE2 now connect
to router TR2.

5

The new facility is created on node TR1, again excluding node FE3 from the
frontend list. The frontends now distribute their connections to the router
nodes TR1 and TR2 according to the load sharing algorithm. The system is
again fully operational.

In the example in Figure 2–1, assume that a new router node TR3 and new
frontend FE4 are being added to the facility funds_transfer. The extended
configuration is shown in Figure 2–2. This diagram shows all possible
connections. The frontend connects to only one router at a time.

Starting and Setting Up RTR 2–5

Starting and Setting Up RTR

2.4 Changing a Facility

Figure 2–2 Extend Configuration Example

R O U T E R SF R O N T E N D S

F E 1

B A C K E N D S

B E 1

T R 1

F E 2

B E 2

T R 2

F E 3

B E 3

T R 3

F E 4

All backend nodes must be informed when router configurations are changed.
Because TR3 will be a router for the FE3 and FE4 frontends, these nodes must
also be informed of its presence. Likewise, TR3 must be informed about FE3 and
FE4.

Example 2–4 shows the

extend facility

command used for this reconfiguration.

SMM_CONFIG_EX_EXT 02−99

2–6 Starting and Setting Up RTR

Starting and Setting Up RTR

2.4 Changing a Facility

Example 2–4 Reconfiguration Using Extend Facility

% RTR
RTR> start rtr /node=(TR3,FE4)
RTR> set environment/node= ­_RTR> (FE1,FE2,FE3,TR1,TR2,BE1,BE2,BE3,TR3,FE4)

1

RTR> extend facility funds_transfer ­_RTR> /router=TR3/frontend=(FE3,FE4) ­_RTR> /backend=(BE1,BE2,BE3)

RTR> extend facility funds_transfer ­_RTR> /router=TR1/frontend=FE4

1

The

set environment

the facility, including the new nodes.

2

The

extend facility

Because the new router is also connected to the existing frontend FE3, this
node must also be specified as a frontend. The new router TR3 is told about
all backends with the /backend qualifier. Note that the
command has been used to create new definitions on TR3 and FE4, and
extend the definitions on BE1, BE2 and BE3.

3

The

extend facility

FE4 in order to give FE4 a second router link.

is used to send the following command to all nodes in

defines the new router TR3 and the new frontend FE4.

command is used to extend the definitions on TR1 and

2.5 Setting up Callout Servers

Callout

through the node where the callout server is running.
Like any other server, callout servers have the ability to abort any transaction

that they participate in. Callout servers are typically used to provide an
additional security service in the network; transactions can be inspected by the
callout server and aborted if they fail to meet any user-defined criteria. Callout
servers can run on router or backend nodes, or both.

servers are applications that receive a copy of every transaction passing

2

3

extend facility

Assume that callout servers are to run on the router nodes (TR1 and TR2) in the
example configuration shown in Figure 2–1. Example 2–5 shows the commands
needed to set up callout servers on the routers.

Starting and Setting Up RTR 2–7

Starting and Setting Up RTR

2.5 Setting up Callout Servers

Example 2–5 Configuration of Callout Servers

% rtr
RTR> set environment/node= ­_RTR> (FE1,FE2,FE3,TR1,TR2,BE1,BE2,BE3)

RTR> start rtr
RTR> create facility funds_transfer/frontend=(FE1,FE2,FE3) -

_RTR> /router=(TR1,TR2) ­_RTR> /backend=(BE1,BE2,BE3) ­_RTR> /call_out=router

2.6 Router Load Balancing

Router load balancing, or intelligent re-connection of frontends to a router
is possible, allowing a frontend to select the router that has least loading. The

create facility

control this. RTR now allows frontends to determine their router connection. The
RTR version 2 implementation of load balancing treated all routers as equal and
this could cause reconnection timeouts in geographically distant routers.

and

set facility

commands have the

/balance

qualifier to

When used with
enabled for frontend/router connections across the facility.

Use the
The default behavior (/nobalance) is for a frontend to connect to the preferred

router. Preferred routers are selected in the order specified in the

set facility/[no]balance

facility/router=tr1,tr2,tr3..

frontend will reconnect to the first router in the order when it becomes available.
Manual balancing can be attained by specifying different router orders across the
frontends.

Non load-balanced frontend connections will fail back to the preferred router
when it becomes available.

Automatic load balancing institutes a router list with a random value for the
frontend assigned at the time the
is issued. The frontend will sort the list of routers based on its own random order.
Randomness ensures that there will be a balance of load in a configuration with a
large number of frontends. Automatic failback will maintain the load distribution
on the routers and failback is controlled at a limited rate so as not to overload
configurations with a small number of routers.

The following points should be born in mind when using load-balancing:

• Frontends connect to a single router, per facility

• When several routers are configured on the frontend:

create facility,/balance

to switch load-balancing off and on.

qualifier. Automatic failback ensures that the

create facility

specifies that load balancing is

create

with the

/balance

command

The specified list in the
order, by default, unless

• Balancing may be individually enabled or disabled on the frontend nodes.

• Balancing is dynamic. The loss or addition of a router node causes the
frontend nodes to redistribute their connections.

2–8 Starting and Setting Up RTR

create facility

/balanced

is used

constitutes the preferred search

Starting and Setting Up RTR

2.6 Router Load Balancing

• Use

• Commands to set/show load balancing are:

/balance

only to enable RTR Version 2 balancing. Use this qualifier only when you are
connecting frontend nodes running RTR Version 2. See CREATE FACILITY
and SET FACILITY for more information on

create facility /balance

Enables load balancing attribute on the executor node
Significant only on router and frontend nodes
Disabled, by default

set facility /[no]balance

Toggles the attribute setting on the executor node

show facility /configuration

Shows the current setting of the load balance attribute

show facility /link

On a frontend, shows the current router node
On a router, shows the frontends connected, and the current load

coordinating backend node

show facility /balance

on frontend nodes only. Use of

/balance

/balance

.

on routers is supported

2.7 RTR Privileges

RTR supports two levels of rights or privileges,
platforms), RTR$OPERATOR and RTR$INFO (on OpenVMS) and RtrOperator
and RtrInfo on Windows NT. In general,
to issue any command that affect the running of the system, and
RTR$INFO is required for using monitor and display commands.

Setting RTR Privileges on UNIX Systems

On UNIX machines RTR privileges are determined by the user id and group
membership. For RTR users and operators, create the group
RTR operators and users as appropriate.

The root user has all privileges need to run RTR. Users in the group
have all privileges with respect to RTR, but may not have sufficient privilege to
access resources used by RTR, such as shared memory or access to RTR files.

The

rtrinfo

rtr_request_info( )

On a router node, shows the current number of frontends connected,
and the current credit

On the coordinating backend node, shows the total number of routers,
frontends and credit given out

Useful for troubleshooting frontend connection problems

rtroper

rtroper

group is currently only used to allow applications to call

.

or RTR$OPERATOR is required

and

rtrinfo

rtrinfo

rtroper

(on UNIX®

or

and add

rtroper

also

Depending on your UNIX system, see the
commands or the System Administration documentation for details on how to
add new groups to your system.

addgroup,groupaddormkgroup

Starting and Setting Up RTR 2–9

Starting and Setting Up RTR

2.7 RTR Privileges

The

rtrinfo

rtr_request_info( )

Users who do not fall into the above categories, but are members of the
group can only use RTR commands that display information (SHOW, MONITOR,
call rtr_request_info, etc.).

group is currently only used to allow applications to call

For other users, create the groups

rtroper

and

rtrinfo

rtrinfo

If the groups
belongs to them. This means that there is no system management required for
systems that do not need privilege checking.

Setting RTR Privileges on OpenVMS Systems

Create the Rights Identifiers RTR$OPERATOR and RTR$INFO if they do not
already exist on your system, and assign them to users as appropriate. The
RTR System Manager must have the RTR$OPERATOR identifier or the OPER
privilege.

Setting RTR Privileges on Windows NT Systems

Administrator privileges are needed for RtrOperator rights by the RTR System
Manager.

rtroper

and

rtrinfo

2.8 RTR ACP Virtual Memory Sizing

In addition to basic memory requirements of an unconfigured RTR ACP of
approximately 5.8 Mbytes, additional memory requirements may be required
according to the operating system environment that the RTR ACP process is
using.

Compaq strongly recommends that you allocate as much virtual memory as
possible. While there is no penalty for allocating more virtual memory than is
used, the result of allocating too little can be catastrophic.

are not defined, then all users automatically

2.8.1 OpenVMS Virtual Memory Sizing

On OpenVMS the following allowances for additional virtual memory should be
made:

• For each link add an additional 202 Kbytes

• For each facility an additional 13 Kbytes plus 80 bytes for each link in the
facility

• For each client or server application process an additional 190 Kbytes for the
first channel

• For each additional application channel an additional 1350 bytes

It is also necessary to prepare for the number of active transactions in the system.
Unless the client applications are programmed to initiate multiple concurrent
transactions this number will not exceed the total number of client channels in
the system. This should be verified with the application provider.

In addition it is necessary to determine the size of the transaction messages in
use:

1. For each front end:

• Add one Kbyte per active transaction

• Add 250 bytes per message per transaction

2–10 Starting and Setting Up RTR

Starting and Setting Up RTR

2.8 RTR ACP Virtual Memory Sizing

• Add the size of all messages

2. For each transaction router:

• Allow one Kbyte for each active transaction

3. For each back end:

• Allow one Kbyte per active transaction

• Allow fifty bytes for each message of a transaction

• Add the size of all replies

The total of all the contributions listed will yield an estimate of the likely virtual
memory requirements of the RTR ACP. A generous additional safety factor should
be applied as a final element to the total of virtual memory sizing. It is better to
grant the RTR ACP resource limits exceeding its real requirements than to risk
loss of service in a production environment as a result of insufficient resource
allocation. The total result should be divided by the virtual memory size in pages
to obtain the final virtual memory requirement. Process memory and page file
quotas should be set to accommodate as least this much memory.

Process quotas are controlled by qualifiers to the START RTR command. START
RTR accepts both links and application processes as qualifiers which can be
used to specify the expected number of links and application processes in the
configuration. The values supplied are used to calculate reasonable and safe
minimum values for the following RTR ACP process quotas:

• ASTLM

• BIOLM

• DIOLM

• FILLM

• PGFLQUOTA
Both /LINKS and /PROCESSES have high default values:

• The default value for /LINKS is now 512—This value is high but is chosen
to protect RTR routers against a failover where the number of front ends
is large and the number of surviving routers is small. The maximum value
for /LINKS is 1200 which is unchanged from earlier versions of RTR on
OpenVMS.

• The default value for /PROCESSES is 64— This value is large for front end
and router nodes but is sized for back ends hosting applications. Back ends
with complex applications may have to set this higher. The maximum value
for /PROCESSES is the OpenVMS allowed maximum. Warning messages
are generated if the requested (or default) memory quotas conflict with the
system-wide WSMAX parameter, or if the calculated or specified page file
quota is greater than the remaining free page file space.

• The default values for /LINK and /PROCESSES require a large page file.
RTR issues a warning if insufficient free space remains in the page file to
accommodate RTR, so choose values appropriate for your configuration.

Starting and Setting Up RTR 2–11

Starting and Setting Up RTR

2.8 RTR ACP Virtual Memory Sizing

Use of /LINK and /PROCESSES do not take into account memory requirements
for transactions. If an application passes a large amount of data from client to
server or vice-versa this should be included in the sizing calculations. For further
information on the START RTR qualifiers see the START RTR command in the
Command Reference section.

Once the requirements have been determined for the START RTR qualifiers of
/PGFLQUOTA or /LINK and /PROCESSES then RTR should be started with
these qualifiers set to ensure the appropriate virtual memory quotas are set.

The AUTHORIZE utility of OpenVMS does not play a role in the
determination of RTR ACP quotas. RTR uses AUTHORIZE quotas
for the command line interface and communication server, COMSERV.
Virtual memory sizing for the RTR ACP are determined through the
qualifiers of the START RTR command.

2.8.2 UNIX Virtual Memory Sizing

The RTR ACP process requires the operator to size the process limits for the ACP
before starting RTR on all platforms. No direct control of the process quotas of
the RTR ACP is offered for UNIX based platforms but log file entries will result if
hard limits are found to be less than the preferred values for the RTR ACP.

Note

The following are the minimum limits for the ACP on the following UNIX
platforms:

• On Compaq Tru64 UNIX:
A minimum of 1024 open file descriptors
A minimum of 1073742 Kbytes for virtual memory address space
A minimum of 268436 Kbytes for a single file size
A minimum of 419430 Kbytes for heap data segment sizing
A minimum of 33555 Kbytes for core file size
A minimum of 8389 Kbytes for stack segment size
A minimum of 0 for CPU time

• On Sun Solaris:
A minimum of 256 open file descriptors
A minimum of 1073742 Kbytes for virtual memory address space
A minimum of 268436 Kbytes for a single file size
A minimum of 419430 Kbytes for heap data segment sizing
A minimum of 33555 Kbytes for core file size
A minimum of 8389 Kbytes for stack segment size
A minimum of 0 for CPU time

• On IBM AIX:
A minimum of 268436 Kbytes for a single file size

2–12 Starting and Setting Up RTR