Message API

A C8_MESSAGE_TYPE describes whether a message is entering or exiting an internal window.

Most adapters will use C8_MESSAGE_POSITIVE for all messages. A normal message is a positive message. In other words, it corresponds to a row of data in the stream.

The other types of messages are not currently intended for use with adapters.

In general, when a "const *" is returned for data associated with an object (for example, a schema associated with a message), the validity of the returned pointer is limited to the lifetime of the pointer's owner (for example, the message). Attempts to de-reference the pointer after the owner no longer exists may result in a runtime exception.

• C8Message* C8MessageCreate(enum C8_MESSAGE_TYPES msg_type, const C8Schema *schema_ptr) – Purpose: Creates an empty message of the specified message type with the specified schema. This is the initial call in composing a message.

  Parameters:

  • msg_type: In almost all cases, this is C8_MESSAGE_POSITIVE. For a list of other message types, see the definition of C8_MESSAGE_TYPES in the file c8messages.h.

  • schema_ptr : A pointer to the schema that you want to define the structure of the message.

  Returns: A pointer to the newly created message. When you are done using this message, destroy it by passing it to C8MessageDestroy() .

  See also the function C8MessageCreateWithSize() below.

• C8Message* C8MessageCreateWithSize(enum C8_MESSAGE_TYPES msg_type, const C8Schema *schema_ptr, C8UInt fields_size) – Purpose: Creates an empty message of the specified message type with the specified schema and with the amount of memory allocated. This is the initial call in composing a message. By specifying the size of the entire message, performance may be increased.

  Parameters:

  • msg_type: In almost all cases, this is C8_MESSAGE_POSITIVE. For a list of other message types, see the definition of C8_MESSAGE_TYPES in the file c8messages.h.

  • schema_ptr: A pointer to the schema you want to define the structure of the message.

  • field_size: A user estimated size of the entire message.

  To calculate the fields_size, sum up the sizes of all of the fields, where the size of each field is the number of bytes of data stored in the field rounded to the closest larger multiple of 4, plus 4 bytes. For example, if you have a value that requires 5 bytes, then the total size for that field is 8 + 4 (5 rounded up to 8, plus 4) - a total of 12 bytes.

  Estimates that are greater than the actual resulting messages size will result in unused memory. Estimates that are too low will result in automatic adjustments upward to the correct message size. Adjustments upward in size may decrease performance.

  Returns: A pointer to the newly created message. When you are done using this message, you must destroy it by passing it to C8MessageDestroy().

  See also the function C8MessageCreate().

  void C8MessageDestroy(C8Message *msg_ptr)

  Purpose: Destroys the message pointed to by msg_ptr. All messages created by the user or received by the C8AdapterReceiveMessage() or C8AdapterReceiveMessageWait() call must be destroyed after it has been dispatched to the Sybase CEP Serveror else a memory leak will occur.

  Parameters:

  • msg_ptr: A pointer to the message to be destroyed (de-callocated).

  Returns: Nothing.

• enum C8_MESSAGE_TYPES C8MessageGetType(const C8Message *msg_ptr) – Purpose: The message type is returned. There are three different categories of messages. There are positive messages, which are simply normal messages. There are also negative messages, which represent rows removed from window. The third category of message is control messages. Some of these are only used internally, and you are unlikely to see them or have to deal with them.

  Messages sometimes arrive in "bundles". The beginning of a bundle is marked by a special start-of-bundle control message (for which C8MessageGetType() returns C8_MESSAGE_START_BUNDLE) and the end of a bundle is marked with a special end-of-bundle control message (for which C8MessageGetType() returns C8_MESSAGE_END_BUNDLE). If you need to handle bundled messages differently from individual messages, you can determinethe start and end of a bundle by recognizing these messages. If you don't need to deal with bundled messages differently from how you deal with individual messages, then you can simply ignore all messages for which C8MessageGetType() returns C8_MESSAGE_START_BUNDLE and C8_MESSAGE_END_BUNDLE.

  Parameters:

  • msg_ptr: A pointer to the message for which you want to know the type.

  Returns: The message type. For a list of the valid message types, see the declaration of C8_MESSAGE_TYPES in the file c8messages.h.

• C8MessageID C8MessageGetID(const C8Message* i_msg) – Purpose: Given a message, return the ID of that message. Useful when you want to mirror a master window, so that you can identify which row to remove from the mirror when a negative message arrives. The ID of the negative message matches the ID of the original positive message. See "Create Window Statement" in the for more information about master and mirror windows.

  Parameters:

  • i_msg: A pointer to the message for which you want to know the ID.

  Returns: The message ID.

  const C8Schema *C8MessageGetSchema(const C8Message *msg_ptr)

  Purpose: Given a message, return the associated schema. This is useful after C8AdapterReceiveMessage() or C8AdapterReceiveMessageWait() provides a message that you wish to process depending upon the schema.

  Parameters:

  • msg_ptr: A pointer to the message for which you want to know the schema.

  Returns: A pointer to the schema. Do not change the memory that the pointer points to, and do not C8Free() this pointer. The lifetime of the returned pointer is limited to the lifetime of the pointer's owner (in this case, the message).

• C8Timestamp C8MessageGetMessageTimestamp(const C8Message* msg_ptr) – Purpose: Given a message, return the associated row timestamp. This is the row timestamp of the message, not one of the timestamps in the data columns.

  Parameters:

  • msg_ptr: a pointer to the message for which you want to know the row timestamp.

  Returns: The row timestamp of the message.

  void C8MessageSetMessageTimestamp(C8Message* msg_ptr, C8Timestamp i_timestamp)

  Purpose: Set the row timestamp of the message to i_timestamp. This is the row timestamp of the message and not the timestamp in any columns in the message.

  Parameters:

  • msg_ptr: The message whose row timestamp you want to set.

  • i_timestamp: The timestamp that you want to set the row timestamp to.

  Returns: ##########################

• C8Status C8MessageColumnIsNull(const C8Message* msg_ptr, C8UInt col_ndx, C8Bool *o_res) – Purpose: For a given message, determines if the column specified by col_ndx is a NULL value or not. Always check for a NULL entry for each column before attempting to read a value from that column, or check the returned status after reading a value from a column.

  Parameters:

  • msg_ptr: A pointer to the message that contains the column.

  • col_ndx: The index number of the desired column within the message. Note that the index is 0-based, not 1-based, and thus valid values range from 0 to N-1 where N is the number of columns in the message.

  • o_res: This variable is set to C8_TRUE if the column is NULL, C8_FALSE otherwise.

  Returns: C8_OK if success, C8_FAIL otherwise.

• C8Status C8MessageColumnIsNullByName(const C8Message* msg_ptr, const C8CHAR *i_fldnm, C8Bool *o_res) – Purpose: For a given message, determines if the column whose name is specified in i_fldnm contains a NULL value or not. Always check for a NULL entry for each column before attempting to read a value from that column.

  Parameters:

  • msg_ptr: A pointer to the message that contains the column you want to check.

  • i_fldnm: The name of the column you want to check.

  • o_res : A pointer to a boolean that is set to C8_TRUE if the column has NULL and C8_FALSE otherwise.

  Returns: C8_OK if success, C8_FAIL otherwise.

• C8Status C8MessageColumnSetToNull(C8Message *msg_ptr, C8UInt col_ndx) – Purpose: Set the column indicated by col_ndx to NULL.

  Parameters:

  • msg_ptr: A pointer to the message containing the column that you want to set to NULL.

  • col_ndx: The index number of the desired column within the message. The index is 0-based, not 1-based, and thus valid values range from 0 to N-1 where N is the number of columns in the message.

  Returns: C8_OK if success, C8_FAIL otherwise.

• C8Status C8MessageColumnSetToNullByName(C8Message *msg_ptr, const C8Char *i_fldnm) – Purpose: Given a message and column name (i_fldnm) within that message, set that column to NULL.

  Parameters:

  • msg_ptr: A pointer to the message.

  • i_fldnm: The name of the field to set to NULL.

  Returns: C8_OK on success, C8_FAIL otherwise.

• C8Status C8MessageColumnGetAsString(const C8Message *i_msg, C8UInt i_ndx, C8Char **o_res) – Purpose: Given a message and the index of a column in that message, return the value of the column in the form of a string. o_res is set to point to that string. When you are done with the string, free it with C8Free().

  Parameters:

  • i_msg: A pointer to a message.

  • i_ndx: Indicates which column you want to retrieve the value from. Column numbers start at 0, not 1.

  • o_res: A pointer to a location that can store a pointer to the string that is retrieved.

  Returns: C8_OK on success, C8_FAIL otherwise. The string returned by this function must be freed by the user with the C8Free() function.

• C8Status C8MessageColumnGetAsStringByName(const C8Message *i_msg, const C8Char *i_fldnm, C8Char **o_res) – Purpose: Given a message and the name of a column in that message, return the value of the column in the form of a string. o_res is set to point to that string. When you are done with the string, free it with C8Free() .

  Parameters:

  • i_msg: The message from which you want to extract the data.

  • i_fldnm: The name of the field/column to get the data from.

  • o_res: A pointer to a string; the function will set this pointer to point to the string retrieved.

  Returns: C8_OK on success, C8_FAIL otherwise. The string returned by this function must be freed by the user with the C8Free() function.

• C8Status C8MessageColumnGetInt(const C8Message *msg_ptr, C8UInt col_ndx, C8Int *o_res) – Purpose: Given a message pointer, a column index, and a pointer o_res to a place to store a C8Int, put the column's value in the location pointed to by o_res.

  Prior to using this function on a column for the first time, ensure that the desired data type is indeed stored at col_ndx by calling C8SchemaGetColumnType(). Before retrieving each row's value, ensure that the field contains a value by calling C8MessageColumnIsNull().

  Parameters:

  • msg_ptr: The message from which you want to extract the data.

  • col_ndx: Indicates which column to retrieve data from. Column numbers start from 0, not 1.

  • o_res: A pointer to a location that can hold the C8Int value retrieved by the function.

  Returns: C8_OK on success, C8_FAIL otherwise.

• C8Status C8MessageColumnGetLong(const C8Message *msg_ptr, C8UInt col_ndx, C8Long *o_res) – Purpose: Given a message pointer, a column index, and a pointer o_res to a place to store a C8Long, put the column's value in the location pointed to by o_res.

  Prior to using this function on a column for the first time, ensure that the desired data type is stored at col_ndx by calling C8SchemaGetColumnType(). Before retrieving each row's value, ensure that the field contains a value by calling C8MessageColumnIsNull().

  Parameters:

  • msg_ptr: The message from which you want to extract the data.

  • col_ndx: Indicates which column to retrieve data from. Column numbers start from 0, not 1.

  • o_res: A pointer to a location that can hold the C8Long value retrieved by the function.

  Returns: C8_OK on success, C8_FAIL otherwise.

