FB_SqlDbRequest
Tâche
Le bloc fonction FB_SqlDbRequest est utilisé pour :
-
Etablir une connexion TCP permanente sécurisée ou non sécurisée à la SQL Gateway. Pour plus d'informations, consultez ST_ExtendedConnectionSettings.
-
Exécuter des requêtes SQL qui lisent des données de la base de données SQL. Les données sont renvoyées dans un tableau à double entrée dont la taille est définie par les paramètres globaux.
-
Exécuter des requêtes SQL qui mettent à jour ou modifient la base de données SQL. Les requêtes ne renvoient aucune donnée.
Description fonctionnelle
Une fois le bloc fonction activé (i_xEnable défini sur TRUE), une connexion TCP (sécurisée par TLS V1.2 ou non sécurisée) à la SQL Gateway est établie à l'aide des paramètres définis dans la variable iq_stExtendedConnSettings.
Dès que la connexion est établie, la sortie q_xReady est définie sur TRUE et le bloc fonction est en mesure d'envoyer des requêtes SQL à la SQL Gateway, laquelle les transfère à la base de données SQL configurée en utilisant le nom de connexion.
Après qu'un front montant a été détecté sur i_xExecute, le bloc fonction envoie la requête SQL à la SQL Gateway et traite la réponse.
Les messages d'état et les informations de diagnostic sont fournis à l'aide des sorties q_xError (TRUE si une erreur a été détectée), q_etResult et q_etResultMsg.
Les messages de diagnostic en cas d'échec d'exécution de commande peuvent être acquittés via la définition de l'entrée i_xErrorQuit sur TRUE. Le bloc fonction reste actif et la connexion TCP n'est pas fermée.
Au terme de l'échange de données avec la base de données SQL, désactivez le bloc fonction. Définissez i_xEnable sur FALSE pour fermer la connexion.
La prise en charge ou non d’une connexion utilisant le protocole TLS dépend du contrôleur sur lequel FB_SqlDbRequest est utilisé. Reportez-vous au manuel de votre contrôleur pour vérifier si la communication TCP via TLS est prise en charge.
Interface
|
Entrée |
Type de données |
Description |
|---|---|---|
|
i_xEnable |
BOOL |
Le bloc fonction établit une connexion avec le SQL Gateway sur un front montant de cette entrée. Si l'entrée est définie sur FALSE, le bloc fonction est réinitialisé et la connexion existante est fermée ou l'établissement de connexion est annulé. For more information, also refer to Behavior of Function Blocks with the Inputs i_xEnable and i_xExecute and i_xErrorQuit. |
|
i_xExecute |
BOOL |
Le bloc fonction exécute une requête SQL pour lire ou écrire des données dans la base de données SQL en cas de front montant sur cette entrée. For more information, also refer to Behavior of Function Blocks with the Inputs i_xEnable and i_xExecute and i_xErrorQuit. |
|
i_xErrorQuit |
BOOL |
Le bloc fonction acquitte une erreur détectée indiquée par q_xError sur un front montant de cette entrée. For more information, also refer to Behavior of Function Blocks with the Inputs i_xEnable and i_xExecute and i_xErrorQuit. |
|
i_etSqlRequest |
Définit le type de requête SQL (lecture ou écriture) à exécuter. Par défaut : ET_SqlRequest.Read |
|
|
i_refRequestWstring |
REFERENCE TO [RequestWstring] |
Référence aux données de la requête qui contiennent une seule demande SQL (de lecture ou d'écriture). Une requête SQL doit être divisée en plusieurs chaînes ne dépassant pas 200 caractères. Adaptez la taille des paramètres globaux Gc_uiMaxRequest et Gc_uiRequestWstringLength à la longueur des requêtes SQL que vous utilisez dans votre application.
NOTE : Pour concaténer des chaînes WSTRINGS, utilisez la fonction WCONCAT de la bibliothèque Standard64.
|
|
i_uiNumOfWstrings |
UINT |
Nombre de chaînes WSTRINGS requises qui contiennent la requête SQL divisée. Le nombre maximum est limité par le paramètre global Gc_uiMaxRequest. |
|
i_refUserData |
REFERENCE TO [UserData] |
Référence aux UserData qui doivent être disponibles sur le contrôleur pour stocker les données SQL lues dans la base de données. |
|
In_Out |
Type de données |
Description |
|---|---|---|
|
iq_stExtendedConnSettings |
ST_ExtendedConnectionSettings |
Contient les informations nécessaires pour la connexion à une SQL Gateway. |
|
Sortie |
Type de données |
Description |
|---|---|---|
|
q_xActive |
BOOL |
Indique que l'exécution du bloc fonction est active. Tant que cette sortie est TRUE, le bloc fonction doit être exécuté de façon cyclique. |
|
q_xReady |
BOOL |
Indique que l'initialisation a réussi et que la connexion TCP est établie. Cette sortie indique TRUE tant que le bloc fonction est capable d'accepter des entrées. |
|
q_xBusy |
BOOL |
Si cette sortie est TRUE, le bloc fonction est en cours d'exécution. |
|
q_xDone |
BOOL |
Si cette sortie est TRUE, l'exécution s'est effectuée correctement. |
|
q_xError |
BOOL |
Si cette sortie est TRUE, une erreur a été détectée. Pour plus d'informations, reportez-vous à q_etResult et q_etResultMsg. |
|
q_etResult |
ET_Result |
Fournit des informations de diagnostic et d'état. |
|
q_sResultMsg |
STRING[255] |
Fournit des informations supplémentaires de diagnostic et d'état. |
|
q_uiRetNumOfRows |
UINT |
Nombre de lignes dans les données renvoyées. Cette sortie est mise à jour avec le nombre d'enregistrements reçu de la base de données SQL.
NOTE : Valide uniquement après le succès d'une requête de lecture.
|
|
q_uiRetNumOfColumns |
UINT |
Nombre de colonnes dans les données renvoyées. Cette sortie est mise à jour avec le nombre d'enregistrements reçu de la base de données SQL.
NOTE : Valide uniquement après le succès d'une requête de lecture.
|
Pour plus d'informations, reportez-vous également à la section Entrées et sorties communes.
Définition d'un ARRAY de données utilisateur
Un tableau ARRAY à double entrée doit être disponible sur le contrôleur pour stocker temporairement les données SQL lues dans la base de données. Le tableau ARRAY à double entrée est défini dans l'ALIAS UserData.
La taille du tableau ARRAY peut être adaptée par les paramètres globaux Gc_uiMaxRows, Gc_uiMaxColumns et Gc_uiTableWstringLength.
Lorsque vous configurez ces paramètres, tenez compte du volume de données SQL que vous espérez recevoir. Avant le début du transfert, les données SQL sont segmentées en fonction de la taille de ce tampon.
Si les données SQL reçues dépassent la taille du tableau ARRAY, le transfert des données SQL s'interrompt et le bloc fonction signale une erreur.