Aller au contenu principal
Version: v20 R4 BETA

Entity

Une entity est une instance d'une Dataclass, tel un enregistrement de la table correspondant à la dataclass contenue dans son datastore associé. Elle contient les mêmes attributs que la dataclass ainsi que les valeurs des données et des propriétés et fonctions spécifiques.

Sommaire

.attributeName : any    stocke la valeur de l'attribut pour l'entité
.clone() : 4D.Entity    crée en mémoire une nouvelle entité référençant le même enregistrement que l'entité d'origine
.diff( entityToCompare : 4D.Entity { ; attributesToCompare : Collection } ) : Collection    compare les contenus de deux entités et renvoie leurs différences
.drop( {mode : Integer} ) : Object    supprime du datastore les données contenues dans l'entité
.first(): 4D.Entity    retourne une référence vers l'entité en première position dans l'entity selection à laquelle appartient l'entité
.fromObject( filler : Object )    remplit les attributs de l'entité avec le contenu de filler
.getDataClass() : 4D.DataClass    retourne la dataclass de l'entité
.getKey( { mode : Integer } ) : Text
.getKey( { mode : Integer } ) : Integer
    renvoie la valeur de la clé primaire de l'entité
.getRemoteContextAttributes() : Text    renvoie des informations sur le contexte d'optimisation utilisé par l'entité
.getSelection(): 4D.EntitySelection    renvoie l'entity selection à laquelle l'entité appartient
.getStamp() : Integer     retourne la valeur courante du stamp de l'entité
.indexOf( { entitySelection : 4D.EntitySelection } ) : Integer    retourne la position de l'entité dans une entity selection
.isNew() : Boolean     renvoie Vrai si l'entité à laquelle elle est appliquée vient d'être créée et n'a pas encore été sauvegardée dans le datastore
.last() : 4D.Entity    retourne une référence vers l'entité en dernière position dans l'entity selection à laquelle appartient l'entité
.lock( { mode : Integer } ) : Object    pose un verrou pessimiste sur l'enregistrement référencé par l'entité
.next() : 4D.Entity    retourne une référence vers l'entité suivante dans l'entity selection à laquelle appartient l'entité
.previous() : 4D.Entity     retourne une référence vers l'entité précédente dans l'entity selection à laquelle appartient l'entité
.reload() : Object    recharge en mémoire le contenu de l'entité
.save( { mode : Integer } ) : Object    sauvegarde les modifications apportées à l'entité
.toObject() : Object
.toObject( filterString : Text { ; options : Integer} ) : Object
.toObject( filterCol : Collection { ; options : Integer } ) : Object
    retourne un objet construit à partir de l'entité
.touched() : Boolean    vérifie si un attribut de l'entité a été modifié depuis que l'entité a été chargée en mémoire ou sauvegardée
.touchedAttributes() : Collection    retourne les noms des attributs qui ont été modifiés depuis que l'entité a été chargée en mémoire
.unlock() : Object    supprime le verrou pessimiste posé sur l'enregistrement correspondant à l'entité

.attributeName

Historique
VersionModifications
v17Ajout

.attributeName : any

Description

Tout attribut de dataclass est disponible en tant que propriété d'une entité, qui stocke la valeur de l'attribut pour l'entité.

Les attributs de dataclass peuvent également être obtenus en utilisant la syntaxe alternative avec [ ].

Le type de valeur de l'attribut dépend de l'attribut kind (relation ou storage) :

  • Si le type de attributeName est storage : .attributeName retourne une valeur du même type que attributeName.
  • Si le type de attributeName est relatedEntity : .attributeName retourne une entité reliée. Les valeurs de l'entité liée sont directement disponibles par le biais des propriétés en cascade, par exemple "myEntity.employer.employees[0].lastname".
  • Si le type de attributeName est relatedEntities : .attributeName retourne une nouvelle entity selection d'entités liées. Les doublons sont supprimés (une entity selection non ordonnée est retournée).

Exemple

 var $myEntity : cs.EmployeeEntity
$myEntity:=ds.Employee.new() //Créer une nouvelle entity
$myEntity.name:="Dupont" //assigner 'Dupont' à l'attribut 'name'
$myEntity.firstname:="John" //assigner 'John' à l'attribut 'firstname'
$myEntity.save() //sauvegarder l'entity

.clone()

Historique
VersionModifications
v17Ajout

.clone() : 4D.Entity

ParamètresTypeDescription
Résultat4D.Entity<-Nouvelle entité référençant l'enregistrement

|

Description

La fonction clone() crée en mémoire une nouvelle entité référençant le même enregistrement que l'entité d'origine. Cette fonction vous permet de mettre à jour des entités séparément.

A noter que toute modification apportée aux entités n'est stockée dans l'enregistrement référencé qu'au moment où la fonction .save( ) est exécutée.

Cette fonction ne peut être utilisée qu'avec des entités déjà enregistrées dans la base de données. Elle ne peut pas être appelée sur une entité nouvellement créée (pour laquelle .isNew() retourne True).

Exemple

 var $emp; $empCloned : cs.EmployeeEntity
$emp:=ds.Employee.get(672)
$empCloned:=$emp.clone()

$emp.lastName:="Smith" //Les mises à jour effectuées sur $emp ne le sont pas sur $empCloned

.diff()

Historique
VersionModifications
v17Ajout

.diff( entityToCompare : 4D.Entity { ; attributesToCompare : Collection } ) : Collection

ParamètresTypeDescription
entityToCompare4D.Entity->Entité à comparer à l'entité d'origine
attributesToCompareCollection->Noms des attributs à comparer
RésultatCollection<-Différences entre les entités

|

Description

La fonction diff() compare les contenus de deux entités et renvoie leurs différences.

Dans le paramètre entityToCompare, passez l'entité à comparer à l'entité d'origine.

Dans le paramètre attributesToCompare, vous pouvez désigner les attributs spécifiques à comparer. Si le paramètre est passé, la comparaison est effectuée uniquement sur les attributs spécifiés. S'il est omis, toutes les différences entre les entités sont retournées.

Les différences sont retournées sous forme de collection d'objets dont les propriétés sont :

