|
|
|
Obtains or releases access to a logical resource.
&LOCK PNAME=resource name
[ TYPE={ EXCL | SHR | TEST | FREE } ]
[ ALTER={ YES | NO } ]
[ MNAME=resource name ]
[ WAIT={ NO | YES | nnnn } ]
[ TEXT={ text | var | userid procedure-name time } ]
&LOCK controls concurrent access to a particular logical resource by different NCL processes. &LOCK lets a process nominate a resource by name (for example, a file ID) for either exclusive or shared access to that resource. This status is altered during processing when ALTER =YES is specified. A procedure that needs to access the resource can use &LOCK to find out whether it is entitled to use it, or whether the current process or another process already has exclusive use.
&LOCK is used to synchronize the activities of different procedures that access, update, or reference common information.
On completion, &RETCODE is set to indicate the result of the operation.
Operands:
(mandatory) Specifies the primary name for the resource targeted by this &LOCK action. The name is any string of 1 to 16 characters.
TYPE=EXCL indicates a request for exclusive control of the resource, as identified by the PNAME (primary name) and optional MNAME (secondary name) operands.
TYPE=SHR indicates a request for shared access to the nominated resource.
TYPE=TEST indicates a request to find out whether the nominated resource is already the subject of an &LOCK operation by this or another process.
TYPE=FREE indicates a request to release the shared or exclusive access to the nominated resource by this process.
Specifies whether or not an NCL procedure can request that the lock type and/or lock text be changed during processing. ALTER=YES allows the type and text to be changed, and ALTER=NO, the default, specifies that no change is allowed.
For the rules that apply when changing the lock type and text, see Altering the Lock Type During Processing.
Specifies the minor name for the resource. This operand is optional. The name is any string of 1 to 256 characters.
WAIT=NO indicates that the request for shared or exclusive control is to lapse immediately if access to the nominated resource cannot be obtained.
When WAIT=YES is specified for TYPE=SHR or EXCL, it indicates that if the request for access to the resource cannot be granted immediately, the &LOCK function will wait indefinitely until the request is granted, or the request fails. For TYPE=TEST, if the resource is not currently held by any user, the request will wait indefinitely until the next request of any type is made by another process.
WAIT=nnnn indicates that if the request for exclusive or shared control of the resource cannot be granted immediately, then the &LOCK function will wait until the request is granted, for up to nnnn seconds maximum (the time value can range from 1 to 9999 seconds). For TYPE=TEST, if the resource is not currently held by any user, the request will wait for the specified period or until the next request of any type is made by another process.
Specifies a maximum of 24 characters of free form text to be associated with this access request. The value of the text is returned in the variable &1 for certain &LOCK operations. If no text is supplied on the &LOCK statement, the default is the current user ID, suffixed by the name of the base NCL procedure, suffixed by the time. The text assigned to the request is composed of text, or variables, or a mixture of both, but cannot contain blanks. If blanks are required in the text, assign the required value to a variable using the &STR function, then use the variable on the TEXT= operand.
Return Codes:
TYPE=EXCL and TYPE=SHR requests complete with &RETCODE set as follows:
Access to the resource is granted. For an EXCL request no other processes can gain access to the resource until it is explicitly FREEd, or the process terminates.
The request has been ignored because this process has control of the resource already. &1 is set to the text of the existing lock. &ZFDBK is set as follows:
Lock is already held shared
Lock is already held exclusively
A lock conflict has been detected
Access to the resource is denied. Another process has control of the resource. The variable &1 contains the text of the oldest request that obtained control of the resource. &ZFDBK is set as follows:
Lock is held shared (TYPE=EXCL requests only)
Lock is held exclusively
When WAIT=YES or WAIT=nnnn is specified:
The request is denied. Access to the resource is not possible. A PURGE command has been issued for the waiting lock request or the time limit has expired. The variable &1 contains the text of the oldest request that obtained control of the resource. &ZFDBK is set as follows:
Lock is held shared (TYPE=EXCL requests only)
Lock is held exclusively
The request is rejected. &SYSMSG is set to the text describing the error condition.
TYPE=TEST requests complete with &RETCODE set as follows:
No other procedure has shared or exclusive control of the resource, or is testing the resource.
The request will fail because this process already has control of the resource. &1 is set to the text of the existing lock. &ZFDBK is set as follows:
Lock is already held shared
Lock is already held exclusively
Lock conflict has been detected
Another process controls the resource. Variable &1 contains the text of the oldest request that obtained control of the resource. &ZFDBK is set as follows:
Lock is held shared
Lock is held exclusively
A TEST request has been made against the resource
TYPE=FREE requests complete with &RETCODE set as follows:
Shared or exclusive control of the resource has been released by this process. Variable &1 contains the text of the request just released. &ZFDBK is set as follows:
Lock is held shared
Lock is held exclusively
The request is ignored. This procedure has no &LOCK control, either shared or exclusive, of the nominated resource.
When ALTER=YES is specified, requests complete with &RETCODE set as follows:
Shared or exclusive control of the resource has been granted. Variable &1 contains the text of the request just released. &ZFDBK is set as follows:
Lock is held shared
Lock is held exclusively
The request is denied. &ZFDBK is set as follows:
Lock is held shared
Lock is held exclusively &1 is set to the text of the lock that prevented the request from succeeding. The text of the requesting NCL procedure's original lock request remains unchanged, and there is no alteration to the original lock ownership (that is, the NCL procedure still owns the lock in shared status as if the &LOCK ALTER=YES was not issued).
Examples: &LOCK
&TODAY = MONDAY
&DTIME = NIGHT
&LOCK TYPE=EXCL PNAME=&TODAY MNAME=&DTIME
.
. -* process
.
&LOCK TYPE=FREE PNAME=&TODAY MNAME=&DTIME
&LOCK TYPE=SHR PNAME=CUSTFILEMNAME=CUSTREC
&LOCKTEXT = &STR &0 write custfile
&LOCK TYPE=EXCL ALTER=YES PNAME=CUSTFILE MNAME=CUSTREC WAIT=20 +
TEXT=LOCKTEXT
Notes:
The resource referred to in connection with the &LOCK statement is not a real entity such as a file or a variable. A resource in this context is a name to which one or more NCL procedures refer. The name is made up of a primary name (PNAME), and optionally a minor name (MNAME), for example, CONFIG.ABC and CONFIG.XYZ (where CONFIG is the primary name and ABC and XYZ are minor names).
If two procedures agree to use the resource CONFIG.ABC to control their access to a UDB, each would request exclusive use of the resource CONFIG.ABC. While one was granted access, the other would fail to obtain access and could not use the UDB. It must be noted that &LOCK resources provide protection only if all procedures that need to synchronize access to a resource are written using &LOCK against a mutually-agreed resource.
Termination of the process releases all locks that are still held.
The &LOCK TYPE=TEST WAIT=YES construction is used to create a semaphore for signalling between procedures.
Note: For more information, see the Network Control Language Programming Guide. See also the PURGE and SHOW NCLLOCKS commands in the Online Help.
| Copyright © 2009 CA. All rights reserved. |
|