Version 3.

1 Users Manual

2000, 2001 by Scalable Network Technologies, Inc.

This is copyrighted material and cannot be reproduced or distributed without permission from SNT, Inc.

Scalable Network Technologies, Inc.

11022 Santa Monica Blvd., Suite 260 Los Angeles, California, 90025

Table of Contents
1. Overview of QualNet.................................................................................................. 8 1.1. QualNet Features ................................................................................................ 8 1.2. Chapter Outline................................................................................................... 9 1.3. How To Install QualNet.................................................................................... 10 1.4. Windows NT 4.0/2000 Notes ..................................................................... 11 1.5. Solaris Notes ................................................................................................. 11 1.6. Linux Notes....................................................................................................... 11 2. Command-Line Execution and File-Based Specification......................................... 12 2.1. Directory Structure of QualNet......................................................................... 13 2.2. Command-Line Compilation and Execution .................................................... 14 2.3. Scenario Input File Syntax................................................................................ 15 2.3.1. Configuration File Converter.................................................................... 15 2.3.2. Comments ................................................................................................. 17 2.3.3. QualNet Time Format ............................................................................... 17 2.3.4. QualNet Coordinate Format...................................................................... 18 2.3.5. Identifying Nodes and Networks .............................................................. 18 2.3.5.1. Node Identifiers .................................................................................... 19 2.3.5.2. IP Addresses and Subnets ..................................................................... 19 2.3.6. Specifying Nodes and Networks............................................................... 20 2.3.6.1. QualNet Subnet Shorthand ................................................................... 21 2.3.6.2. Subnets.................................................................................................. 22 2.3.6.3. Point-to-Point Links.............................................................................. 22 2.3.7. Network-Specific Parameterization .......................................................... 25 2.3.8. Node-Specific Parameterization ............................................................... 26 2.3.9. Instance ID Parameterization.................................................................... 27 3. Global Simulation Parameters .................................................................................. 28 3.1. Experiment Name ............................................................................................. 28 3.2. Version.............................................................................................................. 28 3.3. Coordinate System ............................................................................................ 29 3.4. Terrain Corners ................................................................................................. 29 3.5. Terrain Dimensions........................................................................................... 30 3.6. Irregular Terrain................................................................................................ 30 3.7. Random Number Seed ...................................................................................... 31 3.8. Maximum Simulation Time.............................................................................. 31 3.9. File-based Node Placement............................................................................... 32 3.10. Protocol Stack ............................................................................................... 33 3.11. Statistics Filtering ......................................................................................... 34 3.12. Mobility Options........................................................................................... 35 3.12.1. Random Drunken ...................................................................................... 36 3.12.2. Random Waypoint .................................................................................... 36 3.12.3. Trace ......................................................................................................... 37 3.13. Mobility Position Granularity ....................................................................... 38 3.14. Application Setup File .................................................................................. 38 4. Application Models................................................................................................... 39 4.1. Traffic Generators............................................................................................. 39

4.1.1. FTP............................................................................................................ 40 4.1.2. FTP/Generic.............................................................................................. 41 4.1.3. HTTP......................................................................................................... 43 4.1.4. Telnet ........................................................................................................ 44 4.1.5. CBR........................................................................................................... 45 4.2. Routing Protocols.............................................................................................. 46 4.2.1. RIPv2 ........................................................................................................ 46 4.2.2. Bellman-Ford ............................................................................................ 47 4.2.3. Fisheye State Routing ............................................................................... 47 4.2.4. BGPv4....................................................................................................... 48 4.2.4.1. BGP Global Parameters ........................................................................ 48 4.2.4.2. BGP Config File Parameters................................................................. 50 4.2.4.3. Example BGP Config File .................................................................... 52 5. Transport Protocols................................................................................................... 53 5.1. TCP ................................................................................................................... 53 5.1.1. TCP Tahoe ................................................................................................ 54 5.1.2. TCP Reno.................................................................................................. 55 5.1.3. TCP Lite.................................................................................................... 55 5.1.4. TCP NewReno .......................................................................................... 56 5.1.5. TCP SACK................................................................................................ 56 5.1.6. TCP Parameters ........................................................................................ 57 5.1.6.1. Delay ACKs Option.............................................................................. 57 5.1.6.2. Nagle Algorithm Option ....................................................................... 57 5.1.6.3. Keep-alive Probes Option ..................................................................... 58 5.1.6.4. TCP Header Push Bit Option................................................................ 58 5.1.6.5. Maximum Segment Size ....................................................................... 58 5.1.6.6. RFC 1323 option................................................................................... 58 5.1.6.7. Send Buffer Size ................................................................................... 59 5.1.6.8. Receive Buffer Size .............................................................................. 59 5.1.7. TCP ECN .................................................................................................. 60 5.2. UDP................................................................................................................... 60 6. Network Protocols .................................................................................................... 61 6.1. IPv4 ................................................................................................................... 61 6.1.1. Static Routes ............................................................................................. 62 6.1.2. Default Routes .......................................................................................... 63 6.2. Network Queue Scheduler ................................................................................ 64 6.2.1. Strict Priority Scheduler............................................................................ 65 6.2.2. Round Robin Scheduler ............................................................................ 66 6.2.3. Weighted Fair Queuing Scheduler............................................................ 66 6.2.4. Self-Clocked Fair Queuing Scheduler ...................................................... 67 6.2.5. Weighted Round Robin Scheduler............................................................ 68 6.3. Network Queue Disciplines .............................................................................. 69 6.3.1. FIFO.......................................................................................................... 69 6.3.2. RED........................................................................................................... 70 6.3.3. RIO............................................................................................................ 72 6.3.4. WRED....................................................................................................... 73

6.4. Routing Protocols.............................................................................................. 76 6.4.1. OSPFv2 ..................................................................................................... 76 6.4.2. AODV ....................................................................................................... 77 6.4.3. DSR........................................................................................................... 77 6.4.4. LAR1......................................................................................................... 78 6.4.5. STAR ........................................................................................................ 78 6.5. Multicast Routing Protocols ............................................................................. 79 6.5.1. Multicast Group Membership Configuration............................................ 79 6.5.2. ODMRP .................................................................................................... 80 6.5.3. DVMRP .................................................................................................... 81 6.5.4. MOSPF ..................................................................................................... 82 6.6. Quality of Service (QoS) Routing Protocols .................................................... 83 6.6.1. QOSPF ...................................................................................................... 83 7. MAC Protocols ......................................................................................................... 85 7.1. IEEE 802.11-1997 DCF.................................................................................... 85 7.2. CSMA ............................................................................................................... 86 7.3. Switched Ethernet ............................................................................................. 87 8. Physical Layer Models.............................................................................................. 88 8.1. Channel Properties ............................................................................................ 88 8.1.1. Propagation Channel Frequency ............................................................... 89 8.1.2. Propagation Model.................................................................................... 89 8.1.3. Propagation Limit ..................................................................................... 90 8.1.4. Path Loss Model Selection........................................................................ 91 8.1.5. Shadowing Model ..................................................................................... 92 8.1.6. Fading Model ............................................................................................ 92 8.2. Physical Layer Properties and Parameters........................................................ 93 8.2.1. Channel Masks.......................................................................................... 93 8.2.2. Temperature .............................................................................................. 94 8.2.3. Noise Factor .............................................................................................. 94 8.2.4. Packet Reception Model ........................................................................... 95 8.2.4.1. Bit Error Rate Tables ............................................................................ 95 8.2.5. Data Rate................................................................................................... 96 8.2.6. Transmission Power.................................................................................. 96 8.2.7. Reception Sensitivity ................................................................................ 96 8.2.8. Reception Threshold ................................................................................. 97 8.2.9. Antenna Model.......................................................................................... 97 8.2.10. Antenna Gain ............................................................................................ 97 8.2.11. Antenna Height ......................................................................................... 97 8.2.12. Energy Consumption Model ..................................................................... 98 9. QualNet API Reference ............................................................................................ 99 9.1. QualNet File Extensions ................................................................................... 99 9.2. Time Functions ............................................................................................... 100 9.2.1. getSimTime(node) .................................................................................. 100 9.2.2. ctoa() ....................................................................................................... 101 9.3. Configuration Related Functions .................................................................... 102 9.3.1. IO_ReadString()...................................................................................... 102

9.3.2. IO_ReadInt() ........................................................................................... 104 9.3.3. IO_ReadDouble().................................................................................... 105 9.3.4. IO_ReadTime() ....................................................................................... 107 9.4. Message Related Functions............................................................................. 109 9.4.1. MESSAGE_Alloc() ................................................................................ 110 9.4.2. MESSAGE_InfoAlloc().......................................................................... 111 9.4.3. MESSAGE_PacketAlloc()...................................................................... 113 9.4.4. MESSAGE_AddHeader()....................................................................... 115 9.4.5. MESSAGE_RemoveHeader() ................................................................ 117 9.4.6. MESSAGE_Copy()................................................................................. 119 9.4.7. MESSAGE_Send() ................................................................................. 121 9.4.8. MESSAGE_Free() .................................................................................. 123 9.4.9. MESSAGE_GetEvent() .......................................................................... 125 9.4.10. MESSAGE_ReturnInfo()........................................................................ 126 9.4.11. MESSAGE_ReturnPacket().................................................................... 128 9.5. Graphical User Interface API Functions......................................................... 130 9.5.1. GUI_Initialize ......................................................................................... 130 9.5.2. GUI_SetEffect......................................................................................... 132 9.5.3. GUI_InitNode ......................................................................................... 133 9.5.4. GUI_MoveNode ..................................................................................... 134 9.5.5. GUI_SetNodeOrientation ....................................................................... 135 9.5.6. GUI_SetNodeIcon................................................................................... 136 9.5.7. GUI_SetNodeLabel................................................................................. 137 9.5.8. GUI_SetNodeRange ............................................................................... 138 9.5.9. GUI_SetNodeType ................................................................................. 139 9.5.10. GUI_SetPatternIndex.............................................................................. 140 9.5.11. GUI_SetPatternAndAngle ...................................................................... 141 9.5.12. GUI_AddLink ......................................................................................... 142 9.5.13. GUI_DeleteLink ..................................................................................... 143 9.5.14. GUI_Broadcast ....................................................................................... 144 9.5.15. GUI_EndBroadcast ................................................................................. 145 9.5.16. GUI_Multicast ........................................................................................ 146 9.5.17. GUI_Unicast ........................................................................................... 147 9.5.18. GUI_Receive........................................................................................... 148 9.5.19. GUI_Drop ............................................................................................... 149 9.5.20. GUI_Collision......................................................................................... 150 9.5.21. GUI_CreateSubnet.................................................................................. 151 9.5.22. GUI_CreateHierarchy ............................................................................. 152 9.5.23. GUI_AddApplication.............................................................................. 153 9.5.24. GUI_DeleteApplication .......................................................................... 154 9.5.25. GUI_AddInterfaceQueue........................................................................ 155 9.5.26. GUI_QueueInsertPacket ......................................................................... 156 9.5.27. GUI_QueueDequeuePacket .................................................................... 157 9.5.28. GUI_QueueDropPacket .......................................................................... 158 9.5.29. GUI_DefineMetric.................................................................................. 159 9.5.30. GUI_SendIntegerData............................................................................. 160

9.5.31. GUI_SendRealData................................................................................. 161 9.5.32. GUI_SendUnsignedData......................................................................... 162 9.6. Statistics Output API Functions...................................................................... 163 9.6.1. IO_PrintStat ............................................................................................ 163 9.7. Error/Assertion Related API Functions .......................................................... 164 9.7.1. ERROR_ReportError.............................................................................. 165 9.7.2. ERROR_Assert ....................................................................................... 165

Table of Figures
Figure 1: Examples of the QualNet Time Format ............................................................ 17 Figure 2: Mobility Options ............................................................................................... 35 Figure 3: Mapping to Detailed Algorithm for RED Gateways......................................... 71 Figure 4: The Life Cycle of a Packet .............................................................................. 109

1. Overview of QualNet
1.1. QualNet Features

QualNet is a state-of-the-art simulator for large, heterogeneous networks and the distributed applications that execute on such networks. heterogeneous networks: Robust set of wired and wireless network protocol and device models, useful for simulating diverse types of networks. Optimized for speed and scalability on one processor, QualNet executes equivalent scenarios 5-10x times faster than commercial alternatives Designed from the ground-up as a parallel simulator, QualNet executes your simulation multiples faster as you add processors. A robust graphical user interface covers all aspects of the simulation, from scenario creation and topology setup, integration of custom protocols, through real-time execution of network models from within the GUI, animation, to postsimulation statistical analysis. See the QualNet Visual Environment Users Manual for more details. QualNet has been used to simulate high-fidelity models of wireless networks with as many as 50,000 mobile nodes. QualNet executes on all commonly used platforms including Windows NT/2000/XP Professional, Solaris, Linux, and most UNIX variants. The following QualNet features provide a unique capability for accurate, efficient simulation of large-scale,

1.2.

Chapter Outline

Chapter One provides an introduction to the QualNet simulation environment, and a description of its key features. Following this section is the installation reference and platform-specific notes.

Chapter Two introduces the directory structure, command-line compilation and execution of experiments, and provides a file format and syntax reference for the specification and execution of a network modeling scenario.

Chapter Three covers global simulation parameters, such as network topology, length of the simulation, and mobility, if applicable.

Chapters Four through Eight cover the protocol model library, including the parameters, features, statistics collected, specifications, and references for the standard protocols and models. o Chapter Four introduces application models, such as FTP, TELNET, and Web browser and server models. This chapter also covers application layer routing protocols, such as RIPv2, which utilize a transport protocol (TCP or UDP) to transmit messages. o Chapter Five covers transport protocol models, such as TCP and UDP. o Chapter Six covers network layer protocols, such as routing protocols, queue and scheduling algorithms, which utilize or perform IP services directly. o Chapter Seven covers the MAC layer protocols, such as CSMA, IEEE 802.11 DCF, and the switched Ethernet and point-to-point link models. o Chapter Eight covers the radio and propagation layer protocols and services.

Chapter Nine provides a technical reference, for the advanced user. It covers the simulators inter-layer APIs and all API functions.

1.3.

How To Install QualNet

QualNet has the following system requirements: Operating System Choices: o Solaris 2.5.1 and up o Windows NT 4.0 / 2000 / XP Professional o RedHat, Mandrake, and compatible Linux 6.0-8.1 The Graphical User Interface, including the QualNet Statistical Analysis Package, requires Java 2, version 1.3 or later, which is available for free from Sun Microsystems1 for all of the listed operating systems. Memory Requirements: 64MB for LAN size simulations, 128MB+ for MAN size networks Disk Requirements: 100 MB Processor Requirements: Pentium-class or UltraSPARC Platform-specific Requirements: see the notes for your Operating System below

QualNet has an automatic installation program called setup.exe (Windows)for the Windows operating system. Please see the Release Notes for Installation on UNIX based systems. Run the setup program from the Installation CD, and follow the prompts to complete installation. You will need to know the desired installation location for the software.

http://java.sun.com/products/

1.4.

Windows NT 4.0/2000 Notes

QualNet on Windows NT 4.0 and Windows 2000 requires that the Visual C/C++ 6.0 compiler be installed on the system first. Follow the instructions in your Visual C/C++ or Visual Studio manual to ensure proper installation of your compiler. QualNet also requires at least Visual Studio 6.0 Service Pack 52 be installed. Near the end of the installation process, the Visual C++ installer will provide a checkbox for command-line utilities. Make sure to select this option, since it is not included by default.

1.5.

Solaris Notes

QualNet on Solaris requires installation of the GNU C/C++ compilers, version 2.8.1 and above or the Sun Forte / SparcWorks C++ compiler, version 5.0 or 6.0. We recommend using the most recent version of the compiler.3,4

1.6.

Linux Notes

QualNet on Linux requires installation of the GNU C/C++ compilers version 2.95.2 or greater, which are standard on Mandrake Linux distributions and RedHat distributions starting with version 6.2. Please check the GCC Homepage for the most recent version of the compiler, if necessary.3

2 3

http://msdn.microsoft.com/vstudio/downloads/updates.asp http://www.gnu.org/software/gcc/ 4 http://www.sunfreeware.com/

2. Command-Line Execution and File-Based Specification

For those users who prefer to execute simulations from the command-line, this chapter describes the syntax and files for configuring a simulation outside of the Graphical User Interface (GUI). QualNet requires a single parameter, which is the name of the experiment.config file which sets up the experiment, or network scenario, that you wish to run. An included sample of this file is called the default.config file. The default.config file sometimes references support configuration files (default.app, for example, configures the ftp, telnet, CBR, or other application-level models in a QualNet simulation). We call these files, generally, QualNet Configuration Files, config files, or default.config files.5 The naming convention we have employed uses the prefix (default in this case) to refer to the name of the experiment, and the suffix (.config, .app, .ber) to indicate the type of file.

default.config doesnt have to be named default.config. It could be named my-scenario-Feb10.config, for example. The same freedom applies to default.app, and so on.

2.1.

Directory Structure of QualNet

The QualNet source tree appears under the directory you chose during QualNet installation. The main subdirectories and a brief description of their contents and purpose are listed below: /application /bin /data /doc /gui /include /mac /main /mobility /network /phy /transport /verification code for the application layer protocols and traffic generators executable and configuration or input/output files supplementary data files for experiments and utility programs the documentation the Visual Environment Toolset common include files the code for the MAC layer protocols the basic framework design the code for the mobility models the code for the network layer protocols and routing protocols the code for the physical layer models the code for the transport layer protocols (TCP/UDP, RSVP, etc) Sample files and outputs to verify protocol correctness

2.2.

Command-Line Compilation and Execution

If you are running QualNet for the first time, or if you have created or modified protocol models in QualNet, and placed their source code in the relevant directories, you will need to compile QualNet from the main/ subdirectory to include them. Change to the main/ subdirectory using cd, and then: Windows NT/2000: Solaris/Linux: run nmake from the command-line run make from the command-line

To run the simulation you should change directory to the bin/ subdirectory. The executable produced by the previous step is called "qualnet" (Solaris/Linux) or qualnet.exe (Windows). This executables takes one required command line parameter, which is the filename of the relevant Scenario Input File. Scenario Input Files describe the network being modeled, the length of time to simulate this network, and all other scenario specific parameters, and are described in Section 2.3. This executable also takes a second, optional, command line parameter as a single word name for the experiment that this simulation execution represents. This parameter overrides the EXPERIMENT-NAME configuration parameter if it also appears in the Scenario Input File, and serves the same purpose. Type "qualnet default.config" from a command prompt within the bin/ subdirectory to run the program with the sample scenario file. A file called "default.stat" will be produced at the end of the simulation, and contains all the statistics generated by the current experiment. You can use a text editor to make modifications to the default.config file to vary the parameters for running the simulation.

2.3.

Scenario Input File Syntax

This section explains the syntax for specifying network scenarios in the Scenario Input File. It also covers the network-specific (Section 2.3.7) and node-specific (Section 2.3.8) parameterization syntax that allows users to select different options for different device models, in order to specify the heterogeneous elements such as hosts, routers, and radios that make up the network you are modeling.

2.3.1. Configuration File Converter

The set of recognized and/or required parameters, as described in the remainder of this section and the following chapter, can change with newer releases of QualNet. In order to allow users to easily update their configuration files to operate with the updated releases of QualNet, we have provided a tool for converting old configuration files into the most recent format. This section describes the usage of this tool. The tool is executed from the command line as follows. converter [-c|-nc] infile outfile The converter takes as parameters the name of the configuration file to be converted, and a name for the resulting file. The two names can be the same. The converter also has two optional parameters. The "-c" flag tells the converter to print all the descriptive comments included in the default configuration file to the new file. This is the default behavior. The "-nc" flag disables the comments, printing only the active variables.

The converted file orders its variables according to the standard format, and will print all the qualified versions of a variable consecutively. For example, assume the user's file contains the following. LINK N2-1.0 { 1, 2 } [N2-1.0] LINK-BANDWIDTH 1000000 LINK N2-2.0 { 2, 3 } [N2-2.0] LINK-BANDWIDTH 1000000 LINK N2-3.0 { 3, 4 } [N2-3.0] LINK-BANDWIDTH 1000000 The converter will print these as follows: LINK N2-1.0 { 1, 2 } LINK N2-2.0 { 2, 3 } LINK N2-3.0 { 3, 4 } [N2-1.0] LINK-BANDWIDTH 1000000 [N2-2.0] LINK-BANDWIDTH 1000000 [N2-3.0] LINK-BANDWIDTH 1000000 Note that this conversion utility only updates the variables in the main configuration file. It does not update the format of any auxiliary files, such as the application configuration file, or BGP.

2.3.2. Comments
In the input file anything following a "#" is treated as a comment. The sample default.config file contains descriptive information about the parameters that can be selected, using this style of commenting. It also contains all of the available options for each parameter, all of which are commented, except for the parameter currently selected. In order to select a different option than the one already selected, just add a # symbol in front of the current selection, and remove it from the selection you wish to use instead.

2.3.3. QualNet Time Format

The QualNet Time Format describes the standard text format for specifying units of time. This specification is used in all configuration files where values are expressed as units of time, and appears as a number, optionally followed by characters that specify the unit. If no characters follow the number, the unit is assumed to be seconds. The valid character combinations are listed in examples below (Figure 1: Examples of the QualNet Time Format): 100NS 100US 100MS 100S 100 100M 100H 100D
Figure 1: Examples of the QualNet Time Format

100 nanoseconds 100 microseconds 100 milliseconds 100 seconds 100 seconds (default case) 100 minutes 100 hours 100 days

2.3.4. QualNet Coordinate Format

The QualNet Coordinate Format describes the standard text format for specifying node positions (either initial positions, or as a result of mobility). Users can specify coordinates in either the LATLONALT or CARTESIAN coordinate systems (See Section 3.3). This is selected via the COORDINATE-SYSTEM parameter (See Section 3.3). Coordinates can be either two or three floating-point numeric values, where the third (altitude, z) is assumed to be zero if omitted. These values are separated by commas, and encased between parentheses. Ex. (0,0) or (0,0,0) or (-34.00, 115.00, 220.5)

