SAP ABAP LOCKS

Using the SAP Locking Facility

Definition of an SAP lock

The description of an SAP lock to a table is made via the lock condition
and the lock mode.

The lock condition is a logical condition for the lines of the table to
be locked. It describes the area of the table which the lock is to
protect from competitive access. To avoid the administration of the lock
becoming complicated, the lock condition can not be formulated as freely
as the WHERE clauses: only fully qualified key fields related by AND
may appear in the condition.

Via the lock mode you define which operations on the table are to be
protected by the lock. The lock modes available are:


o Read lock (shared lock)
protects read access to an object. The read lock allows other
transactions read access but not write access to the locked area of
the table.

o Write lock (exclusive lock)
protects write access to an object. The write lock allows other
transactions neither read nor write access to the locked area of the
table.

o Enhanced write lock (exclusive lock without cumulation)
works like a write lock except that the enhanced write lock also
protects from further accesses from the same transaction.

In order to be able to define SAP locks for a table, you must first
create a lock object for the table via Development->Dictionary.
If the data for an application object is distributed among several
database tables, it is often necessary to be able to lock these tables
simultaneously. It is therefore possible to include several tables in a
lock object, althought they must be related via appropriate foreign key
relationships. The tables involved in a lock object are also known as
its base tables.

Requesting an SAP lock

When a lock object obj is activated, two function modules (see CALL
FUNCTION) with the names ENQUEUE_obj and DEQUEUE_obj are generated.
These lock modules are used to explicitly request or release SAP locks
in an ABAP program. The SAP lock concept thus assumes a cooperative
behavior by all the programs involved. This means that access from
programs that do not call the specified modules are not protected.

The lock conditions and lock modes for the requested locks are defined
by the IMPORT parameters of the lock modules.

The lock conditions are defined by the lock parameters of the lock
object. If the lock object has only one base table, each primary key
field of the table corresponds to exactly one lock parameter. Apart from
this, a lock parameter corresponds to a group of primary key fields that
are identified by the join conditions. For each lock parameter par, the
lock modules have two IMPORT parameters with the names par and X_par.
The lock condition is defined by these parameters. If a parameter par is
not defined or if it is defined with the initial value, this means that
the corresponding key fields should be locked generically. If you really
want to lock the key field with the initial value, you must also define
the parameter X_par with the value 'X'.

To define the lock modes, the lock modules have an IMPORT parameter
MODE_tab for each base table tab, with which the lock mode for this
table can be defined. A default value must already be set for this
parameter in the definition of the lock object.

You cannot set an SAP lock by finding all the lines of the table which
satisfy the lock condition and marking them as locked. Rather, the lock
condition and lock mode for a table are entered in a special lock table.

Collision of SAP locks

Before a requested SAP lock is entered in the lock table, a check is
made on whether it collides with a lock already entered in the lock
table. Two locks on the same table collide if their lock conditions
overlap and their lock modes are incompatible.

The overlapping of two lock conditions on one table is a purely logical
attribute. It occurs if a row of the table which meets both conditions
could exist. It is therefore irrelevant for the overlap whether or not
such a row really exists in the table.

The following rules apply for the compatability of locks: An enhanced
write lock is incompatible with all other locks, a write lock is
incompatible with all locks requested by other transactions, and a read
lock is compatible with all other read locks.

If locks are requested with the help of a lock object that has several
base tables, all locks requested are regarded as colliding as soon as a
collision is recognized for just one of the base tables involved.

Behaviour in a collision

An SAP lock that collides with an existing lock cannot be granted and is
therefore not entered in the lock table.

With the help of the IMPORT parameter _WAIT, you can determine how the
ENQUEUE module should behave if the lock it requests collides with an
existing lock. If this parameter has the value ' ', the exception
FOREIGN_LOCK is triggered. The system field SY-MSGV1 is supplied with
the user set by the the colliding lock.
If the parameter has the value 'X', the lock request is repeated at set
intervals until either the lock can be granted or an internal system
time limit is exceeded. In the second case the exception FOREIGN_LOCK is
also triggered.

Duration of an SAP lock

At the end of a transaction, this automatically releases all the SAP
locks it holds. Note, however, that if an update routine is called by
the transaction, locks can be transferred from the ordering transaction
to the update routine. In the same way, these locks are automatically
released at the end of the update routine. Via the IMPORT parameter _SCOPE of the ENQUEUE module, you can determine
whether a lock should be transferred to the update routine if one is
called.
If _SCOPE has the value '1', the lock remains with the the ordering
transaction. If _SCOPE has the value '2', the lock can pass to the
update routine. Finally, if the parameter has the value '3', two locks
of the same kind will be generated, one of which passes to an update
routine when one is called.

