LABEL LIBVOLUME (Label a library volume)

Use this command to label tape volumes or, in an automated library, to label the volumes automatically as they are checked in. With this command, the server uses the full-length label with which the volumes are often prelabeled.

Restriction: Use this command only for MANUAL, SCSI, ACSLS, and 349X libraries. The 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 by issuing the DISMOUNT VOLUME command to dismount the volume in that particular drive. When the library drive becomes available, you can reissue the LABEL LIBVOLUME command.

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

To use the LABEL LIBVOLUME command, at least one drive must exist that is not in use by another Tivoli® Storage Manager process. This includes idle volumes that are mounted. If necessary, use the DISMOUNT VOLUME command to dismount the idle volume to make that drive available.

By default, the LABEL LIBVOLUME command does not overwrite an existing label. However, if you want to overwrite an existing label, you can specify the OVERWRITE=YES option.

Attention:

By overwriting a volume label, you destroy all data on the volume. Use caution when you overwrite volume labels to avoid deleting valid data.
The labels on VolSafe volumes can be overwritten only once. Therefore, use the LABEL LIBVOLUME command only once for VolSafe volumes. You can guard against overwriting the label by using the OVERWRITE=NO option with the LABEL LIBVOLUME command.

When you use the LABEL LIBVOLUME command, you can identify the volumes to be labeled in one of the following ways:

Explicitly name one volume.
Enter a range of volumes by using the VOLRANGE parameter.
Use the VOLLIST parameter to specify a file that contains a list of volume names or to explicitly name one or more volumes.

For automated libraries, you are prompted to insert the volume in the entry/exit slot of the library. If no I/O convenience station is available, insert the volume into an empty slot. For manual libraries, you are prompted to load the volume directly into a drive.

Tip: To automatically label tape volumes, you can use the AUTOLABEL parameter on the DEFINE LIBRARY and UPDATE LIBRARY commands. By using the AUTOLABEL parameter, you eliminate the need to pre-label a set of tapes. This method is more efficient than using the LABEL LIBVOLUME command, which requires you to mount volumes separately. If you use the AUTOLABEL parameter with a SCSI library, you must check in tapes by specifying CHECKLABEL=BARCODE on the CHECKIN LIBVOLUME command. The AUTOLABEL parameter defaults to YES for all non-SCSI libraries and to NO for SCSI libraries.

To label volumes with the LABEL LIBVOLUME command, specify the CHECKIN parameter.

To automatically label tape volumes in SCSI-type libraries, use the AUTOLABEL parameter on the DEFINE LIBRARY and UPDATE LIBRARY commands. By using this parameter, you eliminate the need to pre-label a set of tapes. This method is also more efficient than using the LABEL LIBVOLUME command, which requires you to mount volumes separately. If you use the AUTOLABEL parameter, you must check in tapes by specifying CHECKLABEL=BARCODE on the CHECKIN LIBVOLUME command.

A label cannot include embedded blanks or periods and must be valid when used as a file name on the media.

You must label CD-ROM, Zip, or Jaz volumes with the device utilities from the manufacturer or the Windows utilities. The reason is that Tivoli Storage Manager does not provide utilities to format or label these media types. The operating system utilities include the Disk Administrator program (a graphical user interface) and the label command.

Privilege class

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

Syntax for a manual library


>>-LABEl LIBVolume--library_name------volume_name--------------->

   .-OVERWRITE--=--No------.  .-WAITTime--=--60----.   
>--+-----------------------+--+--------------------+-----------><
   '-OVERWRITE--=--+-No--+-'  '-WAITTime--=--value-'   
                   '-Yes-'

Syntax for a SCSI library


>>-LABEl LIBVolume--library_name-------------------------------->

>----+-volume_name----------------------------------------------------+---->
     '-SEARCH--=--+-Yes--| A |--+--LABELSource--=--+-Barcode--------+-'     
                  '-Bulk--| A |-'                  +-Prompt---------+       
                                                   '-Vollist--| B |-'       

                                .-OVERWRITE--=--No------.   
>--+-------------------------+--+-----------------------+------->
   '-CHECKIN--=--+-SCRatch-+-'  '-OVERWRITE--=--+-No--+-'   
                 '-PRIvate-'                    '-Yes-'     

   .-WAITTime--=--60----.   
>--+--------------------+--------------------------------------><
   '-WAITTime--=--value-'   

A (SEARCH=Yes, SEARCH=Bulk)

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

B (LABELSource=Vollist)

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

Syntax for a 349X library


>>-LABEl LIBVolume--library_name-------------------------------->

>----+-volume_name---------------+------------------------------>
     '-SEARCH--=--Yes----| A |---'     

                                .-OVERWRITE--=--No------.   
>--+-------------------------+--+-----------------------+------->
   '-CHECKIN--=--+-SCRatch-+-'  '-OVERWRITE--=--+-No--+-'   
                 '-PRIvate-'                    '-Yes-'     

   .-WAITTime--=--60----.   
>--+--------------------+--------------------------------------><
   '-WAITTime--=--value-'   

A (SEARCH=Yes)

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

Syntax for an ACSLS library


>>-LABEl LIBVolume--library_name-------------------------------->

>----+-volume_name---------------+------------------------------>
     '-SEARCH--=--Yes----| A |---'     

                                .-OVERWRITE--=--No------.   
