Deploying and Managing Apama Applications > Correlator Utilities Reference > Shutting down and managing components
Shutting down and managing components
All Apama components (the correlator, the IAF, and the Sentinel Agent) implement an interface with which they can be asked to shut themselves down, provide their process ID, and respond to communication checks. Running the tool in the Apama Command Prompt (see Setting up the environment using the Apama Command Prompt) ensures that the environment variables are set correctly.
For historical reasons, there are three commands that all do the same thing. You can enter any of these commands to manage any component:
engine_management
component_management
iaf_management
However, the recommendation is to always use engine_management. The only differences in behavior among these commands is as follows:
*engine_management and component_management default to the local correlator port (15903).
*iaf_management defaults to the default IAF port (16903).
Synopsis
To use the event correlator’s management tool:
*On Windows, run engine_management.exe.
*On UNIX, run engine_management.
When you specify the –h command line option, the tool displays the following usage information:
Usage: engine_management [ options ]

Where options include:
-V | --version Print program version info
-h | --help Display this message
-v | --verbose Be more verbose
-n | --hostname <host> Connect to a component on <host>
-p | --port <port> Component is listening on <port>
-w | --wait Wait forever for component to start
-W | --waitFor <num> Wait <num> seconds for component to start
-N | --getname Get the name of the component
-T | --gettype Get the type of the component
-Y | --getphysical Get the physical ID of the component
-L | --getlogical Get the logical ID of the component
-O | --getloglevel Get the log level of the component
-C | --getversion Get the version of the component
-R | --getproduct Get the product version of the component
-B | --getbuild Get the build number of the component
-F | --getplatform Get the build platform of the component
-P | --getpid Get the process ID of the component
-H | --gethostname Get the hostname of the component
-U | --getusername Get the username of the component
-D | --getdirectory Get the working (current) directory of the component
-E | --getport Get the port of the component
-c | --getconnections Get all the connections to the component
-a | --getall Get all of the above values
-xs| --disconnectsender <id:id> <reason> Disconnect sender with id tuple <id:id>
-xr| --disconnectreceiver <id:id> <reason> Disconnect receiver with id tuple <id:id>
-I | --getinfo <category> Get component-specific info for <category>
Use empty string to get all available categories
Multiple -I options may be specified
-d | --deepping Deep-ping the component
-l | --setloglevel <level> Set logging verbosity to <level>. Available levels
are TRACE, DEBUG, INFO, WARN, ERROR, FATAL, CRIT and OFF
-r | --dorequest <type> <arg>* Send component-specific request
-s | --shutdown <why> Shutdown the component with reason <why>
Description
Use the engine_management tool to connect to a running component. Once connected, the tool can shut down the component or return information about the component. The engine_management tool can connect to any of the following types of components. The engine_management tool sends output to stdout.
*Event correlator
*Adapter
*Sentinel Agent process
Options
When you run the engine_management tool, you can specify any of the options described in the following table. By default, the engine_management tool connects to a local correlator that is listening on port 15903 (the correlator default port). To obtain all information for a particular component, specify the -a option. All options are optional:
Option
Description
-V
Displays version information for the engine_management tool.
-h
Display usage information.
-v
Displays information in a more verbose manner. For example, when you specify the -v option, the engine_management tool displays status messages that indicate that it is trying to connect to the component, has connected to the component, is disconnecting, is disconnected, and so on. If you are having trouble obtaining the information you want, specify the -v option to help determine where the problem is.
-n host
Name of the host on which the component is running (default is localhost). Non-ASCII characters are not allowed in host names.
-p port
Port on which the component you want to connect to is listening. The default is 15903.
-w
Instructs the engine_management tool to wait for the component to start and be in a state that is ready to receive EPL files. This option is similar to the -W option, except that this option (the -w option) instructs the tool to wait forever. The -W option lets you specify how many seconds to wait. See the information for the -W option for an example.
-W num
Instructs the engine_management tool to wait num seconds for the component to start and be in a state that is ready to receive EPL files. If the component is not ready to receive EPL files before the specified number of seconds has elapsed, the engine_management tool terminates with an exit code of 1.
This option is most useful in scripts, when the component you want to operate on has not yet started. For example, suppose a script specifies the following commands:
correlator.exe options engine_inject some_EPL_files
It can sometimes take a few seconds for a component to start, and this number of seconds is not always exactly predictable. If the engine_inject tool runs before the correlator is ready to receive EPL files, the engine_inject tool fails. To avoid this for a local correlator that is listening on the default port, insert the following command between these commands:
engine_management -W 10
This lets the engine_management tool wait for up to 10 seconds for the correlator’s management interface to be available. To set an appropriate wait time for your application, monitor your application’s performance and adjust as needed.
-N
Displays the name of the component. For example, when you start a correlator, you can give it a name with the -N option. This is the name that the engine_management tool returns. If you do not assign a name to a correlator when you start it, the default name is correlator.
-T
Displays the type of the component that the engine_management tool connects to. The returned value is one of the following: correlator, iaf, sentinel_agent. If you see that a port is in use, you can specify this option to determine the type of component that is using that port.
-Y
Displays the physical ID of the component. This can be useful if you are looking at status log information that identifies components by their physical IDs.
-L
Displays the logical ID of the component. This can be useful if you are looking at status log information that identifies components by their logical IDs.
-O
Displays the log level of the component. The returned value is one of the following: TRACE, DEBUG, INFO, WARN, ERROR, CRIT, FATAL, or OFF.
-C
Displays the version of the component. For example, when the tool connects to a correlator, it displays the version of the correlator software that is running.
-R
Displays the product version of the component. For example, when the tool connects to a correlator, it displays the version of the UNIX software that is running.
-B
Displays the build number of the component. This information is helpful if you need technical support. It indicates the exact software contained by the component you connected to.
-F
Displays the build platform of the component. This information is helpful if you need technical support. It indicates the set of libraries required by the component you connected to.
-P
Displays the process ID of the correlator you are connecting to. This can be useful if you are looking at log information that identifies components by their process ID.
-H
Displays the host name of the component. When debugging connectivity issues, this option is helpful for obtaining the host name of a component that is running behind a proxy or on a multihomed system.
-U
Displays the user name of the component. On a multiuser machine, this is useful for determining who owns a component.
-D
Displays the working (current) directory of the component. This can be helpful if a plug-in writes a file in a component’s working directory.
-E
Displays the port of the component.
-c
This option is for use by technical support. It displays all the connections to the component.
-a
Displays all information for the component.
-xs
Disconnects the sender that has the physical ID you specify. If you specify a reason, the engine_management tool sends the reason to the correlator. The correlator then logs the message, sends the reason to the sender, and disconnects the sender. You can specify the component ID as physical_ID/logical_ID.
-xr
Disconnects the receiver that has the physical ID you specify. If you specify a reason, the engine_management tool sends the reason to the correlator. The correlator then logs the message, sends the reason to the receiver, and disconnects the receiver. You can specify the component ID as physical_ID/logical_ID.
-I category
This option is for use by technical support. It displays component-specific information for the specified category.
-d
Ping the component. This confirms that the component process is running and acknowledging communications.
-l level
Sets the amount of information that the component logs. In order of decreasing verbosity, you can specify TRACE, DEBUG, INFO, WARN, ERROR, FATAL, CRIT, or OFF.
-r
This option sends a component-specific request. For example: engine_management -r profiling frequency
This returns the profiling frequency in Hertz.
The following request types are available:
*applicationEventLogging — Sends detailed application information to the correlator log file. See Viewing garbage collection information.
*flushAllQueues — Sends a request into the correlator that waits until every event/injection sent or enqueued to a context before the flushAllQueues request started has been processed, and every event emitted as a result of those events has been acknowledged. This may block if a slow receiver is connected to the correlator. Events enqueued to a context after the request has started may or may not be processed — thus if you want to see the results of one context enqueueing to a second, which enqueues to a third, you should execute engine_management -r flushAllQueues three times, to ensure it has been processed by each context. This does not change the behavior of the correlator (the correlator will always flush all queues as soon as it is able to), it just waits for events currently on input queues to complete.
*profiling — Lets you profile Apama EPL applications. See Using the profiler command-line interface.
*rotateLogs — For details on this request, see Rotating all log files.
*setApplicationLogFile — A set of commands lets you set, get, and unset the log files for packages and monitors. See Setting logging attributes for packages, monitors and events.
*setApplicationLogLevel — A set of commands lets you set, get, and unset logging levels for packages and monitors. See Setting logging attributes for packages, monitors and events.
*setLogFile — Instructs the component to close the log file it is using and open a new log file with the name you specify. See Rotating specified log files.
*verbosegc — Enables logging of garbage collection events. See Viewing garbage collection information.
Certain other requests for this option are available for use by Apama technical support.
-s why
Instructs the component to shut down and specifies a message that indicates the reason for termination. The component inserts the string you specify in its status log file with a CRIT flag, and then shuts down.
Exit status
The following exit values are returned:
Status
Description
0
All status requests were processed successfully.
1
Indicates one of the following:
*No connection to the specified component was possible.
*The connection failed.
*You specified the waitFor option and the specified time elapsed without the component starting.
2
One or more errors occurred while requesting/processing status.
3
Deep ping failed.
Copyright © 2013-2015 Software AG, Darmstadt, Germany and/or Software AG USA Inc., Reston, VA, USA, and/or its subsidiaries and/or its affiliates and/or their licensors.
Use, reproduction, transfer, publication or disclosure is prohibited except as specifically provided for in your License Agreement with Software AG.