******************************************************************************
DBug Definition
******************************************************************************
DBug is a flexable and easy to use real-time Debugger for the software
engineer/developer that provides debugging capabilities that are impossible
for the source-level debugger, easier to use, and often more convenient.

The concept of DBug is simple. You place 1 or more "DBUG" statements in your
program source code at a strategic point for the purpose of displaying a
message, the content of variables or memory, or time stamping a point of entry.

Compile and run your program(s). While or after running your program(s), you
can view the current results via the "DBug" window or view the DBug log file
to browse your DBug results.


******************************************************************************
Using DBug
******************************************************************************
When you compile your programs you include the C/C++ header file "dbug.h" and
specify the compiler directive "-DDEBUG". You must link your program with the
DBug Import Library "DBUGAPI.LIB" to resolve externs.

Once you're done testing and want to remove the DBUG statements for
"production" use, you may:

  1.  Recompile your program(s) WITHOUT specifying the compiler directive
      "-DDEBUG". The compiler will ignore the DBUG statements. Linking with
      "DBUGAPI.LIB" is now unnecessary.

  2.  Manually remove each DBUG statement. Recompile and link.

It is recommended is that you leave the "dbug.h" include file in the
program(s) and choose option 1 above. This allows you to, with just a
recompile, have your run-time debugging enabled quickly for testing.

DBUG statements are C/C++ macros which map to a single API. There is a
"generic" DBUG macro for any use, and specific macros for each unique
standard C data type&colon.

  o  The DBUG macro is generic and allows you to display the contents from
     any data type as well as any chunk of memory.
  o  The DBUGM macro displays a simple message of your choice.
  o  The DBUGS macro displays the contents of a SHORT data type.
  o  The DBUGL macro displays the contents of a LONG data type.
  o  The DBUGI macro displays the contents of a INTEGER data type.
  o  The DBUGD macro displays the contents of a DOUBLE data type.
  o  The DBUGC macro displays the contents of a CHAR data type.
  o  The DBUGZ macro displays the contents of a String data type.
  o  The DBUGP macro displays the contents of a POINTER data type.
  o  The DBUGOPEN macro opens a new DBug log file
  o  The DBUGCLOSE macro closes a the DBug log file
  o  The DBUGSTOP macro terminates the DBug facility

Each DBUG statement will cause an IPC message to be build and sent to the
central DBug program. The DBug program will then display the message in his
standard format and log it for later recall - if logging is turned on.

If the DBug proram is not presently running to receive these requests, your
DBUG statements will be ignored at run-time. The effort required to complete
a single DBUG within your program(s) is very minimal and insignificant.

The DBug program can be started and stopped at any time - even when programs
are actively DBUGing. If restarted, DBug will continue pulling DBUGs from his
queue and displaying/logging them.

DBug will handle bursts of DBUGs easily as he offers a 256K maximum buffer.
DBug will only allocate/commit enough memory to hold each DBUG request - not
the whole 256K. The 256K buffer is therefore used optimally and requires
little real memory from OS/2.

When monitoring DBug, minimize the window if large amounts of DBUGs are be
displayed. This will significantly improve how fast DBug displays and reduce
the overhead of displaying results.

DBug has two log files and are created in the drive/directory where DBug was
started. If started and control from PM Patrol, these log files will reside
in the directory from where PM Patrol was installed and started.

  o  The primary and active log "DBUG.LOG" contains current data.

  o  The backup log "DBUG.BAK" contains the previous primary data after a new
      log file is opened.

When logging is opened, a DBUG message is placed at the beginning of the Dbug
log file.

Note: DBug log files are automatically recycled at midnight so that under
continuous operation, each log will contain a full 24 hours of information.
Therefore, up to 2 days (primary and backup) of DBug information can be
reviewed any time.

If Dbug has nothing to do, absolutely no CPU is used. The small amount of
DBug memory requirements are "swappable" to make room for more active
demanding programs. 

DBug is a high performance debugging tool for even the most intense
environments. When the Dbug window is minimized or DBug is running in "Quiet"
mode, DBug can handle several hundred DBUGs per second. Even more for highend
Pentium or PowerPC processors.


******************************************************************************
DBug Programming Files
******************************************************************************
The DBug software contains 3 files for DBug programming purposes&colon.

  o  DBUG.H is a C/C++ header containing the macros for DBug. "Include"
     this header file in your C/C++ programs.

  o  DBUGAPI.LIB is the Import Library to link with to resolve DBUG APIs. You
     must link (LINK386) with this Import Library to resolve external
     references and is specified in the LINK386 options.

  o  DBUGAPI.DLL is the Dynamic Link Library which holds the actual code of APIs

