Ampex Data Systems DST, DIS User Manual

Download

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

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.

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

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) de vices, or Irix

6.4 TDR tpsc devices. The information cov ers only those features that are unique to the IRIX TDR5 conﬁguration. 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 interface to the

The following functions, identiﬁed by the sufﬁx

•

devscsi driver . They behav e the same as the standard functions that are av ailable on other

platforms. See the manual pages in Section 5 for details.

assthru Functions Standard Functions

dst_clrlog_pt() dst_clrlog() dst_format_pt() dst_format() dst_getdrive_pt() dst_getdrive() dst_getdrive_ex_pt() dst_getdrive_ex() dst_getlog_pt() dst_getlog() dst_gettrace_pt() dst_gettrace() dst_setdrive_pt() dst_setdrive() dst_setpart_pt() dst_setpos() dst_status_pt() 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:

devscsi

tpsc

driver were replaced by SCSI passthru versions that use the pt

driver.

_pt,

use the passthru interface to the

– 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 driv er deb ug le vel. In addition

it can set the data block size only when the drive is positioned to BOT or immediately after a ﬁlemark.

Ampex 1308911-02 iii

–

Running Head

Addendum 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()

Model No.

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

function.

– dst_setnoﬂush() sets the noﬂush interface parameter to on or off.

•

The dst_reset() function is not available; use “scsiha -r <controller number>” to reset the scsi bus.

*_pt

Device Special Files

An application accesses the IRIX tpsc device driv er by specifying one of the following de vice special ﬁles 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

status

Functions that use the mt interface to the device driver must specify the ﬁle descriptor (fd) returned by the open() call.

iv Ampex 1308911-02

DST/DIS Tape Drive UNIX Programmer’s Guide Addendum

Note:

Functions that use the pt interface must specify a ﬁle descriptor that provides a devscsi path name. To obtain a

2. Run

3. Close the

4. Open the

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.

devscsi

open()

that is currently open).

descriptor returned by the

the

tpsc

dst_getptpathname()

tpsc

ﬁle descriptor.

devscsi

ﬁle descriptor:

device driver for mt operation.

to get a

device driver using the path name obtained in step 2. Use the ﬁle

open()

devscsi

call for the

path name (based on the

*_pt

function(s).

tpsc

ﬁle descriptor

Ampex 1308911-02 v

Running Head

Addendum DST/DIS Tape Drive UNIX Programmer’s Guide

Model No.

dst_setnoflush()

NAME

dst_setnoﬂush() - select buffered or unbuffered ﬁlemarks.

SYNOPSIS

#include <dd2.h> int dst_setnoﬂush(int fd, int

DESCRIPTION

dst_setnoﬂush() conﬁgures the

whether or not the buffer is ﬂushed to tape when ﬁlemarks are written.

When

•

tape drive buffer is not ﬂushed to tape on close . One exception is that if a ﬂush buffer command is issued (i.e., write zero ﬁlemarks), the tape drive buffer is ﬂushed to tape regardless of this parameter setting.

DST_NO_FLUSH

noﬂush_setting

DST_NO_FLUSH

is set to on, any ﬁlemarks written to tape are buffered and the

);

drive interface parameter which controls

When

•

The

DST_NO_FLUSH

this function. The default setting is off. To view the current setting, use dst_getparam() or

dd2_getparam_drive . dst_setnoﬂush() is available to all users.

DST_NO_FLUSH

drive buffer is ﬂushed to tape on

PARAMETERS

noﬂush_setting

RETURN V ALUES

The return value is manual page for information on

SEE ALSO

is set to off, ﬁlemarks written to tape are unbuf fered and the tape

setting is retained until the tape drive is po wer off or it is changed using

The ﬁle descriptor returned by the open call.

Integer value; 0 for off (default), nonzero for on.

DST_SUCCESS

(0) or

errno

DST_FAILURE

failure messages and associated DST result codes.

(-1). See the dst_api_intro()

dst_getparam() , dd2_getparam_drive

vi Ampex 1308911-02

DST/DIS Tape Drive UNIX Programmer’s Guide Addendum

dst_getptpathname()

NAME

dst_getptpathname()

functions.

SYNOPSIS

include <dd2.h>

int dst_getptpathname(int fd, char

DESCRIPTION

dst_getptpathname() retrieves the to all users.

PARAMETERS

fd *devscsi_name Pointer to a buffer allocated for storage of the devscsi path name.

noﬂush_setting The size of the buffer (number of bytes). The buffer must be large

- get

devscsi

The

tpsc

enough to hold the full pathname plus the terminating zero byte; i.e., max pathname size = 256 bytes + 1.

pathname needed for

*devscsi_name

devscsi

ﬁle descriptor returned by the

pathname of an open

, int

libdd2

namelen

API passthru (

);

tpsc

scsi device. It is av ailable

open

call.

*_pt

)

NOTES

The scsi device should have permissions set to allow read and write. In order to use a libdd2

1. open() the tpsc device driver for mt operation.

2. Use dst_getptpathname() to obtain the devscsi path name.

3. Close the tpsc ﬁle descriptor and obtain a new ﬁle descriptor by opening the scsi device using the devscsi path name.

4. Use the ﬁle descriptor returned by the devscsi open() call for the

When through, close the pt ﬁle descriptor and reopen the original tpsc device to obtain a new tpsc ﬁle descriptor.

Ampex 1308911-02 vii

*_pt function:

*_pt function call.

Running Head

Addendum DST/DIS Tape Drive UNIX Programmer’s Guide

Model No.

RETURN V ALUES

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_setnoﬂush_drive - Set or reset the noﬂush drive setting.

USE

When set, ﬁlemarks are buffered. When reset, the buffer is ﬂushed when ﬁlemarks are written. this setting can be read back from the drive as the DST_NO_FLUSH bit in the attrib ﬁeld of the ddt_getparam_drive command. This setting persists within the drive until set/reset again by command or power-on.

USAGE

dd2_setnoﬂush_drive - noﬂush <noﬂush_setting> (this ﬂag is required except it

OPTIONS

fd The ﬁle descriptor returned by the open call.

noﬂush_setting Integer value; 0 for off (default), nonzero for on.

RETURN V ALUES

The return value is DST_SUCCESS (0) or DST_FAILURE (-1). See the dst_api_intro() manual page for information on

SEE ALSO

dst_getparam(), dd2_getparam_drive

errno failure messages and associated DST result codes.

Ampex 1308911-02 ix

Running Head

Contents DST/DIS Tape Drive UNIX Programmer’s Guide

Model No.

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 Introduction ....................................................................................................1-1

1.2 Manual Contents ............................................................................................1-2

1.3 Notational Conventions .................................................................................1-3

1.4 Notices and Notes ..........................................................................................1-4

1.5 Related Documents ........................................................................................1-4

1.6 Technical Support ..........................................................................................1-5

1.7 Documentation Support .................................................................................1-5

Section 2 Software Overview

2.1 Introduction ....................................................................................................2-1

2.2 Tape Device Driver ........................................................................................2-1

2.3 Tape Drive Behavior ......................................................................................2-5

2.4 libdd2 API Overview .....................................................................................2-5

2.4.1 Operation of libdd2.................................................................................... 2-6

2.4.2 Function Return Values ............................................................................. 2-6

2.4.3 Errors.......................................................................................................... 2-6

2.4.4 UNIX Platform Compatibility ................................................................... 2-6

2.4.5 Restrictions ................................................................................................2-6

2.5 DD2 Utilities Overview .................................................................................2-7

2.5.1 Exit Status.................................................................................................. 2-7

2.5.2 Errors.......................................................................................................... 2-7

2.5.3 UNIX Platform Compatibility ................................................................... 2-7

2.5.4 Open behavior............................................................................................2-7

2.5.5 Restrictions ................................................................................................2-7

Section 3 DD-2 Tape Format

3.1 Introduction ....................................................................................................3-1

3.2 DST Cartridge ................................................................................................ 3-1

x Ampex 1308911-02

DST/DIS Tape Drive UNIX Programmer’s Guide Contents

3.3 DD-2 Tape Entities .........................................................................................3-1

3.4 DD-2 Format Types .......................................................................................3-2

3.4.1 System Zones..............................................................................................3-3

3.4.2 Partitions.....................................................................................................3-3

3.4.3 File Sections ...............................................................................................3-4

3.4.4 Data Blocks.................................................................................................3-4

3.5 Instrumentation and Data Storage Recording ................................................3-5

Section 4 Tape Drive Operational Characteristics

4.1 Introduction ....................................................................................................4-1

4.2 Tape Drive Block Size ...................................................................................4-3

4.3 Tape Partitions ................................................................................................4-3

Section 5 libdd2 API Functions

5.1 Introduction ....................................................................................................5-1

5.2 DST API Overview ........................................................................................5-1

5.2.1 libdd2 Functions Summary.........................................................................5-1

5.2.2 Position Specifications ...............................................................................5-2

dst_position_st........................................................................................5-2

dst_pos_type_en.....................................................................................5-3

dst_position_un ......................................................................................5-3

dst_pos_tok_t..........................................................................................5-4

dst_dd2_pos_st.......................................................................................5-4

dst_600_pos_st Structure .......................................................................5-5

dst_dis_pos_st Structure.........................................................................5-6

5.2.3 Return Values.............................................................................................5-7

5.2.4 See Also....................................................................................................5-11

5.3 dst_clrlog ......................................................................................................5-12

5.4 dst_convpos ..................................................................................................5-13

5.5 dst_format .....................................................................................................5-16

5.6 dst_getdrive ..................................................................................................5-22

5.7 dst_getdrive_ex ............................................................................................5-26

5.8 dst_getlog .....................................................................................................5-31

5.9 dst_getparam ................................................................................................5-35

5.10 dst_getpos .....................................................................................................5-38

5.11 dst_getstate ...................................................................................................5-40

5.12 dst_gettrace ...................................................................................................5-42

5.13 dst_reset ........................................................................................................5-45

5.14 dst_rewind ....................................................................................................5-46

5.15 dst_setdrive ...................................................................................................5-47

5.16 dst_setparam .................................................................................................5-51

5.17 dst_setpos .....................................................................................................5-54

5.18 dst_space ......................................................................................................5-57

5.19 dst_status ......................................................................................................5-59

5.20 dst_unload ....................................................................................................5-63

Ampex 1308911-02 xi

Running Head

Contents DST/DIS Tape Drive UNIX Programmer’s Guide

5.21 dst_version ...................................................................................................5-64

5.22 dst_weof .......................................................................................................5-66

5.23 dst_weof_ex .................................................................................................5-68

Model No.

Section 6 DD-2 Utilities Manual Pages

6.1 Introduction ....................................................................................................6-1

6.2 DD-2 Utilities Overview ................................................................................6-1

6.2.1 Utilities....................................................................................................... 6-1

6.2.2 Input Conventions......................................................................................6-2

6.2.3 Output Conventions ................................................................................... 6-3

6.2.4 Arguments..................................................................................................6-3

6.2.5 Options.......................................................................................................6-4

6.2.6 Environment............................................................................................... 6-5

6.2.7 Exit Status.................................................................................................. 6-5

6.2.8 See Also ..................................................................................................... 6-6

6.3 dd2_clrlog_drive ............................................................................................6-7

6.4 dd2_format_tape ............................................................................................ 6-9

6.5 dd2_getlog_drive ......................................................................................... 6-14

6.6 dd2_getparam_drive .................................................................................... 6-17

6.7 dd2_getpos_tape .......................................................................................... 6-20

6.8 dd2_gettrace_drive ......................................................................................6-23

6.9 dd2_query_drive .......................................................................................... 6-25

6.10 dd2_query_tape ............................................................................................6-31

6.11 dd2_read_perf .............................................................................................. 6-35

6.12 dd2_reset_drive ............................................................................................6-38

6.13 dd2_rewind_tape ..........................................................................................6-40

6.14 dd2_set_drive ...............................................................................................6-42

6.15 dd2_setparam_drive .....................................................................................6-46

6.16 dd2_setpos_tape ...........................................................................................6-49

6.17 dd2_space_tape ............................................................................................6-53

6.18 dd2_status_drive .......................................................................................... 6-56

6.19 dd2_unload_tape ..........................................................................................6-59

6.20 dd2_weof_tape .............................................................................................6-61

6.21 dd2_write_perf .............................................................................................6-63

Appendix A Glossary and Acronyms

A.1 Glossary ........................................................................................................ A-1

A.2 Acronyms .................................................................................................... A-13

Appendix B Device Special Files

B.1 Introduction ....................................................................................................B-1

xii Ampex 1308911-02

DST/DIS Tape Drive UNIX Programmer’s Guide Contents

Appendix C Result Codes and Machine Status

C.1 Introduction ................................................................................................... C-1

Appendix D MSR Diagnostic Status Information

D.1 Introduction ...................................................................................................D-1

D.2 RF Status Field ..............................................................................................D-1

D.3 Latched/Continuous Status Field ..................................................................D-2

D.4 Physical Block Related Status Field ............................................................D-13

Appendix E Statistics

E.1 Introduction ................................................................................................... E-1

E.2 Service Statistics Parameters (Log Page 31h) ...............................................E-1

E.3 Operational Statistics Parameters 1 (Log Page 32h) .....................................E-3

E.4 Operational Statistics Parameters 2 (Log Page 33h) .....................................E-4

Ampex 1308911-02 xiii

Running Head

Figures DST/DIS Tape Drive UNIX Programmer’s Guide

Model No.

Figures

3-1 DD-2 Tape Entities .............................................................................................................. 3-2

xiv Ampex 1308911-02

DST/DIS Tape Drive UNIX Programmer’s Guide Tables

Tables

2-1 DST/DIS Tape Drive Software Operations ......................................................................2-2

2-2 DST/DIS Tape Device Driver Interfaces............................................................................2-5

3-1 DST and DIS Tape Format Compatibility..........................................................................3-5

4-1 DST/DIS Tape Drive Basic Behavior ...............................................................................4-1

4-2 Tape Drive Behavior Required for tar and dd.....................................................................4-2

B-1 AIX Device Special File Default Interface Parameters Settings .....................................B-2

B-2 DEC, HP-UX, and Solaris Device Special File Default Interface Parameters Settings .B-3

B-3 DST/DIS Device Special File Default Interface Parameters Settings .............................B-4

B-4 AIX Device Special Files Default Actions ......................................................................B-5

B-5 .DEC, HP-UX, and Solaris Device Special Files Default Actions ................................B-10

B-6 DST/DIS Device Special Files Default Actions ...........................................................B-15

B-7 Actions Controlled by DST/DIS Device Special Interface Parameters .........................B-19

B-8 Device Special File Interface Parameter Description ....................................................B-21

C-1 MSI Result Code Definitions.............................................................................................C-1

C-2 MSR Result Code Definitions............................................................................................C-2

C-3 Tape Drive Result Codes ...................................................................................................C-6

C-4 Machine Status Definitions................................................................................................C-9

C-5 Bitmasks for Valid Member of dst_result_st...................................................................C-10

C-6 Rclass Member of dst_result_st.......................................................................................C-10

C-7 Severity Member of dst_result_st ....................................................................................C-11

D-1 RF Status Parameters ........................................................................................................D-1

D-2 Latched/Continuous Status Parameters ............................................................................D-2

D-3 Physical Block Related Status Parameters ......................................................................D-13

E-1 Service Statistics Log Parameters – Log Page 31h ...........................................................E-1

E-2 Transport Operational Statistics 1 Log Parameters – Log Page 32h ...............................E-3

E-3 Electronics Operational Statistics 2 Log Parameters – Log Page 33h ............................. E-4

Ampex 1308911-02 xv

General Information Introduction

Section 1 General Information

1.1 Introduction

Ampex DST/DIS tape drives write data to and read data from a DST cartridge — a high-capacity magnetic tape media incorporating the DD-2 (Data Digital-2) tape standard. This document describes how to use the Ampex DST/DIS tape drive softw are installed on your UNIX host system. The software includes Version 6.0 of the Tape Management Utilities and a

libdd2

The Tape Management Utilities are a set of programs that provide command-line access to an Ampex DST or DIS tape drive. The y are compatible with the DST/DIS Automated Cartridge (ACL) Utilities as well as standard UNIX tape drive utilities (such as forth). All Ampex DST/DIS utilities are designed for use in scripts that perform higher-level operations, so they use a consistent set of input and output conventions that make them easy to integrate.

Application Programming Interface (API).

tar, dd, buffer

, and so

The

libdd2

drives. The API presents a consistent, platform-independent abstract layer that provides access to the DST/DIS tape device driver used on the following supported platforms:

•

The DST/DIS or interfaces presented in this document. See the related documents listed in paragraph 1.5 for the location of information on the installation and operation of DST hardware and software.

API is a set of C-library functions that simplify control of Ampex DST/DIS tape

tpsc

tape device driver used on Silicon Graphics IRIX platforms, or to the Ampex

Digital Equipment Corporation Digital UNIX (formerly DEC OS/F 1) Hewlett Packard HP-UX IBM AIX Sun Microsystems Solaris

tpsc

tape device driver must already be installed before using any of the

Ampex 1308911-02 1-1

Running Head

Manual Contents General Information

Model No.

1.2 Manual Contents

• Section 1, “General Information,” describes document conventions used in this manual,

its intended audience, and related documents.

• Section 2, “Software Overview,” provides a general overview of the host system tape

device driv er interface, tape driv e behavior , the libdd2 API functions, and the DD-2 Tape Management Utilities.

• Section 3,“DD-2 Tape Format,” introduces the DD-2 tape format.

• Section 4, “Tape Drive Operational Characteristics,” describes tape drive operating

features you should be familiar with when using the libdd2 API functions or dd2 utilities.

• Section 5, “libdd2 API Functions,” contains the manual pages for the libdd2 API

functions.

• Section 6, “DD-2 Utilities Manual Pages,” contains the manual pages for the DD-2

utilities.

• Appendix A, “Glossary and Acronyms,” describes terms and deﬁnes acronyms used

throughout this document.

• Appendix B, “Device Special Files,” provides detailed information on the de vice special

ﬁles available on supported UNIX platforms.

• Appendix C, “Result Codes and Machine Status, ” deﬁnes the Result and Machines Status

Codes that the tape drive can report.

• Appendix D, “MSR Diagnostic Status Information,” describes the diagnostic status

information that the tape drive can report.

• Appendix E, “Statistics,” describes the service and operational statistics that the tape

drive can report.

1-2 Ampex 1308911-02

General Information Notational Conventions

1.3 Notational Conventions

This manual uses the following typographical conventions: Bold In a syntax description, indicates text that must be typed literally. In

other contexts, indicates UNIX command names, program/application names, or C function names.

Italic In a syntax description, indicates generic arguments or options; these

should be replaced with user-supplied values. Also used for book titles, notes in the text requiring special attention, or to emphasize terms. Otherwise, indicates C structure names or member names.

[ ] In a command syntax description, surrounds optional elements. Do not

type the brackets themselves.

| In a command syntax description, separates alternate items. Only one of

the alternate items may be used in any given in v ocation. Do not type the | character. In contexts other than syntax descriptions, the | character stands for the UNIX pipe feature, which directs the output of one command into another command.

{ } In a command syntax description, groups alternate items. Do not type

the braces themselves.

... In a command syntax description, indicates an element that may be

repeated. Do not type the dots themselves.

Fixed In an example, indicates computer output or contents of ﬁles or

directories. In other contexts, indicates C type names, C symbolic constants, ﬁle names, or path names.

Fixed Bold In an example, indicates text typed by the operator.

Note: In C function prototypes and e xamples, the special characters above ([ ] | { }) retain

their normal meaning in the C language. The conventions above for the special characters apply only to command-line syntax descriptions, not to C language descriptions or examples.

Initial Uppercase Letters

Indicate command ﬁelds or special terms or names.

/ When used with ioctl symbolic constants, the slash indicates a control

function/operation pair. F or example, to the

DST_SETPOS operation of the ioctl DSTIOCTOP function. In

other contexts, the slash retains its normal meaning.

DSTIOCTOP/DST_SETPOS refers

≈ Indicates approximate values.

Ampex 1308911-02 1-3

Running Head

Notices and Notes General Information

Model No.

1.4 Notices and Notes

The following are examples of warning notices and informational notes that may appear in this document.

Notice!

Indicates a hazard that may result in equipment damage or loss of data.

Note: A Note contains information that requires more emphasis than can be given in a

normal paragraph. This might include additional guidance, hints, reminders, or further explanation.

1.5 Related Documents

DST SCSI T ape Drive DD-2 T ape F ormat Guide, Catalog No. 1306706, describes physical and logical DD-2 tape structures and provides common tape format examples.

DST 310 Tape Drive Installation and Operation, Catalog No. 1299516, describes DST 310 hardware installation and operation.

DIS Tape Drive Installation and Operation, Catalog No. 1306821, describes DIS hardware installation and operation.

DST 410 Automated Cartridge Library Installation and Operation, Part No. 1306378,

describes DST 410 hardware installation and operation.

DST 810/812 Automated Cartridge Library Planning and Installation, Part No. 1306031,

describes DST 810 and DST 812 hardware installation and operation.

DST/DIS Software Installation Guide for Sun Microsystems Solaris Operating Systems, Part No. 1306822, describes how to install system software for Ampex SCSI tape drives and Automated Cartridge Libraries on Sun Microsystems host platforms running the Solaris operating system.

DST/DIS Software Installation Guide for Silicon Graphics IRIX Oper ating Systems, P art No. 1306823, describes how to install system software for Ampex SCSI tape drives and Automated Cartridge Libraries on Silicon Graphics host platforms running the IRIX operating system.

DST/DIS Software Installation Guide for IBM AIX Operating Systems, Part No. 1306824, describes how to install system software for Ampex SCSI tape drives and Automated Cartridge Libraries on IBM host platforms running the AIX operating system.

1-4 Ampex 1308911-02

General Information Technical Support

DST/DIS Software Installation Guide for HP UX Operating Systems, Part No. 1306826, describes how to install system software for Ampex SCSI tape drives and Automated Cartridge Libraries on Hewlett Packard host platforms running the HP UX operating system.

DST/DIS Software Installation Guide for Digital UNIX Operating Systems, P art No. 1306825, describes how to install system software for Ampex SCSI tape drives and Automated Cartridge Libraries on Digital Equipment Corporation host platforms running the Digital UNIX operating system.

DST/DIS Automated Cartridge Library UNIX Application Programmer’s Guide, Part No. 1308910, describes how to use the Ampex ACL (automatic cartridge library) software installed on your UNIX host system.

1.6 Technical Support

If you require information or technical assistance, contact the Ampex Customer Service Department for assistance:

Ampex Corporation Customer Service 600 W ooten Road Colorado Springs, CO 80915-3597 Telephone: 800-DST-SRVC (800-378-7782) or 719-596-2000 Fax: 719-570-3289 International T elephone: 719-570-3378 E-mail address: dstsrvc@ampex.com

1.7 Documentation Support

Your feedback is important to us. If you ﬁnd any errors in this manual or have any comments or suggestions, please send E-mail to our technical publications department at:

techpubs@ampex.com

We are always trying to improve our documentation and appreciate your input.

Ampex 1308911-02 1-5

Software Overview Introduction

Section 2 Software Overview

2.1 Introduction

This section provides a general overvie w of the host system tape device driver interf ace, tape drive behavior , the libdd2 API functions, and the DD-2 Tape Management Utilities. Table 2-1. lists the operations performed by the libdd2 functions and the Tape Management Utilities.

With the Ampex or IRIX tpsc tape device driver installed, the standard UNIX open, close, read, write, read_v, and write_v system calls access the DST drive.

Ampex provides the libdd2 programming interface described in this manual and recommends this interface for all new application development.

The following programming interfaces are available but are not documented in this manual:

• mtio/sto – For compatibility with existing UNIX tape handling programs, the Ampex and

IRIX tpsc drivers provide an mtio/stio interface conforming to mtio/sto conventions for UNIX host platforms.

• ioctl () – The Ampex and IRIX tpsc drivers support this standard UNIX function for

device control.

• DSTIOCPASSTHRU – This ioctl code interface provides full SCSI protocol-speciﬁc

access to the Ampex tape drives.

2.2 Tape Device Driver

Ampex DST and DIS tape drives are compatible with the Ampex DST/DIS tape device driver and the IRIX tpsc tape device driver. Both drivers are implemented as standard UNIX raw character I/O devices with ﬁxed block interfaces. They support multiple Ampex tape dri ves on a single UNIX host but not multiple users per tape drive; only one process can have the tape device driv er open at any one time. Table 2-2 lists the interfaces through which a DST or DIS tape drive can be operated by an application program or from the UNIX command line.

The Ampex DST/DIS tape device driver is used on the following platforms:

• Digital Equipment Corporation Digital UNIX (formerly DEC OS/F 1)

• Hewlett Packard HP-UX

• IBM AIX

• Sun Microsystems Solaris

Ampex 1308911-02 2-1

)

