These files Created 7/86 by Darren New. Released to the PUBLIC DOMAIN. No rights reserved. Do anything you want with it. Simple request: if you make a significant profit from this, or if you have improvements or suggestions, please contact me at CIS User ID: 73647,3301 (sqEZe me! -- I don't check messages that much) Home phone: 356-5728 (voice, please) (the request about profit just for my curiosity) DISCLAIMER: As I am not making money from this, I am not going to be oblicated to support it, either. Thus, THIS IS SUPPLIED "AS IS". No warranty of any kind is made or implied. Lattice is a registered trademark of Lattice, Inc. Thus endeth the A__-covering. -------------------------------------------------------------------------- This set of functions is for debugging programs. The function DEBUG_OPEN() opens a new console at the bottom of the screen. This console is read and written by DEBUGF(). DEBUG_CLOSE() will close this console, freeing it's memory. Eventually, I hope to write these things as resources or devices, or something where everyone doing debug output will write to the same console so that multi-tasking functions can be debuged more easily. (Probably shortly after I start coding multi-process programs myself...) The main advantages of these functions over most of the debugging macros already out there are these: They write to a separate window, so even things with no windows or that do ANSI stuff and so on can be debugged. Another advantage is that they are interactive -- pure macros must be recompiled and relinked to be disposed; these functions can be turned on and off at run time. Of course, a simple compiler switch can remove all trace of these from the object files, just like most of the debugging packages. The debugging info can be sent to a file or to the printer for really sticky problems. Also, user's functions can be called from the keyboard from within the debug functions. Although this does take a little setup, it can be worthwhile for stepping through a program until you start getting strange errors, and then popping back to your program someplace else in order to examine variables, dump files, or whatever; I imagine it could also be used to clean up and exit from the debugger. Finally, it uses AmigaDOS calls only; no Lattice library calls or STDIO calls or anything like that. If you have a "tiny" program, this may be helpful. Note also that under Lattice, the -d switch (pass 1) will #define DEBUG for you. Note that in order for the macros to remove the function calls with variable arguments (under Lattice, at least), any arguments after the formatting string must be separated from the preceeding argument not by a comma, but by the pre-processor symbol "COMMA". This turns all of the variable args into one argument if "COMMA" is not defined. Credit for this technique is hereby given to "Dr. Bob", the author of "DEBUGC", found elsewhere. DEBUG_OPEN(S) ---> void Opens the console. All other debug functions will be ignored while the console is closed. If S is NULL, the default console string is used as the file name for the Open call. If S is not NULL, that string will be used as the filename. If the console can not be opened, DisplayBeep() in a pattern indicative of the error. Calling this is not an error the debugging console is already open. This automatically gets called whenever DEBUG_ENTER() gets called and the nesting stack is empty; usually, this means main() is calling it for the first time. DEBUG_CLOSE() ---> void Closes the console. It is not an error to call this when the console is already closed. The console is automatically closed when DEBUG_RETURN is called from the (seemingly) outermost proceedure. DEBUGF(I, SF COMMA A1 COMMA A2 COMMA ...) ---> char * Other arguments just like PRINTF. The output is formatted and sent to the debug console. One key is accepted from the keyboard, and interpreted as follows: P the debug line is sent to the PRT: device, which is opened until the next DEBUG_CLOSE() if not already open. Q DEBUG_CLOSE() will be called, causing deugging output to be disabled until DEBUG_OPEN is called again. F debugging output will be appended to :T/DEBUGOUT, which will be opened if not already opened, and will remain open until DEBUG_CLOSE() is called. T DEBUG_TRACEBACK() will be called. C the previous action (other than T) will be repeated without pause until DEBUG_OPEN or DEBUG_CLOSE is called again. Good for CONTINUOUS output to a file or printer. Type a space to the debug window to regain control. N Nest: prompts for a digit 0 through 9. Any DEBUG_ENTER which causes the nesting level to exceed this will still be remembered, but will not generate any output on the debug console. Zero turns off all the reports except "main". A space typed in response to the prompt allows all nestings to display. D Detail: prompts for a digit 0 through 9. Any DEBUGF specifying an I larger than this number will not generate any output. A space typed in response to the prompt allows all details to display. Note that detail level of zero will always display. S Skip: debugging output will be discarded until a DEBUG_RETURN is called which restores the nesting level to the current level or lower. Essentially, debugging is turned off until the current function calls DEBUG_RETURN(). 0 thru 9 DEBUG_FUNC[0] thru DEBUG_FUNC[9] will be called if not NULL. Note that this could be ugly if the user does not fill in this global array with pointers to functions. RETURN just return SPACE Same as return The routine will keep scanning the keyboard until a C or a newline (return) or S is detected, at which point it return. Thus, several actions can be taken on a single debug statement. DEBUG_CONSOLE() ---> long Returns 0 if the debugging console is not open, otherwise returns a pointer to the open console, suitable for Read() and Write(). Don't Close() this yourself, or future calls to DEBUG may crash. DEBUG_ENTER(S, SF COMMA A1 COMMA A2 COMMA ...) ---> void Pass in the name of the function being entered. This will be remembered, even if the console is closed. If SF is not NULL, then the args after it (if any) are formatted as in PRINTF and displayed. If this is first called when the console is closed, it is assumed to be being called from main(), and calls DEBUG_OPEN(NULL) for you. DEBUG_RETURN(SF COMMA A1 COMMA A2 COMMA ...) ---> void Indicates that the most recent function to call DEBUG_ENTER is now returning. Automatically closes the colsole and otherwise makes sure that all resources have been freed if the nesting stack goes empty; it is assumed that you are about to exit from main(). This will eventually be implemented as a macro that actually returns the value of A1, if I can figure out how to cast the type properly; the problem is one of side-effects, mainly. DEBUG_EXIT() ---> void Frees all resources used by any of the DEBUG functions. Must be called before a call to Exit(), exit(), _exit(), or whatever; otherwise, you will be left with a console sitting around that you can't close. There will probably be much more over time, maybe including a program to automatically insert debugging calls into the program for you. In the future, I plan to add floating point support. If I hear requests, I may do it before I need it myself. If anyone is interrested in adding it themselves, I have the fuctions to format the numbers; they just have not been incorporated into the DO_PRNT function.