> tibemsStreamMsg
> Type
> Purpose
> A message containing a stream of data items.
> Related Types
> tibemsMsg on page 21

> Member | Description | Page
> tibemsStreamMsg_Create | Create a stream message. | 109
> tibemsStreamMsg_FreeField | Free storage allocated during the reading of a stream message. | 110
> tibemsStreamMsg_Read | Read primitive datatypes from a stream message. | 111
> tibemsStreamMsg_ReadBytes | Read a byte array from a stream message. | 114
> tibemsStreamMsg_ReadField | Read a field from a stream message. | 115
> tibemsStreamMsg_Reset | Set the read position to the beginning of the stream, and mark the message body as read-only. | 116
> tibemsStreamMsg_Write | Write data to a stream message. | 117
> tibemsBytesMsg_WriteBytes | Write bytes from a byte array to a stream message. | 121

> Remarks
> Each datum in the stream must be a primitive type, or an object representation of a primitive type.
> Extensions
> TIBCO Enterprise Message Service extends the MapMessage and StreamMessage body types in two ways. These extensions allow TIBCO Enterprise Message Service to exchange messages with TIBCO Rendezvous and ActiveEnterprise formats that have certain features not available within the JMS specification.

> ● | You can insert another MapMessage or StreamMessage instance as a submessage into a MapMessage or StreamMessage, generating a series of nested messages, instead of a flat message.

> ● | You can use arrays as well as primitive types for the values.

> These extensions add considerable flexibility to the two body types. However, they are extensions and therefore not compliant with JMS specifications. Extended messages are tagged as extensions with the vendor property tag JMS_TIBCO_MSG_EXT.
> For more information on message compatibility with Rendezvous messages, see Message Body in TIBCO Enterprise Message Service User’s Guide.
> tibemsStreamMsg_Create
> Function
> Purpose
> Create a stream message.
> C Declaration
> tibems_status tibemsStreamMsg_Create(
> tibemsStreamMsg* message );
> COBOL Call
> CALL "tibemsStreamMsg_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 stream 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
> tibemsStreamMsg_FreeField
> Function
> Purpose
> Free storage allocated during the reading of a stream message.
> C Declaration
> void tibemsStreamMsg_FreeField(
> tibemsMsgField* field );
> COBOL Call
> CALL "tibemsStreamMsg_FreeField"
> USING BY REFERENCE field
> END-CALL.
> Parameters

> Parameter | Description
> field | Free the storage associated with this field struct.

> Remarks
> Each successful call to tibemsStreamMsg_ReadField allocates storage for a tibemsMsgField. Programs that call tibemsStreamMsg_ReadField must subsequently call this function to free that allocated storage.
> This function does not need to be called after tibemsMapMsg_GetField.
> See Also
> tibemsMsgField on page 132
> tibemsStreamMsg_ReadField on page 115
> tibemsStreamMsg_Read
> Function
> Purpose
> Read primitive datatypes from a stream message.
> C Declaration
> tibems_status tibemsStreamMsg_ReadBoolean(
> tibemsStreamMsg message,
> tibems_bool* value );
> tibems_status tibemsStreamMsg_ReadByte(
> tibemsStreamMsg message,
> tibems_byte* value );
> tibems_status tibemsStreamMsg_ReadChar(
> tibemsStreamMsg message,
> tibems_wchar* value );
> tibems_status tibemsStreamMsg_ReadDouble(
> tibemsStreamMsg message,
> tibems_double* value );
> tibems_status tibemsStreamMsg_ReadFloat(
> tibemsStreamMsg message,
> tibems_float* value );
> tibems_status tibemsStreamMsg_ReadInt(
> tibemsStreamMsg message,
> tibems_int* value );
> tibems_status tibemsStreamMsg_ReadLong(
> tibemsStreamMsg message,
> tibems_long* value );
> tibems_status tibemsStreamMsg_ReadShort(
> tibemsStreamMsg message,
> tibems_short* value );
> tibems_status tibemsStreamMsg_ReadString(
> tibemsStreamMsg message,
> char** value );
> COBOL Call
> CALL "tibemsStreamMsg_ReadBoolean"
> USING BY VALUE message,
> BY REFERENCE value,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsStreamMsg_ReadByte"
> USING BY VALUE message,
> BY REFERENCE value,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsStreamMsg_ReadChar"
> USING BY VALUE message,
> BY REFERENCE value,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsStreamMsg_ReadDouble"
> USING BY VALUE message,
> BY REFERENCE value,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsStreamMsg_ReadFloat"
> USING BY VALUE message,
> BY REFERENCE value,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsStreamMsg_ReadInt"
> USING BY VALUE message,
> BY REFERENCE value,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsStreamMsg_ReadLong"
> USING BY VALUE message,
> BY REFERENCE value,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsStreamMsg_ReadShort"
> USING BY VALUE message,
> BY REFERENCE value,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsStreamMsg_ReadString"
> USING BY VALUE message,
> BY REFERENCE value,
> RETURNING tibems-status
> END-CALL.

