Tracer Message API

A stream can contain normal data messages and tracer messages, which you can use to calculate the time required for a message to move through .

Tracer messages are identified by the having message type C8_MESSAGE_TRACER. For a brief description of different message types, see Message API.

The Sybase CEP SDK includes functions that allow you to get and set the values of fields in these tracer messages:

• CreationUri: The value should be a valid Sybase CEP HTTP Stream URI, for example, http://<host>:<port>/Stream/<ws-name>/<program-name>[/<module-name> ]/<stream-name> .

• CreationTime: The time at which the tracer message was created.

• CreationFrequency: The frequency or interval (measured in microseconds) between tracer messages with which tracer messages are injected into the stream. If there are no periodic tracers, the frequency is 0. If a tracer source is disconnected, the frequency is -1.

Below is a description of each of the tracer-related functions in the API:

• C8Status C8TracerGetCreationURI(const C8Message* i_msg, const C8Char ** o_res); – Purpose: Gets the creation URI field from a tracer message. The value is represented by a null-terminated string. The strings returned by this function must be freed with the C8Free()function.

  Parameters:

  • i_msg: The message from which you wish to read the Creation URI. The message must be of type C8_MESSAGE_TRACER.

  • o_res: Location where the result is to be written.

  Returns: C8_OK on success; C8_Fail otherwise.

• C8Status C8TracerGetCreationTime(const C8Message* i_msg, C8Timestamp* o_res); – Purpose: Gets the creation time from a tracer message.

  Parameters:

  • i_msg: A valid pointer to a message of type C8_MESSAGE_TRACER.

  • o_res: Location filled with the creation time on success.

  Returns: C8_OK on success, C8_FAIL otherwise.

• C8Status C8TracerGetCreationFrequency(const C8Message* i_msg, C8Interval* o_res); – Purpose: Gets the creation frequency from a tracer message.

  Parameters:

  • i_msg: A valid pointer to a message of type C8_MESSAGE_TRACER.

  • o_res: Location filled with the creation frequency on success.

  Returns: C8_OK on success, C8_FAIL otherwise.

• C8Status C8TracerSetCreationURI(C8Message* i_msg, const C8Char * i_val); – Purpose: Sets the creation URI field of a tracer message.

  Parameters:

  • i_msg: A valid pointer to a message of type C8_MESSAGE_TRACER.

  • i_val: Pointer to NULL terminated string containing the creation URI

  Returns: C8_OK on success, C8_FAIL otherwise.

• C8Status C8TracerSetCreationTime(C8Message* i_msg, C8Timestamp i_val); – Purpose: Sets the creation time of a tracer message.

  Parameters:

  • i_msg: A valid pointer to a message of type C8_MESSAGE_TRACER.

  • i_val: Creation timestamp.

  Returns: C8_OK on success, C8_FAIL otherwise.

• C8Status C8TracerSetCreationFrequency(C8Message* i_msg, const C8Interval i_val); – Purpose: Sets the creation frequency of a tracer message.

  Parameters:

  • i_msg: A valid pointer to a message of type C8_MESSAGE_TRACER.

  • i_val: Creation frequency.

  Returns: C8_OK on success, C8_FAIL otherwise.