IBM Tivoli Storage Manager, Version 7.1

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.

Restrictions:

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.
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.
Before checking volumes out of an ACSLS library, ensure that the CAP priority in ACSLS is greater than zero. If the CAP priority is zero, then you must specify a value for the CAP parameter on the CHECKOUT LIBVOLUME command.

For detailed and current drive and library support information, see the Supported Devices Web site for your operating system:

Privilege class

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

Syntax for SCSI library


>>-CHECKOut LIBVolume--library_name----+-volume_name-+---------->
                                       '-| A |-------'     

   .-REMove--=--Bulk-----.  .-CHECKLabel--=--Yes-----.   
>--+---------------------+--+------------------------+---------->
   '-REMove--=--+-Yes--+-'  '-CHECKLabel--=--+-Yes-+-'   
                +-No---+                     '-No--'     
                '-Bulk-'                                 

   .-FORCE--=--No------.   
>--+-------------------+---------------------------------------><
   '-FORCE--=--+-No--+-'   
               '-Yes-'     

A 

|--+-VOLRange--=----volume_name1,volume_name2---+---------------|
   |               .-,-----------.              |   
   |               V             |              |   
   '-VOLList--=--+---volume_name-+--+-----------'   
                 '-FILE:--file_name-'

Syntax for 349X library


>>-CHECKOut LIBVolume--library_name----+-volume_name-+---------->
                                       '-| A |-------'     

   .-REMove--=--Bulk-----.   
>--+---------------------+-------------------------------------><
   '-REMove--=--+-Yes--+-'   
                +-No---+     
                '-Bulk-'     

A 

|--+-VOLRange--=----volume_name1,volume_name2---+---------------|
   |               .-,-----------.              |   
   |               V             |              |   
   '-VOLList--=--+---volume_name-+--+-----------'   
                 '-FILE:--file_name-'

Syntax for ACSLS library


>>-CHECKOut LIBVolume--library_name----+-volume_name-+---------->
                                       '-| A |-------'     

   .-REMove--=--Yes------.                          
>--+---------------------+--+-------------------+--------------><
   '-REMove--=--+-Yes--+-'  '-CAP--=----x,y,z---'   
                +-No---+                            
                '-Bulk-'                            

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.

VOLRange

Specifies two volume names separated by a comma. This parameter 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. 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.

Attention: The file name is case-sensitive.

REMove

Specifies that the server tries to move the volume out of the library and into the convenience I/O station or entry/exit ports. This parameter is optional. Possible values, depending on the type of library, are YES, BULK, and NO. The response of the server to each of those options and the default values are described in the following sections.

349X libraries: The default is BULK. The following table shows how the server responds for 349X libraries.

Table 1. How the Tivoli Storage Manager server responds for 349X libraries
REMOVE=YES	REMOVE=BULK	REMOVE=NO
The 3494 Library Manager ejects the cartridge to the convenience I/O station.	The 3494 Library Manager ejects the cartridge to the high-capacity output facility.	The 3494 Library Manager does not eject the volume. The server leaves the cartridge in the library in the INSERT category for use by other applications.

SCSI libraries: The default is BULK. The following table shows how the server responds for a SCSI libraries.

Table 2. How the Tivoli Storage Manager server responds for SCSI libraries
If a library . . .	And REMOVE=YES, then...	And REMOVE=BULK, then...	And REMOVE=NO, then...
Does not have entry/exit ports	The server leaves the cartridge in its current slot within the library and specifies the slot address in a message. The server then prompts you to remove the cartridge from the slot and to issue a REPLY command.	The server leaves the cartridge in its current slot within the library and specifies the slot address in a message. The server does not prompt you to remove the cartridge and does not require a REPLY command.	The server leaves the cartridge in its current slot within the library and specifies the slot address in a message. The server does not prompt you to remove the cartridge and does not require a REPLY command.
Has entry/exit ports and an entry/exit port is available	The server moves the cartridge to the available entry/exit port and specifies the port address in a message. The server then prompts you to remove the cartridge from the slot and to issue a REPLY command.	The server moves the cartridge to the available entry/exit port and specifies the port address in a message. The server does not prompt you to remove the cartridge and does not request a REPLY command.	The server leaves the cartridge in its current slot within the library and specifies the slot address in a message. The server does not prompt you to remove the cartridge and does not require a REPLY command.
Has entry/exit ports, but no ports are available	The server leaves the cartridge in its current slot within the library and specifies the slot address in a message. The server then prompts you to remove the cartridge from the slot and to issue a REPLY command.	The server waits for an entry/exit port to be made available.	The server leaves the cartridge in its current slot within the library and specifies the slot address in a message. The server does not prompt you to remove the cartridge and does not require a REPLY command.

ACSLS libraries: The default is YES. If the parameter is set to YES, and the cartridge access port (CAP) has an automatic selection priority value of 0, you must specify a CAP ID. The following table shows how the server responds for ACSLS libraries.

Table 3. How the Tivoli Storage Manager server responds for ACSLS libraries
REMOVE=YES or REMOVE=BULK	REMOVE=NO
The server ejects the cartridge to the convenience I/O station, and deletes the volume entry from the server library inventory.	The server does not eject the cartridge. The server deletes the volume entry from the server library inventory and leaves the volume in the library.

CHECKLabel

Specifies how or whether the server reads sequential media labels of volumes.

Attention: This parameter does not apply to IBM® 349X or ACSLS 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.

Attention: This parameter does not apply to IBM 349X or ACSLS 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 applies to volumes in ACSLS libraries only. If the CAP priority value is set to 0 in the library, this parameter is required. If a CAP priority value greater than 0 is set in the library, this parameter is optional. By default, all CAPs initially have a priority value of 0, which means that ACSLS does not automatically select the CAP.

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 identifiers are as follows:

x: The Automated Cartridge System (ACS) ID. This identifier can be a number in the range 0 - 126.
y: The Library Storage Module (LSM) ID. This identifier can be a number in the range 0 - 23.
z: The CAP ID. This identifier can be a number in the range 0 - 11.

For more information, see the StorageTek documentation.

Example: Check out a volume and check the label

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

checkout libvolume forest exb004 checklabel=yes remove=no

Related commands

Table 4. 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 volumes in manual or automated libraries.
QUERY LIBRARY	Displays information about one or more libraries.
QUERY LIBVOLUME	Displays information about a library volume.
QUERY PROCESS	Displays information about background processes.
REPLY	Allows a request to continue processing.
UPDATE LIBVOLUME	Changes the status of a storage volume.

Feedback