Receiving events from correlators
The engine_receive tool lets you connect to a running correlator and receive events from it. Events received and displayed by the engine_receive tool are in Apama event format. This is identical to the format used to send events to the correlator with the engine_send tool. Consequently, it is possible to reuse the output of the engine_receive tool as input to the engine_send tool.
The executable for this tool is located in the Apama/bin directory.
Synopsis
To receive Apama-format events from a correlator, run the following command:
engine_receive [ options ]
When you run this command with the –h option, the usage message for this command is shown.
Description
The engine_receive tool receives events from a correlator and writes them to stdout or to a file that you specify. The correlator output format is the same as that used for event input and is described in Event file format.
You can specify one or more channels on which to listen for events from the correlator. The default is to receive all output events. For more information, see Subscribing to channels.
To view progress information during engine_receive execution, specify the –v option.
Options
The engine_receive 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 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 |
Named channel on which to listen for output events from the correlator. Optional. The default is to listen for all output events. You can specify the -c option multiple times to listen on multiple channels. |
-f file | --filename file |
Dumps all received events in the specified file. Optional. The default is to write the events to stdout. |
-s | --suppressBatch | --suppressbatch |
Omits BATCH timestamps from the output events. Optional. The default is to preserve BATCH timestamps in events. |
-z | --zeroAtFirstBatch | --zeroatfirstbatch |
Records the first received batch of events as being received at 0 milliseconds after the engine_receive tool was started. Optional. The default is that the first received batch of events is received at the number of milliseconds since engine_receive actually started. |
-C | --logChannels |
Specifies that you want engine_receive output to include the channel that an event arrives on. If you then use the engine_receive output as input to engine_send, events are delivered back to the same-named channels. See Event association with a channel. |
-r | --reconnect |
Automatically (re)connect to the server when available. |
-x | --qdisconnect |
Disconnect from the correlator if the engine_receive tool cannot keep up with the events from the correlator. |
-v | --verbose |
Requests verbose output during engine_receive execution. Optional. |
-u | --utf8 |
Indicates that received event files are in UTF-8 encoding. This specifies that the engine_receive tool should not convert the input to any other encoding. |
-V | --version |
Displays version information for the engine_receive tool. Optional. |
Exit status
The engine_receive tool returns the following exit values:
| Value | Description |
|---|---|
0 |
All events were received successfully. |
1 |
No connection to the correlator was possible or the connection failed. |
2 |
Other error(s) occurred while receiving events. |
Text encoding
The engine_receive tool translates all events it receives from UTF-8 into the current character locale. It is therefore important that you correctly set the machine’s locale. To force the engine_receive tool to output events in UTF-8 encoding, specify the -u option.