Error Handling Functions

All the error handling functions are available through functions defined in

#include "c8messages.h"

These error-handling functions are available to both in-process and out-of-process tasks.

The design of error handling permits flexibility in its use. An application may implement error handling to whatever degree necessary. If desired, error handling may be ignored or it may be used after every call. Ignoring error conditions may result in undefined behavior.

You can implement your own error code with associated text messages. This is an alternative way to log errors on the Sybase CEP Engine logger. All calls to C8ErrorSet() result in a log entry in the Sybase CEP system log. All C8ErrorSet() calls are considered equal in the sense that there is no distinction between informational, warning, or fatal messages.

Errors are tracked on a per-thread basis. Once an error condition is detected, the error code will persist until C8ErrorClear() zeroes the error code or until the next Sybase CEP API function is called. Each Sybase CEP API call will reset the error.

A zero error code indicates no errors; this is the initial state.

Refer to c8messages.h for Sybase CEP error codes.

The following commands are available for handling error codes:

• void C8ErrorClear(); – Purpose: Clear any existing error code to the zero state. This implies no errors.

  Parameters: None.

  Returns: Nothing.

• void C8ErrorSet(C8Int error_code, const char *err_text,); – Purpose: This sets the error code (which may subsequently be read). It also prints both the error code and the message to Sybase CEP Server log.

  The err_text variable can contain not any of the print format specifiers allowed by the NSPR C-language printf() function (for example, "%s", "%d", and so on). See the table below for details. As with the standard C printf() call, the call to C8ErrorSet() should have as many additional parameters as there are print format specifiers. For example:

  C8ErrorSet(-99, "Err: expected = %d actual = %d", v1, v2);
  

  Unlike when calling printf(), you do not need to include a new line to force each message to be put on a separate line in the Sybase CEP log.

  The table below shows the print format specifiers used with Sybase CEP data types.

  Sybase CEP Data Type	NSPR Print Format Specifier	Meaning
  C8Blob	None	There is no format specifier for printing a BLOB. To display a BLOB's contents, you may convert it to a string of hexadecimal digits (using the C8ConvertBlobToHexString() function) and then display that string.
  C8Boolean	%d	Signed integer (note that this will print a number, not a word such as "TRUE" or "FALSE").
  C8CharPtr Or C8Char *	%s	String.
  C8Float	%f	64-bit floating point number ("double" on most platforms).
  C8Int	%ld	Signed 32-bit integer (decimal).
  C8UInt	%u	Unsigned 32-bit integer (decimal).
  C8Interval	%lld	This will print the length of an interval in microseconds.
  C8Long	%lld	Signed 64-bit integer.
  C8ULong (UNIX)	%llu	Signed 64-bit integer.
  C8ULong (Microsoft Windows)	%I64u	Unsigned 64-bit integer.
  C8Timestamp	%lld	This will print the timestamp as a number of microseconds since midnight January 1, 1970, UTC.

  For consistency, we recommend that you follow the convention of pairing error numbers and error messages so that you see the same error message each time you see an error number. However, Sybase CEP does not require or check that error codes and error messages are consistently paired. In different calls, the same error code may be used with a different text (and vice versa).

  The error you set with C8ErrorSet() will normally remain until you explicitly clear it with the C8ErrorClear() function or until it is overwritten by another error.

  Note: Errors are "per thread". Each thread sees only its own error codes.

  Calls to the Sybase CEP API clear error code when they succeed and set the error code when they fail. We recommend that you check the return codes of Sybase CEP calls to make sure they succeed.

  • For calls that return C8Status, the return value of C8_FAIL indicates a failed call, while C8_OK indicates success.

  • For functions that return pointers, a return value of NULL indicates that the call failed.

  • For void functions, users need to check whether C8ErrorGetCode() returns a non-zero value, which indicates an error.

  If the Sybase CEP API call failed, the user may get the error code and error text with C8ErrorGetCode(), C8ErrorGetMessageLength() , and C8ErrorGetMessageText().

  Parameters:

  • error_code: The error number that you want to set.

  • err_text: The text of the error message that you would like to set.

  Returns: Nothing.

