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

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:

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:

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:

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:

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:

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

OnFacilityReady()

RTRClientEventHandler::OnFacilityReady();

Prototype


virtual rtr_status_t OnFacilityReady(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 has become operational.

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

Example


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

OnFrontendGainedLinkToRouter()

RTRClientEventHandler::OnFrontendGainedLinkToRouter();

Prototype


virtual rtr_status_t OnFrontendGainedLinktToRouter(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 a frontend link to the current router has been established.

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

Example


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

Previous Next Contents Index