Tivoli Service Desk 6.0 Developer's Toolkit Script Programming Guide
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:
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.
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.
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:
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:
Simple Mail Transfer Protocol (SMTP) provides mechanisms for the transmission of e-mail:
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:
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:
Using the TSD Script Mail interface, you can create TSD Script programs to do the following:
This section introduces some of the terms that are used to describe the implementation of the TSD Script Mail interface.
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.
An entity is a person or program that sends or receives e-mail messages.
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.
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.
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.
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.
A message is any object that can be transported over a messaging system and stored in the message container.
A message client is an interface that allows an end user to do the following:
A message container is the storage location for received messages. This is synonymous with mailbox.
A message header is a header that contains information regarding the:
A message item is a list of items. A message item can be of two types:
A message type defines the format and semantics of the message contents.
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.
The server is the portion of the messaging system that handles the following tasks:
The server is also referred to as the "backend."
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.
A user ID is a unique identifier assigned to an entity. This allows an entity
to log on to the mail server.
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.
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.
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.
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.
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.
Additional user-defined values are also accepted.
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.
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.
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.
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.
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.
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."
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;
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.
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:
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;
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;
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.
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:
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.
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'
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;
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;
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.
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.
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.
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. |
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. |
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 |
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. |
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 |
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