Curseurs d'objets (tech)

Introduction

Les curseurs d'objets (TCursor) permettent d'accéder à un ou plusieurs objets d'une base de données en spécifiant des critères de recherche et de tri ou en utilisant directement des instructions SQL.

Note : Les listes d'objets peuvent être utilisé comme attribut non persistant

Généralement l’utilisation d’un curseur suit le schéma suivant :

1. Le curseur est créé sur une classe particulière, ce sont les objets de cette classe qui seront retournés.
2. Les critères de recherche et de tri sont définis.
3. Le curseur est ouvert.
4. Tant qu’il existe des objets dans le résultat, le curseur est parcouru ; les objets sont retournés un par un dans cette boucle.
5. Le curseur est fermé.

Les curseurs peuvent être implémentés de manière différente suivant les types de serveur de données ; un certain nombre de règles doivent être respectées :

1. Les curseurs sont prévus pour retourner des objets ; ne pas utiliser d’ordre de mise à jour dans le code SQL définissant un curseur.
2. Lorsqu’un curseur est utilisé dans le cadre d’une transaction longue, il est nécessaire de créer la transaction longue avant le curseur.

Déclaration d'une variable curseur

Les curseurs doivent être déclarée avant d'être utilisées, lorsque la classe du curseur est connue au moment de la déclaration la forme préfixé du nom de la classe métier peut être utilisée :

var ls:NomDeClassCursor;

Cette forme de déclaration permet au compilateur de connaitre la classe des objets du curseur.

Création d'un objet curseur

Utilisation du ClassManager

Le ClassManager expose une fonction pour créer des curseurs d'une classe donnée :

function CreateCursor(const iClassName :string):TCursor;

iClassName représente le nom de la classe des objets retournés par le curseur.

Exemple

var ls:TEcritureCursor;
begin
  ls := ClassManager.CreateCursor('TEcriture');
end;

Utilisation du constructeur de curseur d'une classe métier

Les classes métiers exposent un constructeur de curseur permettant de créer un curseur de la classe :

class function TObjectClass.CreateCursor:TObjectClassCursor;

Exemple

var ls:TEcritureList;
begin
  ls := TEcriture.CreateCursor;
end;

Note : Les deux formes de code sont équivalentes, la seconde est plus claire et évite les erreurs de frappe du nom des classes

Propriétés

Propriétés de paramétrage du curseur

Nom	Type	Usage
WHERE	String	Critère de recherche objet permettant de sélectionner les enregistrements renvoyés.
ARGCOUNT	Integer	Spécifie le nombre d'arguments utilisés dans WHERE.
ARGS [ INDEX ]	property Args[index]:Integer;	La propriét Args permet de consulter et de modifier dynamiquement la valeur des arguments utilisés dans WHERE.
ORDERBY	String	Spécifie l'ordre de tri des enregistrements.
DESCENDANTS	Boolean	Inclure ou non les objets descendants.
CLASSFILTER	String	Critère de recherche sur la classe des l'objets parcourus.
MAXINSTANCES	Integer	Limite le nombre d'objet retourné.
NOLOCK	Boolean	Utilise un Hint de base de données pour ne pas verrouiller la table SQL parcourue. Attention : Peut dépendre du pilote de base de données.
ANYWHERE	Boolean	Ne pas filter les objets sur les périmètres de partage. Attention : Cette option n'est à utiliser que pour les dossiers multi-société dans les traitements de type inter-sociétés.
SQL	TStrings	La propriété SQL permet de définir directement les instructions SQL exécutées par le composant. Attention : Aucun contrôle n'est effectué sur le SQL défini dans cette propriété.
TRANSLATOR	Translateur SQL	Objet technique permettant de formatter le code SQL en fonction du pilote de base de données

Propriétés des curseurs avec agrégats

Les curseurs avec agrégats permettent d'exprimer sous forme objet l'équivalent d'un agrégat SQL.

