IRAF Newsletter -- Number 14 -- April 1998

[ Previous ] [ Next ] [ Table of Contents ] [ Search this issue ]


The TAPECAP File Explained

Since the tapecap file was introduced in V2.10 some of the most common technical support questions have dealt with how to add a new device to this file, and the meaning of the various fields in each entry. It is therefore worth spending a little time explaining what this file does and how it can be configured.

In IRAF V2.10 there was one tapecap file per IRAF installation and all client nodes sharing the same central installation required device entries in the global tapecap file. In V2.11 this scheme has been generalized to allow each host to have its own private tapecap file, with a fallback to the generic tapecap file if no host-specific file is found. The system will look first for a configuration file called "tapecap. node " where node is the hostname of the server the tapecap file describes. If this file is not found the default tapecap file, dev$tapecap , will be used.

Since magnetic tape (magtape) devices are interfaced differently in SunOS and Solaris but a single IRAF installation now supports both, the distributed Sun/IRAF system comes with separate versions of the generic tapecap, one for SunOS and one for Solaris (a similar setup exists for PC-IRAF as well):

    tapecap.sunos     # SunOS template     
    tapecap.solaris   # Solaris template
  
The actual tapecap file for a client node can be set up (on Unix systems) as a symbolic link to a locally customized shared version of one of these files, or it could be a separate file which has been simplified and customized for a particular host. The latter approach eliminates device name conflicts and allows simple device names such as "mta" and "mtb" to be used for each node. For example, if we have hosts "corona" and "dosequis", the primary magtape device on each node could be named "corona!mta" and "dosequis!mta" (i.e., device "mta" on both nodes) and these devices would be accessible from any IRAF host on the local network.

As an example, assume we have a heterogeneous network of systems which are predominantly Solaris workstations all sharing a single central IRAF V2.11 installation. The tapecap files in the dev directory might then look something like the following:

link

tapecap -> tapecap.solaris

file

tapecap.sunos

file

tapecap.solaris

file

tapecap.corona

file

tapecap.dosequis

link

tapecap.ursa -> tapecap.solaris

link

tapecap.gemini -> tapecap.sunos

link

tapecap.tucana -> tapecap.sunos

(etc.)

 

 

In this example some of the client nodes have private tapecap files, while others share a central generic OS-dependent tapecap file. The catch-all default entry "tapecap" defaults to the generic tapecap file for Solaris.

The tapecap files included in the distributed system include some generic device entries for both SunOS and Solaris such as "mtxb1" (Exabyte unit 1, Sun ST driver), "mthp2" (HP7880 9 track drive, unit 2), and so on, which you may be able to use as-is to access your local magtape devices. Most likely you will want to add some device aliases, and you may need to prepare custom device entries for local devices. There must be an entry in the tapecap file for a magtape device in order to be able to access the device from within IRAF. All magtape device names must begin with the two-letter prefix "mt".

Configuring New TAPECAP Entries

The tapecap file is a text data base file (similar to the termcap and graphcap files and adhering to the standard BSD Unix termcap file format) describing the capabilities and device names associated with a particular tape device on the system. For information on the format of the file see the Unix termcap(5) man page. A listing of all recognized device fields is given in the program comments for the tape driver in iraf$unix/os/zfiomt.c (more on this later). In general creating a new tapecap entry for a device is a matter of finding a similar entry in the distributed file, and either using that directly if the device names are correct, or simply modifying it slightly to change device names so it will be appropriate for a drive on a different SCSI unit. On occasion other tapecap parameters will need to be added to correct for specific behavior that affects appending new data and tape positioning.

By convention a tapecap entry for a device is usually divided into three different sections: a high-level entry giving the host-specific name of the drive as known to IRAF, a mid-level section defining the host device names associated with the drive, and a low-level entry defining generic capabilities associated with all instances of a particular type of drive (DAT, Exabyte, 9-track, etc.). The starting point for the tapecap entry is whatever IRAF name was used to access the drive. This is usually something like "mta", "mtb", etc., but can be any valid name beginning with an "mt" prefix and which defines all the needed parameters. When searching for a particular tapecap parameter the first occurrence of that parameter in the entry is used by the system, and a complete tapecap description is composed of all the entries which are linked by the ":tc" continuation fields.

As an example consider a typical entry for a DAT drive on unit 0 known to a Solaris/IRAF system as "mta", the high-level entry would look like:

     mta|Generic DAT entry, unit 0|  :tc=mtst0.solaris.dat:
