Topic: DMD0068

EMAIL - Send Email

The Send Email (EMAIL) instruction is used to send an Email message. This instruction is only valid for Do-more controllers that have an on-board Ethernet port. The Email message can be any combination of text and data elements from the controller.

 

Send Email (EMAIL) is a Multi-Scan instruction.

 

Send Email (EMAIL) is an edge-triggered instruction.

 

Parameters:

Note: Use the F9 key (Element Browser) or Down-Arrow key (Auto-Complete) at any time to see a complete list of the memory locations that are valid in the current field of the instruction.

 

SMTP Device - designates the SMTP Client device to use to send the Email. An SMTP Client device must be configured before the Send Email instruction can be added to a program. For information on configuring an SMTP Client Device go to the SMTP Client Device Configuration section of the System Configuration Help.
 

no devices available - indicates that there are no Devices that can execute this instruction. The most likely causes are there are no SMTP Devices configured, or the CPU does not have an onboard Ethernet port.

 

    • create device - select this option to invoke the Device Configuration dialog of the System Configuration to create a new device of the appropriate type

 

In common usage, the To field recipients are the primary audience of the message, Cc (Courtesy Copy or Carbon Copy) field recipients are others whom the author wishes to publicly inform of the message, and Bcc (Blind Carbon Copy) field recipients receive the Email without anyone else (including the To, Cc, and Bcc recipients) seeing who the Bcc recipients are.

 

The To, Cc, and Bcc fields are each limited to 1024 characters. The Email addresses in these fields must be in the form of X@Y.Z. Multiple Email addresses can be entered, each separated by semicolons.

 

To - the list of primary audience Email addresses

 

Cc - the optional list of Courtesy Copy (or Carbon Copy) Email addresses

 

Bcc - the optional list of Blind Carbon Copy Email addresses

 

Subject - the Total number of characters in Subject line is limited to 1024 characters.

 

Automatically insert space after each term - will insert a space between the terms when the instruction is processed. This is most useful when the Message Field contains only a list of elements that would otherwise require a manually entered space character to separate the items.

 

For example, assume that V0 contains the value 1234, and V1 contains 5678, and V2 contains 9012.

 

If Message is specified as V0 V1 V2 and the 'Automatically insert space' is checked the result will be "1234 5678 9012".

 

If Message is specified as V0 V1 V2 and the 'Automatically insert space' is NOT checked the result will be "123456789012".

 

The same result can be had by manually inserting space characters in the Message like this: V0 " " V1 " " V2

 

Message - contains the body of the Email. There can be up to 1023 characters of data in a Message field. This data can consist of any combination of the following:

  • string literal

  • control characters

  • any of the system-defined Short Strings (SS0 - SS127), or system-defined Long Strings (SL0 - SL63), or any user-defined Strings

  • controller data elements (V0, D0, T0.Acc, etc.)

  • data formatting functions (FmtInt, FmtReal, etc.)

  • string selection function (Lookup)
    raw (binary) data

 

For a complete description of the available data options provided by the scripting language for use in the Text Field, see the Help reference for the Scripting Language.

 

On Success: - designates one of the following two options if the Send Email operation is successful:

 

  • SET BIT - The specific BIT location will be SET OFF when the Send Email (EMAIL) instruction is first enabled, and then SET ON if the operation is successful. This value can be any writable bit location.
     

  • JMP to Stage - JMP to the specified Stage. The target Stage must be in the same Program as the Send Email (EMAIL) instruction, you cannot specify a Stage in a different Program. This selection will function the same as a standalone Jump to Stage instruction. Click here for more information on the Jump To Stage instruction.

 

On Error: - designates one of the following two options if the Send Email operation is unsuccessful:
 

  • SET BIT - The specific BIT location will be SET OFF when the Send Email (EMAIL) instruction is first enabled, and then SET ON if the operation is unsuccessful. This value can be any writable bit location.
     

  • JMP to Stage - JMP to the specified Stage. The target Stage must be in the same Program as the Send Email (EMAIL) instruction, you cannot specify a Stage in a different Program. This selection will function the same as a standalone Jump to Stage instruction. Click here for more information on the Jump To Stage instruction.

 

Testing the Send Email Instruction:

Do-more Designer makes it a rather simple task to test the Send Email instruction.

 

There are two reserved strings that receive error and status information while the controller is in RUN mode:
 

  • The system string $MSG receives status information and any time an instruction sets an error code
     

  • the system string $ERR will display an associated text message that explains what the error code means.

 

Utilizing the Do-more Logger utility to capture and display the SMTP traffic between the Do-more controller and the SMTP Server allows the programmer to easily verify that the instruction is working.

 

Setting the system status bit $EnableMsgDump (ST36) to ON will cause the Send Email instruction to echo the SMTP traffic to the Do-more Logger.

 

See Also:

 

Related Topics:

 

Example using Stages:

 

Rung Example: