Reliable Transaction Router

C Application Programmer's
Reference Manual

Order Number: AA-Q88BG-TE

August 2001

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

Revision/Update Information: This manual supersedes the Reliable Transaction Router Application Programmer's Reference Manual, Version 4.0.

Software Version: Reliable Transaction Router, Version 4.1

Compaq Computer Corporation
Houston, Texas

Compaq, the Compaq logo, AlphaServer, AlphaStation, DECnet, TRUCluster, VAX and VMS Registered in U. S. Patent and Trademark Office.

OpenVMS is a trademark of Compaq Information and Technologies Group, L.P. in the United States and other countries.

Microsoft, MS-DOS, Visual Basic, Visual C++, Windows, and Windows NT are trademarks of Microsoft Corporation in the United States and other countries.
Intel is a trademark of Intel Corporation in the United States and other countries.
UNIX and X/Open are trademarks of The Open Group in the United States and other countries.

All other product names mentioned herein may be trademarks or registered trademarks of their respective companies.

Confidential computer software. Valid license from Compaq or authorized sublicensor required for possession, use or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license.

Compaq shall not be liable for technical or editorial errors or omissions contained herein. The information in this document is provided "as is" without warranty of any kind and is subject to change without notice. The warranties for Compaq products are set forth in the express limited warranty statements accompanying such products. Nothing herein should be construed as constituting an additional warranty.

Contents Index

Preface

Purpose of This Manual

This manual is the reference source for persons writing application programs using Reliable Transaction Router (RTR) in the C programming language. It completely describes the RTR C application programming interface (API), formerly called the Portable API.

Document Structure

This manual contains four chapters and two appendices:

Chapter 1 introduces the RTR C programming interface.
Chapter 2 provides a guide to writing RTR applications.
Chapter 3 describes the RTR C Application Programming Interface (API) showing the syntax and data structures for each RTR call.
Chapter 4 describes how to compile and link your application.
Appendix A provides a short RTR C API sample application.
Appendix B provides a short tutorial for the application programmer.

**Table 1**
Document	Content
For all users:
Reliable Transaction Router Getting Started	Provides an overview of RTR technology and solutions, and defines all RTR terms.
Reliable Transaction Router Release Notes	Describes new features, changes, and known restrictions for RTR.
RTR Commands Card	Lists all RTR commands, their qualifiers and defaults.
For the system manager:
Reliable Transaction Router Installation Guide	Describes how to install RTR on all supported platforms.
Reliable Transaction Router System Manager's Manual	Describes how to configure, manage, and monitor RTR.
Reliable Transaction Router Migration Guide	Explains how to migrate from RTR Version 2 to RTR Version 3 (OpenVMS only).
For the application programmer:
Reliable Transaction Router Application Design Guide	Describes how to design application programs for use with RTR, illustrated with both C++ and C interfaces.
Reliable Transaction Router C++ Foundation Classes	Describes the object-oriented C++ interface that can be used to implement RTR object-oriented applications.

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 2 describes the conventions used in this guide.

Table 2 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, constants, and RTR message types returned by an RTR call.

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.

**Table 2 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, constants, and RTR message types returned by an RTR call.
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.

Reading Path

The reading path to follow when using the Reliable Transaction Router information set is shown in Figure 1.

Figure 1 RTR Reading Path

Chapter 1
Introduction

This chapter introduces the Reliable Transaction Router C programming interface. This interface was formerly called the Portable API. RTR concepts and terms are fully defined in Reliable Transaction Router Getting Started.

1.1 RTR Application Programming Interface

The RTR C application programming interface (API) that is provided with Reliable Transaction Router is identical on all hardware and operating system platforms that support RTR. This API (formerly called the Portable API) is described in the following chapter.

In addition, a command line interface (CLI) to the C API is available. This enables you to write simple RTR applications for testing. The RTR CLI is illustrated in Reliable Transaction Router Getting Started and fully described in the Reliable Transaction Router System Manager's Manual.

1.2 C Programming and OpenVMS APIs

The C programming RTR API was made available in Reliable Transaction Router Version 3. It superseded the OpenVMS API used in Reliable Transaction Router Version 2 for new applications.

1.2.1 Compatibility Between RTR Versions

