home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / except2x.zip / except.ipf < prev    next >
Text File  |  1994-11-29  |  15KB  |  267 lines
  1. .*--------------------------------------------------------------------
  2. .* This file contains the tagged source for EXCEPT Package
  3. .*--------------------------------------------------------------------
  4.  
  5. :userdoc.
  6.  
  7. .*--------------------------------------------------------------------
  8. .* Provide a title for the title line of the main window
  9. .*--------------------------------------------------------------------
  10.  
  11. :title.Except Package
  12.  
  13. .*--------------------------------------------------------------------
  14. .* Allow only heading level 1 to appear in the contents window and
  15. .* specify no control area for pushbuttons
  16. .*--------------------------------------------------------------------
  17.  
  18. :docprof toc=1 ctrlarea=none.
  19.  
  20. .*--------------------------------------------------------------------
  21. .* Identify the heading level entries to be displayed in the contents
  22. .* window
  23. .*--------------------------------------------------------------------
  24.  
  25. :h1 id=content1 x=left y=top width=100% height=100% scroll=both
  26.     clear.Fatal Exceptions definition and values.
  27. :p.The except package has been designed to gather the necessary information
  28. when a fatal exception occurs. A fatal exception is an operating system defined
  29. class of error condition which causes the end of the thread and the process
  30. when it occurs.
  31. :p.The exceptions have a 32 bits value and are grouped by severity. The 2 first
  32. bits defined the severity. These 2 bits are set for a fatal exception. The most
  33. current exception when programming is the XCPT_ACCESS_VIOLATION (0xC0000005).
  34. :p. Portable, Fatal, Hardware-Generated Exceptions:
  35. :xmp.
  36.  ┌────────────────────────────────┬──────────────┬──────────────┐
  37.  │Exception Name                  │Value         │Related Trap  │
  38.  ├────────────────────────────────┼──────────────┼──────────────┤
  39.  │  XCPT_ACCESS_VIOLATION         │0xC0000005    │0x09, 0x0B,   │
  40.  │                                │              │0x0C, 0x0D,   │
  41.  │  ExceptionInfo[ 0 ] - Flags    │              │0x0E          │
  42.  │      XCPT_UNKNOWN_ACCESS  0x0  │              │              │
  43.  │      XCPT_READ_ACCESS     0x1  │              │              │
  44.  │      XCPT_WRITE_ACCESS    0x2  │              │              │
  45.  │      XCPT_EXECUTE_ACCESS  0x4  │              │              │
  46.  │      XCPT_SPACE_ACCESS    0x8  │              │              │
  47.  │      XCPT_LIMIT_ACCESS    0x10 │              │              │
  48.  │  ExceptionInfo[ 1 ] - FaultAddr│              │              │
  49.  ├────────────────────────────────┼──────────────┼──────────────┤
  50.  │XCPT_INTEGER_DIVIDE_BY_ZERO     │0xC000009B    │0             │
  51.  ├────────────────────────────────┼──────────────┼──────────────┤
  52.  │XCPT_FLOAT_DIVIDE_BY_ZERO       │0xC0000095    │0x10          │
  53.  ├────────────────────────────────┼──────────────┼──────────────┤
  54.  │XCPT_FLOAT_INVALID_OPERATION    │0xC0000097    │0x10          │
  55.  ├────────────────────────────────┼──────────────┼──────────────┤
  56.  │XCPT_ILLEGAL_INSTRUCTION        │0xC000001C    │0x06          │
  57.  ├────────────────────────────────┼──────────────┼──────────────┤
  58.  │XCPT_PRIVILEGED_INSTRUCTION     │0xC000009D    │0x0D          │
  59.  ├────────────────────────────────┼──────────────┼──────────────┤
  60.  │XCPT_INTEGER_OVERFLOW           │0xC000009C    │0x04          │
  61.  ├────────────────────────────────┼──────────────┼──────────────┤
  62.  │XCPT_FLOAT_OVERFLOW             │0xC0000098    │0x10          │
  63.  ├────────────────────────────────┼──────────────┼──────────────┤
  64.  │XCPT_FLOAT_UNDERFLOW            │0xC000009A    │0x10          │
  65.  ├────────────────────────────────┼──────────────┼──────────────┤
  66.  │XCPT_FLOAT_DENORMAL_OPERAND     │0xC0000094    │0x10          │
  67.  ├────────────────────────────────┼──────────────┼──────────────┤
  68.  │XCPT_FLOAT_INEXACT_RESULT       │0xC0000096    │0x10          │
  69.  ├────────────────────────────────┼──────────────┼──────────────┤
  70.  │XCPT_FLOAT_STACK_CHECK          │0xC0000099    │0x10          │
  71.  ├────────────────────────────────┼──────────────┼──────────────┤
  72.  │XCPT_DATATYPE_MISALIGNMENT      │0xC000009E    │0x11          │
  73.  │                                │              │              │
  74.  │  ExceptionInfo[ 0 ] - R/W flag │              │              │
  75.  │  ExceptionInfo[ 1 ] - Alignment│              │              │
  76.  │  ExceptionInfo[ 2 ] - FaultAddr│              │              │
  77.  ├────────────────────────────────┼──────────────┼──────────────┤
  78.  │XCPT_BREAKPOINT                 │0xC000009F    │0x03          │
  79.  ├────────────────────────────────┼──────────────┼──────────────┤
  80.  │XCPT_SINGLE_STEP                │0xC00000A0    │0x01          │
  81.  └────────────────────────────────┴──────────────┴──────────────┘
  82. :exmp.
  83. :p.Portable, Fatal, Software-Generated Exceptions:
  84. :xmp.
  85.  ┌────────────────────────────────┬──────────────┬──────────────┐
  86.  │Exception Name                  │Value         │Related Trap  │
  87.  ├────────────────────────────────┼──────────────┼──────────────┤
  88.  │XCPT_IN_PAGE_ERROR              │0xC0000006    │0x0E          │
  89.  │                                │              │              │
  90.  │  ExceptionInfo[ 0 ] - FaultAddr│              │              │
  91.  ├────────────────────────────────┼──────────────┼──────────────┤
  92.  │XCPT_PROCESS_TERMINATE          │0xC0010001    │              │
  93.  ├────────────────────────────────┼──────────────┼──────────────┤
  94.  │XCPT_ASYNC_PROCESS_TERMINATE    │0xC0010002    │              │
  95.  │                                │              │              │
  96.  │  ExceptionInfo[ 0 ] - TID of   │              │              │
  97.  │           terminating thread   │              │              │
  98.  ├────────────────────────────────┼──────────────┼──────────────┤
  99.  │XCPT_NONCONTINUABLE_EXCEPTION   │0xC0000024    │              │
  100.  ├────────────────────────────────┼──────────────┼──────────────┤
  101.  │XCPT_INVALID_DISPOSITION        │0xC0000025    │              │
  102.  └────────────────────────────────┴──────────────┴──────────────┘
  103. :exmp.
  104. :p. Non-Portable, Fatal Exceptions:
  105. :xmp.
  106.  ┌────────────────────────────────┬──────────────┬──────────────┐
  107.  │Exception Name                  │Value         │Related Trap  │
  108.  ├────────────────────────────────┼──────────────┼──────────────┤
  109.  │XCPT_INVALID_LOCK_SEQUENCE      │0xC000001D    │              │
  110.  ├────────────────────────────────┼──────────────┼──────────────┤
  111.  │XCPT_ARRAY_BOUNDS_EXCEEDED      │0xC0000093    │0x05          │
  112.  └────────────────────────────────┴──────────────┴──────────────┘
  113. :exmp.
  114. :p.Fatal Signal Exceptions:
  115. :xmp.
  116.  ┌────────────────────────────────┬──────────────┐
  117.  │Exception Name                  │Value         │
  118.  ├────────────────────────────────┼──────────────┤
  119.  │XCPT_SIGNAL                     │0xC0010003    │
  120.  │                                │              │
  121.  │  ExceptionInfo[ 0 ] - Signal   │              │
  122.  │                       Number   │              │
  123.  └────────────────────────────────┴──────────────┘
  124. :exmp.
  125. :p.When investigating an exception caused by your code you first need to know
  126. where it occurred.
  127. :p.Exception handlers
  128. :h1 id=content2 x=left y=top width=100% height=100% scroll=both
  129.     clear.Exception Handlers and investigating fatal exception
  130. :p.Exception handlers are OS/2 2.x programming facilities which allow the
  131. programmer to act when the exception occur.
  132. :p.There must be at least one exception handler defined per thread of the
  133. process to handle the exceptions which may occur in that thread.
  134. :p.The exception handler is a callback function which gets called with
  135. several parameter among which a pointer to CONTEXTRECORD which contains
  136. all the thread and register information at the time the failure occurred.
  137. :p.Some of the registers are essential to investigate the TRAPs.
  138. :dl tsize=20.
  139. :dt.CS:dd.This is the code segment register. Its value is the current code
  140. segment being executed. If the application is a 16&colon.16 bit segmented code is
  141. must be matched to one of the .EXE objects  orone of the DLLs code object in
  142. memory at that time. For 32 bit linear code (C-Set/2 C-Set++) CS contains the
  143. value of the OS/2 segment mapping all executable user memory.
  144. :dt.IP or EIP:dd.IP or EIP (resp. 16&colon.16 or 32 code) is the segment containing
  145. the instruction pointer which is the offset from the beginning of the segment
  146. of the failing instruction. If EIP is greater than 0x0000FFFF then the code
  147. being executed is 32 bits linear else it is 16&colon.16 segmented.
  148. :dt.ESP or SP:dd.Those registers give the current stack pointer.
  149. :dt.EBP or BP:dd.Those registers give the address of the base pointer.
  150. The base pointer should contain the stack address or offset where
  151. the calling function address has been saved.
  152. :p.Usually the stack frame respects the following convention which
  153. allows to find from where the failing code was called once one has the
  154. stack dump.
  155. :xmp.
  156.  ┌──────────────────────────────────────────────────────────────┐
  157.  │                    Stack content                             │
  158.  ├───────────────────────────────┬──────────────────────────────┤
  159.  │     16&colon.16 bit code            │     32 bit code              │
  160.  ├───────────────────────────────┼──────────────────────────────┤
  161.  │       <──── 2 Bytes ─────>    │        <──── 4 Bytes ─────>  │
  162.  │       ┌──────────────────┐    │        ┌──────────────────┐  │
  163.  │    .  .                       │     .  .                     │
  164.  │    │  ├──────────────────┤    │     │  ├──────────────────┤  │
  165.  │    └─<  previous caller  │    │     └─<  previous caller  │  │
  166.  │    ┌ >  BP etc ...       │    │     ┌ >  EBP etc ...      │  │
  167.  │    │  ├──────────────────┤    │     │  ├──────────────────┤  │
  168.  │    │  . caller's local   .    │     │  . caller's local   .  │
  169.  │    │  . parms            .    │     │  . parms            .  │
  170.  │    │  ├──────────────────┤    │     │  .                  .  │
  171.  │    │  │ Caller return IP │    │     │  .                  .  │
  172.  │    │  ├──────────────────┤    │     │  ├──────────────────┤  │
  173.  │    │  │ Caller return CS │    │     │  │ Caller return EIP│  │
  174.  │    │  ├──────────────────┤    │     │  ├──────────────────┤  │
  175.  │    └──< Caller's BP      │    │     └──< Caller's EBP     │  │
  176.  │ BP -> ├──────────────────┤    │ EBP -> ├──────────────────┤  │
  177.  │       .  function local  .    │        .  function local  .  │
  178.  │       .  parameters      .    │        .  parameters      .  │
  179.  │                               │                              │
  180.  │ SP -> └──────────────────┘    │ ESP -> └──────────────────┘  │
  181.  │       <──── 2 Bytes ─────>    │        <──── 4 Bytes ─────>  │
  182.  └───────────────────────────────┴──────────────────────────────┘
  183. :exmp.
  184.  
  185. :dt.CSLIM:dd.For 16&colon.16 bit code this gives the size of the failing code object.
  186. :edl.
  187.  
  188. :h1 id=content3 x=left y=top width=100% height=100% scroll=both
  189.     clear.EXCEPT and EXCEPTQ Trap analysis exception handlers.
  190. :p.EXCEPT and EXCEPTQ are now identical. They are exception handlers which when
  191. a trap occurs save the registers in a file named xxxx.TRP (xxxx=Pid,Tid)
  192. together with the Loaded modules code and data objects addresses, and also
  193. the failing thread stack dump and the call stack analysis.  If the
  194. debugging information is present in the executable then the source line
  195. numbers will be too in the output .TRP file.  Trapper is an IBM C/2 program
  196. which shows how to implement the call to 32 bits exception handler from a
  197. 16&colon.16 bits program Sample in a C-Set/2 program which shows the usage from
  198. a 32 bit program. Enter Trapper (16&colon.16) or Sample (0&colon.32) to
  199. generate a sample trap and the xxxxxx.TRP file.
  200.  
  201.  
  202. :h1 id=content5 x=left y=top width=100% height=100% scroll=both
  203.     clear.TRAPTRAP Non intrusive exception catcher
  204. :p. TRAPTRAP is a sample Trap catcher code using DosDebug.
  205. Usage is
  206.  
  207.   TRAPTRAP [optional watch points] trapping_program arguments
  208.  
  209. optional watch points syntax is :
  210.   /address1 [ /address2 [/address3 [ /address4 ]]]
  211.  
  212. where address1 (2,3,4) are the linear addresses to watch up to 4
  213. addresses can be specified
  214.  
  215. sample provided use > TRAPTRAP TEST
  216. where test.exe will trap
  217.  
  218. sample watch point provided use > TRAPTRAP /20000 WATCH
  219. where watch.exe will write at linear address 20000
  220. run 1st watch alone to check address.
  221.  
  222. it generates a PROCESS.TRP file similar to EXCEPTQ's
  223. :h1 id=CSET x=left y=top width=100% height=100% scroll=both
  224.     clear.Using Exception handler with C-Set/2 and C-Set++
  225. :p. Usage with C-Set/2 and C-Set++ is very simple. Just add the following 2
  226. lines in your code containing the main().
  227. :xmp.
  228. #pragma handler(main)
  229. #pragma map(_Exception,"MYHANDLER")
  230. :exmp.
  231. :p.First line tells compiler to install an exception handler for "main". You
  232. should also add a handler for all thread functions using #pragma handler(xxxx)
  233. where xxxx is the name of the thread function parameter to _beginthread().
  234. :p.Second line tells compiler to use the handler "MYHANDLER" (contained in
  235. EXCEPTQ.DLL or EXCEPT.DLL) instead of the default C-Set handler named _Exception.
  236. :p.See the "sample.c" sample for source. The code object should be linked with
  237. EXCEPTQ.LIB (or EXCEPT.LIB).
  238. :h1 id=Symbol x=left y=top width=100% height=100% scroll=both
  239.     clear.Getting Symbolic information in Trap files
  240. :p.Use the MAPSYM tool from the toolkit against your executables (.EXE,.DLL)
  241.  .MAP files and put the resulting .SYM files in the same directory where the
  242. executable resides. The EXCEPTQ (and EXCEPT) exception handlers will
  243. automatically locate them and use them to find the closest symbols from the
  244. failing address and calling functions when walking the stack. Thus you
  245. will have the symbolic name of the functions (if available).
  246. :p.I'll make line numbering will be available when MAPSYM will be able to
  247. process LINK386 generated maps with /LI line information.
  248. :h1 id=COPYDBG x=left y=top width=100% height=100% scroll=both
  249.     clear.using COPYDBG to ship debug information separately
  250. :p.EXCEPT and EXCEPTQ use the debug inforamtion if present in the executable
  251. to locate the failing line of code and source file. However if you do not
  252. want to ship the modules with the debug (codeview) information and ship it only
  253. if problems occur, then link with /CO first, use the COPYDBG command to copy the debug
  254. information from the executables (EXE or DLL), then link without /CO to ship.
  255. COPYDBG creates files with .DBG extension, those files containing only the
  256. debugging information.
  257. :h1 id=FORCEXIT x=left y=top width=100% height=100% scroll=both
  258.     clear.Using EXCEPTQ's ForceExit
  259. :p.EXCEPTQ has a ForceExit function which allows processes to exit even
  260. if threads are in kernel wait. It intentionally generates an invisible trap,
  261. having resumed all frozen threads before.
  262. :p.Thread calling forcexit should not by in a Critical Section. See the
  263. EXITTEST.c for sample use.
  264. :euserdoc.
  265.  
  266.  
  267.