QUERY MEDIA (Query sequential access storage pool media)

Use this command to display information about the sequential access primary and copy storage pool volumes moved by the MOVE MEDIA command.

Privilege class

Any administrator with system or operator privilege can issue this command unless it includes the CMD parameter. If the CMD parameter is specified and the REQSYSAUTHOUTFILE server option is set to NO, the administrator must have operator, unrestricted storage, or system privilege. If the CMD parameter is specified and the REQSYSAUTHOUTFILE server option is set to YES (the default), the administrator must have system privilege.

Syntax


                .-*-----------.                          
>>-Query MEDia--+-------------+--STGpool--=--pool_name---------->
                '-volume_name-'                          

   .-Days--=--0----.                                        
>--+---------------+--+---------------------------------+------->
   '-Days--=--days-'  |                 .-,-----------. |   
                      |                 V             | |   
                      '-WHERESTATUs--=----+-FULl----+-+-'   
                                          +-FILling-+       
                                          '-EMPty---'       

>--+-------------------------------+---------------------------->
   '-WHEREACCess--=--+-READWrite-+-'   
                     '-READOnly--'     

   .-Format--=--Standard-----.   
>--+-------------------------+---------------------------------->
   '-Format--=--+-Standard-+-'   
                +-Detailed-+     
                '-Cmd------'     

>--+--------------------------------------+--------------------->
   '-WHERESTate--=--+-All---------------+-'   
                    +-MOUNTABLEInlib----+     
                    '-MOUNTABLENotinlib-'     

>--+-------------------------------+--+-------------------+----->
   '-WHEREOVFLOcation--=--location-'  '-CMd--=--"command"-'   

                                  .-APPend--=--No------.   
>--+---------------------------+--+--------------------+-------><
   '-CMDFilename--=--file_name-'  '-APPend--=--+-No--+-'   
                                               '-Yes-'

Parameters

volume_name

Specifies the name of the sequential access primary or copy storage pool volume to display. This parameter is optional. You can use a wildcard character to specify the name. All matching volumes are considered for processing. If you do not specify this parameter, all volumes defined in the storage pool specified with the STGPOOL parameter display.

STGpool (Required)

Specifies the name of the sequential access primary or copy storage pool that is used to select the volumes for processing. You can use wildcard characters to specify the name. All matching storage pools are processed. If the storage pool specified is not managed by an automated library, no volumes display.

Days

Specifies the number of days that must elapse, after the volume has been written to or read from, before the volume is eligible for processing. This parameter is optional. You can specify a number from 0 to 9999. The default value is 0. The most recent of the volume's last written date or last read date is used to calculate the number of days elapsed.

WHERESTATUs

Specifies that the output of the query should be restricted by volume status. This parameter is optional. You can specify more than one status in a list by separating each status with a comma and no intervening spaces. If you do not specify a value for this parameter, all volumes in the specified storage pool, regardless of their status, are displayed.

Possible values are:

FULl: Specifies that volumes with a status of FULL display.
FILling: Specifies that volumes with a status of FILLING display.
EMPty: Specifies that volumes with a status of EMPTY display.

WHEREACCess

Specifies that output should be restricted by volume access mode. This parameter is optional. If you do not specify a value for this parameter, output is not restricted by access mode.

Possible values are:

READWrite: Specifies that volumes with an access mode of READWRITE display.
READOnly: Specifies that volumes with an access mode of READONLY display.

Format

Specifies how information displays. This parameter is optional. The default value is STANDARD. Possible values are:

Standard: Specifies that partial information displays for the specified sequential access storage pool volumes.
Detailed: Specifies that complete information displays for the specified sequential access storage pool volumes.
Cmd: Specifies that executable commands are built for the storage pool volumes processed by the QUERY MEDIA command. These commands will be in the file specified with the CMDFILENAME parameter on the QUERY MEDIA command. If you want the commands to display on the console only, specify a null string ("") for the CMDFILENAME. If FORMAT=CMD is specified but no command string is specified with the CMD parameter, the QUERY MEDIA command will fail.

WHEREState

Specifies the state of volumes to process. This parameter restricts processing to volumes that have the specified state. This parameter is optional. The default is ALL. Possible values are:

All: Specifies that volumes in all states are queried. The valid states are: MOUNTABLEINLIB and MOUNTABLENOTINLIB.
MOUNTABLEInlib: Specifies that volumes that are currently in the MOUNTABLEINLIB state are queried. Volumes in the MOUNTABLEINLIB state are in the library, and are onsite, contain valid data, and are available for onsite processing.
MOUNTABLENotinlib: Specifies that volumes that are currently in the MOUNTABLENOTINLIB state are queried. Volumes in the MOUNTABLENOTINLIB state are not in the library, do not contain valid data, and are not available for onsite processing.

WHEREOVFLOcation

Specifies the overflow location of the volumes to display. This parameter is optional. This parameter restricts processing to volumes that are in the specified location. The maximum length of the location is 255 characters. The location must be enclosed in quotation marks if it contains any blank characters.

CMd

Specifies the creation of executable commands. Enclose the command specification in quotation marks. The maximum length of the command specification is 255 characters. This parameter is optional.

For each volume successfully processed by the QUERY MEDIA command, the server writes the associated commands to a file. Specify the file name with the CMDFILENAME parameter.

AIX operating systems HP-UX operating systems Linux operating systems Oracle Solaris operating systems If you do not specify a filename, the command will generate a default filename by appending the string exec.cmds.media to the server directory.

Windows operating systems If you do not specify a filename, the command will generate a default filename by appending the string exec.cmd.media to the server directory.

Remember:

If the command written to the file exceeds 255 characters, it is split into multiple lines, and a continuation character (+) is added to all but the last line. You may need to alter the continuation character according to the requirements of the product that runs the commands.
If an executable command is specified with any value for FORMAT other than CMD, the command string is ignored, and the QUERY MEDIA command will not write any command line.

Specify a command string and any substitution variables:

string

Specifies the string to build an executable command to process the volume name or volume location or both. You can specify any free form text for the string. Do not use embedded quotation marks. For example, the following is a valid executable command specification:

cmd="checkin libvolume &vol"

The following is an invalid executable command specification:

cmd="checkin libvolume "&vol""

substitution

Specifies a variable for which you want the QUERY MEDIA command to substitute a value. The possible substitution variables are:

&VOL: Substitute the volume name for &VOL. You can specify lowercase characters, &vol. No spaces or blanks are allowed between ampersand, &, and VOL. If there are spaces or blanks between ampersand and VOL, the QUERY MEDIA command will treat them as strings and no substitution will be set. If &VOL is not specified, no volume name is set in the executable command.
&LOC: Substitute the volume location for &LOC. You can specify lowercase characters, &loc. No spaces or blanks are allowed between ampersand, &, and LOC. If there are spaces or blanks between ampersand and LOC, the QUERY MEDIA command will treat them as strings and no substitution will be set. If &LOC is not specified, no location name is set in the executable command.
&VOLDSN: Substitute the volume file name for &VOLDSN. An example of a copy storage pool tape volume file name using the defined prefix IBM® Tivoli® Storage Manager310 is IBM Tivoli Storage Manager310.BFS. If &VOLDSN is not specified, no volume file name is set in the executable command.
&NL: Substitute the new line character for &NL. When &NL is specified, the QUERY MEDIA command will split the command at the position where the &NL is and will not append any continuation character. The user is responsible for specifying the proper continuation character before the &NL if one is required. The user is also responsible for the length of the line written. If the &NL is not specified and the command exceeds 255 characters, the command is split into multiple lines, and a continuation character (+) is added to all but the last line.

CMDFilename

Specifies the full path name that will contain the commands specified with CMD parameter when FORMAT=CMD is specified. This parameter is optional. The maximum length of the file name is 1279 characters.

AIX operating systems HP-UX operating systems Linux operating systems Oracle Solaris operating systems If you specify "" with the CMDFILENAME parameter, the QUERY MEDIA command will generate a file name by appending the "exec.cmds.media" to the server directory. The server directory is the current working directory of the server process.

Windows operating systems If you specify "" with the CMDFILENAME parameter, the QUERY MEDIA command will generate a file name by appending the "exec.cmd.media" to the server directory. The server directory is the current working directory of the server process.

If you specify a null string ("") for the CMDFILENAME, the commands built are displayed on the console only. You can redirect the commands displayed to a file by using the redirection characters for the operating system (> or >>).

AIX operating systems HP-UX operating systems Linux operating systems Oracle Solaris operating systems If the filename is not specified, the command will generate a default filename by appending the string "exec.cmds.media" to the server directory.

Windows operating systems If the filename is not specified, the command will generate a default filename by appending the string "exec.cmd.media" to the server directory.

The QUERY MEDIA command automatically allocates the file name specified or generated. If the file name exists, the QUERY MEDIA command will attempt to use it and the existing data, if any, in the file to be overwritten. You can specify APPEND=YES to prevent the existing data from being overwritten. If the QUERY MEDIA command fails after the command file is allocated, the file is not deleted.

APPend

Specifies to write at the beginning or the ending of the command file data. This parameter is optional. The default is NO. Possible values are:

No: Specifies to write the data from the beginning of the command file. If the given command file exists, its contents are overwritten.
Yes: Specifies to append the command file by writing at the end of the command file data.

Example: Display information on a specific sequential access storage pool

Display all full and partial full volumes that are in the sequential access primary storage pool, ARCHIVE. See Field descriptions for field descriptions.

query media * stgpool=archive wherestatus=full, filling

 
Volume Name State                 Location              Automated
                                                        LibName
----------- -------------------   --------------------  -----------
TAPE01      Mountable in Library                        LIB3494
TAPE03      Mountable not in Lib. Room1234/Bldg31
TAPE07      Mountable in Library                        LIB3494
TAPE09      Mountable not in Lib. Room1234/Bldg31

Example: Display information on sequential access storage pool with a specific prefix

Display in detail all full volumes in MOUNTABLENOTINLIB state for sequential access storage pools that have a prefix name of ONSITE. See Field descriptions for field descriptions.

query media wherestate=mountablenotinlib stgpool=onsite* 
wherestatus=full format=detailed

            Volume Name: TAPE21
                  State: Mountable not in library
                 Status: Full
                 Access: ReadOnly
    Last Reference Date: 01/30/98
  Last Update Date/Time: 08/20/1996 13:29:02
               Location: Rm569/bldg31
      Storage Pool Name: ONSITE.ARCHIVE
      Automated Libname:
 
            Volume Name: TAPE22
                  State: Mountable not in library
                 Status: Full
                 Access: ReadOnly
    Last Reference Date: 01/30/98
  Last Update Date/Time: 08/20/1996 15:29:02
               Location: Rm569/bldg31
      Storage Pool Name: ONSITE.ARCHIVEPOOL
      Automated Libname:

Example: Generate checkin commands

Generate the CHECKIN LIBVOLUME commands for full and partially full volumes that are in the ONSITE.ARCHIVE primary storage pool and stored in the overflow location Room 2948/Bldg31.

query media * stgpool=onsite.archive format=cmd
wherestatus=full,filling wherestate=mountablenotinlib
whereovflocation=room2948/bldg31 
cmd="checkin libvol lib3494 &vol status=private" 
cmdfilename=/tsm/move/media/checkin.vols

The QUERY MEDIA command created the CHECKIN LIBVOLUME executable commands in /tsm/move/media/checkin.vols, which can be run by issuing the MACRO command with /tsm/move/media/checkin.vols as the macro name.

checkin libvol lib3494 TAPE04 status=private
checkin libvol lib3494 TAPE13 status=private
checkin libvol lib3494 TAPE14 status=private

Field descriptions

Volume Name: Specifies the name of the primary sequential access storage pool volume.
State: Specifies the state of the volume.
Status: Specifies the status of the volume.
Access: Specifies the access mode of the volume.
Last Reference Date: Specifies the volume's last written date or last read date, whichever is more recent.
Last Update Date/Time: Specifies the date and time when the volume was most recently updated.
Location: Specifies where the volume is stored. If the volume is ejected from the library and its location is not specified or defined, a question mark (?) is displayed for the location.
Storage Pool Name: Specifies the name of the sequential access storage pool where the volume is defined.
Automated LibName: Specifies the automated library name if the volume is in the library.

Related commands

Table 1. Commands related to QUERY MEDIA
Command	Description
MOVE MEDIA	Moves storage pool volumes that are managed by an automated library.