Click above to get retro games delivered to your door ever month!

Overview -- The Runtime Error System


   In Clipper Summer '87, there are two categories of runtime errors:
   recoverable and non-recoverable.  Recoverable errors are divided into
   classes with each class having an associated error recovery
   function.  The classes are as follows:

      . Database error
      . Expression error
      . Miscellaneous error
      . Print error
      . Open error
      . Undefined error

   The default low-level error handling functions supplied in
   CLIPPER.LIB are written in Clipper.  The source code for these
   functions is provided in the file Errorsys.prg.  If you wish to
   supply more extensive runtime error handling you may modify or
   rewrite the functions in Errorsys.prg.  The new functions can be
   compiled with Clipper and linked within your application as
   replacements for the default functions in CLIPPER.LIB.

   Also included are debugging versions of the low-level error function
   in Alterror.prg.  Each of the functions in this file provide
   facilities that are useful during the debugging phase of a program.
   To substitute new low-level error functions for those found in
   CLIPPER.LIB, you can link a new ERRORSYS.OBJ, ALTERROR.OBJ, or a new
   error function by itself.  The only provision is that you link your
   main program first before any of the object files.


--------------------------- Error Function Structure -----------------------

   Automatic Parameters

   All of the low-level error handling functions share a common
   parameter structure.  When one of the functions is called, it is as
   if the following code has been executed:

      xxx_error(name, line, info [, model [, _1 [, _2;
         [, _3 [, _4 [, _5]]]]]])

   All of the functions are called with the "name," "line," and "info"
   parameters.  The other parameters may or may not be passed to a
   particular error function.


   Name Parameter 

   The "name" parameter contains a character type value.  The value is
   equal to the name of the procedure or function which was executing
   when the error occurred.


   Line Parameter

   The "line" parameter contains a numeric value.  The value is equal to
   the source code line number of the statement which caused the error.
   Note that this line number is relative to the beginning of the source
   file, not the start of the function or procedure.  If the source file
   was compiled with the -l option (line numbers disabled), this
   parameter will contain zero.


   Info Parameter

   The "info" parameter contains a character type value.  The value
   consists of information about the error.  The information consists of
   a descriptive phrase (e.g., "Type error") optionally followed by
   information describing the situation of the error (e.g., ("In
   macro")).  The additional information, if supplied, is surrounded by
   parentheses.


   Model Parameter 

   The "model" parameter, if supplied, contains a character string.  The
   value consists of a fragment of Clipper source code illustrating the
   operation which caused the error.  Note that the fragment is not
   identical to the original source code which caused the error.  The
   fragment can be used with the operand parameters to reconstruct the
   operation which caused the error.


   Operand Parameters

   The "_1," "_2," etc. parameters, if supplied, may contain values of
   any type, depending on the circumstances of the error.  These values
   are equal to the values which were supplied to the Clipper operation
   which failed.

   Note that, although they are unusual, the names "_1," "_2," etc. are
   valid Clipper identifier names.  These names were chosen to avoid
   conflicts with identifiers in your application.


------------------------------ Recovery Strategy ---------------------------

   Using the automatic parameters passed, you can construct a strategy
   to recover from these errors.  In addition to the automatic
   parameters there are several support functions you can use.  They are
   as follows:


   PROCNAME()

   You can use this function to identify, display, or pass as an
   argument to another user-defined function, the name of the error
   function called.


   DOSERROR()

   DOSERROR() returns the current error number.  You will find this
   function useful for determining the cause of a RUN error.  The DOS
   error will tell you whether the problem lies with the location of
   COMMAND.COM or with there not being enough memory to RUN the
   specified program.


   ALTD()

   This function invokes the Clipper Debugger.  There are two modes
   appropriate for use within an error function.  The first, and most
   commonly used in the default error functions, is ALTD(2) which
   invokes the Debugger displaying the Variable:View Privates screen.
   The second mode, and most useful for interactive debugging, is ALTD()
   with no argument.  Invoking the Debugger in this mode displays the
   last screen accessed.  Ideally, you will have set the screen you want
   to display next and then resume execution of your program using the
   Alt-G speed key to Control:Go.


   BEGIN SEQUENCE...BREAK...END

   This command is a control structure you can use to pass control from
   an error function to a local error handler.  The basic idea is to
   block the commands that are most likely to generate a runtime error
   (device and printer errors) with the BEGIN SEQUENCE...END control
   structure statements.  Then place the local error handler statements
   immediately following the END statement.  In the appropriate error
   function, place a BREAK where you want control to branch to the END
   statement in the procedure that initiated the error.

   For example, suppose you are performing a printing operation and you
   want to control the recovery of runtime printing errors in the
   routine that is performing the printing operation.  There are several
   reasons for doing this.  The recovery strategy for a print error when
   printing labels is likely to be much different than when printing a
   statistical or accounting report.  In the former case, rolling back
   the record pointer to reprint a set of labels when the printer jams
   is an appropriate part of the recovery strategy, but when printing
   reports, it is not.  You may need, therefore, to define a recovery
   strategy for each type of printing operation.  BEGIN
   SEQUENCE...BREAK...END allows you to do this by branching from the
   error function back to your program where you can call a local
   recovery procedure.

   To set this up, create a procedure structured like the following for
   each print operation where you want local recovery of print errors:

      PROCEDURE PrintLabel
      PARAMETER lbl_file
      *
      ok = .T.
      error_state = .F.
      local_err = .T.
      *
      DO WHILE ok
         BEGIN SEQUENCE
            LABEL FORM (lbl_file) REST TO PRINT
         END
         *
         IF error_state
            ok = Label_recover()    && Recovery routine.
            error_state = .F.
         ELSE
            ok = .F.
         ENDIF
         *
      ENDDO
      RETURN

   Then create a recovery procedure as a user-defined function that
   returns true (.T.) if you want to continue or false (.F.) if you want
   to quit the printing operation.  In the recovery user-defined
   function, you can present a menu that allows the user to continue,
   quit, rollback the record pointer, view sample labels, or BREAK to a
   higher-level procedure.

   Lastly, change your Print_error() function to include the following
   lines of code:

      FUNCTION Print_error
      PARAMETERS name, line
      *
      IF local_err
         error_state = .T.
         BREAK
      ENDIF
      *
      <rest of error function>...

   This example, of course, does not present an all-encompassing
   strategy for all situations, but it does indicate one way to use
   BEGIN SEQUENCE...BREAK...END to control the environment of runtime
   errors.


   Return Method

   The RETURN argument of the error function determines the action taken
   by Clipper when the error function terminates.

   . For some classes of errors, the error function can RETURN control
     to the command that instigated the error.  With this type of error
     function, RETURNing true (.T.) forces a retry of the operation that
     instigated the error condition.  RETURNing false (.F.) terminates
     the pending operation and passes control to the next intermediate
     code in the program.

   . For classes of errors that are more severe, RETURNing true (.T.)
     will retry, but RETURNing false (.F.) causes Clipper to QUIT.  When
     this is the case, Clipper CLOSEs ALL open files.

   . For expression errors, the RETURN value is substituted for the term
     in which the error occurred.  For example, if you attempt to
     evaluate the following expression containing a divide by zero
     error:

         12 + (12 / 0)

     The expression error occurs within the term (12 / 0).  If you
     RETURN 1, the result of the expression is 13.