entity.lock( )

Home

4D v19.8

entity.lock( )


entity.lock ( {mode} ) -> Result

Parameter	Type	Description
mode	Longint	dk reload if stamp changed: Reload before locking if stamp changed
Result	Object	Result of lock operation

Description

The entity.lock( ) method puts a pessimistic lock(*) on the record referenced by the entity. The lock is set for a record and all the references of the entity in the current process.

(*)For more information, please refer to the Entity locking page.

Other processes will see this record as locked (the result.success property will contain false if they try to lock the same entity using this method). Only methods executed in the "locking" session are allowed to edit and save the attributes of the entity. The entity can be loaded as read-only by other sessions, but they will not be able to enter and save values.

A locked record is unlocked:

when the unlock() method is called on a matching entity in the same process
automatically, when it is no longer referenced by any entities in memory. For example, if the lock is put only on one local reference of an entity, the entity is unlocked when the method ends. As long as there are references to the entity in memory, the record remains locked.
automatically, when the matching entity was locked inside a transaction and the transaction is validated or cancelled.

By default, if the mode parameter is omitted, the method will return an error (see below) if the same entity was modified (i.e. the stamp has changed) by another process or user in the meantime.
Otherwise, you can pass the dk reload if stamp changed option in the mode parameter: in this case, no error is returned and the entity is reloaded when the stamp has changed (if the entity still exists and the primary key is still the same).

Result

The object returned by entity.lock( ) contains the following properties:

Property		Type	Description
success		boolean	true if the lock action is successful (or if the entity is already locked in the current process), false otherwise.
			*Available only if dk reload if stamp changed option is used:*
wasReloaded		boolean	true if the entity was reloaded with sucess, false otherwise.
			*Available only in case of error:*
status(*)		number	Error code, see below
statusText(*)		text	Description of the error, see below
			*Available only in case of pessimistic lock error:*
lockKindText		text	"Locked by record"
lockInfo		object	Information about the lock origin
	task_id	number	Process ID
	user_name	text	Session user name on the machine
	user4d_alias	text	Name or alias of the 4D user
	user4d_id	number	User id in the 4D database directory
	host_name	text	Machine name
	task_name	text	Process name
	client_version	text
			Available only in case of serious error (primary key already exists, disk full...):
errors		collection of objects
	message	text	Error message
	component signature	text	internal component signature (e.g. "dmbg" stands for the database component)
	errCode	number	Error code

(*) The following values can be returned in the status and statusText properties of the Result object in case of error:

Constant	Value	Comment
dk status entity does not exist anymore	5	The entity no longer exists in the data. This error can occur in the following cases: the entity has been dropped (the stamp has changed and the memory space is now free) the entity has been dropped and replaced by another one with another primary key (the stamp has changed and a new entity now uses the memory space). When using entity.drop( ), this error can be returned when dk force drop if stamp changed option is used. When using entity.lock( ), this error can be returned when dk reload if stamp changed option is used Associated statusText: "Entity does not exist anymore"
dk status locked	3	The entity is locked by a pessimistic lock. Associated statusText: "Already locked"
dk status serious error	4	A serious error is a low-level database error (e.g. duplicated key), a hardware error, etc. Associated statusText: "Other error"
dk status stamp has changed	2	The internal stamp value of the entity does not match the one of the entity stored in the data (optimistic lock). with entity.save( ): error only if the dk auto merge option is not used with entity.drop( ): error only if the dk force drop if stamp changed option is not used with entity.lock( ): error only if the dk reload if stamp changed option is not used Associated statusText: "Stamp has changed"

Example 1

Example with error:

 C_OBJECT($employee;$status)

 $employee:=ds.Employee.get(716)

 $status:=$employee.lock()

 Case of

    :($status.success)

       ALERT("You have locked "+$employee.firstName+" "+$employee.lastName)

    :($status.status=dk status stamp has changed)

       ALERT($status.statusText)

 End case

Example 2

Example with dk reload if stamp changed option:

 C_OBJECT($employee;$status)

 

 $employee:=ds.Employee.get(717)

 $status:=$employee.lock(dk reload if stamp changed)

 Case of

    :($status.success)

       ALERT("You have locked "+$employee.firstName+" "+$employee.lastName)

    :($status.status=dk status entity does not exist anymore)

       ALERT($status.statusText)

 End case