Tivoli Service Desk 6.0 Developer's Toolkit Script Language Reference

TSD Script Mail Functions

Return to Main Page


MailAddressBookEntries

Description

Returns the list of all entries in an address book.

Syntax

FUNCTION MAILAddressBookEntries(VAL session: MAIL Session,
                                VAL addrBookName: STRING,
                                REF addrBookEntries: LIST of
                                MAILABEntry): INTEGER;

Argument Notes

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:
  • OMI_PUBLIC: Used to open the default address book that contains entries which are publicly accessible (that is, accessible to all users at a particular location).
  • OMI_PRIVATE: Used to open the default address book that contains entries which are only privately accessible (that is, accessible only to the currently logged-in user).
addrBookEntries List of MailABEntry records describing the entries in the given address book.

Notes

This function is supported by VIM only.

Example

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 Codes

Return Code Description
1 Successful completion
Less than one Error

See Also

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.


MailAddressBooks

Description

Returns a list of address book names available to the current session.

Syntax

FUNCTION MAILAddressBooks(VAL session:MAILSession, REF
                          AddrBooks: LIST of STRING): INTEGER;

Argument Notes

Argument Name Description
session Session identifier
AddrBooks List of address book names available to this session (returned value)

Notes

This function is supported by VIM only.

Example

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 Codes

Return Code Description
1 Successful completion
Less than one Error

See Also

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.


MailCloseMessageContainer

Description

Closes a message container.

Syntax

FUNCTION MAILCloseMessageContainer(VAL msgContainer: MAILContainer): INTEGER;

Argument Notes

Argument Name Description
msgContainer Identifier of the open message container.

Example

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 Codes

Return Code Description
1 Successful completion.
Less than one Error.

See Also

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.


MailCloseSession

Description

Closes the session.

Syntax

FUNCTION MAILCloseSession(REF session: MAILSession): INTEGER;

Argument Notes

Argument Name Description
session Identifies the session to close.

Notes

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.

Example

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 Codes

Return Code Description
1 Successful completion
Less than one Error

See Also

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.


MailGetEntityName

Description

Returns the name of the user or the messaging application associated with the session specified in the session parameter.

Syntax

FUNCTION MAILGetEntityName(VAL session: MAILSession,
                           REF Name: MAILName): INTEGER;

Argument Notes

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.

Example

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;

Notes

This function is supported by VIM only.

See Also

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.


MailGetLastErrorText

Description

Returns the error text associated with the last failed operation.

Syntax

FUNCTION MAILGetLastErrorText( VAL protocol: INTEGER,
 VAL sessID: MAILSession,
 VAL errCode: INTEGER,
 REF LastErrCode: INTEGER,
 REF ErrText: STRING)

Argument Notes

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

Notes

This function is supported by VIM only.

See Also

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.


MailInitialize

Description

Initializes the TSD Script Mail interface. This should be the first function called before using any TSD Script Mail interface services.

Syntax

MAILInitialize (VAL protocol:INTEGER): INTEGER

Argument Notes

Argument Name Description
protocol Identifies the protocol used to communicate with the mail system.
  • OMI_VIM_INTERFACE: For use with VIM protocol
  • OMI_ MAPI_INTERFACE: For use with MAPI protocol

Example

PROCEDURE SendMail IS
VARIABLES
 SESS: MailSession;
ACTIONS
 MAILInitialize(OMI_MAPI_INTERFACE);
 (* Now open the session. *)
 (* Do other processing. *)
MAILTerminate(OMI_MAPI_INTERFACE);

Return Codes

Return Code Description
1 Successful completion.
Less than one Error.

See Also

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.


MailMarkMessageAsRead

Description

Marks a message as read.

Syntax

FUNCTION MAILMarkMessageAsRead(VAL msgContainer:
                               MAILContainer, VAL
                               msgRef:MAILRef): INTEGER;

Argument Notes

Argument Name Description
msgContainer Message container identifier
MsgRef Message reference number of the message marked as read

Notes

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.

