QUERY RETSET (Query a retention set)

Use this command to display information about one or more retention sets and their attributes. You can specify a single retention set ID or filter the retention sets by entering one or more retention set attributes.

Privilege class

Any administrator can issue this command.

Syntax

Parameters

retset_id

Specifies the ID of a retention set that you want to query. The retention set ID is a unique numeric value. This parameter is optional. If you specify a retention set ID, only that retention set is considered during query processing and you do not have to specify any other parameters. If you do not specify a retention set ID, all retention sets are queried.

NOdename

Specifies a node or node group. Use this parameter to limit the display of retention sets to those that match a single node or node group, or to nodes that match a node pattern specified with wildcards (such as asterisks). This parameter is optional.

FIlespace

Specifies the name of a file space or file spaces on a virtual machine to be queried. This parameter is optional. The filespace name can include wildcard characters if the NAMETYPE and the CODETYPE parameters are not specified. To specify a file space that contains a comma in the name, you must specify the file space numerical ID and then specify NAMETYPE=FSID. For example, if the filespace name is 2, specify filespace=2 nametype=fsid.

Tip: Issue the QUERY FILESPACE command to determine which file spaces and file space IDs are defined for a node on the server.

NAMEType

Specifies how you want the server to interpret the file space name that you enter. This parameter is useful when the server has clients with support for Unicode. You can use this parameter for Unicode-enabled IBM Spectrum® Protect clients with Windows, Macintosh OS X, and NetWare operating systems. This parameter is optional.

The default value is SERVER. If a virtual file space mapping name is specified, you must use SERVER. You can specify one of the following values:

SERVER: The server uses the server's code page to interpret the file space name.
UNIcode: The server converts the file space name that is entered from the server code page to the UTF-8 code page. The success of the conversion depends on the characters in the name and the server's code page. Conversion can fail if the string includes characters that are not available in the server code page, or if the server cannot access system conversion routines.
FSID: The server interprets the file space name as the file space ID (FSID).

CODEType

Specifies the type of file spaces to be included in node processing. The default value is BOTH, meaning that file spaces are included regardless of code page type. Use this parameter only when you enter a single wildcard character for the file space name. This parameter is optional. You can specify one of the following values:

UNIcode: Specifies only file spaces that are in Unicode.
NONUNIcode: Specifies only file spaces that are not in Unicode.
BOTH: Specifies all file spaces regardless of code page type.

RETRulename

Specifies the name of the retention rule that triggered the creation of the retention set. This parameter is optional. Use the RETRULENAME parameter to limit the display of retention sets to those that are created by this retention rule. If you have renamed the retention rule, all retention sets that were created with the previous name also match. If you do not specify this parameter, the query output can include all retention rules.

State

Specifies the state of retention sets to be queried. Use the STATE parameter to limit the display of retention sets to those that are in a particular state. This parameter is optional. The default value is ANY. You can specify one of the following values:

ANy: Specifies that retention sets in all states are queried.
ACtive: Specifies that retention sets that are in ACTIVE state are queried. When a retention set is created, it is automatically in ACTIVE state.
Deleted: Specifies that retention sets that are in DELETED state are queried. A retention set that is in DELETED state does not contain files because all files are deleted already.
To provide an audit trail that you can use to track deletions, a record of each deleted retention set (along with its full activity log) is retained based on activity log retention settings.
Expired: Specifies that retention sets in EXPIRED state are queried. A retention set is expired after expiration processing runs and determines that the expiration date of the retention set is passed.
To provide an audit trail that you can use to track expirations, a record of each expired retention set (along with its full activity log) is retained based on activity log retention settings.
COPIed: Specifies that retention sets that are in a COPIED state are queried. A retention set is in a COPIED state after it is copied successfully to tape storage.
To provide an audit trail, a record of each retention set that is copied to tape (along with its full activity log) is retained based on activity log retention settings.
Incomplete: Specifies that retention sets in an INCOMPLETE state are queried. A retention set is incomplete after an operation to copy the retention set to tape is terminated. The retention set that is on the tape device is not complete as all the relevant files have not been copied successfully and are therefore not included in the retention set.
To provide an audit trail, a record of each incomplete retention set (along with its full activity log) is retained based on activity log retention settings.
COPYing: Specifies that retention sets in a COPYING state are queried. A retention set is in a COPYING state during an operation to copy the retention set to tape storage.
Tip: A retention set remains in a COPYING state until the state transitions to either a COPIED state or an INCOMPLETE state.
To provide an audit trail, a record of each retention set that is in the process of being copied to tape (along with its full activity log) is retained based on activity log retention settings.

