QUERY RETMEDIA (Query tape retention storage pool media)

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

Restriction: The QUERY RETMEDIA command cannot be used on volumes in cloud retention storage pools. This command can be used only on volumes in tape retention storage pools.

By default, the QUERY RETMEDIA command processes all eligible volumes in tape retention storage pools. To process a specific volume in a tape retention storage pool, you must issue the SET DRMRETENTIONSTGPOOL command first, or specify the tape retention storage pool name.

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 name of the volume 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 specified by the SOURCE parameter of this command.
Tape retention storage pool volumes from retention storage pools specified by the RETENTIONSTGPOOL parameter. If you do not use the RETENTIONSTGPOOL parameter, the server queries volumes from tape retention storage pools that were previously specified by the SET DRMRETENTIONSTGPOOL command.

WHEREState

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

All

Includes all volumes in all states.

MOuntable

Includes volumes that contain valid data, are checked into the library, and are accessible for onsite processing.

NOTMOuntable

Includes volumes that are onsite, contain valid data, but are checked out of the library and are not accessible for onsite processing.

COUrier

Includes volumes that are being moved to an offsite location.

VAult

Includes volumes that are offsite, contain valid data, and are not accessible for onsite processing.

VAULTRetrieve

Includes volumes that are at the offsite vault and can be moved back onsite:

A tape retention storage pool volume can be in the VAULTRETRIEVE state if all the data on the volume is expired. The volume can be brought back onsite and restored.
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 that is specified by using the SET DRMDBBACKUPEXPIREDAYS command.

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

COURIERRetrieve

Includes volumes that are in transit to the onsite location.

ONSITERetrieve

Includes volumes that 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

Includes volumes that are checked into the library to enable restoration of retention set data. To ensure that the volume is used only for data restore, its access mode 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.

RETENTIONstgpool

Specifies the name of the tape retention storage pool whose volumes are to be processed. This parameter is optional. You can use wildcard characters to specify this name.

The tape retention storage pools that are specified with the RETENTIONSTGPOOL parameter override the tape retention storage pools that are specified with the SET DRMRETENTIONSTGPOOL command. If this parameter is not specified, the server selects the storage pools as follows:

If the SET DRMRETENTIONSTGPOOL command was previously issued with valid tape retention storage pool names, the server processes only those storage pools.
If the SET DRMRETENTIONSTGPOOL command was not issued, or if all tape retention storage pools were removed by using the SET DRMRETENTIONSTGPOOL command, the server processes all tape retention storage pool volumes based on the value that is specified by the WHERESTATE parameter.

BEGINDate

Specifies the beginning date that is used to select volumes. This parameter is optional. Volumes are considered eligible if the MOVE RETMEDIA 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.	01/15/2020
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 were 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 RETMEDIA command 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 RETMEDIA 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 the QUERY RETMEDIA 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 specified begin date.
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 the QUERY RETMEDIA 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 specified begin date.

ENDTime

Specifies the ending time that is used to select volumes. This parameter is optional. Volumes are considered eligible if the MOVE RETMEDIA 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 the QUERY RETMEDIA command at 9:00 with ENDTIME=NOW+03:00 or ENDTIME=+03:00, the server processes volumes that were changed to their current state at 12:00 on the specified end date.
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 the QUERY RETMEDIA command at 9:00 with ENDTIME=NOW-03:00 or ENDTIME=-03:00, the server processes volumes that were changed to their current state at 6:00 on the specified end date.

Source

Specifies whether any database backup volumes that contain tape retention storage pool volumes are selected. This parameter is optional. The default is DBBACKUP. You can specify one of the following values:

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

Format

Specifies the information to be displayed. This parameter is optional. The default is STANDARD. You can specify one of the following values:

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 on the target server.

CMd

Specifies the creation of executable commands to process the volume and location that are 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 that is specified by the CMDFILENAME parameter or the SET DRMCMDFILENAME command, or generated by the QUERY RETMEDIA command. If the command length is greater than 240 characters, it is split into multiple lines and continuation characters (+) are added. You might have to alter the continuation character, depending on the operating system.

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

string

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

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

The following example is not valid:

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

substitution

Specifies a substitution variable to tell QUERY RETMEDIA to substitute a value for the variable. The variables are not case-sensitive, and must not contain blank spaces after the ampersand (&). You can specify the following values:

&VOL: A volume name variable.
&LOC: A volume location.
&VOLDSN: The name of the file that the server writes into the sequential-access media labels. For example, when you use the default prefix TSM, the file name on a retention storage pool tape volume is TSM.BFS. When you use a prefix of TSM310 on a tape device class that is used for database backups, the file name is TSM310.DBB.
&NL: The new line character. When &NL is specified, QUERY RETMEDIA 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. You can specify the following values:

No: The contents of the file are overwritten.
Yes: The commands are appended to the file.

VOLSTAtus

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

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

Example: Display information about volumes in a vault

Display detailed information about all volumes in a vault.

query retmmedia wherestate=vault format=detailed

               
                     Volume Name: VOL001
                           State: Vault
           Last Update Date/Time: 03/20/2020 14:20:12
                        Location: VAULT
                     Volume Type: Retention
               Storage Pool Name: RETPOOL
               Automated LibName: LIBNAME

See Field descriptions for field descriptions.

Field descriptions

Volume Name

The name of the database backup or tape retention 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 transition volumes to VAULTRETRIEVE. At the time the QUERY RETMEDIA command is issued, the server dynamically determines whether the data in tape retention 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:

Retention: A tape retention storage pool volume.
DBBackup: A full or incremental database backup volume.
DBSnapshot: A database snapshot backup volume.

Storage Pool Name

The name of the tape retention 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 RETMEDIA
Command	Description
MOVE RETMEDIA	Moves tape retention storage pool volumes onsite and offsite.
QUERY DRMSTATUS	Displays DRM system parameters.
SET DRMCHECKLABEL	Specifies whether IBM Spectrum Protect should read volume labels during MOVE DRMEDIA command processing.
SET DRMCOURIERNAME	Specifies the name of the courier for the disaster recovery media.
SET DRMNOTMOUNTABLENAME	Specifies the location name of the DRM media to be sent offsite.
SET DRMRETENTIONSTGPOOL	Specifies the tape retention storage pools to be processed by MOVE RETMEDIA and QUERY RETMEDIA commands.
SET DRMVAULTNAME	Specifies the name of the vault where DRM media is stored.