Tivoli Service Desk 6.0 Developer's Toolkit - Referência da Linguagem de Script
O Tivoli Service Desk (TSD) usa um produto de recuperação de textos da IBM chamado Intelligent Miner for Text (IM4T) para criar índices para tabelas em seu banco de dados. Os índices que ele cria podem ser usados por seus analistas de serviços para encontrar rapidamente entradas específicas (arquivos ou documentos pré-existentes) no banco de dados que contêm certas palavras ou combinações de palavras. Os índices não afetam o formato original em que os dados estão armazenados.
Esta seção descreve como:
O IM4T está incluído no software do TSD e não há taxa adicional de licença para sua utilização.
O IM4T usa arquitetura cliente/servidor para indexação de tabelas do banco de dados. Todos os
índices são criados e mantidos em um único servidor. Cada estação de trabalho cliente que estiver utilizando TPM configura-se a si mesmo como um cliente daquele servidor.
Antes de usar a capacidade de recuperação de texto do TSD é necessário criar e
configurar um servidor para seus índices. O primeiro passo para esse processo é instalar o TSD
na máquina designada para ser seu servidor IM4T. É necessário instalar o pacote intitulado
"IM4T Server Installation." Para configurar um servidor IM4T proceda da
seguinte maneira:
Resultado: A janela Manutenção do IMT do Tivoli Service Desk será aberta. Preencha os campos da seguinte maneira:
Seção/Campo | Informações Necessárias |
Nome | Nome do servidor |
Seção de Informações sobre a Conexão | |
Host | Nome do IP de seu computador |
Porta | Número da porta. É necessário criar uma entrada no arquivo etc/services para este servidor. Nota: Este número deve ser para uma porta que não esteja sendo usada por nenhum outro programa na sua LAN. |
Seção de Informações sobre a Tarefa | |
Máximo | Número máximo (entre 1 e 100) de tarefas que o serviço de pesquisa pode identificar simultaneamente |
Tempo limite | Tempo exigido pelo serviço de pesquisa receber informações do cliente |
Disponível | Número de tarefas a serem iniciadas na inicialização do servidor. |
Você deve administrar índices apenas nas máquinas que estiverem configuradas como servidor do IM4T.
Nota: Em sistemas operacionais Unix, será necessário também estar com sessão
iniciada na conta administrativa imoadm que foi criada quando o TSD foi
instalado.
Você pode criar índices executando o Utilitário de Administração de Recuperação de Texto do TSD (tsd_text.kbc). Este é o mesmo utilitário usado para configurar o servidor.
O utilitário primeiro pedirá que você inicie sessão na origem de dados do TSD para o qual você estará criando os índices. Se você iniciar sessão a uma origem de dados para o qual nenhum servidor IM4T estiver configurado, o utilitário pedirá que você faça isso antes.
Depois de ter iniciado sessão e ter configurado o servidor, você verá a tela principal do utilitário intitulado, "Manutenção do IM4T do Tivoli Service Desk."
O utilitário tsd_text constrói índices das colunas Descrição ou Solução que ocorrem em certos tipos de registros de auxílio para diagnóstico Tivoli Problem Management (TPM). Quando existir
um grande número de registros no banco de dados, pode ser mais rápido usar o IM4T para
localizar registros de auxílio para diagnóstico específicos do que usar as caixas Descrição ou Solução disponíveis
em uma caixa de diálogo Consulta.
A pesquisa de texto pode estar disponível nestas caixas de diálogo:
Nota:
Este utilitário tsd_text também é usado para construir índices de problemas, alterações e descrições que são usados durante a análise de impacto no Tivoli Change Management. Consulte Como Desempenhar Análise de Impacto para obter mais detalhes.Com o IM4T, você pode criar novos índices e atualizar índices existentes. Em alguns casos, pode ser necessário excluir um índice. Criar, atualizar e excluir índices pode gastar um tempo significativo, dependendo do tamanho do seu banco de dados. Se sua mesa de auxílio não estiver ativa durante a noite, considere a possibilidade de iniciar atividades de manutenção em índices do IM4T no final do dia.
É necessário criar índices antes que o analista da mesa de auxílio possa usar as funções do Text Inquiry disponíveis nestas caixas de diálogos de Consulta: Consulta de Problemas Comuns, Consulta de Mensagens de Erro, Consulta de Hot News e Consulta de Soluções.
Para garantir que os analistas da mesa de auxílio pesquisem as descrições de soluções e problemas mais recentes, é necessário atualizar seus índices regularmente. Como o processo de atualização pode gastar um tempo significativo, considere a possibilidade de iniciá-la no final do dia. Depois que o processo tiver iniciado, pode ficar não-assistido.
Algumas vezes você pode querer excluir um índice do IM4T. Se um índice parecer estar danificado, exclua-o e crie-o novamente. Os dados do Banco de Dados não são excluídos quando você exclui um índice.
O objetivo de consultar um índice de textos do banco de dados é localizar rapidamente campos no banco de dados. Como ajuda para isso, o comando SQLSelect procura e age na presença de uma seqüência de escape especial, $TextSearch. Essa seqüência permite uma consulta a um índice do Text Retrieval e ao banco de dados. (Uma entrada válida em uma seqüência $TextSearch é uma cláusula WHERE válida para uma origem de dados do Text Retrieval). Revise os exemplos a seguir. Selecionar todas as soluções relacionadas com manutenção de hardware.
Select * from solutions where $TextSearch (contains 'hardware' & 'maintenance')
Selecionar todas as soluções ativas relacionadas com manutenção de hardware.
Select * from solutions where $TextSearch (contains 'hardware' & 'maintenance') AND Active = 1
Se existirem vários índices do Text Retrieval associados a uma única tabela de um banco de dados, é necessário especificar o nome do índice na cláusula $TextSearch. O nome do índice deve preceder a consulta e ser seguido de ponto e vírgula (;).
Select * from solutions where $TextSearch (solNDX; description contains 'hardware') AND Active = 1 OR solution_id > 3000
Para configurar um servidor do IM4T proceda da seguinte maneira:
Seção/Campo | Informações Necessárias |
Serviço de Pesquisa | Nome da ocorrência de serviço (mesmo que informações sobre o servidor) |
Host | Nome do IP do servidor do IM4T. |
Porta | Número da porta. Nota: Este número deve ser para uma porta que não esteja sendo usada por nenhum outro programa na sua LAN. Este número será o mesmo que o número da porta do servidor. |
Botão Avançado | Permite definir opções avançadas |
Esta seção é uma referência a funções comuns de recuperação de documentos utilizados com o IM4T.
FUNCTION FTRSQLTextIndexCreate(IndexName : STRING, Fields : LIST OF IndexFieldRec) : INTEGER;
O IndexName deve ter no máximo oito caracteres. O tipo IndexFieldRec é declarado da seguinte forma:
IndexFieldRec IS RECORD TableName : STRING; --Name of the table to be indexed FieldName : STRING; --Name of the field to be indexed Flags : INTEGER; --Combination of KEY, VALUE,LITERAL, and LONGCHAR END;
Esse registro é definido em ftr.kb.
As definições de sinalizadores em IndexFieldRec são relacionadas na tabela a seguir.
Sinalizador |
Descrição |
SAI_DBTRNDX_KEY | Um campo de chaves na tabela do banco de dados. Pelo menos um IndexFieldRec passado para FTRSQLTextIndexCreate deve ter esse conjunto de sinalização. SAI_DBTRNDX_VALUE indica que a coluna contém um valor numérico. |
SAI_DBTRNDX_LITERAL | Indica que a coluna contém um valor literal (normalmente uma cadeia) |
AI_DBTRNDX_LONGCHAR | Indica que a coluna contém uma cadeia de caracteres (normalmente um campo de texto longo). Pelo menos um IndexFieldRec passado para FTRSQLTextIndexCreate deve ter esse conjunto de sinalização. |
Nota: Os índices de texto do banco de dados devem conter cada campo de chave principal da tabela que está sendo indexado, e no mínimo um campo do tipo LONGCHAR.
Com base nos dados recebidos, FTRSQLTextIndexCreate cria um índice com as seguintes características: todos os campos são indexados e pode-se fazer referência a eles como parte da coluna de texto da tabela de índice. Todos os campos Chave são armazenados em sua própria coluna na tabela de índice. Por exemplo:
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;
Códigos de Retorno |
Descrição |
1 | Êxito |
2001 | DBTR ERR INVALID TABLE NAME |
2002 | DBTR ERR INVALID INDEX NAME |
2003 | DBTR ERR INVALID INDEX FIELD |
(outro) | Código de Erro (Refere-se a Mensagens de Sucesso/Erro do IM4T) |
FUNCTION FTRSQLTextIndexDelete(IndexName : STRING) : INTEGER;
Função | Descrição |
IndexName | Especifica o nome de um índice de texto do banco de dados a ser excluído |
FTRSQLTextIndexDelete encontra o índice especificado e o exclui. Por exemplo:
FTRSQLTextIndexDelete(`DEFNDX');
Códigos de Retorno |
Descrição |
1 | Êxito |
2002 | DBTR_ERR_INVALID_INDEX_NAME |
(outro) | Código de Erro (Refere-se a Mensagens de Sucesso/Erro do IM4T) |
FUNCTION FTRSQLTextIndexUpdate(IndexName : STRING, Method : INTEGER) : INTEGER;
Função | Descrição |
IndexName | Especifica o nome do índice a ser atualizado |
Método | Especifica se o índice é atualizado ou
recriado desde o início.
Essa variável pode ter um desses dois valores:
|
FTRSQLTextIndexUpdate encontra o índice especificado e executa a ação especificada em Método. Por exemplo:
FTRSQLTextIndexUpdate (`DEFNDX', SAI_NDX_REBUILD);
Códigos de Retorno |
Descrição |
1 | Êxito |
2002 | DBTR ERR INVALID INDEX NAME |
(outro) | Código de Erro (Refere-se a Mensagens de Sucesso/Erro do IM4T) |
FUNCTION FTRSQLTextIndexUpdateAll(Method : INTEGER):INTEGER;
O Método especifica se os índices são atualizados ou recriados desde o início. Essa variável pode ter um desses dois valores:
SAI_NDX_UPDATE é o padrão. Se os índices já existirem, são atualizados para incluir alterações nos dados. Se os índices ainda não existirem (isso é, estiverem apenas definidos), são criados nesse ponto.
SAI_NDX_REBUILD cria índices, sejam eles existentes ou não.
FTRSQLTextIndexUpdateAll atualiza cada índice de banco de dados existentes na origem dos dados atual utilizando o método definido em Método. Exemplo:
FTRSQLTextIndexUpdateAll(SAI_NDX_REBUILD);
Códigos de Retorno |
Descrição |
1 | Êxito |
(outro) | Código de Erro (Refere-se a seção de Mensagens de Sucesso/Erro do IM4T) |
FTRSQLSetFilterWhere (IndexName : STRING , WhereStmt : STRING) : INTEGER;
Esta função definirá o Filtro Where de um índice, se o índice existir .
ret:=FTRSQLSetFilterWhere('MYINDEX', 'USER_ID>10000');
Códigos de Retorno |
Descrição |
1 | Êxito |
2002 | DBTR ERR INVALID INDEX NAME |
2005 | DBTR ERR NVALID WHERE STATEMENT |
(outro) | Código de Erro (Refere-se a seção de seção de Mensagens de Sucesso/Erro do IM4T) |
FTRSQLGetFilterWhere (IndexName : STRING, WhereStmt : STRING) : INTEGER;
Esta função conseguirá o Filtro Where de um índice se existir um filtro Where.
WhereStmt : STRING;
Códigos de Retorno |
Descrição |
1 | Êxito |
2002 | DBTR ERR INVALID INDEX NAME |
(outro) | Código de Erro (Refere-se a seção de seção de Mensagens de Sucesso/Erro do IM4T) |
Sintaxe
FTRSQLDeleteFileterWhere (WhereStmt : STRING) : INTEGER;
Esta função excluirá o Filtro Where de um índice se o índice existir.
ret:=FTRSQLDeleteFilterWhere('MYINDEX');
Códigos de Retorno |
Descrição |
1 | Êxito |
2002 | DBTR ERR INVALID INDEX NAME |
(outro) | Código de Erro (Refere-se a seção de seção de Mensagens de Sucesso/Erro do IM4T) |
Sintaxe
FTRListIndexes (Servername : STRING , ResultList : LIST OF STRINGS ) : INTEGER;
Esta função listará todos os índices disponíveis de um servidor.
IdxList:LIST OF STRING; ret:=FTRListIndexes('MYSRVR',IdxList);
Códigos de Retorno |
Descrição |
1 | Êxito |
2002 | DBTR ERR INVALID INDEX NAME |
(outro) | Código de Erro (Refere-se a seção de seção de Mensagens de Sucesso/Erro do IM4T) |
FTRSQLTextIndexCreate
O exemplo a seguir é um índice para a tabela de Soluções do Tivoli Problem Management (TPM) e exibe
a mensagem de Sucesso/Erro da chamada.
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;
A seguir é apresentado um exemplo de código de uma consulta no índice.
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;
Código de Erro | Mensagem de Erro |
-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 |
Código de Aviso | Mensagem de Aviso |
-17510 | SQLWARN_CFG_NULL_ITEM |
-17511 | SQLWARN_TEXTMINER_CLEANUP_ERROR |
-17512 | SQLWARN_PARTIAL_FAILURE |
Para obter mais informações, consulte a documentação do Intelligent Miner for Text (IM4T):
http://www.software.ibm.com/data/iminer/fortext
Tivoli Service Desk 6.0 Developer's Toolkit - Referência da Linguagem de Script