The function modules for setting and removing locks are created automatically when a lock object is activated in the ABAP Dictionary. These function modules can be included when programming interactive transactions.
The name of the function module for setting locks is:
ENQUEUE_<lock_object_name>.
The name of the function module for removing locks is:
DEQUEUE_<lock_object_name>.
Both function modules have the following parameters:
- Field names of the lock object to which the key values to be locked must be copied.
- For every lock field <field>, a parameter X_<field> exists which determines the lock behavior when the initial value is copied. If the initial value is assigned to <field> and X_<field>, then a generic lock is initialized with respect to <field>. If X is assigned to X_<field> then the lock is set with the initial value of <field>.
- A lock is generally removed at the end of the transaction or when the corresponding DEQUEUE function module is called. However, if the transaction has called update routines this is not the case. In this case a parameter must check that the lock has been removed. The parameter SCOPE determines how the lock is sent to the update program. The following values are possible:
- _SCOPE = 1: The lock is not sent to the update program. The lock is removed when the transaction is ended.
- _SCOPE = 2: The lock is sent to the update program. The update program is responsible for removing the lock. The dialog program which requested the lock no longer has an influence on the lock behavior. This is the standard setting for the ENQUEUE function module.
- _SCOPE = 3: The lock is also sent to the update program. The lock must be removed in both the dialog program and by the update program. This is the standard setting for the ENQUEUE function module.
- A parameter MODE_<TAB> exists for each Basis table TAB of the lock object. The lock mode for this table can be set dynamically with this parameter. Valid values for this parameter are S (shared), E (exclusive) and X (exclusive but not cumulative). The lock mode specified when the lock object was created is the default value for this parameter. The default value can however be overruled as required when the function module is called.
If a lock set with a lock mode is to be removed by calling the DEQUEUE function module, this call must have the same value for the parameter MODE_<TAB>.
- Parameter _COLLECT controls whether the lock request or lock release should be performed directly or whether it should first be written to the local lock container.
This parameter can have the following values:
- Initial value
: The lock request or lock release is sent directly to the lock server.
- X
: The lock request or lock release is placed in the local lock container. The lock requests and lock releases collected in this lock container can then be sent to the lock server at a later time as a group by calling the function module FLUSH_ENQUEUE.
The ENQUEUE function module also has the following parameter:
- _WAIT: This parameter determines the lock behavior when a lock conflict occurs. The following values are possible:
- Initial value
: If a lock attempt fails because there is already another lock on the data records, the exception FOREIGN_LOCK is triggered.
- X
: If a lock attempt fails because there is already another lock on the data, the lock attempt is repeated after waiting for a certain time. The exception FOREIGN_LOCK is triggered only if a certain time limit has elapsed since the first lock attempt. The waiting time and the time limit are defined by profile parameters.
The DEQUEUE function module also has the following parameter:
- _SYNCHRON: If X is passed, the DEQUEUE function waits until the entry has been removed from the lock table of the system. Otherwise it is deleted asynchronously, that is, if the lock table of the system is read directly after the lock is removed, the entry in the lock table may still exist.
The ENQUEUE function module can trigger these exceptions:
- FOREIGN_LOCK: A competing lock already exists. You can find out the name of the user holding the lock by looking at system variable SY-MSGV1.
- SYSTEM_FAILURE: This exception is triggered when the ENQUEUE server reports that a problem occurred when setting the lock. In this case, the lock could not be set.
If the exceptions are not processed by the calling program itself, appropriate messages are issued for all exceptions.