Compaq AA-Q88CE-TE User Manual

Download

ReliableTransactionRouter SystemManager’sManual

Order Number: AA-Q88CE-TE

June, 1999

This manual describes how to conﬁgure, 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.

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 Ofﬁce. 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 Deﬁnitions ........................... 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

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 Trafﬁc . . . ........................................ 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

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

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

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

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

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

A Creating Monitor Pictures

A.1 Interactive Deﬁnition 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 Qualiﬁer to CREATE FACILITY Command . . ............... C–1

C.1.3 Modiﬁed 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 Conﬁguration of each Node ............................. 2–2

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

2–3 Reconﬁguration Using Delete and Create Facility . ............... 2–5

2–4 Reconﬁguration Using Extend Facility . . ....................... 2–7

2–5 Conﬁguration of Callout Servers ............................. 2–8

A–1 Interactive Picture Deﬁnition................................ A–2

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

vii

Figures

2–1 Conﬁguration Example .................................... 2–2

2–2 Extend Conﬁguration Example . . ............................ 2–6

A–1 Interactively Deﬁned Monitor Picture ......................... A–3

B–1 Four Node Shadow/Standby Conﬁguration. . . ................... 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 Speciﬁc 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

Purpose of this Manual

This manual describes how to conﬁgure, 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 conﬁgure, 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 ﬁrst 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 conﬁgure 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.

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.

rtrdoc@compaq.com

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 deﬁnitions, 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 ﬁle. 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 deﬁning 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

START

Before application processes are started, a facility must be deﬁned 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, conﬁgured 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 qualiﬁers: these are indicated by the forward slash (/) character. For example, many RTR commands accept the ‘‘/OUTPUT’’ qualiﬁer; it directs the output from the command to a ﬁle.

The forward slash (/) character may also appear in the ﬁlenames of some operating systems; such ﬁlenames must be enclosed in quotation marks to ensure that RTR does not interpret the ﬁlename as a command qualiﬁer.

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 ﬁlenames. 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 ﬁrst 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 ﬁnd out about errors returned by RTR. The folowing sequence returns the error identiﬁer:

% 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 ﬁle and then executed as a procedure using the

% rtr execute createfacil

or:

EXECUTE file-specor@file-spec

is the identiﬁcation 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 qualiﬁers refer to cluster support. These qualiﬁers are for operating systems that fully support clustering. Use of the /CLUSTER qualiﬁer 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 conﬁgure 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 conﬁgure all the nodes from one session.

• You can include the necessary commands in a startup script or command ﬁle on each node so the commands are automatically executed when the nodes are booted.

The ﬁrst 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 deﬁned on each node of the application’s environment. This

start rtr

and

create facility

commands on each

The remaining sections contain examples of the commands that are used to start and conﬁgure 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 Conﬁguration 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 conﬁguration. Commands are issued ﬁrst on node FE1, then on FE2, and on FE3 for frontends followed by TR1 and TR2 for routers, and ﬁnally BE1, BE2, and BE3 for backends.

Example 2–1 Local Conﬁguration 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. Superﬂuous 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 conﬁguration. 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 conﬁguration. However, you must have an account with the necessary privileges on the other nodes.

set environment

command is used to send subsequent

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

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

SHOW FACILITY

2.3 Creating a Recovery Journal

RTR writes data to journal ﬁles 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 ﬁles without ﬁrst making the

CREATE JOURNAL/SUPERSEDE

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

original journal ﬁle read-only or the journal ﬁles will be considered spurious by RTR because it sees journal ﬁles 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 ﬁles to a location other than the see only the one it created.

• Track duplicate copies of journal ﬁles in the log ﬁle 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 sufﬁcient redundancy in a system, facility modiﬁcation 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 deﬁnes the nodes used by an application, and the roles (frontend, router, backend) they may assume. You do not need to change facility deﬁnitions 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 reconﬁgured. The routers can be reconﬁgured 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 reconﬁguration.

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 Reconﬁguration 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 -

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

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

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

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.

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

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.

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

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 conﬁguration 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 Conﬁguration 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 conﬁgurations 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 reconﬁguration.

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 Reconﬁguration 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)

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

The

set environment

the facility, including the new nodes.

The

extend facility

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

The

extend facility

FE4 in order to give FE4 a second router link.

is used to send the following command to all nodes in

deﬁnes the new router TR3 and the new frontend FE4.

command is used to extend the deﬁnitions 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-deﬁned criteria. Callout servers can run on router or backend nodes, or both.

servers are applications that receive a copy of every transaction passing

extend facility

Assume that callout servers are to run on the router nodes (TR1 and TR2) in the example conﬁguration 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 Conﬁguration 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

qualiﬁer 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 speciﬁed in the

set facility/[no]balance

facility/router=tr1,tr2,tr3..

frontend will reconnect to the ﬁrst 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 conﬁguration 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 conﬁgurations 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 conﬁgured on the frontend:

create facility,/balance

to switch load-balancing off and on.

qualiﬁer. Automatic failback ensures that the

create facility

speciﬁes that load balancing is

create

with the

/balance

command

The speciﬁed 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 qualiﬁer 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 Signiﬁcant only on router and frontend nodes Disabled, by default

set facility /[no]balance

Toggles the attribute setting on the executor node

show facility /conﬁguration

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

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 sufﬁcient privilege to access resources used by RTR, such as shared memory or access to RTR ﬁles.

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

group is currently only used to allow applications to call

or RTR$OPERATOR is required

and

rtrinfo

rtroper

(on UNIX®

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

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 Identiﬁers 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 identiﬁer 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 unconﬁgured 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 deﬁned, 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 ﬁrst 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 veriﬁed 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 ﬁfty 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 ﬁnal 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 insufﬁcient resource allocation. The total result should be divided by the virtual memory size in pages to obtain the ﬁnal virtual memory requirement. Process memory and page ﬁle quotas should be set to accommodate as least this much memory.

Process quotas are controlled by qualiﬁers to the START RTR command. START RTR accepts both links and application processes as qualiﬁers which can be used to specify the expected number of links and application processes in the conﬁguration. 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 conﬂict with the system-wide WSMAX parameter, or if the calculated or speciﬁed page ﬁle quota is greater than the remaining free page ﬁle space.

• The default values for /LINK and /PROCESSES require a large page ﬁle. RTR issues a warning if insufﬁcient free space remains in the page ﬁle to accommodate RTR, so choose values appropriate for your conﬁguration.

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 qualiﬁers see the START RTR command in the Command Reference section.

Once the requirements have been determined for the START RTR qualiﬁers of /PGFLQUOTA or /LINK and /PROCESSES then RTR should be started with these qualiﬁers 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 qualiﬁers 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 ﬁle 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 ﬁle descriptors A minimum of 1073742 Kbytes for virtual memory address space A minimum of 268436 Kbytes for a single ﬁle size A minimum of 419430 Kbytes for heap data segment sizing A minimum of 33555 Kbytes for core ﬁle 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 ﬁle descriptors A minimum of 1073742 Kbytes for virtual memory address space A minimum of 268436 Kbytes for a single ﬁle size A minimum of 419430 Kbytes for heap data segment sizing A minimum of 33555 Kbytes for core ﬁle 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 ﬁle size

2–12 Starting and Setting Up RTR

A minimum of 419430 Kbytes for heap data segment sizing A minimum of 33555 Kbytes for core ﬁle size A minimum of 8389 Kbytes for stack segment size A minimum of 0 for CPU time

• On HPUX: A minimum of 1024 open ﬁle descriptors

The START RTR qualiﬁers /LINK and /PROCESSES apply only to the OpenVMS platform and the determination of process quotas on UNIX platforms must be done through operating system handling of virtual memory sizing.

2.9 Network Transports

RTR supports multiple network transports with a default behaviour as follows: If an attempt to create a network connection to a remote node fails, RTR retries

the connection attempt using an alternate transport protocol if one is available. The order in which the supported transport protocols are used depends on the host operating system:

Starting and Setting Up RTR

2.8 RTR ACP Virtual Memory Sizing

OpenVMS - ﬁrst DECnet then TCP/IP. All other platforms - ﬁrst TCP/IP, then DECnet.

If a connection attempt fails on all available protocols, the connect fails and is retried at a later time starting again with the ﬁrst transport protocol.

If an established link fails, RTR automatically initiates a reconnection of the link, starting with the ﬁrst transport protocol for the platform, regardless of the transport employed when the link failed.

2.9.1 Specifying the Link Transport Protocol

It is possible to override the protocol failover mechanism by specifying the transport protocol to be employed for a link by naming links to include a transport selecting preﬁx. Preﬁxing links names with "tcp." and "dna." speciﬁes TCP/IP or DECnet as the required transports respectively. Use of these preﬁxes causes the local node to employ only the speciﬁed transport protocol when attempting a connection on the link to which the preﬁx has been applied. Note that use of a protocol preﬁx on one node does not prevent a remote node from connecting using some other transport.

For example, to specify the facility ‘‘FAX1’’ that only uses the DECnet transport, two routers (‘‘DNET1’’ and ‘‘DNET2’’), two backends (‘‘SRV1’’ and ‘‘SRV2’’) and many frontends, use the following command:-

RTR> create facility FAX1 /frontend=(dna.FE1,dna.FE2,dna.FE3 ....)

/router=(dna.DNET1,dna.DNET2) /backend=(dna.SRV1,dna.SRV2)

Creating a facility that uses only TCP/IP would use a command like this:-

RTR> create facility FINANCE /frontend=(tcp.client1,tcp.client2,tcp.client7 ....)

/router=(tcp.routr1,tcp.routr2) /backend=(tcp.srv1,tcp.srv2)

Starting and Setting Up RTR 2–13

Starting and Setting Up RTR

2.9 Network Transports

2.9.2 Using RTR with DHCP and Internet Tunnels

When using RTR with DHCP or an Internet tunnel, a nodename may not be fully known; special naming techniques are provided for these conditions.

Anonymous Clients

RTR allows the use of wild cards when specifying the frontends that a router is permitted to accept connections from (that is, in the facility deﬁnition on the router). Valid wild card characters are ‘‘*’’, ‘‘%’’ and ‘‘?’’. The result of using a wild card character at facility conﬁguration time is the creation of a template link.

When operating RTR in conjunction with the Compaq Internet Personal Tunnel, a client system outside of the corporate ﬁrewall uses tunnel software to obtain a secure channel from the Internet to inside the corporate domain. The tunnel client is assigned an address by the tunnel server from a pool when the tunnel software starts up.

When an RTR router receives a connection request from RTR running on this client, the source of the address is the address assigned by the tunnel server. There is no longer a ﬁxed relationship between the client and its address. The method of conﬁguring the router to accept such a connection is to deﬁne the frontends nodes with all the possible addresses that the tunnel server can assign to tunnel clients; you can do this with wildcards. For example,

RTR> create facility . . ./frontend=*.pool.places.dec.com

This command enables all nodes connecting through the tunnel to connect as frontends. The anonymous client feature may also be used with frontends that are using DHCP for TCP/IP address assignment.

Using the Tunnel Preﬁx

By using the node name preﬁx ‘‘tunnel.’’, it is possible to conﬁgure RTR to accept a network connection from a particular remote node even if it is connecting via a Internet tunnel using an unknown pseudoadapter address. This method allows stricter access control than the anonymous client feature where wild cards may be used when specifying a remote node name. For example, on the router node behind a ﬁrewall, the facility deﬁnition could include:

RTR> create facility . . ./router=router.rtr.dec.com -

/frontend=tunnel.client.rtr.dec.com

The deﬁnition on the frontend could be

RTR> create facility /router=router.rtr.dec.com -

/frontend=client.rtr.dec.com

Troubleshooting Tunnel and Wildcard Connections

To assist in diagnosing connect acceptance problems, use the monitor picture ACCFAIL. This picture displays the recent history of those links from which the local node has refused to accept connections. It displays the failed link name as provided by the network transport, and can assist in rapidly identifying any problems.

TCP Services File

• RTR uses the TCP/IP port number 46000 for the network communication daemon

On UNIX platforms, you should edit the ﬁle

rtracp 46000/tcp

2–14 Starting and Setting Up RTR

rtr rtrd

/etc/services

to add the line

Starting and Setting Up RTR

This informs the system administrator that port number 46000/tcp is reserved for RTR. (Note that the RTR daemon is started by RTRACP and not by

inetd

2.9.3 Interoperation with RTR Version 2 Using DECnet

Reliable Transaction Router is interoperable with RTR Version 2.2D ECO3 or later when running on a platform that supports DECnet; that is OpenVMS, Compaq Tru64 UNIX, SUN, Windows 95 or Windows NT.

Note that it is not possible to mix Version 2 and Version 3 routers and backends; all router and backend nodes in a facility must be either Version 2 or Version 3. Frontend nodes may be either Version 2 and Version 3.

Deﬁning the facility:

• On RTR Version 2 node(s):- There are no special requirements for including a V3.x frontend in a V2 facility deﬁnition. Simply add the name of the frontend to the node-list speciﬁed by the /FRONTEND qualiﬁer.

• On RTR Version 3 node(s):The default network transport for RTR Version 3.2 is TCP/IP.1Since RTR Version 2 uses DECnet (only), you must specify that your RTR Version 3 nodes use the DECnet protocol. This is achieved by preﬁxing the RTR V2 nodename with the string ‘‘dna.’’.

For example, to specify the facility ‘‘FAX1’’ on the RTR V3 frontend ‘‘v3fe’’ for which the two V2 routers ‘‘VMS1’’ and ‘‘VMS2’’ are deﬁned, use the following command:-

2.9 Network Transports

RTR> create facility FAX1 /frontend=v3fe /router=(dna.VMS1,dna.VMS2)

• Note that the facility name should contain only UPPER-CASE letters on all nodes if the facility includes nodes running RTR V2.

The use of the ‘‘dna.’’ preﬁx assumes that the default network transport is TCP/IP. The default network transport can be changed to DECnet by setting the environment variable RTR_PREF_PROT. On Windows 95 and Windows NT, you can use one of the following statements in your

set RTR_PREF_PROT=RTR_TCP_FIRST set RTR_PREF_PROT=RTR_TCP_ONLY set RTR_PREF_PROT=RTR_DNA_FIRST set RTR_PREF_PROT=RTR_DNA_ONLY

These set the choice of network transport to TCP/IP with fallback to DECnet, TCP/IP only, DECnet with fallback to TCP/IP or DECnet only.

For Reliable Transaction Router Version 3.2 for OpenVMS, refer to Section 2.10 for further information))

Trouble-shooting network connections:If the RTR V3 frontend fails to connect with the RTR V2 router node, then you

