Compaq AAR-88LB-TE User Manual

ReliableTransactionRouter MigrationGuide

Order Number: AA–R88LB–TE

June 1999

This guide explains how to migrate from Reliable Transaction Router™ (RTR) Version 2 to RTR Version 3 on OpenVMS™ systems, and provides information on new and obsolete features.

Revision/Update Information: This guide supersedes the Reliable

Transaction Router Migration Guide for Version 3.1D.

Operating System: OpenVMS Versions 6.2, 7.1, 7.2 Software Version: Reliable Transaction Router Version

3.2

Compaq Computer Corporation Houston, Texas

First Printing, December 1997 Revised, June 1999

COMPAQ COMPUTER CORPORATION SHALL NOT BE LIABLE FOR TECHNICAL OR EDI‘ 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, DEC, DECconnect, DECdtm, DECevent, DECsafe, DECnet, DECwindows, DIGITAL, DIGITAL UNIX, LAT, OpenVMS, PATHWORKS, POLYCENTER, TruCluster, Reliable Transaction Router, VAX, and VMScluster.

The following are third-party trademarks: AIX and IBM are registered trademarks of International Business Machines Corporation.

Memory Channel is a trademark of Encore Computer Corporation. Hewlett-Packard and HP-UX are registered trademarks of Hewlett-Packard Company. Microsoft is a registered trademark, and Windows 95 and Windows NT are trademarks of Microsoft Corporation. Oracle is a registered trademark of Oracle Corporation. Solaris and SUN are registered trademarks of Sun Microsystems, Inc. POSIX is a registered trademark of the Institute of Electrical and Electronics Engineers. PostScript is a registered trademark of Adobe Systems, Inc. UNIX is a registered trademark licensed exclusively through X/Open Company Ltd. X Window System is a trademark of Massachusetts Institute of Technology.

All other trademarks and registered trademarks are the property of their respective holders.

This document was prepared using VAX DOCUMENT Version 2.1.

Contents

Preface ............................................................ vii

1 Introduction

1.1 Why Migrate? ............................................... 1–1

1.2 Goals and Nongoals . . ........................................ 1–2

1.3 Reading Guidelines . . ........................................ 1–2

2 Installation

2.1 Cleaning Up the Old Version 2 Environment ....................... 2–1

2.2 Preserving the Old Environment ................................ 2–2

2.3 Can Both RTR Version 2 and Version 3 Coexist On the Same Node? ..... 2–2

2.4 Can RTR Version 2 and Version 3 Applications Coexist on the Same

Node? ..................................................... 2–2

2.5 Process Quotas .............................................. 2–2

2.6 Journal Issues .............................................. 2–3

2.6.1 Removing the Old Journal . . ................................ 2–4

2.6.2 Journal Compatibility ..................................... 2–4

2.6.3 Location and Naming Conventions ........................... 2–4

2.7 Rights and Privileges . ........................................ 2–4

2.8 Memory and Disk Requirements ................................ 2–4

2.9 Rollback to RTR Version 2 ..................................... 2–5

3 Architectural Changes

3.1 RTR Daemon Process . ........................................ 3–1

3.2 Command Server Process ...................................... 3–1

3.3 The Shared Library (LIBRTR.EXE) .............................. 3–1

3.4 The ACP Process ............................................ 3–2

3.5 Interprocess Communication . . . ................................ 3–2

3.6 Shared Memory Parameters . . . ................................ 3–2

3.7 Counters . . ................................................ 3–2

3.8 Quorum Issues .............................................. 3–3

3.9 Server-Process Partition States . ................................ 3–3

4 Network Issues

4.1 DECnet Support ............................................. 4–1

4.2 TCP/IP Support ............................................. 4–1

4.3 Specifying a Preferred Transport ................................ 4–2

4.3.1 Supported Products ....................................... 4–2

iii

5 System Management

5.1 OpenVMS Quotas ............................................ 5–1

5.2 Startup.................................................... 5–1

5.3 Creating Facilities . . . ........................................ 5–1

5.3.1 Naming Nodes . . . ........................................ 5–1

5.3.2 Modifying Facility Conﬁgurations ............................ 5–1

5.4 Interoperability ............................................. 5–2

5.5 Monitoring . ................................................ 5–2

5.5.1 RTR Version 2 Screens ..................................... 5–2

5.5.2 New Screens ............................................ 5–2

5.5.3 User Parsing of Monitor Output ............................. 5–3

5.5.4 User Customized Monitors . . ................................ 5–3

5.5.5 History Screens . . ........................................ 5–4

5.6 Remote Command Support .................................... 5–4

5.7 Partition Management ........................................ 5–4

5.8 Transaction State Management . ................................ 5–4

5.9 Using RTR Version 2 Command Procedures ....................... 5–4

5.10 Command Line Interface Support for RTR Version 2 API ............. 5–4

5.11 Interpreting Output from SHOW Commands....................... 5–4

