Reliable Transaction Router
C++ Foundation Classes
Previous Contents Index

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:

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 a 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:

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

3.10 RTRClientTransactionProperties

This class holds the properties of its associated RTRServerTransaction object.

RTRClientTransactionProperties Class Members

Construction
Method Description
RTRClientTransactionProperties() Constructor
~RTRClientTransactionProperties() Destructor

RTRClientTransactionProperties()

RTRClientTransactionProperties::RTRClientTransactionProperties();

Prototype


RTRClientTransactionProperties(); 
virtual ~RTRClientTransactionProperties();

Return Value

None

Parameters

None

Description

This class holds the properties of its associated RTRClientTransaction object.

Example


RTRClientTransactionProperties::RTRClientTransactionProperties(); 
{ 
}

3.11 Data Classes and the Class Factory

The data classes of the C++ API are common to both server and client applications. There classes include:

The RTRData class is the base class of all the C++ foundation class data classes. When applications want to receive data they specify Pointer to an RTRData object. After a successful call to the Receive method in either the client or server RTRtransactionController class, RTRData contains one of the following:

The data classes are common to both client and server applications.

The RTRStream class is an RTRData-derived class designed for RTRApplicationMessage and RTRApplicationEvent data objects to read from and write to a buffer.

The RTRClassFactory class creates instances of data classes based on the contents of a Receive call for a message or event. For more information on RTR message and event processing, see the RTR Application Design Guide.

3.12 RTRApplicationEvent Class

RTRApplicationEvent Class Members

Construction
Method Description
RTRApplicationEvent () Default constructor
RTRApplicationEvent
(RTRApplicationEvent &) 		Copy constructor

Operations
Method Description
Dispatch() Basic method.
GetEventData( rtr_msgbuf_t ) Retrieve the application data associated with this RTRApplicationEvent object.
GetEventDataLength(); Retrieve the actual length of the buffer allocated for this RTRApplicationEvent object.
GetEventNumber( rtr_evtnum_t ) Retrieve the application event associated with the data in this RTRApplicationEvent object.
SetEventData( rtr_msgbuf_t,
rtr_msglen_t) 		Set the actual data length of the buffer allocated for this RTRApplicationEvent object.
SetEventNumber( const rtr_evtnum_t) Set the application event number associated with the data in this RTRApplicationEvent object.

Previous Next Contents Index