By calling the DEQUEUE module, a transaction can explicitly release a
lock which it holds. The lock parameter and lock mode must be supplied
with the same value as for calling the ENQUEUE module. If the parameter
_SCOPE has the value '1', only one lock is released which cannot pass to
an update routine. If the parameter has the value '2', only one lock is
released which can pass to the update program. Finally, if the parameter
has the value '3', both locks can be released. Note however that a
transaction can release neither a lock which has already been
transferred to the update program, nor a lock which is held by another
transaction.
Via the IMPORT parameter _SYNCHRON you can control whether the release
of the lock should be synchronous or asynchronous. If this parameter has
the value 'X', the module waits until the lock has really been removed
from the lock table. If the parameter has the value ' ', a requst for
deletion of the lock from the lock table is sent to the application server which manages the lock table, and then the execution of the
program is immediately continued.

Monitoring of SAP locks

The transaction Display and delete locks monitors the SAP locks.

LOCK PARAMETERS

Definition of the lock parameters of a lock object:

The lock parameters of a lock object are used when the relevant lock
modules are called to allocate the values to the lock arguments of the
lock object.

For each parameter field of the lock object (at most) one lock parameter
can be defined.
The name of the lock parameter generally corresponds to the name of the
relevant parameter field. The name can however be freely chosen as long
as it adheres to the name conventions for lock parameters.

For each parameter of the lock objects the relevant lock modules
receive IMPORT parameters and X_. The parameter
possesses the relevant parameter field as reference field. If the IMPORT
parameter is filled with a value in a call, all the lock fields
equivalent to the parameter field in the corresponding lock arguments
are filled with that value. If the parameter remains initial, generic
locking takes place on these lock fields. If however the flag X_ is
set, initial also means that the corresponding lock field should
be locked at initial value.

NAMING CONVENTIONS OF LOCK OBJECTS

When naming the lock parameters of a lock object, the following
conventions apply:

1. No lock parameter may appear twice in a lock object.

2. Each lock parameter name must adhere to the name conventions for
table fields.

3. No lock parameter name may begin with the prefix 'X_'.

4. No lock parameter name may begin with the prefix 'MODE_'.

5. No lock parameter name may correspond to the name of a Basis table.

6. The names 'DDENQ_LIKE' and 'DD26E' are not allowed for lock
parameters.

LOCK FIELDS

Definition of the lock fields of a lock object:

The lock fields of a lock object are the key fields of the base tables
of the lock object for which a lock mode is defined.
The only exception to this rule is when the lock object only has one
base table and this base table is a structure without key fields. In
this case the lock fields of lock object are precisely those parameter
fields of the lock object for which a lock parameter is defined. (Here
too a lock mode must be defined for this base table.)

The lock argument for a table is now constructed from the lock fields
within this table. By virtue of the join conditions which were used to
construct the lock object, each lock field is equivalent to one
parameter field. If a lock parameter is defined for this parameter
field, the content of the lock field in the lock argument is controlled
via this lock parameter. Otherwise only generic locking is possible for
this lock field.

LOCK MODES

Definition of the lock modes of a lock object:
In the definition of a lock object one of the three lock modes
'S'(shared lock), 'E'(exclusive lock) or 'X'(exclusive lock without
accumulation) can be specified for each Basis table.

For each Basis table , for which a lock mode was specified, the
lock modules belonging to the lock object receive an IMPORT parameter
MODE_. This has the specified value as default. In a call this can
be changed to one of the other two values. This value is then entered in
the lock granule for the table. Basis tables for which no lock mode is
defined cannot be locked with the lock object.

LOCK GRANULE

Definition of the lock granule of a lock object:

For each base table of a lock object for which a lock mode is defined, a
lock granule is formed which consists of the name of the table, the
current lock mode and the lock argument for this base table. These lock
granules are the information which is transmitted to the lock server
when a lock module for a lock object is called.


DATABASE LOCKING

Database Locking

Any database permitting simultaneous access by several users requires a
locking mechanism to manage and synchronize access. The tasks of this
mechanism are to:

- protect data objects which a transaction is currently changing
or reading from being changed by other transactions at the same
time.

- protect a transaction against reading data objects which have
not yet been fully written back by another transaction.

How is locking achieved?

Database systems do not usually provide commands for explicitly setting
or releasing locks. Therefore, prior to executing the database
operation, database locks are set implicitly when one of the Open SQL
statements SELECT SINGLE FOR UPDATE, INSERT, UPDATE, MODIFY, DELETE is
called (or when the corresponding Native SQL statement is called).

What is locked?

Database systems set physical locks on all lines affected by a database
call. In the case of SELECT, these are the selected entries. In the case
of UPDATE, DELETE, INSERT and MODIFY, they are the entries to be
changed, deleted, etc.


It is not always the table line which is locked. Tables, data pages and
index pages can also be locked. The units to be locked depend on the
database system you are using and the access being performed.

Lock mode

