mailLogon

Description

Establishes a mail session for the PowerBuilder application. The PowerBuilder application can start a new session or join an existing session.

Applies to

mailSession object

Syntax

mailsession.mailLogon ( { profile, password } {, logonoption } )

Argument	Description
mailsession	A mailSession object identifying the session you want to logon to.
profile (optional)	A string whose value is the user’s mail system profile or user ID.
password (optional)	A string whose value is the user’s mail system password.
logonoption (optional)	A value of the mailLogonOption enumerated datatype specifying the logon options: mailNewSession! – Starts a new mail session, whether or not the mail application is already running mailDownLoad! – Forces the mail application to download any new messages from the server to the user’s inbox. Starts a new mail session only if the mail application is not running mailNewSessionWithDownLoad! – Starts a new mail session and forces new messages to be downloaded from the server to the user’s inbox The default is to use an existing session if possible and not to force new messages to be downloaded.

Returns

mailReturnCode. Returns one of the following values:

mailReturnSuccess!
mailReturnLoginFailure!
mailReturnInsufficientMemory!
mailReturnTooManySessions!
mailReturnUserAbort!

If any argument’s value is null, mailLogon returns null.

Usage

If you do not direct mailLogon to start a new session and the mail application is already running on the user’s computer, then the PowerBuilder mail session attaches to the existing session. A profile and password are not necessary.

When mailLogon establishes a new session, then the mail system’s dialog box prompts for the profile and password if the script does not supply them.

The download option forces the mail server to download the latest messages to the user’s inbox. This ensures that the inbox is up to date; it does not make the messages available to PowerBuilder. To access messages, use mailGetMessages and mailReadMessage.

Before calling mailLogon, you must declare and create a mailSession object.

Examples

Example 1

In this example, the mailSession object new_session is an instance variable of the window. The window’s Open event script allocates memory for the mailSession object and logs on. During the logon process, the mail application displays a dialog box prompting for the profile and password:

new_session = CREATE mailSession

new_session.mailLogon(mailNewSession!)

Example 2

This example establishes a new mail session and makes the user’s inbox up to date. The user wo not be prompted for an ID and password because user information is provided. Here the mailSession object is a local variable:

mailSession new_session

new_session = CREATE mailSession

new_session.mailLogon("jpl", "hotstuff", &

    mailNewSessionWithDownLoad!)