Difference between revisions of "Event Handler"

Revision as of 14:37, 4 July 2007

Event Handler - Block Diagram

The AlphaCom exchange is an intercom exchange of which the main task is to enable uni- and bi-directional speech. In order to be able to meet as many customer requirements as possible when it comes to special features an Event Handler has been implemented. The underlying idea is that by customer-programming this event handler functionality can be implemented which is not part of the standard feature list. The event handler is unique in the world of intercom. It is what gives the exchange its flexibility and makes it possible to meet most, if not all, customer requirements.
The Event Handler is based on the software concept that when the intercom functions run, they report 'events' to a part of the software called the Event Handler. The event can be described as a trigger that sets off an action in the system depending on the information entered in AlphaPro, the programming tool for the AlphaCom exchange. In this way, the Event Handler provides a powerful engineering tool for configuring system behaviour to meet requirements from customers.

Actions can be simple, just to operate a relay under certain circumstances. Actions can also be programmed using a scripting language and can include conditional statements. An action can itself trigger a new event, making it possible to start a chain of actions.

In the case of the scheduler the event is the ‘minute tick’. Stations can trigger many different types of event.
Many events can trigger an action when the event is activated and when the event is de-activated, for instance event type 07: Conversation – Incoming. The On/Off action can be differentiated by the ‘When Change To’ flag.
Events can be, but don't have to be, related to a specific directory number or a group of stations, for instance:

Owner: Station 1
Event: Conversation - Outgoing
Related to: Directory number 102
When change to: ON
Action: RCO 2 ON

In this case the relay connected to RCO 2 will only be activated if 'Station 1' is in conversation with a station with directory nr 102, AND if Station 1 was the station which made the call. If 'Related to' was not specified, that same relay would be activated on any call which Station 1 would make.

Events Types

The list shows the event types available, grouped by function.

Event Type	No.	When triggered
Single Station Events
Audio	01	When audio is played in the speaker
Door Open - Automatick Lock	03	When the Code Lock feature is dialed
Station in Use	04	When a station becomes busy or free
Microphone Open	05	When the microphone is alive
Faulty Station Line	13	When a station is reported faulty or OK
M-key	31	When the M-key is pressed or released
Off-hook	32	When the handset is lifted or replaced
Conversation Events
Conversation Incoming	07	When a call is received
Conversation Outgoing	08	When a call is made
Private Ringing mode	09	During private ringing
Door Opening - During Conv.	02	When door opening feature (digit 6) is activated during conversation
Mail (Call Queue) Events
Received Mail	10	When a mail or a call request is received
Call Requester Mode	13	When a station sends a Call Request
Priority Mail Present	06	When a mail with priority level 100 (programmable) is present in the mail queue
Priority Mail in Idle	12	When a priority mail is present, and the station is not in conversation
Mail Timeout	20	When a mail times out
New Current Mail	23	When the current mail in the queue is changed
New First Mail	24	When a new mail arrives first in the queue
Conference Events
Simplex Conference Audio	16	When listening to simplex conference, and the $VOX command is activated
Simplex Conference Member	17	When a station joins a simplex conference
Open Duplex Conf. Ringing	18	During ringing to an open duplex conference
Open Duplex Conf. Connect	19	When a station connects to an open duplex conference
Event Triggers
Event Trigger	15	When dialing a directory number with feature number 52, 85, 95 or 105
Event Trigger with parameter	25	When dialing Event Trigger feature 95 or 105, preceeded by a directory number or digit
Start: Event Trigger with param.	26	When dialing a directory number with feature number 95
Event Timeout	21	When a timer started by the $ST command expires
Station DAK key as RCI	30	When a DAK key is pressed
Scheduling
Scheduler (Minute Tick)	22	When matching the specified date (or weekdays) and time
EDI - External Data Input
External Data Input	28	When receiving ASCII data on EDI port
System Events
System Status	27	When a device is reported up or down
AlphaNet Link	29	When an AlphaNet link is reported up or down

Action Commands

There are two types of Action Commands which can be used by the Event Handler, Built-In Action Commands and Data Protocol Commands.

Both type of commands can include parameters and macros (e.g. %1.dir and %clk(8))

Built-In Action Commands

Built-in Action Commands are three- or four-letter commands. The commands are case-insensitive as from AMC 08.20. Most of the Built-In commands also have a Data Protocol implementation.

Command	Description	From AMC ver.
PRS	Audio Program to Station
PRG	Audio Program to Group
CNG	Simplex Conference to Group
MST	Mail to Station
MGR	Mail to Group
MPP	Mail to Pocket Pager
AMS	Alarm Message to Station
AMG	Alarm Message to Group
RCO	Set Remote Control Output
EDO	Send text to serial port External Data Output EDO 1 - 4
LOG	Send text to exchange’s log port (including date/time)
IND	Indicator control for CRMIV LEDs, buzzer etc.
OWN	Modify Event Owner (%1) and/or Related_To (%2) values
WUDD	Write a value to an User Defined Data UDD
TMP	Write a string to a temporary variable

Data Protocol Commands

Data Protocol Commands are using ASCII commands in the Simple Link Layer format. The commands begin with $ or @. Data Protocol Commands became available for use in the Event Handler from software version AMC 08.00.

Parameters and macros

Action commands used in the Event Handler can contain parameters and macros. Parameters and macro operations in an action string are preceded by the '%'-sign. They both return a value.

