Locking Objects Explicitly (LOCK Statement)

LOCK Statement: Advantages

Explicit locks protect data while it is being updated in a multi-step SAS program. For example, a nightly update process that uses a DATA step to remove observations that are no longer useful runs PROC SORT to sort the file and PROC DATASETS to re-build the file's indexes. No other users can be allowed to access the file between any of these steps because the SORT and DATASETS procedures will fail if they cannot acquire exclusive access to the file. An explicit lock provides the needed protection.

To set an explicit lock, execute a LOCK statement before the first DATA step to acquire exclusive access to the file. If exclusive access cannot be obtained, the LOCK statement return code &SYSLCKRC is issued to indicate that, and the update program can reschedule the update for a later time, or it can signal an operator or an action that its programmer thinks is appropriate. If the LOCK statement is successful, a user who attempts to access the file before the corresponding LOCK CLEAR statement executes (after the end of the PROC DATASETS step) will be denied access, and the batch update will proceed uninterrupted.

You can use the LOCK statement to obtain exclusive access to the data object and an explicit lock on data libraries, data sets, catalogs, and catalog entries. No other users can read from or write to a data object that you have locked by using this statement.

When you use a LOCK statement to lock a data object, you can open that data object as often as you want to and in any mode that you want. For example, you can create, replace, update, or read from the object, if your PROC or DATA step does not conflict with what is allowed by the engine that the server uses to access the data object. You must first access a SAS library through a server before you can lock that library or any data object in it. Also, you cannot lock a data object that another user has open.

Syntax for the LOCK Statement

LOCK libref<.member-name<.member-type | .entry-name.entry-type>>
<LIST | CLEAR>;

libref

is the name temporarily associated with a SAS library.

member-name

is the name of a member of the referenced SAS library.

member-type

is the type of the SAS file to be locked. Valid values are DATA, VIEW, and CATALOG. The default value is DATA.

If member-type is omitted or is specified as the value DATA or VIEW, two locks are obtained: one on libref.member-name.DATA and the other on libref.member-name.VIEW.

entry-name

is the name of the catalog entry to be locked.

entry-type

is the type of the catalog entry to be locked.

LIST

writes to the SAS log whether the specified data object is locked and by whom. This argument is optional.

CLEAR

releases a lock on the specified data object that was acquired in your SAS session by using the LOCK statement. This argument is optional.

For details about releasing locks, see Clearing an Explicit Lock.

Locking a SAS Library

The following statement locks the SAS library MYLIB.

lock mylib;

Locking a library prevents other users from reading, updating, or deleting existing SAS files in the library or from creating new SAS files in the library. The lock also prevents other users from obtaining a list of files in the library. It does not prevent users from issuing LIBNAME statements to access the library, but it does prevent them from accessing SAS files in the library while it is locked.

Locking a SAS Data Set

The following statements lock the SAS data set FUEL in the library MYLIB. All these statements are equivalent.

lock mylib.fuel;
lock mylib.fuel.data;
lock mylib.fuel.view;

Locking a SAS data set (that is, a SAS data file or a SAS data view) prevents other users from creating, reading, updating, deleting, or renaming a SAS data file and from creating, reading, deleting, renaming, or interpreting a SAS data view.

Beginning with SAS 6.06, a SAS data set can be either a SAS data file (member type DATA) or a SAS data view (member type VIEW). In most SAS programs, it does not matter whether the data comes from a SAS data file or a data view.

Because of this transparency in users' SAS programs, it is important that a SAS data file and a SAS data view that have the same name be locked at the same time. Therefore, when you execute the LOCK statement on one of these data sets, both of them are automatically locked. In the statements given at the beginning of this section, the server locks the SAS data file MYLIB.FUEL.DATA and the SAS data view MYLIB.FUEL.VIEW concurrently. For more information about SAS data sets, see SAS Language Reference: Concepts.

CAUTION:

The LOCK statement does not lock the source data of a data view.

