Apama 10.15.1 | Deploying and Managing Apama Applications | Correlator Utilities Reference | Using the command-line debugger
 
Using the command-line debugger
 
Obtaining online help for the command-line debugger
Enabling and disabling debugging in the correlator
Working with breakpoints using the command-line debugger
Controlling execution with the command-line debugger
Command shortcuts for the command-line debugger
Examining the stack with the command-line debugger
Displaying variables with the command-line debugger
The engine_debug tool lets you control execution of EPL code in the correlator and inspect correlator state. This tool is a correlator client that runs a single command from the command line. It is not an interactive command-line debugger. The executable for this tool is located in the bin directory of the Apama installation.
In general, this tool is expected to be most useful when you are ready to deploy your application or after deployment. During development, the interactive debugger in Software AG Designer will probably be most useful to you.
Before you run the engine_debug tool, specify the -g option when you start the correlator. Specification of this option disables some correlator optimizations. If you run the engine_debug tool 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.
Synopsis
To debug applications on a running correlator, run the following command:
engine_debug [ [ global-options ] [command [options]] ... ]
To obtain a usage message, run the command with the help option.
Description
Debugging a running correlator has some effect on the other programs that connect to that correlator. While you pause a correlator, the expected behavior of connected components is as follows:
*Sending events to the correlator continues to put events on the input queue of each public context. However, since the input queues are not being drained, if an input queue fills up, this will block senders, including the engine_send tool and adapters.
*The correlator sends out any events on its output queue. When the output queue is empty, receivers no longer receive events; no contexts are sending events.
*Other inspections of the correlator proceed as normal. For example, engine_watch, engine_management, and profiling data.
*You can shut down the correlator.
*You can inject monitors while the correlator is stopped. They will not run any of the onload() or similar code until the correlator resumes, but the inject call should succeed.
*Java applications continue to run completely independently of whether the correlator is stopped.
*All other requests block until the correlator resumes processing. This includes dumping correlator state, loading, and changing debug or profiling state.
The engine_debug tool is stateless. Consequently, during debugging, you can have multiple concurrent connections to the same correlator.
Debug commands
The ordering of arguments to engine_debug commands works as follows:
*All arguments before the first command apply to all commands in that command line. This is useful for setting the host and port if you are not using the local defaults.
*All arguments following a command apply to only that command and they override any applicable arguments specified before the first command.
*The arguments to a particular command can be in any order
*When there are multiple commands in a line, the debugger executes them in the order in which they are specified. Execution continues until either all complete, or one fails, which prevents execution of any subsequent commands.
The engine_debug tool takes the following commands as options:
Abbreviation
Command
Description
h [command]
help [command]
Displays a usage message. To obtain help for a particular engine_debug command, specify that command.
p
status
Displays the current debugger state, and position if stopped.
ha
hashes
Lists injected files and their hashes.
si
stepinto
Steps into an action.
sot
stepout
Steps out of an action.
sov
stepover
Steps over an instruction.
r
run
Begins processing instructions.
b
stop
Stops processing instructions.
w [-to int]
wait [--timeout timeout]
Waits for the correlator to stop processing instructions. Specify an integer that indicates the number of seconds to wait. The debugger waits forever if you do not specify a timeout. See The wait command for more information.
s
stack [--context contextid] | [--frame frameid]
Displays current stack information for all contexts. The output includes the frame ID associated with each variable. To display stack information for only a particular context, specify the --context argument. To display stack information for only a particular frame, specify the --frame argument.
i
inspect
--instance monitorinstance |
--instance monitorinstance
--frame frameid |
--instance monitorinstance
--variable variablename |
--instance monitorinstance
--frame frameid
--variable variablename |
--frame frameid |
--frame frameid
--variable variablename
Displays the value of one or more variables. Specify a monitor instance and/or a frame ID and/or a variable name to display a list of variables in that monitor or in a particular monitor frame, or to display the value of a particular variable. Obtain monitor instance IDs from engine_inspect output or correlator log statements. Obtain frame IDs from engine_inspect stack output.
c
context [--context contextid]
Displays information about all contexts in the correlator or about only the context you specify. Information displayed includes context name, context ID, monitor instances in the context, and monitor instance IDs.
e
enable
Enables debugging. You must run this in order to do any debugging.
d
disable
Disables debugging. You must run this to disable debugging. If you do not disable debugging, the correlator runs more slowly and continues to stop when it hits breakpoints.
boe
breakonerror enable
Causes the debugger to pause if it encounters an error.
boeoff
breakonerror disable
Causes the debugger to continue processing if it encounters an error.
ba
breakpoint add
[--breakonce] --file filename
 --line linenumber |
[--breakonce] --owner ownername
--action actionname
--line linenumber
Adds a breakpoint at the beginning of the specified line. If you do not specify --breakonce, the correlator always pauses at this point when debugging is enabled. You must specify the line number where you want the breakpoint. As usual, this is the absolute offset from the beginning of the file. You must specify either the name of the file that contains the breakpoint or the owner and action name that contains the breakpoint. When the owner is a monitor instance, specify package_name.monitor_name or just monitor_name if there is no package.
bd
breakpoint delete
--file filename
--line linenumber |
--owner ownername
--action actionname
--line linenumber | 
--breakpoint breakpointid
Removes a breakpoint. Specify one of the following:
*File name and line number.
*Owner name, action name and line number. When the owner is a monitor instance, specify package_name.monitor_name or just monitor_name if there is no package.
*Breakpoint ID. You can obtain a breakpoint ID by executing the breakpoint list command.
bls
breakpoint list
For each breakpoint in the correlator, this displays the following:
*Breakpoint ID.
*Name of file that contains the breakpoint.
*Name of the action that contains the breakpoint.
*Name of the owner of the breakpoint.
*Number of the line that the breakpoint is on.
The breakpoint owner is the name of the monitor that contains the breakpoint or the name of the event type definition that contains the breakpoint. If the breakpoint is in an event type definition, the definition must specify an action and processing must create a closure between an event instance and an action call.
For information about closures, see Using action type variables.
Exit status
The engine_debug tool returns the following exit values:
Value
Description
0
Success. All requests were processed successfully.
1
Failure. The correlator could not parse the command line, or an exception occurred, such as losing a connection or trying to use a non-existent ID.