Tivoli Service Desk 6.0 Developer's Toolkit Script Programming Guide

Chapter 9:The Tivoli Service Desk (TSD) Script Mail Interface

Back to Table of Contents


Introduction

Electronic mail (e-mail) is one of the fastest growing software application areas. Both the Internet and organizational intranets depend on e-mail as a viable communications agent.

E-mail allows several varieties of communication:

Store and forward mechanism

One of the advantages provided by an e-mail network is the store and forward mechanism.

The store and forward mechanism allows one user to send a message to a second user, even if the second user is not logged into the e-mail network.

The server stores the message sent by the first user and forwards it to the second user when he or she checks his or her mailbox. This allows for asynchronous communication between the two users. Asynchronous communication means that the communications operation proceeds independent of timing.

Communications APIs

Most e-mail vendors publish their APIs (application programming interface) in formats that allow other vendors' applications to interface with their messaging infrastructure. An API is a set of routines that an application uses to request and carry out lower-level services in an operating system.

Using APIs allows software vendors to support specialized operations. This means, however, that an application using these API's must run in a proprietary system in order to take advantage of the messaging capabilities.

Note: The Internet Mail Protocol (SMTP/POP) is not an API.

The VIM protocol

Unlike vendor specific messaging API's, the VIM (vendor independent messaging) protocol is not dependent on vendor specific formats. Using the VIM protocol, a developer can write an application that runs on any platform and that supports the messaging features built into the application.

The VIM interface protocol was designed by the VIM Consortium, which includes the following members:

MAPI

Another popular e-mail protocol that the TSD Script language supports is MAPI (Mail Application Program Interface), a Microsoft product. MAPI exhibits similar functionality to VIM and allows mail communication in the same way that VIM does.

The TSD Script Mail interface communicates with both VIM and MAPI.

Note: The following statements are not supported for MAPI:

SMTP

Simple Mail Transfer Protocol (SMTP) provides mechanisms for the transmission of e-mail:

POP3

Post Office Protocol - version 3 (POP3) permits a workstation to access a maildrop dynamically on a server host. Usually, this means that the POP3 server allows a workstation to retrieve e-mail that the server is holding for it.

Note: The following statements are not supported for SMTP and POP3:

Using TSD Script Mail with Protocols

The TSD Script Mail interface provides progammers with a means to develop mail-enabled applications. Presently, the interface supports three protocols:

The TSD Script Mail interface allows flexibility in building applications as summarized below:

Uses of the TSD Script Mail interface

Using the TSD Script Mail interface, you can create TSD Script programs to do the following:

TSD Script Mail Interface Terms

This section introduces some of the terms that are used to describe the implementation of the TSD Script Mail interface.

Address books

An address book is the location where user information, addresses, mailing lists, and so on are stored. Typically, a mail administrator manages the address book.

There are two types of address books: public and private.

The TSD Script Mail interface supports the ability to read a public address book only for the VIM protocol.

Entity

An entity is a person or program that sends or receives e-mail messages.

File attachments

File attachments are files that can be attached to a message. Attached files can be of any format. It is the responsibility of the sender and receiver to interpret the files correctly.

Inbox

The inbox is a special file that supports reading and marking messages under the POP3 protocol. It stores messages retrieved from the POP3 server and provides a mechanism for the messages to be marked as read or unread.

MsgCntnr serves as a parameter pointer to the inbox for SMTP/POP3.

Mail administrator

The mail administrator is the person who is responsible for overseeing the mail server. This person may be responsible for managing user accounts and managing the volume of messages stored on the network.

Mailbox

A mailbox is the physical location that is assigned to an individual entity. The mailbox stores messages when they are delivered. The mailbox may also be referred to as a message container.

Message

A message is any object that can be transported over a messaging system and stored in the message container.

Message client

A message client is an interface that allows an end user to do the following:

Message container

A message container is the storage location for received messages. This is synonymous with mailbox.

Message header

A message header is a header that contains information regarding the:

Message items

