hp_Reliable_Transaction_Router______________________ Release Notes August 2003 HP Reliable Transaction Router (RTR) is fault tolerant transactional messaging middleware used to implement large, distributed applications using client/server technology. These notes describe the new features, corrections, restrictions, and known problems with workarounds for RTR Version 4.2 ECO1. Software Version: Reliable Transaction Router Version 4.2 ECO1 Hewlett-Packard Company Palo Alto, California ii ________________________________________________________________ © 2003 Hewlett-Packard Development Company, L.P. Microsoft, MS-DOS, Windows, and Windows NT are US registered trademarks of Microsoft Corporation. Intel is a US registered trademark of Intel Corporation. UNIX is a registered trademark of The Open Group. Confidential computer software. Valid license from HP and/or its subsidiaries 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 commercial license. Neither HP nor any of its subsidiaries shall be liable for technical or editorial errors or omissions contained herein. The information in this document is provided "as is" without warranty of any kind and is subject to change without notice. The warranties for HP products are set forth in the express limited warranty statements accompanying such products. Nothing herein should be construed as constituting an additional warranty. This document was prepared using DECdocument, Version 3.3- 1B. _________________________________________________________________ Contents Preface................................................... iv 1 Information Applicable to all Platforms....... 1 1.1 New Features.............................. 1 1.1.1 Functionality........................... 1 1.1.2 Environment/Operational Improvements.... 5 1.2 Upgrades.................................. 7 1.3 Restrictions.............................. 8 1.4 Clarification............................. 9 1.5 Known Problems with Workarounds........... 9 2 OpenVMS-Specific Information.................. 9 2.1 Restrictions.............................. 9 2.2 Known Problems with Workarounds........... 10 3 Tru64-Specific Information.................... 10 3.1 Restrictions.............................. 10 3.2 Known Problems with Workarounds........... 10 4 Windows-Specific Information.................. 10 4.1 New Features.............................. 10 4.2 Restrictions.............................. 11 4.3 Known Problems with Workarounds........... 11 5 Sun Solaris-Specific Information.............. 12 5.1 Restrictions.............................. 12 5.2 Known Problems with Workarounds........... 12 Examples 1 Monitor Summary........................... 4 iii Tables 1 RTR Documents............................. iv iv _________________________________________________________________ Preface Purpose of these Release Notes This document provides information for Reliable Transaction Router Version 4.2 ECO1. 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 Table 1 describes RTR documents and groups them by audience. Table_1_RTR_Documents______________________________________ Document______________Content______________________________ For all users: Reliable Transaction Describes new features, changes, and Router Release known restrictions for RTR. Notes[1] Reliable Transaction Provides an overview of RTR Router Getting technology and solutions, and Started includes the glossary that defines all RTR terms. [1]Distributed_on_software_kit.____________________________ (continued on next page) iv Table_1_(Cont.)_RTR_Documents______________________________ Document______________Content______________________________ Reliable Transaction A pocket-sized handbook that lists Router Commands all RTR commands, their qualifiers and defaults. Reliable Transaction Describes product features. Router Software Product Description For the system manager: Reliable Transaction Describes how to install RTR on all Router Installation supported platforms. Guide Reliable Transaction Describes how to configure, manage, Router System and monitor RTR. Manager's Manual Reliable Transaction Explains how to migrate from RTR Router Migration Version 2 to RTR Version 3 or 4 Guide[2] (OpenVMS only). For the application programmer: Reliable Transaction Describes how to design application Router Application programs for use with RTR, with both Design Guide C++ and C interfaces. Reliable Transaction Describes the object-oriented Router C++ C++ interface that can be used Foundation Classes to implement RTR object-oriented applications. Reliable Transaction Explains how to design and code RTR Router C Application applications using the C programming Programmer's language and the RTR C API. Contains Reference Manual full descriptions of the basic RTR API calls. [2]Softcopy_only.__________________________________________ ___________________________________________________________ You can find additional information about RTR, including the Software Product Descriptions, on the RTR website found v through http://www.hp.com links to middleware products or at http:://www.hp.com/go/rtr. Conventions The following conventions are used in this manual: ___________________________________________________________ Convention________Meaning__________________________________ 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 Information Applicable to all Platforms This section describes the new features, changes, and restrictions in Reliable Transaction Router, Version 4.2 ECO1. 1.1 New Features This section describes the new features available in this release for all platforms. 1.1.1 Functionality o 14-1-2062 Shadow recovery performance improved With fast shadow recovery, a node becomes primary active or secondary active as soon as it has copied all the transactions from the remembering node. Whether it becomes primary or secondary depends on its priority (established with the SET PARTITION/PRIORITY command). However, a large backlog of unprocessed transactions could cause a dual-site outage if a node immediately becomes primary active and then processes the backlog. To avoid such an outage, a change has been implemented in shadow recovery behavior. With this change, a node processing a fast-recovery backlog will stay secondary active until it has caught up with the primary. Only when it has caught up will it change to primary active state. o 14-1-2245, 14-1-2250 Many more commands logged Previously, only a small number of RTR commands were logged. Now, any commands that affect the RTR configuration are logged to give an audit trail. For more information, see the Reliable Transaction Router System Manager's Manual. o 14-1-2330 Linux evaluation kit available. An RTR Linux evaluation kit is available for download from the RTR website http://www.hp.com/go/rtr. o 14-1-2331 Additional documentation formats available on CDROM 1 With the current version of RTR, documents on the CDROM include .pdf files that can be read with Adobe Acrobat and .htm files that can be read with a web browser such as Internet Explorer. o 14-3-182 Function prototypes added to RTR_V2.H The RTR V2 interface has not changed, but the file has been updated to include function prototypes. o 14-3-372 No need to use partition or facility name with SET TRANSACTION with transaction ID RTR V4 no longer requires the user to specify either the facility or partition name when using the SET TRANSACTION command if the transaction ID is supplied. o 14-3-424, 14-3-425 SHOW FACILITY, SHOW LINK exit status When processing the SHOW FACILITY and SHOW LINK commands, the RTR utility now sets its exit status. o 14-3-439 New variation of the rtr_broadcast_event( ) API function added. The existing API routine, rtr_broadcast_event( ), has been complemented with a new "time out" version of the routine, rtr_ext_broadcast_event( ). This extended version allows the programmer to specify a timeout period in which to perform the operation. If RTR is unable to service the broadcast operation within the timeout period, an RTR_STS_TIMOUT status is returned. Refer to the C Application Programmer's Reference Manual for more details on the new routine. o 14-3-442 P1 parameter added to RTR$STARTUP and RTR$SHUTDOWN for OpenVMS To ensure that rtr_pref_prot is correctly defined, the P1 parameter has been added to RTR$STARTUP and RTR$SHUTDOWN to define the preferred network protocol. For additional information, see the RTR Installation Guide. [ECO1] Changes include: o 14-1-2397 New monitor picture: summary.mon 2 A new monitor picture displays information about the channel, transaction, and system environment, including: o For server channels: - Processes (number of processes hosting server channnels) - Active (number of primary active server channels) - Secondary active (number of secondary active server channels) - Standby (number of standby server channels) - Other (number of server channels in states not counted above) - All server channels (number of server channels in all states) o For client channels: - Processes (number of processes hosting client channels) - Channels: number of client channels o For all processes: Total processes: number of RTR application processes (clients and servers). To see separation by process, use MONITOR CHANNEL. o For transaction counts: Active transactions (for each frontend, router, and backend role, displays counts of active transactions with node location and age (in days and clock time as dddd hh:mm::ss) of the oldest transaction) o For RTR uptime by system: Elapsed time in days and clock time(dddd hh:mm:ss) since RTR was started on the given system 3 Example 1 Monitor Summary Environment Summary at 16:00:36 Sat Mar 1 2003 on node -ALL- --Server channels------- --Client channels------- Processes : 2 Processes : 1 Active : 6 Channels : 2 Secondary active : 2 Standby : 4 Other : 1 All server channels : 15 Total processes : 2 Active transactions Backend : 3 Oldest (on length ) 0000 00:04:06 Router : 3 Oldest (on depth ) 0000 00:04:05 Frontend : 3 Oldest (on depth ) 0000 00:04:05 RTR uptime by system depth 0001 02:02:33 length 0001 02:01:56 o 14-5-372 Change to PGFLQUOTA - OpenVMS The calculation of this value for the START RTR command has changed: PGFLQUOTA=((max-links + max- processes)x 400) + 35000 + (reserve_memory_sizex 2048) = default pages (D)) This qualifier, relevant only on OpenVMS systems, specifies the maximum number of pages allocated in the paging file for the RTRACP. The paging file quota is the amount of secondary storage available during execution of the RTRACP image and limits available virtual memory. Note that a shortage of virtual memory can cause transactions to fail. The default value of pages is automatically calculated, based on the values of /LINKS and /PROCESSES. o 14-5-375, 14-5-369 New API calls rtr_get/set_user_ context enable association of user-defined handle with a channel 4 New RTR calls rtr_get_user_context and rtr_set_user_ context have made it possible to associate a user- defined handle with a channel. Details can be found in the softcopy RTR System Manager's Manual and RTR C Application Programmer's Reference Manual distributed on the OpenVMS and Tru64 Online Documentation Libraries distributed after April 2003. These updated RTR documents are also available from the RTR web site at http://www.hp.com/go/rtr o 14-3-488 rtr_set_wakeup documentation enhancements The text of this call has been updated for the RTR C Application Programmer's Reference Manual distributed on the OpenVMS and Tru64 Online Documentation Libraries distributed after April 2003. These updated RTR documents are also available from the RTR web site at http://www.hp.com/go/rtr o 14-1-2448 Description of START RTR/RESERVE_MEMORY_ SIZE improved The description of this command has been improved, and is contained in the softcopy RTR System Manager's Manual distributed on the OpenVMS and Tru64 Online Documentation Libraries distributed after April 2003. These updated RTR documents are also available from the RTR web site at http://www.hp.com/go/rtr 1.1.2 Environment/Operational Improvements o 14-1-769, 14-5-281 Changes in Local Time Tolerated Prior versions of RTR would not operate correctly if the system time were changed to an earlier value, for example when processing a change between standard and daylight savings or summer time. This problem has been corrected. o 14-1-1767 Output of rtr_receive_message improved The output for rtr_receive_message now includes the facility and nodename (FE, TR, BE) of the node sending the event notification. o 14-1-1794, 14-1-1911, 14-3-445 Number of channels, number of partitions increased 5 The number of channels per application process has been increased to 1024. The maximum number of partitions is now dynamic; that is, the user needs to supply the maximum number of partitions using the START RTR command with the /PARTITION qualifier. If the /PARTITION qualifier is not used, then the default number of partitions is set to 500. o 14-1-1938 Flow control counters improved Facility broadcast flow control counters have been expanded to allow differentiation by broadcast flow direction and monitoring of flow stall conditions. o 14-1-1973 Appdelay monitor picture enhanced to reveal blocking applications The process monitor picture APPDELAY has been enhanced to show the presence of application processes with channel queue backlogs sufficiently large to prevent the node from granting flow control credits to its connected RTR routers. Once identified, the system manager should take steps to improve the throughput of such processes. o 14-5-244 Pass facility and link names with certain RTR events RTR NCF-based events are now accompanied by a message naming the affected facility and node. The feature can be disabled by defining the variable RTR_NO_NCF_EVENT_ DATA in the environment of all ACP processes in the configuration. The following events are subject to this behaviour: FACREADY, FACDEAD, FERTRLOSS, FERTRGAIN, RTRBEGAIN, RTRBELOSS, BERTRGAIN, BERTRLOSS, RTRFEGAIN, RTRFELOSS. A server channel may subscribe to these events and use this information to maintain a database of who is connected. o 14-5-294 IP address failover RTR networking support for machines with multiple network adapters has been improved to allow multiple IP connection targets for any host. Thus any pair of machines connected by multiple network paths can fail over to an alternate path should the primary path become unusable. For more information, refer to the Reliable Transaction Router System Manager's Manual section on Network Transports, DNS Server Support. 6 o 14-5-319, 14-5-326 Optional compression of event and reply data This release includes the capability of transmitting broadcast event and transaction reply data in a compressed format, addressing the needs of users who wish to reduce their network bandwidth requirements for the transfer of such data. User data passed to RTR with the rtr_reply_to_client() and rtr_broadcast_ event() calls may optionally be compressed before being passed to the RTRACP process for transmission to the RTR router. The data is decompressed to its original state before being presented to the receiving applications. For more information, refer to the Reliable Transaction Router System Manager's Manual section on Compression of Event and Reply Data. o 14-5-335 Advance notification of prepare message arrival To accomodate the changes to RTR to provide advance notification of arrival of a prepare message, the following changes affect RTR documentation: C API: Open channel flags: RTR_F_OPE_NTFY_PREPARE_PEND - requests notification of the presence of a pending prepare message for the transaction branch at the time of the delivery of the first message of the branch. rtr_receive_message(): New return status possible when returning a message on a channel opened with RTR_F_OPE_NTFY_PREPARE_PEND (see above): RTR_STS_OK_PREPARE_PEND - see rtr.msg 1.2 Upgrades o For a rolling upgrade, RTR nodes should be upgraded from Version 3.2 to Version 4.2 in the following order: 1. Upgrade frontend-only nodes at any time 2. Upgrade router-only and mixed frontend/router nodes 3. Upgrade mixed router/backend nodes 7 4. Upgrade backend-only nodes For more complex configurations, where a node may have combinations of facilities with different backend/router groupings, HP 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, 4.1, or 4.2), 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. The following restrictions apply if you upgrade an RTR environment from RTR Version 3.2 to Version 4.0, 4.1, or 4.2: o The RTR recovery protocol consists of messages sent from one backend through a router to the target backend. If either RTR backend is upgraded to RTR Version 4.0, 4.1 or 4.2, then the router that will be used for recovery must also be running the same version of RTR. o This generally means that any RTR router nodes should be upgraded to RTR Version 4.2 before any RTR backend nodes. o There is no restriction to the order in which RTR backends should be upgraded to Version 4.0, 4.1 or 4.2. 1.3 Restrictions The following restrictions apply to all platforms for this version of RTR. o 14-3-452 Nested transactions not supported Implementation of nested transactions has been withdrawn. This functionality is not available to customer applications. 8 1.4 Clarification [ECO1] o 14-1-2346 SET PARTITION/SUSPEND advisory: Using the SET PARTITION partition-name/SUSPEND command results in the following: o For a partition in the pri_act state, transaction presentation at the secondary site is halted. o For a partition in the sec_act state, the primary site is unaffected. For further information on this command/qualifier combination, see the RTR System Manager's Manual. 1.5 Known Problems with Workarounds The following known problems with workarounds apply to all platforms for this version of RTR. o 14-1-498 Upgrade using RTR V3.1D journal If you are upgrading to RTR Version 4.2 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 RTRACP, or by defining the environment variable RTR_CRM_BE_RECOVERY_PROTOCOL (system-wide) to be 32, using the method appropriate for your operating system. 2 OpenVMS-Specific Information This section gives platform-specific information for the OpenVMS implementation of Reliable Transaction Router. 2.1 Restrictions None. 9 2.2 Known Problems with Workarounds The following known problems with workarounds apply to the OpenVMS platform for RTR. o 14-3-409 RTR V2 command line API not covered in RTR V4 help Before uninstalling RTR V2, make a copy of the RTR V2 help file from SYS$COMMON:[SYSHLP]RTRHLP.HLB and then copy it back afterwards. You can then access it with $ help @RTRHLP 3 Tru64-Specific Information This section gives platform-specific information for this version of Reliable Transaction Router for Tru64 UNIX. 3.1 Restrictions 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. For more information, refer to the Reliable Transaction Router Installation Guide. 3.2 Known Problems with Workarounds None. 4 Windows-Specific Information This section gives platform-specific information for this version of Reliable Transaction Router for Windows platforms. 4.1 New Features o 14-1-2351, 14-1-2386 New toolkit modernizes RTR with Java support. The toolkit can be found on the RTR website at: http://www.hp.com/go/rtr 10 Click on the Java RTR link to access the toolkit. Java RTR (JRTR) is a toolkit that layers on top of RTR. It provides standard Java and J2EE interfaces for RTR applications. JRTR exposes the traditional RTR features of hardware and software high availability, fault tolerance and entire-site disaster recovery by using already well-established interfaces. Specifically it provides JTA (javax.transaction.usertransaction), java.io.InputStream, java.io.OutputStream, and JDBC datasources and connection pools. With JRTR, programmers are more productive because they already know the Java and J2EE concepts. Your investment is protected because you are writing applications that are more portable and better able to integrate with other offerings in the marketplace. 4.2 Restrictions None. 4.3 Known Problems with Workarounds The following known problems with workarounds apply to Windows platforms for RTR. o 14-1-455 Last line of batch file must have 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 of the file or to explicitly add to the end of the last line of the batch procedure. o 14-1-1628 Microsoft DTC patch update required for RTR XA & SQL running on Windows NT 4.0 A bug in Microsoft's Distributed Transaction Coordinator related to the xa_recover() call not returning the full list of in-doubt transactions has been fixed by Microsoft. 11 If you are running Microsoft DTC Version 2.0, check the version number of the msdtc.dll image. If the version number is less than 1999.6.854.0, or if you are not running DTC Version 2.0, verify that NT 4.0 Service Pack 6A is installed, and then upgrade DTC manually. The DTC upgrade, contained in file dtcsetup.exe, and the instructions are available at: ftp://ftp.microsoft.com/bussys/distapps/ MTS/Public-Fixes/usa/DTC/SvcPack/nt4_sp6 ________________________ Note ________________________ This upgrade installs/upgrades to Microsoft DTC Version 2.0, msdtc.dll image version 1999.6.854.0. The upgrade to DTC version 2.0 is the minimum required for RTR to work properly with XA. ______________________________________________________ 5 Sun Solaris-Specific Information This section gives platform-specific information for the implementation of Reliable Transaction Router Version for the Sun Solaris platform. 5.1 Restrictions Reliable Transaction Router Version 4.2 requires Sun Solaris 2.6 or newer; it will not run on Solaris 2.5. 5.2 Known Problems with Workarounds None. 12