Superlock

2.13 Suppressing Error Messages

If Superlock exits with an error code, DCL will report the actual error. Normally you would want this, but there are occasions where you might prefer to check for the error in the surrounding DCL code and take appropriate action.

In the earlier example of Superlock to limit the number of interactive logins within a cluster, the 2nd and subsequent logins that used the Lock command exited with the error

%SYSTEM-W-NOTQUEUED, request not queued

and the login script then logged out. There may be occasions in which you don't want the error displayed, so that your DCL script can test for and handle the error. If you use the "/NOLOG" qualifier, Superlock will prevent DCL from displaying the following errors

%SYSTEM-W-NOTQUEUED, request not queued %SYSTEM-F-TIMEOUT, device timeout

These errors correspond to the use of /NOWAIT and /TIMEOUT respectively. Superlock will logical OR the status code with %X10000000, which will cause DCL to suppress the message, but you can still check the value of $status. Note that other unexpected errors will still be reported normally.

2.14 Further Information

Superlock effectively gives DCL access to the $ENQ and $DEQ system services. The use of LOCK commands is very similar to a programmers use of these services. For further examples on the various uses of the Lock Manager, see the System Services Reference Manual.

Chapter 3
Lock Value Block

Superlock also supports access to the Lock Value Block associated with the resource. When a new lock is requested, OpenVMS assigns a 16 or 64 byte field in the Lock Manager database. This value can be read or written by applications that call the lock manager.

3.1 Creating a Lock Value Block

Superlock provides a /VALUE_BLOCK qualifier to create and manipulate the Lock Value Block. If you specifiy this qualifier, you must provide an argument which is interpreted as a DCL symbol, e.g. if you specify /VALUE=LOCK_VALUE, Superlock will use the DCL symbol LOCK_VALUE to transfer data between the Lock Manager database and the calling process.

3.1.1 Reading and Writing the Symbol

If you use the /VALUE_BLOCK qualifer, Superlock will look for an existing DCL symbol, and set its local copy of the Value Block to this value. If the symbol does not exist, Superlock will initialize its local copy to nulls. When the Superlock program exits, it will (re)define the symbol to the current value of its local copy of the Value Block (which may have changed depending on which lock operation was used).

3.1.2 Copying between the Lock Copy and the Lock Manager Database

Depending on the nature of the lock request, Superlock will transfer between its local copy of the Value Block and that of the Lock Manager Database. If a process requests a new lock, or modifies an existing lock to a more restrictive mode (e.g. from null to exclusive), Superlock will set its local copy to the value maintained in the Lock Manager database. When Superlock exits, this new value will be returned in the DCL symbol. If a process dequeues a lock, or modifies an existing lock to a less restrictive mode, then Superlock will update the Value Block in the Lock Manager database to the value in its local copy. Thus data can be exchanged between processes using the Lock Manager using the Lock Value Block.

3.2 Extended Lock Value Block

The original size of the Lock Value Block was set to 16 bytes, but in OpenVMS 8.2, an optional extended size of 64 bytes was provided. By default, the size of the Lock Value Block is 16 bytes. To use the extended size, use the /EXTEND qualifier (the qualifier is ignored if /VALUE_BLOCK is not specified). If using an extended Lock Value Block, the qualifier must be used by all cooperating processes. Note that versions of OpenVMS prior to 8.2 (which includes all versions of OpenVMS VAX) cannot use extended Lock Value Blocks.

3.2.1 Considerations for Mixed Version Clusters

If you are using Superlock within a cluster containing one or more members running OpenVMS prior to 8.2, you need to exercise care with the use of extended Lock Value Blocks, as the older nodes will not be able to process the block beyond 16 bytes. The warning code SS$_XVALNOTVALID may be returned if a newer node reads the block using /EXTEND.

3.3 Formatting the Lock Value Block

By default, Superlock treats the Lock Value block as a fixed length 16 (or 64 if extended) block of data. It will pad any value provided in the DCL symbol to 16 (or 64) bytes with null characters, and will return a DCL symbol containing exactly 16 (or 64) bytes. You can modify this behavior using /PAD or /TRIM qualifiers (these qualifiers are ignored if /VALUE is not present).

3.3.1 Padding Characters

When Superlock gets a Lock Value Block from a DCL symbol that is less than 16 (or 64) bytes, it pads it to the fixed length using null characters. If you specify /PAD=SPACE, it will instead pad it with space characters.

3.3.2 Trimming Characters

When Superlock sets a the DCL symbol specified in /VALUE on exit, it will set the symbol to the full 16 (or 64) characters. If you specify /TRIM, Superlock will remove any trailing space or null characters before setting the symbol value.

3.4 Further Information

A more detailed description of the use of the Lock Value Block in calls to the Lock Manager is provided in the Programming Concepts Manual chapter on Synchronizing Access to Resources with the Lock Manager. This is available on the vmssoftware.com website, under the "Resources" followed by "Documentation" links.

Chapter 4
Locks and Sublocks

4.1 Lock Hierarchy

By default, resource names are considered "root" resources, in that they do not depend on any other resource. Resources can actually be arranged in a hierarchy, where a resource can be a subresource of another resource.

4.1.1 Specifying a Subresource

When you request s new lock on a resource, you specify a resource name, and a DCL symbol to receive the new Lock ID. If you want the resource to be a subresource of another resource, use the /PARENT qualifier. The argument to /PARENT is another DCL symbol which was used as the /ID of a previous lock request. A lock on a subresource is considered a sublock. Before being granted the sublock, the caller must already have a lock granted to the parent. The following example creates a lock and a sublock.

$ Lock /id=parent_id /mode=crmode PARENT_RESOURCE $ Lock /id=lock_id /parent=parent_id /mode=prmode CHILD_RESOURCE

Sublocks can be used to coordinate access to a set of hierarchical resources such as a database, its files and records.

4.2 Dequeuing Sublocks

Sublocks can be released individually in exactly the same way as root locks using a /RELEASE qualifier, along with Lock ID symbol specified by /ID. You can also release all sublocks of a parent lock by using the /SUBLOCK qualifier. Note that you will need to release all sublocks (either individually or using the /SUBLOCK qualifier) before releasing the parent lock. The following example, creates a root lock with two sublocks, then releases all the sublocks, along with the root lock.

$ Lock /id=parent_id /mode=crmode PARENT_RESOURCE $ Lock /id=lock_id1 /parent=parent_id /mode=prmode CHILD_RESOURCE1 $ Lock /id=lock_id2 /parent=parent_id /mode=prmode CHILD_RESOURCE2 $ Lock /id=parent_id /release /sublock $ Lock /id=parent_id /release

Note

The combination of /SUBLOCK and /RELEASE causes all sublocks of the lock specified by /ID to be released. It does not release the parent lock itself. You need to subsequently release the parent lock using /RELEASE and /ID without /PARENT.

4.3 Further Information

A more detailed description of the use of Locks and Sublocks in calls to the Lock Manager is provided in the Programming Concepts Manual chapter on Synchronizing Access to Resources with the Lock Manager. This is available on the vmssoftware.com website, under the "Resources" followed by "Documentation" links.

Chapter 5
Reporting on Lock Blocking

Superlock V3 introduced a mechanism whereby you can see what processes are preventing you from being granted a particular lock. This is activated by use of the /REPORT_BLOCKERS qualifiers, and information is returned in various DCL symbols.

5.1 Blocking Processes

It should be noted that when you are blocked from acquiring a lock, this can be caused by more than one processes. For example:

Process A acquires a lock on resource MYLOCK using Protected Read mode. This mode requests read access, and allows other processes also to have read mode.
Process B then acquires a lock on the same resource MYLOCK using Protected Read mode. As this mode is consistent with the Protected Mode already granted to Process A, the Lock Manager grants this access too.
Any further processes acquiring Protected or Concurrent Read mode are also granted.
Your process now requests Protected Write mode. This mode requests Write access, and allows other processes to have Read access. Although your request would not prevent other processes having Read access, your requested mode is not consistent with the Protected Read already granted (these processes specified only Read access to other requestors). Thus your lock request is blocked. It cannot be granted until all the processes holding Protected Read either release their locks, or convert them to a compatible mode (e.g. Concurrent Read, or Null).

5.2 DCL Symbols

If your lock request is blocked, and you requested a report, then Superlock will define the following DCL symbols:

SUPERLOCK_BLOCK_COUNT. This symbol is set to a string indicating the number of blocking processes. Note that this is a string (e.g. "3") and not an integer. If you wish to process it as a loop counter in DCL, you will need to use the F$INTEGER lexical function.
SUPERLOCK_BLOCK_1 is the first process PID that is blocking the lock request. This is a string specifying the Process ID in Hex of the process that is holding an incompatible lock.
SUPERLOCK_BLOCK_number for each other process blocking the lock request, the symbol SUPERLOCK_BLOCK_2, SUPERLOCK_BLOCK_3 etc is specified.

Note

The use of /REPORT_BLOCKERS is only useful in combination with the /NOWAIT qualifier. If /WAIT (the default) is used, then Superlock will only exit to DCL when the lock is granted (and thus no longer blocked).

5.3 Restrictions on /REPORT_BLOCKERS

There are two main restrictions on the use of /REPORT_BLOCKERS.

5.3.1 Lock must be an Existing Lock

You cannot use /REPORT_BLOCKERS when acquiring a new lock. You must first acquire a lock in Null mode and then convert it to achieve this. For example

$ Lock FOOBLE /write /id=lock_id /nowait /report %SPRLCK-E-REPORTNEW, Can't report blockers on a new lock request $ Lock FOOBLE /id=lock_id /mode=nlmode $ Lock /id=lock_id /mode=write /report /nowait %SYSTEM-W-NOTQUEUED, request not queued $ $ Show symbol SUPERLOCK* SUPERLOCK_BLOCK_1 = "2024EFC1" SUPERLOCK_BLOCK_COUNT = "1" $

5.3.2 Use of /NOWAIT or /TIMEOUT

To receive a report, you must either specify the /NOWAIT qualifier (which causes the lock request to fail immediately), or specify the /TIMEOUT qualifier, which causes the lock request to fail if the timer expires. Without the use of one of these qualifiers, your lock request will simply wait until the other locks are released, in which case there will be no blockers to report (and your lock will be granted).

5.3.3 Maximum number of Blockers

Superlock will only report up to 256 blocking PIDs. This restriction may be extended in a future release.

Previous Contents Contents