Previous | Contents | Index |
virtual rtr_status_t AcceptTransaction(rtr_reason_t rtrReasonCode = RTR_NO_REASON);
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.
rtrReasonCode
Optional reason for accepting the transaction. This reason is OR ed 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().
Call this member function to accept the transaction currently being processed by this object.
// 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);
virtual rtr_status_t Receive (RTRData **pRTRData, rtr_timout_t tTimeout = RTR_NO_TIMOUTMS);
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. |
pRTRData
A pointer passed by reference, which will receive an object, derived from RTRData. This object can be any of the following:
- RTRMessage
- RTREvent
- RTRApplictionMessage
- RTRApplicationEvent
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 processing models in the Processing Models section of this manual and the Reliable Transaction Router Application Design Guide section on Message Reception Styles.
tTimeout
An optional receive timeout value in milliseconds. If the timeout expires, the call completes with status RTR_STS_TIMOUT.
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
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; }
virtual rtr_status_t RegisterClassFactory ( RTRClassFactory *pFactory);
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 |
pFactory
Pointer to an RTRClassFactory object that is called, if registered, from the RTR framework when processing all Receive methods in your application.
Registering a class factory is not a requirement. An application would register a class factory only when they wish to customize the object that is being allocated.
sStatus = RegisterClassFactory(*pFactory); print_status_on_failure(sStatus);
virtual rtr_status_t RegisterFacility (rtr_const_facnam_t pszFacilityName, rtr_const_rcpspc_t szRecipientName = "*", rtr_const_access_t pszAccess = RTR_NO_ACCESS);
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. |
pszFacilityName
Pointer to a null-terminated facility name.szRecipientName
Name of the recipient. This null-terminated string contains the name of the recipient. This is an optional parameter.Wildcards ("*" for any sequence of characters, and "%" for any one character) can be used in this string to address more than one recipient.
Note that szRecipientName is case sensitive.
pszAccess
Pointer to a null-terminated string containing the access parameter. The default is RTR_NO_ACCESS.
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.
// Register the facility with RTR. sStatus = RegisterFacility(ABCFacility); print_status_on_failure(sStatus); if(RTR_STS_OK == sStatus) { m_bRegistered = true; }
virtual rtr_status_t RegisterHandlers (RTRClientMessageHandler *pMessageHandler, RTRClientEventHandler *pEventHandler);
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 |
pMessageHandler
Pointer to an RTRClientMessageHandler object that processes messages received.pEventHandler
Pointer to an RTRClientEventHandler object that processes events received.
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 applications process.Specify pMessageHandler and/or pEventHandler in order for your application to make use of the RTR frameworks predefined handlers.
For more information on handlers see:
- RTRData::Dispatch
- RTRClientMessageHandler
// ABC Handlers // Register the both handlers with RTR sStatus = RegisterHandlers(&m_rtrHandlers,&m_rtrHandlers); print_status_on_failure(sStatus);
virtual rtr_status_t RejectTransaction(const rtr_reason_t rtrReasonCode = RTR_NO_REASON);
rtr_status_t Interpret value for the success or failure of this call.
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().
Call this member function to reject the transaction currently being processed by this object.
pController->RejectTransaction();
RTRClientTransactionController(); virtual ~RTRClientTransactionController();
None
None
Call this constructor to create an RTRClientTransactionController object.
ABCOrderTaker::ABCOrderTaker():m_bRegistered(false) { }
virtual rtr_status_t SendApplicationEvent(RTRApplicationEvent * pRTRApplicationEvent, rtr_const_rcpspc_t szRecipientName = "*", rtr_const_msgfmt_t mfMessageFormat = RTR_NO_MSGFMT);
rtr_status_t Interpret value for the success or failure of this call.
RTRApplicationEvent
Pointer to an RTRApplicationEvent object which contains application data to be sent to the server.szRecipientName
Name of the recipient. This null-terminated character string contains the name of the recipient. This is an optional parameter.Wildcards ( "*" for any sequence of characters, and "%" for any one character) can be used in this string to address more than one recipient
Note that szRecipientName is case sensitive.
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.
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.
sStatus = SendApplicationEvent(pOrder); print_status_on_failure(sStatus);
virtual rtr_status_t SendApplicationMessage(RTRApplicationMessage *pRTRApplicationMessage, bool bReadonly = false, bool bReturnToSender = false, rtr_const_msgfmt_t mfMessageFormat = RTR_NO_MSGFMT);
rtr_status_t Interpret value for the success or failure of this call.
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 and 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.
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
// Send this Book Order object to a server capable of processing it. cout << "SendApplicationMessage..." << endl; sStatus = SendApplicationMessage(pOrder); print_status_on_failure(sStatus);
virtual rtr_status_t StartTransaction(rtr_timout_t timeout = RTR_NO_TIMOUTMS);
rtr_status_t Interpret value for the success or failure of this call.
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.
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 a join to an existing transaction is to be done
- or a transaction timeout is to be specified
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.
abc_status sStatus; cout << "StartTransaction..." << endl; sStatus = StartTransaction(); print_status_on_failure(sStatus);
Previous | Next | Contents | Index |