Lien d'une variable à une requête Sql de lecture

Une variable peut être liée au résultat d'une requête Sql de lecture en choisissant la source Variables Sql. Voir la rubrique Généralités sur les Connexions de Données. Lorsqu'une variable est liée de cette façon, sa valeur en temps réel, et éventuellement son horodate et sa qualité, proviennent d'une base de données tierce telle que SQL Server de Microsoft. Les requêtes de lecture peuvent être configurées de façon à ce qu'elles soient interrogées périodiquement et/ou lors d'événements.

Une requête Sql de lecture renvoie une liste de lignes ou une valeur scalaire. Dans le cas d'une liste de lignes, vous devez pouvoir sélectionner la ou les ligne(s) et la ou les colonne(s) à mapper sur la variable et ses métadonnées. La configuration se déroule en trois étapes (ou quatre étapes si la requête contient des paramètres) chacune avec son propre onglet de configuration.

1. Sélection de données - Sélectionne la connexion Sql et sa requête Sql de lecture subordonnée.
2. Sélection de ligne - Sélection d'une ligne particulière ou de l'ensemble des lignes dans la table des résultats.
3. Mapping - Sélection dans la ligne du champ qui contient la valeur et, éventuellement, le champ qui contient l'horodate et le status de la variable.
4. Paramètres - Configuration de tous les paramètres que la requête contient. Les paramètres ajoutent de la flexibilité à une requête Sql en permettant à la valeur d'un ou plusieurs champs d'être fournie par la configuration de la variable liée.

Pour plus d'informations et des exemples, voir la rubrique Exemples de mapping de requête Sql de lecture à une variable.

Le mapping de variables à une requête Sql de lecture est soumis à des contraintes liées à la portée :

• La portée de la requête Sql de lecture et la portée de la variable mappée doivent correspondre,

• Lors de l'utilisation d'une variable pour définir la valeur d'un paramètre d'entrée, des contraintes liées à la portée s'appliquent pour éviter que des données spécifiques à un utilisateur ne soient utilisées comme entrées dans un contexte où le ou les résultats de la requête seront accessibles à d'autres utilisateurs.

Le tableau suivant résume la liste des combinaisons de portées valides :

Portée de la variable mappée	Portée de la requête Sql de lecture	Portée des variables utilisées pour définir les paramètres d'entrée
Local	Local	Local, Partagée
Partagée	Partagée	Local, Partagée
Session	Session	Local, Partagée, Session
Contexte client	Contexte client	Local, Partagée, Session, Contexte client

Configuration de la Sélection de données

1. Ouvrir la boîte de dialogue de configuration de la variable et sélectionnez l'onglet Source.
2. Sélectionnez Variables Sql comme Source. Variables Sql n'est disponible que si une ou plusieurs connexions Sql ont été configurées. Un nouvel onglet Lecture apparait pour la configuration de la sélection de données. Voir l'image
   
3. Sélectionnez la Connexion Sql et la Requête Sql subordonnée. L'apparence de l'onglet Source est maintenant modifiée pour afficher trois autres sous-onglets, Sélection de ligne, Mapping et Paramètres. Voir l'image
   
4. Même si la configuration n'est que partiellement terminée, il est possible de tester la requête à l'aide du bouton Exécuter. Si la requête nécessite des paramètres, vous êtes invité à les saisir. Les résultats de la requête sont affichés dans le champ de résultat. Le test de la requête Sql a l'avantage de permettre de découvrir les noms de champs renvoyés par la requête. Les noms de champs sont utilisés dans les autres onglets de configuration. Dans la capture d'écran suivante, le nom de champ qui a été découvert est BIT. Il est suivi, entre parenthèses, du type du champ. Voir l'image
   

Le bouton Traces est utilisé pour activer les informations de trace dans l'Observateur d'événements (F7) qui peuvent être utiles lors du débogage d'une requête particulière.

Configuration de la Sélection de ligne

La sélection de ligne peut être par Position, Valeur de champ ou Toutes les lignes. Voir l'image