5.12 Comparing RTR Version 2 and Version 3 Utility Commands ........... 5–5

6 Running Version 2 Applications

6.1 Comparison of OpenVMS API and Portable API .................... 6–1

6.2 Recompiling and Relinking .................................... 6–2

6.2.1 RTR Version 2 Applications Running on RTR Version 3 ........... 6–3

6.3 Running Applications Installed with Privileges ..................... 6–4

6.3.1 Running Clients That Share Channels . ....................... 6–4

6.4 Application Level Interoperability ............................... 6–4

6.5 Support for $GETTXI. ........................................ 6–4

6.6 Threaded Applications ........................................ 6–5

6.7 DDTM Support ............................................. 6–5

6.8 Current Issues .............................................. 6–5

7 Performance Tips

7.1 Process Quotas .............................................. 7–1

7.2 Journal Sizing .............................................. 7–1

7.3 RTR Startup Qualiﬁers ....................................... 7–1

7.4 Monitoring . ................................................ 7–1

7.5 Memory . . . ................................................ 7–1

7.6 Simultaneous Multiprocessing . . ................................ 7–2

8 Problem Diagnosis and Reporting

8.1 RTR Operator Log . . . ........................................ 8–1

8.2 RTR_ERROR.LOG File ....................................... 8–1

8.3 Dump File . ................................................ 8–1

8.4 Producing and Directing a Trace ................................ 8–1

8.5 Dealing with a Looping Process . ................................ 8–2

8.6 Contents of the RTR Journal File ............................... 8–2

Index

Tables

2–1 OpenVMS Limits . ........................................ 2–3

2–2 OpenVMS Disk Requirements ............................... 2–5

3–1 RTR Executables . ........................................ 3–1

5–1 Interoperability Between Nodes .............................. 5–2

5–2 Obsolete RTR Version 2 Monitor Pictures ...................... 5–2

5–3 New RTR Version 3 Monitor Pictures . . ....................... 5–3

5–4 Changed SHOW COMMANDS ............................... 5–4

5–5 Obsolete OpenVMS RTR Utility Commands .................... 5–5

5–6 New OpenVMS RTR Utility Commands . ....................... 5–5

6–1 OpenVMS API and Portable API Comparison ................... 6–2

6–2 Application Interoperability . ................................ 6–4

Audience

Preface

This guide explains how to migrate a Reliable Transaction Router (RTR) environment and RTR applications from RTR Version 2 to RTR Version 3. It assumes that the application continues to use the RTR Version 2 application programming interface (API) without change. It also provides information on new and obsolete features.

This guide is written for RTR system managers. The system manager should be familiar with the following aspects of the

OpenVMS operating system:

• DIGITAL Command Language (DCL)

• A text editor, such as EDT or EVE The system manager should also be familiar with:

• Monitoring RTR performance

• Adjusting RTR performance

• Installation of RTR Version 2

• Making changes to the RTR environment

• Application use of the RTR Version 2 Application Programming Interface (API)

• Applications running on RTR

Organization of This Guide

The following list can help you ﬁnd information in this guide:

Chapter 1 Provides an introduction to the migration guide and summarizes new

Chapter 2 Describes changes to the installation procedure. Chapter 3 Describes how the RTR architecture has changed. Chapter 4 Describes changes to the network conﬁguration that supports RTR. Chapter 5 Describes changes important to the system manager. Chapter 6 Describes changes to the RTR API. Chapter 7 Describes performance and application tips. Chapter 8 Describes problem diagnosis and reporting.

and changed features.

vii

Related Documents

The following documents provide more information about topics discussed in this guide:

Document Title Description

Reliable Transaction Router

Installation Guide

Reliable Transaction Router

System Manager’s Manual

Reliable Transaction Router

Application Programmer’s Reference Manual

Reliable Transaction Router

Application Design Guide

Reliable Transaction Router

Release Notes

Describes how to install Reliable Transaction Router.

Describes how to conﬁgure, manage, and monitor Reliable Transaction Router

Describes how to code RTR applications, and contains full descriptions of RTR API calls.

Describes how to design applications that use RTR.

Describes new features, changes, and known restrictions for Reliable Transaction Router on all supported platforms.

The following document is your best source for information on OpenVMS procedures that you should be familiar with when using this migration guide:

Document Title Description

OpenVMS System Manager’s Manual: Essentials

Part one of a task-oriented guide to managing an OpenVMS system.

The following document is a useful source for writing applications on OpenVMS:

Document Title Description

DEC C Run-Time Library Reference Manual for OpenVMS

Reader’s Comments

Compaq welcomes your comments on this guide. Please send us your comments by email to rtrdoc@compaq.com. Include the title of the manual, date on the title page, section and page numbers with your comments or suggestions.

Conventions

The following conventions are used in this document.

Convention Meaning

Ctrl/X While you hold down the Ctrl key, press another key or a pointing

Italic Indicates parameters whose values you must provide. For example,

Describes use of the DEC C run-time library.

