Simulation Debugger (ODB)
The Simulation Debugger (ODB) is inherently part of the development Simulation Kernel and is automatically linked to each simulation. This gives you the flexibility of running simulations under ODB control at the spur of the moment without special preparation.
The purpose of ODB is to provide an environment for analyzing the execution of a program in which high-level abstractions (such as variable names, data structures, etc.) are maintained and accessible. Within the context of Modeler, the program being analyzed is a simulation and the high-level abstractions include objects (such as modules and submodules) and dynamic data entities (such as packets and events).
When executing a cosimulation, typically both ODB and the external simulator's debugging environment run in tandem. You can execute most ODB commands from the external simulation's environment and execute the other environment's commands from ODB.
ODB uses a text-based command interpreter that communicates via either the Simulation Console or standard input and output. In addition to a command line, common actions (such as stepping through events and setting breakpoints) are incorporated into the graphical debugging features of the advanced Simulation Execution dialog box.
The command interpreter accepts simple commands that control the execution of the simulation and the printing of information. Most commands take arguments; the arguments can indicate the target object of the command or parameters that affect the command.
ODB provides commands that let you:
- execute single events
- set breakpoints for specific events, times, modules, or processes, and continue execution between the breakpoints
- trace Kernel Procedures as they are being executed, and restrict tracing to selected modules, processes, packets, or groups of packets
- enable breakpoints or traces which have been defined by the invocation of special KPs in process models
- print out information about the current status of simulation entities, including static model objects (such as modules) and dynamic entities such as events, packets, and processes
- print out statistics on memory usage and detailed reports of memory allocation and deallocation
- affect the course of the simulation by modifying object attributes
ODB command formats and descriptions appear in "ODB Command Reference" on page 65.
Invoking ODB
To access the ODB interpreter, simulations are executed with the debug preference set to TRUE. Typically, debugging is enabled from the GUI via the Configure/Run DES dialog box before starting a simulation. Select the "Use Simulation Debugger (ODB)" checkbox on either the Common page or the Execution > OPNET Debugger page. When debugging from the GUI, you have access to all capabilities of ODB via the graphical debugger interface (see "Simulation Execution Dialog Box (Advanced)" on page 9).
Outside the GUI, the most common method of setting the debug preference is via a command line flag, as shown in Figure 7. Alternatively, the debug preference can be set to TRUE using a shell variable or an assignment in the preferences file. These alternative methods are less common, however, because they affect every simulation run while they are active. Another way of the setting the debug preference is via an assignment in an environment file; this supports the creation of debug and non-debug environment files for a simulation.
Figure 7: Invoking ODB from the Command Line
% op_runsim -net_name example -debug
<...simulation banner...>
_______________ Simulation Debugger _______________
Type 'help' for Command Summary
ODB>
In the example simulation shown in Figure 7, the simulation debugger was entered immediately: the "Simulation Debugger" banner and the ODB> command prompt were both displayed following the simulation banner. This might be the case in some simulations, but many simulations will print additional messages between the simulation banner and the ODB banner. Messages that are printed during the initialization phase of simulations have one of the following purposes:
- Signify the loading of simulation objects (if the preference verbose_load is set to TRUE)
- Query the user for the values of promoted object attributes, either from the command line in the shell window from which Modeler was launched or from a dialog prompt box in the GUI
The initial output of another simulation run, shown in Figure 8, includes messages before ODB is entered.
Figure 8: Debugging Example with Messages
% op_runsim -net_name pksw_net -debug
<...simulation banner...>
-------------------- Unset Environment Attribute ---------------------
* pksw1.node0.src.interarrival args: <arg. list>
* Desc:
* Press <return> to select default: 1.0
Enter value> 2.0
----------------------------------------------------------------------
-------------------- Unset Environment Attribute ---------------------
* pksw1.node1.src.interarrival args: <arg. list>
* Desc:
* Press <return> to select default: 1.0
Enter value> 1.0, 2.0
----------------------------------------------------------------------
_______________ Simulation Debugger _______________
Type 'help' for Command Summary
ODB>
ODB Concepts
There are several important concepts that form the basis of most ODB commands. These concepts, common to most symbolic debugging tools, include breakpoints, traces, maps, and diagnostic blocks. Each is described in the following topics, along with the ODB commands based on them.