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.
- 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. IBM Spectrum Protect™ might appear to be hung when it is not. 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.
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 that are 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 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 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 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.
Example: Check out a volume and check the label
Check out the volume that is 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
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. |