IBM Tivoli Storage Manager Extended Edition, Version 7.1

QUERY DRMEDIA (Query disaster recovery media)

Use this command to display information about database backup and copy storage pool volumes. You can also use the command to create a file of executable commands to process the volumes.

Remember: The QUERY DRMEDIA command always processes eligible copy storage-pool volumes. (For details about eligible copy storage pool volumes, see the description of the COPYSTGPOOL parameter in this command). By default, volumes in active-data pools are not eligible for processing by the disaster recovery manager. To process active-data pool volumes, you must issue the SET DRMACTIVEDATASTGPOOL command, or you must use the ACTIVEDATASTGPOOL parameter on the QUERY DRMEDIA command. Depending on the setting for the SOURCE parameter in this command, database backups (full and incremental types, or snapshot types) can also be processed. The other parameters of the command (such as WHERESTATE) can further limit the results of the query.

If you are using an external library and have moved a volume to the NOTMOUNTBLE state using the MOVE DRMEDIA command, the QUERY DRMEDIA command might still report the volume state as MOUNTABLE if it detects that the volume is in the library. Refer to the external library documentation for information about the procedures that you should follow when using the MOVE DRMEDIA and the QUERY DRMEDIA commands.

Privilege class

To issue this command, you must have one of the following privilege classes:

If the CMD parameter is NOT specified: operator or system privilege.
If the CMD parameter is specified and the REQSYSAUTHOUTFILE server option is set to NO: operator, unrestricted storage, or system privilege.
If the CMD parameter is specified and the REQSYSAUTHOUTFILE server option is set to YES (the default): system privilege.

Syntax


                  .-*-----------.   
>>-Query DRMedia--+-------------+------------------------------->
                  '-volume_name-'   

   .-WHERESTate--=--All-----------------.   
>--+------------------------------------+----------------------->
   '-WHERESTate--=--+-----------------+-'   
                    +-All-------------+     
                    +-MOuntable-------+     
                    +-NOTMOuntable----+     
                    +-COUrier---------+     
                    +-VAult-----------+     
                    +-VAULTRetrieve---+     
                    +-COURIERRetrieve-+     
                    '-REmote----------'     

>--+--------------------+--+------------------+----------------->
   '-BEGINDate--=--date-'  '-ENDDate--=--date-'   

>--+--------------------+--+------------------+----------------->
   '-BEGINTime--=--time-'  '-ENDTime--=--time-'   

>--+---------------------------+-------------------------------->
   '-COPYstgpool--=--pool_name-'   

>--+---------------------------------+-------------------------->
   '-ACTIVEDatastgpool--=--pool_name-'   

   .-Source--=--DBBackup-------.  .-Format--=--Standard-----.   
>--+---------------------------+--+-------------------------+--->
   '-Source--=--+-DBBackup---+-'  '-Format--=--+-Standard-+-'   
                +-DBSnapshot-+                 +-Detailed-+     
                '-DBNone-----'                 '-Cmd------'     

>--+----------------------------+--+-----------------------+---->
   '-WHERELOCation--=--location-'  |         .-----------. |   
                                   |         V           | |   
                                   '-CMd--=----"command"-+-'   

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

Parameters

volume_name

Specifies the names of the database backup and copy storage pool volumes to be queried. You can use wildcard characters to specify multiple names. This parameter is optional. The server looks for matching names among the following eligible volumes:

Database backup volumes, as selected by the SOURCE parameter of this command.
Copy storage pool volumes from copy storage pools named in the COPYSTGPOOL parameter. If you do not use the COPYSTGPOOL parameter, the server queries volumes from copy storage pools previously selected by the SET DRMCOPYSTGPOOL command.

Other parameters can also limit the results of the query.

WHEREState

Specifies the state of volumes to be processed. This parameter is optional. The default is ALL. Possible values are:

All

Specifies all volumes in all states.

MOuntable

Volumes in this state contain valid data and are accessible for onsite processing.

NOTMOuntable

Volumes in this state are onsite, contain valid data, and not accessible for onsite processing.

COUrier

Volumes in this state are being moved to an offsite location.

VAult

Volumes in this state are offsite, contain valid data, and are not accessible for onsite processing.

VAULTRetrieve

Volumes in this state are located at the offsite vault, do not contain valid data and can be moved back onsite for reuse or disposal:

A copy storage pool volume is considered to be in the VAULTRETRIEVE state if it has been empty for at least the number of days specified with the REUSEDELAY parameter on the DEFINE STGPOOL command.
A database backup volume is considered to be in the VAULTRETRIEVE state if it is associated with a database backup series that was expired based on the value specified using the SET DRMDBBACKUPEXPIREDAYS command.

Important: When you issue QUERY DRMEDIA WHERESTATE=VAULTRETRIEVE, the server dynamically determines which volumes can be moved back onsite for reuse or disposal. Therefore, to ensure that you identify all volumes that are in a VAULTRETRIEVE state, issue QUERY DRMEDIA WHERESTATE=VAULTRETRIEVE without the BEGINDATE, ENDDATE, BEGINTIME or ENDTIME parameters. The Last Update Date/Time field in the output for QUERY DRMEDIA WHERESTATE=VAULTRETRIEVE displays the date and time that a volume was moved to the VAULT state, not VAULTRETRIEVE.

COURIERRetrieve

Volumes in this state are being moved back to the onsite location.

REmote

Volumes in this state contain valid data and are located at the offsite remote server.

BEGINDate

Specifies the beginning date used to select volumes. This parameter is optional. Volumes are considered eligible if the MOVE DRMEDIA command has changed the volume to its current state on or after the specified date. The default is the earliest date for which volume information exists.

You can specify the date using one of the following values:

Value	Description	Example
MM/DD/YYYY	A specific date	09/15/1998
TODAY	The current date	TODAY
TODAY-days or -days	The current date minus days specified. The maximum number of days is 9999.	TODAY"7 or "7. To query volumes beginning with records changed to their current state a week ago, you can specify BEGINDATE=TODAY-7 or BEGINDATE=-7.
EOLM (End Of Last Month)	The last day of the previous month.	EOLM
EOLM-days	The last day of the previous month minus days specified.	EOLM-1 To include files that were active a day before the last day of the previous month.
BOTM (Beginning Of This Month)	The first day of the current month.	BOTM
BOTM+days	The first day of the current month, plus days specified.	BOTM+9 To include files that were active on the 10th day of the current month.

ENDDate

Specifies the ending date used to select volumes. This parameter is optional. Volumes are considered eligible if the MOVE DRMEDIA command has changed the volume to its current state on or before the specified date. The default is the current date.

You can specify the date using one of the following values:

Value	Description	Example
MM/DD/YYYY	A specific date	09/15/1998
TODAY	The current date	TODAY
TODAY-days or -days	The current date minus days specified. The maximum number of days is 9999.	TODAY"7 or "7. To query volumes beginning with records changed to their current state a week ago, you can specify BEGINDATE=TODAY-7 or BEGINDATE=-7.
EOLM (End Of Last Month)	The last day of the previous month.	EOLM
EOLM-days	The last day of the previous month minus days specified.	EOLM-1 To include files that were active a day before the last day of the previous month.
BOTM (Beginning Of This Month)	The first day of the current month.	BOTM
BOTM+days	The first day of the current month, plus days specified.	BOTM+9 To include files that were active on the 10th day of the current month.

BEGINTime

Specifies the beginning time used to select volumes. This parameter is optional. Volumes are considered eligible if the MOVE DRMEDIA command has changed the volume to its current state on or after the specified time and date. The default is midnight (00:00:00) on the date specified with the BEGINDATE parameter.

You can specify the time using one of the following values:

Value	Description	Example
HH:MM:SS	A specific time on the specified begin date	12:33:28
NOW	The current time on the specified begin date	NOW
NOW+HH:MM or +HH:MM	The current time plus hours and minutes on the specified begin date	NOW+03:00 or +03:00. If you issue QUERY DRMEDIA command at 9:00 with BEGINTIME=NOW+03:00 or BEGINTIME=+03:00. Tivoli® Storage Manager displays volumes that were changed to their current state at 12:00 on the begin date you specify.
NOW-HH:MM or -HH:MM	The current time minus hours and minutes on the specified begin date	NOW-03:30 or -03:30. If you issue QUERY DRMEDIA command at 9:00 with BEGINTIME=NOW-03:30 or BEGINTIME=-03:30. Tivoli Storage Manager displays volumes that were changed to their current state at 5:30 on the begin date you specify.

ENDTime

Specifies the ending time used to select volumes. This parameter is optional. Volumes are considered eligible if the MOVE DRMEDIA command has changed the volume to its current state on or before the specified time and date. The default is 23:59:59.

You can specify the time using one of the following values:

