FreeDOS SWSUBST: Mapping Paths and Drive Letters Through the CDS Table

DOS applications often treat a drive letter as part of their configuration. Installers store D:\APP, batch files change to a work drive, and old programs may accept only a short path even when the real directory is buried several levels deep. FreeDOS provides SWSUBST to change that view without copying the directory.

SWSUBST combines the roles traditionally served by SUBST and JOIN, with additional inspection and manipulation options. It works with DOS’s Current Directory Structure, or CDS, table. That makes a mapping visible to DOS path resolution, but it also means changing one entry can invalidate assumptions already cached by running programs.

SUBST gives a directory its own drive letter

A substitution maps a drive letter to a directory on another drive. The FreeDOS help gives the direct form:

SWSUBST B: C:\BLAH\HUMPF

Afterward, a program opening B:\DATA.DAT reaches the corresponding path beneath C:\BLAH\HUMPF. No second copy of the data exists. Free-space reporting, filesystem limits, and media failure still belong to the underlying drive.

Run SWSUBST without a command to display the CDS table and confirm what DOS currently resolves. Do not infer success only because the command printed no obvious error, especially inside an installer whose output may be redirected.

JOIN redirects a drive into a directory

JOIN expresses the opposite-looking relationship: a drive is joined into a path. SWSUBST supports it with /J, while /U performs substitution explicitly. The unified tool can also break a relationship and create a different one without requiring a separate executable.

This flexibility is useful for compatibility, but it does not turn DOS into a mount-namespace system. The global CDS state is shared by programs in the current DOS environment. A change made for one application can surprise another application that reads the same drive entry.

Write down the original table before editing it. A launcher can establish a temporary mapping, start one program, then restore the previous relationship, but only if no resident or background component continues to depend on the temporary letter.

SWSUBST can create missing path components

FreeDOS extends classic behavior with /K, which creates paths named by the command, and documents that its DOS-compatible SUBST and JOIN forms may create a complete missing path. /T changes checking behavior for substitution. That convenience can hide a typo by creating a directory the operator never intended.

For repeatable automation, create and verify the destination separately, then map it without relying on implicit creation. Confirm that the underlying drive is the expected media and that the target contains an application-specific marker before redirecting a well-known letter.

Path spelling matters. DOS accepts forward and backslashes in various contexts, but legacy applications may not. Store normalized absolute paths in batch variables and quote them when the command interpreter and target tool support spaces.

Drive swapping is a logical operation

The /S command swaps two drive entries. /N can swap unit numbers for drives served by the same device driver, historically useful for floppy arrangements. These operations alter the mapping DOS presents; they do not move disk contents.

Programs can cache a current directory, Disk Transfer Area state, or device information. Swapping letters while such a program remains active may make later opens reach different media. Close applications, change to a neutral drive and root directory, perform the swap, then verify both sides before launching consumers.

Never use a swap as a recovery guess on writable media. Record volume labels or known marker-file contents first so A: and B: are not confused merely because both exist.

The CDS dump is the diagnostic source of truth

SWSUBST includes detailed display options. /# reports JOIN statistics, /_ dumps attributes, /F renders non-printable characters in hexadecimal, and /A displays the table after a command. /! can initialize a JOIN flag when it differs from detected state.

These options exist because CDS state can be inconsistent or affected by another redirector. Inspect before repairing. Network redirectors may own drive entries with semantics different from a local substitution, and SWSUBST has options to query or set physical, network, join, subst, and hidden flags.

Directly forcing flags is an expert recovery operation. A flag that makes a table look plausible cannot create the underlying redirector state. Capture the dump, identify which driver owns the letter, and prefer that driver’s official disconnect command.

ERRORLEVEL has drive-oriented semantics

The FreeDOS documentation states that successful drive queries can return the ASCII value of the drive letter, from 65 for A through 90 for Z. Zero can mean no such drive, while other values signal errors. That differs from the widespread batch convention that zero always means success.

Use the documented meaning for the exact SWSUBST command being run. In a batch script, IF ERRORLEVEL n tests greater-than-or-equal in descending comparisons, which can make an ASCII drive result especially easy to misread. Prefer a follow-up table query or explicit output verification when a mapping affects valuable data.

Do not carry one error-code assumption from SWSUBST to another FreeDOS utility. DOS has no universal structured status model beyond the byte returned by each program.

LASTDRIVE and environment capacity matter

DOS allocates drive-related structures according to its configuration. A desired letter beyond LASTDRIVE cannot be made usable by changing the CDS table alone. Confirm CONFIG.SYS and reboot requirements before promising an installer can create an arbitrary high letter.

Network clients, CD-ROM extensions, RAM disks, and block drivers may allocate letters during boot. Choose a letter after those drivers initialize, not from a static guess made on another machine. A startup batch should check for an existing mapping and ensure it points to the expected directory before reusing it.

Nested substitutions make troubleshooting hard. Map directly to the canonical underlying path rather than mapping a letter to a path that itself depends on another substituted letter.

Restore state as carefully as you create it

/D removes or initializes a mapped drive entry according to the supported syntax. Before removal, change away from that drive, close files beneath it, and stop TSRs or applications that may reopen those paths. Removing a mapping does not flush an application’s private buffers.

A safe launcher captures the initial CDS display, validates the target, establishes one mapping, verifies a known file through both names, runs the application, and restores the prior state only after the child exits. It also leaves a diagnostic log if restoration fails.

SWSUBST is a compatibility tool with system-wide effects. It can make a rigid DOS program see exactly the drive layout it expects, but professional use depends on inspecting the CDS table, respecting other redirectors, interpreting status correctly, and treating every mapping change as shared mutable state.

Related:

Sources: