CALL Calls one batch program from another without causing the parent batch program to stop. The call command now accepts labels as the target of the call. call [drive:][path] filename [batch-parameters] call:label [arguments]
Parameters [drive:][path] filename Example: CALL F:\scripts\batchfile.bat Specifies the location and name of the batch program you want to call. The filename parameter must have a .bat or .cmd extension.
batch-parameters Specifies any command-line information required by the batch program. See below under the arguments parameter for extensions to batch-parameters.
:label Specifies the label (a specified part in the program) to which you want the batch program control to jump. Using the call command with this parameter creates a new batch file context and passes control to the statement after the specified label. The first time the end of the batch file is encountered (after jumping to the label), control returns to the statement after the CALL statement. The second time the end of the batch file is encountered, the batch script is exited.
ECHO Turns the command-echoing feature on or off, or displays a message. echo [on | off] [message]
Parameters on | off Specifies whether to turn the command-echoing feature on or off. To display the current echo setting, use the echo command without a parameter. message Specifies text you want Windows 2000 to display on the screen.
This example shows a batch program that includes a three-line message preceded and followed by a blank line:
echo off echo. echo This is a sample batch program echo Oh Dear said the Borg echo We've assimilated Pooh. echo.
If you want to turn echo off and you do not want to echo the echo command itself, include an at sign (@) before the command, as follows: @echo off
To echo a blank line on the screen, you can type echo and then a period (echo.). There must be no intervening space.
You can use the if and echo commands on the same command line, as follows: if exist *.log echo The log file has arrived.
To display a pipe (|) or redirection character (< or >) when using the echo command, use a caret character immediately before the pipe or redirection character (for example, ^>, ^<, or ^| ). If you need to use the caret character itself (^), use two in a row (^^).
Ends localization of environment changes in a batch file, restoring environment variables to their values before the matching setlocal command. There is an implicit endlocal command at the end of the batch file.
endlocal If command extensions are enabled (the default in Windows 2000), the endlocal command restores the enabled/disabled state of command extensions to what it was before the matching setlocal command was executed.
@echo off rem This program starts the labmice batch program on the network, rem directs the output to a file, and displays the file rem in Notepad. setlocal path=F:\scripts\labmice;%path% call labmice>c:\labmice.out endlocal start notepad c:\labmice.out
Runs a specified command for each file in a set of files. You can use the for command within a batch program or directly from the command prompt.
To use for in a batch program, use the following syntax: for %%variablein (set)do command [command-parameters]
To use for from the command prompt, use the following syntax: for %variablein (set)do command [command-parameters]
Parameters %%variable or %variable Represents a replaceable parameter. The for command replaces %%variable (or %variable) with each text string in the specified set until the command (specified in the command-parameters) processes all of the files. Use %%variable to carry out the for command within a batch program. Use %variable to carry out for from the command prompt. Variable names are case sensitive.
(set) Specifies one or more files or text strings that you want to process with the specified command. The parentheses are required.
command Specifies the command that you want to carry out on each file included in the specified set.
command-parameters Specifies any parameters or switches that you want to use with the specified command (if the specified command uses any parameters or switches).
If command extensions are enabled (the default setting in Windows 2000), additional forms of the for command are supported.
If command extensions are enabled, the following additional forms of the for command are supported:
If set contains wildcards (* and ?), specifies to match against directory names instead of file names.
Recursive for/R [[drive:]path] [%% | %]variablein (set)do command [command-parameters] Walks the directory tree rooted at [drive:]path, executing the for statement in each directory of the tree. If no directory is specified after /R then the current directory is assumed. If set is just a single period (.) character then it will only enumerate the directory tree.
Iterative for/L [%% | %]variablein (start,step,end)do command [command-parameters] The set is a sequence of numbers from start to end, by step amount. So (1,1,5) would generate the sequence 1 2 3 4 5 and (5,-1,1) would generate the sequence (5 4 3 2 1).
The filenameset parameter specifies one or more file names. Each file is opened, read and processed before going on to the next file in filenameset.
Processing consists of reading in the file, breaking it up into individual lines of text and then parsing each line into zero or more tokens. The body of the for loop is then called with the variable value(s) set to the found token string(s). By default, /F passes the first blank separated token from each line of each file.
Blank lines are skipped. You can override the default parsing behavior by specifying the optional "options" parameter. This is a quoted string which contains one or more keywords to specify different parsing options. The keywords are:
specifies an end of line comment character (just one character)
specifies the number of lines to skip at the beginning of the file.
specifies a delimiter set. This replaces the default delimiter set of space and tab.
specifies which tokens from each line are to be passed to the for body for each iteration. This will cause additional variable names to be allocated. The m-n form is a range, specifying the mth through the nth tokens. If the last character in the tokens= string is an asterisk, then an additional variable is allocated and receives the remaining text on the line after the last token parsed.
specifies that a back quoted string is executed as a command, a single quoted string is a literal string command, and you can use double quotes to quote file names in filenameset.
Variable substitution In addition, substitution modifiers for for variable references have been enhanced. You can now use the following optional syntax (for any variable I):
Variable (with modifier)
expands %I which removes any surrounding quotes (")
expands %I to a fully qualified path name
expands %I to a drive letter only
expands %I to a path only
expands %I to a file name only
expands %I to a file extension only
expands path to contain short names only
expands %I to the file attributes of file
expands %I to the date/time of file
expands %I to the size of file
searches the directories listed in the PATH environment variable and expands %I to the fully qualified name of the first one found. If the environment variable name is not defined or the file is not found by the search, then this modifier expands to the empty string.
The modifiers can be combined to get compound results:
Variable (with modifiers)
expands %I to a drive letter and path only
expands %I to a file name and extension only
expands %I to a full path name with short names only
searches the directories listed in the PATH environment variable for %I and expands to the drive letter and path of the first one found
expands %I to a dir-like output line
In the above examples, %I and PATH can be replaced by other valid values. The %~ syntax is terminated by a valid for variable name.
Using uppercase variable names such as %I can make your code more readable and avoid confusion with the modifiers, which are not case sensitive.
Directs Windows 2000 to a line in a batch program marked by a label you specify. The goto command directs Windows 2000 within a batch program to a line identified by a label. When Windows 2000 finds the label, it processes the commands beginning on the next line.
Parameter label Specifies the line in a batch program to which Windows 2000 should go. If command extensions are enabled (the default setting in Windows 2000), goto changes as follows: Using the goto command with a target label of :EOF transfers control to the end of the current batch script file, exiting the batch script file without defining a label.
Valid values for label The label parameter can include spaces but cannot include other separators, such as semicolons or equal signs. When using goto with the EOF label, you must insert a colon before the label, for example: goto :EOF
Goto uses the first eight characters of each label The goto command uses only the first eight characters of a label. Therefore, the labels ":hithere01" and ":hithere02" are both equivalent to ":hithere0."
Matching the label parameter with the label in the batch program The label value you specify on the goto command line must match a label in the batch program. The label within the batch program must begin with a colon.If your batch program does not contain the label that you specify, the batch program stops and Windows 2000 displays the following message: Label not found
Windows 2000 recognizes a batch program line beginning with a colon (:) as a label and does not process it as a command. If a line begins with a colon, Windows 2000 ignores any commands on that line.
The following batch program formats a disk in drive A as a system disk. If the operation is successful, the goto command directs Windows 2000 to a label named "end."
echo off format a: /s if not errorlevel 1 goto end echo An error occurred during formatting. :end echo End of batch program
Performs conditional processing in batch programs. If the condition specified in an if command is true, Windows 2000 carries out the command that follows the condition. If the condition is false, Windows 2000 ignores the command in the if clause, and executes any command in the else clause, if one has been specified.
if [not] errorlevelnumbercommand [elseexpression] if [not] string1==string2command [elseexpression] if [not] exist filenamecommand [elseexpression]
With command extensions enabled:
if [/i] string1compare-opstring2command [elseexpression] ifcmdextversionnumbercommand [elseexpression] ifdefinedvariablecommand [elseexpression]
not Specifies that Windows 2000 should carry out the command only if the condition is false.
errorlevelnumber Specifies a true condition only if the previous program run by Cmd.exe returned an exit code equal to or greater than number.
command Specifies the command that Windows 2000 should carry out if the preceding condition is met.
string1==string2 Specifies a true condition only if string1 and string2 are the same. These values can be literal strings or batch variables (%1, for example). Literal strings do not need quotation marks.
existfilename Specifies a true condition if filename exists.
compare-op one of the following three-letter comparison operators:
not equal to
less than or equal to
greater than or equal to
/i The /i switch, when specified, forces string comparisons to ignore case. The /i switch can also be used on the string1==string2 form of if. These comparisons are generic, in that if both string1 and string2 are both comprised of all numeric digits, then the strings are converted to numbers and a numeric comparison is performed.
cmdextversionnumber The cmdextversion conditional works just like errorlevel, except it is comparing against an internal version number associated with the Command Extensions feature of Cmd.exe. The first version is 1. It will be incremented by one when significant enhancements are added to the command extensions. The cmdextversion conditional is never true when command cxtensions are disabled.
definedvariable The defined conditional works just like exist except it takes an environment variable name and returns true if the environment variable is defined. Three variables are added with this conditional: %errorlevel%, %cmdcmdline%, and %cmdextversion%.
%errorlevel% expands into a string representation of the current value of errorlevel, provided that there is not already an environment variable with the name ERRORLEVEL, in which case you will get its value instead. After running a program, the following illustrates errorlevel use:
goto answer%erorlevel% :answer0 echo Program had return code 0 :answer1 echo Program had return code 1
You can also use the comparison operators listed above at compare-op:
if %errorlevel% LEQ 1 goto okay
%cmdcmdline% expands into the original command line passed to Cmd.exe prior to any processing by Cmd.exe, provided that there is not already an environment variable with the name cmdcmdline, in which case you will get its value instead.
%cmdextversion% expands into the a string representation of the current value of cmdextversion, provided that there is not already an environment variable with the name CMDEXTVERSION, in which case you will get its value instead.
expression In an else clause, an expression consists of a Windows 2000 command and any parameters to be passed to the command.
Using if to verify the presence of a file The following message appears if Windows 2000 cannot find the file Product.dat: if not exist product.dat echo Can't find data file
Using if to post a message when an error occurs The following example displays an error message if an error occurs during formatting of the disk in drive A:
echo off format a: /s if not errorlevel 1 goto end echo An error occurred during formatting. :end echo End of batch program
If no error occurs, the error message is skipped.
Using if to verify the presence of a directory The following example tests for the existence of a directory. The if command cannot be used to test directly for a directory, but the null (NUL) device does exist in every directory. Therefore, you can test for the null device to determine whether a directory exists.
c:mydir\nul goto process
Using the else clause The else clause must occur on the same line as the command after the if. For example:
IF EXIST filename. (
) ELSE (
echo filename. missing.
The following does not work, because the del command must be terminated by a newline: IF EXIST filename. del filename. ELSE echo filename. missing
The following does not work, because the else command must be on the same line as the end of the if command: IF EXIST filename. del filename. ELSE echo filename. missing
The following form of the original statement works, if you want to format it all on a single line: IF EXIST filename. (del filename.) ELSE echo filename. missing
Suspends processing of a batch program and displays a message prompting the user to press any key to continue.
Prompting the user to continue the program Windows 2000 displays the following message in response to the pause command:
Press any key to continue . . .
Dividing a batch file into sections If you press CTRL+C to stop a batch program, Windows 2000 displays the following message: Terminate batch job (Y/N)? If you press Y (for yes) in response to this message, the batch program ends and control returns to the operating system. Therefore, you can insert the pause command before a section of the batch file you may not want to process. While pause suspends processing of the batch program, you can press CTRL+C and then Y to stop the batch program
Suppose you want a batch program to prompt the user to change disks in one of the drives. To do this, you might create the following file:
@echo off :begin copy a:*.* echo Please put a new disk into drive A pause goto begin
In this example, all the files on the disk in drive A are copied to the current directory. After the displayed comment prompts you to place another disk in drive A, the pause command suspends processing so that you can change disks and then press any key to resume processing. This particular batch program runs in an endless loop. The goto BEGIN command sends the command interpreter to the begin label of the batch file. To stop this batch program, press CTRL+C and then Y.
Enables you to include comments (remarks) in a batch file or in your configuration files. This is useful for documentation, and explaining what each section of your batch file does. (Trust me, you'll forget what your programming logic was a year from now.)
Parametercomment Specifies any string of characters you want to include as a comment
Using the echo command to display comments The rem command does not display comments on the screen. You must use the echoon command in your batch or Config.nt file to display comments on the screen.
Restrictions on batch file comments You cannot use a redirection character "(" or ")" or pipe (|) in a batch file comment.
Using rem to add vertical spacing Although you can use rem without a comment to add vertical spacing to a batch file, you can also use blank lines. Windows 2000 ignores the blank lines when processing the batch program.
Examples The following example shows a batch file that uses remarks for both explanations and vertical spacing:
@echo off rem This batch program formats and checks new disks. rem It is named Checknew.bat. rem echo Insert new disk in drive B. pause format b: /v chkdsk b:
Suppose you want to include in your Config.nt file an explanatory comment before the prompt command. To do this, add the following lines to Config.nt:
rem Set prompt to indicate current directory prompt $p$g
Allows you to create a environment variable for use within a batch file. This variable lasts until a matching endlocal command is encountered, or the until end of the batch file.
Parameter option When command extensions are enabled (the default in Windows 2000), the setlocal batch command accepts an optional argument, which can be either enableextensions or disableextensions. This enables or disables the command extensions until the matching endlocal command, regardless of their setting prior to the setlocal command.
The setlocal command also sets the errorlevel value when it is passed an argument. The errorlevel value is set to zero (0) if one of the two valid arguments is given and set to one (1) otherwise.
Changes the position of replaceable parameters in a batch file.
shift When command extensions are enabled (the default setting in Windows 2000), the shift command supports the /n switch, which tells the command to start shifting at the nth argument, where n can be a value from zero to eight.
For example, SHIFT /2 would shift %3 to %2, %4 to %3, and so on, and leave %0 and %1 unaffected
How the shift command works The shift command changes the values of the replaceable parameters %0 through %9, by copying each parameter into the previous one. In other words, the value of %1 is copied to %0, the value of %2 is copied to %1, and so on. This is useful for writing a batch file that performs the same operation on any number of parameters.
Working with more than 10 command-line parameters You can also use the shift command to create a batch file that can accept more than 10 parameters. If you specify more than 10 parameters on the command line, those that appear after the tenth (%9) will be shifted one at a time into %9.
Shifting parameters back There is no backward shift command. After you carry out the shift command, you cannot recover the first parameter (%0) that existed before the shift.
Example The following batch file, testcopy.bat, shows how to use the shift command with any number of parameters. It copies a list of files to a specific directory. The parameters are the directory name followed by any number of file names.
@echo off rem TESTCOPY.BAT copies any number of files rem to a directory. rem The command uses the following syntax: rem testcopy dir file1 file2 ... set todir=%1 :getfile shift if "%1"=="" goto end copy %1 %todir% goto getfile :end set todir= echo copy completed
A variable is a replaceable parameter. The parameters %0 and %1 to %9 can be placed anywhere within a batch file. When the batch file is run, %0 is replaced by the name of the batch file, and the argument variables %1 to %9 are replaced by the corresponding parameters entered on the command line.
For example, to copy the contents of one folder to another, you would add the following statement in your batch file:
xcopy %1\*.* %2
When you run the file, you would type the following:
mybatch.bat C:\afolder D:\bfolder.
The effect is the same as if you had written xcopy C:\afolder \*.* D:\bfolder in the batch file.
The % parameter expands the batch script argument variables (%0, %1, ..., %9) as follows:
%* in a batch script is a wildcard reference to all the arguments. For individual argument variables, the expansion options are explained in the following tables.
expands %1 and removes any surrounding quotes (")
expands %1 to a fully qualified path name
expands %1 to a drive letter
expands %1 to a path
expands %1 to a file name
expands %1 to a file extension
expanded path contains short names only
expands %1 to file attributes
expands %1 to date/time of file
expands %1 to size of file
searches the directories listed in the PATH environment variable and expands %1 to the fully qualified name of the first one found. If the environment variable name is not defined or the file is not found by the search, then this modifier expands to the empty string.
The modifiers can be combined to get compound results:
expands %1 to a drive letter and path
expands %1 to a file name and extension
searches the directories listed in the PATH environment variable for %1 and expands to the drive letter and path of the first one found
expands %1 to a dir-like output line
In the above examples %1 and PATH can be replaced by other valid values. The %~ syntax must be terminated by a valid argument number. The %~ modifiers may not be used with %*.