Reliable_Transaction_Router,_Version_3.1C___________ Release Notes March, 1997 These release notes describe the new features, changes, and known restrictions for Reliable Transaction Router, Version 3.1C 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.1C Digital Equipment Corporation Maynard, Massachusetts ________________________________________________________________ March 4, 1997 (RTR V3.1C (129)) Digital Equipment Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description. Possession, use, or copying of the software described in this publication is authorized only pursuant to a valid written license from Digital or an authorized sublicensor. © 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 VAX DOCUMENT Version 2.1. _________________________________________________________________ Contents Preface................................................... v 1 General Information 1.1 New Features.................................. 1-2 1.2 Changes and Corrections....................... 1-3 1.3 Restrictions.................................. 1-4 1.4 Known Problems................................ 1-5 1.5 Interoperation with RTR Version 2 Using DECnet........................................ 1-6 1.6 Using the RTR Command Utility on UNIX Platforms..................................... 1-8 2 Digital UNIX Specific Information 2.1 New Features.................................. 2-1 2.2 Changes and Corrections....................... 2-1 2.3 Restrictions ................................. 2-1 2.4 Known Problems ............................... 2-1 3 OpenVMS Specific Information 3.1 Reliable Transaction Router Version 3.1C for OpenVMS, New Features ........................ 3-1 3.2 Reliable Transaction Router Version 3.1C for OpenVMS Installation Information.............. 3-1 3.3 Changes and Corrections....................... 3-3 3.4 Restrictions ................................. 3-4 3.5 Known Problems ............................... 3-4 3.6 Network Protocol Selection.................... 3-5 3.7 Problem Diagnosis............................. 3-5 3.8 Linking RTR Applications...................... 3-6 iii 3.9 Compatibility of Version 2 Applications Running on Version 3.1C....................... 3-6 4 AIX Specific Information 4.1 New Features.................................. 4-1 4.2 Changes and Corrections....................... 4-1 4.3 Restrictions ................................. 4-1 4.4 Known Problems ............................... 4-1 5 SunOS Specific Information 5.1 New Features.................................. 5-1 5.2 Changes and Corrections....................... 5-1 5.3 Restrictions ................................. 5-1 5.4 Known Problems ............................... 5-2 6 HP-UX Specific Information 6.1 New Features.................................. 6-1 6.2 Changes and Corrections....................... 6-1 6.3 Restrictions ................................. 6-1 6.4 Known Problems ............................... 6-1 7 Windows NT Specific Information 7.1 New Features.................................. 7-1 7.2 Changes and Corrections....................... 7-1 7.3 Restrictions ................................. 7-2 7.4 Known Problems ............................... 7-2 7.5 Miscellaneous................................. 7-2 7.5.1 Using the RTR Command Utility............. 7-2 7.5.2 File Locations and the Windows NT Registry.................................. 7-2 7.5.3 TCP Services File ........................ 7-3 7.5.4 Examples Provided......................... 7-3 iv 8 Windows 95 Specific Information 8.1 New Features.................................. 8-1 8.2 Changes and Corrections....................... 8-2 8.3 Restrictions ................................. 8-2 8.3.1 Restrictions for Applications Written for RTR Version 1.1 for DOS/Windows........... 8-2 8.4 Known Problems ............................... 8-3 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.1C (RTR) that could not be included in the manuals. These notes give information for all implementations of Reliable Transaction Router, Version 3.1C. The new features of Reliable Transaction Router, Version 3.1C are described, together with any restrictions applicable to this version. ________________________ Note ________________________ References in this document to any particular version of Reliable Transaction Router or features of Reliable Transaction Router products does not imply the availability or otherwise of that version or feature. Refer to the Reliable Transaction Router Software Product Descriptions for further information. ______________________________________________________ Intended Audience These Release Notes are intended for all users of Reliable Transaction Router, Version 3.1C. Please read these notes before using the product. Also read the cover letter supplied with the kit and any README files that are included with the kit. v Document Structure o Chapter 1 describes the new features, changes, restrictions and known problems for Reliable Transaction Router, Version 3.1C applicable to all platforms. o Chapter 2 gives information specific to the Digital UNIX[R] implementation of Reliable Transaction Router, Version 3.1C. o Chapter 3 gives information specific to the OpenVMS implementation of Reliable Transaction Router, Version 3.1C. o Chapter 4 gives information specific to the AIX implementation of Reliable Transaction Router, Version 3.1C. o Chapter 5 gives information specific to the SunOS implementation of Reliable Transaction Router, Version 3.1C. o Chapter 6 gives information specific to the HP-UX implementation of Reliable Transaction Router, Version 3.1C. o Chapter 7 gives information specific to the Windows NT implementation of Reliable Transaction Router, Version 3.1C. o Chapter 8 gives information specific to the Windows 95 implementation of Reliable Transaction Router, Version 3.1C. 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.1B, Installation Guide o Reliable Transaction Router Version 3.1B, Application Programmer's Reference Manual o Reliable Transaction Router Version 3.1B, 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.1C common to all platforms. Refer to later chapters for platform specific information. Reliable Transaction Router Version 3.1C for Windows NT and Windows 95 This is the first release of RTR that runs on Windows 95. Users of Reliable Transaction Router Version 3.1C for Windows NT and Windows 95 on Windows 95 should ignore the "New Features" and "Changes and Corrections" sections in this chapter. Refer to Chapter 8 for all New Features and Changes and Corrections. ______________________________________________________ _Reliable Transaction Router Version 3.1C for OpenVMS _ Users of this release release should ignore the "New Features" and "Changes and Corrections" sections in this chapter. Refer to Chapter 3 for all New Features and Changes and Corrections. ______________________________________________________ ________ Using the Alta Vista Internet Tunnel ________ Reliable Transaction Router, Version 3.1C may be used with the Alta Vista Group Tunnel. The Tunnel can carry any RTR connection (backend to router or router to frontend) 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. General Information 1-1 General Information 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.1 New Features The following new features have been introduced in Reliable Transaction Router, Version 3.1C. o Protecting Against "Rogue" Transactions. It is possible for a "rogue" client transaction which, due to some user application bug, can "kill" the server process. Previously, RTR would re-apply this transaction indefinitely until no more servers were available. In order to avoid a transaction killing all server processes, the following mechanism has been introduced:- A transaction for which no rtr_accept_tx() has been called by a server will be aborted after it has caused the death of three concurrent servers to which it has been presented. The transaction abort status reported to the client is RTR_STS_SRVDIED. An RTR error log message with the same status is also written on the backend where the server deaths occurred. The limitation of this feature to transactions which have not yet been accepted prevents possible transaction inconsistencies which could otherwise arise between client and server(s), and on shadow secondary sites. This implies that it is advisable for a server application to complete any necessary validation of client transaction messages before accepting the transaction, if they wish to take advantage of this feature. 1-2 General Information General Information 1.2 Changes and Corrections 1.2 Changes and Corrections The following changes and corrections have been made in Reliable Transaction Router, Version 3.1C. o Server events corrected: RTR could sometimes deliver incorrect events to concurrent server channels. This has been fixed. o Transaction build-up reduced: Serialisation requirements imposed by the primary shadow sometimes caused a build-up of transactions on the secondary shadow, particularly when long transactions were being executed by concurrent servers on the primary. The build-up has been reduced. o The /BLOCKS qualifier to the CREATE JOURNAL command did not work when used to globally specify the size of journals. The qualifier may be used now. o The MONITOR command can now be used to monitor remote nodes. That is, the /NODE= qualifier is now supported for the MONITOR command. o A frontend could fail to reconnect to a router after using the TRIM FACILITY command, or a link break. This has been fixed. o The maximum length for a node name has been increased from 100 characters to 256 characters. o It was not possible to use node lists in files, i.e. CREATE FACILITY/ALL_ROLES=@filename. This has been fixed. o Problems with handling facility and channel names in a case-independent manner have been fixed. o An rtr_open_channel() server declaration having a key range overlap with an existing server channel caused an erroneous mt_opened message followed immediately by a mt_closed message. This has been fixed. General Information 1-3 General Information 1.2 Changes and Corrections o Changes in RTR monitoring: o The GROUP monitor picture now displays the final txn/csn grouping rather than a running peak. The grouping value has been corrected. o The PARTIT monitor picture now correctly displays the "bounds" field. o Cosmetic improvements have been made to the following monitor pictures: ACTIVE, TRAFFIC, STALLS, INBYTES, INMESS and ROUTERS. o Remote journal counters have been added to the JOURNAL monitor picture. o The pending counters in the CALLS monitor picture sometimes showed incorrect values. This has been fixed. o The erroneous blinking of non-connecting nodes and node/link labelling have been corrected in the CONNECT monitor picture. o An error that prevented the erasure of stale information in monitor pictures has been fixed. o An error in the calculation of numeric totals and averages for multiple-node monitoring has been fixed. 1.3 Restrictions This section describes the restrictions for Reliable Transaction Router, Version 3.1C on all supported platforms. o The API call rtr_set_user_handle() is allowed only when a transaction is not active on the channel. That is, the user handle associated with a particular transaction cannot be changed while a transaction is active. o The flags RTR_F_ACC_FORGET and RTR_F_REJ_RETRY are not supported. o The RTR CALL commands cannot be used as remote commands. 1-4 General Information General Information 1.3 Restrictions o The MODIFY JOURNAL command is not implemented; use the CREATE JOURNAL/MAXIMUM_BLOCKS to ensure that your journals are large enough for your configuration. In particular, when using shadow servers make sure that both are running, and that the journals are large enough to hold the stored transactions for any outage of a shadow server. o The API call rtr_set_info() is not implemented. o The commands SET FACILITY/BALANCE and SET FACILITY/BROADCAST=MINIMUM are not implemented. o This version of RTR does not support nested transactions. o On all UNIX versions, using the SPAWN command may cause the terminal window to hang when used from a RTR prompt that has been evoked by the superuser. If this occurs, kill the RTR prompt process, and also the sh -is process generated by it (if present). o Journal files are limited to a size of 256 MBytes. o RTR commands are limited to a total length of 1014 characters. 1.4 Known Problems This section describes the known problems for Reliable Transaction Router, Version 3.1C on all supported platforms. o 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 The locking mechanism used to prevent a journal being deleted is not supported on all platforms. Avoid using the rtr delete journal command while RTR is running. o 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. General Information 1-5 General Information 1.4 Known Problems o 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 both with the node name and the node address. o Documentation Versions: The current versions of the RTR manuals are the Reliable Transaction Router Version 3.1B, Installation Guide, the Reliable Transaction Router Version 3.1B, Application Programmer's Reference Manual and the Reliable Transaction Router Version 3.1B, System Manager's Manual. The manuals should be used in conjunction with these Release Notes. o Documentation Errata: o In the Reliable Transaction Router Version 3.1B, System Manager's Manual, Section 2.7, the node name prefix used to specify TCP/IP protocol is incorrectly shown as "tcpip.". The correct prefix is "tcp.". o The Reliable Transaction Router Version 3.1B, Application Programmer's Reference Manual wrongly shows the call rtr_set_wakeup() to take a channel-id parameter; the call only takes one parameter (the routine to be called). 1.5 Interoperation with RTR Version 2 Using DECnet Reliable Transaction Router, Version 3.1C 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. 1-6 General Information General Information 1.5 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.1C 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. 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). ____________________ [1] For Reliable Transaction Router Version 3.1C for OpenVMS, the preferred network transport can be either DECnet or TCP/IP. General Information 1-7 General Information 1.6 Using the RTR Command Utility on UNIX Platforms 1.6 Using the RTR Command Utility on UNIX Platforms This section gives guideline for using RTR commands on all UNIX platforms. o When using the command line interface (CLI), all references to files must be enclosed in quote marks, for example: RTR> show facility/output="/usr/users/smith/sho_facs.txt" o When entering commands from the shell prompt, RTR commands that have special characters such as "(" or ")" need special handling due to the behaviour of the shell. For example RTR> create facility/front=(rupiya,rruble)/router=rruble/back=rupiya will work correctly, but % rtr create facility/front=(rupiya,rruble)/router=rruble/back=rupiya will not. To make this command work, observe correct shell interpretation in any of the following ways. % rtr 'create facility/front=(rupiya,rruble)/router=rruble/back=rupiya' or, % rtr create facility/front='(rupiya,rruble)'/router=rruble/back=rupiya or, % rtr create facility/front=\(rupiya,rruble\)/router=rruble/back=rupiya Note also that quoted strings and special characters require this usage: % rtr show facility/output='"/usr/users/smith/sho_facs.txt"' % rtr '@'rtr_command_file 1-8 General Information 2 _________________________________________________________________ Digital UNIX Specific Information This chapter gives platform specific information for the Digital UNIX[R] implementation of Reliable Transaction Router, Version 3.1C. 2.1 New Features There are no new features in this release specific to the Digital UNIX version of this kit. 2.2 Changes and Corrections There are no changes and corrections in this release specific to the Digital UNIX version of this kit. 2.3 Restrictions There are no restrictions in this release specific to the Digital UNIX version of this kit. 2.4 Known Problems There are no known problems in this release specific to the Digital UNIX version of this kit. Digital UNIX Specific Information 2-1 3 _________________________________________________________________ OpenVMS Specific Information This chapter gives platform specific information for the OpenVMS implementation of Reliable Transaction Router, Version 3.1C. 3.1 Reliable Transaction Router Version 3.1C for OpenVMS, New Features There are no new features in this release specific to the OpenVMS version of this kit. Reliable Transaction Router Version 3.1C for OpenVMS provides support for RTR Version 2 system service calls, allowing most Version 2 applications to run. RTR Version 2 system service calls executed from the CLI are also supported. The following points should be noted:- o For new applications, use of the Version 3.1C API is recommended. o It is not possible to use both APIs from the same application program. o The Version 2 API is documented in the Version 2 manuals. 3.2 Reliable Transaction Router Version 3.1C for OpenVMS 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 OpenVMS Specific Information 3-1 OpenVMS Specific Information 3.2 Reliable Transaction Router Version 3.1C for OpenVMS Installation Information 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.1C, 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. o The Installation Verification Procedure (IVP) will complete successfully if at least one of the supported network protocols (DECnet or TCP/IP) is installed. o The standard monitor picture files provided with this kit are copied to SYS$COMMON:[RTR] at installation time. o The RTR help library file RTR.HLB is copied to SYS$HELP 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. o The Reliable Transaction Router Version 3.1B, Installation Guide incorrectly states that user accounts require the identifier RTR$INFO. This identifier is required only for application programs that call rtr_ request_info(). That is, this privilege that must be granted in order to use rtr_request_info(). 3-2 OpenVMS Specific Information OpenVMS Specific Information 3.3 Changes and Corrections 3.3 Changes and Corrections The following changes and corrections are specific to the OpenVMS version of this kit. o Occasional loss of command-line recall has been corrected. o In previous versions, the determination of which router node became the master router could be unpredictable and inconsistent among multiple backends, and this could lead to shadowed databases going out-of-sync. This has been fixed. o Previous versions would sometimes miss the local_ recovery state during server failover, resulting in possible diversion in the contents of shadowed databases. This has been corrected. . o With many RTR application processes running on a heavily loaded system, some application prcoesses could exit with the ACPNOTVIA error message, even though the RTR ACP was still active. This problem has been corrected. o A duplicate copy of LIBRTR.EXE was erroneously included in the PCSI file. The PCSI file is now considerably smaller. o Some RTR Version 2 applications were unable to find RTRSHR. This has been fixed by modifying RTR$STARTUP.COM to define RTRSHR as an executive mode logical name; this is required because RTR is an installed image. o The RTR IVP program could sometimes fail or hang if very large journals were already present on the system. This problem has been fixed. o The RTR Version 2 interface did not always deliver events properly. RTR has been changed to deliver events at the AST level to ensure proper delivery. o The system service $DCL_TX_PRC could fail to complete if the INHNOSRVWT flag was set. This has been fixed. o When using the call rtr_open_channel(), an invalid recipient name specification was incorrectly reported as RTR_STS_INVFACNAM. This has been changed to RTR_STS_ INVRCPNAM. OpenVMS Specific Information 3-3 OpenVMS Specific Information 3.3 Changes and Corrections o A race condition that resulted in process death when multiple command processes attempted to create a command server simultaneously has been fixed. 3.4 Restrictions This section describes the restrictions specific to the OpenVMS implementation of Reliable Transaction Router, Version 3.1C. o RTR commands entered at the operating system prompt have all arguments converted to lower case, unless the arguments are enclosed in quotes. For example: $ rtr call ..../channel=CLICHAN/ .... will be read as $ rtr call ..../channel=clichan/ .... However, $ rtr call ..../channel="CLICHAN"/ .... will be read as $ rtr call ..../channel=CLICHAN/ .... o Use of DECdtm operations with Reliable Transaction Router is not supported. o The Version 2 system services $GET_TXI and $GET_TXIW are not implemented. o The Version 2 commands START REMOTE_CLIENT_HANDLER and STOP REMOTE_CLIENT_HANDLER are not implemented. 3.5 Known Problems This section describes the problems specific to Reliable Transaction Router Version 3.1C for OpenVMS. o Reliable Transaction Router Version 2 sends a default message when the command $ENQ/BRO is used. Version 3.1C does not send a default message when this command is used. 3-4 OpenVMS Specific Information OpenVMS Specific Information 3.6 Network Protocol Selection 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 nodes as described in Section 1.5 of these Notes, and Section 2.7 of the Reliable Transaction Router Version 3.1C, 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.1C for OpenVMS can use either TCP/IP Services for OpenVMS or TCPware Version 5.1 as the TCP/IP transport layer. 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. OpenVMS Specific Information 3-5 OpenVMS Specific Information 3.7 Problem Diagnosis 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 Applications Running on Version 3.1C o Linking Version 2 Applications. Existing RTR Version 2 applications will run if they have been linked against RTRSHR. (RTRSHR has been superseded by LIBRTR.EXE. Existing RTR Version 2 application executables will run without relinking since RTR$STARTUP.COM defines RTRSHR as a logical name that points to LIBRTR.EXE.) However, as RTRSHR.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. 3-6 OpenVMS Specific Information OpenVMS Specific Information 3.9 Compatibility of Version 2 Applications Running on Version 3.1C o Under Reliable Transaction Router Version 2, 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 applications on Version 3.1C, the event status is not passed from sender to receiver. All USER events received by a Version 2 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.1C o RTR Version 2 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.1C makes no such distinction and always returns RTR$_CHNOTALLOC. o If an RTR STOP RTR/ABORT is issued using RTR Version 2, 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. In RTR Version 3.1C, 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-7 4 _________________________________________________________________ AIX Specific Information This chapter gives platform specific information for the AIX[TM] implementation of Reliable Transaction Router, Version 3.1C. 4.1 New Features There are no new features in this release specific to the AIX version. 4.2 Changes and Corrections There are no changes and corrections in this release specific to the AIX version. 4.3 Restrictions There are no restrictions in this release specific to the AIX version. 4.4 Known Problems There are no known problems in this release of RTR specific to the AIX version. 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.1C. 5.1 New Features There are no new features in this release specific to the SunOS version of this kit. 5.2 Changes and Corrections There are no changes and corrections in this release specific to the SunOS version of this kit. 5.3 Restrictions This section describes the restrictions and problems specific to the SunOS implementation of Reliable Transaction Router, Version 3.1C. 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 SunOS Specific Information 5-1 SunOS Specific Information 5.4 Known Problems 5.4 Known Problems This section describes the problems specific to the SunOS implementation of Reliable Transaction Router, Version 3.1C. o Solaris 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 Solaris resource limits: File descriptors are required by the RTR ACP to connect to application processes on the local machine and to RTR ACPs on other machines. The number of file descriptors that a process may use is limited: you can use the command limit descriptors (C shell) or ulimit -a (Korn shell) to view the value of this limit. For some RTR users, the default value of 64 (set by Solaris) is too small; use the following formula to determine the required value:- File descriptors >= 10 + (n * 1.2) + m In the formula, n is the number of processes that use RTR (clients or servers) and m is the number of connections to other nodes. The limit must be set for the process that starts RTR; ensure this is set by using the following commands similar to the following: rtr stop rtr rtr disconnect server limit descriptors 150 rtr start rtr o RTR ACP crash when shared memory segments are exhausted: 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. 5-2 SunOS Specific Information SunOS Specific Information 5.4 Known Problems 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. Note that the SUN documentation that describes how to alter this default contains errors - shmsys:shminfo_ shmseg is incorrectly described as "semsys:seminfo_ shmseg". SunOS Specific Information 5-3 6 _________________________________________________________________ HP-UX Specific Information This chapter gives platform specific information for the HP-UX[R] implementation of Reliable Transaction Router, Version 3.1C. 6.1 New Features There are no new features in this release specific to the HP-UX version of this kit. 6.2 Changes and Corrections There are no changes and corrections in this release specific to the HP-UX version of this kit. 6.3 Restrictions There are no restrictions in this release specific to the HP-UX version of this kit. 6.4 Known Problems There are no known problems in this release specific to the HP-UX version of this kit. HP-UX Specific Information 6-1 7 _________________________________________________________________ Windows NT Specific Information This chapter gives platform specific information for Reliable Transaction Router Version 3.1C 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.5 for further information. ______________________________________________________ 7.1 New Features Reliable Transaction Router, Version 3.1C for Windows NT operates with Windows NT Version 3.51 or Version 4.0 running on Alpha or Intel systems. 7.2 Changes and Corrections The following changes and corrections have been made in Reliable Transaction Router, Version 3.1C for Windows NT. o Previous versions of Reliable Transaction Router, Version 3.1C for Windows NT did not support remote commands. This restriction has been lifted; remote command 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 for Windows NT. Windows NT Specific Information 7-1 Windows NT Specific Information 7.3 Restrictions 7.3 Restrictions This section describes the restrictions and problems in Reliable Transaction Router, Version 3.1C for Windows NT. o RTR shared memory is used for environment settings such as group or system mode. This information survives a reboot of the Windows NT system. You can avoid this by deleting the file RTRENVPS located in the RTR root directory at startup time. o RTR journals are created in the directory RTRJNL located in the RTR kit installation directory. Only one journal file is allowed. (See Section 7.5.2). 7.4 Known Problems This section describes the known problems in Reliable Transaction Router, Version 3.1C for Windows NT. o DECnet transport is not supported between Reliable Transaction Router, Version 3.1C for Windows NT running as a frontend and RTR for SunOS as a backend. 7.5 Miscellaneous 7.5.1 Using the RTR Command Utility Access the RTR Command Line Interface (CLI) by double- clicking on the RTR icon in the Reliable Transaction Router Program Group. Double-click the RTR icon again to start further RTR CLI windows. 7.5.2 File Locations and the Windows NT Registry Entries are created for RTR in the Windows NT Registry at installation time. These entries are the RTR root (selected in the SETUP procedure), the RTR journal directory (defaults to immediately beneath the RTR root) and the RTR version number. You may change the location of the RTR root and journal directories using the registry editor. The registry entries are located in: HKEY_LOCAL_MACHINE\ DigitalEquipmentCorporation\ RTR 7-2 Windows NT Specific Information Windows NT Specific Information 7.5 Miscellaneous The registry entries are: Root - RTR root location\ Journal - RTR journal file location\ Version - RTR version number 7.5.3 TCP Services File o RTR uses the TCP/IP port number 46000 for the network communication. You should edit the services file C:\WINNT\SYSTEM32\DRIVERS\SERVICES to add the line rtracp 46000/tcp This informs the system administrator that port number 46000/tcp is reserved for RTR. 7.5.4 Examples Provided The following examples are provided in the examples subdirectory: o rtrreq.c o rtrsrv.c o rtrw32rq.c The programs rtrreq.c and rtrsrv.c are a console mode client and server. The rtrw32rq.c program is an example GUI client that can run with rtrsrv.c. The example applications can be built by using the examples.mak file: NMAKE /f examples.mak Windows NT Specific Information 7-3 8 _________________________________________________________________ Windows 95 Specific Information This chapter gives platform specific information for Reliable Transaction Router Version 3.1C 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.1C 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. See Section 8.3.1 for further information. 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 VMS V3.1B or later and Oracle 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 This is the first release of Reliable Transaction Router, Version 3.1C that runs on Windows 95, and is packaged as a single kit that may be installed on Windows 95 or Windows NT. Windows 95 Specific Information 8-1 Windows 95 Specific Information 8.2 Changes and Corrections 8.2 Changes and Corrections This is the first release of Reliable Transaction Router Version 3.1C for Windows NT and Windows 95. 8.3 Restrictions This section describes the restrictions in Reliable Transaction Router Version 3.1C for Windows NT and Windows 95 on the Windows 95 platform. o 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 for Windows 95. 8.3.1 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.1C 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.1C 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. 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: 8-2 Windows 95 Specific Information Windows 95 Specific Information 8.3 Restrictions . . . : warning C4047: '=' : different levels of indirection. This warning may safely 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.4 Known Problems This section describes the known problems in Reliable Transaction Router Version 3.1C for Windows NT and Windows 95. o DECnet transport is not supported between Reliable Transaction Router, Version 3.1C for Windows 95 running as a frontend and RTR for SunOS as a backend. Windows 95 Specific Information 8-3 A _________________________________________________________________ RTR Monitor Pictures This appendix describes new 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 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. RTR Monitor Pictures A-3