A message item is a list of items. A message item can be of two types:

Message type

A message type defines the format and semantics of the message contents.

Note parts

Note parts are actual components of a message and several types are supported by the VIM protocol.

The TSD Script Mail interface supports only text note parts.

Server

The server is the portion of the messaging system that handles the following tasks:

The server is also referred to as the "backend."

User address

The user address is the location of the message recipient's mailbox. Each messaging system has its own addressing format.

Message addressing is one of the most complex issues in developing a messaging application. The TSD Script Mail interface was developed to interface with all VIM-, MAPI-, and SMTP/POP-compliant messaging systems. Remember, however, that you must consider the requirements of the underlying messaging system that you are using when developing messaging applications or enhancements.

User ID

A user ID is a unique identifier assigned to an entity. This allows an entity to log on to the mail server.

TSD Script Mail Record Structures


The following sections are extracted from the TSD Script mail.kb file. For additional information, see the section, "Mail.kb File" at the end of this chapter.

Header File

The following types are defined for the TSD Script Mail interface. Depending on the implementation of your mail system, some of the types may be optional. EntityName and Address are the only types supported by the Internet Mail Protocol. SMTP/POP requires that Address be specified; EntityName is optional.

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; 

Descriptions of the types used in the preceding example are listed here.

Specifying message items

The following record is used to define a message item.

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

Descriptions of the types used in the preceding example are listed here.

In the absence of private agreements between sender and recipients of a message, it is recommended that members of the ISO-8859-* series be used in preference to other character sets.

Message header

This record contains the header information of a message to be sent.

In MAPI, only the Subject type is functional, which means that the other types are not supported.

The Internet Mail Protocol supports only the Subject and InReplyTo types.

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; 

Descriptions of the types used in the preceding example are listed here.

Note: The default setting is NORMAL.

In the absence of private agreements between sender and recipients of a message, it is recommended that members of the ISO-8859-* series be used in preference to other character sets.

Message attributes

This record sets the message header attributes while sending a message. Multi-valued header attributes are declared as lists.
In MAPI, the only types supported are:

The Internet Mail Protocol supports the following types:

The example that follows shows message header attributes.

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; 

Type descriptions for the preceding example are listed here.

In the absence of private agreements between sender and recipients of a message, it is recommended that members of the ISO-8859-* series be used in preference to other character sets.

Message summary

This record obtains a summary of the message attributes while scanning the messages in a message container.

In MAPI, only the MsgReference type is supported.

All types are supported in the Internet Mail Protocol except Priority.

This example shows summary message attributes.

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

Descriptions of the types used in the preceding example are listed here.

In the absence of private agreements between sender and recipients of a message, it is recommended that members of the ISO-8859-* series be used in preference to other character sets.

Filtering records

This record is used to filter the type of messages retrieved during the scan messages process.

Neither MAPI nor SMTP/POP supports filtering.

The following example shows filter attributes.

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; 

Descriptions of the types used in the preceding example are listed here.

Additional user-defined values are also accepted.

MAILInfoRec

The MAILInfoRec record structure is used in the MAILQueryDefaults function to receive the default mail system values.
The following example shows how the MailInfoRec structure works.

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

Descriptions of the types used in the preceding example are listed here.

Address books

TSD Script allows you to list the names of message recipients in an address book. (Address books are not supported in either MAPI or SMTP/POP.) Also, TSD Script does not support nested address books.

The following record is used to retrieve the entries in the address book.

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

Note: End users are unable to modify an address book.

Descriptions of the types used in the preceding example are listed here.

Implementing the TSD Script Mail Interface

This section guides you through the process of implementing a small sample TSD Script program (send mail.kb). This program sends a mail message from a user whose ID is "BILL" to a user whose user ID is "JOHN."

Adding the TSD Script Mail interface to a TSD Script program

TSD Script programs can use the TSD Script Mail interface by adding the TSD Script Mail module to the uses section of a knowledgebase.
The TSD Script Mail module is found in the mail.kb file and was automatically installed in the directory where Developer's Toolkit was installed. The mail.kb file contains the definition of record structures, constants, and return codes used by the TSD Script Mail functions.

The following code fragment illustrates the first step in adding the TSD Script Mail interface to a program:

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

Initializing the TSD Script Mail interface

Before calling any of the TSD Script Mail functions, an application must first call the MAILInitialize statement. This function initializes the resources and data structures used by the TSD Script Mail interface.

The MAILInitialize statement must specify as its parameters the protocol that is going to be used:

After you initialize the TSD Script Mail interface, you may open any number of mail sessions within it.

MAILInitialize(OMI_VIM_INTERFACE)

Note: After MailInitialize has been called successfully, MailTerminate should always be called before exiting the program.

Opening a session

After you initialize the TSD Script Mail Interface, you can open a session with the MAILOpenSession statement. The MAILOpenSession requires:

The following example code:

Note: In OS/2, use OMISEL_CP850. In Windows, use OMISEL_CP1252.

You can also pass $Unknown, and the system uses the default character set.

Note: Microsoft Windows 95/98 users: Please see the Notes section of the MailOpenSession statement in the TSD Script Language Reference.

For any fail states, use the MailGetLastErrorType statement.

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; 

A valid session is now open. Before a message can be sent, however, several tasks must be accomplished:

  1. Initialize the message header record.
  2. Initialize the list of recipients.
  3. Specify the list of recipients.
  4. Specify the list of message items.

Initializing the message header

In the following example, only the Subject and Priority fields of the MAILSendHeader record structure are initialized. All the other fields are left as $Unknown.

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

Initializing the list of recipients

Suppose that you want to send a message to a recipient named John. The recipient list consists of only one element, the address "JOHN."

As shown in this example, the toList is a list of MAILName records.

toList:LIST of MAILName; 
toRecipient:MAILName;

Specifying a recipient

There are two ways to specify a recipient: address or name.

The MailName record has a type called EntityType and refers to the type of recipient. If the recipient is a single user or program, the EntityType must be assigned the value OMISEL_ENTITY. If the recipient of the message is a group (such as a mailing list) then the EntityType must be assigned the value OMISEL_GROUP.

Specifying a recipient by name

If you specify a recipient by name, you must initialize the following types in the MAILName record:

The entry in the NameType type is based on the name of the messaging application. For example:

Specifying a recipient by address

If you specify a recipient by address, you must initialize the AddressType and Address fields of the MAILName record.

The AddressType field refers to the type of the address. For example: OMISEL_CCMAIL, OMISEL_NOTES, OMISEL_MHS, and so on. You can find a complete list of AddressType in the type descriptions found later in this chapter.

The Address type contains the address string in the format dictated by the AddressType type. Refer to the documentation from the vendor of your VIM e-mail tool for the correct address format.

SMTP/POP requires that a recipient be specified by address. The name field is optional.

Note:
When MAILReadMessage reads messages, the statement completes both the Name and Address specification types of the MAILName record while retrieving messages.

The statement, msgCntnr, points to the Inbox when used for SMTP/POP3 support. As shown in this code fragment, you specify the recipient by name and use the default address book:

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

Note: The statements toList and ccList can be declared in the same way.

Specifying the list of message items

The next task is to build the message item list. The following items must be specified:

This example program includes the message item list:

(* 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);

Note: An SMTP/POP example for Name.Address would look like the following:

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

Writing the SendMailMessage procedure

The SendMailMessage procedure can be written as shown.

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; 

Reading messages in the message container

The TSD Script Mail interface can read messages in the message container. Reading messages is two-step process:

Note: Filters are not supported for SMTP/POP3.

The following example shows a program that receives mail:

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;

Closing a TSD Script Mail session

It is possible to have multiple TSD Script Mail sessions open simultaneously.

To close a TSD Script Mail session, call the MAILCloseSession statement. This releases the system resources that were associated with the TSD Script Mail session.