PITBEGINDate

Specifies the beginning date in a range of point-in-time dates. All retention sets with point-in-time dates within the specified range are displayed. The default value is the earliest date on which the first retention set creation job was started. This parameter is optional. You can use this parameter with the PITBEGINTIME parameter to specify a range for the date and time. If you specify a begin date without a begin time, the time will be at 12 midnight on the specified date.

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

Value	Description	Example
MM/DD/YYYY	A specific date	05/15/2018
TODAY	The current date	TODAY
TODAY+days or +days	The current date plus the number of specified days	TODAY+3 or +3
TODAY-days or -days	The current date minus the number of specified days	TODAy-3 or -3
EOLM (End Of Last Month)	The last day of the previous month	EOLM
EOLM-days	The last day of the previous month minus the number of specified days	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 the number of specified days	BOTM+9 To include files that were active on the 10th day of the current month

PITBEGINTime

Specifies the beginning time in a point-in-time range. All retention sets with point-in-time times within the specified range are displayed. The default value is 00:00:00. This parameter is optional. You can use this parameter with the PITBEGINDATE parameter to specify a range for the date and time. If you specify a begin time without a begin date, the date will be the date when you run the command.

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

Value	Description	Example
HH:MM:SS	A specific time	10:30:08
NOW	The current time	NOW
NOW+HH:MM or +HH:MM	The current time plus the specified number of hours and minutes	NOW+02:00 or +02:00
NOW-HH:MM or -HH:MM	The current time minus the specified number of hours and minutes	NOW-02:00 or –02:00

PITENDDate

Specifies the end date in a point-in-time range. All retention sets with point-in-time end dates up to and including this date are displayed. This parameter is optional. You can use this parameter with the PITENDTIME parameter to specify an ending date and time. If you specify an end date without an end time, the time will be at 11:59:59 PM on the specified end date.

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

Value	Description	Example
MM/DD/YYYY	A specific date.	05/15/2018
TODAY	The current date.	TODAY
TODAY+days or +days	The current date plus the number of specified days. The maximum number of days that you can specify is 9999.	TODAY+3 or +3
TODAY-days or -days	The current date minus the number of specified days.	TODAY-3 or -3
EOLM (End Of Last Month)	The last day of the previous month.	EOLM
EOLM-days	The last day of the previous month minus the number of specified days.	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 the number of specified days.	BOTM+9 To include files that were active on the 10th day of the current month

PITENDTime

Specifies the end time in a point-in-time range. All retention sets with point-in-time end times up to and including this time are displayed. This parameter is optional. You can use this parameter with the PITENDDATE parameter to specify a range for the date and time. The default value is the current time.

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

Value	Description	Example
HH:MM:SS	A specific time	10:30:08
NOW	The current time	NOW
NOW+HH:MM or +HH:MM	The current time plus the specified number of hours and minutes	NOW+02:00 or +02:00
NOW-HH:MM or -HH:MM	The current time minus the specified number of hours and minutes	NOW-02:00 or –02:00

EXPBEGINDate

