entity.save( )

Home

4D v18

entity.save( )

Description

The entity.save( ) method saves the changes made to the entity in the table related to its dataClass. You must call this method after creating or modifying an entity if you want to save the changes made to it.

The save operation is executed only if at least one entity attribute has been "touched" (see the entity.touched( ) and entity.touchedAttributes( ) methods). Otherwise, the method does nothing (the trigger is not called).

In a multi-user or multi-process application, the entity.save( ) 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) whenever the same entity has been modified by another process or user in the meantime, no matter the modified attribute(s).
Otherwise, you can pass the dk auto merge option in the mode parameter: when the automatic merge mode is enabled, a modification done concurrently by another process/user on the same entity but on a different attribute will not result in an error. The resulting data saved in the entity will be the combination (the "merge") of all non-concurrent modifications (if modifications were applied to the same attribute, the save fails and an error is returned, even with the auto merge mode).

Note: The automatic merge mode is not available for attributes of picture, object, and text type when stored outside of the record. Concurrent changes in these attributes will result in a dk status stamp has changed error.

Result

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

Property		Type	Description
success		boolean	True if the save action is successful, False otherwise.
			*Available only if dk auto merge option is used:*
autoMerged		boolean	True if an auto merge was done, 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_id	text	User name 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 (serious error - can be trying to duplicate a primary key, disk full...):
errors		collection of objects
	message	text	Error message
	componentSignature	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 automerge failed	6	(Only if the dk auto merge option is used) The automatic merge option failed when saving the entity. Associated statusText: "Auto merge failed"
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

Creating a new entity:

 C_OBJECT($status;$employee)

 $employee:=ds.Employee.new()

 $employee.firstName:="Mary"

 $employee.lastName:="Smith"

 $status:=$employee.save()

 If($status.success)

    ALERT("Employee created")

 End if

Example 2

Updating an entity without dk auto merge option:

 C_OBJECT($status;$employees;$employee)

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

 $employee:=$employees.first()

 $employee.lastName:="Mac Arthur"

 $status:=$employee.save()

 Case of

    :($status.success)

       ALERT("Employee updated")

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

       ALERT($status.statusText)

 End case

Example 3

Updating an entity with dk auto merge option:

 C_OBJECT($status;$employees;$employee)

 

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

 $employee:=$employees.first()

 $employee.lastName:="Mac Arthur"

 $status:=$employee.save(dk auto merge)

 Case of

    :($status.success)

       ALERT("Employee updated")

    :($status.status=dk status automerge failed)

       ALERT($status.statusText)

 End case