hp Reliable Transaction Router
C++ Foundation Classes


Previous Contents Index


AcceptTransaction()


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

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


Receive()


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 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.

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; 
} 


RegisterClassFactory()


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 wish to customize the object that is being allocated.

Example


    sStatus = RegisterClassFactory(*pFactory); 
    print_status_on_failure(sStatus); 


RegisterFacility()


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

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.

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; 
      } 


RegisterHandlers()


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 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:


Example


// ABC Handlers 
// Register the both handlers with RTR 
sStatus = RegisterHandlers(&m_rtrHandlers,&m_rtrHandlers); 
print_status_on_failure(sStatus); 


RejectTransaction()


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) 
{ 
 
} 


SendApplicationEvent()


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

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.

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


SendApplicationMessage()


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 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.

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


StartTransaction()


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:

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


Previous Next Contents Index