9 138 MAIL_SET

9.138 MAIL_SET_OPTION

Note: Built-In Function Rules Usage Options

Used to set various options which may be required by the mail system.

Refer to Email Built-In Functions Notes before using this Built-In Function.

LANSA for i Specific Options

Option Name	Option Values	Option Default
PRIORITY An indication of the priority of the message.	'NORMAL' 'LOW' 'URGENT'	'NORMAL'
SENSITIVITY An indication of the sensitivity of the message content.	'NONE' 'PERSONAL' 'PRIVATE' 'CONFIDENTIAL'	'NONE'
IMPORTANCE An indication of the importance of the message content.	'NORMAL' 'LOW' 'HIGH'	'NORMAL'
MESSAGE_CCSID The CCSID to use for the mail message text strings such as mail message subject and text lines.	String	'65535'
CONTENT_TYPE The content-type that the message text contains. Examples are 'text/plain' & 'text/html'. Other values may be used, but in any case the application should be tested to ensure that the content-type is suitable. This option value is not validated, nor is the message text validated against the content-type. When using the content-type of 'text/html', be aware that some email clients may not be able to render this, also this may trip some spam filters.	String	'text/plain'

Visual LANSA Specific Options

Option Name	Option Values	Option Default
PROFILENAME Profile name string to use when logging on. If the value supplied is invalid, and MAPI_LOGON_UI is set, MAPI displays an error followed by a logon dialog box with an empty name field.	String	"Windows Messaging Settings"
PASSWORD Credential string. If the messaging system does not require password credentials, or if it requires that the user enter them, this option should NOT be set. When the user must enter credentials, the MAPI_LOGON_UI or MAPI_PASSWORD_UI option must be set to allow a logon dialog box to be displayed.	String	None - empty string
MAPI_NEW_SESSION Indicates if an attempt should be made to create a new session rather than acquire the environment's shared session. If the MAPI_NEW_SESSION option is not set, an existing shared session is used.	Y/N	N
MAPI_LOGON_UI Indicates if a logon dialog box should be displayed to prompt the user for logon information. If the user needs to provide a password and profile name to enable a successful logon, MAPI_LOGON_UI must be set.	Y/N	N
MAPI_PASSWORD_UI Indicates if MAPI should only prompt for a password and not allow the user to change the profile name. You should not set both MAPI_PASSWORD_UI and MAPI_LOGON_UI since the intent is to select between two different dialog boxes for logon.	Y/N	N

Options Applicable to All Platforms

These options may be used on any platform.

Option Name:	Option Values	Option Default
RECEIPT_REQUESTED Indicates if a receipt notification is requested.	Y/N	N

Arguments

No	Type	Req/ Opt	Description	Min Len	Max Len	Min Dec	Max Dec
1	A	Req	Option Name (see descriptions above).	1	20
2	A	Req	Option Value (see descriptions above).	1	255

Return Values

Type

Req/ Opt

Description

Min Len

Max Len

Min Dec

Max Dec

Opt

Return Code

OK - Action completed

ER - Error occurred

Technical Notes

The MAPI interface is used on the Windows platform. MAIL_SET_OPTION calls may be required for logon to the MAPI mail provider which begins a session with the messaging system. To request the display of a logon dialog box if the credentials presented (password) fail to validate the session, set the MAPI_LOGON_UI or MAPI_PASSWORD_UI option. If you do not allow the display of the dialog box, all logon information, default or specified must be valid or the MAIL_SEND will fail during the MAPI logon phase with very little information available as to the cause of the failure. The information set in this way is not used until a MAIL_SEND call is issued at which time an attempt at logon validation will take place.
Details of the email definition will be lost unless the MAIL_SEND Built-In Function is used to send the message.
If any error occurs, all details of the email definition will be lost. To restart processing, a new call to MAIL_START would be required.
The PRIORITY, SENSITIVITY and IMPORTANCE mail options are usually ignored by PC mail clients. It is your responsibility to verify they work properly in your environment.
The RECEIPT_REQUESTED: Y mail option may either be ignored or disabled by PC mail clients, or disabled at the recipient mail server to prevent spam. It is your responsibility to verify it works properly in your environment.

Example

This example shows only this function. See the example for MAIL_START which defines all details of an Email message and then sends it by using Built-In Functions.

********** COMMENT(Set receipt acknowledgement is required)

USE BUILTIN(MAIL_SET_OPTION) WITH_ARGS(RECEIPT_REQUESTED Y) TO_GET(#LEM_RETC)