DST/DIS Automated Cartridge Library UNIX Application Programmer’s Guide ® 1308904-X4 ™
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.
ACL Application Programmer’s Guide Contents Contents Section 1 General Information 1.1 1.2 1.3 1.4 1.5 1.6 1.7 1.8 1.9 Section 2 ACL Software Overview 2.1 2.2 2.3 2.4 2.4.1 2.4.2 2.4.3 2.4.4 2.4.5 2.4.6 2.4.7 2.5 2.5.1 2.5.2 2.5.3 2.5.4 2.5.5 Ampex 1308904-X4 Introduction ....................................................................................................1-1 Supported UNIX Operating Systems .............................................................1-1 Manual Contents ..............
Model ACL Application Programmer’s GuideNo. Running Head Contents Section 3 ACL Operational Characteristics 3.1 3.2 3.3 3.3.1 3.3.2 3.3.3 3.3.4 3.3.5 3.3.6 3.3.7 3.4 3.4.1 3.4.2 3.5 3.6 3.7 3.7.1 3.7.2 3.7.3 3.7.4 3.7.5 Section 4 libacl API Functions 4.1 4.2 4.3 4.4 4.5 4.6 4.7 4.8 4.9 4.10 4.11 4.12 4.13 4.14 4.15 4.16 4.17 4.18 iv Introduction .................................................................................................... 3-1 SCSI Commands ....................................
ACL Application Programmer’s Guide 4.19 4.20 4.21 4.22 Section 5 Introduction ....................................................................................................5-1 acl_intro ..........................................................................................................5-2 acl_audit_library .............................................................................................5-8 acl_audit_element ..........................................................................
Model ACL Application Programmer’s GuideNo. Running Head Tables Tables 2-1 3-1 3-2 A-1 A-2 A-3 A-4 A-5 vi ACL Operations ................................................................................................................ 2-1 SCSI Address Assignments for 8XX ACL Storage and IMEX Elements ......................... 3-4 ACL Behavior Parameter Descriptions .............................................................................. 3-8 Error/Event Parameter Identification Code Descriptions....
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 libacl Application Programming Interface (API). The ACL Management Utilities are a set of programs that provide command-line access to an Ampex DST or DIS ACL.
Model ACL Application Programmer’s GuideNo. Running Head Manual Contents 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). 1.3 1.
ACL Application Programmer’s Guide Notices and Notes Fixed 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. Fixed Bold In an example, indicates text typed by the operator. Note: In C function prototypes and examples, the special characters above ([ ] | { }) retain their normal meaning in the C language.
Model ACL Application Programmer’s GuideNo. Running Head Related Documents 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.
ACL Application Programmer’s Guide 1.7 Training Services 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.
Model ACL Application Programmer’s GuideNo.
ACL Application Programmer’s Guide ACL Software Overview Section 2 ACL Software Overview 2.1 Introduction This section provides a general overview of the host system device driver interface, the libacl API functions, and the ACL Management Utilities. Table 2-1 shows the ACL operations performed by the libacl functions and the Management Utilities. 2.
Model ACL Application Programmer’s GuideNo. Running Head Native Device Drivers Table 2-1. ACL Operations Operation libacl API Function ACL Utility Usage Get configuration parameter settings. aclGetParam() acl_getparam_library See “Configuration Parameters” on page 3-7. Retrieve the static Log aclGetStaticLog() acl_statlog_library See “Internal Logs” on page 3-13. Get product and version information. aclGetVersion() acl_query_library See “Product Information” on page 3-7.
ACL Application Programmer’s Guide 2.4 libacl API Overview 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 the libami.cf configuration file. The libacl API features include: • Simple, compact, and direct functions to control or obtain data from an ACL.
Model ACL Application Programmer’s GuideNo. Running Head libacl API Overview 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 ACL device driver has set the external variable errno to indicate the type of error that occurred. In other words, a call returns -1 on failure. For convenience, the acl.
ACL Application Programmer’s Guide 2.4.7 ACL Utilities Overview 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.
Model ACL Application Programmer’s GuideNo. Running Head ACL Utilities Overview EBUSY EINVAL ENODEV ENXIO EPERM ETIME 2.5.5 ACL is already in use. Invalid argument supplied. The ACL device is not properly connected to the host system. Device does not exist. Access denied due to device special file permissions. A timeout occurred on a SCSI command. Restrictions None; the ACL utilities are available to all users.
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.
Model ACL Application Programmer’s GuideNo. Running Head ACL Configuration 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 ACL utilities use the location name.
ACL Application Programmer’s Guide ACL Configuration Storage 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. Import/Export Element 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.
Model ACL Application Programmer’s GuideNo. Running Head ACL Configuration Table 3-1.
ACL Application Programmer’s Guide ACL Configuration Table 3-1.
Model ACL Application Programmer’s GuideNo. Running Head ACL Configuration 3.3.2 Barcode Reader The ACL 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.
ACL Application Programmer’s Guide 3.3.4 ACL Configuration 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.
Model ACL Application Programmer’s GuideNo. Running Head ACL Configuration Table 3-2. ACL Behavior Parameter Descriptions Parameter Auto Store Enable State 0 (off)* 1 (on) 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).
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.
Model ACL Application Programmer’s GuideNo. Running HeadMovement Tape Cartridge 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.
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.
Model ACL Application Programmer’s GuideNo.
ACL Application Programmer’s Guide 3.7.4 Operational Status 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). 3.7.5 • aclGetErrorLog() and acl_errlog_library retrieve entries from the error/event log.
Model ACL Application Programmer’s GuideNo. Running Head Operational Status 3-14 – Failure Code Vendor-specific failure code (see Table A-5); sent by ACL when the CHS is unable to complete a SCSI command. – Warning Code Vendor-specific warning code (see Table A-5); sent by ACL when the CHS completes a command but detects a problem. – Error Code Vendor-specific error code (see Table A-5); sent by ACL when the CHS does not attempt to execute a SCSI command.
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.
Model ACL Application Programmer’s GuideNo. Running Head libacl_intro_api 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 Application Programmer’s Guide libacl_intro_api int aclStatus(TBS); int aclTUR(char *device); DESCRIPTION The Ampex DST/DIS SCSI Automated Cartridge Library libacl C-Library functions comprise an application programming interface that provides access to the ACL device 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.
Model ACL Application Programmer’s GuideNo. Running Head libacl_intro_api 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.
ACL Application Programmer’s Guide libacl_intro_api ACL ELEMENTS SCSI addresses are assigned to all ACL elements (locations) that can contain a tape cartridge. libacl API functions recognize the addressable locations described below.
Model ACL Application Programmer’s GuideNo. Running Head libacl_intro_api 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 VALUES All libacl functions return status codes on exit. See the manual pages for descriptions.
ACL Application Programmer’s Guide 4.3 aclGeneric aclGeneric NAME aclGeneric() - generic SCSI command interface. SYNOPSIS #include 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 provide an equivalent function for the desired SCSI command. If desired, you can also use aclGeneric() to issue SCSI commands to a non-Ampex SCSI device.
Model ACL Application Programmer’s GuideNo.
ACL Application Programmer’s Guide 4.4 aclAuditLibrary aclAuditLibrary NAME aclAuditLibrary() - retrieve the status of all elements from the ACL internal database. SYNOPSIS #include 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.
Model ACL Application Programmer’s GuideNo. Running Head aclAuditLibrary int int unsigned short char pos; door; sea; 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 only). ACL_DRIVE - Data Transfer Element (Tape Drive).
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 ACL 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.
Model ACL Application Programmer’s GuideNo. Running Head aclAuditElement 4.5 aclAuditElement NAME aclAuditElement() - retrieve the status of a single element from the ACL internal database. SYNOPSIS #include 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.
ACL Application Programmer’s Guide aclAuditElement sea; /* assign element address here */ vtag[33]; unsigned short char } 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).
Model ACL Application Programmer’s GuideNo. Running Head aclAuditElement 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).
ACL Application Programmer’s Guide 4.6 aclGetElemData aclGetElemData NAME aclGetElemData() - get element count and SCSI addresses. SYNOPSIS #include 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.
Model ACL Application Programmer’s GuideNo. Running Head aclGetElemData 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 VALUES Exit status codes are: 0 DST_SUCCESS. -1 DST_FAILURE.
ACL Application Programmer’s Guide 4.
Model ACL Application Programmer’s GuideNo. Running Head aclGetParam 4.8 aclGetParam NAME aclGetParam() - get the current ACL configuration parameter settings. SYNOPSIS #include 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.
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).
Model ACL Application Programmer’s GuideNo. Running Head aclGetParam When the Auto Import Enable configuration parameter is set to off, 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.
ACL Application Programmer’s Guide 4.
Model ACL Application Programmer’s GuideNo. Running Head aclGetVersion 4.10 aclGetVersion NAME aclGetVersion() - get ACL vendor, product, software version, and software release information. SYNOPSIS #include 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.
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.
Model ACL Application Programmer’s GuideNo. Running Head aclInit 4.11 aclInit NAME aclInit() - update element status in the ACL internal database. SYNOPSIS #include 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.
ACL Application Programmer’s Guide 4.12 aclMoveCartridge aclMoveCartridge NAME aclMoveCartridge() - move a tape cartridge from one ACL location to another. SYNOPSIS #include 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.
Model ACL Application Programmer’s GuideNo. Running Head aclMoveCartridge 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 VALUES Exit status codes are: 0 DST_SUCCESS. -1 DST_FAILURE.
ACL Application Programmer’s Guide 4.13 aclMoveVolume aclMoveVolume NAME aclMoveVolume() - move the specified tape cartridge to another ACL location. SYNOPSIS #include int aclMoveVolume(char *device, char *barcode, unsigned int dea); DESCRIPTION aclMoveVolume() moves 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.
Model ACL Application Programmer’s GuideNo. Running Head aclMoveVolume 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. 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 VALUES Exit status codes are: 0 DST_SUCCESS. -1 DST_FAILURE.
ACL Application Programmer’s Guide 4.14 aclPark aclPark NAME aclPark() - park the ACL cartridge handling system (2XX, 4XX). SYNOPSIS #include 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.
Model ACL Application Programmer’s GuideNo.
ACL Application Programmer’s Guide 4.15 aclPosition 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 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.
Model ACL Application Programmer’s GuideNo. Running Head aclPosition RETURN VALUES Exit status codes are: 0 DST_SUCCESS. -1 DST_FAILURE.
ACL Application Programmer’s Guide 4.16 aclRelease aclRelease NAME aclRelease() - release a previously reserved ACL so that another SCSI initiator can use it. SYNOPSIS #include 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 exclusive access to the ACL when it is connected to multiple initiators.
Model ACL Application Programmer’s GuideNo. Running Head aclRelease RETURN VALUES Exit status codes are: 0 DST_SUCCESS. -1 DST_FAILURE.
ACL Application Programmer’s Guide 4.
Model ACL Application Programmer’s GuideNo. Running Head aclReqSense 4.18 aclReqSense NAME aclReqSense() - retrieve ACL SCSI sense data. SYNOPSIS #include 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.
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 VALUES Exit status codes are: 0 DST_SUCCESS. -1 DST_FAILURE.
Model ACL Application Programmer’s GuideNo. Running Head aclRezero 4.19 aclRezero NAME aclRezero() - reset the ACL and ensure that element status is current in the internal database. SYNOPSIS #include 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.
ACL Application Programmer’s Guide 4.20 aclSetParam aclSetParam NAME aclSetParam() - change ACL configuration parameter(s). SYNOPSIS #include 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.
Model ACL Application Programmer’s GuideNo. Running Head aclSetParam unsigned char AutoAuditOverride; unsigned char BarcodeReqEnable; unsigned char AutoImport; }aclParam_t; STRUCTURE MEMBERS AutoEject Sets the Auto Store Enable configuration parameter to on (1) or off (0, default).
ACL Application Programmer’s Guide AutoImport aclSetParam 8XX – Sets the Auto Import Enable configuration parameter to on (1) or off (0, default). 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 tape cartridge to the next available Storage Element, starting from address 1000.
Model ACL Application Programmer’s GuideNo. Running Head aclStatus 4.
ACL Application Programmer’s Guide 4.22 aclTUR aclTUR NAME aclTUR() - check that the ACL is ready to accept commands. SYNOPSIS #include 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 ACL.
Model ACL Application Programmer’s GuideNo.
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 ACL 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 ACL utilities, see the on-line manual pages installed on your host system.
Model ACL Application Programmer’s GuideNo. Running Head acl_intro 5.2 acl_intro NAME acl_intro - introduction to DST/DIS Automated Cartridge Library (ACL) Management Utilities. DESCRIPTION The Ampex DST/DIS Automated Cartridge Library (ACL) 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.
ACL Application Programmer’s Guide acl_intro UTILITIES SUMMARY Need input for items flagged (TBS). Writer_Note: The ACL Management Utilities have descriptive 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.
Model ACL Application Programmer’s GuideNo. Running Head acl_intro 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. • 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).
ACL Application Programmer’s Guide acl_intro -stdout The -stdout 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 argument allows you to specify the following: • Keywords [%field_name or %(field_name) as documented in the utility’s manual page] that designate the fields in the output stream written to stdout.
Model ACL Application Programmer’s GuideNo. Running Head acl_intro -t 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.
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.
Model ACL Application Programmer’s GuideNo. Running Head acl_audit_library 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 [ -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 argument specifies the fields written to stdout.
ACL Application Programmer’s Guide acl_audit_library -stdout Specifies the output fields written to stdout. You must provide a -stdout argument for this utility (except when using the -help argument). The -stdout argument supports the following keywords: %access %barcode Prints the access status of the location: + Plus (+) indicates that the ACL can transfer a tape cartridge to or from the location.
Model ACL Application Programmer’s GuideNo. Running Head acl_audit_library $RETRY_ON_RESET Specifies that the ACL 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 -retry_on_reset option is specified on the command line. EXIT STATUS The ACL management utilities use the following exit status codes: 0 Operation successful.
ACL Application Programmer’s Guide 5.4 acl_audit_element acl_audit_element NAME acl_audit_element - retrieve the status of a single location from the ACL internal database. SYNOPSIS acl_audit_element -element -stdout [ -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 argument.
Model ACL Application Programmer’s GuideNo. Running Head acl_audit_element -element Specifies the name of the location for which you want to retrieve status. You must provide -element and -stdout arguments for this utility (except when using the -help argument). -stdout Specifies the output fields written to stdout.
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 ACL 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 -retry_on_reset option is specified on the command line.
Model ACL Application Programmer’s GuideNo. Running Head acl_errlog_library 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.
ACL Application Programmer’s Guide acl_errlog_library -t Specifies the optional separator characters that enclose the value specified for the -count argument. If omitted, colons are used as the separator characters. Separator characters are not required for the -count argument but you can them if desired (for compatibility with existing applications).
Model ACL Application Programmer’s GuideNo. Running Head acl_errlog_library $RETRY_ON_RESET Specifies that the ACL 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 -retry_on_reset option is specified on the command line. EXIT STATUS The ACL management utilities use the following exit status codes: 0 Operation successful.
ACL Application Programmer’s Guide 5.6 acl_getparam_library acl_getparam_library NAME acl_getparam_library - get the current ACL configuration parameter settings. SYNOPSIS acl_getparam_library -stdout [ -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 argument specifies the output fields written to stdout.
Model ACL Application Programmer’s GuideNo. Running Head acl_getparam_library 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. -stdout Specifies the output fields written to stdout.
ACL Application Programmer’s Guide %v_req_barcod acl_getparam_library 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).
Model ACL Application Programmer’s GuideNo. Running Head acl_getparam_library 0 Operation successful. nonzero Operation failed. Writer_Note: We should show a typical output for the example. EXAMPLES Print the current settings of all configuration parameters in verbose style.
ACL Application Programmer’s Guide 5.7 acl_init_chs 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.
Model ACL Application Programmer’s GuideNo. Running Head acl_init_chs $ACL_DEV Specifies the device special file to use when you omit the -device option. $RETRY_ON_RESET Specifies that the ACL 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 -retry_on_reset option is specified on the command line.
ACL Application Programmer’s Guide 5.8 acl_move_tape acl_move_tape NAME acl_move_tape - move a tape cartridge from one ACL location to another. SYNOPSIS acl_move_tape -sourcelocation -targetlocation [ -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.
Model ACL Application Programmer’s GuideNo. Running Head acl_move_tape -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: output and revision. -sourcelocation Specifies the name of the ACL location from which the tape cartridge is to be moved. You must use uppercase letters exactly as shown in the acl_intro(1) manual page.
ACL Application Programmer’s Guide acl_move_tape EXAMPLE Move the tape cartridge in storage bin A01 to the drive.
Model ACL Application Programmer’s GuideNo. Running Head acl_move_volume 5.
ACL Application Programmer’s Guide 5.10 acl_park_chs acl_park_chs NAME acl_park_chs - park the ACL cartridge handling system (2XX, 4XX). SYNOPSIS acl_park_chs [ -device device_special_file ] [ -retry_on_reset ] acl_park_chs -help [ help_type ] DESCRIPTION acl_park_chs 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.
Model ACL Application Programmer’s GuideNo. Running Head acl_park_chs 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 ACL management utilities perform one retry automatically when a failure is caused by a SCSI Bus Device Reset of the ACL.
ACL Application Programmer’s Guide 5.11 acl_query_library acl_query_library NAME acl_query_library - get ACL vendor name, product name, software revision levels, and software release dates. SYNOPSIS acl_query_library -stdout output_spec [ -device device_special_file ] [ -n ] [ -retry_on_reset ] acl_query_library -help [ help_type ] DESCRIPTION acl_query_library returns ACL vendor, product and software information. The -stdout option specifies which fields are written to stdout.
Model ACL Application Programmer’s GuideNo. Running Head acl_query_library ARGUMENTS Writer_Note: Bug RWCra01672 states “Usage does not tell you about the “-help v_revision”. Should we cover this in the man page? -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: output and revision. -stdout Specifies the output fields written to stdout.
ACL Application Programmer’s Guide acl_query_library $RETRY_ON_RESET Specifies that the ACL 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 -retry_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.
Model ACL Application Programmer’s GuideNo. Running Head acl_setparam_library 5.12 acl_setparam_library NAME acl_setparam_library - change ACL configuration parameter settings. SYNOPSIS acl_setparam_library -aclparam [ -t separator ] [ -device device_special_file ] [ -retry_on_reset ] acl_setparam_library -help [ help_type ] DESCRIPTION acl_setparam_library sets the behavior of the ACL by changing one or more configuration parameter settings.
ACL Application Programmer’s Guide acl_setparam_library -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 [ 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. -aclparam Specifies new values for the configuration parameters settings you want to change.
Model ACL Application Programmer’s GuideNo. Running Head acl_setparam_library AutoAuditOverride An integer value of 1 or 0, sets the Auto Audit Override configuration parameter to on or off, respectively. 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.
ACL Application Programmer’s Guide acl_setparam_library 0 Operation successful. nonzero Operation failed. I changed the description of the following example. Please verify that leaving a field blank retains the current configuration parameter setting. Writer_Note: EXAMPLES Set the Auto Store Enable configuration parameter to on.
Model ACL Application Programmer’s GuideNo. Running Head acl_statlog_library 5.13 acl_statlog_library NAME acl_statlog_library - retrieve the ACL Static Log. SYNOPSIS acl_statlog_library -stdout [ -device device_special_file ] [ -n ] [ -retry_on_reset ] acl_statlog_library -help [ help_type ] DESCRIPTION acl_statlog_library retrieves the static log from the ACL. This log contains information about internal software performance and protocol tasks.
ACL Application Programmer’s Guide acl_statlog_library -stdout Specifies the output stream written to stdout. You must provide a -stdout argument for this utility (except when using the -help argument). The -stdout argument supports the following keyword: %slog. ENVIRONMENT The ACL management utilities use the following environment variables. Command-line options always override any environment variables.
Model ACL Application Programmer’s GuideNo. Running Head acl_status_library 5.14 acl_status_library NAME acl_status_library - get current ACL status information and SCSI sense data. SYNOPSIS acl_status_library -stdout [ -device device_special_file ] [ -n ] [ -retry_on_reset ] acl_status_library -help [ help_type ] DESCRIPTION acl_status_library issues a SCSI Request Sense command to the ACL to retrieve the current Sense Data.
ACL Application Programmer’s Guide acl_status_library -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 [ 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. -stdout Specifies the output fields written to stdout.
Model ACL Application Programmer’s GuideNo. Running Head acl_status_library %v_chs_posn 2XX, 4XX - Prints a string indicating the current position of the ACL cartridge handling system; i.e., parked (0) or the name of the storage bin positioned in front of the drive (A01–A07). 8XX - Prints a string indicating the name of the location at which the cartridge handler is positioned; i.e. drive (DR1–DR4), IMEX bin (H07–H14), or storage bin (A01–H06 or H15–H32).
ACL Application Programmer’s Guide acl_status_library 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 ACL management utilities perform one retry automatically when a failure is caused by a SCSI Bus Device Reset of the ACL.
Model ACL Application Programmer’s GuideNo.
ACL Application Programmer’s Guide Returned Sense Data Appendix A Returned Sense Data A.1 Error/Event Parameter Identification Codes Table A-1 lists the identification codes that the ACL might report in the Error/Event Log data returned for aclGetErrorLog() and acl_errlog_library. For some of these codes, additional integer values are included to further describe the condition detected.
Running Head Error/Event Parameter Identification Codes Model ACL Application Programmer’s GuideNo. Table A-1.
ACL Application Programmer’s Guide Error/Event Parameter Identification Codes Table A-1.
Model ACL Application Programmer’s GuideNo. Running Sense KeyHead Codes Table A-1. Error/Event Parameter Identification Code Descriptions (Continued) Code A.
ACL Application Programmer’s Guide A.3 Additional Sense Codes and Qualifiers Additional Sense Codes and Qualifiers Table A-3. lists the ASC/ASCQ conditions the ACL might report in the data returned for aclReqSense(), aclStatus(), and acl_status_library. Table A-3. ASC/ASCQ Conditions ASC ASCQ 00h 00h No Sense (0h) No error. 04h 01h Not Ready (2h) ACL is in the process of becoming ready. 04h 03h Not Ready (2h) ACL is not ready; an initialization command is required.
Model ACL Application Programmer’s GuideNo. Running HeadACL Condition Codes Vendor-Specific A.4 Vendor-Specific ACL Condition Codes Table A.4 lists vendor-specific condition codes the ACL might report in the data returned for aclReqSense(), aclStatus(), and acl_status_library. The table is arranged in alpha-numeric sequence, ordered as follows: Sense Key ASC/ASCQ Condition Code Table A-4.
ACL Application Programmer’s Guide Vendor-Specific ACL Condition Codes Table A-4. Vendor-Specific ACL Condition Codes (Continued) Sense ASC ASCQ Key 02h 04h Not Ready 03h ACL Condition Code 30h Condition Reported Unit Not Ready—Sequential Mode (2XX, 4XX) The ACL can be operated from its front panel independently from the host. While it is in sequential mode, it will not execute SCSI commands.
Model ACL Application Programmer’s GuideNo. Running HeadACL Condition Codes Vendor-Specific Table A-4.
ACL Application Programmer’s Guide Vendor-Specific ACL Condition Codes Table A-4. Vendor-Specific ACL Condition Codes (Continued) Sense ASC ASCQ Key ACL Condition Code 04h 55h BFh Hardware Error 3Fh 04h 55h C1h Hardware Error 41h 05h 20h 00h Illegal Request 29h Condition Reported CHS Hardware Failure The CHS has been unable to complete a request because of a mechanical failure. The CHS Failure additional sense page (0x83) will be appended with the specific failure code for the error.
Model ACL Application Programmer’s GuideNo. Running HeadACL Condition Codes Vendor-Specific Table A-4. Vendor-Specific ACL Condition Codes (Continued) Sense ASC ASCQ Key ACL Condition Code 05h 21h 01h Illegal Request 35h 05h 21h 01h Illegal Request 36h Condition Reported Recovery Procedure Invalid Transport Element Address. Read Element Status and verify that the addresses are valid and the move is permitted.
ACL Application Programmer’s Guide Vendor-Specific ACL Condition Codes Table A-4. Vendor-Specific ACL Condition Codes (Continued) Sense ASC ASCQ Key ACL Condition Code 06h 29h 00h Unit Attention 69h 0Bh 55h B9h Aborted Command 39h Condition Reported Power On or Unit Reset Condition Indicates this is the first command sent by the initiator after the ACL completed a boot sequence.
Model ACL Application Programmer’s GuideNo. Running HeadACL Condition Codes Vendor-Specific Table A-4. Vendor-Specific ACL Condition Codes (Continued) Sense ASC ASCQ Key 0Bh 5Ah 97h Aborted Command A-12 ACL Condition Code 17h Condition Reported ACL Library Door(s) Open A cabinet door was opened while the ACL was executing a command. Preliminary Draft Recovery Procedure Close all doors (for an 8XX ACL, also reset the MDA POWER switch).
ACL Application Programmer’s Guide A.5 CHS Failure, Error, and Warning Codes CHS Failure, Error, and Warning Codes Table A.5 lists CHS failure, error, and warning codes the ACL might report in the data returned for aclReqSense(), aclStatus(), and acl_status_library. This information is intended for Ampex factory personnel as interpretation of the codes requires a detailed understanding of ACL internal operation. Table A-5.
Running Head CHS Failure, Error, and Warning Codes Model ACL Application Programmer’s GuideNo. Table A-5.
ACL Application Programmer’s Guide CHS Failure, Error, and Warning Codes Table A-5.
Running Head CHS Failure, Error, and Warning Codes Model ACL Application Programmer’s GuideNo. Table A-5.
ACL Application Programmer’s Guide CHS Failure, Error, and Warning Codes Table A-5.
Running Head CHS Failure, Error, and Warning Codes Model ACL Application Programmer’s GuideNo. Table A-5.
ACL Application Programmer’s Guide CHS Failure, Error, and Warning Codes Table A-5.
Running Head CHS Failure, Error, and Warning Codes Model ACL Application Programmer’s GuideNo. Table A-5.
ACL Application Programmer’s Guide CHS Failure, Error, and Warning Codes Table A-5.
Running Head CHS Failure, Error, and Warning Codes Model ACL Application Programmer’s GuideNo. Table A-5.
ACL Application Programmer’s Guide CHS Failure, Error, and Warning Codes Table A-5. CHS Failure, Error, and Warning Codes (Continued) CHS Code Description WARNING MESSAGES (2XX, 4XX) 2001d (7D1h) +24Vdc supply is indicating greater than 26 volts 2002d (7D2h) +24Vdc supply is indicating less than 22 volts 2003d (7D3h) +5Vdc supply is indicating greater than 5.5 volts 2004d (7D4h) +5Vdc supply is indicating less than 4.
Running Head CHS Failure, Error, and Warning Codes Model ACL Application Programmer’s GuideNo. Table A-5.
ACL Application Programmer’s Guide CHS Failure, Error, and Warning Codes Table A-5.
Running Head CHS Failure, Error, and Warning Codes Model ACL Application Programmer’s GuideNo. Table A-5.
™ Ampex Corporation 401 Broadway Redwood City, CA 94063-3199 Part Number 1308904-X4 ¨
