home *** CD-ROM | disk | FTP | other *** search
/ Piper's Pit BBS/FTP: ibm 0010 - 0019 / ibm0010-0019 / ibm0010.tar / ibm0010 / CLIPB51.ZIP / C5P78.EXE / ERROR.DOC next >
Encoding:
Text File  |  1990-05-26  |  6.2 KB  |  203 lines
  1. Notes on Clipper 5.0 runtime error handling.
  2.  
  3.  
  4. o The Error Block
  5.  
  6.   When an error occurs during execution of a compiled
  7.   application, an automatic code block evaluation occurs. 
  8.   The block that is executed is known as the "error block." 
  9.   A single parameter is passed to the error block when it is
  10.   evaluated.  The parameter consists of a Clipper 5.0 Error
  11.   object (see below).
  12.  
  13.  
  14.  
  15. o The ErrorBlock() function
  16.  
  17.   The error block can be set or queried at any time using
  18.   the ErrorBlock() function.  The syntax for ErrorBlock() is
  19.   shown here:
  20.  
  21.     ErrorBlock( [<bBlock>] )   <--  bCurrent
  22.  
  23.   Example:
  24.  
  25.     ErrorBlock( {|e| MyHandler(e)} )
  26.  
  27.  
  28.  
  29. o The Default Error Block
  30.  
  31.   A default error block is installed by ERRORSYS.PRG during
  32.   startup.  This block causes errors to execute the default
  33.   error handling code in ERRORSYS.PRG.
  34.  
  35.  
  36.  
  37. o Installing a New Error Block
  38.  
  39.   If a subsystem wishes to install its own error handling,
  40.   it should preserve the existing error block and restore it
  41.   on exit.  If the subsystem wishes to handle only a certain
  42.   class of errors, it may pass other errors to the
  43.   previously posted error block by evaluating it with the
  44.   error object as a parameter.
  45.  
  46.  
  47.  
  48. o Error objects
  49.  
  50.   Note:  for a general discussion of Clipper 5.0 predefined
  51.   objects, refer to the "Basic Concepts" chapter of the
  52.   documentation.
  53.   
  54.   An Error object is a simple object that contains
  55.   information pertaining to a runtime error.  Error objects
  56.   have no methods, only exported instance variables.  When a
  57.   runtime error occurs, a new Error object is created and
  58.   passed as a parameter to the runtime error handler.  The
  59.   Error object can then be queried to determine the nature
  60.   of the error condition.
  61.  
  62.  
  63.  
  64. o Exported Instance Variables
  65.  
  66.   args
  67.   
  68.   For argument errors, an array containing the arguments
  69.   that were supplied to the operator or function.  For other
  70.   errors, NIL.
  71.   
  72.   
  73.   canDefault
  74.   
  75.   A logical value indicating whether the subsystem can
  76.   perform default error recovery for the error condition.  A
  77.   value of true (.T.) indicates that default recovery is
  78.   available.  Availability of default handling, and the
  79.   actual default recovery strategy, depend on the subsystem
  80.   and the error condition.  The minimum action is simply to
  81.   ignore the error condition.
  82.   
  83.   Default recovery is requested by returning false (.F.)
  84.   from the error block invoked to handle the error.  Note:
  85.   canDefault is never true if canSubstitute is true.
  86.   
  87.   
  88.   canRetry
  89.   
  90.   A logical value indicating whether the subsystem can retry
  91.   the operation that caused the error condition.  A value of
  92.   true (.T.) indicates that retry is possible.  Retry may or
  93.   may not be available, depending on the subsystem and the
  94.   error condition.
  95.   
  96.   Retry is requested by returning true (.T.) from the error
  97.   block invoked to handle the error.  Note: canRetry is
  98.   never true if canSubstitute is true.
  99.   
  100.   
  101.   canSubstitute
  102.   
  103.   A logical value indicating whether a new result can be
  104.   substituted for the operation which produced the error
  105.   condition (argument errors and certain other simple errors
  106.   allow the error handler to substitute a new result value
  107.   for the failed operation).  A value of true (.T.) means
  108.   that substitution is possible.  
  109.   
  110.   The substitution is performed by returning the new result
  111.   value from the code block invoked to handle the error. 
  112.   Note: canSubstitute is never true if either canDefault or
  113.   canRetry is true.
  114.   
  115.   
  116.   cargo   (Assignable)
  117.   
  118.   This instance variable is a user-definable slot, allowing
  119.   arbitrary information to be attached to an Error object
  120.   and retrieved later.
  121.   
  122.   
  123.   description
  124.   
  125.   A character value containing a printable description of
  126.   the error condition.  A zero-length string indicates that
  127.   the subsystem does not provide a printable description for
  128.   the error.  If the genCode instance variable is non-zero,
  129.   a printable description is always available.
  130.   
  131.   
  132.   filename
  133.   
  134.   A character value containing the name originally used to
  135.   open the file associated with the error condition.  A
  136.   zero-length string indicates either that the error
  137.   condition is not associated with a particular file or that
  138.   the subsystem does not retain filename information.
  139.   
  140.   
  141.   genCode
  142.   
  143.   A numeric value containing a Clipper generic error code. 
  144.   Generic error codes allow default handling of similar
  145.   errors from different subsystems.  A value of zero
  146.   indicates that the error condition is peculiar to the
  147.   subsystem and doesn't correspond to any of the generic
  148.   error codes.
  149.   
  150.   
  151.   operation
  152.   
  153.   A character value containing a printable description of
  154.   the operation being attempted when the error occurred. 
  155.   For operators and functions, this is the name of the
  156.   operator or function.  For undefined variables or
  157.   functions, this is the name of the variable or function. 
  158.   A zero-length string indicates that the subsystem does not
  159.   provide a printable description of the operation.
  160.   
  161.   
  162.   osCode
  163.   
  164.   A numeric value containing the operating system error code
  165.   associated with the error condition.  A value of zero
  166.   indicates that the error condition was not caused by an
  167.   error from the operating system.
  168.   
  169.   
  170.   subCode
  171.   
  172.   A numeric value containing a subsystem-specific error
  173.   code.  A value of zero indicates that the subsystem does
  174.   not assign any particular number to the error condition.
  175.   
  176.   
  177.   subsystem
  178.   
  179.   A character value containing the name of the subsystem
  180.   that generated the error.  For errors in basic Clipper
  181.   operators and functions, the subsystem name "BASE" is
  182.   given.  For errors generated by a database driver, the
  183.   subsystem name is the name of the database driver.
  184.   
  185.   
  186.   tries
  187.   
  188.   A numeric value indicating the number of times the failed
  189.   operation has been attempted.  When canRetry is true
  190.   (.T.), this value can be used to limit the number of retry
  191.   attempts.  A value of zero indicates that the subsystem
  192.   does not track the number of times the operation has been
  193.   tried.
  194.  
  195.  
  196.  
  197. o Examples
  198.  
  199.   Refer to the file ERRORSYS.PRG in the SOURCE directory for
  200.   an example of an error block and associated runtime error
  201.   handler.
  202.  
  203.