Tivoli Service Desk 6.0 Developer's Toolkit Script Language Reference
Return to Main Page
Returns the list of all entries in an address book.
FUNCTION MAILAddressBookEntries(VAL session: MAIL Session, VAL addrBookName: STRING, REF addrBookEntries: LIST of MAILABEntry): INTEGER;
Argument Name | Description |
session | Mail Session identifier. |
addrBookName | Name of the address book to open. The following symbolic names are
available as shortcuts to open standard address books:
|
addrBookEntries | List of MailABEntry records describing the entries in the given address book. |
This function is supported by VIM only.
VARIABLES session: MAILSession; AddressBookName: String; AddressBookEntries: LIST of MAILABEntry rc: Integer;
ACTION
AddressBookName := 'Private Mailing List'; rc := MAILAddressBooksEntries(session, AddressBookName, AddressBookEntries); IF rc = 1 THEN (* Address Book Entries available *) ELSE (* Error occurred in reading address book entries. *) END; END;
Return Code | Description |
1 | Successful completion |
Less than one | Error |
For a complete list of the TSD Script Mail error codes and a description of the MailSendHeader record, see the Tivoli Service Desk 6.0 Developer's Toolkit Programming Guide.
Returns a list of address book names available to the current session.
FUNCTION MAILAddressBooks(VAL session:MAILSession, REF AddrBooks: LIST of STRING): INTEGER;
Argument Name | Description |
session | Session identifier |
AddrBooks | List of address book names available to this session (returned value) |
This function is supported by VIM only.
VARIABLES session: MAILSession; rc: Integer; AddressBooks: LIST of String;
ACTIONS
(* A MAILSession is opened. *)
rc := MAILAddressBooks(session, AddressBooks); IF rc = 1 THEN (* The list of address book names available to this session is stored in AddressBooks *) ELSE (* Function failed *) END; END;
Return Code | Description |
1 | Successful completion |
Less than one | Error |
For a list of TSD Script Mail error codes and a description of the MailSendHeader record, see the Tivoli Service Desk 6.0 Developer's Toolkit Programming Guide.
Closes a message container.
FUNCTION MAILCloseMessageContainer(VAL msgContainer: MAILContainer): INTEGER;
Argument Name | Description |
msgContainer | Identifier of the open message container. |
VARIABLES msgContainer: MAILContainer;
ACTIONS
(* Message Container Opened and used *)
rc := MAILCloseMessageContainer(msgContainer); IF rc = 1 THEN (* Message container closed successfully *) ELSE (* Function failed *) END; END;
Return Code | Description |
1 | Successful completion. |
Less than one | Error. |
For a list of TSD Script Mail error codes and a description of the MailSendHeader record, see the Tivoli Service Desk 6.0 Developer's Toolkit Programming Guide.
Closes the session.
FUNCTION MAILCloseSession(REF session: MAILSession): INTEGER;
Argument Name | Description |
session | Identifies the session to close. |
All open mail sessions must close when those mail sessions are complete. Closing a session frees any system resources associated with the session. Failure to close an open session when a program terminates may result in memory loss.
Note: For a description of the MailSendHeader record structure, see the Tivoli Service Desk Developer's Toolkit Programming Guide.
VARIABLES rc: Integer; session: Integer;
ACTIONS rc := MAILOpenSession('F:\CCMAIL\CCDATA', 'VIMAPPLICATION', 'PASSWD', OMISEL_CP1252, session); IF rc <> 1 THEN (* Error in opening session *) ELSE
(* Perform some operations with the open session. *)
rc := MAILCloseSession(session); IF rc <> 1 THEN (* Error in closing session *) END; END; END;
Return Code | Description |
1 | Successful completion |
Less than one | Error |
For a list of TSD Script Mail error codes and a description of the MailSendHeader
record, see the Tivoli Service Desk 6.0 Developer's Toolkit
Programming Guide.
Returns the name of the user or the messaging application associated with the session specified in the session parameter.
FUNCTION MAILGetEntityName(VAL session: MAILSession, REF Name: MAILName): INTEGER;
Argument Name | Description |
session | Identifier of session from which the user name is desired. If $Unknown is specified, the default name of the user or messaging application is returned. If no default is available, an error is returned. |
Name | MailName record to receive the user's name. On return from this function, only the distinguished name portion of the MailName record is filled in. |
KNOWLEDGEBASE ERROR;
USES mail;
ROUTINES PROCEDURE Mail;
PRIVATE ROUTINES
PROCEDURE Mail IS
VARIABLES sess :MAILSession; reply :string; rc :INTEGER;
ACTIONS
rc:=MAILOpenSession ('mailserv.microsoft.com', 'bgates@microsoft.com', 'password',$UNKNOWN, sess,OMI_VIM_INTERFACE); IF rc < 1 THEN WinMessageBox ($Desktop,'Error',$MBIconError, 'Open session failed: '&rc);
MailGetLastErrorText(OMI_SMTP_POP_INTERFACE, sess,rc, rc, reply); WinMessageBox($Desktop,'Error',$MBIconError, 'Open session failed: '& reply); MAILTerminate(OMI_SMTP_POP_INTERFACE); EXIT; END;
END;
This function is supported by VIM only.
For a list of TSD Script Mail error codes and a description of the MailSendHeader record, see the Tivoli Service Desk 6.0 Developer's Toolkit Programming Guide.
Returns the error text associated with the last failed operation.
FUNCTION MAILGetLastErrorText( VAL protocol: INTEGER, VAL sessID: MAILSession, VAL errCode: INTEGER, REF LastErrCode: INTEGER, REF ErrText: STRING)
Argument Name | Description |
protocol | Identifies the protocol used to communicate with the mail system |
sessID | Identifies the session (return value MailOpenSession) |
errCode | Value of error code returned by last Mail function call |
LastErrCode | Error code returned by last Mail function call |
ErrText | Last error text is returned in this parameter |
This function is supported by VIM only.
For a list of TSD Script Mail error codes and a description of the MailSendHeader record, see the Tivoli Service Desk 6.0 Developer's Toolkit Programming Guide.
Initializes the TSD Script Mail interface. This should be the first function called before using any TSD Script Mail interface services.
MAILInitialize (VAL protocol:INTEGER): INTEGER
Argument Name | Description |
protocol | Identifies the protocol used to communicate with the mail system.
|
PROCEDURE SendMail IS VARIABLES SESS: MailSession; ACTIONS MAILInitialize(OMI_MAPI_INTERFACE);
(* Now open the session. *)
(* Do other processing. *)
MAILTerminate(OMI_MAPI_INTERFACE);
Return Code | Description |
1 | Successful completion. |
Less than one | Error. |
MailTerminate
For a list of TSD Script Mail error codes and a description of the MailSendHeader record, see the Tivoli Service Desk 6.0 Developer's Toolkit Programming Guide.
Marks a message as read.
FUNCTION MAILMarkMessageAsRead(VAL msgContainer: MAILContainer, VAL msgRef:MAILRef): INTEGER;
Argument Name | Description |
msgContainer | Message container identifier |
MsgRef | Message reference number of the message marked as read |
On some mail systems, this function also causes the return receipt to be sent. However, this is only the case if the message has not previously been read and a return receipt was requested by the sender.
VARIABLES rc: Integer; msgContainer: MAILContainer; msgRef: MAILRef;
ACTIONS (* Open a message container *) (* Scan messages in the container and get the *) (* message reference numbers *) (* Set msgRef to the number of the message you want to mark as read *) rc := MAILMarkMessageAsRead(msgContainer, msgRef); IF (rc <> 1) THEN (* MAILMarkMessageAsRead function failed *) ELSE (* Message marked as read *) END;
(* Close message container *)
END;
Return Code | Description |
1 | Successful completion |
Less than one | Error |
For a list of TSD Script Mail error codes and a description of the MailSendHeader record, see the Tivoli Service Desk 6.0 Developer's Toolkit Programming Guide.
Opens the specified message container and returns an identifier that can be used to scan and read received messages in that container.
FUNCTION MAILOpenMessageContainer(VAL session: MAILSession, VAL cntnrName: STRING, REF msgContainer: MAILContainer ): INTEGER;
Argument Name | Description |
session | Identifies the session |
cntnrName | Name of the message container to open. The syntax of the name is
dependent on the messaging system. Typically, it is the full PATH of the database or queue
that implements the message container. If $Unknown is passed, the default message container for the session is opened. The default message container is sometimes called the mailbox or inbox. |
msgContainer | Identifier of the open message container |
The messaging system uses the authenticated session identifier to determine whether the user has access to the specified message container.
Note: In MAPI sessions, $Unknown can be passed for cntnrName.
VARIABLES rc: Integer; session: MAILSession; name: String; hfile: File;
ACTIONS
(* Open a session *)
rc := MAILOpenMessageContainer(session, containername, msgcontainer); IF rc <> 1 THEN ( * Function MAILOpenMessageContainer failed *) ELSE (* Message container opened successfully *) END;
(* Close the container/session *)
END;
Return Code | Description |
1 | Successful completion |
Less than one | Error |
For a list of TSD Script Mail error codes and a description of the MailSendHeader record, see the Tivoli Service Desk 6.0 Developer's Toolkit Programming Guide.
Opens an authenticated session with the messaging system.
FUNCTION MAILOpenSession(VAL pathSpec: STRING, VAL name: STRING, VAL password: STRING, VAL CharSet:INTEGER, REF session: MAILSession, VAL protocol:INTEGER): INTEGER;
Argument Name | Description |
pathSpec | Path name of the message container database, or server name. Message
containers are required by Lotus cc:Mail and Microsoft Mail. Server names are required by
Lotus Notes, Microsoft Exchange, and SMTP/POP. A value of $Unknown may be
passed if this parameter is not required. Refer to the documentation provided by the vendor of your mail application for the specific value to be passed in the parameter. |
name | Name of the user trying to log in. A value of $Unknown may be
passed if this parameter is not required. Microsoft Windows 95 users: See the Notes section for the MailOpenSession statement. |
password | Password of the user trying to log in. A value of $Unknown may be
passed if this parameter is not required. Microsoft Windows 95 users: See the Notes section for the MailOpenSession statement. |
CharSet | Controls the character set expected for all input character strings and
returned for all output character strings, or else the character set to be used as a
default for the MIME character set parameter, for MIME-encoded message subject lines and
texts. The selected character set may be one of the following:
|
session | Session identifier opened by this function |
protocol | Identifies the protocol used to communicate with the mail system.
|
Tip: If you are not certain which value to pass in the CharSet argument, use $Unknown to have the correct value supplied automatically.
Using Microsoft Exchange Profile Names
Microsoft Windows 98/NT includes a program called Microsoft Windows Messaging. This program functions as an MS-Exchange or MS-Mail Client, and can also be configured for additional services such as fax and Internet mail. Windows Messaging uses a Profile to store information about the services available to a user.
Windows 98/NT users who use Microsoft Windows Messaging should pass the Profile name as the <name> argument to open a mail session. No password is necessary. When calling MailOpenSession, pass $Unknown for the <password> argument. Do not use the MS-Exchange or MS-Mail UserID. The Windows Messaging client program obtains the UserID and Password automatically from the Windows Messaging Profile settings. To work correctly, the Windows Messaging Profile should include the password information.
VARIABLES rc: Integer; PathSpec: String; Name: String; Password: String; CharSet: Integer; Session: MAILSession;
ACTIONS PathSpec := 'server@company.com'(* path spec of message container database / server name *) Name := 'user@company.com';(* a valid user id *) Password := 'password'; (* password for user id *) CharSet := OMISEL_US_ASCII;(* a character set supported by your system. *) rc := MAILOpenSession(PathSpec, Name, Password, CharSet, Session, OMI_SMTP_POP_INTERFACE); IF rc <> 1 THEN (* Error in opening session *) END; END;
Return Code | Description |
1 | Successful completion |
Less than one | Error |
For a list of TSD Script Mail error codes and a description of the MailSendHeader record, see the Tivoli Service Desk 6.0 Developer's Toolkit Programming Guide.
This function is used to query the default values of some of the attributes used in the TSD Script Mail interface.
FUNCTION MAILQueryDefaults(VAL protocol : Integer, REF infoRec:MAILInfoRec): INTEGER;
Argument Name | Description |
protocol | The protocol that is used to communicate with the mail system. This function is currently supported only for VIM interface. |
infoRec | The mail information record structure. On successful return from the function, the fields of this record are filled in with the corresponding values. |
This function is supported by VIM only.
VARIABLES inforec : MAILInfoRec; rc : Integer;
ACTIONS rc := MAILQueryDefaults(OMI_VIM_INTERFACE, inforec) IF (rc = 1) THEN (* inforec is filled with the system values *) PrintInfoRec(inforec); ELSE MsgBox('An error occurred. Return code: ' & rc); exit; END;
Return Code | Description |
1 | Successful completion |
Less than one | Error |
For a list of TSD Script Mail error codes, see the Tivoli Service Desk 6.0 Developer's Toolkit Programming Guide.
Determines whether new messages have been delivered to a message container.
FUNCTION MAILQueryNewMessages (VAL MsgContainer: MAILContainer, REF NewMessages:BOOLEAN): INTEGER;
Caution: Calling this function too frequently can result in significant performance
problems for the underlying messaging system. To prevent this,
some messaging systems may check the elapsed time since this function was called and
return FALSE if the previous call to this function was recent.
Note: It is recommended that this function be called no more than once a minute.
Argument Name | Description |
msgContainer | Identifier of the message container |
newMessages | Return value indicates the presence or absence of new messages |
Note: This function is supported by VIM only.
In VIM this function polls the message container to determine if any new messages have arrived since the previous call to this function. The first time this function is called for a message container, the return value indicates whether any new messages have been delivered to it since the message container was opened.
VARIABLES msgContainer: MAILContainer; newMessages: Boolean; rc: Integer;
ACTIONS (* Open session/container *) rc := MAILQueryNewMessages(msgContainer, newMessages); IF (rc <> 1) THEN (* MAILQueryNewMessages function failed *) ELSE IF (newMessages = TRUE) THEN (* There have been new messages since the container was opened *) ELSE (* There have been no new messages since the container was opened *) END; END; . . (* Close container/session *) . END
Return Code | Description |
1 | Successful completion |
Less than one | Error |
For a list of TSD Script Mail error codes and a description of the MailSendHeader record, see the Tivoli Service Desk 6.0 Developer's Toolkit Programming Guide.
Determines the count of unread messages in the message container.
FUNCTION MAILQueryNewMessages(VAL msgContainer: MAILContainer, REF newMessages :BOOLEAN): INTEGER;
Argument Name | Description |
msgContainer | Identifier of the message container. |
newMessages | Indicates if the number of new messages, if any, received by this message container since it opened. |
Because each call requires a significant amount of processing time, this function should not be used for polling.
VARIABLES rc: Integer; msgContainer: MAILContainer; unreadCount: Integer; hfile: FILE;
ACTIONS
(* Open a session/container/file *)
rc := MAILQueryUnreadMailCount(msgContainer, unreadCount); IF (rc <> 1) THEN (* MAILQueryUnreadMailCount function failed *) ELSE FWrite( hfile, 'Number of unread messages : ' & unreadCount); END; (
* Close same *)
END;
Return Code | Description |
1 | Successful completion |
Less than one | Error |
For a list of TSD Script Mail error codes and a description of the MailSendHeader record, see the Tivoli Service Desk 6.0 Developer's Toolkit Programming Guide.
Reads a message in the message container.
FUNCTION MAILReadMessage (VAL msgContainer:MAILContainer, VAL msgRef:MAILRef, VAL nestedLevel:INTEGER, REF msgHeader:MAILReadHeader, REF msgItems:LIST of MAILItem, REF toList, ccList, bccList:LIST of MAILName, REF nestedMsg:BOOLEAN);
Argument Name | Description |
msgContainer | Message container identifier. |
msgRef | Message reference number of the message to read. |
nestedLevel | The level of the nested message whose information is to be returned. By default, the information about the top level message is returned. The level number for the top level message is 0. |
msgHeader | The header information of the message to be read. In the case of nested messages, this corresponds to the attributes of the message as it existed at that particular point in the forwarding history. |
msgItems | The list of all the items in the message including note parts, file attachments, and application defined items. Note that for file attachments, the output file is written in the native file system's format. |
toList | List of recipients in the TO list of the message. |
ccList | List of recipients in the CC (carbon copy) list of the message. |
bccList | List of recipients in the BCC (blind carbon copy) list of the message. |
nestedMsg | Flag that indicates if a nested message is present at the level indicated by the nestedLevel parameter. |
Nested messages are not supported in MAPI. A MAPI message can have only one note part, which must be the first item in the msgItems list.
Note: Refer to the section on TSD Script Mail record structures to see which header attributes are not supported in MAPI.
VARIABLES ...
PROCEDURE MessageReadDemo IS ...
ACTIONS . . (* Open a file/session/container *) . rc := ScanAndReadMessages(msgContainer); . . (* Close the container/session/file *) . END; FUNCTION ScanAndReadMessages(VAL msgContainer:MAILContainer ): INTEGER IS ...
ACTIONS rc := MAILScanMessages(msgContainer, OMI_REVERSE_SCAN, $Unknown, TRUE, nMessages, msgsummary); msgRef := msgsummary[$First].MsgReference; ReadMessage (msgContainer, msgRef); Exit(1); END;
FUNCTION ReadMessage(VAL msgContainer:MAILContainer, VAL msgRef:MAILRef):INTEGER IS
VARIABLES nestedmsg:BOOLEAN; msgHeader:MAILReadHeader; msgItems: LIST of MAILItem; toList: LIST of MAILName; ccList: LIST of MAILName; bccList: LIST of MAILName; rc : INTEGER;
ACTIONS rc := MAILReadMessage(msgContainer, msgRef, 0, msgHeader, msgItems, toList, ccList, bccList, nestedmsg); if (rc < 0) THEN (* Message Read Failed *) ELSE (* Message read successfully *) END; END;
Return Code | Description |
1 | Successful completion. |
Less than one | Error. |
For a list of TSD Script Mail error codes and descriptions of the MailItem, MailName, MailReadHeader, and MailSendHeader record structures, see the Tivoli Service Desk 6.0 Developer's Toolkit Programming Guide.
For more details of the code example, see the file msgread.kb in the EXAMPLES directory where Tivoli Service Desk Developer's Toolkit was installed.
This function is used to release the resources used by message reference numbers. When messages are scanned using the MailScanMessages function, a list of message reference numbers is returned. These message references are released using this call after the required processing has occurred with the message. The message reference number must not be used once it has been released.
FUNCTION MAILReleaseMessageReference(VAL msgContainer: MAILContainer, VAL msgReference: MAILRef) : INTEGER;
Argument Name | Description |
msgContainer | Message container identifier. |
msgReference | Message reference number to be released. On return this argument is set to $Unknown. |
It is advisable to release the message reference numbers as soon as they are no longer needed. Doing this frees up system memory resources.
PROCEDURE MailReadDemo IS
VARIABLES rc, nmessages : Integer; msgContainer : MailContainer; outfile : FILE; msgSummary : LIST of MAILMsgSummary; msgHeader : MAILReadHeader; msgItems : LIST of MAILItem; toList, ccList, bccList : List of MAILName; nsflag : Boolean; loopcnt : Integer;
ACTIONS
IF (context.container = $unknown) THEN MessageBox('The Message container has not been opened. Cannot run this test'); Exit; ELSE msgContainer := context.container; END;
rc := MAILScanMessages(msgContainer, 0, $unknown, TRUE, nmessages, msgSummary);
IF (rc <> 1) THEN MessageBox('MAILScanMessages function failed, Error code is ' & rc); Exit; END;
MessageBox('MailScanMessages function successful');
(* Now read all the messages *) Fopen(outfile, 'readmsg1.txt', $create); loopcnt := 0; FOR msgSummary DO loopcnt := loopcnt + 1; rc := MAILReadMessage(msgContainer, msgSummary[$current]. msgReference, 0, msgHeader, msgItems, toList, ccList, bccList, nsflag); IF (rc <> 1) THEN MessageBox('MAILReadMessage function failed reading message number ' & loopcnt & '. Error code is ' & rc); ELSE PrintMessage(outfile, msgHeader, msgItems, toList, ccList, bccList); END; END; FClose(outfile); MessageBox('MailReadMessage function successful');
(* Release the message reference numbers *) FOR msgSummary DO MAILReleaseMessageReference(msgContainer, msgSummary[$current]. msgReference); END; END;
Return Code | Description |
1 | Successful completion |
Less than one | Error |
MailScanMessages
For a list of TSD Script Mail error codes, see the Tivoli Service Desk 6.0 Developer's Toolkit Programming Guide.
Removes a message from the message container.
FUNCTION MAILRemoveMessage(VAL msgContainer:MAILContainer, VAL msgRef:MAILRef): INTEGER;
Argument Name | Description |
msgContainer | Message container identifier. |
msgRef | Message reference number of the message to be removed. |
VARIABLES msgContainer: MAILContainer; msgRef: MAILRef; rc: Integer;
ACTIONS (* Open a message container *) (* Scan the messages in the container, get the message ref numbers *) rc := MAILRemoveMessage(msgContainer, msgRef); IF (rc <> 1) THEN (* Message could not be removed successfully *) ELSE (* Message removed successfully *) END; . . (* Close message container *) . END;
Return Code | Description |
1 | Successful completion |
Less than one | Error |
For a list of TSD Script Mail error codes and a description of the MailSendHeader record, see the Tivoli Service Desk 6.0 Developer's Toolkit Programming Guide.
Returns the message reference number and summary attributes of the messages in the message container.
FUNCTION MAILScanMessages(VAL msgCntnr:MAILContainer, VAL Flag:INTEGER, VAL Filter:MAILFilter, VAL summFlag:BOOLEAN, REF nMessages:INTEGER, REF msgSummary:LIST of MAILMsgSummary ): INTEGER;
Argument Name | Description |
msgCntnr | Message container identifier. |
Flag | Enumeration flag that determines which messages are scanned and the order
in which they are scanned. This is created by a Bitwise ORing of one or more of the
following values:
|
Filter | Specifies the filter used to scan messages. If $Unknown is passed, no filtering occurs and all messages are scanned. (This does not include sent messages.) It is currently not possible to set more than one filter condition. |
summFlag | Indicates whether to retrieve the message summary attributes. If this flag is set to FALSE (which is the default), only the message reference numbers are retrieved in the MailMsgSummary record. The default behavior is to retrieve only the message reference numbers. |
nmessages | The number of messages scanned. |
msgSummary | List of the MailMsgSummary records that contain message information. The message reference numbers are obtained from this record and are used to read the messages. |
Filters are not supported in MAPI.
In MAPI, only the message reference numbers are retrieved, regardless of the value of the flag (summFlag).
KNOWLEDGEBASE MSGCONT; PRIVATE VARIABLES ... ROUTINES PROCEDURE ContainerDemo IS VARIABLES sess: MAILSession; rc : INTEGER; msgContainer : MAILContainer;
ACTIONS
(* Open a file/session/container *)
(* --- Scan Messages in the container ---- *) rc := ScanMessages(msgContainer);
(* Close container/session/file *)
END;
FUNCTION ScanMessages(VAL msgContainer:MAILContainer): INTEGER IS VARIABLES Filter : MAILFilter; summaryFlag : BOOLEAN; nMessages, rc: INTEGER; msgsummary : LIST of MAILMsgSummary;
ACTIONS rc := MAILScanMessages(msgContainer, 0, $Unknown, TRUE, nMessages, msgsummary); if (rc < 0) THEN (* Scan messages function failed *) END; (* Scan Messages function succeeded *) PrintScannedMessagesInfo(msgsummary);
END;
PROCEDURE PrintScannedMessagesInfo(VAL msgsummary:LIST of MAILMsgSummary) IS VARIABLES summrec : MAILMsgSummary; ACTIONS FOR msgsummary DO summrec := msgsummary[$current]; FWriteLn(hfile, 'MessageType : ' & summrec.Type); FWriteLn(hfile, 'Unread Mail: ' & summrec.UnreadMail); FWriteLn(hfile, 'FromName: ' & summrec.FromName); FWriteLn(hfile, 'FromAddress: ' & summrec. FromAddress); FWriteLn(hfile, 'Priority: ' & summrec.Priority); FWriteLn(hfile, 'Subject: ' & summrec.Subject); FWriteLn(hfile, ' ********* '); END; END;
Return Code | Description |
1 | Successful completion. |
Less than one | Error. |
For a list of TSD Script Mail error codes and descriptions of the MailFilter, MailSendHeader, and the MailMsgSummary record structures, see the Tivoli Service Desk 6.0 Developer's Toolkit Programming Guide.
For details of the code example, see the msgcont.kb file in the EXAMPLES directory where Tivoli Service Desk Developer's Toolkit was installed.
Creates a new mail message from an existing mail message.
Used to forward or reply to a message.
FUNCTION MAILSendDerivedMessage(VAL msgCntnr:MAILContainer, VAL msgRef:MAILRef, VAL type, flags:Integer, VAL msgHeader:MAILSendHeader, VAL toList, ccList, bccList:LIST of VAL items:LIST of MAILItem ): INTEGER;
Argument Name | Description |
msgCntnr | Message container identifier. |
msgRef | Message reference number of the message from which to derive the new mail message. |
type | Type of new mail message to create. This could be OMISEL_FORWARD or OMISEL_REPLY. |
flags | A bit mask of style flags OR-ed together which specify the components of
the mail message which should be inherited by the newly created mail message. The meaning
of the flags depend upon the type of mail message being created. $Unknown may
be used if nothing is to be inherited. If type is OMISEL_FORWARD, flags has the following meaning: OMI_HISTORY: Specifies that the previous forwarding history of the existing mail message should be inherited by the newly created mail message. If this is not set, the previous history is not inherited. If type is OMISEL_REPLY, flags has the following meaning: OMI_INHERIT_CONTENTS: Specifies that the contents of the existing mail message should be inherited by the newly created mail message. If this is not set, the contents are not inherited. Some message service implementations may inherit only note parts, while other implementations inherit both the note parts and any attachments. OMI_ALL_RECIPIENTS: Specifies that all recipients of the existing mail message should be inherited by the newly created mail message. If this is not set, only the sender of the original mail message is inherited. |
msgHeader | Initializes the MailSendHeader record to set the header attributes of the message being sent. |
toList | List of primary recipients of the message. |
ccList | List of recipients in the CC (carbon copy) list of the message. |
bccList | List of recipients in the BCC (blind carbon copy) list of the message. |
items | List of the items in the message. |
This function is supported by VIM only.
Return Code | Description |
1 | Successful completion. |
Less than one | Error. |
For a list of TSD Script Mail error codes and a description of the MailSendHeader record, see the Tivoli Service Desk 6.0 Developer's Toolkit Programming Guide.
Creates a new message and sends it.
FUNCTION MAILSendMessage(VAL session:MAILSession, VAL MsgType:STRING, VAL MsgHeader: MAILSendHeader, VAL ToList, ccList, bccList:LIST of MAILName, VAL Items: LIST of MAILItem ): INTEGER;
Caution: In MAPI there is no way to specify whether the message that is sent should
be logged in the message log. To prevent a disk space problem with outgoing messages,
message logging can be controlled using the Mail/Options choice in the MS-Mail menu.
The mail client should be set up in such a way that messages sent are not saved.
Argument Name | Description |
session | Identifies the session for which the message is to be created. |
MsgType | Type of message being composed. VIM_MAIL or OMI_MAIL should be used for mail messages. This type may be up to 32 characters in length. |
MsgHeader | Initializes the MailSendHeader record to set the header attributes of the message being sent. |
toList | List of primary recipients of the message. |
ccList | List of recipients in the CC (carbon copy) list of the message |
bccList | List of recipients in the BCC (blind carbon copy) list of the message. |
Items | List of the items in the message. |
All attributes and fields of the MailSendHeader record may not be supported by the messaging service provider. If these fields could not be set by MailSendMessage because of this, no error code is generated. MailSendMessage returns an error code only if an error other than 'Not Supported' occurs for the header attributes.
If the function could not send to one of the message recipients, it returns an error code. Similarly, if any of the message items could not be successfully attached to the message, the function returns an error code.
Recipients designated in the toList and ccList are unable to view the names of recipients designated in the bccList.
There may be a limit on the maximum subject length or the maximum text length of the message. Use the MailQueryDefaults to determine the maximum subject length and text length.
There can be only one message item of class NOTE_PART, and it must be the first item in the message item list.
KNOWLEDGEBASE SENDDEMO;
PROCEDURE SendDemo IS VARIABLES session: MAILSession; rc : INTEGER; ACTIONS
(* Open session *)
rc := SendMail(session);
(* Close session *)
END;
FUNCTION SendMail(VAL sess: MAILSession): INTEGER IS VARIABLES header :MAILSendHeader; Items :LIST of MAILItem; Item :MAILItem; name :MAILName; toList :LIST of MAILName; rc :INTEGER; ACTIONS (* Set the header record *) header.subject := 'Sample Message'; (* 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 Reader, This message is being sent by a VIM application.'; 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(sess, OMI_MAIL, header, toList, $UNKNOWN, $UNKNOWN, Items); Exit(rc); END;
Return Code | Description |
1 | Successful completion. |
Less than one | Error. |
See the Tivoli Service Desk 6.0 Developer's Toolkit Programming Guide for the following information:
Note: For details on the code example, see the senddemo.kb file in the EXAMPLES directory where Tivoli Service Desk Developer's Toolkit was installed.
Releases the resources used by the TSD Script Mail interface. This function must be called before terminating the application. No calls to the TSD Script Mail interface can be made after executing this call until you call MailInitialize.
FUNCTION MAILTerminate (VAL protocol: INTEGER): INTEGER
Argument Name | Description |
protocol | Identifies the protocol used to communicate with the mail system.
|
PROCEDURE SendMail IS VARIABLES SESS: MailSession; ACTIONS MAILInitialize;
(*Now open the session.*)
(* Do other processing. *)
MAILTerminate;
Return Code | Description |
1 | Successful completion. |
Less than one | Error. |
MailInitialize
For a list of TSD Script Mail error codes and a description of the MailSendHeader record, see the Tivoli Service Desk 6.0 Developer's Toolkit Programming Guide.
Gets and verifies the digital signature on a message.
FUNCTION MAILVerifyMessageSignature(VAL msgContainer: MAILContainer, VAL msgRef:MAILRef, REF signer:MAILName, REF certifier:MAILName ): INTEGER;
Argument Name | Description |
msgContainer | Message container identifier |
msgRef | Message reference number of the message |
signer | Identity of the signer |
certifier | Identity of the certifier |
This function is supported by VIM only. The meaning of the message signature (such as the dependability of the verification) varies with the implementation of the messaging system.
VARIABLES rc: Integer; msgContainer: MAILContainer; msgRef: MAILRef; signer: String; certifier: String; hfile: FILE; ACTIONS (* Open a message container, scan the messages and set msgRef to the reference number of the message with the needed signature information *) . rc:= MAILVerifyMessageSignature(msgContainer, msgRef, signer, certifier); IF rc <> 1 THEN ELSE FWrite (hfile, 'The signer of the message is ' & signer.EntityName); FWrite (hfile, 'The certifier of the message is ' & certifier.EntityName); END . . . END;
Return Code | Description |
1 | Successful completion. |
Less than one | Error. |
For a list of TSD Script Mail error codes and a description of the MailSendHeader record, see the Tivoli Service Desk 6.0 Developer's Toolkit Programming Guide.
Tivoli Service Desk 6.0 Developer's Toolkit Script Language Reference