EVENT

Concept Link IconSee also Concept Link IconExample

Program the execution of a function on the change of a variable.

WebVue support - Yes.

Mode Mnemonic Syntax
1 ADD, ADDPROG 1
2 ADDPROGEVT 7
3 DELPROGEVT 8
5 DEL 2
6 DELALL 3
1 ADD, ADDPROG 1
7 IMPORTBYFILE 5
8 IMPORTBYHANDLE 6
9 ADDEMAIL 9
10 DELEMAIL 8
11 ADDPROGS 1
12 ADDSMS 10
13 DELSMS 8
14 TRACE 11
21 DELPROG 4

Any program from which functions are triggered must be preloaded.

Variable names should not be preceded by the @ character.

The use of DELAY within a function called periodically may produce unpredictable results and should be avoided.

Arguments common to more than one mode

Sense is an expression that defines the conditions under which the event is triggered. The available options depend on the type of variable with which the event is associated. Refer to the topic Conditions of Variables.
Argument Description
Sense

A string or string variable defining the trigger condition. Type STR.
Prog

The name of the program that contains the function tobe executed. Type STR.
VarName

The name of a variable from the Variables Tree. Type STR.
Branch

The branch for the above program. Type STR.
Func

The name of the function that is to be executed. Type STR.
Farg

Optional. A string of 2,047 characters maximum used to provide up to 8 arguments (separated by comma ",") to the function. The arguments are retrieved in the function using the verb GETARG.
Name

The name of the event. The string you enter here will appear in the Name field of the Event Configuration dialog and is also used as the identifier when deleting the event programmatically. Type STR.

Description

A description for the event. The string you enter here will appear in the Description field of the Event Configuration dialog. Type STR.
ActiveBit

Optional. The name of the bit or alarm variable which enables the event. Type STR.

ServerListName

The name of a server list. On multi-station applications, the event will only be active on a server station that appears in the list. Type STR.

Syntax 1

IntVal = EVENT(Mode, VarName, Sense, Prog, Branch, Func[, Farg [, ActivBit]]) ;

Return type: INTEGER.

Argument Description

ActivBit

Optional. The name of the bit or alarm variable which enables the event.

Execution

Mode Mnemonic Description

1

ADD, ADDPROG

Create an event. The conditions under which the event is triggered are defined by the Sense expression. If a function name is not supplied the MAIN function will be triggered. Any existing event attached to the variable will be replaced.

11

ADDPROGS

Add an event. The conditions under which the event is triggered are defined by the Sense expression. You can attach multiple events with triggering different functions with different senses to the same variable.

Syntax 2

IntVal = EVENT(Mode, VarName[, Sense, Prog, Branch, Func] );

Return type: INTEGER.

Execution

Mode Mnemonic Description

5

DEL

Delete an existing event.

The sense must be the same as the original event.

If the Sense, Prog, Branch and Identity parameters are missing, then all events attached to the named variable are deleted.

Return: 1 if successful, else 0.

Syntax 3

IntVal = EVENT(Mode [, Type, DelAllMode]);

Return type: INTEGER.

Argument Description

Type

The type of events to be deleted. Type INTEGER.

0 = Delete all events regardless of their type. This is the default if Type is not used.
1 = Delete all program events.
2 = Delete all e-mail events.
DellAllMode

Optional argument to indicate which events should be deleted, temporary created by program and/or permanent events created by configuration. Type: INTEGER.

1 = Delete temporary events only (default value),
2 = Delete permanent events only,
3 = Delete both temporary and permanent events.

Execution

Mode Mnemonic Description

6

DELALL

Delete all existing events.

Return: Always 1.

Syntax 4

IntVal = EVENT(Mode, VarName, Sense, Program, Branch, Function);

Execution

Mode Mnemonic Description

21

DELPROG

The identified single event is deleted. All the arguments are required.

Return: 1 if successful, else 0.

Syntax 5

IntVal = EVENT(Mode, FileName);

Return type: INTEGER.

Argument Description

FileName

Name of the text file in the TP folder of the project or in a folder selected by an absolute path. Type STR.

The formats of event files, and of the means for adding and deleting them, are specified in the topic Format for import of event configuration.

Execution

Mode Mnemonic Description

7

IMPORTBYFILE

Obtain events from the file in the specified folder.

Return:
0 if the file could not be found or if it contained no element to import.
Otherwise, a positive number corresponding to the number of lines processed as part of the import.
A line may have been processed and not caused any configuration change if its syntax was invalid or if it referred to the deletion or modification of an element that did not exist in the configuration.

Example

Copy 
EVENT(7, "addEvent.dat");
'OR
EVENT("IMPORTBYFILE", "addEvent.dat");

Syntax 6

IntVal = EVENT(Mode, Handle);

Return type: INTEGER.

Argument Description

Handle

Address of the buffer memory area as allocated by ALLOC_BUFFER. Type LONG.

Execution

Mode Mnemonic Description

8

IMPORTBYHANDLE

Obtain events from a buffer.

Returns: 1 if OK, else 0.