2.3.5. Identifying Nodes and Networks

A Node in QualNet can represent any of the several devices that connect to a network, such as radio devices, desktop computers, routers, and laptop computers. Each Node in QualNet has a unique Node Identifier. These devices/nodes can have one or more network interfaces, each of which has its own IP address and subnet mask. The IP address and subnet mask combine to describe that network interfaces membership in a subnet.

2.3.5.1. Node Identifiers

Every QualNet node has a unique nodeId (or node identifier), which is a unique, positive (nonzero) integer. These integers need not be contiguous, so they can be numbered for user readability. For example, if a scenario has three nodes, a user can assign them nodeIds 1, 2, and 3. The user could also assign these three nodes, nodeIds 13, 16, and 159. NodeIds are used in mobility configuration files, initial node placement files, and throughout the text based QualNet Configuration File, to refer to node-specific, heterogeneous parameters and settings. From this point forward in the documentation, if we wish to refer to a node by its nodeId, we will use the term node 1, for example, to refer to the node with the nodeId of 1.

2.3.5.2. IP Addresses and Subnets

Nodes communicate with each other through connected network interfaces. Every node must have at least one network interface. Examples of Network interfaces exist include 802.11b PCMCIA cards, Ethernet adapters, and serial links on routers. A network interface in QualNet has one unique IP address6 and a subnet mask which is shared by all network interfaces on a single subnet. If you apply (use bitwise OR) the subnet mask to any IP address on the subnet, you obtain the network (subnet) address of that subnet. A subnets network address in IPv4 is a 32-bit address with zeroes for all bits used to determine host IP addresses. A subnet mask is a 32-bit value with ones for all bits used by the network address and zeroes for all bits used to determine host IP addresses. An example of a network address in dot-notation would be 192.168.0.0, and a corresponding subnet mask would be 255.255.255.0. Dotnotation gives the value of each 8 bits of the 32-bit address separated by dots.
While 10/24 and 192.168/16 subnets are frequently deployed behind NATd networks, in QualNet, each of these subnets would be made up of network interfaces with unique IP addresses for simplicity of reading and categorizing statistics.
6

Therefore, the example subnet mask of 255.255.255.0 indicates that 8 bits are used to determine host IP addresses, and these hosts would have IP addresses from 192.168.0.1 through 192.168.0.254, for a maximum of 254 hosts on this subnet. 192.168.0.0 is the network address and 192.168.0.255 is the broadcast address for this subnet.

2.3.6. Specifying Nodes and Networks

A QualNet simulation experiment is composed of networks of Nodes, which we will refer to as subnets. To instantiate these networks, users will need to place descriptive SUBNET and LINK declarations in the configuration file. A LINK declaration is a specialized SUBNET with exactly two members connected by a full duplex link, also referred to as a point-to-point link. LINK and SUBNET declarations include two parameters: the QualNet Subnet Shorthand declaration of the network address and subnet mask, and the list of nodeIds for the members of the subnet.

2.3.6.1. QualNet Subnet Shorthand

We define a shorthand method to define the network address and subnet mask of a network as QualNet Subnet Shorthand, which has the following syntax: N<host bits>-<network address with significant digits only> An example of this syntax would be N8-1.0. This example specifies that eight bits be reserved for host addresses, which defines the subnet mask to be 255.255.255.0 (See Section 2.3.5.2). The network address is 0.0.1.0, because omitted (insignificant) numbers are assumed to be zero. N8-1.0 and N8-0.0.1.0 are equivalent. Hosts on this network would have IP addresses from 0.0.1.1 through 0.0.1.254, for a maximum of 254 hosts on this subnet. 0.0.1.255 is the broadcast address for this subnet. The number of hosts that can be enumerated is calculated by 2n-2, where n is the number of host bits. 28-2 = 254. QualNet will report an error if more nodes are assigned to this subnet than the number of host bits can allow. The QualNet Subnet Shorthand specification of a network can be used to set configuration parameters which apply specifically to the network, and the values of these parameters can differ from the global defaults, or the values assigned for these parameters in other subnets. (See Section 2.3.7 for more information)

2.3.6.2. Subnets
The SUBNET keyword is used to describe a network composed of two or more nodes. It also instantiates the network interfaces on those nodes, and instantiates the nodes themselves, if they have not appeared in an earlier SUBNET or LINK declaration. It takes two arguments: the QualNet Subnet Shorthand specification of the network address and subnet mask, and the nodeIds of the two or more nodes that compose the network separated by commas, and surrounded by curly braces {}. An Example illustrating the usage of the SUBNET keyword is given below, with explanations and supporting details to follow: SUBNET N8-1.0 { 1, 2, 3 thru 10 } QualNet auto-assigns IP addresses based on the network address to the nodes in the subnet represented by the SUBNET declaration by assigning network_address.1 through network_address.10 to the ten nodes. Notice the use of the thru keyword, indicating that there are seven additional nodes numbered from 3 through 7, without having to explicitly enumerate them. In this example, node 1 is assigned IP address 0.0.1.1. Node 2 is assigned IP address 0.0.1.2. Node 10 is assigned IP address 0.0.1.10.

2.3.6.3. Point-to-Point Links

The LINK keyword is used to describe a point-to-point link connecting two nodes. It also instantiates the network interfaces on those nodes, and instantiates the nodes themselves, if they have not appeared in an earlier SUBNET or LINK declaration. It takes two arguments: the QualNet Subnet Shorthand specification of the network address and subnet mask, and the two nodeIds of the nodes that are connected by the point-to-point link separated by commas, and surrounded by curly braces {}.

Associated with the LINK declaration are the following configuration parameters, which define the properties of the link: LINK-BANDWIDTH LINK-PROPAGATION-DELAY LINK-RETURN-BANDWIDTH LINK-RETURN-PROPAGATION-DELAY 1544000 1MS 1000000 5MS

LINK-BANDWIDTH defines the bandwidth in bits per second, of the link between the first nodeId and the second nodeId between the curly braces. If LINK-RETURN-BANDWIDTH is not specified, then the link is assumed to have identical bandwidth in both directions. If it is specified, then LINKRETURN-BANDWIDTH defines the bandwidth in bits per second, from the second nodeId to the first nodeId, for an asymmetrical link. LINK-PROPAGATION-DELAY specifies the time in QualNet Time Format (See Section 2.3.3) it takes one bit to traverse the link from the first nodeId to the second nodeId between the curly braces. The amount of time it takes to transmit a packet from the idle state to arrival at the receiver is the (packet size / bandwidth) + propagation delay. identical propagation delay in both directions. If LINK-RETURNPROPAGATION-DELAY is not specified, then the link is assumed to have Otherwise, LINK-RETURNPROPAGATION-DELAY specifies the propagation delay in QualNet Time Format (See Section 2.3.3) from the second nodeId to the first nodeId, for an asymmetrical link.

An Example illustrating the usage of the LINK keyword is given below, with explanations and supporting details to follow: LINK N2-1.0 { 1, 2 } LINK N2-2.0 { 2, 3 } LINK-BANDWIDTH 1544000

LINK-PROPAGATION-DELAY 1MS [N8-2.0] [N8-2.0] LINK-BANDWIDTH LINK-PROPAGATION-DELAY 112000 50MS

In the first LINK statement, the two nodes connected have nodeIds 1 and 2. From the second LINK statement, we see that nodeId 2 and nodeId 3 are connected. NodeId 2 is connected to both nodeId 1 and nodeId 3, by separate links, and can switch packets between them. QualNet auto-assigns IP addresses based on the network address to the nodes in the subnet represented by the LINK declaration by assigning network_address.1 and network_address.2 to the two nodes. For the first LINK statement in the example, node 1 is assigned IP address 0.0.1.1. Node 2 is assigned IP address 0.0.1.2. The LINK-BANDWIDTH and LINK-PROPAGATION-DELAY lines LINK-BANDWIDTH LINK-PROPAGATION-DELAY 1544000 1MS

specify the default properties for point-to-point links (in this case they have T1 bandwidth and delay). The lines

[N8-2.0] [N8-2.0]

LINK-BANDWIDTH LINK-PROPAGATION-DELAY

112000 50MS

indicate that the link on the 0.0.2.0 subnet should operate at 112 kbps with a 50 ms propagation delay (ISDN speed), for each direction.7 (See Section 2.3.7 for more information on this syntax)

2.3.7. Network-Specific Parameterization

Users can set any of the protocol-based parameters (MAC-PROTOCOL, ROUTING-PROTOCOL, MULTICAST-PROTOCOL, etc.) for all nodes, subsets of nodes, or single nodes. This section deals with the selection of protocol-based parameters for entire subnets. In order to restrict the specification of a protocol-based parameter to a subnet, include that subnets QualNet Subnet Shorthand (See Section 2.3.6.1) representation in brackets to the left of the parameter name, as in the example below: # [N8-1.0] MAC-PROTOCOL MAC802.11 MAC-PROTOCOL CSMA # The example above assigns the N8-1.0 subnet to use the MAC-PROTOCOL MAC802.11 . All other subnets use CSMA. A parameter without the qualifier within brackets on the left hand side, is used as the default value.

Thats 112 kbps one way, 112 kbps the other way.

2.3.8. Node-Specific Parameterization

Users can set any of the protocol-based parameters (MAC-PROTOCOL, ROUTING-PROTOCOL, MULTICAST-PROTOCOL, etc.) for all nodes, subsets of nodes, or single nodes. This section deals with the selection of protocol-based parameters for subsets of nodes or single nodes. In order to restrict the specification of a protocol-based parameter to a single node or set of nodes, include the IP Addresses or NodeIds of the nodes you would like the parameter to apply to, in brackets to the left of the parameter name, as in the example below: # [0.0.1.1, 0.0.1.2, 3, 4] IP-QUEUE-TYPE RED IP-QUEUE-TYPE FIFO # The example above sets the queueing mechanism on the nodes that have network interfaces with IP addresses 0.0.1.1, and 0.0.1.2 to use Random Early Detection. It also sets the default network interfaces (the first one instantiated) on nodes with nodeIds 3 and 4, to use Random Early Detection queueing as well. It is recommended that users use nodeIds only in the case where the specification would not be ambiguous, i.e., do not use nodeId parameterization for nodes that serve as gateways, as a general rule.

2.3.9. Instance ID Parameterization

Some parameters can have different values for different instances on the same network interface, or multiple global definitions. A good example of the former would be parameters that affect each of the multiple priority output queues on a particular network interface. An example of the latter case would be the channel frequency of each wireless channel in the simulation. An example of how to specify each follows: # IP-QUEUE-TYPE[2] RED IP-QUEUE-TYPE FIFO PROPAGATION-CHANNEL-FREQUENCY[0] 2.4e9 PROPAGATION-CHANNEL-FREQUENCY[1] 2.5e9 # In the example above, the default queueing mechanism for all nodes, and all IP output queues is FIFO. However, for the IP queue with priority 2, the queueing mechanism is Random Early Detection. (See Section 6.3.2 for more information) The example also instantiates two wireless channels to be simulated, and these operate at 2.4 Ghz and 2.5Ghz respectively. (See Section 8.1.1 for more information)

3. Global Simulation Parameters

This chapter explains the global simulation parameters for specifying network scenarios in the Scenario Input File. Global parameters include the length of simulated time, the number of elements (hosts, routers, radios) that comprise the network, and statistics collection values.

3.1.

Experiment Name

The following parameter specifies the name of the experiment that this configuration file describes. It is used as the prefix (followed by .stat) of the statistical output file produced at the end of the simulation. # EXPERIMENT-NAME myExperiment #

3.2.

Version

The following parameter specifies the version number of this configuration file. Each release of QualNet has an associated version number, and this parameter allows the Configuration File Converter (See Section 2.3.1) to port any changes that you have made to your configuration file to the newest version. Please do not alter the value of this field yourself. # VERSION 3.0 #

3.3.

Coordinate System

The following parameter specifies the coordinate system to use for all coordinates in this scenario. The two options are LATLONALT, which specifies the standard latitude, longitude, and altitude coordinates, and CARTESIAN, which specifies that coordinates are given in positive values that represent the distance in meters from the origin (0, 0, 0) on a flat plain. However, the Z or altitude coordinate can be negative in both the Cartesian and Lat/Lon/Alt coordinate systems, or omitted entirely. If the third coordinate is omitted, it is assumed to be 0. # COORDINATE-SYSTEM CARTESIAN # COORDINATE-SYSTEM LATLONALT #

3.4.

Terrain Corners

The following parameter specifies the coordinates of the southwest and northeast corners of the simulated terrain, when using the LATLONALT coordinate system specified in Section 3.3. All node positions will have coordinate values between the southwest corner and northeast corner coordinates for their latitude and longitude coordinates. The altitude coordinate should be omitted in this parameter. # TERRAIN-SOUTH-WEST-CORNER TERRAIN-NORTH-EAST-CORNER #

(30.00, 40.00) (30.01, 40.01)

3.5.

Terrain Dimensions

The following parameter specifies the size of the physical terrain in which the elements are being simulated, in the CARTESIAN coordinate system specified in Section 3.3. The coordinate unit is meters. The altitude coordinate should be omitted in this parameter.

# # Terrain Area we are simulating. TERRAIN-DIMENSIONS (2000, 2000) #

3.6.

Irregular Terrain8

The following three parameters allow integration with irregular terrain files for propagation and mobility modeling. The TERRAIN-DATA-TYPE parameter specifies the type of terrain data to interface with. The only available setting for this parameter is CTDB. CTDB-FILENAME specifies the relative or absolute path and filename for the CTDB data file for the selected terrain. MOBILITY-GROUND-NODE if turned on (YES) uses the terrain file to determine the altitude coordinates of nodes. # # TERRAIN-DATA-TYPE CTDB # CTDB-FILENAME nebosnia_mes # MOBILITY-GROUND-NODE YES #

Terrain Support is not included in the basic QualNet product. Please contact sales@scalablenetworks.com for more information. Access to these models is also restricted.

3.7.

Random Number Seed

The following is a random number seed for generating random numbers as needed by the simulation. Specifying the same parameters and seed over two simulations guarantees that the simulators result will be exactly the same no matter how many times you execute the specific scenario. Varying the seed, and averaging the resulting metrics over several runs can reduce the number of outliers in the statistical analysis of network behavior. # SEED 1 #

3.8.

Maximum Simulation Time

The following parameter represents the maximum simulation time. It is specified in the QualNet Time Format (See Section 2.3.3) described above. When QualNet has simulated your network for this amount of time, the simulation will terminate and record all of the statistics you have collected. See Section 3.11 regarding filtering options so that you do not collect unwanted statistics from layers or protocols you are not interested in. # SIMULATION-TIME 100M #

3.9.

File-based Node Placement

The following parameter represents the method used to automate or specify node placements. For automatic placement of nodes, select RANDOM, UNIFORM, or GRID. To place nodes manually, choose FILE, specify NODE-PLACEMENTFILE with the filename of your text file containing all of the initial coordinates for all of your nodes. # NODE-PLACEMENT RANDOM # RANDOM UNIFORM Nodes are placed randomly within the physical terrain. Based on the number of nodes in the simulation, the physical terrain is divided into a number of cells. Within each cell, a node is placed randomly. This yields a topology that is random, but with a somewhat uniform density of nodes. Node placement starts at (0, 0) and the nodes are placed in grid format with each node GRID-UNIT away from its neighbors. GRIDUNIT must also be specified numerically, with the unit in meters or degrees, depending on the value of COORDINATE-SYSTEM. The number of nodes specified for the simulation also must be square of an integer (i.e. 4, 9, 16, 25, ) Position of nodes is read from the NODE-PLACEMENT-FILE. NODE-PLACEMENT-FILE is specified as a filename, which can have a relative or absolute path. The filename is given without quotes, and cannot contain spaces. On each line of the referenced text file, the node address is given, followed by a space, then the time value 0, and then the (x, y, z) or (lat, lon, alt) coordinates for the position of the node. Optionally, the azimuth and elevation values can follow the coordinates.

GRID

FILE

3.10.

Protocol Stack
The

The following parameters define the protocol selections at each layer.

available protocols at each layer are discussed in Chapter 4. Note that you can combine these selections with the node specific parameterization discussed in Section 2.3.4 to define the set of protocols running at every node in the simulated network. # MAC-PROTOCOL TCP NETWORK-PROTOCOL IP-QUEUE-TYPE IP-QUEUE-SCHEDULER ROUTING-PROTOCOL #

802.11 LITE IP FIFO STRICT-PRIORITY BELLMANFORD

3.11.

Statistics Filtering

The following parameters determine if you are interested in the statistics of each layer in QualNet. By specifying YES for some or all of the following parameters, the simulation will provide you with statistics for the selected layers. All of the statistics are compiled together into a file called "default.stat" that is produced at the end of the simulation. If EXPERIMENT-NAME is defined in the configuration file, the compiled statistics file will be named <experiment_name>.stat instead of default.stat. The statistics filtering options are listed below: # APPLICATION-STATISTICS TCP-STATISTICS UDP-STATISTICS RSVP-STATISTICS ROUTING-STATISTICS IGMP-STATISTICS EXTERIOR-GATEWAY-PROTOCOL-STATISTICS NETWORK-LAYER-STATISTICS QUEUE-STATISTICS MAC-LAYER-STATISTICS PHY-LAYER-STATISTICS MOBILITY-STATISTICS # YES YES YES NO YES NO YES YES YES YES YES NO

3.12.

Mobility Options

The following sections cover mobility related parameters. QualNet provides the Random-Drunken and Random-Waypoint models of mobility as part of the standard package, and also provides Trace-based mobility for users who wish to interface with existing mobility logs or third-party mobility generators. Pathloss-Matrix mobility is a special case, in which the radio nodes look up a precalculated path loss from a timeindexed table when they wish to transmit data. MOBILITY PATHLOSS-MATRIX requires PATHLOSS PATHLOSS-MATRIX to be selected as well. # MOBILITY # NONE RANDOMDRUNKEN RANDOMWAYPOINT

NONE

TRACE

PATHLOSSMATRIX

The nodes remain fixed in place for the duration of the simulation A node has equal likelihood of remaining at its current position, or moving 1 meter in any direction that lies within the simulated terrain boundaries A node randomly selects a destination from the physical terrain. It moves in the direction of the destination in a speed uniformly chosen between MOBILITY-WP-MIN-SPEED and MOBILITY-WPMAX-SPEED (both specified in meter/sec). After it reaches its destination, the node stays there for MOBILITY-WP-PAUSE (specified in QualNet Time Format) time period. The mobility patterns are contained in a time-ordered trace file specified by MOBILITY-TRACE-FILE. Each line of the trace file has the following format: <nodeId> <time> (<destination x coord>, <dest y>, <dest z>) where time is in QualNet Time Format, and speed is in meters/second. Used in conjunction with the PATHLOSS-MATRIX Propagation function. With propagation determined by the matrix, QualNet does not need to track node positions to calculate path loss analytically.

Figure 2: Mobility Options

3.12.1.

Random Drunken

Random Drunken mobility simply selects randomly at each interval among five possibilities: movement in any of the four directions (assuming they lie within the simulated terrain), or remaining at its current position. To select Random Drunken mobility as the mobility model, place the following entry in default.config: MOBILITY MOBILITY-INTERVAL RANDOM-DRUNKEN 30S

In addition to this specification, this protocol requires that MOBILITYINTERVAL be specified in QualNet Time Format (See Section 2.3.3). This parameter specifies the interval between mobility selections. Smaller values specify that node positions be updated more frequently.

3.12.2.

Random Waypoint

Random Waypoint mobility selects random destinations and speeds for each node. After the nodes reach their selected destinations, they pause for a given amount of time, specified by MOBILITY-WP-PAUSE and then repeat the process. To select Random Waypoint mobility as the mobility model, place the following entry in default.config: MOBILITY MOBILITY-WP-PAUSE MOBILITY-WP-MIN-SPEED MOBILITY-WP-MAX-SPEED MOBILITY-POSITION-GRANULARITY RANDOM-WAYPOINT 30S 1 10 0.5

In addition to this specification, this protocol requires that MOBILITYPOSITION-GRANULARITY be defined in meters. This unit determines the resolution at which node positions are updated. Smaller figures mean that node positions are updated more often at smaller increments. Speed entries are specified in meters/second, with the model choosing uniformly between these, and pause time is given in QualNet Time Format (See Section 2.3.3).

3.12.3.

Trace

Trace-based mobility allows node mobility to be read from a user-readable text file format. This format allows for easy import from external models of node movements and patterns. To select trace-based mobility as the mobility model, place the following entry in default.config: MOBILITY MOBILITY-TRACE-FILE MOBILITY-POSITION-GRANULARITY TRACE default.mobility 0.5

In addition to this specification, this protocol requires that MOBILITYPOSITION-GRANULARITY be defined in meters. This unit determines the resolution at which node positions are updated. Smaller figures mean that node positions are updated more often at smaller increments. MOBILITY-TRACE-FILE refer to a text file (in the prior example, called default.mobility) that contains the following entries, each on its own line: <nodeId> <time> (<destination x coord>, <dest y>, <dest z>) where the destination coordinates are in the coordinate system specified by COORDINATE-SYSTEM (See Section 3.3) and time is specified in QualNet Time Format (See Section 2.3.3).

3.13.

Mobility Position Granularity

The MOBILITY-POSITION-GRANULARITY (in meters) is used for QualNet to calculate the frequency of updating the position of each network node. The smaller the value selected, the greater the number of position update events, and the greater the accuracy of the simulated node position throughout the simulation. However, selecting extremely small values can slow down the simulation without providing sufficient benefit in improved accuracy of results. # #MOBILITY-POSITION-GRANULARITY #

0.5

3.14.

Application Setup File

In order to set up applications (traffic generators) on nodes in a text-based QualNet simulation execution, specify the filename for the application configuration file with the APP-CONFIG-FILE parameter in the configuration file as follows: # APP-CONFIG-FILE default.app #