• Par position - Généralement utilisé avec un format de table large où chaque variable de données apparaît dans une colonne distincte. Sélectionne une ligne par sa position réelle dans les résultats de la requête. Vous pouvez saisir une position (1 par défaut pour sélectionner la 1^ère ligne), ou bien sélectionner Dernière ligne pour sélectionner la dernière ligne retournée.
• Par valeur de champ - Généralement utilisé avec un format de table étroit où une colonne contient les valeurs et les autres colonnes les métadonnées. Sélectionne une ligne en fonction de la valeur d'une colonne particulière (recherche de type lookup). Si la requête de lecture Sql a été testée à l'aide du bouton Exécuter, les zones de liste Nom du champ et Valeur sont remplies avec les valeurs possibles. Le champ sélectionné doit être de type booléen, entier ou chaîne de caractères. Les types de données double, flottant, décimal, dates ou données structurées ne peuvent pas être utilisés.
• Toutes les lignes - Généralement utilisé avec un format de table large dans lequel la requête de lecture Sql a été configurée pour renvoyer plusieurs lignes de la même valeur. Sélectionne et traite toutes les lignes reçues.
• Filtre de sélection - Vous permet de définir une expression qui enlèvera les lignes retournées que vous souhaitez exclure. Si pour une ligne donnée, le résultat de l'expression est Vrai, la ligne est prise en compte. Si le résultat est Faux, la ligne est ignorée. Par exemple, si vous souhaitez exclure les lignes renvoyant la valeur Null dans la colonne appelée Temperature, vous pouvez ajouter le filtre de sélection suivant : =if(IsDbNull(FieldValue("Temperature")) == false, true, false)
• Lorsque la sélection de ligne est vide - Vous permet de contrôler la façon dont l'horodate, la valeur et la qualité de la variable sont mises à jour si la requête ne renvoie aucune ligne.
  • Si le paramètre Préserver l'état de la variable est activée, le VTQ de la variable est maintenu.
  • Si le paramètre est défini sur Définir la variable comme invalide, la qualité de la variable est positionnée à NS.
  • Si le paramètre Remplacer la valeur de la variable par est activée, la valeur de la variable est fixée à la valeur spécifique que vous avez saisie.

Configuration du mapping

L'onglet Mapping est utilisé pour mapper les champs contenant la valeur et éventuellement l'horodate de la variable et le status (qualité). Le mapping est réalisé avec une expression tirant parti de la fonction FieldValue () avec le nom de la colonne à considérer comme argument. L'expression est saisie à l'aide de la boîte de dialogue Éditeur d'expression. Voir la rubrique Utilisation de l'éditeur d'expression. Si la requête de lecture Sql a été testée à l'aide du bouton Exécuter, cliquer sur le bouton en haut à gauche de la boîte de dialogue affichera une liste des champs disponibles. Voir l'image

