Error Handling and Logging in the LabOne C API

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.