ImqCache

Figure 5. ImqCache class

Use this class to hold or marshal data in memory. The user can nominate a buffer of memory of fixed size, or the system can provide a flexible amount of memory automatically. This class relates to the MQI calls listed in Table 7.

Other relevant classes

ImqError (see ImqError).

Object attributes

automatic buffer

Indicates whether buffer memory is managed automatically by the system (TRUE) or is supplied by the user (FALSE). It is initially set to TRUE.

This attribute is not set directly. It is set indirectly using either the useEmptyBuffer or the useFullBuffer method.

If user storage is supplied, this attribute is FALSE, buffer memory cannot grow, and buffer overflow errors can occur. The address and length of the buffer remain constant.

If user storage is not supplied, this attribute is TRUE, and buffer memory can grow incrementally to accommodate an arbitrary amount of message data. However, when the buffer grows, the address of the buffer might change, and so care has to be exercised when using the buffer pointer and data pointer.

buffer length

The number of bytes of memory in the buffer. The initial value is zero.

buffer pointer

The address of the buffer memory. The initial value is null.

data length

The number of bytes succeeding the data pointer. Equal to or less than the message length. The initial value is zero.

data offset

The number of bytes preceding the data pointer. Equal to or less than the message length. The initial value is zero.

data pointer

The address of that part of the buffer that is to be written to or read from next. The initial value is null.

message length

The number of bytes of significant data in the buffer. The initial value is zero.

Constructors

ImqCache( );

The default constructor.

ImqCache( const ImqCache & cache );

The copy constructor.

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 both 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 will be 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 may 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 nonnull 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.

Reason codes

MQRC_BUFFER_NOT_AUTOMATIC

MQRC_DATA_TRUNCATED

MQRC_INSUFFICIENT_BUFFER

MQRC_INSUFFICIENT_DATA

MQRC_NULL_POINTER

MQRC_STORAGE_NOT_AVAILABLE

MQRC_ZERO_LENGTH