Tivoli Storage Manager for Windows: Administrator's Reference
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:
- 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.
- 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:
- If defined, the directory pointed to by the DSMSERV_DIR environment
variable.
- 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 ]