Apama 10.15.0 | Deploying and Managing Apama Applications | Correlator Utilities Reference | Sending events to correlators
 
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.