The RTR C++ API major application classes are:
This chapter describes these major classes in the above order. Within each major class, each lesser class is described in alphabetical order. Within each lesser class, all of its inherited methods are then described in alphabetical order.
RTRData-derived classes are used for passing data between client and server applications.
An application can send two data categories:
An application can receive four data categories:
The four RTRData-derived classes are:
An RTRClassFactory object creates these four classes. The RTR application does not need to register a class factory with a transaction controller. However, if it does, it can customize how the objects are allocated including allocating a class derived from any of the four data classes above.
The server application classes are:
This class defines event handlers for all potential events that an RTR server application can receive. Each handler has a default behavior. Applications should override those member functions for which they want to perform application-specific processing.
Note
Applications can extend this class by deriving from it and adding their own application-level event handlers.
For further information, see RTRData::Dispatch().
RTRServerEventHandler Class Members
Construction
|
Method |
Description |
|
Constructor |
|
|
~RTRServerEventHandler() |
Destructor |
Operations
|
Method |
Description |
|
OnApplicationEvent(RTRApplicationEvent, RTRServerTransactionController) |
The application has generated an event for the server. |
|
OnBackendGainedLinkToRouter(RTREvent, |
Default handler for the event where a backend link to the current router has been established. |
|
OnBackendLostLinkToRouter(RTREvent, |
Default handler for the event where the backend link to the current router has been lost. |
|
OnFacilityDead(RTREvent, |
Default handler for the event where the facility is no longer operational. |
|
OnFacilityReady(RTREvent, RTRServerTransactionController) |
Default handler for the event where the facility has become operational. |
|
OnServerGainedShadow(RTREvent, |
The server gained its shadow partner. |
|
OnServerIsPrimary(RTREvent, |
Default handler for the event where the server is in primary mode. |
|
OnServerIsSecondary(RTREvent, RTRServerTransactionController) |
Default handler for the event where the server is in secondary mode. |
|
OnServerIsStandby(RTREvent, |
Default handler for the event where the server is in standby mode. |
|
OnServerLostShadow(RTREvent, |
The server lost its shadow partner. |
|
OnServerRecoveryComplete(RTREvent, |
Default handler for the event where the server has completed recovery. |
RTRServerMessageHandler::OnApplicationEvent();
Prototype
virtual rtr_status_t OnApplicationEvent (RTRApplicationEvent *pRTRApplicationEvent,
RTRServerTransactionController *pController)
{
return RTR_STS_OK;
}
Parameters
pRTRApplicationEvent
Pointer to an RTRApplicationEvent object that describes the message which is being processed.
pController
Pointer to the transaction controller within which this event was received.
Description
The pRTRApplicationEvent parameter contains an application event sent to it by the client application.
Override this method if your application is to receive an indication that this event has occurred.
The default behavior is that the handler dismisses the notification.
Example
void CombinationOrderProcessor::OnApplicationEvent ( RTRApplicationEvent *pApplicationEvent, RTRServerTransactionController *pController)
{
// This handler is called by RTR when the client has sent an event.
}
RTRServerEventHandler::OnBackendGainedLinkToRouter();
Prototype
virtual rtr_status_t OnBackendGainedLinkToRouter(RTREvent * pRTREvent,
RTRServerTransactionController *pController)
{
return RTR_STS_OK;
}
Parameters
pRTREvent
Pointer to an RTREvent object that describes the RTR-generated event being processed.
pController
Pointer to the transaction controller within which this event was received.
Description
This method provides the default handler for the event where a backend link to the current router has been established.
The server application is receiving an RTR-generated event. RTREvent contains the RTR-defined event number RTR_EVTNUM_BERTRGAIN (104) and any associated data.
Override this method if your application is to receive an indication that this event has occurred.
Example
void RTRServerEventHandler::OnBackendGainedLinkToRouter( RTREvent
*pEvent, RTRServerTransactionController *pController )
{
}
RTRServerEventHandler::OnBackendLostLinkToRouter();
Prototype
virtual rtr_status_t OnBackendLostLinktToRouter(RTREvent * pRTREvent,
RTRServerTransactionController *pController)
{
return RTR_STS_OK;
}
Parameters
pRTREvent
Pointer to an RTREvent object that describes the RTR-generated event being processed.
pController
Pointer to the transaction controller within which this event was received.
Description
This method provides the default handler for the event where the backend link to the current router has been lost.
The server application is receiving an RTR-generated event. RTREvent contains the RTR-defined event number RTR_EVTNUM_BERTRLOSS (105) and any associated data.
Override this method if your application is to receive an indication that this event has occurred.
Example
void RTRServerEventHandler::OnBackendLostLinkToRouter( RTREvent *pEvent, RTRServerTransactionController *pController )
{
}
RTRServerEventHandler::OnFacilityDead();
Prototype
virtual rtr_status_t OnFacilityDead(RTREvent * pRTREvent,
RTRServerTransactionController *pController)
{
return RTR_ST_OK;
}
Parameters
pRTREvent
Pointer to an RTREvent object that describes the RTR-generated event being processed.
pController
Pointer to the transaction controller within which this event was received.
Description
This method provides the default handler for the event where the facility is no longer operational.
The server application is receiving an RTR-generated event. RTREvent contains the RTR-defined event number RTR_EVTNUM_FACDEAD (97) and any associated data.
Override this method if your application wants to receive an indication that this event has occurred.
Example
void RTRServerEventHandler::OnFacilityDead( RTREvent *pEvent, RTRServerTransactionController *pController )
{
}
RTRServerEventHandler::OnFacilityReady();
Prototype
virtual rtr_status_t OnFacilityReady(RTREvent * pRTREvent,
RTRServerTransactionController *pController)
{
return RTR_STS_OK;
}
Parameters
pRTREvent
Pointer to an RTREvent object that describes the RTR-generated event being processed.
pController
Pointer to the transaction controller within which this event was received.
Description
This method provides the default handler for the event where the facility has become operational.
The server application is receiving an RTR-generated event. RTREvent contains the RTR-defined event number RTR_EVTNUM_FACREADY (96) and any associated data.
Override this method if your application is to receive an indication that this event has occurred.
Example
void RTRServerEventHandler::OnFacilityReady( RTREvent *pEvent, RTRServerTransactionController *pController )
{
}
OnFrontendGainedLinkToRouter()
RTRServerEventHandler::OnFrontendGainedLinkToRouter();
Prototype
virtual rtr_status_t OnFrontendGainedLinkToRouter(RTREvent * pRTREvent,
RTRServerTransactionController *pController)
{
return RTR_STS_OK;
}
Parameters
pRTREvent
Pointer to an RTREvent object that describes the RTR-generated event being processed.
pController
Pointer to the transaction controller within which this event was received.
Description
This method provides the default handler for the event where the router gained link to a frontend.
The server application is receiving an RTR-generated event. RTREvent contains the RTR-defined event number RTR_EVTNUM_RTRFEGAIN (106) and any associated data.
Override this method if your application is to receive an indication that this event has occurred.
Example
void RTRServerEventHandler::OnFrontendGainedLinkToRouter( RTREvent *pEvent, RTRServerTransactionController *pController )
{
}
RTRServerEventHandler::OnFrontendLostLinkToRouter();
Prototype
virtual rtr_status_t OnFrontendLostLinkToRouter(RTREvent * pRTREvent,
RTRServerTransactionController *pController)
{
return RTR_STS_OK;
}
Parameters
pRTREvent
Pointer to an RTREvent object that describes the RTR-generated event being processed.
pController
Pointer to the transaction controller within which this event was received.
Description
This method provides the default handler for the event where the router lost link to the current frontend.
The server application is receiving an RTR-generated event. RTREvent contains the RTR-defined event number RTR_EVTNUM_RTRFELOSS (107) and any associated data.
Override this method if your application is to receive an indication that this event has occurred.
Example
void RTRServerEventHandler::OnFrontendLostLinkToRouter( RTREvent *pEvent, RTRServerTransactionController *pController )
{
}
RTRServerEventHandler::OnServerGainedShadow();
Prototype
virtual rtr_status_t OnServerGainedShadow(RTREvent * pRTREvent,
RTRServerTransactionController *pController
rtr_const_parnam_t pszPartitionName)
{
return RTR_STS_OK;
}
Parameters
pRTREvent
Pointer to an RTREvent object that describes the RTR-generated event being processed.
pController
Pointer to the transaction controller within which this event was received.
pszPartitionName
A pointer to the partition name on which the message or event was received.
Description
This method provides the default handler for the event where the server gained its shadow partner.
The server application is receiving an RTR generated event. RTREvent contains the RTR defined event number RTR_EVTNUM_SRSHADOWGAIN (112) and any associated data.
Override this method if your application is to receive an indication that this event has occurred.
Example
void RTRServerEventHandler::OnServerGainedShadow (*pEvent, *pController, pszPartitionName)
{
}
RTRServerEventHandler::OnServerIsPrimary();
Prototype
virtual rtr_status_t OnServerIsPrimary(RTREvent * pRTREvent,
RTRServerTransactionController *pController
rtr_const_parnam_t pszPartitionName)
{
return RTR_STS_OK;
}
Parameters
pRTREvent
Pointer to an RTREvent object that describes the RTR-generated event being processed.
pController
Pointer to the transaction controller within which this event was received.
pszPartitionName
Pointer to a partition name that is registered for the server transaction controller.
Description
This method provides the default handler for the event where the server is in primary mode.
The server application is receiving an RTR-generated event. RTREvent contains the RTR-defined event number RTR_EVTNUM_SRPRIMARY (108) and any associated data.
Override this method if your application is to receive an indication that this event has occurred.
Example
void RTRServerEventHandler::OnServerIsPrimary(*pEvent, *pController, pszPartitionName )
{ }
RTRServerEventHandler::OnServerIsSecondary();
Prototype
virtual rtr_status_t OnServerIsSecondary(RTREvent * pRTREvent,
RTRServerTransactionController *pController
rtr_const_parnam_t pszPartitionName)
{
return RTR_STS_OK;
}
Parameters
pRTREvent
Pointer to an RTREvent object that describes the RTR-generated event being processed.
pController
Pointer to the transaction controller within which this event was received.
pszPartitionName
Pointer to a partition name that is registered for the server transaction controller.
Description
This method provides the default handler for the event where the server is in secondary mode.
The server application is receiving an RTR-generated event. RTREvent contains the RTR-defined event number RTR_EVTNUM_SRSECONDARY (110) and any associated data.
Override this method if your application is to receive an indication that this event has occurred.
Example
void RTRServerEventHandler::OnServerIsSecondary(*pEvent,
*pController, pszPartitionName )
{ }
RTRServerEventHandler::OnServerIsStandby();
Prototype
virtual rtr_status_t OnServerIsStandby(RTREvent * pRTREvent,
RTRServerTransactionController *pController
rtr_const_parnam_t pszPartitionName)
{
return RTR_STS_OK;
}
Parameters
pRTREvent
Pointer to an RTREvent object that describes the RTR-generated event being processed.
pController
Pointer to the transaction controller within which this event was received.
pszPartitionName
Pointer to a partition name that is registered for the server transaction controller.
Description
This method provides the default handler for the event where the server is in standby mode.
The server application is receiving an RTR-generated event. RTREvent contains the RTR-defined event number RTR_EVTNUM_SRSTANDBY (109) and any associated data.
Override this method if your application is to receive an indication that this event has occurred.
Example
void RTRServerEventHandler::OnServerIsStandby(*pEvent,
*pController, pszPartitionName )
{
}
RTRServerEventHandler::OnServerLostShadow();
Prototype
virtual rtr_status_t OnServerLostShadow(RTREvent * pRTREvent,
RTRServerTransactionController *pController
rtr_const_parnam_t pszPartitionName)
{
return RTR_STS_OK;
}
Parameters
pRTREvent
Pointer to an RTREvent object that describes the RTR-generated event being processed.
pController
Pointer to the transaction controller within which this event was received.
pszPartitionName
Pointer to a partition name that is registered for the server transaction controller.
Description
This method provides the default handler for the event where the server lost its shadow partner
The server application is receiving an RTR-generated event. RTREvent contains the RTR defined event number RTR_EVTNUM_SRSHADOWLOST (111) and any associated data.
Override this method if your application is to receive an indication that this event has occurred.
Example
void RTRServerEventHandler::OnServerShadowLost(*pEvent,
*pController, pszPartitionName )
{
}
RTRServerEventHandler::OnServerRecoveryComplete();
Prototype
virtual rtr_status_t OnServerRecoveryComplete(RTREvent * pRTREvent,
RTRServerTransactionController *pController
rtr_const_parnam_t pszPartitionName)
{
return RTR_STS_OK;
}
Parameters
pRTREvent
Pointer to an RTREvent object that describes the RTR-generated event being processed.
pController
Pointer to the transaction controller within which this event was received.
pszPartitionName
Pointer to a partition name that is registered for the server transaction controller.
Description
This method provides the default handler for the event where the server has completed recovery.
The server application is receiving an RTR-generated event. RTREvent contains the RTR-defined event number RTR_EVTNUM_SRRECOVERCMPL (113) and any associated data.
Override this method if your application is to receive an indication that this event has occurred.
Example
void RTRServerEventHandler::OnServerRecoveryComplete(*pEvent, *pController, pszPartitionName )
{ }
RTRServerEventHandler::RTRServerEventHandler();
Prototype
RTRServerEventHandler();
virtual ~RTRServerEventHandler();
Return Value
None
Parameters
None
Description
Call this constructor to create an RTRServerEventHandler object.
Example
class MySRVEventHandler: public RTRServerEventHandler
{
public:
MySRVEventHandler();
~MySRVEventHandler();
rtr_status_t OnServerIsPrimary( RTREvent *pRTREvent,
RTRServerTransactionController *pTC );
private:
};
MySRVEventHandler::MySRVEventHandler()
{
}
MySRVEventHandler::~MySRVEventHandler()
{
}
MySRVEventHandler::OnServerIsPrimary( RTREvent *pRTREvent,
RTRServerTransactionController *pTC )
{
cout << "This server is primary " <<endl;
return RTR_STS_OK;
}
This class defines message handlers for all potential messages that an RTR server application can receive. Each handler has a default behavior. Applications should override those member functions for which they want to perform application-specific processing.
Note
Applications can extend this class by deriving from it and adding their own application-level message handlers.
For further information, see RTRData::Dispatch().
RTRServerMessageHandler Class Members
Construction
|
Method |
Description |
|
Constructor |
|
|
~RTRServerMessageHandler() |
Destructor |
Message Handlers
|
Method |
Description |
|
OnAccepted(RTRMessage, |
The specified transaction has been accepted by all participants. |
|
OnApplicationMessage(RTRApplicationMessage, |
The client has sent the server this message. |
|
OnInitialize(RTRApplicationMessage, RTRServerTransactionController) |
A new transaction is being processed. |
|
OnPrepareTransaction(RTRMessage, |
The specified transaction is complete (that is, all messages from the client have been received). |
|
OnRejected(RTRMessage, |
The specified transaction has been rejected by a participant. |
|
OnUncertainTransaction(RTRApplicationMessage, |
RTR is replaying a transaction which may or may not have been completed. |
RTRServerMessageHandler::OnAccepted();
Prototype
virtual rtr_status_t OnAccepted(RTRMessage *pRTRMessage,
RTRServerTransactionController *pController)
{
pController->AcknowledgeTransactionOutcome();
};
Return Value
rtr_status_t
Interpret value for the success or failure of this call.
|
Status |
Message |
|
RTR_STS_NOMESSAGE |
The data object does not contain a message. |
|
RTR_STS_OK |
Normal successful completion. |
Parameters
pRTRMessage
Pointer to an RTRMessage object that describes the message which is being processed.
pController
Pointer to the transaction controller within which this message was received.
Description
The specified transaction has been accepted by all participants.
RTR is informing the application that the current transaction has been accepted by all parties of the transaction and successfully completed. RTRMessage will contain rtr_mt_accepted.
The default behavior is the handler dismisses the notification.
Example
rtr_status_t MySRVMessageHandler::OnAccepted(RTRMessage *pmyMsg,
RTRServerTransactionController *pTC)
{
cout << "accepted txn " << endl;
pTC->AcknowledgeTransactionOutcome();
return RTR_STS_OK;
}
RTRServerMessageHandler::OnApplicationMessage();
Prototype
virtual rtr_status_t OnApplicationMessage(RTRApplicationMessage
*pRTRApplicationMessage,
RTRServerTransactionController *pController
rtr_const_parnam_t pszPartitionName)
{
return RTR_STS_OK;
}
Parameters
pRTRApplicationMessage
Pointer to an RTRApplicationMessage object that describes the message which is being processed.
pController
Pointer to the transaction controller within which this message was received.
pszPartitionName
Pointer to a partition name that is registered for the server transaction controller.
Description
The RTRApplicationMessage parameter contains application data sent to it by an RTR client. RTRApplicationMessage will contain rtr_mt_msg1 or rtr_mt_msgn and associated data.
The default behavior is the handler dismisses the notification.
Example
void ClassDerivedFromHandler::OnApplicationMessage(*pApplicationMessage, *pController, pszPartitionName )
{
// This handler is called by RTR when the client has sent a message.
// This is where you process the application's business logic
return RTR_STS_OK;
}
RTRServerMessageHandler::OnInitialize(RTRApplicationMessage);
Prototype
virtual rtr_status_t OnInitialize(RTRApplicationMessage *pRTRApplicationMessage,
RTRServerTransactionController *pController)
{
return RTR_STS_OK;
}
Parameters
pRTRApplicationMessage
Pointer to an RTRApplicationMessage object that describes the message which is being processed.
pController
Pointer to the transaction controller within which this message was received.
Description
The OnInitialize member function is called by the RTR framework at the beginning of every new transaction this object processes. Your application should override this member function to perform any special logic for each transaction processed.
Example
rtr_status_t ABCSHandlers::OnInitialize( RTRApplicationMessage *pRTRApplicationMessage, RTRServerTransactionController *pController )
{
// This message notifies the RTR application that a new transaction
// is about to begin. Do any per-transaction state handling here.
cout << endl << endl << endl << "New Transaction being received..." << endl;
m_bVoteToAccept = true;
return RTR_STS_OK;
}
RTRServerMessageHandler::OnPrepareTransaction();
Prototype
virtual rtr_status_t OnPrepareTransaction(RTRMessage *pRTRMessage,
RTRServerTransactionController *pController)
{
return RTR_STS_OK;
}
Parameters
pRTRMessage
Pointer to an RTRMessage object that describes the message being processed.
pController
Pointer to the transaction controller within which this message was received.
Description
The current transaction is complete (that is, all messages from the client have been received). RTRMessage will contain rtr_mt_prepare.
The default behavior is the handler dismisses the notification. Note that you must override the defaults with a vote to accept or reject the transaction being processed so the transaction is successfully completed.
Example
rtr_status_t ABCSHandlers::OnPrepareTransaction( RTRMessage *pRTRMessage, RTRServerTransactionController *pController )
{
// This handler is called by RTR when the client has accepted the
// transaction. This is our notification that we have all orders
// for this transaction.
// We must now give RTR a vote for this transaction. A vote means
// either calling Accept or Reject.
// We simply check to see if anything has gone wrong. If so, reject
// the transaction, otherwise accept it.
rtr_status_t sStatus;
if (true == m_bVoteToAccept)
{
cout << "Voting to Accept..." << endl;
sStatus = pController->AcceptTransaction();
}
else
{
cout << "Voting to Reject..." << endl;
sStatus = pController->RejectTransaction();
}
return sStatus;
}
RTRServerMessageHandler::OnRejected();
Prototype
virtual rtr_status_t OnRejected(RTRMessage * pRTRMessage,
RTRServerTransactionController *pController)
{
pController->AcknowledgeTransactionOutcome();
};
Return Value
rtr_status_t
Interpret value for the success or failure of this call.
|
Status |
Message |
|
RTR_STS_NOMESSAGE |
The data object does not contain a message. |
|
RTR_STS_OK |
Normal successful completion. |
Parameters
pRTRMessage
Pointer to an RTRMessage object that describes the message which is being processed.
pController
Pointer to the transaction controller within which this message was received.
Description
The specified transaction has been rejected by a participant. RTRMessage will contain rtr_mt_rejected.
The default behavior is the handler dismisses the notification.
Example
rtr_status_t ABCSHandlers::OnRejected( RTRMessage *pRTRMessage, RTRServerTransactionController *pController)
{
cout << "Entire Transaction Rejected..." << endl;
return RTRServerMessageHandler::OnRejected(pRTRMessage,pController);
}
RTRServerMessageHandler::OnUncertainTransaction();
Prototype
virtual rtr_status_t OnUncertainTransaction(RTRMessage * pRTRApplicationMessage,
RTRServerTransactionController *pController
rtr_const_parnam_t pszPartitionName)
{
return RTR_STS_OK;
}
Parameters
pRTRApplicationMessage
Pointer to an RTRMessage object that describes the message which is being processed.
pController
Pointer to the transaction controller within which this message was received.
pszPartitionName
Pointer to a partition name that is registered for the server transaction controller.
Description
The OnUncertainTransaction() member function is called by the RTR framework when RTR is replaying or recovering a transaction. The user’s application should override this member function to perform any special logic for each transaction processed. OnInitialize is also called when the server receives an rtr_mt_msg1_uncertain message.
Note: This member function is only called for transactions whose RTRServerEnvironment object has set bXAManaged = FALSE.
The default behavior is the handler dismisses the notification.
Example
ABCSHandlers::OnUncertainTransaction( RTRApplicationMessage *pRTRApplicationMessage, RTRServerTransactionController *pController, rtr_const_parnam_t pszPartitionName )
{
return RTR_STS_OK;
}
RTRServerMessageHandler::RTRServerMessageHandler();
Prototype
RTRServerMessageHandler();
virtual ~RTRServerMessageHandler();
Return Value
None
Parameters
None
Description
Call this constructor to create an RTRServerMessageHandler object.
Example
class MySRVMessageHandler: public RTRServerMessageHandler
{
public:
MySRVMessageHandler();
~MySRVMessageHandler();
rtr_status_t OnPrepareTransaction( RTRMessage *pmyMsg,
RTRServerTransactionController *pTC);
rtr_status_t OnAccepted( RTRMessage *pmyMsg,
RTRServerTransactionController *pTC);
private:
};
MySRVMessageHandler::MySRVMessageHandler()
{
}
MySRVMessageHandler::~MySRVMessageHandler()
{
}
RTRServerTransactionController
RTRServerTransactionController is the class most commonly used to create an RTR server application. Typically, one instance of this class is used to process multiple consecutive transactions. A transaction controller object is used to send and receive all data between RTR clients and servers.
RTRServerTransactionController Class Members
Construction
|
Method |
Description |
|
Constructor |
|
|
~RTRServerTransactionController() |
Destructor |
Operations
|
Method |
Description |
|
RegisterClassFactory(RTRClassFactory) |
Register a class factory for RTR to call when creating RTRData-derived objects. |
|
RegisterFacility(rtr_const_facnam_t) |
Register a facility for which this transaction controller processes requests. |
|
RegisterHandlers(RTRServerMessageHandler, RTRServerEventHandler) |
Register your handlers with this transaction. |
|
RegisterPartition(rtr_const_parnam_t rtr_const_rcpnam_t, rtr_const_access_t) |
Add a partition to the list of partitions for which this transaction controller processes requests. |
Basic Methods
|
Method |
Description |
|
Allow RTR to remove the current transaction from the journal and proceed with the next request from a client. |
|
|
AcceptTransaction(rtr_reason_t, bool) |
Accept the current transaction. |
|
Tell RTR to cancel the current transaction and re-present it. |
|
|
Receive(RTRData, rtr_timout_t) |
Receive an RTR or application-generated message or an RTR event. |
|
UnRegisterPartition(rtr_const_parnam_t) |
Remove a partition from the list of partitions for which this transaction controller processes requests. |
|
Method |
Description |
|
RejectTransaction(rtr_reason_t) |
Vote to reject the current transaction. |
|
SendApplicationEvent(RTRApplicationEvent, rtr_const_rcpspc_t, rtr_const_msgfmt_t) |
Send an application-defined event within the current facility to the client. |
|
SendApplicationMessage(RTRApplicationMessage, rtr_const_msgfmt_t) |
Send an application-defined message to the client whose transaction this controller call it is currently processing. |
Get State Methods
|
Method |
Description |
|
GetFacilityName(rtr_facnam_t, const size_t) |
Get facility name for the current transaction, if one exists. |
|
GetPartitionName(rtr_parnam_t, const size_t) |
Get partition name for the current transaction, if one exists. |
|
Get properties of the current transaction. |
RTRServerTransactionController::AcceptTransaction();
Prototype
virtual rtr_status_t AcceptTransaction(rtr_reason_t rtrReasonCode = RTR_NO_REASON,
bool bIndependent = false);
Return Value
rtr_status_t
Interpret value for the success or failure of this call.
|
Status |
Message |
|
RTR_STS_NOACCEPT |
Client or server has already voted, or there is no active transaction. |
|
RTR_STS_NOMESSAGE |
The data object does not contain a message. |
|
RTR_STS_OK |
Normal successful completion. |
|
RTR_STS_TXNOTACT |
No transaction currently active on this channel. |
Parameters
rtrReasonCode
Optional reason for accepting the transaction. This reason is ORed together with the reasons of the other participants in the transaction and returned to all participants of the transaction. The participants can retrieve this reason by calling RTRMessage::GetReason().
bIndependent
If set to true, the transaction is considered independent of other transactions that RTR is processing. Independent transactions can improve performance in certain shadowing conditions because RTR will not need to maintain the order in which this transaction is processed on the shadow node.
Description
Call this member function to accept the transaction currently being processed.
Example
ABCSHandlers::OnPrepareTransaction( RTRMessage *pRTRMessage, RTRServerTransactionController *pController )
{
// We simply check to see if anything has gone wrong. If so,
// reject the transaction, otherwise accept it.
if (true == m_bVoteToAccept)
{
pController->AcceptTransaction();
}
else
{
pController->RejectTransaction();
}
return;
}
AcknowledgeTransactionOutcome()
RTRServerTransactionController::AcknowledgeTransactionOutcome();
Prototype
virtual rtr_status_t AcknowledgeTransactionOutcome();
Return Value
rtr_status_t
Interpret value for the success or failure of this call.
|
Status |
Message |
|
RTR_STS_ACKTXN |
AcknowledgeTransactionOutcome can only be called after receiving the transaction outcome. |
|
RTR_STS_NOMESSAGE |
The data object does not contain a message. |
|
RTR_STS_OK |
Normal successful completion. |
Parameters
None
Description
Call this member function after the application receives an indication of the outcome of the transaction, that is, the transaction has been either accepted or rejected.
Calling this method is mandatory. RTR will not process the next transaction until the application acknowledged that it has received the outcome of the transaction.
Example
ABCSHandlers::OnAccepted( RTRMessage *pRTRMessage, RTRServerTransactionController *pController )
{ pController->AcknowledgeTransactionOutcome();
return;
}
RTRServerTransactionController::ForceTransactionRetry();
Prototype
virtual rtr_status_t ForceTransactionRetry ();
Return Value
rtr_status_t
Interpret value for the success or failure of this call.
|
Status |
Message |
|
RTR_STS_NORETRYTXN |
ForceRetryTransaction can only be called while processing a transaction. |
|
RTR_STS_OK |
Normal successful completion. |
Parameters
None
Description
Call this function when your application wants the current transaction to be represented to your application without being rejected. If this call is made before the application votes to accept or reject the transaction, the maximum number of attempts will be 3. If this function is called after the application has voted, the maximum number of attempts will be determined by the current value of the Recovery Retry Count attribute of the partition. Note that this attribute can be changed by using the RTRPartitionProperties class or by issuing a command to the RTR command line interface.
Example
pController-> ForceTransactionRetry();
RTRServerTransactionController::GetFacilityName();
Prototype
virtual rtr_status_t GetFacilityName (rtr_facnam_t pszFacilityName,
const size_t uiFacilityNameSize);
Return Value
rtr_status_t
Interpret value for the success or failure of this call.
|
Status |
Message |
|
RTR_STS_APPBUFFTOOSMALL |
The application buffer is too small. |
|
RTR_STS_INVARGPTR |
Invalid parameter address specified on last call. |
|
RTR_STS_OK |
Normal successful completion. |
Parameters
pszFacilityName
A null-terminated pointer to a facility name. Memory is allocated by the function call. If the size of the parameter is not big enough, the return error message RTR_STS_APPBUFFTOOSMALL is returned.
uiFacilityNameSize
An unsigned integer for the size of the named facility.
Description
Obtain the facility name, which the current transaction is executing in.
Memory is allocated by the caller and if uiFacilityNameSize is not big enough, an error message is returned.
Example
pController->GetFacilityName(pszFacilityName, uiFacilityNameSize);
RTRServerTransactionController::GetPartitionName();
Prototype
virtual rtr_status_t GetPartitionName(rtr_parnam_t pszPartitionName,
const size_t uiPartitionNameSize
RTRData *pRTRData);
Return Value
rtr_status_t
Interpret value for the success or failure of this call.
|
Status |
Message |
|
RTR_STS_APPBUFFTOOSMALL |
The application buffer is too small. |
|
RTR_STS_DATANOTAVAILABL |
A required property was not available. |
|
RTR_STS_INVARGPTR |
Invalid parameter address specified on last call. |
|
RTR_STS_OK |
Normal successful completion |
|
RTR_STS_TXNOTACT |
No transaction currently active on this channel. |
Parameters
pszPartitionName
A null-terminated pointer to a partition name.
uiPartitionNameSize
An unsigned integer for the size of the named partition.
pRTRData
The name of the partition on which the data object (message or event) was received.
Description
Obtain the partition name, which the current transaction is using.
Example
char szPartitionName[RTR_MAX_PARNAM_LEN+1];
sStatus = pController-> GetPartitionName(&szPartitionName[0],
RTR_MAX_PARNAM_LEN+1,
pRTRData);
// This call will either succeed or return RTR_STS_NOPARTITION.
// This means that the dat object has no partition associated with
// it. Only application messages and certain RTR events have a
// partition associated with them.
RTRServerTransactionController::GetProperties();
Prototype
virtual RTRServerTransactionProperties* GetProperties();
Parameters
None
Description
This method gets a pointer to the RTRServerTransacitonProperties object describing the server transaction. If a transaction does not exist, NULL is returned.
Example
RTRServerTransactionProperties *pTxnProp =
pController->GetProperties();
If (PTxnProp->TransactionIsOriginal())
{
…
}
RTRServerTransactionController::Receive();
Prototype
virtual rtr_status_t Receive(RTRData **pRTRData,
rtr_timout_t tTimeout = RTR_NO_TIMOUTMS);
Return Value
rtr_status_t
Interpret value for the success or failure of this call.
|
Status |
Message |
|
RTR_STS_ACPNOTVIA |
RTR ACP not a viable entity. |
|
RTR_STS_INVCHANNEL |
Invalid channel argument. |
|
RTR_STS_INVDATPTRPTARG |
Invalid pointer-to-data-pointer pointer argument |
|
RTR_STS_INVFLAGS |
Invalid flags argument. |
|
RTR_STS_INVMSG |
Invalid pmsg argument. |
|
RTR_STS_INVRMNAME |
Invalid resource manager name. |
|
RTR_STS_NOACP |
No RTRACP process available. |
|
RTR_STS_NOMESSAGE |
The data object does not contain a message. |
|
RTR_STS_NORECEIVE |
Attempting to receive at this point is not allowed. |
|
RTR_STS_OK |
Normal successful completion. |
|
RTR_STS_TIMOUT |
Call to Receive timed out. |
|
RTR_STS_TRUNCATED |
Buffer too short for message. Message has been truncated. |
Parameters
pRTRData
A pointer passed by reference, which will receive an object, derived from RTRData. This object can be any of the following:
If a class factory is registered with the transaction controller, the application has the ability to have this object be any application class derived from RTRData. By calling the Dispatch() method, the most over-ridden implementation of dispatch will be called.
For more information, see the description of the RTR receive model in the RTR Application Design Guide.
tTimeout
The maximum amount of time that the application is willing to wait for this receive to complete. The timeout value is in milliseconds.
Description
This member function should be called when the application is ready to receive messages and events from the RTR framework. Typically this function is called in a loop. The RTRData object returned contains the message or event type, as well as other information useful to the application.
For more information see:
RTRData
Example
// Continually loop receiving messages and dispatching them to the handlers.
void ABCOrderProcessor::ProcessIncomingOrders()
{
// Start processing orders
abc_status sStatus = RTR_STS_OK;
RTRData *pOrder = NULL;
while (1)
{
// Receive an Order
sStatus = Receive(&pOrder);
print_status_on_failure(sStatus);
if(ABCSuccess != sStatus) break;
// If we can't get an Order then stop processing.
delete pOrder;
}
return;
}
RTRServerTransactionController::RegisterClassFactory();
Prototype
virtual rtr_status_t RegisterClassFactory( RTRClassFactory *pFactory
);Return Value
rtr_status_t
Interpret value for the success or failure of this call.
|
Status |
Message |
|
RTR_STS_INVFACTORYPTARG |
The factory argument pointer is invalid. |
|
RTR_STS_OK |
Normal successful completion. |
Parameters
pFactory
Pointer to an RTRClassFactory object that is called, if registered, from the RTR framework when processing all Receive calls in your application.
Description
A class factory returns an object for RTR to use (write data to) when the method RTRServerTransactionController::Receive is called. The application can register their own class factory and override the functions to return their own objects derived from the RTR data classes. The four RTR data classes are RTRApplicationMessage, RTRApplicationEvent, RTRMessage, and RTREvent.
Registering a class factory is not a requirement. An application would register a class factory only when they want to customize the object being allocated.
Example
sStatus = RegisterClassFactory(&m_ClassFactory);
print_status_on_failure(sStatus);
RTRServerTransactionController::RegisterFacility();
Prototype
virtual rtr_status_t RegisterFacility (rtr_const_facnam_t pszFacilityName);
Return Value
rtr_status_t
Interpret value for the success or failure of this call.
|
Status |
Message |
|
RTR_STS_INVALIDFACILITY |
The specified facility does not exist. |
|
RTR_STS_INVFACNAMEARG |
The facility name argument is invalid. |
|
RTR_STS_OK |
Normal successful completion. |
|
RTR_STS_RTRNOTRUNNING |
RTR is not running. |
Parameters
pszFacilityName
Pointer to a null-terminated facility name.
Description
Call the RegisterFacility() member function to register an existing RTR facility for your application. By registering a facility, your application informs RTR of the facility for which your application can process transactions.
Example
// Register the facility with the transaction controller.
sStatus = RegisterFacility(ABCFacility);
print_status_on_failure(sStatus);
RTRServerTransactionController::RegisterHandlers();
Prototype
virtual rtr_status_t RegisterHandlers (
RTRServerMessageHandler *pMessageHandler,
RTRServerEventHandler *pEventHandle
r);Return Value
rtr_status_t
Interpret value for the success or failure of this call.
|
Status |
Message |
|
RTR_STS_INVEVNTHNDPTARG |
The event handler pointer argument is invalid. |
|
RTR_STS_INVMSGHNDLPTARG |
The message handler pointer argument is invalid. |
|
RTR_STS_OK |
Normal successful completion. |
Parameters
pMessageHandler
Pointer to an RTRServerMessageHandler object that will process all server messages in your application.
pEventHandler
Pointer to an RTRServerMessageHandler object that will process all server events in your application.
Description
Call the RegisterHandlers member function to register RTR message and event handlers for your application. By registering the handlers, your application informs RTR of the different configurations for which your application can process transactions. Your application can only use one partition at a time. The message and event handlers are called by the RTRData::Dispatch method.
Specify pMessageHandler and/or pEventHandler if your application wishes to make use of the RTR frameworks predefined handlers.
For more information on handlers see:
Example
// Register the message and event handlers with the transaction controller.
sStatus = pTransaction->RegisterHandlers( pAppClassDerivedFromRTRMessageHandler,
pAppClassDerivedFromRTREventHandler
);
assert(RTR_STS_OK == sStatus);
RTRServerTransactionController::RegisterPartition();
Prototype
virtual rtr_status_t RegisterPartition(rtr_const_parnam_t pszPartitionName,
rtr_const_rcpnam_t szRecipientName = RTR_NO_RCPNAM,
rtr_const_access_t pszAccess = RTR_NO_ACCESS);
Return Value
rtr_status_t
Interpret value for the success or failure of this call.
|
Status |
Message |
|
RTR_STS_DUPLPARTITION |
Attempting to insert a duplicate partition. |
|
RTR_STS_FACNOTREG |
Facility is not registered. |
|
RTR_STS_INVACCSTRPTRARG |
The access string argument is invalid. |
|
RTR_STS_INVPARTNAMEARG |
The partition name argument is invalid. |
|
RTR_STS_INVRECPNAMPTARG |
The recipient name argument is invalid. |
|
RTR_STS_OK |
Normal successful completion. |
|
RTR_STS_RTRNOTRUNNING |
RTR is not running. |
Parameters
pszPartitionName
A null-terminated pointer to a partition name.
szRecipientName
pszAccess
Pointer to a null-terminated string containing the access parameter. The default value is RTR_NO_ACCESS.
Description
Call the RegisterPartition member function to register an RTR partition for your application. By registering a partition, your application informs RTR of the different configurations for which your application can process transactions. Your application can only use one partition at a time.
It is mandatory to register a partition that already exists in a registered facility. RegisterPartition may be called multiple times to register multiple partitions.
Example
// Register the partition with the transaction controller.
sStatus = pTransaction->RegisterPartition( "MyPartition);
assert(RTR_STS_OK == sStatus);
RTRServerTransactionController::RejectTransaction();
Prototype
virtual rtr_status_t RejectTransaction(rtr_reason_t rtrReasonCode = RTR_NO_REASON);
Return Value
rtr_status_t
Interpret value for the success or failure of this call.
|
Status |
Message |
|
RTR_STS_NOMESSAGE |
The data object does not contain a message. |
|
RTR_STS_NOREJECT |
Client or server has already voted, or there is no active transaction. |
|
RTR_STS_OK |
Normal successful completion. |
|
RTR_STS_TXNOTACT |
No transaction is currently active on this channel. |
Parameters
rtrReasonCode
Optional reason for rejecting the transaction. This reason is returned to the other participants in the transaction. The participants can retrieve this reason by calling RTRMessage::GetReason.
Description
Call this member function to reject the transaction currently being processed by this object.
Example
pController->RejectTransaction();
RTRServerTransactionController()
RTRServerTransactionController::RTRServerTransactionController();
Prototype
RTRServerTransactionController();
virtual ~RTRServerTransactionController();
Return Value
None
Parameters
None
Description
Call this constructor to create an RTRServerTransactionController object.
Example
ABCOrderProcessor::ABCOrderProcessor()
{
}
RTRServerTransactionController::SendApplicationEvent();
Prototype
virtual rtr_status_t SendApplicationEvent( RTRApplicationEvent * pRTRApplicationEvent,
rtr_const_rcpspc_t szRecipientName = "*",
rtr_const_msgfmt_t mfMessageFormat = RTR_NO_MSGFMT);
Return Value
rtr_status_t
Interpret value for the success or failure of this call.
|
Status |
Message |
|
RTR_STS_INSVIRMEM |
Insufficient virtual memory. |
|
RTR_STS_INVAPPEVNTPTARG |
Invalid application event pointer argument. |
|
RTR_STS_INVMSGFMTPTRARG |
The message format string argument is invalid. |
|
RTR_STS_INVRECPNAMPTARG |
The recipient name argument is invalid. |
|
RTR_STS_NOEVENTDATA |
There is no event data associated with the event. |
|
RTR_STS_NOMESSAGE |
The data object does not contain a message. |
|
RTR_STS_OK |
Normal successful completion. |
Parameters
pRTRApplicationEvent
Pointer to an RTRApplicationEvent object which contains application data to be sent to the client.
szRecipientName
mfMessageFormat
Message format description. mfMessageFormat is a null-terminated character string containing the format description of the message. RTR uses this description to convert the contents of the message appropriately when processing the message on different hardware platforms. If no parameter is specified, the default is no special formatting.
Description
This member function should be called when the application wants to send an application-defined (broadcast) event to the client. Formerly, application-defined events are only delivered to the clients that have subscribed for them and these are not related to any transaction. Only reply messages go to the client that started the transaction. Simply calling this function will not deliver the event to the client, unless it has subscribed for it. With the C++ API, you "subscribe" by overriding the event handler methods. The events are only received if they are overridden.
Example
sStatus = pTransaction->SendApplicationEvent(pEventA);
assert(RTR_STS_OK == sStatus);
RTRServerTransactionController::SendApplicationMessage();
Prototype
virtual rtr_status_t SendApplicationMessage(RTRApplicationMessage
*pRTRApplicationMessage,
rtr_const_msgfmt_t mfMessageFormat = RTR_NO_MSGFMT);
Return Value
rtr_status_t
Interpret value for the success or failure of this call.
|
Status |
Message |
|
RTR_STS_INSVIRMEM |
Insufficient virtual memory. |
|
RTR_STS_INVAPPMSGPTARG |
Invalid application message pointer argument. |
|
RTR_STS_INVMSGFMTPTRARG |
The message format string argument is invalid. |
|
RTR_STS_NOMESSAGE |
The data object does not contain a message. |
|
RTR_STS_NOSEND |
Attempting to send an application message at this point is not allowed. |
|
RTR_STS_OK |
Normal successful completion. |
Parameters
pRTRApplicationMessage
Pointer to an RTRApplicationMessage object which contains application data to be sent to the client.
mfMessageFormat
Message format description. mfMessageFormat is a null-terminated character string containing the format description of the message. RTR uses this description to convert the contents of the message appropriately when processing the message on different hardware platforms. If no parameter is specified, the default is no special formatting.
Description
This member function should be called when the application wants to send application data to the client which originally established the transaction. The RTRData object contains the data to be sent.
For more information see:
RTRData
Example
// Send the Server a message
sStatus = pTransaction->SendApplicationMessage(pMessage1);
assert(RTR_STS_OK == sStatus);
RTRServerTransactionController::UnRegisterPartition();
Prototype
virtual rtr_status_t UnRegisterPartition(rtr_const_parnam_t pszPartitionName);
Return Value
rtr_status_t
Interpret value for the success or failure of this call.
|
Status |
Message |
|
RTR_STS_INVPARTNAMEARG |
The partition name argument is invalid |
|
RTR_STS_NOPARTITION |
The partition name has not been previously registered. |
|
RTR_STS_OK |
Normal successful completion |
Parameters
pszPartitionName
A null-terminated pointer to a partition name.
Description
Remove a partition from the list of partitions for which this transaction controller processes requests.
Example
pController-> UnRegisterPartition();
RTRServerTransactionProperties
This class holds, makes available, and allows modification of the properties of its associated RTRServerTransactionController object. It provides attributes for a given transaction.
Typically, RTR C++ API applications obtain this object by calling GetProperties on the transaction controller. Other applications, including legacy applications, may create an instance of this object by calling the constructor with the TID of the transaction.
RTRServerTransactionProperties Class Members
Construction
|
Method |
Description |
|
RTRServerTransactionProperties(const rtr_tid_t) |
Constructor |
|
~RTRServerTransactionProperties() |
Destructor |
Get the Type of Transaction
|
Method |
Description |
|
Tests whether the transaction is an original transaction. |
|
|
Tests whether the transaction is a recovered transaction. |
|
|
Tests whether the transaction is a replayed transaction. |
Get Functions
|
Method |
Description |
|
GetFacilityName(rtr_facnam_t, const size_t) |
Get the facility. |
|
GetTID(rtr_tid_t) |
Get the TID (transaction ID). |
|
GetTransactionState(rtr_tx_jnl_state_t) |
Get the transaction state. |
When setting the state of a transaction, the state transaction must be valid, or else the call will return an error. For each of the set state methods, there are two versions. The versions with no parameters attempt to transition the transaction to the requested state. The second version for each method will only transition to the requested state if the current transaction state matches the state passed in the stCurrentTxnState argument.
Set the State of Transaction
|
Method |
Description |
|
Sets the transaction state to abort. |
|
|
SetStateToAbort(rtr_tx_jnl_state_t) |
Sets the transaction state to abort. |
|
Sets the transaction state to commit. |
|
|
SetStateToCommit(rtr_tx_jnl_state_t) |
Sets the transaction state to commit. |
|
Sets the transaction state to done. |
|
|
SetStateToDone(rtr_tx_jnl_state_t) |
Sets the transaction state to done. |
|
Sets the transaction state to exception. |
|
|
SetStateToException(rtr_tx_jnl_state_t) |
Sets the transaction state to exception. |
RTRServerTransactionProperties::GetFacilityName();
Prototype
rtr_status_t GetFacilityName(rtr_facnam_t pszFacilityName,
const size_t uiFacilityNameSize );
Return Value
rtr_status_t
Interpret value for the success or failure of this call.
|
Status |
Message |
|
RTR_STS_APPBUFFTOOSMALL |
The application buffer is too small. |
|
RTR_STS_DATANOTAVAILABL |
A required property was not available. |
|
RTR_STS_INVARGPTR |
Invalid parameter address specified on last call. |
|
RTR_STS_OK |
Normal successful completion. |
Parameters
pszFacilityName
Pointer to a zero-terminated string receiving the name of the associated facility with the transaction.
uiFacilityNameSize
Description
This method gets the facility name associated with the transaction and described by the RTRServerTransactionProperties object.
Example
pTransaction->GetFacility(pszFacilityName);
RTRServerTransactionProperties::GetTID();
Prototype
rtr_status_t GetTID(rtr_tid_t &rtrTID);
Return Value
rtr_status_t
Interpret value for the success or failure of this call. RTR_STS_OK is the normal successful completion. Returns RTR_STS_NOTID on failure.
Parameters
rtrTID
An RTR transaction identifier.
Description
This method copies the transaction identifier (TID) of the transaction described by the RTRServerTransactionProperties object for the current transaction.
Example
rtr_tid_t tid = pController->GetTID(&rtrTID);
RTRServerTransactionProperties:: GetTransactionState ();
Prototype
rtr_status_t GetTransactionState (rtr_tx_jnl_state_t &pstCurrentTxnState);
Return Value
rtr_status_t
Interpret value for the success or failure of this call.
|
Status |
Message |
|
RTR_STS_INVTXNSTATPTARG |
Invalid transaction state pointer argument. |
|
RTR_STS_DATANOTAVAILABL |
A required property was not available. |
|
RTR_STS_OK |
Normal successful completion |
Parameters
pstCurrentTxnState
Pointer to the transaction state of type rtr_tx_jnl_state_t.
Description
Get the transaction state for the current transaction.
Example
rtr_tx_jnl_state_t txnState;
rtr_status_t sStatus = GetTransactionState(txnState);
If ( rtr_tx_jnl_voted == txnState)
{
}
RTRServerTransactionProperties()
RTRServerTransactionProperties::RTRServerTransactionProperties();
Prototype
RTRServerTransactionProperties(const rtr_tid_t &tid);
virtual ~RTRServerTransactionProperties();
Return Value
None
Parameters
tid
A transaction identifier value of type rtr_tid_t.
Description
Call this constructor to create an RTRServerTransactionProperties object associated with the specified TID.
Example
RTRServerTransactionProperties::RTRServerTransactionProperties
{
}
RTRServerTransactionProperties::SetStateToAbort();
Prototype
rtr_status_t SetStateToAbort();
rtr_status_t SetStateToAbort(rtr_tx_jnl_state_t stCurrentTxnState);
Return Value
rtr_status_t
Interpret value for the success or failure of this call. RTR_STS_OK is the normal successful completion.
Parameters
stCurrentTxnState
A transaction state of type rtr_tx_jnl_state_t.
Description
This method is used to set the current server transaction state to abort .There are two forms:
Example
rtr_status_t sStatus = SetStateToAbort(txnState);
RTRServerTransactionProperties::SetStateToCommit();
Prototype
rtr_status_t SetStateToCommit();
rtr_status_t SetStateToCommit(rtr_tx_jnl_state_t stCurrentTxnState);
Return Value
rtr_status_t
Interpret value for the success or failure of this call. RTR_STS_OK is the normal successful completion.
Parameters
stCurrentTxnState
A transaction state of type rtr_tx_jnl_state_t.
Description
This method is used to set the current server transaction state to commit. There are two forms:
Example
rtr_status_t sStatus = SetStateToCommit(txnState);
RTRServerTransactionProperties::SetStateToDone();
Prototype
rtr_status_t SetStateToDone();
rtr_status_t SetStateToDone(rtr_tx_jnl_state_t stCurrentTxnState);
Return Value
rtr_status_t
Interpret value for the success or failure of this call. RTR_STS_OK is the normal successful completion.
Parameters
stCurrentTxnState
A transaction state of type rtr_tx_jnl_state_t.
Description
This method is used to set the current server transaction state to done. There are two forms:
Example
rtr_status_t sStatus = SetStateToDone(txnState);
RTRServerTransactionProperties::SetStateToException();
Prototype
rtr_status_t SetStateToException();
rtr_status_t SetStateToException(rtr_tx_jnl_state_t stCurrentTxnState);
Return Value
rtr_status_t
Interpret value for the success or failure of this call. RTR_STS_OK is the normal successful completion.
Parameters
stCurrentTxnState
A transaction state of type rtr_tx_jnl_state_t.
Description
This method is used to set the current server transaction state to exception. There are two forms:
Example
rtr_status_t sStatus = SetStateToException(txnState);
RTRServerTransactionProperties::TransactionIsOriginal();
Prototype
bool TransactionIsOriginal();
Return Value
bool
A true or false return value.
Parameters
None
Description
This method tests if the transaction is an original transaction. Note that this does not necessarily mean that the transaction has never been presented before.
Example
RTRServerTransactionProperties *pstProperties =
pController->GetProperties();
bool bOriginal = pTransactionController ->TransactionIsOriginal();
RTRServerTransactionProperties::TransactionIsRecovery();
Prototype
bool TransactionIsRecovery();
Return Value
bool
A true or false return value.
Parameters
None
Description
This method tests if the transaction is a recovered transaction. A recovered transaction is one where the transaction was held in the RTR journal during a crash of a node, and has been restored and can be committed in the database.
Example
rtr_status_t sStatus = TransactionIsRecovery();
RTRServerTransactionProperties::TransactionIsReplay();
Prototype
bool TransactionIsReplay();
Return Value
bool
A true or false return value.
Parameters
None
Description
This method tests if the transaction is a replayed transaction.
Example
rtr_status_t sStatus = TransactionIsReplay();
The client classes of the RTR API are:
These classes are described in this section in alphabetical order.
This class defines event handlers for all potential events that an RTR client application can receive. Each handler has a default behavior. Applications should override those member functions for which they intend to perform application-specific processing.
Applications can extend this class by deriving from it and adding their own application-level event handlers.
For further information see RTRData::Dispatch().
RTRClientEventHandler Class Members
Construction
|
Method |
Description |
|
Constructor |
|
|
~RTRClientEventHandler() |
Destructor |
Operations
|
Method |
Description |
|
OnApplicationEvent(RTRApplicationEvent, RTRClientTransactionController) |
There is an event generated by the application, for the client. |
|
OnFacilityDead(RTREvent, RTRClientTransactionController) |
Default handler for the event where the facility is no longer operational. |
|
OnFacilityReady(RTREvent, RTRClientTransactionController) |
Default handler for the event where the facility has become operational. |
|
OnFrontendGainedLinkToRouter(RTREvent, RTRClientTransactionController) |
Default handler for the event where a frontend link to the current router has been established. |
|
OnFrontendLostLinkToRouter(RTREvent, RTRClientTransactionController) |
Default handler for the event where the frontend link to the current router has been lost. |
|
OnKeyRangeNoLongerAvailable(RTREvent, RTRClientTransactionController) |
Default handler for the event where no more servers remain for a particular routing key range. |
|
OnNewKeyRangeAvailable(RTREvent, RTRClientTransactionController) |
Default handler for the event where one or more servers for a new key range have become available. |
|
OnRouterGainedLinkToBackend(RTREvent, RTRClientTransactionController) |
Default handler for the event where a current router established a link to a backend. |
|
OnRouterLostLinkToBackend(RTREvent, RTRClientTransactionController) |
Default handler for the event where the current router lost a link to a backend. |
RTRClientEventHandler::OnApplicationEvent();
Prototype
virtual rtr_status_t OnApplicationEvent(RTRApplicationEvent *pRTRApplicationEvent,
RTRClientTransactionController *pController)
{
return RTR_STS_OK;
}
Parameters
pRTRApplicationEvent
Pointer to an RTRApplicationEvent object that describes the message which is being processed.
pController
Pointer to the transaction controller within which this event was received.
Description
The RTRData parameter contains an application event sent to it by an RTR server.
The default behavior is the handler dismisses the notification.
Example
MyCLIEventHandler::OnApplicationEvent( RTRApplicationEvent
*pRTRApplicationEvent,
RTRClientTransactionController
*pCTC )
{
cout << "An application event... " <<endl;
return RTR_STS_OK;
}
RTRClientEventHandler::OnFacilityDead();
Prototype
virtual rtr_status_t OnFacilityDead(RTREvent *pRTREvent,
RTRClientTransactionController *pController)
{
return RTR_STS_OK;
}
Parameters
pRTREvent
Pointer to an RTREvent object that describes the RTR-generated event being processed.
pController
Pointer to the transaction controller within which this event was received.
Description
This method provides the default handler for the event where the facility is no longer operational.
The client application is receiving an RTR-generated event. RTREvent contains the application-defined number RTR_EVTNUM_FACDEAD (97) and any associated data.
Example
MyCLIEventHandler::OnFacilityDead( RTREvent *pRTREvent,
RTRClientTransactionController *pCTC )
{
return RTR_STS_OK;
}
RTRClientEventHandler::OnFacilityReady();
Prototype
virtual rtr_status_t OnFacilityReady(RTREvent *pRTREvent,
RTRClientTransactionController *pController)
{
return RTR_STS_OK;
}
Parameters
pRTREvent
Pointer to an RTREvent object that describes the RTR-generated event being processed.
pController
Pointer to the transaction controller within which this event was received.
Description
This method provides the default handler for the event where the facility has become operational.
The client application is receiving an RTR-generated event. RTREvent contains the application-defined number RTR_EVTNUM_FACREADY (96) and any associated data.
Example
MyCLIEventHandler::OnFacilityReady( RTREvent *pRTREvent,
RTRClientTransactionController *pCTC )
{
return RTR_STS_OK;
}
OnFrontendGainedLinkToRouter()
RTRClientEventHandler::OnFrontendGainedLinkToRouter();
Prototype
virtual rtr_status_t OnFrontendGainedLinktToRouter(RTREvent *pRTREvent,
RTRClientTransactionController *pController)
{
return RTR_STS_OK;
}
Parameters
pRTREvent
Pointer to an RTREvent object that describes the RTR-generated event being processed.
pController
Pointer to the transaction controller within which this event was received.
Description
This method provides the default handler for the event where a frontend link to the current router has been established.
The client application is receiving an RTR-generated event. RTREvent contains the application-defined event number RTR_EVTNUM_FERTRGAIN (98) and any associated data.
Example
MyCLIEventHandler::OnFrontendGainedLinkToRouter( RTREvent
*pRTREvent,
RTRClientTransactionController
*pCTC )
{
return RTR_STS_OK;
}
RTRClientEventHandler::OnFrontendLostLinkToRouter();
Prototype
virtual rtr_status_t OnFrontendLostLinkToRouter(RTREvent *pRTREvent,
RTRClientTransactionController *pController)
{
return RTR_STS_OK;
}
Parameters
pRTREvent
Pointer to an RTREvent object that describes the RTR-generated event being processed.
pController
Pointer to the transaction controller within which this event was received.
Description
This method provides the default handler for the event where the frontend link to the current router has been lost.
The client application is receiving an RTR-generated event. RTREvent contains the application-defined number RTR_EVTNUM_FERTRLOSS (99) and any associated data.
Example
MyCLIEventHandler:: OnFrontendLostLinkToRouter (
RTREvent *pRTREvent,
RTRClientTransactionController *pCTC )
{
return RTR_STS_OK;
}
RTRClientEventHandler::OnNewKeyRangeAvailable();
Prototype
virtual rtr_status_t OnNewKeyRangeAvailable
(RTREvent * pRTREvent,RTRClientTransactionController *pController
){
return RTR_STS_OK;
}
Parameters
pRTREvent
Pointer to an RTREvent object that describes the RTR-generated event being processed.
pController
Pointer to the transaction controller within which this event was received.
Description
This method provides the default handler for the event where one or more servers for a new routing key range have become available.
The client application is receiving an RTR-generated event. RTREvent contains the application-defined number RTR_EVTNUM_KEYRANGEGAIN (102) and any associated data.
Example
MyCLIEventHandler:: OnNewKeyRangeAvailable (
RTREvent *pRTREvent,
RTRClientTransactionController *pCTC )
{
return RTR_STS_OK;
}
RTRClientEventHandler::OnKeyRangeNoLongerAvailable();
Prototype
virtual
rtr_status_t OnKeyRangeNoLongerAvailable(RTREvent * pRTREvent,RTRClientTransactionController *pController
){
return RTR_STS_OK;
}
Parameters
pRTREvent
Pointer to an RTREvent object that describes the RTR-generated event being processed.
pController
Pointer to the transaction controller within which this event was received.
Description
This method provides the default handler for the event where no more servers remain for a particular routing key range.
The client application is receiving an RTR-generated event. RTREvent contains the application-defined number RTR_EVTNUM_KEYRANGELOSS (103) and any associated data.
Example
MyCLIEventHandler:: OnKeyRangeNoLongerAvailable(
RTREvent *pRTREvent,
RTRClientTransactionController *pCTC )
{
return RTR_STS_OK;
}
RTRClientEventHandler::OnRouterGainedLinkToBackend();
Prototype
virtual
rtr_status_t OnRouterGainedLinkToBackend(RTREvent * pRTREvent,RTRClientTransactionController *pController
){
return RTR_STS_OK;
}
Parameters
pRTREvent
Pointer to an RTREvent object that describes the RTR-generated event being processed.
pController
Pointer to the transaction controller within which this event was received.
Description
This method provides the default handler for the event where the current router established a link to the backend.
The client application is receiving an RTR-generated event. RTREvent contains the application-defined event number RTR_EVTNUM_RTRBEGAIN (100) and any associated data.
Example
MyCLIEventHandler::OnRouterGainedLinkToBackend(
RTREvent *pRTREvent,
RTRClientTransactionController *pCTC )
{
return RTR_STS_OK;
}
RTRClientEventHandler::OnRouterLostLinkToBackend();
Prototype
virtual
rtr_status_t OnRouterLostLinkToBackend(RTREvent * pRTREvent,RTRClientTransactionController *pController
){
return RTR_STS_OK;
}
Parameters
pRTREvent
Pointer to an RTREvent object that describes the RTR-generated event being processed.
pController
Pointer to the transaction controller within which this event was received.
Description
This method provides the default handler for the event where the current router lost a link to a backend.
The client application is receiving an RTR-generated event. RTREvent contains the application-defined number RTR_EVTNUM_RTRBELOSS (101) and any associated data.
Example
MyCLIEventHandler::OnRouterLostLinkToBackend(
RTREvent *pRTREvent,
RTRClientTransactionController *pCTC )
{
return RTR_STS_OK;
}
RTRClientEventHandler::RTRClientEventHandler();
Prototype
RTRClientEventHandler();
Return Value
None
Parameters
None
Description
Construct a client event handler object.
Example
RTRClientEventHandler::RTRClientEventhandler()
{
}
This class defines message handlers for all potential messages that an RTR client application can receive. Each handler has a default behavior. Applications should override those member functions for which they intend to perform application-specific processing.
Note
Applications can extend this class by deriving from it and adding their own application-level message handlers.
For further information, see RTRData::Dispatch().
RTRClientMessageHandler Class Members
Construction
|
Method |
Description |
|
Constructor |
|
|
~RTRClientMessageHandler() |
Destructor |
Operations
|
Method |
Description |
|
OnAccepted(RTRMessage, RTRClientTransactionController) |
The specified transaction has been accepted by all participants. |
|
OnAllPreparedTransaction(RTRMessage, RTRClientTransactionController) |
The specified transaction has been prepared by all participants. |
|
OnApplicationMessage(RTRApplicationMessage, RTRClientTransactionController) |
The server has sent the client a message. |
|
A new transaction is being processed. |
|
|
OnRejected(RTRMessage, RTRClientTransactionController) |
The specified transaction has been rejected by a participant. |
|
OnReturnToSender(RTRMessage, RTRClientTransactionController) |
The message could not be delivered and has been returned to the sender. |
RTRClientMessageHandler::OnAccepted();
Prototype
virtual rtr_status_t OnAccepted(RTRMessage *pRTRMessage,
RTRClientTransactionController *pController)
{
return RTR_STS_OK;
}
Return Value
None
Parameters
pRTRMessage
Pointer to an RTRApplicationMessage object that describes the message which is being processed.
pController
Pointer to the transaction controller within which this message was received.
Description
The specified transaction has been accepted by all participants.
The default behavior is the handler dismisses the notification.
Example
rtr_status_t ABCCHandlers::OnAccepted( RTRMessage *pRTRMessage, RTRClientTransactionController *pController )
{
return ABCOrderSucceeded;
}
RTRClientMessageHandler::OnAllPreparedTransaction();
Prototype
virtual rtr_status_t OnAllPreparedTransaction (RTRMessage * pRTRMessage,
RTRClientTransactionController *pController)
{
RTR_STS_OK;
}
Parameters
pRTRMessage
Pointer to an RTRMessage object that describes the message which is being processed.
pController
Pointer to the transaction controller within which this message was received.
Description
The specified transaction has been prepared by all participants.
The default behavior is the handler dismisses the notification.
Example
rtr_status_t MyCLIMessageHandler::OnAllPreparedTransaction(
RTRMessage *pmyMsg,
RTRClientTransactionController *pTC)
{
cout << "prepare txn " << endl;
return RTR_STS_OK;
}
RTRClientMessageHandler::OnApplicationMessage();
Prototype
virtual rtr_status_t OnApplicationMessage(RTRApplicationMessage
*pRTRApplicationMessage,
RTRClientTransactionController *pController)
{
RTR_STS_OK;
}
Return Value
None
Parameters
pRTRApplicationMessage
Pointer to an RTRApplicationMessage object that describes the message which is being processed.
pController
Pointer to the transaction controller within which this message was received.
Description
The RTRApplicationMessage parameter contains application data sent to it by an RTR server.
The default behavior is the handler dismisses the notification.
Example
rtr_status_t MyCLIMessageHandler::OnApplicationMessage(
RTRApplicationMessage *pmyMsg,
RTRClientTransactionController *pTC)
{
return RTR_STS_OK;
}
RTRClientMessageHandler::OnInitialize();
Prototype
virtual rtr_status_t OnInitialize()'
{
RTR_STS_OK;
}
Parameters
None
Description
This method is called at the beginning of each transaction to prepare the server for a transaction. Allowing the application to perform any application-specific initialization necessary to process the transaction.
Example
rtr_status_t MyCLIMessageHandler::OnInitialize()
{
return RTR_STS_OK;
}
RTRClientMessageHandler::OnRejected();
Prototype
virtual rtr_status_t OnRejected(RTRMessage * pRTRMessage,
RTRClientTransactionController *pController)
{
return RTR_STS_OK;
}
Parameters
pRTRMessage
Pointer to an RTRMessage object that describes the message which is being processed.
pController
Pointer to the transaction controller within which this message was received.
Description
The specified transaction has been rejected by a participant.
The default behavior is the handler dismisses the notification.
Example
rtr_status_t ABCCHandlers::OnRejected( RTRMessage *pRTRMessage, RTRClientTransactionController *pController )
{
return ABCOrderFailed;
}
RTRClientMessageHandler::OnReturnToSender();
Prototype
virtual rtr_status_t OnReturnToSender(RTRMessage * pRTRMessage,
RTRClientTransactionController *pController)
{
return RTR_STS_OK;
}
Parameters
pRTRMessage
Pointer to an RTRMessage object that describes the message which is being processed.
pController
Pointer to the transaction controller within which this message was received.
Description
The message could not be delivered and has been returned to sender.
The default behavior is the handler dismisses the notification.
Example
rtr_status_t MyCLIMessageHandler::OnReturnToSender(
RTRMessage *pmyMsg,
RTRClientTransactionController *pTC)
{
return RTR_STS_OK;
}
RTRClientMessageHandler::RTRClientMessageHandler();
Prototype
RTRClientMessageHandler();
virtual ~RTRClientMessageHandler();
Return Value
None
Parameters
None
Description
Call this constructor to create an RTRClientMessageHandler object.
Example
MyCLIMessageHandler::MyCLIMessageHandler()
{
}
MyCLIMessageHandler::~MyCLIMessageHandler()
{
}
RTRClientTransactionController
RTRClientTransactionController is the main class used to create an RTR client application. The transaction controller object is used to send and receive all data between RTR clients and servers. Typically one instance of this class is used to process multiple consecutive transactions.
RTRClientTransactionController Class Members
Construction
|
Method |
Description |
|
Constructor |
|
|
~RTRClientTransactionController() |
Destructor |
Basic Methods
|
Method |
Description |
|
AcceptTransaction(rtr_reason_t) |
Accept the current transaction. |
|
Receive(RTRData, rtr_timout_t) |
Receive an RTR or application-generated message or an RTR event. |
|
RegsiterClassFactory(RTRClassFactory) |
Register a class factory for RTR to call when creating RTRData-derived objects. |
|
RegisterFacility(rtr_const_facnam_t, rtr_const_rcpspc_t, rtr_const_access_t) |
Inform the controller that it should operate within the given facility. |
|
RegisterHandlers(RTRClientMessageHandler, RTRClientEventHandler) |
Register handlers for messages and events. |
|
RejectTransaction(const rtr_reason_t) |
Reject the current transaction. |
|
SendApplicationEvent(RTRApplicationEvent, rtr_const_rcpspc_t, rtr_const_msgfmt_t) |
Send an application-defined event to the server. |
|
SendApplicationMessage(RTRApplicationMessage, bool, bool, rtr_const_msgfmt_t) |
Send an application-defined message to the server. |
|
StartTransaction(rtr_timout_t) |
Start a new transaction. |
RTRClientTransactionController::AcceptTransaction();
Prototype
virtual rtr_status_t AcceptTransaction(rtr_reason_t rtrReasonCode =
RTR_NO_REASON);
Return Value
rtr_status_t
Interpret value for the success or failure of this call.
|
Status |
Message |
|
RTR_STS_NOACCEPT |
Client or server has already voted, or there is no active transaction. |
|
RTR_STS_NOMESSAGE |
The data object does not contain a message. |
|
RTR_STS_OK |
Normal successful completion. |
|
RTR_STS_TXNOTACT |
No transaction currently active on this channel. |
Parameters
rtrReasonCode
Optional reason for accepting the transaction. This reason is ORed together with the reasons of the other participants in the transaction and returned to all participants of the transaction. The participants can retrieve this reason by calling RTRMessage::GetReason().
Description
Call this member function to accept the transaction currently being processed by this object.
Example
// Let RTR know that this is the only object being sent and that
// we are done with our work.
cout << "AcceptTransaction..." << endl;
sStatus = AcceptTransaction();
print_status_on_failure(sStatus);
RTRClientTransactionController::Receive();
Prototype
virtual rtr_status_t Receive (RTRData **pRTRData,
rtr_timout_t tTimeout = RTR_NO_TIMOUTMS);
Return Value
rtr_status_t
Interpret value for the success or failure of this call.
|
Status |
Message |
|
RTR_STS_INVDATPTRPTARG |
Invalid pointer-to-data-pointer pointer argument |
|
RTR_STS_NORECEIVE |
Attempting to receive at this point is not allowed. |
|
RTR_STS_NOMESSAGE |
The data object does not contain a message. |
|
RTR_STS_OK |
Normal successful completion. |
|
RTR_STS_TIMOUT |
Call to Receive timed out. |
|
RTR_STS_TRUNCATED |
Buffer too short for message. Message has been truncated. |
Parameters
pRTRData
A pointer passed by reference, which will receive an object derived from RTRData. This object can be any of the following:
If a class factory is registered with the transaction controller, the application has the ability to have this object be any application class derived from RTRData. By calling the Dispatch() method, the most overridden implementation of dispatch will be called.
For more information, see the description of the RTR receive model.
tTimeout
An optional receive timeout value in milliseconds. If the timeout expires, the call completes with status RTR_STS_TIMOUT.
Description
This member function should be called when the application is ready to receive messages and events from the RTR framework. Typically this function is called in a loop. The RTRData object returned contains the message or event type as well as other information useful to the application.
For more information see:
RTRData
Example
abc_status ABCOrderTaker::DetermineOutcome()
{
RTRData *pResult = NULL;
abc_status sStatus = ABCSuccess;
bool bDone = false;
while (!bDone)
{
sStatus = Receive(&pResult);
print_status_on_failure(sStatus);
}
delete pResult;
return sStatus;
}
RTRClientTransactionController::RegisterClassFactory();
Prototype
virtual rtr_status_t RegisterClassFactory (RTRClassFactory *pFactory
);Return Value
rtr_status_t
Interpret value for the success or failure of this call.
|
Status |
Message |
|
RTR_STS_INVFACTORYPTARG |
The factory argument pointer is invalid. |
|
RTR_STS_OK |
Normal successful completion. |
Parameters
pFactory
Pointer to an RTRClassFactory object that is called, if registered, from the RTR framework when processing all Receive methods in your application.
Description
Registering a class factory is not a requirement. An application would register a class factory only when they want to customize the object being allocated.
Example
sStatus = RegisterClassFactory(*pFactory);
print_status_on_failure(sStatus);
RTRClientTransactionController::RegisterFacility();
Prototype
virtual rtr_status_t RegisterFacility (rtr_const_facnam_t pszFacilityName,
rtr_const_rcpspc_t szRecipientName = "*",
rtr_const_access_t pszAccess = RTR_NO_ACCESS);
Return Value
rtr_status_t
Interpret value for the success or failure of this call.
|
Status |
Message |
|
RTR_STS_INVACCSTRPTRARG |
The access string argument is invalid. |
|
RTR_STS_INVALIDFACILITY |
The specified facility does not exist. |
|
RTR_STS_INVFACNAMEARG |
The facility name argument is invalid. |
|
RTR_STS_INVRECPNAMPTARG |
The recipient name argument is invalid. |
|
RTR_STS_OK |
Normal successful completion. |
|
RTR_STS_RTRNOTRUNNING |
RTR is not running. |
Parameters
pszFacilityName
Pointer to a null-terminated facility name.
szRecipientName
pszAccess
Pointer to a null-terminated string containing the access parameter. The default is RTR_NO_ACCESS.
Description
Call the RegisterFacility() member function to register an RTR facility for your application. By registering a facility, your application informs RTR of the facility for which your application can process transactions.
Example
// Register the facility with RTR.
sStatus = RegisterFacility(ABCFacility);
print_status_on_failure(sStatus);
if(RTR_STS_OK == sStatus)
{
m_bRegistered = true;
}
RTRClientTransactionController::RegisterHandlers();
Prototype
virtual rtr_status_t RegisterHandlers (RTRClientMessageHandler *pMessageHandler,
RTRClientEventHandler *pEventHandler);
Return Value
rtr_status_t
Interpret value for the success or failure of this call.
|
Status |
Message |
|
RTR_STS_INVEVNTHNDPTARG |
The event handler pointer argument is invalid. |
|
RTR_STS_INVMSGHNDLPTARG |
The message handler pointer argument is invalid. |
|
RTR_STS_OK |
Normal successful completion. |
Parameters
pMessageHandler
Pointer to an RTRClientMessageHandler object that processes messages received.
pEventHandler
Pointer to an RTRClientEventHandler object that processes events received.
Description
Call the RegisterHandlers member function to register message and event handlers for your application. By registering an environment (a facility and a partition), your application informs RTR of the different configurations for which your application can process transactions. Your application will only use one environment at a time. The RTR framework picks the most efficient environment for your application depending on the number of client requests being received. If no environment is specified, RTR uses any of the previously defined environments in your application process.
Specify pMessageHandler and/or pEventHandler in order for your application to make use of the RTR framework's predefined handlers.
For more information on handlers see:
Example
// ABC Handlers
// Register the both handlers with RTR
sStatus = RegisterHandlers(&m_rtrHandlers,&m_rtrHandlers);
print_status_on_failure(sStatus);
RTRClientTransactionController::RejectTransaction();
Prototype
virtual rtr_status_t RejectTransaction(const rtr_reason_t rtrReasonCode =
RTR_NO_REASON);
Return Value
rtr_status_t
Interpret value for the success or failure of this call.
|
Status |
Message |
|
RTR_STS_FACNOTREG |
Facility is not registered. |
|
RTR_STS_NOMESSAGE |
The data object does not contain a message. |
|
RTR_STS_NOREJECT |
Client or server has already voted, or there is no active transaction. |
|
RTR_STS_OK |
Normal successful completion. |
|
RTR_STS_TXNOTACT |
No transaction is currently active on this channel. |
Parameters
rtrReasonCode
Optional reason for rejecting the transaction. This reason is returned to the other participants in the transaction. The participants can retrieve this reason by calling RTRMessage::GetReason().
Description
Call this member function to reject the transaction currently being processed by this object.
Example
pController->RejectTransaction();
RTRClientTransactionController()
RTRClientTransactionController::RTRClientTransactionController();
Prototype
RTRClientTransactionController();
virtual ~RTRClientTransactionController();
Return Value
None
Parameters
None
Description
Call this constructor to create an RTRClientTransactionController object.
Example
ABCOrderTaker::ABCOrderTaker():m_bRegistered(false)
{
}
RTRClientTransactionController::SendApplicationEvent();
Prototype
virtual rtr_status_t SendApplicationEvent(RTRApplicationEvent * pRTRApplicationEvent,
rtr_const_rcpspc_t szRecipientName = "*",
rtr_const_msgfmt_t mfMessageFormat =
RTR_NO_MSGFMT);
Return Value
rtr_status_t
Interpret value for the success or failure of this call.
|
Status |
Message |
|
RTR_STS_INSVIRMEM |
Insufficient virtual memory. |
|
RTR_STS_INVAPPEVNTPTARG |
Invalid application event pointer argument. |
|
RTR_STS_INVMSGFMTPTRARG |
The message format string argument is invalid. |
|
RTR_STS_INVRECPNAMPTARG |
The recipient name argument is invalid. |
|
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
RTRApplicationEvent
Pointer to an RTRApplicationEvent object which contains application data to be sent to the server.
szRecipientName
mfMessageFormat
Message format description. mfMessageFormat is a null-terminated character string containing the format description of the message. RTR uses this description to convert the contents of the message appropriately when processing the message on different hardware platforms. If no parameter is specified, the default is no special formatting.
Description
This member function should be called when the application wants to send an application-defined event to the server. Formerly, application-defined events are only delivered to the clients or servers that have subscribed for them and these are not related to any transaction. Only reply messages go to the client that started the transaction. Simply calling this function does not deliver the event to the client, unless it has subscribed for it. With the C++ API, you "subscribe" by overriding the event-handler methods. The events are only received if they are overridden.
Example
sStatus = SendApplicationEvent(pOrder);
print_status_on_failure(sStatus);
RTRClientTransactionController::SendApplicationMessage();
Prototype
virtual rtr_status_t SendApplicationMessage(RTRApplicationMessage
*pRTRApplicationMessage,
bool bReadonly = false,
bool bReturnToSender = false,
rtr_const_msgfmt_t mfMessageFormat =
RTR_NO_MSGFMT);
Return Value
rtr_status_t
Interpret value for the success or failure of this call.
|
Status |
Message |
|
RTR_STS_INSVIRMEM |
Insufficient virtual memory. |
|
RTR_STS_INVAPPMSGPTARG |
Invalid application message pointer argument. |
|
RTR_STS_INVMSGFMTPTRARG |
The message format string argument is invalid. |
|
RTR_STS_INVRECPNAMPTARG |
The recipient name argument is invalid. |
|
RTR_STS_NOMESSAGE |
The data object does not contain a message. |
|
RTR_STS_NOSEND |
Attempting to send an application message at this point is not allowed. |
|
RTR_STS_OK |
Normal successful completion. |
Parameters
pRTRApplicationMessage
Pointer to an RTRApplicationMessage object which contains application data to be sent to the server.
mfMessageFormat
Message format description. mfMessageFormat is a null-terminated character string containing the format description of the message. RTR uses this description to convert the contents of the message appropriately when processing the message on different hardware platforms. If no parameter is specified, the default is no special formatting.
bReadonly
Set this Boolean to true to indicate to RTR that this message does not perform writes that would need to be shadowed.
bReturnToSender
Set this Boolean to true to indicate to RTR that, if the message is not delivered to the server, it should return to this transaction controller a message indicating that.
Description
This member function should be called when the application wants to send application data to the server. The RTRData object contains the data to be sent.
For more information see:
RTRData
Example
// Send this Book Order object to a server capable of processing it.
cout << "SendApplicationMessage..." << endl;
sStatus = SendApplicationMessage(pOrder);
print_status_on_failure(sStatus);
RTRClientTransactionController::StartTransaction();
Prototype
virtual rtr_status_t StartTransaction(rtr_timout_t timeout = RTR_NO_TIMOUTMS);
Return Value
rtr_status_t
Interpret value for the success or failure of this call.
|
Status |
Message |
|
RTR_STS_CONNECTIONLOST |
An RTR connection has been lost. |
|
RTR_STS_FACNOTREG |
Facility is not registered. |
|
RTR_STS_INVTIMOUTMS |
Invalid timeout argument. |
|
RTR_STS_NOMESSAGE |
The data object does not contain a message. |
|
RTR_STS_NOSTARTTXN |
A client transaction is already active. |
|
RTR_STS_OK |
Normal successful completion. |
|
RTR_STS_TIMOUT |
Timeout time expired. |
Parameters
timeout
Transaction timeout. This value is specified in milliseconds. If the timeout time expires, RTR aborts the transaction and returns status RTR_STS_TIMOUT. If no timeout is required, specify RTR_NO_TIMOUTMS.
Description
Explicitly start a transaction from a client transaction controller. This method is mandatory.
The StartTransaction method is used to start a transaction explicitly. An explicit transaction start is only necessary if either:
Transactions are implicitly started when a message is sent on a currently inactive transaction controller. Implicitly started transactions have no timeout and are not joined to other RTR transactions.
Example
abc_status sStatus;
cout << "StartTransaction..." << endl;
sStatus = StartTransaction();
print_status_on_failure(sStatus);
RTRClientTransactionProperties
This class holds the properties of its associated RTRServerTransaction object.
RTRClientTransactionProperties Class Members
Construction
|
Method |
Description |
|
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();
{
}
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.
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. |
|
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. |
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();
{
}
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 parameter address specified on last call. |
|
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 );
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();
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 );
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 |
Invalid parameter address specified on last call. |
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);
RTRApplicatio
nEvent::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 );
RTRApplicationMessage Class Members
Construction
|
Method |
Description |
|
RTRApplicationMessage() |
Default constructor |
|
~RTRApplicationMessage () |
Default destructor |
Operations
|
Method |
Description |
|
Dispatch() |
Basic method. |
|
Retrieve the message associated with the data in this object. |
|
|
Retrieve the actual length of the message associated with the data in this object. |
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;
}
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();
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();
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_INSVIRMEM |
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 RTRApplicationEvent();
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_INSVIRMEM |
Insufficient virtual memory. |
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 applications 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;}
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_INSVIRMEM |
Insufficient virtual memory. |
Parameters
pRTREvent
Pointer to an RTREvent object that describes the message being processed.
Description
Create an RTREvent data object if the transaction controller determines that Receive call points to a message of type RTREvent.
Example
CreateRTREvent(*&pRTREvent)
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_INSVIRMEM |
Insufficient virtual memory. |
Parameters
pRTRMessage
Pointer to an RTRMessage object that describes the message 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 RTRMessage();
RTRData is the abstract base class for all data classes.
Construction
|
Method |
Description |
|
RTRData() |
Default constructor |
|
RTRData() |
Default destructor |
Operations
|
Method |
Description |
|
Dispatch() |
Basic method. |
|
Return the message buffer length. |
|
|
Return the logical buffer length. |
|
|
Determine if this object contains application-generated data. |
|
|
Determine if this object contains application-generated message. |
|
|
IsEvent() |
Determine if this object contains an RTR or application-generated event. |
|
Determine if this object contains an RTR or application-generated message. |
|
|
Determine if this object contains RTR-generated data. |
|
|
Determine if this object contains RTR-generated message. |
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.
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 ();
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();
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())
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())
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);
}
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();
}
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())
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();
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 deallocation of memory for the call. By using this form of the constructor, the application requests that RTR allocate enough memory to receive the data.
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. |
|
Retrieve the actual length of the data associated with this RTREvent object. |
|
|
GetEventNumber( rtr_evtnum_t ) |
Retreive the RTR event associated with the data in this RTREvent object. |
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();
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 |
Invalid parameter address specified on last call. |
|
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);
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();
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);
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. |
|
Retrieve the reason associated with the acceptance or rejection of the transaction. |
|
|
Retrieve the secondary status associated with the acceptance or rejection of the transaction. |
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();
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);
RTRMessage::GetReason();
Prototype
rtr_reason_t GetReason();
Return Value
rtr_reason_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 acceptance 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;
};
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 acceptance 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;
};
The RTRStream class derives from RTRData and extends the RTRData class by allowing RTR applications to issue multiple read and write requests to the buffer (managed by RTRData) without needing to maintain Pointer to the end of the buffer.
An RTRStream object automatically handles the details of maintaining the offset within the buffer when the application wants to read and write multiple times to a buffer.
When reading from and writing to a stream, a copy of the data is performed.
RTRStream Class Members
Construction
|
Method |
Description |
|
Default constructor |
|
|
~RTRStream |
Default destructor |
Operations
|
Method |
Description |
|
WriteToStream(rtr _msgbuf_t, rtr_msglen_t); |
Copy data to the end of the buffer managed by RTRData. |
|
WriteToStream(const char); |
Copy string to the end of the buffer managed by RTRData. |
|
WriteToStream(rtr_sgn_32_t); |
Copy the signed integer to the end of the buffer managed by RTRData. |
|
WriteToStream(rtr_uns_32_t); |
Copy the unsigned integer to the end of the buffer managed by RTRData. |
|
ReadFromStream(rtr _msgbuf_t, rtr_msglen_t, rtr_msglen_t); |
Copy the data from the buffer managed by RTRData to the buffer specified. |
|
ReadFromStream(rtr_sgn_32_t); |
Copy the signed integer from the buffer managed by RTRData to uiNumber. |
|
ReadFromStream(char, size_t); |
Copy the data from the buffer managed by RTRData to pString. |
|
ReadFromStream(rtr_uns_32_t); |
Copy the unsigned integer from the buffer managed by RTRData to uiNumber. |
Operators
|
Operator |
Description |
|
RTRStream& operator>> (char) |
ReadFromStream operator |
|
RTRStream& operator>> (rtr_sgn_32_t) |
ReadFromStream operator |
|
RTRStream& operator>> (rtr_uns_32_t) |
ReadFromStream operator |
|
RTRStream& operator<< (const char) |
WriteToStream operator |
|
RTRStream& operator<< (rtr_sgn_32_t) |
WriteToStream operator |
|
RTRStream& operator<< (rtr_uns_32_t) |
WriteToStream operator |
RTRStream::operator>>
Prototype
RTRStream& operator>> (char *pString)
{
ReadFromStream(pString);
return *this;
}
RTRStream& operator>> (rtr_sgn_32_t &iNumber)
{
ReadFromStream(iNumber);
return *this;
}
RTRStream& operator>> (rtr_uns_32_t &uiNumber)
{
ReadFromStream(uiNumber);
return *this;
}
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 |
Invalid parameter address specified on last call. |
Parameters
pString
Pointer to a character string.
iNumber
A signed integer.
uiNumber
An unsigned integer.
Description
>> denotes the ReadFromStream operators. These member functions extract data from a buffer by calling ReadFromStream to read the data and return *this. The three types of stream data are string, signed, and unsigned.
Example
// Populate this object with the data
*this >> m_uiPrice >> m_uiISBN >> m_szTitle >> m_szAuthor;
// The 1 line call above is equivalent to the 4 lines below.
// ReadFromStream(m_uiISBN);
// ReadFromStream(m_uiPrice);
// ReadFromStream(m_szTitle);
// ReadFromStream(m_szAuthor);
RTRStream::operator<<
Prototype
RTRStream& operator<< (char *pString)
{
WriteToStream(pString);
return *this;
}
RTRStream& operator<< (rtr_sgn_32_t &iNumber)
{
WriteToStream(iNumber);
return *this;
}
RTRStream& operator<< (rtr_uns_32_t &uiNumber)
{
WriteToStream(uiNumber);
return *this;
}
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_INVSTRINGPTRARG |
The string pointer argument is invalid - string too long. |
Parameters
pString
Pointer to a character string.
iNumber
A signed integer.
uiNumber
An unsigned integer.
Description
<< denotes the WriteToStream operators. These member functions write data to a buffer by calling WriteToStream to write the data and return *this. The three types of stream data are string, signed, and unsigned.
Example
// Save the type of object we are. This is used by the class factory
// on the server side to determine which type of class to allocate.
*this << ABC_BOOK;
*this << m_uiPrice << m_uiISBN << m_szTitle << m_szAuthor;
// The 1 line call above is equivalent to the 4 lines below. We
// can use the << and >> operators because we know that the data
// which we store is not > the current RTR maximum = 65535 bytes.
// WriteToStream(m_uiISBN);
// WriteToStream(m_uiPrice);
// WriteToStream(m_szTitle);
// WriteToStream(m_szAuthor);
RTRStream::ReadFromStream();
Prototype
rtr_status_t ReadFromStream(rtr_msgbuf_t pvBuffer,
rtr_msglen_t &uiBufferSize
rtr_msglen_t &uiSizeCopied);
rtr_status_t ReadFromStream(char *pString, size_t uiStringSize);
rtr_status_t ReadFromStream(rtr_sgn_32_t &iNumber);
rtr_status_t ReadFromStream(rtr_uns_32_t &uiNumber);
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_APPBUFFTOOSMALL |
The application buffer is too small. |
|
RTR_STS_ENDOFSTREAM |
The end-of-stream has been reached. |
Parameters
uiBufferSize
An unsigned integer for length of the buffer.
pvBuffer
A void pointer to a buffer.
uiNumber
An unsigned integer.
pString
Pointer to a character string.
iNumber
A signed integer
Description
Reads the first instance of a data type from a buffer as specified in the ReadFromStream methods. Note that the string buffer is assumed to be large enough (RTR_MAX_MSGLEN).
Example
RTRStream::ReadFromStream(pString);
RTRStream::RTRStream();
Prototype
RTRStream();
Return Value
None
Parameters
None
Description
Constructor method for the RTRStream class.
Example
RTRStream::RTRStream();
RTRStream::WriteToStream();
Prototype
rtr_status_t WriteToStream(rtr_const_msgbuf_t pvBuffer, rtr_msglen_t uiBufferLength);
rtr_status_t WriteToStream(const char *pString);
rtr_status_t WriteToStream(rtr_sgn_32_t iNumber);
rtr_status_t WriteToStream(rtr_uns_32_t uiNumber);
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_ENDOFSTREAM |
The end-of-stream has been reached. |
Parameters
uiBufferLength
An unsigned integer for length of the buffer.
pvBuffer
A void pointer to a buffer.
uiNumber
An unsigned integer.
iNumber
A signed integer.
pString
Pointer to a character string.
Description
Write to a data buffer, specifying the data with either buffer and buffer length, as unsigned integer, or string.
Example
RTRStream::WriteToStream(uiNumber);