part of The FreeDOS Project

Automate tasks with BAT files

A quick-start guide to writing FreeDOS batch files.

The FreeCOM (COMMAND.COM) shell is how you interact with FreeDOS. With FreeCOM, you can navigate the filesystem and run commands.

But you can also combine commands into a kind of "script" for FreeDOS, called a "batch" file, with 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.

Here's a helpful guide to batch files under FreeDOS.

Printing text

BAT files started out as just a collection of DOS commands, and DOS printed out each command as it was run. This is called "echo" and can make the output quite difficult to read. If you want to hide this output, you need to use one of two methods:

  1. Add a keyword with the ECHO statement: OFF to turn off command echo, and ON to turn it on.
  2. Add @ as the first character of any command.

To avoid printing any unwanted output from your BAT file, include this line at the top of the file:

ECHO OFF

However, FreeDOS will still print ECHO OFF to the screen as it executes this first statement. To avoid this, add @ as the first character the ECHO command, like this:

@ECHO OFF

Comments

If you're writing a very long BAT file, it can be helpful to include a comment to remind yourself what the BAT file is supposed to do, in case you ever need to update it again. A comment in a BAT file is called a remark statement, entered using the REM keyword:

REM - This is a comment

Calling another BAT file

Normally, FreeDOS processes only one BAT file at a time. If your BAT file runs another BAT file, the first BAT file is abandoned in favor of running the other BAT file. This is different from other operating systems like Linux, where one shell script can run another shell script like a program, and execution resumes in the first script after the second one is done.

To run a second BAT file from "inside" the first BAT file, use the CALL keyword:

CALL SETENV.BAT

Evaluation

BAT files support a simple set of conditions or tests using the IF statement. This has three basic forms:

1. Testing the return status of the previous command

A common use of BAT files is to run several commands at once. This is great unless the second command depends on the successful execution of the first command. That's when you need to test the return status of the previous command.

DOS programs usually exit with a status of zero if everything ran successfully, or some nonzero value otherwise. That exit status is also called the error level because it usually indicates some kind of error occurred. We can use that with the ERRORLEVEL test to evaluate the exit status.

@ECHO OFF
MYPROG
IF ERRORLEVEL 0 ECHO Success

Testing if a variable has a certain value

Another way to use IF is to test a value and then jump to another part of the BAT file. For example, we could instead write the BAT file with the == comparison and the ERRORLEVEL environment variable. FreeDOS sets the ERRORLEVEL variable with the return status of the most recently run command. This allows you to create BAT files that can process multiple things at once.

Let's say we need to run three programs, called PRE, MYPROG, and CLEANUP. If the first one does not run successfully, the BAT file should not try to run the other programs. We can add the NOT keyword to the IF test to test if PRE ran successfully, and exit immediately if not:

@ECHO OFF
PRE
IF NOT ERRORLEVEL 0 GOTO END
MYPROG
CLEANUP
:END

This also introduces the GOTO instruction, which jumps to a line label (labels start with the : character). The BAT file first runs the PRE program. If the program returned any value other than zero, then the BAT file jumps to the END label, which is the last line of the file, which immediately exits the program. Otherwise, the BAT file continues to the next line and runs MYPROG followed by CLEANUP.

3. Testing if a file exists or not

Let's say a program used a file to store temporary data. If the program aborted, you might want to delete the temporary file before running the program again. You can let a BAT file test if a file exists by using the EXIST keyword:

@ECHO OFF
IF EXIST TEMP.DAT DEL TEMP.DAT
MYPROG

Loops

If you need to perform the same set of tasks over a set of files, you can use a FOR loop to do everything in one line. To use a FOR loop, you need to specify a single-letter variable to store a value, plus a list (such as a list of files), while FOR iterates over that set of values. When run from the command line, the FOR loop looks like this:

FOR %F IN (*.ZIP) DO UNZIP %F

This uses the UNZIP program to extract every zip file in the current directory.

However, FOR has a slightly different syntax when used in a BAT file. Instead of a single %, use two of them:

@ECHO OFF
FOR %%F IN (*.ZIP) DO UNZIP %%F

Command line processing

BAT files let you process the command line given to it, by interpreting every item on the command line through numbered variables: %1 through %9. The special variable %0 holds the name of the BAT file.

If your BAT file needs to process more than nine options, you can use the SHIFT statement to remove the first option and shift every option after it by one position: %2 becomes %1, and so on.

For example:

@ECHO OFF
ECHO %1 %2 %3 %4 %5 %6 %7 %8 %9
SHIFT
ECHO %1 %2 %3 %4 %5 %6 %7 %8 %9

If we save this as ARGS.BAT and run it with a list of ten items, the first ECHO statement will print only the first nine elements. After the SHIFT statement, the second ECHO will print elements 2 through 10:

D:\>ARGS.BAT A B C D E F G H I J
A B C D E F G H I
B C D E F G H I J