Descriptor (TQueryExecuteTask)

property Descriptor:TfwxmlDocument;

Cette propriété contient le descriptif d'exportation.

La structure d'un descripteur d'exportation est la suivante :

Tip : Toutes les valeurs sont définies dans le texte des éléments, sauf spécifié

<root>
  <title>...</title>
 
  <queries>
    <query>...</query>
    ...
  </queries>
 
  <output>...</output>
 
  <exporter>...</exporter>
 
  <interface>...</interface>
 
  <parameters>
    <parameter>...</parameter>
    ...
  </parameters>
 
  <statements>
    <statement>...</statement>
    ...
  </statements>
 
  <scripts>
    <script>...</script>
    ...
  </scripts>
<root>

Title

Titre du descriptif

queries

Cette section est une collection de requêtes (query)

query

Cette section décrit une requête

Item	Type	O/F	Valeur
ClassName	string	O	Nom de la classe de la requête
navMode	string	F	Mode de navigation
Filter	string	F	Expression objet de filtre (par défaut)
Descendants	boolean	F	Inclure les classes descendantes
ClassFilter	string	F	Filtre sur les classes
OrderBy	string	F	Ordre de tri
NoOrderBy	boolean	F	Pas de tri
NoOrderByOID	boolean	F	Pas de tri par OID
Distinct	boolean	F	Ajout de la clause distinct
ShareRestrictions	string	F	Restrictions de partage
NoInCommitCache	boolean	F	ignorer le cache
Args	Liste de Arg	F	Liste d'arguments par index
Condition	Script	F	Condition d'exécution de la requête
parameters	Liste de parameter	F	Liste de paramètres par nom
filters	Liste de filtre	F	Liste de filtres conditionnables

• Condition

Expression permettant de conditionner l'exécution de la requête.

Arg

Text de l'élément Arg

Valeur sérialisée du paramètre

Parameter

Name	Nom du paramètre
Value	Valeur sérialisée du paramètre

Filter

Filter	Expression objet du filtre
Term	Expression objet d'un terme du filtre
Condition	Expression logique suivant laquelle s'applique le filtre

• Filter

Si défini, remplace totalement le filtre

• Term

Si défini, s'ajoute au filtre existant (combinaison AND)

• Condition

La condition est un script devant retourner une valeur logique, si la valeur retournée est vraie le filtre s'applique.

Exemple avec filter:

  ////////////////////////////////////////////////////////////////////////////// 
  itps := itr.AddItem('parameters'); 
  ////////////////////////////////////////////////////////////////////////////// 
  // these are public parameters 
  itps.AddChildItems('parameter',['name','value','isPublic'],['ArgNonLettre',True,True]);
  .....
 
  ////////////////////////////////////////////////////////////////////////////// 
  itqs := itr.AddItem('queries');
  ////////////////////////////////////////////////////////////////////////////// 
  itq := itqs.AddChildItems('query',['QueryName','ClassName','Filter'],['q3','VueExportBalanceEcriture',
      '(CodeNorme in %ArgApprocheNorme)'+
      'and(OrigineLot<>%ArgOrigineLotAN)and(OrigineLot<>%ArgOrigineLotCloture)'+
      'and(DateDebut>=%ArgDateDebut)and(DateDebut<=%ArgDateFin)'
      ]); 
  itfs := itq.AddItem('filters');
  itfs.AddChildItems('filter[name="nonLettre"]',['filter','condition'],[
      // filter on "non lettre" ecritures 
      '(CodeNorme in %ArgApprocheNorme)'+
      'and(OrigineLot<>%ArgOrigineLotAN)and(OrigineLot<>%ArgOrigineLotCloture)'+
      'and(DateDebut>=%ArgDateDebut)and(DateDebut<=%ArgDateFin)'+
      'and(((oidlettrageEcriture='''') or (dateLettrage>%ArgDateFin)) or (Total=0))',
      // condition to apply this filter
      'begin'#13+
      '  Result := ArgNonLettre = True;'#13+
      'end;' 
  ]);

Exemple avec term:

  ////////////////////////////////////////////////////////////////////////////// 
  itps := itr.AddItem('parameters'); 
  ////////////////////////////////////////////////////////////////////////////// 
  // these are public parameters 
  itps.AddChildItems('parameter',['name','value','isPublic'],['ArgNonLettre',True,True]);
  .....
 
  ////////////////////////////////////////////////////////////////////////////// 
  itqs := itr.AddItem('queries');
  ////////////////////////////////////////////////////////////////////////////// 
  itq := itqs.AddChildItems('query',['QueryName','ClassName','Filter'],['q3','VueExportBalanceEcriture',
      '(CodeNorme in %ArgApprocheNorme)'+
      'and(OrigineLot<>%ArgOrigineLotAN)and(OrigineLot<>%ArgOrigineLotCloture)'+
      'and(DateDebut>=%ArgDateDebut)and(DateDebut<=%ArgDateFin)'
      ]); 
  itfs := itq.AddItem('filters');
  itfs.AddChildItems('filter[name="nonLettre"]',['term','condition'],[
      // filter on "non lettre" ecritures 
      '(((oidlettrageEcriture='''') or (dateLettrage>%ArgDateFin)) or (Total=0))',
      // condition to apply this filter
      'begin'#13+
      '  Result := ArgNonLettre = True;'#13+
      'end;' 
  ]);

output

Cette section décrit la destination de l'export

Item	Type	O/F	Valeur
BooksheetName	string	F	Nom de l'onglet si le document est un classeur
BooksheetInfo	string	F	Titre de l'onglet si le document est un claseur
OutputContainerName	string	F	Nom du containeur de sortie
OutputFileName	string	F	Nom du fichier de sortie
OutputDocumentName	string	F	Nom du document de sortie
OutputMailTo	string	F	Adresse(s) messagerie de sortie
OutputMailSubject	string	F	Sujet du mail
OutputMailBody	string	F	Corps du mail
OutputQueueName	string	F	Nom de la file d'attente de sortie
OutputEncoding	string	F	Encodage du fichier de sortie
OutputContentType	string	F	Type de contenu du fichier de sortie
ExportColumns	boolean	F	Exporter les entêtes de colonne
Compressed	boolean	F	Compresser le fichier de sortie
columns	Liste de column	O	Liste des colonnes à exporter

Column

Item	Type	O/F	Valeur
PropName	string	O	Nom de l'attribut de la classe de la requête
Title	string	O	Titre de la colonne
Offset	integer	F	Offset dans le fichier de sortie (format fixe)
Length	integer	F	Longueur dans le fichier de sortie (format fixe)
Disable	boolean	F	Désactiver la colonne
values	Liste de valeurs	F	Liste de valeurs de substitution pour cette colonne

Valeur de substitution

Item	Type	O/F	Valeur
oldValue	String	O	Ancienne valeur
newValue	String	O	Nouvelle valeur

Tip : Une ancienne valeur à vide remplacera toutes les valeurs

Tip : Il est possible de définir les valeurs de substitution par les scripts

exporter

Cette section décrit le formatage des données exportées.

Les propriétés de l'exporteur dépendent du type de l'exporteur.

Item	Type	O/F	Valeur
ClassName	string	O	Nom de la classe de l'exporteur
NumberFormat	string	F	Format de nombre
WordWrap	string	F	WordWrap
Landscape	string	F	Landscape
AsCube	string	F	AsCube
PrintColors	string	F	PrintColors
ExportColors	string	F	ExportColors
Borderaround	string	F	BorderAround
GridMode	string	F	GridMode
FitToWidth	string	F	FitToWidth
ScaleFactor	string	F	ScaleFactor
PageOrder	string	F	PageOrder
Title	string	F	Title
Title2	string	F	Title2
HeaderPage	string	F	HeaderPage
HeaderText	string	F	HeaderText
FooterText	string	F	FooterText

Classe d'exporteur

TCSVExporter	Export au format CSV (.csv)
TPdfExporter	Acrobat Reader (.pdf)
TXMLExporter	Export au format xml (.xml)
TOpenXmlExporter	Microsoft Excel 2007 (.xlsx)
TOpenDocumentExporter	Open Office 1.2 (.ods)

interface

Cette section indique que la classe principale du descriptif est une interface.