Specifies the beginning date in a range of expiration dates. All retention sets with an expiration date within this range are displayed. This parameter is optional. You can use this parameter with the EXPBEGINTIME parameter to specify a range for the date and time. If you specify a begin date without a begin time, the time will be at 12:00 midnight on the date that you specify. The default is the earliest date on which the first retention set creation job expires.

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

Value	Description	Example
MM/DD/YYYY	A specific date	05/15/2018
TODAY	The current date	TODAY
TODAY+days or +days	The current date plus the number of specified days	TODAY+3 or +3
TODAY-days or -days	The current date minus the number of specified days	TODAY-3 or -3
EOLM (End Of Last Month)	The last day of the previous month	EOLM
EOLM-days	The last day of the previous month minus the number of specified days	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 the number of specified days	BOTM+9 To include files that were active on the 10th day of the current month

EXPBEGINTime

Specifies the beginning time in a range of expiration times. All retention sets with an expiration time within this range are displayed. You can use this parameter with the EXPBEGINDATE parameter to specify a range for the date and time. If you specify a begin time without a begin date, the date will be the current date at the time you specify. This parameter is optional. The default value is 00:00:00.

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

Value	Description	Example
HH:MM:SS	A specific time	10:30:08
NOW	The current time	NOW
NOW+HH:MM or +HH:MM	The current time plus the specified number of hours and minutes	NOW+02:00 or +02:00
NOW-HH:MM or -HH:MM	The current time minus the specified number of hours and minutes	NOW-02:00 or –02:00

EXPENDDate

Specifies the ending date in a range of expiration dates. All retention sets with an expiration end date up to and including this date are displayed. This parameter is optional. You can use this parameter with the EXPENDTIME parameter to specify an ending date and time. If you specify an end date without an end time, the time will be at 11:59:59 PM on the specified end date.

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

Value	Description	Example
MM/DD/YYYY	A specific date.	05/15/2018
TODAY	The current date.	TODAY
TODAY+days or +days	The current date plus the number of specified days. The maximum number of days you can specify is 9999.	TODAY+3 or +3
TODAY-days or -days	The current date minus the number of specified days.	TODAY-3 or -3
EOLM (End Of Last Month)	The last day of the previous month.	EOLM
EOLM-days	The last day of the previous month minus the number of specified days.	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 the number of specified days.	BOTM+9 To include files that were active on the 10th day of the current month

EXPENDTime

Specifies the ending time in a range of expiration times. All retention sets with an expiration end time up to and including this time are displayed. This parameter is optional. You can use this parameter with the EXPENDDATE parameter to specify a date and time. If you specify an end time without an end date, the date will be the current date at the time you specify.

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

Value	Description	Example
HH:MM:SS	A specific time	10:30:08
NOW	The current time	NOW
NOW+HH:MM or +HH:MM	The current time plus the specified number of hours and minutes	NOW+02:00 or +02:00
NOW-HH:MM or -HH:MM	The current time minus the specified number of hours and minutes	NOW-02:00 or –02:00

Held

Specifies whether the retention sets to be queried are subject to a retention hold. This parameter is optional. The default value is ANY. The following values are possible:

Yes: Specifies that only retention sets that are currently subject to a retention hold are displayed.
No: Specifies that only retention sets that are not subject to a retention hold are displayed.
ANy: Specifies that all retention sets are displayed.

LISTVOLumes

Specifies whether information about the storage pool volumes on which the retention set resides is displayed. This parameter is optional. The default value is No. The following values are possible:

Yes: Specifies that the names of the storage pool volumes on which the retention set resides are displayed.
No: Specifies that no information about the storage pool volumes on which the retention set resides is displayed.

Example: Display detailed information about a retention set

Display detailed information about retention set 36. See Field descriptions for field descriptions.

query retset 36

 
              Retention Set ID: 36
           Retention Rule Name: WEEKLY
            Point-In-Time Date: 05/07/2018 08:44:48
              Retention Period: 3
               Expiration Date: 10/28/2023 08:44:48
           Retention Set State: Active
         Total File Sizes (MB): 0
