Configuration des requêtes Sql

Les connexions de données permettent de créer des requêtes Sql de lecture et d'écriture. En général, une requête Sql de lecture tire parti d'instructions telles que SELECT et renvoie les lignes d'une table, et une requête Sql d'écriture, de type non-query, tire parti d'instructions telles que INSERT, UPDATE ou DELETE qui effectuent une action sur la base de données et affecte éventuellement des lignes.

Création d'une nouvelle requête et configuration des propriétés générales

1. Allez dans la configuration, puis sélectionnez l'Application Explorer et dépliez l'arborescence de configuration afin de sélectionner une connexion Sql existante dans le dossier Connexions de données.

2. Cliquez sur le bouton Ajouter une requête Sql dans la barre d'outils et choisissez si vous voulez ajouter une requête de lecture ou d'écriture. Voir l'image

   

3. Saisissez un nom de requête et une description (optionnelle). Le nom est utilisé comme Id de la requête dans toute l'application.

4. Si vous prévoyez d'utiliser cette requête Sql avec le contrôle grid Sql, sélectionnez Interface utilisateur dans le menu déroulant Type de consommateur. Seules les requêtes en lecture disposent de cette option.
   Si vous prévoyez d'utiliser la requête Sql avec le driver variables Sql, sélectionnez Variables Sql dans la liste déroulante type de consommateur.

   Une fois que vous avez sélectionné Interface utilisateur dans le type de consommateur, il ne vous reste plus qu'à configurer les onglets Paramètres et Traces. L'onglet Paramètres n'apparaît que si vous avez saisi un paramètre dans le champ Requête.

5. Sélectionnez la portée de la requête Sql. La portée est utilisée pour contrôler la distribution des résultats de la requête Sql entre les sessions utilisateur. La portée n'est pas disponible pour le type de consommateur Interface utilisateur.

   La portée des variables suivantes doit correspondre à la portée de la requête : Variable état d'inhibition, variable état de déclenchement, variable status d'exécution et variable erreur d'exécution.

   Pour plus d'informations sur la propriété Portée, reportez-vous à la rubrique Lien d'une variable à une requête Sql de lecture et Éléments de configuration affectés par la portée.

6. (Pour une requête Sql de lecture) Sélectionnez le type de données à retourner par la commande Sql :

   • Lecture de lignes : Utilisé lorsque la requête est conçue pour renvoyer un ensemble de lignes contenant un ou plusieurs champs.

   • Lecture d'un scalaire : Utilisé lorsque la requête est conçue pour renvoyer une valeur scalaire unique.

   La propriété Type n'est pas disponible pour le type de consommateur Interface utilisateur, seule la lecture des lignes est intéressante.

