XStat V1.15 Documentation ========================= Program and documentation are (C) Copyright 1992-94 by Jürgen Weinelt. IMPORT StdDisclaimer; (* in short: use it at your own risk *) XStat was carefully tested, but there's certainly plenty of room for bugs. XStat V1.15 is Freeware, non-commercial distribution is o.k. as long as the following conditions are met: * Source, executable and documentation must be distributed together (XStat.mod, XStat, XStat.data, XStat.doc, XStat.dok and Make), and these files must be intact (you're not allowed to make changes). You're NOT allowed to add files to the archive. * This program may be included on PD/freeware CDs if I am allowed to order one of those CDs at 50% off the retail price (or cheaper :). Of course a free copy of the CD would be even nicer... Exception: Fred Fish has UNCONDITIONAL permission to add this program version to his library, no matter if he's distributing it on floppy disk or on CD. XStat requires AmigaOS V37 or later (that's 2.04 or later). Purpose ======= XStat extracts statistic information from the Xferstat file created by some UUCICOs (tested with the SWB and wUUCP variant). The most important information XStat offers to you is the phone cost for a certain number of connects. Installation ============ Copy the executable "XStat" to a directory in your "Path", preferably UUBIN: There's only one more file that needs to be installed; it's called "XStat.data", and should be copied to your UULIB: directory. You'll have to customize (edit) XStat.data to complete the installation. The new V1.14 output formats and associated environment variables are documented in the file "FORMS.doc". XStat.data ========== XStat.data contains the phone cost on a "per host" basis, in the following format: XStat.data file header: ----------------------- H XSTAT DATA This header must be the first line of XStat.data XStat.data comment line: ------------------------ # any comments you wish to add to XStat.data You may add comment lines anywhere in your XStat.data file, except before the file header. XStat.data currency sign info: ------------------------------ S Tells XStat the currency sign for your country. This line must come before the first "N"-line. There can be only one "S"-line in your XStat.data file. Examples: # currency sign for the U.S.A. S $ # currency sign for Germany S DM XStat.data host name info: -------------------------- N ... Starts a new connection cost data record. Must be followed by at least one "C"-line. should be the name of a host you're directly connected to, without any path or domain information. Examples: # my own newsfeed N imart # my alternate newsfeed N cbmger Since XStat V1.10, you can use the extended N-line syntax that allows you to specify multiple host names in a single N-line. All those hosts will have the same cost information. Example: # several hosts that have the same cost info's N cbmger brewak forge Since XStat V1.11, you can use several consecutive N-lines. Example: # several hosts that have the same cost info's N cbmger N brewak forge Maximum line length of a N-line is 100 characters. Since XStat V1.11, you can also use the reserved host name ".default.". This cost info will be used for every connect for which the host name cannot be found in XStat.data. Since XStat V1.12 you can also use the reserved host name ".illegal.". This name will be used by XStat whenever an XferStat line with empty host name is encountered; some UUCiCos write such lines when a connection is aborted prematurely. XStat.data connection duration offset info: ------------------------------------------- O Tells XStat that the connection duration in the XferStat file is off by seconds. You can use this to compensate for the connection negotiation phase of the modems (which does not appear in the XferStat connection time). The option was only tested with positive offsets. The "O" line must come directly after the "N" line. There can be only one "O" line per host. Example: N imart O 13 C ... Tells XStat that my modem will usually need 13 seconds to negotiate a connection with imart. XStat.data connection time/cost info: ------------------------------------- C Tells XStat that between and a connection will cost per . "C"-lines must follow a "N"-line. must be in seconds, in the currency of your choice. The first "C"-line must be for "SU-00:00:00"! (see exception at LOCAL/IGNORE below) Example: N imart C SU-00:00:00 120 0.23 C MO-08:00:00 60 0.23 C MO-18:00:00 120 0.23 From Sunday 0:00:00 to Monday 7:59:59, a connection between my site and my newsfeed "imart" will cost 0.23DM/120sec. Between Monday 8:00:00 and Monday 17:59:59, a connection between my site and my newsfeed "imart" will cost 0.23DM/60sec. With this short example, the connection cost for the rest of the week (from Monday 18:00:00 to Saturday 23:59:59) would be 0.23DM/120sec. Since Version 1.09 there's another possible C-line syntax... you can also use "C IGNORE" to tell XStat to ignore all connections from and to that particular host, or you can use "C LOCAL" to specify a local connection without connection costs (only the in/out bytes will be counted in this case). If you use "LOCAL" or "IGNORE", you may NOT use the normal C-line syntax for that host. "LOCAL" and "IGNORE" are mutually exclusive. Example: N imart C IGNORE will cause all connects from/to imart to be ignored. Example: N imart C LOCAL will cause all connects from/to imart to be counted with cost=0. Since Version 1.14, you can also use a unit duration of "0" seconds, which will instruct XStat to assume a "flat rate" for the corresponding connections (one single "unit" will be counted for those connections). Example: N imart C SU-00:00:00 0 0.23 C MO-08:00:00 60 0.23 C MO-18:00:00 120 0.23 Connections between Sunday, 0:00 and Monday, 8:00 will cost one single unit, no matter how long they were. Full length example for XStat.data: ----------------------------------- - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut - H XSTAT DATA #============================================================================== # XStat connection cost data file #============================================================================== # #------------------------------------------------------------------------------ # currency sign for Germany; S must come before first N #------------------------------------------------------------------------------ S DM # #------------------------------------------------------------------------------ # my own newsfeed, connection cost is 0.23/60sec (0.23/120sec night & weekend) #------------------------------------------------------------------------------ N imart N .illegal. C SU-00:00:00 120 0.23 C MO-08:00:00 60 0.23 C MO-18:00:00 120 0.23 C TU-08:00:00 60 0.23 C TU-18:00:00 120 0.23 C WE-08:00:00 60 0.23 C WE-18:00:00 120 0.23 C TH-08:00:00 60 0.23 C TH-18:00:00 120 0.23 C FR-08:00:00 60 0.23 C FR-18:00:00 120 0.23 # #------------------------------------------------------------------------------ # cbmger, brewak, forge, default: # connection cost is 0.23/21sec (0.23/42sec night & weekend) #------------------------------------------------------------------------------ N cbmger N brewak forge N .default. C SU-00:00:00 42 0.23 C MO-08:00:00 21 0.23 C MO-18:00:00 42 0.23 C TU-08:00:00 21 0.23 C TU-18:00:00 42 0.23 C WE-08:00:00 21 0.23 C WE-18:00:00 42 0.23 C TH-08:00:00 21 0.23 C TH-18:00:00 42 0.23 C FR-08:00:00 21 0.23 C FR-18:00:00 42 0.23 # #------------------------------------------------------------------------------ # modula, this is a local (e.g. null-modem) connection #------------------------------------------------------------------------------ N modula C LOCAL # #------------------------------------------------------------------------------ # walker, connects will be ignored #------------------------------------------------------------------------------ N walker C IGNORE # - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut - Usage ===== XStat [?] [DATA name] [FILE name] [V | VERBOSE] [FD | FROMDATE date] [TD | TODATE date] [NI | NOINCOM] [NO | NOOUTGO] [H | HOSTNAME name] [M | MONTH shortdate] [SE | STDERR] [P | PREVIOUS numdays] [L | LAST numdays] Alternate description: XStat FILE/K,DATA/K,V=VERBOSE/S,M=MONTH/K,NI=NOINCOM/S,NO=NOOUTGO/S, Q=QUIET/S,H=HOSTNAME/K,FD=FROMDATE/K,TD=TODATE/K,SE=STDERR/S, P=PERIOD/N,L=LAST/N You may also use the environment variable "XSTATARGS" to specify parameters. This is very useful if you're using XStat from the Workbench (XStat doesn't really support Workbench, that's why there's no icon for it). ? - Displays a help message. DATA name --------- Tells XStat to read its connection cost data from file . defaults to "UULIB:XStat.data". FILE name --------- Tells XStat to extract the statistic information from file . defaults to "UUSPOOL:XferStat". V | VERBOSE ----------- Enables the "verbose" mode. When on, XStat displays short statistics for every connect found in the Xferstat file. Defaults to "off". Specify VERBOSE to turn verbose mode on. WARNING! The VERBOSE option will be changed drastically soon (probably in the next release). FD | FROMDATE date ------------------ Tells XStat to ignore connects before . defaults to "01-JAN-78". You may use any valid AmigaDOS date string, including things like "TODAY" or "YESTERDAY". XStat will add a time string of "00:00:00" internally, you may not do this yourself. Be careful, if you're using Workbench 2.1 (which is [ought to be] currently available to registered developers only) you'll have to use your locale date specifications, for example "HEUTE" instead of "TODAY" if you're using the german locale. Please read the warnings for "PREVIOUS" and "LAST"! TD | TODATE date ---------------- Tells XStat to ignore connects after . defaults to current date/time. You may use any valid AmigaDOS date string, including things like "TODAY" or "YESTERDAY" (with the same 2.1/locale limitations as FD). XStat will add a time string of "23:59:59" internally, you may not do this yourself. Please read the warnings for "PREVIOUS" and "LAST"! M | MONTH shortdate ------------------- Tells XStat to ignore FD and TD, and to compute the statistics for the specified month instead. The month must be given in the format "MMM-YY", without specifying the day. Example: "MONTH JUN-92" will compute the stats for June 92. MONTH is inactive as default. Please read the warnings for "PREVIOUS" and "LAST"! NI | NOINCOM ------------ Tells XStat to suppress evaluation of incoming calls; defaults to off. Specify "NI" to suppress evaluation of incoming calls. Meaning of this switch was inverted before version 1.04. NO | NOOUTGO ------------ Tells XStat to suppress evaluation of outgoing calls; defaults to off. Specify "NO" to suppress evaluation of outgoing calls. Meaning of this switch was inverted before version 1.04. Q | QUIET --------- Tells XStat to suppress non-fatal error messages; defaults to off. Specify QUIET to suppress non-fatal errors. This is very handy for getting rid of those "(ignoring this one)" messages for failed connects. H | HOSTNAME ------------ Tells XStat to evaluate calls to host only; defaults to all hosts. Starting with V1.06, if contains any valid AmigaDos pattern, XStat will display subtotals for each host that matches these patterns. Patterns are not case sensitive. Example: XStat hostname (a|x)#? will evaluate calls to all hosts that start with an "a" or "x", and will display sub-totals for each of those hosts. New feature in 1.15: If the hostname is a simple string (no AmigaDOS patterns in it), then XStat will just produce statistics for that hosts, NOT any "TOTAL"s. SE | STDERR ----------- Tells XStat to send all error messages to StdErr instead of StdOut. Then you can redirect the statistic output to a file using ">File", without redirecting the error messages to that file as well. Redirection defaults to off; specify STDERR to enable redirecting error messages to StdErr. StdErr is always the console window XStat was started from. The STDERR option was tested with the standard AmigaShell only. It *should* work with other shells, too. P | PERIOD numdays ------------------ Display the statistics for a certain period of time; the period is from "FROMDATE" to "FROMDATE+numdays". WARNINGS: (1) this overrides both "MONTH" and "TODATE" (2) there's no sanity checking done on "numdays", you can cause an internal overflow by specifying extremely large values (3) you're not allowed to specify "PERIOD" and "LAST" simultaneously (4) "numdays"=1 displays statistics for "FROMDATE" and the following day L | LAST numdays ---------------- Display the statistics for a certain period of time; the period is from "TODATE-numdays" to "TODATE". WARNINGS: (1) this overrides both "MONTH" and "FROMDATE" (2) there's no sanity checking done on "numdays", you can cause an internal underflow by specifying extremely large values (3) you're not allowed to specify "PERIOD" and "LAST" simultaneously (4) "numdays"=1 displays statistics for "TODATE" and the day before XStat's output ============== Example: > (On 25-DEC-93) XStat last 30 > > XStat 1.15 > © Copyright 1992-94 by Jürgen Weinelt > XStat is Freeware - read the docs for details. > > > > TOTAL: Connection statistics for incoming calls. > [...] > > > > TOTAL: Connection statistics for outgoing calls. > > Transfer statistics from 25-Nov-93 18:24:07 to 25-Dez-93 18:24:07 > > number of connects 54 > local connects 0 > ignored connects 0 > > total online time 8112 seconds > total phone units 98 units > total phone cost 22.540 DM > average online time 151 seconds/connect > average phone units 1.815 units/connect > average phone cost 0.417 DM/connect > > total gross read 10491743 bytes > total gross send 1819008 bytes > total net read 8347777 bytes > total net send 106961 bytes > average gross read 194292 bytes/connect > average gross send 33686 bytes/connect > average net read 154589 bytes/connect > average net send 1981 bytes/connect > > average speed 1517 CPS (gross data transfer) > fastest connect 1653 CPS (gross data transfer) > average speed 1042 CPS (net data transfer) > fastest connect 1366 CPS (net data transfer) > > average cost 1.920 DM/MB (gross data transfer) > average cost 2.795 DM/MB (net data transfer) Notes: "gross" means, the figure includes the protocol overhead. "net" means, the figure excludes the protocol overhead. History ======= V1.15 fixed FORMS.doc, fixed formatting bug, enhanced the "&HN" format, added "WARN" returncode for empty statistics (no connects). V1.14 added output formats, connection time offset, flat rate feature V1.13 added "PREVIOUS" and "LAST", added date line to output V1.12 added ".illegal." feature fixed a potential bug in the XferStat parsing code V1.11 added multiple N-line feature and ".default." host name to XStat.data N-Line Syntax. fixed a minor bug in the EOF handling of the Xferstat parser. V1.10 added multiple name feature to XStat.data N-Line syntax fixed a small bug in the NI/NO feature V1.09 added LOCAL and IGNORE to XStat.data C-line syntax V1.08 added STDERR option, replaced "ø" with "av." V1.07 list of connection statistics was not sorted correctly. Fixed. V1.06 extended "hostname" to include pattern matching and "per host" feature V1.05 added "per host" statistics V1.04 fixed a bug (problem with locale), switched to dos.library "ReadArgs()" V1.03 added monthly statistics. V1.02 added peak brutto/netto cps rating. V1.01 XStat used to guru when brutto or netto xfer was 0 bytes. Fixed. V1.00 initial release. V0.9x several test/beta versions, limited circulation Known problems/bugs =================== The MONTH option yields inaccurate results. This is not a bug in XStat. The date conversion routines from dos.library are broken; C= will fix this in the release version of [whatever comes after Kickstart 3.0]. The online time is not very accurate. That's because the connection start time seems to state the time the modem says "CONNECT", not the real start time of the (phone line) connection. This can be improved by using the new 1.14 "connection time offset" feature. If you have questions or bug reports... ======================================= You can contact me by eMail: jow@rz.uni-wuerzburg.de (preferred) jow@hcast.franken.de jow@hcast.adsp.sub.org (avoid if possible) Or through the snail mail: Jürgen Weinelt Franz-Ludwig-Strasse 10 D-97072 Wuerzburg Germany You might also try posting to alt.sys.amiga.uucp. Thanks ====== The following people contributed suggestions and bug reports: Christian Balzer Kai Bolay Christof Damian Hartmut "Essich" Goebel Tommy V. Hansen Tapio Heiskanen Michael-Wolfgang Hohmann Alfredo Jahn V Andrew "Charly" Kopp Erik Kunze Matthias "Tron" Scheler Henning "Barnard" Schmiedehausen Kai "wusel" Siering Peter "Peti" Simons Thank you all.