Error Handling and Logging in the LabOne C API#

group ErrorHandling

This section describes how to get more information when an error occurs.

In general, two types of errors can occur when using ziAPI. The two types are distinguished by the origin of the error: Whether it occurred within ziAPI itself or whether it occurred internally in the Zurich Instruments Core library.

All ziAPI functions (apart from a very few exceptions) return an exit code ZIResult_enum, which will be non-zero if the function call was not entirely successful. If the error originated in ziAPI itself, the exit code describes precisely the type of error that occurred (in other words, the exit code is not ZI_ERROR_GENERAL). In this case the error message corresponding to the exit code can be obtained with the function ziAPIGetError.

However, if the error has occurred internally, the exit code will be ZI_ERROR_GENERAL. In this case, the exit code does not describe the type of error precisely, instead a detailed error message is available to the user which can be obtained with the function ziAPIGetLastError. The function ziAPIGetLastError may be used with any function that takes a ZIConnection as an input argument (with the exception of ziAPIInit, ziAPIDestroy, ziAPIConnect, ziAPIConnectEx) and is the recommended function to use, if applicable, otherwise ziAPIGetError should be used.

The function ziAPIGetLastError was introduced in LabOne 15.11 due to the availability of ziCoreModules” in ziAPI - its not desirable in general to map every possible error to an exit code in ziAPI; what is more relevant is the associated error message.

In addition to these two functions, ziAPI’s log can be very helpful whilst debugging ziAPI-based programs. The log is not enabled by default; it’s enabled by specifying a logging level with ziAPISetDebugLevel.

Functions

ZIResult_enum ziAPIGetError(ZIResult_enum result, char **buffer, int *base)

Returns a description and the severity for a ZIResult_enum.

This function returns a static char pointer to a description string for the given ZIResult_enum error code. It also provides a parameter returning the severity (info, warning, error). If the given error code does not exist a description for an unknown error and the base for an error will be returned. If a description or the base is not needed NULL may be passed. In general, it’s recommended to use ziAPIGetLastError instead to get detailed error messages.

Parameters:
  • result[in] A ZIResult_enum for which the description or base will be returned

  • buffer[out] A pointer to a char array to return the description. May be NULL if no description is needed.

  • base[out] The severity for the provided Status parameter:

    • ZI_INFO_BASE For infos.

    • ZI_WARNING_BASE For warnings.

    • ZI_ERROR_BASE For errors.

Returns:

  • ZI_INFO_SUCCESS Upon success.

ZIResult_enum ziAPIGetLastError(ZIConnection conn, char *buffer, uint32_t bufferSize)

Returns the message from the last error that occurred.

This function can be used to obtain the error message from the last error that occurred associated with the provided ZIConnection. If the last ziAPI call is successful, then the last error message returned by ziAPIGetError is empty. Only ziAPI function calls that take ZIConnection as an input argument influence the message returned by ziAPIGetLastError, if they do not take ZIConnection as an input argument the last error message will neither be reset to be empty or set to an error message (in the case of the error). There are some exceptions to this rule, ziAPIGetLastError can also not be used with ziAPIInit, ziAPIConnect, ziAPIConnectEx and ziAPIDestroy

. Note, a call to ziAPIGetLastError will also reset the last error message to empty if its call was successful. Since the buffer is left unchanged in the case of an error occurring in the call to ziAPIGetLastError it is safest to initialize the buffer with a known value, for example, “ziAPIGetLastError was

not successful”.

Parameters:
  • conn[in] The ZIConnection from which to get the error message.

  • buffer[out] A pointer to a char array to return the message.

  • bufferSize[in] The length of the provided buffer.

Returns:

  • ZI_INFO_SUCCESS Upon success.

  • ZI_ERROR_CONNECTION When the connection is invalid (not connected) or when a communication error occurred. In this case the provided buffer is left unchanged.

  • ZI_ERROR_LENGTH If the message’s length exceeds the provided bufferSize, the message is truncated and written to buffer.

void ziAPISetDebugLevel(int32_t severity)

Enable ziAPI’s log and set the severity level of entries to be included in the log.

Calling this function enables ziAPI’s log at the specified severity level. On Windows the logs can be found by navigating to the Zurich Instruments “Logs” folder entry in the Windows Start Menu: Programs -> Zurich Instruments -> LabOne Servers -> Logs. This will open an Explorer window displaying folders containing log files from various LabOne components, in particular, the ziAPILog folder contains logs from ziAPI. On Linux, the logs can be found at “/tmp/ziAPILog_USERNAME”, where “USERNAME” is the same as the output of the “whoami” command.

Parameters:

severity[in] An integer specifying the log’s severity level:

  • trace: 0,

  • debug: 1,

  • info: 2,

  • status: 3,

  • warning: 4,

  • error: 5,

  • fatal: 6,

void ziAPIWriteDebugLog(int32_t severity, const char *message)

Write a message to ziAPI’s log with the specified severity.

This function may be used to write a message to ziAPI’s log from client code to assist with debugging. Note, logging must be first enabled using ziAPISetDebugLevel.

Parameters:
  • severity[in] An integer specifying the severity of the message to write in the log:

    • trace: 0,

    • debug: 1,

    • info: 2,

    • status: 3,

    • warning: 4,

    • error: 5,

    • fatal: 6,

  • message[in] A character array comprising of the message to be written.