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).

Class Attributes Index

o E_NoSuchError
Error return value indicating that the errorID parameter to method Error.Get() is neither a system ID nor a user-defined ID.

Class Methods Index

o Abort( [Dynamic status] )
Ends script execution.
o Define( Integer errNum, String errText )
Defines a new Error value and its associated Error message.
o ErrorToString( Error errRef )
Returns the String description associated with the specified Error.
o Get( Integer status )
Gets the corresponding Error value.
o Id( Error errRef )
Returns the Integer status value associated with the specified Error.
o IntToError( Integer errID )
Returns an Error whose id is the specified integer errID.

Class Attributes

o E_NoSuchError 
 Error E_NoSuchError

Error return value indicating that the errorID parameter to Error.Get() is neither a system ID nor a user-defined ID.

Class Methods

o Abort 
 Void Abort(
         [Dynamic status] )

Ends script execution. It does not return a value. It is used for debugging. If status is a value of type Error, the status that ends script execution is the Integer related to the Error from either system Errors or customized Error.Define() Errors. Otherwise, if status is not a value of type Error or is not specified, script execution is ended with the status Unknown Abort. The Scheduler built-in functions also provide a way to suspend or end script execution.

Parameters:
status  -  Specifies an optional value, either of type Error, or any other type. If not specified, then execution will be aborted with a status indicating an Error.Abort().
Returns:
None-- execution of the current script terminates.
o Define 
 Error Define(
           Integer errNum,
           String errText )

Defines a new Error value and its associated Error message. The Error remains defined for the duration of the program execution only. The newly defined Error value can be retrieved using Error.Get().

Parameters:
arg1  -  An Integer indicating a unique identifier for the Error which must be within the range of 1024 to 2047.
arg2  -  Specifies a String text description for the Error.
Returns:
Returns a new value of type Error.
o ErrorToString 
 String ErrorToString(
               Error errRef  )

Returns the String description associated with the specified Error. The Echo built-in function can display the text of an Error in the Debug window, by passing the Error to the function.

Parameters:
errRef  -  Specifies the Error whose String is returned. This Error can be a system Error, or an Error created using Error.Define().
Returns:
The String associated with the Error.
o Get 
 Error Get(
         Integer status  )

Gets the corresponding Error value.

Parameters:
status  -  An Integer Error status.
Returns:
The Error corresponding to the specified status, if found; otherwise Error.E_NoSuchError.
o Id 
 Integer Id(
           Dynamic errRef )

Returns the Integer status value associated with the specified Error.

Passed a value of type Error that was created by Error.Define(), this returns the Integer status parameter defined for the Error.

Parameters:
errRef  -  Specifies an Error value for which the status is returned.
Returns:
The ID number for the specified Error.
o IntToError 
 Error IntToError(
               Integer errID )

Returns an Error whose id is the specified integer errID.

Parameters:
errID  -  Specifies the ID of the error that will be created.
Returns:
An Error whose ID is that passed in Integer.