Sending events to correlators

The engine_send tool sends Apama-format events into a correlator. The executable for this tool is located in the Apama/bin directory.

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.

Synopsis

To send Apama-format events to a correlator, 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).

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.

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