Reliable Transaction Router

Reliable Transaction Router

Migration Guide

Order Number: AA--R88LB--TE


June 1999

This guide explains how to migrate from Reliable Transaction Routertm (RTR) Version 2 to RTR Version 3 on OpenVMStm 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.

Copyright ©1999 Digital Equipment Corporation

.

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

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

The following are trademarks of Compaq Computer Corporation: AlphaGeneration, AlphaServer, AlphaStation, 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.

Contents Index


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.

Audience

This guide is written for RTR system managers.

The system manager should be familiar with the following aspects of the OpenVMS operating system:

The system manager should also be familiar with:

Organization of This Guide

The following list can help you find information in this guide:
Chapter 1 Provides an introduction to the migration guide and summarizes new and changed features.
Chapter 2 Describes changes to the installation procedure.
Chapter 3 Describes how the RTR architecture has changed.
Chapter 4 Describes changes to the network configuration 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.

Related Documents

The following documents provide more information about topics discussed in this guide:
Document Title Description
Reliable Transaction Router Installation Guide Describes how to install Reliable Transaction Router.
Reliable Transaction Router System Manager's Manual Describes how to configure, manage, and monitor Reliable Transaction Router
Reliable Transaction Router Application Programmer's Reference Manual Describes how to code RTR applications, and contains full descriptions of RTR API calls.
Reliable Transaction Router Application Design Guide Describes how to design applications that use RTR.
Reliable Transaction Router Release Notes 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 Describes use of the DEC C run-time library.

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 device button.
Italic Indicates parameters whose values you must provide. For example, if the procedure asks you to type file name, you must type the actual name of a file.

Italic also indicates variables and the titles of referenced documents.

monospace Indicates the actual commands, words, or characters that you type in a dialog box, at a command prompt, or system output.
Note: Provides information of special importance.
/ A forward slash in command descriptions indicates that a command qualifier follows.
boldface In online files, boldface indicates information that you enter.
... A horizontal ellipsis following an entry in a command line indicates that the entry or a similar entry can be repeated any number of times. An ellipsis following a file 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.


Chapter 1
Introduction

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:

Additionally, other considerations are:

Other changes introduced with RTR Version 3:

Note

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.


Chapter 2
Installation

The installation for RTR Version 3 has changed significantly 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 flushed 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 file 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 files.

2.2 Preserving the Old Environment

Applications that run in the RTR Version 2 environment on OpenVMS systems will run in the RTR Version 3 environment on OpenVMS systems. However, as part of your testing and verification of the new environment, you should check that an RTR Version 2 application runs as expected after the upgrade.

You cannot mix RTR Version 2 and Version 3 routers and back-end systems; all routers and back-end systems in a facility must be either RTR Version 2 or RTR Version 3. Front-end systems can be either Version 2 or Version 3.

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

No, RTR Version 2 and Version 3 cannot coexist on the same node.

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

Under most circumstances, RTR Version 2 applications will run in the RTR Version 3 environment unchanged, and RTR Version 2 and Version 3 applications can coexist on the same node, and exchange messages.

Because the RTR Version 2 API is frozen, any new features requiring a change in the API cannot be exploited from within an RTR Version 2 application. This may be a reason to consider migration. Additionally, if portability is an issue, migrate to RTR Version 3.

2.5 Process Quotas

RTRACP buffers all active transactions. All message information that was previously kept in the shared memory RTR cache is now kept within RTRACP process memory.

Because of the use of mailboxes to handle message traffic, mailbox quotas should generally be set larger than in Version 2. These quotas or limits include:

Table 2-1 provides estimates of values for these limits.

Note

Values in Table 2-1 supersede values previously documented.

Table 2-1 OpenVMS Limits
Limit Name OpenVMS Name Value for ACP Value for Application
AST queue limit ASTlm 2000 or more  
Byte count limit Bytlm 32K + (32K * appn +) Not less than 100K
Buffered I/O count limit BIOlm Not less than 3 * appn  
Direct I/O count limit DIOlm 2000 or more  
Paging file limit Pgflquo Not less than 200K  
Timer Queue Entry limit TQElm 2000 or more  


+In the table, appn is the number of application processes.

For more information on these limits, see the OpenVMS System Manager's Manual: Essentials.

2.6 Journal Issues

With RTR Version 3 software, the format and content of the transaction journal have changed. In general, if you upgrade or migrate to RTR Version 3 but continue to use the RTR Version 2 API and DECnet, you can use your existing application without change, However, if an RTR Version 2 application stored and used a transaction ID, the changed transaction ID format of RTR Version 3 can cause problems to that application. To correct such a problem, change the application.

A journal file resides on each RTR back-end system. This is not a change from RTR Version 2. Before you shut down RTR Version 2 to bring up RTR Version 3, you must deal with your journal file, using the following procedure:

  1. In the Version 2 environment, stop all clients so that no new transactions can be initiated.
  2. Monitor the Version 2 journal file to check the status of all current transactions.
  3. When all transactions are complete and the journal file is empty, you can delete the journal file at this point, and shut down the entire Version 2 environment as follows:
    1. Shut down RTR applications.
    2. Shut down RTR Version 2.
    3. Install RTR Version 3.
    4. Bring up RTR Version 3 including performing the following tasks:
      1. Start RTR Version 3.
      2. Create the new journal file.
      3. Create the new operating environment, for example, define facilities.
      4. Start the application.

2.6.1 Removing the Old Journal

To verify that the new journal is running correctly, use the DUMP JOURNAL command to verify that transactions are processing as expected, and to be sure that all transactions have completed before bringing down RTR to install RTR Version 3.

There is no need to save the old journal file once all transactions have cleared.

2.6.2 Journal Compatibility

RTR Version 2 journal files are incompatible with RTR Version 3 journal files. No tools exist to migrate RTR Version 2 journal files to the RTR Version 3 journal file.

2.6.3 Location and Naming Conventions

With RTR, the journal records transactions for use during recovery when required. You specify the disk location for the journal file with the CREATE JOURNAL command. This is unchanged for RTR Version 3.

However, the location and naming conventions for the journal have changed for RTR Version 3.

In RTR Version 2, journal files reside on each back-end node in:

In RTR Version 3, journal files reside on each back-end node in:

Group names are used for naming RTR journal files.

2.7 Rights and Privileges

You need the same rights and privileges to manage the RTR environment and RTR applications in Version 3 as in Version 2.

To manage RTR, you must have one of the following OpenVMS system rights or privileges: OPER, SETPRV, RTR$OPERATOR. To use the RTR API rtr_request_info, you must have the following right: RTR$INFO.

To run an application, you must have the following OpenVMS privilege: TMPMBX.


Next Contents Index