Tivoli Service Desk 6.0 Developer's Toolkit - Guia de Programação do Script

Capítulo 9:A Interface do Tivoli Service Desk (TSD) Script Mail

Retornar ao Índice


Introdução

A correspondência eletrônica (e-mail) é uma das áreas de aplicativo de software que mais cresce. Tanto a Internet quanto as intranets organizacionais dependem do e-mail como um agente de comunicações viável.

O e-mail permite diversas variedades de comunicações:

Mecanismo de armazenamento e encaminhamento

Uma das vantagens fornecidas por uma rede de e-mail é o mecanismo de armazenamento e encaminhamento.

O mecanismo de armazenamento e encaminhamento permite que um usuário envie uma mensagem para um outro usuário, mesmo se o outro usuário não estiver com sessão iniciada na rede de e-mail.

O servidor armazena a mensagem enviada pelo primeiro usuário e a encaminha para o outro usuário quando ele verifica sua caixa de correio. Isto permite comunicação assíncrona entre os dois usuários. A comunicação assíncrona significa que a operação de comunicações prossegue independentemente da sincronização.

APIs de Comunicações

A maioria dos fornecedores de e-mail publicam suas APIs (application programming interface) em formatos que permitem que os aplicativos de outros fornecedores façam interface com sua infraestrutura de mensagens. Uma API é um conjunto de rotinas que um aplicativo utiliza para solicitar e executar serviços de nível inferior em um sistema operacional.

A utilização de APIs permite que os fornecedores de software suportem operações especializadas. Isso significa, no entanto, que um aplicativo que utiliza estas APIs deve executar em um sistema proprietário para obter vantagem dos recursos de mensagens.

Nota: O Internet Mail Protocol (SMTP/POP) não é uma API.

Protocolo VIM

Diferente das APIs de mensagens específicas do fornecedor, o protocolo VIM (vendor independent messaging) não é dependente dos formatos específicos do fornecedor. Utilizando o protocolo VIM, um desenvolvedor pode escrever um aplicativo que executa em qualquer plataforma e que suporta os recursos de mensagens construídos para o aplicativo.

O protocolo de interface VIM foi projetado pelo VIM Consortium, que inclui os seguintes membros:

MAPI

Um outro protocolo de e-mail popular que a linguagem TSD Script aceita é o MAPI (Mail Application Program Interface), um produto da Microsoft. O MAPI mostra funcionalidade semelhante ao VIM e permite a comunicação de correio do mesmo modo que o VIM.

A interface TSD Script Mail se comunica com o VIM e o MAPI.

Nota: As seguintes instruções não são aceitas pelo MAPI:

SMTP

O Simple Mail Transfer Protocol (SMTP) fornece mecanismos para a transmissão de e-mail:

POP3

Post Office Protocol - versão 3 (POP3) permite que uma estação de trabalho acesse uma caixa de mensagens dinamicamente em um host servidor. Usualmente, isso significa que o servidor POP3 permite que uma estação de trabalho recupere o e-mail que o servidor está retendo para ele.

Nota: As seguintes instruções não são suportadas pelo SMTP e POP3:

Como Utilizar o TSD Script Mail com Protocolos

A interface TSD Script Mail fornece aos programadores um meio para desenvolver aplicativos ativados para correio. No momento, a interface suporta três protocolos:

A interface TSD Script Mail permite flexibilidade na construção de aplicativos, conforme resumido abaixo:

Utilizações da Interface TSD Script Mail

Utilizando a interface TSD Script Mail, você pode criar programas TSD Script para fazer o seguinte:

Termos da Interface TSD Script Mail

Esta seção apresenta alguns dos termos que são utilizados para descrever a implementação da interface TSD Script Mail.

Catálogos de endereços

Um catálogo de endereços é a localização onde as informações do usuário, os endereços, as listas de distribuição e outros são armazenados. Geralmente, um administrador de correio gerencia o catálogo de endereços.

Há dois tipos de catálogos de endereços: público e particular.

A interface TSD Script Mail suporta a capacidade para ler um catálogo de endereços público somente para o protocolo VIM.

Entidade

Uma entidade é uma pessoa ou programa que envia ou recebe mensagens de e-mail.

Anexos de arquivo

Anexos de arquivo são arquivos que podem ser anexados a uma mensagem. Os arquivos anexados podem ser de qualquer formato. É responsabilidade do emissor e do receptor interpretar os arquivos corretamente.

Caixa de entrada

A caixa de entrada é um arquivo especial que suporta a leitura e marcação de mensagens sob o protocolo POP3. Ela armazena mensagens recuperadas do servidor POP3 e fornece um mecanismo para as mensagens serem marcadas como lidas ou não-lidas.

MsgCntnr serve como um indicador de parâmetro na caixa de entrada para o SMTP/POP3.

Administrador de correio

O administrador de correio é a pessoa responsável pela inspeção do servidor de correio. Esta pessoa pode ser responsável pelo gerenciamento de contas de usuário e do volume de mensagens armazenadas na rede.

Caixa de correio

Uma caixa de correio é a localização física que é atribuída a uma entidade individual. A caixa de correio armazena as mensagens quando elas são enviadas. A caixa de correio também pode ser referida como um contêiner de mensagens.

Mensagem

Uma mensagem é qualquer objeto que possa ser transportado através de um sistema de mensagens e armazenado no contêiner de mensagens.

Cliente de mensagem

Um cliente de mensagem é uma interface que permite que o usuário final faça o seguinte:

Contêiner de mensagens

Um contêiner de mensagens é a localização de armazenamento para mensagens recebidas. Este é sinônimo de caixa de correio.

Cabeçalho de mensagem

Um cabeçalho de mensagem é um cabeçalho que contém informações referentes a:

Itens de mensagem

Um item de mensagem é uma lista de itens. Um item de mensagem pode ser de dois tipos:

Tipo de mensagem

Um tipo de mensagem define o formato e a semântica do conteúdo da mensagem.

Partes da nota

Partes da nota são componentes reais de uma mensagem e vários tipos são aceitos pelo protocolo VIM.

