Debugging JCC Programs.


Building with Trace-On.

The JCC compiler will generate additional information for a remote debugging server to control the program flow and allow variables to be viewed, the parameter:

-test=file.tst
must be used when compiling files that need to be debugged. All source files which are to become a complete JCC program (and are to be traced) should specify the same filename with this parameter. Each compile step will append its additional debugging data to the end of the file. When the debugger loads this file, it only takes the most recent information available, which allows individual files to be recompiled without the need to rebuild the entire 'debug' file.

A new scanning program dbgscan also needs to be used with the assembler list output:

Usage: dbgscan input.lst file.tst
 Appends assembler output to a test file created by JCC.
the file.tst file should also be the same file referenced when compiling with -test. dbgscan reads the assembler-listing and adds the generated JCC comments to the 'debug' file along with the code offsets within the assembled object. This step is not required when using the -o direct object generation function of JCC.

When prelinking, the prelink parameter:

-test=file.tst
also needs to be specified as the first parameter, which appends object offsets to the 'debug' file. Additional JCC library objects for debug are used when -test is specifed. This concludes the additional steps required for building a JCC program with debug turned on.


To allow fully remote tracing (using multiple computers) the global variable char * debug_server = "computer"; can be defined within a souce code file which makes up the JCC program. If the variable exists the default "127.0.0.1" is no longer used to connect to the server-debugger, and is replaced with the user specified string.


Running the Debugger.

The program jccdbg is the command-line server-debugger which comes with JCC (the Visual Basic JCC GUI Debugger for Windows is easier to use under that OS... see: guidbg.)

The 'current path' must be exactly the same as that used by the JCC Compiler to compile the source code (as the debugger also needs to load those files from the same path offsets.) When started, the server-debugger waits for a new connection from a JCC program - if no debugger is running when a JCC program is executed, then it runs without trace but with reduced performance as compared to JCC programs without debugging switched on.

The initial response to a connection from a JCC program to the debugger, is to ask which test file should be used to perform a trace. At this point 'help' will show the available commands:

run - runs the program without loading a debugging file.
term - terminates the program with RC=0 and continues to wait for new JCC programs.
quit - terminates the program with RC=0 and exits the debugger.
When the filename of a valid 'debug' file is entered, its contents are loaded and information about why the program has entered trace is printed. These are the available commands: (also shown if 'help' is entered at the '>' prompt.)
b or break - sets a breakpoint
c or clear - resets a or all breakpoints
d or dump  - dumps a or all scoped variables
l or list  - lists source filenames
s or step  - steps into one statement
o or over  - steps over one statement
g or go    - runs the program
q or quit  - terminates the program and quits debugging
t or term  - terminates the program with rc=0
break will set a breakpoint at the current statement, or if a line number is also entered then at that line position within the current source file. If both a source file (as described when the list command is used) and a line number is entered (delimited by a space) then any code which was generated by that source-code-line will trigger a breakpoint.

NOTE: care must be exercised to ensure the line number entered is one which will cause a breakpoint in the JCC program. (Not all source code lines are the start of a statement.)

clear will reset all breakpoints, or if an address is supplied (as printed when a breakpoint occurs) then only that breakpoint will be reset.

dump will print out all scoped variables available from the current trace-position. If a name is also supplied, then only variables starting with the name entered are displayed. If a number is supplied then 4 bytes are displayed at the memory location described by the number - care must be used with this option - accessing invalid memory locations will cause the JCC program to ABEND. An optional length is allowed when dumping memory this way.

list shows the exact text entry required to specify a breakpoint location in a source file.

step traces one statement.

over traces until the next statement within the current function.

go runs the program until a breakpoint occurs.

quit terminates the program with RC=0, and exits the debugger.

term terminates the program with RC=0, and waits for a new JCC program to connect.