An Error represents either a system-defined or user-defined Error. Errors can be used not only to indicate if an operation failed or was successful (in which case a Boolean would suffice), but also to indicate why a failure occurred. For example, if you attempt to copy a file to the desktop, the process can either succeed or fail. If it fails, it could be because the file to copy cannot be found, because the destination disk is full, because a file with that name already exists, and so on. A specific Error can be generated for each case, allowing the application designer to determine the reason the function failed.

An Error can be thought of as containing two parts; the Integer error identifier and the String error message. Errors are referred to in scripts by their error identifiers, but the error message can be used to provide the user with information about the type of error that occurred.

There are two types of Errors used in OScript:

• System-defined Errors created by Open Text as part of Livelink are returned when OScript built-in functions fail. Designers can examine the messages associated with these Errors, but cannot modify them or return them. For example, the function File.Open() returns a file reference if successful, or an Error if the file could not be opened.
• User-defined Errors created using Error.Define() to associate an error identifier (in the range 1024 to 2047) with an error message about the created Error.

The following example illustrates the definition of user-defined Errors:

	Error.Define( 1024, "Cannot find specified file." )
	Error.Define( 2000, "File already exists." )
	Error.Define( 2047, "Out of range." )

Once an Error type is defined, it exists for the remainder of the application execution. It is not disposed of when the script creating the Error completes execution. In this way Errors can be defined during initialization scripts, and not be worried about again.

Values of type Error are obtained by executing Error.Get(). The following example illustrates (it relies upon the "Out of range." Error 2047 defined above):

	function Boolean checkRange( Integer checkValue )
		Boolean returnValue
		Error negative = Error.Define( 2001, "Negative" )
		if ( checkValue < 0 ) 
			// Return the negative value error.
			returnValue = negative 
		elseif ( checkValue > 1000 ) 
			// Return the out of range error.
			returnValue = Error.Get( 2047 )
		else
			returnValue = TRUE;
		end
		return( returnValue )
	end

Redefining an Error is acceptable, and the old String message is merely replaced with the new. Because of this, be careful that your User Error values do not overlap:

Error.Define( 1954, "A" )
Echo( Error.Get( 1954 ) )  // Echoes "A"
Error.Define( 1954, "B" )
Echo( Error.Get( 1954 ) )  // Echoes "B"

Unlike most other OScript data types, any type of variable can assume an Error value. This allows you to create a variable of any type and store a valid value in it if the operation was successful, or store an Error in it if the operation failed.