DST/DIS SCSI Tape Drive UNIX Software Programmer's Guide FOR Digital Equipment Corporation Digital UNIX Hewlett-Packard HP-UX IBM AIX Silicon Graphics IRIX Sun Microsystems Solaris ® TM 1308911-02 NOTICE The contents of this technical manual have been checked and are believed to be accurate. However, no responsibility is assumed for any inaccuracies in the information provided herein. Ampex Corporation reserves the right to make changes without notice to improve reliability, function or design. TRADEMARKS AIX is a registered trademark of International Business Machines Corporation. DEC is a trademark of Digital Equipment Corporation. DST is a registered trademark of Ampex Corporation. DIS is a trademark of Ampex Corporation. IRIX is a registered trademark of Silicon Graphics Incorporated. Solaris is a registered trademark of Sun Microsystems, Inc. UNIX is registered trademark licensed exclusively by X/Open Co., Ltd. All other trademarks and registered trademarks are the property of their respective holders. COPYRIGHT INFORMATION U.S. GOVERNMENT RESTRICTED RIGHTS: Software and any documentation are provided with RESTRICTED RIGHTS. Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013 and Rights in Data-General, including Alternate III, at FAR 52.227-14, as applicable. Prepared by Technical Publications Ampex Corporation 500 Broadway Redwood City, CA 94063-3199 Copyright © 1995-96 by Ampex Corporation All rights reserved Part No. Ampex 1308911-02 Issued: August 2000 DST/DIS Tape Drive UNIX Programmer's Guide Addendum Addendum Introduction This addendum provides supplementary information applicable to using the libdd2 API version 6.0 with SGI Irix 6.5 tpsc magnetic tape (mt) and devscsi passthru (pt) devices, or Irix 6.4 TDR tpsc devices. The information covers only those features that are unique to the IRIX TDR5 configuration. See the remainder of the document for information on other features that are common to all supported UNIX platforms. API Functions In the IRIX TDR5 environment, the libdd2 API uses the SGI tpsc or devscsi driver rather than the Ampex DST tape device driver. Those functions that could not be implemented through the mt interface to the tpsc driver were replaced by SCSI passthru versions that use the pt interface to the devscsi driver. · The following functions, identified by the suffix _pt, use the passthru interface to the devscsi driver. They behave the same as the standard functions that are available on other platforms. See the manual pages in Section 5 for details. Passthru Functions dst_clrlog_pt() dst_format_pt() dst_getdrive_pt() dst_getdrive_ex_pt() dst_getlog_pt() dst_gettrace_pt() dst_setdrive_pt() dst_setpart_pt() dst_status_pt() Standard Functions dst_clrlog() dst_format() dst_getdrive() dst_getdrive_ex() dst_getlog() dst_gettrace() dst_setdrive() dst_setpos() dst_status() · The following functions use the mt interface to the tpsc device driver but behave differently than on other supported platforms. When referring to the manual pages in Section 5, note the following: ­ ­ dst_getparam() reports only those attributes that are available under IRIX TDR5 (see "Device Special Files" on page iv). dst_setparam() is not capable of setting the device driver debug level. In addition it can set the data block size only when the drive is positioned to BOT or immediately after a filemark. Ampex 1308911-02 iii Running Head Addendum Model No. DST/DIS Tape Drive UNIX Programmer's Guide ­ dst_setpos() accommodates tape formats up to 255 partitions. If you need additional positioning capability, use dst_setpart_pt() which accommodates tape formats up to 1024 partitions. dst_status() does not clear an error code. The last error code is retained until it is overwritten by another error code. dst_version() does not report device driver strings. ­ ­ · The following functions use the mt interface to the tpsc device driver and behave the same as on other supported platforms. See the manual pages in Section 5 for details. dst_convpos() dst_getpos() dst_getstate() dst_rewind() dst_space() dst_unload() dst_weof() dst_weof_ex() · The following functions use the mt interface to the tpsc device driver but are available only on an IRIX TDR5 platform. See the manual pages at the end of this Addendum for details. ­ ­ dst_getptpathname() returns the devscsi path name required to use a *_pt function. dst_setnoflush() sets the noflush interface parameter to on or off. · The dst_reset() function is not available; use "scsiha -r " to reset the scsi bus. Device Special Files An application accesses the IRIX tpsc device driver by specifying one of the following device special files in the open() call: tpsXDY tpsXDYnr tpsXDYnrns tpsXDYnrs tpsXDYns tpsXDYs tpsXDYstat rewind no rewind no rewind, no byte swap no rewind, byte swap no byte swap byte swap mt status Functions that use the mt interface to the device driver must specify the file descriptor (fd) returned by the open() call. iv Ampex 1308911-02 DST/DIS Tape Drive UNIX Programmer's Guide Addendum Note: To use pt functions, the function goes through the devscsi driver. Upon every system reboot, devscsi permissions are reset to root access only. Therefore, to use the passthru function, the devscsi permissions must be changed to give user read/write access after every reboot. Functions that use the pt interface must specify a file descriptor that provides a devscsi path name. To obtain a devscsi file descriptor: 1. open() the tpsc device driver for mt operation. 2. Run dst_getptpathname() to get a devscsi path name (based on the tpsc file descriptor that is currently open). 3. Close the tpsc file descriptor. 4. Open the devscsi device driver using the path name obtained in step 2. Use the file descriptor returned by the open() call for the *_pt function(s). Ampex 1308911-02 v Running Head Addendum Model No. DST/DIS Tape Drive UNIX Programmer's Guide dst_setnoflush() NAME dst_setnoflush() - select buffered or unbuffered filemarks. SYNOPSIS #include int dst_setnoflush(int fd, int noflush_setting); DESCRIPTION dst_setnoflush() configures the DST_NO_FLUSH drive interface parameter which controls whether or not the buffer is flushed to tape when filemarks are written. · When DST_NO_FLUSH is set to on, any filemarks written to tape are buffered and the tape drive buffer is not flushed to tape on close. One exception is that if a flush buffer command is issued (i.e., write zero filemarks), the tape drive buffer is flushed to tape regardless of this parameter setting. When DST_NO_FLUSH is set to off, filemarks written to tape are unbuffered and the tape drive buffer is flushed to tape on close. · The DST_NO_FLUSH setting is retained until the tape drive is power off or it is changed using this function. The default setting is off. To view the current setting, use dst_getparam() or dd2_getparam_drive. dst_setnoflush() is available to all users. PARAMETERS fd noflush_setting The file descriptor returned by the open call. Integer value; 0 for off (default), nonzero for on. RETURN VALUES The return value is DST_SUCCESS (0) or DST_FAILURE (-1). See the dst_api_intro() manual page for information on errno failure messages and associated DST result codes. SEE ALSO dst_getparam(), dd2_getparam_drive vi Ampex 1308911-02 DST/DIS Tape Drive UNIX Programmer's Guide Addendum dst_getptpathname() NAME dst_getptpathname() - get devscsi pathname needed for libdd2 API passthru (*_pt) functions. SYNOPSIS #include int dst_getptpathname(int fd, char *devscsi_name, int namelen); DESCRIPTION dst_getptpathname() retrieves the devscsi pathname of an open tpsc scsi device. It is available to all users. PARAMETERS fd *devscsi_name noflush_setting The tpsc file descriptor returned by the open call. Pointer to a buffer allocated for storage of the devscsi path name. The size of the buffer (number of bytes). The buffer must be large enough to hold the full pathname plus the terminating zero byte; i.e., max pathname size = 256 bytes + 1. NOTES The scsi device should have permissions set to allow read and write. In order to use a libdd2 *_pt function: 1. open() the tpsc device driver for mt operation. 2. Use dst_getptpathname() to obtain the devscsi path name. 3. Close the tpsc file descriptor and obtain a new file descriptor by opening the scsi device using the devscsi path name. 4. Use the file descriptor returned by the devscsi open() call for the *_pt function call. When through, close the pt file descriptor and reopen the original tpsc device to obtain a new tpsc file descriptor. Ampex 1308911-02 vii Running Head Addendum Model No. DST/DIS Tape Drive UNIX Programmer's Guide RETURN VALUES The return value is DST_SUCCESS (0) or DST_FAILURE (-1). See the dst_api_intro() manual page for information on errno failure messages and associated DST result codes. viii Ampex 1308911-02 DST/DIS Tape Drive UNIX Programmer's Guide Addendum dd2_setnoflush_drive NAME dd2_setnoflush_drive - Set or reset the noflush drive setting. USE When set, filemarks are buffered. When reset, the buffer is flushed when filemarks are written. this setting can be read back from the drive as the DST_NO_FLUSH bit in the attrib field of the ddt_getparam_drive command. This setting persists within the drive until set/reset again by command or power-on. USAGE dd2_setnoflush_drive - noflush (this flag is required except it OPTIONS fd noflush_setting The file descriptor returned by the open call. Integer value; 0 for off (default), nonzero for on. RETURN VALUES The return value is DST_SUCCESS (0) or DST_FAILURE (-1). See the dst_api_intro() manual page for information on errno failure messages and associated DST result codes. SEE ALSO dst_getparam(), dd2_getparam_drive Ampex 1308911-02 ix Running ContentsHead Model No. DST/DIS Tape Drive UNIX Programmer's Guide Contents Addendum Introduction .................................................................................................................. iii API Functions ............................................................................................................... iii Device Special Files ..................................................................................................... iv dst_setnoflush() ............................................................................................................ vi dst_getptpathname() ..................................................................................................... vii dd2_setnoflush_drive ................................................................................................... ix Section 1 General Information 1.1 1.2 1.3 1.4 1.5 1.6 1.7 Introduction .................................................................................................... 1-1 Manual Contents ............................................................................................ 1-2 Notational Conventions ................................................................................. 1-3 Notices and Notes .......................................................................................... 1-4 Related Documents ........................................................................................ 1-4 Technical Support .......................................................................................... 1-5 Documentation Support ................................................................................. 1-5 Section 2 Software Overview 2.1 2.2 2.3 2.4 2.4.1 2.4.2 2.4.3 2.4.4 2.4.5 2.5 2.5.1 2.5.2 2.5.3 2.5.4 2.5.5 Introduction .................................................................................................... 2-1 Tape Device Driver ........................................................................................ 2-1 Tape Drive Behavior ...................................................................................... 2-5 libdd2 API Overview ..................................................................................... 2-5 Operation of libdd2 .................................................................................... 2-6 Function Return Values ............................................................................. 2-6 Errors.......................................................................................................... 2-6 UNIX Platform Compatibility ................................................................... 2-6 Restrictions ................................................................................................ 2-6 DD2 Utilities Overview ................................................................................. 2-7 Exit Status ............................. ...