This is Info file tua.info, produced by Makeinfo-1.63 from the input
file tua.texinfo.

  This file documents TUA, The Uucp Analyzer, a tool that analyze the
BNU Uucp connections of your machine.

  Copyright (C) 1991,96 Emanuele Gaifas.

  This is the the first edition of this manual in Texinfo and replaces
the previous document in NROFF text format.

  Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

  Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

  Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.


File: tua.info,  Node: Top,  Next: Copying,  Prev: (dir),  Up: (dir)

TUA - The Uucp Analyzer
***********************

  TUA is a tool that extract as much info as it can from the logs
produced by the various BNU Uucp programs, and build a complete report
of what is going on with your links.

* Menu:

* Copying::                     TUA Copying Conditions
* Overview::                    Overview of TUA
* Options::                     Descriptions of all the Options
* Output::                      Detailed explanation of what you will see
* History::                     How TUA maintains the historical data
* TCL::                         TCL Interface
* GNU General Public License::
* Bugs::                        Known deficiencies
* Author::                      Who wrote it, and why
* Acknowledgment::              I wanna thanks...
* Disclaimer::                  I'm not the guilty
* Compilation and Installation::
* Files::                       Files used by TUA
* Taylor Uucp Patch::
* Concept Index::               Concept Index

 -- The Detailed Node Listing --

Detailed report description

* By System::                   The system per system report
* By User::                     A report from a per user point of view
* Daily::                       What happened on Aug, 16th?
* Summary by System::           Details on each system
* Summary by System (table format)::  The same in a tabular form
* Since::                       The historical report
* Last 12 months Activity::     A summary of the last 12 months activity
* Hourly Activity::             Charts showing the per port activity

TCL Interface

* More about TCL::              Where you can get more info
* Available TCL commands::      List of the available commands
* Adding new TCL commands::     How to add your own commands

Available TCL commands

* Command List::                List of available TCL commands
* Examples::                    A sample Initialization Script

Bugs

* Bugs Report::                 Bugs Report

Files

* HDB Uucp Files::              Files used in HDB mode
* Taylor Uucp Files::           Files used in Taylor mode
* PCD File::                    Phone Category Description
* TCL Files::
* NLS Files::                   National Language Support files


File: tua.info,  Node: Copying,  Next: Overview,  Prev: Top,  Up: Top

TUA Copying Conditions
**********************

  TUA is "free"; this means that everyone is free to use it and free to
redistribute it on a free basis. It is NOT in the public domain; TUA is
copyrighted and there are restrictions on its distribution, but these
restrictions are designed to permit everything that a good cooperating
citizen would want to do.  What is not allowed is to try to prevent
others from further sharing any version of this programs that they
might get from you.

  *Note GNU General Public License:: for more details on the
distribution policy.


File: tua.info,  Node: Overview,  Next: Options,  Prev: Copying,  Up: Top

Overview of TUA
***************

  TUA is NOT simply a "Yet Another Uucp Analyzer": its purpose is to
produce a readable and complete analysis of the `UUCP' connections. TUA
is able to extract a report from both `HoneyDanBer UUCP'(1) and `Taylor
Uucp'.

  The report shows, from several points of view, what exactly is going
on at your site. For a detailed description of the output, see *Note
Output::.

  This is done by reading the various logs UUCP produces(2) , as well
as `.../tua.history', that is where TUA records the historical data.
The exact pathnames of these files are defined in the customization
file `src/customize.h'.

  TUA has several command line options that change its behavior, for
example to restrict the range of the systems analyzed. For a list of all
the options, see *Note Options::.

  TUA 4.0 is backward compatible with the previous released version,
TUA 3.3, at both the command line option level and the format of the
`tua.history'. If you have compiled in both Taylor Uucp and HDB Uucp
support, Taylor Uucp will be the default mode. To specify a different
Uucp use the options '-hdb-uucp' or '-taylor-uucp' (this can be changed
editing `src/customize.h').

  TUA 4.1 and higher may even be configured to print out its messages in
whatever national language you want (other than english, of course),
taking advantage of the `GNU gettext' package. Actually, only *italian*
translation of the messages is provided within the distribution
package, but you can very easily add your own. As usual, if you do it,
I'll be happy to include your translated `.po' files in the
distribution, although surely I cannot check their exactness.

  ---------- Footnotes ----------

  (1)  Also known as `BNU Uucp' or `HDB Uucp'

  (2)  `.../.Admin/xferstats' and the `.../.Log/' directory hierarchy
for HDB Uucp, `.../Stats' and `.../Log' for Taylor Uucp


File: tua.info,  Node: Options,  Next: Output,  Prev: Overview,  Up: Top

Command line options
********************

  To specify any of the options, you can use either the short form or
the more mnemonic long form. In the latter case, you can abbreviate the
name as long as it is unique. For more information on the long format,
please refer to the `GNU getopt' package description.

`-a NAME'
`--country NAME'
     After option processing, TUA reads the Phone Categories Definition
     file (*note PCD File::.). This file may contain a default value
     for your country, near the top of the file. You may however
     override that value using this option. If the pcd file does not
     contain a definition for the country you specified (either with
     -country or with the "default" directive inside the pcd file
     itself), TUA will print a message on the standard error stating
     that it will not print the phone costs in the report.

`--print-country'
     Print the current country information and exit. The definition is
     printed in the same format you specified it in the PCD file. This
     is mainly used to check the content of this file.

`--list-countries'
     Print a list of the countries present in the PCD file, and exit.

`-S'
`--no-system-rep'
     Do not print the "per System report" (*note By System::.). The
     default is to print it out.

`-U'
`--no-user-rep'
     Do not print the "per User report" (*note By User::.). The default
     is to print it out.

`-D'
`--no-daily-rep'
     Do not print the "Daily report" (*note Daily::.). The default is
     to print it out.

`-C'
`--command-lists'
     Show also the command lists. It is off by default because TUA
     becomes very hungry of memory since it needs to store in memory
     all the commands executed. Anyway, it is a nice way to see where
     is going all those megs of e-mail everyday!

`-O SYSTEM'
`--only-system SYSTEM'
     Consider just system SYSTEM in the reports. You can specify more
     than one of this option, so you can have TUA consider just those
     systems.

`-m'
`--no-monthly-act'
     Do not output the last 12 months activity summary.

`-h'
`--no-history'
     Do not output the history at the end of the reports.

`-c'
`--separate-command-report'
     Separate command lists from the other data. So there will be two
     tables with the header "By System" (*note By System::.), the first
     containing only the amounts and the timing of each transfer, the
     second with all the commands invoked by each System. This option
     implies `--command-lists'.

`-k SYSTEM'
`--kill-system SYSTEM'
     Eliminate each reference to SYSTEM from the reports. Neither the
     transfer table nor the SYSTEM command list will be printed.

`-K USER'
`--kill-user USER'
     Like `--kill-system', but it applies to the user called USER.

`-H'
`--update-history'
     Update the `history' database (*note History::.) with the new
     values. Warning: since this option will cause TUA to write the
     historical data on your disk, you must have write permission on the
     history file `tua.history', usually located inside the spool
     directory of your UUCP. So if `tua.history' does not exist, TUA
     needs write permission on that directory to create it.

`-0'
`--reset-history'
     Reset the history database, thus clearing the non-volatile memory
     of TUA. This option must be used with `--update-history'.

`-y'
`--no-hourly-chart'
     Do not display the hourly activity chart.

`-z SIZE'
`--chart-size SIZE'
     Set the size of the hourly activity chart to SIZE rows. The greater
     this number is, the smaller is the scale. By default it is set to
     10.

`-o'
`--chart-only'
     Display only the hourly activity chart. Since with this options TUA
     reads only the statistical data produced by UUCP(1), it is faster.

`-v'
`--verbose'
     Print, on standard error, what is going on. While TUA reads the
     various logs, it displays a counter of the loaded lines. This
     option is enabled only specifying -DDEBUG at compile time.

`-p PATH'
`--prefix-path PATH'
     By default, TUA looks for uucp logs in the directory specified in
     `src/customize.h' at compile time. This option lets you change
     this directory, so that TUA looks for the data in the specified
     PATH. This is mainly for debugging purposes, but nothing stops you
     to use it for example to keep your old logs archived somewhere, so
     that you can examine them whenever you want instead of keeping
     everything on-line.