• C8Status C8MessageColumnGetFloat(const C8Message *msg_ptr, C8UInt col_ndx, C8Float *o_res) – Purpose: Given a message pointer, a column index, and a pointer o_res to a place to store a C8Float, put the column's value in the location pointed to by o_res.

  Prior to using this function on a column for the first time, ensure that the desired data type is indeed stored at col_ndx by calling C8SchemaGetColumnType(). Before retrieving each row's value, ensure that the field contains a value by calling C8MessageColumnIsNull().

  Parameters:

  • msg_ptr: The message from which you want to extract the data.

  • col_ndx: Indicates which column to retrieve data from. Column numbers start from 0, not 1.

  • o_res: A pointer to a location that can hold the C8Float value retrieved by the function.

  Returns: C8_OK on success, C8_FAIL otherwise.

• C8Status C8MessageColumnGetBool(const C8Message *msg_ptr, C8UInt col_ndx, C8Bool *o_res) – Purpose: Given a message pointer, a column index, and a pointer o_res to a place to store a C8Bool, put the column's value in the location pointed to by o_res.

  Prior to using this function on a column for the first time, ensure that the desired data type is indeed stored at col_ndx by calling C8SchemaGetColumnType(). Before retrieving each row's value, ensure that the field contains a value by calling C8MessageColumnIsNull().

  Parameters:

  • msg_ptr: The message from which you want to extract the data.

  • col_ndx: Indicates which column to retrieve data from. Column numbers start from 0, not 1.

  • o_res: A pointer to a location that can hold the C8Bool value retrieved by the function.

  Returns: C8_OK on success, C8_FAIL otherwise.

• C8Status C8MessageColumnGetTimestamp(const C8Message *msg_ptr, C8UInt col_ndx, C8Timestamp *o_res) – Purpose: Given a message pointer, a column index, and a pointer o_res to a place to store a C8Timestamp, put the column's value in the location pointed to by o_res.

  Prior to using this function on a column for the first time, ensure that the desired data type is indeed stored at col_ndx by calling C8SchemaGetColumnType(). Before retrieving each row's value, ensure that the field contains a value by calling C8MessageColumnIsNull().

  Parameters:

  • msg_ptr: The message from which you want to extract the data.

  • col_ndx: Indicates which column to retrieve data from. Column numbers start from 0, not 1.

  • o_res: A pointer to a location that can hold the C8Timestamp value retrieved by the function.

  Returns: C8_OK on success, C8_FAIL otherwise.

• C8Status C8MessageColumnGetInterval(const C8Message *msg_ptr, C8UInt col_ndx, C8Interval *o_res) – Purpose: Given a message pointer, a column index, and a pointer o_res to a place to store a C8Interval, put the column's value in the location pointed to by o_res.

  Prior to using this function on a column for the first time, ensure that the desired data type is indeed stored at col_ndx by calling C8SchemaGetColumnType(). Before retrieving each row's value, ensure that the field contains a value by calling C8MessageColumnIsNull().

  Parameters:

  • msg_ptr: The message from which you want to extract the data.

  • col_ndx: Indicates which column to retrieve data from. Column numbers start from 0, not 1.

  • o_res: A pointer to a location that can hold the C8Interval value retrieved by the function.

  Returns: C8_OK on success, C8_FAIL otherwise.

• C8Status C8MessageColumnGetString(const C8Message *msg_ptr, C8UInt col_ndx, const C8Char **o_res) – Purpose: Given a message pointer and column index, set o_res to the C8Char* stored in that message. Do not C8Free the returned pointer as this pointer points to a part of the message. The pointer to the string is valid as long as the pointer to the message is valid.

  Prior to using this function on a column for the first time, ensure that the desired data type is indeed stored at col_ndx by calling C8SchemaGetColumnType(). Before retrieving each row's value, ensure that the field contains a value by calling C8MessageColumnIsNull() .

  Parameters:

  • msg_ptr: The message from which you want to extract the data.

  • col_ndx: Indicates which column to retrieve data from. Column numbers start from 0, not 1.

  • o_res: A pointer to a location that can hold a pointer to the string (C8Char *) value retrieved by the function.

  Returns: C8_OK on success, C8_FAIL otherwise.

• C8Status C8MessageColumnGetBlob(const C8Message *msg_ptr, C8UInt col_ndx, const C8Blob **o_res, C8UInt *o_sz) – Purpose: Given a message pointer and a column index, set o_res to the C8Blob * stored in that message, and set o_sz to the number of bytes in that BLOB. Do not C8Free() the returned pointer as this pointer points to a part of the message. The pointer to the BLOB is valid as long as the pointer to the message is valid.

  Prior to using this function on a column for the first time, ensure that the desired data type is indeed stored at col_ndx by calling C8SchemaGetColumnType(). Before retrieving each row's value, ensure that the field contains a value by calling C8MessageColumnIsNull().

  Parameters:

  • msg_ptr: The message from which you want to extract the data.

  • col_ndx: Indicates which column to retrieve data from. Column numbers start from 0, not 1.

  • o_res: A pointer to a location that can hold a pointer to the BLOB value retrieved by the function.

  • o_sz: The function stores the length of the blob in the location pointed to by o_sz.

  Returns: C8_OK on success, C8_FAIL otherwise.

  The retrieved value is a "raw" BLOB (as opposed to a hex string or a base64 string). For an explanation of raw vs. hex string vs. base64 string formats, see "Data Types and Subroutines for UDFs and In-Process Adapters".

