SAS/SHARE User's Guide

Locking Objects Explicitly (LOCK Statement)

A classic case in which explicit locks protect data while it is being updated is a multi-step SAS program. For example, consider a nightly update process that consists of a DATA step that removes observations that are no longer useful and then 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. Before the first DATA step, execute a LOCK statement to acquire exclusive access to the file. If exclusive access cannot be obtained, the LOCK statement return code (&SYSLCKRC) indicates that, and the update program can re-schedule 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 an explicit lock on the following data objects:

data library

data set

catalog

catalog entry.

When you use a LOCK statement, you have exclusive access to the data object. No other clients can read or write to a data object that you have locked by using this statement. You cannot lock a data object that another client has open.

When you use a LOCK statement to lock a data object, you can open that data object as often as you want and in any mode that you want. For example, you can create, replace, update, or read the object, as long as 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 data library through a server before you can lock that library or any data object in it.

The syntax for the LOCK statement follows:

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

The LOCK statement takes the following arguments:

libref

is a valid SAS name that serves as a symbolic link to a SAS data library.

member-name

is a valid SAS name that specifies a member of the referenced SAS data 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 use of the LOCK statement. This argument is optional.

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

Locking a SAS Data Library

This statement locks the SAS data library that is referenced by MYLIB.

lock mylib;

Locking the 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 using SAS files in the library while it is locked.

Locking a SAS Data Set

These statements lock the SAS data set FUEL that is referenced by MYLIB. These three statements are equivalent to each other.

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

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

Since Release 6.06 of SAS software, 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 to lock both the SAS data file and the SAS data view by the same name at the same time. When you execute the LOCK statement on one of these data sets, it automatically locks both of them. In the preceding example, the server locks the SAS data file MYLIB.FUEL.DATA and the SAS data view MYLIB.FUEL.VIEW. For more information about SAS data sets, see SAS Language Reference: Concepts.

CAUTION:: The LOCK statement does not affect 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 SAS session.

Locking a SAS Catalog

This statement locks the member MYCAT in the library SCLLIB. MYCAT is a SAS catalog, as indicated by the member type 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 other users from creating, reading, updating, deleting, or renaming any of the entries in the catalog.

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. By doing this, you can be sure that no other users are executing your application while you are in the middle of updating its entries. After you have updated all the entries and tested your application, you clear the lock by using the LOCK statement and the CLEAR argument. This allows other users to gain access to your catalogs and to execute your application. For information about the CLEAR argument, see Clearing an Explicit Lock.

Locking a Catalog Entry

This 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

How you clear an explicit lock depends on the level in the data object hierarchy at which the lock was obtained. You can use one of three methods to clear locks:

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. Consequently, you can clear the single higher-level lock after you have finished accessing the lower-level objects.

Explanations of these methods follow.

Explicitly Locking and Unlocking Each Data Object

You obtain an explicit lock on a specific data object and you clear each lock individually. Examples follow:

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 sets implicit locks on the SAS data library EDUCLIB and on the SAS catalog EDUCLIB.MYCAT. It then 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 CLEAR argument 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 CLEAR argument releases the explicit lock on the catalog entry CHOICE2.MENU. Because no catalog entries remain locked, the CLEAR argument releases the implicit lock on the SAS catalog EDUCLIB.MYCAT. Also, because no members of the library are locked, it clears the implicit lock on the SAS library EDUCLIB.

Unlocking One Higher-Level Data Object for Multiple Lower-Level Objects

You set explicit locks on data objects at low levels. Clear a higher-level implicit lock to cause all of the lower-level explicit locks to be cleared automatically. Examples follow:

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 sets implicit locks on the SAS data library EDUCLIB and on the SAS catalog EDUCLIB.MYCAT. It then 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 CLEAR argument 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, it also clears the implicit lock on the SAS library.

Locking One Higher-Level Data Object for Access to Multiple Lower-Level Data Objects and Clearing the Single Higher-Level Lock

To update several lower-level data objects without individually locking each one when all these 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 the higher-level data object.

However, you may 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 case, you can acquire explicit locks on the lower-level data objects that you need, and then 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, for example,

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

Now, one of your co-workers needs to work on some SAS files in the library EDUCLIB that you are not updating. So, you lock the SAS files in the library EDUCLIB that you do need, as in the following example:

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

Then, you 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 to clear your implicit lock on the library as follows:

  lock educlib clear;

Listing Locks

You can list to the SAS log the status of the specified data object - whether it is locked and by whom. The format for listing lock status follows:

data-object is status by whom

Example:

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 the LOCK statement. The following actions result in a non-zero value in SYSLCKRC:

You try to lock a data object but cannot obtain the lock (for example, the data object was already in use or is locked by another user).
You use a LOCK statement with the LIST argument to list a lock you do not have.
You use a LOCK statement with the CLEAR argument to release a lock you do not have.

For more information about the SYSLCKRC SAS macro variable, see SAS Guide to Macro Processing.

Chapter Contents
Previous
Next
Top of Page