A Programming Essentials

This appendix covers the basic elements of the programming languages, which are essential for developing NS2 simulation programs. These include Tcl/OTcl which is the basic building block of NS2 and AWK which can be used for post simulation analysis.

A.1 Tcl Programming

Tcl is a general purpose scripting language. While it can do anything other languages could possibly do, its integration with other languages has proven even more powerful. Tcl runs on most of the platforms such as Unix, Windows, and Mac. The strength of Tcl is its simplicity. It is not necessary to declare a data type for variable prior to the usage. At runtime, Tcl interprets the codes line by line and converts the string into appropriate data type (e.g., integer) on the fly.

A.1.1 Program Invocation

Tcl can be invoked from a shell command prompt with the following syntax:

tclsh [ ...] where tclsh is mandatory. Other input arguments are optional. When the above command is invoked without input argument, the shell enters Tcl en- vironment where it waits for the Tcl statements line by line. If is specified, Tcl will interpret the text specified in the file whose name is line by line. In addition, if ... are specified, they will be placed in a list variable (see Section A.1.3) argv.Inthemain program, can be retrieved by executing “lindex $argv $i”. 390 A Programming Essentials

A.1.2 A Simple Example

To get a feeling about the language, we look at Example A.1 below:

Example A.1. The following Tcl script, “convert.tcl”, converts tempera- tures from Fahrenheit to Celsius. The conversion starts at 0 degree (Fahren- heit), proceeds with a step of 25 degrees (Fahrenheit), and stops when the temperature exceeds 140 degrees (Fahrenheit). The program prints out the converted temperature in Celsius as long as the temperature in Fahrenheit does not exceed 140 degrees.

# convert.tcl # Fahrenheit to Celsius Conversion 1 proc tempconv {} { 2 set lower 0 3 set upper 140 4 set step 25 5 set fahr $lower 6 while {fahr < $upper} { 7 set celsius [expr 5*($fahr - 32)/9] 8 puts "Fahrenheit / Celsius : $fahr / $celsius" 9 set fahr [expr $fahr + $step] 10 } 11 }

The details of the above example are as follows. The symbol # here denotes the beginning of a line comment. The reserved word proc in Line 1 declares a procedure tempconv{} which takes no input argument. The procedure also defines four local variables (i.e., lower, upper, step,andfahr) and assigns values to them using the reserved word set followed by the name and its as- signed value (Lines 2–5). Note here that, to refer to the value of a variable, the reserved character $ is used in front of the variable (e.g., set fahr $lower). The keyword expr in Line 9 informs the Tcl interpreter to interpret the fol- lowing string as a mathematical expression. The while loop in Lines 6–10 controls the iteration of the procedure through the test expression enclosed in a double quotation mark. The command puts in Line 8 prints out the string contained within the quotation mark. If the name of the script is convert.tcl, the script can be executed by typing the following on a shell prompt:

>>tclsh convert.tcl Fahrenheit / Celsius : 0 / -17.778 Fahrenheit / Celsius : 25 / -3.889 Fahrenheit / Celsius : 50 / 10 Fahrenheit / Celsius : 75 / 23.889 Fahrenheit / Celsius : 100 / 37.778 Fahrenheit / Celsius : 125 / 51.667 A.1 Tcl Programming 391

Alternatively, since NS2 is written in Tcl, the following invocation would lead to the same result. >>ns convert.tcl

A.1.3 Variables and Data Types

Data Types

As an interpreter, Tcl does not need to define data type of variables. Instead, it stores everything in string and interprets them based on the context.

Example A.2. Consider the following Tcl codes: # vars.tcl 1 set a "10+1" 2 set b "5" 3 set c $a$b 4 set d [expr $a$b] 5 puts $c 6 puts $d 7 unset c 8 puts $c After executing the Tcl script “vars.tcl”, the following result should appear on the screen:

>>tclsh vars.tcl 10+15 25

Here, variable c is simply a string “10+15”, whereas variable d is 25 ob- tained by numerically evaluating the string “10+15”storedinvariablec. Therefore, we may conclude that everything is treated as a string unless spec- ified otherwise [26].

Variable Assignment and Retrieval

Tcl stores a value in a variable using the reserved word “set”. The value stored in a variable can be retrieved by placing a character “$”infrontofa variable name. In addition, a reserved word “unset” is used to clear the value stored in a variable.

Example A.3. Insert the following two lines into the end of the codes in Example A.2. 7 unset c 8 puts $c 392 A Programming Essentials

