> tibemsBytesMsg
> Type
> Purpose
> A message containing a stream of uninterpreted bytes.
> Related Types
> tibemsMsg on page 21
> Remarks
> Messages with this body type contain a single value, which is a byte sequence.

> Function | Description | Page
> tibemsBytesMsg_Create | Create a bytes message. | 73
> tibemsBytesMsg_GetBodyLength | Get the body length (in bytes) of a bytes message. | 74
> tibemsBytesMsg_GetBytes | Get the body data of a bytes message. | 75
> tibemsBytesMsg_Read | Read primitive datatypes from the byte stream in the message body. | 76
> tibemsBytesMsg_ReadBytes | Read bytes to a byte sequence from the byte stream in the message body. | 80
> tibemsBytesMsg_Reset | Set the read position to the beginning of the byte stream, and mark the message body as read-only. | 82
> tibemsBytesMsg_SetBytes | Set the body data of a bytes message from a byte sequence. | 83
> tibemsBytesMsg_Write | Write primitive datatypes to the byte stream in the message body. | 84
> tibemsBytesMsg_WriteBytes | Write bytes from a byte array to the byte stream in the message body. | 87

> tibemsBytesMsg_Create
> Function
> Purpose
> Create a bytes message.
> C Declaration
> tibems_status tibemsBytesMsg_Create(
> tibemsBytesMsg* message );
> COBOL Call
> CALL "tibemsBytesMsg_Create"
> USING BY REFERENCE message,
> RETURNING tibems-status
> END-CALL.

> | message has usage pointer.

> Parameters

> Parameter | Description
> message | The function stores a pointer to the new message in this location.

> Remarks
> This call creates a new bytes message.
> When your application creates a message, it also allocates storage for that message. This storage must subsequently be freed by a call to tibemsMsg_Destroy.
> See Also
> tibemsMsg_Create on page 28
> tibemsMsg_Destroy on page 31
> tibemsBytesMsg_GetBodyLength
> Function
> Purpose
> Get the body length (in bytes) of a bytes message.
> C Declaration
> tibems_status tibemsBytesMsg_GetBodyLength(
> tibemsMsg message,
> tibems_int* return_length );
> COBOL Call
> CALL "tibemsBytesMsg_GetBodyLength"
> USING BY VALUE message,
> BY REFERENCE return-length,
> RETURNING tibems-status
> END-CALL.

> | message has usage pointer.

> Parameters

> Parameter | Description
> message | Get the body length of this message.
> return_length | The function stores the body length in this location.

> tibemsBytesMsg_GetBytes
> Function
> Purpose
> Get the body data of a bytes message.
> C Declaration
> tibems_status tibemsBytesMsg_GetBytes(
> tibemsBytesMsg message,
> void** bytes,
> tibems_uint* byteSize );
> COBOL Call
> CALL "tibemsBytesMsg_GetBytes"
> USING BY VALUE message,
> BY REFERENCE bytes,
> BY REFERENCE byteSize,
> RETURNING tibems-status
> END-CALL.

> | message and bytes have usage pointer.

> Parameters

> Parameter | Description
> message | Get the byte sequence of this bytes message.
> bytes | The function stores a pointer to the bytes of the message in this location. Your program must not change the bytes, which belong to the message; if you must modify the bytes, make a private copy first.
> byteSize | The function stores the length of the byte sequence in this location.

> Remarks
> This call extracts a pointer to the body data of a bytes message.
> The byte sequence storage persists until your program destroys the message object.
> tibemsBytesMsg_Read
> Function
> Purpose
> Read primitive datatypes from the byte stream in the message body.
> C Declaration
> tibems_status tibemsBytesMsg_ReadBoolean(
> tibemsBytesMsg message,
> tibems_bool* value );
> tibems_status tibemsBytesMsg_ReadByte(
> tibemsBytesMsg message,
> tibems_byte* value );
> tibems_status tibemsBytesMsg_ReadChar(
> tibemsBytesMsg message,
> tibems_wchar* value );
> tibems_status tibemsBytesMsg_ReadDouble(
> tibemsBytesMsg message,
> tibems_double* value );
> tibems_status tibemsBytesMsg_ReadFloat(
> tibemsBytesMsg message,
> tibems_float* value );
> tibems_status tibemsBytesMsg_ReadInt(
> tibemsBytesMsg message,
> tibems_int* value );
> tibems_status tibemsBytesMsg_ReadLong(
> tibemsBytesMsg message,
> tibems_long* value );
> tibems_status tibemsBytesMsg_ReadShort(
> tibemsBytesMsg message,
> tibems_short* value );
> tibems_status tibemsBytesMsg_ReadUnsignedByte(
> tibemsBytesMsg message,
> tibems_int* value );
> tibems_status tibemsBytesMsg_ReadUnsignedShort(
> tibemsBytesMsg message,
> tibems_int* value );
> tibems_status tibemsBytesMsg_ReadUTF(
> tibemsBytesMsg message,
> const char** value,
> tibems_int* length );
> COBOL Call
> CALL "tibemsBytesMsg_ReadBoolean"
> USING BY VALUE message,
> BY REFERENCE tibems-Boolean,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsBytesMsg_ReadByte"
> USING BY VALUE message,
> BY REFERENCE value,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsBytesMsg_ReadChar"
> USING BY VALUE message,
> BY REFERENCE value,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsBytesMsg_ReadDouble"
> USING BY VALUE message,
> BY REFERENCE value,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsBytesMsg_ReadFloat"
> USING BY VALUE message,
> BY REFERENCE value,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsBytesMsg_ReadInt"
> USING BY VALUE message,
> BY REFERENCE value,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsBytesMsg_ReadLong"
> USING BY VALUE message,
> BY REFERENCE value,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsBytesMsg_ReadShort"
> USING BY VALUE message,
> BY REFERENCE value,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsBytesMsg_ReadUnsignedByte"
> USING BY VALUE message,
> BY REFERENCE value,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsBytesMsg_ReadUnsignedShort"
> USING BY VALUE message,
> BY REFERENCE value,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsBytesMsg_ReadUTF"
> USING BY VALUE message,
> BY REFERENCE value,
> BY REFERENCE length,
> RETURNING tibems-status
> END-CALL.