can make a basic check by executing a OpenVMS router node. If this fails, consult your Network Manager. (For Compaq Tru64 UNIX machines, ensure that the DECnet library is installed as

/libdna.so

dlogin

AUTOEXEC.BAT

from the RTR V3 node to the

/usr/shlib

For Reliable Transaction Router Version 3.2 for OpenVMS, the default network transport is DECnet.

Starting and Setting Up RTR 2–15

Starting and Setting Up RTR

2.10 Network Protocol Selection on OpenVMS

• The default network transport protocol on OpenVMS is DECnet. You may change the default to TCP/IP by removing this line from

$ DEFINE/SYSTEM RTR_PREF_PROT RTR_DNA_FIRST

RTR$STARTUP.COM

If you are using TCP/IP, you will need to use the node-name preﬁx ‘‘ if you speciﬁcally want DECnet transport to be used. This is required, for example, when connecting to Version 2.2D ECO6 nodes as described in Section 2.9.3 of these Notes, and Section 2.7 of the System Manager’s Manual.

If you are using DECnet as the default, you will need to use the node-name preﬁx ‘‘

If the value of the logical RTR_PREF_PROT is changed, the new value takes effect only after RTR has been restarted.

• Reliable Transaction Router Version 3.2 for OpenVMS can use either Compaq TCP/IP Services for OpenVMS or TCPware Version 5.1 as the TCP/IP transport layer.

tcp.

’’ to connect to other nodes using TCP/IP transport.

2.11 Running RTR as a Service on Windows NT

Once the RTR as Service has been installed (see Installation Guide), RTR may be started or stopped from the Control Panel / Services panel using the START and STOP buttons provided.

• To start RTR: Press the START button.

• To stop RTR: Press the STOP button.

Note

dna.

’’

Pressing START and STOP or the reverse in quick succession (within ﬁve or so seconds, depending on the speed of your computer) may cause undesirable results. This is because the Service executes quickly, making available the other action button, but the requested RTR action may not have completed when the second action button is pressed. It is therefore possible, for example, that the STOP action may be blocked by an incomplete START action. Although the Service will claim to be STOPped, RTR may in fact remain started. Pressing whichever action button is functioning should repair the problem.

By default, RTR will not restart automatically at system reboot time. You can change this by setting the Control Panel / Services entry for RTR.

Occasionally, an RTR process may continue to run after STOP has been pressed, and subsequent START and STOP actions may have no effect or produce an error. Under these circumstances, it will be necessary to intervene directly, as a privileged (SYSTEM) user, to stop RTR. This can be done either using RTR commands or with the Task Manager, or by rebooting.

2–16 Starting and Setting Up RTR

2.11 Running RTR as a Service on Windows NT

2.11.1 Customizing the RTR Windows NT Service

While starting RTR, the Service looks for the ﬁle directory. On ﬁnding the ﬁle, the Service executes any RTR commands it may contain. RTR commands from

From the point of view of the Service, the RTR home directory is found in the system-level environment variable the directory from which the Service was executed.

UsrStart.RTR

RTR_DIRECTORY

Starting and Setting Up RTR

UsrStart.RTR

execute after RTR has been started.

, or, if that is not deﬁned, then

in the RTR home

For the RTR Service to use it, environment variables list, not the user-level environment variables list. Also, the system must be rebooted after the deﬁnition of created or changed for it to be used.

If a user-level copy of directory as the system-level copy, or if there is no system-level copy, the directory containing the currently registered Service program. If it does not, behavior of RTR is undeﬁned. Changing the value of service from another directory while RTR is running, is dangerous and should be avoided. Starting RTR from the Service, then stopping it from DOS (or the reverse) should also be avoided.

If you put not detect that RTR has been stopped and will offer only the STOP action button. Pressing the STOP button will ﬁx the problem.

Similarly, when the Service stops RTR, it searches the RTR home directory for the ﬁle commands from

If you put QUIT or EXIT in either will exit improperly. As a result, an RTR command server process incorrectly remains active, preventing the Service from starting or stopping RTR, and preventing the RTR command server from exiting. Because the RTR command server executes under the SYSTEM account, it cannot be stopped from Task Manager other than by the SYSTEM account.

STOP RTR

UsrStop.RTR

RTR_DIRECTORY

in the

and, if the ﬁle exists, execute any RTR commands in it. User

UsrStop.RTR

RTR_DIRECTORY

must be deﬁned in the system-level

RTR_DIRECTORY

exists, it must identify the same RTR home

RTR_DIRECTORY

UsrStart.RTR

are executed before RTR has stopped.

ﬁle, it will stop RTR. The Service will

WARNING

, or reregistering the

UsrStart.RTRorUsrStop.RTR

is either

, RTR

2.11.2 Files Created by the RTR Windows NT Service

If RTR is started from the Service rather than via a Command Prompt window, several ﬁles are created in the RTR root directory. as a command line input source; output; RTR, it recreates Creation of these ﬁles is unconditional; that is, they are created every time RTR is started or stopped, whether or not they already exist. RTR will thus ignore (and overwrite) any changes made to one of these ﬁles.

RTRStart.RTR

contains the startup commands. When the Service stops

SrvcIn.Txt

SrvcOut.Txt

and creates

acts as a container for console

RTRStop.RTR

SrvcIn.Txt

for stopdown commands.

Starting and Setting Up RTR 2–17

is created to act

Starting and Setting Up RTR

2.12 How RTR Selects Processing-states (Roles) for Nodes

This section discusses how RTR assigns roles to backend node partitions, and how routers are selected.

2.12.1 Role Assignment for Backend Node Partitions

RTR assigns a primary or secondary processing state to a partition (or a keyrange deﬁnition), consisting of one or more server application channels, which may or may not share a common process. All such server channels belonging to a given partition will have the same processing state on a given node. However, the processing state for the same partition will normally be different on different nodes. The exception is the case of the standby processing state. Because a given partition can have multiple standby nodes, several of these nodes may be in this state.

RTR determines the processing state of a given partition through the use of a globally managed sequence number for that partition. By default, the RTR master router will automatically assign sequence numbers to partitions during startup. When a server is started up on a backend node and declares a new partition for that node, the partition initially has a sequence number of zero. When the partition on that backend makes an initial connection to the master router, the router increases its sequence number count for that partition by one and assigns the new sequence number to the new backend partition. The active node with the lowest backend partition sequence number gets the primary processing state in both shadow and standby conﬁgurations. That node is also referred to as the primary node, though the same node could have a standby processing state for a different partition.

Under certain failover conditions, backend partitions may either retain their original sequence number or be assigned a new sequence number by the router. If a failure is caused by a network disruption, for example, a backend partition will retain its sequence number when it reconnects with the router. However, if the backend node is rebooted or RTR is restarted on the backend node, a new sequence number will be assigned by the router to any partitions that start up on that node. Routers will only assign new sequence numbers to backend partitions that have a current sequence number of zero, or if the backend partition is joining an existing facility and has a sequence number that conﬂicts with another backend partition on another node.

Sequence number information can be obtained from the SHOW PARTITION command. In the output of this command the sequence number is indicated by the relative priority. The following example shows a sample of the SHOW PARTITION command from a router partition. This example shows that the backend partition called Bronze has a sequence number of 1, and backend partition called Gold has a sequence number of 2.

Router partitions on node SILVER in group test at Mon Mar 22 14:51:16 1999 State: ACTIVE

Low bound: 0 High bound: 4294967295 Failover policy: fail_to_standby Backends: bronze,gold

States: pri_act,sec_act Relative priorities: 1,2

Primary main: bronze Shadow main: gold

2–18 Starting and Setting Up RTR

Starting and Setting Up RTR

2.12 How RTR Selects Processing-states (Roles) for Nodes

The SHOW PARTITION command on each backend node is as follows:

Backend partitions on node BRONZE in group "test" at Mon Mar 22 14:52:32 1999

Partition name: p1 Facility: RTR$DEFAULT_FACILITY State: pri_act Low bound: 0 High bound: 4294967295 Active servers: 0 Free servers: 1 Transaction presentation: active Last Rcvy BE: gold Active transaction count: 0 Transactions recovered: 0 Failover policy: fail_to_standby Key range ID: 16777217 Master router: silver Relative priority: 1 Features: Shadow,NoStandby,Concurrent

Backend partitions on node GOLD in group "test" at Mon Mar 22 14:54:12 1999 Partition name: p1

Facility: RTR$DEFAULT_FACILITY State: sec_act Low bound: 0 High bound: 4294967295 Active servers: 0 Free servers: 1 Transaction presentation: active Last Rcvy BE: bronze Active transaction count: 0 Transactions recovered: 0 Failover policy: fail_to_standby Key range ID: 16777216 Master router: silver Relative priority: 2 Features: Shadow,NoStandby,Concurrent

The following description shows how sequence numbers are initially assigned in a simple partition with two backends named Bronze and Gold, and a router named Silver.

Backend A

Router

Backend B

1. A partition (with shadowing enabled) is started on node Bronze.

2. The partition on Bronze obtains sequence number 1 from the router and becomes the primary.

3. Another server on the same partition (with the same attributes) is started on Gold.

4. The partition on Gold obtains sequence number 2 from the router and becomes the secondary.

5. Node Bronze crashes and reboots (the partition sequence number on Bronze is reset to 0). The partition on Gold goes into Remember.

6. When the server starts, The partition on Bronze obtains sequence number 3 from the router and becomes the secondary, Gold now becomes the primary.

7. The network connection from node Silver to node Gold fails. The partition on Bronze becomes the primary. The partition on node Gold loses quorum and is in a wait-for-quorum state.

Starting and Setting Up RTR 2–19

Starting and Setting Up RTR

2.12 How RTR Selects Processing-states (Roles) for Nodes

8. The network connection to node Gold is reestablished. The partition on Gold retained its original sequence number of 2 and retains the primary role while the partition on Bronze reassumes the secondary role.

Alternately, the roles of backend nodes can be speciﬁcally assigned with the /PRIORITY_LIST qualiﬁer to the SET PARTITION command. In the previous example the /PRIORITY_LIST qualiﬁer can be used to insure that when Bronze fails and then returns to participate in the facility it then becomes the active primary member. To insure this, the following command would be issued on both backend systems immediately after the creation of the partition:

SET PARTITION test/PRIORITY_LIST=(bronze,gold)

It is recommended that the same priority list order be used on all partition members. If a different list is used then the router will determine the sequence number for conﬂicting members through the order in which those members joined the facility. For example, if the above command were issued only on Bronze and Gold had the opposite priority list, then the router would assign the lower sequence number to the backend that joined the facility ﬁrst.

The /PRIORITY_LIST feature is very useful in cluster conﬁgurations. For example, Site A and Site B each contain 2-node clusters. The facility is conﬁgured such that at Site A, Node-A1 has the primary active partition and Node-A2 has the standby partition. At Site B, Node-B1 is the secondary active partition and Node-B2 has the standby of the secondary. The partition could be deﬁned such that the standby node, Node-A2, would become active if the primary node were to fail. For example, issuing the following command on all four nodes for this partition guarantees that the speciﬁed list is followed when there is a failure.

SET PARTITION test/PRIORITY_LIST=(Node-A1,Node-A2,Node-B1,Node-B2)

Using the SHOW PARTITION command from the router, this partition would be as follows:

Router partitions on node SILVER in group "test" at Mon Mar 22 17:22:06 1999

State: ACTIVE Low bound: 0 High bound: 4294967295 Failover policy: fail_to_standby Backends: node-a1,node-a2,node-b1,node-b2

States: pri_act,standby,sec_act,standby Relative priorities: 1,2,3,4

Primary main: node-a1 Shadow main: node-b1

However, the partition could also be conﬁgured so that the secondary active node, Node-B1, would become the primary node if the original primary system were to fail. This is controlled with the /FAILOVER_POLICY qualiﬁer to the SET PARTITION command. The default is /FAILOVER_POLICY=STAND_BY.

2–20 Starting and Setting Up RTR

Starting and Setting Up RTR

2.12 How RTR Selects Processing-states (Roles) for Nodes

Site A

Node-A1 Node-A2

Router

Site B

Node-B1 Node-B2

If the relative priority (sequence number) for Node-A2 is changed to four it still becomes the primary active server if Node-A1 fails because the failover policy indicates a fail_to_standby requirement for this facility.

SET PARTITION test/PRIORITY_LIST=(Node-A1,Node-B1,Node-B2,Node-A2)

After issuing this command the router partition appears as follows. Note the change in relative priorities for the backends.

Router partitions on node SILVER in group test at Tue Mar 23 13:29:41 1999

State: ACTIVE Low bound: 0 High bound: 4294967295 Failover policy: fail_to_standby Backends: node-a1,node-a2,node-b1,node-b2

States: pri_act,standby,sec_act,standby Relative priorities: 1,4,2,3

Primary main: node-a1 Shadow main: node-b1

The following SET PARTITION command can be issued to change the facility so that Node-B1 will become the primary active server if Node-A1 fails.

SET PARTITION test/FAILOVER_POLICY=shadow

The /FAILOVER_POLICY qualiﬁer is intended for use in selecting a new active primary in conﬁgurations where shadowing is enabled. This qualiﬁer takes precedence over the /PRIORITY_LIST qualiﬁer. The /PRIORITY_LIST qualiﬁer is intended for use in determining the failover order for speciﬁc nodes. It is most useful in cluster conﬁgurations where it can be used to specify the exact failover order for the nodes within the cluster. For example, in a standby facility on a cluster of four nodes, the /PRIORITY_LIST qualiﬁer can be used to specify the desired order of failover for those cluster members. Some machines within a cluster may be more powerful than other machines. This feature allows for the most efﬁcient use of those machines.

2.12.2 Router Selection

Within the scope of a given facility, routers and backends connect to one another. However, nodes with a speciﬁc role do not connect to nodes with the same role, i.e., routers do not connect to other routers. Frontends choose only one router to connect to at a given time. This router is called the Current Router for that frontend within the scope of a facility.

A backend connects to all routers deﬁned within a facility. The connected router with the lowest network address is designated the master router. Internally, a node is identiﬁed through a structure called the Kernel Net ID. The Kernel Net ID is a concatenation of all network addresses a node is known as for all the protocols and interfaces that it supports. The master router designation is only

Starting and Setting Up RTR 2–21

Starting and Setting Up RTR

2.12 How RTR Selects Processing-states (Roles) for Nodes

relevant to a backend. It is where the backend goes to obtain and verify partition conﬁguration and facility information.

Routers are made known to the frontend systems through the list speciﬁed in the /ROUTER=(list) qualiﬁer to the CREATE FACILITY command. This list speciﬁcally determines the preferred router. If the ﬁrst router speciﬁed is not available, the next one on the list is chosen. When the facility is created on the frontend, the list of routers speciﬁed can be a subset of the routers contained within the entire facility. This can be used to prevent a frontend from selecting a router that is reserved for other frontend systems. Fail back of routers is supported. This means that if the preferred router was not available, and it became available later, the frontend would automatically fail back and connect to its preferred router.

Router connectivity can also be controlled through the use of the /BALANCE qualiﬁer either on the CREATE FACILITY command or on the SET FACILITY command. When the /BALANCE qualiﬁer is used, the list of routers speciﬁed in the router list is randomized, making the preferred router a random selection within the list. Assume the following command is issued from a frontend:

RTR CREATE FACILITY test/FRONTEND=Z/ROUTER=(A,B,C)

The frontend attempts to select a router based on the priority list A, B, C, with A being the preferred router. If the /BALANCE qualiﬁer is added to the end of this command then the preferred router is randomly selected from the three nodes. This random list exists for the duration of the facility. After the facility is stopped, a new random list is made when the facility is created again. The exception to this is if a router does not have quorum (sufﬁcient access to backend systems) then that router will no longer accept connections from frontend systems until it has again achieved quorum. The /BALANCE qualiﬁer is only valid for frontend systems.

2–22 Starting and Setting Up RTR

3.1 Overview

This section describes the concepts and operations of RTR’s partitions.

3.1.1 What is a Partition?

Partitions are subdivisions of a routing key range of values. They are used with a partitioned data model and RTR data content routing. Partitions exist for each distinct range of values in the routing key for which a server is available to process transactions. RTR provides for failure tolerance by allowing system operators to start redundant instances of partitions in a distributed network and by automatically managing the state and ﬂow of transactions to the partition instances.

Partition instances support the following relationships:

• Concurrency - this attribute permits multiple server channels to be connected to an instance of a partition.

Partition Management

• Standbys - multiple instances of a partition distributed over the nodes of a cluster. A standby set may have as many members as a cluster has nodes, or with some restrictions you may place a standby on any network node. At any one time, one member of the set is active while the others wait in standby mode to take over in the event of failure of the active member.

• Shadows - shadow instances provide site disaster protection by allowing replication of transaction processing at a remote site. A pair of partition instances or (standby sets thereof) cooperate to provide this replication, with provision for automatic recovery of a shadow member restarting after a failure.

Prior to RTR V3.2, the creation and behavior of a partition was tied to the declaration of server application channels. Partitions and their characteristics can now be deﬁned by the system operator. This has the following advantages:

• It allows a further de-coupling of the application from its operating environment, thus reducing application programming requirements.

• Allows the system operators to make choices concerning the runtime behavior of the system.

3.1.2 What is Partition Management?

Before RTR V3.2, the management of the state of a partition was an entirely automatic function of the distributed RTR system. Starting with RTR V3.2, the system operator can issue commands to control certain partition characteristics, and to set preferences concerning partition behavior.

Partition Management 3–1

Partition Management

3.2 Partition Naming

A prerequisite for partition management is the ability to identify a partition in the system that is to be the subject of management commands. For this purpose, partitions have been given names, which may be drawn from a number of sources described below.

3.2.1 Default Partition Names

Unless supplied by one of the methods described below, partitions receive automatically generated default names. They allow system operators access to the partition command set without the need to change existing application programs or site conﬁguration procedures.

3.2.2 Programmer Supplied Names

An extension to the to supply a name when opening a server channel. The speciﬁes an additional item of type

•

ks_type = rtr_keyseg_partition

passed.

• code_example>(ks_lo_bound) should point to the null-terminated string to use for the partition name.

rtr_open_channel( )

call allows the application programmer

pkeyseg

rtr_keyseg_t

, indicating that a partition name is being

, assigning the following values:

argument

• code_example>(ks_hi_bound) must be NULL.

Using this model, the partition segments and key ranges served by the server are still speciﬁed by the server when the channel is opened.

3.2.3 System Manager Supplied Partition Names

Partitions can be deﬁned by the system manager through the use of the code_ example>(create partition) system management command, or through use of

rtr_open_channel( )

characteristics with this command and applications can open channels to the partition by name. See the Section 3.4 for an example of passing a partition name with

rtr_open_channel( )

ﬂag arguments. The system manager can set partition

3.2.4 Name Format and Scope

A valid partition name must contain no more than 63 characters in length and can combine alphanumeric characters (abc123), the plus sign (+), the underscore (_), and the dollar sign ($). Partition names must be unique within a facility name and should be referenced on the command line with the facility name when using partition commands. Partition names exist only on the backend where the partition resides. You won’t see the partition names at the RTR routers.

3.3 Life Cycle of a Partition

3–2 Partition Management

3.3.1 Implicit Partition Creation

Partitions are created implicitly when an application program calls

rtr_open_channel( )

and value ranges for the segments with the attributes are established with the the only way in which partitions could be created. Partitions created in this way are automatically deleted when the last server channel to the partition is closed.

to create a server channel, specifying the key segments

3.3.2 Explicit Partition Creation

Partitions can also be created by the system operator before server application program start up using system management commands. This gives the operator more control over partition characteristics. Partitions created in this way remain in the system until either explicitly deleted by the operator, or RTR is stopped.

3.3.3 Persistence of Partition Deﬁnitions

RTR stores partition deﬁnitions in the journal, and records for each transaction the partition in which it was processed. This is convenient when viewing or editing the contents of the journal, where the partition name can be used to select a subset of the transactions in the journal. RTR will not permit a change in the partition name or deﬁnition as long as transactions remain in the journal that were processed under the current name or deﬁnition for the partition. If transactions remain in the journal and you need to change the partition name or deﬁnition, you can take the following actions:

Partition Management

3.3 Life Cycle of a Partition

pkeyseg

flags

argument. Before RTR V3.2, this was

argument. Other partition

• Start appropriate servers to complete processing of the transactions.

• Remove the transactions from the journal with the command.

• Replace the RTR journal with the that this will destroy any transactions remaining in the journal and should be done with caution.

CREATE JOURNAL/SUPERSEDE

3.4 Binding Server Channels to Named Partitions

For a server application to be able to open a channel to an explicitly created partition, the application passes the name of the partition through the argument of descriptors, but if the application does so, they must be compatible with the existing partition deﬁnition. You may pass partition characteristics through the

flags

Example:

argument, but these will be superseded by those of the existing partition.

RTR> create partition/KEY1=(type. . .) par_one

...

rtr_keyseg_t partition_name; partition_name.ks_type = rtr_keyseg_partition;

partition_name.ks_lo_bound = "par_one"; status - rtr_open_channel( . . ., RTR_F_OPE_SERVER, . . ., 1, &partition_name);

rtr_open_channel( )

call. It is not necessary to pass key segment

SET TRANSACTION

command. Note

pkeyseg

Summarizing, to fully de-couple server applications from the deﬁnition of the partitions to be processed, write applications that open server channels where only the required partition name is passed. Leave the management of the partition characteristics to the system managers and operators.

Partition Management 3–3

Partition Management

3.5 Entering Partition Commands

Partitions can be managed by issuing partition commands directed at the required partition after they are created. Partition commands can be entered in one of two ways:

• A command line processed by the RTR command line interface, for example

RTR> SET PARTITION

• Programmed using Enter partition commands on the backend where the partition is located. Note

that commands that affect a partition state only take effect once the ﬁrst server joins a partition. Errors encountered at that time will appear as log ﬁle entries. Using partition commands to change the state of the system causes a log ﬁle entry.

rtr_set_info( )

3.5.1 Command Line Usage

Partition management in the RTR command language is implemented with the following command set:

•

RTR> CREATE PARTITION

•

RTR> SET PARTITION

•

RTR> DELETE PARTITION

The name of the facility in which the partition resides may be speciﬁed with the /FACILITY command line qualiﬁer, or as a colon-separated preﬁx to the partition name (for example Facility1:Partition1). Detailed descriptions of the command syntax are given in the Command Line Reference section of this manual, and are summarized in the discussions below. Examples in the following sections use a partition name of Partition1 in the facility name of Facility1.

3.5.2 Programmed Partition Management

Partition commands are programmed using arguments are as follows:

rtr_set_info( )

. Usage of the

•

pchannel

opened in the event of a successful call.

• Flags must be

• Verb must be the value

• Object must be

•

select_qualifiers

example:

• The or characteristic.

3–4 Partition Management

- Supplies the address of a

rtr_channel_t

to receive the channel

RTR_NO_FLAGS

verb_set

(from the enumeration rtr_verb_t)

rtr_partition_object

should identify the facility and partition, by name, for

rtr_qualifier_value_t select_qualifiers[ 3 ]; select_qualifiers[ 0 ].qv_qualifier = rtr_facility_name; select_qualifiers[ 0 ].qv_value = "your_facility_name_here"; select_qualifiers[ 1 ].qv_qualifier = rtr_partition_name; select_qualifiers[ 1 ].qv_value = "your_partition_name_here"; select_qualifiers[ 2 ].qv_qualifier = rtr_qualifiers_end; select_qualifiers[ 2 ].qv_value = NULL;

set_qualifier

list expresses the required change in partition behaviour

The

rtr_set_info( )

successful, completion will be signaled by the delivery of an RTR message of type the using

rtr_mt_closed

pchannel

argument. The programmer should retrieve this message by

rtr_receive_message( )

rtr_status_data_t

accessed as the status ﬁeld of the message data.

3.6 Managing Partitions

To manage partitions a set of commands or program calls are used. Information on managing partitions is provided in this section.

3.6.1 Controlling Shadowing

The state of shadowing for a partition can be enabled or disabled. This may be useful in the following circumstances:

• Enabling site disaster protection for an application partition for the ﬁrst time

• A recovery aid following prolonged outage of a former shadow site.

Partition Management

3.5 Entering Partition Commands

call completes asynchronously. If the function call is

on the channel whose identiﬁer is returned through

. The data accompanying the message is of type

. The completion status of the partition command can be

The following restrictions apply. Shadowing for a partition can be turned off only in the absence of an active secondary site, The active member must be running in remember mode. The command will fail if entered on either an active primary or secondary with a message to this effect. If entered on a standby of either the primary or secondary, the command is accepted but fails in the RTR router. This failure is recorded with a log ﬁle entry at the router. Once shadowing is disabled, the secondary site servers will be unable to startup in shadow mode until shadowing is enabled again. Shadowing for the partition can be turned on by entering the command at the current active member or on any of its standbys.

3.6.1.1 Command Line Example

RTR> SET PARTITION/FACILITY=Facility1/SHADOW Facility1:Partition1

For further information see the SET PARTITION command in Chapter 6.

3.6.1.2 Programming Information

To enable shadowing, program the as follows:

rtr_qualifier_value_t set_qualifiers[ 2 ]; rtr_partition_state_t newState = rtr_partition_state_shadow;

set_qualifiers[ 0 ].qv_qualifier = rtr_partition_state; set_qualifiers[ 0 ].qv_value = &newState; set_qualifiers[ 1 ].qv_qualifier = rtr_qualifiers_end; set_qualifiers[ 1 ].qv_value = NULL;

set_qualifier

argument of

rtr_set_info( )

To disable shadowing, specify

newStateasrtr_partition_state_noshadow

Partition Management 3–5

Partition Management

3.6 Managing Partitions

3.6.2 Controlling Transaction Presentation

Transaction presentation is the process of passing transactions to idle server channels for processing. While transaction presentation is active, new transactions are started on the ﬁrst free server channel for the appropriate partition.

Use the presentation of new transactions to servers on the backend where the command is entered. The command completes when the processing of all currently active transactions is complete. The optional of seconds, the time that the command waits for completion. If the command times out, presentation of new transactions are suspended, but there still exist transactions for which servers have yet to complete processing. The operator must decide either to reenter the command and wait a further period of time, or resume the partition. Note that use of this command does not affect any transaction timeout value speciﬁed by RTR clients, so such transactions may encounter a timeout condition if the partition remains suspended.

/RESUME

channels.

3.6.2.1 Command Line Example

Example usage of the qualiﬁers:

RTR> SET PARTITION/FACILITY=Facility1/SUSPEND/TIMEOUT=5 Facility1:Partition1 RTR> RTR> SET PARTITION/FACILITY=Facility1/RESUME Facility1:Partition1

For a more complete description see the SET PARTITION command in Chapter

3.6.2.2 Programming Information

To suspend transaction presentation on a partition with a timeout of 30 seconds, program the

/SUSPEND

qualiﬁer restarts presentation of transactions to the server application

set_qualifier

qualiﬁer to the

argument of the

SET PARTITION

/TIMEOUT

qualiﬁer speciﬁes, as a number

rtr_set_info( )

command to halt the

call as follows:

rtr_qualifier_value_t set_qualifiers[ 3 ]; rtr_partition_state_t newState = rtr_partition_state_suspend; rtr_uns_32_t ulTimeoutSecs = 30;

set_qualifiers[ 0 ].qv_qualifier = rtr_partition_state; set_qualifiers[ 0 ].qv_value = &newState; set_qualifiers[ 1 ].qv_qualifier = rtr_partition_cmd_timeout_secs; set_qualifiers[ 1 ].qv_value = &ulTimeoutSecs; set_qualifiers[ 2 ].qv_qualifier = rtr_qualifiers_end; set_qualifiers[ 2 ].qv_value = NULL;

Note that the timeout is an optional element. To resume transaction presentation, specify

newStateasrtr_partition_state_resume

3.6.3 Controlling Recovery

The purpose of RTR automated recovery is to ensure the best possible consistency of application databases across a distributed computing environment. To achieve this RTR relies in part on information stored in the journals of the participating systems. Should one or more of these systems be unavailable at recovery time, automated recovery may stall or fail awaiting availability of these systems and their journals. This is good from the point of view of data consistency, but bad when viewed from an application availability perspective.

3–6 Partition Management

Partition Management

3.6 Managing Partitions

If a partition enters a wait state or fails but has neither a local or remote journal, an operator can instruct RTR to skip the current step in the recovery process with the recovery cycle use it with caution in cases where availability above consistency in application databases is desired.

/IGNORE_RECOVERY

qualiﬁer. Since this command bypasses parts of the

The recovery cycle can also be manually restarted with the qualiﬁer. This may be useful if the operator previously aborted automated recovery. Since this command can result in recovery of transactions from previously inaccessible journals, do not use this if your applications are sensitive to the order in which transactions are processed by the servers.

3.6.3.1 Command Line Example

Example of the qualiﬁers:

RTR> SET PARTITION/FACILITY=Facility1/IGNORE_RECOVERY Facility1:Partition1 RTR> RTR> SET PARTITION/FACILITY=Facility1/RESTART_RECOVERY Facility1:Partition1

A complete description of the qualiﬁers to the SET PARTITION command can be found in Chapter 6.

3.6.3.2 Programming Information

To terminate the current recovery state, program the

rtr_set_info( )

rtr_qualifier_value_t set_qualifiers[ 2 ]; rtr_partition_state_t newState = rtr_partition_state_exitwait;

set_qualifiers[ 0 ].qv_qualifier = rtr_partition_state; set_qualifiers[ 0 ].qv_value = &newState; set_qualifiers[ 1 ].qv_qualifier = rtr_qualifiers_end; set_qualifiers[ 1 ].qv_value = NULL;

To restart recovery, specify newState as rtr_partition_state_recover.

as follows:

/RESTART_RECOVERY

set_qualifier

argument of

3.6.4 Controlling the Active Site

RTR lets the system operator to deploy a range of shadow and standby partitions in order to provide the desired degree of application resilience to failures. By default, RTR automatically manages the assignment of active and standby roles to the available partition instances. The operator can assign a relative priority to each backend on which a partition instance exists. Enter priority as a list of backend node names with the highest priority ﬁrst in decreasing order. See the command example Section 3.6.4.1.

Suspend transaction presentation before entering or changing the priority list.

3.6.4.1 Command Line Example

RTR> SET PARTITION/PRIORITY_LIST=(BE1, BE2, BE3) Facility1:Partition1

For more information on the SET PARTITION command see Chapter 6.

Partition Management 3–7

Partition Management

3.6 Managing Partitions

3.6.4.2 Programming Information

To set the partition backend priority list, program the of the

rtr_set_info( )

rtr_qualifier_value_t set_qualifiers[ 2 ]; char *szNodeList = "your,list,of,node,names,here"

set_qualifiers[ 0 ].qv_qualifier = rtr_partition_be_priority_list; set_qualifiers[ 0 ].qv_value = &szNodeList; set_qualifiers[ 1 ].qv_qualifier = rtr_qualifiers_end; set_qualifiers[ 1 ].qv_value = NULL;

3.6.5 Controlling Failover

In a system conﬁgured for maximum fault tolerance employing both shadows and standbys, there is a choice to be made in case of the failure of the primary site. The qualiﬁer to the system operator to select one of the following policies that RTR should pursue in selecting the new primary site in the event of a failure:

•

/FAILOVER_POLICY=STANDBY

primary (if any) to become the new primary. If there is more than one standby, the operator may addition use the priority list feature (described above) to control which standby is preferred. Depending on the size of the journal of the failed primary, there will be a hold up in the processing of transactions whilst the journal is recovered. This is the default behaviour.

call as follows:

SET PARTITION

causes RTR to choose a standby of the failed

command of

set_qualifier

/FAILOVER_POLICY=

argument

allows the

•

/FAILOVER_POLICY=SHADOW

any) the new primary. A standby of the failed primary (if any) will be elected to become the new secondary. This option gives the shortest fail over time, but will move the primary to a different cluster that you may have located at a different site.

