Reliable Transaction Router

Reliable Transaction Router

Application Programmer's Reference Manual

Order Number: AA-Q88BE-TE

June, 1999

This manual explains how to design and code applications for Reliable Transaction Router (RTR). It contains full descriptions of the RTR application programming interface (API) calls, and includes a short tutorial.

Revision/Update Information: This manual supersedes Version 3.1D of the RTR Application Programmer's Reference Manual. It has been extensively revised.

Operating Systems: OpenVMS Version 6.2, 7.1, 7.2
Windows NT Version 4.0
Sun Solaris Version 2.5, 2.6x
IBM AIX Version 4.2 to 4.3x
Hewlett-Packard HP-UX Version 10.20

Software Version: Reliable Transaction Router, Version 3.2

Compaq Computer Corporation
Houston, Texas

June, 1999


Copyright ©1999 Digital Equipment Corporation


The software described in this guide is furnished under a license agreement or nondisclosue agreement. The software may be used or copied only in accordance with the terms of the agreement.

Compaq and the Compaq logo are registered in the United States Patent and Trademark Office.

The following are trademarks of Compaq Computer Corporation: AlphaGeneration, AlphaServer, AlphaStation, DEC, DECconnect, DECdtm, DECnet, DIGITAL, OpenVMS, PATHWORKS, POLYCENTER, Reliable Transaction Router, TruCluster, VAX, and the VMScluster.

The following are third-party trademarks:

AIX and IBM are registered trademarks of International Business Machines Corporation.
Encina is a registered trademark of Transarc Corporation.
Hewlett-Packard and HP-UX are registered trademarks of Hewlett-Packard Company.
Intel is a trademark of Intel Corporation.
Microsoft, Microsoft Access, Microsoft SQL Server, Internet Explorer, :MS--DOS, Visual Basic, Visual C++, Windows, Windows 95, Windows NT are trademarks or registered trademarks of Microsoft Corporation.
Netscape, Netscape Communicator, and Netscape Navigator are registered trademarks of Netscape Communications Corporation.
Oracle, ORACLE7, PL/SQL, SQL*Net, AND SQL*Plus are trademarks or registered trademarks of Oracle Corporation.
Solaris, SPARCstation, SUN, SunOS, and Sunlink are trademarks or registered trademarks of Sun Microsystems, Inc.
UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company, Ltd.

Contents Index


Purpose of this Manual

This manual is the main reference source for persons writing application programs using Reliable Transaction Router (RTR). It completely describes the RTR application programming interface (API).

Document Structure

This manual contains three chapters and two appendices:

Related Documentation

Reader's Comments

Compaq welcomes your comments on this manual. Please send us your comments by email to Please include the following with your comments or suggestions: the title of the manual, date from the title page, section and page numbers.


Table 1 describes the conventions used in this guide.

Table 1 Conventions
Convention Meaning
boldface Boldface is used for emphasis.
italic Italics indicate arguments or variables, and titles of manuals.
rtr_start_tx() Monospaced font indicates the name of an RTR API call in text, and constants. partition, pathname, directory, or file.
rtr_mt_msg1 Monospaced bold font indicates RTR message types returned by an RTR call, and other fixed values.
RTR_STS_OK Small capitals show RTR commands and return status values in text and examples.
... Horizontal ellipsis in examples indicates one of the following:
  • Additional optional arguments in a statement have been omitted.
  • The preceding item or items can be repeated one or more times.
  • Additional parameters, values, or other information can be entered.
Vertical ellipsis indicates the omission of items from a code example or command format.
numbers All numbers in text are decimal, unless otherwise noted. Nondecimal radixes---binary, octal, or hexadecimal---are explicitly indicated.

Chapter 1
Reliable Transaction Router Concepts

This chapter introduces the Reliable Transaction Router, and some basic terms. Terms are more fully defined in the RTR Application Design Guide.

1.1 The Three Layer Model