Terminating the TSD Script Mail interface

When you are ready to terminate the TSD Script Mail interface, you must first close all open TSD Script Mail sessions. Then you need to call the MAILTerminate statement.

TSD Script Mail Return Codes

This section lists possible error codes that may occur from the TSD Script Mail interface statements. Errors may occur at several points during the message processing, either in the VIM or MAPI layer, or in the TSD Script layer. The following tables describe the error codes that may occur in each of these layers.

Note: All TSD Script Mail interface calls return the value 1 if a function executes successfully. Otherwise, a negative number is returned.

Error codes generated in the VIM layer

The list below details the possible error codes that may be generated by the VIM layer.

Error Value Comment
OMISTS_FAILURE -1 General failure.
OMISTS_FATAL -2 A fatal error occurred. Further system use is not
possible until the problem is corrected.
OMISTS_ALL_PARAMS_REQUIRED -3 MAILOpenSession returns this message when a
path, name, and password are all required by the underlying messaging system.
OMISTS_ATTACHMENT_NOT_FOUND -4 The attachment file specified (in a MAILSendMessage)
was not found.
OMISTS_BAD_PARAM -5 A required parameter was unknown, a parameter is
out of range, or a parameter is otherwise invalid.
OMISTS_BUF_TOO_SMALL -6 The TSD Script Mail interface uses buffers to retrieve
values from the messaging system. This return code
implies that the buffer used was too small to fit the value returned.
OMISTS_CONV_NOT_SUPPORTED -7 The specified conversion is not supported in this implementation.
OMISTS_INSUFFICIENT_MEMORY -8 An internal operation failed due to lack of available
memory.
OMISTS_INVALID_CONFIGURATION -9 An invalid underlying configuration was detected.
OMISTS_INVALID_OBJECT
-10 The object handle (MAILSession, MAILContainer, MAILRef) was unknown or otherwise invalid. For
example, a handle to a non-mail message may not be
passed to functions which expect a mail message.
OMISTS_INVALID_PASSWORD -11 A bad password was passed to MAILOpenSession.
OMISTS_INVALID_SELECTOR -12 A selector (OMISEL_*) was passed to the statement
that is unknown to this context.
OMISTS_INVALID_SIGNATURE -13 A bad signature was passed to MAILVerifySignature,
or the message has been compromised.
OMISTS_NAME_EXISTS -14 This return code is not used in VIM.
OMISTS_NAME_NOT_FOUND -15 MAILSendMessage validated the recipient name immediately and the name was not found in the specified address book. (If no address book was specified, the
default address book is used.)
OMISTS_NOT_SUPPORTED -16 The called feature is not supported by this implementation.
OMISTS_NO_COMMON_CERTIFICATES -17 MAILVerifyMessage Signature reports no common certificates between recipient and signer.
OMISTS_NO_DEFAULT -18 MAILGetEntityName is unable to choose among several active sessions. Some implementations may return the
name of the session that has been active for the longest
time, rather than return an error code
OMISTS_NO_MATCH -19 No match was found.
OMISTS_NO_SIGNATURE -20 MAILVerifyMessage Signature reports that the
specified message does not have a signature.
OMISTS_NO_SUCH_ATTRIBUTE -21 The called attribute is not used.
OMISTS_OPEN_FAILURE -22 A platform-dependent error occurred while opening or creating a file.
OMISTS_PASS_REQUIRED -23 MAILOpenSession reports that a password is required
to open a session in this implementation.
OMISTS_READ_FAILURE -24 A platform-dependent error occurred while opening or creating a file.
OMISTS_UNSUP_TYPE -25 MAILSendMessage or MAILSendDerived Message was passed a message type other than VIM_MAIL which
is not supported by this implementation. Or, MAILReadMessage does not support reading this
type of item.
OMISTS_UNSUP_VERSION -26 Mismatch of the TSD Script Mail Interface and the
underlying VIM interface.
OMISTS_WRITE_FAILURE -27 A platform-dependent error occurred while writing a file.

