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