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.