Server User Manual

ManualsBrandsADIC ManualsServerServer

The ADIC

Distributed AML Server

DAS V3.10E

Interfacing

Guide

Summary of content (218 pages)

PAGE 1
The ADIC Distributed AML Server DAS V3.
PAGE 2
Copyright Notice © Copyright ADIC 2001 The information contained in this document is subject to change without notice. This document contains proprietary information which is protected by copyright. All rights are reserved. No part of this document may be photocopied, reproduced, or translated to another language without prior written consent of ADIC.
PAGE 3
21 Dec 2001 iii
PAGE 4
iv [Chapter Name] 601626-B
PAGE 5
Contents 1 Introduction Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3 Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3 Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3 Associated Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 6
Media Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7 DAS Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8 3 Safety Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3 Hazard Alert Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 7
Return Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-25 aci_drivestatus3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-26 Return Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-29 aci_drivestatus4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 8
aci_getVolserToSide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-70 Return Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-71 aci_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-72 Return Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 9
aci_scratch_info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-111 Return Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-112 aci_scratch_set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-114 Return Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 10
das_force . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7 das_insert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-8 das_eject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9 das_eject_complete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 11
Error Recovery Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3 Terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 12
x Contents 601626-B
PAGE 13
Figures Figure 2-1 Logical Relationship Between AML Components . . . . . . . . . . . . . . . 2-3 Figure 4-1 aci_barcode Function Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5 Figure 4-2 Example of the aci_barcode Function. . . . . . . . . . . . . . . . . . . . . . . . . . 4-7 Figure 4-3 aci_cancel Function Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7 Figure 4-4 Example of the aci_cancel Function . . . . . . . . . . . . . . . .
PAGE 14
x Figures Figure 4-22 aci_drivestatus4 Function Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-29 Figure 4-23 Returned Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-30 Figure 4-24 aci_drivestatus_one Function Call . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-32 Figure 4-25 Returned Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 15
21 Dec 2001 Figure 4-55 Example of the aci_foreign Function. . . . . . . . . . . . . . . . . . . . . . . . . . 4-68 Figure 4-56 aci_getvolsertodrive Function Call . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-68 Figure 4-57 aci_voltodrive_entry Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-69 Figure 4-58 Example of the aci_getvolertodrive Function . . . . . . . . . . . . . . . . . . 4-70 Figure 4-59 aci_getVolserToSide Function Call . . . . . . . . . . . . . . .
PAGE 16
xii Figures Figure 4-88 aci_qversion Function Call. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-97 Figure 4-89 Example of the aci_qversion Function . . . . . . . . . . . . . . . . . . . . . . . . 4-98 Figure 4-90 aci_qvolsrange Function Call. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-98 Figure 4-91 Amount of Listed Volsers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-99 Figure 4-92 Structure for the aci_volserinfo . . . . . .
PAGE 17
21 Dec 2001 Figure 5-1 Example of a Generic aci_async_add() Function . . . . . . . . . . . . . . . . 5-5 Figure 5-2 aci_async_add Function with the das_mount Parameter . . . . . . . . . 5-6 Figure 5-3 Example of the aci_async_add Function with the das_mount Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6 Figure 5-4 aci_async_add Function with the das_dismount Parameter . . . . . .
PAGE 18
xiv Figures 601626-B
PAGE 19
Tables Table 2-1 Routines Available with Basic Service Access . . . . . . . . . . . . . . . . . . 2-5 Table 2-2 Routines Available with Complete Service Access . . . . . . . . . . . . . . 2-5 Table 2-3 Supported Media Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7 Table 3-1 Hazard Alert Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3 Table 4-1 Parameters for the aci_barcode Function Call. . . . . . . . . . . . . . . . . .
PAGE 20
xvi Tables Table 4-19 Parameters for the aci_eject2_complete Function Call. . . . . . . . . . . 4-52 Table 4-20 Parameters for the aci_eject3_complete Function Call. . . . . . . . . . . 4-55 Table 4-21 Parameters for the aci_ejectclean Function Call . . . . . . . . . . . . . . . . 4-57 Table 4-22 Parameter for the aci_email Function Call. . . . . . . . . . . . . . . . . . . . . 4-61 Table 4-23 Parameter for the aci_flip Function Call . . . . . . . . . . . . . . . . . . . . . .
PAGE 21
Dec 2001 Table 4-52 Parameters for the aci_view Function Call . . . . . . . . . . . . . . . . . . . 4-124 Table 4-53 Table Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-124 Table 4-54 Table Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-125 Table 4-55 Parameters for the aci_volser_inventory Function Call. . . . . . . . . 4-127 Table 4-56 Parameters for the aci_volseraccess Function Call . . .
PAGE 22
xviii Tables 601626-B
PAGE 23
1 Introduction Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3 Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3 Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3 Associated Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 24
1-2 Introduction 601626-B
PAGE 25
1- Overview This guide contains information and instructions necessary to program an application for using the ADIC AML via the Distributed AML Server (DAS). The topics discussed in this chapter are: • Overview • Intended Audience • Organization • Associated Documents • Explanation of Symbols and Notes • Assistance Intended Audience This guide is intended for use by system programmers and administrators working with the DAS software. Knowledge of the UNIX and OS/2 operating systems is required.
PAGE 26
Associated Documents You may wish to reference the following documents: • 601324-A DAS V3.1 Release Guide • 601625-A DAS V3.1 Administration Guide Explanation of Symbols and Notes The following symbols and highlighted passages draw attention to important information. Detailed explanations for the above symbols are provided in Hazard Alert Messages on page 3-3. 1-4 Introduction <1>+<2> Press these keys simultaneously. Italic Headline, e.g., Chapter 3, Safety File name, e.g., dasdata.
PAGE 27
Assistance If problems cannot be solved with the aid of this document or if recommended training is desired, contact the ADIC Technical Assistance Center (ATAC). ADIC 10949 East Peakview Avenue Englewood, CO 80112 U.S.A.
PAGE 28
1-6 Introduction 601626-B
PAGE 29
2 DAS ACI Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3 DAS/2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3 ACI Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4 Client Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 30
2-2 DAS ACI 601626-B
PAGE 31
2- Overview This section contains an overview of the DAS/2 software and information on AML Client Interface (ACI) services. DAS/2 DAS is a client/server software product designed to provide shared access to the family of ADIC AML systems (AMLs). The DAS software may be installed as a stand-alone AML connection or be configured to share an AML with MVS or other ADIC supported, host attachments.
PAGE 32
The DAS server component is an OS/2 program that runs within the AMU controller personal computer (PC). It converts DAS client requests into AMU AMS requests and sends them to the AMS for action. Fifty heterogeneous networked clients can be configured within the DAS server environment. Clients requiring access to ADIC AML systems may use the DAS ACI software component to communicate library requests to the DAS server component.
PAGE 33
ACI Routines - Basic Services Table 2-1 lists the routines that are available to an ACI client with basic service access rights. Table 2-1 Routines Available with Basic Service Access Routine Explanation aci_dismount Dismount media from the drive. aci_init Initialize the AML for client use. aci_initialize Initialize ACI library for client use. aci_mount Mount specified media in drive.
PAGE 34
Table 2-2 Routines Available with Complete Service Access Routine 2-6 DAS ACI Explanation aci_eject2 Eject media from AML, and keep database entry for future insert requests. aci_ejectclean Eject clean media from AML, and remove database entry. aci_eject2_complete Eject media from AML, and remove database entry. aci_flip Turn Optical Disk on in the drive. aci_force Force a dismount request from a specified drive. aci_foreign Add or delete foreign media.
PAGE 35
Table 2-2 Routines Available with Complete Service Access Routine Explanation aci_robhome Set the AML-System to offline and move the robot to home position. aci_robstat Get Information about the AML-status and set the AML to on-line. aci_scratch_get Mount a scratch volume. aci_scratch_info Query scratch volume information. aci_scratch_set Add volume to scratch pool. aci_scratch_unset Remove volume from scratch pool. aci_killamu Shutdown AMU complete with OS/2. aci_shutdown Shut down DAS.
PAGE 36
Table 2-3 Supported Media Types ACI Media Name Media Type ACI_8MM DDS 8mm tape (e.g.
PAGE 37
3 Safety Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3 Hazard Alert Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3 Validity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 38
3-2 Safety 601626-B
PAGE 39
3- Overview Knowledge and observance of these instructions is imperative for the safe operation of the ADIC Storage Systems AML system. Note In addition to the safety instructions in this guide, local and professional safety rules apply. Avoid danger when maintaining and operating the machine by • behaving in a safety-conscious manner • acting judiciously Hazard Alert Messages ADIC classifies hazards in several categories.
PAGE 40
Table 3-1 Symbol Hazard Alert Message Damage to ... Material Signal Word Static Sensitive Definition Consequence Potential electronic damaging situation Possible damage to the product Tips for operators No hazardous or damaging consequences Important or useful information No hazardous or damaging consequences Note Specially emphasized paragraphs in this guide warn of danger or draw attention to important information.
PAGE 41
Validity These instruction are valid for ADIC Storage Systems AML systems. Supplementary safety provisions for any components used on the machine are not invalidated by these instructions. Any other manufacturer's documentation forms part of the AML documentation.
PAGE 42
3-6 Safety 601626-B
PAGE 43
4 DAS ACI Functions Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5 aci_barcode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5 Return Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6 aci_cancel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 44
aci_drivestatus2_one . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-34 Return Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-35 aci_drivestatus3_one . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-36 Return Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 45
Return Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-76 aci_insert2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-77 Return Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-79 aci_inventory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 46
Return Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-118 aci_snmp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-119 Return Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-119 aci_switch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 47
4- Overview All ACI function calls and ACI structures are defined in the aci.h header file. ACI functions return 0 or -1 for successful and unsuccessful command execution respectively. A command failure sets the DAS error code variable d_errno to the specific error code. In such case, a text error message may be written to standard error by calling aci_perror, which accepts a user defined message string and attaches it to the DAS error message.
PAGE 48
The Scalar 1000 does not support the aci_barcode command (barcode on Scalar 1000 will never read on mount and eject). Use this command to switch the barcode reading after the command aci_mount, aci_cleandrive or any aci_eject ended with failure and derrno=EBARCODE. After aci_barcode completed, try the previous command again. Return Values • 0: The call was successful. • -1: The call failed.
PAGE 49
/* Switch the barcode reading off for robot 1 */ int rc = 0; char *cRobNum = "1"; char *Action = "OFF"; rc = aci_barcode( cRobNum, Action ); if( rc ) { aci_perror( "Command failed: " ); } else { printf( "barcode reading switched off \n" );} Figure 4-2 Example of the aci_barcode Function aci_cancel The aci_cancel function cancels a specific DAS request. See Figure 4-3. #include "aci.
PAGE 50
The cancel request cancels the command in the DAS server and the AML. If the request is being acted upon in the AML, DAS attempts to cancel it, however this is unlikely to succeed. Once the robotics are in motion, the request may not be canceled. DAS reports that the cancel was successful while the canceled request completes. For additional information, Refer to aci_list on page 4-84. Return Values • 0: The call was successful. • -1: The call failed.
PAGE 51
aci_cleandrive The aci_cleandrive function mounts a cleaning cartridge to a specific drive. See Figure 4-5. #include "aci.h" int aci_cleandrive( char *drive) aci_cleandrive Function Call Figure 4-5 See Table 4-3 for a description of the parameter for the aci_cleandrive function call. Table 4-3 Parameter for the aci_cleandrive Function Call Parameter drive Description name of the drive to be cleaned Only clean the drives when they need to be cleaned. Unnecessary cleaning damages the drives.
PAGE 52
4-10 DAS ACI Functions • ERERTRYL • EINUSE • ECANCELLED • EDASINT • ECLEANING • ETIMEOUT • ESWITCHINPROG • EHICAPINUSE • EBARCODE • EINVALIDDEV • ENOROBOT • EDATABASE • ENOTSUPPHCMD • EAREAEMPTY • ENOPOOL • EPROBDEV • EBARCODE • EAREAFULL 601626-B
PAGE 53
aci_clientaccess The aci_clientaccess function modifies the access lists of a client. See Figure 4-6. #include "aci.h" int aci_clientaccess( char *clientname, enum aci_command action, char *volser_range, enum aci_media type, char *drive_range ) Figure 4-6 aci_clientaccess Function Call See Table 4-4 for a description of the parameters for the aci_clientaccess function call.
PAGE 54
The changes will be lost when the DAS software is shut down. Only use this command if, at the time, you do not have access to the config configuration file, or you cannot restart DAS. Otherwise, change the access privileges in the config file. This ACI command allows the administrator to add new volume ranges or drive ranges to the AML system without shutting down the DAS server. The modifications created by using the aci_clientaccess function are only valid while DAS is running.
PAGE 55
/* Add a volser range to a clients access list */ int rc = 0; enum aci_command action = ACI_ADD; /*default action*/ char *client = "SomeClient"; char *volser = "AAB000 - AAB999"; char *drive = ""; enum aci_media type = ACI_3590; if ((rc = aci_clientaccess ( client, action, volser, type, drive ) )) { aci_perror( "Command failed: " ); } else { if (*volser) { printf ( "Volser range %s for client %s added.\n", volser, client ); } if (*drive) { printf ( "Drive range %s added for client %s.
PAGE 56
aci_clientstatus The aci_clientstatus function queries client access list configuration. See Figure 4-8. #include "aci.h" int aci_clientstatus( char *clientname, struct aci_client_entry *client ) Figure 4-8 aci_clientstatus Function Call Query the current client access configuration status of a client named clientname. All configuration information is returned in the structure aci_client_entry. See Figure 4-9. For additional information, refer to aci_clientaccess on page 4-11.
PAGE 57
Table 4-5 Parameters for the aci_clientstatus Function Call Parameter Description clientname name of the client which authorization is to be changed aci_client_entry returned information to the requested client clientname requested client name in_addr 32-bit dotted decimal noted Internet Protocol (IP) address avc (true or false) Parameter “avoid volume contention” defined the reaction during a mount of an already mounted cartridge complete_access (true or false) Parameter authorized complete o
PAGE 58
/* Query some clients access list configuration */ int rc = 0; char *client = "SomeClient"; struct aci_client_entry client_entry; rc = aci_clientstatus ( client, &client_entry ); if( rc ) { aci_perror( "Command failed: " ); } Figure 4-10 Example of the aci_clientstatus Function aci_dismount The aci_dismount function dismounts a volume. See Figure 4-11. #include "aci.
PAGE 59
Return Values • 0: The call was successful. • -1: The call failed.
PAGE 60
/* Dismount volume from drive */ int rc = 0; enum aci_media type = ACI_3590; char *volser = "AAB001"; if (( rc = aci_dismount( volser, type ) )) { aci_perror( "Dismount command failed: " ); } else { printf( "Dismount of %s successful.\n", volser ); } Figure 4-12 Example of the aci_dismount Function aci_driveaccess The aci_driveaccess function modifies allocation status of a drive. See Figure 4-13. #include "aci.
PAGE 61
Table 4-7 Parameters for the aci_driveaccess Function Call Parameter Description clientname client that has allocated the drive or wants to allocate the drive. Using SHARED_ACCESS as a key word for the client name when requesting a drive reservation causes that drive to be shared with other clients. All clients which are configured for that drive can access it.
PAGE 62
Return Values The aci_driveaccess returns the following values: • 0: The call was successful. • -1: The call failed. The external variable d_errno is set to one of the following DAS error codes: • ERPC • EINVALID • ENODRIVE • EDRVOCCUPIED • ENOTHAUTH • EUPELSE • EBADCLIENT • ENOTAUTH • ETIMEOUT • ESWITCHINPROG • EEXUP • EDASINT See Figure 4-14 for an example of the aci_driveaccess function.
PAGE 63
aci_drivestatus The aci_drivestatus function queries status of up to 15 drives. See Figure 4-15. #include "aci.h" int aci_drivestatus( char *clientname, struct aci_drive_entry *pstDriveEntry[ACI_MAX_DRIVE_ENTRIES]) Figure 4-15 aci_drivestatus Function Call Return the status of drives which are set to UP (active) for the client with name clientname. If clientname is the NULL string, return status on all drives. The status is returned in drive_entry, an array of pointers to aci_drive_entry structures.
PAGE 64
Return Values • 0: The call was successful. • -1: The call failed. The external variable d_errno is set to one of the following DAS error codes: • ERPC • EINVALID • ETIMEOUT • ESWITCHINPROG • EBADCLIENT aci_drivestatus2 The aci_drivestatus2 function queries status of up to 250 drives. See Figure 4-17. #include "aci.
PAGE 65
struct aci_drive_entry { char drive_name[ACI_DRIVE_LEN]; char amu_drive_name[ACI_AMU_DRIVE_LEN]; enum aci_drive_status drive_state; char type; char system_id[ACI_NAME_LEN]; char clientname[ACI_NAME_LEN]; char volser [ACI_VOLSER_LEN]; bool_t cleaning; short clean_count; }; Figure 4-18 Returned Status See Table 4-8 for a description of the parameters for the aci_drivestatus2 function call.
PAGE 66
Table 4-8 Parameters for the aci_drivestatus2 Function Call Parameter aci_drive_entry Description returned information about the status of the drives drive_name name of the drive (name used in DAS and AMS description) amu_drive_name internal AMS drive name e.g. 03 or ZZ drive_state UP or DOWN reservation of the drive Refer to aci_driveaccess on page 4-18 type type of the drive (internal AMS code, e.g.
PAGE 67
Return Values • 0: The call was successful. • -1: The call failed. The external variable d_errno is set to one of the following DAS error codes: • ERPC • EINVALID • ETIMEOUT • ESWITCHINPROG • EBADCLIENT Refer to Figure 4-19 on page 4-26 for an example of the aci_drivestatus2 function.
PAGE 68
/* Get drive status information for some client */ int rc = 0; int i = 0; char *client = "SomeClient"; struct aci_drive_entry *drive_entry[ACI_MAX_DRIVE_ENTRIES2]; if (( rc = aci_drivestatus2( client, drive_entry ) )) { aci_perror( "listd failed" ); } else { printf("Drive status request for client: %s successful\n",client ); for (i = 0; i < ACI_MAX_DRIVE_ENTRIES2; i++) { if ( *drive_entry[i]->drive_name == '\0' ) break; printf( "drive:%s amu drive:%s st:%s type:%c" "sysid:%s client:%s volser:%s cleaning:%d"
PAGE 69
#include "aci.h" init aci_drivestatus3 ( char *clientname, struct aci_ext_drive_entry *pstDriveEntry[]) Figure 4-20 aci_drivestatus3 Function Call Return the status of drives which are set to UP for the client with the name clientname. If clientname is the NULL string, the call returns status on all drives. The status is returned in an array of pointers to aci_ext_drive_entry structure. The array element can be maximal 250. See Figure 4-21.
PAGE 70
Table 4-9 Parameters for the aci_drivestatus3 Function Call Parameter aci_drive_entry 4-28 DAS ACI Functions Description returned information about the status of the drives drive_name name of the drive (name used in DAS and AMS description) amu_drive_name internal AMS drive name e.g. 03 or ZZ drive_state UP or DOWN reservation of the drive Refer to aci_driveaccess on page 4-18 type type of the drive (internal AMS code, e.g.
PAGE 71
Return Values • 0: The call was successful • -1: The call has failed The external variable d_errno is set to one of the following DAS error codes: • EBADCLIENT • ERPC • EINVALID • EDASINT • ETIMEOUT • ESWITCHINPROGRESS • EDASINT aci_drivestatus4 The aci_drivestatus4 function queries the physical status of up to 380 drives. See Figure 4-22. #include "aci.
PAGE 72
struct aci_ext_drive_entry4 { char drive_name[ACI_DRIVE_LEN]; char amu_drive_name[ACI_AMU_DRIVE_LEN]; enum aci_drive_status drive_state; char type; char system_id[ACI_NAME_LEN]; char clientname[ACI_NAME_LEN]; char volser[ACI_VOLSER_LEN]; bool_t cleaning; short clean_count; int mount; int keep; char serial_number[ACI_SERIAL_NUMBER_LEN]; }; Figure 4-23 Returned Status The variable ACI_SERIAL_NUMBER_LEN is equal to 51.
PAGE 73
Table 4-10 Parameters for the aci_drivestatus4 Function Call Parameter Description drive_state UP or DOWN reservation of the drive Refer to aci_driveaccess on page 4-18 type type of the drive (internal AMS code, e.g.
PAGE 74
• ERPC • EINVALID • ETIMEOUT • ESWITCHINPROGRESS • EBADCLIENT • ENOTSUPPHCMD aci_drivestatus_one The aci_drivestatus_one function queries the physical status of up to 15 drives. See Figure 4-24. #include "aci.h" init aci_drivestatus_one ( char *clientname, char *drive struct aci_drive_entry *pstDriveEntry[ACI_MAX_DRIVE_ENTRIES]) Figure 4-24 aci_drivestatus_one Function Call Return the status of drives which are set to UP for the client with the name clientname.
PAGE 75
See Table 4-11 for an explanation of the parameters used for the aci_drivestatus_one function. Table 4-11 Parameters for the aci_drivestatus_one Function Call Parameter Description clientname name of the client that requested the status of the drives. If clientname is the NULL string, return status on all drives. aci_drive_entry returned information about the status of the drives drive_name name of the drive (name used in DAS and AMS description) amu_drive_name internal AMS drive name e.g.
PAGE 76
• ERPC • EINVALID • ETIMEOUT • ESWITCHINPROGRESS • EBADCLIENT • ENOTSUPPHCMD aci_drivestatus2_one The aci_drivestatus2_one function queries the physical status of up to 250 drives. See Figure 4-26. #include "aci.h" init aci_drivestatus2_one ( char *clientname, char *drive struct aci_drive_entry *pstDriveEntry[ACI_MAX_DRIVE_ENTRIES2]) Figure 4-26 aci_drivestatus_2_one Function Call Return the status of drives which are set to UP for the client with the name clientname.
PAGE 77
See Table 4-12 for an explanation of the parameters used for the aci_drivestatus2_one function. Table 4-12 Parameters for the aci_drivestatus2_one Function Call Parameter Description clientname name of the client that requested the status of the drives. If clientname is the NULL string, return status on all drives. aci_drive_entry returned information about the status of the drives drive_name name of the drive (name used in DAS and AMS description) amu_drive_name internal AMS drive name e.g.
PAGE 78
• ERPC • EINVALID • ETIMEOUT • ESWITCHINPROGRESS • EBADCLIENT • ENOTSUPPHCMD aci_drivestatus3_one The aci_drivestatus3_one function queries the physical status of up to 250 drives. See Figure 4-28. #include "aci.h" init aci_drivestatus3_one ( char *clientname, char *drive struct aci_drive_entry *pstDriveEntry[ACI_MAX_DRIVE_ENTRIES2]) Figure 4-28 aci_drivestatus_3_one Function Call Return the status of drives which are set to UP for the client with the name clientname.
PAGE 79
See Table 4-13 for an explanation of the parameters used for the aci_drivestatus3_one function. Table 4-13 Parameters for the aci_drivestatus3_one Function Call Parameter Description clientname name of the client that requested the status of the drives. If clientname is the NULL string, return status on all drives. aci_drive_entry returned information about the status of the drives drive_name name of the drive (name used in DAS and AMS description) amu_drive_name internal AMS drive name e.g.
PAGE 80
• ERPC • EINVALID • ETIMEOUT • ESWITCHINPROGRESS • EBADCLIENT • ENOTSUPPHCMD aci_eif_conf The aci_eif_conf function queries status from up to 20 logical ranges. See Figure 4-30. #include "aci.h" int aci_eif_conf( struct aci_lora *lora_desc, int *nCount) Figure 4-30 aci_eif_conf Function Call The call returns nCount and the staus of the logical range. The status is returned in an array of pointers to the aci_lora structure. The array can be a maximum of 20 elements. See Figure 4-31.
PAGE 81
Table 4-14 Parameters for the aci_eif_conf Function Call Parameter aci_lorta nCount Description structure used to describe the import/export area and addressing lora_name the name of the import/export area StartCoord the starting coordinates of the area EndCoord the ending coordinates of the area ctype the cartridge type associated with the area description a description of the import.export area the number of returned status (maximum of 300) Return Values • 0: The call was successful.
PAGE 82
Eject the volumes in volser_range to the eject_area. The media type of the volumes must match that of the eject_area. Set type to the media type of the volser_range. See Table 4-15. Table 4-15 Parameters for the aci_eject Function Call Parameter Description clientname Using SHARED_ACCESS as a key word for the client shows all drives which are allocated in the SHARED_ACCESS mode. Using EXUP as a key word for the clientname shows all drives which are allocated in the EXUP mode.
PAGE 83
• ENOVOLUME • EPROBVOL • EAMU • EAMUCOMM • EROBOTCOMM • EDASINT • ENOAREA • ENOTAUTH • EBADCLIENT • ERETRYL • EINUSE • ECANCELED • EDASINT • ENOMATCH • ETIMEOUT • ESWITCHINPROG • EHICAPINUSE • ECOORDINATE • EBARCODE • EINVALIDDEV • ENOROBOT • EDATABASE • ENOTSUPPHCMD • EAREAEMPTY • EBARCODE • EAREAFULL Refer to Figure 4-33 for an example of the aci_eject function.
PAGE 84
aci_eject2 The aci_eject2 function ejects a range of volumes from the AML. See Figure 4-34. #include "aci.h" int aci_eject2( char *eject_area, char *volser_range, enum aci_media type, int *pnActualCount, struct aci_ei_info *psteiInfo) Figure 4-34 aci_eject2 Function Call For the structure of the aci_ei_info function, refer to Figure 4-35. struct aci_ei_info { char volser[ACI_VOLSER_LEN]; char media_type[ACI_DRIVE_LEN]; int errcode }; Figure 4-35 Structure of the aci_ei_info function from aci.
PAGE 85
Table 4-16 Parameters for the aci_eject2 Function Call Parameter aci_ei_info Description returned information on each volser ejected volser volser of the ejected volume type media type of the named volser Refer to Media Types on page 2-7 errcodes error code derrno If the eject area is full, the system stops the eject procedure.
PAGE 86
• ENOTAUTH • EBADCLIENT • ERETRYL • EINUSE • ECANCELED • EDASINT • ENOMATCH • ETIMEOUT • ESWITCHINPROG • EHICAPINUSE • ECOORDINATE • EBARCODE • EINVALIDDEV • ENOROBOT • EDATABASE • ENOTSUPPHCMD • EAREAEMPTY • EBARCODE • EAREAFULL See Figure 4-36 for an example of the aci_eject2 function.
PAGE 87
/* Eject volume but reserve archive location */ int rc, i, pnActualCount; char *volser_range = "000815 - 004711"; char *eject_area = "E02" struct aci_ei_info ei_info[ACI_EI_MAX_RANGE]; rc = aci_eject2( eject_area, volser_range, ACI_3590 &pnActualCount, &ei_info ); if( rc ) { aci_perror( "Command failed: " ); } else { printf("Volume ejects request successful\n" ); for (i = 0; i < ACI_EI_MAX_RANGE; i++) { if ( *ei_info[i]->volser == '\0' ) break; printf( "volser:%s media type:%s Error:%d\n", ei_info[i]->volse
PAGE 88
aci_eject3 The aci_eject3 function ejects a range of volumes from the AML. See Figure 4-37. #include "aci.h" int aci_eject3( char *eject_area, char *volser_range, enum aci_media type, int *pnActualCount, struct aci_ei_info *psteiInfo) Figure 4-37 aci_eject3 Function Call The volser_range field has a maximum size of 512 bytes. For the structure of the aci_ei_info function, refer to Figure 4-38.
PAGE 89
Table 4-17 Parameters for the aci_eject3 Function Call Parameter Description pnActualCount returned number of ejected volsers aci_ei_info returned information on each volser ejected volser volser of the ejected volume type media type of the named volser Refer to Media Types on page 2-7 errcodes error code derrno If the eject area is full, the system stops the eject procedure.
PAGE 90
4-48 DAS ACI Functions • ENOAREA • ENOTAUTH • EBADCLIENT • ERETRYL • EINUSE • ECANCELED • ENOMATCH • ETIMEOUT • ESWITCHINPROG • EHICAPINUSE • ECOORDINATE • EBARCODE • EINVALIDDEV • ENOROBOT • EDATABASE • ENOTSUPPHCMD • EAREAEMPTY • EBARCODE • EAREAFULL 601626-B
PAGE 91
aci_eject_ complete The aci_eject_complete function ejects volumes and removes the database entries. See Figure 4-39. #include "aci.h" int aci_eject_complete( char *eject_area, char *volser_range, enum aci_media type) Figure 4-39 aci_eject_complete function call Eject the volumes in volser_range to the eject_area. The media type of the volumes must match that of the eject_area. Set type to the media type of the volser_range.
PAGE 92
Return Values • 0: The call was successful. • -1: The call failed.
PAGE 93
/* Eject volume from archive and free storage position. */ int rc = 0; rc = aci_eject_complete("E01", "AAB001", ACI_3590 ); if( rc ) { aci_perror( "Command failed:" ); } else { printf( "Volser AAB001 ejected to E01 \n" ); } Figure 4-40 Example of the aci_eject_complete Function aci_eject2_complete The aci_eject2_complete function ejects a range of volumes from the AML, and deletes the home coordinate. See Figure 4-41. #include "aci.
PAGE 94
See Table 4-19 for a description of the parameters for the aci_eject2_complete function call.
PAGE 95
Return Values • 0: The call was successful. • -1: The call failed.
PAGE 96
/* Eject volume complete from AML system*/ int rc, i, pnActualCount; char *volser_range = "000815 - 004711"; char *eject_area = "E02" struct aci_ei_info ei_info[ACI_EI_MAX_RANGE] ; rc = aci_eject2_complete( eject_area, volser_range, ACI_3590, & pActualCount, &ei_info ); if( rec ) { aci_perror( "Command failed: " ); } else { printf("Volume ejects request successful\n" ); for (i = 0; i < ACI_EI_MAX_RANGE; i++) { if ( *ei_info[i]->volser == '\0' ) break; printf( "volser:%s media type:%s Error:%d\n", ei_info[i]
PAGE 97
The volser_range field has a maximum size of 512 bytes. See Figure 4-45 for the structure of the aci_ei_info function. struct aci_ei_info { char volser[ACI_VOLSER_LEN]; char media_type[ACI_DRIVE_LEN]; int errcode }; Figure 4-45 Structure of the aci_ei_info function See Table 4-20 for a description of the parameters for the aci_eject3_complete function call.
PAGE 98
The attribute of the coordinate will be set to empty in the AMU database. The volser will be set to 0000000000000000, but the type will remain unchanged. The compartment is ready for the other volsers. For additional information, refer to aci_insert on page 4-75, and aci_eject2 on page 4-42. Return Values • 0: The call was successful. • -1: The call failed.
PAGE 99
aci_ejectclean The aci_ejectclean function ejects all exhausted cleaning cartridges from one Cleanpool. See Figure 4-46. #include "aci.h" int aci_ejectclean( char *areaname, char *Cleanpoolname, int *pnActualCount, struct aci_ei_info *psteiInfo) Figure 4-46 aci_ejectclean Function Call See Figure 4-47 for the structure of the aci_ei_info function. struct aci_ei_info { char volser[ACI_VOLSER_LEN]; char media_type[ACI_DRIVE_LEN]; int errcode }; Figure 4-47 Structure of the aci_ei_info function from aci.
PAGE 100
Table 4-21 Parameters for the aci_ejectclean Function Call Parameter Description aci_ei_info returned information to each ejected volser volser volser of the ejected volume type media type of the named volser Refer to Media Types on page 2-7 errcode error code derrno If the eject area is full the system stops the eject procedure.
PAGE 101
• EBADCLIENT • ERETRYL • EINUSE • ECANCELED • EDASINT • ENOMATCH • ETIMEOUT • ESWITCHINPROG • ENOPOOL • EAREAFULL • EHICAPINUSE • ECOORDINATE • EBARCODE • EINVALIDDEV • ENOROBOT • EDATABASE • ENOTSUPPHCMD • EAREAEMPTY • EBARCODE • EAREAFULL Refer to Figure 4-48 on page 4-60 for an example of the aci_ejectclean function.
PAGE 102
/* Eject clean cartridges from AML system*/ int res, i, pnActualCount; char *Cleanpoolname = "CLP01"; char *areaname = "E02" struct aci_ei_info *ei_info[ACI_EI_MAX_RANGE]; res = aci_ejectclean( areaname, Cleanpoolname, ei_info); if( rec ) { aci_perror( "Command failed: " ); } else { printf("Volume ejects request successful\n" ); for (i = 0; i < ACI_EI_MAX_RANGE; i++) { if ( *ei_info[i]->volser == '\0' ) break; printf( "volser:%s media type:%s Error:%d\n", ei_info[i]->volser, ei_info[i]->media_type, ei_info[
PAGE 103
Table 4-22 Parameter for the aci_email Function Call Parameter Description Adr A non-empty email address of no more than 64 characters Msg defines the email message of no more than 255 characters Only supported by the Scalar DLC software. Return Values • 0: The call was successful. • -1: The call failed.
PAGE 104
Table 4-23 Parameter for the aci_flip Function Call Parameter drive Description name of the optical disk drive for the flip operation Return Values • 0: The call was successful. • -1: The call failed.
PAGE 105
• EBARCODE • EAREAFULL See Figure 4-51 for an example of the aci_flip function. /* Flip a volume in a optical disk drive */ int rc = 0; char *drive = "od01"; if (( rc = aci_flip( drive ) )) { aci_perror( "Flip command failed: " ); } else { printf("Flip of in drive %s successful completed.
PAGE 106
aci_force The aci_force function dismounts any cartridge from a specific drive. See Figure 4-52. #include "aci.h" int aci_force( char *drive ) Figure 4-52 aci_force Function Call Force a dismount from a drive named drive, regardless of which volser is in the drive. See Table 4-24. For additional information, refer to aci_dismount on page 4-16, and aci_mount on page 4-91.
PAGE 107
• EBADCLIENT • ENOTMOUNTED • ECANCELED • EDASINT • ENOMATCH • ETIMEOUT • ESWITCHINPROG • EHICAPINUSE • ECOORDINATE • EBARCODE • EINVALIDDEV • ENOROBOT • EDATABASE • ENOTSUPPHCMD • EAREAEMPTY • EBARCODE • EAREAFULL See Figure 4-53 for an example of the aci_force function. /* Dismount any volume from drive */ int rc = 0; rc = aci_force( "Drive1" ); if( rc ) { aci_perror( "Command failed: " ); } else { printf( "Dismount of Drive1 successful.
PAGE 108
aci_foreign The aci_foreign function catalogs a foreign volume. See Figure 4-54. #include "aci.h" int aci_foreign( enum aci_command action, char *volser, enum aci_media type, char *coordinate, short position ) Figure 4-54 aci_foreign Function Call When a foreign volume named volser of media type has been added to or removed from the AML system in a foreign mount area, DAS must be informed of the status. This function notifies DAS of the existence of the volume, and its coordinate.
PAGE 109
Table 4-25 Parameters for the aci_foreign Function Call Parameter Descriptions position reserved for compatibility, not used This version does not have a command to display occupied symbolic volsers. Please note this assignment; the symbolic volser will be needed for the rmf command. For additional information, refer to aci_dismount on page 4-16, and aci_mount on page 4-91. Return Values • 0: The call was successful. • -1: The call failed.
PAGE 110
/* Add foreign media to DAS catalog */ int rc = 0; enum aci_media type = ACI_3590; char *volser = "FOR001"; char *coord = "E301010310"; short pos = 0; if ((rc = aci_foreign(ACI_ADD, volser, type, coord, pos ))) { aci_perror("Foreign media location failed: "); { else { printf("Foreign volser %s added.\n", volser); } Figure 4-55 Example of the aci_foreign Function. aci_getvolsertodrive The aci_getvolsertodrive function gets the configured relation between the specified drive and the volser.
PAGE 111
struct aci_voltodrive_entry{ char Drive[ACI_DRIVE_LEN]; char VolserRange[ACI_RANGE_LEN]; } Figure 4-57 aci_voltodrive_entry Structure See Table 4-26 for a description of the parameters for the aci_getvolsertodrive function call.
PAGE 112
/* Display volumes reserved for a drive*/ int rc, i, num; char *Drive = "Drive1"; struct aci_voltodrive_entry *drive_inf[ACI_MAX_RANGES]; rc = aci_getvolsertodrive( Drive, num, drive_inf); if( rc ) { aci_perror( "Command failed: " ); } else for (i = 0; i < ACI_MAX_RANGES; i++) { if ( *drive_inf[i]->volser == '\0' ) break; printf( "drive:%s Volser Range%d\n", drive_inf[i]->Drive, drive_inf[i]->VolserRange ); } Figure 4-58 Example of the aci_getvolertodrive Function aci_getVolserToSide The aci_getvolsertos
PAGE 113
struct aci_sideinfo { char cVolumeSide; char szVolser[ACI_VOLSER_LEN]; } Structure of Type aci_sideinfo Figure 4-60 The define ‘ACI_SIDE_NUMBER’ parameter is set, in aci.h, to 2. See Table 4-27.
PAGE 114
/* Display volsers for the optical disk*/ int rc = 0; char *volser = "00815F"; struct aci_sideinfo *sideinfo[ACI_SIDE_NUMBER]; rc = aci_getvolsertoside( volser, sideinfo); if( rc ) { aci_perror( "Command failed: " ); } else printf( "Side:%s Volser:%d\n", side_info[0]->Side, side_info[0]->Volser, side_info[1]->Side, side_info[1]->Volser); } Figure 4-61 Example of the aci_getvolsertoside Function aci_init The aci_init function initializes the AML for client use. See Figure 4-62. #include "aci.
PAGE 115
Return Values • 0: The call was successful. • -1: The call failed. The external variable d_errno is set to one of the following DAS error codes: • ERPC • EINVALID • EDASINT • EBADCLIENT • EDASINT • ETIMEOUT • ESWITCHINPROG See Figure 4-63 for an example of the aci_init function.
PAGE 116
aci_initialize The aci_initialize function initializes ACI library for client use. See Figure 4-64. #include "aci.h" int aci_initialize( void ) Figure 4-64 aci_initialize Function Call This function initializes the DAS 3.01 ACI library. This function should be called as the first activity, before the use of any other functions from the ACI library. For additional information, refer to aci_init on page 4-72. Return Values • 0: The call was successful. • -1: The call failed.
PAGE 117
aci_insert The aci_insert function inserts volumes into the AML. See Figure 4-66. #include "aci.h" int aci_insert( char *insert_area, char *volser_ranges, enum aci_media type ) Figure 4-66 aci_insert Function Call This function is for compatibility. Please use the aci_insertgen function. The cartridges which are actually located in the insert area of the AML and registered by the AMU (automatically inventoried after closing the area) will be inserted.
PAGE 118
Use the insert2 function instead of this command. This function experiences difficulties with large I/O units with long volsers (16-digit) since the buffer for displaying the inserted volser is restricted. For compatibility reasons this function continues to be supported. For additional information, refer to aci_insert on page 4-75, and aci_eject2 on page 4-42. Return Values • 0: The call was successful. • -1: The call failed.
PAGE 119
• EBARCODE • EAREAFULL Refer to Figure 4-67 on page 4-77 for an example of the aci_insert function.
PAGE 120
• Volsers which already have a entry in the AMU database, will be moved to this position. • Volsers which have no entry in the AMU database, will be moved to the first free slot (AMU database Attribute: "Empty" of this media type of the Type AMU-Dynamic) • With insertopt -c will move the cartridges to the first free slot (AMU database Attribute: "Empty") of this media type of the Type AMU-Dynamic.
PAGE 121
Table 4-29 Parameters for the aci_insert2 Function Call Parameter Description aci_ei_info returned information on each volser ejected volser volser of the ejected volume type media type of the named volser Refer to Media Types on page 2-7 errcodes error code derrno Return Values • 0: The call was successful. • -1: The call failed.
PAGE 122
• EDATABASE • ENOTSUPPHCMD • EAREAEMPTY • ENOPOOL • EBARCODE • EAREAFULL See Figure 4-70 for an example of the aci_insert2 function.
PAGE 123
aci_inventory The aci_inventory function performs a physical inventory of the AML. See Figure 4-71. #include "aci.h" int aci_inventory( void ) Figure 4-71 aci_inventory Function Call This command instructs the robot to perform a physical inventory of the archive and to update the database. The inventory command is issued to the archive and the function will not wait for the completion of the inventory operation.
PAGE 124
• EHICAPINUSE • ECOORDINATE • EBARCODE See Figure 4-72 for an example of the aci_inventory function. /* Inventory the AML */ int rc = 0; rc = aci_inventory( ); if( rc ) { aci_perror( "Command failed:" ); } Figure 4-72 Example of the aci_inventory Function aci_killamu The aci_killamu function homes the robots and shuts down all programs running on the AMU PC (including OS/2). See Figure 4-73. #include "aci.
PAGE 125
Return Values • 0: The call was successful. • -1: The call failed. The external variable d_errno is set to one of the following DAS error codes: • ENOTAUTH • ERPC • EINVALID • EDASINT • ETIMEOUT • EAMUCOMM • EHICAPINUSE • ESWITCHINPROG See Figure 4-74 for an example of the aci_killamu function.
PAGE 126
aci_list The aci_list function lists outstanding requests for a client. See Figure 4-75. #include "aci.h" int aci_list( char *clientname, struct aci_req_entry *request_list[ACI_MAX_REQ_ENTRIES]) Figure 4-75 aci_list Function Call List outstanding requests belonging to the client clientname. Return the requests in the request_list array of aci_req_entry request_list structures. The structure’s request types are defined in the header file "aci_das.h". See Figure 4-76.
PAGE 127
Table 4-30 Parameters for the aci_list Function Call Parameter Description clientnamet Name of the client that active request are reported to. aci_req_entry Returned information about outstanding commands request_no DAS command sequence serial number individ_no reserved, not used clientname name of the requesting client req_type type of the outstanding command Refer to Table 4-31 See Table 4-31 for an explanation of the req_types.
PAGE 128
Return Values • 0: The call was successful. • -1: The call failed. The external variable d_errno is set to one of the following DAS error codes: • ERPC • EINVALID • EDASINT • ETIMEOUT • ESWITCHINPROG See Figure 4-77 for an example of the aci_list function.
PAGE 129
aci_list2 The aci_list2 function lists executing requests for a client. See Figure 4-78. #include "aci.h" int aci_list2( char *clientname, struct aci_req_entry2 *req_status[]) Figure 4-78 aci_list2 Function Call List executing requests belonging to the client clientname. Return the requests in the array of aci_req_entry2 structures. The array element can be maximum size of 15. See Figure 4-79.
PAGE 130
Table 4-32 Parameters for the aci_list2 Function Call Parameter Description clientname Name of the client that receives the active request information.
PAGE 131
Table 4-33 Explanation of the Req_types req_types Explanation PINV Complete archive inventory and database update (aci_inventory) PRGE Delete a command from the command list (aci_cancel) SHUT Shutdown off the complete AMU (aci_killamu) Return Values • 0: The call was successful. • -1: The call failed.
PAGE 132
struct aci_foreign_desc { char volser[ACI_VOLSER_LEN]; char coord[ACI_COORD_LEN]; enum aci_media_type eType; char attrib }; Figure 4-81 Example of the Returned Structure Refer to Table 4-34 for a description of the parameters for the aci_list_foreign function call.
PAGE 133
aci_mount The aci_mount function mounts a volume in a drive. See Figure 4-82 #include "aci.h" int aci_mount( char *volser, enum aci_media type, char *drive ) aci_mount Function Call Figure 4-82 Mount the volume named volser of media type type in the drive named drive. The volume will then be available to the requesting client. See Table 4-35. For additional information, refer to aci_dismount on page 4-16, and aci_scratch_set on page 4-114, and aci_view on page 4-123.
PAGE 134
• EDRVOCCUPIED • EPROBVOL • EAMU • EAMUCOMM • EROBOTCOMM • EDASINT • EDEVEMPTY • ENOTAUTH • EUPELSE • EBADCLIENT • ERETRYL • EINUSE • ENOTFOUND • ECANCELLED • EDASINT • ENOMATCH • ECLEANING • ETIMEOUT • ESWITCHINPROG • EHICAPINUSE • ECOORDINATE • EBARCODE • EINVALIDDEV • ENOROBOT • EDATABASE • ENOTSUPPHCMD • ECOORDINATE • EPROBDEV • EBARCODE • EAREAFULL Refer to Figure 4-83 on page 4-93 for an example of the aci_mount function.
PAGE 135
/* Mount volume in specific drive */ int rc = 0; rc = aci_mount( "AAB001", ACI_3590, "Drive2" ); if( rc ) { aci_perror( "Command failed:" ); } else { printf( "Mount of %s successful.\n", volser ); } Figure 4-83 Example of the aci_mount Function aci_partial_inventory The aci_partial_inventory function inventories part of the AML (only in one device). See Figure 4-84. #include "aci.
PAGE 136
Table 4-36 Parameter Description SourCoor 10 digit logical coordinate of the device for the start of the inventory (defined in the AMU database), e.g. L501010101 TargetCoor 10 digit logical coordinate of the device for the end of the inventory (defined in the AMU database), e.g. L501011310 Source and targeted must be in the same device. Attention 4-94 Parameters for the aci_partial_inventory Function Call DAS ACI Functions The aci_partial_inventory function is intended for testing and startup.
PAGE 137
Return Values • 0: The call was successful. • -1: The call failed. The external variable d_errno is set to one of the following DAS error codes: • ERPC • EINVALID • ENOVOLUME • EPROBVOL • EAMU • EAMUCOMM • EROBOTCOMM • EDASINT • ERETRYL • ENOTFOUND • ECANCELLED • EDASINT • ETIMEOUT • ESWITCHINPROG • EHICAPINUSE • ECOORDINATE • EBARCODE See Figure 4-85 for an example of the aci_partial_inventory function.
PAGE 138
aci_perror The aci_perror function writes DAS error text to standard error. See Figure 4-86. #include "aci.h" int aci_perror( char *error_prefix ) Figure 4-86 aci_perror Function Call The aci_perror function writes an error message to the standard error device, describing the last error encountered. The error message is either returned by the DAS server, or if not available, the error message is selected according to the value stored in d_errno.The parameter error_prefix is attached to the message.
PAGE 139
aci_qversion The aci_qversion function queries the version string of ACI and DAS component. See Figure 4-88. #include "aci.h" int aci_qversion( char *aciver, char *dasver ) aci_qversion Function Call Figure 4-88 Query the version of the installed ACI and DAS component. This function allows the client to determine that the correct software component prerequisite is installed.
PAGE 140
/* Check DAS and ACI version */ int rc = 0; char szACIVersion[ ACI_MAX_VERSION_LEN ] = ""; char szDASVersion[ ACI_MAX_VERSION_LEN ] = ""; if( ( rc = aci_qversion( (char *) &szACIVersion, (char *) &szDASVersion ) ) ) { aci_perror("Version request failed: "); } else { printf("DAS-Version : %s\n", szDASVersion ); } printf("ACI-Version : %s\n", szACIVersion ); /*always OK */ Figure 4-89 Example of the aci_qversion Function aci_qvolsrange The aci_qvolsrange queries the list of available volsers.
PAGE 141
Volser Ranges defined for Client Archive Catalog Range defined with startvolser and endvolser with aci_qvolsrange listed volsers Figure 4-91 Amount of Listed Volsers See Figure 4-92 for the aci_volserinfo function structure. struct aci_volserinfo { char volser[ACI_VOLSER_LEN]; enum aci_media media_type; char attrib; }; Figure 4-92 Structure for the aci_volserinfo See Table 4-39 for a description of the parameters for the aci_qvolsrange function call.
PAGE 142
Table 4-39 Parameters for the aci_qvolsrange Function Call Parameter Description number_of_returned_volser number of the volsers actually found in the range aci_volserinfo volser barcode number of the volser media_type media type of the volser attrib status of the volser If the startvolser and endvolser parameters are set to the NULL string ("" or ’\0’), a search will start at the smallest database entry defined for the client and end at the largest database entry defined for the client.
PAGE 143
Table 4-40 Explanation of the Attrib Values Name attrib Explanation ACI_VOLSER_ATTRIB_ TEMP_HERE T temp here (slot occupied, medium in the problem box) ACI_VOLSER_ATTRIB_ TEMP_AWAY A temp away (medium temporarily not at the specified coordinates, in transit on AML/2 with double robotic controller systems) Return Values • 0: The call was successful. • 1: More data is available. • -1: The call failed.
PAGE 144
/* Query volser range */ int rc = 0; char szBeginVolser[ ACI_VOLSER_LEN ] = ""; char szEndVolser [ ACI_VOLSER_LEN ] = ""; char szClient [ ACI_NAME_LEN ] = ""; int nCount = ACI_MAX_QUERY_VOLSRANGE; int nActualCount = 0; int nFor; struct aci_volserinfo stVolsRange[ nCount ]; rc = aci_qvolsrange((char *) &szBeginVolser, (char *) &szEndVolser, nCount, (char *) &szClient, &nActualCount, (struct aci_volserinfo *) &stVolsRange ); if( rc == -1 ) aci_perror("Command failed: "); else { printf( "\nnext volser %s", szB
PAGE 145
aci_register The aci_register function registers a client. See Figure 4-94. #include "aci.h" int aci_register( char *client, char *host, enum aci_command action, bool_t avc, bool_t complete, bool_t dismount, Figure 4-94 aci_register Function Call Clients are defined for the DAS server by the DAS configuration file. However, clients may be registered temporarily with the aci_register function.
PAGE 146
Table 4-41 Parameters for the aci_register Function Call Parameter Description avc true or false option avoid volume contention (Refer to the DAS Administration Guide) complete true or false selection between basic or complete command set (Refer to Client Services on page 2-4) dismount true or false optional dismount; for configuring an automatic dismount without DAS command (Refer to the DAS Administration Guide) Return Values • 0: The call was successful. • -1: The call failed.
PAGE 147
/* Modify existing client configuration */ int rc =0; char *client = "SomeClient"; char * ipname = "CLIENT1"; enum aci_command action; short avc; short c; short dism; int i, j; struct aci_client_entry client_entry; rc = aci_clientstatus (client, &client_entry); if ( !rc ) { action = ACI_MODIFY; avc = client_entry.avc; dism= client_entry.dismount; c = FALSE; rc=aci_register(client,ipname,action,avc,c,dism); if( rc ) aci_perror("Command failed: "); else printf ("Client %s updated.
PAGE 148
aci_robhome The aci_robhome function sets the robot (accessor in Scalar 1000) in the AML to off-line and moves it to the home position. See Figure 4-96. #include "aci.h" int aci_robhome(char *szRobot) Figure 4-96 aci_robhome Function Call The call of this function sends the robot with number ‘szRobot’ to the home position. See Table 4-42.
PAGE 149
• EHICAPINUSE • ECOORDINATE • EDATABASE • ENOTSUPPHCMD See Figure 4-97 for an example of the aci_robhome function. /* Robot Homing */ int rc = 0; rc =aci_robhome("R1"); if( rc ) { aci_perror( "Command failed:" ); } else { printf( "robot is now home.\n"); } Figure 4-97 Example of the aci_robhome Function aci_robstat The aci_robstat function starts the robot or gets the status of the robot. See Figure 4-98. #include "aci.
PAGE 150
Table 4-43 Parameters for the aci_robstat Function Call Parameter Description szRobot the defined robot of a twin AML system R1 Robot 1 of AML (must also be used for all single AML system) R2 Robot 2 of the twin AML START or start in szRobot, set the defined Robot to online STAT or stat ask the AMS for the status of the robots, parameter szRobot must set to NULL szAction Return Values • 0: The call was successful • -1: The call failed The external variable d_errno is set to one of the foll
PAGE 151
/* Check robot status */ int rc; char szRobot[ 3 ] = "R1"; char szAction[ 5 ] = "STAT"; if( ( rc = aci_robstat(szRobot, szAction))) { aci_perror("Version request failed: "); } else { printf("Robstat 1 : %s\n", szSourceCoord ); printf (“robstat sucessful\n) } Figure 4-99 Example of the aci_robstat Function aci_scratch_get The aci_scratch_get function gets a scratch volume. See Figure 4-100. #include "aci.
PAGE 152
Table 4-44 Parameters for the aci_scratch_get Function Call Parameter Description subpool stored name of the pool for scratch media in the AMU database If the volume is to be taken from a default subpool of a media type, set type to the media type of the volser and set subpool to the NULL string (““ or ‘\0’) type type of media in the named subpool (Refer to Media Types on page 2-7) volser first scratch volser of the named subpool found in the AMU database, independent of the status of the volser (e
PAGE 153
/* Get volser of new scratch media */ int rc; char *pszPoolName = ""; enum aci_media type = ACI_3590; char szVolser[ACI_VOLSER_LEN]; rc = aci_scratch_get (pszPoolName, type, pszVolser); if( rc ) { aci_perror ("Command failed: "); } else { printf ("Scratch volser %s found.\n", szVolser); } Figure 4-101 Example of the aci_scratch_get Function aci_scratch_info The aci_scratch_info function gets information about a scratch pool. See Figure 4-102. #include "aci.
PAGE 154
Table 4-45 Parameters for the aci_scratch_info Function Call Parameter Description subpool stored name of the pool for scratch media.
PAGE 155
/* List scratch pool information */ int rc; char *pszPoolName = ""; enum aci_media type = ACI_3590; long lVolserCount, lScratchCount; if ((rc = aci_scratch_info (pszPoolName, type, &lVolserCount, &lScratchCount)) != 0 ) { aci_perror ("Command failed: "); } else { if (strcmp (pszPoolName, "") == 0) { printf ("DEFAULT_POOL:VolserCount:%d, ScratchCount:%d\n", lVolserCount, lScratchCount); } else { printf ("%s: VolserCount: %d, ScratchCount: %d \n", pszPoolName, lVolserCount, lScratchCount); } } Figure 4-103
PAGE 156
aci_scratch_set The aci_scratch_set function sets volume status to scratch. See Figure 4-104. #include "aci.h" int aci_scratch_set( char *subpool, enum aci_media type, char *volser ) Figure 4-104 aci_scratch_set Function Call Set volume named volser of media type type to scratch status in the scratch pool named subpool. The subpool is created if it does not exist. If a subpool is not specified and set to the NULL string ("" or ’\0’), the default pool will be used.
PAGE 157
The command will be rejected with the message EOTHERPOOL if the medium already exists in another scratch pool. For additional information, refer to aci_scratch_unset on page 4-116. Return Values • 0: The call was successful. • -1: The call failed. The external variable d_errno is set to one of the following DAS error codes: • EINVALID • EDASINT • ENOPOOL • ERPC • ETIMEOUT • ESWITCHINPROG • EDATABASE • ENOTSUPPHCMD See Figure 4-105 for an example of the aci_scratch_set function.
PAGE 158
aci_scratch_unset The aci_scratch_unset function resets the scratch status of a volume. See Figure 4-106. #include "aci.h" int aci_scratch_unset( char *subpool, enum aci_media type, char *volser ) Figure 4-106 aci_scratch_unset Function Call Reset the status of volume named volser in the scratch pool named subpool from scratch to non-scratch media and remove the volser from subpool. If subpool is set to the NULL string ("" or ’\0’) the default pool will be used.
PAGE 159
Return Values • 0: The call was successful. • -1: The call failed. The external variable d_errno is set to one of the following DAS error codes: • EINVALID • EDASINT • ENOPOOL • ERPC • ETIMEOUT • ESWITCHINPROG • EDATABASE • ENOTSUPPHCMD See Figure 4-107 for an example of the aci_scratch_unset function.
PAGE 160
aci_shutdown The aci_shutdown function shuts down the DAS software. See Figure 4-108. #include "aci.h" int aci_shutdown (char *now) Figure 4-108 aci_shutdown Function Call This function shuts down the DAS server. Once the request has been accepted, no other request will be accepted. A restart of the DAS server is necessary to resume DAS operations. See Table 4-48.
PAGE 161
/* Shut down DAS operation */ int rc; char *now = NULL; if ((rc = aci_shutdown(now))) { aci_perror("Shut down failed:"); } else { printf("Shut down successful.\n"); } Figure 4-109 Example of the aci_shutdown Function aci_snmp The aci_snmp function sends SNMP messages. See Figure 4-110. #include "aci.h" int aci_snmp (char *Msg) Figure 4-110 aci_snmp Function Call See Table 4-49.
PAGE 162
The external variable d_errno is set to one of the following DAS error codes: • ERPC • EINVALID • ETIMEOUT • ESWITCHINPROG • EBADCLIENT • ENOTSUPPHCMD aci_switch The aci_switch function switches the passive AMU to active. See Figure 4-111. #include "aci.h" int aci_switch (char *Switch) Figure 4-111 aci_switch Function Call Allow the second AMU to be used without manual intervention, if the first AMU-PS is down. An installed and running Dual-AMU is necessary for this function. See Table 4-50.
PAGE 163
Return Values • 0: The call was successful. • -1: The call failed. The external variable d_errno is set to one of the following DAS error codes: • ENOTAUTH • ERPC • EINVALID • EDASINT • ETIMEOUT • EAMUCOMM • EHICAPINUSE • ESWITCHINPROG • ENOTSUPPHCMD See Figure 4-112 for an example of the aci_switch function. /* Switch to the Dual AMU */ int rc; char *Switch = "-n"; if ((rc = aci_switch(Switch))) { aci_perror("Swicht actual not possible:"); } else { printf("Now the Dual AMU is active.
PAGE 164
aci_unload The aci_unload function presses one or more buttons on a drive in the AML. See Figure 4-113. #include "aci.h" int aci_unload(char *szDrive) Figure 4-113 aci_unload Function Call See Table 4-51 for an description of the parameter for the aci_unload function.
PAGE 165
aci_view The aci_view function is used to view a database entry for a volume. See Figure 4-114. #include "aci.h" int aci_view( char *volser, enum aci_media type, struct aci_volume_desc *desc ) Figure 4-114 aci_view Function Call Return the database entry for the volume named volser of media type type. The database entry is returned in the aci_volume_desc structure. See Figure 4-115. For additional information, refer to aci_qvolsrange on page 4-98, and aci_inventory on page 4-81.
PAGE 166
Table 4-52 Parameters for the aci_view Function Call Parameter Description volser volser specifying the medium for which information is being queried type media type to which the volser belongs Refer to Media Types on page 2-7 aci_volume_desc structure with the returned data from the AMU database table COORDINATES coordinate 10-digit logical coordinate specifying the slot (Refer to the AMU Reference Manual) owner number of the robot which can access the home coordinate of the named volser (1 = r
PAGE 167
See Table 4-54 for an explanation of the table attributes.
PAGE 168
/* Get volume information */ int rc; enum aci_media type = ACI_3590; char *volser = ""; struct aci_vol_desc desc; if ( rc = aci_view(volser, type, &desc )) { aci_perror("view failed"); } else { printf("Volser=%s Type=%c Attrib=%c\n\tcoordinate =%s\n" "\tuse count = %d\n\", desc.volser, desc.type, desc.attrib, desc.coord, desc.use_count; } Figure 4-116 Example of the aci_view Function aci_volser_inventory The aci_volser_inventory function inventories the volsers within the AML. See Figure 4-117.
PAGE 169
Table 4-55 Parameters for the aci_volser_inventory Function Call Parameter Description pszVolser Pointer to an individual volser status Indicator to determine manipulate of the database ACI_INVT_NOTUPDT 0 = do not update the database ACI_INVT_UPDT 0 = update the database Return Values • 0: The call was successful • -1: The call failed The external variable d_errno is set to one of the following DAS error codes 21 Dec 2001 • ERPC • EINVALID • ENOVOLUME • EPROBVOL • EAMU • EAMUCOMM
PAGE 170
aci_volseraccess The aci_volseraccess function sets ownership of a volser or range of volsers. See Figure 4-118. #include "aci.h" int aci_volseraccess(char *ClientName , char *VolserRange, enum aci_volser_status status) Figure 4-118 aci_volseraccess Function Call Modify allocation status of a volser for a specified client. Refer to Table 4-56 .
PAGE 171
• EUPELSE • ERPC • EINVALID • ENOVOLUME • EDASINT • EBADCLIENT • ENOTAUTH • ETIMEOUT • ESWITCHINPROG • EUPOWN aci_volserstatus The aci_volserstatus function queries ownership of the volser. See Figure 4-119. #include "aci.h" int aci_volserstatus char *ClientName, int *num char *VolserRange, struct aci_volser_entry *VolserEntry[ACI_MAX_VOLSER_ENTRIES] Figure 4-119 aci_volserstatus Function Call Returns the status of volsers which are set to UP for the client with name clientname.
PAGE 172
Figure 4-120 aci_volser_entry Structure See Table 4-57 for a description of the parameters for the aci_volserstatus function call.
PAGE 173
5 DAS ACI 3.0 Asynchronous Support Layer Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3 How It Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3 Sadmin Sample Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3 Sadmin Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 174
aci_eject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-19 Return Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-19 aci_eject_complete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-19 Return Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 175
5- Overview Asynchronous Support Layer library works as a filter between existing ACI libraries (version 3 or later) and the client application, which wants to issue asynchronous ACI calls. Since the native ACI interface is synchronous, a client had to wait for the completion of the request. Now using special programming techniques, developers who want to use ACI in an asynchronous manner can use the Asynchronous Support Layer library of this purpose.
PAGE 176
• eject: eject/elect complete volsers • allocv: allocate volser • allocd: allocate drive • script: run the commands from a script file This application can run in both single command and scripting modes. To stop this application, press + or use the KILL command. Sadmin Syntax The syntax of the sadmin sample application has two general forms: • sadmin [-h] | [[] [] ...
PAGE 177
aci_async_add - adds an entry in the shared memory area aci_async_create - creates and initializes the shared memory area aci_async_find - finds required shared memory table entry aci_async_free - frees required shared memory table entry There is also a header file for C developers, aci_async.h, defining all the required structures and macros for development of software using the ACI asynchronous support.
PAGE 178
das_mount The aci_async_add function with the das_mount parameter mounts a volume in a drive. See Figure 5-2 aci_asycn_add (das_mount, *volser, *type, *drive) Figure 5-2 aci_async_add Function with the das_mount Parameter Mount the volume named volser of media type type in the drive named drive. The volume will then be available to the requesting client. See Table 5-1.
PAGE 179
das_dismount The aci_async_add function with the das_dismount parameter dismounts a volume. See Figure 5-4. aci_async_add (das_dismount, *volser, *type) Figure 5-4 aci_async_add Function with the das_dismount Parameter Dismount the volume volser of defined media type from its drive. The drive is identified by the DAS software. For additional information, refer to das_mount on page 5-6. Retries can be configured in the config file or in the AMS configuration.
PAGE 180
Table 5-3 Parameter for the das_force Parameter Parameter drive Description name of the drive for the dismount das_insert The aci_async_add function with the das_insert parameter inserts volumes into the AML. See Figure 5-6. aci_async_add (das_insert, *insert_area, *volser_range, *type) Figure 5-6 aci_async_add Function with the das_insert Parameter This function is for compatibility. Please use the aci_insertgen function.
PAGE 181
Table 5-4 Parameters for the das_insert Parameter Parameter Description insert_area Logical insert range of the Insert/Eject unit of the AML in the AMS (e.g. I03) volser_range The volumes found in the insert_area are returned in the volser_ranges array of strings, where each volser is separated by a comma. Each range is ACI_RANG_LEN long and there are up to ACI_MAX_RANGES ranges.
PAGE 182
Table 5-5 Parameters for the das_eject Parameter Parameter Description eject_area Logical area defined in AML, where the cartridges should be ejected volser_ranges • a single volser • multiple volsers separated by commas • a range of volsers separated by a hyphen types media type of the named volser Refer to Media Types on page 2-7 The database entry for the volume is not deleted, and the position in the AML that the volume occupied remains reserved for insertion of a volume with a matching volser.
PAGE 183
space is needed in the AML. If the volume is re-inserted into the AML, it is stored in the next available position, and it probably will not occupy the previous position. The volume is re-inserted in the same position only if das_eject is used. See Table 5-6 for a description of the parameters for the das_eject_complete parameter.
PAGE 184
. . . /* * sadmin sample application, dasadmin.c file * aci_async.
PAGE 185
aci_async_create() The aci_async_create function creates a shared memory array of the entry_num size, that will hold the requests sent. See Figure 5-10 #include "aci_async.h" aci_async_entry* aci_async_create(long entry_num); aci_async_create Function Call Figure 5-10 See Table 5-7 for a description of the parameter for the aci_async_create function.
PAGE 186
. . . /* * sadmin sample application, dasadmin.c file * creating a table in shared memory - 50 entries */ if( ( async_entry = aci_async_create( 50L ) ) == 0 ) { aci_perror( "create async failed" ); return 1; } . . . Figure 5-11 Example if the aci_async_create Function aci_async_find() The aci_async_find function looks for the appropriate aci_async_entry in shared memory array. If an entry has the same value in the pid field as pid parameter it is returned. See #include "aci_async.
PAGE 187
Return Values The call was successful if a pointer to the found value is returned. The call failed if zero is returned The structure of the aci_async_entry uses a pid_t type member pid as a unique identifier of an entry. When calling several asynchronous calls at a time the system can assign the same process id to a new process when a previous call has terminated. This could cause duplicate values the in pid fields of shared memory array entries. Refer to Response Technique on page 5-21.
PAGE 188
aci_async_free() The aci_async_free function clears the async_table entry. See Figure 5-14. #include "aci_async.h" void aci_async_free(aci_async_entry* async_entry); Figure 5-14 aci_async_free Function Call Table 5-9 Parameters for the aci_async_free Function Parameter async_entry Description pointer to an aci_async_entry that should be cleaned Return Values None This call only clears the pid field in the appropriate aci_async_entry structure. Macros The aci_async.
PAGE 189
All the parameters must comply with the rules for aci_mount function call. The local variables int res must be defined before using this macro. Return Values The d_errno and d_text globals are copied to d_errno and d_text fields of shared memory array entry. The process is terminated by the exit() call with the res exit code. If there are problems with shared memory attachment, d_errno global will be set to ENOSHARED. aci_dismount The aci_dismount function dismounts a volume. See Figure 5-16.
PAGE 190
#include "aci_async.h" ACI_FORCE(drive) Figure 5-17 aci_force Asynchronous ACI Call All the parameters must comply with the rules for the aci_force function call. The local variable int res must be defined before using this macro. Return Values The d_errno and d_text globals are copied to d_errno and d_text fields of shared memory array entry. The process is terminated by the exit call with the res exit code. If there are problems with shared memory attachment, d_errno global will be set to ENOSHARED.
PAGE 191
aci_eject The aci_eject function ejects a range of volumes from the AML. See Figure 5-19. #include "aci_async.h" ACI_EJECT(eject_area, volser_range, type) Figure 5-19 aci_eject Asynchronous Function Call All the parameters must comply with the rules for the aci_eject function call. The local variable int res must be defined before using this macro. Return Values The d_errno and d_text globals are copied to the d_errno and d_text fields of the shared memory array entry.
PAGE 192
Return Values The d_errno and d_text globals are copied to the d_errno and d_text fields of the shared memory array entry. The process is terminated by the exit call with the res exit code. If there are problems with the shared memory attachment, the d_errno global will be set to ENOSHARED. 5-20 DAS ACI 3.
PAGE 193
Response Technique This section describes the most desirable response processing technique. Setup The following code should be executed upon startup. This code installs a signal handler, which will be automatically run every time one of the child processes terminates. At this point retrieve the results, place them into internal data structures and free the shared memory array entry. See Figure 5-21. . . . /* dasadmin sample application, dasadmin.
PAGE 194
Signal Handler Routine The following code processes the result of child process work. At the point this function is run, the results are placed in the shared memory array entry, and developer should program the logic that will take the results from there and place them somewhere else. The dasadmin sample application puts all the data into the standard output. See Figure 5-22. /* dasadmin sample application, wait_for_child.
PAGE 195
Data structures This section provides and overview of the data structures used in asynchronous ACI data interchange. The shared memory array consists of several entries of type aci_async_entry. The exact number should be set in the aci_async_create call.
PAGE 196
struct _aci_async_entry { pid_t pid; means slot is empty */ int aci_func; DAS_DISMOUNT, DAS_FORCE, /* process id, -1 /* DAS_MOUNT, DAS_INSERT, DAS_EJECT, DAS_EJECT_COMPLETE */ int d_errno; /* DAS error code */ char d_text[DAS_SZ_MSG_LEN]; /* error message */ union _parms /* parameters data */ { async_drive_parms st_drive_parms; /* mount, dismount, force parameters */ async_ei_parms st_ei_parms; /* insert, eject, eject_complete parameters */ } parms; union _response response data */ { async_mount_parms st_
PAGE 197
Parameter Data (Parms Structure) This union contains several structures that hold the data required for making an appropriate ACI call. All the constants, starting with XDR, are defined in aci_xdr.h file. Some of the structures contain unusable data fields. This is done for better compatibility with RPC structures. Developers who do not use the macros, may need to fill in the structures. If the macros are used, the developer only needs to take note of what the macros do.
PAGE 198
Response Data (Structure) This union contains several structures where the asynchronous call results are stored after the call is completed. st_response This structure is reserved for possible future use. Asynchronous ACI developer could use it for storing data. See Figure 5-26. struct async_response { int code; char text[XDR_TEXT_LEN]; }; Figure 5-26 async_response Structure st_mount_parms This structure is reserved for possible future use. Asynchronous ACI developer could use it for storing data.
PAGE 199
st_insert_response This structure is supported by ACI_INSERT macro, described above. If you do not use macros, you could fill it with appropriate data after aci_insert() call returns. ACI_INSERT macro also fills the member volser_ranges_len with the actual size of volser_ranges_val array, which could be less that XDR_NO_RANGES in most cases. See Figure 5-28.
PAGE 200
5-28 DAS ACI 3.
PAGE 201
A Application Notes Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3 Error Recovery Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3 Terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 202
A-2 Application Notes 601626-B
PAGE 203
A- Overview This section contains information on error recovery procedures and explanations of terms used throughout this document. Error Recovery Procedures This section contains information on error recovery procedures. See Table A-1. Table A-1 Number Error Code Reactions d_error Name Recommended Reactions to the Error Code 0 EOK No error. 1 ERPC Communication problem, test the TCP/IP to the AMU PC and, if possible, try an alternate route.
PAGE 204
Table A-1 Number Error Code Reactions d_error Name Recommended Reactions to the Error Code 6 EPROBVOL The AMS returned a error code from robot control or information about an unrecoverable situation in the AML. Stop the command that returned this error. Refer to the AMU-Log for more information. 7 EAMU The AMS returned an unexpected error. Stop the command that returned this error. Refer to the AMU-Log for more information.
PAGE 205
Table A-1 Number Error Code Reactions d_error Name Recommended Reactions to the Error Code 14 EBADHOST DAS was unable to resolve the IP-name to an address, or the address is invalid. Check the TCP/IP command. Set the IP-configuration and change configuration data in AMU or the environment. 15 ENOAREA The named insert or eject area was not found in the configuration. Try the command with another area name, or change the AMS configuration.
PAGE 206
Table A-1 Number 22 Error Code Reactions d_error Name ERERTRYL Recommended Reactions to the Error Code The maximum number of automatic retries for recovering has been exceeded. There is a problem in the AMS. Check the AMU-Log for more information: • <0420> Cartridge not ejected. • The dismount manager is not configured correctly (Refer to the AMU Reference Guide). • The drive has not received the unload command (send unload via data path to the drive or to DAS aci_unload.
PAGE 207
Table A-1 Number 21 Dec 2001 Error Code Reactions d_error Name Recommended Reactions to the Error Code 26 ENOTFOUND Problem with parameters in the command. Check the command and confirm the parameters with the AMS configuration. 27 ECANCELLED A command was canceled with the aci_cancel command or on the AMS. 28 EDASINT An internal DAS error has occurred. Restart DAS. Save the Log and inform ADIC support about the error situation. 29 EACIINT An internal ACI error has occurred. Restart DAS.
PAGE 208
Table A-1 Number A-8 Error Code Reactions d_error Name Recommended Reactions to the Error Code 35 ESWITCHINPROG The commands can not be executed. DAS and AMS are being switched to the other AMU. Wait until the switching process is completed and try again. 36 ENOPOOL There has been an attempt to insert or eject cleaning cartridges to a cleanpool that has not been configured. Confirm the cleanpool name in the command with the cleanpool names in the AMS configuration.
PAGE 209
Table A-1 Error Code Reactions Number d_error Name Recommended Reactions to the Error Code 45 EUPOWN The Client tried to allocate volsers that are already allocated. 46 ENOTSUPPHCMD The AMU has a command exclusion feature that can be used to configure which DAS commands are supported. The command that wes sent to the AMU is configured as a not supported host command. Refer to the AMU Administration Guide if this needs to be changed. 47 EDATABASE Check the AMU log for a more detailed message.
PAGE 210
API Application Program Interface A program residing on the client’s platform used to interpret the client’s requests and to provide all the network communication compatible with the interface requirements. Archive The archive consists of: • physical archive • logical archive. The physical archive consists of storage segments for tape cartridges and optical disks (= media). The logical archive (archive catalog) is the list of volsers assigned to the compartments in the physical archive.
PAGE 211
21 Dec 2001 Drive A device used to read and write data on a medium. eject The physical action of removing a medium from an archive. For a robotic archive, the medium is robotically moved to the unload port for removal by the operator. Eject area The logical location within the I/O unit that accepts ejected media. Ethernet Interface standard defined by IEEE Standard 802.3 File An individual collection of related data (e.g.; a letter, a table, a digitized photograph).
PAGE 212
A-12 Application Notes Network The physical and logical connection of computers and peripheral devices that allows communication and data sharing. Network Protocols A set of rules defining the physical and logical connection. OS/2 Operating system (multitasking, single user) that is used on the AMU controller PC. PC Personal Computer. RAM Random Access Memory Robotic archive A storage system featuring one or more robots for media handling.
PAGE 213
Volser, VSN 21 Dec 2001 Volume Serial Number An up to sixteen-digit alphanumeric designation. It identifies one medium (cartridge, optical disk) in the archive. Exception: optical disk has one logical compartment but two volsers (A and B side). The volser is attached to the rear of the medium on a barcode label and can be read by the handling unit.
PAGE 214
A-14 Application Notes 601626-B
PAGE 215
Index -AACI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4 ACI (AML Client Interface) . . . . . . . . . . . . . . . . . 2-4 ACI client administration . . . . . . . . . . . . . . . . . . . . . . . . . 2-5 ACI client services basic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5 complete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5 ACI interface types command line . . . . . . . . . . . . . . . . . . . . . . . . . 2-4 aci.h . . . . . .
PAGE 216
add volume to scratch pool . . . . . . . . . . . . . . 2-7 cancel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5 change client access . . . . . . . . . . . . . . . . . . . . 2-5 change client drive status . . . . . . . . . . . . . . . 2-5 dismount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5 drive status . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5 eject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5, 2-6 eject complete . . . . . . . . . .
PAGE 217
Drive status . . . . . . . . . . . . . . . . . . . . . . 4-5, 4-9, 4-21 ACI client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5 -EEject . . . . . . . . . . . . . . . . . . . . . 4-39, 4-42, 4-51, 4-57 ACI client . . . . . . . . . . . . . . . . . . . . . . . . . 2-5, 2-6 Eject complete ACI client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6 -FForce . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-61, 4-64 ACI client . . . . . . . . . . . . . . . . . . . . .
PAGE 218
Scratch unset . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-116 Set scratch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-111 Setenv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-111 Shutdown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-118 ACI client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7 shutdown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-82 Signal Handler . . . . . . . . . . . . . . . . . . .