HP_Reliable_Transaction_Router______________________ Release Notes December, 2003 HP Reliable Transaction Router (RTR) is fault tolerant transactional messaging middleware used to implement large, multitier, distributed applications using client/server technology. These notes describe the new features, corrections, restrictions, and known problems with workarounds for RTR Version 4.2 ECO2, Version 4.2A for Windows, and Version 4.2 for Linux Frontend. Software Version: HP Reliable Transaction Router Version 4.2 ECO2, Version 4.2A for Windows, Version 4.2 for Linux Frontend Hewlett-Packard Company Palo Alto, California ________________________________________________________________ © 2003 Hewlett-Packard Development Company, L.P. The information contained herein is subject to change without notice. The only warranties for HP products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. HP shall not be liable for technical or editorial errors or omissions contained herein. Proprietary computer software. Valid license from HP 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. Windows[R] and Windows NT[R] are U.S. registered trademarks of Microsoft Corporation. Intel[R] is a U.S. registered trademark of Intel Corporation. UNIX[R] is a registered trademark of The Open Group. Java[[TM]] is a U.S. trademark of Sun Microsystems, Inc. This document was prepared using DECdocument, Version 3.3- 1B. _________________________________________________________________ Contents Preface................................................... v 1 RTR Version 4.2 ECO2 1.1 New Features.................................. 1-1 1.2 Changes Applicable to All Platforms........... 1-11 2 RTR Version 4.2 ECO1 2.1 Information Applicable to All Platforms....... 2-1 2.1.1 New Features.............................. 2-1 2.1.1.1 Functionality........................... 2-1 2.1.1.2 Environment/Operational Improvements.... 2-5 2.1.2 Upgrades.................................. 2-8 2.1.3 Restrictions.............................. 2-9 2.1.4 Clarification............................. 2-9 2.1.5 Known Problems with Workarounds........... 2-9 2.2 OpenVMS-Specific Information.................. 2-10 2.2.1 Restrictions.............................. 2-10 2.2.2 Known Problems with Workarounds........... 2-10 2.3 Tru64-Specific Information.................... 2-10 2.3.1 Restrictions.............................. 2-10 2.3.2 Known Problems with Workarounds........... 2-10 2.4 Windows-Specific Information.................. 2-10 2.4.1 New Features.............................. 2-11 2.4.2 Restrictions.............................. 2-11 2.4.3 Known Problems with Workarounds........... 2-11 2.5 Sun Solaris-Specific Information.............. 2-12 2.5.1 Restrictions.............................. 2-12 2.5.2 Known Problems with Workarounds........... 2-12 iii 3 RTR for Linux Frontend Quick Install 3.1 Disk and Time Requirements.................... 3-1 3.2 Installation Procedure........................ 3-1 4 Full Installation on Linux Frontend 4.1 Prepare for Installation...................... 4-1 4.1.1 Check Required Hardware................... 4-1 4.1.2 Check Required Software .................. 4-2 4.1.3 Check Required Disk Space................. 4-2 4.1.4 Check System Parameters................... 4-2 4.1.4.1 Check Memory-Mapped I/O Requirements.... 4-2 4.1.4.2 Check Virtual Memory Requirements....... 4-2 4.2 Install RTR................................... 4-2 4.3 Complete RTR Setup............................ 4-5 4.3.1 Check Installed Files..................... 4-5 4.3.2 Enable RTR Remote Commands................ 4-5 4.3.3 Display Documentation..................... 4-6 4.3.4 Run RTR................................... 4-6 4.3.4.1 Configure RTR Facilities and Partitions.............................. 4-6 4.3.5 Install and Run Applications.............. 4-6 4.3.5.1 Uninstall RTR for Linux Frontend........ 4-7 Examples 1-1 Monitor Compress.......................... 1-7 1-2 Monitor Lrc............................... 1-9 2-1 Monitor Summary........................... 2-4 Tables 1 RTR Documents............................. v iv _________________________________________________________________ Preface Purpose of these Release Notes This document provides information for Reliable Transaction Router Version 4.2 ECO2. It also contains the full text of information provided with 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, corrections, Router Release restrictions, and known problems for Notes[1] RTR. 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) v 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 through http://www.hp.com links to middleware products or at http:://www.hp.com/go/rtr . vi 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._ vii 1 _________________________________________________________________ RTR Version 4.2 ECO2 This section contains information specific to RTR Version 4.2 ECO2. 1.1 New Features o 14-5-350, 14-3-476 SET TRANSACTION command enhanced with a new transition state: defer. Transactions can be placed in the defer state to delay their recovery. To place a transaction in the defer state, use the SET TRANSACTION command and change the state from pri_done to defer. Later, the deferred transactions can be reset to the pri_done state. /NEW_STATE Specifies the new transaction state to which selected transactions will be changed. This qualifier is required and a new state must be specified. Value of new_state may be one of the following: ABORT COMMIT DONE EXCEPTION PRI_DONE DEFER Note that not all state changes are valid. The following table shows the only valid transaction state changes. RTR Version 4.2 ECO2 1-1 RTR Version 4.2 ECO2 1.1 New Features ________________________________________________________ ________________________________________NEW_STATE_______ Current PRI_ State______COMMIT___ABORT___EXCEPTIONDEFER___DONE_____DONE SENDING YES VOTED YES YES COMMIT YES YES EXCEPTION YES YES PRI_DONE YES YES DEFER________________________________________YES________ o RTR for Linux Frontend An RTR for Linux Frontend product is available for ordering. These Release Notes contain its installation procedures in Chapter 3 (Quick Install) and Chapter 4 (Full Install). The Software Product Description is available on the HP web site, www.hp.com, in the middleware links. o 14-5-404, 14-5-408 Files containing nodelists can include comments. For the RTR CREATE FACILITY command with the /BACKEND, /FRONTEND, and /ROUTER qualifiers that can call indirect files with @filespec, comments can be included in the specified file. Valid comment characters are "!" and "#". Text following a comment character is ignored. o 14-3-507 rtr_start and rtr_send generate new tids. EXPLICIT_START added to the RTR_OPEN_CHANNEL command and equivalent API call. The CALL RTR_OPEN_CHANNEL command executes the rtr_ open_channel() routine and displays the returned status. The EXPLICIT_START qualifier on a client channel ensures that rtr_send_to_server does not generate new transactions in the event of an rtr_start_tx time out. ________________________ Note ________________________ This command is not available in the RTR web browser interface. ______________________________________________________ 1-2 RTR Version 4.2 ECO2 RTR Version 4.2 ECO2 1.1 New Features CALL RTR_OPEN_CHANNEL ________________________________________________________ Command Qualifiers_____Defaults_________________________________ /EXPLICIT_ /NOEXPLICIT_START START___________________________________________________ The CALL RTR_OPEN_CHANNEL command causes a command server to call the rtr_open_channel() routine using values supplied on the command line. The following table shows the correspondence between the C language flag and the value you supply on the command line. ________________________________________________________ C Parameter_C_Parameter_Value_______Command_Line__________ flag RTR_F_OPE_EXPLICIT_ /EXPLICIT_START __________START_________________________________________ /EXPLICIT_START NOEXPLICIT_START (D) Valid for client channels only. Using this flag requires that an explicit rtr_start_tx() be called on this channel. The procedure is in effect until the channel is closed. The EXPLICIT_START flag insures that rtr_ send_to_server() does not generate new transactions should the rtr_start_tx() time out. If the user calls rtr_send_to_server() without first calling rtr_start_tx(), the error message RTR_STS_ INVIMPCLSTRT is returned informing the caller that they must call rtr_start_tx() first on this channel. o 14-5-409, 14-1-2577 RTR on Linux detects and uses IP addresses from INET interfaces. RTR Version 4.2 ECO2 1-3 RTR Version 4.2 ECO2 1.1 New Features Linux INET Interface Support: To ensure that RTR does not use a loopback address, RTR on Linux enumerates all INET interfaces. RTR adds to its cache the IP address associated with each INET interface that is not a loopback interface and is UP. To view the interfaces on your system, issue the command ifconfig -a; this command reveals which interfaces are loopback, and which are UP. Beginning with Red Hat Enterprise Linux WS 2.1 and Red Hat 9.0, the /etc/hosts file may contain an entry matching the hostname with IP address 127.0.0.1. A sample default /etc/hosts file on those platforms would look like the following: -- SAMPLE /etc/hosts file -- # Do not remove the following line, or various programs # that require network functionality will fail. 127.0.0.1 hostname localhost.localdomain localhost ---------------------------- Thus, the gethostbyname() function returns address 127.0.0.1 for any query on hostname. o 14-3-517 Display and use of PIDs improved. OpenVMS displays process IDs (PIDs) as 8-character strings, left padding with zeros as needed. On unclustered OpenVMS systems, earlier versions of RTR would display PIDs without leading zeros and PIDs with leading zeros were not accepted as values for SHOW and MONITOR commands. These defects have been corrected. o 14-5-414 Default node affix enhancement is explained in the following table. 1-4 RTR Version 4.2 ECO2 RTR Version 4.2 ECO2 1.1 New Features ________________________________________________________ Environment Variable for Default Node Affixes_____________Description_________________________ Default Node RTR can accept a default nodename Affixes prefix or suffix from the environment. The prefix or suffix is applied to all node names referenced in facility creation, trim and extend operations, unless the nodename as entered already contains the period character '.' This functionality is controlled by the following environment variables: RTR_DEFAULT_NODE_ Defines a default node prefix for PREFIX facility configuration commands. Example: $ define/system RTR_DEFAULT_NODE_PREFIX "LOCAL:.ZKO." RTR_DEFAULT_NODE_ Defines a default node suffix for SUFFIX facility configuration commands. Examples: OpenVMS: $ define/system RTR_DEFAULT_NODE_ SUFFIX ".hp.com" UNIX: export RTR_DEFAULT_NODE_ SUFFIX=".hp.com" Windows: set RTR_DEFAULT_NODE_ SUFFIX=".hp.com" RTR_DEFAULT_NODE_ If defined, overrides the setting ALL that exempts nodes whose names contain a period from default prefix and suffix processing. RTR Version 4.2 ECO2 1-5 RTR Version 4.2 ECO2 1.1 New Features ________________________________________________________ Environment Variable for Default Node Affixes_____________Description_________________________ Local Node Euphemism · When working with facilities, the nodename of '.' (a period or full stop) is an acceptable substitute for the local nodename. For example, the command: RTR> create facility f1/frontend=./router=elsewhere makes the computer executing the command a frontend in the facility ____________________named_f1.___________________________ o 14-5-326 Monitor picture for compression data. A new monitor picture, compress.mon (Monitor Compress), displays compression configuration and operation information. Monitor Compress Displays compression configuration and operation information. Information displayed includes the following: o Compression settings and results for replies from server to client channels. o Compression settings and results for server and client generated broadcast events. o Name of computer sending the sample, and the application process ID and name. o Compression threshold setting in bytes [environment variable RTR_REPLY_COMPRESS_THRESHOLD]. Only larger replies are compressed. A value of 0 indicates that compression is not enabled. 1-6 RTR Version 4.2 ECO2 RTR Version 4.2 ECO2 1.1 New Features o The reply compression level in effect for the process [environment variable RTR_REPLY_COMPRESS_LEVEL]. A value of -1 indicates the default compression level is selected. o Average compression effectiveness for server replies, ranging from 100 (perfect) to 0 (completely ineffective) or even less than 0. This column is only displayed if reply compression is enabled. o Compression threshold setting in bytes [environment variable RTR_EVENT_COMPRESS_THRESHOLD]. Only larger events are compressed. A value of 0 indicates that compression is not enabled. o The event compression level in effect for the process [environment variable RTR_EVENT_COMPRESS_LEVEL]. A value of -1 indicates the default compression level is selected. o Average compression effectiveness for client generated events, ranging from 100 [perfect] to 0 [completely ineffective] or even less than 0. This column is only displayed if event compression is enabled. o Average compression effectiveness for server generated events, ranging from 100 [perfect] to 0 [completely ineffective] or even less than 0. This column is only displayed if event compression is enabled. Example 1-1 Monitor Compress COMPRESSION OVERVIEW BY PROCESS 17:38:13 Wed Oct 15 2003 on -ALL- (continued on next page) RTR Version 4.2 ECO2 1-7 RTR Version 4.2 ECO2 1.1 New Features Example 1-1 (Cont.) Monitor Compress +-Replies-----------+ +-Events------------------+ ClientServer Node, Process ID & name Threshold Level Ratio Threshold Level Ratio Ratio nodeaa 10712 10712 0 0 0 0 rtrm08 1940 usertest v3t_sr 1 -1 100.0 0 -1 rtrm08 2108 usertest v3t_sr 1 -1 100.0 0 -1 rtrm08 2072 usertest v3t_sr 1 -1 100.0 0 -1 rtrm08 2020 usertest v3t_sr 999 -1 100.0 0 -1 rtrm08 1856 usertest v3t_sr 0 -1 0 -1 rtrm08 2120 usertest v3t_sr 0 9 0 -1 rtrm08 2112 usertest v3t_sr 0 9 555 -1 100.0 100.0 rtrm08 156 usertest v3t_sr 0 9 555 3 100.0 100.0 rtrm08 2168 usertest rtr.ex 777 9 91.0 666 3 88.4 88.1 o 14-3-535 Improved display of large numeric values (DISPLAY NUMERIC) in monitor pictures on character-cell terminals. Numeric values that are too large to fit within the field width of a monitor picture when displayed on a terminal are rescaled and displayed with a suffix indicating the scale. The number of significant figures displayed depends on the available field width. o 14-5-419 Monitor picture for link checksums. A new monitor picture, lrc.mon (Monitor LRC), displays link checksum configuration and operation. Monitor LRC Displays link checksum configuration and operation status. Information displayed includes the following: o Shows incoming message and checksum data for the given links. o Number of links which are up. o Number of links which are down. o Total number of links. o All required links are up. 1-8 RTR Version 4.2 ECO2 RTR Version 4.2 ECO2 1.1 New Features o Some required links are down. o Number of links with checksum enabled. o Number of messages received with a bad checksum. o Number of messages received from RTR V2 with an LRC. o Number of messages received with a checksum appended. o Number of messages received without a checksum. o Total number of messages received on the link. o Total of all shown links. Example 1-2 Monitor Lrc LINK CHECKSUM ERRORS Wed Oct 15 2003 18:03:57 DEPTH <- -ALL- Links up 2 Links down 1 Total links 3 Required links down enabled lrcerror lrcheader lrctrailer lrcundone received Total 1 0 0 34 12155189 50839617 DEPTH <- depth 0 0 0 0 0 38684394 DEPTH <- length 1 0 0 34 12155189 12155223 DEPTH <- sarand 0 0 0 0 0 0 o A new DISCONNECT LINK command provides enhanced link control capabilities. Disconnects an RTR link. DISCONNECT LINK [linkname] ________________________________________________________ Command Qualifiers____Defaults__________________________________ /CLUSTER /NOCLUSTER /NODE[=node- /NODE=default-node list] /OUTPUT[=files/OUTPUT=stdout____________________________ The DISCONNECT LINK command disconnects an RTR link. RTR Version 4.2 ECO2 1-9 RTR Version 4.2 ECO2 1.1 New Features ________________________ Note ________________________ - Linkname matching is case sensitive. - Linknames must be entered exactly as displayed by the SHOW LINK command; no aliases are allowed. - No error is generated if the specified link cannot be found, nor is exit status set to indicate an error. ______________________________________________________ linkname Specifies the name of a link (that is, the node at the other end of a link); linkname may contain wild cards ("*" and "%"), in which case all matching links are disconnected. /CLUSTER /NOCLUSTER (D) Specifies that the command is executed on all the nodes in the cluster. If neither /NODE nor /CLUSTER is specified, the command is executed on the nodes specified by the latest SET ENVIRONMENT command. If no SET ENVIRONMENT command has been entered, the command is executed only on the node where the command was issued. ________________________ Note ________________________ In environments that do not support remote command capability, the /CLUSTER qualifier causes the relevant command to be executed on the local node only. ______________________________________________________ /NODE[=node-list] /NODE=default-node (D) Specifies that the command is executed on all nodes specified in node-list. If node-list is omitted, the command is executed only on the node where the command was issued. 1-10 RTR Version 4.2 ECO2 RTR Version 4.2 ECO2 1.1 New Features /OUTPUT[=filespec] /OUTPUT=stdout (D) Specifies that the resulting information is written to the file filespec. If /OUTPUT or filespec is omitted, the standard or default output is used. 1.2 Changes Applicable to All Platforms o 14-3-530 The following reply compression description supersedes that provided with Reliable Transaction Router Version 4.2 in Februrary 2003. Compression of Event and Reply Data Transaction data can be transmitted in a compressed format, to address the needs of users who wish to reduce their network bandwidth requirements for the transfer of such data. User data passed to RTR using the rtr_reply_to_ client(), rtr_broadcast_event() and rtr_ext_broadcast_ event() calls may optionally be compressed before being passed to the RTRACP process for transmission to the RTR router. The event or reply data are decompressed to their original state before being presented to the receiving applications. Compression and decompression occur in the address space of client and server applications, so these processes will consume additional CPU resources when compression is in use. Compression is done using the zlib open source library. For further information, consult http://www.gzip.org/zlib/. To ensure interoperability, all participating systems must be running a version of RTR that supports compression. Failure to observe this restriction may cause compressed data to be incorrectly delivered to applications expecting uncompressed data. You cannot use compression and the msgfmt argument of rtr_ reply_to_client(), rtr_broadcast_event(), or rtr_ext_ broadcast_event() simultaneously. RTR Version 4.2 ECO2 1-11 RTR Version 4.2 ECO2 1.2 Changes Applicable to All Platforms Compression is controlled with the following environment variables defined on participating frontends and backends as follows: On participating frontends to control compression of client broadcasts: RTR_EVENT_COMPRESS_LEVEL RTR_EVENT_COMPRESS_THRESHOLD On participating backends: RTR_EVENT_COMPRESS_LEVEL RTR_EVENT_COMPRESS_THRESHOLD RTR_REPLY_COMPRESS_LEVEL RTR_REPLY_COMPRESS_THRESHOLD The EVENT_COMPRESS variables control event-data compression. They are deployed on a frontend to control compression of outgoing client broadcasts, and on a backend to control compression of outgoing server broadcasts. The LEVEL variable controls compression amount or level; valid values are integers in the range 1-9. Higher levels cause better compression, at the cost of increased CPU usage. If unspecified, the zlib default compression level is used. The REPLY_COMPRESS variables control outgoing server reply data compression, and are consequently deployed on the backends where the replies originate. The THRESHOLD variable defines the size of the largest data packet not subject to compression; anything larger is compressed. A threshold value of 0, the default, disables compression. These variables are read once only, shortly after an application makes its first call to the RTR API. No setup is required on router nodes, or if no compression is wanted. Decompression is automatic, provided the interoperability criteria (see above) are met. Compression settings and operations can be monitored for any RTR application process with the commands. Compression settings are displayed with: RTR> show process/counter=api_compress* 1-12 RTR Version 4.2 ECO2 RTR Version 4.2 ECO2 1.2 Changes Applicable to All Platforms The number of compressed data operations performed by an application process can be viewed with: RTR> show process/counter=*compressed The number of uncompressed (or raw) and resulting compressed bytes per operation can be viewed with either of the following commands: RTR> show process/counter=*event*bytes* RTR> show process/counter=*reply_to_client_bytes* o 14-3-549 Installation instructions for stopping RTRD superseded As part of the uninstalling procedure, to stop all RTR processes on the system, use the following command sequence: RTR STOP RTR [stop all other RTR processes as needed] RTR DISCONNECT SERVER/DAEMON The command that disconnects the server and daemon must be executed after all other RTR processes have been stopped. If any other RTR processes are still running after the daemon is disconnected, the daemon will be automatically restarted. The command server must still be running in order for that command to disconnect the daemon. If the command server has been stopped, then that command will not disconnect the daemon. RTR Version 4.2 ECO2 1-13 2 _________________________________________________________________ RTR Version 4.2 ECO1 2.1 Information Applicable to All Platforms This section describes the new features, changes, and restrictions in Reliable Transaction Router, Version 4.2 ECO1. 2.1.1 New Features This section describes the new features available in this release for all platforms. 2.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 RTR Version 4.2 ECO1 2-1 RTR Version 4.2 ECO1 2.1 Information Applicable to All Platforms 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 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 2-2 RTR Version 4.2 ECO1 RTR Version 4.2 ECO1 2.1 Information Applicable to All Platforms 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 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) RTR Version 4.2 ECO1 2-3 RTR Version 4.2 ECO1 2.1 Information Applicable to All Platforms 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 Example 2-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. 2-4 RTR Version 4.2 ECO1 RTR Version 4.2 ECO1 2.1 Information Applicable to All Platforms o 14-5-375, 14-5-369 New API calls rtr_get/set_user_ context enable association of user-defined handle with a channel 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 2.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. RTR Version 4.2 ECO1 2-5 RTR Version 4.2 ECO1 2.1 Information Applicable to All Platforms o 14-1-1794, 14-1-1911, 14-3-445 Number of channels, number of partitions increased 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 2-6 RTR Version 4.2 ECO1 RTR Version 4.2 ECO1 2.1 Information Applicable to All Platforms Transaction Router System Manager's Manual section on Network Transports, DNS Server Support. 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 RTR Version 4.2 ECO1 2-7 RTR Version 4.2 ECO1 2.1 Information Applicable to All Platforms 2.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 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. 2-8 RTR Version 4.2 ECO1 RTR Version 4.2 ECO1 2.1 Information Applicable to All Platforms 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. 2.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. 2.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. RTR Version 4.2 ECO1 2-9 RTR Version 4.2 ECO1 2.2 OpenVMS-Specific Information 2.2 OpenVMS-Specific Information This section gives platform-specific information for the OpenVMS implementation of Reliable Transaction Router. 2.2.1 Restrictions None. 2.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 2.3 Tru64-Specific Information This section gives platform-specific information for this version of Reliable Transaction Router for Tru64 UNIX. 2.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. 2.3.2 Known Problems with Workarounds None. 2.4 Windows-Specific Information This section gives platform-specific information for this version of Reliable Transaction Router for Windows platforms. 2-10 RTR Version 4.2 ECO1 RTR Version 4.2 ECO1 2.4 Windows-Specific Information 2.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 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. 2.4.2 Restrictions None. 2.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 RTR Version 4.2 ECO1 2-11 RTR Version 4.2 ECO1 2.4 Windows-Specific Information 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. 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. ______________________________________________________ 2.5 Sun Solaris-Specific Information This section gives platform-specific information for the implementation of Reliable Transaction Router Version for the Sun Solaris platform. 2.5.1 Restrictions Reliable Transaction Router Version 4.2 requires Sun Solaris 2.6 or newer; it will not run on Solaris 2.5. 2.5.2 Known Problems with Workarounds None. 2-12 RTR Version 4.2 ECO1 3 _________________________________________________________________ RTR for Linux Frontend Quick Install Your Reliable Transaction Router for Linux Frontend kit is supplied on CD-ROM. After installation, the Release Notes file is located in the /usr/share/doc directory; you are advised to read the Release Notes file before using RTR. _____________ User-Changed Monitor Files _____________ If you have changed any RTR monitor (*.mon) files, they will automatically be renamed when using rpm to uninstall. ______________________________________________________ 3.1 Disk and Time Requirements The installation of the RTR base product requires about 22 MB (megabytes) of disk space. The installation procedure takes about two minutes to complete. 3.2 Installation Procedure 1. If RTR is already installed on your system, see Section 4.3.5.1, Uninstall RTR for Linux Frontend, for information on uninstalling RTR and removing related processes. 2. If you are installing on Linux, log in as the root user. 3. Insert the RTR CD-ROM into the drive. If Red Hat does not automatically mount your CD-ROM, you will need to mount it before proceeding to the next step. 4. CD to your CD-ROM drive. RTR for Linux Frontend Quick Install 3-1 RTR for Linux Frontend Quick Install 3.2 Installation Procedure 5. The Reliable Transaction Router for Linux Frontend installs in the standard way on Red Hat systems. You may use gnorpm on Red Hat Workstation for a graphical install, or, on the command line with Red Hat 9, use rpm -i packagename.rpm as the root user. If you previously installed an RTR Linux kit, you will need to uninstall the old one before installing the new one. 3-2 RTR for Linux Frontend Quick Install 4 _________________________________________________________________ Full Installation on Linux Frontend This chapter describes how to install HP Reliable Transaction Router on Linux Frontend systems. It includes steps for: o Preparing for installation o Installing RTR o Completing RTR setup 4.1 Prepare for Installation Before you start the installation, review the hardware and software requirements described in the following sections. _____________ User-Changed Monitor Files _____________ If you have changed any RTR monitor (*.mon) files, you must rename them or they will be overwritten during installation. To avoid this, always work from renamed copies of RTR monitor files when making local modifications. ______________________________________________________ 4.1.1 Check Required Hardware o For client functionality, any Intel32 system that runs Redhat Linux Version 9 or Redhat Enterprise Linux WS Version 2.1. Full Installation on Linux Frontend 4-1 Full Installation on Linux Frontend 4.1 Prepare for Installation 4.1.2 Check Required Software Required software for each system to be used with RTR: o Redhat Linux Version 9 o Redhat Enterprise Linux WS Version 2.1 o TCP/IP support as provided by the operating system o At least one Reliable Transaction Router Backend license for a supported operating system for development and application deployment 4.1.3 Check Required Disk Space The installation of the RTR base product requires about 22 megabytes of disk space. The installation procedure takes about two minutes to complete. 4.1.4 Check System Parameters RTR has basic memory requirements. This section references setup instructions for the relevant system parameters. 4.1.4.1 Check Memory-Mapped I/O Requirements For information on how to size memory-mapped I/O appropriately, refer to Reliable Transaction Router System Manager's Manual, RTR Shared Memory Sizing. 4.1.4.2 Check Virtual Memory Requirements The basic memory requirement for an unconfigured RTRACP is 5.6 MB. Additional memory may be required. 4.2 Install RTR 1. If you are installing on Linux, ensure that you are logged in as the root user. 2. If RTR is already installed on your system, see Section 4.3.5.1, Uninstall RTR for Linux Frontend, for information on uninstalling RTR and removing related processes. 3. Insert the RTR CD-ROM into the drive. If Redhat does not automatically mount your CD-ROM, you will need to mount it before proceeding to the next step. 4-2 Full Installation on Linux Frontend Full Installation on Linux Frontend 4.2 Install RTR 4. Exit all programs. 5. CD to the CDROM drive. 6. The HP Reliable Transaction Router for Linux Frontend installs in the standard way on Redhat systems: o use gnorpm for a graphical install on Redhat Workstation systems o use rpm -i packagename.rpm on the command line with Redhat 9 as the root user. 7. If you previously installed an RTR Linux kit, you will need to uninstall the old one before installing the new one. For example, the following shows the installation display: # rpm -i rtr_frontend-4.2-362.i386.rpm RTR for Linux Front End is licensed per processor, with one license required for each processor in the system. If more processors or systems are added, then additional RTR licenses must be purchased. # To verify your installation, run the IVP: # cd /opt/rtr/examples/IVP # ./rtr_ivp_osf.sh Starting Reliable Transaction Router V4.2 for GNU Linux Installation Verification Procedure keeping any existing log file settings (RTR_DBG not set) starting RTR . . . %RTR-S-RTRSTART, RTR started on node bznbzn creating a journal, if not already created . . . %RTR-S-JOURNALINI, journal has been created on device /dev/hda3 creating test facility . . . %RTR-S-FACCREATED, facility rtr_ivp_facility created stopping RTR. %RTR-S-RTRSTOP, RTR stopped on node bznbzn [OPTIONAL] attempting to compile and link rtr test applications . . . Full Installation on Linux Frontend 4-3 Full Installation on Linux Frontend 4.2 Install RTR If this system is not configured with an application development environment, or the platform does not support threads, then some messages about application compilation not succeeding are normal. multithreaded server rtr application compiled single-threaded client rtr application compiled applications rtrreq and rtrsrv available starting rtr and creating default facility %RTR-I-NOLOGSET, logging not set %RTR-S-RTRSTART, RTR started on node bznbzn %RTR-S-FACCREATED, facility RTR$DEFAULT_FACILITY created starting an rtr server application running an rtr client application, should complete in a few seconds stopping rtr %RTR-S-RTRSTOP, RTR stopped on node bznbzn Reliable Transaction Router V4.2 for GNU Linux Installation Verification Procedure successful # To see additional detail about what you have installed, use the following command: # rpm -q -i rtr_frontend Name : rtr_frontend Relocations: /opt/rtr Version : 4.2 Vendor: Hewlett-Packard Company Release : 362 Build Date: Wed 03 Sep 2003 03:47:11 PM EDT Install date: Wed 03 Sep 2003 03:53:40 PM EDT Build Host: bznbzn Group : Development/Middleware Source RPM: rtr_frontend-4.2-362.nosrc.rpm Size : 22029958 License: Per Processor License for RTR Linux Frontend Packager : HP RTR Engineering URL : http://www.hp.com/go/rtr Summary : HP Reliable Transaction Router Description : HP Reliable Transaction Router (RTR) for Linux Frontend is fault tolerant transactional middleware used as a client in a client/server environment. 4-4 Full Installation on Linux Frontend Full Installation on Linux Frontend 4.3 Complete RTR Setup 4.3 Complete RTR Setup Give the RTR root directory and all its subdirectories "Full Control" access for all RTR users. You may then restrict access on individual files to read only. (All RTR users require write access to the RTR journal directory.) 4.3.1 Check Installed Files Navigate to the directory where you installed RTR. The default is /var/opt/rtr. To see a list of the files installed, enter the following command: # rpm -q -l rtr_frontend To see what has been installed, enter the following command: # rpm -q -i rtr_frontend Name : rtr_frontend Relocations: /opt/rtr Version : 4.2 Vendor: Hewlett-Packard Company Release : 362 Build Date: Wed 27 Aug 2003 01:27:4T Install date: Wed 27 Aug 2003 02:13:13 PM EDT Build Host: bznbzn Group : Development/Middleware Source RPM: rtr_frontend-4.2-362.nom Size : 22029958 License: Per Processor License fd Packager : HP RTR Engineering URL : http://www.hp.com/go/rtr Summary : HP Reliable Transaction Router Description : Reliable Transaction Router(TM) (RTR) is an open client/server software fault tolerant middleware for continuous high performance distributed transaction processing. # 4.3.2 Enable RTR Remote Commands While this is not required to use RTR for Linux Frontend, to make it possible to execute RTR commands on remote systems, you must use the remote shell (RSH). See the documentation on remote shell on your Linux system. The RSH service runs commands on remote computers running the RSH service. This command is available only if the TCP/IP protocol has been installed. Full Installation on Linux Frontend 4-5 Full Installation on Linux Frontend 4.3 Complete RTR Setup You can also execute remote commands with /NODE qualifiers on certain RTR commands, and in conjunction with the RTR SET ENVIRONMENT command. For more information on executing RTR commands remotely, refer to the Reliable Transaction Router System Manager's Manual. 4.3.3 Display Documentation Softcopy documentation for Reliable Transaction Router is available on the RTR Software Kit in distilled PostScript (.pdf) file format. You can display .pdf files with Acrobat Reader, a free reader of electronic files from Adobe Systems. Release Notes are placed in the /usr/share/doc directory with the .pdf files. 4.3.4 Run RTR To run RTR, follow these steps: o To run RTR, enter the following command at the system prompt: # RTR RTR> o To start RTR, enter Start RTR at the RTR> prompt. 4.3.4.1 Configure RTR Facilities and Partitions For information on configuring RTR facilities and setting up partitions, refer to the Reliable Transaction Router Getting Started and the Reliable Transaction Router System Manager's Manual. 4.3.5 Install and Run Applications Once applications that use RTR have been designed and tested, they can be deployed on the systems configured for use with RTR. For information on designing applications, refer to the Reliable Transaction Router Application Design Guide; for information on deployment and monitoring, refer to the Reliable Transaction Router System Manager's Manual. 4-6 Full Installation on Linux Frontend Full Installation on Linux Frontend 4.3 Complete RTR Setup 4.3.5.1 Uninstall RTR for Linux Frontend The command to uninstall a Linux package is the following: rpm -e packagename When executing this command, the system displays the following: uninstalling RTR_FRONTEND... # To list all installed packages, issue the command rpm -qa. Full Installation on Linux Frontend 4-7