Reliable Transaction Router
C++ Foundation Classes
Previous Contents Index

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

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:

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

RTR()

RTR::RTR();

Prototype


RTR();

Return Value

None

Parameters

None

Description

Call this method to declare an RTR object.

Example


RTR *myRTR = new RTR();

Start()

RTR::Start();

Prototype


rtr_status_t Start();

Return Value

rtr_status_t Interpret value for the success or failure of this call.
Status Message
RTR_STS_ ACPDIED The RTR ACP is no longer running, restart RTR.
RTR_STS_ ACPNOTVIA ACP is no longer a viable entity.
RTR_STS_ BYTLMNSUFF Insufficient process quota bytlm, required 100000.
RTR_STS_ ERRSTAACP Unable to start ACP.
RTR_STS_ EXWSMAX Requested memory quotas exceed the system limit WSMAX.
RTR_STS_OK Normal successful completion.

Parameters

None

Description

Call this method to start RTR on a node.

Example


    // declare RTR object. 
    RTR *myRTR = new RTR(); 
    rtr_status_t sStatus; 
    sStatus = myRTR->Start();

Stop()

RTR::Stop();

Prototype


rtr_status_t Stop();

Return Value

rtr_status_t Interpret value for the success or failure of this call.
Status Description
RTR_STS_ ACPDIED The RTR ACP is no longer running, restart RTR.
RTR_STS_OK Normal successful completion.
RTR_STS_ RTRNOTRUN RTR not running.

Parameters

None

Description

Call this method to stop RTR on a node. Calling this method stops all RTR activity on the computer where it is called. Any running applications receive the error indication RTR_STS_NOACP. All facilities, links, and partitions are destroyed.

Example


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

Previous Next Contents Index