Order Number: AA-Q88BE-TE

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
DIGITAL UNIX 4.0D
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

COMPAQ COMPUTER CORPORATION SHALL NOT BE LIABLE FOR TECHNICAL OR EDITORIAL ERRORS OR OMISSIONS CONTAINED HEREIN, NOR FOR INCIDENTAL OR CONSEQUENTIAL DAMAGES RESULTING FROM THE FURNISHING, PERFORMANCE, OR USE OF THIS MATERIAL. THIS INFORMATION IS PROVIDED "AS IS" AND COMPAQ COMPUTER CORPORATION DISCLAIMS ANY WARRANTIES, EXPRESS, IMPLIED OR STATUTORY AND EXPRESSLY DISCLAIMS THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR PARTICULAR PURPOSE, GOOD TITLE AND AGAINST INFRINGEMENT. This publication contains information protected by copyright. No part of this publication may be photocopied or reproduced in any form without prior written consent from Compaq Computer Corporation.

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:

• A brief introduction to RTR concepts, Chapter 1.
• A guide to writing RTR applications, Chapter 2, Overview of the Portable API. This chapter includes information on new features such as use of XA and nested transactions.
• A complete description of the RTR Application Programming Interface (API) showing the syntax and data structures for each RTR call, Chapter 3, RTR Call Reference.
• An appendix, Appendix A, Comparison of Portable and OpenVMS APIs, comparing the portable API and the OpenVMS API.
• A short tutorial for the application programmer, Appendix B.

Related Documentation

• Reliable Transaction Router Release Notes
• Reliable Transaction Router Installation Guide
• Reliable Transaction Router System Manager's Manual
• Reliable Transaction Router Migration Guide
• Reliable Transaction Router Application Design Guide

Reader's Comments

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

Conventions

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.

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:

• Allows the database to be distributed geographically.
• Permits replication of servers to cope with either network, node or site failures.
• Allows computer resources to be added to meet performance requirements.
• Allows performance or geographic expansion whilst protecting the investments made in existing hardware and application software.

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:

• For use of the disk
• For locks on database records
• For the CPU resources needed to access the database

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

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

• Atomic: The system will either perform all individual operations on the data, or will assure that no partially completed operations leave any effects on the data.
• Consistent: Any execution of a transaction must take the database (globally) from one consistent state to another consistent state.
• Isolated: Operation of concurrent transactions must yield results that are indistinguishable from the results which would be obtained by forcing each transaction to be serially executed (i.e., in isolation).
• Durable: The ability to preserve the effects of committed transactions and ensure database consistency after recovery from processor, memory, media or network failures.

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

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:

• If any hardware or software component fails while a transaction is active, the client application does not need to cancel operations begun for the current transaction.
• If any hardware or software component fails after the client has accepted a transaction, the database will be updated during a subsequent restart. (Transactions that were accepted are stored on disk and automatically replayed by RTR.)

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:

• Concurrent servers
• Standby servers
• Shadow servers
• Router failover

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

• Concurrent servers handle similar transactions which access the same data partition and run on the same node.
• Shadow servers handle the same transactions and run on different nodes.
• Standby servers provide a node that can take over processing on a data partition when the primary server or node fails.
• Callout servers run on backends or routers and receive all messages within a facility so that authentication and logging operations can be performed in parallel.

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

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:

• The security check can run in parallel with the database updates thus improving response times.
• The security check can be run on the router hardware.
• The security checking code is completely separated from other application code.

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.