Deploying and Managing Apama Applications > Event Correlator Utilities Reference > Starting the event correlator
Starting the event correlator
This topic provides information about starting the event correlator. 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.
This topic is organized as follows:
*Synopsis
*Description
*Options
*Exit status
*Logging correlator status
*Text internationalization issues
*About the low latency and high throughput options
*Determining whether to disconnect slow receivers
*Determining whether to disable the correlator’s internal clock
Synopsis
To start the event correlator:
*On Windows, run correlator.exe.
*On UNIX, run correlator.
To obtain the following usage message, run the command without any options or with the –h option:

Usage: correlator [ options ]
Where options include:
-V | --version Print version info and exit
-h | --help This message
-p | --port <port> Listening on <port>
-f | --logfile <file> Correlator status log file name is <file>
-v | --loglevel <level> Log level is <level>
-t | --truncate Truncate log file at startup
-I | --logicalID <id> Component logical ID is <id>
-N | --name <name> Component name is <name>
-l | --license <file> License filename is <file>
-m | --maxoutstandingack <num> Buffer up to <num> secs of events/receiver
-M | --maxoutstandingkb <num> Buffer up to <num> kb of events/receiver
-x | --qdisconnect Disconnect slow event consumers
--lowLatency Tune output algorithm for low latency
--highThroughput Tune output algorithm for high throughput
--logQueueSizePeriod <p> Send info to log every <p> seconds
--jmsConfig <dir> Enable JMS messaging using configuration
files in <dir>
--distMemStoreConfig <dir> Enable Distributed MemoryStore using
configuration files in <dir>
-j | --java Enable Java application support
-J | --javaopt <option> Option to pass to JVM
--replayLog <file> Replay log file name is <file>
--inputLog <file> Input log file name is <file>
(can only specify replay or input log)
-XsetRandomSeed <num> Set the seed of correlator random number
generator to <num>
-XignoreEnqueue Ignore all enqueue statements (for replay)
--replayMode Replay IDs from a replay log (implies
-XignoreEnqueue)
--inputQueueSize <num> Set the capacity of the input queue
-g | --nooptimize Disable optimizations
-P Enable persistence
-PsnapshotInterval=<interval> The persistent correlator snapshot interval
-PstoreLocation=<path> The path where the persistent correlator
stores its recovery datastore
-PadjustSnapshot=<true/false> Automatically adjust the snapshot interval
-PstoreName=<file> The name of the recovery datastore file
-Pclear Clear contents of recovery datastore if
one exists
-XrecoveryTime <num> The time used after the recovery(seconds
since the epoch)
-noDatabaseInReplayLog Disallow database dumps to Replay/Input log
-Xclock | --externalClock Use external clocking (&TIME events)
-Xconfig | --configFile <file> Use service configuration file <file>

The loglevel argument must be one of:
OFF, CRIT, FATAL, ERROR, WARN, INFO, DEBUG, TRACE