• C8Status C8MessageColumnGetBlobAsBase64String(const C8Message *msg_ptr, C8UInt col_ndx, const C8Blob **o_res) – Purpose: Given a message pointer and a column index, return a pointer to a string that contains the base64 representation of the BLOB.

  Prior to using this function on a column for the first time, ensure that the desired data type is indeed stored at col_ndx by calling C8SchemaGetColumnType(). Before retrieving each row's value, ensure that the field contains a value by calling C8MessageColumnIsNull() .

  Parameters:

  • msg_ptr: The message from which you want to extract the data.

  • col_ndx: Indicates which column to retrieve data from. Column numbers start from 0, not 1.

  • o_res: A pointer to a location that can hold a pointer to the BLOB value retrieved by the function.

  Returns: C8_OK on success, C8_FAIL otherwise.

  The returned value is in a "base64 string" format (as opposed to a hex string or a raw BLOB). For an explanation of raw vs. hex string vs. base64 string formats, see "Data Types and Subroutines for UDFs and In-Process Adapters".

• C8Status C8MessageColumnGetXmlAsString(const C8Message *msg_ptr, C8UInt col_ndx, const C8Char **o_res) – Purpose: Given a message pointer and a column index, set o_res to point to a copy of the XML value represented as a string. When you are done using the XML value, C8Free() the string. Note that this is different from what you do for a C8String or C8Blob.

  Prior to using this function on a column for the first time, ensure that the desired data type is indeed stored at col_ndx by calling C8SchemaGetColumnType(). Before retrieving each row's value, ensure that the field contains a value by calling C8MessageColumnIsNull() .

  Parameters:

  • msg_ptr: The message from which you want to extract the data.

  • col_ndx: Indicates which column to retrieve data from. Column numbers start from 0, not 1.

  • o_res: A pointer to a location that can hold a pointer to the string value retrieved by the function.

  Returns: C8_OK on success, C8_FAIL otherwise.

• C8Status C8MessageColumnGetIntByName(const C8Message *msg_ptr, const C8Char *i_fldnm, C8Int *o_res) – Purpose: Given a message pointer, a column name, and a pointer o_res to a place to store a C8Int, put the column's value in the location pointed to by o_res.

  Prior to using this function on a column for the first time, ensure that the desired data type is indeed stored at col_ndx by calling C8SchemaGetColumnType(). Before retrieving each row's value, ensure that the field contains a value by calling C8MessageColumnIsNull().

  Parameters:

  • msg_ptr: The message from which you want to extract the data.

  • i_fldnm: Indicates which column to retrieve data from.

  • o_res: A pointer to a location that can hold the C8Int (integer) value retrieved by the function.

  Returns: C8_OK on success, C8_FAIL otherwise.

• C8Status C8MessageColumnGetLongByName(const C8Message *msg_ptr, const C8Char *i_fldnm, C8Long *o_res) – Purpose: Given a message pointer, a column name, and a pointer o_res to a place to store a C8Long, put the column's value in the location pointed to by o_res.

  Prior to using this function on a column for the first time, ensure that the desired data type is indeed stored at col_ndx by calling C8SchemaGetColumnType(). Before retrieving each row's value, ensure that the field contains a value by calling C8MessageColumnIsNull().

  Parameters:

  • msg_ptr: The message from which you want to extract the data.

  • i_fldnm: Indicates which column to retrieve data from.

  • o_res: A pointer to a location that can hold the C8Long value retrieved by the function.

  Returns: C8_OK on success, C8_FAIL otherwise.

• C8Status C8MessageColumnGetFloatByName(const C8Message *msg_ptr, const C8Char *i_fldnm, C8Float *o_res) – Purpose: Given a message pointer, a column name, and a pointer o_res to a place to store a C8Float, put the column's value in the location pointed to by o_res.

  Prior to using this function on a column for the first time, ensure that the desired data type is indeed stored at col_ndx by calling C8SchemaGetColumnType(). Before retrieving each row's value, ensure that the field contains a value by calling C8MessageColumnIsNull().

  Parameters:

  • msg_ptr: The message from which you want to extract the data.

  • i_fldnm: Indicates which column to retrieve data from.

  • o_res: A pointer to a location that can hold the C8Float value retrieved by the function.

  Returns: C8_OK on success, C8_FAIL otherwise.

• C8Status C8MessageColumnGetBoolByName(const C8Message *msg_ptr, const C8Char *i_fldnm, C8Bool *o_res) – Purpose: Given a message pointer, a column name, and a pointer o_res to a place to store a C8Bool, put the column's value in the location pointed to by o_res.

  Prior to using this function on a column for the first time, ensure that the desired data type is indeed stored at col_ndx by calling C8SchemaGetColumnType(). Before retrieving each row's value, ensure that the field contains a value by calling C8MessageColumnIsNull().

  Parameters:

  • msg_ptr: The message from which you want to extract the data.

  • i_fldnm: Indicates which column to retrieve data from.

  • o_res: A pointer to a location that can hold the C8Bool value retrieved by the function.

  Returns: C8_OK on success, C8_FAIL otherwise.

