HUNTER -- An Automatic Phone Dialler Program This program commands a modem to dial a specified series of phone numbers until it finds one that isn't busy. It enables convenient calling to businesses that have multiple phone lines, in a phone system that lacks "hunt group" capability (which, if it were present, would immediately connect the caller to the first free line automatically). SETUP INSTRUCTIONS 1. Connect the modem to the phone line. 2. Connect a telephone instrument to the same line via a modular plug to dual-socket expander. Do not plug the phone into the phone socket of the modem; the relay inside the modem will keep the phone disconnected at certain times during the dial- ling process when it shouldn't be. 3. Connect the modem to the computer's serial port. 4. Using a text editor program, create the dialling directory file according to the format given below. Include at the beginning the serial port number and, optionally, a dialling prefix string. ERROR CHECKING When the program starts, it first checks the dialling directory file, and if it finds any erroneous entries, prints error mes- sages about them and exits. The user can save these messages (for reference while correcting the directory) by starting the program with its output redirected to a file, e.g.: hunter > errors.sav PROGRAM OPERATION Each business that may be called has a one-line entry in a dialing directory file (described below). When the program is started (if there are no errors) the user is shown the entries one screen at a time; PgDn and PgUp display the next and previous page (if any) respectively. To dial, the user types the indicated number of the desired entry (i.e., a number between 1 and the total number of entries), followed by the Enter key. The program then suc- cessively dials all the phone numbers specified by that entry. When a phone number is encountered that is not busy, the compu- ter's beeper is sounded, which signals the user to pick up the telephone receiver immediately. Pressing the spacebar after the beep causes the modem to hang up, so it doesn't shunt the phone and diminish the sound level. The user must pick up the phone before doing this, otherwise the connection will be lost. If all the numbers in the entry have been dialed and found busy, the program begins again with the first one. Pressing the Esc key interrupts dialling and causes the program to await another entry number. Pressing the Q key and answering "Y" (yes) when asked, quits the program. COMMAND-LINE OPTIONS -f path\file specifies the name and location of the dialing directory file; overrides the default--HUNTER.DIR in the current directory -t puts the program into test mode--commands are not actually sent to the modem -p prints out all lines of the dialing directory file during the error-checking that always occurs when the program is started -l list dialing directory in diagnostic form and exit, instead of interacting with user. -25 use 80x25 video mode -50 use 80x50 video mode THE DIALING DIRECTORY Phone numbers are specified in a dialing directory file, which the user creates by means of a text editor or word processor (if the latter, the file *must* be saved in ASCII, not document, format). The default name and location of this file is HUNTER.DIR in the current directory, but this can be changed by specifying another path/filename as a command-line argument to the program. This allows each of multiple users to have their own personal dialling directory. The file can have three different types of lines: 1. Dialling entries, which always contain at least one vertical- bar character, and may not contain an equal sign or begin with a period. 2. Parameter lines, which always contain an equal sign, and may not contain a vertical-bar character or begin with a period. 3. Comment lines, which must begin with a period. 4. Blank lines, which contain no characters, or only spaces and tabs. Each of these is described in a section below. SIZE LIMITATIONS Lines in the dialling directory are limited in length to 1000 characters. However, only the first 75 or so characters are displayed on the screen. The maximum number of lines in the directory is limited to 30,000. The program reads the entire file into memory when it runs, which limits the length of the file to the amount of available memory (which varies depending on how the computer is set up), less the size of the program itself. Also, the representation of the data in memory is somewhat larger than the file itself. These factors limit the size of the file to somewhere between 300KB and 600KB. If the file is too large, the program will report that it is unable to allocate memory and will abort. TABS To simplify the display of the directory, each tab character is replaced by a single space. It is recommended that tabs not be used in the file; if indentation of lines is desired, use spaces instead. DIALLING ENTRIES In the dialling directory, the entry for each company occupies one line, which specifies the company name and the phone num- bers to be dialled. FORMAT Dialling entries have the following format: Company name, etc. | # | # | # > N | ... # is a phone number and # > N represents a range of numbers. (Single phone numbers and ranges are both called "components".) Vertical bar characters separate the company name and the phone numbers and ranges. The directory can have any number of entry lines. The lines must not contain any equal signs, and must not begin with a period (to distinguish them from parameter lines and comments, respectively). The format of each phone number # is the same as used in the modem ATDT command (but without the "ATDT"), and thus may include commas, spaces, dashes, etc., which are sent to the modem and have their normal effect (if any). RANGES # > N specifies a range of phone numbers. # is defined as above, with the additional restriction that the rightmost character(s) of the phone number must be numeric (digits 0-9 only). The _tail_ of # is defined as its rightmost 6 (or fewer, if there aren't 6) digit characters. N, the _limit_, is a decimal integer. For example, this range: 1 408 555 1234 > 1296 has a tail of 1234, since that is the rightmost string of digits in the phone number that is preceded by a non-digit character (in this case, a space). The limit is 1296. When the program encounters a range, it dials the number re- peatedly, incrementing the tail by 1 each time until it equals the limit. Thus, the preceding range signifies all the numbers in succes- ion from 1 408 555 1234 to 1 408 555 1296. The limit may not have more digits than the tail. This range is illegal: 1 408 555 1234 > 51296 The limit may have fewer digits than the tail, in which case it is automatically padded with the corresponding digits from the tail, i.e., these two ranges are equivalent: 1 408 555 1234 > 96 1 408 555 1234 > 1296 The limit (after padding, if necessary) must be greater than or equal to the tail. So these (equivalent) ranges are illegal: 1 408 555 1234 > 1215 1 408 555 1234 > 15 PARAMETERS The program has three user-settable parameters. Each is given a value on a line of the dialling directory file. Parameter setting lines must contain an equal sign and may not contain any vertical bar characters (to distinguish them from dialing entry lines), nor begin with a period (which would make them a comment, and would also be illegal parameter syntax). MODEM SERIAL PORT NUMBER The serial port number, 1 or 2, must be specified on a line somewhere in the dialling directory file in this format: MODEM_SERIAL_PORT = <1 or 2> For example, MODEM_SERIAL_PORT = 1 DIALLING PREFIX By default, the string "ATDT" is prefixed to the phone number to make the command to send to the modem. A different dialling prefix may be specified, in this format: DIALLING_PREFIX = For example, this prefix dials 9 and waits two seconds for an outside line: DIALLING_PREFIX = ATDT 9, whereas this one specifies the use of pulse (rotary) instead of tone (push-button) dialling: DIALLING_PREFIX = ATDP BUSY/RING DECISION TIME After the program sends the dialling command to the modem, it waits a number of seconds to get a BUSY response. If none has been received by the time that interval ends, the program considers the phone to be ringing. This length of time is 5 seconds by default, but can be changed as follows: BUSY_RING_DECISION_TIME = For example, this line changes it to 10.5 seconds: BUSY_RING_DECISION_TIME = 10.5 COMMENTS AND BLANK LINES The dialling directory file can contain comment lines and blank lines to improve readability. These are displayed along with the entries, but are not otherwise acted upon by the program. Any line that begins with a period is treated as a comment. (Period is used instead of the usual semicolon or pound sign because the latter are permitted in phone numbers.) When displayed, the period is replaced by a space. Any line that contains no printable characters (i.e., contains only spaces and tabs, or no characters at all), is a blank line, and is also displayed, but has no other effect. Comment and blank lines can be used for separating one's dial- ling entries into meaningful groups for easier access. It can also be useful to temporarily deactivate a line by "commenting it out", i.e., putting a period at the beginning of it, for example to change easily among several different dialling prefixes that are kept in the file. DISPLAYS The program shows the selected entry and the number being dialed, as well as a prompt at the cursor, listing the avail- able user commands. For maximum compatibility between various screen modes and oper- ating systems, the display is operated in teletype style (scrol- ling up from the bottom) instead of random access. DEMO/TEST MODE If the modem does not respond to the initial "AT" command sent by the program (by answering "OK"), the program goes into Demo/Test mode for the duration of that execution. In that mode it functions as above except that it does not actually send any commands to the modem, and it pretends to receive a BUSY message from the modem after (not really) dialling each number. LIMITATIONS OF BUSY/RING DISCRIMINATION Because the Hayes modem command interface does not provide full call progress tracking, the program cannot fully differ- entiate between a busy, ringing, and answered phone. If the line is busy, the modem returns a "BUSY" message after three pulses of the busy tone (usually 3 seconds after dialing). However, it does not return a response when it hears the ring- ing tone, nor when the phone is answered (if it is), and it appears that there is no way to make it do so. Therefore it is impossible to differentiate with certainty between a phone that's not busy (i.e., is ringing or answered) and one that *is* busy, but hasn't yet returned three pulses of the busy tone (which may take a while with, e.g., some long-distance calls). The best that can be done is to set a time limit, for example 5 seconds, and if no BUSY message has been received by that time, the line is considered to be ringing, and the user is alerted. With this system, two types of problematic situations can arise: 1. If the phone system takes longer than the limit to sound 3 busy tones, the user will be told to pick up the phone, only to hear a busy signal after a few more seconds. In this case, the user should immediately hang up the phone, and dialling will continue. 2. If the remote phone rings and someone answers it quickly, they may say hello and begin waiting for the user to re- spond before the time limit is reached and the user is alerted that the line is ringing. Thus the person answer- ing may get annoyed, and may even hang up. To prevent this from occurring, the user can listen to the modem speaker, and pick up the phone as soon as he hears ringing. The disadvantage is that he will hear all the busy signals. A less certain, but less annoying, remedy is to pick up the phone the moment the alert sounds, and instantly say hello, in case someone is waiting. A short time limit may cause the first kind of problem, and a long one may cause the second kind. Even with a medium value, like 7 seconds, *both* types of problems may occur when calling to various phone systems. It may therefore prove useful, or even necessary, to alter the time limit for certain calling entries. This would be done by including an optional time value in seconds within the entry, or by including a parameter specification that would apply to the entries following it. This has not been implemented in the present version of the program. ABOUT ULTIMATE ENGINEERING Ultimate Engineering is a United States consulting firm located in San Jose, California. Ultimate Engineering is providing this program (source code included) free of charge. However, please leave all comments and this paragraph in all future revisions of Hunter. Ultimate Engineering is at http://www.ulti.com. ABOUT HUNTER Ultimate Engineering is working with the South East Asia Software Research Center (http://seasrc.th.net/) providing software tools. During my last trip, I noticed that many Central Offices do not provide "hunting". Therefore, a company with 50 phone lines, has 50 telephone numbers. Anyone calling the company would dial the numbers until a ringing line was located. Hunter was designed to help this problem. If anyone is interested in improving Hunter, such as a Windows 95 Port, please contact Bill Delveaux (billd@ulti.com). - - * - -