NAME

tu58 − routines to access TU58 tape drives attached to the VAX

SYNOPSIS

topen(drive, mode, name)
char ∗drive;
int mode;
char ∗name;

tclose(dn)
int dn;

tseek(dn, offset, whence)
int dn;
int offset;
int whence;

tread(dn, buf, nbytes)
int dn;
char ∗buf;
int nbytes;

twrite(dn, buf, nbytes)
int dn;
char ∗buf;
int nbytes;

#include <tu58io.h>
tioctl(dn, request, arg)
int dn;
int request;
union tio ∗arg

#include <tu58errno.h> extern int terrno; tperror(str) char ∗str;

DESCRIPTION

These routines manipulate a TU58 tape drive unit that is attached directly to the VAX.  They are obtained by loading the library lib58.a. These routines do all the tape controlling including mutual exclusion of users (but not that of a user’s processes). 

The TU58 has two drives on one controller.  These routines treat each drive as a separate file; that is, each must be opened individually, operations may be intermixed, and they can be closed in any order. 

Topen opens drive drive for reading (if mode is 0), writing (if mode is 1) or for both reading and writing (if mode is 2).  Drive is the address of a string of ASCII characters representing the drive number; only the first character is used.  Legal drive names are “0” and “1”.  File is the name of the port to which the TU58 is attached; if given as NULL, the port /dev/LSIfast is used. 

The opened drive is positioned at the beginning (block 0), and is opened with the verification bit set and the special addressing and maintenance modes cleared.  (To change these, see tioctl, below.) The returned drive descriptor must be used for subsequent calls for other input-output functions on the drive. On error, -1 is returned.

Given a drive descriptor dn returned from a topen call, tclose closes the associated drive.  If all drives on the TU58 are closed, it also releases the unit.  Note that this routine is not invoked automatically; it must be called explicitly. 

Given a drive descriptor dn returned from a topen call, and the address buf which is the location of nbytes contiguous bytes into which the input will be placed, tread will read nbytes bytes into the buffer.  The number of characters read, or -1 (on error), is returned.  Note that reading begins at a block boundary, and that there is no concept of “end of file”. 

Given a drive descriptor dn returned from a topen call, and the address buf which is the location of nbytes contiguous bytes which are to be written to the drive, twrite will write nbytes bytes from the buffer to the drive.  The number of characters written, or -1 (on error), is returned.  Note that writing begins at a block boundary,

Given a drive descriptor dn returned from a topen call and a request request, tioctl will either alter a characteristic of the drive, or return information about the drive.  Legal requests are:

request effect

TU58SSAM set special addressing mode

TU58CSAM clear special addressing mode

TU58SVFY set verification mode

TU58CVFY clear verification mode

TU58SMTM set maintenance mode

TU58CMTM clear maintenance mode

TU58SPOS set new position; unlike tseek, this does not move the tape, but the next operation will take place at the current position. Arg is a pointer to an integer, which is the new block number. 

TU58GDCB return the drive control block.  This copies the drive control block into the locations pointed to by arg; the structure is defined in Xinu-directory/include/tu58io.h.

On error, tioctl returns -1; on success, 0.  The requests are defined in the include file Xinu-directory/include/tu58io.h.

ERROR HANDLING

Errors are handled uniformly; if the operation failed, the attempted command is aborted and an error flag is returned.  This flag is always -1.  To obtain more detailed error messages, there is a routine tperror which prints its argument string, followed by a brief message describing the last error that occurred.  There is an external variable, terrno, that contains a code number indicating the last error. Its values are in Xinu-directory/include/tu58errno.h.

There is one error that will not return an error code, even though terrno is set (and so tperror will report it); namely, if the operation succeeded but retries were necessary.  This is a TU58 error code; the only routine that ever sends something more than once is the routine that initializes communications between the VAX and the TU58. 

AUTHOR

Matt Bishop (mab)

BUGS

Sometimes the TU58 does not respond to an initialization command.  When this happens, check the connections and try again. 

December 01, 1986  —  Xinu Programmer’s Manual