                              QWKfone

                    A Fidonet "Phone Book" Utility
                             Version 1.3
                           by Bryan Beatty


QWKFONE.ZIP contains the following files:
    FILE_ID.DIZ     (short file description)
    README.TXT      (the file you're reading now)
    QWKFONE.EXE     (executable file)
    QWKFONE.CFG     (sample configuration file)

=============================================================================
1.  Installation
----------------

If you're reading this, you've already unZIPped the QWKFONE.ZIP file.
Put the QWKFONE.EXE and QWKFONE.CFG files in the same directory; QWKFONE.EXE
won't work properly if it can't read QWKFONE.CFG.  I put them in the same
directory as my off-line mail reader, but you can put them pretty much any-
where you like.



=============================================================================
2.  Usage
---------

QWKFONE filename

where filename is the name of a .QWK mail packet.  You may leave off the
".QWK" extension.



=============================================================================
3.  What It Does
----------------

QWKfone creates and maintains a text file database of message posters and
their Fidonet addresses-- sort of a "phone book" for Fidonet.  It does this
by extracting the relevant information from QWK mail packets.

When you run QWKfone, it scans through all the messages in a .QWK packet.
For each message, it extracts the names in the To: and From: fields, the
time and date of the message, and, if possible, the Fidonet address of the
sender.  It can usually find the Fidonet address, because echomail is usually
posted with an origin line that looks something like this:

* Origin: Some BBS Name (615) 555-1234 (1:2345/67.8)

The program looks at the final block of the message and searches for a
sequence n:n/n or n:n/n.n, where "n" signifies a contiguous sequence of
digits 0-9.  If it finds one, it interprets this as a Fidonet address and
adds the message to the database.

If the database file does not exist, QWKfone creates it.  If there is
already an existing database file, then running QWKfone on a new .QWK packet
will update the database by adding new entries to it.

The database file itself is an ASCII text file.  It consists of a time and
date stamp, followed by a blank line, followed by a single header line which
labels the various columns, followed by one data line for each person in the
file.  From left to right, each data line contains the following information:

Fidonet address
Name
Date of most recent message posted
Time of most recent message posted
Total number of messages posted
Total number of messages posted to you (blank if none)

In addition, if a user has posted any messages to you, an asterisk appears
to the left of his or her name.

Users are listed in alphabetical order, last name first.  If several messages
are received that have the same sender's name but different Fidonet addresses,
QWKfone creates multiple entries.  (If you don't like this, you can easily
go into the database file with a text editor and delete any lines you don't
want.)


=============================================================================
4.  The Configuration File:  QWKFONE.CFG
----------------------------------------

QWKFONE.EXE uses a configuration file, QWKFONE.CFG, to tell it where to
look for files, etc.  A sample QWKFONE.CFG is included with the program;
it ought to work "as is," but you'll probably want to change it with a
text editor to suit yourself.

The file QWKFONE.CFG should be in the same directory from which you run
QWKFONE.EXE.

When QWKFONE.EXE reads QWKFONE.CFG, it interprets blank lines, and any line
starting with a character other than a letter, as comments.  Any line
starting with a letter is interpreted as a command.

Commands have the format:

command="whatever"

Leading and trailing spaces are okay, and the program isn't case-sensitive,
but (IMPORTANT!) there should be no spaces within the commands themselves--
for example, before or after the = sign.

The following commands should be in the config file (if they're left out,
the program will use defaults):


QWKpath="path"
--------------
Specify a DOS path in which to look for QWK files.  path can be any valid
DOS path, and should include the drive name.  Example:  QWKpath="C:\COMM"
If this command is omitted, the program will look in the current directory.


Database="pathfile"
-------------------
Specify a complete path and filename for the database file.  If none is
specified, the default is QWKFONE.TXT in the current directory.
Example:  Database="C:\COMM\QWKFONE.TXT"


WorkDir="path"
--------------
Specify a directory to use for a working directory.  When QWKfone runs, it
creates some temporary files, which are deleted after running.  I generally
set this working directory to a RAM drive to speed things up, but you can
set it wherever you want.  If this command is omitted, the current directory
will be used.  Example:  WorkDir="D:\"


UnArchive="unarchiver"
----------------------
Specify a program to use to unpack the .QWK file.  For the vast majority
of people, this will probably be PKUNZIP, but I put this option in for those
poor souls using something else.  If this command is omitted, the default is
PKUNZIP.  Example:  UnArchive="PKUNZIP.EXE"


YourName="your name","your other name","your still other name"
--------------------------------------------------------------
Specify your name.  QWKfone needs this in order to tell which messages
in the QWK packet were sent to you.  Probably, you will have only one
name in there, but if you use different names or aliases on different
BBS systems (or if more than one person uses your computer), you can specify
up to 20 names delimited by commas.  IMPORTANT: Don't put in any extraneous
spaces (for example, after the commas).  If this command is omitted, the
default is set to "ALL".  Examples:
to specify just one name:   YourName="John Smith"
to specify multiple names:  YourName="John Smith","Snafu","Mary Smith"


MaxZone="num"
-------------
Specify the maximum allowable zone number, where num is some positive
integer, typically 5 or so (don't forget the quotes!)  Using this option  
will cause QWKfone to skip over all messages which have zones higher than
the specified maximum in their addresses.
    In a Fido address, the zone is the number that comes before the colon;
for example, the zone in the address 1:3615/65 is 1, which corresponds to
North America.  I added this option because some other nets (WildNet, for
example) also use addresses of the form n:n/n.n, which would result in
non-Fido addresses occasionally getting into the database.  These are usually
fairly easy to recognize-- they have much higher zone numbers than Fido
addresses.  I've never seen a Fido address with a zone higher than 5 or
thereabouts, so 5 might be a good setting.
    Omitting this command will disable filtering:  all addresses will be
accepted, regardless of zone number.


Twit="twitname"
Twit="twitname*"
---------------
This option allows the user to specify some names as "twits."  When QWKfone
scans through the messages in the .QWK packet, it will look at the sender's
name on each message, and if that name is a "twit," then the program won't
add that message to the database.
    You can specify only ONE twit on a line, but you can have up to 100 twit
lines in the config file.  For example, if you wanted to specify three names
as twits, you could add the following three lines to QWKFONE.CFG:
Twit="Schmoe, Joe"
Twit="Public, John Q."
Twit="Snafu"
    Note that the form of the name must be EXACTLY as shown in the database:
last name, comma, ONE space, other names (or just a single name, if there is
only one); it's not case sensitive, though.  IMPORTANT:  don't put in any
extraneous spaces in the line (for example, before and after the = sign).
    If you put a trailing asterisk after the name, then the program will
consider ALL names starting with that character sequence as twits.  For
example, if you wanted to ignore all messages coming from Schmoe, John Schmoe,
Mary Schmoe, or indeed anyone else named Schmoe, you could add the following
line to QWKFONE.CFG:
Twit="Schmoe*"



=============================================================================
5.  Why I Wrote QWKfone
-----------------------

For me, sending Fido netmail has always been a somewhat frustrating
experience.  I enter all my mail in an offline mail reader that uses the
standard .QWK packets which are available from just about any BBS.  When
I want to send someone netmail, I can generally get their Fido address from
the origin line at the end of the message.  Unfortunately, I can't enter
their Fido address in my reply in the offline mailer-- I can only enter their
name.  Since Fido addresses are generally un-rememberable sequences of
numbers, this means that in order to send someone netmail, I have to:
A) Write their Fido address down on a slip of paper,
B) Type the message,
C) Log into the BBS,
D) Upload my reply packet,
E) Find the slip of paper and type in the netmail address,
F) Hang onto the slip of paper forever after, just in case I ever want
   to send them netmail again.

It's *all* rather inelegant, but step F) is the doozy:  my desk was always
awash in a sea of little slips of paper all over the place in no particular
order, each with a hastily-scrawled name and address.  If I ever wanted to
write someone a message, I'd have to hunt around for the paper with his
address, or else find another message from him in a .QWK packet somewhere.

So I wrote QWKfone to help me keep track.  It takes *all* the messages from
the .QWK packet and keeps them in a database for me, conveniently alpha-
betized.  Probably 99% of the people in there I will never write to, but
they're there if I need them; and since every person who has ever sent me
a message (either netmail or echomail) is marked with an asterisk, I can
easily find the people to whom I'm most likely to write.  The file also
keeps track of when the most recent message was received from the person--
so every once in a long while, I can go into the database and weed out
everyone who hasn't posted anything in, say, a month.

I wrote QWKfone for my own convenience, since I needed something like it;
but a friend suggested that other folks might find it useful, too, so
here it is.  Have fun!



=============================================================================
6.  Some Ideas for Future Versions
----------------------------------

This is a *very* preliminary program; there are a lot of features that I
could have added, but which weren't necessary for the program to do its
primary job.  There are many ways in which the program could be improved.
There are also probably a lot of bugs which I haven't found yet.

If no-one out there is using the program, it's probably not worth the bother
to add features; but if a few people write me (hint, hint!) to tell me that
they're using the program, and wouldn't it be great if the program could
only _____, then I will probably release some future versions.  Anyway, here
are some ideas:

    --Error tolerance.  As it is, the program is quick-and-dirty, and
      is fairly intolerant of errors:  the QWKFONE.CFG has to be just
      so, without any extraneous spaces in the wrong places; if the
      filenames have unexpected characters or paths, the program will
      get confused; and so forth.  If the program turns out to be popular,
      I'll try to make it less brittle.

    --Keep track of BBS name for each entry in the database.  There's enough
      room to add an eight-character name (probably the name of the .QWK
      packet) at the right end of each data line, and still keep the total
      width under 80 characters.  This could be useful in keeping track of
      who's posting where.

    --Add more command-line options.  As it is, all QWKfone does is allow
      you to specify a .QWK file to scan.  I could add some more options
      which would allow you to perform various operations on the database:
      for example, hunt for a particular name; display a an alphabetized
      list of all users from a particular Fido node, network, or zone;
      purge out all entries for users who haven't posted anything for some
      specified length of time; and so forth.

    --Add more options to the configuration file.  For example:  a
      "do you want your own messages in the database?" toggle; a toggle to
      prevent QWKfone from creating multiple database entries in cases
      where two messages have the same name but different Fido addresses;
      a toggle to paginate the database file (with margins and form feed
      characters); a "verbose" switch to make QWKfone display more detailed 
      information as it works; and so forth.



