Reliable Transaction Router

Reliable Transaction Router

C++ Foundation Classes

Order Number: AA-RLE0A-TE

August 2001

This manual provides detailed information on the C++ object-oriented application programmer's interface for Reliable Transaction Router.

Revision/Update Information: This is a new manual.

Software Version: Reliable Transaction Router Version 4.1

Compaq Computer Corporation
Houston, Texas

© 2001 Compaq Computer Corporation

Compaq, the Compaq logo, DEC, and VAX Registered in the United States Patent and Trademark Office.

DECnet, OpenVMS, and Tru64 are trademarks of Compaq Information Technologies Group, L.P.

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

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 publication is subject to change without notice and is provided "AS IS" WITHOUT WARRANTY OF ANY KIND. THE ENTIRE RISK ARISING OUT OF THE USE OF THIS INFORMATION REMAINS WITH RECIPIENT. IN NO EVENT SHALL COMPAQ BE LIABLE FOR ANY DIRECT, CONSEQUENTIAL, INCIDENTAL, SPECIAL, PUNITIVE, OR OTHER DAMAGES WHATSOEVER (INCLUDING WITHOUT LIMITATION, DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, OR LOSS OF BUSINESS INFORMATION), EVEN IF COMPAQ HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. THE FOREGOING SHALL APPLY REGARDLESS OF THE NEGLIGENCE OR OTHER FAULT OF EITHER PARTY AND REGARDLESS OF WHETHER SUCH LIABILITY SOUNDS IN CONTRACT, NEGLIGENCE, TORT, OR ANY OTHER THEORY OF LEGAL LIABILITY, AND NOTWITHSTANDING ANY FAILURE OF ESSENTIAL PURPOSE OF ANY LIMITED REMEDY.

The limited warranties for Compaq produces are exclusively set forth in the documentation accompanying such products. Nothing herein should be construed as constituting a further or additional warranty.

Contents Index

Preface

Purpose of this Manual

This document describes the C++ interface for the Reliable Transaction Router (RTR) in which RTR concepts are represented as individual classes. The flexibility and extensibility of these classes enable existing as well as new applications to use features that were otherwise unavailable. This application programming interface (API) is backward-compatible with existing RTR applications.

Programming Requirements

Programs using the C++ API require the following files:

NT platform:
File Description
rtrapi.h Header file defining RTR classes
rtrapicpp.lib Library file that applications link against to make use of the RTRAPI
rtrapicpp.dll Library used by all RTR applications using RTR V4.0

UNIX platforms:
File Description
rtrapi.h Header file defining RTR classes
rtrapicpp.so File used by all RTR applications using RTR V3.2 or later

OpenVMS platforms:
File Description
rtrapi.h Header file defining RTR classes
rtrapicpp_shr.exe File used by all RTR applications using RTR V3.2 or later

Document Structure

Related Documentation

Additional resources in the RTR documentation kit include:
Document Description
Reliable Transaction Router Getting Started Provides an overview of RTR technology concepts and solutions.
Reliable Transaction Router Application Design Guide Provides design guidelines for implementing RTR client and server applications.
Reliable Transaction Router C Application Programmer's Reference Manual Explains how to design and code RTR applications; contains full descriptions of the RTR API calls for the C programming language.
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.
Reliable Transaction Router Installation Guide Describes how to install RTR.
Reliable Transaction Router Release Notes Describes new features, changes, and known restrictions for RTR.

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

Each class section includes member tables listing all inherited methods. The methods are in alphabetical order and provide argument types in the method column. For the argument names, see the individual method sections, which follow each class member table in alphabetical order.

The name of each method shows the class from which the method derives. For example, RTRServerTransactionController::Receive shows that the Receive method derives from the RTRServerTransactionController class.

The Prototype sections list each method with its arguments, argument types, and return types. The Return Value sections that follow contain return value information.

For each class, destructors are listed without comment along with the respective constructor. Only when there is associated behavior (an effect on another object) is there a note on a destructor.

The following table lists the typographic conventions in this manual.
Convention Description
User Input User input and programming examples are shown in a monospaced font.
Parameter Parameters you can change are shown in italics . Italics are also used for titles and chapters of manuals and books.
FE RTR Frontend
TR RTR Router
BE RTR Backend

Reading Path

Figure 1 RTR Reading Path

Chapter 1
C++ API Concepts

This chapter provides an overview of the RTR C++ foundation classes and describes concepts that apply to application development using this application programming interface (API). It includes conceptual descriptions of client and server interaction and application processing. Detailed information is provided on each class and its associated methods in later chapters of this manual. For code examples and implementation information, see the Design and Implementation chapter of this manual.

1.1 Overview

