# hp Reliable Transaction Router
C++ Foundation Classes

Previous | Contents | Index

## 1.4.2 Polling Model

Figure 1-13 shows the steps in the polling model of transaction processing as used in a client application.

Figure 1-13 Polling Processing Model

The polling model processing steps are:

1. Create an environment that has one or more partitions defined in key segments.
2. Create a transaction controller object.
3. Call Register methods to register facility (for client) and partitions (for server) and class factory.
4. Call Receive to check the data object.
5. In place of Dispatch, start gathering information for the partition on RTR by calling RTRData methods such as IsApplicationMessage, IsMessage, and IsEvent (for a full listing of boolean RTRData methods, see the Application Classes chapter of this manual) to determine what type of data is being received in order to process it.
   User-implemented logic handles all possible messages, events, and serialized objects using RTRData methods.
6. Call Receive again.

In the polling model, you create a receive loop to poll for incoming data. Messages or events are received one at a time, and Register does not connect message and event handlers. The server asks RTR for a request.

You can still check the data object and code tasks as follows:

- Create the polling loop logic.
- In place of Dispatch, detect the incoming data type using the RTRData methods IsApplicationData, IsMessage, and IsEvent. If you call Dispatch, RTR responds that there are no handlers.
- In place of the Handler classes, you must develop logic to handle all possible RTR and application messages, events, and serialized objects using RTRData methods such as GetBuffer, GetMessageType, and GetEventNumber. These methods are used in the Dispatch call.

As Figure 1-13 illustrates, in common with the event driven model, you use a subset of the same objects, but Register does not connect the message and event handlers.

Polling Model Example

Example 1-2 illustrates an implementation for the polling model of processing. As this example illustrates, the flow is controlled by the object that is polling for a message or event from RTR with Receive.

Example 1-2 Polling Model Example

    ServerTransactionController ServerTransactionController;
    RTRData *pDataBeingReceived = NULL;
    while (true){
    // Receive some data
    ServerTransactionController.Receive(&pDataBeingReceived);
    // Since handlers are not being used, determine what is
      // received. Application-generated message or event.
      // RTR-generated message or event.
    if (true = pDataBeingReceived->IsApplicationMessage())
    {
      // Process accordingly
    }
    else
    if (true = pDataBeingReceived->IsApplicationEvent())
    {
      // Process accordingly
    }
    else
    if (true = pDataBeingReceived->IsRTRMessage())
    {
      // Process accordingly
    }
    else
    if (true = pDataBeingReceived->IsRTREvent())
    {
      // Process accordingly
    }
    }

# 1.5 Base Classes Message and Event Mapping

The foundation class message and event handler methods are provided in base classes. You derive from them and choose which ones to use in your implementation. Base handlers are used by default, if you do not derive from them.

Figure 1-14 illustrates RTR messaging between client and server. RTR messages are contained in the data object passing between the client and server. With event-driven processing, the class factory creates the appropriate data object.

Figure 1-14 RTR Messaging Between Client and Server Applications

To connect, the client registers a facility and the server registers a facility and a partition. The client transaction ends with rtr_mt_accepted or rtr_mt_rejected. The server transaction ends with the AcknowledgeTransactionOutcome method.

When Dispatch is called, certain handlers are called for transactions on the client and server, as shown in the following tables.

## 1.5.1 Client Messages

When Dispatch is called, certain handlers are called for transactions on the client, as shown in Table 1-6.

Table 1-6 Client Handlers by Message Type
When the RTR Message Type is: | Contained in: | The RTRClientMessageHandler Call is:
--- | --- | ---
rtr_mt_accepted | RTRMessage | OnAccepted
rtr_mt_reply | RTRApplicationMessage | OnApplicationMessage
rtr_mt_rttosend | RTRMessage | OnReturnToSender
rtr_mt_prepared | RTRMessage | OnAllPreparedTransaction
rtr_mt_rejected | RTRMessage | OnRejected