`-u USER=ALIAS'
`--user-alias USER=ALIAS'
     Inserts ALIAS as the new name for USER. Where ever appears USER it
     will be replaced with ALIAS. Since this occurs at the lowest
     level, if happens that ALIAS is another user name, this will cause
     that all the data that belongs to USER will be added to the ALIAS
     user. In this way you can create groups of users: for example you
     may want a report on your development stuff as a whole.
          $ tua --user-alias piggy=lele --user-alias gnu=lele
     This will merge data from users PIGGY and GNU with that of user
     LELE.

`-r PORT=ALIAS'
`--port-alias PORT=ALIAS'
     Like `--user-alias', but it applies to the serial port names. This
     can be useful on those OS where a single serial port has two
     names, one for normal use and the other with modem control (eg.
     `tty1a' and `tty1A').

`-s SYS=ALIAS'
`--system-alias SYS=ALIAS'
     Like `--user-alias', but it applies to the systems names.

`-E GLOB=ALIAS'
`--glob-user-alias GLOB=ALIAS'
`-R GLOB=ALIAS'
`--glob-port-alias GLOB=ALIAS'
`-M GLOB=ALIAS'
`--glob-system-alias GLOB=ALIAS'
     These are the counterpart respectively of `--user-alias',
     `--port-alias' and `--system-alias' with `meta-characters'
     searches. You can use for example
          tua --glob-user-alias uu*=UUCPUSERS
     and every user name that begins with `uu' will be mapped in a meta
     user called `UUCPUSERS'. See the manual page for `bash(1)' or
     `wildmat(3)', distribuited in the `doc' directory of the
     distribution package, for a description of `meta-characters'.

`-t'
`--no-tua-rc'
     When the TCL extensions (*note TCL::.) are enabled, TUA loads a TCL
     script upon startup. This option prevents this to occur.

`-T FILENAME'
`--rc-file FILENAME'
     Specify an alternate initializing TCL script, ie TUA will load
     FILENAME at startup instead of the standard `TUA_init.tcl'.

`-I'
`--interactive'
     Enter in interactive mode. After TUA finished to collect the data
     it needs, it will prompt you for TCL commands, in particular those
     that print some report. *Note Command List::.

`-V'
`--version'
     Print just the version, without any further processing.

`-i'
`--help'
     Show a summary and a description of all the options.

`-Y'
`--taylor-uucp'
     This option is available only if TUA was compiled with both
     TAYLOR_UUCP and HDB_UUCP defined. It forces TUA to read the Taylor
     UUCP logs, the default behaviour.

`-B'
`--hdb-uucp'
     This option is available only if TUA was compiled with both
     TAYLOR_UUCP and HDB_UUCP defined. It forces TUA to read the HDB
     Uucp logs. It will digest Taylor Uucp logs in HDB mode too, but
     this feature is not completely tested yet.

  If international support has been compiled in, TUA will use the
environment variable LANG if any to select the national language used
in the report. The only national language supported as of release 4.1
is *italian*. You are invited to send me translations of the messages
for other languages, I will add them for the next release. Consult
`ABOUT-NLS' in the distribution package for other details on how do it.

  ---------- Footnotes ----------

  (1)  `.Admin/xferstats' for HDB Uucp, `Stats' for Taylor Uucp


File: tua.info,  Node: Output,  Next: History,  Prev: Options,  Up: Top

Detailed report description
***************************

  The generated report is divided in several section, and it is printed
on the standard output, so you can easily redirect it wherever you like.

  Assuming, unless otherwise stated, that you do not explicitly request
to disable some of the reports (eg. when you do not specify any command
line option), here is a short description of what you get.

* Menu:

* By System::                   The system per system report
* By User::                     A report from a per user point of view
* Daily::                       What happened on Aug, 16th?
* Summary by System::           Details on each system
* Summary by System (table format)::  The same in a tabular form
* Since::                       The historical report
* Last 12 months Activity::     A summary of the last 12 months activity
* Hourly Activity::             Charts showing the per port activity


File: tua.info,  Node: By System,  Next: By User,  Prev: Output,  Up: Output

By System Section
=================

  With this report, you get all the information relative to all the
nodes that talk with your machine but those which didn't sent or
received something. The data are divided in `inbound' and `outbound'.

  For each system, displayed in alphabetical order, you have the total
count of the files transferred, with the relative bytes and times, as
well as an average transfer rate (ATP).

  If `--commands-lists' was specified, next there is the list of the
commands invoked by that node, or directed to it. If a command is
preceded by a number between brackets, that number indicates how many
times that command was invoked.
     By System:
     ==========
                     R E C E I V E D                       S E N T
     System  Files  KBytes    Time      ATP   Files  KBytes    Time      ATP
     
     angmar   106       16  0:03:09.30   86    116      381  0:29:07.25  223
     argo       4        4  0:00:10.62  419     22      188  0:03:38.30  879


File: tua.info,  Node: By User,  Next: Daily,  Prev: By System,  Up: Output

By User Section
===============

  This report is similar to the previous one, but it shows, in
alphabetical order for each local user, all the commands the user
invoked, and the transfers he caused.
     By User:
     ========
                             S E N T
     User         Files   KBytes      Time
     
     gnu            18        13     0:00:24.99
     news          118      2585     0:54:33.65


File: tua.info,  Node: Daily,  Next: Summary by System,  Prev: By User,  Up: Output

Daily Section
=============

  This report summarize the per day activity on the local machine. It
doesn't depend on the destinations and on the users.

  As for the By System section, this table contains
     By Day:
     =======
     Date       R E C E I V E D                     S E N T
     Mo/Dy  Files   KBytes       Time      Files   KBytes       Time
     
     01/20    14        20     0:00:45.25    20       205     0:05:02.68
     01/21   104      1511     0:32:36.31    67       715     0:18:41.43
     01/22   134      1145     0:26:12.08   102       638     0:20:51.58


File: tua.info,  Node: Summary by System,  Next: Summary by System (table format),  Prev: Daily,  Up: Output

Summary by System
=================

  It shows a summary of the activity of each system, and the number of
calls (inbound and outbound) for it.

  Please note that sometimes TUA fails in calculating the exact number
of calls, because of the misleading log of HDB uucico.

  Note also that the "total connection time" always differs from the sum
of the transmissions times, because it takes care also of the various
uucp dead time. In fact, it is calculated from the difference between
the time in which the nodes are really connected (ie. at the end of dial
phase, when the modem answers) and the time in which the link is
dropped, due to the end of the conversation as well as to any error.
(1) TUA specifies the amount of this time paid by the two connected
systems.

  The subdivision in timebands of the connection time is currently
approximated, ie it is merely the sum of the pure file transfer times,
as reported in `xferstats' if reading HDB logs, or in `Stats' with
Taylor logs. So the various dead time, such as the login phase,
inter-file delays and so on are not included. It is possible to
customize the timeband divisions and names, by changing an external
file. See *Note PCD File:: for details.

  Then comes the time of the last connection with that system.

  Finally, the total number of connections, a count of failed (i.e. that
did not reach even the dial phase) and stopped (i.e. interrupted in the
middle of the transfer, for any reason) calls.
     SUMMARY by System:
     ==================
     
     itnnext4:
             Received  148594425 (2177 Files) in   24:09:34.61: 1708 cps
             Sent        5986874 ( 105 Files) in    0:56:16.32: 1773 cps
             Received  142607551 bytes more than sent.
             The system has been connected for     26:05:03.00 (3.8% of dead time)
                     of which   18:04:44.00 ( 69.3%) are payed by the local system
                          and    8:00:19.00 ( 30.7%) by this system.
             Spent     0:12:23.72 (  0.8%,  12934 Lit) in Peak Time
                       2:47:52.38 ( 11.1%, 108890 Lit) in Normal Time
                       4:07:32.35 ( 16.4%,  99680 Lit) in Evening Time
                      17:58:02.47 ( 71.6%, 349635 Lit) in Night Time
             Last connection: 13 Jul 1993 - 15:53:01
             There have been 168 calls (with an average of 2 Ok/day):
                                             139 OK ( 34 IN, 105 OUT,   7 STOPPED)
                                              22 FAILED

  ---------- Footnotes ----------

  (1)  In some cases it may even be smaller than the sum. This is