In principle, one type of lock is enough to control conflicting data
accesses. However, to achieve a greater degree of parallel running among
transactions, database systems use several types of locks. These can
vary from system to system, but the following two are sufficient to gain
an understanding of how locking works:

o Read lock (shared lock)

Read locks permit the setting of further read locks, but prevent
other transactions from setting write locks for the objects in
question.

o Write lock (exclusive lock)

Write locks do not allow other transactions to set any locks for the
objects in question.

How are locks set?

You set write locks with the Open SQL statements SELECT SINGLE FOR
UPDATE, INSERT, UPDATE, MODIFY and DELETE (or with the appropriate
Native SQL statements).

The decision as to whether the Open SQL command SELECT or the
appropriate Native SQL command sets the lock or not depends on the
isolation level of the transaction. Two possible levels are
distinguished:

o Uncommitted read (or dirty read)

A program using an "uncommitted read" to read data does not set
locks on data objects and does not obey them. For this reason,
programmers must bear in mind that their programs might read data
which has not yet been finally written to the database with a database commit and could thus still be deleted from the database by
a database rollback. "Uncommitted read" is the default setting in
the R/3 system for the isolation level.

o Committed read

A program using a "committed read" to read data obeys the locks on
data objects. This means that programmers can be sure that their
programs will read only data which has been finally written to the
database with a database commit. You can set the isolation level in
the R/3 system to "committed read" by calling the function module
DB_SET_ISOLATION_LEVEL. The next database commit or rollback will
reset the isolation level to its default setting, as will calling
the function module DB_RESET_ISOLATION_TO_DEFAULT.

Many database systems employ additional isolation levels (e.g. "cursor
stability" and "repeatable read"). These work like "committed read", but
the read lock is retained until the next data object is read or until
the database cursor is closed. Since these isolation levels are not
sufficiently standardized, they are not currently used in the R/3
System.

If a transaction cannot lock an object because it is already locked by another transaction, it waits until the other transaction has released
the lock. This can result in a deadlock. A deadlock occurs, for example,
when two transactions are waiting for a lock held by the other.


How long is a lock retained?

In database locking, all locks are released no later than the next database commit or rollback (see Logical Unit of Work (LUW)). Read locks
are usually retained for a shorter period. Sometimes, this causes
problems for transactions which cover several dialog steps:

In the above example, further dialog steps follow the selection of a
flight with free seats to enter additional data for the reservation.
Here, the adding of the flight reservation occurs in a different LUW
than the original selection of the flight. Database locking does not
prevent another transaction from booking this flight in the meantime.
This means that the scheduled booking may have to be canceled after all.

From the user's point of view, this solution is very inconvenient. To
avoid this scenario, a flight reservation system must use the SAP
locking mechanism (see SAP Locking) to lock the flight for the entire
duration of the transaction.

MESSAGES

MESSAGE Syntax Diagram

Variants:
1. MESSAGE xnnn.
2. MESSAGE ID id TYPE mtype NUMBER n.
3. MESSAGE xnnn(mid).

Effect Sends a message. Messages are stored in table T100, and can be
maintained using Transaction SE91. They are fully integrated
in the forward navigation of the ABAP Workbench.

The ABAP runtime environment handles messages according to the
message type specified in the MESSAGE statement and the
context in which the message is sent. There are six kinds of
message type:

A (Abend) Termination
E (Error) Error
I (Info) Information
S (Status) Status message
W (Warning) Warning
X (Exit) Termination with short dump
Messages are used primarily to handle user input on screens.


There is an Example program for messages that displays how
messages behave in various contexts.

Variant 1 MESSAGE xnnn.

Additions:
1. ... WITH f1 ... f4
2. ... RAISING exception
3. ... INTO f

Effect Sends the message nnn from message class i with type x. You
can specify the message class i in the MESSAGE-ID addition to
the REPORT, PROGRAM or other introductory statement.

Example
MESSAGE I001.

- If you want to use a different message class, you can
specify one in parentheses after the message number:
MESSAGE I001(SU).
- When the statement is executed, the following system
variables are set:
* SY-MSGID (Message class)
* SY-MSGTY (Message type)
* SY-MSGNO (Message number)

Note Runtime errors:

- MESSAGE_TYPE_UNKNOWN: Message type unknown
- MESSAGE_TYPE_X: Deliberate program termination with short
dump

TRANSATIONS


1.SCREEN NUMBERS

The screen number identifies a screen within a program (module pool,
report).

Screen numbers can be up to 4 characters long, all of which must be
digits. Screen numbers from 9000 are reserved for customer-specific
screens.

The use of screen numbers is namespace-dependent. For screens in
programs in the SAP namespace, numbers less than 9000 are reserved for
SAP screens, numbers between 9000 and 9500 are reserved for SAP
partners, and numbers greater than 9500 are for customers.