Last Update by (administrator):
         Last Update Date/Time:
                         Holds: court_docket_987204
                   Description:
         Retention Destination: RETPOOL
                        Stack: Yes
       Maximum Copy Processes: Storage Rule
        Retention Set Contents: FILEMAN:\\lambo\k$ TAPEMAN:\\lambo\k$

Example: Display all retention sets that were created from a particular point in time

Display detailed information for all retention sets that were created by retention set creation jobs that were started at a particular point in time. See Field descriptions for field descriptions.

query retset pitbegindate=05/12/2018 pitbegintime=18:00


              Retention Set ID: 42
           Retention Rule Name: MONTHLY2
            Point-In-Time Date: 05/13/2018 22:18:46
              Retention Period: 3
               Expiration Date: 05/13/2019 22:18:46 
           Retention Set State: Active
         Total File Sizes (MB): 0
Last Update by (administrator):
         Last Update Date/Time:
                         Holds:
                   Description:
        Retention Destination: RETPOOL
                       Stack: Yes
      Maximum Copy Processes: Storage Rule
        Retention Set Contents: FILEMAN:\\lambo\k$ TAPEMAN:\\lambo\k$

              Retention Set ID: 46
           Retention Rule Name: WEEKLY
            Point-In-Time Date: 05/14/2018 08:44:50
              Retention Period: 7
               Expiration Date: 11/04/2023 08:44:50
           Retention Set State: Active
         Total File Sizes (MB): 0
Last Update by (administrator):
         Last Update Date/Time:
                         Holds:
                   Description:
         Retention Destination: RETPOOL
                        Stack: Yes
       Maximum Copy Processes: Storage Rule
        Retention Set Contents: FILEMAN:\\lambo\k$ TAPEMAN:\\lambo\k$

              Retention Set ID: 97
           Retention Rule Name: NODGRP
            Point-In-Time Date: 05/28/2018 06:10:01
              Retention Period: 6  
               Expiration Date: 05/29/2018 06:10:01 
           Retention Set State: Expired
         Total File Sizes (MB): 32964
Last Update by (administrator): FRED
         Last Update Date/Time: 05/29/2018 21:00:25
                         Holds:
                   Description: 3 nodes in nodegroup
        Retention Destination:
                       Stack: Yes
      Maximum Copy Processes: Storage Rule
 Retention Set Contents: LAMBO:\\lambo\k$ LAMBO:\\lambo\c$(*) LAMBO:\\lambo\e$ 
                                LAMBO:\\lambo\f$ LAMBO:\\lambo\g$ LAMBO:\\lambo\h$ 
                                LAMBO:\\lambo\i$ LAMBODDENCR:\\lambo\j$ 
                                LAMBODDENCR:\\lambo\k$(*)

Example: Display the volumes on which a retention set resides

Display detailed information about retention set including details about the volumes on which it resides. See Field descriptions for field descriptions.

query retset nodename=weekly listvol=yes

 
              Retention Set ID: 4
           Retention Rule Name: WEEKLY
            Point-In-Time Date: 07/23/2019 08:52:48
              Retention Period: 3
               Expiration Date: 12/28/2023 08:52:48
           Retention Set State: Copied
         Total File Sizes (MB): 0 
               Number of Files: 11
Last Update by (administrator): SERVER_CONSOLE
         Last Update Date/Time: 07/23/2019 08:57:48
                         Holds: 
                   Description:
         Retention Destination: RETPOOL2
                         Stack: Yes
        Maximum Copy Processes: Storage Rule
          Storage Pool Volumes: D:\STGP\0000000A.BFS D:\STGP\0000000C.BFS
        Retention Set Contents: FILEMAN:\\lambo\k$ TAPEMAN:\\lambo\k$

Example: Display the volumes on which a retention set resides

