Error Handling

Under certain conditions the API functions will be unable to successfully execute. In this case an error condition will occur that requires handling by code outside of the API. The API provides three modes of error handling:

The current error mode is set using the vpb_seterrormode() function. The default error mode is Debug.

Debug

If an error occurs in this mode, the program stops execution immediately and prints an error message. This is useful during debugging as it brings any problems to the programmer's immediate attention. However, such behavior is obviously not desirable in release versions of the software. Note that this mode is only suitable for console mode programs, it will cause the program to hang when used with a windows program.

Error Codes

In this case the function returns an integer corresponding to the nature of the error. The convention used by the API is that positive numbers and zero indicate successful function completion, and negative numbers represent an error condition. The error codes for the API functions are listed in vpberr.h. There are other, undocumented error codes that lower levels of the API software may return, but these are not defined in vpberr.h. These errors should not occur during normal operation. To convert an error code into a more helpful error string, use vpb_strerror().

Exceptions

Exceptions are a form of error handling supported by C++. When an error occurs, an exception is "thrown". In the case of the VPBAPI , the exception is a class VpbException that contains information describing the error. The code member of the class corresponds to an error number defined exactly the same way as in the error code error handling method. The other members contain strings describing the API function that generated the error and a brief translation of the error code. The user must provide code to catch the exception at some level in their program. The advantage of exceptions is that it is not necessary to trap errors at every API call, which can become tedious from a programming point of view, especially for API calls deep within nested function calls. Consider the following code fragments, first using error codes:

Example 2. Error Handling Using Error Codes

vpb_seterrormode(VPB_ERROR_CODE);

// Attempt to open channel 1

if ((handle1 = vpb_open(1,1)) != VPB_OK) {
        printf("Error, code = %d\n",handle1);
        exit(0);
}

// Attempt to open channel 2

if ((handle2 = vpb_open(1,2)) != VPB_OK) {
        printf("Error, code = %d\n",handle2);
        exit(0);
}

And now using exceptions:

Example 3. Error Handling Using Exceptions


try {
        vpb_seterrormode(VPB_EXCEPTION);
        handle1 = vpb_open(1,1);
        handle2 = vpb_open(1,2);
}

catch (VpbException v) {
        printf("Error, code = %d, s = %s, api func = %s\n", v.code, 
               v.s, v.api_function);
        exit(0);
}

Using exceptions enables the programmer to send all run time errors to a single point in the code, removing the need for handling errors after every API call. If the current function does not have try/catch exception handling, then the compiler aborts the current function, climbing up the "call stack" until an exception handler is found in a calling function. If no exception handler is found in the calling functions, the program aborts. For more information on exceptions, see a C++ text, or your C++ compiler on-line documentation.