HP OpenVMS Systems Documentation

OpenVMS Programming Concepts Manual

The previous maximum value for the number of sub-resources or sub-locks in a resource or lock tree (parent/children relationships) was 65535. The internal structures were reorganized from word to longword counters, which can handle sub-resource and sub-lock counts up to the current architectural limits of the lock manager. No programming or interface changes were made. As a result, SS$_EXDEPTH errors no longer occur for exceeding the sub-locks or sub-resources limit.

The maximum number of locks on a single resource is limited to 65,535. If your program attempts to exceed this limit, SS$_EXDEPTH will still be returned.

In a mixed-version OpenVMS Cluster, only nodes running OpenVMS Version 7.1 or higher are able to handle these large lock trees. Large scale locking applications should be restricted to running on a subset of nodes running OpenVMS Version 7.1, or the entire cluster should be upgraded to OpenVMS Version 7.1 to avoid unpredictable results.

7.3.9.3 Resource Hash Table

The resource hash table is an internal OpenVMS lock manager structure used to do quick lookups on resource names without a lengthy interactive search. Like all such tables, it results in a tradeoff of consuming memory in order to speed operation. A typical tuning goal is to have the resource hash table size (RESHASHTBL system parameter) about four times larger than the total number of resources in use on the system. Systems that have memory constraints or are not critically dependent on locking speed could set the table to a smaller size.

Previously, the limit for the RESHASHTBL was 65535, based on both the word field used for the parameter and the algorithm used to develop the hash index. This limit has been removed. The new maximum for the RESHASHTBL is 16,777,216 (2²⁴), which is the current architectural maximum for the total number of resources possible on the system.

No external changes are apparent from this modification. Large memory systems that use very large resource namespaces can take advantage of this change to gain a performance advantage in many locking operations. There is no mixed-version OpenVMS Cluster impact related to this change.

7.3.9.4 LOCKIDTBL System Parameter

The lock ID table is an internal OpenVMS lock manager structure used to find the relevant data structures for any given lock in the system. On OpenVMS Alpha, the lock ID table is allowed to expand up to the LOCKIDTBL_MAX system parameter limit. When the table is filled with current locks, the lock request is rejected with an error of SS$_NOLOCKID. This usually results in a system failure (LCKMGRERR bugcheck) as soon as a privileged system application receives such an error.

On OpenVMS VAX, however, this behavior was modified to allow for continued expansion of the lock ID table and was not constrained by LOCKIDTBL_MAX, as on OpenVMS Alpha.

With OpenVMS Version 7.1, both Alpha and VAX platforms dynamically increase the lock ID table as usage requires and if sufficient physical memory is available. The default, minimum, and maximum values for the LOCKIDTBL system parameter now allow large single tables for lock IDs. The maximum number of locks is now regulated by the amount of available nonpaged pool instead of by both nonpaged pool and the LOCKIDTBL_MAX system parameter.

The LOCKIDTBL_MAX parameter is now obsolete. In its place, an appropriate maximum value based on the total available memory is calculated at boot time and stored as the value for the parameter. Inputs (via MODPARAMS or SYSGEN) are ignored.

In addition, the lock ID table itself is now located in S2 space for OpenVMS Alpha, to avoid using large amounts of S0 space in large memory systems.

There are no visible changes for these modifications.

7.4 Queuing Lock Requests

You use the SYS$ENQ or SYS$ENQW system service to queue lock requests. SYS$ENQ queues a lock request and returns; SYS$ENQW queues a lock request, waits until the lock is granted, and then returns. When you request new locks, the system service call must specify the lock mode, address of the lock status block, and resource name.

The format for SYS$ENQ and SYS$ENQW is as follows:

SYS$ENQ(W) ([efn] ,lkmode ,lksb ,[flags] ,[resnam] ,[parid] ,[astadr]
,[astprm] ,[blkast] ,[acmode] ,[rsdm_id] ,[nullarg])

The following example illustrates a call to SYS$ENQW:

#include <stdio.h>
#include <descrip.h>
#include <lckdef.h>

/* Declare a lock status block */

struct lock_blk {
                  unsigned short  condition,reserved;
                  unsigned int lock_id;
}lksb;

   .
   .
   .
        unsigned int status, lkmode=LCK$K_PRMODE;
        $DESCRIPTOR(resource,"STRUCTURE_1");

/* Queue a request for protected read mode lock */
        status = SYS$ENQW(0,     /* efn - event flag */
                 lkmode,         /* lkmode - lock mode requested */
                 &lksb,          /* lksb - lock status block */
                 0,              /* flags */
                 &resource,      /* resnam - name of resource */
                 0,              /* parid - parent lock id */
                 0,              /* astadr - AST routine */
                 0,              /* astprm - AST parameter */
                 0,              /* blkast - blocking AST */
                 0,              /* acmode - access mode */
                 0);             /* rsdm_id - resource domain id */

}

In this example, a number of processes access the STRUCTURE_1 data structure. Some processes read the data structure; others write to the structure. Readers must be protected from reading the structure while it is being updated by writers. The reader in the example queues a request for a protected read mode lock. Protected read mode is compatible with itself, so all readers can read the structure at the same time. A writer to the structure uses protected write or exclusive mode locks. Because protected write mode and exclusive mode are not compatible with protected read mode, no writers can write the data structure until the readers have released their locks, and no readers can read the data structure until the writers have released their locks.

Table 7-3 shows the compatibility of lock modes.

7.4.1 Example of Requesting a Null Lock

The program segment in Example 7-1 requests a null lock for the resource named TERMINAL. After the lock is granted, the program requests that the lock be converted to an exclusive lock. Note that, after SYS$ENQW returns, the program checks the status of the system service and the status returned in the lock status block to ensure that the request completed successfully. (The lock mode symbols are defined in the $LCKDEF module of the system macro library.)

! Define lock modes
INCLUDE '($LCKDEF)'
! Define lock status block
STRUCTURE /STATUS_BLOCK/
 INTEGER*2 LOCK_STATUS,
2          NULL
 INTEGER*4 LOCK_ID
END STRUCTURE
RECORD /STATUS_BLOCK/ IOSTATUS
   .
   .
   .
! Request a null lock
STATUS = SYS$ENQW (,
2                  %VAL(LCK$K_NLMODE),
2                  IOSTATUS,
2                  ,
2                  'TERMINAL',
2                  ,,,,,)
IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS))
IF (.NOT. IOSTATUS.LOCK_STATUS)
2    CALL LIB$SIGNAL (%VAL(IOSTATUS.LOCK_STATUS))
! Convert the lock to an exclusive lock
STATUS = SYS$ENQW (,
2                  %VAL(LCK$K_EXMODE),
2                  IOSTATUS,
2                  %VAL(LCK$M_CONVERT),
2                  'TERMINAL',
2                  ,,,,,)
IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS))
IF (.NOT. IOSTATUS.LOCK_STATUS)
2    CALL LIB$SIGNAL (%VAL(IOSTATUS.LOCK_STATUS))

For more complete information on the use of SYS$ENQ, refer to the OpenVMS System Services Reference Manual.

7.5 Advanced Locking Techniques

The previous sections discuss locking techniques and concepts that are useful to all applications. The following sections discuss specialized features of the lock manager.

7.5.1 Synchronizing Locks

The SYS$ENQ system service returns control to the calling program when the lock request is queued. The status code in R0 indicates whether the request was queued successfully. After the request is queued, the procedure cannot access the resource until the request is granted. A procedure can use three methods to check that a request has been granted:

• Specify the number of an event flag to be set when the request is granted, and wait for the event flag.
• Specify the address of an AST routine to be executed when the request is granted.
• Poll the lock status block for a return status code that indicates that the request has been granted.

These methods of synchronization are identical to the synchronization techniques used with the SYS$QIO system services (described in Chapter 23).

The $ENQW macro performs synchronization by combining the functions of the SYS$ENQ system service and the Synchronize (SYS$SYNCH) system service. The $ENQW macro has the same arguments as the $ENQ macro. It queues the lock request and then places the program in an event flag wait state (LEF) until the lock request is granted.

7.5.2 Notification of Synchronous Completion

The lock management services provide a mechanism that allows processes to determine whether a lock request is granted synchronously, that is, if the lock is not placed on the conversion or waiting queue. This feature can be used to improve performance in applications where most locks are granted synchronously (as is normally the case).

