Gaijin.at

Windows Batch Programs

This article contains information on how to use the Windows command interpreter, as well as variables and important commands in batch programs.

Contents


The term "Batch Program" is used for batch files with the file name extensions .BAT or .CMD.

Command interpreter

The command interpreter processes both user input in the console and called batch programs. The following topics deal with some special features and useful functions of the command interpreter.

Masking special characters

If parameters for a command contain characters that are used by the command interpreter, the parameter must be enclosed in double quotation marks ("). These characters are ( ) [ ] { } ^ = ; ! ' + , ` ~ and the space character. Program and file names containing spaces and other special characters must also be enclosed in quotation marks. Quotation marks themselves do not need to be escaped within parameters.

Examples:
test.cmd Test1"ABC"
test.cmd Test2  ABC
test.cmd "Test3 "ABC""

Output of the 1st parameter with the command "echo %~1" in the file "test.cmd":

Test1"ABC"
Test2
Test3 "ABC"

If redirection characters (<, > or |) are used, they must be escaped with a circumflex (^).

echo ^<html^>

Prints the text "<html>".

Line breaks can also be masked with a circumflex:

echo Word1 ^
Word2 ^
Word3

Ausgabe:

Word1 Word2 Word3

To output a circumflex, it must also be escaped with a circumflex:

echo ^^

Only a circumflex is output.

To output a percent sign used for variables in a batch program, it must be masked with a percent sign.

echo %%1

Prints the text "%1". When entering manually in the console, masking is not required.

Dynamic variables

If command extensions are enabled, the command interpreter supports additional environment variables that are not displayed by the SET command.

VariableContent
%CD%Current directory as full path.
%CMDCMDLINE%Original command line that called the command interpreter "CMD" - including the parameters and options.
%CMDEXTVERSION%Version number of the current extensions for the command interpreter.
%DATE%Current date in the same format as the DATE command.
%ERRORLEVEL%Return value (exit code) of the last program or command.
%HIGHESTNUMANODENUMBER%Highest NUMA node number on this computer.
%RANDOM%Random decimal number between 0 and 32767.
%TIME%Current time in the same format as the TIME command.

Extension of variables

The command interpreter replaces the variables in a batch file with their contents before execution. This is also called "expansion" of variables. The only exception is delayed expansion.

Examples:
set var=2 or 3

This line set the variable var to "2 or 3".

if "%var%" == "1" goto start1

This line checks whether the quoted content of the variable var is equal to "1" (including the quotes).

The variable is replaced with the content before execution, which causes the line to be executed and checked like this:

if "2 or 3" == "1" echo start1

If the quotation marks are omitted from the comparison, the IF line would look like this:

if %var% == 1 goto start1

However, after expanding the variable, the command interpreter would try to execute the line like this:

if 2 or 3 == 1 echo start1

Since the number "2" is followed by the word "or" instead of the expected comparison operator, an error would occur.

This expansion of the variables before the actual execution of the commands can also have advantages, as this example shows:

goto Result%ERRORLEVEL%

:Result0
echo OK
goto :EOF

:Result1
echo ERROR!!!
goto :EOF

In der ersten Zeile wird der Name der Marke mit einer Variable ERRORLEVEL verbunden, um dann, basierend auf deren Wert, eine passende Meldung auszugeben. Wenn beispielsweise die Variable ERRORLEVEL gleich 0 ist, wird die erste Zeile so ausgeführt:

goto Result0

The label "Result0" is found by the command interpreter and execution continues from there.

Redirections

Console commands and console programs use channels for input and output.

Channel 0 (input channel, standard input or STDIN) is used to read keyboard input from the console.

Text is output to the console via channel 1 (output channel, standard output or STDOUT).

Error messages are output to the console via channel 2 (error channel, standard error output or STDERR).

The data from these channels can be redirected to other channels, to files or to devices, e.g. a printer (LPT1, LPT2 etc.).

Such redirections are specified after a command with a greater-than or less-than sign. The source channel and destination can be specified before and after these signs. If a channel is specified as the destination of the redirection, it must be preceded by an ampersand (&). If multiple redirections are specified, the redirection of the error channel to the output channel must be specified after the redirection of the output channel.

Redirections to a file create one if it doesn't exist. Any output redirection to a file with a simple greater than character (> or 2>) overwrites it.

If the output of one command is to be sent to the input of another command, a pipe character (|) is used.

Overview of common redirections:
Command > File
Redirects the command output to a file.
Command >> File
Appends the output of the command to a file.
Command < File
Sends the contents of a file as input to the command.
Command 2> File
Redirects the command's error messages to a file.
Command 2>> File
Appends the command's error messages to a file.
Command > File 2>&1
Redirects the error messages and command output to a file.
Command > File-A 2> File-B
Redirects output to File-A and error messages to File-B.
Command 2> nul
Displays no command error messages. Any data sent to the NUL device is discarded.
Command > nul 2>&1
Does not display error messages or command output.
Command > File 2> nul
Redirects the command output to a file. Error messages are not displayed.
Command-A | Command-B
Sends the output of Command-A to the input of Command-B. Example: "set | sort /R" displays the output of SET in reverse order.

Concatenate commands

To execute multiple commands on one line, they can be linked with an ampersand (&). Likewise, execution can be linked to the successful or error-free execution of another command. Whether a command was executed successfully is determined by its return value (error code).

Examples:
Command-A & Command-B
First execute Command-A and then Command-B.
Command-A && Command-B
If Command-A is executed successfully, Command-B is executed afterwards.
Command-A || Command-B
If Command-A is not executed successfully, Command-B is executed.
Command-A && Command-B || Command-C
If Command-A is executed successfully, Command-B is executed, if not, Command-C is executed.

Were the free content on my website helpful for you?
Support the further free publication with a donation via PayPal.

Read more about support options...

Local variables

The SETLOCAL command enables the limitation of the scope of variables to subsequent commands. Changes to variables made after SETLOCAL are undone at the end of the batch program or after the ENDLOCAL command.

Example:
@echo off

set TEST_Global=Original
echo TEST_Global=%TEST_Global%

setlocal
echo setlocal

set TEST_Global=Changed
set TEST_New=New
echo TEST_Global=%TEST_Global%
echo TEST_New=%TEST_New%

endlocal
echo endlocal

echo TEST_Global=%TEST_Global%
echo TEST_New=%TEST_New%

Output:

TEST_Global=Original
setlocal
TEST_Global=Changed
TEST_New=New
endlocal
TEST_Global=Original
TEST_New=

Command extensions

Command extensions extend the functionality of some commands and are usually enabled. The help for the commands also indicates how the command extensions affect the respective command and its parameters. In a batch file, the command extensions can be activated with the line:

setlocal EnableExtensions

When calling the command interpreter CMD, the command extensions are activated with the option "/E:ON" and deactivated with "/E:OFF".

Delayed expansion

The delayed expansion of environment variables ensures that variables are not expanded when the command (the line) is read, as is usual, but rather during execution. This allows, for example, variables to be changed in each iteration of a FOR loop, instead of just at the beginning. Command blocks that begin and end with parentheses also cause problems without delayed expansion. In a batch file, delayed expansion can be used with the line:

setlocal EnableDelayedExpansion

When calling the command interpreter CMD, delayed expansion is activated with the option "/V:ON" and deactivated with "/V:OFF".

When using delayed expansion, the variables in question must be enclosed with an exclamation mark instead of a percent sign. In the following example, these are the variables var in the IF block and files in the FOR loop. The variable files is expanded and correctly populated with each loop iteration thanks to delayed expansion.

Example:
@echo off
setlocal EnableDelayedExpansion

set var=1
echo %var% = 1 in main
if not "%var%" == "" (
	set var=2
	echo !var! = 2 in IF block
	set var=3
	echo !var! = 3 in IF block
)
echo %var% = 3 in main

echo.

set files=
for %%i in (.\files\*) do set files=!files! %%i
echo Files:%files%

endlocal

Output:

1 = 1 in main
2 = 2 in IF block
3 = 3 in IF block
3 = 3 in main

Files: .\files\test.jpg .\files\test.zip .\files\test1.txt .\files\test2.txt .\files\test3.txt

Without delayed expansion, the variable var in the IF block would not expand correctly. The variable files in the FOR loop would only contain the last filename, because the empty variable files would only be expanded on the first call. As a result, it would only contain the last filename at the end of the FOR loop.

Parameters and arguments

A batch file can be called with parameters via the console or from another batch file using the CALL command. Even when a label is called in a batch file using the CALL command, arguments can be passed. These parameters and arguments are then available as special variables:

%0
Contains the name of the batch file or brand.
%1, %2...
Contains the parameters passed during the call.
%*
Contains all parameters starting from the 1st parameter, each separated by a space.

A specific part of each of the parameters (%1, %2, etc.) can be returned. The following uses the first parameter (%1) as an example. However, some specifications require an existing file or directory name for the correct output.

ExpressionDescription
%~1Removes enclosing quotes (") before output. This is useful for file and directory names.
%~f1Returns the full file name. If a relative path is specified, the full path is returned.
%~d1Returns only the drive letter with the colon.
%~p1Returns only the path.
%~n1Returns only the file name without the extension.
%~x1Returns only the file extension, including the period.
%~s1Returns the short name of the file.
%~a1Returns the file attributes.
%~t1Returns the date/time of the file.
%~z1Returns the file size in bytes of the file.
%~$PATH:1Searches the directories specified in the PATH environment variable and expands the first file found, %1, to its full filename. If the environment variable name is undefined or the file was not found during the search, this parameter expands to an empty string.

The parameters can also be combined with each other:

%~dp1
Returns the drive letter and path.
%~nx1
Returns the file name and file extension.
%~tz1
Returns the date/time of the file and its size.

%~ must not be used with %*.

Example:
@echo off
setlocal EnableExtensions

call :printparams "C:\Windows\Explorer.exe"
goto :EOF

:printparams
echo Original:   %1
echo No Quotes:  %~1
echo Full Name:  %~f1
echo Drive:      %~d1
echo Path:       %~p1
echo Name:       %~n1
echo Extension:  %~x1
echo Short Name: %~s1
echo Attributes: %~a1
echo Date/Time:  %~t1
echo File Size:  %~z1 B
echo.
echo Drive and Path:      %~dp1
echo Name and Extension:  %~nx1
echo Date, Time and Size: %~tz1

goto :EOF

Output:

Original:   "C:\Windows\Explorer.exe"
No Quotes:  C:\Windows\Explorer.exe
Full Name:  C:\Windows\explorer.exe
Drive:      C:
Path:       \Windows\
Name:       explorer
Extension:  .exe
Short Name: C:\Windows\explorer.exe
Attributes: --a------
Date/Time:  22.01.2016 07:19
File Size:  3231232 B

Drive and Path:      C:\Windows\
Name and Extension:  explorer.exe
Date, Time and Size: 22.01.2016 07:19 3231232

SHIFT - Move parameter position

SHIFT [/parameter_position]

The SHIFT command moves the parameters by one position. If command extensions are enabled, the position of the first parameter to be moved can be specified as a parameter. Parameter numbering starts at 0. A slash must be specified before the position.

In the following example, all parameters are first moved one position. Then, starting with the third parameter (position 2), the parameters are moved one position.

Example:
@echo off
setlocal EnableExtensions

echo 0=%0
echo 1=%1
echo 2=%2
echo 3=%3

shift
echo.

echo 0=%0
echo 1=%1
echo 2=%2
echo 3=%3

shift /2
echo.

echo 0=%0
echo 1=%1
echo 2=%2
echo 3=%3

endlocal

Call parameters of the example:

test 111 222 333 444 555 666 777

Output:

0=test
1=111
2=222
3=333

0=111
1=222
2=333
3=444

0=111
1=222
2=444
3=555

Change text in variables

Text can be replaced, cut, or extracted from variables. However, this only affects the output (the expansion). The value of the variable in question is not changed. If this is desired, the new value must be assigned to the variable using SET.

Replacing and cutting text

The value of a variable can be searched for a search term and replaced with another text. This process is case-insensitive. If the replacement is empty, the searched text is removed.

Syntax: %Variable:SearchTerm=Replacement%

Example:
%var:abc=XYZ%
Replaces all occurrences of "abc" (regardless of capitalization - including "aBc" or "AbC") with the text "XYZ".
%var: =%
Removes all spaces.
%var:*test=TEST%
If an asterisk (*) is specified before the search term, the search result and everything before it will be replaced. If the variable "var" contains the value "This is a test text", "TEST text" is output. There is no corresponding functionality for removing the text after the search term.

Extracting text

Parts of the value of a variable can be extracted and output.

Syntax: %Variable:~Offset,Length%

The offset determines the position of the first character, starting at 0. If the offset is negative, counting starts from the end. The length determines the number of characters to be output. If the length is negative, counting starts from the end. If the length, including the comma, is omitted, the entire text is output to the end.

Examples:

For the following expressions, it is assumed that the variable "var" contains the text "1234567890".

ExpressionOutput
%var:~1,2%23
%var:~7%890
%var:~-3%890
%var:~-9,2%23
%var:~4,-2%5678

PUSHD and POPD

In batch files it often happens that you have to change to another directory briefly and then back to the previous directory.

PUSHD [Directory]

The PUSHD command saves the current directory and then changes to the specified directory.

POPD

The POPD command restores the directory saved with PUSHD as the current directory.

Examples:
cd
pushd C:\Windows
cd
popd
cd

If the current directory is "D:\Test", the following is output:

D:\Test
C:\Windows
D:\Test

CALL

CALL [Drive:][Path]Filename [Parameter]

The CALL command calls a batch file from another batch file.

After the file name, parameters can be passed to the called batch file, which it needs to execute.

If the command extensions are enabled, a label within the current batch file can also be specified as the jump target for the CALL command:

CALL :Label [Arguments]

These arguments create a new batch context and continue execution beyond the specified label. This makes processing similar to a subroutine or function.

To exit the batch context and continue processing after the CALL command, the GOTO command must be specified with the internal label ":EOF." Unlike other labels, the colon is required with the GOTO command. The GOTO command thus exits the batch file or, after a call via CALL command, the batch context.

Example:
echo 1
call :label
echo 3
goto :EOF

:label
echo 2
goto :EOF

echo This text is not displayed.

Output:

1
2
3

SET

SET [String]

The SET command displays the environment variables and their values. A string can be passed as a parameter, which only displays variables that begin with this string.

To create a new variable or change the value of an existing variable, the variable and the new value are passed to the SET command in the format "Variable=Value".

SET Variable=Value

Spaces before the equal sign belong to the name of the variable, spaces after the equal sign belong to the value.

If the value contains spaces, the parameter does not need to be enclosed in quotation marks. For trailing spaces, or for characters that the command interpreter also uses, such as & or >, quotation marks must be used. These must also enclose the variable name, otherwise the quotation marks are considered part of the value.

SET "Variable=Value"

To remove a variable, assign an empty value to the variable:

SET Variable=

SET /A - Calculate Numeric Expression

SET /A Variable=[Expression]
SET /A [Expression]

The "/A" parameter returns the result of a numeric expression. The result can also be stored in a variable, which can be specified before the expression.

When printing, please note that only decimal, octal, and hexadecimal numbers are supported. Octal numbers must be preceded by a "0", while hexadecimal numbers must be preceded by the character "0x".

All other values will either return an error message or be treated as 0. Variables do not need to be preceded by a percent sign in an expression. Some operators, such as & and >>, the expression must be enclosed in quotation marks as these are also used by the command interpreter.

OperatorOperationExpression SET /A "..."ResultNote
*Multiplication2*336Multiplies numbers.
/Division4/22Divide the first number by the second number.
%Modulo8%32Returns the remainder of a division.
+Addition2+35Adds numbers.
-Subtraction3-21Subtracts numbers.
<<Logical Shift Left8<<232Shifts the bits of a number to the left.
0000 1000 becomes
0010 0000
>>Logical Shift Right32>>28Shifts the bits of a number to the right.
0010 0000 becomes
0000 1000
&Bitwise And200&448Performs a logical AND comparison between the bits at the same position of both values. If both bits are 1, the result is 1; otherwise, the result is 0.
1100 1000 &
0010 1100 results in
0000 1000
|Bitwise Or200|44236Performs a logical OR comparison between the bits at the same position of both values. If at least one bit is 1, the result is 1; otherwise, it is 0.
1100 1000 &
0010 1100 results in
1110 1100
^Bitwise Exclusive Or200^44228Performs a logical exclusive-or comparison between the bits at the same position of both values. If both bits are equal, the result is 0; otherwise, the result is 1.
1100 1000 &
0010 1100 results in
1110 0100
...=Assignment to the same variablevar=3
var+=2		5Performs one of the operations described above with the value of the specified variable as the first value and a second value. The result is assigned to the variable.
!Logical Negation!10Negates a logical value. 0 (False) becomes 1 (True), 1 and any number except 0 becomes 0.
~Bitwise Inversion~0xfffffffe1Inverts a 32-bit signed number bitwise.
( )Grouping of operations(1+2)*26Groups operations. Without parentheses, the result would be 5 (* before +)
,Separation of expressionsvar=2+3,var*=210A comma separates several expressions from each other.

SET /P - User input

SET /P Variable=[Prompt]

The "/P" parameter assigns user input to a variable. Additionally, a prompt can be displayed.

Example:
@echo off
setlocal

set /P input="Please enter a text: "
echo You typed: %input%

endlocal

Output:

Please enter a text: Test
You typed: Test

SET /P - ECHO without line break

The SET command with the "/P" parameter can also be used to output text without line breaks. This can be useful if you want to output text on the same line before a program output.

The variable name can and should be omitted to prevent any changes to the variable. Input can be automatically generated using command redirection or input redirection. Therefore, only the command prompt is displayed in the examples. The output of the next command begins immediately afterward—without a line break.

Example:
<nul set /P="Current Directory: " & cd

or

echo | set /P ="Current Directory: " & cd

Output:

Current Directory: C:\Windows

IF

With IF, conditions can be checked and commands executed depending on them.

If the IF command is followed by NOT, the command is only executed if the condition is not met.

IF EXIST Filename Command

EXIST checks whether the specified file exists.

IF DEFINED Variable Command

DEFINED checks whether a variable exists.

IF ERRORLEVEL Number Command

ERRORLEVEL is a number returned by the last program to exit (corresponding to the "exit code"). It indicates whether the program exited successfully or due to an error. This code varies depending on the program. However, an exit code of 0 usually means that the program exited without errors.

The condition is met if ERRORLEVEL is equal to or greater than the specified number.

IF CMDEXTVERSION Number Command

CMDEXTVERSION can be used to check the version number of the command extensions. This is an integer starting at 1. This condition is not met if the command extensions are not enabled.

IF [/I] String1 ComparisonOperator String2 Command

This line compares two strings. The "/I" option specifies case insensitivity. It is only available when command extensions are enabled.

Depending on the content of the strings, such as spaces, quotation marks may be required. However, these characters will be included in the validation.

Example:
set var=Text
if %var% == "Text" (echo TRUE) else echo FALSE
if "%var%" == "Text" (echo TRUE) else echo FALSE

Output:

FALSE
TRUE

Possible comparison operators are:

OperatorComparison
==equal
EQUequal
NEQnot equal
LSSless than
LEQless than or equal
GTRgreater than
GEQgreater than or equal

Except for "==", all comparison operators are only available when command extensions are enabled. If both strings contain only numbers, the comparison is performed numerically.

ELSE

To execute a command with the same IF statement even if the condition is not met, the ELSE keyword can be used. ELSE must be on the same line as IF. Since it's impossible to distinguish between the spaces in the IF statement, ELSE, and the parameters of the commands to be executed, parentheses are used to enclose the command.

Example:
if exist test.txt (del test.txt) else echo test.txt not found.

Multiple commands can also be placed between the parentheses on multiple lines, as shown in the next example. For better readability, parentheses can also be used when they are not strictly necessary, such as after ELSE and only one subsequent command.

Example:
if exist test.txt (
	echo Removing test.txt ...
	del test.txt
	echo Done.
) else (
	echo test.txt not found.
)

FOR

FOR %Variable IN (Set) DO Command [Parameters]

The FOR command executes a command on a set of files.

FOR variables are case-sensitive. In a batch program, two percent signs must be used, i.e., "%%Variable."

The set can contain files and directories, with or without wildcards. Multiple files must be separated by a comma. The current file name is stored in the FOR variable.

Example:
for %i in (file.txt, directory, files\*) do @echo %i

In this example, the command - outputting the file name with ECHO - is executed for the file "file.txt", the directory "directory" and all files in the directory "files".

When command extensions are enabled, additional options are supported that provide more capabilities.

FOR /D %Variable IN (Set) DO Command [Parameters]

If a statement in the sentence contains a placeholder, it refers to directories and not to files.

FOR /R [[Drive:]Path] %Variable IN (Set) DO Command [Parameters]

The FOR command is executed recursively for the specified path as the root directory for each subordinate directory. If no path is specified, the current directory is used. If the sentence contains only a period, only the directories followed by a period are output.

FOR /L %Variable IN (Start,Increment,End) DO Command [Parameters]

With the "/L" option, the set is interpreted as a sequence of numbers from start to end, with the specified increment. A negative number can also be specified as the increment to count backward. The set (1, 1, 10) creates a sequence of numbers from 1 to 10. The set (32, -8, 0) creates the sequence of numbers 32, 24, 16, 8, and 0.

FOR /F ["Options"] %Variable IN (FileSet) DO Command [Parameters]
FOR /F ["Options"] %Variable IN ("String") DO Command [Parameters]
FOR /F ["usebackq Options"] %Variable IN (`Command`) DO Command [Parameters]
FOR /F ["usebackq Options"] %Variable IN ("File"...) DO Command [Parameters]

The FOR command opens all files in the file set and parses them line by line based on the specified options. The file set can contain one or more files, but cannot contain wildcards.

Alternatively, you can specify a string enclosed in double quotes. This string will be treated as a single line.

A command can also be executed and its output used for processing.

Processing is done with separators that break each line down into parts, called tokens. Each token to be output is stored in the FOR variable and the alphabetically following variables. In this case, the FOR loop, only one variable with a letter from a to z may be specified. A maximum of 26 variables can be filled with tokens in this way, provided the FOR variable is %a. The following variables are generated automatically. For example, if %i was specified as the FOR variable and tokens 1, 2, and 3 are to be output, the variable %i contains token 1, %j contains token 2, and %k contains token 3. The FOR command is case-sensitive.

The following options are possible:

eol=Character
Specifies the character for comment lines. Lines beginning with this character are ignored. Only a single character can be specified.
skip=NumberOfLines
Specifies the number of lines to skip at the beginning of a file.
delims=Delimiter
Specifies one or more separators that replace the standard delimiters tab and space. The line is split at these delimiters. The delimiters themselves are not output.
tokens=X,Y,M-N
Specifies which tokens should be stored in the variables. The individual tokens must be separated by a comma. A hyphen allows you to specify a range, e.g., "3-5" for tokens 3, 4, and 5. If the last character is an asterisk (*), the remaining text is stored in an additional variable.
usebackq
Specifies that the command should be executed within backquotes (`). If double quotes are used, the sentence is treated as a file or file list rather than a string. This allows filenames to be specified with spaces.

If no options are specified, the first word of each line is stored in the variable.

Replacements in FOR Variables

FOR variables can return a specific part. The following example uses the FOR variable %i. However, some statements require an existing file or directory name for the correct output.

ExpressionDescription
%~iRemoves enclosing quotes (") before output. This is useful for file and path names.
%~fiReturns the full file name. If a relative path is specified, the full path is returned.
%~diReturns only the drive letter with the colon.
%~piReturns only the path.
%~niReturns only the file name without the extension.
%~xiReturns only the file extension, including the period.
%~siReturns the short name of the file.
%~aiReturns the file attributes.
%~tiReturns the date/time of the file.
%~ziReturns the file size in bytes of the file.
%~$PATH:iSearches the directories specified in the PATH environment variable and expands the first file %i found to the full filename. If the environment variable name is undefined or the file was not found during the search, this parameter expands to an empty string.

The parameters can also be combined with each other:

%~dpi
Returns the drive letter and path.
%~nxi
Returns the file name and file extension.
%~tzi
Returns the date/time of the file and its size.
Example:
for /F "eol=; tokens=2,3* delims=, " %%i in (File.txt) do @echo %%i %%j %%k

The file "File.txt" is processed line by line. All lines beginning with a semicolon are ignored. Tokens 2 and 3 are stored in the variables %i and %j. The remaining tokens are stored in the variable %k.

for /F "usebackq delims==" %%i in (`set`) do @echo %%i

Lists the names of all environment variables. The equals sign is used as a separator.

for /F "usebackq delims== tokens=1*" %%i in (`set`) do @echo %%i = "%%j"

Lists the names of all environment variables and prints the value in quotes, e.g.:

%ProgramFiles% = "C:\Program Files"

Were the free content on my website helpful for you?
Support the further free publication with a donation via PayPal.

Read more about support options...