Manuale per la programmazione Tivoli Service Desk 6.0 Developer's Toolkit Script

Capitolo 9: Interfaccia TSD (Tivoli Service Desk) Script Mail

Ritorna all'Indice analitico


Introduzione

La posta elettronica (e-mail) è una delle aree di applicazione software più in espansione. Sia Internet che le intranet organizzative dipendono dall'e-mail come agente per le comunicazioni.

L'e-mail consente diversi tipi di comunicazioni:

Meccanismo di memorizzazione e di inoltro

Uno dei vantaggi dalla rete e-mail è il meccanismo di memorizzazione e di inoltro.

Questo meccanismo permette all'utente di inviare un messaggio ad un secondo utente, anche se il secondo utente non è collegato nella rete e-mail.
Il server memorizza il messaggio inviato dal primo utente e lo inoltra al secondo utente quando questo controlla la propria casella di posta. Questo consente le comunicazioni asincrone tra i due utenti. Comunicazione asincrona significa che l'operazione di comunicazione procede in modo indipendente dalla tempificazione.

API delle comunicazioni

La maggior parte dei fornitori di e-mail offrono le proprie API (application programming interface) in formati che consentono alle applicazioni di altri fornitori di interfacciare con la loro infrastruttura di messaggistica. Una API è una serie di routine utilizzate da un'applicazione per richiedere ed eseguire servizi di livello inferiore in un sistema operativo.

L'utilizzo delle API consente ai fornitori del software di supportare operazioni specializzate. Questo significa, tuttavia, che un'applicazione che utilizza queste API deve operare in un sistema appropriato per poter trarre vantaggio dalle funzioni di messaggistica.

Nota: Il Protocollo di posta Internet (SMTP/POP) non è una API.

Protocollo VIM

A differenza dalle API di messaggistica specifiche del fornitore, il protocollo VIM (vendor independent messaging) non dipende dai formati specifici del fornitore.
Utilizzando il VIM, uno sviluppatore può scrivere un'applicazione che opera su una qualsiasi piattaforma e che supporta i dispositivi di messaggistica inseriti nell'applicazione.
Il protocollo di interfaccia VIM è stato progettato dal VIM Consortium, che comprende anche i seguenti membri:

MAPI

Un altro protocollo e-mail molto comune che il linguaggio TSD Script supporta è MAPI (Mail Application Program Interface), un prodotto della Microsoft.
MAPI fornisce una funzionalità simile a quella di VIM e consente le comunicazioni di posta allo stesso modo di VIM.

L'interfaccia TSD Script Mail comunica sia con VIM che con MAPI.

Nota: Le seguenti istruzioni non sono supportate per MAPI:

SMTP

L'SMTP (Simple Mail Transfer Protocol) fornisce meccanismi per la trasmissione delle e-mail:

POP3

POP3 (Post Office Protocol - versione 3) permette ad una workstation di accedere ad una casella di posta in modo dinamico su un host del server. Solitamente, questo indica che il server POP3 consente ad una workstation di richiamare l'e-mail che il server sta conservando.

Nota: Le seguenti istruzioni non sono supportate per SMTP e POP3:

Utilizzo di TSD Script Mail con i protocolli

L'interfaccia TSD Script Mail fornisce ai programmatori i mezzi per sviluppare le applicazioni abilitate per la posta. Attualmente, l'interfaccia supporta tre protocolli:

L'interfaccia TSD Script Mail fornisce flessibilità nella creazione delle applicazioni come di seguito riepilogato:

Utilizzo dell'interfaccia TSD Script Mail

Utilizzando l'interfaccia TSD Script Mail, è possibile creare i programmi TSD Script per:

Termini dell'interfaccia TSD Script Mail


Questa sezione introduce alcuni dei termini utilizzati per descrivere l'implementazione dell'interfaccia TSD Script Mail.

Rubriche

Una rubrica è la posizione in cui vengono memorizzate le informazioni sull'utente, gli indirizzi, gli elenchi di posta e così via. Generalmente, un amministratore di posta gestisce la rubrica.

Esistono due tipi di rubrica: pubblica e privata.

L'interfaccia TSD Script Mail supporta la funzione che consente di leggere una rubrica pubblica solo per il protocollo VIM.

Entità

Un'entità è una persona o programma che invia o riceve messaggi e-mail.

Allegati dei file

Gli Allegati dei file sono file che possono essere associati ad un messaggio. I file associati possono essere di qualsiasi formato. E' responsabilità del mittente e del destinatario interpretare i file in modo corretto.

Inbox

Inbox è un file speciale che supporta la lettura e il contrassegno dei messaggi nel protocollo POP3. Memorizza i messaggi richiamati dal server POP3 e fornisce un meccanismo per contrassegnare i messaggi come letti o non letti.

MsgCntnr opera come puntatore dei parametri nella inbox per SMTP/POP3.

Amministratore di posta

L'amministratore di posta è la persona responsabile del controllo del server di posta. Questa persona può essere responsabile della gestione degli account degli utenti e della gestione del volume dei messaggi memorizzati nella rete.

