XStat V1.13 Documentation ========================= Program and documentation are (C) Copyright 1992,1993 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.13 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 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. 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 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. 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 # #------------------------------------------------------------------------------ # bigbang, this is a local (e.g. null-modem) connection #------------------------------------------------------------------------------ N bigbang 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=PREVIOUS/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. 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 | PREVIOUS 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 08-AUG-93) XStat LAST 30 HOSTNAME #? > > XStat 1.13 > © Copyright 1992,1993 by Jürgen Weinelt > XStat is Freeware - read the docs for details. > > Connection statistics for outgoing calls to host "cbmger": > > xfer statistics from 09-Jul-93 00:32:27 to 08-Aug-93 00:32:27 > > connects 4 (0 of them were local) > online time 924 sec ( 231 sec/connect) > units 25 units ( 6.250 units/connect) > cost 5.75 DM ( 1.437 DM/connect) > > gross read 1309936 bytes ( 327484 bytes/connect) > gross send 37044 bytes ( 9261 bytes/connect) > net read 1266359 bytes ( 316590 bytes/connect) > net send 3329 bytes ( 833 bytes/connect) > > av. gross speed 1457 cps ( 1489 cps peak) > av. net speed 1374 cps ( 1414 cps peak) > av. gross cost 4.476 DM/MB > av. net cost 4.749 DM/MB > > > Connection statistics for outgoing calls to host "imart": > > xfer statistics from 09-Jul-93 00:32:27 to 08-Aug-93 00:32:27 > > connects 60 (0 of them were local) > online time 11936 sec ( 199 sec/connect) > units 133 units ( 2.217 units/connect) > cost 30.59 DM ( 0.510 DM/connect) > > gross read 6034293 bytes ( 100572 bytes/connect) > gross send 1064930 bytes ( 17749 bytes/connect) > net read 4735238 bytes ( 78921 bytes/connect) > net send 55204 bytes ( 921 bytes/connect) > > av. gross speed 594 cps ( 1768 cps peak) > av. net speed 401 cps ( 1321 cps peak) > av. gross cost 4.518 DM/MB > av. net cost 6.696 DM/MB > > > Connection statistics for incoming calls: > ----------------------------------------- > > xfer statistics from 09-Jul-93 00:32:27 to 08-Aug-93 00:32:27 > > no connects recorded. > > > Connection statistics for outgoing calls: > ----------------------------------------- > > xfer statistics from 09-Jul-93 00:32:27 to 08-Aug-93 00:32:27 > > connects 64 (0 of them were local) > ignored connects 0 > online time 12860 sec ( 201 sec/connect) > units 158 units ( 2.469 units/connect) > cost 36.34 DM ( 0.568 DM/connect) > > gross read 7344229 bytes ( 114754 bytes/connect) > gross send 1101974 bytes ( 17219 bytes/connect) > net read 6001597 bytes ( 93775 bytes/connect) > net send 58533 bytes ( 915 bytes/connect) > > av. gross speed 656 cps ( 1768 cps peak) > av. net speed 471 cps ( 1414 cps peak) > av. gross cost 4.512 DM/MB > av. net cost 6.288 DM/MB connects -------- Number of connects, and number of local (=free) connects (XStat.data "C LOCAL"). ignored connects ---------------- Number of connects that were IGNOREd (-> XStat.data "C IGNORE"). online time ----------- Total online time, and average online time per connect. units ----- Phone units consumed, and average phone units consumed per connect. Note: in Germany, a "phone unit" is an indivisible time quantum (sounds like quantum physics :-). This means even if your connect is shorter than that, the phone company still charges for the entire time quantum. Example: unit duration is 60 seconds, connect time was 97 seconds, phone company charges two units (120 seconds). You can influence the unit duration by editing the XStat.data file; the in the "C"-lines tells XStat the unit duration. cost ---- Total cost, and average cost per connect. gross read ---------- Total bytes read (including protocol information), and average (per connect). gross send ---------- Total bytes sent (including protocol information), and average (per connect). net read -------- Total bytes read (excluding protocol information), and average (per connect). net send -------- Total bytes sent (excluding protocol information), and average (per connect). av. gross speed --------------- Average transmission speed, including protocol overhead, and speed of fastest connect. av. net speed ------------- Average transmission speed, excluding protocol overhead, and speed of fastest connect. av. gross cost -------------- Average cost per MByte, including protocol overhead. av. net cost ------------ Average cost per MByte, excluding protocol overhead. History ======= 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 yield 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. If you have questions or bug reports... ======================================= You can contact me by eMail: jow@sun.rz.uni-wuerzburg.de (preferred) jow@hcast.adsp.sub.org jow@hcast.franken.de Or through the snail mail: Jürgen Weinelt Zur Kanzel 1 D-97762 Hammelburg Germany You might also try posting to alt.sys.amiga.uucp. Thanks ====== The following people contributed suggestions and bug reports: Christian Balzer Kai Bolay Hartmut Goebel Michael-Wolfgang Hohmann Alfredo Jahn V Andrew Kopp Henning Schmiedehausen Kai "wusel" Siering Peter Simons Thank you all.