@Database "sana2meter" @Author "Marius Gröger" @(c) "Copyright © 1996 by Marius Gröger" @$VER: sana2meter.guide 34.3 (15.04.96) @node Main "SANA2Meter" @{fg highlight}@{b} SANA2Meter -- A statistics monitor for SANA-II compliant network devices @{ub}@{fg text} (C) Copyright 1996 Marius Gröger @{b}TABLE OF CONTENTS@{ub} @{b}Intro@{ub} @{" Description " link "Description"} Why You need it! @{" Features " link "Features"} All in one glance @{" Requirements " link "Requirements"} What you need @{b}Getting started@{ub} @{" Installation " link "Installation"} What's needed to be done @{b}Options@{ub} @{" Options and Tooltypes " link "Options"} What options are offered @{" The Menu " link "Menu"} How to use the menu @{" Program Termination " link "Stopping"} How to get rid of it @{b}Problems, Questions and Caveats@{ub} @{" Caveats " link "Caveats"} Caution! @{" Troubleshooting " link "Trouble"} Doesn't it work properly? @{" Bugs " link "Bugs"} Known Bugs @{b}Appendices@{ub} @{" Future plans " link "Future"} Things I will perhaps lay my hands on @{" History " link "History"} What's been done already @{" Localisation " link "Localisation"} Other languages @{" (C)/Credits/Author " link "Author"} Legal stuff, Thanks and How to contact me @endnode @node Description "SANA2Meter - Description" @next Features @prev Main @{fg highlight}@{b}Description@{ub}@{fg text} ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The SANA2Meter is a simple tool that displays the network device statistics of any SANA-II network device. The set of displayable values include static parameters such as hardware type, MTU, speed in bits per second as well as dynamic values such as number of sent and received packets and error counters. In addition, SANA2Meter is able to display up to 20 device special statistics using generic code for the inquiry. The dynamic statistics are updated periodically. SANA2Meter can be called from both CLI and Workbench. A great lot of values, including the set of displayed statistics, refresh time, window position, public screen, and font can easily be customized by CLI arguments, tooltypes, and menu selection. The current setting may be saved to the tooltype list from the GUI. SANA2Meter can be used with any SANA-II compliant network device including popular SLIP or PPP devices used to connect to an internet provider service. @endnode @node Features "SANA2Meter - Features" @prev Description @next Requirements @{fg highlight}@{b}Features@{ub}@{fg text} ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ · Monitors all standard SANA-II network device statistics · Monitors up to 20 special statistics · Monitors arbitrarily many particular packet types using SANA-II packet type tracking · A great lot of settings may be customized · Localisation · Completely pure code · Distributed as Freeware, complete source code included @endnode @node Requirements "SANA2Meter - Requirements" @next Installation @prev Features @{fg highlight}@{b}Requirements@{ub}@{fg text} ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ · AmigaOS Release 2.04 (V37) or higher, 3.1 (V40) is recommended for best rendering quality · gtlayout.library V24 or higher (tested with V32.3) · Some SANA-II compliant network device · Workbench 2.1 (V38) if localisation is desired @endnode @node Installation "SANA2Meter - Installation" @next Options @prev Requirements @{fg highlight}@{b}Installation@{ub}@{fg text} ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The installation is done best by using the supplied Installer-Script. If you don't want to use the installer, just put one of the executables suitable for your system located in the @{b}bin@{ub} directory to a place where you want to. The @{b}Help@{ub} directory contains this AmigaGuide document. The @{b}Icons@{ub} directory contains Icons for a standard AmigaOS Workbench as well as some that are suitable for the MagicWB environment and color palette. Sana2meter offers some @{" options " link Options}. If you want to launch sana2meter from Workbench edit the tooltype list accordingly. If you plan to run in from CLI, pass in the right commandline arguments. In the @{b}Catalogs@{ub} directory are @{" localisation " link Localisation} catalogs stored. Currently the only supported languages include: · enlish (built-in) · german Sana2meter has been designed completely pure and reentrant. So you might want to put it into the AmigaDOS resident list by issuing the command: @{b}Resident sana2meter@{ub} Note, however, that due to the poor design of Workbench the resident list is @{i}not @{ui}searched if programs are started from Workbench, but only if started from CLI. @endnode @node Options "SANA2Meter - Startup Options and Tooltypes" @next Menu @prev Installation @{fg highlight}@{b}Invoking sana2meter@{ub}@{fg text} ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The sana2meter client accepts the following options either on the commandline or given as tooltypes: @{b}SHOW@{ub} Template: S=SHOW/K Tooltype: SHOW Default: ipackets,opackets,baddata,overruns,unknown,mtu,bps,hwtype This parameter lets the user specify the statistical counters that should be displayed. The argument is a list of keywords, each two keywords must be separated by either a comma (,), a semi-colon (;), a bar (|), or a blank ( ). The following keywords are recognized: ipackets Number of packets that the unit has received opackets Number of packets that the unit has sent baddata Number of bad packets received (i.e., hardware CRC failed) overruns Number of packets dropped due to insufficient resources available in the network interface. unknown Number of packets received that had no pending read command with the appropriate packet type. reconfigs Number of network reconfigurations since this unit was last configured. mtu Maximum Transmission Unit, the size, in bytes, of the maximum packet size, not including header and trailer information. BPS Best guess at the raw line rate for this network in bits per second. hwtype Specifies the type of network hardware the driver controls. special1 trough special20 Special device statistics. This kind of statistics is optional to a network device driver writer, and therefore not all devices support it. The special statistics are used to maintain statistic counters for values that are special to the device. For instance, a SLIP device might provide a counter for the number of compressed packets that were received so far. SANA2Meter sort of "probes" the device to find out if, how much and what special statistic counters it provides. The @{" menu " link Menu} of the interactive GUI will be adapted accordingly. @{b}LIST@{ub} Template: L=LIST/S Tooltype: LIST Instead of opening the GUI a list of displayable statistics will be printed to the console. A console window will be opened if started from Workbench. @{b}TRACKTYPE@{ub} Template: TT=TRACKTYPE/K Tooltype: TRACKTYPE Default: This parameter allows to keep track of the statistics of particular packet types. Since type tracking is done completely generic, the type number to be monitored must be given as a decimal or a sedecimal value. Multiple packet types may be kept track of. The types in question are determined by list of packet type specifiers. Similar to the keyword list of the SHOW argument, each packet type specifiers must be separated by either a comma (,), a semi-colon (;), a bar (|), or a blank ( ). A packet type specifier primarily determines a certain packet type to be monitored. The following table lists some common packet type numbers: packet type number Meaning -------------------------------------------------------------------- $800 IP packets on Ethernet. This type number is also used for some other network interfaces, e.g. (C)SLIP or PLIP. $806 ARP packets on Ethernet $21 IP packets on PPP (RFC 1334 IP protocol). $F0 ARCNET(?) (RFC 1051 framing) $F1 ARCNET(?) (RFC 1051 framing) $D4 ARCNET(?) (RFC 1201 framing) $D5 ARCNET(?) (RFC 1201 framing) $D6 ARCNET(?) (RFC 1201 framing) In addition, the packet type specifier may determine which particular statistics about the packets of this type should be actually displayed. The following values are updated for each type and can be displayed: PacketsSent Number of packets of this particular type sent. PacketsReceived Number of packets of this particular type that satisfied a read command. BytesSent Number of bytes of data sent in packets of this particular type. BytesReceived Number of bytes of data of this particular packet type that satisfied a read command. PacketsDropped Number of packets of this particular type that were received while there were no pending reads of that packet type. In the packet type specifiers, a 5-character-mask determines which value should be displayed. Each displayable value is associated with a certain character position in the mask. As studying examples is always the best way to learn, the next table lists some valid packet type specifiers: packet type specifier Meaning -------------------------------------------------------------------- $800 Display full statistics of $800 type packets. $800:--##- Display only the number of transfered bytes of $800-type packets. $800:##--# Display only the number of transfered or dropped packets of $800-type packets. $800:xxoox dito. $800:XXOOX dito. $800:++..+ dito. $800:++--+ dito. $800/++--+ dito. $800:--##-,$806:--##- Display only the number of transfered bytes of $800- and $806-type packets. $800:--##-;$806:--##- dito. $800:--##-|$806:--##- dito. $800:--##- $806:--##- dito. Notice that on CLI startup the argument of a keyword may only contain blanks if it is enclosed in quotation characters ("). @{b}WINDOW@{ub} Template: WINDOW/K Tooltype: WINDOW CLI-Default: CLI-Window; WB-Default: CON:0/0/400/200/SANA-II Meter Tool Output/AUTO/WAIT/CLOSE Console window specifier to define an output channel when started from Workbench. On CLI startup this keyword is parsed but it's value will be ignored. @{b}DEVICE@{ub} Template: DEVICE Tooltype: DEVICE Default: devs:networks/magplip.device This keyword specifies the SANA-II compliant network device. Depending on your system setup it may be neccessary to specify the full path, e.g. @{i}devs:networks/a2065.device @{ui}. @{b}UNIT@{ub} Template: U=UNIT/K/N Tooltype: UNIT Default: 0 This lets the user specify the network device unit number to use for opening the device. @{b}FORCE@{ub} Template: FORCE/S Tooltype: FORCE Some SANA-II devices might not love the fact that sana2meter is a not a real device user program in the way an actual protocol stack is. This switch makes sana2meter to appear more like such. @{b}REFRESH@{ub} Template: RF=REFRESH/K/N Tooltype: REFRESH Default: 2 This lets the user specify the number of seconds between each two refresh cycles. @{b}FONT@{ub} Template: FONT=FONTNAME/K Tooltype: FONT, FONTNAME Default: System default font By this keyword a different font for the display window may be specified. @{b}FONTSIZE@{ub} Template: FONTSIZE/K/N Tooltype: FONTSIZE Default: System font's height or an 8 point custom font, respectively. By this keyword a different fontsize for the display window may be specified. @{b}LEFT@{ub} Template: LEFT/K/N Tooltype: LEFT Default: 30 The X-Coordinate where the window should open. @{b}TOP@{ub} Template: TOP/K/N Tooltype: TOP Default: 20 The Y-Coordinate where the window should open. @{b}NOACTIVATE@{ub} Template: NA=NOACTIVATE/S Tooltype: NOACTIVATE Setting this switch makes the window open in inactive state @{b}WINDOWOBACK@{ub} Template: W2B=WINDOWTOBACK/S Tooltype: WINDOWTOBACK Setting this switch moves the window behind all other non-backdrop windows right after opening it. @{b}PUBSCREEN@{ub} Template: SCREEN=PUBSCREEN/K Tooltype: PUBSCREEN Default: System default public screen (usually the workbench screen). The name of the public screen where the window should open on. @endnode @node Menu "SANA2Meter - The Menu" @next Stopping @prev Options @{fg highlight}@{b}The Menu@{ub}@{fg text} ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A menu strip is attached to the display window. Following a description of the various items. The menu texts are referred to using the built-in english texts. Users running sana2meter in a different language will have to do some associative work anyway when reading this document. @{b}Project/Save configuration@{ub} Saves the current window position, and settings of the "Settings" and "Show" menus to the program's list of tooltypes. @{b}Project/About...@{ub} Displays a requester with copyright and author information. @{b}Project/Quit@{ub} Terminates sana2meter. @{b}Settings/Update (seconds)@{ub} The attached sub-menu may be used to set the refresh rate for the dynamic statistics in seconds. @{b}Show/#?@{ub} The items in this menu may be checked or unchecked to modify the set of displayed statistics. The special device statistics are near the end of the menu. SANA2Meter uses automatically the statistic counter names as provided by the network driver. Note that it is the duty of the network driver to localize these names. Being a generic monitor tool without any knowledge of a particular network driver SANA2Meter can only reproduce the special statistic counter's names. If packet type tracking is used, each type being tracked is represented by a separate submenu at the end of the menu, the subitems of which may be checked or unchecked to modify the set of displayed statistics. @endnode @node Stopping "SANA2Meter - Program Termination" @next Caveats @prev Menu @{fg highlight}@{b}Program Termination@{ub}@{fg text} ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The programm may be stopped by clicking the window's closebox, by sending an AmigaDOS break-signal to the process or by pressing ESC when the window is active. @endnode @node Caveats "SANA2Meter - Caveats" @next Trouble @prev Stopping @{fg highlight}@{b}Caveats@{ub}@{fg text} ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This section tries to address some known problems. I will always try to give the user the necessary technical background to understand the problem and, if possible, to include a work-around. If you have found a similar problem which is not mentioned in this document, you should contact @{" me " link Author} in order to append it to this section. @{b}SANA2Meter and different Kickstart releases@{ub} SANA2Meter's GUI is built using the powerful gtlayout.library by Olaf Barthel. The aim of this library is to provide a more abstract and intelligent inferface than Kickstart's built-in gadtools.library. However, gtlayout.library only defines API functions, data structures and tag values that are additional to gadtools.library. Most internal actions of gtlayout.library end up in a some calls to gadtools.library. This saves memory and retains the Amiga look and feel, but also inherits the various levels of functionality found in the different versions of gadtools.library, not to mention bugs. Due to some bug in gadtools.library V39 the displayed numbers are not nicely right justified as done under gadtools.library V40. When running AmigaOS 2.04 (V37), the numbers won't even be displayed in highlighted text. There might by other limitations that I am not aware of by now , especally with respect to AmigaOS 2.04. @{b}SANA2Meter and type tracking@{ub} Type tracking as defined by the SANA-II standard seems to assume only one device user tracks a certain type. At least, trying to track a type that is alreay tracked by some other user leads to a SANA-II error condition. It is @{i}not @{ui}told whether this means to the refused user that he is now disallowed to get the desired statistics, or that he may nevertheless retrieve them. SANA2Meter acts like this: · If the type could be tracked successfully, it will be displayed and untracked on exit. · If it could not be tracked successfully, it will nevertheless attempted to be displayed; if this bothers the device SANA-II tells it to refuse the inquiry request as currently not applicable. SANA2Meter will stop displaying the counter in that case. The type won't be untracked. By the way, the magplip.device will nest multiple type tracking requests satisfying all users as well as the SANA-II standard. Generally SANA2Meter will stop displaying a certain value when the corresponding i/o operations needed to retrieve the statistics fail. @endnode @node Trouble "SANA2Meter - Troubleshooting" @next Bugs @prev Caveats @{fg highlight}@{b}Troubleshooting@{ub}@{fg text} ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Q: @{b}The device can't be opened.@{ub} A requester appears telling that the device couldn't be opened. A: Check whether you have specified the device name and unit correctly. The device name may need to be specified along with a full file specification: According to the SANA-II 2.0 standard all network interface drivers should be located in @{b}devs:networks@{ub}. The path specification may be provided case insensitive, the device name, however, must be given using the original letter cases. Q: @{b}The device can't be opened.@{ub} A requester appears telling that the device couldn't be opened. The device name and unit have been entered correctly, though! A: Some SANA-II devices need request certain additional data when opening the device that are needed for real protocol stacks, but that are actually neccessary for the retrieval of statistic information. The @{" FORCE " link Options} option makes sana2meter to appear a bit more like a protocol stack. Q: @{b}Sometimes a certain statistical information vanishes without command.@{ub} It can't be display again. A: This indicates that for some reason the network device refused to provide SANA2Meter with the desired information. SANA2Meter can't do anything about this, except ceasing the display of the value in question. Most often this will happen to the display of packet type tracking information in the case that the operation of the protocol stack will be terminated. See also the @{" Caveats " link Caveats} section. @endnode @node Bugs "SANA2Meter - Known Bugs" @next Future @prev Trouble @{fg highlight}@{b}Known Bugs@{ub}@{fg text} ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ SANA2Meter 37.1 and 37.2 failed to work under Kickstart 3.0 releases. @{i}@{b}This was due to a bug in older versions of gadtools.library, that wouldn't render number fields correctly right justified! @{ub}@{ui}Version 40.1 of gadtools.library fixes that bug. Work-around for to get those versions to work is to get SANA2Meter 37.3 or higher (which simply suppresses right justification when a gadtools version lower than 40.1 is installed), or/and to run Kickstart 3.1 or higher. Thanks all users that pointed that bug out. Please don't blame me but the makers of the (anyway brain-damaged) gadtools.library. If you have found bugs, please contact @{" me " link Author}. @endnode @node Future "SANA2Meter - Future plans" @next Localisation @prev Bugs @{fg highlight}@{b}Future plans@{ub}@{fg text} ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Perhaps I will implement some more features: · Packet type tracking If you have any suggestions, contact @{" me " link Author}. @endnode @node Localisation "SANA2Meter - Localisation" @next History @prev Future @{fg highlight}@{b}Localisation@{ub}@{fg text} ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ As of the current version the following languages are supported by built-in texts and transient catalog files: · enlish (built-in) · german Further localisation depends on the Amiga user's community. There has been provided a blank catalog source file in the source tree (see @{b}Source/blank.ct@{ub}). If you want to translate it to a new language, say, a klingonic version, you should: 1. Contact @{" me " link Author} to get an exclusive permission to perform the translation. 2. Perform it. 3. Send to me the klingon.ct file 4. Watch out for the next release's documentation, section "Credits". @endnode @node History "SANA2Meter - History" @next Author @prev Localisation @{fg highlight}@{b}Development history of SANA2Meter@{ub}@{fg text} ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Release 37.3 · SANA2Meter now also renders it's display under Kickstart 3.0 (V39). Earlier releases of SANA2Meter failed to operate accurately due to a bug in gadtools lower than 40.1 · loosing track of some values (most notably packet type tracking information) will terminate their display Release 37.2 · packet type tracking Release 37.1 · initial release @{b}Technical history of "SANA2Meter"@{ub} For more technical details, please refer to the source code. In the header section of each source file, you find the pseudo-keyword $HISTORY: after which follows the complete revision history of this file. @endnode @node Author "SANA2Meter - Copyright / Credits / Author" @prev History @{fg highlight}@{b}Copyright, Credits and Author Information@{ub}@{fg text} ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @{b}Credits@{ub} The GUI has been created using @{fg highlight}Olaf Barthel@{fg text}'s gtlayout library. The tooltype modification uses parts of the supra.lib code written by @{fg highlight} Jure Vrhovnik@{fg text}. The integrated CLI/Workbench argument parsing is done using the ExtReadArgs package written by @{fg highlight}Stefan Ruppert@{fg text}. Some stylistic decisions concerning the look and feel of the program and the documentation have been inspired by the Executive package from @{fg highlight}Petri Nordlund@{fg text}, a very recommendable piece of software, by the way. @{b}Legal stuff@{ub} SANA2Meter (C) Copyright 1996 Marius Gröger. All Rights Reserved. This software is freeware. It is provided as-is and is subject to change; no warranties are made. All use is at your own risk. No liability or responsibility is assumed. It's strictly forbidden to include this archive in any kind of software collection except @{fg highlight}Fred Fish's AmigaLibrary@{fg text}, @{fg highlight}Meeting Pearls CD's@{fg text}, @{fg highlight}Aminet@{fg text}, @{fg highlight}Aminet CD's@{fg text} and @{fg highlight}BBS fileareas@{fg text}. You may make any changes to the source for your own use. If you consider them useful for everybody, please get in touch with me. This way I can try to include them in the next public release. Installer and Installer project icon (c) Copyright 1991-93 Commodore-Amiga, Inc. All Rights Reserved. Reproduced and distributed under license from Commodore. AmigaGuide, AmigaGuide.info, amigaguide.library, WDisplay, WDisplay.info (c) Copyright 1991-93 Commodore-Amiga, Inc. All Rights Reserved. Reproduced and distributed under license from Commodore. MagicWB (c) Copyright 1994 Martin Huttenloher. All Rights Reserved. @{b}Contact@{ub} If you like this software, or have any suggestion how to improve it, or just want to complain about it, feel free to contact me. @{b}Home address:@{ub} @{fg highlight}Marius Gröger, Bärstadter Str. 4 65307 Bad Schwalbach (GERMANY)@{fg text} @{b}Internet email addresses:@{ub} @{fg highlight}mag@sysgo.de groeger@goofy.zdv.uni-mainz.de@{fg text} @endnode