> | message has usage pointer in all calls. value has usage pointer in tibemsBytesMsg_ReadUTF.

> Parameters

> Parameter | Description
> message | Read a datum from the body byte stream of this message.
> value | The function stores the datum in this location.
> length | tibemsBytesMsg_ReadUTF reads a UTF-8 string. Since the length of the string cannot be determined in advance, the function stores the actual length in this location.

> Remarks
> The JMS specification defines eleven calls to extract data from the byte stream body of a tibemsBytesMsg.
> Each call reads a unit of data from the stream, and advances the read position so that the next read call gets the next datum.

> Table 8 BytesMessage Read Functions
> Function | # Bytes | Interpret As
> tibemsBytesMsg_ReadBoolean | 1 | tibems_bool
> tibemsBytesMsg_ReadByte | 1 | tibems_byte
> tibemsBytesMsg_ReadUnsignedByte | 1 | tibems_int
> tibemsBytesMsg_ReadShort | 2 | tibems_short
> tibemsBytesMsg_ReadUnsignedShort | 2 | tibems_int
> tibemsBytesMsg_ReadChar | 2 | tibems_wchar
> tibemsBytesMsg_ReadInt | 4 | tibems_int
> tibemsBytesMsg_ReadLong | 8 | tibems_long
> tibemsBytesMsg_ReadFloat | 4 | tibems_float
> tibemsBytesMsg_ReadDouble | 8 | tibems_double
> tibemsBytesMsg_ReadUTF | varies | char* Encoded as UTF.

> See Also
> tibemsBytesMsg_ReadBytes on page 80
> tibemsBytesMsg_ReadBytes
> Function
> Purpose
> Read bytes to a byte sequence from the byte stream in the message body.
> C Declaration
> tibems_status tibemsBytesMsg_ReadBytes(
> tibemsBytesMsg message,
> const void** value,
> tibems_int requested_length,
> tibems_int* return_length );
> COBOL Call
> CALL "tibemsBytesMsg_ReadBytes"
> USING BY VALUE message,
> BY REFERENCE value,
> BY VALUE requested-length,
> BY REFERENCE return-length,
> RETURNING tibems-status
> END-CALL.

> | message and value have usage pointer.

> Parameters

> Parameter | Description
> message | Read bytes from the body of this message.
> value | The program supplies a location. In that location, this call stores a pointer to the next block of bytes within the bytes message. Your program must not change the bytes, which belong to the message; if you must modify the bytes, make a private copy first.
> requested_length | Read (at most) this number of bytes from the stream. This argument must be greater than zero.
> return_length | The function stores in this location the actual number of bytes that it read. (If the number of bytes remaining in the message is less than the requested_length, then this location indicates that number of remaining bytes. Your program must not use bytes beyond this limit.) When the function cannot read even one byte, it stores -1 in this location (and returns a successful status code).

> Remarks
> Each call reads bytes from the stream into the byte array, and advances the read position.
> tibemsBytesMsg_Reset
> Function
> Purpose
> Set the read position to the beginning of the byte stream, and mark the message body as read-only.
> C Declaration
> tibems_status tibemsBytesMsg_Reset(
> tibemsBytesMsg message );
> COBOL Call
> CALL "tibemsBytesMsg_Reset"
> USING BY VALUE message,
> RETURNING tibems-status
> END-CALL.

> | message has usage pointer.

> Parameters

> Parameter | Description
> message | Reset the read position for this message.

