DEFINE RETRULE (Define a retention rule)

Use this command to define a retention rule for an IBM Spectrum Protect server.

You can define the retention rule to run only once or on a scheduled basis.

A one-time only retention rule enables you to create a retention set to meet requirements to collect active data in either the past, present, or in the future.
Restrictions: The following restrictions apply to one-time only retention rules.
  • When you define a retention rule as a one-time only rule, you cannot modify it later to run on a recurring basis or to create another retention set.
  • 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 that is in the past cannot be triggered for such a node.

You can also define a retention rule to run on a scheduled basis, beginning from the current date and time or a date and time in the future.

Privilege class

To issue this command, you must have system privilege or unrestricted policy privilege.

Syntax


1  DEFine RETRule   retrule_name 
2.1+ ,
2.1 node_name
2.1 node_group_name?  + , filespace_name(1)(2)(3)
2.1!  NAMEType = SERVER
2.1  NAMEType =
2.2.1 SERVER
2.2.1 UNIcode
2.2.1 FSID
2.1!  CODEType = BOTH
2.1  CODEType =
2.2.1 UNIcode
2.2.1 NONUNIcode
2.2.1 BOTH 
2.1  RETention =
2.2.1 days
2.2.1 NOLimit 
2.1!  STARTTime = NOW
2.1  STARTTime = time
2.1!  STARTDate = TODAY
2.1  STARTDate = date 
2.1  %classic_schedule
2.1  %enhanced_schedule
1!  ACTive = Yes
1  ACTive =
2.1 Yes
2.1 No
2?  DESCription = description
classic schedule

1!  SCHEDStyle = Classic
1  SCHEDStyle = Classic
1!  FREQuency = Weekly
1  FREQuency =
2.1 Weekly
2.1 Monthly
2.1 Quarterly
2.1 Yearly
2.1 Onetime
1!  DAYofweek = ANY
1  DAYofweek =
2.1 ANY
2.1 WEEKDay
2.1 WEEKEnd
2.1 SUnday
2.1 Monday
2.1 TUesday
2.1 Wednesday
2.1 THursday
2.1 Friday
2.1 SAturday
enhanced schedule

1  SCHEDStyle = Enhanced

1!  MONth = ANY
1  MONth =
2.1+ ,
2.1 ANY
2.1 JAnuary
2.1 February
2.1 MARch
2.1 APril
2.1 May
2.1 JUNe
2.1 JULy
2.1 AUgust
2.1 September
2.1 October
2.1 November
2.1 December
1!  DAYOFMonth = ANY
1  DAYOFMonth =
2.1 ANY
2.2.1+ ,
2.2.1 Day
1  WEEKofmonth =
2.1+ ,
2.1 ANY
2.1 FIrst
2.1 Second
2.1 Third
2.1 FOurth
2.1 Last
1!  DAYofweek = ANY
1  DAYofweek =
2.1 ANY
2.1 WEEKDay
2.1 WEEKEnd
2.2.1+ ,
2.2.1 SUnday
2.2.1 Monday
2.2.1 TUesday
2.2.1 Wednesday
2.2.1 THursday
2.2.1 Friday
2.2.1 SAturday
Notes:
  • 1 The filespace_name must correspond to an IBM Spectrum Protect for Virtual Environments virtual machine.
  • 2 If you specify a file space name, you can specify only one fully qualified node name.
  • 3 Instead of specifying a file space name, you can specify the name of the virtual machine.

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 wildcard characters in the node name, when the retention set is created, all nodes are included in the retention set that match that wildcard specification. If you specify a file space name, you can specify a single node name only.
filespace_name
Specifies the name of a file space to which the retention rule applies. The file space name corresponds to the name of an IBM Spectrum Protect for Virtual Environments virtual machine. Instead of specifying a file space name, you can also specify the name of the virtual machine. The file space 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.
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. Use this parameter only when you specify a partially or a fully qualified file space name.

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 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 file space 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 a single wildcard character for the file space 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 time in a range of times in which the retention rule is first processed. If the start time is 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 at the time you issue the command.
Tip: For retention sets that are created in the past, an information message is issued to the activity log that indicates that the retention set can include files as they existed in the past.

If the scheduled creation of a retention set does not run as planned, its creation occurs as soon as possible.

The default is the current time. This parameter is optional.

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
STARTDate
Specifies the beginning date for the range of dates in which the retention rule is first processed. If the start date is 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 at the time you issue the command.
Tip: For retention sets that are created in the past, an information message is issued to the activity log that indicates that the retention set can include files as they existed in the past.

If the scheduled creation of a retention set does not run as planned, its creation occurs as soon as possible.

This parameter is optional. The default is the current date.

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 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
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 required.

The retention period that you specify is used as the retention period value of any retention sets that are created by 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 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 used by the IBM Spectrum Protect server to create retention sets based on the scheduling criteria. This parameter is optional. The default value is Yes.
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. To suspend the creation of retention sets by this rule, set the ACTIVE parameter to No. To resume the creation of retention sets, set this parameter to Yes.
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.

SCHEDStyle
This parameter is optional. The SCHEDSTYLE parameter defines either the interval between times when a schedule can run, or the days on which it runs. The default is the Classic value.
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 schedule on which retention sets are created for this retention rule. You can specify the FREQUENCY parameter with the SCHEDSTYLE=CLASSIC setting only.
Restriction: If you specify FREQUENCY=ONETIME, you cannot change this value. Conversely, if you specify a value other than ONETIME, you cannot change this value to ONETIME at a later point.

Example: Define a retention rule that initiates the creation of a retention set weekly

Define a retention rule on NODE1 that initiates the creation of a retention set weekly and that is named MY_WEEKLY_RETSET. Specify the start date as 10 May 2018 and that the retention sets are created each Saturday at 1.00 AM. The retention sets that are created with this retention rule are retained for 150 days.
define retrule my_weekly_retset NODE1 retention=150 
description="Weekly retention set creation" 
startdate=05/10/2018 starttime=01:00:00 
schedstyle=classic frequency=weekly dayofweek=saturday

Example: Define a retention rule on multiple nodes by using a wildcard and also on a client node group

Define a retention rule named SERVER_TEST_DATA on the client nodes NODE1, NODE2, and NODE3 and on the client node group name TESTDATA. The only nodes on the system that start with the characters "NODE" are NODE1, NODE2, and NODE3, so you can use a wildcard to specify them. Specify the start date as the current date at 1.00 AM. The retention period for which the retention set and its data are retained is 60 days. 
define retrule server_test_data NODE*,testdata retention=60 
startdate=TODAY starttime=01:00:00 
schedstyle=classic frequency=weekly dayofweek=monday

Related commands

Table 2. Commands related to DEFINE RETRULE
Command Description
UPDATE RETRULE Changes the attributes of a retention rule.
QUERY RETRULE Displays information about retention rules.
DELETE RETRULE Deletes a retention rule.
RENAME RETRULE Renames a retention rule.