FreeDOS APPEND: Data-File Search Paths Without PATH Confusion

FreeDOS APPEND changes how compatible programs locate data files. It lets a program that asks DOS to open a relative filename search one or more additional directories as though those files were available in the current directory. That can preserve older application layouts, but it also changes a basic assumption: the program may open a file that is not beside the executable, not in the current directory, and not named by the executable search path.

APPEND is not the same as PATH. PATH helps the command interpreter locate executable commands. APPEND affects file-open requests made by applications; /X:ON additionally extends the behavior to file searches and command execution according to the FreeDOS help. This distinction matters in support work. A program may launch correctly while silently opening an unexpected configuration or data file from an appended directory.

Model lookup as an ordered search policy

Begin by separating three locations: the current directory, the program directory, and APPEND’s list. An application can use an explicit absolute path, a drive-relative path, or a bare filename. APPEND is intended for file requests that can be resolved through its appended directories, not as a universal filesystem overlay. Its documented /PATH:ON default also permits search for requests that already contain a path; /PATH:OFF disables that extension. Do not assume every program uses the same DOS open API or follows every compatibility behavior.

The documented syntax is:

APPEND [[drive]path[;...]] [/X[:ON|:OFF]] [/PATH:ON|/PATH:OFF] [/E]
APPEND ;
APPEND

With no arguments, the command displays the current appended directories. APPEND ; clears the list. The list is process-wide DOS environment state maintained by a resident command, not a per-application setting. A typo, stale removable-drive path, or unexpected boot-script invocation can therefore affect multiple later programs.

Install it once, then call the resident command

FreeDOS Help documents APPEND as becoming an internal resident command on its first execution. Subsequent invocations must use the command name without the executable’s file path and extension; trying to load the executable again can detect the already-resident copy and fail. A practical setup is:

C:\FREEDOS\BIN\APPEND C:\APPDATA
APPEND D:\SHARED
APPEND

The initial command loads the utility and establishes the first directory. Later commands update the resident instance. Check the displayed list after each change and verify that the referenced drive exists in the runtime environment. Do not copy this example blindly into AUTOEXEC.BAT: confirm the package path and boot sequence on the target installation first.

/E stores the directory list in an environment variable, but FreeDOS documentation imposes two constraints: it can be used only on the first invocation, and that same command line cannot include the paths to append. Do not combine APPEND C:\APPDATA /E on the assumption that it both initializes the environment-backed list and adds the directory. If a deployment requires /E, consult the installed APPEND /? and the matching Help version, initialize it according to that syntax, then add paths in a separate valid invocation. This mode consumes environment space, so a crowded DOS environment is another operational limit.

The command is resident and consumes conventional memory according to its help page. FreeDOS documents that it can be loaded high with LH where upper-memory support is configured, but that is a memory-placement choice, not a requirement for correct lookup. Measure the memory map before adding another resident component to a constrained boot configuration.

Choose `/X` deliberately

The default is /X:OFF: APPEND applies to open-file requests. /X:ON extends it to searches and command execution. The distinction is important because a failed search and a successful open are different events. If an application enumerates candidate files before opening one, enabling /X can alter which names it sees. If the executable lookup behavior itself is changing, /X:ON may make a command run from an appended location that was not intended to contain programs.

Start with the least expansive behavior that satisfies the application. Reproduce the exact failing open in a disposable directory, use a deliberately unique filename, and check which file content the application consumes. Then enable /X:ON only if the documented operation requires search or command execution semantics. Keep the APPEND list narrow and ordered; broad roots such as C:\ make provenance difficult and can select stale duplicate filenames.

The /PATH switch controls requests that already include a path. Because /PATH:ON is the documented default, a program’s partially qualified request can be affected even when an operator expected APPEND to apply only to bare names. Test the request form used by the application rather than inferring behavior from its user interface. If a program logs only the basename, that log is not sufficient evidence of which physical file was opened.

Diagnose without turning a search path into a mystery

Record the command interpreter, the APPEND binary and version, the exact invocation order, current drive and directory, and the displayed list. Then build two controlled fixtures with the same filename but different sentinel contents: one in the current directory and one in an appended directory. Ask the target program to read the file and confirm which sentinel it reports. Repeat with an explicit path and with /X:OFF and /X:ON as appropriate. Do this on a copy, not against a production data directory.

When lookup surprises you, first run bare APPEND to inspect state. Next check the program’s requested path form and whether /PATH or /X is active. Confirm drive-relative semantics separately: D:FILE.DAT is not equivalent to D:\FILE.DAT. APPEND cannot correct a wrong current directory, a missing volume, an 8.3 alias mismatch, or an application that bypasses DOS file APIs.

FreeDOS Help explicitly warns not to use APPEND with Windows or 32-bit extenders. Treat that warning as a compatibility boundary, not a performance suggestion. Such environments may implement file lookup through other layers that APPEND does not safely govern. Disable or remove APPEND before entering those environments, and test under the actual runtime rather than extrapolating from a real-mode DOS prompt.

Keep application data provenance visible

APPEND is an ambient dependency: a call such as OPEN("SETTINGS.DAT") can resolve differently without any change to the application binary. That complicates incident analysis. A repair technician who copies a newer data file into the current directory may not change what the application reads if an earlier appended directory wins. Conversely, adding a path for one program can make a different program pick up an identically named file.

For important workflows, place a sentinel record or version marker in each candidate data file and use an application diagnostic that reports the selected path when available. If the application cannot reveal its resolved path, temporarily remove duplicate names from the test copy and repeat the operation. Do not rename or move live data merely to make the search “obvious”; preserve a backup first. Capture the displayed APPEND list and the current drive/directory in the support record.

Avoid treating APPEND as a substitute for an application-specific configuration option. An explicit working directory or data-directory argument is easier to reason about because it makes the dependency visible at process launch. If the application is launched from a batch menu, set its directory immediately before execution and restore the prior location afterward where possible. Verify drive-relative path behavior separately; APPEND cannot make D:FILE.DAT mean a fully rooted D:\FILE.DAT.

Also account for removable-media timing. A configured path on a disk that is absent at startup may fail later or resolve after a different disk is assigned that drive letter. If a program expects removable data, check the media identity and volume label before launching it; a drive letter alone is not a stable identity. Keep APPEND entries out of generic system-wide startup unless every command and program on the machine is intended to inherit them.

Operational acceptance checks

Before shipping a configuration, prove four outcomes on a disposable copy: a file in the current directory opens as expected; a file found only in the appended directory opens only when intended; /X changes search behavior only when enabled; and APPEND ; removes the configured list. Test application startup after a cold boot so the resident state is not inherited from an interactive experiment. Inspect every boot-script line that can execute APPEND, including menu branches.

Finally, decide whether the application genuinely needs APPEND. If it accepts an explicit data directory or a configuration file with an absolute path, that is often easier to audit. APPEND remains useful for legacy software with fixed relative file-open behavior, but its convenience is purchased by ambient lookup state. Treat that state like a dependency: document it, minimize it, and remove it when the application no longer needs it.

Related:

Sources: