1 LOCK

		© Marc Van Dyck, 20-MAR-2000

LCK is a package that offers the DCL user the possibility to 
use the VMS distributed lock manager. The DCL command LOCK
created by this package allows to enqueue and dequeue locks
on arbitrary-chosen resources. It can thus be used to synchronize
independent processes running DCL command procedures in order to,
for example, provide exclusive access to a file, or any other
shared resource that may not be accessed by more than one process
simultaneously. 

LCK also features a callable interface, which offers a simplified
interface to the $ENQ/$DEQ system services for the programmer who
does not care to much about playing with such constructs as item
lists or lock status blocks. 

Of course, the whole functionality of the distributed lock manager
is not offered by this package : this version provides exclusive
locks only, no lock conversions, lock value blocks, sub-locks, or
resource domains. Some of those items might be considered as possible
enhancements for a future version of the package.

This package also allows to create system mode locks. To prevent
any irrelevant usage of this feature, the package requires the
presence of the SYSLCK privilege before enqueuing a system lock.
In any case, extreme caution must be applied when using this
feature : specially, using system locks on resource names that
contain dollar signs ($) should be avoided, because of the risk
of conflicts with a VMS resource.

The LOCK command must the used with either the qualifier /REQUEST,
or with the qualifier /RELEASE. Both qualifiers at once, or no
qualifier at all, are syntaxes that are not allowed.


2 /REQUEST

	LOCK /REQUEST resource-name

This command enqueues a lock on the resource whose name is specified
by the parameter P1.

Unless the qualifier /NOWAIT is specified, the command will wait until
the lock can be enqueued, i.e. until the resource specified is free of
use.

3 Parameters

resource-name

The name of the resource that must be locked. Up to 31 alphanumeric
characters, A-Z, a-z, 0-9, dollar sign ($), and underscore (_).
Resource names containing lowercase characters must be passed between
quotation marks.

This parameter is required.

3 Qualifiers

/SYSTEM

	/SYSTEM       
	/NOSYSTEM (default)

By default, locks only apply to processes of the cluster running 
in the same UIC group. IF the qualifier /SYSTEM is specified, 
the lock will apply to all processes of the cluster, without any
UIC consideration.

The privilege SYSLCK is required to use this feature.

/WAIT

	/WAIT (default)
	/NOWAIT

This qualifier is present by default.

If a lock is requested on a resource that has already be granted to
another process, the lock command will wait until the process that
owns the lock will release it.

However, if the qualifier /NOWAIT is specified, the lock command will
exit immediately, with a success status if the lock has been granted,
or with an error status if the lock was already owned by another
process. 

/LOG

	/LOG
	/NOLOG (default)

If specified, success messages will be displayed to the process output
device (SYS$OUTPUT), as well as error messages. If the qualifier /LOG
is not specified, only error messages are displayed.

2 /RELEASE

	LOCK /RELEASE resource-name

Releases an existing lock on a resource whose name is specified by the
parameter P1.

Locks created by the LCK package are requested in supervisor mode. This
means that they survive image rundown, but not process deletion.

3 Parameters

resource-name

The name of the resource on which the lock must be removed.

This parameter is required.

3 Qualifiers

/LOG

	/LOG
	/NOLOG (default)

If specified, success messages will be displayed to the process output
device (SYS$OUTPUT), as well as error messages. If the qualifier /LOG
is not specified, only error messages are displayed.
