An Error Handling statement will, when called, monitor an expression run-time for errors. If an error occurs after this point, the statement will redirect the flow of the expression to a labelled statement (known as the Error Handler) inside the same expression. Typically, the error handler will instruct the expression engine how to deal with the error. If the error handler does not terminate the expression (using a Stop statement), the expression will then continue from the point of error.
Syntax
OnErrorJumpTo(ErrorVariableName, OnAllErrors, MaximumAttempts, StopAfterMaxAttempt):ErrorHandlerName
Parameters
| Parameter Name | Type | Description | Optional? | Default Value |
|---|---|---|---|---|
| ErrorVariableName | String | The keyword for the variable into which information about the error will be written. If this parameter is omitted, the information will not be stored in any variable. | Yes | "" |
| OnAllErrors | Boolean | Determines whether this particular OnErrorJumpTo should handle all errors that occur within the expression. If set to True, all subsequent OnErrorJumpTo statements in the same expression will be ignored. If set to False, the value of MaximumAttempts will be set to 1, and StopAtMaxAttempts will be set to False even if you specify alternative values for either. | Yes | 0/False |
| MaximumAttempts | Integer | The maximum number of times OnErrorJumpTo will redirect the expression to the specified error handler. After this limit has been exceeded, what happens next will depend on the value assigned to the subsequent StopAtMaxAttempts parameter. | Yes | 2 |
| StopAfterMaxAttempts | Boolean | Determines whether the current expression should stop entirely if the maximum number of error handling attempts is reached. If set to False, the expression will continue to run without the influence of the current OnErrorJumpTo statement. | Yes | 0/False |
| ErrorHandlerName | String | A labelled statement that should be executed when an error occurs. | No | n/a |
If you do not need to use any of the optional parameters, you can simply write the expression like this: OnErrorJumpTo:ErrorHandlerName
Output
The function does not return any value, as it simply instructs another set of expressions to execute.
Use Case
An online store provides users with a search tool that allows them to browse products on sale. Because the store recently had an influx of new customers, the server occasionally experiences a high level of traffic, which in turn can negatively affect the performance of the search feature.
For instance, the database used to facilitate customer searches might be overloaded or otherwise unavailable. In situations like this, any attempts to interrogate the database will result in an error. The platform-level handler will register this error, but will neither stop the overall process nor give the end user an indication that there's a problem at this stage. The consequences of the process continuing without corrective error handling at this stage might be insignificant, but they might just as easily cause more serious compound issues further along.
To remedy this, the website administrators implement a multi-stage error reporting system. Throughout the expression, there are a number of assignments to a variable called ErrorStage. Each time the expression reaches a certain stage, a relevant value is written to ErrorStage.
An OnErrorJumpTo statement is written at the top of the expression, and paired with a labelled statement called GenericErrorHandler:
OnErrorJumpTo(ErrorDetails,True):GenericErrorHandler;
ErrorStage:= 1;
// The statements that run as part of stage 1 will go here.;
ErrorStage:= 2;
// The statements that run as part of stage 2 will go here.;
ErrorStage:= 3;
// The statements that run as part of stage 3 will go here.;
#GenericErrorHandler:
{
// Some error handling statements will go here.;
};
When the rest of the expression is filled in, the process will work like this:
- The OnErrorJumpTo statement is initialised.
- ErrorStage is given a value of 1.
- The statements in stage 1 will execute in sequence. If any errors occur, the handler will initialise the contents of GenericErrorHandler, then proceed from the point the error occurred.
- ErrorStage is given a value of 2.
- The statements in stage 2 will execute in sequence. If any errors occur, the handler will initialise the contents of GenericErrorHandler, then proceed from the point the error occurred.
- ErrorStage is given a value of 3.
- The statements in stage 3 will execute in sequence. If any errors occur, the handler will initialise the contents of GenericErrorHandler, then proceed from the point the error occurred.
The significance of using the ErrorStage variable is that any time GenericErrorHandler is called, the value of that variable is available to the contents of that labelled block. This means you could write a statement inside GenericErrorHandler that records the date and time of the error, as well as the stage in which the error occurred. You could then have the expression e-mail details of the error to a system administrator, or use a data source function to write those details to a database.
Below, you can see how the online store's administrators used an e-mail function to notify administrators of any errors:
#GenericErrorHandler
{
TimeOfError:= GetDateTimeFormat("G","en-US");
SendHTMLEmail("Error Report E-mail");
};
The Error Report E-mail template is used to generate an e-mail containing the values of ErrorDetails (into which KnowledgeKube passed details of the error), TimeOfError (which was assigned the date and time when the error occurred) and ErrorStage. This e-mail is sent to an administrator for further action.
The administrators then decide they want to redirect users who encounter an error to a form containing a meaningful error message, letting them know that there is a fault with the site and that an administrator will look into resolving it. After the user is directed to this form, execution of the expression should stop entirely to prevent any further problems occurring as a result of the error.
#GenericErrorHandler
{
TimeOfError:= GetDateTimeFormat("G","en-US");
SendHTMLEmail("Error Report E-mail");
ShowGroupForm("GenericErrorForm");
Stop;
};
The final process now works like this:
- The OnErrorJumpTo statement is initialised.
- ErrorStage is given a value of 1.
- The statements in stage 1 will execute in sequence. If any errors occur, the handler will initialise the contents of GenericErrorHandler, which e-mails the administrator, redirects the user to GenericErrorForm and ends the expression.
- If no error occurs during stage 1, ErrorStage is given a value of 2.
- The statements in stage 2 will execute in sequence. If any errors occur, the handler will initialise the contents of GenericErrorHandler, which e-mails the administrator, redirects the user to GenericErrorForm and ends the expression.
- If no error occurs during stage 2, ErrorStage is given a value of 3.
- The statements in stage 3 will execute in sequence. If any errors occur, the handler will initialise the contents of GenericErrorHandler, which e-mails the administrator, redirects the user to GenericErrorForm and ends the expression.