Note: Without specification of a license file, the correlator runs for
30 minutes and accepts only local clients.
Description
By default, the correlator.exe (on Windows) or correlator (on UNIX) tool starts an event correlator process on the current host, and configures it to listen on port 15903 for monitoring and management requests.
On start-up, the executable displays the current version number and configuration settings.
To terminate an event correlator process, press Ctrl-C in the window in which it was started. Alternatively, you can issue the engine_management command with the --shutdown option. See Shutting down and managing components. Regardless of which technique you use to terminate the correlator, Apama first tries to shut down the correlator cleanly. If this is not possible, for example, perhaps because of a monitor in an infinite loop, Apama forces the correlator to shut down.
Options
When you start the correlator, there are a number of options that you can specify.
The following table describes the options you can specify when you start the correlator.
Option
Description
-V | --version
Displays version information for the correlator.
-h | --help
Displays usage information.
-p port | --port port
Specifies the port on which the event correlator should listen for monitoring and management requests. The default is 15903.
-f file | --logfile file
Specifies the path of the status log file that the event correlator writes messages to. The default is stdout. See Logging correlator status.
-v level | --loglevel level
Specifies the level of information that the event correlator sends to the correlator status log file. In increasing amount of information order, the value must be one of the following: OFF, CRIT, FATAL, ERROR, WARN, INFO, DEBUG, TRACE. The default is INFO.
-t | --truncate
Specifies that if the correlator status log file already exists, the correlator should empty it first. The default is to append to it.
-I id | --logicalID id
Assigns a logical Id to the correlator. The logical Id must be an integer. The default is the value of the physical ID, which is a 19-digit integer. The correlator’s messaging system generates the physical Id and ensures that it is unique in the scope of your network.
-N name | --name name
Assigns a name to the correlator. The default is correlator. If you are running a lot of correlators you might find it useful to assign a name to each correlator. A name can make it easier to use the engine_management tool to manage correlators and adapters.
-l file | --license file
Specifies the path to the file that contains the license string. If a license file is not specified, the correlator will start, but in a restricted mode that prevents connections to other hosts and it will terminate after 30 minutes of operation. If the license file exists but is expired or invalid then the correlator will fail to start.
-m num | --maxoutstandingack num
Specifies that you want the correlator to buffer messages for up to num seconds for each receiver that the correlator sends events to. The default is 10. For additional information, see Determining whether to disconnect slow receivers.
-M num | --maxoutstandingkb num
Specifies that you want the correlator to buffer the events for each receiver up to the size in kb represented by num.
-x | --qdisconnect
Specifies that you want the correlator to disconnect receivers that are consuming events too slowly. For details, see Determining whether to disconnect slow receivers. The default is that the correlator does not disconnect slow receivers.
--lowLatency
Indicates that the correlator transport waits until an event is on the correlator’s output queue. The transport then sends to receivers, in one batch, as many events as are available on the output queue. Because of thread scheduling effects, this can be more than the event that woke up the transport. This is the default behavior for multiprocessor machines. For additional information, see About the low latency and high throughput options.
--highThroughput
Indicates that the correlator transport waits 10 milliseconds before it tries to send any events to receivers. Typically, during that time, the correlator emits enough events to its output queue to form an efficient batch. This is the default behavior for uniprocessor machines. For additional information, see About the low latency and high throughput options.
--logQueueSizePeriod p
Sets the interval at which the correlator sends information to its log file. The default is 5 seconds. Replace p with a float value for the period you want.CAUTION: Setting logQueueSizePeriod to 0 turns logging off. Without correlator logging information, it is impossible to effectively troubleshoot problems.
--jmsConfig dir
Specifies that the correlator-integrated JMS messaging is enabled using the configuration files in the specified directory. Note that the configuration filenames must end with *-spring.xml and the correlator will not start unless the specified directory contains at least one configuration file. For more information on the configuration files for JMS messaging, see Configuration files.
--distMemStoreConfig dir
Specifies that the distributed MemoryStore is enabled, using the configuration files in the specified directory. Note that the configuration filenames must end with *-spring.xml and the correlator will not start unless the specified directory contains at least one configuration file. For more information on a distributed MemoryStore's configuration files, see "Using the Distributed MemoryStore" in Developing Apama Applications in EPL.
-j | --java
Enables support for Java applications. If you do not specify this option, any attempt to inject a Java application using engine_inject –j results in an error.
-J option | --javopt option
Specifies an option or property that you want the correlator to pass to the embedded JVM. You must specify the -J option for each JVM option. You can specify the -J option multiple times in the same correlator.exe command line. For example, -J "-Da=value1" -J "-Db=value2" -J "-Xmx400m"
You cannot use this mechanism to pass the classpath to the JVM. The correlator sets the classpath implicitly as the last option, which overrides any value you might have set. Set the CLASSPATH environment variable if you want to set a particular classpath.
--replayLog file
Specifies the path of the replay log file. The event correlator writes incoming messages to the replay log. If there is a problem with your application, Software AG Global Support can use the replay log to diagnose it. See Using a replay log to diagnose problems. A full replay log lets you replay the exact same behavior, ordering of emit operations, and so on, as the run that generated the replay log.
--inputLog file
Specifies the path of the input log file. The event correlator writes only input messages to the input log file. If there is a problem with your application, Software AG Global Support can use the input log to diagnose it. See Using a replay log to diagnose problems. An input-only replay log contains only the external inputs to the correlator. There is no information about multi-context ordering. Consequently, if there is more than one context, there is no guarantee that you can replay execution in the same order as the original execution.
--frequency hz
Instructs the correlator to generate clock ticks at a frequency of hz per second. Defaults to 10, which means there is a clock tick every 0.1 seconds. Be aware that there is no value in increasing hz above the rate at which your operating system can generate its own clock ticks internally. On UNIX and some Windows machines this is 100 Hz and on other Windows machines it is64 Hz.
-XsetRandomSeed int
Starts the correlator with the random seed value you specify. Specify an integer whose value is in the range of 1 to 2 32.The correlator uses the random seed to calculate the random numbers returned by the integer.rand() and float.rand() functions. The same random seed returns the same sequence of random numbers. This option is useful when your application uses the integer.rand() and float.rand() functions and you are capturing correlator behavior in a replay log. If you need to reproduce correlator behavior from that replay log, you will want the correlator to generate the same random numbers as it generated when the original behavior was captured.
-XignoreEnqueue
Instructs the correlator to ignore the output of enqueue statements. This is required when Reproducing correlator behavior from a replay log.
--replayMode
Enables replay of correlator behavior previously captured in a replay log. Always specify the --replayMode option when you start a correlator that will be reproducing behavior captured in a replay log. Specify this option in addition to the other options described in .
--inputQueueSize int
Sets the maximum number of spaces in every context’s input queue. The default is that each input queue has 20,000 spaces. If events are arriving on an input queue faster than the correlator can process them the input queue can fill up. You can set the inputQueueSize option to allow all input queues to accept more events. Typically, the default input queue size is enough so if you find that you need to increase the size of the input queue you should try to understand why the correlator cannot process the events fast enough to leave room on the default-sized queue. If you notice that adapters or applications are blocking it might be because a public context’s input queue is full. To determine if a public context's input queue is full, use output from the engine_inspect utility in conjunction with the status messages in the correlator log file.
-g | --nooptimize
Disables some correlator optimizations. Specify this option when you plan to run the engine_debug utility. If you run the engine_debug utility and you did not specify the -g option when you started the correlator, the optimizations hinder the debugging process. For example, the correlator might simultaneously execute multiple statements over multiple lines even if you are using debugger commands to step through the program line by line. When you use Apama Studio, it automatically uses the -g option when it starts a correlator from a debug launch configuration.
-P
Enables correlator persistence. You must specify this option to enable correlator persistence. If you do not specify any other correlator persistence options, the correlator uses the default persistence behavior as described in "Enabling correlator persistence" in Developing Apama Applications in EPL (available if you selected Developer during installation). If you specify one or more additional correlator persistence options, the correlator uses the settings you specify for those options and uses the defaults for the other persistence options.
-PsnapshotInterval=interval
Specifies the period between persistence snapshots. The default is 200 milliseconds.
-PstoreLocation=path
Specifies the path for the directory in which the correlator stores persistent state. The default is the current directory, which is the directory in which the correlator was started.
-PadjustSnapshot=boolean
Indicates whether or not the correlator should automatically adjust the snapshot interval according to application behavior. The default is true, which means that the correlator does automatically adjust the snapshot interval. You might want to set this to false to diagnose a problem or test a new feature.
-PstoreName=filename
Specifies the name of the file that contains the persistent state. This is the recovery datastore. The default is persistence.db.
-Pclear
Specifies that you want to clear the contents of the recovery datastore. This option applies to the recovery datastore you specify for the -PstoreName option or to the default persistence.db file if you do not specify the -PstoreName option. When the correlator starts it does not recover from the specified recovery datastore.
-XrecoveryTime num
For correlators that use an external clock, this is a time expression that represents the time of day that a correlator starts at when it recovers persistent state and restarts processing. The default is the time expression that represents the time of day captured in the last committed snapshot. This option is useful only for replaying replay logs that contain recovery information. To change the default, specify a number that indicates seconds since the epoch.
-noDatabaseInReplayLog
Specifies that the correlator should not copy the recovery datastore to the replay/input log when it restarts a persistence-enabled correlator. The default is that the correlator does copy the recovery datastore to the replay/input log upon restarting a persistence-enabled correlator. You might set this option if you are using an input log as a record of what the correlator received. The recovery datastore is a large overhead that you probably do not need. Or, if you maintain an independent copy of the recovery datastore, you probably do not want a copy of it in the replay log.
-Xclock |--externalClock
Instructs the correlator to disable its internal clock. By default, the correlator uses internally generated clock ticks to assign a timestamp to each incoming event. When you specify the -Xclock option, you must send time events (&TIME) to the correlator. These time events set the correlator’s clock. For additional information, see Determining whether to disable the correlator’s internal clock.
-Xconfig file | --configFile 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.
--runtime mode
On Linux 64-bit systems, you can specify whether you want the correlator to use the compiled runtime or the interpreted runtime, which is the default. Specify --runtime compiled or --runtime interpreted.
The interpreted runtime compiles EPL into bytecode whereas the compiled runtime compiles EPL into native code that is directly executed by the CPU. For many applications, the compiled runtime provides significantly faster performance than the interpreted runtime. Applications that perform dense numerical calculations are most likely to have the greatest performance improvement when the correlator uses the compiled runtime. Applications that spend most of their time managing listeners and searching for matches among listeners typically show a smaller performance improvement.
Other than performance, the behavior of the two runtimes is the same except
*The interpreted runtime allows for the profiler and debugger to be switched on during the execution of EPL. The compiled runtime does not permit this. For example, you cannot switch on the profiler or debugger in the middle of a loop.
*The amount of stack space available is different for the two runtimes. This means that recursive functions run out of stack space at a different level of recursion on the two runtimes.
Exit status
The correlator.exe tool returns the following exit values:
Exit values for correlator.exe
Value
Description
0
The event correlator terminated successfully.
1
An error occurred which caused the event correlator to terminate abnormally.
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.