amiga-request@abcfd20.larc.nasa.gov (Amiga Sources/Binaries Moderator) (10/05/90)
Submitted-by: <DrBob@cup.portal.com>
Posting-number: Volume 90, Issue 263
Archive-name: devices/btntape-1.0/part02
#!/bin/sh
# This is a shell archive. Remove anything before this line, then unpack
# it by saving it into a file and typing "sh file". To overwrite existing
# files, type "sh file -c". You can also feed this as standard input via
# unshar, or by typing "sh <file", e.g.. If this archive is complete, you
# will see the following message at the end:
# "End of archive 2 (of 2)."
# Contents: tape.doc
# Wrapped by tadguy@abcfd20 on Thu Oct 4 19:41:24 1990
PATH=/bin:/usr/bin:/usr/ucb ; export PATH
if test -f 'tape.doc' -a "${1}" != "-c" ; then
echo shar: Will not clobber existing file \"'tape.doc'\"
else
echo shar: Extracting \"'tape.doc'\" \(22039 characters\)
sed "s/^X//" >'tape.doc' <<'END_OF_FILE'
X**** BTNtape: a SCSI-Direct Tape Handler for AmigaDOS
X**** Version 1.0 09/10/90
X**** Freeware by Bob Rethemeyer (DrBob@cup.portal.com)
X****
X**** (c) Copyright 1990 Robert Rethemeyer.
X**** This software may be freely distributed and redistributed,
X**** for non-commercial purposes, provided this notice is included.
X**** All original files must included in the distribution.
X
XBTNtape is a "Better Than Nothing" SCSI tape device handler. It provides
Xflat-file access to a SCSI tape drive from application programs using
Xsimple DOS calls to Read() and Write(). It can also be used with the Amiga
XTAR utility for disk backups. Files may span multiple tape volumes
Xand may start at any tape block. This handler requires a "SCSI-direct"
Xcompatible hard disk driver. It is known to work with a 3-M MCD-40 tape
Xdrive on the CBM 2091 controller, the CBM 2090A with an ST506 hard drive,
Xand the Supra 4x4, and may also work with others (refer to the docs).
XIncluded is a monitoring program which prints useful information
Xabout handler activities, including error sense data.
X
XThis handler is probably not the all-purpose tape driver you have been waiting
Xfor. It won't work with any backup program which requires Exec devices.
XI claim only that it works with the Amiga TAR program ported by Jonathan Hue.
XBut until we see good commercial or shareware tape software, you might
Xfind this handler to be "better than nothing".
X
X=================== ******> R E A D T H I S <****** ======================
X
XDISCLAIMER:
X "This software is provided 'as-is', without warranty of any kind,
Xeither expressed or implied. In no event will I, Robert Rethemeyer,
Xbe liable for direct, indirect, incidental or consequential damages or
Xdata loss resulting from the use or application of this software. The entire
Xrisk as to the results and performance of this software is assumed by you."
X
XI cannot guarantee that this software will work for any combinations
Xof drives or controllers other than those I have specifically tested.
X
XIf you do not agree with this disclaimer, I recommend you not use this
Xsoftware; wait for good commercial tape drivers.
X
X============================================================================
X
XI cannot at this time commit to adding further enhancements
Xor special features requested by users. This is not to say that I won't
Xdo these things, it's just that I can't guarantee I'll have the time
Xor resources.
X
XAlthough this documentation refers to alleged problems with some
Xmanufacturers' driver software, that should not be construed as a statement
Xabout the quality of their products. In fact, there is still a possibility
Xthat the problems may be in my handler software or the equipment I used.
X
X==============================================================================
X
XDISTRIBUTION:
X
X The distribution should contain the following files:
X tape-handler handler binary
X tape.c source for main handler program
X tapeio.c source for interface to SCSI-direct
X pktstuff.c source for packet handling, by Phillip Lindsay
X tape.h local include file
X tplink.h local include file for handler/monitor structure
X tapemon directory
X tapemon monitor program binary
X tapemon.c monitor source
X tapemon.doc documentation for the monitor program
X tapemon.lmk Lattice make file for tapemon
X mountlist example mountlist entry
X formattape raw command file for formatting tapes
X lmkfile Lattice make file for handler
X makefile Manx make file for handler
X sense.codes describes sense codes for 3-M MCD-40 drive
X tape.doc you're reading it
X
X
XCOMPATIBILITY:
X
X You must have hard disk driver software which honors the SCSI-direct protocol
X as defined in the "devices/scsidisk.h" include file. Currently I know that
X the CBM 2090A, 2091, and Supra Series-II v1.10 software support this protocol.
X There are probably others which will support it also; check with your vendor.
X
X This handler is has been tested on the following equipment:
X
X Tape drives: * 3-M Model MCD-40 40MB cartridge tape drive
X
X Controllers: * Commodore 2091- works with no known problems.
X * Commodore 2090A- works *if* the hard drive is ST506.
X * Supra 4x4 (Amiga 1000)- works, but see Supra user notes.
X
X It may possibly work with other controllers:
X
X 2090A with SCSI hard drive: if the hard drive is on the same SCSI bus
X with the tape drive, the 2090A driver seems to go into some kind of loop
X when restoring files from tape to disk. I believe this to be a problem
X with the 2090A driver. You can still restore the files to RAM or floppy.
X
X A3000: It is my understanding that the Amiga 3000 built-in SCSI
X controller is based on the 2091, so the handler should work with a 3000,
X but I have not tested it on one. Ditto for the A590.
X
X Other SUPRA controllers: I believe that the same Supra driver software
X is used on all their controllers. I have only tried the handler on
X the Supra 4x4 for the A1000, but it might work with their A2000 boards.
X
X Other tape drives: the handler *might* work with another SCSI tape drive
X if it supports the SCSI commands REZERO, REQUEST_SENSE, READ, and WRITE.
X The drive must also support READ_CAPACITY for end-of-tape detection to work.
X (If it does work for some other drive model, I would like to hear about it.)
X
X
XINSTALLATION:
X
X 1. Copy the TAPE-HANDLER file to L:TAPE-HANDLER.
X Copy the TAPEMON program to C: or a directory appropriate for you.
X
X 2. Create an entry in DEVS:MOUNTLIST something like this:
X
X TAPE: Handler = L:tape-handler
X Priority = 5 /* use 11 for Supra */
X Mount = 1 /* optional */
X Stacksize = 4000
X GlobVec = -1
X Startup = "4/1/8192/1/0/yourscsi.device"
X | | | | | |
X | | | | | +---- name of your SCSI-direct driver
X | | | | +--- number of reserved tape blocks
X | | | +--- number of tape blocks per buffer
X | | +---- tape drive block size (bytes)
X | +---- BufMemType
X +---- SCSI bus unit number to address tape drive
X
X There is nothing magic about the name TAPE: You may use some
X other valid device name if you like.
X
X The Startup parameter is used by the handler to determine how
X to access your drive. It should not have any embedded blanks
X and should be enclosed in quotes. The parts must be separated
X by slashes. The numbers may be written as decimal, or hex in the
X "0xNN" format. FAILURE TO ENTER PROPER INFORMATION IN STARTUP MAY
X RESULT IN PROBLEMS INCLUDING HANGS, VISITS FROM THE GURU,
X OR DATA LOSS.
X
X The first number is the SCSI bus unit ID of your tape drive, as it
X will be addressed by your SCSI-direct driver. Presumably you have
X set the tape drive ID switches or jumpers to a value that is unique
X on the SCSI bus. 2090A owners- use the permuted (+3) unit number here.
X
X The second number is the same as BufMemType for mountlists. Use
X 0 or 1 for "any", 2 or 3 for "chip", 4 or 5 for "fast".
X
X The third number is the number of bytes in a SCSI logical block
X for your tape drive.
X
X The fourth number is the number of SCSI logical blocks to write or
X read in one I/O operation. Some drives may be mechanically more
X efficient writing multiple blocks. You may want to tweak this
X parameter to find out, but start with 1 to be safe (some 2090A
X owners report problems with multiple-block SCSI-direct I/O).
X This parameter also determines how much storage is needed for
X buffers. The handler uses double buffering, so it will need
X " 2 * blocksize * numberofblocks " bytes when you Open it.
X For example, for 8K blocks if you specify 8, then
X 2*8192*8 = 128K bytes are needed.
X
X The fifth number is like the Reserved parameter in mountlists. It tells
X the handler how many SCSI logical blocks to skip at the beginning of
X the tape before accessing data. You may need it if there is something
X on the front of the tape you want to preserve, like volume
X information. In most cases you can use zero. To read a tape, you
X must use the same reserved number with which it was written.
X
X The last part is the name of the device driver which provides
X the SCSI-direct command protocol. For 2090As this is "hddisk.device";
X for Supra it is "supradirect.device". Do not include any path
X information. You may need to include a special character in front
X of the name to invoke bug circumventions- see the user notes below.
X
X 3. Install the handler in DOS using the CLI command "MOUNT TAPE:"
X Unfortunately, if the handler fails due to a mountlist or OpenDevice
X problem, there is no error indication [anyone know how I can?].
X The device will show up in ASSIGN LIST, but no handler process.
X Use ASSIGN dev REMOVE, fix the problem, and try again.
X
X
X2090A USERS- NOTE
X
X Apparently (I don't own a 2090A) there is a software bug in the
X CBM 2090A SCSI-direct driver that causes problems with tape
X writes. Bob Mitchell figured out that the problem can be
X circumvented by asserting data address bit 24 for writes.
X This handler can optionally invoke that circumvention.
X To do so, prefix the driver name in the Startup parameter
X with a dollar sign. example: "4/1/8192/1/0/$hddisk.device"
X The circumvention is NOT necessary for other controllers.
X
X A worse problem- the 2090A cannot seem to handle both the disk
X and the tape drive on the same SCSI bus. Strict reads and writes
X to the tape work fine, but intermixed tape reads and disk writes
X (such as during a restore) will cause the 2090A to get
X stuck in a loop reading and rereading the same block.
X This does not happen if the hard drive is on the ST506 bus.
X It also does not happen if you restore the files to RAM or floppy.
X
X Make sure the tape is out of the drive when you boot
X AmigaDOS; otherwise, DOS never comes up.
X
X When you mount TAPE:, make sure there is no cartridge in the
X tape drive. For some reason I do not understand, the 2090A
X causes a reset to the tape drive when OpenDevice is called.
X If a cartridge is in the drive at that time, the system
X eventually enters an unusable state. I recommend using
X "Mount = 1" in your MountList entry for TAPE:. When TAPE:
X is mounted, it will put up a requester because the drive is
X empty; click on cancel, then everything will be happy.
X
X
XSUPRA USERS- NOTE
X
X Apparently (I DO own one) there is a problem with the Supra v1.10
X SCSI-direct software that causes the host adapter to hang when a
X non-zero byte count is supplied in the command (SCSICmd.scsi_Length).
X It works fine when a data length of zero is used. The handler can also
X circumvent this problem. Prefix the driver name in the Startup parameter
X with a plus sign. Example: "4/1/8192/1/0/+supradirect.device"
X I have reported this to Supra, and they are looking into it.
X
X You *must* run the tape handler at a higher priority than the
X Supra driver task. You do this by changing the "Priority ="
X line in the mountlist entry. For Supra v1.10, the task runs
X at priority 10. Therefore, the tape handler should run at
X "Priority = 11". If some other Supra version runs at a different
X priority, change the mountlist priority accordingly.
X Use a utility such as Xoper or TaskX to find task priorities.
X
X If the cartridge is in the drive at the time you boot AmigaDOS,
X SupraMount will hang the system if it touches the tape drive.
X To avoid this, use the selective mount feature of SupraMount.
X That is, SupraMount only your disk unit. Example: "SupraMount 6".
X
X
XHOW TO USE IT
X
X Now that the handler is installed, how do you talk to it?
X You can use TAR, or your own application program, including ARexx.
X You can write data to the tape and later read it back in a manner
X similar to other files, using DOS calls to Open, Read, Write, and Close.
X
X The handler makes the tape data look like a sequential AmigaDOS file.
X There is NO FILE SYSTEM on the tape, but you may place multiple files
X on a tape by positioning the tape to specific block numbers.
X Also, files may span multiple tape volumes.
X
X You refer to the tape with one of the following file name forms:
X
X TAPE: Rewind and open the tape at the first available block
X TAPE:* Opens the tape at the current position (no rewind)
X TAPE:n Opens the tape at block n (n is a SCSI block number)
X TAPE:$$RAWCMD$$ Sends a raw SCSI command to the drive (see below)
X
X The TAPE:n form works only if the tape drive supports direct block access.
X
X The handler does not support mixed reads and writes. That is, you may
X do only Reads or only Writes, but not both. Seeks are not supported.
X You cannot Open the tape in "append" mode.
X
X Be sure your cartridge is formatted. If you try to write to an
X unformatted tape, results will be non-optimal. You can buy
X preformatted tapes, or you can try formatting your own-
X see the section on raw commands below.
X
X If there is no cartridge in the drive at the time TAPE: is
X opened, DOS will put up a requester asking for volume "TAPE"
X "in any drive". Insert the cartridge (in the tape drive, not
X a floppy drive :-) and click on retry after tape motion stops.
X
X If the application reaches the end of the tape, the handler will put up
X a requester (if drive supports the "Read Capacity" SCSI command).
X The requester asks you to insert the next tape and click "Continue",
X or click "Quit". The continue option allows the application program
X to access a file across multiple tape volumes without interruption.
X If you click quit, an I/O error indication is returned to the application.
X
X To use TAR, cd to the desired directory or partition ("cd DH0:"), then...
X
X To make a backup archive with TAR : tar -cv -f tape: ""
X To add another archive file : tar -cv -f tape:* ""
X To restore files from archive : tar -xv -f tape: *
X To restore from archive at blk 840 : tar -xv -f tape:840 *
X To list the archive on the tape : tar -t -f tape:
X To make an archive log : tar >logfile -t -f tape:
X To look at raw tape data : type tape: opt h ... cntl-C
X
X When restoring files, TAR is case sensitive to the file names.
X TAR can be aborted with cntl-C.
X TAR can also make backups using a list of files from another file.
X Refer to the TAR documentation for more information.
X
X HELPFUL HINTS:
X - Label your tape cartridges.
X - When writing multiple files to a tape, you must write down the
X block numbers where each file starts. Use the TAPEMON
X program to obtain the block numbers. Example:
X File A starts at 0
X File B starts at 48
X File C starts at 224 ...
X - First time, try backing up and restoring a floppy before doing the
X same with your hard drive, to make sure the process works for you.
X For the same reason, make a HD backup to floppies first. Then
X if the tape restore fails, you have something to fall back on.
X
X
XTHE MONITOR PROGRAM
X
X Included in with the handler is the TAPEMON program. TAPEMON is
X a program that runs under a separate CLI and prints one-line
X messages from the handler. The messages include the current
X tape operation and block number, and error and sense codes.
X You will need to run this program to be able to place multiple
X files on a tape. Read TAPEMON.DOC for more information.
X
X
XFINE TUNING
X
X There are a few factors you can tweak to get good performance
X on your particular system. Good performance means the tape tends
X to run continuously for long periods of time and does not have
X to frequently back up to get a running start at the next block.
X The tape usually has to stop while TAR gets more data from the
X hard disk, but you can minimize it.
X
X The handler's "number of blocks" parameter can be increased from
X one to some larger number as your memory allows. With more handler
X blocks, a large quantity of data is available to dump to the tape
X (but creates potentially more "dead blocks" at the end of the tape).
X
X The TAR program also has a block parameter. It controls how much
X DOS data TAR collects before sending it to the handler. If you
X increase this parameter, it makes no sense to also increase the
X handler block parameter, since the data has to go through both
X buffers anyway. You can increase the TAR blocks if your SCSI-
X direct driver does not support multi-block operations.
X
X Some tape drives may support an interleave factor for the tape
X that can be specified at the time the cartridge is formatted.
X Interleave is the number of physical blocks separating adjacent
X logical blocks. The 3-M unit defaults to interleave 2, but I find
X for my Supra that 3 prevents the tape from backing up frequently.
X It doesn't seem to make much difference with the CBM controllers.
X
X
XHOW IT WORKS
X
X Writing to TAPE:, the handler collects the data in a memory buffer
X until the buffer is full, then the buffer is written to
X the current tape block. Reads work in a similar manner but
X in the other direction.
X
X Two buffers are maintained so that one buffer can be used by DOS
X while the other is exchanging data with the drive. This is
X supposed to help keep the tape in motion, but it may not help much
X with non-DMA controllers.
X
X This software does not write (or expect) anything special on
X the tape for itself. That is to say, the data written on the
X tape is your raw data, nothing else. If I were to use parts
X of the tape for file system information, I would be
X introducing a sort of standard-- I don't think that is a good
X idea right now. Raw data provides a lowest common denominator
X which should help compatibility with other things. For instance,
X a TAR tape created on a non-Amiga system should be readable
X using this handler and Amiga TAR.
X
X The handler does not provide a tape file system, and the tape
X does not have a volume name. The handler assumes the tape is
X endless. That is, it just keeps writing until you run out of tape.
X
X
XFORMATTING A TAPE- the raw command interface
X
X This handler provides a crude means of formatting cartridges,
X without a special format program. It's done with a built-in
X raw command mode which allows you to send your own SCSI command to
X the tape controller. Although it might be used to send any
X command, it's really designed only to make it easy to do a format.
X There is no provision for any data transfer; don't try it.
X (As you might guess, playing with raw mode can be dangerous.)
X
X The raw command mode is invoked by referencing the tape file as
X "TAPE:$$RAWCMD$$". The letters RAWCMD must be upper case and be
X enclosed by the double dollar signs. This magic word is how
X the handler knows you want to do a raw command.
X
X To send a raw command, you enter the CLI command:
X
X TYPE filename TO TAPE:$$RAWCMD$$
X
X Line 1 of the file contains the bytes to be sent as the raw command,
X in ASCII format. Only the FIRST line of the file is significant;
X you can use any following lines as comments, but the total size of
X the file must be less than the size of a tape block.
X The first line must contain ONLY hex digits and spaces.
X Each byte of the raw command should be specified as a pair of hex
X digits; separate bytes by spaces. Up to 32 bytes may be
X specified, but only 6 or 10 are really needed.
X
X The supplied file "formattape" contains the raw command bytes
X to initiate a format operation on the 3M tape drive. Other
X tape drive models may need different data; I can't help you there.
X Look at the file for an explanation of the 3M format command bytes.
X
X
XBUGS
X
X The handler always assumes the tape device is LUN zero.
X
X I have not tested this software with AmigaDOS 1.2 or 2.0
X (but it should work).
X
X The handler does not multi-task well, but I believe that to be
X a characteristic of the SCSI-direct drivers, not the handler.
X Don't expect to do much else while a backup is in progress.
X
X To read a file across multiple volumes, you must make sure that the
X blocking factor specified in Startup is the same as when the tape
X was written. This is because there may be a few "dead blocks" at
X the end of the tape which cannot be reached, and a different blocking
X factor may make some previously written blocks unaccessible.
X
X
XAUTHOR:
X
X Email: DrBob@cup.portal.com OR ...!sun!portal!cup.portal.com!DrBob
X
X USmail: Robert Rethemeyer
X 979-4 Belmont Terrace
X Sunnyvale, CA 94086
X
X
XMANY THANKS GO TO:
X
X Bob Mitchell for the SCSI-direct programs I used to get started,
X and the 2090A circumvention.
X Phillip Lindsay for the my.handler example code.
X Rene' Vega for advice and Manxification.
X Gary Walborn, Don Camp, and Clay Jones for beta testing.
X
END_OF_FILE
if test 22039 -ne `wc -c <'tape.doc'`; then
echo shar: \"'tape.doc'\" unpacked with wrong size!
fi
# end of 'tape.doc'
fi
echo shar: End of archive 2 \(of 2\).
cp /dev/null ark2isdone
MISSING=""
for I in 1 2 ; do
if test ! -f ark${I}isdone ; then
MISSING="${MISSING} ${I}"
fi
done
if test "${MISSING}" = "" ; then
echo You have unpacked both archives.
rm -f ark[1-9]isdone
else
echo You still need to unpack the following archives:
echo " " ${MISSING}
fi
## End of shell archive.
exit 0
--
Mail submissions (sources or binaries) to <amiga@uunet.uu.net>.
Mail comments to the moderator at <amiga-request@uunet.uu.net>.
Post requests for sources, and general discussion to comp.sys.amiga.