>--+-------------------------+--+-----------------------+------->
   '-CHECKIN--=--+-SCRatch-+-'  '-OVERWRITE--=--+-No--+-'   
                 '-PRIvate-'                    '-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 that contains the storage volume.

volume_name

Specifies the name of the volume to be labeled.

For SCSI libraries: The server requests that the volume be inserted into a slot in the library or, if available, into an entry/exit port. The server identifies a slot by the slot's element address. If you are labeling a volume in a SCSI library with multiple entry/exit ports, the volume in the lowest numbered slot will be labeled.
For MANUAL libraries: The server requests that the volume be inserted into a drive.
For 349X libraries: The volume might already be in the library, or you might be prompted to put it into the I/O station.

Remember: If the specified volume name is already defined in a storage pool or in a volume history file, the volume is not labeled, and a message is displayed.

CHECKIN

Specifies whether the server checks in the volume. This parameter is optional. The following are possible values:

SCRatch: Specifies that the server checks in the volumes and adds them to the library's scratch pool. If a volume has an entry in volume history, you cannot check it in as a scratch volume.
PRIvate: Specifies that the server checks in the volumes and designates them as private. Private volumes are available only when you request them by name.

If you do not specify a value for this parameter, the command labels the volume, but does not check it in. If you do not specify a value for this parameter and you want to check in the volume, you must issue the CHECKIN LIBVOLUME command.

SEARCH

Specifies that the server searches the library for usable volumes to label. This parameter applies to SCSI, 349X, and ACSLS libraries.

The following values are valid:

Yes: Specifies that the server labels only volumes that are stored in the library, unless the volume is already labeled or its bar code cannot be read.
If you specify the LABELSOURCE=PROMPT option, the volume is moved into the drive from its location in the library or entry and exit ports. The server prompts you to issue the REPLY command that contains the label string, and that label is written to the tape.
Bulk: Specifies that the server searches the library entry/exit ports for usable volumes to label. This option is only valid for SCSI libraries.
If you specify LABELSOURCE=BARCODE, the volume bar code is read. Then, the tape is moved from its location in the library or in the entry/exit ports to a drive where the bar code label is written. After the tape is labeled, it is moved back to its location in the library, to the entry/exit ports, or to a storage slot if the CHECKIN option is specified. For bar code support to work correctly for libraries that are supported by Tivoli Storage Manager, the Tivoli Storage Manager server and the device driver must be at the same level. Bar code support is available for libraries that are supported by Tivoli Storage Manager and that use the Tivoli Storage Manager device driver or the IBM® Magstar® or LTO Ultrium device driver.

Tip: You can use the VOLRANGE or VOLLIST parameter to limit the search.

VOLRange

Specifies a range of volume names that are separated by a comma. Use this parameter to limit the search for volumes to be labeled 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.

You can 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 labeled: bar110, bar111, bar112,...bar129, bar130.
`volrange=bar11a,bar13a`	The 3 volumes are labeled: bar11a, bar12a, bar13a.
`volrange=123400,123410`	The 11 volumes are labeled: 123400, 123401, ...123409, 123410.

VOLList

Specifies a list of volumes. Use this parameter to limit the search for volumes to be labeled 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. The VOLLIST parameter can also be the source of names to be used to label volumes if the LABELSOURCE parameter is set to VOLLIST. If LABELSOURCE=VOLLIST, you must specify the VOLLIST parameter.

The following values are valid:

volume_name

Specifies the names of one or more values that are used for the command. 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 volume TAPE01, TAPE02 and TAPE03, create a file that is named TAPEVOL that contains these lines:

TAPE01
TAPE02
TAPE03

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

Remember: The file name is case-sensitive.

LABELSource

Specifies how or whether the server reads sequential media labels of volumes. This option is only valid for SCSI libraries. Specify this parameter only when SEARCH=YES or SEARCH=BULK.

You can specify the following values:

Prompt: The server prompts for volume names as necessary.
Barcode: The server attempts to read the bar code label. If the attempt fails, the server does not label the volume and displays a message.
Important: For bar code support to work properly, the appropriate device drivers must be installed for the libraries.
Vollist: This option applies only to SCSI libraries. The server attempts to read the specified file or list of files. If the attempt fails, the server does not label the volumes and displays a message.

OVERWRITE

Specifies whether the server attempts to overwrite existing labels. This parameter is optional. The default is NO. You can specify the following values:

No: Specifies that the server labels only unlabeled volumes. For StorageTek VolSafe volumes, the value must be NO.
Yes: Specifies that the server overwrites existing labels only if both the existing label and the prompted or bar code label are not already defined in either the server storage pool or volume history list.

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 that 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 wait 60 minutes for you to reply. Alternatively, suppose that you specify a wait time of 0. If you inserted a tape, a wait time of zero causes the operation to continue without prompting. If you did not insert a tape, a wait time of zero causes the operation to fail.

Example: Automatically label library volumes

Label tapes in a SCSI library named AUTO automatically as you are checking in the volumes.

label libvolume auto checkin=scratch search=yes labelsource=barcode
overwrite=yes

Example: Label sequential library volumes

Label 3 volumes from bar11a to bar13a in a SCSI library named ABC. When you issue the following command, the three volumes are labeled: bar11a, bar12a, bar13a.

label libvolume abc checkin=scratch search=yes volrange=bar11a,bar13a 
labelsource=barcode

Related commands

Table 1. Commands related to LABEL 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.
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.
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.