Chapter 2 Messages : tibemsStreamMsg

tibemsStreamMsg
Type
Purpose
A message containing a stream of data items.
Related Types
tibemsMsg on page 21
 
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.
 
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
 
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
 
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
 
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
 
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
 
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
 
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 );
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
 
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
 
Remarks
Each call writes bytes from the byte array into the stream, and advances the write position.