Mailbox

Una mailbox è l'ubicazione fisica che viene assegnata ad un'entità individuale. La mailbox memorizza i messaggi quando vengono consegnati. La mailbox può essere considerata anche come un contenitore dei messaggi.

Messaggio

Un messaggio è un oggetto che può essere trasportato su un sistema di messaggistica e memorizzato nel contenitore dei messaggi.

Client dei messaggi

Un client dei messaggi è un'interfaccia che consente agli utenti finali di:

Contenitore dei messaggi

Un contenitore dei messaggi è l'ubicazione di memorizzazione per i messaggi ricevuti. Questo è sinonimo di mailbox.

Intestazione del messaggio

L'intestazione del messaggio è un'intestazione che contiene le informazioni su:

Voci di messaggio

Una voce di messaggio è un elenco di voci. Una voce di messaggio può essere di due tipi:

Tipo di messaggio

Un tipo di messaggio definisce il formato e la semantica del contenuto del messaggio.

Parti della nota

Le Parti della nota sono i veri componenti di un messaggio e diversi tipi vengono supportati dal protocollo VIM.

L'interfaccia TSD Script Mail supporta solo le parti di nota di testo.

Server

Il server è la parte del sistema di messaggistica che gestisce le seguenti attività:

Il server viene anche considerato come "remoto."

Indirizzo utente

L'indirizzo utente è l'ubicazione della mailbox del destinatario del messaggio. Ogni sistema di messaggistica ha il proprio formato di indirizzamento.

L'indirizzamento dei messaggi è una delle attività più complesse nello sviluppo di un'applicazione di messaggistica. L'interfaccia TSD Script Mail è stata sviluppata per interfacciare con tutti i sistemi di messaggistica in conformità con VIM, MAPI e SMTP/POP. Ricordarsi, tuttavia, di considerare i requisiti del sistema di messaggistica che si utilizza quando si sviluppano i miglioramenti o le applicazioni di messaggistica.

ID utente

Un ID utente è un identificativo univoco assegnato ad un'entità. Questo consente all'entità di collegarsi al server di posta.

Strutture del record TSD Script Mail


Le seguenti sezioni sono estratte dal file mail.kb del TSD Script. Per ulteriori informazioni, consultare la sezione "File Mail.kb" alla fine di questo capitolo.

File di intestazione

I seguenti tipi vengono definiti per l'interfaccia TSD Script Mail. A seconda dell'implementazione del proprio sistema di posta, alcuni dei tipi possono essere facoltativi. EntityName e Address sono i soli tipi supportati dal Protocollo di posta Internet. L'SMTP/POP richiede che l'Address sia specificato; EntityName è facoltativo.

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; 

Le descrizioni dei tipi utilizzati nell'esempio precedente vengono qui elencate.

Specifica delle voci dei messaggi

Il seguente record viene utilizzato per definire una voce messaggio.

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

Le descrizioni dei tipi utilizzati nell'esempio precedente vengono qui elencate.

In assenza di accordi privati tra il mittente e i destinatari di un messaggio, si consiglia di utilizzare i membri delle serie ISO-8859-* al posto di altre serie di caratteri.

Intestazione del messaggio

Questo record contiene le informazioni di intestazione di un messaggio che deve essere inviato.

Nella MAPI, solo il tipo Subject è funzionale, il che indica che gli altri tipi non sono supportati.

Il Protocollo di posta Internet supporta solo i tipi Subject e InReplyTo.

Stato:
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; 

Le descrizioni dei tipi utilizzati nell'esempio precedente vengono qui elencate.

Nota: L'impostazione di default è NORMAL.

In assenza di accordi privati tra il mittente e i destinatari di un messaggio, si consiglia di utilizzare i membri delle serie ISO-8859-* al posto di altre serie di caratteri.

Attributi del messaggio

Questo record imposta gli attributi dell'intestazione dei messaggi durante l'invio di un messaggio. Gli attributi dell'intestazione a più valori vengono considerati come elenchi.
Nella MAPI, i soli tipi supportati sono:

Il Protocollo di posta Internet supporta i seguenti tipi:

L'esempio riportato mostra gli attributi dell'intestazione dei messaggi.

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; 

Le descrizioni dei tipi per l'esempio precedente vengono qui elencate.

In assenza di accordi privati tra il mittente e i destinatari di un messaggio, si consiglia di utilizzare i membri delle serie ISO-8859-* al posto di altre serie di caratteri.

Riepilogo del messaggio

Questo record ottiene un riepilogo degli attributi del messaggio durante la scansione dei messaggi in un contenitore dei messaggi.

Nella MAPI, viene supportato solo il tipo MsgReference.

Tutti i tipi vengono supportati nel Protocollo di posta Internet tranne Priority.

Questo esempio mostra gli attributi del messaggio di riepilogo.

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

Le descrizioni dei tipi utilizzati nell'esempio precedente vengono qui elencate.

In assenza di accordi privati tra il mittente e i destinatari di un messaggio, si consiglia di utilizzare i membri delle serie ISO-8859-* al posto di altre serie di caratteri.

Record di filtraggio

Questo record viene utilizzato per filtrare il tipo di messaggi richiamati durante il processo di scansione dei messaggi.

Nè la MAPI ne l'SMTP/POP supportano il filtraggio.

Il seguente esempio mostra gli attributi del 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; 

Le descrizioni dei tipi utilizzati nell'esempio precedente vengono qui elencate.

Vengono inoltre accettati i valori aggiuntivi definiti dall'utente.

MAILInfoRec

La struttura del record MAILInfoRec viene utilizzata nella funzione MAILQueryDefaults per ricevere i valori del sistema di posta di default.
Il seguente esempio mostra come funziona la struttura 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;

Le descrizioni dei tipi utilizzati nell'esempio precedente vengono qui elencate.

Rubriche

Il TSD Script consente di elencare i nomi dei destinatari dei messaggi in una rubrica. (Le rubriche non sono supportate nella MAPI o nel SMTP/POP.) Inoltre, il TSD Script non supporta le rubriche nidificate.

Il record seguente viene utilizzato per richiamare le voci nella rubrica.

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

Nota: Gli utenti finali non possono modificare una rubrica.

Le descrizioni dei tipi utilizzati nell'esempio precedente vengono qui elencate.

Implementazione dell'interfaccia TSD Script Mail

Questa sezione guida l'utente lungo il processo di implementazione di un piccolo programma TSD Script di esempio (inviare mail.kb). Questo programma invia un messaggio di posta da un utente il cui ID è "BILL" ad un utente il cui ID utente è "JOHN."

Aggiunta dell'Interfaccia TSD Script Mail ad un programma TSD Script

I programmi TSD Script possono utilizzare l'interfaccia TSD Script Mail aggiungendo il modulo TSD Script Mail alla sezione utilizzi di un file .kb (knowledgebase).
Il modulo TSD Script Mail si trova nel file mail.kb ed è stato installato automaticamente nella directory in cui è stato installato il Developer's Toolkit. Il file mail.kb contiene la definizione delle strutture dei record, delle costanti e dei codici di ritorno utilizzati dalle funzioni TSD Script Mail.

Il seguente frammento di codice illustra il primo passo per l'aggiunta dell'interfaccia TSD Script Mail ad un programma:

Knowledgebase SENDMAIL; 
USES
    mail; 
PUBLIC 
PROCEDURE SendMailMessage; 
PRIVATE 
    ROUTINES 
PROCEDURE SendMailMessage IS 
ACTIONS 
    (*Body of procedure *) 
      END; 

Inizializzazione dell'interfaccia TSD Script Mail

Prima di chiamare una qualsiasi delle funzioni TSD Script Mail, un'applicazione deve chiamare prima l'istruzione MAILInitialize. Questa funzione inizializza le risorse e le strutture dei dati utilizzate dall'interfaccia di posta TSD Script.

L'istruzione MAILInitialize deve specificare come parametri propri il protocollo che utilizzerà:

Dopo aver inizializzato l'interfaccia TSD Script Mail, è possibile aprire un qualsiasi numero di sessioni di posta nel suo interno.

MAILInitialize(OMI_VIM_INTERFACE)

Nota: Dopo aver chiamato MailInitialize con esito positivo, è necessario chiamare sempre MailTerminate prima di uscire dal programma.

Apertura di una sessione

Dopo aver inizializzato l'Interfaccia TSD Script Mail, è possibile aprire una sessione con l'istruzione MAILOpenSession. MAILOpenSession richiede:

Il seguente codice di esempio:

Nota: In OS/2, utilizzare OMISEL_CP850. In Windows, utilizzare OMISEL_CP1252.

E' possibile inoltre inoltrare $Unknown, e il sistema utilizza la serie di caratteri di default.

Nota: Utenti di Microsoft Windows 95/98: Consultare la sezione Note dell'istruzione MailOpenSession nel Riferimento Lingua del TSD Script.

Per ogni stato di errore, utilizzare l'istruzione MailGetLastErrorType.

PROCEDURE SendMailMessage 
VARIABLES 
    sessID:MailSession; 
    rc:Integer; 