• C8Status C8MessageColumnGetTimestampByName(const C8Message *msg_ptr, const C8Char *i_fldnm, C8Timestamp *o_res) – Purpose: Given a message pointer, a column name, and a pointer o_res to a place to store a C8Timestamp, put the column's value in the location pointed to by o_res.

  Prior to using this function on a column for the first time, ensure that the desired data type is indeed stored at col_ndx by calling C8SchemaGetColumnType(). Before retrieving each row's value, ensure that the field contains a value by calling C8MessageColumnIsNull().

  Parameters:

  • msg_ptr: The message from which you want to extract the data.

  • i_fldnm: Indicates which column to retrieve data from.

  • o_res: A pointer to a location that can hold the C8Timestamp value retrieved by the function.

  Returns: C8_OK on success, C8_FAIL otherwise.

• C8Status C8MessageColumnGetIntervalByName(const C8Message *msg_ptr, const C8Char *i_fldnm, C8Interval *o_res) – Purpose: Given a message pointer, a column name, and a pointer o_res to a place to store a C8Interval, put the column's value in the location pointed to by o_res.

  Prior to using this function on a column for the first time, ensure that the desired data type is indeed stored at col_ndx by calling C8SchemaGetColumnType(). Before retrieving each row's value, ensure that the field contains a value by calling C8MessageColumnIsNull().

  Parameters:

  • msg_ptr: The message from which you want to extract the data.

  • i_fldnm; Indicates which column to retrieve data from.

  • o_res: A pointer to a location that can hold the C8Interval value retrieved by the function.

  Returns: C8_OK on success, C8_FAIL otherwise.

• C8Status C8MessageColumnGetStringByName(const C8Message *msg_ptr, const C8Char *i_fldnm, const C8Char **o_res) – Purpose: Given a message pointer and column name, set o_res to the C8Char* stored in that message. Do not C8Free() the returned pointer as this pointer points to a part of the message. The pointer to the string is valid as long as the pointer to the tuple is valid.

  Prior to using this function on a column for the first time, ensure that the desired data type is indeed stored at col_ndx by calling C8SchemaGetColumnType(). Before retrieving each row's value, ensure that the field contains a value by calling C8MessageColumnIsNull().

  Parameters:

  • msg_ptr: The message from which you want to extract the data.

  • i_fldnm: Indicates which column to retrieve data from.

  • o_res: A pointer to a location that can hold a pointer to the string (C8Char *) value retrieved by the function.

  Returns: C8_OK on success, C8_FAIL otherwise.

• C8Status C8MessageColumnGetBlobByName(const C8Message *msg_ptr, const C8Char *i_fldnm, const C8Blob **o_res, C8UInt *o_sz) – Purpose: Given a message pointer and a column name, set o_res to the C8Blob * stored in that message, and set o_sz to the number of bytes in that BLOB. Do not C8Free() the returned pointer as this pointer points to a part of the message.

  Prior to using this function on a column for the first time, ensure that the desired data type is indeed stored at col_ndx by calling C8SchemaGetColumnType(). Before retrieving each row's value, ensure that the field contains a value by calling C8MessageColumnIsNull().

  Parameters:

  • msg_ptr: The message from which you want to extract the data.

  • i_fldnm: Indicates which column to retrieve data from.

  • o_res: A pointer to a location that can hold a pointer to the BLOB value retrieved by the function.

  • o_sz: The function stores the length of the blob in the location pointed to by o_sz.

  Returns: C8_OK on success, C8_FAIL otherwise.

  The retrieved blob is a "raw" blob (as opposed to a hex string or a base64 string). For an explanation of raw vs. hex string vs. base64 string formats, see "Data Types and Subroutines for UDFs and In-Process Adapters".

• C8Status C8MessageColumnGetXmlAsStringByName(const C8Message *msg_ptr, const C8Char *i_fldnm, const C8Char **o_res) – Purpose: Given a message pointer and a column name, set o_res to point to a copy of the XML value represented as a string. When you are done using the XML value, C8Free() the string. Note that this is different from what you do for a C8String or C8Blob.

  Prior to using this function on a column for the first time, ensure that the desired data type is indeed stored at col_ndx by calling C8SchemaGetColumnType(). Before retrieving each row's value, ensure that the field contains a value by calling C8MessageColumnIsNull().

  Parameters:

  • msg_ptr: The message from which you want to extract the data.

  • i_fldnm: Indicates which column to retrieve data from.

  • o_res: A pointer to a location that can hold a pointer to the string value retrieved by the function.

  Returns: C8_OK on success, C8_FAIL otherwise.

• C8Status C8MessageColumnSetInt(C8Message *msg_ptr, C8UInt col_ndx, C8Int value) – Purpose: Given a message pointer and a column index, set the value in the message to the indicated value. If the column type in the message is not a C8Int, the results are undefined and an error is logged. If the col_ndx is out of range, the set is ignored and an error message is logged.

  Parameters:

  • msg_ptr: The message from which you want to extract the data.

  • col_ndx: Indicates which column to retrieve data from. Column numbers start from 0, not 1.

  • value: The value to store in the message.

  Returns: C8_OK on success, C8_FAIL otherwise.

• C8Status C8MessageColumnSetLong(C8Message *msg_ptr, C8UInt col_ndx, C8Long value) – Purpose: Given a message pointer and a column index, set the value in the message to the indicated value. If the column type in the message is not a C8Long, the results are undefined and an error is logged. If the col_ndx is out of range, the set is ignored and an error message is logged.

  Parameters:

  • msg_ptr: The message from which you want to extract the data.

  • col_ndx: Indicates which column to retrieve data from. Column numbers start from 0, not 1.

  • value: The value to store in the message.

  Returns: C8_OK on success, C8_FAIL otherwise.

