Disk Basic Summary

In addition to the capabilities of Extended Color BASIC, Color Disk BASIC
adds the following.
  ------------------------------------------------------------------------

Disk management commands
   BACKUP n TO m            Copy all files from one disk to another
   BACKUP n                 BACKUP a disk using only a single disk drive
   COPY file1 TO file2      Make a duplicate of a file
   DIR n                    List the files that are on the disk
   DRIVE n                  Use drive n as the default
   DSKINIn                  Initialize (format) a disk
   KILL file                Delete a file from the disk
   LOAD file,R              Load a program, and optionally start it running
   LOADM file,offset        Load a machine-code program, shifting by offset
   MERGE file,R             Load an ASCII program without clearing the old one
   RENAME file1 TO file2    Change the name of a file
   RUN file,R               Load a program, and optionally start it running
   SAVE file,A              Save a program, optionally in ASCII
   SAVEM file,a1,a2,ax      Save a machine-code program, from a1 to a2, exec at ax
   VERIFY ON                Double-check all writes to the disk
   VERIFY OFF               Don't double-check

Programming commands
   FILES max_f,size         Reserve buffers for open files
   FREE(n)                  Returns the number of free granules (2304 bytes each)
   UNLOAD n                 Close all open files on drive n
   DSKI$ n,t,s,v1$,v2$      Read track t sector s into v1$ and v2$
   DSKO$ n,t,s,v1$,v2$      Write track t sector s from v1$ and v2$
   OPEN "I",f,file          Open a file for sequential input (ie: INPUT)
   OPEN "O",f,file          Open a file for sequential output (ie: PRINT/WRITE)
   OPEN "D",f,file,len      Open a file for direct access; (ie: GET/PUT);
                              record length len is optional
   CLOSE #f                 Close a file

Sequential file commands
   EOF(f)                   Returns true if file f has been read to the end
   INPUT #f, var,...        Read variables from a file
   LINE INPUT #f,var$       Read an entire line from a file into a string variable
   WRITE #f,values          Write values to file, with commas, strings in quotes,...
   PRINT #f,values          Write values to file, just as PRINT would display them
   PRINT #f,USING f$;values Formatted printing; many options for f$

Direct-access file commands
   FIELD #f, size AS v$,... Give variable names to parts of the file buffer
   RSET v$ = value$         Fill in a named part of the file buffer, right-justified
   LSET v$ = value$         Fill in ..., left justified
   PUT #f,r                 Write the buffer to record r
   GET #f,r                 Read record r into the buffer
   CVN(var$)                Make a number out of a binary string
   MKN$(num)                Make a binary string out of a number
   LOC(f)                   Return the current record number in the buffer
   LOF(f)                   Return the highest record number in the file

In all cases, f is a file number, n and m are drive numbers, file is a
filename, and dollar signs signify variables that must be string-variables.
Note that filenames must be either string variables or string constants in
quotes. Upper-case words are keywords, lower-case words are supplied by the
user.

Special file numbers are -2=printer -1=cassette and 0=screen

  ------------------------------------------------------------------------
Syntax for a filename, in BNF. (Things in square brackets are optional, the
vertical bar separates alternatives, angle brackets surround nonterminals,
and uppercase words denote single-letter constants.)

<filename> ::= <name> [(DOT|SLASH) <extension>] [COLON <drivenum>]

The name can be up to eight characters long, and cannot include a dot,
slash, colon, or zero. The extension can be up to three characters long,
and also cannot include those four characters. The drive number is a single
digit, from zero up to the highest drive on your system.

  ------------------------------------------------------------------------
There is one documented subroutine in the Disk BASIC ROM that you can use
to access the disk. Its address is stored at $C004 and $C005, so you jump
to it using indirection: JSR [$C004] .

Before calling that, you should load the X register with the address of a
data structure that describes what you want to do. The examples in the
manual always load this address from locations $C006 and $C007. I have not
tried using this, so I don't know it will work if you put your structure
anyplace else. This data structure is seven bytes long:

        1 byte    op code (0 - 3)
        1 byte    drive number (0 - 3)
        1 byte    track number (0 - 34)
        1 byte    sector number (1 - 18)
        2 bytes   address of 128-byte data buffer
        1 byte    error code

Op codes are either 0 (restore to track 0), 1 (no op), 2 (read sector), or
3 (write sector).

Bits in the error code are defined as follows (since the labels match those
in the 1771 data sheet, I assume it is just the 1771 status code being
returned, and have taken the much more complete descriptions from that data
sheet). Note that some of the bits have different meanings based on which
command caused them to be set.

        7   Not Ready
                This bit, when set, indicates that the disk drive is
                not ready to perform a read or write operation.  When
                reset it indicates that the drive is ready.  Thus,
                this bit is an inverted copy of the READY input signal
                to the 1771 from the disk drive, and is logically ORed
                with the *MR signal

        6   Record Type/Write Protect
                On a Read command, this bit is used in conjunction with
                Bit 5 to indicate the type of data address mark that
                was read.  On a Write command, this bit indicates that
                the diskette was write protected.

        5   Record Type/Write Fault/Head Loaded
                On a Read command, this bit in conjunction with Bit 6
                indicates the type of data address mark that was read.
                On a Write command, this bit indicates that the write
                fault input from the disk drive was detected: it is
                thus an inverted copy of the *WF input signal.
                On a Restore command, this bit indicates that the
                read/write head is loaded against the diskette surface.
                This bit is thus the logical AND of the HLD and HLT
                signals.

        4   Record Not Found/Seek Error
                On Read or Write command, this bit indicates that the
                desired track and sector were not found.
                On a Restore command, this bit indicates that the
                designated track could not be verified.  This bit is
                reset to 0 whenever a new command is loaded.

        3   CRC error
                On a Read or Write command, if Bit 4 is also set, then
                this bit indicates that an error was found in one or
                more ID fields; otherwise, it indicates an error in a
                data field.
                On a Restore command, this bit indicates that one or
                more CRC errors were encountered on a track verification
                operation.  This bit is reset to 0 whenever a new
                command is loaded.

        2   Lost Data/Track 00
                On a Read or Write command, this bit indicates that
                the microprocessor did not respond to the Data Request
                (DRQ) within one byte time and that a byte of data was
                subsequently lost.
                On a Restore command, this bit indicates that the read/
                write head is positioned over track 0.  This bit is
                thus an inverted copy of the *TR00 input to the 1771.

        1   Data Request/Index
                On a Read or Write command, this bit is a copy of the
                DRQ output signal.  When set, it indicates that the
                Data register is full on a read operation or empty on
                a write operation.
                On a Restore command, this bit indicates that an index
                mark was detected on the diskette.  This bit is thus
                an inverted copy of the *IP input to the 1771.

        0   Busy
                When set, this bit indicates that a command is currently
                being executed.  This bit is reset when a command is
                completed and thus indicates that the 1771 is available
                to execute another command.

The disk control routine modifies the contents of only the condition code
register.

Finally, note that you can force the drive motor to turn off by writing a
zero into address $FF40. This probably also means you could force the motor
on by writing non-zero there, but the documentation doesn't explain which
bits to what.

Back to my top-level CoCo page

  ------------------------------------------------------------------------
26-Mar-96
yakowenk@csx.unxc.edu
(remove all "x"s to get a valid address)
