                                CyberPager

                Copyright  1993 by Christopher A. Wichura
                           All rights reserved.

LEGAL MUMBO JUMBO
=================

The CyberPager software is not in the public domain.  All source files, along
with the resulting executable, are copyright by C.  Wichura.  You many not
sell CyberPager.  The only allowed charge that may be placed on the CyberPager
software is for media and/or mailing costs.

The CyberPager software may be freely redistributed via BBSs,
InterNet/Usenet, and disk libraries such as Fred Fish's, as long as the
archive is not modified.  Disk magazines and services that charge extra for
file transfers may not distribute CyberPager.

In using the CyberPager software, you accept the responsibility for any
damage or loss of productivity/money that may occur through or during its
use.  C.  Wichura is not and cannot be held accountable.

QUICK DOCKS FOR CYBERPAGER
==========================

Please excuse the crude format of these docs.  I don't have a lot of free
time available these days, and so can not take the time to create a full
AmigaGuide doc file right now.  Sorry.

WHAT IT DOES
============

The CyberPager software allows one to send alpha-numeric pages from one's
Amiga.  This is accomplished by dialing into an IXO protocol compliant
pager central and uploading messages.

FEATURES
========

o   Aliases file allows for commonly paged people to be refered to by
    name rather than having to remember cryptic PIN numbers.

o   Groups file allows one to create "groups" allowing messages to
    be easily sent to many people working on the same project, in the
    same department, etc.

o   Supports multiple pager centrals through a Services configuration
    file.

o   Any number of messages can be spooled to disk to be uploaded in
    a single call to a service.

o   Automatically breaks long messages up into seperate pages.  Individual
    preferences for maximum message length can be set for each account
    listed in the aliases file.

o   Dialer supports multiple modems and knows how to hunt down a free
    modem in priority order.

o   Full logging of messages spooled, dialout attempts, etc.

o   Supports the OwnDevUnit.library method of locking serial devices,
    making the dialer compatible with mith Amiga UUCP, Welmat, and
    many major Amiga terminal programs.

SYSTEM REQUIREMENTS
===================

