Reference > Batch File Reference

Introduction

This reference was written from the point-of-view that no one is writing batch programs for MS-DOS, and that few people are writing batch programs for Windows 95. Most of the reference material is based on Windows 2000 and XP, with notes about functionality that differs between Windows 98 and 2000.

Batch file technology has evolved with each version of MS-DOS and early versions of Windows, and is now supplanted at least partly by the Windows Scripting Host (WSH). WSH gives you much greater flexibility and power because it lets you create scripts with powerful scripting languages like VBScript and JavaScript.

Ansi.sys - a toy-box for batch-file developers - gave batch programs the capability to change foreground and background colors, position the cursor, apply different text attributes, redefine keyboard keys and assign commands to function keys. Beginning with Windows 98 Millenium, terminate-and-stay-resident (TSR) real-mode drivers like ansi.sys were excluded from Windows startup in the attempt to reduce start-up time and improve stability ("device=" entries in config.sys are not processed unless you start in real mode).

Some of the capabilities provided by ansi.sys are available as environment variables, accessible through the command shell using SET and CMD; other MS-DOS commands are no longer available and some are replaced by new functionality built directly into Windows.

Commands

Batch file commands include the following:

• CALL - allows a batch file to call another batch file
• ECHO - suppresses or enables display of commands
• ENDLOCAL - ends localization of environment changes
• FOR - repeats processing on a set of files
• IF - tests for specific conditions
• GOTO - Directs processing to a line identified by a label
• NOT operator - Reverses the result of a true or false result in an IF command
• PAUSE - suspends execution
• REM - remark; comment
• SETLOCAL - changes environment variables for the batch file
• SHIFT - changes the position of parameters in a batch file

In addition to the standard batch file commands there are some DOS commands that are particularly useful for batch programs:

• CHOICE - displays message and waits for user input
• CMD - loads a second command processor into memory
• EXIT - MS-DOS command, returns processing to calling program
• NUL - bit bucket for disposing of unwanted output

CALL

Allows a batch file to run another batch file and then continue execution of the calling batch file.

    VER
    CALL bat2
    

    SET PATH=%PATH%;C:\Temp
    ECHO Path is now %PATH%
    

    Microsoft Windows 2000 [Version 5.00.2195]
    Path is now C:\WINNT\system32;C:\WINNT;C:\WINNT\System32\Wbem;C:\Temp
    

ECHO

Suppresses or enables the display of command names as MS-DOS executes the commands within a batch file.

    TIME
    DATE
    

    C:\> TIME
    Current time is 22:11:50.50
    Enter new time:

    C:\> DATE
    The current date is: Sat 06/30/2001
    Enter new date: (mm-dd-yy)
    

    @ECHO OFF
    TIME
    DATE
    

    Current time is 22:11:50.50
    Enter new time:
    The current date is: Sat 06/30/2001
    Enter new date: (mm-dd-yy)
    

ENDLOCAL

Ends localization of environment changes by restoring environment variables to their values before the matching SETLOCAL command.

FOR

Repeats processing on a set of files.

IF

IF is used to test for specific conditions. It has limited capabilities in batch files, compared to other languages: there are three conditions that can be tested. Including the NOT operator allows you to test the opposite condition.

First Form

Second Form

Third Form

GOTO

Directs processing to a line identified by a label. Processing begins on the line following the label.

NOT operator

Reverses the result of a true or false result in an IF command.

PAUSE

Temporarily suspends execution and displays an optional message. Execution continues when the user presses any key.

REM

Allows you to put remarks in a batch file.

    REM ftp database extract from host.
    REM Author: G. Swanson
    REM 2/10/1999
    

SETLOCAL

Changes (localizes) environment variables for the batch file. Localization ends when a matching ENDLOCAL command is encountered or when the end of the batch file is reached.

SHIFT

Changes the position of parameters in a batch file

CHOICE

Displays message and waits for user input. Input is defined as a set of keys in the setup for CHOICE; the exit-status returned by CHOICE is used to determine which key the user pressed.

CMD

16-bit version is COMMAND