L'expression doit contenir la fonction FieldValue(), qui sélectionne le champ. Elle peut également contenir d'autres éléments d'expression en cas de besoin de manipulation de la valeur avant qu'elle ne soit utilisée pour mettre à jour la valeur (respectivement l'horodate ou la qualité) de la variable.

Le mapping du statut (qualité) de la variable peut être réalisé en utilisant l'une des constantes suivantes :

• VAR_QUALITY_GOOD - Pour définir le status de la variable comme valide
• VAR_QUALITY_NS - Pour définir le status de la variable comme invalide
• VAR_QUALITY_NSCOM - Pour définir le status de la variable comme invalide en raison d'une erreur de communication

Si la propriété de variable Timestamp n'est pas mappée à un champ du résultat de la requête, elle sera définie par PcVue et gérée en conséquence. Il en va de même pour la propriété Quality.

• Préserver l'état de la variable sur erreur - Si activé, la VTQ de la variable sera maintenu si le mapping ne peut pas être effectué. Par exemple, si un champ attendu est manquant dans les lignes retournées, si une erreur de conversion de type de données se produit ou si la requête échoue. Si non activée, la variable est invalide dans une telle situation.

Configuration des paramètres

Si un ou plusieurs paramètres sont trouvés dans la requête Sql de lecture, ils sont répertoriés dans l'onglet Paramètres et doivent être remplacés à l'aide d'une expression. Un paramètre ne peut être remplacé qu'une seule fois. Si la requête Sql de lecture est ensuite utilisée dans une autre variable, la substitution de paramètres est préconfigurée et le champ est grisé indiquant qu'il est en lecture seule.

Un paramètre défini par une expression peut référencer une propriété de la variable (domaine, attribut étendu, etc.) et utiliser les fonctions et opérateurs du moteur d'expression. Le bouton en haut à gauche de la boîte de dialogue de l'éditeur d'expression affiche une liste des propriétés des variables pouvant être substituées. Voir l'image

Les paramètres ne peuvent être définis qu'une seule fois - la première variable dans laquelle une requête de lecture est utilisée définira la valeur du paramètre.

Par exemple, Register01 a le domaine Security. Register01 utilise une requête de lecture contenant ?Param01 configuré pour utiliser le domaine. Quel que soit le domaine de Register02, Security sera utilisée comme valeur pour ?Param01. Register02 utilise la même requête de lecture. Quel que soit le domaine de Register02, Security sera utilisée comme valeur pour ?Param01.

Un paramètre est mappé avec une indirection sur un attribut étendu texte afin qu'il soit défini avec une valeur de variable, l'adéquation de la portée de la variable par rapport à la portée de la requête Sql n'est vérifiée qu'au moment de l'exécution. Elle n'est pas vérifiée au moment de la configuration, ni au démarrage.

Fonctions d'expressions exclusivement pour le mapping de variables de requête Sql

Fonction et syntaxe	Opération
FieldValue(QueryResultFieldName)	Renvoie la valeur du champ QueryResultFieldName qui fait parti du résultat d'une requête Sql de lecture. Le format de la valeur retournée est le même que celui du champ. Exemple : FieldValue("Temperature")
IsDbNull	Fonction pour évaluer une valeur de champ retournée par rapport à NULL.
Row_Num	Retourne le numéro de la ligne dans le jeu de données retourné par la requête.

Fonctions exclusivement pour les paramètres de substitution de requête Sql

Les fonctions suivantes renvoient toutes une propriété particulière de la variable concernée.

Fonction et syntaxe	Propriété de la variable
AlarmLevel	Niveau d'alarme. Type VT_I2. Exemple : 1
AssocLabel	La valeur de l'état spécifique de l'attribut binaire étendu. Type VT_BOOL. Exemple : "Running"
BinAttr	Attribut binaire étendu complet. Type VT_UI4. Exemple : 128
BinAttrXX (de 1 à 30)	La valeur de l'état spécifique de l'attribut binaire étendu. Type VT_BOOL. Exemple : BinAttr01 > 0
Description	Description. Type VT_BSTR. Exemple : "Room 101 measured temperature"
Domain	Domaine. Type VT_BSTR. Exemple : "BUILDING01"
Name	Nom. Type VT_BSTR. Exemple : "Building01.Floor01.Room01.Temperature"
Nature	Nature. Type VT_BSTR. Exemple : "HEATING"
Quality	La qualité. Type VT_UI2. Exemple : 192
TextAttrXX (03 à 16)	Attribut de texte étendu 03 à 16. Type VT_BSTR. Exemple 1 : TextAttr05 > "Building01.Floor01.Room01.Temperature" Exemple 2 : TextAttr06 > "Help.PDF"
TextIndAttrXX (03 à 16)	Attribut de texte étendu différé 03 à 16. Type VT_BSTR. Exemple : "21.75"
TS	Horodate. Type VT_R8. Exemple : 43895.647743055553
Units	Unités. Type VT_BSTR. Exemple : "Deg °C"
UserName	Nom de l'utilisateur. Type VT_BSTR.
Value	Valeur. Le type est soit VT_BSTR (variable texte) soit VT_R8 (variable mesure ou état). Exemple : 21.75

Traces

Le bouton Traces permet d'activer les messages de trace 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).

• Trace 1: Tous les drivers - Général - Active des traces générales relatives à l'activité entre le Gestionnaire de Variables et le driver Variables Sql.
• Trace 2: Tous les drivers - Détails - Active des traces détaillées relatives à l'activité entre le Gestionnaire de Variables et le driver Variables Sql.
• Trace 3: Tous les drivers - Performances - Active des traces relatives aux performances du driver Variables Sql.
• Trace 4: Sql variable driver - Performances - Active des traces relatives aux performances du traitement des résultats des requêtes Sql.