# 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:
> - RTRMessage
> - RTREvent
> - RTRApplicationMessage
> - 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 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