home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 196.lha / Exception_v0.6 / excption.doc < prev    next >
Text File  |  1988-12-27  |  7KB  |  326 lines
  1.         TABLE OF CONTENTS (not in order)
  2.  
  3.  
  4.              Version 0.6
  5.             July 6th, 1988
  6.  
  7.  
  8. excption/EIRaise
  9. excption/EIBlow
  10. excption/AllocException
  11. excption/FreeException
  12. excption/EIInit
  13. excption/EIUnmount
  14. excption/ExcpDisable
  15. excption/ExcpEnable
  16. excption/EIEndHand       -- Not Documented
  17. excption/EIExcpHandler   -- Not Documented
  18.  
  19. excption/EIInit
  20.  
  21. NAME
  22.     EIInit -- set excption handler
  23.  
  24. SYNOPSIS
  25.     void EIInit(anchor)
  26.  
  27.     E_ErrorStatus *anchor;
  28.  
  29. FUNCTION
  30.     This function must be called to set the data structures used
  31.     by the exception handler. This routine will install the first
  32.     protected zone.
  33.  
  34. INPUTS
  35.     anchor -- an pointer to an non filled E_ErrorStatus structure.
  36.  
  37. RESULT
  38.         none -- initialization always succeeds.
  39.  
  40. BUGS
  41.     None known
  42.  
  43. SEE ALSO
  44.     EIUnmount()
  45.  
  46. AUTHOR
  47.     HEWES
  48.  
  49. DATE    
  50.     880508 HEW First documented version
  51.  
  52. excption/EIUnmount
  53.  
  54. NAME
  55.     EIUnmount -- dismount/terminate excption handler
  56.  
  57. SYNOPSIS
  58.     void EIUnmount(anchor)
  59.  
  60.     E_ErrorStatus *anchor;
  61.  
  62. FUNCTION
  63.     This function dismounts the exception handler. It disables the
  64.     exception anchor structure, and installs the default trap code
  65.     which existed before the exception handler was installed.
  66.  
  67. INPUTS
  68.     anchor -- an pointer to a initialised E_ErrorStatus structure.
  69.  
  70. RESULT
  71.         none -- unmount always succeeds.
  72.  
  73. BUGS
  74.     None known
  75.  
  76. SEE ALSO
  77.     EIInit()
  78.  
  79. AUTHOR
  80.     HEWES
  81.  
  82. DATE    
  83.     880508 HEW First documented version
  84.  
  85. excption/EIRaise
  86.  
  87. NAME
  88.     EIRaise -- raise and/or propagate an exception
  89.  
  90. SYNOPSIS
  91.     void EIRaise(anchor,class)
  92.  
  93.     E_ErrorStatus *anchor;
  94.         ExcpClass class;
  95.  
  96. FUNCTION
  97.     In a protected code zone, EIRaise raises an exception transferring
  98.     program to current exception handler code.
  99.     In a handler code zone, propagates to the next level handler code
  100.     zone. This is used to propagate an exception which cannot be
  101.     treated locally.
  102.  
  103.     Raising in the top level handling code brutally calls the exit
  104.     function. You are responsible for your own handling, including
  105.     non-planned exceptions.
  106.  
  107.     Warning : if your the exception data is corrupted, ie the magic number
  108.     is not correct, then exit is brutaly called with either a exit
  109.     value of 200 or 201 depending on the context. This error occurs
  110.     either if all the amiga is corrupted, but most often it happens
  111.     if you have not respected the BEGIN/EXCEPTION/END format. Forgetting
  112.     the END statement is a good example.
  113. INPUTS
  114.     anchor -- an pointer to a initialised E_ErrorStatus structure.
  115.     class  -- Class number of exception. Values 1 - 65535 are reserved.
  116. RESULT
  117.         none -- control does not resume after the call.
  118.     exit(200) or exit(201) if corrupted data.
  119. BUGS
  120.     None known
  121.  
  122. SEE ALSO
  123.  
  124. AUTHOR
  125.     HEWES
  126.  
  127. DATE    
  128.     880508 HEW First documented version
  129.         880517 HEW protected the puts around an #if DEBUG for pgm
  130.                    with no stderr.
  131.  
  132. excption/EIBlow
  133.  
  134. NAME
  135.     EIBlow -- blow up to top level
  136.  
  137. SYNOPSIS
  138.     void EIBlow(anchor,class)
  139.  
  140.     E_ErrorStatus *anchor;
  141.         ExcpClass class;
  142.  
  143. FUNCTION
  144.     Similar to EIRaise, but gives control to the top level handler code
  145.     zone, thus the name blow. This is a pretty dramatic function.
  146.  
  147.     Warning: the same warning applies to this function as for EIRaise
  148.     concerning corrupted data. The exit is called with the value 203.
  149. INPUTS
  150.     anchor -- an pointer to a initialised E_ErrorStatus structure.
  151.     class  -- Class number of exception. Values 1 - 65535 are reserved.
  152. RESULT
  153.         none -- control does not resume after the call.
  154.         exit(203) if data corrupted.
  155. BUGS
  156.     Never Tested.
  157.  
  158. SEE ALSO
  159.  
  160. AUTHOR
  161.     HEWES
  162.  
  163. DATE    
  164.     880508 HEW First documented version
  165.         880517 HEW protected the puts around an #if DEBUG for pgm
  166.                    with no stderr.
  167.  
  168. excption/AllocException
  169.  
  170. NAME
  171.     AllocException -- Allocates an unique exception number
  172.  
  173. SYNOPSIS
  174.     result =  AllocException(number)
  175.  
  176.         ExcpClass number;
  177.     ExcpClass result;
  178.  
  179. FUNCTION
  180.     Allocates an unique exception number for use by the handler.
  181.  
  182.     Currently two incompatible ways to use exceptions are possible.
  183.     Either, the programmer #define's all his exceptions, and thereby
  184.     is responsible for their uniqueness.
  185.     Either, the programmer uses Alloc and Free exception to get unique
  186.     numbers. 
  187.     These two methods are incompatible because AllocException is
  188.     unaware of your #define's.
  189.  
  190.     In all case exception class numbers must be over 65535. Under the
  191.     numbers are reserved for various other libraries currently under
  192.     developement.
  193.  
  194.     Under version 0.4, AllocExcption just allocates numbers starting
  195.     from 65536, and increments by one at each call.
  196.  
  197.     One day, in the future, this allocation may function in a more 
  198.         Amiga-like fashion (see Trap Allocation in RKM).
  199.  
  200. INPUTS
  201.     number -- MUST be -1 with version 0.4
  202.  
  203. RESULT
  204.     result -- returns a positive number if success,
  205.                   or -1 if failure.     
  206.  
  207. BUGS
  208.     None Known
  209.  
  210. SEE ALSO
  211.     FreeException()
  212.  
  213. AUTHOR
  214.     HEWES
  215.  
  216. DATE    
  217.     880508 HEW First documented version
  218.  
  219. excption/FreeException
  220.  
  221. NAME
  222.     FreeException -- Free an exception number
  223.  
  224. SYNOPSIS
  225.     void FreeException(number)
  226.  
  227.         ExcpClass number;
  228.  
  229. FUNCTION
  230.     Free an allocated exception number for later use.
  231.  
  232.     Under version 0.4, FreeException does ABSOLUTELY nothing.
  233.  
  234.     One day, in the future, this allocation may function in a more 
  235.         Amiga-like fashion (see Trap Allocation in RKM).
  236.  
  237. INPUTS
  238.     number -- Valid allocated exception number.
  239.  
  240. RESULT
  241.         None
  242.  
  243. BUGS
  244.     None Known, just a nice return!
  245.  
  246. SEE ALSO
  247.     AllocException()
  248.  
  249. AUTHOR
  250.     HEWES
  251.  
  252. DATE    
  253.     880508 HEW First documented version
  254.  
  255. excption/ExcpDisable
  256.  
  257. NAME
  258.     ExcpDisable -- Disable processor errors capture
  259.  
  260. SYNOPSIS
  261.     void ExcpDisable(anchor)
  262.  
  263.         E_ErrorStatus *anchor;
  264.  
  265. FUNCTION
  266.     Disables the use of the provided processor errors handler.
  267.     This means that these events: 680x0 exception, traps and interrupts
  268.     will not be captured by the software. This is useful if you wish
  269.     to debug your code with an external debugger such as Wack. If this
  270.     is not done, your errors will be invisible to your debugger, and
  271.     thus impossible to find the error.
  272.  
  273.     Default status is error handler in use.
  274.  
  275. INPUTS
  276.     anchor -- an pointer to a initialised E_ErrorStatus structure
  277.  
  278. RESULT
  279.         None
  280.  
  281. BUGS
  282.     Never tested
  283.  
  284. SEE ALSO
  285.     ExcpEnable()
  286.  
  287. AUTHOR
  288.     HEWES
  289.  
  290. DATE    
  291.     880706 HEW First documented version V0.6
  292.  
  293. excption/ExcpEnable
  294.  
  295. NAME
  296.     ExcpEnable -- Enable processor errors capture
  297.  
  298. SYNOPSIS
  299.     void ExcpEnable(anchor)
  300.  
  301.         E_ErrorStatus *anchor;
  302.  
  303. FUNCTION
  304.     Enables software capture of processor errors such as 680X0 exceptions,
  305.     traps, and interrupts. This function is to be used after an ExcpDisable
  306.     call.
  307.  
  308.     Default status is error handler in use.    
  309. INPUTS
  310.     anchor -- an pointer to a initialised E_ErrorStatus structure
  311.  
  312. RESULT
  313.         None
  314.  
  315. BUGS
  316.     None Known, just a nice return!
  317.  
  318. SEE ALSO
  319.     ExcpDisable()
  320.  
  321. AUTHOR
  322.     HEWES
  323.  
  324. DATE    
  325.     880706 HEW First documented version V0.6
  326.