# hp Reliable Transaction Router
C++ Foundation Classes

Previous | Contents | Index

# AcceptTransaction()

## RTRClientTransactionController::AcceptTransaction();

## Prototype

>     virtual rtr_status_t AcceptTransaction(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_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 OR ed 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().

## Description

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

## Example

>     // Let RTR know that this is the only object being sent and that
>     // we are done with our work.
>         cout << "AcceptTransaction..." << endl;
>             sStatus = AcceptTransaction();
>             print_status_on_failure(sStatus);

# Receive()

## RTRClientTransactionController::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_INVDATPTRPTARG | Invalid pointer-to-data-pointer pointer argument
RTR_STS_NORECEIVE | Attempting to receive at this point is not allowed.
RTR_STS_NOMESSAGE | The data object does not contain a message.
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
> - RTRApplictionMessage
> - 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 processing models in the Processing Models section of this manual and the Reliable Transaction Router Application Design Guide section on Message Reception Styles.

> ### tTimeout

> An optional receive timeout value in milliseconds. If the timeout expires, the call completes with status RTR_STS_TIMOUT.

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

>     abc_status ABCOrderTaker::DetermineOutcome()
>     {
>             RTRData  *pResult = NULL;
>             abc_status sStatus = ABCSuccess;
>             bool bDone = false;
>             while (!bDone)
>             {
>                    sStatus = Receive(&pResult);
>                    print_status_on_failure(sStatus);
>             }
>     delete pResult;
>             return sStatus;
>     }

# RegisterClassFactory()

## RTRClientTransactionController::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 methods in your application.

## Description

> 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(*pFactory);
>         print_status_on_failure(sStatus);

# RegisterFacility()

## RTRClientTransactionController::RegisterFacility();

## Prototype

>     virtual rtr_status_t RegisterFacility (rtr_const_facnam_t pszFacilityName,
>                                 rtr_const_rcpspc_t szRecipientName = "*",
>                                 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_INVACCSTRPTRARG | The access string argument is invalid.
RTR_STS_INVALIDFACILITY | The specified facility does not exist.
RTR_STS_INVFACNAMEARG | The facility 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

> ### pszFacilityName

> Pointer to a null-terminated facility 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 is RTR_NO_ACCESS.

## Description

> Call the RegisterFacility() member function to register an 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 RTR.
>             sStatus = RegisterFacility(ABCFacility);
>             print_status_on_failure(sStatus);
>     if(RTR_STS_OK == sStatus)
>           {
>             m_bRegistered = true;
>           }

# RegisterHandlers()

## RTRClientTransactionController::RegisterHandlers();

## Prototype

>     virtual rtr_status_t RegisterHandlers (RTRClientMessageHandler
>                                            *pMessageHandler,
>                                            RTRClientEventHandler
>                                            *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 RTRClientMessageHandler object that processes messages received.

> ### pEventHandler

> Pointer to an RTRClientEventHandler object that processes events received.

## Description

> Call the RegisterHandlers member function to register message and event handlers for your application. By registering an environment (a facility and a partition), your application informs RTR of the different configurations for which your application can process transactions. Your application will only use one environment at a time. The RTR framework picks the most efficient environment for your application depending on the number of client requests being received. If no environment is specified, RTR uses any of the previously defined environments in your applications process.

> Specify pMessageHandler and/or pEventHandler in order for your application to make use of the RTR frameworks predefined handlers.

> For more information on handlers see:

> - RTRData::Dispatch
> - RTRClientMessageHandler

## Example

>     // ABC Handlers
>     // Register the both handlers with RTR
>     sStatus = RegisterHandlers(&m_rtrHandlers,&m_rtrHandlers);
>     print_status_on_failure(sStatus);

# RejectTransaction()

## RTRClientTransactionController::RejectTransaction();

## Prototype

>     virtual rtr_status_t RejectTransaction(const 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_FACNOTREG | Facility is not registered.
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

>     pController->RejectTransaction();

# RTRClientTransactionController()

## RTRClientTransactionController::RTRClientTransactionController();

## Prototype

>     RTRClientTransactionController();
>     virtual ~RTRClientTransactionController();

## Return Value

> None

## Parameters

> None

## Description

> Call this constructor to create an RTRClientTransactionController object.

## Example

>     ABCOrderTaker::ABCOrderTaker():m_bRegistered(false)
>     {

>     }

# SendApplicationEvent()

## RTRClientTransactionController::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_NOEVENT | The data object does not contain an event.
RTR_STS_NOMESSAGE | The data object does not contain a message.
RTR_STS_OK | Normal successful completion.

## Parameters

> ### RTRApplicationEvent

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

> ### szRecipientName

> Name of the recipient. This null-terminated character 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.

> ### 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 event to the server. Formerly, application-defined events are only delivered to the clients or servers 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 does 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 = SendApplicationEvent(pOrder);
>     print_status_on_failure(sStatus);

# SendApplicationMessage()

## RTRClientTransactionController::SendApplicationMessage();

## Prototype

>     virtual rtr_status_t SendApplicationMessage(RTRApplicationMessage
>                                        *pRTRApplicationMessage,
>                                        bool bReadonly = false,
>                                        bool bReturnToSender = false,
>                                        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_INVRECPNAMPTARG | The recipient name 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 server.

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

> ### bReadonly

> Set this Boolean to true to indicate to RTR that this message does not perform and writes that would need to be shadowed.

> ### bReturnToSender

> Set this Boolean to true to indicate to RTR that, if the message is not delivered to the server, it should return to this transaction controller a message indicating that.

## Description

> This member function should be called when the application wants to send application data to the server. The RTRData object contains the data to be sent.

> For more information see:

> RTRData

## Example

>     // Send this Book Order object to a server capable of processing it.
>         cout << "SendApplicationMessage..." << endl;
>             sStatus = SendApplicationMessage(pOrder);
>             print_status_on_failure(sStatus);

# StartTransaction()

## RTRClientTransactionController::StartTransaction();

## Prototype

>     virtual rtr_status_t StartTransaction(rtr_timout_t
>                                           timeout = RTR_NO_TIMOUTMS);

## Return Value

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

Status | Message
--- | ---
RTR_STS_CONNECTIONLOST | An RTR connection has been lost.
RTR_STS_FACNOTREG | Facility is not registered.
RTR_STS_INVTIMOUTMS | Invalid timeout argument
RTR_STS_NOMESSAGE | The data object does not contain a message.
RTR_STS_NOSTARTTXN | A client transaction is already active.
RTR_STS_OK | Normal successful completion.
RTR_STS_TIMOUT | Timeout time expired.

## Parameters

> ### timeout

> Transaction timeout. This value is specified in milliseconds. If the timeout time expires, RTR aborts the transaction and returns status RTR_STS_TIMOUT. If no timeout is required, specify RTR_NO_TIMOUTMS.

## Description

> Explicitly start a transaction from a client transaction controller. This method is mandatory.

> The StartTransaction method is used to start a transaction explicitly. An explicit transaction start is only necessary if:

> - either a join to an existing transaction is to be done
> - or a transaction timeout is to be specified

> Transactions are implicitly started when a message is sent on a currently inactive transaction controller. Implicitly started transactions have no timeout and are not joined to other RTR transactions.

## Example

>         abc_status sStatus;

>     cout << "StartTransaction..." << endl;
>         sStatus = StartTransaction();
>         print_status_on_failure(sStatus);

Previous | Next | Contents | Index