Error codes generated by the MAPI layer

The list below details the possible error codes that may be generated by the MAPI layer.

Error Value Comment
MAPI_USER_ABORT -201 The user cancelled the process. The function was not completed.
MAPI_E_FAILURE

-202 One or more unspecified errors occurred. The function
was not completed.
MAPI_E_LOGIN_ FAILURE

-203 The user failed to log on successfully. No session
identifier is returned.
MAPI_E_DISK_FULL
-204 The disk is full.
MAPI_E_INSUFFICIENT
_MEMORY

-205 There is insufficient memory to proceed. The function
was not completed.
MAPI_E_TOO_MANY_SESSIONS

-208 Too many sessions open at once.
MAPI_E_ TOO_MANY_FILES -209 There are too many file attachments.
MAPI_E_ TOO_MANY_RECIPIENTS -210 There are too many message recipients specified.
MAPI_E_ATTACHMENT_NOT
_FOUND
-211 One or more files that needed to be attached to the
message could not be found.
MAPI_E_ ATTACHMENT_OPEN_FAILURE -212 One or more files that needed to be attached to the
message could not be opened.
MAPI_E_ ATTACHMENT_WRITE_FAILURE -213 An attachment cannot be written to a temporary file.
Check directory rights.
MAPI_E_UNKNOWN_RECIPIENT -214 The recipient is not found in the address list.
MAPI_E_BAD_RECIPTYPE -215 No recipient type is specified, or is invalid.
MAPI_E_INVALID_MESSAGE -217 The message reference number is invalid.
MAPI_E_TEXT_TOO_LARGE -218 The message text is too long.
MAPI_E_INVALID_SESSION -219 The session identifier is invalid.
MAPI_E_TYPE_NOT
_SUPPORTED
-220 One or more of the types is not supported by this implementation.
MAPI_E_AMBIGUOUS
_RECIPIENT
-221 One or more of the recipients is ambiguous.
MAPI_E_INVALID_RECIPS -225 One or more of the recipients is invalid.
MAPI_E_NOT_SUPPORTED -226 This function is not supported by the underlying implementation.


Error codes generated by SMTP

The table below lists the error codes that may be generated by SMTP.

Error Value Comment
OMI_ERR_SMTP_OPENSESSION
_FAILURE
-3000 Failed to initialize all data in MAILOpenSession(..).
OMI_ERR_SMTP_MAIL
_FAILURE
-3001 Failed to send mail command to SMTP server.
OMI_ERR_SMTP_CLOSE
_FAILURE
-3002 Failed to send close command to SMTP server.
OMI_ERR_SMTP_VERIFY
_FAILURE
-3003 SMTP server cannot verify a user in the recipient list.
OMI_ERR_ATTACH_FILE
_ERROR
-3004 File specified as attachment either does not exist or
filename is in the incorrect format.
OMI_ERR_SMTP_OPEN_SERVER
_FAILURE
-3005 Failed to open connection with SMTP server.
OMI_ERR_POP_OPEN_FAILURE -3006 Failed to open connection with POP server.
OMI_ERR_INVALID_PASSWORD -3007 Password verification failed.
OMI_ERR_POP_STAT_FAILURE -3008 Failed to send stat command to POP server.
OMI_ERR_POP_RETR_FAILURE -3009 Failed to send retr command to POP server.
OMI_ERR_POP_DELE_FAILURE -3010 Failed to send delete command to POP server.
OMI_ERR_POP_QUIT_FAILURE -3011 Failed to send quit command to POP server.
OMI_ERR_SOCKET_FAILURE -3012 Socket call failed.
OMI_ERR_PARSE_MESSAGE
_FAILURE
-3013 Parse message call failed.
OMI_ERR_INVALID_FILE -3014 File size is 0.
OMI_ERR_SERVICE_NOT
_AVAILABLE
-3421 This may be a reply to any SMTP command if the service knows it must shut down.
OMI_ERR_MAILBOX_BUSY -3450 Mailbox may be busy.
OMI_ERR_LOCAL_ERROR_IN
_PROCESSING
-3451 Requested action aborted due to local error in processing.
OMI_ERR_INSUFFCIENT
_SYSTEM_STORAGE
-3452 Requested action aborted due to insufficient system storage.
OMI_ERR_SYNTAX_ERROR -3500 Syntax error, command unrecognized.
OMI_ERR_SYNTAX_ERROR_IN
_PARAMETER
-3501 Syntax error in parameters or arguments.
OMI_ERR_COMMAND_NOT
_IMPLEMENTED
-3502 Command not implemented.
OMI_ERR_SEQUENCE_ERROR -3503 Bad command sequence.
OMI_ERR_PARAMETER_NOT
_IMPLEMENTED
-3504 Command parameter not implemented.
OMI_ERR_MAILBOX
_UNAVAILABLE
-3550 Requested action not taken: mailbox unavailable.
OMI_ERR_USER_NOT_LOCAL -3551 User not local; please try <forward-path>
OMI_ERR_EXCEEDED
_STORAGE_ALLOCATION
-3552 Requested mail action aborted: exceeded storage allocation.
OMI_ERR_MAILBOX_NAME
_NOT_ALLOWED
-3553 Mailbox name not allowed
OMI_ERR_TRANSACTION
_FAILED
-3554 Transaction Failed
OMI_ERR_SOCKET_ERROR -3099 Socket communication error

