Back to files

Notes about the debug macros and routine:

1. Source file with main() must #define MAIN_C, no other source files should do so.
2. The ADM prefix is a leftover from the original program I used this in.
3. All routines that will use debug macros need to define a character string fname[]. This can be done conditionally, as so

        #ifdef DEBUG
        char    fname[]="Name of Routine";
        #endif

        Do this at the start of each routine.  The scope of fname is local to
        the routine.

4. There are 6 macros:

        DBGOpen(fd) - opens the debug output file
        DBGClose(fd) - closes the debug output file
        DBGEnter() - prints a message that a routine has been entered
        DBGExit() - prints a message that a routine is being exited
        DBGPrint(level, A) - prints A, which should be a character string
        DBGPrintf(level, A) - prints A, which is a varargs format string just
                like printf() would use.

        Both DBGPrint() and DBGPrintf() use "level", which can be used to set
        different levels of debug output.  This isn't implemented all that well.
        The debug level should be set via command line args, but doing so is not
        part of the debug macros.  It does work well when you only want to debug

certain parts (as opposed to different levels). If anyone wants to add levels to debug.h, please let me know so I can track them.

Example use of DBGPrint() and DBGPrintf():

        DBGPrint(DBG_INFO, "testing debug\n");
        DBGPrintf(DBG_INFO, ("testing debug: my name=%s\n", (char *)name));

        Note that the latter's second argument must be enclosed in
        parenthesis!  Also, the strings must use the same syntax as printf()
        for DBGPrintf().  DBGPrint() just prints the strings, so you can't use
        it to print variable arguments.  You'll find you use DBGPrintf() much
        more than DBGPrint().

        DBGEnter() and DBGExit() require not arguments.

5. There are 4 globally set variables:

        int     GMDebugLevel - this can be DBG_PROC, DBG_INFO, DBG_SPECIAL, etc.
                        see debug.h
        char    *DBGFile - the name of the debug output file
        char    *DBGbuf - points to the character string created from varargs list
        int     DEBUG_FD - file descriptor for open debug output file

        You must call DBGOpen() with DEBUG_FD, as 
                DBGOpen(DEBUG_FD);
        The same is true of DBGClose().
        
        The default value for DBGFile is "/dev/null".

---

How To Use libgmdebug.a:

1. Add the following line to the module where your main() is located:

   #define MAIN_C

2. Add the following to your main():

char *fname="main()";

        GMDebugLevel = DBG_ALL;
        DBGFile = "/tmp/debug.out";
        DBGOpen(DEBUG_FD);
        DBGEnter();

        This will tell the library that all possible debug output should be 
        displayed and to send that output to /tmp/debug.out.  You can use
        the convenience routine, DBGStringToInt(), to convert a hex string
        to an integer value if you'd like.  That way, you can just specify
        a hex value on the command line, pass it to DBGStringToInt(), and 
        set the returned value to GMDebugLevel.

3. Include the following to you source where you want to use the debug library.

#include "debug.h"

4. Add the fname variable to any routine that will be using the debug

library.

5. Add the DBGEnter(), DBGExit(), DBGPrint() and DBGPrintf() to your routines.

6. Debug till your heart is content.

These macros are actually a hybrid from the macros used on a project at IBM and ones used on an Interactive TV project for GTE. This little library has grown tremendously since I first created it. Its now ready for use in any project you'd like to drop it into!