ACTIONS 
    rc := MAILInitialize(OMI_VIM_INTERFACE); 
     IF (rc <> KML_SUCCESS) THEN 
         WinMessageBox($desktop, 'error', $MBOK,
                       'Error in MAILInit. 
                        Error code is ' & rc <); 
      Exit; 
      END; 
     rc:= MAILOpenSession('M:\APPS\CCMAIL\CCDATA',
                          'BILL','K2K2', OMISEL_CP850,
                           sessID,OMI_VIM_INTERFACE);
     IF (rc <> KML_SUCCESS) THEN 
         WinMessageBox($desktop, 'error', $MBOK,
                       'Error in MAILInit. 
                        Error code is ' & rc <); 
         MailTerminate(OMI_VIM_INTERFACE);
      Exit; 
      END; 
        (* Send the message *) 
     rc := MAILCloseSession(sessID); 
     IF (rc <> KML_SUCCESS) THEN 
         WinMessageBox($desktop, 'error', $MBOK,
                       'Error in MAILInit. 
                        Error code is ' & rc <); 
         MailTerminate(OMI_VIM_INTERFACE); 
      Exit; 
      END; 
     rc := MAILTerminate(OMI_VIM_INTERFACE); 
      END; 

Ora è aperta una sessione valida. Prima di poter inviare un messaggio, tuttavia, è necessario compiere alcuni passi:

  1. Inizializzare il record di intestazione del messaggio.
  2. Inizializzare l'elenco dei destinatari.
  3. Specificare l'elenco dei destinatari.
  4. Specificare l'elenco delle voci dei messaggi.

Inizializzazione dell'intestazione dei messaggi

Nel seguente esempio, vengono inizializzati solo i campi Subject e Priority della struttura del record MAILSendHeader. Tutti gli altri campi vengono lasciati $Unknown.

msgHeader:MAILSendHeader; 
msgHeader.Subject := 'Floor Plan'; 
msgHeader.Priority := OMI_HIGH_PRIORITY; 

Inizializzazione dell'elenco dei destinatari

Si supponga di voler inviare un messaggio ad un destinatario di nome John. L'elenco dei destinatari è composto da un solo elemento, l'indirizzo "JOHN."

Come spiegato nell'esempio, toList è un elenco di record MAILName.

toList:LIST of MAILName; 
toRecipient:MAILName;

Specifica di un destinatario

Esistono due modi per specificare un destinatario: indirizzo o nome.

Il record MailName ha un tipo denominato EntityType e si riferisce al tipo di destinatario. Se il destinatario è un singolo utente o programma, EntityType deve avere il valore OMISEL_ENTITY. Se il destinatario del messaggio è un gruppo (come ad esempio elenco di posta) EntityType deve avere il valore OMISEL_GROUP.

Specifica di un destinatario per nome

Se si specifica un destinatario per nome, è necessario inizializzare i seguenti tipi nel record MAILName:

La voce nel tipo NameType si basa sul nome dell'applicazione di messaggistica. Ad esempio:

Specifica di un destinatario per indirizzo

Se si specifica un destinatario per indirizzo, è necessario inizializzare i campi AddressType e Address del record MAILName.

Il campo AddressType si riferisce al tipo dell'indirizzo. Ad esempio: OMISEL_CCMAIL, OMISEL_NOTES, OMISEL_MHS e così via. E' possibile trovare un elenco completo di AddressType nelle descrizioni del tipo riportate di seguito in questo capitolo.

Il tipo Address contiene la stringa di indirizzo nel formato dettato dal tipo AddressType. Consultare la documentazione del fornitore del programma di posta VIM per il formato dell'indirizzo corretto.

SMTP/POP richiede che un destinatario venga specificato per indirizzo. Il campo name è facoltativo.

Nota:
Quando MAILReadMessage legge i messaggi, l'istruzione completa i tipi di specifica Name e Address del record MAILName durante il richiamo dei messaggi.

L'istruzione, msgCntnr, punta sulla Inbox quando viene utilizzata per il supporto SMTP/POP3. Come spiegato in questo frammento di codice, specificare il destinatario per nome e utilizzare la rubrica di default:

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

Nota: Le istruzioni toList e ccList possono essere dichiarate allo stesso modo.

Specifica dell'elenco delle voci dei messaggi

Il passo seguente consiste nel creare l'elenco delle voci dei messaggi. E' necessario specificare le seguenti voci:

Questo programma di esempio comprende l'elenco delle voci dei messaggi:

(* Build the message items list *) 
    (* First item is a note part *) 
Item.Class      := OMISEL_NOTE_PART; 
    Item.Type       := OMI_TEXT; 
    Item.Name       := 'Title for the 
                       note part'; 
    Item.BufferType := OMI_ACTUAL_DATA; 
    Item.BufferData := 'Hi John. I have' & 
                       'enclosed the floor' &
                       'plan layout in the' & 
                       'file attachment. ';
    Name.Address    := 'JOHN/ACME CORPORATION'
    ListInsert(Items, Item, $After);
   (* Second item is a file attachment *)
Item.Class      := OMISEL_ATTACH;
    Item.Name       := 'image.pcx';
    Item.BufferType := OMI_FILE_DATA;
    Item.BufferData := 'D:\TMP\PAPANIM.PCX';
    ListInsert(Items, Item, $After);

Nota: Un esempio SMTP/POP per Name.Address appare come quello di seguito riportato:

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

Scrittura della procedura SendMailMessage

La procedura SendMailMessage può essere scritta come di seguito mostrato.

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, 'error', $MBOK,
                       'Error in MAILInit. 
                        Error code is ' & rc <); 
      Exit; 
      END; 
    rc:= MAILOpenSession('M:\APPS\CCMAIL\CCDATA', 
                          'BILL','K2K2', 
                     OMISEL_CP850, sessID,
OMI_VIM_INTERFACE); 
                IF (rc < 1) THEN 
         WinMessageBox($desktop, 'error', $MBOK,
                       'Error in MAILInit. 
                        Error code is ' & rc <); 
         MailTerminate(OMI_VIM_INTERFACE); 
      Exit; 
          END; 
    (* Send the message *) 
    (* Set the header record *) 
    header.subject := 'Floor Plan'; 
    header.Priority := OMI_HIGH_PRIORITY; 
    (* Build the message items list *) 
    (* First item is a note part *) 
    Item.Class      := OMISEL_NOTE_PART; 
    Item.Type       := OMI_TEXT; 
    Item.Name       := 'Title for
                      the note part'; 
    Item.BufferType := OMI_ACTUAL_DATA; 
    Item.BufferData := 'Hi John. I have enclosed'& 
                       'the floor plan layout in'& 
                       'the file attachment. '; 
    ListInsert(Items, Item, $After); 
    (* Second item is a file attachment *) 
    Item.Class      := OMISEL_ATTACH; 
    Item.Name       := 'image.pcx'; 
    Item.BufferType := OMI_FILE_DATA; 
    Item.BufferData := 'D:\TMP\PAPANIM.PCX'; 
    ListInsert(Items, Item, $After); 
    (* Specify the recipient *) 
    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, 'error', $MBOK,
                       'Error in MAILInit. 
                        Error code is ' & rc <); 
        ELSE ('Mail sent successfully'); 
      END; 
    rc := MAILCloseSession(sessID); 
            IF (rc < 1) THEN 
         WinMessageBox($desktop, 'error', $MBOK,
                       'Error in MAILInit. 
                       Error code is ' & r <); 
         MailTerminate(OMI_VIM_INTERFACE); 
      Exit; 
      END; 
    rc := MAILTerminate(OMI_VIM_INTERFACE); 
      END; 

Lettura dei messaggi nel contenitore dei messaggi

L'interfaccia TSD Script Mail può leggere i messaggi nel contenitore dei messaggi. La lettura dei messaggi è un procedimento composto da due fasi:

Nota: I filtri non sono supportati per SMTP/POP3.

Il seguente esempio mostra un programma che riceve la posta:

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,'Error',$MBIconError,
                'Open session failed: '&rc);
     MAILTerminate(OMI_SMTP_POP_INTERFACE);
    EXIT;
      END;
 rc:=MAILOpenMessageContainer (sess,
                              'c:\mail\inbox.idx',
                               msgContainer);
              IF rc < 1 THEN
             WinMessageBox($Desktop,'Error',$MBIconError,
                 'Open container failed: '&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,'Error',$MBOK,
                   'Scan failed: '&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,'Error',$MBIconError,
                          'File Open failed: '&rc);
                EXITLoop;
      ELSE
             FWriteLn(outfile, 'Number Read: ' & 
                      numMessages);
            FOR msgSummary DO
                 summRec := msgSummary[$Current];
                 FWriteLn(outfile, 'Message Type: ' &
                          summRec.Type);
                 FWriteLn(outfile, 'Unread Mail: ' &
                          summRec.UnreadMail);
                 FWriteLn(outfile, 'FromName: ' &
                          summRec.FromName);
                 FWriteLn(outfile, 'FromAddress ' &
                          summRec.FromAddress);
                 FWriteLn(outfile, 'Priority: ' &
                          summRec.Priority);
                 FWriteLn(outfile, 'Subject: ' &
                          summRec.Subject);
                 msgRef := summRec.MSGReference;
                rc := MAILReadMessage(msgContainer,msgRef,
                                      0,msgHeader,
                                     msgItems,toList,
                                     ccList,bccList,
                                      nestedMsg);
              IF rc < 1 THEN
                WinMessageBox($Desktop,'Error',
                              $MBIconError,
                              'ReadMessage failed: '&rc);
          FClose(outfile); 
                EXITLoop; 
                     ELSE
                    MAILReleaseMessageReference
                        (msgContainer, msgSummary
                         [$Current].msgReference);
              FOR tolist DO
                 FWriteLn(outfile,'To Name: ' &
                          toList[$current].EntityName);
                 FWriteLn(outfile,'To Address: ' &
                          toList[$current].address);
      END;
              FWriteLn(outfile, ' ***Message Items**** ');
                 FOR msgItems DO
            FWriteLn(outfile,msgItems
                     [$current].Type);
            FWriteLn(outfile,msgItems
                     [$current].Name);
            FWriteLn(outfile,msgItems
                     [$current].BufferData);
      END;
            FWriteLn(outfile, 
                    '*********************************
                     ******************* ');
            END; (*End of Else*)
          END; (*End of For LOOP*)
          FClose(outfile); 
       END;(*End of Else*)
    END;(*End of IF*)
 UNTIL TRUE;
 MAILCloseMessageContainer(msgContainer);
 MAILCloseSession(sess);
     MAILTerminate(OMI_SMTP_POP_INTERFACE);
 WinMessageBox($Desktop,'Program Complete',$MBOK,
              'Execution is complete. 
               Check for output.');
      END;

Chiusura di una sessione TSD Script Mail

E' possibile avere più sessioni TSD Script Mail aperte contemporaneamente.

Per chiudere una sessione TSD Script Mail, chiamare l'istruzione MAILCloseSession. Questo rilascia le risorse associate alla sessione TSD Script Mail.

Chiusura dell'interfaccia TSD Script Mail

Quando si è pronti a chiudere l'interfaccia TSD Script Mail, è necessario chiudere innanzitutto tutte le sessioni TSD Script Mail aperte. Quindi è necessario chiamare l'istruzione MAILTerminate.

Codici di ritorno TSD Script Mail

Questa sezione elenca i possibili codici di errore che possono verificarsi dalle istruzione dell'interfaccia TSD Script Mail. Gli errori possono verificarsi in diversi punti durante l'elaborazione dei messaggi, nel layer VIM o MAPI o nel layer TSD Script. Le seguenti tabelle descrivono i codici di errori che possono verificarsi in ognuno di questi layer.

Nota: Tutte le chiamate dell'interfaccia TSD Script Mail restituiscono il valore 1 se una funzione viene eseguita con esito positivo. In caso contrario, viene restituito un numero negativo.

Codici di errore creati nel layer VIM

L'elenco di seguito riportato elenca in modo dettagliato i possibili codici di errore che possono essere creati dal layer VIM.

Errore Valore Commento
OMISTS_FAILURE -1 Errore generale.
OMISTS_FATAL -2 Si è verificato un errore irreversibile. Impossibile utilizzare il sistema fino a quando non
si corregge il problema.
OMISTS_ALL_PARAMS_REQUIRED -3 MAILOpenSession restituisce questo messaggio quando un
percorso, un nome e la password sono richiesti dal sistema di messaggistica.
OMISTS_ATTACHMENT_NOT_FOUND -4 Il file allegato specificato (in MAILSendMessage)
non è stato rilevato.
OMISTS_BAD_PARAM -5 Un parametro richiesto è sconosciuto, un parametro non è
compreso nell'intervallo o un parametro non è valido.
OMISTS_BUF_TOO_SMALL -6 L'interfaccia TSD Script Mail utilizza i buffer per richiamare
i valori dal sistema di messaggistica. Questo codice di ritorno
implica che il buffer utilizzato era troppo piccolo per contenere il valore restituito.
OMISTS_CONV_NOT_SUPPORTED -7 La conversione specificata non è supportata in questa implementazione.
OMISTS_INSUFFICIENT_MEMORY -8 Operazione interna non riuscita a causa di
memoria disponibile insufficiente.
OMISTS_INVALID_CONFIGURATION -9 E' stata rilevata una configurazione non valida.
OMISTS_INVALID_OBJECT
-10 L'handle degli oggetti (MAILSession, MAILContainer, MAILRef) era sconosciuto o non valido. Ad
esempio, un'handle per un messaggio non di posta non può essere
inoltrato alle funzioni che prevedono un messaggio di posta.
OMISTS_INVALID_PASSWORD -11 E' stata inoltrata una password non valida a MAILOpenSession.
OMISTS_INVALID_SELECTOR -12 Un selettore (OMISEL_*) è stato inoltrato all'istruzione
ma non è riconosciuto in questo contesto.
OMISTS_INVALID_SIGNATURE -13 E' stata inoltrata una firma non valida a MAILVerifySignature,
oppure il messaggio è stato compromesso.
OMISTS_NAME_EXISTS -14 Questo codice di ritorno non viene utilizzato in VIM.
OMISTS_NAME_NOT_FOUND -15 MAILSendMessage ha convalidato immediatamente il nome del destinatario e il nome non è stato rilevato nella rubrica specificata. (Se nessuna rubrica è stata specificata,
viene utilizzata la rubrica di default.)
OMISTS_NOT_SUPPORTED -16 La funzione richiamata non è supportata da questa implementazione.
OMISTS_NO_COMMON_CERTIFICATES -17 MAILVerifyMessage La firma non documenta alcun certificato comune tra il destinatario e il firmatario.
OMISTS_NO_DEFAULT -18 MAILGetEntityName non è in grado di scegliere tra diverse sessioni attive. Alcune implementazioni possono restituire il
nome della sessione che è stata attiva per il periodo di tempo
più lungo, invece che un codice di errore
OMISTS_NO_MATCH -19 Nessuna corrispondenza rilevata.
OMISTS_NO_SIGNATURE -20 MAILVerifyMessage documenta che il
messaggio specificato non ha una firma.
OMISTS_NO_SUCH_ATTRIBUTE -21 L'attributo chiamato non viene utilizzato.
OMISTS_OPEN_FAILURE -22 Si è verificato un errore dipendente dalla piattaforma durante l'apertura o la creazione di un file.
OMISTS_PASS_REQUIRED -23 MAILOpenSession indica che è necessaria una password
per aprire una sessione in questa implementazione.
OMISTS_READ_FAILURE -24 Si è verificato un errore dipendente dalla piattaforma durante l'apertura o la creazione di un file.
OMISTS_UNSUP_TYPE -25 MAILSendMessage o MAILSendDerived Message è stato inoltrato ad un tipo di messaggio diverso da VIM_MAIL che
non è supportato da questa implementazione. Oppure, MAILReadMessage non supporta la lettura di questo
tipo di voce.
OMISTS_UNSUP_VERSION -26 Mancata messa in corrispondenza dell'Interfaccia TSD Script Mail e
dell'interfaccia VIM.
OMISTS_WRITE_FAILURE -27 Si è verificato un errore dipendente dalla piattaforma durante la scrittura di un file.

Codici di errore creati dal layer MAPI

L'elenco di seguito riportato elenca in modo dettagliato i possibili codici di errore che possono essere creati dal layer MAPI.

Errore Valore Commento
MAPI_USER_ABORT -201 L'utente ha annullato il processo. La funzione non è stata completata.
MAPI_E_FAILURE

-202 Si è verificato uno o più errori non specificati. La funzione
non è stata completata.
MAPI_E_LOGIN_ FAILURE

-203 L'utente non è riuscito a collegarsi con esito positivo. Nessun identificativo
di sessione restituito.
MAPI_E_DISK_FULL
-204 Il disco è pieno.
MAPI_E_INSUFFICIENT
_MEMORY

-205 Memoria insufficiente per procedere. La funzione
non è stata completata.
MAPI_E_TOO_MANY_SESSIONS

-208 Troppe sessioni aperte contemporaneamente.
MAPI_E_ TOO_MANY_FILES -209 Troppi allegati dei file.
MAPI_E_ TOO_MANY_RECIPIENTS -210 Troppi destinatari dei messaggi specificati.
MAPI_E_ATTACHMENT_NOT
_FOUND
-211 Uno o più file da allegare al
messaggio non sono stati trovati.
MAPI_E_ ATTACHMENT_OPEN_FAILURE -212 Uno o più file da allegare al
messaggio non possono essere aperti.
MAPI_E_ ATTACHMENT_WRITE_FAILURE -213 Un allegato non può essere scritto su un file temporaneo.
Controllare i diritti della directory.
MAPI_E_UNKNOWN_RECIPIENT -214 Il destinatario non è stato trovato all'interno dell'elenco degli indirizzi.
MAPI_E_BAD_RECIPTYPE -215 Nessun tipo di destinatario specificato, oppure non è valido.
MAPI_E_INVALID_MESSAGE -217 Il numero di riferimento del messaggio non è valido.
MAPI_E_TEXT_TOO_LARGE -218 Il testo del messaggio è troppo lungo.
MAPI_E_INVALID_SESSION -219 L'identificativo della sessione non è valido.
MAPI_E_TYPE_NOT
_SUPPORTED
-220 Uno o più tipi non sono supportati da questa implementazione.
MAPI_E_AMBIGUOUS
_RECIPIENT
-221 Uno o più dei destinatari è ambiguo.
MAPI_E_INVALID_RECIPS -225 Uno o più dei destinatari non è valido.
MAPI_E_NOT_SUPPORTED -226 Questa funzione non è supportata dall'implementazione.


Codici di errore creati da SMTP

La tabella di seguito riportata elenca i codici di errore che possono essere creati da SMTP.

Errore Valore Commento
OMI_ERR_SMTP_OPENSESSION
_FAILURE
-3000 Impossibile inizializzare tutti i dati in MAILOpenSession(..).
OMI_ERR_SMTP_MAIL
_FAILURE
-3001 Impossibile inviare il comando mail al server SMTP.
OMI_ERR_SMTP_CLOSE
_FAILURE
-3002 Impossibile inviare il comando close al server SMTP.
OMI_ERR_SMTP_VERIFY
_FAILURE
-3003 Il server SMTP non può verificare un utente nell'elenco dei destinatari.
OMI_ERR_ATTACH_FILE
_ERROR
-3004 Il file specificato come allegato non esiste o il
nome file è nel formato non corretto.
OMI_ERR_SMTP_OPEN_SERVER
_FAILURE
-3005 Impossibile aprire la connessione con il server SMTP.
OMI_ERR_POP_OPEN_FAILURE -3006 Impossibile aprire la connessione con il server POP.
OMI_ERR_INVALID_PASSWORD -3007 Verifica della password non riuscita.
OMI_ERR_POP_STAT_FAILURE -3008 Impossibile inviare il comando stat al server POP.
OMI_ERR_POP_RETR_FAILURE -3009 Impossibile inviare il comando retr al server POP.
OMI_ERR_POP_DELE_FAILURE -3010 Impossibile inviare il comando delete al server POP.
OMI_ERR_POP_QUIT_FAILURE -3011 Impossibile inviare il comando quit al server POP.
OMI_ERR_SOCKET_FAILURE -3012 Chiamata socket non riuscita.
OMI_ERR_PARSE_MESSAGE
_FAILURE
-3013 Chiamata del messaggio di analisi non riuscita.
OMI_ERR_INVALID_FILE -3014 La dimensione del file è 0.
OMI_ERR_SERVICE_NOT
_AVAILABLE
-3421 Questa può essere una risposta ad ogni comando SMTP se il servizio è a conoscenza della sua chiusura.
OMI_ERR_MAILBOX_BUSY -3450 La mailbox può essere piena.
OMI_ERR_LOCAL_ERROR_IN
_PROCESSING
-3451 Azione richiesta annullata a causa di un errore locale nell'elaborazione.
OMI_ERR_INSUFFCIENT
_SYSTEM_STORAGE
-3452 Azione richiesta annullata a causa di memoria di sistema insufficiente.
OMI_ERR_SYNTAX_ERROR -3500 Errore di sintassi, comando non riconosciuto.
OMI_ERR_SYNTAX_ERROR_IN
_PARAMETER
-3501 Errore di sintassi nei parametri o negli argomenti.
OMI_ERR_COMMAND_NOT
_IMPLEMENTED
-3502 Comando non implementato.
OMI_ERR_SEQUENCE_ERROR -3503 Sequenza di comando non corretta.
OMI_ERR_PARAMETER_NOT
_IMPLEMENTED
-3504 Parametro dei comandi non implementato.
OMI_ERR_MAILBOX
_UNAVAILABLE
-3550 Azione richiesta non eseguita: mailbox non disponibile.
OMI_ERR_USER_NOT_LOCAL -3551 Utente non locale; tentare con <altro percorso>
OMI_ERR_EXCEEDED
_STORAGE_ALLOCATION
-3552 Azione richiesta per la posta annullata: assegnazione di memoria superata.
OMI_ERR_MAILBOX_NAME
_NOT_ALLOWED
-3553 Nome mailbox non abilitato
OMI_ERR_TRANSACTION
_FAILED
-3554 Transazione non riuscita
OMI_ERR_SOCKET_ERROR -3099 Errore di comunicazione socket

Codici di errore creati dal TSD Script

L'elenco di seguito riportato elenca in modo dettagliato i possibili codici di errore che possono essere creati dal TSD Script.

Errore Valore Commento
OMI_ERR_INVALID_BUFFER
_TYPE
-2000 Tipo di buffer non valido specificato nel record della voce
Mail.
OMI_ERR_INVALID_BUFFER
_DATA
-2001 Dati buffer non validi.
OMI_ERR_NO_MEMORY -2002 Risorse di memoria del sistema esaurite.
OMI_ERR_INVALID_FILENAME -2003 Nome file non valido.
OMI_ERR_NO_TOLIST -2004 Nessun elenco di destinazioni specificato.
OMI_ERR_BAD_PARAM -2005 E' stato specificato un parametro non corretto.
OMI_ERR_NO_NESTED
_MESSAGE
-2006 Nessun messaggio nidificato rilevato nel livello richiesto.
OMI_ERR_TOO_MANY_FILE
_NAMES
-2007 Troppi nomi di file specificati.
OMI_ERR_UNSUPPORTED
_PROTOCOL
-2008 Il valore per l'argomento del protocollo non è valido o
questo protocollo non è supportato.
OMI_ERR_UNSUPPORTED
_FEATURE
-2009 Questa funzione non è disponibile in questa implementazione.
OMI_ERR_NOT_IMPLEMENTED -2010 Questa funzione non è stata implementata.
OMI_ERR_UNKNOWN_ITEM
_CLASS
-2011 La classe della voce è sconosciuta.
OMI_ERR_INVALID_NOTE_PART -2012 La parte della nota del messaggio non è valida.
OMI_ERR_MAPI_FAILURE -2013 Si è riscontrato un errore nella programmazione dell'interfaccia MAPI.
OMI_ERR_NOT_INITIALISED -2014 L'interfaccia per la posta non è stata inizializzata. MailInitialize deve essere chiamata prima di utilizzare l'interfaccia TSD Script Mail.
OMI_ERR_COULD_NOT_LOAD
_DLL
-2015 TSD Script Mail non può essere caricato nella DLL MAPI o VIM.
KML_ERR_UNKNOWN_ITEM
_CLASS
-5000 E' stata specificata una classe di voce sconosciuta.
KML_ERR_UNKNOWN_ITEM
_TYPE
-5001 E' stato specificato un tipo di voce sconosciuto.
KML_ERR_UNKNOWN_BUFFER_TYPE -5002 E' stato specificato un tipo di buffer sconosciuto.
KML_ERR_UNKNOWN_BUFFER_DATA -5003 Sono stati specificati dei dati di buffer sconosciuti.

Costanti TSD Script Mail

Di seguito vengono elencate le costanti di TSD Script Mail valide.

Costante Valore
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

File Mail.kb

File TSD Script Mail

Il file mail.kb completo può essere rilevato nella directory in cui è stato installato il Developer's Toolkit.


Manuale per la programmazione Tivoli Service Desk 6.0 Developer's Toolkit Script

Ritorna all'Indice analitico

Copyright