currently a bug, not a feature.


File: tua.info,  Node: Summary by System (table format),  Next: Since,  Prev: Summary by System,  Up: Output

Summary by System - Table Format
================================

  Substancially, this report summarizes some of the previous
information in a tabular form. Nothing new...
     +--------+--------------------------+--------------------------+----+
     |        |      R E C E I V E D     |          S E N T         |    |
     | SYSTEM | KiloBytes:  Time   :Files| KiloBytes:  Time   :Files| ATP|
     +--------+----------:---------:-----+----------:---------:-----+----|
     |angmar  |        16:  0:03:09:  106|       381:  0:29:07:  116| 209|
     |argo    |         4:  0:00:10:    4|       188:  0:03:38:   22| 858|
     |gear    |         9:  0:00:35:    8|      1826:  0:37:00:   88| 832|
     |ideahb  |         2:  0:00:03:    2|         1:  0:00:00:    2| 703|
     |itnsg1  |      5084:  1:46:14:  246|        22:  0:00:20:   90| 817|
     |lpds    |         1:  0:00:03:    2|       616:  0:12:20:   13| 848|
     |otello  |       132:  0:04:04:   48|        30:  0:00:33:   36| 600|
     |usixth  |         0:  0:00:00:    0|       587:  0:12:20:   50| 811|
     +--------+----------:---------:-----+----------:---------:-----+----|
     | TOTALS |      5248:  1:54:21:  416|      3651:  1:35:21:  417|####|
     +--------+----------:---------:-----+----------:---------:-----+----|


File: tua.info,  Node: Since,  Next: Last 12 months Activity,  Prev: Summary by System (table format),  Up: Output

Historical data - Since...
==========================

  This is the historical data maintained by TUA.  It looks like the
previous table, but it includes the history of the system,
incrementally since the last `history reset' operation.
     ...and since Fri Oct 11 01:26:02 1991
     
     +--------+--------------------------+--------------------------+----+
     |        |      R E C E I V E D     |           S E N T        |    |
     | SYSTEM | KiloBytes:  Time   :Files| KiloBytes:  Time   :Files| ATP|
     +--------+----------:---------:-----+----------:---------:-----+----|
     |angmar  |        75:  0:12:52:  396|      2146:  2:44:11:  679| 214|
     |argo    |        46:  0:02:21:   60|      2566:  0:50:48:  280| 838|
     |gear    |       596:  0:13:56:   29|     18279:  6:11:05:  735| 836|
     |ideahb  |      4937:  1:25:53:  259|     16974:  3:20:11:  141|1307|
     |itnsg1  |     58552: 20:00:30: 2063|       172:  0:02:53:  388| 832|
     |lpds    |         8:  0:00:37:   18|      3341:  1:37:02:  131| 585|
     |otello  |      1812:  1:02:23:  938|      1176:  0:23:33:  577| 593|
     |usixth  |         0:  0:00:00:    0|       587:  0:12:20:   50| 811|
     +--------+----------:---------:-----+----------:---------:-----+----|
     | TOTALS |     66025: 22:58:35: 3763|     45241: 15:22:06: 2981|####|
     +--------+----------:---------:-----+----------:---------:-----+----|


File: tua.info,  Node: Last 12 months Activity,  Next: Hourly Activity,  Prev: Since,  Up: Output

Last 12 months Activity
=======================

  This table shows the activity of the local machine during the last 12
months.  Only the transferred amounts are computed.

  The months are displayed in a manner so that the last column contains
the current one, so it is very readable (of course, it is a matter of
opinions!)
     Last 12 Months Activity
     =======================
     
     ------+---+---+---+---+---+---+---+---+-----+-----+-----+-----
     System|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep| Oct | Nov | Dic | Jan
     ------+---+---+---+---+---+---+---+---+-----+-----+-----+-----
     angmar|***|***|***|***|***|***|***|***| *** | 381K| 932K| 907K
     argo  |***|***|***|***|***|***|***|***| 193K| 486K|1552K| 380K
     gear  |***|***|***|***|***|***|***|***|2599K|3241K|6223K|6813K
     ideahb|***|***|***|***|***|***|***|***|9201K|6460K|5893K| 356K
     itnsg1|***|***|***|***|***|***|***|***|6852K|  16M|  15M|  20M
     lpds  |***|***|***|***|***|***|***|***| *** |1251 | 836K|2511K
     otello|***|***|***|***|***|***|***|***| 480K| 924K| 947K| 637K
     usixth|***|***|***|***|***|***|***|***| *** | *** | *** | 587K
     ------+---+---+---+---+---+---+---+---+-----+-----+-----+-----
     TOTALS|***|***|***|***|***|***|***|***|  19M|  28M|  32M|  32M
     ------+---+---+---+---+---+---+---+---+-----+-----+-----+-----


File: tua.info,  Node: Hourly Activity,  Prev: Last 12 months Activity,  Up: Output

Hourly Activity
===============

  NOTE: Taylor Uucp 1.04 needs a patch to print the name of the port
used for the connection in the `Stats' logfile. See *Note Taylor Uucp
Patch:: for details.

  These charts shows the uucp hourly load for each used communication
port.  Each hour is divided in 20 minutes slices.

  The final one is the sums of all the preceding, i.e. it displays the
uucp load of the machine.
     Hourly Activity (on a 20 minutes basis) on tty00
     ======================================================
     
     Max Value :     2217788 bytes
     Scale     : '#'= 221779 bytes
     
        #
        ##
        ##    #
        ##    #
        ##    #
        ##    #
        ##    #
     #  ##    #
     #  ###   #
     ## ###   #   # ###
     ========================================================================
     0  1  2  3  4  5  6  7  8  9  10 11 12 13 14 15 16 17 18 19 20 21 22 23


File: tua.info,  Node: History,  Next: TCL,  Prev: Output,  Up: Top

History
*******

  TUA maintains a database with the history of each system and of the
activity in each of the last 12 months activities.

  It is usually located in `.../tua.history' and it is actually an
ASCII file. It is up to you to update it or not, because probably most
of the time you will like to run TUA simply to have a notion of what is
going on.

  To make it working correctly, you have to run TUA with the option
`--update-history' just before you run uuclean. So probably you will
have to modify that script including in it a line like

     $ tua --update-history [whatever options you like] | mail lele

  before it cleans up the uucp logs.

  There is a commented header at the top of that file that explains its
content. There is no needs for you to view and/or modify it, since
everything is made by TUA, but I can understand your curiosity!.


File: tua.info,  Node: TCL,  Next: GNU General Public License,  Prev: History,  Up: Top

TCL Interface
*************

  "TCL" means "Tool Command Language", and it was designed by John
Ousterhout(1) to make it easier to add an embedded command language to
the programs that need this feature.

  This chapter talks about the relationship between TUA and TCL. You
