TCL/OTCL

NS and TCL linkage

Relationship between NS and TCL
The NS simulator is more like an extended TCL language interpreter:
- You can add new commands into the NS "language"
  These new commands can be:
  - new nodes (i.e., a new routing method)
  - new links (i.e., a new queueing method)
  - new agents (i.e., a new transport layer protocol)
- The new command is added as a C++ class

Illstrative Example: adding a simple class/command to NS

Here is a simple C++ class "MyAgent" that inherits from the NS class "Agent":

#include <stdio.h> #include <string.h> #include "agent.h" // New class is a subclass of Agent // This example will work as subclass // of any C++ class // *********************** // Class header // *********************** class MyAgent : public Agent { public: MyAgent(); // Constructor - binds variables protected: int command(int argc, const char*const* argv); private: int my_var1; // Variable 1 double my_var2; // Variable 2 void MyPrivFunc(void); void showvars(void); }; // *********************** // Class Body // *********************** /* --------------------------------------------------- Constructor: bind variables in C++ class to strings --------------------------------------------------- */ MyAgent::MyAgent() : Agent(PT_UDP) { bind("my_var1_otcl", &my_var1); bind("my_var2_otcl", &my_var2); } /* ------------------------------------------------------------ command: MAIN entry point from TCL call. When TCL executes a command: MyAgent-type-Object x y z Then, this "command" method is invoked with "x" "y" "z" as argv[] parameters to this "command" method !!! ------------------------------------------------------------ */ int MyAgent::command(int argc, const char*const* argv) { /* ----------------------------------------------------------- In this example, we tries to detect 2 possible commands for argv[1]: ----------------------------------------------------------- */ if (strcmp(argv[1], "call-my-priv-func") == 0) { MyPrivFunc(); // invoke the corresponding implementation return(TCL_OK); } else if (strcmp(argv[1], "showvars") == 0) { showvars(); // invoke the corresponding implementation return(TCL_OK); } /* ----------------------------------------------------------- If we arrived here, the command issued was not one of those implemented by MyAgent. But since MyAgent is an Agent, it inherits ALL agent commands. So let Agent handle it... ----------------------------------------------------------- */ return(Agent::command(argc, argv)); } /* ----------------------------------------------------------- MyPrivFunc(): shows how to invoke TCL commands within C++ ----------------------------------------------------------- */ void MyAgent::MyPrivFunc(void) { Tcl& tcl = Tcl::instance(); tcl.eval("puts \"Message From MyPrivFunc\""); tcl.evalf("puts \" my_var1 = %d\"", my_var1); tcl.evalf("puts \" my_var2 = %f\"", my_var2); } /* ----------------------------------------------------------- showvars(): shows an ordinary C++ function ----------------------------------------------------------- */ void MyAgent::showvars(void) { printf("** my_var1 = %d\n", my_var1); printf("** my_var2 = %lf\n", my_var2); }

How to use the new class in NS:

set myagent [new Agent/MyAgentOtcl]
To define (create) a new MyAgent object in TCL (NS):
NOTE: why "new Agent/MyAgentOtcl"? It will be revealed in the binding class soon

$myagent set my_var1_otcl 2 $myagent set my_var2_otcl 3.14
$myagent.my_var1_otcl := 2
$myagent.my_var2_otcl := 3.14

$myagent call-my-priv-func $myagent showvars
Invokes $myagent.call-my-priv-func
Invokes $myagent.showvars

The glue between C++ and TCL (NS)

Before the NS/Tcl script will work with the C++ program, there need to be a binding process executed at the start of the NS program (so NS has to be re-compiled to incorporate the new C++ class AND the binding mechanism)
Specifically, TCL must learn/know:
- how to recognize a TCL command that instructs TCL to create a "MyClass" object
- once it is instructed, what TCL must do to create a "MyClass" object
TCL learns this by executing a register function at the start of the NS program.

Example register (or binding) class:

/* --------------------------------------------- The TCL Binding class for "MyClass" --------------------------------------------- */ static class MyAgentClass : public TclClass { public: /* ----------------------------------------------------------- Constructor - defines the string "Agent/MyAgentOtcl" as a TCL class ----------------------------------------------------------- */ MyAgentClass() : TclClass("Agent/MyAgentOtcl") {} /* ----------------------------------------------------------- create(): method invoked when [new Agent/MyAgentOtcl] is invoked inside a TCL (NS) script ----------------------------------------------------------- */ TclObject* create(int, const char*const*) { return(new MyAgent()); } } class_my_agent; // This defines a STATIC variable of MyAgentClass // type which FORCES C++ to invoke the CONSTRUCTOR

Preparing to enhance NS: make a copy of NS for yourself
- Create a clean subdirectory to hold your new project (modifying NS)
- Get a copy of the following "duplicate" script into that new directory: click here
- The script assumes a number of things:
  - The version of NS: VERSION=ns-2.26
  - The source directory of NS: NS_SRC=/export/home/cheung/thesis/ns/ns-2.26
  - The destination directory: DEST=ns2
  You may have to edit the script when the version of NS change or the source directory is different
