Error Catching

All operations that are carried out on the rows of a table can fail for a variety of reasons. If an operation fails, an IliErrorMessage object that describes the error is created. The member function that triggered the error returns an error status.

An instance of the IliErrorMessage class contains the following information:

• Origin — an enumeration tag that identifies the library from which the error originates. It can be any of the following libraries: DbmsServer, DbmsClientApi, DbLink, Data Access or Application.

• Code — an integer whose interpretation depends on the origin.

• Message — a character string that contains a description of the error.

Error messages are caught by objects. An error sink is an object to which errors can be forwarded.

class IliErrorSink { public: ... virtual void addError(const IliErrorMessage&) {} }; //The IliErrorSink class is intended to be subclassed. Here is an example: class MyErrorSink : public IliErrorSink { public: virtual void addError(const IliErrorMessage& msg) { IlvPrint(“Error: code=%ld, message=’%s’”, (long)msg.getCode(), msg.getMessage()); } };

Alternatively, the class can be used. This class inherits from IliErrorSink, overloading the addError member function so that all errors caught are recorded and made available for inspection.

Once a particular type of error sink has been chosen, the IliTable::addErrorSink member function can be used to indicate that all subsequent error messages be forwarded to it.

Here is an example of how the addErrorSink member function can be used:

IliErrorList errors; IliTable* tbl; ... tbl->addErrorSink(&errors); if (!tbl->deleteRow(10)) { for(IlInt i = 0; i < errors.getErrorsCount(); ++i) { IlvPrint(“Error: %s”, errors.getErrorAt(i).getMessage()); } tbl->removeErrorSink(&errors);

Note that when table objects are acted upon through the default Data Access interaction mechanisms (such as the DbNavigator or the table gadget), any errors that occur are automatically reported to the end user.

However, when table objects are acted upon by custom C++ or Script code that executes on behalf of user interface callbacks, it is the custom code that bears the responsibility to catch any errors that may occur (in an error list object, for example) and to explicitly report these errors to the end user.

The distinction should be made between user interface callbacks (such as the callback of a button gadget or of a menu item) and other more specialized callbacks (such as the data source ValidateRow callback).

Catching and reporting errors has to be done by user interface callbacks. It does not need to be done by the more specialized callbacks because the latter callbacks always execute in the context of a user interface callback.

Errors are reported by the IliErrorReporter class, which has a virtual reportErrors member function. It is possible to provide a custom error reporter on a data source or table gadget basis, or, more globally, the default error reporter may be overridden.