The LOCK statement does not prevent a SAS data view's underlying SAS file (or files) from being read or updated by a SAS library engine or by a SAS view engine when a different view is interpreted in the server session.

Locking a SAS Catalog

The following statement locks the member MYCAT in the library SCLLIB. The member type CATALOG indicates that MYCAT is a SAS catalog.

lock scllib.mycat.catalog;

Locking a member of type CATALOG prevents other users from creating, deleting, or renaming the catalog, or listing the entries in the catalog. It also prevents creating, reading, updating, deleting, or renaming any of the entries in the catalog by other users.

While your SAS catalog or catalogs are locked, you can update an application that uses many different catalog entries. For example, you can execute LOCK statements to ensure exclusive access to the catalogs that contain your application's entries. This ensures that no other users are executing your application while you are updating its entries. After you have updated all the entries and tested your application, you can clear the lock by using the argument CLEAR in a LOCK statement. This allows other users to gain access to your catalogs and to execute your application. For more information, see Clearing an Explicit Lock.

Locking a Catalog Entry

The following statement locks the catalog entry JOHNCBT of type CMAP in the catalog SCLLIB.MYCAT.

lock scllib.mycat.johncbt.cmap;

Locking an entry in a catalog prevents other users from creating, reading, updating, or deleting that entry.

Clearing an Explicit Lock

GENERATED SUBSUBTOPIC TITLE

How you clear an explicit lock depends on the level in the data object hierarchy at which the lock was obtained. There are three ways to clear locks. Each is explained in detail in the sections that follow.

Explicitly lock and unlock each data object that you access.
Explicitly lock lower-level data objects and unlock the higher-level data objects, which implicitly unlocks its lower-level objects.
Explicitly lock a higher-level data object that contains multiple lower-level data objects that you want to access. This allows you to clear the single higher-level lock after you have finished accessing the lower-level objects.

Explicitly Locking and Clearing Each Data Object

When you explicitly lock a specific data object, you must clear each lock individually. Here is an example.

lock educlib.mycat.choice1.menu;
lock educlib.mycat.choice2.menu;

/* Update the two catalog entries */
/* as needed.                     */
lock educlib.mycat.choice1.menu clear;
lock educlib.mycat.choice2.menu clear;

The first LOCK statement in the preceding example sets implicit locks on the SAS library EDUCLIB and on the SAS catalog EDUCLIB.MYCAT. Then it sets an explicit lock on the catalog entry EDUCLIB.MYCAT.CHOICE1.MENU. Because the user already has implicit locks on the catalog and library, the second LOCK statement does not set additional implicit locks before it sets an explicit lock on the catalog entry EDUCLIB.MYCAT.CHOICE2.MENU.

The first LOCK statement that contains the argument CLEAR releases the explicit lock on the catalog entry CHOICE1.MENU, but it does not clear the implicit locks because an entry in the catalog is still locked. The second LOCK statement that contains the argument CLEAR releases the explicit lock on the catalog entry CHOICE2.MENU. Because no catalog entries remain locked, the argument CLEAR releases the implicit lock on the SAS catalog EDUCLIB.MYCAT. Also, because no members of the library are locked, this argument clears the implicit lock on the SAS library EDUCLIB.

Clearing a Higher-Level Data Object to Clear Multiple Lower-Level Objects

You can set explicit locks on data objects at low levels. However, when you clear a higher-level implicit lock, all of the lower-level explicit locks are cleared automatically. Here is an example.

lock educlib.mycat.choice1.menu;
lock educlib.mycat.choice2.menu;

/* Update the two catalog entries */ 
/* as needed.                     */
lock educlib.mycat clear;

The first LOCK statement in the preceding example sets implicit locks on the SAS library EDUCLIB and on the SAS catalog EDUCLIB.MYCAT. Then it sets an explicit lock on the catalog entry EDUCLIB.MYCAT.CHOICE1.MENU. Because the user already has implicit locks on the catalog and the library, the second LOCK statement does not set additional implicit locks before it sets an explicit lock on the catalog entry EDUCLIB.MYCAT.CHOICE2.MENU.

