Receiving events from correlators
The engine_receive tool lets you connect to a running event 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 bin directory of the Apama installation. Running the tool in the Apama Command Prompt ensures that the environment variables are set correctly.
Synopsis
To receive Apama-format events from an event correlator:
On Windows, run
engine_receive.exe.
On UNIX, run
engine_receive.
To obtain the following usage message, run the command without any options or with the –h option:
Usage: engine_receive [ options ]
To receive and log output events from a remote correlator.
Where options include:
-h | --help This message
-n | --hostname <host> Connect to an engine on <host>
-p | --port <port> Engine is listening on <port>
-c | --channel <channel> Listen on output channel <channel>
-f | --filename <file> Write to <file> instead of to standard out
-s | --suppressBatch Do not include BATCH timestamps in the output
| --suppressbatch
-z | --zeroAtFirstBatch Measure BATCH timestamps from when the first
| --zeroatfirstbatch batch arrived, instead of from when
engine_receive was started
-C | --logChannels Include channels in output
-r | --reconnect Automatically (re)connect to the server when available
-x | --qdisconnect Disconnect from correlator if we don't keep up
-v | --verbose Be more verbose
-u | --utf8 Write output in UTF8
-V | --version Print program version info
-Xconfig | --configFile <file> Use service configuration file <file>
Multiple -c options may be given
Description
The
engine_receive tool receives events from an event 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 information about event channels, see in Introduction to Apama.
To view progress information during engine_receive execution, specify the –v option.
You can also use engine_receive to receive events emitted by the Integration Adapter Framework (IAF) directly. To do this, specify the port of the IAF, by default this is 16903.
Options
The tool engine_receive.exe (on Windows) or engine_receive (on UNIX) takes a number of command line options. These are:
Option | Description |
-h | Displays usage information. Optional. |
-n host | Name of the host on which the event correlator is running. Optional. The default is localhost. Note: Non-ASCII characters in host names are not supported. |
-p port | Port on which the event correlator is listening. Optional. The default is 15903. |
-c 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. |
-C | 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. |
-f file | Dumps all received events in the specified file. Optional. The default is to write the events to stdout. |
-s | Omits BATCH timestamps from the output events. Optional. The default is to preserve BATCH timestamps in events. |
-z | 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. |
-r | Automatically (re)connect to the server when available |
-x | Disconnect from the correlator if the engine_receive utility cannot keep up with the events from the correlator. |
-v | Requests verbose output during engine_receive execution. Optional. |
-u | Indicates that received event files are in UTF-8 encoding. This specifies that the engine_receive utility should not convert the input to any other encoding. |
-V | Displays version information for the engine_receive tool. Optional. |
-Xconfig file | Specifies a special configuration file that the correlator uses to initialize its networking. Specify this option only as directed by Apama Technical Support to troubleshoot networking problems. For more information, see Using the Apama Component Extended Configuration File. |
Exit status
The engine_receive tool returns the following exit values:
Status | Description |
0 | All events were received successfully. |
1 | No connection to the event 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.