# hp Reliable Transaction Router
C++ Foundation Classes

Previous | Contents | Index

# GetFacilityName()

## RTRServerTransactionProperties::GetFacilityName();

## Prototype

>     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_DATANOTAVAILABL | A required property was not available.
> 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

> This method gets the facility name associated with the transaction and described by the RTRServerTransactionProperties object.

## Example

>     pTransaction->GetFacility(pszFacilityName);

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

# GetTID()

## RTRServerTransactionProperties::GetTID();

## Prototype

>     rtr_status_t GetTID(rtr_tid_t &rtrTID);

## Return Value

> rtr_status_t Interpret value for the success or failure of this call. RTR_STS_OK is the normal successful completion. Returns RTR_STS_NOTID on failure.

## Parameters

> ### rtrTID

> An RTR transaction identifier.

## Description

> This method copies the transaction identifier (TID) of the transaction described by the RTRServerTransactionProperties object for the current transaction.

## Example

>     rtr_tid_t tid = pController->GetTID(&rtrTID);

# GetTransactionState()

## RTRServerTransactionProperties:: GetTransactionState ();

## Prototype

>     rtr_status_t GetTransactionState (rtr_tx_jnl_state_t &pstCurrentTxnState);

## Return Value

> rtr_status_t Interpret value for the success or failure of this call.

> Status | Message
> --- | ---
> RTR_STS_INVTXNSTATPTARG | Invalid transaction state pointer argument.
> RTR_STS_DATANOTAVAILABL | A required property was not available.
> RTR_STS_OK | Normal successful completion

## Parameters

> ### pstCurrentTxnState

> Pointer to the transaction state of type `rtr_tx_jnl_state_t` .

## Description

> Get the transaction state for the current transaction.

## Example

>     rtr_tx_jnl_state_t txnState;
>     rtr_status_t sStatus = GetTransactionState(txnState);
>     if ( rtr_tx_jnl_voted == txnState)
>     {

>     }

# RTRServerTransactionProperties()

## RTRServerTransactionProperties::RTRServerTransactionProperties();

## Prototype

>     RTRServerTransactionProperties(const rtr_tid_t &tid);
>     virtual ~RTRServerTransactionProperties();

## Return Value

> None

## Parameters

> ### tid

> A transaction identifier value of type `rtr_tid_t` .

## Description

> Call this constructor to create an RTRServerTransactionProperties object associated with the specified tid.

## Example

>     RTRServerTransactionProperties::RTRServerTransactionProperties
>     {
>     }

# SetStateToAbort()

## RTRServerTransactionProperties::SetStateToAbort();

## Prototype

>     rtr_status_t SetStateToAbort();

>     rtr_status_t SetStateToAbort(rtr_tx_jnl_state_t stCurrentTxnState);

## Return Value

> rtr_status_t Interpret value for the success or failure of this call. RTR_STS_OK is the normal successful completion.

## Parameters

> ### stCurrentTxnState

> A transaction state of type `rtr_tx_jnl_state_t` .

## Description

> This method is used to set the current server transaction state to abort.There are two forms:
> - For the form with no parameter, the current transaction state is internally tested. If it is currently valid to transition from that state to the abort state, the call succeeds.
> - For the form with the transaction state parameter, if it is valid to transition from that state to the abort state, the call succeeds.

## Example

>     rtr_status_t sStatus = SetStateToAbort(txnState);

# SetStateToCommit()

## RTRServerTransactionProperties::SetStateToCommit();

## Prototype

>     rtr_status_t SetStateToCommit();

>     rtr_status_t SetStateToCommit(rtr_tx_jnl_state_t stCurrentTxnState);

## Return Value

> rtr_status_t Interpret value for the success or failure of this call. RTR_STS_OK is the normal successful completion.

## Parameters

> ### stCurrentTxnState

> A transaction state of type `rtr_tx_jnl_state_t` .

## Description

> This method is used to set the current server transaction state to commit.There are two forms:
> - For the form with no parameter, the current transaction state is internally tested. If it is currently valid to transition from that state to the commit state, the call succeeds.
> - For the form with the transaction state parameter, if it is valid to transition from that state to the commit state, the call succeeds.

## Example

>     rtr_status_t sStatus = SetStateToCommit(txnState);

# SetStateToDone()

## RTRServerTransactionProperties::SetStateToDone();

## Prototype

>     rtr_status_t SetStateToDone();

>     rtr_status_t SetStateToDone(rtr_tx_jnl_state_t stCurrentTxnState);

## Return Value

> rtr_status_t Interpret value for the success or failure of this call. RTR_STS_OK is the normal successful completion.

## Parameters

> ### stCurrentTxnState

> A transaction state of type `rtr_tx_jnl_state_t` .

## Description

> This method is used to set the current server transaction state to done.There are two forms:
> - For the form with no parameter, the current transaction state is internally tested. If it is currently valid to transition from that state to the done state, the call succeeds.
> - For the form with the transaction state parameter, if it is valid to transition from that state to the done state, the call succeeds.

## Example

>     rtr_status_t sStatus = SetStateToDone(txnState);

# SetStateToException()

## RTRServerTransactionProperties::SetStateToException();

## Prototype

>     rtr_status_t SetStateToException();

>     rtr_status_t SetStateToException(rtr_tx_jnl_state_t stCurrentTxnState);

## Return Value

