Commodore DOS / CBM DOS

Listing the directory of a 1541-formatted disk
Developer	Commodore International
Latest release	10.0
Available in	English
Platforms	MOS 6502 family
License	Proprietary

Commodore DOS, also known asCBM DOS, is thedisk operating system used withCommodore's8-bit computers. Unlike most otherDOSes, which are loaded from disk into the computer's ownRAM and executed there, CBM DOS is executed internally in the drive: the DOS resides inROM chips inside the drive, and is run there by one or more dedicatedMOS 6502 familyCPUs. Thus, data transfer between Commodore 8-bit computers and their disk drives more closely resembles alocal area network connection than typical disk/host transfers.

At least seven distinctly numbered versions of Commodore DOS are known to exist; the following list gives the version numbers and related disk drives. Unless otherwise noted, drives are 5¼-inch format. The "lp" code designates "low-profile" drives. Drives whose model number starts with 15 connect via Commodore's uniqueserial IEEE-488 bus (IEC Bus) serial (TALK/LISTEN) protocols; all others use the parallelIEEE-488.

•   1.0 – found in the2040 and3040 floppy drives
•   2.0 – found in the4040 and3040 floppy drives
•   2.5 – found in the8050 floppy drives
•   2.6 – found in the1540,1541 including the one built into theSX-64,1551,2031 (+"lp"), and4031 floppy drives
•   2.7 – found in the8050,8250 (+"lp"), andSFD-1001 floppy drives
•   3.0 – found in the1570, external1571, and8280 floppy drives (8280: 8-inch), as well as the9060 and9090hard drives
•   3.1 – found in the built-in 1571 drive of C128DCR computers
• 10.0 – found in the1581 (3½-inch) floppy drive

Version 2.6 was by far the most commonly used and widely known DOS version, due to its use in the1541 as part ofC64 systems.

Note: The revisedfirmware for the 1571 which fixed the relative file bug wasalso identified as V3.0. Thus it is not possible to differentiate the two versions using the version number alone.

The 1541 Commodore floppy disk can contain up to 144 files in a flat namespace (nosubdirectories); the directory is stored on reserved track 18, which is located halfway from the hub to the edge of a 35-track single-sided disk. A file name may be up to 16bytes in length and is theoretically unique; by using direct access methods on the directory structure, it is possible to rename a file to that of another—although accessing such files may be difficult or impossible. Files with identical names usually serve no purpose except to inform or visually manage files. One popular trick, used, for example, byThe Final Cartridge III, was to add files named"----------------" of typeDEL< to the directory, and files could then be rearranged around those lines to form groups. Many game developers,warez group members, anddemoscene hackers used some more clever custom directory entries as well.

File names may contain a shifted space character ($A0), and if the directory listing is being viewed from BASIC, the portion of the file name beyond the$A0 character will appear to have been separated from the first part of the file name by a quotation mark, causingBASIC to not consider it to be part of the full file name. This feature can be used to create directory entries such asSAVE "PROGRAM⇧ Shift–space Commodore–DUDE",8,1, which will then appear in the directory listing as, for example,32 "PROGRAM",8,1 PRG.^[1] When the user moves the cursor to the beginning of the line, types the wordLOAD over the file size, and pressesRETURN, BASIC interprets that asLOAD"PROGRAM",8,1..., causing the program to be loaded into memory. Anything after the colon or the secondary address will not be executed, since the computer ignores any command after a LOAD.^[2] Alternatively, the user could press⇧ Shift–RUN/STOP toLOAD andRUN the program automatically.^[3]

A null byte embedded in a file name will interrupt the listing after loading by BASIC. If there are three null bytes, that makes it difficult to list through BASIC. Many machine language programmers would experiment with null bytes in an attempt to make it harder for BASIC programmers to access their code and tamper with it.

In BASIC, the directory can be accessed as a non-executable pseudo-BASIC program withLOAD"$0",8 (orLOAD"$1",8 in the case of a dual drive) followed byLIST. The first line has a line number of 0 or 1 (indicating the drive number), showing in reverse video the name and ID of the disk and a shorthand code for the DOS version with which it was created (codes vary only as far as the DOS versions use incompatible disk formats: "2A" is used by most 5.25-inch DOS versions, "3D" by the 3.5-inch 1581). Lines after this have the size of a file (in disk blocks) as their pseudo "line number", followed by the file name in quotes and the three-letter type code. The last line shows the number of unallocated blocks on the disk (again as a pseudo "line number"), followed by the words "BLOCKS FREE."

On theCommodore 64, enteringLOAD"$",8,1 will flood the screen with garbage instead of loading the directory into BASIC RAM. This is because the drive assigns the directory a load address of$0401 (1025), which is equivalent to the start of BASIC for theCommodore PET, but corresponds to the default screen memory in the C64 (starting with the second character on the first line of the screen).

