Object methods (public)

void operator = ( const ImqCache & cache );

Copies up to message length bytes of data from the cache object to the object. If automatic buffer is FALSE, the buffer length must already be sufficient to accommodate the copied data.

ImqBoolean automaticBuffer( ) const ;

Returns the automatic buffer value.

size_t bufferLength( ) const ;

Returns the buffer length.

char * bufferPointer( ) const ;

Returns the buffer pointer.

void clearMessage( );

Sets the message length and data offset to zero.

size_t dataLength( ) const ;

Returns the data length.

size_t dataOffset( ) const ;

Returns the data offset.

ImqBoolean setDataOffset( const size_t offset );

Sets the data offset. The message length is increased if necessary to ensure that it is no less than the data offset. This method returns TRUE if successful.

char * dataPointer( ) const ;

Returns a copy of the data pointer.

size_t messageLength( ) const ;

Returns the message length.

ImqBoolean setMessageLength( const size_t length );

Sets the message length. Increases the buffer length if necessary to ensure that the message length is no greater than the buffer length. Reduces the data offset if necessary to ensure that it is no greater than the message length. It returns TRUE if successful.

ImqBoolean moreBytes( const size_t bytes-required );

Assures that bytes-required more bytes are available (for writing) between the data pointer and the end of the buffer. It returns TRUE if successful.

If automatic buffer is TRUE, more memory is acquired as required; otherwise, the buffer length must already be adequate.

ImqBoolean read( const size_t length, char * & external-buffer );

Copies length bytes, from the buffer starting at the data pointer position, into the external-buffer. After the data has been copied, the data offset is increased by length. This method returns TRUE if successful.

ImqBoolean resizeBuffer( const size_t length );

Varies the buffer length, provided that automatic buffer is TRUE. This is achieved by reallocating the buffer memory. Up to message length bytes of data from the existing buffer are copied to the new one. The maximum number copied is length bytes. The buffer pointer is changed. The message length and data offset are preserved as closely as possible within the confines of the new buffer. It returns TRUE if successful, and FALSE if automatic buffer is FALSE.

Note:

This method can fail with MQRC_STORAGE_NOT_AVAILABLE if there is any problem with system resources.

ImqBoolean useEmptyBuffer( const char * external-buffer, const size_t length );

Identifies an empty user buffer, setting the buffer pointer to point to external-buffer, the buffer length to length, and the message length to zero. Performs a clearMessage. If the buffer is fully primed with data, use the useFullBuffer method instead. If the buffer is partially primed with data, use the setMessageLength method to indicate the correct amount. This method returns TRUE if successful.

This method can be used to identify a fixed amount of memory, as described above (external-buffer is not null and length is nonzero), in which case automatic buffer is set to FALSE, or it can be used to revert to system-managed flexible memory (external-buffer is null and length is zero), in which case automatic buffer is set to TRUE.

ImqBoolean useFullBuffer( const char * externalBuffer, const size_t length );

As for useEmptyBuffer, except that the message length is set to length. It returns TRUE if successful.

ImqBoolean write( const size_t length, const char * external-buffer );

Copies length bytes, from the external-buffer, into the buffer starting at the data pointer position. After the data has been copied, the data offset is increased by length, and the message length is increased if necessary to ensure that it is no less than the new data offset value. This method returns TRUE if successful.

If automatic buffer is TRUE, an adequate amount of memory is guaranteed; otherwise, the ultimate data offset must not exceed the buffer length.