•

/FAILOVER_POLICY=COMPATIBLE_PRE_V32

conﬁgurations that contain RTR routers running versions of the software prior to V3.2. This mode will be automatically adopted if such routers exists in or join the conﬁguration.

3.6.5.1 Command Line Example

An example use of the

RTR> SET PARTITION/FAILOVER_POLICY=SHADOW Facility1:Partition1

For more information see the SET PARTITION command in Chapter 6.

3.6.5.2 Programming Information

To set the partition failover policy, program the

rtr_set_info( )

rtr_qualifier_value_t set_qualifiers[ 2 ]; rtr_partition_failover_policy_t newPolicy;

set_qualifiers[ 0 ].qv_qualifier = rtr_partition_failover_policy; set_qualifiers[ 0 ].qv_value = &newPolicy; set_qualifiers[ 1 ].qv_qualifier = rtr_qualifiers_end; set_qualifiers[ 1 ].qv_value = NULL;

call as follows:

instructs RTR to make the active secondary (if

/FAILOVER_POLICY

qualiﬁer:

is a mode that will operate with

set_qualifier

argument of the

Legal values for

•

rtr_partition_fail_to_standby

3–8 Partition Management

newPolicy

are:

•

rtr_partition_fail_to_shadow

•

rtr_partition_pre32_compatible

3.6.6 Controlling Transaction Replay

RTR has implemented the capability of controlling transaction replay in cases where a "killer message" happens during a transaction replay preventing recovery from continuing normally. A "killer message" presents a situation where server availability is lost because of the presence of a message capable of causing repeated server application failure during recovery. This is typically the result of an improperly handled condition or application programming error within the server itself. Under such circumstances it may be desirable to sidestep a particular transaction, maintain server operation, and manually process the transaction at some later time.

The RTR solution is to establish, for a given partition, the maximum number of retries for any given transaction presented during recovery. Once this limit has been exceeded, the offending transaction is removed from the recovery process and is written to the journal as an exception record. Subsequent processing of this transaction requires manual intervention by someone qualiﬁed to evaluate and correct the situation in both the application and in RTR. Once the application status is understood, the journal, thus insuring that the ﬁnal state of any manually transacted exceptions are accurately reﬂected in future recovery operations.

set transaction

Partition Management

3.6 Managing Partitions

command can be used to update the

The recovery retry count indicates the maximum number of times that a transaction should be presented for recovery before being written to the journal as an exception. Once a transaction has been recorded as an exception, it is no longer considered eligible for recovery and requires manual processing by a qualiﬁed individual.

The recovery retry count is partition-speciﬁc, and applies to both local and shadow recovery operations. The default is no limit on the number of retries, which permits a killer message to bring down all available servers servicing a given partition.

The recovery retry count should be set before starting (or restarting) the application servers so that the limit is established prior to the start of recovery operations.

3.6.6.1 Command Line Example

RTR> SET PARTITION/RECOVERY_RETRY_COUNT=3 Facility1:Partition1

For more information on the SET PARTITION command see Chapter 6.

3.6.6.2 Programming Information

To set the partition transaction recovery limit, program the argument of

rtr_qualifier_value_t set_qualifiers[ 2 ]; rtr_uns_32_t newLimit = . . .;

set_qualifiers[ 0 ].qv_qualifier = rtr_partition_rcvy_retry_count; set_qualifiers[ 0 ].qv_value = &newLimit; set_qualifiers[ 1 ].qv_qualifier = rtr_qualifiers_end; set_qualifiers[ 1 ].qv_value = NULL;

rtr_set_info( )

set_qualifier

as follows:

Partition Management 3–9

Partition Management

3.7 Displaying Partition Information

Information on the deﬁnition and state of a partition is displayed with the

SHOW PARTITION

partition management relates to the backend instance of the partition. For more information see the SHOW PARTITION command in Chapter 6.

3.7.0.1 Command Line Example

RTR> show partition/backend Backend partitions on node BE1 in group "Facility1" at Wed Feb 24 15:07:50 1999 Partition name Facility State

RTR$DEFAULT_PARTITION_16777217 RTR$DEFAULT_FACILITY active RTR$DEFAULT_PARTITION_16777218 RTR$DEFAULT_FACILITY active

command. The information of interest in the context of

3–10 Partition Management

4.1 Overview

This section describes the concepts of RTR’s transaction management capability. The RTR transaction is the heart of an RTR application, and transaction state

is the property that characterizes a transaction’s current condition. Whenever a transaction progresses from one stage to another, the transaction state is updated to reﬂect a transaction transition. Transaction states are maintained in memory and some types of transaction states are also stored in the RTR Journal for recovery purposes.

Three different types of states are used internally by RTR to keep track of transaction status.

• Transaction Runtime State

• Transaction Journal State

• Transaction Server State These three state types are very closely related. The Transaction Runtime State,

also known as Transaction State, describes how a transaction progresses from a RTR role (FE, TR, BE) point of view. For example, a transaction can enter a stage in which its transaction state from an RTR frontend viewpoint is different than the transaction state of an RTR router.

Transaction Management

The Transaction Journal State describes how a transaction running on an RTR backend progresses from the RTR journal perspective. When a transaction transitions, its Transaction Journal State gets updated and the new state along with other information pertaining to this transaction is stored in the RTR journal. The Transaction Journal State is primarily used by RTR to perform the recovery replay of a transaction after a failure, if necessary. An RTR frontend and router will not see this state.

The Transaction Server State describes transaction state transition seen by the server. RTR uses this state to determine if a server is available to process a new transaction or if a server has voted on a particular transaction. As with the Transaction Journal State, the Transaction Server State is only managed at the backend.

RTR provides a set of comprehensive management utilities to help users closely monitor the ﬂow of a transaction and all three types of states associated with that transaction. These utilities help users understand how a transaction migrates from one stage to another and help diagnose problems.

The RTR up-to-date status on frontend, router or backend roles. With this command, users can see all three types of transaction states of a particular transaction and also understand how the RTR journal and application servers perceive this transaction. When a transaction commits or aborts, all status associated with

SHOW TRANSACTION

command can be used to examine a transaction’s

Transaction Management 4–1

Transaction Management

4.1 Overview

this transaction is removed from memory and can no longer be monitored by the command.

The RTR transaction. The RTR journal saves all of the information about a transaction, its transaction journal state, the transaction messages (records) received from the RTR client, and the content of a message sent to the server. The information will be kept until a transaction is committed and forgotten.

The RTR change the current state of a transaction to a new state. This command can be used to circumvent a difﬁcult situation. For example, in a situation where two shadowed servers are conﬁgured, the system administrator might decide not to replay (recover) all transactions in a shadowed RTR journal after a failure. The or remember state to a DONE state and avoid the delay of transactions being remembered from a journal for fast recovery. The should only be used by experienced RTR system administrators as the command introduces the risk of corrupting or losing transactions if used incorrectly. It can be used on the backend only and the RTR log ﬁle must be turned on for this command.

Log ﬁle entries are made for all transaction state changes for debugging and auditing purposes.

4.1.0.1 Command Line Examples

An example of the use of the

DUMP JOURNAL

SET TRANSACTION

command can be used to trace and review the ﬂow of a

command is used to modify a live transaction to

command could set speciﬁed transactions in a PRI_DONE

SET TRANSACTION

command:

SET TRANSACTION

command

RTR> start rtr RTR> set log/file=settran RTR> set transaction/state=PRI_DONE/new_state=DONE/facility=Facility1/partition=Partition1 *

This example would set all transactions with the wildcard * in the current state of PRI_DONE (remember) to DONE on the facility Facility1 and the partition Partition1. The log ﬁle, settran, would record the transaction state changes. The changes could be viewed with the

JOURNAL

remember transactions and provide for a fast recovery of access to the database if needed.

For detailed information on these commands see Chapter 6.

command. In a shadow recovery situation this would clear the journal of

4.1.1 Exception Transactions

Transactions can cause servers to fail after the VOTE phase and impact availability of a server in a recovery. These "EXCEPTION" transactions can now be ﬂagged by RTR as "fail transactions" after the user sets the attempts at recovery from a failure with the command. They then can be identiﬁed and removed from the RTR journal and from the system to allow recovery to continue with the command. In the case of a ﬂagged "EXCEPTION" transaction the system administrator can take action by changing the state of the "EXCEPTION" transaction to that of "DONE" with the

/NEW_STATE=DONE

to allow the recovery to continue.

SHOW TRANSACTION

command or the

DUMP

SET PARTITION/RECOVERY_RETRY_COUNT=nn

SET TRANSACTION

SET TRANSACTION/STATE=EXCEPTION

4–2 Transaction Management

4.1.2 Transaction State Changes

There are eight valid state changes allowed for the Attempting to change transaction state to a state that is not allowed produces an error message of

state to the specified state

changes.

Table 4–19 Valid Transaction State Transitions

Current State COMMIT ABORT EXCEPTION DONE

SENDING YES VOTED YES YES COMMIT YES YES EXCEPTION YES YES PRI_DONE YES

Four typical situations are listed below where transaction state changes by the system administrator are allowed.

%RTR-E-INVSTATCHANGE, Invalid to change from current

Transaction Management

4.1 Overview

SET TRANSACTION

. The Table 6–19 table identiﬁes the valid state

NEW STATE

command.

1. State

2. State

3. State

SENDING

The application server, after receiving a calling situation and cannot proceed. Aborting this transaction with the

rtr_accept_tx( )

TRANSACTION

will send the ABORT message to the router as well as the all participating servers to abort this transaction in a consistent matter.

VOTED

This is the case where a application server running on the backend may have been separated from the rest of participating servers after casting the VOTE for the transaction. The other servers may have already committed the transaction but not ‘‘forgotten’’ it. As far as the application is concerned, this global transaction is committed and all changes have been committed to the underlying database on the different sites. However, the local transaction record is still in VOTED state in the RTR journal. You can use the command to manually commit the local transaction branch.

Note that this command is only applicable if there is no coordinating router running, i.e., servers are separated from the rest of the RTR network. If this is not the case, RTR rejects the command.

VOTED

In a similar manner to the VOTED-to-COMMIT situation described above, the server has been separated from the other participating servers and all other participants aborted this transaction; use this command to manually abort the local transaction branch.

Note that this command is only applicable if there is no coordinating router running and servers are separated from the rest of the RTR network. If this is not the case, RTR rejects the command.

changed to state

ABORT

rtr_mt_msg_1

for a particular transaction, experiences a ‘‘hung’’

message and before

SET

command is the only way to correct it. Internally, RTRACP

changed to state

COMMIT

ABORT

4. State

COMMIT

changed to state

DONE

Transaction Management 4–3

Transaction Management

4.1 Overview

This is the case where, for example, a server crashed while performing an SQL commit immediately after receiving a transaction is in COMMIT state as recorded in the RTR journal and the transaction is also committed in the underlying database.

mt_accepted

message. The

After the be used to verify the result.

SET TRANSACTION

command is executed the

DUMP JOURNAL

command can

4–4 Transaction Management

This chapter contains a description of the RTR monitor. The RTR monitor gives you a means of viewing the activities of RTR and your applications. Many different aspects of RTR’s behaviour can be viewed, allowing the activities and performance of RTR to be analyzed.

5.1 Introduction

The RTR monitor provides a means to continuously display the status of RTR and the applications using it.

It can be used to check the correct operation of an RTR network, showing information useful for tuning, capacity planning, and locating conﬁguration and application errors.

RTR Monitoring

The information displayed is composed of named continuously updated by RTR. These data items can be displayed in various formats, and combined using simple arithmetic operators and constants.

The monitor is invoked with the

monitor picture

of the A monitor picture contains elements that are either text (such as labels and

titles) or variables derived from data items. Monitor pictures can be deﬁned either interactively at the

You can use monitor ﬁles that are provided with RTR, and you can create your own. See Appendix A for information about creating monitor ﬁles.

MONITOR

that is periodically updated. See Section 6.2 for the full syntax

command.

RTR>

5.2 Standard Monitor Pictures

A number of standard monitor pictures are supplied with RTR. These cover most of the usual monitoring requirements. You may deﬁne your own monitor pictures or alter the standard ones to suit your particular needs. Table 5–1 contains a list of the standard monitor pictures. To display one of these pictures use the following command at the RTR prompt:

RTR> MONITOR

The ﬁles for standard monitor pictures are installed on your system when RTR is installed. The location of these ﬁles is platform-speciﬁc. The ﬁlenames are the picture name appended with starting the display.)

