Prétraitement du texte des commandes (FireDAC)

De RAD Studio
Aller à : navigation, rechercher

Remonter à Utilisation des commandes (FireDAC)


Rubriques

Rubrique Description
Fonctions macro caractères Liste des fonctions utilisant des chaînes de caractères.
Fonctions macro numériques Liste des fonctions utilisant des nombres.
Fonctions macro date et heure Liste des fonctions utilisant la date et l'heure.
Fonctions macro système Liste des fonctions externes.
Fonction macro CONVERT Décrit la fonction CONVERT.
Support unifié de RETURNING FireDAC supporte la phrase RETURNING Firebird, Oracle et PostgreSQL.


Informations générales

En plusieurs endroits de ce document, une "macro" et une "séquence d'échappement" sont des phrases interchangeables. FireDAC prend en charge trois types d'instructions de macro :

  • Variables de substitution. Ces variables permettent de placer des paramètres de substitution dans un texte de commande afin de développer l'utilisation des paramètres. Par exemple, pour paramétrer un nom de table dans la clause FROM ou les noms de colonne dans la clause SELECT, vous pouvez utiliser des variables de substitution mais pas des paramètres.
  • Séquences d'échappement. Ces séquences permettent d'écrire des commandes SQL indépendantes du SGBD.
  • Substitutions conditionnelles. Ces substitutions permettent le développement de la commande SQL de manière conditionnelle, selon les attributs définis dans l'application ou le SGBD actuellement attaché.

La définition de valeurs de propriété CommandText ou SQL remplit automatiquement la propriété de la collection Macros si la propriété ResourceOptions.MacroCreate est définie sur True. Lors de l'appel de la méthode Prepare, le préprocesseur de commande FireDAC transforme le texte de commande dans un format compris par le SGBD, si la propriété ResourceOptions.MacroExpand vaut True. Cela signifie que les macros ne sont pas visibles pour le SGBD.

La propriété de la collection Params est remplie automatiquement si la valeur de la propriété ResourceOptions.ParamCreate vaut True. Lors de l'appel de la méthode Prepare, FireDAC remplace les marqueurs de paramètre FireDAC par les marqueurs natifs du SGBD si la propriété ResourceOptions.ParamExpand vaut True.

Les séquences d'échappement et les substitutions conditionnelles sont traitées si la propriété ResourceOptions.EscapeExpand vaut True.

Abstraction de dialectes SQL

Si l'application est amenée à prendre en charge plusieurs SGBD, sachez que leurs dialectes SQL peuvent être différents. Les séquences d'échappement FireDAC vous permettent d'écrire des commandes SQL qui sont indépendantes des dialectes SQL.

Ainsi, la fonction de conversion d'une chaîne en majuscule est différente dans MySQL, Oracle et Microsoft SQL Server. En revanche, la commande suivante fonctionne dans tout type de SGBD : 

SELECT {ucase(Name)} FROM MyTable

Notez qu'avec SQLite, vous devez ajouter l'unité FireDAC.Stan.ExprFuncs à votre clause "uses". Dans les cas plus complexes, des parties de la commande, voire la commande toute entière, doivent être réécrites. La séquence d'échappement conditionnelle FireDAC est utile : 

{IF Oracle} SELECT * FROM OracleTab {fi}
{IF MSSQL} SELECT * FROM MSSQLTab {fi}

Variables de substitution

Une variable de substitution commence par le symbole '!' ou '&' et est suivie du nom de la variable de macro. Par exemple : 

SELECT * FROM &TabName

Les symboles ont la signification suivante :

  • '!' -- mode de substitution de "chaîne". La valeur de macro est remplacée "en l'état" sans aucune transformation, directement dans le texte de commande.
  • '&' -– mode de substitution "SQL". La valeur de macro est remplacée en fonction du type de données de macro, à l'aide des règles syntaxiques du SGBD cible.

Pour exploiter les macros, utilisez l'extrait de code suivant : 

FDQuery1.SQL.Text := 'SELECT * FROM &TabName';
FDQuery1.MacroByName('TabName').AsRaw := 'Orders';
FDQuery1.Open;

