# hp Reliable Transaction Router
C++ Foundation Classes

Previous | Contents | Index

# RegisterClassFactory()

## RTRServerTransactionController::RegisterClassFactory();

## Prototype

>     virtual rtr_status_t RegisterClassFactory( RTRClassFactory *pFactory);

## Return Value

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

> Status | Message
> --- | ---
> RTR_STS_INVFACTORYPTARG | The factory argument pointer is invalid.
> RTR_STS_OK | Normal successful completion

## Parameters

> ### pFactory

> Pointer to an RTRClassFactory object that is called, if registered, from the RTR framework when processing all Receive calls in your application.

## Description

> A class factory returns an object for RTR to use (write data to) when the method RTRServerTransactionController::Receive is called. The application can register their own class factory and override the functions to return their own objects derived from the RTR data classes. The four RTR data classes are RTRApplicationMessage, RTRApplicationEvent, RTRMessage, and RTREvent.

> Registering a class factory is not a requirement. An application would register a class factory only when they wish to customize the object that is being allocated.

## Example

>     sStatus = RegisterClassFactory(&m_ClassFactory);
>     print_status_on_failure(sStatus);

# RegisterFacility()

## RTRServerTransactionController::RegisterFacility();

## Prototype

>     virtual rtr_status_t RegisterFacility (rtr_const_facnam_t pszFacilityName);

## Return Value

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

> Status | Message
> --- | ---
> RTR_STS_INVALIDFACILITY | The specified facility does not exist.
> RTR_STS_INVFACNAMEARG | The facility name argument is invalid.
> RTR_STS_OK | Normal successful completion
> RTR_STS_RTRNOTRUNNING | RTR is not running.

## Parameters

> ### pszFacilityName

> A null-terminated pointer to a facility name. Memory is allocated by the function call. If the size of the parameter is not big enough, the return error message RTR_STS_APPBUFFTOOSMALL is returned.

## Description

> Call the RegisterFacility() member function to register an existing RTR facility for your application. By registering a facility, your application informs RTR of the facility for which your application can process transactions.

## Example

>     // Register the facility with the transaction controller.
>        sStatus = RegisterFacility(ABCFacility);
>        print_status_on_failure(sStatus);

# RegisterHandlers()

## RTRServerTransactionController::RegisterHandlers();

## Prototype

>     virtual rtr_status_t RegisterHandlers (
>                                  RTRServerMessageHandler *pMessageHandler,
>                                  RTRServerEventHandler *pEventHandler);

## Return Value

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

> Status | Message
> --- | ---
> RTR_STS_INVEVNTHNDPTARG | The event handler pointer argument is invalid.
> RTR_STS_INVMSGHNDLPTARG | The message handler pointer argument is invalid.
> RTR_STS_OK | Normal successful completion

## Parameters

> ### pMessageHandler

> Pointer to an RTRServerMessageHandler object that will process all server messages in your application.

> ### pEventHandler

> Pointer to an RTRServerMessageHandler object that will process all server events in your application.

## Description

> Call the RegisterHandlers member function to register RTR message and event handlers for your application. By registering the handlers, your application informs RTR of the different configurations for which your application can process transactions. Your application can only use one partition at a time. The message and event handlers are called by the RTRData::Dispatch method.

> Specify pMessageHandler and/or pEventHandler if your application wishes to make use of the RTR frameworks predefined handlers.

> For more information on handlers see:

> - RTRApplicationMessage::Dispatch
> - RTRApplicationEvent::Dispatch
> - RTRMessage::Dispatch
> - RTREvent::Dispatch
> - RTRServerMessageHandler
> - RTRServerEventHandler

## Example

>     // Register the message and event handlers with the transaction controller.
>        sStatus = pTransaction->RegisterHandlers(
>     pAppClassDerivedFromRTRMessageHandler,
>     pAppClassDerivedFromRTREventHandler
>     );
>     assert(RTR_STS_OK == sStatus);

# RegisterPartition()

## RTRServerTransactionController::RegisterPartition();

## Prototype

>     virtual rtr_status_t RegisterPartition(rtr_const_parnam_t pszPartitionName,
>             rtr_const_rcpnam_t szRecipientName = RTR_NO_RCPNAM,
>             rtr_const_access_t pszAccess = RTR_NO_ACCESS);

## Return Value

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

