Class: Error

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. Errors provide OScript with error-handling more powerful than any found in the C language or Pascal, even though Errors are not as powerful as C++ and Java's Exceptions.

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 and integral to Livelink. These are returned when OScript built-in functions fail. Designers can examine the messages associated with these Errors, but can neither modify them nor return them. For example, 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.

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.

Unlike most other OScript data types, the Error value is special the way Undefined (null) is in that any type of variable can assume an Error value. This allows 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 (note: this has the interesting effect that the Boolean type can actually be any of four values; True, False, Undefined, or Error).