Documentation Comments

Use this form to comment on this topic. You can also provide any general observations about the Online Documentation, or request that additional information be added in a future release.

Reality V15.2 Online Documentation (MoTW) Revision 3

EM_START_EMAIL Function (DataBasic Email API) (em_start_email.htm)

To	Reality
Version
Topic
Submitted by
Company
Location
Email address
Comment

EM_START_EMAIL Function

Purpose

Defines the start of an email by defining the connection information for the mail server to be used. If a predefined host configuration item is specified the details are loaded from that item; these details can be overridden by providing additional configuration parameters.

Returns TRUE or FALSE.

Syntax

EM_START_EMAIL(host-item, host-configuration)

Syntax elements

host-itemThe item ID of a predefined host configuration item from an email configuration file (either the default EM_CONFIG file or a file previously specified by the EM_DEFINE_CONFIG function) to be used as the basis for the mail server connection. If this is not set, an empty configuration item is created ready to be overwritten by the configuration defined by the host-configuration parameter.

host-configurationA dynamic array of the parameters defining the mail server connection configuration. This overrides any values that may have been loaded from an existing predefined configuration item specified by host-item.

Attribute	Name	Description
1	DESCRIPTION	Optional description of configuration for reference only.
2	CONFIG	Optional configuration table.
		Value	Name	Description
		1	RETRY LIMIT	Maximum number of times to retry receiving a response from the server. Setting the number of retries to -1 will retry forever whereas setting to zero will not retry after the initial attempt. If this is left blank, the default of 10 retries is used.
		2	RETRY SLEEP	The time in seconds (between 1 and 10) to sleep before the first attempt to receive a message and subsequent retries). If this is left blank, the default value of 1 second is used.
3	CONNECTION	The information required to set up communications with the server.
		Value	Name	Description
		1	HOST	The fully-qualified name or IP address of the mail server to use.
		2	PORT	The port used for connecting to the mail server. If this is left blank, the default of 25 is used.
		3	PROTOCOL	The protocol used for connecting to the mail server. Currently, the only valid option is TCP. If this is left blank, the default value TCP is used.
		4	TLS	The setting for the TLS (transport layer security) option. If this is set, `;TLS=option` is added to the details used for the connection. Currently, the only valid options are none and server. If neither option is set, the TLS string is not added to the connection.
4	AUTH DETAILS	Optional authentication details for logging into the mail server.
		Value	Name	Description
		1	USER	The name of the user account with which to login to the mail server. If this is not set (null), no authentication is used.
		2	PASSWORD	The password of the user account. If no user account is defined, the password is ignored.

Returns

EM_START_EMAIL returns TRUE if successful or FALSE if unsuccessful. If FALSE, the details of the failure to load the configuration can be found by inspecting the error number held in the common variable EM_ERROR_DETAILS.

Comments

You must include the item #EM_INCLUDES in all programs that use the Email API functions; for example, you could add the line

INCLUDE #EM_INCLUDES FROM /SYSFILES/SYS.BASLIB

at the start of the program, or create an item to be automatically included that contains this line.