Reliable_Transaction_Router,_Version_3.1D___________ Release Notes November, 1997 These release notes describe the new features, changes, and known restrictions for Reliable Transaction Router, Version 3.1D on all supported platforms. Reliable Transaction Router is fault tolerant and transaction management middleware, used to implement large, distributed, transaction processing applications. Software Version: Reliable Transaction Router, Version 3.1D Digital Equipment Corporation Maynard, Massachusetts ________________________________________________________________ November, 1997 The information in this document is subject to change without notice and should not be construed as a commitment by Digital Equipment Corporation. Digital Equipment Corporation assumes no responsibility for any errors that may appear in this document. The software described in this document is furnished under a license and may be used or copied only in accordance with the terms of such license. No responsibility is assumed for the use or reliability of software on equipment that is not supplied by Digital Equipment Corporation or its affiliated companies. Restricted Rights: Use, duplication, or disclosure by the U.S. Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013. © Digital Equipment Corporation 1989, 1997. All Rights Reserved. The following are trademarks of Digital Equipment Corporation: Alpha, DEC, DECdtm, DECnet, Digital, DNA, OpenVMS, PATHWORKS, Reliable Transaction Router, VAX, VAX DOCUMENT, VAX Pascal, VAX RMS, VAX Volume Shadowing, VMS, VMScluster, and the DIGITAL Logo. The following are Registered Trademarks of Borland International, Inc.: Turbo Pascal[R] The following is a Registered Trademark of Hewlett-Packard Company: HP-UX[R] The following is a Trademarks of Intel Corporation: Intel[TM] The following is a Registered Trademark of International Business Machines Corporation: IBM[R]. The following are Trademarks of International Business Machines Corporation: AIX[TM] and RISC System/6000[TM]. The following are Registered Trademarks of Microsoft Corporation: MS-DOS[R] MS[R] and Microsoft[R]. The following are Trademarks of Microsoft Corporation: Windows[TM], Windows NT[TM], Visual Basic[TM] and Visual C++ [TM] The following are Registered Trademarks of Oracle Corporation: ORACLE[R], SQL*Net[R] and SQL*Plus[R]. The following are Trademarks of Oracle Corporation: ORACLE7[TM] and PL/SQL[TM]. The following are Registered Trademarks of Sun Microsystems, Inc.: SUN[R] and Solaris[R]. The following are Trademarks of Sun Microsystems, Inc.: SPARCstation[TM] and SunOS[TM]. UNIX is a registered trademark in the United States and other countries licensed exclusively through X/Open Company Ltd. This document was prepared using DECdocument, Version 3.2. _________________________________________________________________ Contents Preface................................................... v 1 General Information 1.1 New features.................................. 1-1 1.2 Changes and Corrections....................... 1-3 1.3 Known Problems................................ 1-11 1.4 Restrictions.................................. 1-12 1.5 Miscellaneous................................. 1-14 1.5.1 TCP Services File......................... 1-14 1.5.2 RTR Privileges............................ 1-14 1.6 Interoperation with RTR Version 2 Using DECnet........................................ 1-15 2 Digital UNIX Specific Information 2.1 New features.................................. 2-1 2.2 Changes and Corrections....................... 2-1 2.3 Known Problems................................ 2-1 2.4 Restrictions.................................. 2-2 3 OpenVMS Specific Information 3.1 New features.................................. 3-1 3.2 Changes and Corrections....................... 3-1 3.3 Known Problems................................ 3-6 3.4 Restrictions.................................. 3-6 3.5 Reliable Transaction Router, Version 3.1D Installation Information...................... 3-7 3.6 Network Protocol Selection.................... 3-8 3.7 Problem Diagnosis............................. 3-9 3.8 Linking RTR Applications...................... 3-9 iii 3.9 Compatibility of Version 2.2D ECO6 Applications Running on Version 3.1D.......... 3-9 4 AIX Specific Information 4.1 New features.................................. 4-1 4.2 Changes and Corrections....................... 4-1 4.3 Known Problems................................ 4-1 4.4 Restrictions.................................. 4-1 5 SunOS Specific Information 5.1 New features.................................. 5-1 5.2 Changes and Corrections....................... 5-1 5.3 Known Problems................................ 5-1 5.4 Restrictions.................................. 5-2 5.5 Miscellaneous................................. 5-3 6 HP-UX Specific Information 6.1 New features.................................. 6-1 6.2 Changes and Corrections....................... 6-1 6.3 Known Problems................................ 6-1 6.4 Restrictions.................................. 6-1 7 Windows NT Specific Information 7.1 New features.................................. 7-1 7.2 Changes and Corrections....................... 7-4 7.3 Known Problems................................ 7-5 7.4 Restrictions.................................. 7-5 8 Windows 95 Specific Information 8.1 New features.................................. 8-1 8.2 Changes and Corrections....................... 8-3 8.3 Known Problems................................ 8-4 8.4 Restrictions.................................. 8-4 8.5 Restrictions for Applications Written for RTR Version 1.1 for DOS/Windows................... 8-5 iv A RTR Monitor Pictures A.1 New Monitor Pictures.......................... A-1 Tables A-1 MONITOR GROUP Fields...................... A-2 v _________________________________________________________________ Preface Purpose of these Release Notes These Release Notes provide information for Reliable Transaction Router, Version 3.1D (RTR) that could not be included in the manuals. These notes give information for all implementations of Reliable Transaction Router, Version 3.1D. The new features of Reliable Transaction Router, Version 3.1D are described, together with any restrictions applicable to this version. Intended Audience These Release Notes are intended for all users of Reliable Transaction Router, Version 3.1D. Please read these notes before using the product. You should also read the cover letter and any README files supplied with the kit. Document Structure o Chapter 1 describes the new features, changes, restrictions and known problems for Reliable Transaction Router, Version 3.1D applicable to all platforms. o Chapter 2 gives information specific to the Digital UNIX[R] implementation of Reliable Transaction Router, Version 3.1D. o Chapter 3 gives information specific to the OpenVMS implementation of Reliable Transaction Router, Version 3.1D. o Chapter 4 gives information specific to the AIX implementation of Reliable Transaction Router, Version 3.1D. v o Chapter 5 gives information specific to the SunOS implementation of Reliable Transaction Router, Version 3.1D. o Chapter 6 gives information specific to the HP-UX implementation of Reliable Transaction Router, Version 3.1D. o Chapter 7 gives information specific to the Windows NT implementation of Reliable Transaction Router, Version 3.1D. o Chapter 8 gives information specific to the Windows 95 implementation of Reliable Transaction Router, Version 3.1D. o Appendix A gives information about new RTR monitor files provided to help in debugging RTR applications. Related Documentation o Reliable Transaction Router Version 3.1D, Installation Guide o Reliable Transaction Router Version 3.1D, Application Programmer's Reference Manual o Reliable Transaction Router Version 3.1D, System Manager's Manual vi Conventions The following conventions are used in this manual: ___________________________________________________________ Convention________Meaning__________________________________ # A number sign (#) is the default UNIX superuser prompt. % A percent sign (%) is the default UNIX user prompt. In examples, a boxed symbol indicates that you must press the named key on the keyboard. Ctrl/C This symbol indicates that you must press the Ctrl key while you simultaneously press another key (in this case, C). user input In interactive examples, this typeface indicates input entered by the user. filesystem In text, this typeface indicates the exact name of a command, routine, partition, pathname, directory, or file. This typeface is also used in interactive examples and other screen displays. UPPERCASE The Digital UNIX operating system lowercase differentiates between lowercase and uppercase characters. Examples, syntax descriptions, function definitions, and literal strings that appear in text must be typed exactly as shown. Commands typed to the RTR CLI are not case sensitive unless enclosed in quote marks. setld(8) Cross-references to UNIX online reference pages include the appropriate section number in parentheses. For example, setld(8) indicates that you can find the material on the setld command in Section 8 of the reference pages. vii ___________________________________________________________ Convention________Meaning__________________________________ [y] In a prompt, square brackets indicate that the enclosed item is the default response. For example, [y] means the __________________default_response_is_Yes._________________ viii 1 _________________________________________________________________ General Information This chapter describes the new features, changes and restrictions in Reliable Transaction Router, Version 3.1D common to all platforms. Refer to later chapters for platform specific information. ________________________ Note ________________________ All items in these Release Notes are prefixed with a Problem Number, in order to improve problem tracking and reporting. ______________________________________________________ 1.1 New features o 14-7-719 Year 2000 compliance RTR V3.1D is fully compliant with Digital Equipment Corporation standards for Year 2000 functionality, in particular: - Software product supports a date range beyond the year 2000 (ie. 20:45:52, December 13, 1901 to 03:14:07, January 19, 2038 for Digital UNIX) and will transition from Dec. 31, 1999 to Jan. 1, 2000 without intervention. - Software product system time will automatically function beyond the year 2000 without intervention. Software product will correctly use system time beyond the year 2000. - All date calculations and representations are correct for any date data within the supported date range. All General Information 1-1 General Information 1.1 New features date translations are correct for date data within the supported date range. - Software product provides four digit year data interfaces and API's. Any two digit year interfaces and API's have corresponding four digit alternatives and include a documented behavior such as a sliding window interpretation. o 14-1-82 Message length checking While making an RTR call to rtr_send_to_server(), rtr_ reply_to_client() or rtr_broadcast_event() the error code RTR_STS_INVDSDEF "msglen not consistent with msglen derived from msgfmt" is returned when a user passed a "msglen" parameter that is not consistent with the length derived from "msgfmt". o 14-7-308 New monitor picture MONITOR RECOVERY displays the status of restart and shadow recovery operations. RTR scans backend journals when a server is started or whenever a backend node is reconnected to an operational facility in order to recover remembered transactions. MONITOR RECOVERY shows the number of backend journals which were scanned during this process and the number of transactions recovered. MONITOR RECOVERY is useful in determining which backend node could not be accessed during the recovery operation (server states lcl_rec_fail and shd_rec_fail). o 14-7-308 More RTR monitor pictures The monitor pictures MONITOR ACCFAIL, MONITOR CONNECT and MONITOR CONNECTS have been introduced to assist in application and network debugging. See the Monitor Pictures Appendix for further information. o 14-7-853 Alta Vista Internet Personal Tunnel support This version of RTR may be used with the Alta Vista Internet Personal Tunnel. Frontend nodes located outside the firewall may be specified in facility definitions using wildcards in nodenames. The set of valid wild card 1-2 General Information General Information 1.1 New features characters are "*%?". This allows facility definitions such as:- CREATE FACILITY . . ./FRONT_END=*.OUR.ISP.PROVIDER o 14-7-853 Alta Vista Internet Group Tunnel support This version of RTR may be used with the Alta Vista Group Tunnel. The Tunnel can carry any RTR connection. The single restriction is that the RTR nodes must be separate from the Tunnel nodes; that is, the Tunnel software and RTR must run on different machines. In general, the Tunnel is transparent to RTR. The TCP/IP routing tables should be configured to pass RTR traffic through the tunnel, allowing RTR to function without any special consideration. 1.2 Changes and Corrections o 14-1-113 Load balancing qualifier The qualifier /BALANCE was documented for use with the commands SET FACILITY and EXTEND FACILITY, but it was not implemented in prior versions of RTR V3. Implementation of this qualifier has been added with this release. o 14-1-128 Router quorum loss delayed In order to prevent temporary link loss causing unnecessary disruption to applications, a period of uncertainty (under 30 seconds) is now tolerated before a router becomes inquorate. o 14-1-129 Improved node inactivity tracking Improvements have been made to the algorithm tracking node inactivity so that the number of network messages required has been substantially reduced. General Information 1-3 General Information 1.2 Changes and Corrections o 14-1-191 Network link reconnection timers Network link reconnection timers on connecting nodes have been desychronised to reduce connection collisions. This has resulted in more rapid reconnection of lost network links, particularly between router and backend nodes. o 14-1-9 Improvements to the two-phase commit protocol Improvements have been made to the two-phase commit protocol to correct problems observed in shadowed enviroments where network links bounce. These include: transactions being delivered out of sequence to the servers in rare circumstances; transactions marked as uncertain being delivered twice to shadow secondary servers during recovery; improvements in the voting algorithm. o 14-7-387 If a spurious journal existed, using the RTR CREATE JOURNAL without /SUPERSEDE would erroneously create a new journal. o 14-7-674 [CTRL-Z] handling [CTRL-Z] now results in the standard platform specific behaviour, i.e. on UNIX it suspends the process, and on VMS it executes the command on the command line (if any) and then exits. o 14-7-874 Spurious log messages Failed connection attempts to remote DECnet nodes used to result in repeated messages being written to the RTR log file (the message text was concerning an XTI event requiring attention). These unnecessary messages have been removed. o 14-1-50 Improved handling of poor DNS server response Network links could become unstable if a Distributed Name Service (DNS) was configured improperly or the service was slow in responding. During extreme DNS latency, RTR on connected nodes could time-out the connections to nodes waiting for a DNS response. An 1-4 General Information General Information 1.2 Changes and Corrections internal node-name-to-id cache has been implemented which reduces RTR's exposure to degraded name servers. o 14-3-51 Prevent standby server becoming active if local- recovery fails A standby server could become active during network partitioning events resulting in two active servers for the same partition. RTR has been modified to prevent a server whose local-recovery fails when it is inquorate from becoming active. o 14-1-139 Shadow server available when partner reconnects A shadow server running alone after its partner was disconnected from the network could become temporarily unavailable upon reconnection. The remembering shadow server was being set to a waiting state while the rejoined node completed its recovery. This only occurred if the rejoining member was the preferred primary. The wait state has been eliminated and the server now remains in remembering state until its partner completes recovery. o 14-1-171 Recovered transactions were not forgotten Transactions recovered during shadow recovery were not "forgotten" if the remembering journal was directly accessible by the recovering node due to shared access to the journal disk drive. If the recovery operation was subsequently interrupted and restarted, these transactions could be re-recovered. o 14-1-110 Use of the /NODE qualifier with the CALL commands is now supported. o 14-1-134 Link drop when sending DECnet message larger than 64000 bytes RTR used to drop the network link if an attempt was made to send a message greater than 64000 bytes over a DECnet link. General Information 1-5 General Information 1.2 Changes and Corrections o 14-1-72 Frontend failback to preferred router The ability of a frontend to automatically reconnect to a preferred router node when it became available was not functioning. This feature now functions with Version 3 frontends connecting to Version 3 or Version 2 routers. (Note that there is currently no support for the router fail back function for V2 frontend nodes connecting to V3 routers.) o 14-1-75 Erroneous RTR-F-BRODISLIN on RTR CREATE FACILITY Previous versions of RTR would log an erroneous indication of the condition BRODISLIN on RTR CREATE FACILITY. o 14-1-83 Frontend load balancing scheme changed The implementation of frontend load balancing across the available set of router nodes is changed with this version of RTR. The old scheme where frontends were distributed evenly across all available routers is replaced by a scheme driven by the frontends and the subset of routers configured at a frontend. This scheme allows one or more subsets of the frontends to be automatically load balanced over subsets of the available routers, and requires that facility load balancing be specified on the frontends only. It is still valid to enable balancing on a router, but this is effective only for the old load balancing scheme where the connecting front ends are running earlier versions of RTR. o 14-1-86 Imposed Quorum Threshold Error In previous versions, when an imposed quorum threshold was defined, the quorum state was incorrectly calculated if the value for imposed quorum threshold was different to the number of reachable roles. o 14-3-12 Incorrect partition state shown during MONITOR PARTITION. The RTR MONITOR RECOVERY would sometimes show a stale partition state after a state transaction. 1-6 General Information General Information 1.2 Changes and Corrections o 14-3-4 rtr_receive_message() and threaded applications This only affects threaded application programs using RTR. The rtr_receive_message() call takes a parameter prcvchan that is used to specify the channels on which a receive is required. There is a slight change in the behaviour of the rtr_receive_message() call in cases where rtr_receive_message() is waiting for messages on a channel which is then closed by another thread in the program. The previous behaviour was that the rtr_receive_ message() call would hang indefinitely if the channel that it was waiting on was closed by another thread (and only if this was the only channel that was specified in the call to rtr_receive_message). This effectively blocked the thread that was executing the rtr_receive_ message() call. The new behaviour causes rtr_receive_message() to return with the error status RTR_STS_CHANOTOPE. This status is returned in a multi-threaded program when an rtr_receive_message() is outstanding on a channel that is closed by another thread. There are 3 distinct cases to consider: (i) Thread 1 is waiting in rtr_receive_message() having specified one or more channels in the prcvchan parameter. If one of the channels specified in this list is close by another thread, then the rtr_receive_ message() in thread 1 will return with the error status RTR_STS_CHANOTOPE. In this case, the application program should rebuild the list of open channels and call rtr_ receive_message with the updated list of channels. (ii) Thread 1 is waiting in rtr_receive_message with prcvchan set to RTR_ANYCHAN and the timeout parameter set to RTR_NO_TIMOUTMS. Thread 2 closes a currently open channel. In this case, there will be no indication in thread 1 that a channel has been closed, since the wild- card channel specification was used. The only exception in this case is if the close channel results in there General Information 1-7 General Information 1.2 Changes and Corrections being no more open channels. Then the rtr_receive_ message() call in thread 1 will return with the error status RTR_STS_CHANOTOPE. (iii) This is similiar to case (ii), except that a timeout parameter has been specified in the call to rtr_ receive_message(). If a channel is closed by another thread, resulting in there being no currently open channels in the program, then the rtr_receive_message() call will not return with an error status immediately. It will either timeout, or complete successfully if a channel is opened before the timeout expires. o 14-3-44 Error message %RTR-E-TXNOTACTIVE, transaction is not active The message RTR_STS_CHNOTACTIVE and RTR$_CHNOTACTIVE are now returned where TXNOTACTIVE was incorrectly used. o 14-5-7 Internal RTR error status sent to the operator log It was possible for the internal RTR error status JAM_ STS_JOUNOTAVA to be written to the operator log. The condition causing this to occur is now reported using the RTR status code RTR_STS_JOUNOTAVA. o 14-7-234 Previous versions would produce an error if quoted strings were used in remote commands. o 14-7-288 SHOW FACILITY/LINK erroneously showed nodes in roles that had been removed by a TRIM FACILITY command. o 14-7-375 The MONITOR ACTIVE on shadowed backend did not show any transactions. o 14-7-383 RTR MONITOR CHANNELS showed incorrect values RTR MONITOR CHANNELS showed incorrect values. o 14-7-418 Using the V2 interface, issuing a $COMMIT_TX() when the transaction had already been aborted could cause an application error. 1-8 General Information General Information 1.2 Changes and Corrections o 14-7-833 Infinite loop on journal scan A problem with the algorithm used to scan RTR backend nodes for journals belonging to nodes that were currently available could cause the RTR ACP process to enter a CPU-bound loop in certain multiple facility configurations. o 14-7-853 Alta Vista Internet Tunnel support By using the node name prefix "tunnel.", it is possible to configure rtr to accept a network connection from a particular remote node even if it is connecting via a Internet tunnel using an unknown pseudoadapter address. This allows stricter access control than the anonymous client feature where wild cards may be used when specifying a remote node name. If the prefix "tunnel." should conflict with an existing node name in your network, RTR will accept an alternate prefix string from the environment variable RTR_TUNNEL_ PREFIX. o 14-7-968 Connection not established if valid DECnet node used in tcp.[node] On a CREATE FACILITY command, if a node name is entered as tcp.[node] but [node] is only valid as a DECnet node name, facility creation succeeds, but no IP connection can be made since the IP address is unknown. This is corrected, in that a "%RTR-F-NODNOTKNO, Node not known, tcp.[node]" message is now returned. The system manager must ensure that all names used are correctly entered in the appropriate network name registry. o 14-7-982 Connection attempts will not try another router. A frontend attempting to connect to a router would never try another router in the facility if the first attempt timed out. Frontends will now attempt to connect to another configured router, if one is available. General Information 1-9 General Information 1.2 Changes and Corrections o 14-8-53 An RTR command can hang with two "comserv" processes on the system. This problem was due to a race condition which led to multiple competing command servers. Process locking has been implemented which prevents more than the one required command server from being created. o 14-7-1019 RTR now uses locks to prevent more than one process from (i) accessing a journal, (ii) starting RTR or (iii) starting a comserver process, and (iv) issuing commands affecting RTR entities simultaneously. Previously it was the operator's responsibility to stop RTR while creating or modifying a journal, to not issue more than one command by the same user at the same time, to not start RTR more than once at the same time, and to not issue more than one command affecting journals, facilities or other RTR entities at the same time. (On DIGITAL UNIX platform with TruCluster, DLM is used for locking. On DIGITAL UNIX without TruCluster and other UNIX platforms, locks are implemented in the /rtr directory). o 14-3-17 Correction to journal behaviour. RTR would occasionally fail in an attempt to flush records to a recently closed journal file. o 14-1-200 RTRACP failed evaluating state of removed link The ACP would on occasion fail or loop attempting to evaluate the traffic state of a link that had been removed as the result of a facility trim. o 14-7-147 Incorrect selection with SHOW /FACILITY and SHOW/ID The qualifiers /FACILITY and /IDENTIFICATION were not properly selecting objects for display when used with the following commands: SHOW CLIENT, SHOW SEGMENT, SHOW SERVER, SHOW PARTITION and SHOW TRANSACTION 1-10 General Information General Information 1.2 Changes and Corrections o 14-7-112 The MODIFY JOURNAL command is now implemented, but incorrectly also reports success if there is no journal on the specified device. RTR-S-JOURNALMOD should be taken to mean that any journals that have been found on that device have been modified. Please use the SHOW JOURNAL /FULL /FILE command to verify that journals have been modified as intended, noting that the disk name is not updated when journals are moved physically, or if they are indirectly located using symbolic links, virtual drives or mounts. 1.3 Known Problems o 14-1-121 RTR_F_SEN_RETURN_TO_SENDER flag The flag RTR_F_SEN_RETURN_TO_SENDER for the rtr_send_ to_server() call is wrongly shown in RTR HELP and the Application Programmer's Guide as RTR_F_SEN_RETTOSEND. o 14-1-194 Error message not displayed with MONITOR command If a monitor picture contains an error, for eaxmple DISPLAY NUMERIC "fac:invalid_name", then the MONITOR command fails in that the display of the monitor picture is inhibited, but no error message is displayed. o 14-7-202 TCP/IP configuration inconsistencies: Inconsistencies in your TCP/IP configuration can result in applications hanging when TCP/IP node names or addresses cannot be resolved correctly. In particular, the RTR ACP has been seen to stall on a router when a frontend node attempts to connect, but the TCP/IP address of frontend cannot be resolved on the router. If the RTR ACP stalls on the first connection attempt of a new frontend node, you should check for inconsistencies using nslookup, UCX SHOW HOST, or the equivalent command for your platform and TCP/IP package, both with the node name and the node address. You may also use the RTR MONITOR CONNECTS and RTR MONITOR ACCFAIL to view the status of RTR connections. General Information 1-11 General Information 1.3 Known Problems o 14-7-795 SHOW SERVER/FULL can show incorrect values The SHOW SERVER/FULL command does not show the correct value of the server partition key definition if the definition contains non-printable characters. o 14-7-579 Incorrect architecture type display This version of RTR incorrectly displays the architecture type of connected AIX and HP-UX nodes as type SPARC. This is a display issue only and does not affect operation in any way. o 14-9-111 Under normal operating conditions, broadcasts from a secondary shadow server are inhibited. This version of RTR does not inhibit broadcasts from secondary shadow servers when they are performing recovery. o 14-9-112 The reason code supplied on a call to rtr_ accept_tx() on a client channel is not passed back to the server, regardless of the outcome of the transaction. 1.4 Restrictions o 14-3-33 Allowed number of partitions The previous releases supported only up to 100 partitions per facility. The current release augments this to 500 but is not extendable beyond that. o 14-3-50 Maximum number of application processes limit When the process open file limit for RTR is reached, and a new RTR application is trying to connect, it will erroneously report "ACPNOTVIA, the RTR ACP is no longer a viable entity, restart RTR". In fact the ACP continues to operate with all previously connected processes, and only the new rejected process receives the message. This message should be interpreted as "ACPINSRES, The RTR ACP has insufficient resources." Please ensure that your system is configured with sufficient default per-process resources, or that 1-12 General Information General Information 1.4 Restrictions the ACP process is started with increased resource limits. Allow at least one open file for each additional application process, and at least one for each link. o 14-3-58 Shadow server reply checking not implemented. This release does not support reply checking, i.e. transactions that are replayed to another server which then sends a different reply are not aborted. Optional support for this feature will be provided in a future release of RTR. 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 failure when trying to stop the server. 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 V2 or V3 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 V3 API, the error status returned is RTR_STS_ INVCHANNEL. Under the V2 API, the error status returned is RTR$_INVALCH. Note that using RTR V2, even if the exit handler was declared before the first call to RTR, then a call to RTR within the exit handler could complete successfully. This is not the case using the RTR V2 (compatability) API under RTR V3. o 14-7-24 Transaction and message size limits The number of bytes in any application message (that is, a message sent with the rtr_send_to_server(), rtr_ reply_to_client() or rtr_broadcast_event() routines) is currently restricted to 64000. General Information 1-13 General Information 1.4 Restrictions The number of messages sent (that is, using rtr_send_ to_server()) in any single transaction is limited to 65534. There is no fixed limit on the number of replies (that is, sent with rtr_reply_to_client()) in any single transaction. o 14-9-106 The flags RTR_F_ACC_FORGET and RTR_F_REJ_RETRY are not supported. o 14-9-107 The API call rtr_set_info() is not implemented. o 14-9-108 This version of RTR does not support nested transactions. o 14-9-109 Journal files are limited to a size of 256 MBytes. o 14-9-110 RTR commands are limited to a total length of 1014 characters. 1.5 Miscellaneous 1.5.1 TCP Services File o RTR uses the TCP/IP port number 46000 for the network communication daemon rtr rtrd. On UNIX platforms, you should edit the file /etc /services to add the line rtracp 46000/tcp This informs the system administrator that port number 46000/tcp is reserved for RTR. (Note that the RTR daemon is started by RTRACP and not by inetd). 1.5.2 RTR Privileges RTR supports two levels of rights or privileges, rtroper and rtrinfo (on UNIX platforms), RTR$OPERATOR and RTR$INFO (on OpenVMS) and RtrOperator and RtrInfo on Windows NT. In general, rtroper or RTR$OPERATOR is required to issue any command that affect the running of the system, and rtrinfo or RTR$INFO is required for using monitor and display commands. 1-14 General Information General Information 1.5 Miscellaneous Setting RTR Privileges on UNIX Systems On UNIX machines RTR privileges are determined by the user id and group membership. For RTR users and operators, create the group rtroper and add RTR operators and users as appropriate. The root user has all privileges need to run RTR. Users in the group rtroper also have all privileges with respect to RTR, but may not have sufficient privilege to access resources used by RTR, such as shared memory or access to RTR files. The rtrinfo group is currently only used to allow applications to call rtr_request_info(). Depending on your UNIX system, see the addgroup, groupadd or mkgroup commands or the System Administration documentation for details on how to add new groups to your system. The rtrinfo group is currently only used to allow applications to call rtr_request_info() For other users, create the groups rtroper and rtrinfo Users who do not fall into the above categories, but are members of the rtrinfo group can only use RTR commands that display information (SHOW, MONITOR, call rtr_request_info, etc.). If the groups rtroper and rtrinfo are not defined, then all users automatically belongs to them. This means that there is no system management required for systems that do not need privilege checking. Setting RTR Privileges on OpenVMS Systems Create the Rights Identifiers RTR$OPERATOR and RTR$INFO if they do not already exist on your system, and assign them to users as appropriate. The RTR System Manager must have the RTR$OPERATOR identifier or the OPER privilege. 1.6 Interoperation with RTR Version 2 Using DECnet Reliable Transaction Router, Version 3.1D is interoperable with RTR Version 2.2D ECO3 or later when running on a platform that supports DECnet; that is OpenVMS, Digital UNIX, SUN, Windows 95 or Windows NT. General Information 1-15 General Information 1.6 Interoperation with RTR Version 2 Using DECnet Note that it is not possible to mix Version 2 and Version 3 routers and backends; all router and backend nodes in a facility must be either Version 2 or Version 3. Frontend nodes may be either Version 2 and Version 3. Defining the facility: o On RTR Version 2 node(s):- There are no special requirements for including a V3.x frontend in a V2 facility definition. Simply add the name of the frontend to the node-list specified by the /FRONTEND qualifier. o On RTR Version 3 node(s):- The default network transport for RTR Version 3.1D is TCP/IP. [1] Since RTR Version 2 uses DECnet (only), you must specify that your RTR Version 3 nodes use the DECnet protocol. This is achieved by prefixing the RTR V2 nodename with the string "dna.". For example, to specify the facility "FAX1" on the RTR V3 frontend "v3fe" for which the two V2 routers "VMS1" and "VMS2" are defined, use the following command:- RTR> create facility FAX1 /frontend=v3fe /router=(dna.VMS1,dna.VMS2) o Note that the facility name should contain only UPPER- CASE letters on all nodes. The use of the "dna." prefix assumes that the default network transport is TCP/IP. The default network transport can be changed to DECnet by setting the environment variable RTR_PREF_PROT. On Windows 95 and Windows NT, you can use one of the following statements in your AUTOEXEC.BAT. RTR_PREF_PROT=RTR_TCP_FIRST RTR_PREF_PROT=RTR_TCP_ONLY RTR_PREF_PROT=RTR_DNA_FIRST RTR_PREF_PROT=RTR_DNA_ONLY These set the choice of network transport to TCP/IP with fallback to DECnet, TCP/IP only, DECnet with fallback to TCP/IP or DECnet only. ____________________ [1] For Reliable Transaction Router Version 3.1D for OpenVMS, the preferred network transport can be either DECnet or TCP/IP. 1-16 General Information General Information 1.6 Interoperation with RTR Version 2 Using DECnet For Reliable Transaction Router Version 3.1D for OpenVMS, refer to Section 3.6 for further information)) Trouble-shooting:- If the RTR V3 frontend fails to connect with the RTR V2 router node, then you can make a basic check by executing a dlogin from the RTR V3 node to the OpenVMS router node. If this fails, consult your Network Manager. (For Digital UNIX machines, ensure that the DECnet library is installed as /usr/shlib/libdna.so). General Information 1-17 2 _________________________________________________________________ Digital UNIX Specific Information This chapter gives platform specific information for the Digital UNIX[R] implementation of Reliable Transaction Router, Version 3.1D. 2.1 New features o 14-7-788 RTR works with Digital UNIX TruClusters RTR supports Digital UNIX TruCluster configurations. Standby server configurations can be run in this environment. The required software is Digital TruCluster Production Server Software Version 1.4A, for which a minimum of Digital UNIX V4.0A is required. 2.2 Changes and Corrections There are no changes and corrections in this release that are specific to this platform. 2.3 Known Problems o 14-1-212 IVP failure and RTR journal creation failures On systems using the AdvFS file system for the root file system, the Installation Verification Procedure (IVP) fails without giving an explanatory message. The IVP can be run in this environment by making sure that (1) RTR is stopped, (2) no RTR journal is present, and (3) running the following command:- # RTR_SCAN_ALL=true setld -v RTRBASE314 Digital UNIX Specific Information 2-1 Digital UNIX Specific Information 2.3 Known Problems Note also that on systems using the AdvFS file system for the root file system, attempting to create an RTR journal without specifying a device gives the error "%RTR-F-NODEFDEV, no default device found for journal creation". This problem can be avoided by specifying the environment variable RTR_SCAN_ALL whenever RTR is started or journal commands are entered. 2.4 Restrictions o 14-1-88 CREATE JOURNAL on shared TruCluster disks Attempting to create journals on shared TruCluster disks gives the error message "%RTR-F-ILLDEVTYP, device /local@service is unsuitable for journals". The easiest way to direct RTR to scan and use a shared TruCluster disk is to create a symbolic link to it from a non-shared, local disk. The default disk / is the most convenient choice for a link to the first or only journal file system. This method is useful if there is one suitable local filesystem mounted for each required journal disk. The alternative is to set the environment variable RTR_ SCAN_ALL. The RTR command server will then allow journal creation on, (and the RTR ACP will scan) any mounted file systems that are not read-only or absolutely unsuitable in some other way. When using RTR_SCAN_ALL, you should check whether you have any NFS-mounted remote filesystems that might later become inaccessible, causing the RTR ACP or command server process to hang for the duration specified in the mount options. (By default RTR does not scan NFS or NFS3 disks.) There is a command available to root to obtain a list of services: /usr/sbin/asemgr -d -v. 2-2 Digital UNIX Specific Information Digital UNIX Specific Information 2.4 Restrictions o 14-5-23 Upgrading the Operating System When upgrading Digital UNIX from V3.2 to V4.0 or greater, it will be necessary to de-install RTR on the existing system and then re-install it after the Operating System upgrade. The same is also true if you downgrade from V4.0 back to V3.2. Digital UNIX Specific Information 2-3 3 _________________________________________________________________ OpenVMS Specific Information This chapter gives platform specific information for the OpenVMS implementation of Reliable Transaction Router, Version 3.1D. 3.1 New features There are no new features in this release that are specific to this platform. 3.2 Changes and Corrections o 14-1-11 RTR daemon memory leak caused dump The RTR daemon process used to consume memory with each incoming connection. o 14-1-163 V2 API $DEQ() issued after a $VOTE Server $DEQ()s issued after a $VOTE, but before the $VOTE completes were being inappropriately completed with the status NONTRMDEQCOM, i.e. as if they belonged to the previous transaction. o 14-1-170 Process counters were not being incremented The process counters rtr_api_wakeup_entries/exits were not incremented. This gave an incorrect indication of the number of wakeup calls on the MONITOR CALLS picture. o 14-1-38 V2 application started before RTR caused access violation Starting an RTR V2 application before starting RTR would cause the application to fail with an access violation. OpenVMS Specific Information 3-1 OpenVMS Specific Information 3.2 Changes and Corrections o 14-1-70 SET LOG /OPERATOR was not implemented The command SET LOG /OPERATOR is now implemented. Previous releases of RTR Version 3 on OpenVMS lacked this function. o 14-3-13 V2 API Errors Errors in the emulation of the V2 API have been corrected. When processing an "accepted" message, RTR V3 assumed that the only active call in a client would be a $COMMIT_TX(), and incorrectly tried to complete an outstanding $DEQ_TX() with the "accepted" message. RTR now correctly generates the following conditions, as appropriate: NONTMRDEQCOM NONTRMSRVCOM NONDEQMSGCOM o 14-3-35 PRTBEGIN was unable to identify image path name The PRTBEGIN entry in the RTR log file would be unable to identify the image path name of the starting partition if the server process was started in a UIC group different to that of the RTR control process. o 14-3-47 BYTLM default The default amount for BYTLM (/BYTLM qualifier) on the START RTR command has been raised to 1,000,000. o 14-5-5 Remote commands with no login permission on remote node Attempting to execute a remote command with no login permission on the remote node resulted in output containing repeated unhelpful messages: "%DCL-W- UNDFIL, file has not been opened by DCL - check logical name". These messages have been eliminated; only the appropriate error is now shown. 3-2 OpenVMS Specific Information OpenVMS Specific Information 3.2 Changes and Corrections o 14-7-419 V2 API $ENQ_TX to send broadcasts causes application crash Using V2 verb $ENQ_TX to send broadcasts could have resulted in an application crash inside the RTR shareable image. o 14-7-511 Specifying a timeout value on $DCL_TX_PRC no longer causes spurious errors. o 14-7-548 The RTR$M_INHNOSRVWT feature of the V2 verb $DCL_TX_PRC() is now implemented. o 14-7-551 Sending a broadcast sometimes caused the RTR ACP to crash. o 14-7-561 The SET ENVIRONMENT /CLUSTER command would only set the environment to the local node, even in a cluster configuration. The environment is now set to all nodes in the cluster. o 14-7-573 DECdtm is now supported when using the Version 2 interface. 1. Three new monitor screens are available which replace MONITOR DTINFO and MONITOR DDTM. MONITOR DTX shows status of high-level distributed transaction calls made internally by RTR and the duration of each call. MONITOR DDTM shows the status of the DTM calls made by RTR and the duration of each call. MONITOR DTXREC shows the status of the DTM calls made by RTR during transaction recovery operations. 2. Default DTM transactions are not supported in this release of RTR. Applications must therefore explicitly pass the returned transaction id to the DTM compliant database manager even if the $DCL_TX_PRC flag RTR$M_ NONDEFTID has not been specified. 3. The statement in the V2.2D Release Notes (4a) that "It will never receive a RTR$_STARTTXREC status" is not valid for servers which specify the shadow OpenVMS Specific Information 3-3 OpenVMS Specific Information 3.2 Changes and Corrections option. Shadow servers which receive an RTR$_STARTTXREC indication should check the database according to normal RTR conventions to ensure that the transaction has not already been committed to the database. Please see the RTR Version 2 documentation for further information. o 14-7-671 Server may receive a vote request after transaction abort after link break. Using the V2 API, a server process could get a vote message after a transaction has been aborted, and subsequently gets TXNOTACTIVE error message after calling VOTE_TX(). o 14-7-678 Journal is locked by another user Journal file creation could sometimes fail with the message "%RTR-F-JOUINUSE, journal is locked by another user". o 14-7-708 Transaction replies delivered to the next transaction. When using the V2 API, if an application did not $DEQ() all available replies before issuing a $COMMIT, the remaining replies were delivered at the start of the next transaction. This error has been corrected. The remaining replies are discarded, and the requester receives the NONDEQMSGCOM status, indicating that replies from the server were available, but not $DEQ'ed. o 14-7-757 Spurious error message on installation A spurious error message on installation on OpenVMS VAX V6.1 %INSTALL-W-NOGBLSEC, ... CMA$OPEN_RTL.EXE has been removed. 3-4 OpenVMS Specific Information OpenVMS Specific Information 3.2 Changes and Corrections o 14-7-809 RTR$DEFAULT_MESSAGE is not supplied When using the V2 verb $ENQ_TX() from the RTR command line, the default value for the message parameter (RTR$DEFAULT_MESSAGE) was not correctly identified and processed. o 14-7-857 MONITOR /ID qualifier did not accept hexadecimal id's. MONITOR /IDENTIFICATION= qualifier did not accept hexadecimal process-id's. Both decimal and hexadecimal qualifier values are now accepted, and passed through to the destination node. If that node is OpenVMS, the process id is interpreted as hexadecimal. o 14-7-883 Broadcast event ASTs not delivered in AST mode Broadcast event ASTs were not always delivered in AST mode to users of the V2 programming API. o 14-7-900 Servers using V2 API stop processing transactions after reject. An error that would prevent servers from processing further transactions following receipt of a reject transaction message has been corrected. o 14-7-950 Completion routines called even if the service failed Completion routines to $ABORT_TX() and $ENQ_TX() were being called even if the service failed. Also, a successful call to $ABORT_TX did not result in the TID field of the TXSB being written. o 14-7-963 When using the V2 API, closing a channel did not cause an outstanding $DEQ_TX to complete. OpenVMS Specific Information 3-5 OpenVMS Specific Information 3.3 Known Problems 3.3 Known Problems o 14-1-106 RTRACP hang on Create Facility Creating a facility can cause the RTR ACP to hang when RTR is scanning for journals and a disk is doing a shadow merge operation. o 14-3-33 RTR SET FACILITY/MAX_PARTITION=nnn The Version 2 command RTR SET FACILITY/MAX_PARTITION=nnn is not supported on Version 3. The current release supports up to a maximum of 500 partitions. 3.4 Restrictions o 14-1-53 DECdtm and possible duplicate transactions DECdtm enabled servers should check for possible duplicate transactions flagged by RTR with the rtr_ mt_uncertain indicator. While the use of DECdtm allows RTR to check for duplicate transactions in most cases, recovery of duplicate transactions remembered on a shadow node cannot currently be detected. o 14-7-1026 Increased AST Process Quota Usage It may be necessary to increase process ASTLM quotas after upgrading from RTR V2 to V3. If your application receives a large number of messages in a relatively small time period, and you find that RTR calls are failing to complete, raise the ASTLM substantially. For example, if your process receives several hundred broadcast in a few seconds, raise ASTLM by several hundred. o 14-9-100 The minimum OpenVMS version supported is OpenVMS 6.1 for both VAX and Alpha architectures. RTR is compatible with OpenVMS 7.0 and 7.1. o 14-9-101 This release supports TCP/IP, and was designed for UCX. While UCX is recommended, RTR has been shown to also work with TCPware from Process Software. 3-6 OpenVMS Specific Information OpenVMS Specific Information 3.4 Restrictions o 14-9-102 The recommended version of DECnet-Plus (formerly DECnet/OSI) for those wishing to use the DECnet Phase V transport is 6.3-ECO7 or higher. o 14-9-103 The RTR Version 2 system services $GET_TXI and $GET_TXIW are not implemented. o 14-9-104 The RTR Version 2 commands START REMOTE_ CLIENT_HANDLER and STOP REMOTE_CLIENT_HANDLER are not implemented. 3.5 Reliable Transaction Router, Version 3.1D Installation Information o If you are installing Reliable Transaction Router on V6.1 of OpenVMS VAX, it is necessary to check that OpenVMS has been properly registered with PCSI before running the RTR installation. To confirm this, use the command:- $ product show product vms If VMS is not registered, then register it now with the command: $ product register product vms/version=v6.1/source=sys$update Failure to perform this step may cause the installation to fail with an error message similar to this: %PCSI-E-PARUDF, the file [SYSHLP]HELPLIB.HLB has not been provided by a previous Install or Register operation - module update skipped o The PCSI installation procedure has an extra option that is not described in the Reliable Transaction Router Version 3.1D, Installation Guide. The option gives the choice of whether to run the RTR Installation Verification Procedure (IVP):- Do you want to run the RTR IVP [YES] It is recommended to run the IVP, but RTR and applications that use RTR should always be shut down properly before doing so. OpenVMS Specific Information 3-7 OpenVMS Specific Information 3.5 Reliable Transaction Router, Version 3.1D Installation Information o The Installation Verification Procedure (IVP) will complete successfully if at least one of the supported network protocols (DECnet or TCP/IP) is installed and active. o The standard monitor picture files provided with this kit are copied to SYS$COMMON:[RTR] at installation time. o If you wish to install the ODBC Over RTR (OOR) option, you must have Oracle7 installed on your system. The minimum version for OpenVMS VAX installations is Oracle7 V7.0 and for OpenVMS Alpha installations it is Oracle7 V7.1. 3.6 Network Protocol Selection o The default network transport protocol is DECnet. You may change the default to TCP/IP by removing this line from RTR$STARTUP.COM: $ DEFINE/SYSTEM RTR_PREF_PROT RTR_DNA_FIRST If you are using TCP/IP as the default, you will need to use the node-name prefix "dna." to override the default if you specifically want DECnet transport to be used. This is required, for example, when connecting to Version 2.2D ECO6 nodes as described in Section 1.6 of these Notes, and Section 2.7 of the Reliable Transaction Router Version 3.1D, System Manager's Manual. If you are using DECnet as the default, you will need to use the node-name prefix "tcp." to connect to other nodes using TCP/IP transport. If the value of the logical RTR_PREF_PROT is changed, the new value takes effect only after RTR has been restarted. o Reliable Transaction Router Version 3.1D for OpenVMS can use either DIGITAL TCP/IP Services for OpenVMS or TCPware Version 5.1 as the TCP/IP transport layer. 3-8 OpenVMS Specific Information OpenVMS Specific Information 3.7 Problem Diagnosis 3.7 Problem Diagnosis o RTR ACP process dumps or core files can be directed to a directory specified though the environment variable RTR$DUMP_DIRECTORY or RTR_DUMP_DIRECTORY. Note that the RTR$DUMP_DIRECTORY equivalence string should not contain any logical names not visible to the RTR ACP process, and that SYS$LOGIN is invalid for the RTR ACP. o In the event of an RTR ACP failure, the file RTR_ ERROR.LOG is generated and written to RTR$DUMP_ DIRECTORY. This file is helpful in diagnosing RTR problems, and should be included when reporting RTR problems to DIGITAL. o It can be useful to know that on OpenVMS, Reliable Transaction Router process names are RTRACP, RTRCSV and RTRD. These are the RTR ACP, the RTR Command Server and RTR Network Daemon, respectively. (Note: the RTRD process is present only on systems where TCP/IP is installed.) If RTR is running in group mode, then the process names for the RTR ACP and Command Server are RTRACP_ and RTRCSV_ respectively. 3.8 Linking RTR Applications To link RTR application programs, include the following line in the linker options file: SYS$SHARE:LIBRTR/SHARE If you are linking RTR Version 2 applications, also see Section 3.9. 3.9 Compatibility of Version 2.2D ECO6 Applications Running on Version 3.1D o Linking Version 2 Applications. OpenVMS Specific Information 3-9 OpenVMS Specific Information 3.9 Compatibility of Version 2.2D ECO6 Applications Running on Version 3.1D Existing RTR Version 2 applications will run if they have been linked against RTRSHR. (RTRSHR has been superseded by LIBRTR.EXE. Existing RTR Version 2 application executables will run without relinking since RTR$STARTUP.COM defines RTRSHR as a logical name that points to LIBRTR.EXE.) However, as RTRSHR.EXE is no longer distributed you are advised to change the linker options file referencing RTRSHR (that is, changing SYS$SHARE:RTRSHR/SHARE to SYS$SHARE:LIBRTR/SHARE). After making this change, you may remove SYS$SHARE:RTRSHR.EXE from your system. If you are linking on a system where RTR Version 2 was never installed (that is, no RTRSHR.EXE is present) the linker options described above are always required. o Under Reliable Transaction Router Version 2.2D ECO6, it was possible to pass an event status as a parameter when calling $ENQ with the RTR$M_BROADCAST flag set. This broadcast $ENQ would be delivered to the recipient with the event status stored in the RTR$L_EVT_STATUS field of the RTR$_EVT data structure passed as parameter to the broadcast AST. When running Version 2.2D ECO6 applications on Version 3.1D, the event status is not passed from sender to receiver. All USER events received by a Version 2.2D ECO6 application will have the event status parameter set to 0: - if the sender is a V3 application, then there is no event status - if the sender is a V2 application then the event status is not passed on by RTR Version 3.1D o RTR Version 2.2D ECO6 returned the error status RTR$_ INVALCH if an operation was attempted using a channel number that was invalid (e.g. 0), and RTR$_CHNOTALLOC for (potentially) valid channel numbers that have not actually been declared. RTR Version 3.1D makes no such distinction and always returns RTR$_CHNOTALLOC. o If an RTR STOP RTR/ABORT is issued using RTR Version 2.2D ECO6, RTR executes an AST in the context of any applications with an RTR channel open which causes the application to exit with the status RTR$_RTRWASSTO. 3-10 OpenVMS Specific Information OpenVMS Specific Information Compatibility of Version 2.2D ECO6 Applications Running on Version 3.1D In RTR Version 3.1D, there is no difference in behaviour between the commands STOP RTR and STOP RTR/ABORT. If either of these commands is entered, RTR is always stopped. Any application with an RTR channel open will receive an error status on any RTR operation in progress on that channel, but the application will not be terminated. It is up to the application to handle the error correctly (the error status returned in this case is RTR$_NOACP, the same status that is returned if the RTR ACP fails for any reason). OpenVMS Specific Information 3-11 4 _________________________________________________________________ AIX Specific Information This chapter gives platform specific information for the AIX[TM] implementation of Reliable Transaction Router, Version 3.1D. 4.1 New features There are no new features in this release that are specific to this platform. 4.2 Changes and Corrections There are no changes and corrections in this release that are specific to this platform. 4.3 Known Problems There are no known problems in this release that are specific to this platform. 4.4 Restrictions There are no restrictions in this release that are specific to this platform. AIX Specific Information 4-1 5 _________________________________________________________________ SunOS Specific Information This chapter gives platform specific information for the SunOS[TM] implementation of Reliable Transaction Router, Version 3.1D. 5.1 New features There are no new features in this release that are specific to this platform. 5.2 Changes and Corrections o 14-3-42 Limited open file descriptors for stdio Solaris 2.6 and lower operating system versions have a restriction of only 256 open file descriptors for stdio. This restriction is now worked around. Also, RTR now fails gracefully if the journal scan cannot be performed because no more file descriptors are available. 5.3 Known Problems o 14-1-120 File descriptor restrictions on SUN/Solaris The default setting for the maximum number of open file descriptors on Solaris is low, usually 64, and RTR raises this to 256. If there are a large number of server/client processes connecting to the RTR ACP on a Solaris node this file descriptor limit is very quickly used up by the IPC socket connections. Once this limit is reached further attempts to open a file fails. This can result in the RTR ACP crashing when it tries to open a journal file or perform other kinds of file open SunOS Specific Information 5-1 SunOS Specific Information 5.3 Known Problems operations. Also, additional application process will also not be able start once this limit is reached. This limit can be increased using the limit command. However, even if this limit is increased, there is a fixed limit for stdio which is 0..255. This means that all fopen calls need to have free file descriptors below the 256 range for the call to succeed. This release of RTR uses file descriptors for socket communications starting from a default value of 50, leaving the range below 50 free for stdio calls. This default value can be changed at RTR startup by setting the environment variable RTR_OFFSET_FILE_DESC to the value required. 5.4 Restrictions o 14-1-6 MONITOR CONNECTS and DECnet (SUNLink DNI) RTR gives a reason code when explicitily rejecting a network connection from another node. The reason text is displayed in the MONITOR CONNECTS picture, and is useful in diagnosing connectivity and configuration problems. The reject reason is not available when attempting connections using DECnet on SUN (SUNLink DNI) as a network transport. As a result, this platform incorrectly reports an explicit rejection by a remote node as having been refused. Use the MONITOR ACCFAIL picture on the target of the connection to obtain a correct indication of the reason for the connect rejection. o 14-5-23 Upgrading the Operating System When upgrading SunOS from V5.4 to V5.5 or greater, it will be necessary to de-install RTR on the existing system, and then re-install it after the Operating System upgrade. The same is also true if you downgrade from V5.5 back to V5.4. o 14-4-5 This version of RTR does not run with Solaris 2.6 (SunOS 5.6). 5-2 SunOS Specific Information SunOS Specific Information 5.5 Miscellaneous 5.5 Miscellaneous This section describes some issues concerning SunOS relevant to Reliable Transaction Router, Version 3.1D. o DECnet library location: In order to use DECnet on SunOS, it is necessary that the file libdni.so (the shared object library for DECnet) is installed in the directory /usr/lib. (After installation, this file is normally found in the directory /opt/SUNWconn/dni/lib/). For example, the following commands will create the necessary link to the library file: ln -s /opt/SUNWconn/dni/lib/libdni.so /usr/lib/libdni.so chown bin /usr/lib/libdni.so chgrp bin /usr/lib/libdni.so o Solaris 2.4 operating system patch Users of Solaris 2.4 are strongly advised to install the operating system patch 101945-27 to ensure the proper operation of RTR. This patch is available from SunSoft Services and can be accessed via the World Wide Web at http://access1.sun.com/. This patch makes a number of corrections to the operating system in the areas of sockets and networking in general. o Shared memory segments: The number of shared memory segments that a process may attach to is limited on Solaris to six. This limits the number of application processes that can use RTR to about 50. This value can be changed by adding the following line to the /etc/system file: set shmsys:shminfo_shmseg=s If you plan to run more that six RTR application processes, you should set s as shown:- s >= (p / 10) + 5 Where p is the number of RTR application processes that can run. The system must be rebooted for the new value to come into effect. SunOS Specific Information 5-3 SunOS Specific Information 5.5 Miscellaneous Note that the SUN documentation that describes how to alter this default contains errors - shmsys:shminfo_ shmseg is incorrectly described as "semsys:seminfo_ shmseg". 5-4 SunOS Specific Information 6 _________________________________________________________________ HP-UX Specific Information This chapter gives platform specific information for the HP-UX[R] implementation of Reliable Transaction Router, Version 3.1D. 6.1 New features There are no new features in this release that are specific to this platform. 6.2 Changes and Corrections There are no changes and corrections in this release that are specific to this platform. 6.3 Known Problems There are no known problems in this release that are specific to this platform. 6.4 Restrictions o 14-7-394 "Gold" key not supported The "gold" key (PF1 on VT keyboards) is not supported on an HP-UX xterm. HP-UX Specific Information 6-1 7 _________________________________________________________________ Windows NT Specific Information This chapter gives platform specific information for Reliable Transaction Router Version 3.1D for Windows NT and Windows 95 when used on Windows NT. ________________________ Note ________________________ Interoperation with RTR Version 2 is supported when using Reliable Transaction Router Version 2.2D ECO3 or later. See Section 1.6 for additional information. ______________________________________________________ 7.1 New features o 14-7-789 Windows NT Digital Clusters now supported RTR configurations are supported in Windows NT cluster environments; the cluster platform currently supported is Digital Clusters for Windows NT Version 1.1 on Windows NT4.0. RTR supports the use of standby configurations in this environment. In terms of NT clusters, RTR is an application and the RTR journals are the database resource which can fail over between the NT cluster servers. The following requirements must be observed: 1) The RTR journal for both NT servers must be located on the same disk on the SCSI bus that is shared between the two NT cluster servers. The RTR registry entry for the journal must be set to the same value on both server nodes. Furthermore, the registry entry should specify Windows NT Specific Information 7-1 Windows NT Specific Information 7.1 New features the journal disk using the path qualified by the cluster name. For example, if the cluster name is ALPHACLUSTER, and the journal disk has the cluster share name DISK1, then the RTR journal registry entry should be entered as: \\ALPHACLUSTER\DISK1\RTRJNL (This can be modified using the Registry Editor.) 2) If the journal file is specified as above on a shared SCSI disk, then RTR can operate with standby server functionality. If the journal is not located on a shared disk in a Windows NT cluster configuration, then RTR behaves as a standalone RTR node and no use is made of cluster functionality. 3) RTR must be configured as both a backend and a router role on the Windows NT cluster server nodes if the journal file is located on a shared SCSI disk. 4) In a Windows NT cluster configuration, the RTR directory must not be located on a shared SCSI disk. 5) The failover group containing the disk share on which the journal files are located must have no failback policy enabled. That is, if the failover group fails over to the secondary cluster node due to primary server outage, then the group must not failback to the primary node once the primary node is available again. 6) While RTR facilities have been defined in a cluster configuration, then the failover group with the journal device must not be manually failed over to the other cluster server (by the cluster administrator). Failover should only occur on the discretion of the cluster failover manager software. 7) RTR creates lock files in the RTR directory and the journal directory during normal operation. These are of the form N*.LCK or N*.BLK, and C*.LCK or C*.BLK. These files may be left in these directories after RTR has been stopped, but they will be reused once RTR is 7-2 Windows NT Specific Information Windows NT Specific Information 7.1 New features started again. There is no real need for a daemon to purge these files at system boot time. o 14-5-4 RTR for Windows NT supports DECnet in the following configuration: Windows NT V4.0 with Pathworks 32 V7.0A The following is extracted from the release notes for Pathworks 32 V7.0A, and applies when using RTR: DECnet Listening Socket When a DECnet application halts abnormally, the PATHWORKS32 DECnet layer might not properly release the application's DECnet Listening Socket. If this happens, the DECnet application may fail to run the next time a user attempts to start it. For example, this problem could affect RTR running over DECnet. Assuming that RTR halted abnormally and DECnet did not properly release RTR's DECnet Listening Socket, RTR may fail to establish any DECnet links with other nodes the next time it is run. If you encounter this problem with RTR over DECnet, or in any of your DECnet applications, follow these steps: 1. Check for unreleased DECnet Listening Sockets by issuing the following NCP command in a DOS box: NCP> show known links 2. Use the following NCP command to release any links that are listed with the name RTR$username (where username is the user name you used to log in to Windows 95) and RTR$ACP. NCP> set link n state off Once the links are cleared, the DECnet applications should work properly. Windows NT Specific Information 7-3 Windows NT Specific Information 7.2 Changes and Corrections 7.2 Changes and Corrections o 14-1-101 Journal directory location and management The default journal device is no longer taken from the JOURNAL item in the Windows registry, but is calculated as the first fixed drive in the system, or if this cannot be determined then as "C:". The registry key HKEY_LOCAL_MACHINE\SOFTWARE\ DigitalEquipmentCorporation\RTR\Journal is only used for existing installations, and journals will still be found in the location it points to. New journals will be created under [device]:\rtrjnl\[group], as on other platforms. Once a new journal is created using the new software, the registry entry may be removed. o 14-3-31 Exception condition "NET:API no sockets available" The exception condition "NET:API no sockets available" could occur if more than approximately 100 client applications were started. The maximum for the sum of the number of connected client applications and network links has been raised to 1000. o 14-7-526 Windows NT frontends could not connect to RTR Version 2.x routers; this is now supported. o 14-7-975 Data checksums RTR can optionally perform checksum calculations on data packets passed over network links. This can help in diagnosing errors where faulty network components are suspected. By default, checksum calculations are off, except for DECnet links on Windows NT. They may be controlled on a per node and protocol basis by defining the following environment variables: RTR_NODE_CHECKSUM_TCP_STATE RTR_NODE_CHECKSUM_DNA_STATE 7-4 Windows NT Specific Information Windows NT Specific Information 7.2 Changes and Corrections A value of one for either of these variables will cause the node to start calculating and sending checksum values with each packet send over a network 7.3 Known Problems o 14-3-55 IP link reconnect and RTRACP allocating all available memory. If the TCP/IP links to a backend are aborted and an attempt is made to reconnect in a short period of time then the RTRACP process on the NT system appears to allocate all available memory. 7.4 Restrictions o 14-5-10 Using Dr Watson In the event that a problem is discovered that causes RTR to crash, a process dump file can be generated by enabling the Dr Watson post mortem crash analyser. This is done by entering the MS-DOS command "%WINDIR%\drwtsn32 -i". The files that are created are %WINDIR%\DRWTSN32.LOG and %WINDIR%\USER.DMP. These files should be included with any problem report submitted to RTR Engineering in the event of an RTR crash, along with the RTR dump file (RTR_[n].DMP) and the RTR log file. o 14-9-105 Remote commands and remote shell daemon Remote commands may be sent from Windows NT nodes, and Windows NT nodes may be used in SET ENVIRONMENT commands and /NODE= qualifiers. This feature requires the installation of a remote shell (rsh) daemon. The remote shell daemon from Ataman(TM) Software Inc. is recommended. Visit Ataman's web site (http:/ /www.ataman.com) for further information. Windows NT Specific Information 7-5 8 _________________________________________________________________ Windows 95 Specific Information This chapter gives platform specific information for Reliable Transaction Router Version 3.1D for Windows NT and Windows 95 when used on Windows 95. Installation and operating procedures are the same when used on Windows 95 or Windows NT, unless stated otherwise. Users migrating from Reliable Transaction Router, Version 3.1D Client for Windows 3.1 should note the following:- o Client applications developed using the RTR for Windows V1.1 API can be run under Windows 95 or Windows NT. These applications need to be recompiled and relinked in the new environment. o VBX support is being discontinued. Some existing Visual Basic applications may run, but this is not supported. o A new 32-bit version of the ODBC driver for RTR is included as part of the kit. Using the ODBC driver requires RTR for OpenVMS V3.1D or later and ORACLE[R] on the backend node. o The recommended resources are greater on Windows 95 compared to Windows 3.1. 16MB RAM is the suggested minimum. 8.1 New features o 14-5-4 RTR for Windows 95 supports DECnet in the following configurations: 1) Windows 95 with Pathworks V1.0, DECnet not supported (TCP only) Windows 95 Specific Information 8-1 Windows 95 Specific Information 8.1 New features 2) Windows 95 with Pathworks 32 V7.0A, Winsock V1.1, DECnet not supported (TCP only) 3) Windows 95 with Pathworks 32 V7.0A, Winsock V2, DECnet supported Note that Winsock V2 must be additionally installed if you want to use RTR over DECnet on Windows 95 (the Winsock V2 executables are distributed with the Pathworks V7.0A kit). The following is extracted from the release notes for Pathworks 32 V7.0A, and applies when using RTR: DECnet Listening Socket When a DECnet application halts abnormally, the PATHWORKS32 DECnet layer might not properly release the application's DECnet Listening Socket. If this happens, the DECnet application may fail to run the next time a user attempts to start it. For example, this problem could affect RTR running over DECnet. Assuming that RTR halted abnormally and DECnet did not properly release RTR's DECnet Listening Socket, RTR may fail to establish any DECnet links with other nodes the next time it is run. If you encounter this problem with RTR over DECnet, or in any of your DECnet applications, follow these steps: 1. Check for unreleased DECnet Listening Sockets by issuing the following NCP command in a DOS box: NCP> show known links 2. Use the following NCP command to release any links that are listed with the name RTR$username (where username is the user name you used to log in to Windows 95) and RTR$ACP. NCP> set link n state off 8-2 Windows 95 Specific Information Windows 95 Specific Information 8.1 New features Once the links are cleared, the DECnet applications should work properly. 8.2 Changes and Corrections o 14-1-101 Journal directory location and management The default journal device is no longer taken from the JOURNAL item in the Windows registry, but is calculated as the first fixed drive in the system, or if this cannot be determined then as "C:". The registry key HKEY_LOCAL_MACHINE\SOFTWARE\ DigitalEquipmentCorporation\RTR\Journal is only used for existing installations, and journals will still be found in the location it points to. New journals will be created under [device]:\rtrjnl\[group], as on other platforms. Once a new journal is created using the new software, the registry entry may be removed. o 14-1-188 Reduced occurrence of ERRACCNOD errors Improved synchronisation between the command server and the CLI gives less instances of RTR commands failing with the condition ERRACCNOD. o 14-3-45 Number of client applications increased The number of client applications supported by RTR on a Windows system has been increased from approximately 60 to 1024. o 14-7-975 Data checksums RTR can optionally perform checksum calculations on data packets passed over network links. This can help in diagnosing errors where faulty network components are suspected. By default, checksum calculations are off, except for DECnet links on Windows NT. They may be controlled on a per node and protocol basis by defining the following environment variables: RTR_NODE_CHECKSUM_TCP_STATE Windows 95 Specific Information 8-3 Windows 95 Specific Information 8.2 Changes and Corrections RTR_NODE_CHECKSUM_DNA_STATE A value of one for either of these variables will cause the node to start calculating and sending checksum values with each packet send over a network 8.3 Known Problems There are no known problems in this release that are specific to this platform. 8.4 Restrictions o 14-1-160 TCP/IP protocol must be operational RTR for Windows 95 requires TCP/IP protocol to be operational, since TCP/IP is used for inter-process communication between the RTR ACP and the application. If TCP/IP is removed using the Network applet in the Control Panel (for example, if DECnet has been installed), then trying to start RTR will result in a Winsock error. o 14-7-810 Maximum number of DECnet links The maximum number of DECnet links that can be active at any time is defined by the DECnet executor and can be displayed using the command: C:> ncp show executor characteristics This value is 8 by default when Pathworks is installed. This means that on a default installation, RTR cannot have links to more than six other DECnet nodes configured in one or more facilities (the seventh link is reserved for the listener socket, and the eigth for the command server). If you will be configuring RTR on your Windows 95 system such that it requires links to more than six nodes at any time, then this executor parameter will need to be increased. 8-4 Windows 95 Specific Information Windows 95 Specific Information 8.4 Restrictions o 14-7-894 DECnet and Solaris backend not supported DECnet transport is not supported between Windows 95 or Windows NT as a frontend, and Solaris as a backend. o 14-1-50 Use of HOST file recommended Microsoft Windows installations should configure TCP with redundant DNS or WINS servers, or make entries for all systems participating in an RTR configuration in the HOSTS file on all systems. Windows sites should not rely on broadcast name resolution, as TCP sockets based applications such as RTR may block for prolonged periods whilst making a name lookup to an unavailable host. This may result in dropped network links, with consequent interruption to transaction processing activity. o 14-9-105 Remote commands and remote shell daemon Remote commands may be sent from Windows 95 nodes, and Windows 95 nodes may be used in SET ENVIRONMENT commands and /NODE= qualifiers. This feature requires the installation of a remote shell (rsh) daemon. The remote shell daemon from Ataman(TM) Software Inc. is recommended. Visit Ataman's web site (http:/ /www.ataman.com) for further information. 8.5 Restrictions for Applications Written for RTR Version 1.1 for DOS/Windows Existing applications written for RTR Version 1.1 for DOS /Windows API can be used with Reliable Transaction Router Version 3.1D Client for Windows 3.1 with the following restrictions: o The first call to the RTR API must be rtr_dcl_tx_prc[w]. Reliable Transaction Router, Version 3.1D on the PC uses this call to determine that the application is a Version 1.1 application. One cannot, for example, call rtr_error_text() before rtr_dcl_tx_prc[w](), since RTR at that point has not determined whether the Version 3 or Version 1.1 API is being used. Windows 95 Specific Information 8-5 Windows 95 Specific Information 8.5 Restrictions for Applications Written for RTR Version 1.1 for DOS/Windows o Note that the definitions of the functions rtr_error_ text() and rtr_start_tx() have been redefined for RTR Version 3. The verbs were formerly in use in the Reliable Transaction Router Version 1.1 for MS-DOS and Windows product. Since the Version 3 functions return different data types, an option is provided to control the use of Version 2 and Version 3 function prototypes in rtr.h. As delivered, rtr.h is compatible with a program written to the RTR V3 API. If you recompile programs written to the RTR V2 API, calls to rtr_error_text() will result in the following warning message being generated: . . . : warning C4047: '=' : different levels of indirection. In most cases, this warning may be ignored. To enforce strict V2 API type and argument checking, you may add the following line to your source module before including rtr.h. #define RTR_STRICT_V2API Alternatively, you may add this line to rtr.h, or retain a copy of rtr.h from the V1.1 product. (Be careful when reinstalling RTR Version 3 that this variant does not get replaced.) To enforce strict V3 API type and argument checking, you may add the following line to your source module before including rtr.h. #define RTR_STRICT_V3API 8-6 Windows 95 Specific Information A _________________________________________________________________ RTR Monitor Pictures This appendix describes some features that can aid in debugging RTR and application problems. A.1 New Monitor Pictures o New RTR monitor file, MONITOR ACTIVE The new monitor picture MONITOR ACTIVE shows active transactions, and transaction starts and completions by application process. An example is shown below. % rtr monitor active ACTIVE TRANSACTIONS BY PROCESS 19:32:41 Tue Mar 12 1996 Starts Completions Active All processes: 5 5 0 Node ID Process Image bronze 11141 11141 rtr 5 5 0 o New RTR monitor file, MONITOR GROUP The monitor picture MONITOR GROUP shows server and transaction concurrency on a partition basis including: a. Concurrent server "pool" usage. b. Transaction execution concurrency for shadow servers. In addition, the state of active transactions through their voting cycles is shown. Table A-1 describes the fields in detail. RTR Monitor Pictures A-1 RTR Monitor Pictures A.1 New Monitor Pictures % rtr monitor group Concurrency Measures Wed Apr 24 1996 10:04:26, NODE: finance.system.com -- averages -- txn srv -- transactions -- txn vote txn krid state cnt cnt que vreq vote ack /csn que act /csn 16777216 shd_rec_fail 0 1 0 0 0 0 0 0.0 0.0 0.0 16777217 shd_rec_fail 0 1 0 0 0 0 0 0.0 0.0 0.0 Table_A-1_MONITOR_GROUP_Fields_____________________________ Field_____Meaning__________________________________________ krid Key range (partition) identifier. state Partition state. txn cnt Number of transactions executed for this partition. srv cnt Number of servers active for this partition. The following fields track the progress of a transaction through the states: queued, vote requested, voted, acknowledged. que Number of transactions queued or in receiving state for this partition. vreq Number of transactions that are waiting for the server to vote. vote Number of transactions that have been voted on by the server but not committed by RTR. ack Number of transactions that have been committed but have not been acknowledged by the server. Acknowledgment occurs on a subsequent rtr_ receive_message() call by the server processing this transaction to get a message for a new transaction. /csn Number of transactions which have been grouped under the same "commit sequence number" (CSN). This grouping determines the ordering of transactions submitted to a secondary shadow server. txn que Average number of transactions queued or in receiving state for this partition. This average is computed by sampling the transaction que column from the time the monitor screen is invoked. A-2 RTRoMonitor Picturesnumber of transactions that have been voted on by the server but which have not yet been committed by RTR. This average is computed by sampling the transaction vote column from the time the monitor screen is invoked. txn/csn average number of transactions which have been grouped under the same commit sequence number (CSN) since this partition became active. This average is computed as the quotient of the txn __________cnt_column_and_the_total_number_of_CSN's.________ RTR Monitor Pictures A.1 New Monitor Pictures o New RTR monitor file, MONITOR IPC This monitor picture shows counts of inter-process communication (IPC) activity in the RTRACP and active RTR applications. o New RTR monitor file, MONITOR CONNECT This monitor picture displays the link counters relating to connection management, and displays the link state and architecture of remote nodes. o New RTR monitor file, MONITOR CONNECTS This monitor picture displays information relating to connection management, and displays the link state, network transport, architecture of remote nodes, and the reason for any connection failure. o New RTR monitor file, MONITOR V2CALLS This monitor picture displays counts of the RTR Version 2 verb usage through the interoperability subsystem. The screen layout is identical to the RTR Version 2 monitor calls picture. This monitor picture is not available for all platforms. o New RTR monitor file, MONITOR ACCFAIL When configuring RTR it can happen that nodes sometimes refuse to connect up. Whilst the cause of the error can be viewed on the initiator side with the connect monitor picture, until now it has been difficult to pinpoint the problem when looking at the other end of the link. The new monitor picture named ACCFAIL can now be used to display the names and reasons for links which the local node is refusing to accept connections on. Here is a sample: RTR Monitor Pictures A-3 RTR Monitor Pictures A.1 New Monitor Pictures ================================================================================ U n a c c e p t a b l e L i n k s Most recent links on which a connection attempt was declined Node: LENGTH Wed Jan 8 1997 11:51:00 -------------------------------------------------------------------------------- Link Transport Name(s) Reason for failure -------------------------------------------------------------------------------- ilira node is not configured for the facility dmark.zko.dec.com node not recognized breal facility name not matched DMARK DEC:.ZKO.DMARK node not recognized ilira node is not configured for the facility dmark.zko.dec.com node not recognized breal facility name not matched sfranc node role definitions do not match for breal facility name not matched DMARK DEC:.ZKO.DMARK node not recognized -------------------------------------------------------------------------------- List entries are reused in a cyclical fashion; the most recent entry is highlighted. ================================================================================ Some of the error that can be displayed by ACCFAIL are:- - RTR_STS_NOTRECOGNISED - "node not recognized" The local node has received a connection request over a link that is not configured in any facility on the local machine. If you expected the connection to succeed as the result of having a template link defined, check carefully the names displayed in the monitor picture. These are the names obtained from the network transport over which the link connection attempt was received, and it is with these that a match with a template (wildcard specification) link must succeed. Bear in mind that the name match is performed in a case sensitive manner. Names corresponding to TCP links may or may nor contain your domain name, depending on how the name is entered in either your local hosts file or name server. DECnet-Plus systems may yield both a A-4 RTR Monitor Pictures RTR Monitor Pictures A.1 New Monitor Pictures pseudonym and a link name; both are checked for a match with a template. - RTR_STS_FACNOTDEC - "facility name not matched" The connecting link is configured, but the facility that it requests does not exist on the local node. - RTR_STS_NODENOTCNFG - "node is not configured for the facility" The connecting link is configured on the local node, but not as part of the requested facility. - RTR_STS_ROLESMISMATCH - "node role definitions do not match for this facility" The connecting link is configured in the requested facility, but with a different role configuration on the local node. - RTR_STS_TRNOQUO - "router has no quorum in facility %s" The router is unable to accept front end connections since it is not quorate. This condition will clear up automatically as soon as the router gains connections to sufficient backends. RTR Monitor Pictures A-5