4. Application Models
The QualNet Standard Protocol Model Library is organized on a number of layers, based on the TCP/IP stack. At the top of the QualNet hierarchy is the application layer, which includes traffic generating applications, and routing protocols that use the transport layer services to send and receive messages. This chapter covers these protocol models, their configuration, statistical output, and includes references to the literature, where applicable.

4.1.

Traffic Generators

Traffic generators produce the data that you would expect to flow across your network. These traffic generators fall into two categories: models of the representative applications you are using, and theoretical or trace-based models of traffic.

The first category includes the web-browsing, file transfer, and Telnet connections that make up the vast majority of Internet traffic. The latter category includes models that use randomized generation, from exponential random distributions to self-similar behavior to model background, multimedia, or Internet-based traffic without the ability to sample or measure it. This category also includes trace-based traffic generation, which can be used to model the traffic characteristics of a network over which you have administrative authority. A user can also combine trace-based models with any of the other models to experiment with the effects of increasing traffic loads on a realistic model of your network.

4.1.1. FTP
FTP represents the File Transfer Protocol server and client. The size of the items sent is taken from network traces, distributions given from the tcplib9 library. If the <items_to_send> parameter is specified as 0, then tcplib9 also determines the number of items to send. In order to specify FTP traffic in the default.app application configuration file, make entries according to the following format: FTP <src> <dest> <items_to_send> <start_time> <src> <dest> refers to the the client server nodes nodes nodeId nodeId (See (See Section Section 2.3.5.1) 2.3.5.1)

or IP Address. You can use these interchangeably in this file. indicates or IP Address. <items_to_send> specifies the number of items to send. <start_time> indicates when the transmissions should begin, in simulation time (QualNet Time Format Section 2.3.3). The following example specifies that the node with nodeId 1 (node 1) will send 10 items to node 2, and begin these transmissions 50 simulation seconds into the total simulation time: FTP 1 2 10 50S The following example specifies that node 1 will send a random number of items to node 2, and begin these requests 100 simulation seconds into the total simulation time: FTP 0 1 0 100S

Software developed by the University of Southern California

The FTP model collects the following statistics: Time when session is started Time when session is closed Number of bytes sent Number of bytes received Throughput.

4.1.2. FTP/Generic
FTP/Generic represents a more configurable model of the File Transfer Protocol server and client. The size of the items sent is not determined by network traces, but instead are specified by the user. format: FTP/GENERIC <src> <dest> <items_to_send> <item_size> <start_time> <end_time> <src> <dest> refers to the the client server nodes nodes nodeId nodeId (See (See Section Section 2.3.5.1) 2.3.5.1) In order to specify FTP/Generic traffic in the default.app application configuration file, make entries according to the following

or IP Address. You can use these interchangeably in this file. indicates or IP Address. <items_to_send> specifies the number of items to send. <item_size> specifies the size of each item in bytes <start_time> indicates when the transmissions should begin, in simulation time (QualNet Time Format Section 2.3.3). <end_time> indicates when the transmissions should end (QualNet Time Format Section 2.3.3).

If <items_to_send> is set to 0, FTP/Generic will run until the specified <end_time> or until the end of the simulation, whichever comes first. If <end_time> is set to 0, FTP/Generic will run until all <items_to_send> have been sent, or until the end of the simulation, whichever comes first. If both <items_to_send> and <end_time> are greater than 0, FTP/Generic will run until either <items_to_send> items have been sent, <end_time> is reached, or the simulation ends, whichever comes first. The following example specifies that the node with the nodeId 1 (node 1) will send 10 1460byte items to node 2, and begin these transmissions at the start of the simulation (note that the start time is specified in QualNet Time Format): FTP/GENERIC 1 2 10 1460 0S 600S If the 10 items are sent before the 600 simulation seconds elapse, no other items will be sent. The FTP/Generic model collects the following statistics: Time when session is started Time when session is closed Number of bytes sent Number of bytes received Throughput.

4.1.3. HTTP
HTTP represents a single-thread web-browser and a set of web-servers that the browser will connect to. generator. This model is ported from the INSANE10 HTTP traffic The model considers think time between client requests, and varying

numbers of pages, items per page, and size of items, in the server responses. The client also considers varying lengths of sessions during which it makes requests of the same server for a given number of pages. This behavior is based on collected traffic traces11. In order to specify web-traffic in the default.app application configuration file, make entries according to the following format: HTTPD <nodeId> HTTP <nodeId> <n = num_of_servers> <server_1> <server_n> <nodeId> can refer either to the desired nodes nodeId (See Section 2.3.5.1) or IP Address. You can use these interchangeably in this file. <server {1..n}> indicates the server nodes nodeId(s) (See Section 2.3.5.1) or IP Address. An example follows, in which there are web servers placed on the nodes with nodeIds 1, 2, and 3 (nodes 1, 2, and 3). Node 4 has a web client that can choose among these three servers when deciding to request web pages. HTTPD 1 HTTPD 2 HTTPD 3 HTTP 4 3 1 2 3

10

INSANE: An Internet Simulated ATM Networking Environment. http://www.employees.org/~bmah/Software/Insane/ 11 B. Mah. An Empirical Model of HTTP Network Traffic'', Proceedings of INFOCOM 97, Kobe, Japan, April 1997. http://www.employees.org/~bmah/Papers/Http-Infocom.pdf

4.1.4. Telnet
Telnet represents the cleartext terminal server and client. The typing rate and sizes of server responses are taken from distributions created from network traces, given rom the tcplib9 library. In order to specify Telnet traffic in the default.app application configuration file, make entries according to the following format: TELNET <src> <dest> <session_duration> <start_time> <src> <dest> refers to the the client server nodes nodes nodeId nodeId (See (See Section Section 2.3.5.1) 2.3.5.1)

or IP Address. You can use these interchangeably in this file. indicates or IP Address. <session_duration> indicates the length of the entire session, in simulation time (QualNet Time Format Section 2.3.3). <start_time> indicates when the transmissions should begin, in simulation time (QualNet Time Format Section 2.3.3). The following example specifies that the node with nodeId 1 (node 1) will initiate a 5-minute telnet session to node 2, and begin the session 50 simulation seconds into the total simulation time: TELNET 1 2 5M 50S The TELNET model collects the following statistics: Time when session is started Time when session is closed Number of bytes sent Number of bytes received Throughput.

4.1.5. CBR
CBR represents constant-bit-rate traffic. It is generally used to either fill in background traffic to affect the performance of other applications being analyzed, or to simulate the performance of generic multimedia traffic. In order to specify CBR traffic in the default.app application configuration file, make entries according to the following format: CBR <src> <dest> <items_to_send> <item_size> <interval> <start time> <end time> <src> <dest> refers to the the client server nodes nodes nodeId nodeId (See (See Section Section 2.3.5.1) 2.3.5.1)

or IP Address. You can use these interchangeably in this file. indicates or IP Address. <items_to_send> specifies the number of items to send. <item_size> specifies the size of each item. <interval> indicates the pause time between transmission of each item, in simulation time. <start_time> indicates when the transmissions should begin, in simulation time (QualNet Time Format Section 2.3.3). <end_time> indicates when the transmissions should cease, in simulation time (QualNet Time Format Section 2.3.3).

The following example specifies that the node with nodeId 1 (node 1) will send 500 2-kilobyte items to node 2, sending one per minute, starting from 50 simulation seconds into the total simulation time, and ending 500 minutes later: CBR 1 2 500 2048 1M 50S 501M

The CBR model collects the following statistics: Time when session is started Time when session is closed Number of bytes sent Number of bytes received Throughput.

4.2.

Routing Protocols

4.2.1. RIPv212
This is the Internet standard implementation of the Bellman-Ford (a.k.a. Ford Fulkerson) routing algorithm. It is a distance vector routing algorithm utilizing UDP for control packet transmission, and its specification in default.config follows: ROUTING-PROTOCOL RIPv2 It takes no parameters.

12

http://www.ietf.org/rfc/rfc2453.txt

4.2.2. Bellman-Ford
This is a generic Bellman-Ford (a.k.a. Ford Fulkerson) routing algorithm. This algorithm is the underlying mechanism of RIP, but this protocol is not RIPv2 compliant. It is a distance vector routing algorithm utilizing UDP for control packet transmission, and its specification in default.config follows: ROUTING-PROTOCOL BELLMANFORD It takes no parameters. Bellman-Ford takes the following statistics: numRTBroadcast numTriggerUpdate numRTUpdate numFromUdp Total number of routing table broadcasts Total number of triggered routing table updates Total number of routing table updates Total number of routing table packets received

4.2.3. Fisheye State Routing13

Fisheye State Routing (FSR) is a link state type protocol which maintains a topology map at each node. FSR differs from the standard link state algorithm by having only neighboring nodes exchange the link state information, utilizing only time-triggered, not event-triggered link state exchanges, and using different exchange intervals for nearby versus far away nodes. To select FSR as the routing protocol in default.config, place the following entry in default.config: ROUTING-PROTOCOL FISHEYE It takes no parameters.

13

A. Iwata, C.-C. Chiang, G. Pei, M. Gerla, and T.-W. Chen, Scalable Routing Strategies for Ad-hoc Wireless Networks in IEEE Journal on Selected Areas in Communications, Special Issue on Ad-Hoc Networks, August 1999. http://www.cs.ucla.edu/NRL/wireless/PAPER/jsac99.ps.gz

4.2.4. BGPv414
BGPv4 (Border Gateway Protocol version 4) is a routing protocol used to route packets between autonomous systems. If you are modeling an existing network which spans autonomous systems or a very large one that you wish to partition based on administrative control, activating and configuring BGPv4 can give you a more accurate picture of expected network operation. To select BGPv4 as the exterior gateway routing protocol in default.config, place the following entry in default.config: EXTERIOR-GATEWAY-PROTOCOL BGPv4 It takes many parameters.

4.2.4.1. BGP Global Parameters

The following parameters are specified in the experiment.config file directly. Other parameters can be specified for individual BGP routers in a separate configuration file (See Section 4.2.4.2). The amount of time a speaker will wait to listen for activities from a peer is specified using the following parameter in QualNet Time Format (See Section 2.3.3). If omitted, this parameter will default to a value of 90 seconds. BGP-HOLD-TIME-INTERVAL 90S The hold time in active state is specified using the following parameter in QualNet Time Format (See Section 2.3.3). default to a value of 4 minutes. BGP-LARGE-HOLD-TIME-INTERVAL 4M The interval between two subsequent update messages for external peers is specified using the following parameter in QualNet Time Format (See Section 2.3.3). If omitted, this parameter will default to a value of 30 seconds.
14

If omitted, this parameter will

http://www.ietf.org/rfc/rfc1771.txt

BGP-MIN-RT-ADVERTISEMENT-INTERVAL 30S The interval between two subsequent update messages for internal peers is specified using the following parameter in QualNet Time Format (See Section 2.3.3). If omitted, this parameter will default to a value of 15 seconds. BGP-MIN-AS-ORIGINATION-INTERVAL 15S The interval between two successive keep alive message is specified using the following parameter in QualNet Time Format (See Section 2.3.3). If omitted, this parameter will default to a value of 30 seconds. BGP-KEEPALIVE-INTERVAL 30S The amount of time to wait before re-opening a TCP connection is specified using the following parameter in QualNet Time Format (See Section 2.3.3). If omitted, this parameter will default to a value of 120 seconds. BGP-CONNECT-RETRY-INTERVAL 120S The amount of time to wait to determine if a neighbor is no longer reachable is specified using the following parameter in QualNet Time Format (See Section 2.3.3). If omitted, this parameter will default to a value of 15 seconds. BGP-ROUTE-WAITING-INTERVAL 15S The remaining parameters for BGPv4 involve the configuration of individual BGP routers. specified below. BGP-CONFIG-FILE ./default.bgp These parameters are read from the BGP-CONFIG-FILE

4.2.4.2. BGP Config File Parameters

The following parameters are specified in the BGP-CONFIG-FILE. The first step is to associate a BGP Router (Speaker) with a particular Autonomous System (AS) ID. The following ROUTER declaration associates the nodeId of the Speaker to the AS ID: ROUTER <nodeId> BGP <AS ID> The AS ID should be a positive (greater than 0) integer that uniquely identifies this Autonomous System. The next step is to configure the BGP-router, using some or all of the following configuration parameters. These parameters should immediately follow the ROUTER statement: The NETWORK parameter specifies the network address that the BGP Speaker will advertise. A BGP speaker may advertise more than one network addresses by specifying multiple NETWORK statements in this section. NETWORK <ip_address> The NEIGHBOR parameter specifies a neighbor connection of the BGP speaker. One must specify at least one neighbor connection, but need not specify all of them, or else the BGP connection will not be established. More than one neighbor connection can be specified using multiple NEIGHBOR statements in this section. REMOTE-AS refers to the remote Autonomous System ID.

NEIGHBOR <neighbor_ip_addr> REMOTE-AS <remote_as_id> The NEIGHBOR parameter can also specify the BGP Weight of a neighboring BGP speaker as follows: NEIGHBOR <neighbor_ip_address> WEIGHT <weight_value> By default, BGP synchronizes routes with the Interior Gateway Protocol (IGP). This is the Routing Protocol running inside the Autonomous System that the BGP Router belongs to. By adding the following statement, the user can disable this route synchronization: NO SYNCHRONIZATION The following statement indicates the local preference for internal paths as an unsigned integer. DEFAULT LOCAL-PREFERENCE <unsigned_integer> The following statement specifies the multi-exit discriminator (MED). DEFAULT-METRIC <unsigned integer> The following statement disables IGP route injection into BGP. By default, the IGP does inject routes into BGP. NO-ADVERTISEMENT-FROM-IGP

The following statement sets the probe time interval if IGP route injection into BGP is active: BGP-PROBE-IGP-INTERVAL <time>

4.2.4.3. Example BGP Config File

The following specifies that node 4 is a BGP speaker in AS 1. Node 4 is advertising N8-2.0 to neighbor BGP speaker 1.2, which is located in AS 2. ROUTER 4 BGP 1 NETWORK N8-2.0 NEIGHBOR 1.2 REMOTE-AS 2 Here, it specifies that node 5 is a BGP speaker in AS 2. Node 5 is advertising N8-3.0 to neighbor BGP speaker 1.1, which is located in AS 1. ROUTER 5 BGP 2 NETWORK N8-3.0 NEIGHBOR 1.1 REMOTE-AS 1

5. Transport Protocols
5.1. TCP

QualNets TCP is converted from the FreeBSD 2.2.215 source code implementation for TCP. The differences between the QualNet code and the FreeBSD code are improvements for simulation performance, configurability via QualNet configuration files and GUI, interface code to the simulator, and modifications to offer additional flavors of TCP. FreeBSDs TCP variant is known as TCP Lite. Applications that require TCP include FTP and Telnet. TCP statistics collected are part of the port from FreeBSD 2.2.2 tcps_sndtotal tcps_sndpack tcps_sndbyte tcps_sndrexmitpack tcps_sndrexmitbyte tcps_sndacks tcps_sndprobe tcps_sndurg tcps_sndwinup tcps_sndctrl tcps_rcvtotal tcps_rcvpack tcps_rcvbyte tcps_rcvbadsum tcps_rcvbadoff tcps_rcvshort tcps_rcvctrl tcps_rcvduppack tcps_rcvdupbyte tcps_rcvpartduppack tcps_rcvpartdupbyte
15

Total number of packets sent Total number of data packets sent, excluding retransmissions and probes Total number of data bytes sent, excluding retransmissions and probes Total number of retransmitted packets Total number of retransmitted bytes Total number of ACK only packets sent Total number of window probes sent Total number of packets sent with URG Total number of window update packet sent Total number of control (SYN|FIN|RST) packets sent Total number of packets received Total number of data packets received, excluding retransmissions and probes Total number of data bytes received, excluding retransmissions and probes Total number of packets dropped due to checksum errors Total number of packets dropped due to bad offset Total number of packets dropped due to being too short Total number of control packets received Total number of duplicate packets received Total number of bytes received in duplicate packets Total number of packets received with partial duplication Total number of bytes received in packets with partial

http://www.freebsd.org/

tcps_rcvoopack tcps_rcvoobyte tcps_rcvpackafterwin tcps_rcvbyteafterwin tcps_rcvafterclose tcps_rcvwinprobe tcps_rcvdupack tcps_rcvackpack tcps_rcvackbyte tcps_rcvacktoomuch tcps_rcvwinupd tcps_pawsdrop tcps_predack tcps_preddat tcps_persistdrop tcps_badsyn

duplication Total number of out-of-order packets received Total number of bytes received in out-of-order packets Total number of packets received after the window Total number of bytes received after the window Total number of packets dropped due to already closed TCP session Total number of window probe packets received Total number of duplicate ACK packets received Total number of in-sequence ACK packets received Total number of bytes acknowledged by ACK packets received Total number of erroneous ACKs received for unsent data Total number of window update packets received Total number of segments dropped due to PAWS Total number of times the header predicts ok for ACKs Total number of times the header predicts ok for data packets Total number of timeouts in persist state Total number of bogus SYN packets, e.g. premature ACKs

The QualNet TCP models include many variants, which are described in the following sections:

5.1.1. TCP Tahoe

TCP Tahoe includes the following features: Slow Start, Congestion Avoidance, and Fast Retransmit.

To select TCP Tahoe, place the following entry in the default.config: TCP TAHOE You can also modify the TCP parameters (Section 5.1.6).

5.1.2. TCP Reno

TCP Reno includes the following features: Slow Start, Congestion Avoidance, Fast Retransmit, and Fast Recovery.

To select TCP Reno, place the following entry in the default.config: TCP RENO You can also modify the TCP parameters (Section 5.1.6).

5.1.3. TCP Lite

TCP Lite is the default flavor of TCP for QualNet. TCP Lite includes the following features: Slow Start, Congestion Avoidance, and Fast Retransmit, Fast Recovery, Big Window & Protection Against Wrapped Sequence Numbers option (rfc 132316).

16

http://www.ietf.org/rfc/rfc1323.txt

To select TCP Lite, either ensure that no other TCP specification exists, or place the following entry in the default.config: TCP LITE You can also modify the TCP parameters (Section 5.1.6).

5.1.4. TCP NewReno

TCP Reno includes the following features: Slow Start, Congestion Avoidance, Fast Retransmit, and Fast Recovery with modifications.

To select TCP Reno, place the following entry in the default.config: TCP NEWRENO You can also modify the TCP parameters (Section 5.1.6).

5.1.5. TCP SACK

TCP SACK includes the following features: Slow Start, Congestion Avoidance, Fast Retransmit, Fast Recovery, and Selective Acknowledgement.

To select TCP SACK, place the following entry in the default.config: TCP SACK You can also modify the TCP parameters (Section 5.1.6).

5.1.6. TCP Parameters

There are several TCP parameters that you can specify via the QualNet configuration file. These are modified in real systems by using compiler directives to enable sections of code, and then recompiling the kernel. In QualNet, you can change them by editing the configuration file.

5.1.6.1. Delay ACKs Option

By default, ACKs for data segment packets are delayed for a certain period of time, in order to reduce the number of ACKs transmitted. Changing this parameter to NO causes ACKs to be sent immediately. TCP-DELAY-ACKS NO

5.1.6.2. Nagle Algorithm Option

By default, a source of TCP traffic will coalesce small outgoing data packets into fewer and larger outgoing packets. This behavior is called the Nagle algorithm. In order to send small outgoing packets individually, disable this algorithm by changing this option to NO. TCP-USE-NAGLE-ALGORITHM NO

5.1.6.3. Keep-alive Probes Option

By default, keep-alive probes are employed by TCP. To turn off these probes, change this option to NO. TCP-USE-KEEPALIVE-PROBES NO

5.1.6.4. TCP Header Push Bit Option

By default, the source of TCP traffic sets a push field requesting immediate ACK for a given packet, except for FIN segments. By setting this option to NO, the push field is not set. TCP-USE-PUSH # TCP-USE-PUSH YES NO

5.1.6.5. Maximum Segment Size

By default, the maximum segment size is 512 bytes. To change this value, set this option as desired. TCP-MSS 512

5.1.6.6. RFC 1323 option

The RFC 1323 option sends window scale and timestamps in the TCP options header. This option cannot be selected for TCP Reno or TCP Tahoe. When enabled, the RFC 1323 option allows the reported window size to reach a maximum 1,073,725,440 bytes. This option can be enabled by placing the following entry in default.config: TCP-USE-RFC1323 YES

5.1.6.7. Send Buffer Size

By default, the TCP send buffer is 16384 bytes. The Send Buffer Size and Receive Buffer Size (Section 5.1.6.8) provide an upper bound on the advertised window (you cannot send a window of data which is larger than the amount of data you can store at once in TCP). Without RFC 1323 (Section 5.1.6.6), the maximum advertised window is 65536, so there is little need to have a send buffer size larger than this value without the RFC 1323 option. To change this value, specify the desired size in bytes in the option below. TCP-SEND-BUFFER 16384

5.1.6.8. Receive Buffer Size

By default, the TCP receive buffer is 16384 bytes. The Send Buffer Size (5.1.6.7) and Receive Buffer Size provide an upper bound on the advertised window (you cannot send a window of data which is larger than the amount of data you can store at once in TCP). Without RFC 1323 (Section 5.1.6.6), the maximum advertised window is 65536, so there is little need to have a receive buffer size larger than this value without the RFC 1323 option. To change this value, specify the desired size in bytes in the option below. TCP-RECEIVE-BUFFER 16384

5.1.7. TCP ECN

ECN (Explicit Congestion Notification)17 marks the IP header, instead of dropping packets, when network queues report congestion. ECN requires IP-QUEUETYPE to be RED, RIO, or WRED. Furthermore, the source and destination nodes must be ECN enabled; intermediate routes need not be ECN enabled. To enable ECN, place the following entry in the default.config: ECN YES

5.2.

UDP

