Reliable_Transaction_Router_________________________ Release Notes January, 2001 Reliable Transaction Router (RTR) is fault tolerant transactional messaging middleware used to implement large, distributed applications using client/server technology. Reliable Transaction Router (RTR) Engineering is pleased to announce that RTR Version 4.0 is now available. Software Version: Reliable Transaction Router Version 4.0 Compaq Computer Corporation Houston, Texas ________________________________________________________________ © 2001 Compaq Computer Corporation Compaq, the Compaq logo, DEC, and VAX Registered in the United States Patent and Trademark Office. DECnet, OpenVMS, and Tru64 are trademarks of Compaq Information Technologies Group, L.P. Microsoft, MS-DOS, Visual C++, Windows, and Windows NT are trademarks of Microsoft Corporation. Intel is a trademark of Intel Corporation in the United States and/or other countries. UNIX is a registered trademark 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 commercial 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 produces are exclusively set forth in the documentation accompanying such products. Nothing herein should be construed as constituting a further or additional warranty. This document was prepared using VAX DOCUMENT, Version 2.1. _________________________________________________________________ Contents Preface................................................... iv 1 General Information Applicable to all Platforms..................................... 1 1.1 New Features.............................. 1 1.2 Corrections............................... 3 1.3 Known Problems with Workarounds........... 5 1.4 Restrictions.............................. 6 1.5 Documentation Changes..................... 7 1.6 Limitations............................... 7 2 OpenVMS Specific Information.................. 7 2.1 New Features.............................. 7 2.2 Corrections............................... 7 2.3 Known Problems with Workarounds........... 8 2.4 Restrictions.............................. 9 3 Windows Specific Information.................. 9 3.1 New Features.............................. 9 3.2 Corrections............................... 9 3.3 Known Problems with Workarounds........... 9 3.4 Restrictions.............................. 10 4 UNIX Specific Information..................... 10 4.1 New Features.............................. 10 4.2 Corrections............................... 10 4.3 Known Problems with Workarounds........... 10 4.4 Restrictions.............................. 10 5 Compaq Tru64 UNIX Specific Information........ 10 5.1 New Features.............................. 11 5.2 Corrections............................... 11 5.3 Known Problems with Workarounds........... 11 5.4 Restrictions.............................. 11 6 Sun Solaris Specific Information.............. 12 6.1 New Features.............................. 12 6.2 Corrections............................... 12 6.3 Known Problems with Workarounds........... 12 iii 6.4 Restrictions.............................. 13 7 Restrictions Described in Previous Release Notes......................................... 13 iv _________________________________________________________________ Preface Purpose of these Release Notes This document provides information for Reliable Transaction Router, Version 4.0. Intended Audience These Release Notes are intended for all users of Reliable Transaction Router. Please read all of this document before using the product. Related Documentation ___________________________________________________________ Document_________Content___________________________________ For all users: Reliable Provides an overview of RTR technology Transaction concepts and solutions. Router Getting Started RTR Commands Lists all RTR commands, their qualifiers Card and defaults. Reliable Describes new features, changes, and known Transaction restrictions for RTR. Router Release Notes For the system manager: iv ___________________________________________________________ Document_________Content___________________________________ Reliable Describes how to install RTR on all Transaction supported platforms. Router Installation Guide Reliable Describes how to configure, manage, and Transaction monitor RTR. Router System Manager's Manual Reliable Explains how to migrate from RTR Version 2 Transaction to RTR Version 3 (OpenVMS only). Router Migration Guide For the application programmer: Reliable Describes how to design application Transaction programs for use with RTR, illustrated Router with both the C and C++ interfaces. Application Design Guide Reliable Describes the object-oriented C++ Transaction interface that can be used to implement Router C++ RTR object-oriented applications. Foundation Classes Reliable Explains how to design and code RTR Transaction applications using the C programming Router C language; contains full descriptions of Application the basic RTR API calls. Programmer's Reference Manual_____________________________________________________ v Conventions The following conventions are used in this manual: ___________________________________________________________ Convention________Meaning__________________________________ boldface text Boldface text represents the introduction of a new term or the name of an argument, an attribute, or a reason. Boldface text is also used to show user input in online versions of the manual. italic text Italic text emphasizes important information, indicates variables, and indicates complete titles of manuals. Italic text also represents information that can vary in system messages (for example, Internal error number), command lines (for example, /PRODUCER=name), and command parameters in text. UPPERCASE TEXT Uppercase text indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege. user input This bold typeface is used in interactive examples to indicate typed user input. system output This typeface is used in interactive and __________________code_examples_to_indicate_system_output._ vi 1 General Information Applicable to all Platforms This chapter describes the new features and restrictions in Reliable Transaction Router, Version 4.0. 1.1 New Features This section describes the new features available in RTR Version 4.0 for all platforms. o C++ API RTR now provides an object-oriented C++ application programming interface. It includes C++ foundation classes which enable you to implement new RTR client and server applications, or to integrate specific classes into existing applications to add additional functionality. RTR concepts have been mapped to and implemented by the set of foundation classes for handling system management and the needs of business applications. o Web-based Interface With Version 4.0, the RTR system management interface is available as a Web-based interface as well as a command line interface. The web interface allows a point and click style of managing RTR from a browser. o Optimized Shadow Recovery RTR Version 4.0 implements an optimized shadow recovery protocol that reduces the time spent in shadow recovery after an extended shadow site outage. The period of time it takes for an RTR shadow configuration to get back into a state of full redundancy is much less as a result. By default, optimized shadow recovery is enabled, but can be controlled by the new command RTR SET NODE/RECOVERY, or by setting the environment variable RTR$CRM_BE_RECOVERY_PROTOCOL (or RTR_CRM_BE_RECOVERY_PROTOCOL) to either Version 3.2 or Version 4.0. 1 In earlier versions of RTR, shadow recovery consisted of sending a recovery query from the node with the recovering partition to the node with the partition in remember state. The query response would consist of the next remembered transaction found by RTR in that node's journal. Every recoverable transaction was requested in this manner, with network messages being sent between the recovering node and the remember node. In RTR Version 4.0, a recovery query is sent by the recovering node to the remember node and results in all recoverable transactions being sent back to the recovering node and written to that node's journal. The recoverable transactions are thus copied in blocks from the remember journal to the recovering node's journal, and deleted from the remember journal. The recovery of transactions then takes place from the recovering node's local journal. The period spent in shadow recovery under Version 4.0 is the time it takes to copy the remember transactions from the remember node to the recovering node, and is generally much less than the time it would take to recover the transactions one by one over the network from the remember node. 2 o New Monitors Four new flow control monitor pictures have been added to RTR: APPDELAY, DOWNSTREAM, FLOSTALLS, and UPSTREAM. These pictures allow monitoring of flow control induced traffic stalls by traffic type, facility, direction, and application process. A new monitor picture, FASTRECOVERY, is provided that displays the number of transactions recovered during optimized shadow recovery. There are three monitor pictures to use with the web browser interface: - ORTR contains a list of server/client transaction controllers. - STCCALLS contains the history of calls for a specified server transaction controller. - CTCALLS contains the history of calls for a specifed client transaction controller. 1.2 Corrections The following changes and corrections have been made in RTR Version 4.0 for all platforms. o SET TRANSACTION command Various problems with the SET TRANSACTION command and associated qualifiers have been corrected. o Monitor screens Improvements and corrections have been made to many monitor screens. o 14-1-1211 Transaction aborted with DLKTXRES status Previously when RTR detected that the environment had changed, for example, if the backend lost quorum or a transaction router was not available, it would abort the active transaction and present the server with status DLKTXRES (Deadlock detected, transaction rescheduled). This misleading status has been corrected. RTR now presents the server with PRTSTACHGTXRES (partition state change, transaction rescheduled) to indicate that the environment has been changed. o 14-3-143 /BRIEF qualifier added to SHOW FACILITY/LINKS 3 The /BRIEF qualifier has been added to the command SHOW FACILITY/LINKS. The /BRIEF qualifier shows the status of links on one line. The brief output format shows the facility name, followed by one or more lines showing the name of each link followed by the link's roles and their status in parentheses: Nodename (Backend coordinator, Router quorate, Frontend connected) o 14-3-206 Journal file full status is written to RTR log file If the journal file is full, causing a journal write operation to fail, the following error message is written to the RTR log file: %RTR-W-JOUFILFUL, RTR journal file full - use MODIFY JOURNAL to increase size A full journal file will also cause the transactions which cannot be written to the journal to be deleted. In this case, the following messages are written to the RTR log file for each transaction until the journal file problem is cleared: %RTR-E-JOUFULDEL, journal file full - transaction has been deleted %RTR-I-RQEQUALS, transaction client was RTRCSV %RTR-I-TIMEEQUALS, issued at Wed Dec 6 15:11:29 2000 %RTR-I-TXIDEQUALS, transaction ID aa020049,aa000400,200b,0,0, baa031f,33da0001 Once the journal file problem has been cleared, the following message is written to the RTR log file: %RTR-I-JOUNOTFUL, journal file no longer full - journal write succeeded o 14-5-224 New fields added to ROUTING monitor Fields have been added to the ROUTING monitor to display counts of undeliverable transaction messages and broadcasts. Counts in these categories indicate the absence of an appropriate key range server or broadcast destination respectively, and will likely indicate the absence of a required server application or perhaps an application configuration problem. o 14-8-321 Integer division affecting performance Integer division for new counters introduced in Version 3.2 was causing a small but noticeable drop in performance for large numbers of messages. Performance has been improved by eliminating integer division. 4 o 14-8-325, 14-8-353 Protection error on exception in cleanup handler A protection error could occur under obscure circumstances where the RTR cleanup handler was called twice. The cleanup handler no longer attempts to delete the shared memory segment a second time. 1.3 Known Problems with Workarounds The following known problems with workarounds apply to all platforms. o 14-1-498 Upgrade using RTR V3.1D journal If you are upgrading to RTR Version 4 from RTR Version 3.1D, and there are recoverable transactions in the Version 3.1D journal, then you must set the recovery protocol to Version 3.2 mode before adding any facilities on any node that has access to the Version 3.1D journal. This can be done by entering the RTR SET NODE/RECOVERY=V32 command after starting the ACP, or by defining the environment variable RTR_CRM_BE_RECOVERY_PROTOCOL (system-wide) to be 32. o 14-1-1427 Web page auto-reload may fail in Netscape browser RTR system management monitor web pages are designed to refresh themselves periodically by instructing the browser to initiate a page reload after an appropriate interval. This mechanism occasionally breaks down when using the Netscape browser. The problem has been seen on both Netscape Communicator Version 4.05 and Version 4.72 on Compaq Tru64 UNIX. The refresh can be restarted by manually reloading the frame. o 14-1-1134 Constructing URLs RTR generates URLs for use as links in management web pages and for redirecting HTTP requests to the correct command server port. These URLs are constructed using the fully qualified domain name of the host computer. It is important that the computer hosting the web browser be configured so that it is able to successfully resolve these names to IP address. Experience has shown that this is a frequent source of connection problems. If you are experiencing difficulty in connecting to the 5 RTR management web pages, check for compliance with this condition. 1.4 Restrictions The following restrictions apply to RTR Version 4.0 on all platforms. o Version 3.2 and Version 4.0 Rolling Upgrade Restrictions The following restrictions apply if you upgrade an RTR environment from RTR Version 3.2 to Version 4.0. The RTR recovery protocol consists of messages sent from one backend, via a router to the target backend. If either of the RTR backends is upgraded to RTR Version 4.0, then the router that will be used for recovery must also be running RTR Version 4.0. This generally means that any RTR router nodes should be upgraded to RTR Version 4.0 before any RTR backend nodes. There is no restriction in the order that RTR backends should be upgraded to V4. The order in which RTR nodes should be upgraded for a rolling upgrade from Version 3.2 to Version 4.0 is as follows 1. Frontend-only nodes can be upgraded at any time 2. Router-only and mixed frontend/router nodes 3. Mixed router/backend nodes 4. Backend-only nodes For more complex configurations, where a node may have combinations of facilities with different backend/router groupings, Compaq recommends that you set the recovery protocol to use the Version 3.2 algorithm. Once RTR has been upgraded on all nodes, the recovery protocol can be reset to its default value (Version 4.0), and RTR restarted at a convenient time on each node. This need not be a simultaneous restart on all nodes. RTR can be restarted on each node one by one after resetting the default recovery protocol, so that continuous application availability is maintained. o 14-1-1451 ODBC no longer supported Support for ODBC has been removed from RTR. 6 o Internet Explorer preferred over Netscape Navigator RTR works better with Internet Explorer than it does with Netscape Navigator. If you do use Netscape Navigator, Compaq recommends Version 6.0, because Netscape Navigator Version 4.0 has some minor problems with cascading style sheets. 1.5 Documentation Changes There are no corrections to documentation in these Release Notes. 1.6 Limitations Please see the Software Product Description. 2 OpenVMS Specific Information This chapter gives platform-specific information for the OpenVMS implementation of Reliable Transaction Router, Version 4.0. 2.1 New Features There are no new features in this release that are specific to this platform. 2.2 Corrections The following changes and corrections have been made in RTR Version 4.0 for the OpenVMS platform. o 14-1-1319 Management web pages not available if user BYTLM too small RTR management web pages can fail to load if the user process quota BYTLM was insufficient. The system has been modified to allow easier diagnosis of this condition. If encountered, normal operation can be achieved by raising the users BYTLM quota. o 14-3-176 RTR does not add the RTR$INFO and RTR$OPERATOR rights identifier During the installation of previous versions of RTR, the RTR$OPERATOR and RTR$INFO rights identifiers were not added to the UAF file. The RTR installation now adds the RTR$INFO and RTR$OPERATOR rights identifiers during the 7 installation process and removes them during the product removal process. ________________________ Note ________________________ If you are removing RTR from OpenVMS Version 6.2 systems and have not previously installed the RTR$OPERATOR and RTR$INFO rights identifiers, you will encounter an error message similar to the following: $PRODUCT REMOVE RTR ... %PCSI-I-PRCOUTPUT, output from subprocess follows... %CLI-W-NOQUAL, qualifiers not allowed - supply only verb and parameters Portion Done: 10% %PCSI-E-ERRDELIDENT, error deleting rights identifier RTR$OPERATOR -CLI-W-NOQUAL, qualifiers not allowed - supply only verb and parameters %PCSI-E-OPFAILED, operation failed Terminating is strongly recommended. Do you want to terminate? [YES] no Portion Done: 20%...30%...40%...50%...60%...70%...80%... 90%...100% The following product has been removed: DEC AXPVMS RTR V4.0-267 %PCSIUI-I-COMPWERR, operation completed after explicit continuation from errors Do not terminate the process. The error message is just a warning that a rights identifier has not been previously installed. To avoid getting this message you can edit the PCSI$DELETE_RIGHTS_IDENTIFIER.COM file in the SYS$UPDATE directory. Remove 'P2' from the line: $ MCR AUTHORIZE REMOVE/IDENTIFIER 'P1''P2' ______________________________________________________ 2.3 Known Problems with Workarounds There are no known problems with workarounds in this release that are specific to this platform. 8 2.4 Restrictions The following restrictions apply to RTR Version 4.0 on the OpenVMS platform. o 14-3-323 Creation of CSV process on OpenVMS relies on clean LOGIN.COM If running the login.com file produces an error, RTR may not run. 3 Windows Specific Information This chapter gives platform-specific information for Reliable Transaction Router, Version 4.0 for Windows platforms. 3.1 New Features There are no new features in this release that are specific to this platform. 3.2 Corrections There are no corrections in RTR Version 4.0 that are specific to this platform. 3.3 Known Problems with Workarounds The following problems with workarounds apply to RTR Version 4.0 on Windows platforms. o 14-1-997 RTR command and HTTP servers not available after logout RTR command and HTTP servers started during the course of an interactive Windows session do not survive when users log out of that session. This means that the machine is no longer accessible to browser GUI. This difficulty can be avoided by enabling rsh access to the Windows system. The HTTP server can then be started with a remote rtr command directed at the system concerned. rsh functionality for Windows is available from third parties. A version also ships with the Microsoft NT 4.0 Server Resource Kit. 9 3.4 Restrictions There are no restrictions in RTR Version 4.0 that are specific to this platform. 4 UNIX Specific Information This chapter gives platform-specific information for the implementation of Reliable Transaction Router, Version 4.0 on all UNIX platforms. 4.1 New Features There are no new features in this release that are specific to all UNIX platforms. 4.2 Corrections There are no changes or corrections in RTR Version 4.0 that are specific to all UNIX platforms. 4.3 Known Problems with Workarounds The following known problems with workarounds apply to RTR Version 4.0 on all UNIX platforms. o 14-1-1532 Lack of fully qualified domain name may break web interface. We have noticed that if the hostname is set to a short name instead of a fully qualified domain name (the host followed by the domain), web browsers on such systems may not be able to view the RTR web interface. This is being investigated. 4.4 Restrictions There are no restrictions in RTR Version 4.0 that are specific to all UNIX platforms. 5 Compaq Tru64 UNIX Specific Information This chapter gives platform-specific information for the Compaq Tru64 UNIX implementation of Reliable Transaction Router, Version 4.0. 10 5.1 New Features There are no new features in this release that are specific to this platform. 5.2 Corrections The following changes and corrections have been made for RTR Version 4.0 for the Compaq Tru64 UNIX platform. o 14-1-836, 14-1-1382 Crash on Tru64 UNIX Versions 5.0 and 5.0A with a sendmsg error The sendmsg binary incompatibility bug that causes a crash with EINVAL when uninitialized data is found in the newly extended part of iov_len is fixed in Compaq Tru64 UNIX 5.1 and the first patch kit for Version 5.0A. 5.3 Known Problems with Workarounds The following known problems with workarounds apply to RTR Version 4.0 on the Compaq Tru64 UNIX platform. o 14-1-1382 Compaq Tru64 UNIX Version 5.0a requires patch RTR requires that Patch Kit 1 be applied to Compaq Tru64 UNIX Version 5.0a in order to prevent network connection problems. o 14-1-1532 Lack of fully qualified domain name may break web interface The hostname of a node running a UNIX operating system is configured by modifying the file /etc/hostname. If this file does not contain the fully qualified domain name (the host followed by the domain), web browsers may not be able to view the RTR web interface. To prevent this problem, add the domain to the hostname in /etc/hostname. 5.4 Restrictions The following restrictions apply to RTR Version 4.0 on the Compaq Tru64 UNIX platform. o 14-9-79 Support of TruCluster Server 5 The /rtr directory is now a symbolic link to a target directory that is a context-dependent symbolic link (CDSL), so that it is a different physical directory on each cluster member. 11 Before installing RTR on a TruCluster Server, it is important that you first remove any existing /rtr directory, or /rtr symbolic link and its target directory, and the directory's contents, on all member nodes. If you don't need the previous journal it's also a good idea to remove /rtrjnl and contents; it will then be recreated as a symbolic link to a shared directory in /var which usually has more space than the / filesystem. Note that although the /rtrjnl directory can also be replaced by a symbolic link, the target should be an ordinary cluster-wide directory and not a member- specific CDSL, so that each member can access the journal files belonging to the other. Similarly, any other devices that you may specify when creating journals should normally also refer to cluster-wide shared directories. 6 Sun Solaris Specific Information This chapter gives platform-specific information for the Sun Solaris implementation of Reliable Transaction Router, Version 4.0. 6.1 New Features There are no new features in this release that are specific to this platform. 6.2 Corrections The following changes and corrections have been made in RTR Version 4.0 for the Sun Solaris platform. o 14-3-373 Creating a journal on Sun Veritas It is no longer necessary to define RTR_SCAN_ALL=1 to use journal files on a device with filesystem type vxfs. 6.3 Known Problems with Workarounds There are no known problems with workarounds in this release that are specific to this platform. 12 6.4 Restrictions There are no restrictions in RTR Version 4.0 that are specific to this platform. 7 Restrictions Described in Previous Release Notes The following restrictions were described in previous release notes and are still applicable to RTR. o 14-1-39 Declaring exit handlers in RTR applications If an exit handler contains calls to RTR, then the exit handler must be declared after the first call to RTR. Using the RTR Version 2 or Version 3 API, if the exit handler is declared before the first call to RTR, then any call to RTR made within the exit handler will return an error. Under the Version 3 API, the error status returned is RTR_STS_INVCHANNEL. Under the Version 2 API, the error status returned is RTR$_INVALCH. o 14-1-103 Using rtr_set_wakeup() in a threaded program After calling rtr_set_wakeup() in a threaded program, you should also call rtr_set_wakeup(NULL) wherever your program can exit. This will prevent any wakeups in other threads while the main thread is already running the RTR exit handler, which could lead to a server core dump when trying to stop the server. o 14-1-263 Non-English character sets are not supported for identifiers The supported character set for RTR identifiers such as facility names is ASCII, with lowercase and uppercase letters equivalent. Eight bit characters are not supported because the name might not interoperate with RTR processes using a different locale or running another RTR version. o 14-1-455 Last line of batch procedure sometimes ignored On Windows platforms the last line of a batch procedure or command file must explicitly end with added by pressing the Enter/Return key when creating the procedure. Without the explicit , RTR ignores the line. The workaround is to add a comment to the end 13 of the file or to explicitly add to the end of the last line of the batch procedure. o 14-1-681, 14-3-278 ACP crash in RDM subsystem It has been observed that with a large number of concurrently active transactions, where each transaction sends back a large number of very large replies, it is possible to exhaust the virtual memory requirements of RTR in order to store the replies for possible recovery after a link glitch. This would cause RTR to crash on a backend node. The workaround is to reduce the number of concurrent server channels, so as to limit the number of concurrently active transactions on each backend. Another possibility would be to limit the number of replies per transaction. In our tests we were able to exceed the RTR limits using 10 servers, each sending back 200 replies of 64KB each. o 14-1-769 System time must not be set backwards Correct operation of RTR is not guaranteed if the time is not monotonic. When performing Year 2000 testing, stop all RTR processes and remove any journalled transactions before setting the clock back. When configuring the Network Time Protocol daemon ntp, do not select, or accept by default, any options which may result in the system clock being set backwards. While RTR is running as a service on NT, do not allow the time to be set backwards by ntp or in login scripts. On OpenVMS systems, do not change to a different time zone, or to or from Summer Time or Daylight Savings Time, while using current versions of RTR which are built on OpenVMS V6 to run on both OpenVMS V6 and V7. On most UNIX systems it is in any case not recommended that you change the date and time when running in multi-user mode. Adjustments are normally made by speeding up or slowing down the clock. 14