Debugging Batch Files
CMD.EXE includes a built-in batch file debugger, invoked with the SETDOS
/Y1 command. The debugger allows you to "single-step" through a batch
file line by line, with the file displayed in a popup window as it
executes. You can execute or skip the current line, continue execution
with the debugger turned off, view the fully-expanded version of the
command line, or exit the batch file. The batch debugger can also pop up
a separate window to view current environment variables or aliases so you
can check their values during execution, and can pop up the LIST command
to display the contents of any file.
To start the debugger, insert a SETDOS /Y1 command at the beginning of the
portion of the batch file you want to debug, and a SETDOS /Y0 command at
the end. You can also invoke SETDOS /Y1 from the prompt, but because the
debugger is automatically turned off whenever the command processor
returns to the prompt, you must enter the SETDOS command and the batch
file name on the same line, for example:
[c:\] setdos /y1 & mybatch.btm
If you use the debugger regularly you may want to define a simple alias to
invoke it, for example:
[c:\] alias trace `setdos /y1 & %$`
This alias simply enables the debugger, then runs whatever command is
passed to it. You can use the alias to debug a batch file with a command
like this:
[c:\] trace mybatch.btm
When the debugger is running you can control its behavior with keystrokes.
Debugging continues after each keystroke unless otherwise noted:
T(race), Enter, or F8
Executethecurrentcommand . If
itcallsasubroutinewithGOSUB
,oranotherbatchfilewithCALL ,single -
stepintothecalledsubroutineorbatchfile .
S(tep) or F10 Execute the current command, but execute any
subroutine or CALLed batch file without
single-stepping.
J(ump) Skip the current command and proceed to the next
command.
X (Expand) Display the next command to be executed, after
expansion of aliases and environment variables.
L(ist) Prompt for a file name and then view the file with
the LIST command.
V(ariables) Open a popup window to display the current
environment, in alphabetical order.
A(liases) Open a popup window to display the current aliases,
in alphabetical order.
O(ff) or Esc Turn off the debugger and continue with the
remainder of the batch file.
Q(uit) Quit the debugger and the current batch file,
without executing the remainder of the file.
The debugger highlights each line of the batch file as it is executed.
It executes the commands on the line one at a time, so when a line
contains more than one command, the highlight will not move as each
command is executed. To see the individual commands, use the X key to
expand each command before it is executed.
If you use a "prefix" command like EXCEPT, FOR, GLOBAL, or SELECT, the
prefix command is considered one command, and each command it invokes is
another. For example, this command line executes four commands -- the
FOR and three ECHO commands:
for %x in (a b c) do echo %x
You cannot use the batch debugger with REXX files or EXTPROC files. It
can only be used with normal CMD.EXE batch files.
The debugger gives you a detailed, step-by-step view of batch file
execution, and will help solve particularly difficult batch file
problems. However, in some cases you will find it easier to diagnose
these problems with techniques that allow you to review what is happening
at specific points in the batch file without stepping through each line
individually.
There are several tricks you can use for this purpose. Probably the
simplest is to turn ECHO on at the beginning of the file while you're
testing it, or use SETDOS /V2 to force ECHO on even if an ECHO OFF
command is used in the batch file. This will give you a picture of what
is happening as the file is executed, without stopping at each line. It
will make your output look messy of course, so just turn it off once
things are working. You can also turn ECHO on at the beginning of a
group of commands you want to "watch", and off at the end, just by adding
ECHO commands at the appropriate spots in your file.
If an error occurs in a batch file, the error message will display the
name of the file, the number of the line that contained the error, and
the error itself. For example:
e:\test.bat [3] Invalid parameter "/d"
tells you that the file E:\TEST.BAT contains an error on line 3. The
first line of the batch file is numbered 1.
Another trick, especially useful in a fast-moving batch file or one where
the screen is cleared before you can read messages, is to insert PAUSE
commands wherever you need them in order to be able to watch what's
happening. You can also use an ON ERRORMSG command to pause if an error
occurs, then continue with the rest of the file (the first command
below), or to quit if an error occurs (the second command):
on errormsg pause
on errormsg quit
If you can't figure out how your aliases and variables are expanded, try
turning LOG on at the start of the batch file. LOG keeps track of all
commands after alias and variable expansion are completed, and gives you
a record in a file that you can examine after the batch file is done.
You must use a standard LOG command; LOG /H (the history log) does not
work in batch files.
You may also want to consider using redirection to capture your batch
file output. Simply type the batch file name followed by the redirection
symbols, for example:
[c:\] mybatch >& testout
This records all batch file output, including error messages, in the file
TESTOUT, so you can go back and examine it. If you have ECHO ON in the
batch file you'll get the batch commands intermingled with the output,
which can provide a very useful trace of what's happening. Of course,
output from full-screen commands and programs that don't write to the
standard output devices can't be recorded, but you can still gain a lot
of useful information if your batch file produces any output.
If you're using redirection to see the output, remember that any prompts
for input will probably go to the output file and not to the screen, so
you need to know in advance the sequence of keystrokes required to get
through the entire batch file, and enter them by hand or with KEYSTACK.
You can also use the TEE command to both view the output while the batch
file is running and save it in a file for later examination.
Created using Inf-PHP v.2 (c) 2003 Yuri Prokushev
Created using Inf-HTML v.0.9b (c) 1995 Peter Childs