> rtr_status_t Interpret value for the success or failure of this call. RTR_STS_OK is the normal successful completion.

## Parameters

> ### stCurrentTxnState

> A transaction state of type `rtr_tx_jnl_state_t` .

## Description

> This method is used to set the current server transaction state to exception.There are two forms:
> - For the form with no parameter, the current transaction state is internally tested. If it is currently valid to transition from that state to the exception state, the call succeeds.
> - For the form with the transaction state parameter, if it is valid to transition from that state to the exception state, the call succeeds.

## Example

>     rtr_status_t sStatus = SetStateToException(txnState);

# TransactionIsOriginal()

## RTRServerTransactionProperties::TransactionIsOriginal();

## Prototype

>     bool TransactionIsOriginal();

## Return Value

> bool A true or false return value.

## Parameters

> None

## Description

> This method tests if the transaction is an original transaction. Note that this does not necessarily mean that the transaction has never been presented before.

## Example

>     RTRServerTransactionProperties *pstProperties =
>                                   pController->GetProperties();
>     bool bOriginal  = pTransactionController ->TransactionIsOriginal();

# TransactionIsRecovery()

## RTRServerTransactionProperties::TransactionIsRecovery();

## Prototype

>     bool TransactionIsRecovery();

## Return Value

> bool A true or false return value.

## Parameters

> None

## Description

> This method tests if the transaction is a recovered transaction. A recovered transaction is one where the transaction was held in the RTR journal during a crash of a node, and has been restored and can be committed in the database.

## Example

>     rtr_status_t sStatus = TransactionIsRecovery();

# TransactionIsReplay()

## RTRServerTransactionProperties::TransactionIsReplay();

## Prototype

>     bool TransactionIsReplay();

## Return Value

> bool A true or false return value.

## Parameters

> None

## Description

> This method tests if the transaction is a replayed transaction.

## Example

>     rtr_status_t sStatus = TransactionIsReplay();

# 3.6 Client Classes

The client classes of the RTR API are:

- RTRClientEventHandler
- RTRClientMessageHandler
- RTRClientTransactionController
- RTRClientTransactionProperties

These classes are described in this section in alphabetical order.

# 3.7 RTRClientEventHandler

This class defines event handlers for all potential events that an RTR client application can receive. Each handler has a default behavior. Applications should override those member functions for which they intend to perform application-specific processing.

Applications can extend this class by deriving from it and adding their own application-level event handlers.

For further information see RTRData::Dispatch().

# RTRClientEventHandler Class Members

Construction

Method | Description
--- | ---
RTRClientEventHandler() | Constructor
~RTRClientEventHandler() | Destructor

Operations

Method | Description
--- | ---
OnApplicationEvent(RTRApplicationEvent, RTRClientTransactionController) | There is an event generated by the application, for the client.
OnFacilityDead(RTREvent, RTRClientTransactionController) | Default handler for the event where the facility is no longer operational.
OnFacilityReady(RTREvent, RTRClientTransactionController) | Default handler for the event where the facility has become operational.
OnFrontendGainedLinkToRouter (RTREvent, RTRClientTransactionController) | Default handler for the event where a frontend link to the current router has been established.
OnFrontendLostLinkToRouter (RTREvent, RTRClientTransactionController) | Default handler for the event where the frontend link to the current router has been lost.
OnKeyRangeNoLongerAvailable (RTREvent, RTRClientTransactionController) | Default handler for the event where no more servers remain for a particular routing key range.
OnNewKeyRangeAvailable(RTREvent, RTRClientTransactionController) | Default handler for the event where one or more servers for a new key range have become available.
OnRouterGainedLinkToBackend (RTREvent, RTRClientTransactionController) | Default handler for the event where a current router established a link to a backend.
OnRouterLostLinkToBackend (RTREvent, RTRClientTransactionController) | Default handler for the event where the current router lost a link to a backend.

# OnApplicationEvent()

## RTRClientEventHandler::OnApplicationEvent();

## Prototype

>     virtual rtr_status_t OnApplicationEvent(RTRApplicationEvent
>                                                  *pRTRApplicationEvent,
>                            RTRClientTransactionController *pController)
>     {
>     return RTR_STS_OK;
>     }

## Parameters

> ### pRTRApplicationEvent

> Pointer to an RTRApplicationEvent object that describes the message which is being processed.

> ### pController

> Pointer to the transaction controller within which this event was received.

## Description

> The RTRData parameter contains an application event sent to it by an RTR server.

> The default behavior is the handler dismisses the notification.

## Example

>     MyCLIEventHandler::OnApplicationEvent( RTRApplicationEvent
>                                                  *pRTRApplicationEvent,
>                                           RTRClientTransactionController
>                                                    *pCTC )
>     {
>             cout << "An application event... " <<endl;
>             return RTR_STS_OK;
>     }

# OnFacilityDead()

## RTRClientEventHandler::OnFacilityDead();

## Prototype

>     virtual rtr_status_t OnFacilityDead(RTREvent *pRTREvent,
>                                   RTRClientTransactionController *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 is no longer operational.

> The client application is receiving an RTR-generated event. RTREvent contains the application-defined number RTR_EVTNUM_FACDEAD (97) and any associated data.

## Example

>     MyCLIEventHandler::OnFacilityDead( RTREvent *pRTREvent,
>      RTRClientTransactionController *pCTC )
>     {
>      return RTR_STS_OK;
>     }

Previous | Next | Contents | Index