Some macros were introduced in order to make error handling more consistent and useful both from the developer's and the scanner operator's point of view. Here we describe the suggested method to use when programming with KSFoundation.

Signaling an error

When an error is detected in the code, the programmer is encouraged to use the newly introduced macro KS_THROW – e.g.

if (value > upper_bound) {
  return KS_THROW("value is over its upper bound"); 
}

The macro KS_THROW is a wrapper around ks_error and prepends to the error message the function name, file name and line number of the KS_THROW in order to easily find where the error occurred.

Regarding the error message, it should be chosen short enough so that it can be read in the scanner UI. If more information is needed, it can be added at the start of the error messsage followed by a semi colon. This is because ks_error removes everything up to the last semi colon when passing the error message to the UI. For instance, we can modify the example above as following:

if (value > upper_bound) {
  return KS_THROW("value=%d, upper_bound=%d: value is over its upper bound",
                  value, upper_bound); 
}

and the error message in the UI will be unchanged but the extra information is stored in ks_errors.txt.

Forwarding an error

When calling a function that returns a STATUS value, usage of the macro KS_RAISE is encouraged – e.g.

STATUS status = my_func();

KS_RAISE(status);

In this manner the entire stack trace from the function where the error originally occurred up to the currently running top-level function will be recorded in ks_debug.txt.

Alternatively, one might want to clarify the error condition relative to the local context. In this case it is fine to call again KS_THROW as in the following:

STATUS status = my_func();
if (status != SUCCESS) {
  return KS_THROW("Clarifying comment on the error");
}

The above is also recommended when calling a GE's function that return a STATUS as GE's uses a different logging system for errors and it would otherwise result in an incomplete stack trace in ks_debug.txt.

Other considerations

There are two values for failure: FAILURE and ADVISORY_FAILURE. Always check for failure by comparing with SUCCESS.
It is advised never to return a FAILURE as this leads to poor UX on the scanner.
On WTools, the stack trace is logged in ks_errors.txt and it is visible on the WTools UI.
File names and line numbers in the stack trace might refer to files generated by the Epic preprocessor.

Home