Command Reference VolServ Version 5.
Trademark Notice AMASS, DataMgr, EMASS, FileServ, and VolServ are either trademarks or registered trademarks of ADIC, Advanced Digital Information Corporation. DAS is a trademark of Grau, an ADIC subsidiary. All other product names and identifications are trademarks or registered trademarks of their respective manufacturers. Copyright Notice © 1996-2001 ADIC®. All rights reserved. This document is the property of ADIC.
READER COMMENT FORM ADIC includes this Form in an effort to provide the best possible documentation to our customers. Please take a few moments to mail or FAX your response to: ADIC Software Documentation 10949 East Peakview Ave. Englewood, CO 80111 FAX: 303-792-2465 E-mail: techdocs@adic.com Question Circle One Information was complete. Agree Disagree Information was easy to find. Agree Disagree Information was easy to follow.
NOTES
Contents Preface Purpose of This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Who Should Read This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How This Book is Organized . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Books . . . . . . . . . . . . . . . . .
Command Reference vsconnectqry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-40 vsdismount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-44 vsdriveqry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-48 vsdrivevary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Preface Purpose of This Book . . . . . . . . . . . . . . . . . . . . . . .P-3 Who Should Read This Book. . . . . . . . . . . . . . . . .P-3 How This Book is Organized . . . . . . . . . . . . . . . .P-3 Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .P-4 Books. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .P-5 Online Books . . . . . . . . . . . . . . . . . . . . . . . . . . .P-5 Related Publications . . . . . . . . . . . . . . . . . . . . .
Command Reference NOTES P-2 Preface 601356 Rev A
Purpose of This Book This book alphabetically lists and describes the VolServ commands. Who Should Read This Book This book is written for system administrators who uses the command line to operate VolServ. How This Book is Organized It assumes the administrator has a strong familiarity with: • UNIX operating systems. • Applications running in their site environment. This book contains the following chapters: Chapter 1: Introduction — Describes environment variables and the command line structure.
Command Reference Conventions The conventions used throughout the VolServ technical books are listed below: Convention Example Screen text, file names, program names, and commands are in Courier font. Request to add a new volume: Volume group will be “20” Volume position will be “A123”. The root prompt is shown as a number symbol. # su root What you should type in is shown in Courier bold font. vsarchiveqry Site-specific variables are in a Times italics font.
Books The books described below are part of the technical documentation set, and are shipped on CD along with the VolServ software: Overview Provides an overview of VolServ. Contains a glossary. Installing VolServ Describes server requirements, installation instructions, troubleshooting procedures, and configuration parameters. Using the VolServ GUI Describes how to perform system administrative tasks using the graphical user interface.
Command Reference Related Publications The publications described in the table below are created and distributed on an as-needed basis. Related Publications “Release Notes” Description For each version of VolServ, the “Release Notes” contain: • Summary of enhancements. • Describes: - Fixed problems. - Known problems. - Installation and configuration issues. • Lists: - Operating system patches. - System requirements. “Product Alerts” Informs customers of technical problems and solutions.
1 Introduction Introduction Options Common to all Commands . . . . . . . . . . 1-3 Optional Parameters. . . . . . . . . . . . . . . . . . . . . 1-4 Default Values . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5 Environment Variables . . . . . . . . . . . . . . . . . . . . . 1-7 Command-specific Options. . . . . . . . . . . . . . . . . . 1-9 Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Command Reference Roadmap Topic 1-2 Introduction Refer To Chapter Introduction. 1 Alphabetical list of commands.
Command Reference Seven options are available on every command that is supported from the command line. These parameters are: Parameter Description -I Indicates command line options are to be read from stdin. The -I option provides the capability for the client to enter command options on the command line, in a text file, or a combination of both. When the -I option is specified, command options are first read from the command line. VolServ then reads any options from stdin.
Command Reference Parameter -P priority Default value is 15. -R retries Default value is 3. -T timeout Description The execution priority of the entered command. Assignable priority values are restricted to a range from 1 (highest) to 32 (lowest) inclusive. Number of retries the CLI software attempts if a time-out is returned by the API software. Default value is 120 seconds. Amount of time (in seconds) the API software waits for status from VolServ before returning a time-out to the CLI software.
Command Reference • -T (timeout). • -V (prognum). A client can specify values that override the default values previously specified. To specify an override value, the client must set an environment variable for each common option that is to have an override default.
Command Reference prompt VSCLI_HOST=eiffel prompt export VSCLI_HOST (bourne shell) When a client specifies one or more of the -H (hostname), the -P (priority), the -R (retries), the -T (timeout), and the -V (prognum) options on the command line, the values entered on the command line supercedes the VolServ default values and any user-specified default values for the appropriate options.
Command Reference Environment Variables The following environment variables provide the capability for the client to specify default values for common options: VSCLI_HOST • VSCLI_PRIORITY • VSCLI_RETRIES • VSCLI_TIMEOUT Introduction • • VSCLI_PROGNUM The environment variable belowcontrols the number of lines per page for report output: • VSRPT_PAGE_LENGTH The default page length is 66 lines.
Command Reference 1-8 Introduction • Request Query • Media Type Query • Media Query 601356 Rev A
Command Reference Commandspecific Options A matrix that shows which commands support which command-specific options is included in below Command-specific options are described in the following outline. Parameter -a Description Specifies that all items meet specified criteria that are to be processed. Used primarily on query commands. -a archivename Specifies the name of the archive to be referenced by the command. Valid archive names may contain up to 16 alphanumeric characters, including spaces.
Command Reference Parameter -b Identifies the batch assigned to the medium/media being imported. -c Indicates that all MediaClass names associated with the specified archive are to be reported. -c currentmediaclass -c mediaclass -d Introduction Example vsimport … -b batch1 … Identifies batch1 as the batch assigned to the medium/media being imported. The batch assigned to a medium is maintained by the VolServ system.
Command Reference Parameter driveID… Description Specifies a list of one or more drives from which the drives to satisfy the command are to be selected. Example vsunlock 1 3 … Instructs VolServ to unlock drive 1 and drive 3. drivepool enterpriseID Specifies the name of the drive pool being queried. vspoolqry drivepool3 Specifies the identifier of the enterprise connection being queried. vsconnectqry 4 Introduction The number of drives that can be specified is restricted by the CLI software.
Command Reference Parameter -l lockID Description Specifies the lock ID assigned to the drive specified in the command. -m mediaclass mediaID vsdismount … -l 9 … Indicates that the drive specified in the command is reserved for exclusive use and has been assigned the lock ID 9. Indicates that all media associated with the specified archive are to be reported. vsarchiveqry … -m … Specifies the name of the MediaClass group being queried.
Command Reference Parameter mediatype… Description Specifies a list of one or more mediatypes to be processed by the command. Example vsmedtypeqry medtypeZ Instructs VolServ to return information on medtypeZ. Introduction Valid MediaType names can contain up to 16 alphanumeric characters, including spaces. Leading and trailing spaces are not permitted. The number of media types that can be specified is restricted by the CLI software. Currently, the maximum allowed number is 32.
Command Reference Parameter requestID Description Specifies VolServ-assigned ID of the request being queried. A valid request ID must be specified in either the ydddnnnnn format or the yy:ddd:nnnnn format where y and yy represent the last one/two digits of the year, ddd represents the Julian day, and nnnnn is a one-up number. -s compstate -t -t comment -u 1-14 Introduction Specifies the target state of the item being varied.
Command Reference Parameter -v Description Indicates that verbose output is requested. • If -v option is specified on a query command, all applicable information is returned to the client. • If -v is not specified on a command that specifies a list of items, status is returned on only those items that were not successfully processed. • If -v option is not specified on a query command, only the specifically requested information is returned to the client.
Command Reference Parameter -x Description Specifies a list of one or more drives to exclude from a specified drive pool when selecting drives to satisfy a command. The -x option is valid only when the -p drivepool option is specified. Tables 1-16 Example vsmount …-p : drvpoolmed -x 1 2 … Instructs VolServ to exclude drives 1 and 2 from consideration when selecting drives from the drvpoolmed drive pool to satisfy the mount request.
Command Reference -a (all) -a archive name vsamlconfig -b -c batchID (MediaClass) -c current mediaclass X X X vsarchivevary X vsaudit X vscheckin Introduction vsarchiveqry archivename X X vscheckout vscleareject vsconnectqry vsdismount vsdriveqry X vsdrivevary vsexport vsimport X X vsintransitqry vslock vsmedclassqry X vsmedqry X vsmedtypeqry X vsmount vsmove X vsping vspoolqry X vsqrymount vsreclassify X vsrequestqry vsunlock 601356 Rev A Introduction 1-17
Command Reference -f manufacturer -i (mount, attended) -l lockID -m mediaclass (mediaIDs) vsamlconfig vsarchiveqry X vsarchivevary vsaudit vscheckin vscheckout vscleareject vsconnectqry vsdismount X vsdriveqry vsdrivevary vsexport vsimport X vsintransitqry vslock vsmedclassqry X X vsmedqry vsmedtypeqry vsmount X vsmove X X vsping vspoolqry vsqrymount vsreclassify vsrequestqry vsunlock 1-18 Introduction X 601356 Rev A
Command Reference mediaID mediaID… mediatype -n new mediaclass -p drivepool -q quantity vsamlconfig Introduction vsarchiveqry vsarchivevary vsaudit vscheckin X vscheckout X vscleareject X vsconnectqry vsdismount X vsdriveqry vsdrivevary X vsexport X vsimport X vsintransitqry vslock X X vsmedclassqry vsmedqry X vsmedtypeqry X vsmount X vsmove X X X vsping vspoolqry vsqrymount vsreclassify X X X vsrequestqry vsunlock 601356 Rev A Introduction 1-19
Command Reference request ID -t (Media Types) -t -s comment compstate -u (mount, unattended) -u usage time vsamlconfig vsarchiveqry X vsarchivevary X vsaudit vscheckin vscheckout X vscleareject vsconnectqry vsdismount X vsdriveqry vsdrivevary X vsexport X vsimport vsintransitqry vsmedclassqry vslock vsmedqry vsmedtypeqry vsmount X vsmove vsping vspoolqry vsqrymount vsreclassify vsrequestqry X vsunlock 1-20 Introduction 601356 Rev A
Command Reference -v (verbose) -w (wait) -x driveID… vsamlconfig vsarchiveqry Introduction vsarchivevary vsaudit vscheckin vscheckout vscleareject X vsconnectqry vsdismount vsdriveqry vsdrivevary X vsexport X vsimport X vsintransitqry X vsmedclassqry vslock X X vsmedqry vsmedtypeqry vsmount vsmove X X X vsping vspoolqry X vsqrymount vsreclassify X vsrequestqry vsunlock 601356 Rev A X Introduction 1-21
Command Reference CLI Directory Structure All files necessary for command line interface to VolServ are contained in the volserv/vscli directory by default. However, the installer may choose a different directory during execution of the installation script. The vscli subdirectory is always appended to the directory specified by the installer. Refer to Installing VolServ for more information. The system administrator or clients may use the commands to interface to VolServ.
Command Reference NOTES Introduction 601356 Rev A Introduction 1-23
Command Reference NOTES 1-24 Introduction 601356 Rev A
2 Command Reference Commands volserv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3 vsamlconfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6 vsarchiveqry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8 vsarchivevary . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-14 vsaudit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-18 vscheckin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Command Reference vsunlock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-148 vswin. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-153 Roadmap Topic 2-2 Command Reference Refer To Chapter Introduction. 1 Alphabetical list of commands.
Command Reference volserv Starts or ends VolServ and activates the system log display. Parameters volserv -s volserv -t | -q volserv [-y] Parameters Parameters Description Starts VolServ in the single user mode. Only commands run with vswin are run. Client interface commands are refused. -t Terminates the VolServ operations. VolServ terminates gracefully. Outstanding commands are cancelled and any commands awaiting status are allowed to complete (within a certain time period).
Command Reference Return Codes Examples • 0 - Command completed successfully - VolServ started or completed normally. • 1 - Command did not complete successfully - VolServ did not start or complete as expected. Step 1. Successful VolServ system start-up. Requests VolServ to start. volserv Step 2. Output returned: VolServ Version x.0.0 for SunOS (x.x) -- Copyright (c) 1992-1999 ADIC.
Command Reference vsamlconfig Starts the ADIC-GRAU AML (Automated Media Library) configuration script. The following information needs to be known before running the command: • Archive name. • Attended Mode or Unattended Mode. • Console location. • AMU host name. • AMU port number. vsamlconfig Example Configure an AML. 601356 Rev A Commands Parameters Step 1. vsamlconfig Step 2. AML CONFIG MENU Step 3. [C]onfigure a New Archive Step 4. [R]econfigure a existing Archive Step 5.
Command Reference Step 10. Enter Mode: ArchiveMode Step 11. Is ArchiveMode correct (Y/N [Y]): Step 12. Enter Console Location (termname:0): Terminal Step 13. Is Terminal correct (Y/N [Y]): Step 14. Enter Mode ([A]ttended,[U]nattended: ArchiveMode Step 15. Is ArchiveMode correct (Y/N [Y]): Step 16. Enter AMU Host Name: HostName Step 17. Is HostName correct (Y/N [Y]): Step 18. Enter AMU Port Number : PortNum Step 19.
Command Reference vsarchiveqry Queries for information about a specified library. Parameters vsarchiveqry archivename vsarchiveqry -a [ [ [ [ [ [ -cdIhmtv ] -H hostname ] -P priority ] -R retries ] -T timeout ] -V prognum ] Parameters archivename Description Identifies the library to be queried. • Valid library names may contain up to 16 alphanumeric characters, including spaces. • Leading and trailing spaces are not permitted. 601356 Rev A -a Specifies that all libraries are to be queried.
Command Reference Parameters -v Description Indicates that all drives, all MediaClass groups, all media, and all media types associated with the specified libraries are to be reported. Specifying the -v option is equivalent to specifying the -d, the -c, the -m, and the -t options. -I Command options are first read from the command line. VolServ then reads any options contained in the stdin file. -h Requests help for the entered command.
Command Reference Return Codes Examples • 0 - The vsarchiveqry command is successfully processed. • -1 - An error is detected by either the CLI software or the API software. • >0 - An error is detected by VolServ. The returned exit code corresponds to the error code given by VolServ. Step 1. Successful library query. Requests VolServ to return the MediaClass groups and the media types associated with the shelf1 library. vsarchiveqry shelf1 -ct Output returned: Commands Step 2.
Command Reference Action: None Archive Capacity: Current Fill Level: Assigned Locations: Auto Checkin: Auto Import: Action: D2M 40 2 2 off off None MediaType: Step 1. Successful library query. Requests VolServ to return the drives, the media, the MediaClass groups, and the media types associated with the stage1 library. vsarchiveqry stage1 -v Step 2.
Command Reference Drive ID(s): 12 Media ID(s): med001med002 med003 med004 MediaClass: MC-3480 3480 50% 100 4 None Archive Capacity: Current Fill Level: Assigned Locations: Auto Checkin: Auto Import: Action: 3480 100 4 4 off off None MediaType: Step 1. Commands MediaType: Class Capacity %: Class Capacity: Current Fill Level: Action: Unsuccessful library query. Requests VolServ to return the drives associated with the BadArchiveName library. vsarchiveqry BadArchiveName -d Step 2.
Command Reference A pending or executing vsarchiveqry request is cancelled with the VolServ cancel command. The VolServ cancel command is run from the command line by sending a SIGQUIT signal (control-\). The request is also aborted by sending the SIGINT signal (control-c).
Command Reference vsarchivevary Varies the state of a library. The name of the library and the target state (online, offline, or diagnostic) must be specified. The return code presented to the client indicates the success or failure of the command. Parameters vsarchivevary -s state archivename [ [ [ [ [ [ -Ih ] -H hostname ] -P priority ] -R retries ] -T timeout ] -V prognum ] Commands Parameters Parameters -s state Description Specifies the target state of the specified drives.
Command Reference Parameters -h Description Requests help for the entered command. When the Help option is specified, no command line processing is performed. An exit code of 0 is returned to the client when the Help option is specified. -H hostname Host name of the VolServ server. The default host name is the host name of the computer where the CLI command is run. -P priority The execution priority of the entered command.
Command Reference Return Codes Examples • 0 - The vsarchivevary command is successfully processed. • -1 - An error is detected by either the CLI software or the API software. • >0 - An error is detected by VolServ. The returned exit code corresponds to the error code given by VolServ. Step 1. Successful archive vary. Requests VolServ to vary the shelf1 archive to the diagnostic state. vsarchivevary shelf1 -s diagnostic Step 2. Output returned: Step 1. Unsuccessful archive vary.
Command Reference VolServ processes commands that interact strictly with the database (for example: Query Mount, Create Drive Pool, and Create Archive Media Class), regardless of the state of the associated archive. All components associated with an offline or diagnostic library, such as media, drives, and physical hardware, are unavailable. The Archive Vary command does not trigger unsolicited status messages from VolServ. A pending vsarchivevary request is cancelled with the VolServ cancel command.
Command Reference vsaudit Performs library inventory verification. If the specified library is robotically controlled, the robot scans each physical bin location and verifies that the database is consistent with the actual location of media. Any noted inconsistencies are returned to the client, logged in a system log file, and VolServ initiates corrective action, based on the circumstances of the discrepancy.
Command Reference Parameters Parameters archivename Description Specifies the name of the archive to audit. • Valid archive names may contain up to 16 alphanumeric characters, including spaces. • Leading and trailing spaces are not permitted. -I Command options are first read from the command line. VolServ then reads any options contained in the stdin file. -h Requests help for the entered command. When the Help option is specified, no command line processing is performed.
Command Reference Parameters -V prognum Description RPC program number for VolServ. Default value is 300016. Return Codes 0 - The vsaudit command is successfully processed. • -1 - An error is detected by either the CLI software or the API software. • >0 - An error is detected by VolServ. The returned exit code corresponds to the error code given by VolServ. Step 1. Successful audit request. Requests VolServ to audit the shelf1 archive. vsaudit shelf1 Step 2.
Command Reference Step 2. Output returned: Audit of archive [BadArchiveName] was unsuccessful Error VOL013: invalid archive Notes With the exceptions of the manual libraries, a pending or executing vsaudit request is cancelled with the VolServ cancel command. The VolServ cancel command is run from the command line by sending a SIGQUIT signal (control-\). The request also is aborted by sending the SIGINT signal (control-c).
Command Reference The total length of time that VolServ waits for a command status, in synchronous mode, from VolServ is (VSID_RETRY_LIMIT plus 1) multiplied by VSID_TIMEOUT_VALUE. Because of the time required for robotic audits, the timeout value or retries may need to be increased from the default values.
Command Reference vscheckin Logically checks media into the VolServ system that has been previously checked out of the VolServ system. Checkin is a logical operation. After media is logically checked in to the VolServ system, the media is physically entered into a library before becoming available for client use (mounting,…). Media is physically entered into the VolServ system via the “Enter” functionality available from the appropriate library’s console display.
Command Reference Parameter -a archivename Descrition Specifies the name of the destination library for the media to be entered into after they are checked in. • Valid library names may contain up to 16 alphanumeric characters, including spaces. • Leading and trailing spaces are not permitted. -v Indicates that verbose output is needed. Status is returned on every media specified in the vscheckout command.
Command Reference Parameter -T timeout Descrition Default value is 120 seconds. Amount of time (in seconds) the API software waits for status from VolServ before returning a time-out to the CLI software. Total wait time for a command is (retries plus 1) multiplied by time-out value. -V prognum RPC program number for VolServ. Default value is 300016. Return Codes Examples • 0 - The vscheckin command is successfully processed.
Command Reference Step 1. Successful Checkin request with verbose option not specified. Requests VolServ to check MED013 into the shelf2 library and to return status on media only if processing for that media failed. vscheckin MED013 -a shelf2 Step 2. Output returned: Check in 1 of 1 media was successful Step 1. vscheckin MED011 MED014 MED021 -v Step 2.
Command Reference Step 1. Errors with verbose option not specified. Requests VolServ to check MED001, MED002, and MED093 into the stage1 library and to return status on media only if processing for that media failed: vscheckin MED001 MED002 MED093 -a stage1 Step 2.
Command Reference A pending or executing vscheckin request is cancelled with the VolServ cancel command. The VolServ cancel command is run from the command line by sending a SIGQUIT signal (control-\). The request also is aborted by sending the SIGINT signal (control-c).
Command Reference vscheckout Checks media out of the VolServ system. Media that has been checked out is still known by VolServ, but is unavailable for client allocation. Upon receipt of a vscheckout request, VolServ marks the specified media for checkout. If the specified media is contained in libraries, VolServ adds the media to the Eject list of the containing library.
Command Reference Parameter Description -t comment Provide a comment to be associated with each checked-out media. This comment is provided on the Eject list (a GUI display) from the library console associated with the library containing the media. -v Indicates that verbose output is needed. Status is returned on every media specified in the vscheckout command. NOTE: If -v is not specified, status is returned on only those media that were not successfully checked out.
Command Reference Parameter -T timeout Description Default value is 120 seconds. Amount of time (in seconds) the API software waits for status from VolServ before returning a time-out to the CLI software. Total wait time for a command is (retries plus 1) multiplied by time-out value. -V prognum RPC program number for VolServ. Default value is 300016. Return Codes Examples • 0 - The vscheckout command is successfully processed.
Command Reference Step 1. Successful Checkout request with verbose option not specified. Requests VolServ to check MED003, MED004, MED005, MED006, MED007, and MED008 out of the VolServ system and to return status on media only if processing for that media failed. vscheckout MED003 MED004 MED005 MED006 MED007 MED008 Step 2. Output returned: Check out 6 of 6 media was successful Step 1. vscheckout MED010 MED011 MED012 MEDa13 -v Step 2.
Command Reference Step 1. Errors with verbose option not specified. Requests VolServ to check MED010, MED011, MED012, and MEDa13 out of the VolServ system and to return status on media only if processing for that media failed: vscheckout MED010 MED011 MED012 MEDa13 Step 2.
Command Reference A pending or executing vscheckout request is cancelled with the VolServ cancel command. The VolServ cancel command is run from the command line by sending a SIGQUIT signal (control-\). The request is aborted by sending the SIGINT signal (control-c).
Command Reference vscleareject Removes the specified media from the library’s Eject list. Ejects can be generated during processing of the VolServ vscheckout vsexport, vsmount, and vsmove commands. Ejects can also be generated during automigration. The Clear Eject command essentially undoes the completion of these commands. Media is removed from the Eject list and returned to the available state.
Command Reference Parameters Paramaeter mediaid … Description Specifies the media (up to 64 pieces) to remove from the Eject list. • A valid media identifier may contain up to 16 alphanumeric characters, including spaces. • Leading and trailing spaces are not permitted. -v Indicates that verbose output is needed. Status is returned on every media specified in the vscheckout command. -I Command options are first read from the command line. VolServ then reads any options contained in the stdin file.
Command Reference Paramaeter -T timeout Description Default value is 120 seconds. Amount of time (in seconds) the API software waits for status from VolServ before returning a time-out to the CLI software. Total wait time for a command is (retries plus 1) multiplied by time-out value. -V prognum RPC program number for VolServ. Default value is 300016. Return Codes Examples • 0 - The vscleareject command is successfully processed.
Command Reference Step 1. Successful with verbose option not specified. Requests VolServ to remove MED016, MED018, MED020, and MED021 from the Eject list and to return status on media only if processing for that media failed. vscleareject MED016 MED018 MED020 MED021 Step 2. Output returned: Clear Eject 4 of 4 media was successful Step 1. vscleareject MED012 MED013 MEd014 MED051 -v Step 2.
Command Reference Step 1. Errors with verbose option not specified. Requests VolServ to remove MED012, MED013, MED014, and MED051 from the Eject list and to return status on media only if processing for that media failed. vscleareject MED012 MED013 MED014 MED051 Step 2.
Command Reference • vsexport, • vsmount, • vsmove Commands 601356 Rev A Command Reference 2-39
Command Reference vsconnectqry Queries for enterprise connection information. This command provides a list of all client internet addresses that are currently associated with the given enterprise identifier. Parameters vsconnectqry enterpriseid [ [ [ [ [ [ -Ih ] -H hostname ] -P priority ] -R retries ] -T timeout ] -V prognum ] Parameters Parameter enterpriseid Description Specifies the identifier of the enterprise connection being queried. An enterprise identifier must be numeric.
Command Reference Parameter -P priority Default value is 15. -R retries Default value is 3. -T timeout Description The execution priority of the entered command. Assignable priority values are restricted to a range from 1 (highest) to 32 (lowest) inclusive. Number of retries the CLI software attempts if a time-out is returned by the API software. -V prognum RPC program number for VolServ. Commands Default value is 120 seconds.
Command Reference Step 2. Output returned: ----------------------------------------------Connect Query Report May 24 12:43:18 19931 ----------------------------------------------Enterprise ID: 3 ----------------------------------------------Client #: 1 Socket Family: Socket Port: Internet Address: Program Number: Version Number: Procedure Number: 10 1 300 300016 2 1 ² • Step 1. Unsuccessful enterprise query.
Command Reference However, only from the GUI can “query all” be specified to list all enterprises. From the command line, only one enterprise can be specified within a single command. This restriction prevents any single client from listing the clients of other enterprises being serviced by VolServ. The vsconnectqry command does not trigger unsolicited status messages from VolServ. A pending vsconnectqry request is cancelled with the VolServ cancel command.
Command Reference vsdismount Parameters Dismounts media from a drive. • For automated libraries, VolServ checks to see that the media is ejected from the drive by the storage subsystem. If the media is not ejected from the drive, the vsdismount request fails and VolServ returns a failure status to the client. However, if the media is ejected from the drive, VolServ tells the library robotics to move the media from the drive pickup point to a bin within the library system.
Command Reference Parameters Parameter Description Identifies the media to be dismounted. A valid media identifier may contain up to 16 alphanumeric characters, including spaces. Leading and trailing spaces are not permitted. -d driveid Identifies the drive where the media is mounted. -l lockid Specifies the lock identifier associated with the drive if the drive is mounted with a lock identifier. -u usagetime The amount of time (in seconds) the drive is in use.
Command Reference Parameter -R retries Default value is 3. -T timeout Description Number of retries the CLI software attempts if a time-out is returned by the API software. Default value is 120 seconds. Amount of time (in seconds) the API software waits for status from VolServ before returning a time-out to the CLI software. Total wait time for a command is (retries plus 1) multiplied by time-out value. -V prognum RPC program number for VolServ. Default value is 300016.
Command Reference Step 1. Unsuccessful dismount request. Requests VolServ to dismount MED016 from drive 13. vsdismount MED016 -d 13 Step 2. Output returned: Dismount of Media [MED016] from Drive [13] was unsuccessful Error VOL081: drive not mounted Step 1. Unsuccessful dismount request. Requests VolServ to dismount MED016 from drive 9. vsdismount MED016 -d 9 Commands Step 2.
Command Reference vsdriveqry Queries for information on specified drives. Parameters vsdriveqry driveid… vsdriveqry [ [ [ [ [ [ -a -Ih ] -H hostname ] -P priority ] -R retries ] -T timeout ] -V prognum ] Parameters Parameter driveid… Description Specify a list of one through 64 drives to be queried. -a Indicates all drives known to the VolServ system are to be queried. -I Command options are first read from the command line. VolServ then reads any options contained in the stdin file.
Command Reference Parameter -P priority Default value is 15. -R retries Default value is 3. -T timeout Description The execution priority of the entered command. Assignable priority values are restricted to a range from 1 (highest) to 32 (lowest) inclusive. Number of retries the CLI software attempts if a time-out is returned by the API software. -V prognum RPC program number for VolServ. Commands Default value is 120 seconds.
Command Reference Step 2.
Command Reference ----------------------------------------------Drive ID: 4 ----------------------------------------------Drive Type: Magnetic Associated Archive: shelf1 Current State: Online Assignment: Free Usage Count: 0 Current Usage Time: 0 Total Usage Time: 0 Error Count: 0 Mount State: Unmounted Mounted Media ID: Media Type(s) Supported:D2M Step 1. vsdriveqry 35 Step 2. Output returned: Drive query was unsuccessful. Error VOL008: item not found.
Command Reference vsdrivevary Changes the state of a drive. A drive in the offline, unavailable, or diagnostic state is excluded from VolServ’s drive selection algorithm. Tip A vsmount or vslock request for an offline, unavailable, or diagnostic drive will fail. On the ohter hand, varying a drive to the online state makes it available for selection for vsmount or vslock requests.
Command Reference Parameter -s state Description Specifies the target state of the specified drives. Valid drive states are • online (on) • offline (of) • diagnostic (d) -v Indicates that verbose output is needed. Status is returned on every media specified in the vscheckout command. NOTE: If -v is not specified, status is returned on only those media that were not successfully checked out. Command options are first read from the command line. VolServ then reads any options contained in the stdin file.
Command Reference Parameter -T timeout Description Default value is 120 seconds. Amount of time (in seconds) the API software waits for status from VolServ before returning a time-out to the CLI software. Total wait time for a command is (retries plus 1) multiplied by time-out value. -V prognum RPC program number for VolServ. Default value is 300016. Return Codes Examples • 0 - The vsdrivevary command is successfully processed.
Command Reference Step 2. Output returned: Vary 8 of 8 drives to state [off-line] was successful. Drive [1] no error Drive [4] no error Drive [5] no error Drive [7] no error Drive [8] no error Drive [11] no error Drive [12] no error Drive [14] no error Step 1. Successful drive vary with verbose option not specified. Requests VolServ to vary drive 2 to the diagnostic state and to return status on a drive only if processing for that drive failed. Commands vsdrivevary 2 -s diagnostic Step 2.
Command Reference Step 2. Output returned: Vary 3 of 5 drives to state [online] was successful Drive [5] no error Drive [15] invalid drive specified Drive [8] no error Drive [18] invalid drive specified Drive [11] no error Step 1. Errors with verbose option not specified. Requests VolServ to vary drives 5, 15, 8, 18, and 11 to the off-line state and to return status on a drive only if processing for that drive failed. vsdrivevary 5 15 8 18 11 -s offline Step 2.
Command Reference Notes Mounted drives that have their state changed remain in-use. Varying a drive has no impact on client data transfer operations in progress and the client receives no automatic notification of a drive state change. Drives can be varied, regardless of whether or not they are associated with a library. Drives can be varied, regardless of whether or not they are allocated; however, allocated drives that are not online cannot be dismounted.
Command Reference vsexport Marks media and related media information for removal from the VolServ system. If the specified media is not associated with a library, the media is logically removed from the VolServ system. However, if the specified media is associated with a library, the media is placed on the Eject list of the appropriate library. A client can also use the vsexport command to remove information about media that have been checked out of the library and is physically out of the library.
Command Reference Parameters Parameter mediaid… Description Specifies a list of one through 64 media to export. • A valid media identifier may contain up to 16 alphanumeric characters, including spaces. • Leading and trailing spaces are not permitted. Provide a text message to be displayed on the library console for each media being exported. This comment is provided on the Eject list (a GUI display) from the library console associated with the library containing the media.
Command Reference Parameter -P priority Default value is 15. -R retries Default value is 3. -T timeout Description The execution priority of the entered command. Assignable priority values are restricted to a range from 1 (highest) to 32 (lowest) inclusive. Number of retries the CLI software attempts if a time-out is returned by the API software. Default value is 120 seconds. Amount of time (in seconds) the API software waits for status from VolServ before returning a time-out to the CLI software.
Command Reference Examples Step 1. Successful export request with verbose and comment options specified. Requests to VolServ to place media MED012, MED014, and MED016 on the Eject list with the comment, Media to be shipped off-site, and to return status on every specified media. vsexport MED012 MED014 MED016 -t Media to be shipped off-site -v Step 2. Output returned: Step 1.
Command Reference Requests to VolServ to place media MED007, MED014, MED021, MED028, MED053, and MED042 on the Eject list with the comment, Media to be shipped off-site, and to return status on every specified media. vsexport MED007 MED014 MED021 MED028 MED053 MED042 -t Media to be shipped off-site -v Step 2. Output returned: Export 4 of 6 media was successful Error VOL024: error in the list Media [MED007] Media [MED014] Media Media Media Media [MED021] [MED028] [MED053] [MED042] Step 1.
Command Reference Step 2. Output returned: Export 4 of 6 media was successful Error VOL024: error in the list Media [MED014] Media [MED053] Notes invalid action or location state for operation item not found The vsexport command cannot be cancelled. Media can be unmarked for export via the Clear Eject request or if the operator fails the eject. An allocated media can be marked for export. Attempts to physically eject an allocated media fail until the media is no longer in-use.
Command Reference vsimport Logically adds media to the VolServ system. Upon receipt of a vsimport request, the specified media is added to the VolServ system. If a non-unique media identifier is specified, the import for that media fails. The vsimport is a logical operation. Media must be physically entered into a library before the media is available for client use (mounting,…). Entry is performed when an operator selects the Enter functionality from the appropriate library’s console display.
Command Reference Parameters Parameter mediaid… Description Specifies a list of one through 64 media to import. • A valid media identifier may contain up to 16 alphanumeric characters, including spaces. • Leading and trailing spaces are not permitted. -a archivename Identifies the library into which the media are to be entered. VolServ sends Enter commands for the media to be entered to the console for the specified library. • Leading and trailing spaces are not permitted.
Command Reference Parameter -b batch Description Specifies the manufacturer’s batch that contains the media to be entered. • If the -b (batch) option is specified, the -f (manufacturer) option must also be specified. • If the -b (batch) option is not specified, the -f (manufacturer) option cannot be specified. -v Indicates that verbose output is needed. Status is returned on every media specified in the vscheckout command.
Command Reference Parameter -T timeout Description Default value is 120 seconds. Amount of time (in seconds) the API software waits for status from VolServ before returning a time-out to the CLI software. Total wait time for a command is (retries plus 1) multiplied by time-out value. -V prognum RPC program number for VolServ. Default value is 300016. Return Codes 0 - The vsimport command is successfully processed. • -1 - An error is detected by either the CLI software or the API software.
Command Reference Step 2. Output returned: Import 5 of 5 media was successful Media [MED003] Media [MED018] Media [MED021] Media [MED030] Media [MED036] Step 1. no no no no no error error error error error Successful Import request with verbose option not specified Requests VolServ to import media MED003, MED018, MED021, MED030, and MED036 into the medclasssh1med MediaClass group in the shelf1 library and to return status on media only if processing for that media failed.
Command Reference specified media. “MediaMaker ABC” is the manufacturer of these media and these media were part of batch “1001.” vsimport MED003 MED018 MED021 MED030 MED036 -a shelf1 -c medclasssh1med -v -f “MediaMaker ABC” -b 1001 Step 2. Output returned: Step 1.
Command Reference Step 2. Output returned: Import 3 of 5 media was successful Error VOL024: error in the list Media [MED018] Media [MED021]item already exists Step 1. item already exists Unsuccessful Import request. Requests VolServ to import media MED003, MED018, MED021, MED030, and MED036 into the medclassmed MediaClass group in the BadArchiveName library and to return status on media only if processing for that media failed.
Command Reference Media identifiers of media being imported into manual libraries may contain alphanumeric and special characters including spaces. However, spaces cannot be used as leading or trailing characters. If media in a manual library can later be moved into an automated library, the media identifiers must also conform to any naming restrictions imposed by the automated library. For example, special characters may not be allowed in media identifiers in the automated library.
Command Reference vsintransitqry Queries for media that are in the intransit state. The query returns a list of media identifiers. Note The vsintransitqry command supports no command-specific options. Media is considered to be intransit under the following conditions: Parameters • It is waiting to be entered into a library as a result of vsimport, vsmount, vsmove, vscheckout, or migration activity processing. • It is in the homeless state as a result of a manual eject or a failed enter activity.
Command Reference Parameter -h Description Requests help for the entered command. When the Help option is specified, no command line processing is performed. An exit code of 0 is returned to the client when the Help option is specified. -H hostname Host name of the VolServ server. The default host name is the host name of the computer where the CLI command is run. -P priority The execution priority of the entered command.
Command Reference • Examples >0 - An error is detected by VolServ. The returned exit code corresponds to the error code given by VolServ. Step 1. Successful intransit query. Requests VolServ to return a list of all media in the intransit state. vsintransitqry Step 2. Output returned: ----------------------------------------------Intransit Query Report May 14 09:45:57 19931 ----------------------------------------------Media ID(s):MED007 MED025MED040 Step 1.
Command Reference A pending vsintransitqry request is cancelled with the VolServ cancel command. The VolServ cancel command is run from the command line by sending a SIGQUIT signal (control-\). The request also is aborted by sending the SIGINT signal (control-c).
Command Reference vslock Obtains exclusive use of one or more drives. The lock identifier assigned to the locked drives is returned to the client. This lock identifier must be used by clients on subsequent requests (such as vsmount) for those drives. A request to lock a drive that is busy (mounted or previously locked) is queued until the drive becomes available. In addition, intermediate status is returned to indicate the reason a request is being queued.
Command Reference Parameters vslock driveid… vslock -p drivepool [ -x driveid ] [-q quantity] [ -Ih ] [ -H hostname ] [ -P priority ] [ -R retries ] [ -T timeout ] [ -V prognum ] Parameters Parameter Description Specifies a list of one through 64 candidate drives to reserve (lock) for exclusive use. -p drivepool Specifies the name of a drive pool. Commands driveid… • Valid drive pool names may contain up to 16 alphanumeric characters, including spaces.
Command Reference Parameter -h Description Requests help for the entered command. When the Help option is specified, no command line processing is performed. An exit code of 0 is returned to the client when the Help option is specified. -H hostname Host name of the VolServ server. The default host name is the host name of the computer where the CLI command is run. -P priority The execution priority of the entered command.
Command Reference Examples Step 1. Successful Lock request that specifies a list of one or more drives (vslock 4 8 12) Step 2. Requests VolServ to lock (reserve for exclusive use) one of the drives 4, 8, and 12. Step 3. Output returned: Lock [1] drives locked with lock id[1719790788] 1 Drive[4] Step 1. Successful Lock request that specifies a drive pool and a quantity vslock -p drvpoolmed -q 2 Step 2.
Command Reference Step 2. Output returned: Lock was unsuccessful Error VOL122: not enough available drives in pool Step 1. Unsuccessful Lock request. Requests VolServ to lock (reserve for exclusive use) 1 drive from drive pool BadDrivePool. vslock -p BadDrivePool -q 1 Step 2.
Command Reference If a vsmount request specifies a drive pool, but does not specify a lock identifier, only available unlocked drives in the specified drive pool are considered to satisfy the mount request. If there are no available unlocked drives in the specified drive pool, the mount request waits until a drive from the specified drive pool becomes available and unlocked. A vslock command that is queued and awaiting resources is cancelled via the VolServ cancel command.
Command Reference vsmedclass qry Queries for the attributes of a specified MediaClass group or all MediaClass groups. The members of the MediaClass group and any additionally requested information on each media is returned to the client.
Command Reference Parameter Description -I Command options are first read from the command line. VolServ then reads any options contained in the stdin file. -h Requests help for the entered command. When the Help option is specified, no command line processing is performed. An exit code of 0 is returned to the client when the Help option is specified. Host name of the VolServ server. The default host name is the host name of the computer where the CLI command is run.
Command Reference Examples • -1 - An error is detected by either the CLI software or the API software. • >0 - An error is detected by VolServ. The returned exit code corresponds to the error code given by VolServ. Step 1. Successful MediaClass Query with neither -m nor -v specified. Requests VolServ to return information on every MediaClass group known to the VolServ system. No media-specific information is requested. vsmedclassqry -a Step 2.
Command Reference •² Media Class: medclasssh2med ----------------------------------------------Media Type: D2M Capacity: 20 Current Fill Level: 3 High Mark %: 80% Mountable by Class: Yes Notify Comment: Media exceed high mark RPC Option: Enterprise Callback Enterprise ID: 3 • •² •² Step 1.
Command Reference Step 2. Output returned: ----------------------------------------------Media Class Query Report May 14 09:45:57 19931 ----------------------------------------------Media Class: medclasssh1usr ----------------------------------------------Media Type: USRTYPE Capacity: 20 Current Fill Level: 3 High Mark %: 80% Mountable by Class: Yes Notify Comment: Media exceed high mark RPC Option: No Callback Media ID(s): MED007 Step 1.
Command Reference Media Class: medclasssml ----------------------------------------------Media Type: D2S Capacity: 20 Current Fill Level: 8 High Mark %: 80% Mountable by Class: Yes Notify Comment: Media exceed high mark RPC Option: No Callback D2S medclasssml Free Archive stage1 Commands MediaID: MED005 Media Type: Media Class: Assignment: Location State: Current Archive: Pending Archive: Action State: Import Date: Last Access: Mount Count: Move Count: Manufacturer: Batch: None May 14 09:30:09 1993 May
Command Reference MediaID: MED017 Media Type: Media Class: Assignment: Location State: Current Archive: Pending Archive: Action State: Import Date: Last Access: Mount Count: Move Count: Manufacturer: Batch: D2S medclasssml Allocated Archive shelf2 None May 14 09:28:41 1993 May 14 09:40:21 1993 1 1 ² ² MediaID: MED038 Media Type: Media Class: Assignment: Location State: Current Archive: Pending Archive: Action State: Import Date: Last Access: Mount Count: Move Count: Manufacturer: Batch: • • • 2-88 Comm
Command Reference MediaID: MED051 Media Type: Media Class: Assignment: Location State: Current Archive: Pending Archive: Action State: Import Date: Last Access: Mount Count: Move Count: Manufacturer: Batch: shelf1 Import May 14 09:30:09 1993 0 0 Unsuccessful Media Class Query. Commands Step 1. D2S medclasssml Free Intransit Requests VolServ to return information on the UnknownClass MediaClass group. vsmedclassqry UnknownClass Step 2.
Command Reference A pending vsmedclassqry is cancelled with the VolServ cancel command. The VolServ cancel command is run from the command line by sending a SIGQUIT signal (control-\). The request also is aborted by sending the SIGINT signal (control-c).
Command Reference vsmedqry Queries for the attributes of one or more specified media. The values of the attributes of the media are returned to the client. Parameters vsmedqry mediaid… vsmedqry -a [ [ [ [ [ [ -Ih ] -H hostname ] -P priority ] -R retries ] -T timeout ] -V prognum ] Parameter Description mediaid… Specifies a list of one through 64 media to be queried. -a Specifies the -a option to indicate information is to be reported on all media known to the VolServ system.
Command Reference Parameter -P priority Default value is 15. -R retries Default value is 3. -T timeout Description The execution priority of the entered command. Assignable priority values are restricted to a range from 1 (highest) to 32 (lowest) inclusive. Number of retries the CLI software attempts if a time-out is returned by the API software. Default value is 120 seconds. Amount of time (in seconds) the API software waits for status from VolServ before returning a time-out to the CLI software.
Command Reference Step 2.
Command Reference Media ID: MED015 ----------------------------------------------Media Type: D2M Media Class: medclassmed Assignment: Free Location State: Intransit Current Archive: Pending Archive: shelf1 Action State: Move Import Date: May 13 16:25:39 1993 Last Access: May 13 16:40:53 1993 Mount Count: 0 Move Count: 0 Manufacturer: MediaMaker ABC Batch: 1001 ² ² Media ID: MED027 ----------------------------------------------Media Type: D2M Media Class: medclassmed Assignment: Free Location State: Archive
Command Reference Media ID: MED039 ----------------------------------------------Media Type: D2M Media Class: medclassmed Assignment: Allocated Location State: Archive Current Archive: shelf1 Pending Archive: shelf2 Action State: Move Import Date: May 12 14:36:10 1993 Last Access: May 13 14:36:10 1993 Mount Count: 1 Move Count: 1 Manufacturer: Batch: Media Query request with errors. Commands Step 1. Requests VolServ to return information on media MED027, BadMedia, and MED039.
Command Reference Media ID: MED027 ----------------------------------------------Media Type: D2M Media Class: medclassmed Assignment: Free Location State: Archive Current Archive: shelf2 Pending Archive: shelf1 Action State: Move Import Date: May 13 16:36:39 1993 Last Access: May 24 12:23:25 1993 Mount Count: 0 Move Count: 0 Manufacturer: Batch: Media ID: BadMedia ----------------------------------------------Error: item not found Media ID: MED039 ----------------------------------------------Media Type: D
Command Reference A pending vsmedqry is cancelled with the VolServ cancel command. The VolServ cancel command is run from the command line by sending a SIGQUIT signal (control-\). The request also is aborted by sending the SIGINT signal (control-c). The vsmedqry command does not trigger unsolicited status messages from VolServ.
Command Reference vsmedtype qry Queries for the attributes of one or more media types. The values of the attributes of the media types are returned to the client. Parameters vsmedtypeqry mediatype… vsmedtypeqry -a [ [ [ [ [ [ -Ih ] -H hostname ] -P priority ] -R retries ] -T timeout ] -V prognum ] Parameters Parameter mediatype… Description Specifies a list of one or more media types to be queried. Either system-specified media types and or user-defined media types can be specified.
Command Reference Parameter -h Description Requests help for the entered command. When the Help option is specified, no command line processing is performed. An exit code of 0 is returned to the client when the Help option is specified. -H hostname Host name of the VolServ server.The default host name is the host name of the computer where the CLI command is run. -P priority The execution priority of the entered command.
Command Reference Examples Step 1. Successful Media Type Query request. Requests VolServ to return information on every media type known to the VolServ system. vsmedtypeqry -a Step 2. Output returned: ----------------------------------------------Media Type Query Report May 24 12:43:18 19931 ----------------------------------------------MediaType: D2S ----------------------------------------------Capacity: 25000.
Command Reference ---------------------------------------------Media Type Query Report May 24 12:43:18 19931 ----------------------------------------------MediaType: D2S ----------------------------------------------Capacity: 25000.00 megabytes Number of Sides: 1 MediaType: USRTYPE ----------------------------------------------Error: item not found Notes The vsmedtypeqry command does not trigger unsolicited status messages from VolServ.
Command Reference vsmount Mounts media onto a drive. When issuing a Mount command, the client can specify one of the following. • Single media. • List of media. • MediaClass group. • And: - Specific drive. - Drive pool. - Drive pool with the exclusion of drives. The vsmount command’s lock identifier parameter.is required if the drive to be used in satisfying the vsmount request has been previously locked with a vslock request.
Command Reference For manual libraries, a vsmount notice is sent to the operator console for action. The operator is then responsible for confirmation to VolServ when the mount is complete. VolServ returns a return code to the client after the operator action is complete. A vsmount request is queued for later processing if: • The specified drive is busy. • The specified media is busy. • The selected drive is locked and a lock identifier was not specified on the Mount request.
Command Reference Parameters Parameter mediaid… Description Specifies a list of one through 64 media to be mounted. • A valid media identifier may contain up to 16 alphanumeric characters, including spaces. • Leading and trailing spaces are not permitted. -d driveid Specifies a drive that can be used to satisfy the Mount request. -c mediaclass Specifies a MediaClass name from which the media to be mounted is to be selected.
Command Reference Parameter Description -H hostname Host name of the VolServ server. The default host name is the host name of the computer where the CLI command is run. -n newmediaclass Specifies the destination MediaClass group for the reclassification of the media selected to satisfy the Mount request. NOTE: Use this only if the selected media is to be reclassified to a different MediaClass group. -p drivepool Specifies the name of a drive pool.
Command Reference Parameter -x driveid… Return Codes Examples Description Specifies a list of one through 64 drives contained in the specified drive pool that are to be excluded from consideration when allocating drives to satisfy the Mount request. • 0 - The vsmount command is successfully processed. • -1 - An error is detected by either the CLI software or the API software. • >0 - An error is detected by VolServ. The returned exit code corresponds to the error code given by VolServ. Step 1.
Command Reference Requests VolServ to mount media from MediaClass medclassmed onto drive 10 and to reclassify the selected media to MediaClass group medclasssh1med. vsmount -c medclassmed -d 10 -n medclasssh1med Step 2. Output returned: Mount of Media [MED027] onto Drive [10] was successful Step 1. Successful Mount request that specifies a specific media and a drive pool with an exclusion drive list. vsmount MED022 -p drvpoolusr -x 4 14 Step 2.
Command Reference Step 2. Output returned: Mount of Media [MED041] onto Drive [7] was successful Step 1. Successful Mount request when all specified drives are in use. Requests VolServ to mount media MED034 onto drive 12. (MED022 is currently mounted on drive 12.) vsmount MED034 -d 12 Step 2. Output returned: Mount waiting due to busy drive Mount of Media [MED034] onto Drive [12] was successful Step 1. Successful Mount request when specified media is in use.
Command Reference Step 1. Successful Mount request reclassifying the selected media. Requests VolServ to mount any media from MediaClass group medclassstgmed onto any drive in drive pool drvpoolmed, and to change the MediaClass association of the selected media from medclassstgmed to medclassmed. vsmount -c medclassstgmed -p drvpoolmed -n medclassmed Step 2.
Command Reference Step 2. Output returned: Media could not be mounted onto drive Error VOL110: mount crosses archives Step 1. Unsuccessful Mount request with unknown media specified. Requests VolServ to mount media BadMedia onto drive 5. vsmount BadMedia -d 5 Step 2. Output returned: Media could not be mounted onto drive Error VOL029: invalid media specified Notes The time required to satisfy a specific mount request depends on the number of available drives and pending vsmount requests.
Command Reference If a specified or selected drive was previously locked and the vsmount request does not specify a lock identifier, VolServ returns a message to the client that the selected drive is locked and VolServ is waiting for the drive to become unlocked to continue execution of the command.
Command Reference If a list of media specified in a vsmount request contains media of more than one type, the request fails. When media or drive pairing requires the media be moved within a single library system (such as cross-aisle) the mount may take a while to complete. The -i and -u options do NOT apply to intra-library system movement.
Command Reference The Mount command triggers unsolicited status messages from VolServ to the client software. Mount requests may require inter-library media movement or a Mount request can be queued waiting for an in-use media or drive. The client may want to increase the timeout value or the retries value so the CLI vsmount request does not timeout while waiting for the Mount request to complete. If the Mount request allows movement, VolServ checks the destination library for available space.
Command Reference vsmove Moves media from one library to another. A client uses the vsmove command to direct the movement of media from one library to another. Inter-library media movement requires operator intervention. The operator must eject the media from their current libraries and enter them into the target library. The Eject and Enter functionalities are available from the appropriate library’s console display. The Eject and Enter functionalities are not available from the command line.
Command Reference Parameters vsmove mediaid vsmove -a archivename [-iIhwv] [ -H hostname ] [ -P priority ] [ -R retries ] [ -T timeout ] [ -V prognum ] Parameters Parameter mediaid… Description Specifies a list of one through 64 media to be moved. • Leading and trailing spaces are not permitted. -a archivename Specifies the name of the library to which the specified media are to be moved. • Valid library names may contain up to 16 alphanumeric characters, including spaces.
Command Reference Parameter Description -w Indicates VolServ waits until the command processing completes before returning status to the client. If the move requires an inter-library move, VolServ waits until the move completes, whether the source and destination libraries are attended or unattended. When the • If -w option is not specified, final status is returned as soon as move processing begins. -v Indicates that verbose output is needed.
Command Reference Parameter -R retries Default value is 3. -T timeout Description Number of retries the CLI software attempts if a time-out is returned by the API software. Default value is 120 seconds. Amount of time (in seconds) the API software waits for status from VolServ before returning a time-out to the CLI software. Total wait time for a command is (retries plus 1) multiplied by time-out value. -V prognum RPC program number for VolServ. Default value is 300016.
Command Reference Step 2. Move 4 of 4 media Media Media Media Media Output returned: was successful [MED016] [MED028] [MED043] [MED048] no no no no error error error error Step 1. Successful Move request, verbose option not specified. Step 2. Requests VolServ to move media MED013, MED016, MED028, and MED028 to library shelf1. Since the -i option is NOT specified, the move is to complete whether the losing and gaining libraries are attended or unattended.
Command Reference Step 3. Output returned: Move 0 of 4 media was successful Error VOL024: error in the list Media [MED013] target Media [MED016] target Media [MED022] target Media [MED034] target Step 1. archive archive archive archive mode mode mode mode is is is is unattended unattended unattended unattended Errors with verbose option not specified. Requests VolServ to move media MED003, MED004, MED013, MED028, MED033, and MED043 to the shelf2 library. Step 2.
Command Reference Step 2. Output returned: Move of media was unsuccessful Error VOL107: invalid target archive Notes Movement of media is between libraries, not within libraries. Media that is allocated to a Move request is not available for other allocation until the move completes. • If the -w option is not specified, status from the Move request indicates only the initial validity of the move.
Command Reference vsping Pings the VolServ system. The vsping command allows a user to check the availability of VolServ (in other words, a means for the client systems to “ping” the VolServ system.) If VolServ responds to the vsping, it is assumed by the client that the VolServ client interface is available and functioning. The client is not required to use the vsping command before sending other commands, but vsping is available for clients to verify that VolServ software is running.
Command Reference Parameter -h Description Requests help for the entered command. When the Help option is specified, no command line processing is performed. An exit code of 0 is returned to the client when the Help option is specified. -H hostname Host name of the VolServ server. The default host name is the host name of the computer where the CLI command is run. RPC program number for VolServ. -V prognum Default value is 300016.
Command Reference Successful request, VolServ is not available Step 1. Successful request, VolServ is not available. Requests VolServ to acknowledge receipt of the Ping request. vsping Step 2. Output returned: VolServ is not available Notes The client is not required to use vsping before issuing other commands. The vsping command is a relatively fast operation. No VolServ status messages are returned in response to the vsping command.
Command Reference vspoolcfg Configures a specified drivepool. Parameters vspoolcfg -p drivepool vspoolcfg -c driveid vspoolcfg -d driveid vspoolcfg -i driveid vspoolcfg -r driveid [ [ [ [ [ [ -Ih ] -H hostname ] -P priority ] -R retries ] -T timeout ] -V prognum] Parameters Parameter -p drivepool Description Specifies a single drive pool to be queried. • Valid drive pool names may contain up to 16 alphanumeric characters, including spaces. • Leading and trailing spaces are not permitted.
Command Reference Parameter Description -I Command options are first read from the command line. VolServ then reads any options contained in the stdin file. -h Requests help for the entered command. When the Help option is specified, no command line processing is performed. An exit code of 0 is returned to the client when the Help option is specified. -H hostname Host name of the VolServ server. The default host name is the host name of the computer where the CLI command is run.
Command Reference vspoolqry Queries for information on a specified drive pool or on all drive pools known to VolServ. The command returns the list of drives contained in each drive pool. Detailed information on each individual drive is obtained by specifying the -v (verbose) option. Parameters vspoolqry drivepool vspoolqry [ [ [ [ [ [ -a -Ihv ] -H hostname ] -P priority ] -R retries ] -T timeout ] -V prognum] Parameters Parameter drivepool Description Specifies a single drive pool to be queried.
Command Reference Parameter Description -a Specifies the -a option to request information on all drive pools known to the VolServ system. -I Command options are first read from the command line. VolServ then reads any options contained in the stdin file. -h Requests help for the entered command. When the Help option is specified, no command line processing is performed. An exit code of 0 is returned to the client when the Help option is specified. -H hostname Host name of the VolServ server.
Command Reference Examples • -1 - An error is detected by either the CLI software or the API software. • >0 - An error is detected by VolServ. The returned exit code corresponds to the error code given by VolServ. Step 1. Successful Drive Pool Query request with verbose option specified. Requests the VolServ to return detailed drive information for the every drive in the drvpoolsml drive pool. vspoolqry drvpoolsml -v Step 2.
Command Reference Drive ID: 7 Drive Type: Associated Archive: Current State: Assignment: Usage Count: Mount State: Mounted Media ID: ² ² ² Magnetic tower1 Online Allocated 1 Mounted MED041 Drive Type: Associated Archive: Current State: Assignment: Usage Count: Mount State: Mounted Media ID: ² ² ² Magnetic shelf1 Diagnostic Free 0 Unmounted Drive ID: 13 Commands Step 1. Successful Drive Pool Query request with verbose option not specified.
Command Reference Drive Pool: drvpoolsml ----------------------------------------------Drive ID(s): 2467 9111314 • • ² Drive Pool: drvpooltwr ----------------------------------------------Drive ID(s): 711 • • ² Drive Pool: drvpoolstg ----------------------------------------------Drive ID(s): 139 Step 1. Unsuccessful Drive Pool Query. Requests the VolServ to return a list of drive identifiers for the NoPool drive pool. vspoolqry NoPool -v Step 2.
Command Reference A pending vspoolqry is cancelled with the VolServ cancel command. The VolServ cancel command is run from the command line by sending a SIGQUIT signal (control-\). The vspoolqry also is aborted by sending the SIGINT signal (control-c).
Command Reference vsqrymount Queries for drives that could be used in a subsequent mount of a specified media. The vsqrymount output lists the drives in the order of preference, based (in order of relative importance) upon their availability, proximity to the media, and usage time. Upon receipt of the vsqrymount request, VolServ determines which library contains the specified media: Parameters • If the specified media is not in a library, a null list of drives is returned to the client.
Command Reference Parameter Description -I Command options are first read from the command line. VolServ then reads any options contained in the stdin file. -h Requests help for the entered command. When the Help option is specified, no command line processing is performed. An exit code of 0 is returned to the client when the Help option is specified. -H hostname Host name of the VolServ server. The default host name is the host name of the computer where the CLI command is run.
Command Reference • Examples >0 - An error is detected by VolServ. The returned exit code corresponds to the error code given by VolServ. Step 1. Successful Query Mount request. Requests VolServ to return a list of drives that are candidates to be mounted with MED024. vsqrymount MED024 Step 2. Output returned: Media [MED024] can be mounted on the following drives: 1Drive [14] 2Drive [12] Step 1. Unsuccessful Query Mount request, specified media already mounted.
Command Reference Requests VolServ to return a list of drives that are candidates to be mounted with MED003. vsqrymount MED003 Step 2. Output returned: Query Mount for media [MED003] was unsuccessful. Error VOL008: item not found Notes Drives that are not online are not considered suitable for mounting and are, therefore, not returned in response to the query.
Command Reference The vsqrymount command does not trigger unsolicited status messages from VolServ. A pending vsqrymount request is cancelled with the VolServ cancel command. The VolServ cancel command is run from the command line by sending a SIGQUIT signal (control-\). The request also is aborted by sending the SIGINT signal (control-c).
Command Reference vsreclassify Changes the MediaClass name of one or more media. Upon receipt of this request, VolServ verifies that each specified media identifier references a media of the type supported by the target MediaClass group. • If all media are of the appropriate media type, VolServ verifies that the target MediaClass group is not filled to capacity. • If the target MediaClass group is filled to capacity, the vsreclassify fails and a failure return code is returned to the client.
Command Reference Parameters Parameter Description mediaid… Specifies a list of one through 64 media to be reclassified. -c currentmediaclass Specifies the MediaClass group with which the specified media are currently associated. • Valid MediaClass names may contain up to 16 alphanumeric characters, including spaces. • Leading and trailing spaces are not permitted. -n newmediaclass Specifies the new MediaClass group with which the specified media are to be associated.
Command Reference Parameter -h Description Requests help for the entered command. When the Help option is specified, no command line processing is performed. An exit code of 0 is returned to the client when the Help option is specified. -H hostname Host name of the VolServ server. The default host name is the host name of the computer where the CLI command is run. -P priority Default value is 15. Default value is 3.
Command Reference Examples Step 1. Successful Reclassify request with verbose option specified. Requests VolServ to reclassify media MED002, MED023, and MED044 from MediaClass group medclassstgsml to medclasssml and to return status on every specified media. vsreclassify MED002 MED023 MED044 -c medclassstgsml -n medclasssml -v Step 2. Output returned: Reclassify of 3 of 3 media into class [medclasssml] was successful Media [MED003] no error Media [MED023] no error Media [MED044] no error Step 1.
Command Reference Requests VolServ to reclassify media MED013, MED017, MED020, MED032, MED041, and BadMedia from MediaClass group medclasssml to medclasssh2sml and to return status on every specified media. vsreclassify MED013 MED017 MED020 MED032 MED041 BadMedia -c medclasssml -n medclasssh2sml -v Step 2. Output returned: Step 1.
Command Reference Step 2. Output returned: Reclassify of 2 of 6 media into class [medclasssh2sml] was successful Error VOL024: error in the list Media [MED013] class does not support media type Media [MED020] invalid current class Media [MED041] archive not associated with mediaclass Media [BadMedia] item not found Step 1. Unsuccessful Reclassify request.
Command Reference The capacity of a library media class is a soft limit. If the capacity of a library media class is exceeded, the entire vsreclassify request is processed unless the capacity of the associated MediaClass group is reached. When the capacity of the library media class is reached, applicable High Mark processing is initiated. An attempt to reclassify media into its current MediaClass group fails.
Command Reference vsrequestqry Queries for information about a specified request. The client must specify VolServ assigned request identifier of the request being queried. Upon receipt of a vsrequestqry request, VolServ searches its request queue for the specified request identifier. If the specified request is not found, status is returned to the client that indicates a non-existent request. If the request is found, the attribute values of the request are returned to the client.
Command Reference Parameter -h Description Requests help for the entered command. When the Help option is specified, no command line processing is performed. An exit code of 0 is returned to the client when the Help option is specified. -H hostname Host name of the VolServ server. The default host name is the host name of the computer where the CLI command is run. -P priority Default value is 15. Default value is 3.
Command Reference • Examples >0 - An error is detected by VolServ. The returned exit code corresponds to the error code given by VolServ. Step 1. Successful Request Query. Requests VolServ to return status on request 93:144:02136 (or 314402136). vsrequestqry 93:144:02136 Step 2.
Command Reference Notes The client must know the request identifier to be queried. After execution of a request completes, a relatively short period of time exists where the request shows a state of “complete.” Afterwards, all knowledge of the request is removed from the VolServ system and any subsequent queries for the command fail. The vsrequestqry command returns information for only one request per execution. The vsrequestqry command does not trigger unsolicited status messages from VolServ.
Command Reference vsunlock Releases exclusive use of one or more drives. The list of drives to be unlocked and the assigned lock identifier for those drives must be specified. A client needing to release a subset of locked drives, locked via a single lock command, can runmultiple unlock requests. Each unlock request can specify a subset of the drives held by the client. VolServ releases only those drives specified in the unlock request.
Command Reference Parameter Description -I Command options are first read from the command line. VolServ then reads any options contained in the stdin file. -h Requests help for the entered command. When the Help option is specified, no command line processing is performed. An exit code of 0 is returned to the client when the Help option is specified. -H hostname Host name of the VolServ server. The default host name is the host name of the computer where the CLI command is run.
Command Reference Examples • -1 - An error is detected by either the CLI software or the API software. • >0 - An error is detected by VolServ. The returned exit code corresponds to the error code given by VolServ. Step 1. Successful Unlock request with verbose option specified. Requests VolServ to unlock drives 4, 8, and 12, all of which have an assigned lock identifier of 1719790788, and to return status on every specified drive. vsunlock -v 4 8 12 -l 1719790788 Step 2.
Command Reference Step 1. Unsuccessful Unlock identifier with verbose option. Requests VolServ to unlock drives 40, 41, 42, and 43, three of which have an assigned lock identifier of 1719790788, and to return status on every specified drive. vsunlock -v 40 41 42 43 -l 1719790788 Step 2. Output returned: Step 1.
Command Reference Notes The client can release a subset of drives locked by a single vsunlock request. VolServ fails a vsunlockfor a drive if the lock identifier specified in the unlock request does not match the lock identifier assigned to the drive. The vsunlock command does not trigger unsolicited status messages from VolServ. A pending vsunlock is cancelled with the VolServ cancel command. The VolServ cancel command is run from the command line by sending a SIGQUIT signal (control-\).
Command Reference vswin Starts the VolServ system administrator’s console and brings up the system GUI display. Parameters vswin -display host# Parameters Parameter -display host# Example Starts the VolServ GUI. • 0 - Terminated normally. • 1 - Error occurred during initialization. Step 1. Commands Return Codes Description Initialize the VolServ System console. vswin Step 2. Run the VolServ System Console in the background. vswin & Notes The environmental variable VS_DIR must be set.
Command Reference The display location of vswin must give xhost privileges to the VolServ host machine for vswin to properly work.
Command Reference NOTES Commands 601356 Rev A Command Reference 2-155
Command Reference NOTES 2-156 Command Reference 601356 Rev A