A interface TSD Script Mail suporta somente partes da nota de texto

Servidor

O servidor é a parte do sistema de mensagens que trata das seguintes tarefas:

O servidor também é referido como o "programa emissor".

Endereço do usuário

O endereço do usuário é a localização da caixa de correio do destinatário da mensagem. Cada sistema de mensagens possui seu próprio formato de endereçamento.

O endereçamento de mensagem é um dos assuntos mais complexos no desenvolvimento de um aplicativo de mensagens. A interface TSD Script Mail foi desenvolvida para fazer interface com todos os sistemas de mensagens compatíveis com VIM, MAPI e SMTP/POP. No entanto, lembre-se de que é preciso considerar os requisitos do sistema de mensagens base que você está utilizando quando desenvolver aplicativos de mensagens ou aperfeiçoamentos.

ID do usuário

Um ID do usuário é um identificador exclusivo atribuído a uma entidade. Isto permite que uma entidade inicie sessão para o servidor de correio.

Estruturas de Registro do TSD Script Mail


As seções a seguir são extraídas do arquivo mail.kb do TSD Script. Para obter informações adicionais, consulte a seção, "Arquivo Mail.kb" no final deste capítulo.

Arquivo de Cabeçalho

Os seguintes tipos são definidos para a interface TSD Script Mail. Dependendo da implementação de seu sistema de correio, alguns dos tipos podem ser opcionais. EntityName e Address são os únicos tipos aceitos pelo Internet Mail Protocol. SMTP/POP requer a especificação de Address; EntityName é opcional.

MAILContainer is INTEGER; 
MAILSession is INTEGER; 
MAILRef is REAL; 
MAILName is RECORD; 
  EntityType        : INTEGER; 
  NameType          : INTEGER; 
  AddressBookName   : STRING; 
  EntityName        : STRING; 
  AddressType     : INTEGER; 
  Address         : STRING; 
  CharSet:            : STRING; 
            END; 

As descrições dos tipos utilizados no exemplo anterior são listadas aqui.

Como especificar itens de mensagem

O seguinte registro é utilizado para definir um item de mensagem.

MAILItem is RECORD 
  Class         : INTEGER; 
  Type                      : STRING; 
  Name            : STRING; 
  BufferType    : INTEGER; 
  BufferData    : STRING; 
            END; 

As descrições dos tipos utilizados no exemplo anterior são listadas aqui.

Na falta de acordos particulares entre o emissor e os destinatários de uma mensagem, recomenda-se que os membros da série ISO-8859-* sejam utilizados preferencialmente em relação a outros conjuntos de caracteres.

Cabeçalho de mensagem

Este registro contém as informações de cabeçalho de uma mensagem a ser enviada.

No MAPI, somente o tipo Subject é funcional, o que significa que os outros tipos não são suportados.

O Internet Mail Protocol suporta somente os tipos Subject e InReplyTo.

Status: 
MAILSendHeader is RECORD 
  Subject                       : STRING; 
  Priority                      : INTEGER; 
  DeliveryReport      : BOOLEAN; 
  NonDeliveryReport   : BOOLEAN; 
  NonDeliveryContents : BOOLEAN; 
  Encrypt             : BOOLEAN;
  Sign                          : BOOLEAN; 
  ExpirationDate      : DATE
  ConversationID                       : LIST of STRING;
  Sensitivity                   : INTEGER; 
  InReplyTo                            : STRING;
  RespondBy                     : DATE; 
  KeyWord             : LIST of STRING; 
  ReturnReceipt                        : BOOLEAN; 
  Save                : BOOLEAN; 
  CharSet:            : STRING;
            END; 

As descrições dos tipos utilizados no exemplo anterior são listadas aqui.

Nota: A definição padrão é NORMAL.

Na falta de acordos particulares entre o emissor e os destinatários de uma mensagem, recomenda-se que os membros da série ISO-8859-* sejam utilizados preferencialmente em relação a outros conjuntos de caracteres.

Atributos de mensagem

Este registro define os atributos do cabeçalho de mensagem ao enviar uma mensagem. Os atributos do cabeçalho multi-valorados são declarados como listas.
No MAPI, os únicos tipos aceitos são:

O Internet Mail Protocol aceita os seguintes tipos:

O exemplo a seguir mostra os atributos do cabeçalho de mensagem.

MAILReadHeader is RECORD 
  Type                      : STRING; 
  FromName                  : STRING; 
  FromAddress               : STRING; 
  Subject                       : STRING; 
  MessageDate               : DATE; 
  Priority                      : INTEGER; 
  Sign                          : BOOLEAN; 
  NestingDepth                         : INTEGER; 
  UniqueMsgID                   : STRING; 
  Sensitivity                   : INTEGER; 
  InReplyTo                            : STRING; 
  RespondBy                     : DATE; 
  ReturnReceipt                        : BOOLEAN; 
  ConversationID                       : LIST of STRING; 
  KeyWords                             : LIST of STRING;
  AddressType     : INTEGER; 
  FromCharSet               : STRING;
  SubjectCharSet            : STRING;
            END; 

As descrições dos tipos para o exemplo anterior são listadas aqui.

Na falta de acordos particulares entre o emissor e os destinatários de uma mensagem, recomenda-se que os membros da série ISO-8859-* sejam utilizados preferencialmente em relação a outros conjuntos de caracteres.

Resumo da mensagem

Este registro obtém um resumo dos atributos da mensagem ao varrer as mensagens em um contêiner.

No MAPI, somente o tipo MsgReference é aceito.

Todos os tipos são aceitos no Internet Mail Protocol, exceto Priority.

Este exemplo mostra o resumo dos atributos da mensagem.

MAILMsgSummary is RECORD 
  MsgReference              : MAILRef; 
  Type                      : STRING; 
  UnreadMail                : BOOLEAN; 
  FromName                  : STRING; 
  FromAddress               : STRING; 
  Priority                      : INTEGER; 
  Subject                       : STRING; 
  MessageDate               : DATE; 
  FromCharSet               : STRING;
  SubjectCharSet            : STRING;
            END; 