picture-name

data items

RTR MONITOR

prompt or deﬁned in a ﬁle called a

.mon

(You type the ﬁlename without

command. RTR monitor displays a

which are

monitor file

.mon

when

RTR Monitoring 5–1

RTR Monitoring

5.2 Standard Monitor Pictures

Obsolete monitor pictures have been removed from the documentation.

Table 5–1 Standard Monitor Pictures

Picture name Description

Note

accfail Shows link transport name for links on which a connection attempt was declined,

acp2app Displays counts of messages and number of bytes from RTRACP to the application,

active Displays a list of RTR processes, and for each process the number of transactions

app2acp Displays counts of messages and number of bytes from the application to RTRACP,

broadcast Displays information about RTR user events by process, including number of user

calls Displays the total number of RTR API calls and their success or failure for the

channel Displays the roles of the channels declared by an application. This can be useful as a

congest Displays a sorted list of nodes responsible for causing the most congestion since RTR

connects Displays connection status summary, including the number of links up and down,

ddtm Displays counts of RTR calls to DECdtm, as viewed from a speciﬁc node, for all PIDs,

dtx Displays counts of RTR DTX calls including open, start, prepare, rollback, commit,

dtxrec Displays a summary of DECdtm transaction recovery (DTX), as viewed from a

event Displays event routing data by facility. Information includes events in transit

facility Displays a number of per facility data items. The

ﬂow Displays the ﬂow control counters. frontend Displays frontend status and counts by node and facility, including frontend state

group Shows server and transaction concurrency on a partition basis. ipc Shows counts of inter-process communication (IPC) activity in the RTR ACP and

ipcrate Displays rate information on IPC messages, byte counts, and IO primitive usage.

with a reason for failure. The most recent entry is highlighted.

as viewed from a speciﬁc node.

they have started, the number of transactions they have completed and the number of transactions that are still active.

as viewed from a speciﬁc node.

events enqueued, received, and discarded.

processes on all the nodes being monitored. All RTR message are also show by message type. (Pending messages are ones that an application has not received yet). Use the speciﬁc process, otherwise the total values for all processes are displayed.

debugging tool in the early stages of application development.

was last started, and the instantaneous state.

and a list of links with state (up or down), architecture, network transport, and fail-reason, if any.

processes, and images.

and close, as viewed from a speciﬁc node for all PIDs, processes, and images.

speciﬁc node for all PIDs, processes, and images.

and destination information showing number of events enqueued, processed, and discarded.

to say which facility should be monitored. If this is not speciﬁed then the totals of the data items for all facilities are displayed.

current router, reject status, retry count, and quorum rejects.

active RTR applications.

/IDENTIFICATION=process-id

qualiﬁer to display the values for one

/FACILITY

qualiﬁer can be used

(continued on next page)

5–2 RTR Monitoring

Table 5–1 (Cont.) Standard Monitor Pictures

Picture name Description

RTR Monitoring

5.2 Standard Monitor Pictures

jcalls Displays counts of successful (success), failed (fail) and total journal calls for local

journal Displays the current journal usage on a node. Local node journal statistics are

link Displays a number of per link data items.

netbytes Displays a list of the links to other nodes. For each link, the total number of bytes

netstat For each link, displays the connection status in detail, with the link state (up or

partit Displays the status of server partitions. Shows the partition identiﬁers, key ranges

queues Shows transaction queues on a partition basis. quorum Tracks (by facility) the conﬁguration, reachability and quorum status of one or more

rdm Displays memory used by each RTR subsytem. recovery Displays the status of server recovery procedures, such as waiting for quorum,

rejects Displays the last rejhist Displays the last ten response Displays the elapsed time that a transaction has been active on the opened channels

rfb Displays router failback operations, including both a summary and detail by facility. rolequor A detailed picture of the various data items displayed in the QUORUM picture,

routers Displays information on a router node. It gives an indication of the utilization of the

routing Displays statistics of transaction and broadcast trafﬁc by facility. rscbe Displays the most recent calls history for the RSC subsystem on a backend node. rtr Displays various per node data items. stalls Displays in real time any network links that are currently stalling in their outbound

system Displays the state of critical resources within the RTR environment. If a resource

tps Displays the rate of transaction commits carried out by each process using RTR. tpslo Displays low end of the rate of transaction commits carried out by each process using

and remote journals.

provided, and data for non-local journals accessed from the local node. Include statistics covering total number of entries and records written, the number of records read, and how many bytes were involved. Bar graphs showing current usage of journal blocks (as a percentage of the total) are also provided.

/LINK=link-name

The be displayed, otherwise the total values for all links are displayed.

received and sent on that link and the number of bytes received and sent per second are displayed.

down), and architecture type of remote node (such as VAX, I386, Alpha, and so on).

and key segments, and the status of the servers (active, recovering and so on).

nodes.

catching up transactions, and so on.

of a process.

separated by roles. If a quorum problem is encountered, this picture may be useful for problem diagnosis.

router in terms of transactions and broadcasts routed through this node. Useful to monitor performance, or locate problems.

trafﬁc, and provides a history of the stalls that the various links encountered during their lifetime.

has exceeded a predeﬁned threshold, a warning indicator is displayed.

RTR.

qualiﬁer can be used if the values for one speciﬁc link are to

rtr_mt_rejected

message received by each running process.

messages received by the selected process.

(continued on next page)

RTR Monitoring 5–3

RTR Monitoring

5.2 Standard Monitor Pictures

Table 5–1 (Cont.) Standard Monitor Pictures

Picture name Description

trafﬁc Displays a list of the links to other nodes. Shown for each link are: byte rate, packet

trans Displays transactions for a frontend, router and backend. v2calls Shows RTR Version 2 verb usage through the interoperability subsystem. The screen

xa Displays XA counter information including success and failure as well as call and

rate, message rate and congestion, in both directions. Average packets per second is also shown.

layout is identical to the RTR Version 2 monitor calls picture.

readonly counters.

The following sections describe the more commonly used standard monitor pictures in detail.

5.2.1 Monitor ACCFAIL (Link Acceptance Failures)

When conﬁguring RTR it can happen that nodes sometimes fail to connect up. Whilst the cause of the error can be viewed on the initiator side with the MONITOR NETSTAT picture, it can be difﬁcult to pinpoint the problem when looking at the other end of the link. The monitor picture ACCFAIL can be used to display the reason for the local node to refuse to accept connections. An example:

================================================================================

Most recent links on which a connection attempt was declined

Node: LENGTH Wed Jan 7 1998 10:51:00

-------------------------------------------------------------------------------Link Transport Name(s) Reason for failure

-------------------------------------------------------------------------------ilira node is not configured for the facility dmark.zko.dec.com node not recognized breal facility name not matched DMARK DEC:.ZKO.DMARK node not recognized ilira node is not configured for the facility dmark.zko.dec.com node not recognized breal facility name not matched sfranc node role definitions do not match for breal facility name not matched DMARK DEC:.ZKO.DMARK node not recognized

-------------------------------------------------------------------------------List entries are reused in a cyclical fashion; the most

recent entry is highlighted.

================================================================================

Unacceptable Links

Some of the errors that can be displayed by ACCFAIL are:-

• RTR_STS_NOTRECOGNISED - "node not recognized"

5–4 RTR Monitoring

The local node has received a connection request over a link that is not conﬁgured in any facility on the local machine. If you expected the connection to succeed as the result of having a template link deﬁned, check carefully the names displayed in the monitor picture. These are the names obtained from the network transport over which the link connection attempt was received, and it is with these that a match with a template (wildcard speciﬁcation) link must succeed. Bear in mind that the name match is performed in a case sensitive manner. Names corresponding to TCP links may or may nor contain

RTR Monitoring

5.2 Standard Monitor Pictures

your domain name, depending on how the name is entered in either your local hosts ﬁle or name server. DECnet-Plus systems may yield both a pseudonym and a link name; both are checked for a match with a template.

• RTR_STS_FACNOTDEC - "facility name not matched" The connecting link is conﬁgured, but the facility that it requests does not

exist on the local node.

• RTR_STS_NODENOTCNFG - "node is not conﬁgured for the facility" The connecting link is conﬁgured on the local node, but not as part of the

requested facility.

• RTR_STS_ROLESMISMATCH - "node role deﬁnitions do not match for this facility"

The connecting link is conﬁgured in the requested facility, but with a different role conﬁguration on the local node.

• RTR_STS_TRNOQUO - "router has no quorum in facility %s" The router is unable to accept front end connections since it is not quorate.

This condition will clear up automatically as soon as the router gains connections to sufﬁcient backends.

5.2.2 Monitor ACP2APP

RTR ACP to Application Messages, Node: NodeA PID: -ALL- Process name: -ALL-

Image: -ALL- 14:15:46 Mon Jan 25 1999

messages client server other pend opened 0 0 0 0 0 0 0

closed 0 0 0 0 0 0 0 msg1 0 0 0 msg1_uncertain 0 0 0 msgn 0 0 0 repl_2_client 0 0 0 rettosend 0 0 0 accepted 0 0 0 0 0 rejected 0 0 0 0 0 user_event 0 0 0 0 0 rtr_event 0 0 0 0 0 mt_prepare 0 0 0

request_info 0 0 0 set_info 0 0 0

receive_message 0 0 0 0 user_wakeup 0 0

Displays counts of messages and number of bytes from RTRACP to the application, as viewed from a speciﬁc node. Includes openend, closed, msg1, msg1_uncertain, msgn, repl_2_client (reply to client), rettosend (return to sender), accepted, rejected, user_event, rtr_event, mt_prepare, request_info, and set_info messages as appropriate. For receive_message and user_wakeup, displays calls, active, fail, and timeout counts.

# Bytes # Bytes # Bytes #

other

calls active fail timeout

The default is to display information on all PIDs, process names, and images. To display information on one process only, user the qualifer /IDENTIFICATION=

process-id

RTR Monitoring 5–5

RTR Monitoring

5.2 Standard Monitor Pictures

5.2.3 Monitor Active

ACTIVE TRANSACTIONS BY PROCESS Fri Mar 12 1999 19:32:41

All processes: 5 5 0 Node ID Process Image

NodeA 11141 11141 rtr 5 5 0

Displays a list of RTR processes, and for each process the number of transactions they have started, the number of transactions they have completed and the number of transactions still active.

5.2.4 Monitor APP2ACP

RTR Application to ACP Messages, Node: NodeA PID: -ALL- Process name: -ALL-

Image: -ALL- 14:21:19 Mon Jan 25 1999

messages client server other open_channel 0 0 0 0 0 0

close_channel 0 0 0 0 0 0 accept_tx 0 0 0 0 reject_tx 0 0 0 0 broadcast_event 0 0 start_tx 0 0 send_to_server 0 0 reply_to_client 0 0 request_info 00 set_info 00

Starts Completions Active

# Bytes # Bytes # Bytes

Displays counts of messages and number of bytes from the application to RTRACP, as viewed from a speciﬁc node. Includes open_channel, close_channel, accept_tx (accept transaction), reject_tx (reject transaction), broadcast_event, start_tx, send_to_server, reply_to_client, request_info, and set_info.

The default is to display counts for all PIDs and processes, for client, server, and other roles.

5.2.5 Monitor Broadcast

Node ID Process Received Queued Lost Rate of delivery Total 2750 5 17 850.0

NODEA 20400249 RTRACP 0 0 0 NODEA 2040024D BATCH_2993 2750 5 17 850.0 NODEA 2040024B BATCH_2991 0 0 0 NODEA 2040024C BATCH_2992 0 0 0

Displays information about the RTR user events process. Fields displayed included number of user events enqueued for the application, number of user events received by the application, and number of user events discarded by RTR.

BROADCAST RECEPTION BY PROCESS 15:20:27 6-APR-1999

5–6 RTR Monitoring

5.2.6 Monitor Calls

RTR api calls, Node: nodea.zuo.dec.com , PID: 2162 , Process name: -ALLImage: -ALL- Fri Feb 12 1999 16:38:05 CALLS client server fail MESSAGES client server pend open_channel 1 1 0 mt_opened 1 1 0 close_channel 0 0 0 mt_closed 0 0 0 start_tx 0 0 mt_msg1 0 1 send_to_server 1 0 mt_msg1_uncertain 0 0

reply_to_client 0 0 mt_reply 0 0 prepare_tx 0 0 mt_prepared 0 0

accept_tx 0 0 0 mt_accepted 0 0 0 reject_tx 0 0 0 mt_rejected 0 0 0 broadcast_event 0 0 0 mt_user_event 0 0 0 set_user_handle 0 0 0 mt_rtr_event 0 0 0 get_tid 0 0 0 mt_prepare 0 0

request_info 3 0 mt_request_info 2 0 set_info 0 0 mt_set_info 0 0 error_text 2 mt_closed 2 set_wakeup 0

receive_message 9 1 2 2 user wakeup 0 0

RTR Monitoring

5.2 Standard Monitor Pictures

mt_msgn 0 0 mt_rettosend 0 0

other other

calls active fail timeout

Displays the total number of RTR API calls and their outcome for the processes on all the nodes being monitored. Use the to display the values for one speciﬁc process, otherwise the total values for all processes are displayed.

5.2.7 Monitor Channel

RTR CHANNELS BY TYPE PER PROCESS Fri Feb 12 1999 16:41:13

Node ID Process Image Pri. Sby. Router Backend nodea 2162 2162 1 0 0 0 0

Displays the channels opened by RTR CALL RTR_OPEN_CHANNEL comands.

5.2.8 Monitor Connects

Node: nodea.zuo.dec.com Tue Feb 16 1999 13:02:18

-Executive summary----------------------------------------

----------------------------------------------------------

-Detail-------------------------------------------------------------------------

Node -> Link State Arch T’port Fail-reason

--------------:-----:-----:------:----------------------------------------------

nodea->nodea up alpha nodea->nodeb up alpha TCP nodea->nodec up i386 TCP

/IDENTIFICATION=process-id

Client Server Call-out

Connection Status Summary

Number of links up: 3 (100.%)

Number of links down: 0 (0.0 %)

qualiﬁer

RTR Monitoring 5–7

RTR Monitoring

5.2 Standard Monitor Pictures

Displays the link protocol for connected links, and the fail reason as a text message for any links on which a connection has failed. Unconnected links where connection have been attempted are highlighted. Link state and architecture of the remote node are also displayed. Summarizes link status and is less detailed than the monitor netstat display.

5.2.9 Monitor Event

EVENT ROUTING STATISTICS BY FACILITY 6-APR-1999 15:21:47

Node Facility In Out Lost In Out Lost Total 180 175 5 180 180 0

NODEA FACCMS 25 25 0 25 25 0 NODEA TESTFAC 155 150 5 155 155 0

Displays event routing data by facility. Information includes events in transit from RTR to a destination facility and destination information showing number of events enqueued for the application (In column), number of events processed by the application (Out column), and the number of events discarded by RTR (Lost column).

Destination Transit

5.2.10 Monitor Facility

FACILITY COUNTERS 7-JAN-1999 14:04:27, NODE: -ALL- , FACILITY: -ALL-

ASM_MSGS_TO_APPS 290005 TMBE_TX_RQ_COMMITS 0 NCF_TR_FE_LOSS 0 ASM_MSGS_FROM_APPS290404 TMBE_TX_RQ_ABORTS 0 NCF_TR_BE_LOSS 0 BM_NCF_EVENTS_DELV 6 TMBE_TX_ACCEPTS 72501 NCF_TR_FE_GAIN 1 BM_NCF_EVENTS_RCVD 7 TMBE_TX_REJECTS 0 NCF_TR_BE_GAIN 1 TM_NCF_EVENTS_RCVD 13 TMBE_TX_RTR_FORGETS 72499 NCF_TR_FQM_LOSS 0 TMFE_TX_RQ_STARTS 72700 TMBE_CRPS_REQUESTED 0 NCF_FE_TR_LOSS 0 TMFE_TX_RQ_ENQS 72700 RSC_GETTXDST_CALLS 72700 NCF_FE_TR_NOCUR 0 TMFE_TX_RQ_COMMITS 72700 RSC_GETTXDST_SUCCESS 72700 NCF_FE_TR_GAIN 1 TMFE_TX_RQ_ABORTS 0 RSC_GETTXSRV_CALLS 0 NCF_BE_TR_LOSS 0 TMFE_TX_ACCEPTS 72500 RSC_GETTXSRV_SUCCESS 0 NCF_BE_TR_GAIN 1 TMFE_TX_REJECTS 0 RSC_GETEVTDST_CALLS 0 NCF_FQM_TR_LOSS 0 TMFE_TX_REPLAYS 0 RSC_GETEVTDST_SUCCESS 0 QRM_REQ_LINK_QUEUE 0 TMRT_TX_RQ_STARTS 72700 RSC_GETEVTRCV_CALLS 6 QRM_RSP_LINK_QUEUE 0 TMRT_TX_RQ_ENQS 72700 RSC_GETEVTRCV_SUCCESS 0 TMRT_TX_RQ_COMMITS 72700 RSC_FE_NODES 1 TMRT_TX_RQ_ABORTS 0 RSC_BE_NODES 1 TMRT_TX_ACCEPTS 72500 RSC_TR_SERVER_CLASSES 1 TMRT_TX_REJECTS 0 RSC_BE_SERVER_CLASSES 1 TMBE_TX_RQ_STARTS 72700 RSC_SERVER_CHANS 1 TMBE_TX_RQ_ENQS 72700 RSC_REQUESTER_CHANS 2

Displays per facility counters. Use the it is not speciﬁed then the totals of the counters for all facilities are displayed.

/FACILITY

qualiﬁer to specify a facility; if

5–8 RTR Monitoring

5.2.11 Monitor Flow

FLOW CONTROL COUNTERS 7-JAN-1999 14:08:06, NODE: -ALL- , FACILITY: -ALL-

ROLE AVAILABLE BYTES/SEC WAITS SENT PENDING SENT PENDING FE=>TR 15000 2065 307 966 0 966 0 TR=>BE 15000 2065 70 998 0 998 0 BE=>TR 0 0 0 0 0 0 0 TR=>FE 15000 0 0 2 0 2 0

LINK DATA RATE WAITS PENDING REQS SENT CACHE IN USE NODEA =>NODEA 0 0 0 1 NODEA 0 NODEA =>NODEB 0 0 0 0 NODEB 51456 NODEB =>NODEB 2065 307 0 968 NODEB =>NODEA 2065 70 0 999

Displays the ﬂow control internals.

5.2.12 Monitor Group

% rtr monitor group

Concurrency Measures Tue Apr 6 1999 10:04:26, NODE: NODEA

krid state cnt cnt act vreq vote ack /csn act /sec /csn 16777216 shd_rec_fail 0 1 0 00000.00.00.0 16777217 shd_rec_fail 0 1 0 00000.00.00.0

RTR Monitoring

5.2 Standard Monitor Pictures

CREDIT DATA RATE REQUESTS GRANTS

-- averages --

txn -server- -- transactions -- srv txn txn

Table 5–2 MONITOR GROUP Fields

Field Meaning

krid Key range (partition) identiﬁer. state Partition state. txn cnt Number of transactions executed for this partition. srv cnt Number of servers active for this partition. srv act Number servers that are currently busy processing txns for this sample. The following ﬁelds track the progress of a transaction through the states: vote requested,

voted, acknowledged. vreq Number of transactions that are waiting for the server to vote. vote Number of transactions that have been voted on by the server but not

ack Number of transactions that have been committed but have not been

/csn Number of transactions which have been grouped under the same ‘‘commit

txn/sec The average rate of transaction starts per second for this partition. txn/csn average number of transactions which have been grouped under the same

committed by RTR.

acknowledged by the server. Acknowledgment occurs on a subsequent

rtr_receive_message()

to get a message for a new transaction.

sequence number’’ (CSN). This grouping determines the ordering of transactions submitted to a secondary shadow server.

commit sequence number (CSN) since this partition became active. This average is computed as the quotient of the number of CSN’s.

call by the server processing this transaction

txn cnt

column and the total

RTR Monitoring 5–9

RTR Monitoring

5.2 Standard Monitor Pictures

5.2.13 Monitor IPC

RTR> Monitor IPC Node: LENGTH I P C S u mmary FriMar 51999 11:18:34

+----------------------------------------------------------------------------+

This screen displays usage information on IPC messages, byte counts and IO primitives. Display units are counts, kbytes and calls respectively.

+----------------------------------------------------------------------------+

Process Messages ...kbytes send() ...kbytes Messages recv() ...kbytes rtracp 110334 49744 73437 49744 73434 220299 5616 3123B84F 0 0 0 0 0 0 0 31232395 73282 5569 73280 5569 109930 293144 49685

Displays interprocess communication message information.

|-----Outgoing/s----|--Incoming/s--|

5.2.14 Monitor IPCRATE

RTR> Monitor IPCRATE Node: LENGTH I P C R a t e s Fri Mar 5 1999 11:18:53

+----------------------------------------------------------------------------+

This screen displays rate information on IPC messages, byte counts and IO primitive usage. Display units are counts, kbytes and calls per second respectively.

+----------------------------------------------------------------------------+

Process Messages ...kbytes send() ...kbytes Messages recv() ...kbytes rtracp 44 19 29 19 29 86 2 3123B84F 0 0 0 0 0 0 0 31232395 28 2 28 2 41 110 18

Displays interprocess communication rate information for messages.

|-----Outgoing/s----|--Incoming/s--|

5.2.15 Monitor Journal

5–10 RTR Monitoring

JOURNAL USAGE ON NODE NODEA AT 10:36:05 Tue Apr 6 1999 LOCAL JOURNAL STANDBY JOURNAL(S) JNL_LCL_BLOCKS_IN_USE 128 JNL_RMT_BLOCKS_IN_USE 0

[___ 13% ] [ 0% ] JNL_LCL_NR_BLOCKS 992 JNL_RMT_NR_BLOCKS 992 JNL_LCL_TOP_BLOCKS_USED 128 JNL_RMT_TOP_BLOCKS_USED 0 JNL_LCL_BLOCKS_AVAILABLE 864 JNL_RMT_BLOCKS_AVAILABLE 0 JNL_LCL_TX_ENTRIES 1 JNL_RMT_TX_ENTRIES 0 JNL_LCL_TX_RECORDS 2 JNL_RMT_TX_RECORDS 0 JNL_LCL_MEMORY_BYTES 530121 JNL_RMT_MEMORY_BYTES 4197 JNL_LCL_DISK_READS 31 JNL_RMT_DISK_READS 33 JNL_LCL_BLOCKS_READ 992 JNL_RMT_BLOCKS_READ 1056 JNL_LCL_DISK_WRITES 12 JNL_RMT_DISK_WRITES 0 JNL_LCL_BLOCKS_WRITTEN 14 JNL_RMT_BLOCKS_WRITTEN 0 JNL_LCL_ENTRIES_TOTAL 201 JNL_RMT_ENTRIES_TOTAL 5 JNL_LCL_RECORDS_TOTAL 398 JNL_RMT_RECORDS_TOTAL 9 JNL_LCL_RECORDS_READ 21 JNL_RMT_RECORDS_READ 0 JNL_LCL_REC_BYTES_READ 8006 JNL_RMT_REC_BYTES_READ 0 JNL_LCL_NONTX_ENTRIES 5 JNL_RMT_NONTX_ENTRIES 0

JNL_LCL_OPEN_JOURNALS 2

Displays information about journal usage, including total number of entries and records written, number of records read, and how many bytes were involved. Bar graphs showing current usage of journal blocks (as a percentage of the total) are also provided.

The local journal ﬁgures refer to journal usage for the displayed node. Standby journals are journals of standby nodes that are being accessed due to restart or catch-up situations. Under normal conditions standby journal ﬁgures are all zero.

The bar graphs appear under the ﬁrst line of the display (JNL_LCL_BLOCKS_IN_USE).

5.2.16 Monitor Link

LINK COUNTERS 8-MAR-1999 14:24:44, NODE: -ALL- , LINK: -ALL- -> -ALL-

NCF_PROTOCOL 0 NIO_WRITING 0 NCF_TIMEOUT 0 NIO_READING 0 NCF_LINKEXIT 0 NIO_WRERROR 0 NCF_DISCONNECT 0 NIO_RDERROR 0 NCF_THIRDPARTY 0 NIO_RDINCMP 0 NCF_PATHLOST 0 NIO_SEQERR 0 NCF_RESPONSES_SENT 3 NIO_BUFOVF 0 NCF_QUERIES_RCVD 11 NIO_READS_ACTIVE 3 NCF_RESPONSES_RCVD 2 NIO_WRITES_ACTIVE 0 NCF_QUERIES_SENT 10 NIO_BYTES_RCVD 44206961 NCF_IPT_MSGS_RCVD 16 NIO_BYTES_SENT 44206996 NCF_IPT_MSGS_SENT 16 NIO_PCKTS_RCVD 412114 NCF_LINK_GAIN 4 NIO_PCKTS_SENT 412114 NCF_LINK_LOSS 0 NIO_MSGS_RCVD 189284 NCF_ABORTED 0 NIO_TMO_SENDS 161307 NCF_REJECTEE 1 QRM_REQ_LINK_QUEUE 0 NCF_ACCEPTED 1 QRM_RSP_LINK_QUEUE 0 NCF_CONFIRMED 1 NCF_INITIATED 2

RTR Monitoring

5.2 Standard Monitor Pictures

Displays a number of per link counters. The used if the values for one speciﬁc link are to be displayed, otherwise the total values for all links are displayed.

5.2.17 Monitor Netbytes

LINK TRAFFIC IN BYTES Fri Apr 16 1999 17:41:12, NODE: nodea.zko.dec.com

Total 59201466 6776.0 - 1002579480 113857.0 nodea->nodea 3072248 336.0 336.0 3072248 336.0 336.0

nodea->nodeb 42569496 4974.0 4974.0 717457678 84438.0 84438.0 nodea->nodec 13559722 1466.0 1466.0 282049554 29083.0 29083.0

Displays a list of the links to other nodes. For each link, the total number of bytes received and sent on that link and the number of bytes received and sent per second are displayed. Derived from the NIO_BYTES_RCVD and NIO_ BYTES_SENT counters. The Max ﬁeld represents the maximum rate since the link started.

/LINK=link-name

Bytes Rcvd Bytes Sent

-------------------------- -------------------------Abs Rate Max Abs Rate Max

qualiﬁer can be

RTR Monitoring 5–11

RTR Monitoring

5.2 Standard Monitor Pictures

5.2.18 Monitor Netstat

Connection Status Detail

Node: NODEA Mon March 15 1999 09:50:28

Ini Cnf Acc Abo Rej Loss Gain Ctmo Rstr State Type FailCode

Node Link 12 0 2 12 12 1 3 0 0 NODEA ->nodeb 0 00000100upalpha

NODEA ->nodec 6 00660000down ? 76490676 NODEA ->noded 6 00660000down ? 76490676 NODEA ->nodee 0 02001200upalpha

Displays the link status for connected links in detail and the fail code for any links on which a connection has failed. Unconnected links where connection have been lost are highlighted. Link aborts, rejects, loss, gain, restarts, state and architecture of the remote node are also displayed. More detail included than in in the monitor connects display.

5.2.19 Monitor Partit

PARTITION DEFINITIONS Tue Apr 6 1999 10:40:31, NODE: NODEA Partition-name # # bounds callout

RTR$DEFAULT_PARTITION_16777218 active 1 1 "A" "A" RTR$DEFAULT_PARTITION_16777221 active 1 1 "B" "B" RTR$DEFAULT_PARTITION_16777217 active 1 1 0 429496

State svrs segs lo hi type

Partitions are shown in the form

if a partition name has been speciﬁed using the SET PARTITION command.

name

node$facility_partition-idorpartition

The number of servers and key segments are shown for each partition. The least signiﬁcant byte of the partition’s low and high bound is also shown, and callout type (if any). The partition state meanings are given in Table 5–3.

Table 5–3 Monitor Partition States

State Meaning

wt_tr_ok Server is waiting for routers to accept it wt_quorum Server is waiting for backend to be quorate lcl_rec Local recovery lcl_rec_fail Primary server waiting for access to a restart journal lcl_rec_icpl Getting next journal to recover from lcl_rec_cpl Processed all journals for local recovery shd_rec Shadow recovery shd_rec_fail Shadow server waiting for access to a restart journal shd_rec_icpl Shadow getting next journal to recover from shd_rec_cpl Processed all journals for shadow recovery catchup Secondary is catching up with primary standby Server is declared as standby

(continued on next page)

5–12 RTR Monitoring

Table 5–3 (Cont.) Monitor Partition States

State Meaning

active Server is active pri_act Server is active as primary shadow sec_act Server is active as secondary shadow remember Primary is running without shadow secondary

5.2.20 Monitor Queues

TRANSACTION QUEUES BY PARTITION 15-JAN-1999 12:42:53, NODE: NODEA

Partition-name Processed Queued # NODEA$NODEB$16842753 5792 5794 0 2 6 3

Shows transaction queues on a partition basis. Uses counters from Transaction Manager (TM) and the Requester/Server conﬁgurator (RSC).

5.2.21 Monitor Quorum

RTR Monitoring

5.2 Standard Monitor Pictures

Txns Msgs Rplys Txn Msg Svrs

QUORUM STATUS BY NODE AND FACILITY Tue Apr 6 1999 10:50:24, NODE: NODEA (node/role counts can be inaccurate for incorrectly configured facilities) States: bad configuration,not connected,minority,uncertain,quorate node/roles Node Facility State CNF RCH QRT NODEA RTR$DEFAULT_FACILITY TR:quorate,BE:quorate 2 2 2 NODEA shadow TR:quorate,BE:minority(ffranc) 4 2 1

Quorum states are shown for router (TR) and backend (BE) nodes and roles in the columns

The number of nodes seen as conﬁgured (CNF), reachable (RCH) and quorate (QRT) are shown for each node, in the columns

State

node/roles

5.2.22 Monitor Recovery

RECOVERY INFORMATION at Tue Apr 6 1999 10:54:50 on NODEA

Partition-id State Backend Scans Recovered Scans Recovered

Server Recovery Journal Txns Journal Txns

------------ ------ ------- ------- --------- ------- --------16777218 active NODEA 1 0 0 0 16777221 active NODEA 1 0 0 0 16777217 active NODEA 1 0 0 0

Shows the progress of transaction recovery. Last recovery backend is the last backend accessed to recover transactions. If the server state is lcl_rec_fail or shd_ rec_fail, this entry is the name of the background which could not be accessed. Journal scans is the number of journal ﬁles searched. Transactions recovered is the number of transactions found for this partition.

Last Restart-Recovery Shadow-Recovery

RTR Monitoring 5–13

RTR Monitoring

5.2 Standard Monitor Pictures

Server recovery state meanings are shown in Table 5–4.

Table 5–4 Monitor Recovery States

State Meaning

5.2.23 Monitor Rejects

NODE: NODEA PROCESS: 20413894 Fri Apr 9 1999 10:26:14

Time Pid Chan Reason Status Text

------------------- ------ ------ -------- ----------------------------Fri Apr 9 10:18:43 20417266 client 0 No server available to handle Fri Apr 9 10:17:47 20417274 server 0 Client aborted tx

Displays the last

Table 5–5 MONITOR REJECTS Fields

Field Meaning

Time Time of day that the Pid The process id that received the message. Chan The type of channel (client or server) that received the message. Reason The reason ﬁeld returned in the Status Text The textual status that describes the reject reason.

Rejected Transaction Summary

rtr_mt_rejected

message received by each running process.

rtr_mt_rejected

message was received.

rtr_status_data_t

buffer.

5–14 RTR Monitoring

5.2.24 Monitor Rejhist

RTR Monitoring

5.2 Standard Monitor Pictures

NODE: NODEA PROCESS: 38009A8B Mon Mar 9 1999 10:26:14

------------------- ------ ------- -------------------------------------Mon Mar 15 18:06:06 client 0 Client aborted tx Mon Mar 15 18:06:41 server 0 Normal successful completion Mon Mar 15 18:06:41 client 0 Server aborted tx

-------------------------------------------------------------------------------

Displays the last ten This picture should always be invoked with the /ID qualiﬁer. The transaction identiﬁer associated with the rejected transaction can be displayed with the SHOW PROCESS <id>/COUNTER=

Table 5–6 MONITOR REJHIST Fields

Field Meaning

Time Time of day that the Chan The type of channel (client or server) that received the message. Reason The reason ﬁeld returned in the Status Text The textual status that describes the reject reason.

Time Chan Reason Status Text

rtr_mt_rejected

Rejected Transaction History

number of reject msgs = 3 number of accept msgs = 0 rejected / total txns = 100%

messages received by the selected process.

api_reject*

rtr_mt_rejected

command.

message was generated.

rtr_status_data_t

buffer.

5.2.25 Monitor Response

Process Image Client Response Time Server Response Time

ID Name seconds 0 1 2 3 4 seconds 0 1 2 3 4 20413894 SERVER.EXE;4 0.000 3.670 20417266 RTR.EXE;75 2.200 3.440 20417274 SERVER.EXE;4 0.000 1.160

Displays the elapsed time that a transaction has been active on the opened channels of a process. On the client, transaction duration is measured between the

rtr_mt_acceptedorrtr_mt_rejected

also marks the end of a transaction. On the server, transaction duration is measured between receipt of a message and the receipt of the ﬁnal call. Accepted transaction end times are recorded when the server issues a

rtr_receive_message

rtr_start_txorrtr_send_tx

TRANSACTION DURATION AT 10:24:51 Fri Apr 9 1999

call and the receipt of the ﬁnal

message. A call to

rtr_reject_tx

rtr_mt_msg1orrtr_mt_msg1_uncertain

rtr_mt_rejected

call to request a new transaction for processing.

message or

rtr_reject_tx

RTR Monitoring 5–15

RTR Monitoring

5.2 Standard Monitor Pictures

5.2.26 Monitor Rolequorum

QUORUM COUNTS BY FACILITY 7-JAN-1999 14:32:48, NODE: -ALL-

Router View of Backend View of

backends routers backend routers

CNF RCH QRT CNF RCH QRT CNF RCH QRT CNF RCH QRT

VIP 111 111 111 111

5.2.27 Monitor Routers

ROUTER TRANSACTION COUNTERS AT 14:33:29 7-JAN-1999

Node: -ALLFacility: -ALL-

Starts: 116641 25.7 Enqueues: 116641 25.7 Commits: 116641 25.6 Aborts: 0 0.0

Abs Rate 10 20 30 40 50 60 70 80 90 100

Displays information on a router node. It gives an indication of the utilization of the router in terms of transactions and broadcasts routed through this node. Useful to monitor performance, or locate problems. Uses counters in the Transaction Manager (TM) subsystem.

5.2.28 Monitor Routing

ROUTING STATISTICS BY FACILITY Thu Apr-15-1999 14:34:20, NODE: -ALL-

Total 118489 39.2 68444 994.0 VIP 118489 39.2 68444 994.0

Displays statistics of transaction and broadcast trafﬁc by facility. Rate is the number of transactions or broadcasts per second within the monitoring interval.

Transactions Broadcasts

Absolute Rate Absolute Rate

5–16 RTR Monitoring

5.2.29 Monitor RSCBE

RTR> Monitor rscbe

Most Recent RSC Dclsrv Calls History on Backend LENGTH Thu Mar 4 1999,15:19:41 Key Range Id: 16777216 Partition Start Time: THU MAR 4 15:18:22 1999

Image Name: RTR.EXE T-delta RSC calls router state seq_nr

0 send_dcl_to_master sfranc wait_for_response 0 1 recv_status_ok sfranc rstart_rvy 1 1 send_dcl_to_master sfranc rstart_rvy_incomp 1 1 recv_status_ok sfranc rstart_rvy 1 1 send_dcl_to_master sfranc rstart_rvy_incomp 1 1 recv_status_ok sfranc active 1 1 send_dcl_to_other depth active 1 1 recv_status_ok depth active 1

Displays backend request to server messages and declared state for routers

5.2.30 Monitor RTR

RTR Monitoring

5.2 Standard Monitor Pictures

RTR> Monitor RTR

RTR COUNTERS 7-JAN-1999 14:35:05, NODE: -ALL-

ACP_WAKEUPS 310484 QRM_QCXTS 48 ACP_WAKE_REQS 859200 QRM_QIRS 0 CM_BYTES_PRESENT 1048576 QRM_RAES 0 CM_BYTES_IN_USE 51968 QRM_MAXQUOTA 278718 CM_FREECHCPCKT 3738 QRM_CURQUOTA 278718 TIM_TIMER_SETS 238349 QRM_RDES 18 TIM_TIMER_CANCELS 34165 QRM_QARS 0 TIM_TIMER_DELIVERS 204174 QRM_QUERIES_SENT 481308 TM_QRM_QUERIES_SENT 0 QRM_QUERIES_RCVD 481308 TM_QRM_QUERIES_RCVD 0 QRM_RESPONS_SENT 3082 NCF_REJECTEE 1 QRM_RESPONS_RCVD 3092 NCF_REJECTER 1 QRM_RETRIES 7 NCF_FACILITY_UP 2 QRM_TIMEOUTS 0 NCF_FACILITY_DOWN 0 RSC_ALLOC_MEM 2098

Displays various per node counters.

RTR Monitoring 5–17

RTR Monitoring

5.2 Standard Monitor Pictures

5.2.31 Monitor Stalls

NETWORK STALLS AT 29-JAN-1999 15:35:03, ON NODE: TR1

Issued Rate Sent Drops Secs <3s <10s <30s >30s Tot Total 5467 0.0 327148 2 33 23 1 0 0 24 TR1 -> TR1 29 0.0 3718 0 0 0 0 0 0 0 TR1 -> FE2 509 0.0 20707 0 4 4 0 0 0 4 TR1 -> BE1 303 0.0 13707 0 3 3 0 0 0 3 TR2 -> TR2 111 0.0 11682 0 0 0 0 0 0 0 TR2 -> BE1 504 0.0 22743 0 18 8 1 0 0 9 Stall FE1 -> FE1 64 0.0 6645 0 0 0 0 0 0 0 FE1 -> FE2 373 0.0 18890 0 2 2 0 0 0 2 FE1 -> BE1 310 0.0 24487 0 0 0 0 0 0 0 FE2 -> FE2 231 0.0 18900 0 0 0 0 0 0 0 FE2 -> BE1 284 0.0 22503 1 1 1 0 0 0 1 FE2 -> TR1 536 0.0 28166 0 0 0 0 0 0 0 FE2 -> FE1 396 0.0 23643 0 0 0 0 0 0 0 BE1 -> BE1 355 0.0 28121 0 0 0 0 0 0 0 BE1 -> FE2 284 0.0 13014 1 0 0 0 0 0 0 BE1 -> TR2 515 0.0 27502 0 2 2 0 0 0 2 BE1 -> TR1 328 0.0 25698 0 1 1 0 0 0 1 BE1 -> FE1 335 0.0 17022 0 2 2 0 0 0 2

QIOs Bytes Link Stalls

Displays in real time any network links that are currently stalling (that is, waiting to transmit outbound trafﬁc) and provides a history of the stalls that the various links have encountered during their lifetime. The display shows:

The total number of network QIOs issued, Rate of network QIOs per second, Total number of bytes sent, Number of DECnet link losses, Total waited seconds for QIO completions, Number of 1 to 2 second stalls, Number of 3 to 9 second stalls, Number of 10 to 29 second stalls, Number of stalls longer than 30 seconds, Total number of stalled QIOs, Current number of incomplete network writes.

5–18 RTR Monitoring

5.2.32 Monitor System

RTR Monitoring

5.2 Standard Monitor Pictures

System Status at 10:27:51 Fri Apr 9 1999

node: NODEA

Resource OK Warning

Facility QUORUM states...... x

JOURNAL free space.......... x

Note: Additional detail

Link CONNECTS............... x about a resource can be

obtained by monitoring

Link traffic STALLS......... x the subsystem specified

in capital letters.

FLOW control credits........ x

For example, to get more

PARTITION states............ x information on links

type MONITOR CONNECTS

CALL Msg outstanding.......... x

To modify threshold values,

Transaction QUEUES............ x edit the file SYSTEM.MON.

Transaction REJECTS........... x

Broadcast EVENT discards...... x

Displays the state of critical resources within the RTR environment. If a resource has exceeded a predeﬁned threshold, a warning indicator is displayed.

The default thresholds are as follows:

Quorum Warn if any roles are inquorate. Journal Warn if journal free space is less than 30% of total. Links Warn if any link is disconnected. Stalls Warn if 10 second stalls are greater than 1% of all messages sent. Flow Warn if the wait is more than one second for 10% of the total credit

Partition Warn if any of the partitions are not in one of the following states:

Calls Warn if any messages have been pending for more than 30 seconds. Queues Warn if the transaction queue cannot be emptied within 10 seconds. Rejects Warn if the number of rejects (non-user) is greater than 5% of the total

Events Warn if the number of discards is greater than 5% of the total events

requests.

Standby, Active, Pri_act, or Sec_act.

transactions processed, or a reject (non-user) has occurred within the last 30 minutes.

sent.

Threshold values can be customized by editing the ﬁle SYSTEM.MON.

RTR Monitoring 5–19

RTR Monitoring

5.2 Standard Monitor Pictures

5.2.33 Monitor TPS

TRANSACTION COMMITS BY PROCESS 14:37:23 7-JAN-1999

Node ID Process Abs. Rate 10 20 30 40 50 60 70 80 90 100

-ALL- 00000000 -REQUESTERS- 123298 31.8

-ALL- 00000000 -SERVERS- 123297 28.9 NODEA 20200BEA RTRACP 0 0.0 NODEA 20200C03 ANDERS_1 123297 28.9 NODEB 21400724 RTRACP 0 0.0 NODEB 214005F0 ANDERS_1 123298 31.8

Same as TOPTPS except that a given process is always displayed at the same position on the screen, that is, the list is not sorted by TPS.

5.2.34 Monitor Trafﬁc

RTR> Monitor Traffic

Total 13465.5 13213.3 123.8 121.2 239.1 53.3 53.3 35 0.0 NODEA -> NODEA 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0 0.0

NODEA -> NODEB 10718.0 2705.8 95.1 27.5 118.9 24.9 27.2 28 0.0 NODEB -> NODEB 41.7 41.7 1.2 1.2 1.4 1.2 1.2 0 0.0 NODEB -> NODEA 2705.8 10465.8 27.5 92.5 118.8 27.2 24.9 7 0.0

Commits

LINK TRAFFIC 7-JAN-1999 14:38:08, NODE: -ALL-

Bytes/second Packets/sec Messages/sec Congestion

Rcvd Sent Rcvd Sent Avrg Rcvd Sent Abs Rate

Displays a list of the links to other nodes. Shown for each link are: byte rate, packet rate, message rate and congestion, in both directions. Average packets per second is also shown. Uses counters in the Network I/O (NIO) subsystem.

5.2.35 Monitor Trans

RTR> Monitor Trans monitoring transactions Thu Mar 4 1999 15:21:38, NODE: NODEA

Tid (Frontend) Facility FE-User 46d01f10,0,0,0,0,baa09da,abf10001 RTR$DEFAULT_FACILITY RTRCSV_TETRAUL aborting

Tid (Router) Facility FE-User

State

Tid (Backend) Facility FE-User 46d01f10,0,0,0,0,baa09da,abf10001 RTR$DEFAULT_FACILITY RTRCSV_TETRAUL aborting

Displays transaction state for transactions in a facility.

5–20 RTR Monitoring

5.2.36 Monitor V2CALLS

RTR> Monitor V2CALLS RTR system service calls, Node: NODEA , PID: 00000000, Process name: -ALL-

Image: -ALL- 13:09:18 5-MAR-1999 dcl_tx_prc/server 3 0 4 0 0 4

dcl_tx_prc/req. 1 dcl_tx_prc/shut. 0

start_tx 1 0 1 0 0 1 start_tx /timeout 0

enq_tx 1 0 50395 0 0 50395 enq_tx /broadcast 25187 enq_tx /reply 25207

deq_tx 50381 0 50391 0 2 50393 deq_tx /reply 12

commit_tx 1 0 1 0 0 1 abort_tx 0 0 0 0 0 0 vote_tx /commit 25187 0 25189 0 0 25189

vote_tx /abort 0 vote_tx /forget 2

RTR Monitoring

5.2 Standard Monitor Pictures

Accept Reject Success Failure Outstng Calls

Displays RTR Version 2 calls when running RTR Version 2 or mixture of RTR Version 3 and 2 environment.

5.2.37 Monitor XA

RTR> Monitor XA

MONITOR XA RTR XA Calls Node: nodea.zko PID: -ALL- Process name: -ALLImage: -ALL- 11:42:06 Tue 6-Apr-1999

open 0 0 0 0 close 0 0 0 0 start 0 0 0 0 end 0 0 0 0 prepare 0 0 0 0 commit 0 0 0 0 rollback 0 0 0 0 recovery 0 0 0 0

Txn starts 0.0 0

Displays XA calls when using XA with RTR.

Calls Success Readonly Failure

Rate 0 2 4 6 8 10 12 14 16 18 20 Active

RTR Monitoring 5–21

RTR Command Line Interface

Each RTR API call can be invoked This is provided to facilitate testing. For example, clients may be tested before the corresponding servers have been written by manually entering the server’s API calls.

6.1 Introduction

The commands that invoke the RTR API calls are similar to the call names. For example, the CLI-level.

Where possible, command qualiﬁers have been given the same names as the parameters to the API calls. See the Application Programmer’s Reference Manual for details about the parameters to API calls.

Most commands can be issued on remote nodes by using the or

/CLUSTER

command to specify nodes where commands are to be executed. Commands such as DEFINE KEY are intended for local execution only.

Output from each command can be redirected to another device or ﬁle using the

/OUTPUT

Because the RTR command utility keeps parameter checking to a minimum, ‘‘what if’’ questions can be answered quickly without having to write test programs.

at CLI level

rtr_accept_tx( )

qualiﬁers, or by preceding them with the SET ENVIRONMENT

qualiﬁer.

call is invoked using

using the RTR command utility.

CALL RTR_ACCEPT_TX

/NODE=node-list

at the

In a mixed RTR Version 2 and Version 3 environment, you cannot execute commands remotely with the /NODE qualiﬁer.

6.2 RTR Command Reference

This section describes in detail each command in the RTR command utility. The command descriptions are presented in alphabetical order.

Note

RTR Command Line Interface 6–1

ADD FACILITY

See CREATE FACILITY; ADD FACILITY is retained for compatibility reasons only.

6–2 RTR Command Line Interface

CALL RTR_ACCEPT_TX

The CALL RTR_ACCEPT_TX command causes a command server to execute the

rtr_accept_tx( )

Format

CALL RTR_ACCEPT_TX

Command Qualiﬁers Defaults

/CHANNEL_NAME=channel-name /CHANNEL_NAME=RTR$DEFAULT_CHANNEL /CLUSTER /NOCLUSTER /FORGET /NOFORGET /INDEPENDENT NOINDEPENDENT /NODE[=node-list] /NODE=default-node-list /OUTPUT[=ﬁle-spec] /OUTPUT=stdout /REASON[=reason] /REASON=0

Description

The CALL RTR_ACCEPT_TX command causes a command server to call the

rtr_accept_tx( )

CALL RTR_ACCEPT_TX

routine and to display the returned status.

routine using values supplied on the command line.

The numeric status returned from the call is then converted to its textual representation and displayed.

The

rtr_accept_tx( )

routine itself is described in Application Programmer’s

Reference Manual.

The prototype of

rtr_accept_tx( )

is:

rtr_status_t rtr_accept_tx (

rtr_channel_t channel, rtr_acc_flag_t flags, rtr_reason_t reason );

Table 6–1 shows the correspondence between values you supply on the command line and the C language parameter values produced and used for the call.

Table 6–1 Parameters for rtr_accept_tx

C Parameter Name C Parameter Value Command Line Speciﬁcation

channel /CHANNEL_NAME=name ﬂags RTR_NO_FLAGS [none] [D]

RTR_F_ACC_FORGET /FORGET

reason RTR_NO_REASON /NOREASON [D]

reason_value /REASON=reason_value

Issuing the CALL RTR_ACCEPT_TX command in preference to using the /ACCEPT qualiﬁer with the CALL RTR_SEND_TO_SERVER or CALL RTR_ REPLY_TO_CLIENT commands is only necessary when you wish to specify an acceptance "reason" other than the default value of zero (using the /REASON qualiﬁer).

RTR Command Line Interface 6–3

CALL RTR_ACCEPT_TX

Qualiﬁers

/CHANNEL_NAME=channel_name /CHANNEL_NAME=RTR$DEFAULT_CHANNEL

Speciﬁes the channel for which the operation is to be performed. The command server uses a combination of the channel_name and the window

from which the call was issued to uniquely identify which channel to use.

channel_name

The default channel name is RTR$DEFAULT_CHANNEL.

/CLUSTER /NOCLUSTER (D)

Speciﬁes that the command is executed on all the nodes in the cluster. If neither

nodes speciﬁed by the latest command has been entered then the command is executed only on the node where the command was issued.

Note: In environments that do not support clustering, use of the /CLUSTER qualiﬁer will cause the relevant command to be executed on the local node only.

/FORGET /NOFORGET

Use /FORGET to specify the call

rtr_accept_tx( )

The default for value for /FORGET is /NOFORGET, which causes the command server to use the value RTR_NO_FLAGS for the

rtr_accept_tx( )

/INDEPENDENT NOINDEPENDENT

Use the /INDEPENDENT qualiﬁer to specify the ﬂags parameter RTR_F_ACC_ INDEPENDENT in the call to rtr_accept_txt().

is not case sensitive.

/NODE

nor

/CLUSTER

is speciﬁed then the command is executed on the

SET ENVIRONMENT

flags

parameter as RTR_F_ACC_FORGET in the

command. If no

flags

parameter in the call to

SET ENVIRONMENT

/NODE[=node-list] /NODE=default-node-list (D)

Speciﬁes that the command is executed on all nodes speciﬁed in

node-list

command was issued.

/OUTPUT[=ﬁle-spec] /OUTPUT=stdout (D)

Speciﬁes that the resulting information is written to the ﬁle

is omitted then the command is executed only on the node where the

/OUTPUTorfile-spec

/REASON[=reason] /REASON=0

Use /REASON to supply a value for the

rtr_accept_tx( )

The default for value for /REASON is 0, which causes the command server to use the value RTR_NO_REASON for the

rtr_accept_tx( )

6–4 RTR Command Line Interface

node-list

file-spec

is omitted then the standard or default output is used.

reason

parameter in the call to

reason

parameter in the call to

.If

Related Commands

•

CALL RTR_OPEN_CHANNEL

•

CALL RTR_REJECT_TX

Examples

Accept the current transaction with a reason of 42.

RTR> CALL RTR_ACCEPT_TX /REASON=42 %RTR-S-OK, normal successful completion

CALL RTR_ACCEPT_TX

RTR Command Line Interface 6–5

CALL RTR_BROADCAST_EVENT

The CALL RTR_BROADCAST_EVENT command causes a command server to execute the

Format

CALL RTR_BROADCAST_EVENT [message-ﬁeld1] [,message-ﬁeld2...]

Parameters

[message-ﬁeld1] [,message-ﬁeld2...]

Specify the message to be sent (if any) as one or more comma separated parameter values. You can use the /TYPE_OF_DATA and /LENGTH_OF_DATA positional qualiﬁers on each parameter value to specify the data type and length of each ﬁeld.

Command Qualiﬁers Defaults

/CHANNEL_NAME=channel-name /CHANNEL_NAME=RTR$DEFAULT_CHANNEL /CLUSTER /NOCLUSTER /EVENT_NUMBER=evtnum none /FORMAT=fmt-string /NOFORMAT /LENGTH_OF_FIELD=message lengthDepends on data type; see description. /NODE[=node-list] /NODE=default-node-list /OUTPUT[=ﬁle-spec] /OUTPUT=stdout /RECIPIENT_SPEC=rcpspc /NORECIPIENT_SPEC /TYPE_OF_DATA=data type /TYPE_OF_DATA=STRING

rtr_broadcast_event( )

routine and to display the returned status.

Description

The CALL RTR_BROADCAST_EVENT command causes a command server to call the line.

The numeric status returned from the call is then converted to its textual representation and displayed.

The Programmer’s Reference Manual.

The prototype of

Table 6–2 shows the correspondence between values you supply on the command line and the C language parameter values produced and used for the call.

rtr_broadcast_event( )

routine using values supplied on the command

routine itself is described in Application

rtr_broadcast_event( )

rtr_status_t rtr_broadcast_event (

rtr_channel_t channel, rtr_bro_flag_t flags, rtr_msgbuf_t pmsg, rtr_msglen_t msglen, rtr_evtnum_t evtnum, rtr_rcpspc_t rcpspc, rtr_msgfmt_t msgfmt );

is:

6–6 RTR Command Line Interface

CALL RTR_BROADCAST_EVENT

Table 6–2 Parameters for rtr_broadcast_event

C Parameter Name C Parameter Value Command Line Speciﬁcation

channel /CHANNEL_NAME=name ﬂags RTR_NO_FLAGS [none] [D] pmsg, msglen,

msgfmt evtnum 42 /EVENT_NUMBER=42 rcpspc "workstat*" /RECIPIENT_SPEC="workstat*"

The actual values used for

command line parameter.

pmsg,msglen

and

msgfmt

The command server uses message data speciﬁed as command line parameter values to generate a record containing the message data (for the the message length (for the the

msgfmt

parameter).

msglen

[message deﬁnition parameter list with positional qualiﬁers. ]

are based upon the message deﬁnition you specify as a

parameter), and a record type description (for

pmsg

parameter),

Qualiﬁers

/CHANNEL_NAME=channel-name /CHANNEL_NAME=RTR$DEFAULT_CHANNEL

Speciﬁes the channel for which the operation is to be performed. The command server uses a combination of the

channel_name

and the window

from which the call was issued to uniquely identify which channel to use.

channel_name

is not case sensitive.

The default for channel-name is RTR$DEFAULT_CHANNEL.

/CLUSTER /NOCLUSTER (D)

Speciﬁes that the command is executed on all the nodes in the cluster. If neither

nodes speciﬁed by the latest

/NODE

nor

/CLUSTER

is speciﬁed then the command is executed on the

SET ENVIRONMENT

command. If no

SET ENVIRONMENT

command has been entered then the command is executed only on the node where the command was issued.

Note: In environments that do not support clustering, use of the /CLUSTER qualiﬁer will cause the relevant command to be executed on the local node only.

/EVENT_NUMBER=user-event-number

The user event number associated with this broadcast, in the range of RTR_EVTNUM_USERBASE to RTR_EVTNUM_USERMAX (i.e. 0 to 250).

/FORMAT[=fmt-string] /NOFORMAT (D)

Speciﬁes that a format string should be sent with this message. If /FORMAT is speciﬁed without

fmt-string

, RTR automatically generates a format string. The format string is generated using the parameters given for the qualiﬁers /SIGNED, /UNSIGNED, /STRING and /LENGTH. The following table shows permitted values for these qualiﬁers when using /FORMAT without

fmt-string

RTR Command Line Interface 6–7

CALL RTR_BROADCAST_EVENT

Table 6–3 Generated Format Strings

Data Type With /LENGTH= With /NOLENGTH

STRING =n, "%nC" "%nC" where n=strlen(string) SIGNED =1, "%SB" "%SL" SIGNED =2, "%SW" "%SL" SIGNED =4, "%SL" "%SL" UNSIGNED =1, "%UB" "%SL" UNSIGNED =2, "%UW" "%SL" UNSIGNED =4, "%UL" "%SL"

Refer to Application Programmer’s Reference Manual, section ‘‘Deﬁning a Message Format Description’’ for information on constructing a parameter.

/LENGTH_OF_FIELD=ﬁeld-length

Enter the size of the message ﬁeld that you want to deﬁne. The default for string types is the length of the message entered, plus one (for the zero termination byte). The default for signed and unsigned types is four. This is a positional qualiﬁer; it must immediately follow the message ﬁeld that it refers to.

fmt-string

Examples

/NODE[=node-list] /NODE=default-node-list (D)

Speciﬁes that the command is executed on all nodes speciﬁed in

node-list

command was issued.

/OUTPUT[=ﬁle-spec] /OUTPUT=stdout (D)

Speciﬁes that the resulting information is written to the ﬁle

/OUTPUTorfile-spec

/RECIPIENT_SPEC=rcpspc

Enter a string specifying the recipient name. The wild-card characters ‘‘*’’ and ‘‘?’’ are permitted.

RECIPIENT_SPEC is case sensitive

/TYPE_OF_DATA=STRING|SIGNED|UNSIGNED /TYPE_OF_DATA=STRING (D)

Enter the data type of the message ﬁeld that you want to deﬁne. The default is the string type. This is a positional qualiﬁer; it must immediately follow the message ﬁeld that it refers to.

is omitted then the command is executed only on the node where the

is omitted then the standard or default output is used.

node-list

file-spec

.If

This command broadcasts user event number 23 to all channels having a null string rcpnam (the default). A message is sent with the broadcast.

6–8 RTR Command Line Interface

CALL RTR_BROADCAST_EVENT

RTR> CALL RTR_BROADCAST_EVENT "Dollar is up"/EVENT_NUMBER=23 %RTR-S-OK, Normal successful completion

The following command broadcasts user event number 24 to all recipients whose /RECIPIENT_NAME matches the DEALER% string (that is, DEALER1, DEALER2, DEALERx). Note that only the event is broadcast, there is no associated message.

RTR> CALL RTR_BROADCAST_EVENT /EVENT=24/RECIPIENT_SPEC=DEALER% %RTR-S-OK, Normal successful completion

The following example shows a broadcast message containing two ﬁelds. The ﬁrst ﬁeld is of type unsigned, entered as a hexadecimal number; the second ﬁeld is of type string.

RTR> CALL RTR_BROADCAST_EVENT /EVENT=24 0xFA9BC0 /TYPE_OF_ DATA=UNSIGNED/LENGTH=8,"This field of the message is a string" %RTR-S-OK, Normal successful completion

RTR Command Line Interface 6–9

CALL RTR_CLOSE_CHANNEL

The CALL RTR_CLOSE_CHANNEL command causes a command server to

Format

Description

execute the

CALL RTR_CLOSE_CHANNEL

Command Qualiﬁers Defaults

/CHANNEL_NAME=channel-name /CHANNEL_NAME=RTR$DEFAULT_CHANNEL /CLUSTER /NOCLUSTER /IMMEDIATE /IMMEDIATE=RTR$DEFAULT_CHANNEL /NODE[=node-list] /NODE=default-node-list /OUTPUT[=ﬁle-spec] /OUTPUT=stdout

The CALL RTR_CLOSE_CHANNEL command causes a command server to call the

rtr_close_channel( )

routine and to display the returned status.

routine using values supplied on the command line.

The numeric status returned from the call is then converted to its textual representation and displayed.

The

rtr_close_channel( )

Programmer’s Reference Manual. The prototype of

rtr_status_t rtr_close_channel (

Table 6–4 shows the correspondence between values you supply on the command line and the C language parameter values produced and used for the call.

Table 6–4 Parameters for rtr_close_channel

C Parameter Name C Parameter Value Command Line Speciﬁcation

channel /CHANNEL_NAME=name ﬂags RTR_NO_FLAGS [none] [D]

rtr_close_channel( )

routine itself is described in Application

is:

rtr_channel_t channel, rtr_clo_flag_t flags );

Qualiﬁers

/CHANNEL_NAME=channel_name /CHANNEL_NAME=RTR$DEFAULT_CHANNEL

Speciﬁes the channel for which the operation is to be performed. The command server uses a combination of the channel_name and the window

from which the call was issued to uniquely identify which channel to use.

channel_name

The default channel name is RTR$DEFAULT_CHANNEL. You may close all the channels belonging to a window using

CLOSE CHANNEL/CHANNEL_NAME=*.

6–10 RTR Command Line Interface

is not case sensitive.

CALL RTR_CLOSE_CHANNEL

/CLUSTER /NOCLUSTER (D)

Speciﬁes that the command is executed on all the nodes in the cluster. If neither

nodes speciﬁed by the latest command has been entered then the command is executed only on the node where the command was issued.

Note: In environments that do not support clustering, use of the /CLUSTER qualiﬁer will cause the relevant command to be executed on the local node only.

/IMMEDIATE /IMMEDIATE=RTR$DEFAULT_CHANNEL

Speciﬁes the closing of a channel immediately without sending of a transaction acknowledgement.

Use /IMMEDIATE=RTR_F_CLO_IMMEDIATE to close the channel and recover any accepted transactions on this channel to an alternate server channel.

/NODE[=node-list] /NODE=default-node-list (D)

Speciﬁes that the command is executed on all nodes speciﬁed in

node-list

command was issued.

/OUTPUT[=ﬁle-spec] /OUTPUT=stdout (D)

Speciﬁes that the resulting information is written to the ﬁle

/OUTPUTorfile-spec

/NODE

nor

/CLUSTER

is omitted then the command is executed only on the node where the

is omitted then the standard or default output is used.

is speciﬁed then the command is executed on the

SET ENVIRONMENT

command. If no

SET ENVIRONMENT

node-list

file-spec

.If

Examples

This command closes the RTR$DEFAULT_CHANNEL.

RTR> CALL RTR_CLOSE_CHANNEL %RTR-S-OK, Normal successful completion

This command closes the channel named ‘‘client1’’.

RTR> CALL RTR_CLOSE_CHANNEL/CHANNEL_NAME=CLIENT1 %RTR-S-OK, Normal successful completion

RTR Command Line Interface 6–11

CALL RTR_ERROR_TEXT

The CALL RTR_ERROR_TEXT command causes a command server to execute the

rtr_error_text( )

Format

CALL RTR_ERROR_TEXT

Command Qualiﬁers Defaults

/OUTPUT[=ﬁle-spec] /OUTPUT=stdout /STATUS=status-code /none

Description

The CALL RTR_ERROR_TEXT command causes a command server to call the

rtr_error_text( )

The

rtr_error_text( )

Reference Manual.

routine using the value supplied on the command line.

routine and to display the returned error text.

routine itself is described in Application Programmer’s

The prototype of

Table 6–5 shows the correspondence between values you supply on the command line and the C language parameter values produced and used for the call.

Table 6–5 Parameters for rtr_error_text

C Parameter Name Parameter Value Command Line Speciﬁcation

sts 42 42 (parameter)

rtr_error_text( )

char *rtr_error_text (

rtr_status_t sts );

is:

Qualiﬁers

/OUTPUT[=ﬁle-spec] /OUTPUT=stdout (D)

Speciﬁes that the resulting information is written to the ﬁle

/OUTPUTorfile-spec

/STATUS=status-code No default

Speciﬁes the

sts

is omitted then the standard or default output is used.

parameter in the

rtr_request_info( )

call.

file-spec

.If

Examples

This command shows the text associated with error number 4849722.

RTR> CALL RTR_ERROR_TEXT /STATUS=4849722 error text normal successful completion

6–12 RTR Command Line Interface

CALL RTR_GET_TID

The CALL RTR_GET_TID command causes a command server to execute the

rtr_get_tid( )

Format

CALL RTR_GET_TID

Command Qualiﬁers Defaults

/CHANNEL_NAME=channel-name /CHANNEL_NAME=RTR$DEFAULT_CHANNEL /CLUSTER /NOCLUSTER /NODE[=node-list] /NODE=default-node-list /OUTPUT[=ﬁle-spec] /OUTPUT=stdout

Description

The CALL RTR_GET_TID command causes a command server to call to the

rtr_get_tid( )

The transaction id returned from the call is converted to its textual representation and displayed.

CALL RTR_GET_TID

routine and to display the returned status.

routine using values supplied on the command line.

The

rtr_get_tid( )

Reference Manual. The prototype of

rtr_status_t rtr_get_tid (

void* ptid

Table 6–6 shows the correspondence between values you supply on the command line and the C language parameter values produced and used for the call.

Table 6–6 Parameters for rtr_get_tid

C Parameter Name Parameter Value Command Line Speciﬁcation

channel /CHANNEL_NAME=name ﬂags RTR_NO_FLAGS [none] [D]

routine itself is described in Application Programmer’s

rtr_get_tid( )

is:

rtr_channel_t channel, rtr_tid_flag_t flags,

);

Qualiﬁers

/CHANNEL_NAME=channel_name /CHANNEL_NAME=RTR$DEFAULT_CHANNEL

Speciﬁes the channel for which the operation is to be performed. The command server uses a combination of the channel_name and the window

from which the call was issued to uniquely identify which channel to use. The default channel name is RTR$DEFAULT_CHANNEL.

/CLUSTER /NOCLUSTER (D)

Speciﬁes that the command is executed on all the nodes in the cluster.

RTR Command Line Interface 6–13

CALL RTR_GET_TID

Examples

If neither nodes speciﬁed by the latest command has been entered then the command is executed only on the node where the command was issued.

Note: In environments that do not support clustering, use of the /CLUSTER qualiﬁer will cause the relevant command to be executed on the local node only.

/NODE[=node-list] /NODE=default-node-list (D)

Speciﬁes that the command is executed on all nodes speciﬁed in

node-list

command was issued.

/OUTPUT[=ﬁle-spec] /OUTPUT=stdout (D)

Speciﬁes that the resulting information is written to the ﬁle

/OUTPUTorfile-spec

This command shows the transaction id active on channel ‘‘CLIENT1’’.

RTR> CALL RTR_GET_TID/CHANNEL=CLIENT1

%RTR-S-OK, normal successful completion

tid: e100b810,0,0,0,0,3bc5,6eb02001

/NODE

nor

/CLUSTER

is omitted then the command is executed only on the node where the

is omitted then the standard or default output is used.

is speciﬁed then the command is executed on the

SET ENVIRONMENT

command. If no

SET ENVIRONMENT

node-list

file-spec

.If

6–14 RTR Command Line Interface

CALL RTR_OPEN_CHANNEL

The CALL RTR_OPEN_CHANNEL command causes a command server to execute the

Format

CALL RTR_OPEN_CHANNEL

Command Qualiﬁers Defaults

/ACCEPT_EXPLICIT /NOACCEPT_EXPLICIT /ACCESS=access /NOACCESS /BE_CALL_OUT /NOBE_CALL_OUT /CHANNEL_NAME=channel-name /CHANNEL_NAME=RTR$DEFAULT_CHANNEL /CLIENT /NOCLIENT /CLUSTER /NOCLUSTER /CONCURRENT /CONCURRENT /EVENTS[=event-nr-list] /NOEVENTS /FACILITY_NAME[=facility-name] /FACILITY_NAME=RTR$DEFAULT_FACILITY /FOREIGN_TM[=tm_id] /NOFOREIGN_TM /HIGH_BOUND=high-bound /HIGH_BOUND=max-value-for-key-type /KEY1=keysegdesc /KEYn=keysegdesc /LENGTH_OF_FIELD=key-ﬁeld-length /LENGTH_OF_FIELD=4 /LOW_BOUND=low-bound /LOW_BOUND=lowest value for key-type /NODE[=node-list] /NODE=default-node-list /OFFSET_OF_KEY=offset /OFFSET_OF_KEY=0 /OUTPUT[=ﬁle-spec] /OUTPUT=stdout /PARTITION_NAME=partition-name /PREPARE_EXPLICIT /NOPREPARE_EXPLICIT /RECIPIENT_NAME=rcpnam /RECIPIENT_NAME=null /SERVER /NOSERVER /SHADOW /NOSHADOW /STANDBY /STANDBY /TR_CALL_OUT /NOTR_CALL_OUT /TYPE_OF_FIELD=key-ﬁeld-type /TYPE_OF_FIELD=UNSIGNED

rtr_open_channel( )

CALL RTR_OPEN_CHANNEL

routine and to display the returned status.

Description

The CALL RTR_OPEN_CHANNEL command causes a command server to call the

rtr_open_channel( )

routine using values supplied on the command line.

The numeric status returned from the call is then converted to its textual representation and displayed.

The

rtr_open_channel( )

routine itself is described in Application Programmer’s

Reference Manual.

The prototype of

rtr_open_channel( )

is:

RTR Command Line Interface 6–15

CALL RTR_OPEN_CHANNEL

rtr_status_t rtr_open_channel (

rtr_channel_t *pchannel, rtr_ope_flag_t flags, rtr_facnam_t facnam, rtr_rcpnam_t rcpnam, rtr_evtnum_t *pevtnum, rtr_access_t access, rtr_numseg_t numseg, rtr_keyseg_t *pkeyseg );

Table 6–7 shows the correspondence between values you supply on the command line and the C language parameter values produced and used for the call.

Table 6–7 Parameters for rtr_open_channel

C Parameter Name C Parameter Value Example

channel /CHANNEL_NAME=name ﬂags RTR_NO_FLAGS none [D]

RTR_F_OPE_CLIENT /CLIENT RTR_F_OPE_SERVER /SERVER RTR_F_OPE_BE_CALL_OUT /BE_CALL_OUT RTR_F_OPE_NOCONCURRENT /NOCONCURRENT RTR_F_OPE_EXPLICIT_PREPARE /PREPARE_EXPLICIT RTR_F_OPE_EXPLICIT_ACCEPT /ACCEPT_EXPLICIT RTR_F_OPE_FOREIGN_TM /FOREIGN=tm_id RTR_F_OPE_SHADOW /SHADOW RTR_F_OPE_NOSTANDBY /NOSTANDBY RTR_F_OPE_TR_CALL_OUT /TR_CALL_OUT

facnam "CASHFACIL" /FACILITY_NAME=CASHFACIL rcpnam "CLI6CHAN" /RECIPIENT_NAME=CLI6CHAN pevtnum [All events. See /EVENTS] /EVENTS=(USER,RTR) access J67TF098 /ACCESS=J67TF098 numseg 1 pkeyseg

-> ks_type rtr_keyseg_string /TYPE_OF_FIELD=STRING

-> ks_length 10 /LENGTH_OF_FIELD=10

-> ks_offset 2 /OFFSET_OF_KEY=2

-> ks_lo_bound "AAAAAAAAAA" /LOW_BOUND="AAAAAAAAAA"

-> ks_hi_bound "NNNNNNNNNN" /HIGH_BOUND="NNNNNNNNNN"

Qualiﬁers

/ACCEPT_EXPLICIT /NOACCEPT_EXPLICIT

Speciﬁes that the RTR_F_OPE_EXPLICIT_ACCEPT ﬂag is set in the call to

rtr_open_channel( )

6–16 RTR Command Line Interface

CALL RTR_OPEN_CHANNEL

/ACCESS=access /NOACCESS (D)

Speciﬁes an access string (that is, a password). All application programs (clients and servers) must specify the same access string for a given facility.

/BE_CALL_OUT /NOBE_CALL_OUT (D)

Speciﬁes that the RTR_F_OPE_BE_CALL_OUT ﬂag is set in the in the call to server.

/CHANNEL_NAME=channel-name /CHANNEL_NAME=RTR$DEFAULT_CHANNEL

Speciﬁes the name of the window’s channel for use in subsequent operations on this channel.

rtr_open_channel( )

. The channel is opened as a backend call-out

flags

parameter

channel_name

RTR$DEFAULT_CHANNEL.

/CLIENT /NOCLIENT

Speciﬁes that the RTR_F_OPE_CLIENT ﬂag is set on the call to

rtr_open_channel( )

/CLUSTER /NOCLUSTER (D)

Speciﬁes that the command is executed on all the nodes in the cluster. If neither

nodes speciﬁed by the latest command has been entered then the command is executed only on the node where the command was issued.

Note: In environments that do not support clustering, use of the /CLUSTER qualiﬁer will cause the relevant command to be executed on the local node only.

/CONCURRENT (D) /NOCONCURRENT

Specifying /NOCONCURRENT sets the RTR_F_OPE_NOCONCURRENT ﬂag in the call to servers. By default a server may have other concurrent servers.

is not case sensitive. The default channel name is

. The channel is opened as a client.

/NODE

nor

/CLUSTER

rtr_open_channel( )

is speciﬁed then the command is executed on the

SET ENVIRONMENT

, and the server may not be concurrent with other

command. If no

SET ENVIRONMENT

/EVENTS=event-nr-list /NOEVENTS (D)

The /EVENTS qualiﬁer speciﬁes that broadcast events are received on the channel. To subscribe to all user and RTR events, enter the qualiﬁer with no arguments. Enter /EVENTS=RTR to receive the full range of RTR events only. Enter /EVENTS=USER to receive the full range of USER events only. Specify particular ranges of event numbers using arguments in the following format:

/EVENTS=(RTR,n, TO,m, USER,p, TO,q) wheren,m,pandqare event numbers. The default is to listen to no events.

RTR Command Line Interface 6–17

CALL RTR_OPEN_CHANNEL

/FACILITY_NAME=facility-name /FACILITY=RTR$DEFAULT_FACILITY (D)

Speciﬁes the name of the facility for which the channel is declared. An application must specify the facility name when using the RTR CLI. The default facility name is RTR$DEFAULT_FACILITY.

/FOREIGN_TM[=tm_id] /NOFOREIGN_TM (D)

Valid for client channels only. This indicates that the global coordinating Transaction Manager (TM) is a Foreign TM (denoted as FTM), and that all TXs on this channel will be coordinated by the FTM. If this qualiﬁer is set, then calls to rtr_start_tx on this channel must supply a value for the jointxid parameter, which is the TXID of the TX.

A TM identiﬁer can also be passed in as parameter. It must be in the range of 0 to 65535. Default value is 0.

It is recommended that operators or script programs using nested transactions specify a TM identiﬁer, particularly if more than one process opens RTR client channels using the same FTM on the one node, or if different types of FTMs are used on the same node. When a process that has open FTM client channels fails, then the FTM must be able to ﬁnd out from RTR what state the transactions are in that were active in that process. Thus the FTM must be able to identify itself to RTR in order that RTR can ﬁnd out what transactions were active for that FTM channel. Generally, FTM client channels opened in the same process (and for the same FTM) can have a common TM identiﬁer, but FTM client channels opened in separate processes should have different TM identiﬁers.

Calling CALL RTR_OPEN_CHANNEL with the FOREIGN_TM qualiﬁer speciﬁed will cause a local journal scan to occur if a journal has not already been opened on that node.

/HIGH_BOUND=high-bound /HIGH_BOUND=max-val-for-key-type (D)

Speciﬁes the upper bound of the key range that the server handles. The interpretation of string then it is interpreted as text, otherwise it is interpreted as a numeric value. The default for speciﬁed key type.

If the key bound value length is less than the key length (given in /LENGTH_OF_ FIELD), the key bound will automatically be null-padded to the required length.

/KEYn=keysegdesc

Speciﬁes a partition key segment. Up to eight key segments may be deﬁned for a partition (KEY1, KEY2,... up to KEY8).

The syntax of the KEYn qualiﬁer is:

/KEYn= (type_of_key=[signed|unsigned|string], -

length_of_key=nnnn, offset_of_key=nnnn, low_bound=low-bound-string, high_bound=high_bound_string)

type_of_key= unsigned,signedorstring

high-bound

Speciﬁes the ﬁeld type of the key. The

depends on the key type. If the key is of type

is the largest possible value that can ﬁt in the

. The default is

unsigned

key-type

must be one of

6–18 RTR Command Line Interface

CALL RTR_OPEN_CHANNEL

length_of_key=nnnn

bytes. Use this qualiﬁer only if the key ﬁeld type is string, since the key length is in other cases implied by the key type. The default value for bytes.

offset_of_key=nnnn

The default is zero, that is, the key is at the start of the messages.

low_bound=

partition will service. The interpretation of the key is of type string then it is interpreted as text, otherwise it is interpreted as a numeric value. The default for can ﬁt in the speciﬁed key type.

If the key bound value length is less than the key length (given in

length_of_key

length.

high_bound=

partition will service. The interpretation of If the key is of type string then it is interpreted as text, otherwise it is interpreted as a numeric value. The default for can ﬁt in the speciﬁed key type.

If the key bound value length is less than the key length (given in

length_of_key

length.

Speciﬁes the lower bound of the key range that servers in the

), the key bound will automatically be null-padded to the required

Speciﬁes the upper bound of the key range that servers in the

), the key bound will automatically be null-padded to the required

Speciﬁes the length of the key ﬁeld in enqueued messages in

key-length

Speciﬁes the offset of the key within the messages in bytes.

low-bound

is the smallest possible value that

high-bound

depends on the key type; if

depends on the key type.

is the largest possible value that

is four

Note

The

/KEYn=keysegdesc

/xxx_OF_FIELD

/LENGTH_OF_FIELD=key-ﬁeld-length /LENGTH_OF_FIELD=4 (D)

Speciﬁes the length of the key ﬁeld in the enqueued messages in bytes. Use this qualiﬁer only if the key ﬁeld type is string, since the key length is in all other cases implied by the key type. The default value for

/LOW_BOUND=low-bound /LOW_BOUND=min-val-for-key-type (D)

Speciﬁes the lower bound of the key range that the server handles. The interpretation of string then it is interpreted as text, otherwise it is interpreted as a numeric value. The default for speciﬁed key type.

If the key bound value length is less than the key length (given in /LENGTH_OF_ FIELD), the key bound will automatically be null-padded to the required length.

/NODE[=node-list] /NODE=default-node-list (D)

Speciﬁes that the command is executed on all nodes speciﬁed in

node-list

command was issued.

is omitted then the command is executed only on the node where the

qualiﬁer.

low-bound

qualiﬁer is an alternative to use of the

key-length

depends on the key type. If the key is of type

low-bound

is the smallest possible value that can ﬁt in the

is four bytes.

node-list

.If

RTR Command Line Interface 6–19

CALL RTR_OPEN_CHANNEL

/OFFSET_OF_KEY=offset /OFFSET_OF_KEY=0 (D)

Speciﬁes the offset of the key within the messages in bytes. The default is zero, that is, the key is at the start of the messages. Note that only one key segment deﬁnition is allowed.

/OUTPUT[=ﬁle-spec] /OUTPUT=stdout (D)

Speciﬁes that the resulting information is written to the ﬁle

/OUTPUTorfile-spec

/PARTITION_NAME=partition-name

Enables a system manager to specify a particular named partition.

/PREPARE_EXPLICIT /NOPREPARE_EXPLICIT

Speciﬁes that the ﬂag RTR_F_OPE_EXPLICIT_PREPARE is set in the call to

rtr_open_channel( )

/RECIPIENT_NAME=rcpnam /RECIPIENT_NAME=null (D)

Speciﬁes an optional name for broadcast reception to be associated with the channel. Only broadcasts matching this name are delivered on the channel. (Note that to receive named events, the correct event number must also be speciﬁed.)

file-spec

is omitted then the standard or default output is used.

.If

RECIPIENT_NAME is case sensitive. If /RECIPIENT_NAME is supplied without a qualiﬁer value, then its value defaults to the value of /CHANNEL_NAME. Not supplying the /RECIPIENT_NAME qualiﬁer has the same effect as specifying a null string. Wild card characters broadcasts can use wildcards when specifying /RECIPIENT_SPEC).