Loads a second command processor into memory. The command shell program provides direct communication between the user and operating system. MS-DOS and Windows versions through Windows 98 (pre-millenium edition) used COMMAND.COM to execute batch programs, while later Windows versions use CMD.EXE. Windows Script Host runs more sophisticated scripts in the command shell.

EXIT

Use when calling another batch file from within a batch file. You must call EXIT to return processing to the calling batch file.

NUL

The NUL device - referred to as a bit bucket - is useful for disposing of unwanted output.

    ECHO the following PAUSE command will display a prompt:
    PAUSE
    ECHO the following PAUSE command will not display a prompt:
    PAUSE > NUL
    

Parameters

Parameters are the command-line arguments to your batch program. Cmd.exe provides variables %0 through %9, with %0 reserved for the batch-file name. If you have more than 9 input parameters to your batch program, you can use SHIFT to access them.

Modifiers

Modifiers expand batch parameters by taking drive and directory information and creating a partial or complete file or directory name. The syntax is
%~modifier.

Modifiers you can use include the following:

You can get compound results using combinations of modifiers listed in the following table:

Filters

Filter commands give you control over the display of information your batch program processes. Redirection operators are used with filter commands to determine their behavior.

• filter < filename sends input from a file to a filter command
• command | filter sends input from another command to a filter command
• filter < filename > filename2 sends input from a file to a filter command and saves the result in filename2

Filter commands include the following:

• MORE - displays command output or file contents in one command prompt window at a time
• FIND - searches files and command output for specified characters
• SORT - orders files and command output alphabetically

MORE

Displays command output or file contents in one command prompt window at a time.

    tree c:\inetpub | more
    

FIND

Searches files and command output for specified characters. Displays any lines that contain the specified characters.

SORT

Reads input from the keyboard, pipe, or file; sorts the data, and writes the result to screen, file, or another device.

    sort filename.txt

    find "Swanson" contacts.txt | sort
    

Redirection Operators

Redirection operators redirect command input and output stream locations. Stream location is referred to as a handle. Handles have numeric values, three of which are pre-defined: STDIN, STDOUT, and STDERR.

Default command input is sent via STDIN from the keyboard to the command processor (command.com or cmd.exe). Default command output is sent via STDOUT from the command processor to the Command Prompt window.

If you do not specify a handle when using redirection operators with the command processor, the default handle used by the < operator is zero (0) and the default handle used by the > operator is one (1). The syntax for redirection to existing handles is as follows:

For example you can redirect STDERR into STDOUT with this command:

    1<&2
    

Programming

• Interrupting Execution
• Redirecting Output
• Running One Command at a Time
• Suspend Processing

Interrupting Batch File Execution

You can interrupt execution of the commands in a batch file by holding down the Ctrl key and press C. DOS displays ^C and the message:

    Terminate batch job (Y/N)?
    

If you press Y, DOS immediately stops processing the batch file. If you press N, DOS ends the command it is currently executing, and continues execution with the next command.

Redirecting Output

You must specify I/O redirection on the specific command line(s) of the batch file if you want to send output of the batch file somewhere other than the screen.

Running One Command at a Time

When you have a batch file that is not working correctly, you can step through the file to find out which command is causing the problem. Use the COMMAND batch file command with the /Y and /C switches followed by the file name. DOS runs the file and stops at each command, with a prompt that lets you run the command or skip it.

Suspend Processing

When your batch file needs to wait until you perform some task, you can use the PAUSE command to display a message, suspending execution until you press a key to continue.

When the PAUSE command executes, it displays the message specified in its command line (if ECHO is not OFF), followed by the message:

    Press any key to continue...
    

Command Cross Reference

View the list of commands at the command prompt on Windows 2000 by typing help and pressing Enter. The HELP command is not available on Windows 98.

To view help for a command, open a command prompt (Windows 2000, XP) or DOS window (Windows 98) and enter /? command and press ENTER.

References

Jamsa, Kris, 1994, Concise Guide to MS-DOS Batch Files: Microsoft Press, 218 pages. ISBN 1-55615-638-3

Microsoft TechNet online reference - search for "command-line reference."

Copyright © 1999-2008. All rights reserved. | Contact | About SwansonSoftware.com