Controlling multirecord update edit operations

As a Rational® ClearQuest® administrator or schema designer, you can write hook code that uses multirecord update status information to implement multirecord update controls.

For example, the schema could limit which records or record types can be modified, which fields can be modified, who can perform multirecord update operations, or prevent further changes when the error count reaches a limit. Other possibilities include limits that are based on the record type, associated Project record, current user, or group membership.

Multirecord update status information is provided to the schema in the ratl_MultiModifyBatchStatus session variable. The value of the ratl_MultiModifyBatchStatus session variable is composed of the following numeric values in the order shown. Each value is numeric and is separated by a newline.

The total number of records, including the template record
The ordinal of the current record, ranging from 1 to the total number of records. The ordinal value is 1 for the template record.
The number of failed updates

The record ordinal can be used to determine when the multirecord update template record is being edited. An ordinal value of 2 or higher indicates that playback is in progress, and that multirecord update is currently operating on the record that corresponds to the ordinal value. For example, suppose you perform a multirecord update on 13 records. When the template record is being edited, the value of the ratl_MultiModifyBatchStatus session variable is "13 1 0" (with newlines for spaces). When multirecord update is being played back on the fifth record with no failures, the value of ratl_MultiModifyBatchStatus is "13 5 0". When multirecord update is being played back on the ninth record after having two failures on previous records, the value of ratl_MultiModifyBatchStatus is "13 9 2".

The ratl_MultiModifyBatchStatus session variable and the ratl_MultiModifyBatchMode session variable are set when multirecord update performs an operation on a record that causes a hook to run. Examples of such operations are all action phases, record script alias actions, field changes, choice list hooks, any hook that may run for edit operations on any record, and even a hook that is not included in the multirecord update.

The following example shows how to check that the current record is the one that multirecord update is operating on. This example is intended to be used in an action access control hook. After the action control hook checks whether multirecord update is in progress, the hook checks the failure count. If there are 10 or more failures, it uses a Perl die () statement to raise an error. Multirecord update will continue to process all the records in the multirecord update result set, and this example hook will continue to mark each subsequent record with a failure.

$result = 1;
# If doing multirecord update, check if it has too many errors.
   #
   my $mru_id = $session->GetNameValue("ratl_MultiModifyBatchMode");
   if ($mru_id ne "") {
      my $me = $entity->GetDisplayName();
      if ($mru_id eq $me) {
         # Yes, currently doing Multi-Record Update on the current record.

         my $status = $session->GetNameValue("ratl_MultiModifyBatchStatus");
         my ($count, $ordinal, $failures, $ignore) = split('\n', $status, 4);

         if ($failures > 10) {
            die("This multirecord update has encountered too many errors ($failures). No more updates are allowed.")
         }
      }
   }