• C8Status C8MessageColumnSetFloat(C8Message *msg_ptr, C8UInt col_ndx, C8Float value) – Purpose: Given a message pointer and a column index, set the value in the message to the indicated value. If the column type in the message is not a C8Float, the results are undefined and an error is logged. If the col_ndx is out of range, the set is ignored and an error message is logged.

  Parameters:

  • msg_ptr: The message from which you want to extract the data.

  • col_ndx: Indicates which column to retrieve data from. Column numbers start from 0, not 1.

  • value: The value to store in the message.

  Returns: C8_OK on success, C8_FAIL otherwise.

• C8Status C8MessageColumnSetBool(C8Message *msg_ptr, C8UInt col_ndx, C8Bool value) – Purpose: Given a message pointer and a column index, set the value in the message to the indicated value. If the column type in the message is not a C8Bool, the results are undefined and an error is logged. If the col_ndx is out of range, the set is ignored and an error message is logged.

  Parameters:

  • msg_ptr: The message from which you want to extract the data.

  • col_ndx: Indicates which column to retrieve data from. Column numbers start from 0, not 1.

  • value: The value to store in the message.

  Returns: C8_OK on success, C8_FAIL otherwise.

• C8Status C8MessageColumnSetTimestamp(C8Message *msg_ptr, C8UInt col_ndx, C8Timestamp value) – Purpose: Given a message pointer and a column index, set the value in the message to the indicated value. If the column type in the message is not a C8Timestamp, the results are undefined and an error is logged. If the col_ndx is out of range, the set is ignored and an error message is logged.

  Parameters:

  • msg_ptr: The message from which you want to extract the data.

  • col_ndx: Indicates which column to retrieve data from. Column numbers start from 0, not 1.

  • value: The value to store in the message.

  Returns: C8_OK on success, C8_FAIL otherwise.

• C8Status C8MessageColumnSetInterval(C8Message *msg_ptr, C8UInt col_ndx, C8Interval value) – Purpose: Given a message pointer and a column index, set the value in the message to the indicated value. If the column type in the message is not a C8Interval, the results are undefined and an error is logged. If the col_ndx is out of range, the set is ignored and an error message is logged.

  Parameters:

  • msg_ptr: The message from which you want to extract the data.

  • col_ndx: Indicates which column to retrieve data from. Column numbers start from 0, not 1.

  • value : The value to store in the message.

  Returns: C8_OK on success, C8_FAIL otherwise.

• C8Status C8MessageColumnSetString(C8Message *msg_ptr, C8UInt col_ndx, C8Char* value) – Purpose: Given a message pointer and a column index, set the column in the message to the indicated value. If the data type of the column is not C8Char *, the results are undefined and an error is logged. If the col_ndx is out of range, the set is ignored and an error message is logged.

  If the pointer named "value" was obtained through C8Malloc(), the user must free the pointer (via C8Free()) after calling C8AdapterSendMessage() to prevent a memory leak. (The C8MessageColumnSetString() routine will make a copy of the value, so freeing that value does not cause the server to lose access to the information.)

  Parameters:

  • msg_ptr: The message from which you want to extract the data.

  • col_ndx: Indicates which column to retrieve data from. Column numbers start from 0, not 1.

  • value: The value to store in the message.

  Returns: C8_OK on success, C8_FAIL otherwise.

• C8Status C8MessageColumnSetBlob(C8Message *msg_ptr, C8UInt col_ndx, const C8Blob *i_buf, C8UInt i_sz) – Purpose: Given a message pointer and a column index, set the column in the message to the indicated value. If the data type of the column is not C8Blob *, the results are undefined and an error is logged. If the col_ndx is out of range, the set is ignored and an error message is logged.

  If the i_buf pointer was obtained through C8Malloc(), the user must free the pointer via C8Free() after C8AdapterSendMessage() to prevent a memory leak. (The C8MessageColumnSetBlob() routine will make a copy of the value, so freeing that value does not cause the server to lose access to the information.)

  Note that the i_buf parameter should contain the original data value - do not convert the data to a string of hexadecimal values first. The function will do this for you. Note that since converting the data to a hexadecimal string will require 2N + 1 bytes (2 hex digits for each byte of the original data, plus a null byte as a string terminator), and since the longest allowable string is 4GB, the longest blob you can put in is 2GB - 1 bytes.

  Parameters:

  • msg_ptr: The message from which you want to extract the data.

  • col_ndx: Indicates which column to retrieve data from. Column numbers start from 0, not 1.

  • i_buf: The BLOB value to store in the message. The value is a "raw" BLOB (as opposed to a hex string or a base64 string). For an explanation of raw vs. hex string vs. base64 string formats, see "Data Types and Subroutines for UDFs and In-Process Adapters".

  • i_sz: The number of bytes in the BLOB.

  Returns: C8_OK on success, C8_FAIL otherwise.