need TCL version 6.1 or higher, and compile TUA with the option
`USE_TCL' in order to get these functionalities.

  Using this facility, you can configure TUA at runtime. Currently this
is just a different way to specify command line options (*note
Options::.), but adding others of them is very simple.

  TUA, at startup just before beginning to parse the input files, look
for a TCL script (see the content of the macro TUA_INIT_SCRIPT, defined
in `src/customize.h' for exact pathname. I set it to `TUA_init.tcl' by
default). If its name does not begin with a slash "/", it is considered
relative to the library directory, usually `/usr/local/lib'.

  TUA doesn't really need TCL, but I wanted to give it a try, to learn
what TCL can be useful for. I cannot really think of a good use for
TUA; for this reason, I do not plan to spend time on this
functionality. But if you have good examples of how (and why ;-) use
this feature, please let me know!

  However, I think that eventually a large site, with many more users
and links than mine, could use profitably this feature, first of all the
alias-related commands.

  The following sections explain what you can do, and how to add other
TCL command to TUA.

* Menu:

* More about TCL::              Where you can get more info
* Available TCL commands::      List of the available commands
* Adding new TCL commands::     How to add your own commands

  ---------- Footnotes ----------

  (1)  His e-mail address is ouster@sprite.berkeley.edu


File: tua.info,  Node: More about TCL,  Next: Available TCL commands,  Prev: TCL,  Up: TCL

More information about TCL
==========================

  You can obtain a copy of TCL by `ftp' from `sprite.berkeley.edu'. In
its distribution package, you can found several documents that provide
both an introduction to the language and a technical reference of it.
There is a dedicated and very trafficated newsgroup on `USENET':
comp.lang.tcl. There is also a mailing list that collects the people
interested with TCL.  Send a request to
`tcl-request@sprite.berkeley.edu' to join in.


File: tua.info,  Node: Available TCL commands,  Next: Adding new TCL commands,  Prev: More about TCL,  Up: TCL

Available TCL commands
======================

* Menu:

* Command List::                List of available TCL commands
* Examples::                    A sample Initialization Script


File: tua.info,  Node: Command List,  Next: Examples,  Prev: Available TCL commands,  Up: Available TCL commands

List of the TCL commands
------------------------

 - TCL Command: kill_user USERNAME
     The user USERNAME will never appear in the report.

 - TCL Command: user_alias USERNAME ALIAS
     Insert ALIAS as the new name for the user USERNAME.

 - TCL Command: glob_user_alias USERNAME ALIAS
     Insert ALIAS as the new name for the group of users whose name
     matches USERNAME. USERNAME may contains "meta-characters", with
     rules very similar to those supported by the `shell'.

 - TCL Command: kill_sys SYSNAME
     The system SYSNAME will never appear in the report.

 - TCL Command: sys_alias SYSNAME ALIAS
     Insert ALIAS as the new name for the system SYSNAME.

 - TCL Command: glob_sys_alias SYSNAME ALIAS
     Insert ALIAS as the new name for the group of systems whose name
     matches SYSNAME.

 - TCL Command: kill_port PORTNAME
     The communication port PORTNAME will never appear in the report.

 - TCL Command: port_alias USERNAME ALIAS
     Insert ALIAS as the new name for the communication port PORTNAME.

 - TCL Command: glob_port_alias USERNAME ALIAS
     Insert ALIAS as the new name for the group of ports whose name
     matches PORTNAME.

 - TCL Command: do_option OPTIONNAME
     Simulates the invocation of TUA with the option -OPTIONNAME, that
     needs to a long option name. Currently with this command you can
     specify just those option that doesn't need any further argument,
     because it doesn't do any parsing on the OPTIONNAME passed as the
     argument.

 - TCL Command: interactive
     Enter in interactive mode. TUA will prompt you for some TCL
     commands, and it will print the result on *stdout*, unless any
     redirection of the standard output was specified on the command
     line.

 - TCL Command: systems_report
     Prints out the Per System Report; *Note By System::.

 - TCL Command: users_report
     Prints out the Per User Report; *Note By User::.

 - TCL Command: daily_report
     Prints out the Daily Activity; *Note Daily::.

 - TCL Command: system_summary
     Prints out the Per System Summary; *Note Summary by System::.

 - TCL Command: system_summary_table
     Prints out the Tabled System Summary; *Note Summary by System
     (table format)::.


File: tua.info,  Node: Examples,  Prev: Command List,  Up: Available TCL commands

A sample Initialization Script
------------------------------

  What follows is just an example of what you can put in your
`TUA_init.tcl'.

     # This file shows which TUA specific commands are available
     #
     # do_option "long-option-name"
     #   This command is the same as putting "--long-option-name" on the
     #   command line.
     #   It is valid only for those options that do not require an argument
     #
     # port_alias "port-name" "its-alias"
     #   Like --port-alias port-name=its-alias
     #
     # glob_port_alias "port-name" "its-globbing-alias"
     #   Like --port-glob-alias port-name=its-globbing-alias
     #
     # kill_port "port-name"
     #   Like --kill-port port-name
     #
     # sys_alias "sys-name" "its-alias"
     #   Like --sys-alias sys-name=its-alias
     #
     # glob_sys_alias "sys-name" "its-globbing-alias"
     #   Like --sys-glob-alias sys-name=its-globbing-alias
     #
     # kill_sys "sys-name"
     #   Like --kill-sys sys-name
     #
     # user_alias "user-name" "its-alias"
     #   Like --user-alias user-name=its-alias
     #
     # glob_user_alias "user-name" "its-globbing-alias"
     #   Like --user-glob-alias user-name=its-globbing-alias
     #
     # kill_user "user-name"
     #   Like --kill-user user-name
     #
     
     # I do not wanna see my name in the report
     kill_user "lele"
     
     # I'd like to group all the UUCP login names into one meta-user
     glob_user_alias "uu*" "U_USERS"
     
     # I don't wanna see a separate entry for each of my machines
     sys_alias "calypso" "nautilus"
     sys_alias "titanic" "nautilus"
     sys_alias "doria" "nautilus"
     
     # Collect the various ports into one meta-port
     glob_port_alias "ttya?" "LOCAL LINKS"
     port_alias "tty00" "MODEM"
     
     # Always show me the command report
     do_option "command-lists"
     do_option "separate-command-report"


File: tua.info,  Node: Adding new TCL commands,  Prev: Available TCL commands,  Up: TCL

Adding new TCL commands
=======================

  Embedding a new TCL command into TUA is a simple operation, once you
know how TCL works, and this is not the scope of this manual.

  In few words, you must build a function that accepts four parameter
from the calling TCL command and performs some operation on them, and
returns a status to TCL, tipically TCL_OK when it ends correctly, or
TCL_ERROR to signal an incorrect situation.

  The called C function gets its arguments in the same way the function
`main' in a C program accepts arguments from the invoking environment,
i.e. with two variables, generally called ARGC and ARGV, where the
former carries the number of arguments passed, the latter is an array
of pointer to char containing, one per slot, the arguments. This is
possible since TCL supports just one data type: `string', that is a
null-terminated array of chars, like in C.

  Once you have this function, you must tell TCL its name and address,
