Because of changes to many monitor screens with RTR Version 3, user scripts that parse monitor output may need to be reviewed and changed.

5.5.4 User Customized Monitors

User monitors customized for use with RTR Version 2 may or may not work with RTR Version 3. DIGITAL recommends that user-customized monitors be tested with RTR Version 3 before being put into production.

5.5.5 History Screens

New monitor screens that show partition state or network connection history include MONITOR accfail and MONITOR rscbe.

5.6 Remote Command Support

With the new support for TCP/IP, you can execute commands on remote systems using the rsh utility.

To use this feature, check your operating system documentation for how to ensure access to a TCP/IP environment, and grant such privileges to users. You may, for example, need to make an entry in the .rhosts file in the home directory of the RTR user on the target node or nodes, among other things. This file would contain the host name (and optionally the user name) of the node where the remote commands will be issued.

5.7 Partition Management

Partitions are now managed objects in RTR Version 3.2; partitions can be defined by the system manager before application startup. New commands listed in Table 5-6 support partition management.

5.8 Transaction State Management

Transaction state can be changed by the system manager to resolve certain deadlock situations using the SET TRANSACTION command. For more information on this command, see the RTR System Manager's Manual.

5.9 Using RTR Version 2 Command Procedures

Most RTR Version 2 command procedures will still work with RTR Version 3. One changed command is listed in Section 5.3.2 and fully described in the RTR System Manager's Manual.

5.10 Command Line Interface Support for RTR Version 2 API

Command-line interface support for the RTR Version 2 API may not be fully compatible between RTR Version 2 and RTR Version 3. See the RTR Version 3 System Manager's Manual and Release Notes for additional details.

5.11 Interpreting Output from SHOW Commands

The output from SHOW commands has changed with RTR Version 3. All SHOW output now includes date and time. Additional changes are listed in Table 5-4.

Table 5-4 Changed SHOW COMMANDS

Command	Description
SHOW CLIENT	This new command displays information about client channels. It supersedes the SHOW REQUESTOR command.
SHOW SERVER/FULL	The SHOW SERVER/FULL command provides new information on states.
SHOW TRANSACTION	With the SHOW TRANSACTION command, you can now specify display for a frontend, backend, or router.
SHOW FACILITY/LINK	The SHOW FACILITY/LINK command provides new information on states.
SHOW PARTITION/FULL	The SHOW PARTITION/FULL command provides new information on states.

5.12 Comparing RTR Version 2 and Version 3 Utility Commands

Table 5-5 Obsolete OpenVMS RTR Utility Commands

Command Name	Comparable RTR Version 3 Command
ATTACH	No equivalent.
DEFINE/KEY	No equivalent.
PRINT	Use MONITOR filespec/OUTPUT= filename, and the OpenVMS PRINT command.
SHOW RTR/PARAMS	No equivalent.

Table 5-6 lists commands that are new to RTR Version 3.

These commands are described more fully in the Reliable Transaction Router System Manager's Manual.

Table 5-6 New OpenVMS RTR Utility Commands

Command Name	Description
CALL RTR_< routine>	Executes the named routine and returns status.
CREATE PARTITION	Creates a named partition.
DELETE PARTITION	Deletes a named partition.
DISPLAY STRING	Displays a string in a monitor picture.
DUMP JOURNAL	Displays contents of RTR journal.
EXECUTE	Executes RTR commands from a file.
QUIT	Exits RTR.
REGISTER RM 1	Registers resource managers with the current transaction manager.
SET PARTITION	Sets partition properties.
SET TRANSACTION	Changes the state of a transaction.
SHOW CLIENT	Supersedes SHOW REQUESTOR.
SHOW RM 1	Displays information for registered resource managers.
UNREGISTER RM 1	Deletes a resource manager.

In this chapter the term OpenVMS API refers to the Reliable Transaction Router for OpenVMS Version 2. The term Portable API refers to the API used in Reliable Transaction Router for OpenVMS Version 3.

With RTR Version 3, the Portable API provides:

• Portability over a wide range of language and machine environments
• Simplified handling of concurrency, independent of the type of operating system
• Support for communication between machines with different hardware representations of common data types
• Interoperability with existing applications that use the OpenVMS API
• Improved performance for commonly used transaction types
• Support for use within a threaded environment
• Support for foreign protocols such as XA and Microsoft DTC, with nested or subtransaction transaction capability

Table 6-1 lists the OpenVMS API and comparable Portable API calls.

Table 6-1 OpenVMS API and Portable API Comparison

OpenVMS API (Version 2)	Portable API (Version 3)
$dcl_tx_prc()	rtr_open_channel()
$start_tx()	rtr_start_tx() [optional]
$commit_tx()	rtr_accept_tx()
$abort_tx()	rtr_reject_tx()
$vote_tx()	rtr_accept_tx() rtr_reject_tx()
$deq_tx()	rtr_receive_message()
$enq_tx()	rtr_send_to_server() rtr_reply_to_client() rtr_broadcast_event()
$dcl_tx_prc() (SHUT)	rtr_close_channel()
$get_txi()	rtr_request_info()
$set_txi()	rtr_set_info()
ASTPRM (on asynch calls)	rtr_set_user_handle()
-	rtr_error_text()
-	rtr_get_tid()
-	rtr_prepare_tx()
-	rtr_set_wakeup()

OpenVMS API calls are obsolete and supported only on OpenVMS systems.