• C8Status C8MessageColumnSetBlobFromBase64String(C8Message *msg_ptr, C8UInt col_ndx, const C8Char *i_base64_string) – Purpose: Given a message pointer and a column index, set the column in the message to the indicated value. If the data type of the column is not C8Blob *, the results are undefined and an error is logged. If the col_ndx is out of range, the set is ignored and an error message is logged.

  If the i_base64_string pointer was obtained through C8Malloc(), the user must free the pointer via C8Free() after C8AdapterSendMessage() to prevent a memory leak. (The C8MessageColumnSetBlob() routine will make a copy of the value, so freeing that value does not cause the server to lose access to the information.)

  Parameters:

  • msg_ptr: The message from which you want to extract the data.

  • col_ndx: Indicates which column to retrieve data from. Column numbers start from 0, not 1.

  • value: The BLOB value to store in the message. The value is a "raw" BLOB (as opposed to a hex string or a base64 string). For an explanation of raw vs. hex string vs. base64 string formats, see "Data Types and Subroutines for UDFs and In-Process Adapters".

  Returns: C8_OK on success, C8_FAIL otherwise.

• C8Status C8MessageColumnSetXmlFromString(C8Message *msg_ptr, C8UInt col_ndx, C8Char* value) – Purpose: Given a message pointer and a column index, set the column in the message to the indicated value. If the data type of the column is not a C8Char *, the results are undefined and an error is logged. If the col_ndx is out of range, the set is ignored and an error message is logged.

  If the value pointer was obtained through C8Malloc(), the user must free the pointer (via C8Free()) after C8AdapterSendMessage() to prevent a memory leak. (The C8MessageColumnSetXmlFromString() routine will make a copy of the value, so freeing that value does not cause the server to lose access to the information.)

  Parameters:

  • msg_ptr: The message from which you want to extract the data.

  • col_ndx: Indicates which column to retrieve data from. Column numbers start from 0, not 1.

  • value: The value to store in the message.

  Returns: C8_OK on success, C8_FAIL otherwise.

• C8Status C8MessageColumnSetIntByName(C8Message *msg_ptr, const C8Char *i_fldnm, C8Int value) – Purpose: Given a message pointer and a column name, set the value in the message to the indicated value. If the schema type in the message is not a C8Int, the results are undefined and an error is logged. If the col_ndx is out of range, the set is ignored and an error message is logged.

  Parameters:

  • msg_ptr: The message from which you want to extract the data.

  • col_ndx: Indicates which column to retrieve data from. Column numbers start from 0, not 1.

  • value: The value to store in the message.

  Returns: C8_OK on success, C8_FAIL otherwise.

• C8Status C8MessageColumnSetLongByName(C8Message *msg_ptr, const C8Char *i_fldnm, C8Long value) – Purpose: Given a message pointer and a column name, set the value in the message to the indicated value. If the schema type in the message is not a C8Long, the results are undefined and an error is logged. If the col_ndx is out of range, the set is ignored and an error message is logged.

  Parameters:

  • msg_ptr: The message from which you want to extract the data.

  • col_ndx: Indicates which column to retrieve data from. Column numbers start from 0, not 1.

  • value: The value to store in the message.

  Returns: C8_OK on success, C8_FAIL otherwise.

• C8Status C8MessageColumnSetFloatByName(C8Message *msg_ptr, const C8Char *i_fldnm, C8Float value) – Purpose: Given a message pointer and a column name, set the value in the message to the indicated value. If the schema type in the message is not a C8Float, the results are undefined and an error is logged. If the col_ndx is out of range, the set is ignored and an error message is logged.

  Parameters:

  • msg_ptr: The message from which you want to extract the data.

  • col_ndx: Indicates which column to retrieve data from. Column numbers start from 0, not 1.

  • value: The value to store in the message.

  Returns: C8_OK on success, C8_FAIL otherwise.

• C8Status C8MessageColumnSetBoolByName(C8Message *msg_ptr, const C8Char *i_fldnm, C8Bool value) – Purpose: Given a message pointer and a column name, set the value in the message to the indicated value. If the schema type in the message is not a C8Bool, the results are undefined and an error is logged. If the col_ndx is out of range, the set is ignored and an error message is logged.

  Parameters:

  • msg_ptr: The message from which you want to extract the data.

  • col_ndx: Indicates which column to retrieve data from. Column numbers start from 0, not 1.

  • value: The value to store in the message.

  Returns: C8_OK on success, C8_FAIL otherwise.

• C8Status C8MessageColumnSetTimestampByName(C8Message *msg_ptr, const C8Char *i_fldnm, C8Timestamp value) – Purpose: Given a message pointer and a column name, set the value in the message to the indicated value. If the schema type in the message is not a C8Timestamp, the results are undefined and an error is logged. If the col_ndx is out of range, the set is ignored and an error message is logged.

  Parameters:

  • msg_ptr: The message from which you want to extract the data.

  • col_ndx : Indicates which column to retrieve data from. Column numbers start from 0, not 1.

  • value: The value to store in the message.

  Returns: C8_OK on success, C8_FAIL otherwise.

• C8Status C8MessageColumnSetIntervalByName(C8Message *msg_ptr, const C8Char *i_fldnm, C8Interval value) – Purpose: Given a message pointer and a column name, set the value in the message to the indicated value. If the schema type in the message is not a C8Interval, the results are undefined and an error is logged. If the col_ndx is out of range, the set is ignored and an error message is logged.

  Parameters:

  • msg_ptr: The message from which you want to extract the data.

  • col_ndx: Indicates which column to retrieve data from. Column numbers start from 0, not 1.

  • value: The value to store in the message.

  Returns: C8_OK on success, C8_FAIL otherwise.

