Error Handling

This chapter provides details about how errors are reported and handled in Lasso 9. Topics include error reporting, custom error pages, error methods and error handling.

Overview

Responding to errors gracefully is the hallmark of good programming. Errors in Lasso run the gamut from expected errors such as a database search that returns no records to syntax errors that require fixing before a page will even process. Lasso provides tools to manage errors at several different levels which can act redundantly to ensure that no errors will be missed.

The following lists the types of errors that can occur in or are reported by Lasso. This chapter includes instructions for how to handle each of these types of errors.

Error Types

• Web Server Errors include file not found errors and access violations in realms. These will be reported with standard HTTP response codes, e.g. 404 for File Not Found.
• Syntax Errors include misspellings of type or method names, missing delimiters, and mismatched data types. Lasso will return an error message rather than the processed Lasso page if it encounters a syntax error.
• Action Errors include misspellings of database names, table names, or field names and other problems specifying database actions. The database action cannot be performed until the errors are corrected.
• Database Errors are generated by the data source application and include data type mismatches, missing required field values, and others. Lasso will report the error which was returned from the data source application without modification.
• Logical Errors are problems that cause a page to process unexpectedly even though the syntax of the code is correct. These include infinite loops, missing cases, and assumptions about the size or composition of a found set.
• Security Violations are not strictly errors, but are attempts to perform database actions or file accesses which are not allowed by the permissions set for the current user. 
• Operating System Errors can also be reported by Lasso if they occur.

Some errors are more serious than others. Pages will not be processed at all if they contain syntax errors or if there are operational problems which prevent Lasso Service from being accessed. Other errors are commonly encountered in the normal use of a Web site. Most database errors and security violations are handled by simple means such as showing a No Records Found message or displaying a security dialog box to prompt the user for a username and password.

There following mechanisms for handling errors can be used singly or in concert to provide comprehensive error handling.

Error Control Types

• Automatic Error Reporting is performed by Lasso in response to unhandled errors.
• A Custom Error Page allows the automatic error page to be replaced by a custom page. Custom error pages are usually created for each site on a server.
• Error Methods allow action and logical errors and security violations to be handled within a Lasso page.
• Error Handling methods allow advanced error handling to be built into Lasso pages. These techniques allow error handling routines to be built into a page without disrupting the normal processing of a page if no errors occur.

Error Reporting

Lasso 9 delivers an "error stack" in response to an error that prevents processing of the page. This error stack contains a significant amount of information, which can be used to identify the cause and location of an error.

The error stack can be accessed by using provided [Error_...] methods.

Custom Error Page

A custom error page can be defined which will be displayed to the site visitor rather than Lasso's built-in error message. The error message displayed on a custom error page will depend on the LassoScript used to code the custom page.

To define a custom error page, create a file named error.lasso and place it in the root of the Web serving folder. Each host that has a distinct web serving folder can have a custom error page.

Custom error pages can be further fine tuned by placing the error.lasso file in the web serving folder's subdirectories. Lasso Server will process the first error.lasso it encounters on the file path, starting with the current directory and continuing upwards until it reaches the root of the web serving folder. If none are found, Lasso Server will use the default error page.

Error Methods

The [Error_…] methods in Lasso allow custom errors to be reported and provide access to the most recent error that was reported by the code executing in the current Lasso page. This allows the developer to check for specific errors and respond if necessary with an error message or code to correct the error.

Lasso maintains a single error code and error message that is set by any method which reports an error. The error code and error message should be checked immediately after a method that may report an error. If any intervening methods report errors then the error code and error message will be lost.

Custom errors can be created using the [Error_SetErrorMessage] and [Error_SetErrorCode] methods. Once set, the [Error_CurrentError] method or [Error_Code] and [Error_Msg] method will return the custom error code and message. A developer can utilize these methods to incorporate both built-in and custom error codes into the error recovery mechanisms for a site.

Error Methods

To display the current error in a Lasso page:
Use the [Error_Msg] method and the [Error_Code] method. The following code will display a short error message.

