home *** CD-ROM | disk | FTP | other *** search
/ World of Shareware - Software Farm 2 / wosw_2.zip / wosw_2 / PASCAL / TBTREE16.ZIP / ERROR.PAS < prev    next >
Pascal/Delphi Source File  |  1989-07-13  |  12KB  |  199 lines
  1. (* TBTree16             Copyright (c)  1988,1989       Dean H. Farwell II    *)
  2.  
  3. unit Error;
  4.  
  5. (*****************************************************************************)
  6. (*                                                                           *)
  7. (*                E R R O R   H A N D L I N G    R O U T I N E S             *)
  8. (*                                                                           *)
  9. (*****************************************************************************)
  10.  
  11. (* This unit is designed to handle a few of the errors which can occur within
  12.    TBTREE.  Specifically, it handles I/O errors.  Before explaining this unit,
  13.    I want to talk about the philosophy of error handling.  There is a tradeoff
  14.    to be made when developing error handlers for a product such as TBTREE.  I
  15.    could try to handle every possible error which could ever occur and try to
  16.    figure out what to do to handle the error.  Although this would seem to
  17.    make it easier for the user of these routines, it would make my life very
  18.    difficult.  More importantly, it would put a tremendous amount of overhead
  19.    into the program which would invariably slow it down, in most cases
  20.    unnecessarily.  On the other hand, I could do no error checking whatsoever
  21.    which means that you must develop your application with error checking in
  22.    mind and preclude any errors from happening.  In this way, you could
  23.    customize the error checking to your application and ensure that errors do
  24.    not occur.  For example, you could make sure that you do not call my
  25.    routines with values which are out of range.  This way, you only need the
  26.    overhead which is absolutely required and can handle errors in more of a
  27.    specific way.  I have taken a middle of the road approach although I lean
  28.    more towards the second approach.  There are certain types of errors which
  29.    I need to report to you to allow you to try to fix them.  I/O errors fall
  30.    into this category.  I supply a routine which gets called when an I/O error
  31.    occurs.  This routine makes up the bulk of this unit.  It is supplied as
  32.    part of this unit but is intended to be modified by the user as required.
  33.    You should set it up so that it handles errors in a manner which makes
  34.    sences in your application.  The routine it self has further explanation.
  35.    When an error occurs and I call the routine, I pass back information which
  36.    can be used to solve the problem.  When the routine is finished, it will
  37.    return back to where the error occurred. What happens then depends on the
  38.    error routine called.  Again, further explanation accompanies the error
  39.    routine.
  40.  
  41.    It should be noted that, like in previous versions, the bulk of the error
  42.    checking is up to you.  You need to ensure that parameters are in range
  43.    before calls are made, indexes and data files exist before manipulating
  44.    them, file names are legal prior to creating a file, etc.                 *)
  45.  
  46. (* Version Information
  47.  
  48.    Version 1.5 - Unit added to TBTREE
  49.  
  50.    Version 1.6 - No Changes                                                  *)
  51.  
  52. (*\*)
  53. (*////////////////////////// I N T E R F A C E //////////////////////////////*)
  54.  
  55. interface
  56.  
  57. type
  58.     RoutineNameString = String[50];           (* Used as type to provide the
  59.                                                  routine name where the error
  60.                                                  occured.  Remember, these are
  61.                                                  strings and are case
  62.                                                  sensitive!                  *)
  63.  
  64.     IOErrorRec = record
  65.                  routineName : RoutineNameString;
  66.                  tBTreeIOResult : Word;
  67.                  end;
  68.  
  69. (*\*)
  70. (* This routine will handle disk I/O errors which occur within TBTREE.  Since
  71.    all disk I/O calls are concentrated either in the FILEBUFF unit or the PAGE
  72.    unit, this will trap all disk I/O error calls which occur.  Errors are
  73.    trapped because I/O checking is turned off in the FILEBUFF unit and in the
  74.    PAGE unit.  Instead, the Turbo Pascal routine IOResult is called after each
  75.    I/O operation.  If a value other than 0 is returned, an error has occurred
  76.    and this routine is called.  When the routine is called, the ioErrorRec
  77.    contains the name of the TBTREE routine which contained the error and the
  78.    error code returned as a result of the call to IOResult.  Using this
  79.    information, you can decide what to do.  You actually have two options.
  80.    First you can cause the program to terminate by either forcing an error or
  81.    by using Halt;  The program will terminate after running through the exit
  82.    routines.  If any exit routines do I/O (which they probably do) another
  83.    error could occur.  If this happens, this routine will be called again. The
  84.    second option is to try to handle the error, depending on what it is. How
  85.    to correct the error is entirely up to you and your application.  Once you
  86.    have solved the problem, your routine will terminate and control will
  87.    return to the place where the error occurred.  The operation which caused
  88.    the error routine  to be called will be repeated.  If you solved the
  89.    condition which caused the error, the program will roll merrily along as if
  90.    no error ever occurred.  If the error occurs again, this routine will be
  91.    called again.  This will continue until you halt or fix the error
  92.    condition.  As you can see, this could be the world's best infinite loop
  93.    generator if you do not do something to make sure that a fix is only
  94.    attempted a finite number of times.  The right thing to do is application
  95.    specific.  The reason for forcing the repeat is very fundamental.  A disk
  96.    operation, especially a write, which does not complete successfully is
  97.    absolutely a catastrophe.  Either you fix the condition, or you terminate.
  98.    Now you might be asking .. So what good is this?  Well, it is available to
  99.    handle catastrophic errors such as Disk Full, etc. It should be used to
  100.    only handle catastrophic problems which are hard to protect against.  Think
  101.    of it as a last ditch chance to solve a problem before terminating (which
  102.    happened automatically in previous versions).  It should never be used for
  103.    mundane activities like checking for the existence of a file etc.  There is
  104.    an explicit routine available which will check for the existence of a file.
  105.    If you are creating a file, you should check to ensure that it is a valid
  106.    file name prior to calling the creation routine, etc.  Your application
  107.    should be written such that you do not do an access to a nonexistent index
  108.    or data file. These checks are very application specific and should be
  109.    handled by you rather than in TBTREE.
  110.  
  111.    The routine, as written, will simply Halt and write an error message if an
  112.    error occurs.  You will probably want to change it for your application.
  113.  
  114.    Presently, the only legal values for ioErrRec.routineName are as follows:
  115.  
  116.           FILEBUFF unit :
  117.                           'CloseFile'
  118.                           'RewriteUntypedFile'
  119.                           'OpenUntypedFile'
  120.                           'RewriteTextFile'
  121.                           'OpenTextFile'
  122.                           'AppendTextFile'
  123.           PAGE unit :
  124.                           'WriteToDisk'
  125.                           'ReadFromDisk'                                     *)
  126.  
  127. procedure UserIOError(ioErrRec : IOErrorRec);
  128. (*!*)
  129. (*\*)
  130. (*///////////////////// I M P L E M E N T A T I O N /////////////////////////*)
  131.  
  132. implementation
  133.  
  134. (* This routine will handle disk I/O errors which occur within TBTREE.  Since
  135.    all disk I/O calls are concentrated either in the FILEBUFF unit or the PAGE
  136.    unit, this will trap all disk I/O error calls which occur.  Errors are
  137.    trapped because I/O checking is turned off in the FILEBUFF unit and in the
  138.    PAGE unit.  Instead, the Turbo Pascal routine IOResult is called after each
  139.    I/O operation.  If a value other than 0 is returned, an error has occurred
  140.    and this routine is called.  When the routine is called, the ioErrorRec
  141.    contains the name of the TBTREE routine which contained the error and the
  142.    error code returned as a result of the call to IOResult.  Using this
  143.    information, you can decide what to do.  You actually have two options.
  144.    First you can cause the program to terminate by either forcing an error or
  145.    by using Halt;  The program will terminate after running through the exit
  146.    routines.  If any exit routines do I/O (which they probably do) another
  147.    error could occur.  If this happens, this routine will be called again. The
  148.    second option is to try to handle the error, depending on what it is. How
  149.    to correct the error is entirely up to you and your application.  Once you
  150.    have solved the problem, your routine will terminate and control will
  151.    return to the place where the error occurred.  The operation which caused
  152.    the error routine  to be called will be repeated.  If you solved the
  153.    condition which caused the error, the program will roll merrily along as if
  154.    no error ever occurred.  If the error occurs again, this routine will be
  155.    called again.  This will continue until you halt or fix the error
  156.    condition.  As you can see, this could be the world's best infinite loop
  157.    generator if you do not do something to make sure that a fix is only
  158.    attempted a finite number of times.  The right thing to do is application
  159.    specific.  The reason for forcing the repeat is very fundamental.  A disk
  160.    operation, especially a write, which does not complete successfully is
  161.    absolutely a catastrophe.  Either you fix the condition, or you terminate.
  162.    Now you might be asking .. So what good is this?  Well, it is available to
  163.    handle catastrophic errors such as Disk Full, etc. It should be used to
  164.    only handle catastrophic problems which are hard to protect against.  Think
  165.    of it as a last ditch chance to solve a problem before terminating (which
  166.    happened automatically in previous versions).  It should never be used for
  167.    mundane activities like checking for the existence of a file etc.  There is
  168.    an explicit routine available which will check for the existence of a file.
  169.    If you are creating a file, you should check to ensure that it is a valid
  170.    file name prior to calling the creation routine, etc.  Your application
  171.    should be written such that you do not do an access to a nonexistent index
  172.    or data file. These checks are very application specific and should be
  173.    handled by you rather than in TBTREE.
  174.  
  175.    The routine, as written, will simply Halt and write an error message if an
  176.    error occurs.  You will probably want to change it for your application.
  177.  
  178.    Presently, the only legal values for ioErrRec.routineName are as follows:
  179.  
  180.           FILEBUFF unit :
  181.                           'CloseFile'
  182.                           'RewriteUntypedFile'
  183.                           'OpenUntypedFile'
  184.                           'RewriteTextFile'
  185.                           'OpenTextFile'
  186.                           'AppendTextFile'
  187.           PAGE unit :
  188.                           'WriteToDisk'
  189.                           'ReadFromDisk'                                     *)
  190.  
  191. procedure UserIOError(ioErrRec : IOErrorRec);
  192.  
  193.     begin
  194.     Writeln('Catestrophic I/O error --->> ',ioErrRec.tBTreeIOResult);
  195.     Halt;
  196.     end;
  197.  
  198. end.                                                    (* end of Error unit *)
  199.