# hp Reliable Transaction Router
C++ Foundation Classes

Previous | Contents | Index

# CreateRTREvent()

## RTRClassFactory::CreateRTREvent();

## Prototype

>     virtual rtr_status_t CreateRTREvent( RTREvent *&pRTREvent)
>     {
>       rtr_status_t sStatus = RTR_STS_OK;
>       pRTREvent = new RTREvent();
>       if (NULL == pRTREvent)
>       {
>         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

> ### pRTREvent

> Pointer to an RTREvent object that describes the message which is being processed.

## Description

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

## Example

>     pRTREvent = newRTREvent();

# CreateRTRMessage()

## RTRClassFactory::CreateRTRMessage ();

## Prototype

>     virtual rtr_status_t CreateRTRMessage( RTRMessage *&pRTRMessage)
>     {
>       rtr_status_t sStatus = RTR_STS_OK;
>       pRTRMessage = new RTRMessage();
>       if (NULL == pRTRMessage)
>       {
>         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

> ### pRTRMessage

> Pointer to an RTRMessage object that describes the message which is being processed.

## Description

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

## Example

>     pApplicationMessage = new ApplicationMessage();

# 3.15 RTRData

RTRData is the abstract base class for all data classes.

# RTRData Class Members

Construction

Method | Description
--- | ---
RTRData() | Default constructor
RTRData() | Default destructor

Operations

Method | Description
--- | ---
Dispatch() | Basic method.
GetActualBufferLength() | Return the message buffer length.
GetLogicalBufferLength() | Return the logical buffer length.
IsApplicationEvent() | Determine if this object contains application-generated data.
IsApplicationMessage() | Determine if this object contains application-generated message.
IsEvent() | Determine if this object contains an RTR or application-generated event.
IsMessage() | Determine if this object contains an RTR or application-generated message.
IsRTREvent() | Determine if this object contains RTR-generated data.
IsRTRMessage() | Determine if this object contains RTR-generated message.

# Dispatch()

## RTRData::Dispatch();

## Prototype

>     virtual rtr_status_t Dispatch() = 0;

## Return Value

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

## Parameters

> None

## Description

> This is a pure virtual member function. RTRData does not supply an implementation for Dispatch and therefore cannot be instantiated. All classes that derive from RTRData must implement their own version of Dispatch, with the functionality based on their needs.

# GetActualBufferLength()

## RTRData::GetActualBufferLength();

## Prototype

>     rtr_msglen_t GetActualBufferLength ();

## Return Value

> rtr_msglen_t The message buffer length.

## Parameters

> None

## Description

> The method returns the message buffer length.

## Example

>     GetActualBufferLength ();

# GetLogicalBufferLength()

## RTRData::GetLogicalBufferLength();

## Prototype

>     rtr_msglen_t GetLogicalBufferLength();

## Return Value

> rtr_msglen_t Return the logical buffer length.

## Parameters

> None

## Description

> Call this method for the logical buffer length.

## Example

>     GetLogicalBufferLength();

# IsApplicationEvent()

## RTRData::IsApplicationEvent();

## Prototype

>     bool IsApplicationEvent ();

## Return Value

> bool A true or false return value.

## Parameters

> None

## Description

> If the RTRData object contains an event sent by the application, this function returns TRUE. Otherwise it returns FALSE.

## Example

>     sStatus = Receive(&pResult);
>     print_status_on_failure(sStatus);
>     if ( true == pResult->IsApplicationEvent();)

# IsApplicationMessage()

## RTRData::IsApplicationMessage();

## Prototype

>     bool IsApplicationMessage();

## Return Value

> bool A true or false return value.

## Parameters

> None

## Description

> If the RTRData object contains a message sent by the application, this function returns TRUE. Otherwise it returns FALSE.

## Example

>     sStatus = Receive(&pResult);
>     print_status_on_failure(sStatus);
>     if ( true == pResult->IsApplicationMessage();)

# IsEvent()

## RTRData::IsEvent();

## Prototype

>     bool IsEvent();

## Return Value

> bool A true or false return value.

## Parameters

> None

## Description

> If the RTRData object contains an event generated by either RTR or an application, this function returns TRUE. Otherwise it returns FALSE.

## Example

>     if (IsEvent();)
>     {
>         rtr_evtnum_t enEvent;
>         sStatus = GetEventNumber(enEvent);
>     }

# IsMessage()

## RTRData::IsMessage();

## Prototype

>     bool IsMessage();

## Return Value

> bool A true or false return value.

## Parameters

> None

## Description

> If the RTRData object contains a message, generated by either RTR or an application, this function returns TRUE. Otherwise it returns FALSE.

## Example

>     // Look for a status for this transaction.
>     RTRData *pTransactionData = new RTRData();
>     sStatus = GetTransaction()->Receive(pTransactionData);
>     // Determine if we have a message or an event
>     if (false == pTransactionData->IsMessage();)
>         {
>         pTransactionData->Dispatch();
>         }

# IsRTREvent()

## RTRData::IsRTREvent();

## Prototype

>     bool IsRTREvent();

## Return Value

> bool A true or false return value.

## Parameters

> None

## Description

> If the RTRData object contains an event sent by RTR, this function returns TRUE. Otherwise it returns FALSE.

## Example

>     sStatus = Receive(&pResult);
>     print_status_on_failure(sStatus);
>     if ( true == pResult->IsRTREvent();)

# IsRTRMessage()

## RTRData::IsRTRMessage();

## Prototype

>     bool IsRTRMessage();

## Return Value

> bool A true or false return value.

## Parameters

> None

## Description

> If the RTRData object contains a message sent by RTR, this function returns TRUE. Otherwise it returns FALSE.

## Example

>     sStatus = Receive(&pResult);
>     print_status_on_failure(sStatus);
>     if ( true == pResult->IsRTRMessage();)

# RTRData()

## RTRData::RTRData();

## Prototype

>     RTRData();
>     virtual ~RTRData();

## Parameters

> None

## Description

> This constructor is a pure virtual function and requires an associated higher-level data object (for example, RTRApplicationMessage). The default constructor should be used by applications when receiving data from a call to Receive that does not intend to handle allocation and de-allocation of memory for the call. By using this form of the constructor, the application requests that RTR allocate enough memory to receive the data.

# 3.16 RTREvent Class

The RTREvent class contains members that retrieve the RTR data and RTR event associated with an RTREvent object.

# RTREvent Class Members

Construction

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

Operations

Method | Description
--- | ---
Dispatch() | Basic method.
GetEventData( rtr_msgbuf_t ) | Retrieve the RTR data associated with this RTREvent object.
GetEventDataLength(); | Retrieve the actual length of the data associated for this RTREvent object.
GetEventNumber( rtr_evtnum_t ) | Retreive the RTR event associated with the data in this RTREvent object.

# Dispatch()

## RTREvent::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_OK | Normal successful completion
RTR_STS_TCDELETED | The application has deleted the transaction controller.
RTR_STS_EVENT | The data object does not contain an event.
RTR_STS_NOEVENTDATA | There is no event data associated with the event.
RTR_STS_MESSAGE | The data object does not contain a message.
RTR_STS_HANDLERDELETED | The application has deleted the handler.
RTR_STS_NOHANDLRREGSTRD | The application has not registered a handler

## 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 = pOrderEvent->Dispatch();

# GetEventData()

## RTREvent::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_OK | Normal successful completion
RTR_STS_INVARGPTR |
RTR_STS_NOEVENTDATA | There is no event data associated with the event.

## Parameters

> ### evEventData

> Pointer to event data.

## Description

> Retrieve the RTR data associated with this RTREvent object.

## Example

>     RTREvent.GetEventData(&evEventData);

# GetEventDataLength()

## RTREvent::GetEventDataLength();

## Prototype

>     rtr_msglen_t GetEventDataLength();

## Return Value

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

## Parameters

> None

## Description

> Retrieve the actual length of the data associated for this RTREvent object.

## Example

>     RTREvent.GetEventDataLength();

# GetEventNumber()

## RTREvent::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_OK | Normal successful completion
RTR_STS_NOEVENT | The data object does not contain an event.

## Parameters

> ### evEventNumber

> An event number.

## Description

> Call this member function to retrieve the RTR event associated with the data in this RTREvent object. This function is typically used by only those applications that do not register an event.

## Example

>     RTREvent.GetEventNumber(&evEventNumber);

# 3.17 RTRMessage

RTRMessage contains members that retrieve the RTR message associated with the data in the RTRMessage object, the reason for its acceptance or rejection of a transaction, and a secondary status if needed.

# RTRMessage Class Members

Construction

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

Operations

Method | Description
--- | ---
Dispatch() | Basic method.
GetMessageType(rtr_msg_type_t) | Retrieve the RTR message associated with the data in this RTRMessage object.
GetReason() | Retrieve the reason associated with the accepting or rejection of the transaction.
GetSecondaryStatus() | Retrieve the secondary status associated with the accepting or rejection of the transaction.

# Dispatch()

## RTRMessage::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_OK | Normal successful completion.
RTR_STS_TCDELETED | The application has deleted the transaction controller.
RTR_STS_NOMESSAGE | The data object does not contain a message.
RTR_STS_HANDLERDELETED | The application has deleted the handler.
RTR_STS_NOHANDLRREGSTRD | The application has not registered a handler.

## 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 = pOrderMessage->Dispatch();

Previous | Next | Contents | Index