Sound Sensations!/sound_sensations.iso/voice/ringbck2/ringback.doc

Text File | 1990-09-30 | 23.9 KB | 605 lines

Subject: Documentation
Topic:   Ring*Back v1.1
Date:    29-Sept-90



OVERVIEW:
---------
Ring*Back -- Communications "Front-end" module for use with BBS or other data
telecommunications software that enables both voice and data operations to
exist on a shared (single) telephone line.

This software also may be used to provide RS232 Pin 22 Ring Detect/Answer
capability to data telecommunications software which do not have this
capability or as a stand-alone system to answer data calls at times when
normal BBS operations are unavailable (i.e., during periods of routine
maintenance or system malfunction.).

Full communications port and modem support, as well as, techniques for
communicating a data caller's Baud rate and communications port in use
information to subordinate software is provided.



SYSTEM REQUIREMENTS:
-------------------
IBM(R) PC or compatible
PC/MS-DOS(R) v2.0 or later
Asynchronous communications (Aka: serial port, "COM" port)  [COM1 or COM2]
RS232 cable with pin 22 connected
Intelligent AT command set modem (Aka: "Hayes(R) compatible" modem)
ANSI.SYS ANSI Driver


USAGE:
------

   RINGBACK [mode]

   Where:  [mode] = "DIRECT" or "RING-BACK"

The single command line argument [mode] is MANDITORY and must appear at
run-time.  There are no default settings.



DIRECT MODE OPERATIONS:
-----------------------
Example:  Ringback DIRECT

Setting [mode] = DIRECT selects "Direct Mode" operations.  In this operations
mode, all incoming calls are treated as "Data" calls and the modem will go
on-line in answer mode (sends ATA to modem) after the first ring is detected.



RING-BACK MODE OPERATIONS:
--------------------------
Example:  Ringback RING-BACK

Setting [mode] = RING-BACK selects "Ring-Back Mode" operations.  This
operations mode allows both "Voice" and "Data" service to share a common
telephone line.

When "Ring-Back Mode" operations are active, the number and timing of the
incoming telephone call rings is monitored.  If 3 or more rings occure in
sequence with no timing gap between rings, then it is assumed that the call is
a "Voice" call and the software does nothing.  The call may then be answered
manually or a "Telephone Answering Machine" may be employed to take the call.
If a "Telephone Answering Machine" is used, it should be configured to answer
on a later ring, the 4th for example.

If only 1 or 2 rings are detected followed by a timing gap, then it is
assumed that the NEXT call will be a "Data" call and the software waits for a
specified time period (called the "Ring-Back Window").  If a ring occures
within the "Ring-Back Window" period then the software instructs the modem to
answer the call as a "Data" call.  If no ring is detected within the
"Ring-Back Window" period, the software recycles and awaits another call at
which point the process begins anew.

The values for the "Ring-back Window" period (as well as other operations
parameters) are defined in the configuration file "Ringback.Cfg".



CONFIGURATION FILE -- "RINGBACK.CFG":
------------------------------------
The configuration file "Ringback.Cfg" is an ASCii text file which defines the
operational parameters for the software.  This file must exist and be
available to the program Ring*Back at run-time -- there are NO default
settings.  This file may be edited using any ASCii text editor.  A sample is
provided.

The following illustrates the format of "Ringback.Cfg":

[------------------ TOP OF ASCII FILE "RINGBACK.CFG" ------------------------]
8
60
com1
8
2400
AT Q0 V0 M0 E0 X4 S2=255 &C1 &D2 &W
0
1
5
10
1000
Loading BBS.  Please wait ...
[------------------ END OF ASCII FILE "RINGBACK.CFG" --------------------------]

Notes: ALL lines must exist in the order shown.
       The first line must begin at the top of the file.
       Each line must begin at the left-most vertical position.
       All trailing white-space characters should be stripped from each line.
       Line entries are case insensitive.
       Modem result codes MUST be in "Short Form/Numeric" format.
       The first 11 lines are manditory.
       The 12th (last) line is optional.


LINE 1 -- RING-BACK WINDOW BEGIN TIME (SECONDS)
Define the minimum ring interval time.  Although ring intervals vary between
telephone systems, an interval of more than eight (8) seconds between rings
(usually) indicates that the caller has "hung-up".  Therefore, this value
should be set to a value equal to or greater than 8 seconds.


LINE 2 -- RING-BACK WINDOW END TIME (SECONDS)
Define the maximum time allowed for a data caller to re-dial your number
("Ring-back").  Values between 30 and 120 seconds are common.


