QUERY DRMEDIA (Query disaster recovery media)

Use this command to display information about database backup volumes, and volumes in copy storage pools, container-copy storage pools, and active-data storage pools. You can also use the command to create a file of executable commands to process the volumes.

The processing of volumes by this command depends on what the volumes are used for:

Backups of the server database: To control whether the command processes database backup volumes, use the SOURCE parameter. The command can process volumes that are used for full plus incremental or snapshot database backups. You cannot specify virtual volumes (backup objects that are stored on another server). You can change volumes through each state, or you can use the TOSTATE parameter and skip states to simplify the movements.
Copy storage pools: The QUERY DRMEDIA command always processes eligible copy storage-pool volumes.
Container-copy storage pools: By default, volumes in container-copy storage pools are not eligible for processing by the QUERY DRMEDIA command. To process container-copy storage pool volumes, you must issue the SET DRMCOPYCONTAINERSTGPOOL command first, or specify the COPYCONTAINERSTGPOOL parameter on the QUERY DRMEDIA command.
Active-data storage pools: By default, volumes in active-data storage pools are not eligible for processing by the QUERY DRMEDIA command. To process active-data pool volumes, you must issue the SET DRMACTIVEDATASTGPOOL command first, or specify the ACTIVEDATASTGPOOL parameter on the QUERY DRMEDIA command.

If you are using an external library and moved a volume to the NOTMOUNTBLE state by 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 to follow when you use 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

Parameters

volume_name

Specifies the names of the 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 specified by the COPYSTGPOOL parameter. If you do not use the COPYSTGPOOL parameter, the server queries volumes from copy storage pools that are previously specified by the SET DRMCOPYSTGPOOL command.
Active-data storage pool volumes from active-data storage pools specified by the ACTIVEDATASTGPOOL parameter. If you do not use the ACTIVEDATASTGPOOL parameter, the server queries volumes from active-data storage pools that were previously specified by the SET DRMACTIVEDATASTGPOOL command.
Container-copy storage pool volumes from container-copy storage pools specified by the COPYCONTAINERSTGPOOL parameter. If you do not use the COPYCONTAINERSTGPOOL parameter, the server queries volumes from container-copy storage pools that were previously specified by the SET DRMCOPYCONTAINERSTGPOOL 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 is empty for at least the number of days that are 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 by 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.

REmote

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

COURIERRetrieve

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

ONSITERetrieve

Volumes in this state were retrieved from an offsite vault. The volumes are onsite and can be checked into the library, and the data from the volume can be restored.

RESToreonly

Volumes are checked into the library to enable restoration of data. To ensure that the volume is used only to restore data, the access mode of the volume is read only. When the data is restored and the volume is no longer needed onsite, the volume can be returned to the offsite vault.

BEGINDate

Specifies the beginning date that is used to select volumes. This parameter is optional. Volumes are considered eligible if the MOVE DRMEDIA command 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 by using one of the following values:

Value	Description	Example
MM/DD/YYYY	A specific date	09/15/2019
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 that begin with records that are 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 that is 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 by using one of the following values:

Value	Description	Example
MM/DD/YYYY	A specific date	09/15/2019
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 that begin with records that are 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 that is used to select volumes. This parameter is optional. Volumes are considered eligible if the MOVE DRMEDIA command 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 that is specified with the BEGINDATE parameter.

You can specify the time by 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. The server displays volumes that were changed to their current state at 12:00 on the begin date that 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. The server displays volumes that were changed to their current state at 5:30 on the begin date that you specify.

ENDTime

Specifies the ending time that is used to select volumes. This parameter is optional. Volumes are considered eligible if the MOVE DRMEDIA command 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 by 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, IBM Spectrum® Protect 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, IBM Spectrum Protect 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 that are specified with this parameter override those that are specified with the SET DRMCOPYSTGPOOL command.

If this parameter is not specified, the server selects the storage pools as follows:

If the SET DRMCOPYSTGPOOL command was previously issued with valid copy storage pool names, the server 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 by using the SET DRMCOPYSTGPOOL command, the server 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 storage pools that are specified with this parameter override those specified with the SET DRMACTIVEDATASTGPOOL command.

If this parameter is not specified, the server selects the storage pools as follows:

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

COPYCONtainerstgpool

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

If this parameter is not specified, the server selects the storage pools as follows:

If the SET DRMCOPYCONTAINERSTGPOOL command was previously issued with names of valid container-copy storage pools, the server processes only those storage pools.
If the SET DRMCOPYCONTAINERSTGPOOL command has not been issued, or if all container-copy storage pools were removed by using the SET DRMCOPYCONTAINERSTGPOOL command, the server processes all container-copy pool volumes based on the value that is specified by the WHERESTATE parameter. If the parameter is set to a value of ALL, NOTMOUNTABLE, COURIER, VAULT, VAULTRETRIEVE, COURIERRETRIEVE, or REMOTE, the volumes are processed. If the value is set to MOUNTABLE, the volumes 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 that are located on the target server.

CMd

Specifies the creation of executable commands to process the volume name and location that is 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 might 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 by using the default prefix TSM is TSM.BFS. An example of a database backup tape volume file name by 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, the server creates a file name by appending exec.cmds to the absolute directory path name of the IBM Spectrum Protect instance directory. If you specify a null string (" "), the commands are displayed on the console only. You can redirect the commands to a file by using the redirection character for the operating system.

If the operation fails after the command file is 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, the server creates a file name by appending exec.cmd to the directory that represents this instance of the server (typically the directory where the IBM Spectrum Protect server was originally installed). If you specify a null string (""), the commands are displayed on the console only. You can redirect the commands to a file by using > or >> provided by the system. The disaster recovery manager allocates the file name that is 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 is 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.

VOLSTAtus

Specifies the status of the volume. This parameter is optional. You can enter one of the following values:

Empty: Only empty volumes are processed.
Notempty: Only non-empty volumes are processed.
Full: Only full volumes are processed.

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
Container Copy Storage Pool Name:
               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 Location field is displayed when the volume is not mountable or when it's not in the library. The Location field is empty if the volume is mountable and is in the library.

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.
ContcopyStgPool: A container-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 storage pool volume, the name of the active-data storage pool.

Container-Copy Storage Pool Name

For a container-copy storage pool volume, the name of the container-copy storage 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 IBM Spectrum Protect 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 onsite and offsite.
QUERY DRMSTATUS	Displays DRM system parameters.
SET DRMACTIVEDATASTGPOOL	Specifies that active-data storage pools are managed by DRM.
SET DRMCOPYCONTAINERSTGPOOL	Specifies the container-copy storage pools that are used in DRM commands.
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.