How to Use FreeCOM Batch Features Beyond a Linear Startup Script

Most FreeDOS batch files people actually write are linear scripts - a fixed sequence of commands run top to bottom. FreeCOM, FreeDOS’s command interpreter, supports considerably more structure than that, and using it turns a fragile startup script into something closer to a genuinely reusable routine.

Step 1: document the input contract before writing any logic

Start every script with a comment block stating exactly what arguments it expects, in what order, and what each one means. A batch file with no stated contract becomes something only its original author can safely modify - an explicit, documented contract is what makes a routine safe for someone else (including a future version of yourself) to call without re-reading the entire script first.

Step 2: validate before anything destructive runs

IF "%1"=="" GOTO usage
IF NOT EXIST %1 GOTO usage
REM Validate other required arguments before destructive work.
GOTO end
:usage
ECHO Usage: BACKUP source destination
:end

This simple example assumes a DOS 8.3 filename without spaces; validate the exact quoting behavior of the command and FreeCOM version before accepting arbitrary paths. Check required files and arguments before any command that deletes, overwrites, or formats anything. A missing argument can otherwise be interpreted as empty and reach a destructive command.

Step 3: reuse a second batch file with CALL

REM In BACKUP.BAT:
CALL LOGMSG.BAT STARTING_BACKUP
REM Continue in BACKUP.BAT after LOGMSG.BAT returns.

REM In LOGMSG.BAT:
ECHO %1 >> LOGFILE.TXT

FreeDOS’s batch guide documents CALL for invoking another batch file while preserving the caller; without CALL, FreeCOM switches to the second batch and stops processing the first. Do not use Windows cmd.exe label-call idioms such as CALL :label or GOTO :EOF as FreeCOM subroutines: the FreeDOS guide documents GOTO as a jump, not a return mechanism. A separate helper batch file is the documented reusable pattern.

Step 4: branch on a program’s ERRORLEVEL

FreeCOM exposes the last program’s return status as %ERRORLEVEL%; the documented IF ERRORLEVEL n form also tests whether the status is at least n. Check it immediately after the command whose result matters, before another program replaces that status. For example, test IF %ERRORLEVEL%==0 GOTO success and then handle the nonzero path. Batch statements do not provide a general way to assign an arbitrary process exit code, so branch on the program’s actual result rather than claiming to set it yourself.

Step 5: keep environment changes bounded

The FreeDOS batch guide documents ordinary SET variables, but not Windows cmd.exe’s SETLOCAL/ENDLOCAL scoping. Do not rely on those commands in FreeCOM unless the exact installed interpreter documents them. If a helper changes the caller’s environment, explicitly save and restore variables or run it without CALL when you want the caller to stop.

Step 6: quote carefully, and don’t assume uniform parsing

Quote paths containing spaces wherever the specific command you’re calling actually supports quoted arguments - DOS-era utilities differ noticeably in how (or whether) they parse quotes, unlike the more standardized argument handling modern shells provide. Redirect diagnostic detail to a log file, and echo only a concise, human-readable failure summary to the screen, so a user running the script interactively isn’t overwhelmed with debug output during normal operation.

Step 7: test under the real target FreeCOM, not just cmd.exe

Test with empty arguments, a full disk, and a deliberately interrupted command, and do this testing under the actual FreeCOM version shipped with your target system rather than assuming a script that works in Windows’s cmd.exe behaves identically - the two interpreters share batch-file ancestry but have diverged enough that cmd.exe-specific syntax is a common, avoidable source of scripts that fail only once deployed to real FreeDOS.

Why piping behaves differently than you might expect

FreeCOM’s current source implements each non-final pipe stage by creating a temporary file, running that command with redirected output, and opening the file as input for the next stage. Thus the stages are processed sequentially rather than as concurrent streaming processes. This can consume disk space and fail if the temporary file cannot be created or written; leave room on the filesystem used for temporary files and avoid assuming Unix-style streaming behavior.

Keeping the whole routine debuggable as it grows

As a batch workflow accumulates helper batch files invoked via CALL, add an explicit ECHO trace at each helper’s entry point while developing it, then remove or gate those traces once the helper is confirmed working. Keep labels for GOTO branching, not for Windows-style callable subroutines.

Related:

Sources: