Tivoli Storage Manager for Windows: Administrator's Reference

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 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--=--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 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. 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.

Notes:

  1. If the length of a command written to the file exceeds 255 characters, the command is split into multiple lines and a continuation character, +, is added to all but the last line of the command. You may need to alter the continuation character according to the requirements of the product that executes the commands.

  2. If an executable command string is specified with any value for FORMAT other than CMD, the executable command string specification is ignored and the QUERY MEDIA command will not write any executable 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 LIBVOL &VOL"

The following is an invalid executable command specification:

        CMD=""CHECKIN LIBVOL" &VOL"

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

&VOL
Specifies to 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
Specifies to 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
Specifies to substitute the volume file name for &VOLDSN. An example of a copy storage pool tape volume file name using the defined prefix TSM310 is TSM310.BFS. If &VOLDSN is not specified, no volume file name is set in the executable command.

&NL
Specifies to 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 length of the command line exceeds 255, the command line is split into multiple lines and a continuation character, +, is added to all but the last line of the command.

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. 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 determined in the following order:
  1. If defined, the directory pointed to by the DSMSERV_DIR environment variable.
  2. If the DSMSERV_DIR environment variable is not defined, 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. If desired, you can redirect the commands displayed to a file using the redirection characters for the operating system (> or >>).

If the filename is not specified, the command will generate a default filename by appending the string "exec.cmds.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.

Examples

Task 1

Display all full and partial full volumes that are in the ARCHIVE sequential access primary storage pool.

Command:
query media * stgpool=archive 
wherestatus=full, filling

Output:
 
+--------------------------------------------------------------------------------+
|                                                                                |
|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                               |
+--------------------------------------------------------------------------------+

See Task 2 for parameter definitions.

Task 2

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

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

Output:
 
+--------------------------------------------------------------------------------+
|            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:                                                        |
|                                                                                |
+--------------------------------------------------------------------------------+

where:

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 out of the library and its location is not specified or defined, a question mark (?) will be 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.

Task 3

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.

Command:
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

Output:
QUERY MEDIA created the executable commands in /TSM/move/media/checkin.vols:

+--------------------------------------------------------------------------------+
|------------------------------------------------------------------              |
|checkin libvol lib3494 TAPE04 status=private                                    |
|checkin libvol lib3494 TAPE13 status=private                                    |
|checkin libvol lib3494 TAPE14 status=private                                    |
|      ------------------------------------------------------------------        |
+--------------------------------------------------------------------------------+
Note:
Run the CHECKIN LIBVOLUME commands by issuing the TSM MACRO command with /TSM/move/media/checkin.vols as the macro name.

Related Commands

Table 193. Commands Related to QUERY MEDIA

Command Description
MOVE MEDIA Moves storage pool volumes that are managed by an automated library.


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]