CBM Funet Archive/cbm-funet-archive-2003.iso/cbm/c128/utilities/lrr270.sfx/lrr270.txt

Text File | 1998-02-16 | 25.3 KB | 454 lines

LITTLE RED READER  Version 2.70  [February 16, 1998]

MS-DOS file reader/writer for the C128 and 1571/81/FD drives.

by Craig Bruce  ([e-mail])

Little Red Reader (LRR) is a program for the C128 that will read and write
files to and from MS-DOS floppy disks using a 1571, 1581, CMD FD-2000, or CMD
FD-4000 disk drive.  With the FD drives, you can use High Density (HD) MS-DOS
disks. The program copies files from drive to drive (no internal buffering),
so you need a second disk drive (either real or virtual) to copy files to.
You can use RAMDOS for the second drive if you have an REU and you execute a
GRAPHIC CLR after starting it up.  The menu-driven full-screen user interface
is written in BASIC so it is mildly sluggish, but the actual file copying is
written in machine language and operates as fast as the disk drives will go.

1. INTRODUCTION

This document presents a program that reads and writes MS-DOS files and the
root directory of MS-DOS disks.  The program copies only from drive to drive
without buffering file data internally.  This is simpler and imposes no limits
on the size of the files transferred, although it requires the use of two disk
drives (or a logical drive).  The user-interface code is written in BASIC and
presents a full-screen file selection menu.  The grunt-work code is written in
assembly language and operates at maximum velosity.

The program also allows MS-DOS files to be deleted and to allows the copying
of Commodore-DOS files between CBM-DOS disks (this makes it more convenient to
use the program with a temporary logical drive like RAMDOS).  Also, since I
have a CMD FD-4000 floppy disk drive, I know that this program works with
MS-DOS disks with this drive (for both the 720K and 1.44M MS-DOS formats).
The FD disk drives are logically referred to below as being the 1581.

The Burst Command Instruction Set of the 1571/81 is used to read the MS-DOS
disk blocks and the standard kernel routines are used for outputting the data.
(I am an operating systems specialist, so I call it a kernEl!) Thus, the
MS-DOS files must be read from a 1571 or 1581 disk drive, but the output
device may be any disk drive type, the screen or a printer, or a virtual drive
type such as RAMLink, RAMDrive, or RAMDOS (for the REU).  It is interesting to
note that the data can be read in from an MS-DOS disk faster than it can be
written out to a 1571, 1581, or even a RAMDOS file.  A RAMLink can swallow the
data only slightly faster than it can be read.

Little Red Reader (LRR) supports double density 3.5" disks formatted with 80
tracks, 9 sectors per track, and 2 sides with a 1581 and 5.25" double density
disks formatted with 40 tracks, 9 sectors per track, and 2 sides with a 1571,
and more recently, high density 3.5" disks formatted with 80 tracks, 18
sectors per track, 2 sides, and a "12-bit FAT".  A limit of 224 directory
entries and 9 File Allocation Table (FAT) sectors is imposed.  There must be 2
copies of the FAT and the cluster size may be 1 or 2 sectors.  The sector size
must be 512 bytes.

The program runs on either the 40 or 80-column screens, but you will get much
better performance from the BASIC portion of the program by being in 80-column
mode and FAST mode.  A modification that someone might want to make would be
to spread-out the display for the 80-column screen and add color to the rather
bland display.

Oh, about the name.  It is a play on the name of another MS-DOS file copier
available for the C-128.  "Little" means that it is smaller in scope than the
other program, and "Red" is a different primary color to avoid any legal
complications.  It is also the non-white color of the flag of the country of
origin of this program (no, I am not Japanese).  Also, this program is Public
Domain Software, as is all software I develop for 8-bit Commodore Computers.
Feel free to E-mail me if you have questions or comments about this article.

2. USER GUIDE

LOAD and RUN the "lrr270" BASIC program file.  When the program is first run,
it will display an "initializing" message and will load in the binary machine
language package from the "current" Commodore DOS drive (the current drive is
obtained from PEEK(186) - the last device accessed).  The binary package is
loaded only on the first run and is not reloaded on subsequent runs if the
package ID field is in place.

The system is designed to have two file selection menus: one for the MS-DOS
disk drive, and one for the Commodore-DOS disk drive (which may be a logical
disk drive).  The idea for copying is that you select the files in one of
these menus, and then program knows to copy them to the disk for the other
menu.

2.1. MS-DOS MENU

The main screen of the program is then displayed.  The main screen of the
program will look something vaguely like this:

   MS-DEV=9    MS-TYPE=1581    CBM-DEV=8

   NUM  S  TRN  TYP  FILENAME  EXT  LENGTH
   ---  -  ---  ---  --------  ---  ------
     1  *  ASC  SEQ  HACK4     TXT  120732
     2     BIN  PRG  RAMDOS    SFX   34923

   D=DIRECTORY  M=MS-DEV  F=CBM-DEV Q=QUIT
   T=TOGGLE-COLUMN, C=COPY-FILES, +/- PAGE

except that immediately after starting up, "<directory not loaded>" will be
displayed rather than filenames.  The "MS-DEV" and "MS-TYPE" fields give the
device number and type of the drive containing the MS-DOS disk to copy from,
and the "CBM-DEV" gives the device number of the drive/virtual drive/character
device to copy file data to.  The number of bytes free on the drive are also
displayed (which is useful to know when writing files) and there are some more
commands.

Information about all MS-DOS files in the root directory of the MS-DOS disk is
displayed in columns below the drive information.  "NUM" gives the number of
the MS-DOS file in the directory listing, and "S" indicates whether the file
is "selected" or not.  If the file is selected, an asterisk (*) is displayed;
otherwise, a blank is displayed.  When you later enter Copy Mode, only the
files that have been "selected" are copied.

The "TRN" field indicates the character translation scheme to be used when the
file is copied.  A value of "BIN" (binary) means no translation and a value of
"ASC" (ascii) means the file characters are to be translated from MS-DOS ASCII
(or "ASCII-CrLf") to PETSCII.  The "TYP" field indicates the type of
Commodore-DOS file to create for writing the MS-DOS file contents into.  The
possible values are "SEQ" (sequential) and "PRG" (program).  The values of the
TRN and TYP fileds are set independently, so you can copy binary data to SEQ
files and ascii data to PRG files if you wish.

The "FILENAME" and "EXT" fields give the filename and extension type of the
MS-DOS files and "LENGTH" gives the exact length of the files in bytes.  Note
that if you perform "ASC" translation on a file, its PETSCII version will have
a shorter length.

2.2. USER COMMANDS

The bottom of the screen gives the command summary.  After starting the
program, you will want to setup the MS-DOS and CBM-DOS drives with the "M" and
"F" commands.  Simply press the (letter) key corresponding to the command name
to activate the command.  Pressing M will prompt you for the MS-DOS Drive
Number and the MS-DOS Drive Type.  In both cases, type the number and press
RETURN.  (Sorry for insulting all non-novices out there, but I want to be
complete).  The MS-DOS drive number cannot be the same as the CBM-DOS drive
number (since the program copies from drive-to-drive without internal
buffering).  For the drive type, enter an "8", "81", or "1581" for a 1581
drive or FD-series drive, or a "7", "71", or "1571" for a 1571 drive.

Pressing F will prompt you for the CBM-DOS device number.  You may enter a
number from 0 to 30, except that it must not be the MS-DOS drive number.
Enter a "1" for Cassette Drive (God forbid!), a "3" for the screen, a "4" for
the printer (with an automatic secondary address of 7 (lowercase)), any number
above 7 for a Commodore disk drive or special virtual drive, or a value of "0"
for the special "null" drive.  A CBM-DEV value of 0 will case the program to
read MS-DOS files and do nothing with the output.  You can use this feature to
check out the raw reading speed of the program.

After setting up the drives, press D to read in the root directory off the
MS-DOS disk.  The data will come blazing in from the disk but BASIC will take
its good ole time sifting through it.  Filenames are displayed on the screen
as they are scanned in.  The program will (eventually) return to the main
screen and display the formatted file information.  One note: the process of
logging in a 1581 MS-DOS disk takes about 12 seconds (on my 1581, anyway), so
be patient.  An MS-DOS disk will have to be "logged in" every time you change
MS-DOS disks.  (Disks are logged in automatically).

A couple of notes about accessing MS-DOS disks: don't try to access a device
that is not present because the machine language routines cannot handle this
error for some reason and will lock up, requiring a STOP+RESTORE.  Also, make
sure that an actual MS-DOS disk is loaded into the drive.  If you accidentally
place Commodore-DOS disk into the MS-DOS drive, the 1581 will report an
invalid boot parameters error (#60), but a 1571 will lock up (since I don't
check the sector size and my burst routines are expecting 512 bytes to come
out of a sector whereas Commodore disks have only 256 bytes per sector).

Now you are ready to pick what files you want copied and how you want them
copied.  You will notice that a "cursor" appears in the "S" column of the
first file.  You may move the cursor around with the cursor keys: UP, DOWN,
LEFT, RIGHT, HOME, and CLR.  CLR (SHIFT-HOME) will move the cursor back to the
first file on the first screen.  You can move the cursor among the select,
translation, and file-type columns of all the files.  Pressing a SPACE or a
RETURN will toggle the value of the field that the cursor is on.  To toggle
all of the values of the "cursor" column (including files on all other
screens), press T.  You will notice that moving the cursor around and toggling
fields is a bit sluggish, especially if you are in Slow mode on the 40-column
screen.  Did I mention that this program will run on either the 40 or
80-column screen?  Toggling an entire column can take a couple of seconds.

If there are more than 18 MS-DOS files, you can press the "+" and "-" keys to
move among all of the screens of files.  The cursor movement keys will wrap
around on the current screen.  "+" is page forward, and "-" is page backward.
The screens wrap around too.

After you have selected all of the files you want to copy and their
translation and file-type fields have been set, press the C key to go into
Copy Mode (next section).  After copying, you are returned to the main screen
with all of the field settings still intact.  To exit from the program, press
Q.

Additional commands are: "R" (remove == delete), "/" (change menu), and "X"
(copy CBM files == "Xerox").  The remove command is used to delete selected
files from the MS-DOS disk.  After selecting this option, you will get an
annoying "are you sure" question and the the selected files will quickly
disappear and the changes will finally be written to disk.  Deleting a batch
of MS-DOS files is much quicker than deleting Commodore-DOS files since MS-DOS
disks use a File Allocation Table rather than the linked list of blocks
organization that CBM uses.  In order to make the BASIC program execute
quicker, after deleting, the original order of the filenames in the directory
listing will be changed.  Be forewarned that the delete operation is
non-recoverable.

The change menu command is used to move back and forth between the
Commodore-DOS and MS-DOS menus.

2.3. COPYING MS-DOS TO CBM-DOS

When you enter copy mode, the screen will clear and the name of each selected
file is displayed as it is being copied.  If an error is encountered on either
the MS-DOS or CBM-DOS drive during copying, an error message will be displayed
and copying will continue (after you press a key for MS-DOS errors).

To generate a CBM-DOS filename from an MS-DOS filename, the eight filename
characters are taken (including spaces) and a dot (.) and the three characters
of the extension are appended.  Then, all spaces are removed, and if the name
ends with a dot (.) character, then that dot character is removed as well.  I
think this is fairly reasonable.

If there already is a file with the same filename on the CBM-DOS disk, then
you will be prompted if you want to overwrite the file or not.  Entering an
"n" will abort the copying of that file and go on to the next file, and
entering a "y" (or anything else) will cause the CBM-DOS file to be
"scratched" and then re-written.

The physical copying of the file is done completely in machine language and
nothing is displayed on the screen while this is happening, but you can follow
things by looking at das blinkin lichtes and listening for clicks and grinds.
You will probably be surprised by the MS-DOS file reading speed (I mean in a
good way).  The disk data is read in whole tracks and cached in memory and the
directory information and the FAT are retained in memory as well.  The result
is that minimal time is spent reading disk data, and no costly seeks are
required for opening a new MS-DOS file.  A result is that small files are
copied one after another very quickly.  You will have to wait, however, on the
relatively slow standard kernel/Commodore-DOS file writing.

A few changes had to be made to the program to accomodate the RAMDOS program.
RAMDOS uses memory from $2300 to $3FFF of RAM0, which is not really a good
place for a device driver, and it uses some of the zero-page locations that I
wanted to use.  But, difficulties were overcome.  The importance of RAMDOS
compatibility is that if you only have one disk drive but you have an REU, you
can use RAMDOS to store the MS-DOS files temporarily.  Since the new version
has greater memory requirements, after starting up "ramdos" (if you use it)
you will have to execute the "graphic clr" BASIC command.  If you only have
one disk drive and no REU, you are SOL (Out of Luck) unless you can get a
RamDisk-type program for an unexpanded 128.  The RAMDOS program is available
from FTP site "ftp.jbrain.com" in directory
"/pub/cbm/software/utils/128/OLDIES92" in file "ramdosii.sfx".  One note I
found out about RAMDOS: you cannot use a

DOPEN#1,(CF$),U(CD),W

with it like you are supposed to be able to; you have to use a

DOPEN#1,(CF$+",W"),U(CD)

