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: : where is the name of a service found in the services file and 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). Finally, you must specify the password for the service. Most systems don't really make use of this, in which case you must use "1000000" as the password. The password is limited to 15 characters. The final option that must be specified in the services file is a flag that indicates if the service uses 8 data bits, no parity, 1 stop bit. The IXO specification states that IXO TAPs should be using 7E1. However, some services have started using 8N1, which will cause CyberPager to fail to connect. By setting this flag to Y, you will cause CyberPager to dial the service in 8N1 mode, rather than in 7E1. 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 for reporting this problem. 1.3 Greg Peck had a problem with the 1stPage service where it was sending out messages before ACKing the page (which the service is not supposed to do). CyberPager would report an "unknown packet" and resend the page. It would then see the ACK from the previous page. The end result was that he was getting each page twice. CyberPager no-longer resends the page on unknown packets, but rather continues to look for an ACK or NAK from the service. Related to this, I changed the log level of the "unknown packet" message to 2 (which is the same level as the "saw NAK, retrying" message) so that people in Greg's position wouldn't have their logfile explode due to the unknown packet messages being dumped into it for every page. 1.4 (2/7/94, SpoolPage v0.140, DialIXO v0.226, library v1.26) David Varley reported that his makes use of the password specification at login time. This is the first time I heard of any system actually making use of this, rather than always using the default '1000000'. I have modified the system to have a password field in the services file. For most systems, simply specifying "1000000" should suffice. Note: this change requires that you modify your services file to include a password field for each service, even if it is just "1000000". 1.5 (10/5/94, SpoolPage v0.144, DialIXO v0.230, library v1.27) Added Use8N1 field to services configuration file. The IXO protocol specification indicates that all IXO TAPs should use 7E1. Some newer services are now using 8N1, however. By setting this flag to "y", DialIXO will dial the service in 8N1 mode, instead of the default 7E1 mode. Note: this change requires that you modify your services file to include a Use8N1 field for each service. For most services, you should simply specify "n" to continue to use 7E1.