Apama Documentation : Deploying and Managing Apama Applications : Correlator Utilities Reference : Injecting code into a correlator
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 (see Setting up the environment using the Apama Command Prompt) ensures that the environment variables are set correctly.
Synopsis
To inject applications into the event correlator, run the following command:
engine_inject [ options ] [ file1 [ file2 ... ] ]
When you run this command with the –h option, the usage message for this command is shown.
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 a hyphen (-) 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 Event Processing Language. For more information on EPL, see Introduction to Apama Event Processing Language. 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 Apama JMon Applications.
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.
Note:  
If a license file cannot be found, the correlator does not allow the injection of user-generated CDPs. See Running Apama without a license file.
Options
The engine_inject tool takes the following options:
Option
Description
-h | --help
Displays usage information.
-n host | --hostname host
Name of the host on which the event correlator is running. The default is localhost. Non-ASCII characters are not allowed in host names.
-p port | --port port
Port on which the event correlator is listening. The default is 15903.
-v | --verbose
Requests verbose output during engine_inject execution.
-u | --utf8
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 this option to override this assumption. The engine_inject tool then assumes that all input files are in UTF-8.
-V | --version
Displays version information for the engine_inject tool.
-j | --java
Indicates that each operand is a Java archive file (JAR file) that contains a single JMon application.
-c | --cdp
Indicates that each operand is a correlator deployment package (CDP) file.
-s | --hashes
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:
Operand
Description
[ file1 [ file2 ... ] ]
The names of zero or more files that contain application data in Apama EPL, JMon, or correlator deployment package (CDP) 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:
Value
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.
Copyright © 2013-2016 Software AG, Darmstadt, Germany.

Product LogoContact Support   |   Community   |   Feedback