invoking the TCL command `Tcl_CreateCommand'. Look at the table in
`tcl_supp.c', and add and appropriate entry for your function.

  You can see examples of this operation in `useralias.c',
`portalias.c', `sysalias.c', `tua.c'..., i.e. in every C source file
that create a new TCL command.

  Please refer to the TCL manual pages for further information about the
language and its interface with C.


File: tua.info,  Node: GNU General Public License,  Next: Bugs,  Prev: TCL,  Up: Top

GNU General Public License
**************************

                         Version 2, June 1991

     Copyright (C) 1989, 1991 Free Software Foundation, Inc.
     59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
     
     Everyone is permitted to copy and distribute verbatim copies
     of this license document, but changing it is not allowed.

Preamble
========

  The licenses for most software are designed to take away your freedom
to share and change it.  By contrast, the GNU General Public License is
intended to guarantee your freedom to share and change free
software--to make sure the software is free for all its users.  This
General Public License applies to most of the Free Software
Foundation's software and to any other program whose authors commit to
using it.  (Some other Free Software Foundation software is covered by
the GNU Library General Public License instead.)  You can apply it to
your programs, too.

  When we speak of free software, we are referring to freedom, not
price.  Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
this service if you wish), that you receive source code or can get it
if you want it, that you can change the software or use pieces of it in
new free programs; and that you know you can do these things.

  To protect your rights, we need to make restrictions that forbid
anyone to deny you these rights or to ask you to surrender the rights.
These restrictions translate to certain responsibilities for you if you
distribute copies of the software, or if you modify it.

  For example, if you distribute copies of such a program, whether
gratis or for a fee, you must give the recipients all the rights that
you have.  You must make sure that they, too, receive or can get the
source code.  And you must show them these terms so they know their
rights.

  We protect your rights with two steps: (1) copyright the software, and
(2) offer you this license which gives you legal permission to copy,
distribute and/or modify the software.

  Also, for each author's protection and ours, we want to make certain
that everyone understands that there is no warranty for this free
software.  If the software is modified by someone else and passed on, we
want its recipients to know that what they have is not the original, so
that any problems introduced by others will not reflect on the original
authors' reputations.

  Finally, any free program is threatened constantly by software
patents.  We wish to avoid the danger that redistributors of a free
program will individually obtain patent licenses, in effect making the
program proprietary.  To prevent this, we have made it clear that any
patent must be licensed for everyone's free use or not licensed at all.

  The precise terms and conditions for copying, distribution and
modification follow.

    TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

  1. This License applies to any program or other work which contains a
     notice placed by the copyright holder saying it may be distributed
     under the terms of this General Public License.  The "Program",
     below, refers to any such program or work, and a "work based on
     the Program" means either the Program or any derivative work under
     copyright law: that is to say, a work containing the Program or a
     portion of it, either verbatim or with modifications and/or
     translated into another language.  (Hereinafter, translation is
     included without limitation in the term "modification".)  Each
     licensee is addressed as "you".

     Activities other than copying, distribution and modification are
     not covered by this License; they are outside its scope.  The act
     of running the Program is not restricted, and the output from the
     Program is covered only if its contents constitute a work based on
     the Program (independent of having been made by running the
     Program).  Whether that is true depends on what the Program does.

  2. You may copy and distribute verbatim copies of the Program's
     source code as you receive it, in any medium, provided that you
     conspicuously and appropriately publish on each copy an appropriate
     copyright notice and disclaimer of warranty; keep intact all the
     notices that refer to this License and to the absence of any
     warranty; and give any other recipients of the Program a copy of
     this License along with the Program.

     You may charge a fee for the physical act of transferring a copy,
     and you may at your option offer warranty protection in exchange
     for a fee.

  3. You may modify your copy or copies of the Program or any portion
     of it, thus forming a work based on the Program, and copy and
     distribute such modifications or work under the terms of Section 1
     above, provided that you also meet all of these conditions:

       a. You must cause the modified files to carry prominent notices
          stating that you changed the files and the date of any change.

       b. You must cause any work that you distribute or publish, that
          in whole or in part contains or is derived from the Program
          or any part thereof, to be licensed as a whole at no charge
          to all third parties under the terms of this License.

       c. If the modified program normally reads commands interactively
          when run, you must cause it, when started running for such
          interactive use in the most ordinary way, to print or display
          an announcement including an appropriate copyright notice and
          a notice that there is no warranty (or else, saying that you
          provide a warranty) and that users may redistribute the
          program under these conditions, and telling the user how to
          view a copy of this License.  (Exception: if the Program
          itself is interactive but does not normally print such an
          announcement, your work based on the Program is not required
          to print an announcement.)

     These requirements apply to the modified work as a whole.  If
     identifiable sections of that work are not derived from the
     Program, and can be reasonably considered independent and separate
     works in themselves, then this License, and its terms, do not
     apply to those sections when you distribute them as separate
     works.  But when you distribute the same sections as part of a
     whole which is a work based on the Program, the distribution of
     the whole must be on the terms of this License, whose permissions
     for other licensees extend to the entire whole, and thus to each
     and every part regardless of who wrote it.

     Thus, it is not the intent of this section to claim rights or
     contest your rights to work written entirely by you; rather, the
     intent is to exercise the right to control the distribution of
     derivative or collective works based on the Program.

     In addition, mere aggregation of another work not based on the
     Program with the Program (or with a work based on the Program) on
     a volume of a storage or distribution medium does not bring the
     other work under the scope of this License.

  4. You may copy and distribute the Program (or a work based on it,
     under Section 2) in object code or executable form under the terms
     of Sections 1 and 2 above provided that you also do one of the
     following:

       a. Accompany it with the complete corresponding machine-readable
          source code, which must be distributed under the terms of
          Sections 1 and 2 above on a medium customarily used for
          software interchange; or,

       b. Accompany it with a written offer, valid for at least three
          years, to give any third party, for a charge no more than your
          cost of physically performing source distribution, a complete
          machine-readable copy of the corresponding source code, to be
          distributed under the terms of Sections 1 and 2 above on a
          medium customarily used for software interchange; or,

       c. Accompany it with the information you received as to the offer
          to distribute corresponding source code.  (This alternative is
          allowed only for noncommercial distribution and only if you
          received the program in object code or executable form with
          such an offer, in accord with Subsection b above.)

     The source code for a work means the preferred form of the work for
     making modifications to it.  For an executable work, complete
     source code means all the source code for all modules it contains,
     plus any associated interface definition files, plus the scripts
     used to control compilation and installation of the executable.
     However, as a special exception, the source code distributed need
     not include anything that is normally distributed (in either
     source or binary form) with the major components (compiler,
     kernel, and so on) of the operating system on which the executable
     runs, unless that component itself accompanies the executable.

     If distribution of executable or object code is made by offering
     access to copy from a designated place, then offering equivalent
     access to copy the source code from the same place counts as
     distribution of the source code, even though third parties are not
     compelled to copy the source along with the object code.

  5. You may not copy, modify, sublicense, or distribute the Program
     except as expressly provided under this License.  Any attempt
     otherwise to copy, modify, sublicense or distribute the Program is
     void, and will automatically terminate your rights under this
     License.  However, parties who have received copies, or rights,
     from you under this License will not have their licenses
     terminated so long as such parties remain in full compliance.

  6. You are not required to accept this License, since you have not
     signed it.  However, nothing else grants you permission to modify
     or distribute the Program or its derivative works.  These actions
     are prohibited by law if you do not accept this License.
     Therefore, by modifying or distributing the Program (or any work
     based on the Program), you indicate your acceptance of this
     License to do so, and all its terms and conditions for copying,
     distributing or modifying the Program or works based on it.

  7. Each time you redistribute the Program (or any work based on the
     Program), the recipient automatically receives a license from the
     original licensor to copy, distribute or modify the Program
     subject to these terms and conditions.  You may not impose any
     further restrictions on the recipients' exercise of the rights
     granted herein.  You are not responsible for enforcing compliance
     by third parties to this License.

  8. If, as a consequence of a court judgment or allegation of patent
     infringement or for any other reason (not limited to patent
     issues), conditions are imposed on you (whether by court order,
     agreement or otherwise) that contradict the conditions of this
     License, they do not excuse you from the conditions of this
     License.  If you cannot distribute so as to satisfy simultaneously
     your obligations under this License and any other pertinent
     obligations, then as a consequence you may not distribute the
     Program at all.  For example, if a patent license would not permit
     royalty-free redistribution of the Program by all those who
     receive copies directly or indirectly through you, then the only
     way you could satisfy both it and this License would be to refrain
     entirely from distribution of the Program.

     If any portion of this section is held invalid or unenforceable
     under any particular circumstance, the balance of the section is
     intended to apply and the section as a whole is intended to apply
     in other circumstances.

     It is not the purpose of this section to induce you to infringe any
     patents or other property right claims or to contest validity of
     any such claims; this section has the sole purpose of protecting
     the integrity of the free software distribution system, which is
     implemented by public license practices.  Many people have made
     generous contributions to the wide range of software distributed
     through that system in reliance on consistent application of that
     system; it is up to the author/donor to decide if he or she is
     willing to distribute software through any other system and a
     licensee cannot impose that choice.

     This section is intended to make thoroughly clear what is believed
     to be a consequence of the rest of this License.

  9. If the distribution and/or use of the Program is restricted in
     certain countries either by patents or by copyrighted interfaces,
     the original copyright holder who places the Program under this
     License may add an explicit geographical distribution limitation
     excluding those countries, so that distribution is permitted only
     in or among countries not thus excluded.  In such case, this
     License incorporates the limitation as if written in the body of
     this License.

 10. The Free Software Foundation may publish revised and/or new
     versions of the General Public License from time to time.  Such
     new versions will be similar in spirit to the present version, but
     may differ in detail to address new problems or concerns.

     Each version is given a distinguishing version number.  If the
     Program specifies a version number of this License which applies
     to it and "any later version", you have the option of following
     the terms and conditions either of that version or of any later
     version published by the Free Software Foundation.  If the Program
     does not specify a version number of this License, you may choose
     any version ever published by the Free Software Foundation.

 11. If you wish to incorporate parts of the Program into other free
     programs whose distribution conditions are different, write to the
     author to ask for permission.  For software which is copyrighted
     by the Free Software Foundation, write to the Free Software
     Foundation; we sometimes make exceptions for this.  Our decision
     will be guided by the two goals of preserving the free status of
     all derivatives of our free software and of promoting the sharing
     and reuse of software generally.

                                NO WARRANTY

 12. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO
     WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE
     LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
     HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT
     WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT
     NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
     FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS TO THE
     QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
     PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
     SERVICING, REPAIR OR CORRECTION.

 13. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
     WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
     MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE
     LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
     INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
     INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
     DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU
     OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY
     OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
     ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

                      END OF TERMS AND CONDITIONS

How to Apply These Terms to Your New Programs
=============================================

  If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these
terms.

  To do so, attach the following notices to the program.  It is safest
to attach them to the start of each source file to most effectively
convey the exclusion of warranty; and each file should have at least
the "copyright" line and a pointer to where the full notice is found.

     ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES.
     Copyright (C) 19YY  NAME OF AUTHOR
     
     This program is free software; you can redistribute it and/or modify
     it under the terms of the GNU General Public License as published by
     the Free Software Foundation; either version 2 of the License, or
     (at your option) any later version.
     
     This program is distributed in the hope that it will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
     GNU General Public License for more details.
     
     You should have received a copy of the GNU General Public License
     along with this program; if not, write to the Free Software
     Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

  Also add information on how to contact you by electronic and paper
mail.

  If the program is interactive, make it output a short notice like this
when it starts in an interactive mode:

     Gnomovision version 69, Copyright (C) 19YY NAME OF AUTHOR
     Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
     This is free software, and you are welcome to redistribute it
     under certain conditions; type `show c' for details.

  The hypothetical commands `show w' and `show c' should show the