After executing the Tcl script “vars.tcl”, the following result should appear on the screen:

>>tclsh vars.tcl 10+15 25 can’t read "c": no such variable while executing "puts c" (file "var.tcl" line 8)

Clearly after being unset,variablec stores nothing. Printing the variable would result in a runtime error.

Bracketing

There are four type of bracketing in Tcl. These are used to group a series of strings. Tcl interprets strings inside different types of bracket differently. Suppose a variable $var stores a value 10. Tcl interprets a statement “expr $var + 1” with four different bracketing differently. • Curly braces ({expr $var + 1}): Tcl interprets this statement as it is. • Quotation marks ("expr $var + 1"): Tcl interpolates the variable var in the string. This statement would be interpreted as “expr 10 + 1”. • Square brackets ([expr $var + 1]): Tcl regards a square bracket in the same way that C++ regards a parenthesis. It interprets the string in a square bracket before interpreting the entire line. This statement would be interpreted as “11”. • Parentheses ((expr $var + 1)): Tcl uses a parentheses for indexing an array and for invoking built-in mathematical function.

Example A.4. Insert the following two lines into the end of the codes in Example A.2. 7 puts -nonewline {{}: } 8 puts {expr $c} 9 puts -nonewline {"": } 10 puts "expr $c" 11 puts -nonewline {[]: } 12 puts [expr $c] After executing the Tcl script “vars.tcl”, the following result should appear on the screen:

>>tclsh vars.tcl 10+15 25 A.1 Tcl Programming 393

{}: expr $c "": expr 10+15 []: 25

When bracketing with “{}”, Tcl interprets the string as it is; The result in this case is “expr $c”. The string $c is replaced with its value when bracketing with “""”. The result in this case is “expr 10+15”. Finally, “[]”identifies the sequence of execution. The string “expr $c” is executed first. The result in this case is “25”.

Global Variables

In Example A.1, we briefly mentioned about local variables. But what was missing there is the notion of global variables. Global variables are common and used extensively throughout a program. These variables can be called upon by any procedure in the program. Example A.5 shows an example use of global variables.

Example A.5 (Global variables). set PI 3.1415926536 proc perimeter {radius} { global PI expr 2*$PI*$radius }

Since “PI” is defined outside of the procedure perimeter,thekeyword global is used here to make “PI” global and available within the procedure. When called upon, this procedure simply calculates the perimeter of a circle based on the supplied input radius. Finally, we note here that no default values are automatically assigned to variables. Any attempt to call an unini- tialized variable would lead to a runtime error.

Array

An array is a special variable which can be used to store a collection of items. An array stores both the indexes and the values as strings. For example, index “0” is not a number, but a numeric string. By default, an array in Tcl is an associative array. Example A.6 below shows various ways of string manipulation.

Example A.6 (Array assignment). # Numeric indexing set arr(0) 1 set arr(1) 3 set arr(1) 5 394 A Programming Essentials

# String indexing set wlan(datarate) 54000000 set wlan(protocol) "tcp"

Lists

A list is an ordered collection of elements such as numbers, strings or even lists themselves. The key list manipulations are shown below: • List creation: A list can be created in various ways as shown in Exam- ple A.7 below.

Example A.7. The following two statement are equivalent (i) set mylist "1 2 3" (ii) set mylist {123}

From the above, a list can be created in three ways. First, it can be created by the reserved word list which takes list members as input arguments. Alternatively, it can be created by embracing the members within a pair of curly braces or a pair of quotation marks. • Member retrieval: The following command returns the nth (= {0, 1, ···}) element in a list mylist: lindex $mylist $n • Member setting: The following command sets the value of the nth ele- ment in a list mylist to be : lset $mylist $n $value • Group retrieval: The following command returns a list whose members are the nth member through the mth member of a list mylist: lrange $mylist $n $m • Appending the list: The following command attaches a list alist to the end of a list mylist: lappend $mylist $alist

A.1.4 Input/Output

Tcl employs a so-called Tcl channel to receive an input using a command gets or to send an output using a command puts. A.1 Tcl Programming 395

Tcl Channels

A Tcl channel refers to an interface used to interact to the outside world. Two main types of Tcl channels include standard reading/writing channels and file channels. The former are classified into stdin for reading, stdout for writing, and stderr for error reporting. The latter needs to be attached to a file before it is usable. The syntax for attaching a file to a Tcl file channel is shown below:

