Editing Commodore DOS (section)

===File access===
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 the [[Commodore BASIC|BASIC 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:

:{{code|lang=cbmbas|OPEN 3,8,4,"0:ADDRESSBOOK,S,W"}}

The parameters following the <code>OPEN</code> [[verb]] are as follows:

;3
:This parameter, the ''file number'', logically identifies the opened file within the ''computer's'' operating system and is analogous to a [[file descriptor]] in [[UNIX-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. In [[assembly language]] programs, this value is often referred to as LA (logical address), the abbreviation coming from the [[mnemonic]] 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, the ''device number'', identifies a specific [[peripheral]] 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 interface [[GPIB]]) 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, the ''secondary 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 the ''file number'', it can only use the ''secondary 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 <code>"0:ADDRESSBOOK,S,W"</code> parameter is officially referred to in Commodore documentation as the ''command 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 (<code>0:</code>, not to be confused with the device number), filename (<code>ADDRESSBOOK</code>), file type (<code>S</code>, sequential in this example) and access mode (<code>W</code>, 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 a [[logical unit number]] in a [[SCSI]] controller that is capable of controlling multiple mechanisms (e.g., the [[OMTI]] [[SCSI|SASI]] controllers that were developed to work with [[ST-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 the [[Lt. Kernal]] hard disk subsystem, in which the drive number refers to "logical units" ([[Vdisk|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 with <code>LOAD</code> and <code>SAVE</code> commands. File name specifiers can also be used here, for example, {{code|lang=cbmbas|SAVE "FILE",8}} saves the BASIC program to a <code>PRG</code> (program) file and {{code|lang=cbmbas|SAVE "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. {{code|lang=cbmbas|LOAD "FILE",8}}), the file is saved/loaded from the BASIC memory area (which, on the C64, starts by default at [[Hexadecimal|$]]0801). If the secondary address is specified as a non-zero value (e.g. {{code|lang=cbmbas|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)&mdash;this form of command is more common when loading machine code programs.

Load relocation was first introduced on the [[VIC-20]] because this machine could start BASIC RAM in several different locations, depending on the memory expansion that was installed. The older [[Commodore PET]] series did not support relocation, so {{code|lang=cbmbas|LOAD "FILE",8}} and {{code|lang=cbmbas|LOAD "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-in [[machine language monitor]] to change the link address for the BASIC program after loading it.

The command {{code|lang=cbmbas|LOAD "*",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 the [[wildcard character|wildcard]] 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 subsequent {{code|lang=cbmbas|LOAD "*",8,1}} commands will load that file rather than the first. (However, {{code|lang=cbmbas|LOAD "0:*",8,1}} or {{code|lang=cbmbas|LOAD ":*",8,1}} will always load the first file on the disk.)

The directories of disks in two-drive units are accessed as {{code|lang=cbmbas|LOAD "$0", 8}} and {{code|lang=cbmbas|LOAD "$1", 8}}. <code>"0:$"</code> and <code>"1:$"</code> do not access the directory but actual files on one drive or the other that just happen to be named <code>"$"</code>.  Partial directories can be loaded by adding a colon and a template: for example, {{code|lang=cbmbas|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.