4.3 Other Methods

The Simulator class provides a number of methods used to set up the simulation. They generally fall into three categories: methods to create and manage the topology (which in turn consists of managing the nodesChapterchap:nodes and managing the linksChapterchap:links), methods to perform tracingChapterchap:trace, and helper functions to deal with the scheduler. The following is a list of the non-topology related simulator methods:

Simulator instproc now {} # return scheduler's notion of current time;
Simulator instproc at args # schedule execution of code at specified time;
Simulator instproc cancel args # cancel event;
Simulator instproc run args # start scheduler;
Simulator instproc halt {} # stop (pause) the scheduler;
Simulator instproc flush-trace {} # flush all trace object write buffers;
Simulator instproc create-trace { type files src dst } # create trace object;
Simulator instproc create_packetformat # set up the simulator's packet format;

\clearpage

\section{Commands at a glance}
\label{sec:simcommand}
\begin{flushleft}
Synopsis:
{\tt ns \\<otclfile\\> \\<arg\\> \\<arg\\>..}\\
Description:
Basic command to run a simulation script in ns.
The simulator (ns) is invoked  via the ns interpreter, an extension of the
vanilla otclsh command shell. A simulation is defined by a OTcl script
(file). Several examples of OTcl scripts can be found under \emph{ns}/tcl/ex
directory.


The following is a list of simulator commands commonly used in simulation
scripts:

{\tt set ns\_ [new Simulator]}\\
This command creates an instance of the simulator object.


{\tt set now [\$ns\_ now]}\\
The scheduler keeps track of time in a simulation. This returns scheduler's
notion of current time.


{\tt \$ns\_ halt}\\
This stops or pauses the scheduler.


{\tt \$ns\_ run}\\
This starts the scheduler.


{\tt \$ns\_ at \\<time\\> \\<event\\>}\\
This schedules an \<event\> (which is normally a piece of code) to be executed
at the specified \<time\>.
e.g $ns_ at $opt(stop) "puts \"NS EXITING..\" ; $ns_ halt"
or, $ns_ at 10.0 "$ftp start"


{\tt \$ns\_ cancel \\<event\\>}\\
Cancels the event. In effect, event is removed from scheduler's list of 
ready to run events.


{\tt \$ns\_ create-trace \\<type\\> \\<file\\> \\<src\\> \\<dst\\> \\<optional arg: op\\>}\\
This creates a trace-object of type \<type\> between \<src\> and \<dst\> objects
and attaches trace-object to \<file\> for writing trace-outputs. If op is defined
as "nam", this creates nam tracefiles; otherwise if op is not defined, ns
tracefiles are created on default.


{\tt \$ns\_  flush-trace}\\
Flushes all trace object write buffers.


{\tt \$ns\_ gen-map}\\
This dumps information like nodes, node components, links etc created for a
given simulation. This may be broken for some scenarios (like wireless).


{\tt \$ns\_ at-now \\<args\\>}\\
This is in effect like command "$ns_ at $now $args". Note that this function
may not work because of tcl's string number resolution.


These are additional simulator (internal) helper functions (normally used
for developing/changing the ns core code) :

{\tt \$ns\_ use-scheduler \\<type\\>}\\
Used to specify the type of scheduler to be used for simulation. The different
types of scheduler available are List, Calendar, Heap and RealTime. Currently
Calendar is used as default.


{\tt \$ns\_ after \\<delay\\> \\<event\\>}\\
Scheduling an \<event\> to be executed after the lapse of time \<delay\>.


{\tt \$ns\_ clearMemTrace}\\
Used for memory debugging purposes.


{\tt \$ns\_ is-started}\\
This returns true if simulator has started to run and false if not.


{\tt \$ns\_ dumpq}\\
Command for dumping events queued in scheduler while scheduler is halted.


{\tt \$ns\_ create\_packetformat}\\
This sets up simulator's packet format.

\end{flushleft}


Tom Henderson 2011-11-05