Deploying and Managing Apama Applications > Event Correlator Utilities Reference > Receiving events from correlators
Receiving events from correlators
The engine_receive tool lets you connect to a running event correlator and receive events from them. 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
 -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 channel, see Introduction to Apama Event Processing Language in Developing Apama Applications in EPL (available if you selected Developer during installation).
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. Note, however that engine_receive must either not specify a channel (i.e., listen to all channels), or specify the com.apama.input channel, which echoes back all Apama events sent to the IAF.
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.
-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.
Copyright © 2013 Software AG, Darmstadt, Germany and/or Software AG USA Inc., Reston, VA, USA, and/or Terracotta Inc., San Francisco, CA, USA, and/or Software AG (Canada) Inc., Cambridge, Ontario, Canada, and/or, Software AG (UK) Ltd., Derby, United Kingdom, and/or Software A.G. (Israel) Ltd., Or-Yehuda, Israel and/or their licensors.