Parameters are related to the actual event, and refer to the involved station(s) or functions.

%1: the parameter is associated with the Owner field
%2: the parameter is associated with the Related to field
%3: the parameter is associated with the When change to field

A macro is unrelated to the event itself. It reads information from the memory (nvram) or performs a calculation. A macro always starts with the character "%".

Macros and parameters can be nested freely, and makes it possible to build complicated expressions.

Parameters and macro’s:

%n.dir(length,filler) :
- n can be 1 or 2
- empty () can be omitted; %n.dir is equivalent to %n.dir()
- shortform: %nd
%n.phy(length,filler)
- n can be 1 or 2
- empty () can be omitted; %n.phy is equivalent to %n.phy()
%n.nod()
- n can be 1 or 2
%n.ref
- n can be 1 or 2
%n.nam(length,filler) : returns the display text
- n can be 1 or 2
- shortform: %nn
%n.dak(DAK search string,D_10 range)
- n can be 1 or 2
%n.exp : External Feature Parameter
- n can be 1 or 2
%n.DEV : returns the device number (as from AMC 9.03).
- n can be 1 or 2
- if n equals 2, it will work only if the 'related to' parameter is a station in the same node
%n.BRD : returns the board number (as from AMC 9.03).
- n can be 1 or 2
- if n equals 2, it will work only if the 'related to' parameter is a station in the same node
%n.PORT : returns the port number (as from AMC 9.03).
- n can be 1 or 2
- if n equals 2, it will work only if the 'related to' parameter is a station in the same node
%3.chg(on_text,off_text)
- %3.chg(,) can be shorted to %chg(,)
%3.RFT(normal_text,refresh_text) : Action command parameter which substitutes the parameter with a text describing the on/off transition of the event. Some events can be reported many times (e.g. line errors), and it's possible to have different actions depending on if this is the first time, or a ReFresh.
- can be shorted to %3r(on_text,off_text)
%1.mpri : returns the priority of the mail
%1.mfre : returns the free text of a station mail if it is available, otherwise '-'
%1.tag : returns the mail tag
%sng(station, group) : (Station Next Group). Returns the next group after group of which station is a member. Returns '0' if station is not a member of any (more) groups. %sng(station, 0) returns the first group of which station is a member.
- group is 1 – 100, station is physical number 0 – 552.
%gns(group, station) : (Group Next Station). Returns the next station after station which is a member of group. Returns ‘0’ if no more members in group. %gns(group, 0) returns the first station in group.
- group is 1 – 100
- station is physical number 0 – 552.
%sgm(station,group) (Station Group Membership). Returns '1' if station is a member of the group.
- group is 1 – 100
- station is physical number 0 – 552.
%UDD(index) : Command string macro to get the User Defined Data out of the location 'index'.
%SEV : Returns the sub-event number (in decimal format) of the event being processed. If the sub-type of en event is defined as 255, the main event will be triggered independent on the reported sub-type. If this is used with feature 105, 'Event trigger on dialling digits', %SEV will return the dialled digit. (introduced in AMC software 9.03)
%OP( , , ) : macro for numeric calculations. The general format is %OP(integer1,operator,integer2), no space is allowed between ',' and the operator. The operator can be:
- + add
- - subtract
- * multiply
- / divide
- < less
- <= less or equal
- > greater
- >= greater or equal
- = equal
- == equal
- != not equal
- << bit shift left / up
- >> bit shift right / down
- && logical and
- || logical or
- & bitwise and
- | bitwise or
- ! logical not of second operand
- ^ bitwise xor
%clk
- returns current date/time 2000-11-10 12:59:35
%clkyear
- returns current year: 2000
%clkmon
- returns current month: 11
%clkday
- returns current day: 10
%clkhour
- returns current hour: 12
%clkmin
- returns current minute: 59
%clksec
- returns current second: 35
%clkwday
- returns current day of week: 5 (1 = monday, 7 = sunday)
%1.clk, %1.clkmin %1.clkhour etc. will return the scheduling tick time, not the real time if used within a Scheduling action.
%GNV() : returns the value of the NVRAM-parameter, of which the address is specified in between () (as from AMC 9.05).
- %GNV(1,3,54) returns the value of 'ex_profile.timeouts.th_conn_length' in AMC 9.05. Note that the address can be different in different AMC software versions.

Statements

PAUSE pauses the event handler command interpreter for 100ms

IF/ENDIF Conditional statement. If the text/expression after the keyword IF evaluates to ‘0’, all following commands/statements are skipped until the keyword ENDIF is encountered; IF/ENDIF statements can be nested

STOP The statement STOP stops the execution of the action string. Is only useful in front of the keyword ENDIF

Debugging Event Handler Actions

EDO port

TST Console

DT - data protocol trace

CSI - Command String Intepreter

@@ Line 165: / Line 165: @@
 [[#Action Commands|Action commands]] used in the Event Handler can contain '''parameters''' and '''macros'''. Parameters and macro operations in an action string are preceded by the '%'-sign. They both return a value.
-'''Parameters''' are related to the event and refer to the involved station(s) or functions.
+'''Parameters''' are related to the actual event, and refer to the involved station(s) or functions.
 *'''%1''': the parameter is associated with the ''Owner'' field
 *'''%2''': the parameter is associated with the ''Related to'' field