If the flag bit LCK$M_SYNCSTS is set and a lock is granted synchronously, the status code SS$_SYNCH is returned in R0; no event flag is set, and no AST is delivered.

If the request is not completed synchronously, the success code SS$_NORMAL is returned; event flags or AST routines are handled normally (that is, the event flag is set, and the AST is delivered when the lock is granted).

7.5.3 Expediting Lock Requests

A request can be expedited (granted immediately) if its requested mode, when granted, does not block any currently queued requests from being granted. The LCK$M_EXPEDITE flag is specified in the SYS$ENQ operation to expedite a request. Currently, only NLMODE requests can be expedited. A request to expedite any other lock mode fails with SS$_UNSUPPORTED status.

7.5.4 Lock Status Block

The lock status block receives the final completion status and the lock identification, and optionally contains a lock value block (see Figure 7-4). When a request is queued, the lock identification is stored in the lock status block even if the lock has not been granted. This allows a procedure to dequeue locks that have not been granted. For more information about the Dequeue Lock Request (SYS$DEQ) system service, see Section 7.6.

Figure 7-4 Lock Status Block

The status code is placed in the lock status block either when the lock is granted or when errors occur in granting the lock.

The uses of the lock value block are described in Section 7.7.1.

7.5.5 Blocking ASTs

In some applications that use the lock management services, a process must know whether it is preventing another process from locking a resource. The lock management services inform processes of this through the use of blocking ASTs. When the lock prevents another lock from being granted, the blocking routine is delivered as an AST to the process. Blocking ASTs are not delivered when the state of the lock is either Conversion or Waiting.

To enable blocking ASTs, the blkast argument of the SYS$ENQ system service must contain the address of a blocking AST service routine. The astprm argument passes a parameter to the blocking AST. For more information about ASTs and AST service routines, see Chapter 8. Some uses of blocking ASTs are also described in that chapter.

7.5.6 Lock Conversions

Lock conversions perform three main functions:

• Maintaining a low-level lock and converting it to a higher lock mode when necessary
• Maintaining values stored in a resource lock value block (described in the following paragraphs)
• Improving performance in some applications

A procedure normally needs an exclusive (or protected write) mode lock while writing data. The procedure should not keep the resource exclusively locked all the time, however, because writing might not always be necessary. Maintaining an exclusive or protected write mode lock prevents other processes from accessing the resource. Lock conversions allow a process to request a low-level lock at first and convert the lock to a high-level lock mode (protected write mode, for example) only when it needs to write data.

Some applications of locks require the use of the lock value block. If a version number or other data is maintained in the lock value block, you need to maintain at least one lock on the resource so that the value block is not lost. In this case, processes convert their locks to null locks, rather than dequeuing them when they have finished accessing the resource.

To improve performance in some applications, all resources that might be locked are locked with null locks during initialization. You can convert the null locks to higher-level locks as needed. Usually a conversion request is faster than a new lock request because the necessary data structures have already been built. However, maintaining any lock for the life of a procedure uses system dynamic memory. Therefore, the approach of creating all necessary locks as null locks and converting them as needed improves performance at the expense of increased storage requirements.

Queuing Lock Conversions

To perform a lock conversion, a procedure calls the SYS$ENQ system service with the flag bit LCK$M_CONVERT. Lock conversions do not use the resnam, parid, acmode, or prot argument. The lock being converted is identified by the lock identification contained in the lock status block. The following program shows a simple lock conversion. Note that the lock must be granted before it can be converted.

#include <stdio.h>
#include <descrip.h>
#include <lckdef.h>

/* Declare a lock status block */

struct lock_blk {
                unsigned short lkstat, reserved;
                unsigned int lock_id;
}lksb;

   .
   .
   .
        unsigned int status, lkmode, flags;
        $DESCRIPTOR(resource,"STRUCTURE_1");
   .
   .
   .
        lkmode = LCK$K_NLMODE;

/* Queue a request for protected read mode lock */
        status = SYS$ENQW(0,    /* efn - event flag */
                  lkmode,       /* lkmode - lock mode */
                  &lksb,        /* lksb - lock status block */
                  0,            /* flags */
                   &resource,   /* resnam - name of resource */
                  0, 0, 0, 0, 0, 0);
   .
   .
   .
        lkmode = LCK$K_PWMODE;
        flags = LCK$M_CONVERT;

