# hp Reliable Transaction Router
C++ Foundation Classes

Previous | Contents | Index

# OnFacilityReady()

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

# OnRouterGainedLinkToFrontend()

## RTRServerEventHandler::OnRouterGainedLinkToFrontend();

## Prototype

>     virtual rtr_status_t OnRouterGainedLinkToFrontend(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::OnRouterGainedLinkToFrontend( RTREvent *pEvent,
>     RTRServerTransactionController *pController )
>     {
>     }

# OnRouterLostLinkToFrontend()

## RTRServerEventHandler::OnRouterLostLinkToFrontend();

## Prototype

>     virtual rtr_status_t OnRouterLostLinkToFrontend(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_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::OnRouterLostLinkToFrontend(
>                                 RTREvent *pEvent,
>                                 RTRServerTransactionController *pController )
>     {
>     }

# OnServerGainedShadow()

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

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

# OnServerIsPrimary()

## 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 the partition name on which the message or event was received.

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

# OnServerIsSecondary()

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

# OnServerIsStandby()

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

# OnServerLostShadow()

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

# OnServerRecoveryComplete()

## 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::RTRServerEventHandler();

## Prototype

>         RTRServerEventHandler();
>         virtual ~RTRServerEventHandler();

## Return Value

> None

## Parameters

> None

## Description

> Call this constructor to create and 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;
>     }

# 3.3 RTRServerMessageHandler

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
--- | ---
RTRServerMessageHandler() | Constructor
~RTRServerMessageHandler() | Destructor

Method | Description
--- | ---
OnAccepted(RTRMessage, RTRServerTransactionController) | The specified transaction has been accepted by all participants.
OnApplicationMessage RTRApplicationMessage, RTRServerTransactionController | The client has sent the server this message.
OnInitialize(RTRApplicationMessage, RTRServerTransactionController) | A new transaction is being processed.
OnPrepareTransaction(RTRMessage, RTRServerTransactionController) | The specified transaction is complete (that is, all messages from the client have been received).
OnRejected(RTRMessage, RTRServerTransactionController) | The specified transaction has been rejected by a participant.
OnUncertainTransaction (RTRApplicationMessage, RTRServerTransactionController) | RTR is replaying a transaction which may or may not have been completed.

# OnAccepted()

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

# OnApplicationMessage()

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

# OnInitialize()

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

# OnPrepareTransaction()

## 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 which is being processed.

> ### pController

> Pointer to the transaction controller within which this event 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 that the handler dismisses the notification. Note that if 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;
>     }

Previous | Next | Contents | Index