UPDATE RETRULE (Update a retention rule)
Use this command to update the attributes of a retention rule. The changes that you make do not affect the attributes of retention sets that were already created based on the rule. The changes apply only to new retention sets.
Privilege class
To issue this command, you must have system privilege or unrestricted policy privilege.
Syntax
- 1 The filespace_name can correspond to a file space on a backup-archive client or to an IBM Spectrum® Protect for Virtual Environments virtual machine. If you specify a filespace name, you can specify only one fully qualified node name. To specify the virtual machine, use either the virtual machine name or the corresponding filespace name. This is relevant for both the add client and remove client actions.
- 2 To specify the HOLD and HOLDREASON parameters, FREQUENCY=ONETIME must be specified.
Parameters
- retrule_name (Required)
- Specifies the name of the retention rule. The name must be unique, and the maximum length is 64 characters.
- node_name or node_group_name (Required)
- Specifies the name of the client node or node groups to which the retention rule applies. To
specify multiple node names and node group names, separate the names with commas and no intervening
spaces. You can use wildcard characters with node names but not with node group names. If you
specify a filespace name, you can specify only a single node name.Restriction: Client nodes that are decommissioned when the retention set is created are excluded from the retention set.
- filespace_name
- Specifies the name of a file space to which the retention rule applies.
The filespace name can correspond to a backup-archive client file space. The filespace name can also correspond to the name of an IBM Spectrum Protect for Virtual Environments virtual machine. Instead of specifying a filespace name, you can also specify the name of the virtual machine.
You can specify wildcard characters in the filespace name. 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.
Tips:- Issue the QUERY FILESPACE command to determine which file spaces and file space IDs are defined for a node on the server.
- File spaces that are decommissioned when the retention set is created are excluded from the retention set.
- NAMEType
- Specifies how you want the server to interpret the filespace name that you enter. Use this
parameter only when you specify
a fully qualified
filespace name.
The default value is SERVER. If a virtual filespace 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 filespace name.
- UNIcode
- The server converts the filespace 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 fails 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 filespace name as the file space ID (FSID).
- CODEType
- Specifies the type of file spaces to be included in retention rule processing. The default value
is BOTH, meaning that file spaces are included regardless of code page type. Use this parameter only
when you enter
at least one wildcard character for the filespace name. 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.
- STARTTime
- Specifies the beginning of a time period during which the retention rule is first processed. The
default is the current time. This parameter is optional. You can update the
STARTTime value as follows, depending on the type of retention rule.
- One time onlyFor a one-time-only retention rule, you can specify a start time in the past. Files that were active from the specified time and that are still stored on the IBM Spectrum Protect server are to be included in the retention set, even if they are inactive when you issue the command. You can update the STARTTime value, but the new start time will apply only to future retention set creation runs.Restriction: If a node on a server is the target node for a node replication operation from another server, the creation of one-time-only retention sets for a time and date that is in the past cannot be triggered for the node.
- Scheduled
For a retention set creation run that is scheduled for today, you can update the run schedule only if the run has not started or completed today. If the run was started or completed today, you can change the schedule to run tomorrow or later.
Tip: For retention sets that are created in the past, an information message is issued to the activity log to indicate that the retention set can include files as they existed in the past. For example, expiration processing or other deletion activities might have deleted one or more files over time, but the files would be included in the retention set if the files existed at the specified time in the past.You can specify one of the following values:Value Description Example HH:MM:SS A specific time 23: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 - One time only
- STARTDate
- Specifies the beginning date for a time period during which the retention rule is first
processed. This parameter is optional. The default is the current date. You can update the
STARTDate value as follows, depending on the type of retention rule.
- One time onlyFor a one-time-only retention rule, you can specify a start date in the past. Files that were active from the specified date and that are still stored on the IBM Spectrum Protect server are to be included in the retention set, even if they are inactive when you issue the command. You can update the STARTDate value, but the new start date will apply only to future retention set creation runs.Restriction: If a node on a server is the target node for a node replication operation from another server, the creation of one-time-only retention sets for a time and date that is in the past cannot be triggered for the node.
- Scheduled
For a retention set creation run that is scheduled for today, you can update the run schedule only if the run has not started. If the run was started or completed today, you can change the schedule to run tomorrow or later.
Tip: For retention sets that are created in the past, an information message is issued to the activity log to indicate that the retention set might include files as they existed in the past. For example, expiration processing or other deletion activities might have deleted one or more files over time, but the files would be included in the retention set if the files existed at the specified time in the past.You can specify 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 EOLM (End Of Last Month) The last day of the previous month. EOLM EOLM-days The last day of the previous month minus the specified number of 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
- One time only
- HOLD
- Specifies the name of the retention hold to which one or more retention sets can be added. You
can place a retention set in a retention hold to preserve relevant data indefinitely, for example,
if a litigation is pending or anticipated. Any retention set that is added to a retention hold
cannot be deleted, regardless of its expiration date, until the retention set is explicitly released
from the hold.Restriction: To specify the HOLD and HOLDREASON parameters, FREQUENCY=ONETIME must be specified.
- HOLDREASon
- Specifies the reason for which a hold is placed on the specified retention set. The maximum length is 510 characters. Enclose the reason in quotation marks if it contains any blank characters.
- RETention
- Specifies the length of time, in days, for which any retention set that is created by the
retention rule is retained by the server. This parameter is optional.
The retention period that you specify is used as the retention period value of any retention sets created from the rule; however, you can change this value by issuing the UPDATE RETSET command. Data that is contained in a retention set does not expire until the retention period of that retention set has passed, irrespective of the management class and copy group policies associated with that data. You can specify one of the following values:
- days
- Specify an integer value in the range 0 - 30,000.
After you determine the length of time to retain data, you can use the following table to convert the number of years to days. Accordingly, if the period includes a leap year, adjust the number of days.
Table 1. Sample number of days converted to years Number of years Number of days to years 1 year 365 2 years 730 3 years 1095 4 years 1461 5 years 1826 6 years 2191 7 years 2556 8 years 2921 9 years 3287 10 years 3652 20 years 7304 30 years 10957 40 years 14609 50 years 18262 - NOLimit
- Specifies that you want to keep the retention set indefinitely. If you specify NOLimit, the server retains retention sets forever, unless an authorized user or administrator deletes the retention set. For information on the DELETE RETSET command, see DELETE RETSET (Delete a retention set).
- ACTive
- Specifies whether the retention rule is enabled for processing. This parameter is optional.
- Yes
- Specifies that the retention rule is active. To allow retention sets to be created by the retention rule, the ACTIVE parameter must be set to Yes.
- No
- Specifies that the retention rule is not in an ACTIVE state and as such, retention sets are not created by this retention rule.
- DESCription
- Specifies a description for the retention rule. This description is copied to the retention sets
that are created by this retention rule. This parameter is optional.
The maximum length of the description is 255 characters. Enclose the description in quotation marks if it contains any blank characters.
- STACK
- Specifies whether data for the retention sets that are created by the retention rule can be
copied to shared tape volumes, that is, volumes that also contain data from other retention sets.
This parameter is optional.
- Yes
- Specifies that retention set data can share tape volumes with data copied from other retention
sets. Tip: If you specify Yes, retained data can be copied to any tape volume with a status of EMPTY. Data can also be copied to volumes with a status of FILLING, but only if those volumes are not already in use by retention sets that require a separate volume.
- No
- Specifies that retention set data does not share tape volumes with data copied from other
retention sets.Tip: If you specify No, the retention set data can be copied to tape volumes with a status of EMPTY or FILLING. Data can be copied to FILLING volumes only if the volumes already contain data for the retention set that is being copied. When the operation to copy the retained data to the volume finishes, even though the volume might not be full, the volume will be marked as FULL to prevent its use by other retention sets.
- MAXCOPYProcess
- Specifies the maximum number of parallel processes that the storage rule can run when copying
retained data to a retention storage pool. This parameter is optional. All retention sets that are
created from the retention rule inherit the MAXCOPYPROCESS value that is
specified for the storage rule. By ensuring that the MAXCOPYPROCESS parameter is set to an
appropriate value, you can help to optimize the performance of copy operations.
- AUTOmatic
- Specifies that the maximum number of processes to use is preset for optimal performance.
- STGRule
- Specifies that the number of parallel processes is determined by the MAXPROCESS value of the storage rule.
- number
- Specifies the maximum number of parallel processes to copy retained data. You can enter a value in the range 1 - 99.
- DESTination
- Specifies a destination for the retention sets that are created by this retention rule. You can
specify the name of a retention storage pool into which copies of data in the retention sets created
by this retention rule will be stored. To remove a destination, specify the
DESTINATION parameter with a null string (""). This parameter is optional.
- retention_storage_pool
- Specifies the name of a retention storage pool to which the retention sets are copied.
Restriction:Only retention storage pools can be specified as a destination.
- SCHEDStyle
- Specifies the type of schedule for the retention rule. This parameter
is optional. The default value is Classic.You can specify one of the following values:
- Classic
- The parameter for the Classic syntax is DAYOFWEEK. If you specify SCHEDSTYLE=CLASSIC, you cannot specify the following parameters: MONTH, DAYOFMONTH, and WEEKOFMONTH.
- Enhanced
- The parameters for the Enhanced syntax are MONTH, DAYOFMONTH, WEEKOFMONTH, and DAYOFWEEK. If you specify SCHEDSTYLE=ENHANCED, you cannot specify the FREQUENCY parameter.
- FREQuency
- Specifies the frequency for creating retention sets. The default value is WEEKLY. You can
specify the FREQUENCY parameter with the SCHEDSTYLE=CLASSIC setting only.Restriction: If you specify FREQuency=ONETIME, you cannot change this value after the retention rule is defined. Conversely, if you specify a value other than ONETIME, you cannot change this value to ONETIME after the retention rule is defined.
Example: Update a retention rule to add a client node
Update retention rule RULE1 to add a client note, TESTNODE.
update retrule rule1 add client testnode
Example: Update a retention rule to change the retention period
Update retention rule RULE1 to change the retention period to 60 days.update retrule rule1 retention=60
Related commands
Command | Description |
---|---|
DEFINE RETRULE | Defines a retention rule. |
DELETE RETRULE | Deletes a retention rule. |
QUERY RETRULE | Displays information about retention rules. |
RENAME RETRULE | Renames a retention rule. |