DOS APPEND

For a long time, I couldn’t quite grasp what the DOS APPEND command could possibly be good for. Until I came across a situation which APPEND was made for.

When I worked on organizing and building the DOS 2.11 source code, I tried to place the source files in a tree structure similar to that used by DOS 3.x (this is known from DOS 3.x OAKs):

C:.
└───src
    ├───bios
    ├───cmd
    │   ├───chkdsk
    │   ├───command
    │   ├───debug
    │   ├───diskcopy
    │   ├───edlin
    │   ├───exe2bin
    │   ├───fc
    │   ├───find
    │   ├───format
    │   ├───more
    │   ├───print
    │   ├───recover
    │   ├───sort
    │   └───sys
    ├───dos
    ├───inc
    └───msdos

The inc subdirectory unsurprisingly contains shared include files such as DOSSYM.ASM, which are included just about from everywhere. No problem, right?

Except… to get output that most closely matches existing DOS 2.x binaries, it is necessary to use an old version of MASM (version 1.25 seems to do the trick). But MASM 1.25 is designed to run on top of DOS 1.x, and knows nothing whatsoever about directories.

It is possible that back in the day, DOS 2.x was built from a single huge directory on a hard disk. In fact it is known that DOS 2.0 could not be built on PCs at all, and was built on DEC mainframes. Yet DOS 2.11 was also clearly modified such that it could be build on PCs using Microsoft’s development tools.

However it was done back in 1983, lumping 150+ assembler source files into a single directory, and then adding hundreds of object and executable files, did not sound at all appealing. Cloning DOSSYM.ASM to every directory where it was needed seemed even worse.

That’s when I somehow remembered that APPEND exists, and realized that it’s the perfect solution to the problem. Before building, one can run

APPEND ..\..\INC;..\INC

and the inc directory becomes accessible from all of its sibling subdirectories and from subdirectories one level deeper. It would have been possible to use an absolute path as well, but this way the build batch file does not need to know where it lives.

With APPEND in place, the old MASM 1.25 which uses FCB I/O will find the centrally located include files, and the source code can be organized into a neat hierarchical structure that’s far easier to work with than one giant blob.

What is APPEND?

APPEND is a “DOS extension”, in fact it is a TSR which intercepts INT 21h and adds special handling for several subfunctions. These are primarily:

• 0Fh FCB File Open
• 3Dh Handle File Open
• 23h Get File Size

If these subfunctions fail to find a file in the current directory, APPEND will retry them using the list of paths it manages.

When building DOS 2.11, MASM 1.25 will try to open DOSSYM.ASM using INT 21h/0Fh (FCB File Open). Because the file does not exist in the current directory, the initial attempt will fail. APPEND will then try opening ..\INC\DOSSYM.ASM and, if that is unsuccessful, also ..\..\INC\DOSSYM.ASM. Old MASM is thus magically upgraded to handle multiple directories, without actually knowing anything about them.

The working principle of APPEND is not complicated. It primarily serves as a bridge between old DOS applications which have no or poor support for directories, and users who really, really want to organize files and programs in multiple directories and possibly across multiple drive letters. Of course the actual APPEND implementation is anything but straightforward.

APPEND Evolution and Implementation

The first DOS version which came with APPEND was DOS 3.3 (1987), not coincidentally the first DOS version developed by IBM.

But APPEND is older than that—it first appeared in the IBM PC Network Program 1.0 in 1985. It is hard to speculate why it was shipped with the PC Network Program (later the PC LAN Program) because APPEND does not really have anything to do with networking. It is plausible that it was especially useful with networking, when users were motivated to store applications on a central network server and data files on their own machines. And that’s a problem for applications which cannot handle directories well.

Now that we can see the source code for APPEND, some things are clearer. The original PC Network Program version of APPEND was written by someone with initials G. G. A., and in 1986 it was adapted for shipping with DOS by B. A. F., no doubt Barry A. Feigenbaum (best known for developing the SMB protocol).

APPEND by default manages the path list in its own internal storage. But it also has a /E option which instead causes APPEND to look for an eponymous environment variable. This mechanism has a disadvantage in that the APPEND= variable needs space in every newly created environment. On the other hand, it also allows different DOS processes to have different APPEND paths.

It should be noted that OS/2 implements a mechanism analogous to APPEND /E through the DPATH environment variable. Only on OS/2 it’s built in, with no need to load TSRs.

Another APPEND addition was the /X switch, which causes APPEND to hook further DOS subfunctions, most notably Find First and Exec. This effectively allows APPEND to supplant the PATH environment variable.

APPEND is listed in the PC DOS 3.3 reference as both internal and external command. At first glance that doesn’t make any sense, but it’s actually true.

The first time APPEND is run, it is an external command. But when it installs itself as a TSR, it hooks INT 2Fh/AEh. COMMAND.COM, in turn, calls INT 2Fh/AEh when it is asked to execute a command that COMMAND.COM does not know about. This mechanism allows APPEND to function as an internal command once it is installed.

That is, the first time APPEND is run, it must be loaded and executed from disk. But any subsequent attempt to run APPEND through COMMAND.COM, either from the command line or a batch file, will take a shortcut directly to the already installed TSR, effectively turning APPEND into an internal command. The INT 2Fh/AEh interface between COMMAND.COM and a TSR was added in DOS 3.3, quite likely for the benefit of APPEND.

APPEND also has its own programming interface, accessed through INT 2Fh/B7h. This allows programs to control APPEND behavior and query the current APPEND path. How widely this is used isn’t entirely clear.

Summary

APPEND is one of the things that are completely irrelevant 99.99% of the time… yet can be extremely useful when the need arises. It is a TSR which allows applications to find files in a directory other than the current one.

The first appearance in APPEND was in the IBM PC Network Program (1985), but since version 3.3 (1987) it was integrated into DOS, with an interesting link to COMMAND.COM which allows APPEND to become an internal command once it is installed.