9.162 MAIL_START
Þ Note: Built-In Function Rules.
Used to start an email session.
The email session started can be used by the calling function to define and send a single email message.
Refer to Email Built-In Functions Notes before using this Built-In Function.
For use with
|
Arguments
None
Return Values
|
Technical Notes
- MAIL_START destroys any existing mail message information and starts a new mail session.
- Only one email definition can be in progress at one time (ie: it is not possible to concurrently define two email definitions prior to sending them from within the same job).
- 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 are destroyed. To restart processing, a new call to MAIL_START would be required.
Example
This example defines all details of an Email message and then sends it by using Built-In Functions.
Note: If you wish to use this example for testing you should replace <-- name --> and <-- recipient@address --> where these are used in the examples of MAIL_ADD_RECIPIENT and MAIL_ADD_ORIGINATOR.
FUNCTION OPTIONS(*DIRECT)
DEFINE FIELD(#LEM_RETC) TYPE(*CHAR) LENGTH(2) LABEL('Return Code')
DEF_COND NAME(*OKAY) COND('#LEM_RETC = OK')
DEF_COND NAME(*NOTOKAY) COND('#LEM_RETC *NE OK')
DEF_COND NAME(*CLIENT) COND('*CPUTYPE *NE AS400')
DEF_COND NAME(*HOST) COND('*CPUTYPE *EQ AS400')
**********
BEGIN_LOOP
********** COMMENT(Start Mail message - Initialize)
USE BUILTIN(MAIL_START) TO_GET(#LEM_RETC)
********** COMMENT(If not IBM i, set MAPI arguments)
IF COND(*CLIENT)
********** COMMENT(Use the Windows Default Profile)
USE BUILTIN(MAIL_SET_OPTION) WITH_ARGS('PROFILENAME' 'Windows Messaging Settings') TO_GET(#LEM_RETC)
********** COMMENT(Assume user has no Password)
USE BUILTIN(MAIL_SET_OPTION) WITH_ARGS('PASSWORD' *BLANK) TO_GET(#LEM_RETC)
********** COMMENT(Use existing MAPI mail session)
********** COMMENT(from logged on Email client)
USE BUILTIN(MAIL_SET_OPTION) WITH_ARGS('MAPI_NEW_SESSION' N) TO_GET(#LEM_RETC)
********** COMMENT(Display MAPI Logon dialog if required)
USE BUILTIN(MAIL_SET_OPTION) WITH_ARGS('MAPI_LOGON_UI' Y) TO_GET(#LEM_RETC)
********** COMMENT(Do not display MAPI Password Dialog)
********** COMMENT(mutually exclusive to MAPI_LOGON_UI))
USE BUILTIN(MAIL_SET_OPTION) WITH_ARGS('MAPI_PASSWORD_UI' N) TO_GET(#LEM_RETC)
********** COMMENT(Set Recipient using TO argument)
********** COMMENT(may also set others for TO CC BCC)
USE BUILTIN(MAIL_ADD_RECIPIENT) WITH_ARGS(TO '<-- name -->' 'SMTP:<-- recipient@address -->') TO_GET(#LEM_RETC)
********** COMMENT(To define attachment file remove comments)
*** USE BUILTIN(MAIL_ADD_ATTACHMENT) WITH_ARGS('c:\config.sys' 'MyConfig.txt') TO_GET(#LEM_RETC)
ELSE
********** COMMENT(Set Recipient using TO argument)
USE BUILTIN(MAIL_ADD_RECIPIENT) WITH_ARGS(TO 'SMTP:<-- recipient@address -->') TO_GET(#LEM_RETC)
ENDIF
IF COND(*HOST)
********** COMMENT(Define Message Originator if IBM i)
********** COMMENT(MAPI on non-IBM i usually defaults)
USE BUILTIN(MAIL_ADD_ORIGINATOR) WITH_ARGS('SMTP:<-- recipient@address -->') TO_GET(#LEM_RETC)
ENDIF
********** COMMENT(Set receipt acknowledgement is required)
USE BUILTIN(MAIL_SET_OPTION) WITH_ARGS(RECEIPT_REQUESTED Y) TO_GET(#LEM_RETC)
********** COMMENT(Set Subject text)
USE BUILTIN(MAIL_SET_SUBJECT) WITH_ARGS('Testing Email Built-In Functions') TO_GET(#LEM_RETC)
********** COMMENT(Set message Text)
USE BUILTIN(MAIL_ADD_TEXT) WITH_ARGS('Hello,' Y) TO_GET(#LEM_RETC)
DEFINE FIELD(#BIGLINE) TYPE(*CHAR) LENGTH(255) LABEL('Big Text Line') INPUT_ATR(LC)
CHANGE FIELD(#BIGLINE) TO('''I am sending this message just to try out the LANSA Email Built-In Functions.''')
USE BUILTIN(MAIL_ADD_TEXT) WITH_ARGS(#BIGLINE Y) TO_GET(#LEM_RETC)
USE BUILTIN(MAIL_ADD_TEXT) WITH_ARGS('Thank You' N) TO_GET(#LEM_RETC)
********** COMMENT(Prompt to SEND the mail then send)
DEFINE FIELD(#LTEXT2) TYPE(*CHAR) LENGTH(1) DESC('Press ENTER to SEND or CANCEL')
POP_UP FIELDS((#LTEXT2 *L4 *P4 *DESC *NC)) IDENTIFY(*LABEL) AT_LOC(7 20) WITH_SIZE(57 10) PANEL_TITL('Confirm Mail Send...') EXIT_KEY(*NO) PROMPT_KEY(*NO) STD_HEAD(*YES)
USE BUILTIN(MAIL_SEND) TO_GET(#LEM_RETC)
IF COND(*OKAY)
MESSAGE MSGTXT('Send SUCCESSFUL.')
ELSE
MESSAGE MSGTXT('Send FAILED.')
ENDIF
END_LOOP
**********