Reliable Transaction Router Version 3 interoperates with RTR Version 2.2 in a DECnet environment using DECnet Phase IV naming. (The same version of RTR must be installed on all routers and backends. See the section on Network Transports in the Reliable Transaction Router System Manager's Manual to find out how to configure your Version 3 nodes.)

Note that the size of an RTR transaction ID was changed for Reliable Transaction Router Version 3; it is now 28 bytes. (This ensures that the transaction ID contains a unique node specification.)

1.2.2 Reasons for a C Programming API

RTR was first developed for use within an OpenVMS environment. Reliable Transaction Router Version 3 extends the applicability of RTR to allow users to create fault-tolerant distributed applications running on networks of heterogeneous machines and platforms.

The OpenVMS API presented some incompatibilities when used on non-OpenVMS platforms as follows:

The "$" character contained in all RTR identifiers is not permitted in identifiers in some languages.
There was no provision for reformatting user messages passed between machines to account for differing machine representations of particular data types.
RTR permits applications to be written to perform multiple concurrent operations, a feature that can be critical for good performance in high-volume transaction processing systems. The notification mechanisms used to indicate completion of such asynchronous operations (event-flag, txsb, completion-AST) were OpenVMS-specific.

1.2.3 Benefits of the C Programming API

The benefits of using the C programming API are:

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 (little-endian and big-endian, and so forth).
Interoperability with existing applications using the OpenVMS API.
Features extended above those provided by the OpenVMS API.
Improved performance for commonly-used transaction types.
Support for use within a threaded environment.

The C programming API has been designed to:

Avoid the problem of applications dropping threads.
Simplify the API.
Schedule concurrent application operations in the same FIFO manner as is used with AST-driven processing on OpenVMS. This avoids the synchronization worries faced by the application writer when working with ASTs.
Make it impossible for an application to stall by waiting for one operation to complete and hence being unable to respond to some other event.
Permit a more efficient implementation. RTR does not have to maintain multiple internal queues.

1.2.4 Comparison of OpenVMS and C Programming API Calls

Table 1-1 compares the OpenVMS and C Programming API calls.

Table 1-1 OpenVMS API (V2) and C Programming API (V3) Compared
OpenVMS API C Programming API

$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()

**Table 1-1 OpenVMS API (V2) and C Programming API (V3) Compared**
OpenVMS API	C Programming API
$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()

Chapter 2
Overview of the C Programming API

The term C programming API is used to describe the RTR application programming interface (API) adopted in Reliable Transaction Router Version 3. This API is available on all platforms on which Reliable Transaction Router is supported. This API is the erstwhile Portable API.

2.1 Transactional Messages

RTR allows the client and server applications to communicate by entering into a dialogue consisting of an exchange of messages between a client application (the dialogue initiator) and one or more server applications.

Note

In the context of RTR, client and server are always applications.

Each dialogue forms a transaction in which all participants have the opportunity to either accept or reject the whole transaction. When the transaction is complete, all participants are informed of the transaction's completion status: success ( rtr_mt_accepted ) if all participants accepted it, failure ( rtr_mt_rejected ) if any participant rejected it. (For more information on messages, see Section 2.10, RTR Messages.)

2.2 RTR Channels

With RTR, applications can be engaged in several transactions at a time.

To support many in-progress transactions at the same time, RTR lets applications open multiple channels. An application opens one or more channels to RTR, and any transaction is associated with only one channel. The transaction is said to be active on that channel. For example, a client application opens a channel and then sends the first message of a transaction on that channel. All messages sent and received for that transaction are now associated with that channel.

While waiting for a response from the server, the client application can open a second channel and start a new transaction on it. When the transaction on the first channel has completed, the client application may start the next transaction on it, or simply issue the rtr_accept_tx call.

Similarly, a server application may open several channels and, when the first message of a new transaction arrives, RTR delivers it on the first available channel. That channel remains associated with the transaction until it completes.

An application opens a channel before it can send or receive messages; the RTR API call rtr_open_channel is used to do this. The RTR call specifies whether the channel is a client channel or a server channel; it cannot be both. (This restriction helps to simplify application structure, and to deal with the special properties of each channel type.) A single application can, however, open client channels and server channels.

2.3 Broadcast Messages and Events

In addition to transactional messages, client or server programs may broadcast event messages. These are delivered to some subset of the distributed applications, as specified by the event-number and event-name parameters. In contrast to transactional dialogues, no completion status is subsequently returned to the initiator. A message can be from 0 to 64K bytes long.

Both client and server channels receive messages from RTR. A client channel receives event messages only from servers, and a server channel receives event messages only from clients. To enable a client application to receive event/broadcast messages from another client application, the application must be both a client and a server application (open a channel with both CLIENT and SERVER flags), and must be in a facility on a node that is both a frontend and a backend. A broadcast event is sent so long as the server channel is open. Events are more fully described in Section 2.11, RTR Events.

2.4 C Programming API Calls

The C Programming API calls are shown in Table 2-1, C Programming API Calls. Each call is shown with a brief description and whether it can be used on client channels or server channels or both. Calls are listed in alphabetical order.

Table 2-1 C Programming API Calls
RTR Call Description Channel Use

rtr_accept_tx Accepts a transaction Client and server

rtr_broadcast_event Broadcasts (sends) an event message Client and server

rtr_close_channel Closes a previously opened channel Client and server

rtr_error_text Gets the text for an RTR status number Client and server

rtr_get_tid Gets the current transaction ID Client and server

rtr_open_channel Opens a channel for sending and receiving messages Client and server

rtr_prepare_tx Prepares a nested transaction to be committed Client only

rtr_receive_message Receives the next message (transaction message, event or completion status) Client and server

rtr_reject_tx Rejects a transaction Client and server

rtr_reply_to_client Sends a response from a server to a client Server only

rtr_request_info Requests information from RTR Client and server

rtr_send_to_server Sends a message from a client to the server(s) Client only

rtr_set_info Sets an RTR parameter Client and server

rtr_set_user_handle Associates a user value with a transaction Client and server

rtr_set_wakeup Sets a function to be called on message arrival Client and server

rtr_start_tx Explicitly starts a transaction Client only

**Table 2-1 C Programming API Calls**
RTR Call	Description	Channel Use
rtr_accept_tx	Accepts a transaction	Client and server
rtr_broadcast_event	Broadcasts (sends) an event message	Client and server
rtr_close_channel	Closes a previously opened channel	Client and server
rtr_error_text	Gets the text for an RTR status number	Client and server
rtr_get_tid	Gets the current transaction ID	Client and server
rtr_open_channel	Opens a channel for sending and receiving messages	Client and server
rtr_prepare_tx	Prepares a nested transaction to be committed	Client only
rtr_receive_message	Receives the next message (transaction message, event or completion status)	Client and server
rtr_reject_tx	Rejects a transaction	Client and server
rtr_reply_to_client	Sends a response from a server to a client	Server only
rtr_request_info	Requests information from RTR	Client and server
rtr_send_to_server	Sends a message from a client to the server(s)	Client only
rtr_set_info	Sets an RTR parameter	Client and server
rtr_set_user_handle	Associates a user value with a transaction	Client and server
rtr_set_wakeup	Sets a function to be called on message arrival	Client and server
rtr_start_tx	Explicitly starts a transaction	Client only

2.5 Programming Examples

The following pseudocode examples of a client and a server application illustrate the use of the C programming API. Details have been omitted to keep the basic structure clear.

2.5.1 Simple Client

This simple client program issues transactions and receives event messages. It simply issues one transaction, waits for it to be processed, and in the meantime handles any events that arrive. It then issues the next transaction. It does not need to wait until one transaction finishes before starting the next.

The following two examples are single-threaded. They can be made multithreaded by opening more channels. The structure of the main receive loop does not need to be changed to implement this. Note that rtr_receive_message receives the next message in the process input queue for any of the channels opened by the program (unless preferred channels have been requested in the rtr_receive_message .

Example 2-1 Example Client

rtr_open_channel() ! Open a channel to the required facility rtr_receive_message() ! Get the completion status of the open call ! success returns rtr_mt_opened send_loop: rtr_send_to_server( ...RTR_F_SEN_ACCEPT....) ! Send a tx-message and ! implicitly start a new tx rcv_loop: rtr_receive_message() ! Find out what RTR wants to tell us next switch (message_received_type) { case rtr_mt_reply: Process_Reply_from_Server; break; case rtr_mt_rtr_event: Process_RTR_Event; break; case rtr_mt_user_event: Process_User_Event; break; case rtr_mt_accepted: Tell_User_It_Worked; break; case rtr_mt_rejected: Tell_User_About_Failure; break; } IF ( message_received_type = rtr_mt_accepted ) OR ( message_received_type = rtr_mt_rejected ) THEN GOTO send_loop ! Last transaction done, issue the next one ELSE GOTO rcv_loop ! Get the next incoming message

In Example 2-1, note that the switch statement tests on message type. All messages that are received from RTR have a message type; for further information, see Section 2.10.

Contents

Index