appropriate parts of the General Public License.  Of course, the
commands you use may be called something other than `show w' and `show
c'; they could even be mouse-clicks or menu items--whatever suits your
program.

  You should also get your employer (if you work as a programmer) or
your school, if any, to sign a "copyright disclaimer" for the program,
if necessary.  Here is a sample; alter the names:

     Yoyodyne, Inc., hereby disclaims all copyright interest in the program
     `Gnomovision' (which makes passes at compilers) written by James Hacker.
     
     SIGNATURE OF TY COON, 1 April 1989
     Ty Coon, President of Vice

  This General Public License does not permit incorporating your
program into proprietary programs.  If your program is a subroutine
library, you may consider it more useful to permit linking proprietary
applications with the library.  If this is what you want to do, use the
GNU Library General Public License instead of this License.


File: tua.info,  Node: Bugs,  Next: Author,  Prev: GNU General Public License,  Up: Top

Bugs
****

  Since `BNU' Uucp doesn't put a complete datestamp in its logs, but
omits the year, it may be possible that TUA fails to compute the various
times in the first analysis of the year.  This is in my opinion its
major weakness. For this silliness, TUA cannot correctly handle logs
that cover several years. There is little that I can do to correct the
situation; I tried to adjust the year when the to-be-parsed date refers
obviously to the previous year, but this is just a work\-around.... If
this is serious for you, I suggest switching to Taylor Uucp.

  `BNU' logs get garbaged sometime, for a reason that is unknown to me.
This may cause TUA to fails. This is the second weakness: eventually
I'll try to implement a better parser in a future release. It should
recognise this situation and print out a log, indicating where exacly
the error occured. If this happens, you have to find out the garbage
inside your logs, and eliminate it. If compiled with the "-DDEBUG"
flag, TUA may help you a little givinig it the flag "-verbose".

  There is a limit: if your system spent more than 9999 hours linked
with someone (or the sum exceed that value), the reports will be
garbaged...  Ohhh well...

* Menu:

* Bugs Report::                 Bugs Report


File: tua.info,  Node: Bugs Report,  Prev: Bugs,  Up: Bugs

Bugs Report
===========

  If you have any problem building or using TUA, please do not hesitate
to contact me as lele@eclipse.it.

  Give it a try, and feel free to modify it. The only thing I ask you is
to send me all your enhancements, or bug fixes, so I can include them in
some future releases.  PLEASE if you can resist, and I know you can, do
not post or spread yourself patches without e-mailing me a copy.  I do
not receive all USENET groups, and it'd be difficult for me to collect
them.

  Include in your message (suggestions, bug reports, patches,
flames...), as usual, the machine and OS type you are using, so I can
eventually customize TUA for your environment.


File: tua.info,  Node: Author,  Next: Acknowledgment,  Prev: Bugs,  Up: Top

Author
******

  Lele Gaifax, Rovereto (TN) - Italy lele@eclipse.it

  I developed it because the other analyzers I looked at didn't satisfy
my needs.  So I picked up their best features, and put all that stuff
together.

  I had a lot of fun doing it, and I learnt even more. I used `nroff'
for the first manual page, and then `Texinfo' for this one: this forced
me to compile TeX on my old machine, `GCC' since the native compiler
wasn't able to do it, and to find a `dvilj' for my silly LJ compatible
laser printer; `Bison' for the first approach to parse the date inside
the `uucico' logs; `TCL' as a configuration tool; `GDB' to debug the
binary tree management...

  And yes, I know that supporting `TCL', `ReadLine', `SoftChip Btree'
is of no use for the larger part of you out there, but this is an
interesting way to learn from other's sources. With a few changes to
`src/customize.h' and maybe `Makefile' you can exclude these
experiments.

  I took care of portability and correctness (I hope ;-). I wrote the
preceeding versions on PC clones, running derivatives of Un*x System V.
Then I grew up, bought a wonderful NeXTStation, where I have everything
I need: `GNU Emacs', `GCC', `GDB', TeX and `dvips' are there since the
Big Bang. I added `Taylor Uucp', restarted the development there and,
at last, TUA run on a BSD system (at least mine!).

  BTW, "TUA" in italian means "yours": "questa cosa e' TUA" can be
translated with "this stuff is yours".  So even in the name this package
reflects the spirit which inspired me in writing it. I chose to cover
TUA with the GNU General Public License right to protect this intention.


File: tua.info,  Node: Acknowledgment,  Next: Disclaimer,  Prev: Author,  Up: Top

Acknowledgement
***************

  I want to thank especially Marco Lorenzini (marlor@gear.sublink.org)
for his help in debugging the previous releases of TUA on the SCO Unix
architecture, and for his suggestions on the layout of the reports.

  To Paolo Ventafridda (venta@i2ack.sublink.org) for his support and
interest, and several other people that encouraged me to add more and
more functionality, or that let me scan their huge logs.

  John Plate (plate@infotek.dk) convinced me to complete the Taylor Uucp
support, and also helped me with suggestion and feedback.

  Michel Cerdini (cerdini@zen.gatelink.fr.net) contributed several nice
