home *** CD-ROM | disk | FTP | other *** search
/ HAM Radio 1 / HamRadio.cdr / misc / monax2 / doc.doc < prev    next >
Encoding:
Text File  |  1987-10-30  |  10.9 KB  |  337 lines
  1. Documentation for WB6YMH/NK6K Stats package.
  2. Version 1.1, October 1987.
  3.  
  4.  
  5.  
  6. This set of programs is intended to be the start of a family of 
  7. programs to gather performance statistics and other information 
  8. about the amateur radio packet system.  A complete background on 
  9. the project was provided in a paper presented at the 6th ARRL 
  10. Computer Networking Conference.  A copy of the paper is included 
  11. in this release.
  12.  
  13. The following programs are currently included:
  14.  
  15. STATS - monitors output from a KISS TNC, displays activity on
  16. the screen and puts stats in LOG.
  17.  
  18. REPORT - reformats data from LOG file.
  19.  
  20. TOTALS - reformats data from LOG file.
  21.  
  22. PTOTALS - prints output from TOTALS program.
  23.  
  24. AVERAGE - averages data from REPORT program.
  25.  
  26.  
  27. The programs are written C and compiled with Microsoft C 
  28. 3.0 and 4.0.  They will be as easily transportable to other 
  29. versions of C as any other C program.
  30.  
  31. The STATS program uses two assembly language modules for an 
  32. interface to the PC's serial ports.  The SERIALIP.ASM module 
  33. provides interrupt driven serial I/O for IBM compatible COM1 and 
  34. COM2 serial ports.  The CDTMR.ASM module samples the Carrier 
  35. Detect line on the RS232 port at a 18.2 Hz rate. Obviously these 
  36. routines are very machine specific and would have to be heavily 
  37. modified or replaced when porting the STATS program to another 
  38. hardware environment.
  39.  
  40. Specifics on each program are discussed below.
  41.  
  42.  
  43. STATS
  44. ----
  45.  
  46. This program reads AX.25 frames in the KISS TNC format.  
  47. Information about the frame is summed in various counters.  These 
  48. counters are output into a log file once every reporting 
  49. interval.  The reporting interval is currently set at five 
  50. minutes.   The format of the records in the log file are in 
  51. MONFILE.H
  52.  
  53. At the end of each interval, STATS opens "log" in the current 
  54. directory, appends the new records, and then closes the file.  If 
  55. the log file can not be opened (disk full), STATS aborts.
  56.  
  57. STATS also writes all incoming frames on stdout.
  58.  
  59. The STATS program may be used either standalone or with an 
  60. W0RLI/WA7MBL compatible "mbbios" program.  The standalone version 
  61. supports a standard COM1 or COM2 serial port.  Non-standard ports 
  62. are supported by use of the "mbbios" program.  STATS will use the 
  63. mbbios program instead of the internal serial routine if mbbios 
  64. is loaded. 
  65.  
  66. Commands to STATS can be entered on the startup line, or after it 
  67. is running.  Once running, the command parser is entered by 
  68. hitting Alt-C.  The parser will then accept one command line, 
  69. then return to collecting data.  Multiple commands are separated 
  70. by ';'.  The commands are:
  71.  
  72.  
  73. BASE 
  74.  
  75.     Sets the base address of the COM port. This command is used 
  76.     when a "mbbios" program is used to support a non-standard COM 
  77.     port.  The specified BASE address is used by the background 
  78.     routine to sample the CD status line.  The BASE address is 
  79.     automatically set by the PORT command when the built in 
  80.     interrupt handler is used.  Example: BASE 768 sets the base 
  81.     address of a non-standard serial port to 768 (300 hex).
  82.  
  83.  
  84. BAUD
  85.  
  86.     Selects baud rate of the serial line to the KISS TNC, e.g. 
  87.     BAUD 4800.
  88.  
  89.  
  90. END
  91.  
  92.     Terminates execution.  Alt-X may also be used to exit 
  93.     instead of Alt-C END.
  94.  
  95.  
  96. HELP
  97.  
  98.     Displays the list of available commands.
  99.  
  100.  
  101. QUIT
  102.  
  103.     Synonym for END.
  104.  
  105.  
  106. PORT
  107.  
  108.     Selects the port for the KISS TNC connection, n = 0 or 1 if 
  109.     mbbios is not used.  Otherwise n maybe any port supported by 
  110.     mbbios. The default is 0 (com1).  
  111.  
  112. TIME
  113.  
  114.     Adds timestamp to each frame displayed by STATS.  Timestamp 
  115.     records are always included in the log file.
  116.  
  117.  
  118. The following hardware mod should be made if DCD on/off times are
  119. desired.
  120.  
  121. Since most of the current TNC designs use the DCD signal on the RS-232 
  122. interface as a connect status indicator it is necessary to modify 
  123. the TNC hardware slightly to provide a true modem DCD on the RS-232 
  124. interface.  The modification for the TNC 2 and clones is very 
  125. simple, consisting of a single jumper wire.  The jumper goes 
  126. between pin 2 of the modem disconnect header (DCD output from the 
  127. modem) and the pin of JMP1 which is NOT connected to +5 volts 
  128. (input to the DCD driver).  On the MFJ-1270B artwork the correct 
  129. pin of JMP1 is the one closest to the front panel.  The authors 
  130. have not researched modifications to other TNC designs, but it is 
  131. expected the modifications will be similar.  It is NOT necessary 
  132. to perform the DCD modification to run the monitoring software, 
  133. it is only necessary if the statistics of DCD activity are 
  134. desired.
  135.  
  136. Most terminal software used on packet will be unaffected by this
  137. modification, however most BBS software will require the jumper to 
  138. be removed for normal operation.
  139.  
  140.  
  141.  
  142.  
  143. REPORT
  144. ------
  145.  
  146. Report further summarizes and combines the information in the log 
  147. file built by STATS.  Data is emitted as one record per interval.  
  148. These records can then be passed through AVERAGE to produce data
  149. averaged over larger intervals.  The data can then passed to a 
  150. plotting program for display.  Lotus 123 was used to produce the 
  151. graphs in the conference proceedings.  The various items output 
  152. by REPORT have no great cosmic meaning, they serve as examples of 
  153. the kind of information we feel can tell us something about how 
  154. the network is running.  The intent is for others to add more 
  155. sophisticated reports as we get an idea of what it is we need to 
  156. know.
  157.  
  158.  
  159. The commands are summarized below.  An item enclosed in [] is 
  160. optional.
  161.  
  162. CIRCUIT
  163.  
  164.     Most of the data graphed in the conference proceedings was 
  165.     generated by this command.  It has no options.  The command 
  166.     generates one record per interval; the records contain the 
  167.     following fields:
  168.           time_stamp          Time stamp of the start of the 
  169.                               interval.
  170.           all circuits        Count of unique to/from pairs.
  171.           user circuits       Circuits excluding those sending 
  172.                               only occasional UI frames.  These
  173.                               are assumed to be beacons or NETROM
  174.                               node commands.
  175.           packets             All packets on channel
  176.           retried packets     Total data packets - unique data 
  177.                               packets
  178.           poll                All packets with poll bit set
  179.           final               All packets with final bit set
  180.           rnr                 RNR packets
  181.           rej                 REJ packets
  182.           bytes               total bytes (all bytes in all 
  183.                               packets)
  184.           udbytes             unique data bytes (data bytes in I 
  185.                               frames of unique packets)
  186.  
  187. END
  188.  
  189.     Exits REPORT.
  190.  
  191.  
  192. HELP
  193.  
  194.     Generates a list of valid commands.
  195.  
  196.  
  197. INPUT file
  198.  
  199.     Selects a file to use in place of the default "log".
  200.  
  201.  
  202. OUTPUT file
  203.  
  204.     Selects a file to use for the generated report instead of 
  205.     stdout.
  206.  
  207. HELP
  208.  
  209.     Displays the list of available commands.
  210.  
  211.  
  212. QUIT
  213.  
  214.     Exits REPORT.
  215.  
  216.  
  217. RAW  [T]
  218.           
  219.     This command displays all fields of all records selected by 
  220.     the RECORD command.  Hit the space key to abort the display.  
  221.     The number printed under the TO call for circuit records is 
  222.     the record number.  RAW also totals all the data in F records 
  223.     and prints this total at the end of the display, providing a 
  224.     quick indication of the amount of data collect.  This command 
  225.     has one option, T.  If T is specified, only the F record 
  226.     total line is displayed.
  227.  
  228.  
  229. RECORD [c][d][f][i][t]
  230.  
  231.     This command selects record types for processing.  The record 
  232.     types are defined in the MONFILE.H file.  To select a record 
  233.     type, enter the type code(s) after the command name, e.g.
  234.           RECORD FT
  235.     selects timestamp and frequency records.  Record with no 
  236.     options will display the current setting.  The default is all 
  237.     types.
  238.  
  239.  
  240. RR
  241.  
  242.     RR has no options.  The command generates one record per 
  243.     interval; the records contain the following fields:
  244.           time_stamp          Time stamp of the start of the 
  245.                               interval.
  246.           packets             Total packets
  247.           i packets           total non-digipeated I frames
  248.           rr packets          total non-digipeater RR frames
  249.  
  250.  
  251. SELECT [call]
  252.  
  253.     This command selects a callsign.  Only circuit records 
  254.     containing this call as one of the endpoints are used in 
  255.     other processing.  The default is no call specified, i.e., 
  256.     all calls are used.  Only one call may be specified at a 
  257.     time, use select with no call to de-select.
  258.  
  259.  
  260.  
  261.  
  262. AVERAGE
  263. -------
  264.  
  265. This program takes the output from the one-interval-per-record 
  266. output of REPORT and averages them together.  Average takes two 
  267. commands on the startup line, -n and -t.  -n is followed by the 
  268. number of records that should be averaged.  For instance, the 
  269. basic reporting interval is five minutes.  If the data is to be 
  270. plotted in half hour points, use -n6.  This will average six 
  271. five-minute intervals together.
  272.  
  273. If -t is specified, the first data item in each record is assumed 
  274. to be a timestamp, which is then not averaged.
  275.  
  276.  
  277.  
  278.  
  279. TOTALS
  280. ------
  281.  
  282. This program reads a log file through STDIN and generals a totals 
  283. file through STDOUT.  It produces four record types, detailed 
  284. below.  This program generates one record per station on the air, 
  285. one record per digipeater, and one record giving totals of all 
  286. packets and bytes heard on the frequency.  PTOTALS is used to 
  287. display the information output by TOTALS.
  288.  
  289. TOTALS takes one option on the command line, a call sign.  If 
  290. specified, only circuit records containing the specified call as 
  291. one of the end points are used.  Record types are:
  292.  
  293.      D - Totals for each digipeater.
  294.           call
  295.           total bytes
  296.           total packets
  297.  
  298.  
  299.      F - Totals for the frequency
  300.           total packets
  301.           total bytes
  302.           unique packets
  303.           unique bytes
  304.           l32 packets <= 32 bytes long
  305.           l64 packets <= 64 bytes long
  306.           l128 packets <= 128 bytes long
  307.           l256 packets <= 256 bytes long
  308.           g256 packets > 256 bytes long
  309.           dcd on ticks
  310.           dcd off ticks
  311.  
  312.  
  313.      S - totals for a station
  314.           station call
  315.       total rx bytes
  316.           total rx unique data bytes
  317.           total rx non-digipeated data bytes
  318.           total rx data bytes
  319.       total tx bytes
  320.           total tx unique data bytes
  321.           total tx non-digipeated data bytes
  322.           total tx data bytes
  323.  
  324. If a callsign was specified, a Z record is emitted as the first 
  325. record in the output file.  This record is the same as an S 
  326. record, and contains the data for the selected call.
  327.  
  328.  
  329.  
  330. PTOTALS
  331. -------
  332.  
  333. This program formats the output from the TOTALS program.
  334. There are no options.
  335.  
  336.  
  337.