Preparing message data

When you send a message, message data is first prepared in a buffer managed by an ImqCache object (see ImqCache). A buffer is associated (by inheritance) with each ImqMessage object (see ImqMessage): it can be supplied by the application (using either the useEmptyBuffer or useFullBuffer method) or automatically by the system. The advantage of the application supplying the message buffer is that no data copying is necessary in many cases because the application can use prepared data areas directly. The disadvantage is that the supplied buffer is of a fixed length.

The buffer can be reused, and the number of bytes transmitted can be varied each time, by using the setMessageLength method before transmission.

When supplied automatically by the system, the number of bytes available is managed by the system, and data can be copied into the message buffer using, for example, the ImqCache write method, or the ImqMessage writeItem method. The message buffer grows according to need. As the buffer grows, there is no loss of previously-written data. A large or multipart message can be written in sequential pieces.

The following examples show simplified message sends.

1. Use prepared data in a user-supplied buffer

   char szBuffer[ ] = "Hello world" ;
    
   msg.useFullBuffer( szBuffer, sizeof( szBuffer ) );
   msg.setFormat( MQFMT_STRING );
    
   

2. Use prepared data in a user-supplied buffer, where the buffer size exceeds the data size

   char szBuffer[ 24 ] = "Hello world" ;
    
   msg.useEmptyBuffer( szBuffer, sizeof( szBuffer ) );
   msg.setFormat( MQFMT_STRING );
   msg.setMessageLength( 12 );
    
   

3. Copy data to a user-supplied buffer

   char szBuffer[ 12 ];
    
   msg.useEmptyBuffer( szBuffer, sizeof( szBuffer ) );
   msg.setFormat( MQFMT_STRING );
   msg.write( 12, "Hello world" );
    
   

4. Copy data to a system-supplied buffer

   msg.setFormat( MQFMT_STRING );
   msg.write( 12, "Hello world" );
    
   

5. Copy data to a system-supplied buffer using objects (objects set the message format as well as content)

   ImqString strText( "Hello world" );
    
   msg.writeItem( strText );