Here we define the IRAF name (which must begin with an "mt" prefix) along with any aliases delimited by the "|". The ":tc" field indicates that the tapecap entry continues the next entry named "mtst0.solaris.dat". This is an alias for the "mtsd0" entry as shown below:

     mtsd0|mtst0.solaris.dat|DAT drive on Solaris:\
       :al=0 0bn 0cb 0cn 0hb 0hn 0lb 0ln 0mb 0mn 0u 0ubn \
       0b 0c 0cbn 0h 0hbn 0l 0lbn 0m 0mbn 0n 0ub 0un:\
       :dv=0bn:lk=0:tc=solaris-dat:
This entry is primarily used to specify the host device names associated with the drive. The ":al" (aliases) field is a list of all device aliases in the Unix /dev or /dev/rmt directories associated with this device. This information is needed so the tape allocation task can change the permissions and ownership on each device name which accesses that tape drive. The ":dv" (device) field is the no-rewind device name and is the device file actually opened for tape I/O. This must be a no-rewind device for IRAF to be able to keep track of the tape position. The actual device name typically depends on the density of the tape, whether compression is used, etc. The ":lk" is used to build the name of a "lok file" that is created in the /tmp directory of the machine hosting the drive that will be used to maintain the tape status and position information; this value should be unique for each drive on the machine to avoid conflicts.

When configuring a new tapecap entry, all one usually needs to change is the IRAF device name in the first section and the host device names in the ":dv", ":al" and ":lk" fields of this entry. The host device name entry continues with a ":tc" field saying to branch to the "solaris-dat" generic device entry:

     solaris-dat|sdat-60m|Sun/Solaris DAT drive:\
     :dt=Archive Python 4mm Helical Scan tape drive:tt=DG-60M:\
     :ts#1274378:bs#0:mr#0:or#65536:fb#10:fs#127000:mf:fe#2000:
     
The low-level entry here is where parameters relating to all drives of a particular type using a particular host tape driver are maintained, e.g., the record sized used for tape I/O, positioning capabilities, filemark sizes, etc. These will rarely need to be changed from the distributed entries unless you are using a new tape driver or a different model tape drive, or a type of tape cartridge with a capacity different than that given ("tz"). See the section below for a full list of the tapecap parameters and their meanings.

For a more complicated example let's consider how to add an entry for an Exabyte 8505 drive given an existing entry for an Exabyte 8200 device. We can ignore for now the low-level entry found in the distributed tapecap and concentrate on what fields actually need changing in this case. We begin with the high-level entry defining the IRAF names, we will need one name for the drive in each of three modes (8200 mode, 8500 mode, and 8500 mode with compression):

     mta|Exabyte 8200, Unit 0|       :tc=mtst0.solaris.exb8200
     mtb|mtblo|Exabyte 8505, Unit 0| :tc=mtst0.exb8505-lo: 
     mtbhi|Exabyte 8505, Unit 0|     :tc=mtst0.exb8505-hi:
     mtbc|Exabyte 8505, Unit 0|      :tc=mtst0.exb8505-c:

The new IRAF names are therefore mtb (8200 mode), mtbhi (8500 mode), and mtbc (8500 + compression). These all link to the second level entry where we make use of the existing EXB8200 entry:

     mtsee0|mtst0.solaris.exb8200|Exabyte 8200 drive on Solaris:\
       :al=0 0bn 0cb 0cn 0hb 0hn 0lb 0ln 0mb 0mn 0u 0ubn \
       0b 0c 0cbn 0h 0hbn 0l 0lbn 0m 0mbn 0n 0ub 0un:
       :dv=0bn:lk=0:tc=solaris-exb8200:
     mtsee0lo|mtst0.exb8505-lo|:dv=0lbn:tc=mtsee0:
     mtsee0hi|mtst0.exb8505hi|:dv=0mbn:fs#48000:ts#5000000:tc=mtsee0:
     mtsee0hic|mtst0.exb8505c|:dv=0cbn:fs#48000:ts#5000000:tc=mtsee0:
Note that the names we just created link to the one-line entries below the standard EXB 8200 entry "mtst0.solaris.exb8200" (the mtb entry could just as legally have linked to this entry right away). Since all we need to change is the ":dv" field (because we're opening the same drive, but by using a different name the host system accesses it in the appropriate mode) we can simply make a new entry point, change the ":dv" field and then link to the existing entry where all the rest of the parameters will be the same. In this case we've also reset the ":fs" and ":ts" fields to override the values in the low-level Exabyte description since these have also changed for the new model drive. If we wished to modify this entry for a drive on, e.g., unit 2, all we would need to do is modify the various ":dv", ":al", and ":lk" fields so the device names are correct, and change the name of the tapecap entry points so we avoid any confusion later on.

When configuring a new tapecap and encountering problems it is useful to turn on status output so you get a better idea of where the tape is positioned and what's going on; to do this use the ":so" (status output) field. This can be included directly in the tapecap entry for the device or temporarily enabled on the command line as in the following examples:

Alternatively, the :so can be specified on the command line, e.g.,

Any other tapecap parameters can be included on the command line in the same way; these will override the defaults given in the tapecap file. The quotes around the tape name are required if any special characters such as "=" are included in the device name string. Status output like this can also be directed to an Xtapemon tape status server running either locally or remotely; see the Xtapemon man page for details. Help with configuring new tapecap entries is available from IRAF site support.

More on TAPECAP Parameters

As we see from the previous section, in most cases the only tapecap parameters that need to be changed are ":dv", ":al", and maybe ":lk". There are however a number of other tapecap parameters that sometimes must be modified to describe how the tape device operates or to optimize I/O to the device. A full listing of the available tapecap parameters can be found in the program comments for the IRAF tape driver (file iraf$unix/os/zfiomt.c ); we will only briefly discuss a few here. Any changes you make with the parameters mentioned here can usually go in the low-level tapecap entry so they will "fix" all drives of the same type. However, you may prefer to modify just the high-level entry so that only one drive is affected, particularly if you are correcting a feature that is only seen on a particular host and which does not reflect the generic behavior of the device. For example:

     mta|Generic DAT entry, unit 0|    :se:ow:tc=mtst0.solaris.dat:
would add the ":se:ow" fields (discussed below) to only the mta device.

Boolean tapecap parameters may be negated if you are linking to an existing entry which already defines a particular field. For example, in

     mta|Generic DAT entry, unit 0|    :se@:tc=mtst0.solaris.dat:
the "@" character would negate the ":se" field regardless of whether it is defined elsewhere in the entry.

One of the most common problems encountered is that only odd-numbered images on a tape are readable by the drive. The solution to this is usually to add a ":se" to the tapecap to tell the driver that the tape will position past EOT in a read. Another common problem is with appending new data to an existing tape; this sometimes requires the addition of an ":ow" field to tell the driver to backspace and overwrite the EOT when appending. A ":re" is sometimes needed if there is a problem sensing the EOT when reading all images from a tape; this tells the driver that a read at EOT returns an ERR.

The parameter ":fb" may be specified for a device to define the "optimum" FITS blocking factor for the device. Unless the user explicitly specifies the blocking factor, this is the value that the V2.11 wfits task will use when writing FITS files to a tape. Note that for cartridge devices a FITS blocking factor of 22 is used for some devices; at first this may seem non-standard FITS, but it is perfectly legal, since for a fixed block size device the FITS blocking factor serves only to determine how the program buffers the data (for a fixed block device you get exactly the same tape regardless of the logical blocking factor). For non-FITS device access the magtape system defines an optimum record size which is used to do things like buffer data for cartridge tape devices to allow streaming.

Some devices, e.g., most Exabyte drives, are slow to switch between read and skip mode, and for files smaller than a certain size, when skipping forward to the next file, it will be faster to read the remainder of the file than to close the file and do a file skip forward. The ":fe" parameter is provided for such devices, to define the "file equivalent" in kilobytes of file data, which can be read in the time that it takes to complete a short file positioning operation and resume reading. Use of this device parameter in a tape scanning application such as rfits can make a factor of 5-10 difference for some devices in the time required to execute a tape scan of a tape containing many small files.

On a device such as most cartridge tape devices where backspacing is not permitted or does not work reliably, it may be necessary to set the ":nf" parameter to tell the driver to rewind and space forward when backspacing to a file.

Lastly, when configuring a new low-level generic entry for the device it is sometimes necessary to change the various size parameters for the drive. These include:

bs

device block size (0 if variable)

fb

default FITS blocking factor (recsize=fb*2880)

fe

time to FSF equivalent in file Kb

mr

maximum record size

or

optimum record size

fs

approximate filemark size (bytes)

ts

tape capacity (MB)

dn

density

All but the last three fields are used either by the driver or a task when reading or writing a tape. The ":fs", ":ts" and ":dn" fields are used by tape monitoring tasks such as Xtapemon to compute the approximate amount of tape used and do not affect tape operation. For devices which are capable of variable block size I/O (i.e., almost anything but a cartridge tape) it is best to leave the ":bs" field set to zero. The maximum and optimum record sizes, the ":mr" and ":or" fields, are usually determined by the host tape driver used. Values for these can either be found in the host driver man page or its system include file.

Mike Fitzpatrick, Doug Tody

[ Previous ] [Next ] [ Table of Contents ] [ Search this issue ]

IRAF Group, National Optical Astronomy Observatories, P.O. Box 26732, Tucson, AZ 85726, Phone: (520) 318-8160, FAX: (520) 318-8360, Email iraf@noao.edu

Posted: 07May1998