Tivoli Service Desk 6.0 Developer's Toolkit - Manuel de référence du langage TSD Script
Tivoli Service Desk (TSD) exploite un logiciel d'extraction de texte appelé IM4T (Intelligent Miner for Text), qui crée des index de tables dans votre base de données. Ces index peuvent être générés par les analystes TSD dans le but de localiser rapidement des entrées particulières (fichiers de données ou documents pré-existants) situées dans la base de données et contenant certains mots ou combinaisons de mots. Les index n'affectent en aucune manière le format initial sous lequel les données ont été enregistrées à l'origine.
Cette section décrit comment :
IM4T fait partie intégrante du logiciel TSD et sont utilisation ne
requiert aucun droit de licence supplémentaire.
IM4T gère l'indexation des tables de base de données au moyen d'une
architecture client/serveur. Tous les index sont créés et maintenus
sur un serveur unique. Chacun des postes de travail clients qui
exécutent le logiciel TPM se configure automatiquement comme un
client dépendant de ce serveur.
Avant d'être en mesure d'exploiter les fonctions d'extraction de
TSD, vous devez créer et configurer un serveur destiné à accueillir
les index. La première étape de cette procédure consiste à installer
TSD sur le poste désigné comme serveur IM4T. Vous devez procéder à
l'installation du composant intitulé "Installation du serveur
IM4T". Pour configurer un serveur IM4T, procédez de la manière
suivante :
Résultat : La fenêtre de l'utilitaire IM4T Maintenance de Tivoli Service Desk s'affiche. Renseignez les champs comme suit :
Section/Champ | Informations obligatoires |
Nom | Nom du serveur |
Section relative aux informations de connexion | |
Hôte | Nom IP de votre machine |
Port | Numéro de port. Il convient d'ajouter une entrée réservée au serveur dans le fichier etc/services. Remarque : Le numéro de port doit être différent de celui de tous les autres programmes hébergés sur le réseau local. |
Section relative aux informations sur les tâches | |
Maximum | Nombre maximal (compris entre 1 et 100) de tâches pouvant être traitées simultanément par le service de recherche |
Délai | Temps nécessaire au service de recherche pour recevoir les informations en provenance du client |
Disponible | Nombre de tâches à lancer lors du démarrage du serveur. |
La gestion des index doit être effectuée sur le poste ayant servi
à configurer le serveur IM4T.
Remarque : Sur les systèmes d'exploitation Unix,
vous devez également vous connecter au compte d'administration
imoadm créé au moment de l'installation
de TSD.
Vous pouvez créer des index en exécutant l'utilitaire TSD Text Retrieval Administration Utility (tsd_text.kbc). Il s'agit du même utilitaire que celui ayant servi à la configuration du serveur.
Cet utilitaire vous invite en premier lieu à vous connecter à la source de données TSD pour laquelle vous souhaitez créer des index. Si vous vous connectez à une source de données pour laquelle aucun serveur IM4T n'a été configuré, l'utilitaire vous invite à effectuer d'abord cette opération.
Une fois la connexion établie et le serveur configuré, l'écran principal de l'utilitaire "Tivoli Service Desk - IM4T Maintenance." s'affiche.
L'utilitaire tsd_text élabore des index correspondant aux
colonnes Description ou Solution qui apparaissent dans certains
enregistrements d'aide au diagnostic de Tivoli Problem Management
(TPM). Lorsque la base de données commence à contenir
un nombre important d'enregistrement, vous pouvez mettre à profit
IM4T pour localiser les enregistrements d'aide au diagnostic, plutôt
au lieu de parcourir les cases Description ou Solution indiquées par
une boîte de dialogue de requête.
La recherche du texte est accessible dans les boîtes de dialogue
suivantes :
Remarque
: L'utilitaire tsd_text peut également servir à élaborer des index concernant les incidents, les modifications et les descriptions utilisés lors de l'analyse des incidences avec Tivoli Change Management. Pour plus d'informations, reportez-vous à la section Exécution de l'analyse de l'incidence.IM4T vous permet de créer de nouveaux index et de mettre à jour ceux qui existent déjà. Dans certains cas, il peut vous arriver d'avoir à supprimer un index. Les opérations de création, de mise à jour de suppression d'index sont plus ou moins longues à réaliser, suivant la taille de votre base de données. Si vous ne disposer d'aucun service d'assistance durant la nuit, il peut être judicieux de commencer la mise en oeuvre des activités de gestion d'index IM4T en fin de journée.
Les index doivent être créés avant que les analystes du service d'assistance ne fassent appel aux fonctions d'interrogation de texte fournies par les boîtes de dialogue d'interrogation : Interrogation des incidents fréquents, Interrogation des messages d'erreur, Interrogation des dernières nouvelles et Interrogation des solutions.
Afin de veiller à ce que les analystes du service d'assistance recherchent toujours les descriptions d'incidents et de solutions les plus récentes, vous devez procéder à des mises à jour régulières des index. Compte tenu du temps que peuvent nécessiter ces mises à jour, il convient de les effectuer de préférence en fin de journée. Une fois que le processus est lancé, vous pouvez le laisser se dérouler sans assistance.
Il peut vous arriver occasionnellement d'avoir à supprimer un index IM4T. Lorsqu'un index est altéré, vous pouvez le détruire, puis le recréer. La suppression d'un index n'entraîne pas celle des informations contenues dans la base de données.
L'interrogation de l'index de texte d'une base de données a pour objet de retrouver rapidement les champs dans une base. Pour cela, la commande SQLSelect effectue la recherche et ne fonctionne que lors de la séquence d'échappement $TextSearch. Cette séquence permet de lancer une requête dans l'index d'extraction de texte, ainsi que dans la base de données (La clause WHERE de la source de données d'extraction de texte est une entrée valide pour la séquence $TextSearch). Prenez connaissance des exemples ci-après : Sélectionnez toutes les solutions concernant la maintenance du matériel.
Select * from solutions where $TextSearch (contains 'hardware' & 'maintenance')
Sélectionnez toutes les solutions actives concernant la maintenance du matériel.
Select * from solutions where $TextSearch (contains 'hardware' & 'maintenance') AND Active = 1
Si plusieurs index Text sont associés à une seule table de la base de données, vous devez indiquer le nom de l'index dans la clause de $TextSearch. Le nom de l'index doit précéder la requête et être suivi d'un point virgule (;).
Select * from solutions where $TextSearch (solNDX; description contains 'hardware') AND Active = 1 OR solution_id > 3000
Pour configurer un serveur IM4T, procédez de la manière suivante :
Section/Champ | Informations obligatoires |
Fonction de recherche | Nom de l'instance de la fonction (identique aux informations du serveur) |
Hôte | Nom IP du serveur IM4T |
Port | Numéro de port. Remarque : Le numéro de port doit être différent de celui de tous les autres programmes hébergés sur le réseau local. Il doit s'agir du même numéro de port que celui du serveur. |
Boutons Avancé | Vous permet de définir les options avancées |
Cette section concerne les fonctions d'extraction d'un document courant à l'aide de IM4T.
FUNCTION FTRSQLTextIndexCreate(IndexName : STRING, Fields : LIST OF IndexFieldRec) : INTEGER;
L'argument IndexName ne doit pas dépasser huit caractères. Le type d'argument IndexFieldRec est déclaré de la manière suivante :
IndexFieldRec IS RECORD TableName : STRING; -- Nom de la table à indexer FieldName : STRING; -- Name du champ à indexer Flags : INTEGER; -- Combinaison de KEY, VALUE,LITERAL et LONGCHAR END;
Cet enregistrement est défini dans ftr.kb.
Les définitions des indicateurs dans IndexFieldRec sont disponibles dans le tableau ci-dessous.
Indicateur |
Description |
SAI_DBTRNDX_KEY | Champ clé dans la table de la base de données. Au moins un IndexFieldRec transmis à FTRSQLTextIndexCreate doit avoir cet indicateur. SAI_DBTRNDX_VALUE indique que la colonne contient une valeur numérique. |
SAI_DBTRNDX_LITERAL | Indique que la colonne contient une valeur littérale (généralement une chaîne) |
AI_DBTRNDX_LONGCHAR | Indique que la colonne contient une chaîne de caractères (généralement un champ pouvant contenir beaucoup de texte). Au moins un IndexFieldRec transmis à FTRSQLTextIndexCreate doit avoir cet indicateur. |
Remarque : Les index de texte de la base de données doivent avoir chaque champ de clé primaire de la table indexée, ainsi qu'au moins un champ de type LONGCHAR.
En se basant sur les données qu'il reçoit, FTRSQLTextIndexCreate crée un index ayant les caractéristiques suivantes : tous les champs sont indexés et peuvent être référencés comme faisant partie de la colonne texte dans l'index de la table. Tous les champs clé sont enregistrés dans leur propre colonne d'index. Voir l'exemple ci-dessous.
VARIABLES NewIndex : LIST OF IndexFieldRec; Entry : IndexFieldRec; ACTIONS Entry.TableName = `EQ_Defects'; Entry.FieldName = `Defect_Title'; Entry.Flags = SAI_DBTRNDX_LITERAL; ListInsert(NewIndex,Entry); Entry.TableName = `EQ_Defects'; Entry.FieldName = `Defect_Desc_Text'; Entry.Flags = SAI_DBTRNDX_LONGCHAR; ListInsert(NewIndex, Entry); Entry.TableName = `EQ_Defects'; Entry.FieldName = `Defect_Steps_Text'; Entry.Flags = SAI_DBTRNDX_LONGCHAR; ListInsert(NewIndex, Entry); Entry.TableName = `EQ_Defects'; Entry.FieldName =`Defect_Title'; Entry.Flags = BitOr(SAI_DBTRNDX_KEY, SAI_DBTRNDX_VALUE); ListInsert(NewIndex, Entry); FTRSQLTextIndexCreate(`DefNDX', NewIndex); END;
Codes retour |
Description |
1 | Opération exécutée avec succès. |
2001 | ERREUR DBTR - NOM DE TABLE INCORRECT |
2002 | ERREUR DBTR - NOM D'INDEX INCORRECT |
2003 | ERREUR DBTR - CHAMP D'INDEX NON VALIDE |
(autre) | Code d'erreur (Reportez-vous à la section IM4T - Messages de réussite/erreur) |
FUNCTION FTRSQLTextIndexDelete(IndexName : STRING) : INTEGER;
Fonction | Description |
IndexName | Indique le nom de l'index de texte de la base de données à supprimer |
FTRSQLTextIndexDelete trouve l'index recherché et le laisse inchangé. Voir l'exemple ci-dessous.
FTRSQLTextIndexDelete(`DEFNDX');
Codes retour |
Description |
1 | Opération exécutée avec succès. |
2002 | DBTR_ERR_INVALID_INDEX_NAME |
(autre) | Code d'erreur (Reportez-vous à la section IM4T - Messages de réussite/erreur) |
FUNCTION FTRSQLTextIndexUpdate(IndexName : STRING, Method : INTEGER) : INTEGER;
Fonction | Description |
IndexName | Indique le nom de l'index à mettre à jour |
Method | Indique si l'index a été mis à jour
ou recréé après avoir été effacé.
Cette variable peut avoir l'une des deux
valeurs suivantes :
|
FTRSQLTextIndexUpdate trouve l'index recherché et
effectue l'opération définie dans la méthode. Voir l'exemple ci-dessous.
FTRSQLTextIndexUpdate (`DEFNDX', SAI_NDX_REBUILD);
Codes retour |
Description |
1 | Opération exécutée avec succès. |
2002 | ERREUR DBTR - NOM D'INDEX INCORRECT |
(autre) | Code d'erreur (Reportez-vous à la section IM4T - Messages de réussite/erreur) |
FUNCTION FTRSQLTextIndexUpdateAll(Method : INTEGER):INTEGER;
Method indique si les index ont été mis à jour ou recréés après avoir été effacés. Cette variable peut avoir l'une des deux valeurs suivantes :
SAI_NDX_UPDATE est la valeur par défaut. Si les index existent déjà, ils sont mis à jour pour prendre en compte les changements dans les données. S'ils n'existent pas encore (c'est-à-dire qu'ils ne sont que définis), ils sont créés à ce moment-là.
SAI_NDX_REBUILD crée des index, qu'ils aient existé ou non.
FTRSQLTextIndexUpdateAll met à jour chaque index de texte de la base existant dans la source de données courante selon la méthode définie dans Method. Exemple :
FTRSQLTextIndexUpdateAll(SAI_NDX_REBUILD);
Codes retour |
Description |
1 | Opération exécutée avec succès. |
(autre) | Code d'erreur (Reportez-vous à la section IM4T - Messages de réussite/erreur) |
FTRSQLSetFilterWhere (IndexName : STRING , WhereStmt : STRING) : INTEGER;
Cette fonction applique le filtre Where à un index, si ce dernier existe.
ret:=FTRSQLSetFilterWhere('MYINDEX', 'USER_ID>10000');
Codes retour |
Description |
1 | Opération exécutée avec succès. |
2002 | ERREUR DBTR - NOM D'INDEX INCORRECT |
2005 | ERREUR DBTR - INSTRUCTION 'WHERE' NON VALIDE |
(autre) | Code d'erreur (Reportez-vous à la section IM4T - Messages de réussite/erreur) |
FTRSQLGetFilterWhere (IndexName : STRING, WhereStmt : STRING) : INTEGER;
Cette fonction applique le filtre Where à un index, si ce filtre Where existe.
WhereStmt : STRING;
Codes retour |
Description |
1 | Opération exécutée avec succès. |
2002 | ERREUR DBTR - NOM D'INDEX INCORRECT |
(autre) | Code d'erreur (Reportez-vous à la section IM4T - Messages de réussite/erreur) |
Syntaxe
FTRSQLDeleteFileterWhere (WhereStmt : STRING) : INTEGER;
Cette fonction supprime le filtre Where d'un index, si ce dernier existe.
ret:=FTRSQLDeleteFilterWhere('MYINDEX');
Codes retour |
Description |
1 | Opération exécutée avec succès. |
2002 | ERREUR DBTR - NOM D'INDEX INCORRECT |
(autre) | Code d'erreur (Reportez-vous à la section IM4T - Messages de réussite/erreur) |
Syntaxe
FTRListIndexes (Servername : STRING , ResultList : LIST OF STRINGS ) : INTEGER;
Cette fonction dresse la liste de tous les index disponibles dans un serveur.
IdxList:LIST OF STRING; ret:=FTRListIndexes('MYSRVR',IdxList);
Codes retour |
Description |
1 | Opération exécutée avec succès. |
2002 | ERREUR DBTR - NOM D'INDEX INCORRECT |
(autre) | Code d'erreur (Reportez-vous à la section IM4T - Messages de réussite/erreur) |
FTRSQLTextIndexCreate
L'exemple ci-après est un index de la table Tivoli Problem Management
(TPM) Solutions, dans laquelle s'affiche le message
d'erreur/de
réussite de l'appel.
KNOWLEDGEBASE MakeNDX;
USES TEXTRET;
ROUTINES
PROCEDURE TestMain;
PRIVATE
ROUTINES
PROCEDURE TestMain IS
VARIABLES
Col : IndexFieldRec;
ColList : LIST OF IndexFieldRec;
Lines : List of String;
nRC : Integer;
whdl : Window;
ACTIONS
SQLCommand(`connect TOOLKIT');
Col.TableName := 'solutions';
Col.FieldName := 'solution_id';
Col.Flags := BitOr (SAI_DBTRNDX_VALUE,
SAI_DBTRNDX_KEY);
ListPush(ColList, Col);
Col.TableName := 'dbo.solutions';
Col.FieldName := 'description';
Col.Flags := SAI_DBTRNDX_LONGCHAR;
ListPush(ColList, Col);
nRC := FTRSQLTextIndexCreate('solndx', ColList);
ListInsert(Lines, nRC, $BEFORE);
WinCreateScrollWindow($Desktop, whdl,
$NullHandler,
5,5,50,15,
'Create Index',
$SystemMonospaced,
10,
$WinDefaultStyle);
WinWriteLN(whdl, Lines);
WinWait(whdl);
END;
Ce qui suit est un exemple de code dans une requête d'index.
KNOWLEDGEBASE querysol; ROUTINES PROCEDURE TestMain; PRIVATE ROUTINES PROCEDURE TestMain IS VARIABLES Lines : List of String; nRC : Integer; whdl : Window; cursor : SQLCURSOR; System : String; ACTIONS nRC := SQLCommand('CONNECT ADVISOR'); IF (nRC <> 1) THEN EXIT; END; ListInsert(Lines, nRC, $BEFORE); nRC := SQLSelect(cursor, 'SELECT SYSTEM FROM SOLUTIONS WHERE $TextSearch(SOLNDX;DESCRIPTION CONTAINS ''PROBLEM'')'); ListInsert(Lines, nRC, $BEFORE); nRC := SQLFetch(cursor, System); WHILE (nRC = 1) DO ListInsert(Lines, System, $BEFORE); nRC := SQLFetch(cursor, System); END; ListInsert(Lines, nRC, $BEFORE); SQLCloseCursor(cursor); WinCreateScrollWindow($Desktop, whdl, $NullHandler, 5,5,50,15, 'Query Index', $SystemMonospaced, 10, BitOr($WinDefaultStyle, $WinVScroll)); WinWriteLN(whdl, Lines); WinWait(whdl); END;
Code d'erreur | Message d'erreur |
-17407 | SQLERR_NO_KEY |
-17408 | SQLERR_NO_LONGCHAR |
-17409 | SQLERR_COL_TYPE_CONFLICT |
-17410 | SQLERR_INDEX_NAME_NOT_FOUND |
-17411 | SQLERR_BAD_KEY_TYPE |
-17415 | SQLERR_TR_NOT_INITIALIZED |
-17417 | SQLERR_INVALID_TEXTSEARCH |
-17420 | SQLERR_INVALID_INDEX_NAME |
-17424 | SQLERR_TEXTMINER_DATA_BUILD |
-17425 | SQLERR_CANT_DETERMINE_SERVER_LOCATION |
-17426 | SQLERR_SECTION_FILE_SYNTAX_ERROR |
-17427 | SQLERR_DEFINITION_FILE_SYNTAX_ERROR |
-17428 | SQLERR_CANT_OPEN_FILE |
-17429 | SQLERR_CANT_WRITE_FILE |
-17430 | SQLERR_CANT_READ_FILE |
-17431 | SQLERR_TABLE_NAME_NOT_SET |
-17432 | SQLERR_ENVIRONMENT_VARIABLE_NOT_SET |
-17433 | SQLERR_INVALID_REMOTE_PROCEDURE |
-17434 | SQLERR_MISSING_LANGUAGE |
-17435 | SQLERR_CANT_GET_CODEPAGE |
-17700 | SQLERR_NOT_ENOUGH_MEMORY |
-17701 | SQLERR_DICTIONARY_NOT_FOUND |
-17702 | SQLERR_STOPWORD_IGNORED |
-17703 | SQLERR_CCS_NOT_SUPPORTED |
-17704 | SQLERR_LANGUAGE_NOT_SUPPORTED |
-17705 | SQLERR_CONFLICT_WITH_INDEX_TYPE |
-17706 | SQLERR_INVALID_MASKING_SYMBOL |
-17707 | SQLERR_INDEX_GROUP_SEARCH_ERROR |
-17708 | SQLERR_INDEX_SPECIFIC_ERROR |
-17709 | SQLERR_UNEXPECTED_ERROR |
-17710 | SQLERR_DATASTREAM_SYNTAX_ERROR |
-17711 | SQLERR_UNKNOWN_SESSION_POINTER |
-17712 | SQLERR_PROCESSING_LIMIT_EXCEEDED |
-17713 | SQLERR_REQUEST_IN_PROGRESS |
-17714 | SQLERR_MAX_NUMBER_OF_RESULTS |
-17715 | SQLERR_SERVER_NOT_AVAILABLE |
-17716 | SQLERR_SERVER_BUSY |
-17717 | SQLERR_SERVER_CONNECTION_LOST |
-17718 | SQLERR_INDEX_DELETED |
-17719 | SQLERR_INDEX_SUSPENDED |
-17720 | SQLERR_INDEX_NOT_ACCESSIBLE |
-17721 | SQLERR_EMPTY_QUERY |
-17722 | SQLERR_EMPTY_INDEX |
-17723 | SQLERR_FUNCTION_DISABLED |
-17724 | SQLERR_FUNCTION_IN_ERROR |
-17725 | SQLERR_INSTALLATION_PROBLEM |
-17726 | SQLERR_COMMUNICATION_PROBLEM |
-17727 | SQLERR_IO_PROBLEM |
-17728 | SQLERR_WRITE_TO_DISK_ERROR |
-17729 | SQLERR_MAX_NUMBER_OF_BUSY_INDEXES |
-17730 | SQLERR_UNKOWN_SECTION_NAME |
-17731 | SQLERR_DOCMOD_READ_PROBLEM |
-17732 | SQLERR_INCORRECT_AUTHENTICATION |
-17733 | SQLERR_CONFLICTING_TASK_RUNNING |
-17734 | SQLERR_NO_ACTION_TAKEN |
-17735 | SQLERR_LS_NOT_EXECUTABLE |
-17736 | SQLERR_LS_FUNCTION_FAILED |
-17737 | SQLERR_MAX_NUMBER_OF_TASKS |
-17738 | SQLERR_MISSING_DEFAULT_MODEL |
-17739 | SQLERR_UNKNOWN_DOCUMENT_MODEL-NAME |
-17740 | SQLERR_MEMBER_OF_INDEX_GROUP |
-17741 | SQLERR_UNKNOWN_INDEX_NAME |
-17742 | SQLERR_INDEX_ALREADY_OPENED |
-17743 | SQLERR_MAX_NUMBER_OF_OPEN_INDEXES |
-17744 | SQLERR_CONTINUATION_MODE_ENTERED |
-17745 | SQLERR_EMPTY_LIST |
-17746 | SQLERR_SERVER_IN_ERROR |
-17747 | SQLERR_FUNCTION_NOT_SUPPORTED |
-17748 | SQLERR_UNKNOWN_INDEX_TYPE |
-17749 | SQLERR_INCORRECT_INDEX_NAME |
-17750 | SQLERR_INCORRECT_LS_EXECUTABLES |
-17751 | SQLERR_INCORRECT_LIBRARY_ID |
-17752 | SQLERR_INCORRECT_LOCATION |
-17753 | SQLERR_INDEX_ALREADY_EXISTS |
-17754 | SQLERR_MAX_NUMBER_OF_INDEXES |
-17755 | SQLERR_LOCATION_IN_USE |
-17756 | SQLERR_UNKNOWN_SERVER_NAME |
-17757 | SQLERR_UNKNOWN_COMMUNICATION_TYPE |
-17758 | SQLERR_UNKNOWN_SERVER_INFORMATION |
-17759 | SQLERR_INCORRECT_HANDLE |
-17760 | SQLERR_QUERY_TOO_COMPLEX |
Code de l'avertissement | Message d'avertissement |
-17510 | SQLWARN_CFG_NULL_ITEM |
-17511 | SQLWARN_TEXTMINER_CLEANUP_ERROR |
-17512 | SQLWARN_PARTIAL_FAILURE |
Pour plus d'informations reportez-vous à la documentation fournie
avec Intelligent Miner for Text (IM4T) à l'adresse suivante :
http://www.software.ibm.com/data/iminer/fortext
Tivoli Service Desk 6.0 Developer's Toolkit - Manuel de référence du langage TSD Script