9.140 MAIL_START

Note: Built-In Function Rules Usage Options

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.

Arguments

None.

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

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
     **********