# hp Reliable Transaction Router
C++ Foundation Classes

Previous | Contents | Index

# GetMessageType()

## RTRMessage::GetMessageType();

## Prototype

>     rtr_status_t GetMessageType(rtr_msg_type_t& mtMessageType);

## Return Value

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

Status | Message
--- | ---
RTR_STS_OK | Normal successful completion
RTR_STS_NOMESSAGE | The data object does not contain a message

## Parameters

> ### mtMessageType

> An RTR message.

## Description

> Retrieve the RTR message associated with the data in this RTRMessage object.

## Example

>     sStatus = ((RTRMessage*)pResult)->GetMessageType(mtMessageType);
>     print_status_on_failure(sStatus);

# GetReason()

## RTRMessage::GetReason();

## Prototype

>     rtr_reason_t GetReason();

## Return Value

> rtr_status_t This function either returns RTR_NO_REASON or the value specified by the participants in the transaction. If different participants provide different reason codes, RTR ORs them.

## Parameters

> None

## Description

> Retrieve the reason associated with the accepting or rejection of the transaction.

## Example

>     void OnAccepted(RTRMessage* pRTRData,
>             RTRClientTransactionController* pController)
>     {
>             rtr_status_t sStatus =
>                    pRTRData->GetSecondaryStatus();
>             rtr_reason_t rcReasonCode = pRTRData->GetReason();
>             m_bAcceptReceived = true;
>     };

# GetSecondaryStatus

## RTRMessage::GetSecondaryStatus();

## Prototype

>     rtr_status_t GetSecondaryStatus();

## Return Value

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

Status | Message
--- | ---
RTR_STS_OK | Normal successful completion
RTR_STS_NOMESSAGE | The data object does not contain a message.

## Parameters

> None

## Description

> Retrieve the secondary status associated with the accepting or rejection of the transaction.

## Example

>     void OnAccepted(RTRMessage* pRTRData,
>            RTRClientTransactionController* pController)
>     {
>           rtr_status_t sStatus =
>                  pRTRData->GetSecondaryStatus();
>             rtr_reason_t rcReasonCode = pRTRData->GetReason();
>             m_bAcceptReceived = true;

>     };

# 3.18 RTRStream Class

The RTRStream class derives from RTRData and extends the RTRData class by allowing RTR applications to issue multiple read and write requests to the buffer (managed by RTRData) without needing to maintain Pointer to the end of the buffer.

An RTRStream object automatically handles the details of maintaining the offset within the buffer when the application wants to read and write multiple times to a buffer.

When reading from and writing to a stream, a copy of the data is performed.

# RTRStream Class Members

Construction

Method | Description
--- | ---
RTRStream() | Default constructor
~RTRStream | Default destructor

Operations

Method | Description
--- | ---
ReadFromStream(rtr _msgbuf_t, rtr_msglen_t, rtr_msglen_t); | Copy the data from the buffer managed by RTRData to the buffer specified.
ReadFromStream(rtr_sgn_32_t); | Copy the signed integer from the buffer managed by RTRData to uiNumber.
ReadFromStream(char, size_t); | Copy the data from the buffer managed by RTRData to pString.
ReadFromStream(rtr_uns_32_t); | Copy the unsigned integer from the buffer managed by RTRData to uiNumber.
WriteToStream(rtr _msgbuf_t, rtr_msglen_t); | Copy data to the end of the buffer managed by RTRData.
WriteToStream(const char); | Copy string to the end of the buffer managed by RTRData.
WriteToStream(rtr_sgn_32_t); | Copy the signed integer to the end of the buffer managed by RTRData.
WriteToStream(rtr_uns_32_t); | Copy the unsigned integer to the end of the buffer managed by RTRData.

Operators

Operator | Description
--- | ---
RTRStream& operator>> (char) | ReadFromStream operator
RTRStream& operator>> (rtr_sgn_32_t) | ReadFromStream operator
RTRStream& operator>> (rtr_uns_32_t) | ReadFromStream operator
RTRStream& operator<< (const char) | WriteToStream operator
RTRStream& operator<< (rtr_sgn_32_t) | WriteToStream operator
RTRStream& operator<< (rtr_uns_32_t) | WriteToStream operator

# operator>>

## RTRStream::operator>>

## Prototype

>     RTRStream& operator>> (char *pString)
>       {
>             ReadFromStream(pString);
>             return *this;
>       }
>     RTRStream& operator>> (rtr_sgn_32_t &iNumber)
>       {
>             ReadFromStream(iNumber);
>             return *this;
>       }
>     RTRStream& operator>> (rtr_uns_32_t &uiNumber)
>       {
>             ReadFromStream(uiNumber);
>             return *this;
>       }

## Return Value

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

Status | Message
--- | ---
RTR_STS_OK | Normal successful completion
RTR_STS_INVARGPTR |

