home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: SysTools / SysTools.zip / pmp43.zip / DBUG.TXT < prev    next >
Text File  |  1996-07-06  |  16KB  |  468 lines
  1. ******************************************************************************
  2. DBug Definition
  3. ******************************************************************************
  4. DBug is a flexable and easy to use real-time Debugger for the software
  5. engineer/developer that provides debugging capabilities that are impossible
  6. for the source-level debugger, easier to use, and often more convenient.
  7.  
  8. The concept of DBug is simple. You place 1 or more "DBUG" statements in your
  9. program source code at a strategic point for the purpose of displaying a
  10. message, the content of variables or memory, or time stamping a point of entry.
  11.  
  12. Compile and run your program(s). While or after running your program(s), you
  13. can view the current results via the "DBug" window or view the DBug log file
  14. to browse your DBug results.
  15.  
  16.  
  17. ******************************************************************************
  18. Using DBug
  19. ******************************************************************************
  20. When you compile your programs you include the C/C++ header file "dbug.h" and
  21. specify the compiler directive "-DDEBUG". You must link your program with the
  22. DBug Import Library "DBUGAPI.LIB" to resolve externs.
  23.  
  24. Once you're done testing and want to remove the DBUG statements for
  25. "production" use, you may:
  26.  
  27.   1.  Recompile your program(s) WITHOUT specifying the compiler directive
  28.       "-DDEBUG". The compiler will ignore the DBUG statements. Linking with
  29.       "DBUGAPI.LIB" is now unnecessary.
  30.  
  31.   2.  Manually remove each DBUG statement. Recompile and link.
  32.  
  33. It is recommended is that you leave the "dbug.h" include file in the
  34. program(s) and choose option 1 above. This allows you to, with just a
  35. recompile, have your run-time debugging enabled quickly for testing.
  36.  
  37. DBUG statements are C/C++ macros which map to a single API. There is a
  38. "generic" DBUG macro for any use, and specific macros for each unique
  39. standard C data type&colon.
  40.  
  41.   o  The DBUG macro is generic and allows you to display the contents from
  42.      any data type as well as any chunk of memory.
  43.   o  The DBUGM macro displays a simple message of your choice.
  44.   o  The DBUGS macro displays the contents of a SHORT data type.
  45.   o  The DBUGL macro displays the contents of a LONG data type.
  46.   o  The DBUGI macro displays the contents of a INTEGER data type.
  47.   o  The DBUGD macro displays the contents of a DOUBLE data type.
  48.   o  The DBUGC macro displays the contents of a CHAR data type.
  49.   o  The DBUGZ macro displays the contents of a String data type.
  50.   o  The DBUGP macro displays the contents of a POINTER data type.
  51.   o  The DBUGOPEN macro opens a new DBug log file
  52.   o  The DBUGCLOSE macro closes a the DBug log file
  53.   o  The DBUGSTOP macro terminates the DBug facility
  54.  
  55. Each DBUG statement will cause an IPC message to be build and sent to the
  56. central DBug program. The DBug program will then display the message in his
  57. standard format and log it for later recall - if logging is turned on.
  58.  
  59. If the DBug proram is not presently running to receive these requests, your
  60. DBUG statements will be ignored at run-time. The effort required to complete
  61. a single DBUG within your program(s) is very minimal and insignificant.
  62.  
  63. The DBug program can be started and stopped at any time - even when programs
  64. are actively DBUGing. If restarted, DBug will continue pulling DBUGs from his
  65. queue and displaying/logging them.
  66.  
  67. DBug will handle bursts of DBUGs easily as he offers a 256K maximum buffer.
  68. DBug will only allocate/commit enough memory to hold each DBUG request - not
  69. the whole 256K. The 256K buffer is therefore used optimally and requires
  70. little real memory from OS/2.
  71.  
  72. When monitoring DBug, minimize the window if large amounts of DBUGs are be
  73. displayed. This will significantly improve how fast DBug displays and reduce
  74. the overhead of displaying results.
  75.  
  76. DBug has two log files and are created in the drive/directory where DBug was
  77. started. If started and control from PM Patrol, these log files will reside
  78. in the directory from where PM Patrol was installed and started.
  79.  
  80.   o  The primary and active log "DBUG.LOG" contains current data.
  81.  
  82.   o  The backup log "DBUG.BAK" contains the previous primary data after a new
  83.       log file is opened.
  84.  
  85. When logging is opened, a DBUG message is placed at the beginning of the Dbug
  86. log file.
  87.  
  88. Note: DBug log files are automatically recycled at midnight so that under
  89. continuous operation, each log will contain a full 24 hours of information.
  90. Therefore, up to 2 days (primary and backup) of DBug information can be
  91. reviewed any time.
  92.  
  93. If Dbug has nothing to do, absolutely no CPU is used. The small amount of
  94. DBug memory requirements are "swappable" to make room for more active
  95. demanding programs. 
  96.  
  97. DBug is a high performance debugging tool for even the most intense
  98. environments. When the Dbug window is minimized or DBug is running in "Quiet"
  99. mode, DBug can handle several hundred DBUGs per second. Even more for highend
  100. Pentium or PowerPC processors.
  101.  
  102.  
  103. ******************************************************************************
  104. DBug Programming Files
  105. ******************************************************************************
  106. The DBug software contains 3 files for DBug programming purposes&colon.
  107.  
  108.   o  DBUG.H is a C/C++ header containing the macros for DBug. "Include"
  109.      this header file in your C/C++ programs.
  110.  
  111.   o  DBUGAPI.LIB is the Import Library to link with to resolve DBUG APIs. You
  112.      must link (LINK386) with this Import Library to resolve external
  113.      references and is specified in the LINK386 options.
  114.  
  115.   o  DBUGAPI.DLL is the Dynamic Link Library which holds the actual code of APIs
  116.  
  117. For compiling and linking, append the installation path used for PM Patrol to
  118. the following statements in your CONFIG.SYS:
  119.  
  120.   o  "LIB" statement for the API import library (DBUGAPI.LIB).
  121.  
  122.   o  "INCLUDE" statement for the API C/C++ header (DBUG.H).
  123.  
  124. Make sure the DBug DLL is available at run time by appending the installtion
  125. path used for PM Patrol to the following statements in your CONFIG.SYS
  126. file:
  127.  
  128.   o  "LIBPATH" statement for the API DLL (DBUGAPI.DLL).
  129.  
  130.  
  131. ******************************************************************************
  132. DBug Macro Set
  133. ******************************************************************************
  134.  
  135. DBUG() Macro
  136. ------------------------------------------------------------------------------
  137. The DBUG macro is generic and allows you to display the contents from any
  138. data type as well as any chunk of memory.
  139.  
  140. Prototype: ULONG  DBUG (PVOID address, USHORT size, PCHAR note)
  141.  
  142. Parms:     address            ... Address to displayed/dumped
  143.            size               ... Size of data type or memory to be display
  144.            note               ... A personal description of your choice
  145.  
  146. Returns:   NO_ERROR           ... Successful with no errors, or error code
  147.  
  148. Example:
  149. --------------
  150. #include <stdio.h>
  151. #include <stdlib.h>
  152. #include <dbug.h>
  153.   ...
  154.  
  155.   CHAR   array[60];
  156.  
  157.   DBUG(array, sizeof(array), "my array");
  158.  
  159.  
  160. DBUGM() Macro
  161. ------------------------------------------------------------------------------
  162. The DBUGM macro displays a simple message of your choice.
  163.  
  164. Prototype: ULONG  DBUGM(PCHAR message)
  165.  
  166. Parms:     message            ... A personal description of your choice
  167.  
  168. Returns:   NO_ERROR           ... Successful with no errors, or error code
  169.  
  170. Example:
  171. ----------
  172. #include <stdio.h>
  173. #include <stdlib.h>
  174. #include <dbug.h>
  175.   ...
  176.  
  177.   DBUGM("Point 1 of program");
  178.  
  179.  
  180. DBUGS() Macro
  181. ------------------------------------------------------------------------------
  182. The DBUGS macro displays the contents of a SHORT data type.
  183.  
  184. Prototype: ULONG  DBUGS(PSHORT address, PCHAR note)
  185.  
  186. Parms:     address            ... Address of short to be displayed
  187.            note               ... A personal description of your choice
  188.  
  189. Returns:   NO_ERROR           ... Successful with no errors, or error code
  190.  
  191. Example:
  192. ----------
  193. #include <stdio.h>
  194. #include <stdlib.h>
  195. #include <dbug.h>
  196.  ...
  197.  
  198.   USHORT  variable;
  199.  
  200.   DBUGS(&.variable, "my variable");
  201.  
  202.  
  203. DBUGS() Macro
  204. ------------------------------------------------------------------------------
  205. The DBUGL macro displays the contents of a LONG data type.
  206.  
  207. Prototype: ULONG  DBUGL(PLONG address, PCHAR note)
  208.  
  209. Parms:     address            ... Address of long to be displayed
  210.            note               ... A personal description of your choice
  211.  
  212. Returns:   NO_ERROR           ... Successful with no errors, or error code
  213.  
  214. Example:
  215. ----------
  216. #include <stdio.h>
  217. #include <stdlib.h>
  218. #include <dbug.h>
  219.   ...
  220.  
  221.   LONG   variable;
  222.  
  223.   DBUGL(&.variable, "my variable");
  224.  
  225.  
  226. DBUGI() Macro
  227. ------------------------------------------------------------------------------
  228. The DBUGI macro displays the contents of a INTEGER data type.
  229.  
  230. Prototype: ULONG  DBUGI(PINT address, PCHAR note)
  231.  
  232. Parms:     address            ... Address of integer to be displayed
  233.            note               ... A personal description of your choice
  234.  
  235. Returns:   NO_ERROR           ... Successful with no errors, or error code
  236.  
  237. Example:
  238. ----------
  239. #include <stdio.h>
  240. #include <stdlib.h>
  241. #include <dbug.h>
  242.   ...
  243.  
  244.   INT    variable;
  245.  
  246.   DBUGI(&.variable, "my variable");
  247.  
  248.  
  249. DBUGD() Macro
  250. ------------------------------------------------------------------------------
  251. The DBUGD macro displays the contents of a DOUBLE data type.
  252.  
  253. Prototype: ULONG  DBUGD(PDOUBLE address, PCHAR note)
  254.  
  255. Parms:     address            ... Address of double to be displayed
  256.            note               ... A personal description of your choice
  257.  
  258. Returns:   NO_ERROR           ... Successful with no errors, or error code
  259.  
  260. Example:
  261. ----------
  262. #include <stdio.h>
  263. #include <stdlib.h>
  264. #include <dbug.h>
  265.   ...
  266.  
  267.   DOUBLE  variable;
  268.  
  269.   DBUGD(&.variable, "my variable");
  270.  
  271.  
  272. DBUGC() Macro
  273. ------------------------------------------------------------------------------
  274. The DBUGC macro displays the contents of a CHAR data type.
  275.  
  276. Prototype: ULONG  DBUGC(PINT address, PCHAR note)
  277.  
  278. Parms:     address            ... Address of char to be displayed
  279.            note               ... A personal description of your choice
  280.  
  281. Returns:   NO_ERROR           ... Successful with no errors, or error code
  282.  
  283. Example:
  284. ----------
  285. #include <stdio.h>
  286. #include <stdlib.h>
  287. #include <dbug.h>
  288.   ...
  289.  
  290.   CHAR     variable;
  291.  
  292.   DBUGC(&.variable, "my variable");
  293.  
  294.  
  295. DBUGP() Macro
  296. ------------------------------------------------------------------------------
  297. The DBUGP macro displays the contents of a POINTER data type.
  298.  
  299. Prototype: ULONG  DBUGP(PVOID address, PCHAR note)
  300.  
  301. Parms:     address            ... Address of pointer to be displayed
  302.            note               ... A personal description of your choice
  303.  
  304. Returns:   NO_ERROR           ... Successful with no errors, or error code
  305.  
  306. Example:
  307. ----------
  308. #include <stdio.h>
  309. #include <stdlib.h>
  310. #include <dbug.h>
  311.   ...
  312.  
  313.   PVOID  variable;
  314.  
  315.   /* display pointer value */
  316.   DBUGP(&.variable, "my variable");
  317.  
  318.   /* display memory contents */
  319.   DBUG(variable, 2048, "my variable memory");
  320.  
  321.  
  322. DBUGZ() Macro
  323. ------------------------------------------------------------------------------
  324. The DBUGZ macro displays the contents of a String data type.
  325.  
  326. Prototype: ULONG  DBUGZ(PVOID address, PCHAR note)
  327.  
  328. Parms:     address            ... Address of string to be displayed
  329.            note               ... A personal description of your choice
  330.  
  331. Returns:   NO_ERROR           ... Successful with no errors, or error code
  332.  
  333. Example:
  334. ----------
  335. #include <stdio.h>
  336. #include <stdlib.h>
  337. #include <dbug.h>
  338.   ...
  339.  
  340.   CHAR   variable[32]="Hello world";
  341.  
  342.   DBUGZ(variable, "my variable");
  343.  
  344.  
  345. DBUGOPEN() Macro
  346. ------------------------------------------------------------------------------
  347. The DBUGOPEN macro opens a new DBug log file.
  348.  
  349. Prototype: ULONG  DBUGOPEN(VOID)
  350.  
  351. Parms:     None
  352.  
  353. Returns:   NO_ERROR           ... Successful with no errors, or error code
  354.  
  355. Example:
  356. ----------
  357. #include <stdio.h>
  358. #include <stdlib.h>
  359. #include <dbug.h>
  360.   ...
  361.  
  362.   DBUGOPEN();
  363.  
  364.  
  365. :h3.DBUGCLOSE()
  366. ------------------------------------------------------------------------------
  367. The DBUGCLOSE. macro closes the DBug log file.
  368.  
  369. Prototype: ULONG  DBUGCLOSE(VOID)
  370.  
  371. Parms:     None
  372.  
  373. Returns:   NO_ERROR           ... Successful with no errors, or error code
  374.  
  375. Example:
  376. ----------
  377. #include <stdio.h>
  378. #include <stdlib.h>
  379. #include <dbug.h>
  380.   ...
  381.  
  382.   DBUGCLOSE();
  383.  
  384.  
  385. DBUGSTOP() Macro
  386. ------------------------------------------------------------------------------
  387. The DBUGSTOP macro terminates the DBug Facility.
  388.  
  389. Prototype: ULONG  DBUGSTOP(VOID)
  390.  
  391. Parms:     None
  392.  
  393. Returns:   NO_ERROR           ... Successful with no errors, or error code
  394.  
  395. Example:
  396. ----------
  397. #include <stdio.h>
  398. #include <stdlib.h>
  399. #include <dbug.h>
  400.   ...
  401.  
  402.   DBUGSTOP();
  403.  
  404.  
  405. ******************************************************************************
  406. DBug Sample Output
  407. ******************************************************************************
  408.  
  409. The following is a sample output from the DBug Facility.
  410. ------------------------------------------------------------------------
  411. From: PID 00a3  At 21:06:42  DBUG.CPP (line 474)
  412. Note: DBug log opened.
  413. Type: INFO, 0 bytes   (0 qCnt)
  414. ------------------------------------------------------------------------
  415. From: PID 00a8  At 21:07:10  TEST.C (line 22)
  416. Note: sample DBUGs
  417. Type: INFO, 0 bytes   (3 qCnt)
  418. ------------------------------------------------------------------------
  419. From: PID 00a8  At 21:07:10  TEST.C (line 23)
  420. Note: my return code (little endian)
  421. Type: LONG, 4 bytes   (2 qCnt)
  422. 0000: 00 00 00 00                                     |....            |
  423. ------------------------------------------------------------------------
  424. From: PID 00a8  At 21:07:10  TEST.C (line 24)
  425. Note: a chunk of memory
  426. Type: VOID, 120 bytes   (1 qCnt)
  427. 0000: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................|
  428. 0010: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................|
  429. 0020: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................|
  430. 0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................|
  431. 0040: 00 00 00 00 00 00 00 00 00 00 43 44 45 46 00 00 |..........CDEF..|
  432. 0050: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................|
  433. 0060: 00 00 00 00 00 43 00 00 00 00 00 00 00 00 60 c6 |.....C........`.|
  434. 0070: a2 41 00 00 00 00 10 59                         |.A.....Y        |
  435. ------------------------------------------------------------------------
  436. From: PID 00a8  At 21:07:10  TEST.C (line 25)
  437. Note: my double value
  438. Type: DOUBLE, 8 bytes   (0 qCnt)
  439. 0000: 33 33 33 33 b3 00 ab 40                         |3333...@        |
  440. ------------------------------------------------------------------------
  441.  
  442.  
  443. Using the last DBUG for example, the DBug output contains four (4) main
  444. sections:
  445.  
  446.   o  The "From" section identifies who (what program) the DBUG was sent from:
  447.  
  448.      o  The Process ID (as hex)
  449.      o  The time the DBug was issued (not received and displayed/logged).
  450.      o  The program source code name and line number of the DBUG statement
  451.         within the program source.
  452.  
  453.   o  The "Note" section is where your personal note/description from the DBUG
  454.      statement is displayed.
  455.  
  456.   o  The "Type" section identifies the data type displayed, the number of
  457.      bytes for the data, and how many DBUG statements remain in the DBug queue
  458.      to be displayed (qCnt)&colon.
  459.  
  460.      o  These include all standard data types such as DOUBLE, CHAR, PCHAR,
  461.         INT, and so on.
  462.      o  VOID is displayed when a "memory chunk" is displayed.
  463.      o  INFO is displayed when just a DBUGM (Message) statement is issued.
  464.  
  465.   o  The last section displays the contents (in hex and ASCII representation)
  466.      of the data type. The left most column of this section is the offset
  467.      starting at zero.
  468.