# hp Reliable Transaction Router
C++ Foundation Classes

Previous | Contents | Index

# 3.10 RTRClientTransactionProperties

This class holds the properties of its associated RTRServerTransaction object.

# RTRClientTransactionProperties Class Members

Construction

Method | Description
--- | ---
RTRClientTransactionProperties() | Constructor
~RTRClientTransactionProperties() | Destructor

# RTRClientTransactionProperties()

## RTRClientTransactionProperties::RTRClientTransactionProperties();

## Prototype

>     RTRClientTransactionProperties();
>     virtual ~RTRClientTransactionProperties();

## Return Value

> None

## Parameters

> None

## Description

> This class holds the properties of its associated RTRClientTransaction object.

## Example

>     RTRClientTransactionProperties::RTRClientTransactionProperties();
>     {
>     }

# 3.11 Data Classes and the Class Factory

The data classes of the C++ API are common to both server and client applications. There classes include:

- RTRData
- RTRApplicationMessage
- RTRApplicationEvent
- RTRMessage
- RTREvent
- RTRClassFactory
- RTRStream

The RTRData class is the base class of all the C++ foundation class data classes. When applications want to receive data they specify Pointer to an RTRData object. After a successful call to the Receive method in either the client or server RTRtransactionController class, RTRData contains one of the following:

- RTRMessage
- RTREvent
- RTRApplicationMessage
- RTRApplicationEvent

The data classes are common to both client and server applications.

The RTRStream class is an RTRData-derived class designed for
RTRApplicationMessage and RTRApplicationEvent data objects to read from and write to a buffer.

The RTRClassFactory class creates instances of data classes based on the contents of a Receive call for a message or event. For more information on RTR message and event processing, see the RTR Application Design Guide.

# 3.12 RTRApplicationEvent Class

The RTRApplicationEvent Class contains members that retrieve application data and application events associated with an RTRApplicationEvent object.

# RTRApplicationEvent Class Members

Construction

Method | Description
--- | ---
RTRApplicationEvent () | Default constructor
RTRApplicationEvent (RTRApplicationEvent &) | Copy constructor

Operations

Method | Description
--- | ---
Dispatch() | Basic method.
GetEventData( rtr_msgbuf_t ) | Retrieve the application data associated with this RTRApplicationEvent object.
GetEventDataLength(); | Retrieve the actual length of the buffer allocated for this RTRApplicationEvent object.
GetEventNumber( rtr_evtnum_t ) | Retrieve the application event associated with the data in this RTRApplicationEvent object.
SetEventData( rtr_msgbuf_t, rtr_msglen_t) | Set the actual data length of the buffer allocated for this RTRApplicationEvent object.
SetEventNumber( const rtr_evtnum_t) | Set the application event number associated with the data in this RTRApplicationEvent object.

# Dispatch()

## RTRApplicationEvent::Dispatch();

## Prototype

>     rtr_status_t Dispatch();

## Return Value

> rtr_status_t Interpret value for the success or failure of this call.

Status | Message
--- | ---
RTR_STS_HANDLERDELETED | The application has deleted the handler.
RTR_STS_NOEVENT | The data object does not contain an event.
RTR_STS_NOEVENTDATA | There is no event data associated with the event.
RTR_STS_NOHANDLRREGSTRD | The application has not registered a handler
RTR_STS_NOMESSAGE | The data object does not contain a message.
RTR_STS_OK | Normal successful completion.
RTR_STS_TCDELETED | The application has deleted the transaction controller.

## Parameters

> None

## Description

> This member function must be overridden by the RTR application. When called, the data contained within the object is processed. Processing the data may include performing some application specific logic and/or dispatching to a handler.

## Example

>     sStatus = pApplicationEvent->Dispatch();
>     {
>     }

# GetEventData()

## RTRApplicationEvent::GetEventData();

## Prototype

>     rtr_status_t GetEventData( rtr_msgbuf_t &evEventData );

## Return Value

> rtr_status_t Interpret value for the success or failure of this call.

Status | Message
--- | ---
RTR_STS_INVARGPTR | Invalid argument pointer.
RTR_STS_NOEVENT | The data object does not contain an event.
RTR_STS_NOEVENTDATA | There is no event data associated with the event.
RTR_STS_OK | Normal successful completion

## Parameters

> ### evEventData

> Pointer to event data.

## Description

> Retrieve the application data associated with this RTRApplicationEvent object.

## Example

>     GetEventData(&evEventData );

# GetEventDataLength()

## RTRApplicationEvent::GetEventDataLength();

## Prototype

>     rtr_msglen_t GetEventDataLength();

## Return Value