## Parameters

> ### pString

> Pointer to a character string.

> ### iNumber

> A signed integer.

> ### uiNumber

> An unsigned integer.

## Description

> >> denotes the ReadFromStream operators. These member functions extract data from a buffer by calling ReadFromStream to read the data and return *this. The three types of stream data are string, signed, and unsigned.

## Example

>     // Populate this object with the data
>         *this >> m_uiPrice >> m_uiISBN  >> m_szTitle >> m_szAuthor;

>     // The 1 line call above is equivilant to the 4 lines below.
>     //        ReadFromStream(m_uiISBN);
>     //        ReadFromStream(m_uiPrice);
>     //        ReadFromStream(m_szTitle);
>     //        ReadFromStream(m_szAuthor);

# operator<<

## RTRStream::operator<<

## Prototype

>     RTRStream& operator<< (char *pString)
>       {
>             WriteToStream(pString);
>             return *this;
>       }
>     RTRStream& operator<< (rtr_sgn_32_t &iNumber)
>       {
>             WriteToStream(iNumber);
>             return *this;
>       }
>     RTRStream& operator<< (rtr_uns_32_t &uiNumber)
>       {
>             WriteToStream(uiNumber);
>             return *this;
>       }

## Return Value

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

Status | Message
--- | ---
RTR_STS_OK | Normal successful completion
RTR_STS_INVSTRINGPTRARG | The string pointer argument is invalid - string too long.

## Parameters

> ### pString

> Pointer to a character string.

> ### iNumber

> A signed integer.

> ### uiNumber

> An unsigned integer.

## Description

> << denotes the WriteToStream operators. These member functions write data to a buffer by calling WriteToStream to write the data and return *this. The three types of stream data are string, signed, and unsigned.

## Example

>     // Save the type of object we are. This is used by the class factory
>     // on the server side to determine which type of class to allocate.
>         *this << ABC_BOOK;
>         *this << m_uiPrice << m_uiISBN  << m_szTitle << m_szAuthor;
>     // The 1 line call above is equivalent to the 4 lines below. We
>     // can use the << and >> operators because we know that the data
>     // which we store is not > the current RTR maximum  = 65535 bytes.
>     //        WriteToStream(m_uiISBN);
>     //        WriteToStream(m_uiPrice);
>     //        WriteToStream(m_szTitle);
>     //        WriteToStream(m_szAuthor);

# ReadFromStream()

## RTRStream::ReadFromStream();

## Prototype

>     rtr_status_t ReadFromStream(rtr_msgbuf_t pvBuffer,
>                                 rtr_msglen_t &uiBufferSize
>                                 rtr_msglen_t &uiSizeCopied);

>     rtr_status_t ReadFromStream(char *pString, size_t uiStringSize);

>     rtr_status_t ReadFromStream(rtr_sgn_32_t &iNumber);

>     rtr_status_t ReadFromStream(rtr_uns_32_t &uiNumber);

## Return Value

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

Status | Message
--- | ---
RTR_STS_OK | Normal successful completion.
RTR_STS_APPBUFFTOOSMALL | The application buffer is too small.
RTR_STS_ENDOFSTREAM | The end-of-stream has been reached.

## Parameters

> ### uiBufferSize

> An unsigned integer for length of the buffer.

> ### pvBuffer

> A void pointer to a buffer.

> ### uiNumber

> An unsigned integer.

> ### pString

> Pointer to a character string.

> ### iNumber

> A signed integer

## Description

> Reads the first instance of a data type from a buffer as specified in the ReadFromStream methods. Note that the string buffer is assumed to be large enough (RTR_MAX_MSGLEN).

## Example

>     RTRStream::ReadFromStream(pString);

# RTRStream()

## RTRStream::RTRStream();

## Prototype

>     RTRStream();

## Return Value

> None

## Parameters

> None

## Description

> Constructor method for the RTRStream class.

## Example

>     RTRStream::RTRStream();

# WriteToStream()

## RTRStream::WriteToStream();

## Prototype

>     rtr_status_t WriteToStream(rtr_const_msgbuf_t pvBuffer, rtr_msglen_t
>                                                          uiBufferLength);

>     rtr_status_t WriteToStream(const char *pString);

>     rtr_status_t WriteToStream(rtr_sgn_32_t iNumber);

>     rtr_status_t WriteToStream(rtr_uns_32_t uiNumber);

## Return Value

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

Status | Message
--- | ---
RTR_STS_OK | Normal successful completion.
RTR_STS_ENDOFSTREAM | The end-of-stream has been reached.

## Parameters

> ### uiBufferLength

> An unsigned integer for length of the buffer.

> ### pvBuffer

> A void pointer to a buffer.

> ### uiNumber