RTR is based on a three layer architecture consisting of frontend (FE) roles, backend (BE) roles and router (TR) roles. The roles are shown in Figure 1-1. In this and subsequent diagrams, rectangles represent physical nodes, ovals represent application software, and DB represents the disks storing the database (and usually the database software that runs on the server).

Figure 1-1 The Three Layer Model

Client processes run on nodes defined to have the frontend role. This layer allows computing power to be provided locally at the end-user site for transaction acquisition and presentation.

Server processes (represented by "Server" in Figure 1-1) run on nodes defined to have the backend role. This layer:

The router layer contains no application software unless running callout servers. This layer reduces the number of logical network links required on frontend and backend nodes. It also decouples the backend layer from the frontend layer so that configuration changes in the (frequently changing) user environment have little influence on the transaction processing and database (backend) environment.

The three layer model can be mapped to any system topology. More than one role may be assigned to any particular node. For example, on a system with few frontends, the router and frontend layers can be combined in the same nodes. During application development and test, all three roles can be combined in one node.

The nodes used by an application and their configuration roles are specified using RTR configuration commands. RTR lets application code be completely location and configuration independent.

1.2 RTR Facilities

Many applications can use RTR at the same time without interfering with one another. This is achieved by defining a separate facility for each application.

When an application calls the rtr_open_channel() routine to declare a channel as a client or server, it specifies the name of the facility it will use.

See the RTR System Manager's Manual for information on how to define facilities.

1.3 The Partitioned Data Model

One goal in designing for high transaction throughput is reducing the time that users must wait for shared resources.

While many elements of a transaction processing system can be duplicated, one resource that must be shared is the database. Users compete for a shared database in three ways:

This competition can be alleviated by spreading the database across several backend nodes, each node being responsible for a subset of the data, or partition. RTR enables you to implement this partitioned data model, shown roughly in Figure 1-2 where the database has three partitions. RTR routes messages to the correct partition on the basis of an application-defined key. For a more complete description of partitioning as provided with RTR, see the Reliable Transaction Router Application Design Guide.

Figure 1-2 Partitioned Data Model

1.4 Transaction Integrity

RTR greatly simplifies the design and coding of distributed applications, because, with RTR, database actions can be bundled together into transactions.

1.4.1 The ACID Properties of Transactions

Any system that processes transactions must have the following properties (the ACID properties):

RTR allows you to easily build applications that ensure the ACID properties of transactions.

1.4.2 Two-Phase Commit

To ensure atomicity of transactions and consistency of the database, RTR uses the mechanism called two-phase commit. This mechanism is initiated by the client when it executes a call to RTR that says "I accept the transaction." The server or servers participating in the transaction are then asked: "Are you prepared to accept this transaction, or will you reject it?" This is the first phase of the commit, sometimes called the prepare phase.

RTR then collects all the votes from the server participants. If any server rejects the transaction, all the other participants are informed of this, and any changes are rolled back. If they are all "Yes, I accept the transaction," RTR then tells all the participant servers that they should commit the transaction to the database. RTR also informs the client that the transaction has completed successfully.

1.4.3 XA Support

The XA interface is part of the X/Open DTP (Distributed Transaction Processing) standard. It defines the interface that transaction managers (TM) and resource managers (RM) use to perform the two-phase commit protocol. (Resource managers are underlying database systems such as ORACLE RDBMS, Microsoft SQL Server, and others) This interface is not used by the application programs; it is only used by TM-to-RM exchanges to coordinate a transaction.

RTR, as a transaction manager, implements this XA interface so that it can directly communicate with an XA-compliant resource manager to commit a transaction. For example, when a server application calls rtr_accept_tx() to cast its vote during the first phase of the commit, RTR internally would call the XA interface with xa_prepare() to let underlying resource managers know that the transaction is ready to commit. After RTR collects votes from all the participants, RTR uses another XA call, xa_commit(), to tell participating resource managers to commit the transaction. RTR then sends an rtr_mt_accepted message to the server application to inform the application that the transaction is complete. Or RTR would call xa_rollback() to ask underlying resource managers to abort this transaction if any server rejects the transaction.

