Reliable Transaction Router Migration Guide 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.
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.
Contents Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii 1 Introduction 1.1 1.2 1.3 Why Migrate? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Goals and Nongoals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Reading Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5 System Management 5.1 5.2 5.3 5.3.1 5.3.2 5.4 5.5 5.5.1 5.5.2 5.5.3 5.5.4 5.5.5 5.6 5.7 5.8 5.9 5.10 5.11 5.12 OpenVMS Quotas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Startup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating Facilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Naming Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Modifying Facility Configurations . . . . . . . . . . . . . . . .
Index Tables 2–1 2–2 3–1 5–1 5–2 5–3 5–4 5–5 5–6 6–1 6–2 OpenVMS Limits . . . . . . . . . . . . . . . . . . . . . . OpenVMS Disk Requirements . . . . . . . . . . . . RTR Executables . . . . . . . . . . . . . . . . . . . . . . Interoperability Between Nodes . . . . . . . . . . . Obsolete RTR Version 2 Monitor Pictures . . . New RTR Version 3 Monitor Pictures . . . . . . Changed SHOW COMMANDS . . . . . . . . . . . . Obsolete OpenVMS RTR Utility Commands . New OpenVMS RTR Utility Commands . . . . .
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.
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.
Convention Meaning 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. ... . . . 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.
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.
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 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.
Installation 2.2 Preserving the Old Environment 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.
Installation 2.5 Process Quotas Table 2–1 OpenVMS Limits Limit Name OpenVMS Name Value for ACP AST queue limit ASTlm 2000 or more Byte count limit Bytlm 32K + (32K * appn †) 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 Value for Application Not less than 100K †In the table, appn is the number of application processes.
Installation 2.6 Journal Issues 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.
Installation 2.8 Memory and Disk Requirements Table 2–2 OpenVMS Disk Requirements Requirement RTR Version 2 RTR Version 3 Disk space (installation) 40,000 blocks (20MB) 50,000 blocks (25MB) Disk space (permanent) 24,000 blocks (12MB) 36,000 blocks (18MB) 2.9 Rollback to RTR Version 2 To restore the RTR Version 2 environment if RTR Version 3 does not work with your applications as expected, use the following procedure: 1.
3 Architectural Changes RTR Version 3 introduces certain process and other architectural changes. The following sections highlight these changes. 3.1 RTR Daemon Process In RTR Version 3, a new RTR daemon process (called RTRD) is used by the RTRACP process to build TCP/IP connections for internode links. The RTR daemon process is present only on systems with IP networking installed and with IP enabled as an RTR transport (see Chapter 4, Network Issues, for information on setting your network transport). 3.
Architectural Changes 3.3 The Shared Library (LIBRTR.EXE) Table 3–1 (Cont.) RTR Executables RTR Version 2 RTR Version 3 RTRRTL No longer apply. 3.4 The ACP Process The RTR Application Control Process (ACP) handles application control, and has the process name RTRACP. This is unchanged from RTR Version 2. 3.5 Interprocess Communication In RTR Version 2, global sections (cache) were used for interprocess communication. In RTR Version 3, interprocess communication is handled with mailboxes.
Architectural Changes 3.8 Quorum Issues 3.8 Quorum Issues Network partitioning in RTR Version 3 is based on a router and backend count, whereas in RTR Version 2 it was based on quorum. However, quorum is still used in RTR Version 3; state names and some quorum-related displays have changed. Additionally, the quorum-related condition of a node in a minority network partition is handled more gracefully in RTR Version 3.
4 Network Issues With RTR Version 3, two network transports are available: • DECnet (default on OpenVMS) • TCP/IP At least one transport is required. If a destination supports both transports, RTR Version 3 can use either. Any node can run either protocol, but the appropriate transport software must be running on that node. For example, for a node to use the DECnet protocol, the node must be running DECnet software.
Network Issues 4.3 Specifying a Preferred Transport 4.3 Specifying a Preferred Transport During installation, the system manager can specify either transport, using logical names RTR_DNA_FIRST or RTR_TCP_FIRST. For example, in the RTR$STARTUP.COM file (found in SYS$STARTUP), the following line specifies DECnet as the default transport: $ DEFINE/SYSTEM RTR_PREF_PROT RTR_DNA_FIRST To set the default transport to TCP/IP, remove (comment out) this definition from RTR$STARTUP.COM and restart RTR.
5 System Management A number of changes that affect system management have been introduced with RTR Version 3. The following sections describe these changes. 5.1 OpenVMS Quotas RTR Version 2 used OpenVMS quota values specified on the RTR START command or calculated defaults. Because RTR Version 3 uses dynamic allocation (with the exception of the number of partitions that is statically defined), RTR does not calculate the required quotas, but depends on the system manager to configure quotas adequately.
System Management 5.4 Interoperability 5.4 Interoperability All supported operating systems can interoperate together in the RTR environment, as described in Table 5–1. Table 5–1 Interoperability Between Nodes RTR Version 3 nodes interoperate with... Description Other RTR Version 2 nodes In RTR Version 3, RTR uses data marshalling (examination of byte format of messages) and can handle data of more than one byte format, making the appropriate translation as required.
System Management 5.5 Monitoring Table 5–3 New RTR Version 3 Monitor Pictures Picture Description accfail Shows most recent links on which a connection attempt was declined. acp2app Shows RTRACP-to-application message counts. app2acp Shows application-to-RTRACP message counts. broadcast Shows information about RTR user events by process. connect Renamed to netstat. connects Shows connection status summary. dtx Shows distributed transaction calls status.
System Management 5.5 Monitoring 5.5.5 History Screens New monitor screens that show partition state or network connection history include MONITOR accfail and MONITOR rscbe. 5.6 Remote Command Support With the new support for TCP/IP, you can execute commands on remote systems using the rsh utility. To use this feature, check your operating system documentation for how to ensure access to a TCP/IP environment, and grant such privileges to users. You may, for example, need to make an entry in the .
System Management 5.11 Interpreting Output from SHOW Commands Table 5–4 (Cont.) Changed SHOW COMMANDS Command Description SHOW TRANSACTION With the SHOW TRANSACTION command, you can now specify display for a frontend, backend, or router. SHOW FACILITY/LINK The SHOW FACILITY/LINK command provides new information on states. SHOW PARTITION /FULL The SHOW PARTITION/FULL command provides new information on states. 5.
System Management 5.12 Comparing RTR Version 2 and Version 3 Utility Commands Table 5–6 (Cont.) New OpenVMS RTR Utility Commands Command Name Description QUIT Exits RTR. REGISTER RM1 Registers resource managers with the current transaction manager. SET PARTITION Sets partition properties. SET TRANSACTION Changes the state of a transaction. SHOW CLIENT Supersedes SHOW REQUESTOR.
6 Running Version 2 Applications In this chapter the term OpenVMS API refers to the Reliable Transaction Router for OpenVMS Version 2. The term Portable API refers to the API used in Reliable Transaction Router for OpenVMS Version 3.
Running Version 2 Applications 6.
Running Version 2 Applications 6.2 Recompiling and Relinking 6.2.1 RTR Version 2 Applications Running on RTR Version 3 • Linking Version 2 applications Existing RTR Version 2 applications will run if they have been linked against RTRSHR. (RTRSHR has been superseded by LIBRTR.EXE. Existing RTR Version 2 application executables will run without relinking since RTR$STARTUP.COM defines RTRSHR as a logical name that points to LIBRTR.EXE.) However, as RTRSHR.
Running Version 2 Applications 6.3 Running Applications Installed with Privileges 6.3 Running Applications Installed with Privileges With RTR Version 2, RTR calls execute in kernel mode; with RTR Version 3, RTR runs in application process mode, normally user mode. 6.3.1 Running Clients That Share Channels With RTR Version 2, clients that start up and declare channels could use the flag INHNOSRVWT (inhibit-no server-wait) to proceed without waiting.
Running Version 2 Applications 6.6 Threaded Applications 6.6 Threaded Applications With RTR Version 3, applications that rely on threading may not work exactly the same way they worked with RTR Version 2 on OpenVMS. Applications that use kernel threads with RTR Version 2 will not work with RTR Version 3. RTR Version 2 was thread-reentrant, but the RTR Version 2 layer in RTR Version 3 on OpenVMS and Windoes should not be called from more than one thread.
7 Performance Tips With RTR Version 3, there are several considerations for improving performance. These are described in the following sections. 7.1 Process Quotas OpenVMS process quotas should be increased to accomodate the use of mailboxes for processes. Check the RTR Installation Guide for the specific formula to use. 7.2 Journal Sizing With RTR, the larger the journal, the more time it takes to read it. This can affect failover in some circumstances.
Performance Tips 7.6 Simultaneous Multiprocessing 7.6 Simultaneous Multiprocessing With RTR Version 2, threaded applications could use Symmetric Multiprocessing (SMP) effectively. In RTR Version 3, SMP will not provide the performance advantages of RTR Version 2. The single control process of RTRACP in RTR Version 3 does not take advantage of an SMP configuration.
8 Problem Diagnosis and Reporting RTR Version 3 provides a new error log and logical names to assist tracing errors including: • the RTR operator log file, capturing events that occur, and useful for diagnosis of problems • the RTR_ERROR.LOG file • the dump file (.DMP), a binary crash dump that, if needed, must be sent to your support service 8.1 RTR Operator Log Always initiate an operator log in your RTR$STARTUP.COM procedure. Place it in a disk partition separate from the RTR journal or database.
Problem Diagnosis and Reporting 8.4 Producing and Directing a Trace set trace/subsystem=(API, CIF, CRM) 4. set mode/nounsupported Starts the trace on subsystems API, CIF and CRM. . Trace continues. or Sets mode to supported. . Trace continues. set mode/unsupp 6. set trace 7. set mode/nounsupp Sets mode to unsupported. 5. Stops the trace. Sets mode back to supported. Running a trace can affect performance, so be sure to turn it off again when done (see step 6). 8.
Index A ABORT command, 6–3 ANALYZE/SYSTEM, 8–2 API OpenVMS, 6–1 Portable, 6–1 API (defined), vii B Back ends, 2–2 C DECdtm, 6–5 DECnet protocol, 4–1 DELETE PARTITION command, 5–6 $DEQ_TX, 6–5 DISCONNECT SERVER command, 2–1 DISPLAY STRING command, 5–6 DSDEF, 6–4 DTC support, 6–1 DUMP JOURNAL command, 2–1, 2–4, 5–6 E Event status, 6–3 EXECUTE command, 5–6 Cache, 3–2 Call RTR_, 5–6 Call stack, 8–1 Channel number, 6–3 CLI, 5–4 Command ABORT, 6–3 CREATE PARTITION, 5–6 DELETE PARTITION, 5–6 DISPLAY
M MONITOR, 7–1 Monitor pictures, 5–2 MONITOR QUORUM, 3–3 Multihoming, 4–1 Multiple network transports, 4–1 N Name server, 4–1 Nested transactions, 1–2 Network partition, 3–3 O OpenVMS API, 6–1 P Partition network, 3–3 Partition states server-process, 3–3 PCSI (defined), 1–1 Pictures monitor, 5–2 Portable API, 6–1 Process counters, 3–2 Process states, 3–3 Protocol selection, 4–2 Q QUIT command, 5–6 Quorum, 3–3 Quota OpenVMS, 5–1 R REGISTER RM command, 5–6 .