Display detailed information about retention set including details about the volumes on which it resides. See Field descriptions for field descriptions.

query retset nodename=weekly listvol=yes

 
              Retention Set ID: 431
           Retention Rule Name: WEEKLY
            Point-In-Time Date: 07/23/2019 08:52:48
              Retention Period: 3
               Expiration Date: 12/28/2023 08:52:48
           Retention Set State: Copying
         Total File Sizes (MB): 56MB 
               Number of Files: 34
Last Update by (administrator): SERVER_CONSOLE
         Last Update Date/Time: 07/23/2019 08:57:48
                         Holds: 
                   Description:
         Retention Destination: RETPOOL2
                         Stack: No
        Maximum Copy Processes: 1
          Storage Pool Volumes: C:\JUNK\STORAGE\D81A\00000018.BFS C:\JUNK\STORAGE\D81A\00000019.BFS 
                                C:\JUNK\STORAGE\D81A\0000001A.BFS C:\JUNK\STORAGE\D81A\0000001B.BFS 
         Retention Set Contents: FILEMAN:\\lambo\k$ TAPEMAN:\\lambo\k$

Example: Display detailed information about a deleted retention set

Display detailed information about retention set 82, which has been deleted. The client nodes and file spaces that were contained in the retention set are all deleted and denoted with the indicator "(*)". See Field descriptions for field descriptions.

query retset 82

 
              Retention Set ID: 82
           Retention Rule Name: WEEKLY
            Point-In-Time Date: 05/07/2020 12:44:32
              Retention Period: 3
               Expiration Date: 10/07/2020 14:01:48
           Retention Set State: Deleted
         Total File Sizes (MB): 16091
Last Update by (administrator): 
         Last Update Date/Time: 10/07/2020 14:01:48
                         Holds: 
                   Description:
         Retention Destination: RETPOOL1
                         Stack: Yes
        Maximum Copy Processes: Automatic
        Retention Set Contents: FILEMAN:\\lambo\k$(*) TAPEMAN:\\lambo\k$(*) TAPE2MAN:\\lambo\k$(*)

Field descriptions

Retention Set ID: The number that is associated with the retention set.
Retention Rule Name: The name of the retention rule that created the retention set.
Point-In-Time Date: The date and time of the point-in-time snapshot of the client data.
Retention Period: The length of time, in days, for which any retention set that is created by the retention rule is retained by the server. If no retention period was specified, the value No Limit is displayed.
Expiration Date: The expiration date and time of the retention set.
Retention Set State: The current state of the retention set.
Total File Sizes: The size of the files that are included in the retention set.
Last Update by (administrator): The name of the administrator who defined or most recently updated the retention rule.
Last Update Date/Time: The date and time that an administrator defined or most recently updated the retention rule.
Holds: The list of retention holds with which the retention set is associated.
Description: A description of the retention set.
Destination: The retention storage pool that is specified by the retention rule on which copies of retained data is stored. The retention storage pool must be a tape device.
Stack: Indicates whether the retention set shares storage pool volumes with other retention sets or if the retention set is isolated from other retention sets.
Maximum Copy Processes: The maximum number of copy-to-tape processes that can run in parallel.
Storage Pool Volumes: The names of the storage pool volumes.
Retention Set Contents: The clients that are included in the retention set. If wildcards are used to specify nodes, file spaces, or both, this value reflects the clients that match those specifications.
Tip: Any client nodes or file spaces that are deleted from the retention set are denoted by the indicator "(*)". For example, FILEMAN:\\lambo\k$(*). If the entire retention set is deleted, the "(*)" indicator appears for all client nodes and file spaces that were contained in the retention set.

Related commands

Table 1. Commands related to QUERY RETSET
Command	Description
DELETE RETSET	Deletes a retention set.
UPDATE RETSET	Changes the attributes of a retention set.
QUERY RETSETCONTENTS	Displays information about the contents of retention sets.