The User Datagram Protocol (UDP) is a simple, low-overhead, packet-switched transport protocol that assumes that the Internet Protocol (IP) is the underlying network protocol. Applications that require UDP include CBR or routing protocols such as RIP, UDP. UDP collects the following statistics: numPktFromApp numPktToApp Total Number of packets received from applications Total Number of packets sent to application layer

17

http://www.ietf.org/rfc/rfc2481.txt

6. Network Protocols
6.1. IPv4
packet-

The Internet Protocol is designed for use in interconnected systems of switched computer communication networks.

The Internet Protocol provides for

transmitting blocks of data called datagrams from sources to destinations, where sources and destinations are hosts identified by fixed length addresses. The Internet Protocol also provides for fragmentation and reassembly of long datagrams, if necessary, for transmission through "small packet" networks. Selection of this protocol is currently mandatory, and is achieved by placing the following entry in the default.config: NETWORK-PROTOCOL It takes no parameters. IP statistics collected are taken from the standard MIB statistics, and listed below: ipInReceives ipInHdrErrors ipInForwardDatagrams ipInDelivers ipOutRequests ipOutDiscards ipOutNoRoutes ipReasmReqds ipReasmOKs ipReasmFails IpFragOKs Packets received from the MAC protocol Packets dropped due to header errors Packets forwarded by this intermediate node towards its destination Packets sent to the applicable transport layer protocol (TCP, UDP) Packets sent by IP to the MAC protocol Packets lost to IP queue overflow Packets dropped due to unreachable destination Fragments of packets received Successful reassembly of fragments into a data packet Unsuccessful reassembly of fragments into a data packet Successful receptions of fragments IP

6.1.1. Static Routes

QualNet allows users to specify static routes that take precedence over those discovered by any routing protocols. These routes remain fixed throughout the simulation, even if network conditions (mobility, link failures) render the route useless, causing packet drops. There are also no route acquisition related overheads with static routes, such as packet transmissions, receptions, computational overhead for producing routes, or route acquisition delays that would normally be present using a traditional routing model. If no routing protocol is running on the node, and there is no static or default route to a given destination, corresponding packets will be dropped. To specify that static routes are present for some or all nodes, place the following entries in default.config: STATIC-ROUTE STATIC-ROUTE-FILE YES default.routes-static

The static routing model requires that STATIC-ROUTE-FILE refer to a text file (in the prior example, called "default.routes-static") that contains the following entries, each on its own line: <source nodeId> <destination IP/Subnet Address> <nextHop IP Address> In the following example, the route for node 1 to the networks 0.0.2.0 and 0.0.3.0 use node 1s outgoing interface identified by the IP Address 0.0.1.2. (See QualNet Subnet Shorthand in Section 2.3.6.1 for more information on how N2-2.0 translates to the 0.0.2.0 network) 1 1 N2-2.0 N2-3.0 1.2 1.2

6.1.2. Default Routes

QualNet allows users to specify default routes that will be used by nodes who have no other route to the destination, either via static route assignment, routing protocol discovery, or forwarding table lookup. There are also no route acquisition related overheads with default routes, such as packet transmissions, receptions, computational overhead for producing routes, or route acquisition delays that would normally be present using a traditional routing model. If no routing protocol is running on the node, and there is no static or default route to a given destination, corresponding packets will be dropped. To specify that default routes are present for some or all nodes, place the following entries in default.config: DEFAULT-ROUTE DEFAULT-ROUTE-FILE YES default.routes-default

