namtrace.tex

柯老师网站上找到的

variable with a single value. 
Notice that the value is simple treated as a string (without
white space).
Every feature is required to be associated with an agent. 
Then, it can be added or modified at any time after its agent is created.
The trace line to create a feature is:
\begin{verbatim}
f -t <time> -s <src> -a <agentname> -T <type> -n <varname> -v <value> -o <prev value>
\end{verbatim}
Flag {\tt <type>} is ``l'' for a list, ``v'' for a simple variable, ``s''
for a stopped timer, ``u'' for an up-counting timer, ``d'' for a
down-counting timer.
However, only ``v'' is implemented in \ns. 
Flag {\tt -v <value>} gives the new value of the variable. 
Variable values are simple ASCII strings obeying the TCL string
quoting conventions. 
List values obey the TCL list conventions. 
Timer values are ASCII numeric. 
Flag {\tt -o <prev value>} gives the previous value of the variable. 
This is used in backward animation. 
Here is an example of a simple feature event:
\begin{verbatim}
\code{f -t 0.00000000000000000 -s 1 -n C1_ -a srm(1) -v 2.25000 -T v}\\
\end{verbatim}

Features may be deleted using:
\begin{verbatim}
f -t <time> -a <agent name> -n <var name> -o <prev value> -X
\end{verbatim}

\subsection{Miscellaneous Trace Events}

There are other trace events in addition to the formats described above:
\begin{description}
\item[Annotation] This event is represented by event type ``v''. 
  It is used for generic annotation:
\begin{verbatim}
v -t <time> <TCL script string>  
\end{verbatim}
  Notice that this event is very generic, in that it may include an
  arbitrary tcl script to be executed at a given
  time, as long as it is in one line (no more than 256
  characters).
  There may be white spaces in the string.
  The order of flag and the string is important.

  Here is an example of this event:
\begin{verbatim}
v -t 4 sim_annotation 4 3 node 0 added one mark
\end{verbatim}
  This line calls a special tcl function {\tt sim\_annotation} in
  nam, which inserts the given string \code{node 0 added one mark}
  into nam's annotation pane.

\item[Color] Nam allows one to associate color names with
  integers. This is very useful in coloring packets, where flow id of
  a packet is used to color the packet using the corresponding color:
\begin{verbatim}
c -t <time> -i <color id> -n <color name>
\end{verbatim}
  Notice the color name should be one of the names
  listed in color database in X11 (/usr/X11/lib/rgb.txt). 

\item[Version]
  The following line define the nam version as required to visualize
  the given trace:
\begin{verbatim}
V -t <time> -v <version> -a <attr>
\end{verbatim}
  Normally there is only one version string in a given tracefile, and
  it is usually the first line of the file.

\item[Hierarchy] Hierarchical address information is defined by:

  \code{A -t <time> -n <levels> -o <address-space size> -c <mcastshift> -a <mcastmask> -h <nth level> -m <mask in nth level> -s <shift in nth level>}
  
  This trace gives the details of hierarchy, if hierarchical
  addressing is being used for simulation. 
  Flag {\tt -n <levels>}
  indicate the total number of hierarchical tiers, which is 1 for flat
  addressing, 2 for a 2-level hierarchy etc. 
  Flag {\tt -o <address space size>} 
  denotes the total number of bits used for addressing. 
  Flag {\tt -h <nth level>} specifies the level of the address
  hierarchy. 
  Flag {\tt -m <mask>} and {\tt -s <shift>} describes the address mask
  and the bit shift of a given level in the address hierarchy,
  respectively. 
  Here is an example of a trace for topology with 3 level hierachy:
\begin{verbatim}
A -t * -n 3 -p 0 -o 0xffffffff -c 31 -a 1
A -t * -h 1 -m 1023 -s 22
A -t * -h 2 -m 2047 -s 11
A -t * -h 3 -m 2047 -s 0 
\end{verbatim}
\end{description}

The functions that implement the different nam trace formats described
above may be found in the following files: \ns/trace.cc, 
\ns/trace.h, \ns/tcl/lib/ns-namsupp.tcl.

\section{Ns commands for creating and controlling nam animations}
\label{sec:namcommands}

