Note that each user is informed only of bids placed by the other user, and not of their own bids. Note also that USER02 was alerted to the fact that item PS447 (the subject of the previous bidding by USER02) had been closed. So the auction system really does work, and quite well, as a matter of fact! 3.1 DBMS_PIPE: Communicating Between Sessions 4. User Lock and Transaction Management Copyright (c) 2000 O'Reilly & Associates. All rights reserved. [Appendix A] What's on the Companion Disk? 3.2.3 DBMS_ALERT Examples 201 Chapter 4 202 4. User Lock and Transaction Management Contents: DBMS_LOCK: Creating and Managing Resource Locks DBMS_TRANSACTION: Interfacing to SQL Transaction Statements Complex, multiuser applications that manage new types of resources (objects, BLOBs, etc.) require the ability to manage contention for those resources. The Oracle database manages concurrent, multiuser contention for data using sophisticated locking mechanisms. This chapter describes two packages that provide interfaces to the Oracle lock and transaction management facilities: DBMS_LOCK Oracle now provides developers with the "keys" to its locking mechanisms through the DBMS_LOCK package; watch out, though, this deceptively powerful package might also put your applications to "sleep!" DBMS_TRANSACTION Complements DBMS_LOCK by providing a programmatic interface to a number of transaction−oriented SQL statements. 4.1 DBMS_LOCK: Creating and Managing Resource Locks The DBMS_LOCK package makes Oracle lock management services available to PL/SQL developers. User locks created and managed using DBMS_LOCK are functionally identical to native RDBMS locks, even down to the various sharing modes and the deadlock detection. Locks are typically used to provide serialized access to some resource. Within the database, the most familiar use of locking is to prevent multiple users from updating the same row in a table at the same time. Using DBMS_LOCK, applications can be written that serialize and coordinate access or usage of nondata resources. For instance, user locks can be used to do the following: • Provide exclusive access to an external device or service (e.g., a printer) • Coordinate or synchronize parallelized applications • Disable or enable execution of programs at specific times • Detect whether a session has ended a transaction using COMMIT or ROLLBACK 4.1.1 Getting Started with DBMS_LOCK The DBMS_LOCK package is created when the Oracle database is installed. The dbmslock.sql script (found in the built−in packages source code directory, as described in Chapter 1, Introduction) contains the source code for this package's specification. This script is called by catproc.sql, which is normally run immediately after database creation. The script creates the public synonym DBMS_LOCK for the package. Under Oracle7, no privileges are automatically granted on DBMS_LOCK. Under Oracle8, the EXECUTE_CATALOG_ROLE role is granted EXECUTE privilege on DBMS_LOCK. Thus, the DBMS_LOCK programs are not generally available to users. Access to DBMS_LOCK is obtained by granting EXECUTE privilege explicitly to users or roles that require use of the package. 4. User Lock and Transaction Management 203 4.1.1.1 DBMS_LOCK programs Table 4.1 lists the programs available in the DBMS_LOCK package. Table 4.1: DBMS_LOCK Programs Name Description Use in SQL? ALLOCATE_UNIQUE Generates a unique lock ID for a given lock name No CONVERT Converts lock to specified mode No RELEASE Releases previously acquired lock No REQUEST Requests lock with specified mode No SLEEP Suspends the session for a specified time No DBMS_LOCK does not declare any package exceptions, and none of its programs assert a purity level with the RESTRICT_REFERENCES pragma. 4.1.1.2 DBMS_LOCK nonprogram elements DBMS_LOCK declares a number of constants, most of which identify specific locking modes. Table 4.2 describes these elements. Table 4.2: DBMS_LOCK Declared Constants Constant Description nl_mode CONSTANT INTEGER Null lock mode ss_mode CONSTANT INTEGER Sub−shared lock mode sx_mode CONSTANT INTEGER Sub−exclusive lock mode s_mode CONSTANT INTEGER Shared lock mode ssx_mode CONSTANT INTEGER Sub−shared exclusive lock mode x_mode CONSTANT INTEGER Exclusive lock mode maxwait CONSTANT INTEGER Used as default for timeout parameters 4.1.1.3 Lock compatibility rules A lock held by one user session in a certain mode may prevent another session from being able to obtain that lock in the same or another mode. There are lock compatibility rules determining the success or failure of acquiring and converting locks from one mode to another, depending on the modes in which the same lock is held by other sessions. Table 4.3 indicates the compatibility rules for the various lock modes. The HELD MODE column indicates the mode in which the lock is currently held by some session. The other columns indicate whether the lock can be obtained by other sessions in the mode specified by the column header. Table 4.3: Lock Mode Compatibility [Appendix A] What's on the Companion Disk? 4.1.1 Getting Started with DBMS_LOCK 204 HELD MODE GET NL GET SS GET SX GET S GET SSX GET X NL Succeed Succeed Succeed Succeed Succeed Succeed SS Succeed Succeed Succeed Succeed Succeed Fail SX Succeed Succeed Succeed Fail Fail Fail S Succeed Succeed Fail Succeed Fail Fail SSX Succeed Succeed Fail Fail Fail Fail X Succeed Fail Fail Fail Fail Fail 4.1.2 The DBMS_LOCK Interface This section contains descriptions of all of the procedures and functions available through DBMS_LOCK. 4.1.2.1 The DBMS_LOCK.ALLOCATE_UNIQUE procedure The ALLOCATE_UNIQUE procedure returns a unique "handle" to a lock specified by the lockname parameter. The handle can be used to safely identify locks in calls to other DBMS_LOCK programs. Using lockhandles avoids the potential for lock identifier collisions that exists when identifiers are determined by applications. The header for this program follows: PROCEDURE DBMS_LOCK.ALLOCATE_UNIQUE (lockname IN VARCHAR2 ,lockhandle OUT VARCHAR2 ,expiration_secs IN INTEGER DEFAULT 864000); Parameters for this procedure are summarized in the following table. Parameter Description lockname Name of the lock lockhandle Unique handle to lock by name expiration_secs Length of time to leave lock allocated The program does not raise any package exceptions. 4.1.2.1.1 Restrictions Note the following restrictions on calling ALLOCATE_UNIQUE: • Lock names can be up to 128 characters in length and are case−sensitive. • Lock names must not begin with "ORA$", as these names are reserved for use by Oracle Corporation. • The ALLOCATE_UNIQUE procedure always performs a COMMIT, so it cannot be called from a database trigger. 4.1.2.1.2 Example The following function returns the lockhandle of a specific named lock. It calls ALLOCATE_UNIQUE only if the lockhandle has not already been determined, and avoid the COMMIT unless it is necessary. The function manipulates global variables and thus needs to be included in a PL/SQL package. [Appendix A] What's on the Companion Disk? 4.1.2 The DBMS_LOCK Interface 205 . resources. The Oracle database manages concurrent, multiuser contention for data using sophisticated locking mechanisms. This chapter describes two packages that provide interfaces to the Oracle lock. Started with DBMS_LOCK The DBMS_LOCK package is created when the Oracle database is installed. The dbmslock.sql script (found in the built−in packages source code directory, as described in Chapter. script creates the public synonym DBMS_LOCK for the package. Under Oracle7 , no privileges are automatically granted on DBMS_LOCK. Under Oracle8 , the EXECUTE_CATALOG_ROLE role is granted EXECUTE privilege