Example

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 Codes

Return Code Description
1 Successful completion
Less than one Error

See Also

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.


MailOpenMessageContainer

Description

Opens the specified message container and returns an identifier that can be used to scan and read received messages in that container.

Syntax

FUNCTION MAILOpenMessageContainer(VAL session: MAILSession,
                                  VAL cntnrName: STRING,
                                  REF msgContainer: MAILContainer
                                  ): INTEGER;

Argument Notes

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

Notes

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.

Example

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 Codes

Return Code Description
1 Successful completion
Less than one Error

See Also

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.


MailOpenSession

Description

Opens an authenticated session with the messaging system.

Syntax

FUNCTION MAILOpenSession(VAL pathSpec: STRING, VAL name: STRING,
                         VAL password: STRING, VAL CharSet:INTEGER,
                         REF session: MAILSession,
                         VAL protocol:INTEGER): INTEGER;

Argument Notes

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:
  • OMISEL_CP850: Text and character string data are presented and returned using Code Page 850. This is always valid for DOS and OS/2-based implementations.
  • OMISEL_CP1252: Text and character string data are presented and returned using Code Page 1252 (ANSI). This is always valid for Windows-based implementations.
  • OMISEL_CP437: Text and character string data are presented and returned using Code Page 437 (IBM PC). This is always valid for DOS based implementations.
  • OMISEL_LMBCS: Text and character string data are presented and returned using the Lotus Multi-Byte Character Set.
  • OMISEL_UNICODE: Text and character string data are presented and returned using Unicode.
  • OMISEL_ISO_2022_JP: Default MIME character set parameter set to ISO-2022-JP.
  • OMISEL_ISO_2022_JP_2: Default MIME character set parameter set to ISO-2022-JP-2.
  • OMISEL_ISO_8859_1: Default MIME character set parameter set to ISO-_8859-1 (Latin).
  • OMISEL_US_ASCII: Default MIME character set parameter set to US ASCII (ANSI X3.4)
session Session identifier opened by this function
protocol Identifies the protocol used to communicate with the mail system.
  • OMI_VIM_INTERFACE: For use with VIM protocol
  • OMI_ MAPI_INTERFACE: For use with MAPI protocol
  • OMI_ SMTP_POP_INTERFACE For use with SMTP/POP protocol

Tip: If you are not certain which value to pass in the CharSet argument, use $Unknown to have the correct value supplied automatically.

Notes

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.

Example

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 Codes

Return Code Description
1 Successful completion
Less than one Error

See Also

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.


MailQueryDefaults

Description

This function is used to query the default values of some of the attributes used in the TSD Script Mail interface.

Syntax

FUNCTION MAILQueryDefaults(VAL protocol : Integer,
                           REF infoRec:MAILInfoRec): INTEGER;

Argument Notes

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.

Notes

This function is supported by VIM only.

Example

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 Codes

Return Code Description
1 Successful completion
Less than one Error

See Also

For a list of TSD Script Mail error codes, see the Tivoli Service Desk 6.0 Developer's Toolkit Programming Guide.


MailQueryNewMessages

Description

Determines whether new messages have been delivered to a message container.

Syntax

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 Notes

Argument Name Description
msgContainer Identifier of the message container
newMessages Return value indicates the presence or absence of new messages

Notes

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.

Example

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 Codes

Return Code Description
1 Successful completion
Less than one Error

See Also

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.


MailQueryUnreadMailCount

Description

Determines the count of unread messages in the message container.

Syntax

FUNCTION MAILQueryNewMessages(VAL msgContainer:
                              MAILContainer, REF newMessages
                              :BOOLEAN): INTEGER;

Argument Notes

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.

Notes

Because each call requires a significant amount of processing time, this function should not be used for polling.

Example

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 Codes

Return Code Description
1 Successful completion
Less than one Error

See Also

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.


MailReadMessage

Description

Reads a message in the message container.

Syntax

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 Notes

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.

Notes

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.

Example

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 Codes

Return Code Description
1 Successful completion.
Less than one Error.

