hp Reliable Transaction Router
C++ Foundation Classes
Previous Contents Index

OnRejected()

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

OnUncertainTransaction()

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

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

3.4 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
RTRServerTransactionController Constructor
~RTRServerTransactionController Destructor

Operations
Method Description
RegisterClassFactory
(RTRClassFactory) 		Register a class factory for RTR to call when creating RTRData-derived objects.
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
AcknowledgeTransactionOutcome() 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.
UnRegisterPartition(rtr_const_parnam_t) Remove a partition from the list of partitions for which this transaction controller processes requests.
ForceTransactionRetry() 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.
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 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.
GetProperties() Get properties of the current transaction.

AcceptTransaction()

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

ForceTransactionRetry()

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 may 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 command to the RTR command line interface.

Example


pController-> ForceTransactionRetry();

GetFacilityName()

RTRServerTransactionController::GetFacilityName();

Prototype


virtual rtr_status_t GetFacilityName (rtr_facnam_t pszFacilityName, 
                                      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 argument pointer.
RTR_STS_OK Normal successful completion.

Parameters

pszFacilityName

A null-terminated pointer to a facility name. Memory is allocated by the function call.

uiFacilityNameSize

Specifies size of buffer passed by the facility name. If the size of the facility name intended for the pszFacilityName character string is greater than the size in uiFacilityNameSize , the error code RTR_STS_APPBUFFTOOSMALL is returned and the facility name is not copied into the character string.

Description

Obtain the name of the facility in which the current transaction is executing.

Memory is allocated by the caller and if uiFacilityNameSize is not big enough, an error message is returned.

Example


pController->GetFacilityName(pszFacilityName, uiFacilityNameSize);

GetPartitionName()

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 argument pointer.
RTR_STS_OK Normal successful completion
RTR_STS_TXNOTACT Transaction not active.

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.

GetProperties()

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

Receive()

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 message reception 
styles in Section 1.4. Addtional information can be found in the 
Reliable Transaction Router 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; 
 
        } 
















  

    Previous
    Next
    Contents
    Index