> rtr_msglen_t: Returns the size of the event data length.

## Parameters

> None

## Description

> Call this member function to receive the size of the application event data length.

## Example

>     rtr_msglen_t LengthOfData =
>                              pRTRApplicationEvent->GetEventDataLength();

# GetEventNumber()

## RTRApplicationEvent::GetEventNumber();

## Prototype

>     rtr_status_t GetEventNumber (rtr_evtnum_t &evEventNumber );

## Return Value

> rtr_status_t Interpret value for the success or failure of this call.

Status | Message
--- | ---
RTR_STS_NOEVENT | The data object does not contain an event.
RTR_STS_NOMESSAGE | The data object does not contain a message
RTR_STS_OK | Normal successful completion.

## Parameters

> ### evEventNumber

> An event number.

## Description

> Get the event number associated with the received application event.

## Example

>     GetEventNumber (&evEventNumber );

# SetEventData()

## RTRApplicationEvent::SetEventData();

## Prototype

>     rtr_status_t SetEventData (rtr_msgbuf_t &evEventData, rtr_msglen_t
>     dlDataLength);

## Return Value

> rtr_status_t Interpret value for the success or failure of this call.

Status | Message
--- | ---
RTR_STS_OK | Normal successful completion.
RTR_STS_INVARGPTR | The data object does not contain an event.

## Parameters

> ### evEventData

> Pointer to event data.

> ### dlDataLength

> The length of the data.

## Description

> Set the application data associated with this RTRApplicationEvent object.

## Example

>     SetEventData (&evEventData, dlDataLength);

# SetEventNumber()

## RTRApplicationEvent::SetEventNumber();

## Prototype

>     rtr_status_t SetEventNumber (const rtr_evtnum_t &evEventNumber );

## Return Value

> rtr_status_t Interpret value for the success or failure of this call. RTR_STS_OK is the normal successful completion.

## Parameters

> ### evEventNumber

> An event number.

## Description

> Set the application event number associated with the data in this RTRApplicationEvent object.

## Example

>     SetEventNumber (&evEventNumber );

# 3.13 RTRApplicationMessage Class

The RTRApplicationMessage class contains members that retrieve the message and its length associated with the data in the object. Processing the data may include executing application logic or dispatch to a handler.

# RTRApplicationMessage Class Members

Construction

Method | Description
--- | ---
RTRApplicationMessage() | Default constructor
~RTRApplicationMessage () | Default destructor

Operations

Method | Description
--- | ---
Dispatch() | Basic method.
GetMessage() | Retrieve the message associated with the data in this object.
GetMessageLength() | Retrieve the actual length of the message associated with the data in this object.

# Dispatch()

## RTRApplicationMessage::Dispatch();

## Prototype

>     rtr_status_t Dispatch();

## Return Value

> rtr_status_t Interpret value for the success or failure of this call.

Status | Message
--- | ---
RTR_STS_HANDLERDELETED | The application has deleted the handler.
RTR_STS_NOHANDLRREGSTRD | The application has not registered a handler
RTR_STS_NOMESSAGE | The data object does not contain a message
RTR_STS_OK | Normal successful completion
RTR_STS_TCDELETED | The application has deleted the transaction controller.

## Parameters

> None

## Description

> This member function must be overridden by the RTR application. When called, the data contained within the object is processed. Processing the data may include performing some application specific logic and/or dispatching to a handler.

## Example

>     void ABCOrderProcessor::ProcessIncomingOrders()
>     {
>             abc_status sStatus = RTR_STS_OK;
>             RTRData *pOrder = NULL;
>             while (1)
>             {
>             sStatus = pOrder->Dispatch();
>             print_status_on_failure(sStatus);
>             delete pOrder;
>             }
>     return;
>     }

# GetMessage()

## RTRApplicationMessage::GetMessage();

## Prototype

>     rtr_msgbuf_t GetMessage();

## Return Value

> rtr_status_t Interpret value for the success or failure of this call.

Status | Message
--- | ---
RTR_STS_OK | Normal successful completion.
RTR_STS_NOMESSAGE | The data object does not contain a message

## Parameters

> None

## Description

> Retrieve the message associated with the data in this object.

## Example

>     RTRApplicationMessage.GetMessage();

# GetMessageLength()

## RTRApplicationMessage::GetMessageLength();

## Prototype

>     rtr_msgbuf_t GetMessageLength();

## Return Value

> rtr_status_t Interpret value for the success or failure of this call.

Status | Message
--- | ---
RTR_STS_OK | Normal successful completion.
RTR_STS_NOMESSAGE | The data object does not contain a message

## Parameters

> None

## Description

