Rejecting a request

In a request filter, your code can reject the request, which means that the request will not be completed to the DB2 server, and the client will receive an error message.

A typical rejection would be, for instance, in a query filter. The code in your filter can reject the query with e.g.:

const hours = new Date().getHours();

if (hours > 18 || hours < 7) {

    context.result.errorCode = -438;

    context.result.sqlStatus = 23514;

    context.result.addErrorParameter("This query is not allowed outside of business hours");

}

The critical part is the errorCode -- if it is set to a value other than zero (the default), then the request will be rejected.

Errors in DB2 have two main components:

• the error code, which is a negative number, typically between -007 and -32000, and corresponds to an error message (see below). This must be set to a non-zero value for the request to be rejected.

• the SQL status, which is a positive 5-digit number that is standardized (see list of common SQL state codes). This is not strictly speaking required (the default is 00000). However, some DB2 clients may react unpredictably if sqlStatus is not given a meaningful value. If you're not sure which sqlStatus to select, you can use 23514, which means "Check data processing has found constraint violations".

Error messages

Each error code corresponds to an error message that is defined by IBM. The exact list of available error messages (and therefore error codes) is dependent on the version of DB2. For instance, see the error messages for DB2/LUW 11.5.

The database uses the version of the messages that is appropriate for the language currently in use.

Many error messages contain placeholders for parameter values. For instance, error message -104 in English is:

An unexpected token token was found following text. Expected tokens may include: token-list.

This error message takes three parameters: token, text, and token-list. If your code wants to reject a request with this error message, it would set errorCode to -104, and add three error parameters, e.g.:

context.result.errorCode = -104;

context.result.addErrorParameter(badToken);

context.result.addErrorParameter(textBefore);

context.result.addErrorParameter("this, that, the other");

Parameters can only be strings.

You'll need to select an existing error code appropriate for your use case. If you're not sure which errorCode to use, a good generic error is error -438:

Application raised error or warning with diagnostic text: text.

This allows you to return a meaningful message in the parameter text.