As descrições dos tipos utilizados no exemplo anterior são listadas aqui.

Na falta de acordos particulares entre o emissor e os destinatários de uma mensagem, recomenda-se que os membros da série ISO-8859-* sejam utilizados preferencialmente em relação a outros conjuntos de caracteres.

Como filtrar registros

Este registro é utilizado para filtrar o tipo de mensagens recuperadas durante o processo de varredura de mensagens.

O MAPI e o SMTP/POP não aceitam a filtragem.

O exemplo a seguir mostra os atributos de filtro.

MAILFilter is RECORD 
  MessageType                   : STRING; 
  UniqueMsgID                   : STRING; 
  Sent                          : BOOLEAN; 
  Keyword                       : STRING; 
  From                          : STRING; 
  Subject                       : STRING; 
  Date                          : DATE; 
  Priority                      : INTEGER; 
  Sign                          : BOOLEAN; 
  ConversationID                : STRING; 
  Sensitivity                   : INTEGER; 
  RespondBy                     : DATE; 
            END; 

As descrições dos tipos utilizados no exemplo anterior são listadas aqui.

Valores definidos pelo usuário adicionais também são aceitos.

MAILInfoRec

A estrutura do registro MAILInfoRec é utilizada na função MAILQueryDefaults para receber os valores do sistema de correio padrão.
O exemplo a seguir mostra como funciona a estrutura MailInfoRec.

MAILInfoRec is RECORD
  Product:                        STRING;
  SpecVersion:                    INTEGER;
  MaxSubjectLen:                  INTEGER;
  MaxTextLen:                     INTEGER;
  PathNameReq:                    BOOLEAN;
  UserNameReq:                    BOOLEAN;
  PasswdReq:                      BOOLEAN;
  DefPathName:                    STRING;
  DefUserName:                    STRING;
  DefCharSet:                     STRING;
            END;

As descrições dos tipos utilizados no exemplo anterior são listadas aqui.

Catálogos de endereços

O TSD Script permite listar os nomes de destinatários da mensagem em um catálogo de endereços. (Os catálogos de endereços não são aceitos no MAPI ou SMTP/POP.) Além disso, o TSD Script não aceita catálogos de endereços aninhados.

O seguinte registro é utilizado para recuperar as entradas no catálogo de endereços.

MAILABEntry is RECORD 
  Name            : STRING; 
  AddressType     : INTEGER; 
  Address         : STRING; 
  Comments        : STRING; 
  EntryType       : INTEGER; 
            END; 

Nota: Os usuários finais não podem modificar um catálogo de endereços.

As descrições dos tipos utilizados no exemplo anterior são listadas aqui.

Como Implementar a Interface TSD Script Mail

Esta seção orienta você no processo de implementação de uma pequena amostra do programa TSD Script (send mail.kb). Este programa envia uma mensagem de correio de um usuário cujo ID é "BILL" para um usuário cujo ID do usuário é "JOHN."

Como incluir a interface TSD Script Mail em um programa TSD Script

Os programas TSD Script podem utilizar a interface TSD Script Mail incluindo o módulo TSD Script Mail na seção Uses de uma base de informações.
O módulo TSD Script Mail é encontrado no arquivo mail.kb e foi instalado automaticamente no diretório onde o Developer's Toolkit foi instalado. O arquivo mail.kb contém a definição de estruturas de registro, constantes e códigos de retorno utilizados pelas funções do TSD Script Mail.

O fragmento de código a seguir ilustra a primeira etapa na inclusão da interface TSD Script Mail em um programa:

Knowledgebase SENDMAIL; 
USES
    mail; 
PUBLIC 
PROCEDURE SendMailMessage; 
PRIVATE 
ROUTINES 
PROCEDURE SendMailMessage IS 
ACTIONS 
    (*Corpo do procedimento *)
            END; 

Como inicializar a interface TSD Script Mail

Antes de chamar qualquer uma das funções do TSD Script Mail, um aplicativo deve primeiramente chamar a instrução MAILInitialize. Esta função inicializa os recursos e as estruturas de dados utilizadas pela interface TSD Script Mail.

A instrução MAILInitialize deve especificar como seus parâmetros o protocolo que vai ser utilizado:

Após inicializar a interface TSD Script Mail, você pode abrir qualquer número de sessões de correio nela.

MAILInitialize(OMI_VIM_INTERFACE)

Nota: Após MailInitialize ter sido chamado com êxito, MailTerminate deverá ser chamado antes de sair do programa.

Como abrir uma sessão

Após inicializar a interface TSD Script Mail, você pode abrir uma sessão com a instrução MAILOpenSession. A instrução MAILOpenSession requer:

O código de exemplo a seguir:

Nota: No OS/2, utilize OMISEL_CP850. No Windows, utilize OMISEL_CP1252.

Você pode também passar $Unknown e o sistema utiliza o conjunto de caracteres padrão.

Nota: Usuários do Microsoft Windows 95/98: Consulte a seção Notes da instrução MailOpenSession no TSD - Referência de Linguagem do Script.

Para quaisquer estados de falha, utilize a instrução MailGetLastErrorType.

PROCEDURE SendMailMessage 
VARIABLES 
    sessID:       MailSession; 
    rc:Integer; 