The current error is [Error_Code]: [Error_Msg].

If the code on the page is executing normally and there is no current error to report then the code will return:

The current error is 0: No Error.

Use the [Error_CurrentError] mehod with the optional -ErrorCode keyword. The following code will display a short error message.

The current error is [Error_CurrentError: -ErrorCode]: [Error_CurrentError].

If the code on the page is executing normally and there is no current error to report then the code will return.

The current error is 0: No Error.

To set the current error in a Lasso page:
The current error code and message can be set using the [Error_SetErrorCode] and [Error_SetErrorMessage] methods. These methods will not affect the execution of the current Lasso page, but will simply set the current error so it will be returned by the [Error_CurrentError] method or [Error_Code] and [Error_Msg] methods.

In the following example, the error message is set to A custom error occurred and the error code is set to -1.

[Error_SetErrorMessage: 'A custom error occurred']
[Error_SetErrorCode: -1]

The [Error_CurrentError] method now reports this custom error when it is called later in the page, unless any intervening code changed the error message again.

The current error is [Error_CurrentError: -ErrorCode]: [Error_CurrentError].
The current error is -1: A custom error occurred.

The current error code and message can also be set using the [Error_Code] and [Error_Msg] methods.

[Error_Msg = 'A custom error occurred']
[Error_Code = -1]

To store and restore the current error in a Lasso page:
Use the [Error_Push] and [Error_Pop] methods. The following code stores the current error code and message before the [Protect] block is executed. This allows the [Protect] block to execute without any previous error on the page bleeding into it and mistakenly triggering the [Handle_Failure] block. Then the error code and message are restored at the end of the block

error_push;  // Push error on to stack

protect => { // Protect from failure
	handle_failure => {
		// Handle an error generated within the protect block.		
	}
}

error_pop;	// Retrieve error on stack

The [Error_Push] and [Error_Pop] methods can also be used to prevent a custom methods from modifying the current error condition, while still using error handling code within the method. The following code stores the current error code and message at the beginning of the custom method definition. The error code and message are restored just before the custom method returns a value.

define myMethod( ) => {
// Push current error on to stack.
	error_push;
	
	// Code that may generate error.
	// ...
	
	// Retrieve error from stack.
	error_pop;
	
	return 'myValue';
}

To reset the current error in a Lasso page:
Use the [Error_Reset] method. This resets the error message to blank and the error code to 0.

[Error_Reset]

Error Handling

Lasso includes powerful error handling methods that allow areas of a page to be protected. Error-specific handlers are called if any errors occur in a protected area of a page. These methods allow comprehensive error handling to be built into a page without disturbing the code of the page with many conditionals and special cases.

Handle Methods

The [Handle] methods are used to surround a block of code that will be executed after the current code segment is completed. The opening [Handle] method takes a single parameter which is a conditional expression (defaults to True). If the conditional expression returns True, then the code in the [Handle] capture block is executed.

All [Handle] and [Handle_failure] methods are processed sequentially, giving each a chance to be executed in the order they were specified and allowing for execution of multiple [Handle] blocks. Therefore, it is necessary to define them before logic that could halt the script execution. [Handle] methods that are defined after a script failure will not be executed. It is generally good practice to place [Handle] and [Handle_Failure] methods at the start of the parent capture block, most commonly [Protect]. This is a change from previous versions of Lasso and increases the reliability of executing fault-condition fallbacks

[Handle] methods will not be executed if a syntax error occurs while Lasso is parsing a page. When Lasso encounters a syntax error it returns an error page instead of processing the code on a page.

[Handle] methods will be executed if a logical error occurs while Lasso is processing a page. However, the result of the page will be an error message rather than the output of the page. Code within the
[Handle] methods can redirect the user to another page using [Redirect_URL] or can replace the contents of the page being served.

There are two ways to use [Handle] methods within a Lasso page:

• When used on their own in a Lasso page, the code inside the [Handle] methods will be conditionally executed after all the rest of the code in the Lasso page has completed. [Handle] methods can be used to provide post-processing code for a Lasso page.