Les macros sont traitées lorsque les propriétés ResourceOptions.MacroCreate et MacroExpand sont définies sur True.

Marqueurs de paramètre

Un marqueur de paramètre commence par le symbole ':' et est suivi du nom du paramètre. Par exemple : 

SELECT * FROM Orders WHERE OrderDate > :FROM_DATE

Le symbole '?' est reconnu en tant que marqueur de paramètre sans nom. Utilisé dans le cadre de la compatibilité avec DataSnap, il ne doit pas être utilisé dans une application FireDAC classique.

Pour utiliser les paramètres, consultez la section "Utilisation des paramètres" dans la rubrique "Exécution des commandes". Les paramètres sont traités lorsque les propriétés ResourceOptions.ParamCreate et ParamExpand valent True.

Séquences d'échappement

FireDAC fournit cinq types de séquences d'échappement :

  • Autorisation de la substitution de constante.
  • Autorisation de la substitution d'identificateur.
  • Substitution conditionnelle.
  • Séquence d'échappement d'opérateur LIKE.
  • Fonctions scalaires.

Les séquences d'échappement sont traitées lorsque la propriété ResourceOptions.EscapeExpand est définie sur True.

Les séquences d'échappement de substitution de constante permettent l'écriture de constantes dans le texte de commande, indépendamment de la syntaxe du SGBD et des paramètres régionaux. Le tableau suivant décrit l'extension des séquences d'échappement à la syntaxe du SGBD :

Format Description
{e <nombre>} Constante numérique. L'argument <nombre> doit être spécifié avec le séparateur décimal '.'.

Par exemple : {e 123.7} -> 123,7 sous MSAccess

{d <date>} Constante de date. L'argument <date> doit être spécifié au format 'aaaa-mm-jj'.

Par exemple : {d 2004-08-30} -> TO_DATE('2004-08-30', 'aaaa-mm-jj') sous Oracle.

{t <heure>} Constante d'heure. L'argument <heure> doit être spécifié au format 'hh24:mi:ss'.

Par exemple : {t 14:30:00} -> CONVERT(DATETIME, '14:30:00', 114) sous SQL Server

{dt <date & heure>} Constante de date et d'heure. L'argument <date & heure> doit être spécifié aux formats indiqués ci-dessus.
{l <booléen>} Constante booléenne. <booléen> prend la valeur False ou True. Si le SGBD supporte le type de données booléen, la séquence se développe en cette constante de type, sinon elle se développe en valeurs numériques 0 ou 1.
{s <chaîne>} Constante de chaîne. L'argument <chaîne> est une séquence de caractères délimitée ou non délimitée.

Par exemple : {s Company '1st Coding'} -> 'Company 1st Coding'


La séquence d'échappement de substitution d'identificateur permet l'abstraction des règles de délimitation d'identificateur spécifiques au SGBD. Pour de plus amples informations, voir "Noms d'objets". La syntaxe est la suivante :

