How do I debug my program?

One of the most useful tools in Stata for debugging programs is set trace. By default, set trace is turned off. To use it, simply type

        .  set trace on

and run the program again. You will see lots of output, as Stata will display each line from each ado-file that it runs.

If the program you are debugging is giving you an error message and exiting, the error message will appear in the trace output after the last line that Stata attempted to execute. Because you know which line is causing the error, you may immediately recognize what is wrong, and then make a change to your program.

If you cannot immediately recognize what is wrong, you might be interested in customizing the trace output with any of the six trace control commands: set tracedepth, set traceexpand, set tracesep, set traceindent, set tracenumber, and set tracehilite. Their default values are

If your trace settings are all set to the default values, you will see each line that was executed preceded by a single dash. If an executed line contains any macros, local or global, Stata will display the line twice, once with a single dash in front of it the way it appears in the ado-file and once preceded by an equal sign with all of the macros expanded to show the values they contain.

This display of the line with all macros expanded is the default setting. You can toggle this behavior by typing set traceexpand off or set traceexpand on.

In the trace output, you will also notice that, whenever one ado-file calls another ado-file, a separator line containing the name of the subprogram is displayed, and the commands in that nested ado-file are indented. This is the default behavior from the settings of set tracesep and set traceindent. To change this behavior, type set tracesep off or set traceindent off.

If you wish to see the nesting level of a particular program, you can type set tracenumber on. The nesting level will precede each line, starting at 01. If the top-level program calls another ado-file, the called program will have its lines preceded by an 02, and so on.

You can control whether deeper nested programs show up in the trace output by changing the value of set tracedepth. For example, if you were only concerned with tracing the main program and any programs it calls, you could type set tracedepth 2. Only lines from these two levels would show in the trace output.

Many times when you are looking at trace output, you may find it hard to find exactly what you are looking for because so many lines are displayed. In such cases, set tracehilite may be useful. If you type something like set tracehilite "mymacro", every time the pattern "mymacro" occurs in your trace output, it will be highlighted, making it easier to pick out.

If the trace output does not help you figure out what is wrong in your program, you might want to add display lines to your program that display the values of particular macros at different points. For example, you might include debugging lines such as

        display `"mymacro = |`mymacro'|"'

After you are finished debugging, you will want to get rid of all of the debug output. You turn the trace off by typing

        . set trace off

Note:  When you are editing your program and you make changes, make sure to use the program drop _all or discard command so that Stata will reread your ado-file and implement any changes that you make.

Note:  If you have a long ado-file or if there is a lot of output from the trace, you may wish to log the output and use the command set more off so that Stata will not pause during the execution of the command. To return to the usual pauses, use set more on.

        . log using junk, replace
        . prog drop _all
        . set more off
        . set trace on
        . run your program again
        . log close
        . set more on
        . set trace off