ideas, like cost support in the PCD file.

  Eberhard W. Lisse (el@lisse.na) tested TUA on Linux...

  ...And many others, who sent me logs, ideas, flowers...

  Thanks also to all the people that, with their PD or GPL software,
helped me indirectly with ideas or examples.


File: tua.info,  Node: Disclaimer,  Next: Compilation and Installation,  Prev: Acknowledgment,  Up: Top

Disclaimer
**********

  I reject any responsibility about this program. It is simple and safe;
unless you explicity give the option to update the history database TUA
doesn't write anything on your disks. I did not try it under all the
possible conditions and environments, so if it causes you some trouble,
I'll be sad for a while, but that's it.

  However, I will try to correct any bug you will tell me.

  And *please*, forgive my poor english, but I put my soul in it...


File: tua.info,  Node: Compilation and Installation,  Next: Files,  Prev: Disclaimer,  Up: Top

How to compile and install TUA
******************************

  To compile TUA, you must first of all you configure it for your
system. This is done semiautomatically by running `configure', a shell
script that attempts to guess correct values for various
system-dependent variables used during compilation. More info about
`configure' and its usage can be found in the file `INSTALL'.

  `configure' will check your machine and operating system to extract
some information, and will update `Makefile' and `config.h'.

  When this is done, give a look to the `Makefile' and edit it to
satisfy your needs, then check and edit `src/customize.h' following its
directives. This file contains settings that will alter the behaviour
of the program: you can decide what kind of `UUCP' logs TUA will read
(Taylor Uucp or HDB Uucp, or both), where the various files TUA
accesses live, and so on.

  A simpler way to change some of these settings is by giving some
command-line options to the `configure' procedure:

`--with-glob'
`--without-glob'
     Enable / Disable the support for the "glob" pattern matching:
     enabling it will let you use a notation similar to that used by
     `bash' to indicate a class of users, or systems. The "glob"
     library is included in the package.

`--with-readline'
`--without-readline'
     This option cause the TCL support routines to use the GNU Readline
     library for the interaction with the user, instead of a simpler
     (and smaller) `fgets()'. You can get the GNU ReadLine library from
     your nearest GNU/FSF archive.

`--with-tcl'
`--without-tcl'
     Long time ago I was learning `TCL', and I interfaced `tua' with
     it. If you know what `TCL' is, you may be interested. If not,
     surely you don't ;-). This needs `TCL' already installed on your
     machine.

`--with-softchip'
`--without-softchip'
     The `SoftChip Btree Library' is a freely available balanced trees
     implementation. `tua' internally uses a simple binary trees
     library, included in the `tua' package, that is good enough for
     me. As for `TCL', I added the support for this library years ago
     (don't ask: while I was trying the library... I'm a very curious
     boy ;-); I did not tried it extensively, and I don't know/care if
     using balanced trees instead of the simpler binary makes TUA
     fly... However, if your machine have thousends `UUCP' neighbours...

`--enable-taylor'
`--disable-taylor'
     Include or exclude the compilation and the linkage of the `Taylor
     Uucp' specific code. The support for it is included by default,
     but if you are using another UUCP implementation you can reduce (a
     little) the size of the executable while reducing (a lot) TUA
     capabilities...

`--enable-hdb'
`--disable-hdb'
     TUA was born to parse `HDB Uucp' logs: at that time I was learning
     to program in "C" on UNIX, working on '286 running Xenix... Now I
     usually program in "Objective C" on NeXTSTEP, working on a
     NeXTStation, and with `Taylor Uucp'. The support for HDB is there,
     but is disable by default. If your are not using Taylor Uucp, or
     configured it in HDB mode, give this option to configure.

  TUA 4.1 has been internationalized by using the `GNU gettext'
package, and `configure' accepts two related options:

`--with-gnu-gettext'
     Bypass the system `catgets' or `gettext' to use GNU `gettext'.

`--disable-nls'
     Totally disable translation of messages.

  See `ABOUT-NLS' in the distribuition package for other details.

  Last run the compilation executing `make'.


File: tua.info,  Node: Files,  Next: Taylor Uucp Patch,  Prev: Compilation and Installation,  Up: Top

Files
*****

  Here is a list of all the files involved in the analisys. Their exact
location is defined in `src/customize.h'.

* Menu:

* HDB Uucp Files::              Files used in HDB mode
* Taylor Uucp Files::           Files used in Taylor mode
* PCD File::                    Phone Category Description
* TCL Files::
* NLS Files::                   National Language Support files


File: tua.info,  Node: HDB Uucp Files,  Next: Taylor Uucp Files,  Prev: Files,  Up: Files

HDB Uucp Files
==============

  Files TUA reads when in HDB mode. The default prefix directory is
`/usr/spool/uucp'.