device button.

if the procedure asks you to type ﬁle name, you must type the actual name of a ﬁle.

Italic also indicates variables and the titles of referenced documents.

viii

Convention Meaning

monospace

Note: Provides information of special importance. / A forward slash in command descriptions indicates that a command

. . . A horizontal ellipsis following an entry in a command line indicates

. . .

Indicates the actual commands, words, or characters that you type in a dialog box, at a command prompt, or system output.

qualiﬁer follows.

that the entry or a similar entry can be repeated any number of times. An ellipsis following a ﬁle name indicates that additional parameters, values, or information can be entered.

A vertical ellipsis in an example indicates that not all the data are shown.

This document is intended to assist RTR Version 2 users to migrate to RTR Version 3.

1.1 Why Migrate?

Migration to RTR Version 3 takes advantage of the new features and improved capabilities of RTR Version 3. These include:

• Improved installation procedure using Polycenter Software Installation Utility (PCSI), not VMSINSTAL

• Interoperability with multiple operating systems including:

OpenVMS (Alpha and VAX) UNIX (DIGITAL UNIX, SUN Solaris, IBM AIX, HP–UX) Windows NT Windows 95 (client only)

• Improved ability to choose a primary server

Introduction

• Use of more than one other node for a standby server

• Network transport selection (DECnet or TCP/IP)

• New SHOW command screens containing information about transactional messages, resource managers, and some new state names

• New MONITOR pictures

• A new API, the Portable API

• Role clariﬁcation (Requestor changed to Client)

• Compatibility with Version 2 applications (no recompilation or linking required)

• Use of mailboxes instead of OpenVMS cache and global sections for interprocess communication

• Use of OpenVMS quotas, eliminating need for manually sizing conﬁguration parameters

• Enhanced partition management

• Enhanced journal management

• Exception logging

• Support for industry standard protocols for resource managers:

Microsoft DTC (Distributed Transaction Communicator) support XA protocol

Introduction 1–1

Introduction

1.1 Why Migrate?

• Support for subtransactions or nested transactions

Additionally, other considerations are:

• New features will be implemented in RTR Version 3, not in RTR Version 2

• Some software problems will be addressed only in RTR Version 3 and not in RTR Version 2

• Some improved capabilities are already available only in RTR Version 3

• More extensive release test coverage than with RTR Version 2

• RTR Version 3 tested for year 2000 compliance (RTR Version 3.1D, Version

3.2)

• Any residual year 2000 problems will be ﬁxed only in RTR Version 3.1D or later

Other changes introduced with RTR Version 3:

• New format and content of journal to improve security and ﬂexibility of transactional messaging

• Change of shared library name RTRSHR.EXE to LIBRTR.EXE

There is no upgrade path for Windows 3.1 clients; applications must be rewritten using the RTR Version 3 API.

1.2 Goals and Nongoals

The goal of this document is to assist the RTR Version 2 system manager in planning and implementing the migration of an RTR Version 2 environment to RTR Version 3.

It is not a goal of this document to instruct the system manager about RTR or teach troubleshooting or analysis of the RTR environment.

1.3 Reading Guidelines

Read this document, the RTR Version 3 documentation and Release Notes before beginning to implement an RTR migration to RTR Version 3.

Note

1–2 Introduction

Installation

The installation for RTR Version 3 has changed signiﬁcantly from Version 2. In Version 2, the installation tool was VMSINSTAL; for Version 3, the installation tool is PCSI. Follow instructions in the Reliable Transaction Router Installation Guide to perform your RTR Version 3 installation.

Note

Reading Release Notes in RTR Version 3 is different from in RTR Version

2. See the Reliable Transaction Router Installation Guide for information on installing the product and reading release notes.

In a cluster environment, a planned transition from RTR Version 2 to Version 3 could be done as follows:

1. Install RTR Version 3 on a single standalone node.

2. Bring up RTR Version 3 on the standalone node with the RTR application.

3. Verify that the application and RTR Version 3 work as expected. Resolve any problems before proceeding.

4. Stop all transactions and RTR with the following commands:

$ RTR STOP RTR $ RTR DISCONNECT SERVER $ RTR DUMP JOURNAL

5. Examine the output of the DUMP JOURNAL command to verify that all transactions have been ﬂushed from the journal.

6. Bring down RTR Version 2 on the entire cluster.

7. Install RTR Version 3 on the cluster.

8. Start up RTR Version 3 on each node.

9. Verify that the application is running correctly on each node.

10. Verify that the application is running correctly on the cluster.

11. Verify that the application is running correctly throughout the RTR facility and network environment.

2.1 Cleaning Up the Old Version 2 Environment

Before bringing up the RTR Version 3 environment, you will need to shut down RTR Version 2 on client systems, let the RTR journal ﬁle clear, and then bring up RTR Version 3. This should be part of the process you use in your planned migration. See Section 2.6 for more information on checking journal ﬁles.

Installation 2–1

+ 29 hidden pages