Page 1
DST/DIS
Automated Cartridge Library
UNIX Application
Programmer’s Guide
1308904-X4
®
™
Page 2
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
UNIX is registered trademark licensed exclusively by X/Open Co., Ltd.
DIS is a trademark of Ampex Corporation.
DST is a registered trademark of Ampex Corporation.
COPYRIGHT INFORMATION
U.S. GOVERNMENT RESTRICTED RIGHTS: Software and any documentation are provided with
RESTRICTED RIGHTS. Use, duplication, or disclosure by the Government is subject to restrictions as
set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at
DFARS 252.227-7013 and Rights in Data-General, including Alternate III, at FAR 52.227-14, as
applicable.
Prepared by Technical Publications
Ampex Corporation
401 Broadway
Redwood City, CA 94063-3199
Copyright © 1996 by Ampex Corporation
All rights reserved
Part No. 1308904-X4
Issued: September 1997
Page 3
ACL Application Programmer’s Guide Contents
Contents
Section 1 General Information
1.1 Introduction ....................................................................................................1-1
1.2 Supported UNIX Operating Systems .............................................................1-1
1.3 Manual Contents ............................................................................................1-2
1.4 Notational Conventions ..................................................................................1-2
1.5 Notices and Notes ...........................................................................................1-3
1.6 Related Documents ........................................................................................1-4
1.7 Training Services ............................................................................................1-5
1.8 Technical Support ..........................................................................................1-5
1.9 Documentation Support ..................................................................................1-5
Section 2 ACL Software Overview
2.1 Introduction ....................................................................................................2-1
2.2 The Ampex Automated Cartridge Library Device Driver .............................2-1
2.3 Native Device Drivers ....................................................................................2-1
2.4 libacl API Overview .......................................................................................2-3
2.4.1 Operation of libacl......................................................................................2-3
2.4.2 Function Return Values..............................................................................2-4
2.4.3 Errors..........................................................................................................2-4
2.4.4 Platform and Drive Compatibility..............................................................2-4
2.4.5 ACL Driver Version Compatibility............................................................2-4
2.4.6 Open behavior.............................................................................................2-4
2.4.7 Restrictions.................................................................................................2-5
2.5 ACL Utilities Overview .................................................................................2-5
2.5.1 Exit Status...................................................................................................2-5
2.5.2 Platform and Drive Compatibility..............................................................2-5
2.5.3 ACL Driver Version Compatibility............................................................2-5
2.5.4 Open behavior.............................................................................................2-5
2.5.5 Restrictions.................................................................................................2-6
Ampex 1308904-X4 Preliminary Draft iii
Page 4
Running Head
Contents ACL Application Programmer’s Guide
Model No.
Section 3 ACL Operational Characteristics
3.1 Introduction ....................................................................................................3-1
3.2 SCSI Commands ............................................................................................ 3-1
3.3 ACL Configuration ........................................................................................3-2
3.3.1 Addressable Elements................................................................................ 3-2
Element SCSI Addresses.......................................................................3-2
Element Location Names....................................................................... 3-3
3.3.2 Barcode Reader.......................................................................................... 3-6
3.3.3 SCSI Target Configuration ........................................................................ 3-6
3.3.4 Product Information................................................................................... 3-7
3.3.5 Multiple Port and Multiple Initiator Considerations.................................. 3-7
3.3.6 Configuration Parameters .......................................................................... 3-7
3.3.7 Power Up and Hard Reset..........................................................................3-8
3.4 Tape Cartridge Loading and Unloading ........................................................3-9
3.4.1 Series 2XX and 4XX .................................................................................3-9
3.4.2 Series 8XX................................................................................................. 3-9
Loading a Tape Cartridge......................................................................3-9
Unloading a Tape Cartridge...................................................................3-9
3.5 Tape Cartridge Movement ...........................................................................3-10
3.6 CHS Positioning .......................................................................................... 3-10
3.7 Operational Status ........................................................................................ 3-10
3.7.1 Unit Ready Status ....................................................................................3-10
3.7.2 Initialize Element Status .......................................................................... 3-10
3.7.3 Read Element Status ................................................................................ 3-11
3.7.4 Internal Logs............................................................................................3-13
3.7.5 Sense Data................................................................................................ 3-13
Section 4 libacl API Functions
4.1 Introduction ....................................................................................................4-1
4.2 libacl_intro_api .............................................................................................. 4-2
4.3 aclGeneric ...................................................................................................... 4-7
4.4 aclAuditLibrary ..............................................................................................4-9
4.5 aclAuditElement .......................................................................................... 4-12
4.6 aclGetElemData ...........................................................................................4-15
4.7 aclGetErrorLog ............................................................................................ 4-17
4.8 aclGetParam .................................................................................................4-18
4.9 aclGetStaticLog ........................................................................................... 4-21
4.10 aclGetVersion .............................................................................................. 4-22
4.11 aclInit ........................................................................................................... 4-24
4.12 aclMoveCartridge ........................................................................................ 4-25
4.13 aclMoveVolume .......................................................................................... 4-27
4.14 aclPark ......................................................................................................... 4-29
4.15 aclPosition ....................................................................................................4-31
4.16 aclRelease .................................................................................................... 4-33
4.17 aclReserve ....................................................................................................4-35
4.18 aclReqSense .................................................................................................4-36
iv Preliminary Draft Ampex 1308904-X4
Page 5
ACL Application Programmer’s Guide Contents
4.19 aclRezero ......................................................................................................4-38
4.20 aclSetParam ..................................................................................................4-39
4.21 aclStatus .......................................................................................................4-42
4.22 aclTUR .........................................................................................................4-43
Section 5 ACL Utilities
5.1 Introduction ....................................................................................................5-1
5.2 acl_intro ..........................................................................................................5-2
5.3 acl_audit_library .............................................................................................5-8
5.4 acl_audit_element .........................................................................................5-11
5.5 acl_errlog_library .........................................................................................5-14
5.6 acl_getparam_library ....................................................................................5-17
5.7 acl_init_chs ...................................................................................................5-21
5.8 acl_move_tape ..............................................................................................5-23
5.9 acl_move_volume ........................................................................................5-26
5.10 acl_park_chs .................................................................................................5-27
5.11 acl_query_library .........................................................................................5-29
5.12 acl_setparam_library ....................................................................................5-32
5.13 acl_statlog_library ........................................................................................5-36
5.14 acl_status_library .........................................................................................5-38
Appendix A Returned Sense Data
A.1 Error/Event Parameter Identification Codes .................................................A-1
A.2 Sense Key Codes ...........................................................................................A-4
A.3 Additional Sense Codes and Qualifiers .........................................................A-5
A.4 Vendor-Specific ACL Condition Codes .......................................................A-6
A.5 CHS Failure, Error, and Warning Codes .....................................................A-13
Ampex 1308904-X4 Preliminary Draft v
Page 6
Running Head
Tables ACL Application Programmer’s Guide
Model No.
Tables
2-1 ACL Operations ................................................................................................................2-1
3-1 SCSI Address Assignments for 8XX ACL Storage and IMEX Elements ......................... 3-4
3-2 ACL Behavior Parameter Descriptions.............................................................................. 3-8
A-1 Error/Event Parameter Identification Code Descriptions.................................................. A-1
A-2 Sense Key Code Descriptions ........................................................................................... A-4
A-3 ASC/ASCQ Conditions..................................................................................................... A-5
A-4 Vendor-Specific ACL Condition Codes............................................................................ A-6
A-5 CHS Failure, Error, and Warning Codes......................................................................... A-13
vi Preliminary Draft Ampex 1308904-X4
Page 7
ACL Application Programmer’s Guide General Information
Section 1
General Information
1.1 Introduction
This manual describes how to use the Ampex DST/DIS Automated Cartridge Library (ACL)
software installed on your UNIX host system. The ACL software includes Management
Utilities and a
The A CL Management Utilities are a set of programs that pro vide command-line access to an
Ampex DST or DIS ACL. They are compatible with the DST/DIS Tape Management (DD-2)
Utilities. Both sets of 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 link together.
libacl Application Programming Interface (API).
libacl API is a set of C Library functions that simplify communication, control, and
The
integration of Ampex ACLs. The API presents a consistent, platform-independent abstract
layer that provides access to the ACL device driver and also to native SCSI passthru device
driver interfaces
Information in this manual that is unique to particular models of the A CL is identified by series
number (see listing below); all other information is common to all models of the ACL.
The following ACL models are covered by this manual:
•
Ampex DIS 220i and DIS 260i (series 2XX)
•
Ampex DST 410 (series 4XX)
•
Ampex DST 810 (series 8XX)
1.2 Supported UNIX Operating Systems
The ACL device driver is supported on the following UNIX operating systems:
•
Digital Equipment Corporation Digital UNIX (formerly DEC OS/F 1)
•
Hewlett Packard HP-UX
•
IBM AIX
•
Silicon Graphics IRIX
•
Sun Microsystems Solaris
Ampex 1308904-X4 Preliminary Draft 1-1
Page 8
Running Head
Manual Contents ACL Application Programmer’s Guide
Each platform-specific software installation guide referenced in “Related Documents” on
page 1-4 provides a complete list of supported hosts and operating system versions for that
platform. You can also contact Ampex Technical Support for information on supported
systems (see page 1-5).
Model No.
1.3 Manual Contents
•
Section 1, “General Information,” describes document conventions used in this manual,
its intended audience, and related documents.
•
Section 2, “ACL Software Overview,” provides a general overview of the host system
device driver interface, the
•
Section 3, “ACL Operational Characteristics,” describes ACL capabilities and behavior.
•
Section 4, “libacl API Functions” contains the libacl API manual pages.
•
Section 5, “ACL Utilities“ contains the ACL utilities manual pages.
•
Appendix A, “Returned Sense Data,” describes the sense data and condition codes the
ACL uses to report events, conditions, and operational status.
libacl API functions, and the ACL utilities.
1.4 Notational Conventions
This manual uses the following typographical conventions:
Bold
Italic
[ ] In a command syntax description, surrounds optional elements. Do not
| In a command syntax description, separates alternate items. Only one of
{ } In a command syntax description, groups alternate items. Do not type
In a syntax description, indicates text that must be typed literally. In
other contexts, indicates UNIX command and utility names, program
and application names, and C function names.
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
type the brackets themselves.
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.
the braces themselves.
emphasize terms.
... In a command syntax description, indicates an element that may be
repeated. Do not type the dots themselves.
1-2 Preliminary Draft Ampex 1308904-X4
Page 9
≈
ACL Application Programmer’s Guide Notices and Notes
Fixed
Fixed Bold
Note:
Initial Capitalization Indicates command fields or special terms or names.
/ When used with
In C function prototypes and examples, the special characters above ([ ] | { }) r etain
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.
In an example, indicates computer output or contents of files or
directories. In other contexts, indicates C type names, C symbolic
constants, C structure or member names, file names, and path names.
In an example, indicates text typed by the operator.
function/operation pair. For example,
refers to the
function. In other contexts, the slash retains its normal meaning.
Indicates approximate values.
1.5 Notices and Notes
ioctl symbolic constants, the slash indicates a control
DSTIOCTOP/DST_SETPOS
DST_SETPOS
operation of the ioctl
DSTIOCTOP
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.
Ampex 1308904-X4 Preliminary Draft 1-3
Page 10
,
Running Head
Related Documents ACL Application Programmer’s Guide
Model No.
1.6 Related Documents
DST/DIS SCSI Tape Drive DD-2 Tape Format Guide , Part No. 1306706, describes physical
and logical DD-2 tape structures and provides common tape format examples.
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 Operating Systems , Part 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.
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
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
Part No.
1-4 Preliminary Draft Ampex 1308904-X4
Page 11
ACL Application Programmer’s Guide Training Services
1.7 Training Services
Ampex offers technical training on this and other data storage products on a scheduled basis.
For information regarding training, call 800-227-8402.
1.8 Technical Support
If you require information or technical assistance, contact the Ampex Customer Service
Department:
Ampex Corporation Customer Service
600 W ooten Road
Colorado Springs, CO 80915-3597
Telephone: 800-DST-SRVC (800-378-7782)
Fax: 719-570-3289
International T elephone: 719-570-3378
E-mail address: [email protected]
Website: http://www.ampex.com
1.9 Documentation Support
Your feedback is important to us. If you find any errors in this manual or ha v e an y comments
or suggestions, please send E-mail to our technical publications department at:
We are always trying to improve our documentation and appreciate your input.
Ampex 1308904-X4 Preliminary Draft 1-5
Page 12
Running Head
Documentation Support ACL Application Programmer’s Guide
Model No.
1-6 Preliminary Draft Ampex 1308904-X4
Page 13
ACL Application Programmer’s Guide ACL Software Overview
Section 2
ACL Software Overview
2.1 Introduction
This section provides a general overvie w of the host system de vice driv er interface, the libacl
API functions, and the ACL Management Utilities. Table 2-1 shows the ACL operations
performed by the
2.2 The Ampex Automated Cartridge Library Device Driver
libacl functions and the Management Utilities.
The ACL device driver is a standard UNIX device driver which implements a pass-through
access via the DSTIOCPASSTHRU
through which programs can operate an ACL.
2.3 Native Device Drivers
Some platforms supported by the DST/DIS host system software have their own SCSI
passthru driver interfaces. The
available. See the
more information.
Operation libacl API Function ACL Utility Usage
Get status of specified
element.
Get status of all
elements.
DST/DIS Software Installation Guide for your host operating system for
Table 2-1. ACL Operations
aclAuditElement() acl_audit_element
aclAuditLibrary() acl_audit_library
ioctl. The ACL device driver provides an interface
libacl API provides access to these driver interfaces when
See “Read Element Status” on
page 3-11.
See “Read Element Status” on
page 3-11.
Issue SCSI command. aclGeneric()
Get element count and
addresses.
Retrieve the error or
event log.
Ampex 1308904-X4 Preliminary Draft 2-1
aclGetElemData() N/A See “Element SCSI Addresses”
aclGetErrorLog() acl_errlog_library See “Internal Logs” on page
N/A See “SCSI Commands” on page
3-1.
on page 3-2.
3-13.
Page 14
Running Head
Native Device Drivers ACL Application Programmer’s Guide
Model No.
Table 2-1. ACL Operations
Operation libacl API Function ACL Utility Usage
Get configuration
parameter settings.
Retrieve the static Log aclGetStaticLog() acl_statlog_library See “Internal Logs” on page
Get product and
version information.
Update element status
in the internal database
Move a tape cartridge
from one location to
another.
Move the specified
tape cartridge to
another location.
Park the cartridge
handler (2XX, 4XX)
Set position of
cartridge handler.
Release ACL
previously reserved
for exclusive use by
specified initiator.
aclGetParam() acl_getparam_library See “Configuration Parameters”
on page 3-7.
3-13.
aclGetVersion() acl_query_library See “Product Information” on
page 3-7.
aclInit() acl_init_chs See “Initialize Element Status”
on page 3-10.
aclMoveCartridge() acl_move_tape See “Tape Cartridge Movement”
on page 3-10.
aclMoveVolume() acl_move_volume See “Tape Cartridge Movement”
on page 3-10.
aclPark() acl_park_chs See “Tape Cartridge Loading and
Unloading” on page 3-9.
aclPosition() N/A See “CHS Positioning” on page
3-10.
aclRelease() N/A See “Multiple Port and Multiple
Initiator Considerations” on page
3-7.
Retrieve status and
SCSI sense data.
Reserve ACL for
exclusive use by
specified initiator.
Reset the ACL and
ensure internal
database status is
current
Change configuration
parameter settings.
? aclStatus() ? See ?
Check that ACL is
ready to accept
commands.
2-2 Preliminary Draft Ampex 1308904-X4
aclReqSense() acl_status_library See “Sense Data” on page 3-13.
aclReserve() N/A See “Multiple Port and Multiple
Initiator Considerations” on page
3-7.
aclRezero() N/A See “Initialize Element Status”
on page 3-10.
aclSetParam() acl_setparam_library See “Configuration Parameters”
on page 3-7.
aclTUR() N/A See “Unit Ready Status” on page
3-10.
Page 15
ACL Application Programmer’s Guide libacl API Overview
2.4 libacl API Overview
The libacl API retains complete compatibility with previous versions of the DST/DIS
Automated Cartridge Library API (libami) while allowing for further growth and easier
support. In addition, programmers writing to the libacl API are no longer required to manage
libami.cf configuration file.
the
The libacl API features include:
• Simple, compact, and direct functions to control or obtain data from an ACL. Detailed
knowledge of the hardware and SCSI interface are not necessary.
• A generic interface for situations where a developer may want to issue a SCSI command
not available in the libacl C-Library functions.
• Access to the lower lev el libami API when a dev eloper needs more control ov er the A CL.
Note: Detailed knowledge of the ACL SCSI interface is necessary in order to program the
lower level libami API.
• Complete compatibility with previous versions of the libami.
2.4.1 Operation of libacl
The libacl API layer packages SCSI A CL commands as C functions, isolating the caller from
the device driver ioctl layer. C programs that use the libacl API normally use the C
preprocessor
acl.h Contains the libacl function prototypes and provides sev eral useful definitions.
libami.h Contains the libami function prototypes and several useful definitions. Although
WriterNote: I could not find any instance of a system header file #include in any libacl API
In addition to the
inclusion of standard system header files. Any such files are shown in the syntax section for
the function.
The header files are normally installed in the
referenced in a C program using C preprocessor directives such as the following:
#include directive to include one or more of the following header files.
acl.h header file must be included by application using the libacl API.
The
libami is a part of the libacl API, it is a self contained library interface. The
libami.h header file must be included by applications using the libacl API.
libami.h is provided for backwards compatibility with software that was
written directly to the libami interface.
manual page.
acl.h and libami.h header files, some of the libacl functions require
/usr/include/sys directory, so they can be
#include <sys/acl.h>
Ampex 1308904-X4 Preliminary Draft 2-3
Page 16
Running Head
libacl API Overview ACL Application Programmer’s Guide
Model No.
2.4.2 Function Return Values
Each libacl function returns an integer value. The meaning of any non-negative return value
is specific to the call. A return value of -1 indicates that the libacl function encountered an
error during processing and that the A CL de vice driv er has set the external variable
indicate the type of error that occurred. In other words, a call returns -1 on failure.
errno to
For convenience, the
indicate a success return value (0) and the symbolic constant
failure return value (-1).
acl.h header file defines the symbolic constant DST_SUCCESS to
2.4.3 Errors
The ACL device driver uses the external variable errno to provide information about the
most recent system call error. Because the system does not reset the
successful system calls, your program should test
<sys/errno.h> file describes the symbolic names and values possible for errno. The
The
limited number of error definitions in the
ACL drive errors onto single values. Because of this overloading, the
provides additional error information beyond that provided by the return value.
2.4.4 Platform and Drive Compatibility
All the libacl API functions operate consistently across supported platforms. See the on line
release notes installed with the libacl API for more information.
DST_FAILURE to indicate a
errno variable on
errno only if the call fails (returns -1).
<sys/errno.h> file requires mapping of multiple
aclStatus() function
2.4.5 ACL Driver Version Compatibility
See the on line release notes installed with the libacl API to find out which v ersion of the A CL
device driver it is compatible with.
2.4.6 Open behavior
The libacl API handles the opening and closing of the A CL. If an error occurs during an open,
the external system variable
EBUSY ACL is already in use.
EINVAL Invalid argument supplied.
ENODEV The ACL device is not properly connected to the host system.
ENXIO Device does not exist.
EPERM Access denied due to device special file permissions.
ETIME A timeout occurred on a SCSI command.
2-4 Preliminary Draft Ampex 1308904-X4
errno should be set to one of the following:
Page 17
ACL Application Programmer’s Guide ACL Utilities Overview
2.4.7 Restrictions
None; the libacl API functions are available to all users
2.5 ACL Utilities Overview
The ACL utilities provide command-line access to an Ampex DST or DIS ACL. They are
compatible with the DST/DIS Tape Management (DD-2) 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 link together.
2.5.1 Exit Status
The ACL utilities use the following exit status codes, and may also produce output to -stdout
on success:
0 Operation successful.
nonzero Operation failed.
A nonzero return value describes the error encountered error during processing. An error
message is written to stderr along with the return value.
The limited number of error definitions in the
multiple ACL errors onto single values. Because of this overloading, the
utility provides additional error information beyond that provided by the return value.
2.5.2 Platform and Drive Compatibility
All of the A CL utilities operate consistently across supported platforms. See the on line release
notes installed with the ACL software for more information.
2.5.3 ACL Driver Version Compatibility
See the on line release notes installed with the ACL software to find out which version of the
ACL device driver the utilities are compatible with.
2.5.4 Open behavior
<sys/errno.h> file requires mapping of
acl_status_library
Each ACL utility handles the opening and closing of the ACL. If an error occurs during an
open, one of the following messages should be written to stderr:
Ampex 1308904-X4 Preliminary Draft 2-5
Page 18
Running Head
ACL Utilities Overview ACL Application Programmer’s Guide
EBUSY ACL is already in use.
EINVAL Invalid argument supplied.
ENODEV The ACL device is not properly connected to the host system.
ENXIO Device does not exist.
EPERM Access denied due to device special file permissions.
ETIME A timeout occurred on a SCSI command.
Model No.
2.5.5 Restrictions
None; the ACL utilities are available to all users.
2-6 Preliminary Draft Ampex 1308904-X4
Page 19
ACL Application Programmer’s Guide ACL Operational Characteristics
Section 3
ACL Operational Characteristics
3.1 Introduction
This section describes ACL capabilities and behavior. You should be familiar with the
information in this section before using the ACL utilities or libacl API functions.
3.2 SCSI Commands
The ACL is a SCSI device that conforms to the American National Standard for Information
Systems – Small Computer System Interface-2, X3.131-1994, 31 January 1994. The libacl API
and A CL utilities simplify application program de velopment by presenting abstract interf aces
that eliminate the need for in-depth understanding of the device driv er or the underlying SCSI
interface. If desired, howev er, you can use the aclGeneric() function to issue a SCSI command
to a supported SCSI target (which can be an Ampex or non-Ampex SCSI device).
The SCSI commands that the ACL supports fall into four categories as listed below. For
detailed information on using the commands see the DST/DIS ACL SCSI Interface Control
Document (ICD).
• ANSI Device Generic commands:
Inquiry Mode Select (6) Mode Sense (10)
Log Select Mode Select (10) Request Sense
Log Sense Mode Sense (6) Test Unit Ready
• ANSI Direct Access commands:
Release Reserve Rezero Unit
• ANSI Device Specific commands:
Initialize Element Status Position to Element
Move Medium Read Element Status
• Vendor Specific commands:
Move Volume Initialize Element Range
Ampex 1308904-X4 Preliminary Draft 3-1
Page 20
Running Head
ACL Configuration ACL Application Programmer’s Guide
Model No.
3.3 ACL Configuration
The following paragraphs describe the ACL configuration.
3.3.1 Addressable Elements
Each ACL element that can contain a tape cartridge is assigned both a SCSI address and a
location name. The libacl API functions use the SCSI address to refer to an element. The A CL
utilities use the location name.
2XX and 4XX ACLs can move a tape cartridge from a storage bin to the tape drive, or from
the tape drive to a storage bin. 8XX ACLs can move a tape cartridge to or from any element.
Element SCSI Addresses
libacl functions recognize the SCSI element addresses listed below. You can use the
aclGetElemData() function to retrieve complete element counts and SCSI starting addresses
from the ACL.
Series 2XX and 4XX
Data Transfer
Element
Transport
Element
Storage
Element
Series 8XX
Data Transfer
Element
Transport
Element
The ACL tape drive. Its SCSI address is 100d (64h).
The ACL cartridge handling system (CHS) which consists of the
mechanical and electrical assemblies necessary to transfer tape cartridges
between the storage bins and the tape drive. Its SCSI address is 01.
One of the seven storage bins in the CHS. The bins are assigned SCSI
addresses 1000d / 3E8h (bottom bin) through 1006d / 3EEh ( top bin).
The ACL tape drive(s). Up to four tape drives can be installed in the ACL.
The drives are assigned SCSI addresses 100d / 64h (bottom dri ve) through
103d / 67h (top drive).
The ACL cartridge handling system (CHS) which consists of the
mechanical and electrical assemblies necessary to transfer tape cartridges
between the storage bins, import/export bins, and tape drive(s). Its SCSI
address is 01.
3-2 Preliminary Draft Ampex 1308904-X4
Page 21
ACL Application Programmer’s Guide ACL Configuration
Storage
Element
Import/Export
Element
One of the 248 storage bins in the CHS. The bins are assigned SCSI
addresses 1000d – 1247d (3E8h – 4DFh). Table 3-1 shows the layout of
the storage bins.
One of the eight import/export (IMEX) bins in the CHS. The bins are
assigned SCSI addresses 10d – 17d (0Ah –12h). Table 3-1 shows the
layout of the IMEX bins.
Element Location Names
ACL utilities recognize the element location names listed below.
ACL Series 2XX and 4XX
Tape Drive The ACL has one tape drive named DR1.
Cartridge Handling
System
Storage Element The ACL contains seven storage bins named A01 through A07 (from
The ACL cartridge handling system is named CHS.
top to bottom).
ACL Series 8XX
Tape Drive(s) The ACL can contain up to four tape drives. The drives are named
DR4 through DR1 (from top to bottom)
Cartridge Handling
System
Storage BIns The ACL contains 248 storage bins. The bins are arranged in an
IMEX bins The eight IMEX bins provide operator access for insertion and
The ACL cartridge handling system is named CHS
8-column by 32-row matrix (which also contains eight import/export
bins). The rows are numbered 01 through 32 from top to bottom and
the columns are alphabetized A through H from left to right. The
storage bin names correspond to the locations they occupy:
A01-A32, B01-B32, C01-C32, D01-D32, E01-E32, F01-F32,
G01-G32, H01-H06, and H15-H32.
removal of tape cartridges. The y are named H07-H14, corresponding
to the locations they occupy.
Ampex 1308904-X4 Preliminary Draft 3-3
Page 22
Running Head
ACL Configuration ACL Application Programmer’s Guide
Model No.
Table 3-1. SCSI Address Assignments for 8XX ACL Storage and IMEX Elements
Row A Row B Row C Row D Row E Row F Row G Row H
Bin #
Decimal Address
01 1031d( 1063d 1095d 1127d 1159d 1191d 1223d 1247d
02 1030d 1062d 1094d 1126d 1158d 1190d 1222d 1246d
03 1029d 1061d 1093d 1125d 1157d 1189d 1221d 1245d
04 1028d 1060d 1092d 1124d 1156d 1188d 1220d 1244d
05 1027d 1059d 1091d 1123d 1155d 1187d 1219d 1243d
06 1026d 1058d 1090d 1122d 1154d 1186d 1218d 1242d
07 1025d 1057d 1089d 1121d 1153d 1185d 1217d
08 1024d 1056d 1088d 1120d 1152d 1184d 1216d 16d
09 1023d 1055d 1087d 1119d 1151d 1183d 1215d 15d
10 1022d 1054d 1086d 1118d 1150d 1182d 1214d 14d
11 1021d 1053d 1085d 1117d 1149d 1181d 1213d 13d
12 1020d 1052d 1084d 1116d 1148d 1180d 1212d 12d
13 1019d 1051d 1083d 1115d 1147d 1179d 1211d 11d
14 1018d 1050d 1082d 1114d 1146d 1178d 1210d 10d
15 1017d 1049d 1081d 1113d 1145d 1177d 1209d 1241
16 1016d 1048d 1080d 1112d 1144d 1176d 1208d 1240
17 1015d 1047d 1079d 1111d 1143d 1175d 1207d 1239d
18 1014d 1046d 1078d 1110d 1142d 1174d 1206d 1238d
19 1013d 1045d 1077d 1109d 1141d 1173d 1205d 1237d
20 1012d 1044d 1076d 1108d 1140d 1172d 1204d 1236d
21 1011d 1043d 1075d 1107d 1139d 1171d 1203d 1235d
22 1010d 1042d 1074d 1106d 1138d 1170d 1202d 1234d
23 1009d 1041d 1073d 1105d 1137d 1169d 1201d 1233d
24 1008d 1040d 1072d 1104d 1136d 1168d 1200d 1232d
25 1007d 1039d 1071d 1103d 1135d 1167d 1199d 1231d
26 1006d 1038d 1070d 1102d 1134d 1166d 1198d 1230d
27 1005d 1037d 1069d 1101d 1133d 1165d 1197d 1229d
28 1004d 1036d 1068d 1100d 1132d 1164d 1196d 1228d
29 1003d 1035d 1067d 1099d 1131d 1163d 1195d 1227d
30 1002d 1034d 1066d 1098d 1130d 1162d 1194d 1226d
31 1001d 1033d 1065d 1097d 1129d 1161d 1193d 1225d
32 1000d 1032d 1064d 1096d 1128d 1160d 1192d 1224d
* IMEX bin
17d*
*
*
*
*
*
*
*
3-4 Preliminary Draft Ampex 1308904-X4
Page 23
ACL Application Programmer’s Guide ACL Configuration
Table 3-1. SCSI Address Assignments for 8XX ACL Storage and IMEX Elements (Continued)
Row A Row B Row C Row D Row E Row F Row G Row H
Bin #
Hexadecimal Address
01 407h 427h 447h 467h 487h 4A7h 4C7h 4DFh
02 406h 426h 446h 466h 486h 4A6h 4C6h 4DEh
03 405h 425h 445h 465h 485h 4A5h 4C5h 4DDh
04 404h 424h 444h 464h 484h 4A4h 4C4h 4DCh
05 403h 423h 443h 463h 483h 4A3h 4C3h 4DBh
06 402h 422h 442h 462h 482h 4A2h 4C2h 4DAh
07 401h 421h 441h 461h 481h 4A1h 4C1h 011h*
08 400h 420h 440h 460h 480h 4A0h 4C0h
09 3FFh 41Fh 43Fh 45Fh 47Fh 49Fh 4BFh 00Fh*
10 3FEh 41Eh 43Eh 45Eh 47Eh 49Eh 4BEh 00Eh*
11 3FDh 41Dh 43Dh 45Dh 47Dh 49Dh 4BDh 00Dh*
12 3FCh 41Ch 43Ch 45Ch 47Ch 49Ch 4BCh 00Ch*
13 3FBh 41Bh 43Bh 45Bh 47Bh 49Bh 4BBh 00Bh*
14 3FAh 41Ah 43Ah 45Ah 47Ah 49Ah 4BAh 00Ah*
15 3F9h 419h 439h 459h 479h 499h 4B9h 4D9h
16 3F8h 418h 438h 458h 478h 498h 4B8h 4D8h
17 3F7h 417h 437h 457h 477h 497h 4B7h 4D7h
18 3F6h 416h 436h 456h 476h 496h 4B6h 4D6h
19 3F5h 415h 435h 455h 475h 495h 4B5h 4D5h
20 3F4h 414h 434h 454h 474h 494h 4B4h 4D4h
21 3F3h 413h 433h 453h 473h 493h 4B3h 4D3h
22 3F2h 412h 432h 452h 472h 492h 4B2h 4D2h
23 3F1h 411h 431h 451h 471h 491h 4B1h 4D1h
24 3F0h 410h 430h 450h 470h 490h 4B0h 4D0h
25 3EFh 40Fh 42Fh 44Fh 46Fh 48Fh 4AFh 4CFh
26 3EEh 40Eh 42Eh 44Eh 46Eh 48Eh 4AEh 4CEh
27 3EDh 40Dh 42Dh 44Dh 46Dh 48Dh 4ADh 4CDh
28 3ECh 40Ch 42Ch 44Ch 46Ch 48Ch 4ACh 4CCh
29 3EBh 40Bh 42Bh 44Bh 46Bh 48Bh 4ABh 4CBh
30 3EAh 40Ah 42Ah 44Ah 46Ah 48Ah 4AAh 4CAh
31 3E9h 409h 429h 449h 469h 489h 4A9h 4C9h
32 3E8h 408h 428h 448h 468h 488h 4A8h 4C8h
* IMEX bin
010h*
Ampex 1308904-X4 Preliminary Draft 3-5
Page 24
Running Head
ACL Configuration ACL Application Programmer’s Guide
Model No.
3.3.2 Barcode Reader
The A CL maintains a volatile internal database that tracks the contents of the storage bins, tape
drive(s), and IMEX bins (8XX). This information includes the barcode IDs (volume tags) of
the tape cartridges located therein.
3.3.3 SCSI Target Configuration
The following parameters describe the ACL SCSI operating configuration (as reported in
response to a SCSI Inquiry command):
Inquiry field Value Description
Peripheral Qualifier,
Peripheral Device Type
RMB (Removable Medium) 1 Medium is removable.
Device Type Modifier (SCSI 1) 0 Not supported.
ISO Version 0 The ACL does not claim compliance with the ISO v ersion of
ECMA 0 The ACL does not claim compliance with the European
ANSI Approved Version 2h Complies with ANSI Standard X3.131-1994.
AENC 0 Asynchronous Event Notification Capability is not
TrmIOP 0 Terminate I/O Process is not applicable.
Response Data Format
Additional Length E5h Specifies the length in bytes of the returned data. During
0
Medium Changer Device. When the Inquiry command is
08h
performed on any logical unit other than logical unit zero,
the ACL returns 7Fh indicating that it supports no logical
unit other than 0.
SCSI.
Computer Manufacturers Association.
Supported.
2h Complies with ANSI SCSI-2 standards.
system initialization before all inquiry data is available,
returns a value of 1Fh indicating the shortened data length.
RelAddr 0 Relative addressing is not supported.
WBus32 0 32-bit wide data transfers are not supported.
WBus16 0 16-bit wide data transfers are not supported.
Sync 0 Synchronous data transfers are not supported.
Link 0 Linked commands are not supported
CmdQue 0 Command queing is not supported.
Soft Reset 0 Soft reset in response to a reset condition is not supported.
3-6 Preliminary Draft Ampex 1308904-X4
Page 25
ACL Application Programmer’s Guide ACL Configuration
3.3.4 Product Information
You can use either the aclGetVersion() function or acl_query_library utility to retrieve
vendor-specific information from the ACL. The information includes: vendor name, product
name, software revision levels, and software release dates.
3.3.5 Multiple Port and Multiple Initiator Considerations
The two SCSI ports on the ACL system I/O panel are functionally equivalent. Each port is
independently addressable and neither port has priority over the other. If desired, you can
connect the ACL to two separate SCSI buses simultaneously and each SCSI bus can have
multiple initiators arbitrating in the standard way for access; e.g., using the aclReserve() and
aclRelease() functions to achieve coordination.
When an initiator makes a reservation, the ACL denies access to all other initiators regardless
of which bus they are on. In the absence of a reservation, commands can e xecute concurrently
on both buses. The ACL appears busy if two initiators issue tape cartridge access commands
simultaneously, however, and one of the commands is rejected. Unit Attention Conditions
notify initiators of mode parameter changes made by other initiators.
3.3.6 Configuration Parameters
Table 3-2 describes the ACL configuration parameters that set ACL behavior.
• To view the current parameter settings, use the aclGetParam() function or the
acl_getparam_library utility.
• To change a parameter setting, use the aclSetParam() function or the
acl_setparam_library utility.
The ACL keeps only one set of values for its configuration parameters and they apply to all
initiators in a multi-initiator SCSI configuration. The Save P age feature is not supported; after
a hard reset or power-up, all the mode parameters reset to their default values.
Writer_Note: How does the user application detect the Unit Attention that occurs asynchronously?
When any of the Mode Parameters change, the A CL generates a Unit Attention to all initiators
except the one that issued the change parameter command.
Ampex 1308904-X4 Preliminary Draft 3-7
Page 26
Running Head
ACL Configuration ACL Application Programmer’s Guide
Model No.
Table 3-2. ACL Behavior Parameter Descriptions
Parameter State Description
Normally, the initiator must invoke a Tape Cartridge Movement
function or utility to remove a cartridge from the drive (after the
drive ejects the cartridge in response to an Unload command).
When the Auto Store Enable bit is set, the CHS automatically
returns any cartridge ejected by the drive to the storage bin from
which it was loaded (or, if this is unknown, to an empty storage
bin).
The ACL has an internal database which it keeps up to date.
When powered on with a tape cartridge in the drive, however, the
ACL cannot read the bar code on that cartridge until it is
unloaded from the drive.
When the Auto Audit Override parameter is set to off, the ACL
automatically executes a bar code read when it does not have a
bar code ID stored for the cartridge it unloads from the drive.
When the Auto Audit Override parameter is set to on, this
functionality is suppressed.
Auto Store Enable
Auto Audit Override
0 (off)*
1 (on)
0 (off)*
1 (on)
Bar Code Required
Enable
Auto Import Enable
(2XX, 4XX)
Auto Import Enable
(8XX)
* Default state.
0 (off)*
1 (on)
0 (off) The ACL does not have any Import/Export Elements.
0 (off)*
1 (on)
3.3.7 Power Up and Hard Reset
When the ACL is powered on or reset from the SCSI bus (hard reset or Bus Device Reset
message), it performs a boot sequence. During the boot sequence, the A CL loads the operating
program, initializes its subsystems, performs internal self tests, resets its mode parameters to
their default values, and clears its internal logs.
The ACL does not accept any SCSI commands other than Inquiry or Test Unit Ready until
it is ready for operation (see “Unit Ready Status” on page 3-10). When the boot sequence
completes successfully, Unit Attention is sent to all initiators to signal that the mode
parameters have changed.
When set, the ACL will not load a cartridge if it cannot read the
bar code on the cartridge.
The ACL detects the presence of a tape cartridge wen it is
inserted into an IMEX bin. When the Auto Import Enable
parameter is set to on, the ACL automatically transfers the
cartridge to a storage bin. When the Auto Import Enable
parameter is set to off, this functionality is suppressed and the
initiator must issue a Move command to transfer the cartridge to
a storage bin (or tape drive).
3-8 Preliminary Draft Ampex 1308904-X4
Page 27
ACL Application Programmer’s Guide Tape Cartridge Loading and Unloading
After completing the boot sequence successfully, the ACL performs an initialization routine
to update its element status database. Further updating of the database occurs automatically
whenever the ACL detects a condition that could cause element status to change (see
“Initialize Element Status” on page 3-10).
3.4 Tape Cartridge Loading and Unloading
3.4.1 Series 2XX and 4XX
The initiator must invoke the aclPark() function or acl_park_chs utility to park the CHS
before the front door can be opened to gain access to the storage bins. Opening the front door
locks the CHS in the parked position. (Before the front door is opened, any function or utility
that requires CHS movement will unpark the CHS; after the front door is opened, any function
or utility that requires CHS movement will unpark).
If the aclAuditLibrary() function or acl_audit_library utility is in voked while the front door
is open, the return data indicates that the door status is open and all element states are
unknown. During this period, all functions and utilities that require CHS movement will fail.
When the front door is closed after being opened (assuming the A CL is on-line), unparking of
the CHS occurs automatically and an initialization routine is performed to update location
status in the internal database.
3.4.2 Series 8XX
The IMEX bins are used for loading and unloading of tape cartridges.
Loading a Tape Cartridge
When a tape cartridge is inserted in an IMEX bin, the ACL detects its presence and performs
a bar code read to update the internal database. When the Auto Import Enable mode parameter
is set to on, the ACL automatically transfers the cartridge to an empty storage bin. (If all
storage bins are full, the ACL returns Check Condition status for the next SCSI command.)
When the Auto Import Enable mode parameter is set to off, the initiator must invoke a Tape
Cartridge Movement function or utility to transfer the tape cartridge to a storage bin or tape
drive.
Unloading a Tape Cartridge
Unloading a tape cartridge consists of moving it to an IMEX bin and manually removing it.
The ACL automatically updates element status in the internal database.
Ampex 1308904-X4 Preliminary Draft 3-9
Page 28
Running Head
Tape Cartridge Movement ACL Application Programmer’s Guide
Model No.
3.5 Tape Cartridge Movement
You can use the following functions and utilities to move tape cartridges between ACL
elements.
• aclMoveCartridge() and acl_move_tape move a tape cartridge from the specified
source location to the specified destination location.
• aclMoveVolume() and acl_move_volume move the specified tape cartridge (identified
by barcode ID) to the designated location.
Note: To ensure that the source element is full or the destination element is empty, use the
aclAuditElement() function or the acl_audit_element utility.
Table 3-2 describes the ACL configuration parameters that control how the ACL implements
a move command.
The ACL updates the internal database after each successful move command.
3.6 CHS Positioning
The initiator can use the aclPosition() function to position the designated storage bin in front
of the tape drive (2XX, 4XX) or to position the cartridge handler in front of the designated
element (8XX).
3.7 Operational Status
The following paragraphs describe the ACL status interface.
3.7.1 Unit Ready Status
You can use the aclTUR() function to check whether the ACL is ready for operation. The
function succeeds when the ACL is ready to accept commands and fails when the ACL is not
ready to accept commands.
3.7.2 Initialize Element Status
Any time that the ACL detects a condition that could cause element status to change, it
performs an initialization routine to audit the tape cartridge bins and update element status in
the internal database. This includes reading and storing the barcode IDs of the tape cartridges
contained therein.
The initialization routine is always performed when:
3-10 Preliminary Draft Ampex 1308904-X4
Page 29
ACL Application Programmer’s Guide Operational Status
• The ACL is powered on.
• A SCSI hard reset or Bus Device Reset message is received.
• ACL door status changes from open to closed.
• The ACL is placed in the SCSI mode after being operated in a manual mode.
When desired, an initiator can use the aclInit() function or the acl_init_chs utility to force the
ACL to perform an initialization routine. A related function, aclRezero(), resets the CHS and
directs the ACL to check element status; if a discrepancy is found, the ACL automatically
re-initializes to update its internal database.
3.7.3 Read Element Status
You can use the following functions and utilities to retrieve current ACL element status from
the internal database:
• aclAuditElement() and acl_audit_element retrieve the status of a single element.
• aclAuditLibrary() and acl_audit_library retrieve the status of all elements.
The aclAuditElement() and aclAuditLibrary() functions return the following information
for the various elements:
Transport Element Element address—address of the CHS
Door status—open or closed
CHS location (2XX, 4XX)—parked or the address of the
storage bin positioned in front of the tape drive
CHS location (8XX)—the location name of the element at
which the cartridge handler is positioned.
Storage Element Element address—address of the storage element (bin) for
which status is being reported
CHS access permission—allowed or disallowed
Element state—normal or abnormal
Empty or full—tape cartridge present or not
Tape cartridge volume tag—bar code ID
Tape cartridge size
Ampex 1308904-X4 Preliminary Draft 3-11
Page 30
Running Head
Operational Status ACL Application Programmer’s Guide
Data Transfer Element Element address—address of the data transfer element (tape
drive) for which status is being reported
CHS access permission—allowed or disallowed
Element state—normal or abnormal
Empty or full—tape cartridge present or not
Tape cartridge volume tag—bar code ID
Tape cartridge size
Model No.
Import/Export Element
(8XX)
The acl_audit_element and acl_audit_library utilities return the following information for
an element:
Element address—address of the import/export element
(IMEX bin) for which status is being reported
CHS access permission—allowed or disallowed
Element state—normal or abnormal
Empty or full—tape cartridge present or not
ASC/ASCQ condition
Tape cartridge volume tag—bar code ID
Tape cartridge size
• Access permission (allowed or disallowed).
• Contents (empty or full).
• Tape cartridge barcode ID (when available).
• Element state (normal or abnormal/unknown).
• Location name.
• Location type (element type: bin, CHS, drive, or IMEX).
For additional information such as door status or CHS position, use the aclStatus() function
or the acl_status_library utility.
3-12 Preliminary Draft Ampex 1308904-X4
Page 31
ACL Application Programmer’s Guide Operational Status
3.7.4 Internal Logs
You can use the following functions and utilities to retrieve entries from internal logs
containing statistics kept by the ACL. This information is valid for the current operating
session (that is, for the period since power on or the last reset).
• aclGetErrorLog() and acl_errlog_library retrieve entries from the error/e vent log. This
log lists internal events that might be useful to service personnel in diagnosing and
correcting problems; the events are reported in order of occurrence, starting with the most
recent
• aclGetStaticLog() and acl_statlog_library retrieve entries from the static log. This log
contains information about ACL internal software performance and protocol tasks; the
information is intended for use by Ampex factory personnel.
3.7.5 Sense Data
The ACL sets Sense Data when a command results in Check Condition status (see
Appendix A for descriptions of ACL Sense Data codes). You can use the following functions
and utilities to retrieve the Sense Data: aclReqSense(), aclStatus(), and acl_status_library.
Writer_Note: The following listing is based on the acl_status_library man page only. I have not yet
received the man page inputs for aclReqSense() and aclStatus(). [Vaughn gave me an
E-mail that suggested aclStatus() would be used to parse the data returned for
aclReqSense()].
The information returned includes the following
• SCSI Sense Data
– Sense Key The SCSI sense key value describing the condition (see
T able A-2).
– Sense Code The SCSI ASC/ASCQ value describing the condition (see
T able A-3).
• Additional Sense Data
– Condition Code Vendor-specific condition code (see T able A-4).
– CHS position 2XX, 4XX - The current position of the ACL cartridge
handling system; i.e., parked (0) or the address of the storage
bin positioned in front of the drive (100d–106d).
– 8XX - The address of the element at which the cartridge
handler is positioned; i.e. drive (100d–103d), storage bin
(1000d–1247d), or IMEX bin (10d–17d).
– Door Status Indicates whether door status is open or closed; sent by ACL
when door status changes and whenever a door is open.
Ampex 1308904-X4 Preliminary Draft 3-13
Page 32
Running Head
Operational Status ACL Application Programmer’s Guide
– Failure Code Vendor-specific failure code (see T able A-5); sent by ACL
when the CHS is unable to complete a SCSI command.
– Warning Code Vendor-specific warning code (see T able A-5); sent by ACL
when the CHS completes a command but detects a problem.
– Error Code V endor-specific error code (see T able A-5); sent by ACL when
the CHS does not attempt to execute a SCSI command.
– Frame Warning (2XX, 4XX) Indicates either that the tape drive is secured in
the ACL cabinet, or that the CHS assembly is swung away
from the ACL cabinet (i.e., out of frame).
– CHS Mode Indicates the current operating mode of the CHS: On-line,
Manual, Sequential Looping, or Sequential Non_Looping.
– Cartridge Size Not currently used but reserved for future implementation.
Model No.
3-14 Preliminary Draft Ampex 1308904-X4
Page 33
ACL Application Programmer’s Guide libacl API Functions
Section 4
libacl API Functions
4.1 Introduction
This section contains print versions of the manual pages for the libacl 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 libacl API functions, see the on-line manual
pages installed on your host system.
Ampex 1308904-X4 Preliminary Draft 4-1
Page 34
Running Head
libacl_intro_api ACL Application Programmer’s Guide
Model No.
4.2 libacl_intro_api
NAME
libacl_intro_api - introduction to DST/DIS libacl API C-Library functions
SYNOPSIS
Writer_Note: Need input for items flagged (TBS).
#include <acl.h>
int aclGeneric(char *device, ptBlk_t *cmd, int cmdLen, int flags, char *buf, int size);
int aclAuditLibrary(char *device, aclElementStatus_t elemdata[]);
int aclAuditElement(char *device, aclElementStatus_t elemdata[]);
int aclGetElemData(char *device, aclElemData_t *elemdata);
int GetErrorLog(TBS);
int aclGetParam(char *device, aclParam_t *param);
int aclGetVersion(char *device, aclVersion_t *aclversion);
int aclGetStaticLog(TBS);
int aclInit(char *device);
int aclMoveCartridge(char *device, unsigned int dea, unsigned int sea);
int aclMoveVolume(char *device, char *barcode, unsigned int dea);
int aclPark(char *device);
int aclPosition(char *device, int dest_addr);
int aclRelease(char *device, int tpr, int tpdid);
int aclReserve(TBS);
int aclReqSense(char *device, sense_data_t *sp, int size);
int aclRezero(char *device);
int aclSetParam(char *device, aclParam_t *param, int valid);
4-2 Preliminary Draft Ampex 1308904-X4
Page 35
ACL Application Programmer’s Guide libacl_intro_api
int aclStatus(TBS);
int aclTUR(char *device);
DESCRIPTION
The Ampe x DST/DIS SCSI Automated Cartridge Library libacl C-Library functions comprise
an application programming interface that provides access to the ACL de vice driver and also
to native SCSI passthru device driver interfaces. libacl functions provide the means to:
• check whether the ACL is ready to accept commands.
• update the ACL internal database and check element status.
• check or change ACL configuration parameter settings.
• retrieve error/event logs, static logs, and SCSI sense data.
• get vendor, product, software version, and software release information.
• control the ACL cartridge handling system (CHS).
• move tape cartridges between specified locations.
• retrieve ACL operating status.
• reserve and release the ACL.
• issue generic SCSI commands.
APPLICABILITY
Unless otherwise noted, the information in the libacl API manual pages applies to all DST and
DIS ACLs. Information unique to specific ACL models is identified by series number:
Series Number ACL Model
2XX DIS 220i, DIS 260i, etc.
4XX DST 410, DST 412, etc.
8XX DST 810, DST 812, etc.
Ampex 1308904-X4 Preliminary Draft 4-3
Page 36
Running Head
libacl_intro_api ACL Application Programmer’s Guide
Model No.
LIBACL FUNCTIONS SUMMARY
aclGeneric() Generic SCSI command interface.
aclAuditLibrary() Retrieve the status of all elements from the ACL internal database.
aclAuditElement() Retrieve the status of a single element from the ACL internal database.
aclGetElemData() Get element count and SCSI addresses.
aclGetErrorLog() (TBS)
aclGetParam() Get the current ACL configuration parameter settings.
aclGetStaticLog() (TBS)
aclGetVersion() Get ACL vendor, product, software version, and software release
information.
aclInit() Update element status in the ACL internal database.
aclMoveCartridge() Move a tape cartridge from one ACL location to another.
aclMoveVolume() Move the specified tape cartridge to another ACL location.
aclPark() Park the ACL cartridge handling system (2XX, 4XX).
aclPosition() Position the designated storage bin in front of the tape drive (2XX,
4XX) or position the cartridge handler in front of the designated
element (8XX).
aclRelease() Release a previously reserved ACL so that another SCSI initiator can
use it.
aclReserve() (TBS)
aclReqSense() Retrieve ACL SCSI sense data.
aclRezero() Reset the ACL and ensures that element status is current in the internal
database.
aclSetParam() Change ACL configuration parameter(s).
aclStatus() (TBS)
aclTUR() Check that the ACL is ready to accept commands.
4-4 Preliminary Draft Ampex 1308904-X4
Page 37
ACL Application Programmer’s Guide libacl_intro_api
ACL ELEMENTS
SCSI addresses are assigned to all A CL elements (locations) that can contain a tape cartridge.
libacl API functions recognize the addressable locations described below.
2XX and 4XX ACLs can move a tape cartridge from a storage bin to the tape drive, or from
the tape drive to a storage bin
8XX ACLs can move a tape cartridge to or from an y of the addressable elements (tape drive,
storage bin, IMEX bin, or CHS)
ACL Series 2XX and 4XX
Data Transfer Element The ACL tape drive. Its SCSI address is 100d (0x64).
Transport Element The A CL cartridge handling system (CHS). Its SCSI address is 01.
Storage Element One of the seven storage bins in the ACL. The bins are assigned
SCSI address 1000d / 0x3E8 (bottom bin) through 1006d / 0x3EE
(top bin).
ACL Series 8XX
Data Transfer Element The ACL tape dri ve(s). Up to four tape dri ves can be installed in the
Transport Element The A CL cartridge handling system (CHS). Its SCSI address is 01.
Storage Element One of the 248 storage bins in the ACL. The bins are assigned SCSI
Import/Export Element One of the eight import/export (IMEX) bins in the ACL. Each
ACL. The drives are assigned SCSI address 100d / 0x64 (bottom
drive) through 103d / 0x67 (top drive).
addresses in the following sequences:
Bin Numbers SCSI Addresses
A01-A32 1031-1000 (0x407-0x3E8)
B01-B32 1063-1032 (0x427-0x408)
C01-C32 1095-1064 (0x447-0x428)
D01-D32 1127-1096 (0x467-0x448)
E01-E32 1159-1128 (0x487-0x468)
F01-F32 1191-1160 (0x4A7-0x488)
G01-G32 1223-1192 (0x4C7-0x4A8)
H01-H06 1247-1242 (0x4DF-0x4DA)
H15-H32 1241-1224 (0x4D9-0x4C8)
IMEX bin has a SCSI address in the range of 17 / 0x11 (top IMEX
bin) through 10 / 0x0a (bottom IMEX bin).
Ampex 1308904-X4 Preliminary Draft 4-5
Page 38
Running Head
libacl_intro_api ACL Application Programmer’s Guide
Model No.
ENVIRONMENT
When the $RETRY_ON_RESET environment variable is set, all libacl functions
automatically perform one retry when a failure is caused by a SCSI Bus Device Reset of the
ACL.
RETURN V ALUES
All libacl functions return status codes on exit. See the manual pages for descriptions.
SEE ALSO
acl_intro(1), dd2_intro(1), dst_api_intro
DST/DIS Automated Cartridge Library Application Programming Interface (libacl)
Programmer’s Guide,
4-6 Preliminary Draft Ampex 1308904-X4
Page 39
ACL Application Programmer’s Guide aclGeneric
4.3 aclGeneric
NAME
aclGeneric() - generic SCSI command interface.
SYNOPSIS
#include <acl.h>
int aclGeneric(char *device, ptBlk_t *cmd, int cmdLen, int flags, char *buf, int size);
DESCRIPTION
aclGeneric() issues a SCSI command to a supported SCSI target. It is typically used when the
libacl API does not pro vide an equiv alent function for the desired SCSI command. If desired,
you can also use aclGeneric() to issue SCSI commands to a non-Ampex SCSI device.
aclGeneric() is available to all users.
PARAMETERS
*device Pointer or string specifying the device special file associated with the
ACL.
*cmd Pointer to a structure of type
cmdLen Integer value (6, 10, or 12) specifying the length in bytes of the SCSI
command descriptor block (CDB).
Writer_Note: Get new flags description from header file. (Vaughn is currently updating the file).
flags ?_Better Description Needed_? Contains information about the
direction of SCSI I/O.
*buf Pointer to a data buffer lar ge enough to store the SCSI data to be sent or
received; null if no data.
Writer_Note: What is the significance of “(to the interface)”.
size Integer specifying the size of the buffer (to the interface).
ptBlk_t.
USAGE
Before calling aclGeneric(), initialize the *cmd structure with the SCSI CDB data.
Ampex 1308904-X4 Preliminary Draft 4-7
Page 40
Running Head
aclGeneric ACL Application Programmer’s Guide
typedef struct ptBlk {
unsigned char b0; /* byte 0 */
unsigned char b1; /* byte 1 */
unsigned char b2; /* byte 2 */
unsigned char b3; /* byte 3 */
unsigned char b4; /* byte 4 */
unsigned char b5; /* byte 5 */
unsigned char b6; /* byte 6 */
unsigned char b7; /* byte 7 */
unsigned char b8; /* byte 8 */
unsigned char b9; /* byte 9 */
unsigned char b10; /* byte 10 */
unsigned char b11; /* byte 11 */
}ptBlk_t;
Model No.
ENVIRONMENT
When the $RETRY_ON_RESET environment variable is set, all libacl functions
automatically perform one retry when a failure is caused by a SCSI Bus Device Reset of the
ACL.
RETURN V ALUES
Exit status codes are:
0 DST_SUCCESS.
-1 DST_FAILURE.
SEE ALSO
libacl_api_intro(1)
DST/DIS Automated Cartridge Library Application Programming Interface (libacl)
Programmer’s Guide
4-8 Preliminary Draft Ampex 1308904-X4
Page 41
ACL Application Programmer’s Guide aclAuditLibrary
4.4 aclAuditLibrary
NAME
aclAuditLibrary() - retrieve the status of all elements from the ACL internal database.
SYNOPSIS
#include <acl.h>
int aclAuditLibrary(char *device, aclElementStatus_t elemdata[]);
DESCRIPTION
aclAuditLibrary() reports current status of all addressable elements in the ACL. See
libacl_api_intro(3) for information on ACL address assignments.
aclAuditLibrary() is available to all users.
PARAMETERS
*device Pointer or string specifying the device special file associated with the
ACL.
elemdata[] Array of
maximum number of elements in the ACL (nine for a 2XX or 4XX
ACL; 261 for an 8XX ACL).
aclElementStatus_t structures equal in size to the
USAGE
aclAuditLibrary() reports the element status in the elemdata[] array of structures Each
structure provides status for a single element.
Writer_Note: Change aclElementStatus_t aes[9] to max_element syntax; get details from header file.
char device[] = "device_name"
aclElementStatus_t aes[9]; /* or aes[261] for an 8XX ACL */
aclAuditLibrary(device,aes);
typedef struct
{
aclElementType_t type;
int acc;
int ex;
int full;
int size;
Ampex 1308904-X4 Preliminary Draft 4-9
Page 42
Running Head
aclAuditLibrary ACL Application Programmer’s Guide
int pos;
int door;
unsigned short sea;
char vtag[33];
}
aclElementStatus_t;
Model No.
STRUCTURE MEMBERS
type Identifies the element type:
ACL_CHS - Transport Element (CHS).
ACL_BIN - Storage Element (storage bin).
ACL_IMEX - Import/Export Element (IMEX bin, 8XX only).
ACL_DRIVE - Data Transfer Element (Tape Drive).
typedef enum
{
ACL_unused = 0,
ACL_CHS,
ACL_BIN,
ACL_IMEX,
ACL_DRIVE
}
aclElementType_t;
acc An access bit of one or zero indicates, respectively, that the A CL can or
cannot transfer a tape cartridge to or from the element.
ex An exception bit of one indicates an abnormal or unknown element
state. Zero indicates a normal state.
full A full bit of one indicates the element contains a tape cartridge. Zero
indicates the element is empty.
size The size of the tape cartridge in the element:
0x0001 - Small.
0x0002 - Medium.
0x0003 - Large.
0xFFFF - Unknown.
pos Reports the position of the CHS.
2XX, 4XX – Parked (0), or the address of the storage bin positioned in
front of the tape drive (1000-1006 / 0x3E8-0x3EE).
8XX – The address of the location at which the cartridge handler is
positioned:
4-10 Preliminary Draft Ampex 1308904-X4
Page 43
ACL Application Programmer’s Guide aclAuditLibrary
Tape drive (100 - 103 / 0x64 - 0x67)
Storage bin (1000 - 1247 / 0x3E8 - 0x4DF)
IMEX bin (10 - 17 / 0x0A - 0x12)
door Indicates that a door on the A CL is open (1) or that all doors are closed (0).
Valid for the transport element (CHS) only.
sea Address of the element for which status is being reported.
Writer_Note: The ACL Utilities say that the barcode ID is 6 characters. Here it says the barcode ID
can be up to 32 characters. Which is correct?
vtag Reports the barcode ID (volume tag) of the tape cartridge in the element
(when available). This can be up to 32 characters long. Barcode IDs
containing fewer characters are left justified and padded with trailing
spaces (0x20).
ENVIRONMENT
When the $RETRY_ON_RESET environment variable is set, all libacl functions
automatically perform one retry when a failure is caused by a SCSI Bus Device Reset of the
ACL.
RETURN V ALUES
Exit status codes are:
9 (2XX, 4XX) DST_SUCCESS.
261 (8XX)
0 DST_FAILURE.
SEE ALSO
libacl_api_intro(3), acl_audit_library(1)
DST/DIS Automated Cartridge Library Application Programming Interface (libacl)
Programmer’s Guide
Ampex 1308904-X4 Preliminary Draft 4-11
Page 44
Running Head
aclAuditElement ACL Application Programmer’s Guide
Model No.
4.5 aclAuditElement
NAME
aclAuditElement() - retrieve the status of a single element from the ACL internal database.
SYNOPSIS
#include <acl.h>
int aclAuditElement(char *device, aclElementStatus_t elemdata[]);
DESCRIPTION
aclAuditElement() reports the current status of a single addressable element in the ACL. See
libacl_api_intro(3) for information on ACL address assignments.
aclAuditElement() is available to all users.
PARAMETERS
*device Pointer or string specifying the device special file associated with the
elemdata[] An array containing a single
USAGE
aclAuditElement() reports the element status in the elemdata[] structure.
Before calling aclAuditElement(), assign the address of the element for which you are
requesting status to the
char device[] = "device_name"
aclElementStatus_t aes[1];
aclAuditLibrary(device,aes);
typedef struct
{
ACL.
aclElementStatus_t structure.
sea member of the structure.
aclElementType_t type;
int acc;
int ex;
int full;
int size;
int pos;
int door;
4-12 Preliminary Draft Ampex 1308904-X4
Page 45
ACL Application Programmer’s Guide aclAuditElement
unsigned short sea; /* assign element address here */
char vtag[33];
}
aclElementStatus_t;
STRUCTURE MEMBERS
type Identifies the element type:
ACL_CHS - Transport Element (CHS).
ACL_BIN - Storage Element (storage bin).
ACL_IMEX - Import/Export Element (IMEX bin, 8XX).
ACL_DRIVE - Data Transfer Element (tape drive).
typedef enum
{
ACL_unused = 0,
ACL_CHS,
ACL_BIN,
ACL_IMEX,
ACL_DRIVE
}
aclElementType_t;
acc An access bit of one or zero indicates, respectively, that the ACL can or
cannot transfer a tape cartridge to or from the element.
ex An exception bit of one indicates an abnormal or unknown element state.
Zero indicates a normal state.
full A full bit of one indicates the element contains a tape cartridge. Zero
indicates the element is empty.
size The size of the tape cartridge in the element:
0x0001 - Small.
0x0002 - Medium.
0x0003 - Large.
0xFFFF - Unknown.
pos Reports the position of the CHS.
2XX, 4XX – Parked (0), or the address of the storage bin positioned in
front of the tape drive (1000-1006 / 0x3E8-0x3EE).
8XX – The address of the location at which the cartridge handler is
positioned:
Tape drive (100 - 103 / 0x64 - 0x67).
Storage bin (1000 - 1247 / 0x3E8 - 0x4DF).
IMEX bin (10 - 17 / 0x0A - 0x12).
Ampex 1308904-X4 Preliminary Draft 4-13
Page 46
Running Head
aclAuditElement ACL Application Programmer’s Guide
door Indicates that a door on the ACL is open (1) or that all doors are
closed (0). Valid for the transport element (CHS) only.
sea On input, specifies the address of the element for which status is
being requested. On return, indicates the address of the element for
which status is being reported.
vtag Reports the barcode ID (volume tag) of the tape cartridge in the
element (when available). This can be up to 32 characters long.
Volume tags containing fewer characters are left justified and
padded with trailing spaces (0x20).
Model No.
ENVIRONMENT
When the $RETRY_ON_RESET environment variable is set, all libacl functions
automatically perform one retry when a failure is caused by a SCSI Bus Device Reset of the
ACL.
RETURN V ALUES
Exit status codes are:
0 DST_SUCCESS.
-1 DST_FAILURE.
SEE ALSO
libacl_api_intro(3), acl_audit_element(1)
DST/DIS Automated Cartridge Library Application Programming Interface (libacl)
Programmer’s Guide
4-14 Preliminary Draft Ampex 1308904-X4
Page 47
ACL Application Programmer’s Guide aclGetElemData
4.6 aclGetElemData
NAME
aclGetElemData() - get element count and SCSI addresses.
SYNOPSIS
#include <acl.h>
int aclGetElemData(char *device, aclElemData_t *elemdata);
DESCRIPTION
aclGetElemData() retrieves element data such as SCSI address assignments and element
counts. This information is used to determine the inputs to the aclMoveCartridge() and
aclMoveVolume() functions. See libacl_api_intro(3) for information on ACL address
assignments.
aclGetElemData() is available to all users.
PARAMETERS
*device Pointer or string specifying the device special file associated with the A CL.
*elemdata Pointer to a structure of type
aclElemData_t.
USAGE
aclGetElemData() reports element data in the *elemdata structure.
Writer_Note: “Transfer element “ should be “data transfer element”.
typedef struct
{
unsigned int XportCount; /* transport element count */
unsigned int XportStart; /* transport element start address */
unsigned int StorCount; /* storage element count */
unsigned int StorStart; /* storage element starting address */
unsigned int ImexCount; /* import/export element count */
unsigned int ImexStart; /* import/export element starting address */
unsigned int XferCount; /* transfer element count */
unsigned int XferStart; /* transfer element starting address */
}aclElemData_t;
Ampex 1308904-X4 Preliminary Draft 4-15
Page 48
Running Head
aclGetElemData ACL Application Programmer’s Guide
Model No.
ENVIRONMENT
When the $RETRY_ON_RESET environment variable is set, all libacl functions
automatically perform one retry when a failure is caused by a SCSI Bus Device Reset of the
ACL.
RETURN V ALUES
Exit status codes are:
0 DST_SUCCESS.
-1 DST_FAILURE.
SEE ALSO
libacl_api_intro(3), DST/DIS Automated Cartridge Library Application Programming
Interface (libacl) Programmer’s Guide
4-16 Preliminary Draft Ampex 1308904-X4
Page 49
ACL Application Programmer’s Guide aclGetErrorLog
4.7 aclGetErrorLog
(TBS)
Ampex 1308904-X4 Preliminary Draft 4-17
Page 50
Running Head
aclGetParam ACL Application Programmer’s Guide
Model No.
4.8 aclGetParam
NAME
aclGetParam() - get the current ACL configuration parameter settings.
SYNOPSIS
#include <acl.h>
int aclGetParam(char *device, aclParam_t *param);
DESCRIPTION
aclGetParam() gets the current settings of the ACL configuration parameters. These
parameters define ACL behavior as described below. To change a configuration parameter
setting, use the aclSetParam() function.
aclGetParam() is available to all users.
PARAMETERS
*device Pointer or string specifying the device special file associated with the
*param Pointer to a structure of type
USAGE
aclGetParam() reports the configuration parameter settings in the *param structure.
typedef struct
{
unsigned char AutoEject;
unsigned char AutoAuditOverride;
unsigned char BarcodeReqEnable;
unsigned char AutoImport;
}aclParam_t;
ACL.
aclParam_t.
4-18 Preliminary Draft Ampex 1308904-X4
Page 51
ACL Application Programmer’s Guide aclGetParam
STRUCTURE MEMBERS
AutoEject Reports whether the Auto Store Enable configuration parameter is
on (1) or off (0, default).
When the Auto Store Enable configuration parameter is set to off,
the initiator must use the aclMoveCartridge() or
aclMoveVolume() function to remove a tape cartridge from the
tape drive (after the drive ejects the tape cartridge in response to a
tape drive Unload command).
When the Auto Store Enable configuration parameter is set to on,
the ACL automatically returns any tape cartridge ejected by the
drive to the storage bin from which it was loaded (or, if this is
unknown, to an empty storage bin).
AutoAuditOverride Reports whether the Auto Audit Override configuration parameter
is on (1, default) or off (0).
The ACL has an internal database that it keeps up to date. When
powered on with a tape cartridge in the drive, however, the ACL
cannot read the barcode ID of that cartridge until it is unloaded from
the drive.
When the Auto Audit Ov erride configuration parameter is set to off,
the ACL automatically executes a barcode read when it does not
have a barcode ID stored for the tape cartridge it unloads from the
drive. When the Auto Audit Ov erride configuration parameter is set
to on, this functionality is suppressed.
BarcodeReqEnable Reports whether the Barcode Required Enable configuration
parameter is on (1) or off (0, default).
When the Barcode Required Enable configuration parameter is set
to on, the ACL will not accept a tape cartridge that does not have a
readable barcode ID; i.e., the ACL will not transfer the cartridge to
a drive (2XX, 4XX) or from an IMEX bin (8XX). When the
parameter is set to off, the ACL accepts all tape cartridges without
regard to barcode ID.
AutoImport 8XX – Reports whether the Auto Import Enable configuration
parameter is on (1) or off (0, default).
The A CL detects the presence of a tape cartridge when it is inserted
into an IMEX bin. When the Auto Import Enable configuration
parameter is set to on, the ACL automatically transfers the tape
cartridge to the next available Storage Element, starting from
address 1000.
Ampex 1308904-X4 Preliminary Draft 4-19
Page 52
Running Head
aclGetParam ACL Application Programmer’s Guide
When the Auto Import Enable configuration parameter is set to of f,
this functionality is suppressed and the initiator must use the
aclMoveCartridge() or aclMoveVolume() function to transfer the
tape cartridge to a storage bin (or tape drive).
Model No.
ENVIRONMENT
When the $RETRY_ON_RESET environment variable is set, all libacl functions
automatically perform one retry when a failure is caused by a SCSI Bus Device Reset of the
ACL.
BUGS
RETURN V ALUES
Exit status codes are:
0 DST_SUCCESS.
-1 DST_FAILURE.
SEE ALSO
libacl_api_intro(3) aclSetParam(3), acl_getparam_library(1)
DST/DIS Automated Cartridge Library Application Programming Interface (libacl)
Programmer’s Guide
4-20 Preliminary Draft Ampex 1308904-X4
Page 53
ACL Application Programmer’s Guide aclGetStaticLog
4.9 aclGetStaticLog
(TBS)
Ampex 1308904-X4 Preliminary Draft 4-21
Page 54
Running Head
aclGetVersion ACL Application Programmer’s Guide
Model No.
4.10 aclGetVersion
NAME
aclGetVersion() - get ACL vendor, product, software version, and software release
information.
SYNOPSIS
#include <acl.h>
int aclGetVersion(char *device, aclVersion_t *aclversion);
DESCRIPTION
aclGetVersion() reports the ACL vendor name, product name, software revision levels and
software release dates.
aclGetVersion() is available to all users.
PARAMETERS
*device Pointer or string specifying the device special file associated with the
ACL.
*aclversion Pointer to a structure of type
aclVersion_t.
USAGE
aclGetVersion() reports the version information in the *aclversion structure.
Writer_Note: Sizes of structure members are different that shown for SCSI Inquiry command in ICD.
typedef struct
{
unsigned char vendor[9];
unsigned char product[17];
unsigned char proto_cpu[5];
unsigned char servo_cpu[5];
unsigned char proto_prom[5];
unsigned char servo_prom[5];
unsigned char util_rel[5];
unsigned char libacl_rel[5];
unsigned char firm_rel_date[9];
unsigned char util_rel_date[18];
unsigned char libacl_rel_date[18];
}aclVersion_t;
4-22 Preliminary Draft Ampex 1308904-X4
Page 55
ACL Application Programmer’s Guide aclGetVersion
STRUCTURE MEMBERS
vendor Vendor name.
product Product name.
proto_cpu CPU Protocol Software version.
servo_cpu CPU Servo Software version.
proto_prom Boot Prom Protocol Software version.
servo_prom Boot Prom Servo Software version.
util_rel ACL Utilities version.
libacl_rel libacl API Version.
firm_rel_date ACL firmware release date release date.
util_rel_date ACL Utilities release date.
libacl_rel_date libacl API release date.
ENVIRONMENT
When the $RETRY_ON_RESET environment variable is set, all libacl functions
automatically perform one retry when a failure is caused by a SCSI Bus Device Reset of the
ACL.
RETURN V ALUES
Exit status codes are:
0 DST_SUCCESS.
-1 DST_FAILURE.
SEE ALSO
libacl_api_intro(3), acl_query_library(1)
DST/DIS Automated Cartridge Library Application Programming Interface (libacl)
Programmer’s Guide
Ampex 1308904-X4 Preliminary Draft 4-23
Page 56
Running Head
aclInit ACL Application Programmer’s Guide
Model No.
4.11 aclInit
NAME
aclInit() - update element status in the ACL internal database.
SYNOPSIS
#include <acl.h>
int aclInit(char *device);
DESCRIPTION
aclInit() directs the ACL cartridge handling system to audit the contents of all elements
(locations) and update their status in the ACL internal database. Use of this utility is optional
since the ACL automatically performs an initialization routine whenever it detects any
condition that could cause element status to change.
aclInit() is available to all users.
PARAMETERS
*device Pointer or string specifying the device special file associated with the
ENVIRONMENT
When the $RETRY_ON_RESET environment variable is set, all libacl functions
automatically perform one retry when a failure is caused by a SCSI Bus Device Reset of the
ACL.
RETURN V ALUES
Exit status codes are:
0 DST_SUCCESS.
-1 DST_FAILURE.
SEE ALSO
ACL.
libacl_api_intro(3), acl_init_chs(1)
DST/DIS Automated Cartridge Library Application Programming Interface (libacl)
Programmer’s Guide
4-24 Preliminary Draft Ampex 1308904-X4
Page 57
ACL Application Programmer’s Guide aclMoveCartridge
4.12 aclMoveCartridge
NAME
aclMoveCartridge() - move a tape cartridge from one ACL location to another.
SYNOPSIS
#include <acl.h>
int aclMoveCartridge(char *device, unsigned int sea, unsigned int dea);
DESCRIPTION
aclMoveCartridge() moves a tape cartridge from the specified source location to the specified
destination location. This function fails if the source location is empty , the destination location
is full, an invalid source or destination location is specified, or a cabinet door is open.
2XX and 4XX ACLs can only move a tape cartridge from a storage bin to the tape drive, or
from the tape drive to a storage bin. 8XX ACLs can move a tape cartridge to or from any of
the addressable elements (tape drive, storage bin, IMEX bin, or CHS).
When the source location is a tape drive, the tape cartridge to be moved must already be
located in the drive load port; that is, the dri ve must have already ejected the cartridge. T o force
the drive to eject the tape cartridge, invoke the dst_unload(3) function before calling the
aclMoveCartridge() function.
aclMoveCartridge() is available to all users. See libacl_api_intr o(3) for information on A CL
address assignments.
PARAMETERS
*device Pointer or string specifying the device special file associated with the
sea, dea Source and destination addresses.
ACL.
Valid addresses for a 2XX or 4XX ACL are:
Tape drive 100 (0x64).
Storage bin 1000-1006 (0x3E8-0x3EE).
Valid addresses for an 8XX ACL are:
Tape drive 100-103 (0x64-0x67).
Storage bin 1000-1247 (0x3E8-0x4DF).
IMEX bin 10-17 (0x0A-0x12).
Transport (CHS) 01.
Ampex 1308904-X4 Preliminary Draft 4-25
Page 58
Running Head
aclMoveCartridge ACL Application Programmer’s Guide
Model No.
ENVIRONMENT
When the $RETRY_ON_RESET environment variable is set, all libacl functions
automatically perform one retry when a failure is caused by a SCSI Bus Device Reset of the
ACL.
RETURN V ALUES
Exit status codes are:
0 DST_SUCCESS.
-1 DST_FAILURE.
SEE ALSO
libacl_api_intro(3), aclMoveVolume(3), acl_move_tape(1), dst_unload(3),
DST/DIS Automated Cartridge Library Application Programming Interface (libacl)
Programmer’s Guide
4-26 Preliminary Draft Ampex 1308904-X4
Page 59
ACL Application Programmer’s Guide aclMoveVolume
4.13 aclMoveVolume
NAME
aclMoveVolume() - move the specified tape cartridge to another ACL location.
SYNOPSIS
#include <acl.h>
int aclMoveVolume(char *device, char *barcode, unsigned int dea);
DESCRIPTION
aclMoveVolume() mov es the specified tape cartridge to another ACL location. This function
fails if the barcode ID is not found, the target location is full, an invalid target location is
specified, or a cabinet door is open.
2XX and 4XX ACLs can only move a tape cartridge to a storage bin or the tape drive. 8XX
ACLs can move a tape cartridge to any of the addressable elements (tape drive, storage bin,
IMEX bin, or CHS).
When the source location is a tape drive, the tape cartridge to be moved must already be
located in the drive load port; that is, the dri ve must have already ejected the cartridge. T o force
the drive to eject the tape cartridge, invoke the dst_unload(3) function before calling the
aclMoveCartridge() function.
aclMoveVolume() is available to all users.
PARAMETERS
*device Pointer or string specifying the device special file associated with the
*barcode The barcode ID of the tape cartridge that you want to move. This value
dea The address of the element to which you want to move the tape
ACL.
must be a six character ASCII string with no trailing null character.
cartridge.
Valid addresses for a 2XX or 4XX ACL are:
Tape drive 100 (0x64).
Storage bin 1000-1006 (0x3E8-0x3EE).
Ampex 1308904-X4 Preliminary Draft 4-27
Page 60
Running Head
aclMoveVolume ACL Application Programmer’s Guide
Valid addresses for an 8XX ACL are:
Tape drive 100-103 (0x64-0x67).
Storage bin 1000-1247 (0x3E8-0x4DF).
IMEX bin 10-17 (0x0A-0x12).
Transport (CHS) 01.
Model No.
ENVIRONMENT
When the $RETRY_ON_RESET environment variable is set, all libacl functions
automatically perform one retry when a failure is caused by a SCSI Bus Device Reset of the
ACL.
RETURN V ALUES
Exit status codes are:
0 DST_SUCCESS.
-1 DST_FAILURE.
SEE ALSO
libacl_api_intro(3), aclMoveCartridge(3), acl_move_volume(1), dst_unload(3), DST/DIS
Automated Cartridge Library Application Programming Interface (libacl) Programmer’s
Guide
4-28 Preliminary Draft Ampex 1308904-X4
Page 61
ACL Application Programmer’s Guide aclPark
4.14 aclPark
NAME
aclPark() - park the ACL cartridge handling system (2XX, 4XX).
SYNOPSIS
#include <acl.h>
int aclPark(char *device);
DESCRIPTION
aclPark() parks the ACL cartridge handling system (CHS) so that the front door of the ACL
can be opened to insert or remove tape cartridges. Opening the front door locks the CHS in
the parked position.
Unparking of the CHS occurs when the front door is closed after being opened (or the ACL is
commanded to reposition the CHS before the front door is opened). Closing the front door also
causes the ACL to perform an initialization routine that updates element status in the internal
database.
aclPark() is available to all users.
PARAMETERS
*device Pointer or string specifying the device special file associated with the
ENVIRONMENT
When the $RETRY_ON_RESET environment variable is set, all libacl functions
automatically perform one retry when a failure is caused by a SCSI Bus Device Reset of the
ACL.
RETURN V ALUES
Exit status codes are:
ACL.
0 DST_SUCCESS.
-1 DST_FAILURE.
Ampex 1308904-X4 Preliminary Draft 4-29
Page 62
Running Head
aclPark ACL Application Programmer’s Guide
Model No.
SEE ALSO
libacl_api_intro(3), acl_park_chs(1)
DST/DIS Automated Cartridge Library Application Programming Interface (libacl)
Programmer’s Guide
4-30 Preliminary Draft Ampex 1308904-X4
Page 63
ACL Application Programmer’s Guide aclPosition
4.15 aclPosition
NAME
aclPosition() - position the designated storage bin in front of the tape drive (2XX, 4XX), or
position the cartridge handler in front of the designated element (8XX).
SYNOPSIS
#include <acl.h>
int aclPosition(char *device, int dest_addr);
DESCRIPTION
For a 2XX or 4XX ACL, aclPosition() moves the designated storage bin in front of the tape
drive. For an 8XX A CL, aclP osition() mo v es the cartridge handler to the designated element
(tape drive, storage bin or IMEX bin).
aclPosition() is available to all users.
PARAMETERS
*device Pointer or string specifying the device special file associated with the
*dest_addr) Destination address (2XX, 4XX) - you can specify any of the storage
ENVIRONMENT
When the $RETRY_ON_RESET environment variable is set, all libacl functions
automatically perform one retry when a failure is caused by a SCSI Bus Device Reset of the
ACL.
ACL.
element addresses: 1000d – 1006d (3E8h – 3EEh).
Destination Address (8XX) - You can specify any of the following
element addresses:
Tape drive 100d – 103d (64h – 67h).
Storage bin 1000d – 1247d (3E8h – 4DFh).
IMEX bin 10d – 17d (0Ah – 11h).
Ampex 1308904-X4 Preliminary Draft 4-31
Page 64
Running Head
aclPosition ACL Application Programmer’s Guide
Model No.
RETURN V ALUES
Exit status codes are:
0 DST_SUCCESS.
-1 DST_FAILURE.
SEE ALSO
libacl_api_intro(3)
DST/DIS Automated Cartridge Library Application Programming Interface (libacl)
Programmer’s Guide
4-32 Preliminary Draft Ampex 1308904-X4
Page 65
ACL Application Programmer’s Guide aclRelease
4.16 aclRelease
NAME
aclRelease() - release a previously reserved ACL so that another SCSI initiator can use it.
SYNOPSIS
#include <acl.h>
int aclRelease(char *device, int tpr, int tpdid);
DESCRIPTION
aclRelease() releases a previously reserved ACL from the specified initiator. This function,
along with the aclReserve() function, provides a mechanism to obtain exclusi ve access to the
ACL when it is connected to multiple initiators.
aclRelease() is available to all users.
PARAMETERS
*device Pointer or string specifying the device special file associated with the
*tpr When set to zero, releases any outstanding reservation made by the
tpdid Third Party SCSI Device ID (0 -7) of the initiator reserving the ACL.
ENVIRONMENT
When the $RETRY_ON_RESET environment variable is set, all libacl functions
automatically perform one retry when a failure is caused by a SCSI Bus Device Reset of the
ACL.
ACL.
initiator issuing the aclRelease() function—which was not a 3rd party
reservation.
When set to one, releases any outstanding reservation made by the
initiator issuing the aclRelease() function—which was a 3rd party
reservation on behalf of the same device specified by the 3rd Party
Device ID (tpdid parameter).
This parameter is ignored when the tpr parameter is zero
Ampex 1308904-X4 Preliminary Draft 4-33
Page 66
Running Head
aclRelease ACL Application Programmer’s Guide
Model No.
RETURN V ALUES
Exit status codes are:
0 DST_SUCCESS.
-1 DST_FAILURE.
SEE ALSO
libacl_api_intro (3), aclReserve(3)
DST/DIS Automated Cartridge Library Application Programming Interface (libacl)
Programmer’s Guide
4-34 Preliminary Draft Ampex 1308904-X4
Page 67
ACL Application Programmer’s Guide aclReserve
4.17 aclReserve
(TBS)
Ampex 1308904-X4 Preliminary Draft 4-35
Page 68
Running Head
aclReqSense ACL Application Programmer’s Guide
Model No.
4.18 aclReqSense
NAME
aclReqSense() - retrieve ACL SCSI sense data.
SYNOPSIS
#include <acl.h>
int aclReqSense(char *device, sense_data_t *sp, int size);
Writer_Note: Should we list the sense_data_t structure in the man page and describe the structure
members? Even if we do so, the supporting detail necessary to interpret the sense data
is currently published only in the ICD which the customer doesn’t get. I plan to include
the detail in some future release of the libacl Programmer’s Guide, but I have no idea
when that will be as eight months have elapsed since I last had a chance to work on it.
DESCRIPTION
aclReqSense() issues a SCSI Request Sense command to the ACL to retrieve the current
Sense Data. This function is usually called to determine the condition(s) that caused the
previous function to fail.
• The ACL clears Sense Data prior to executing any command other than Request Sense
and sets Sense Data when a command results in a Check Condition or Command
Terminated status. Separate Sense Data is preserved for each initiator. Sense Data is
cleared after it is retrieved by a Request Sense command.
• In general, the ACL retains the original Sense Data when an error occurs executing a
Request Sense command. However, when the error occurs parsing the command
descriptor block (CDB), the original Sense Data is lost and is replaced with Sense Data
corresponding to the parsing error
aclReqSense() is available to all users.
PARAMETERS
*device Pointer or string specifying the device special file associated with the
ACL.
*sp Pointer to a structure of type
Writer_Note: Need input for size parameter.
size (TBS)
4-36 Preliminary Draft Ampex 1308904-X4
sense_data_t.
Page 69
ACL Application Programmer’s Guide aclReqSense
USAGE
aclReqSense() reports current Sense Data in the *sp structure. See the acl.h header file for
details.
ENVIRONMENT
When the $RETRY_ON_RESET environment variable is set, all libacl functions
automatically perform one retry when a failure is caused by a SCSI Bus Device Reset of the
ACL.
RETURN V ALUES
Exit status codes are:
0 DST_SUCCESS.
-1 DST_FAILURE.
SEE ALSO
libacl_api_intro(3)
DST/DIS Automated Cartridge Library Application Programming Interface (libacl)
Programmer’s Guide
Ampex 1308904-X4 Preliminary Draft 4-37
Page 70
Running Head
aclRezero ACL Application Programmer’s Guide
Model No.
4.19 aclRezero
NAME
aclRezero() - reset the ACL and ensure that element status is current in the internal database.
SYNOPSIS
#include <acl.h>
int aclRezero(char *device);
DESCRIPTION
aclRezero() resets the ACL cartridge handling system and directs the ACL to check element
status. If a discrepancy is found, the ACL re-initializes to update its internal database.
aclRezero() is available to all users.
PARAMETERS
*device Pointer or string specifying the device special file associated with the
ENVIRONMENT
When the $RETRY_ON_RESET environment variable is set, all libacl functions
automatically perform one retry when a failure is caused by a SCSI Bus Device Reset of the
ACL.
RETURN V ALUES
Exit status codes are:
0 DST_SUCCESS.
-1 DST_FAILURE.
SEE ALSO
ACL.
libacl_api_intro(3)
DST/DIS Automated Cartridge Library Application Programming Interface (libacl)
Programmer’s Guide
4-38 Preliminary Draft Ampex 1308904-X4
Page 71
ACL Application Programmer’s Guide aclSetParam
4.20 aclSetParam
NAME
aclSetParam() - change ACL configuration parameter(s).
SYNOPSIS
#include <acl.h>
int aclSetParam(char *device, aclParam_t *param, int valid);
DESCRIPTION
aclSetParam() sets the behavior of the ACL by changing one or more configuration parameter
settings. To check the current configuration parameter settings, use the aclGetParam()
function.
aclSetParam() is available to all users.
PARAMETERS
*device Pointer or string specifying the device special file associated with the
*param Pointer to a structure of type
valid The valid parameter is a bit-mask that indicates which member(s) of the
USAGE
ACL.
aclParam_t.
aclParam_t structure contain new configuration parameter settings.
AutoEject_Valid 0x00000001
AutoAuditOverride_Valid 0x00000002
BarcodeReqEnable_Valid 0x00000003
AutoImport_Valid 0x00000004
If only the
are being changed for example, the valid mask should be set as follows:
AutoEject and AutoImport configuration parameters
valid = AutoEject_Valid | AutoImport_Valid;
Before calling aclSetParam(), initialize the appropriate members of the *param structure
with new values for the configuration parameters you want to change.
typedef struct
{
unsigned char AutoEject;
Ampex 1308904-X4 Preliminary Draft 4-39
Page 72
Running Head
aclSetParam ACL Application Programmer’s Guide
unsigned char AutoAuditOverride;
unsigned char BarcodeReqEnable;
unsigned char AutoImport;
}aclParam_t;
Model No.
STRUCTURE MEMBERS
AutoEject Sets the Auto Store Enable configuration parameter to on (1) or of f
(0, default).
When the Auto Store Enable configuration parameter is set to off,
the initiator must use the aclMoveCartridge() or
aclMoveVolume() function to remove a tape cartridge from the
tape drive (after the drive ejects the tape cartridge in response to a
tape drive Unload command).
When the Auto Store Enable configuration parameter is set to on,
the ACL automatically returns any tape cartridge ejected by the
drive to the storage bin from which it was loaded (or, if this is
unknown, to an empty storage bin).
AutoAuditOverride Sets the Auto Audit Override configuration parameter to on
(1, default) or off (0).
The ACL has an internal database that it keeps up to date. When
powered on with a tape cartridge in the drive, however, the ACL
cannot read the barcode ID of that cartridge until it is unloaded from
the drive.
When the Auto Audit Ov erride configuration parameter is set to off,
the ACL automatically executes a barcode read when it does not
have a barcode ID stored for a tape cartridge it unloads from the
drive. When the Auto Audit Ov erride configuration parameter is set
to on, this functionality is suppressed.
BarcodeReqEnable Sets the Barcode Required Enable configuration parameter to on (1)
or off (0, default).
When the Barcode Required Enable configuration parameter is set
to on, the ACL will not accept a tape cartridge that does not have a
readable barcode ID; i.e., the ACL will not transfer the cartridge to
a drive (2XX, 4XX) or from an IMEX bin (8XX). When the
parameter is set to off, the ACL accepts all tape cartridges without
regard to barcode ID.
4-40 Preliminary Draft Ampex 1308904-X4
Page 73
ACL Application Programmer’s Guide aclSetParam
AutoImport 8XX – Sets the Auto Import Enable configuration parameter to on
(1) or off (0, default).
The A CL detects the presence of a tape cartridge when it is inserted
into an IMEX bin. When the Auto Import Enable configuration
parameter is set to on, the ACL automatically transfers the tape
cartridge to the next available Storage Element, starting from
address 1000.
When the Auto Import Enable configuration parameter is set to of f,
this functionality is suppressed and the initiator must use the
aclMoveCartridge() or aclMoveVolume() function to transfer the
tape cartridge to a storage bin (or tape drive).
ENVIRONMENT
When the $RETRY_ON_RESET environment variable is set, all libacl functions
automatically perform one retry when a failure is caused by a SCSI Bus Device Reset of the
ACL.
RETURN V ALUES
Exit status codes are:
0 DST_SUCCESS.
-1 DST_FAILURE.
SEE ALSO
libacl_api_intro(3), aclGetParam(3), acl_setparam_library(1)
DST/DIS Automated Cartridge Library Application Programming Interface (libacl)
Programmer’s Guide
Ampex 1308904-X4 Preliminary Draft 4-41
Page 74
Running Head
aclStatus ACL Application Programmer’s Guide
Model No.
4.21 aclStatus
(TBS)
4-42 Preliminary Draft Ampex 1308904-X4
Page 75
ACL Application Programmer’s Guide aclTUR
4.22 aclTUR
NAME
aclTUR() - check that the ACL is ready to accept commands.
SYNOPSIS
#include <acl.h>
int aclTUR(char *device);
DESCRIPTION
aclTUR() checks that the ACL is ready to accept commands.
aclTUR() is available to all users.
PARAMETERS
*device Pointer or string specifying the device special file associated with the
ENVIRONMENT
When the $RETRY_ON_RESET environment variable is set, all libacl functions
automatically perform one retry when a failure is caused by a SCSI Bus Device Reset of the
ACL.
RETURN V ALUES
Exit status codes are:
0 DST_SUCCESS.
-1 DST_FAILURE.
SEE ALSO
libacl_api_intro(3)
ACL.
Ampex 1308904-X4 Preliminary Draft 4-43
Page 76
Running Head
aclTUR ACL Application Programmer’s Guide
Model No.
4-44 Preliminary Draft Ampex 1308904-X4
Page 77
ACL Application Programmer’s Guide ACL Utilities
Section 5
ACL Utilities
5.1 Introduction
This section contains print versions of the manual pages for the A CL utilities. 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 A CL utilities, see the on-line manual pages installed on your
host system.
Ampex 1308904-X4 Preliminary Draft 5-1
Page 78
Running Head
acl_intro ACL Application Programmer’s Guide
Model No.
5.2 acl_intro
NAME
acl_intro - introduction to DST/DIS Automated Cartridge Library (ACL) Management
Utilities.
DESCRIPTION
The Ampe x DST/DIS Automated Cartridge Library (A CL) Management Utilities are a set of
programs that provide command-line access to an Ampex DST or DIS ACL. They provide
capabilities for:
• updating the ACL internal database and checking location status.
• checking or changing ACL configuration parameter settings.
• retrieving error/event logs, static logs, and SCSI sense data.
• getting vendor, product, software version, and software release information.
• controlling the ACL cartridge handling system (CHS).
• moving tape cartridges between locations.
• retrieving ACL operating status.
ACL Management Utilities are compatible with the DST/DIS Tape Management (DD-2)
Utilities. They are designed for use in scripts that perform higher-le vel operations, so the y use
a consistent set of input and output conventions that make them easy to link together.
APPLICABILITY
Unless otherwise noted, the information in the ACL Management Utilities manual pages
applies to all DST/DIS ACLs. Information unique to specific ACL models is identified by
series number.
Series Number ACL Model
2XX DIS 220i, DIS 260i, etc.
4XXDST 410, DST 412, etc.
8XXDST 810, DST 812, etc.
Writer_Note: What about aliases? Should we list them also?
5-2 Preliminary Draft Ampex 1308904-X4
Page 79
ACL Application Programmer’s Guide acl_intro
UTILITIES SUMMARY
Writer_Note: Need input for items flagged (TBS).
The A CL Management Utilities have descripti ve names that indicate both the type of operation
performed and the type of object upon which the operation is performed:
acl_audit_library Retrieve the status of all locations from the ACL internal
database.
acl_audit_element Retrieve the status of a single location from the ACL internal
database.
acl_errlog_library Retrieve ACL Error/Event Log parameters.
acl_getparam_library Get the current ACL configuration parameter settings.
acl_init_chs Update the status of all locations in the ACL internal database.
acl_move_tape Move a tape cartridge from one ACL location to another.
acl_move_volume
acl_park_chs Park the ACL cartridge handling system (2XX, 4XX).
acl_query_library Get ACL vendor, product, software version, and software
acl_setparam_library Change ACL configuration parameter settings.
acl_statlog_library Retrieve the ACL static log.
acl_status_library Get current ACL status information and SCSI sense data.
(TBS)
release information.
INPUT CONVENTIONS
The ACL Management Utilities use the following input conventions:
• All arguments or options are specified using explicit, descriptive command-line flags or
environment variables. Where applicable, the utilities use the same command-line flag
names and content.
Writer_Note: Please verify that separator characters are optional for single-element input
specifications.
• Some arguments consist of multiple-element input specifications. Every element in this
type of specification must be enclosed by colons or by the separator character you specify
using the -t option. (Separator characters are optional for a single-element input
specification.)
Ampex 1308904-X4 Preliminary Draft 5-3
Page 80
Running Head
acl_intro ACL Application Programmer’s Guide
For example, an argument such as -aclparam :1:::: uses colons as separators.
Separator characters must be present to reserve places for all elements, even if they are
empty.
Model No.
• You can specify integer input values using a standard decimal number, a hexadecimal
value (first two characters are 0x), or an octal value (the first character is a zero and the
second character is not an x).
OUTPUT CONVENTIONS
The ACL Management Utilities have the following output conventions:
• Many utilities support the -stdout <output_spec> argument which specifies the output
stream written to stdout. Each output field in the string is identified by a unique keyword
[%field_name or %(field_name)] that you can specify to display the field, or omit to skip
the field.
• All error and help messages are written to stderr.
• On success, all utilities return an exit status of zero. Utilities that support the
-stdout <output_spec> argument may also produce output to stdout.
• On failure, all utilities return a nonzero exit status. You can use the acl_status_library
utility to retrieve SCSI Sense Data that provides detailed information on the cause of the
failure.
ARGUMENTS
The arguments supported by more than one utility are described below. For other ar guments,
consult each utility’s manual page.
Writer_Note: Several Bug Reports in the DDTS refer to a v_revision keyword for the
-help <help_type> specification. If the keyword is an undocumented feature, we should
describe it here and list it on the appropriate manual pages.
-help [
help_type
Displays help on stderr and invalidates all other options, cancelling any other actions. The
optional help_type specification indicates the kind of help to supply:
]
• output - lists the keywords that are valid for the-stdout <output_spec> argument.
• revision - displays the utility revision number.
When -help is specified without the help_type argument, it displays the utility usage line.
5-4 Preliminary Draft Ampex 1308904-X4
Page 81
ACL Application Programmer’s Guide acl_intro
-stdout <
The -stdout <output_spec> argument specifies the output stream written to stdout. It is
required for all ACL Management Utilities that produce an output, unless you use the -help
argument.
The -stdout <output_spec> argument allows you to specify the following:
• Keywords [%field_name or %(field_name) as documented in the utility’s manual page]
• Characters that the command copies literally to the output stream. A backslash (\) in the
Keywords that start with v_ (%v_field_name) provide verbose output that displays a
descriptive string; all other keywords produce normal output that displays only the returned
value.
By default, the output stream contains a trailing newline. Use the -n option to suppress the
newline.
output_spec>
that designate the fields in the output stream written to stdout. When specifying more
than one keyword, enclose the entire argument in quotes and use spaces to separate the
field names.
output specification is not itself printed and causes the following character to be printed
literally , except for
a percent sign without having it interpreted as a keyword indicator.
\n which produces a ne wline. For e xample, you can use \% to print
On output, the command formats the output values by stripping any leading zeroes from
numbers and any trailing spaces from strings. Tape cartridge barcode IDs (volume tags) are
considered to be strings.
OPTIONS
The options supported by more than one utility are described below . For other options, consult
each utility’s manual page.
-device <
Specifies the device special file to use for the operation. If omitted, the device special file
specified by the $ACL_DEV en vironment v ariable is used. There is no default if $A CL_DEV
is not defined.
-n
Prevents a trailing newline from being appended to the output stream. If omitted, the output
stream includes a trailing newline.
-n does not affect newlines embedded in the output stream.
-n is valid for all commands that output to stdout.
device_special_file>
Ampex 1308904-X4 Preliminary Draft 5-5
Page 82
Running Head
acl_intro ACL Application Programmer’s Guide
-t <
separator>
Specifies the separator character that encloses each element in a multi-element input field. If
omitted, colons are used as the separator characters. Valid for all commands that take
multi-element lists as input.
-retry_on_reset
Specifies that the utility perform one retry automatically when a failure is caused by a SCSI
Bus Device Reset of the ACL. There are no arguments to this option. Any arguments listed
after the option cause the utility to fail.
If the -retry_on_reset option is omitted, the $RETR Y_ON_RESET en vironment variable can
be used to enable retries after resets. If the -retry_on_reset option and the
$RETRY_ON_RESET environment variable are both omitted, the utility will not retry
automatically after a SCSI Bus Device Reset of the ACL. This is the default.
Model No.
ACL LOCATIONS
Names are assigned to all ACL locations that can contain a tape cartridge. ACL Management
utilities recognize the location names described below.
2XX and 4XX ACLs can move a tape cartridge from a storage bin to the tape drive, or from
the tape drive to a storage bin
8XX ACLs can move a tape cartridge to or from any of the named locations (tape drive,
storage bin, IMEX bin, or CHS)
ACL Series 2XX and 4XX
Tape Drive The ACL has one tape drive named DR1.
Cartridge Handling System The ACL cartridge handling system is named CHS.
Storage BIn The ACL contains seven storage bins named A01 through A07
ACL Series 8XX
Tape Drive(s) The ACL can contain up to four tape drives. The drives are
Cartridge Handling System The ACL cartridge handling system is named CHS.
(from top to bottom).
named DR4 through DR1 (from top to bottom).
Storage BIns The ACL contains 248 storage bins. The bins are arranged in an
8-column by 32-row matrix (which also contains eight
import/export bins). The rows are numbered 01 through 32 from
top to bottom and the columns are alphabetized A through H
from left to right.
5-6 Preliminary Draft Ampex 1308904-X4
Page 83
ACL Application Programmer’s Guide acl_intro
The storage bin names correspond to the locations they occupy:
A01-A32, B01-B32, C01-C32, D01-D32, E01-E32, F01-F32,
G01-G32, H01-H06, and H15-H32.
IMEX bins The eight IMEX bins provide operator access for insertion and
removal of tape cartridges. They are named H07-H14,
corresponding to the locations they occupy.
ENVIRONMENT
The ACL management utilities use the following environment variables. Command-line
options always override any environment variables.
$ACL_DEV
Specifies the device special file to use when you omit the -device <device_special_file>
option.
$RETRY_ON_RESET
Specifies that the A CL management utilities perform one retry automatically when a failure is
caused by a SCSI Bus Device Reset of the ACL. When $RETRY_ON_RESET is not set, an
ACL management utility will perform a retry automatically only if the -r etry_on_reset option
is specified on the command line.
EXIT STATUS
The ACL management utilities use the following exit status codes, and may also produce
output to -stdout on success:
0 Operation successful.
nonzero Operation failed.
SEE ALSO
libacl_intro_api(3), dd2_intro(1), dst_api_Intro(3)
DST/DIS Automated Cartridge Library Application Programming Interface (libacl)
Programmer’s Guide
Ampex 1308904-X4 Preliminary Draft 5-7
Page 84
Running Head
acl_audit_library ACL Application Programmer’s Guide
Model No.
5.3 acl_audit_library
NAME
acl_audit_library - retrieve the status of all locations from the ACL internal database.
SYNOPSIS
acl_audit_library -stdout <output_spec> [ -device device_special_file ] [ -n ]
[ -retry_on_reset ]
acl_audit_library -help [ help_type ]
DESCRIPTION
acl_audit_library reports current status of all ACL locations. The -stdout <output_spec>
argument specifies the fields written to stdout. These can include location name, type,
contents (including barcode ID when available), access status, and exception status.
acl_audit_library is available to all users. See the acl_intro(1) manual page for A CL naming
conventions and general information on command-line options and arguments.
OPTIONS
-device
-n
-retry_on_reset
device_special_file
Specifies the device special file to use for the operation.
Prevents the utility from appending a trailing newline to the output stream written to stdout,
but does not affect newlines embedded in the output stream.
Specifies that the utility perform one retry automatically when a failure is caused by a SCSI
Bus Device Reset of the ACL.
ARGUMENTS
-help [
help_type
]
Displays help on stderr and invalidates all other options, cancelling any other actions. Valid
keywords for the optional help_type specification are:
5-8 Preliminary Draft Ampex 1308904-X4
output and revision.
Page 85
ACL Application Programmer’s Guide acl_audit_library
-stdout <
Specifies the output fields written to stdout. You must provide a -stdout <output_spec>
argument for this utility (except when using the -help argument).
The -stdout <output_spec> argument supports the following keywords:
%access Prints the access status of the location:
%barcode Prints the contents of the location:
output_spec>
+ Plus (+) indicates that the ACL can transfer a tape cartridge to or
from the location.
- Minus (-) indicates that the A CL cannot transfer a tape cartridge to
or from the location.
+ Plus (+) indicates that the location contains a tape cartridge, but
the barcode ID is unknown.
- Minus (-) indicates that the location does not contain a tape
cartridge.
bar_code - six-digit barcode ID of the tape cartridge in the location
(when available).
%exception Prints the exception status of the location:
%locname Prints the location name.
%loctype Prints the location type:
ENVIRONMENT
The ACL management utilities use the following environment variables. Command-line
options always override any environment variables.
$ACL_DEV
Specifies the device special file to use when you omit the -device option.
+ Plus (+) indicates an abnormal or unknown state.
- Minus (-) indicates a normal state.
bin - storage bin.
chs - cartridge handling system.
drive - tape drive.
imex - import/export bin.
Ampex 1308904-X4 Preliminary Draft 5-9
Page 86
Running Head
acl_audit_library ACL Application Programmer’s Guide
$RETRY_ON_RESET
Specifies that the A CL management utilities perform one retry automatically when a failure is
caused by a SCSI Bus Device Reset of the ACL. When $RETRY_ON_RESET is not set, an
ACL management utility will perform a retry automatically only if the -r etry_on_reset option
is specified on the command line.
Model No.
EXIT STATUS
The ACL management utilities use the following exit status codes:
0 Operation successful.
nonzero Operation failed.
EXAMPLES
1. Print the contents of all the drives in the ACL.
2. Print a one-line list of every location name and barcode ID.
SEE ALSO
acl_intro(1), acl_audit_element(1), aclAuditLibrary(3)
DST/DIS Automated Cartridge Library Application Programming Interface (libacl)
Programmers Guide
acl_audit_library -stdout "%locname %barcode" | grep DR
For an 8XX ACL, the above example might produce output like this:
DR0 000025
DR1 000403
DR2 000027
DR3 000318
acl_audit_library -stdout "%locname:%barcode " -n ; echo ""
For a 2XX or 4XX ACL, the above example might produce output like this:
CHS:- DR01:+ A01:+ A02:- A03:+ A04:001234 A05:010235 A06:+ A07:+
5-10 Preliminary Draft Ampex 1308904-X4
Page 87
ACL Application Programmer’s Guide acl_audit_element
5.4 acl_audit_element
NAME
acl_audit_element - retrieve the status of a single location from the ACL internal database.
SYNOPSIS
acl_audit_element -element <element_location> -stdout <output_spec>
[ -device device_special_file ] [ -n ] [ -retry_on_reset ]
acl_audit_element -help [ help_type ]
DESCRIPTION
acl_audit_element reports the status of the ACL location specified by the
-element <element_location> argument. The -stdout <output_spec> argument specifies the
output fields written to stdout. These can include location name, type, contents (including
barcode ID when available), access status, and exception status.
acl_audit_element is available to all users. See the acl_intro(1) manual page for ACL
naming conventions and general information on command-line options and arguments.
OPTIONS
-device
-n
-retry_on_reset
device_special_file
Specifies the device special file to use for the operation.
Prevents the utility from appending a trailing newline to the output stream written to stdout,
but does not affect newlines embedded in the output stream.
Specifies that the utility perform one retry automatically when a failure is caused by a SCSI
Bus Device Reset of the ACL.
ARGUMENTS
-help [
help_type
]
Displays help on stderr and invalidates all other options, cancelling any other actions. Valid
keywords for the optional help_type specification are:
Ampex 1308904-X4 Preliminary Draft 5-11
output and revision.
Page 88
Running Head
acl_audit_element ACL Application Programmer’s Guide
Model No.
-element <
Specifies the name of the location for which you want to retrieve status. You must provide
-element <element_location> and -stdout <output_spec> arguments for this utility (except
when using the -help argument).
-stdout <
Specifies the output fields written to stdout. You must provide -stdout <output_spec> and
-element <element_location> arguments for this utility (except when using the -help
argument).
The -stdout <output_spec> argument supports the following keywords for status reporting:
%access Prints the access status of the location:
%barcode Prints the contents of the location:
element_location>
output_spec>
+ Plus (+) indicates that the ACL can transfer a tape cartridge to or
from the location.
- Minus (-) indicates that the A CL cannot transfer a tape cartridge to
or from the location.
%exception Prints the exception status of the location:
%locname Prints the location name.
%loctype Prints the location type:
ENVIRONMENT
The ACL management utilities use the following environment variables. Command-line
options always override any environment variables.
+ Plus (+) indicates that the location contains a tape cartridge, but
the barcode ID is unknown.
- Minus (-) indicates that the location does not contain a tape
cartridge.
bar_code - six-digit barcode ID of the tape cartridge in the location
(when available).
+ Plus (+) indicates an abnormal or unknown state.
- Minus (-) indicates a normal state.
bin - storage bin.
chs - cartridge handling system.
drive - tape drive.
imex - import/export bin.
5-12 Preliminary Draft Ampex 1308904-X4
Page 89
ACL Application Programmer’s Guide acl_audit_element
$ACL_DEV
Specifies the device special file to use when you omit the -device option.
$RETRY_ON_RESET
Specifies that the A CL management utilities perform one retry automatically when a failure is
caused by a SCSI Bus Device Reset of the ACL. When $RETRY_ON_RESET is not set, an
ACL management utility will perform a retry automatically only if the -r etry_on_reset option
is specified on the command line.
EXIT STATUS
The ACL management utilities use the following exit status codes:
0 Operation successful.
nonzero Operation failed.
Writer_Note: Changed the description to match the example.
EXAMPLE
Print the contents of storage bin A01.
The above example might produce output like this:
SEE ALSO
acl_intro(1), acl_audit_library(1), aclAuditElement(3)
DST/DIS Automated Cartridge Library Application Programming Interface (libacl)
Programmers Guide
acl_audit_element -element A01 -stdout "locname: %locname
barcode: %barcode"
locname: A01 barcode: 000025
Ampex 1308904-X4 Preliminary Draft 5-13
Page 90
Running Head
acl_errlog_library ACL Application Programmer’s Guide
Model No.
5.5 acl_errlog_library
Writer_Note: Bug RWCra 01707 states “I don’t think this utility works.” Also, are separator
characters (colons) required for the single argument to count?
NAME
acl_errlog_library - retrieve ACL Error/Event Log parameters.
SYNOPSIS
acl_errlog_library -count <count_specification> -stdout <output_spec>
[ -device device_special_file ] [ -n ] [ -t separator ] [ -retry_on_reset ]
acl_errlog_library -help [ help_type ]
Writer_Note: Changed 2048 parameters to 1000 parameters to agree with current r elease of the ACL
SCSI ICD.
DESCRIPTION
acl_errlog_library retrieves up to 1000 parameters from the ACL error/event log, starting
with the most recent entry . This information is intended to aid service personnel in diagnosing
and correcting problems.
The -stdout <output_spec> argument is required to write the error/event log parameters to
stdout. The -count <count_specification> argument specifies the number of parameters to
retrieve.
acl_errlog_library is available to all users. See the acl_intro(1) manual page for ACL
naming conventions and general information on command-line options and arguments.
OPTIONS
-device
-n
device_special_file
Specifies the device special file to use for the operation.
Prevents the utility from appending a trailing newline to the output stream written to stdout,
but does not affect newlines embedded in the output stream.
Writer_Note: At our meeting, we said the separator character would be optional for a single entry.
Has this change been implemented?
5-14 Preliminary Draft Ampex 1308904-X4
Page 91
ACL Application Programmer’s Guide acl_errlog_library
-t <
separator>
Specifies the optional separator characters that enclose the value specified for the
-count <count_specification> argument. If omitted, colons are used as the separator
characters.
Separator characters are not required for the -count <count_specification> argument but you
can them if desired (for compatibility with existing applications).
-retry_on_reset
Specifies that the utility perform one retry automatically when a failure is caused by a SCSI
Bus Device Reset of the ACL.
ARGUMENTS
-help [
Writer_Note: I changed 2048 to 1000 to agree with ACL SCSI ICD.
-count
-stdout
help_type
Displays help on stderr and invalidates all other options, cancelling any other actions. Valid
keywords for the optional help_type specification are:
]
output and revision.
<count_specification>
Specifies the number of parameters to retrieve from the ACL error/event log. The maximum
value is 1000. The most recent parameters are displayed first.
You must provide -count <count_specification> and -stdout <output_spec> arguments for
this utility (except when using the -help argument).
<output_spec>
Specifies the output stream written to stdout. Y ou must pro vide -count <count_specification>
and -stdout <output_spec> arguments for this utility (except when using the -help argument).
The -stdout <output_spec> argument supports the following keyword:
ENVIRONMENT
%elog.
The ACL management utilities use the following environment variables. Command-line
options always override any environment variables.
$ACL_DEV
Specifies the device special file to use when you omit the -device option.
Ampex 1308904-X4 Preliminary Draft 5-15
Page 92
Running Head
acl_errlog_library ACL Application Programmer’s Guide
$RETRY_ON_RESET
Specifies that the A CL management utilities perform one retry automatically when a failure is
caused by a SCSI Bus Device Reset of the ACL. When $RETRY_ON_RESET is not set, an
ACL management utility will perform a retry automatically only if the -r etry_on_reset option
is specified on the command line.
Model No.
EXIT STATUS
The ACL management utilities use the following exit status codes:
0 Operation successful.
nonzero Operation failed.
Writer_Note: If possible, we should show what the output looks like. The only place we describe the
format of the error/event parameters is in the SCSI ICD.
EXAMPLES
Print the 10 most recent error/event log entries.
SEE ALSO
acl_intro(1), aclGetErrorLog(3)
DST/DIS Automated Cartridge Library Application Programming Interface (libacl)
Programmers Guide
acl_errlog_library -count :10: -stdout %elog
5-16 Preliminary Draft Ampex 1308904-X4
Page 93
ACL Application Programmer’s Guide acl_getparam_library
5.6 acl_getparam_library
NAME
acl_getparam_library - get the current ACL configuration parameter settings.
SYNOPSIS
acl_getparam_library -stdout <output_spec> [ -device device_special_file ] [ -n ]
[ -retry_on_reset ]
acl_getparam_library -help [ help_type ]
DESCRIPTION
acl_getparam_library returns information about the current ACL configuration parameter
settings. The -stdout <output_spec> argument specifies the output fields written to stdout. T o
change a configuration parameter setting, use the acl_setparam_library utility.
acl_getparam_library is available to all users. See the acl_intro(1) manual page for ACL
naming conventions and general information on command-line options and arguments.
OPTIONS
-device
-n
-retry_on_reset
device_special_file
Specifies the device special file to use for the operation.
Prevents the utility from appending a trailing newline to the output stream written to stdout,
but does not affect newlines embedded in the output stream.
Specifies that the utility perform one retry automatically when a failure is caused by a SCSI
Bus Device Reset of the ACL.
ARGUMENTS
-help [
help_type
]
Displays help on stderr and invalidates all other options, cancelling any other actions. Valid
keywords for the optional help_type specification are:
Ampex 1308904-X4 Preliminary Draft 5-17
output and revision.
Page 94
Running Head
acl_getparam_library ACL Application Programmer’s Guide
Writer_Note: Please verify that this utility supports verbose keywords and, if so, that the syntax is
correct. I added the %v_* keywords to support the original -stdout description, and
changed %req_barcod to %barcode_enable as specified in Bug RWCra01713.
Model No.
-stdout <
Writer_Note: Auto Eject was changed to Auto Store Enable in the ACL SCSI ID.
output_spec>
Specifies the output fields written to stdout. You must provide a -stdout <output_spec>
argument for this utility (except when using the -help argument).
The -stdout option supports the keywords listed below. Each field can print in verbose or
non-verbose style, depending on the keyword specified. Non-verbose style prints only the
returned value; verbose style replaces the returned value with a descriptive string. If the data
for a particular keyword is not available
keyword.
%auto_eject Prints the current setting of the Auto Store Enable
%v_auto_eject configuration parameter:
1 or Enabled indicates that the parameter is set to on.
0 or Disabled Indicates that the parameter is set to off.
When the Auto Store Enable configuration parameter is set to
off, the initiator must use the acl_move_tape or
acl_move_volume utility to remove a tape cartridge from the
tape drive (after the dri ve ejects the tape cartridge in response to
a tape drive Unload command).
, na prints instead of the value (or string) for that
When the Auto Store Enable configuration parameter is set to
on, the ACL automatically returns any tape cartridge ejected by
the tape drive to the location from which it was loaded (or , if this
is unknown, to an empty storage bin).
%auto_audit_override Prints the current setting of the Auto Audit Override
%v_auto_audit_override configuration parameter:
1 or Enabled indicates that the parameter is set to on.
0 or Disabled Indicates that the parameter is set to off.
The ACL has an internal database which it keeps up to date.
When powered on with a tape cartridge in the drive, however,
the ACL cannot read the barcode ID of that cartridge until it is
unloaded from the drive.
When the Auto Audit Override configuration parameter is set to
off, the A CL automatically executes a barcode read when it does
not have a barcode ID stored for the tape cartridge it unloads
from the drive. When the Auto Audit Override parameter is set
to on, this functionality is suppressed.
%req_barcod Prints the current setting of the Barcode Required Enable
5-18 Preliminary Draft Ampex 1308904-X4
Page 95
ACL Application Programmer’s Guide acl_getparam_library
%v_req_barcod configuration parameter:
1 or Enabled indicates that the parameter is set to on.
0 or Disabled Indicates that the parameter is set to off.
When the Barcode Required Enable configuration parameter is
set to on, the ACL will not accept a tape cartridge that does not
have a readable barcode ID; i.e., the ACL will not transfer the
cartridge to a drive (2XX, 4XX) or from an IMEX bin (8XX).
When the parameter is set to off, the ACL accepts all tape
cartridges without regard to barcode ID.
Writer_Note: Bug RWCra 01712 erroneously states “‘%v_auto_import’ is not supported”.
%auto_import Prints the current setting of the Auto Import Enable
%v_auto_import configuration parameter (8XX):
1 or Enabled indicates that the parameter is set to on.
0 or Disabled indicates that the parameter is set to off.
The ACL detects the presence of a tape cartridge when it is
inserted into an IMEX bin. When the Auto Import Enable
configuration parameter is set to on, the ACL automatically
transfers the cartridge to the next available storage bin.
ENVIRONMENT
The ACL management utilities use the following environment variables. Command-line
options always override any environment variables.
$ACL_DEV
Specifies the device special file to use when you omit the -device option.
$RETRY_ON_RESET
Specifies that the A CL management utilities perform one retry automatically when a failure is
caused by a SCSI Bus Device Reset of the ACL. When $RETRY_ON_RESET is not set, an
ACL management utility will perform a retry automatically only if the -r etry_on_reset option
is specified on the command line.
EXIT STATUS
When the Auto Import Enable configuration parameter is set to
off, this functionality is suppressed and the initiator must use the
acl_move_tape or acl_move_volume utility to transfer the tape
cartridge to a storage bin (or tape drive).
The ACL management utilities use the following exit status codes:
Ampex 1308904-X4 Preliminary Draft 5-19
Page 96
Running Head
acl_getparam_library ACL Application Programmer’s Guide
0 Operation successful.
nonzero Operation failed.
Writer_Note: We should show a typical output for the example.
Model No.
EXAMPLES
Print the current settings of all configuration parameters in verbose style.
acl_getparam_library -stdout "%v_auto_eject %v_auto_import
%v_auto_audit_override %v_req_barcode"
SEE ALSO
acl_intro(1), acl_setparam_libarary(1), aclGetparam(3)
DST/DIS Automated Cartridge Library Application Programming Interface (libacl)
Programmers Guide
5-20 Preliminary Draft Ampex 1308904-X4
Page 97
ACL Application Programmer’s Guide acl_init_chs
5.7 acl_init_chs
NAME
acl_init_chs - update the status of all locations in the ACL internal database.
SYNOPSIS
acl_init_chs [ -device device_special_file ] [ -retry_on_reset ]
acl_init_chs -help [ help_type ]
DESCRIPTION
acl_init_chs directs the cartridge handling system (CHS) to audit the contents of all locations
in the ACL and update their status in the ACL internal database. Use of this utility is optional
since the ACL automatically performs an initialization routine whenever it detects any
condition that could cause a change in status.
acl_init_chs is available to all users.
OPTIONS
-device
-retry_on_reset
device_special_file
Specifies the device special file to use for the operation.
Specifies that the utility perform one retry automatically when a failure is caused by a SCSI
Bus Device Reset of the ACL.
ARGUMENTS
-help [
help_type
Displays help on stderr and invalidates all other options, cancelling any other actions. Valid
keywords for the optional help_type specification are:
ENVIRONMENT
]
output and revision.
The ACL management utilities use the following environment variables. Command-line
options always override any environment variables.
Ampex 1308904-X4 Preliminary Draft 5-21
Page 98
Running Head
acl_init_chs ACL Application Programmer’s Guide
$ACL_DEV
Specifies the device special file to use when you omit the -device option.
$RETRY_ON_RESET
Specifies that the A CL management utilities perform one retry automatically when a failure is
caused by a SCSI Bus Device Reset of the ACL. When $RETRY_ON_RESET is not set, an
ACL management utility will perform a retry automatically only if the -r etry_on_reset option
is specified on the command line.
Model No.
EXIT STATUS
The ACL management utilities use the following exit status codes:
0 Operation successful.
nonzero Operation failed.
SEE ALSO
acl_intro(1), aclInit(3)
DST/DIS Automated Cartridge Library Application Programming Interface (libacl)
Programmers Guide
5-22 Preliminary Draft Ampex 1308904-X4
Page 99
ACL Application Programmer’s Guide acl_move_tape
5.8 acl_move_tape
NAME
acl_move_tape - move a tape cartridge from one ACL location to another.
SYNOPSIS
acl_move_tape -sourcelocation <location> -targetlocation <location>
[ -device device_special_file ] [ -retry_on_reset ]
acl_move_tape -help [ help_type ]
DESCRIPTION
acl_move_tape moves a tape cartridge from the specified source location to the specified
destination location. It fails if the source location is empty, the destination location is full, an
invalid source or destination is specified, or a cabinet door is open.
2XX and 4XX ACLs can only move a tape cartridge from a storage bin to the tape drive, or
from the tape drive to a storage bin. 8XX ACLs can move a tape cartridge to or from any of
the named locations (tape drive, storage bin, IMEX bin, or CHS).
When the source location is a drive, the tape cartridge to be mov ed must already be located in
the drive load port; that is, the dri ve must hav e already ejected the cartridge. To force the dri ve
to eject the tape cartridge, issue a dst_unload_tape(1) command before issuing the
acl_move_tape command
acl_move_tape is available to all users. See the acl_intro(1) manual page for ACL naming
conventions and general information on command-line options and arguments.
OPTIONS
-device
Specifies the device special file to use for the operation.
-retry_on_reset
Specifies that the utility perform one retry automatically when a failure is caused by a SCSI
Bus Device Reset of the ACL.
device_special_file
ARGUMENTS
Writer_Note: Bug RWCra01725 states “How would a user know about '-help v_revision'??? It does
not seem to show up in the usage stuff.” Should we cover this in the man page?
Ampex 1308904-X4 Preliminary Draft 5-23
Page 100
Running Head
acl_move_tape ACL Application Programmer’s Guide
Model No.
-help [
-sourcelocation <
-targetlocation <
help_type
Displays help on stderr and invalidates all other options, cancelling any other actions. Valid
keywords for the optional help_type specification are:
Specifies the name of the A CL location from which the tape cartridge is to be moved. Y ou must
use uppercase letters exactly as shown in the acl_intro(1) manual page.
Specifies the name of the ACL location to which the tape cartridge is to be moved. You must
use uppercase letters exactly as shown in the acl_intro(1) manual page.
ENVIRONMENT
The ACL management utilities use the following environment variables. Command-line
options always override any environment variables.
$ACL_DEV
Specifies the device special file to use when you omit the -device option.
]
output and revision.
location>
location>
$RETRY_ON_RESET
Specifies that the A CL management utilities perform one retry automatically when a failure is
caused by a SCSI Bus Device Reset of the ACL. When $RETRY_ON_RESET is not set, an
ACL management utility will perform a retry automatically only if the -r etry_on_reset option
is specified on the command line.
EXIT STATUS
The ACL management utilities use the following exit status codes:
0 Operation successful.
nonzero Operation failed.
5-24 Preliminary Draft Ampex 1308904-X4
Loading...