`.../.Log/uucico/*'
     Directory that contains uucico's logs

`.../.Log/uucp/*'
     Directory that contains uucp's logs

`.../.Log/uux/*'
     Directory that contains uux's logs

`.../.Log/uuxqt/*'
     Directory that contains uuxqt's logs

`.../.Admin/xferstat'
     File containing transfer stats

`.../.Admin/tua.history'
     This file contains the history maintened by TUA.

`.../TUA_init.tcl'
     This file is usually located in the library directory
     `/usr/local/lib' and if exists it gets loaded at startup by TUA.
     It may contain a TCL script used for customize some behavior of
     the program.


File: tua.info,  Node: Taylor Uucp Files,  Next: PCD File,  Prev: HDB Uucp Files,  Up: Files

Taylor Uucp Files
=================

  Files TUA reads when in Taylor mode. The default prefix directory is
`/usr/local/spool/uucp'.

`.../Log'
     Main Taylor Uucp log file.

`.../Stats'
     Transfers statistics.

`.../tua.history'
     This file contains the history maintened by TUA.


File: tua.info,  Node: PCD File,  Next: TCL Files,  Prev: Taylor Uucp Files,  Up: Files

PCD File: Phone Categories configuration
========================================

  In order to subdivide the time your system spends talking at the phone
in each of cost rates used in your country, TUA needs a table of how
your telephone company rates your calls at some time in the day. To
make it simpler than in previous versions, now TUA is able to read this
information from an external file, using the Phone Categories
Definition Language. In this language, spaces, tabs, new lines are
ignored, as well as the comments, introduced by a pound sign # thru the
following end of line.

  This file contains, at its beginning, the default name of the country,
likely the name of your country. The statement that do this is
"`default = "'YOUR_COUNTRY_NAME`"'".

  Each country is defined in a way similar to the following example:


     # ITALY - Pizza & Spaghetti country
     country "italy" = {
       currency = "Lit";
       decimals = 0;                 # Do not print fractions of Lits
     
       # COSTS:
       # - assuming that 1 unit costs 127 Lit...
       # - timings are for distances > 120km
     
       name PEAK = "Orario di Punta";	# 8:30am to 1pm
       cost PEAK = 127,127/13.1;		# 1 unit for the call, then one
                                             # every 13.1sec
       name NORMAL = "Orario Diurno";	# 8am to 8:30am, 1pm to 6:30pm
       cost NORMAL = 127,127/20;
       name EVENING = "Orario Serale";	# 6:30pm to 10pm
       cost EVENING = 127,127/32;
       name NIGHT = "Orario Notturno";	# 10pm to 8 am
       cost NIGHT = 127,127/40;
     
       monday-friday = {
         rate PEAK = 8:31-13:00;
         rate NORMAL = 8:01-8:30, 13:01-18:30;
         rate EVENING = 18:31-22:00;
         rate NIGHT = 22:01-08:00;    # sc for 22:01-24:00, 0:01-8:00
       };
       saturday = {
         rate NORMAL = 08:01-13:00;
         rate EVENING = 13:01-22:00;
         rate NIGHT = 22:01-08:00;
       };
       sunday = {
         rate EVENING = 8:01-22:00;
         rate NIGHT = 22:01-08:00;
       };
     }

  You write the names of your timebands, and then, day by day, specify
the bands themself. You can abbreviate the names of the days to the
first three letters.

  A timeband is defined as a list of comma separated ranges in the form
of `H1:M1-H2:M2', like "18:00-22:00". You can use the form
"22:00-08:00" with the same meaning of the longer "22:00-24:00,
0:00-08:00". The format "HH.MM", with a point as separator instead of
the colon, is accepted as well.

  To set the country's currency name use the statement
     currency = "Lit";

  You may specify with how many decimal digits TUA will print money
amounts:
     decimals = 4;

  It is possible to assign a cost to each timeband with a statement like
     cost HIGH = 123.2/60.3;
  that means you will pay 123.2 units of CURRENCY every 60.3 seconds.
TUA, and UUCP as well, knows nothing about different kind of calls,
i.e. long-distance vs. intercontinental etc. For this reason, whatever
cost you will set, the final amount will be an approximation, unless all
your calls are of a single type.

  If your telephone company applies a fixed cost for the call, thus
ignoring the time it takes, use the simpler form

     cost LOW = 127;
  to mean that in the "LOW" band each call costs *127*. More probably,
the cost will be a mix of the two: a fixed amount for the call, then
another quid calculated on the time the call takes to terminate. In
this case the form to use is
     cost MEDIUM = 254,127/66;
  to specify a fixed cost of 254, applied to all calls, plus a cost of
127 per unit of time of 66 seconds (or less: a 10-secs-long call costs
one unit).

  This file is located inside your local library directory, usually
`/usr/local/lib', and named `TUA.pcd'.


File: tua.info,  Node: TCL Files,  Next: NLS Files,  Prev: PCD File,  Up: Files

TCL Initialization file
=======================

  When TUA is configured to support TCL, you may create a file called
`TUA_init.tcl' in the library directory (usually `/usr/local/lib').
This file, if exists, gets loaded at startup by TUA, and may contain a
TCL script used for customize some behavior of the program.

  *Note Examples::.


File: tua.info,  Node: NLS Files,  Prev: TCL Files,  Up: Files

National Language Support files
===============================

  Files TUA accesses when NLS is needed.

`.../LANG/LC_MESSAGES/TUA.mo'
     Where LANG is the selected national language, contains the
     translations of all the messages TUA will put in the generated
     reports.


File: tua.info,  Node: Taylor Uucp Patch,  Next: Concept Index,  Prev: Files,  Up: Top

Taylor Uucp Patch
*****************

  If you are using Taylor Uucp version 1.04 and want the Hourly Activity
Chart, you have to patch its source, adding the port name in each line
of the `Stats' log file.

  TUA automatically recognize patched logs, and will produce the chart
without any other intervention by you.

  Here below is the patch you may want apply. To simplify your work, I
included it in `src/taylor/TaylorLogsPatch.diff' in the TUA package. To
install it, go to the Taylor Uucp source directory and execute the
command "`patch < .../taylor/TaylorLogsPatch.diff'", where the dots
represent the name of the directory where you keep TUA sources.

  Taylor Uucp 1.05 and greater do not need this patch.

     *** log-org.c   Sun Sep 26 11:52:38 1993
     --- log.c       Sun Sep 26 11:54:29 1993
     ***************
     *** 602,612 ****
     
       #if HAVE_TAYLOR_LOGGING
         fprintf (eLstats,
     !          "%s %s (%s) %s%s %ld bytes in %ld.%03ld seconds (%ld bytes/sec)\n",
                zuser, zsystem, zldate_and_time (),
                fsucceeded ? "" : "failed after ",
                fsent ? "sent" : "received",
     !          cbytes, csecs, cmicros / 1000, cbps);
       #endif /* HAVE_TAYLOR_LOGGING */
       #if HAVE_V2_LOGGING
         fprintf (eLstats,
     --- 602,613 ----
     
       #if HAVE_TAYLOR_LOGGING
         fprintf (eLstats,
     !          "%s %s (%s) %s%s %ld bytes in %ld.%03ld seconds (%ld bytes/sec) on port %s\n",
                zuser, zsystem, zldate_and_time (),
                fsucceeded ? "" : "failed after ",
                fsent ? "sent" : "received",
     !          cbytes, csecs, cmicros / 1000, cbps,
     !          zLdevice == NULL ? "unknown" : zLdevice);
       #endif /* HAVE_TAYLOR_LOGGING */
       #if HAVE_V2_LOGGING
         fprintf (eLstats,


File: tua.info,  Node: Concept Index,  Prev: Taylor Uucp Patch,  Up: Top

Concept and Function Index
**************************

* Menu:

* TUA_init.tcl example:                 Examples.
* Acknowledgement:                      Acknowledgment.
* Author:                               Author.
* Available TCL commands:               Command List.
* Bug Report:                           Bugs Report.
* Bugs:                                 Bugs.
* Command line options:                 Options.
* Communication port Activity:          Hourly Activity.
* Compilation:                          Compilation and Installation.
* Conditions for copying TUA:           Copying.
* Configuration:                        Compilation and Installation.
* Configuring TUA with TCL:             TCL.
* Copying conditions:                   Copying.
* country configuration:                PCD File.
* Customization:                        Compilation and Installation.
* Daily Activity:                       Daily.
* daily_report:                         Command List.
* do_option:                            Command List.
* Getting TCL:                          More about TCL.
* glob_port_alias:                      Command List.
* glob_sys_alias:                       Command List.
* glob_user_alias:                      Command List.
* Historical data <1>:                  History.
* Historical data:                      Since.
* History:                              History.
* Hourly Activity:                      Hourly Activity.
* How to send a Bug Report:             Bugs Report.
* Installation:                         Compilation and Installation.
* interactive:                          Command List.
* Internationalization:                 NLS Files.
* Invocation:                           Options.
* kill_port:                            Command List.
* kill_sys:                             Command List.
* kill_user:                            Command List.
* Known deficiencies:                   Bugs.
* Last 12 months Activity:              Last 12 months Activity.
* New TCL Commands:                     Adding new TCL commands.
* Options:                              Options.
* Output:                               Output.
* Overview of TUA:                      Overview.
* Patch for Taylor Uucp:                Taylor Uucp Patch.
* PCD File:                             PCD File.
* Per System Summary:                   Summary by System.
* Per System Tabled Summary:            Summary by System (table format).
* Phone Categories:                     PCD File.
* port_alias:                           Command List.
* Reporting a Bug:                      Bugs Report.
* Runtime configuration with TCL:       TCL.
* Since...:                             Since.
* Summary by System (Table format):     Summary by System (table format).
* Summary by System (Verbose):          Summary by System.
* Summary of the last year Activity:    Last 12 months Activity.
* sys_alias:                            Command List.
* system_summary:                       Command List.
* system_summary_table:                 Command List.
* systems_report:                       Command List.
* TCL:                                  TCL Files.
* TCL Mailing List:                     More about TCL.
* Thanks:                               Acknowledgment.
* user_alias:                           Command List.
* users_report:                         Command List.
* What TUA is:                          Overview.
* Who wrote it and why:                 Author.



Tag Table:
Node: Top1012
Node: Copying3295
Node: Overview3939
Node: Options5889
Node: Output13737
Node: By System14737
Node: By User15814
Node: Daily16304
Node: Summary by System16977
Node: Summary by System (table format)19738
Node: Since21150
Node: Last 12 months Activity22681
Node: Hourly Activity24125
Node: History25133
Node: TCL26069
Node: More about TCL27934
Node: Available TCL commands28516
Node: Command List28813
Node: Examples31163
Node: Adding new TCL commands33160
Node: GNU General Public License34619
Node: Bugs53792
Node: Bugs Report55145
Node: Author55886
Node: Acknowledgment57607
Node: Disclaimer58612
Node: Compilation and Installation59198
Node: Files62878
Node: HDB Uucp Files63371
Node: Taylor Uucp Files64202
Node: PCD File64588
Node: TCL Files68451
Node: NLS Files68874
Node: Taylor Uucp Patch69224
Node: Concept Index71145

End Tag Table