For example, using the event-driven processing model, when RTRData contains rtr_mt_reply, by default, the RTRApplicationMessage Dispatch method calls OnApplicationMessage.

## 1.5.2 Client Events

When Dispatch is called, certain handlers are called for transactions on the client, as listed in Table 1-7.

Table 1-7 Client Handlers by Event for RTREvent
When the RTR Event Number is: | The RTRClientEventHandler Call is:
--- | ---
RTR_EVTNUM_FACDEAD | OnFacilityDead
RTR_EVTNUM_FACREADY | OnFacilityReady
RTR_EVTNUM_FERTRGAIN | OnFrontendGainedLinkToRouter
RTR_EVTNUM_FERTRLOSS | OnFrontendLostLinkToRouter
RTR_EVTNUM_RTRBEGAIN | OnRouterGainedLinkToBackend
RTR_EVTNUM_RTRBELOSS | OnRouterLostLinkToBackend
RTR_EVTNUM_KEYRANGEGAIN | OnNewKeyRangeAvailable
RTR_EVTNUM_KEYRANGELOSS | OnKeyRangeNoLongerAvailable

For example, with the event-driven processing model, when RTRData contains RTR_EVTNUM_FACREADY, by default, the RTREvent Dispatch method calls OnFacilityReady.

## 1.5.3 Server Messages

When Dispatch is called, certain handlers are called for transactions on the server side, as listed in Table 1-8.

Table 1-8 Server Handlers by Message Type
When the RTR Message Type is: | Contained in: | The RTRServerMessageHandler Call is:
--- | --- | ---
rtr_mt_accepted | RTRMessage | OnAccepted
rtr_mt_msg1 | RTRApplicationMessage | OnInitialize
|  | OnApplicationMessage
rtr_mt_msg1_uncertain | RTRApplicationMessage | OnUncertainTransaction
rtr_mt_msgn | RTRApplicationMessage | OnApplicationMessage
rtr_mt_prepare | RTRMessage | OnPrepareTransaction
rtr_mt_rejected | RTRMessage | OnRejected

For example, with the event-driven processing model, by default when RTRData contains rtr_mt_msg1, the RTRServerMessageHandler first calls OnInitialize and then calls OnApplicationMessage. With the polling model, use IsMessage in place of Dispatch and implement GetMessageType to handle the message.

A typical series of Server messages processed for a Transaction in an RTRTransactionController object would be as follows:

- Start the loop and execute the following receives:

      OnInitialize
      OnApplicationMessage
      OnPrepareTransaction
      OnAccepted

- Loop again and get another transaction.

## 1.5.4 Server Events for RTREvent

When Dispatch is called, certain handlers are called for transactions on the server side, as listed in Table 1-9.

Table 1-9 Server Handlers by Event
When the RTR Event Number is: | The RTRServerEventHandler Call is:
--- | ---
RTR_EVTNUM_BERTRLOSS | OnBackendGainedLinkToRouter
RTR_EVTNUM_BERTRGAIN | OnBackendGainedLinkToRouter
RTR_EVTNUM_FACDEAD | OnFacilityDead
RTR_EVTNUM_FACREADY | OnFacilityReady
RTR_EVTNUM_RTRFEGAIN | OnFrontendGainedLinkToRouter
RTR_EVTNUM_RTRFELOSS | OnFrontendLostLinkToRouter
RTR_EVTNUM_SRSHADOWGAIN | OnServerGainedShadow
RTR_EVTNUM_SRSHADOWLOST | OnServerLostShadow
RTR_EVTNUM_SRRECOVERCMPL | OnServerRecoveryComplete
RTR_EVTNUM_SRPRIMARY | OnServerIsPrimary
RTR_EVTNUM_SRSECONDARY | OnServerIsSecondary
RTR_EVTNUM_SRSTANDBY | OnServerIsStandby

