TRSDOS

TRSDOS (which stands for the Tandy Radio Shack Disk Operating System) is the operating system for the Tandy TRS-80 line of eight-bit Zilog Z80 microcomputers that were sold through Radio Shack from 1977 through 1991. Tandy's manuals recommended that it be pronounced triss-doss. TRSDOS should not be confused with Tandy DOS, a version of MS-DOS licensed from Microsoft for Tandy's x86 line of personal computers (PCs).

With the original TRS-80 Model I of 1977, TRSDOS was primarily a way of extending the MBASIC (BASIC in ROM) with additional I/O (input/output) commands that worked with disk files rather than the cassette tapes that were used by non-disk Model I systems. Later disk-equipped Model III computers used a completely different version of TRSDOS by Radio Shack which culminated in 1981 with TRSDOS Version 1.3. From 1983 disk-equipped TRS-80 Model 4 computers used TRSDOS Version 6, which was a development of Model III LDOS by Logical Systems, Inc. This last was updated in 1987 and released as LS-DOS 6.3.

Completely unrelated was a version of TRSDOS by Radio Shack for its TRS-80 Model II professional computer from 1979, also based on the Z80 and equipped with 8-inch disk drives. The later machines in this line, the Models 12, 16 and 6000, used the Z80 as an alternate CPU to its main Motorola 68000 chip and could run this version of TRSDOS for backwards compatibility with older Z80 applications software.

History
Tandy Corporation's TRS-80 microcomputer did not have a disk drive or disk operating system at release. The first version of TRSDOS, by Randy Cook, was so buggy that others wrote alternatives, including NewDOS and LDOS. After disputes with Cook over ownership of the source code, Tandy hired Logical Systems, LDOS's developer, to continue TRSDOS development. TRSDOS 6, shipped with the TRS-80 Model 4 in 1983, is identical to LDOS 6.00.

Dates

 * October, 1979 – Radio Shack releases TRSDOS 2.3
 * May 1, 1981 – Radio Shack releases Model III TRSDOS 1.3
 * April 26, 1983 – Radio Shack introduces TRSDOS Version 6.0 with the new Model 4s
 * 1984 – Radio Shack releases Version 6.2, the definitive version for the Model 4
 * 1984 – Logical Systems publishes The Source, the commented assembler source code to TRSDOS 6.2
 * Late 1986 – Logical Systems releases LS-DOS 6.3, the functionally equivalent update to TRSDOS 6.2. From this date, Tandy/Radio Shack ships it with the Model 4D.

Features and capabilities
RadioShack's Z80-based line of TRS-80 computers (Models I/III and Model 4) support up to four physical floppy (mini-diskette) drives which (as sold) use 5¼-inch diskettes. The original TRSDOS for the Model I supported only single-sided disks with 35 tracks formatted in single density (sectors are encoded using the frequency modulation technique). Model III TRSDOS (culminating in version 1.3) supported 40-track disks formatted in double density (using modified frequency modulation). Model Is retrofitted with double density controllers and Models I/III equipped with 80-track drives or double-sided drives could not use TRSDOS; RadioShack sold Logical System's LDOS operating system which could control these types of drives. The Model 4's TRSDOS 6 is a development of LDOS and has the same capabilities.

Hard disk drives (then also known as winchester drives) required custom driver software supplied by their manufacturers. These drivers permitted any TRSDOS installation to access them with up to eight possible drive partitions, each assigned to drive numbers zero through seven. Actually, a large hard drive could be formatted with more than eight partitions, but TRSDOS can only access eight during any one session. Hard drives could have some partitions formatted under TRSDOS and others under the CP/M OS. Each floppy drive in the system would also take up one drive number assignment. The Model 4, with its ability to set up a ramdisk (Memdisk), also required a drive number assignment for this.

All versions of TRSDOS use overlays to satisfy most system requests and disk directories are not maintained in memory. This has two implications for system performance. First, upon initial file access the DOS always references the disk directory to obtain information giving the physical mapping of disk space allocated to the file (including its extents, if any). After the initial access this information is maintained in a File Control Block, the memory space for which is supplied by the calling application. Further references do not need to read the disk directory (unless the file is written to and more disk space needs to be allocated). For this reason system performance depends greatly on how close a file's allocated disk space(s) is/are to the directory cylinder, and how fragmented (extents located in non-contiguous space(s)) the file is as a whole. The farther away the directory cylinder is, the more the drive's read/write head will need to move, which slows disk access and produces more mechanical wear on the drive. TRSDOS has commands permitting the user to optimize placement of particular files on the disk's physical space, and the command to display a map of a file's physical placement on a drive.