Running Head

Tape Device Driver Software Overview

Model No.

Table 2-1. DST/DIS Tape Drive Software Operations

Operation DD-2 Utility libdd2 API Function

TAPE DRIVE STATUS

Get tape drive current state

dd2_status_drive and dst_status()

report more information than

dst_getstate()

Get results of last I/O operation.

Format tape cartridge.

Get tape cartridge format.

dd2_status_drive

(See paragraph

dd2_status_drive

(See paragraph

dd2_format_tape

(See paragraph

dd2_query_tape

See paragraph

6.18 on page 6-56

TAPE CARTRIDGE

6.4 on page 6-9

6.10 on page 6-31)

dst_getstate ()

(see paragraph 5.11 on page 5-40)

dst_status

(see paragraph 5.19 on page 5-59)

dst_status ()

(see paragraph 5.19 on page 5-59)

dst_format ()

(see paragraph 5.5 on page 5-16)

dst_status ()

(see paragraph 5.19 on page 5-59)

()

Unload tape cartridge.

Get current position.

Get remaining capacity of current partition (with respect to current position).

Convert position.

Set absolute position.

Set relative position.

Rewind tape to beginning of current partition.

Get tape drive current data block size. dd2_getparam_drive

dd2_unload_tape

(See paragraph

dd2_getpos_tape

(see paragraph 6.7 on page 6-20

dd2_setpos_tape

(see paragraph 6.16 on page 6-49)

dd2_space_tape

(see paragraph 6.17 on page 6-53)

dd2_rewind_tape

(see paragraph 6.17 on page 6-53)

TAPE DRIVE CONFIGURATION

(see paragraph 6.15 on page 6-46)

6.19 on page 6-59)

TAPE POSITIONING

dst_unload()

(see paragraph 5.20 on page 5-63)

dst_getpos ()

(see paragraph 5.10 on page 5-38)

dst_status ()

(see paragraph 5.19 on page 5-59)

dst_status

(see paragraph 5.19 on page 5-59)

dst_convpos

(see paragraph 5.4 on page 5-13)

dst_setpos

(see paragraph 5.17 on page 5-54)

dst_space

(see paragraph 5.18 on page 5-57)

dst_rewind

(see paragraph 5.14 on page 5-46)

dst_getparam ()

(see paragraph 5.9 on page 5-35)

dst_status

(see paragraph 5.19 on page 5-59)

()

Get tape drive minimum and maximum data block sizes.

dst_status()

(see paragraph 5.19 on page 5-59)

2-2 Ampex 1308911-02

Software Overview Tape Device Driver

Table 2-1. DST/DIS Tape Drive Software Operations (Continued)

Operation DD-2 Utility libdd2 API Function

Get tape drive default write-data block size.

Get tape drive conﬁguration attributes and parameter settings.

Get tape drive product information.

Set tape drive data block size.

Change tape drive conﬁguration parameters.

Reset tape drive.

TAPE DEVICE DRIVER CONFIGURATION AND VERSION

Get tape device driver interface parameter settings.

Get tape device driver debug level.

dd2_status_drive

(see paragraph 6.18 on page 6-56)

dd2_query_drive

(see paragraph 6.9 on page 6-25)

dd2_query_drive

(see paragraph 6.9 on page 6-25)

dd2_setparam_drive

(see paragraph 6.15 on page 6-46)

dd2_set_drive

(see paragraph 6.14 on page 6-42)

dd2_reset_drive

(see paragraph 6.12 on page 6-38)

dd2_getparam_drive

(see paragraph 6.6 on page 6-17)

dd2_getparam_drive

(see paragraph 6.6 on page 6-17)

dst_status()

(see paragraph 5.19 on page 5-59)

dst_getdrive()

(see paragraph 5.6 on page 5-22)

dst_getdrive_ex

(see paragraph 5.7 on page 5-26)

dst_getdrive()

(see paragraph 5.6 on page 5-22)

dst_getdrive_ex

(see paragraph 5.7 on page 5-26)

dst_setparam()

(see paragraph 5.16 on page 5-51)

dst_setdrive

(see paragraph 5.15 on page 5-47)

dst_reset()

(see paragraph 5.13 on page 5-45)

dst_getparam ()

(see paragraph 5.9 on page 5-35)

dst_getparam ()

(see paragraph 5.9 on page 5-35)

()

Get tape device driver version.

Set tape device driver debug level.

Get tape drive buffer size.

Get number of data bytes in tape drive buffer.

Write Filemark(s)

dd2_query_drive

(see paragraph 6.9 on page 6-25)

dd2_setparam_drive

(see paragraph 6.15 on page 6-46)

TAPE DRIVE BUFFER

dd2_query_drive

(see paragraph 6.9 on page 6-25)

dd2_status_drive

(see paragraph 6.18 on page 6-56)

dd2_weof_tape

(see paragraph 6.20 on page 6-61)

dst_getdrive

(see paragraph 5.6 on page 5-22)

dst_getdrive_ex

(see paragraph 5.7 on page 5-26)

dst_version

(see paragraph 5.21 on page 5-64)

dst_setparam

(see paragraph 5.16 on page 5-51)

dst_getdrive ()

(see paragraph 5.6 on page 5-22)

dst_getdrive_ex

(see paragraph 5.7 on page 5-26)

dst_status

(see paragraph 5.19 on page 5-59)

dst_weof

(see paragraph 5.22 on page 5-66)

dst_weof_ex

(see paragraph 5.23 on page 5-68)

()

Ampex 1308911-02 2-3

Running Head

Tape Device Driver Software Overview

Model No.

Table 2-1. DST/DIS Tape Drive Software Operations (Continued)

Operation DD-2 Utility libdd2 API Function

Synchronize (ﬂush) tape drive buffer dd2_weof_tape

(see paragraph 6.20 on page 6-61)

TAPE DRIVE CAPABILITIES

Get tape drive capabilities

Get tape drive error statistics.

Get tape drive service statistics.

dst_getlog() reports more information

than

dd2_getlog_drive

dd2_query_drive dst_getdrive ()

TAPE DRIVE STATISTICS

dd2_getlog_drive

(see paragraph 6.5 on page 6-14)

dst_weof ()

(see paragraph 5.22 on page 5-66)

dst_weof_ex ()

(see paragraph 5.23 on page 5-68)

(see paragraph 5.6 on page 5-22)

dst_getdrive_ex ()

(see paragraph 5.7 on page 5-26)

dst_getlog ()

(see paragraph 5.8 on page 5-31)

dst_getlog

(see paragraph 5.8 on page 5-31)

()

Get tape drive operational statistics.

Get tape drive diagnostics statistics.

Clear tape drive Error and Operational Statistics Logs.

Get Transport Control Firmware trace log

Get Process Control Firmware trace log

Get Recorder Control Firmware trace log

Get SCSI trace log

TAPE DRIVE READ/WRITE PERFORMANCE

Measure overall read performance of SCSI device and host

Measure overall write performance of SCSI device and host

dd2_getlog_drive dst_getlog

dd2_clrlog_drive

(see paragraph 6.3 on page 6-7)

TAPE DRIVE TRACE LOGS

dd2_gettrace_drive

(see paragraph 6.8 on page 6-23)

dd2_gettrace_drive

(see paragraph 6.8 on page 6-23)

dd2_gettrace_drive

(see paragraph 6.8 on page 6-23)

dd2_gettrace_drive

(see paragraph 6.8 on page 6-23)

dd2_read_perf

(see paragraph 6.11 on page 6-35)

dd2_write_perf

(see paragraph 6.21 on page 6-63)

dst_clrlog

(see paragraph 5.3 on page 5-12)

dst_gettrace ()

(see paragraph 5.12 on page 5-42)

dst_gettrace ()

(see paragraph 5.12 on page 5-42)

dst_gettrace

(see paragraph 5.12 on page 5-42)

dst_gettrace

(see paragraph 5.12 on page 5-42)

()

2-4 Ampex 1308911-02

Software Overview Tape Drive Behavior

Table 2-2. DST/DIS Tape Device Driver Interfaces

Interface Description

COMMAND LINE INTERFACES

Ampex dd2 utilities

UNIX mt utility

UNIX data transfer utilities

The dd2 utilities take full advantage of the DD-2 tape format. They are the recommended method for controlling the tape drive from the command line.

The mt utility provides an alternate method of controlling the tape drive from the command line but it doesn’t take full advantage of the DD-2 tape format. Use this utility only when necessary for compatibility with existing UNIX tape handling programs.

UNIX provides several utilities for reading from and writing to tape. Two of the more common ones are dd and tar (including enhanced versions such as ftar, GNU tar , and so forth.

2.3 Tape Drive Behavior

When the Ampex tape drive software is installed on a UNIX platform, the host creates a number of device special ﬁles which provide access to the tape device driver. Each device special ﬁle deﬁnes a unique set of interface parameters that establish a particular operational behavior for the tape drive.

For additional information on device special ﬁles, see Section 4 and Appendix B.

• Section 4 describes how the interface parameter settings affect common tape drive

operations.

• Appendix B lists the default device special ﬁle choices for each host platform,

summarizes the behavior speciﬁed by each ﬁle, provides detailed description of the interface parameters, and cross references the interface parameters to descriptions of the actions that they control on open, while open, or on close.

2.4 libdd2 API Overview

The libdd2 API features simple, compact, and direct functions that af ford program control of all salient tape and drive operations except for open, close, read, and write which are accomplished using standard UNIX system calls. Detailed knowledge of the hardware and SCSI interface are not necessary.

Ampex 1308911-02 2-5

Running Head

libdd2 API Overview Software Overview

Model No.

2.4.1 Operation of libdd2

The libdd2 API layer packages SCSI tape dri ve commands as C functions, isolating the caller from the device driver layer. C programs that use the libdd2 API normally use the C preprocessor

dd2.h Contains the libdd2 function prototypes and provides several useful

In addition to the above DST tape device driver header ﬁle, some of the system calls require inclusion of standard system header ﬁles. Any such ﬁles are shown in the syntax section for each system call.

#include directive to include the following header ﬁle.

deﬁnitions such as the DST_SPACE type argument. To use any dd2 function, include the following statement:

#include <dd2.h>.

The DST tape device driver header files are normally installed in the directory. To use any dd2 functions, include the following statment:

#include <dd2.h>

To link your application, reference the libdd2 library in /user/lib.

2.4.2 Function Return Values

All libdd2 C-Library functions return either DST_SUCCESS (0) or DST_FAILURE (-1).

2.4.3 Errors

See “Return Values” on page 5-7 for information on libdd2 error reporting.

2.4.4 UNIX Platform Compatibility

Unless noted otherwise, all libdd2 functions operate consistently across supported platforms. See the on line release notes installed with the libdd2 API to ﬁnd out which v ersion of the DST device driver it is compatible with.

/usr/include/sys

2.4.5 Restrictions

Some of the libdd2 API functions are restricted for use by the root user only. The manual page for each libdd2 function notes any such restriction.

2-6 Ampex 1308911-02

Software Overview DD2 Utilities Overview

2.5 DD2 Utilities Overview

The dd2 utilities provide command-line access to an Ampex DST or DIS tape drive. They are compatible with the DST/DIS Automated Cartridge Library (ACL) Utilities and can be used together with them in scripts that perform higher-level operations. Both sets of utilities use a consistent set of input and output conventions that make them easy to integrate.

2.5.1 Exit Status

The dd2 utilities use the following e xit status codes to indicate success or failure. To view the status code, type

0 Operation succeeded. nonzero Operation failed.

2.5.2 Errors

echo $status (see C-shell).

See “Exit Status” on page 6-5 for information on dd2 utilities error reporting.

2.5.3 UNIX Platform Compatibility

Unless noted otherwise, all of the dd2 utilities operate consistently across supported platforms.

2.5.4 Open behavior

Each dd2 utility handles the opening and closing of the tape drive.

2.5.5 Restrictions

Some of the dd2 utilities are restricted for use by the root user only. The manual page for each dd2 utility notes any such restriction.

Ampex 1308911-02 2-7

DD-2 Tape Format Introduction

Section 3 DD-2 Tape Format

3.1 Introduction

This section introduces the DD-2 tape format. For additional information, see the DST/DIS SCSI Tape Drive DD-2 Tape Format Guide.

3.2 DST Cartridge

The DST cartridge is available in the following capacities:

• 25, 75, or 165 gigabytes single density cartridges

• 50, 150, or 330 gigabytes double density cartridges

• 100, 300, or 660 gigabytes quad density cartridge

3.3 DD-2 Tape Entities

A formatted DD-2 tape contains the following entities (see Figure 3-1):

• Beginning of Tape (BOT) system Zone

• Volume Format Information (VFI) Zone

• Partition(s)

– Beginning of Partition (BOP) mark – Beginning of Media (BOM) zone – File Sections identiﬁed by File Section Number (FSN) – End of Recording (EOR) / End of Data (EOD) mark – Early Warning (EW) mark – End of Media Warning (EMW) mark – End of Partition (EOP) mark

• End of Tape (EOT) system zone

In addition, the tape can contain additional system zones to facilitate positioning, unthreading and unloading.

Ampex 1308911-02 3-1

Running Head

DD-2 Format Types DD-2 Tape Format

Model No.

EOP/BOP

partition

n+1

EOP/BOP

partition

INFORMATION ZONE

partition

BOP

clear BOT EOT

leader zone zone

EOP/BOP

VFI

partition

EOP

(PARTITION DETAIL)

BOM

FSN #1

FSN #2

PARTITION

FSN #n

EOR/

EOD

EMW/EW

clear trailer

EOP/BOP

BOT SIDE EOT SIDE

(SYTEMS ZONES ARE INTERSPERSED THROUGHOUT THE INFORMATION ZONE.

LOAD OPERATION

ZONE (LOZ)

SYSTEM ZONE

THEIR SPACING IS USER CONFIIGURABLE.)

VFI

ZONE

Figure 3-1. DD-2 Tape Entities

3.4 DD-2 Format Types

A DD-2 tape supports three basic format types, each having distinct uses and advantages:

• Initialized (or non-preformatted).

• Partially formatted (or partially preformatted).

3-2 Ampex 1308911-02

DD-2 Tape Format DD-2 Format Types

• Fully formatted (or preformatted).

Initialized (or non-preformatted) is the simplest kind of formatting. This is a relatively quick operation (about 20 seconds). Initializing records some Volume Format Information at the beginning of tape and leaves the remaining tape unrecorded. An initialized tape allows only for a single partition of data; that is, the volume cannot be sub-divided into smaller volumes on the cartridge.

In partial formatting (also called partial preformatting), part of the tape is formatted and the remaining part is treated as a single initialized partition. This type of formatting is often used to create one or more small partitions at the beginning of the tape and a large partition for data at the end. It may be useful in some applications to use the small partitions at the beginning of the tape for directory or other descriptive information about the data in the large partition.

In full formatting (also called preformatting), the tape is written at several times normal play speed with information that deﬁnes all the partitions on the tape. Full formatting allows for multiple partitions and provides the most ﬂexibility in partitioning data on the cartridge. Of the three types of formatting, full formatting takes the longest time to complete.

3.4.1 System Zones

System zones are areas that allow tape loading and unloading at locations other than BOT. Their layout is speciﬁed at the time the tape is formatted.

System zones can be located anywhere and do not necessarily correspond to partition boundaries unless the tape was speciﬁcally formatted with system zones at partition boundaries.

Although system zone placement can affect data access times and space usage, they are transparent to applications and do not affect the logical structure shown in Figure 3-1.

3.4.2 Partitions

Formatting a DD-2 tape creates one or more partitions. Each partition contains a set number of physical blocks (also referred to as double fr ames). These are the smallest units (1,199,840 bytes) that the drive can use to write data to tape. Typically, each physical block contains multiple data blocks which are the units in which your application transfers data to or from the tape drive (8192 bytes is the default data block size).

Each partition comprises a separate entity, logically as well as physically. Most operations, including read and write, cannot cross a partition boundary . Only explicit partition positioning commands and a rewind immediately after cartridge load will cross a partition boundary.

Ampex 1308911-02 3-3

Running Head

DD-2 Format Types DD-2 Tape Format

Model No.

3.4.3 File Sections

A ﬁle section consists of zero or more consecutive data blocks bounded on each end by a ﬁlemark, BOP, or EOD. File sections are numbered sequentially within a partition, starting at one.

Some older tape formats use a set of two consecutive ﬁlemarks to indicate EOD. Because the DD-2 format keeps track of EOD independently, double ﬁlemarks are not required; they merely indicate an empty ﬁle.

Note: Each additional filemark advances the ﬁle section number by one.

The DD-2 format requires that each ﬁle section start at the beginning of a physical block (but the ﬁle section can span multiple physical blocks). Thus, writing many small ﬁle sections will waste space on the tape.

3.4.4 Data Blocks

The following paragraphs discuss data block sizes and the relationship between tape drive physical and logical data blocks.

Physical Blocks. Physical blocks are storage locations for data written to tape. They are the

smallest units that the drive can use when writing data to tape from the buffer. Each physical block is 1,199,840 bytes. Each ﬁle section must start in a separate physical block (but it can span multiple physical blocks). To conserve partition space try to avoid writing small ﬁle sections that waste signiﬁcant physical block space (for example, writing ten 200 kB ﬁle sections would consume approximately 12 MB of space on tape).

Logical Data Blocks. A data block (also called a logical data block or a record) is a series of

consecutive bytes of a ﬁxed length. Any given ﬁle section has only one data block size. Each data block is followed by a two-byte checksum unless you disable the checksum feature or operate the drive in byte-stream mode.

Note: Ampex does not recommend turning of f chec ksums or changing the default data block

size unless you want to operate in byte stream mode.

Data blocks are numbered by:

• Logical Data Block Number (LDBN) within a ﬁle section, starting at zero.

• Cumulative Data Block Number (CDBN) within a partition, starting at one (ﬁlemarks are

counted as blocks for addressing purposes). CDBN is also referred as block address.

Data Block Size. The tape drive accepts data block sizes of one byte (byte-stream mode), or an

even number of bytes between 80 and 1,199,840 (1,199,838 when using checksums). Data blocks cannot span physical block boundaries. Therefore, best use of space is achieved by data

3-4 Ampex 1308911-02

DD-2 Tape Format Instrumentation and Data Storage Recording

block sizes that are small or that divide (with their checksums) into 1,199,840 leaving only a small remainder. F or example, a data block size of 600,000 would w aste almost half the space in each physical block.

A second factor in choosing a data block size is that all transfers to/from the drive must be in multiples of the data block size.

Byte-Stream Mode. Byte-stream mode allows data transfers of any length so long as they do

not start or end on an odd-byte boundary. Checksums are not used.

Note that byte-stream mode is not the same as variable-length records. Each byte is directly addressable regardless of the number of bytes written at a time.

3.5 Instrumentation and Data Storage Recording

The DD-2 tape format provides an extend time stamp enable (ETSE) bit which determines whether time code information is recorded with data written to tape.

When a DD-2 tape is formatted on a DIS tape drive operating in the instrumentation mode, the ETSE bit is set to on to enable time code recording. The Ampe x DST/DIS Tape Management Software identiﬁes this as the DIS format.

When a DD-2 tape is formatted on a DST drive or a DIS drive operating in the SCSI mode, the ETSE bit is set to off to disable time code recording. The Ampex DST/DIS Tape Management Software identiﬁes this as the DST format.

Table 3-1 shows the read/write compatibility of DIS and DST formatted tapes on DST/DIS tape drives. .

Table 3-1. DST and DIS Tape Format Compatibility

DST Tape Format DIS Tape Format

Tape Drive

Read Write Read Write

DIS drive operating in instrumentation mode Yes DST drive or

DIS drive operating in SCSI mode

1. Tape does not contain time code.

2. Invalid (zero) time code values are recorded for data written to tape.

Yes Yes Yes Yes

No Yes Yes

Ampex 1308911-02 3-5

Tape Drive Operational Characteristics IntroductionIntroduction

Section 4 Tape Drive Operational Characteristics

4.1 Introduction

The following paragraphs describe tape drive basic behavior (see Table 4-1 and 4-2) you should be familiar with when using the libdd2 API functions or dd2 utilities.

Table 4-1. DST/DIS Tape Drive Basic Behavior

Platform Default Actions

HP, DEC, Solaris (device special file *.0)

On Open:

• Retains current block size.

• Retains current position.

• Clears outstanding Unit Attention conditions.

• Reserves tape drive for exclusive use by initiator.

While Open:

• Allows reformatting of tapes.

• When a ﬁlemark is detected during a read, returns the number of bytes read and

sets the current position to after the ﬁlemark; the next read gets data from the next ﬁle.

• If a ﬁlemark is encountered during the ﬁrst read after open and no data was

transferred, returns zero bytes.

• Allows appending to and overwriting of existing data.

• Filemarks written to tape are not buffered.

• If EW is encountered during a write, tries to ﬂush the tape drive buffer to tape.

– If successful, returns -1 with errno set to ENOSPC to signify that all data in

the buffer was ﬂushed to tape and the tape/partition is full.

– If unsuccessful, returns the number of bytes written to tape.

On Close:

• If Write was the last command issued before the close, writes a single ﬁlemark.

• Flushes the tape drive buffer to tape.

• Sets the current position to BOP.

• Releases the tape drive for concurrent operation.

Ampex 1308911-02 4-1

Running Head

IntroductionTape Drive Operational CharacteristicsTape Drive Operational Characteristics

Model No.

Table 4-1. DST/DIS Tape Drive Basic Behavior (Continued)

Platform Default Actions

AIX (device special file *.0)

SGI

(device special ﬁle

/tps Xdy)

Platform Required Behavior

HP, DEC, Solaris, AIX (device special file *.9)

Same as DEC, HP, and Solaris, except implements the user-deﬁned block size on open.

Same as DEC, HP, and Solaris, except:

• On open, the tape drive is not reserved for exclusive use by current process.

• While open:

– When a ﬁlemark is detected during a read operation, returns the number of

bytes read and sets the current position to after the ﬁlemark. If some data was read before the ﬁlemark was detected, the next read operation reports zero bytes.

– If a ﬁlemark is encountered during the ﬁrst read after open and no data was

transferred, the ﬁlemark is ignored and the read command is re-issued.

Table 4-2. Tape Drive Behavior Required for tar and dd.

Same as described in Table 2-3, except:

• While open:

– When a ﬁlemark is detected during a read, returns the number of bytes read

and sets the current position to after the ﬁlemark. If some data was read before the ﬁlemark was detected, the next read reports zero bytes.

– When Early W arning is detected during a write, ﬂushes the tape drive b uffer

to tape and reports zero bytes.

• On close, the current position is not changed. Since each utility opens and

closes the tape drive, this behavior is required so that a positioning utility can be used to establish the current position from which tar or dd starts reading from or writing to tape.

SGI

(device special ﬁle

/tps Xdy)

4-2 Ampex 1308911-02

Same as described in Table 2-3, except the current position is not changed on close. This behavior is required so that a positioning utility can be used to establish the current position at which tar or dd starts reading from or writing to tape.

Tape Drive Operational Characteristics Tape Drive Block SizeTape Drive Block Size

4.2 Tape Drive Block Size

The DST/DIS tape drive is a ﬁxed block device and enables the following block sizes to be used during its operation:

• 1 byte (byte stream mode) - checksums are disabled.

• 80 to 1199840 bytes (even values only) - checksums can be enabled or disabled.

There are three block sizes that must be considered in tape drive operation:

• File block size – The block size used in a given ﬁle section. Every ﬁle section may have

a different block size, but only a single block size is used within a ﬁle section.

• Drive block size -- The block size number maintained within the tape drive. This is the

number returned by dd2_getparam_drive as %blksize, and dd2_status_drive as %drvblksz.

• Write block size -- The block size number maintained within the device driver for new

writes. This is the number returned by dd2_status_drive as %wrblksz. This parameter, and drive block size, are both set by dd2_setparam_dri ve. Ho we ver , dri v e block size will change as described below. Write block size will not change. Its default value is 8192.

Whenever you attempt a write at BOP or immediately after a ﬁlemark, drive block size will ﬁrst be set to the driver's write block size. This becomes the ﬁle block size for the new ﬁle section. Whenev er you attempt a read or a write within a ﬁle section, the dri ve block size will ﬁrst be set to the existing ﬁle's ﬁle block size. Then, the read() or write() will fail if the amount of data to be transferred is not a multiple of the drive block size at it is now set.

4.3 Tape Partitions

All functions and utilities that read from, write to, or position the tape, will work only within the boundaries of a partition, with the following exceptions:

• After an initial tape load, before establishing position, a rewind command rewinds a tape

to the beginning of the ﬁrst partition.

• The dd2_setpos_tape function enables speciﬁcation of a partition number. If this requires

a partition change, the behavior is to position to the beginning of the target partition and then to the target location within the partition.

Ampex 1308911-02 4-3

libdd2 API Functions Introduction

Section 5 libdd2 API Functions

5.1 Introduction

This section contains the manual pages for the libdd2 API functions. All information in the section was accurate at the time of publication, but is subject to change without notice. For the latest information on the libdd2 API functions, see the Release Notes for your version of the tape drive software.

5.2 DST API Overview

The libdd2 C-Library functions provide access to the DD-2 interface of the DST/DIS tape device driver. This interface supports a large set of operations that afford program control of all salient tape and drive operations.

5.2.1 libdd2 Functions Summary

dst_clrlog() Clear tape drive error and operational statistics. dst_convpos() Convert tape position from structure to token or vica versa. dst_format() Format a DD-2 tape. dst_getdrive() Get tape drive product information, conﬁguration and capabilities,

and tape device driver version.

dst_getdrive_ex() Get tape drive product information, conﬁguration and extended

capabilities, and tape device driver version.

dst_getlog() Get tape drive error, operational, service, and diagnostic statistics. dst_getparam() Get tape drive data block size, tape device driver debug level, and

device special ﬁle interface parameter settings.

dst_getpos() Get current position. dst_getstate() Get tape drive current state. dst_gettrace() Get a ﬁrmware trace log from the tape drive. dst_reset() Reset the tape drive.

Ampex 1308911-02 5-1

Running Head

DST API Overview libdd2 API Functions

dst_rewind() Rewind tape to Beginning of Partition (BOP). dst_setdrive() Change tape drive conﬁguration parameters. dst_setparam() Change tape drive data block size and tape device driver debug

level.

dst_setpos() Set tape drive position to the speciﬁed location. dst_space() Change current position by a speciﬁed number of blocks or ﬁles, or

set current position to end of data (EOD).

dst_status() Get information on tape drive and tape cartridge. dst_unload() Unload the tape cartridge from the tape drive. dst_version() Get version information for the tape device driver. dst_weof() Write ﬁlemark(s) to tape. dst_weof_ex() Write ﬁlemark(s) to tape (extended).

Model No.

5.2.2 Position Specifications

The libdd2 API permits applications to specify tape drive position in either token form or standard C structure form. Three positioning formats are supported: DST (standard DD-2), DST600, and DIS. Each format can be converted from token form to structure form or vica versa. In order to obtain DIS timecode, however, a position must be retrieved from tape in structure form and converted to a token.

The token form of a position speciﬁcation is a portable byte array that is not subject to host platform byte-ordering or alignment variations. A token position written on one host platform can be read by a program running on a different host platform. The structure form of a position speciﬁcation may not be portable across platforms.

The libdd2 API functions use the following structures, unions, and typedefs to get, set, and convert position.

dst_position_st

This structure type is used to get, set, or convert a position speciﬁcation.

typedef struct {

dst_pos_type_en type; /* Position type */ dst_position_un pos; /* Position */

} dst_position_st;

5-2 Ampex 1308911-02

libdd2 API Functions DST API Overview

type Speciﬁes the position form and format (see dst_pos_type_en

below).

pos Union containing the position information in the speciﬁed form and

format (see

dst_position_un below).

dst_pos_type_en

This typedef enumeration supports the following deﬁnitions of position form and format. The position format must be compatible with the current drive capabilities, ho wever. For example, if the drive supports only standard DD-2 positioning, then deﬁnition for this member.

typedef enum dst_pos_type {

DstPosDef = 0, /* Default position in structure form */ DstPosTok, /* Token position (in current drive format on get) */ DstPosDD2, /* Standard DD-2 position in structure form */ DstPos600, /* DST600 position in structure form */ DstPosDIS /* DIS timecode position in structure form */

} dst_pos_type_en;

DstPos600 is not a valid

DstPosDef Structure form of position in the native format of the current drive.

DstPosTok Token form of position (expanded format that accommodates all drive

types).

DstPosDD2 Structure form of position in standard DST format. DstPos600 Structure form of position in DST600 format.

DstPosDIS Structure form of position in DIS format.

dst_position_un

This union type contains the position information in the speciﬁed form and format.

typedef union {

dst_pos_tok_t token; /* Type DstPosTok (any drive format) */ dst_dd2_pos_st dd2; /* Type DstPosDD2 */ dst_600_pos_st dst600; /* Type DstPos600 */ dst_dis_pos_st dis; /* Type DstPosDIS */

} dst_position_un;

token Position token array of type dst_pos_tok_t (see dst_pos_tok_t

below).

Ampex 1308911-02 5-3

Running Head

DST API Overview libdd2 API Functions

dd2 Structure of type dst_dd2_pos_st for representing position in

standard DST (DD-2) format (see

dst600 Structure of type dst_600_pos_st for representing position in

DST600 format. (see

dis Structure of type dst_600_pos_st for representing position in DIS

format (see

dst_dis_pos_st below).

dst_600_pos_st below).

dst_dd2_pos_st below).

Model No.

dst_pos_tok_t

This position token array deﬁnes sufﬁcient elements to support standard DST, DST600, and DIS tape drives. These include: tape cartridge volume ID, current tape drive type, absolute double frame number (adfn), partition ID, ﬁle section number (fsn), logical data block number (ldbn), cumulative data block number (cdbn), and timecode. The following caveats apply:

• Retrieving a token:

– If the drive is a DST or DIS, the token will contain

information. You cannot retrieve a token that contains DIS information; you can create one, however, as described below.

– If the drive is a DST 600, the token will contain

fsn/ldbn position

timecode

cdbn position information.

• Creating a DIS token:

– To create a DIS token that contains

dst_getpos() to retrieve a convert the structure to a token.

DstPosDIS structure. Then, use dst_convpos() to

timecode position information, ﬁrst use

• Identifying a token:

– After a token is created, there is no way to identify what type of positioning

information it contains. The user is responsible for logging this information when the token is created.

The token form of a position is always complete and contains within itself sufﬁcient information for conversion into a structure form of position.

#define DST_POS_TOK_SZ40 typedef u_char dst_pos_tok_t[DST_POS_TOK_SZ];

dst_dd2_pos_st

This structure type represents position in native DST (DD-2) format and may not be portable across platforms.

typedef struct {

u_int valid; /* Flag indicating which members are valid */

5-4 Ampex 1308911-02

libdd2 API Functions DST API Overview

int adfn; /* Absolute double-frame number */ int ptid; /* Partition ID (starting at zero!) */ int fsn; /* File section number (within partition) */ dst_dbn_st ldbn; /* Logical data block number (within FSN) */

dst_dd2_pos_st;

valid Bit mask that indicates whether the position is valid and, if so, which

structure members contain valid information

#define DST_POSN_INVALID 0x0000 #define DST_ADFN_VALID 0x0001 #define DST_DBN_VALID 0x0002 #define DST_FSN_VALID 0x0004 #define DST_PTID_VALID 0x0008 #define DST_TIMECODE_VALID 0x0010

adfn

Absolute Double Frame Number - The number of the physical block that contains the speciﬁed location. This is an optional value that, strictly speaking, is not part of the position speciﬁcation. When used, it provides a very accurate hint to the drive, expediting high-speed positioning to the speciﬁed position.

DO NOT SPECIFY AN ADFN UNLESS YOU ARE CERTAIN THAT IT IS ACCURA TE. An incorrect

adfn can set the tape position to an

invalid location (such as past end of data).

ptid Partition Identiﬁcation Number (ID) - The number of the partition that

contains the speciﬁed location. Partitions are numbered sequentially on the tape starting at zero.

fsn File Section Number - The number of the ﬁle section that contains the

speciﬁed location. Files are numbered sequentially within a partition starting at one.

ldbn Logical Data Block Number - The block number of the location. Data

blocks are numbered sequentially within a ﬁle section starting at zero.

dst_600_pos_st Structure

This structure type represents position in DST600 format and may not be portable across platforms. It is similar to the native DST structure, except that is identiﬁes the location by cumulative data block number within the partition rather than logical data block number within the ﬁle section. Use this position form only if you must maintain DST 600 compatibility.

typedef struct {

u_int valid; /* Flag indicating which members are valid */

Ampex 1308911-02 5-5

Running Head

DST API Overview libdd2 API Functions

int adfn; /* Absolute double-frame number */ int ptid; /* Partition ID (starting at zero!) */ int fsn; /* File section number (within partition) */ dst_dbn_st cdbn; /* Cumulative data block no. (within partition.)

/* (not counting FSNs as blocks) */

} dst_600_pos_st;

Model No.

valid Same as described for dst_dd2_pos_st.

adfn Same as described for dst_dd2_pos_st.

ptid Same as described for dst_dd2_pos_st.

fsn Same as described for dst_dd2_pos_st. Although fsn is returned

for current DST600 position, it is not used when setting DST600 position.

cdbn Cumulative Data Block Number - The block number of the location.

Data blocks are numbered sequentially within the partition starting at zero, and ﬁlemarks are counted as blocks.

dst_dis_pos_st Structure

This structure type represents position in DIS format and may not be portable across platforms. It is similar to the native DST structure, except that it uses timecode to specify a location instead of

typedef struct {

u_int valid; /* Flag indicating which members are valid */ int adfn; /* Absolute double-frame number */ int ptid; /* Partition ID (0-1023) */ int reserve2; /* timecode don't have FSN */ dst_dbn_st timecode; /* Timecode */

} dst_dis_pos_st;

valid Same as described for dst_dd2_pos_st.

adfn Same as described for dst_dd2_pos_st.

ptid Same as described for dst_dd2_pos_st.

reserve2 Not used.

timecode IRIG-B timecode value recorded for the location. This is a 64-bit

fsn and ldbn.

extended precision integer that speciﬁes IRIG-B time in number of milliseconds.

5-6 Ampex 1308911-02

libdd2 API Functions DST API Overview

5.2.3 Return Values

All libdd2 C-Library functions return either DST_SUCCESS (0) or DST_FAILURE (-1).

For conv enience, the indicate a success return value (0) and the symbolic constant

dstio.h header ﬁle deﬁnes the symbolic constant DST_SUCCESS to

DST_FAILURE to indicate a

failure return value (-1). A failure return value of -1 indicates that the libdd2 function encountered an error during

processing and that the tape device driv er has set the external v ariable

errno to indicate the

type of error that occurred.

The tape device driver uses the external variable most recent system call error. Because the system does not reset the successful system calls, your program should test

The

<sys/errno.h> ﬁle lists the symbolic names and values possible for errno. T ypical

errno codes are shown below for common errors that can occur. See your host system

documentation for the

errno values reported by your system.

errno to provide information about the

errno variable on

errno only if the call fails (returns -1).

• If the device could not be successfully opened, open() sets errno to a value that may

include one of the following.

EBUSY Drive is already in use. EINVAL Invalid argument supplied. EIO Tape drive fault (such as cartridge not present) during open processing. ENODEV The DST device is not properly connected to the host system. ENXIO Device does not exist. EPERM Access denied due to device special ﬁle permissions. EACCES Attempt to open a write protected device for writing. ETIME A timeout occurred on a SCSI command.

• If a problem occurred during the close operation, close sets errno to a value that may

include one of the following.

EIO Problem with synchronization, post-positioning, or command abortion. ENODEV The DST device is not properly connected to the host system. ETIME A timeout occurred on a SCSI command.

This call closes the interface unconditionally regardless of any error encountered.

• If the read operation could not be completed, this call sets errno to a value that may

include one of the following.

EIO Hardware fault or position undeﬁned at start of operation. EINVAL Invalid argument, or current device data block size attribute does not

match the actual data block size of the current ﬁle section, or the current device interface cannot use the data block size of the current ﬁle section.

Ampex 1308911-02 5-7

Running Head

DST API Overview libdd2 API Functions

ENOSPC Read attempted at EOD. ETIME A timeout occurred on a SCSI command. ENODEV The DST device is not properly connected to the host system.

Model No.

• If the write operation could not be completed, this call sets errno to a value that may

include one of the following.

EIO Hardware fault or position undeﬁned at start of operation. EINVAL Current device data block size attribute does not match the actual data

block size of the current ﬁle section, or the current device interface cannot use the data block size of the current ﬁle section.

ENOSPC No space left on device. ETIME A timeout occurred on a SCSI command. ENODEV The DST device is not properly connected to the host system.

The limited number of error deﬁnitions in the

<sys/errno.h> ﬁle requires mapping of

multiple DST drive errors onto single values. Because of this overloading, the libdd2 API provides the dst_status() function to supply additional error information beyond that provided by the

errno variable.

The

results member of the dst_status_st structure reports the results the of the last

I/O operation. Each result consists of a DST result code, a result class and a printable message describing the result. The following listing summarizes the result codes that can be reported; see the

dstio.h header ﬁle for deﬁnitions and descriptions.

DstCodeBadBlockWr Bad block written DstCodeBadMedFmt Invalid tape format detected DstCodeBadMedType Cartridge not supported based on coding holes DstCodeBecomingRdy Unit in process of becoming ready DstCodeBigFMcount Big FM count (3 bytes only) DstCodeBOMPosErr BOM encountered unexpectedly DstCodeBOP BOM/BOP detected DstCodeCleanCart Cleaning cartridge is in the transport DstCodeCmdPhaseErr Command phase error DstCodeCmdSeqErr Command sequence error (received in wrong order) DstCodeCopyInErr Copy in error DstCodeCopyOutErr Copy out error DstCodeCorruptFmt Medium tape format corrupted DstCodeDatPhaseErr Data phase error DstCodeDevIsInUse Device is in use by another user process DstCodeDriveIsBusy Drive is busy

5-8 Ampex 1308911-02

libdd2 API Functions DST API Overview

DstCodeDriveIsReserved Drive is reserved DstCodeEnvErr Environmental error (internal target failure) DstCodeEOD EOD detected DstCodeEODNotFound EOM/EOP encountered DstCodeEODPosError Error while setting position to EOD DstCodeEOFPosError Error while setting position to EOF DstCodeEOMPosErr EOM encountered unexpectedly DstCodeEOP EOM/EOP detected DstCodeFSN Filemark detected DstCodeGetPosError Error while getting position on tape DstCodeHitEW Hit early warning DstCodeInqDataChg Inquiry data has changed DstCodeIntTargFail Internal target fatal error DstCodeInvalidArg Invalid argument provided by the user DstCodeInvCDBField Invalid field in received CDB DstCodeInvCmdOp Invalid command operation code in received CDB DstCodeInvParmFld Invalid field in received parameter list DstCodeInvXferSize Invalid transfer size DstCodeIOTerm I/O process terminated DstCodeLoadError Error while loading tape DstCodeLogParmChg Log parameters have changed DstCodeLUNNotConf Logical unit not self-configured yet DstCodeLUNNotSupp Logical unit not supported (must be zero) DstCodeMemAllocFailed Kernel memory allocation failed DstCodeModeSelectFailed Mode select call failed DstCodeModeSenseFailed Mode sense call failed DstCodeN2RTrans Transition from not-ready to ready occurred DstCodeNegativeFMcount Negative FM count

DstCodeNoActionRequested

No action was specified with ioctl command

DstCodeNoCassette DstCodeNoDevice No tape drive detected

DstCodeNoEstablishedPos Unit not ready - needs positioning command

No cartridge present

Ampex 1308911-02 5-9

Running Head

DST API Overview libdd2 API Functions

DstCodeNoKnownErr No known error DstCodeNoPermission No permission to perform requested task DstCodeNoRemove Cartridge is prevented from removal DstCodeNoTapeInstalled No tape installed in the drive DstCodeNotRdyIC Unit not ready due to internal communications DstCodeNotRdyMan Unit not ready - manual intervention needed DstCodeOtherErr Other type of error DstCodeOverlapCmd Overlapped commands attempted DstCodeParmChanged Mode parameters have changed DstCodeParmLenErr Parameter list length error DstCodeProgrammingErr Programming error DstCodeRandPosErr Random positioning error DstCodeReadOnly Device is opened for read only purposes

Model No.

DstCodeRecRetries Recovered data with retries DstCodeReposErr Positioning failed during retries DstCodeReserved1 Reserved (other type of error) DstCodeReserveFailed Failed to reserve tape drive DstCodeReset Power-on reset or bus device reset occurred DstCodeRewindError Error while rewinding tape DstCodeRIncomplete Incomplete block read DstCodeRUnrecover Unrecovered read error DstCodeSetPosError Error while setting position on tape DstCodeThreshMet Threshold condition met DstCodeTrackFollow Track following error DstCodeUnknownFmt Unknown tape format

DstCodeUnsupportedCmd DstCodeVolOvr Volume overflow - EOM detected on write

DstCodeWeofError Write EOF error DstCodeWFault Write fault - data corrupted

Unsupported ioctl command submitted

DstCodeWrAppend Write append error

DstCodeWriteProt DstCodeWriteProtected Cartridge is write-protected

Cartridge is write-protected

5-10 Ampex 1308911-02

libdd2 API Functions DST API Overview

5.2.4 See Also

dd2_intro,

DST SCSI Tape Drive DD-2 Tape Format Guide

Ampex 1308911-02 5-11

Running Head

dst_clrlog libdd2 API Functions

Model No.

5.3 dst_clrlog

NAME

dst_clrlog - clear tape drive error and operational statistics.

SYNOPSIS

#include <dd2.h>

int dst_clrlog(int fd, dst_log_st *log);

DESCRIPTION

dst_clrlog() sets the tape drive error and operational statistics to their default v alues except for service statistics. The service statistics (such as total scanner head contact time) are not resettable.

You must have root permissions to use dst_clrlog().

PARAMETERS

fd The ﬁle descriptor returned by the open call.

*log Pointer to dst_log_st structure. This member is obsolete

RETURN V ALUES

The return value is DST_SUCCESS (0) or DST_FAILURE (-1). See the “DST API Overview”

on page 5-1 for information on

SEE ALSO

““DST API Overview” on page 5-1, dst_getlog(), dd2_clrlog_drive

since driver version 4.0 and will be ignored.

errno failure messages and associated DST result codes.

5-12 Ampex 1308911-02

libdd2 API Functions dst_convpos

5.4 dst_convpos

NAME

dst_convpos() - convert tape position from structure form to token form or token form to structure form.

SYNOPSIS

#include <dd2.h>

int dst_convpos(int fd, dst_convpos_st *pos);

DESCRIPTION

dst_convpos() con v erts a tape position from one form to another; i.e., from token to structure or structure to token. See the ““DST API Ov erview” on page 5-1 for information on position speciﬁcations, including: form, format, typedef enumerations (deﬁnitions), unions, structures, and tokens.

dst_convpos() is available to all users.

PARAMETERS

fd The ﬁle descriptor returned by the open call.

*pos Pointer to a structure of type

USAGE

dst_convpos() uses the *pos structure for both input and output. On input, the srcpos union provides the source (input) position speciﬁcation and the deﬁnitions for the conversion. On return, the (converted) position speciﬁcation.

dst_convpos_st.

source/dest members provide

destpos union provides the destination

Ampex 1308911-02 5-13

Running Head

dst_convpos libdd2 API Functions

typedef struct {

dst_pos_type_en source; /* Source position type */ dst_position_un srcpos; /* Source position */ dst_pos_type_en dest; /* Destination position type */ dst_position_un destpos; /* Destination position */

} dst_convpos_st;

Model No.

Before calling dst_convpos():

• Initialize the srcpos union with the source position speciﬁcation. If the speciﬁcation

is in structure form, set the information.

valid bit mask to specify which members contain valid

• Initialize the source and dest members of the *pos structure with deﬁnitions of the

source and destination position speciﬁcations.

On return, the

destpos union contains the converted position speciﬁcation. If the

speciﬁcation is in structure form, the information.

STRUCTURE MEMBERS

source/dest Source and destination position deﬁnitions. You can specify token/

srcpos A union containing the position token or structure to be converted.

valid bit mask speciﬁes which members contain valid

structure or structure/token but not token/token or structure/structure. The following deﬁnitions are valid:

oken Structure

DstPosTok DstPosDD2

DstPos600 DstPosDIS

The structure deﬁnition speciﬁes the format for the converted position speciﬁcation (DD-2, DST600, or DIS). Make sure that the source element contains appropriate position information for this deﬁnition as the conversion is performed without error checking of the source data.

When converting from structure to tok en, make sure that the

valid bit

is set correctly. dst_convpos() only converts complete positions. Use the dst_getpos()

function to get the complete form of the current position if necessary.

destpos A union into which this function places the converted position token or

structure.

5-14 Ampex 1308911-02

libdd2 API Functions dst_convpos

RETURN V ALUES

The return value is DST_SUCCESS (0) or DST_FAILURE (-1). See “DST API Overvie w” on

page 5-1 for information on

SEE ALSO

dst_api_intro(), dst_getpos(), dd2_getpos_tape

errno failure messages and associated DST result codes.

Ampex 1308911-02 5-15

Running Head

dst_format libdd2 API Functions

Model No.

5.5 dst_format

NAME

dst_format() - format a DD-2 tape.

SYNOPSIS

#include <dd2.h>

int dst_format(int fd, dst_format_st *fmt);

DESCRIPTION

A DD-2 tape must be formatted before it can be used for data storage. See the DST SCSI Tape Drive DD-2 Tape Format Guide for information on formatting and examples of several

commonly used formats.

Unless the No Re-Formatting ( special ﬁle, dst_format() formats unconditionally and does not check whether the target tape has already been formatted or contains data. Re-formatting a tape inv alidates all data written previously. To check the dst_getparam() function; the interface settings are reported by

dst_param_st.attributes.

dst_format() is available to all users.

PARAMETERS

fd The ﬁle descriptor returned by the open call.

*fmt Pointer to a structure of type

USAGE

dst_format() uses the *fmt structure for both input and output. On input, the structure speciﬁes how to format the tape cartridge in the drive. On return, the structure reports the format read from tape by the drive.

Before calling dst_format(), initialize the *fmt structure with the tape format speciﬁcation. The read only members are ignored on input and need not be initialized.

DST_NO_REFORMAT) interface parameter is set in the device

DST_NO_REFORMAT interface parameter setting, use the

dst_format_st.

typedef struct {

u_int flags; /* Flags */ dst_fmt_type_en type; /* Format type */

5-16 Ampex 1308911-02

libdd2 API Functions dst_format

dst_volid_t volid; /* Volume ID */ u_int asize; /* Partition A size in phys blks */ u_char acount; /* Partition A count */ u_int bsize; /* Partition B size in phys blks */ u_char bcount; /* Partition B count */ dst_fmt_layout_en layout; /* System zone layout */ u_int sz_size; /* System zone size (0 on input means use

* default size for installed tape) */

u_int spacing; /* Number of phys blks between sys zones

* (0 on input means use default spacing) */

u_char lastzone; /* Last system zone ID (read only) */ u_int lastptsz; /* Last part. sz in phys blks (read only) */ u_short lastptid; /* Last partition ID (read only) */ dst_tape_sz_en tapesize; /* Tape size (read only) */ dst_tape_type_en tapetype; /* Tape type (read only) */

} dst_format_st;

STRUCTURE MEMBERS

The members of the dst_format_st structure are deﬁned below. This structure type is used by both dst_format() and dst_status(). Information that pertains

only to dst_status() is identiﬁed as such. All other information is common to both functions.

flags Set to zero; no options currently supported on input. On return, indicates

whether the

type Format type. Must be one of the following:

DstFmtFull - full format (preformat) DstFmtPart - partial format, Group A only DstFmtInit - initialized, no preformat.

volid Byte array containing the volume ID. The volume ID is intended to

lastptsz member is valid.

uniquely identify the medium and is written to the VFI area on the tape. This is an arbitrary 6-byte value. Each byte can be any v alue, except all 6 bytes cannot be binary zero.

On input, you can specify the volume ID in one of two ways:

• You can supply six or fewer printable ASCII characters. If you

supply fewer than six characters, the function left-justiﬁes your input string and pads the right part of the volume ID with ASCII spaces.

• Y ou can supply a 12-digit he xadecimal number preﬁxed by 0x. This

number can be any value that is not all zeroes. The function does not pad your input; you must supply all 12 digits.

Ampex 1308911-02 5-17

Running Head

dst_format libdd2 API Functions

asize The size, in physical blocks, of the Group A partitions on the tape.

Model No.

Minimum partition size is 235 physical blocks. However, you can use zero to indicate that the partition takes up the remainder of the tape. Values in the range 1-234 are not allowed. Of the speciﬁed size, 35 physical blocks are reserved for system information and therefore not available for user data, leaving a usable minimum size of 200 physical blocks (roughly 240 million bytes).

The

asize parameter is ignored when the format type is

DstFmtInit.

acount The number of Group A partitions per partition pattern. This value must

be in the range 1-255.

The

acount parameter is ignored if the format type is DstFmtInit.

bsize The size, in physical blocks, of the Group B partitions on the tape.

Minimum partition size is 235 physical blocks. Howev er , you can use a zero value here to indicate that the partition takes up the remainder of the tape. Values in the range 1-234 are not allowed. Of the speciﬁed size, 35 physical blocks are reserved for system information and therefore not available for user data, leaving a usable minimum size of 200 physical blocks (roughly 240 million bytes).

If the format type is

DstFmtInit or DstFmtPart, zero is the only

valid value.

bcount The number of Group B partitions per partition pattern, in the range 0-

255. A zero indicates that there is only one type of partition on the tape (the Group A partition).

If the format type is

If the format type i

layout Tape layout, indicating how to handle allocation of partitions across

DstFmtInit, zero is the only valid value.

s DstFmtPart, one is the only valid value.

system zones. The following deﬁnitions apply:

DstPack - Packs as many partitions as possible onto the tape, allowing

any given partition to span a system zone if necessary. If there is not enough space for a full partition between the last system zone and EOT, the remaining space is not used.

DstStretch - An y gi v en partition is stretched to the next system zone

if there is not room for another partition before the system zone. This can mean that some partitions are larger than the speciﬁed size. If there is not enough space for a full partition between the last system zone and EOT, the last partition is extended to EOT.

5-18 Ampex 1308911-02

libdd2 API Functions dst_format

DstWaste - Does not allocate partitions across system zones. Instead,

allocates each partition with exactly the speciﬁed size, wasting any space between the end of the partition and the system zone if there’s not enough room for another partition before the system zone. If there is not enough space for a full partition between the last system zone and EOT, the remaining space is not used.

DstAlternate - Puts a system zone between every partition and no

system zones inside of any partition. If there is not enough space for a full partition between the last system zone and EOT, the remaining space is not used.

DstNoZones - Formats the tape without system zones.

DstDisFmt - (Read Only) Indicates a DIS formatted tape is loaded in

the drive.

sz_size System zone size in physical blocks; valid only if the layout member

is not

DstNoZones. If zero, dst_format() uses the default system zone

size matching the cartridge size of the loaded tape. The defaults are the same as the minimum allowed values and are given by the

DST_MIN_SMALL_SZSIZE, DST_MIN_MEDIUM_SZSIZE, and DST_MIN_LARGE_SZSIZE symbolic constants in the dstioctl.h

header ﬁle.

spacing Number of physical blocks between system zones; valid only if the

layout member is not DstAlternate. Must be zero or at least DST_MIN_SYSTEM_ZONE_SPACING. If zero, dst_format() uses the

default system zone spacing matching the cartridge size of the loaded tape. The defaults are given by the

DST_DEF_MEDIUM_SZSP, and DST_DEF_LARGE_SZSP symbolic

constants in the

lastzone (Read Only) Speciﬁes the ID of the last system zone on the tape. System

dstioctl.h header ﬁle.

DST_DEF_SMALL_SZSP,

zones are numbered starting with zero. Only valid for fully preformatted tapes.

lastptsz (Read Only) Speciﬁes the size of the last partition on the tape.

lastptid (Read Only) Speciﬁes the partition ID of the last partition on the tape.

Partitions are numbered starting with zero. Only valid for fully preformatted tapes.

Ampex 1308911-02 5-19

Running Head

dst_format libdd2 API Functions

tapesize (Read Only) Speciﬁes tape cartridge size as one of the following values:

DstSmall = 0x00, /* 25 Gb (50 Gb if double-density, 100 Gb if quad-density)*/

DstMedium = 0x01, /* 75 Gb (150 Gb if double-density, 300 Gb if quad-density) */

DstLarge = 0x02, /* 165 Gb (330 Gb if double-density, 660 Gb if quad-density) */

DstUnknown = 0xfe, /* Unknown tape size */

DstAbsent = 0xff /* No tape present */

tapetype (Read Only) Speciﬁes the tape cartridge type as one of the following

Model No.

values:

DstTapeQuadData = 0x01, /* Quad density DD-2 data tape */

DstTapeHiClean = 0x02, /* High abrasivity cleaning tape */ DstTapeData = 0x05, /* User DD-2 data tape */ DstTapeLoClean = 0x06, /* Low abrasivity cleaning tape */ DstTapeMaint = 0x0e /* Maintenance tape */

BUGS

lastptsz always returns zero.

RETURN V ALUES

The return value is DST_SUCCESS (0) or DST_FAILURE (-1). See “DST API Overvie w” on

page 5-1 for information on

1. Before a format command can be issued to the tape driv e, dst_format() checks that a tape

is installed and that it is not write protected.

If no tape is installed dst_format() returns DST result code set to

If the installed tape is write protected, dst_format() returns with

EROFS (30) and the DST result code set to DstCodeTapeWriteProt.

2. If the

DST_NO_REFORMAT interface parameter is set, the current tape is checked for a

valid format. If the current tape is unformatted the format proceeds; otherwise dst_format() returns with

DstCodeNoPermission.

errno failure messages and associated DST result codes.

-1 with errno set to EIO (5) and the

DstCodeNoTapeInstalled.

errno set to

errno set to EPERM (1) and the DST result code set to

3. If a read or write command is attempted immediately after a format (i.e., before a

position command is issued), zero bytes are returned and the DST result code is set to

DstCodeNotRdyNoPos.

5-20 Ampex 1308911-02

libdd2 API Functions dst_format

SEE ALSO

“DST API Overview” on page 5-1, dst_status()), dd2_format_tape, DST SCSI Tape Drive

DD-2 Tape Format Guide

Ampex 1308911-02 5-21

Running Head

dst_getdrive libdd2 API Functions

Model No.

5.6 dst_getdrive

NAME

dst_getdrive() - get tape drive product information, conﬁguration and capabilities, and tape device driver version.

SYNOPSIS

#include <dd2.h>

int dst_getdrive(int fd, dst_drive_st *drive);

DESCRIPTION

dst_getdrive() reports the following:

• Tape drive product information, conﬁguration attributes and parameter settings,

capabilities and buffer size.

• Tape device driver version, release date, and current functionality (latest changes or

added features).

There is usually no need to alter the default tape drive conﬁguration. If the need does arise, use the dst_setdrive() function.

dst_getdrive() is available to all users.

PARAMETERS

fd The ﬁle descriptor returned by the open call.

*drive Pointer to a structure of type

USAGE

dst_getdrive() uses the *drive structure for both input and output.

• On input, the valid bit mask speciﬁes which members to get information for.

• On successful return, the valid bit mask indicates which members are reporting current

status.

• If the valid bit mask is different on return, it indicates that dst_getdrive() could not

get all of the status requested.

dst_drive_st.

Before calling dst_getdrive(), initialize the

5-22 Ampex 1308911-02

valid bit mask appropriately.

libdd2 API Functions dst_getdrive

typedef struct {

u_int valid; /* Valid members - see defines above */ u_int config; /* Drive configuration attributes */ u_char rdretryct; /* Read retry count (0-80) */ u_char wrretryct; /* Write retry count (0-127) */ u_char wrbuffull; /* Write buffer full ratio/256 (25-200) */ u_char rdbuffull; /* Read buffer full ratio/256 (25-200) */ int wrdelay; /* Write delay 100 millisecs (1-65535) */ u_char sctimeout; /* Scanner timeout in minutes (0-30) */ u_char thtimeout; /* Thread timeout in seconds (6-30) */ int ewoffset; /* EW offset before EMW, in PBs (0-) */ int cleantime; /* Cleaning time in seconds (1-) */ dst_ddver_st ddver; /* DST Driver version info (read only) */ dst_tdver_st tdver; /* Tape drive version info (read only) */ u_int capability; /* Drive capabilities (read only) */ int bufsize; /* Drive buffer size in bytes (read only) */

} dst_drive_st;

STRUCTURE MEMBERS

valid Bit mask that speciﬁes which members to get information for on input,

and which members contain valid information on return. The follo wing deﬁnitions apply (see the

DST_CFG_VALID DST_RDRTY_VALID DST_WRRTY_VALID DST_WRBUF_VALID DST_RDBUF_VALID DST_WRDLY_VALID DST_SCTO_VALID DST_THTO_VALID DST_EWOFF_VALID DST_DDVER_VALID DST_TDVER_VALID DST_CAP_VALID DST_CLTM_VALID DST_BUFSZ_VALID

config Bit mask of the drive conﬁguration. The follo wing deﬁnitions apply (see

the

dstio.h ﬁle for details): DST_POST_ERR - post internal retry errors DST_SYNC_EW - synchronize buffer at EW DST_EOR_BLOAD - search forward after load DST_PARK_ANY - park anywhere DST_CHECKSUM - enable data block checksums

dstio.h ﬁle for details):

rdretryct Read retry count. The default is 5. The range is 0-255.

Ampex 1308911-02 5-23

Running Head

dst_getdrive libdd2 API Functions

wrretryct Write retry count. The default is 5. The range is 0-255.

wrbuffull Write buffer full ratio, di vided by 256 to obtain percentage. The def ault

Model No.

is 0. The range is 0 or 1-255. A value of zero indicates that the drive waits until the its buffer is half full before writing to tape.

rdbuffull Read buffer full ratio, di vided by 256 to obtain percentage. The def ault

is 0. The range is 0 or 1-255. A value of zero indicates that the drive begins retrieving data from tape when its buffer is half empty.

wrdelay Write delay time, multiplied by 100 milliseconds. The default is 0. The

range is 1-65535.

sctimeout Scanner time-out in minutes. The default is 5. The range is 0-30.

thtimeout Thread time-out in seconds. The default is 15. The range is 6-30.

ewoffset Early Warning (EW) offset before End of Media Warning (EMW), in

physical blocks. The default is 100. The range is 0-1677215.

cleantime Cleaning time in seconds when using a head cleaning cartridge. The

default is 5. The range is 1 - 65535.

ddver A structure of tape device driver version information.

typedef struct {

char drvversion[80]; /* Driver version number/ID */ char notes[80]; /* Notes */ char comments[80]; /* Comments */

} dst_ddver_st;

version - 80-byte character array that reports the current tape device

driver version (for example “4.0”).

notes - 80-byte character array that provides a short description on

the latest changes or added functionality (such as “Now Supports AIX”).

comments - 80-byte character array that reports the tape device

driver’s release date (for example “Released 31st July 1996”).

tdver An extensive structure of tape drive product information.

/* ** Structure for tape drive version info. ** All fields are plain ASCII characters unless otherwise noted.

5-24 Ampex 1308911-02

libdd2 API Functions dst_getdrive

** No terminating NULs are guaranteed, so use counts with any string ops! */ typedef struct {

char vendor[8]; /* DST tape drive vendor name */ char product[16]; /* DST tape drive product name */ char rcfver[4]; /* RCF firmware version */ char tcfver[4]; /* TCF firmware version */ char pcfver[4]; /* PCF firmware version */ char systemrev[8]; /* System revision number */ char serialnum[4]; /* System serial number */ char mfgid[16]; /* Manufacturer's ID */ u_char transport; /* Transport type */ char ibsboard[20]; /* IBS board info */ char sbcboard[20]; /* SBC board info */ char eccboard[20]; /* ECC board info */ char eqltboard[20]; /* EQ/TL board info */ char astctlboard[20]; /* AST/CTL board info */ char mdaboard[20]; /* Servo MDA board info */

} dst_tdver_st;

capability A bit mask of tape drive capabilities (see the dstio.h file for details).

bufsize Tape drive data buffer size in bytes.

RETURN V ALUES

The return value is DST_SUCCESS (0) or DST_FAILURE (-1). See paragraph 5.2 for information on

EXAMPLE

The following is an example of how to call the dst_getdrive() function:

/* ** get drive configuration */ d2_drive.valid = DST_CFG_VALID; if (dst_getdrive(fd, &d2_drive)) {

perror ("dst_getdrive() failed");

exit (1); } printf("getdrive config: 0x%x ...\n", d2_drive.config);

errno failure messages and associated DST result codes.

SEE ALSO

“DST API Overview” on page 5-1, dst_setdrive(), dd2_set_drive

Ampex 1308911-02 5-25

Running Head

dst_getdrive_ex libdd2 API Functions

Model No.

5.7 dst_getdrive_ex

NAME

dst_getdrive_ex() - get tape drive product information, conﬁguration and extended capabilities, and tape device driver version.

SYNOPSIS

#include <dd2.h>

int dst_getdrive_ex(int fd, dst_drive_ex_st *drive);

DESCRIPTION

dst_getdrive_ex() reports the following:

• T ape drive product information, conﬁguration attrib utes and parameter settings, extended

capabilities, and buffer size.

• Tape device driver version, release date, and current functionality (latest changes or

added features).

There is usually no need to alter the default tape drive conﬁguration. If the need does arise, use the dst_setdrive() function.

dst_getdrive_ex() is available to all users.

PARAMETERS

fd The ﬁle descriptor returned by the open call.

*drive Pointer to a structure of type

USAGE

dst_getdrive_ex() uses the *drive structure for both input and output.

• On input, the valid bit mask speciﬁes which members to get information for.

• On successful return, the valid bit mask indicates which members are reporting current

status.

• If the valid bit mask is different on return, it indicates that dst_getdrive_ex() could

not get all of the status requested.

dst_drive_ex_st.

Before calling dst_getdrive_ex(), initialize the

5-26 Ampex 1308911-02

valid bit mask appropriately.

libdd2 API Functions dst_getdrive_ex

typedef struct

{

} dst_drive_ex_st;

STRUCTURE MEMBERS

valid Bit mask that speciﬁes which members to get information for on input,

config

and which members contain valid information on return. The follo wing deﬁnitions apply (see the

dstio.h ﬁle for details):

Bit mask of the drive conﬁguration. The follo wing deﬁnitions apply (see the

dstio.h ﬁle for details): DST_POST_ERR - post internal retry errors DST_SYNC_EW - synchronize buffer at EW

Ampex 1308911-02 5-27

Running Head

dst_getdrive_ex libdd2 API Functions

DST_EOR_BLOAD - search forward after load DST_PARK_ANY - park anywhere DST_CHECKSUM - enable data block checksums

rdretryct Read retry count. The default is 5. The range is 0-255.

wrretryct Write retry count. The default is 5. The range is 0-255.

wrbuffull Write buffer full ratio, di vided by 256 to obtain percentage. The def ault

Model No.

is 0. The range is 0 or 1-255. A value of zero indicates that the drive waits until the its buffer is half full before writing to tape.

rdbuffull Read buffer full ratio, di vided by 256 to obtain percentage. The def ault

is 0. The range is 0 or 1-255. A value of zero indicates that the drive begins retrieving data from tape when its buffer is half empty.

wrdelay Write delay time, multiplied by 100 milliseconds. The default is 0. The

range is 1-65535.

sctimeout Scanner time-out in minutes. The default is 5. The range is 0-30.

thtimeout Thread time-out in seconds. The default is 15. The range is 6-30.

ewoffset Early Warning (EW) offset before End of Media Warning (EMW), in

physical blocks. The default is 100. The range is 0-1677215.

cleantime Cleaning time in seconds when using a head cleaning cartridge. The

default is 5. The range is 1 - 65535.

ddver A structure of tape device driver version information.

typedef struct {

char drvversion[80]; /* Driver version number/ID */ char notes[80]; /* Notes */ char comments[80]; /* Comments */

} dst_ddver_st;

version - 80-byte character array that reports the current tape device

driver version (for example “4.0”).

notes - 80-byte character array that provides a short description on

the latest changes or added functionality (such as “Now Supports AIX”).

comments - 80-byte character array that reports the tape device

driver’s release date (for example “Released 31st July 1996”).

5-28 Ampex 1308911-02

libdd2 API Functions dst_getdrive_ex

tdver An extensive structure of tape drive product information.

/* ** Structure for tape drive version info. ** All fields are plain ASCII characters unless otherwise noted. ** No terminating NULs are guaranteed, so use counts with any string ops! */ typedef struct {

} dst_tdver_st;

capability A bit mask of tape drive capabilities (see the dstio.h ﬁle for details).

bufsize Tape drive data buffer size in bytes.

capability_ex A bit mask of tape drive extended capabilities (see the dstio.h ﬁle for

details).

density T ape dri v e density. The following values apply (see the dstio.h ﬁle for

details): DstUnknownDensity - drive density not known DstSingleDensity - single density drive DstDoubleDensity - double density drive DstQuadDensity - quad density drive

speed Maximum data rate the drive is capable of in megabytes per second.

reserved0 Reserved for future use.

reserved1 Reserved for future use.

Ampex 1308911-02 5-29

Running Head

dst_getdrive_ex libdd2 API Functions

Model No.

RETURN V ALUES

The return value is DST_SUCCESS (0) or DST_FAILURE (-1). See paragraph 5.2 for information on

errno failure messages and associated DST result codes.

EXAMPLE

The following is an example of how to call the dst getdrive_ex() function:

/* ** get extendeddrive configuration */ d2_drive_ex.valid = DST_CFG_VALID; if (dst_getdrive_ex(fd, &d2_drive_ex)) {

perror ("dst_getdrive_ex() failed");

exit (1); } printf("getdrive extended config: 0x%x ...\n", d2_drive_ex.config);

SEE ALSO

“DST API Overview” on page 5-1, dst_setdrive(), dd2_set_drive

5-30 Ampex 1308911-02

libdd2 API Functions dst_getlog

5.8 dst_getlog

NAME

dst_getlog() - get tape drive error, operational, service, and diagnostic statistics.

SYNOPSIS

#include <dd2.h>

int dst_getlog(int fd, dst_log_st *log);

DESCRIPTION

dst_getlog() retrieves error and operational statistics from tape drive integer counters. This information is intended to aid service personnel in diagnosing and correcting problems.

The tape drive increments a given counter every time the associated event occurs. An exception is registered if a counter’s threshold value is exceeded.

You can use dst_clrlog() to reset the error and operational statistics counters to their starting values (usually zero). The service statistics counters cannot be reset.

dst_getlog() is available to all users

PARAMETERS

fd The ﬁle descriptor returned by the open call.

*log Pointer to a structure of type

USAGE

dst_getlog() uses the *log structure for both input and output. Before calling dst_getlog(), initialize the *log structure retrieve.

dst_log_st.

flags and type members to indicate which information to

Ampex 1308911-02 5-31

Running Head

dst_getlog libdd2 API Functions

typedef struct {

u_int flags; /* Log category mask */ u_int type; /* Log parameter type */ u_int bufunder; /* Buffer underruns */ u_int bufover; /* Buffer overruns */ u_int wrerr; /* Write errors */ u_int wrerrc; /* Write errors corrected */ u_int wrretry; /* Write retries */ u_int wrerru; /* Write errors uncorrected */ u_int rderr; /* Read errors */ u_int rderrc; /* Read errors corrected */ u_int rdretry; /* Read retries */ u_int rderru; /* Read errors uncorrected */ u_int nmerr; /* Non-medium errors */ dst_log_serv_st servstats; /* Service statistics */ dst_log_optm_st optmstats; /* TM operational statistics */ dst_log_opem_st opemstats; /* EM operational statistics */ dst_log_msr_st msrstats; /* MSR diagnostic statistics */

} dst_log_st;

Model No.

PARAMETERS

flags Speciﬁes the statistics to be retrieved :

type Type of statistics to be retrieved:

bufunder Buffer Underruns - A buffer underrun is detected during a write

bufover Buffer Overruns - A buffer overrun is detected during a read operation

DST_LOG_IOERR - get statistics for u_int members only. DST_LOG_SERV - get statistics for servstats member only. DST_LOG_OPTM - get statistics for optmstats member only. DST_LOG_OPEM - get statistics for opemstats member only. DST_LOG_MSR - get statistics for msrstats member only. DST_LOG_ALL - get statistics for all members.

DST_LOG_THRESHOLD - threshold values. DST_LOG_CUMULATIVE - cumulative values. DST_LOG_DEFAULT_THRESHOLD - default threshold values. DST_LOG_DEFAULT_CUMULATIVE - default cumulative values.

operation when a buffer empty condition pre vents continued transfer of data to tape from the buffer; this occurs when the initiator does not transfer data to the buffer fast enough to keep up with writing to tape.

when a buffer full condition prevents continued transfer of data to the buffer from tape. This occurs when the initiator does not transfer data from the buffer fast enough to keep up with reading from tape.

wrerr Write Errors - The total number of write errors encountered, including

those detected during retries.

5-32 Ampex 1308911-02

libdd2 API Functions dst_getlog

wrerrc Write Errors Corrected - The number of successful applications of the

write retry algorithm that occurred within the allowed number of retries.

wrretry Write Retries - The total number of times the drive attempted a write

retry, regardless of whether the write attempt succeeded.

wrerru Write Errors Uncorrected - The number of unsuccessful applications of

the write retry algorithm that occurred within the allowed number of retries.

rderr Read Errors - The total number of read errors encountered, including

those detected during retries.

rderrc Read Errors Corrected - The number of successful applications of the

read retry algorithm that occurred within the allowed number of retries.

rdretry Read Retries - The total number of times the drive attempted a read

retry, regardless of whether the read attempt succeeded.

rderru Read Errors Uncorrected - The number of unsuccessful applications of

the read retry algorithm that occurred within the allowed number of retries.

nmerr Non-Medium Errors - The number or recoverable error events other

servstats Service Statistics - Structure for storing the 31 service statistics

optmstats Transport Module Operational Statistics - Structure for storing the 24

opemstats Electronics Module Operational Statistics - Structure for storing the 99

msrstats MSR Diagnostic Statistics - Character array for storing up to 620 bytes

RETURN V ALUES

than write, read, or verify failures.

parameters (see the

dst_log_serv_st structure in the dstio.h

ﬁle and Table E-1.). This information is intended to aid service personnel in diagnosing and correcting problems.

transport statistics parameters (see the in the

dstio.h ﬁle and Table E-2.).

electronics statistics parameters (see the in the

dstio.h ﬁle and Table E-3.).

of diagnostic statistics (see the

dstio.h ﬁle and Appendix D). This information is intended to aid

dst_log_opem_st structure in the

dst_log_optm_st structure

dst_log_opem_st structure

service personnel in diagnosing and correcting problems.

The return value is DST_SUCCESS (0) or DST_FAILURE (-1). See “DST API Overvie w” on

page 5-1 for information on

Ampex 1308911-02 5-33

errno failure messages and associated DST result codes.

Running Head

dst_getlog libdd2 API Functions

Model No.

SEE ALSO

“DST API Overview” on page 5-1, dst_clrlog(), dd2_getlog_drive

5-34 Ampex 1308911-02

libdd2 API Functions dst_getparam

5.9 dst_getparam

NAME

dst_getparam() - get tape drive data block size, tape device driver debug level, and device special ﬁle interface parameter settings.

SYNOPSIS

#include <dd2.h>

int dst_getparam(int fd, dst_param_st *parms);

DESCRIPTION

dst_getparam() reports the current tape drive block size, debug level, and device special ﬁle interface parameter settings. The interface parameters specify default behavior for the tape drive. They are set on each call according to the device special ﬁle selected.

For information about the tape cartridge in the drive or the results of the last I/O operation, use the dst_status() function. T o change any of the interf ace parameters, use the dst_setparam() function.

dst_getparam() is available to all users.

PARAMETERS

fd The ﬁle descriptor returned by the open call.

*parms Pointer to a structure of type

USAGE

dst_getparam() uses the *parms structure for both input and output.

• On input, the valid bit mask speciﬁes which members to get information for.

• On return, the valid bit mask indicates which members are reporting current status

retrieved from the drive or tape device driver.

• If the valid bit mask is different on return, it indicates dst_getparam() could not get

all of the status requested.

dst_param_st.

Before calling dst_getparam(), initialize the

typedef struct dst_param {

Ampex 1308911-02 5-35

valid bit mask appropriately.

Running Head

dst_getparam libdd2 API Functions

u_int valid; /* Valid members */ int blksize; /* Current blocksize in bytes */ u_int dbglevel; /* Device driver debug message level */ u_int attributes; /* Bit mask of attributes */

} dst_param_st;

Model No.

STRUCTURE MEMBERS

valid Bit mask that speciﬁes which members to get information for on input,

and which members contain valid information on return. The follo wing deﬁnitions apply (see the

DST_ATTR_VALID DST_BLK_VALID DST_DBG_VALID

blksize Data block size in bytes. The block size does not include the two-byte

checksum, if any.

dbglevel Bit mask representing the current tape device driver debug level. Zero

unless tape device driver debug messages have been enabled; see the dst_setparam() manual page for details.

dstio.h ﬁle for details):

attributes Bit mask of device special ﬁle interface parameter settings (see the

Software Installation Manual for your host system for details):

DST_NO_REWIND - Do not rewind on close device. DST_NO_FM - Do not write ﬁlemarks on close. DST_NO_RESERVE - Do not reserve unit for exclusive use. DST_NO_FLUSH - Do not ﬂush tape drive buffer. DST_NO_OPN_CMD - Do not issue any commands on open. DST_SBLK_SIZE - Force user deﬁned block size on open. DST_REWIND_OPN - Rewind on open to BOP. DST_SPC_FWD - Space forward on close, if not at end of ﬁle (EOF). DST_APPEND_ONLY - Allow writing at end of data (EOD) only. DST_BYTE_SWAP - Swap bytes of all data transferred. DST_DEF_POS_OPN - If position is undeﬁned on open, set to BOT. DST_NO_REFORMAT - No re-formatting of formatted tapes. DST_SYNC_WRITE - Flush tape drive buffer after every write. DST_ZERO_ON_FM - Report zero bytes for read after ﬁlemark (FM). DST_ZERO_ON_EW - Report zero bytes for write after EW. DST_IGN_FM - Ignore FM on ﬁrst read after open. DST_OPEN_RDONLY - Open for read only. DST_OBSOLETE - Obsolete; used to be DST_WRITTEN. DST_WRITE_PROT - Cartridge is write protected. DST_OBSOLETE1 - Obsolete; used to be Disable Checksums. DST_OBSOLETE2 - Obsolete; used to be High Density Drive. DST_OBSOLETE3 - Obsolete; used to be Set EOR Beyond Load Bit.

5-36 Ampex 1308911-02

libdd2 API Functions dst_getparam

RETURN V ALUES

The return value is DST_SUCCESS (0) or DST_FAILURE (-1). See “DST API Overvie w” on

page 5-1 for information on

SEE ALSO

“DST API Overview” on page 5-1, dst_set_param(), dst_status(), dd2-getparam_drive

errno failure messages and associated DST result codes.

Ampex 1308911-02 5-37

Running Head

dst_getpos libdd2 API Functions

Model No.

5.10 dst_getpos

NAME

dst_getpos() - get current position.

SYNOPSIS

#include <dd2.h>

int dst_getpos(int fd, dst_position_st *pos);

DESCRIPTION

dst_getpos() reports the current tape drive position in token or structure form. This is the data block address at which the next read or write operation occurs.

The position returned by dst_getpos() does not necessarily reﬂect the actual physical tape head position. For example, if there is data in the tape driv e buffer that has not yet been written to tape, dst_getpos() returns the next buf fer position, not the current tape head position. If you need the actual physical position, use the dst_status() function, which also returns other position-related information such as number of unsynchronized bytes in the tape drive data buffer and the remaining capacity of the current partition.

dst_getpos() is available to all users.

PARAMETERS

fd The ﬁle descriptor returned by the open call.

*pos Pointer to a structure of type

USAGE

dst_getpos() uses the *pos structure for both input and output.

• On input, the type member deﬁnes the position speciﬁcation to be retrieved from the

drive; see “DST API Overview” on page 5-1 for details.

• On successful return, the pos member contains the position speciﬁcation which

indicates the current position of the drive. If the speciﬁcation is in structure form, the

valid bit mask speciﬁes which members contain valid information.

typedef struct {

dst_pos_type_en type; /* Position type */ dst_position_un pos; /* Position */

dst_position_st.

5-38 Ampex 1308911-02

libdd2 API Functions dst_getpos

} dst_position_st;

Before calling dst_getpos(), initialize the type member of the *pos structure with the deﬁnition of the position speciﬁcation you want the drive to return. The other members need not be initialized.

RETURN V ALUES

The return value is DST_SUCCESS (0) or DST_FAILURE (-1). See “DST API Overview” on

page 5-1 for information on

1. For end of ﬁle (EOF) or end of data (EOD), dst_getpos() succeeds and returns the actual logical position. It does not return -1 to indicate EOF or EOD. Use dst_status() to determine if the tape is at EOF or EOD.

errno failure messages and associated DST result codes.

2. If no tape is installed, dst_getpos() returns -1 with

3. If the tape is installed but the Ready/Not Ready button on the front panel is Not Ready,

4. If the tape position cannot be determined, dst_getpos() returns -1 with

5. dst_getpos() returns

SEE ALSO

“DST API Overview” on page 5-1, dst_convpos(), dst_setpos(), dst_status(),

dd2_getpos_tape

errno set to EIO (5) and the DST

result code set to

dst_getpos() returns -1 with

DstCodeNoEstablishedPos.

(5) and the DST result code set to DstCodeGetPosError.

DST_TIMECODE_VALID are set.

DstCodeNoTapeInstalled.

errno set to EIO (5) and the DST result code set to

EINVAL (22) if DST_FSN_VAIID, DST_DBN_VALID, and

errno set to EIO

Ampex 1308911-02 5-39

Running Head

dst_getstate libdd2 API Functions

Model No.

5.11 dst_getstate

NAME

dst_getstate() - get tape drive current state.

SYNOPSIS

#include <dd2.h>

int dst_getstate(int fd, dst_state_st *state);

DESCRIPTION

dst_getstate is a limited version of dst_status that lets you quickly determine whether a tape is installed and ready for I/O operations. It is available to all users.

PARAMETERS

fd The ﬁle descriptor returned by the open call.

*state Pointer to a structure of type

USAGE

dst_getstate() reports the drive state in the *state structure.

typedef struct dst_state { u_int state; /* Current state of drive */ } dst_state_st;

STRUCTURE MEMBERS

state Bit-mask of the current drive state. The following deﬁnitions apply

dst_state_st.

(deﬁnitions in parenthesis are old descriptors that have been retained for compatibility with existing applications):

DST_READY (DST_IS_READY) DST_PRESENT (DST_CASS_PRESENT) DST_LOADED (DST_IS_LOADED) DST_WR_PROTECT (DST_WR_PROTECTED)

DST_PRESENT or DST_CASS_PRESENT is set when a tape is present

in the drive; however, this doesn’t mean that the drive is ready for user interaction.

5-40 Ampex 1308911-02

libdd2 API Functions dst_getstate

DST_LOADED or DST_IS_LOADED is set when the drive completes a

volume search; however, this doesn’t mean that the drive is ready for user interaction.

DST_WR_PROTECT or DST_WR_PROTECTED is set when the installed

tape is found to be write protected.

DST_READY or DST_IS_READY is set when necessary to perform

operations that establish a logical position on tape.

RETURN V ALUES

The return value is DST_SUCCESS (0) or DST_FAILURE (-1). See “DST API Overvie w” on

page 5-1 for information on

SEE ALSO

“DST API Overview” on page 5-1, dst_status()

The tape drive is ready for user interaction, when

DST_PRESENT, and DST_LOADED are all set.

errno failure messages and associated DST result codes.

DST_READY,

Ampex 1308911-02 5-41

Running Head

dst_gettrace libdd2 API Functions

Model No.

5.12 dst_gettrace

NAME

dst_gettrace() - get a ﬁrmware trace log from the tape drive.

SYNOPSIS

#include <dd2.h>

int dst_gettrace(int fd, dst_trace_st *trace);

DESCRIPTION

dst_gettrace() gets one of the four available tape dri v e ﬁrmware trace logs. This information is intended to aid service personnel in diagnosing and correcting problems.

A trace log consists of printable ASCII characters. Within the log, each ASCII line feed character indicates a new line. Y ou can retrie v e an entire log or just the last (most recent) line.

dst_gettrace() is available to all users.

PARAMETERS

fd The ﬁle descriptor returned by the open call.

*trace Pointer to a structure of type

USAGE

dst_gettrace() uses the *trace structure for both input and output. Before calling dst_gettrace(), initialize the structure appropriately.

typedef struct {

dst_trace_type_en type; /* Trace log type */ int start; /* Starting line, from end */ int size; /* Size of trace buffer */ int offset; /* Offset before data required */ int length; /* Size of complete log*/ int no_of_lines; /* Number of lines in complete log */ caddr_t buf; /* Pointer to trace buffer */

} dst_trace_st;

dst_trace_st.

The log data is loaded into the trace buffer that the buf member points to. On input, the size member speciﬁes the capacity of the buffer. On return, the size member speciﬁes the number of bytes stored in the buffer

5-42 Ampex 1308911-02

libdd2 API Functions dst_gettrace

When you request an entire log, data retrieval starts with the ﬁrst (earliest) entry in the log. The

offset member permits specifying whether any data bytes should be discarded before

loading of the buffer is enabled. Should a b uffer full condition occur , dst_gettrace() succeeds, terminates successfully and remembers where it left off. To continue retrieving data from the log, repeat the dst_gettrace() call.

STRUCTURE MEMBERS

type Speciﬁes the trace log to get. The following deﬁnitions apply:

DstTraceTCF - Transport Control Firmware trace log DstTracePCF - Process Control Firmware trace log DstTraceRCF - Recorder Control Firmware trace log DstTraceSCSI - SCSI Control Firmware trace log

start Speciﬁes the information to get from the log. The following deﬁnitions

apply:

DST_TRACE_ALL - get the entire log, starting with the ﬁrst (oldest)

entry

DST_TRACE_LAST - get the last entry in the log DST_TRACE_CONT - continue from ending point of last call

size On input, speciﬁes the capacity of the available trace b uffer in bytes. On

offset Speciﬁes how many data bytes to discard before loading of the buffer

length Read only member; if start is set to DST_TRACE_ALL, length

no_of_lines Read only member; if start is set to DST_TRACE_ALL,

buf Address of the trace buffer.

RETURN V ALUES

return, speciﬁes the number of data bytes stored in the buffer.

T o pre v ent b uf fer ov erﬂo w

DST_GETTRACE only returns size bytes

into the trace buffer. If the buffer is not large enough for the entire log, you can get the next portion of the log by calling dst_gettrace() again with the

start member set to DST_TRACE_CONT.

occurs; i.e., how much of the log to skip over. To retrie ve the entire log, set

offset to zero.

indicates the number of data bytes available in the complete log; otherwise it is set to -1.

no_of_lines indicates the number of lines a v ailable in the complete

log; otherwise it is set to -1.

The return value is DST_SUCCESS (0) or DST_FAILURE (-1). See “DST API Overvie w” on

page 5-1 for information on

Ampex 1308911-02 5-43

errno failure messages and associated DST result codes.

Running Head

dst_gettrace libdd2 API Functions

Model No.

SEE ALSO

dst_api_intro(), dd2_gettrace_drive

5-44 Ampex 1308911-02

libdd2 API Functions dst_reset

5.13 dst_reset

NAME

dst_reset() - reset the tape drive.

SYNOPSIS

#include <dd2.h>

int dst_reset(int fd);

DESCRIPTION

dst_reset() resets the tape drive. This restores the drive’s conﬁguration parameters to the last saved values and clears any active I/O process, pending data, and status. The tape drive performs its standard power-on self tests, after which the drive status indicators and display begin normal operation. dst_reset() returns immediately , howe ver . It doesn’t wait for the dri ve to return to normal status.

dst_reset() normally results in a reset identical to that obtained by manually pressing the drive reset button. However, certain conﬁgurations may result in soft resets for some conditions (such as concurrent use of the drive by multiple hosts).

Using dst_reset() to perform a software reset is usually preferable to manually pressing the drive RESET button because it gives the host system software better recovery opportunities.

dst_reset() is restricted to the root user.

PARAMETERS

fd The ﬁle descriptor returned by the open call.

RETURN V ALUES

The return value is DST_SUCCESS (0) or DST_FAILURE (-1). See “DST API Overvie w” on

page 5-1 for information on

SEE ALSO

dst_api_intro(), dd2_reset_drive

errno failure messages and associated DST result codes.

Ampex 1308911-02 5-45

Running Head

dst_rewind libdd2 API Functions

Model No.

5.14 dst_rewind

NAME

dst_rewind() - rewind tape to Beginning of Partition (BOP).

SYNOPSIS

#include <dd2.h>

int dst_rewind(int fd);

DESCRIPTION

dst_rewind moves the current position to the be ginning of the current partition (BOP). If the cartridge was just inserted, the current partition is assumed to be 0.

dst_rewind is available to all users.

PARAMETERS

fd The ﬁle descriptor returned by the open call.

RETURN V ALUES

The return value is DST_SUCCESS (0) or DST_FAILURE (-1). See paragraph “DST API

Overview” on page 5-1 for information on

result codes.

SEE ALSO

“API Introduction” on page 5-1, dd2_rewind_tape

errno failure messages and associated DST

5-46 Ampex 1308911-02

libdd2 API Functions dst_setdrive

5.15 dst_setdrive

NAME

dst_setdrive() - changes tape drive conﬁguration parameters.

SYNOPSIS

#include <dd2.h>

int dst_setdrive(int fd, dst_drive_st *drive);

DESCRIPTION

dst_setdrive() changes the speciﬁed tape drive conﬁguration parameters to the values requested.

dst_setdrive() is available to all users.

PARAMETERS

fd The ﬁle descriptor returned by the open call.

*drive Pointer to a structure of type

USAGE

dst_setdrive() uses the *drive structure for both input and output.

• On input, the valid bit mask indicates which members specify conﬁguration parameter

changes for the drive.

• On successful return, the valid bit mask identiﬁes the members for which changes

were made.

• If the valid bit mask is different on return, it indicates that dst_setdrive() could not

make all of the changes requested. To check the current conﬁguration parameter settings, use the dst_getdrive() function.

Before calling dst_setdrive(), initialize the appropriate *drive structure members with new values for the conﬁguration parameters you want to change, and set the accordingly.

dst_drive_st.

valid bit mask

typedef struct

{

u_int valid; /* Valid members - see defines above */ u_int config; /* Drive configuration attributes */

Ampex 1308911-02 5-47

Running Head

dst_setdrive libdd2 API Functions

u_char rdretryct; /* Read retry count (0-80) */ u_char wrretryct; /* Write retry count (0-127) */ u_char wrbuffull; /* Write buffer full ratio/256 (25-200) */ u_char rdbuffull; /* Read buffer full ratio/256 (25-200) */ int wrdelay; /* Write delay 100 millisecs (1-65535) */ u_char sctimeout; /* Scanner timeout in minutes (0-30) */ u_char thtimeout; /* Thread timeout in seconds (6-30) */ int ewoffset; /* EW offset before EMW, in PBs (0-) */ int cleantime; /* Cleaning time in seconds (1-) */ dst_ddver_st ddver; /* DST Driver version info (read only) */ dst_tdver_st tdver; /* Tape drive version info (read only) */ u_int capability; /* Drive capabilities (read only) */ int bufsize; /* Drive buffer size in bytes (read only) */

} dst_drive_st;

Model No.

STRUCTURE MEMBERS

The members of the dst_drive_st structure are deﬁned below. This structure type is used by both dst_getdrive() and dst_setdrive(). The read only members

are valid only for dst_getdrive().

valid On input, indicates which members to modify. On return, indicates

which members contain valid information. The following deﬁnitions apply:

DST_CFG_VALID DST_DDVER_VALID DST_RDRTY_VALID DST_WRRTY_VALID DST_WRBUF_VALID DST_RDBUF_VALID DST_WRDLY_VALID DST_SCTO_VALID DST_THTO_VALID DST_EWOFF_VALID DST_CLTM_VALID DST_TDVER_VALID DST_CAP_VALID DST_CFG_VALID DST_BUFSZ_VALID

config

Bit mask of the desired drive conﬁguration. The following deﬁnitions apply (see the

DST_POST_ERR - post internal retry errors DST_SYNC_EW - synchronize buffer at early warning (EW) DST_EOR_BLOAD - search forward after load DST_PARK_ANY - park anywhere DST_CHECKSUM - enable data block checksums

dstio.h ﬁle for details):

5-48 Ampex 1308911-02

libdd2 API Functions dst_setdrive

T o determine the current conﬁguration, call the dst_getdrive() function. The default is Sync on Early Warning with checksums enabled.

rdretryct The Read Retry Count drive conﬁguration parameter speciﬁes the

maximum number of retries to read a physical block from tape. The default setting is 5. The range is 0-255.

wrretryct The Write Retry Count parameter speciﬁes the maximum number of

retries to write a physical block to tape. The default setting is 5. The range is 0-255.

wrbuffull The Write Buffer Full parameter speciﬁes ho w full the b uffer should be

before the drive starts writing data to tape. This setting is di vided by 256 to obtain percentage. The default is 0 which speciﬁes that the driv e wait until the buffer is half full before writing data to tape. The range is 0 or 1-255.

rdbuffull The Read Buffer Full parameter speciﬁes how empty the b uffer should

be before the drive retrieves additional data from tape. This setting is divided by 256 to obtain percentage. The default is 0 which speciﬁes that the drive wait until the b uffer is half empty before reading data from tape. The range is 0 or 1-255.

wrdelay The Write Delay Time parameter speciﬁes the maximum time that the

drive waits before it writes any buffered data to tape. The time is measured in 100 millisecond increments from the last buffered Write command that did not cause the buffer to exceed the Write Buffer Full Ratio. The default value of zero speciﬁes that there is no time-out and the data remains in the buffer until a subsequent command writes the data to tape. The range is 1-65535 (multiplied by 100 milliseconds

sctimeout The Scanner Timeout parameter speciﬁes (in minutes) how long the

tape drive idles before stopping scanner rotation after a thread timeout. The default is 5. The range is 0-30.

thtimeout The Thread T imeout parameter speciﬁes (in seconds) how long the tape

drive idles before doing a park and unthread operation. The park location is determined by the Park Anywhere conﬁguration parameter. The default is 15. The range is 6-30.

ewoffset The Early Warning (EW) parameter controls the position of early

warning relative to the physical End of Partition (EOP). It is measured in physical blocks (each physical block is approximately 1.2 megabytes). The default is 100. The range is 0-16777215.

cleantime The Cleaning Time parameter speciﬁes the duration of the cleaning

cycle when a head cleaning cartridge is inserted into the tape drive. The default is 5. The range is 1-65535.

Ampex 1308911-02 5-49

Running Head

dst_setdrive libdd2 API Functions

ddver Read only member; see dst_getdrive(). tdver Read only member; see dst_getdrive(). capability Read only member; see dst_getdrive(). bufsize Read only member; see dst_getdrive().

Model No.

RETURN V ALUES

The return value is DST_SUCCESS (0) or DST_FAILURE (-1). See the “DST API Overview”

on page 5-1 for information on

errno failure messages and associated DST result codes.

EXAMPLE

The following is an example of how to call the dst_setdrive() function:

/* ** set/unset drive configuration */

SEE ALSO

“DST API Overview” on page 5-1, dst_getdrive(), dd2_set_drive

d2_drive.valid = DST_CFG_VALID; if (unset_config) {

d2_drive.config &= ~DST_EOR_BLOAD;

printf("unset DST_EOR_BLOAD bit: 0x%x ...\n", d2_drive.config); } else {

d2_drive.config |= DST_EOR_BLOAD;

printf("set DST_EOR_BLOAD bit: 0x%x ...\n", d2_drive.config); }

if (dst_setdrive(fd, &d2_drive)) {

perror ("dst_setdrive() failed");

exit (1); }

5-50 Ampex 1308911-02

libdd2 API Functions dst_setparam

5.16 dst_setparam

NAME

dst_setparam() - change tape drive data block size and tape device driver debug level.

SYNOPSIS

#include <dd2.h>

int dst_setparam(int fd, dst_param_st *parms);

DESCRIPTION

dst_setparam() changes tape drive data block size and/or tape device driver debug level. To view the current settings, use the dst_getparam() function.

dst_setparam() is available to all users.

PARAMETERS

fd The ﬁle descriptor returned by the open call.

*parms Pointer to a structure of type

USAGE

dst_setparam() uses the *parms structure for both input and output.

• On input, the valid bit mask indicates which members specify parameter changes.

• On successful return, the valid bit mask identiﬁes the members for which changes

were made.

• If the valid bit mask is different on return, it indicates that dst_setparam() could not

make all of the changes requested. To check the current parameter settings, use the

dst_getparam() function.

Before calling dst_setparam(), initialize the appropriate *parms structure members with new values for the parameters you want to change, and set the

typedef struct dst_param {

u_int valid; /* Valid members */ int blksize; /* Current blocksize in bytes */ u_int dbglevel; /* Device driver debug message level */ u_int attributes; /* Bit mask of attributes */

} dst_param_st;

dst_param_st.

valid bit mask accordingly.

Ampex 1308911-02 5-51

Running Head

dst_setparam libdd2 API Functions

Model No.

STRUCTURE MEMBERS

The members of the dst_param_st structure are deﬁned below. This structure type is used by both dst_getparam() and dst_setparam(). The

attributes

member is valid only for dst_getparam().

valid Bit mask that indicates which members contain valid data on input and

return. The following deﬁnitions apply:

DST_BLK_VALID (blksize member valid) DST_DBG_VALID (dgblevel member valid)

blksize Data block size in bytes. Valid for write operations only (read operations

adjust to the existing block size). This value must be the same for all data blocks within a ﬁle section and can be 1 or any even number from 80 through 1199838. The block size does not include the two-byte checksum, if any . If checksums are disabled, the maximum block size is

1199840.

dbglevel Bit mask specifying the tape device driver debug level; each bit

corresponds to a speciﬁc tape device driv er internal module or function. The tape device driver sends debugging messages to the host system console and the system error log as speciﬁed by this value. Though primarily intended for tape device driver debugging, you can also use this capability to display tape drive controller commands, status, and results.

The following deﬁnitions apply:

DST_DBG_NONE - no debug messages DST_DBG_MODULE - Outputs statements associated with tape device

driver

loading and unloading.

DST_DBG_AUTOCONFIG - Outputs statements associated with device

driver conﬁguring (or attaching).

DST_DBG_UNIT_ATTN - Outputs messages as SCSI Unit Attention

conditions are processed.

DST_DBG_OPEN - Outputs statements associated with the open

system call.

DST_DBG_CLOSE - Outputs statements associated with the close

system call.

DST_DBG_RW - Outputs statements associated with read and write

system calls.

DST_DBG_IOCTL - Outputs statements associated with the ioctl

system call.

5-52 Ampex 1308911-02

libdd2 API Functions dst_setparam

DST_DBG_RETRY - Outputs statements associated with SCSI

command retry attempts.

DST_DBG_INTERRUPT - Outputs statements associated with the

handling of tape device driver interrupts.

DST_DBG_PARAMETERS - Each SCSI command descriptor block

(cdb) is displayed before being sent to the tape drive; this allows invalid settings to be checked.

DST_DBG_RESULTS - Outputs statements associated with the drive

receiving SCSI Request Sense data.

DST_DBG_STATUS - Outputs statements associated with the drive

performing SCSI Mode Select/sense commands, which set or get tape drive operational settings.

DST_DBG_COMMAND - Outputs statements associated with SCSI

commands which are initiated and processed within the device driver.

DST_DBG_ABSTRACT - Outputs statements associated with the use of

the DD-2 interface (

dstioctop ioctl).

attributes This member is not used by dst_setparam() since the tape device driv er

RETURN V ALUES

The return value is DST_SUCCESS (0) or DST_FAILURE (-1). See the “DST API Overview”

on page 5-1 for information on

SEE ALSO

DST_DBG_LOG_SENSE - Outputs statements associated with Log

Sense statistics gathering.

DST_DBG_TIMING - Outputs the results when various timing

functions are turned on.

DST_DBG_ERROR - Shows error condition. DST_DBG_ENTRY - Shows entry/exit of functions. DST_DBG_ARGS - Shows arguments. DST_DBG_WARNING - Shows warning messages.

interface parameter settings can only be changed by specifying a new device special ﬁle in the open call. To check current settings, use the dst_getparam() function.

errno failure messages and associated DST result codes.

“API Introduction” on page 5-1, dst_get_param(), dd2_setparam_drive

Ampex 1308911-02 5-53

Running Head

dst_setpos libdd2 API Functions

Model No.

5.17 dst_setpos

NAME

dst_setpos() - set tape drive position to the speciﬁed location.

SYNOPSIS

#include <dd2.h>

int dst_setpos(int fd, dst_position_st *pos);

DESCRIPTION

dst_setpos() positions the tape drive to the speciﬁed location. This is the data block address at which the next read or write operation occurs, and is often referred to as the current position. Initiating a write operation at any position other than end of data (EOD), inv alidates all data in the partition that was written previously to locations beyond the current position.

A position can be expressed in either portable token form or standard C structure form, as described in “DST API Overview” on page 5-1. You can also specify a partial position as described below.

dst_setpos() is available to all users.

PARAMETERS

fd The ﬁle descriptor returned by the open call.

*pos Pointer to a structure of type

USAGE

dst_setpos() uses the *pos structure for input only; see “DST API Ov ervie w” on page 5-1 for details. Before calling dst_setpos:

• Initialize the pos member with a position speciﬁcation that indicates the location you

want the drive to position to.

• Initialize the type member with the deﬁnition of the position structure.

typedef struct {

dst_pos_type_en type; /* Position type */ dst_position_un pos; /* Position */

} dst_position_st;

dst_position_st.

5-54 Ampex 1308911-02

libdd2 API Functions dst_setpos

dst_setpos() determines whether the tape drive is already positioned at the desired location prior to issuing any positioning commands. If the data buffer contains write data, dst_setpos() ﬂushes the buffer to tape before setting the new position. Therefore, dst_setpos() can fail if there is a problem ﬂushing the buffer.

When the position speciﬁcation is provided in structure form, you can specify a partial position by indicating that only certain members of the structure are valid. dst_setpos() applies defaults derived from the current position to any unspeciﬁed position elements.

• If only a ﬁle section number (fsn) is supplied in a DD-2 or DIS position structure, the

position is set to the beginning of the speciﬁed ﬁle in the current partition unless the

value is -1. An fsn v alue of -1 sets tape drive position to the end of data (EOD) location

in the current partition.

The

fsn member is not valid for a DST600 position structure. To set tape drive position

to EOD, specify -1 for the

cdbn member.

fsn

• If only a data block address (ldbn or timecode) is supplied in a DD-2 or DIS position

structure, tape drive position is set to the speciﬁed block in the current ﬁle unless the v alue

is -1. A data block address of -1 sets tape dri ve position to the end of the current ﬁle (EOF)

location.

RETURN V ALUES

The return value is DST_SUCCESS (0) or DST_FAILURE (-1). See “DST API Overvie w” on

page 5-1 for information on

1. If there is no tape cartridge in the drive, dst_setpos() returns -1 with

(5) and the DST result code set to DstCodeNoTapeInstalled.

2. If no tape is installed, dst_setpos() returns -1 with errno set to EIO (5) and the DST

result code set to

3. If the tape is installed but the Ready/Not Ready button on the front panel of the drive is

Not Ready , dst_setpos() returns -1 with set to

DstCodeNoEstablishedPos.

4. If the position speciﬁcation is provided in token form, the volume ID of the current tape

is compared to the value in the token. If the values differ, dst_setpos() returns -1 with

errno set to EINVAL (22) and the DST result code set to DstCodeInvalidArg. If

the values are the same, the position token is con verted into the rele vant position structure before being processed further.

5. If the desired tape position cannot be found (i.e., doesn’t exist on the current tape),

dst_setpos() returns -1 with

DstCodeSetPosError. If the tape is unformatted, hence the reason for an unestablished

position,

DstCodeUnknownFmt.

errno failure messages and associated DST result codes.

errno set to EIO

DstCodeNoTapeInstalled.

errno set to EIO (5) and the DST result code

errno set to EIO (5) and the DST result code set to

errno is set to EIO (5) and the DST result code is set to

Ampex 1308911-02 5-55

Running Head

dst_setpos libdd2 API Functions

6. If the user supplies a partition that doesn’t exist, dst_setpos() returns -1 with errno set

EINVAL (22).

Model No.

7. If the position type is

SEE ALSO

dst_api_intro(), dst_getpos(), dst_convpos(), dd2_setpos_tape

DstPosDIS and the tape is not formatted for instrumentation

purposes, dst_setpos() returns -1 with

errno set to EINVAL (22).

5-56 Ampex 1308911-02

libdd2 API Functions dst_space

5.18 dst_space

NAME

dst_space() - change current position by a speciﬁed number of blocks or ﬁles, or set current position to end of data (EOD).

SYNOPSIS

#include <dd2.h>

int dst_space(int fd, int type, int count);

DESCRIPTION

dst_space() performs relative rather than absolute positioning. The current position can be changed by:

• Spacing forward or backward by the speciﬁed number of ﬁlemarks. The destination

position will be at the beginning or end of a ﬁle, respectively; i.e., at the end of tape (EO T)

side of a ﬁlemark when spacing forward, or the beginning of tape (BOT) side of a

ﬁlemark when spacing backward.

• Spacing forward or backward by the speciﬁed number of user blocks within a ﬁle.

• Spacing forward to EOD in the current partition.

PARAMETERS

fd The ﬁle descriptor returned by the open call.

type Speciﬁes the type of relative positioning to perform. The following

count Speciﬁes the number or ﬁlemarks or data blocks to space over. Use a

deﬁnitions apply:

DST_SPACE_FILEMARKS DST_SPACE_BLOCKS DST_SPACE_TO_EOD

positive value to space forward or a negative value to space backward. The largest positive value is 1388607 (0x7fffff). The largest negative value allowed is –1388608 (0xffffff).

RETURN V ALUES

The return value is DST_SUCCESS (0) or DST_FAILURE (-1). See “DST API Overvie w” on

page 5-1 for information on

Ampex 1308911-02 5-57

errno failure messages and associated DST result codes.

Running Head

dst_space libdd2 API Functions

1. If no tape is installed, dst_space() returns -1 with errno set to EIO (5) and the DST

result code set to

2. If the tape is installed but the Ready/Not Ready button on the front panel is Not Ready,

dst_space() returns -1 with

DstCodeNoEstablishedPos.

3. If the desired tape position cannot be found (i.e., the count value was too large),

dst_space() returns -1 with

DstCodeSetPosError.

DstCodeNoTapeInstalled.

errno set to EIO (5) and the DST result code set to

Model No.

SEE ALSO

dst_api_intro(), dd2_space_tape, DST SCSI Tape Drive DD-2 Tape Format Guide

5-58 Ampex 1308911-02

libdd2 API Functions dst_status

5.19 dst_status

NAME

dst_status() - Get information on tape drive and tape cartridge.

SYNOPSIS

#include <dd2.h>

int dst_status(int fd, dst_status_st *stat);

DESCRIPTION

dst_status() returns current information on the tape drive and the tape cartridge. This includes:

• T ape Dri ve - block size, state, position, results of last I/O operation, and number of bytes

in data buffer.

• Tape Cartridge - format and remaining capacity of current partition.

PARAMETERS

fd The ﬁle descriptor returned by the open call.

*stat Pointer to a structure of type

USAGE

dst_status() uses the *stat structure for both input and output.

• On input, the valid bit mask speciﬁes which members to get information for.

• On successful return, the valid bit mask indicates which members are reporting current

status retrieved from the drive.

• If the valid bit mask is different on return, it indicates that dst_status() could not get

all of the status requested.

Before calling dst_status(), initialize the

dst_status_st.

valid bit mask appropriately.

Ampex 1308911-02 5-59

Running Head

dst_status libdd2 API Functions

typedef struct {

u_int valid; /* Valid members - see defines above */ int minblksz; /* Minimum block size */ int maxblksz; /* Maximum block size */ int drvblksz; /* Drive's current block size */ int wrblksz; /* New file block size (set on write)*/ dst_state_st state; /* Current state - see defines above */ dst_result_st results; /* Results from the last I/O op */ dst_format_st format; /* Tape format information */ dst_position_st lpos; /* Current logical position */ dst_position_st obsolete1; /* Used to be ppos */ int bufdata; /* no. of bytes in buffer */ int rpcap; /* Remaining partition capacity past current *

position in phys blks */

int fileblksz; /* Used to be rtcap, obsolete3 */

} dst_status_st;

typedef struct {

u_int valid; /* Valid members */ (see Table C-5) dst_rcode_en rcode; /* Primary result code */ (see Table C-3) dst_rclasss_en rclass /* Result class of rcode */ (see Table C-6) dst_msicode_en msicode; /* MSI result code */ (see Table C-1) dst_msrcode_en msrcode; /* MSR result code*/ (see Table C-2) dst_msrstat_st msrstat; /* MSR machine status */ (see below) dst_severity_en severity; /* Level of error severity */ (see Table C-6)

} dst_result_st;

Model No.

typedef struct {

u_char statbyte[2];

} dst_msrstat_st;

msrstat.statbyte[0] corresponds to Byte 23 in Table C-4 msrstat.statbyte[1] corresponds to Byte 24 in Table C-4

STRUCTURE MEMBERS

valid On input, indicates which structure members to get information for. On

return indicates which members contain current information retrieved from the drive. The following deﬁnitions apply:

DST_MINBLK_VALID DST_MAXBLK_VALID DST_DRVBLK_VALID DST_STATE_VALID DST_RESULT_VALID DST_FMT_VALID DST_LPOS_VALID

5-60 Ampex 1308911-02

Ampex Data Systems DST, DIS User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

Addendum

Introduction

API Functions

Device Special Files

dst_setnoflush()

dst_getptpathname()

dd2_setnoflush_drive

Contents

Figures

Tables

General Information Introduction

1.1 Introduction

1.2 Manual Contents

1.3 Notational Conventions

1.4 Notices and Notes

1.5 Related Documents

1.6 Technical Support

1.7 Documentation Support

Software Overview Introduction

2.1 Introduction

2.2 Tape Device Driver

2.3 Tape Drive Behavior

2.4 libdd2 API Overview

2.4.1 Operation of libdd2

2.4.2 Function Return Values

2.4.3 Errors

2.4.4 UNIX Platform Compatibility

2.4.5 Restrictions

2.5 DD2 Utilities Overview

2.5.1 Exit Status

2.5.2 Errors

2.5.3 UNIX Platform Compatibility

2.5.4 Open behavior

2.5.5 Restrictions

DD-2 Tape Format Introduction

3.1 Introduction

3.2 DST Cartridge

3.3 DD-2 Tape Entities

3.4 DD-2 Format Types

3.4.1 System Zones

3.4.2 Partitions

3.4.3 File Sections

3.4.4 Data Blocks

3.5 Instrumentation and Data Storage Recording

Tape Drive Operational Characteristics IntroductionIntroduction

4.1 Introduction

4.2 Tape Drive Block Size

4.3 Tape Partitions

libdd2 API Functions Introduction

5.1 Introduction

5.2 DST API Overview

5.2.1 libdd2 Functions Summary

5.2.2 Position Specifications

dst_position_st

dst_pos_type_en

dst_position_un

dst_pos_tok_t

dst_dd2_pos_st

dst_600_pos_st Structure

dst_dis_pos_st Structure

5.2.3 Return Values

5.2.4 See Also

5.3 dst_clrlog

5.4 dst_convpos

5.5 dst_format

5.6 dst_getdrive

5.7 dst_getdrive_ex

5.8 dst_getlog

5.9 dst_getparam

5.10 dst_getpos

5.11 dst_getstate

5.12 dst_gettrace

5.13 dst_reset

5.14 dst_rewind

5.15 dst_setdrive

5.16 dst_setparam