.BAT File Format – File structure

Extensions

Microsoft’s call page says the file named after call must have a .bat or .cmd extension. Two file names have a fixed role:

• AUTOEXEC.BAT – run by COMMAND.COM at start-up in MS-DOS and Windows 9x. Windows NT reads the environment variables and paths set in it (the Microsoft cmd page lists it among the sources of variables).
• AUTOEXEC.NT – run when a 16-bit DOS program starts under Windows NT; the Microsoft set page says set is often used in it. It is written like a batch file.

.bat against .cmd

cmd.exe reads a .bat and a .cmd file with the same parser, the same commands and the same syntax. The difference reported by SS64 and others is in ERRORLEVEL: a few commands that change the environment or the file associations (the reported list includes set, path, prompt, assoc and ftype) always set it in a .cmd file, but in a .bat file they set it only when they fail. Microsoft’s pages do not describe this, so it is given here as reported, not checked. See Errorlevel and exit codes.

COMMAND.COM does not know .cmd at all: it runs only .com, .exe and .bat files.

How the file is found

Typing a name runs the first match: a command built into the interpreter, then a file in the current directory, then a file in each directory of PATH. If no extension is typed, cmd.exe tries each extension of the PATHEXT variable in turn. A usual value is .COM;.EXE;.BAT;.CMD;.VBS;.VBE;.JS;.JSE;.WSF;.WSH;.MSC, so build runs build.exe before build.bat. COMMAND.COM tries .COM, then .EXE, then .BAT.

When a batch file is run by typing its name, control does not return to the file that typed it: the new file replaces it unless it is run with call (see Parameters and labels).

How the file is read

The interpreter reads the file again from disk for each command, remembering the byte offset of the next line, not the whole text. This is why a batch file can be edited while it runs, with odd results, and why goto searches for its label by reading the file from the start. A .btm file is the exception: it is loaded once.

Because the file is not compiled, a syntax error is found only when the line that holds it is reached.

Encodings

• Code page, not Unicode. A batch file holds one byte per character (or two for a double-byte code page) and is read in the console’s active code page, the OEM page of the system (437, 850, 866 and so on) unless chcp has changed it. The same bytes mean different characters on another computer. A file with accented characters, written in a Windows ANSI editor, shows them wrongly when run.
• UTF-8. After chcp 65001 the console’s code page is UTF-8, and a batch file saved as UTF-8 without a byte order mark can then hold non-ASCII text in its strings and file names. The chcp command has to run before such text is read, so it goes near the top of the file and the lines before it stay ASCII.
• Byte order mark. A UTF-8 file that starts with the bytes EF BB BF is widely reported to make the first command fail, because those bytes become part of its name (for example @echo). Save batch files without a mark.
• UTF-16. Not supported: a file that starts FF FE or FE FF, or that holds a zero byte after each letter, is not read as batch text.
• Output encoding. cmd /a makes output ANSI and cmd /u makes it UTF-16, which affects redirected files, not the script file.

The viewer reads a batch file as text in the encoding it detects and treats each character alike, so a code page does not change the colouring.

Line ends and Ctrl-Z

• CR LF. The line end of DOS and Windows text, bytes 0D 0A, and what every batch file should use.
• LF alone. cmd.exe runs a file that uses bare line feeds, but a file with Unix line ends is widely reported to break goto and call :label when the label falls across a boundary of the buffer the interpreter reads in. Keep CR LF.
• Ctrl-Z. The byte 1A was the end-of-text marker of DOS text files, written after the last line by old editors. type stops there on DOS. Whether the interpreter stops reading at it is not documented. The viewer reads it as white space.
• A last line without a line end is still run.
• NUL bytes have no meaning in batch text, and the viewer shows a file that holds them as binary.

Limits

• Microsoft says the longest command line cmd.exe handles, after variables are expanded, is 8191 characters, in a batch file as at the prompt. The same limit applies to each environment variable it inherits.
• Older documentation gives 127 characters for COMMAND.COM on MS-DOS; this was not checked against a primary source here.
• Microsoft’s for page says no more than 52 loop variables can be active at a time.
• Nesting of parenthesised blocks and of call is limited by memory and stack, not by a documented number.

Running a batch file

Nothing marks a text file as a script except its extension and, for a file that is run directly, the association Windows has for it. A batch file started from the desktop is run by a new cmd.exe as cmd /c "file.bat" and the window closes when it ends; cmd /k keeps it open. The cmd options that matter to a script are:

Without /d, cmd first runs the commands in the AutoRun registry value under HKLM\Software\Microsoft\Command Processor and HKCU\Software\Microsoft\Command Processor. The EnableExtensions values under the same keys set the default for command extensions. All of this is from the Microsoft cmd page.

A file as bytes

@echo off
rem Written with CR LF line ends and no byte order mark.
chcp 65001 >nul
echo Grüße
pause

Not described