The When clauses execute if the ECF for the rule passes. The When clauses cause actions to occur and can generate or update existing events or create messages.
The When clause in rule phases is re-evaluated whenever a slot’s value changes, provided the ECF condition is met. This means that if a rule phase subsequent to the Execute phase changes a slot’s values, and the ECF for the Execute rule phase passes, the When clause is re-evaluated for that event in the Execute rule phase.
Note
Dynamic data values as resulting from a Using clause in the ECF may not be used in the When clause.
The Execute phase is often used to execute external programs in the context of an event. In order to do that, we use the execute primitive in a block. The syntax of the primitive is:
execute (Var, Program, [ArgList], Watch)
Execute runs a program with optional arguments on the cell. The arguments are as follows:
• Var is the name of the variable containing the event in the context of which the program is executed.
• Program is the name of the executable. The location of the executable is in the architecture specific directory under the bin
directory of the Knowledge Base.
• [ArgList] contains the list of comma-separated arguments passed to the executable as positional arguments ($1, $2, and so on). Note that all the slots and slot values of the event on behalf of which the executable runs are passed to the latter via environment variables. Use [ ] if the list is empty.
• Watch is a Boolean flag stating whether or not the execution result will generate an event containing the result of the action.
You can use environment variables in the executable script or program when creating an executable. The following is a list of available environment variables:
All slots are passed in the environment, in the form of variables (with the same names as the slot names) containing the slot values.
All variables that exist in the environment in which the cell is started are also passed but they cannot be enumerated because they are determined by the actual runtime environment.
Variable Definitions
MCELL_HOME The home directory where the cell resides.
CELL_NAME The cell name.
CELL_RELEASE The release number, for example, 1.1
CELL_BUILD The build numbe as can be found in the About box of the console.
CELL_DATE The date when the build was made.
PKG_NAME The name of the rule package.
RULE_NAME The name of the rule that triggered this external action.
REQUESTOR The requestor of the external action, either user@host for an action from a client or package:rule for an action initiated from a rule.
CLASS The class of the event under analysis.
SLOTS The list of slot names for this class.
HOME The home directory for the requestor.
LOGNAME A logfile name.
SHELL A shell program.
TERM A terminal type (Unix only).
All external action primitives have the same environment. The
environment variable REQUESTOR specifies the requestor of the external action. It is user@host for an action from a client and package:rule
for an action initiated from a rule. All variables from the initial cell startup environment are passed to the environment of external actions launched from the cell.
Examples
The following example Execute rule executes upon receipt of a
DiskUsedPercentage event. The When clause generates a new message for the event. The message that is sent by the event contains a value for the disk space used. The When clause uses primitives to convert the number received from the event to a whole number and then
concatenates the message.
execute Disk_Msg :
DiskUsedPercentage ($DUP) when $DUP.status: equals OPEN {
$V1 = round($DUP.value * 100) ;
concat([$DUP.sub_origin, ‘: ’, $V1, ‘% of space used’], $V2) ;
$DUP.msg = $V2 ; }
END
This example contains three When clauses for the event
APP_MISSING_PROCESSES. The first when clause fires upon receipt of an OPEN event. A new message is created with the concat primitive and a new event, APP_DOWN, is generated from the original event indicating the application is down.
execute Event_Status :
APP_MISSING_PROCESSES ($AMP) when $AMP.status: equals OPEN {
concat ([‘Application ’,
$AMP.application,‘ is down.’], $MSG) ;
generate_event (APP_DOWN, [hostname = $AMP.hostname, origin = $AMP.origin, date = $AMP.date,
application = $AMP.application, msg = $MSG ]) ; }
when $AMP.processes: equals [] {
$AMP.status = CLOSED ; }
when $AMP.status: equals CLOSED {
generate_event (APP_UP, [hostname = $AMP.hostname, origin = $AMP.origin,
application = $AMP.application]) ; execute ($AMP, make_noise, [], NO) ; }
END
The second When clause fires to close the APP_MISSING_PROCESSES
event when all processes for the application are running.
The third When clause fires and generates a new event, APP_UP, indicating the application is up when the original event is CLOSED. In addition, an executable is fired that sends a sound to the system indicating the application is up again.
This illustrates how to use primitives such as generate_event or