\input texinfo          @c -*- texinfo -*-
@c %**start of header
@setfilename tua.info
@settitle @sc{tua} - The Uucp Analyzer
@syncodeindex fn cp
@paragraphindent 2
@c %**end of header

@ifinfo
This file documents @sc{tua}, The Uucp Analyzer, a tool that analyze the BNU
Uucp connections of your machine.

Copyright @copyright{} 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.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
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.
@end ifinfo

@setchapternewpage on
@titlepage
@title TUA
@subtitle The Uucp Analyzer
@subtitle Edition 1.02, for @sc{tua} Version 4.3
@subtitle February 1996

@author by Lele Gaifax

@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1991,96 Emanuele Gaifas

@sp 2
This is the First Edition of the @sc{tua} documentation in Texinfo,
and covers @sc{tua} version 4.2.
@sp 2

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.
@end titlepage

@ifinfo
@node top, Copying, (dir), (dir)
@top @sc{tua} - The Uucp Analyzer

@sc{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.
@end ifinfo

@menu
* Copying::                     @sc{tua} Copying Conditions
* Overview::                    Overview of @sc{tua}
* Options::                     Descriptions of all the Options
* Output::                      Detailed explanation of what you will see
* History::                     How @sc{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 @sc{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
@end menu

@node Copying, Overview, top, top
@comment  node-name,  next,  previous,  up
@unnumbered @sc{tua} Copying Conditions
@cindex Copying conditions
@cindex Conditions for copying @sc{tua}

@sc{tua} is @dfn{free}; this means that everyone is free to use it and
free to redistribute it on a free basis. It is @sc{not} in the public
domain; @sc{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.@refill

@xref{GNU General Public License} for more details on the distribution
policy.

@node Overview, Options, Copying, top
@comment  node-name,  next,  previous,  up
@chapter Overview of @sc{tua}
@cindex Overview of @sc{tua}
@cindex What @sc{tua} is

@sc{tua} is @sc{not} simply a ``Yet Another Uucp Analyzer'': its purpose
is to produce a readable and complete analysis of the @cite{UUCP}
connections. @sc{tua} is able to extract a report from both
@cite{HoneyDanBer UUCP}@footnote{Also known as @cite{BNU Uucp} or
@cite{HDB Uucp}} and @cite{Taylor Uucp}. @refill

The report shows, from several points of view, what exactly is going on
at your site. For a detailed description of the output, see
@ref{Output}.

This is done by reading the various logs UUCP
produces@footnote{@file{@dots{}/.Admin/xferstats} and the
@file{@dots{}/.Log/} directory hierarchy for HDB Uucp,
@file{@dots{}/Stats} and @file{@dots{}/Log} for Taylor Uucp} , as well
as @file{@dots{}/tua.history}, that is where @sc{tua} records the
historical data. The exact pathnames of these files are defined in the
customization file @file{src/customize.h}.@refill

@sc{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 @ref{Options}.

@sc{tua} 4.0 is backward compatible with the previous released version,
@sc{tua} 3.3, at both the command line option level and the format of
the @file{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 @file{src/customize.h}).@refill

@sc{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 @cite{GNU gettext} package. Actually, only
@emph{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 @file{.po} files in
the distribution, although surely I cannot check their exactness.

@node Options, Output, Overview, top
@comment  node-name,  next,  previous,  up
@chapter Command line options
@cindex Command line options
@cindex Options
@cindex Invocation

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 @cite{GNU getopt} package description.

@table @code
@item -a @var{name}
@itemx --country @var{name}
After option processing, @sc{tua} reads the Phone Categories Definition
file (@pxref{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), @sc{tua} will print a message on the
standard error stating that it will not print the phone costs in the
report.@refill

@item --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.

@item --list-countries
Print a list of the countries present in the PCD file, and exit.

@item -S
@itemx --no-system-rep
Do not print the "per System report" (@pxref{By System}). The
default is to print it out.@refill

@item -U
@itemx --no-user-rep
Do not print the "per User report" (@pxref{By User}). The
default is to print it out.@refill

@item -D
@itemx --no-daily-rep
Do not print the "Daily report" (@pxref{Daily}). The default is
to print it out.

@item -C
@itemx --command-lists
Show also the command lists. It is off by default because @sc{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! @refill

@item -O @var{system}
@itemx --only-system @var{system}
Consider just system @var{system} in the reports. You can specify more
than one of this option, so you can have @sc{tua} consider just those
systems. @refill

@item -m
@itemx --no-monthly-act
Do not output the last 12 months activity summary.

@item -h
@itemx --no-history
Do not output the history at the end of the reports.

@item -c
@itemx --separate-command-report
Separate command lists from the other data. So there will be two tables
with the header "By System" (@pxref{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
@code{--command-lists}. @refill

@item -k @var{system}
@itemx --kill-system @var{system}
Eliminate each reference to @var{system} from the reports. Neither the
transfer table nor the @var{system} command list will be printed.

@item -K @var{user}
@itemx --kill-user @var{user}
Like @code{--kill-system}, but it applies to the user called @var{user}.

@item -H
@itemx --update-history
Update the @file{history} database (@pxref{History}) with the new
values. Warning: since this option will cause @sc{tua} to write the
historical data on your disk, you must have write permission on the
history file @file{tua.history}, usually located inside the spool
directory of your UUCP. So if @file{tua.history} does not exist,
@sc{tua} needs write permission on that directory to create it. @refill

@item -0
@itemx --reset-history
Reset the history database, thus clearing the non-volatile memory
of @sc{tua}. This option must be used with @code{--update-history}.

@item -y
@itemx --no-hourly-chart
Do not display the hourly activity chart.

@item -z @var{size}
@itemx --chart-size @var{size}
Set the size of the hourly activity chart to @var{size} rows. The greater
this number is, the smaller is the scale. By default it is set to 10.

@item -o
@itemx --chart-only
Display only the hourly activity chart. Since with this options @sc{tua}
reads only the statistical data produced by
UUCP@footnote{@file{.Admin/xferstats} for HDB Uucp, @file{Stats} for
Taylor Uucp}, it is faster. @refill

@item -v
@itemx --verbose
Print, on standard error, what is going on. While @sc{tua} reads the
various logs, it displays a counter of the loaded lines. This option is
enabled only specifying -DDEBUG at compile time.

@item -p @var{path}
@itemx --prefix-path @var{path}
By default, @sc{tua} looks for uucp logs in the directory specified in
@file{src/customize.h} at compile time. This option lets you
change this directory, so that @sc{tua} looks for the data in the
specified @var{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. @refill

@item -u @var{user=alias}
@itemx --user-alias @var{user=alias}
Inserts @var{alias} as the new name for @var{user}. Where ever appears
@var{user} it will be replaced with @var{alias}. Since this occurs at
the lowest level, if happens that @var{alias} is another user name, this will
cause that all the data that belongs to @var{user} will be added to the
@var{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.@refill
@example
$ tua --user-alias piggy=lele --user-alias gnu=lele
@end example
This will merge data from users @var{piggy} and @var{gnu} with that of
user @var{lele}. 

@item -r @var{port=alias}
@itemx --port-alias @var{port=alias}
Like @code{--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. @samp{tty1a} and
@samp{tty1A}).@refill

@item -s @var{sys=alias}
@itemx --system-alias @var{sys=alias}
Like @code{--user-alias}, but it applies to the systems names.

@item -E @var{glob=alias}
@itemx --glob-user-alias @var{glob=alias}

@itemx -R @var{glob=alias}
@itemx --glob-port-alias @var{glob=alias}

@itemx -M @var{glob=alias}
@itemx --glob-system-alias @var{glob=alias}
These are the counterpart respectively of @code{--user-alias},
@code{--port-alias} and @code{--system-alias} with @samp{meta-characters}
searches. You can use for example @refill
@example
tua --glob-user-alias uu*=UUCPUSERS
@end example
and every user name that begins with @samp{uu} will be mapped in a meta
user called @samp{UUCPUSERS}. See the manual page for @code{bash(1)} or
@code{wildmat(3)}, distribuited in the @file{doc} directory of the
distribution package, for a description of
@samp{meta-characters}.@refill

@item -t
@itemx --no-tua-rc
When the TCL extensions (@pxref{TCL}) are enabled, @sc{tua} loads a TCL
script upon startup. This option prevents this to occur.

@item -T @var{filename}
@itemx --rc-file @var{filename}
Specify an alternate initializing TCL script, ie @sc{tua} will load
@var{filename} at startup instead of the standard @file{TUA_init.tcl}.

@item -I
@itemx --interactive
Enter in interactive mode. After @sc{tua} finished to collect the data it
needs, it will prompt you for TCL commands, in particular those that
print some report. @xref{Command List}.@refill

@item -V
@itemx --version
Print just the version, without any further processing.

@item -i
@itemx --help
Show a summary and a description of all the options.

@item -Y
@itemx --taylor-uucp
This option is available only if @sc{tua} was compiled with both TAYLOR_UUCP
and HDB_UUCP defined. It forces @sc{tua} to read the Taylor UUCP logs, the
default behaviour.

@item -B
@itemx --hdb-uucp
This option is available only if @sc{tua} was compiled with both TAYLOR_UUCP
and HDB_UUCP defined. It forces @sc{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.

@end table

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

@node Output, History, Options, top
@comment  node-name,  next,  previous,  up
@chapter Detailed report description
@cindex Output

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
@end menu

@node By System, By User, Output, Output
@comment  node-name,  next,  previous,  up
@section 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 @samp{inbound} and @samp{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 @code{--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.
@example
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
@end example

@node By User, Daily, By System, Output
@comment  node-name,  next,  previous,  up
@section 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.
@example
By User:
========
                        S E N T
User         Files   KBytes      Time

gnu            18        13     0:00:24.99
news          118      2585     0:54:33.65
@end example

@node Daily, Summary by System, By User, Output
@comment  node-name,  next,  previous,  up
@section Daily Section
@cindex Daily Activity

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 
@example
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
@end example

@node Summary by System, Summary by System (table format), Daily, Output
@comment  node-name,  next,  previous,  up
@section Summary by System
@cindex Summary by System (Verbose)
@cindex Per System Summary

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

Please note that sometimes @sc{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.
@footnote{In some cases it may even be smaller than the sum. This is
currently a bug, not a feature.} @sc{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 @file{xferstats} if reading HDB logs, or in @file{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 @ref{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. 
@example
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
@end example

@node Summary by System (table format), Since, Summary by System, Output
@comment  node-name,  next,  previous,  up
@section Summary by System - Table Format
@cindex Summary by System (Table format)
@cindex Per System Tabled Summary

Substancially, this report summarizes some of the previous information in a
tabular form. Nothing new@dots{}
@example
+--------+--------------------------+--------------------------+----+
|        |      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|####|
+--------+----------:---------:-----+----------:---------:-----+----|
@end example

@node Since, Last 12 months Activity, Summary by System (table format), Output
@comment  node-name,  next,  previous,  up
@section Historical data - Since@dots{}
@cindex Since@dots{}
@cindex Historical data

This is the historical data maintained by @sc{tua}.  It looks like the
previous table, but it includes the history of the system,
incrementally since the last @samp{history reset} operation.
@example
...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|####|
+--------+----------:---------:-----+----------:---------:-----+----|
@end example

@node Last 12 months Activity, Hourly Activity, Since, Output
@comment  node-name,  next,  previous,  up
@section Last 12 months Activity
@cindex Last 12 months Activity
@cindex Summary of the last year 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!)
@example
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
------+---+---+---+---+---+---+---+---+-----+-----+-----+-----
@end example

@node Hourly Activity,  , Last 12 months Activity, Output
@comment  node-name,  next,  previous,  up
@section Hourly Activity
@cindex Hourly Activity
@cindex Communication port Activity

@b{NOTE:} Taylor Uucp 1.04 needs a patch to print the name of the port
used for the connection in the @file{Stats} logfile. See @ref{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.
@example
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
@end example

@node History, TCL, Output, top
@comment  node-name,  next,  previous,  up
@chapter History
@cindex History
@cindex Historical data

@sc{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 @file{@dots{}/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 @sc{tua} simply to have a notion
of what is going on.

To make it working correctly, you have to run @sc{tua} with the option
@code{--update-history} just before you run uuclean. So probably you will
have to modify that script including in it a line like

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

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 @sc{tua}, but I can understand your curiosity!.

@node TCL, GNU General Public License, History, top
@comment  node-name,  next,  previous,  up
@chapter TCL Interface
@cindex Configuring @sc{tua} with TCL 
@cindex Runtime configuration with TCL

@dfn{TCL} means ``Tool Command Language'', and it was designed by John
Ousterhout@footnote{His e-mail address is ouster@@sprite.berkeley.edu}
to make it easier to add an embedded command language to the programs
that need this feature.

This chapter talks about the relationship between @sc{tua} and TCL. You need
TCL version 6.1 or higher, and compile @sc{tua} with the option
@code{USE_TCL} in order to get these functionalities.

Using this facility, you can configure @sc{tua} at runtime. Currently this is
just a different way to specify command line options (@pxref{Options}),
but adding others of them is very simple.

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

@sc{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 @sc{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 @sc{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
@end menu

@node More about TCL, Available TCL commands, TCL, TCL
@comment  node-name,  next,  previous,  up
@section More information about TCL
@cindex Getting TCL
@cindex TCL Mailing List

You can obtain a copy of TCL by @code{ftp} from
@cite{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 @cite{USENET}: @b{comp.lang.tcl}. There is also a mailing
list that collects the people interested with TCL.  Send a request to
@code{tcl-request@@sprite.berkeley.edu} to join in.

@node Available TCL commands, Adding new TCL commands, More about TCL, TCL
@comment  node-name,  next,  previous,  up
@section Available TCL commands

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

@node Command List, Examples, Available TCL commands, Available TCL commands
@comment  node-name,  next,  previous,  up
@subsection List of the TCL commands
@cindex Available TCL commands

@deffn {TCL Command} kill_user username
The user @var{username} will never appear in the report.
@end deffn

@deffn {TCL Command} user_alias username alias
Insert @var{alias} as the new name for the user @var{username}.
@end deffn

@deffn {TCL Command} glob_user_alias username alias
Insert @var{alias} as the new name for the group of users whose name
matches @var{username}. @var{username} may contains ``meta-characters'',
with rules very similar to those supported by the @code{shell}.
@end deffn

@deffn {TCL Command} kill_sys sysname
The system @var{sysname} will never appear in the report. 
@end deffn

@deffn {TCL Command} sys_alias sysname alias
Insert @var{alias} as the new name for the system @var{sysname}.
@end deffn

@deffn {TCL Command} glob_sys_alias sysname alias
Insert @var{alias} as the new name for the group of systems whose name
matches @var{sysname}.
@end deffn

@deffn {TCL Command} kill_port portname
The communication port @var{portname} will never appear in the report.
@end deffn

@deffn {TCL Command} port_alias username alias
Insert @var{alias} as the new name for the communication port @var{portname}.
@end deffn

@deffn {TCL Command} glob_port_alias username alias
Insert @var{alias} as the new name for the group of ports whose name
matches @var{portname}.
@end deffn

@deffn {TCL Command} do_option optionname
Simulates the invocation of @sc{tua} with the option @var{--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 @var{optionname} passed as the argument.
@end deffn

@deffn {TCL Command} interactive
Enter in interactive mode. @sc{tua} will prompt you for some TCL commands,
and it will print the result on @emph{stdout}, unless any redirection of
the standard output was specified on the command line.
@end deffn

@deffn {TCL Command} systems_report
Prints out the Per System Report; @xref{By System}.
@end deffn

@deffn {TCL Command} users_report
Prints out the Per User Report; @xref{By User}.
@end deffn

@deffn {TCL Command} daily_report
Prints out the Daily Activity; @xref{Daily}.
@end deffn

@deffn {TCL Command} system_summary
Prints out the Per System Summary; @xref{Summary by System}.
@end deffn

@deffn {TCL Command} system_summary_table
Prints out the Tabled System Summary; @xref{Summary by System (table
format)}. 
@end deffn

@node Examples,  , Command List, Available TCL commands
@comment  node-name,  next,  previous,  up
@subsection A sample Initialization Script
@cindex @file{TUA_init.tcl} example

What follows is just an example of what you can put in your
@file{TUA_init.tcl}.

@example
@include ../lib/TUA_init.ex
@end example

@node Adding new TCL commands,  , Available TCL commands, TCL
@comment  node-name,  next,  previous,  up
@section Adding new TCL commands
@cindex New TCL Commands

Embedding a new TCL command into @sc{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 @var{TCL_OK} when it ends correctly, or
@var{TCL_ERROR} to signal an incorrect situation.

The called C function gets its arguments in the same way the function
@code{main} in a C program accepts arguments from the invoking
environment, i.e. with two variables, generally called @var{argc} and
@var{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:
@code{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 @code{Tcl_CreateCommand}. Look at the table in
@file{tcl_supp.c}, and add and appropriate entry for your function.

You can see examples of this operation in
@file{useralias.c}, @file{portalias.c}, @file{sysalias.c},
@file{tua.c}@dots{}, 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.

@node GNU General Public License, Bugs, TCL, top
@comment  node-name,  next,  previous,  up
@appendix GNU General Public License

@include gpl.texinfo

@node Bugs, Author, GNU General Public License, top
@comment  node-name,  next,  previous,  up
@appendix Bugs
@cindex Known deficiencies
@cindex Bugs

Since @samp{BNU} Uucp doesn't put a complete datestamp in its logs, but
omits the year, it may be possible that @sc{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, @sc{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@dots{}. If this is serious for you, I suggest switching to
Taylor Uucp.

@samp{BNU} logs get garbaged sometime, for a reason that is unknown to
me. This may cause @sc{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, @sc{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@dots{}
Ohhh well@dots{}

@menu
* Bugs Report::                 Bugs Report
@end menu

@node Bugs Report,  , Bugs, Bugs
@comment  node-name,  next,  previous,  up
@appendixsec Bugs Report
@cindex How to send a Bug Report
@cindex Reporting a Bug
@cindex Bug Report

If you have any problem building or using @sc{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.  @sc{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 @sc{usenet} groups, and it'd be difficult for me to
collect them.

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

@node Author, Acknowledgment, Bugs, top
@comment  node-name,  next,  previous,  up
@appendix Author
@cindex Author
@cindex Who wrote it and why

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 @code{nroff}
for the first manual page, and then @code{Texinfo} for this one: this
forced me to compile @TeX{} on my old machine, @code{GCC} since the
native compiler wasn't able to do it, and to find a @code{dvilj} for my
silly LJ compatible laser printer; @code{Bison} for the first approach
to parse the date inside the @code{uucico} logs; @code{TCL} as a
configuration tool; @code{GDB} to debug the binary tree
management@dots{}

And yes, I know that supporting @code{TCL}, @code{ReadLine},
@code{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 @file{src/customize.h} and maybe @file{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: @code{GNU Emacs}, @code{GCC}, @code{GDB}, @TeX{} and
@code{dvips} are there since the Big Bang. I added @code{Taylor Uucp},
restarted the development there and, at last, @sc{tua} run on a BSD system
(at least mine!).

@ifinfo
BTW, ``@sc{tua}'' in italian means ``yours'': ``questa cosa e' @sc{tua}'' can be
@end ifinfo
@tex
BTW, ``@sc{tua}'' in italian means ``yours'': ``questa cosa \'e @sc{tua}'' can be
@end tex
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
@sc{tua} with the GNU General Public License right to protect this intention.

@node Acknowledgment, Disclaimer, Author, top
@comment  node-name,  next,  previous,  up
@appendix Acknowledgement
@cindex Acknowledgement
@cindex Thanks

I want to thank especially Marco Lorenzini (marlor@@gear.sublink.org)
for his help in debugging the previous releases of @sc{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 @sc{tua} on Linux@dots{}

@dots{}And many others, who sent me logs, ideas, flowers@dots{}

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

@node Disclaimer, Compilation and Installation, Acknowledgment, top
@comment  node-name,  next,  previous,  up
@appendix Disclaimer

I reject any responsibility about this program. It is simple and safe;
unless you explicity give the option to update the history database
@sc{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 @emph{please}, forgive my poor english, but I put my soul in it@dots{}

@node Compilation and Installation, Files, Disclaimer, top
@comment  node-name,  next,  previous,  up
@appendix How to compile and install @sc{tua}
@cindex Compilation
@cindex Installation
@cindex Configuration
@cindex Customization

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

@code{configure} will check your machine and operating system to extract
some information, and will update @file{Makefile} and @file{config.h}.

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

A simpler way to change some of these settings is by giving some
command-line options to the @code{configure} procedure:

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

@item --with-readline
@itemx --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) @code{fgets()}. You can get the GNU ReadLine library from your
nearest GNU/FSF archive.

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

@item --with-softchip
@itemx --without-softchip
The @cite{SoftChip Btree Library} is a freely available balanced trees
implementation. @code{tua} internally uses a simple binary trees
library, included in the @code{tua} package, that is good enough for
me. As for @code{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 @sc{tua}
fly... However, if your machine have thousends @code{UUCP} neighbours...

@item --enable-taylor
@itemx --disable-taylor
Include or exclude the compilation and the linkage of the @cite{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) @sc{tua} capabilities...

@item --enable-hdb
@itemx --disable-hdb
@sc{tua} was born to parse @cite{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 @cite{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.

@end table

@sc{tua} 4.1 has been internationalized by using the @cite{GNU gettext}
package, and @code{configure} accepts two related options:

@table @code
@item --with-gnu-gettext
Bypass the system @code{catgets} or @code{gettext} to use GNU
@code{gettext}.

@item --disable-nls
Totally disable translation of messages.

@end table

See @file{ABOUT-NLS} in the distribuition package for other details.

Last run the compilation executing @code{make}.

@node Files, Taylor Uucp Patch, Compilation and Installation, top
@comment  node-name,  next,  previous,  up
@appendix Files

Here is a list of all the files involved in the analisys. Their exact
location is defined in @file{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
@end menu

@node HDB Uucp Files, Taylor Uucp Files, Files, Files
@comment  node-name,  next,  previous,  up
@appendixsec HDB Uucp Files

Files @sc{tua} reads when in HDB mode. The default prefix directory is
@file{/usr/spool/uucp}.

@table @file

@item @dots{}/.Log/uucico/*
Directory that contains uucico's logs

@item @dots{}/.Log/uucp/*
Directory that contains uucp's logs

@item @dots{}/.Log/uux/*
Directory that contains uux's logs

@item @dots{}/.Log/uuxqt/*
Directory that contains uuxqt's logs

@item @dots{}/.Admin/xferstat
File containing transfer stats

@item @dots{}/.Admin/tua.history
This file contains the history maintened by @sc{tua}.

@item @dots{}/TUA_init.tcl
This file is usually located in the library directory
@file{/usr/local/lib} and if exists it gets loaded at startup by
@sc{tua}. It may contain a TCL script used for customize some behavior of
the program.
@end table

@node Taylor Uucp Files, PCD File, HDB Uucp Files, Files
@comment  node-name,  next,  previous,  up
@appendixsec Taylor Uucp Files

Files @sc{tua} reads when in Taylor mode. The default prefix directory is
@file{/usr/local/spool/uucp}.

@table @file

@item @dots{}/Log
Main Taylor Uucp log file.

@item @dots{}/Stats
Transfers statistics.

@item @dots{}/tua.history
This file contains the history maintened by @sc{tua}.

@end table

@node PCD File, TCL Files, Taylor Uucp Files, Files
@comment  node-name,  next,  previous,  up
@appendixsec PCD File: Phone Categories configuration
@cindex Phone Categories
@cindex PCD File
@cindex country configuration

In order to subdivide the time your system spends talking at the phone
in each of cost rates used in your country, @sc{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 @sc{tua} is able to read
this information from an external file, using the @b{Phone Categories
Definition Language}. In this language, spaces, tabs, new lines are
ignored, as well as the comments, introduced by a pound sign @key{#}
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
``@code{default = "}@var{your_country_name}@code{"}''.

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

@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;
  @};
@}

@end example

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
@code{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
@example
currency = "Lit";
@end example

You may specify with how many decimal digits @sc{tua} will print money
amounts:
@example
decimals = 4;
@end example

It is possible to assign a @i{cost} to each timeband with a statement
like
@example
cost HIGH = 123.2/60.3;
@end example
that means you will pay 123.2 units of @var{currency} every 60.3 seconds.
@sc{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

@example
cost LOW = 127;
@end example
to mean that in the ``LOW'' band each call costs @emph{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
@example
cost MEDIUM = 254,127/66;
@end example
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
@file{/usr/local/lib}, and named @file{TUA.pcd}.

@node TCL Files, NLS Files, PCD File, Files
@comment  node-name,  next,  previous,  up
@appendixsec TCL Initialization file
@cindex TCL

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

@xref{Examples}.

@node NLS Files,  , TCL Files, Files
@comment  node-name,  next,  previous,  up
@appendixsec National Language Support files
@cindex Internationalization

Files @sc{tua} accesses when NLS is needed.

@table @file

@item @dots{}/@var{LANG}/LC_MESSAGES/TUA.mo
Where @var{LANG} is the selected national language, contains the
translations of all the messages @sc{tua} will put in the generated
reports.

@end table

@node Taylor Uucp Patch, Concept Index, Files, top
@comment  node-name,  next,  previous,  up
@appendix Taylor Uucp Patch
@cindex Patch for Taylor Uucp

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 @file{Stats} log file. @refill

@sc{tua} automatically recognize patched logs, and will produce the
chart without any other intervention by you. @refill

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

Taylor Uucp 1.05 and greater do not need this patch.

@example
@include ../src/taylor/TaylorLogsPatch.diff
@end example

@node Concept Index,  , Taylor Uucp Patch, top
@comment  node-name,  next,  previous,  up
@unnumbered Concept and Function Index

@printindex cp

@contents
@bye
