Club Amiga de Montreal

home *** CD-ROM | disk | FTP | other *** search

/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 421.lha / BTNtape_v1.0 / tape.doc.pp / tape.doc

Wrap

Text File | 1990-10-01 | 21.5 KB | 450 lines

**** BTNtape: a SCSI-Direct Tape Handler for AmigaDOS **** Version 1.0 09/10/90 **** Freeware by Bob Rethemeyer (DrBob@cup.portal.com) **** **** (c) Copyright 1990 Robert Rethemeyer. **** This software may be freely distributed and redistributed, **** for non-commercial purposes, provided this notice is included. **** All original files must 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. Files may span multiple tape volumes and may start at any tape block. This handler requires a "SCSI-direct" compatible hard disk driver. It is known to work with a 3-M MCD-40 tape drive on the CBM 2091 controller, the CBM 2090A with an ST506 hard drive, and the Supra 4x4, and may also work with others (refer to the docs). Included is a monitoring program which prints useful information about handler activities, including error sense data. 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". =================== ******> 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 will work for any combinations of drives or controllers other than those I have specifically tested. If you do not agree with this disclaimer, I recommend you not use this software; wait for good commercial tape drivers. ============================================================================ I cannot at this time commit to adding further enhancements or special features requested by users. This is not to say that I won't do these things, it's just that I can't guarantee I'll have the time or resources. 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. ============================================================================== DISTRIBUTION: The distribution should contain the following files: tape-handler handler binary tape.c source for main handler program 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 tapemon directory tapemon monitor program binary tapemon.c monitor source tapemon.doc documentation for the monitor program tapemon.lmk Lattice make file for tapemon mountlist example mountlist entry formattape raw command file for formatting tapes lmkfile Lattice make file for handler makefile Manx make file for handler sense.codes describes sense codes for 3-M MCD-40 drive tape.doc you're reading it COMPATIBILITY: You must have hard disk driver software which honors the SCSI-direct protocol as defined in the "devices/scsidisk.h" include file. Currently I know that the CBM 2090A, 2091, and Supra Series-II v1.10 software support this protocol. There are probably others which will support it also; check with your vendor. This handler is has been tested on the following equipment: Tape drives: * 3-M Model MCD-40 40MB cartridge tape drive Controllers: * Commodore 2091- works with no known problems. * Commodore 2090A- works *if* the hard drive is ST506. * Supra 4x4 (Amiga 1000)- works, but see Supra user notes. It may possibly work with other controllers: 2090A with SCSI hard drive: if the hard drive is on the same SCSI bus with the tape drive, the 2090A driver seems to go into some kind of loop when restoring files from tape to disk. I believe this to be a problem with the 2090A driver. You can still restore the files to RAM or floppy. A3000: It is my understanding that the Amiga 3000 built-in SCSI controller is based on the 2091, so the handler should work with a 3000, but I have not tested it on one. Ditto for the A590. Other SUPRA controllers: I believe that the same Supra driver software is used on all their controllers. I have only tried the handler on the Supra 4x4 for the A1000, but it might work with their A2000 boards. Other tape drives: the handler *might* work with another SCSI tape drive if it supports the SCSI commands REZERO, REQUEST_SENSE, READ, and WRITE. The drive must also support READ_CAPACITY for end-of-tape detection to work. (If it does work for some other drive model, 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 = "4/1/8192/1/0/yourscsi.device" | | | | | | | | | | | +---- name of your SCSI-direct driver | | | | +--- number of reserved tape blocks | | | +--- number of tape blocks per buffer | | +---- tape drive block size (bytes) | +---- BufMemType +---- SCSI bus unit number to address tape drive There is nothing magic about the name TAPE: You may use some other valid device name if you like. The Startup parameter is used by the handler to determine how to access your drive. It should not have any embedded blanks and should be enclosed in quotes. The parts must be separated by slashes. The numbers may be written as decimal, or hex in the "0xNN" format. FAILURE TO ENTER PROPER INFORMATION IN STARTUP MAY RESULT IN PROBLEMS INCLUDING HANGS, VISITS FROM THE GURU, OR DATA LOSS. The first number is the SCSI bus unit ID of your tape drive, as it will be addressed by your SCSI-direct driver. Presumably you have set the tape drive ID switches or jumpers to a value that is unique on the SCSI bus. 2090A owners- use the permuted (+3) unit number here. The second number is the same as BufMemType for mountlists. Use 0 or 1 for "any", 2 or 3 for "chip", 4 or 5 for "fast". The third number is the number of bytes in a SCSI logical block for your tape drive. The fourth number is the number of SCSI logical blocks to write or read in one I/O operation. Some drives may be mechanically more efficient writing multiple blocks. You may want to tweak this parameter to find out, but start with 1 to be safe (some 2090A owners report problems with multiple-block SCSI-direct I/O). This parameter also determines how much storage is needed for buffers. The handler uses double buffering, so it will need " 2 * blocksize * numberofblocks " bytes when you Open it. For example, for 8K blocks if you specify 8, then 2*8192*8 = 128K bytes are needed. The fifth number is like the Reserved parameter in mountlists. It tells the handler how many SCSI logical blocks to skip at the beginning of the tape before accessing data. You may need it if there is something on the front of the tape you want to preserve, like volume information. In most cases you can use zero. To read a tape, you must use the same reserved number with which it was written. The last part is the name of the device driver which provides the SCSI-direct command protocol. For 2090As this is "hddisk.device"; for Supra it is "supradirect.device". Do not include any path information. You may need to include a special character in front of the name to invoke bug circumventions- see the user notes below. 3. Install the handler in DOS using the CLI command "MOUNT TAPE:" Unfortunately, if the handler fails due to a mountlist or OpenDevice problem, there is no error indication [anyone know how I can?]. The device will show up in ASSIGN LIST, but no handler process. Use ASSIGN dev REMOVE, fix the problem, and try again. 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, prefix the driver name in the Startup parameter with a dollar sign. example: "4/1/8192/1/0/$hddisk.device" The circumvention is NOT necessary for other controllers. A worse problem- the 2090A cannot seem to handle both the disk and the tape drive on the same SCSI bus. Strict reads and writes to the tape work fine, but intermixed tape reads and disk writes (such as during a restore) will cause the 2090A to get stuck in a loop reading and rereading the same block. 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:. 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. Prefix the driver name in the Startup parameter with a plus sign. Example: "4/1/8192/1/0/+supradirect.device" I have reported this to Supra, and they are looking 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. That is, SupraMount only your disk unit. Example: "SupraMount 6". HOW TO USE IT 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 block numbers. Also, files may span multiple tape volumes. You refer to the tape with one of the following file name forms: TAPE: Rewind and open the tape at the first available block TAPE:* Opens the tape at the current position (no rewind) TAPE:n Opens the tape at block n (n is a SCSI block number) TAPE:$$RAWCMD$$ Sends a raw SCSI command to the drive (see below) The TAPE:n form works only if the tape drive supports direct block access. 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 supported. You cannot Open the tape in "append" mode. Be sure your cartridge is formatted. If you try to write to an unformatted tape, results will be non-optimal. You can buy preformatted tapes, or you can try formatting your own- see the section on raw commands below. If there is no cartridge in the drive at the time TAPE: is opened, DOS will put up a requester asking for volume "TAPE" "in any drive". Insert the cartridge (in the tape drive, not a floppy drive :-) and click on retry after tape motion stops. If the application reaches the end of the tape, the handler will put up a requester (if drive supports the "Read Capacity" SCSI command). The requester asks you to insert the next tape and click "Continue", or click "Quit". The continue option allows the application program to access a file across multiple tape volumes without interruption. If you click quit, an I/O error indication is returned to the application. To use TAR, cd to the desired directory or partition ("cd DH0:"), then... To make a backup archive with TAR : tar -cv -f tape: "" To add another archive file : tar -cv -f tape:* "" To restore files from archive : tar -xv -f tape: * To restore from archive at blk 840 : tar -xv -f tape:840 * To list the archive on the tape : tar -t -f tape: To make an archive log : tar >logfile -t -f tape: To look at raw tape data : type tape: opt h ... cntl-C When restoring files, TAR is case sensitive to the file names. TAR can be aborted with cntl-C. TAR can also make backups using a list of files from another file. Refer to the TAR documentation for more information. HELPFUL HINTS: - Label your tape cartridges. - When writing multiple files to a tape, you must write down the block numbers where each file starts. Use the TAPEMON program to obtain the block numbers. Example: File A starts at 0 File B starts at 48 File C starts at 224 ... - First time, 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. 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-line messages from the handler. The messages include the current tape operation and block number, and error and sense codes. You will need to run this program to be able to place multiple files on a tape. Read TAPEMON.DOC for more information. 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 does not have to frequently back up to get a running start at the next block. The tape usually has to stop while TAR gets more data from the hard disk, but you can minimize it. The handler's "number of blocks" parameter can be increased from one 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 creates potentially more "dead blocks" at the end of the tape). The TAR program also has a block parameter. It controls how much DOS data TAR collects before sending it to the handler. If you increase this parameter, it makes no sense to also increase the handler block parameter, 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. Some tape drives may support an interleave factor for the tape that can be specified at the time the cartridge is formatted. Interleave is the number of physical blocks separating adjacent logical blocks. The 3-M unit defaults to interleave 2, but I find for my Supra that 3 prevents the tape from backing up frequently. It doesn't seem to make much difference with the CBM controllers. HOW IT WORKS Writing to TAPE:, the handler collects the data in a memory buffer until the buffer is full, then the buffer is written to the current tape block. Reads work in a similar manner but in the other direction. Two buffers are maintained so that one buffer can be used by DOS while the other is exchanging data with the drive. This is supposed to help keep the tape in motion, but it may not help much with non-DMA controllers. This software 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 should be readable using this handler and Amiga TAR. The handler does not provide a tape file system, and the tape does not have a volume name. The handler assumes the tape is endless. That is, it just keeps writing until you run out of tape. FORMATTING A TAPE- the raw command interface This handler provides a crude means of formatting cartridges, without a special format program. It's done with a built-in raw command mode which allows you to send your own SCSI command to the tape controller. Although it might be used to send any command, it's really designed only to make it easy to do a format. There is no provision for any data transfer; don't try it. (As you might guess, playing with raw mode can be dangerous.) The raw command mode is invoked by referencing the tape file as "TAPE:$$RAWCMD$$". The letters RAWCMD must be upper case and be enclosed by the double dollar signs. This magic word is how the handler knows you want to do a raw command. To send a raw command, you enter the CLI command: TYPE filename TO TAPE:$$RAWCMD$$ Line 1 of the file contains the bytes to be sent as the raw command, in ASCII format. Only the FIRST line of the file is significant; you can use any following lines as comments, but the total size of the file must be less than the size of a tape block. The first line must contain ONLY hex digits and spaces. Each byte of the raw command should be specified as a pair of hex digits; separate bytes by spaces. Up to 32 bytes may be specified, but only 6 or 10 are really needed. The supplied file "formattape" contains the raw command bytes to initiate a format operation on the 3M tape drive. Other tape drive models may need different data; I can't help you there. Look at the file for an explanation of the 3M format command bytes. BUGS The handler always assumes the tape device is LUN zero. I have not tested this software with AmigaDOS 1.2 or 2.0 (but it should work). 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. To read a file across multiple volumes, you must make sure that the blocking factor specified in Startup is the same as when the tape was written. This is because there may be a few "dead blocks" at the end of the tape which cannot be reached, and a different blocking factor may make some previously written blocks unaccessible. AUTHOR: Email: DrBob@cup.portal.com OR ...!sun!portal!cup.portal.com!DrBob USmail: Robert Rethemeyer 979-4 Belmont Terrace Sunnyvale, CA 94086 MANY THANKS GO TO: Bob Mitchell for the SCSI-direct programs I used to get started, and the 2090A circumvention. Phillip Lindsay for the my.handler example code. Rene' Vega for advice and Manxification. Gary Walborn, Don Camp, and Clay Jones for beta testing.