Any Amiga running AmigaDOS 2.0 or higher.
A Hayes compatible modem.
OwnDevUnit.library v2.1 or higher must be installed (v3.3 is included
    with this distribution for those that don't already have ODU)

Highly recommended:
	A hard drive
	A cron program (job scheduler) of some sort, such as CyberCron.

THEORY OF OPERATION
===================

The CyberPager software is comprised mainly of two programs: SpoolPage and
DialIXO.  Additional functionality can be provided by using various rexx
scripts to interface other applications to the CyberPager software.  A few
such scripts designed for use with Amiga UUCP are included.  Additionally,
a script to page a person currently on call given current system time is
also provided.  See the rexx/README file for more information on the rexx
scripts provided.

Messages are sent using the SpoolPage program.  SpoolPage is responsible
for figuring out who the message is going to, translating 8-bit characters
to 7-bit "best" equivalents (such as  -> a), breaking the message into
multiple pages (if needed), and finally spooling the message to disk.

Once a message has been spooled, the DialIXO program is used to actually
dial the pager central and upload all messages waiting for that service.
DialIXO knows how to scan the spool directory to see which services have
messages and will only dial out if it needs to deliver a message.

USING SPOOLPAGE
===============

SpoolPage understands the following arguments:

	TO/M/A,URGENT/S,LOGLEVEL/N/K,MESSAGE/F

    TO
	used to specify the person or persons the message is for.
	SpoolPage will first check to see if a name is listed in
	the groups file.  If it is, it will try sending the page
	to all people listed as part of that group.  If the name
	is not found in the groups file, the aliases file will be
	checked before an error is reported.

	messages can be spooled to people not in the aliases file
	by entering an address in the form of:

		<service name>:<pin number>

	where <service name> is the name of a service found in the
	services file and <pin number> is the pager number you
	want to send the page to.

    URGENT
	If specified, SpoolPage will try to start DialIXO after spooling
	the message to disk.  The ALWAYSURGENT flag in the config file
	can be used to force this option to always be on if desired.

    LOGLEVEL
	controls the level of log output.  Higher numbers give more
	output.  The current version of SpoolPage does not log
	much extra when a level higher than default is used, so
	this option is of dubious use at the moment.

    MESSAGE
	if the message keyword is given, everything following it on
	the command line will be interpreted as the text of the
	message to be sent.  if the message keyword is not given
	then SpoolPage will read the message text from it's standard
	input, allowing one to pipe messages into SpoolPage.

USING DIALIXO
=============

DialIXO understands the following arguments:

	SERVICE/K,MODEM/N/K,LOGLEVEL/N/K

    SERVICE
	limits DialIXO to only checking if work exists for the
	service listed.  Normally DialIXO tries to scan every
	service for work pending.

    MODEM
	allows one to specify a specific modem (as listed in the
	configuration file) to try and dial out on.  when a modem
	is specified, DialIXO will wait indefinately for the
	modem to become free.  If no modem is specified, or
	modem 0 is specified, DialIXO will try to hunt for a
	modem currently not in use.  If no modem is available,
	DialIXO will exit.

    LOGLEVEL
	similar to the LOGLEVEL option in SpoolPage.  If you are having
	trouble connecting to a service reliably, try using
	loglevel 5.  This will dump all packets received from the
	service into the log file and may aide you in determining
	why things are failing (assuming you know what IXO result
	packets are supposed to look like, of course... :->)  As of
	release 1.1, DialIXO at loglevel 4 or higher will now log
	each packet it is sending to the service as it uploads messages.

INSTALLING THE SOFTWARE
=======================

Make a directory where you want the pager software to be located.  Assign
PAGER: to this directory.  You'll also probably want to add this assign to
your user-startup (or however you handle assigns at boot time; I use
BindNames, for example).  Make a directory called libs in PAGER:.  Copy
the pager-support.library to this directory.

	NOTE!  pager-support.library should __NEVER__ be placed in your
	LIBS: directory.  SpoolPage and DialIXO expect it to be
	located in PAGER:libs!

Choose a place for the spool directory.  The software defaults to
PAGER:spool, however, this can be changed via an entry in the configuration
file.  Make the directory.  It is perfectly legal to point the spool
directory somewhere in RAM:.  However, if you do this, spooled pages not
delivered by DialIXO will be lost when the system reboots.

	IMPORTANT!  If the spool directory does not exist, the software
	WILL NOT BE ABLE TO SPOOL PAGES.

If you do not have OwnDevUnit.library installed on your system, copy it to
LIBS: (not PAGER:libs).

Now you need to edit the following files (see the sample files provided for
their format):

    PAGER:services
	describes the various services that you need to connect to.
	for each service, you need to indicate a name that it will be
	known by to the rest of the CyberPager software, the phone number
	to dial to connect to the service, the maximum baud rate the
	service operates at (1200 in most cases these days, although
	some are still limited to 300 and one or two support 2400),
	the maximum page size the service supports (call the technical
	support folks at your service to find this out -- in general,
	most services only support page sizes between 196-230 bytes,
	even though the IXO protocol supports an unlimited page size),
	and whether or not your service supports multi-block IXO packets
	(again, ask the tech support folks at your service -- in general,
	most services don't and if you turn on multiblock when the
	service doesn't support it then longer pages (>250 bytes) will
	get trashed).

    PAGER:aliases
	describes people you commonly send pages to.  for each alias, you
	need to indicate a name the person will be known by, the service
	that the person subscribes to (must be defined in the
	PAGER:services file), the PIN (pager identification number) of
	the person, the maximum message length (in bytes) that the person
	wishes to allow, and the max page size the person wishes to allow.

    PAGER:groups
	allows one to describe groups of people in the same department,
	etc., to easily send a single message to many people who it is
	of interest to.  see the sample groups file for information on
	how this file is set up.  if you don't plan to use any groups,
	removing this file will speed up SpoolPage's processing a tad.

    PAGER:config
	defines characteristics of your system, such as where the spool
	directory is located, where to place the logfile, etc.  most
	importantly, it defines the modem(s) to be used to dial out
	on.  see the config file for comments on the format of each
	entry type.  you MUST edit this file before you will be able to
	use DialIXO (as my modem settings don't use the built-in
	serial port).

Install the SpoolPage and DialIXO binaries somewhere in your search path.
I recommend placing them in PAGER:bin and adding PAGER:bin to your path.
This provides a consistant place for higher level scripts to find the
binaries in.  Note that both SpoolPage and DialIXO are pure, and thus can
be added to the resident list.

Once this is all done you should try sending yourself a page.  Suppose
the alias you created for yourself was called 'me'.  You'd run SpoolPage
with something like this:

	spoolpage me message this is a test

If spoolpage doesn't complain, try running DialIXO to actually deliver the
message to the service.  If all goes well, your pager should go off fairly
shortly thereafter.

Once you know that the software is installed properly and working, you
should probably look into adding a cron event that will run DialIXO
periodically to scan for any spool files waiting to be sent out.  I'd
recommend a fairly regular running of DialIXO with no specific modem
specified.  Then, at a less frequent interval, run DialIXO on a specific
modem so that it will block for it to come free.  This way, if you are
using all your modems when the hunt mode DialIXO is run, you will still
have a lock mode IXO come around every now and again that will wait
until you are done using one of your modems and upload all waiting pages
at that time.

NOTES ON NETWORK SUPPORT
========================

At this time, it is __NOT__ safe to have multiple machines share the same
spool directory (cross mounted from another machine).  The locking
mechanism used for files does not extend beyond the local machine.  Thus,
if you wish to use this in a networked environment, you must have all
'client' machines (i.e., the ones which DialIXO does not run on) rsh (or
whatever) SpoolPage on the pager server.

FUTURE PLANS
============

Workbench support (currently SpoolPage will quitely exit when started from
	Workbench, doing nothing).
Add in localization support.
Redo documentation as a texinfo file, allowing for beautiful hardcopy, an
	AmigaGuide file and a text file to be generated from the same
	doc file.
A nice GUI interface for this.  Won't happen until MUI comes along,
	though...

THANKS TO
=========

Mike Meyer for all is comments and beta testing, not to mention letting me
include the rexx scripts he wrote.

Brian Vargyas for getting me hooked on the alpha-numeric pager idea and not
going totally wild when I got side-tracked from this other project he
want's me to do in order to work on CyberPager... :-)

Nickey MacDonald for pointing out and helping track down a bug occuring
on V37 machines.

CONTACTING THE AUTHOR
=====================

If you happen to find a bug or have a suggestion for CyberPager, or just
want to say "hey, cool program", please contact me using one of the ways
listed below.  Even if you wanna say "CyberPager sucks", let me know and be
sure to say why you feel this way so that I might be able to fix what you
think is wrong with the program.

These electronic forms are the most prefered means of contacting me.  They
will get you a response pretty quick.

	e-mail: caw@miroc.chi.il.us
	BIX: caw

Snail Mail is pretty slow and I'm not known for being very good about
responding to it...  :-)

	Christopher A. Wichura
	5450 East View Park
	Chicago, Il.  60615
	USA