For example, with the event-driven processing model, by default, when RTRData contains RTR_EVTNUM_FACREADY, the RTRServerEventHandler calls OnFacilityReady. With the polling model, use IsEvent in place of Dispatch, and implement GetEventNumber to handle the event.

For more information, see the state diagrams in Appendix C of the RTR Application Design Guide.

# 1.6 Using the C++ API with Existing Applications

When working with existing RTR applications, you can integrate individual C++ foundation classes into existing client or server applications and also write new management routines that work with existing applications. With the C++ foundation classes, there are no migration issues. There is no need to rewrite existing code to integrate C++ foundation classes. Existing client and server applications are linked transparently by RTR .

In existing applications, objects defined in the application can point to instances of foundation classes.

These classes are designed to be used:

- With other foundation classes
- Independently in legacy RTR applications (property classes are constructable from legacy applications)

Objects defined in your application can point to instances of the foundation classes, and inherit the rich functionality within these base classes.

The C++ foundation classes provide a method for implementing RTR solutions that is easier to use than the C API. The C++ foundation classes:

- Replaces RTR structures with easily manageable classes. You no longer need to master complex structures and flags, a common cause of programming errors. These structures and flags are not part of the foundation classes.
- Replaces all flags with Get/Set methods. This completely eliminates the use of channels in new implementations.
- Provides for transparent creation and use of channels using the transaction controller classes, RTRServerTransactionController and RTRClientTransactionController.
- Provides default handling code for all messages and events where appropriate. Formerly, an application had to provide handling for all messages and events and could not write common processing code.
- Abstracts the sending and receiving of data to a higher level. Sending and receiving data is no longer handled at a low level. The foundation classes eliminate coding for buffers and links.
- Transforms the features of `rtr_request_info()` and `rtr_set_info()` into simple methods of RTR classes. `rtr_request_info()` and `rtr_set_info()` calls require internal knowledge of RTR data structures. The C++ API obtains this information without the application needing to know the internals of RTR.
- Represents each major RTR concept in its own individual class.

## 1.6.1 Classes that Legacy Applications Can Use

Table 1-10 lists the classes that legacy RTR server applications can use to create and manage the environment in which RTR applications run. The second column of Table 1-10 lists the information required to implement instances of these classes.

Table 1-10 Foundation Classes for Legacy Applications
Class | Requires:
--- | ---
Setup class: |
RTR | Nothing
Facility classes: |
RTRFacilityManager | Facility Name
RTRFacilityMember | Facility Name
Partition classes: |
RTRPartitionManager | Nothing
RTRKeySegment | Nothing
Property classes: |
RTRClientTransactionProperties | TID (Transaction ID)
RTRServerTransactionProperties | TID
RTRBackendPartitionProperties | Partition Name
RTRFacilityProperties | Facility Name
Diagnostic class: | Nothing (for new applications)
RTRCounter | Group Name

Facility, management, and partition information exists in RTR. The methods within the management and property classes rely on attributes that RTR applications have.

For example, the diagnostic class RTRCounter relies on the following attributes for getting information:

- Group name
- Counter name
- Data type

These are all attributes found in RTR.

The RTRBackendPartitionProperties class relies on partition name and facility name; existing applications already know the partition name. This enables you to call methods, such as GetRetryCount, in this class by passing in a partition. For example:

    RTRBackendPartitionProperties MyPartition("MyPartitionName");
    MyPartition.GetRetryCount();

## 1.6.2 Encapsulating Application Protocols

Since foundation classes work with existing applications, the protocol for passing data has not changed. As Figure 1-15 illustrates, legacy applications and new applications both use the same protocol for passing data. Thus, all combinations of old and new clients and servers can communicate with each other.

Figure 1-15 C++ API into Existing Applications

The protocol manager represents an object that knows how to send and receive a protocol defined by the application. The protocol is your data. This is achieved by deriving a class from RTRData that knows how to store information (data) in it. RTRData does this by pointing to a buffer.