Error codes generated by TSD Script

The list below details the possible error codes that may be generated by TSD Script.

Error Value Comment
OMI_ERR_INVALID_BUFFER
_TYPE
-2000 An invalid buffer type was specified in the Mail Item
record.
OMI_ERR_INVALID_BUFFER
_DATA
-2001 Invalid buffer data.
OMI_ERR_NO_MEMORY -2002 System memory resources exhausted.
OMI_ERR_INVALID_FILENAME -2003 Invalid file name.
OMI_ERR_NO_TOLIST -2004 No "To" list specified.
OMI_ERR_BAD_PARAM -2005 A bad parameter was specified.
OMI_ERR_NO_NESTED
_MESSAGE
-2006 No nested message found at the level requested.
OMI_ERR_TOO_MANY_FILE
_NAMES
-2007 Too many file names were specified.
OMI_ERR_UNSUPPORTED
_PROTOCOL
-2008 The value for the protocol argument is invalid or this
protocol is not supported.
OMI_ERR_UNSUPPORTED
_FEATURE
-2009 This feature is not available in this implementation.
OMI_ERR_NOT_IMPLEMENTED -2010 This feature has not been implemented.
OMI_ERR_UNKNOWN_ITEM
_CLASS
-2011 The item class is unknown.
OMI_ERR_INVALID_NOTE_PART -2012 The note part of the message is invalid.
OMI_ERR_MAPI_FAILURE -2013 An error was encountered in programming the MAPI interface.
OMI_ERR_NOT_INITIALISED -2014 The mail interface has not been initialized. MailInitialize must be called before using the TSD Script Mail interface.
OMI_ERR_COULD_NOT_LOAD
_DLL
-2015 TSD Script Mail could not load either the MAPI or the VIM DLL.
KML_ERR_UNKNOWN_ITEM
_CLASS
-5000 Unknown item class was specified.
KML_ERR_UNKNOWN_ITEM
_TYPE
-5001 Unknown item type was specified.
KML_ERR_UNKNOWN_BUFFER_TYPE -5002 Unknown buffer type was specified.
KML_ERR_UNKNOWN_BUFFER_DATA -5003 Unknown buffer data was specified.

TSD Script Mail constants

The following are the valid TSD Script Mail constants.

Constant Value
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

Mail.kb File

TSD Script Mail file

The complete mail.kb file can be found in the directory where Developer's Toolkit was installed.


Tivoli Service Desk 6.0 Developer's Toolkit Script Programming Guide

Back to Table of Contents

Copyright