DirectSQL

La fonction DirectSQL exécute une requête ou une instruction SQL sur la base de données spécifiée.

Vous ne pouvez utiliser la fonction DirectSQL qu'avec les types de données de base de données SQL.

Vous pouvez utiliser cette fonction pour effectuer des requêtes SELECT avec des clauses JOIN et pour réaliser d'autres opérations qui ne peuvent pas être accomplies via GetByKey, GetByFilter ou GetByLinks. Les lignes résultantes des requêtes SELECT sont renvoyées à la règle en tant qu'éléments de données. Cette fonction prend également en charge les instructions SQL telles que INSERT, UPDATE et DELETE.

Syntaxe

La fonction DirectSQL présente la syntaxe suivante :

[Array =] DirectSQL(DataSource, Query, CountOnly, ForceSelect )

Paramètres

La fonction DirectSQL possède les paramètres suivants.

Tableau 1. Paramètres de la fonction DirectSQL
Paramètre	Type	Description
`DataSource`	String	Nom de la source de données associée à la base de données SQL.
`Query`	String	Opération SQL à exécuter sur la base de données.
`CountOnly`	Booléen	Envoyez la valeur `false` pour ce paramètre. Uniquement pour la compatibilité ascendante.
`ForceSelect`	Booléen	Impose à la fonction `DirectSQL` d'exécuter la requête en tant qu'instruction `SELECT` même si celle-ci ne commence pas par un mot clé `SELECT`.

Valeur renvoyée

Pour les requêtes SELECT , la fonction DirectSQL renvoie un tableau d'éléments de données dans lequel chaque élément de données représente une ligne renvoyée par la requête SQL. Les zones des éléments de données ont une correspondance une-à-une avec les zones des lignes renvoyées.

Pour les autres instructions telles que INSERT, UPDATE ou DELETE, la fonction DirectSQL renvoie le nombre de lignes affectées ou 0 si l'instruction SQL n'a rien renvoyé.

Remarque: Si l'instruction UPDATE extrait des données de ligne SQL en même temps (à l'aide de mots clés tels que la clause PostgreSQL RETURNING ), vous pouvez forcer la fonction DirectSQL à renvoyer les données de ligne en définissant le paramètre ForceSelect sur true. L'expression doit renvoyer zéro ou plusieurs lignes, sinon la fonction risque d'être en attente de données.

Exemples

L'exemple suivant montre comment exécuter une opération SQL SELECT avec une clause JOIN sur une base de données.

// Call DirectSQL and pass the name of the data source and the
// SQL SELECT statement as input parameters
					
DataSource = "MYSQL_01";
Query = "SELECT * FROM Customer LEFT JOIN Server ON " + \
    "Customer.Location = Server.Location";
CountOnly = false;
					
MyCustomers = DirectSQL(DataSource, Query, CountOnly);

L'exemple suivant montre comment exécuter une opération SQL UPDATE sur une base de données.

// Call DirectSQL and pass the name of the data source and the
// SQL statement as input parameters

DataSource = "MYSQL_02";
Query = "UPDATE Customer SET Affected = true WHERE Location = 'New York'";
CountOnly = false;

DirectSQL(DataSource, Query, CountOnly);

L'exemple suivant montre comment exécuter une opération SQL DELETE sur une base de données.

// Call DirectSQL and pass the name of the data source and the
// SQL statement as input parameters

DataSource = "MYSQL_03";
Query = "DELETE FROM Customer WHERE Location = 'New York'";
CountOnly = false;
DirectSQL(DataSource, Query, CountOnly);
num_rows_deleted = Num;
Log("Number of deleted rows: " + num_rows_deleted);

Cette requête supprime les enregistrements indiqués et renvoie le nombre de lignes supprimées.

Mise en cache pour l'instruction SELECT

La fonction DirectSQL prend en charge la mise en cache lorsqu'elle est utilisée pour exécuter une instruction SELECT qui renvoie un ensemble de résultats depuis une base de données. La mise en cache est configurée séparément pour chaque source de données.

Pour activer la mise en cache, vous devez créer un fichier de propriétés DirectSQL. Ce fichier doit s'appeler servername_directsql.props, où servername est le nom du serveur Impact. Le fichier doit se trouver dans le répertoire $IMPACT_HOME/etc. Le tableau suivant montre les propriétés contenues dans ce fichier.

Vous devez remplacer la chaîne dans chaque propriété par le numéro de la source de données tel qu'il apparaît dans la liste des sources de données. La liste des sources de données est un fichier nommé servername_datasourcelist qui se trouve dans le répertoire $IMPACT_HOME/etc.

Tableau 2. Propriétés de la mise en cache DirectSQL
Propriété	Description
`impact.datasource.n.enablecaching`	Indique si la mise en cache est activée pour cette source de données. La valeur peut être true ou false.
`impact.datasource.n.cachesize`	Nombre maximal de lignes par requête à mettre en cache.
`impact.datasource.n.querycachesize`	Nombre maximal de requêtes à mettre en cache.
`impact.datasource.n.cacheinvalidation`	Durée (en secondes) après laquelle les éléments de données du cache sont considérés comme obsolètes et doivent faire l'objet d'une mise à jour à partir de la source de données.
`impact.datasource.n.querycacheinvalidation`	Durée (en secondes) après laquelle les requêtes du cache sont considérées comme obsolètes et doivent faire l'objet d'une mise à jour à partir de la source de données.

Remarque: Les valeurs définies pour impact.datasource.n.querycacheinvalidation et impact.datasource.n.cacheinvalidation doivent être égales.