entity.save( )

4D v19

entity.save( )

Description

La méthode entity.save( ) sauvegarde dans la table de la dataclass les modifications effectuées sur l'entité. Vous devez appeler cette méthode après toute création ou modification d'entité si vous souhaitez stocker les changements.

La sauvegarde est effectuée si et seulement si au moins un attribut de l'entité a été "touché" (voir les méthodes entity.touched( ) et entity.touchedAttributes( )). Sinon, la méthode ne fait rien (le trigger n'est pas appelé).

Dans une application multi-utilisateur ou multi-process, la méthode entity.save( ) est exécutée avec le mécanisme du "verrouillage optimiste", dans lequel un compteur interne (stamp) est automatiquement incrémenté à chaque sauvegarde de l'enregistrement. Pour plus d'informations, veuillez vous reporter à la page Verrouillage d'entités.

Par défaut, si le paramètre mode est omis, la méthode retournera systématiquement une erreur (voir ci-dessous) lorsque la même entité a été modifiée entre-temps par un autre process ou utilisateur, quel(s) que soi(en)t l(es) attribut(s) modifié(s).
Vous pouvez passer l'option dk auto merge dans le paramètre mode afin d'activer le mode "automatic merge". Dans ce mode, une modification effectuée entre-temps par un autre process/utilisateur sur la même entité mais sur un attribut différent ne génère pas d'erreur. Les données effectivement stockées dans l'enregistrement résultent alors de la combinaison (le "merge") des modifications non-concurrentes (si des modifications ont été effectuées sur le même attribut, la sauvegarde échoue et une erreur est retournée, même en mode "automatic merge").

Note : Le mode "automatic merge" n'est pas utilisable avec les attributs de type image, objet ou texte stockés en-dehors de l'enregistrement.

Résultat

L'objet retourné par entity.save( ) contient les propriétés suivantes :

Propriété		Type	Description
success		booléen	vrai si la sauvegarde a été effectuée avec succès, sinon faux.
			Disponible uniquement si l'option *dk auto merge a été utilisée :*
autoMerged		booléen	vrai si un "auto merge" a été effectué, sinon faux.
			Disponible uniquement en cas d'erreur (status=faux) :
status(*)		numérique	Code d'errreur, voir ci-dessous
statusText(*)		texte	Description de l'errreur, voir ci-dessous
			Disponible uniquement en cas d'erreur en verrouillage pessimiste :
lockKindText		texte	"Locked by record"/"'Verrouillé par enregistrement"
lockInfo		objet	Information sur l'origine du verrouillage
	task_id	numérique	ID du process
	user_name	texte	Nom de l'utilisateur de la session sur la machine
	user4d_alias	texte	Alias utilisateur défini avec FIXER ALIAS UTILISATEUR, sinon le nom d'utilisateur dans le répertoire de la base 4D
	user4d_id	numérique	Numéro de l'utilisateur 4D (Disponible uniquement dans les bases 4D binaires)
	host_name	texte	Nom de la machine
	task_name	texte	Nom du process
	client_version	texte
			Disponible uniquement en cas d'erreur sérieuse (clé primaire dupliquée, disque plein...) :
errors		collection d'objets
	message	texte	Message d'erreur
	componentSignature	texte	Signature de composant interne (ex. "dmbg" pour le composant base de données)
	errCode	numérique	Code d'erreur

(*) Les valeurs suivantes peuvent être retournées dans les propriétés status et statusText de l'objet Résultat en cas d'erreur :

Constante	Valeur	Comment
dk status automerge failed	6	(Uniquement si l'option dk auto merge est utilisée) Echec du mécanisme de merge automatique lors de la sauvegarde de l'entité. statusText associé : "Auto merge failed"
dk status entity does not exist anymore	5	L'entité n'existe plus dans les données. Cette erreur peut se produire dans les cas suivants : l'entité a été supprimée (le stamp est modifié et l'espace mémoire est libéré) l'entité a été supprimée et remplacée par une autre avec une clé primaire différente (le stamp est modifié et une nouvelle entité occupe l'espace mémoire). Avec entity.drop( ), cette erreur peut être retournée lorsque l'option dk force drop if stamp changed est utilisée. Avec entity.lock( ), cette erreur peut être retournée lorsque l'option dk reload if stamp changed est utilisée. statusText associé : "Entity does not exist anymore"
dk status locked	3	L'entité est verrouillée par un verrou pessimiste. statusText associé : "Already locked"
dk status serious error	4	Une erreur critique peut être une erreur de bas niveau de la base de données (ex. clé dupliquée), une erreur matérielle, etc. statusText associé : "Other error"
dk status stamp has changed	2	La valeur du marqueur interne (stamp) de l'entité ne correspond pas à celle de l'entité stockée dans les données (verrouillage optimiste). avec entity.save( ) : erreur uniquement si l'option dk auto merge n'est pas utilisée avec entity.drop( ) : erreur uniquement si l'option dk force drop if stamp changed n'est pas utilisée avec entity.lock( ) : erreur uniquement si l'option dk reload if stamp changed n'est pas utilisée statusText associé : "Stamp has changed"

Exemple 1

Création d'une nouvelle entité :

 C_OBJET($status;$employee)

 $employee:=ds.Employee.new()

 $employee.firstName:="Mary"

 $employee.lastName:="Smith"

 $status:=$employee.save()

 Si($status.success)

    ALERTE("Employé(e) créé(e)")

 Fin de si

Exemple 2

Mise à jour d'une entité sans option dk auto merge :

 C_OBJET($status;$employees;$employee)

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

 $employee:=$employees.first()

 $employee.lastName:="Mac Arthur"

 $status:=$employee.save()

 Au cas ou

    :($status.success)

       ALERTE("Employé(e) mis(e) à jour")

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

       ALERTE($status.statusText)

 Fin de cas

Exemple 3

Mise à jour d'une entité avec option dk auto merge :

 C_OBJET($status;$employees;$employee)

 

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

 $employee:=$employees.first()

 $employee.lastName:="Mac Arthur"

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

 Au cas ou

    :($status.success)

       ALERTE("Employé(e) mis(e) à jour")

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

       ALERTE($status.statusText)

 Fin de cas

Voir aussi

entity.drop( )
entity.getStamp( )
entity.isNew( )