trigger lock

System trigger that is activated for cautious and optimistic locking when modifying or writing a database occurrence. It is the location for the lock statement and associated logic.

Declaration: trigger lock
Applies to: Entity
Activation: Activated for cautious and optimistic locking when modifying or writing a database occurrence. For details, see Trigger Activation
Default behavior: None
Behavior upon completion: If $status is less than zero, the user is prevented from modifying the occurrence.

Description

The purpose of this trigger is to ensure that the user modifies the latest copy of the data, and that data integrity problems do not occur. Usually, the lock trigger contains the lock ProcScript statement, which asks for a lock on the data in the database.

The granularity of the lock (that is, how much data is locked: table, page, row, and so on) is specific to each supported DBMS and cannot be influenced from the lock trigger. For more information, see the documentation for the relevant DBMS connector and consult the documentation for your DBMS.

If a lock is requested and successfully obtained for the occurrence, Uniface sets a flag on the current field to guarantee activation of the valueChanged trigger when the field is left.

Trigger Activation

The lock trigger is activated when the user first tries to modify an occurrence that has been retrieved from the database. For optimistic locking, any lock statement in the trigger is ignored.

The lock trigger is activated for an Up entity only if its deleteUp or writeUp trigger contains ProcScript. The presence of code in one of these triggers implies that the Up entity should be locked because it will be written to the database.

The lock trigger is not activated in the following circumstances:

  • When using paranoid locking (that is, issuing the read/lock statement in the read trigger to request an immediate lock)
  • In a Limited component.

Cautious Locking

The activation process for cautious locking is started after successful completion of the startModification trigger for the first field edited in an occurrence. If the startModification trigger completes with a non-negative return value in $status, Uniface activates the lock trigger for the occurrence.

To prevent the lock trigger from activating when modifying dummy fields in a retrieved occurrence, use /init on the assignment statement.

Using the lock Command

By default, the lock trigger contains the following ProcScript: 

trigger lock
  lock
  if ($status = -10) reload
end; lock

This ensures that the data is reloaded if an occurrence in the database has been modified (which is what $status=-10 means).

Tip: Except in exceptional circumstance, it is recommended that you always have a lock statement in the lock trigger.

One such circumstance is if you remove the store statement from the store trigger or other relevant trigger to prevent the user from storing occurrences. In this case, you should also remove the lock statement from the lock trigger to prevent a user's request to store the data resulting in an unwanted lock. However, this may result in the user not being presented with the latest data, because in the time between the user retrieving the data and it being modified, another user may have modified and stored the occurrence. It may be advisable to place a reload statement in the lock trigger instead of a lock statement.

Related Topics