Command: LOCK

Purpose: Sets (or attempts to set) a lock on the specified array reference. Once set, no other client can set a lock on the same array reference until it is unlocked by the original client that set it using the UNLOCK command.

Note: Locks do not prevent any other client using a SET operation on the specified array reference.

Note that the specified array reference does not, in fact, have to exist.

All locks that are established by a client are automatically released when the M/Wire session is terminated by QUIT, EXIT or HALT, or if the M/Wire client closes the socket.

Arguments:

Argument No Description
1 The array node to be locked. This takes the format:
   arrayRef[subscr1,subscr2,..etc]
You may specify no subscripts at all, in which case the top-level node is locked,eg:
   arrayRef
Locking the first level of subscripting would look like:
   arrayRef[1]
Locking the second level of subscripting would look like:
   arrayRef[1,"aaa"]

Note that subscripts can be numeric or text. Text subscripts must be wrapped in double quote (") characters. Quoting of numeric subscripts is optional.
2 Timeout in seconds. If not specified, the timeout is set to 5. If a LOCK cannot be established within the timeout period, a value of 0 is returned and the LOCK command is abandoned. If the LOCK is successful within the timeout period, a value of 1 is returned. The M/Wire server will not return a response until either the LOCK is successfully established or the timeout period is exhausted, whichever occurs earlier.

Response

Single-line integer response

Lock successfully established:

Server: :1

Lock unsuccessful:

Server: :0

Examples

Successful:

Client: LOCK test1["a","b"]
Server: :1

Unsuccessful attempt after 30 seconds:

Client: LOCK test1["a","b"] 30
Server: :0

For those familiar with the native language of GT.M and Caché systems, the second example is the equivalent of:

ok=1
lock +^test1("a","b"):30 else set ok=0
write ok