Locking is a system which protects data integrity in a multi-user environment. When data is accessed by a user, it is locked so that no other user can edit or delete it. Once items such as tables are locked, no other user can alter them until they are unlocked again. If a user attemplts to lock a table which already has a record locked by a different user, the table lock will fail

Where possible, Equinox handles locking and unlocking automatically. eg:

• Records are locked when they are inserted, edited and deleted
• Records are also locked during reports, queries, batch processes, exports and imports
• Database and workarea definitions and other application items, are locked when they are being modified

However, the following items are not locked automatically. If you want unique access then you must lock them manually, using the Lock statement:

• Records inside subtable blocks
• Whole tables (while running reports, etc)
• Public workareas

You must also unlock them manually, using the Unlock statement.

The argument, ItemList, is a comma-separated list of items to be locked and may contain the following:

• The "Subtable" keyword (locks the current record in the home table and any related records)
• Table names
• Public workarea names

If you omit ItemList, it defaults to Subtable only. Note that if any one of the items in ItemList cannot be locked, then none of them are. An error number is stored in the system workarea SysError.

Locks do not stack and can only be set or released. This means that an item locked twice is unlocked by a single Unlock statement. You can use the IsLockedByMe function to test if an item is already locked.

Note that if a subtable is locked and not specifically unlocked, then it remains locked until the subtable block is closed. Other items remain locked until you switch to a different application, or until the copy of Equinox is closed.

A Lock command can be put on the same record from two different view groups when using query indexes.

A deadlock (or deadly embrace) occurs when two users both require the same two items and each user has one item locked. This may be avoided by locking both items with one Lock statement. The statement will fail and unlock both items.

After the statement is executed, the SysError system workarea may take one of the following values:

• 0 The statement was executed successfully.
• 1 An error occurred.
• 2 The item is already locked by another user and therefore cannot be locked again.

The following example locks the current record in the home table and any related records.

Lock Subtable

The following example locks the Customer table.

Lock Customer

The following example locks the specified public workarea.

Lock MyPublicWorkarea