Reliable Transaction Router
C++ Foundation Classes
Previous Contents Index

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 the application, 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 the application, 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

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 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();

GetMessageType()

RTRMessage::GetMessageType();

Prototype


rtr_status_t GetMessageType(rtr_msg_type_t& mtMessageType);

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

mtMessageType

An RTR message.

Description

Retrieve the RTR message associated with the data in this RTRMessage object.

Example


sStatus = ((RTRMessage*)pResult)->GetMessageType(mtMessageType); 
print_status_on_failure(sStatus);

GetReason()

RTRMessage::GetReason();

Prototype


rtr_reason_t GetReason();

Return Value

rtr_status_t This function either returns RTR_NO_REASON or the value specified by the participants in the transaction. If different participants provide different reason codes, RTR ORs them.

Parameters

None

Description

Retrieve the reason associated with the accepting or rejection of the transaction.

Example


void OnAccepted(RTRMessage* pRTRData, 
        RTRClientTransactionController* pController) 
{ 
        rtr_status_t sStatus = 
               pRTRData->GetSecondaryStatus(); 
        rtr_reason_t rcReasonCode = pRTRData->GetReason(); 
        m_bAcceptReceived = true; 
};

GetSecondaryStatus

RTRMessage::GetSecondaryStatus();

Prototype


rtr_status_t GetSecondaryStatus();

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 secondary status associated with the accepting or rejection of the transaction.

Example


void OnAccepted(RTRMessage* pRTRData, 
       RTRClientTransactionController* pController) 
{ 
      rtr_status_t sStatus = 
             pRTRData->GetSecondaryStatus(); 
        rtr_reason_t rcReasonCode = pRTRData->GetReason(); 
        m_bAcceptReceived = true; 
 
};

Previous Next Contents Index