For compiling and linking, append the installation path used for PM Patrol to
the following statements in your CONFIG.SYS:

  o  "LIB" statement for the API import library (DBUGAPI.LIB).

  o  "INCLUDE" statement for the API C/C++ header (DBUG.H).

Make sure the DBug DLL is available at run time by appending the installtion
path used for PM Patrol to the following statements in your CONFIG.SYS
file:

  o  "LIBPATH" statement for the API DLL (DBUGAPI.DLL).


******************************************************************************
DBug Macro Set
******************************************************************************

DBUG() Macro
------------------------------------------------------------------------------
The DBUG macro is generic and allows you to display the contents from any
data type as well as any chunk of memory.

Prototype: ULONG  DBUG (PVOID address, USHORT size, PCHAR note)

Parms:     address            ... Address to displayed/dumped
           size               ... Size of data type or memory to be display
           note               ... A personal description of your choice

Returns:   NO_ERROR           ... Successful with no errors, or error code

Example:
--------------
#include <stdio.h>
#include <stdlib.h>
#include <dbug.h>
  ...

  CHAR   array[60];

  DBUG(array, sizeof(array), "my array");


DBUGM() Macro
------------------------------------------------------------------------------
The DBUGM macro displays a simple message of your choice.

Prototype: ULONG  DBUGM(PCHAR message)

Parms:     message            ... A personal description of your choice

Returns:   NO_ERROR           ... Successful with no errors, or error code

Example:
----------
#include <stdio.h>
#include <stdlib.h>
#include <dbug.h>
  ...

  DBUGM("Point 1 of program");


DBUGS() Macro
------------------------------------------------------------------------------
The DBUGS macro displays the contents of a SHORT data type.

Prototype: ULONG  DBUGS(PSHORT address, PCHAR note)

Parms:     address            ... Address of short to be displayed
           note               ... A personal description of your choice

Returns:   NO_ERROR           ... Successful with no errors, or error code

Example:
----------
#include <stdio.h>
#include <stdlib.h>
#include <dbug.h>
 ...

  USHORT  variable;

  DBUGS(&amp.variable, "my variable");


DBUGS() Macro
------------------------------------------------------------------------------
The DBUGL macro displays the contents of a LONG data type.

Prototype: ULONG  DBUGL(PLONG address, PCHAR note)

Parms:     address            ... Address of long to be displayed
           note               ... A personal description of your choice

Returns:   NO_ERROR           ... Successful with no errors, or error code

Example:
----------
#include <stdio.h>
#include <stdlib.h>
#include <dbug.h>
  ...

  LONG   variable;

  DBUGL(&amp.variable, "my variable");


DBUGI() Macro
------------------------------------------------------------------------------
The DBUGI macro displays the contents of a INTEGER data type.

Prototype: ULONG  DBUGI(PINT address, PCHAR note)

Parms:     address            ... Address of integer to be displayed
           note               ... A personal description of your choice

Returns:   NO_ERROR           ... Successful with no errors, or error code

Example:
----------
#include <stdio.h>
#include <stdlib.h>
#include <dbug.h>
  ...

  INT    variable;

  DBUGI(&amp.variable, "my variable");


DBUGD() Macro
------------------------------------------------------------------------------
The DBUGD macro displays the contents of a DOUBLE data type.

Prototype: ULONG  DBUGD(PDOUBLE address, PCHAR note)

Parms:     address            ... Address of double to be displayed
           note               ... A personal description of your choice

Returns:   NO_ERROR           ... Successful with no errors, or error code

Example:
----------
#include <stdio.h>
#include <stdlib.h>
#include <dbug.h>
  ...

  DOUBLE  variable;

  DBUGD(&amp.variable, "my variable");


DBUGC() Macro
------------------------------------------------------------------------------
The DBUGC macro displays the contents of a CHAR data type.

Prototype: ULONG  DBUGC(PINT address, PCHAR note)

Parms:     address            ... Address of char to be displayed
           note               ... A personal description of your choice

Returns:   NO_ERROR           ... Successful with no errors, or error code

Example:
----------
#include <stdio.h>
#include <stdlib.h>
#include <dbug.h>
  ...

  CHAR     variable;

  DBUGC(&amp.variable, "my variable");


DBUGP() Macro
------------------------------------------------------------------------------
The DBUGP macro displays the contents of a POINTER data type.

Prototype: ULONG  DBUGP(PVOID address, PCHAR note)

Parms:     address            ... Address of pointer to be displayed
           note               ... A personal description of your choice

Returns:   NO_ERROR           ... Successful with no errors, or error code

Example:
----------
#include <stdio.h>
#include <stdlib.h>
#include <dbug.h>
  ...

  PVOID  variable;

  /* display pointer value */
  DBUGP(&amp.variable, "my variable");

  /* display memory contents */
  DBUG(variable, 2048, "my variable memory");


DBUGZ() Macro
------------------------------------------------------------------------------
The DBUGZ macro displays the contents of a String data type.

Prototype: ULONG  DBUGZ(PVOID address, PCHAR note)

Parms:     address            ... Address of string to be displayed
           note               ... A personal description of your choice

Returns:   NO_ERROR           ... Successful with no errors, or error code

Example:
----------
#include <stdio.h>
#include <stdlib.h>
#include <dbug.h>
  ...

  CHAR   variable[32]="Hello world";

  DBUGZ(variable, "my variable");


DBUGOPEN() Macro
------------------------------------------------------------------------------
The DBUGOPEN macro opens a new DBug log file.

Prototype: ULONG  DBUGOPEN(VOID)

Parms:     None

Returns:   NO_ERROR           ... Successful with no errors, or error code

Example:
----------
#include <stdio.h>
#include <stdlib.h>
#include <dbug.h>
  ...

  DBUGOPEN();


:h3.DBUGCLOSE()
------------------------------------------------------------------------------
The DBUGCLOSE. macro closes the DBug log file.

Prototype: ULONG  DBUGCLOSE(VOID)

Parms:     None

Returns:   NO_ERROR           ... Successful with no errors, or error code

Example:
----------
#include <stdio.h>
#include <stdlib.h>
#include <dbug.h>
  ...

  DBUGCLOSE();


DBUGSTOP() Macro
------------------------------------------------------------------------------
The DBUGSTOP macro terminates the DBug Facility.

Prototype: ULONG  DBUGSTOP(VOID)

Parms:     None

Returns:   NO_ERROR           ... Successful with no errors, or error code

Example:
----------
#include <stdio.h>
#include <stdlib.h>
#include <dbug.h>
  ...

  DBUGSTOP();


******************************************************************************
DBug Sample Output
******************************************************************************

The following is a sample output from the DBug Facility.
------------------------------------------------------------------------
From: PID 00a3  At 21:06:42  DBUG.CPP (line 474)
Note: DBug log opened.
Type: INFO, 0 bytes   (0 qCnt)
------------------------------------------------------------------------
From: PID 00a8  At 21:07:10  TEST.C (line 22)
Note: sample DBUGs
Type: INFO, 0 bytes   (3 qCnt)
------------------------------------------------------------------------
From: PID 00a8  At 21:07:10  TEST.C (line 23)
Note: my return code (little endian)
Type: LONG, 4 bytes   (2 qCnt)
0000: 00 00 00 00                                     |....            |
------------------------------------------------------------------------
From: PID 00a8  At 21:07:10  TEST.C (line 24)
Note: a chunk of memory
Type: VOID, 120 bytes   (1 qCnt)
0000: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................|
0010: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................|
0020: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................|
0030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................|
0040: 00 00 00 00 00 00 00 00 00 00 43 44 45 46 00 00 |..........CDEF..|
0050: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................|
0060: 00 00 00 00 00 43 00 00 00 00 00 00 00 00 60 c6 |.....C........`.|
0070: a2 41 00 00 00 00 10 59                         |.A.....Y        |
------------------------------------------------------------------------
From: PID 00a8  At 21:07:10  TEST.C (line 25)
Note: my double value
Type: DOUBLE, 8 bytes   (0 qCnt)
0000: 33 33 33 33 b3 00 ab 40                         |3333...@        |
------------------------------------------------------------------------


Using the last DBUG for example, the DBug output contains four (4) main
sections:

  o  The "From" section identifies who (what program) the DBUG was sent from:

     o  The Process ID (as hex)
     o  The time the DBug was issued (not received and displayed/logged).
     o  The program source code name and line number of the DBUG statement
        within the program source.

  o  The "Note" section is where your personal note/description from the DBUG
     statement is displayed.

  o  The "Type" section identifies the data type displayed, the number of
     bytes for the data, and how many DBUG statements remain in the DBug queue
     to be displayed (qCnt)&colon.

     o  These include all standard data types such as DOUBLE, CHAR, PCHAR,
        INT, and so on.
     o  VOID is displayed when a "memory chunk" is displayed.
     o  INFO is displayed when just a DBUGM (Message) statement is issued.

  o  The last section displays the contents (in hex and ASCII representation)
     of the data type. The left most column of this section is the offset
     starting at zero.