Command Reference
VolServ Version 5.0
September 2001
601356 Rev A
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
Information was complete.
Circle One
Disagree
Agree
Agree
Agree
Information was easy to find.
Information was easy to follow.
Disagree
Disagree
Is there anything you especially like or dislike about the organization, presentation,
or writing in this manual?_______________________________________________
___________________________________________________________________
___________________________________________________________________
___________________________________________________________________
___________________________________________________________________
Book Title
Document Number
Telephone
Customer Name
E-mail Address
Company Name
Address
City, State, Zip
NOTES
Contents
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
Options Common to all Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-3
Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-7
Command-specific Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-9
volserv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-3
vsamlconfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-5
vsarchiveqry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-7
vsarchivevary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-13
vsaudit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-17
vscleareject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-34
601356 Rev A
i
Command Reference
vsdismount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-44
vsdriveqry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-48
vsdrivevary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-52
vsimport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-64
vsintransitqry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-72
vslock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-76
vsmedclassqry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-82
vsping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-121
vspoolcfg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-124
vsreclassify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-137
vsrequestqry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-144
vsunlock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-148
vswin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-153
ii
Contents
601356 Rev A
Command Reference
NOTES
P-2
Preface
601356 Rev A
Command Reference
This book alphabetically lists and describes the VolServ
commands.
Purpose of
This Book
This book is written for system administrators who uses the
command line to operate VolServ.
Who Should
Read This
Book
It assumes the administrator has a strong familiarity with:
•
•
UNIX operating systems.
Applications running in their site environment.
This book contains the following chapters:
How This
Book is
Chapter 1: Introduction — Describes environment variables
and the command line structure.
Organized
Chapter 2: Command Reference — Alphabetical list of
VolServ commands.
601356 Rev A
Preface
P-3
Command Reference
The conventions used throughout the VolServ technical books
are listed below:
Conventions
Convention
Example
Screen text, file names, program names, and Request to add a new volume:
commands are in Courierfont.
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 vsarchiveqry
bold font.
Site-specific variables are in a Times italics
tar -xvf tapedevicename
font.
A backward slash ( \ ) denotes the input is
continued onto the next line; the printed page
is just not wide enough to accommodate the
line.
# remshnodename -n dd if=/dev \
/tapedevicename/bs=20b | tar xvfb \
- 20
(You should type the entire command without
the backward slash.)
Pressing <Return> after each command is
assumed.
A menu name with an arrow refers to a
sequence of menus.
Config-->MediaType-->Redefine
P-4
Preface
601356 Rev A
Command Reference
The books described below are part of the technical
documentation set, and are shipped on CD along with the
VolServ software:
Books
Overview
Administrative Tasks
Provides an overview of VolServ. Contains a
glossary.
Describes how to perform system
administrative tasks using VolServ
commands.
Installing VolServ
Describes server requirements, installation
instructions, troubleshooting procedures,
and configuration parameters.
Command Reference
Contains a list of VolServ commands
Error Messages
Using the VolServ GUI
Provides corrective action for system log
errors.
Describes how to perform system
administrative tasks using the graphical user
interface.
Quick Reference Card
Summarizes commands.
API Guide
Provides a list of API functions.
The documentation CD contains VolServ book files and
Online Books
®
®
Adobe Acrobat Reader. The Reader allows you to view and
navigate the online documentation files yet preserves the page
design and graphics from the printed books.
601356 Rev A
Preface
P-5
Command Reference
The publications described in the table below are created and
distributed on an as-needed basis.
Related
Publications
Related Publications
Description
“Release Notes”
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.
“Product Bulletins”
Conveys technical information—not problems—to
customers.
To make corrections or to comment on VolServ publications,
please contact Software Technical Publications at our e-mail
address: [email protected].
Contact
Publications
Department
To receive access to the secured site on our home page contain-
ing technical product information (Release Notes, Product
Alerts, Product Bulletins, FAQs), visit http://partners.adic.com/
and follow the password request procedure. In return, ADIC
will send you instructions and a password.
Secured Web
Site
P-6
Preface
601356 Rev A
Command Reference
Roadmap
Refer To
Chapter
Topic
Introduction.
Alphabetical list of commands.
1
2
1-2
Introduction
601356 Rev A
Command Reference
Seven options are available on every command that is supported
from the command line. These parameters are:
Options
Common to
all
Commands
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.
Example: cat optionfile> vsmount -I -u
-p drvpool2 instructs VolServ to first read
the -u and -p options entered on the
command line and then to read the options
from stdin(the contents of optionfile). If
optionfilecontains “-c class1”, the
command, as processed by VolServ, will look
like “vsmount -u -p drvpool2-c class1”
-h
Requests help for the entered command. The
Help option returns the usage for the entered
command, a copyright notice, and the version
number of the CLI software. The Help option
takes precedence over any other option
entered on a 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 issued.
601356 Rev A
Introduction
1-3
Command Reference
Parameter
-P priority
Description
The execution priority of the entered
command. Assignable priority values are
restricted to a range from 1 (highest) to 32
(lowest) inclusive.
Default value is
15.
-R retries
Number of retries the CLI software attempts if
a time-out is returned by the API software.
Default value is
3.
-T timeout
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.
Default value is
120 seconds.
-V prognum
RPC program number for VolServ.
Default value is
300016.
The following parameters are optional:
Optional
Parameters
•
•
-I (read from stdin).
-h (help).
Both options needs to be specified only if the client is
requesting the functionality provided by the option.
The remaining parameters have default values:
Default Values
•
•
•
-H (hostname).
-P (priority).
-R (retries).
1-4
Introduction
601356 Rev A
Command Reference
•
•
-T (timeout).
-V (prognum).
If the client does not specify one or more of these options on a
command, VolServ uses the appropriate default values specified
in the description of the previous options.
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.
The environment variables and their associated common
options are:
Parameter
-H hostname
Environment Variable*
VSCLI_HOST
-P priority
-R retries
VSCLI_PRIORITY
VSCLI_RETRIES
VSCLI_TIMEOUT
VSCLI_PROGNUM
-T timeout
-V prognum
The client runs the UNIX setenvcommand to set an
environment variable.
Example
The following example sets the default for the -H ( hostname )
option to eiffeland overrides the VolServ default. The
default hostname is the host computer where the command is
issued.
setenv VSCLI_HOST eiffel
Or,
601356 Rev A
Introduction
1-5
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.
1-6
Introduction
601356 Rev A
Command Reference
The following environment variables provide the capability for
the client to specify default values for common options:
Environment
Variables
• VSCLI_HOST
• VSCLI_PRIORITY
• VSCLI_RETRIES
• VSCLI_TIMEOUT
• 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.
If the default page length is not appropriate, a client can execute
the appropriate environment variable command to set the
VSRPT_PAGE_LENGTHenvironment variable to the desired
page length. If the VSRPT_PAGE_LENGTHenvironment variable
is set to 0, VolServ generates reports with no page breaks.
VolServ uses the user-specified page length when generating the
following reports.
•
•
•
•
•
•
Archive Query
Connect Query
Drive Query
Intransit Query
MediaClass Query
Drive Pool Query
601356 Rev A
Introduction
1-7
Command Reference
•
•
•
Request Query
Media Type Query
Media Query
1-8
Introduction
601356 Rev A
Command Reference
A matrix that shows which commands support which
command-specific options is included in below
Command-
specific
A discussion of how each of these options direct or modify the
processing of individual commands is included with the
command descriptions in this discussion.
Options
Command-specific options are described in the following
outline.
Parameter
Description
Example
vsdriveqry -a
-a
Specifies that all items meet
specified criteria that are to be
processed.
Instructs VolServ to return
information on all drives known to
the VolServ system.
Used primarily on query
commands.
-a archivename
Specifies the name of the
archive to be referenced by the
command.
vsimport … -a archive1 …
Instructs VolServ to import the
specified medium/media into the
archive1archive.
Valid archive names may
contain up to 16 alphanumeric
characters, including spaces.
Leading and trailing spaces are
not permitted.
archivename
Specifies the name of the
archive to be referenced by the
command.
vsarchivevary archive1…
Specifies that VolServ is to vary
the state of the archive1
archive.
Valid archive names may
contain up to 16 alphanumeric
characters, including spaces.
Leading and trailing spaces are
not permitted.
601356 Rev A
Introduction
1-9
Command Reference
Parameter
Description
Example
-b
Identifies the batch assigned to
the medium/media being
imported.
vsimport … -b batch1…
Identifies batch1as the batch
assigned to the medium/media
being imported. The batch
assigned to a medium is
maintained by the VolServ
system.
-c
Indicates that all MediaClass
names associated with the
specified archive are to be
reported.
vsarchiveqry … -c …
Instructs VolServ to return all
MediaClass names associated
with the specified archive.
-c currentmediaclass
Identifies the current
MediaClass name of the
medium/media to be
reclassified.
vsreclassify … -c
MediaClassA…
Indicates to VolServ that the
medium/media specified on the
command are currently
associated with MediaClassA.
-c mediaclass
Identifies the target MediaClass vsimport … -c MediaClassB…
name of the medium/media
specified on the command.
Instructs VolServ to associate the
imported medium/media with
MediaClassB.
-d
Indicates that all drives
vsarchiveqry … -d …
associated with the specified
archive are to be reported.
Instructs VolServ to return all
drive IDs associated with the
specified archive.
-d driveID
Identifies the drive on which the vsdismount … -d 1…
medium to be dismounted is
currently mounted.
Indicates to VolServ that the
medium specified to be
dismounted is currently mounted
on drive 1.
1-10
Introduction
601356 Rev A
Command Reference
Parameter
driveID…
Description
Example
vsunlock 13…
Specifies a list of one or more
drives from which the drives to
satisfy the command are to be
selected.
Instructs VolServ to unlock drive 1
and drive 3.
The number of drives that can
be specified is restricted by the
CLI software. Currently, the
maximum allowed number is 64.
drivepool
Specifies the name of the drive
pool being queried.
vspoolqry drivepool3
Instructs VolServ to return
information on drive pool3.
enterpriseID
Specifies the identifier of the
enterprise connection being
queried.
vsconnectqry 4
Instructs VolServ to return
information on the 4connection.
An enterprise ID must be
numeric.
-f
Identifies the manufacturer of
the medium/media being
imported.
vsimport … -f manufac1…
Identifies manufac1as the
manufacturer of the
medium/media being imported.
The manufacturer of a medium is
maintained by the VolServ
system.
-i
Indicates, if an inter-archive
move is required, that the
command is to be processed
only if both the source and
destination archives are
attended.
vsmount … -i …
Instructs VolServ to perform the
mount if an inter-archive move is
required only if both the source
and destination archives are
attended.
601356 Rev A
Introduction
1-11
Command Reference
Parameter
Description
Example
-l lockID
Specifies the lock ID assigned
to the drive specified in the
command.
vsdismount … -l 9…
Indicates that the drive specified
in the command is reserved for
exclusive use and has been
assigned the lock ID 9.
-m
Indicates that all media
vsarchiveqry … -m …
associated with the specified
archive are to be reported.
Instructs VolServ to return all
media IDs associated with the
specified archive.
mediaclass
Specifies the name of the
MediaClass group being
queried.
vsmedclassqry medclass6…
Instructs VolServ to return
information on medclass6.
mediaID
Specifies the medium to be
processed by the command.
vsqrymount medium7
Requests a list of the drives
available to satisfy a mount
request for medium7.
A valid medium identifier may
contain up to 16 alphanumeric
characters, including spaces.
Leading and trailing spaces are
not permitted.
mediaID…
Specifies a list of one or more
media to be processed by the
command.
vsexport medium8 medium 9
medium11 medium3…
Instructs VolServ to export
medium8, medium9, medium11,
and medium3.
A valid medium identifier may
contain up to 16 alphanumeric
characters, including spaces.
Leading and trailing spaces are
not permitted.
The number of media that can
be specified is restricted by the
CLI software. Currently, the
maximum allowed number is 64.
1-12
Introduction
601356 Rev A
Command Reference
Parameter
mediatype…
Description
Example
Specifies a list of one or more
mediatypes to be processed by
the command.
vsmedtypeqry medtypeZ
Instructs VolServ to return
information on medtypeZ.
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.
-n newmediaclass
-p drivepool
Identifies the target MediaClass MedClassX…
group of the medium/media
specified on the command.
Instructs VolServ to associate the
specified medium/media with
MedClassX.
Specifies the name of a drive
pool from which a drive can be
selected to satisfy the
command.
vsmount … -p drivepool1…
Instructs VolServ to mount the
specified medium/media on
drives selected from drive pool
drivepool1.
Valid drive pool names may
contain up to 16 alphanumeric
characters, including spaces.
Leading and trailing spaces are
not permitted.
-q quantity
Specifies the number of drives
to be locked.
vslock … -q 3…
Instructs VolServ to lock three
drives.
601356 Rev A
Introduction
1-13
Command Reference
Parameter
Description
Example
requestID
Specifies VolServ-assigned ID
of the request being queried.
vsrequestqry 93:131:14796…
Requests status on request
A valid request ID must be
specified in either the
93:131:14796from VolServ.
ydddnnnnnformat or the
yy:ddd:nnnnnformat where y
and yy represent the last
one/two digits of the year, ddd
represents the Julian day, and
nnnnnis a one-up number.
-s compstate
Specifies the target state of the
item being varied.
vsdrivevary …-s on-line…
Instructs VolServ to vary the
specified drive to the on-line
state.
-t
Indicates that all media types
associated with the specified
archive are to be reported.
vsarchiveqry … -t …
Instructs VolServ to return all
media types associated with the
specified archive.
-t comment
Provides a comment to be
associated with each media
specified on the command.
VolServ maintains the comment,
if any, associated with each
medium. This comment is
provided on the Eject list (a GUI
display) from the archive
vscheckout … -t “Sending
tocustomer xyz”
Provides the comment “Sending
to customer xyz” to be
associated with each medium
specified in the command.
console associated with the
archive containing the media.
-u
Indicates the command is to be
processed if an inter-archive
move is required whether the
source and destination archives
are attended or unattended.
vsmount … -u …
Instructs VolServ to perform the
mount if an inter-archive move is
required whether the losing and
gaining archives are attended or
unattended.
1-14
Introduction
601356 Rev A
Command Reference
Parameter
Description
Example
-v
Indicates that verbose output is
requested.
vscleareject … -v …
Instructs VolServ to return status
on every medium specified in the
command, regardless of whether
• If -v option is specified on a
command that specifies a list
of items, status is returned on the medium is successfully or
every item specified in the list, unsuccessfully processed. If the
regardless of the success or
failure of the command
processing on each item.
-v option is not specified on the
vscleareject command, status is
returned on only those media that
are not successfully removed
from the Eject list.
• If -v option is specified on a
query command, all
applicable information is
returned to the client.
vsmedclassqry … -v
Instructs VolServ to return
• 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.
detailed information for all media
associated with each media class
reported. If the -v option was not
specified on the vsmedclassqry
command, only the IDs of the
media associated with the
• If -v option is not specified on
a query command, only the
specifically requested
information is returned to the
client.
reported MediaClass group are
returned to the client.
-w
Indicates VolServ waits until the vsmove … -w …
command processing
completes before returning
status to the client.
Instructs VolServ to return status
only after move processing
completes.
If the move requires an
inter-archive move, VolServ
waits until the move completes,
whether the source and
destination archives are
attended or unattended. When
the -w option is not specified,
final status is returned as soon
as move processing begins.
601356 Rev A
Introduction
1-15
Command Reference
Parameter
Description
Example
vsmount …-p
-x
Specifies a list of one or more
drives to exclude from a
specified drive pool when
selecting drives to satisfy a
command.
: drvpoolmed-x 1 2…
Instructs VolServ to exclude
drives 1and 2from
consideration when selecting
drives from the drvpoolmed
drive pool to satisfy the mount
request.
The -x option is valid only when
the -p drivepooloption is
specified.
The names of the commands, as entered from the command
line, are listed alphabetically in the first column of the table.
The command-specific options are listed alphabetically across
the top of the table.
Tables
•
When a command does not support an option, the cell that
represents the intersection of the command and the
command-specific option is shaded. For example, the
vsdismountcommand does not support the -a
archivename option.
•
When a command does support an option, the cell that
represents the intersection of the command and the option
contains an X. For example, the vsdismountcommand
does support the -d driveID, the -l lockID option, and the
mediaID option.
1-16
Introduction
601356 Rev A
Command Reference
-a
archive
name
-c
current
mediaclass
-b
-c
-a (all)
archivename
batchID (MediaClass)
vsamlconfig
vsarchiveqry
vsarchivevary
vsaudit
X
X
X
X
X
X
vscheckin
vscheckout
vscleareject
vsconnectqry
vsdismount
vsdriveqry
vsdrivevary
vsexport
X
X
vsimport
X
X
vsintransitqry
vslock
vsmedclassqry
vsmedqry
vsmedtypeqry
vsmount
X
X
X
vsmove
X
vsping
vspoolqry
X
vsqrymount
vsreclassify
vsrequestqry
vsunlock
X
601356 Rev A
Introduction
1-17
Command Reference
-i
-f
-l
-m
(mount,
attended)
mediaclass
manufacturer
lockID
(mediaIDs)
vsamlconfig
vsarchiveqry
vsarchivevary
vsaudit
X
vscheckin
vscheckout
vscleareject
vsconnectqry
vsdismount
vsdriveqry
vsdrivevary
vsexport
X
vsimport
X
vsintransitqry
vslock
vsmedclassqry
vsmedqry
vsmedtypeqry
vsmount
X
X
X
X
X
vsmove
vsping
vspoolqry
vsqrymount
vsreclassify
vsrequestqry
vsunlock
X
1-18
Introduction
601356 Rev A
Command Reference
-n
new
mediaclass
-p
-q
mediaID mediaID… mediatype
drivepool quantity
vsamlconfig
vsarchiveqry
vsarchivevary
vsaudit
vscheckin
vscheckout
vscleareject
vsconnectqry
vsdismount
vsdriveqry
vsdrivevary
vsexport
X
X
X
X
X
X
X
vsimport
vsintransitqry
vslock
X
X
X
vsmedclassqry
vsmedqry
vsmedtypeqry
vsmount
X
X
X
X
X
X
vsmove
vsping
vspoolqry
vsqrymount
vsreclassify
vsrequestqry
vsunlock
X
X
601356 Rev A
Introduction
1-19
Command Reference
-t
-u
(mount,
unattended)
-u
usage
time
request
ID
-t
-s
(Media
Types)
comment compstate
vsamlconfig
vsarchiveqry
vsarchivevary
vsaudit
X
X
vscheckin
vscheckout
vscleareject
vsconnectqry
vsdismount
vsdriveqry
vsdrivevary
vsexport
X
X
X
X
vsimport
vsintransitqry
vsmedclassqry
vslock
vsmedqry
vsmedtypeqry
vsmount
X
vsmove
vsping
vspoolqry
vsqrymount
vsreclassify
vsrequestqry
vsunlock
X
1-20
Introduction
601356 Rev A
Command Reference
-v
-w
-x
(verbose)
(wait)
driveID…
vsamlconfig
vsarchiveqry
vsarchivevary
vsaudit
vscheckin
vscheckout
vscleareject
vsconnectqry
vsdismount
vsdriveqry
vsdrivevary
vsexport
X
X
X
X
X
vsimport
vsintransitqry
vsmedclassqry
vslock
X
X
X
vsmedqry
vsmedtypeqry
vsmount
vsmove
X
X
X
X
X
vsping
vspoolqry
vsqrymount
vsreclassify
vsrequestqry
vsunlock
601356 Rev A
Introduction
1-21
Command Reference
All files necessary for command line interface to VolServ are
contained in the volserv/vsclidirectory by default.
However, the installer may choose a different directory during
execution of the installation script. The vsclisubdirectory is
always appended to the directory specified by the installer.
Refer to Installing VolServ for more information.
CLI Directory
Structure
The system administrator or clients may use the commands to
interface to VolServ. The commands are interfaced to VolServ
via the API. For more information, refer to the Command
Reference and API Guide.
The default command directory structure is shown in the
following figure and described in the table below.
/volserv/vscli
/util
/bin
/man
Directory
bin
Contents
Contains the CLI executables that are invoked
from the command line by the system
administrator and the system operator.
man
util
Contains man pages for each executable in the
/bindirectory.
Contains several utilities and associated .README
files.
1-22
Introduction
601356 Rev A
Command Reference
NOTES
601356 Rev A
Introduction
1-23
Command Reference
NOTES
1-24
Introduction
601356 Rev A
Command Reference
Roadmap
Refer To
Chapter
Topic
Introduction.
1
2
Alphabetical list of commands.
2-2
Command Reference
601356 Rev A
Command Reference
Starts or ends VolServ and activates the system log display.
volserv
volserv -s
volserv -t | -q
volserv [-y]
Parameters
Parameters
Parameters
Description
-s
Starts VolServ in the single user mode. Only
commands run with vswinare 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).
The termination of VolServ prompts the user to
continue the software termination.
• If the -y option is specified, the prompt is
automatically answered as “yes” and the
software is terminated automatically.
NOTE: If a VolServ request is submitted to the
system duringVolServ system termination,
VolServ issues a message which states that the
system is unavailable.
-q
-y
Quits the VolServ operations. The user will be
prompted to verify if the software should really be
shutdown if the -y option is not specified..
Automatically answers the command prompt with
a “yes.”
601356 Rev A
Command Reference
2-3
Command Reference
Return Codes
•
•
0 - Command completed successfully - VolServ started or
completed normally.
1 - Command did not complete successfully - VolServ did
not start or complete as expected.
Examples
Step 1.
Step 2.
Successful VolServ system start-up. Requests
VolServ to start.
volserv
Output returned:
VolServ Version x.0.0 for SunOS (x.x)
-- Copyright (c) 1992-1999 ADIC.
Initiating VolServ start up
Setup environment variables ok
Starting up process server… Done
Process server started ok
Starting up VolServ server processes
… Done
Server processes started ok
Starting up VolServ system processes
… Done
System processes started ok
VolServ start up completed
Notes
The environment variables VS_DIRand II_SYSTEMmust be
set before executing VolServ.
II_SYSTEMmust be in the path.
See Also
•
vswin (l)
2-4
Command Reference
601356 Rev A
Command Reference
Starts the ADIC-GRAU AML (Automated Media Library)
configuration script.
vsamlconfig
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
Parameters
Example
Configure an AML.
Step 1.
vsamlconfig
Step 2. AML CONFIG MENU
Step 3. [C]onfigure a New Archive
Step 4. [R]econfigure a existing Archive
Step 5. [D]elete an existing Archive
Step 6. [Q]uit
Step 7.
Step 8. Enter Archive Name: ArchiveName
Step 9. Is ArchiveName correct (Y/N [Y]):
Enter option (C/R/D/Q/) :Option
601356 Rev A
Command Reference
2-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. Is PortNum correct (Y/N [Y]):
The Archive Configuration completed successfully.
Cycle VolServ to bring up the library
See Also
None
2-6
Command Reference
601356 Rev A
Command Reference
Queries for information about a specified library.
vsarchiveqry
vsarchiveqry archivename
Parameters
vsarchiveqry -a
[ -cdIhmtv ]
[ -H hostname ]
[ -P priority ]
[ -R retries ]
[ -T timeout ]
[ -V prognum ]
Parameters
Parameters
Description
archivename
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.
-a
-c
Specifies that all libraries are to be queried.
Indicates that detailed information on all
MediaClass groups associated with the
specified libraries are to be reported.
-d
-m
-t
Indicates that all drives associated with the
specified libraries are to be reported.
Indicates that all media associated with the
specified libraries are to be reported.
Indicates that detailed information on all
media types associated with the specified
libraries are to be reported.
601356 Rev A
Command Reference
2-7
Command Reference
Parameters
Description
-v
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 stdinfile.
-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
-P priority
Host name of the VolServ server. The default
host name is the host name of the computer
where the CLI command is run.
The execution priority of the entered
command. Assignable priority values are
restricted to a range from 1 (highest) to 32
(lowest) inclusive.
Default value is
15.
-R retries
The number of retries the CLI software
attempts if a time-out is returned by the API
software.
Default value is
3.
-T timeout
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.
Default value is
120 seconds.
-V prognum
RPC program number for VolServ.
Default value is
300016.
2-8
Command Reference
601356 Rev A
Command Reference
Return Codes
•
•
•
0 - The vsarchiveqrycommand 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.
Examples
Step 1.
Successful library query. Requests VolServ to return
the MediaClass groups and the media types
associated with the shelf1library.
vsarchiveqry shelf1 -ct
Step 2.
Output returned:
-----------------------------------------------
Archive Query Report
12:43:18 1993
May 24
1
-----------------------------------------------
Archive: shelf1
-----------------------------------------------
Archive Type:
Current State:
Archive Mode:
DataShelf
online
Attended
Console Display Location:columbia:0
Fill Mode:
None
Configure State:
Not Being
Configured
MediaClass:
MC-D2M
D2M
50%
40
MediaType:
Class Capacity %:
Class Capacity:
Current Fill Level:
2
601356 Rev A
Command Reference
2-9
Command Reference
Action:
None
MediaType:
D2M
40
2
Archive Capacity:
Current Fill Level:
Assigned Locations:
Auto Checkin:
Auto Import:
Action:
2
off
off
None
Step 1.
Step 2.
Successful library query. Requests VolServ to return
the drives, the media, the MediaClass groups, and
the media types associated with the stage1library.
vsarchiveqry stage1 -v
Output returned:
----------------------------------------------
Archive Query Report
12:59:38 1993
May 24
1
-----------------------------------------------
Archive: stage1
-----------------------------------------------
Archive Type:
Current State:
Archive Mode:
Stage
online
Attended
Console Display Location:columbia:0
Fill Mode:
None
Configure State:
Not Being
Configured
2-10
Command Reference
601356 Rev A
Command Reference
Drive ID(s):
Media ID(s):
12
med001med002
med004
med003
MediaClass:
MC-3480
3480
50%
100
4
MediaType:
Class Capacity %:
Class Capacity:
Current Fill Level:
Action:
None
MediaType:
3480
100
4
Archive Capacity:
Current Fill Level:
Assigned Locations:
Auto Checkin:
Auto Import:
Action:
4
off
off
None
Step 1.
Step 2.
Unsuccessful library query. Requests VolServ to
return the drives associated with the
BadArchiveNamelibrary.
vsarchiveqry BadArchiveName -d
Output returned:
Archive query was unsuccessful
Error VOL008: item not found
Notes
The vsarchiveqrycommand does not trigger unsolicited
status messages from VolServ.
601356 Rev A
Command Reference
2-11
Command Reference
A pending or executing vsarchiveqryrequest 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).
See Also
•
vsarchivevary
2-12
Command Reference
601356 Rev A
Command Reference
Varies the state of a library.
vsarchivevary
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.
vsarchivevary -s state archivename
Parameters
[ -Ih ]
[ -H hostname ]
[ -P priority ]
[ -R retries ]
[ -T timeout ]
[ -V prognum ]
Parameters
Parameters
-s state
Description
Specifies the target state of the specified
drives. Valid drive states are
• online (on)
• offline (of)
• diagnostic (d)
archivename
Identifies the library to be varied.
• Valid library 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 stdinfile.
601356 Rev A
Command Reference
2-13
Command Reference
Parameters
Description
-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
-P priority
Host name of the VolServ server. The default
host name is the host name of the computer
where the CLI command is run.
The execution priority of the entered
command. Assignable priority values are
restricted to a range from 1 (highest) to 32
(lowest) inclusive.
Default value is
15.
-R retries
The number of retries the CLI software
attempts if a time-out is returned by the API
software.
Default value is
3.
-T timeout
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.
Default value is
120 seconds.
-V prognum
RPC program number for VolServ.
Default value is
300016.
2-14
Command Reference
601356 Rev A
Command Reference
Return Codes
•
•
•
0 - The vsarchivevarycommand 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.
Examples
Step 1.
Step 2.
Successful archive vary. Requests VolServ to vary
the shelf1archive to the diagnosticstate.
vsarchivevary shelf1 -s diagnostic
Output returned:
Vary of archive [shelf1] to state [diagnostic]
was successful
Step 1.
Unsuccessful archive vary. Requests VolServ to vary
the BadArchiveNamearchive to the on-line
state.
vsarchivevary BadArchiveName -s
online
Step 2.
Output returned:
Vary of archive [BadArchiveName] to state
[on-line] was unsuccessful
Error VOL013: invalid archive
Notes
VolServ rejects all incoming requests that could physically
command an offline or diagnostic library (for example: Mount,
Dismount, and Move).
601356 Rev A
Command Reference
2-15
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 vsarchivevaryrequest 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).
See Also
•
•
vsarchiveqry
vsdrivevary
2-16
Command Reference
601356 Rev A
Command Reference
Performs library inventory verification.
vsaudit
•
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.
•
However, if the specified library is a manually controlled,
the library operator is directed to generate the audit report.
The operator then directs the report to be printed or to verify
the information online. Either way, the operator performs
the inventory and corrects any reported discrepancies.
Discrepancies are resolved by issuing appropriate media
management commands (for example, Eject) to relocate
media to the appropriate locations. Audits of manual
libraries do not return a discrepancy list.
Although audit requests from the command line are for full
library audits only, subset audits can be performed from the
GUI.
Tip
Full archive audits are lengthy and should be requested with
discretion.
vsaudit archivename
Parameters
[ -Ih ]
[ -H hostname ]
[ -P priority ]
[ -R retries ]
[ -T timeout ]
[ -V prognum ]
601356 Rev A
Command Reference
2-17
Command Reference
Parameters
Parameters
Description
archivename
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 stdinfile.
-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
-P priority
Host name of the VolServ server. The default
host name is the host name of the computer
where the CLI command is run.
The execution priority of the entered
command. Assignable priority values are
restricted to a range from 1 (highest) to 32
(lowest) inclusive.
Default value is
15.
-R retries
The number of retries the CLI software
attempts if a time-out is returned by the API
software.
Default value is
3.
-T timeout
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.
Default value is
120 seconds.
2-18
Command Reference
601356 Rev A
Command Reference
Parameters
Description
RPC program number for VolServ.
-V prognum
Default value is
300016.
Return Codes
•
•
0 - The vsauditcommand 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.
Examples
Step 1.
Step 2.
Successful audit request. Requests VolServ to audit
the shelf1archive.
vsaudit shelf1
Output returned:
-----------------------------------------------
Audit Report
12:43:18 1993
May 24
1
-----------------------------------------------
Archive: shelf1
-----------------------------------------------
no discrepancies found
Step 1.
Unsuccessful audit request. Requests VolServ to
audit the BadArchiveName archive.
vsaudit BadArchiveName
601356 Rev A
Command Reference
2-19
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 vsauditrequest 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).
Note
A pending or executing vsauditrequest is reprioritized
using the VolServ reprioritize command. The reprioritize
command is not available from the command line, but is
available to the client through either the API or the RPC
interface.
A pending or executing Storage Technology ACS product
family library audit requires a Cassette Autoloader Port (CAP).
If the CAP is busy, the vsauditcommand can be queued. This
results in intermediate status that indicates the vsaudit
command is waiting for a busy CAP to be freed.
In an ADIC/GRAU DataTower or Storage Technology ACS
product family database, VolServ does not actually track media
location to the bin level, but only down to the Manipulator Unit
(MU) level. However, the logic and VolServ responses are
similar to the bin tracking performed in the DataLibrary
software with no internal database.
The vsauditcommand does not trigger unsolicited status
messages from VolServ.
2-20
Command Reference
601356 Rev A
Command Reference
The total length of time that VolServ waits for a command
status, in synchronous mode, from VolServ is
(VSID_RETRY_LIMITplus 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.
See Also
None
601356 Rev A
Command Reference
2-21
Command Reference
Logically checks media into the VolServ system that has been
previously checked out of the VolServ system.
vscheckin
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. The Enter functionality is not available from
the command line.
vscheckin mediaid…
Parameters
[ -a archivename]
[ -Ihv ]
[ -H hostname ]
[ -P priority ]
[ -R retries ]
[ -T timeout ]
[ -V prognum ]
Parameters
Parameter
mediaid…
Descrition
Specifies a list of one through 64 media to be
checked in.
• A valid media identifier may contain up to
16 alphanumeric characters, including
spaces.
• Leading and trailing spaces are not
permitted.
2-22
Command Reference
601356 Rev A
Command Reference
Parameter
Descrition
-a archivename
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 vscheckoutcommand.
NOTE: If -vis not specified, status is returned
on only those media that were not
successfully checked out.
-I
Command options are first read from the
command line. VolServ then reads any
options contained in the stdinfile.
-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
-P priority
Host name of the VolServ server. The default
host name is the host name of the computer
where the CLI command is run.
The execution priority of the entered
command. Assignable priority values are
restricted to a range from 1 (highest) to 32
(lowest) inclusive.
Default value is
15.
-R retries
Number of retries the CLI software attempts if
a time-out is returned by the API software.
Default value is
3.
601356 Rev A
Command Reference
2-23
Command Reference
Parameter
-T timeout
Descrition
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.
Default value is
120 seconds.
-V prognum
RPC program number for VolServ.
Default value is
300016.
Return Codes
•
•
0 - The vscheckincommand 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.
Examples
Step 1.
Successful Checkin request with verbose option
specified. Requests VolServ to check MED012,
MED014, and MED023into the library from
which they were checked out and to return status on
each media.
vscheckin MED012 MED014 MED023 -v
Step 2.
Output returned:
Check in 3 of 3 media was successful
Media [MED012]
Media [MED014]
Media [MED023]
no error
no error
no error
2-24
Command Reference
601356 Rev A
Command Reference
Step 1.
Step 2.
Successful Checkin request with verbose option not
specified. Requests VolServ to check MED013into
the shelf2 library and to return status on media
only if processing for that media failed.
vscheckin MED013 -a shelf2
Output returned:
Check in 1 of 1 media was successful
Step 1.
Errors with verbose option specified. Requests
VolServ to check MED011, MED014, and
MED021into the library from which they were
checked out and to return status on every specified
media.
vscheckin MED011 MED014 MED021 -v
Step 2.
Output returned:
Check in 1 of 3 media was successful
Error VOL024: error in the list
Media [MED011]
invalid action
or location state
for operation
no error
Media [MED014]
Media [MED021]
item not found
601356 Rev A
Command Reference
2-25
Command Reference
Step 1.
Errors with verbose option not specified. Requests
VolServ to check MED001, MED002, and
MED093into the stage1 library and to return
status on media only if processing for that media
failed:
vscheckin MED001 MED002 MED093 -a
stage1
Step 2.
Output returned:
Check in 1 of 3 media was successful
Error VOL024: error in the list
Media [MED001] archive not associated with
media class
Media [MED093]
item not found
Notes
Media checked out of one library can be checked in to another
library, as long as the receiving library is configured to support
the media’s MediaClass group and the receiving library is not at
capacity for the media’s media type.
Media checked out from more than one library can be checked
in as a single group into a single new library (assuming
necessary library media class associations exist).
Media that are checked out from more than one library and are
checked in as a single group without a target library specified on
the vschechincommand are returned to their respective
check-out libraries.
Failure of the vscheckinrequest for one or more media in a
list does not fail the request for all media in the list.
The vscheckincommand triggers unsolicited status messages
from VolServ to the client software.
2-26
Command Reference
601356 Rev A
Command Reference
A pending or executing vscheckinrequest 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).
See Also
•
vscheckout
601356 Rev A
Command Reference
2-27
Command Reference
Checks media out of the VolServ system.
vscheckout
Media that has been checked out is still known by VolServ, but
is unavailable for client allocation.
Upon receipt of a vscheckoutrequest, 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. An operator selects the “Eject” functionality
from the appropriate librarie’s console display to physically
remove the checked-out media from the containing library.
vscheckout mediaid…
Parameters
[-t comment]
[ -Ihv ]
[ -H hostname ]
[ -P priority ]
[ -R retries ]
[ -T timeout ]
[ -V prognum ]
Parameters
Parameter
mediaid…
Description
Specifies a list of one through 64 media to be
checked out of the VolServ system.
• A valid media identifier may contain up to
16 alphanumeric characters, including
spaces.
• Leading and trailing spaces are not
permitted.
2-28
Command Reference
601356 Rev A
Command Reference
Parameter
-t comment
Description
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 vscheckoutcommand.
NOTE: If -vis not specified, status is returned
on only those media that were not
successfully checked out.
-I
Command options are first read from the
command line. VolServ then reads any
options contained in the stdinfile.
-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
-P priority
Host name of the VolServ server. The default
host name is the host name of the computer
where the CLI command is run.
The execution priority of the entered
command. Assignable priority values are
restricted to a range from 1 (highest) to 32
(lowest) inclusive.
Default value is
15.
-R retries
Number of retries the CLI software attempts if
a time-out is returned by the API software.
Default value is
3.
601356 Rev A
Command Reference
2-29
Command Reference
Parameter
-T timeout
Description
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.
Default value is
120 seconds.
-V prognum
RPC program number for VolServ.
Default value is
300016.
Return Codes
•
•
0 - The vscheckoutcommand 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.
Examples
Step 1.
Successful Checkout request with verbose option
specified. Requests VolServ to check
MED003,MED004,and MED005out of the
VolServ system and to return status on every
specified media.
vscheckout MED003 MED004 MED005 -t
“Transfer to Library“ -v
Step 2.
Output returned:
Check out 3 of 3 media was successful
Media [MED003]
Media [MED004]
Media [MED005]
no error
no error
no error
2-30
Command Reference
601356 Rev A
Command Reference
Step 1.
Successful Checkout request with verbose option
not specified. Requests VolServ to check MED003,
MED004, MED005, MED006, MED007, and
MED008out 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.
Errors with verbose option specified. Requests
VolServ to check MED010, MED011, MED012,
and MED13out of the VolServ system and to return
status on every specified media.
vscheckout MED010 MED011 MED012
MEDa13 -v
Step 2.
Output returned:
Check out 2 of 4 media was successful
Error VOL024: error in the list
Media [MED010]
invalid action or location
state for operation
no error
no error
Media [MED011]
Media [MED012]
Media [MED013]
item not found
601356 Rev A
Command Reference
2-31
Command Reference
Step 1.
Errors with verbose option not specified. Requests
VolServ to check MED010, MED011, MED012,
and MEDa13out of the VolServ system and to
return status on media only if processing for that
media failed:
vscheckout MED010 MED011 MED012
MEDa13
Step 2.
Output returned:
Check out 2 of 4 media was successful
Error VOL024: error in the list
Media [MED010]
Media [MED013]
invalid action or location
state for operation
item not found
Notes
Failure of the vscheckoutrequest for one or more media in a
list does not fail the request for all media in the list.
A currently allocated media is checked out of the VolServ
system. Attempts to physically eject an allocated media fail
until the media is no longer in use.
Media marked for checkout is unmarked (removed from the
Eject list) by the Clear Eject command. An operator removes
media from the Eject list by performing an Eject Fail operation
from the appropriate library’s console display. The Eject Fail
functionality is not available from the command line.
The Clear Eject command is available to clients, whereas, Fail
Eject is an operator-only command.
The vscheckoutcommand triggers unsolicited status
messages from VolServ.
2-32
Command Reference
601356 Rev A
Command Reference
A pending or executing vscheckoutrequest 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).
See Also
•
vscheckin, vscleareject
601356 Rev A
Command Reference
2-33
Command Reference
Removes the specified media from the library’s Eject list.
vscleareject
Ejects can be generated during processing of the VolServ
vscheckoutvsexport, vsmount, and vsmovecommands.
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. For example, if a client issues an
export command for a specific media, the specified media is
scheduled for removal by adding the media to the Eject list for
the library associated with the media. If the client decides the
media should not be removed from its associated library, the
client issues the Clear Eject command, and VolServ removes
the media from the Eject list, thus voiding the Export request.
vscleareject mediaid…
Parameters
[ -Ihv ]
[ -H hostname ]
[ -P priority ]
[ -R retries ]
[ -T timeout ]
[ -V prognum]
2-34
Command Reference
601356 Rev A
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 vscheckoutcommand.
NOTE: If -vis not specified, status is returned
on only those media that were not
successfully checked out.
-I
Command options are first read from the
command line. VolServ then reads any
options contained in the stdinfile.
-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
-P priority
Host name of the VolServ server. The default
host name is the host name of the computer
where the CLI command is run.
The execution priority of the entered
command. Assignable priority values are
restricted to a range from 1 (highest) to 32
(lowest) inclusive.
Default value is
15.
-R retries
Number of retries the CLI software attempts if
a time-out is returned by the API software.
Default value is
3.
601356 Rev A
Command Reference
2-35
Command Reference
Paramaeter
-T timeout
Description
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.
Default value is
120 seconds.
-V prognum
RPC program number for VolServ.
Default value is
300016.
Return Codes
•
•
•
0 - The vsclearejectcommand 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.
Examples
Step 1.
Successful with verbose option specified. Requests
VolServ to remove MED017, MED021, and
MED023from the Eject list and to return status on
each specified media.
vscleareject MED017 MED021 MED023 -v
Step 2.
Output returned:
Clear Eject 3 of 3 media was successful
Media [MED017]
Media [MED021]
Media [MED023]
no error
no error
no error
2-36
Command Reference
601356 Rev A
Command Reference
Step 1.
Successful with verbose option not specified.
Requests VolServ to remove MED016, MED018,
MED020, and MED021from the Eject list and to
return status on media only if processing for that
media failed.
vscleareject MED016 MED018 MED020
MED021
Step 2.
Step 1.
Output returned:
Clear Eject 4 of 4 media was
successful
Errors with verbose option specified. Requests
VolServ to remove MED012, MED013, MED014,
and MED051from the Eject list and to return status
on every specified media.
vscleareject MED012 MED013 MEd014
MED051 -v
Step 2.
Output returned:
Clear Eject 2 of 4 media was successful
Error VOL024: error in the list
Media [MED012]
Media [MED013]
Media [MED014]
Media [MED051]
no error
item not marked for ejection
no error
item not found
601356 Rev A
Command Reference
2-37
Command Reference
Step 1.
Errors with verbose option not specified. Requests
VolServ to remove MED012, MED013, MED014,
and MED051from the Eject list and to return status
on media only if processing for that media failed.
vscleareject MED012 MED013 MED014
MED051
Step 2.
Output returned:
Clear Eject 2 of 4 media was successful
Error VOL024: error in the list
Media [MED013]
Media [MED051]
media not marked for ejection
item not found
Notes
The vsclearejectrequest fails for media if the media is
already selected for eject by the operator.
Failure of the vsclearejectrequest for one or more media in
a list does not fail the request for all media in the list.
An operator also removes media from the Eject list by
performing an Eject Fail from the appropriate library’s console
display. The Eject Fail functionality is not available from the
command line.
The Clear Eject command triggers unsolicited status messages
from VolServ.
A pending Clear Eject 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).
See Also
•
vscheckout,
2-38
Command Reference
601356 Rev A
Command Reference
•
•
•
vsexport,
vsmount,
vsmove
601356 Rev A
Command Reference
2-39
Command Reference
Queries for enterprise connection information.
vsconnectqry
This command provides a list of all client internet addresses
that are currently associated with the given enterprise identifier.
vsconnectqry enterpriseid
Parameters
[ -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.
-I
Command options are first read from the
command line. VolServ then reads any
options contained in the stdinfile.
-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.
2-40
Command Reference
601356 Rev A
Command Reference
Parameter
-P priority
Description
The execution priority of the entered
command. Assignable priority values are
restricted to a range from 1 (highest) to 32
(lowest) inclusive.
Default value is
15.
-R retries
Number of retries the CLI software attempts if
a time-out is returned by the API software.
Default value is
3.
-T timeout
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.
Default value is
120 seconds.
-V prognum
RPC program number for VolServ.
Default value is
300016.
Return Codes
•
•
•
0 - The vsconnectqrycommand 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.
Examples
Step 1.
Successful enterprise query. Requests VolServ to
return a list of the client internet addresses
associated with enterprise identifier 3.
vsconnectqry 3
601356 Rev A
Command Reference
2-41
Command Reference
Step 2.
Output returned:
-----------------------------------------------
Connect Query Report
May 24 12:43:18 19931
-----------------------------------------------
Enterprise ID:
3
-----------------------------------------------
Client #: 1
Socket Family:
Socket Port:
10
1
Internet Address:
Program Number:
Version Number:
Procedure Number:
300
300016
2
1
²
•
Step 1.
Step 2.
Unsuccessful enterprise query. Requests VolServ to
return a list of the client Internet addresses
associated with enterprise identifier 13:
vsconnectqry 13
Output returned:
Connect query was unsuccessful
Error VOL008: item not found
Notes
The vsconnectqrycommand is run from either:
•
•
Command line.
Or, GUI.
2-42
Command Reference
601356 Rev A
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 vsconnectqrycommand does not trigger unsolicited
status messages from VolServ.
A pending vsconnectqryrequest 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).
See Also
None
601356 Rev A
Command Reference
2-43
Command Reference
Dismounts media from a drive.
•
vsdismount
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. A
successful return code is returned to the client after the
media movement is completed.
•
For manual libraries, a dismount notice is sent to the
appropriate library’s console display for action. An operator
dismounts the specified media and then notifies VolServ that
the media dismount is complete. VolServ returns a
successful return code to the client only after the operator
confirms the dismount is complete.
vsdismount mediaid
vsdismoun-d driveid
Parameters
[-l lockid]
[-u usagetime]
[-e errorcount]
[ -Ih ]
[ -H hostname ]
[ -P priority ]
[ -R retries ]
[ -T timeout ]
[ -V prognum ]
2-44
Command Reference
601356 Rev A
Command Reference
Parameters
Parameter
mediaid
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
-l lockid
Identifies the drive where the media is
mounted.
Specifies the lock identifier associated with
the drive if the drive is mounted with a lock
identifier.
-u usagetime
-e errorcount
-I
The amount of time (in seconds) the drive is in
use.
The number of errors encountered while
interacting with the drive.
Command options are first read from the
command line. VolServ then reads any
options contained in the stdinfile.
-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
-P priority
Host name of the VolServ server. The default
host name is the host name of the computer
where the CLI command is run.
The execution priority of the entered
command. Assignable priority values are
restricted to a range from 1 (highest) to 32
(lowest) inclusive.
Default value is
15.
601356 Rev A
Command Reference
2-45
Command Reference
Parameter
-R retries
Description
Number of retries the CLI software attempts if
a time-out is returned by the API software.
Default value is
3.
-T timeout
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.
Default value is
120 seconds.
-V prognum
RPC program number for VolServ.
Default value is
300016.
Return Codes
•
•
0 - The vsdismountcommand 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.
Examples
Step 1.
Step 2.
Successful dismount. Requests VolServ to dismount
MED032from drive 2.
vsdismount MED012 -d 2
Output returned:
Dismount of Media [MED032] from Drive
[2] was successful
2-46
Command Reference
601356 Rev A
Command Reference
Step 1.
Step 2.
Unsuccessful dismount request. Requests VolServ to
dismount MED016from drive 13.
vsdismount MED016 -d 13
Output returned:
Dismount of Media [MED016] from Drive
[13] was unsuccessful
Error VOL081: drive not mounted
Step 1.
Step 2.
Unsuccessful dismount request. Requests VolServ to
dismount MED016from drive 9.
vsdismount MED016 -d 9
Output returned:
Dismount of Media [MED016] from Drive
[9] was unsuccessful
Error VOL044: media not mounted
Notes
The vsdismountcommand triggers unsolicited status
messages from VolServ.
A pending vsdismountrequest 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).
See Also
•
vsmount
601356 Rev A
Command Reference
2-47
Command Reference
Queries for information on specified drives.
vsdriveqry
vsdriveqry driveid…
Parameters
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
-I
Indicates all drives known to the VolServ
system are to be queried.
Command options are first read from the
command line. VolServ then reads any
options contained in the stdinfile.
-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.
2-48
Command Reference
601356 Rev A
Command Reference
Parameter
-P priority
Description
The execution priority of the entered
command. Assignable priority values are
restricted to a range from 1 (highest) to 32
(lowest) inclusive.
Default value is
15.
-R retries
Number of retries the CLI software attempts if
a time-out is returned by the API software.
Default value is
3.
-T timeout
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.
Default value is
120 seconds.
-V prognum
RPC program number for VolServ.
Default value is
300016.
Return Codes
•
•
0 - The vsdriveqrycommand 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.
Examples
Step 1.
Successful drive query. Requests VolServ to return
information on every drive known to the VolServ
system.
vsdriveqry -a
601356 Rev A
Command Reference
2-49
Command Reference
Step 2.
Output returned:
-----------------------------------------------
Drive Query Report
Mar 10 11:00:32 19941
-----------------------------------------------
Drive ID:
1
-----------------------------------------------
Drive Type:
Magnetic
Associated Archive:
Current State:
Assignment:
stage1
Online
Free
Usage Count:
0
Current Usage Time:
Total Usage Time:
Error Count:
0
0
0
Mount State:
Unmounted
Mounted Media ID:
Media Type(s) Supported:D2M
•
•
²
Drive ID:
3
-----------------------------------------------
Drive Type:
Magnetic
Associated Archive:
Current State:
Assignment:
shelf1
Online
Free
Usage Count:
1
Current Usage Time:
Total Usage Time:
Error Count:
0
0
0
Mount State:
Unmounted
Mounted Media ID:
Media Type(s) Supported:D2M
2-50
Command Reference
601356 Rev A
Command Reference
-----------------------------------------------
Drive ID:
-----------------------------------------------
4
Drive Type:
Magnetic
Associated Archive:
Current State:
Assignment:
shelf1
Online
Free
Usage Count:
0
Current Usage Time:
Total Usage Time:
Error Count:
0
0
0
Mount State:
Unmounted
Mounted Media ID:
Media Type(s) Supported:D2M
Step 1.
Step 2.
Unsuccessful drive query. Requests VolServ to
return information on drive 35.(Drive 35 does not
exist.)
vsdriveqry 35
Output returned:
Drive query was unsuccessful.
Error VOL008: item not found.
Notes
The vsdriveqrycommand does not trigger unsolicited status
messages from VolServ.
A pending vsdriveqryrequest 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).
See Also
•
vsdrivevary
601356 Rev A
Command Reference
2-51
Command Reference
Changes the state of a drive.
vsdrivevary
A drive in the offline, unavailable, or diagnostic state is
excluded from VolServ’s drive selection algorithm.
Tip
A vsmountor vslockrequest 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.
vsdrivevary -s state
vsdrivevary driveid
Parameters
vsdrivevary -p drivepool
[ -Ihv ]
[ -H hostname ]
[ -P priority ]
[ -R retries ]
[ -T timeout ]
[ -V prognum]
Parameters
Parameter
driveid…
-p drivepool
Description
Specifies one through 64 individual drives
whose state is to be varied.
Specifies the name of a drive pool .
• Valid drive pool names may contain up to
16 alphanumeric characters, including
spaces.
• Leading and trailing spaces are not
permitted.
2-52
Command Reference
601356 Rev A
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 vscheckoutcommand.
NOTE: If -vis not specified, status is returned
on only those media that were not
successfully checked out.
-I
Command options are first read from the
command line. VolServ then reads any
options contained in the stdinfile.
-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
-P priority
Host name of the VolServ server. The default
host name is the host name of the computer
where the CLI command is run.
The execution priority of the entered
command. Assignable priority values are
restricted to a range from 1 (highest) to 32
(lowest) inclusive.
Default value is
15.
-R retries
Number of retries the CLI software attempts if
a time-out is returned by the API software.
Default value is
3.
601356 Rev A
Command Reference
2-53
Command Reference
Parameter
-T timeout
Description
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.
Default value is
120 seconds.
-V prognum
RPC program number for VolServ.
Default value is
300016.
Return Codes
•
•
0 - The vsdrivevarycommand 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.
Examples
Step 1.
Successful drive vary with verbose option specified.
Requests VolServ to vary all drives in the
drvpoolusr drive pool to the off-linestate
and to return status on every drive in
drvpoolusr.
vsdrivevary -p drvpoolusr -s off-line
-V
2-54
Command Reference
601356 Rev A
Command Reference
Step 2.
Output returned:
Vary 8 of 8 drives to state [off-line] was successful.
Drive [1]
Drive [4]
Drive [5]
Drive [7]
Drive [8]
Drive [11]
Drive [12]
Drive [14]
no error
no error
no error
no error
no error
no error
no error
no error
Step 1.
Successful drive vary with verbose option not
specified. Requests VolServ to vary drive 2to the
diagnosticstate and to return status on a drive
only if processing for that drive failed.
vsdrivevary 2 -s diagnostic
Step 2.
Step 1.
Output returned:
Vary 1 of 1 drives to state
[diagnostic] was successful.
Errors with verbose option specified. Requests
VolServ to vary drives 5, 15, 8, 18, and 11
to the on-linestate and to return status on every
specified drive.
vsdrivevary 5 15 8 18 11 -s online -v
601356 Rev A
Command Reference
2-55
Command Reference
Step 2.
Output returned:
Vary 3 of 5 drives to state [online] was successful
Drive [5]
Drive [15]
Drive [8]
Drive [18]
Drive [11]
no error
invalid drive specified
no error
invalid drive specified
no error
Step 1.
Errors with verbose option not specified. Requests
VolServ to vary drives 5, 15, 8, 18, and 11
to the off-linestate and to return status on a
drive only if processing for that drive failed.
vsdrivevary 5 15 8 18 11 -s offline
Step 2.
Output returned:
Vary 3 of 5 drives to state [offline] was successful
Error VOL024: error in the list
Drive [15]
Drive [18]
invalid drive specified
invalid drive specified
Step 1.
Unsuccessful Drive Vary request. Requests VolServ
to vary every drive associated with the
BadPoolNamedrive pool to the diagnostic
state.
vsdrivevary -p BadPoolName -s
diagnostic
Step 2.
Output returned:
Error VOL030: invalid drive pool
specified
2-56
Command Reference
601356 Rev A
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.
The unavailable state is assignable only by VolServ when a
higher level component in the library system is no longer
online. For example, varying a CLM offline causes the
associated drive to be viewed as unavailable.
The vsdrivevarycommand does not trigger unsolicited
status messages from VolServ.
A pending vsdrivevaryrequest 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).
See Also
•
vsdriveqry
601356 Rev A
Command Reference
2-57
Command Reference
Marks media and related media information for removal from
the VolServ system.
vsexport
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 vsexportcommand to remove
information about media that have been checked out of the
library and is physically out of the library.
Upon receipt of an vsexportrequest, VolServ marks the
specified media for eject and returns a successful return code to
the client. The <Eject> button is highlighted on the operator’s
consoleto indicate that media need to be ejected from the
library.
To physically remove the media marked for export from the
library, an operator must select the Eject functionality from the
appropriate library’s console display. The Eject functionality is
not available from the command line.
After media, specified on a vsexportcommand, is physically
removed from the library system, the media is no longer
managed by VolServ, and all information related to exported
media is deleted from VolServ.
vsexport mediaid…
Parameters
[-t comment]
[ -Ihv]
[ -H hostname ]
[ -P priority ]
[ -R retries ]
[ -T timeout ]
[ -V prognum ]
2-58
Command Reference
601356 Rev A
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.
-t comment
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. The length of the comment is restricted
by the CLI software. Currently, the maximum
allowed length is 80.
-v
Indicates that verbose output is needed.
Status is returned on every media specified in
the vscheckoutcommand.
NOTE: If -vis not specified, status is returned
on only those media that were not
successfully checked out.
-I
Command options are first read from the
command line. VolServ then reads any
options contained in the stdinfile.
-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.
601356 Rev A
Command Reference
2-59
Command Reference
Parameter
-P priority
Description
The execution priority of the entered
command. Assignable priority values are
restricted to a range from 1 (highest) to 32
(lowest) inclusive.
Default value is
15.
-R retries
Number of retries the CLI software attempts if
a time-out is returned by the API software.
Default value is
3.
-T timeout
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.
Default value is
120 seconds.
-V prognum
RPC program number for VolServ.
Default value is
300016.
Return Codes
•
•
0 - The vsexportcommand 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.
2-60
Command Reference
601356 Rev A
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:
Export 3 of 3 media was successful
Media [MED012]
no error
no error
no error
Media [MED014]
Media [MED016]
Step 1.
Successful export request with comment option
specified and verbose option not specified.
Requests to VolServ to place media MED001,
MED002, MED003, MED012, MED014, and
MED016on the Eject list with the comment, Media
to be shipped off-site, and to return status on media
only if processing for that media failed.
vsexport MED001 MED002 MED003 MED012
MED014 MED016 -t Media to be shipped
off-site
Step 2.
Step 1.
Output returned:
Export 6 of 6 media was successful
Errors with verbose and comment options specified
601356 Rev A
Command Reference
2-61
Command Reference
Requests to VolServ to place media MED007,
MED014, MED021, MED028, MED053, and
MED042on 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]
no error
Media [MED014]
invalid action or location state
for operation
no error
no error
item not found
no error
Media [MED021]
Media [MED028]
Media [MED053]
Media [MED042]
Step 1.
Errors with verbose option not specified and
comment option specified
Requests to VolServ to place media MED007,
MED014, MED021, MED028, MED053, and
MED042on the Eject list with the comment, Media
to be shipped off-site, and to return status on media
only if processing on that media failed.
vsexport MED007 MED014 MED021 MED028
MED053 MED042 -t Media to be shipped
off-site
2-62
Command Reference
601356 Rev A
Command Reference
Step 2.
Output returned:
Export 4 of 6 media was successful
Error VOL024: error in the list
Media [MED014]
invalid action or location state
for operation
Media [MED053]
item not found
Notes
The vsexportcommand cannot be cancelled. Media can be
unmarked for export via the Clear Eject request or if the
operator fails the eject.
Media that is marked for ejection from the library system
cannot be reallocated to satisfy a client request, except to satisfy
a query of the media. Any other request (except
vscleareject) received for that media fails.
An allocated media can be marked for export. Attempts to
physically eject an allocated media fail until the media is no
longer in-use.
The vsdrivevarycommand triggers unsolicited status
messages from VolServ to the client software.
See Also
•
vscleareject, vsimport
601356 Rev A
Command Reference
2-63
Command Reference
Logically adds media to the VolServ system.
vsimport
Upon receipt of a vsimportrequest, the specified media is
added to the VolServ system. If a non-unique media identifier is
specified, the import for that media fails.
The vsimportis 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. The Enter functionality is not available from the
command line.
vsimport mediaid…
Parameters
vsimport -a archivename
vsimport -c mediaclass
[ -f manufacturer ]
[ -b batch ]
[-Ihv]
[ -H hostname ]
[ -P priority ]
[ -R retries ]
[ -T timeout ]
[ -V prognum]
2-64
Command Reference
601356 Rev A
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.
• Valid library names may contain up to 16
alphanumeric characters, including spaces.
• Leading and trailing spaces are not
permitted.
-c mediaclass
Identifies the MediaClass name with which the
imported media are to be associated. Valid
MediaClass names may contain up to 16
alphanumeric characters, including spaces.
Leading and trailing spaces are not permitted.
-f manufacturer
Specifies the name of the media
manufacturer.
• If the -f (manufacturer) option is specified,
the -b (batch) option must also be specified.
• If the -f (manufacturer) option is not
specified, the -b (batch) option cannot be
specified.
601356 Rev A
Command Reference
2-65
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 vscheckoutcommand.
NOTE: If -vis not specified, status is returned
on only those media that were not
successfully checked out.
-I
Command options are first read from the
command line. VolServ then reads any
options contained in the stdinfile.
-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
-P priority
Host name of the VolServ server. The default
host name is the host name of the computer
where the CLI command is run.
The execution priority of the entered
command. Assignable priority values are
restricted to a range from 1 (highest) to 32
(lowest) inclusive.
Default value is
15.
-R retries
Number of retries the CLI software attempts if
a time-out is returned by the API software.
Default value is
3.
2-66
Command Reference
601356 Rev A
Command Reference
Parameter
-T timeout
Description
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.
Default value is
120 seconds.
-V prognum
RPC program number for VolServ.
Default value is
300016.
Return Codes
•
•
0 - The vsimportcommand 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.
Examples
Step 1.
Successful Import request with verbose option
specified
Requests VolServ to import media MED003,
MED018, MED021, MED030,and MED036into
the medclasssh1medMediaClass group in the
shelf1library and to return status on every
specified media.
vsimport MED003 MED018 MED021 MED030
MED036
-a shelf1 -c medclasssh1med -v
601356 Rev A
Command Reference
2-67
Command Reference
Step 2.
Output returned:
Import 5 of 5 media was successful
Media [MED003]
no error
no error
no error
no error
no error
Media [MED018]
Media [MED021]
Media [MED030]
Media [MED036]
Step 1.
Successful Import request with verbose option not
specified
Requests VolServ to import media MED003,
MED018, MED021, MED030, and MED036
into the medclasssh1medMediaClass group in
the shelf1library and to return status on media
only if processing for that media failed.
vsimport MED003 MED018 MED021 MED030
MED03
-a shelf1 -c medclasssh1med
Step 2.
Step 1.
Output returned:
Import 5 of 5 media was successful
Errors with verbose option specified.
Requests VolServ to import media MED003,
MED018, MED021, MED030, and MED036
into the medclasssh1medMediaClass group in
the shelf1library and to return status on every
2-68
Command Reference
601356 Rev A
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:
Import 3 of 5 media was successful
Error VOL024: error in the list
Media [MED003]
no error
Media [MED018]
Media [MED021]
Media [MED030]
item already exists
item already exists
no error
Media [MED036]
no error
Step 1.
Errors with verbose option not specified
Requests VolServ to import media MED003,
MED018, MED021, MED030, and MED036
into the medclasssh1medMediaClass group in
the shelf1library and to return status on media
only if processing for that media failed.
“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 -f “MediaMaker ABC”
-b 1001
601356 Rev A
Command Reference
2-69
Command Reference
Step 2.
Output returned:
Import 3 of 5 media was successful
Error VOL024: error in the list
Media [MED018]
item already exists
Media [MED021]item already exists
Step 1.
Unsuccessful Import request.
Requests VolServ to import media MED003,
MED018, MED021, MED030, and MED036
into the medclassmedMediaClass group in the
BadArchiveNamelibrary and to return status on
media only if processing for that media failed.
vsimport MED003 MED018 MED021 MED030
MED036 -a BadArchiveName
-c medclassmed
Step 2.
Output returned:
Import of media was unsuccessful
Error VOL013: invalid archive
Notes
Import is a logical operation. Media must be physically entered
into a library by an operator before they are available for
general use. A successful Import request results in the media
identifier being placed on the receiving library’s Enter list.
Media identifier values must be unique throughout a VolServ
system. Non-unique media identifiers are rejected.
•
If the Enter fails for the media to be imported, the media is
placed Intransit.
2-70
Command Reference
601356 Rev A
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.
The media type for the media is determined by the media type
of the specified MediaClass group.
After the MediaClass capacity is reached, no more media can be
imported into the MediaClass group.
The vsimportcommand triggers unsolicited status messages
from VolServ to the client software.
A pending Import 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).
See Also
•
vsexport
601356 Rev A
Command Reference
2-71
Command Reference
Queries for media that are in the intransit state. The query
returns a list of media identifiers.
vsintransitqry
Note
The vsintransitqrycommand supports no
command-specific options.
Media is considered to be intransit under the following
conditions:
•
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.
vsintransitqry
Parameters
[ -Ih ]
[ -H hostname ]
[ -P priority ]
[ -R retries ]
[ -T timeout ]
[ -V prognum ]
Parameters
Parameter
Description
-I
Command options are first read from the
command line. VolServ then reads any
options contained in the stdinfile.
2-72
Command Reference
601356 Rev A
Command Reference
Parameter
Description
-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
-P priority
Host name of the VolServ server. The default
host name is the host name of the computer
where the CLI command is run.
The execution priority of the entered
command. Assignable priority values are
restricted to a range from 1 (highest) to 32
(lowest) inclusive.
Default value is
15.
-R retries
Number of retries the CLI software attempts if
a time-out is returned by the API software.
Default value is
3.
-T timeout
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.
Default value is
120 seconds.
-V prognum
RPC program number for VolServ.
Default value is
300016.
Return Codes
•
•
0 - The vsintransitqrycommand is successfully
processed.
-1 - An error is detected by either the CLI software or the
API software.
601356 Rev A
Command Reference
2-73
Command Reference
•
>0 - An error is detected by VolServ. The returned exit code
corresponds to the error code given by VolServ.
Examples
Step 1.
Successful intransit query.
Requests VolServ to return a list of all media in the
intransitstate.
vsintransitqry
Step 2.
Output returned:
-----------------------------------------------
Intransit Query Report
May 14 09:45:57 19931
-----------------------------------------------
Media ID(s):MED007
MED025MED040
Step 1.
Step 2.
Unsuccessful intransit query
Requests VolServ to return a list of all media in the
intransitstate.
vsintransitqry
Output returned:
Intransit query was unsuccessful
Error VOL008: item not found
Notes
Only media in the Intransit state are queried and reported to the
client.
The vsintransitqrycommand does not trigger unsolicited
status messages from VolServ.
2-74
Command Reference
601356 Rev A
Command Reference
A pending vsintransitqryrequest 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).
See Also
•
vsmedqry
601356 Rev A
Command Reference
2-75
Command Reference
Obtains exclusive use of one or more drives.
vslock
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.
A vslockcommand:
•
That specifies a drive pool or a list of drives should also
indicate the number of drives from the pool and list to be
locked. VolServ selects the drives to lock from within the
pool and list according to drive availability.
•
•
cannot specify a drive pool or a list of drives that spans
libraries, they must be associated with a single library.
Reserves one drive for exclusive use if a quantity is not
specified on the command.
VolServ considers only online drives as candidates to be locked.
If a sufficient number of online drives in the same library are
unavailable to satisfy a vslock command, the command fails.
If there is a sufficient number of online drives in the same
library to satisfy a vslockrequest, but the number of available
online drives is not sufficient, the request waits until sufficient
drives become available.
Note
Partial locks are not set.
2-76
Command Reference
601356 Rev A
Command Reference
vslock driveid…
Parameters
vslock -p drivepool
[ -x driveid ]
[-q quantity]
[ -Ih ]
[ -H hostname ]
[ -P priority ]
[ -R retries ]
[ -T timeout ]
[ -V prognum ]
Parameters
Parameter
Description
driveid…
Specifies a list of one through 64 candidate
drives to reserve (lock) for exclusive use.
-p drivepool
Specifies the name of a drive pool.
• Valid drive pool names may contain up to
16 alphanumeric characters, including
spaces.
• Leading and trailing spaces are not
permitted.
Specifies a list of one through 64 drives
contained in the specified drive pool that are
NOT reserved for exclusive use.
-x driveid…
-q quantity
Specifies the number of drives to be locked.
• If the [-q quantity] option is not specified,
the number of drives to be locked defaults
to 1.
-I
Command options are first read from the
command line. VolServ then reads any
options contained in the stdinfile.
601356 Rev A
Command Reference
2-77
Command Reference
Parameter
Description
-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
-P priority
Host name of the VolServ server. The default
host name is the host name of the computer
where the CLI command is run.
The execution priority of the entered
command. Assignable priority values are
restricted to a range from 1 (highest) to 32
(lowest) inclusive.
Default value is
15.
-R retries
Number of retries the CLI software attempts if
a time-out is returned by the API software.
Default value is
3.
-T timeout
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.
Default value is
120 seconds.
-V prognum
RPC program number for VolServ.
Default value is
300016.
Return Codes
•
•
0 - The vslockcommand 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.
2-78
Command Reference
601356 Rev A
Command Reference
Examples
Step 1.
Step 2.
Step 3.
Successful Lock request that specifies a list of one or
more drives (vslock4 8 12)
Requests VolServ to lock (reserve for exclusive use)
one of the drives 4, 8, and12.
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
Requests VolServ to lock (reserve for exclusive use)
2 drives from drive pool drvpoolmed.
vslock -p drvpoolmed -q 2
Step 2.
Output returned:
Lock [2] drives locked with lock id[1719790788]
1
2
Drive[40]
Drive[41]
Step 1.
Unsuccessful Lock request, too many drives
requested to be reserved.
Requests VolServ to lock (reserve for exclusive use)
5 drives from drive pool drvpooltwr
(drvpooltwrcontains only 2 drives.)
vslock -p drvpooltwr -q 5
601356 Rev A
Command Reference
2-79
Command Reference
Step 2.
Step 1.
Output returned:
Lock was unsuccessful
Error VOL122: not enough available
drives in pool
Unsuccessful Lock request.
Requests VolServ to lock (reserve for exclusive use)
1 drive from drive pool BadDrivePool.
vslock -p BadDrivePool -q 1
Output returned:
Step 2.
Lock was unsuccessful
Error VOL030: invalid drive pool
specified
Notes
Note
It is important to keep any vsmountor vsdismount
request that contains the proper lock identifier to continue to
have access to a locked drive.
If a mount request does not specify a lock identifier for a locked
drive, whether the drive is available for use or not, the vsmount
request waits until the drive is both unlocked and available.
2-80
Command Reference
601356 Rev A
Command Reference
If a vsmountrequest 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 vslockcommand that is queued and awaiting resources is
cancelled via 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).
An vsunlockcommand is run when the client no longer needs
drives for exclusive use.
The vslockcommand does not trigger unsolicited status
messages from VolServ.
Intermediate status may be returned if the vslockcommand is
queued.
See Also
•
•
•
vsdismount,
vsmount,
vsunlock
601356 Rev A
Command Reference
2-81
Command Reference
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.
vsmedclass
qry
vsmedclassqry mediaclass
Parameters
vsmedclassqry -a
[ -m | -v ]
[ -Ih ]
[ -H hostname ]
[ -P priority ]
[ -R retries ]
[ -T timeout ]
[ -V prognum ]
Parameters
Parameter
mediaclass
Description
Specifies a single MediaClass name to
request information on. Valid MediaClass
names may contain up to 16 alphanumeric
characters, including spaces. Leading and
trailing spaces are not permitted.
-a
Requests information on all MediaClass
groups known to the VolServ system.
-m
Requests a list of media identifiers for all
media associated with each reported
MediaClass group.
-v
Requests detailed information for all media
associated with each reported MediaClass
group.
2-82
Command Reference
601356 Rev A
Command Reference
Parameter
Description
-I
Command options are first read from the
command line. VolServ then reads any
options contained in the stdinfile.
-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
-P priority
Host name of the VolServ server. The default
host name is the host name of the computer
where the CLI command is run.
The execution priority of the entered
command. Assignable priority values are
restricted to a range from 1 (highest) to 32
(lowest) inclusive.
Default value is
15.
-R retries
Number of retries the CLI software attempts if
a time-out is returned by the API software.
Default value is
3.
-T timeout
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.
Default value is
120 seconds.
-V prognum
RPC program number for VolServ.
Default value is
300016.
Return Codes
•
0 - The vsmedclassqrycommand is successfully
processed.
601356 Rev A
Command Reference
2-83
Command Reference
•
•
-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.
Examples
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.
Output returned:
-----------------------------------------------
Media Class Query Report
May 14 10:09:11 19931
-----------------------------------------------
Media Class: medclassstgusr
-----------------------------------------------
Media Type:
Capacity:
USRTYPE
20
Current Fill Level:
High Mark %:
Mountable by Class:
Notify Comment:
RPC Option:
•
2
80%
Yes
Media exceed high mark
No Callback
•²
2-84
Command Reference
601356 Rev A
Command Reference
•²
Media Class: medclasssh2med
-----------------------------------------------
Media Type:
Capacity:
D2M
20
Current Fill Level:
High Mark %:
Mountable by Class:
Notify Comment:
RPC Option:
Enterprise ID:
•
3
80%
Yes
Media exceed high mark
Enterprise Callback
3
•²
•²
Media Class: medclasssh2sml
-----------------------------------------------
Media Type:
D2S
Capacity:
20
Current Fill Level:
High Mark %:
2
80%
Mountable by Class:
Notify Comment:
RPC Option:
Yes
Media exceed high mark
Standard Callback
HostName:
copper
Program Number:
Version Number:
Procedure Number:
Protocol:
1
1
1
TCP
Step 1.
Successful Media Class Query request with -m
option specified.
Requests VolServ to return detailed media
information for every media in the
medclasssh1usrMediaClass group.
vsmedclassqry medclasssh1usr -m
601356 Rev A
Command Reference
2-85
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:
High Mark %:
3
80%
Mountable by Class:
Notify Comment:
RPC Option:
Yes
Media exceed high mark
No Callback
Media ID(s):
MED007
MED025
MED040
Step 1.
Successful Media Class Query request with -v
option specified.
Requests VolServ to return detailed media
information for every media in the medclasssml
MediaClass group.
vsmedclassqry medclasssml -v
Step 2.
Output returned:
-----------------------------------------------
Media Class Query Report
May 14 09:45:57 19931
-----------------------------------------------
2-86
Command Reference
601356 Rev A
Command Reference
Media Class: medclasssml
-----------------------------------------------
Media Type:
D2S
Capacity:
20
Current Fill Level:
High Mark %:
8
80%
Mountable by Class:
Notify Comment:
RPC Option:
Yes
Media exceed high mark
No Callback
MediaID: MED005
Media Type:
D2S
Media Class:
Assignment:
medclasssml
Free
Location State:
Current Archive:
Pending Archive:
Action State:
Import Date:
Last Access:
Mount Count:
Move Count:
Archive
stage1
None
May 14 09:30:09 1993
May 14 09:45:43 1993
2
Manufacturer:
Batch:
MediaMaker
1001
²
²
601356 Rev A
Command Reference
2-87
Command Reference
MediaID: MED017
Media Type:
D2S
Media Class:
Assignment:
medclasssml
Allocated
Archive
shelf2
Location State:
Current Archive:
Pending Archive:
Action State:
Import Date:
Last Access:
Mount Count:
Move Count:
None
May 14 09:28:41 1993
May 14 09:40:21 1993
1
1
Manufacturer:
Batch:
²
²
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:
D2S
medclasssml
Free
Archive
shelf2
shelf1
Move
May 14 09:30:09 1993
1
2
•
•
•
2-88
Command Reference
601356 Rev A
Command Reference
MediaID: MED051
Media Type:
D2S
Media Class:
Assignment:
medclasssml
Free
Location State:
Current Archive:
Pending Archive:
Action State:
Import Date:
Last Access:
Mount Count:
Move Count:
Intransit
shelf1
Import
May 14 09:30:09 1993
0
0
Manufacturer:
Batch:
Step 1.
Step 2.
Unsuccessful Media Class Query.
Requests VolServ to return information on the
UnknownClass MediaClass group.
vsmedclassqry UnknownClass
Output returned:
Query of Media Class [UnknownClass]
was unsuccessful
Error VOL008: item not found
Notes
The vsmedclassqrycommand does not trigger unsolicited
status messages from VolServ.
601356 Rev A
Command Reference
2-89
Command Reference
A pending vsmedclassqryis 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).
See Also
•
vsmedqry
2-90
Command Reference
601356 Rev A
Command Reference
Queries for the attributes of one or more specified media. The
values of the attributes of the media are returned to the client.
vsmedqry
vsmedqry mediaid…
Parameters
vsmedqry -a
[ -Ih ]
[ -H hostname ]
[ -P priority ]
[ -R retries ]
[ -T timeout ]
[ -V prognum ]
Parameters
Parameter
mediaid…
Description
Specifies a list of one through 64 media to be
queried.
-a
-I
Specifies the -a option to indicate information
is to be reported on all media known to the
VolServ system.
Command options are first read from the
command line. VolServ then reads any
options contained in the stdinfile.
-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.
601356 Rev A
Command Reference
2-91
Command Reference
Parameter
-P priority
Description
The execution priority of the entered
command. Assignable priority values are
restricted to a range from 1 (highest) to 32
(lowest) inclusive.
Default value is
15.
-R retries
Number of retries the CLI software attempts if
a time-out is returned by the API software.
Default value is
3.
-T timeout
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.
Default value is
120 seconds.
-V prognum
RPC program number for VolServ.
Default value is
300016.
Return Codes
•
•
0 - The vsmedqrycommand 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.
Examples
Step 1.
Successful Media Query request.
Requests VolServ to return information on every
media known to the VolServ system.
vsmedqry -a
2-92
Command Reference
601356 Rev A
Command Reference
Step 2.
Output returned:
-----------------------------------------------
Media Query Report
May 14 10:34:30 19931
-----------------------------------------------
Media ID:
MED001
-----------------------------------------------
Media Type:
Media Class:
Assignment:
USRTYPE
medclassstgusr
Free
Location State:
Current Archive:
Pending Archive:
Action State:
Import Date:
Last Access:
Mount Count:
Move Count:
Archive
stage1
None
May 13 12:06:15 1993
May 13 13:12:09 1993
1
2
Manufacturer:
Batch:
²
²
601356 Rev A
Command Reference
2-93
Command Reference
Media ID:
MED015
-----------------------------------------------
Media Type:
D2M
Media Class:
Assignment:
medclassmed
Free
Location State:
Current Archive:
Pending Archive:
Action State:
Import Date:
Last Access:
Mount Count:
Move Count:
Intransit
shelf1
Move
May 13 16:25:39 1993
May 13 16:40:53 1993
0
0
Manufacturer:
Batch:
MediaMaker ABC
1001
²
²
Media ID:
MED027
-----------------------------------------------
Media Type:
Media Class:
Assignment:
Location State:
Current Archive:
Pending Archive:
Action State:
Import Date:
Last Access:
Mount Count:
Move Count:
Manufacturer:
Batch:
D2M
medclassmed
Free
Archive
shelf2
shelf1
Move
May 12 14:36:10 1993
May 13 16:13:53 1993
0
0
•
•
•
2-94
Command Reference
601356 Rev A
Command Reference
Media ID:
MED039
-----------------------------------------------
Media Type:
D2M
Media Class:
Assignment:
medclassmed
Allocated
Location State:
Current Archive:
Pending Archive:
Action State:
Import Date:
Last Access:
Mount Count:
Move Count:
Archive
shelf1
shelf2
Move
May 12 14:36:10 1993
May 13 14:36:10 1993
1
1
Manufacturer:
Batch:
Step 1.
Media Query request with errors.
Requests VolServ to return information on media
MED027, BadMedia, and MED039.
vsmedqry MED027 BadMedia MED039
Step 2.
Output returned:
-----------------------------------------------
Media Query Report
May 25 16:06:09 19931
-----------------------------------------------
601356 Rev A
Command Reference
2-95
Command Reference
Media ID:
MED027
-----------------------------------------------
Media Type:
D2M
Media Class:
Assignment:
medclassmed
Free
Location State:
Current Archive:
Pending Archive:
Action State:
Import Date:
Last Access:
Mount Count:
Move Count:
Archive
shelf2
shelf1
Move
May 13 16:36:39 1993
May 24 12:23:25 1993
0
0
Manufacturer:
Batch:
Media ID:
BadMedia
-----------------------------------------------
Error:
item not found
Media ID:
MED039
-----------------------------------------------
Media Type:
D2M
Media Class:
Assignment:
medclassmed
Allocated
Location State:
Current Archive:
Pending Archive:
Action State:
Import Date:
Last Access:
Mount Count:
Move Count:
Archive
shelf1
shelf2
Move
May 13 16:36:39 1993
May 24 12:23:25 1993
1
1
Manufacturer:
Batch:
Notes
A vsmedqrycan query any media in the VolServ system. The
media specified in a single Media Query request are not
required to be located in the same library.
2-96
Command Reference
601356 Rev A
Command Reference
A pending vsmedqryis 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 vsmedqrycommand does not trigger unsolicited status
messages from VolServ.
See Also
•
vsmedclassqry
601356 Rev A
Command Reference
2-97
Command Reference
Queries for the attributes of one or more media types. The
values of the attributes of the media types are returned to the
client.
vsmedtype
qry
vsmedtypeqry mediatype…
Parameters
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.
Valid media type names may 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.
-a
-I
Indicates that information is to be returned on
all media types known to the VolServ system.
Command options are first read from the
command line. VolServ then reads any
options contained in the stdinfile.
2-98
Command Reference
601356 Rev A
Command Reference
Parameter
Description
-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
-P priority
Host name of the VolServ server.The default
host name is the host name of the computer
where the CLI command is run.
The execution priority of the entered
command. Assignable priority values are
restricted to a range from 1 (highest) to 32
(lowest) inclusive.
Default value is
15.
-R retries
Number of retries the CLI software attempts if
a time-out is returned by the API software.
Default value is
3.
-T timeout
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.
Default value is
120 seconds.
-V prognum
RPC program number for VolServ.
Default value is
300016.
Return Codes
•
•
•
0 - The vsmedtypeqrycommand 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.
601356 Rev A
Command Reference
2-99
Command Reference
Examples
Step 1.
Step 2.
Successful Media Type Query request.
Requests VolServ to return information on every
media type known to the VolServ system.
vsmedtypeqry -a
Output returned:
-----------------------------------------------
Media Type Query Report
May 24 12:43:18 19931
-----------------------------------------------
MediaType:
D2S
-----------------------------------------------
Capacity:
25000.00 megabytes
Number of Sides:
1
•
•
•
MediaType:
3480
-----------------------------------------------
Capacity:
200.00 megabytes
Number of Sides:
1
Step 1.
Media Type Query request with errors.
vsmedtypeqry D2S USRTYPE
2-100
Command Reference
601356 Rev A
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 vsmedtypeqrycommand does not trigger unsolicited
status messages from VolServ.
A pending vsmedtypeqryis 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).
See Also
•
•
vsmedclassqry,
vsmedqry
601356 Rev A
Command Reference
2-101
Command Reference
Mounts media onto a drive.
vsmount
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 vsmountcommand’s lock identifier parameter.is required
if the drive to be used in satisfying the vsmountrequest has
been previously locked with a vslockrequest. If a vsmount
request is run for a locked drive and does not specify a lock
identifier, VolServ waits until the requested drive is unlocked.
The client can also specify how to handle a vsmountrequest
that requires an inter-library movement of the media. This
option indicates whether an inter-library media movement
should or should not be attempted and whether to consider if the
source and destination libraries are operator-attended or not.
If more than one media and or a drive pool is specified on the
vsmountcommand, VolServ applies a selection algorithm to
select media and drive pair from the list of media and available
drives.
2-102
Command Reference
601356 Rev A
Command Reference
For manual libraries, a vsmountnotice 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 vsmountrequest 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.
When a vsmountrequest is queued for later processing,
VolServ returns intermediate status to the client that specifies
the reason the Mount request was queued.
vsmount mediaid…
vsmount -c mediaclass
vsmount -d driveid
vsmount -p drivepool
Parameters
[ -f flipmedia ]
[ -i | -u ]
[ -l lockid]
[ -Ih ]
[ -H hostname ]
[ -n newmediaclass ]
[ -P priority ]
[ -R retries ]
[ -T timeout ]
[ -V prognum]
[ -x driveid…]
601356 Rev A
Command Reference
2-103
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.
-f flipmedia
-i
Indicates that a mount requiring an
inter-library move fails if either the source and
destination library is marked as unattended.
-u
Indicates that a mount requiring an
inter-library move is to be performed,
regardless of whether either the losing or
gaining library is attended or unattended.
-l lockid
Specifies the associated lock identifier if a
locked drive) is specified to satisfy the Mount
request.
-I
Command options are first read from the
command line. VolServ then reads any
options contained in the stdinfile.
-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.
2-104
Command Reference
601356 Rev A
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.
• Valid drive pool names may contain up to
16 alphanumeric characters, including
spaces.
• Leading and trailing spaces are not
permitted.
-P priority
The execution priority of the entered
command. Assignable priority values are
restricted to a range from 1 (highest) to 32
(lowest) inclusive.
Default value is
15.
-R retries
Number of retries the CLI software attempts if
a time-out is returned by the API software.
Default value is
3.
-T timeout
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.
Default value is
120 seconds.
-V prognum
RPC program number for VolServ.
Default value is
300016.
601356 Rev A
Command Reference
2-105
Command Reference
Parameter
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.
-x driveid…
Return Codes
•
•
0 - The vsmountcommand 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.
Examples
Step 1.
Successful Mount request that specifies a list of one
or more media and a specific drive.
Requests VolServ to mount media MED026on drive
9.
vsmount MED026 -d 9
Step 2.
Step 1.
Output returned:
Mount of Media [MED026] onto Drive
[9] was successful
Successful Mount request that specifies a
MediaClass group and a specific drive.
2-106
Command Reference
601356 Rev A
Command Reference
Requests VolServ to mount media from MediaClass
medclassmedonto drive 10and to reclassify the
selected media to MediaClass group
medclasssh1med.
vsmount -c medclassmed -d 10 -n
medclasssh1med
Step 2.
Step 1.
Output returned:
Mount of Media [MED027] onto Drive
[10] was successful
Successful Mount request that specifies a specific
media and a drive pool with an exclusion drive list.
Requests VolServ to mount media MED022 onto any
drive from drive pool drvpoolusr, excluding drives 4
and 14.
vsmount MED022 -p drvpoolusr -x 4 14
Step 2.
Step 1.
Output returned:
Mount of Media [MED022] onto Drive
[12] was successful
Successful Mount request that specifies a
MediaClass name and a drive pool.
Requests VolServ to mount media from the
medclasssml MediaClass group onto a drive
from the drvpooltwrdrive pool.
vsmount -c medclasssml -p drvpooltwr
601356 Rev A
Command Reference
2-107
Command Reference
Step 2.
Step 1.
Output returned:
Mount of Media [MED041] onto Drive
[7] was successful
Successful Mount request when all specified drives
are in use.
Requests VolServ to mount media MED034onto
drive 12.(MED022is currently mounted on drive
12.)
vsmount MED034 -d 12
Output returned:
Step 2.
Step 1.
Mount waiting due to busy drive
Mount of Media [MED034] onto Drive
[12] was successful
Successful Mount request when specified media is
in use.
Requests VolServ to mount media MED034on any
drive in drive pool drvpoolmedexcept drive 12.
vsmount MED034 -p drvpoolmed -x 12
Output returned:
Step 2.
Mount waiting due to busy media
Mount of Media [MED034] on Drive [14]
was successful
2-108
Command Reference
601356 Rev A
Command Reference
Step 1.
Successful Mount request reclassifying the selected
media.
Requests VolServ to mount any media from
MediaClass group medclassstgmedonto any
drive in drive pool drvpoolmed,and to change
the MediaClass association of the selected media
from medclassstgmedto medclassmed.
vsmount -c medclassstgmed -p
drvpoolmed -n medclassmed
Step 2.
Output returned:
Mount of Media [MED048] onto Drive
[3] was successful
Note
Before running the vsmountrequest, MED048
was associated with medclassstgmed. After
running the vsmountrequest, MED048is
associated with medclassmed. The vsmedqry
command can be used to verify the MediaClass
association of a specific media.
Step 1.
Unsuccessful Mount request requiring an
inter-library move.
Requests VolServ to mount media MED023 located
in the stage1library onto drive 11associated with
the tower1library.
vsmount MED023 -d 11
601356 Rev A
Command Reference
2-109
Command Reference
Step 2.
Step 1.
Output returned:
Media could not be mounted onto drive
Error VOL110: mount crosses archives
Unsuccessful Mount request with unknown media
specified.
Requests VolServ to mount media BadMediaonto
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.
A drive that is specified in a vsmountrequest may not be the
ideal drive where to mount the specified media. It may take
considerably longer to mount the media onto a specified drive
than if a drive pool is specified.
The -i and -u options have no affect on a vsmountrequest that
does not require an inter-library media movement.
If a specified drive was previously locked, the lock identifier
assigned to that drive must be supplied before that drive is
considered in the selection process.
2-110
Command Reference
601356 Rev A
Command Reference
If a specified or selected drive was previously locked and the
vsmountrequest 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.
If the vsmountrequest specifies a MediaClass group and the -n
newmediaclass option is specified, the reclassify to a different
MediaClass group occurs only after VolServ selects the media
to satisfy the vsmountrequest. Only the selected media is
reclassified. The remaining media in the MediaClass group are
not reclassified.
•
If the -n newmediaclass option is specified, the receiving
MediaClass group is checked for compatible media type, as
well as for adequate room for another media (i.e., fill level
less than capacity).
•
If either of these conditions is not satisfied, the vsmount
request fails.
A pending vsmountrequest (waiting for a drive or media) is
cancelled with the VolServ Cancel request. 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 vsmountrequest fails if no specified drive is online.
If media or drive is specified and either the media or drive (or
both) are presently in use, the vsmountrequest waits for
resources and a message is returned to the client that indicates
the reason for the delay.
When specifying a drive pool that contains drives that support
different types of media, only those drives that support the
media type of the media specified in the vsmountrequest are
considered for selection.
601356 Rev A
Command Reference
2-111
Command Reference
If a list of media specified in a vsmountrequest 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.
When a vsmountrequest with groups of media or drives is
submitted, VolServ attempts to select a drive or media pair
where the drive and media are associated with the same library.
If multiple drive or media pair are candidates, VolServ selects a
drive or media pair from the library with an available drive.
If no drive or media pair associated with the same library exists,
VolServ then selects a drive or media pair where the drive and
media are associated with a different library. If multiple drive or
media pair are candidates, VolServ selects a drive or media pair
from the library with the largest number of drives. If all libraries
contain the same number of drives, VolServ then selects a drive
or media pair from the library with the largest number of media.
When specifying a mount by MediaClass group, and the
specified MediaClass group is associated with more than one
library, no inter-library media or drive pairing is permitted. The
media selected from the MediaClass group must be in the same
library as the selected drive; otherwise the Mount request fails.
When media is ejected (as a result of Export, or Checkout, no
check is made to determine if a queued Mount request exists for
the ejected media. As a result, the Mount request remains
queued until a drive is freed. At that time, the Mount request
fails because the media is not available. In other words, the
request queue is not checked for impact on pending requests
each time a resource changes its availability and after media or
drive pair is identified. VolServ does not attempt re-pairing
based on changed availability of resources.
2-112
Command Reference
601356 Rev A
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 vsmountrequest 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. If no space is available,
the mount fails.
See Also
•
•
vsdismount,
vsreclassify
601356 Rev A
Command Reference
2-113
Command Reference
Moves media from one library to another.
vsmove
A client uses the vsmovecommand 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.
Upon receipt of a vsmoverequest, the VolServ software verifies
the specified media exist, the target library supports the media
type of the specified media, and there exists an appropriate
library MediaClass association with the target library. The
current library of each specified media is commanded to eject
the media. An Eject request, specifying the target library, is
displayed on the library console of each losing library. The
operator must select and manually eject or remove the media on
the list. After media is selected for ejection, the target library
displays a corresponding Enter request for that media. The
operator must then manually enter the media specified on the
list into the target library.
When the media is ejected from the original library and entered
into the target library, the VolServ system generates unsolicited
status messages if any of the moved media are associated with
MediaClass groups that are configured to generate unsolicited
communication from VolServ.
The vsmovecommand is run for “homeless” media. A
homeless media is an Intransit media that has no pending
movement activity.
2-114
Command Reference
601356 Rev A
Command Reference
vsmove mediaid
Parameters
vsmove -a archivename
[-iIhwv]
[ -H hostname ]
[ -P priority ]
[ -R retries ]
[ -T timeout ]
[ -V prognum ]
Parameters
Parameter
Description
Specifies a list of one through 64 media to be
moved.
mediaid…
• A valid media identifier may contain up to
16 alphanumeric characters, including
spaces.
• 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.
• Leading and trailing spaces are not
permitted.
-i
Indicates this command is to be processed
only if both the source and destination
libraries are operator-attended.
601356 Rev A
Command Reference
2-115
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.
Status is returned on every media specified in
the vscheckoutcommand.
NOTE: If -vis not specified, status is returned
on only those media that were not
successfully checked out.
-I
Command options are first read from the
command line. VolServ then reads any
options contained in the stdinfile.
-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
-P priority
Host name of the VolServ server.
The default host name is the host name of the
computer where the CLI command is run.
The execution priority of the entered
command. Assignable priority values are
restricted to a range from 1 (highest) to 32
(lowest) inclusive.
Default value is
15.
2-116
Command Reference
601356 Rev A
Command Reference
Parameter
-R retries
Description
Number of retries the CLI software attempts if
a time-out is returned by the API software.
Default value is
3.
-T timeout
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.
Default value is
120 seconds.
-V prognum
RPC program number for VolServ.
Default value is
300016.
Return Codes
•
•
0 - The vsmovecommand 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.
Examples
Step 1.
Successful Move request, wait until move completes
before returning status to client, verbose option
specified.
Requests VolServ to move media MED016,
MED023, MED044,and MED048 to library
stage1; to wait until the move completes before
returning status to the client; and to return status on
every specified media.
vsmove MED016 MED023 MED044 MED048 -a
stage1 -wv
601356 Rev A
Command Reference
2-117
Command Reference
Step 2.
Output returned:
Move 4 of 4 media was successful
Media [MED016]
no error
no error
no error
no error
Media [MED028]
Media [MED043]
Media [MED048]
Step 1.
Step 2.
Successful Move request, verbose option not
specified.
Requests VolServ to move media MED013,
MED016, MED028,and MED028to library
shelf1.Since the -i option is NOT specified, the
move is to complete whether the losing and gaining
libraries are attended or unattended.
vsmove MED013 MED016 MED028 MED031 -a
shelf1
Step 3.
Output returned:
Move 4 of 4 media was successful.
Step 1.
Step 2.
Errors with verbose option specified (target library is
unattended).
Requests VolServ to move media MED013,
MED016, MED022,and MED034to the shelf1
library only if both the source libraries and the
destination library are attended and to return status
on every specified media.
vsmove MED013 MED016 MED022 MED034 -a
shelf1 -iv
2-118
Command Reference
601356 Rev A
Command Reference
Step 3.
Output returned:
Move 0 of 4 media was successful
Error VOL024: error in the list
Media [MED013] target archive mode is unattended
Media [MED016] target archive mode is unattended
Media [MED022] target archive mode is unattended
Media [MED034] target archive mode is unattended
Step 1.
Errors with verbose option not specified.
Requests VolServ to move media MED003,
MED004, MED013, MED028, MED033,and
MED043to the shelf2library.
vsmove MED003 MED004 MED013 MED028
MED033 MED043
-a shelf2
Step 2.
Output returned:
Move 3 of 6 media was successful
Error VOL024: error in the list
Media [MED003]
item not found
Media [MED004]
media already exists in an
archive
Media [MED033]
archive not associated with
class
media
Step 1.
Unsuccessful Move request.
Requests VolServ to move media MEDabcand
MEDxyz to the BadArchivelibrary.
vsmove MEDabc MEDxyz -a BadArchive
601356 Rev A
Command Reference
2-119
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. Actual
completion of the move can only be traced via callback
processing, media querying, or operator monitoring.
The Move command does trigger unsolicited status messages
from VolServ.
•
If the -w option is specified on a Move request, the client
can increase the timeout value or the retries value so the CLI
vsmove command does not time-out while awaiting
completion of the Move request.
A pending Mount 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).
See Also
•
vscleareject
2-120
Command Reference
601356 Rev A
Command Reference
Pings the VolServ system.
vsping
The vspingcommand 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 vspingcommand before
sending other commands, but vspingis available for clients to
verify that VolServ software is running.
•
If no options are specified, vspingtries to ping the VolServ
system on the host machine at VolServ’s default program
number.
Note
The vspingcommand supports no command-specific
options.
vsping
Parameters
[ -Ih ]
[ -H hostname ]
[ -V prognum ]
Parameters
Parameter
Description
-I
Command options are first read from the
command line. VolServ then reads any
options contained in the stdinfile.
601356 Rev A
Command Reference
2-121
Command Reference
Parameter
Description
-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
-V prognum
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.
Default value is
300016.
Return Codes
•
•
0 - The vspingcommand 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.
Examples
Step 1.
Step 2.
Successful request, VolServ is available.
Requests VolServ to acknowledge receipt of the Ping
request.
vsping
Output returned:
VolServ is available.
2-122
Command Reference
601356 Rev A
Command Reference
Successful request, VolServ is not
available
Step 1.
Step 2.
Successful request, VolServ is not available.
Requests VolServ to acknowledge receipt of the Ping
request.
vsping
Output returned:
VolServ is not available
Error CMD022: could not send command
to volume server.
Notes
The client is not required to use vspingbefore issuing other
commands.
The vspingcommand is a relatively fast operation.
No VolServ status messages are returned in response to the
vspingcommand.
The vspingcommand does not trigger unsolicited status
messages from VolServ.
See Also
None
601356 Rev A
Command Reference
2-123
Command Reference
Configures a specified drivepool.
vspoolcfg
vspoolcfg -p drivepool
vspoolcfg -c driveid
vspoolcfg -d driveid
vspoolcfg -i driveid
vspoolcfg -r driveid
Parameters
[ -Ih ]
[ -H hostname ]
[ -P priority ]
[ -R retries ]
[ -T timeout ]
[ -V prognum]
Parameters
Parameter
Description
-p drivepool
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.
-c driveid
Identifies the drive where the media is
mounted.
-d driveid
-i driveid
-r driveid
2-124
Command Reference
601356 Rev A
Command Reference
Parameter
Description
-I
Command options are first read from the
command line. VolServ then reads any
options contained in the stdinfile.
-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.
-P πρι ορι τ ψ
The execution priority of the entered
command. Assignable priority values are
restricted to a range from 1 (highest) to 32
(lowest) inclusive.
Default value is
15.
-R retries
Number of retries the CLI software attempts if
a time-out is returned by the API software.
Default value is
3.
-T timeout
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.
Default value is
120 seconds.
-V prognum
RPC program number for VolServ.
Default value is
300016.
601356 Rev A
Command Reference
2-125
Command Reference
Queries for information on a specified drive pool or on all drive
pools known to VolServ.
vspoolqry
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.
vspoolqry drivepool
Parameters
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.
• Valid drive pool names may contain up to
16 alphanumeric characters, including
spaces.
• Leading and trailing spaces are not
permitted.
-v
IIndicates that verbose output is needed.
Status is returned on every media specified in
the vscheckoutcommand.
NOTE: If -vis not specified, status is returned
on only those media that were not
successfully checked out.
2-126
Command Reference
601356 Rev A
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 stdinfile.
-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
-P priority
Host name of the VolServ server.
The default host name is the host name of the
computer where the CLI command is run.
The execution priority of the entered
command. Assignable priority values are
restricted to a range from 1 (highest) to 32
(lowest) inclusive.
Default value is
15.
-R retries
Number of retries the CLI software attempts if
a time-out is returned by the API software.
Default value is
3.
-T timeout
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.
Default value is
120 seconds.
-V prognum
RPC program number for VolServ.
Default value is
300016.
Return Codes
•
0 - The vspoolqrycommand is successfully processed.
601356 Rev A
Command Reference
2-127
Command Reference
•
•
-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.
Examples
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.
Output returned:
-----------------------------------------------
Drive Pool Query Report
May 25 15:03:52 19931
-----------------------------------------------
Drive Pool: drvpoolsml
-----------------------------------------------
²
²
²
Drive ID: 4
Drive Type:
Associated Archive:
Current State:
Assignment:
Usage Count:
Mount State:
Mounted Media ID:
²
Magnetic
shelf2
Offline
Free
1
Unmounted
²
²
2-128
Command Reference
601356 Rev A
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 ID: 13
Drive Type:
Associated Archive:
Current State:
Assignment:
Usage Count:
Mount State:
Mounted Media ID:
²
Magnetic
shelf1
Diagnostic
Free
0
Unmounted
²
²
Step 1.
Successful Drive Pool Query request with verbose
option not specified.
Requests the VolServ to return a list of Drive IDs for
every drive pool known to the VolServ system.
vspoolqry -a
Step 2.
Output returned:
-----------------------------------------------
Drive Pool Query Report
May 26 15:45:52 19931
-----------------------------------------------
601356 Rev A
Command Reference
2-129
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 NoPooldrive pool.
vspoolqry NoPool -v
Step 2.
Output returned:
Query of drive pool [NoPool] was
unsuccessful
Error VOL008: item not found
Notes
The vspoolqrycommand does not trigger unsolicited status
messages from VolServ.
2-130
Command Reference
601356 Rev A
Command Reference
A pending vspoolqryis cancelled with the VolServ cancel
command. The VolServ cancel command is run from the
command line by sending a SIGQUIT signal (control-\). The
vspoolqryalso is aborted by sending the SIGINT signal
(control-c).
See Also
None
601356 Rev A
Command Reference
2-131
Command Reference
Queries for drives that could be used in a subsequent mount of a
specified media.
vsqrymount
The vsqrymountoutput 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 vsqrymountrequest, VolServ determines
which library contains the specified media:
•
If the specified media is not in a library, a null list of drives
is returned to the client.
•
If the media is in a library, VolServ determines which drives
in that library (and only that library) are suitable (based on
the media’s type) for mounting the media.
vsqrymount mediaid
Parameters
[-Ih]
[ -H hostname ]
[ -P priority ]
[ -R retries ]
[ -T timeout ]
[ -V prognum]
Parameters
Parameter
Description
mediaid
Specifies the media for which a list of drives
supporting the media’s type is being
requested.
A valid media identifier may contain up to 16
alphanumeric characters, including spaces.
Leading and trailing spaces are not permitted.
2-132
Command Reference
601356 Rev A
Command Reference
Parameter
Description
-I
Command options are first read from the
command line. VolServ then reads any
options contained in the stdinfile.
-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
-P priority
Host name of the VolServ server.
The default host name is the host name of the
computer where the CLI command is run.
The execution priority of the entered
command. Assignable priority values are
restricted to a range from 1 (highest) to 32
(lowest) inclusive.
Default value is
15.
-R retries
Number of retries the CLI software attempts if
a time-out is returned by the API software.
Default value is
3.
-T timeout
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.
Default value is
120 seconds.
-V prognum
RPC program number for VolServ.
Default value is
300016.
Return Codes
•
•
0 - The vsqrymountcommand is successfully processed.
-1 - An error is detected by either the CLI software or the
API software.
601356 Rev A
Command Reference
2-133
Command Reference
•
>0 - An error is detected by VolServ. The returned exit code
corresponds to the error code given by VolServ.
Examples
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.
Requests VolServ to return a list of drives that are
candidates to be mounted with MED041.
vsqrymount MED041
Step 2.
Output returned:
Query Mount for media [MED041] was unsuccessful.
Error VOL043: media mounted
1Drive [11]
2Drive [7]
Step 1.
Unsuccessful Query Mount request.
2-134
Command Reference
601356 Rev A
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
The returned list of drives are known to be suitable for
mounting the specified media, but those drives are not available
if they are currently in use.
Drives that are not online are not considered suitable for
mounting and are, therefore, not returned in response to the
query.
If a vsqrymountis run against media:
•
•
that is found to be currently mounted, the output to the
client includes a message that the media is mounted, in
addition to a list of suitable drives.
that is currently allocated for mounting (but has not
completed the mount move), the output includes a message
that the media is assigned.
The ordering of the returned drive list is based on the media’s
current physical location. Drives that are not mounted are listed
before drives that have media mounted on them. Consequently,
for a mounted media, the drive where the media is currently
mounted may not be the first drive on the returned list.
601356 Rev A
Command Reference
2-135
Command Reference
The vsqrymountcommand does not trigger unsolicited status
messages from VolServ.
A pending vsqrymountrequest 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).
See Also
•
vsmount
2-136
Command Reference
601356 Rev A
Command Reference
Changes the MediaClass name of one or more media.
vsreclassify
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
vsreclassifyfails and a failure return code is returned to
the client.
If the target MediaClass group is not filled to capacity, only as
many media as it takes to reach the capacity are reclassified.
Any remaining media specified in the vsreclassify
command request are not reclassified and have a failure
indicator returned to the client.
vsreclassify mediaid
Parameters
vsreclassify -c currentmediaclass
vsreclassify -n newmediaclass
[-Ihv]
[ -H hostname ]
[ -P priority ]
[ -R retries ]
[ -T timeout ]
[ -V prognum]
601356 Rev A
Command Reference
2-137
Command Reference
Parameters
Parameter
mediaid…
-c currentmediaclass
Description
Specifies a list of one through 64 media to
be reclassified.
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.
• Valid MediaClass names may contain up
to 16 alphanumeric characters, including
spaces.
• Leading and trailing spaces are not
permitted.
-v
-I
Indicates that verbose output is needed.
Status is returned on every media
specified in the vscheckoutcommand.
NOTE: If -vis 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 stdinfile.
2-138
Command Reference
601356 Rev A
Command Reference
Parameter
Description
-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.
-P priority
The execution priority of the entered
command. Assignable priority values are
restricted to a range from 1 (highest) to 32
(lowest) inclusive.
Default value is 15.
-R retries
Number of retries the CLI software
attempts if a time-out is returned by the
API software.
Default value is 3.
-T timeout
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.
Default value is 120
seconds.
-V prognum
RPC program number for VolServ.
Default value is
300016.
Return Codes
•
•
•
0 - The vsreclassifycommand 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.
601356 Rev A
Command Reference
2-139
Command Reference
Examples
Step 1.
Successful Reclassify request with verbose option
specified.
Requests VolServ to reclassify media MED002,
MED023,and MED044from MediaClass group
medclassstgsmlto medclasssmland 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]
Media [MED023]
Media [MED044]
no error
no error
no error
Step 1.
Successful Reclassify request with verbose option
not specified.
Requests VolServ to reclassify media MED002,
MED023,and MED044from MediaClass group
medclasssmlto medclassstgsmland to
return status on media only if processing for that
media was unsuccessful.
vsreclassify MED002 MED023 MED044 -c
medclasssml -n medclassstgsml
Step 2.
Step 1.
Output returned:
Reclassify of 3 of 3 media into class
[medclassstgsml] was successful
Errors with verbose option specified.
2-140
Command Reference
601356 Rev A
Command Reference
Requests VolServ to reclassify media MED013,
MED017, MED020, MED032, MED041,and
BadMediafrom MediaClass group
medclasssmlto medclasssh2smland to
return status on every specified media.
vsreclassify MED013 MED017 MED020
MED032 MED041 BadMedia -c medclasssml
-n medclasssh2sml -v
Step 2.
Output returned:
Reclassify of 2 of 6 media into class [medclasssh2sml] was
successful
Error VOL024:
Media [MED013]
error in the list
class does not support media type
no error
invalid current class
no error
Media [MED017]
Media [MED020]
Media [MED032]
Media [MED041]
archive not associated with
mediaclass
Media [BadMedia]
item not found
Step 1.
Errors with verbose option not specified.
Requests VolServ to reclassify media MED013,
MED017, MED020, MED032, MED041,and
BadMediafrom MediaClass group
medclasssmlto medclasssh2smland to
return status on media only if processing on that
media was unsuccessful.
vsreclassify MED013 MED017 MED020
MED032 MED041 BadMedia -c medclasssml
-n medclasssh2sml
601356 Rev A
Command Reference
2-141
Command Reference
Step 2.
Output returned:
Reclassify of 2 of 6 media into class [medclasssh2sml] was
successful
Error VOL024:
Media [MED013]
error in the list
class does not support media type
invalid current class
archive not associated with
mediaclass
Media [MED020]
Media [MED041]
Media [BadMedia] item not found
Step 1.
Unsuccessful Reclassify request.
Requests VolServ to reclassify the media MED042
from MediaClass group medclassmedto
BadClassand to return status on media only if
processing on that media was unsuccessful.
vsreclassify MED042 -c medclassmed -n
BadClass
Step 2.
Output returned:
Reclassify of media into class
[BadClass] was unsuccessful
Error VOL147: invalid target class
Notes
The reclassifycommand cannot be cancelled.
Pending vsmountrequests are not affected by the
reclassification of media.
If the capacity of the target MediaClass group is exceeded by
the reclassification, only as many media as necessary to reach
capacity are reclassified; the reclassification of any remaining
media fails.
2-142
Command Reference
601356 Rev A
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
vsreclassifyrequest 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.
If reclassifying media places it in a MediaClass group that does
not have the media’s present location as a preferred location, the
media is NOT moved just to place it into a preferred area. Later,
if the media is mounted then dismounted, or ejected then
entered, an attempt is made to place the media in a preferred
location as defined by the target library media class.
If media to be reclassified is in a library, the target MediaClass
group must be associated with that library.
Media that does not reside in a library can be reclassified.
The vsreclassifycommand triggers unsolicited status
messages from VolServ.
See Also
•
•
vsmount
vsmedclassqry
601356 Rev A
Command Reference
2-143
Command Reference
Queries for information about a specified request.
vsrequestqry
The client must specify VolServ assigned request identifier of
the request being queried.
Upon receipt of a vsrequestqryrequest, 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.
vsrequestqry requestid
Parameters
[ -Ih ]
[ -H hostname ]
[ -P priority ]
[ -R retries ]
[ -T timeout ]
[ -V prognum]
Parameters
Parameter
requestid
Description
Specifies the VolServ-assigned identifier of
the request to be queried. A valid request
identifier must be specified in the: yyyyddmm
format.
-I
Command options are first read from the
command line. VolServ then reads any
options contained in the stdinfile.
2-144
Command Reference
601356 Rev A
Command Reference
Parameter
Description
-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
-P priority
Host name of the VolServ server.
The default host name is the host name of the
computer where the CLI command is run.
The execution priority of the entered
command. Assignable priority values are
restricted to a range from 1 (highest) to 32
(lowest) inclusive.
Default value is
15.
-R retries
Number of retries the CLI software attempts if
a time-out is returned by the API software.
Default value is
3.
-T timeout
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.
Default value is
120 seconds.
-V prognum
RPC program number for VolServ.
Default value is
300016.
Return Codes
•
•
0 - The vsrequestqrycommand is successfully
processed.
-1 - An error is detected by either the CLI software or the
API software.
601356 Rev A
Command Reference
2-145
Command Reference
•
>0 - An error is detected by VolServ. The returned exit code
corresponds to the error code given by VolServ.
Examples
Step 1.
Successful Request Query.
Requests VolServ to return status on request
93:144:02136(or 314402136).
vsrequestqry 93:144:02136
Step 2.
Output returned:
-----------------------------------------------
Request Query Report
May 24 12:43:18 19931
-----------------------------------------------
Request ID:
93:144:02136
-----------------------------------------------
Request Type:
Priority:
Move
15
Time:
Current State:
May 24 12:41:54 1993
Executing
Step 1.
Unsuccessful Request Query.
Requests VolServ to return status on request
314402137 (or 93:144:02137).
vsrequestqry 314402137
Step 2.
Output returned:
-----------------------------------------------
Request Query Report
May 24 12:54:43 19931
-----------------------------------------------
Error:
item not found
2-146
Command Reference
601356 Rev A
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 vsrequestqrycommand returns information for only
one request per execution.
The vsrequestqrycommand does not trigger unsolicited
status messages from VolServ.
A pending vsrequestqryis 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).
See Also
None
601356 Rev A
Command Reference
2-147
Command Reference
Releases exclusive use of one or more drives.
vsunlock
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 unlockrequests. Each
unlockrequest can specify a subset of the drives held by the
client. VolServ releases only those drives specified in the
unlockrequest.
vsunlock driveid…
vsunlock -l lockid
Parameters
[ -Ihv ]
[ -H hostname ]
[ -P priority ]
[ -R retries ]
[ -T timeout ]
[ -V prognum ]
Parameters
Parameter
driveid…
Description
Specifies a list of one through 64 drives to be
released (unlocked) from exclusive use.
-l lockid
Indicates the lock identifier assigned to the
specified, locked drive.
-v
Indicates that verbose output is needed.
Status is returned on every media specified in
the vscheckoutcommand.
NOTE: If -vis not specified, status is returned
on only those media that were not
successfully checked out.
2-148
Command Reference
601356 Rev A
Command Reference
Parameter
Description
-I
Command options are first read from the
command line. VolServ then reads any
options contained in the stdinfile.
-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
-P priority
Host name of the VolServ server.
The default host name is the host name of the
computer where the CLI command is run.
The execution priority of the entered
command. Assignable priority values are
restricted to a range from 1 (highest) to 32
(lowest) inclusive.
Default value is
15.
-R retries
Number of retries the CLI software attempts if
a time-out is returned by the API software.
Default value is
3.
-T timeout
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.
Default value is
120 seconds.
-V prognum
RPC program number for VolServ.
Default value is
300016.
Return Codes
•
0 - The vsunlockcommand is successfully processed.
601356 Rev A
Command Reference
2-149
Command Reference
•
•
-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.
Examples
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.
Output returned:
Unlock [3] drives unlocked with lock id [1719790788]
Drive [4] no error
Drive [8] no error
Drive [12] no error
Step 1.
Successful Unlock request without verbose option
specified.
Requests VolServ to unlock drive 4and 3, with an
assigned lock identifier of 1719790788, and to
return status on a drive only if the Unlock request for
that drive was unsuccessful.
vsunlock 4 8 -l 1719790788
Unlock [2] drives unlocked with lock
id [1719790788]
2-150
Command Reference
601356 Rev A
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:
Unlock [3] drives unlocked with lock id [1719790788]
Error VOL024: error in the list
Drive [40] invalid lock id
Drive [41]no error
Drive [42] no error
Drive [43] no error
Step 1.
Unsuccessful Unlock identifier without verbose
option.
Requests VolServ to unlock drives 40, 41, 42,
and 43, three of which have an assigned lock
identifier of 1719790788and to return status on a
drive only if the Unlock request for that drive was
unsuccessful.
vsunlock 40 41 42 43 -l 1719790788
Step 2.
Output returned:
Unlock [3] drives unlocked with lock id [1719790788]
Error VOL024: error in the list
Drive [40] invalid lock id
601356 Rev A
Command Reference
2-151
Command Reference
Notes
The client can release a subset of drives locked by a single
vsunlockrequest.
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 vsunlockcommand does not trigger unsolicited status
messages from VolServ.
A pending vsunlockis 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).
See Also
•
vslock
2-152
Command Reference
601356 Rev A
Command Reference
Starts the VolServ system administrator’s console and brings up
the system GUI display.
vswin
vswin -displayhost#
Parameters
Parameters
Parameter
-display host#
Description
Starts the VolServ GUI.
Return Codes
Example
•
•
0 - Terminated normally.
1 - Error occurred during initialization.
Step 1.
Step 2.
Initialize the VolServ System console.
vswin
Run the VolServ System Console in the background.
vswin &
Notes
The environmental variable VS_DIRmust be set. The
environmental variable II_SYSTEMmust be set and in the path
statement.
vswincan only be run from the VolServ host machine.
601356 Rev A
Command Reference
2-153
Command Reference
The display location of vswinmust give xhostprivileges to
the VolServ host machine for vswinto properly work.
See Also
•
volserv (l)
2-154
Command Reference
601356 Rev A
Command Reference
NOTES
601356 Rev A
Command Reference
2-155
Command Reference
NOTES
2-156
Command Reference
601356 Rev A
|