> | message has usage pointer. value has usage pointer only in tibemsStreamMsg_ReadString (but not in the other calls documented in this group).

> Parameters

> Parameter | Description
> message | Read a field struct from this message.
> value | The function stores a pointer to the field struct in this location.

> Remarks
> 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. (Other read functions are documented on separate pages.)
> See Also
> tibemsStreamMsg_ReadBytes on page 114
> tibemsStreamMsg_ReadField on page 115
> tibemsStreamMsg_ReadBytes
> Function
> Purpose
> Read a byte array from a stream message.
> C Declaration
> tibems_status tibemsStreamMsg_ReadBytes(
> tibemsStreamMsg message,
> void** value,
> tibems_uint* length );
> COBOL Call
> CALL "tibemsStreamMsg_ReadBytes"
> USING BY VALUE message,
> BY REFERENCE value,
> BY REFERENCE size,
> RETURNING tibems-status
> END-CALL.

> | message and value have usage pointer.

> Parameters

> Parameter | Description
> message | Read a byte array from this message.
> value | The function stores a pointer to the byte sequence (within the message) in this location.
> length | The function stores the actual number of bytes read in this location.

> Remarks
> Each call reads bytes from the stream into the byte array, and advances the read position so that the next read call gets the next datum. (Other read functions are documented on separate pages.)
> This call uses the length parameter to return the actual number of bytes read. When the call cannot read even one byte, the length is -1.
> A program that calls this function must call it repeatedly until it returns -1, indicating that the program has extracted the complete set of bytes. Only then may the program call another read function.
> See Also
> tibemsStreamMsg_Read
> tibemsStreamMsg_ReadField on page 115
> tibemsStreamMsg_ReadField
> Function
> Purpose
> Read a field from a stream message.
> C Declaration
> tibems_status tibemsStreamMsg_ReadField(
> tibemsStreamMsg message,
> tibemsMsgField* value );
> COBOL Call
> CALL "tibemsStreamMsg_ReadField"
> USING BY VALUE message,
> BY REFERENCE value,
> RETURNING tibems-status
> END-CALL.

> | message has usage pointer.

> Parameters

> Parameter | Description
> message | Read a field struct from this message.
> value | The function stores a pointer to the field struct in this location.

> Remarks
> Each call reads a field from the stream, and advances the read position so that the next read call gets the next datum. (Other read functions are documented on separate pages.)
> Freeing Fields
> Each successful call to tibemsStreamMsg_ReadField creates a field struct. Field structs can contain data in allocated storage. Programs that call tibemsStreamMsg_ReadField must subsequently call tibemsStreamMsg_FreeField to free that allocated storage.
> See Also
> tibemsStreamMsg_FreeField on page 110
> tibemsStreamMsg_Reset
> Function
> Purpose
> Set the read position to the beginning of the stream, and mark the message body as read-only.
> C Declaration
> tibems_status tibemsStreamMsg_Reset(
> tibemsStreamMsg message );
> COBOL Call
> CALL "tibemsStreamMsg_Reset"
> USING BY VALUE message,
> RETURNING tibems-status
> END-CALL.

> | message has usage pointer.

> Parameters

