80 call.  As was seen earlier in the tutorial, the logging system has Doxygen 

    80 call.  As was seen earlier in the tutorial, the logging system has Doxygen 

    81 documentation and now would be a good time to peruse the Logging Module 

    81 documentation and now would be a good time to peruse the Logging Module 

    82 documentation if you have not done so.

    82 documentation if you have not done so.

    83 

    83 

    84 Now that you have read the documentation in great detail, let's use some of

    84 Now that you have read the documentation in great detail, let's use some of

    87 

    87 

    88 @node Enabling Logging

    88 @node Enabling Logging

    89 @subsection Enabling Logging

    89 @subsection Enabling Logging

    90 @cindex NS_LOG

    90 @cindex NS_LOG

    91 Let's use the NS_LOG environment variable to turn on some more logging, but

    91 Let's use the NS_LOG environment variable to turn on some more logging, but

    92 to get our bearings, go ahead and run the script just as you did previously,

    92 to get our bearings, go ahead and run the script just as you did previously,

    93 

    93 

    94 @verbatim

    94 @verbatim

    96   Entering directory `/home/craigdo/repos/ns-3-dev/build'

   102   Entering directory `/home/craigdo/repos/ns-3-dev/build'

    97   Compilation finished successfully

   103   Compilation finished successfully

    98   Sent 1024 bytes to 10.1.1.2

   104   Sent 1024 bytes to 10.1.1.2

    99   Received 1024 bytes from 10.1.1.1

   105   Received 1024 bytes from 10.1.1.1

   100   Received 1024 bytes from 10.1.1.2

   106   Received 1024 bytes from 10.1.1.2

   106 @code{UdpEchoServerApplication}.  We can ask the client application, for 

   111 @code{UdpEchoServerApplication}.  We can ask the client application, for 

   107 example, to print more information by setting its logging level via the 

   112 example, to print more information by setting its logging level via the 

   108 NS_LOG environment variable.  

   113 NS_LOG environment variable.  

   109 

   114 

   110 I am going to assume from here on that are using an sh-like shell that uses 

   115 I am going to assume from here on that are using an sh-like shell that uses 

   111 the``VARIABLE=value'' syntax.  If you are using a csh-like shell, then you 

   116 the``VARIABLE=value'' syntax.  If you are using a csh-like shell, then you 

   112 will have to convert my examples to the ``setenv VARIABLE value'' syntax 

   117 will have to convert my examples to the ``setenv VARIABLE value'' syntax 

   113 required by those shells.

   118 required by those shells.

   114 

   119 

   115 Right now, the UDP echo client application is responding to the following line

   120 Right now, the UDP echo client application is responding to the following line

   117 

   122 

   118 @verbatim

   123 @verbatim

   119   LogComponentEnable("UdpEchoClientApplication", LOG_LEVEL_INFO);

   124   LogComponentEnable("UdpEchoClientApplication", LOG_LEVEL_INFO);

   120 @end verbatim

   125 @end verbatim

   121 

   126 

   125 @code{NS_LOG_DEBUG}, @code{NS_LOG_WARN} and @code{NS_LOG_ERROR}.  We can

   130 @code{NS_LOG_DEBUG}, @code{NS_LOG_WARN} and @code{NS_LOG_ERROR}.  We can

   126 increase the logging level and get more information without changing the

   131 increase the logging level and get more information without changing the

   127 script and recompiling by setting the NS_LOG environment variable like this:

   132 script and recompiling by setting the NS_LOG environment variable like this:

   128 

   133 

   129 @verbatim

   134 @verbatim

   131 @end verbatim

   136 @end verbatim

   132 

   137 

   133 This sets the shell environment variable @code{NS_LOG} to the string,

   138 This sets the shell environment variable @code{NS_LOG} to the string,

   134 

   139 

   135 @verbatim

   140 @verbatim

   141 we are going to turn on all of the debugging levels for the application.  If

   146 we are going to turn on all of the debugging levels for the application.  If

   142 you run the script with NS_LOG set this way, the @command{ns-3} logging 

   147 you run the script with NS_LOG set this way, the @command{ns-3} logging 

   143 system will pick up the change and you should see the following output:

   148 system will pick up the change and you should see the following output:

   144 

   149 

   145 @verbatim

   150 @verbatim

   149   UdpEchoClientApplication:UdpEchoClient()

   153   UdpEchoClientApplication:UdpEchoClient()

   150   UdpEchoClientApplication:StartApplication()

   154   UdpEchoClientApplication:StartApplication()

   151   UdpEchoClientApplication:ScheduleTransmit()

   155   UdpEchoClientApplication:ScheduleTransmit()

   152   UdpEchoClientApplication:Send()

   156   UdpEchoClientApplication:Send()

   153   Sent 1024 bytes to 10.1.1.2

   157   Sent 1024 bytes to 10.1.1.2

   154   Received 1024 bytes from 10.1.1.1

   158   Received 1024 bytes from 10.1.1.1

   156   Received 1024 bytes from 10.1.1.2

   160   Received 1024 bytes from 10.1.1.2

   157   UdpEchoClientApplication:StopApplication()

   161   UdpEchoClientApplication:StopApplication()

   158   UdpEchoClientApplication:DoDispose()

   162   UdpEchoClientApplication:DoDispose()

   159   UdpEchoClientApplication:~UdpEchoClient()

   163   UdpEchoClientApplication:~UdpEchoClient()

   161 @end verbatim

   164 @end verbatim

   162 

   165 

   163 The additional debug information provided by the application is from

   166 The additional debug information provided by the application is from

   164 the NS_LOG_FUNCTION level.  This shows every time a function in the application

   167 the NS_LOG_FUNCTION level.  This shows every time a function in the application

   165 is called during script execution.  Note that there are no requirements in the

   168 is called during script execution.  Note that there are no requirements in the

   196 Now, if you run the script you will see that the logging system makes sure 

   199 Now, if you run the script you will see that the logging system makes sure 

   197 that every message from the given log component is prefixed with the component

   200 that every message from the given log component is prefixed with the component

   198 name.

   201 name.

   199 

   202 

   200 @verbatim

   203 @verbatim

   204   UdpEchoClientApplication:UdpEchoClient()

   206   UdpEchoClientApplication:UdpEchoClient()

   205   UdpEchoClientApplication:StartApplication()

   207   UdpEchoClientApplication:StartApplication()

   206   UdpEchoClientApplication:ScheduleTransmit()

   208   UdpEchoClientApplication:ScheduleTransmit()

   207   UdpEchoClientApplication:Send()

   209   UdpEchoClientApplication:Send()

   208   UdpEchoClientApplication:Send(): Sent 1024 bytes to 10.1.1.2

   210   UdpEchoClientApplication:Send(): Sent 1024 bytes to 10.1.1.2

   209   Received 1024 bytes from 10.1.1.1

   211   Received 1024 bytes from 10.1.1.1

   211   UdpEchoClientApplication:HandleRead(): Received 1024 bytes from 10.1.1.2

   213   UdpEchoClientApplication:HandleRead(): Received 1024 bytes from 10.1.1.2

   212   UdpEchoClientApplication:StopApplication()

   214   UdpEchoClientApplication:StopApplication()

   213   UdpEchoClientApplication:DoDispose()

   215   UdpEchoClientApplication:DoDispose()

   214   UdpEchoClientApplication:~UdpEchoClient()

   216   UdpEchoClientApplication:~UdpEchoClient()

   216 @end verbatim

   217 @end verbatim

   217 

   218 

   218 You can now see all of the messages coming from the UDP echo client application

   219 You can now see all of the messages coming from the UDP echo client application

   219 are identified as such.  The message ``Received 1024 bytes from 10.1.1.2'' is

   220 are identified as such.  The message ``Received 1024 bytes from 10.1.1.2'' is

   220 now clearly identified as coming from the echo client application.  The 

   221 now clearly identified as coming from the echo client application.  The 

   225 @verbatim

   226 @verbatim

   226   export 'NS_LOG=UdpEchoClientApplication=level_all|prefix_func:

   227   export 'NS_LOG=UdpEchoClientApplication=level_all|prefix_func:

   227                  UdpEchoServerApplication=level_all|prefix_func'

   228                  UdpEchoServerApplication=level_all|prefix_func'

   228 @end verbatim

   229 @end verbatim

   229 

   230 

   232 

   233 

   233 Now, if you run the script you will see all of the log messages from both the

   234 Now, if you run the script you will see all of the log messages from both the

   234 echo client and server applications.  You may see that this can be very useful

   235 echo client and server applications.  You may see that this can be very useful

   235 in debugging problems.

   236 in debugging problems.

   236 

   237 

   237 @verbatim

   238 @verbatim

   241   UdpEchoServerApplication:UdpEchoServer()

   241   UdpEchoServerApplication:UdpEchoServer()

   242   UdpEchoClientApplication:UdpEchoClient()

   242   UdpEchoClientApplication:UdpEchoClient()

   243   UdpEchoServerApplication:StartApplication()

   243   UdpEchoServerApplication:StartApplication()

   244   UdpEchoClientApplication:StartApplication()

   244   UdpEchoClientApplication:StartApplication()

   245   UdpEchoClientApplication:ScheduleTransmit()

   245   UdpEchoClientApplication:ScheduleTransmit()

   246   UdpEchoClientApplication:Send()

   246   UdpEchoClientApplication:Send()

   247   UdpEchoClientApplication:Send(): Sent 1024 bytes to 10.1.1.2

   247   UdpEchoClientApplication:Send(): Sent 1024 bytes to 10.1.1.2

   248   UdpEchoServerApplication:HandleRead(): Received 1024 bytes from 10.1.1.1

   248   UdpEchoServerApplication:HandleRead(): Received 1024 bytes from 10.1.1.1

   249   UdpEchoServerApplication:HandleRead(): Echoing packet

   249   UdpEchoServerApplication:HandleRead(): Echoing packet

   251   UdpEchoClientApplication:HandleRead(): Received 1024 bytes from 10.1.1.2

   251   UdpEchoClientApplication:HandleRead(): Received 1024 bytes from 10.1.1.2

   252   UdpEchoServerApplication:StopApplication()

   252   UdpEchoServerApplication:StopApplication()

   253   UdpEchoClientApplication:StopApplication()

   253   UdpEchoClientApplication:StopApplication()

   254   UdpEchoClientApplication:DoDispose()

   254   UdpEchoClientApplication:DoDispose()

   255   UdpEchoServerApplication:DoDispose()

   255   UdpEchoServerApplication:DoDispose()

   256   UdpEchoClientApplication:~UdpEchoClient()

   256   UdpEchoClientApplication:~UdpEchoClient()

   257   UdpEchoServerApplication:~UdpEchoServer()

   257   UdpEchoServerApplication:~UdpEchoServer()

   259 @end verbatim

   258 @end verbatim

   260 

   259 

   261 It is also sometimes useful to be able to see the simulation time at which a

   260 It is also sometimes useful to be able to see the simulation time at which a

   262 log message is generated.  You can do this by ORing in the prefix_time bit.

   261 log message is generated.  You can do this by ORing in the prefix_time bit.

   263 

   262 

   264 @verbatim

   263 @verbatim

   265   export 'NS_LOG=UdpEchoClientApplication=level_all|prefix_func|prefix_time:

   264   export 'NS_LOG=UdpEchoClientApplication=level_all|prefix_func|prefix_time:

   266                  UdpEchoServerApplication=level_all|prefix_func|prefix_time'

   265                  UdpEchoServerApplication=level_all|prefix_func|prefix_time'

   267 @end verbatim

   266 @end verbatim

   268 

   267 

   275   0s UdpEchoServerApplication:UdpEchoServer()

   274   0s UdpEchoServerApplication:UdpEchoServer()

   276   0s UdpEchoClientApplication:UdpEchoClient()

   275   0s UdpEchoClientApplication:UdpEchoClient()

   277   1s UdpEchoServerApplication:StartApplication()

   276   1s UdpEchoServerApplication:StartApplication()

   278   2s UdpEchoClientApplication:StartApplication()

   277   2s UdpEchoClientApplication:StartApplication()

   279   2s UdpEchoClientApplication:ScheduleTransmit()

   278   2s UdpEchoClientApplication:ScheduleTransmit()

   280   2s UdpEchoClientApplication:Send()

   279   2s UdpEchoClientApplication:Send()

   281   2s UdpEchoClientApplication:Send(): Sent 1024 bytes to 10.1.1.2

   280   2s UdpEchoClientApplication:Send(): Sent 1024 bytes to 10.1.1.2

   282   2.00369s UdpEchoServerApplication:HandleRead(): Received 1024 bytes from 10.1.1.1

   281   2.00369s UdpEchoServerApplication:HandleRead(): Received 1024 bytes from 10.1.1.1

   283   2.00369s UdpEchoServerApplication:HandleRead(): Echoing packet

   282   2.00369s UdpEchoServerApplication:HandleRead(): Echoing packet

   285   2.00737s UdpEchoClientApplication:HandleRead(): Received 1024 bytes from 10.1.1.2

   284   2.00737s UdpEchoClientApplication:HandleRead(): Received 1024 bytes from 10.1.1.2

   286   10s UdpEchoServerApplication:StopApplication()

   285   10s UdpEchoServerApplication:StopApplication()

   287   10s UdpEchoClientApplication:StopApplication()

   286   10s UdpEchoClientApplication:StopApplication()

   288   UdpEchoClientApplication:DoDispose()

   287   UdpEchoClientApplication:DoDispose()

   289   UdpEchoServerApplication:DoDispose()

   288   UdpEchoServerApplication:DoDispose()

   290   UdpEchoClientApplication:~UdpEchoClient()

   289   UdpEchoClientApplication:~UdpEchoClient()

   291   UdpEchoServerApplication:~UdpEchoServer()

   290   UdpEchoServerApplication:~UdpEchoServer()

   293 @end verbatim

   291 @end verbatim

   294 

   292 

   295 You can see that the constructor for the UdpEchoServer was called at a 

   293 You can see that the constructor for the UdpEchoServer was called at a 

   296 simulation time of 0 seconds.  This is actually happening before the 

   294 simulation time of 0 seconds.  This is actually happening before the 

   297 simulation starts.  The same for the UdpEchoClient constructor.

   295 simulation starts.  The same for the UdpEchoClient constructor.

   298 

   296 

   301 @code{StartApplication} method of the server is, in fact, called at one second

   299 @code{StartApplication} method of the server is, in fact, called at one second

   302 (or one billion nanoseconds).  You can also see that the echo client 

   300 (or one billion nanoseconds).  You can also see that the echo client 

   303 application is started at a simulation time of two seconds as we requested in

   301 application is started at a simulation time of two seconds as we requested in

   304 the script.

   302 the script.

   305 

   303 

   320   export 'NS_LOG=*=level_all|prefix_func|prefix_time'

   318   export 'NS_LOG=*=level_all|prefix_func|prefix_time'

   321 @end verbatim

   319 @end verbatim

   322 

   320 

   323 The asterisk above is the logging component wildcard.  This will turn on all 

   321 The asterisk above is the logging component wildcard.  This will turn on all 

   324 of the logging in all of the components used in the simulation.  I won't 

   322 of the logging in all of the components used in the simulation.  I won't 

   326 for the single packet echo) but you can redirect this information into a file 

   324 for the single packet echo) but you can redirect this information into a file 

   327 and look through it with your favorite editor if you like,

   325 and look through it with your favorite editor if you like,

   328 

   326 

   329 @verbatim

   327 @verbatim

   342 

   340 

   343 @node Adding Logging to your Code

   341 @node Adding Logging to your Code

   344 @subsection Adding Logging to your Code

   342 @subsection Adding Logging to your Code

   345 @cindex NS_LOG

   343 @cindex NS_LOG

   346 You can add new logging to your simulations by making calls to the log 

   344 You can add new logging to your simulations by making calls to the log 

   348 have in the @code{scratch} directory.

   346 have in the @code{scratch} directory.

   349 

   347 

   350 Recall that we have defined a logging component in that script:

   348 Recall that we have defined a logging component in that script:

   351 

   349 

   352 @verbatim

   350 @verbatim

   355 

   353 

   356 You now know that you can enable all of the logging for this component by

   354 You now know that you can enable all of the logging for this component by

   357 setting the @code{NS_LOG} environment variable to the various levels.  Let's

   355 setting the @code{NS_LOG} environment variable to the various levels.  Let's

   358 go ahead add some logging to the script.  The macro used to add an 

   356 go ahead add some logging to the script.  The macro used to add an 

   359 informational level log message is @code{NS_LOG_INFO}.  Go ahead and add one 

   357 informational level log message is @code{NS_LOG_INFO}.  Go ahead and add one 

   361 ``Creating Topology.''  This is done as in this code snippet,

   359 ``Creating Topology.''  This is done as in this code snippet,

   362 

   360 

   363 @verbatim

   363 @verbatim

   364   NS_LOG_INFO ("Creating Topology");

   364   NS_LOG_INFO ("Creating Topology");

   365 @end verbatim

   372 @end verbatim

   366 

   373 

   367 Now build the script using waf and clear the @code{NS_LOG} variable to turn 

   374 Now build the script using waf and clear the @code{NS_LOG} variable to turn 

   368 off the torrent of logging we previously enabled:

   375 off the torrent of logging we previously enabled:

   369 

   376 

   370 @verbatim

   377 @verbatim

   383 @end verbatim

   396 @end verbatim

   384 

   397 

   385 If you now run the script you will see your new ``Creating Topology'' log

   398 If you now run the script you will see your new ``Creating Topology'' log

   386 message,

   399 message,

   387 

   400 

   388 @verbatim

   401 @verbatim

   392   Creating Topology

   404   Creating Topology

   393   Sent 1024 bytes to 10.1.1.2

   405   Sent 1024 bytes to 10.1.1.2

   394   Received 1024 bytes from 10.1.1.1

   406   Received 1024 bytes from 10.1.1.1

   395   Received 1024 bytes from 10.1.1.2

   407   Received 1024 bytes from 10.1.1.2

   397 @end verbatim

   408 @end verbatim

   398 

   409 

   399 @c ========================================================================

   410 @c ========================================================================

   400 @c Using Command Line Arguments

   411 @c Using Command Line Arguments

   401 @c ========================================================================

   412 @c ========================================================================

   426   }

   437   }

   427 @end verbatim

   438 @end verbatim

   428 

   439 

   429 This simple two line snippet is actually very useful by itself.  It opens the

   440 This simple two line snippet is actually very useful by itself.  It opens the

   430 door to the @command{ns-3} global variable and attribute systems.  Go ahead 

   441 door to the @command{ns-3} global variable and attribute systems.  Go ahead 

   433 for help in the following way,

   444 for help in the following way,

   434 

   445 

   435 @verbatim

   446 @verbatim

   440 line argument @code{--PrintHelp} to the script.  The quotes are required to 

   451 line argument @code{--PrintHelp} to the script.  The quotes are required to 

   441 sort out which program gets which argument.  The command line parser will

   452 sort out which program gets which argument.  The command line parser will

   442 now see the @code{--PrintHelp} argument and respond with,

   453 now see the @code{--PrintHelp} argument and respond with,

   443 

   454 

   444 @verbatim

   455 @verbatim

   448   --PrintHelp: Print this help message.

   458   --PrintHelp: Print this help message.

   449   --PrintGroups: Print the list of groups.

   459   --PrintGroups: Print the list of groups.

   450   --PrintTypeIds: Print all TypeIds.

   460   --PrintTypeIds: Print all TypeIds.

   451   --PrintGroup=[group]: Print all TypeIds of group.

   461   --PrintGroup=[group]: Print all TypeIds of group.

   452   --PrintAttributes=[typeid]: Print all attributes of typeid.

   462   --PrintAttributes=[typeid]: Print all attributes of typeid.

   453   --PrintGlobals: Print the list of globals.

   463   --PrintGlobals: Print the list of globals.

   455 @end verbatim

   464 @end verbatim

   456 

   465 

   457 Let's focus on the @code{--PrintAttributes} option.  We have already hinted

   466 Let's focus on the @code{--PrintAttributes} option.  We have already hinted

   458 at the @command{ns-3} attribute system while walking through the 

   467 at the @command{ns-3} attribute system while walking through the 

   459 @code{first.cc} script.  We looked at the following lines of code,

   468 @code{first.cc} script.  We looked at the following lines of code,

   470 listing says that we should provide a @code{TypeId}.  This corresponds to the

   479 listing says that we should provide a @code{TypeId}.  This corresponds to the

   471 class name of the class to which the attributes belong.  In this case it will

   480 class name of the class to which the attributes belong.  In this case it will

   472 be @code{ns3::PointToPointNetDevice}.  Let's go ahead and type in,

   481 be @code{ns3::PointToPointNetDevice}.  Let's go ahead and type in,

   473 

   482 

   474 @verbatim

   483 @verbatim

   476 @end verbatim

   485 @end verbatim

   477 

   486 

   478 The system will print out all of the attributes of this kind of net device.

   487 The system will print out all of the attributes of this kind of net device.

   479 Among the attributes you will see listed is,

   488 Among the attributes you will see listed is,

   480 

   489 

   516 @end verbatim

   525 @end verbatim

   517 

   526 

   518 If you run the script, you should now see the following output,

   527 If you run the script, you should now see the following output,

   519 

   528 

   520 @verbatim

   529 @verbatim

   526   Sent 1024 bytes to 10.1.1.2

   533   Sent 1024 bytes to 10.1.1.2

   529   Received 1024 bytes from 10.1.1.2

   536   Received 1024 bytes from 10.1.1.2

   531   UdpEchoServerApplication:DoDispose()

   538   UdpEchoServerApplication:DoDispose()

   532   UdpEchoServerApplication:~UdpEchoServer()

   539   UdpEchoServerApplication:~UdpEchoServer()

   534 @end verbatim

   540 @end verbatim

   535 

   541 

   536 Recall that the last time we looked at the simulation time at which the packet

   542 Recall that the last time we looked at the simulation time at which the packet

   539 the data rate of the @code{PointToPointNetDevice} down to its default of 

   550 the data rate of the @code{PointToPointNetDevice} down to its default of 

   540 32768 bits per second from five megabits per second.

   551 32768 bits per second from five megabits per second.

   541 

   552 

   542 If we were to provide a new @code{DataRate} using the command line, we could 

   553 If we were to provide a new @code{DataRate} using the command line, we could 

   543 speed our simulation up again.  We do this in the following way, according to

   554 speed our simulation up again.  We do this in the following way, according to

   544 the formula implied by the help item:

   555 the formula implied by the help item:

   545 

   556 

   546 @verbatim

   557 @verbatim

   548 @end verbatim

   559 @end verbatim

   549 

   560 

   550 This will set the default value of the @code{DataRate} attribute back to 

   561 This will set the default value of the @code{DataRate} attribute back to 

   558 @end verbatim

   570 @end verbatim

   559 

   571 

   560 We discover the @code{Delay} attribute of the channel is set in the following

   572 We discover the @code{Delay} attribute of the channel is set in the following

   561 way:

   573 way:

   562 

   574 

   566 @end verbatim

   578 @end verbatim

   567 

   579 

   568 We can then set both of these default values through the command line system,

   580 We can then set both of these default values through the command line system,

   569 

   581 

   570 @verbatim

   582 @verbatim

   572     --ns3::PointToPointNetDevice::DataRate=5Mbps

   584     --ns3::PointToPointNetDevice::DataRate=5Mbps

   573     --ns3::PointToPointChannel::Delay=2ms"

   585     --ns3::PointToPointChannel::Delay=2ms"

   574 @end verbatim

   586 @end verbatim

   575 

   587 

   576 in which case we recover the timing we had when we explicitly set the

   588 in which case we recover the timing we had when we explicitly set the

   577 @code{DataRate} and @code{Delay} in the script:

   589 @code{DataRate} and @code{Delay} in the script:

   578 

   590 

   579 @verbatim

   591 @verbatim

   583   Sent 1024 bytes to 10.1.1.2

   596   Sent 1024 bytes to 10.1.1.2

   586   Received 1024 bytes from 10.1.1.2

   599   Received 1024 bytes from 10.1.1.2

   588   UdpEchoServerApplication:DoDispose()

   601   UdpEchoServerApplication:DoDispose()

   589   UdpEchoServerApplication:~UdpEchoServer()

   602   UdpEchoServerApplication:~UdpEchoServer()

   590 @end verbatim

   603 @end verbatim

   591 

   604 

   593 could actually set any of the attributes used in the script in this way.  In

   606 could actually set any of the attributes used in the script in this way.  In

   594 particular we could set the @code{UdpEchoClient} attribute @code{MaxPackets} 

   607 particular we could set the @code{UdpEchoClient} attribute @code{MaxPackets} 

   595 to some other value than one.

   608 to some other value than one.

   596 

   609 

   597 How would you go about that?  Give it a try.  Remember you have to comment 

   610 How would you go about that?  Give it a try.  Remember you have to comment 

   602 control the number of packets echoed from the command line.  Since we're nice

   615 control the number of packets echoed from the command line.  Since we're nice

   603 folks, we'll tell you that your command line should end up looking something

   616 folks, we'll tell you that your command line should end up looking something

   604 like,

   617 like,

   605 

   618 

   606 @verbatim

   619 @verbatim

   608     --ns3::PointToPointNetDevice::DataRate=5Mbps 

   621     --ns3::PointToPointNetDevice::DataRate=5Mbps 

   609     --ns3::PointToPointChannel::Delay=2ms 

   622     --ns3::PointToPointChannel::Delay=2ms 

   610     --ns3::UdpEchoClient::MaxPackets=2"

   623     --ns3::UdpEchoClient::MaxPackets=2"

   611 @end verbatim

   624 @end verbatim

   612 

   625 

   617 Let's use this facility to specify the number of packets to echo in a 

   630 Let's use this facility to specify the number of packets to echo in a 

   618 completely different way.  Let's add a local variable called @code{nPackets}

   631 completely different way.  Let's add a local variable called @code{nPackets}

   619 to the @code{main} function.  We'll initialize it to one to match our previous 

   632 to the @code{main} function.  We'll initialize it to one to match our previous 

   620 default behavior.  To allow the command line parser to change this value, we

   633 default behavior.  To allow the command line parser to change this value, we

   621 need to hook the value into the parser.  We do this by adding a call to 

   634 need to hook the value into the parser.  We do this by adding a call to 

   623 start with the following code,

   636 start with the following code,

   624 

   637 

   625 @verbatim

   638 @verbatim

   626   int

   639   int

   627   main (int argc, char *argv[])

   640   main (int argc, char *argv[])

   644 @end verbatim

   657 @end verbatim

   645 

   658 

   646 Now if you run the script and provide the @code{--PrintHelp} argument, you 

   659 Now if you run the script and provide the @code{--PrintHelp} argument, you 

   647 should see your new @code{User Argument} listed in the help display.

   660 should see your new @code{User Argument} listed in the help display.

   648 

   661 

   653   --PrintHelp: Print this help message.

   671   --PrintHelp: Print this help message.

   654   --PrintGroups: Print the list of groups.

   672   --PrintGroups: Print the list of groups.

   655   --PrintTypeIds: Print all TypeIds.

   673   --PrintTypeIds: Print all TypeIds.

   656   --PrintGroup=[group]: Print all TypeIds of group.

   674   --PrintGroup=[group]: Print all TypeIds of group.

   657   --PrintAttributes=[typeid]: Print all attributes of typeid.

   675   --PrintAttributes=[typeid]: Print all attributes of typeid.

   658   --PrintGlobals: Print the list of globals.

   676   --PrintGlobals: Print the list of globals.

   659   User Arguments:

   677   User Arguments:

   660       --nPackets: Number of packets to echo

   678       --nPackets: Number of packets to echo

   662 @end verbatim

   679 @end verbatim

   663 

   680 

   664 If you want to specify the number of packets to echo, you can now do so by

   681 If you want to specify the number of packets to echo, you can now do so by

   665 setting the @code{--nPackets} argument in the command line,

   682 setting the @code{--nPackets} argument in the command line,

   666 

   683 

   667 @verbatim

   684 @verbatim

   671   Sent 1024 bytes to 10.1.1.2

   695   Sent 1024 bytes to 10.1.1.2

   673   Received 1024 bytes from 10.1.1.2

   698   Received 1024 bytes from 10.1.1.2

   674   Sent 1024 bytes to 10.1.1.2

   699   Sent 1024 bytes to 10.1.1.2

   676   Received 1024 bytes from 10.1.1.2

   702   Received 1024 bytes from 10.1.1.2

   678 @end verbatim

   706 @end verbatim

   679 

   707 

   680 You have now echoed two packets.

   708 You have now echoed two packets.

   681 

   709 

   682 You can see that if you are an @command{ns-3} user, you can use the command 

   710 You can see that if you are an @command{ns-3} user, you can use the command 

   762 @command{ns-2} output, this type of trace is analogous to the @command{out.tr}

   790 @command{ns-2} output, this type of trace is analogous to the @command{out.tr}

   763 generated by many scripts.

   791 generated by many scripts.

   764 

   792 

   765 @cindex tracing packets

   793 @cindex tracing packets

   766 Let's just jump right in and add some ASCII tracing output to our 

   794 Let's just jump right in and add some ASCII tracing output to our 

   769 

   806 

   770 @verbatim

   807 @verbatim

   771   std::ofstream ascii;

   808   std::ofstream ascii;

   773   PointToPointHelper::EnableAsciiAll (ascii);

   810   PointToPointHelper::EnableAsciiAll (ascii);

   774 @end verbatim

   811 @end verbatim

   775 

   812 

   776 The first two lines are just vanilla C++ code to open a stream that will be

   813 The first two lines are just vanilla C++ code to open a stream that will be

   778 are unfamiliar with this code.  The last line of code in the snippet above

   815 are unfamiliar with this code.  The last line of code in the snippet above

   779 tells @command{ns-3} that you want to enable ASCII tracing on all 

   816 tells @command{ns-3} that you want to enable ASCII tracing on all 

   780 point-to-point devices in your simulation; and you want the (provided) trace

   817 point-to-point devices in your simulation; and you want the (provided) trace

   781 sinks to write out information about packet movement in ASCII format to the 

   818 sinks to write out information about packet movement in ASCII format to the 

   782 stream provided. For those familiar with @command{ns-2}, the traced events are

   819 stream provided. For those familiar with @command{ns-2}, the traced events are

   783 equivalent to the popular trace points that log "+", "-", "d", and "r" events.

   820 equivalent to the popular trace points that log "+", "-", "d", and "r" events.

   784 

   821 

   793 You can now build the script and run it from the command line:

   822 You can now build the script and run it from the command line:

   794 

   823 

   795 @verbatim

   824 @verbatim

   802 the running program.  

   831 the running program.  

   803 

   832 

   805 Because of the way that Waf works, the file is not created in the local 

   834 Because of the way that Waf works, the file is not created in the local 

   806 directory, it is created at the top-level directory of the repository by 

   835 directory, it is created at the top-level directory of the repository by 

   807 default.  If you want to control where the traces are saved you can use the 

   836 default.  If you want to control where the traces are saved you can use the 

   808 @code{--cwd} option of Waf to specify this.  We have not done so, thus we 

   837 @code{--cwd} option of Waf to specify this.  We have not done so, thus we 

   809 need to change into the top level directory of our repo and take a look at 

   838 need to change into the top level directory of our repo and take a look at 

   811 

   840 

   812 @subsubsection Parsing Ascii Traces

   841 @subsubsection Parsing Ascii Traces

   813 @cindex parsing ascii traces

   842 @cindex parsing ascii traces

   814 There's a lot of information there in a pretty dense form, but the first thing

   843 There's a lot of information there in a pretty dense form, but the first thing

   815 to notice is that there are a number of distinct lines in this file.  It may

   844 to notice is that there are a number of distinct lines in this file.  It may

   842   01 2 

   871   01 2 

   843   02 /NodeList/0/DeviceList/0/$ns3::PointToPointNetDevice/TxQueue/Enqueue 

   872   02 /NodeList/0/DeviceList/0/$ns3::PointToPointNetDevice/TxQueue/Enqueue 

   844   03 ns3::PppHeader (

   873   03 ns3::PppHeader (

   845   04   Point-to-Point Protocol: IP (0x0021)) 

   874   04   Point-to-Point Protocol: IP (0x0021)) 

   846   05   ns3::Ipv4Header (

   875   05   ns3::Ipv4Header (

   848   07     length: 1052 10.1.1.1 > 10.1.1.2)

   877   07     length: 1052 10.1.1.1 > 10.1.1.2)

   849   08     ns3::UdpHeader (

   878   08     ns3::UdpHeader (

   850   09       length: 1032 49153 > 9) 

   879   09       length: 1032 49153 > 9) 

   851   10       Payload (size=1024)

   880   10       Payload (size=1024)

   852 @end verbatim

   881 @end verbatim

   915 and the channel @code{Delay} set to their default values.  This time should 

   944 and the channel @code{Delay} set to their default values.  This time should 

   916 be familiar as you have seen it before in a previous section.

   945 be familiar as you have seen it before in a previous section.

   917 

   946 

   918 The trace source namespace entry (reference 02) has changed to reflect that

   947 The trace source namespace entry (reference 02) has changed to reflect that

   919 this event is coming from node 1 (@code{/NodeList/1}) and the packet reception

   948 this event is coming from node 1 (@code{/NodeList/1}) and the packet reception

   921 progress of the packet through the topology by looking at the rest of the 

   950 progress of the packet through the topology by looking at the rest of the 

   922 traces in the file.

   951 traces in the file.

   923 

   952 

   924 @subsection PCAP Tracing

   953 @subsection PCAP Tracing

   925 @cindex pcap

   954 @cindex pcap

   935 

   964 

   936 @cindex pcap tracing

   965 @cindex pcap tracing

   937 The code used to enable pcap tracing is a one-liner.  

   966 The code used to enable pcap tracing is a one-liner.  

   938 

   967 

   939 @verbatim

   968 @verbatim

   941 @end verbatim

   970 @end verbatim

   942 

   971 

   943 Go ahead and insert this line of code after the ASCII tracing code we just 

   972 Go ahead and insert this line of code after the ASCII tracing code we just 

   946 parameter is a prefix, not a complete file name.  The helper will actually 

   975 parameter is a prefix, not a complete file name.  The helper will actually 

   947 create a trace file for every point-to-point device in the simulation.  The 

   976 create a trace file for every point-to-point device in the simulation.  The 

   948 file names will be built using the prefix, the node number, the device number

   977 file names will be built using the prefix, the node number, the device number

   949  and a ``.pcap'' suffix.

   978  and a ``.pcap'' suffix.

   950 

   979 

   953 node 1-device 0, respectively.

   982 node 1-device 0, respectively.

   954 

   983 

   955 Once you have added the line of code to enable pcap tracing, you can run the

   984 Once you have added the line of code to enable pcap tracing, you can run the

   956 script in the usual way:

   985 script in the usual way:

   957 

   986 

   958 @verbatim

   987 @verbatim

   960 @end verbatim

   989 @end verbatim

   961 

   990 

   962 If you look at the top level directory of your distribution, you should now

   991 If you look at the top level directory of your distribution, you should now

   965 are the new pcap files we just generated.  

   994 are the new pcap files we just generated.  

   966 

   995 

   967 @subsubsection Reading output with tcpdump

   996 @subsubsection Reading output with tcpdump

   968 @cindex tcpdump

   997 @cindex tcpdump

   969 The easiest thing to do at this point will be to use @code{tcpdump} to look

   998 The easiest thing to do at this point will be to use @code{tcpdump} to look

   975   2.000000 IP 10.1.1.1.49153 > 10.1.1.2.9: UDP, length 1024

  1004   2.000000 IP 10.1.1.1.49153 > 10.1.1.2.9: UDP, length 1024

   976   2.514648 IP 10.1.1.2.9 > 10.1.1.1.49153: UDP, length 1024

  1005   2.514648 IP 10.1.1.2.9 > 10.1.1.1.49153: UDP, length 1024

   979   2.257324 IP 10.1.1.1.49153 > 10.1.1.2.9: UDP, length 1024

  1009   2.257324 IP 10.1.1.1.49153 > 10.1.1.2.9: UDP, length 1024

   980   2.257324 IP 10.1.1.2.9 > 10.1.1.1.49153: UDP, length 1024

  1010   2.257324 IP 10.1.1.2.9 > 10.1.1.1.49153: UDP, length 1024

   985 echo packet is sent at 2 seconds into the simulation.  If you look at the

  1014 echo packet is sent at 2 seconds into the simulation.  If you look at the

   988 in the second dump, and finally, you see the packet being received back at 

  1017 in the second dump, and finally, you see the packet being received back at 

   989 the client in the first dump at 2.514648 seconds.

  1018 the client in the first dump at 2.514648 seconds.

   990 

  1019 

   991 @subsubsection Reading output with Wireshark

  1020 @subsubsection Reading output with Wireshark

   992 @cindex Wireshark

  1021 @cindex Wireshark