• C8Status C8MessageColumnSetStringByName(C8Message *msg_ptr, const C8Char *i_fldnm, C8Char* value) – Purpose: Given a message pointer and a column name, set the column in the message to the indicated value. If the data type of the column is not a C8Char *, the results are undefined and an error is logged. If the col_ndx is out of range, the set is ignored and an error message is logged.

  If the value pointer was obtained through C8Malloc(), the user must free the pointer (via C8Free()) after C8AdapterSendMessage() to prevent a memory leak. (The C8MessageColumnSetStringByName() routine will make a copy of the value, so freeing that value does not cause the server to lose access to the information.)

  Parameters:

  • msg_ptr: The message from which you want to extract the data.

  • col_ndx: Indicates which column to retrieve data from. Column numbers start from 0, not 1.

  • value: The value to store in the message.

  Returns: C8_OK on success, C8_FAIL otherwise.

• C8Status C8MessageColumnSetBlobByName(C8Message *msg_ptr, const C8Char *i_fldnm, const C8Blob * i_buf, C8UInt i_sz) – Purpose: Given a message pointer and a column name, set the column in the message to the indicated value. If the data type of the column is not a C8Blob *, the results are undefined and an error is logged. If the col_ndx is out of range, the set is ignored and an error message is logged.

  If the value pointer was obtained through C8Malloc(), the user must free the pointer (via C8Free()) after C8AdapterSendMessage() to prevent a memory leak. (The C8MessageColumnSetBlobByName() routine will make a copy of the value, so freeing that value does not cause the server to lose access to the information.)

  Note that the i_buf parameter should contain the original data value -- do not convert the data to a string of hexadecimal values first -- the function will do that for you. Note that since converting the data to a hexadecimal string will require 2N + 1 bytes (2 hex digits for each byte of the original data, plus a null byte as a string terminator), and since the longest allowable string is 4GB, the longest blob you can put in is 2GB - 1 bytes.

  Parameters:

  • msg_ptr: The message from which you want to extract the data.

  • col_ndx: Indicates which column to retrieve data from. Column numbers start from 0, not 1.

  • value - the value to store in the message. The value is a "raw" BLOB (as opposed to a hex string or a base64 string). For an explanation of raw vs. hex string vs. base64 string formats, see "Data Types and Subroutines for UDFs and In-Process Adapters".

  Returns: C8_OK on success, C8_FAIL otherwise.

• C8Status C8MessageColumnSetXmlFromStringByName(C8Message *msg_ptr, const C8Char *i_fldnm, C8Char* value) – Purpose: Given a message pointer and a column name, set the column in the message to the indicated value. If the data type of the column is not a C8Char *, the results are undefined and an error is logged. If the col_ndx is out of range, the set is ignored and an error is message logged.

  If the value pointer was obtained through C8Malloc(), the user must free the pointer via C8Free() after C8AdapterSendMessage() to prevent a memory leak. The C8MessageSetXmlFromStringByName() routine will make a copy of the value, so freeing that value does not cause the server to lose access to the information.

  Parameters:

  • msg_ptr: The message from which you want to extract the data.

  • col_ndx: Indicates which column to retrieve data from. Column numbers start from 0, not 1.

  • value: The value to store in the message.

  Returns: C8_OK on success, C8_FAIL otherwise.

• C8Char* C8MessageSerialize(const C8Message *msg_ptr, enum C8_MESSAGE_FORMAT fmt) – Purpose: A serialized form of msg_ptr is returned as formatted by fmt. Currently the only format supported is C8_MESSAGE_XML. You are responsible for freeing the returned string via C8Free().

  Parameters:

  • msg_ptr: The message from which you want to extract the data.

  • col_ndx: Indicates which column to retrieve data from. Column numbers start from 0, not 1.

  • value: The value to store in the message.

  Returns: C8_OK on success, C8_FAIL otherwise.

• C8Message* C8MessageDeserialize(const C8Char* string, enum C8_MESSAGE_FORMAT fmt) – Purpose: The input string of format fmt is converted to a message. Currently the only format supported is C8_MESSAGE_XML. You are responsible for freeing the returned string via C8Free().

  Parameters:

  • msg_ptr: The message from which you want to extract the data.

  • col_ndx: Indicates which column to retrieve data from. Column numbers start from 0, not 1.

  • value: The value to store in the message.

  Returns: C8_OK on success, C8_FAIL otherwise.

• C8SizeType C8MessageBatchGetCount(C8MessageBatch* batch) – Purpose: Determines the number of messages in a batch.

  Parameters:

  • batch: The batch you want a count of.

  Returns: The number of messages in the batch.

• C8Message* C8MessageBatchPopMessage(C8MessageBatch* batch) – Purpose: Extracts the next message from a batch.

  Parameters:

  • batch: The batch from which you want to extract a message.

  Returns: A pointer to a message or NULL if there are no messages in the batch. Use C8MessageDestroy to destroy each message when you are finished with it.

• const C8Char* C8MessageBatchGetId(C8MessageBatch* batch) – Purpose: Retrieves the ID of this batch of messages.

  Parameters:

  • batch: The batch for which you want the ID.

  Returns: A NULL-terminated string containing the batch ID.

• void C8MessageBatchDestroy(C8MessageBatch* batch) – Purpose: Destroys a batch, including all the messages, and deallocates the associated memory.

  Parameters:

  • batch: The batch you want to destroy.

  Returns: Nothing.