Messages : tibemsBytesMsg

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.
 
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
 
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
 
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
 
Your program must not change the bytes, which belong to the message; if you must modify the bytes, make a private copy first.
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
 
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.
 
tibemsBytesMsg_ReadUnsignedShort
See Also
tibemsBytesMsg_ReadBytes on page 81
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
 
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.
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
 
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
 
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
 
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.
 
This function writes true as (byte)1, and false as (byte)0.
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.
See Also
tibemsBytesMsg_WriteBytes on page 88
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
 
Remarks
Each call writes bytes from the byte array into the stream, and advances the write position.