6.2 Recompiling and Relinking

There is no need to recompile and relink RTR Version 2 applications to run them on RTR Version 3.

To link RTR application programs, include the following line in the linker options file:

SYS$SHARE:LIBRTR/SHARE

An existing RTR Version 2 application will run on RTR Version 3.

However, if the application is recompiled, you must supply all parameters for any RTR call. For example, the $ENQ_TX service has eleven parameters, some of which were optional in RTR Version 2. All eleven must be supplied if the application is recompiled with RTR Version 3.

• 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, change the linker options file referencing RTRSHR (that is, change SYS$SHARE:RTRSHR/SHARE to SYS$SHARE:LIBRTR/SHARE). After making this change, you can remove SYS$SHARE:RTRSHR.EXE from your system.
  If you are linking on a system where RTR Version 2 was never installed, always use SYS$SHARE:LIBRTR/SHARE.
• Event status
  With RTR Version 2, an application could pass event status as a parameter when calling $ENQ with the RTR$M_BROADCAST flag set. This broadcast $ENQ was delivered with the event status stored in the RTR$L_EVT_STATUS field of the RTR$_EVT data structure, and passed as a parameter to the broadcast AST.
  When running RTR Version 2 applications on RTR Version 3, event status is not passed from sender to receiver. All User events received by an RTR Version 2 application have the event status parameter set to 0 as shown in the following table:

  If the sender is:	Then:
  A Version 2 application	RTR Version 3 does not pass event status.
  A Version 3 application	There is no event status.

• Channel number
  In some cases, RTR Version 2 returned the error status RTR$_INVALCH if an operation was attempted using an invalid channel number (for example, 0), and RTR$_CHNOTALLOC for potentially valid channel numbers that have not been declared. RTR Version 3 always returns RTR$_CHNOTALLOC.
• RTR STOP/ABORT
  If an RTR STOP RTR/ABORT command is issued with RTR Version 2, RTR executes an AST in the context of any applications that have an RTR channel open. The applications exit with the status RTR$_RTRWASSTO.
  In RTR Version 3, 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 receives an error status on any RTR operation in progress on that channel, but the application is not terminated. The application must 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.)

With RTR Version 2, RTR calls execute in kernel mode; with RTR Version 3, RTR runs in application process mode, normally user mode.

6.3.1 Running Clients That Share Channels

With RTR Version 2, clients that start up and declare channels could use the flag INHNOSRVWT (inhibit-no server-wait) to proceed without waiting. (It lets $DCL_TX_PRC/REQ complete before servers have been declared.) With RTR Version 3, to perform a similar operation, an application must have either the OPER or RTR$OPERATOR process right.

6.4 Application Level Interoperability

With RTR Version 2, application level interoperability worked only with both applications running on the same operating system. With the upgrade to RTR Version 3, applications using the RTR Version 3 API can run on any supported operating system, and RTR Version 2 and RTR Version 3 applications can run in the RTR Version 3 environment. Table 6-2 provides information on application interoperability.

Table 6-2 Application Interoperability

Application Feature	Description
Mixing Version 2 and Version 3 style calls	You cannot mix RTR Version 2 and RTR Version 3 calls in the same application.
Transaction identification	In RTR Version 3, unless your application uses only the RTR Version 2 API and DECnet, the size of the transaction identification is larger than in RTR Version 2 (28 bytes compared to 8 bytes).
Version 2 and Version 3 applications talking to one another	RTR Version 2 and RTR Version 3 applications can directly communicate using RTR calls.
The DSDEF feature for data marshalling	A new feature in RTR Version 3 is DSDEF, with which an application can specify data marshalling requirements. With RTR Version 3, you can specify data format and RTR Version 3 can do format translations where required. See the Reliable Transaction Router Application Programmer's Reference Manual for more information.

6.5 Support for $GETTXI

The $GETTXI system service to return transaction information is not available in RTR Version 3. The RTR Version 3 equivalent is rtr_request_info. Applications that used $GETTXI must either remove $GETTXI or convert to RTR Version 3 calls. This change was required because of significant change to RTR data structures between RTR Version 2 and RTR Version 3.

6.6 Threaded Applications

With RTR Version 3, applications that rely on threading may not work exactly the same way they worked with RTR Version 2 on OpenVMS.

Applications that use kernel threads with RTR Version 2 will not work with RTR Version 3. RTR Version 2 was thread-reentrant, but the RTR Version 2 layer in RTR Version 3 on OpenVMS and Windoes should not be called from more than one thread. When writing threaded applications, a developer should consult OpenVMS documentation for information on what can be done at AST level in a threaded application. For example, see the DEC C Run-Time Library Reference Manual for OpenVMS Systems, Section 1.7.1, "Reentrancy", for restrictions on the simultaneous use of OpenVMS ASTs and threads.

The RTR Version 3 API can be called from multiple threads when linked with the multi-threaded version of the RTR shared library provided with RTR for DIGITAL UNIX, Windows NT/95, Sun Solaris, or AIX.

6.7 DDTM Support

RTR Version 2 provides limited support for DDTM (DECdtm^tm) in RTR Version 3.1D and later.

6.8 Current Issues

Certain server applications that worked with RTR Version 2 may not work correctly with RTR Version 3. In RTR Version 3, server applications must have outstanding $DEQ_TX calls for each server channel at all times. RTR Version 2 could tolerate breaking of this condition; RTR Version 3 does not.