AFCON SOFTWARE AND ELECTRONICS LTD

P-CIM Email

AFCON SOFTWARE AND ELECTRONICS LTD

Table of Contents
Overview ....................................................................................................................................................... 3
System Requirements................................................................................................................................... 3
Using P-CIM Email in Interactive Mode.................................................................................................... 4
Runtime Usage in Interactive Mode ........................................................................................................... 4
Using P-CIM Email in Background Mode ................................................................................................. 5
Examples ....................................................................................................................................................... 6
AutoAction Example .................................................................................................................................. 6
Advanced Alarm Handler Example............................................................................................................ 7
Sending Email using P-CIM Alarm Pager Notification ............................................................................ 7
Send Rate and Dispatch Cycles .................................................................................................................. 8
System Requirements................................................................................................................................... 8
Setup Instructions......................................................................................................................................... 8
Enabling P-CIM Database Blocks .............................................................................................................. 9
Configuring the ODBC Data Source .......................................................................................................... 9
Configure the Email Parameters............................................................................................................... 10
Scheduling ................................................................................................................................................ 11
Message Format ....................................................................................................................................... 12
Run Time Usage.......................................................................................................................................... 13
Accessing the Dispatcher Configurator ................................................................................................. 13

Email Sender and Dispatcher

2 of 13

AFCON SOFTWARE AND ELECTRONICS LTD

Overview

With P-CIM Email you can dispatch alarm and system event messages to any email recipient or
to a group of email recipients. P-CIM Email can also be incorporated into the runtime (Operator
Workstation) display to allow a user to manually generate and dispatch email messages.
P-CIM Email integrates with a resident MAPI mail server to enable transmission.
P-CIM Email can operate in two modes:
Interactive
Background
In Interactive mode, the application displays the Email Sender form at the users station. The
user manually configures the content of the email message and sends it.
In Background mode, the parameters and layout of the email message are configured as an
Action command during the application development using a command-line syntax. This Action
command can then be associated with an:
Action Button
AutoAction
Alarm Class
When the Action is triggered, P-CIM Email composes and dispatches the email message
automatically.

System Requirements
To use P-CIM for Windows Email your system must include:
Any 32 Bit Windows OS
P-CIM for Windows or P-CIM for the Web Rev. 6.54+
A resident MAPI mail exchange service
Internet Mail access
For P-CIM Revision 6.54 - SEK enabled for Pager and Email transmission
For P-CIM Revision 6.60+ - SEK enabled for Email transmission (Pager not necessary)
Important Check that the resident mail exchange service is running before invoking P-CIM
Email.

Email Sender and Dispatcher

3 of 13

AFCON SOFTWARE AND ELECTRONICS LTD

Using P-CIM Email in Interactive Mode

Any user with access to the P-CIM Group can use P-CIM Email in Interactive mode as a standalone utility.
Accessing the Email Sender
1. Click on the Email Sender

icon.

2. Enter the relevant information for Address, Subject, and Message.

3. Choose the options for level of Importance and Read/Delivery receipt request.
4. Enter the profile that handles your mail services into the Profile field. If this field is left blank,
the default profile is called.
5. Choose Send to send or Cancel to quit.

Runtime Usage in Interactive Mode

You can configure a P-CIM display to invoke the P-CIM Email Sender form. To do this:
1. Create an Action button.
2. Configure the buttons Action with the following command: Email (no arguments).
Choosing this button at runtime invokes the form and allows the user to compose and send an
email message.

Email Sender and Dispatcher

4 of 13

AFCON SOFTWARE AND ELECTRONICS LTD

Using P-CIM Email in Background Mode