/* Queue a request for protected write mode lock */
        status = SYS$ENQW(0,     /* efn - event flag */
                  lkmode,        /* lkmode - lock mode */
                  &lksb,         /* lksb - lock status block */
                  flags,         /* flags */
                  0, 0, 0, 0, 0, 0, 0);
   .
   .
   .
}

It is possible to force certain conversions to be queued that would otherwise be granted. A conversion request with the LCK$M_QUECVT flag set is forced to wait behind any already queued conversions.

The conversion request is granted immediately if no conversions are already queued.

The QUECVT behavior is valid only for a subset of all possible conversions. Table 7-4 defines the legal set of conversion requests for LCK$M_QUECVT. Illegal conversion requests fail with SS$_BADPARAM returned.

NL = Null
CR = Concurrent read
CW = Concurrent write
PR = Protected read
PW = Protected write
EX = Exclusive

When a lock request is queued, you can declare a parent lock for the new lock. A lock that has a parent is called a sublock. To specify a parent lock, the lock identification of the parent lock is passed in the parid argument to the SYS$ENQ system service. A parent lock must be granted before the sublocks belonging to the parent can be granted.

The benefits of specifying parent locks are as follows:

• Low-level locks (concurrent read or concurrent write) such as files can be held at a coarse granularity; whereas high-level (protected write or exclusive mode) sublocks such as records or data items are held on resources of a finer granularity.
• Resource names are unique with each parent; parent locks are part of the resource name.

The following paragraphs describe the use of parent locks.

Assume that a number of processes need to access a database. The database can be locked at two levels: the file and individual records. For updating all the records in a file, locking the whole file and updating the records without additional locking is faster and more efficient. But for updating selected records, locking each record as it is needed is preferable.

To use parent locks in this way, all processes request locks on the file. Processes that need to update all records must request protected write or exclusive mode locks on the file. Processes that need to update individual records request concurrent write mode locks on the file and then use sublocks to lock the individual records in protected write or exclusive mode.

In this way, the processes that need to access all records can do so by locking the file, while processes that share the file can lock individual records. A number of processes can share the file-level lock at concurrent write mode while their sublocks update selected records.

On VAX systems, the number of levels of sublocks is limited by the size of the interrupt stack. If the limit is exceeded, the error status SS$_EXDEPTH is returned. The size of the interrupt stack is controlled by the SYSGEN parameter INTSTKPAGES. The default value for INTSTKPAGES allows 32 levels of sublocks. For more information about SYSGEN and INTSTKPAGES, see the OpenVMS System Manager's Manual.

On Alpha systems, the number of levels of sublocks is fixed at 127. If that limit is exceeded, the error status SS$_EXDEPTH is returned.

7.5.9 Lock Value Blocks

The lock value block is an optional, 16-byte extension of a lock status block. The first time a process associates a lock value block with a particular resource, the lock management services create a resource lock value block for that resource. The lock management services maintain the resource lock value block until there are no more locks on the resource.

To associate a lock value block with a resource, the process must set the flag bit LCK$M_VALBLK in calls to the SYS$ENQ system service. The lock status block lksb argument must contain the address of the lock status block for the resource.

When a process sets the flag bit LCK$M_VALBLK in a lock request (or conversion request) and the request (or conversion) is granted, the contents of the resource lock value block are written to the lock value block of the process.

When a process sets the flag bit LCK$M_VALBLK on a conversion from protected write or exclusive mode to an equal or lower mode, the contents of the process's lock value block are stored in the resource lock value block.

In this manner, processes can pass the value in the lock value block along with the ownership of a resource.

Table 7-5 shows how lock conversions affect the contents of the process's and the resource's lock value block.

NL---Null
CR---Concurrent read
CW---Concurrent write
PR---Protected read
PW---Protected write
EX---Exclusive

Key to Effects:

Return---The contents of the resource lock value block are returned to the lock value block of the process.
Neither---The lock value block of the process is not written; the resource lock value block is not returned.
Write---The contents of the process's lock value block are written to the resource lock value block.

Note that when protected write or exclusive mode locks are dequeued using the Dequeue Lock Request (SYS$DEQ) system service and the address of a lock value block is specified in the valblk argument, the contents of that lock value block are written to the resource lock value block.