Injecting code into a correlator
To inject EPL files, JMon applications, or Correlator Deployment Packages (CDPs) into the correlator invoke the engine_inject tool. The executable for this tool is located in the bin directory of the Apama installation. Running the tool in the Apama Command Prompt ensures that the environment variables are set correctly.
Synopsis
To inject applications into the event correlator:
On Windows, run
engine_inject.exe.
On UNIX, run
engine_inject.
To obtain the following usage message, run the command without any options or with the –h option:
Description
The engine_inject tool reads application definitions from the specified file(s) and injects them into an event correlator. If you do not specify a filename, or if you specify "—" as the filename, the correlator reads data from the standard input device (stdin) until you indicate the end of the file: Ctrl-D on UNIX and Ctrl-Z on Windows.
Application definitions can be monitors scripted in Apama’s EPL language. For more information on EPL, see "Introduction to Apama Event Processing Language" in Developing Apama Applications in EPL (available if you selected Developer during installation). Alternatively, you can specify the –j or -c options. The -j option specifies that you will inject an application written in Java. The -c option specifies that you will inject a Correlator Deployment Package file.
When you specify the -j option, each file you inject must be a Java archive file (JAR) that contains a single JMon application. For more information, see "Overview of JMon Applications" in Developing Apama Applications in Java (available if you selected Developer during installation).
When you specify the
-c option, the file you inject must be an Apama Correlator Deployment Package (CDP). For more information on preparing a CDP, see
Packaging EPL and Java code.
By default, the engine_inject tool is silent unless an error occurs. To view information about engine_inject execution, specify the --verbose option.
If you try to inject invalid EPL files or invalid JMon applications, the event correlator generates an error. None of the application data in the invalid file is loaded. The engine_inject tool terminates. If you specify multiple EPL or Java files for injection the engine_inject tool injects all of them or terminates when it reaches the first file that contains an error. For example:
engine_inject 1.mon 2.mon 3.mon
If the 2.mon file contains an error then engine_inject successfully injects 1.mon and then terminates when if finds the error in 2.mon. The tool does not operate on 3.mon.
If you try to inject a CDP the correlator processes each EPL file packaged in the CDP separately. If one file in a CDP contains an error then the correlator reports an error for that file and does not run it but it does run the other files in the CDP (if they have no errors). It does not matter which file in the CDP contains the error. That is, the first file in the CDP that the correlator processes can contain an error and the correlator still runs the other files in the CDP if they contain no errors.
Options
The following table describes the options you can specify when you inject applications into the correlator:
Option | Description |
-h | Displays usage information |
-n host | Name of the host on which the event correlator is running. The default is localhost. Note: Non-ASCII characters in host names are not supported. |
-p port | Port on which the event correlator is listening. The default is 15903. |
-v | Requests verbose output during engine_inject execution. |
-u | Indicates that input files are in UTF-8 encoding. The default is that the engine_inject tool assumes that the EPL files to be injected are in the native character set of your platform. Set the -u option to override this assumption. The engine_inject tool then assumes that all input files are in UTF-8. |
-V | Displays version information for the engine_inject tool. |
-j | Indicates that each operand is a Java archive file (JAR file) that contains a single JMon application. |
-c | Indicates that each operand is a Correlator Deployment Package file. |
-s | Indicates that instead of injecting the specified files you want to print the hashes (UTF8-encoded) for the files. If engine_inject is operating on Java or Correlator Deployment Package (CDP) files then you must also specify -j or -c. |
Operands
The engine_inject tool takes the following operands:
[ file1 file2 ... ] ] | The names of zero or more files that contain application data in Apama EPL, JMon, or Correlator Deployment Package files. If you do not specify one or more filenames, the engine_inject tool takes input from stdin. |
Exit status
The engine_inject tool returns the following exit values:
Status | Description |
0 | All definitions were injected into the event correlator successfully. |
1 | No connection to the event correlator was possible or the connection failed. |
2 | Other error(s) occurred while injecting the supplied definitions. |
Text encoding
By default, the engine_inject tool uses the default system encoding to determine the local character set. The engine_inject tool then translates all submitted EPL text from the local character set to UTF-8. Consequently, it is important to correctly set the machine’s locale.
However, some input files might start with a UTF-8 Byte Order Mark. The engine_inject tool treats such input files as UTF-8 and does not do any translation. Alternatively, you can specify the -u option when you run the engine_inject tool. This forces the tool to treat each input file as UTF-8.