Skip to main content
Version: v20

$lock

Locks and unlocks an entity using the pessimistic mechanism.

Syntax

To lock an entity for other sessions and 4D processes:

/?$lock=true

To unlock the entity for other sessions and 4D processes:

/?$lock=false

The lockKindText property is "Locked by session".

Description

The locks triggered by the REST API are put at the session level.

A locked entity is seen as locked (i.e. lock / unlock / update / delete actions are not possible) by:

  • other REST sessions
  • 4D processes (client/server, remote datastore, standalone) running on the REST server.

An entity locked by the REST API can only be unlocked:

  • by its locker, i.e. a /?$lock=false in the REST session that sets /?$lock=true
  • or if the session's inactivity timeout is reached (the session is closed).

Response

A ?$lock request returns a JSON object with "result"=true if the lock operation was successful and "result"=false if it failed.

The returned "__STATUS" object has the following properties:

PropertyTypeDescription
Available only in case of success:
successbooleantrue if the lock action is successful (or if the entity is already locked in the current session), false otherwise (not returned in this case).
Available only in case of error:
statusnumberError code, see below
statusTexttextDescription of the error, see below
lockKindnumberLock code
lockKindTexttext"Locked by session" if locked by a REST session, "Locked by record" if locked by a 4D process
lockInfoobjectInformation about the lock origin. Returned properties depend on the lock origin (4D process or REST session).
Available only for a 4D process lock:
task_idnumberProcess ID
user_nametextSession user name on the machine
user4d_aliastextName or alias of the 4D user
user4d_idnumberUser id in the 4D database directory
host_nametextMachine name
task_nametextProcess name
client_versiontextVersion of the client
Available only for a REST session lock:
hosttextURL that locked the entity (e.g. "127.0.0.1:8043")
IPAddrtextIP address of the locker (e.g. "127.0.0.1")
recordNumbernumberRecord number of the locked record
userAgenttextuserAgent of the locker (e.g. Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/96.0.4664.110 Safari/537.36")

The following values can be returned in the status and statusText properties of the __STATUS object in case of error:

statusstatusTextComment
2"Stamp has changed"The internal stamp value of the entity does not match the one of the entity stored in the data (optimistic lock).
3"Already locked"The entity is locked by a pessimistic lock.
4"Other error"A serious error is a low-level database error (e.g. duplicated key), a hardware error, etc.
5"Entity does not exist anymore"The entity no longer exists in the data.

Example

We lock an entity in a first browser:

GET /rest/Customers(1)/?$lock=true

Response:

{
"result": true,
"__STATUS": {
"success": true
}
}

In a second browser (other session), we send the same request.

Response:

{
"result":false,
"__STATUS":{
"status":3,
"statusText":"Already Locked",
"lockKind":7,
"lockKindText":"Locked By Session",
"lockInfo":{
"host":"127.0.0.1:8043",
"IPAddr":"127.0.0.1",
"recordNumber": 7,
"userAgent": ""Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_3) AppleWebKit/537.36..."
}
}
}