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.

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.

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 SP4
OpenVMS Alpha	Compaq C	Version 6.2-006
	Compaq C++	Version 6.2-035
OpenVMS VAX	Compaq C	Version 6.2-003
Sun	Workshop Compilers	Version 4.2
Tru64 UNIX	Compaq C	Version 6.3-126
	Compaq C++	Version 6.2-033