Question & Answer
Question
How can you remove history records from an IBM Rational ClearQuest database?
Cause
By default, history has always been recorded for all record-types. Not all record-types have form controls to display this history. History for all record-types is recorded to a single database table. The load time for IBM Rational ClearQuest records may decrease over time as the result of recording history, if total record count is large, the number of actions performed upon records is high, and or the database is not properly tuned. Selectively scrubbing and or disabling history may be prudent under certain schema designs or usage patterns.
Answer
The installutil scrubhistory command is used to remove history records from an IBM Rational ClearQuest database. Here is the command usage summary:
Note: Check with your business unit if disabling history meets local regulatory compliance practices.
Caution: Removal of history is irreversible. Take appropriate backups of the database set and any related integrations prior to performing irreversible changes.
This command can be used on any record-type. It does not matter if history is disabled for the record-type (a capability introduced with Feature Level 9).
Using -all causes all history for all records of the named record-type to be removed.
The -action <name> option removes any history record for the named action.
The -modify-only option removes any history record for any action of type modify.
The-before option removes only history records created before the given date. The date format is the same as what is accepted for a ClearQuest DateTime field.
Either -all or at least one of the -action, -modify-only, and -before options must be provided.
The -action, -modify-only, and -before options can be combined. Each one imposes a different type of restriction on the history records that would be removed. For example, -action REVISE -modify-only will remove history for the REVISE action, but only if that action is of type modify. Or, -action REVISE -before 2014-01-01 will remove history for the REVISE action that was created before January 1, 2014.
The command will report how many history records were removed for each action and a total for all actions.
The -verbose option causes the command to report more detail of its operation as it progresses.
The -show option causes the command to only report what it would remove without actually doing anything.
Example
MultiSite
When the database is replicated with IBM Rational ClearQuest MultiSite, the history deletion can be performed at any site and will be replicated to all other sites. The history is deleted without regard for mastership of the associated records.
Scrubbing Actions By Name
History entries record the action by name, which has the following implications:
Impact of Feature Level On scrubhistory Command
This scrubhistory command can be used in a database at any feature level. However, if the database is at feature level 8 or below, the command will not remove the latest history entry for a record. These history records have no entry for the expired_timestamp field, which is updated when the next history record is saved. Without Feature Level 9, the latest history record must remain in the database so there are no errors when updating a record.
If you wish to scrub all history records for the given matching criteria, first upgrade to Feature Level 9 to remove this limitation.
Note: The history timestamp values depend on the database feature level. At FL6 and above, the timestamps are recorded in GMT. At FL5 and below, they were recorded in DBMS server local time. Older databases may contain history entries recorded at FL5 and below. Those entries would have timestamp values recorded as local time. The scrubhistory command does not account for this difference, but treats all history timestamps as if they were recorded as GMT. This should be taken into consideration when using the -before option.
Package Owned Record-Types
Removal of history from package owned record-types is not supported. If you require removal of history from package owned record-types, please contact IBM Rational Support for guidance.
Usage: installutil scrubhistory
<dbset> <user> <password> <userDB>
<recordtype>
(-all | { -action <name> | -modify-only | -before <date> } ... )
[-verbose] [-show]Note: Check with your business unit if disabling history meets local regulatory compliance practices.
Caution: Removal of history is irreversible. Take appropriate backups of the database set and any related integrations prior to performing irreversible changes.
This command can be used on any record-type. It does not matter if history is disabled for the record-type (a capability introduced with Feature Level 9).
Using -all causes all history for all records of the named record-type to be removed.
The -action <name> option removes any history record for the named action.
The -modify-only option removes any history record for any action of type modify.
The-before option removes only history records created before the given date. The date format is the same as what is accepted for a ClearQuest DateTime field.
Either -all or at least one of the -action, -modify-only, and -before options must be provided.
The -action, -modify-only, and -before options can be combined. Each one imposes a different type of restriction on the history records that would be removed. For example, -action REVISE -modify-only will remove history for the REVISE action, but only if that action is of type modify. Or, -action REVISE -before 2014-01-01 will remove history for the REVISE action that was created before January 1, 2014.
The command will report how many history records were removed for each action and a total for all actions.
The -verbose option causes the command to report more detail of its operation as it progresses.
The -show option causes the command to only report what it would remove without actually doing anything.
Example
- This example will preview the scrubbing of all history for the "Defect" record-type, if the action is "Revise" and the history was created prior to "2014-01-01" with detailed progress. To execute with commit, remove the -show argument.
installutil scrubhistory DEV admin "" BUGS Defect -action Revise -before 2014-01-01 -verbose -showMultiSite
When the database is replicated with IBM Rational ClearQuest MultiSite, the history deletion can be performed at any site and will be replicated to all other sites. The history is deleted without regard for mastership of the associated records.
Scrubbing Actions By Name
History entries record the action by name, which has the following implications:
- The -action option can be used to identify any action recorded in the history, whether or not that action is still defined in the schema.
- The -modify-only option must determine the action type and therefore it will only have an effect on actions that still exist in the schema. The current action definition is used to determine whether the action is the modify type or not. Therefore, if an action was originally defined as a state change action type (or submit or any other type), was subsequently deleted, and a new action of type modify created with the same name, then all history records with that action name will be removed. This happens because the actual removal is by name, and there is no way to know the actual action type at the time it was recorded in a history entry.
Impact of Feature Level On scrubhistory Command
This scrubhistory command can be used in a database at any feature level. However, if the database is at feature level 8 or below, the command will not remove the latest history entry for a record. These history records have no entry for the expired_timestamp field, which is updated when the next history record is saved. Without Feature Level 9, the latest history record must remain in the database so there are no errors when updating a record.
If you wish to scrub all history records for the given matching criteria, first upgrade to Feature Level 9 to remove this limitation.
Note: The history timestamp values depend on the database feature level. At FL6 and above, the timestamps are recorded in GMT. At FL5 and below, they were recorded in DBMS server local time. Older databases may contain history entries recorded at FL5 and below. Those entries would have timestamp values recorded as local time. The scrubhistory command does not account for this difference, but treats all history timestamps as if they were recorded as GMT. This should be taken into consideration when using the -before option.
Package Owned Record-Types
Removal of history from package owned record-types is not supported. If you require removal of history from package owned record-types, please contact IBM Rational Support for guidance.
Related Information
[{"Line of Business":{"code":"LOB45","label":"Automation"},"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Product":{"code":"SSSH5A","label":"Rational ClearQuest"},"ARM Category":[{"code":"a8m0z000000boUtAAI","label":"ClearCase->Documentation"},{"code":"a8m0z000000boYbAAI","label":"ClearQuest->Administration"},{"code":"a8m0z000000boZKAAY","label":"ClearQuest->Core"}],"ARM Case Number":"","Platform":[{"code":"PF033","label":"Windows"}],"Version":"8.0.1;9.0.1;9.0.2;9.1.0"}]
Was this topic helpful?
Document Information
Modified date:
17 March 2021
UID
swg21689388