9.160 MAIL_SET_OPTION
Þ Note: Built-In Function Rules.
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.
For use with
|
LANSA for i
|
YES
|
|
Visual LANSA for Windows
|
YES
|
|
Visual LANSA for Linux
|
NO
|
|
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
|
No
|
Type
|
Req/ Opt
|
Description
|
Min Len
|
Max Len
|
Min Dec
|
Max Dec
|
|
1
|
A
|
Opt
|
Return Code
OK - Action completed
ER - Error occurred
|
2
|
2
|
|
|
|
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)