PHONE version 1.3


A Shareware Dialing Utility
Copyright 1988 by Jonathan Wayne


PHONE is dialing utility that has great flexibility in dialing numbers
through a modem. It is NOT a resident (TSR) dialer and must therefore
be invoked from a DOS prompt. If there is a great need (which I doubt,
since there are TSR phone dialers such as the one provided with
Sidekick) I might consider making PHONE a resident program.
Nevertheless, I find it one my most used utilities that was written
because other dialers didn't satisfy my needs.

For PHONE to be of any use you must have a modem connected to your
computer. There must also be a phone connected to the same line (either
at the modem or with a "T" adapter at the phone jack) unless you just
want to listen to the weather or Dial-a-Joke through the modem speaker!

If you type 'PHONE' from the DOS command line, you will see a syntax
error message as you must supply an argument to PHONE. If you type
'PHONE ?' a help screen will be displayed explaining your three options
and showing your current configuration. Command line options are:

PHONE (#)
PHONE (name)
PHONE -cfg


An Explanation Of Your Options


1. PHONE #, where # is the phone number that you wish to dial.

The number must begin with a digit and may contain other characters
that your modem recognizes, such as dashes, parentheses, and commas.
As a matter of fact, NO filtering of characters is made with this
option. However you may include spaces only if the entire phone number
is enclosed by double quotes. E.g.:

PHONE 18003551212 - ok
PHONE 9,1(800)355-1212 - ok
PHONE 1 800 355-1212 - no good
PHONE "1 800 355-1212" - ok


2. PHONE name, where name is a character string, for example 'PHONE
mom'.

This option is the real reason for PHONE being written. It will look in
a phone directory file (more on this later) for the first line
containing the name specified (case insensitive), and then try and
extract from the line a legitimate phone number. This extraction will
begin at the first digit (0-9) in the line and continue to the end of
the line OR until an invalid character is reached. Valid character
include digits, space, comma, parenthesis, dash, colon, pound sign and
asterisk. In addition, a phone number must be a minimum length which
is defined by the configuration option (the default is a 7 digit
minimum). If the number extracted is not of minimum length, PHONE will
continue to look on the same line for a legitimate number, exiting with
a message if one is not found. Phone numbers do not have to occur on
the same line as the name, provided that you enable the line search
increment option described later.


For these two options it is best, nay almost necessary, to have your
modem speaker on (you can do this with the configuration option if you
desire -- ATM1, for example, enables the speaker while dialing with a a
Hayes-compatible modem). If the number was extracted from a file, then
the line containing the number will be displayed. Also displayed is a
note saying that a SPACE will hang up the modem. You will then hear
the dialing. When the dialing is completed you may pick up the
telephone. If the line is busy, you may either hit the space bar which
hangs up and exits the program, or type in 'A' or 'a' which dials
Again. The 'A' option is also useful if for some reason the modem
doesn't dial the first time. If you pick up the phone to talk, tap the
space bar to disconnect the modem.

You have other options if the line is busy, especially useful for phone
numbers that are constantly busy. An 'R' or 'r' will start a redial
loop using the default redial interval defined in your configuration.
For example, if the redial interval is 10 seconds, then PHONE will hang
up and redial the phone number every 10 seconds. You may also specify
another redial interval on the fly by typing a digit, 1 to 9, during
dialing. PHONE will multiply this number by 4 and use the result as the
new redial interval. This is useful when you would like to compensate
for some numbers taking much longer or shorter to dial/connect than
others (e.g., local versus long distance). Please note that PHONE
"sleeps" without checking the keyboard while in the midst of a redial
cycle, so hitting the space bar will hang up the phone only after the
conclusion of that cycle.

You can also type an 'X' or 'x' to exit the program without hanging up
the modem. This can be useful if your modem has a redial upon busy
option (eg, ATB1 - or a colon after the number - with a Hayes 2400, or
an ATX2 with a Prometheus 1200) and you are calling a number that is
usually busy. An 'X' will allow you to use your computer while the
modem continues to redial. However, when the party answers (or when
you get tired of waiting) you'll have to hang up the modem. You can
either turn off the modem itself, or do something like 'PHONE 1' and
then hit the space bar. IMPORTANT: unless you specify otherwise, your
modem will send result codes back to the computer via the serial port.
In such a case, when you use the 'X' option to continue dialing a
number and then continue working at the computer, it is very likely
that your system will crash, requiring you to reboot! This can be
avoided by specifying a "quiet mode" in the initialization string (ATQ1
for Hayes and compatibles). So why don't I have PHONE invoke this
option automatically? Because I'd like to give the user as much leeway
as possible in controlling his/her configuration. And to allow non-
Hayes commands strings. Of course, additional problems are likely with
the 'X' option if you invoke programs that use the COM port while PHONE
is dialing. Please note that the 'X' and the 'R' options are mutually
exclusive. The 'R' redials from within the program, while the 'X'
exits the program and allows redialing according to the modem's
capabilities.


3. PHONE -cfg (or PHONE /cfg), to view or change program defaults.

This option allows you to make a number of changes to the PHONE
program, such as changing which COM port you use, the modem
initialization string, and the file name in which your phone numbers
are kept. Invoking this option will show you the current settings and
then allow you change those options, PROVIDED that the program
'PHONE.EXE' is in your current directory and it is writeable (e.g., not
"read only"). Note that there is no separate configuration file - all
changes are direct patches to 'PHONE.EXE'.


A '1' on the config screen allows you to change the communications
port. Only a '1' or a '2' will be accepted (COM1 or COM2). It is up
to you to make sure that a valid COM port is specified, as there is no
checking as to whether the port exists or if a modem is attached to it.


A '2' on the config screen allows you to change the modem
initialization string. You can change things such as dialing speed,
pulse versus tone dialing, etc, depending upon the capabilities of your
modem (see your modem manual for specifics). This option will accept a
string of up to 25 letters which will be converted to upper case (as
per the Hayes standard. Let me know if this is a problem). A tip:
register S11 controls the speed of tone dialing. PHONE comes configured
to S11=55. Keep such a low value for S11 in your configuration if you
like speedy dialing!


A '3' on the config screen allows you to change the name of the file in
which the phone numbers are kept. Up to 50 letters may be input if you
want to define the entire file path. If you don't specify the entire
file path, then the file specified must exist either in the current
directory (the directory you are in when you invoke PHONE) or in a
directory included in your PATH environment setting. It is preferable
to explicitly define the entire file path, since you don't want to be
restricted to the current directory and the PATH is usually used for
locating programs (i.e., not data). This should also, in general, give
you the best performance when PHONE must reference the file to extract
a phone number.

(Note: if you keep your phone file in the root directory, and if root
is not included in your path, you MUST prepend the phone file name with
a '\' (backslash). This is due to a bug in Turbo C. I felt that the
situation was sufficiently rare to justify adding additional code.
Keeping PHONE small is a priority in making any modifications!)


A '4' on the config screen is for changing the minimum length of a
phone number string. You can specify between 1 and 9 for this option.
For example, from home I have a seven digit minimum and anything less
than that is not a legitimate number. From my office one can dial a
four digit extension. So I use different patches for each location
specifying a different minimum length. Note: there is NO minimum when
specifying the number on the command line.


A '5' on the config screen is for changing the redial delay mentioned
above. You can specify any number from 5-99 seconds.


A '6' on the config screen enables or disables the line search
increment for extracting phone numbers. This allows you more leeway in
the format of the file that contains your phone numbers. Let's say
that you want to use an address file to double as your phone file, and
that you use the following format:

John Doe
123 Main Street
Anywhere, USA 12345
1 (212) 123-4567

The third line after the name is the party's phone number. You would
thus enable the line search option by specifying a '3'. PHONE will
then search for a valid phone number on the third line following the
name (i.e., the fourth line of an address entry). The config option
will accept a 'D' for disabling this feature, or a '1' through '9'.
Disable simply means to search for a valid phone number on the same
line as the name that was matched.


An ESCAPE will exit the configuration option and save any changes that
you made, as long as you say that it is OK to do so.



A Brief Note About Your Phone Directory

Your phone directory file should be a regular CR/LF delineated file.
This means that all lines end with a carriage return/line feed
combination. Most editors create such files (Eg, Sidekick's notepad,
Qedit, etc) as do some word processors (such as PC-Write). Many word
processors create files without carriage returns and which contain many
control codes and formatting information embedded within the text.
Actually, the problem is not with the lack of carriage returns: PHONE
should be able to handle such files with no problems. However, the
formatting codes may give you erroneous results, for example if they
contain numeric characters or extra line feeds. Most word processors
usually have a way to create unformatted text (called "Dos text" in
WordPerfect, "Unformatted text" in Microsoft Word, "Ascii text" in
others). Note that a phone directory file that works with Sidekick's
dialer can also be used by PHONE.

And remember, lines are parsed from the FIRST number in that line if
the line search increment is disabled. So don't try to 'PHONE MOM2'
(which you might have used as a second number for Mom, or the first
number for your second mother!) unless you have an invalid dialing
character between the "2" and the phone number desired.

Other than these restrictions, the format of your phone directory is
pretty much up to you. PHONE was designed to be very accommodating!



Shareware and Other Notes of Importance


This version of PHONE is the first shareware version due to the number
of enhancement requests I have received. Use it and share it freely.
But if you continue to use it, a payment of $10 PER USER is requested.
This will (hopefully!) allow me to spend more time making enhancements
to the program and allow you a clear conscience for supporting the
shareware concept. In a commercial environment, $10 PER WORKSTATION
using PHONE is required. Registered users will be mailed the next
major upgrade of PHONE free of charge. Likewise if any SERIOUS bugs
are found. Minor updates will be sent, upon request, for a nominal
mailing/material charge. Registered users will be given first
consideration for suggested modifications to the program. Mail your
payment to the address below. Be sure to include your address and the
version of PHONE you are using.

If you do share PHONE with other individuals and bulletin boards, this
documentation - without modification - must accompany every copy of
PHONE. The only alterations allowed to the PHONE program are those
patches created by the configuration option. No one is allowed any
monetary compensation for disbursing this program, other than
reasonable media costs.

PHONE is undergoing constant revisions, enhancements, and (very
rarely!) bug-fixes. Rather than bore you with an update history, just
be aware that the version accompanying this document, version 1.3, is
the most recent one. PHONE doesn't do anything weird that might mess
up files, disks, the ozone layer or whatever, but just for the sake of
completeness let me say that I AM NOT RESPONSIBLE for any damages,
direct or incidental, that might arise out of the use of this program.

PHONE is written in Borland International's Turbo C, version 1.5. The
communications module writes directly to the communications port via
polling - i.e, no interrupts are changed. Note that PHONE only supports
COM1 and COM2 at this time. Other than this restriction, PHONE should
be very tolerant of different modem/cable configurations, but please
inform me if you are experiencing any problems. PHONE has been tested
successfully on a number of different hardware configurations. (Note to
PCjr users: On most IBM compatibles, the port addresses for COM1 and
COM2 are at 3F8h and 2F8h, respectively. The PCjr has its internal
modem at 3F8h and COM1 at 2F8h. I don't have a PCjr for testing, but
you can probably use PHONE with a PCjr if you configure the program to
use COM1 for an internal modem and COM2 for a modem attached to the
COM1 port).



Please let me know via Compuserve EMAIL (CIS PPN number below) or at
the address below if you come across any bugs in PHONE. And even if
you decide not to register, if you have suggestions for improvement let
me know also. I'll be glad to implement such changes, time permitting.

Jonathan Wayne
977 Byron Ave
Elizabeth, NJ 07208

Compuserve PPN: 76703,410



end of documentation for PHONE
==============================================================================