Viewing the directory with aLOAD"$",8 command overwrites the BASIC program in memory. TheDOS Wedge and various third-party cartridges and extenders such asEpyx Fast Load,Action Replay, andThe Final Cartridge III allow viewing of the disk directory using special commands that load the directory into screen memory without destroying the current BASIC program. Some versions of Commodore BASIC include aDIRECTORY orCATALOG command that performs the same function.

The following file types are supported:

SEQ

Asequential file is a data file that can be linearly read from start to finish.SEQ files are commonly used to store documents or text files created by a word processor or other such editor. A sequential file is analogous to aflat file inLinux orUNIX, in that it has no specialized internal structure. It is not possible to position to any arbitrary location in a sequential file, as there is no analog of thelseek kernel call found inUNIX-like operating systems.

PRG

PRG files normally contain executable program code, although they can also be used for data files. The first two bytes of thePRG are read by thekernal "load file" routine and used to determine the load address (they are stored in alittle endian format).

REL

A relative file is a variation of the sequential file type, in which an indexing mechanism referred to as side-sectors is present to permit record-oriented access. Records may be a maximum of 254 bytes in size and are addressed by a one-based cardinal number, permitting truerandom access to any part of the file.

USR

A user-specified file has an internal structure that is identical to that of a sequential file. Commodore's original purpose for this file type was the facilitation of DOS development, as the file content could be copied into a drive buffer for execution by the drive's microprocessor. Very few programs ever made use of this file type. Some applications that use non-standard low-level disk structures save data in USR format, which came to be considered a sort of "leave me alone, don't try to copy or delete" indication to the user. Most notably,GEOS' "VLIR" files show up asUSR files.

DEL

An undocumented internally used file type similar in structure to a sequential file. Creation of this file type must be accomplished by direct manipulation of the disk directory.

The presence of an asterisk (*) prepended to the file type in a directory listing (for example,*SEQ) indicates that the file was not properly closed after writing. When the drive is commanded to close a file that has been opened for writing, the associated buffer is flushed to the disk and theblock availability map (BAM) is updated to accurately reflect which blocks have been used. If a program crash or other problem (such as the user removing the disk while a file is open) results in an "orphan file", also referred to as a "poison" or "splat" file,buffers are not flushed and the BAM will not accurately reflect disk usage, putting the disk at risk of corruption. A poison file generally cannot be accessed (but can be opened in "modify" mode), and an attempt to use the DOSscratch command to delete the file may causefilesystem corruption, such as crosslinking. The only practical method of removing one of these files is by opening the file in "modify" mode (and fixing it), or by validating the disk (see the DOSvalidate command below), the latter which rebuilds the BAM and removes poison file references from the directory. The infamoussave-with-replace bug could result in creation of splat files.

*DEL is a special type written into the on-disk directory entry of files that have been deleted. Such files are not shown in a normal directory listing, and their data blocks and directory entries will be reused by files that are subsequently created. Some utility programs allow the "un-deletion" of such files if their data blocks and directory entries haven not yet been overwritten by other files.DEL files are commonly used to insert banners or comment sections into a directory listing.

File types with< after them (for example,PRG<) are "locked", and cannot be deleted—they can be opened for reading, however. There is no Commodore DOS command that can explicitly set or clear this status, but many third-party utilities were written to allow this to be done. These utilities generally read the directory using direct-access commands, perform the necessary modifications to the raw data, and then write the changes back to the disk.

Accessing files is primarily an issue for the host computer. The kernal ROM in the computer contains the necessary primitive routines needed to access files, and theBASIC ROM contains a higher level abstraction for file access using BASIC syntax. The components that concern the DOS itself are file name parsing and the secondary address. This section will give an overview of the necessary BASIC commands for the sake of completeness.

Opening a file on a Commodore disk unit entails the processing of a number of parameters that are vaguely analogous to file opening procedures in other environments. Since the DOS is actually running in the drive's controller, the file opening sequence must pass enough information to the drive to assure unambiguous interpretation. A typical statement in BASIC to write to a sequential file would be as follows:

OPEN3,8,4,"0:ADDRESSBOOK,S,W"

The parameters following theOPENverb are as follows:

3

This parameter, thefile number, logically identifies the opened file within thecomputer's operating system and is analogous to afile descriptor inUNIX-like operating systems. It is never sent to the drive and thus is neither known nor used by the drive's own operating system. The file number may be in the range of 1 to 254 inclusive, is assigned by the programmer and must be unique if more than one file is simultaneously opened. Once the file has been opened all program input and output procedures use the file number. Inassembly language programs, this value is often referred to as LA (logical address), the abbreviation coming from themnemonic that refers to the memory location where the file number is stored. File numbers greater than 127 cause the system to write an extra line feed after each carriage return (useful for double spacing a document, as an example.)