open [] This command returns a Tcl channel attached to a file with the name . The optional input argument could be “r” for reading, “w” for writing to a new file, or “a” for appending an existing file. When a Tcl channel is no longer in use, it can be closed by using the command close whose syntax is as follows: close where is the Tcl channel which need to be closed.

The Commands gets and puts

The command puts and gets reads and writes, respectively, a message to a specified Tcl channel. In particular, the command “gets” reads a line from a Tcl channel, and passes every character in the line except the end-of-line char- acter to the Tcl running environment. The Tcl channel could be a standard channel or a file channel. The syntax of the command gets is as follows: gets Here, all the characters in the current line from the channel channel will be stored in the variable . The command “puts” writes a string followed by an end-of- line character to a Tcl channel .If is not specified, the stdout will be used as a default channel. The syntax of the command puts is as follows: puts [-nonewline] ][ where the nonewline option above specifies not to write an end-of-line char- acter to the end of the string. Normally, the command puts does not output immediately onto a Tcl channel. Instead, it puts the input argument (i.e., string) in its buffer, and releases the stored string either when the buffer is full or when the channel is closed. To force the immediate outputting, flush is used. Note that while a standard channel is opened and closed on the fly (i.e., upon an invocation of “puts), a file channel needs to be closed explicitly using the command close. 396 A Programming Essentials

Example A.8. Consider the following Tcl codes: puts "Press any key to continue..." gets stdin set ch_in [open "input.txt" "r}] set ch_out [open "output.txt" "a"] set line_no 0 while {[gets $ch_in line] >= 0} { puts $ch_out "[incr line_no] $line" } close $ch_in close $ch_out In this example, the content of file input.txt is copied to file output.txt line by line. In addition, the line number is prefixed at the beginning of each new line.

A.1.5 Mathematical Expressions

Tcl implements mathematical expressions through mathematical operators and mathematical functions. A mathematical expression of either type must be preceded by a reserved word “expr”. Otherwise, Tcl will recognize the operator as a character (see Lines 1 and 4 in Example A.2). A mathematical expression consists of an operator and operands. A list of most widely used operators is given in Table A.1. An operand can be either floating-point, octal or hexadecimal numbers. To be evaluated as octal and hexadecimal numbers, the numbers must be preceded by 0 and 0x, respectively. As another means to implement mathematical operations, mathematics functions can be placed after the reserved word “expr”. The built-in mathe- matical functions are shown below, where the input argument of a function is enclosed by parentheses.

Table A.1. Tcl mathematical operators. Operators Usage −+ ∼! Unary minus, unary plus, bit-wise negation, logical negation ∗ / % Multiplication, division, remainder +− Addition, subtraction > Bit shift left, right <>= Less than, greater than, less than or equal, greater than or equal & Bit-wise AND ∧ Bit-wise exclusive OR | Bit-wise OR && Logical AND || Logical exclusive OR x?y : z If x is non-zero, then y.Otherwise,z. A.1 Tcl Programming 397

abs(x) cosh(x) log(x) sqrt(x) acos(x) double(x) log10(x) srand(x) asin(x) exp(x) pow(x,y) tan(x) atan(x) floor(x) rand(x) tanh(x) atan2(x) fmod(x) round(x) wide(x) ceil(x) hypot(x,y) sin(x) cos(x) int(x) sinh(x) The detail of all the above functions is given in [27] Example A.9. Examples of invocation of mathematical functions log10(x) and abs(x) are shown below. >>tclsh >>expr log10(10) 1.0 >>expr abs(-10) 10 >>expr 1+2 3

A.1.6 Control Structure Tcl control structure defines how the program proceeds. This is carried out using the commands if/else/elseif, switch, for, while, foreach,and break/continue if/else/elseif An if/else/elseif command provides a program with a selective choice. A gen- eral form of this command is shown below: if {} { } elseif {} { } . . . else { } Here, the command first checks whether condition1 in the if statement is true. If so, it will take actions_1. Otherwise, it will check whether condition2 in the elseif statement is true. If so, it will take actions_2. If not, the process continues for every elseif statement. If nothing matches, actions_n defined under the else condition will be taken. 398 A Programming Essentials

switch

The switch command is a good substitute of a long series of a if/else/elseif command. It checks the value of a variable against given patterns, and takes actions associated with a matched pattern. The structure of a switch com- mand is shown below:

switch { { } { } . . . default { } } In this case action_i will be taken if matches with where i= { 1,2,...,n-1}. If none of the predefined patterns matches with the value,thedefault actions (i.e., actions_n) will be taken. while/for/foreach

The commands while, for,andforeach are used when actions need to be repeated for several times. The command while repeats actions until a pre- defined condition is no longer true. The command for repeats the actions for a given number of times. The command foreach repeats the actions for every item in a given list. The syntax of these three commands are as follows:

while {} { }

for {} {} {} { }

foreach {} {} { } A.1 Tcl Programming 399

The while command repeats the as long as the is true.Thefor command begins with an initialization statement init.After taking , it executes the Tcl statement and checks whether the is true. If so, it will repeat the .Otherwise,the command will terminate. The command foreach repeats for every member in the . In each repetition, the member is stored in variable and can be used for various purposes. break/continue

Commands break and continue are used in looping structures while, for, and foreach. They are used to prematurely stop the looping mechanism. Their key difference is that while the command break immediately exits the loop, the command continue simply restarts the loop. Example A.10.

set var 0 while {$var < 100} { puts $var set var [expr $var+5] if {$var == 20} break } puts $var

In this example, the loop continues as long as $var < 100. However, the command break terminates the looping mechanism if $var == 20. Therefore, the above program will print out 20. If the reserved word break is replaced with a reserved word continue, the loop will restart after being stopped. In this case the program will print out 100.

A.1.7 Procedures

A procedure is usually used in place of a series of Tcl statements to tidy up the program. The syntax of a procedure is shown below: proc { ... } { [return ] } The definition of a procedures begins with a reserved word proc. The pro- cedure name is placed after the word proc. The input arguments are placed within a curly braces, located immediately after the procedure name. Embrac- ing with a curly braces, the main body placed next to the input argument. 400 A Programming Essentials

Here, the actions for the procedures are defined. Optionally, the procedure may return a , using a reserved word return. After defining a procedure, one may invoke the procedure by executing the following statement: set var [ ] where var is set to the value returned from the procedure ,andthe values are fed as input arguments of the procedure.

A.2 Objected Oriented Tcl (OTcl) Programming

OTcl is an object-oriented version of Tcl, just like C++ is an object-oriented version of C [28]. The basic architecture and syntax in OTcl are much the same as those in Tcl. The difference, however, is the philosophy behind each of them. In OTcl, the concepts of classes and objects are of great importance. A class is a representation of a group of objects which share the same behavior(s) or trait(s). Such a behavior can be passed down to child classes. In this respect, the donor and the receiver of the behaviors are called a superclass (or a parent class) and a subclass (or a child class), respectively. Apart from inheriting behaviors from a parent class, a class defines its own functionalities to make itself more specific. This inheritance is the very main concept for any OOP including OTcl.

A.2.1 Class and Inheritance In OTcl, a class can be declared using the following syntax: Class [-superclass ] If the optional argument in the square bracket is present, OTcl will recognize class as a child class of class . Alternatively, if the option is absent, class can be also declared as a child class of class by executing superclass Note that, class inherits the functionalities (including proce- dures and variables) of class . In OTcl, the top-level class is class Object, which provides basic procedures and variables, from which every user-defined class inherits. Example A.11. Consider a general network node. When equipped with mo- bility, this node becomes a mobile node. Declaration of a class Node and its child class Mobile is shown below. This declaration allows class Mobile to inherit capabilities of class Node (e.g., receiving packets) and to include more capabilities (e.g., moving) to itself. A.2 Objected Oriented Tcl (OTcl) Programming 401

1 Class Node 2 Class Mobile -superclass Node

A.2.2 Class Member Procedures and Variables

A class can be associated with procedures and variables. In OTcl, a procedure and a variable associated with a class are referred to as instance procedure (i.e., instproc) and an instance variable (i.e., instvar), respectively.

Instance Procedures

The syntax which declaver an instproc is shown below:

instproc [{args}] { } where instproc “instproc” is defined in the top-level class Object. Here, the name of the instproc is . The detail (i.e., ) of the instproc is embraced within curly braces. The input arguments of the instproc are given in . Each input argument is separated by a white space. OTcl supports assignment of each input argument with a default value. That is, the input argument will be assigned with the default value if the value is not given at the invocation. Denote an input argument and its default value by and , respectively. The argument declaration is as follows: { def} For example, let an instproc has two input arguments: and . The first input argument is not given a default value. The default value for the second input argument is given by . To declare this instproc, we replace [args] above with “ {}”. Once declared, an instproc is usually invoke through an object (whose class is ) using the following syntax.