Category : Communication (modem) tools and utilities
Archive   : !LOCAL11.ZIP
Filename : LOCALNUM.DOC

This is a shareware program. You should feel obligated to pay for
it. The reasonable fee is $8 for a full operational license. Your
contribution will help support the concept of shareware, aid in
putting my perfect, angelic children through private schools, and,
maybe buy me some nice things. See the bottom of this document for
details. If you're impatient, here's my address:

Matthew J. Slattery
1696 Forest Hill Court
Crofton, MD 21114


LOCALNUM 1.1
------------
You know what stinks? I live in the Annapolis, Maryland area.
That happens to fall in between the large Washington, DC and
Baltimore, MD dialing areas. Many numbers under both the 410 and
301 Maryland area codes are long distance to me, even though they
may be just a few miles away.

I'm an avid BBS (Bulletin Board System) user, but living where I
do, I can never tell if a BBS number I have is local to me or not.
Many times, I'll download a list of numbers and discover that most
of them (if not all of them) are long distance calls.

That's why I developed LOCALNUM. It's a little utility that, once
configured, can tell me whether any phone numbers in a given list
are local calls to me. This saves me time and headaches when I
download a list of BBS numbers. I even discovered that a few
cities which are thought were long distance were actually local.

If you sometimes download lists of BBS's, or have any need to
determine whether a given number is local to you without first
dialing it, you could benefit from using LOCALNUM.


What's new in version 1.1?
--------------------------
Added the #include command to aid in the creation of the config
files. I agree that the config files are a pain to set up and
maintain, particularly when so many exchanges share the same
groups of local numbers. The #include command should ease
some of the pain until I come up with a better idea.

Added intelligence to check a single number from the command
line. The format is "LOCALNUM 555-1212 {configfile}". The
number is checked and the results printed. If used in
in conjunction with the 'b' switch such as
"LOCALNUM b 555-1212 {configfile}" nothing at all is
printed and the program returns an error code based on
the confidence key (see below).


Using LOCALNUM
--------------
LOCALNUM is quite simple to use. First, it must be configured.
Once that is done, you invoke it using one of the following formats:

Checking an entire file
-----------------------
To check for local numbers in a text file, such as a BBS list,
invoke LOCALNUM with the following format:

LOCALNUM {switches} textfile {configfile}

LOCALNUM will read the configuration file and print a list of phone
numbers in the text file that are local calls from your area. It
will print the phone number, the line number in the file, and the
line itself. It also prints a "confidence key" to indicate how
certain it is that a given number is in your local calling area.
The key is shown below:

! exact match of area code and exchange
? no area code was given in the file, but the exchange
matches at least one area code and exchange in your
configuration file.
- An area code was given in the text file, and a match for
the exchange was found - but with a different area code.

If you neglect to specify a configuration file, LOCALNUM will look
for a file called LOCALNUM.CFG and use it. You may program your
own configuration (see below) and copy it to LOCALNUM.CFG so that
you only have to type "LOCALNUM textfile" to use this utility.

There's currently only one command line switch available - "/b".
The 'b' switch puts LOCALNUM into brief mode, where it prints only
the phone number. No confidence key, line number, or line of text
is printed. This may be helpful in reading the output or exporting
it into other programs.


Checking a single number
------------------------
LOCALNUM also allows you to pass a single number on the command
line. It automatically recognizes the number as not a filename
and will treat it as such. Samples are shown below:

LOCALNUM {switches} 555-1212 {configfile}
LOCALNUM {switches} (123)555-1212 {configfile}

LOCALNUM has a reasonable level of intelligence built in to
recognize different formats of phone numbers passed on the
command line. For instance, the dash or the parentheses are
optional, so 5551212 is valid, as is 1235551212, and various
other combinations.

If the 'b' (brief) switch is used with the single number format,
LOCALNUM prints nothing but returns an errorlevel that may be checked
in a batch file. The errorlevel is set to match one of the confidence
keys documented above. The following errorlevels will be set