> Parameter | Description
> message | Reset the read position of 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.
> tibemsStreamMsg_Write
> Function
> Purpose
> Write data to a stream message.
> Single Value
> C Declarations
> tibems_status tibemsStreamMsg_WriteBoolean(
> tibemsStreamMsg message,
> tibems_bool value );
> tibems_status tibemsStreamMsg_WriteByte(
> tibemsStreamMsg message,
> tibems_byte value );
> tibems_status tibemsStreamMsg_WriteChar(
> tibemsStreamMsg message,
> tibems_wchar value );
> tibems_status tibemsStreamMsg_WriteDouble(
> tibemsStreamMsg message,
> tibems_double value );
> tibems_status tibemsStreamMsg_WriteFloat(
> tibemsStreamMsg message,
> tibems_float value );
> tibems_status tibemsStreamMsg_WriteInt(
> tibemsStreamMsg message,
> tibems_int value );
> tibems_status tibemsStreamMsg_WriteLong(
> tibemsStreamMsg message,
> tibems_long value );
> tibems_status tibemsStreamMsg_WriteShort(
> tibemsStreamMsg message,
> tibems_short value );
> tibems_status tibemsStreamMsg_WriteString(
> tibemsStreamMsg message,
> char* value );
> Array
> C Declarations
> tibems_status tibemsStreamMsg_WriteDoubleArray(
> tibemsMsg message,
> const tibems_double* value,
> tibems_int count );
> tibems_status tibemsStreamMsg_WriteFloatArray(
> tibemsMsg message,
> const tibems_float* value,
> tibems_int count );
> tibems_status tibemsStreamMsg_WriteIntArray(
> tibemsMsg message,
> const tibems_int* value,
> tibems_int count );
> tibems_status tibemsStreamMsg_WriteLongArray(
> tibemsMsg message,
> const tibems_long* value,
> tibems_int count );
> tibems_status tibemsStreamMsg_WriteShortArray(
> tibemsMsg message,
> const tibems_short* value,
> tibems_int count );
> Nested Message C Declarations
> tibems_status tibemsStreamMsg_WriteMapMsg(
> tibemsMsg message,
> tibemsMsg value );
> tibems_status tibemsStreamMsg_WriteStreamMsg(
> tibemsMsg message,
> tibemsMsg value );

> | Nested messages are an extension of the JMS specification. Programs that use this feature are non-compliant.

> COBOL Call
> CALL "tibemsStreamMsg_WriteBoolean"
> USING BY VALUE message,
> BY VALUE value,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsStreamMsg_WriteByte"
> USING BY VALUE message,
> BY VALUE value,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsStreamMsg_WriteChar"
> USING BY VALUE message,
> BY VALUE value,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsStreamMsg_WriteDouble"
> USING BY VALUE message,
> BY VALUE value,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsStreamMsg_WriteDoubleArray"
> USING BY VALUE message,
> BY REFERENCE value,
> BY VALUE count,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsStreamMsg_WriteFloat"
> USING BY VALUE message,
> BY VALUE value,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsStreamMsg_WriteFloatArray"
> USING BY VALUE message,
> BY REFERENCE value,
> BY VALUE count,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsStreamMsg_WriteInt"
> USING BY VALUE message,
> BY VALUE value,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsStreamMsg_WriteIntArray"
> USING BY VALUE message,
> BY REFERENCE value,
> BY VALUE count,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsStreamMsg_WriteLong"
> USING BY VALUE message,
> BY VALUE value,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsStreamMsg_WriteLongArray"
> USING BY VALUE message,
> BY REFERENCE value,
> BY VALUE count,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsStreamMsg_WriteMapMsg"
> USING BY VALUE message,
> BY VALUE value,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsStreamMsg_WriteShort"
> USING BY VALUE message,
> BY VALUE value,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsStreamMsg_WriteShortArray"
> USING BY VALUE message,
> BY REFERENCE value,
> BY VALUE count,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsStreamMsg_WriteStreamMsg"
> USING BY VALUE message,
> BY VALUE value,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsStreamMsg_WriteString"
> USING BY VALUE message,
> BY REFERENCE value,
> RETURNING tibems-status
> END-CALL.

> | message has usage pointer. value has usage pointer only in tibemsStreamMsg_WriteStreamMsg and tibemsStreamMsg_WriteMapMsg (but not in the other calls documented in this group).

> Parameters

> Parameter | Description
> message | Write a datum to this stream message.
> value | Write this datum. Arrays must not be null.
> count | Array functions set array values of this size.

> Remarks
> 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.
> See Also
> tibemsStreamMsg_WriteBytes on page 121
> tibemsStreamMsg_WriteBytes
> Function
> Purpose
> Write bytes from a byte array to a stream message.
> C Declaration
> tibems_status tibemsStreamMsg_WriteBytes(
> tibemsStreamMsg message,
> void* value,
> tibems_uint length );
> COBOL Call
> CALL "tibemsStreamMsg_WriteBytes"
> USING BY VALUE message,
> BY REFERENCE value,
> BY VALUE length,
> RETURNING tibems-status
> END-CALL.

> | message has usage pointer.

> Parameters

> Parameter | Description
> message | Write to the byte stream of this message.
> value | Copy bytes from this byte array to the message.
> length | Write this number of bytes from the byte array to the message.

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

Copyright © TIBCO Software Inc. All Rights Reserved.