Document:     MTIODEV

Purpose:      Describes the tape manipulation routines and setup.

Category:     TAPES

File:         mtiodev.c

Author:       K.G. Begeman

Description:  The mtiodev routines can read/write data from/to tapes
              and files. The structure of a 'disktape' is as follows:
              The name of a disktape is the name of a directory. This
              directory contains the data files "file<filenum>.mt" and
              the tape descriptor file "tape.descriptor". The descriptor
              file is a text file which contains a description of the
              structure on a real tape (i.e. information about records and
              file markers), the binary files contain the data on the tape.
              <filenum> indicates the sequence number of the file on the
              disktape. There is a one to one relation between the number
              of tape marks skipped so far and <filenum> (<filenum> =
              number of tape marks plus one). So the data structure on a
              real tape can be completely simulated on disk, as is shown
              below:

              Structure on tape       Structure on disk

                                      tape.descriptor
              BLOCK of fb11 bytes     "@file000001.mt"
                                      "fb11"
              BLOCK of fb12 bytes     "fb12"
              ..... .. .... .....     "...."
              BLOCK of fb1n bytes     "fb1n"
              TAPE MARK               "0"
              BLOCK of fb21 bytes     "@file000002.mt"
                                      "fb21"
              ..... .. .... .....     "...."
              BLOCK of fb2n bytes     "fb2n"
              TAPE MARK               "0"
              ...
              ...
              TAPE MARK               "0"
              TAPE MARK               "0"

              Importing foreign disktape files is very simple. One can
              either create the file "tape.descriptor" with an editor, or
              rename the data files to be imported "file000001.mt",
              "file000002.mt" etc. Whenever a disktape is opened with
              MTOPEN, it will check whether the tape descriptor file exists.
              When it does not exist, MTOPEN will check whether there is
              a file named "file000001.mt". If so, MTOPEN will assume that
              the blocking factor is 2880 bytes (FITS standard) and create
              the tape descriptor file. Then it will check whether a
              file with name "file000002.mt" exists etc.

              A tape device, be it a tapeunit or a disk file, is opened
              with function MTOPEN. MTOPEN has one argument, a character
              string denoting the name of the device. If the name corresponds
              with the name of a tape unit in $gip_loc/mtdevices (not
              case sensitive), this unit will be used, otherwize it is assumed
              to be a directory on disk. The argument to MTOPEN may also be
              a question mark (?), optionally followed by a keyword. This
              means that MTOPEN will prompt the user for a tape device
              (with keyword MTDEVICE= or the keyword specified after the
              question mark), and list the available tape units (if the
              user wants it). The syntax of $gip_loc/mtdevices is described
              in $gip_doc/mtdevices.doc.

              After a succesful call to MTOPEN, the returned TAPEID is
              used to denote this tape device in further calls to MTIODEV
              routines.

              The following tape manipulation functions are available:

              MTOPEN   Opens a tape device.
              MTCLOSE  Closes an opened tape device.
              MTREW    Rewinds an opened tape device.
              MTSTAT   Returns status of an opened tape device.
              MTREAD   Reads a block from an opened tape device.
              MTWRITE  Writes a block to an opened device.
              MTFSF    Forward spaces a tape mark on an opened device.
              MTBSF    Backward spaces a tape mark on an opened device.
              MTFSR    Forward spaces a block on an opened device
              MTBSR    Backward spaces a block on an opened device
              MTWEOF   Writes tape mark to an opened tape device.
              MTNAME   Returns name (synonym) of tape device.

              Each routine is described in more detail in the
              appropriate document.

Notes:        For disktapes, files containing the real data may have any
              legal name (excluding <cr> and space). The correct filename
              should then be inserted in the tape.descriptor file, preceded
              by a @.

Related Docs: rmtserver.dc1

Updates:      Mar 27, 1990: KGB Document created.
              Oct 31, 1990: KGB Remote tapeserver implemented.
              Jun 24, 1991: PRR Implemented use of read-only disk-tapes.
              Oct 15, 1991: KGB Better implementation of mtopen.
              Dec 11, 1991: KGB Call to cancel replaced by call to reject.
              Jun 13, 1997: KGB Allowed non BSD compatible devices on solaris.
              Jan 22, 1998: KGB Implemented DLT on hpux.
              Nov  5, 1999: JPT Support generic DAT for Solaris.
              Feb 23, 2001: KGB Support DLT for Solaris.
              Jun 22, 2010: JPT Fix to prevent compilation failure on Apple.