Value	Description	Example
HH:MM:SS	A specific time on the specified end date	10:30:08
NOW	The current time on the specified end date	NOW
NOW+HH:MM or +HH:MM	The current time plus hours and minutes on the specified end date	NOW+03:00 or +03:00. If you issue QUERY DRMEDIA command at 9:00 with ENDTIME=NOW+03:00 or ENDTIME=+03:00, Tivoli Storage Manager processes volumes that were changed to their current state at 12:00 on the end date you specify.
NOW-HH:MM or -HH:MM	The current time minus hours and minutes on the specified end date	NOW-03:30 or -03:30 If you issue QUERY DRMEDIA command at 9:00 with ENDTIME=NOW-03:00 or ENDTIME=-03:00, Tivoli Storage Manager processes volumes that were changed to their current state at 6:00 on the end date you specify.

COPYstgpool

Specifies the name of the copy storage pool whose volumes are to be processed. This parameter is optional. You can use wildcard characters to specify this name. The copy storage pools specified with this parameter override those specified with the SET DRMCOPYSTGPOOL command.

If this parameter is not specified, Tivoli Storage Manager selects the storage pools as follows:

If the SET DRMCOPYSTGPOOL command was previously issued with valid copy storage pool names, Tivoli Storage Manager processes only those storage pools.
If the SET DRMCOPYSTGPOOL command has not been issued, or if all of the copy storage pools have been removed using the SET DRMCOPYSTGPOOL command, Tivoli Storage Manager processes all copy storage pool volumes in the specified state (ALL, MOUNTABLE, NOTMOUNTABLE, COURIER, VAULT, VAULTRETRIEVE, COURIERRETRIEVE, or REMOTE).

Source

Specifies whether any database backup volumes are selected. This parameter is optional. The default is DBBACKUP. Possible values are:

DBBackup: Full and incremental database backup volumes are selected.
DBSnapshot: Snapshot database backup volumes are selected.
DBNone: No database backup volumes are selected.

ACTIVEDatastgpool

Specifies the name of the active-data storage pool whose volumes are to be processed. This parameter is optional. You can use wildcard characters to specify this name. The active-data pools that are specified with this parameter override those specified with the SET DRMACTIVEDATASTGPOOL command.

If this parameter is not specified, Tivoli Storage Manager selects the storage pools as follows:

If the SET ACTIVEDATASTGPOOL command was previously issued with valid active-data pool names, Tivoli Storage Manager processes only those storage pools.
If the SET ACTIVEDATASTGPOOL command has not been issued, or all of the active-data pools have been removed using the SET ACTIVEDATASTGPOOL command, Tivoli Storage Manager processes all active-data pool volumes in the specified state (ALL, NOTMOUNTABLE, COURIER, VAULT, VAULTRETRIEVE, COURIERRETRIEVE, or REMOTE). Volumes in the MOUNTABLE state are not processed.

Format

Specifies the information to be displayed. This parameter is optional. The default is STANDARD. Possible values are:

Standard: Specifies that partial information is displayed.
Detailed: Specifies that detailed information is displayed.
Cmd: Specifies that executable commands are built for the selected volumes. If you specify FORMAT=CMD, you must also specify the CMD parameter.

WHERELOcation

Specifies the location of the volumes to be queried. This parameter is optional. The maximum length of the location is 255 characters. Enclose the text in quotation marks if it contains any blank characters. If you specify a target server name, the disaster recovery manager displays all database backup volumes and copy storage pool volumes located on the target server.

CMd

Specifies the creation of executable commands to process the volume name and location obtained by this command. This parameter is optional. You must enclose the command specification in quotation marks. The maximum length of this parameter is 255 characters. The disaster recovery manager writes the commands to a file specified by the CMDFILENAME parameter or the SET DRMCMDFILENAME command, or generated by the QUERY DRMEDIA command. If the command length is greater than 240 characters, it is split into multiple lines and continuation characters (+) are added. You may need to alter the continuation character according to the product that runs the commands.

If you do not specify the FORMAT=CMD parameter, this command will not create any command lines.

string

The command string. The string must not include embedded quotation marks. For example, this is a valid CMD parameter:

cmd="checkin libvol lib8mm &vol status=scratch"

This is an example of a CMD parameter that is not valid:

cmd=""checkin libvolume lib8mm" &vol status=scratch""

substitution

Specifies a substitution variable to tell QUERY DRMEDIA to substitute a value for the variable. The variables are not case-sensitive, and must not contain blank spaces after the ampersand (&). The possible variables are:

&VOL: A volume name variable.
&LOC: A volume location.
&VOLDSN: The name of the file the server writes into the sequential access media labels. An example of a copy storage pool tape volume file name using the default prefix TSM is TSM.BFS. An example of a database backup tape volume file name using a prefix TSM310 defined with the device class is TSM310.DBB.
&NL: The new line character. When &NL is specified, QUERY DRMEDIA command splits the command at the &NL variable and does not append a continuation character. You must specify the proper continuation character before the &NL if one is required. If the &NL is not specified and the command line is greater than 240 characters, the line is split into multiple lines and continuation characters (+) are added.