7. Saisissez une requête. La requête doit respecter la syntaxe Sql telle que supportée par la source de données sous-jacente et le fournisseur ADO.Net. Bien que l'éditeur de requêtes mette en évidence les mots clés, il n'y a pas de saisie semi-automatique. La longueur maximale est de 10 000 caractères.

   Nous vous recommandons d'utiliser des outils fournis avec votre source de données pour concevoir et tester vos requêtes, par exemple un éditeur de requête ou un profileur de performance des requêtes. Ils vous aideront à les ajuster avant de les configurer dans l'Application Explorer. En général, les requêtes Sql mal conçues affectent négativement les performances et la disponibilité du système, et en particulier le temps qu'il faut à la source externe pour les traiter.

   • Utilisez le bouton Ajouter un paramètre de substitution pour ajouter un paramètre à la requête.

   • Utilisez le bouton Ajouter un snippet pour insérer un snippet de requête Sql prédéfini. La disponibilité des snippets de requête dépend de la source de données et du fournisseur de données sélectionnés lors de la configuration de la connexion de données. Les snippets de requête sont disponibles pour Sql server, Sql pour Oracle et certains fournisseurs intégrés.

     L'activation des snippets de requête nécessite de placer manuellement un fichier XML dans un dossier nommé DataProviders au même niveau que le dossier Bin du logiciel PcVue. Vous pouvez modifier ce fichier pour ajouter ou personnaliser des snippets. Contactez votre revendeur local pour obtenir les fichiers snippet de requête.

   • Utilisez le bouton de l'assistant de requête Open Sql pour faciliter la configuration des requêtes Sql. Cet assistant n'est disponible que pour les sources de données Sql Server et Oracle. Il est utile pour créer une nouvelle requête à partir de zéro et ne peut pas être utilisé pour modifier une requête existante.

     Pour que l'assistant de requête fonctionne, vous devez être connecté à une instance de Sql Server ou à un serveur de base de données Oracle avec des tables.

     • (Pour une requête Sql de lecture) Choisissez une table dans le menu déroulant et utilisez les icônes de contrôle à droite de la table pour sélectionner et trier les données. Le bouton Ajouter une colonne calculée vous permet d'ajouter une colonne calculée basée sur les colonnes des tables.

     • (Pour une requête Sql de lecture) Cliquez sur Suivant, sélectionnez les composants de votre requête Sql en utilisant les champs déroulants de la table pour filtrer les données à renvoyer (clause Where). Vous pouvez également sélectionner le nombre maximal de lignes à renvoyer et indiquer si les lignes renvoyées doivent être distinctes ou non. Voir l'image

       

     • (Pour une requête Sql de lecture) Cliquez sur Suivant, triez et regroupez les jeux de données résultat à l'aide des flèches situées à droite des tables, puis cliquez sur Terminer.

     • (Pour une requête d'écriture Sql) Indiquez si la requête Sql est conçue pour insérer, mettre à jour ou supprimer des lignes. Cliquez sur Suivant.

     • (Pour une requête Sql d'écriture) Sélectionnez dans la liste déroulante, la table à modifier et en fonction de l'action sélectionnée dans le dialogue précédent, vous pouvez :

       • Insérer des données en sélectionnant des noms de colonnes et en saisissant des valeurs pour les colonnes sélectionnées.

       • Supprimer des données en filtrant la table sélectionnée pour identifier les lignes à supprimer.

       • Mettre à jour les valeurs des données en sélectionnant les colonnes et en saisissant ou en remplaçant une valeur. Les valeurs peuvent être définies comme nulles ou remplacées par un paramètre.

   Dans le cadre de l'édition des requêtes pour certains fournisseurs intégrés, vous avez la possibilité d'insérer des émojis. Contactez votre revendeur local pour obtenir le programme d'installation de ces fournisseurs intégrés.

8. (Facultatif) Cliquez sur Test. La boîte de dialogue Test d'une requête Sql s'affiche. La boîte de dialogue Test permet de saisir des valeurs pour tous les paramètres et affiche à la fois le résultat de la requête et des informations utiles sur le status de son exécution.

Configuration des paramètres de requête

La configuration des paramètres permet à la valeur d'un ou plusieurs champs de la requête d'être fournie par le contexte d'exécution de la requête (par exemple le mapping de variable).

1. Allez dans la configuration, puis sélectionnez l'Application Explorer et dépliez l'arborescence de configuration afin de sélectionner une connexion Sql existante dans le dossier Connexions de données.

2. Sélectionnez et ouvrez la requête Sql puis cliquez sur l'onglet Paramètres de la boîte de dialogue de création de requête Sql. Ici, vous pouvez configurer les paramètres ajoutés dans l'onglet Général. Vous pouvez saisir une description ainsi que définir les propriétés suivantes : Voir l'image

   

   • Longueur de chaîne max - Le nombre maximum de caractères entre 1 et 2048. La valeur par défaut est 132.

   • De type numérique - Si coché, le paramètre est vérifié pour s'assurer que son contenu correspond à une valeur numérique.

   • Bloquer si séquences d'échappement - Si coché, une valeur de paramètre contenant une chaîne d'échappement sera bloquée et la requête ne sera pas exécutée, par exemple si la valeur de paramètre contient : \0, 1F, 7F, des guillemets simples ou doubles. Si pas coché, la valeur du paramètre n'est pas vérifiée, il peut contenir une chaîne d'échappement et ainsi être plus susceptible aux risques d'injection Sql.

   • Utilise la valeur par défaut - Si coché, la Valeur par défaut est utilisée si la valeur du paramètre ne peut pas être résolue.

   • Valeur par défaut - Une valeur, une expression ou une chaîne vide.

Configuration des propriétés d'exécution

1. Allez dans la configuration, puis sélectionnez l'Application Explorer et dépliez l'arborescence de configuration afin de sélectionner une connexion Sql existante dans le dossier Connexions de données.

2. Sélectionnez et ouvrez la requête Sql puis cliquez sur l'onglet Exécution de la boîte de dialogue de création de requête Sql. Ici vous pouvez configurer quand une requête est exécutée. Une requête peut être exécutée de manière cyclique, sur événement et/ou à la suite de l'exécution d'une autre requête. Vous pouvez configurer les propriétés suivantes pour affiner l'exécution de la requête : Voir l'image

   

   • Cyclique - La période est configurable de 10 secondes à 1 heure. Il n'y a pas de synchronisation. Par exemple, si vous configurez la période à 0:10:00 (10 minutes) et que le démarrage de l'application est à 12:05:15, la première exécution aura lieu au démarrage, la suivante à 12:15:15, 12:25:15, etc.

   • Bit de déclenchement - Nom d'une variable état dont une transition de la valeur doit déclencher l'exécution.

   • Sur requête terminée - Si coché, la requête est exécutée à la fin de la requête que vous sélectionnez ici. La condition sur laquelle la requête est déclenchée dépend du status d'exécution de la requête sélectionnée. Par exemple, vous pouvez exécuter une requête lorsque la requête sélectionnée s'est exécutée avec succès en ne renvoyant aucune ligne, ou si elle a échoué. La matrice suivante indique si la requête sera exécutée en fonction de la configuration et des résultats de la première requête. La sélection peut être combinée, par exemple pour exécuter la requête si aucune ligne n'est retournée et aussi si la requête a échoué :

     	Requête exécutée avec succès Au moins 1 ligne retournée	Requête exécutée avec succès 0 ligne retournée	L'exécution de la requête a échoué
     (Pour les requêtes Sql de lecture uniquement) Si Avec données est sélectionné (Pour les requêtes Sql en écriture uniquement) Si Avec données affectées est sélectionné	La requête est exécutée
     (Pour les requêtes Sql de lecture uniquement) Si Sans donnée est sélectionné (Pour les requêtes Sql en écriture uniquement) Si Sans donnée affectée est sélectionné		La requête est exécutée
     Si Echec est sélectionné			La requête est exécutée

     • Autoriser l'exécution de boucle - Si coché, autorise l'enchaînement de requêtes qui peuvent potentiellement conduire à une boucle infinie. Ne dois pas être sélectionné si vous ne contrôlez pas précisément l'enchaînement des requêtes. Mais par exemple, c'est nécessaire si vous configurez la requête à appeler à la fin d'une requête qui est elle-même enchaînée lors de l'exécution de la requête que vous configurez.

   • Autoriser le déclenchement par script - Autorise le déclenchement de la requête en utilisant l'instruction SCADA Basic SQL_QUERY.

   • (Uniquement pour les requêtes Sql d'écriture) Autoriser le déclenchement par changement de variable : Autorise le déclenchement de la requête sur changement d'une variable mappée. Selon le mapping de la variable, la requête peut être déclenchée sur commande de la variable ou sur un changement de valeur ou les deux.

   • (Pour les requêtes Sql de lecture uniquement) Exécution répétée - La requête Sql peut être configurée d'une manière telle que son exécution sera répétée si le nombre de lignes reçues dépasse un maximum que vous définissez. C'est utile si votre requête est conçue pour récupérer un certain nombre de lignes en mode nominal (avec une clause Select TOP par exemple). Cependant, dans certains cas rares, comme un redémarrage après une longue période de temps ou une avalanche de nouvelles lignes, vous devez répéter la requête jusqu'à ce que toutes les lignes stockées pendant l'arrêt soient récupérées.

     • Répéter la requête - Cochez pour activer l'exécution répétée. Elle peut être utilisée pour des requêtes cycliques et des requêtes exécutées sur un Bit de déclenchement.

     • Nb max de lignes reçues - Le seuil en nombre de lignes reçues, qui déclenchera la réitération de l'exécution. L'exécution peut être répétée plus d'une fois si le nombre de lignes reçues est toujours supérieur ou égal à la valeur définie.

   • Bit d'inhibition - Nom d'une variable état qui peut être utilisée pour empêcher l'exécution.

Configuration des propriétés avancées

1. Allez dans la configuration, puis sélectionnez l'Application Explorer et dépliez l'arborescence de configuration afin de sélectionner une connexion Sql existante dans le dossier Connexions de données.

2. Sélectionnez la requête Sql puis cliquez sur l'onglet Avancé. Ici, vous pouvez sélectionner les variables qui fourniront des informations sur le status de la requête, et les propriétés de la file d'attente si le déclenchement par script est activé dans l'onglet Exécution. Vous pouvez configurer les propriétés suivantes : Voir l'image

   

   • Status d'exécution - Les status qui peuvent être fournis sont :

     • 0 = Succès.

     • 1 = En cours d'exécution.

     • 2 = Échec.

     • 3 = Annulé.

   • Erreur d'exécution - Variable texte fournissant des informations supplémentaires lorsque la variable status indique un échec. Dans la plupart des cas, le texte décrivant l'erreur vient directement du fournisseur ADO.NET.

   • Nombre de lignes affectées - Variable mesure fournissant le nombre de lignes renvoyées par la dernière exécution de la requête. Positionnée à 0 si la requête a échoué.

Activation des traces

1. Allez dans la configuration, puis sélectionnez l'Application Explorer et dépliez l'arborescence de configuration afin de sélectionner une connexion Sql existante dans le dossier Connexions de données.

2. Sélectionnez une requête Sql puis cliquez sur l'onglet Traces. Ici vous pouvez activer les messages de traces de diagnostic. Chaque trace génère des messages spécifiques qui sont enregistrés dans les fichiers de trace et affichés dans la boîte de dialogue Observateur d'événements (F7). Voir l'image

   

Voici quelques-unes des traces que vous pouvez activer :

• Trace 1 : Général - Active des traces générales relatives à la gestion de la requête.

• Trace 2 : Configuration - Active des traces relatives à la gestion de la configuration de la requête.

• Trace 3 : Runtime (Driver variables Sql - Général) - Active des traces générales relatives à l'activité du driver Variables Sql pour la requête.

• Trace 4 : Runtime (Driver variables Sql - Déclenchements) - Active des traces relatives à la gestion des déclenchements de cette requête pour le driver Variable Sql.

• Trace 5 : Runtime (Driver variables Sql - Requêtes) - Active des traces relatives à la gestion de la requête pour le driver Variable Sql.

• Trace 6 : Runtime (Driver variables Sql - Requêtes avec détails) - Active des traces détaillées relatives à la gestion de la requête pour le driver Variable Sql, notamment la substitution des paramètres et l'extraction des valeurs.

• Trace 7 : Runtime (Driver variables Sql - Mapping) - Active des traces relatives à la résolution du mapping de la requête pour le driver Variable Sql.

• Trace 8 : Runtime (Driver variables Sql - Performances) - Active des traces relatives aux performances de la requête pour le driver Variable Sql.