8

This parameter, thedevice number, identifies a specificperipheral attached to the computer. Devices 0 through 3 address the keyboard, tape cassette,RS-232 interface, and video display, respectively, all of which are directly controlled by the kernal ROM. Device numbers 4 and higher address devices attached to the peripheral bus, such as printers or disk drives. In the case of a disk drive, the device number refers to the unit's controller, not the drive mechanism(s) within the unit. By convention, the first disk drive unit on a system has device number 8, the second drive, if present, 9, etc., up to a maximum number of 15 (when eight disk drives are attached). The device number scheme was derived from the IEEE-488 (or general purpose interfaceGPIB) bus that was used with the Commodore PET/CBM models. In assembly language programs, this value is often referred to as FA or PA (physical address), again from the mnemonic for the memory location where the device number is stored.

4

This parameter, thesecondary address, which may range from 0 to 15 inclusive, refers to a specific communication channel established with the device's controller and is passed to the device when it is commanded to "talk" or "listen" on the peripheral bus. As with the file number, the secondary address is determined by the programmer and must be unique for the device in question. The range 0 to 14 inclusive is used for passing data to or from the device, whereas 15, referred to as the "command channel", is used to issue commands to the device's controller (such as to rename a disk file), if the device is able to support such an operation. In disk drives, secondary addresses 0 to 14 inclusive are mapped to buffers within the controller, hence establishing communication with a specific file on a specific disk; since as mentioned above the drive does not know about thefile number, it can only use thesecondary address to make a difference between several files that are open at the same time. On the other hand, the host operating system is agnostic about the secondary address; it is transmitted to the drive on every access to the file, but not otherwise used by the host. In assembly language programs, this value is often referred to as SA (secondary address).

COMMAND STRING

The"0:ADDRESSBOOK,S,W" parameter is officially referred to in Commodore documentation as thecommand string and is interpreted by the controller of the device being accessed. In the case of a disk drive unit, the formal command string structure consists of the drive mechanism number (0:, not to be confused with the device number), filename (ADDRESSBOOK), file type (S, sequential in this example) and access mode (W, opened for writing in this example). In practice, some of these parameters may be omitted. Minimally, only the filename is required if the file is to be opened for reading.

The drive number identifies a drive mechanism attached to a disk unit's controller and is analogous to alogical unit number in aSCSI controller that is capable of controlling multiple mechanisms (e.g., theOMTISASI controllers that were developed to work withST-412/ST-506 hard drives in the 1980s). In floppy disk units, the first mechanism is drive 0: and the second is 1:. It is fairly common practice to omit the drive number when communicating with a single drive floppy unit, as 0: is the default in such units, but since omitting the number can trigger a few obscure bugs in the DOS it is not a recommended practice (a colon alone is equivalent to 0: and is enough to avoid those bugs). An exception to this convention is with theLt. Kernal hard disk subsystem, in which the drive number refers to "logical units" (virtual drives created on a single physical drive), which made syntax such as 4: or 10: necessary if a file to be opened was not on logical unit zero (equivalent to drive mechanism zero in a dual floppy unit).

Files can also be loaded and saved to withLOAD andSAVE commands. File name specifiers can also be used here, for example,SAVE"FILE",8 saves the BASIC program to aPRG (program) file andSAVE"0:FILE,SEQ,WRITE",8,1 saves the BASIC program to a sequential file. If the secondary address isn't specified or is specified as 0 (e.g.LOAD"FILE",8), the file is saved/loaded from the BASIC memory area (which, on the C64, starts by default at$0801). If the secondary address is specified as a non-zero value (e.g.LOAD"FILE",8,1), the program is loaded starting from the address specified by the file itself (the PRG header, which is the first two bytes of the file)—this form of command is more common when loading machine code programs.

Load relocation was first introduced on theVIC-20 because this machine could start BASIC RAM in several different locations, depending on the memory expansion that was installed. The olderCommodore PET series did not support relocation, soLOAD"FILE",8 andLOAD"FILE",8,1 would have the same effect: the file would be loaded into the same memory region from which it was saved. Load relocation happens in the host, being an exception to what is said above about the secondary address being used only device-internally. Since the PET cannot relocate files, BASIC programs written on later Commodore machines must be modified by using a sector editor to change the header bytes. It is also possible to use the PET's built-inmachine language monitor to change the link address for the BASIC program after loading it.

