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:

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

Get the Type of Transaction
Method Description
TransactionIsOriginal() Tests whether the transaction is an original transaction.
TransactionIsReplay() Tests whether the transaction is a replayed transaction.
TransactionIsRecovery() Tests whether the transaction is a recovered transaction.

Get Functions
Method Description
GetFacilityName(rtr_facnam_t,
const size_t) 		Get the facility.
GetTransactionState
(rtr_tx_jnl_state_t) 		Get the transaction state
GetTID(rtr_tid_t) Get the TID (transaction ID).

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