This section describes different APIs in \ns that may be used to
manipulate nam animations for objects like nodes, links, queues and
agents. 
The implementation of most of these APIs is contained in
\ns/tcl/lib/ns-namsupp.tcl.
Demonstration of nam APIs may be found in \ns/tcl/ex/nam-example.tcl.

\subsection{Node}

Nodes are created from the ``n'' trace event in trace file. 
Each node represents a host or a router. 
Nam terminates if there are duplicate definitions of the same node.
Attributes specific to node are color, shape, label, label-color,
position of label and adding/deleting mark on the node.
Each node can have 3 shapes: circle (default), square, or hexagon.
But once created, the shape of a node cannot be changed during the
simulation.
Different node may have different colors, and its color may be changed
during animation. 
The following OTcl procedures are used to set node attributes, they
are methods of the class Node:

\begin{program}
$node color [color]      ;# sets color of node
$node shape [shape]      ;# sets shape of node
$node label [label]      ;# sets label on node
$node label-color [lcolor]  ;# sets color of label
$node label-at [ldirection] ;# sets position of label
$node add-mark [name] [color] [shape]   ;# adds a mark to node
$node delete-mark [name]    ;# deletes mark from node
\end{program} %$

\subsection{Link/Queue}

Links are created between nodes to form a network topology. 
\nam links
are internally simplex, but it is invisible to the users. The trace
event ``l'' creates two simplex links and other necessary setups, hence
it looks to users identical to a duplex link. Link may have many
colors and it can change its color during animation. Queues are
constructed in nam between two nodes. Unlike link, nam queue is
associated to a simplex link.  The trace event ``q'' only creates a
queue for a simplex link. In nam, queues are visualized as stacked
packets. Packets are stacked along a line, and the angle between the
line and the horizontal line can be specified in the trace event ``q''.
Commands to setup different animation attributes of a link are as
follows:

\code{$ns duplex-link-op <attribute> <value>} %$

The <attribute> may be one of the following: orient, color, queuePos.
Orient or the link orientation defines the angle between the link and
horizontal. The optional orientation values may be difined in
degrees or by text like right (0), right-up (45), right-down (-45), left
(180), left-up (135), left-down (-135), up (90), down (-90). The queuePos
or position of queue is defined as the angle of the queue line with
horizontal. 
Examples for each attribute are given as following : 
\begin{program}
$ns duplex-link-op orient right      ;# orientation is set as right. The order
                                     ;# in which links are created in nam
                                     ;# depends on calling order of this function.
$ns duplex-link-op color "green"
$ns duplex-link-op queuePos 0.5
\end{program} %$

\subsection{Agent and Features}

Agents are used to separate protocol states from nodes. They are always
associated with nodes. An agent has a name, which is a unique identifier
of the agent. It is shown as a square with its name inside, and a line
link the square to its associated node. The following are commands that
support agent tracing:
\begin{program}
$ns add-agent-trace <agent> <name> <optional:tracefile>
$ns delete-agent-trace <agent>
$ns monitor-agent-trace <agent>
\end{program} %$

Once the above command is used to create an agent in nam trace, the
{\tt tracevar} method of the \ns agent can be used to create feature
traces of a given variable in the agent. 
For example, the following code segment creates traces of the variable
{\tt C1\_} in an SRM agent {\tt \$srm(0)}:

\begin{program}
        $ns attach-agent $n($i) $srm(0)
        $ns add-agent-trace $srm($i) srm(0)
        $ns monitor-agent-trace $srm(0) ;# turn nam monitor on from the start
        $srm(0) tracevar C1_
\end{program}%$

\subsection{Some Generic Commands}

\code{$ns color <color-id>} %$
defines color index for nam. Once
specified, {\tt color-id} can be used in place of the color name in
nam traces.

\code{$ns trace-annotate <annotation>} %$
inserts an annotation in nam. Notice that if {\tt <annotation>} 
contains white spaces, it must be quoted using the double quote.
An example of this would be
\code{$ns at $time "$ns trace-annotate \"Event A happened\""} %$
This annotation appears in the nam window and is used to control
playing of nam by events.