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.6.4 User-Customized Monitors

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

5.6.5 History Screens

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

5.7 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.8 Partition Management

Partitions became 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.9 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.10 Using RTR Version 2 Command Procedures

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

5.11 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 Versions 3 and 4. See the RTR Versions 3 or 4 System Manager's Manual and Release Notes for additional details.

5.12 Interpreting Output from SHOW Commands

The output from SHOW commands 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.
SHOW TRANSACTION/BEFORE and /SINCE	Lets you specify before or since dates for viewing transactions.

5.13 Comparing RTR Version 2 and Version 3 or 4 Utility Commands

Table 5-5 Obsolete OpenVMS RTR Utility Commands

Command Name	Comparable RTR Version 3 or 4 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.
START HTTP_SERVER	Starts the browser interface to use in managing RTR.
UNREGISTER RM 1	Deletes a resource manager.

Table 5-7 lists the command that is new to RTR Version 4. This command is described more fully in the Reliable Transaction Router System Manager's Manual.

Table 5-7 RTR Utility Commands New with RTR Version 4

Command Name	Description
SHOW VERSION	Shows the version of RTR running on your system.

Table 5-8 lists new qualifiers for the RTR DISPLAY commands added to support new functions needed for the web browser system management interface.

Table 5-8 New Qualifiers to RTR DISPLAY Commands

Qualifier	Description
/COLSPAN= n	Number of columns the item is to span.
/DESCRIPTION=" text-string"	Provides descriptive text in a pop-up for a mouse-over.
/DISPLAY=NoHTML|NoTEXT	Suppresses hyphen-rules that section the display for use with browser (HTML) output.
/HEADER	Added to the first item in a new row, displays it as a header.
/MONITOR_HYPERLINK	For DISPLAY TEXT command only, inserts hyperlink to a MONITOR screen.
/PARAGRAPH	Formats display at start of HTML paragraph. Valid only after DISPLAY/NOTABLE.
/TABLE	As the first item of a new row, indicates start of a new table; /NOTABLE closes current table and starts a new text section.

Table 5-9 lists a new qualifier to the SET NODE command.

Table 5-9 New Qualifier to RTR SET NODE Command

Qualifier	Description
/RECOVERY[= recovery-protocol]	Specifies the recovery protocol to use, V32 or V40.

In this chapter the term OpenVMS API refers to Reliable Transaction Router for OpenVMS Version 2. The term C programming API refers to the C API used in Reliable Transaction Router for OpenVMS Versions 3 and 4, formerly known as the Portable API.

With RTR Versions 3 and 4, the C programming 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 C programming API calls.

Table 6-1 OpenVMS API and C Programming API Comparison

OpenVMS API (Version 2)	C Programming API (Versions 3 and 4)
$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 or 4.

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 or 4.

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 or 4.

• 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 or 4, 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 or 4 does not pass event status.
  A Version 3 or 4 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 or 4 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 Versions 3 and 4, 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 Versions 3 and 4, 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, or 4to 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 or 4, applications using the RTR Version 3 or 4 C API can run on any supported operating system, and RTR Version 2 and RTR Versions 3 and 4 applications can run in the RTR Version 3 or 4 environment. Table 6-2 provides information on application interoperability.

Table 6-2 Application Interoperability

Application Feature	Description
Mixing Version 2 and Version 3 or 4 style calls	You cannot mix RTR Version 2 and RTR Version 3 or 4 calls in the same application.
Transaction identification	In RTR Version 3 and 4, 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 Versions 3 or 4 applications talking to one another	RTR Version 2 and RTR Versions 3 or 4 applications can directly communicate using RTR calls.
The DSDEF feature for data marshalling	A new feature in RTR Version 3 was DSDEF, with which an application can specify data marshalling requirements. With RTR Versions 3 and 4, you can specify data format and RTR Versions 3 abd 4 can do format translations where required. See the Reliable Transaction Router Application Programmer's Reference Manual for more information.

6.5 Support for $GET_TXI

The $GET_TXI system service to return transaction information is not available in RTR Version 3 or 4. The RTR Version 3 and 4 equivalent is rtr_request_info. Applications that used $GET_TXI must either remove $GET_TXI or convert to RTR Version 3 or 4 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 Versions 3 and 4, applications that rely on threading may not work exactly as they worked with RTR Version 2 on OpenVMS.

Applications that use kernel threads with RTR Version 2 will not work with RTR Versions 3 and 4. RTR Version 2 was thread-reentrant, but the RTR Version 2 layer in RTR Version 3 or 4 on OpenVMS and Windows 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 Versions 3 and 4 C API can be called from multiple threads when linked with the multi-threaded version of the RTR shared library provided with RTR for Compaq Tru64 UNIX, Windows NT/2000, Windows 95/98, or Sun Solaris.

6.7 DDTM Support

RTR Version 2 provides limited support for DDTM (DECdtm^tm), which is more fully supported in RTR Version 3.1D and later.

6.8 Use of $DEQ_TX Calls

Certain server applications that worked with RTR Version 2 may not work correctly with RTR Versions 3 and 4. In RTR Versions 3 and 4, 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 Versions 3 and 4 do not.

6.9 C++ API

There is no direct comparison between the Version 2 OpenVMS API and the newest API available with RTR, the C++ object-oriented API. For information on the C++ object-oriented API, see Reliable Transaction Router Getting Started, the Reliable Transaction Router Application Design Guide, and the Reliable Transaction Router C++ Foundation Classes manual.