The C++ foundation classes enable you to implement new RTR client and server applications, or to integrate specific classes into existing applications to add additional functionality.

RTR concepts have been mapped to and implemented by the set of foundation classes for handling system management and the needs of business applications.

Figure 1-1 shows the C++ foundation classes. Management classes represent RTR, facilities, partitions, and key segments (part of the partitioning classes in Figure 1-1 whereas application classes represent transactions, data, messages and events.

The primary application classes include client classes, server classes, and data classes that are common to both client and server classes. There are also server and client transaction property classes.

You use management classes to implement applications that can help manage RTR. You use application classes to implement client and server applications. However, client and server applications can also use the management classes to dynamically set up RTR facilities and partitions.

Figure 1-1 C++ Foundation Classes

Facility, partition, and transaction property classes include methods that provide access to facilities, partitions, and transactions. These classes enable a program to obtain additional information on a facility, partition, or a transaction. Transaction property classes are useful for transaction recovery and for obtaining and setting transaction states.

Property classes work with other foundation classes in new applications; they can also be used independently in legacy RTR applications. They do this by using information that existing RTR applications already have, including transaction IDs (tids), facility names, and partition names.

1.2 Application Classes

RTR C++ foundation application classes include:

(Client and server transaction property classes are included within the client application classes and server application classes, respectively.)

To use RTR application classes, it is useful to understand RTR concepts necessary for implementing application solutions with the C++ API, C++ API- specific information, and object-oriented concepts.

Figure 1-2 illustrates the client and server classes and the paths through which they typically communicate. (There are design alternatives to the illustrated path.) TransactionController objects control transactions. Communication between client and server applications is through messages and events sent and received by the RTR application. Data objects (instances of data classes) carry these messages and events between RTR clients and servers.

Figure 1-2 C++ API Classes

The principal application classes are the transaction controller classes and data classes. A transaction controller object manages a transaction. The RTRData-derived data object is the common means through which client and server applications interact. A message handler encapsulates the data. Most events are not related to transactions. A message is sent from a client to a server or a server to a client (1-to-1). An event can go from one client or server to many clients and servers.

1.2.1 Transaction Classes

In RTR, a transaction is a logical grouping of messages.

A transaction is controlled by a TransactionController object. The client transaction controller class (RTRClientTransactionController) creates single instances of a transaction. The server transaction controller class (RTRServerTransactionController) manages single instances of a transaction.

A transaction controller object:

Typically, a transaction controller object processes multiple consecutive transactions, but there is at most one active transaction in a transaction controller object at any one time.

A transaction controller:

1.2.2 Data Classes

Applications use data objects to carry data between RTR clients and servers. Thus, the data classes are common to both client and server applications. RTRData is the base class from which four kinds of data are derived:

The class factory, RTRClassFactory, creates instances of data classes based on the content of a transaction controller Receive call for a message or event.

Communication between client and server applications is through messages and events. Data objects contain these messages and events sent and received by RTR clients and servers.

Figure 1-3 illustrates the data classes and their relationships to the RTRData base class and a memory buffer. For example, the base class of RTRStream is RTRData and the base class of RTRApplicationMessage is RTRStream.

Figure 1-3 Data Classes

An application wanting to send or receive data specifies an RTRData object. The mechanism for sending and receiving is different as follows:

After a successful call to the Receive method, the RTRData pointer contains one of the following kinds of objects:

The RTRClassFactory class creates the above data objects. Based on the type of message contained on the transaction controller Receive call the class factory creates an instance of the appropriate data class. The class factory also enables you to customize the behavior of data object creation. An application may derive its own RTRClassFactory class and register it with the transaction controller. In this case, the transaction controller calls the application's class factory to create the data object.

Dispatch Methods and Handlers

Since all Data classes are derived from RTRData, an application can treat the data polymorphically, especially when receiving data on the server.

For example: 


ServerTransactionController ServerTransactionController; 
RTRData *pDataBeingReceived = NULL; 
while (true) 
{ 
// Receive some data 
ServerTransactionController.Receive(&pDataBeingReceived); 
// No need to determine what we received. 
// Just call Dispatch() 
pDataBeingReceived->Dispatch(); 
}

The RTRData class has a pure virtual method named Dispatch(). This means that all classes derived from RTRData provide an implementation of Dispatch(). This implementation of Dispatch, which is provided by the derived class, determines the exact message or event number that it contains and calls the appropriate method in the handler.

The message and event handler classes are:

An application may derive its own class from any or all of these handlers to provide its own custom handling of the specific messages and events.

1.2.3 Messages

Data objects carry messages between clients and servers. These messages are of two types:

1.2.4 Events

Data objects carry events between clients and servers. These events are of two types:

Application events can be transmitted only within the RTR facility in which they are defined. Application events cannot be sent between facilities or outside RTR.

1.2.5 Client and Server Interaction

For client and server applications to work together, you create a
ClientTransactionController in the client application and a ServerTransactionController in the server application. These transaction objects communicate by using objects derived from the RTRData class.

RTR applications need to define an application-level protocol to pass data between client and server. From the point of view of a client or server application, the application protocol is just data. The data object encapsulates the application protocol as shown in Figure 1-4. In this example, a protocol is defined for sending data between a client and server application that processes book orders, as in the book ordering sample application. This data protocol includes fields for ISBN number, book-price, book-name, and author. These fields are contained in a buffer in an RTRData object.

The data protocol is encapsulated in a user-defined ApplicationProtocol class. The ApplicationProtocol class is an (derives from) RTRApplicationMessage, which is an (derives from) RTRStream, which is an (derives from) RTRData object that contains the application protocol in its buffer.

Figure 1-4 RTRData Encapsulation

The data classes are used by both client and server RTR applications. When applications want to send or receive data, they specify an RTRData-derived object.

Figure 1-5 illustrates client/server deployment and interaction. The numbered steps represent client logic within the client application and server logic within the server application. For a more detailed description of transactional messaging, see the RTR Application Design Guide.

Figure 1-5 Client/Server Interaction

An RTR transaction processing system consists of separate client applications and server applications. This example demonstrates a client sending a message to the server and the server responding, but the server calls the first Receive. The logical interaction between client and server is as follows:

  1. Call Receive from an RTRServerTransactionController object to obtain an RTRApplicationMessage object from the client. (The server first creates an RTRServerTransactionController object and then calls Receive.)
  2. Create a transaction in the RTRClientTransactionController object by calling StartTransaction.
  3. Create an RTRApplicationMessage object (or one derived from RTRApplicationMessage).
  4. Send the RTRApplicationMessage object to the server and wait for a message from the server by calling SendApplicationMessage.
  5. Process the data in the server application.
  6. Send an RTRApplicationMessage object from the server back to the client by calling SendApplicationMessage.

For more information on client and server messaging, see the RTR Application Design Guide.

1.2.6 The Class Factory

An instance of the class RTRClassFactory is an object that creates other data objects. The class RTRClassFactory has four methods:

Client and server transaction controllers use the class factory when receiving a message or event. Every transaction controller has a class factory. If the application does not register its own, a default is provided.

When the application calls Receive, the transaction controller determines what kind of message or event is about to be received, and then calls the appropriate method in the application-derived and registered class factory object (for example, CreateRTRMessage). This method creates the appropriate data object (for example, an RTRMessage object) and returns it to the transaction controller. The transaction controller copies the incoming data into the data object returned from the class factory and returns back to the application's call to Receive().

Applications can override the methods of the RTRClassFactory and return their own customized versions of the data classes.

Receiving an Application Message

Typical client requests processed by a server application are sent and received as RTRApplicationMessage objects. The most common method for implementing business logic data protocols is deriving from the RTRApplicationMessage class. In Figure 1-6, AM represents an incoming application message.

Figure 1-6 Receiving an Application Message

In Figure 1-6:

  1. An application calls a transaction controller Receive (for example, RTRServerTransactionController::Receive) to receive a message or event (AM, in the above figure).
  2. The transaction controller determines what kind of message or event is to be received (in this case, an application message) and calls the appropriate method in the registered RTRClassFactory object (for example, CreateRTRApplicationMessage).
  3. The RTRClassFactory object CreateRTRApplicationMessage method creates the appropriate data object (in this case, an RTRApplicationMessage object) and returns it to the transaction controller.
  4. The application processes the message according to the application implementation.

Receiving a User-Defined Application Message

User-defined application messages are sent and received as RTRApplicationMessage objects. In Figure 1-7: Receiving a User-Defined Application Message, AM represents an incoming application message.

Figure 1-7 Receiving a User-Defined Application Message

In Figure 1-7:

  1. An application calls a transaction controller Receive (for example, RTRServerTransactionController::Receive) to receive a message or event (AM, in the above figure).
  2. The transaction controller determines what kind of message or event is to be received (in this case, an application message) and calls the appropriate method in the application-derived and registered ABCClassFactory object (for example, CreateApplicationMessage).
  3. The ABCClassFactory object CreateApplicationMessage method creates the appropriate data object (in this case, an ABCOrder object) and returns it to the transaction controller.
  4. The application processes the message according to the application implementation.

Note that the derived class factory does not have to handle the all messages. It is only handling the application message (AM) and taking all of the other default methods (for example, CreateRTRMessage).

Next Contents Index