entity.drop( )

Home

4D v19.8

entity.drop( )


entity.drop ( {mode} ) -> Result

Parameter	Type	Description
mode	Longint	dk force drop if stamp changed: Forces the drop even if the stamp has changed
Result	Object	Result of drop operation

Description

The entity.drop( ) method deletes the data contained in the entity from the datastore, from the table related to its dataClass. Note that the entity remains in memory.

In a multi-user or multi-process application, the entity.drop( ) method is executed under an "optimistic lock" mechanism, wherein an internal locking stamp is automatically incremented each time the record is saved. For more information, please refer to the Entity locking page.

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 force drop if stamp changed option in the mode parameter: in this case, the entity is dropped even if the stamp has changed (and the primary key is still the same).

Result

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

Property		Type	Description
success		boolean	true if the drop action is successful, 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	User alias defined with SET USER ALIAS, otherwise user name in the 4D database directory
	user4d_id	number	4D user number (Only available in 4D binary databases)
	host_name	text	Machine name
	task_name	text	Process name
	client_version	text
			Available only in case of serious error (serious error can be trying to duplicate a primary key, 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 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 without dk force drop if stamp changed option:

 C_OBJECT($employees;$employee;$status)

 $employees:=ds.Employee.query("lastName=:1";"Smith")

 $employee:=$employees.first()

 $status:=$employee.drop()

 Case of

    :($status.success)

       ALERT("You have dropped "+$employee.firstName+" "+$employee.lastName) //The dropped entity remains in memory

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

       ALERT($status.statusText)

 End case

Example 2

Example with dk force drop if stamp changed option:

 C_OBJECT($employees;$employee;$status)

 $employees:=ds.Employee.query("lastName=:1";"Smith")

 $employee:=$employees.first()

 $status:=$employee.drop(dk force drop if stamp changed)

 Case of

    :($status.success)

       ALERT("You have dropped "+$employee.firstName+" "+$employee.lastName) //The dropped entity remains in memory

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

       ALERT($status.statusText)

 End case