Order Number: AA--R88LC--TE
This guide explains how to migrate from Reliable Transaction Router (RTR) Version 2 to RTR Version 3 or RTR Version 4 on OpenVMS systems, and provides information on new and obsolete features.
Revision/Update Information: This guide supersedes the Reliable Transaction Router Migration Guide Version 3.2.
Software Version: Reliable Transaction Router Version 4.0
Compaq Computer Corporation
Houston, Texas
© 2001 Compaq Computer Corporation
Compaq, the Compaq logo, AlphaServer, TruCluster, VAX, and VMS Registered in U. S. Patent and Trademark Office.
DECnet, OpenVMS, and PATHWORKS are trademarks of Compaq Information Technologies Group, L.P.
Microsoft, Microsoft Access, Microsoft SQL Server, Internet Explorer,
and Windows NT are trademarks of Microsoft Corporation.
Intel is a registered trademark of Intel Corporation.
UNIX and The Open Group are trademarks of The Open Group.
All other product names mentioned herein may be trademarks or registered trademarks of their respective companies.
Confidential computer software. Valid license from Compaq or authorized sublicensor required for possession, use, or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commerical license.
Compaq shall not be liable for technical or editorial errors or omissions contained herein.
The information in this publication is subject to change without notice and is provided "AS IS" WITHOUT WARRANTY OF ANY KIND. THE ENTIRE RISK ARISING OUT OF THE USE OF THIS INFORMATION REMAINS WITH RECIPIENT. IN NO EVENT SHALL COMPAQ BE LIABLE FOR ANY DIRECT, CONSEQUENTIAL, INCIDENTAL, SPECIAL, PUNITIVE OR OTHER DAMAGES WHATSOEVER (INCLUDING WITHOUT LIMITATION, DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION OR LOSS OF BUSINESS INFORMATION), EVEN IF COMPAQ HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. THE FOREGOING SHALL APPLY REGARDLESS OF THE NEGLIGENCE OR OTHER FAULT OF EITHER PARTY AND REGARDLESS OF WHETHER SUCH LIABILITY SOUNDS IN CONTRACT, NEGLIGENCE, TORT OR ANY OTHER THEORY OF LEGAL LIABILITY, AND NOTWITHSTANDING ANY FAILURE OF ESSENTIAL PURPOSE OF ANY LIMITED REMEDY.
The limited warranties for Compaq products are exclusively set forth in the documentation accompanying such products. Nothing herein should be construed as constituting a further or additional warranty.
| Contents | Index |
This guide explains how to migrate a Reliable Transaction Router (RTR) environment and RTR applications from RTR Version 2 to RTR Version 3 or RTR Version 4. 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 and application programmers.
The system manager should be familiar with the following aspects of the OpenVMS operating system:
The system manager should also be familiar with:
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. |
The following documents provide more information about topics discussed in this guide and about Reliable Transaction Router:
| 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 C Application Programmer's Reference Manual | Describes how to code RTR applications using the RTR C programming interface, 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 Getting Started | Describes RTR concepts and defines RTR terminology. |
| Reliable Transaction Router C++ Foundation Classes | Describes the object-oriented C++ programming interface that can be used to implement RTR object-oriented applications. |
| 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. |
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.
The following conventions are used in this document.
| Convention | Meaning |
|---|---|
| Italic |
Indicates parameters whose values you must provide. For example, if the
procedure asks you to type
filename, you must type the actual name of a file.
Italics also indicate 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. |
|
.
. . |
A vertical ellipsis in an example indicates that not all the data are shown. |
The reading path to follow when using the Reliable Transaction Router information set is shown in Figure 1.
Figure 1 Reading Path
This document is intended to assist RTR Version 2 users to migrate to
RTR Version 3 or RTR Version 4.
1.1 Why Migrate?
Migration to RTR Version 3 or 4 takes advantage of the new features and improved capabilities of RTR Versions 3 or 4. These include:
Additionally, other considerations that may help you decide to migrate are:
Other changes introduced with RTR Version 3:
There is no upgrade path for Windows 3.1 clients; applications must be rewritten using the RTR Version 3 C API or the RTR Version 4 C++ API. |
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 or Version 4.
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 or Version 4 documentation and Release Notes before beginning to implement an RTR migration.
The installation for RTR Version 3 and Version 4 has changed significantly from Version 2. In Version 2, the installation tool was VMSINSTAL; for Versions 3 and 4, the installation tool is PCSI. Follow instructions in the Reliable Transaction Router Installation Guide to perform your RTR Version 3 or 4 installation.
Reading Release Notes in RTR Versions 3 and 4 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 or 4 could be done as follows:
$ RTR STOP RTR $ RTR DISCONNECT SERVER $ RTR DUMP JOURNAL |
Before bringing up the RTR Version 3 or 4 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 or 4. This should be part of the
process you use in your planned migration. See Section 2.7 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 or 4 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 or 4 routers and back-end systems; all routers and back-end systems in a facility must be either RTR Version 2 or RTR Version 3 or RTR Version 4. Front-end systems can be either Version 2, Version 3, or Version 4.
Command line entries using $ENQ_TX may have spaces dropped. To retain spaces, use quadruple quotes, for example: RTR $ENQ_TX """"Spaces remain!"""" . |
No, RTR Version 2 and Version 3 cannot coexist on the same node.
2.4 Can Both RTR Version 2 and Version 4 Coexist on the Same Node?
No, RTR mixed versions cannot exist on the same node.
2.5 Can Mixed Version Applications Coexist on the Same Node?
Under most circumstances, RTR Version 2 applications will run in the RTR Version 3 or Version 4 environment unchanged, and RTR Version 2 and Version 3 or Version 4 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 or Version 4.
2.6 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.
Values in Table 2-1 supersede values previously documented. |
| 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 |
For more information on these limits, see the OpenVMS System
Manager's Manual: Essentials.
2.7 Journal Issues
With RTR Version 3 and Version 4 software, the format and content of the transaction journal have changed. In general, if you upgrade or migrate to RTR Version 3 or 4 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 or Version 4 can cause problems to that application. To correct such a problem, change the application.
A journal file resides on each RTR backend system. This is not a change from RTR Version 2. Before you shut down RTR Version 2 to bring up RTR Version 3 or 4, you must deal with your journal file, using the following procedure:
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 or 4.
There is no need to save the old journal file once all transactions
have cleared.
2.7.2 Journal Compatibility
RTR Version 2 journal files are incompatible with RTR Version 3 or 4
journal files. No tools exist to migrate RTR Version 2 journal files to
the RTR Version 3 or 4 journal file.
2.7.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 and 4.
However, the location and naming conventions for the journal have changed for RTR Version 3 and 4.
In RTR Version 2, journal files reside on each backend node in:
dev:[RTRJNL]filename
In RTR Versions 3 and 4, journal files reside on each backend node in:
dev:[RTRJNL.SYSTEM]nodename.Jnn
Group names are used for naming RTR journal files.
| Next | Contents | Index |