Example

Copy 
DIM hbuf AS LONG;
hbuf = FILETOBUF("addevent.dat");
EVENT(8, hbuf);
'OR
EVENT("IMPORTBYHANDLE", hbuf);

Syntax 7

IntVal = EVENT(Mode, Name, Description, ServerListName, VarName, Sense, Prog, Branch, Func[, Farg [, ActiveBit]];

Return type: INTEGER.

Execution

Mode Mnemonic Description

2

ADDPROGEVT

Create an event. The conditions under which the event is triggered are defined by the Sense expression. If a function name is not supplied the MAIN function will be triggered. An existing event with the same name will be replaced.

Returns: 1 if OK, else 0.

Syntax 8

IntVal = EVENT (Mode, Name);

Return type: INTEGER.

Execution

Mode Mnemonic Description

3

DELPROGEVT

Delete the named event.

Returns: 1 if OK, else 0.

10

DELEMAIL

Delete the named e-mail event.

Returns: 1 if OK, else 0.
13 DELSMS

Delete the named SMS event.

Returns: 1 if OK, else 0.

Syntax 9

IntVal = EVENT (Mode, Mode, Name, Description, ServerListName, VarName, Sense, EmailTemplate, [, ActiveBit [, EmailProfile [, To [, Cc [, Bcc [, Subject [, Message [, FileAttachments [, Priority[, MessageFormat [, MessageEncoding]]]]]]]]]]])

Return type: INTEGER.

Argument Description

EmailTemplate

The name of an email template as configured in Actions.Email.Templates. The template field may be left blank. Type STR.

EmailProfile

Optional. The name of an email profile as configured in Actions.Email.Profiles. The profile provides information such as the outgoing (SMTP) server name. If no profile is specified then the default profile is used. Type STR.

To

Optional. The address of the recipients as a list of semicolon delimited e-mail addresses. Type STR.

Cc

Optional. The address of any carbon copy recipients as a list of semicolon delimited e-mail addresses. Type STR.

Bcc

Optional. The address of the blind carbon copy recipients as a list of semicolon delimited e-mail addresses. Type STR.

Subject

Optional. The e-mail subject line. Type STR.

Message

Optional. The body of the e-mail message. Type STR.

FileAttachments

Optional. A list of semicolon delimited file attachments. Files in the list must be specified with absolute paths. Type Str.

Priority

Optional. The priority of the message. Any numeric type.

0 = Normal
1 = Low
2 = High

MessageFormat

Optional. The format of the body of the e-mail message. Any numeric type.

0 = Plain text
1 = HTML

MessageEncoding

Optional. The encoding for the body of the e-mail topic. See the Message Encoding topic

If a template is specified and, in the template, the behavior of a property was configured as Imposed By The Template, the properties in the template will overwrite any that you configure in the instruction. The properties affected are EmailProfile, To, Cc, Bcc, Subject, Message, Attachments, Priority, MessageFormat and MessageEncoding.

Execution

Mode Mnemonic Description

9

ADDEMAIL

Create an event triggering an e-mail. The conditions under which the event is triggered are defined by the Sense expression. If an event of the same name already exists, it will be replaced.

Returns: 1 if OK, else 0.

Syntax 10

IntVal = EVENT(Mode, Name, Description, ServerListName, VarName, Sense, MsgTemplate, [, ActiveBit [, SmsProfile [, PhoneNumbers[, Subject [, Message [, Format]]]]]]) ;

Return type: INTEGER.

Argument Description

MsgTemplate

The name of a message template as configured in Actions.Messages.Message templates. Type STR.

SmsProfile

 The name of an SMS profile as configured in Actions.Messages.SMS profiles. The profile provides information about the connection port and the simcard of the modem. Optional. Type STR.

PhoneNumbers

 The telephone numbers of the SMS recipients. Multiple numbers must be separated by semicolons. Optional. Type STR.

Subject

 The SMS subject. Optional. Type STR.

Message

 The SMS message. Optional. Type STR.

Format

The message format. Optional.

0 = Auto (Default value)

1 = Text

2 = PDU 7-bit

3 = Unicode

Execution

Mode Mnemonic Description

12

ADDSMS

Create an SMS event. The change in value of the variable under which the event is triggered is defined by the Sense expression.

Syntax 11

IntVal = EVENT(Mode, SubMode);

Return type: INTEGER.

Argument Description
SubMode

Either "ON" or "OFF". Type STR.

Execution

Mode Mnemonic Description
14 TRACE

Activate ("ON") or deactivate ("OFF") diagnostic messages. Trace message appear in the Event Window (F7) and are generated each time an event is triggered.

Return: always 1 if successful, else 0.

Trace message example

Copy 
[SV.Events] The traces are activated
[SV.Event.Program]<Branch01.Branch02.Bit01:Session.Event01> Run program=p.scb function=VarEvent args= Branch=
[SV.Event.E-mail]<Branch01.Branch02.Bit05:Session.Event01> Send Email or Sms or Fax, subject=Test From Bit05