Nom de propriétéTypeDescription
attributeNameStringNom de l'attribut
valueDépend du type d'attributValeur de l'attribut dans l'entité d'origine
otherValueDépend du type d'attributValeur de l'attribut dans entityToCompare

Seuls les attributs dont les valeurs diffèrent sont inclus dans la collection. Si aucune différence n'est trouvée, .diff() retourne une collection vide.

La fonction s'applique aux attributs dont le kind est storage ou relatedEntity. Dans le cas où une entité liée a été mise à jour (c'est-à-dire la clé étrangère), le nom de l'entité liée et de sa clé primaire sont retournés comme propriétés attributeName (value et otherValue sont vides pour l'entité liée).

Si l'une des entités comparées vaut Null, une erreur est retournée.

Exemple 1

 var $diff1; $diff2 : Collection
employee:=ds.Employee.query("ID=1001").first()
$clone:=employee.clone()
employee.firstName:="MARIE"
employee.lastName:="SOPHIE"
employee.salary:=500
$diff1:=$clone.diff(employee) // Toutes les différences sont retournées
$diff2:=$clone.diff(employee;New collection("firstName";"lastName"))
// Seules les différences sur firstName et lastName sont retournées

$diff1:

[
{
"attributeName": "firstName",
"value": "Natasha",
"otherValue": "MARIE"
},
{
"attributeName": "lastName",
"value": "Locke",
"otherValue": "SOPHIE"
},
{
"attributeName": "salary",
"value": 66600,
"otherValue": 500
}
]
$diff2:

[
{
"attributeName": "firstName",
"value": "Natasha",
"otherValue": "MARIE"
},
{
"attributeName": "lastName",
"value": "Locke",
"otherValue": "SOPHIE"
}
]

Exemple 2

 var vCompareResult1; vCompareResult2; vCompareResult3; $attributesToInspect : Collection
vCompareResult1:=New collection
vCompareResult2:=New collection
vCompareResult3:=New collection
$attributesToInspect:=New collection

$e1:=ds.Employee.get(636)
$e2:=ds.Employee.get(636)

$e1.firstName:=$e1.firstName+" update"
$e1.lastName:=$e1.lastName+" update"

$c:=ds.Company.get(117)
$e1.employer:=$c
$e2.salary:=100

$attributesToInspect.push("firstName")
$attributesToInspect.push("lastName")

vCompareResult1:=$e1.diff($e2)
vCompareResult2:=$e1.diff($e2;$attributesToInspect)
vCompareResult3:=$e1.diff($e2;$e1.touchedAttributes())

vCompareResult1 (toutes les différences sont retournées) :

[
{
"attributeName": "firstName",
"value": "Karla update",
"otherValue": "Karla"
},
{
"attributeName": "lastName",
"value": "Marrero update",
"otherValue": "Marrero"
},
{
"attributeName": "salary",
"value": 33500,
"otherValue": 100
},
{
"attributeName": "employerID",
"value": 117,
"otherValue": 118
},
{
"attributeName": "employer",
"value": "[object Entity]",// Entity 117 de Company
"otherValue": "[object Entity]"// Entity 118 de Company
}
]

vCompareResult2 (seules les différences sur $attributesToInspect sont retournées)

[
{
"attributeName": "firstName",
"value": "Karla update",
"otherValue": "Karla"
},
{
"attributeName": "lastName",
"value": "Marrero update",
"otherValue": "Marrero"
}
]

vCompareResult3 (seules les différences sur les attributs touchés de $e1 sont retournées)

[
{
"attributeName": "firstName",
"value": "Karla update",
"otherValue": "Karla"
},
{
"attributeName": "lastName",
"value": "Marrero update",
"otherValue": "Marrero"
},
{
"attributeName": "employerID",
"value": 117,
"otherValue": 118
},
{
"attributeName": "employer",
"value": "[object Entity]",// Entity 117 de Company
"otherValue": "[object Entity]"// Entity 118 de Company

}
]

.drop()

Historique
VersionModifications
v17Ajout

.drop( {mode : Integer} ) : Object

ParamètresTypeDescription
modeInteger->dk force drop if stamp changed : Force la suppression même si le marqueur interne a changé
RésultatObject<-Résultat de l'opération de suppression

|

Description

La fonction .drop() supprime du datastore les données contenues dans l'entité, dans la table liée à sa dataclass. A noter que l'entité reste en mémoire.

Dans une application multiprocess ou multi-utilisateurs, la fonction .drop() est exécutée en mode "verrouillage optimiste" dans lequel un marqueur de verrouillage interne est automatiquement incrémenté à chaque sauvegarde de l'enregistrement.

Par défaut, si le paramètre mode est omis, la fonction 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).

Sinon, vous pouvez passer l'option dk force drop if stamp changed dans le paramètre mode : dans ce cas, l'entité est supprimée même si la valeur du marqueur interne est différente (si la clé primaire est identique).

Résultat

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

PropriétéTypeDescription
successbooleanvrai si l'action de suppression a été effectuée avec succès, sinon Faux.
Disponible uniquement en cas d'erreur :
status(*)numberCode d'erreur, voir ci-dessous
statusText(*)textDescription de l'erreur, voir ci-dessous
Disponible uniquement en cas d'erreur de verrouillage pessimiste :
LockKindTexttext"Locked by record"
lockInfoobjectInformation sur l'origine du verrouillage
task_idnumberId du process
user_nametextNom d'utilisateur de la session sur la machine
user4d_aliastextAlias utilisateur si défini avec SET USER ALIAS, sinon le nom d'utilisateur dans le répertoire de la base 4D
host_nametextNom de la machine
task_nametextNom du process
client_versiontext
Disponible uniquement en cas d'erreur critique (clé primaire dupliquée, disque plein..) :
errorscollection of objects
messagetextMessage d'erreur
component signaturetextsignature du composant interne (e.g. "dmbg" pour le composant de base de données)
errCodenumberCode 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 :

ConstanteValeurCommentaire
dk status entity does not exist anymore5L'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 drop( ), cette erreur peut être retournée lorsque l'option dk force drop if stamp changed est utilisée. Avec 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 locked3L'entité est verrouillée par un verrou pessimiste.
    statusText associé : "Already locked"
    dk status serious error4Une 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 changed2La valeur du marqueur interne (stamp) de l'entité ne correspond pas à celle de l'entité stockée dans les données (verrouillage optimiste).
  • avec .save( ) : erreur uniquement si l'option dk auto merge n'est pas utilisée
  • avec .drop( ) : erreur uniquement si l'option dk force drop if stamp changed n'est pas utilisée
  • avec .lock( ) : erreur uniquement si l'option dk reload if stamp changed n'est pas utilisée
  • statusText associé : "Stamp has changed"
  • dk status wrong permission1Les privilèges courants ne permettent pas de supprimer l'entité. statusText associé : "Permission error"

    Exemple 1

    Exemple sans option dk force drop if stamp changed :

     var $employees : cs.EmployeeSelection
    var $employee : cs.EmployeeEntity
    var $status : Object
    $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) //L'entité supprimée reste en mémoire
    :($status.status=dk status stamp has changed)
    ALERT($status.statusText)
    End case

    Exemple 2

    Même exemple avec l'option dk force drop if stamp changed :

     var $employees : cs.EmployeeSelection
    var $employee : cs.EmployeeEntity
    var $status : Object
    $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) //L'entité supprimée reste en mémoire
    :($status.status=dk status entity does not exist anymore)
    ALERT($status.statusText)
    End case

    .first()

    Historique
    VersionModifications
    v17Ajout

    .first(): 4D.Entity

    ParamètresTypeDescription
    Résultat4D.Entity<-Référence à la première entité de l'entity selection (Null si non trouvée)

    |

    Description

    La fonction .first() retourne une référence vers l'entité en première position dans l'entity selection à laquelle appartient l'entité.

    Si l'entité n'appartient à aucune entity selection (i.e. .getSelection( ) retourne Null), la fonction renvoie une valeur Null.

    Exemple

     var $employees : cs.EmployeeSelection
    var $employee; $firstEmployee : cs.EmployeeEntity
    $employees:=ds.Employee.query("lastName = :1";"H@") //Cette entity selection contient 3 entités
    $employee:=$employees[2]
    $firstEmployee:=$employee.first() //$firstEmployee est la première entité de l'entity selection $employees

    .fromObject()

    Historique
    VersionModifications
    v17Ajout

    .fromObject( filler : Object )

    ParamètresTypeDescription
    fillerObject->Objet avec lequel remplir l'entité

    |

    Description

    La fonction .fromObject() remplit les attributs de l'entité avec le contenu de filler.

    Cette fonction modifie l'entity d'origine.

    La correspondance entre l'objet et l'entité est établie à partir des noms de propriétés/d'attributs :

    • Si une propriété de l'objet n'existe pas dans la dataclass, elle est ignorée.
    • Les types de données doivent être équivalents. S'il existe une différence de type entre l'objet et la dataclass, 4D essaie de convertir les données lorsque cela est possible (voir Conversion des types de données), sinon l'attribut demeure intact.
    • La clé primaire peut être donnée telle quelle ou avec une propriété "__KEY" (remplie avec la valeur de la clé primaire). Si elle n'existe pas déjà dans la dataclass, l'entité est créée avec la valeur donnée lorsque .save() est appelé. Si la clé primaire n'est pas fournie, l'entité est créée et la valeur de la clé primaire est affectée en fonction des règles de la base de données. L'auto-incrémentation n'est calculée que si la clé primaire est nulle.

    filler peut contenir une related entity dans les conditions suivantes :

    • filler contient lui-même la clé étrangère, ou
    • filler contient une propriété de type objet qui a le même nom que l'entité relative, contenant une seule propriété nommée "__KEY".
    • si l'entité relative n'existe pas, elle est ignorée.

    Exemple

    Avec l'objet $o suivant :

    {
    "firstName": "Mary",
    "lastName": "Smith",
    "salary": 36500,
    "birthDate": "1958-10-27T00:00:00.000Z",
    "woman": true,
    "managerID": 411,// relatedEntity fournie avec clé primaire
    "employerID": 20 // relatedEntity fournie avec clé primaire
    }

    Le code suivant créera une entité avec les entités relatives manager et employer.

     var $o : Object
    var $entity : cs.EmpEntity
    $entity:=ds.Emp.new()
    $entity.fromObject($o)
    $entity.save()

    Vous pouvez également utiliser une entité relative fournie sous forme d'objet :


    {
    "firstName": "Marie",
    "lastName": "Lechat",
    "salary": 68400,
    "birthDate": "1971-09-03T00:00:00.000Z",
    "woman": false,
    "employer": {// relatedEntity fournie sous forme d'objet
    "__KEY": "21"
    },
    "manager": {// relatedEntity fournie sous forme d'objet
    "__KEY": "411"
    }
    }

    .getDataClass()

    Historique
    VersionModifications
    v17 R5Ajout

    .getDataClass() : 4D.DataClass

    ParamètresTypeDescription
    Résultat4D.DataClass<-Dataclass à laquelle appartient l'entité

    |

    Description

    La fonction .getDataClass() retourne la dataclass de l'entité. Cette fonction est utile pour l'écriture du code générique.

    Exemple

    Le code générique suivant duplique toute entité :

      //méthode duplicate_entity 
    //duplicate_entity($entity)

    #DECLARE($entity : 4D.Entity)
    var $entityNew : 4D.Entity
    var $status : Object

    $entityNew:=$entity.getDataClass().new() //crée une nouvelle entité dans la dataclass parente
    $entityNew.fromObject($entity.toObject()) //lire tous les attributs
    $entityNew[$entity.getDataClass().getInfo().primaryKey]:=Null //réinitialise la clé primaire
    $status:=$entityNew.save() //sauvegarde l'entité dupliquée

    .getKey()

    Historique
    VersionModifications
    v17Ajout

    .getKey( { mode : Integer } ) : Text
    .getKey( { mode : Integer } ) : Integer

    ParamètresTypeDescription
    modeInteger->dk key as string: retourner la clé primaire en texte, quel que soit son type d'origine
    RésultatText<-Valeur de la clé primaire texte de l'entité
    RésultatInteger<-Valeur de la clé primaire numérique de l'entité

    Description

    La fonction .getKey() renvoie la valeur de la clé primaire de l'entité.

    Les clés primaires peuvent être des nombres (integer) ou des textes. Vous pouvez "forcer" la méthode à retourner la valeur de clé primaire sous forme de chaîne, quel que soit son type d'origine, en passant l'option dk key as string dans le paramètre mode.

    Exemple

     var $employees : cs.EmployeeSelection
    var $employee : cs.EmployeeEntity
    $employees:=ds.Employee.query("lastName=:1";"Smith")
    $employee:=$employees[0]
    ALERT("The primary key is "+$employee.getKey(dk key as string))

    .getRemoteContextAttributes()

    Historique
    VersionModifications
    v19R5Ajout

    .getRemoteContextAttributes() : Text

    ParamètresTypeDescription
    resultText<-Attributs de contexte associés à l'entity, séparés par une virgule

    |

    Mode avancé : Cette fonction est destinée aux développeurs qui souhaitent personnaliser les fonctionnalités par défaut de ORDA dans le cadre de configurations spécifiques. Dans la plupart des cas, vous n'aurez pas besoin de l'utiliser.

    Description

    La fonction .getRemoteContextAttributes() renvoie des informations sur le contexte d'optimisation utilisé par l'entité .

    S'il n'existe pas de contexte d'optimisation pour l'entity, la fonction retourne un texte vide.

    Exemple

    var $ds : 4D.DataStoreImplementation
    var $address : cs.AddressEntity
    var $p : cs.PersonsEntity
    var $contextA : Object
    var $info : Text
    var $text : Text

    $ds:=Open datastore(New object("hostname"; "www.myserver.com"); "myDS")

    $contextA:=New object("context"; "contextA")

    $address:=$ds.Address.get(1; $contextA)
    $text:=""
    For each ($p; $address.persons)
    $text:=$p.firstname+" "+$p.lastname
    End for each

    $info:=$address.getRemoteContextAttributes()

    //$info = "persons,persons.lastname,persons.firstname"

    Voir également

    EntitySelection.getRemoteContextAttributes()
    .clearAllRemoteContexts()
    .getRemoteContextInfo()
    .getAllRemoteContexts()
    .setRemoteContextInfo()

    .getSelection()

    Historique
    VersionModifications
    v17Ajout

    .getSelection(): 4D.EntitySelection

    ParamètresTypeDescription
    Résultat4D.EntitySelection<-Entity selection à laquelle appartient l'entité (Null si non trouvée)

    |

    Description

    La fonction .getSelection() renvoie l'entity selection à laquelle l'entité appartient.

    Si l'entité n'appartient pas à une entity selection, la fonction renvoie Null.

    Exemple

     var $emp : cs.EmployeeEntity
    var $employees; $employees2 : cs.EmployeeSelection
    $emp:=ds.Employee.get(672) // Cette entité n'appartient à aucune entity selection
    $employees:=$emp.getSelection() // $employees contient Null

    $employees2:=ds.Employee.query("lastName=:1";"Smith") //Cette entity selection contient 6 entités
    $emp:=$employees2[0] // Cette entité appartient à une entity selection

    ALERT("L'entity selection contient "+String($emp.getSelection().length)+" entités")

    .getStamp()

    Historique
    VersionModifications
    v17Ajout

    .getStamp() : Integer

    ParamètresTypeDescription
    RésultatInteger<-Valeur du "stamp" de l'entité (0 si l'entité vient d'être créée)

    |

    Description

    La fonction .getStamp() retourne la valeur courante du stamp de l'entité.

    Le stamp (marqueur interne) d'une entité est automatiquement incrémenté par 4D à chaque fois qu'une entité est enregistrée sur disque. Il permet de gérer les accès et modifications concurrent(e)s sur les mêmes entités (cf. Entity locking).

    Pour une nouvelle entité (jamais enregistrée), la fonction retourne 0. Pour savoir si une entité vient d'être créée, il est cependant recommandé d'utiliser .isNew().

    Exemple

     var $entity : cs.EmployeeEntity
    var $stamp : Integer

    $entity:=ds.Employee.new()
    $entity.lastname:="Smith"
    $entity.save()
    $stamp:=$entity.getStamp() //$stamp=1

    $entity.lastname:="Wesson"
    $entity.save()
    $stamp:=$entity.getStamp() //$stamp=2

    .indexOf()

    Historique
    VersionModifications
    v17Ajout

    .indexOf( { entitySelection : 4D.EntitySelection } ) : Integer

    ParamètresTypeDescription
    entitySelection4D.EntitySelection->Entity selection dans laquelle obtenir la position de l'entité
    RésultatInteger<-Position de l'entité dans l'entity selection

    |

    Description

    La fonction .indexOf() retourne la position de l'entité dans une entity selection.

    Par défaut, si le paramètre entitySelection est omis, la fonction retourne la position de l'entité dans sa propre entity selection (si elle existe). Sinon, elle renvoie la position de l'entité dans l'entitySelection spécifiée.

    La valeur résultante est comprise entre 0 et la longueur de l'entity selection -1.

    • Si l'entité n'a pas d'entity selection ou n'appartient pas à entitySelection, la fonction retourne -1.
    • Si entitySelection est Null ou n'appartient pas à la même dataclass que l'entité, une erreur est générée.

    Exemple

     var $employees : cs.EmployeeSelection
    var $employee : cs.EmployeeEntity
    $employees:=ds.Employee.query("lastName = :1";"H@") //Cette entity selection contient 3 entités
    $employee:=$employees[1] //Cette entité appartient à l'entity selection
    ALERT("La position de cette entité dans son entity selection est "+String($employee.indexOf())) //1

    $employee:=ds.Employee.get(725) //Cette entité n'appartient pas à l'entity selection
    ALERT("La position de cette entité est "+String($employee.indexOf())) // -1

    .isNew()

    Historique
    VersionModifications
    v17Ajout

    .isNew() : Boolean

    ParamètresTypeDescription
    RésultatBoolean<-Vrai si l'entité vient juste d'être créée et n'a pas encore été enregistrée. Sinon, Faux.

    |

    Description

    La fonction .isNew() renvoie Vrai si l'entité à laquelle elle est appliquée vient d'être créée et n'a pas encore été sauvegardée dans le datastore. Sinon, elle renvoie Faux.

    Exemple

     var $emp : cs.EmployeeEntity

    $emp:=ds.Employee.new()

    If($emp.isNew())
    ALERT("Ceci est une nouvelle entité")
    End if

    .last()

    Historique
    VersionModifications
    v17Ajout

    .last() : 4D.Entity

    ParamètresTypeDescription
    Résultat4D.Entity<-Référence à la dernière entité de l'entity selection (Null si non trouvée)

    |

    Description

    La fonction .last() retourne une référence vers l'entité en dernière position dans l'entity selection à laquelle appartient l'entité.

    Si l'entité n'appartient à aucune entity selection (i.e. .getSelection( ) retourne Null), la fonction renvoie une valeur Null.

    Exemple

     var $employees : cs.EmployeeSelection
    var $employee; $lastEmployee : cs.EmployeeEntity
    $employees:=ds.Employee.query("lastName = :1";"H@") //Cette entity selection contient 3 entités $employee:=$employees[0]
    $lastEmployee:=$employee.last() //$lastEmployee est la dernière entité de l'entity selection $employees

    .lock()

    Historique
    VersionModifications
    v17Ajout

    .lock( { mode : Integer } ) : Object

    ParamètresTypeDescription
    modeInteger->dk reload if stamp changed : Recharger avant de verrouiller si le marqueur interne a changé
    RésultatObject<-Résultat de l'opération lock

    |

    Description

    La fonction 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 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 fonction). Seules les fonctions 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 fonction unlock() est appelée sur une entité correspondante dans le même process
    • automatiquement, lorsqu'elle n'est plus référencée par aucune entité en mémoire. Par exemple, si le verrou n'est posé que sur une référence locale d'une entité, celle-ci est déverrouillée à la fin de la fonction. Tant qu'il existe des références à l'entité en mémoire, l'enregistrement reste verrouillé.

    Pour plus d'informations, veuillez consulter la section Verrouillage d'une entité.

    Par défaut, si le paramètre mode est omis, la fonction 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).

    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 .lock( ) contient les propriétés suivantes :

    PropriétéTypeDescription
    successbooleanvrai 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 :
    wasReloadedbooleanvrai si l'entité a été correctement rechargée, sinon faux.
    Disponible uniquement en cas d'erreur :
    status(*)numberCode d'erreur, voir ci-dessous
    statusText(*)textDescription de l'erreur, voir ci-dessous
    Disponible uniquement en cas d'erreur de verrouillage pessimiste :
    lockKindTexttext"Locked by record" si verrouillage par un process 4D, "Locked by session" si verrouillage par une session REST
    lockInfoobjectInformation sur l'origine du verrouillage. Les propriétés retournées dépendent de l'origine du verrouillage (process 4D ou session REST).
    Disponible uniquement pour un verrouillage par process 4D:
    task_idnumberID du process
    user_nametextNom d'utilisateur de la session sur la machine
    user4d_aliastextNom ou alias de l'utilisateur 4D
    user4d_idnumberIdentifiant utilisateur dans le répertoire de la base 4D
    host_nametextNom de la machine
    task_nametextNom du process
    client_versiontextVersion du client
    Disponible uniquement pour un verrouillage par session REST :
    hosttextURL ayant verrouillé l'entité (ex : "www.myserver.com")
    IPAddrtextAdresse IP d'origine du verrouillage (ex. 127.0.0.1")
    userAgenttextuserAgent de l'origine du verouillage (ex : "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/96.0.4664.110 Safari/537.36")
    Disponible uniquement en cas d'erreur critique (clé primaire dupliquée, disque plein...) :
    errorscollection of objects
    messagetextMessage d'erreur
    component signaturetextsignature du composant interne (e.g. "dmbg" pour le composant de base de données)
    errCodenumberCode 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 :

    ConstanteValeurCommentaire
    dk status entity does not exist anymore5L'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 .drop( ), cette erreur peut être retournée lorsque l'option dk force drop if stamp changed est utilisée. Avec .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 locked3L'entité est verrouillée par un verrou pessimiste.
    statusText associé : "Already locked"
    dk status serious error4Une 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 changed2La valeur du marqueur interne (stamp) de l'entité ne correspond pas à celle de l'entité stockée dans les données (verrouillage optimiste).
  • avec .save( ) : erreur uniquement si l'option dk auto merge n'est pas utilisée
  • avec .drop( ) : erreur uniquement si l'option dk force drop if stamp changed n'est pas utilisée
  • avec .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 :

     var $employee : cs.EmployeeEntity
    var $status : Object
    $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

    Exemple 2

    Exemple avec option dk reload if stamp changed :

     var $employee : cs.EmployeeEntity
    var $status : Object
    $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

    .next()

    Historique
    VersionModifications
    v17Ajout

    .next() : 4D.Entity

    ParamètresTypeDescription
    Résultat4D.Entity<-Référence à l'entité suivante dans l'entity selection (Null si non trouvée)

    |

    Description

    La fonction .next() retourne une référence vers l'entité suivante dans l'entity selection à laquelle appartient l'entité.

    Si l'entité n'appartient à aucune entity selection existante (i.e. .getSelection() retourne Null), la fonction renvoie une valeur Null.

    If the entity does not belong to any existing entity selection (i.e. .getSelection( ) returns Null), the function returns a Null value.

    Exemple

     var $employees : cs.EmployeeSelection
    var $employee; $nextEmployee : cs.EmployeeEntity
    $employees:=ds.Employee.query("lastName = :1";"H@") //Cette entity selection contient 3 entités
    $employee:=$employees[0]
    $nextEmployee:=$employee.next() //$nextEmployee est la deuxième entité de l'entity selection $employees

    .previous()

    Historique
    VersionModifications
    v17Ajout

    .previous() : 4D.Entity

    ParamètresTypeDescription
    Résultat4D.Entity<-Référence à l'entité précédente dans l'entity selection (Null si non trouvée)

    |

    Description

    La fonction .previous() retourne une référence vers l'entité précédente dans l'entity selection à laquelle appartient l'entité.

    Si l'entité n'appartient à aucune entity selection existante (i.e. .getSelection() retourne Null), la fonction renvoie une valeur Null.

    If the entity does not belong to any existing entity selection (i.e. .getSelection( ) returns Null), the function returns a Null value.

    Exemple

     var $employees : cs.EmployeeSelection
    var $employee; $previousEmployee : cs.EmployeeEntity
    $employees:=ds.Employee.query("lastName = :1";"H@") //Cette entity selection contient 3 entités
    $employee:=$employees[1]
    $previousEmployee:=$employee.previous() //$previousEmployee est la première entité de l'entity selection $employees

    .reload()

    Historique
    VersionModifications
    v17Ajout

    .reload() : Object

    ParamètresTypeDescription
    RésultatObject<-Objet statut

    |

    Description

    La fonction .reload() recharge en mémoire le contenu de l'entité, à partir des informations stockées dans la table associée à la dataclass dans le datastore. Le rechargement est effectué uniquement si l'entité existe toujours avec la même clé primaire.

    Résultat

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

    PropriétéTypeDescription
    successbooleanVrai si l'action de rechargement est réussie, Faux sinon. Disponible uniquement en cas d'erreur:
    status(*)numberCode d'erreur, voir ci-dessous
    statusText(*)textDescription de l'erreur, voir ci-dessous

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

    ConstanteValeurCommentaire
    dk status entity does not exist anymore5L'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 .drop( ), cette erreur peut être retournée lorsque l'option dk force drop if stamp changed est utilisée. Avec .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 serious error4Une 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"

    Exemple

     var $employee : cs.EmployeeEntity
    var $employees : cs.EmployeeSelection
    var $result : Object

    $employees:=ds.Employee.query("lastName=:1";"Hollis")
    $employee:=$employees[0]
    $employee.firstName:="Mary"
    $result:=$employee.reload()
    Case of
    :($result.success)
    ALERT("Rechargement effectué")
    :($result.status=dk status entity does not exist anymore)
    ALERT("L'entité a été supprimée")
    End case

    .save()

    Historique
    VersionModifications
    v17Ajout

    .save( { mode : Integer } ) : Object

    ParamètresTypeDescription
    modeInteger->dk auto merge : Active le mode "automatic merge"
    RésultatObject<-Résultat de la sauvegarde

    |

    Description

    La fonction save() sauvegarde les modifications apportées à l'entité dans la table liée à sa dataclass. Vous devez appeler cette fonction après toute création ou modification d'entité si vous souhaitez sauvegarder les changements.

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

    Dans une application multi-utilisateur ou multi-process, la fonction .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.

    Par défaut, si le paramètre mode est omis, la fonction 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).

    Sinon, 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 simultanée effectuée 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").

    Le mode de fusion automatique n'est pas disponible pour les attributs de type Image, Objet et Texte lorsqu'ils sont stockés en dehors de l'enregistrement. Des modifications simultanées de ces attributs entraîneront une erreur "dk status stamp has changed".

    Résultat

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

    PropriétéTypeDescription
    successbooleanVrai si la sauvegarde a été effectuée avec succès, sinon faux.
    Disponible uniquement si l'option dk auto merge a été utilisée :
    autoMergedbooleanVrai si un "auto merge" a été effectué, sinon faux.
    Disponible uniquement en cas d'erreur :
    statusnumberCode d'erreur, voir ci-dessous
    statusTexttextDescription de l'erreur, voir ci-dessous
    Disponible uniquement en cas d'erreur en verrouillage pessimiste :
    lockKindTexttext"Locked by record"
    lockInfoobjectInformation sur l'origine du verrouillage
    task_idnumberId du process
    user_nametextNom d'utilisateur de la session sur la machine
    user4d_aliastextAlias utilisateur si défini avec SET USER ALIAS, sinon le nom d'utilisateur dans le répertoire de la base 4D
    host_nametextNom de la machine
    task_nametextNom du process
    client_versiontext
    Disponible uniquement en cas d'erreur critique (clé primaire dupliquée, disque plein...) :
    errorscollection of objects
    messagetextMessage d'erreur
    componentSignaturetextSignature du composant interne (e.g. "dmbg" pour le composant de base de données)
    errCodenumberCode d'erreur
    status et statusText

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

    ConstanteValeurCommentaire
    dk status automerge failed6(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 anymore5L'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 .drop( ), cette erreur peut être retournée lorsque l'option dk force drop if stamp changed est utilisée. Avec .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 locked3L'entité est verrouillée par un verrou pessimiste.
    statusText associé : "Already locked"
    dk status serious error4Une 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 changed2La valeur du marqueur interne (stamp) de l'entité ne correspond pas à celle de l'entité stockée dans les données (verrouillage optimiste).
  • avec .save( ) : erreur uniquement si l'option dk auto merge n'est pas utilisée
  • avec .drop( ) : erreur uniquement si l'option dk force drop if stamp changed n'est pas utilisée
  • avec .lock( ) : erreur uniquement si l'option dk reload if stamp changed n'est pas utilisée

  • statusText associé : "Stamp has changed"
    dk status wrong permission1Les privilèges courants ne permettent pas de supprimer l'entité. statusText associé : "Permission error"

    Exemple 1

    Création d'une entité :

     var $status : Object
    var $employee : cs.EmployeeEntity
    $employee:=ds.Employee.new()
    $employee.firstName:="Mary"
    $employee.lastName:="Smith"
    $status:=$employee.save()
    If($status.success)
    ALERT("Employé créé")
    End if

    Exemple 2

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

     var $status : Object
    var $employee : cs.EmployeeEntity
    var $employees : cs.EmployeeSelection
    $employees:=ds.Employee.query("lastName=:1";"Smith")
    $employee:=$employees.first()
    $employee.lastName:="Mac Arthur"
    $status:=$employee.save()
    Case of
    :($status.success)
    ALERT("Employé mis à jour")
    :($status.status=dk status stamp has changed)
    ALERT($status.statusText)
    End case

    Exemple 3

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

     var $status : Object

    var $employee : cs.EmployeeEntity
    var $employees : cs.EmployeeSelection

    $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("Employé mis à jour")
    :($status.status=dk status automerge failed)
    ALERT($status.statusText)
    End case

    .toObject()

    Historique
    VersionModifications
    v17Ajout

    .toObject() : Object
    .toObject( filterString : Text { ; options : Integer} ) : Object
    .toObject( filterCol : Collection { ; options : Integer } ) : Object

    ParamètresTypeDescription
    filterStringText->Attribut(s) à extraire (chaînes séparées par des virgules)
    filterColCollection->Collection d'attribut(s) à extraire
    optionsInteger->dk with primary key: ajoute la propriété __KEY ;
    dk with stamp: ajoute la propriété _STAMP
    RésultatObject<-Objet généré à partir de l'entité

    |

    Description

    La fonction .toObject() retourne un objet construit à partir de l'entité. Les noms des propriétés de l'objet correspondent aux noms des attributs de l'entité.

    Si aucun filtre n'est passé ou si le paramètre filterString contient une chaîne vide ou "*", l'objet retourné contiendra :

    • tous les attributs storage de l'entité
    • attributs de kind relatedEntity : vous obtenez une propriété portant le même nom que l'entité liée (nom du lien N vers 1). L'attribut est extrait sous forme simple.
    • attributs de kind relatedEntities : non retournés.

    Dans le premier paramètre, indiquez le ou les attribut(s) à extraire. Vous pouvez passer :

    • filterString : une chaîne avec les chemins des propriétés séparés par des virgules : "propertyPath1, propertyPath2, ...", ou
    • filterCol : une collection de chaînes contenant des chemins de propriétés : ["propertyPath1","propertyPath2";...]

    Si un filtre est spécifié pour les attributs dont le kind est relatedEntity :

    • propertyPath = "relatedEntity" -> l'attribut est extrait sous forme simple : un objet avec la propriété __KEY (clé primaire).
    • propertyPath = "relatedEntity.*" -> toutes les propriétés sont extraites
    • propertyPath = "relatedEntity.propertyName1; relatedEntity.propertyName2; ..." -> seules ces propriétés sont extraites

    Si un filtre est spécifié pour les attributs dont le kind est relatedEntities :

    • propertyPath = "relatedEntities.*" -> toutes les propriétés sont extraites
    • propertyPath = "relatedEntities.propertyName1; relatedEntities.propertyName2; ..." -> seules ces propriétés sont extraites

    Dans le paramètre options, vous pouvez passer les sélecteurs dk with primary key et/ou dk with stamp afin d'ajouter les clés primaires et/ou les stamps dans les objets extraits.

    Avertissement

    Si vous utilisez un autre attribut que la clé primaire comme attribut 1 dans une relation, la valeur de cet attribut sera inscrite dans la propriété "__KEY". Gardez à l'esprit qu'il est recommandé d'utiliser la clé primaire comme attribut 1 dans vos relations, en particulier lorsque vous utilisez les fonctions .toObject() et .fromObject() .

    Exemple 1

    La structure suivante sera utilisée pour les exemples de cette section :

    Sans paramètre filtre :

    employeeObject:=employeeSelected.toObject()

    Retourne :

    {
    "ID": 413,
    "firstName": "Greg",
    "lastName": "Wahl",
    "salary": 0,
    "birthDate": "1963-02-01T00:00:00.000Z",
    "woman": false,
    "managerID": 412,
    "employerID": 20,
    "photo": "[object Picture]",
    "extra": null,
    "employer": { // relatedEntity extraite sous forme simple
    "__KEY": 20
    },
    "manager": {
    "__KEY": 412
    }
    }

    Exemple 2

    Extraction de la clé primaire et du stamp :

    employeeObject:=employeeSelected.toObject("";dk with primary key+dk with stamp)

    Retourne :

    {
    "__KEY": 413,
    "__STAMP": 1,
    "ID": 413,
    "firstName": "Greg",
    "lastName": "Wahl",
    "salary": 0,
    "birthDate": "1963-02-01T00:00:00.000Z",
    "woman": false,
    "managerID": 412,
    "employerID": 20,
    "photo": "[object Picture]",
    "extra": null,
    "employer": {
    "__KEY": 20
    },
    "manager": {
    "__KEY": 412
    }
    }

    Exemple 3

    Extraction complète des attributs des relatedEntities :

    employeeObject:=employeeSelected.toObject("directReports.*")
    {
    "directReports": [
    {
    "ID": 418,
    "firstName": "Lorena",
    "lastName": "Boothe",
    "salary": 44800,
    "birthDate": "1970-10-02T00:00:00.000Z",
    "woman": true,
    "managerID": 413,
    "employerID": 20,
    "photo": "[object Picture]",
    "extra": null,
    "employer": {
    "__KEY": 20
    },
    "manager": {
    "__KEY": 413
    }
    },
    {
    "ID": 419,
    "firstName": "Drew",
    "lastName": "Caudill",
    "salary": 41000,
    "birthDate": "2030-01-12T00:00:00.000Z",
    "woman": false,
    "managerID": 413,
    "employerID": 20,
    "photo": "[object Picture]",
    "extra": null,
    "employer": {
    "__KEY": 20
    },
    "manager": {
    "__KEY": 413
    }
    },
    {
    "ID": 420,
    "firstName": "Nathan",
    "lastName": "Gomes",
    "salary": 46300,
    "birthDate": "2010-05-29T00:00:00.000Z",
    "woman": false,
    "managerID": 413,
    "employerID": 20,
    "photo": "[object Picture]",
    "extra": null,
    "employer": {
    "__KEY": 20
    },
    "manager": {
    "__KEY": 413
    }
    }
    ]
    }

    Exemple 4

    Extraction de quelques attributs des relatedEntities :

     employeeObject:=employeeSelected.toObject("firstName, directReports.lastName")

    Retourne :

    {
    "firstName": "Greg",
    "directReports": [
    {
    "lastName": "Boothe"
    },
    {
    "lastName": "Caudill"
    },
    {
    "lastName": "Gomes"
    }
    ]
    }

    Exemple 5

    Extraction d'une relatedEntity sous forme simple :

     $coll:=New collection("firstName";"employer")
    employeeObject:=employeeSelected.toObject($coll)

    Retourne :

    {
    "firstName": "Greg",
    "employer": {
    "__KEY": 20
    }
    }

    Exemple 6

    Extraction de tous les attributs d'une relatedEntity :

     employeeObject:=employeeSelected.toObject("employer.*")

    Retourne :

    {
    "employer": {
    "ID": 20,
    "name": "India Astral Secretary",
    "creationDate": "1984-08-25T00:00:00.000Z",
    "revenues": 12000000,
    "extra": null
    }
    }

    Exemple 7

    Extraction de quelques attributs d'une relatedEntity :

     $col:=New collection
    $col.push("employer.name")
    $col.push("employer.revenues")
    employeeObject:=employeeSelected.toObject($col)

    Retourne :

    {
    "employer": {
    "name": "India Astral Secretary",
    "revenues": 12000000
    }
    }

    .touched( )

    Historique
    VersionModifications
    v17Ajout

    .touched() : Boolean

    ParamètresTypeDescription
    RésultatBoolean<-Vrai si au moins un attribut de l'entité a été modifié et non encore sauvegardé, sinon Faux

    |

    Description

    La fonction touched() vérifie si un attribut de l'entité a été modifié depuis que l'entité a été chargée en mémoire ou sauvegardée.

    Si un attribut a été modifié ou calculé, la fonction retourne Vrai, sinon elle retourne Faux. Vous pouvez utiliser cette fonction pour savoir s'il est nécessaire de sauvegarder l'entité.

    Cette fonction retourne Faux pour une entité qui vient d'être créée (avec .new( )). A noter cependant que si vous utilisez une fonction pour calculer un attribut de l'entité, la fonction .touched() retournera Vrai. Par exemple, si vous appelez .getKey() pour calculer la clé primaire, .touched() retourne alors Vrai.

    Exemple

    Cet exemple vérifie s'il est nécessaire de sauvegarder l'entité :

     var $emp : cs.EmployeeEntity
    $emp:=ds.Employee.get(672)
    $emp.firstName:=$emp.firstName //Même réassigné avec sa propre valeur, l'attribut est considéré "touched"

    If($emp.touched()) //si au moins l'un des attributs a été modifié
    $emp.save()
    End if // sinon, inutile de sauvegarder l'entité

    .touchedAttributes( )

    Historique
    VersionModifications
    v17Ajout

    .touchedAttributes() : Collection

    ParamètresTypeDescription
    RésultatCollection<-Noms des attributs touchés ou collection vide

    |

    Description

    La fonction .touchedAttributes() retourne les noms des attributs qui ont été modifiés depuis que l'entité a été chargée en mémoire.

    Cette fonction est applicable aux attributs dont le kind est storage ou relatedEntity.

    Dans le cas d'un attribut relationnel ayant été "touché" (i.e., la clé étrangère), le nom de l'entité liée et celui de sa clé primaire sont retournés.

    Si aucun attribut de l'entité n'a été touché, la fonction retourne une collection vide.

    Exemple 1

     var $touchedAttributes : Collection
    var $emp : cs.EmployeeEntity

    $touchedAttributes:=New collection
    $emp:=ds.Employee.get(725)
    $emp.firstName:=$emp.firstName //Même modifié avec la même valeur, l'attribut est considéré comme touché
    $emp.lastName:="Martin"
    $touchedAttributes:=$emp.touchedAttributes()
    //$touchedAttributes: ["firstName","lastName"]

    Exemple 2

     var $touchedAttributes : Collection
    var $emp : cs.EmployeeEntity
    var $company : cs.CompanyEntity

    $touchedAttributes:=New collection

    $emp:=ds.Employee.get(672)
    $emp.firstName:=$emp.firstName
    $emp.lastName:="Martin"

    $company:=ds.Company.get(121)
    $emp.employer:=$company

    $touchedAttributes:=$emp.touchedAttributes()

    //collection $touchedAttributes: ["firstName","lastName","employer","employerID"]

    Dans ce cas :

    • firstName et lastName ont un type storage
    • employer a un type relatedEntity
    • employerID est la clé étrangère de l'entité reliée employer

    .unlock()

    Historique
    VersionModifications
    v17Ajout

    .unlock() : Object

    ParamètresTypeDescription
    RésultatObject<-Objet statut

    |

    Description

    La fonction unlock() supprime le verrou pessimiste posé sur l'enregistrement correspondant à l'entité dans la table liée à sa dataclass.

    Pour plus d'informations, veuillez consulter la section Verrouillage d'une entité.

    Un enregistrement est automatiquement déverrouillé lorsqu'il n'est plus référencé par aucune entité dans le process qui l'a verrouillé (par exemple : si le verrou est posé sur uniquement sur une référence locale d'une entité, l'entité et donc l'enregistrement sont déverrouillés lorsque le process se termine).

    Lorsqu'un enregistrement est verrouillé, il doit être déverrouillé depuis le process qui l'a verrouillé et via la référence d'entité sur laquelle le verrou a été posé. Par exemple :

     $e1:=ds.Emp.all()[0]
    $e2:=ds.Emp.all()[0]
    $res:=$e1.lock() //$res.success=true
    $res:=$e2.unlock() //$res.success=false
    $res:=$e1.unlock() //$res.success=true

    Résultat

    L'objet retourné par .unlock() contient la propriété suivante :

    PropriétéTypeDescription
    successBooleanVrai si l'action unlock a été exécutée avec succès, Faux sinon. Si le déverrouillage est effectué sur une entité qui a été supprimée, sur un enregistrement non verrouillé ou sur un enregistrement verrouillé par un autre process ou une autre entité, success vaut Faux.

    Exemple

     var $employee : cs.EmployeeEntity
    var $status : Object

    $employee:=ds.Employee.get(725)
    $status:=$employee.lock()
    ... //processing
    $status:=$employee.unlock()
    If($status.success)
    ALERT("L'entité est déverrouillée")
    End if