Sending events to correlators
The
engine_send tool sends Apama-format events into a correlator or IAF adapter. 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.
If the events you want to send are not in Apama format, you must use an adapter that can transform your event format into Apama event format.
Note:
You can also send events using Software AG Designer. For more information, see
Sending an event from the Engine Information view.
Synopsis
To send Apama-format events to a correlator or IAF adapter, run the following command:
engine_send [ options ] [ file1 [ file2 ... ] ]
When you run this command with the –h option, the usage message for this command is shown.
Description
The engine_send tool sends Apama-format events to a correlator. In Apama-format event files, you can specify whether to send the events in batches of one or more events or at set time intervals.
The correlator reads events from one or more specified files. Alternatively, you can specify a hyphen (-) or not specify a filename so that the correlator reads events from stdin until it receives an end-of-file signal (Ctrl+D on UNIX and Ctrl+Z on Windows).
For details about Apama-format events, see
Event file format.
By default, the engine_send tool is silent unless an error occurs. To view progress information during engine_send execution, specify the -v option when you invoke engine_send.
You can also use engine_send to send events directly to the Integration Adapter Framework (IAF). To do this, specify the port of the IAF. By default, this is 16903.
Options
The engine_send tool takes the following options:
Option | Description |
-h | --help | Displays usage information. Optional. |
-n host | --hostname host | Name of the host on which the correlator to which you want to send events is running. Optional. The default is localhost. 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. |
-c channel | --channel channel | For events for which a channel is not specified, this option designates the delivery channel. If a channel is not specified for an event and you do not specify this option, the event is delivered to the default channel, which is the empty string. All public contexts receive events sent to the default channel. All queries receive events sent to the default channel. To send events to only running Apama queries, specify the com.apama.queries channel. See
Defining Queries. Note:
Apama queries are deprecated and will be removed in a future release. |
-l count | --loop count | Number of times to cycle through and send the input events. Optional. Replace count with one of the following values:  0 — Indicates that you want the engine_send tool to iterate through and send the input data once. This is the default. Any negative integer— Indicates that you want the engine_send tool to indefinitely cycle through and send the input events. Any positive integer — Indicates the number of times to cycle through and send the input events. The engine_send tool ignores this option if you specify it and the input is from stdin. |
-v | --verbose | Requests verbose output during execution. Optional. |
-u | --utf8 | Indicates that input files are in UTF-8 encoding. This specifies that the engine_send tool should not convert the input to any other encoding. |
-V | --version | Displays version information for the engine_send tool. Optional. |
Operands
The engine_send tool takes the following operands:
Operand | Description |
[ file1 [ file2 ... ] ] | Specify zero, one, or more files that contain event data. Each file you specify must comply with the event file format described in
Event file format. If you do not specify any filenames, the engine_send tool takes input from stdin. |
Exit status
The engine_send tool returns the following exit values:
Value | Description |
0 | The events were sent successfully. |
1 | No connection to the correlator was possible or the connection failed. |
2 | One or more other errors occurred while sending the events. |
Operating notes
To end an indefinite cycle of sending events, press Ctrl+C in the window in which you invoked the engine_send tool.
You might want to indefinitely cycle through and send events in the following situations:
In test environments. For example, you can use
engine_send to simulate heartbeats. If you then kill the
engine_send process, you can test your EPL code that detects when heartbeats stop.
In production environments. For example, you can use the
engine_send tool to initialize a large data table in the correlator.
Text encoding
By default, the engine_send tool checks the environment variable or global setting that specifies the locale because this indicates the local character set. The engine_send tool then translates 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_send 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_send tool. This forces the tool to treat each input file as UTF-8.