Figure 1-16 illustrates an example of data encapsulation in the protocol manager objects that are shown in Figure 1-15.

Figure 1-16 The Protocol Manager Object

For more information on defining a class that encapsulates an application protocol, see the Design and Implementation chapter of this manual.

## 1.6.3 Implementation Example

In the example shown in Figure 1-17, there is an existing server application and a new client application. To have your existing RTR legacy server application communicate with and obtain information from a new C++ client application, you do not need to integrate C++ foundation classes into your server application.

Figure 1-17 Legacy Application Example

Legacy applications do not have a TransactionController but with the RTRServerTransactionProperties and RTRClientTransactionProperties classes, you need only a TID (transaction identifier) to get state information. You obtain the TID with the existing RTR C API using the rtr_get_tid method. You can pass this TID into the RTRServerTransactionProperties and RTRClientTransactionProperties classes.

By using the rtr_get_tid method of the RTR C API to get the TID, you can pass this value to the new C++ API to construct a ServerTransactionProperties object, with this TID as the parameter (ServerTransactionProperties(TID)). Creating an application with this ServerTransactionProperties object enables you to call any member functions within the ServerTransactionProperties class, such as GetTransactionState and GetFacility.

# 1.7 Compiling and Linking your Application

All client and application programs must be written using C, C++, or a language that can use RTR C++ API calls. Include the RTR data types and error messages file rtrapi.h in your compilation so that it will be appropriately referenced by your application. For each client and server application, your compilation/link process is as follows:

1. Write your application code using RTR calls.
2. Use RTR data and status types for cross-platform interoperability.
3. Compile your application code calling in rtrapi.h using ANSI C include rules. For example, if rtrapi.h is in the same directory as your C++ code, use with the following statement: #include "rtrapi.h".
4. Link your object code with the RTR library to produce your application executable.

This process is illustrated in Figure 1-18. In this figure, Library represents the RTR C++ API shareable images (OpenVMS), DLLs (Win32), and shared libraries (UNIX).

Figure 1-18 RTR Compile Sequence

The following command lines show the sort of command lines that are needed to compile and link a C++ RTR application that uses the C++ foundation classes, with and without Posix or Microsoft threads. The parts of the command relating to RTR and the parts relating to threads are shown. You may need to specify library directories explicitly if the RTR header files and libraries are not installed in the same directory or in system directories. Note that the exact name of the RTR foundation classes shared library, DLL or shareable image file, and how it is referenced in a command line, varies slightly according to the conventions for the particular platform. Most compilers recognize the extensions .cc .cpp and .cxx for C++ source files.

- Compaq C++ for OpenVMS, single threaded application:

      $ cxx yourapp.cxx
      $ cxxlink yourapp,sys$input/opt
      librtrcpp/share
      $

- Compaq C++ for OpenVMS 7 Alpha, multi-threaded application:

      $ cxx yourapp.cxx
      $ cxxlink yourapp,sys$input/opt
      librtrcpp_r/share
      $

- Windows MSVC (always multithreaded):

      > cl /c  -D_MT yourapp.cpp
      > link yourapp.obj /out:yourapp.exe rtrcppapi.lib

- Compaq C++ for Tru64 UNIX (also available for Linux Alpha), single threaded:

      % cxx yourapp.cc -o yourapp -lrtrcpp

- Compaq C++ for Tru64 UNIX (also available for Linux Alpha), multi-threaded:

      % cxx -pthread yourapp.cc -o yourapp -lrtrcpp

Compilers commonly used in developing RTR applications include those in the following table. For additional information, see the Reliable Transaction Router Software Product Description.

Operating System | Compiler | Compiler Version
--- | --- | ---
Microsoft Windows | Microsoft Visual C++ | Version 6.0 SP5
OpenVMS Alpha | Compaq C++ | Version 6.2-035
Sun Solaris | Sun Workshop 6 | Update 1
Tru64 UNIX | Compaq C++ | Version 6.3-008

Previous | Next | Contents | Index