LockRecord

Description

Creates a lock on the record.

Acquiring a record lock includes the ability to specify a maximum wait time in seconds. This value is the time to wait for an existing lock to be released before the lock attempt fails. The lock attempt fails if the lock cannot be acquired before the value specified by the wait_seconds parameter has elapsed.

The method throws an exception if the lock cannot be acquired for any of the following reasons:

Feature Level is less than FL7.
The record type is system owned.
The record is locked by another user.
The record is locked by another session.
The record was updated during lock.

To enable record locking, for each record type:

Add a new action named LockRecord of type BASE.
Add an Action_Initialization hook to the action, and have the hook call the LockRecord method. For example,
```
$entity->LockRecord(0);
```

Note: This method became available in version 7.1.

Syntax

VBScript


entity.LockRecord wait_seconds

Perl


$entity->LockRecord(wait_seconds);

Identifier: Description
entity: An Entity object representing a user data record. Inside a hook, if you omit this part of the syntax, the Entity object corresponding to the current data record is assumed (VBScript only).
wait_seconds: A Long that specifies the number of seconds to wait for an existing lock to be released before the lock attempt fails.
Return value: None.

Examples

VBScript

Function Defect_LockRecord(param)
' Lock Record for RECORD_SCRIPT_ALIAS action
  ' param As Variant
  ' record type name is Defect
    REM add your hook code here
  ' don't wait
    LockRecord(0) 
End Function


Sub Defect_Initialization(actionname, actiontype)
' Lock Record for BASE action Action_Initialization hook
  ' actionname As String
  ' actiontype As Long
  ' action is LockRecord
  ' record type name is Defect
    REM do any setup for the action here
    LockRecord(0)
End Sub

Perl

sub Defect_LockRecord {
 # Lock Record Script for RECORD_SCRIPT_ALIAS action
 my($result);
 my($param) = @_;
 # record type name is Defect

 if (ref ($param) eq "CQEventObject") {
   # add your CQEventObject parameter handling code here
 } elsif (ref (\$param) eq "SCALAR") {
     # Add your scalar parameter handling code here
     # The Web clients support scalar parameter type only,
     # so the hook code added in the above section, needs to be duplicated here
    } else {
     # Add your handling code for other type parameters here, for example:
     # die("Unknown parameter type");
       }
 # don't wait
   $entity->LockRecord(0);   
  return $result;
 }


sub Defect_Initialization {
 # Lock Record script for BASE action Action_Initialization hook
    my($actionname, $actiontype) = @_;
    # $actionname as string scalar
    # $actiontype as long scalar
    # action is LockRecord
    # record type name is Defect
    # Do any setup for the action here.
      $entity->LockRecord(0);
}