Debugging your batch files

Batch files will seldom be perfect right away.
This page describes some debugging techniques that will help you find and correct the errors.

Error messages

Often running a batch file will result in a cryptic error message between (or sometimes instead of) the expected output.
To discover the source of the message, follow these steps:

1. REM out the @ECHO OFF line, i.e. REM @ECHO OFF or :: @ECHO OFF
2. Run the batch file with the required command line parameters, redirecting all output to a log file for later comparison.
   For MS-DOS:
   
   mybatch.bat any_optional_parameters > mybatch.log
   
   For Windows NT 4 and later:
   
   mybatch.bat any_optional_parameters > mybatch.log 2>&1
   
   Search the file mybatch.log for the error message. Or, for Windows 2000 and later (download LOGBATCH.BAT first):
   
   LOGBATCH.BAT mybatch.bat any_optional_parameters
   
   Search the file mybatch_Test.log for the error message.
3. Check the previous line for any unexpected or invalid command, command line switch(es) or value(s); pay special attention to the values of any environment variables used in the command.
4. Correct the error and repeat this process until all error messages have disappeared.

Environment variables

A common source of errors are empty environment variables, or other unexpected values.
To check these values, follow these steps:

1. Insert "variable check lines" just before a line which uses the value in a command to check the value of a variable.
   For MS-DOS:
   
   ECHO.MyVariable=%MyVariable%
   
   For Windows NT 4 and later:
   
   SET MyVariable
   
   This will return a line like:
   
   MyVariable=MyValue
2. Follow the procedure to find error message sources described above.

Complex command lines

Another common source of errors are incorrectly redirected commands, like for example "nested" FIND or FINDSTR commands with incorrect search strings, sometimes within a FOR /F loop.
Here's a real-life example of such a one-liner:

FOR /F "tokens=8 delims=\" %%A IN ('TYPE %Temp%.\apipaorg.reg ^| FIND "[HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\TCPIP\Parameters\Interfaces\"') DO CALL :Enum "%%A"

To check the validity of these complex commands, follow these steps:

1. Insert "command check lines" just before a line which uses the complex command set.
   Going back to our example, this is what you might insert:
   
   TYPE %Temp%.\apipaorg.reg
ECHO.=====================================================
TYPE %Temp%.\apipaorg.reg | FIND "[HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\TCPIP\Parameters\Interfaces\"
   
   

   Note:

   The ECHO command is inserted to mark where the output of the first TYPE command ends and the next one starts

2. Follow the procedure to find error message sources described above.
   Pay special attention to the output of the "simplified" command lines: Is the output of the expected format? Is the "token" value or position as expected?

Subroutines

(Windows NT 4 and later)

Subroutines generating error messages pose an extra "challenge" in finding the cause of the error, as they may be called multiple times in the same batch file.
To help find out what causes the incorrect call to the subroutine, follow these steps:

1. Add and reset a counter variable at the beginning of the script:
   
   SET Counter=0
2. Increment the counter each time the subroutine is called, by inserting the following line at the beginning of the subroutine:
   
   SET /A Counter += 1
3. Insert another line right after the counter increment, containing only the SET command; this will list all environment variables and their values.
4. Follow the procedure to find error message sources described above.

Windows Versions

If you intend to distribute your batch files to other computers that may or may not run the same Windows version, you will need to test your batch files in as many Windows versions as possible.

Some, but not all, known compatibility issues are:

• REG.EXE version 3.0 vs. 2.0 and older
• Delayed variable expansion is not available in Windows NT 4 and possibly Windows 2000 base and earliest ServicePack
• As of Windows XP, SET /A and IF can handle much larger integers
• Windows XP's ServicePack 2 introduced almost as many changes as a complete new Windows version would

The solution for compatibility issues with REG queries only is to issue the command twice, once for each version.
This technique is demonstrated in my iDate sample.

For testing of internal commands, I keep copies of CMD.EXE of all my previous Windows versions.
For ease of use I renamed them cmdNT4.exe, cmdW2K.exe, cmdXP.exe, cmdXP2.exe etcetera.
Now if I want to know if an internal command will work in NT 4 I use a command like this:

cmdNT4.exe /K DIR /?

But before distribution of your scripts you still need to run a full test on every Windows version the script is intended for.

If in doubt, you can control in which version(s) the batch file is allowed to run:

@ECHO OFF
:: Check for Windows NT 4 and later
IF NOT "%OS%"=="Windows_NT" GOTO DontRun
:: Check for Windows NT 4
VER | FIND "Windows NT" >NUL && GOTO DontRun
:: Check for Windows 2000
VER | FIND "Windows 2000" >NUL && GOTO DontRun

:: Place actual code here . . .
   •
   •
   •
:: End of actual code . . .
EXIT

:DontRun
ECHO Sorry, this batch file was written for Windows XP and later versions only