Tivoli Service Desk 6.0 Developer's Toolkit - Guia do Criador de Interface
Os arquivos de mapas utilizados pelo EHLLAPI são arquivos de texto ASCII. Há duas seções em um arquivo de mapa: o Cabeçalho e o Campo.
As informações do cabeçalho contêm atributos globais para um arquivo de mapa. Por exemplo, você pode desejar que o Interpretador do TSD Script pressione ERASE_EOF antes de preencher cada campo.
O formato para um cabeçalho é o seguinte:
*HEADER CLEAR_FIRST = {{TRUE or ON}|{FALSE or OFF}} MOVE_CURSOR = {{TRUE or ON}|{FALSE or OFF}} LIBRARY = {kbc biblioteca a ser utilizada como o padrão para funções de formato definidas pelo usuário}
O cabeçalho sempre deve ser a primeira seção do arquivo de mapa. As especificações são as seguintes:
Esta seção especifica os campos do host e sua relação com os dados do TSD Script. Essencialmente, cada linha da seção campos liga uma posição do campo de dados do host a um campo de registro do TSD Script. De forma alternativa, se os dados a serem transferidos forem uma única variável do TSD Script, uma linha na seção campos ligará a posição do campo de dados do host àquele nome de variável do TSD Script. Cada linha da seção campos é chamada de entrada de mapa.
O formato da seção campos para um arquivo de mapa é o seguinte:
*FIELDS {field}[, ]{row}[, ]{{col}[, ]{{len} {{USERFORMAT [, ]{[file:]routinename}|{SYSFORMAT[, ]{constant [constant ...]}}
Cada segmento de uma entrada de mapa deve ser separado por espaço em branco (um ou mais espaços em branco ou tabulações) ou por uma vírgula. Cada segmento é descrito abaixo:
Cada campo de dados do host deve ser traduzido tanto para ou de um tipo do TSD Script.
Para cada tipo de campo simples do TSD Script, aplicam-se determinados formatos do sistema aos tipos.
Formatos do sistema podem ser combinados para listar mais que um formato do sistema para um campo. Se você tiver uma cadeia que deseja alinhar à esquerda e preencher com zeros ao ser feito o seu upload, poderá gravar algum código do TSD Script para fazê-lo ou especificar LEFT_JUSTIFY ZERO_PAD como o formato do sistema no arquivo de mapa. Utilizar o formato do sistema é mais fácil e executa mais rapidamente que uma rotina de conversação do TSD Script. A não ser que tenha que gravar uma rotina de conversão especial do TSD Script, você deve utilizar o formato do sistema.
O aplicativo de um formato do sistema depende do tipo simples do TSD Script que está sendo formatado. A seguir estão os tipos simples do TSD Script, os formatos do sistema aplicáveis e as descrições associadas.
Tipo | Descrição |
STRING |
|
INTEGER |
|
BOOLEAN |
|
REAL |
|
TIME |
|
DATE |
|
Em algumas circunstâncias, convém gravar suas próprias funções de formato no TSD Script. Uma função de formato definida pelo usuário aceita dados de entrada, converte-os para o novo formato e retorna um Boolean indicando o êxito da operação. O protótipo para funções de formato definidas pelo usuário é:
FUNCTION {funcname}(VAL {source}:{sourcetype}, REF {target}:{targettype}):BOOLEAN
A seguir, estão explicações das funções de formato definidas pelo usuário:
Função de Formato Definida pelo Usuário | Descrição |
sourcetype |
|
targettype |
|
returntype | O tipo de retorno deve ser BOOLEAN. Se a função retornar FALSE, o Interpretador do TSD Script assumirá que ocorreu um erro e retornará EMUERR_FORMAT_FN_FAILURE (-7005) ao responsável pela chamada. Se a função de conversão retornar TRUE, mas definir o valor de destino para $Unknown, o Interpretador do TSD Script assumirá que a conversão foi bem-sucedida e executará a operação. No caso de um download, a variável do TSD Script ou do campo de registro obtém um valor de $Unknown. No upload, o Interpretador do TSD Script pula o campo. |
Devido ao fato das regras diferirem para os tipos dependendo da direção do fluxo de dados, um mapa que inclui funções do usuário deve ser dedicado tanto ao upload quanto ao download a não ser que os tipos de destino e de origem sejam STRING.
Como exemplo, suponha que você deseja converter um código de gravidade do Tivoli Problem Management (TPM), que é numérico, para uma escala alfabética (por exemplo, 1 para A, 2 para B e assim por diante). Além disso, durante um download, você deseja converter da escala alfabética de volta para a numérica. Primeiro, uma função do TSD Script é gravada para alterar o numérico para alfabético (para o upload):
FUNCTION ToAlpha(VAL inSeverity:INTEGER, REF outSeverity:STRING):BOOLEAN IS ACTIONS outSeverity := Char(64 + inSeverity); Exit(TRUE); END; -- ToAlpha
A seguir, uma rotina é criada para converter o alfabético de volta para numérico (para o download):
FUNCTION ToNumeric(VAL inSeverity:STRING, REF outSeverity:INTEGER):BOOLEAN IS ACTIONS outSeverity := CharCode(StrUpper(inSeverity)) - 64; END; -- ToNumeric
Assuma que estas funções são armazenadas em um arquivo denominado CONVERT. Na definição do campo de mapa do upload para a gravidade, a função ToAlpha é especificada da seguinte maneira:
SEVERITY 10 10 1 USERFORMAT CONVERT:TOALPHA
Na definição do campo de mapa do download para a gravidade a função ToNumeric é especificada da seguinte maneira:
SEVERITY 10 10 1 USERFORMAT CONVERT:TONUMERIC
Embora os arquivos de mapas sejam simples, criar arquivos de mapas manualmente para um aplicativo da interface inteira pode levar tempo.
Determinar corretamente as posições da tela do host contando linhas e colunas pode levar a erro humano, especialmente quando o desenvolvedor confronta-se com muitas telas, cada uma contendo muitos campos.
A maioria dos desenvolvedores da interface poderia, preferivelmente, gastar seu tempo elaborando a logística da interface.
A modificação do arquivo de mapa em uma data posterior (ou por alguém mais) será difícil se o usuário tiver apenas o arquivo de texto para ver.
Para superar essas preocupações, o Tivoli Systems criou o Utilitário de Mapa do EHLLAPI.
O Utilitário de Mapa do EHLLAPI fornece uma forma intuitiva de criar arquivos de mapas que são utilizados pelo EMUMapUpload e EMUMapDownload do TSD Script.
O Utilitário de Mapa do EHLLAPI permite capturar telas do host e armazená-las como arquivos de texto (arquivos SCR). Os arquivos de mapas, baseados nas telas capturadas, são criados quando os campos para os quais você deseja criar entradas de campos são selecionados. Para selecionar entradas de campos, você pode dar um clique sobre e arrastar os campos.
Além disso, o Utilitário de Mapa do EHLLAPI é útil para a manutenção da interface porque a ferramenta carrega arquivos SCR (capturados anteriormente) e aplica qualquer arquivo de mapa à tela. Com o Utilitário de Mapa do EHLLAPI, as entradas de campo são criadas, exibidas, editadas e excluídas de uma forma visual, intuitiva.
O Utilitário de Mapa do EHLLAPI é totalmente gravado no TSD Script. Se você deseja fazer modificações no código do TSD Script, o Tivoli Systems recomenda fazer uma cópia de backup do código original (maputil.kb, mapentry.df) antes de começar.
Para usar o Utilitário de Mapa do EHLLAPI, você deve ter o TSD Developer's Toolkit instalado na sua máquina. Para utilizar a opção Capturar, é necessário instalar também as Extensões do EHLLAPI para o TSD Developer's Toolkit.
Para iniciar a ferramenta:
Ao olhar para as telas que foram capturadas do host, você vê caracteres que não eram visíveis na janela do terminal. Estes caracteres são caracteres ocultos do host que agem como delimitadores de campo. O Utilitário de Mapa do EHLLAPI não elimina estes caracteres, pois eles podem ser úteis na determinação de onde os campos de dados começam e terminam.
A primeira operação com a qual você deve se familiarizar é como capturar uma tela do host. Esta é uma primeira etapa necessária na configuração de uma operação de upload/download para qualquer tela do host.
Quando você captura uma tela, ela é:
O Tivoli Systems adotou a convenção de colocar a extensão .SCR nos arquivos de tela capturada; entretanto, você pode escolher qualquer extensão que desejar ao nomear o arquivo.
Para capturar uma tela do host:
Nota: Após você capturar uma tela, o comando de menu Capturar Tela do Host torna-se inativo.
Se você desejar capturar outra tela do host:
A janela do Utilitário de Mapa do EHLLAPI é redimensionável. Se a tela do host não for completamente visível, você poderá redimensionar a janela até que a tela inteira esteja visível. Não é possível fazer entradas de mapas para as áreas fora da tela do host se a janela for muito grande.
Nota: Você utiliza sessões de emulação de terminal apenas para capturar telas. Todas as outras operações do Utilitário de Mapa do EHLLAPI utilizam apenas o TSD Developer's Toolkit. Isto permite capturar várias telas de uma vez e fazer mapas posteriormente, mesmo se você utilizar uma máquina que não tenha o Communications Manager.
Se desejar carregar um arquivo de tela capturada anteriormente:
Após você carregar um arquivo de tela, a opção Carregar Arquivo de Tela torna-se inativa. Se desejar carregar outra tela:
Após carregar um arquivo de tela, você pode criar um arquivo de mapas para essa tela.
Para selecionar o campo para o qual uma entrada de mapa é criada:
Se o indicador for arrastado muito rapidamente, a área destacada pode não incluir o primeiro caractere do campo. Se isto ocorrer, repita as etapas acima.
Para criar uma entrada para a área destacada:
Para editar uma entrada de mapa:
Nota: Dar um clique duplo sobre um objeto é equivalente a dar só um clique e escolher Editar Entrada.
Para excluir uma entrada de mapa:
Para definir as informações de cabeçalho para o arquivo de mapa:
Para salvar um arquivo de mapa não-nomeado (ou se você desejar salvar o arquivo com um nome diferente):
Se desejar salvar um mapa que já esteja nomeado:
Aplicar um arquivo de mapa a uma tela permite que um usuário leia o arquivo de mapa especificado e destaque as entradas de mapa encontradas no arquivo de mapa. Isto é útil quando os usuários precisam incluir ou alterar um arquivo de mapa.
Para aplicar um arquivo de mapa a uma tela:
Após o mapa ser aplicado, você pode editar, excluir e incluir entradas no mapa.
Ao exibir uma tela, ou se você tiver um mapa aplicado a uma tela, alguns comandos do menu Arquivo não estarão disponíveis. Se você precisar capturar uma nova tela ou carregar um arquivo de tela diferente, será necessário redefinir a tela atual.
Para redefinir a tela atual:
Para alterar a fonte utilizada na janela do utilitário:
Nota: A definição da fonte não é salva quando você fecha o Utilitário de Mapa do EHLLAPI.
É possível sair da execução do Utilitário de Mapa do EHLLAPI utilizando um dos métodos a seguir:
Se você escolher sair, mas não tiver salvo suas últimas alterações, aparecerá uma mensagem perguntando se deseja salvar o arquivo.
Se escolher Sim e o arquivo não tiver sido nomeado, aparecerá uma caixa de diálogo Arquivo que permite nomear o arquivo.
Para este exemplo, é mostrada uma tela do AS/400 que exibe atributos de rede. No curso do exemplo, você:
Os arquivos de exemplo (denominados example.scr, example.kb e example.map) podem ser encontrados no diretório OS2ASE.
A tela do host é parecida com o exemplo a seguir:
Exibir o Sistema de Atributos de Rede:
Sistema:
S1028662
Nome do sistema atual . . . . . . . .. . . : S1028662
Nome do sistema pendente . . . . . . . . . . .:
ID de rede local . . . . . . . . . . . . . : APPN
Nome do ponto de controle local . . . . . . . . : S1028662
Localização padrão . . . . . . . . . . . . : S1028662
Modo padrão. . . . . . . . . . . . . . . . : BLANK
Tipo de nó APPN. . . . . . . . . . . . . . :*ENDNODE
Número máximo de sessões intermediárias. . : 200
Resistência de adição de rota. . . . . . . .: 128
ID de rede do servidor/nome do ponto de controle. .:
Mais...
Pressione Enter para continuar.
F3=Sair F12=Cancelar
Para utilizar o exemplo do Utilitário de Mapa do EHLLAPI, siga essas etapas:
Quando você concluir os procedimentos na seção anterior, poderá capturar uma tela.
Example.scr é escolhido como o nome do arquivo de tela, embora uma interface real provavelmente utilize um nome mais descritivo como dnetattr.scr. Utilizando o nome do arquivo de tela como uma base, você cria um mapa denominado example.map.
Para tornar este exemplo simples e efetivo:
A lista a seguir detalha as informações utilizadas para cada entrada de mapa:
Entrada de Mapa | Descrição |
currentSystemName | Comprimento 8, o formato do sistema é DEFAULT_FORMAT, o tipo do TSD Script é STRING. |
pendingSystemName | Comprimento 8, o formato do sistema é DEFAULT_FORMAT, o tipo do TSD Script é STRING. |
localNetworkID | Comprimento 8, o formato do sistema é LEFT_JUSTIFY, o tipo do TSD Script é STRING. |
localCPName | Comprimento 8, o formato do sistema é DEFAULT_FORMAT, o tipo do TSD Script é STRING. |
dfltLocalLocation | Comprimento 8, o formato do sistema é DEFAULT_FORMAT, o tipo do TSD Script é STRING. |
dfltMode | Comprimento 8, o formato do sistema é LEFT_JUSTIFY. |
APPNNodeType | Comprimento 8, o formato do sistema é DEFAULT_FORMAT, o tipo do TSD Script é INTEGER. |
maxNbrIntSess | Comprimento 4, o formato do sistema é LEFT_JUSTIFY, o tipo do TSD Script é INTEGER. |
routeAddRes | Comprimento 3, o formato do sistema é LEFT_JUSTIFY, o tipo do TSD Script é INTEGER. |
Estes formatos de sistemas (diferentes de DEFAULT_FORMAT) são utilizados por operações de upload. Para operações de download, o espaço em branco é ajustado a partir dos valores. Os atributos de cabeçalho não são definidos para este mapa; em vez disso, são utilizadas as definições padrão.
Após criar todas as entradas, salve o mapa como EXAMPLE.MAP. O Utilitário de Mapa do EHLLAPI gera um arquivo parecido com o exemplo a seguir. Este exemplo executa um download simples. Entretanto, ele ilustra as etapas básicas da criação de mapa usando o Utilitário de Mapa do EHLLAPI.
O nome do arquivo de mapa *REM é E:\EHLLAPI\MAPUTIL\example.map *HEADER CLEAR_FIRST = FALSE MOVE_CURSOR = TRUE
*FIELDS
currentSystemName, 3, 55, 8, SYSFORMAT, DEFAULT_FORMAT pendingSystemName, 4, 57, 8, SYSFORMAT, DEFAULT_FORMAT localNetworkID, 5, 55, 8, SYSFORMAT, LEFT_JUSTIFY localCPName, 6, 55, 8, SYSFORMAT, DEFAULT_FORMAT dfltLocalLocation, 7, 55, 8, SYSFORMAT, DEFAULT_FORMAT dfltMode, 8, 55, 8, SYSFORMAT, LEFT_JUSTIFY APPNNodeType, 9, 55, 8, SYSFORMAT, DEFAULT_FORMAT maxNbrIntSess, 10, 55, 4, SYSFORMAT, LEFT_JUSTIFY routeAddRes, 11, 55, 3, SYSFORMAT, LEFT_JUSTIFY O segmento de código do TSD Script a utilizar este arquivo de mapa é parecido com:
TYPES
NetAttrRec IS RECORD currentSystemName :STRING; pendingSystemName :STRING; localNetworkID :STRING; localCPName :STRING; dfltLocalLocation :STRING; dfltMode :STRING; APPNNodeType :STRING; maxNbrIntSess :INTEGER; routeAddRes :INTEGER; $myDnloadMap {'EXAMPLE.MAP'}:STRING; END; ROUTIINES FUNCTION GetNetAttributes(VAL conn:EMUCONNECTION, REF netAttr:NetAttrRec):INTEGER IS
-- Supõe que você já esteja na tela à direita.
VARIABLES rc :INTEGER; ACTIONS rc := EMUMapDownload(conn, netAttr.$myDnloadMap,netAttr); IF (rc < 1) THEN WinMessageBox($DESKTOP,'Error',$MBOK, 'Map dnload returns '& rc); END; Exit(rc); END; -- GetNetAttributes
Nesta seção, você cria uma entrada de mapa para os IDs de rede do Servidor. Há cinco campos que podem conter um ID de rede do servidor.
Arrastar o indicador do primeiro caractere do primeiro campo para o último caractere do último campo cria uma entrada chamada srvrNetworkID e é considerado um campo de multi-linhas pelo Utilitário de Mapa do EHLLAPI. É criada uma função de formato do usuário chamada ParseSrvrNames.
A função de formato é parecida com o seguinte:
FUNCTION ParseSrvrNames(VAL inStr:STRING, REF srvrNetworkID:LIST OF STRING):BOOLEAN IS VARIABLES temp :STRING; ACTIONS temp := StrTrim(StrLTrim(inStr)); -- get rid of blank fields WHILE (Known(temp)) DO ListInsert(srvrNetworkID, StrCopy(temp,1,8)); temp := StrDelete(temp,1,80); END; Exit(TRUE); END; -- ParseSrvrNames
Você declara srvrNetworkID como uma lista de cadeias no registro:
NetAttrRec IS RECORD currentSystemName :STRING; pendingSystemName :STRING; localNetworkID :STRING; localCPName :STRING; dfltLocalLocation :STRING; dfltMode :STRING; APPNNodeType :STRING; maxNbrIntSess :INTEGER; routeAddRes :INTEGER; srvrNetworkID :LIST OF STRING; $myDnloadMap {'EXAMPLE.MAP'}:STRING; END;
Quando a função de download é executada, a lista é atualizada com valores corretos. Você pode achar que este método é mais flexível do que chamar EMUFillBuffer repetitivamente ou do que criar campos fictícios no registro do TSD Script para fazer download de todos os campos em um mapa e, em seguida, inserir os valores, um de cada vez, na lista.
Tivoli Service Desk 6.0 Developer's Toolkit - Guia de APIs Existentes