CHECKIN LIBVOLUME (Check a storage volume into a library)
Use this command to add a sequential access storage volume or a cleaning tape to the server inventory for an automated library. The server cannot use a volume that physically resides in an automated library until that volume is checked in.
- The CHECKIN LIBVOLUME command processing does not wait for a drive to become available, even if the drive is only in the IDLE state. If necessary, you can make a library drive available issuing the DISMOUNT VOLUME command to dismount the volume. After a library drive is available, reissue the CHECKIN LIBVOLUME command.
- You do not define the drives, check in media, or label the volumes in an external library. The server provides an interface that external media management systems use to operate with the server.
- When you check in WORM tapes other than 3592, you must use CHECKLABEL=YES or they are checked in as normal read/write tapes.
This command creates a background process that you can cancel with the CANCEL PROCESS command. To display information about background processes, use the QUERY PROCESS command.
Privilege class
To issue this command, you must have system privilege or unrestricted storage privilege.
Syntax for SCSI libraries
>>-CHECKIn LIBVolume--library_name------------------------------> .-SEARCH--=--No-. >----+-volume_name--+---------------+-+-------------------------> +-SEARCH--=--Yes--+-------+------+ | '-| A |-' | '-SEARCH--=--Bulk--+-------+-----' '-| A |-' .-OWNer--=--""----------. >--STATus--=--+-PRIvate-+--+-----------------------+------------> +-SCRatch-+ '-OWNer--=--server_name-' '-CLEaner-' .-CHECKLabel--=--Yes---------. .-SWAP--=--No------. >--+----------------------------+--+------------------+---------> '-CHECKLabel--=--+-Yes-----+-' '-SWAP--=--+-No--+-' +-No------+ '-Yes-' '-Barcode-' .-WAITTime--=--60----. >--+--------------------+--+--------------------------+-------->< '-WAITTime--=--value-' '-CLEanings--=----number---' A (SEARCH=Yes, SEARCH=Bulk) |--+-VOLRange--=----volume_name1,volume_name2---+---------------| | .-,-----------. | | V | | '-VOLList--=--+---volume_name-+--+-----------' '-FILE:--file_name-'
Syntax for 349X libraries
>>-CHECKIn LIBVolume--library_name------------------------------> .-SEARCH--=--No-. >----+-volume_name--+---------------+-+-------------------------> '-SEARCH--=--Yes--+-------+------' '-| A |-' .-OWNer--=--""----------. >--STATus--=--+-PRIvate-+--+-----------------------+------------> '-SCRatch-' '-OWNer--=--server_name-' .-CHECKLabel--=--Yes-----. >--+------------------------+--+----------------------+---------> '-CHECKLabel--=--+-Yes-+-' '-DEVType--=--+-3590-+-' '-No--' '-3592-' .-SWAP--=--No------. .-WAITTime--=--60----. >--+------------------+--+--------------------+---------------->< '-SWAP--=--+-No--+-' '-WAITTime--=--value-' '-Yes-' A (SEARCH=Yes) |--+-VOLRange--=----volume_name1,volume_name2---+---------------| | .-,-----------. | | V | | '-VOLList--=--+---volume_name-+--+-----------' '-FILE:--file_name-'
Syntax for ACSLS libraries
>>-CHECKIn LIBVolume--library_name------------------------------> .-SEARCH--=--No-. >----+-volume_name--+---------------+-+-------------------------> '-SEARCH--=--Yes--+-------+------' '-| A |-' .-OWNer--=--""----------. >--STATus--=--+-PRIvate-+--+-----------------------+------------> '-SCRatch-' '-OWNer--=--server_name-' .-CHECKLabel--=--Yes-----. .-SWAP--=--No------. >--+------------------------+--+------------------+-------------> '-CHECKLabel--=--+-Yes-+-' '-SWAP--=--+-No--+-' '-No--' '-Yes-' .-WAITTime--=--60----. >--+--------------------+-------------------------------------->< '-WAITTime--=--value-' A (SEARCH=Yes) |--+-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 of the storage volume that is being checked in. This parameter is required if SEARCH equals NO. Do not enter this parameter if the SEARCH parameter equals YES or BULK. If you are checking a volume into a SCSI library with multiple entry/exit ports, the volume in the lowest numbered slot is checked in.
- STATus (Required)
- Specifies the volume status. Possible values are:
- PRIvate
- Specifies that the volume is a private volume that is mounted only when it is requested by name.
- SCRatch
- Specifies that the volume is a new scratch volume. This volume
can be mounted to satisfy scratch mount requests during either data
storage operations or export operations.
If a volume has an entry in volume history, you cannot check it in as a scratch volume.
- CLEaner
- Specifies that the volume is a cleaner cartridge and not a data
cartridge. The CLEANINGS parameter is required for a cleaner cartridge
and must be set to the number of cleaner uses.
CHECKLABEL=YES is not valid for checking in a cleaner cartridge. Use STATUS=CLEANER to check in a cleaner cartridge separately from a data cartridge.
- OWNer
- Specifies which library client owns a private volume in a library that is shared across a SAN.
The volume for which you specify ownership must be a private volume. You cannot specify ownership
for a scratch volume. Furthermore, you cannot specify an owner when you use SEARCH=YES or
SEARCH=BULK.
When you issue the CHECKIN LIBVOLUME command, the server validates the owner. If you did not specify this parameter, then the server uses the default and delegates volume ownership to the owning library client, as recorded in the volume history file on the library manager. If the volume is not owned by any library client, then the server delegates ownership to the library manager.
- SEARCH
- Specifies whether the server searches the library to find volumes
that were not checked in. This parameter is optional. The default
is NO.
Possible values are:
- No
- Specifies that only the named volume is checked into the library.
For SCSI libraries: The server issues a request to have the volume inserted into a cartridge slot in the library or, if available, into an entry port. The cartridge slot or entry port is identified by its element address. For 349X libraries: The volume might already be in the library, or you can put it into the I/O station when prompted.
- Yes
- Specifies that the server searches the library for volumes to
be checked in. You can use the VOLRANGE or VOLLIST parameter
to limit the search. When you use this parameter, consider the following
restrictions:
- If the library is shared between applications, the server might examine a volume that is required by another application. For 349X libraries, the server queries the library manager to determine all volumes that are assigned to the SCRATCH or PRIVATE category and to the INSERT category.
- For SCSI libraries, do not specify both SEARCH=YES and CHECKLABEL=NO in the same command.
- Bulk
- Specifies that the server searches the library's entry/exit ports
for volumes that can be checked in automatically. This option applies
to only SCSI libraries. Important:
- Do not specify both CHECKLABEL=NO and SEARCH=BULK.
- You can use the VOLRANGE or VOLLIST parameter to limit the search.
- VOLRange
- Specifies a range of volume names that are separated by commas.
You can use this parameter to limit the search for volumes to be
checked in when you specify SEARCH=YES (349X, ACSLS, and SCSI libraries)
or SEARCH=BULK (SCSI libraries only). 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 in: bar110, bar111, bar112,...bar129, bar130. volrange=bar11a,bar13a The 3 volumes are checked in: bar11a, bar12a, bar13a. volrange=123400,123410 The 11 volumes are checked in: 123400, 123401, ...123409, 123410. - VOLList
- Specifies a list of volumes. You can use this parameter to limit
the search for volumes to be checked in when you specify SEARCH=YES
(349X, ACSLS, and SCSI libraries) or SEARCH=BULK (SCSI libraries only).
If there are no volumes in the library that are in the list, the command
completes without errors. Possible values are:
- volume_name
- Specifies one or more volumes names that are separated by commas and no intervening spaces. For 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.
- CHECKLabel
- Specifies
how or whether the server should read sequential media labels of volumes.
This parameter is optional. The default is YES. Possible values are:
- Yes
- Specifies that an attempt is made to read the media label during
check-in. Attention:
- For SCSI libraries, do not specify both SEARCH=YES and CHECKLABEL=NO in the same command.
- For WORM media other than 3592, you must specify YES.
- No
- Specifies that the media label is not read during check-in. However, suppressing label checking can result in future errors (for example, either a wrong label or an improperly labeled volume can cause an error). For 349X and ACSLS libraries, specify NO to avoid loading cartridges into a drive to read the media label. These libraries always return the external label information about cartridges, and IBM Spectrum Protect™ uses that information.
- Barcode
- Specifies that the server reads the bar code label if the library
has a bar code reader and the volumes have external bar code labels.
You can decrease the check-in time by using the bar code. This parameter
applies only to SCSI libraries.
If the bar code reader cannot read the bar code label, or if the tape does not have a bar code label, the server mounts the tape and reads the internal label.
- DEVType
- Specifies the device type for the volume that is being checked
in. This parameter is required if none of the drives in this library have defined
paths.
- 3590
- Specifies that the device type for the volume that is being checked in is 3590.
- 3592
- Specifies that the device type for the volume that is being checked in is 3592.
- SWAP
- Specifies
whether the server swaps volumes if an empty library slot is not available. The
volume that is selected for the swap operation (target swap volume)
is ejected from the library and replaced with the volume that is being
checked in. The server identifies a target swap volume by checking
for an available scratch volume. If none exists, the server identifies
the least frequently mounted volume.
This parameter is optional. The default is NO. This parameter applies only if there is a volume name that is specified in the command. Possible values are:
- No
- Specifies that the server checks in the volume only if an empty slot is available.
- Yes
- Specifies that if an empty slot is not available, the server swaps cartridges to check in the volume.
- WAITTime
- Specifies the number of minutes that the server waits for you to reply or respond to a request. Specify a value in the range 0-9999. If you want to be prompted by the server, specify a wait time greater than zero. The default value is 60 minutes. For example, suppose the server prompts you to insert a tape into the entry/exit port of a library. If you specified a wait time of 60 minutes, the server issues a request and waits 60 minutes for you to reply. Suppose, on the other hand, you specify a wait time of 0. If you already inserted a tape, a wait time of zero causes the operation to continue without prompting. If you have not inserted a tape, a wait time of zero will cause the operation to fail.
- CLEanings
- Enter the recommended value for the individual cleaner cartridge
(usually indicated on the cartridge). Cleanings apply only to SCSI
libraries. This parameter is required if STATUS=CLEANER.
If more than one cleaner is checked into the library, only one is used until its CLEANINGS value decreases to zero. Another cleaner is then selected, and the first cleaner can be checked out and discarded.
Example: Check a volume into a SCSI library
Check in a volume named WPDV00 into the SCSI library named AUTO.checkin libvolume auto wpdv00 status=scratch
Example: Use a bar code reader to scan a library for a cleaner cartridge
Scan a SCSI library named AUTOLIB1 and, using the bar code reader, look for cleaner cartridge CLNV. Use SEARCH=YES, but limit the search by using the VOLLIST parameter.checkin libvolume autolib1 search=yes vollist=cleanv status=cleaner
cleanings=10 checklabel=barcode
Example: Scan a library to put unused volumes in a specific range in scratch status
Scan a 349X library named ABC, and limit the search to a range of unused volumes BAR110 to BAR130 and put them in scratch status.checkin libvolume abc search=yes volrange=bar110,bar130
status=scratch
Example: Scan a library to put a specific volume in scratch status
Use the barcode reader to scan a SCSI library named MYLIB for VOL1, and put it in scratch status.checkin libvolume mylib search=yes vollist=vol1 status=scratch
checklabel=barcode
Related commands
Command | Description |
---|---|
AUDIT LIBRARY | Ensures that an automated library is in a consistent state. |
CANCEL PROCESS | Cancels a background server process. |
CHECKOUT LIBVOLUME | Checks a storage volume out of 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. |
DISMOUNT VOLUME | Dismounts a sequential, removable volume by the volume name. |
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. |