/SERVER /NOSERVER (D)

Speciﬁes that the RTR_F_OPE_SERVER ﬂag is set in the call to

rtr_open_channel( )

as a server.

/SHADOW /NOSHADOW (D)

The /SHADOW qualiﬁer speciﬁes that the RTR_F_OPE_SHADOW ﬂag is set in the call to

/STANDBY (D) /NOSTANDBY

The /NOSTANDBY qualiﬁer speciﬁes that the ﬂag RTR_F_OPE_NOSTANDBY is set in the call to standby(s). By default, servers may have standby(s).

/TR_CALL_OUT /NOTR_CALL_OUT (D)

Speciﬁes that the RTR_F_OPE_TR_CALL_OUT ﬂag is set in the call to

rtr_open_channel( )

server is not a router call-out server.

. Use this qualiﬁer if you want to declare the channel

rtr_open_channel( )

, and the server is a router call-out server. By default a

cannot

. The server is part of a shadow pair.

be used for this qualiﬁer. (Senders of

, and the server may not be (or have)

6–20 RTR Command Line Interface

/TYPE_OF_FIELD=key-ﬁeld-type /TYPE_OF_FIELD=UNSIGNED (D)

Speciﬁes the ﬁeld type of the key. The SIGNED or STRING. The default is UNSIGNED.

Related Commands

•

CALL RTR_CLOSE_CHANNEL

Examples

This command opens a server channel called RTR$DEFAULT_CHANNEL that may not have concurrent servers, explicitly accepts transactions and listens for all RTR events.

RTR> CALL RTR_OPEN_CHANNEL/SERVER/NOCONCURRENT/ACCEPT_EXPLICIT/EVENTS=RTR %RTR-S-OK, Normal successful completion

This command open a client channel called ‘‘FIN1CHAN’’.

CALL RTR_OPEN_CHANNEL

key-type

must be one of UNSIGNED,

RTR> CALL RTR_OPEN_CHANNEL/CLIENT/CHANNEL=FIN1CHAN %RTR-S-OK, Normal successful completion

RTR Command Line Interface 6–21

CALL RTR_PREPARE_TX

The CALL RTR_PREPARE_TX command causes a command server to execute the

rtr_prepare_tx( )

Format

CALL RTR_PREPARE_TX

Command Qualiﬁers Defaults

/CHANNEL_NAME=channel-name /CHANNEL_NAME=RTR$DEFAULT_CHANNEL /DATA[=data] /DATA=0 /NODE[=node-list] /NODE=default-node-list /OUTPUT[=ﬁle-spec] /OUTPUT=stdout /REASON[=reason] /REASON=0

Description

The CALL RTR_PREPARE_TX command causes a command server to call the

rtr_prepare_tx( )

routine and to display the returned status.

routine using values supplied on the command line.

The numeric status returned from the call is then converted to its textual representation and displayed.

The

rtr_prepare_tx( )

routine itself is described in Application Programmer’s

Reference Manual.

The prototype of

rtr_prepare_tx( )

is:

rtr_status_t rtr_prepare_tx (

rtr_channel_t channel, rtr_pre_flag_t flags,

rtr_reason_t reason rtr_msgbuf_t pmsg rtr_msglen_t msglen

);

Table 6–8 shows the correspondence between values you supply on the command line and the C language parameter values produced and used for the call.

Table 6–8 Parameters for rtr_prepare_tx

C Parameter name C Parameter Value Command Line Speciﬁcation

channel /CHANNEL_NAME=name ﬂags RTR_NO_FLAGS [none] [D] reason RTR_NO_REASON /NOREASON [D]

reason_value /REASON=reason_value

pmsg, msglen / DATA=data

The CALL RTR_PREPARE_TX command causes a command server to execute the rtr_prepare_tx( ) routine using the values supplied on the command line. The numeric status returned from the call is then converted to its textual representation and displayed.

6–22 RTR Command Line Interface

CALL RTR_PREPARE_TX

The CALL RTR_PREPARE_TX can only be used in the context of nested transactions (rtr_start_tx was called with the parameter join_txid not equal to NOJOIN_TXID). If this call returns RTR_STS_OK, then the ﬁrst (prepare) phase of the RTR 2PC protocol has been initiated.

Qualiﬁers

The message type associated with this command is the message types message type returns data of type this case, the status ﬁeld of rtr_status_data_t is always RTR_STS_OK, and the reason ﬁeld contains the same reason mask that would be returned in the rtr_ mt_accepted message type for the same TX were the TX to be accepted.

Only when the rtr_mt_prepared message is delivered, can the operator be sure that all participants of the nested TX are ready to commit. Alternatively, calling rtr_prepare_tx can result in the message rtr_mt_rejected being delivered if one of the participating servers votes to reject the nested TX.

The rtr_mt_prepared message is only delivered to the console if the rtr_prepare_ tx is called.

A call to rtr_prepare_tx must be followed at some point by a call to rtr_accept_tx (or rtr_reject_tx), which in this context implements the commit phase of the 2PC. (Generally, rtr_prepare_tx and rtr_accept_tx will be called by the foreign TM directly, not by the operator).

/CHANNEL_NAME=channel_name /CHANNEL_NAME=RTR$DEFAULT_CHANNEL

Speciﬁes the channel for which the operation is to be performed. The command server uses a combination of the channel_name and the window

from which the call was issued to uniquely identify which channel to use.

rtr_mt_accepted

and

rtr_status_data_t

rtr_mt_rejected

rtr_mt_prepared

, the

in the user buffer. In

. Similar to

rtr_mt_prepared

channel_name

The default channel name is RTR$DEFAULT_CHANNEL.

/DATA[=data] /DATA=0

The data parameter can be used to pass an ASCII string to RTR that will be saved in the local journal. This string is not sent to the routers or backends, and is used only during recovery, when it is passed back to the client application. RTR does not interpret or modify this data in any way. The maximum size of the data parameter is deﬁned as

/NODE[=node-list] /NODE=default-node-list (D)

Speciﬁes that the command is executed on all nodes speciﬁed in

node-list

command was issued.

/OUTPUT[=ﬁle-spec] /OUTPUT=stdout (D)

Speciﬁes that the resulting information is written to the ﬁle

/OUTPUTorfile-spec

is not case sensitive.

RTR_MAX_BLOB_LEN

is omitted then the command is executed only on the node where the

is omitted then the standard or default output is used.

and is set to 2048 bytes.

node-list

file-spec

.If

RTR Command Line Interface 6–23

CALL RTR_PREPARE_TX

/REASON[=reason] /REASON=0

Use /REASON to supply a value for the

rtr_prepare_tx( )

reason

parameter in the call to

The reason parameter to parameter in the subsequent the call to

rtr_prepare_tx( )

Related commands

•

CALL RTR_OPEN_CHANNEL

•

CALL RTR_REJECT_TX

Examples

Prepare the current transaction with a reason of 42.

RTR> CALL RTR_PREPARE_TX /REASON=42 %RTR-S-OK, normal successful completion

rtr_prepare_tx( )

rtr_accept_tx call( )

is used in place of the reason

(that is, the reason ﬁeld in

rtr_accept_tx call()orrtr_reject_tx( )

is ignored). The default for value for /REASON is 0.

which follows a call to

6–24 RTR Command Line Interface

Compaq AA-Q88CE-TE User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual