home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 498b.lha / BTNtape_v2.0 / tape.doc.pp / tape.doc
Text File  |  1991-04-08  |  35KB  |  718 lines

  1. ****    BTNtape:  an AmigaDOS handler for SCSI tape drives
  2. ****       Version 2.0   3/28/91
  3. ****       Freeware by Bob Rethemeyer   (DrBob@cup.portal.com)
  4. ****
  5. ****    (c) Copyright 1990, 1991  Robert Rethemeyer.
  6. ****      This software may be freely distributed and redistributed,
  7. ****      for non-commercial purposes, provided this notice is included.
  8. ****      All original files must be included in the distribution.
  9.  
  10. BTNtape is a "Better Than Nothing" SCSI tape device handler.  It provides
  11. flat-file access to a SCSI tape drive from application programs using
  12. simple DOS calls to Read() and Write().  It can also be used with the Amiga
  13. TAR utility for disk backups.  It requires a "SCSI-direct" compatible
  14. SCSI bus adapter.  This is version 2.0, update to version 1.0.  It now
  15. supports many more tape drives, and includes some new features.
  16.  
  17. Some advantages of BTN over other handlers and dedicated tape backup programs:
  18.   * Includes a monitor program that keeps you informed of what's happening
  19.   * Supports many standard SCSI tape drives and Amiga SCSI bus adapters
  20.   * Supports the 3M MCD-40, a non-standard SCSI tape drive
  21.   * Supports any size of tape block, and multiple-block accesses
  22.   * Supports tape files that span multiple tape volumes
  23.   * Double buffering improves streaming performance
  24.   * Includes an interface to send SCSI control commands to the drive
  25.   * Includes an interface to set drive-specific Mode Select parameters
  26.   * TAR tapes can be exchanged with Un*x systems
  27.  
  28. =================== ******> R E A D   T H I S <****** ======================
  29.  
  30. DISCLAIMER:
  31.  "This software is provided 'as-is', without warranty of any kind,
  32. either expressed or implied.  In no event will I, Robert Rethemeyer,
  33. be liable for direct, indirect, incidental or consequential damages or
  34. data loss resulting from the use or application of this software.  The entire
  35. risk as to the results and performance of this software is assumed by you."
  36.  
  37. I cannot guarantee that this software is compatible with any combinations
  38. of drives or adapters other than those I have specifically tested.
  39.  
  40. If you do not agree with this disclaimer,  I recommend you not use this
  41. software;  wait for commercial tape drivers.
  42.  
  43. ============================================================================
  44.  
  45. This handler is probably not the all-purpose tape driver you have been waiting
  46. for.  It won't work with any backup program which requires Exec devices.
  47. I claim only that it works with the Amiga TAR program ported by Jonathan Hue.
  48. But until we see good commercial or shareware tape software, you might
  49. find this handler to be "better than nothing".
  50.  
  51. I will try to provide support for this handler, especially for bug fixes,
  52. as my time and resources allow.  But I cannot commit to adding all the
  53. enhancements or special features requested by users.  If you have something
  54. in mind, ask, but I can't guarantee anything.
  55.  
  56. Although this documentation refers to alleged problems with some
  57. manufacturers' driver software, that should not be construed as a statement
  58. about the quality of their products.  In fact, there is still a possibility
  59. that the problems may be in my handler software or the equipment I used.
  60.  
  61. My apologies to those people who tried to use version 1.0 and didn't have
  62. a 3M tape drive.  At that time I naively thought that all SCSI tape drives
  63. must look the same, and wrote as though that were true.  Wrongo...
  64. So this version should handle many more types of drives, but there is
  65. no way I can test all the combinations of drives and SCSI adapters.
  66.  
  67. ==============================================================================
  68.  
  69. DISTRIBUTION:
  70.  
  71.   The distribution should contain the following files:
  72.     tape-handler          handler binary
  73.     tape.c                source for main handler
  74.     tapeio.c              source for interface to SCSI-direct
  75.     pktstuff.c            source for packet handling, by Phillip Lindsay
  76.     tape.h                local include file
  77.     tplink.h              local include file for handler/monitor structure
  78.     lmkfile               SAS/Lattice make file for handler
  79.     makefile              Manx make file for handler
  80.     tapemon               directory
  81.        tapemon               monitor binary
  82.        tapemon.c             monitor source
  83.        tapemon.doc           documentation for the monitor program
  84.        tapemon.lmk           SAS/Lattice make file for tapemon
  85.     mountlist             example mountlist entry
  86.     changes.doc           a brief history of BTNtape
  87.     tape.doc              you're reading it
  88.  
  89.  
  90. COMPATIBILITY:
  91.  
  92.   You must have a SCSI adapter and software that honors the SCSI-direct
  93.   protocol as defined in the "devices/scsidisk.h" include file.  The list
  94.   below shows the manufacturers I know about that support SCSI-direct
  95.   (but this list I'm sure is incomplete).
  96.  
  97.   This handler has been tested on the following equipment (but not in
  98.   all the combinations):
  99.  
  100.     SCSI adapters:
  101.       * Commodore A2091
  102.       * Commodore A590
  103.       * Commodore A3000 (built-in), including DOS 2.0
  104.       * GVP Series II
  105.       * HardFrame
  106.       * Nexus
  107.       * Commodore 2090A- works *if* the hard drive is ST506.
  108.       * Supra 4x4 (Amiga 1000)- works, but see Supra user notes.
  109.       * Trumpcard- with 2.0F software, 4.0 ROMs, Interrupt 2 jumper.
  110.  
  111.     Tape drives:
  112.       * Archive 2150S (Viper)
  113.       * Teac MT-2ST Cassette
  114.       * Exabyte EXB-8200 8mm Cartridge Tape Subsystem
  115.       * Emulex MT-02 SCSI/QIC-36 tape adapter
  116.       * 3M MCD-40  40MB cartridge tape drive (direct access)
  117.  
  118.   Even if your hardware is not listed here, there is a good chance it
  119.   will still work if it adheres to the standards (SCSI-direct and SCSI).
  120.   The handler treats a drive as one of two types: sequential or direct access.
  121.   The 3M drive is the only direct access drive I currently know about.
  122.   Everything else is usually sequential.  The handler will adjust itself
  123.   for either type.  If you get it to work with some drive model I haven't
  124.   mentioned here, I would like to hear about it.
  125.  
  126.  
  127. INSTALLATION:
  128.  
  129.   1.  Copy the TAPE-HANDLER file to L:TAPE-HANDLER.
  130.       Copy the TAPEMON program to C: or a directory appropriate for you.
  131.  
  132.   2.  Create an entry in DEVS:MOUNTLIST something like this:
  133.  
  134.        TAPE: Handler = L:tape-handler
  135.              Priority = 5         /* use 11 for Supra */
  136.              Mount = 1            /* optional */
  137.              Stacksize = 4000
  138.              GlobVec = -1
  139.              Startup = "yourscsi.device/AA-x/BB-x/..." /* EXPLAINED BELOW */
  140.         #
  141.  
  142.       There is nothing magic about the name TAPE:   You may use some
  143.       other valid device name if you like.
  144.  
  145.   3.  Install the handler in DOS using the CLI command "MOUNT TAPE:"
  146.       Do not use the ARP version of MOUNT !!
  147.       If you get a write-protect requester, click Cancel on it
  148.       (this is a side effect of MOUNT- it tries to open TAPE in write mode).
  149.  
  150.       Unfortunately, if the handler fails due to a mountlist or OpenDevice
  151.       problem, there is no visible error indication- MOUNT still works.
  152.       [does anyone know how I can make MOUNT fail?]
  153.       The device will show up in "ASSIGN LIST", but no handler process exists.
  154.       Type "ASSIGN TAPE: REMOVE", fix the problem, and try again.
  155.  
  156.  
  157. THE STARTUP PARAMETER
  158.  
  159.       The mountlist Startup parameter is used by the handler to determine how
  160.       to access your drive.  FAILURE TO ENTER PROPER INFORMATION IN STARTUP
  161.       MAY RESULT IN PROBLEMS INCLUDING HANGS, VISITS FROM THE GURU,
  162.       OR DATA LOSS.  This is the messiest part of setting up.  Pay attention.
  163.  
  164.    *NOTE*  The Startup string format has been changed from v1.0
  165.       of the handler.  You must change to the new format.  It is more
  166.       readable, more flexible, and can be more easily expanded in the future.
  167.  
  168.    *NOTE*  The new Startup string format will NOT work with the
  169.       ARP (AmigaDOS Replacement Project) version of the MOUNT command.
  170.       You MUST use the Commodore version of MOUNT.  To tell the difference,
  171.       ARP 1.3 MOUNT is 2372 bytes long, and CBM MOUNT (1.3.2) is 5604 bytes.
  172.       ARP MOUNT inexplicably truncates Startup at 40 bytes.  There is no need
  173.       to completely abandon ARP- you can still use the CBM MOUNT.
  174.       Just give the two MOUNT commands different names in your C: directory.
  175.  
  176.       The Startup string must be in the form:
  177.  
  178.                Startup = "devicename/keywd-num/keywd-num/..."
  179.  
  180.       It must not have any embedded blanks and must be enclosed in quotes.
  181.       The pieces must be separated by slashes.
  182.  
  183.       The first parameter must be the name of the device driver which provides
  184.       the SCSI-direct command interface. Do not include any path information.
  185.       This name is defined by the manufacturer of your SCSI adapter.
  186.       (v1.0 users- DO NOT use the old circumvention characters: $ or + ).
  187.       Note letter cases.  The names for the adapters I know about are:
  188.  
  189.         A3000,A2091,A590 -> scsi.device
  190.         A2090A           -> hddisk.device
  191.         Supra            -> supradirect.device
  192.         GVP              -> gvpscsi.device
  193.         HardFrame        -> HardFrame.device
  194.         Nexus            -> Nexus.device  (NOT NexusTape.device!)
  195.         Trumpcard        -> IVS_SCSI.device
  196.         ICD Advantage    -> icddisk.device
  197.  
  198.       The name parameter MUST be the first item in the string.  All other
  199.       parameters may be in any order, but the name must be first.
  200.  
  201.       The remaining items consist of pairs of two-letter keywords and a number
  202.       separated by a dash (minus sign).  The keywords are explained below.
  203.       You may omit any of them (except UNit), and a default value will be
  204.       assumed.  The numbers may be decimal, or hex in the "0xNN" format.
  205.  
  206.       Keyword-default
  207.       ---------------
  208.       UN       UNit:  The unit number of your tape drive, as it will be
  209.                       addressed by your hard disk driver.  Usually you can
  210.                       just specify the SCSI bus ID, example: "UN-0" for 0.
  211.                       More complex setups may require the form "UN-0xBLI",
  212.                       where B=board#, L=logical unit#, I=SCSI bus ID#.
  213.                       Be sure you have set the drive ID switches or jumpers
  214.                       to a value that is unique on the SCSI bus.
  215.                       2090A owners- add 3 to the ID number.
  216.  
  217.       LU-0     Logical Unit:  another number that may be required to address
  218.                       your drive.  Most drives are hardwired for 0, so this
  219.                       parameter may be omitted.  It is provided here for the
  220.                       few exceptions that are probably out there.
  221.  
  222.       BS-512   Block Size: the number of bytes in a SCSI logical block for
  223.                       your tape drive.  Consult your drive documentation.
  224.                       Some drives allow you to specify different
  225.                       block sizes, within a legal range;  the handler will
  226.                       command the drive to use the size you specify.
  227.                       Others can use only one fixed size.  If you can vary
  228.                       the block size, you must use the same size when reading
  229.                       a tape as you did when writing it.
  230.  
  231.       NB-1     Number of Blocks:  the number of SCSI logical blocks to write
  232.                       or read in each tape operation.  See below.
  233.  
  234.       BT-0     BufmemType:  the type of memory to allocate for the tape
  235.                       buffers, same as BufMemType for mountlists.  Use
  236.                       0 or 1 for "any", 2 or 3 for "chip", 4 or 5 for "fast".
  237.  
  238.       FM-1     FileMarks:  specifies number of file marks to write when
  239.                       closing at the end of a write, or the number to skip
  240.                       for each file when opening for read.
  241.                       Allowed range is 0-255.  Sequential drives only.
  242.  
  243.       VB-0     Variable Block flag:  the handler normally operates sequential
  244.                       drives in fixed block mode.  Specifying VB-1 will force
  245.                       operation in variable block mode instead.  Use this
  246.                       if your drive does not support fixed block mode or
  247.                       you for some reason need variable block mode.
  248.  
  249.       RB-0     Reserved Blocks:  for direct access drives only.  Sets how
  250.                       many blocks to skip at the beginning of the tape.
  251.  
  252.       OV-1     OVerlapped I/O Flag:  the handler normally attempts to overlap
  253.                       tape drive I/O and DOS I/O to increase throughput.
  254.                       Specifying OV-0 disables overlapping and double buffering
  255.                       for systems that can't walk and chew gum at the same time.
  256.  
  257.       DF-0     Device Flags:  equivalent to the Flags parameter in mountlists.
  258.                       It is passed in the OpenDevice() call to open the SCSI-
  259.                       direct driver. If you don't know what you would use
  260.                       this parameter for, then you probably don't need it.
  261.  
  262.       SU-0     SUpra Flag: activates the circumvention for the Supra 4x4
  263.                       v1.10 problem.  Specify SU-1 to activate this.
  264.                       See below. (Replaces "+" in handler v1.0)
  265.  
  266.       C9-0     CBM 2090A Flag:  activates the circumvention for the Commodore
  267.                       2090A problem.  Specify C9-1 to activate this.
  268.                       See below. (Replaces "$" in handler v1.0)
  269.  
  270.  
  271.       Here are some examples of valid Startup strings:
  272.  
  273.        Startup = "scsi.device/UN-7"   /* the minimum info required */
  274.        Startup = "scsi.device/BS-0x400/NB-16/LU-3/UN-0x102"
  275.        Startup = "supradirect.device/un-4/bs-8192/nb-8/bt-1/su-1"
  276.  
  277.       A note about the NB parameter:  Some drives may be mechanically more
  278.       efficient writing multiple blocks.  You may want to tweak this
  279.       parameter to find out.  The handler will wait until NB blocks have been
  280.       accumulated before starting a write.   Buffered drives may also have a
  281.       limit on the number of blocks they can hold at once, so the size of NB
  282.       relative to that number may have an effect.  Consult your drive docs.
  283.       In general, the more blocks the better.
  284.       This parameter also determines how much memory is needed for
  285.       buffers.  The handler uses double buffering, so it will need
  286.       2 * BS * NB bytes when you Open() it.
  287.       For example, if BS=8192 and NB=8, then 8192*8 = 64K,
  288.       for a total of 128K.
  289.  
  290.  
  291. 2090A USERS- NOTE
  292.  
  293.      Apparently (I don't own a 2090A) there is a software bug in the
  294.      CBM 2090A SCSI-direct driver that causes problems with tape
  295.      writes.  Bob Mitchell figured out that the problem can be
  296.      circumvented by asserting data address bit 24 for writes.
  297.      This handler can optionally invoke that circumvention.
  298.      To do so, specify "C9-1" in the Startup string.
  299.      The circumvention is NOT necessary for other adapters.
  300.  
  301.      A worse problem- the 2090A cannot seem to handle both the disk
  302.      and the tape drive on the same SCSI bus.  Simple reads or writes
  303.      to the tape work fine, but intermixed tape reads and disk writes
  304.      (such as during a restore) will cause the 2090A to get confused.
  305.      This does not happen if the hard drive is on the ST506 bus.
  306.      It also does not happen if you restore the files to RAM or floppy.
  307.  
  308.      Make sure the tape is out of the drive when you boot
  309.      AmigaDOS;  otherwise, DOS never comes up.
  310.  
  311.      When you mount TAPE:,  make sure there is no cartridge in the
  312.      tape drive.  For some reason I do not understand, the 2090A
  313.      causes a reset to the tape drive when OpenDevice is called.
  314.      If a cartridge is in the drive at that time, the system
  315.      eventually enters an unusable state.  I recommend using
  316.      "Mount = 1" in your MountList entry for TAPE: so when TAPE:
  317.      is mounted, it will put up a requester because the drive is
  318.      empty;  click on cancel, then everything will be happy.
  319.  
  320.  
  321. SUPRA USERS- NOTE
  322.  
  323.      Apparently (I DO own one) there is a problem with the Supra v1.10
  324.      SCSI-direct software that causes the host adapter to hang when a
  325.      non-zero byte count is supplied in the command (SCSICmd.scsi_Length).
  326.      It works fine when a data length of zero is used.  The handler can also
  327.      circumvent this problem.  Specify "SU-1" in the Startup parameter.
  328.      I have reported this to Supra, and they promised to look into it.
  329.  
  330.      You MUST run the tape handler at a higher priority than the
  331.      Supra driver task.  You do this by changing the "Priority ="
  332.      line in the mountlist entry.  For Supra v1.10, the task runs
  333.      at priority 10.  Therefore, the tape handler should run at
  334.      "Priority = 11".  If some other Supra version runs at a different
  335.      priority, change the mountlist priority accordingly.
  336.      Use a utility such as Xoper or TaskX to find task priorities.
  337.  
  338.      If the cartridge is in the drive at the time you boot AmigaDOS,
  339.      SupraMount will hang the system if it touches the tape drive.
  340.      To avoid this, use the selective mount feature of SupraMount
  341.      to mount only your disk unit.  Example: "SupraMount 6".
  342.  
  343.  
  344. HOW TO ACCESS TAPE DATA
  345.  
  346.      Now that the handler is installed, how do you talk to it?
  347.      You can use TAR, or your own application program, including ARexx.
  348.      You can write data to the tape and later read it back in a manner
  349.      similar to other files, using DOS calls to Open, Read, Write, and Close.
  350.  
  351.      The handler makes the tape data look like a sequential AmigaDOS file.
  352.      There is NO FILE SYSTEM on the tape, but you may place multiple files
  353.      on a tape by positioning the tape to specific file marks or blocks.
  354.      The handler does not support mixed reads and writes.  That is, you may
  355.      do only Reads or only Writes, but not both.  Seeks are not allowed.
  356.      You cannot Open the tape in "append" mode.
  357.  
  358.      Tape data is written in quantities of "NB*BS" bytes.  No information
  359.      about the exact length of the file is written.  If a tape file
  360.      ends before filling a block, the remainder of the block is filled with
  361.      zeroes.  Therefore, any program reading the tape must know when to
  362.      stop reading data, otherwise it will read extraneous zeroes past
  363.      true end of the file.  For instance, this will not work, because the
  364.      second copy won't know the size of the file it is copying:
  365.         COPY filename TAPE:
  366.         COPY TAPE: newfile    ; will read too much data
  367.  
  368.      TAR works because it essentially writes and interprets the tape data
  369.      as its own little file system that includes the length of each file.
  370.  
  371.      When a tape file is closed in write mode, one or more filemarks
  372.      (as determined by "FM") are written at the end of the file to
  373.      delineate the file from subsequent files. (Sequential drives only).
  374.  
  375.      If there is no tape in the drive at the time TAPE: is
  376.      opened, DOS will put up a requester asking for volume "TAPE"
  377.      "in any drive".  Insert the tape (in the tape drive, not
  378.      a floppy drive :-)  and click on retry after tape motion stops.
  379.  
  380.      Refer to the tape with one of the following file name forms:
  381.  
  382.      TAPE:     Rewinds and opens the tape at the first available block.
  383.  
  384.      TAPE:*    Opens the tape at the current position, without rewinding.
  385.  
  386.      TAPE:num  Opens the tape at the position specified by the number.
  387.         For sequential drives, the number indicates the file position.
  388.         The 0th file is at the beginning of the tape, file 1 follows it,
  389.         etc.  Note, the files must have been previously written on the tape.
  390.         Files are separated by one or more filemarks as specified by the
  391.         FM startup parameter.  For the 3M direct access drive, the number
  392.         specifies an absolute SCSI block number on the tape.  You must
  393.         remember (write down) the block number of the beginning of each
  394.         file on the tape, as reported by TAPEMON.
  395.  
  396.      TAPE:RAWCMD   A special mode for issuing a raw SCSI command, not for
  397.         accessing the tape medium.  See "RAW COMMAND INTERFACE" below.
  398.  
  399.      TAPE:MODESEL  A special mode for writing mode-select data, not for
  400.         accessing the tape medium.  See "USER-SPECIFIED MODE SELECT" below.
  401.  
  402.  
  403. A QUICK FUNCTIONALITY TEST
  404.  
  405.      Before jumping into disk backups and restores, try the following
  406.      simple test to see if your setup is basically working.
  407.      Write a large ASCII text file, such as TAPE.DOC, to the tape
  408.      and see if you can read it back intact.  This can be done with the
  409.      CLI TYPE command:
  410.  
  411.              TYPE tape.doc TO TAPE:     ; writes the file to tape
  412.      then... TYPE TAPE:                 ; reads the file back
  413.  
  414.      The second TYPE should legibly print the ASCII file on your screen.
  415.      When you have seen enough, use control-C to abort it.
  416.  
  417.  
  418. USING TAR FOR BACKUPS AND RESTORES
  419.  
  420.      For backups, I use the version of TAR ported by Jonathan Hue.
  421.      It is 33860 bytes long.   Each TAR archive is written to the tape
  422.      as a single file, terminated by a file mark (on sequential drives).
  423.      NOTE: the version of TAR distributed with Amiga UUCP apparently
  424.      does NOT work with BTNtape.  I don't know why.   Other similar
  425.      programs, like PAX, may also work, but I haven't tried them.
  426.  
  427.      TAR will backup all directories, files, and subdirectories in the
  428.      directory you specify, including the date, protection, and filenote
  429.      attributes.  The easiest way to do a backup is to CD to the desired
  430.      directory or partition (e.g. "cd DH0:"), then...
  431.  
  432.      To make a backup archive with TAR  :   tar -cv -f tape: ""
  433.          (note the null string)
  434.      To add another archive file        :   tar -cv -f tape:* ""
  435.      To restore files from archive      :   tar -xv -f tape: *
  436.      To restore a specific file         :   tar -xv -f tape: path/filename
  437.      To restore from archive at file 6  :   tar -xv -f tape:6 *
  438.      To list the archive on the tape    :   tar -t  -f tape:
  439.       (this also tests archive integrity)
  440.      To make an archive log             :   tar >logfile -t -f tape:
  441.      To look at raw tape data           :   type tape: opt h  ... cntl-C
  442.  
  443.      TAR can also make backups using a list of files from another file.
  444.      When you restore an individual file from an archive, provide the
  445.      exact path and file name;  these names are case sensitive.
  446.      Refer to the TAR documentation for more information.
  447.  
  448.  
  449. END-OF-TAPE HANDLING
  450.  
  451.      If the application reaches the end of the tape, the handler will put up
  452.      a requester asking you to insert the next tape and click "Continue",
  453.      or click "Abort".  The continue option allows the application program
  454.      to access a file across multiple tape volumes without interruption.
  455.      WAIT FOR TAPE MOTION TO STOP on the new tape before clicking Continue.
  456.      If you click Abort, an I/O error is returned to the application.
  457.  
  458.   *NOTE*  EOT handling is invoked when any of the blocks in the group of "NB"
  459.      blocks gets an EOM or Volume Overflow error.  When you click Continue,
  460.      the entire group of blocks is rewritten/reread on the new tape.
  461.      Therefore, to use the multiple-volume capability of the handler, you must
  462.      use the same blocking factor (value of NB) when reading the tape as
  463.      when it was written.
  464.  
  465.   *NOTE*  EOT handling for the 3M drive will work only if the ROM version
  466.      supports the READ_CAPACITY SCSI command.  If you see no "Capacity"
  467.      message from TAPEMON, then EOT handling is unavailable.
  468.  
  469.  
  470. ERROR HANDLING
  471.  
  472.      This version of the handler does not deal with tape errors.  If the
  473.      drive detects a medium error, the current operation will be aborted
  474.      by returning -1 for Read() or Write().  Some drives insulate the
  475.      user from bad blocks by automatically correcting them or remapping
  476.      to a good block, but other drives may not do this.
  477.  
  478.  
  479. 3M DRIVE USERS- NOTE
  480.  
  481.      The following applies only to the 3M MCD-40 direct access drive.
  482.  
  483.      The 3M drive does not use file marks.  When you reference the
  484.      tape as "TAPE:num", num is the SCSI block number, not the file number.
  485.      When writing multiple files to a tape, you should write down the
  486.      block numbers where each file starts (unless you have a good memory).
  487.      Use the TAPEMON program to see the block numbers.
  488.  
  489.      The RB parameter in Startup may be used to skip over a number of
  490.      blocks at the beginning of the tape, if there is something there
  491.      (like volume information) you wish to preserve.
  492.  
  493.      Be sure your cartridge is formatted.  If you try to use an
  494.      unformatted tape, results will be non-optimal.  You can buy
  495.      preformatted tapes, or you can format your own- see the section on
  496.      raw commands below. Cartridges may be formatted with an interleave
  497.      factor. Interleave is the number of physical blocks separating adjacent
  498.      logical blocks.  The 3M unit defaults to interleave 2, but I find
  499.      for my Supra that 3 improves performance slightly.
  500.  
  501.      The raw command to format a tape is:  04 80 20 00 00 80
  502.      which denotes the format command, immediate completion, precondition
  503.      the tape, default interleave, and retry on errors.
  504.  
  505.      A note about the hardware.  If you haven't noticed it yet, the
  506.      3M drive is EXTREMELY sensitive to electrical noise.  It is
  507.      *essenstial* that the drive be properly grounded.  The ground
  508.      in the power connector is insufficient.  You should run a thick
  509.      wire or braided strap from the metal side-plate to a good ground,
  510.      preferrably the power supply ground.  I'm not kidding.
  511.  
  512.  
  513. HELPFUL HINTS:
  514.  
  515.      Label your tapes.  Include the file number or block number
  516.      of each file on a multi-file tape.
  517.  
  518.      Try backing up and restoring a floppy before doing the
  519.      same with your hard drive, to make sure the process works for you.
  520.      For the same reason, make a HD backup to floppies first.  Then
  521.      if the tape restore fails, you have something to fall back on.
  522.  
  523.      This is obvious, right?  Make sure you have a copy of the handler and
  524.      TAR on an easily-accessible floppy.  If the only copy you have is
  525.      on your hard drive, you might find it difficult to restore
  526.      from a tape backup after a disk wipe-out.
  527.  
  528.  
  529. THE MONITOR PROGRAM
  530.  
  531.      Included in with the handler is the TAPEMON program.  TAPEMON is
  532.      a program that runs under a separate CLI and prints one-liner
  533.      messages from the handler.  The messages include the current
  534.      tape operation and block number, and error and sense codes.
  535.      The handler will run with or without TAPEMON; i.e. TAPEMON is optional.
  536.      TAPEMON must be started up AFTER the handler is mounted and activated.
  537.      Read TAPEMON.DOC for more information.
  538.  
  539.  
  540. RAW COMMAND INTERFACE
  541.  
  542.      This handler provides a means to send your own SCSI control commands
  543.      to the tape drive, without the need for a special program.
  544.      Some control commands you might want to send it would be REWIND,
  545.      UNLOAD, ERASE, FORMAT, LOCK, etc.  Only control commands may be sent-
  546.      there is no provision for any data transfer; don't try it.
  547.      (As you might guess, raw commands can be dangerous.)
  548.  
  549.      The raw command mode is invoked by writing data to the file name
  550.      "TAPE:RAWCMD".  (v1.0 users- the dollar signs are no longer used).
  551.      This magic word is how the handler knows you want to do a raw command.
  552.  
  553.      There are two ways to send data via RAWCMD using CLI commands:
  554.         1) use the ECHO command:     ECHO >TAPE:RAWCMD "hex command bytes..."
  555.         2) use the TYPE command:     TYPE filename TO TAPE:RAWCMD
  556.  
  557.      The ECHO command is useful to place in a script or create an alias
  558.      for the command.  You may also place the data in a file and use TYPE;
  559.      line 1 of the file contains the bytes to be sent as the raw command.
  560.  
  561.      The exact value of the data bytes is determined by the byte format of
  562.      the SCSI command you want to send. (Refer to your drive documentation.)
  563.      The data must contain ONLY hex digits and spaces terminated, by a newline.
  564.      Each byte of the raw command should be specified as a pair of hex
  565.      digits;  separate bytes by spaces.  Up to 10 bytes may be specified.
  566.      The data for TYPE must be on the first line of the file.
  567.      You can use any following lines as comments, but the total size of
  568.      the file must be less than the size of BS*NB.
  569.  
  570.      Command examples:
  571.         Rewind:     01 00 00 00 00 00
  572.         Erase:      19 00 00 00 00 00
  573.         Lock:       1E 00 00 00 01 00
  574.  
  575.  
  576. USER-SPECIFIED MODE SELECT
  577.  
  578.      In recognition of the fact that it will never be able to provide
  579.      switches for all possible modes of all tape drives, BTNtape
  580.      allows you to set the modes of the drive directly.
  581.      These modes might include:  buffering, speed, auto-loading,
  582.      enable disconnect, medium type, etc.
  583.  
  584.    *NOTE* Do not use this feature unless you know what you are doing.
  585.      This feature is provided for the convenience of "power users".
  586.      Most drives can get by with defaults if you do not set the modes,
  587.      so it is unlikely that not setting a mode will cause problems.
  588.  
  589.      Drive modes are set using the SCSI command MODE_SELECT (0x15).
  590.      BTNtape will send its own MODE_SELECT to the drive if necessary
  591.      to set the drive to fixed block mode and set the block length.
  592.      But you may also send this command to the drive at other times,
  593.      using any data you wish.
  594.  
  595.      The command is sent in a manner very similar to the RAWCMD
  596.      method described above, but the magic word MODESEL is
  597.      used instead.  The handler provides the SCSI command,
  598.      and you provide the data.  The data is specified as pairs of
  599.      hex digits separated by spaces, in a file for TYPE, or directly
  600.      in an ECHO command.
  601.  
  602.             ECHO >TAPE:MODESEL "hex data bytes..."
  603.        or   TYPE filename TO TAPE:MODESEL
  604.  
  605.      Since each drive has different things that are affected by MODE_SELECT,
  606.      you MUST refer to the programming documentation for your drive.
  607.      But in general, the mode select data consists of a parameter
  608.      list, a block descriptor, and vendor unique parameters.
  609.     *NOTE*  If you specify a block descriptor, it will behoove you to
  610.      specify the same block length as specified in the mountlist entry
  611.      when using fixed block mode, or zero if using variable block mode.
  612.  
  613.      The handler counts the number of bytes you specify (up to 64),
  614.      and uses that for the SCSI command data length.  The drive may
  615.      be fussy about the length, so specify exactly the number of bytes
  616.      as described in your docs.
  617.  
  618.      Mode Select data example:
  619.  
  620.        --parmlist-   ----block-descriptor---   vendorparms
  621.        00 10 00 08   03 00 00 00 00 00 04 00   11 22 33 44
  622.           |     |    |                 || ||
  623.   Buff mode  BD Len  Density         Blk Len
  624.  
  625.  
  626. FINE TUNING
  627.  
  628.      There are a few factors you can tweak to get good performance
  629.      on your particular system.  Good performance means the tape tends
  630.      to run continuously for long periods of time and seldom has
  631.      to stop and back up to get a running start at the next block.
  632.      The tape may have to stop while TAR gets more data from the
  633.      hard disk, but you can minimize it.
  634.  
  635.      The handler's NB parameter can be increased from 1 to
  636.      some larger number as your memory allows.  With more handler
  637.      blocks, a large quantity of data is available to dump to the tape,
  638.      but there is probably a point of diminishing return.
  639.  
  640.      The TAR program also has a block parameter.  It controls how much
  641.      DOS data TAR collects before sending it to the handler.  If you
  642.      use many TAR blocks, it makes no sense to also use many handler
  643.      blocks,  since the data has to go through both buffers
  644.      anyway.  You can increase the TAR blocks if your SCSI-
  645.      direct driver does not support multi-block operations.
  646.  
  647.      Using the TAPEMON program may slow down the handler slightly
  648.      when it prints messages, but it's not really a problem.
  649.      If you absolutely need maximum throughput, shut down TAPEMON.
  650.  
  651.  
  652. HOW IT WORKS
  653.  
  654.      Two buffers are maintained so that one buffer can be used by DOS
  655.      while the other is exchanging data with the drive.  With the
  656.      multitasking nature of the Amiga, this should help keep the tape
  657.      in motion, but it may not help much with non-DMA SCSI adapters.
  658.  
  659.      In write mode, the handler collects DOS data in one buffer while
  660.      the previously filled buffer is being written to tape.  In read mode,
  661.      the handler reads ahead on the tape to fill one buffer while
  662.      DOS gets data from the previously read buffer.
  663.  
  664.      The handler does not write (or expect) anything special on
  665.      the tape for itself.  That is to say, the data written on the
  666.      tape is your raw data, nothing else.  If I were to use parts
  667.      of the tape for file system information, I would be
  668.      introducing a sort of standard-- I don't think that is a good
  669.      idea right now.  Raw data provides a lowest common denominator
  670.      which should help compatibility with other things.  For instance,
  671.      a TAR tape created on a non-Amiga system is readable using
  672.      this handler and Amiga TAR.
  673.  
  674.  
  675. BUGS
  676.  
  677.      The variable block mode of operation (VB-1) has not been tested.
  678.  
  679.      The handler has not been tested with AmigaDOS 1.2.
  680.  
  681.      The handler does not multi-task well, but I believe that to be
  682.      a characteristic of the SCSI-direct drivers, not the handler.
  683.      Don't expect to do much else while a backup is in progress.
  684.      In fact, other things going on can reduce tape drive performance.
  685.  
  686.  
  687. AUTHOR:
  688.  
  689.   Email:  DrBob@cup.portal.com   OR   ...!sun!portal!cup.portal.com!DrBob
  690.  
  691.   USmail: Robert Rethemeyer
  692.           979-4 Belmont Terrace
  693.           Sunnyvale, CA  94086
  694.           USA
  695.  
  696.   If you want to contact me about a problem, please try to include
  697.   with your mail the following:
  698.       *  a copy of your mountlist entry for TAPE:
  699.       *  a capture of the output from TAPEMON.  Just redirect its
  700.              output to a file:     TAPEMON >filename
  701.       *  a verbal description of what happens to the drive and/or Amiga
  702.              (e.g.  tape doesn't move, smoke issues from Amiga, etc.)
  703.       *  any other info that may help me figure out what's going on.
  704.           Remember, I'm not there to see what is happening, and I
  705.           probably don't have your drive model available to recreate
  706.           the problem.  I have only your description to go by.
  707.  
  708.  
  709. MANY THANKS GO TO:
  710.  
  711.   Bob Mitchell for the SCSI-direct programs I used to get started,
  712.     and the 2090A circumvention.
  713.   Beta testers Bill Seymour, Don Phillips, Steve Goldstein,
  714.      Dick Wood, Don Camp, George Armhold, Gary Walborn.
  715.   Phillip Lindsay for the my.handler example code.
  716.   Rene' Vega for advice and Manxification.
  717.  
  718.