home *** CD-ROM | disk | FTP | other *** search
/ Really Useful CD 1 / ReallyUsefulCD1.iso / extras / progutils / error / readme < prev   
Encoding:
Text File  |  1991-04-22  |  3.8 KB  |  109 lines
  1. Error
  2.  
  3. Legal stuff...
  4.  
  5. The Error module is in the Public Domain, and may be freely copied and
  6. distributed on the following conditions:
  7.  
  8. 1. It is supplied complete with this documentation, and neither is altered
  9.    in any way, shape or form.
  10. 2. The program remains the exclusive property of Armen Software.
  11. 3. We get a mention in the credits of any program that uses it.
  12.  
  13. I don't mind if it gets used in commercial programs.
  14.  
  15. Overview
  16.  
  17. When writing WIMP applications, safeguarding the user's data 
  18. must be a priority. Therefore, when an error such as a machine 
  19. exception occurs, the task must not quit instantly without the user's 
  20. permission. The problem is, though, that these fatal errors 
  21. instantly cause BASIC programs to end. What the Error module is 
  22. designed for is changing these fatal errors into normal manageable 
  23. errors before BASIC gets to hear about it and quits the task.
  24.  
  25. Technical information
  26.  
  27. Error can be in one of two states: Error_Fatal and 
  28. Error_Severe. If in the Error_Fatal state, all fatal errors 
  29. behave normally, allowing applications to perform their error-
  30. trapping in the manner it was originally written. In the 
  31. Error_Severe state, however, if a fatal error (which is 
  32. signified by an error number higher than &80000000) is discovered, 
  33. the error number is stored in Error's workspace, and the error 
  34. number is then changed to the value &804700, which is a perfectly 
  35. acceptable everyday error number. If the task is interested, the 'real' 
  36. error number (the original one) may be discovered by a call to SWI 
  37. Error_LastError.
  38.  
  39. The current state of the Error module is determined by a counter in 
  40. Error's workspace. If the count is zero, the Error_Fatal state is 
  41. adopted, if non-zero, the Error_Severe state is used (this is to 
  42. allow correct nesting of calls to the module to change the state).
  43. Error should be left in the Error_Fatal state during calls to 
  44. Wimp_Poll, to allow other tasks to perform their own trapping of 
  45. 'fatal' errors. Therefore, a possible example code fragment is as 
  46. follows:
  47.  
  48. SYS "Error_Severe"
  49. REPEAT
  50.         SYS "Error_Fatal"
  51.         SYS "Wimp_Poll" TO reason%
  52.         SYS "Error_Severe"
  53.         PROCaction(reason%)
  54. UNTIL quit%
  55. SYS "Wimp_CloseDown"
  56. SYS "Error_Fatal"
  57. END
  58.  
  59. SWI calls
  60.  
  61. Error_Fatal
  62. (SWI &427C0)
  63.  
  64. Switches Error into the Error_Fatal state.
  65.  
  66. On entry        -
  67. On exit         All registers preserved.
  68. Interrupts      Interrupt status is undefined.
  69. Processor mode  Processor is in SVC mode.
  70. Re-entrancy     Re-entrancy is undefined.
  71. Use             This call decrements Error's internal count, which will 
  72.                 normally switch the module into the Error_Fatal state. If 
  73.                 the count is already zero, then an error is returned.
  74. Related SWIs    Error_Severe (SWI &427C1).
  75. Related vectors None.
  76.  
  77. Error_Severe
  78. (SWI &427C1)
  79.  
  80. Puts Error into the Error_Severe state.
  81.  
  82. On entry        -
  83. On exit         All registers preserved.
  84. Interrupts      Interrupt status is undefined.
  85. Processor mode  Processor is in SVC mode.
  86. Re-entrancy     Re-entrancy is undefined.
  87. Use             This call increases Error's internal count, which will place
  88.                 it  in Error_Severe mode. In order to cancel a call to
  89.                 Error_Severe, it is necessary to call Error_Fatal as  many
  90.                 times as Error_Severe has been called (see the example
  91.                 given in the Technical information above). 
  92. Related SWIs    Error_Fatal (SWI &427C0). 
  93. Related vectors None.
  94.  
  95. Error_LastError
  96. (SWI &427C2)
  97.  
  98. Returns the number of the last 'fatal' error trapped by Error.
  99.  
  100. On entry        -
  101. On exit         R0 = error number. 
  102. Interrupts      Interrupt status is undefined.
  103. Processor mode  Processor is in SVC mode.
  104. Re-entrancy     Re-entrancy is not defined. 
  105. Use             This SWI enables you to find out exactly which error the
  106.                 module has trapped without tedious comparison of strings.
  107. Related SWIs    None.
  108. Related vectors None.
  109.