Gold Fish 1/GoldFishApril1994_CD2.img/d4xx/d471/btntape/tape.doc

Text File | 1991-04-17 | 35KB | 718 lines

****    BTNtape:  an AmigaDOS handler for SCSI tape drives
****       Version 2.0   3/28/91
****       Freeware by Bob Rethemeyer   ([e-mail])
****
****    (c) Copyright 1990, 1991  Robert Rethemeyer.
****      This software may be freely distributed and redistributed,
****      for non-commercial purposes, provided this notice is included.
****      All original files must be included in the distribution.

BTNtape is a "Better Than Nothing" SCSI tape device handler.  It provides
flat-file access to a SCSI tape drive from application programs using
simple DOS calls to Read() and Write().  It can also be used with the Amiga
TAR utility for disk backups.  It requires a "SCSI-direct" compatible
SCSI bus adapter.  This is version 2.0, update to version 1.0.  It now
supports many more tape drives, and includes some new features.

Some advantages of BTN over other handlers and dedicated tape backup programs:
  * Includes a monitor program that keeps you informed of what's happening
  * Supports many standard SCSI tape drives and Amiga SCSI bus adapters
  * Supports the 3M MCD-40, a non-standard SCSI tape drive
  * Supports any size of tape block, and multiple-block accesses
  * Supports tape files that span multiple tape volumes
  * Double buffering improves streaming performance
  * Includes an interface to send SCSI control commands to the drive
  * Includes an interface to set drive-specific Mode Select parameters
  * TAR tapes can be exchanged with Un*x systems

=================== ******> R E A D   T H I S <****** ======================

DISCLAIMER:
 "This software is provided 'as-is', without warranty of any kind,
either expressed or implied.  In no event will I, Robert Rethemeyer,
be liable for direct, indirect, incidental or consequential damages or
data loss resulting from the use or application of this software.  The entire
risk as to the results and performance of this software is assumed by you."

I cannot guarantee that this software is compatible with any combinations
of drives or adapters other than those I have specifically tested.

If you do not agree with this disclaimer,  I recommend you not use this
software;  wait for commercial tape drivers.

============================================================================

This handler is probably not the all-purpose tape driver you have been waiting
for.  It won't work with any backup program which requires Exec devices.
I claim only that it works with the Amiga TAR program ported by Jonathan Hue.
But until we see good commercial or shareware tape software, you might
find this handler to be "better than nothing".

I will try to provide support for this handler, especially for bug fixes,
as my time and resources allow.  But I cannot commit to adding all the
enhancements or special features requested by users.  If you have something
in mind, ask, but I can't guarantee anything.

Although this documentation refers to alleged problems with some
manufacturers' driver software, that should not be construed as a statement
about the quality of their products.  In fact, there is still a possibility
that the problems may be in my handler software or the equipment I used.

My apologies to those people who tried to use version 1.0 and didn't have
a 3M tape drive.  At that time I naively thought that all SCSI tape drives
must look the same, and wrote as though that were true.  Wrongo...
So this version should handle many more types of drives, but there is
no way I can test all the combinations of drives and SCSI adapters.

==============================================================================

DISTRIBUTION:

  The distribution should contain the following files:
    tape-handler          handler binary
    tape.c                source for main handler
    tapeio.c              source for interface to SCSI-direct
    pktstuff.c            source for packet handling, by Phillip Lindsay
    tape.h                local include file
    tplink.h              local include file for handler/monitor structure
    lmkfile               SAS/Lattice make file for handler
    makefile              Manx make file for handler
    tapemon               directory
       tapemon               monitor binary
       tapemon.c             monitor source
       tapemon.doc           documentation for the monitor program
       tapemon.lmk           SAS/Lattice make file for tapemon
    mountlist             example mountlist entry
    changes.doc           a brief history of BTNtape
    tape.doc              you're reading it


COMPATIBILITY:

  You must have a SCSI adapter and software that honors the SCSI-direct
  protocol as defined in the "devices/scsidisk.h" include file.  The list
  below shows the manufacturers I know about that support SCSI-direct
  (but this list I'm sure is incomplete).

  This handler has been tested on the following equipment (but not in
  all the combinations):

    SCSI adapters:
      * Commodore A2091
      * Commodore A590
      * Commodore A3000 (built-in), including DOS 2.0
      * GVP Series II
      * HardFrame
      * Nexus
      * Commodore 2090A- works *if* the hard drive is ST506.
      * Supra 4x4 (Amiga 1000)- works, but see Supra user notes.
      * Trumpcard- with 2.0F software, 4.0 ROMs, Interrupt 2 jumper.

    Tape drives:
      * Archive 2150S (Viper)
      * Teac MT-2ST Cassette
      * Exabyte EXB-8200 8mm Cartridge Tape Subsystem
      * Emulex MT-02 SCSI/QIC-36 tape adapter
      * 3M MCD-40  40MB cartridge tape drive (direct access)

  Even if your hardware is not listed here, there is a good chance it
  will still work if it adheres to the standards (SCSI-direct and SCSI).
  The handler treats a drive as one of two types: sequential or direct access.
  The 3M drive is the only direct access drive I currently know about.
  Everything else is usually sequential.  The handler will adjust itself
  for either type.  If you get it to work with some drive model I haven't
  mentioned here, I would like to hear about it.


INSTALLATION:

  1.  Copy the TAPE-HANDLER file to L:TAPE-HANDLER.
      Copy the TAPEMON program to C: or a directory appropriate for you.

  2.  Create an entry in DEVS:MOUNTLIST something like this:

       TAPE: Handler = L:tape-handler
             Priority = 5         /* use 11 for Supra */
             Mount = 1            /* optional */
             Stacksize = 4000
             GlobVec = -1
             Startup = "yourscsi.device/AA-x/BB-x/..." /* EXPLAINED BELOW */
        #

      There is nothing magic about the name TAPE:   You may use some
      other valid device name if you like.

  3.  Install the handler in DOS using the CLI command "MOUNT TAPE:"
      Do not use the ARP version of MOUNT !!
      If you get a write-protect requester, click Cancel on it
      (this is a side effect of MOUNT- it tries to open TAPE in write mode).

      Unfortunately, if the handler fails due to a mountlist or OpenDevice
      problem, there is no visible error indication- MOUNT still works.
      [does anyone know how I can make MOUNT fail?]
      The device will show up in "ASSIGN LIST", but no handler process exists.
      Type "ASSIGN TAPE: REMOVE", fix the problem, and try again.


THE STARTUP PARAMETER

      The mountlist Startup parameter is used by the handler to determine how
      to access your drive.  FAILURE TO ENTER PROPER INFORMATION IN STARTUP
      MAY RESULT IN PROBLEMS INCLUDING HANGS, VISITS FROM THE GURU,
      OR DATA LOSS.  This is the messiest part of setting up.  Pay attention.

   *NOTE*  The Startup string format has been changed from v1.0
      of the handler.  You must change to the new format.  It is more
      readable, more flexible, and can be more easily expanded in the future.

   *NOTE*  The new Startup string format will NOT work with the
      ARP (AmigaDOS Replacement Project) version of the MOUNT command.
      You MUST use the Commodore version of MOUNT.  To tell the difference,
      ARP 1.3 MOUNT is 2372 bytes long, and CBM MOUNT (1.3.2) is 5604 bytes.
      ARP MOUNT inexplicably truncates Startup at 40 bytes.  There is no need
      to completely abandon ARP- you can still use the CBM MOUNT.
      Just give the two MOUNT commands different names in your C: directory.

      The Startup string must be in the form:

               Startup = "devicename/keywd-num/keywd-num/..."

      It must not have any embedded blanks and must be enclosed in quotes.
      The pieces must be separated by slashes.

      The first parameter must be the name of the device driver which provides
      the SCSI-direct command interface. Do not include any path information.
      This name is defined by the manufacturer of your SCSI adapter.
      (v1.0 users- DO NOT use the old circumvention characters: $ or + ).
      Note letter cases.  The names for the adapters I know about are:

        A3000,A2091,A590 -> scsi.device
        A2090A           -> hddisk.device
        Supra            -> supradirect.device
        GVP              -> gvpscsi.device
        HardFrame        -> HardFrame.device
        Nexus            -> Nexus.device  (NOT NexusTape.device!)
        Trumpcard        -> IVS_SCSI.device
        ICD Advantage    -> icddisk.device

      The name parameter MUST be the first item in the string.  All other
      parameters may be in any order, but the name must be first.

      The remaining items consist of pairs of two-letter keywords and a number
      separated by a dash (minus sign).  The keywords are explained below.
      You may omit any of them (except UNit), and a default value will be
      assumed.  The numbers may be decimal, or hex in the "0xNN" format.

      Keyword-default
      ---------------
      UN       UNit:  The unit number of your tape drive, as it will be
                      addressed by your hard disk driver.  Usually you can
                      just specify the SCSI bus ID, example: "UN-0" for 0.
                      More complex setups may require the form "UN-0xBLI",
                      where B=board#, L=logical unit#, I=SCSI bus ID#.
                      Be sure you have set the drive ID switches or jumpers
                      to a value that is unique on the SCSI bus.
                      2090A owners- add 3 to the ID number.

      LU-0     Logical Unit:  another number that may be required to address
                      your drive.  Most drives are hardwired for 0, so this
                      parameter may be omitted.  It is provided here for the
                      few exceptions that are probably out there.

      BS-512   Block Size: the number of bytes in a SCSI logical block for
                      your tape drive.  Consult your drive documentation.
                      Some drives allow you to specify different
                      block sizes, within a legal range;  the handler will
                      command the drive to use the size you specify.
                      Others can use only one fixed size.  If you can vary
                      the block size, you must use the same size when reading
                      a tape as you did when writing it.

      NB-1     Number of Blocks:  the number of SCSI logical blocks to write
                      or read in each tape operation.  See below.

      BT-0     BufmemType:  the type of memory to allocate for the tape
                      buffers, same as BufMemType for mountlists.  Use
                      0 or 1 for "any", 2 or 3 for "chip", 4 or 5 for "fast".

      FM-1     FileMarks:  specifies number of file marks to write when
                      closing at the end of a write, or the number to skip
                      for each file when opening for read.
                      Allowed range is 0-255.  Sequential drives only.

      VB-0     Variable Block flag:  the handler normally operates sequential
                      drives in fixed block mode.  Specifying VB-1 will force
                      operation in variable block mode instead.  Use this
                      if your drive does not support fixed block mode or
                      you for some reason need variable block mode.

      RB-0     Reserved Blocks:  for direct access drives only.  Sets how
                      many blocks to skip at the beginning of the tape.

      OV-1     OVerlapped I/O Flag:  the handler normally attempts to overlap
                      tape drive I/O and DOS I/O to increase throughput.
                      Specifying OV-0 disables overlapping and double buffering
                      for systems that can't walk and chew gum at the same time.

      DF-0     Device Flags:  equivalent to the Flags parameter in mountlists.
                      It is passed in the OpenDevice() call to open the SCSI-
                      direct driver. If you don't know what you would use
                      this parameter for, then you probably don't need it.

      SU-0     SUpra Flag: activates the circumvention for the Supra 4x4
                      v1.10 problem.  Specify SU-1 to activate this.
                      See below. (Replaces "+" in handler v1.0)

      C9-0     CBM 2090A Flag:  activates the circumvention for the Commodore
                      2090A problem.  Specify C9-1 to activate this.
                      See below. (Replaces "$" in handler v1.0)


      Here are some examples of valid Startup strings:

       Startup = "scsi.device/UN-7"   /* the minimum info required */
       Startup = "scsi.device/BS-0x400/NB-16/LU-3/UN-0x102"
       Startup = "supradirect.device/un-4/bs-8192/nb-8/bt-1/su-1"

      A note about the NB parameter:  Some drives may be mechanically more
      efficient writing multiple blocks.  You may want to tweak this
      parameter to find out.  The handler will wait until NB blocks have been
      accumulated before starting a write.   Buffered drives may also have a
      limit on the number of blocks they can hold at once, so the size of NB
      relative to that number may have an effect.  Consult your drive docs.
      In general, the more blocks the better.
      This parameter also determines how much memory is needed for
      buffers.  The handler uses double buffering, so it will need
      2 * BS * NB bytes when you Open() it.
      For example, if BS=8192 and NB=8, then 8192*8 = 64K,
      for a total of 128K.


2090A USERS- NOTE

     Apparently (I don't own a 2090A) there is a software bug in the
     CBM 2090A SCSI-direct driver that causes problems with tape
     writes.  Bob Mitchell figured out that the problem can be
     circumvented by asserting data address bit 24 for writes.
     This handler can optionally invoke that circumvention.
     To do so, specify "C9-1" in the Startup string.
     The circumvention is NOT necessary for other adapters.

     A worse problem- the 2090A cannot seem to handle both the disk
     and the tape drive on the same SCSI bus.  Simple reads or writes
     to the tape work fine, but intermixed tape reads and disk writes
     (such as during a restore) will cause the 2090A to get confused.
     This does not happen if the hard drive is on the ST506 bus.
     It also does not happen if you restore the files to RAM or floppy.

     Make sure the tape is out of the drive when you boot
     AmigaDOS;  otherwise, DOS never comes up.

     When you mount TAPE:,  make sure there is no cartridge in the
     tape drive.  For some reason I do not understand, the 2090A
     causes a reset to the tape drive when OpenDevice is called.
     If a cartridge is in the drive at that time, the system
     eventually enters an unusable state.  I recommend using
     "Mount = 1" in your MountList entry for TAPE: so when TAPE:
     is mounted, it will put up a requester because the drive is
     empty;  click on cancel, then everything will be happy.


SUPRA USERS- NOTE

     Apparently (I DO own one) there is a problem with the Supra v1.10
     SCSI-direct software that causes the host adapter to hang when a
     non-zero byte count is supplied in the command (SCSICmd.scsi_Length).
     It works fine when a data length of zero is used.  The handler can also
     circumvent this problem.  Specify "SU-1" in the Startup parameter.
     I have reported this to Supra, and they promised to look into it.

     You MUST run the tape handler at a higher priority than the
     Supra driver task.  You do this by changing the "Priority ="
     line in the mountlist entry.  For Supra v1.10, the task runs
     at priority 10.  Therefore, the tape handler should run at
     "Priority = 11".  If some other Supra version runs at a different
     priority, change the mountlist priority accordingly.
     Use a utility such as Xoper or TaskX to find task priorities.

     If the cartridge is in the drive at the time you boot AmigaDOS,
     SupraMount will hang the system if it touches the tape drive.
     To avoid this, use the selective mount feature of SupraMount
     to mount only your disk unit.  Example: "SupraMount 6".


HOW TO ACCESS TAPE DATA

     Now that the handler is installed, how do you talk to it?
     You can use TAR, or your own application program, including ARexx.
     You can write data to the tape and later read it back in a manner
     similar to other files, using DOS calls to Open, Read, Write, and Close.

     The handler makes the tape data look like a sequential AmigaDOS file.
     There is NO FILE SYSTEM on the tape, but you may place multiple files
     on a tape by positioning the tape to specific file marks or blocks.
     The handler does not support mixed reads and writes.  That is, you may
     do only Reads or only Writes, but not both.  Seeks are not allowed.
     You cannot Open the tape in "append" mode.

     Tape data is written in quantities of "NB*BS" bytes.  No information
     about the exact length of the file is written.  If a tape file
     ends before filling a block, the remainder of the block is filled with
     zeroes.  Therefore, any program reading the tape must know when to
     stop reading data, otherwise it will read extraneous zeroes past
     true end of the file.  For instance, this will not work, because the
     second copy won't know the size of the file it is copying:
        COPY filename TAPE:
        COPY TAPE: newfile    ; will read too much data

     TAR works because it essentially writes and interprets the tape data
     as its own little file system that includes the length of each file.

     When a tape file is closed in write mode, one or more filemarks
     (as determined by "FM") are written at the end of the file to
     delineate the file from subsequent files. (Sequential drives only).

     If there is no tape in the drive at the time TAPE: is
     opened, DOS will put up a requester asking for volume "TAPE"
     "in any drive".  Insert the tape (in the tape drive, not
     a floppy drive :-)  and click on retry after tape motion stops.

     Refer to the tape with one of the following file name forms:

     TAPE:     Rewinds and opens the tape at the first available block.

     TAPE:*    Opens the tape at the current position, without rewinding.

     TAPE:num  Opens the tape at the position specified by the number.
        For sequential drives, the number indicates the file position.
        The 0th file is at the beginning of the tape, file 1 follows it,
        etc.  Note, the files must have been previously written on the tape.
        Files are separated by one or more filemarks as specified by the
        FM startup parameter.  For the 3M direct access drive, the number
        specifies an absolute SCSI block number on the tape.  You must
        remember (write down) the block number of the beginning of each
        file on the tape, as reported by TAPEMON.

     TAPE:RAWCMD   A special mode for issuing a raw SCSI command, not for
        accessing the tape medium.  See "RAW COMMAND INTERFACE" below.

     TAPE:MODESEL  A special mode for writing mode-select data, not for
        accessing the tape medium.  See "USER-SPECIFIED MODE SELECT" below.


A QUICK FUNCTIONALITY TEST

     Before jumping into disk backups and restores, try the following
     simple test to see if your setup is basically working.
     Write a large ASCII text file, such as TAPE.DOC, to the tape
     and see if you can read it back intact.  This can be done with the
     CLI TYPE command:

             TYPE tape.doc TO TAPE:     ; writes the file to tape
     then... TYPE TAPE:                 ; reads the file back

     The second TYPE should legibly print the ASCII file on your screen.
     When you have seen enough, use control-C to abort it.


USING TAR FOR BACKUPS AND RESTORES

     For backups, I use the version of TAR ported by Jonathan Hue.
     It is 33860 bytes long.   Each TAR archive is written to the tape
     as a single file, terminated by a file mark (on sequential drives).
     NOTE: the version of TAR distributed with Amiga UUCP apparently
     does NOT work with BTNtape.  I don't know why.   Other similar
     programs, like PAX, may also work, but I haven't tried them.

     TAR will backup all directories, files, and subdirectories in the
     directory you specify, including the date, protection, and filenote
     attributes.  The easiest way to do a backup is to CD to the desired
     directory or partition (e.g. "cd DH0:"), then...

     To make a backup archive with TAR  :   tar -cv -f tape: ""
         (note the null string)
     To add another archive file        :   tar -cv -f tape:* ""
     To restore files from archive      :   tar -xv -f tape: *
     To restore a specific file         :   tar -xv -f tape: path/filename
     To restore from archive at file 6  :   tar -xv -f tape:6 *
     To list the archive on the tape    :   tar -t  -f tape:
      (this also tests archive integrity)
     To make an archive log             :   tar >logfile -t -f tape:
     To look at raw tape data           :   type tape: opt h  ... cntl-C

     TAR can also make backups using a list of files from another file.
     When you restore an individual file from an archive, provide the
     exact path and file name;  these names are case sensitive.
     Refer to the TAR documentation for more information.


END-OF-TAPE HANDLING

     If the application reaches the end of the tape, the handler will put up
     a requester asking you to insert the next tape and click "Continue",
     or click "Abort".  The continue option allows the application program
     to access a file across multiple tape volumes without interruption.
     WAIT FOR TAPE MOTION TO STOP on the new tape before clicking Continue.
     If you click Abort, an I/O error is returned to the application.

  *NOTE*  EOT handling is invoked when any of the blocks in the group of "NB"
     blocks gets an EOM or Volume Overflow error.  When you click Continue,
     the entire group of blocks is rewritten/reread on the new tape.
     Therefore, to use the multiple-volume capability of the handler, you must
     use the same blocking factor (value of NB) when reading the tape as
     when it was written.

  *NOTE*  EOT handling for the 3M drive will work only if the ROM version
     supports the READ_CAPACITY SCSI command.  If you see no "Capacity"
     message from TAPEMON, then EOT handling is unavailable.


ERROR HANDLING

     This version of the handler does not deal with tape errors.  If the
     drive detects a medium error, the current operation will be aborted
     by returning -1 for Read() or Write().  Some drives insulate the
     user from bad blocks by automatically correcting them or remapping
     to a good block, but other drives may not do this.


3M DRIVE USERS- NOTE

     The following applies only to the 3M MCD-40 direct access drive.

     The 3M drive does not use file marks.  When you reference the
     tape as "TAPE:num", num is the SCSI block number, not the file number.
     When writing multiple files to a tape, you should write down the
     block numbers where each file starts (unless you have a good memory).
     Use the TAPEMON program to see the block numbers.

     The RB parameter in Startup may be used to skip over a number of
     blocks at the beginning of the tape, if there is something there
     (like volume information) you wish to preserve.

     Be sure your cartridge is formatted.  If you try to use an
     unformatted tape, results will be non-optimal.  You can buy
     preformatted tapes, or you can format your own- see the section on
     raw commands below. Cartridges may be formatted with an interleave
     factor. Interleave is the number of physical blocks separating adjacent
     logical blocks.  The 3M unit defaults to interleave 2, but I find
     for my Supra that 3 improves performance slightly.

     The raw command to format a tape is:  04 80 20 00 00 80
     which denotes the format command, immediate completion, precondition
     the tape, default interleave, and retry on errors.

     A note about the hardware.  If you haven't noticed it yet, the
     3M drive is EXTREMELY sensitive to electrical noise.  It is
     *essenstial* that the drive be properly grounded.  The ground
     in the power connector is insufficient.  You should run a thick
     wire or braided strap from the metal side-plate to a good ground,
     preferrably the power supply ground.  I'm not kidding.


HELPFUL HINTS:

     Label your tapes.  Include the file number or block number
     of each file on a multi-file tape.

     Try backing up and restoring a floppy before doing the
     same with your hard drive, to make sure the process works for you.
     For the same reason, make a HD backup to floppies first.  Then
     if the tape restore fails, you have something to fall back on.

     This is obvious, right?  Make sure you have a copy of the handler and
     TAR on an easily-accessible floppy.  If the only copy you have is
     on your hard drive, you might find it difficult to restore
     from a tape backup after a disk wipe-out.


THE MONITOR PROGRAM

     Included in with the handler is the TAPEMON program.  TAPEMON is
     a program that runs under a separate CLI and prints one-liner
     messages from the handler.  The messages include the current
     tape operation and block number, and error and sense codes.
     The handler will run with or without TAPEMON; i.e. TAPEMON is optional.
     TAPEMON must be started up AFTER the handler is mounted and activated.
     Read TAPEMON.DOC for more information.


RAW COMMAND INTERFACE

     This handler provides a means to send your own SCSI control commands
     to the tape drive, without the need for a special program.
     Some control commands you might want to send it would be REWIND,
     UNLOAD, ERASE, FORMAT, LOCK, etc.  Only control commands may be sent-
     there is no provision for any data transfer; don't try it.
     (As you might guess, raw commands can be dangerous.)

     The raw command mode is invoked by writing data to the file name
     "TAPE:RAWCMD".  (v1.0 users- the dollar signs are no longer used).
     This magic word is how the handler knows you want to do a raw command.

     There are two ways to send data via RAWCMD using CLI commands:
        1) use the ECHO command:     ECHO >TAPE:RAWCMD "hex command bytes..."
        2) use the TYPE command:     TYPE filename TO TAPE:RAWCMD

     The ECHO command is useful to place in a script or create an alias
     for the command.  You may also place the data in a file and use TYPE;
     line 1 of the file contains the bytes to be sent as the raw command.

     The exact value of the data bytes is determined by the byte format of
     the SCSI command you want to send. (Refer to your drive documentation.)
     The data must contain ONLY hex digits and spaces terminated, by a newline.
     Each byte of the raw command should be specified as a pair of hex
     digits;  separate bytes by spaces.  Up to 10 bytes may be specified.
     The data for TYPE must be on the first line of the file.
     You can use any following lines as comments, but the total size of
     the file must be less than the size of BS*NB.

     Command examples:
        Rewind:     01 00 00 00 00 00
        Erase:      19 00 00 00 00 00
        Lock:       1E 00 00 00 01 00


USER-SPECIFIED MODE SELECT

     In recognition of the fact that it will never be able to provide
     switches for all possible modes of all tape drives, BTNtape
     allows you to set the modes of the drive directly.
     These modes might include:  buffering, speed, auto-loading,
     enable disconnect, medium type, etc.

   *NOTE* Do not use this feature unless you know what you are doing.
     This feature is provided for the convenience of "power users".
     Most drives can get by with defaults if you do not set the modes,
     so it is unlikely that not setting a mode will cause problems.

     Drive modes are set using the SCSI command MODE_SELECT (0x15).
     BTNtape will send its own MODE_SELECT to the drive if necessary
     to set the drive to fixed block mode and set the block length.
     But you may also send this command to the drive at other times,
     using any data you wish.

     The command is sent in a manner very similar to the RAWCMD
     method described above, but the magic word MODESEL is
     used instead.  The handler provides the SCSI command,
     and you provide the data.  The data is specified as pairs of
     hex digits separated by spaces, in a file for TYPE, or directly
     in an ECHO command.

            ECHO >TAPE:MODESEL "hex data bytes..."
       or   TYPE filename TO TAPE:MODESEL

     Since each drive has different things that are affected by MODE_SELECT,
     you MUST refer to the programming documentation for your drive.
     But in general, the mode select data consists of a parameter
     list, a block descriptor, and vendor unique parameters.
    *NOTE*  If you specify a block descriptor, it will behoove you to
     specify the same block length as specified in the mountlist entry
     when using fixed block mode, or zero if using variable block mode.

     The handler counts the number of bytes you specify (up to 64),
     and uses that for the SCSI command data length.  The drive may
     be fussy about the length, so specify exactly the number of bytes
     as described in your docs.

     Mode Select data example:

       --parmlist-   ----block-descriptor---   vendorparms
       00 10 00 08   03 00 00 00 00 00 04 00   11 22 33 44
          |     |    |                 || ||
  Buff mode  BD Len  Density         Blk Len


FINE TUNING

     There are a few factors you can tweak to get good performance
     on your particular system.  Good performance means the tape tends
     to run continuously for long periods of time and seldom has
     to stop and back up to get a running start at the next block.
     The tape may have to stop while TAR gets more data from the
     hard disk, but you can minimize it.

     The handler's NB parameter can be increased from 1 to
     some larger number as your memory allows.  With more handler
     blocks, a large quantity of data is available to dump to the tape,
     but there is probably a point of diminishing return.

     The TAR program also has a block parameter.  It controls how much
     DOS data TAR collects before sending it to the handler.  If you
     use many TAR blocks, it makes no sense to also use many handler
     blocks,  since the data has to go through both buffers
     anyway.  You can increase the TAR blocks if your SCSI-
     direct driver does not support multi-block operations.

     Using the TAPEMON program may slow down the handler slightly
     when it prints messages, but it's not really a problem.
     If you absolutely need maximum throughput, shut down TAPEMON.


HOW IT WORKS

     Two buffers are maintained so that one buffer can be used by DOS
     while the other is exchanging data with the drive.  With the
     multitasking nature of the Amiga, this should help keep the tape
     in motion, but it may not help much with non-DMA SCSI adapters.

     In write mode, the handler collects DOS data in one buffer while
     the previously filled buffer is being written to tape.  In read mode,
     the handler reads ahead on the tape to fill one buffer while
     DOS gets data from the previously read buffer.

     The handler does not write (or expect) anything special on
     the tape for itself.  That is to say, the data written on the
     tape is your raw data, nothing else.  If I were to use parts
     of the tape for file system information, I would be
     introducing a sort of standard-- I don't think that is a good
     idea right now.  Raw data provides a lowest common denominator
     which should help compatibility with other things.  For instance,
     a TAR tape created on a non-Amiga system is readable using
     this handler and Amiga TAR.


BUGS

     The variable block mode of operation (VB-1) has not been tested.

     The handler has not been tested with AmigaDOS 1.2.

     The handler does not multi-task well, but I believe that to be
     a characteristic of the SCSI-direct drivers, not the handler.
     Don't expect to do much else while a backup is in progress.
     In fact, other things going on can reduce tape drive performance.


AUTHOR:

  Email:  [e-mail]   OR   ...!sun!portal!cup.portal.com!DrBob

  USmail: Robert Rethemeyer
          979-4 Belmont Terrace
          Sunnyvale, CA  94086
          USA

  If you want to contact me about a problem, please try to include
  with your mail the following:
      *  a copy of your mountlist entry for TAPE:
      *  a capture of the output from TAPEMON.  Just redirect its
             output to a file:     TAPEMON >filename
      *  a verbal description of what happens to the drive and/or Amiga
             (e.g.  tape doesn't move, smoke issues from Amiga, etc.)
      *  any other info that may help me figure out what's going on.
          Remember, I'm not there to see what is happening, and I
          probably don't have your drive model available to recreate
          the problem.  I have only your description to go by.


MANY THANKS GO TO:

  Bob Mitchell for the SCSI-direct programs I used to get started,
    and the 2090A circumvention.
  Beta testers Bill Seymour, Don Phillips, Steve Goldstein,
     Dick Wood, Don Camp, George Armhold, Gary Walborn.
  Phillip Lindsay for the my.handler example code.
  Rene' Vega for advice and Manxification.