The LOCK statement that contains the argument CLEAR releases the explicit locks on both catalog entries and clears the implicit lock on the SAS catalog. Because no members of the library remain locked, this argument also clears the implicit lock on the SAS library.

Locking a Higher-Level Data Object to Lock Multiple Lower-Level Data Objects and Clearing the Higher-Level Lock

To update several lower-level data objects without having to lock each one separately when all the data objects fall under a single higher-level data object, you can lock the higher-level data object to prevent access by other users to all of the data objects that are included under that higher-level data object.

However, you might need to clear the lock on the higher-level data object before you are finished with your work. For example, a co-worker wants to work on other lower-level data objects under the same higher-level data object. In this instance, you can explicitly lock the lower-level data objects that you need and clear your explicit lock on the higher-level data object. You will retain an implicit lock on the higher-level data object as long as you have lower-level data objects locked.

lock educlib;
/* Update various library members  */
/* and catalog entries.            */

If one of your co-workers needs to work on some SAS files in the library EDUCLIB that you are not updating, you can lock the SAS files in the library EDUCLIB that you need, by using the following statements:

lock educlib.mycat.catalog;
lock educlib.mydata1;
lock educlib.mydata2;

Then, use the following statement to clear your explicit lock on the library to allow your co-worker to use other members of the library:

lock educlib clear;

You retain an implicit lock on the library because you hold explicit locks on three SAS files in the library.

You continue to update entries in the SAS catalog EDUCLIB.MYCAT and the SAS data sets EDUCLIB.MYDATA1 and EDUCLIB.MYDATA2 that you have locked. After you finish your updates, you can issue one LOCK statement to clear your explicit locks on the three library members and your implicit lock on the library, as follows:

lock educlib clear;

Listing Lock Status

SAS/SHARE delivers an informational or an error message if you attempt to access a data object that is already in use or that is locked by another operation. The message is issued in the following form:

object is status by whom

object

SAS library | SAS data member | SAS data file observation or catalog

status

locked for exclusive access | in use | not locked

whom

you | user user(server-connection-number) | n other users of this server | task FSEDIT (server-connection-number)

The messages explain the status of the data object that is being accessed. To recover, you usually must wait until the data object is available or find out when the data object will be available by talking to the person who has locked the object. Here are some examples of messages.

In the first example, the SAS library that is referenced by MYLIB is locked by user SASUSER(1). A lock on a library prevents other users from reading, updating, or deleting existing SAS files or from creating new SAS files in that library. The lock also prevents other users from obtaining a list of files in the library. The lock does not prevent users from issuing LIBNAME statements to access the library, but it does prevent them from using SAS files in the library while it is locked. You must wait for user SASUSER(1) to unlock the library before you can use it.

NOTE: SASUSER.MYLIB is not locked or in use by you, 
but is locked for exclusive access by user sasuser(1).

In this example, because two users are already accessing the MYCAT member in the MYLIB library, you can infer that no locks have been set on the catalog, and that users are reading catalog entries or adding entries to the catalog. Although you can browse the catalog or add entries to the catalog, you cannot attempt to lock the catalog until there are no others using it.

NOTE: MYLIB.MYCAT.CATALOG is not locked or in use by you,
but is in use by 2 other users of this server.

The catalog entry MYCATENTRY of type CMAP in the catalog MYLIB.MYCAT is not locked by user SASUSER(1). This message results when user SASUSER attempts to unlock a catalog entry that another client has locked.

NOTE: MYLIB.MYCAT.MYCATENTRY.CMAP is not locked by sasuser(1).

The following LOCK statement lists in the SAS log whether a specified data object is locked and by whom. The format used in the LOCK statement for listing lock status is

data-object is status by whom

lock educlib.mycat.catalog list;
EDUCLIB is locked by sasuser

Return Codes for the LOCK Statement

The SAS macro variable SYSLCKRC contains the return code from a LOCK statement. A nonzero value in SYSLCKRC results when you use a LOCK statement with the argument LIST to list a lock.