Injecting code into a correlator

To inject EPL files, Apama Java 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.

Usage: engine_inject [ options ] [ file1 [ file2 ... ] ]
In order to inject to a correlator.
Where options include:
-h | --help            This message
-n | --hostname <host> Connect to an engine on <host>
-p | --port <port>     Engine is listening on <port>
-v | --verbose         Be more verbose
-u | --utf8            Assume input is in UTF8
-V | --version         Print program version info
-j | --java            Operate on Java applications rather than EPL or CDP
-c | --cdp             Operate on CDP files rather than EPL or Java
-s | --hashes Print out hashes of (UTF8-encoded) files, rather
than injecting, to obtain hashes for Java or CDP
files also specify -j or -c
Use '-' to read from <stdin>

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 Java application. For more information, see "Overview of Apama Java Applications" in Developing Apama Applications in Java (available if you selected Developer during installation).

If you try to inject invalid EPL files or invalid Apama Java 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:

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.

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 Java 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.

[ file1 [ file2 ... ] ]

The names of zero or more files that contain application data in Apama EPL, Apama Java, or Correlator Deployment Package files. If you do not specify one or more filenames, the engine_inject tool takes input from stdin.

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.

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.