Error Object

The host Error object will have various properties and methods to detail errors in the code that are tracked, indicated, and handled using try, throw, and catch. Some properties of the Error object will be determined by arguments to the throw; others will be determined by the context from which the throw occurs. File and line information is automatically set when the Error object is created. object, description, and id are set by the arguments to the Error constructor.

Errors that do not belong to a specific object will be defined as properties directly on the prototype Error object. See the Errors list for details. Exceptions that are generated for specific objects are also listed there.

Constructor

Error(id, description, object)

Construct and return a new Error object instance. Specifies the id, the description, and the object name for a new Error object instance. Instance properties help track errors and exit from failed functions that otherwise would terminate a program. The instance properties filename and linenumber are generated automatically when the object instance is created.

Instance Properties

object	The object that generates the error, i.e., the called object that failed.
description	String describing why the function call failed.
id	A number that uniquely identifies the error.
filename	If applicable, the file that contains the script which generated the error.
linenumber	If applicable, the line number within the filename above that generated the error.

Prototype Properties

Errors

Object containing properties for all default error ids. Note that the Error Object's Errors property, i.e., Error.Errors, has the alias "Errors" so that, for example, Error.Errors.GeneralFailure can be written simply as Errors.GeneralFailure.

Prototype Methods

getErrorName()

Returns the error name for a given error.

The first example demonstrates usage of the Error constructor:

   function throw_error_obj()
   {
      var obj = new Object();
      throw(Error(Errors.GeneralFailure, 'hello', obj));
   }

The example below demonstrates error handling using the Error object.

   webcall function find_file(filename)
   {
   var folder_obj = new Folder("/");
   if (!filename)
      throw Error(Errors.InvalidParameter, 
         "Missing parameter 'filename'.", "find_file");
   try
   {
      var folder_name = find_file_helper(folder_obj, filename);
      if (folder_name)
          response.write("file '"+filename+"' found in folder '" + 
             folder_name +"'.");
      else
         response.write("file '" + filename+"' could not 
            be found in the web");
   }
   catch(e)
   {
      switch(e.id)
      {
         case Errors.InvalidName:
            response.write("You specified an invalid file name.");
            break;
         default:
            response.write("error "+Error.getErrorName(e.id)
               + " occurred in " + e.filename + " at line " 
               + e.linenumber);
      }
   }
   }

   function find_file_helper(folder_obj, filename)
   {
   if (!folder_obj)
      throw Error(Errors.InvalidParameter, 
         "Missing parameter 'folder_obj'", "find_file_helper");
   if (!filename)
      throw Error(Errors.InvalidParameter, 
         "Missing parameter 'filename'.", "find_file_helper");

   if (File.Exists(folder_obj.path + filename))
      return folder_obj.path;

   var sub_name_array = folder_obj.getFolderNames();
   for (var i = 0; i < sub_name_array .length; i++)
   {
      try
      {
         var sub_obj = folder_obj.getFolder(sub_name_array[i]);
         if (find_file_helper(sub_obj, filename))
            return sub_obj.path;
      }
      catch(e)
      {
         switch(e.id)
         {
            // if the folder doesn't exist, just move on, someone 
            //may have just deleted it
            case Errors.ObjectNotFound: 
               break;
         }
         //for any other errors, re-throw
         throw;
     }
     }
   return null;
   }