Event Handler
From Zenitel Wiki
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.
Contents
The principal
An event has an owner, the source which triggers the event. The following possible owners are defined:
- A single station
- A group of stations (UDP group) with common behaviour
- The scheduler, the internal AlphaCom clock which generates a ‘tick’ every minute
- EDI Text, a data port set up to receive ASCII text strings from external devices
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 available event types, 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.
Context Parameters and macros
Action commands used in the Event Handler can contain context parameters and macros. They both return a value.
Context Parameters are related to the actual event, and refer to the involved station(s) or functions. A parameter always starts with the character "%". Context parameters are useful for defining the action of a rule where the condition is a UDP_group.
- %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. Also a macro always starts with the character "%".
Macros and parameters can be nested freely, and makes it possible to build complicated expressions.
List of context parameters
Parameter | Short name (owner) | Returned value | From version |
---|---|---|---|
%1.phy | %1p | The physical number | AMC 06.00? |
%1.dir | %1d | The directory number | AMC 06.00? |
%1.nam | %1n | The name (display text) | AMC 06.00? |
%1.exp | %1e | The User defined parameter | AMC 06.00? |
%1.dak | %1k | The number of the DAK key containing a specified string | AMC 06.00? |
%1.nod | The node number | AMC 06.00? | |
%1.ref | The node and directory number %1.ref is equivalent to "L(%1.nod) %1.dir" |
AMC 06.00? | |
%1.mpri | Priority of the mail. Available in mail related events only | AMC 06.00? | |
%1.mfre | Free-text of station mail if available, else ”-”. Available in mail related events only | AMC 06.00? | |
%1.tag | Mail tag. Unique mail identification. Available in mail related events only | AMC 06.00? | |
%1.dev | The device number | AMC 09.03 | |
%1.brd | The board number | AMC 09.03 | |
%1.port | The board number | AMC 09.03 | |
%3.chg | %3c | ON_txt when the event goes ON OFF_txt when the event goes OFF |
AMC 06.00? |
%3.rft | %3r | 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. | AMC 06.00? |
Note: %2 can be used instead of %1. %2 will refer to the 'Related To' filed instead of the 'Owner' field.
List of macros
Macro | Description | From version |
---|---|---|
%op | Macro for numeric calculations | AMC 08.20 |
%udd | Read User Defined variable | AMC 08.20 |
%tmp | Read Temporary variable | AMC 10.00 |
%sng | Next group which station is member of | AMC 08.20 |
%gns | Next member station of group | AMC 08.20 |
%sgm | Is station member of group | AMC 08.20 |
%sev | Read sub-event number | AMC 08.20??? |
%clk | Read current date/time | AMC 08.20 |
%clkyear | Read current year | AMC 08.20 |
%clkmon | Read current month | AMC 08.20 |
%clkday | Read current day | AMC 08.20 |
%clkmin | Read current minute | AMC 08.20 |
%clksec | Read current second | AMC 08.20 |
%clkwday | Read current day of week (1 = Monday, 7 = Sunday) | AMC 08.20 |
%1.clk, %1.clkyear etc | Read the sceduling tick time | AMC 08.20 |
%gnv | The value of the NVRAM-parameter | AMC 09.05 |
Formating
Text adjustment parameters can be added to all %xxx macros
- %xxx(width,filler)
- width: Length of field
- If ‘<’ is put immediately after the width, it means left-adjustment. Default is right adjustment
- filler: If width is wider than the returned value, the specified filler character is filled in
- Typical fillers are
- ” ” (space)
- ”0” (leading zero)
- ”F” (MPC protocol)
- The filler can be omitted: %xxx(width). Then ” ” (space) will be used as filler if required. It is not allowed with space between the formatting parameters
- Typical fillers are
Examples:
%1.dir
Minimum: %1.dir - Example result: “123” MPC format: %1.dir(4,F) - Example result: “F123” Two last digits: %1.dir(2) - Example result: “23”
%1.nam
Minimum: %1.nam - “Mr. Smith” 5 last characters: %1.nam(5) - “Smith” 12 char, right : %1.nam(12) - “ Mr. Smith” 12 char, left : %1.nam(12<) - “Mr. Smith ”
%udd (assuming decimal value 65 is stored in UDD 12)
%udd(12) - “65” %udd(12,4) - “ 65” %udd(12,4<) - “65 ” %udd(12,4,f) - “ff65” %udd(12,4<,f) - “65ff”
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
TMP - Write Temporary Variable
WUDD - Write User Defined Data