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:

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:

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