• void C8Log(const char *log_text, ...); – Purpose: This prints the message to Sybase CEP Server log.

  The log_text variable can contain text as well as any of the print format specifiers allowed by the NSPR C-language printf() function (for example, "%s" or "%d"). See the table in C8ErrorSet() for details. As with the standard C printf() call, the call to C8ErrorSet() should have as many additional parameters as there are print format specifiers. For example:

  C8Log("expected = %d actual = %d", v1, v2);

  Unlike when calling printf(), you do not need to include a new line to force each message to be put on a separate line in the Sybase CEP log.

  Parameters:

  • log_text: The text to write to Sybase CEP Server log.

  Returns: Nothing.

• void C8LogMessage(C8Int i_code, const enum C8LogLevels i_level, const C8Char *i_fmt, ...); – Purpose: This allows the user to specify message for the log file and control the circumstances under which that message will be printed to the log.

  You may have messages that you want logged only under certain circumstances, such as when debugging a problem. This function allows you to specify a message and the severity of that message. By specifying the appropriate severity for each message, and by setting the LogLevel parameter in the server configuration file, you may control whether a particular message is logged or ignored on a particular run of the server.

  The pre-defined levels are shown in the table below.

  C8LogFatalError	-4
  C8LogError	-3
  C8LogWarning	-2
  C8LogStatus	-1
  C8LogInfo	0
  C8LogDebug	1
  C8LogDebug2	2
  C8LogTrace	3

  The level of the message, combined with the setting of the LogLevel parameter in the c8-server.conf file, controls whether the message is sent to the log. For example, if c8-server.conf file contains the following:

  <section name="FileLogger">
    ...
    <preference name="LogLevel">Warning</preference>
    ...
  	</section>
  

  then all calls to C8LogMessage() that have an i_level of Warning or lower will be printed in the log, and the rest will not. In this example, all FatalErrors, Errors, and Warnings will be printed, while Status, Info, Debug, Debug2, and Trace messages will not be logged.

  The i_fmt variable can contain both text and any of the print format specifiers allowed by the NSPR C-language printf() function (for example, "%s" or "%d"). See the table in C8ErrorSet() for details about the print format specifiers. As with the standard C printf() call, the call to C8LogMessage() should have as many additional parameters as there are print format specifiers. For example:

  C8LogMessage(2001, C8LogDebug, "At start of foo(), param1 = %d", param1);

  Unlike when calling printf() , you do not need to include a new line to force each message to be put on a separate line in the Sybase CEP log.

  Parameters:

  • i_code: This number identifies the type of error that occurred.

  • i_leve: This identifies the severity of the message, according to the table shown above.

  • i_fmt: This contains the text of the error message.

  Returns: Nothing.

• C8Int C8ErrorGetCode(); – Purpose: returns the most recent error code. The error code and text are maintained on a per-thread basis and persist until cleared or overwritten by another error.

  Parameters: None.

  Returns: The most recent error code.

• C8SizeType C8ErrorGetMessageLen(); – Purpose: returns the length of the buffer (in bytes) required to hold the message associated with the error code for the current thread. This length accounts for the space needed for the terminating null. If the return value is zero, there is no text information. It is possible to have a non-zero error code and no associated text if this is what the user has set. Sybase CEP software always associates textual information with an error code.

  Parameters: None.

  Returns: The length of the buffer (in bytes) required to hold the message associated with the error code (for the current thread. Note that this includes the space required for the string termination character.

• C8Bool C8ErrorGetMessageText(char *o_text, C8SizeType i_buf_size); – Purpose: the text associated with the current error code is copied into o_text. It is assumed that you have prepared a buffer of adequate size based on the length returned by C8ErrorGetMessageLen(). If the buffer is not large enough to hold the message, then the function will copy as much of the message as will fit, taking into account the byte required to terminate the truncated string with a null. The internal copy of the text remains unaffected.

  Parameters:

  • o_text: The buffer into which to copy the error message.

  • i_buf_size: The size of the buffer.

  Returns: C8_TRUE if the entire message was copied, C8_FALSE otherwise.