You can configure a P-CIM Button, an AutoAction, or an Alarm Class (using Advanced Alarm
Handler) to generate email messages for automatic transmission. This is called Background
mode because, in this case, the P-CIM Email Sender form does not need to appear as all the
activity takes place in the background.
To do so, create a Button, AutoAction or an Alarm Class and configure it using the Email
command.
In the Action property command line, configure the email parameters using the following syntax:
Email [{address|groupname} subject-text body-text [profilename] [-R|-D|-L|-H] [-#]]
Where:
Argument

Description

Comments

Address

Address(es) of recipient or group of

recipients

Maximum 256 characters. Multiple

recipients must be separated with a
;. Recognizes individual and group
nicknames. Address is not optional.

Subject

Subject text

Maximum 256 characters. Subject is

not optional but can be left blank by
inserting .

Body-text

Text of actual message

Maximum 512 characters. Body-text

is not optional but can be left blank
by inserting .

Profile name

Mail service profile that is to be used

Can be omitted, in which case the

default profile is called.

-R

Notification is sent to the sender

when the message is actually read

If the recipient deletes the message

without reading, a notification as
such is sent to the sender. Optional

-D

Notification is sent to the sender

when the message is delivered

Optional

-L

Message labeled for Low importance

-H

Message labeled for High

importance

If both switches are omitted, the

message is labeled Normal by
default. If both switches are
inadvertently inserted, the system
recognizes the latter.

-#

Number of retries to execute if

delivery fails

Email Sender and Dispatcher

Range of 1-9.

5 of 13

AFCON SOFTWARE AND ELECTRONICS LTD

Examples
Email user1@afcon-inc PLC failure L
When executed, email is sent to user1 with the Subject PLC failure and no message text, labeled
for Low importance. Uses default mail profile.
Email Shift Managers; Plant Foremen New Holiday Schedule Labor
Day night workers outlook R 3
When executed, email is sent to all users in the Shift Managers group and in the Plant Foremen
group. The message contains the Subject New Holiday Schedule and a text message that
contains Labor Day night workers (remainder of message). This message is labeled for Normal
importance (by default) and for Read notification. It specifies the profile outlook. It is configured
for 3 retries if not successful.
Email CEO@vacation.com; All Users Engine room is on fire R
D H 9
When executed, email is sent to CEO@vacation.com and to all users in the All Users group. This
message contains no Subject and a text message that contains the specified text. It is labeled for
Delivery and Read notification, High importance, and 9 (maximum) retries. Uses default profile.

AutoAction Example
To email to all plant foremen that the trend reports for the month are to be submitted. A possible
AutoAction script may be:
Action Name: TrendReportEmail
Trigger:

|!@AtDate(XXXX15)

Mode:

Up

Action:
Email Plant Foremen Trend Report Today is
?|!<<$Date>>?. Trend Reports are due! outlook D 3

Email Sender and Dispatcher

6 of 13

AFCON SOFTWARE AND ELECTRONICS LTD

Advanced Alarm Handler Example

You can assign Email as an Alarm action when configuring an Alarm Class in the Database
Editor (Database > Zones > Classes).
In this example, when a block associated with class OffHours Alarm triggers an alarm, email is
dispatched to the Off Premises Users group containing the readout of the alarm as the Subject.
There is no message text in this example, importance is Normal and there are no retries.

Sending Email using P-CIM Alarm Pager

Notification
Alarm enabled blocks can be configured to dispatch email messages at regular intervals that
contain a summary of the alarms that were generated over the duration of the interval.
To understand how to do this it is important to have a look behind-the-scenes.
If a Database block is Alarm Enabled i.e., the Enable option in the Alarm Table section is
checked AND one or both of the following options are likewise checked:
Pager on alarm
Pager on RTN
THEN, when an alarm occurs, an alarm message is written to the system variable
$DispatchAlarm. The alarm message is comprised of the following fields:
Node#

The node number of the P-CIM client station originating the alarm.

Date

The date of the alarm formatted using the Windows regional setting.

Time

The time of the alarm formatted using the Windows regional setting.

Tag-Name

The name of P-CIM database block.

Alarm-Type

Type of alarm (HIGH, LOW, ROC etc.).

Tag-Value EGU

The value of the block causing the alarm followed by the EGU notation as
specified in the block.

Tag-Description

The description of the block as specified in the database.

Email Sender and Dispatcher

7 of 13

AFCON SOFTWARE AND ELECTRONICS LTD

Each message is buffered in an ODBC database table. From this database, the alarm data is
retrieved and formatted and subsequently dispatched as email.
The P-CIM Email Dispatcher-Configurator is a utility for configuring recipient and message
parameters, formatting the alarm data, and for scheduling the time intervals for dispatch: Once
the message, format, and schedules are configured and the database block is enabled for
dispatch by enabling one or both of the Pager options at every Send Rate period, the P-CIM
Email Dispatcher retrieves the alarm data, formats the email message, and sends it to the target
recipient(s). No further user input is required.

Send Rate and Dispatch Cycles

Email is dispatched per message on a FIFO (First In First Out). That means that when a block
begins generating alarms they are buffered in the database table in chronological order. When
the email is to be dispatched, the application retrieves the first alarm in the buffer and dispatches
it to each recipient one by one (that is, for ten recipients there are ten consecutive email
dispatches NOT one simultaneous dispatch). When all the recipients have been served, that
alarm is cleared from the buffer.
It then retrieves the next alarm and repeats the dispatch procedure. This continues as long as
there are alarms in the buffer.
The rate of dispatch is called the Send Rate and is configured in the P-CIM Email DispatcherConfigurator. Minimum Send Rate is one second.
This is important since email is dispatched consecutively and not simultaneously. This means that
if you have, for example, ten recipients and the Send Rate is one second, you must allow at least
ten seconds per alarm for dispatch (it may actually take longer especially if retries are requested).
Likewise, for ten recipients, if the Send Rate is three seconds, you must allow 30 seconds for a
complete dispatch. This can be problematic if alarm generation is quite frequent and new alarms
arrive faster than they are dispatched. This can cause the buffer to back up and ultimately
overload. Care must be taken to avoid this scenario.

System Requirements
In addition to the components listed above (page 3), the host computer must also be equipped
with one of the following ODBC compatible database systems:
MS Access
SQL Server

Setup Instructions
There are three steps to setting up your P-CIM system for Alarm Pager Notification via email:
1. Properly enable the P-CIM database blocks.
2. Configure the ODBC Data Source.

Email Sender and Dispatcher

8 of 13

AFCON SOFTWARE AND ELECTRONICS LTD

3. Configure the email parameters for dispatch (i.e., Send Rate, recipients, scheduling,
message format, etc.).

Enabling P-CIM Database Blocks

For every database block that is to generate alarms for transmission, you must enable the
following options that appear in the Alarm Table section of the Properties box:
Enable
One or both of the following:
Pager on alarm
Pager on RTN

This tells P-CIM to send the alarm data to the ODBC buffer.

Configuring the ODBC Data Source

The second step is to define an ODBC data source.
The data source is the destination database format to which you want the ODBC Server to
convert the data (i*.dbf format, *.mdb format, SQL format, etc.). The file location must also be
defined in the data source definition. In step 3, you will reference this data source as the server
for the alarm data.
To define an ODBC data source:
1. From the Windows Start menu choose Settings >Control Panel > ODBC(32 BIT).

2. In User DSN, choose Add. The Create New Data Source dialog box appears.
3. Select the desired driver (for MS Access, select Microsoft Access Driver [*.mdb]; for SQL
select SQL Server, etc.). Click Finish.
4. In the Setup dialog box choose Create.
5. Specify a name and path for the data source. Click OK.
The new data source appears in the ODBC32 main window.
Email Sender and Dispatcher

9 of 13

AFCON SOFTWARE AND ELECTRONICS LTD

Configure the Email Parameters

The third step is to configure the email dispatch parameters. To do this:
1. Make sure that P-CIM is running.
2. From the P-CIM icon group, choose the P-CIM E-mail Dispatcher icon
The P-CIM Email Dispatcher-Configurator appears.

Note The Dispatcher Configurator appears only at the first use. After that, the Email
Dispatcher window appears (see Run Time Usage, page 13). To invoke the Dispatcher
Configurator from the Dispatcher window, choose File > Configuration
1. Begin at the Preferences tab.
2. Select the ODBC Data Source that you created earlier (see above, page 9) from the
drop-down list.
3. Enter a value for Send Rate (see page 8) in seconds. (Range: 1-999 seconds).
4. Enter a value for maximum retries (1-9).
5. Proceed to the Scheduler tab.

Email Sender and Dispatcher

10 of 13

AFCON SOFTWARE AND ELECTRONICS LTD

6. On the left side of the form, create a list of recipients.

7. To add new recipients: Type the email address of the entry into the upper field. You can
also type in a nickname or group name that is listed in your default address book.
8. Choose Add. The entry appears in the lower field. You can also invoke your default
address book and select the desired recipients. To do this, click on Browse Address
Book.
9. To edit recipients: Select the desired recipient from the list in the lower field. The entry
appears in the upper field.
10. Make your changes in the upper field.
11. Choose Change. The revised entry appears in the lower field.
12. To remove recipients: Select the desired recipient from the list in the lower field.
13. Choose Delete. The entry disappears.

Scheduling
By default all recipients receive email at all times. Use the Scheduler to designate time periods for
withholding transmission for each recipient.
To schedule a recipient:
1. Select the desired recipient from the list.
2. Enable the weekdays that are to be scheduled (choose Mute All to enable scheduling i.e. withholding - for all times).
3. Set the time periods for non-transmission (up to two time periods per weekday). Use 24hour format.
4. Repeat this procedure for all recipients that are to be scheduled.
Proceed to the Message Format tab.

Email Sender and Dispatcher

11 of 13

AFCON SOFTWARE AND ELECTRONICS LTD

Message Format
You can customize the message format for each recipient. To do this:
1. Select the recipient.
2. There are seven possible message fields as described above (page 7).
Place those that you wish to appear in the message in the Message Fields window. Place
the remainder in the Available Fields window.
Use the Add and Remove buttons to move the fields between windows.
3. The included fields appear in the Message Sample window. You can rearrange the order
by selecting the desired field in the Message Fields window and repositioning it using the
Move Right and Move Left buttons.
To restore the format to the default layout, choose Reset.
4. Choose the options for level of Importance, Profile, Read/Delivery receipt request.
5. Repeat steps 1-4 for all the recipients for whom you wish a customized format.
6. Click on Save. All of the settings configured in this session are stored in an INI file.
7. Click on Close to close the Dispatcher - Configurator.

Email Sender and Dispatcher

12 of 13

AFCON SOFTWARE AND ELECTRONICS LTD

Run Time Usage

Once the Email Dispatcher Configurator has been configured with an ODBC data source and at
least one recipient, Email Dispatcher can be invoked at run time both from the P-CIM icon group
and in a display.
To invoke P-CIM Email Dispatcher from the P-CIM icon group:
1. Choose the Email Dispatcher icon
. The icon appears in the Windows taskbar to
indicate that Email Dispatcher is running.
2. Double click on the icon or right-click on it and choose Open from the popup menu. The PCIM Email Dispatcher window appears. The window displays a line item indicating a
successful connection to the ODBC data source followed by a log of the messages that are
currently stored in the buffer.

3. To invoke P-CIM Email Dispatcher from a display:

4. Create an Action button and configure it with the following command:
Run edispatch.exe

Accessing the Dispatcher Configurator

To access the Dispatcher Configurator from the Email Dispatcher:
From the taskbar icon (window is minimized) right-click on the icon and choose Configuration
From the Dispatcher (window is maximized choose File > Configuration

Email Sender and Dispatcher

13 of 13