| Previous | Contents | Index |
The RTR ACP process requires the operator to size the process limits for the ACP before starting RTR on all platforms. No direct control of the process quotas of the RTR ACP is offered for UNIX based platforms. However, log file entries will result if hard limits are less than the preferred values for the RTR ACP.
This list shows the minimum limits for the ACP on the following UNIX platforms:
The START RTR qualifiers /LINK and /PROCESSES apply only to the OpenVMS
platform. Process quotas on UNIX platforms must be determined through
operating system handling of virtual memory sizing.
2.11 Environment Variables Used by RTR
The following table lists environment variables used by RTR.
| Environment Variable | Description |
|---|---|
| SYS$NODE | Set by DECnet if configured; used to detect presence of DECnet. |
| RTR$DUMP_DIRECTORY | Directory for rtr_error.log and rtr.dmp |
| RTR_DUMP_DIRECTORY | Synonym for RTR$DUMP_DIRECTORY. |
| RTR_MAX_CHANNEL_WAITQ_LIMIT | Defines for each channel the maximum amount of ACP WAITQ memory (in bytes) allowed. The default value is -1, which means there is no limit. This value may set to several million bytes. Set the RTR_MAX_CHANNEL_WAITQ_LIMIT value to an amount of ACP WAITQ memory that you can afford for one channel, considerably less than your virtual memory and heap quotas. If the value is -1, both RTR_MAX_CHANNEL_WAITQ_BYTES and RTR_MAX_CHANNEL_FULL_COUNT apply. If the value is greater than -1, only RTR_MAX_CHANNEL_FULL_COUNT applies. |
| RTR_MAX_CHANNEL_WAITQ_BYTES | Defines for each application channel the maximum queue size in bytes for a pending transaction or set of broadcasts. The default value is 100,000 bytes. You can set the RTR_MAX_CHANNEL_WAITQ_BYTES variable somewhat larger than the total amount of data that can possibly occur in one transaction or one set of broadcasts. This value might be a few million bytes for a typical large message application. This variable must be set to a value less then RTR_MAX_CHANNEL_WAITQ_LIMIT when RTR_MAX_CHANNEL_WAITQ_LIMIT is enabled (set greater than -1). |
| RTR_MAX_CHANNEL_FULL_COUNT | Defines for each channel the maximum number of attempts the ACP allows for a message to be placed in a full queue. The default value is 2000. This number may be set to a maximum of RTR_MAX_CHANNEL_WAITQ_LIMIT/64000, where 64000 is the maximum number of bytes allowed in an application message. |
| RTR_PREF_PROT | Default is RTR_DNA_FIRST for OpenVMS nodes with DECnet; RTR_TCP_FIRST for other platforms. Other possible values are RTR_DNA_ONLY and RTR_TCP_ONLY. |
| RTRHELP | Specifies an alternate location for the RTR online help file ( rtr.hlb ). |
|
RTR_DNA_PREFIX
RTR_TCP_PREFIX RTR_TUNNEL_PREFIX |
These command interfaces allow link names to be prefixed to indicate special treatment, e.g. tcp . If a prefixed name conflicts with a real node in the target environment, the value of the prefix string can be changed using these environment variables. |
If an application is sending many large messages, flow control may not close the application channel soon enough which may cause the ACP to run out of memory.
For applications using large messages containing tens of thousands of bytes, the following environment variables are provided to adjust the flow control algorithm parameters: RTR_MAX_CHANNEL_WAITQ_LIMIT, RTR_MAX_CHANNEL_WAITQ_BYTES, and RTR_MAX_CHANNEL_FULL_COUNT. These three variables are described in Table 2-1.
When the WAITQ memory quota is exceeded, the ACP deletes all messages
in the queue and returns a status of RTR_STS_CACHEXHAU, along with a
"channel has been closed" message
(rtr_mt_closed)
which indicates that all messages were discarded in the application
channel's queue.
2.13 Network Transports
RTR supports multiple network transports with a default behavior.
If an attempt to create a network connection to a remote node fails, RTR retries the connection attempt using an alternate transport protocol if one is available. The order in which the supported transport protocols are used depends on the host operating system.
If a connection attempt fails on all available protocols, it is retried at a later time starting again with the first transport protocol.
If an established link fails, RTR automatically initiates a reconnection of the link, starting with the first transport protocol for the platform, regardless of the transport employed when the link failed.
For information on dual-rail and multihome environments, see the
appendix on Dual-Rail Setup in the RTR Application Design
Guide.
2.13.1 Specifying the Link Transport Protocol
It is possible to override the protocol failover mechanism by specifying the transport protocol to be employed for a link by naming links to include a transport selecting prefix. Prefixing names of nodes with tcp. and dna. specifies TCP/IP or DECnet as the required transports respectively. These prefixes cause the local node to employ only the specified transport protocol when attempting a connection on the link to which the prefix has been applied. Using a protocol prefix on one node does not prevent a remote node from connecting using some other transport.
For example, to specify the facility FAX1 which uses only the DECnet transport, two routers (DNET1 and DNET2), two backends (SRV1 and SRV2) and many frontends, use the following command:
RTR> create facility FAX1 /frontend=(dna.FE1,dna.FE2,dna.FE3 ....)
/router=(dna.DNET1,dna.DNET2)
/backend=(dna.SRV1,dna.SRV2)
|
Creating a facility that uses only TCP/IP would use a command like this:
RTR> create facility FINANCE
/frontend=(tcp.client1,tcp.client2,tcp.client7 ....)
/router=(tcp.routr1,tcp.routr2)
/backend=(tcp.srv1,tcp.srv2)
|
When using RTR with Dynamic Host Configuration Protocol (DHCP) or an internet tunnel, a node name may not be fully known; special naming techniques are provided for these conditions.
RTR allows the use of wildcards when specifying the frontends from which a router is permitted to accept connections (that is, in the facility definition on the router). Valid wildcard characters are asterisk (*), percent sign (%), and question mark (?). Using a wildcard character at facility configuration time will result in the creation of a template link.
When operating RTR in conjunction with internet tunnels, a client system outside of the corporate firewall uses tunnel software to obtain a secure channel from the Internet to inside the corporate domain. The tunnel client is assigned an address by the tunnel server from a pool when the tunnel software starts up.
When an RTR router receives a connection request from RTR running on this client, the source address of the connection is the address assigned by the tunnel server. There is no longer a fixed relationship between the client and its address. You can configure the router to accept such a connection. Use wildcards to define the frontend nodes with all the possible addresses that the tunnel server can assign to tunnel clients, for example:
RTR> create facility . . ./frontend=*.pool.places.dec.com
|
This command enables all nodes connecting through the tunnel to connect as frontends. The anonymous client feature may also be used with frontends that are using DHCP for TCP/IP address assignment.
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 through an internet tunnel using an unknown pseudoadapter address. This method allows stricter access control than the anonymous client feature where wildcards may be used when specifying a remote node name. For example, on the router node behind a firewall, the facility definition could include:
RTR> create facility . . ./router=router.rtr.dec.com -
/frontend=tunnel.client.rtr.dec.com
|
The definition on the frontend could be:
RTR> create facility /router=router.rtr.dec.com -
/frontend=client.rtr.dec.com
|
Troubleshooting Tunnel and Wildcard Connections
To assist in diagnosing connect-acceptance problems, use the monitor picture ACCFAIL. This picture displays the recent history of those links from which the local node has refused to accept connections. It also displays the failed link name as provided by the network transport, and can assist in rapidly identifying any problems.
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
.
2.13.3 Interoperation with RTR Version 2 Using DECnet
Reliable Transaction Router is interoperable with RTR Version 2.2D ECO3 or later when running on a platform that supports DECnet. These platforms include OpenVMS, Tru64 UNIX, Sun Microsystems, Microsoft Windows 95, Windows 98, Windows NT, or Windows 2000.
You must not mix Version 2 and Version 3 or later routers and backends; router and backend nodes in a facility must be either all Version 2 or all Version 3 or later. Frontend nodes may be any version.
On RTR Version 2 nodes there are no special requirements for including a Version 3.x or later frontend in a Version 2 facility definition. Simply add the name of the frontend to the node list specified by the /FRONTEND qualifier.
On RTR Version 3 and later nodes the default network transport is TCP/IP, except for OpenVMS. 1 Since RTR Version 2 uses DECnet (only), you must specify that your RTR Version 3 and later nodes use the DECnet protocol. This is achieved by prefixing the RTR V2 node name with the dna. string.
For example, use the following command to specify the facility FAX1 on the RTR V3 frontend v3fe for which the two V2 routers VMS1 and VMS2 are defined.
RTR> create facility FAX1 /frontend=v3fe /router=(dna.VMS1,dna.VMS2) |
Make sure the facility name contains only UPPERCASE letters on all nodes if the facility includes nodes running RTR V2.
Using 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 platforms, you can use one of the following statements in your autoexec.bat .
set RTR_PREF_PROT=RTR_TCP_FIRST set RTR_PREF_PROT=RTR_TCP_ONLY set RTR_PREF_PROT=RTR_DNA_FIRST set RTR_PREF_PROT=RTR_DNA_ONLY |
These statements 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 4.0 for OpenVMS, refer to Section 2.14 for further information.
Troubleshooting network connections
If the RTR V3 frontend fails to connect with the RTR V2 router node, 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 Compaq Tru64 UNIX machines, ensure that the DECnet library is installed as /usr/shlib/libdna.so .
1 For RTR Version 3.2 and later for OpenVMS, the default network transport is DECnet. |
2.14 Network Protocol Selection on OpenVMS
The default network transport protocol on OpenVMS 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, you must use the node name prefix dna. if you want DECnet transport to be used. This is required, for example, when connecting to Version 2.2D ECO6 nodes.
If you are using DECnet as the default, you must 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.
Reliable Transaction Router Version 4.0 for OpenVMS can use either Compaq TCP/IP Services for OpenVMS or TCPware Version 5.1 as the
TCP/IP transport layer.
2.15 Running RTR as a Service on Windows NT
Once the RTR as Service has been installed (see the Reliable Transaction Router Installation Guide), RTR can be started or stopped from the Control Panel/Services panel using the START and STOP buttons provided.
Pressing START and STOP or the reverse in quick succession (within approximately 5 seconds, depending on the speed of your computer) may cause undesirable results because the Service executes quickly, making available the other action button. However, the requested RTR action may not have completed when the second action button is pressed. It is therefore possible that the STOP action may be blocked by an incomplete START action. Although the Service will claim to be stopped, RTR may in fact remain started. Pressing whichever action button is functioning should repair the problem. |
By default, RTR will not restart automatically at system reboot. You
can change this by setting the Control Panel/Services entry for RTR.
2.15.1 Customizing the RTR Windows NT Service
While starting RTR, the Service looks for the file usrstart.rtr in the RTR home directory. When it finds the file, the Service executes any RTR commands it may contain. RTR commands from usrstart.rtr execute after RTR has been started.
From the point of view of the Service, the RTR home directory is found in the system-level environment variable rtr_directory , or, if that is not defined, then the directory from which the Service was executed.
For the RTR Service to use it, rtr_directory must be defined in the system-level environment variables list, not the user-level environment variables list. Also, the system must be rebooted after the definition of rtr_directory is either created or changed for it to be used.
If a user-level copy of rtr_directory exists, it must identify the same RTR home directory as the system-level copy, or if there is no system-level copy, the directory containing the currently registered Service program. If it does not, behavior of RTR is undefined.
Changing the value of rtr_directory , or reregistering the service from another directory while RTR is running, is dangerous and should be avoided. Starting RTR from the Service, then stopping it from DOS (or the reverse) should also be avoided. |
If you put STOP RTR in the usrstart.rtr file, it will stop RTR. The Service will not detect that RTR has been stopped and will offer only the STOP action button. Pressing the STOP button will fix the problem.
Similarly, when the Service stops RTR, it searches the RTR home directory for the file usrstop.rtr and, if the file exists, it executes any RTR commands in it. User commands from usrstop.rtr are executed before RTR has stopped.
If you put QUIT or EXIT in either usrstart.rtr or usrstop.rtr , RTR will exit improperly. As a result, an RTR command server process incorrectly remains active, preventing the Service from starting or stopping RTR, and preventing the RTR command server from exiting. Because the RTR command server executes under the SYSTEM account, it cannot be stopped from Task Manager other than by the SYSTEM account. |
If RTR is started from the Service rather than from a Command Prompt window, several files are created in the RTR root directory.
When the Service stops RTR, it recreates
srvcin.txt
and creates
rtrstop.rtr
for stopdown commands. Creation of these files is unconditional; that
is, they are created every time RTR is started or stopped, whether or
not they already exist. RTR will therefore ignore (and overwrite) any
changes made to one of these files.
2.16 Selecting Processing-states (Roles) for Nodes
This section discusses how RTR assigns roles to backend node
partitions, and how routers are selected.
2.16.1 Role Assignment for Backend Node Partitions
RTR assigns a primary or secondary processing state to a partition (or a key-range definition), consisting of one or more server application channels, which may or may not share a common process. All such server channels belonging to a given partition will have the same processing state on a given node. However, the processing state for the same partition will normally be different on different nodes. The exception is the case of the standby processing state. Because a given partition can have multiple standby nodes, several of these nodes may be in this state.
RTR determines the processing state of a given partition through the use of a globally managed sequence number for that partition. By default, the RTR master router will automatically assign sequence numbers to partitions during startup. When a server is started up on a backend node and declares a new partition for that node, the partition initially has a sequence number of zero. When the partition on that backend makes an initial connection to the master router, the router increases its sequence number count for that partition by one and assigns the new sequence number to the new backend partition. The active node with the lowest backend partition sequence number gets the primary processing state in both shadow and standby configurations. That node is also referred to as the primary node, though the same node could have a standby processing state for a different partition.
Under certain failover conditions, backend partitions may either retain their original sequence number or be assigned a new sequence number by the router. If a failure is caused by a network disruption, for example, a backend partition will retain its sequence number when it reconnects with the router. However, if the backend node is rebooted or RTR is restarted on the backend node, a new sequence number will be assigned by the router to any partitions that start up on that node. Routers will only assign new sequence numbers to backend partitions that have a current sequence number of zero, or if the backend partition is joining an existing facility and has a sequence number that conflicts with another backend partition on another node.
Sequence number information can be obtained from the SHOW PARTITION command. In the output of this command, the sequence number is indicated by the "relative priority". The following example shows how to use the SHOW PARTITION command from a router partition. In this example, the backend partition called Bronze has a sequence number of 1, and the backend partition called Gold has a sequence number of 2.
Router partitions on node SILVER in group test at Mon Mar 22 14:51:16 1999 State: ACTIVE Low bound: 0 High bound: 4294967295 Failover policy: fail_to_standby Backends: bronze,gold States: pri_act,sec_act Relative priorities: 1,2 Primary main: bronze Shadow main: gold |
The output of the SHOW PARTITION command for each backend node is as follows:
Backend partitions on node BRONZE in group "test" at Mon Mar 22 14:52:32 1999 Partition name: p1 Facility: RTR$DEFAULT_FACILITY State: pri_act Low bound: 0 High bound: 4294967295 Active servers: 0 Free servers: 1 Transaction presentation: active Last Rcvy BE: gold Active transaction count: 0 Transactions recovered: 0 Failover policy: fail_to_standby Key range ID: 16777217 Master router: silver Relative priority: 1 Features: Shadow,NoStandby,Concurrent Backend partitions on node GOLD in group "test" at Mon Mar 22 14:54:12 1999 Partition name: p1 Facility: RTR$DEFAULT_FACILITY State: sec_act Low bound: 0 High bound: 4294967295 Active servers: 0 Free servers: 1 Transaction presentation: active Last Rcvy BE: bronze Active transaction count: 0 Transactions recovered: 0 Failover policy: fail_to_standby Key range ID: 16777216 Master router: silver Relative priority: 2 Features: Shadow,NoStandby,Concurrent |
The following figure shows how sequence numbers are initially assigned in a simple partition with two backends named Bronze and Gold, and a router named Silver.
Figure 2-3 Assignment of Sequence Numbers
Alternately, the roles of backend nodes can be specifically assigned with the /PRIORITY_LIST qualifier to the SET PARTITION command. The /PRIORITY_LIST qualifier can be used to ensure that when Bronze fails and then returns to participate in the facility, it then becomes the active primary member. To ensure this, the following command would be issued on both backend systems immediately after the creation of the partition:
SET PARTITION test/PRIORITY_LIST=(bronze,gold) |
| Previous | Next | Contents | Index |