home *** CD-ROM | disk | FTP | other *** search
/ Programmer 7500 / MAX_PROGRAMMERS.iso / PASCAL / STAKDUMP.ZIP / STAKDUMP.DOC < prev    next >
Encoding:
Text File  |  1993-01-04  |  4.7 KB  |  93 lines
  1. STAKDUMP - Error handler with Stack Trace for Turbo Pascal 4.0
  2. ------------------------------------------------------------------------------
  3. Kim Kokkonen
  4. TurboPower Software
  5. 11/27/87
  6. Version 1.0
  7. Released to the public domain
  8.  
  9.  
  10. Overview
  11. ------------------------------------------------------------------------------
  12. When Turbo Pascal encounters a runtime error, it normally reports the error
  13. number and the location of the error, and then halts execution. This is a
  14. useful feature that allows you to track down errors quickly.
  15.  
  16. Knowing the location of the error is sometimes not enough. Suppose for
  17. example that you have some small routines that are called from many places
  18. within a program. If a runtime error occurs within one of those routines, you
  19. probably won't have any idea why the error really occurred, since the small
  20. routine could have been called from anywhere.
  21.  
  22. The STAKDUMP unit solves this problem by reporting not only the address of the
  23. actual error, but also the addresses of all calls made in reaching the error.
  24. The Turbo Graphix Toolbox for Turbo 3 has a similar routine but it isn't
  25. adequate for Turbo 4, which mixes near and far calls as required by the unit
  26. structure of the program.
  27.  
  28.  
  29. Using STAKDUMP
  30. ------------------------------------------------------------------------------
  31. STAKDUMP is a small unit that exports no identifiers at all. You use it by
  32. inserting it as the first unit in the USES statement of your program. STAKDUMP
  33. uses about 700 bytes of code space.
  34.  
  35. STAKDUMP automatically installs itself as a Turbo exit handler. When the
  36. program terminates, the exit handler gains control. If a runtime error has
  37. occurred, STAKDUMP writes the error number and the error address, followed by
  38. any stacked return addresses. It writes to the standard output device after
  39. first resetting it so that the results will appear on the console screen.
  40.  
  41. STAKDUMP reports addresses in the relative segment format used by the
  42. compiler. The base code segment of the program is 0 in this format. You can
  43. use any of the addresses with the TPC.EXE /F "find error" option to relate
  44. back to the source code. Alternatively you can find the addresses in a MAP
  45. file produced by the TPMAP utility.
  46.  
  47. STAKDUMP has one major limitation: it will work only when your program is run
  48. as a standalone EXE file. Within the user-interface compiler TURBO.EXE, or
  49. when run using the TPC /R option, the program's code is loaded in a different
  50. manner and at different relative addresses than when it is an EXE file.
  51. STAKDUMP senses these situations and simply passes control to the normal Turbo
  52. error handler. Similarly, you can't use TURBO.EXE's "find error" command to
  53. find errors reported when running the EXE file. You must use the TPC /F option
  54. to find the source locations.
  55.  
  56.  
  57. How STAKDUMP Works
  58. ------------------------------------------------------------------------------
  59. STAKDUMP traces the BP chain on the stack. While within any routine in Turbo
  60. Pascal, the word at SS:[BP] contains the calling routine's BP value. (While
  61. within the main block, SS:[BP] contains the initial value of the stack
  62. pointer. This value is used to terminate the trace.) The word at SS:[BP+2]
  63. contains the return offset of the current call. If the call was FAR, the word
  64. at SS:[BP+4] contains the return segment of the current call. Otherwise,
  65. SS:[BP+4] contains an undefined value, perhaps a parameter.
  66.  
  67. The tricky part of STAKDUMP lies in determining whether each call was NEAR or
  68. FAR. It does so by doing a partial disassembly of the code. For each error
  69. address, STAKDUMP scans forward in the object code until it finds a RET
  70. instruction. Based on the type of the return instruction, STAKDUMP can tell
  71. whether the current call was NEAR or FAR, and thus whether SS:[BP+4] has a new
  72. code segment or not.
  73.  
  74. STAKDUMP must assume the presence of a chain of stack frame pointers. Code
  75. generated by the Turbo compiler always maintains this chain by inserting the
  76. instruction sequence
  77.  
  78.         PUSH BP
  79.         MOV  BP,SP
  80.  
  81. at the beginning of every procedure and function. If an external assembly
  82. language routine does not set up a stack frame in this way and is active at
  83. the time a runtime error occurs, STAKDUMP will not be able to follow the stack
  84. chain and will either produce garbage or halt with an error of its own.
  85.  
  86. The disassembly technique places further restrictions that apply only to
  87. external assembly language routines. First, the disassembler cannot deal with
  88. data placed within the code stream. Second, the disassembler assumes that the
  89. return instruction for any routine is at the end of the routine.
  90.  
  91. STAKDUMP is written primarily in assembly language to save code space.
  92. STAKDUMP.ASM will assemble with MASM 4.0, MASM 5.0 or A86.
  93.