> An unsigned integer.

> ### iNumber

> A signed integer.

> ### pString

> Pointer to a character string.

## Description

> Write to a data buffer, specifying the data with either buffer and buffer length, as unsigned integer, or string.

## Example

>     RTRStream::WriteToStream(uiNumber);

# Chapter 4
Management Classes

Management classes are offered for both new and existing RTR applications. The types of management classes include:

- Setup class:
  RTR class
- Facility classes:
  - RTRFacilityMember class
  - RTRFacilityMemberArray class
  - RTRFacilityProperties class
  - RTRFacilityManager class
- Partition classes:
  - RTRBackendPartitonProperties class
  - RTRKeySegment class
  - RTRKeySegmentArray
  - RTRPartitionManager class
- Counter classes:
  - RTRCounter class
  - RTRSignedCounter class
  - RTRStringCounter class
  - RTRUnsignedCounter class

# 4.1 RTR

The RTR class is a setup class, for RTR system management operations, designed for starting and stopping RTR, and creating and deleting RTR journals.

# RTR Class Members

Construction

Method | Description
--- | ---
RTR() | Constructor
~RTR() | Destructor

Operations

Method | Description
--- | ---
CreateJournal(bool) | Create a journal for RTR.
DeleteJournal() | Delete the journal for RTR.
GetErrorText(rtr_status_t) | Get the error text associated with the rtr_status_t return value.
IsRunning() | Determine if RTR is running.
Start() | Start RTR.
StartWebServer(bool, bool) | Start RTR on a web server.
Stop() | Stop RTR.
StopWebServer() | Stop RTR on a web server.

# CreateJournal()

## RTR::CreateJournal();

## Prototype

>     rtr_status_t CreateJournal( bool bSupersede = false);

## Return Value

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

> Status | Message
> --- | ---
> RTR_STS_OK | Normal successful completion
> RTR_STS_ ILLDEVTYP | RTR can only create its journal files on directory structured devices.

## Parameters

> ### bSupersede

> A boolean attribute that specifies how to handle cases where a journal already exists. Set bSupersede to true to overwrite an existing journal. If set to false, a journal is created only if no journal previously existed.

## Description

> Call this method to create an RTR journal file. A journal is required for all facility members with a backend role, and any frontends that participate in nested transactions.

> For more information on RTR journals, see the RTR Application Design Guide and the RTR System Manager's Manual .

## Example

>     // Declare an RTR object.
>     RTR *myRTR = new RTR();
>      rtr_status_t sStatus;
>      bool  bSupersede = false;  // false -> no supersede
>      sStatus = myRTR->CreateJournal(bSupersede);

# DeleteJournal()

## RTR::DeleteJournal();

## Prototype

>     rtr_status_t DeleteJournal();

## Return Value

> rtr_status_t The RTR status message return value. RTR_STS_OK is the normal successful completion.

## Parameters

> None

## Description

> Call this method for deleting a journal.

> For more information on RTR journals, see the RTR System Manager's Manual .

## Example

>      // declare an RTR object
>      RTR *myRTR = new RTR();
>      rtr_status_t sStatus;
>      sStatus = myRTR->DeleteJournal();

# GetErrorText()

## RTR::GetErrorText();

## Prototype

>     static const char *GetErrorText(rtr_status_t sStatus);

## Return Value

> Returns a pointer to the error message text associated with a known RTR message.

## Parameters

> ### rtr_status_t

> The RTR status message return value. RTR_STS_OK is the normal successful completion.

## Description

> Call this method to retrieve the error message text associated with an RTR status.

## Example

>         // start rtr
>         RTRmyRTR;
>         sStatus = myRTR.Start();
>         cout << myRTR.GetErrorText(sStatus) << endl;
>         // create journal
>         sStatus = myRTR.CreateJournal(true);
>         cout << myRTR.GetErrorText(sStatus) << endl;

>         //An example from the Sample application in the Examples directory
>         inline void print_status_on_failure(rtr_status_t sStatus)
>         {
>             switch (sStatus)
>             {
>         case ABCSuccess :
>         case ABCOrderSucceeded :
>         case ABCOrderFailed :{
>         break;
>         }
>         default: {
>                             cout << RTR::GetErrorText(sStatus);
>                             break;
>         };
>           }
>         return;
>         }

# IsRunning()

## RTR::IsRunning();

## Prototype

>     bool IsRunning();

## Return Value

Status | Message
--- | ---
TRUE | RTR is running.
FALSE | RTR is not running.

## Parameters

> None

## Description

> Call this method to find out if RTR is running on this node. If RTR is running, it will return a true, otherwise an error code.

## Example

>      RTR *myRTR = new RTR();
>      rtr_status_t sStatus;
>      sStatus = myRTR->IsRunning();

Previous | Next | Contents | Index