home *** CD-ROM | disk | FTP | other *** search
/ Usenet 1994 January / usenetsourcesnewsgroupsinfomagicjanuary1994.iso / sources / misc / volume30 / oraperl-v2 / part04 / Debugging < prev    next >
Encoding:
Text File  |  1992-07-06  |  3.1 KB  |  65 lines
  1.  
  2. Starting with version 2, Oraperl incorporates Fred Fish' excellent
  3. debugging package, DBUG. The entire package (including documentation)
  4. is included in the dbug/ subdirectory, so you can install it separately
  5. to use with other programs. DBUG is in the public domain.
  6.  
  7. Read dbug/dbug.p for full details on the package, but briefly you need
  8. to assign debugging control strings to $ora_debug to indicate the level
  9. of debugging required. A list of the debugging controls is on pages 18
  10. and 19 of the documentation. For example, if you want to trace allocation
  11. and freeing of memory in the functions ora_open and ora_close, writing
  12. the output to a file called trace, numbering the lines, you could say:
  13.  
  14.          $ora_debug = 'd,malloc,free:f,ora_open,ora_close:o,trace:N';
  15.                        ^             ^                    ^       ^
  16.                        |             |                    |       |
  17.     debugging keys ----+             |                    |       |
  18.     functions to be traced ----------+                    |       |
  19.     where to write output --------------------------------+       |
  20.     number output lines ------------------------------------------+
  21.  
  22. The debugging keywords (for the 'd' parameter) used are the following:
  23.  
  24.      conv    report string/double conversions (only for addresses)
  25.      entry   report function entry, with parameters
  26.      exit    report function exit, with return values
  27.      free    report memory freeing
  28.      info    report other information of interest
  29.      malloc  report memory allocation, success or failure
  30.  
  31. Debugging is turned off by assigning an empty string to $ora_debug.
  32.  
  33. It is still possible to assign a numeric value to $ora_debug, for
  34. compatibility with existing programs and to allow continued use of
  35. Perl's -D flag. Values are translated according to the following table:
  36.  
  37.       value    keywords
  38.       -----    --------
  39.          8     entry exit info
  40.         32     conv
  41.        128     malloc free
  42.  
  43. These values may combined, so that $ora_debug = 168 turns on all debugging.
  44. If the resulting value contains no valid flags, debugging is turned off;
  45. thus "$ora_debug = 0" still works. When a numerical value is used, the
  46. controls ':t:N' are appended to show the function nesting and number the
  47. output lines.
  48.  
  49. If your uperl.o was built with -DDEBUGGING, you can define PERL_DEBUGGING
  50. at compilation and the oraperl debugging will be initialiased from the -D
  51. flag. If not, you can still define DEBUGGING, but you will have to set
  52. ora_debug from within your program.
  53.  
  54. One idea would be to include a flag in all your programs which would allow
  55. a debugging string to be entered on the command line. The author of the
  56. DBUG package recommends -# (and so the routines will remove a leading -#
  57. from the control string if there is one). For example, I use this line:
  58.  
  59.     $ora_debug = shift if $ARGV[0] =~ /-#/;
  60.  
  61. If you want to trace something else, you can add your own DBUG_PRINT
  62. statements to the code wherever you want. I would recommend that you use
  63. a keyword that isn't specified here (possibly beginning with your initials)
  64. so that you can easily distinguish between my debugging and yours.
  65.