The second implication of the overlay-based architecture is that a disk containing TRSDOS system files (file extension /SYS) must always be present in whichever drive is assigned as logical drive number zero. (On the Model 4 this may be the Memdisk, thus freeing physical drive zero be used for a non-system data disk). LDOS and TRSDOS 6 have a SYSRES command which loads selected system files into Z80 RAM, thus freeing space on the system disk for non-system data. All versions have variants of the SYSTEM command which can reassign logical drive numbers to physical drives. It is possible to assign drive numbers such that a physical drive is unassigned a logical drive number; this is sometimes useful to guarantee that the drive cannot be accessed for security or safety (write protection) purposes. Drives may be set to be write protected by the DOS, also.

Disk management
The primary function of any disk operating system is to provide the user with a facility for managing and accessing files stored on disk storage devices. Since the user must not be burdened with the physical details of the storage devices themselves, it is the operating system's responsibility to translate file record access requests into specific drive, track, sector, and head parameters that pinpoint the storage location of each record.

The system also maintains in Z80 memory within TRSDOS a Drive Control Table that stores the parameters associated with each of the eight logical drives. Disk drive parameters refer to how the total storage space on a drive is divided up into addressable units. The layer(s) of magnetic particles on the surface of the disk media are magnetized (during the format process) into concentric circles of storage areas called TRACKS. Each track is divided into 256-byte sub-areas called SECTORS. Each sector is uniquely identified by a pattern of information preceding each sector called an ID FIELD. Although the number of sectors per track may vary from one media type to another, the number of sectors in each track of the same media (and in each granule) must always be a constant.

Disks are organized as follows: each track is formatted into a specific number of 256-byte sectors with a maximum capacity of 32 sectors per track. Sectors are grouped into blocks called granules which vary in size according to total track capacity of the disk media, though granule size for each disk format is constant. For forty-cylinder disks formatted in double density, standard for the drives installed in the TRS-80 Models III and 4, the granule size is six 256-byte sectors, or 1.5 KB. Each track has three granules for 4.5 KB of storage. Each side (surface) of the disk is normally formatted with 40 tracks, yielding 180 KB per side. The Model 4D, with its double-sided drives, yields 360 KB of storage. Whenever additional disk space is needed for a file (such as extending a file while being written to), an additional granule is allocated. The granule thus becomes the minimum size storage unit.

TRSDOS assigns numbers to every sector, every track, and every surface. Surfaces are numbered consecutively starting from zero. Tracks are numbered consecutively starting from zero at the outermost edge of the disk giving the innermost track the highest number. Where multiple headed drives are in use, the track numbers on a surface are duplicated on each surface with all similarly numbered tracks constituting a cylinder. For a double-sided floppy disk as formatted on a Model 4D, track zero of surface zero and track zero of surface one are grouped together into cylinder zero. Cylinder capacities also have an upper limit of 256 sectors per cylinder or eight granules per cylinder, while the system supports (for hard drives with multiple platters of storage media) a maximum of eight heads per drive.

The disk's directory cylinder is placed during the format process on the middle-numbered cylinder; thus a standard 40 cylinder disk has its directory installed on cylinder 20. This reduces the average distance (and access time) that the drive's read/write head must move to access the directory. The first sector of the disk directory contains the Granule Allocation Table (GAT). The GAT is bit mapped to each granule of space on the drive. Other fields in the GAT contain the PACK NAME, DATE of creation (when the disk was formatted), pack PASSWORD, and data pertaining to the configuration of the drive.

When a file is to be opened for access, the system needs to search the directory for its directory record. Search time is minimized by using a hashing technique to reduce the 11-character string formed from the file name and extension to a one byte value. The hash code for each file is stored in a Hash Index Table (HIT) which is the second sector of the directory. Each position in this table corresponds to a specific directory entry record. The hash table, being one sector in length, can index a maximum of 256 directory records or files. The directory itself is sized according to disk capacity by being a maximum of one cylinder (up to 34 sectors). Thus, the larger the disk storage capacity, the larger its directory, and the greater the number of file names that can be stored on the disk.