> Retrieve the actual length of the message associated with the data in this object.

## Example

>     RTRApplicationMessage.GetMessageLength();

# 3.14 RTRClassFactory Class

The RTRClassFactory class constructs an RTR application event or message directly from an RTR message data buffer.

# RTRClassFactory Class Members

Construction

Method | Description
--- | ---
RTRClassFactory() | Default constructor
~RTRClassFactory() | Default destructor

Operations

Method | Description
--- | ---
CreateRTRApplicationEvent (rtr_const_msgbuf_t, rtr_msglen_t, RTRApplicationEvent) | Create an RTRApplicationEvent data object.
CreateRTRApplicationMessage (rtr_const_msgbuf_t, rtr_msglen_t, RTRApplicationMessage) | Create an RTRApplicationMessage data object.
CreateRTREvent(RTREvent) | Create an RTREvent data object.
CreateRTRMessage(RTRMessage) | Create an RTRMessage data object.

# CreateRTRApplicationEvent()

## RTRClassFactory::CreateRTRApplicationEvent();

## Prototype

>     virtual rtr_status_t CreateRTRApplicationEvent(rtr_const_msgbuf_t
>                                                       pmsgCallersData,
>                                     rtr_msglen_t msglCallersDataLength
>                                     RTRApplicationEvent *&pApplicationEvent)
>     {
>         rtr_status_t sStatus = RTR_STS_OK;
>         pApplicationEvent = new RTRApplicationEvent();
>         if (NULL == pApplicationEvent);
>         {
>           sStatus = RTR_STS_INSVIRMEM;
>         }
>         return sStatus;
>     };

## Return Value

> rtr_status_t Interpret value for the success or failure of this call.

Status | Message
--- | ---
RTR_STS_OK | Normal successful completion.
RTR_STS_INSVIREM | Insufficient virtual memory.

## Parameters

> ### pmsgCallersData

> Pointer to the caller's data.

> ### msglCallersDataLength

> The length of the caller's data.

> ### pApplicationEvent

> Pointer to the application event.

## Description

> Create an RTRApplicationEvent data object if the transaction controller determines that Receive call points to a message of type RTRApplicationEvent.

## Example

>     pApplicationEvent = new ApplicationEvent();

# CreateRTRApplicationMessage()

## RTRClassFactory::CreateRTRApplicationMessage();

## Prototype

>     virtual rtr_status_t CreateRTRApplicationMessage(rtr_const_msgbuf_t
>                                                        pmsgCallersData,
>                                     rtr_msglen_t msglCallersDataLength,
>                            RTRApplicationMessage *&pApplicationMessage)
>     {
>         rtr_status_t sStatus = RTR_STS_OK;
>         pApplicationMessage = new RTRApplicationMessage();
>         if (NULL == pApplicationMessage)
>         {
>         sStatus = RTR_STS_INSVIRMEM;
>         }
>         return sStatus;
>     };

## Return Value

> rtr_status_t Interpret value for the success or failure of this call.

Status | Message
--- | ---
RTR_STS_OK | Normal successful completion.
RTR_STS_INSVIREM |

## Parameters

> ### pmsgCallersData

> Pointer to the caller's data.

> ### msglCallersDataLength

> The length of the caller's data.

> ### pApplicationMessage

> Pointer to the application message.

## Description

> Create an RTRApplicationMessage data object if the transaction controller determines that Receive call points to a message of type RTRApplicationMessage.

## Example

>     rtr_status_t ABCSClassFactory::CreateRTRApplicationMessage(
>     rtr_const_msgbuf_t pmsgCallersData,
>     rtr_msglen_t msglCallersDataLength,
>     RTRApplicationMessage *&pApplicationMessage )
>     { // Determine what kind of serialized object we are receiving.
>       // The ABC company protocol defines the first integer of the
>       // message to represent the type of the object we are receiving.
>       // Book = ABC_BOOK. Magazine = ABC_MAGAZINE unsigned int
>       // uiClassType = *(unsigned int*)pmsgCallersData;
>     switch (uiClassType)
>         {
>       case ABC_BOOK : pApplicationMessage = new ABCBook(); break;
>       case ABC_MAGAZINE : pApplicationMessage = new ABCMagazine(); break;
>       default:
>         // If we ever get here then the client is sending us data that we
>         // can't recognize. For some applictations this may not be an
>         // issue. For the ABC company this should be impossible.
>         assert(false);
>         }
>     // Make sure we are passing back a valid address
>     if (NULL == pApplicationMessage)
>     return RTR_STS_INSVIRMEM;
>     return ABC_STS_SUCCESS;}

Previous | Next | Contents | Index