 











































                    Reliable_Transaction_Router,_Version_3.1D___________

                    Release Notes





                    December, 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



 













          ________________________________________________________________

          December, 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-13

        1.5   Miscellaneous.................................   1-15

        1.5.1     TCP Services File.........................   1-15

        1.5.2     RTR Privileges............................   1-15

        1.6   Interoperation with RTR Version 2 Using

              DECnet........................................   1-16



  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-8

        3.6   Network Protocol Selection....................    3-9

        3.7   Problem Diagnosis.............................    3-9

        3.8   Linking RTR Applications......................   3-10





                                                                iii



 















          3.9   Compatibility of Version 2.2D ECO6

                Applications Running on Version 3.1D..........   3-10



    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-6











    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.



              <Return>          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-1-139 Shadow server reconnecting and partition

                 unavailable



                 A node with shadow servers which loses connection to the

                 network may cause its partner node to prematurely enter

                 "sec_act" when the node is reconnected. This will cause

                 the partition to become unavailable to new transactions

                 until shadow recovery is completed.



                 This problem will only happen if the shadow servers

                 had previously been the "preferred primary", i.e. these

                 servers were started before the servers on the partner

                 node.









                                                General Information  1-11



 







    General Information

    1.3 Known Problems





          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.



          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-3-40 After an RTR SET LOG/FILE=... command fails,

             RTR SHOW LOG incorrectly displays the failed log file

             settings, even though the previous log file settings are

             really still in effect.



          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-12 General Information



 







                                                     General Information

                                                         1.4 Restrictions





        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

                 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.









                                                General Information  1-13



 







    General Information

    1.4 Restrictions





          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.



             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-14 General Information



 







                                                     General Information

                                                        1.5 Miscellaneous





        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.



              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.



                                                General Information  1-15



 







    General Information

    1.5 Miscellaneous





          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.



          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.".



          ____________________

          [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 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.



              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.



              o  14-1-208 Server processes could fail when processing the

                 $deq_tx() function following an aborted transaction on

                 which the server voted to commit.







                                        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.



          o  14-1-222 RTR START RTR can return inappropriate %SYSTEM-

             F-BADPARAM status.



             If RTR START RTR takes more than ten seconds to start

             the ACP, then when it does start, RTR returns the

             error code %SYSTEM-F-BADPARAM instead of the success

             code %RTR-S-RTRSTART, even though RTR was started

             successfully. The RTRSTART message appears immediately,

             but should appear after any "%RTR-I-WFPROCESS, waiting

             for acp to start up" messages.



    3.4 Restrictions



          o  14-3-53 Erroneous status "RTR ACP not available"



             Setting the process ASTlm quota too low may result in

             applications receiving an erroneous indication that the

             ACP is not available. Raising the process ASTlm quota

             corrects this problem.



          o  14-1-214 Installing on a system running RTR Version 2.



             When installing RTR V3 on a system running RTR Version

             2, shut down RTR V2 by using the command RTR STOP RTR

             before running the installation. This ensures that the

             V2 RTRACP process exits prior to installing RTR V3.

             Failure to do this may either prevent the V3 ACP from

             starting, or cause a process failure when adding the

             first RTR facility.





    3-6 OpenVMS Specific Information



 







                                            OpenVMS Specific Information

                                                         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.



              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.















                                        OpenVMS Specific Information  3-7



 







    OpenVMS Specific Information

    3.5 Reliable Transaction Router, Version 3.1D Installation Information





    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.



          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-8 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.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.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-9



 







    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_

             <groupname> and RTRCSV_<username> 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.



             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-10 OpenVMS Specific Information



 







                                            OpenVMS Specific Information

 Compatibility  of Version 2.2D ECO6 Applications Running on Version 3.1D





              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.



                 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



              o  14-1-228 Typing CTRL-C at the RTR command line to

                 interrupt command output used to result in an exception

                 condition and a message box display.



        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-1-155 TCP/IP protocol must be operational



                 RTR for Windows NT 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 Control Panel

                 (because DECnet has been installed, for example) then

                 trying to start RTR results in a Winsock error.



                 To fully support protocol failover between TCP/IP

                 and DECnet on Windows NT and Windows 95 systems, the

                 unqualified IP host name of the machine should be the

                 same as the DECnet node name.



              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.







                                      Windows NT Specific Information 7-5



 







    Windows NT Specific Information

    7.4 Restrictions





             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-4-6 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 for

             Windows NT. The remote shell daemon from Ataman[TM]

             Software Inc. is recommended. Visit Ataman's web site

             (http://www.ataman.com) for further information.



             Because of the limitation imposed by Ataman's remote

             shell daemon, processes created as a result of using

             a remote command remain in existence only for life of

             that command. Therefore it is recommended to issue the

             command "RTR START RTR" locally (perhaps in a startup

             file) before beginning to use remote commands.



          o  14-3-62 If Pathworks32 is installed without DECnet

             support (for example, LAT procotol only, or if want to

             use PowerTerm or eXcursion where DECnet not strictly

             needed), then RTR will not start correctly if the

             version of Pathworks used is V7.0.



             To use RTR in such a configuration, use one of the

             workarounds:



             o upgrade to Pathworks32 V7.0A which fixes the problem



             o set RTR_PREF_PROT=RTR_TCP_ONLY























    7-6 Windows NT Specific Information



 





















                                                                        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



          o  14-1-228 Typing CTRL-C at the RTR command line to

             interrupt command output used to result in an exception

             condition and a message box display.



    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 NT 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 Control Panel

             (because DECnet has been installed, for example) then

             trying to start RTR results in a Winsock error.



             To fully support protocol failover between TCP/IP

             and DECnet on Windows NT and Windows 95 systems, the

             unqualified IP host name of the machine should be the

             same as the DECnet node name.



          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



    8-4 Windows 95 Specific Information



 







                                          Windows 95 Specific Information

                                                         8.4 Restrictions





                 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.



              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-4-6 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 for

                 Windows 95. The remote shell daemon from Ataman[TM]

                 Software Inc. is recommended. Visit Ataman's web site

                 (http://www.ataman.com) for further information.



                 Because of the limitation imposed by Ataman's remote

                 shell daemon, processes created as a result of using

                 a remote command remain in existence only for life of

                 that command. Therefore it is recommended to issue the

                 command "RTR START RTR" locally (perhaps in a startup

                 file) before beginning to use remote commands.















                                      Windows 95 Specific Information 8-5



 







    Windows 95 Specific Information

    8.5 Restrictions for Applications Written for RTR Version 1.1 for DOS/Windows





    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.



          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.)



    8-6 Windows 95 Specific Information



 







                                          Windows 95 Specific Information

 for             Applications Written for RTR Version 1.1 for DOS/Windows





                 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

















































































                                      Windows 95 Specific Information 8-7



 





















                                                                        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