As a result, RTR and the underlying resource manager become tightly integrated with respect to committing a transaction. Using a resource manager eliminates the need for an application to deal with rtr_mt_msg1_uncertain messages. However, under certain circumstances such as ensuring that a broadcast, housekeeping, or other cleanup at the end of a transaction is not missed, an application may still need to deal with rtr_mt_msg1_uncertain messages.

1.4.4 RTR Implementation for Transaction Integrity

Transaction messages are exchanged between the client and the server application using the RTR API calls rtr_send_to_server(), rtr_reply_to_client() and rtr_receive_message().

A client may indicate the start of a transaction by explicitly using the rtr_start_tx() call, or implicitly by sending a message. The end of the transaction is indicated by using the rtr_accept_tx() call.

Collecting messages into transactions (sometimes described as bracketing) using rtr_start_tx() and rtr_accept_tx() ensures that:

The rtr_reject_tx() call ensures that all participants except the one making the call are informed that in-progress work should be rolled back.

Reliable Transaction Router also provides an implicit start transaction call, as follows. If a call is made to rtr_send_to_server() and no transaction is active on the channel, a new transaction is started.

1.5 Broadcasts

Sometimes an application has a requirement to send unsolicited messages to multiple recipients.

An example of such an application is a commodity trading system, where the clients submit orders and also need to be informed of the latest price changes.

The RTR broadcast capability meets this requirement.

Recipients subscribe to a class of broadcasts; a sender broadcasts a message in this class, all interested recipients receive the message.

RTR permits clients to broadcast messages to one or more servers, or servers to broadcast to one or more clients. If a server needs to broadcast a message to another server, it must open a second channel as a client.

1.6 Reliability Features

Reliability in RTR is enhanced by the use of:

Note that, conceptually, servers can be contrasted as follows:

1.6.1 Concurrent Servers

Concurrent servers allow transactions to be processed in parallel to increase throughput. Concurrent servers deal with the same database partition, and may be implemented as multiple channels within a single process or as one channel in separate processes.

1.6.2 Standby Servers

Standby servers are "spare" servers which automatically take over from the main backend if it fails. This takeover is transparent to the application.

Figure 1-3 shows a simple standby configuration. The two backend nodes are members of a cluster environment, and are both able to access the database.

For any one key range, the main or primary server (Smain) runs on one node whilst the standby server (Ssby) runs on the other node. The standby server process is running, but RTR does not pass any transactions to it. Should the primary node fail, RTR starts passing transactions to (Ssby). Note that one node can contain the primary servers for one key range and standby servers for another key range to balance the load across systems. This allows the nodes in a cluster environment to act as standby for other nodes without having idle hardware. When setting up a standby server, both servers must have access to the same journal.

Figure 1-3 Standby Servers

1.6.3 Shadow Servers

Shadow servers are servers on separate backends which handle the same transactions in parallel on identical copies of the database.

Figure 1-4 shows a simple shadow configuration. The main server (Smain) at Site 1 and the shadow server (Sshdw) at Site 2 both receive every transaction for the data partition they are servicing. Should Site 1 fail, Site 2 continues to operate without interruption. Sites can be geographically remote, for example, available at separate locations in a wide area network (WAN).

Figure 1-4 Shadow Servers

Note that each shadow server can also have standby servers.

1.6.4 Callout Servers

RTR callout servers provide partition-independent processing for authentication. For example, a callout server can enable checks to be carried out on all requests in a given facility.

Callout servers run on backend or router nodes. They receive a copy of every transaction either delivered to or passing through the node. Since callout servers are also asked to vote on the outcome of the transactions, they can effectively veto any transaction that does not pass the security checks.

Callout servers offer the following advantages:

Since this technique relies on backing out unauthorized transactions, it is most suitable when only a small proportion of transactions are expected to fail the security check, so as not to have a performance impact.

Next Contents Index