0 no match found
1 matches confidence key '-'
2 matches confidence key '?'
3 matches confidence key '!'
255 bad number passed to LOCALNUM

A sample batch file where the number is passed as the first command
line parameter might look as follows. Note that the highest errorlevel
is checked first because the "if errorlevel" test is considered to be
true if the errorlevel is greater than or equal to the operator. If
you don't know what I talking about, consult your DOS manual.

LOCALNUM -b %1 myconfig.cfg
if errorlevel 3 goto REALLYGOODMATCH
if errorlevel 2 goto PRETTYGOODMATCH
if errorlevel 1 goto WEAKMATCH
if errorlevel 1 goto NOMATCH
goto BADPHONENUMBER

:REALLYGOODMATCH
.
. Insert some batch commands here (etc.)
.


Programming your configuration file
-----------------------------------
In order to use LOCALNUM, you need to specify the area codes and
exchanges that are local to you. Where do you get this
information? Your local phone book probably has this information
in it - probably in the front or center section where they list
local attractions, have a local map, or detail your local
governmental agencies. If not, try calling your local phone
company and asking if they can provide you with a list (or just
skip a phone bill or two, and they'll call you.)

Once you have this information, you must encode it in such a way
that LOCALNUM will read and register it. The configuration file
contains this information, and it is encoded in the following
format:

#areacode1
exchange1
exchange2
.
.
exchangeN

#areacode2
exchangeA
exchangeB
.
.
exchangeX

For example, my local area is local to two area codes, 301 and 410.
My configuration file might look as follows (my actual
configuration is in the LOCALNUM.CFG packaged with this utility, so
look there for guidance). Note that comments are delimited with
semi-colons, which may appear anywhere in a line. Blank lines are
also permissible.

;
; Baltimore and Annapolis
;
#410
224
263
266

;
; DC/Metro Suburban MD area
;
#301
261
858
206

This file must be created as a pure ASCII text file, such as that
created by the EDIT utility that comes with DOS 5.0 and above. It
must not contain any formatting or extraneous characters. You may
use your word processor to create the file, but remember to save it
as an ASCII or TEXT file (CTRL-F5 for you Word Perfect users.)

When you create this file, please save it as aaaeee.CFG, where
"aaa" is your area code and "eee" is your exchange. For instance,
my home number is (410) 721-xxxx, so my configuration file is
410721.CFG.

The #include command
--------------------
I agree that creating these files is a pain, so I added the #include
command to ease the pain a little. It is particularly helpful if
you wish to create configuration files for more than just your
exact exchange.

The #include command tells LOCALNUM to stop reading the current
configuration file, open a new one, and read it as though its
contents were included in the current file. When the end
of that opened file is reached, LOCALNUM picks up reading where
it left off in the original file.

For example, the file MYCFG.CFG contains the following

#123
987
876

#include MYCFG2.INC

654

And the file MYCFG2.INC contains the following line

765

LOCALNUM will contruct the list of exchanges for area code 123
so that it contains 987, 876, 765, and 654. Notice how the
exchange 765 from the included file is magically inserted into
the list.

One thing you'll have to be careful of is changing the area code
from within an included file. LOCALNUM processes included files
are though they were actually inserted in the original file,
so any #123 style area code changes will be in effect when the
included file reaches its end and new number are encountered in
the original file.



******************
AN IMPORTANT NOTE:
******************
Once you have created your configuration file, and saved it under
the correct name, compress it using PKZIP or another popular
compression utility, and save that compressed file as LNaaaeee.ZIP
(see above for what "aaa" and "eee" mean.) Then upload that file
to the BBS from where you downloaded this utility. This will save
the next guy time, and help me construct a nationwide list of local
numbers for a future release of LOCALNUM. Include your name in the
comments of the configuration file to get ample credit and the
admiration of your peers. If you find errors in an LN file you
download, beg and plead with your BBS's sysop to replace it with
your corrected version.

If you create a group of configuration files, zip them into a single
file called LNsscccc.zip, where "ss" is your two-letter state
abbreviation, and cccc is some sort of representation of the exchanges
that you have encoded. For instance, I have created LNMDANAP.ZIP that
contains all the files for the Annapolis, MD calling area.


Features for Future Versions
----------------------------
The following features are being considered for future releases of
LOCALNUM. Consider this a wish list. I make no promises that any
or all of these features will ever be implemented. In fact, if I
don't see some decent money coming in the door, you may be holding
the final release of LOCALNUM. Please drop me a letter if you have
comments or suggestions for enhancement. Enclosing a check will
help me maintain my concentration on your correspondence.

Full, nationwide directory of valid phone exchanges so you
don't have to program your own configuration file.

Option to sort valid phone numbers.

Ability to maintain a database of phone numbers and show the
differences between phone numbers in a text file and ones in
the database. This will help you recognize when a BBS appears
or disappears from your local scene.

Ability to use the LOCALNUM database and difference feature to
update and maintain your communication program's dialing
directory. Should support most popular communications
programs (e.g. Procomm, QModem, Telix.)

Windowed on-screen user interface. Command line still
functional.

Direct dial and connect capability when phone numbers are
located. I'll either develop my own techniques or allow you
to launch your favorite communications program in such a way
that it will dial the number given it.


Registration and Licensing Information
--------------------------------------
If you use and benefit from LOCALNUM, please forward a "donation"
of $8 US to the address below. I'll attempt to answer some
questions about the licensing below.

Why $8? Because LOCALNUM took me about 8 hours of programming and
documentation time. At a rate of $40 per hour, that means it cost
me $320 to develop. If 4,000 people nationally download and use it
at least occasionally, and if 1% of them have the upbringing and
moral integrity to pay me for my efforts, I'll break even.

What do you get for your $8? A warm feeling inside, knowing that
you've done your duty as an American and supporter of the free
enterprise system. If your political or economic tendencies stray
from the basic tenets of capitalism, rest assured that your payment
supports a new system of software distribution whereby large,
exploitative companies are brought to their knees through the
thoughtful, caring action of collective-minded individuals. And if
my Lexus happens to pass through your commune, be sure to wave.

What if you don't pay $8? Not much happens. This is not
crippleware, or trialware, or demoware. This is a fully functional
program. If you use it, you should pay for it. If you use it and
don't pay for it, you won't be punished. If a lot of people don't
pay, you're looking at the last official release of LOCALNUM.

What if you're a corporation? Pay me $8. You'll get the same
benefits as the average single user (see above under "What do you
get for your $8?) I make no further restrictions on usage. Put
this utility on a network and let anyone or everyone use it. What
the hell. But if you work for a company that uses it, and you take
it home to use it for your own purposes, please pay an extra $8 for
the use of your personal copy.

Are there any restrictions? Sure, I don't want my good name
attached to any hacked up, trashy versions of software, so you're
not permitted to modify, disassemble, or reverse-engineer the
executable (past and future misguided court rulings to the contrary
being the exception) in any way. And please be sure to distribute
the compressed (ZIP'ed) file in its entirety as I have packaged it,
documentation, support files, etc. included, with no addition of
your own files. If you're a BBS sysop, and feel the need to
include an ad for your BBS in my ZIP file, please do it in the
comments of the zip file, not by adding another advertisement
file to the zip.

Where do I send my $8? Make your checks or money orders out to me
and send them to the following address:

Matthew J. Slattery
1696 Forest Hill Court
Crofton, MD 21114

I wouldn't recommend sending cash through the U.S. Mail, but if you
do, please enclose a little note indicating that you paid me $8 for
the LOCALNUM utility. It'll help me prove to the I.R.S. that I'm
not a criminal. Include comments and suggestions if you have any.