Tivoli Service Desk 6.0 Developer's Toolkit Script - Manuel de référence du langage TSD Script
Retour à la page principale
Commence une transaction.
FUNCTION SQLBeginWork: INTEGER;
Normalement, TSD Script valide chaque instruction SQL lorsque celle-ci aboutit. Toutefois, il se peut que vous souhaitiez qu'une série d'instructions SQL soient validées ou invalidées ensemble. Dans ce cas, utilisez l'instruction SQLBeginWork, qui suspend la validation automatique de chaque instruction SQL jusqu'à ce que vous appeliez SQLCommit ou SQLRollBack.
Après une validation ou une invalidation, la transaction prend fin et TSD Script reprend la validation automatique. SQLBeginWork doit alors être appelée de nouveau pour commencer une autre transaction.
KNOWLEDGEBASE Example;
--PUBLIC ROUTINES
FUNCTION Test:INTEGER;
PRIVATE ROUTINES
FUNCTION Test:INTEGER IS VARIABLES
ok : BOOLEAN; ACTIONS
(* start the transaction (transaction) ==> this disables the normal automatic committing after every SQL operation *) SQLBeginWork;
(* do your work here ok := .... *)
IF ok THEN SQLCommit; (* save changes since SQLBeginWork *) ELSE SQLRollBack; (* reverse changes since SQLBeginWork *) END;
(* After a commit or rollback the transaction will be terminated. *) (* Call SQLBeginWork again to start the next transaction if you don't *) (* want the automatic committing *)
END; --Test--
Code retour | Description |
1 | Opération exécutée avec succès. |
(autre) | Reportez-vous au manuel Tivoli Service Desk 6.0 Developer's Toolkit - Guide de programmation TSD Script. |
Ferme les instructions préparées et les curseurs ouverts et ferme les connexions de SGBD ouvertes.
FUNCTION SQLCloseAll: INTEGER;
Bien que cela ne soit pas obligatoire, il est conseillé d'appelé cette routine avant de sortir du fichier .kb principale. En effet, elle permet de valider les transactions éventuellement en cours.
KNOWLEDGEBASE Example;
--PUBLIC ROUTINES
FUNCTION Test:INTEGER;
PRIVATE ROUTINES
FUNCTION Test:INTEGER IS ACTIONS (* perform some SQL operations... *)
SQLCloseAll; END;
Codes retour | Description |
1 | Opération exécutée avec succès. |
(autre) | Reportez-vous au manuel Tivoli Service Desk 6.0 Developer's Toolkit - Guide de programmation TSD Script. |
Ferme un curseur précédemment ouvert par un appel à SQLSelect.
FUNCTION SQLCloseCursor(cursor: SQLCURSOR): INTEGER;
Attention : Une opération d'invalidation ferme tous les curseurs (voir SQLRollBack).
La plupart des pilotes ne permettent pas de définir des curseurs susceptibles de couvrir plusieurs unités de travail (c'est-à-dire en les déclarant avec WITH HOLD). Le pilote DB2 CLI constitue une exception. Après une opération de validation, tous les curseurs sont fermés. Par conséquent, si vous exécutez des opérations SQL (telles que des mises à jour) dans une boucle d'extraction, vous devez désactiver la validation automatique qui intervient normalement après chaque instruction SQL.
Remarque : Vous devez fermer tous les curseurs avant d'effectuer une opération de validation ou d'invalidation.
Nom de l'argument | Description |
cursor | Paramètre de type SQLCursor défini par un appel précédent à SQLSelect. |
Lorsque son exécution s'achève, SQLCloseCursor affecte au curseur la valeur $Unknown. Tout appel à SQLCloseCursor alors que le curseur concerné a déjà été fermé prend fin avec une erreur. Aucun message d'erreur n'est toutefois affiché.
KNOWLEDGEBASE Example;
--PUBLIC ROUTINES
FUNCTION Test:INTEGER;
PRIVATE ROUTINES
FUNCTION Test:INTEGER IS VARIABLES (* columns *) name: STRING; (* misc *) cursor: SQLCursor; retCd: INTEGER; ACTIONS (* select all employees *) retCd := SQLSelect(cursor,'* from emp'); IF (retCd < 0) THEN EXIT retCd; END;
retCd := SQLFetch(cursor,name); WHILE (retCd > 0) DO (* perform some operations based on this row...
. . . *)
(* get the next record *) retCd := SQLFetch(cursor); END;
(* now close the cursor *) SQLCloseCursor(cursor);
END;
Code retour | Description |
1 | La fermeture du curseur a abouti. |
(autre) | Reportez-vous au manuel Tivoli Service Desk 6.0 Developer's Toolkit - Guide de programmation TSD Script. |
Ferme une instruction précédemment ouverte (préparée) à l'aide de SQLPrepare.
FUNCTION SQLCloseStatement(statement: SQLSTATEMENT): INTEGER;
Une opération d'invalidation détruit toutes les instructions préparées. Une opération de validation ferme toutes les instructions préparées qui ne font pas référence à un curseur ouvert.
Remarque : Vous devez fermer manuellement toutes les instructions concernées à l'aide de SQLCloseStatement avant d'effectuer une opération de validation ou d'invalidation.
Nom de l'argument | Description |
statement | Le paramètre statement est initialisé par un appel à SQLPrepare. |
SQLCloseStatement est prise en charge par tous les pilotes. Lorsque son exécution s'achève, SQLCloseStatement affecte au curseur la valeur $Unknown.
Tout appel à SQLCloseStatement alors que l'instruction concernée a déjà été fermée prend fin avec une erreur. Aucun message d'erreur n'est toutefois affiché.
KNOWLEDGEBASE Example;
--PUBLIC ROUTINES
FUNCTION Test(REF users: LIST OF STRING):INTEGER;
PRIVATE ROUTINES
FUNCTION Test(REF users: LIST OF STRING):INTEGER IS VARIABLES stmt: SQLStatement; retCd: INTEGER; ACTIONS SQLBeginWork
(* insert the user names passed in *) retCd := SQLPrepare(stmt,'INSERT INTO USERS VALUES (?)'); IF (retCd < 0) THEN SQLRollBack; (* terminate the transaction *) EXIT retCd; END;
FOR users DO retCd := SQLExecute(stmt,users[$current]); IF retCd < 0 THEN SQLCloseStatement(stmt); SQLRollBack; (* reverse changes and release locks *) EXIT retCd; END; END; (* for *)
(* close the prepared statement *) SQLCloseStatement(stmt); SQLCommit; (* save changes and release locks *) END;
Code retour | Description |
1 | Opération exécutée avec succès. |
(autre) | Reportez-vous au manuel Tivoli Service Desk 6.0 Developer's Toolkit - Guide de programmation TSD Script. |
Envoie à l'interpréteur SQL des commandes non SQL dépendantes de l'installation.
FUNCTION SQLCommand(sub_command: STRING): INTEGER;
Nom de l'argument | Description |
sub_command | La chaîne de commande comporte deux parties : la sous-commande du gestionnaire de base de données, et les paramètres éventuels de cette sous-commande. Vous pouvez taper cette dernière indifféremment en majuscules ou en minuscules. Les paramètres doivent être séparés par des espaces. Pour connaître la liste des sous_commandes disponibles, reportez-vous à la section suivante. |
Comme vous pouvez le constater en regardant le tableau, l'instruction SQLCommand admet de nombreuses sous-commandes.
Plusieurs sous-commandes nécessitent une chaîne de descripteur de connexion (connection_handle_string). Pour désigner la base de données source actuellement sélectionnée, vous pouvez transmettre la valeur $Current. Vous pouvez également ne rien indiquer, auquel cas cette base sera automatiquement utilisée.
Pour obtenir une chaîne de descripteur de connexion, appelez SQLCommand avec la sous-commande GET CURRENT CONNECTION. La valeur entière renvoyée peut alors être affectée à une chaîne. Cette chaîne est la (chaîne_de_descripteur_de_connexion).
Plusieurs sous-commandes comportent un nom de source (nom_de_la_source). (Les paramètres de nom de source sont toujours facultatifs.) Pour préciser la source à laquelle vous êtes actuellement connecté, vous pouvez transmettre la valeur $Current. Pour préciser la source de données par défaut, transmettez la valeur $Default. Si aucun nom de source n'est précisé, la valeur $Current est utilisée par défaut.
Le tableau ci-dessous répertorie les sous-commandes (argument '<sub_command>') de
l'instruction SQLCommand ainsi que leurs paramètres et leur description. Les valeurs de la colonne
Paramètre doivent être fournies par l'utilisateur.
Sous-commande | Paramètre | Description |
CONNECT | chaîne_de_connexion | Ouvre une connexion avec votre SGBD. Cette commande doit être appelée avant toute opération SQL. Généralement, c'est l'une des premières instructions appelées par votre application. Si le paramètre chaîne_de_connexion n'est pas fourni, une connexion est établie avec la source de données par défaut. Une fois la connexion établie, elle devient la connexion actuellement sélectionnée. |
DISCONNECT | chaîne_de_descripteur_de_connexion | Interrompt la connexion désignée par chaîne_de_descripteur_de_connexion. Le descripteur de connexion est un entier qui peut être obtenu en appelant SQLCommand (GET CURRENT CONNECTION) immédiatement après l'établissement de la connexion. |
GET CASE CONVERSION | nom_de_la_source | Renvoie le mode de conversion de la casse des noms d'objets (et non des données) : 0 = NONE (aucune conversion) 1 = UPPER (majuscules) 2 = LOWER (minuscules) Un code retour négatif signale une erreur. |
GET CASE SENSITIVITY | nom_de_la_source | Indique à Tivoli Service Desk Developer's Toolkit si le SGBD effectue la distinction
entre les majuscules et les minuscules pour les noms d'objets (noms de tables, de colonnes, etc.). Ceci ne
concerne pas les données (bien que dans certains SGBD, tels que SQLServer, les noms d'objets
et les données soient soumis à la distinction majuscules/minuscules). Les valeurs susceptibles d'être renvoyées sont les suivantes : 0 = pas de distinction majuscules/minuscules 1 = distinction majuscules/minuscules effectuée |
GET CATALOG CASE CONVERSION | nom_de_la_source | Renvoie le mode de conversion de la casse des données des tables du catalogue
système : 0 = NONE (aucune conversion) 1 = UPPER (majuscules) 2 = LOWER (minuscules) Une valeur négative signale une erreur. |
GET CHECK DRIVER | nom_de_la_source | Renvoie TRUE si (au moment de la connexion) une vérification est effectuée pour déterminer si le pilote (par exemple, CDSS06.DLL) fait partie des pilotes non pris en charge. Sinon, renvoie la valeur FALSE. |
GET CURRENT CONNECTION | nom_de_la_source | Renvoie un entier correspondant au descripteur de la connexion actuellement sélectionnée. Si vous recevez un code retour négatif, reportez-vous à la page Définition des codes d'erreur SQL pour plus d'informations. |
GET CURRENT ODBC HENV | Renvoie le descripteur d'environnement ODBC effectivement utilisé par Tivoli Service Desk Developer's Toolkit. Ceci ne s'applique que lors de l'utilisation de pilotes ODBC. Une valeur négative signale une erreur. | |
GET CURRENT ODBC HDBC | Renvoie le véritable descripteur de connexion ODBC pour la connexion principale en cours de Tivoli Service Desk Developer's Toolkit. Ceci ne s'applique que lors de l'utilisation de pilotes ODBC. Une valeur négative signale une erreur. | |
GET DATE FORMAT | nom_de_la_source | Renvoie le format de date en cours utilisé par le SGBD. |
GET DBMS | nom_de_la_source | Renvoie le code entier correspondant au SGBD de la source "nom_de_la_source". Les valeurs susceptibles d'être renvoyées sont 0 ou 2 (DB2/) ; 1 (Oracle) ; 3, 23 ou 24 (SQLServer) ; 4 ou 12 (SYBASE) et 16 ou 17 (INFORMIX). |
GET IN TRANSACTION | descripteur_de_connexion | Renvoie 1 si une transaction est en cours is (en d'autres termes, si SQLBeginWork a été appelée et que SQLCommit ou SQLRollback ne l'a pas encore été). Le code retour 0 indique qu'aucune transaction n'est en cours. Un code retour négatif signale une erreur. |
GET MODULE | Renvoie le code entier correspondant à la bibliothèque SQL que vous utilisez. Ceci ne permet que la compatibilité amont. Les valeurs possibles des codes de modules sont : 2 = (Multiplateforme - X/OPEN et ODBC). | |
GET MODULE TYPE | Renvoie le type de module en cours. Ceci ne permet que la compatibilité amont. Les
valeurs possibles sont : 5 = X/OPEN. Remarque : Cette sous-commande est semblable à la sous-commande GET MODULE, mais GET MODULE mappe ODBC sur Q+E version 2 pour garantir la compatibilité amont. |
|
GET MULTI CONNECT | nom_de_la_source | Renvoie 1 si la source nom_de_la_source supporte des connexions simultanées. |
GET SHOW WARNINGS | source | Renvoie TRUE si les boîtes de messages d'avertissement sont active. Sinon, renvoie FALSE. |
GET TIME FORMAT | nom_de_la_source | Renvoie le format d'heure en cours utilisé par le SGBD. |
GET UPDATE LOCK STYLE | nom_de_la_source | Renvoie le style de verrouillage en cours : 0 = NONE (aucun verrouillage) 1 = SELECT FOR UPDATE (sélection pour mise à jour) 2 = UPDATE (mise à jour) Un code retour négatif signale une erreur. |
GET UPDATE MODE | nom_de_la_source | Renvoie le mode de mise à jour en cas de contrôle passif des accès concurrents. Les
valeurs admises sont : 0 = NONE (aucun) 1 = SELECT (sélection) 2 = DBMS_OPTIMISTIC (optimiste SGBD) Un code retour négatif signale une erreur. |
RESTORE CURRENT QUALIFIER | Extrait la valeur du dernier qualifiant sauvegardé dans la pile interne et fait de ce qualifiant le qualifiant en cours pour la connexion en cours. | |
RESTORE CURRENT SYSQUALIFIER | Extrait la valeur du dernier qualifiant de table système sauvegardé dans la pile interne et fait de ce qualifiant le qualifiant système en cours pour la connexion en cours. | |
SAVE CURRENT QUALIFIER | Place la valeur du qualifiant de table en cours de la connexion en cours dans une pile interne. | |
SAVE CURRENT SYSQUALIFIER | Place la valeur du qualifiant de table système en cours de la connexion en cours dans une pile interne. | |
SET CASE CONVERSION | conversion | Définit le mode de conversion de la casse des noms d'objets (et non des données). Les valeurs admises pour la conversion sont : NONE, UPPER et LOWER. |
SET CASE SENSITIVITY | true | false | Indique à Tivoli Service Desk Developer's Toolkit si le SGBD en cours effectue la distinction entre les majuscules et les minuscules pour les noms d'objets (noms de tables, de colonnes, etc.). Ceci ne concerne pas les données(bien que dans certains SGBD, tels que SQLServer, les noms d'objets et les données soient soumis à la distinction majuscules/minuscules). |
SET CATALOG CASE CONVERSION | conversion | Définit le mode de conversion de la casse des données des tables du catalogue système. Les valeurs admises pour conversion sont UPPER (majuscules), LOWER (minuscules) et NONE (pas de conversion). |
SET CHECK DRIVER | true | false | Définit l'état en cours pour la vérification du pilote. |
SET CONNECTION | chaîne_de_descripteur_de_connexion | Définit la connexion actuellement sélectionnée, en utilisant le descripteur désigné par chaîne_de_descripteur_de_connexion. |
SET CURRENT QUALIFIER | qualifiant | Définit le qualifiant de table comme étant le qualifiant de la connexion actuellement sélectionnée. |
SET CURRENT SYSQUALIFIER | qualifiant | Définit le qualifiant de table système comme étant le qualifiant de la connexion actuellement sélectionnée. |
SET DBMS | sgbd | Permet de remplacer le SGBD actuellement reconnu. (Pour connaître la liste des valeurs de SGBD, reportez-vous à la description de la sous-commande GET DBMS.) |
SET SHOW WARNINGS | true | false | Définit l'état en cours pour l'affichage des boîtes de messages d'avertissement. |
SET UPDATE LOCK STYLE | style | Permet de définir localement le style de verrouillage en cours. Les valeurs admises pour style sont : NONE, SELECT FOR UPDATE et UPDATE. |
SET UPDATE MODE | none | select | dbms_optimistic | Indique à Tivoli Service Desk Developer's Toolkit comment le contrôle passif des accès
concurrents doit être effectué : NONE - l'enregistrement original n'est pas comparé avec la base de données. SELECT - exécute une instruction SQL SELECT sur l'enregistrement et le compare à l'enregistrement original utilisé dans les mécanismes de contrôle passif des accès concurrents afin de déterminer si la version SGBD de l'enregistrement a changé. DBMS_OPTIMISTIC - tente d'utiliser les mécanismes de contrôle passif des accès concurrents propres au SGBD afin de déterminer si la version SGBD de l'enregistrement a changé. |
START USING DATABASE | nom_de_base_de_données | Fait de "nom_de_base_de_données" la base de données active. |
TRACE ALERT DESTINATION | nom_de_fichier | Définit le fichier de destination des messages d'avertissement générés par une horloge
de traçage. Dans ce cas, les informations sont ajoutées à la fin du fichier indiqué. Par défaut, il s'agit du fichier sql_trc.alr. Remarque : Les informations sont ajoutées à la fin du fichier existant. Avec la commande TRACE FILE, en revanche, les informations sont placées dans le fichier indiqué et celui-ci est tronqué. |
TRACE AUTO FLUSH | true | false | Si la valeur définie est TRUE, la sortie est vidée (écrite sur disque) dans le fichier
de trace à chaque écriture. Normalement, la sortie destinée au fichier de trace n'est écrite sur disque que
lorsque la trace est terminée ou que le système d'exploitation décide de vider la mémoire tampon. Une défaillance du système d'exploitation peut provoquer la perte de tout ou partie des informations de trace. Cette commande force l'écriture de ces informations dans le fichier, ce qui permet d'éviter toute perte de données en cas de défaillance du système d'exploitation. La valeur par défaut est TRUE. Remarque : En cas de vidage à chaque écriture, la fréquence des accès au disque augmente et les performances peuvent s'en trouver diminuées. |
TRACE ENABLED | true | false | Détermine si la trace est active ou non. Si TRACE ENABLED n'est pas définie explicitement, la valeur utilisée par défaut est FALSE. |
TRACE FILE | nom_de_fichier | Place la sortie de trace dans le fichier indiqué. Ce fichier est tronqué chaque fois que vous démarrez la fonction de trace, sauf si vous avez activé l'ajout des données (voir TRACE APPEND). Si le paramètre TRACE_FILE est absent, le fichier de trace par défaut, sql_trc.log, est créé dans le répertoire en cours. |
TRACE FILE APPEND | true | false | Lorsque la valeur TRUE est indiquée, les données de trace sont ajoutées à celles du fichier existant, le cas échéant. Si la valeur FALSE est indiquée, elles remplacent les données existantes, le cas échéant. Dans les deux cas, le fichier de trace est créé s'il n'existe pas. La valeur par défaut est FALSE. |
TRACE INDENT INCR | entier | Contrôle le nombre d'espaces utilisés pour permettre l'indentation des blocs imbriqués. La valeur par défaut est de 4 espaces. |
TRACE MAX LINE LENGTH | entier | Définit la longueur maximale des lignes du fichier de trace de sortie. Lorsque cette longueur est atteinte, un retour à la ligne se produit. La valeur par défaut est de 2 000 000 000, ce qui a pour effet de désactiver le retour à la ligne. |
TRACE MAX NUM FETCHES | entier | Définit le nombre maximal de lignes d'ensembles de résultats enregistrées dans le fichier journal. Définit également le nombre d'exécutions faisant l'objet d'une consignation en cas d'utilisation de la combinaison SQLPrepare/SQLExecute. La valeur par défaut est 3. |
TRACE MAX PARAMETER SIZE | entier | ALL | NONE | Définit la quantité de données, exprimée en octets par colonne, placées dans le fichier
journal à partir des résultats renvoyés par les instructions SQL. Si vous indiquez ALL, l'instruction entière
est toujours écrite. Si vous indiquez NONE, le traçage des données des colonnes est désactivé et les
résultats ne sont pas journalisés. Si vous indiquez 0, les noms des colonnes apparaissent dans le journal
mais aucune donnée n'est enregistrée.
La valeur par défaut est de 256 octets. |
TRACE MAX STATEMENT SIZE | entier | ALL | Définit la taille limite de la sortie journalisée dans le fichier de trace. Si vous indiquez ALL, l'instruction entière est journalisée sans troncature. La valeur par défaut est de 1024 octets. |
TRACE MSG | texte_du_message | Place le texte du message dans le fichier journal de trace. |
TRACE SEPARATOR | chaîne | Permet d'utiliser une chaîne définie par l'utilisateur au lieu de la valeur par défaut "==>". Permet de repérer rapidement un bloc spécifique dans la sortie de trace. |
TRACE START TIMER | nom_de_l'horloge [/i=espaces_d'indentation] [/a=millisecondes] [/q] | Démarre l'horloge désignée par l'identificateur unique indiqué. Cette valeur est consignée dans le
journal à titre de référence. Le paramètre /i contrôle le niveau d'indentation (nombre d'espaces) à utiliser
lors de la journalisation des événements pendant l'intervalle de temps considéré. La valeur par défaut de /i
est 0. La paramètre facultatif /a permet de définir une limite supérieure pour l'intervalle de temps, qui servira de seuil d'alerte. Le paramètre facultatif /q permet d'activer le mode de sortie "silencieux", c'est-à-dire sans consignation dans le fichier journal. Si vous omettez ce paramètre, la sortie est placée dans un fichier. Remarque : TRACE_START_TIMER est appelée de façon implicite lors de l'initialisation de SQL. |
TRACE STATEMENTS | Liste des types d'instructions à journaliser, séparés par un signe plus (+). Pour désactiver la journalisation, définissez l'indicateur avec la valeur NONE. La valeur par défaut est ALL. | |
TRACE STOP TIMER | nom_de_l'horloge | Met fin à la session de chronométrage démarrée par l'appel correspondant à
TRACE_START_TIMER. (Le nom d'horloge unique n'est pas soumis à la distinction majuscules/minuscules.) Lorsque la session prend fin, le niveau d'indentation est réinitialisé et les résultats sont consignés, sauf si le paramètre de mode silencieux /q (quiet) a été indiqué (dans TRACE START TIMER) pour désactiver la sortie dans le fichier journal. Remarque : TRACE STOP TIMER est appelée de façon implicite lors de la désinitialisation de SQL (SQLCloseAll ou fin du programme). |
WRITE LAST ERROR MSG | nom_de_fichier | Ecrit le dernier message d'erreur du SGBD dans le fichier nom_de_fichier. Cette sous-commande n'écrit pas les messages d'erreur générés par Tivoli Service Desk Developer's Toolkit (par exemple, INVALID CURSOR HANDLE). |
Vous pouvez définir un sous-ensemble des options de trace à l'aide des variables d'environnement SAISQLTRCFILE et SAISQLTRCENABLED.
SAISQLTRCFILE définit le nom du fichier de trace. Par exemple, pour définir cette variable d'environnement à partir de la ligne de commande, tapez :
SET SAISQLTRCFILE=c:\trc\trc.log.
SAISQLTRCENABLED active ou désactive la trace SQL. Par exemple, pour définir cette variable d'environnement à partir de la ligne de commande, tapez :
SET SAISQLTRCENABLED=TRUE.
KNOWLEDGEBASE Example;
--PUBLIC ROUTINES
FUNCTION Test:INTEGER IS VARIABLES connectionHandle, retCd, dbms, module, caseSensitive, caseConvert: INTEGER;
ACTIONS (*connect to the data source*) retCd := SQLCommand('CONNECT SOURCE=ADV_ORACLE;QUAL= EXAV;UID=TIM;');
IF (retCd < 0) THEN EXIT retCd; END;
(* get the current connection handle*) connectionHandle := SQLCommand ('GET CURRENT CONNECTION'); IF (retCd < 0) THEN EXIT retCd; END;
(* set the current connection*) ret := SQLCommand ('SET CONNECTION' & connectionHandle); IF (retCd < 0) THEN EXIT retCd; END;
(*disconnect from the current connection*) retCd := SQLCommand ('DISCONNECT'); IF (retCd < 0) THEN EXIT retCd; END;
(*disconnect from a specified connection*) retCd := SQLCommand ('DISCONNECT' & connectionHandle); IF (retCd < 0) THEN EXIT retCd; END;
(* get the current DBMS type*) dbms := SQLCommand ('GET DBMS'); IF (retCd < 0) THEN EXIT retCd; END;
(* get the DBMS type for a specific data source *) dbms := SQLCommand ('GET DBMS TEST'); IF (retCd < 0) THEN EXIT retCd; END;
(* get SAI_SQL.DLL module type *) module := SQLCommand ('GET MODULE'); IF (retCd < 0) THEN EXIT retCd; END;
(* get whether or not the DBMS is case-sensitive *) caseSensitive := SQLCommand ('GET CASE SENSITIVITY'); IF (retCd < 0) THEN EXIT retCd; END;
(* get the current case conversion mode *) caseConvert := SQLCommand ('GET CASE CONVERSION'); IF (retCd < 0) THEN EXIT retCd; END;
(* set the current case conversion mode for the current connection *) ret := SQLCommand ('SET CASE CONVERSION upper'); IF (retCd < 0) THEN EXIT retCd; END;
(* save the current qualifier for the current connection *) ret := SQLCommand ('SAVE CURRENT QUALIFIER'); IF (retCd < 0) THEN EXIT retCd; END;
(* get the date format for the named ADVISOR *) ret := SQLCommand('GET DATE FORMAT ADVISOR'); IF (retCd < 0) THEN EXIT retCd; END;
(* get the time format for the source to which I am currently connected *) ret := SQLCommand('GET TIME FORMAT'); IF (retCd < 0) THEN EXIT retCd; END;
(* set the current qualifier for the current connection *) ret := SQLCommand('SET CURRENT QUALIFIER Fred'); IF (retCd < 0) THEN EXIT retCd; END;
(* restore the current qualifier for the current connection *) ret := SQLCommand('RESTORE CURRENT QUALIFIER'); IF (retCd < 0) THEN EXIT retCd; END;
(* switch databases *) ret := SQLCommand('START USING DATABASE advisor'); IF (retCd < 0) THEN EXIT retCd; END;
END; --Test--
Code retour | Description |
1 | Opération exécutée avec succès. |
(autre) | Reportez-vous au manuel Tivoli Service Desk 6.0 Developer's Toolkit - Guide de programmation TSD Script. |
Pour plus d'informations concernant les sujets ci-dessous, reportez-vous au manuel Tivoli Service Desk 6.0 Developer's Toolkit - Guide de programmation TSD Script.
Envoie une commande SQL Commit Work à l'interpréteur SQL, ce qui a pour effet de valider toutes les modifications effectuées au cours de la transaction.
FUNCTION SQLCommit: INTEGER;
Si une instruction préparée ne fait pas référence à un curseur ouvert, une validation (commit) entraîne la fermeture de cette instruction. Vous devez fermer manuellement les instructions préparées (le cas échéant) avant d'effectuer une validation.
La plupart des pilotes ne permettent pas de définir des curseurs susceptibles de couvrir plusieurs unités de travail (par exemple, en les déclarant avec WITH HOLD). Le pilote DB2 CLI constitue une exception. Après une opération de validation, tous les curseurs sont fermés. Par conséquent, si vous exécutez des opérations SQL (telles que des mises à jour) dans une boucle d'extraction, vous devez désactiver la validation automatique qui intervient normalement après chaque instruction SQL.
Remarque : Vous devez fermer tous les curseurs avant d'effectuer une opération de validation ou d'invalidation.
Normalement, TSD Script valide chaque instruction SQL lorsque celle-ci aboutit. Toutefois, lorsque vous exécutez un groupe d'instructions SQL dans une transaction, vous devez valider ou invalider manuellement la transaction à l'aide, respectivement, de SQLCommit ou SQLRollBack.
Après un appel à SQLCommit (ou SQLRollBack), la transaction en cours prend fin et la validation automatique reprend. Si vous souhaitez démarrer une autre transaction, vous devez utiliser l'instruction SQLBeginWork.
KNOWLEDGEBASE Example;
--PUBLIC ROUTINES
FUNCTION Test(REF age: INTEGER):INTEGER;
PRIVATE ROUTINES
FUNCTION Test(REF age: INTEGER):INTEGER IS VARIABLES (* misc *) retCd: INTEGER; ACTIONS (* begin a transaction *) SQLBeginWork;
(* delete all employees whose age is > age passed in *) retCd := SQLDelete('emp','age > ' & age); IF retCd < 0 THEN SQLRollBack; (* terminate this transaction *) EXIT retCd; END;
(* commit changes and release locks *) SQLCommit; END;
Code retour | Description |
1 | Opération exécutée avec succès. |
(autre) | Reportez-vous au manuel Tivoli Service Desk 6.0 Developer's Toolkit - Guide de programmation TSD Script. |
A partir d'un enregistrement dont les champs contiennent des critères de recherche, SQLCreateSearchString crée une clause SQL WHERE correcte (sans le WHERE).
FUNCTION SQLCreateSearchString(VAL tableName: STRING, REF searchString: STRING, VAL searchRec: any record or list of any record): INTEGER;
Lors d'une recherche n'effectuant pas la distinction entre majuscules et minuscules, TSD Script appelle automatiquement la fonction Upper appropriée. Dans la plupart des cas, la recherche n'utilise pas d'index. Si vous voulez utiliser des index dans vos recherches, indiquez un opérateur effectuant la distinction entre majuscules et minuscules.
Nom d'argument | Description |
tableName | Table ou vue dans laquelle vous effectuez la recherche. |
searchString | Contient la chaîne de recherche générée par SQLCreateSearchString. |
searchRec | Ce paramètre correspond à un enregistrement ou une liste d'enregistrements contenant les critères de recherche. |
SQLCreateSearchString sert à créer une clause WHERE à partir du contenu de l'enregistrement ou de la liste d'enregistrements transmis. Dans le cas d'une liste d'enregistrements, les clauses résultant de chaque élément de la liste sont combinées à l'aide de l'opérateur logique OR. Pour un enregistrement, les clauses résultant de chaque champ sont combinées avec à l'aide de l'opérateur logique AND.
Remarques à propose de SQLCreateSearchString :
Valeur | Description |
(aucun) | Si aucun opérateur n'est indiqué sur l'écran d'interrogation, la recherche effectuée fait la distinction entre les majuscules et les minuscules. Ceci permet l'utilisation d'index. |
= | Egal à, sans distinction majuscules/minuscules (utilisé si le champ opérateur n'existe pas ou contient $Unknown:database:querying). |
> | Supérieur à, sans distinction majuscules/minuscules. |
< | Inférieur à, sans distinction majuscules/minuscules. |
>= | Supérieur ou égal à, sans distinction majuscules/minuscules. |
<= | Inférieur ou égal à, sans distinction majuscules/minuscules. |
<> | Différent de, sans distinction majuscules/minuscules. |
== | Egal à, avec distinction majuscules/minuscules. |
>> | Supérieur à, avec distinction majuscules/minuscules. |
<< | Inférieur à, avec distinction majuscules/minuscules. |
>= | Supérieur ou égal à, avec distinction majuscules/minuscules. |
<= | Inférieur ou égal à, avec distinction majuscules/minuscules. |
<<>> | Différent de, avec distinction majuscules/minuscules. |
IS NULL | Prend la valeur TRUE si la colonne est NULL. Lorsque vous utilisez l'opérateur IS NULL, la valeur du champ correspondant est sans importance. Toutefois, le champ correspondant à la colonne doit exister. |
IS NOT NULL | Prend la valeur TRUE si la colonne n'est pas NULL. Lorsque vous utilisez l'opérateur IS NOT NULL, la valeur du champ correspondant est sans importance. Toutefois, le champ correspondant à la colonne doit exister. |
Les suffixes _LO et _HI indiquent respectivement les valeurs de plage inférieure et supérieure pour le champ. Par exemple, si "age" est un champ correspondant à une colonne de la table et que age_lo est égal à 21, et age_hi, à 65, le critère de recherche suivant est généré :
'(age >= 21) AND (age <= 65)'. s:
Lorsque vous utilisez les opérateurs de plage _LO et _HI, la valeur du champ de colonne correspondant est sans importance. Toutefois, le champ correspondant à la colonne doit exister.
Si l'un des deux champs d'opérateur de plage _LO ou _HI n'existe pas ou est $Unknown, la fonction de plage est désactivée et la valeur du champ correspondant est utilisée. Si un champ d'opérateur _OP existe et que sa valeur est <>, les opérateurs de plage sont > et <. Sinon, les valeurs par défaut (>= et <=) sont utilisées.
Si la colonne est de type chaîne, vous pouvez effectuer une recherche en utilisant les caractères génériques * et ?.
Dans le programme, les caractères génériques * et ? sont convertis en une clause SQL LIKE compatible avec % et _. Si un champ d'opérateur _OP existe et que sa valeur est <>, les lignes qui ne satisfont pas au critères de recherche sont sélectionnées (c'est-à-dire qu'une clause NOT LIKE est générée).
KNOWLEDGEBASE Example;
--PUBLIC ROUTINES
FUNCTION Test:INTEGER;
PRIVATE ROUTINES
FUNCTION Test:INTEGER IS
TYPES SearchRecord IS RECORD ssn: INTEGER; title: STRING; title_op: STRING; salary: REAL; age_lo:integer; age_hi:integer; age_op:string; name: STRING; name_lo:string; name_hi:string; name_op:string; age: INTEGER; married: BOOLEAN; MARRIED_OP:STRING; rating: REAL; addr: STRING; addr_OP: STRING; bDate: DATE; bTime: TIME; sysDT: STRING; sysDT_op: STRING; END; (* SearchRecord *)
VARIABLES r : SearchRecord; searchString : STRING; cursor : SQLCursor; ret : INTEGER;
ACTIONS
(* These values would normally come from a custom dialog box. *)
r.title_op := '<>'; r.title := 'PROGRAMMER'; (* ( (title <> 'PROGRAMMER) AND *) r.ssn := 315687890; (* (ssn = 316700056) AND *) r.name := 'Pamela*'; (* (name LIKE 'Pamela%') AND *) r.name_op := '=='; (* perform a case-sensitive search *) r.age := 30; (* ((age >= 13) AND (age <= 49)) AND *) r.age_lo := 13; r.age_hi := 49; r.age_op := '='; r.MARRIED_OP := 'is NOT null'; (* (married IS NOT NULL) AND *) r.rating := 43.457; (* (rating = 43.457) *) r.addr := '5051 ?. Morris *'; (* (addr NOT LIKE '5050 _. Morris %') AND *) r.bTime := {14,09,16}:TIME; (* (bTime = '14:09:16') AND *) r.bDate := {06,26,1985}:DATE; (* (bDate= '06/26/1985') AND *) r.sysDT := '1961-10-10-14.09.16.00'; (* (sysDT >= '1961-10-10-14.09.16.00)) *) r.sysDT_op := '>=';
SQLCreateSearchString('emps',searchString,r);
ret := SQLSelect(cursor, 'emps',searchString); IF ret < 0 THEN Exit ret; END;
ret := SQLFetch(cursor,r); WHILE ret > 0 DO
(* process r... *)
ret := SQLFetch(cursor); END;
SQLCloseCursor(cursor); END;
Code retour | Description |
1 | Opération exécutée avec succès. |
(autre) | Reportez-vous au manuel Tivoli Service Desk 6.0 Developer's Toolkit - Guide de programmation TSD Script. |
Supprime la ligne indiquée de sa table.
SQLDelete(tableName: STRING, queryString: STRING [,expressionList...]): INTEGER;
Attention : Un appel à SQLDelete pouvant supprimer de nombreuses lignes, définissez avec soin votre clause WHERE.
Nom d'argument | Description |
tableName | Nom de la table dans laquelle la suppression doit être effectuée. |
queryString | Clause Where. |
expressionList | Liste contenant zéro ou plus expressions, séparées par une virgule. Par exemple : 3,4, âge + 100, nom, 'Fred', Sin(45), ... |
Le mot clé WHERE est facultatif dans la chaîne de requête.
SQLDelete permet la substitution de marqueurs de paramètres. Pour utiliser un marqueur de paramètre, insérez un point d'interrogation (?) dans la chaîne de l'instruction. Celui-ci sert de marque de réservation pour une valeur qui sera substituée ultérieurement.
Cette valeur provient de la liste d'expressions facultative qui suit la chaîne de l'instruction. Le nombre d'expressions doit être identique au nombre de marqueurs de paramètres et les expressions doivent être dans le même ordre que les marqueurs.
Tivoli Service Desk Developer's Toolkit ne peut fournir un contrôle de type totalement fiable en cas d'utilisation de marqueurs de paramètres. Par exemple :
retCd = SQLDelete('emp','WHERE name = ?',name);
La chaîne qui constitue le nom de la variable n'a pas besoin de figurer entre apostrophes. En outre, vous n'êtes pas obligé d'utiliser des variables. Par exemple :
retCd = SQLDelete('emp','WHERE name = ?','Smith');
KNOWLEDGEBASE Example;
--PUBLIC ROUTINES
FUNCTION Test(REF AGE: INTEGER):INTEGER;
PRIVATE ROUTINES
FUNCTION Test(REF AGE: INTEGER):INTEGER IS VARIABLES retCd: INTEGER; ACTIONS (* delete all employees from Indiana, and whose age is greater than *) (* the age passed into this function. *) retCd := SQLDelete('emp','(state = ''IN'') AND (age >> ' & age & ')'); IF (retCd < 0) THEN EXIT retCd; END;
END;
Code retour | Description |
1 | Opération exécutée avec succès. |
(autre) | Reportez-vous au manuel Tivoli Service Desk 6.0 Developer's Toolkit - Guide de programmation TSD Script. |
Supprime la ligne située à l'emplacement du curseur.
SQLDeleteCurrent(cursor: SQLCURSOR): INTEGER;
Nom d'argument | Description |
cursor | Le curseur cursor doit être préalablement ouvert par un appel à SQLSelect. |
SQLDeleteCurrent n'est prise en charge que par le pilote DB2 CLI.
Même si vous n'effectuez pas de mise à jour, vous devez utiliser la clause FOR UPDATE OF dans l'instruction SQLSelect lorsque vous supprimez une ligne. En effet, dans ce cas, l'interpréteur SQL applique les verrouillages appropriés. Si vous n'utilisez pas cette clause, la sélection est considérée comme étant en lecture seule.
Contrairement à l'instruction SQLUpdateCurrent, pour laquelle chaque colonne mise à jour doit être indiquée dans la clause FOR UPDATE OF, il suffit d'indiquer une seule colonne dans l'instruction SQLDeleteCurrent. Vous devez toutefois indiquer au moins une colonne correcte et vous ne pouvez pas utiliser le caractère générique *.
KNOWLEDGEBASE Example;
--PUBLIC ROUTINES
FUNCTION Test(REF age: INTEGER):INTEGER;
PRIVATE ROUTINES
FUNCTION Test(REF age: INTEGER):INTEGER IS
VARIABLES (* columns *) name: STRING; (* misc *) cursor: SQLCursor; retCd: INTEGER; ACTIONS SQLBeginWork
(* select all employees from Indiana, and whose age is greater than *) (* the age passed into this function. *) retCd := SQLSelect(cursor,'name from emp WHERE (state = ''IN'') AND ' & '(age > ' & age & ') FOR UPDATE OF NAME');
IF (retCd < 0) THEN SQLRollBack; (* terminate this transaction *) EXIT retCd; END;
retCd := SQLFetch(cursor,name); WHILE (retCd > 0) DO (* possibly perform some operation(s) based on "name" *)
(* now delete this row *) retCd := SQLDeleteCurrent(cursor); IF (retCd < 0) THEN SQLCloseCursor(cursor); SQLRollback; (* reverse any changes, and release locks *) EXIT retCd; END;
(* get the next record *) retCd := SQLFetch(cursor); END;
SQLCloseCursor(cursor); SQLCommit; (* accept changes and release locks *) END;
Code retour | Description |
1 | Opération exécutée avec succès. |
(autre) | Reportez-vous au manuel Tivoli Service Desk 6.0 Developer's Toolkit - Guide de programmation TSD Script. |
Exécute une instruction préparée.
SQLExecute(statement: STATEMENT [,expressionList...]): INTEGER;
Une opération d'invalidation ferme automatiquement toutes les instructions et curseurs ouverts (préparés) (voir SQLRollBack). Une opération de validation ferme automatiquement les instructions ouvertes qui ne font pas référence à un curseur ouvert.
Remarque : Vous ne pouvez ouvrir plus de 20 instructions simultanément.
Nom d'argument | Description |
statement | Il s'agit de l'instruction dans sa forme préparée, obtenue de SQLPrepare. |
expressionList | Liste contenant zéro ou plus expressions, séparées par une virgule. 3,4, âge + 100, nom, 'Fred', $Sin(45), ... |
Si vous devez exécuter une commande de nombreuses fois dans une boucle, il peut être plus rapide de la préparer une seule fois à l'aide de SQLPrepare et d'exécuter la version préparée dans la boucle à l'aide de SQLExecute.
SQLExecute permet la substitution de marqueurs de paramètres. Pour utiliser un marqueur de paramètre, insérez un point d'interrogation (?) dans la chaîne de l'instruction.
Celui-ci sert de marque de réservation pour une valeur qui sera substituée ultérieurement. Cette valeur provient de la liste d'expressions facultative qui suit la chaîne de l'instruction. Le nombre d'expressions doit être identique au nombre de marqueurs de paramètres et les expressions doivent être dans le même ordre que les marqueurs.
Tivoli Service Desk Developer's Toolkit ne peut fournir un contrôle de type totalement fiable en cas d'utilisation de marqueurs de paramètres. Par exemple :
retCd = SQLPrepare(stmt, 'UPDATE emp SET name= ? WHERE ssn=?);
La chaîne qui constitue le nom de la variable n'a pas besoin de figurer entre apostrophes. En outre, vous n'êtes pas obligé d'utiliser des variables. Par exemple :
retCd = SQLExecute (stmt, 'Smith', 317689630);
Les marqueurs de paramètres permettent d'effectuer certaines opérations (telles que cette mise à jour) dans des boucles compactes à l'aide de la combinaison efficace SQLPrepare/SQLExecute au lieu de SQLUpdate, SQLExecuteImmediate, etc.
KNOWLEDGEBASE Example;
--PUBLIC ROUTINES
FUNCTION Test(REF users: LIST OF STRING):INTEGER;
PRIVATE ROUTINES
FUNCTION Test(REF users: LIST OF STRING):INTEGER IS VARIABLES stmt: SQLStatement; retCd: INTEGER; ACTIONS SQLBeginWork; (* start a transaction *)
(* insert the user names passed in *) retCd := SQLPrepare(stmt,'INSERT INTO USERS VALUES (?)'); IF (retCd < 0) THEN SQLRollBack; (* terminate this transaction *) EXIT retCd; END;
FOR users DO retCd := SQLExecute(stmt,users[$current]); IF (retCd < 0) THEN SQLRollBack; (* reverse changes and release locks *) EXIT retCd; END; END; (* for *)
SQLCloseStatement(stmt); SQLCommit; (* accept changes and release locks *) END;
Code retour | Description |
1 | Opération exécutée avec succès. |
(autre) | Reportez-vous au manuel Tivoli Service Desk 6.0 Developer's Toolkit - Guide de programmation TSD Script. |
Exécute une instruction SQL directement, à partir de sa version sous forme de chaîne.
SQLExecuteImmediate(sqlCommand: STRING [,expressionList...]): INTEGER;
Nom d'argument | Description |
sqlCommand | Il doit s'agir d'une commande (instruction) SQL complète et syntactiquement correcte, autre qu'une commande SELECT et pouvant être préparée dynamiquement. |
expressionList | Liste contenant zéro ou plus expressions, séparées par une virgule. 3,4, âge + 100, nom, 'Fred', $Sin(45), ... |
SQLExecuteImmediate permet d'exécuter toutes les commandes SQL, à l'exception des commandes SELECT et des commandes qui ne peuvent être préparées dynamiquement.
Si vous devez exécuter une commande de nombreuses fois dans une boucle, il peut être plus rapide de la préparer une seule fois à l'aide de SQLPrepare et d'exécuter la version préparée dans la boucle.
Vous pouvez utiliser les fonctions intégrées de gestion des chaînes de Tivoli Service Desk Developer's Toolkit's pour vous aider à construire la chaîne de votre commande.
Tivoli Service Desk Developer's Toolkit ne procède à aucun développement de la qualification dans SQLExecuteImmediate. Toutefois, vous pouvez toujours utiliser $QUAL et $SYSQUAL.
Note permet la substitution de marqueurs de paramètres.
Pour utiliser un marqueur de paramètre, insérez un point d'interrogation (?) dans la chaîne de l'instruction. Celui-ci sert de marque de réservation pour une valeur qui sera substituée ultérieurement. Cette valeur provient de la liste d'expressions facultative qui suit la chaîne de l'instruction. Le nombre d'expressions doit être identique au nombre de marqueurs de paramètres et les expressions doivent être dans le même ordre que les marqueurs.
Tivoli Service Desk Developer's Toolkit ne peut fournir un contrôle de type totalement fiable en cas d'utilisation de marqueurs de paramètres. Par exemple :
retCd = SQLExecuteImmediate('UPDATE emp SET name = ? WHERE ssn = ?',name,ssn);
La chaîne qui constitue le nom de la variable n'a pas besoin de figurer entre apostrophes. En outre, vous n'êtes pas obligé d'utiliser des variables. Par exemple :
retCd =SQLExecuteImmediate('UPDATE emp SET name = ? WHERE ssn?','Smith', 316798965);
KNOWLEDGEBASE Example;
--PUBLIC ROUTINES
FUNCTION Test:INTEGER;
PRIVATE ROUTINES
FUNCTION Test:INTEGER IS VARIABLES (* table columns of emp *) sDate: DATE; (* 'integer' *) name: STRING; (* 'char(15)' *) age: INTEGER; (* 'smallint' *) ssn: INTEGER; (* 'integer' *) married: BOOLEAN; (* 'smallint' *) salary: REAL; (* 'float' *) rating: REAL; (* 'decimal(8,3)' *) addr: STRING; (* 'varchar(81)' *) sp: SPACE; (* 'varchar(2500) *) lsp: SPACE; (* 'long varchar for bit data *) bDate: DATE; (* 'date' *) bTime: TIME; (* 'time' *) sTime: TIME; (* 'integer' *) sysDT: STRING; (* 'timestamp' *)
(* misc *) retCd: INTEGER; s: STRING;
ACTIONS
SQLExecuteImmediate('DROP TABLE tsql');
s := 'CREATE TABLE tsql (name CHAR(15), ' & 'age SMALLINT, ' & 'married SMALLINT, ' & 'ssn INTEGER, ' & 'salary FLOAT, ' & 'rating DECIMAL(8,3), ' & 'addr VARCHAR(81), ' & 'sp VARCHAR(2500), ' & 'lsp LONG VARCHAR FOR BIT DATA, ' & 'bdate DATE, ' & 'btime TIME, ' & 'sdate INTEGER, ' & 'stime INTEGER, ' & 'sysDT TIMESTAMP) ' & 'PRIMARY KEY(ssn))'; retCd := SQLExecuteImmediate(s);
EXIT retCd; END;
Code retour | Description |
1 | Opération exécutée avec succès. |
(autre) | Reportez-vous au manuel Tivoli Service Desk 6.0 Developer's Toolkit - Guide de programmation TSD Script. |
Pour plus d'informations, reportez-vous à votre documentation SQL.
Extrait la prochaine ligne du curseur et la place dans les paramètres indiqués.
SQLFetch(cursor: SQLCURSOR [,parameterList...]): INTEGER;
Attention : Si vous utilisez la méthode d'optimisation par extraction préinitialisée, assurez-vous que les paramètres (variables de colonne) indiqués dans la première extraction (extraction d'initialisation) sont toujours visibles lors des extractions suivantes (extractions initialisées). C'est toujours le cas lorsque l'extraction d'initialisation, les paramètres et les extractions initialisées font partie de la même fonction.
Remarque : Une invalidation ferme tous les curseurs. Si une invalidation se produit au cours d'une boucle d'extraction, le prochain appel de SQLFetch échoue.
Nom d'argument | Description |
cursor | Le curseur cursor doit être préalablement ouvert par un appel à SQLSelect. |
paramètres | Liste de zéro ou plus paramètres (variables de colonne) séparés par des virgules, dont les noms doivent correspondre aux noms des colonnes associées (voir les remarques ci-dessous). |
Une instruction SQLFetch optimisée présente deux formes. Dans la première, tous les paramètres (variables de colonne) figurent après le curseur, alors que la seconde ne comporte que le curseur. La première forme est désignée sous le nom d'extraction d'initialisation car elle initialise Tivoli Service Desk Developer's Toolkit pour permettre des insertions rapides dans les paramètres. La seconde forme suppose que les paramètres à extraire sont les mêmes que ceux qui ont été indiqués dans le dernier appel à une extraction d'initialisation (c'est-à-dire de la première forme). Cette seconde forme est appelée extraction initialisée ou extraction préinitialisée.
Une fois que Tivoli Service Desk Developer's Toolkit connaît les paramètres d'extraction, il s'exécute nettement plus vite lorsque vous n'indiquez pas de nouveau ces paramètres. (En effet, si vous les indiquez de nouveau, Tivoli Service Desk Developer's Toolkit est obligé de les réinitialiser inutilement.)
Remarque : Pour plus d'informations sur les extractions préinitialisées, reportez-vous aux avertissements relatifs à cette instruction.
Les noms des paramètres doivent correspondre aux noms des colonnes qui leur sont associées. Tout paramètre
dont le nom ne correspond pas à un nom de colonne est ignoré. Cette règle ne s'applique toutefois pas aux
noms de colonnes qui commencent par SQLColumn_ et se terminent par le numéro de la colonne dans la liste de
sélection. Cette méthode permet en effet d'accéder aux résultats des fonctions (d'agrégation) de colonne.
Par exemple, si la chaîne de sélection est :
SELECT count(*) FROM emp
et que vous déclarez SQLColumn_1 en tant que variable de type INTEGER, vous pouvez extraire le nombre "count" de la manière suivante :
SQLFetch(cursor,$SQLColumn_1);
L'ordre des paramètres $SQLColumn_xx dans la liste n'a pas d'importance.
Par exemple, si nom est une colonne de type caractères, âge, une colonne numérique, et que votre chaîne de sélection est :
SELECT nom,âge FROM emp
et que vous avez déclaré les variables $SQLColumn_xx de la manière suivante :
$SQLColumn_1: STRING; $SQLColumn_2: INTEGER;
alors l'instruction suivante extrait "nom" dans $SQLColumn_1 et "âge" dans $SQLColumn_2 :
SQLFetch(cursor,$SQLColumn_1,$SQLColumn_2);
comme le ferait également :
SQLFetch(cursor,$SQLColumn_2,$SQLColumn_1);
Cet exemple fait appel aux types STRING et INTEGER, mais vous pouvez utiliser l'un quelconque des types de
données TSD Script admis pour $SQLColumn, à l'exception de LIST et WINDOWS.
Vous pouvez transmettre un enregistrement sous forme de paramètre. Dans ce cas, les noms des champs doivent correspondre aux noms des colonnes de la table, sous peine d'être ignorés.
KNOWLEDGEBASE Example;
--PUBLIC ROUTINES
FUNCTION Test(REF age: INTEGER):INTEGER;
PRIVATE ROUTINES
FUNCTION Test(REF age: INTEGER):INTEGER IS VARIABLES VARIABLES (* columns *) name: STRING; (* misc *) cursor: SQLCursor; retCd: INTEGER; ACTIONS SQLBeginWork; (* start a transaction *)
(* select all employees from Indiana, and whose age is greater *) (* than the age passed into this function. *) retCd := SQLSelect(cursor,'name from emp WHERE (state = ''IN'') AND ' & '(age > ' & age & ') FOR UPDATE OF NAME'); IF (retCd < 0) THEN SQLRollBack; (* terminate the transaction *) EXIT retCd; END;
retCd := SQLFetch(cursor,name); WHILE (retCd > 0) DO (* possibly perform some operations based on "name"
. . . *)
(* set name to uppercase *) name := StrUpper(name);
(* now update this row *) retCd := SQLUpdateCurrent(cursor,name); IF (retCd < 0) THEN SQLCloseCursor(cursor); SQLRollback; (* reverse any changes, and release locks *) EXIT retCd; END;
(* get the next record *) retCd := SQLFetch(cursor); END;
SQLCloseCursor(cursor); SQLCommit; (* accept changes and release locks *) END;
Code retour | Description |
1 | Opération exécutée avec succès. |
(autre) | Reportez-vous au manuel Tivoli Service Desk 6.0 Developer's Toolkit - Guide de programmation TSD Script. |
Convertit la valeur d'une donnée en une chaîne adaptée au format de données du SGBD que vous utilisez.
SQLFormat(value: SIMPLE EXPRESSION): STRING;
Il est possible que votre SGBD nécessite des formats de date et d'heure différents de ceux utilisés pour l'affichage. Par exemple, le format de date par défaut d'Oracle est DD-MMM-YY, alors que celui de Tivoli Service Desk Developer's Toolkit aux Etats-Unis est MM/DD/YYYY.
Nom d'argument | Description |
value | Cette valeur doit être d'un type simple (tel que DATE ou STRING). |
SQLFormat renvoie une chaîne formatée, et non un code retour, qui indique si l'opération a abouti ou échoué. Si la valeur transmise est $Unknown, la chaîne 'NULL' est renvoyée. Le formatage spécifique de la chaîne dépend du type de celle-ci :
La chaîne formatée est renvoyée. Si la valeur transmise est $Unknown, la chaîne 'NULL' est renvoyée.
KNOWLEDGEBASE Example;
--PUBLIC ROUTINES FUNCTION GetCount(VAL d: DATE): INTEGER;
PRIVATE ROUTINES FUNCTION GetCount(VAL d: DATE): INTEGER IS VARIABLES retCd : INTEGER; cmd : STRING; $SQLColumn_1 : INTEGER; ACTIONS cmd := 'SELECT COUNT(*) FROM COMPANIES WHERE name = ' & SQLFormat('Joe''s place') & ' AND founded_date ' & SQLFormat(d); retCd := SQLSelectInto(cmd, $SQLColumn_1); IF retCd < 0 THEN Exit( retCd ); ELSE Exit( $SQLColumn_1 ); END; END;
Pour plus d'informations sur les formats de date, d'heure, d'entier et de réels, reportez-vous à la section "Indicateurs de format de types de données" du Chapitre 3.
Pour plus d'informations sur le fichier sai_sql.cfg, reportez-vous au manuel Tivoli Service Desk 6.0 Developer's Toolkit TSD Script - Guide de programmation.
Renvoie le nom que l'interpréteur SQL utilise de manière interne pour désigner le curseur indiqué.
SQLGetCursorName(cursor: SQLCURSOR, cursorName: STRING):
INTEGER;
Nom d'argument | Description |
cursor | Le curseur cursor doit être préalablement ouvert par un appel à SQLSelect. |
cursorName | Nom du curseur. |
SQLGetCursorName n'est prise en charge que par le pilote DB2 CLI.
KNOWLEDGEBASE Example;
--PUBLIC ROUTINES
FUNCTION Test(REF age: INTEGER):INTEGER;
PRIVATE ROUTINES
FUNCTION Test(REF age: INTEGER):INTEGER IS VARIABLES (* columns *) name: STRING; (* misc *) cursor: SQLCursor; cursorName: STRING; retCd: INTEGER; ACTIONS (* select all employees from Indiana, and whose age is greater *) (* than the age passed into this function. *) retCd := SQLSelect(cursor,'name from emp WHERE (state = ''IN'') AND ' & '(age > ' & age & ') FOR UPDATE OF NAME'); IF (retCd < 0) THEN EXIT retCd; END;
SQLGetCursorName(cursor,cursorName);
retCd := SQLFetch(cursor,name); WHILE (retCd > 0) DO
(* possibly perform some operations based on "name" and "cursorName" . . . *)
(* get the next record *) retCd := SQLFetch(cursor); END; SQLCloseCursor(cursor); END;
Code retour | Description |
1 | Opération exécutée avec succès. |
(autre) | Reportez-vous au manuel Tivoli Service Desk 6.0 Developer's Toolkit - Guide de programmation TSD Script. |
Récupère la valeur d'une option d'état de contexte ou de configuration.
SQLGetOption(VAL option: STRING, REF optionValue : <ANY SIMPLE VARIABLE> [, VAL srcOrConn : <INTEGER OR STRING EXPRESSION>]) : INTEGER;
Attention : Contrairement aux noms d'options du fichier de configuration SQL (sai_sql.cfg), les noms d'options transmis à SQLGetOption utilisent des espaces, et non des traits de soulignement, comme séparateurs.
Remarque : La plupart des options dont vous pouvez obtenir la valeur à l'aide de SQLGetOption peuvent être définies avec SQLSetOption.
Nom d'argument | Description |
option | Nom de l'option (tel que : 'DATE FORMAT'). Pour une liste complète, reportez-vous aux remarques. |
optionValue | Variable qui prend la valeur de l'option. |
srcOrConn | Argument facultatif qui, s'il est indiqué, doit contenir un nom de source (STRING) ou un descripteur de connexion (INTEGER). Si cet argument n'est pas indiqué, la valeur $CURRENT est utilisée par défaut. |
La fonction renvoie un code de succès ou d'échec. Les codes d'erreur les plus fréquents sont : INVALID_OPTION et NOT_CONNECTED (pour les options qui exigent une connexion, ce qui est le cas de la plupart d'entre elles).
Cette fonction incorpore certaines des possibilités précédemment offertes par SQLCommand ('GET ... '), mais présente l'avantage de pouvoir renvoyer des données de type STRING.
Les options qui peuvent être indiquées avec cette commande sont les suivantes :
Option | Description |
'BIND PARAMETER BUFFER SIZE' | Renvoie la taille de mémoire tampon utilisée pour la liaison des paramètres. |
'BIND PARAMETER FILL OUTPUT NULL VALS' | Renvoie TRUE si les valeurs de sortie NULL reçoivent la valeur zéro. |
'BIND PARAMETER PAD OUTPUT STRINGS' | Renvoie TRUE si les chaînes de paramètres de sortie sont complétées par des blancs pour obtenir la précision voulue. |
'BOOLEAN FORMAT' | Renvoie le format utilisé pour enregistrer les valeurs booléennes dans le SGBD. Pour plus d'informations concernant le formatage des données, reportez-vous au Chapitre 3 de ce manuel. |
'BOOLEAN PARAMETER PRECISION' | Renvoie la précision utilisée pour la liaison des valeurs booléennes. |
'BOOLEAN PARAMETER TYPE' | Renvoie le type de données X/Open utilisé pour la liaison des valeurs booléennes. |
'BOOLEAN STORAGE TYPE' | Renvoie le type de stockage utilisé pour représenter les valeurs booléennes. Les valeurs
admises sont : 1 - INTEGER 2 - STRING 3 - BOOLEAN |
'CASE CONVERSION' | Renvoie le mode de conversion de la casse utilisé par Tivoli Service Desk Developer's
Toolkit pour les noms d'objets (ne s'applique pas aux données). Les valeurs admises sont : 1 - Upper (majuscules) 2 - Lower (minuscules) 3 - None (aucun) |
'CASE SENSITIVITY' | Renvoie TRUE si la base de données effectue la distinction entre les majuscules et les minuscules pour les noms d'objets (ne s'applique pas aux données). |
'CATALOG CASE CONVERSION' | Renvoie le mode de conversion de la casse utilisé par Tivoli Service Desk Developer's
Toolkit pour les données des vues de catalogues (SAI_SYSCOLUMNS et SAI_SYSTABLES). Les valeurs admises
sont : 1 - Upper (majuscules) 2 - Lower (minuscules) 3 - None (aucun) |
'CHECK DRIVER' | Renvoie TRUE si Tivoli Service Desk Developer's Toolkit vérifie si le pilote fait partie de ceux qui ne sont pas pris en charge. |
'COLUMN CATALOG METHOD' | Renvoie la méthode utilisée par Tivoli Service Desk Developer's Toolkit pour obtenir les
valeurs du catalogue des colonnes. Les valeurs admises sont : 1 - Utilisation de la méthode standard pour interroger le catalogue des colonnes. 2 - Utilisation d'une requête propre au SGBD pour interroger le catalogue des colonnes. 3 - Utilisation de la fonction ODBC SQLColumn(). |
'COMMIT SELECTS' | Applicable si MANUAL COMMITS a la valeur TRUE. Indique si une validation a lieu ou non après les unités de travail en lecture seule. |
'CONFIG FILE' | Renvoie le nom du fichier de configuration utilisé par Tivoli Service Desk Developer's Toolkit lors de l'établissement de la connexion. Il n'est pas nécessaire d'être connecté pour pouvoir obtenir cette valeur. |
'CONNECTION' | Renvoie le descripteur de la connexion. Vous pouvez obtenir cette valeur à l'aide de SQLGetOption mais vous ne pouvez pas la définir avec SQLSetOption. |
'CURRENT COL BUFFER' | Renvoie la taille de la mémoire tampon de colonne en cours. |
'CURRENT ROW BUFFER' | Renvoie la taille de la mémoire tampon de ligne en cours. |
'DATE FORMAT' | Renvoie le format de date utilisé par le SGBD. Pour plus d'informations concernant le formatage des données, reportez-vous au Chapitre 3 de ce manuel. |
'DATE PARAMETER PRECISION' | Renvoie la précision utilisée pour la liaison des valeurs de date. |
'DATE PARAMETER TYPE' | Renvoie le type de données X/Open utilisé pour la liaison des valeurs de date. |
'DATE STORAGE TYPE' | Renvoie le type de stockage utilisé pour représenter les dates. Les valeurs admises
sont : 1 - INTEGER 2 - STRING 6 - DATE |
'DBMS' | Renvoie le SGBD (sous forme de numéro). Les SGBD actuellement reconnus sont : 0 - DB2/2, DB2/6000, DB2/NT, DB2/UX 1 - ORACLE 2 - DB2 3 - SQL SERVER 4.x 4 - SYBASE 5 - NETWARE SQL 6 - GUPTAN SQLBASE 7 - XDB 8 - DBASE 9 - BTRIEVE 10 - ASCII TEXT 11 - EXCEL 12 - SYBASE 10 (et supérieur) 13 - PARADOX 14 - INGRES3 15 - INGRES4 16 - INFORMIX4 17 - INFORMIX5 18 - TANDEM 19 - PROGRESS 20 - HP ALLBASE 21 - WATCOM 22 - FULCRUM 23 - MS SQL SERVER 6.x 24 - (AUTRE) |
'DBMS STRING' | Renvoie les noms de bases de données suivants : DB2, ORACLE, SQLSERVER, SYBASE ou DBMS_OTHER. |
'DSN' | Renvoie le nom de la source de données ODBC en cours (en cas de connexion à une telle source uniquement). |
'HAS TRANSACTIONS' | Renvoie TRUE si le SGBD accepte les transactions. |
'IN TRANSACTION' | Renvoie TRUE si une transaction a été démarrée par SQLBeginWork et n'a pas encore fait l'objet d'une validation ou d'une invalidation. Vous pouvez obtenir la valeur de cette option à l'aide de SQLGetOption mais vous ne pouvez pas la définir avec SQLSetOption. |
'INTEGER FORMAT' | Renvoie le format d'entier utilisé par le SGBD. Pour plus d'informations concernant le formatage des données, reportez-vous au Chapitre 3 de ce manuel. |
'INTEGER PARAMETER PRECISION' | Renvoie la précision utilisée pour la liaison des valeurs entières. |
'INTEGER PARAMETER TYPE' | Renvoie le type de données X/Open utilisé pour la liaison des valeurs entières. |
'INTEGER STORAGE TYPE' | Renvoie le type de stockage utilisé pour représenter les entiers. Les valeurs admises
sont : 1 - INTEGER 2 - STRING |
'LAST ERROR MSG' | Renvoie le texte du dernier message d'erreur émis par le SGBD. |
'MANUAL COMMITS' | Renvoie TRUE si SAI_SQL (et non le pilote) contrôle le comportement de validation. |
'MAX LITERAL LEN' | Renvoie la longueur maximum d'un littéral chaîne au-delà de laquelle Tivoli Service Desk Developer's Toolkit effectue la liaison des paramètres lors des insertions et des mises à jour. |
'MODULE' | Conçu pour permettre la compatibilité amont uniquement. Renvoie le type de module. La seule valeur possible pour Tivoli Service Desk Developer's Toolkit 5.0 est 5 (X/Open). |
'MODULE TYPE' | Conçu pour permettre la compatibilité amont uniquement. Renvoie le type de module. La seule valeur possible pour Tivoli Service Desk Developer's Toolkit 5.0 est 5 (X/Open). |
'MULTI CONNECT' | Renvoie TRUE si le SGBD accepte plusieurs connexions à partir du même processus client. |
'MULTI CONNECT REQUIRED' | Renvoie TRUE si le SGBD exige plusieurs connexions pour pouvoir traiter plusieurs instructions SQL simultanées ("imbriquées"). |
'NEEDS CODEPAGE TRANSLATION' | Renvoie TRUE si Tivoli Service Desk Developer's Toolkit doit effectuer des transcodages de pages de codes ANSI vers OEM et OEM vers ANSI (Windows uniquement). |
'PROCESS RESULTS ON FREESTMT' | Renvoie TRUE si Tivoli Service Desk Developer's Toolkit garantit l'exhaustivité de l'ensemble de résultats en extrayant les données jusqu'à ce que plus aucune ligne ne soit renvoyée. |
'QUAL' | Renvoie le qualifiant (généralement le créateur ou le propriétaire) utilisé pour accéder aux tables de données. |
'REAL FORMAT' | Renvoie le format de nombre réel utilisé par le SGBD. Pour plus d'informations concernant le formatage des données, reportez-vous au Chapitre 3 de ce manuel. |
'REAL PARAMETER PRECISION' | Renvoie la précision utilisée pour la liaison des valeurs réelles. |
'REAL PARAMETER SCALE' | Renvoie l'échelle utilisée pour la liaison des valeurs réelles. |
'REAL PARAMETER TYPE' | Renvoie le type de données X/Open utilisé pour la liaison des valeurs réelles. |
'REAL STORAGE TYPE' | Renvoie le type de stockage utilisé pour représenter les réels. Les valeurs admises sont : 2 - STRING 3 - REAL |
'SHOW WARNINGS' | Renvoie TRUE si les boîtes de message d'avertissement sont affichées. |
'SOURCE' | Renvoie le nom de la source de données SAI_SQL connectée. |
'STRING FORMAT' | Renvoie le format de chaîne utilisé par le SGBD. Pour plus d'informations concernant le formatage des données, reportez-vous au Chapitre 3 de ce manuel. |
'STRING PARAMETER PRECISION' | Renvoie la précision utilisée pour la liaison des valeurs de type chaîne. |
'STRING PARAMETER TYPE' | Renvoie le type de données X/Open utilisé pour la liaison des valeurs de type chaîne. |
'SYSQUAL' | Renvoie le qualifiant nécessaire pour accéder aux tables du catalogue système. Remarque : Depuis la version 4.1.0, Tivoli Service Desk Developer's Toolkit utilise des vues "wrapper" créées par SAI pour la présentation des informations de catalogue, où SYSQUAL est utilisé pour créé les vues (par exemple, EXAV), au lieu du qualifiant système normal (par exemple, SYSIBM). |
'TABLE CATALOG METHOD' | Renvoie la méthode utilisée par Tivoli Service Desk Developer's Toolkit pour obtenir les
valeurs du catalogue des tables. Les valeurs admises sont : 1 - Utilisation de la méthode standard pour interroger le catalogue des colonnes. 2 - Utilisation d'une requête propre au SGBD pour interroger le catalogue des colonnes. 3 - Utilisation de la fonction ODBC SQLTable(). |
'TIME FORMAT' | Renvoie le format d'heure utilisé par le SGBD. Pour plus d'informations concernant le formatage des données, reportez-vous au Chapitre 3 de ce manuel. |
'TIME PARAMETER PRECISION' | Renvoie la précision utilisée pour la liaison des valeurs horaires. |
'TIME PARAMETER TYPE' | Renvoie le type de données X/Open utilisé pour la liaison des valeurs horaires. |
'TIME STORAGE TYPE' | Renvoie le type de stockage utilisé pour représenter les heures. Les valeurs admises sont : 1 - INTEGER 2 - STRING 5 - TIME |
'TRACE ALERT DESTINATION' | Renvoie le nom du fichier d'alertes (si les alertes sont utilisées). |
'TRACE APPEND' | Renvoie TRUE si les données de trace doivent être ajoutées à la fin du fichier de trace (au lieu de remplacer les données existantes). |
'TRACE AUTO FLUSH' | Renvoie TRUE si la sortie de trace est vidée dans le fichier de trace après chaque écriture. |
'TRACE ENABLED' | Renvoie TRUE si la fonction de trace a été activée. |
'TRACE FILE' | Renvoie le nom du fichier de sortie de trace. |
'TRACE INDENT INCR' | Renvoie l'incrément d'indentation utilisé. |
'TRACE MAX LINE LENGTH' | Renvoie la longueur de ligne au-delà de laquelle un retour à la ligne se produit. |
'TRACE NUM EXECUTES' | Renvoie le nombre maximum d'instructions SQLFetch et SQLExecute pouvant être journalisées. |
'TRACE PARAM SIZE' | Renvoie la longueur maximum des paramètres écrits dans le fichier. |
'TRACE SEPARATOR' | Renvoie le séparateur de sortie de trace utilisé. |
'TRACE STATEMENT SIZE' | Renvoie la longueur maximum des instructions écrites dans le fichier. |
'TRACE STATEMENTS' | Renvoie le masque binaire des instructions suivies à l'aide de la fonction de trace. |
'TRANSLATE FUNC' | Renvoie le nom de la fonction de conversion en majuscules utilisée par le SGBD. |
'UPDATE LOCK COLUMN' | Renvoie le nom de la colonne utilisée pour le verrouillage en cas de contrôle passif des accès concurrents (il s'agit généralement de MODIFY_DATETIME). |
'UPDATE LOCK ERROR FILTER' | Renvoie le niveau de filtrage des erreurs utilisé pour le verrouillage en cas de
contrôle passif des accès concurrents en mise à jour. Les valeurs admises sont : 0 - Fatal (valeur par défaut) 1 - Error (erreur) 2 - Warning (avertissement) 3 - Informational (information) |
'UPDATE LOCK STYLE' | Renvoie le style de verrouillage utilisé pour les mises à jour en cas de contrôle passif
des accès concurrents. Les valeurs admises sont : 1 - SELECT FOR UPDATE 2 - UPDATE 3 - UPDATE CONDITIONAL |
'UPDATE MODE' | Renvoie le mode de mise à jour en cas de contrôle passif des accès concurrents
(algorithme). Les valeurs admises sont : 1 - SELECT 2 - DBMS OPTIMISTIC 3 - NONE |
Code retour | Description |
1 | Opération exécutée avec succès. |
(autre) | Reportez-vous au manuel Tivoli Service Desk 6.0 Developer's Toolkit - Guide de programmation TSD Script. |
KNOWLEDGEBASE Example;
--PUBLIC ROUTINES PROCEDURE Example; PRIVATE ROUTINES PROCEDURE Example IS VARIABLES retCd : INTEGER; dateFormat : INTEGER; lastErrorMsg : STRING; hConn : INTEGER; ACTIONS retCd := SQLGetOption('LAST ERROR MSG' lastErrorMsg); retCd := SQLGetOption('DATE FORMAT', dateFormat, 'ADVISOR'); retCd := SQLGetOption('CONNECTION', hConn); retCd := SQLGetOption('DATE FORMAT', dateFormat, hConn); END;
Insère une nouvelle ligne dans la table indiquée.
SQLInsert(tableName: STRING [,parameters...]): INTEGER;
Nom d'argument | Description |
tableName | Nom de la table dans laquelle l'insertion doit être effectuée. |
paramètres | Liste de zéro ou plus paramètres (variables de colonne) séparés par des virgules, dont
les noms doivent correspondre aux noms des colonnes associées (voir les remarques ci-dessous). |
Les paramètres (variables de colonne) transmis à SQLInsert doivent porter le même nom que les colonnes correspondantes de la table. Si le nom d'un paramètre ne correspond à aucun nom de colonne, ce paramètre est ignoré.
Remarque : Vous n'avez pas besoin de transmettre des paramètres pour toutes les colonnes de la table, seulement pour celles qui ont été créées comme étant NOT NULL.
N'essayez pas d'insérer un paramètre Tivoli Service Desk Developer's Toolkit dont la valeur est $Unknown dans une table dont la colonne correspondante a été créée avec l'option NOT NULL. Vous pouvez transmettre un enregistrement sous forme de paramètre. Dans ce cas, les noms des champs doivent correspondre aux noms des colonnes de la table, sous peine d'être ignorés.
KNOWLEDGEBASE Example;
--PUBLIC ROUTINES
FUNCTION Test:INTEGER;
PRIVATE ROUTINES
FUNCTION Test:INTEGER IS VARIABLES (* column names *) name: STRING; ssn: INTEGER; (* misc *) retCd: INTEGER; ACTIONS (* set the column values *) name := 'Fred'; ssn := 316768990;
(* insert new row *) retCd := SQLInsert('emp',name,ssn); IF (retCd < 0) THEN EXIT retCd; END;
END;
Code retour | Description |
1 | Opération exécutée avec succès. |
(autre) | Reportez-vous au manuel Tivoli Service Desk 6.0 Developer's Toolkit - Guide de programmation TSD Script. |
SQLPrepare prépare une chaîne de commande SQL en vue de son exécution ultérieure. Une fois préparée, cette chaîne de commande est appelée "instruction préparée". Si l'opération SQLPrepare aboutit, la variable transmise en tant que paramètre d'instruction contient un descripteur d'instruction correct.
SQLPrepare(statement: SQLSTATEMENT, sqlCommand: STRING): INTEGER;
Une opération d'invalidation ferme automatiquement toutes les instructions et curseurs ouverts (préparés). Une opération de validation ferme automatiquement les instructions ouvertes qui ne font pas référence à un curseur ouvert déclaré WITH HOLD (voir SQLCommit).
Nom d'argument | Description |
statement | Descripteur d'instruction utilisé dans l'instruction SQLExecute suivante. |
sqlCommand | Instruction SQL complète et syntactiquement correcte. |
SQLPrepare permet de préparer toutes les commandes SQL, à l'exception des commandes SELECT et des commandes qui ne peuvent être préparées dynamiquement.
Si vous devez exécuter une commande (telle que SQLDelete) de nombreuses fois dans une boucle, il peut être plus rapide, au lieu de l'exécuter directement chaque fois, de la préparer une seule fois et d'exécuter la version préparée dans la boucle à l'aide de SQLExecute.
Remarque : Vous pouvez utiliser les fonctions intégrées de gestion des chaînes de Tivoli Service Desk Developer's Toolkit pour vous aider à construire la chaîne de la commande à préparer.
Tivoli Service Desk Developer's Toolkit ne procède à aucun développement de la qualification dans SQLPrepare. Toutefois, vous pouvez toujours utiliser $QUAL et $SYSQUAL.
KNOWLEDGEBASE Example;
--PUBLIC ROUTINES
FUNCTION Test(REF users: LIST OF STRING):INTEGER;
PRIVATE ROUTINES
FUNCTION Test(REF users: LIST OF STRING):INTEGER IS VARIABLES stmt: SQLStatement; retCd: INTEGER; ACTIONS SQLBeginWork; (* start a transaction *)
(* insert the user names passed in *) retCd := SQLPrepare(stmt,'INSERT INTO USERS VALUES (?)'); IF (retCd < 0) THEN SQLRollBack; (* terminate the transaction *) EXIT retCd; END;
FOR users DO retCd := SQLExecute(stmt,users[$current]); IF (retCd < 0) THEN SQLRollBack; (* reverse changes and release locks *) EXIT retCd; END; END; (* for *)
SQLCloseStatement(stmt); SQLCommit; (* accept changes and release locks *) END;
Code retour | Description |
1 | Opération exécutée avec succès. |
(autre) | Reportez-vous au manuel Tivoli Service Desk 6.0 Developer's Toolkit - Guide de programmation TSD Script. |
Pour plus d'informations, reportez-vous à votre documentation SQL.
Envoie une commande ROLLBACK WORK à l'interpréteur SQL, ce qui a pour effet d'inverser/annuler les modifications effectuées au cours de la transaction.
FUNCTION SQLRollBack: INTEGER;
Attention : Une invalidation entraîne la fermeture automatique des instructions préparées et des curseurs ouverts.
SQLRollBack met fin à la transaction en cours. Si vous voulez démarrer une autre transaction, vous devez de nouveau utiliser SQLBeginWork. Sinon, TSD Script reprend la validation automatique de chaque instruction SQL.
Utilisez SQLRollBack pour annuler de petites transactions qui ont échoué et qui n'impliquent pas des entrées de l'utilisateur. Evitez de l'utiliser comme méthode générique pour annuler des opérations réalisées à l'aide de l'interface utilisateur.
KNOWLEDGEBASE Example;
--PUBLIC ROUTINES
FUNCTION Test(REF ssnList: LIST OF INTEGER):INTEGER;
PRIVATE ROUTINES
FUNCTION Test(REF ssnList: LIST OF INTEGER):INTEGER IS VARIABLES (* misc *) retCd: INTEGER; ACTIONS (* Start a logical transaction *) SQLBeginWork; (* delete all employees whose ssn is in the ssn list passed in *)
FOR ssnList DO retCd := SQLDelete('emp','ssn = ' & ssnList[$CURRENT]); IF retCd < 0 THEN SQLRollBack; (* reverse the changes and release locks *) EXIT retCd; END; END;
(* commit changes and release locks *) SQLCommit; END;
Code retour | Description |
1 | Opération exécutée avec succès. |
(autre) | Reportez-vous au manuel Tivoli Service Desk 6.0 Developer's Toolkit - Guide de programmation TSD Script. |
Ouvre un curseur basé sur les lignes sélectionnées, en vue de leur extraction ultérieure par SQLFetch.
SQLSelect(cursor: SQLCURSOR, queryString: STRING [,expressionList...]): INTEGER;
Vous ne pouvez ouvrir plus de 20 curseurs simultanément.
Une opération d'invalidation ferme automatiquement tous les curseurs.
La plupart des pilotes ne permettent pas de définir des curseurs susceptibles de couvrir plusieurs unités de travail (c'est-à-dire en les déclarant avec WITH HOLD). Le pilote DB2 CLI constitue une exception. Après une opération de validation, tous les curseurs sont fermés. Par conséquent, si vous exécutez des opérations SQL (telles que des mises à jour) dans une boucle d'extraction, vous devez désactiver la validation automatique qui intervient normalement après chaque instruction SQL.
Remarque : Vous devez fermer tous les curseurs avant d'effectuer une opération de validation ou d'invalidation.
Nom d'argument | Description |
cursor | Descripteur de curseur pour la requête. |
queryString | Chaîne de sélection. Elle doit être complète et syntactiquement correcte. |
expressionList... | Liste contenant zéro ou plus expressions, séparées par une virgule. Par exemple : 3,4, âge + 100, nom, 'Fred', $Sin(45), ... |
Si vous mettez à jour ou supprimez des lignes extraites, utilisez une clause FOR UPDATE OF pour que l'interpréteur SQL comprenne clairement vos intentions. Ceci est obligatoire si vous voulez ultérieurement pouvoir utiliser une instruction SQLUpdateCurrent.
C'est également conseillé si vous utilisez SQLDeleteCurrent. Si vous n'utilisez pas cette clause, la sélection est considérée comme étant en lecture seule.
Remarque : Pour les chaînes de sélection simples (telles que celles de l'exemple), le mot clé SELECT est facultatif.
SQLSelect permet la substitution de marqueurs de paramètres. Pour utiliser un marqueur de paramètre, insérez un point d'interrogation (?) dans la chaîne de l'instruction. Celui-ci sert de marque de réservation pour une valeur qui sera substituée ultérieurement. Cette valeur provient de la liste d'expressions facultative qui suit la chaîne de l'instruction. Le nombre d'expressions doit être identique au nombre de marqueurs de paramètres et les expressions doivent être dans le même ordre que les marqueurs.
Tivoli Service Desk Developer's Toolkit ne peut fournir un contrôle de type totalement fiable en cas d'utilisation de marqueurs de paramètres. Par exemple :
retCd = SQLSelect(cursor,'SELECT * FROM emp WHERE name = ?',name);
La chaîne qui constitue le nom de la variable n'a pas besoin de figurer entre apostrophes. En outre, vous n'êtes pas obligé d'utiliser des variables. Par exemple :
retCd = SQLSelect(cursor,'SELECT * FROM emp WHERE name = ?', 'Smith');
KNOWLEDGEBASE Example;
--PUBLIC ROUTINES
FUNCTION Test(REF age: INTEGER):INTEGER;
PRIVATE ROUTINES
FUNCTION Test(REF age: INTEGER):INTEGER IS VARIABLES (* columns *) name: STRING; (* misc *) cursor: SQLCursor; retCd: INTEGER; ACTIONS SQLBeginTran; (* start a transaction *)
(* select all employees from Indiana, and whose age is *) (* greater than the age passed into this function. *) retCd := SQLSelect(cursor,'SELECT name from emp WHERE (state = ''IN'') AND ' & '(age > ' & age & ') FOR UPDATE OF NAME'); IF (retCd < 0) THEN SQLRollBack; (* terminate the transaction *) EXIT retCd; END;
retCd := SQLFetch(cursor,name); WHILE (retCd > 0) DO (* possibly perform some operations based on "name" . . . *)
(* set name to uppercase *) name := StrUpper(name);
(* now update this row *) retCd := SQLUpdateCurrent(cursor,name); IF (retCd < 0) THEN SQLCloseCursor(cursor); SQLRollBack; (* reverse changes and release locks *) EXIT retCd; END;
(* get the next record *) retCd := SQLFetch(cursor); END;
SQLCloseCursor(cursor); SQLCommit; (* accept changes and release locks *) END;
Code retour | Description |
1 | Opération exécutée avec succès. |
(autre) | Reportez-vous au manuel Tivoli Service Desk 6.0 Developer's Toolkit - Guide de programmation TSD Script. |
Sélectionne et extrait la ligne indiquée dans les paramètres (variables de colonne).
SQLSelectInto(queryString: STRING [,parameters...]): INTEGER;
Nom d'argument | Description |
queryString | Chaîne de sélection. Elle doit être complète et syntactiquement correcte. |
paramètres | Liste de zéro ou plus paramètres (variables de colonne) séparés par des virgules, dont
les noms doivent correspondre aux noms des colonnes associées. Pour plus d'informations, reportez-vous aux remarques. |
SQLSelectInto équivaut à la séquence de code suivante :
SQLSelect SQLFetch SQLCloseCursor
Par conséquent, si la requête de sélection porte sur plusieurs lignes, seule la première d'entre elles est extraite.
Si vous mettez à jour ou supprimez des lignes extraites, utilisez une clause FOR UPDATE OF pour que l'interpréteur SQL comprenne clairement vos intentions. Si vous n'utilisez pas cette clause, la sélection est considérée comme étant en lecture seule.
Les noms des paramètres doivent correspondre aux noms des colonnes qui leur sont associées. Tout paramètre dont le nom ne correspond pas à un nom de colonne est ignoré. Cette règle ne s'applique toutefois pas aux noms de colonnes qui commencent par SQLColumn_ et se terminent par le numéro de la colonne dans la liste de sélection. Cette méthode permet en effet d'accéder aux résultats des fonctions (d'agrégation) de colonne.
Par exemple, si déclarez SQLColumn_1 en tant que variable entière (INTEGER), vous pouvez extraire le nombre "count" de la manière suivante :
SQLSelectInto('SELECT count(*) from emp',$SQLColumn_1);
L'ordre des paramètres $SQLColumn_xx dans la liste n'a pas d'importance. Par exemple, si nom est une colonne de type caractères, âge, une colonne numérique, et que vous avez déclaré les variables $SQLColumn_xx de la manière suivante :
$SQLColumn_1: STRING; $SQLColumn_2: INTEGER;
alors l'instruction suivante extrait "nom" dans $SQLColumn_1 et "âge" dans $SQLColumn_2 :
SQLSelectInto('name,âge FROM emp',$SQLColumn_1,$SQLColumn_2);
comme le ferait également :
SQLSelectInto('name,âge FROM emp',$SQLColumn_2,$SQLColumn_1);
Pour les chaînes de sélection simples (telles que celles de l'exemple), le mot clé SELECT est facultatif.
Vous pouvez transmettre un enregistrement en tant que paramètre. Dans ce cas, les noms des champs doivent
correspondre aux noms des colonnes de la table, sous peine d'être ignorés.
Si vous transmettez deux enregistrements du même type, SQLSelectInto les remplit tous les deux. Ceci permet d'éviter une étape d'affectation en cas de contrôle passif des accès concurrents.
KNOWLEDGEBASE Example;
--PUBLIC ROUTINES
FUNCTION Test:INTEGER;
PRIVATE ROUTINES
FUNCTION Test:INTEGER IS
VARIABLES (* columns *) name: STRING; ssn: INTEGER; age: INTEGER; (* misc *) retCd: INTEGER; ACTIONS (* select all employees from Indiana *) retCd := SQLSelectInto('SELECT * from emp WHERE state = ''IN''', name, age, ssn); IF (retCd < 0) THEN EXIT retCd; END;
END;
Code retour | Description |
1 | Opération exécutée avec succès. |
(autre) | Reportez-vous au manuel Tivoli Service Desk 6.0 Developer's Toolkit - Guide de programmation TSD Script. |
Définit la valeur d'une option d'état de contexte ou de configuration.
SQLSetOption(VAL option: STRING, VAL optionValue:<ANY SIMPLE VARIABLE> [,VAL srcOrConn : <INTEGER OR STRING EXPRESSION> ) : INTEGER;
Contrairement aux noms d'options du fichier de configuration SQL (sai_sql.cfg), les noms d'options transmis à SQLGetOption utilisent des espaces, et non des traits de soulignement, comme séparateurs.
Les options dont vous pouvez obtenir la valeur à l'aide de SQLGetOption ne peuvent pas toutes être définies avec SQLSetOption. Pour connaître la liste des options admises et de celles qui peuvent être modifiées à l'aide de SQLSetOption, reportez-vous à la description de SQLGetOption.
Nom d'argument | Description |
option | Nom de l'option, tel que 'DATE FORMAT'. |
optionValue | Valeur à affecter à l'option. |
srcOrConn | Argument facultatif qui, s'il est indiqué, doit contenir un nom de source (STRING) ou un
descripteur de connexion (INTEGER). Si cet argument n'est pas indiqué, la valeur $CURRENT est utilisée
par défaut. Remarque : Contrairement à SQLGetOption, l'instruction SQLSetOption
de Tivoli Service Desk Developer's Toolkit ne prend actuellement pas en charge cet argument. S'il est
indiqué, il est ignoré. |
La fonction renvoie un code de succès ou d'échec. Les codes d'erreur les plus fréquents sont : INVALID_OPTION et NOT_CONNECTED (pour les options qui exigent une connexion, ce qui est le cas de la plupart d'entre elles).
Cette fonction incorpore la plupart des possibilités précédemment offertes par SQLCommand ('SET ... '). Pour plus d'informations sur chaque paramètre (y compris ses valeurs par défaut), demandez l'aide associée à celui-ci dans l'éditeur de configuration SQL. A l'exception de quelques-uns, tous les paramètres dont vous pouvez obtenir la valeur à l'aide de SQLGetOption peuvent être définis avec SQLSetOption. Pour obtenir la liste des options disponibles (y compris celles qui ne peuvent être définies), reportez-vous à la description de SQLGetOption.
KNOWLEDGEBASE Example;
--PUBLIC ROUTINES
PROCEDURE Example;
PRIVATE ROUTINES PROCEDURE Example IS VARIABLES retCd : INTEGER; ACTIONS retCd := SQLSetOption('CASE CONVERSION', 2); END;
Code retour | Description |
1 | Opération exécutée avec succès. |
(autre) | Reportez-vous au manuel Tivoli Service Desk 6.0 Developer's Toolkit - Guide de programmation TSD Script. |
Met à jour la ligne indiquée, en y incorporant les valeurs des paramètres (variables de colonne).
SQLUpdate(tableName: STRING, queryString: STRING, parameters...] [,originalParameters...]): INTEGER;
Attention : Un appel à SQLUpdate pouvant mettre à jour de nombreuses lignes, définissez avec soin votre condition WHERE.
Nom d'argument | Description |
tableName | Nom de la table ou de la vue à mettre à jour. |
queryString | Clause Where. |
parameters | Liste de zéro ou plus paramètres (variables de colonne) séparés par des virgules, dont
les noms doivent correspondre aux noms des colonnes associées. Pour plus d'informations, reportez-vous à la section Remarques relative à cette instruction. |
originalParameters | Jeu de paramètres facultatif identique au premier jeu. Ces paramètres sont utilisés pour
le contrôle de l'accès concurrent passif. Pour plus d'informations, reportez-vous à la section Remarques relative à cette instruction. |
Le mot clé WHERE est facultatif dans la chaîne de requête. Les paramètres (variables de colonne) transmis à SQLUpdate doivent porter le même nom que les colonnes correspondantes de la table. Si le nom d'un paramètre ne correspond à aucun nom de colonne, ce paramètre est ignoré.
N'essayez pas de mettre à jour une colonne de table créée avec l'option NOT NULL avec un paramètre Tivoli Service Desk Developer's Toolkit dont la valeur est $Unknown. Vous pouvez transmettre un enregistrement en tant que paramètre. Dans ce cas, les noms des champs doivent correspondre aux noms des colonnes de la table, sous peine d'être ignorés.
Tivoli Service Desk Developer's Toolkit fournit un certain niveau de prise en charge des accès concurrents, sous la forme du mécanisme de contrôle passif des accès concurrents. Le contrôle passif des accès concurrents est une méthode simple mais efficace qui permet à plusieurs utilisateurs d'accéder à une table sans la verrouiller. Ce contrôle est dit passif car aucun verrouillage n'est activement appliqué lors de l'accès normal à un enregistrement.
Le contrôle passif des accès concurrents fonctionne de la manière suivante :
Remarque : Si un seul enregistrement est transmis, SQLUpdate ne procède à aucun contrôle passif des accès concurrents.
Il n'est pas obligatoire d'utiliser des enregistrements en tant que paramètres. Si vous utilisez le contrôle passif des accès concurrents, assurez-vous que l'ordre des deux jeux de paramètres est identique.
N'essayez pas de mettre à jour une colonne de table créée avec l'option NOT NULL avec un paramètre Tivoli Service Desk Developer's Toolkit dont la valeur est $Unknown.
KNOWLEDGEBASE Example; (* This example shows an update without passive concurrency. *)
--PUBLIC ROUTINES
FUNCTION Test:INTEGER;
PRIVATE ROUTINES
FUNCTION Test:INTEGER IS VARIABLES (* table columns *) age: INTEGER; (* misc *) retCd: INTEGER; ACTIONS age := 29;
(* Set all female employee's ages to 29 if they are 30 or over *) retCd := SQLUpdate('emp','age > 29',age); IF (retCd < 0) THEN EXIT retCd; END;
END;
Code retour | Description |
1 | Opération exécutée avec succès. |
(autre) | Reportez-vous au manuel Tivoli Service Desk 6.0 Developer's Toolkit - Guide de programmation TSD Script. |
Met à jour la ligne en cours du curseur en y incorporant les valeurs des paramètres (variables de colonne).
SQLUpdateCurrent(cursor: SQLCURSOR, paramètres): INTEGER;
Nom d'argument | Description |
cursor | Le curseur "cursor" doit être préalablement ouvert par un appel à SQLSelect. |
paramètres | Liste de zéro ou plus paramètres (variables de colonne) séparés par des virgules, dont
les noms doivent correspondre aux noms des colonnes associées. Pour plus d'informations, reportez-vous aux remarques. |
SQLUpdateCurrent n'est prise en charge que par le pilote DB2 CLI. Chaque colonne à mettre à jour doit être indiquée dans la clause FOR UPDATE OF de la chaîne de sélection (reportez-vous à la description de l'instruction SQLSelect).
Les paramètres (variables de colonne) transmis à SQLUpdateCurrent doivent porter le même nom que les colonnes correspondantes de la table. Si le nom d'un paramètre ne correspond à aucun nom de colonne, ce paramètre est ignoré. Vous pouvez transmettre un enregistrement sous forme de paramètre. Dans ce cas, les noms des champs doivent correspondre aux noms des colonnes de la table, sous peine d'être ignorés.
Remarque : Vous devez utiliser la clause FOR UPDATE OF... pour chaque colonne à mettre à jour.
N'essayez pas de mettre à jour une colonne de table créée avec l'option NOT NULL avec un paramètre Tivoli Service Desk Developer's Toolkit dont la valeur est $Unknown.
KNOWLEDGEBASE Example;
--PUBLIC ROUTINES
FUNCTION Test(REF age: INTEGER):INTEGER;
PRIVATE ROUTINES
FUNCTION Test(REF age: INTEGER):INTEGER IS VARIABLES (* columns *) name: STRING; (* misc *) cursor: SQLCursor; retCd: INTEGER; ACTIONS SQLBeginWork; (* start a transaction *)
(* select all employees from Indiana, and whose age is greater *) (* than the age passed into this function. *) retCd := SQLSelect(cursor,'name from emp WHERE (state = ''IN'') AND ' & '(age > ' & age & ') FOR UPDATE OF NAME'); IF (retCd < 0) THEN SQLRollBack; (* must terminate the transaction *) EXIT retCd; END;
retCd := SQLFetch(cursor,name); WHILE (retCd > 0) DO (* possibly perform some operations based on "name" . . . *)
(* set name to uppercase *) name := StrUpper(name);
(* now update this row *) retCd := SQLUpdateCurrent(cursor,name); IF (retCd < 0) THEN SQLCloseCursor(cursor); SQLRollback; (* reverse any changes, and release locks *) EXIT retCd; END;
(* get the next record *) retCd := SQLFetch(cursor); END;
SQLCloseCursor(cursor); SQLCommit; (* commit changes and release locks *) END;
Code retour | Description |
1 | Opération exécutée avec succès. |
(autre) | Reportez-vous au manuel Tivoli Service Desk 6.0 Developer's Toolkit - Guide de programmation TSD Script. |
Tivoli Service Desk 6.0 Developer's Toolkit Script - Manuel de référence du langage TSD Script