Menu
Simba Technologies
Simba Technologies

SimbaEngine X SDK 10.1.3
Developing Drivers for Data Stores Without SQL

Handling Errors and Exceptions

ODBC, JDBC, and ADO.NET require that driver provide standard error codes so that applications have a standard way of dealing with error conditions. Data stores can also provide their own custom error codes. This section explains what your custom driver should do when it encounters an error or an exception.

Using the ErrorException Class

When your DSII detects an error condition, it should throw an exception of type ErrorException. This class has the following signature:

ErrorException(

DiagState in_stateKey,

simba_int32 in_componentId,

const simba_wstring& in_msgKey,

simba_signed_native in_rowNum = NO_ROW_NUMBER,

simba_int32 in_colNum = NO_COLUMN_NUMBER);

The parameters for this method are described below:

  • in_componentId

    The component id is used to determine which component threw the exception and where the message should be loaded from. The list of reserved component Ids (1-10) and their names can be found in SimbaErrorCodes.h. It is suggested that any custom component Id you define for your DSII start counting from 100.

  • in_msgKey

    The in_msgKey argument is a string shortcut to indicate which message to load from the standard error message file or your own custom message source. For information about error message files, see Localizing Messages.

  • in_stateKey

    The in_stateKey argument is used to control which SQLSTATE code should be associated with the error returned by ODBC. SQLSTATE is a 5-character sequence defined by SQL standards that is used to return a standard error code. The most common state to throw is DIAG_GENERAL_ERROR. A full list of available DiagState keys can be found in DiagState.h.

Exception Macros in the Sample Drivers

The Quickstart sample driver provides sample macros that you can adapt to throw your own exceptions. These macros are defined in Quickstart.h. For information on using Quickstart, see the 5 Day Guides at http://www.simba.com/resources/sdk/documentation/.

Example: Using Quickstart's Exception Macro

In the sample Quickstart driver, the following macro is used to throw an exception if the required DBF setting is missing:

QSTHROW(DIAG_INVALID_AUTH_SPEC, L"QSDbfNotFound");

This throws an ErrorException with a DiagState of DIAG_INVALID_AUTH_SPEC and the QSDbfNotFound message key. The macro automatically includes the Quickstart component Id.

Some messages are also parameterized, and there are sample macros to assist in constructing the vector of parameters before throwing the exception.

Example: Throwing an Exception With Parameters

This example throws an ErrorException with a DiagState of DIAG_GENERAL_ERROR and the QSInvalidCatalog message key.

QSTHROWGEN1(L"QSInvalidCatalog", in_schemaName);

in_schemaName is a simba_wstring parameter that is added to a vector and passed to a constructor for ErrorException, which accepts a parameter vector. The message source will use the parameter vector to do string substitution on special markers in the message string.

Using or Building a Message Source

All exceptions and warnings in your custom driver are looked up by their message key using an IMessageSource constructed by your custom driver. An implementation of this class, called DSIMessageSource, is provided to handle looking up any message key generated by SDK components. This class looks up the messages in the error messages files. The error message files are located in the directory [INSTALL_DIRECTORY]\DataAccessComponents\ErrorMessages. The driver determines the location of this file by looking up the ErrorMessagesPath value in the registry at HKLM\Software\<OEM NAME>\Driver\, or inside the configuration file on Linux, Unix, or macOS platforms.

In order to provide messages of your own, you must register an error messages file with DSIMessageSource or construct your own MyDSIIMessageSource class deriving from IMessageSource. If you use DSIMessageSource, you will only be responsible for providing an XML message file for all of the messages your DSII uses. If you derive from IMessageSource, you will be responsible for looking up any message key generated by either the SDK or your DSII.

All of the sample drivers register an additional message file with the default DSIMessageSource, and it is recommended that your DSII do the same unless there is good reason to do otherwise. The error messages XML files are placed in directories named after the locale that the message files are associated with, for example, [INSTALL_DIRECTORY]\DataAccessComponents\ErrorMessages\en-US.

For information about error message files, see Including Error Message Files.

Custom SQL States

SQLSTATE is a 5-character sequence defined by SQL standards. It provides detailed information about the cause of a warning or error. The SimbaEngine X SDK attempts to return SQL states, or equivalent, that accurately follow the specifications of ODBC, JDBC, and ADO.NET. However, in some cases your custom driver may need to return a different SQL state than what is used by the SDK. In those cases, your DSII will return a custom SQL state as described in the this section:

ODBC

Exceptions are implemented in the ErrorException base class. The predefined SQL states are mapped to DiagStates, and there are constructors that take a DiagState along with other information for this purpose. When using custom SQL states, use the constructors that take a simba_string for the SQL state to provide any 5 character SQL state.

Likewise, warnings with custom SQL states will post warnings to the IWarningListener using the simba_string constructor instead of the DiagState constructor.

JDBC

Exceptions are implemented in the DSIException base class. The predefined SQL states are mapped to ExceptionID, and there are constructors that take an ExceptionID along with other information for this purpose. When using custom SQL states, use the constructors that take a String for the SQL state to provide any 5 character SQL state.

Likewise, warnings with custom SQL states will post warnings to the IWarningListener using a Warning constructed with the String constructor instead of the WarningCode constructor.

ADO.NET

Exceptions are implemented in the DSIException base class. Note that SQL states are not directly supported by the ADO.NET API. Instead, the custom SQL state is prepended to the exception error message. The predefined SQL states are mapped to ErrorCode, and there are constructors that take an ErrorCode along with other information for this purpose. When using custom SQL states, use the constructors that take a string for the SQL state to provide any 5 character SQL state.

Likewise, warnings with custom SQL states will post warnings to the IWarningListener using the string constructor instead of the WarningCode constructor.

OLE DB

SQL states, custom or not, are exposed using the custom error object through the ISqlErrorInfo interface. For details on the ISqlErrorInfo interface, see http://msdn.microsoft.com/en-us/library/windows/desktop/ms711569%28v=vs.85%29.aspx. Also, refer to the topic How a Provider Returns an OLE DB Error Object in MSDN at http://msdn.microsoft.com/en-us/library/windows/desktop/ms723101%28v=vs.85%29.aspx.

 

Related Links

Posting Warning Messages

Including Error Message Files

Localizing Messages