.BAT File Format – Parameters and labels

Arguments

Arguments are separated by spaces, tabs, and also by ,, ; and = (reported: build.bat a=b gives %1 as a and %2 as b). Text in double quotes is one argument, and the quotes stay in the value. Only nine arguments can be named directly: use shift or %* for more.

Since an empty argument makes if %1==x a syntax error, the usual tests are if "%~1"=="" and, in old scripts, if [%1]==[].

Modifiers

A ~ after the percent sign expands the argument and then changes it. Modifiers are not case sensitive and can be combined in any order, and the argument number ends the syntax (Microsoft’s call page). The same modifiers apply to for variables.

Combined: %~dp1 (drive and path), %~nx1 (file name and extension), %~fs1 (full path, short names), %~dp$PATH:1 (drive and path of the match in PATH), %~ftza1 (a line like dir shows). The most used form is %~dp0, the folder the batch file is in, ending with a backslash, which makes a script independent of the current directory: "%~dp0tools\run.exe".

shift

shift moves each argument down one place: %2 becomes %1 and so on, and the tenth argument becomes %9. %0 is not changed. With command extensions, shift /n starts shifting at the nth argument (0 to 9) and leaves the ones before it. A loop that takes each argument in turn:

:next
if "%~1"=="" goto done
echo Argument: %~1
shift
goto next
:done

goto

goto label continues at the line after the label :label. It searches the file from the start, so a label above the goto works too.

• The match is not case sensitive, and the name is the text up to the first space; the characters ; and = cannot be in it (Microsoft).
• With command extensions on, goto :eof goes to the end of the current batch file, or of the current call :label subroutine, with no label needed. The colon is required, and goto:eof is accepted.
• If the label is not found, the batch file stops with Label not found.
• A goto out of the middle of a ( ) block or a for loop is allowed and abandons the block.
• The label can be built from a variable: goto answer%errorlevel% jumps to :answer0, :answer1 (Microsoft’s if example).

call

Without call, running another batch file from a batch file hands control over and does not come back. call runs it and returns to the next line when it ends (Microsoft).

• Do not use pipes or redirection with call, says Microsoft.
• call does nothing at the prompt outside a script.
• A batch file may call itself, but needs an exit condition or it loops until the stack is exhausted.
• The called file shares the environment of the caller. Variable changes stay unless the callee used setlocal. A subroutine has no local variables of its own beyond that.
• The exit code of the callee is available in %errorlevel% afterwards.

Subroutines

A subroutine is a label with exit /b or goto :eof at its end, called with call :name args, and kept after the main code so that execution does not fall into it. A result is returned in the exit code or in a variable whose name the caller passes in.

@echo off
call :square 7 result
echo 7 squared is %result%
call :banner "Done"
exit /b 0

:square
set /a %2=%1*%1
goto :eof

:banner
setlocal
set "text=%~1"
echo ==== %text% ====
endlocal
exit /b 0

exit /b [code] ends the current batch file or subroutine and sets ERRORLEVEL to code; exit without /b ends the whole cmd.exe (Errorlevel and exit codes).

Running other programs

• A program runs and the batch file waits for it, if it is a console program. A Windows (GUI) program is started and the batch file goes on; start /wait waits for it.
• start "" "C:\Program Files\App\app.exe" – the first quoted argument of start is a window title, so an empty title is put in front of a quoted path.
• cmd /c file.bat runs a batch file in a new cmd.exe, whose variable changes are lost on return.

Not described