Tip : L'utilisation de ces propriétés évitent d'écrire un curseur sous forme SQL.

Nom	Type	Usage
AGREGATECOUNT	Integer	Détermine le nombre d'agrégat
AGREGATES[ INDEX ]	String	Détermine un attribut à agréger.
AGREGATEOPES[ INDEX ]	Enum	Détermine l'opérateur de l'agrégat. agrSum Somme agrMax Maximum agrMin Minimum agrCount Compte agrAvr Moyenne
GROUPBYCOUNT	Integer	Détermine le nombre d'attribut à regrouper.
GROUPBYS	String	Détermine un attribut à regrouper.
FIELDCOUNT	Integer	Retourne le nombre de champs SQL de la requête.
FIELDS	variant	Retourne la valeur courante du champ de la requête.

Propriétés d'exécution

Nom	Type	Usage
EOI	Boolean	Indique si le curseur est positionné sur le dernier enregistrement d'un ensemble de données.
COUNT	Integer	Renvoie le nombre d'objet qui sera parcourus par le curseur. Note : La lecture de la propriété Count provoque l'exécution de la requête. Count ne peut pas être utilisé sur un curseur avec agrégats.
FETCHCOUNT	Integer	Renvoie le nombre de fetch réalisés.
OID	TOID	Renvoie l'identifiant de l'objet courant.
INSTANCE	TitObject	Renvoie l'instance d'objet courant. La classe de cette instance est la classe spécifiée à la création du curseur.

Méthodes

OPEN	procedure Open;	Exécute la requête.
CLOSE	procedure Close;	Ferme le curseur.
ROLLBACK	procedure RollBack;	Annule toutes les modifications, insertions ou suppressions de données de la transaction en cours et termine la transaction Valable pour un curseur de type modification.
NEXT	procedure Next;	Appelez Next pour placer le curseur sur l'enregistrement suivant.

Exemples

Utilisation de Where

function getCursor:TCursor;
var
  vDOLCursorList : TCursor;
  vWhere : String;
begin
  vDOLCursorList := ClassManager.CreateCursor('TDetailOperationLogistique');
  vDOLCursorList.Where := '(oidLotProduit = %1) and (oidDepot = %2) and (dateExecution >= %3)';
  vDOLCursorList.ArgCount := 3;
  vDOLCursorList.Args[1] := aOidLotProduit ;
  vDOLCursorList.Args[2] := aOidDepot ;
  vDOLCursorList.Args[3] := aDate ;
  //
  vDOLCursorList.NOLOCK := TRUE;
  vDOLCursorList.Open;
  Result := vDOLCursorList;
end;

=Utilisation de Count

//Function CountByCursor(aNomClasse:string):integer;
var vCursorOP :TCursor;
begin
  vCursorOP := ClassManager.CreateCursor(aNomClasse);
  vCursorOP.Descendants := True;
  vCursorOP.Where := aRequete;
  result := vCursorOP.Count;
end;

Curseur avec agrégats

//Procedure TotalEngaementParNature(out rslt:WSX_NatureEngagementList);
var vCursor:TDetailEngagementCursor; inst:WSX_NatureEngagement;
begin
  vCursor := TDetailEngagement.CreateCursor;
  vCursor.Descendants := True;
  vCursor.AgregateCount := 1;
  vCursor.Agregates[1] := 'montantValorisation';
  vCursor.GroupBycount := 1;
  vCursor.GroupBys[1] := 'NatureBudgetaire.code';
  vCursor.Open;
  while not vCursor.Eoi do
   begin
     inst := WSE_NatureEngagement.Create;
     inst.Code := vCursor.Fields[0];
     inst.Montant := vCursor.Fields[1];
     rslt.AddRef(inst);
     vCursor.Next;
   end;
end;

— Code métier — Développement DSM —

Whos here now:   Members 0   Guests 1   Bots & Crawlers 0