The default routing model requires that DEFAULT-ROUTE-FILE refer to a text file (in the prior example, called "default.routes-default") that contains the following entries, each on its own line: <source nodeId> <destination IP/Subnet Address> <nextHop IP Address> In the following example, the default route for node 1 to the networks 0.0.2.0 and 0.0.3.0 use node 1s outgoing interface identified by the IP Address 0.0.1.2. translates to the 0.0.2.0 network) 1 1 N2-2.0 N2-3.0 1.2 1.2 (See QualNet Subnet Shorthand in Section 2.3.6.1 for more information on how N2-2.0

6.2.

Network Queue Scheduler

For each network interface in QualNet, IP maintains a set of priority queues. These queues can represent the greater priority that real-time or control (routing-protocol, ACKs, etc) packets can have over the normal IP best-effort datagrams. They can also represent the various flows that Quality of Service scheduling disciplines distinguish between, using a round robin or other scheduling discipline. The Network Queue Scheduler is the scheduling discipline, implemented as a set of functions that IP uses to enqueue and dequeue packets from its various priority queues for a given network interface. The number of these priority queues is determined by the parameter IP-QUEUE-NUM-PRIORITIES. Given that generic QualNet traffic generators and protocols generate three different priorities of traffic (CONTROL, REAL_TIME, NON_REAL_TIME), the default value of 3 is useful here. Defining less than three would cause different traffic priorities to share the same queue. Quality of Service applications can either add or remove priority queues during simulation execution as well. Specification of a value for this parameter is currently mandatory, and is achieved by placing the following entry in the default.config: IP-QUEUE-NUM-PRIORITIES 3 It can be specified using node-specific (See Section 2.3.8) or network-specific parameterization (See Section 2.3.7).

In addition to the IP-QUEUE-NUM-PRIORITIES parameter, you must also specify the size of these priority queues. This is accomplished by setting the value of the IP-QUEUE-PRIORITY-QUEUE-SIZE parameter. This value is specified in bytes. Once the buffer space is filled with data packets whose aggregate size exceeds this value, the priority queue must drop subsequent packets. default.config: IP-QUEUE-PRIORITY-QUEUE-SIZE 50000 # bytes Specification of a value for this parameter is currently mandatory, and is achieved by placing the following entry in the

It can be specified using node-specific (See Section 2.3.8) or network-specific parameterization (See Section 2.3.7).

6.2.1. Strict Priority Scheduler

The Strict Priority Scheduler is the default scheduling discipline in QualNet. It services the highest priority queue until it is empty, and then moves to the next highest priority queue, and so on. It is possible that if there is enough high priority traffic, the lower priorities could be completely frozen out. Selection of a scheduler is currently mandatory, and is achieved by placing the following entry in the default.config: IP-QUEUE-SCHEDULER STRICT-PRIORITY

It takes no parameters. It can be specified using node-specific (See Section 2.3.8) or network-specific parameterization (See Section 2.3.7).

6.2.2. Round Robin Scheduler

The Round Robin Scheduler is an alternative scheduling discipline in QualNet. It services each priority queue, starting with the highest priority queue that contains packets, services a single packet, and moves to the next lower priority queue that contains packets, servicing a single packet from each, until each queue with packets has been serviced once. It then starts the cycle over with the highest priority queue containing packets. Selection of a scheduler is currently mandatory, and is achieved by placing the following entry in the default.config: IP-QUEUE-SCHEDULER ROUND-ROBIN

It takes no parameters. It can be specified using node-specific (See Section 2.3.8) or network-specific parameterization (See Section 2.3.7).

6.2.3. Weighted Fair Queuing Scheduler

The Weighted Fair Queuing (WFQ) Scheduler is an alternative scheduling discipline in QualNet. WFQ attempts to service each priority queue based on a percentage allocation of the total outgoing bandwidth of the link. This allocation is based on a configurable weight assigned to each queue. Selection of a scheduler is currently mandatory, and is achieved by placing the following entry in the default.config: IP-QUEUE-SCHEDULER WEIGHTED-FAIR

It can be specified using node-specific (See Section 2.3.8) or network-specific parameterization (See Section 2.3.7). It requires no parameters. If no parameters are given, the weight of each queue is the ((priority value of the queue)+ 1) / (sum of all the priority_values for all the queues). Otherwise, users must specify the weight for all of the queues on that interface, such that the sum of the weights equals one, using the following parameter: QUEUE-WEIGHT[priority] # weight_between_zero_and_one

Where priority is the integer value of the priority assigned to each queue (numbered from 0num_of_priority_queues-1), and the weight is a floating point number between zero and one. This parameter can also be specified using node-specific (See Section 2.3.8) or network-specific parameterization (See Section 2.3.7).

6.2.4. Self-Clocked Fair Queuing Scheduler

The Self-Clocked Fair Queuing (SCFQ) Scheduler is an alternative scheduling discipline in QualNet. SCFQ is similar to WFQ in its attempt to service each priority queue based on a percentage allocation of the total outgoing bandwidth of the link. However, it was discovered that calculating the Finish Time (the time at which a packet would have been serviced given a hypothetical fluid server) for WFQ was complicated/difficult. SCFQ uses a simplified method of calculating the service time, based on the transmission delay of the packet, and the finish time of the packet currently being serviced. Selection of a scheduler is currently mandatory, and is achieved by placing the following entry in the default.config: IP-QUEUE-SCHEDULER SELF-CLOCKED-FAIR

It can be specified using node-specific (See Section 2.3.8) or network-specific parameterization (See Section 2.3.7). It requires no parameters. If no parameters are given, the weight of each queue is the ((priority value of the queue)+ 1) / (sum of all the priority_values for all the queues). Otherwise, users must specify the weight for all of the queues on that interface, such that the sum of the weights equals one, using the following parameter: QUEUE-WEIGHT[priority] # weight_between_zero_and_one

Where priority is the integer value of the priority assigned to each queue (numbered from 0num_of_priority_queues-1), and the weight is a floating point number between zero and one. This parameter can also be specified using node-specific (See Section 2.3.8) or network-specific parameterization (See Section 2.3.7).

6.2.5. Weighted Round Robin Scheduler

The Weighted Round Robin (WRR) Scheduler is an alternative scheduling discipline in QualNet. Weighted Round Robin also attempts to service each priority queue based on a percentage allocation of the total outgoing bandwidth of the link. However, it does not calculate a Finish Time (the time at which a packet would have been serviced given a hypothetical fluid server) for each packet, instead, it establishes a round-robin order with multiple turns for highly weighted priority queues. Selection of a scheduler is currently mandatory, and is achieved by placing the following entry in the default.config: IP-QUEUE-SCHEDULER WEIGHTED-ROUND-ROBIN

It can be specified using node-specific (See Section 2.3.8) or network-specific parameterization (See Section 2.3.7). It requires no parameters. If no parameters are given, the weight of each queue is the ((priority value of the queue)+ 1) / (sum of all the priority_values for all the queues). Otherwise, users must specify the weight for all of the queues on that interface, such that the sum of the weights equals one, using the following parameter: QUEUE-WEIGHT[priority] # weight_between_zero_and_one

Where priority is the integer value of the priority assigned to each queue (numbered from 0num_of_priority_queues-1), and the weight is a floating point number between zero and one. This parameter can also be specified using node-specific (See Section 2.3.8) or network-specific parameterization (See Section 2.3.7).

6.3.

Network Queue Disciplines

Network Queue Disciplines can be distinguished from Queue Scheduling Disciplines by the fact that they deal exclusively with the enqueue and dequeue functions of a single priority queue, rather than the choice between all of the existing priority queues. These parameters can be specified using node-specific (See Section 2.3.8) or network-specific parameterization (See Section 2.3.7). In addition, it can be specified using Instance ID Specification (See Section 2.3.9), if you wish to have different values for certain parameters, for each priority queue.

6.3.1. FIFO
FIFO queues operate on a First In, First Out basis. The FIFO queue accepts packets until it is full (the packets occupying the queue total an aggregate number of bytes that prevent the next packet from being admitted). The size of the queue is specified by the IP-QUEUE-PRIORITY-QUEUE-SIZE parameter. (See Section 6.2) At that point, all packets that arrive at the queue are dropped, until packets are dequeued, and space becomes available. To select FIFO as the Network Queue Discipline, place the following entry in default.config: IP-QUEUE-TYPE It takes no parameters. The FIFO queue model collects the following statistics, per priority queue, per node: NumPktsQueued NumPktsDequeued NumPktsDropped AvgQueueLen AvgTimeInQueue PeakTimeInQueue Number of Packets Queued Number of Packets Dequeued Number of Packets Dropped Average Queue Length in Bytes Average Time Spent By Packets in the Queue (in seconds) Longest Time Spent in Queue by a Packet (in seconds) FIFO

6.3.2. RED18
RED is an acronym for Random Early Detection18. This implementation drops packets at the current router based on drop probabilities, rather than at a subsequent congested router, if ECN (See Section 5.1.7) is off (default). If ECN is active, packets are marked instead of dropped, and the source of the TCP traffic will throttle back based on the notification. RED is a congestion avoidance algorithm that calculates average queue sizes in order to address incipient congestion. The algorithm also attempts to address global synchronization as well as maintaining fairness across data flows, without bias against bursty flows. To select RED as the Network Queue Discipline, place the following entry in default.config: IP-QUEUE-TYPE RED

It takes five parameters, which can be defined using network-specific or nodespecific parameterization. The following example illustrates a RED configuration where the maximum dropping probability is 1/50 (0.02 as specified by RED-MAXPROBABILITY). The possibility of random early drops begins when the RED queue average algorithm determines that the queue size (number of packets in the queue, not the bytes used by those packets) average is greater than or equal to RED-MINTHRESHOLD and less than RED-MAX-THRESHOLD. The RED-QUEUEWEIGHT determines the bias towards recent or historical queue lengths in calculating the average queue size. The RED-SMALL-PACKET-TRANSMISSION-TIME is the time it would take to transmit a typical small packet, and this value is used to estimate the queue average during idle periods (when the queue is completely empty). RED-MIN-THRESHOLD RED-MAX-THRESHOLD RED-MAX-PROBABILITY RED-QUEUE-WEIGHT RED-SMALL-PACKET-TRANSMISSION-TIME
18

5 15 0.02 0.002 10MS

Sally Floyd and Van Jacobson, "Random Early Detection For Congestion Avoidance", IEEE/ACM Transactions on Networking, August 1993. http://www.aciri.org/floyd/papers/red/red.html

Figure 3 below is a mapping between these parameters and the variable and parameter names given for the Detailed algorithm for RED gateways18. QualNet Configuration File Parameter RED-MIN-THRESHOLD RED-MAX-THRESHOLD RED-MAX-PROBABILITY RED-QUEUE-WEIGHT RED-SMALL-PACKET-TRANSMISSION-TIME Detailed algorithm for RED

minth maxth maxp wq s from Section 11: Implementation

Figure 3: Mapping to Detailed Algorithm for RED Gateways

RED queues collect the following statistics, per priority queue, per node: NumPktsQueued NumPktsDequeued NumPktsDropped AvgQueueLen AvgTimeInQueue PeakTimeInQueue PeakQueueSize Number of Packets Queued Number of Packets Dequeued Number of Packets Dropped Average Queue Length in Bytes Average Time Spent By Packets in the Queue (in seconds) Longest Time Spent in Queue by a Packet (in seconds) Largest number of bytes stored in the queue at any time (the upward bound on this stat would be the queue size itself)

6.3.3. RIO19
RIO is a queue discipline that implements two instances of the RED algorithm with different parameter settings. The first instance uses a set of parameters to specify the marking/dropping behavior of packets which are marked as being in-profile. Inprofile packets conform to existing agreements between networks for level of service, i.e. fall within certain bandwidth, burstiness, and delay characteristics. Out-profile packets exceed the existing agreements for level of service between networks, and the dropping/marking behavior for these ill-behaved packets is specified by the set of parameters for the second instance of the RED algorithm. This latter set of parameters tends to specify more aggressive marking/dropping probabilities and thresholds. To select RIO as the Network Queue Discipline, place the following entry in default.config: IP-QUEUE-TYPE RIO

It takes eight parameters, which can be defined using network-specific or nodespecific parameterization. The following example illustrates a RIO configuration where the maximum dropping probability for in-profile packets is 1/50 (0.02 as specified by RIO-IN-MAX-PROBABILITY). The possibility of random early drops for in-profile packets begins when the RED queue average algorithm determines that the queue size (number of packets in the queue, not the bytes used by those packets) average is greater than or equal to RIO-IN-MIN-THRESHOLD and less than RIO-IN-MAXTHRESHOLD. The thresholds and probabilities for the out-profile packets are RIOOUT-MAX-PROBABILITY, RIO-OUT-MIN-THRESHOLD, and RIO-OUTMAX-THRESHOLD. The last two parameters are shared with RED (Section 6.3.2). The RED-QUEUE-WEIGHT determines the bias towards recent or historical queue lengths in calculating the average queue size. The RED-SMALL-PACKETTRANSMISSION-TIME is the time it would take to transmit a typical small packet,
19

David D. Clark and Wenjia Fang, Explicit Allocation of Best Effort Packet Delivery Service, ACM Transactions on Networking, August, 1998. http://diffserv.lcs.mit.edu/Papers/exp-alloc-ddc-wf.pdf

and this value is used to estimate the queue average during idle periods (when the queue is completely empty). RIO-IN-MIN-THRESHOLD RIO-IN-MAX-THRESHOLD RIO-IN-MAX-PROBABILITY RIO-OUT-MIN-THRESHOLD RIO-OUT-MAX-THRESHOLD RIO-OUT-MAX-PROBABILITY 10 20 0.02 5 10 0.1

RED-QUEUE-WEIGHT 0.002 RED-SMALL-PACKET-TRANSMISSION-TIME 10MS RIO queues collect the following statistics, per priority queue, per node: NumPktsQueued NumPktsDequeued NumPktsDropped AvgQueueLen AvgTimeInQueue PeakTimeInQueue PeakQueueSize Number of Packets Queued Number of Packets Dequeued Number of Packets Dropped Average Queue Length in Bytes Average Time Spent By Packets in the Queue (in seconds) Longest Time Spent in Queue by a Packet (in seconds) Largest number of bytes stored in the queue at any time (the upward bound on this stat would be the queue size itself)

6.3.4.

WRED20

WRED is a queue discipline that implements three instances of the RED algorithm with different parameter settings. The first instance uses a set of parameters to specify the marking/dropping behavior of packets which are marked as being within / below the committed target rate. The committed target rate is an agreement between networks for level of service. These packets are considered to be green, and the dropping/marking behavior is governed by the green instance of RED parameters. Yellow packets fall between the committed target rate, and a higher peak rate, and the

20

http://www.ieng.com/univercd/cc/td/doc/product/software/ios112/ios112p/gsr/wred_gs.htm

dropping/marking behavior is governed by the yellow instance of RED parameters. Red packets exceed the peak rate, and the dropping/marking behavior for these illbehaved packets is specified by the set of parameters for the red instance of RED parameters. The yellow and red sets of parameters tend to specify increasingly aggressive marking/dropping probabilities and thresholds. To select WRED as the Network Queue Discipline, place the following entry in default.config: IP-QUEUE-TYPE WRED

It takes eleven parameters, which can be defined using network-specific or nodespecific parameterization. The following example illustrates a WRED configuration where the maximum dropping probability for green packets is 1/50 (0.02 as specified by WRED-GREEN-MAX-PROBABILITY). The possibility of random early drops for green packets begins when the RED queue average algorithm determines that the queue size (number of packets in the queue, not the bytes used by those packets) average is greater than or equal to WRED-GREN-MIN-THRESHOLD and less than WRED-GREEN-MAX-THRESHOLD. yellow packets are The thresholds and probabilities for the WREDWRED-YELLOW-MAX-PROBABILITY,

YELLOW-MIN-THRESHOLD, and WRED-YELLOW-MAX-THRESHOLD. The thresholds and probabilities for the red packets are WRED-RED-MAXPROBABILITY, WRED-RED-MIN-THRESHOLD, and WRED-RED-MAXTHRESHOLD. The last two parameters are shared with RED (Section 6.3.2). The RED-QUEUE-WEIGHT determines the bias towards recent or historical queue lengths in calculating the average queue size. The RED-SMALL-PACKETTRANSMISSION-TIME" is the time it would take to transmit a typical small packet, and this value is used to estimate the queue average during idle periods (when the queue is completely empty).

WRED-GREEN-MIN-THRESHOLD WRED-GREEN-MAX-THRESHOLD WRED-GREEN-MAX-PROBABILITY WRED-YELLOW-MIN-THRESHOLD WRED-YELLOW-MAX-THRESHOLD WRED-YELLOW-MAX-PROBABILITY WRED-RED-MIN-THRESHOLD WRED-RED-MAX-THRESHOLD WRED-RED-MAX-PROBABILITY

12 20 0.02 8 13 0.1 5 10 0.2

RED-QUEUE-WEIGHT 0.002 RED-SMALL-PACKET-TRANSMISSION-TIME 10MS WRED queues collect the following statistics, per priority queue, per node: NumPktsQueued NumPktsDequeued NumPktsDropped AvgQueueLen AvgTimeInQueue PeakTimeInQueue PeakQueueSize Number of Packets Queued Number of Packets Dequeued Number of Packets Dropped Average Queue Length in Bytes Average Time Spent By Packets in the Queue (in seconds) Longest Time Spent in Queue by a Packet (in seconds) Largest number of bytes stored in the queue at any time (the upward bound on this stat would be the queue size itself)

6.4.

Routing Protocols

6.4.1. OSPFv221
OSPF is a link-state routing protocol. It is designed for intra-Autonomous System Routing, and requires that each OSPF router maintain a database describing the Autonomous System's topology. From this database, a routing table is calculated by constructing a shortest-path tree. To select OSPF as the routing protocol in default.config, place the following entry in default.config: ROUTING-PROTOCOL It takes no parameters. OSPFv2 collects the following statistics: numHelloPktSent numHelloPktRecvd numLSDOrig numLSDRecvd numLSROrig numLSRRecvd numLSUOrig numLSURecvd numLSAOrig numLSARecvd Total number of Hello packets sent Total number of Hello packets received Total number of Link State Description packets originated Total number of Link State Description packets received Total number of Link State Request packets originated Total number of Link State Request packets received Total number of Link State Update packets originated Total number of Link State Update packets received Total number of Link State ACK packets originated Total number of Link State ACK packets received OSPFv2

21

http://www.ietf.org/rfc/rfc2328.txt

6.4.2. AODV22
The Ad-Hoc On Demand Distance Vector (AODV) routing algorithm is a routing protocol designed for ad-hoc mobile networks. AODV is an on-demand algorithm To select capable of both unicast and multicast routing. This implementation of AODV followed the specification of AODV Internet Draft draft-ietf-manet-aodv-03.txt. default.config: ROUTING-PROTOCOL AODV It takes no parameters. AODV as the routing protocol in default.config, place the following entry in

6.4.3. DSR23
Dynamic Source Routing (DSR) is an on-demand routing protocol that builds routes only by flooding ROUTE REQUEST packets if a sender wishes to send data to a destination with no known route, accumulating node IDs in its header, and returning ROUTE REPLY packets from the destination to the source via the recorded reverse route. In addition to the on-demand algorithm, DSR implements a set of optimizations to attempt to route packets more efficiently, and reduce the control overhead. To select DSR as the routing protocol in default.config, place the following entry in default.config: ROUTING-PROTOCOL DSR It takes no parameters.

22 23

http://alpha.ece.ucsb.edu/~eroyer/aodv.html draft-ietf-manet-dsr-03.txt, Josh Broch, David B. Johnson, and David A. Maltz, October 22, 1999. http://www.monarch.cs.cmu.edu/internet-drafts/draft-ietf-manet-dsr-03.txt

6.4.4. LAR124
Location-Aided Routing (LAR) is an on-demand routing protocol which exploits location information. It is similar to DSR, but with the additional requirement of GPS information. In scheme 1 (implemented), the source defines a circular area in which the destination may be located, determined by the following information: (a) the destination location known to the source; (b) the time instant when the destination was located at that position; and (c) the average moving speed of the destination. The smallest rectangular area that includes this circle and the source is the request zone. This information is attached to a ROUTE REQUEST by the source and only nodes inside the request zone propagate the packet. If no ROUTE REPLY is received within the timeout period, the source retransmits a ROUTE REQUEST via pure flooding. To select LAR1 as the routing protocol in default.config, place the following entry in default.config: ROUTING-PROTOCOL LAR1 It takes no parameters.

6.4.5. STAR25
Source Tree Adaptive Routing (STAR) is a partial link state, table driven protocol, in which the routers exchange only the changes in their own shortest path trees with their neighbors. STAR operates in either the Least Overhead Routing Approach (LORA) and Optimum Routing Approach (ORA) modes. In LORA mode, STAR attempts to provide viable, if not necessarily optimal (according to performance, delay matrics) paths to each destination, while in ORA mode, STAR attempts to provide optimal paths based on the chosen metric. To select FSR as the routing protocol in default.config, place the following entry in default.config:

24

Youngbae Ko and N. H. Vaidya, Location-Aided Routing (LAR) Mobile Ad Hoc Networks, MOBICOM'98, October 1998, Dallas. http://www.cs.tamu.edu/faculty/vaidya/papers/mobilecomputing/mobicom98.pdf 25 J.J. Garcia-Luna-Aceves and M. Spohn, "Source-Tree Routing in Wireless Networks", Proc. IEEE ICNP 99: 7th International Conference on Network Protocols, Toronto, Canada, October 31--November 3, 1999. http://www.cse.ucsc.edu/research/ccrg/publications/spohn.icnp99.pdf

ROUTING-PROTOCOL STAR It takes three parameters, STAR-ROUTING-MODE, NEIGHBOR-

PROTOCOL-SEND-FREQUENCY, and NEIGHBOR-PROTOCOL-ENTRY-TTL. The latter two parameters concern the rate at which the neighbor protocol broadcasts hello packets to all neighbors within range, and how long the entries for neighbors remain valid after hearing a hello message. We recommend that the TTL be longer than the SEND-FREQUENCY to be sure that the neighbor protocol does not provide erroneous neighbor up and neighbor down messages to STAR. STAR-ROUTING-MODE LORA # STAR-ROUTING-MODE ORA NEIGHBOR-PROTOCOL-SEND-FREQUENCY 2S NEIGHBOR-PROTOCOL-ENTRY-TTL 4S

6.5.

Multicast Routing Protocols

Multicast routing protocols address the problem of delivering messages from senders to a set of interested receivers, without individually sending duplicate messages from the sender to each receiver. This set of interested receivers subscribes to one or more multicast groups of interest, and the senders address their messages to the multicast group address. The multicast routing protocol handles the delivery of these messages to the multicast group members.

6.5.1. Multicast Group Membership Configuration

The Multicast Group Membership File contains the join and leave times for all nodes and groups. At the join time, the multicast routing protocol is notified that this node is interested in receiving multicast packets addressed to the groups multicast address. At the leave time, the multicast routing protocol is notified that this node is no longer interested in receiving multicast packets addressed to the groups multicast address.

In order to specify which Multicast Group Membership File to use in a given experiment, place the following entry in default.config: MULTICAST-GROUP-FILE ./default.member

This parameter specifies the filename in either relative or absolute path. The Multicast Group Membership File takes the following format: <nodeId> <group IP address to join> <join time> <leave time>

6.5.2. ODMRP26
The On-Demand Multicast Routing Protocol (ODMRP) is a wireless multicast routing protocol. It is designed for single subnet, wireless ad-hoc multicast routing, and operates similarly to an on-demand unicast wireless routing protocol. ODMRP is a mesh-based, rather than a conventional tree-based, multicast scheme and uses a forwarding group concept (only a subset of nodes forwards the multicast packets via scoped flooding). It applies on-demand procedures to dynamically build routes and uses soft state to maintain multicast group membership. To select ODMRP as the multicast routing protocol in default.config, place the following two entries in default.config: MULTICAST-PROTOCOL MULTICAST-GROUP-FILE It takes no parameters. ODMRP ./default.member

See Section 6.5.1 for more information about the

MULTICAST-GROUP-FILE parameter.

26

http://www.cs.ucla.edu/NRL/wireless/PAPER/draft-ietf-manet-odmrp-02.txt

ODMRP collects the following statistics: numQueryTxed numReplySent numAckSent numDataTxed numDataSent numDataReceived Number of Join Query (with piggybacked data) packets sent Number of Join Reply packets sent Number of ACK packets sent Total Number of ODMRP data packets sent or relayed Number of data packets sent as the source of the data Number of data packets received as the destination of the data

6.5.3. DVMRP27
The Distance Vector Multicast Routing Protocol (DVMRP) is a multicast routing protocol. It is designed for traditional wired network multicast routing, and operates similarly to a distance vector routing protocol like RIPv2. DVMRP is a tree-based, multicast scheme that utilizes Reverse Path Multicasting (RPM)28. To select DVMRP as the multicast routing protocol in default.config, place the following three entries in default.config: MULTICAST-PROTOCOL DVMRP MULTICAST-GROUP-FILE ./default.member GROUP-MANAGEMENT-PROTOCOL IGMP It takes no parameters. See Section 6.5.1 for more information about the GROUP-MANAGEMENT-PROTOCOL

MULTICAST-GROUP-FILE parameter. DVMRP operation.

IGMP activates IGMP (Internet Group Management Protocol), which is necessary for

27 28

http://www.ietf.org/internet-drafts/draft-ietf-idmr-dvmrp-v3-10.txt Deering, S., Cheriton, D., "Multicast Routing in Datagram Internetworks and Extended LANs", ACM Transactions on Computer Systems, Vol. 8, No. 2, May 1990, pp. 85-110.

DVMRP collects the following statistics: totalPacketSent totalPacketReceive probePacketSent probePacketReceive routingUpdateSent routingUpdateReceive numTriggerUpdate pruneSent pruneReceive graftSent graftReceive graftAckSent graftAckReceive numOfDataPacketOriginated numOfDataPacketForward numOfDataPacketDiscard Number of packets sent Number of packets received Number of Probe packets sent Number of Probe packets received Routing Updates sent Routing Updates received Triggered Updates sent Prunes sent Prunes received Grafts sent Grafts received Graft ACKs sent Graft ACKs received Multicast packets sent as data source Multicast data packets forwarded Multicast data packets discarded

6.5.4. MOSPF29
The Multicast Extensions to OSPF (MOSPF) create a multicast routing protocol by extending OSPFv2. These extensions are designed for traditional wired network multicast routing, and operate on top of the link state routing algorithm of OSPFv2. MOSPF is a pruned tree-based, multicast scheme that takes advantage of commonality of paths from source to destinations. To select MOSPF as the multicast routing protocol in default.config, place the following two entries in default.config: MULTICAST-PROTOCOL MULTICAST-GROUP-FILE It takes no parameters. MOSPF ./default.member

See Section 6.5.1 for more information about the

MULTICAST-GROUP-FILE parameter.

29

http://www.ietf.org/rfc/rfc1584.txt

MOSPF collects the following statistics: numGroupMembershipLSAGenerated numGroupJoin numGroupLeave numOfMulticastPacketGenerated numOfMulticastPacketReceived numOfMulticastPacketDiscard numOfMulticastPacketForwarded Group Membership LSAs sent Group Joins Group Leaves Multicast packets sent as data source Multicast Packets received Multicast data packets discarded Multicast Packets forwarded

6.6.

Quality of Service (QoS) Routing Protocols

Quality of Service (QoS) routing protocols address the path selection process problem of providing bandwidth and delay guarantees to QoS flows. QoS routing protocols handle the unreserved resource advertisements, path calculation, and possibly resource reservation issues of providing QoS services.

6.6.1. QOSPF30
The Quality Of Service Path First Routing (QOSPF) protocol is a set of extensions to OSPFv2 that address QoS flow support. This includes the acquisition of information needed to compute QoS paths, the selection of appropriate paths to meet the QoS requirements of a flow, and the maintenance of these paths. To select QOSPF as the QoS routing protocol in default.config, place the following two entries in default.config:
QUALITY-OF-SERVICE Q-OSPF QOSPF-COMPUTATION-ALGORITHM EXTENDED_BREADTH_FIRST_SEARCH_SINGLE_PATH

It takes two parameters: QOSPF-FLOODING-INTERVAL 2S QUEUEING-DELAY-FOR-QOS-PATH-CALCULATION YES # QUEUEING-DELAY-FOR-QOS-PATH-CALCULATION NO

30

http://www.ietf.org/rfc/rfc2676.txt

The QOSPF-FLOODING-INTERVAL parameter specifies the interval for flooding of Q-OSPF Link State Advertisements (LSAs). The default is two seconds. The QUEUEING-DELAY-FOR-QOS-PATH-CALCULATION parameter specifies whether or not to include queue delays in the path calculation and LSAs. QOSPF collects the following statistics: numActiveConnection numRejectedConnection linkBandwidth bandwidthUtilization Number of Active Connections Number of Rejected Connections Link Bandwidth Utilization of Bandwidth

7. MAC Protocols
7.1. IEEE 802.11-1997 DCF

IEEE 802.11-1997 is a wireless LAN media access protocol. The Distributed Coordination Function (DCF), implemented in QualNet, is a carrier-sensing protocol with acknowledgements, and provides optional channel reservation capability using Requestto-Send (RTS) / Clear-to-Send Packets, (CTS) and fragmentation. To select IEEE 802.11 DCF as the MAC protocol in default.config, place the following entry in default.config: MAC-PROTOCOL MAC802.11 It takes no parameters. The IEEE 802.11-1997 DCF model produces the following statistics: Packets received from Network Layer Protocol, i.e. IPv4 Packets Lost to Buffer Overflow Packets dropped at the MAC layer due to buffer overflow Unicast packets to channel Packets with a specific destination address transmitted on the channel Broadcast packets to channel Packets broadcast to all radios within transmission range Unicast packets from channel Packets destined for this specific radio and successfully received Broadcast packets from channel Packets destined for all radios and successfully received by this radio Retransmitted Packets due to CTS Packets rescheduled for transmission timeout due to lack of CTS response to RTS transmission Retransmitted Packets due to ACK Packets rescheduled due to lack of ACK timeout response to packet transmission Retransmitted Fragments due to Fragments of packets retransmitted due Frag ACK timeout to lack of acknowledgement of the fragment Packets drops due to excessive Packets not rescheduled after exceeding retransmission attempts the maximum number of attempts Packet drops due to excessive Packets not rescheduled after exceeding retransmission attempts of fragments the maximum number of unsuccessfully delivered fragments Packets From Network

7.2.

CSMA

Carrier Sense Multiple Access (CSMA) is a generic carrier-sensing protocol. When a radio wishes to send data, it senses the channel. If the channel is busy, it backs off for a random time period before sensing the channel again. If the channel is free, the radio transmits the packet. To select CSMA as the MAC protocol in default.config, place the following entry in default.config: MAC-PROTOCOL CSMA It takes no parameters. The CSMA model produces the following statistics: Packets From Network Packets Lost to Buffer Overflow Unicast packets to channel Broadcast packets to channel Unicast packets from channel Broadcast packets from channel Packets received from Network Layer Protocol, ie IP Packets dropped at the MAC layer due to buffer overflow Packets with a specific destination address transmitted on the channel Packets broadcast to all radios within transmission range Packets destined for this specific radio and successfully received Packets destined for all radios and successfully received by this radio

7.3.

Switched Ethernet

Switched Ethernet is an abstract store and forward single switch-based 802.3 LAN with fixed bandwidth and propagation delay. The model considers the switching fabric to be equivalent to a set of point-to-point links connecting all sources and receivers, except that when multiple sources attempt to send to a single receiver, their transmissions are serialized without additional buffering overhead. To select Switched Ethernet as the MAC protocol in default.config, place the following entry in default.config: MAC-PROTOCOL SWITCHED-ETHERNET It takes two parameters: SUBNET-DATA-RATE 10000000 SUBNET-PROPAGATION-DELAY 1MS These two parameters specify the data rate and propagation delay for the model, respectively. The Switched Ethernet model produces the following statistics: Frames Sent Frames Received Packets sent to the switch Packets received from the switch

8. Physical Layer Models

The following parameters are specific to the radio nodes in the simulation. If you are simulating an entirely wired network, you can ignore these parameters. If you are simulating a mixed network or an entirely wireless network, then you will need to accept the default values or set these parameters appropriately. The Radio Model collects the following statistics: Total Tx Signals Received Signals Above Carrier Threshold Received Signals Above Reception Threshold Received Signals Sent to MAC Energy Consumption Total number of signals broadcast from the radio Total number of signals able to trigger the carrier sense in the radio Total number of signals with sufficient power to be received by the radio Total number of signals passed to the MAC layer protocol Total amount of energy consumed by the radio in mW

8.1.

Channel Properties

Each channel in QualNet is uniquely identified by its frequency. Each channel is assumed to be orthogonal to the others (no inter-channel interference). Users can instantiate channels by initializing a propagation model for each, starting with the mandatory PROPAGATION-CHANNEL-FREQUENCY parameter (See Section 8.1.1). Users can simulate spectrum overlapping by using multiple channels.

8.1.1. Propagation Channel Frequency

The PROPAGATION-CHANNEL-FREQUENCY parameter instantiates and uniquely identifies each simulated channel. The unit is in hertz. A user can distinguish between instances of this parameter by using the Instance ID specification (See Section 2.3.9) between [], as in the example below. This example instantiates two channels, at the 2.4Ghz and 2.5Ghz frequencies: # PROPAGATION-CHANNEL-FREQUENCY[0] 2.4e9 PROPAGATION-CHANNEL-FREQUENCY[1] 2.5e9 #

8.1.2. Propagation Model

The PROPAGATION-MODEL parameter selects the propagation model used on each simulated channel. This can be either a global default, or specified per channel, using the Instance ID specification (See Section 2.3.9), as in the example in Section 8.1.1. The example below specifies that all channels use the STATISTICAL Propagation Model, which is the only model shipping with the released version of QualNet: # PROPAGATION-MODEL #

STATISTICAL

8.1.3. Propagation Limit

The following parameter defines the lower bound of signal power for consideration by the simulator as a global default, or specified per channel, using the Instance ID specification, as in the example below. Signals with powers below PROPAGATION-LIMIT (in dBm) are not delivered. This value impacts the fidelity of the model, with lower values equating to higher precision and longer simulation execution times. Higher values can improve simulation time, but this value must be smaller than the RADIO-RX-SENSITIVITY + RADIOANTENNA-GAIN for all nodes in the model, or the simulator may not deliver signals that are within a particular receivers ability to accept. This parameter is purely a simulation parameter, and does not determine the maximum distance between two radios that still allows successful transmission. See Sections 8.2.7 and 8.2.8 for the parameters that affects radio reception. The following example shows a propagation limit of 111.0 dBm on channel 0, and 121.0 dBm on channel 1. # PROPAGATION-LIMIT[0] PROPAGATION-LIMIT[1] #

-111.0 -121.0

8.1.4. Path Loss Model Selection

Path loss models compute signal attenuation according to tunable parameters and node coordinates. This parameter can be specified as a global default, or specified per channel, using the Instance ID specification (See Section 2.3.9), as in the example below. These parameters vary across the given models, which are listed below and described in more detail in their own sections: # PROPAGATION-PATHLOSS[0] PROPAGATION-PATHLOSS[1] # FREE-SPACE TWO-RAY TWO-RAY FREE-SPACE

PATHLOSSMATRIX TIREM (*)

The Friss free space model. Path loss is calculated with (path loss exponent, sigma) = (2.0, 0.0) Two ray model. It uses the free space path loss (2.0, 0.0) for near sight, and plane earth path loss (4.0, 0.0) for far sight. This model considers ground reflection on flat earth. Three-dimensional matrix indexed by source node, destination node, and time. The value assigned to each triplet is the path loss value between the given source, destination pair at the given simulation time. The Terrain Integrated Rough Earth Model. This model considers terrain effects, transmitter and receiver attributes such as antenna height and frequency, and atmospheric and ground constants. This model is distributed by the Joint Spectrum Center of the Department of Defense (http://www.jsc.mil/), and is interfaced with QualNet.

(*) Access restricted. Please consult with QualNet Support regarding availability and distribution requirements for these models.

8.1.5. Shadowing Model

The Shadowing Model is a log-normal distribution with standard deviation [dB], and can be combined with the Free Space Model, along with the Fading Model (Section 8.1.6). The PROPAGATION-SHADOWING-SIGMA parameter specifies the sigma () to use with this model. This can be either a global default, or specified per channel, using the Instance ID specification (See Section 2.3.9), as in the example below. # PROPAGATION-SHADOWING-SIGMA[0] 0.0 PROPAGATION-SHADOWING-SIGMA[1] 0.0 #

8.1.6. Fading Model

The Fading Models available in QualNet are narrowband flat fading models which implement the Rayleigh and Ricean distributions. The Rayleigh The distribution is useful in highly mobile cases and signals without line of sight. The Ricean distribution is more useful in the presence of line of sight. PROPAGATION-FADING-MODEL parameter specifies the distribution to use. This can be either a global default, or specified per channel, using the Instance ID specification (See Section 2.3.9), as in the example below. # PROPAGATION-FADING-MODEL[0] NONE PROPAGATION-FADING-MODEL[1] RAYLEIGH # PROPAGATION-FADING-MODEL RICEAN # PROPAGATION-RICEAN-K-FACTOR 0.0 # RAYLEIGH RICEAN NONE The Rayleigh Distribution The Ricean Distribution. The Ricean K factor is given using the PROPAGATION-RICEAN-K-FACTOR parameter No Fading Model

8.2.

Physical Layer Properties and Parameters

Radio models simulate the hardware that performs channel sensing, radio transmissions, receptions, and battery usage, and have parameters specified below. These models and parameters are not specified on a per-channel basis, using Instance ID Specification (See Section 2.3.9). They can be specified using node-specific (Section 2.3.8) and network-specific (Section 2.3.7) parameterization. The radio model available in the standard version of QualNet is: PHY802.11b A WaveLAN II / IEEE 802.11 compatible radio device model PHY802.11b

# PHY-MODEL #

8.2.1. Channel Masks

Channel masks are used in multi-channel wireless simulations to specify the channels that nodes in the simulation are able to listen to, and the ones they are currently listening to. PHY-LISTENABLE-CHANNEL-MASK specifies the channels that a node is able to listen to, whether it is configured to do so, or not. It is assumed that the network interfaces on this node allow it to be able to listen on these channels. This parameter is static throughout the simulation duration, and the number of digits in the mask must match the number of defined channels (See Section 8.1.1). PHY-LISTENING-CHANNEL-MASK specifies the channels that a node is listening to at startup. A node can change the channels that it is currently listening to, during the course of the simulation. Any channels specified as 1 in this mask must also be specified as 1 in the PHY-LISTENABLECHANNEL-MASK parameter, and the number of digits in the mask must match the number of defined channels (See Section 8.1.1) as well. The example below assumes that three channels exist. All nodes in the example are able to listen to channels 0 and 1, but are only listening to channel 0 at the start of the simulation.

# PHY-LISTENABLE-CHANNEL-MASK 110 PHY-LISTENING-CHANNEL-MASK 100 #

8.2.2. Temperature
The following parameter defines the temperature of the physical radio model in degrees K. This parameter is used in the calculation of thermal noise, along with the Boltzmann Constant and PHY-NOISE-FACTOR. # PHY-TEMPERATURE #

290

8.2.3. Noise Factor

The following parameter defines the noise factor of the physical radio model. In order to calculate the noise contributed by the physical radio model, the propagation model multiplies this factor by the PHY-TEMPERATURE, the Boltzmann Constant, and the bandwidth. # PHY-NOISE-FACTOR #

10.0

8.2.4. Packet Reception Model

The packet reception models available in QualNet are the ones below. Packet reception models determine how to decide whether or not a packet has successfully reached its destination, when broadcast over a radio. This model is used exclusively for wireless transmissions and receptions. # PHY-RX-MODEL PHY-RX-BER-TABLE-FILE # #PHY-RX-MODEL #PHY-RX-SNR-THRESHOLD # SNR-BOUNDED BER-BASED

BER-BASED ./bpsk.ber SNR-THRESHOLD-BASED 10.0

If the Signal to Noise ratio (SNR) is more than PHY-RXSNR-THRESHOLD (specified in dB), it receives the signal without error. Otherwise, the packet is dropped. The calculated Signal to Noise ratio is used to look up an associated Bit Error Rate (BER) from a table located in filename BER-TABLE-FILE.

8.2.4.1. Bit Error Rate Tables

The following BER table files are available for QualNet, in the data/modulation subdirectory: DPSK BPSK DQPSK GMSK differential phase shift keying binary phase shift keying method differential quaternary phase shift keying method Gaussian minimum shift keying method

8.2.5. Data Rate

The following parameter represents the data rate in bits per second at which wireless nodes will transmit messages. # PHY802.11b-DATA-RATE #

2000000

8.2.6. Transmission Power

The following parameter represents the radio signal transmission power in dBm. # PHY802.11b-TX-POWER #

15.0

8.2.7. Reception Sensitivity

The following parameter represents the radio reception sensitivity in dBm. The radio will detect signals above this threshold, causing carrier-sensing protocols to wait for the channel to clear before transmitting, but the radio may not successfully lock onto this signal, unless its signal strength exceeds the radio reception threshold, described in Section 8.2.8. # PHY802.11b-RX-SENSITIVITY #

-91.0

8.2.8. Reception Threshold

The following parameter represents the radio reception threshold in dBm. The radio will lock onto this signal if the signal strength exceeds this value. # PHY802.11b-RX-THRESHOLD #

-81.0

8.2.9. Antenna Model

The following parameter selects the QualNet model to use to simulate the antenna. # ANTENNA-MODEL OMNIDIRECTIONAL # ANTENNA-MODEL SWITCHED-BEAM # OMNIDIRECTIONAL The antenna model returns 0 dBi gain in all directions SWITCHED-BEAM Stores multiple radiation patterns and returns Ga and Ge for a given direction with a specified pattern STEERABLE Steerable Antenna Model

8.2.10.

Antenna Gain

The following parameter represents the antenna gain in dB. # ANTENNA-GAIN # 0.0

8.2.11.

Antenna Height

The following parameter represents the antenna height in meters. # ANTENNA-HEIGHT # 1.5

8.2.12.

Energy Consumption Model

A simple energy consumption model is included in phy_802_11b.c. It is intended for use with the IEEE 802.11 MAC DCF without power management, so it assumes that the physical device in idle mode (not receiving any signal) consumes the same power as it does in receive mode. This pattern of energy consumption is consistent with the constantly sensing IEEE 802.11 MAC DCF operation. specifications. The default energy consumption values in phy_802_11.h were derived from WaveLAN

9. QualNet API Reference

This chapter includes a brief description of the file extensions for QualNet source files, and the QualNet function call and inter-layer API documentation. A note on naming conventions: the QualNet API functions are divided into groups and placed in common header files. API functions will usually be prefixed with the name of the header file in all upper case. For example, message processing functions are placed in message.h and prefixed MESSAGE_. Similarly, calls to the Graphical User Interface (GUI) tools are declared in gui.h and prefixed with GUI_. Types declared in these files are usually prefixed with the capitalized name of the file, e.g. GuiEvents.

9.1.

QualNet File Extensions

C / C++ header file Text-based Configuration File Text-based Network Traffic (Application) Configuration File Bit Error Rate table Trace-based Mobility File Initial Node Position File Static Routes File Default Routes File QualNet Text-based Statistical Output File Threaded Metric Statistical Output File (see QualNet optional modules)

.h .config .app .ber .mobility .nodes .routes-static .routes-default .stat .thd

9.2.

Time Functions

This Section covers some useful functions for manipulating simulation time variables.

9.2.1.

getSimTime(node)

clocktype getSimTime( Node node);

Routine getSimTime

Required Headers None

Return Value This function returns the current simulation time in the clocktype data format. Parameters None Remarks The getSimTime function returns a clocktype, which is a 64-bit integral data type. QualNet sets the resolution of this clock to indicate the number of nanoseconds that have passed since the start of the simulation. Note that the preferred method for outputting clocktypes to the screen is to use ctoa (See Section 9.2.2) to convert a clocktype to its string representation. Example /* GETSIMTIME.PC: This program uses the getSimTime function * to return the current simulation time. */ #include <stdio.h> void show_the_current_time(Node *node) { clocktype curTime; char buf[80]; curTime = getSimTime(node); ctoa(curTime, buf); } printf(The current time is %s.\n, buf);

Output The current time is 100000.

9.2.2.
void ctoa(

ctoa()
clocktype cVal, char *buffer);

Routine ctoa
Return Value None

Required Headers None

Parameters cVal The clocktype integral variable to convert to its string representation buffer A pointer to a character array of sufficient size to store the string representation of the clocktype. Be sure to allocate space for this array before passing in a pointer. Remarks The ctoa function behaves similarly to sprintf, printing the value of the clocktype parameter into the string parameter. Example /* GETSIMTIME.PC: This program uses the getSimTime function * to return the current simulation time. */ #include <stdio.h> void show_the_current_time(Node *node) { clocktype curTime; char buf[80]; curTime = getSimTime(node); ctoa(curTime, buf); } printf(The current time is %s.\n, buf);

Output The current time is 100000.

9.3.

Configuration Related Functions

At the simulations initialization phase, QualNet reads the text-based Configuration File that was specified as a command-line parameter. Users who execute QualNet via the GUI have their text-based Configuration File generated automatically by the GUI, and fed to the simulator transparently when they hit the Action! button (See the Animator Manual.). This Configuration File contains the information about the protocols that run at each layer of the protocol stack, and at each node in the simulation. It also contains protocol specific parameters that the protocol designers wish to allow end users to modify. This section covers the QualNet Functions that allow you, as a protocol designer, to interface with the text-based Configuration File.

9.3.1. IO_ReadString()
void IO_ReadString( const NodeAddress nodeId, const NodeAddress interfaceAddress, const NodeInput *nodeInput, const char *index, BOOL &retVal, char *readVal);

Routine IO_ReadString
Return Value None

Required Headers fileio.h

Parameters nodeId Either the unique Node Identifier of the Node calling this function, or ANY_NODE, which specifies that the default value of this parameter should be returned, rather than one which is specific to this node. interfaceAddress Either the IP address of the interface for which the function is being called (you can specify different parameter values in the configuration file for different interfaces on the same node) or ANY_INTERFACE, which specifies the default value of this parameter for the given node, rather than one which is specific to one of this nodes interfaces. nodeInput The pointer to the data structure which contains the configuration file. This pointer is passed to all initialization functions. index A character array containing the name of the parameter whose value should be retrieved by this function. retVal The pointer to a Boolean variable. This function will place TRUE or FALSE at this memory location to indicate whether or not the parameter specified by index was found, and the value placed in readVal. readVal A pointer to the character array where this parameters value should be written. Remarks It is safest to allocate character arrays of size MAX_STRING_LENGTH to pass in as the readVal parameter, in order to ensure that no memory violations occur. Example /* READSTRING.PC: This program uses the IO_ReadString function * to return the value of a parameter in the simulation configuration file. */ #include <stdio.h> #include fileio.h void lookup_a_string_parameter(Node *node, const NodeInput *nodeInput) { char buf[MAX_STRING_LENGTH]; bool retVal; IO_ReadString(ANY_NODE, ANY_IP, nodeInput, TCP-STATISTICS, &retVal, buf); if (retVal) { printf(The parameter \TCP-STATISTICS\ has the value \%s\\n, buf); } else printf(Could not find the parameter \TCP-STATISTICS\ in the configuration file.\n); } Output The parameter TCP-STATISTICS has the value NO

9.3.2. IO_ReadInt()
void IO_ReadInt( const NodeAddress nodeId, const NodeAddress interfaceAddress, const NodeInput *nodeInput, const char *index, BOOL &retVal, int *readVal);

Routine IO_ReadInt
Return Value None

Required Headers fileio.h

Parameters nodeId Either the unique Node Identifier of the Node calling this function, or ANY_NODE, which specifies that the default value of this parameter should be returned, rather than one which is specific to this node. interfaceAddress Either the IP address of the interface for which the function is being called (you can specify different parameter values in the configuration file for different interfaces on the same node) or ANY_INTERFACE, which specifies the default value of this parameter for the given node, rather than one which is specific to one of this nodes interfaces. nodeInput The pointer to the data structure which contains the configuration file. This pointer is passed to all initialization functions. index A character array containing the name of the parameter whose value should be retrieved by this function. retVal The pointer to a Boolean variable. This function will place TRUE or FALSE at this memory location to indicate whether or not the parameter specified by index was found, and the value placed in readVal. readVal A pointer to the integer memory location where this parameters value should be written.

Example /* READINT.PC: This program uses the IO_ReadInt function * to return the value of a parameter in the simulation configuration file. */ #include <stdio.h> #include fileio.h void lookup_an_int_parameter(Node *node, const NodeInput *nodeInput) { int count; bool retVal; IO_ReadInt(ANY_NODE, ANY_IP, nodeInput, IP-QUEUE-NUM-PRIORITIES, &retVal, &count); if (retVal) { printf(The parameter \ IP-QUEUE-NUM-PRIORITIES\ has the value \%d\\n, count); } else printf(Could not find the parameter \IP-QUEUE-NUM-PRIORITIES\ in the configuration file.\n);

Output The parameter IP-QUEUE-NUM-PRIORITIES has the value 3

9.3.3. IO_ReadDouble()
void IO_ReadDouble( const NodeAddress nodeId, const NodeAddress interfaceAddress, const NodeInput *nodeInput, const char *index, BOOL &retVal, double *readVal);

Routine IO_ReadDouble
Return Value None

Required Headers fileio.h

Parameters nodeId Either the unique Node Identifier of the Node calling this function, or ANY_NODE, which specifies that the default value of this parameter should be returned, rather than one which is specific to this node. interfaceAddress Either the IP address of the interface for which the function is being called (you can specify different parameter values in the configuration file for different interfaces on the same node) or ANY_INTERFACE, which specifies the default value of this parameter for the given node, rather than one which is specific to one of this nodes interfaces. nodeInput The pointer to the data structure which contains the configuration file. This pointer is passed to all initialization functions. index A character array containing the name of the parameter whose value should be retrieved by this function. retVal The pointer to a Boolean variable. This function will place TRUE or FALSE at this memory location to indicate whether or not the parameter specified by index was found, and the value placed in readVal. readVal A pointer to the double floating point memory location where this parameters value should be written. Example /* READDOUBLE.PC: This program uses the IO_ReadDouble function * to return the value of a parameter in the simulation configuration file. */ #include <stdio.h> #include fileio.h void lookup_a_double_parameter(Node *node, const NodeInput *nodeInput) { double temp; bool retVal; IO_ReadDouble(ANY_NODE, ANY_IP, nodeInput, TEMPERATURE, &retVal, &temp); if (retVal) { printf(The parameter \ TEMPERATURE\ has the value \%lf\\n, temp); } else printf(Could not find the parameter \TEMPERATURE\ in the configuration file.\n);

Output The parameter TEMPERATURE has the value 290.0

9.3.4. IO_ReadTime()
void IO_ReadTime( const NodeAddress nodeId, const NodeAddress interfaceAddress, const NodeInput *nodeInput, const char *index, BOOL &retVal, double *readVal);

Routine IO_ReadTime
Return Value None

Required Headers fileio.h

Parameters nodeId Either the unique Node Identifier of the Node calling this function, or ANY_NODE, which specifies that the default value of this parameter should be returned, rather than one which is specific to this node. interfaceAddress Either the IP address of the interface for which the function is being called (you can specify different parameter values in the configuration file for different interfaces on the same node) or ANY_INTERFACE, which specifies the default value of this parameter for the given node, rather than one which is specific to one of this nodes interfaces. nodeInput The pointer to the data structure which contains the configuration file. This pointer is passed to all initialization functions. index A character array containing the name of the parameter whose value should be retrieved by this function. retVal The pointer to a Boolean variable. This function will place TRUE or FALSE at this memory location to indicate whether or not the parameter specified by index was found, and the value placed in readVal. readVal A pointer to the clocktype memory location where this parameters value should be written. Remarks This function converts between the Qualnet Time Format (See Section 2.3.3) and the clocktype data type that represents the internal simulation clock. The Qualnet Time Format is used by end users in the configuration text files, while the clocktype data type is used internally for timer scheduling and modeling processing and propagation delays.

Example /* READTIME.PC: This program uses the IO_ReadTime function * to return the value of a parameter in the simulation configuration file. */ #include <stdio.h> #include fileio.h void lookup_a_time_parameter(Node *node, const NodeInput *nodeInput) { clocktype simTime; char clockStr[MAX_STRING_LENGTH]; bool retVal; IO_ReadTime(ANY_NODE, ANY_IP, nodeInput, SIMULATION-TIME, &retVal, &simTime); if (retVal) { ctoa(simTime, clockStr); printf(The parameter \SIMULATION-TIME\ has the value \%s\\n, clockStr); } else printf(Could not find the parameter \SIMULATION-TIME\ in the configuration file.\n);

Output The parameter SIMULATION TIME has the value 15000000000

9.4.

Message Related Functions

Messages are the events that are passed between nodes, and between layers in a single node as events. A Message is composed of a Packet Field, which is the combination of the data payload and all headers, Event Information that the QualNet kernel uses to call the appropriate function to process the Message, and additional user-specified space (Info Field) where optional information about the event can be stored. Two examples of Messages are Packets and Timers. Figure 4 illustrates the function calls that manipulate a Packet, from its creation, through the various layers in a node, through the transmission medium, up the protocol stack of the receiving node, to its final destination and destruction.

The Life Cycle of a Packet

Application Application

GLOMO_MsgAlloc() GLOMO_MsgPacketAlloc() GLOMO_MsgSend()

Transport

GLOMO_MsgFree()

Transport

GLOMO_MsgAddHeader() GLOMO_MsgSend()
Routing IP

GLOMO_MsgRemoveHeader() GLOMO_MsgSend()
IP

GLOMO_MsgAddHeader() GLOMO_MsgSend()
MAC

GLOMO_MsgRemoveHeader() GLOMO_MsgSend()
MAC

GLOMO_MsgAddHeader() GLOMO_MsgSend()
Physical

GLOMO_MsgRemoveHeader() GLOMO_MsgSend()
Physical

Figure 4: The Life Cycle of a Packet

9.4.1. MESSAGE_Alloc()
Message* MESSAGE_Alloc( Node *node, LAYER_TYPE layertype, int protocol, EVENT_TYPE eventType);

Routine MESSAGE_Alloc

Required Headers message.h main.h

Return Value This function returns the pointer to the newly created Message structure, and halts simulation execution on failure. Parameters node Pointer to the Node structure containing the calling nodes data space layertype This parameter specifies the destination layer for this Message. LAYER_TYPE is an enumeration listed in main.h (in the include/ subdirectory of the QualNet Directory Structure) of all of the QualNet layers. Examples of these include APP_LAYER, TRANSPORT_LAYER, and so on. protocol This field determines the destination protocol running at the above-referenced layertype for this Message. Examples of these are APP_FTP_SERVER, and TRANSPORT_PROTOCOL_UDP. eventType This field determines the event that this Message represents to the above-referenced protocol and layer. Remarks The MESSAGE_Alloc function creates a pointer to a new Message, and initializes its event, layer, and protocol information. This Message is reusable, as a single Message can traverse the Life Cycle illustrated in Figure 4.

Example /* MSG_ALLOC.PC: This program uses the MESSAGE_Alloc function * to create a new Message for the Application Layer FTP Server. The event * type represented by this Message is a Timer Expiration. */ #include <stdio.h> #include main.h #include message.h Message* create_a_message(Node *node) { Message* newMsg = MESSAGE_Alloc( node, APP_LAYER, APP_FTP_SERVER, MSG_APP_TimerExpired); printf(Created a new Message.\n); return newMsg; } Output Created a new Message.

9.4.2. MESSAGE_InfoAlloc()
void MESSAGE_InfoAlloc( Node *node, Message *msg, int infoSize);

Routine MESSAGE_InfoAlloc

Required Headers message.h

Return Value None. This function halts simulation execution on failure to allocate sufficient memory. The simulation cannot continue when out of memory. Parameters node Pointer to the Node structure containing the calling nodes data space msg This is the Message pointer previously returned by a call to MESSAGE_Alloc (Section 9.4.1) or received from another function or protocol. infoSize This field determines the size in bytes of the data space to be allocated. This info field is used for user-specified event information.

Remarks The MESSAGE_InfoAlloc function either allocates or resizes additional userspecified event information space. On the first call to this function, the space is created, while all subsequent calls replace the prior space with a new space of the desired size. Since this space is allocated for event information, it can be adjusted throughout the life cycle of the Message, and one cannot assume that it contains the same information at the destination as it does at the sender. Also, storage of information in this space does not affect the size of the data packet, and does not increase the transmission delay over wire or wireless media. See MESSAGE_ReturnInfo (Section 9.4.9) for information about accessing the Info Field. Example /* MSG_INFO_ALLOC.PC: This program uses the MESSAGE_InfoAlloc function * to create a new info field for a Message created for the Application Layer FTP Server. * The event type represented by this Message is a Timer Expiration. */ #include <stdio.h> #include main.h #include message.h typedef struct timer_information_str { clocktype generation_time; /* The creation time for this Timer */ int timerType; /* A subtype for the Timer */ NodeAddress neighbor; /* The neighbor IP address that this Timer is concerned with */ } MyTimerInfo; Message *create_a_message_with_info(Node *node) { MyTimerInfo *timerInfoPtr; Message* newMsg = MESSAGE_Alloc( node, APP_LAYER, APP_FTP_SERVER, MSG_APP_TimerExpired); printf(Created a new Message.\n); MESSAGE_InfoAlloc( node, newMsg, sizeof(MyTimerInfo)); timerInfoPtr = (MyTimerInfo *)MESSAGE_ReturnInfo(newMsg); timerInfoPtr->generation_time = getSimTime(node); } return newMsg;

Output Created a new Message.

9.4.3. MESSAGE_PacketAlloc()
void MESSAGE_PacketAlloc( Node *node, Message *msg, int packetSize);

Routine MESSAGE_PacketAlloc

Required Headers message.h

Return Value None. This function halts simulation execution on failure to allocate sufficient memory. The simulation cannot continue when out of memory. Parameters node Pointer to the Node structure containing the calling nodes data space msg This is the Message pointer previously returned by a call to MESSAGE_Alloc (Section 9.4.1) or received from another function or protocol. packetSize This field determines the initial size in bytes of the packet to be allocated. This field is used to store the data and all headers that will be transmitted from one node to other node(s). Remarks The MESSAGE_PacketAlloc function allocates the Packet to an initial size given by the packetSize parameter. Unlike MESSAGE_InfoAlloc (Section 9.4.2) this function should be called only once. If you wish to adjust the size of the packet, use MESSAGE_AddHeader (Section 9.4.4) and MESSAGE_RemoveHeader (Section 9.4.5). Storage of information in this space directly affects the size of the data packet, and its transmission delay over wire or wireless media. See MESSAGE_ReturnPacket (Section 9.4.11) for information about accessing the Packet Field.

Example /* MSG_PACKET_ALLOC.PC: This program uses the MESSAGE_PacketAlloc function * to create a new packet field for a Message created for the Application Layer Constant Bit Rate * generator. The event type represented by this Message is a Packet sent to UDP for * transmission. */ #include <stdio.h> #include main.h #include message.h typedef struct my_cbr_packet_fields { clocktype generation_time; /* The creation time for this Packet */ char buf[512]; /* Padding to make the cbr packet total * 512 bytes + sizeof(clocktype) */ } MyCbrPacket; Message *create_a_cbr_message (Node *node) { Message* msg; MyCbrPacket *packet; msg = MESSAGE_Alloc ( node, TRANSPORT_LAYER, TRANSPORT_PROTOCOL_UDP, MSG_TRANSPORT_FromAppSend); MESSAGE_PacketAlloc (node, msg, sizeof(MyCbrPacket)); /* Allocate the packet */ packet = (MyCbrPacket *) MESSAGE_ReturnPacket (msg); packet->generation_time = getSimTime(node); printf(Created a new Message.\n); return msg; } Output Created a new Message.

9.4.4. MESSAGE_AddHeader()
void MESSAGE_AddHeader( Node *node, Message *msg, int hdrSize);

Routine MESSAGE_AddHeader

Required Headers message.h

Return Value None. This function halts simulation execution on failure to allocate sufficient memory. The simulation cannot continue when out of memory. Parameters node Pointer to the Node structure containing the calling nodes data space msg This is the Message pointer previously returned by a call to MESSAGE_Alloc (Section 9.4.1) or received from another function or protocol. hdrSize This field determines the additional size in bytes to add to the front of the data space already allocated for this Packet. Referencing the Packet Field returns a pointer to this space, with the original, smaller Packet Field appended after it. Remarks The MESSAGE_AddHeader function adds additional data space to the front of an already allocated Packet. Packets are allocated first by MESSAGE_PacketAlloc (Section 9.4.3) and MESSAGE_AddHeader and MESSAGE_RemoveHeader (Section 9.4.5) modify the size of the data space. Storage of information in this space directly affects the size of the data packet, and the transmission delay over wire or wireless media. See MESSAGE_ReturnPacket (Section 9.4.11) for information about accessing the Info Field.

Example /* MSG_ADD_HEADER.PC: This program uses the MESSAGE_AddHeader function * to add a header to a Packet. */ typedef struct my_cbr_packet_fields { clocktype generation_time; /* The creation time for this Packet */ char buf[512]; /* Padding to make the cbr packet total * 512 bytes + sizeof(clocktype) */ } MyCbrPacket; typedef struct my_cbr_header_fields { NodeAddress src_addr; /* The source address of this packet */ } MyCbrHeader; Message *create_a_cbr_message (Node *node) { Message* msg; MyCbrPacket *packet; MyCbrHeader *header; msg = MESSAGE_Alloc ( node, TRANSPORT_LAYER, TRANSPORT_PROTOCOL_UDP, MSG_TRANSPORT_FromAppSend); MESSAGE_PacketAlloc ( node, msg, sizeof(MyCbrPacket)); /* Allocate the packet */ packet = (MyCbrPacket *) MESSAGE_ReturnPacket (msg); packet->generation_time = getSimTime(node); MESSAGE_AddHeader( node, msg, sizeof(MyCbrHeader)); /* Adds a header */ header = (MyCbrHeader *) MESSAGE_ReturnPacket(msg); header->src_addr = node->nodeAddr; printf(Created a new Message.\n); return msg; } Output Created a new Message.

9.4.5. MESSAGE_RemoveHeader()
void MESSAGE_RemoveHeader( Node *node, Message *msg, int hdrSize);

Routine MESSAGE_RemoveHeader
Return Value None.

Required Headers message.h

Parameters node Pointer to the Node structure containing the calling nodes data space msg This is the Message pointer previously returned by a call to MESSAGE_Alloc (Section 9.4.1) or received from another function or protocol. hdrSize This field determines the size in bytes to remove from the front of the data space already allocated for this Packet. Referencing the Packet Field returns a pointer to the front of this reduced space, with hdrSize bytes removed. Remarks The MESSAGE_RemoveHeader function removes data space from the front of an already allocated Packet. Packets are allocated first by MESSAGE_PacketAlloc (Section 9.4.3) and MESSAGE_AddHeader and MESSAGE_RemoveHeader (Section 9.4.5) modify the size of the data space. Storage of information in this space directly affects the size of the data packet, and the transmission delay over wire or wireless media. See MESSAGE_ReturnPacket (Section 9.4.11) for information about accessing the Info Field.

Example /* MSG_REMOVE_HEADER.PC: This program uses the MESSAGE_RemoveHeader * function to remove a header from a Packet. */ typedef struct my_cbr_packet_fields { clocktype generation_time; /* The creation time for this Packet */ char buf[512]; /* Padding to make the cbr packet total * 512 bytes + sizeof(clocktype) */ } MyCbrPacket; typedef struct my_cbr_header_fields { NodeAddress src_addr; /* The source address of this packet */ } MyCbrHeader; Message *create_a_cbr_message (Node *node) { Message* msg; MyCbrPacket *packet; MyCbrHeader *header; msg = MESSAGE_Alloc ( node, TRANSPORT_LAYER, TRANSPORT_PROTOCOL_UDP, MSG_TRANSPORT_FromAppSend); MESSAGE_PacketAlloc ( node, msg, sizeof(MyCbrPacket)); /* Allocate the packet */ packet = (MyCbrPacket *) MESSAGE_ReturnPacket (msg); packet->generation_time = getSimTime(node); MESSAGE_AddHeader( node, msg, sizeof(MyCbrHeader)); /* Adds a header */ header = (MyCbrHeader *) MESSAGE_ReturnPacket(msg); header->src_addr = node->nodeAddr; MESSAGE_RemoveHeader( node, msg, sizeof(MyCbrHeader)); /* Removes a header */ printf(Created a new Message.\n); } return msg;

Output Created a new Message.

9.4.6. MESSAGE_Copy()
Message *MESSAGE_Copy( Node *node, const Message *msg);

Routine MESSAGE_Copy

Required Headers message.h

Return Value This function returns the pointer to the newly created Message structure, and halts simulation execution on failure. The newly created Message structure will have identical contents to the original Message, including Packet and Info fields, and event, layer, and protocol information. Parameters node Pointer to the Node structure containing the calling nodes data space msg This is the Message pointer previously returned by a call to MESSAGE_Alloc (Section 9.4.1) or received from another function or protocol. It represents the original Message to be copied. Remarks The MESSAGE_Copy function creates a pointer to a new Message, and copies its event, layer, and protocol information from the original Message (msg). This function creates an exact duplicate of this original Message. This Message is reusable, as a single Message can traverse the Life Cycle illustrated in Figure 4.

Example /* MSG_COPY.PC: This program uses the MESSAGE_Copy function * to create a new packet field for a Message created for the Application Layer Constant Bit Rate * generator. The event type represented by this Message is a Packet sent to UDP for * transmission. */ #include <stdio.h> #include main.h #include message.h typedef struct my_cbr_packet_fields { clocktype generation_time; /* The creation time for this Packet */ char buf[512]; /* Padding to make the cbr packet total * 512 bytes + sizeof(clocktype) */ } MyCbrPacket; Message *create_a_cbr_message (Node *node) { Message* msg; Message* newMsg; MyCbrPacket *packet; msg = MESSAGE_Alloc ( node, TRANSPORT_LAYER, TRANSPORT_PROTOCOL_UDP, MSG_TRANSPORT_FromAppSend); MESSAGE_PacketAlloc (node, msg, sizeof(MyCbrPacket)); /* Allocate the packet */ packet = (MyCbrPacket *) MESSAGE_ReturnPacket (msg); packet->generation_time = getSimTime(node); printf(Created a new Message.\n); newMsg = MESSAGE_Copy(node, msg); printf(Copied the Message.\n); } return msg;

Output Created a new Message. Copied the Message.

9.4.7. MESSAGE_Send()
void MESSAGE_Send( Node *node, Message *msg, clocktype delay);

Routine MESSAGE_Send

Required Headers message.h

Return Value None. This function will abort simulation execution if the delay value is negative, implying that the sender wishes the Message to arrive earlier than the time it was actually sent. Parameters node Pointer to the Node structure containing the calling nodes data space msg This is the Message pointer previously returned by a call to MESSAGE_Alloc (Section 9.4.1) or received from another function or protocol. It represents the Message to be sent, according to its event, protocol, and layer information delay This is the delay between the current simulation time and the time that the Message should be delivered. This parameter can be used to simulate the processing delay required in a real system to deliver this Message. The unit of time is the nanosecond, and these can be specified by multiplying a numeric value with the defined constants {DAY, HOUR, MINUTE, SECOND, MILLI_SECOND, MICRO_SECOND}. For example, (3*SECOND) would indicate a three-second delay. Remarks The MESSAGE_Send function schedules the Message (msg) for delivery to the layer, and protocol specified by the Message, and delivers it after the delay. This function delivers the Message to the layer and protocol indicated, as an event of the type assigned to this Message. Please note that once you have sent a message, it has left your codes control. It would be incorrect to modify a data or info space in the message, copy the message, send it again, or delete it after you have sent it.

Example /* MSG_SEND.PC: This program uses the MESSAGE_Send function * to create a new packet field for a Message created for the Application Layer Constant Bit Rate * generator. The event type represented by this Message is a Packet sent to UDP for * transmission. */ #include <stdio.h> #include main.h #include message.h typedef struct my_cbr_packet_fields { clocktype generation_time; /* The creation time for this Packet */ char buf[512]; /* Padding to make the cbr packet total * 512 bytes + sizeof(clocktype) */ } MyCbrPacket; void create_a_cbr_message_and_send_it (Node *node) { Message* msg; AppToUdpSend *info; MyCbrPacket *packet; msg = MESSAGE_Alloc ( node, TRANSPORT_LAYER, TRANSPORT_PROTOCOL_UDP, MSG_TRANSPORT_FromAppSend); MESSAGE_PacketAlloc (node, msg, sizeof(MyCbrPacket)); /* Allocate the packet */ packet = (MyCbrPacket *) MESSAGE_ReturnPacket (msg); packet->generation_time = getSimTime(node); printf(Created a new Message.\n); MESSAGE_InfoAlloc (node, msg, sizeof(AppToUdpSend)); info = (AppToUdpSend *) MESSAGE_ReturnInfo(msg); info->sourceAddr = node->nodeAddr; info->sourcePort = APP_CBR_SERVER; /* My Own application type */ info->destAddr = ANY_DEST; /* A broadcast to all destinations within range */ info->destPort = APP_CBR_CLIENT; /* The destination application type */ info->priority = NON_REAL_TIME; /* CONTROL, and DATA are the other two priorities */ MESSAGE_Send(node, msg, (1*MILLI_SECOND)); /* Simulate 1ms processing delay */ printf(Sent the Message.\n); } Output Created a new Message. Sent the Message.

9.4.8. MESSAGE_Free()
void MESSAGE_Free( Node *node, Message *msg);

Routine MESSAGE_Free

Required Headers message.h

Return Value None. This function deallocates memory assigned to the Message, and returns. Parameters node Pointer to the Node structure containing the calling nodes data space msg This is the Message pointer previously returned by a call to MESSAGE_Alloc (Section 9.4.1) or received from another function or protocol. It represents the Message to be deallocated. Remarks The MESSAGE_Free function is called by the final destination for the Message. An example of this is shown at the receiving end of Figure 4: The Life Cycle of a Packet. This Message cannot be sent or copied after its memory has been released by this Function.

Example /* MSG_FREE.PC: This program uses the MESSAGE_Free function * to free a Message created for the Application Layer Constant Bit Rate * generator. */ #include <stdio.h> #include main.h #include message.h typedef struct my_cbr_packet_fields { clocktype generation_time; /* The creation time for this Packet */ char buf[512]; /* Padding to make the cbr packet total * 512 bytes + sizeof(clocktype) */ } MyCbrPacket; void create_a_cbr_message_and_free_it (Node *node) { Message* msg; MyCbrPacket *packet; msg = MESSAGE_Alloc ( node, TRANSPORT_LAYER, TRANSPORT_PROTOCOL_UDP, MSG_TRANSPORT_FromAppSend); MESSAGE_PacketAlloc (node, msg, sizeof(MyCbrPacket)); /* Allocate the packet */ packet = (MyCbrPacket *) MESSAGE_ReturnPacket (msg); packet->generation_time = getSimTime(node); printf(Created a new Message.\n); MESSAGE_Free (node, msg); /* Note that there is no MESSAGE_Send in this function */ printf(Freed the Message.\n); } Output Created a new Message. Freed the Message.

9.4.9. MESSAGE_GetEvent()
short MESSAGE_ReturnEvent( Message *msg);

Routine MESSAGE_GetEvent

Required Headers message.h

Return Value A short integer value corresponding to the type of event represented by the msg. Parameters msg This is the Message pointer previously returned by a call to MESSAGE_Alloc (Section 9.4.1) or received from another function or protocol. Remarks A list of the return values is given in the file include/structmsg.h. Example /* MSG_GET_EVENT.PC: This program uses the MESSAGE_GetEvent function * to determine what kind of event is represented by a certain Message. * The event type represented by this Message is a Timer Expiration. */ #include <stdio.h> #include main.h #include message.h typedef struct timer_information_str { clocktype generation_time; /* The creation time for this Timer */ int timerType; /* A subtype for the Timer */ NodeAddress neighbor; /* The neighbor IP address that this Timer is concerned with */ } MyTimerInfo; void create_a_message_and_print_its_eventType(Node *node) { MyTimerInfo *timerInfoPtr; Message* newMsg = MESSAGE_Alloc( node, APP_LAYER, APP_FTP_SERVER, MSG_APP_TimerExpired); printf(Created a new Message of event type %d.\n, MESSAGE_GetEvent(newMsg)); }

Output Created a new Message of event type 56.

9.4.10.

MESSAGE_ReturnInfo()

char *MESSAGE_ReturnInfo( Message *msg);

Routine MESSAGE_ReturnInfo

Required Headers message.h

Return Value A char pointer which points to the allocated data space for additional user-specified Event information. This space is allocated by MESSAGE_InfoAlloc (Section 9.4.2). This Function will return NULL if the space has not been previously allocated by MESSAGE_InfoAlloc (Section 9.4.2). Parameters msg This is the Message pointer previously returned by a call to MESSAGE_Alloc (Section 9.4.1) or received from another function or protocol. Remarks The MESSAGE_ReturnInfo function returns a character pointer, but is typically casted to a pointer to a user-defined data structure, as in the example below.

Example /* MSG_RETURN_INFO.PC: This program uses the MESSAGE_ReturnInfo function * to access a new info field for a Message created for the Application Layer FTP Server. * The event type represented by this Message is a Timer Expiration. */ #include <stdio.h> #include main.h #include message.h typedef struct timer_information_str { clocktype generation_time; /* The creation time for this Timer */ int timerType; /* A subtype for the Timer */ NodeAddress neighbor; /* The neighbor IP address that this Timer is concerned with */ } MyTimerInfo; Message *create_a_message_with_info(Node *node) { MyTimerInfo *timerInfoPtr; Message* newMsg = MESSAGE_Alloc( node, APP_LAYER, APP_FTP_SERVER, MSG_APP_TimerExpired); printf(Created a new Message.\n); MESSAGE_InfoAlloc( node, newMsg, sizeof(MyTimerInfo)); timerInfoPtr = (MyTimerInfo *)MESSAGE_ReturnInfo(newMsg); /* Casted to a structure */ timerInfoPtr->generation_time = getSimTime(node); values to the /* Assigning * User-Defined Event Info * Space */

return newMsg;

Output Created a new Message.

9.4.11.

MESSAGE_ReturnPacket()

char *MESSAGE_ReturnPacket( Message *msg);

Routine MESSAGE_ReturnPacket

Required Headers message.h

Return Value A char pointer which points to the allocated data space for the Packet. This space is allocated by MESSAGE_PacketAlloc (Section 9.4.3). This Function will return NULL if the space has not been previously allocated by MESSAGE_PacketAlloc (Section 9.4.3). Parameters msg This is the Message pointer previously returned by a call to MESSAGE_Alloc (Section 9.4.1) or received from another function or protocol. Remarks The MESSAGE_ReturnPacket function returns a character pointer, but is typically casted to a pointer to a user-defined data structure, as in the example below.

Example /* MSG_RETURN_PACKET.PC: This program uses the MESSAGE_ReturnPacket function * to access a packet, and a header to a Packet. */ typedef struct my_cbr_packet_fields { clocktype generation_time; /* The creation time for this Packet */ char buf[512]; /* Padding to make the cbr packet total * 512 bytes + sizeof(clocktype) */ } MyCbrPacket; typedef struct my_cbr_header_fields { NodeAddress src_addr; /* The source address of this packet */ } MyCbrHeader; Message *create_a_cbr_message (Node *node) { Message* msg; MyCbrPacket *packet; MyCbrHeader *header; msg = MESSAGE_Alloc ( node, TRANSPORT_LAYER, TRANSPORT_PROTOCOL_UDP, MSG_TRANSPORT_FromAppSend); MESSAGE_PacketAlloc ( node, msg, sizeof(MyCbrPacket)); /* Allocate the packet */ packet = (MyCbrPacket *) MESSAGE_ReturnPacket (msg); /* Casted to a structure */ packet->generation_time = getSimTime(node); the /* Assigning values to * User-Defined Event Info * Space

MESSAGE_AddHeader( node, msg, sizeof(MyCbrHeader)); /* Adds a header */ header = (MyCbrHeader *) MESSAGE_ReturnPacket(msg); /* Casted to a structure */ header->src_addr = node->nodeAddr; /* Assigning values to the * User-Defined Event Info * Space */

printf(Created a new Message.\n); } return msg;

Output Created a new Message.

9.5.

Graphical User Interface API Functions

The Graphical User Interface API Functions are used by application programmers to animate the network activity in their protocols. Most of the API function calls represent events in the simulation, such as radio broadcasts, packet arrivals, packet drops, etc. Events are also tagged with the protocol layer where they occur, and a type. The purpose of these types is to allow the protocol designer to distinguish between different types of objects/data. The system uses zero as a generic default type for nodes, data, and links. The user may define custom types beginning at 1.

9.5.1. GUI_Initialize
void GUI_Initialize( int numNodes, int coordinateSystem, Coordinates origin, Coordinates dimensions, char* terrainMap, clocktype maxClock);

Routine GUI_Initialize
Return Value None

Required Headers gui.h

Parameters numNodes This is the number of nodes in the current simulation. coordinateSystem This is the coordinate system in place for the current simulation. Options are CARTESIAN and LATLONALT, which are two defined constants. origin This is the coordinates for the origin of the current simulation terrain. dimensions This is the dimensions of the current simulation in the coordinateSystem specified above. terrainMap A string containing the path of an image file to use as a terrain background. More full featured terrain support will be included in subsequent versions. maxClock This is the time that the simulation ends. Remarks The GUI_Initialize function initializes the GUI in order to start the animation. This function is called by the QualNet kernel first, and needs to be called before any other GUI API call. Its syntax is provided here for reference only. It is likely to be modified as QualNet and its GUI become more sophisticated. Example /* This is the call to GUI_Initialize that exists in the QualNet kernel. There is no need to use or * modify this function call. */ GUI_Initialize(nodeNum, coordinateSystemType, terrainOrigin, terrainDimensions, NULL, maxSimClock); Output None.

9.5.2. GUI_SetEffect
void GUI_SetEffect( GuiEvents event, GuiLayers layer, int type, GuiEffects effect, GuiColors color);

Routine GUI_SetEffect
Return Value None

Required Headers gui.h

Parameters event This is the semantic event for which the user would like to define the behavior of the GUI. layer This is the protocol layer affected by the change. type This specifies the type of the data or object. effect This is the graphical effect that will be display (such as drawing an arrow, circle, or line) for the given (event, layer, type). color This assigns a color to effect. Remarks This function has been implemented, but is not yet completed supported by the Animator. The Animator maintains a three dimensional table of effects that it will execute when the given (event, layer, type) occurs. This method allows the protocol designer to specify the graphical effect that will occur for each event. Not all effects apply to all events.

Example #define CTS_TYPE 1 #define RTS_TYPE 2 #define ACK 3 GUI_SetEffect(GUI_BROADCAST, GUI_MAC_LAYER, CTS_TYPE, GUI_DEFAULT_EFFECT, GUI_BLUE); GUI_SetEffect(GUI_BROADCAST, GUI_MAC_LAYER, RTS_TYPE, GUI_DEFAULT_EFFECT, GUI_YELLOW); GUI_SetEffect(GUI_BROADCAST, GUI_MAC_LAYER, ACK, GUI_DEFAULT_EFFECT, GUI_RED); Output This code defines three types of messages, and then sets the default behavior of the GUI to display a broadcast of each type of message with a different color. Note that this example is figurative, since the function hasn't been implemented.

9.5.3. GUI_InitNode
void GUI_InitNode( Node* node, NodeInput* nodeInput, clocktype time);

Routine GUI_InitNode
Return Value None

Required Headers gui.h

Parameters node Pointer to the Node structure containing the calling nodes data space nodeInput This is the structure containing all the configuration variable input. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1).

Remarks Provides the initial location of the node, the time of creation, and other information. Example GUI_InitNode(node, nodeInput, getSimTime(node)); Output The nodes initial position will be reflected in the GUI.

9.5.4. GUI_MoveNode
void GUI_MoveNode( NodeAddress id, Coordinates position, clocktype time);

Routine GUI_MoveNode
Return Value None

Required Headers gui.h

Parameters id This is the numeric identifier for the given node. In the Node structure, it is the nodeId struct member. position This is the new position of the given node. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks Moves the node to a new position. Example GUI_MoveNode(node->nodeAddr, node->position, getSimTime(node)); Output The nodes new position will be reflected in the GUI.

9.5.5. GUI_SetNodeOrientation
void GUI_SetNodeOrientation( NodeAddress id, Orientation orientation, clocktype time);

Routine GUI_SetNodeOrientation
Return Value None

Required Headers gui.h

Parameters id This is the numeric identifier for the given node. In the Node structure, it is the nodeId struct member. orientation Specifically for directional antenna systems, this specifies the direction the node is facing. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks This function is not yet supported. When it is, it will be used to specify the direction a wireless node (typically one with a directional antenna) is facing. Example Orientation thisOrientation = {15, 0}; // 15 degrees clockwise from north. GUI_SetNodeOrientation(node->nodeId, thisOrientation, getSimTime(node)); Output Rotates the icon to the correct orientation, and uses the orientation for displaying antenna patterns.

9.5.6. GUI_SetNodeIcon
void GUI_SetNodeIcon( NodeAddress id, char* iconFile, clocktype time);

Routine GUI_SetNodeIcon
Return Value None

Required Headers gui.h

Parameters id This is the numeric identifier for the given node. In the Node structure, it is the nodeId struct member. iconFile This is the path to an image file to use to represent the node graphically. It can be specified either as an absolute path, or a relative path from QUALNET_HOME. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks This function is not yet supported. When it is, it will change the icon being used for a node. Output Changes the icon used to display the node graphically.

9.5.7. GUI_SetNodeLabel
void GUI_SetNodeLabel( NodeAddress id, char* label, clocktype time);

Routine GUI_SetNodeLabel
Return Value None

Required Headers gui.h

Parameters id This is the numeric identifier for the given node. In the Node structure, it is the nodeId struct member. label This is a name to display next to the node in lieu of its ID. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks This function is not yet supported by the GUI. When it is, it will set the string to be used as a label for the node. Output Changes the label on the node.

9.5.8. GUI_SetNodeRange
void GUI_SetNodeRange( NodeAddress id, double range, clocktype time);

Routine GUI_SetNodeRange
Return Value None

Required Headers gui.h

Parameters id This is the numeric identifier for the given node. In the Node structure, it is the nodeId struct member. range The uninhibited propagation range, in meters, of this nodes wireless radio, assuming that both the sender and receiver are using omni-directional antennas. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks Changes the range of a wireless node, which is used to display wireless transmissions. Output Changes the circumference of the circles used to display a wireless broadcast.

9.5.9. GUI_SetNodeType
void GUI_SetNodeType( NodeAddress id, int type, clocktype time);

Routine GUI_SetNodeType
Return Value None

Required Headers gui.h

Parameters id This is the numeric identifier for the given node. In the Node structure, it is the nodeId struct member. type A user-defined integer value representing the type of the node, for example a role the node is playing. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks This function is not yet supported by the Animator. When it is, it will specify the type of the node, which might be used to change the way the node is displayed on the screen. Example #define GATEWAY_NODE 1 #define SIMPLE_NODE 2 node->guiProperties.type = GATEWAY_NODE; GUI_SetNodeType(node->nodeId, node->guiProperties.type, getSimTime(node)); Output This is an example of a hypothetical ad hoc protocol that dynamically assigns roles to nodes. Most are simple nodes, but others are gateways between node groups. Used in conjunction with GUI_SetEffect, the developer can specify how nodes of different types are displayed.

9.5.10.

GUI_SetPatternIndex

void GUI_SetPatternIndex( NodeAddress nodeID, int index, clocktype time);

Routine GUI_SetPatternIndex
Return Value None

Required Headers gui.h

Parameters nodeID This is the numeric identifier for the given node. In the Node structure, it is the nodeId struct member. index This is an index into the nodes antenna pattern array. The value 1 is defined as the omni-directional pattern. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks If Antenna pattern animation is enabled, this function may change the shape of the antenna pattern displayed for this node. For proper operation, the node should have specified an antenna pattern file in the GUI_InitNode function. Example GUI_SetPatternIndex(node->nodeId, ANTENNA_OMNIDIRECTIONAL_PATTERN, getSimTime(node)); Output This example sets the nodes antenna pattern to the default omni-directional pattern.

9.5.11.

GUI_SetPatternAndAngle

void GUI_SetPatternAndAngle( NodeAddress nodeID, int index, int angleInDegrees, clocktype time);

Routine GUI_SetPatternIndex
Return Value None

Required Headers gui.h

Parameters nodeID This is the numeric identifier for the given node. In the Node structure, it is the nodeId struct member. index This is an index into the nodes antenna pattern array. The value 1 is defined as the omni-directional pattern. angleInDegrees This represents the azimuth angle to which the antenna is steered. It is relative to the orientation of the node. Thus if the nodes azimuth is 30 degrees, and this value is 40 degrees, the antenna pattern will be focused at 70 degrees. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks If Antenna pattern animation is enabled, this function may change the shape of the antenna pattern displayed for this node. For proper operation, the node should have specified an antenna pattern file in the GUI_InitNode function. This version of the function is typically used for steerable antennas, where the selected pattern can also be steered to focus at a different angle. Example GUI_SetPatternAndAngle(node->nodeId, ANTENNA_OMNIDIRECTIONAL_PATTERN, 0, getSimTime(node)); Output This example sets the nodes antenna pattern to the default omni-directional pattern with no steering angle.

9.5.12.

GUI_AddLink

void GUI_AddLink( NodeAddress source, NodeAddress dest, GuiLayers layer, int type, NodeAddress subnetAddress, int numHostBits, clocktype time);

Routine GUI_AddLink
Return Value None

Required Headers gui.h

Parameters source This is the numeric identifier for the given source node. In the Node structure, it is the nodeId struct member. dest This is the numeric identifier for the given destination node. In the Node structure, it is the nodeId struct member. layer This is the protocol layer at which this link is relevant, e.g. GUI_NETWORK_LAYER, GUI_TRANSPORT_LAYER, GUI_APP_LAYER. subnetAddress and numHostBits These are optional fields for when the function is used to create a subnet link, and are used by the Animator to correctly assign IP numbers to nodes. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks Adds a link between two nodes. In a wired topology, this could represent a point to point connection between the two nodes. In wireless, it might represent a link on a dynamic route. Or it might be used to represent on open telnet session. Only one link between two nodes will be shown (per layer). If GUI_AddLink is called when a link already exists, the "type" of the link will be updated. Example GUI_AddLink(client->nodeAddr, server->nodeAddr, GUI_APPLICATION_LAYER, GUI_DEFAULT_LINK_TYPE, getSimTime(node)); Output This example adds an application link between a pair of client and server nodes in the GUI.

9.5.13.

GUI_DeleteLink

void GUI_DeleteLink( NodeAddress source, NodeAddress dest, GuiLayers layer, clocktype time);

Routine GUI_DeleteLink
Return Value None

Required Headers gui.h

Parameters source This is the numeric identifier for the given source node. In the Node structure, it is the nodeId struct member. dest This is the numeric identifier for the given destination node. In the Node structure, it is the nodeId struct member. layer This is the protocol layer at which this link is relevant, e.g. GUI_NETWORK_LAYER, GUI_TRANSPORT_LAYER, GUI_APP_LAYER. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks The function will remove the link at the specified layer, no matter the type. The type doesn't matter because only one link will be shown for each layer. Example GUI_DeleteLink(client->nodeAddr, server->nodeAddr, GUI_APPLICATION_LAYER, getSimTime(node)); Output This example removes an application link between a pair of client and server nodes in the GUI.

9.5.14.

GUI_Broadcast

void GUI_Broadcast( NodeAddress source, GuiLayers layer, int type, NodeAddress interfaceAddress, clocktype time);

Routine GUI_Broadcast
Return Value None

Required Headers gui.h

Parameters source This is the numeric identifier for the given source node. In the Node structure, it is the nodeId struct member. layer This is the protocol layer at which this link is relevant, e.g. GUI_NETWORK_LAYER, GUI_TRANSPORT_LAYER, GUI_APP_LAYER. type This is the user-defined type of broadcast. interfaceAddress Primarily for wired nodes, this indicates on which connected network the broadcast should be displayed. A default value can be specified for wireless nodes, or those with only one interface. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks Indicates a broadcast. Typically, broadcasts will occur at the routing protocol or below. Radios will always broadcast. Example GUI_Broadcast(node->nodeId, GUI_PHY_LAYER, GUI_DEFAULT_DATA_TYPE, GUI_DEFAULT_INTERFACE, node-> getSimTime(node)); Output This example executes a radio broadcast from the node identified by nodeId.

9.5.15.

GUI_EndBroadcast

void GUI_EndBroadcast( NodeAddress source, GuiLayers layer, int type, NodeAddress interfaceAddress, clocktype time);

Routine GUI_EndBroadcast
Return Value None

Required Headers gui.h

Parameters source This is the numeric identifier for the given source node. In the Node structure, it is the nodeId struct member. layer This is the protocol layer at which this link is relevant, e.g. GUI_NETWORK_LAYER, GUI_TRANSPORT_LAYER, GUI_APP_LAYER. type This is the user-defined type of broadcast. interfaceAddress Primarily for wired nodes, this indicates on which connected network the broadcast should be displayed. A default value can be specified for wireless nodes, or those with only one interface. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks To help the Animator with the timing of animation events, a wireless broadcast now requires an explicit matching call to EndBroadcast. Output This example erases a radio broadcast from the node identified by nodeId.

9.5.16.

GUI_Multicast

void GUI_Multicast( NodeAddress source, GuiLayers layer, int type, NodeAddress interfaceAddress, clocktype time);

Routine GUI_Multicast
Return Value None

Required Headers gui.h

Parameters source This is the numeric identifier for the given source node. In the Node structure, it is the nodeId struct member. layer This is the protocol layer at which this link is relevant, e.g. GUI_NETWORK_LAYER, GUI_TRANSPORT_LAYER, GUI_APP_LAYER. type This is the user-defined type of multicast. interfaceAddress Primarily for wired nodes, this indicates on which connected network the broadcast should be displayed. A default value can be specified for wireless nodes, or those with only one interface. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks Indicates a multicast. I believe a multicast is only meaningful in certain routing protocols. The GUI currently supports this by treating it identically to GUI_Broadcast (Section 9.5.14). Example GUI_Multicast(node->nodeAddr, GUI_PHY_LAYER, GUI_DEFAULT_DATA_TYPE, GUI_DEFAULT_INTERFACE, getSimTime(node)); Output This example executes a multicast from the node identified by nodeId.

9.5.17.

GUI_Unicast

void GUI_Unicast( NodeAddress source, NodeAddress dest, GuiLayers layer, DataTypes type, clocktype time);

Routine GUI_Unicast
Return Value None

Required Headers gui.h

Parameters source This is the numeric identifier for the given source node. In the Node structure, it is the nodeId struct member. dest This is the numeric identifier for the given destination node. In the Node structure, it is the nodeId struct member. layer This is the protocol layer at which this link is relevant, e.g. GUI_NETWORK_LAYER, GUI_TRANSPORT_LAYER, GUI_APP_LAYER. type This is the user-defined type of unicast. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks Sends a unicast packet/frame/signal to a destination. Will probably be drawn as a temporary line between source and destination, followed by a signal (at the receiver) indicating success or failure. Example GUI_Unicast(node->nodeAddr, destAddr, GUI_PHY_LAYER, GUI_DEFAULT_DATA_TYPE, getSimTime(node)); Output This example executes a unicast from the node identified by nodeId.

9.5.18.

GUI_Receive

void GUI_Receive( NodeAddress source, NodeAddress dest, GuiLayers layer, int type, clocktype time);

Routine GUI_Receive
Return Value None

Required Headers gui.h

Parameters source This is the numeric identifier for the given source node. In the Node structure, it is the nodeId struct member. dest This is the numeric identifier for the given destination node. In the Node structure, it is the nodeId struct member. layer This is the protocol layer at which this link is relevant, e.g. GUI_NETWORK_LAYER, GUI_TRANSPORT_LAYER, GUI_APP_LAYER. type This is the user-defined type of unicast. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks Shows a successful receipt at a destination. Typically would follow a unicast, multicast, or broadcast. Example GUI_Receive(senderAddr, node->nodeAddr, GUI_PHY_LAYER, GUI_DEFAULT_DATA_TYPE, getSimTime(node)); Output This example instructs the GUI to indicate successful reception from the node identified by nodeId.

9.5.19.

GUI_Drop

void GUI_Drop( NodeAddress source, NodeAddress dest, GuiLayers layer, int type, clocktype time);

Routine GUI_Drop
Return Value None

Required Headers gui.h

Parameters source This is the numeric identifier for the given source node. In the Node structure, it is the nodeId struct member. dest This is the numeric identifier for the given destination node. In the Node structure, it is the nodeId struct member. layer This is the protocol layer at which this link is relevant, e.g. GUI_NETWORK_LAYER, GUI_TRANSPORT_LAYER, GUI_APP_LAYER. type This is the user-defined type of unicast. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks Shows a packet/frame/signal being dropped by a node. Typically would follow a broadcast or unicast at the same layer. Example GUI_Drop(senderId, node->nodeId, GUI_PHY_LAYER, GUI_DEFAULT_DATA_TYPE, getSimTime(node)); Output This example instructs the GUI to indicate a drop reception from the node identified by senderId to node->nodeId.

9.5.20.

GUI_Collision

void GUI_Collision( NodeAddress dest, GuiLayers layer, clocktype time);

Routine GUI_Collision
Return Value None

Required Headers gui.h

Parameters dest This is the numeric identifier for the given destination node. In the Node structure, it is the nodeId struct member. layer This is the protocol layer at which this link is relevant, e.g. GUI_NETWORK_LAYER, GUI_TRANSPORT_LAYER, GUI_APP_LAYER. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks Shows a node detecting a collision. Collisions are strictly a wireless animation issue for the GUI. Example GUI_Receive(senderId, node->nodeId, CHANNEL_LAYER, GUI_DEFAULT_DATA_TYPE, getSimTime(node)); Output This example instructs the GUI to indicate a successful reception from the node identified by senderId to node->nodeId.

9.5.21.

GUI_CreateSubnet

void GUI_CreateSubnet( int type, NodeAddress subnetAddress, int numHostBits, char* nodeList, clocktype time);

Routine GUI_CreateSubnet
Return Value None

Required Headers gui.h

Parameters type This is the type, wired or wireless, of the subnet. subnetAddress This is the base IP address of the subnet. numHostBits This is the size of the subnet. nodeList This is the list of node identifiers of the nodes in the subnet. It uses the same formatting conventions as the SUBNET variable, including the thru clause. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks The GUI does not yet fully support this function. Creates either a wired or wireless subnet. Wired subnets are drawn by connecting the nodes to a hub/switch object. Wireless subnets are typically color coded. This function must be called after GUI_InitNode is called for all nodes in the subnet, and is typically called during MAC layer initialization in the kernel code. Output A subnet is drawn.

9.5.22.

GUI_CreateHierarchy

void GUI_CreateHierarchy( int componentId, char* nodeList);

Routine GUI_CreateHierarchy
Return Value None

Required Headers gui.h

Parameters componentId This is an identifier assigned to a hierachical component by the GUI. nodeList This is a duplicate of the string printed by the GUI to identify the contents of this hierarchical component. Remarks This function is used to reconstruct a hierarchically designed experiment in the GUI. Users should not attempt to create hierarchies by hand. Output Draws the nodes in a hierarchical fashion.

9.5.23.

GUI_AddApplication

void GUI_AddApplication( NodeAddress source, NodeAddress dest, char* appName, int uniqueId, clocktype time);

Routine GUI_AddApplication
Return Value None

Required Headers gui.h

Parameters source This is the node ID of the application client. dest This is the node ID of the application server. appName This is the name of the type of application, e.g. CBR or FTP. uniqueId This is a unique identifier assigned to the application, for the purpose of distinction. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks This function adds a label to the client and server nodes to indicate that an application connection is set up between the two nodes. Need only be called by the client. Output A node label.

9.5.24.

GUI_DeleteApplication

void GUI_DeleteApplication( NodeAddress source, NodeAddress dest, char* appName, int uniqueId, clocktype time);

Routine GUI_DeleteApplication
Return Value None

Required Headers gui.h

Parameters source This is the node ID of the application client. dest This is the node ID of the application server. appName This is the name of the type of application, e.g. CBR or FTP. uniqueId This is a unique identifier assigned to the application, for the purpose of distinction. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks This function removes a label from the client and server nodes indicating that an application connection is set up between the two nodes. Need only be called by the client. Output Removes a node label.

9.5.25.

GUI_AddInterfaceQueue

void GUI_AddInterfaceQueue( NodeAddress node, GuiLayers layer, int interfaceId, unsigned int priority, int queuesize, clocktype time);

Routine GUI_AddInterfaceQueue
Return Value None

Required Headers gui.h

Parameters node This is the identifier of the node adding the queue. layer This is protocol layer where the queue is implemented. interfaceId This is the interface on which the queue is located, if the node has more than one interface. priority This is the priority associated with the queue. queuesize This is the queue size in bytes. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks This function is not yet implemented in the GUI. This function will display a queue, or set of queues, next to the node during animation of the simulation. Output A queue outline.

9.5.26.

GUI_QueueInsertPacket

void GUI_QueueInsertPacket( NodeAddress node, GuiLayers layer, int interfaceId, unsigned int priority, int packetSize, clocktype time);

Routine GUI_QueueInsertPacket
Return Value None

Required Headers gui.h

Parameters node This is the identifier of the node adding the queue. layer This is protocol layer where the queue is implemented. interfaceId This is the interface on which the queue is located, if the node has more than one interface. priority This is the priority associated with the queue. packetSize This is the size, in bytes, of the packet. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks This function is not yet implemented in the GUI. This function adds a packet to a queue being displayed on the GUI. Output Adds an appropriately sized packet block to a queue.

9.5.27.

GUI_QueueDequeuePacket

void GUI_QueueDequeuePacket( NodeAddress node, GuiLayers layer, int interfaceId, unsigned int priority, int packetSize, clocktype time);

Routine GUI_QueueDequeuePacket
Return Value None

Required Headers gui.h

Parameters node This is the identifier of the node adding the queue. layer This is protocol layer where the queue is implemented. interfaceId This is the interface on which the queue is located, if the node has more than one interface. priority This is the priority associated with the queue. packetSize This is the size, in bytes, of the packet. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks This function is not yet implemented in the GUI. This function removes a packet from the displayed queue. Output Reduces the displayed queue size by the size of the removed packet.

9.5.28.

GUI_QueueDropPacket

void GUI_QueueDropPacket( NodeAddress node, GuiLayers layer, int interfaceId, unsigned int priority, clocktype time);

Routine GUI_QueueDropPacket
Return Value None

Required Headers gui.h

Parameters node This is the identifier of the node adding the queue. layer This is protocol layer where the queue is implemented. interfaceId This is the interface on which the queue is located, if the node has more than one interface. priority This is the priority associated with the queue. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks This function is not yet implemented in the GUI. This function shows a packet being dropped from the queue. Output A packet of the given size is dropped from the queue.

9.5.29.

GUI_DefineMetric

int GUI_DefineMetric( char* name, NodeAddress nodeID, GuiLayers layer, int linkID, GuiDataTypes datatype, GuiMetrics metrictype);

Routine GUI_DefineMetric

Required Headers gui.h

Return Value An integer identifying the metric. This integer should be used in future calls to GUI_SendIntegerData and GUI_SendRealData. Parameters metricName This is a string containing the name of the metric, e.g. packets dropped. nodeID This is the identifier of the node defining the metric. layer This is layer associated with the metric. linkID This is an identifier used to associate a metric with a link, for example an application connection, rather than a node. datatype This is the type of the data, integer or floating point. metrictype This is the analytical type of the data, e.g. a cumulative total, or a running average. Remarks This function is used to register a statistical variable for generating dynamic graphs during a simulation. This function should generally be called during initialization. The integer value returned should be used in subsequent calls to the GUI_Send*Data calls described subsequently. Routing protocols should use the protocol layer where the particular protocol resides, rather than the generic GUI_ROUTING_LAYER. Output The GUI lists all the metrics, allowing the user to choose statistics to graph dynamically.

9.5.30.

GUI_SendIntegerData

void GUI_SendIntegerData( NodeAddress node, int metricID, int value, clocktype time);

Routine GUI_SendIntegerData
Return Value None

Required Headers gui.h

Parameters node This is the identifier of the node sending the data. metricID This is the identifier for the metric returned from GUI_DefineMetric. value This is the value. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks Each protocol should implement a RunTimeStat function, and ensure that this function is called from the master RunTimeStat function for that layer. For example, the master function for the network layer, NETWORK_RunTimeStat calls the corresponding function for the IP protocol, NetworkIpRunTimeStat. All calls to GUI_Send*Data should be placed in the RunTimeStat function. This allows the Animator to control the frequency of updates. It is also possible to call this function each time a metric is updated. In this case, the Animator will not be able to control the rate of sampling. Output Dynamically generated graphs.

9.5.31.

GUI_SendRealData

void GUI_SendRealData( SubnetType type, int metricID, double value, clocktype time);

Routine GUI_SendRealData
Return Value None

Required Headers gui.h

Parameters node This is the identifier of the node sending the data. metricID This is the identifier for the metric returned from GUI_DefineMetric. value This is the value. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks See the remarks in Section 9.5.30. Output Dynamically generated graphs.

9.5.32.

GUI_SendUnsignedData

void GUI_SendUnsignedData( SubnetType type, int metricID, double value, clocktype time);

Routine GUI_SendUnsignedData
Return Value None

Required Headers gui.h

Parameters node This is the identifier of the node sending the data. metricID This is the identifier for the metric returned from GUI_DefineMetric. value This is the value. time This is the current simulation time (returned by getSimTime(node). See Section 9.2.1). Remarks See the remarks in Section 9.5.30. Output Dynamically generated graphs.

9.6.

Statistics Output API Functions

Statistics Output Functions are used to print statistics data from each protocol to the standard QualNet experiments statistical output text file. There is currently one function that falls into this category.

9.6.1. IO_PrintStat
void IO_PrintStat( Node *node, const char *layer, const char *protocol, NodeAddress interfaceAddress, int instanceId, const char *buf);

Routine GUI_PrintStat
Return Value None

Required Headers api.h

Parameters node Pointer to the Node structure containing the calling nodes data space layer This is the name of the layer at which this statistic is relevant. protocol This is the name of the protocol for which this statistic is relevant. interfaceAddress This is the IP address for which this statistic is relevant, if statistics are recorded per Network Interface. If IP address is not relevant for this statistic, use the constant ANY_DEST. instanceId This is the instance of the protocol for which this statistic is relevant, if statistics are recorded for multiple instances on one interfaceAddress. If multiple instances are not relevant for this statistic, use the value -1. buf This is the statistic, in the form of a character array, usually created with sprintf to be a verbose description of the statistic being reported. Example IO_PrintStat(node, Network, MyProtocol, ANY_DEST, -1, buf);

Output The contents of buf will be printed to the QualNet Statistical Output File as a statistic reported by MyProtocol for the given node.

9.7.

Error/Assertion Related API Functions

Error Functions are used to report error conditions to the user, whether they are executing QualNet via the command-line, or the GUI. The ERROR_ReportError API function is provided to give the protocol modeler a single interface from which to communicate these error conditions to the user, and debug their own models. Assertion Functions are used to debug protocol models and code by inserting sanity checks (e.g., assert that there are actually packets in the queue I am attempting to dequeue from, before I reference the contents of a NULL pointer). However, these differ from Error Functions because they should ultimately be removed from the executable to reduce overhead, once it is determined that the sanity check never fails, and can be removed by defining NDEBUG at compile-time. The ERROR_Assert API function is provided to address the need for Assertion Functions. These API functions differ from their standard C counterparts in that they provide information to the GUI-initiated QualNet simulations as well as the command-line simulations.

9.7.1. ERROR_ReportError
void ERROR_ReportError( char *msg);

Routine ERROR_ReportError

Required Headers error.h

Return Value None. Simulation exits and prints msg. Parameters msg This is the error message to print, either to the GUI or the standard output, if QualNet is running at the command-line. Example ERROR_ReportError( Pointer to the packet is NULL); Output The contents of msg will be printed to the screen or a GUI error window, and then the simulation will exit.

9.7.2. ERROR_Assert
void ERROR_Assert( condition, char *msg);

Routine ERROR_Assert

Required Headers error.h

Return Value None. Simulation exits and prints msg if the condition evaluates to FALSE. Parameters condition This is a Boolean condition that under all sane conditions should evaluate to TRUE, but given that the programmer may not have considered all possible permutations, we wish to doublecheck. If this condition ever evaluates to FALSE, it indicates a logic or programming error that must immediately be addressed. msg This is the error message to print, either to the GUI or the standard output, if QualNet is running at the command-line. This error message provides some additional detail about the unexpected event.

Example ERROR_Assert((ptr != NULL), Pointer to the packet is NULL); Output The line number and filename of the ERROR_Assert call, and the contents of msg will be printed to the screen or a GUI error window, and then the simulation will exit, if condition evaluates to FALSE.