How to automate tasks with BAT files
Even if you haven't used DOS before, you are probably aware of its command line shell, named simply COMMAND.COM
. The COMMAND.COM
shell has become synonymous with DOS, and so it's no surprise that FreeDOS also implements a similar shell called "FreeCOM" - but named COMMAND.COM
just as on other DOS systems.
But the FreeCOM shell can do more than just provide a command line prompt where you run commands. If you need to automate tasks on FreeDOS, you can do that using batch files, also called "BAT files" because these scripts use the .BAT
extension.
Batch files are much simpler than scripts you might write on Linux. That's because when this feature was originally added to DOS, long ago, it was meant as a way for DOS users to "batch up" certain commands. There's not much flexibility for conditional branching, and batch files do not support more advanced features such as arithmetic expansion, separate redirection for standard output vs error messages, background processes, tests, loops, and other scripting structure that are common in Linux scripts.
Here's a helpful guide to batch files under FreeDOS. Remember to reference environment variables by wrapping the variable name with "percent" signs (%
) such as %PATH
. However, note that FOR
loops use a slightly different construct for historical reasons:
Printing output
Your batch file might need to print messages to the user, to let them know what's going on. Use the ECHO
statement to print messages. For example, a batch file might indicate it is done with a task with this statement:
ECHO Done
You don't need quotes in the ECHO
statement. The FreeCOM ECHO
statement will not treat quotes in any special way, and will print them just like regular text.
Normally, FreeDOS will print out every line in the batch file as it executes them. This is usually not a problem in very short batch file that only define a few environment variables for the user. But for longer batch files that do more work, this constant display of the batch lines can become bothersome. To suppress this output, use the OFF
keyword to the ECHO
statement, as:
ECHO OFF
To resume displaying the batch lines as FreeDOS runs them, use the ON
keyword instead:
ECHO ON
Most batch files include an ECHO OFF
statement on the first line, to supress messages. But the shell will still print ECHO OFF
to the screen as it executes that statement. To hide that message, batch files often use an "at" signi (@
) in front. This special character at the start of any line in a batch file will suppress printing that line, even if "echo" is turned on.
@ECHO OFF
Comments
When writing any long batch file, most programmers prefer to use comments to remind themselves about what the batch file is meant to do. To enter a comment in a batch file, use the REM
(for remark) keyword. Anything after REM
will be ignored by the FreeCOM shell.
@ECHO OFF
REM This is a comment
Executing a "secondary" batch file
Normally, FreeCOM only runs one batch file at a time. However, you might need to use another batch file to do certain things, such as set environment variables that are common across several batch files.
If you simply call the second batch file from a "running" batch file, FreeCOM will switch entirely to that second batch file, and stop processing the first one. To instead run the second batch fiel "inside" the first batch file, you need to tell the FreeCOM shell to call the second batch file with the CALL
keyword.
@ECHO OFF
CALL SETENV.BAT
Conditional evaluation
Batch files do support a simple conditional evaluation structure with the IF
statement. This has three basic forms:
- Testing the return status of the previous command
- Testing if a variable is equal to a value
- Testing if a file exists
A common use of the IF
statement is to test if a program returned successfully to the operating system. Most programs will return a zero value if they completed normally, or some other value in case of an error. In DOS, this is called the error level and is a special case to the IF
test.
To test if a program called MYPROG
exited successfully, you actually want to examine if the program returned a "zero" error level. Use the ERRORLEVEL
keyword to test for a specific value, such as:
@ECHO OFF
MYPROG
IF ERRORLEVEL 0 ECHO Success
Testing the error level with ERRORLEVEL
is a klunky way to examine the exit status of a program. A more useful way to examine different possible return codes for a DOS program is with a special variable FreeDOS defines for you, called ERRORLEVEL
. This stores the error level of the most recently executed program. You can then test for different values using the ==
test.
You can test if a variable is equal to a value using the ==
test with the IF
statement. Like some programming languages, you use ==
to directly compare two values. Usually, you will reference an environment variable on one side and a value on the other, but you could also compare the values of two variables to see if they are the same. For example, you could re-write the above ERRORLEVEL
code with this batch file:
@ECHO OFF
MYPROG
IF %ERRORLEVEL%==0 ECHO Success
And another common use of the IF
statement is to test if a file exists, and take action if so. You can test for a file with the EXIST
keyword. For example, to delete a temporary file called TEMP.DAT
, you might use this line in your batch file:
@ECHO OFF
IF EXIST TEMP.DAT DEL TEMP.DAT
With any of the IF
statements, you can use the NOT
keyword to negate a test. To print a message if a file does not exist, you could write:
@ECHO OFF
IF NOT EXIST TEMP.DAT ECHO No file
Branched execution
One way to leverage the IF
test is to jump to an entirely different part of the batch file, depending on the outcome of a previous test. In the simplest case, you might want to skip to the end of the batch file if a key command fails. Or you might want to execute other statements if certain environment variables are not set up correctly.
You can skip around to different parts of a batch file using the GOTO
instruction. This jumps to a specific line, called a label, in the batch file. Note that this is a strict "go-to" jump; batch file execution picks up at the new label.
Let's say a program needed an existing empty file to store temporary data. If the file did not exist, you would need to create a file before running the program. You might add these lines to a batch file, so your program will always have a temporary file to work with:
@ECHO OFF
IF EXIST temp.dat GOTO prog
ECHO Creating temp file...
TOUCH temp.dat
:prog
ECHO Running the program...
MYPROG
Of course, this is a very simple example. For this one case, you might instead rewrite the batch file to create the temporary file as part of the IF
statement:
@ECHO OFF
IF NOT EXIST temp.dat TOUCH temp.dat
ECHO Running the program...
MYPROG
Iteration
What if you need to perform the same task over a set of files? You can iterate over a set of files with the FOR
loop. This is a one-line loop that runs a single command with a different file each time.
The FOR
loop uses a special syntax for the iteration variable, which is used differently than other DOS environment variables. To loop through a set of text files so you can edit each one in turn, use this statement in your batch file:
@ECHO OFF
FOR %%F IN (*.TXT) DO EDIT %%F
Note that the iteration variable is specified with only one "percent" sign (%
) if you run this loop at the command line, without a batch file:
C:\> FOR %F IN (*.TXT) DO EDIT %F
Command line processing
FreeDOS provide a simple method to evaluate any command line options the user might have provided when running batch file. FreeDOS parses the command line, and stores the first nine batch file options in the special variables %1
, %2
, .. and so on until %9
. Notice that the eleventh option (and beyond) are not directly accessible in this way. (The special variable %0
stores the name of the batch file.)
If your batch file needs to process more than nine options, you can use the SHIFT
statement to remove the first option, and shift every option "down" by one value. So the second option becomes %1
, and the tenth option becomes %9
.
Most batch files need to "shift" by one value. But if you need to "shift" by some other increment, you can provide that parameter to the SHIFT
statement, such as:
SHIFT 2
Here's a simple batch file that demonstrates shifting by one:
@ECHO OFF
ECHO %1 %2 %3 %4 %5 %6 %7 %8 %9
ECHO Shift by one ..
SHIFT 1
ECHO %1 %2 %3 %4 %5 %6 %7 %8 %9
Executing this batch file with ten arguments shows how the SHIFT
statement re-orders the command line options, so the batch file can now access the tenth argument as %9
: