Skip to content
FreeDOSDeep Dive Published Updated 6 min readViews unavailable

DOS Network Printer Setup Strings: INT 21h AH=5Eh Without the Assign-List Confusion

Separate DOS network-printer initialization strings from drive mapping, printer BIOS calls, and the redirector-specific behavior that actually consumes them.

DOS printer setup is not one interface. BIOS INT 17h sends characters to a local printer service. A network redirector can map a local printer name to a remote printer. A separate DOS network function can associate a setup string with an entry that already represents a network printer. Confusing those layers can produce a program that writes bytes to a local port while an operator expects the network spooler to apply a printer mode.

This article is narrowly about the historical INT 21h function family AH=5Eh, subfunctions AL=02h and AL=03h: set and get a network printer setup string. It is not an article about creating or removing printer mappings with AH=5Fh, and it is not a promise that a plain FreeDOS installation contains a Microsoft Networks-compatible redirector.

What the 5Eh printer functions are for

The MS-DOS Version 4.0 Programmer’s Reference describes 5Eh/02h as defining a string of control bytes that DOS adds to the beginning of each file sent to the network printer selected by an assign-list index. The companion 5Eh/03h function retrieves the stored printer setup string. The reference gives BX as the printer’s assign-list index; for set, it lists a length in CX and a DS:SI pointer; for get, it provides an ES:DI buffer of 64 bytes and returns the string length in CX.

The setup string is not a printer-language abstraction. It is an opaque byte sequence for a specific device or spool path. A control byte that switches a compatible printer into one mode can be meaningless or harmful on another device. The old reference’s example is a one-byte expanded-print control for a particular class of printer; that is a historical illustration, not a safe universal prologue. Do not paste that byte into a live print pipeline without confirming the exact printer model, language, and reset behavior.

The reference also contains an important source inconsistency: its 5Eh/02h call table lists the input pointer in DS:SI, but its example macro loads DX and does not load SI. Because that macro cannot be reconciled with the table as printed, this article deliberately does not present a supposedly portable MASM sequence for setting the string. Verify the target DOS and redirector’s published ABI, headers, or known-good implementation before assembling a mutating call. In particular, do not silently substitute a familiar DS:DX convention because other DOS functions use it.

Keep the lookup function separate from the setup function

AH=5Eh, AL=02h does not create a network printer mapping. AH=5Fh is the assign-list family; its query subfunction can enumerate entries and identify which one represents a printer. The 5Eh call then uses the relevant index to operate on printer setup data. These are related stages but different contracts: 5Fh describes the redirector’s mapping table, while 5Eh changes or reads a setting associated with an existing network-printer entry.

An index is a lookup value in a running redirector’s table, not a stable printer identity to hard-code forever. The DOS 4 reference explains that the assign list can change between calls. If software enumerates the table and later uses an index, a mapping change in between can make that index identify a different target. Query immediately before use, verify the local and remote names and device type, and stop if the expected printer is absent or ambiguous.

AL=03h is the safer diagnostic starting point because it reads the current setup into a caller-provided 64-byte buffer. Check the carry flag before trusting the result and use the returned CX length to bound inspection; do not assume the bytes are a NUL-terminated C string. The reference documents error code 1 when the function is invalid or Microsoft Networks is not running. Preserve the original bytes and length if you are testing an application in an isolated environment.

A bounded read-before-change workflow

Before a mutating test, identify the DOS version, network redirector product and version, whether its file-sharing/network component is loaded, and the exact local printer mapping. Use a disposable network printer or an emulator with a test redirector rather than an active office printer. The following is an operational checklist, not executable assembly; it avoids the conflicting pointer example in the DOS 4 manual.

  1. Enumerate the redirector’s assign list with that redirector’s documented query interface. Confirm the selected index resolves to a printer, and record both the local name and remote target.
  2. Use 5Eh/03h with the verified index and a 64-byte ES:DI buffer. Check carry, record AX on failure, and preserve only the returned CX bytes on success.
  3. Confirm the printer language and test-control sequence with the model’s manual. Start with a reversible mode change that is known to reset at end of job; do not experiment with persistent network settings or unknown escape sequences.
  4. If you must test 5Eh/02h, confirm the set-string pointer convention with the exact target implementation before assembling it. Send a harmless test document to the disposable queue, then retrieve the string again and inspect the spool output in that isolated environment.
  5. Restore the saved original setup bytes only after verifying the same printer mapping still occupies the index. If the redirector’s mapping changed, stop and re-enumerate rather than applying saved state to a different printer.

This workflow separates three results that are often collapsed into “printing works”: the DOS call was accepted, the redirector associated bytes with the intended printer entry, and the destination device interpreted the sequence as intended. A successful carry-flag check proves neither the printer’s language nor the final page’s appearance.

What FreeDOS does and does not promise

In the pinned FreeDOS kernel source at commit d6791add2043c9d7b584d840a8ffaf8829fd2bdc, the INT 21h handler directly handles the 5Eh machine-name subfunctions AL=00h and AL=01h. Other 5Eh subfunctions are passed to the network redirector multiplexer using the REM_PRINTSET request. That source is useful evidence for the boundary: the kernel routes the request outward; it does not itself supply a network print service or interpret the printer control bytes.

Consequently, packet-driver networking or a successful TCP connection on a FreeDOS machine does not demonstrate that 5Eh/02h and 5Eh/03h are implemented. A compatible redirector must actually be installed, loaded, and able to service the function. Check its own documentation and test the actual DOS build. The pinned source describes that repository revision only; other kernels or redirector versions may differ.

Distinguish setup data from bytes sent to the device

The setup API stores a prefix associated with a network-printer entry. It is not a general means of setting the printer’s permanent configuration, nor does the call itself prove which jobs receive the prefix under every redirector. Confirm the product’s behavior when multiple applications share a queue, when a job is interrupted, and when the connection is lost. A partially sent document may leave a printer in a changed mode even if DOS reports a later error.

For local hardware, use the printer’s documented port or device API and the BIOS status/reporting contract; for a network mapping, use the installed redirector’s interface; for application-specific page description, use the printer language or driver the remote endpoint supports. If a program needs fonts, duplex, paper, or a tray selection, a raw setup prefix is only appropriate when the whole path has been tested to preserve and reset that state. Keep printer operations out of a production queue until those conditions are known.

Related:

Sources:

Comments