> Status | Message
> --- | ---
> RTR_STS_DUPLPARTITION | Attempting to insert a duplicate partition.
> RTR_STS_FACNOTREG | Facility is not registered.
> RTR_STS_INVACCSTRPTRARG | The access string argument is invalid.
> RTR_STS_INVPARTNAMEARG | The partition name argument is invalid
> RTR_STS_INVRECPNAMPTARG | The recipient name argument is invalid.
> RTR_STS_OK | Normal successful completion
> RTR_STS_RTRNOTRUNNING | RTR is not running.

## Parameters

> ### pszPartitionName

> A null-terminated pointer to a partition name.

> ### szRecipientName

> Name of the recipient. This null-terminated string contains the name of the recipient. This is an optional parameter.

> Wildcards ("*" for any sequence of characters, and "%" for any one character) can be used in this string to address more than one recipient.

> Note that szRecipientName is case sensitive.

> ### pszAccess

> Pointer to a null-terminated string containing the access parameter. The default value is RTR_NO_ACCESS.

## Description

> Call the RegisterPartition member function to register an RTR partition for your application. By registering a partition, your application informs RTR of the different configurations for which your application can process transactions. Your application can only use one partition at a time.

> Note It is mandatory to register a partition that already exists in a registered facility. RegisterPartition may be called multiple times to register multiple partitions.

## Example

>     // Register the partition with the transaction controller.
>     sStatus = pTransaction->RegisterPartition( "MyPartition);
>     assert(RTR_STS_OK == sStatus);

# RejectTransaction()

## RTRServerTransactionController::RejectTransaction();

## Prototype

>     virtual rtr_status_t RejectTransaction(rtr_reason_t rtrReasonCode =
>                                            RTR_NO_REASON);

## 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_NOREJECT | Client or Server has already voted or there is no active transaction.
RTR_STS_OK | Normal successful completion.
RTR_STS_TXNOTACT | No transaction is currently active on this channel.

## Parameters

> ### rtrReasonCode

> Optional reason for rejecting the transaction. This reason is returned to the other participants in the transaction. The participants can retrieve this reason by calling RTRMessage::GetReason.

## Description

> Call this member function to reject the transaction currently being processed by this object.

## Example

>         sStatus = pController->RejectTransaction();

# RTRServerTransactionController()

## RTRServerTransactionController::RTRServerTransactionController();

## Prototype

>     RTRServerTransactionController();
>     virtual ~RTRServerTransactionController();

## Return Value

> None

## Parameters

> None

## Description

> Call this constructor to create an RTRServerTransactionController object.

## Example

>     ABCOrderProcessor::ABCOrderProcessor()
>     {
>     }

# SendApplicationEvent()

## RTRServerTransactionController::SendApplicationEvent();

## Prototype

>     virtual rtr_status_t SendApplicationEvent( RTRApplicationEvent
>                                             * pRTRApplicationEvent,
>                           rtr_const_rcpspc_t szRecipientName = "*",
>                rtr_const_msgfmt_t mfMessageFormat = RTR_NO_MSGFMT);

## Return Value

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

Status | Message
--- | ---
RTR_STS_INSVIRMEM | Insufficient virtual memory.
RTR_STS_INVAPPEVNTPTARG | Invalid application event pointer argument.
RTR_STS_INVMSGFMTPTRARG | The message format string argument is invalid.
RTR_STS_INVRECPNAMPTARG | The recipient name argument is invalid.
RTR_STS_NOEVENTDATA | There is no event data associated with the event.
RTR_STS_NOMESSAGE | The data object does not contain a message.
RTR_STS_OK | Normal successful completion.

## Parameters

> ### pRTRApplicationEvent

> Pointer to an RTRApplicationEvent object which contains application data to be sent to the client.

> ### szRecipientName

> Name of the recipient. This null-terminated character string contains the name of the recipient specified with the szRecipientName parameter on the RTRServerTransactionController::RegisterPartition method.

> Wildcards ("*" for any sequence of characters, and "%" for any one character) can be used in this string to address more than one recipient. szRecipientName is an optional parameter.

> Note that szRecipientName is case sensitive.

> ### mfMessageFormat

> Message format description. mfMessageFormat is a null-terminated character string containing the format description of the message. RTR uses this description to convert the contents of the message appropriately when processing the message on different hardware platforms. If no parameter is specified, the default is no special formatting.

## Description

> This member function should be called when the application wants to send an application-defined (broadcast) event to the client. Formerly, application- defined events are only delivered to the clients that have subscribed for them and these are not related to any transaction. Only reply messages go to the client that started the transaction. Simply calling this function will not deliver the event to the client, unless it has subscribed for it. With the C++ API, you "subscribe" by overriding the event handler methods. The events are only received if they are overridden.

## Example

>     sStatus = pTransaction->SendApplicationEvent(pEventA);
>     assert(RTR_STS_OK == sStatus);

# SendApplicationMessage()

## RTRServerTransactionController::SendApplicationMessage();

## Prototype

>     virtual rtr_status_t SendApplicationMessage(RTRApplicationMessage
>                                                 *pRTRApplicationMessage,
>                          rtr_const_msgfmt_t mfMessageFormat = RTR_NO_MSGFMT);

## Return Value

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

Status | Message
--- | ---
RTR_STS_INSVIRMEM | Insufficient virtual memory.
RTR_STS_INVAPPMSGPTARG | Invalid application message pointer argument.
RTR_STS_INVMSGFMTPTRARG | The message format string argument is invalid.
RTR_STS_NOMESSAGE | The data object does not contain a message.
RTR_STS_NOSEND | Attempting to send an application message at this point is not allowed.
RTR_STS_OK | Normal successful completion.

## Parameters

> ### pRTRApplicationMessage

> Pointer to an RTRApplicationMessage object which contains application data to be sent to the client.

> ### mfMessageFormat

> Message format description. mfMessageFormat is a null-terminated character string containing the format description of the message. RTR uses this description to convert the contents of the message appropriately when processing the message on different hardware platforms. If no parameter is specified, the default is no special formatting.

## Description

> This member function should be called when the application wants to send application data to the client which originally established the transaction. The RTRData object contains the data to be sent.

> For more information see:

> RTRData

## Example

>     // Send the Server a message
>     sStatus = pTransaction->SendApplicationMessage(pMessage1);
>     assert(RTR_STS_OK == sStatus);

# UnRegisterPartition()

## RTRServerTransactionController::UnRegisterPartition();

## Prototype

>     virtual rtr_status_t UnRegisterPartition(rtr_const_parnam_t
>     pszPartitionName);

## Return Value

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

> Status | Message
> --- | ---
> RTR_STS_INVPARTNAMEARG | The partition name argument is invalid
> RTR_STS_NOPARTITION | The partition name has not been previously registered.
> RTR_STS_OK | Normal successful completion

## Parameters

> ### pszPartitionName

> A null-terminated pointer to a partition name.

## Description

> Remove a partition from the list of partitions for which this transaction controller processes requests.

## Example

>     pController-> UnRegisterPartition();

# 3.5 RTRServerTransactionProperties

This class holds, makes available, and allows modification of the properties of its associated RTRServerTransactionController object. It provides attributes for a given transaction.

Typically, RTR C++ API applications obtain this object by calling GetProperties on the transaction controller. Other applications, including legacy applications, may create an instance of this object by calling the constructor with the TID of the transaction.

# RTRServerTransactionProperties Class Members

Construction

Method | Description
--- | ---
RTRServerTransactionProperties (const rtr_tid_t, rtr_parnam_t pszPartitionName) | Constructor
~RTRServerTransactionProperties() | Destructor

Get the Type of Transaction

Method | Description
--- | ---
TransactionIsOriginal() | Tests whether the transaction is an original transaction.
TransactionIsRecovery() | Tests whether the transaction is a recovered transaction.
TransactionIsReplay() | Tests whether the transaction is a replayed transaction.

Get Functions

Method | Description
--- | ---
GetFacilityName(rtr_facnam_t, const size_t) | Get the facility.
GetPartitionName(rtr_parnam_t, const size_t) | Get the partition name for the current transaction, if one exists.
GetTID(rtr_tid_t) | Get the TID (transaction ID).
GetTransactionState (rtr_tx_jnl_state_t) | Get the transaction state.

When setting the state of a transaction, the state transaction must be valid, or else the call will return an error. For each of the set state methods, there are two versions. The versions with no parameters attempt to transition the transaction to the requested state. The second version for each method will only transition to the requested state if the current trnasaction state matches the state passed in the stCurrentTxnState argument.

Set the State of Transaction

Method | Description
--- | ---
SetStateToAbort() | Sets the transaction state to abort.
SetStateToAbort(rtr_tx_jnl_state_t) | Sets the transaction state to abort.
SetStateToCommit() | Sets the transaction state to commit.
SetStateToCommit (rtr_tx_jnl_state_t) | Sets the transaction state to commit.
SetStateToDone() | Sets the transaction state to done.
SetStateToDone(rtr_tx_jnl_state_t) | Sets the transaction state to done.
SetStateToException() | Sets the transaction state to exception.
SetStateToException (rtr_tx_jnl_state_t) | Sets the transaction state to exception.

Previous | Next | Contents | Index