> Remarks
> This call prepares a message body for reading, as if the message were newly received. Contrast tibemsMsg_ClearBody on page 26, which clears a message body in preparation for writing, as if it were newly created.
> tibemsBytesMsg_SetBytes
> Function
> Purpose
> Set the body data of a bytes message from a byte sequence.
> C Declaration
> tibems_status tibemsBytesMsg_SetBytes(
> tibemsBytesMsg message,
> const void* bytes,
> tibems_uint byteSize );
> COBOL Call
> CALL "tibemsBytesMsg_SetBytes"
> USING BY VALUE message,
> BY REFERENCE bytes,
> BY VALUE byteSize,
> RETURNING tibems-status
> END-CALL.

> | message has usage pointer.

> Parameters

> Parameter | Description
> message | Set the body data of this bytes message.
> bytes | Copy this byte sequence into the message body.
> byteSize | Copy this number of bytes into the message.

> tibemsBytesMsg_Write
> Function
> Purpose
> Write primitive datatypes to the byte stream in the message body.
> C Declaration
> tibems_status tibemsBytesMsg_WriteBoolean(
> tibemsBytesMsg message,
> tibems_bool value );
> tibems_status tibemsBytesMsg_WriteByte(
> tibemsBytesMsg message,
> tibems_byte value );
> tibems_status tibemsBytesMsg_WriteChar(
> tibemsBytesMsg message,
> tibems_wchar value );
> tibems_status tibemsBytesMsg_WriteDouble(
> tibemsBytesMsg message,
> tibems_double value );
> tibems_status tibemsBytesMsg_WriteFloat(
> tibemsBytesMsg message,
> tibems_float value );
> tibems_status tibemsBytesMsg_WriteInt(
> tibemsBytesMsg message,
> tibems_int value );
> tibems_status tibemsBytesMsg_WriteLong(
> tibemsBytesMsg message,
> tibems_long value );
> tibems_status tibemsBytesMsg_WriteShort(
> tibemsBytesMsg message,
> tibems_short value );
> tibems_status tibemsBytesMsg_WriteUTF(
> tibemsBytesMsg message,
> const char* value );
> COBOL Call
> CALL "tibemsBytesMsg_WriteBoolean"
> USING BY VALUE message,
> BY VALUE tibems-Boolean,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsBytesMsg_WriteByte"
> USING BY VALUE message,
> BY VALUE value,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsBytesMsg_WriteChar"
> USING BY VALUE message,
> BY VALUE value,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsBytesMsg_WriteDouble"
> USING BY VALUE message,
> BY VALUE value,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsBytesMsg_WriteFloat"
> USING BY VALUE message,
> BY VALUE value,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsBytesMsg_WriteInt"
> USING BY VALUE message,
> BY VALUE value,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsBytesMsg_WriteLong"
> USING BY VALUE message,
> BY VALUE value,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsBytesMsg_WriteShort"
> USING BY VALUE message,
> BY VALUE value,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsBytesMsg_WriteUTF"
> USING BY VALUE message,
> BY REFERENCE value,
> RETURNING tibems-status
> END-CALL.

> | message has usage pointer in all calls.

> Parameters

> Parameter | Description
> message | Write data to the body of this bytes message.
> value | Write this value to the message.

> Remarks
> The JMS specification defines these nine calls to insert data into the byte stream of a BytesMessage.
> Each call writes a data value to the stream, and advances the write position so that the next write call appends to the new end of the stream.

> Table 9 BytesMessage Write Functions
> Function | # Bytes | Notes
> tibemsBytesMsg_WriteBoolean | 1 | This function writes true as (byte)1, and false as (byte)0.
> tibemsBytesMsg_WriteByte | 1 |
> tibemsBytesMsg_WriteShort | 2 |
> tibemsBytesMsg_WriteChar | 2 | This function writes a 2-byte character—high byte first.
> tibemsBytesMsg_WriteInt | 4 |
> tibemsBytesMsg_WriteLong | 8 |
> tibemsBytesMsg_WriteFloat | 4 |
> tibemsBytesMsg_WriteDouble | 8 |
> tibemsBytesMsg_WriteUTF | varies | For information about the UTF-8 format, see File System Safe UCS Transformation Format (FSS_UFT), X/Open Preliminary Specification, X/Open Company Ltd., Document Number: P316. This information also appears in ISO/IEC 10646, Annex P.

> See Also
> tibemsBytesMsg_WriteBytes on page 87
> tibemsBytesMsg_WriteBytes
> Function
> Purpose
> Write bytes from a byte array to the byte stream in the message body.
> C Declaration
> tibems_status tibemsBytesMsg_WriteBytes(
> tibemsBytesMsg message,
> const void* value,
> tibems_uint length );
> COBOL Call
> CALL "tibemsBytesMsg_WriteBytes"
> USING BY VALUE message,
> BY REFERENCE value,
> BY VALUE size,
> RETURNING tibems-status
> END-CALL.

> | message has usage pointer in all calls.

> Parameters

> Parameter | Description
> message | Write bytes into the body data of this bytes message.
> value | Write bytes from this byte array into the message.
> length | Write this number of bytes from the byte array.

> Remarks
> Each call writes bytes from the byte array into the stream, and advances the write position.

Copyright © TIBCO Software Inc. All Rights Reserved.