Tivoli Header

Administrator's Reference

CHECKOUT LIBVOLUME (Check a Storage Volume out of a Library)

Use this command to remove a sequential access storage volume from the server inventory for an automated library. This command creates a background process that can be canceled with the CANCEL PROCESS command. To display information on background processes, use the QUERY PROCESS command.

Notes:

  1. Check out processing does not wait for a drive to become available, even if the drive is in the IDLE state. If necessary, you can make a library drive available by dismounting the volume with the DISMOUNT VOLUME command. After a drive is available, the CHECKOUT LIBVOLUME command can be reissued.

  2. Before checking out volumes from a 349X library, ensure that the 349x Cartridge Input and Output facility has enough empty slots for the volumes to be checked out. The 3494 Library Manager does not inform an application that the Cartridge Input and Output facility is full. It accepts requests to eject a cartridge and waits until the Cartridge Input and Output facility is emptied before returning to the server. Tivoli Storage Manager may appear to be hung when it is not. You should check the library and clear any intervention requests.

Privilege Class

To issue this command, you must have system privilege or unrestricted storage privilege.

Syntax



SCSI Library

>>-CHECKOut LIBVolume--library_name----volume_name-------------->
 
   .-REMove--=--Yes------.  .-CHECKLabel--=--Yes-----.
>--+---------------------+--+------------------------+---------->
   '-REMove--=--+-Yes--+-'  '-CHECKLabel--=--+-Yes-+-'
                +-No---+                     '-No--'
                '-Bulk-'
 
   .-FORCE--=--No------.
>--+-------------------+---------------------------------------><
   '-FORCE--=--+-No--+-'
               '-Yes-'
 
 

Syntax



349X Library

>>-CHECKOut LIBVolume--library_name----volume_name-------------->
 
   .-REMove--=--Yes------.
>--+---------------------+-------------------------------------><
   '-REMove--=--+-Yes--+-'
                +-No---+
                '-Bulk-'
 
 

Syntax



ACSLS Library

>>-CHECKOut LIBVolume--library_name----+-volume_name-+---------->
                                       '-| A |-------'
 
   .-REMove--=--Yes-----.  .-CHECKLabel--=--Yes-----.
>--+--------------------+--+------------------------+----------->
   '-REMove--=--+-Yes-+-'  '-CHECKLabel--=--+-Yes-+-'
                '-No--'                     '-No--'
 
   .-FORCE--=--No------.
>--+-------------------+--+-------------------+----------------><
   '-FORCE--=--+-No--+-'  '-CAP--=----x,y,z---'
               '-Yes-'
 
A 
 
|--+-VOLRange--=----volume_name1,volume_name2---+---------------|
   |               .-,-----------.              |
   |               V             |              |
   '-VOLList--=--+---volume_name-+--+-----------'
                 '-FILE:--file_name-'
 
 

Parameters

library_name (Required)
Specifies the name of the library.

volume_name
Specifies the volume name. This parameter is required for SCSI and 3494 libraries.

VOLRange
Specifies two volume names separated by a comma. This parameter, which applies only to ACSLS libraries, is a range of volumes to be checked out. If there are no volumes in the library that are within the specified range, the command completes without errors.

Specify only volume names that can be numerically incremented. In addition to the incremental area, a volume name can include an alphanumeric prefix and an alphanumeric suffix, for example:

Parameter Description
volrange=bar110,bar130 The 21 volumes are checked out: bar110, bar111, bar112,...bar129, bar130.
volrange=bar11a,bar13a The 3 volumes are checked out: bar11a, bar12a, bar13a.
volrange=123400,123410 The 11 volumes are checked out: 123400, 123401, ...123409, 123410.

VOLList
Specifies a list of volumes to check out. This parameter only applies to ACSLS libraries. If there are no volumes in the library that are in the list, the command completes without errors.

Possible values are:

volume_name
Specifies the names of one or more values used for the command. Example: VOLLIST=TAPE01,TAPE02.