The directory record contains information such as the date the file was last modified, its update and access password codes, its access level, and other attributes such as whether it is a SYStem or PDS (Partitioned Data Set) file and if a backup has been made, the relative number of the last sector in the file, and the last byte within the last sector (or End Of File). The record also contains the physical area(s) in use by the file, by pointing to the cylinder, relative starting granule, and number of contiguous granules for each extent comprising the file. When a file has more than four extents, additional directory records are used as required with forward and backward pointers linking each record of each file. Thus the theoretical maximum of 256 files possible on a floppy diskette is realizable only if there is no file fragmentation.

When TRSDOS formats a disk, all of the parameters associated with the diskette are predetermined. Thus the number of sectors per track, number of sectors per granule and thus the granules per track, number of sides (surfaces), and number of cylinders are all designated, as well as the density of the media. Some of these figures (density, sides, granules per track) are written to fields in the Granule Allocation Table which is part of the disk directory. Others (sectors per track, sectors per granule, in addition to the former quantities) are part of the Drive Control Table fields. When the system attempts to open a file on a disk, it uses the @CKDRV SVC to ascertain the availability of the disk, and then logs the disk once it finds it available. This "logging" function will update the DIRCYL field, then update the DBLBIT and MAXCYL fields based on information stored in the GAT. This procedure frees the user from having to manually log a newly inserted disk; he is at liberty to change differently formatted disks in any drive without concern that the system will incorrectly access it.

The SVC disk primitives are funneled through common system routines contained in the driver software installed for each type of disk storage device. The driver for Model III or Model 4 floppy drives is named $FD and is located in the TRSDOS low memory region. Hard disk drives are supplied with their own driver software, and are usually installed in high memory (main 64K Z80 RAM) above the system HIGH$ pointer, since room in the low memory region is usually insufficient (especially on the Model 4 since software needed to access its external memory banks cannot reside in high Z80 RAM memory because that region exists in the banked RAM swap area). These driver routines establish a linkage protocol between the application requesting disk access and the computer's Floppy Disk Controller hardware. TRS-80s use controller chips from the Western Digital series: the WD1791 in the Model 4 non-gate array version, and the WD1773 in the Model 4 Gate Array version. When an I/O request is invoked by a higher level SVC, such as a request to READ a file record, the request is translated to that disk primitive (FDC command or status report) needed to satisfy the function request. The linkage protocol is uniform across all disk devices that are connected to the system. This makes the access of files transparent to size or nature of the disk device within the scope of the parameters stored in the DCT for that drive.

File management
Disk files are supported with two types of access: Record I/O and character I/O. Logical records of from one to 256 bytes in length can be read or written using the @READ or @WRITE SVC requests. Record I/O can be random access (by position SVC requests prior to READ/WRITE) or sequential access using repetitive READs or WRITEs. Character (or byte) I/O is accomplished by @GET and @PUT SVC requests and is essentially the same as record I/O with a Logical Record Length (LRL) equal to one. (Physical access to a disk storage device is always in units of 256 byte sectors. This is fixed by the TRS-80 disk controller hardware). However, if GET or PUT are used to implement sequential access, then a file can be considered a character I/O device just like a printer, a serial port, or a video display device. A byte I/O request is therefore independent of the physical device "connected" to the control block which is requesting the I/O. This makes the system "device independent".

Filenames are limited to eight alphanumeric characters (the first character must be alpha) which are case insensitive (only capital letters are used; any lowercase letters entered are capitalized). File extensions are up to three characters and obey the same rules. File passwords are up to eight characters obeying the same rules (TRSDOS 6 versions up to 6.2 support both owner and user passwords). Entire diskettes can also be assigned master passwords, which may limit user access via the BACKUP and PURGE commands.

Under TRSDOS and LDOS the system is never "logged in" to any current drive as with CP/M, PC DOS and MS-DOS. The system prompt is always TRSDOS Ready. All file access requests (whether issued by the user at the console or a program being executed) are satisfied by searching the directory of the first drive specified (taken as drive zero if no drive number is given) and, if the requested file is not found, then searching the next (higher numbered) drive in the system. This continues until the file is found or all the drives in the system have been searched (but see below for variations on this rule).

Drive numbers are specified with a colon : followed immediately with the drive number. The colon is optional unless the drive specification is used as a suffix for a filename. Using the DIR directory command as an example:


 * DIR displays all files starting with logical drive zero, then drive one, and so on.
 * DIR :4 or DIR 4 searches logical drive four (for all files, as always when no filename is given).
 * DIR :4-6 or DIR 4-6 searches logical drives four, five, and six.
 * DIR :4- or DIR 4- searches logical drives four, five, six and seven.
 * DIR FILENAME:2 searches for FILENAME on logical drive two.
 * DIR FILENAME:2- searches for FILENAME on all logical drives starting from drive two.

As seen, the dash character - is used to specify a range of drive numbers. The DIR and CAT (catalog) commands display all file specifications (filespecs) matching the query on all drives. Other commands/utilities such as BACKUP, COPY and PURGE, and drive searches initiated by programs being executed, stop searching at the first drive found to match. If the same filespec exists on multiple drives, then those files on higher-numbered drives will be excluded.

File access by partial filenames (partspecs), file extensions, and file dates are supported. For example:


 * DIR SAMPLE will select files SAMPLE, SAMPLE1, SAMPLE23 and SAMPLEIT.
 * DIR /BAS will select files SAMPLE/BAS, TEST/BAS, EXAMPLE/BAS, etc.

As with the DIR example earlier, drive specifications (drivespecs) may be appended to filespecs. These examples assume the selected files have not be made invisible in the disk directory. File access requests issued by applications programs running under TRSDOS work the same way.

Command-line interface
Under TRSDOS/LS-DOS 6.x, the standard system command interpreter (SYS1/SYS) can be functionally replaced with a custom interpreter by copying the new interpreter to the system file SYS13/SYS (which in an unmodified installation is a dummy file). This can be any machine code /CMD program file. This is referred to in the documentation as an "Extended Command Interpreter" or ECI.

TRSDOS/LS-DOS 6.x support wildcard characters in filenames, both the single character ? and multicharacter *.

TRSDOS (version II) was notable for the inclusion of noise words, similar to the 1959 COBOL specification. These made commands more English-like. For example, the following commands functioned identically:
 * COPY filea fileb
 * COPY filea TO fileb

Since TRSDOS does not have the notion of redirection for disk files as UNIX/Linux and MS-DOS do, the APPEND command is somewhat different in concept than the UNIX or MS-DOS notion of appending via output redirection. TRSDOS/LS-DOS 6.x do provide I/O redirection for system devices (keyboard *KI, display screen *DO, printer *PR, serial port *CL), as well as for between devices and disk files. The DEVICE command displays a map of I/O links and routes. Under DOS and UNIX printing a file can be done with redirection; under UNIX it is normally done by spooling the file to the "line printer" (using the lpr command) because UNIX is conventionally a multi-user system. TRSDOS/LS-DOS 6.x print jobs can be redirected (such as to a disk file) by applying the LINK or ROUTE commands to the system *PR device.

TRSDOS/LS-DOS 6.x do not support subdirectories or user areas. However, the DIR and CAT (Catalog) commands for displaying file data support the usual partial filenames, suffixes, and file dates. Under TRSDOS/LS-DOS 6.x files can be made invisible to the DIR and CAT commands, and can be displayed with the INV parameter (unless any files are password protected and the correct p/w is not given).

TRSDOS/LS-DOS 6.3 can dump the video screen to the line printer by pressing CTRL.

Many versions support a simple password security for files and programs, with separate Read/Execute and full access capabilities. ex: filename/ext.password:drive#. TRSDOS 6.x supports both Owner and User passwords (8 characters max) for disk files. LS-DOS 6.3 uses the space for the User password for its extended dating scheme (past December 31, 1987). Both Model 4 OSes can set various file access levels and permit software write protection for disk files and entire disks.

Commands
Although MS-DOS owes its heritage most closely to CP/M and thence to TOPS-10, many of the file manipulation commands are similar to those of TRSDOS. Some of the following TRSDOS commands exist on disk as distinct program files (DIR/CMD, FORMAT/CMD, BACKUP/CMD) while all others exist as modules condensed into the library files (technically Partitioned Data Sets or PDSs) SYS6/SYS, SYS7/SYS and SYS8/SYS; these include the TRSDOS commands CAT, COPY, LIST, REMOVE, RENAME etc. Some typical TRSDOS utilities:

Example code
The following Z80 assembler source code is for a subroutine named HELLO_WORLD. This is an introductory program which will print a message to the video display and then exit. Though simple, it demonstrates how an assembler source code is formatted and interacts with the display hardware through TRSDOS. The example uses TRS-80 Model 4 running TRSDOS/LS-DOS 6.x, produced by Tandy/Radio Shack and Logical Systems, with most any assembler sold by Radio Shack or Misosys Inc. (Series I/EDTASM, ALDS, EDAS or MRAS with -GC switch).