The commandLOAD"*",8,1 will load the first program on the disk starting from the file-specified memory location. This is one of the most popular load commands of the platforms, the method to start majority of commercial software, for example. Of note is the fact that thewildcard expansion will only pick the first catalog name when no other file on that disk has been accessed before; the name of the last-used file is kept in memory, and subsequentLOAD"*",8,1 commands will load that file rather than the first. (However,LOAD"0:*",8,1 orLOAD":*",8,1 will always load the first file on the disk.)

The directories of disks in two-drive units are accessed asLOAD"$0",8 andLOAD"$1",8."0:$" and"1:$" do not access the directory but actual files on one drive or the other that just happen to be named"$". Partial directories can be loaded by adding a colon and a template: for example,LOAD"$0:K*=P",8 would load a partial directory that shows only the files whose name starts with the letter K and which are of type PRG; all such partial directories still contain the initial disk name line and the final "BLOCKS FREE" line.

Commodore DOS also offers a "Save-with-Replace" command, which allows a file to be saved over an existing file without the need to firstSCRATCH the existing file. This was done by prepending an@ symbol to the file name during theOPEN orSAVE operation - for instance,SAVE"@MY PROGRAM",8. For years rumors spread, beginning with the 4040 drive, of a bug in the command's implementation. At first, this was denied by some commentators. Prizes were offered to prove the existence of the bug.^[4] By early 1985Compute! magazine advised readers to avoid using the command.^[5] That year various authors independently published articles^[4][6][7][8] proving that the Save-with-Replace bug was real and including methods by which it could be triggered.

Affected devices included the single-drive 1541 and dual-drive 4040; the 8050 and 8250 did not exhibit the issue.^[4] Some commentators suggested the bug could be avoided by always explicitly specifying the0: drive number when saving,^[6] though it was later shown thatany disk operations without a drive number were sufficient to lead to the bug.^[9] The bug stemmed from the fact that the affected DOS implementations were modified versions of the DOS contained in earlier Commodore PET dual drives such as the 8050. This created a "phantom drive1:" on single-drive systems, resulting in the allocation of an unnecessary buffer under some conditions. Since the Save-with-Replace command used all five drive buffers, and because the method by which the "phantom" buffer was allocated did not meet specifications, this could result in scrambled data being written to the disk.

In September 1986, Philip A. Slaymaker published an article^[10] describing in great detail the cause of the bug and providingpatches to the 1541 drive ROMs; readers with anEPROM burner could produce their own patched ROMs which could be swapped into the drive. Commodore was made aware of Slaymaker's findings, and while they never issued an official update for the original 1541's ROMs, they did fix the bug in Revision 5 of the 1571 ROMs, and also in the ROMs for the 1541-c and 1541-II drives. Although not supported by Commodore, it is known that the 1541-II firmware (but not that of the 1541-c) can also be used in an original 1541 drive by using EPROMs, which will fix the bug for that drive as well.

As previously noted, the Commodore DOS itself is accessed via the "command channel", using syntax like that used to access files. Issuing commands to the DOS and retrieving status and error messages generated in response to commands is accomplished by opening a file to the device using 15 as the secondary address, for example:

OPEN1,8,15

To retrieve and display the device status, one could code:

OPEN1,8,15:INPUT#1,E,E$,T,S:PRINTE,E$,T,S:CLOSE1

In the above example,E will hold the error number (if any; it will be zero if no error exists),E$ will be a terse text description of the error,T will represent the disk track where the error occurred, andS will be the sector on trackT to which the error refers. If no error exists, the equivalent of00,OK,00,00 will be returned in the four variables. Note thatINPUT# is a run mode only verb. Also, in programs that issue many disk commands it is customary to open a file to the device's command channel at the start of the program and not close it until the program has finished.

Commodore BASIC versions 4.0 and later provide a pseudo-variable referred to asDS$ that may be used to retrieve drive status in lieu of the above code. This reserved variable is not available on earlier versions of BASIC, so the command channel must be manually read as demonstrated above. Note that immediately after power-on or reset, the DOS revision will be returned. For example, a 1541 will return73,CBM DOS V2.6 1541,00,00. Error code 73 is common to all drive models and may be used to determine if the drive has been reset to its power-on state.

There are also a command for seeking in RELative type files (RECORD#), several block-level direct-access commands (BLOCK-READ,BLOCK-WRITE,BUFFER-POINTER), block management (BLOCK-ALLOCATE,BLOCK-FREE), drive memory manipulation and execution of program code on the drive's processor (MEMORY-WRITE,MEMORY-READ,MEMORY-EXECUTE,BLOCK-EXECUTE) and user-definable functions (USER and& commands). Some of the theoretically user-definable functions were rededicated for accessing new functionality in DOS versions after 1.0.

Notes

• Commodore 64 software
• Disk operating systems
• VIC-20 software

• Articles with short description
• Short description is different from Wikidata
• Articles with Finnish-language sources (fi)