Here is a table of copying speeds for copying from 1571s and 1581s with ASC
and BIN translation modes.  All figures are in bytes/second.  These results
were obtained from copying a 127,280 byte text file (the text of C= Hacking
Issue #3).

   FROM  \ TO: "null"     RAMLink     RAMDOS     JD1581     JD1571
   -------+    ------     -------     ------     ------     ------
   81-bin {CBM--}      5772        3441       2146        n/a        644
   81-asc {CBM--}      5772        3434       2164        n/a        661
   71-bin {CBM--}      4323        2991       1949       1821        n/a
   71-asc {CBM--}      4323        2982       1962       1847        n/a

The "null" device is that "0" CBM-DOS device number, and a couple of entries
are "n/a" since I only have one 1571 and one 1581.  Note that my 71 and 81 are
JiffyDOS-ified, so the performance of a stock 71/81 will be poorer.  JiffyDOS
gives about a 2x performance improvement for the standard file accessing calls
(open, close, chrin, chrout).  RAMDOS doesn't seem to be as snappy as you
might think.

The "null" figures are quite impressive, but the raw sector reading speed
without the overhead of mucking around with file organization is 6700
bytes/sec for a 1581 and 4600 B/s for a 71.  The reason that the 1571 operates
so quickly is that I use a sector interleave of 4 (which is optimal) for
reading the tracks.  I think that other MS-DOS file copier program uses an
interleave of 1 (which is not optimal).  I lose some of the raw performance
because I copy the file data internally once before outputting it (to simplify
some of the code).

In a couple of places you will notice that ASC translation gives slightly
better or slightly worse performance than BIN.  This is because although
slightly more work is required to translate the characters, slightly fewer
characters will have to be written to the CBM-DOS file, since PETSCII uses
only CR where MS-DOS ASCII uses CR and LF to represent end-of-line.
Translation is done by using a table (that you can change if you wish).  Many
entries in this table contain a value of zero, which means that no character
will be output on translation.  Most of the control characters and all of the
characters of value 128 (0x80) or greater are thrown away on being translated.
The table is set up so that CR characters are thrown away and the LF character
is translated to a CBM-DOS CR character.  Thus, both MS-DOS ASCII files and
UNIX ASCII files can be translated correctly.

2.4. COMMODORE-DOS MENU

The Commodore-DOS menu, which displays the names of the Commodore files
selected for various operations, looks and works pretty much the same as the
MS-DOS menu:

   CBMDOS  MS=10:1581  CBM=8  FREE=3211476

   NUM  S  TRN  FILENAME         T  LENGTH
   ---  -  ---  ---------------- -  ------
     1  *  BIN  LRR-128          P    9876
     2     ASC  COM-HACKING-005  S  175412

   D=DIR M=MSDEV F=CBMDEV C=COPY Q=QUIT
   T=TOGGLE R=REMOVE X=CBMCPY /=MENU +-=PG

You'll notice, however, that the filetype field ("T" here) is moved and is
unchangable.  Also, the file lengths are not exact; they are reported as the
block count of the file multiplied by 254.  This menu is not maintained for
files being copied to the CBM-DOS disk from an MS-DOS disk.  You'll have to
re-execute the Directory instruction to get an updated listing.

The "D" (directory) command has local effect when in this menu.  The
Commodore-DOS directory will be loaded from the current CBM device number.
Note that in order for this to work, the CBM device must be number eight or
greater (a disk drive).  Originally, the subroutine for this command was
written using only GET#'s from the disk and was very slow.  It was modified,
however, to call a machine language subroutine to read the information for a
directory entry from the directory listing, and hence the subroutine now
operates at a tolerable speed.

The "C" (copy) command also has a different meaning when in this menu.  It
means to copy the selected CBM files to the MS-DOS disk.  See details below.

The copy CBM files ("X") command is used to copy the files in the CBM-DOS menu
to another CBM-DOS disk unit.  Select the files you want to copy and then
press X.  You will then be asked what device number you want to copy the files
to.  The device can be another disk drive or any other device (except the
keyboard).  Using device number 0 does not mean the "null" device as it does
with copying MS-DOS to CBM.  If you are copying to a disk device and the file
already exists, then you will be asked if you wish to overwrite the file.  You
cannot copy to the same disk unit.  Also, all files are copied in binary mode
(regardless of what translation you have selected for a file).

The copy CBM files command was included since all of the low-level gear needed
to implement it (specifically "commieIn" and "commieOut" below) was also
required by other functions.  This command can be very convenient when working
with RAMDOS.  For example, if you only had a 1571 as device 8 but you have a
RAM expander and have installed RAMDOS as device 9, then you would copy MS-DOS
files to RAMDOS using the MS-DOS menu, and then you would go to the
Commodore-DOS menu ("/"), read the directory, select all files, insert an
Commodore-DOS diskette into your 1571, and then use "X" to copy from the
RAMDOS device to the 1571.

The remove command ("R") does not work for this directory.  You can SCRATCH
your CBM-DOS files your damn self.

2.5. COPY CBM-DOS TO MS-DOS

Before you can copy selected CBM-DOS files to an MS-DOS disk, the MS-DOS disk
directory must be already loaded (from the MS-DOS menu).  This is required
since the directory and FAT information are kept in memory at all times during
the execution of this program.

When you enter copy mode, the screen will clear and the name of each selected
file is displayed as it is being copied.  If an error is encountered on either
the MS-DOS or CBM-DOS drive during copying, an error message will be displayed
and copying will continue (after you press a key for MS-DOS errors).  Please
note that not a whole lot of effort was put into error recovery.

To generate an MS-DOS filename from an CBM-DOS filename, the following
algorithm is used.  The filename is searched from right to left for the last
"." character.  If there is no "." character, then the entire filename, up to
11 characters, is used as the MS-DOS filename.  Characters 9 to 11 will be
used as the extension.  If there is a "." character, the all characters before
it, up to eight, will be used as the MS-DOS filename and all characters after
the final ".", up to three, will be used as the MS-DOS extension.

Then, the newly generated MS-DOS filename is scanned for any extra "."
characters or embedded spaces.  If any are found, they are replaced by the
underscore character ("_", which is the backarrow character on a Commodore
display).  Finally, all trailing underscores are removed from the end of both
the filename and extension portions of the MS-DOS filename.  Also, all
characters are converted to lowercase PETSCII (which is uppercase ASCII) when
they are copied into the MS-DOS filename.  Note that if the Commodore filename
is not in the 8/3 format of MS-DOS, then something in the name may be lost.
Some examples of filename conversion follow:

CBM-DOS FILENAME       MS-DOS FILENAME
----------------       ---------------
"lrr.bin"              "lrr.bin"
"lrr.128.bin"          "lrr_128.bin"
"hello there.text"     "hello_th.tex"
"long_filename"        "long_fil.ena"
"file 1..3.s__5"       "file_1.s"

It would have been time-consuming to have the program scan the MS-DOS
directory for a filename already existing on the disk, so LRR will put
multiple files on a disk with the same filename without complaining.  This
also gets rid of the problem of asking you if you want to overwrite the old
file or generate a new name.  However, in order to retrieve the file from disk
on an MS-DOS machine, you will probably have to use the RENAME command to
rename the first versions of the file on the disk to something else so MS-DOS
will scan further in the directory for the last version of the file with the
same filename.  There is no rename command in LRR because I never thought of
it in time.  It would have been fairly easy to put in.

The date generated for a new MS-DOS file will be set from the default time.

The physical copying of the file is done completely in machine language and
nothing is displayed on the screen while this is happening, but you can follow
things by looking at the blinking lights and listening for clicks and grinds.

Since the FAT and directory are maintained in RAM during the entire copying
process and are only flushed to disk after the entire batch of files are
copied, copying is made more efficient, since there will be no costly seek
back to track 0 after writing each file (like MS-DOS does).  If you have a
number of small files to copy, then they will be knocked off in quick
succession, faster than many MS-DOS machines will copy them.

To simplify the implementation, the current track of disk blocks for writing
is not maintained like it is for reading.  Also, a writing interleave of 1:1
is used for a 1571, which is not optimal.  However, since writing is such a
slow operation anyway, and since the 1571 is particularly bad by insisting on
verifying blocks, not much more overhead is introduced than is already
present.

An interesting note about writing MS-DOS disks is that you can terminate LRR
in the middle of a copy (with STOP+RESTORE) or in the middle of copying a
batch of files, and the MS-DOS disk will remain in a perfectly consistent
state afterwards.  The state will be as if none of the files were copied.  The
reason is that the control information (the FAT and directory) is maintained
internally and is flushed only after copying is all completed.  But don't
terminate LRR while it is flushing the control information.

Here is a table of copying speeds for copying to 1571, 1581, and CMD FD-4000
disk units with ASC and BIN translation modes.  All figures are in bytes/
second, which includes both reading the byte from a C= disk and writing it to
the MS-DOS disk.  The average speed for either the read or write operation
individually will be twice the speed given below.  These results were obtained
from copying a 156,273 byte text file (the text of C= Hacking Issue #4).

   FROM   \ TO: FD-bin     FD-asc     81-bin     81-asc     71-bin     71-asc
   --------+    ------     ------     ------     ------     ------     ------
   RAMLink {CBM--}     2,332      2,200      2,332      2,200      1,594      1,559
   RAMDOS  {CBM--}     1,070      1,053      1,604      1,600      1,561      1,510
   FD4000  {CBM--}         -          -      1,645      1,597      1,499      1,464
   JD1581  {CBM--}     1,662      1,619          -          -      1,474      1,440
   JD1571  {CBM--}     1,050      1,024        953        933          -          -

These figures are for transfer speed only, not counting the couple of seconds
of opening files and flushing the directory.  Note that all my physical drives
are JiffyDOS-ified, so your performance may be slower.  I am at a loss to
explain why an FD-4000 is so much slower than a 1581 for copying from a RAMDOS
file, but the same speed or better for copying from anything else.

---------------------------------------------------------End-of-Document------