LINE 3 -- COM PORT TO USE
Define the "COM" port to use.  Must be either "COM1" or "COM2".


LINE 4 -- COMMUNICATIONS PROTOCOL
Define the "Data Bits" to use.  Must be either "7" for 7-E-1 operations
or "8" for 8-N-1 operations.  (Parity and Stop Bit values can not be altered.)


LINE 5 -- INITIALIZATION BAUD RATE
Define the Baud rate to initialize the BBS's modem.  This is usually set to
the highest Baud rate supported by the modem.


LINE 6 -- MODEM INITIALIZATION STRING
Define the modem initialization (AT command) string.  128 characters maximum.
Although initialization strings will vary from modem-to-modem, for proper
operation the following settings are recommended for all installations:

 1 ... Enable result codes (Quiet command).  (Q0)
 2 ... Enable "Short Form/Numeric" result codes.  (V0)
 3 ... Enable "Extended" result codes.  (X#)
 4 ... Disable character echo.  (E0)

 E.g.:  AT Q0 V0 X4 E0 ...
 (See your modem's documentation for futher instructions.)

In the event of modem initialization problems, it may be necessary to
incorporate a third party utility (e.g., "DosModem", et al.) to initialize the
modem prior to every invocation Ring*Back.  (This is especially true for older
or "off-brand" modems.)  If a third party utility is used to initialize the
modem then, line #6 of Ringback.Cfg should be set to "AT Z".

Also, some (perhaps most) modems may only accept 40 characters per
initialization command line.


IMPORTANT: LINES 7-THRU-11 MUST USE "SHORT FORM/NUMERIC" FORMAT RESULT CODES!
                           ~~~~

LINE 7 -- COMMAND ACCEPTED RESULT CODE:
Define the result code returned by the modem to indicate that the
initialization (AT command) string has been accepted.  This is usually "0"
(representing "OK").

Beginning with version 1.1, Ring*Back will check if the modem received the
initialization string correctly.  Ring*Back will make 3 attempts to verify
that the initialization string was accepted by the modem.  If after the third
attempt the modem does not respond with the result code defined in Line #7 of
Ringback.Cfg, Ring*Back will assume that the modem is initialized properly and
continue.

As a safeguard, if after 3 attempts the "Command Accepted" result code is not
returned by the modem a warning message will be issued.  The display of the
warning message does not mean that the modem is not correctly initialized, only
that the "Command Accepted" result code has not been intercepted by Ring*Back.
(See the recommended initializaiton (AT command) string settings for line #6.)


LINES 8-THRU-11 -- MODEM BAUD RATE RESULT CODES:
Define the modem result codes returned for 300, 1200, 2400 and 9600 Baud,
respectively.  If the modem used does not support a specific Baud rate, simply
set that line to a undefined value.  In the example above, the 9600 Baud rate
is not supported and has been set to an undefined value of 1000


LINE 12 -- OPTIONAL EXIT MESSAGE LINE
Define line of text to send when RING*BACK exits to load BBS.  80 characters
maximum.



INTERFACING RING*BACK WITH BBS SOFTWARE:
----------------------------------------
When loaded, Ring*Back simply waits for the phone to ring.  When a "Data" call
is connected, Ring*Back preforms several tasks before it hands control over to
the BBS software.

The first task Ring*Back preforms is to re-program the communications port to
the caller's Baud rate.  Therefore, if the BBS software that is being loaded
can adopt the current communications port parameters directly, all that need
be done is load the BBS software when Ring*Back exits via a DOS batch file.

However, since most BBS software do not provide this capability, Ring*Back
provides two (2) means for communicating the caller's Baud rate to the BBS
software.  The method used will be determined by the installer's personal
preference and the BBS software used.

COMMUNICATING BAUD RATE BY ERRORLEVEL TRAPPING:
-----------------------------------------------
When Ring*Back removes itself from computer memory it exits to DOS with a
pre-defined ErrorLevel value.  These ErrorLevel values can be "Trapped" via a
DOS batch file.

When the "Local Test" option is issued from the local consol ([RETURN] key
pressed), Ring*Back exits to DOS with an ErrorLevel value = 0.

When a request to "Exit to DOS" is issued from the local consol ([ESC] key
pressed), "Ring*Back" exits to DOS with an ErrorLevel value = 255.

When Ring*Back exits to DOS with a caller on-line the ErrorLevel value is set
to the caller's Baud rate divided by 100.  For example; if a 300 Baud caller
is on-line then Ring*Back exits with an ErrorLevel = 3.  Likewise, for 1200
Baud the ErrorLevel = 12, for 2400 Baud the ErrorLevel = 24 and for 9600 Baud
the ErrorLevel = 96.


"ErrorLevel Trapping" Batch File Example:
-----------------------------------------
Ringback DIRECT
if errorlevel = 255 goto end
if errorlevel = 96 goto 9600baud
if errorlevel = 24 goto 2400baud
if errorlevel = 12 goto 1200baud
if errorlevel = 3 goto 300baud
if errorlevel = 0 goto local

:9600baud
REM Load batch file to load BBS at 9600 Baud
Load9600.Bat

:2400baud
REM Load batch file to load BBS at 2400 Baud
Load2400.Bat

:1200baud
REM Load batch file to load BBS at 1200 Baud
Load1200.Bat

:300baud
REM Load batch file to load BBS at 300 Baud
Load300.Bat

:local
REM Load batch file to load BBS in local mode
Local.Bat

:end
REM exit to DOS
----------------------------------------


COMMUNICATING BAUD RATE BY REPLACEABLE BATCH FILE PARAMETERS:
-------------------------------------------------------------
When Ring*Back removes itself from computer memory with a caller on-line it
also writes to disk a special batch file named "Loadbbs.Bat".  This batch file
may used to communicate the caller's Baud rate and the active communications
port via "Replaceable Batch File Parameters" to another batch file which,
inturn, loads the BBS.


Batch File Example using Loadbbs.Bat:
-------------------------------------
Ringback DIRECT
if errorlevel = 255 goto end
if errorlevel = 96 goto load
if errorlevel = 24 goto load
if errorlevel = 12 goto load
if errorlevel = 3 goto load
if errorlevel = 0 goto local

:load
REM Load batch file "LoadBBS.Bat"
Loadbbs.Bat

:local
REM Load batch file to load BBS in local mode
Local.Bat

:end
REM exit to DOS
----------------------------------------


The batch file "Loadbbs.Bat" is created by Ring*Back and contains only one
line of text in the following format:

     BBSBATCH [baud] [port]

     Where:    BBSBATCH invokes the DOS batch file "Bbsbatch.Bat"
               [baud] is the caller's Baud rate
               [port] is the active communications port number
               ("1" or "2" representing COM1 and COM2, respectively.)

     Example:  BBSBATCH 2400 1

NOTE: The files "Loadbbs.Bat" and "Bbsbatch.Bat" are a system reserved
      filenames.  "Loadbbs.Bat" is overwritten each time a "Data" caller
      connects.  "Bbsbatch.Bat" is simply the DOS batch file used to load the
      BBS software.

When "Loadbbs.Bat" is called from the start-up batch file it immediately calls
the batch file "Bbsbatch.Bat" with the command line arguments of [baud] and
[port], respectively.  In this way, the values for [baud] and/or [port] can be
transferred to the BBS software thru the use of replaceable batch file
parameters.

A simple example of the contents of Bbsbatch.Bat for a Wildcat! BBS might be:

    Wildcat /b %1

Where the Baud rate is being passed by the replaceable batch file
parameter "%1".

The sample batch files "Start.Bat" and "Bbsbatch.Bat" should provide ample
illustration of how this method works.



BANNER.BBS:  (OPTIONAL)
-----------------------
If found, the optional ASCii text file "Banner.Bbs" will be displayed to the
caller immediately after the connection is established.  This file may be used
to welcome callers to your system.

Although this file may be any length, it is wise to keep this message brief as
the caller's screen page length is unknown.



SCHEDULE OF EVENTS FILE -- "RINGBACK.EVT"  (OPTIONAL):
-----------------------------------------------------
The Schedule of Events file "Ringback.Evt" is an ASCii text file which defines
the TIME and DAY for Ring*Back to automatically remove itself from computer
memory and exit to DOS with a specified ErrorLevel value.  The ErrorLevel
value issued for the event is assigned by the system operator and may be
trapped via a DOS batch file to perform any task the system operator desires.

This feature is provided primarily as a means to automatically switch between
"Ring-Back" and "Direct' operation modes according to a predefined schedule.
Creative minds will find many other uses for this feature as well.  (E.g.:
automatic execution of system maintenance routines, loading of alternate
front-end "Mailer" programs, etc.)

"Ringback.Evt" is optional and if it is not found Ring*Back will operate
normally.  This file may be created using any ASCii text editor.  A sample is
provided.

Each line in Ringback.Evt must have the following format with a Space
seperating each parameter:

   [time] [day] [errorlevel]

Where:

   [time] = 00:00 - 23:59

   [day] = "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun", "All", or "M-F".

   [errorlevel] = Any valid DOS errorlevel value between 0 & 255, excluding
                  the system reserved errorlevels: 0, 3, 12, 24, 96 and 255.

Example:
Note: The first line in Ringback.Evt must begin at the top of the file.
      There must be no blank lines between entries.

[------------------ TOP OF ASCII FILE "RINGBACK.EVT" ------------------------]
07:15 sun 4
08:00 m-f 1
08:00 sat 1
13:00 sat 2
17:35 m-f 2
23:59 all 5
[------------------ END OF ASCII FILE "RINGBACK.EVT" ------------------------]

Ringback.Evt may contain as many event lines as required.  However, the lines
MUST appear in TIME sequence from earliest-to-latest.  Ring*Back will use the
FIRST [time] value it encounters that is greater than current system time when
the current system day correspondes to the [day] parameter.

The [day] parameter is case insensitive.  In addition to the individual days
of the week parameters, two additional parameters "All" and "M-F" are
provided. These parameters will schedule events for "All days (Sun-thru-Sat)"
and "Mon-thru-Fri Only", respectively.

To avoid scheduling conflicts and potential errors in event processing, event
tasks should be longer than 1 minute in duration.  If a task is shorter than 1
minute, a suitable delay timer (e.g., "Wait!", et al.) should be employed to
lengthen the task's duration.  If Ring*Back operation is to be reinstated
after a task, Ring*Back must be reinvoked by the task upon completion.

Ring*Back stores the next event parameters in the file "Ringback.Nxt".  Each
time Ring*Back is invoked it will check this file for an overdue event.  If an
overdue event is found, Ring*Back will run it.  In this way, if a caller is
on-line during an event time, Ring*Back will run that event as soon as the
caller disconnects and Ring*Back is reinvoked.  This method eliminates the
need to ban callers from access prior to the running of an event.

Note:
Ring*Back will only recognize events scheduled for the current day.  Therfore,
one should exercise caution when events are scheduled near the end of the day.
If an event is scheduled before midnight and then becomes overdue, it will be
missed if Ring*Back is reinvoked after the midnight clock roll-over.  In these
cases it would be best to re-schedule the event to after midnight.  (E.g., an
event scheduled for 00:00 is preferred to one scheduled for 23:59)



CONSOL COMMANDS:
----------------

  [SPACE BAR] .... Display Menu screen

  [RETURN] ....... Local Text (Exit with ErrorLevel=0)

  [ESC] .......... Exit to DOS (Exit with ErrorLevel=255)

  [R] ............ Toggle "Ring-Back" operation mode ON.

  [D] ............ Toggle "Direct" operation mode ON.

  [C] ............ View Active Configuration (As set in Ringback.Cfg)

  [I] ............ Initialize  (Send COM Port and Modem retrain sequence)

Please note that the Menu display automatically erases itself after 10
seconds.  This feature is provided to prevent screen "Burn-In".  Consol
commands are accepted at any time while Ring*Back is in its wait state (i.e.,
the Menu screen is only provided as a reference and need not be displayed to
enter commands.)

It is often desirable to TEMPORARILY switch between "Ring-Back" and "Direct"
operation modes on the fly.  Pressing the [R] or [D] keys at anytime will
select "Ring-Back" or "Direct" operation modes, respectively.  The active
operation mode is displayed at the top of the Menu screen.

Note:
Please be aware that the operation mode toggle will only remain in effect
until the next "Data" call is received.  The start-up operations mode (which
is defined on the command line at run-time) remains in effect.  A permanent
change in operations mode can only be accomplished via the [mode] command line
argument.

Pressing the [C] key provides an easy means to verify that the configuration
file is loaded correctly.

Pressing the [I] key will recycle the communications port and modem
initialization retrain sequence.  This is preformed automatically during
program start-up and after every 10 minutes of program inactivity.


NOTES & RECOMMENDATIONS:
------------------------
Ring*Back monitors the status of RS232 Pin 22 (RI) on the modem connector.
Therefore, it is important that the modem is set so that it does NOT answer
the phone (i.e., Auto Answer OFF, s0=0).  In addition, pin 22 must be
connected on the modem cable.

It is often desirable to offer "Ring-Back" service during certain times and
"Direct" (Data only) services during other times.  It is for this reason the
operations mode is defined on the command line at run-time.  It is a simple
matter of calling different start-up batch files at different times of the day
to change the operations mode.  This can be easily automated using the
"Schedule of Events" feature.

All messages prefixed with "=>" are only displayed to the local consol.
These messages are provided as system status indicators.

The Errorlevel values of 0 and 255 should always be trapped via a DOS batch
file to implement the "Local Test" and "Exit to Dos" functions, respectively.

If an ErrorLevel value less than 0 is displayed by Ring*Back, check that a
valid communications port ("com1" or "com2" only) is being addressed and that
the modem is operating correctly.  Negative ErrorLevel values indicate a
configuration or system (hardware) error and should be treated accordingly.

When a caller disconnects from the BBS, the BBS software must remove itself
from computer memory and the start-up batch file used to load Ring*Back must
be reinvoked.  The start-up batch file should also be called from the
"Autoexec.Bat" batch file to automatically reload Ring*Back in the event of a
power failure.

For added security, DTR is toggled OFF/ON each time Ring*Back is invoked.
This feature provides a reliable, alternate means for disconnecting callers.

As a safeguard, Ring*Back will attempt to verify that each connection is
adequate for telecommunications.  If carrier (DCD) is lost or flutters during
the first 3 seconds after a connection is established, Ring*Back will
automatically disconnect the caller and recycle.

Most problems with Ring*Back are the result of problems with the configuration
file "Ringback.Cfg" or with the batch files used to load the software or the
BBS.  If you experience problems, check these files and review this
documentation for insturctions.  Also see your BBS's software documentation
for interface instructions.  The instructions provided for installation of
"NetMail" front-end programs should be followed.  In addition, files such as
"Ringback.Cfg" and "Ringback.Evt" should be edited with an ASCii text editor
that strips trailing white-space characters.


LICENSED vs DEMONSTRATION VERSIONS
----------------------------------
This version of Ring*Back is the complete version.  You may operate this
software in "DEMO Mode" to evaluate this software's suitability to your
application on your equipment.  This software may be tested for one month.
After one month, the software may not be used unless a "License to Use" is
purchased.

The following differences exist between "Licensed" and "DEMO Mode" operation
of Ring*Back:

                            LICENSED             DEMO Mode
----------------------+----------------+------------------------------------
LICENSING MESSAGE:    | Not displayed  | Displayed to local & remote screens
----------------------+----------------+------------------------------------
DELAY TIMER:          | Bypassed       | 10 seconds
----------------------+----------------+------------------------------------

When you license your copy of Ring*Back you will receive instructions for
removing the DEMO Mode restrictions.

To obtain a license you must provide the following:

 1 ... Purchaser's Name.

 2 ... Mailing Address.

 3 ... BBS NAME.  This information must be EXACTLY as you want it to appear on
       your license including all spacing, upper and lowercase letters,
       symbols, etc.  60 characters maximum.  This information is displayed
       immediately following the Ring*Back identification line.

 4 ... BBS telephone number(s).

 5 ... $15.00 check or money order (U.S. funds) payable to "D. Owen Mayes".


Mail orders to:

    D. Owen Mayes
    P.O. Box 5025
    Bisbee, AZ 85603 USA


For your convenience, an order form (filename "Form.Txt") is included with
this package.



DISTRIBUTION, LICENSING, COPYRIGHT, RESTRICTIONS & WARRANTIES:
-------------------------------------------------------------
Ring*Back may be distributed without restriction provided no modification,
addition or deletion is made to this package or any associated file and it is
distributed independent of any other software.

Licensed versions of Ring*Back provide the purchaser a license authorizing the
"Right to Use" the software on a single host computer.  Use of the software on
hosts supporting multiple nodes is permitted provided all nodes reside at the
same physical location.  If the software is to be used at any location other
than that for which the license is issued, additional licenses for the
software must be purchased for each additional location.  Licenses are
non-transferable.

COPYRIGHT.  Ring*Back is owned by D. Owen Mayes and is protected by United
States copyright laws and international treaty provision.

OTHER RESTRICTIONS.  You may not rent or lease the software.  You may not
reverse engineer, decompile, or disassemble the software.

WARRANTIES.  This software is without warranty of any kind.  The user assumes
sole responsibility for its use, and it is the user's responsibility to
determine if this software is suitable for the application intended.
The software's author shall not be liable or responsible for any damages,
including special, indirect, or consequential damages, arising or resulting
from the use of or modification of this software.  The sole liability shall be
limited to a court authorized refund of the licensing fee.


This document supersedes all previous documents.  Revision date: 29-Sept-90