Specifying retention settings

You can change the retention setting for an existing object. With the HTTP protocol, you can also specify a retention setting when you store an object in the namespace. The following information describes the retention settings you can specify.

For information about specifying retention settings with HTTP, see Working with system metadata.

With WebDAV, CIFS, or NFS, you change the retention setting on an object by overwriting its retention.txt metafile. In the new file, you specify a single value that tells HCP what change to make. This value must be on a single line. To ensure that HCP processes the value correctly, end the line with a carriage return.

Tip: With Windows and Unix, you can also use the echo command to insert the new value into the retention.txt metafile.

These general rules apply to values you can set:

If you’re storing an object in the namespace with HTTP or setting retention for an existing object that is not under retention, you can specify any retention setting — past or present. If you set a time in the past, the object is immediately deletable.

If you’re changing the setting for an existing object that is in a retention class, you can replace the class with another class, as long as the duration of the replacement class is not shorter than the duration of the original class. You cannot replace the class with an explicit retention setting, such as Deletion Prohibited or a datetime value.

If you’re changing the setting for an existing object that has an explicit datetime retention setting, you can change the setting to lengthen the retention period but not to shorten it.

The table below describes the values you can use to specify the retention setting for an object and contains rules for specifying these values. These values are not case sensitive.

Value Description

0 (zero)
or
Deletion Allowed

Allows the object to be deleted at any time. You can assign this value to an object only when you add it to the namespace or when its retention setting is -2.

The value -0 is equivalent to 0 (zero).

-1
or
Deletion Prohibited

Prevents the object from being deleted and its retention setting from being changed. You can assign this value to an object that is not in a retention class at any time.

If an object is assigned to a retention class and that class is then deleted, the retention setting for that object changes to -1.

-2
or
Initial Unspecified

Specifies that the object does not yet have a retention setting. You can assign this value to an object when you add the object to the namespace. You can also directly change the retention setting for an object from 0 to ‑2.

You can change ‑2 to any other retention setting.

datetime

Prevents the object from being deleted until the specified date and time. You can assign this value to an object that is not in a retention class if the specified date and time is later than the current retention setting for the object. You cannot assign it to an object for which the current retention setting is -1.

For a description of the datetime format, see Specifying a date and time.

offset

Specifies a period for which to retain the object. You can assign this value to an object that is not in a retention class at any time, except when its current retention setting is -1.

HCP calculates the retention setting date and time from the offset and one of these:

The time the object was added to the namespace

The current retention setting

The current time

For a description of the offset format, see Specifying an offset.

C+retention_class_
name

Assigns the object to a retention class.

You can assign this value to an object if any one of these is true:

The original retention period for the object has expired.

The original retention period for the object has not expired, and the retention class results in a retention period that is longer than the current retention period.

The retention setting for the object is 0 or -2.

The retention setting for the object is -1, and the class has a retention setting of -1.

The object is in a retention class, and the duration of the new class is not shorter than the duration of the original class.

The retention class you assign must already be defined for the namespace.

For more information about retention classes, see Retention classes.

For more information about the retention settings listed in the first four rows of this table, see Object retention settings.

© 2015, 2020 Hitachi Vantara LLC. All rights reserved.