- After editing the "duplicate" script, run it inside the new directory
  It will create 2 subdirectories and 1 symbolic link:
  - ns2: contains a linked copy of the source (but files that are most likely need changing are copied)
  - prog: the working subdirectory where you put your new programs (classes that enhance the behavior of NS)
    Initially, it contains copies of a number of often modified header files and TCL scripts. These have been copied for your convenience. If you need to modify other files in the NS source, you need to following these instructions: click here
  - ns: a symbolic link to "ns2/ns-2.26" (or the lastest version) where the source of the NS simulator resides.
    This directory also contains the new version of the simulator (ns) when you add classes to NS
Modifying a file other than the most common ones
If you need to modify a NS source file other than those already linked into the NEWDIR/prog, do this:
- In window 1:
  Find the file in its proper directory - it will be a symbolic link to the NS source directory location.
  Let's call this file FOUND-File
- In window 2:
```
   cd NEWDIR/prog
   cp FOUND-File .   (you need to make a copy before you modify it)
   
```
- Delete FOUND-File
- In the same directory where FOUND-File resides, make a new symbolic link to the new copy in NEWDIR/prog:
```
   (do this inside directory of FOUND-File)

   ln -s NEWDIR/prog/FOUND-File . 
   (now FOUND-File points to the copy in NEWDIR/prog)
   
```
- You can now make changes to the NEWDIR/prog/FOUND-File copy without changing the NS source copy (in fact, you should not have permission to change the NS source tree !)

Adding a new C++ program file to NS

Put the new file in NEWDIR/prog, e.g.:
```
   NEWDIR/prog/ex-linkage.cc
   
```

Add a corresponding object path to the NS makefile, e.g.:

   1. Edit NEWDIR/ns/Makfile

   2. Look for the line "OBJ_CC ="

   3. Add the line:

	../../prog/ex-linkage.o \

Compiling NS to extending the NS system with new capabilities
- Just for illustration, we add the "MyClass" C++ class to NS
- Get the following C++ "ex-linkage.cc" that contains the "MyAgent" (object) and "MyAgentClass" (binding class) into the newly created "prog" directory: click here
- Edit the NS makefile:
```
   NEWDIR/ns/Makefile  (which points to NEWDIR/prog/Makefile)
 
```
  - Look for the line "OBJ_CC ="
  - Add
    ../../prog/ex-linkage.o \
    as part of the object files
- Change directory to:
  NEWDIR/ns
  and type "make" - it should compile and make a new "ns" in NEWDIR/ns
- Download this NS/TCL script that uses the new "MyAgent" class and put it in the "NEWDIR/prog" directory: click here
- If you invoke the OLD NS simulator on "ex-linkage.tcl", you will get an error:
  cd NEWDIR/prog /home/cheung/thesis/ns/ns/bin/ns ex-linkage.tcl invalid command name "Agent/MyAgentOtcl" ...
- If you invoke the new NS simulator on the "ex-linkage.tcl", you will get this:
  cd NEWDIR/prog ../ns/ns ex-linkage.tcl warning: no class variable Agent/MyAgentOtcl::my_var1_otcl see tcl-object.tcl in tclcl for info about this warning. warning: no class variable Agent/MyAgentOtcl::my_var2_otcl Message From MyPrivFunc my_var1 = 2 my_var2 = 3.140000 ** my_var1 = 2 ** my_var2 = 3.140000
- It worked, but has some warning messages.
  This warning messages are caused by the fact that the instance variables have not been initialized.
  The warning also gave you a hint on how to fix it: edit ns-default.tcl to initialize the instance variables in order to get rid of the warning message.
  Edit:
```
     NEWDIR/ns2/ns-2.26/tcl/lib/ns-default.tcl 
	(points to prog/ns-default.tcl)
  
```
  and add the lines:
  Agent/MyAgentOtcl set my_var1_otcl 0 Agent/MyAgentOtcl set my_var2_otcl 0
  at the end of this file
- Change directory to:
  cd NEWDIR/ns touch ../../prog/ex-linkage.cc make
  
  This should make a new NS that includes the initialization commands for Agent/MyAgentOtcl
- Now, if you invoke this brand new NS simulator on the "ex-linkage.tcl", you will get:
  cd NEWDIR/prog ../ns/ns ex-linkage.tcl Message From MyPrivFunc my_var1 = 2 my_var2 = 3.140000 ** my_var1 = 2 ** my_var2 = 3.140000

set myagent [new Agent/MyAgentOtcl]	To define (create) a new MyAgent object in TCL (NS): NOTE: why "new Agent/MyAgentOtcl"? It will be revealed in the binding class soon
$myagent set my_var1_otcl 2 $myagent set my_var2_otcl 3.14	$myagent.my_var1_otcl := 2 $myagent.my_var2_otcl := 3.14
$myagent call-my-priv-func $myagent showvars	Invokes $myagent.call-my-priv-func Invokes $myagent.showvars