You can also reach me by phone.  However, please try to limit your calling
to evening hours (I'm in the central time zone).  If I'm not home and you
leave a message, call back again anyway.  Around here, one tends to get
maybe 5% of the messages left for them, if lucky...  :-)

	(312)/684-2941

HISTORY
=======

1.0
	Initial release

1.1	(7/10/93, SpoolPage v0.136, DialIXO v0.219, library v1.23)
	A bug in the checksum generator manifested itself when talking
	to services which are more strict about the IXO protocol.
	Many IXO services accept a space instead of a zero in the checksum.
	Some, like SkyTell, appear not to.  DialIXO now uses zeros per
	the IXO spec as written by Motorolla.

	Added a loglevel 4 entry to DialIXO that causes it to log the
	exact packet being sent to the service when uploading each
	page.

	Added a routine to intelligently add characters to the safe
	buffer (i.e., non-printable characters converted to escaped
	hex, etc, for display purposes).  DialIXO know displays
	special characters of the IXO protocol, such as ACK, NAK, STX,
	etc., as text rather than hex escape sequences to make
	tracing loglevel 5 output easier.

1.2	(7/20/93, SpoolPage v0.136, DialIXO v0.220, library v1.23)
	Found a bug that affected people running KickStart V37.  The
	wildcard mask DialIXO used to look for spool files would not
	find any that had a letter in them (i.e., 00000a as opposed
	to 000009 which would work).  This was due to the mask having
	the alpha range specified in lowercase.  V37 has a bug that
	doesn't uppercase alphabetic letters when a case-insensitive
	compare is being made.  By changing the mask to specify the
	alphabetics in uppercase, things now work properly on V37
	machines.  Thanks to Nickey MacDonald <i6t4@jupiter.sun.csd.unb.ca>
	for reporting this problem.
