SQL_COMMAND
Voir égalementEnvoie des commandes Sql à l'aide d'une connexion Sql préconfigurée.
Support WebVue - Oui.
L'utilisation de connexions Sql préconfigurées avec les instructions SQL_CONNECTION, SQL_COMMAND et SQL_QUERY sont préférables à l'utilisation du verbe SVSQL (basé sur ODBC).
Les connexions Sql préconfiguré sont configurées dans l'Application Explorer. Consultez le chapitre Data Connections pour plus d'informations.
Certains des modes sont asynchrones. Le développeur de l'application doit s'assurer que la valeur de la variable de status est surveillée et prendre des mesures adéquates lorsqu'elle change.
Ce verbe peut être exécuté localement sur le poste de production de la connexion Sql ou à partir de n'importe quel poste client du producteur. Dans ce dernier cas, les commandes et les données renvoyées sont acheminées de manière transparente à travers le système de messagerie multi-postes. Plusieurs connexions à la même source de données ne sont autorisées que si vous utilisez différentes Connexions Sql. Les connexions multiples en utilisant la même Connexion Sql seront refusées, cependant, il est possible d'envoyer plusieurs requêtes simultanément en utilisant la même Connexion Sql.
Les connexions, et les données qui leur sont associées, sont gérées dans le contexte des sessions utilisateurs. Une connexion ne doit être utilisée que dans le contexte de la session qui l'a initiée à l'origine ; et tous les objets correspondants doivent être libérés/fermés correctement avant que la session ne se termine. Par exemple, il n'est pas possible d'initier une connexion au démarrage et d'avoir des requêtes qui s'exécutent ultérieurement dans des sessions utilisateurs.
| Mode | Mnémonique | Syntaxe |
| 1 | INITCONNECTION | 1 |
| 2 | CLOSECONNECTION | 2 |
| 3 | GETCONNECTIONLIST | 3 |
| 4 | GETCONNECTIONINFO | 4 |
| 5 | EXECREADER | 5 |
| 6 | EXECSCALAR | 6 |
| 7 | EXECNONQUERY | 7 |
| 8 | GETCOMMANDLIST | 8 |
| 9 | GETCOMMANDINFO | 9 |
| 10 | READBUFFER | 14 |
| 11 | SEEKBUFFER | 10 |
| 12 | READBUFFERLINE | 11 |
| 13 | READBUFFERCELL | 12 |
| 14 | BUFFERLINECOUNT | 13 |
| 15 | BUFFERFIELDCOUNT | 13 |
| 16 | BUFFERFIELDNAME | 14 |
| 17 | BUFFERFIELDTYPE | 14 |
| 18 | BUFFERSIZE | 13 |
| 19 | READSCALARVALUE | 14 |
| 20 | READAFFECTEDROW | 13 |
| 21 | CANCEL | 13 |
| 22 | DISPOSE | 13 |
Arguments communs à plus d'un mode
|
Argument |
Définition |
| SqlConnectionName | Nom de la Connexion Sql tel que configurée dans Général.Connexions de données de l'Application Explorer. Type STR |
| BufferHandle | Handle d'un buffer retourné par ALLOC_BUFFER. Type LONG. Tous les modes nécessitent que le buffer soit alloué avant d'appeler l'instruction. |
| SqlCmd | Commande Sql à envoyer. Type STR |
| StatusVariable |
Nom de la variable mesure utilisée pour surveiller le status d'une opération asynchrone. Type STR. Terminé avec succès = 0 |
| ErrortextVariable | Nom d'une variable texte utilisée pour retourner une information supplémentaire lorsque la valeur de la variable de status est positionnée à Echec (2). Type STR. |
| SubstituteNullValueWithEmptyString |
Substitue une valeur nulle par une chaîne vide dans les données retournées. Type INTEGER 0 - Une valeur nulle est représentée par <NULL> |
| LineNumber |
La position d'une ligne dans le buffer de résultat (la première ligne est la LineNumber 0). Type LONG. |
| CmdId | L'Id de la commande retourné par les modes EXECREADER, EXECSCALAR ou EXECNONQUERY. Type INTEGER |
Syntaxe 1
IntVal = SQL_COMMAND(Mode, SqlConnectionName [, MaxSimultaneousCommand]);
Type de retour: INTEGER
|
Argument |
Définition |
| MaxSimultaneousCommand |
Nombre maximum de commandes asynchrones simultanées. Type STR. L'utilisation principale est de limiter la mémoire utilisée par PcVue pour le buffer de réponse. La valeur par défaut est 1. La valeur maximale est 100. Si la valeur est incorrecte, la valeur par défaut est utilisée à la place. |
Exécution
|
Mode |
Mnémonique |
Action |
| 1 | INITCONNECTION |
Initialise l'objet runtime nécessaire à la gestion de la connexion Sql spécifiée. Cela ne provoque pas de connexion de bout en bout avec le SGBD. La connexion Sql doit être démarrée avant d'utiliser ce mode. Retour : 0 si OK, sinon un nombre négatif indique une des erreurs suivantes : Voir le tableau ci-dessous pour les valeurs de retour. |
Les connexions multiples en utilisant la même Connexion Sql seront refusées. Plusieurs connexions à la même source de données ne sont autorisées que si vous utilisez différentes Connexions Sql.
Syntaxe 2
IntVal = SQL_COMMAND(Mode[, SqlConnectionName]);
Type de retour : INTEGER
Exécution
|
Mode |
Mnémonique |
Action |
| 2 | CLOSECONNECTION |
Libère les ressources associées à l'objet runtime correspondant à la connexion Sql spécifiée. Si l'argument SqlConnectionName est omis, toutes les connexions ouvertes seront fermées. Retour : 0 si OK, sinon un nombre négatif indique une des erreurs suivantes : Voir le tableau ci-dessous pour les valeurs de retour. |
Syntaxe 3
IntVal = SQL_COMMAND(Mode, BufferHandle);
Type de retour: INTEGER
Exécution
|
Mode |
Mnémonique |
Action |
| 3 | GETCONNECTIONLIST |
Récupère le nom de toutes les connexions Sql ouvertes et les renvoie dans un buffer. Les noms de connexion sont délimités par le caractère virgule. Retour : 0 si OK, sinon un nombre négatif indique une des erreurs suivantes : Voir le tableau ci-dessous pour les valeurs de retour. |
Syntaxe 4
IntVal = SQL_COMMAND(Mode, ConnectionParam, SqlConnectionName, BufferHandle);
Type de retour: INTEGER
|
Argument |
Définition |
| ConnectionParam |
Sous-mode. Type INTEGER ou STR. 1 ou "NB_COMMAND" Retourne le nombre de commandes actives, c'est-à-dire celles qui n'ont pas encore été libérées en utilisant le mode DISPOSE. |
Exécution
|
Mode |
Mnémonique |
Action |
| 4 | GETCONNECTIONINFO |
Retourne des informations au sujet du nombre de commandes. Retour : 0 si OK, sinon un nombre négatif indique une des erreurs suivantes : Voir le tableau ci-dessous pour les valeurs de retour. |
Syntaxe 5
IntVal = SQL_COMMAND(Mode, SqlConnectionName, SqlCmd, StatusVariable, ErrorTextVariable, LineSeparator, FieldSeparator [, SubstituteNullValueWithEmptyString]);
Type de retour : INTEGER
|
Argument |
Définition |
| LineSeparator | Caractère séparateur de lignes à utiliser dans le buffer. Type STR. |
| FieldSeparator | Caractère séparateur de champs à utiliser dans le buffer. Type STR. |
Exécution
|
Mode |
Mnémonique |
Action |
| 5 | EXECREADER |
Exécute une requête Sql conçue pour retourner un ensemble d'enregistrements et stocker le résultat dans un buffer. Le contenu est structuré en fonction des séparateurs de lignes et de champs passés en paramètres. Retour : Soit une valeur positive représentant l'Id de la commande, soit une valeur négative indiquant une des erreurs suivantes : Voir le tableau ci-dessous pour les valeurs de retour. |
Ce mode est asynchrone. Le programme doit surveiller la valeur de la variable de status et utiliser les modes READBUFFER, READBUFFERLINE ou READBUFFERCELL pour traiter le buffer.
Syntaxe 6
IntVal = SQL_COMMAND(Mode, SqlConnectionName, SqlCmd, StatusVariable, ErrorTextVariable [, SubstituteNullValueWithEmptyString]);
Type de retour: INTEGER
Exécution
|
Mode |
Mnémonique |
Action |
| 6 | EXECSCALAR |
Exécute une requête Sql conçue pour retourner une valeur scalaire et enregistrer le résultat dans un buffer. Le résultat est une valeur unique. Retour : Soit une valeur positive représentant l'Id de la commande, soit une valeur négative indiquant une des erreurs suivantes : Voir le tableau ci-dessous pour les valeurs de retour. |
Ce mode est asynchrone. Le programme doit surveiller la valeur de la variable de status et utiliser le mode READSCALAR pour obtenir la valeur.
Syntaxe 7
IntVal = SQL_COMMAND(Mode, SqlConnectionName, SqlCmd, StatusVariable, ErrorTextVariable);
Type de retour: INTEGER
Exécution
|
Mode |
Mnémonique |
Action |
| 7 | EXECNONQUERY |
Exécute une requête Sql qui ne nécessite pas que des données soient renvoyées à partir de la base de données, mais provoque l'exécution d'une certaine opération du côté de la source de données (tel que défini par l'argument SqlCmd). De telles requêtes renvoient généralement le résultat de l'exécution de l'opération. Retour : Soit une valeur positive représentant l'Id de la commande, soit une valeur négative indiquant une des erreurs suivantes : Voir le tableau ci-dessous pour les valeurs de retour. |
Ce mode est asynchrone. Le programme doit surveiller la valeur de la variable de status et utiliser le mode READAFFECTEDROW pour obtenir le nombre de lignes affectées par la commande.
Syntaxe 8
IntVal = SQL_COMMAND(Mode, SqlConnectionName, BufferHandle);
Type de retour : INTEGER
Exécution
|
Mode |
Mnémonique |
Action |
| 8 | GETCOMMANDLIST |
Récupère la liste de commandes associées à une connexion. Les Ids des commandes sont renvoyés dans le buffer séparés par des virgules. Retour : Soit une valeur positive représentant le nombre de commandes actives, soit une valeur négative indiquant une des erreurs suivantes : SQLCONNAME_PARAM_NOT_STR_OR_NOT_READ Voir le tableau ci-dessous pour les valeurs de retour. |
Syntaxe 9
IntVal = SQL_COMMAND(Mode, RequestParam, CmdId, BufferHandle);
Type de retour : INTEGER
|
Argument |
Définition |
| RequestParam |
Sous-mode. Type INTEGER ou STR. 1 ou "TYPE". |
Exécution
|
Mode |
Mnémonique |
Action |
| 9 | GETCOMMANDINFO |
Récupére des informations, dans un buffer, à propos d'une commande spécifiée par son CmdId. Les informations renvoyées dépendent du sous-mode. TYPE - Récupère le type de commande envoyée. Retour : 0 si OK, sinon un nombre négatif indique une des erreurs suivantes Voir le tableau ci-dessous pour les valeurs de retour. |
Syntaxe 10
IntVal = SQL_COMMAND(Mode, CmdId, LineNumber);
Type de retour : INTEGER
Exécution
|
Mode |
Mnémonique |
Action |
| 11 | SEEKBUFFER |
Lit une ligne spécifique dans le buffer, à la suite d'un appel au mode EXECREADER, une fois que la variable de status est passée à 0. La première ligne est LineNumber 0. Retour : 0 si OK, sinon un nombre négatif indique une des erreurs suivantes : Voir le tableau ci-dessous pour les valeurs de retour. |
Syntaxe 11
IntVal = SQL_COMMAND(Mode, CmdId, BufferHandle, LineNumber);
Type de retour : INTEGER
Exécution
|
Mode |
Mnémonique |
Action |
| 12 | READBUFFERLINE |
Lit une ligne spécifique dans le buffer, à la suite d'un appel au mode EXECREADER, une fois que la variable de status est passée à 0. La première ligne est LineNumber 0. Retour : Soit une valeur positive représentant le nombre de lignes lues, soit une valeur négative représentant l'une des erreurs suivantes : Voir le tableau ci-dessous pour les valeurs de retour. |
Syntaxe 12
IntVal = SQL_COMMAND(Mode, CmdId, BufferHandle, LineNumber, FieldNumber);
Type de retour: INTEGER
|
Argument |
Définition |
| FieldNumber |
Position d'un champ dans une ligne du buffer de résultat (le premier champ est FieldNumber 0). Type LONG. |
| LineNumber | La position d'une ligne dans le buffer de résultat. (la première ligne est la LineNumber 0). Type LONG. |
Exécution
|
Mode |
Mnémonique |
Action |
| 13 | READBUFFERCELL |
Lit un champ spécifique dans une ligne spécifique du buffer, à la suite d'un appel au mode EXECREADER, une fois que la variable de status est passée à 0. Retour : Soit une valeur positive représentant le nombre de lignes lues, soit une valeur négative représentant l'une des erreurs suivantes : Voir le tableau ci-dessous pour les valeurs de retour. |
Syntaxe 13
IntVal = SQL_COMMAND(Mode, CmdId);
Type de retour : INTEGER
Exécution
|
Mode |
Mnémonique |
Action |
| 14 | BUFFERLINECOUNT |
Récupère le nombre de lignes dans le buffer, à la suite d'un appel au mode EXECREADER, une fois que la variable de status est passée à 0. Retour : Soit zéro ou une valeur positive représentant le nombre de lignes lues, soit une valeur négative représentant l'une des erreurs suivantes :
Voir le tableau ci-dessous pour les valeurs de retour. |
| 15 | BUFFERFIELDCOUNT |
Récupère le nombre de champs dans le buffer, à la suite d'un appel au mode EXECREADER, une fois que la variable de status est passée à 0. Retour : Soit zéro ou une valeur positive représentant le nombre de champs lus, soit une valeur négative représentant l'une des erreurs suivantes : Voir le tableau ci-dessous pour les valeurs de retour. |
| 18 | BUFFERSIZE |
Récupère la taille du buffer, à la suite d'un appel au mode EXECREADER, une fois que la variable de status est passée à 0. Retour : Soit une valeur positive représentant le nombre d'octets dans le buffer, soit une valeur négative représentant l'une des erreurs suivantes :
Voir le tableau ci-dessous pour les valeurs de retour. |
| 20 | READAFFECTEDROW |
Récupère le résultat d'un appel avec le mode EXECNONQUERY, une fois que la variable de status est passée à 0. Retour : Soit une valeur positive représentant le nombre d'enregistrements affectés par la commande, soit une valeur négative représentant l'une des erreurs suivantes : Voir le tableau ci-dessous pour les valeurs de retour. |
| 21 | CANCEL |
Annule la requête correspondante à CmdId. Retour : 0 si OK, sinon un nombre négatif indique une des erreurs suivantes : Voir le tableau ci-dessous pour les valeurs de retour. |
| 22 | DISPOSE |
Libère le contexte associé à une requête correspondante au CmdId, y compris le buffer interne. Doit être appelé impérativement après le traitement des résultats d'une requête afin de libérer les ressources. Le résultat du buffer n'est plus utilisable après l'exécution du mode DISPOSE. Retour : 0 si OK, sinon un nombre négatif indique une des erreurs suivantes : Voir le tableau ci-dessous pour les valeurs de retour. |
Ne pas appeler le mode DISPOSE une fois que vous avez terminé une commande et le traitement de son résultat empêche de libérer de la mémoire et peut conduire à une utilisation incontrôlée des ressources machine.
Syntaxe 14
IntVal = SQL_COMMAND(Mode, CmdId, BufferHandle);
Type de retour : INTEGER
Exécution
|
Mode |
Mnémonique |
Action |
| 10 | READBUFFER |
Utilisé pour lire le résultat d'une requête EXEC_READER une fois que la valeur de la variable de status est passée à 0. Il peut être nécessaire d'exécuter cette fonction une ou plusieurs fois en fonction de la taille du buffer et de la quantité de données renvoyées. Retour : Soit une valeur positive représentant le nombre de lignes lues, soit une valeur négative représentant l'une des erreurs suivantes : Voir le tableau ci-dessous pour les valeurs de retour. |
| 16 | BUFFERFIELDNAME |
Récupère les noms des entêtes, à la suite d'un appel au mode EXECREADER, une fois que la variable de status est passée à 0. Retour : 0 si OK, sinon un nombre négatif indique une des erreurs suivantes : Voir le tableau ci-dessous pour les valeurs de retour. |
| 17 | BUFFERFIELDTYPE |
Récupère les types de données correspondant aux champs, à la suite d'un appel au mode EXECREADER, une fois que la variable de status est passée à 0. Retour : 0 si OK, sinon un nombre négatif indique une des erreurs suivantes : Voir le tableau ci-dessous pour les valeurs de retour. |
| 19 | READSCALARVALUE |
Lit la valeur scalaire, à la suite d'un appel au mode EXECSCALAR, une fois que la variable de status est passée à 0. Retour : 0 si OK, sinon un nombre négatif indique une des erreurs suivantes : Voir le tableau ci-dessous pour les valeurs de retour. |
Liste des valeurs de retour possible et leurs significations
| Valeur de retour | Enum | Description |
| 0 | OPERATION_SUCCEEDED | Opération terminée avec succès |
| -1 | SQLCONNAME_PARAM_NOT_STR_OR_NOT_READ | Le paramètre SqlConnectionName n'est pas de type string ou n'a pas pu être lu |
| -2 | SQLCMD_PARAM_NOT_STR_OR_NOT_READ | Le paramètre SqlCmd n'est pas de type string ou n'a pas pu être lu |
| -3 | STATUSVARIABLE_PARAM_NOT_STR_OR_NOT_READ | Le paramètre StatusVariable n'est pas de type string ou n'a pas pu être lu |
| -4 | LINESEPARATOR_PARAM_NOT_STR_OR_NOT_READ_OR_TOOLONG | Le paramètre LineSeparatorn'est pas de type string, n'a pas pu être lu ou est trop long |
| -5 | FIELDSEPARATOR_PARAM_NOT_STR_OR_NOT_READ_OR_TOOLONG | Le paramètre FieldSeparatorn'est pas de type string, n'a pas pu être lu ou est trop long |
| -6 | BUFFERHANDLE_PARAM_INVALID_OR_NULL_OR_NULLSIZE | Le paramètre BufferHandle est invalide, Null ou de taille Null. L'allocation du buffer a probablement été oubliée, ou elle ne s'est pas exécutée correctement |
| -7 | LINENUMBER_PARAM_INVALID | Le paramètre LineNumber est invalide |
| -8 | FIELDNUMBER_PARAM_INVALID | Le paramètre FieldNumber est invalide |
| -9 | ERRORTEXTVARIABLE_PARAM_NOT_STR_OR_NOT_READ | Le paramètre ErrorTextVariable n'est pas de type string ou n'a pas pu être lu |
| -10 | CONNECTION_PARAM_INVALID | Le paramètre ConnectionParam est invalide |
| -11 | COMMAND_PARAM_INVALID | Le paramètre CommandParam est invalide |
| -12 |
SQLCON_DOES_NOT_EXIST |
La connexion Sql spécifiée n'existe pas dans la configuration |
| -13 |
STATUSVARIABLE_NOT_REGISTER_OR_DOES_NOT_EXIST |
La variable de status passée en paramètre (StatusVariable) n'est pas une variable mesure ou n'existe pas |
| -14 |
ERRORTEXTVARIABLE_NOT_TEXT_OR_DOES_NOT_EXIST |
La variable information supplémentaire passée en paramètre (ErrorTextVariable) n'est pas une variable texte ou n'existe pas |
| -15 | CONNECTION_ALREADY_INIT | La connexion est déjà initialisée |
| -16 | CONNECTION_INIT_FAILED | La connexion n'a pas pu être initialisée |
| -17 | CONNECTION_ALREADY_CLOSE_OR_NOT_INIT | La connexion est déjà fermée ou n'est pas initialisée |
| -18 | CONNECTION_CLOSE_FAILED | Echec de la fermeture de la connexion |
| -19 | SEND_COMMAND_FAILED | Impossible d'envoyer la commande Sql. Cette erreur se produit si le service Windows sous-jacent est arrêté ou si l'utilisateur n'a pas assez de privilèges pour exécuter la commande |
| -20 | MAXIMUM_COMMAND_REACH | Le nombre maximum de commandes en cours est atteint |
| -21 | MAXIMUM_CONNECTION_REACH | Le nombre maximum de connexions simultanées est atteint |
| -22 | CMDID_DOES_NOT_EXIST | La commande CmdId passée en paramètre n'existe pas |
| -23 | CMD_TYPE_NOT_VALID | Le type de commande est invalide. Par exemple, cette erreur est déclenchée lors de l'utilisation de READ_BUFFER avec un Id de commande correspondant à une requête de type non-query ou scalaire |
| -24 | CMD_NOT_FINISHED | La commande n'est pas encore terminée |
| -25 | CMD_NOT_REMOVED | La commande n'a pas pu être supprimée |
| -26 | RESULT_BUFFER_EMPTY | Le buffer de résultat est vide |
| -27 | RESULT_BUFFER_TOOSMALL | Le buffer de résultat est trop petit |
| -28 | RESULT_BUFFER_REACH_NBLINE_MAX | Impossible de renvoyer des informations sur le nombre de lignes dans le buffer, car il dépasse la plage de valeurs de retour |
| -29 | RESULT_BUFFER_REACH_SIZE_MAX | Impossible de renvoyer des informations sur la taille du buffer car elle dépasse la plage de valeurs de retour |