See Also

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.


MailReleaseMessageReference

Description

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.

Syntax

FUNCTION MAILReleaseMessageReference(VAL msgContainer: MAILContainer,
                                     VAL msgReference: MAILRef)
                                     : INTEGER;

Argument Notes

Argument Name Description
msgContainer Message container identifier.
msgReference Message reference number to be released. On return this argument is set to $Unknown.

Notes

It is advisable to release the message reference numbers as soon as they are no longer needed. Doing this frees up system memory resources.

Example

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 Codes

Return Code Description
1 Successful completion
Less than one Error

See Also

MailScanMessages

For a list of TSD Script Mail error codes, see the Tivoli Service Desk 6.0 Developer's Toolkit Programming Guide.


MailRemoveMessage

Description

Removes a message from the message container.

Syntax

FUNCTION MAILRemoveMessage(VAL msgContainer:MAILContainer,
                           VAL msgRef:MAILRef): INTEGER;

Argument Notes

Argument Name Description
msgContainer Message container identifier.
msgRef Message reference number of the message to be removed.

Example

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 Codes

Return Code Description
1 Successful completion
Less than one Error

See Also

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.


MailScanMessages

Description

Returns the message reference number and summary attributes of the messages in the message container.

Syntax

 FUNCTION MAILScanMessages(VAL msgCntnr:MAILContainer,
                           VAL Flag:INTEGER, VAL Filter:MAILFilter,
                           VAL summFlag:BOOLEAN, REF nMessages:INTEGER,
                           REF msgSummary:LIST of MAILMsgSummary
                           ): INTEGER;

Argument Notes

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:
  • OMI_UNREADONLY: Return only unread messages. Messages are returned by default.
  • OMI_REVERSE_SCAN: Enumerate messages in reverse order (last in/first out).
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.

Notes

Filters are not supported in MAPI.

In MAPI, only the message reference numbers are retrieved, regardless of the value of the flag (summFlag).

Example

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 Codes

Return Code Description
1 Successful completion.
Less than one Error.

See Also

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.


MailSendDerivedMessage

Description

Creates a new mail message from an existing mail message.

Used to forward or reply to a message.

Syntax

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 Notes

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.

Notes

This function is supported by VIM only.

Return Codes

Return Code Description
1 Successful completion.
Less than one Error.

See Also

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.


MailSendMessage

Description

Creates a new message and sends it.

Syntax

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 Notes

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.

Notes (VIM)

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.

Notes (MAPI)

There can be only one message item of class NOTE_PART, and it must be the first item in the message item list.

Example

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 Codes

Return Code Description
1 Successful completion.
Less than one Error.

See Also

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.


MailTerminate

Description

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.

Syntax

FUNCTION MAILTerminate (VAL protocol: INTEGER): INTEGER

Argument Notes

Argument Name Description
protocol Identifies the protocol used to communicate with the mail system.
  • OMI_VIM_INTERFACE: For use with VIM protocol
  • OMI_ MAPI_INTERFACE: For use with MAPI protocol

Example

PROCEDURE SendMail IS
VARIABLES
 SESS: MailSession;
ACTIONS
 MAILInitialize;
 (*Now open the session.*)
 (* Do other processing. *)
MAILTerminate;

Return Codes

Return Code Description
1 Successful completion.
Less than one Error.

See Also

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.


MailVerifyMessageSignature

Description

Gets and verifies the digital signature on a message.

Syntax

FUNCTION MAILVerifyMessageSignature(VAL msgContainer:
                                    MAILContainer, VAL
                                    msgRef:MAILRef, REF
                                    signer:MAILName, REF
                                    certifier:MAILName
                                    ): INTEGER;

Argument Notes

Argument Name Description
msgContainer Message container identifier
msgRef Message reference number of the message
signer Identity of the signer
certifier Identity of the certifier

Notes

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.

Example

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 Codes

Return Code Description
1 Successful completion.
Less than one Error.

See Also

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

Return to Main Page

Copyright