FILE:file_name
Specifies the name of a file that contains a list of volumes for the command. In the file, each volume name must be on a separate line. Blank lines and comment lines that begin with an asterisk are ignored. For example, to use volumes TAPE01, TAPE02 and TAPE03, create a file, TAPEVOL, that contains these lines:
TAPE01
TAPE02
TAPE03

You can specify the volumes for the command as follows: VOLLIST=FILE:TAPEVOL.

Note:
The file name is case-sensitive.

REMove
Specifies that the server tries to move the volume out of the library and into the bulk I/O station or entry/exit ports.

For 349x Libraries:

For SCSI Libraries:


Table 29. How Tivoli Storage Manager Responds to REMOVE=YES or REMOVE=BULK for SCSI Libraries

If a library . . . Then . . .
Does not have entry/exit ports TSM leaves the cartridge in its current slot within the library and specifies the slot address in a message.
Has entry/exit ports and an entry/exit port is available TSM moves the cartridge to the available entry/exit port and specifies the port address in a message.
Has entry/exit ports, but no ports are available TSM leaves the cartridge in its current slot within the library and specifies the slot address in a message.

This parameter is optional. The default is YES. Possible values are:

Yes
Specifies that a volume is placed into the bulk I/O station. The server deletes the volume entry from the server library inventory.

No
Specifies that a volume is not ejected. The server deletes the volume entry from the server library inventory and leaves the volume in the library for use by other applications.

Bulk
For SCSI libraries with multiple entry/exit ports, this specifies that the volume is ejected to the next available entry/exit port.
Note:
For SCSI libraries only, if REMOVE=BULK, the server indicates where the cartridge is located, but it does not require or request a REPLY command.

CHECKLabel
Specifies how or whether the server reads sequential media labels of volumes.
Note:
This parameter does not apply to IBM 349X libraries.

This parameter is optional. The default is YES. Possible values are:

Yes
Specifies that the server attempts to read the media label to verify that the correct volume is being checked out.

No
Specifies that during checkout the media label is not read. This improves performance because the read process does not occur.

FORCE
Specifies whether the server checks out a volume if an input/output (I/O) error occurs when reading the label.
Note:
This parameter does not apply to IBM 349X libraries.
This parameter is optional. The default is NO. Possible values are:

No
The server does not check out a storage volume if an I/O error occurs when reading the label.

Yes
The server checks out the storage volume even if an I/O error occurs.

CAP
Specifies which cartridge access port (CAP) to use for ejecting volumes if you specify REMOVE=YES. This parameter only applies to ACSLS libraries.

To display valid CAP identifiers (x,y,z), issue the QUERY CAP command with ALL specified from the automated cartridge system system administrator (ACSSA) console on the ACSLS server host. The default value is (-1,-1,-1), in which case the ACSLS server will choose any available CAP with a non-zero priority. This parameter is optional. With CAP=x,y,z specified, each identifier corresponds to:

x
The Automated Cartridge System (ACS) ID. This identifier can be a number between 0-126.

y
The Library Storage Module (LSM) ID. This identifier can be a number between 0-23.

z
The CAP ID. This identifier can be a number between 0-2.

Refer to your Storage Tek documentation for more information.

Examples

Task

Check out the volume named EXB004 from the library named FOREST. Read the label the verify the volume name, but do not move the volume out of the library.

Command:
checkout libvolume forest exb004 checklabel=yes remove=no

Related Commands

Table 30. Commands Related to CHECKOUT LIBVOLUME

Command Description
AUDIT LIBRARY Ensures that an automated library is in a consistent state.
CANCEL PROCESS Cancels a background server process.
CHECKIN LIBVOLUME Checks a storage volume into an automated library.
DEFINE LIBRARY Defines an automated or manual library.
DEFINE VOLUME Assigns a volume to be used for storage within a specified storage pool.
LABEL LIBVOLUME Labels a library volume.
QUERY LIBRARY Displays information about one or more libraries.
QUERY LIBVOLUME Displays information about a library volume.
QUERY PROCESS Displays information about background processes.
UPDATE LIBVOLUME Changes the status of a storage volume.


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]