=============================================================================
7.  Disclaimer
--------------

The author assumes no liability for damages or loss of data resulting from
the use of this program, even if the damage results from defects in this
program.  The author makes no representations concerning the suitability
of this program for any purpose.

Translation:  If the program screws up, it's not my responsibility.
This *is* a preliminary version and probably has bugs in it.  If you're
looking for someone to sue, go find someone who has money!  :-)



=============================================================================
8.  Copying
-----------

QWKfone is copyright 1994-1995 by Bryan K. Beatty.  This program is freeware.
Feel free to give copies of this program to all your friends.  (Please do!)
You may make unlimited copies of this program for any purpose, as long as
A) you don't sell it or make money from it,
B) you don't modify the program or this README file in any way, and
C) this README file is included with the program, complete with this
   copyright notice.


=============================================================================
9.  Please Write!
-----------------

Because it's freeware, I'm not asking for any money, but if you enjoyed
it or have comments, complaints, or suggestions for improvements, I *would*
like to hear from you-- if for no other reason than to find out how many
people are using the program.  You can send me Internet e-mail at the
address beatty@freenet.fsu.edu.  At the time of this writing (January 1995),
you can also send Fidonet netmail to Bryan Beatty at 1:3615/65, although that
may change.


=============================================================================
10.  Revision History
---------------------

version 1.0     11/12/94
    The very first version.  Worked, sort of.

version 1.1     11/14/94
    Fixed a couple of bugs, notably one that kept it from updating an
already-existing database with new people when a new .QWK was scanned in.

version 1.2     11/28/94
    Fixed a bug that could cause the program to hang if one person had
multiple Fido addresses.  Added MaxZone option to filter out addresses
with high zone numbers (WildNet addresses and the like).

version 1.3     1/1/95
    Fixed a bug that kept the program from properly updating the date and
time of the most recent message received from a user.  Added "twit list"
parameter to allow filtering of unwanted users.  Added time & date stamp
at the start of the database file.
