get_external/4

The get_external/4 primitive runs an external program and waits for its termination to continue to process the current event by using data retrieved through an interface object.

Note

The get_external/4 primitive can be used only in a refine rule.

get_external($PROG,$ARGS,$INTF,$ANS)

get_external/4 arguments

Argument	Mode	Type	Description
$PROG	Input	STRING	Specifies the name of the external program to be run
$ARGS	Input	LIST_OF ANY	Action argument list. Required arguments for the program must be provided in the $ARGS list. The arguments are passed to the external program as command-line arguments.
$INTF	Input	STRING	Specifies the name of the interface class
$ANS	Output	OBJECT	The data produced by the external program returned as an interface object

Use get_external/4 to run the program specified in the $PROG argument as an external process on the current event and wait for the program to terminate before continuing to process the event. On successful return, the interface object specified by the $INTF argument is created that contains the data produced by the external program in the interface file. This object is available in the remainder of the rule by using the $ANS variable.

The program location is determined in the same manner as it is for action. For more information, see Actions. A call of get_external/4 suspends the processing of the current event. Upon termination of the program, processing of the current event is resumed. If the program is successful, 0 is returned as the exit status and the event passes through the remainder of the rules. If the program returns a non\-zero exit status, the event is dropped and no other rules are applied to it.

In addition, a file path is passed as extra first command-line argument. The external program is assumed to produce an instance of the $INTF interface class in that file.

The program is activated by using the slot name as environment variable name, in an environment that contains all the slots of the event. In addition, some system-defined variables are available. See the Infrastructure Management Administrator Guide for more information about action execution variables.

get_external/4 example

In this example, the Knowledge Base contains the following class definition:

MC_INTERFACE: DOOR_INFO DEFINES {
door_id: STRING;
door_location: STRING;
door_status: STRING;
}; END

An application could receive events that report incidents on doors. Such events would have mc_object_class set to DOOR. The following refine rule retrieves additional information:

refine get_door_info: EVENT($E) where [$E.mc_object_class==DOOR]
{
get_external(get_door_info,[$E.mc_object],DOOR_INFO,$DI);
$E.msg = concat(['Door ',$DI.door_id,' at ',$DI.door_location,
' changed status to ',$DI.door_status]);
}
END

The external program get_door_info is assumed to return the door information for the door that is indicated in the mc_object slot, as an instance of DOOR_INFO. If the door specified in mc_object is not recognized by the program, the program might fail and return a non-zero exit code. In that case, the event on which the program was triggered will be dropped.

get_external/4

On this page