Format Description
{id <nom d'identificateur>} Se développe en syntaxe de l'identificateur délimité propre au SGBD.

Par exemple : {id Order Details} -> “Order Details” sur Oracle.


La séquence des fonctions d'échappement permet l'abstraction d'un ensemble de fonctions intégrées propres au SGBD et de leur syntaxe. La syntaxe est la suivante :

Format Description
{fn <nom_fonction>(<arguments>)} La syntaxe des fonctions d'échappement et de l'ensemble est identique à celle des fonctions d'échappement ODBC. Dans les sous-rubriques, les fonctions d'échappement FireDAC sont énumérées.

Par exemple : SELECT * FROM MyTab WHERE Year = {fn YEAR({fn NOW()}} ou SELECT * FROM MyTab WHERE Year = {YEAR({NOW()}} -> SELECT * FROM MyTab WHERE Year = TO_NUMBER(TO_CHAR(SYSDATE, 'YYYY')) sous Oracle.

{<nom_fonction>(<arguments>)} Identique à l'exemple ci-dessus.


Substitution conditionnelle

Les séquences d'échappement de substitution conditionnelle permettent de changer du texte en commande, selon le SGBD auquel l'application est connectée ou la valeur de la variable de macro. En plus d'avoir des syntaxes différentes, ces constructions gèrent les paramètres et les macros de diverses façons. Les syntaxes de séquences d'échappement sont les suivantes :

Format Description
{iif (X1, Y1, …, XN, YN, YN+1) } Dans cet exemple, Xi représente selon le cas :
  • Un identificateur de SGBD. Si l'application est connectée à ce SGBD, le texte Yi est alors remplacé dans la commande.
  • Une variable de macro. Si sa valeur n'est pas vide, le texte Yi est remplacé dans la commande.

Si aucune de ces conditions n'est remplie et que le texte YN+1 est spécifié, ce texte est remplacé dans la commande. Les paramètres et les macros de Xi et de Yi sont créés dans les collections Params et Macros.

{if x} y {fi} Dans cet exemple, X représente selon le cas :
  • Un identificateur de SGBD. Si l'application est connectée à ce SGBD, le texte Y est alors remplacé dans la commande.
  • Une variable de macro. Si sa valeur n'est pas vide, le texte Y est remplacé dans la commande.

Les paramètres et les macros de Y sont créés dans les collections Params et Macros uniquement si X est défini sur True.


Les identificateurs de SGBD de FireDAC ne sont pas sensibles à la casse. Ils sont répertoriés dans le tableau suivant :

Identificateur SGBD

ADS

Advantage Database Server

ASA

Sybase SQL Anywhere

DB2

IBM DB2

FIREBIRD

Firebird

INFORMIX

Informix

INTRBASE

InterBase

MSACCESS
MSACC

Base de données Microsoft Access

MSSQL

Microsoft SQL Server

MYSQL

Serveur MySQL

ORACLE
ORA

Serveur Oracle

OTHER

Tout autre SGBD non énuméré dans le tableau.

POSTGRESQL
PG

Serveur PostgreSQL

SQLITE

Base de données SQLite

TDATA
TERADATA

Base de données Teradata


Par exemple : 

{iif (Oracle, TO_CHAR, MSSQL, CONVERT)}          -> ‘TO_CHAR’ on Oracle and ‘CONVERT’ on SQL Server.
{iif (&v1, Me, &v2, You, We)}                   -> ‘Me’ if &v1 has nonempty value, ‘you’ if &v2 has nonempty value, otherwise ‘We’.
{if Oracle} TO_CHAR {fi} {if MSSQL} CONVERT {fi} -> TO_CHAR on Oracle and CONVERT on SQL Server.
{if &v1} Me {fi} {if &v2} You {fi}              -> ‘Me’ if &v1 has nonempty value + ‘you’ if &v2 has nonempty value.

Notez que les fonctions d'échappement IF/IIF portent les mêmes noms. Pour distinguer une fonction d'une substitution conditionnelle, utilisez la syntaxe {fn IF(...)} ou {fn IIF(...)}.

Traitement des caractères spéciaux

Pour transmettre les caractères spéciaux - '!', '&', ':', '?', '{' ou '}' au SGBD, vous devez effectuer les opérations suivantes :

Sinon, les caractères '!', '&' et '{', '}' seront traités comme une commande macro et ':', '?', comme des marqueurs de paramètre, à l'exclusion des cas suivants, quand un constructeur est détecté par FireDAC et ne sera pas traité comme un marqueur de paramètre :

  • L'opérateur d'assignation PL/SQL Oracle.
  • Les paramètres EXECUTE BLOCK de Firebird contenus dans BEGIN … END.
  • Le libellé TSQL.
  • L'opérateur de transtypage '::' de PostgreSQL et Informix.
  • Le séparateur de catalogue ':' de Informix.

Voir aussi

Exemple

Récupérée de « https://docwiki.embarcadero.com/RADStudio/Tokyo/f/index.php?title=Prétraitement_du_texte_des_commandes_(FireDAC)&oldid=207482 »