• When used within any Lasso capture block, the code inside the [Handle] methods will be conditionally executed after the capture block is executed. [Handle] methods will most commonly be used within [Protect] block to provide error handling.

Fail Methods

The [Fail] method allows an error to be triggered from within Lasso code. The two parameters of the method are the integer error code and string error message of the error to be reported. Use of the [Fail] method immediately halts execution of the current page and starts execution of any [Handle] method contained within.

The [Fail] method can be used in the following ways:

• To report an unrecoverable error. Just as Lasso automatically halts execution of a Lasso page when a syntax error or internal error is encountered, Lasso code can use the [Fail] metod to report an error which cannot be recovered from.

• [Fail: -1, 'An unrecoverable error occurred']

• To trigger immediate execution of the page’s [Handle] methods. If an error is handled by one of the [Handle] methods specified in the Lasso page (outside of any other capture blocks) then the code within the [Handle] capture block will be executed.

• To trigger immediate execution of a [Protect] capture block’s [Handle] block. See the next section  Protect for details.

To conditionally execute a [Fail] method:
[Fail_If] allows conditional execution of a [Fail] without using a full [If] capture block. The first parameter to [Fail_If] is a conditional expression. The last two parameters are the same integer error code and string error message as in the [Fail] method. In the following example the [Fail_If] method is only executed if the variable #x does not equal 0.

[Fail_If( #x != 0 ), 100, "Value does not equal 0."]

Protect Methods

The [Protect] methods are used to catch any errors that occur within the code surrounded by the capture block. They create a protected environment from which errors cannot propagate to the page itself. Even if an internal error is reported by Lasso it will be caught by the [Protect] methods allowing the rest of the page to execute successfully.

Any [Fail] or [Fail_If] methods called within [Protect] capture blocks will halt execution only if the code is contained within the [Protect] capture blocks. Any [Handle] capture blocks contained within the [Protect] capture blocks will be conditionally executed, however Lasso 9 requires these [Handle] capture blocks to be present at the top of the [Protect] capture block. The Lasso page will continue executing normally after the closing of the [Protect].

The [Protect] capture blocks can be used for the following purposes:

• To protect a portion of a page so that any errors that would normally result in an error message being displayed to the user are instead handled in the internal [Handle] code blocks.
• To provide advanced flow control in a page. Code within the [Protect] capture blocks is executed normally until a [Fail] signal is encountered. The code then jumps immediately to the internal [Handle] block.

To protect a portion of a page from logical errors:

Wrap the portion of the page that needs to be protected in [Protect] capture block. Any internal errors that Lasso reports will be caught by the [Protect] code block and not reported to the end user. A [Handle] code block should be included to handle the error if necessary.

In the following LassoScript an attempt is made to set a variable $myVar to Null. However if the variable has not been previously declared an error would be reported and the page would not continue processing. Since this code is executed within [Protect] capture block no error is reported, and the [Protect] capture block exits silently and the Lasso page resumes executing after the end of the LassoScript.

protect => {
    $Tags = Null
}

To use [Protect] with custom errors:

The following example shows a [Protect] capture block which surrounds code that contains two [Fail_If] statements with custom error codes -1 and -2. A [Handle] block at the start of the [Protect] is set to intercept either of these custom error codes. This [Handle] block will only execute if one of the [Fail_If] methods executes successfully.

Protect => {^
	Handle => {^
		if(Error_CurrentError(-ErrorCode) == -1)
			'... Handle custom error -1 ...'
		else(Error_CurrentError(-ErrorCode) == -2)
			'... Handle custom error -2 ...'
		else
			'... Another error has ocurred ...'
		/if
	^}

	'Before the fail_if\r'
	
	local(
		ConditionOne	= false,
		ConditionTwo	= true
	)
	Fail_If(#ConditionOne == True, -1, 'Custom error -1')
	Fail_If(#ConditionTwo == True, -2, 'Custom error -2')
	
	'\rAfter the fail_if'

^}