home *** CD-ROM | disk | FTP | other *** search
/ back2roots/padua / padua.7z / padua / uucp / XStat114.lha / XStat.doc < prev    next >
Encoding:
Text File  |  1993-12-25  |  17.1 KB  |  554 lines
  1. XStat V1.14 Documentation
  2. =========================
  3.  
  4. Program and documentation are (C) Copyright 1992,1993 by Jⁿrgen Weinelt.
  5.  
  6. IMPORT StdDisclaimer; (* in short: use it at your own risk *)
  7. XStat was carefully tested, but there's certainly plenty of room for bugs.
  8.  
  9. XStat V1.14 is Freeware, non-commercial distribution is o.k. as long as
  10. the following conditions are met:
  11.  
  12.   * Source, executable and documentation must be distributed together
  13.     (XStat.mod, XStat, XStat.data, XStat.doc, XStat.dok and Make),
  14.     and these files must be intact (you're not allowed to make changes).
  15.     You're NOT allowed to add files to the archive.
  16.  
  17.   * This program may be included on PD/freeware CDs if I am allowed
  18.     to order one of those CDs at 50% off the retail price (or cheaper :).
  19.     Of course a free copy of the CD would be even nicer...
  20.  
  21.     Exception: Fred Fish has UNCONDITIONAL permission to add this
  22.     program version to his library, no matter if he's distributing it
  23.     on floppy disk or on CD.
  24.  
  25.  
  26.  
  27. XStat requires AmigaOS V37 or later (that's 2.04 or later).
  28.  
  29.  
  30.  
  31. Purpose
  32. =======
  33. XStat extracts statistic information from the Xferstat file created
  34. by some UUCICOs (tested with the SWB and wUUCP variant). The most
  35. important information XStat offers to you is the phone cost for a
  36. certain number of connects.
  37.  
  38.  
  39.  
  40. Installation
  41. ============
  42. Copy the executable "XStat" to a directory in your "Path", preferably UUBIN:
  43.  
  44. There's only one more file that needs to be installed; it's called
  45. "XStat.data", and should be copied to your UULIB: directory.
  46.  
  47. You'll have to customize (edit) XStat.data to complete the installation.
  48.  
  49. The new V1.14 output formats and associated environment variables are
  50. documented in the file "FORMS.doc".
  51.  
  52.  
  53.  
  54. XStat.data
  55. ==========
  56. XStat.data contains the phone cost on a "per host" basis, in the following
  57. format:
  58.  
  59. XStat.data file header:
  60. -----------------------
  61. H XSTAT DATA
  62.  
  63. This header must be the first line of XStat.data
  64.  
  65. XStat.data comment line:
  66. ------------------------
  67. # any comments you wish to add to XStat.data
  68.  
  69. You may add comment lines anywhere in your XStat.data file, except before
  70. the file header.
  71.  
  72. XStat.data currency sign info:
  73. ------------------------------
  74. S <currency sign>
  75.  
  76. Tells XStat the currency sign for your country. This line must come before
  77. the first "N"-line. There can be only one "S"-line in your XStat.data file.
  78.  
  79. Examples:
  80.  
  81. # currency sign for the U.S.A.
  82. S $
  83.  
  84. # currency sign for Germany
  85. S DM
  86.  
  87. XStat.data host name info:
  88. --------------------------
  89. N <host name> <host name> ...
  90.  
  91. Starts a new connection cost data record. Must be followed by at least
  92. one "C"-line. <host name> should be the name of a host you're directly
  93. connected to, without any path or domain information.
  94.  
  95. Examples:
  96.  
  97. # my own newsfeed
  98. N imart
  99.  
  100. # my alternate newsfeed
  101. N cbmger
  102.  
  103. Since XStat V1.10, you can use the extended N-line syntax that allows
  104. you to specify multiple host names in a single N-line. All those hosts
  105. will have the same cost information.
  106.  
  107. Example:
  108.  
  109. # several hosts that have the same cost info's
  110. N cbmger brewak forge
  111.  
  112. Since XStat V1.11, you can use several consecutive N-lines.
  113.  
  114. Example:
  115.  
  116. # several hosts that have the same cost info's
  117. N cbmger
  118. N brewak forge
  119.  
  120. Maximum line length of a N-line is 100 characters.
  121.  
  122. Since XStat V1.11, you can also use the reserved host name ".default.".
  123. This cost info will be used for every connect for which the host name
  124. cannot be found in XStat.data.
  125.  
  126. Since XStat V1.12 you can also use the reserved host name ".illegal.".
  127. This name will be used by XStat whenever an XferStat line with empty
  128. host name is encountered; some UUCiCos write such lines when a
  129. connection is aborted prematurely.
  130.  
  131. XStat.data connection duration offset info:
  132. -------------------------------------------
  133. O <offset>
  134.  
  135. Tells XStat that the connection duration in the XferStat file is
  136. off by <offset> seconds. You can use this to compensate for the
  137. connection negotiation phase of the modems (which does not appear
  138. in the XferStat connection time). The option was only tested with
  139. positive offsets. The "O" line must come directly after the "N"
  140. line. There can be only one "O" line per host.
  141.  
  142. Example:
  143. N imart
  144. O 13
  145. C ...
  146.  
  147. Tells XStat that my modem will usually need 13 seconds to negotiate
  148. a connection with imart.
  149.  
  150. XStat.data connection time/cost info:
  151. -------------------------------------
  152. C <start time> <duration> <price>
  153.  
  154. Tells XStat that between <start time> and <start time of next C-line>
  155. a connection will cost <price> per <duration>. "C"-lines must follow
  156. a "N"-line. <duration> must be in seconds, <price> in the currency of
  157. your choice.
  158.  
  159. The first "C"-line must be for "SU-00:00:00"!
  160. (see exception at LOCAL/IGNORE below)
  161.  
  162. Example:
  163. N imart
  164. C SU-00:00:00 120 0.23
  165. C MO-08:00:00  60 0.23
  166. C MO-18:00:00 120 0.23
  167.  
  168. From Sunday 0:00:00 to Monday 7:59:59, a connection between my
  169. site and my newsfeed "imart" will cost 0.23DM/120sec.
  170.  
  171. Between Monday 8:00:00 and Monday 17:59:59, a connection between my site
  172. and my newsfeed "imart" will cost 0.23DM/60sec.
  173.  
  174. With this short example, the connection cost for the rest of the
  175. week (from Monday 18:00:00 to Saturday 23:59:59) would be 0.23DM/120sec.
  176.  
  177. Since Version 1.09 there's another possible C-line syntax... you
  178. can also use "C IGNORE" to tell XStat to ignore all connections from
  179. and to that particular host, or you can use "C LOCAL" to specify a
  180. local connection without connection costs (only the in/out bytes
  181. will be counted in this case). If you use "LOCAL" or "IGNORE", you
  182. may NOT use the normal C-line syntax for that host.
  183. "LOCAL" and "IGNORE" are mutually exclusive.
  184.  
  185.  
  186. Example:
  187. N imart
  188. C IGNORE
  189.  
  190. will cause all connects from/to imart to be ignored.
  191.  
  192.  
  193. Example:
  194. N imart
  195. C LOCAL
  196.  
  197. will cause all connects from/to imart to be counted with cost=0.
  198.  
  199.  
  200. Since Version 1.14, you can also use a unit duration of "0" seconds,
  201. which will instruct XStat to assume a "flat rate" for the
  202. corresponding connections (one single "unit" will be counted for
  203. those connections).
  204.  
  205. Example:
  206. N imart
  207. C SU-00:00:00   0 0.23
  208. C MO-08:00:00  60 0.23
  209. C MO-18:00:00 120 0.23
  210.  
  211. Connections between Sunday, 0:00 and Monday, 8:00 will cost one
  212. single unit, no matter how long they were.
  213.  
  214.  
  215. Full length example for XStat.data:
  216. -----------------------------------
  217.  
  218. - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut -
  219. H XSTAT DATA
  220. #==============================================================================
  221. # XStat connection cost data file
  222. #==============================================================================
  223. #
  224. #------------------------------------------------------------------------------
  225. # currency sign for Germany; S must come before first N
  226. #------------------------------------------------------------------------------
  227. S DM
  228. #
  229. #------------------------------------------------------------------------------
  230. # my own newsfeed, connection cost is 0.23/60sec (0.23/120sec night & weekend)
  231. #------------------------------------------------------------------------------
  232. N imart
  233. N .illegal.
  234. C SU-00:00:00 120 0.23
  235. C MO-08:00:00  60 0.23
  236. C MO-18:00:00 120 0.23
  237. C TU-08:00:00  60 0.23
  238. C TU-18:00:00 120 0.23
  239. C WE-08:00:00  60 0.23
  240. C WE-18:00:00 120 0.23
  241. C TH-08:00:00  60 0.23
  242. C TH-18:00:00 120 0.23
  243. C FR-08:00:00  60 0.23
  244. C FR-18:00:00 120 0.23
  245. #
  246. #------------------------------------------------------------------------------
  247. # cbmger, brewak, forge, default:
  248. # connection cost is 0.23/21sec (0.23/42sec night & weekend)
  249. #------------------------------------------------------------------------------
  250. N cbmger
  251. N brewak forge
  252. N .default.
  253. C SU-00:00:00  42 0.23
  254. C MO-08:00:00  21 0.23
  255. C MO-18:00:00  42 0.23
  256. C TU-08:00:00  21 0.23
  257. C TU-18:00:00  42 0.23
  258. C WE-08:00:00  21 0.23
  259. C WE-18:00:00  42 0.23
  260. C TH-08:00:00  21 0.23
  261. C TH-18:00:00  42 0.23
  262. C FR-08:00:00  21 0.23
  263. C FR-18:00:00  42 0.23
  264. #
  265. #------------------------------------------------------------------------------
  266. # modula, this is a local (e.g. null-modem) connection
  267. #------------------------------------------------------------------------------
  268. N modula
  269. C LOCAL
  270. #
  271. #------------------------------------------------------------------------------
  272. # walker, connects will be ignored
  273. #------------------------------------------------------------------------------
  274. N walker
  275. C IGNORE
  276. #
  277. - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut -
  278.  
  279.  
  280.  
  281. Usage
  282. =====
  283. XStat [?] [DATA name] [FILE name] [V | VERBOSE] [FD | FROMDATE date]
  284.           [TD | TODATE date] [NI | NOINCOM] [NO | NOOUTGO]
  285.           [H | HOSTNAME name] [M | MONTH shortdate] [SE | STDERR]
  286.           [P | PREVIOUS numdays] [L | LAST numdays]
  287.  
  288. Alternate description:
  289.  
  290. XStat FILE/K,DATA/K,V=VERBOSE/S,M=MONTH/K,NI=NOINCOM/S,NO=NOOUTGO/S,
  291.       Q=QUIET/S,H=HOSTNAME/K,FD=FROMDATE/K,TD=TODATE/K,SE=STDERR/S,
  292.       P=PREVIOUS/N,L=LAST/N
  293.  
  294. You may also use the environment variable "XSTATARGS" to specify
  295. parameters. This is very useful if you're using XStat from the
  296. Workbench (XStat doesn't really support Workbench, that's why
  297. there's no icon for it).
  298.  
  299. ?
  300. -
  301. Displays a help message.
  302.  
  303. DATA name
  304. ---------
  305. Tells XStat to read its connection cost data from file <name>.
  306. <name> defaults to "UULIB:XStat.data".
  307.  
  308. FILE name
  309. ---------
  310. Tells XStat to extract the statistic information from file <name>.
  311. <name> defaults to "UUSPOOL:XferStat".
  312.  
  313. V | VERBOSE
  314. -----------
  315. Enables the "verbose" mode. When on, XStat displays short statistics
  316. for every connect found in the Xferstat file. Defaults to "off".
  317. Specify VERBOSE to turn verbose mode on.
  318.  
  319. WARNING! The VERBOSE option will be changed drastically soon (probably
  320. in the next release).
  321.  
  322. FD | FROMDATE date
  323. ------------------
  324. Tells XStat to ignore connects before <date>. <date> defaults to "01-JAN-78".
  325. You may use any valid AmigaDOS date string, including things like
  326. "TODAY" or "YESTERDAY". XStat will add a time string of "00:00:00" internally,
  327. you may not do this yourself. Be careful, if you're using Workbench 2.1 (which
  328. is [ought to be] currently available to registered developers only) you'll have
  329. to use your locale date specifications, for example "HEUTE" instead of "TODAY"
  330. if you're using the german locale.
  331. Please read the warnings for "PREVIOUS" and "LAST"!
  332.  
  333. TD | TODATE date
  334. ----------------
  335. Tells XStat to ignore connects after <date>. <date> defaults to current
  336. date/time. You may use any valid AmigaDOS date string, including things
  337. like "TODAY" or "YESTERDAY" (with the same 2.1/locale limitations as FD).
  338. XStat will add a time string of "23:59:59" internally, you may not do this
  339. yourself.
  340. Please read the warnings for "PREVIOUS" and "LAST"!
  341.  
  342. M | MONTH shortdate
  343. -------------------
  344. Tells XStat to ignore FD and TD, and to compute the statistics for the
  345. specified month instead. The month must be given in the format "MMM-YY",
  346. without specifying the day. Example: "MONTH JUN-92" will compute the stats
  347. for June 92. MONTH is inactive as default.
  348. Please read the warnings for "PREVIOUS" and "LAST"!
  349.  
  350. NI | NOINCOM
  351. ------------
  352. Tells XStat to suppress evaluation of incoming calls; defaults to off.
  353. Specify "NI" to suppress evaluation of incoming calls. Meaning of this
  354. switch was inverted before version 1.04.
  355.  
  356. NO | NOOUTGO
  357. ------------
  358. Tells XStat to suppress evaluation of outgoing calls; defaults to off.
  359. Specify "NO" to suppress evaluation of outgoing calls. Meaning of this
  360. switch was inverted before version 1.04.
  361.  
  362. Q | QUIET
  363. ---------
  364. Tells XStat to suppress non-fatal error messages; defaults to off.
  365. Specify QUIET to suppress non-fatal errors.
  366.  
  367. This is very handy for getting rid of those "(ignoring this one)" messages
  368. for failed connects.
  369.  
  370. H | HOSTNAME
  371. ------------
  372. Tells XStat to evaluate calls to host <name> only; defaults to all hosts.
  373. Starting with V1.06, if <name> contains any valid AmigaDos pattern,
  374. XStat will display subtotals for each host that matches these patterns.
  375.  
  376. Patterns are not case sensitive.
  377.  
  378. Example: XStat hostname (a|x)#?
  379.          will evaluate calls to all hosts that start with an "a" or "x",
  380.          and will display sub-totals for each of those hosts.
  381.  
  382. SE | STDERR
  383. -----------
  384. Tells XStat to send all error messages to StdErr instead of StdOut.
  385. Then you can redirect the statistic output to a file using ">File",
  386. without redirecting the error messages to that file as well.
  387. Redirection defaults to off; specify STDERR to enable redirecting
  388. error messages to StdErr. StdErr is always the console window
  389. XStat was started from. The STDERR option was tested with the
  390. standard AmigaShell only. It *should* work with other shells, too.
  391.  
  392. P | PREVIOUS numdays
  393. --------------------
  394. Display the statistics for a certain period of time; the period
  395. is from "FROMDATE" to "FROMDATE+numdays".
  396.  
  397. WARNINGS:
  398. (1) this overrides both "MONTH" and "TODATE"
  399. (2) there's no sanity checking done on "numdays", you can cause
  400.     an internal overflow by specifying extremely large values
  401. (3) you're not allowed to specify "PERIOD" and "LAST" simultaneously
  402. (4) "numdays"=1 displays statistics for "FROMDATE" and the following day
  403.  
  404. L | LAST numdays
  405. ----------------
  406. Display the statistics for a certain period of time; the period
  407. is from "TODATE-numdays" to "TODATE".
  408.  
  409. WARNINGS:
  410. (1) this overrides both "MONTH" and "FROMDATE"
  411. (2) there's no sanity checking done on "numdays", you can cause
  412.     an internal underflow by specifying extremely large values
  413. (3) you're not allowed to specify "PERIOD" and "LAST" simultaneously
  414. (4) "numdays"=1 displays statistics for "TODATE" and the day before
  415.  
  416.  
  417.  
  418. XStat's output
  419. ==============
  420.  
  421. Example:
  422.  
  423. > (On 25-DEC-93) XStat last 30
  424. >
  425. > XStat 1.14
  426. > ⌐ Copyright 1992,1993 by Jⁿrgen Weinelt
  427. > XStat is Freeware - read the docs for details.
  428. >
  429. >
  430. >
  431. > TOTAL: Connection statistics for incoming calls.
  432. >
  433. [...]
  434. >
  435. >
  436. >
  437. > TOTAL: Connection statistics for outgoing calls.
  438. >
  439. > Transfer statistics from 25-Nov-93 18:24:07 to 25-Dez-93 18:24:07
  440. >
  441. > number of connects        54
  442. > local connects             0
  443. > ignored connects           0
  444. >
  445. > total online time       8112     seconds
  446. > total phone units         98     units
  447. > total phone cost          22.540 DM
  448. > average online time      151     seconds/connect
  449. > average phone units        1.815 units/connect
  450. > average phone cost         0.417 DM/connect
  451. >
  452. > total gross read    10491743     bytes
  453. > total gross send     1819008     bytes
  454. > total net read       8347777     bytes
  455. > total net send        106961     bytes
  456. > average gross read    194292     bytes/connect
  457. > average gross send     33686     bytes/connect
  458. > average net read      154589     bytes/connect
  459. > average net send        1981     bytes/connect
  460. >
  461. > average speed           1517     CPS (gross data transfer)
  462. > fastest connect         1653     CPS (gross data transfer)
  463. > average speed           1042     CPS (net data transfer)
  464. > fastest connect         1366     CPS (net data transfer)
  465. >
  466. > average cost               1.920 DM/MB (gross data transfer)
  467. > average cost               2.795 DM/MB (net data transfer)
  468.  
  469. Notes:
  470.  
  471. "gross" means, the figure includes the protocol overhead.
  472.  
  473. "net" means, the figure excludes the protocol overhead.
  474.  
  475.  
  476.  
  477. History
  478. =======
  479. V1.14   added output formats, connection time offset, flat rate feature
  480. V1.13   added "PREVIOUS" and "LAST", added date line to output
  481. V1.12   added ".illegal." feature
  482.         fixed a potential bug in the XferStat parsing code
  483. V1.11   added multiple N-line feature and ".default." host name to XStat.data
  484.           N-Line Syntax.
  485.         fixed a minor bug in the EOF handling of the Xferstat parser.
  486. V1.10   added multiple name feature to XStat.data N-Line syntax
  487.         fixed a small bug in the NI/NO feature
  488. V1.09   added LOCAL and IGNORE to XStat.data C-line syntax
  489. V1.08   added STDERR option, replaced "°" with "av."
  490. V1.07   list of connection statistics was not sorted correctly. Fixed.
  491. V1.06   extended "hostname" to include pattern matching and "per host" feature
  492. V1.05   added "per host" statistics
  493. V1.04   fixed a bug (problem with locale), switched to dos.library "ReadArgs()"
  494. V1.03   added monthly statistics.
  495. V1.02   added peak brutto/netto cps rating.
  496. V1.01   XStat used to guru when brutto or netto xfer was 0 bytes. Fixed.
  497. V1.00   initial release.
  498.  
  499. V0.9x   several test/beta versions, limited circulation
  500.  
  501.  
  502.  
  503. Known problems/bugs
  504. ===================
  505. The MONTH option yields inaccurate results. This is not a bug in XStat.
  506. The date conversion routines from dos.library are broken; C= will fix this
  507. in the release version of [whatever comes after Kickstart 3.0].
  508.  
  509. The online time is not very accurate. That's because the connection start
  510. time seems to state the time the modem says "CONNECT", not the real
  511. start time of the (phone line) connection. This can be improved by using
  512. the new 1.14 "connection time offset" feature.
  513.  
  514.  
  515.  
  516. If you have questions or bug reports...
  517. =======================================
  518. You can contact me by eMail:
  519.  
  520.    jow@rz.uni-wuerzburg.de (preferred)
  521.    jow@hcast.franken.de
  522.    jow@hcast.adsp.sub.org (avoid if possible)
  523.  
  524. Or through the snail mail:
  525.  
  526.    Jⁿrgen Weinelt
  527.    Zur Kanzel 1
  528.    D-97762 Hammelburg
  529.    Germany
  530.  
  531. You might also try posting to alt.sys.amiga.uucp.
  532.  
  533.  
  534.  
  535. Thanks
  536. ======
  537. The following people contributed suggestions and bug reports:
  538.  
  539.          Christian Balzer
  540.                Kai Bolay
  541.           Christof Damian
  542.            Hartmut Goebel
  543.           Tommy V. Hansen
  544.              Tapio Heiskanen
  545.   Michael-Wolfgang Hohmann
  546.            Alfredo Jahn V
  547.             Andrew Kopp
  548.    Matthias "Tron" Scheler
  549.            Henning Schmiedehausen
  550.        Kai "wusel" Siering
  551.              Peter Simons
  552.  
  553. Thank you all.
  554.