entity.lock( )

4D v18

entity.lock( )

Description

La méhode entity.lock( ) pose un verrou pessimiste(*) sur l'enregistrement référencé par l'entité. Le verrou est posé pour l'enregistrement et toutes les références de l'entité dans le process courant.

(*)Pour plus d'informations, veuillez vous reporter à la page Verrouillage d'entités.

Pour les autres process, cet enregistrement apparaîtra verrouillé (la propriété result.success contiendra Faux s'ils tentent de verrouiller la même entité à l'aide de cette méthode. Seules les méthodes exécutées dans la session à l'origine du verrouillage auront la possibilité de modifier et de sauvegarder les attributs de l'entité. L'entité peut être chargée en lecture seulement dans les autres sessions, mais elles ne pourront ni saisir ni sauvegarder des valeurs.

Un enregistrement verrouillé peut être déverrouillé :

lorsque la méthode unlock() est appelée sur une entité correspondante dans le même process
automatiquement lorsqu'il n'est plus référencé par aucune entité en mémoire. Par exemple, si le verrou est posé sur uniquement sur une référence locale d'une entité, l'entité est déverrouillée lorsque la méthode se termine. Tant qu'il reste des références à l'entité en mémoire, l'enregistrement reste verrouillé.

Par défaut, si le paramètre mode est omis, la méthode retournera une erreur (cf. ci-dessous) si la même entité a été modifiée (i.e. si le marqueur stamp a changé) par un autre utilisateur ou process entre-temps.
Sinon, vous pouvez passer l'option dk reload if stamp changed dans le paramètre mode : dans ce cas, aucune erreur n'est générée et l'entité est simplement rechargée si le stamp a changé (si l'entité existe toujours et si la clé primaire est toujours la même).

Résultat

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

Propriété		Type	Description
success		booléen	Vrai si l'action de verrouillage a été effectuée avec succès (ou si l'entité est déjà verrouillée dans le process courant), sinon Faux.
			Disponible uniquement si l'option *dk reload if stamp changed est utilisée :*
wasReloaded		booléen	Vrai si l'entité a été correctement rechargée, sinon Faux.
			Disponible uniquement en cas d'erreur :
status(*)		numérique	Code d'erreur, voir ci-dessous
statusText(*)		texte	Description de l'erreur, voir ci-dessous
			Disponible uniquement en cas d'erreur de verrouillage pessimiste :
lockKindText		texte	"Locked by record"
lockInfo		objet	Information sur l'origine du verrouillage
	task_id	numérique	ID du process
	user_name	texte	Nom d'utilisateur de la session sur la machine
	user4d_alias	texte	Nom ou alias de l'utilisateur 4D
	user4d_id	numérique	Identifiant utilisateur dans le répertoire de la base 4D
	host_name	texte	Nom de la machine
	task_name	texte	Nom du process
	client_version	texte
			Disponible uniquement en cas d'erreur critique (clé primaire dupliquée, disque plein...) :
errors		collection d'objets
	message	texte	Message d'erreur
	component signature	texte	Signature du composant interne (p.e. "dmbg" pour le composant de base de données)
	errCode	nombre	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 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

Exemple avec erreur :

 C_OBJET($employee;$status)

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

 $status:=$employee.lock()

 Au cas ou

    :($status.success)

       ALERTE("Vous avez verrouillé "+$employee.firstName+" "+$employee.lastName)

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

       ALERTE($status.statusText)

 Fin de cas

Exemple 2

Exemple avec option dk reload if stamp changed :

 C_OBJET($employee;$status)

 

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

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

 Au cas ou

    :($status.success)

       ALERTE("Vous avez verrouillé "+$employee.firstName+" "+$employee.lastName)

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

       ALERTE($status.statusText)

 Fin de cas

Voir aussi

entity.unlock( )