Item	Type	O/F	Valeur
ClassName	string	O	Nom de l'interface
OrderBy	string	F	Ordre de tri du résultat (membre de l'interface)
OrderByDesc	boolean	F	Ordre de tri descendant
UnionAll	boolean	F	Utiliser "UNION ALL" au lieu de "UNION"

Lorsqu'une interface est utilisée toutes les requêtes dont la classe supporte l'interface sont jointe dans une UNION :

  Statements "Before"
  (
  Code SQL généré par la requête 1 si sa classe supporte l'interface 
  )
  UNION
  (
  Code SQL généré par la requête 2 si sa classe supporte l'interface 
  )
  UNION
  ....
  Order By défini dans la section Interface
  Statements "After"

parameters

Cette section décrit des paramètres communs à toutes les requêtes.

parameter

Item	Type	O/F	Valeur
Name	string	O	Nom du paramètre
isPublic	boolean	F	ce paramètre est publique
dataType	string	F	Type de donnée attendu
value	string	F	Valeur sérialisée du paramètre
expression	string	F	Expression définissant la valeur du paramètre
script	string	F	Script objet définissant la valeur du paramètre
query	query descriptor	F	Descripteur de requête associé à l'expression du paramètre

Tip : Les paramètres publiques sont exposés dans la liste des paramètres de l'objet TQueryExecuteTask, ils peuvent être définis dans les interfaces de conception et d'exécution.

Le format d'une expression est :

Expression retournant un tableau de valeurs (pour utilisation dans une clause in)

[query:propName]

Expression retournant une valeur :

@query:propName@

Exemple de paramètre défini par une expression:

  ////////////////////////////////////////////////////////////////////////////// 
  itqs := itr.AddItem('queries');
  ////////////////////////////////////////////////////////////////////////////// 
  itq  := itqs.AddChildItems('query',['QueryName','ClassName','Filter'],['q1','VueExportBalanceAN','(CodeNorme in %ArgApprocheNorme)']); 
  itq := itqs.AddChildItems('query',['QueryName','ClassName','Filter'],['p1','TApprocheNorme','(TApprocheComptable.code=%ArgApprocheComptable)']); 
 
 
  ////////////////////////////////////////////////////////////////////////////// 
  itps := itr.AddItem('parameters'); 
  ////////////////////////////////////////////////////////////////////////////// 
  itps.AddChildItems('parameter',['name','expression'],['ArgApprocheNorme','[p1:oidTNormeComptable]']);

Requête définie au niveau du paramètre :

  ////////////////////////////////////////////////////////////////////////////// 
  itqs := itr.AddItem('queries');
  ////////////////////////////////////////////////////////////////////////////// 
  itq  := itqs.AddChildItems('query',['QueryName','ClassName','Filter'],['q1','VueExportBalanceAN','(CodeNorme in %ArgApprocheNorme)']); 
 
 
  ////////////////////////////////////////////////////////////////////////////// 
  itps := itr.AddItem('parameters'); 
  ////////////////////////////////////////////////////////////////////////////// 
  itp := itps.AddChildItems('parameter',['name','expression'],['ArgApprocheNorme','[oidTNormeComptable]']);
  itp.AddChildItems('query',['QueryName','ClassName','Filter'],['p1','TApprocheNorme','(TApprocheComptable.code=%ArgApprocheComptable)']);

Le format d'un script est :

begin
  // The result will be the value of the parameter.
  Result := ...;
end;

Tip : Le context d'exécution du code des scripts permet l'accès aux paramètres globaux du descriptif

Exemple de paramètre défini par un script:

  ////////////////////////////////////////////////////////////////////////////// 
  itps := itr.AddItem('parameters'); 
  ////////////////////////////////////////////////////////////////////////////// 
  itp := itps.AddChildItems('parameter',['name','value'],['ArgMontant',100.00]);
  itp := itps.AddChildItems('parameter',['name','script'],['ArgScript',
    'begin'#13+ 
    '  Result := ArgMontant * 2;'#13+
    'end;'
  ]);

Tip : Les valeurs des paramètres de type expression ou script sont évaluées avant l'exécution.

statements

Cette section décrit des ajouts SQL générés lors de la création du code sql

statement

Item	Type	O/F	Valeur
Provider	string	F	Nom du provider auquel s'applique l'ordre
SQL	string	O	Code SQL généré
mode	string	O	Mode de génération (Before,After)

Exemple :

Création dynamique de descriptif d'exportation :

//Function CreateDescriptor():TxmlDocument;
var itr,itqs,itq,itt,itcs,itc,itu,itvs,itv,itas:TxmlItem;
begin
  Result := TxmlDocument.Create(nil); 
  itr  := TxmlItem.Create(Result); 
  itr.ItemName := 'root';
 
  // Add a main query
  // main is the default query name
  //
  itqs := itr.AddItem('queries');
  itq  := itqs.AddItem('query'); 
  itq.AddItems(['QueryName','ClassName'],['main','WfClasseA']); 
 
  // Filtering 
  //
  itq.AddItemText('Filter','(unBool=%1)'); 
  itas := itq.AddItem('Args');
  itas.AddItemSerializedVariant('Arg',True); // serializedValue for boolean true
 
  // Output
  // 
  itt := itr.addItem('output');  
  itt.AddItemText('ExportColumns','true'); 
 
  // Columns 
  //
  itcs := itt.AddItem('columns');
  // 
  itc := itcs.AddItem('column');
  itc.AddItems(['PropName','Title'],['unCode','Code']); 
  // 
  itc := itcs.AddItem('column');
  itc.AddItems(['PropName','Title'],['unBool','Boolean']); 
 
  // Translate value list
  //
  itvs := itc.AddItem('values');
 
  itv := itvs.AddItem('value');
  itv.AddAttribute('oldValue','N');
  itv.AddAttribute('newValue','false');
  // 
  itv := itvs.AddItem('value');
  itv.AddAttribute('oldValue','O');
  itv.AddAttribute('newValue','true');
 
  itc := itcs.AddItem('column');
  itc.AddItems(['PropName','Title'],['unCompteur','Compteur']); 
 
  itc := itcs.AddItem('column');
  itc.AddItems(['PropName','Title'],['unEntier','Entier']); 
 
  itc := itcs.AddItem('column');
  itc.AddItems(['PropName','Title'],['unEtat','Enuméré']); 
 
  itc := itcs.AddItem('column');
  itc.AddItems(['PropName','Title'],['unDouble','Double']); 
 
  // Define which exporter to used
  // CSV for excel csv format
  //
  itu := itr.AddItem('exporter'); 
  itu.AddItems(['ClassName'],['TCSVExporter']);
end;

Affectation du descriptif à l'instance :

//Procedure Test;
var qbe:TQueryExecuteTask; doc:TxmlDocument;
begin
  qbe := TQueryExecuteTask.Create;
 
  doc := CreateDescriptor();
  AStr := doc.SaveToString;
 
  // Do not create the descriptor directly inside the Descriptor.document
  // instead, use an intermediate document.
  // This will recreate the document with the correct internal item classes
  //
  qbe.Descriptor.Document.LoadFromString(AStr);
 
  ...
end;

scripts

Cette section décrit les scripts exécutable lors de la préparation de la requête

script

Item	Type	O/F	Valeur
mode	string	O	Mode de génération (Before,After)
script	string	O	Code du script

Un script peut accéder aux éléments suivants du descripteur :

Variable / Méthode	Usage
Nom de paramètre global	Définir la valeur d'un paramètre
AddColumn(colName,colTitle)	Ajouter une colonne
SetColumnValue(colName,oldValue,newValue)	Définir une valeur de substitution de colonne
SetColumnEnable(colName,value)	Activer / désactiver une colonne

Exemple :

Définir des arguments:

  ////////////////////////////////////////////////////////////////////////////// 
  itps := itr.AddItem('scripts'); 
  ////////////////////////////////////////////////////////////////////////////// 
  itps.AddItems(['script'],[
   'var Exercice,ExerciceNonCloture:TExercice;'#13+
   'begin'#13+
   '  Exercice := TfacadeTemps.DonnerExercice(ArgDateDebut,0);'#13+
   '  if Assigned(Exercice) then'#13+
   '   begin'#13+
   '     ArgDateSelFinExercice := Exercice.dateFin;'#13+
 
   '     if Exercice.cloture then'#13+
   '      begin'#13+
   '        ArgDateSelDebut := Exercice.dateDebut;'#13+
   '      end'#13+
   '      else'#13+
   '      begin'#13+
   '        ExerciceNonCloture := TExercice.Find(''(cloture = %1)'',''dateDebut'',false,[false]);'#13+
   '        if Assigned(ExerciceNonCloture) then'#13+
   '         begin'#13+
   '           ArgDateSelDebut := ExerciceNonCloture.dateDebut;'#13+
   '         end;'#13+
   '      end;'#13+
   '  end;'#13+
   'end;'
   ]);

Définir des valeurs de substitution:

  ////////////////////////////////////////////////////////////////////////////// 
  itps := itr.AddItem('scripts'); 
  ////////////////////////////////////////////////////////////////////////////// 
  itps.AddItems(['script'],[
   'begin'#13+
   '  SetColumnValue(''unSens'','''',''X'');'#13+ 
   'end;'
   ]);

Voir aussi:

— TQueryExecuteTask_(class) — Développement DSM —