Apama 10.15.0 | Deploying and Managing Apama Applications | Correlator Utilities Reference | Deleting code from a correlator
 
Deleting code from a correlator
The engine_delete tool removes EPL code and JMon applications from the correlator. The executable for this tool is located in the bin directory of the Apama installation. Running the tool in the Apama Command Prompt or using the apama_env wrapper (see Setting up the environment using the Apama Command Prompt) ensures that the environment variables are set correctly.
Note:
Apama's in-process API for Java (JMon) is deprecated and will be removed in a future release.
Synopsis
To remove applications from the correlator, run the following command:
engine_delete [ options ] [ name1 [ name2 ... ] ]
When you run this command with the –h option, the usage message for this command is shown.
Description
The engine_delete tool deletes named applications, monitors and event types from a correlator. Names are the full package names as previously assigned to an application monitor or event type when injected into the correlator.
To specify the items you want to delete, you can specify any one of the following in the engine_delete command line:
*Names of the items to delete.
*The -f option with the name of a file that contains the names of the items you want to delete. In this file, specify each name on a separate line.
*Neither of the above. In this case, the engine_delete tool reads names from stdin until you type an end-of-file signal, (Ctrl+D on UNIX and Ctrl+Z on Windows). If you want, you can specify a hyphen (-) in the command line to indicate that input will come from stdin.
The tool is silent by default unless an error occurs. To receive progress information, specify the –v option.
The tool permits two kinds of operations: delete and kill. These cause different side-effects. Therefore, you must use them carefully.
*When you delete a monitor, the correlator tries to terminate all of that monitor's instances. If they are responsive (not in some deadlocked state), each one executes its ondie() action, and when the last one exits the correlator calls the monitor's onunload() action. This assumes that the monitor you are deleting defines ondie() and onunload() actions.
If a monitor instance does not respond to a delete request, the correlator cannot invoke the monitor's onunload() action. In this case, you must kill, rather than delete, the monitor instance.
*When you kill a monitor, the correlator immediately terminates all of the monitor's instances, without invoking ondie() or onunload() actions.
Time taken to delete code
Deleting code from a correlator can require scanning the state of the correlator to ensure that the types being deleted are no longer in use. Thus, the deletion will run at least as slowly as it takes the slowest context in the correlator to respond to external events, and will depend on how many objects there are live in the correlator.
If a type is found to be in use and you are not using the -F or -a option, then the deletion will fail with an error message, reporting what is still using the type that was requested to be deleted. If events of the type being deleted are sent to the correlator, they will fail to be parsed and the correlator will report errors.
Options
The engine_delete tool takes the following command line options:
Option
Description
-h | --help
Displays usage information. Optional.
-n host | --hostname host
Name of the host on which the correlator is running. The default is localhost. Optional. Non-ASCII characters are not allowed in host names.
-p port | --port port
Port on which the correlator is listening. Optional. The default is 15903.
-f filename | --file filename
Indicates that you want the engine_delete tool to read names of items to delete from the specified file. In this file, each line contains one name. Optional. The default is that input comes from stdin.
-F | --force
Forces deletion of named event types even if they are still in use. That is, they are referenced by active monitors or applications. A forced delete also removes all objects that refer to the event type you are deleting. For example, if monitor A has listeners for B events and C events and you forcibly delete C events, the operation deletes monitor A, which of course means that the listener for B events is deleted. Optional. The default is that event types that are in use are not deleted.
-k | --kill
Kills all instances of the named monitor regardless of whether an instance is in use. For example, you can specify this option to remove a monitor that is stuck in an infinite loop. Any ondie() and onunload() actions defined in killed monitors are not executed.
-a | --all
Forces deletion of all applications, monitors, and event types. The correlator finishes processing any events on input queues and then does the deletions. Any events sent after invoking engine_delete -a are not recognized. Specifying this option does not stop a monitor that is in an infinite loop. You must explicitly kill such monitors. Specifying the -a option is equivalent to specifying the -F option and naming every object in the correlator. If you want to kill every object in the correlator, shut down and restart the correlator. See Shutting down and managing components.
-y | --yes
Removes the are you sure? prompt when using the -a option.
-v | --verbose
Requests verbose output.
-u | --utf8
Indicates that input files are in UTF-8 encoding. This specifies that the engine_delete tool should not convert the input to any other encoding.
-V | --version
Displays version information for the engine_delete tool.
Operands
The engine_delete tool takes the following operands:
Operand
Description
[ name1 [ name2 ... ] ]
The names of zero or more EPL or JMon applications, monitors and/or event types to delete from the correlator. If you do not specify at least one item name, and you do not specify the -f option, the engine_delete tool expects input from stdin.
Exit status
The engine_delete tool returns the following exit values:
Value
Description
0
The items were deleted from the correlator successfully.
1
No connection to the correlator was possible or the connection failed.
2
Other error(s) occurred while deleting the named items.