Order Number: AA-RLE0B-TE

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

Revision/Update Information: This manual supersedes the Reliable Transaction Router C++ Foundation Classes manual for Version 4.0.

Software Version: Reliable Transaction Router Version 4.2

Hewlett-Packard Company
Palo Alto, California

© 2003 Hewlett-Packard Development Company, L.P.

Microsoft, MS-DOS, Windows, and Windows NT are US registered trademarks of Microsoft Corporation. Intel is a US registered trademark of Intel Corporation. UNIX is a registered trademark of The Open Group.

Confidential computer software. Valid license from HP and/or its subsidiaries 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 commercial license.

Neither HP nor any of its subsidiaries shall 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 HP 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

Purpose of this Manual

This document describes the C++ interface for 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

• Chapter 1, C++ API Concepts
  Overview of the C++ Foundation classes and introduction to RTR application concepts. Includes C++ Foundation Class concepts and terminology and introduces RTR transactional messaging concepts for C++ API client and server applications.
  This chapter also includes a section on how to use C++ foundation classes with legacy or existing applications.
• Chapter 2, Design and Implementation
  Covers client and server application design and implementation. Provides foundation class overloading examples and design concepts.
• Chapter 3, Application Classes
  Lists all foundation class application classes and their inherited methods. Includes separate sections for server, client, and common data classes.
• Chapter 4, Management Classes
  Lists all C++ API management classes and their inherited methods.
• Chapter 5, Sample Application Tutorial
  Provides a walkthrough of the basics of RTR with the C++ API book-processing sample application that is included in the examples directory of the RTR kit.
• Chapter 6, Sample Application Code
  Provides a sample application with a brief description of its components.
• Appendices
  Two appendices offer class and application design diagrams.

Related Documentation

Table 1 describes RTR documents and groups them by audience.

Table 1 RTR Documents

Document	Content
For all users:
Reliable Transaction Router Release Notes 1	Describes new features, changes, and known restrictions for RTR.
Reliable Transaction Router Getting Started	Provides an overview of RTR technology and solutions, and includes the glossary that defines all RTR terms.
Reliable Transaction Router Commands	A pocket-sized handbook that lists all RTR commands, their qualifiers and defaults.
Reliable Transaction Router Software Product Description	Describes product features.
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 2	Explains how to migrate from RTR Version 2 to RTR Version 3 or 4 (OpenVMS only).
For the application programmer:
Reliable Transaction Router Application Design Guide	Describes how to design application programs for use with RTR, 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.
Reliable Transaction Router C Application Programmer's Reference Manual	Explains how to design and code RTR applications using the C programming language and the RTR C API. Contains full descriptions of the basic RTR API calls.

You can find additional information about RTR, including the Software Product Descriptions, on the RTR website found through http://www.hp.com links to middleware products or at http:://www.hp.com/go/rtr.

Conventions

The following conventions have been adopted in this manual:

• 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 typographic conventions used in this manual are the following:

Convention	Description
Code Example	Programming examples and user input are shown in a monospaced font.
Parameter	Parameters you can change are shown in italics. Italics are also used for titles of manuals.
FE	RTR Frontend
TR	RTR Router
BE	RTR Backend

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

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

• Client application classes
• Server application classes
• Data classes
  Data classes are common classes for passing data between client and server applications.

(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:

• Handles the sending and receiving of a specific data object.
• Votes to accept or reject a transaction.

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:

• Contains at most one transaction at a time (0 or 1).
• Is typically constructed once and reused for each transaction.
• Controls the transaction.
• Processes one transaction at a time. For example, if you need 50 concurrent transactions (at the same time), you need 50 transaction controllers.
• Comes in a client and a server version.

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:

• RTRMessage
• RTREvent
• RTRApplicationMessage
• RTRApplicationEvent

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:

• Sending
  When calling SendApplicationMessage on a transaction controller, the caller specifies an RTRApplicationMessage.
• Receiving
  When calling the Receive method, the application supplies an RTRData pointer to NULL. When the transaction controller determines the type of data which is about to be obtained it calls a class factory to create an instance of the appropriate object.

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

• RTRMessage, containing an RTR-generated message
• RTREvent, containing an RTR-generated event
• RTRApplicationMessage, containing an application-generated message
• RTRApplicationEvent, containing an application-generated event

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:

• RTRServerMessageHandler
• RTRServerEventHandler
• RTRClientMessageHandler
• RTRClientEventHandler

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:

• RTR-generated messages such as rtr_mt_rejected (the transaction has been rejected).
• Application-generated messages (the protocol that drives application business logic).

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

• RTR-generated events such as RTR_EVTNUM_SRPRIMARY (server is in primary state for a registered partition).
• Application-generated events (the protocol that drives application business logic).

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.