ACTIONS 
    rc := MAILInitialize(OMI_VIM_INTERFACE); 
     IF (rc <> KML_SUCCESS) THEN 
        WinMessageBox($desktop, 'erro', $MBOK,
                      'Erro no MAILInit.
                       O código de erro é ' & rc <);
        Exit;
            END; 
     rc := MAILOpenSession('M:\APPS\CCMAIL\CCDATA',
                          'BILL','K2K2', OMISEL_CP850,
                           sessID,OMI_VIM_INTERFACE);
     IF (rc <> KML_SUCCESS) THEN 
        WinMessageBox($desktop, 'erro', $MBOK,
                      'Erro no MAILInit. 
                       O código de erro é ' & rc <); 
        MailTerminate(OMI_VIM_INTERFACE);
        Exit; 
            END; 
        (* Enviar a mensagem *)
     rc := MAILCloseSession(sessID); 
     IF (rc <> KML_SUCCESS) THEN 
        WinMessageBox($desktop, 'erro', $MBOK,
                      'Erro no MAILInit. 
                       O código de erro é ' & rc <); 
        MailTerminate(OMI_VIM_INTERFACE); 
        Exit; 
              END; 
     rc := MAILTerminate(OMI_VIM_INTERFACE); 
            END; 

Uma sessão válida agora está aberta. No entanto, antes de uma mensagem ser enviada, várias tarefas devem ser realizadas:

  1. Inicialize o registro de cabeçalho de mensagem.
  2. Inicialize a lista de destinatários.
  3. Especifique a lista de destinatários.
  4. Especifique a lista de itens de mensagem.

Como inicializar o cabeçalho de mensagem

No exemplo a seguir, apenas os campos Subject e Priority da estrutura de registro MAILSendHeader são inicializados. Todos os outros campos são deixados como $Unknown.

msgHeader:MAILSendHeader; 
msgHeader.Subject := 'Planta das Instalações';
msgHeader.Priority := OMI_HIGH_PRIORITY; 

Como inicializar a lista de destinatários

Suponha que você deseje enviar uma mensagem para um destinatário nomeado John. A lista de destinatários consiste em apenas um elemento, o endereço "JOHN."

Conforme mostrado neste exemplo, a toList é uma lista de registros MAILName.

    toList:       LIST of MAILName; 
toRecipient:MAILName;

Como especificar um destinatário

Há dois modos para especificar um destinatário: endereço ou nome.

O registro MailName tem um tipo chamado EntityType e se refere ao tipo de destinatário. Se o destinatário for um único usuário ou programa, o EntityType deve ser atribuído ao valor OMISEL_ENTITY. Se o destinatário da mensagem for um grupo (tal como uma lista de distribuição), o EntityType deverá ser atribuído ao valor OMISEL_GROUP.

Como especificar um destinatário por nome

Se você especificar um destinatário pelo nome, deve inicializar os seguintes tipos no registro MAILName:

A entrada no tipo NameType é baseada no nome do aplicativo de mensagens. Por exemplo:

Como especificar um destinatário por endereço

Se você especificar um destinatário pelo endereço, deve inicializar os campos AddressType e Address do registro MAILName.

O campo AddressType se refere ao tipo do endereço. Por exemplo: OMISEL_CCMAIL, OMISEL_NOTES, OMISEL_MHS e etc. Você pode encontrar uma lista completa de AddressType nas descrições de tipo mencionadas posteriormente neste capítulo.

O tipo Address contém a cadeia de endereço no formato designado pelo tipo AddressType. Consulte a documentação do fornecedor de sua ferramenta de e-mail VIM para obter o formato de endereço correto.

O SMTP/POP requer que um destinatário seja especificado por endereço. O campo name é opcional.

Nota:
Quando o MAILReadMessage lê as mensagens, a instrução completa os tipos de especificação Name e Address do registro MAILName enquanto recupera as mensagens.

A instrução, msgCntnr, aponta para a Caixa de Entrada quando utilizada para suporte de SMTP/POP3. Conforme mostrado neste fragmento de código, você especifica o destinatário pelo nome e utiliza o catálogo de endereços padrão:

toRecipient.EntityType := OMISEL_ENTITY; 
toRecipient.AddressBookName := ''; 
toRecipient.EntityName := 'JOHN'; 
ListInsert(toList, toRecipient, $After); 

Nota: As instruções toList e ccList podem ser declaradas do mesmo modo.

Como especificar a lista de itens de mensagem

A próxima tarefa é construir a lista de itens de mensagem. Os seguintes itens devem ser especificados:

Este programa de exemplo inclui a lista de itens de mensagem:

(* Construir a lista de itens de mensagem *)
    (* O primeiro item é uma parte de nota *) 
Item.Class      := OMISEL_NOTE_PART; 
    Item.Type       := OMI_TEXT; 
    Item.Name       := 'Título para a
                       parte de nota';
    Item.BufferType := OMI_ACTUAL_DATA; 
    Item.BufferData := 'Olá John. Eu' &
                       'incluí o layout da planta' &
                       'das instalações no' &
                       'anexo de arquivo. ';
    Name.Address    := 'JOHN/ACME CORPORATION'
    ListInsert(Items, Item, $After);
   (* O segundo item é um anexo de arquivo *)
Item.Class      := OMISEL_ATTACH;
    Item.Name       := 'image.pcx';
    Item.BufferType := OMI_FILE_DATA;
    Item.BufferData := 'D:\TMP\PAPANIM.PCX';
    ListInsert(Items, Item, $After);

Nota: Um exemplo de SMTP/POP para Name.Address seria semelhante ao seguinte:

Name.Address := 'john@acme.com'

Como escrever o procedimento SendMailMessage

O procedimento SendMailMessage pode ser escrito conforme mostrado.

PROCEDURE SendMailMessage IS 
VARIABLES 
    header:       MAILSendHeader; 
    Items:        LIST of MAILItem; 
    Item:         MAILItem; 
    name:         MAILName; 
    toList:       LIST of MAILName; 
  rc :INTEGER; 
    sessID:       MailSession; 
ACTIONS 
    rc := MAILInitialize(OMI_VIM_INTERFACE); 
    IF (rc < 1) THEN 
        WinMessageBox($desktop, 'erro', $MBOK,
                      'Erro no MAILInit.
                       O código de erro é ' & rc <);
        Exit;
            END; 
    rc := MAILOpenSession('M:\APPS\CCMAIL\CCDATA', 
                          'BILL','K2K2', 
                     OMISEL_CP850, sessID,
OMI_VIM_INTERFACE); 
    IF (rc < 1) THEN 
        WinMessageBox($desktop, 'erro', $MBOK,
                      'Erro no MAILInit.
                       O código de erro é ' & rc <);
        MailTerminate(OMI_VIM_INTERFACE); 
        Exit;
                END; 
    (* Enviar a mensagem *)
    (* Definir o registro de cabeçalho *)
    header.subject := 'Planta das Instalações';
    header.Priority := OMI_HIGH_PRIORITY; 
    (* Construir a lista de itens de mensagem *)
    (* O primeiro item é uma parte de nota *)
    Item.Class      := OMISEL_NOTE_PART; 
    Item.Type       := OMI_TEXT; 
    Item.Name       := 'Título para
                      a parte de nota';
    Item.BufferType := OMI_ACTUAL_DATA; 
    Item.BufferData := 'Olá John. Eu incluí'&
                       'o layout da planta das instalações'&
                       'no anexo de arquivo. ';
    ListInsert(Items, Item, $After); 
    (* O segundo item é um anexo de arquivo *)
    Item.Class      := OMISEL_ATTACH; 
    Item.Name       := 'image.pcx'; 
    Item.BufferType := OMI_FILE_DATA; 
    Item.BufferData := 'D:\TMP\PAPANIM.PCX'; 
    ListInsert(Items, Item, $After); 
    (* Especificar o destinatário *)
    name.EntityType := OMISEL_ENTITY; 
    name.AddressBookName := ''; 
    name.EntityName := 'JOHN' 
    ListInsert(toList, name, $After); 
    rc := MailSendMessage(SESSID, OMI_MAIL, header,
                          toList, $UNKNOWN,$UNKNOWN,
                           Items);
    IF (rc < 1) THEN 
        WinMessageBox($desktop, 'erro', $MBOK,
                      'Erro no MAILInit.
                       O código de erro é ' & rc <);
        ELSE ('Correio enviado com êxito');
            END; 
    rc := MAILCloseSession(sessID); 
    IF (rc < 1) THEN 
        WinMessageBox($desktop, 'erro', $MBOK,
                      'Erro no MAILInit.
                       O código de erro é ' & r <);
        MailTerminate(OMI_VIM_INTERFACE); 
        Exit;
            END; 
    rc := MAILTerminate(OMI_VIM_INTERFACE); 
            END; 

Como ler mensagens no contêiner de mensagens

A interface TSD Script Mail pode ler mensagens no contêiner de mensagens. A leitura de mensagens consiste no processo de duas etapas:

Nota: Os filtros não são aceitos pelo SMTP/POP3.

O exemplo a seguir mostra um programa que recebe correio:

KNOWLEDGEBASE mailrecv;
 
USES mail; 

ROUTINES 

PROCEDURE ReadMail; 

PRIVATE
ROUTINES 

PROCEDURE ReadMail IS
VARIABLES
  sess :MAILSession;
  msgContainer :MAILContainer;
  toList :LIST OF MAILName;

  outfile         :FILE;
  numMessages     :INTEGER;
  msgSummary      :LIST OF MAILMsgSummary;
  summRec         :MAILMsgSummary;
  msgRef          :MAILRef;
  msgHeader       :MAILReadHeader;
  msgItems        :LIST of MAILItem;
  ccList, bccList :LIST of MAILName;
  nestedMsg       :BOOLEAN;
  reply           :string;
  rc :INTEGER;
ACTIONS
   rc:=MAILInitialize(OMI_SMTP_POP_INTERFACE);
              IF rc < 1 THEN
    EXIT;
            END;
   rc:=MAILOpenSession('mozart.softart.com',
                      'Mr Totstuser@domain name',
                       'pass',$UNKNOWN,
                       sess,OMI_SMTP_POP_INTERFACE);
              IF rc < 1 THEN
             WinMessageBox($Desktop,'Erro',$MBIconError,
                'A abertura de sessão falhou: '&rc);
 MAILTerminate(OMI_SMTP_POP_INTERFACE);
    EXIT;
            END;
 rc:=MAILOpenMessageContainer (sess,
                              'c:\mail\inbox.idx',
                               msgContainer);
              IF rc < 1 THEN
             WinMessageBox($Desktop,'Erro',$MBIconError,
                 'A abertura do contêiner falhou: '&rc);
 MAILCloseSession(sess);
 MAILTerminate(OMI_SMTP_POP_INTERFACE);
    EXIT;
            END;
 rc:= MAILScanMessages(msgContainer, OMI_UNREADONLY,
                      $Unknown, TRUE, numMessages,
                       msgSummary);
              IF rc < 1 THEN
     WinMessageBox($Desktop,'Erro',$MBOK,
                   'A varredura falhou: '&rc);
 MAILCloseMessageContainer(msgContainer);
 MAILCloseSession(sess);
 MAILTerminate(OMI_SMTP_POP_INTERFACE);
    EXIT; 
            END;
 REPEAT
    IF numMessages > 0 THEN
         rc:=FOpen(outfile, 'mailtest.log', $CREATE);
              IF rc < 1 THEN 
             WinMessageBox($Desktop,'Erro',$MBIconError,
                          'A abertura do arquivo falhou: '&rc);
                EXITLoop;
ELSE
             FWriteLn(outfile, 'Número Lido: ' &
                      numMessages);
            FOR msgSummary DO
                 summRec := msgSummary[$Current];
                 FWriteLn(outfile, 'Tipo de Mensagem: ' &
                          summRec.Type);
                 FWriteLn(outfile, 'Mensagem Não-lida: ' &
                          summRec.UnreadMail);
                 FWriteLn(outfile, 'Do Nome: ' &
                          summRec.FromName);
                 FWriteLn(outfile, 'Do Endereço ' &
                          summRec.FromAddress);
                 FWriteLn(outfile, 'Prioridade: ' &
                          summRec.Priority);
                 FWriteLn(outfile, 'Assunto: ' &
                          summRec.Subject);
                 msgRef := summRec.MSGReference;
                rc := MAILReadMessage(msgContainer,msgRef,
                                      0,msgHeader,
                                     msgItems,toList,
                                     ccList,bccList,
                                      nestedMsg);
              IF rc < 1 THEN
                WinMessageBox($Desktop,'Erro',
                              $MBIconError,
                              'A leitura da mensagem falhou: '&rc);
          FClose(outfile); 
                EXITLoop; 
               ELSE
                    MAILReleaseMessageReference
                        (msgContainer, msgSummary
                         [$Current].msgReference);
              FOR tolist DO
                 FWriteLn(outfile,'Para Nome: ' &
                          toList[$current].EntityName);
                 FWriteLn(outfile,'Para Endereço: ' &
                          toList[$current].address);
            END;
              FWriteLn(outfile, ' ***Itens de Mensagem**** ');
                 FOR msgItems DO
            FWriteLn(outfile,msgItems
                     [$current].Type);
            FWriteLn(outfile,msgItems
                     [$current].Name);
            FWriteLn(outfile,msgItems
                     [$current].BufferData);
            END;
            FWriteLn(outfile, 
                    '*********************************
                     ******************* ');
            END; (*Fim do Else*)
          END; (*Fim do LOOP*)
          FClose(outfile); 
       END;(*Fim do Else*)
    END;(*Fim do IF*)
 UNTIL TRUE;
 MAILCloseMessageContainer(msgContainer);
 MAILCloseSession(sess);
 MAILTerminate(OMI_SMTP_POP_INTERFACE);
 WinMessageBox($Desktop,'Programa Concluído',$MBOK,
              'A execução está concluída.
               Verifique a saída.');
            END;

Como fechar uma sessão do TSD Script Mail

É possível ter várias sessões do TSD Script Mail abertas simultaneamente.

Para fechar uma sessão do TSD Script Mail, chame a instrução MAILCloseSession. Isto libera os recursos do sistema que foram associados com a sessão do TSD Script Mail.

Como terminar a interface TSD Script Mail

Quando você estiver preparado para terminar a interface TSD Script Mail, deve primeiro fechar todas as sessões do TSD Script Mail abertas. Em seguida, você precisa chamar a instrução MAILTerminate.

Códigos de Retorno do TSD Script Mail

Esta seção lista os códigos de erro possíveis que podem ocorrer a partir das instruções da interface TSD Script Mail. Os erros podem ocorrer em vários pontos durante o processamento da mensagem, na camada VIM ou MAPI ou na camada TSD Script. As tabelas a seguir descrevem os códigos de erro que podem ocorrer em cada uma destas camadas.

Nota: Todas as chamadas da interface TSD Script Mail retornam o valor 1 se uma função for executada com êxito. Caso contrário, um número negativo é retornado.

Códigos de erro gerados na camada VIM

A lista abaixo detalha os códigos de erro possíveis que podem ser gerados pela camada VIM.

Erro Valor Comentário
OMISTS_FAILURE -1 Falha geral.
OMISTS_FATAL -2 Ocorreu um erro fatal. A utilização do sistema não é
mais possível até que o problema seja corrigido.
OMISTS_ALL_PARAMS_REQUIRED -3 MAILOpenSession retorna esta mensagem quando um
caminho, nome e senha são exigidos pelo sistema de mensagens base.
OMISTS_ATTACHMENT_NOT_FOUND -4 O arquivo de anexo especificado (em um MAILSendMessage)
não foi encontrado.
OMISTS_BAD_PARAM -5 Um parâmetro obrigatório é desconhecido, um parâmetro está
fora do intervalo ou um parâmetro é inválido.
OMISTS_BUF_TOO_SMALL -6 A interface TSD Script Mail utiliza buffers para recuperar
valores do sistema de mensagens. Este código de retorno
deduz que o buffer utilizado era muito pequeno para encaixar o valor retornado.
OMISTS_CONV_NOT_SUPPORTED -7 A conversão especificada não é aceita nesta implementação.
OMISTS_INSUFFICIENT_MEMORY -8 Uma operação interna falhou porque não há
memória disponível.
OMISTS_INVALID_CONFIGURATION -9 Uma configuração de base inválida foi detectada.
OMISTS_INVALID_OBJECT
-10 Os identificadores de objeto (MAILSession, MAILContainer, MAILRef) eram desconhecido ou de alguma outra maneira inválidos. Por
exemplo, um identificador para uma mensagem que não seja de correio pode não ser
passado para funções que esperam uma mensagem de correio.
OMISTS_INVALID_PASSWORD -11 Uma senha incorreta foi passada para MAILOpenSession.
OMISTS_INVALID_SELECTOR -12 Um seletor (OMISEL_*) foi passado para a instrução
que é desconhecida neste contexto.
OMISTS_INVALID_SIGNATURE -13 Uma assinatura inválida foi passada para MAILVerifySignature,
ou a mensagem foi comprometida.
OMISTS_NAME_EXISTS -14 Este código de retorno não é utilizado no VIM.
OMISTS_NAME_NOT_FOUND -15 MAILSendMessage validou o nome do destinatário imediatamente e o nome não foi encontrado no catálogo de endereços especificado. (Se nenhum catálogo de endereços foi especificado, o
catálogo de endereços padrão será utilizado.)
OMISTS_NOT_SUPPORTED -16 O recurso chamado não é aceito por esta implementação.
OMISTS_NO_COMMON_CERTIFICATES -17 A assinatura de MAILVerifyMessage não relata certificados comuns entre o destinatário e o signatário.
OMISTS_NO_DEFAULT -18 MAILGetEntityName não consegue escolher entre várias sessões ativas. Alguns implementações podem retornar o
nome da sessão que ficou ativa pelo maior
tempo, em vez de retornar um código de erro
OMISTS_NO_MATCH -19 Nenhuma correspondência foi encontrada.
OMISTS_NO_SIGNATURE -20 A assinatura de MAILVerifyMessage relata que a
mensagem especificada não tem uma assinatura.
OMISTS_NO_SUCH_ATTRIBUTE -21 O atributo chamado não é utilizado.
OMISTS_OPEN_FAILURE -22 Ocorreu um erro dependente da plataforma ao abrir ou criar um arquivo.
OMISTS_PASS_REQUIRED -23 MAILOpenSession relata que uma senha é necessária
para abrir uma sessão nesta implementação.
OMISTS_READ_FAILURE -24 Ocorreu um erro dependente da plataforma ao abrir ou criar um arquivo.
OMISTS_UNSUP_TYPE -25 MAILSendMessage ou MAILSendDerived Message passou um tipo de mensagem diferente de VIM_MAIL que
não é aceito por esta implementação. Ou, MAILReadMessage não aceita a leitura deste
tipo de item.
OMISTS_UNSUP_VERSION -26 Não correspondência da interface TSD Script Mail e da
interface de base VIM.
OMISTS_WRITE_FAILURE -27 Ocorreu um erro dependente da plataforma ao gravar um arquivo.

Códigos de erro gerados pela camada MAPI

A lista abaixo detalha os códigos de erro possíveis que podem ser gerados pela camada MAPI.

Erro Valor Comentário
MAPI_USER_ABORT -201 O usuário cancelou o processo. A função não foi concluída.
MAPI_E_FAILURE

-202 Ocorreram um ou mais erros não especificados. A função
não foi concluída.
MAPI_E_LOGIN_ FAILURE

-203 O usuário não iniciou sessão com êxito. Nenhum identificador de sessão
é retornado.
MAPI_E_DISK_FULL
-204 O disco está cheio.
MAPI_E_INSUFFICIENT
_MEMORY

-205 Memória insuficiente para continuar. A função
não foi concluída.
MAPI_E_TOO_MANY_SESSIONS

-208 Sessões em excesso abertas de uma vez.
MAPI_E_ TOO_MANY_FILES -209 Há anexos de arquivo em excesso.
MAPI_E_ TOO_MANY_RECIPIENTS -210 Há destinatários de mensagem em excesso especificados.
MAPI_E_ATTACHMENT_NOT
_FOUND
-211 Um ou mais arquivos que precisavam ser anexados à
mensagem não puderam ser encontrados.
MAPI_E_ ATTACHMENT_OPEN_FAILURE -212 Um ou mais arquivos que precisavam ser anexados à
mensagem não puderam ser abertos.
MAPI_E_ ATTACHMENT_WRITE_FAILURE -213 Um anexo não pode ser gravado em um arquivo temporário.
Verifique os direitos de diretório.
MAPI_E_UNKNOWN_RECIPIENT -214 O destinatário não foi encontrado na lista de endereços.
MAPI_E_BAD_RECIPTYPE -215 Nenhum tipo de destinatário foi especificado ou era inválido.
MAPI_E_INVALID_MESSAGE -217 O número de referência da mensagem é inválido.
MAPI_E_TEXT_TOO_LARGE -218 O texto da mensagem é muito longo.
MAPI_E_INVALID_SESSION -219 O identificador da sessão é inválido.
MAPI_E_TYPE_NOT
_SUPPORTED
-220 Um ou mais dos tipos não é suportado por esta implementação.
MAPI_E_AMBIGUOUS
_RECIPIENT
-221 Um ou mais dos destinatários é ambíguo.
MAPI_E_INVALID_RECIPS -225 Um ou mais dos destinatários é inválido.
MAPI_E_NOT_SUPPORTED -226 Esta função não é suportada pela implementação de base.


Códigos de erro gerados pelo SMTP

A tabela abaixo lista os códigos de erro que podem ser gerados pelo SMTP.

Erro Valor Comentário
OMI_ERR_SMTP_OPENSESSION
_FAILURE
-3000 Falha ao inicializar todos os dados em MAILOpenSession(..).
OMI_ERR_SMTP_MAIL
_FAILURE
-3001 Falha ao enviar o comando mail para o servidor SMTP.
OMI_ERR_SMTP_CLOSE
_FAILURE
-3002 Falha ao enviar o comando close para o servidor SMTP.
OMI_ERR_SMTP_VERIFY
_FAILURE
-3003 O servidor SMTP não pode verificar um usuário na lista de destinatários.
OMI_ERR_ATTACH_FILE
_ERROR
-3004 O arquivo especificado como anexo não existe ou
o nome do arquivo está no formato incorreto.
OMI_ERR_SMTP_OPEN_SERVER
_FAILURE
-3005 Falha ao abrir conexão com o servidor SMTP.
OMI_ERR_POP_OPEN_FAILURE -3006 Falha ao abrir conexão com o servidor POP.
OMI_ERR_INVALID_PASSWORD -3007 Falha na verificação da senha.
OMI_ERR_POP_STAT_FAILURE -3008 Falha ao enviar o comando stat para o servidor POP.
OMI_ERR_POP_RETR_FAILURE -3009 Falha ao enviar o comando retr para o servidor POP.
OMI_ERR_POP_DELE_FAILURE -3010 Falha ao enviar o comando delete para o servidor POP.
OMI_ERR_POP_QUIT_FAILURE -3011 Falha ao enviar o comando quit para o servidor POP.
OMI_ERR_SOCKET_FAILURE -3012 A chamada do soquete falhou.
OMI_ERR_PARSE_MESSAGE
_FAILURE
-3013 A chamada da mensagem de análise falhou.
OMI_ERR_INVALID_FILE -3014 O tamanho do arquivo é 0.
OMI_ERR_SERVICE_NOT
_AVAILABLE
-3421 Isto pode ser uma resposta a qualquer comando SMTP se o serviço souber que deve encerrar.
OMI_ERR_MAILBOX_BUSY -3450 A caixa de correio pode estar ocupada.
OMI_ERR_LOCAL_ERROR_IN
_PROCESSING
-3451 Ação solicitada abortada devido ao erro local no processamento.
OMI_ERR_INSUFFCIENT
_SYSTEM_STORAGE
-3452 Ação solicitada abortada porque não há memória do sistema suficiente.
OMI_ERR_SYNTAX_ERROR -3500 Erro de sintaxe, comando não-identificado.
OMI_ERR_SYNTAX_ERROR_IN
_PARAMETER
-3501 Erro de sintaxe em parâmetros ou argumentos.
OMI_ERR_COMMAND_NOT
_IMPLEMENTED
-3502 Comando não implementado.
OMI_ERR_SEQUENCE_ERROR -3503 Seqüência de comando incorreta.
OMI_ERR_PARAMETER_NOT
_IMPLEMENTED
-3504 Parâmetro de comando não implementado.
OMI_ERR_MAILBOX
_UNAVAILABLE
-3550 Ação solicitada não executada: caixa de correio não-disponível.
OMI_ERR_USER_NOT_LOCAL -3551 Usuário não local; tente <forward-path>
OMI_ERR_EXCEEDED
_STORAGE_ALLOCATION
-3552 Ação de correio solicitada abortada: alocação de memória excedida.
OMI_ERR_MAILBOX_NAME
_NOT_ALLOWED
-3553 Nome de caixa de correio não permitido
OMI_ERR_TRANSACTION
_FAILED
-3554 A transação falhou
OMI_ERR_SOCKET_ERROR -3099 Erro de comunicação do soquete

Códigos de erro gerados pelo TSD Script

A lista abaixo detalha os códigos de erro possíveis que podem ser gerados pelo TSD Script.

Erro Valor Comentário
OMI_ERR_INVALID_BUFFER
_TYPE
-2000 Foi especificado um tipo de buffer inválido no registro
Mail Item.
OMI_ERR_INVALID_BUFFER
_DATA
-2001 Dados de buffer inválidos.
OMI_ERR_NO_MEMORY -2002 Os recursos da memória do sistema se esgotaram.
OMI_ERR_INVALID_FILENAME -2003 Nome de arquivo inválido.
OMI_ERR_NO_TOLIST -2004 Nenhuma lista "Para" foi especificada.
OMI_ERR_BAD_PARAM -2005 Foi especificado um parâmetro incorreto.
OMI_ERR_NO_NESTED
_MESSAGE
-2006 Não foi encontrada nenhuma mensagem aninhada no nível solicitado.
OMI_ERR_TOO_MANY_FILE
_NAMES
-2007 Foram especificados nomes de arquivos em excesso.
OMI_ERR_UNSUPPORTED
_PROTOCOL
-2008 O valor para o argumento do protocolo é inválido ou este
protocolo não é aceito.
OMI_ERR_UNSUPPORTED
_FEATURE
-2009 Este recurso não está disponível nesta implementação.
OMI_ERR_NOT_IMPLEMENTED -2010 Este recurso não foi implementado.
OMI_ERR_UNKNOWN_ITEM
_CLASS
-2011 A classe do item é desconhecida.
OMI_ERR_INVALID_NOTE_PART -2012 A parte de observação da mensagem é inválida.
OMI_ERR_MAPI_FAILURE -2013 Foi encontrado um erro na programação da interface MAPI.
OMI_ERR_NOT_INITIALISED -2014 A interface de correio não foi inicializada. MailInitialize deve ser chamado antes de utilizar a interface TSD Script Mail.
OMI_ERR_COULD_NOT_LOAD
_DLL
-2015 O TSD Script Mail não pôde carregar a DLL do MAPI ou do VIM.
KML_ERR_UNKNOWN_ITEM
_CLASS
-5000 Foi especificada uma classe de item desconhecida.
KML_ERR_UNKNOWN_ITEM
_TYPE
-5001 Foi especificado um tipo de item desconhecido.
KML_ERR_UNKNOWN_BUFFER_TYPE -5002 Foi especificado um tipo de buffer desconhecido.
KML_ERR_UNKNOWN_BUFFER_DATA -5003 Foram especificados dados de buffer desconhecidos.

Constantes do TSD Script Mail

As seguintes constantes do TSD Script Mail são válidas.

Constante Valor
OMISEL_ADDRESS 1
OMISEL_ATTACH 6
OMISEL_BCC 9
OMISEL_CC 10
OMISEL_CCMAIL 11
OMISEL_CLASS 13
OMISEL_CP1252 16
OMISEL_CP437 17
OMISEL_CP850 18
OMISEL_ENTITY 26
OMISEL_FORWARD 33
OMISEL_GROUP 38
OMISEL_LMBCS 44
OMISEL_MHS 49
OMISEL_NOT_SUPPORTED 61
OMISEL_NOTE_PART 62
OMISEL_NOTES 63
OMISEL_REPLY 77
OMISEL_TO 97
OMISEL_UNICODE 99
OMISEL_UNKNOWN_RECIP_TYPE 101
OMISEL_UNWRAPPED_TEXT 105
OMISEL_X400 107
OMISEL_X500 108
OMI_MAIL 'VIM_MAIL'
OMI_RTF 'VIM_RTF'
OMI_DLR 'VIM_DLR'
OMI_NDLR 'VIM_NDLR'
OMI_PRIVATE 'VIM_PRIVATE'
OMI_PUBLIC 'VIM_PUBLIC'
OMI_RTRC 'VIM_RTRC'
OMI_TEXT 'VIM_TEXT'
OMI_UNWRAPPED_TEXT 'VIM_UNWRAPPED
_TEXT'
OMI_LOW_PRIORITY 0
OMI_NORMAL_PRIORITY 1
OMI_HIGH_PRIORITY 2
OMI_HISTORY 1
OMI_INHERIT_CONTENTS 2
OMI_ALL_RECIPIENTS 4
OMI_UNREADONLY 2
OMI_NORMAL_SENS 0
OMI_PRIVATE_SENS 1
OMI_PERSONAL_SENS 2
OMI_CO_CONFID_SENS 3
OMI_APP_DEF_SENS 16384
OMI_FILE_DATA 1
OMI_ACTUAL_DATA 2
OMI_REVERSE_SCAN 1
OMI_UNREAD_ONLY 2
OMI_SMTP_POP_INTERFACE 3

Arquivo Mail.kb

Arquivo do TSD Script Mail

O arquivo mail.kb completo pode ser encontrado no diretório onde o Developer's Toolkit foi instalado.


Tivoli Service Desk 6.0 Developer's Toolkit - Guia de Programação do Script

Retornar ao Índice

Copyright