CMDFilename

Specifies the fully qualified name of the file to contain the commands specified with CMD parameter. This parameter is optional.

If you do not specify a name with the SET DRMCMDFILENAME command, Tivoli Storage Manager creates a file name by appending exec.cmds to the absolute directory path name of the Tivoli Storage Manager instance directory. If you specify a null string (" ") the commands are displayed on the console only. You can redirect the commands to a file using the redirection character for the operating system.

If the operation fails after the command file has been created, the file is not deleted.

CMDFilename

Specifies the fully qualified name of the file to contain the commands specified with CMD parameter. This parameter is optional.

If you do not specify a file name with the SET DRMCMDFILENAME command, Tivoli Storage Manager creates a file name by appending exec.cmd to the directory representing this instance of the Tivoli Storage Manager server (typically the directory that the Tivoli Storage Manager server was originally installed from). If you specify a null string ("") , the commands are displayed on the console only. You can redirect the commands to a file using > or >> provided by the system. The disaster recovery manager allocates the file name specified or generated. If the file exists, the disaster recovery manager tries to use it and any existing data is overwritten.

If the operation fails after the command file has been created, the file is not deleted.

APPend

Specifies whether to overwrite any existing contents of the command file or append the commands to the file. This parameter is optional. The default is NO. Possible values are:

No: The disaster recovery manager overwrites the contents of the file.
Yes: The disaster recovery manager appends the commands to the file.

Example: List volumes to be sent to offsite storage

Display all volumes to be given to a courier for offsite storage.

query drmedia wherestate=notmountable 
format=standard

Volume Name      State           Last Update           Automated
                                 Date/Time             LibName
---------------  --------------  --------------------  ---------
TAPE01           Not mountable    01/20/1998 14:25:22
DBTP01           Not mountable    01/20/1998 14:25:22
DBTP03           Not mountable    01/20/1998 14:31:53

See Field descriptions for field descriptions.

Example: Display information on volumes at the vault

Display detailed information about all volumes at the vault.

query drmedia wherestate=vault format=detailed

                     Volume Name: DBTP02
                           State: Vault
           Last Update Date/Time: 01/20/1998 13:29:02
                        Location: Ironmnt
                     Volume Type: DBBackup
          Copy Storage Pool Name:
   Active-Data Storage Pool Name: TSMACTIVEPOOL
               Automated LibName:

See Field descriptions for field descriptions.

Field descriptions

Volume Name

The name of the database backup or copy storage pool volume.

State

The state of the volume.

Last Update Date/Time

The date and time that the volume state was last updated. For volumes in the VAULTRETRIEVE state, this field displays the date and time that a volume was moved to the VAULT state, not VAULTRETRIEVE. The server does not "update" volumes to VAULTRETRIEVE. At the time the QUERY DRMEDIA command is issued, the server dynamically determines whether the data in copy storage pool volumes and database backup volumes is no longer valid and whether the volume can be brought back onsite for reuse or disposal.

Location

The volume location.

Volume Type

The type of volume. Possible values are:

DBBackup: A full or incremental database backup volume.
DBSnapshot: A database snapshot backup volume.
CopyStgPool: A copy storage pool volume.

Copy Storage Pool Name

For a copy storage pool volume, the name of the copy storage pool.

Active-Data Storage Pool Name

For an active-data pool volume, the name of the active-data pool.

Automated LibName

The name of the automated library if the volume is in a library.

Related commands

Table 1. Commands related to QUERY DRMEDIA
Command	Description
BACKUP DB	Backs up the Tivoli Storage Manager database to sequential access volumes.
BACKUP STGPOOL	Backs up a primary storage pool to a copy storage pool.
CHECKOUT LIBVOLUME	Checks a storage volume out of an automated library.
MOVE DRMEDIA	Moves DRM media on-site and off-site.
SET DRMACTIVEDATASTGPOOL	Specifies that active-data storage pools are managed by DRM.
SET DRMCOPYSTGPOOL	Specifies that copy storage pools are managed by DRM.
SET DRMDBBACKUPEXPIREDAYS	Specifies criteria for database backup series expiration.
SET DRMCMDFILENAME	Specifies a file name for containing DRM executable commands.
SET DRMFILEPROCESS	Specifies whether the MOVE DRMEDIA or QUERY DRMEDIA command processes files associated with a device type of file.

Feedback