home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / alib / d9xx / d992 / cyberpager.lha / CyberPager / DOCUMENTATION < prev    next >
Text File  |  1994-04-05  |  16KB  |  399 lines
  1.                                 CyberPager
  2.  
  3.                 Copyright © 1993 by Christopher A. Wichura
  4.                            All rights reserved.
  5.  
  6. LEGAL MUMBO JUMBO
  7. =================
  8.  
  9. The CyberPager software is not in the public domain.  All source files, along
  10. with the resulting executable, are copyright by C.  Wichura.  You many not
  11. sell CyberPager.  The only allowed charge that may be placed on the CyberPager
  12. software is for media and/or mailing costs.
  13.  
  14. The CyberPager software may be freely redistributed via BBSs,
  15. InterNet/Usenet, and disk libraries such as Fred Fish's, as long as the
  16. archive is not modified.  Disk magazines and services that charge extra for
  17. file transfers may not distribute CyberPager.
  18.  
  19. In using the CyberPager software, you accept the responsibility for any
  20. damage or loss of productivity/money that may occur through or during its
  21. use.  C.  Wichura is not and cannot be held accountable.
  22.  
  23. QUICK DOCKS FOR CYBERPAGER
  24. ==========================
  25.  
  26. Please excuse the crude format of these docs.  I don't have a lot of free
  27. time available these days, and so can not take the time to create a full
  28. AmigaGuide doc file right now.  Sorry.
  29.  
  30. WHAT IT DOES
  31. ============
  32.  
  33. The CyberPager software allows one to send alpha-numeric pages from one's
  34. Amiga.  This is accomplished by dialing into an IXO protocol compliant
  35. pager central and uploading messages.
  36.  
  37. FEATURES
  38. ========
  39.  
  40. o   Aliases file allows for commonly paged people to be refered to by
  41.     name rather than having to remember cryptic PIN numbers.
  42.  
  43. o   Groups file allows one to create "groups" allowing messages to
  44.     be easily sent to many people working on the same project, in the
  45.     same department, etc.
  46.  
  47. o   Supports multiple pager centrals through a Services configuration
  48.     file.
  49.  
  50. o   Any number of messages can be spooled to disk to be uploaded in
  51.     a single call to a service.
  52.  
  53. o   Automatically breaks long messages up into seperate pages.  Individual
  54.     preferences for maximum message length can be set for each account
  55.     listed in the aliases file.
  56.  
  57. o   Dialer supports multiple modems and knows how to hunt down a free
  58.     modem in priority order.
  59.  
  60. o   Full logging of messages spooled, dialout attempts, etc.
  61.  
  62. o   Supports the OwnDevUnit.library method of locking serial devices,
  63.     making the dialer compatible with mith Amiga UUCP, Welmat, and
  64.     many major Amiga terminal programs.
  65.  
  66. SYSTEM REQUIREMENTS
  67. ===================
  68.  
  69. Any Amiga running AmigaDOS 2.0 or higher.
  70. A Hayes compatible modem.
  71. OwnDevUnit.library v2.1 or higher must be installed (v3.3 is included
  72.     with this distribution for those that don't already have ODU)
  73.  
  74. Highly recommended:
  75.     A hard drive
  76.     A cron program (job scheduler) of some sort, such as CyberCron.
  77.  
  78. THEORY OF OPERATION
  79. ===================
  80.  
  81. The CyberPager software is comprised mainly of two programs: SpoolPage and
  82. DialIXO.  Additional functionality can be provided by using various rexx
  83. scripts to interface other applications to the CyberPager software.  A few
  84. such scripts designed for use with Amiga UUCP are included.  Additionally,
  85. a script to page a person currently on call given current system time is
  86. also provided.  See the rexx/README file for more information on the rexx
  87. scripts provided.
  88.  
  89. Messages are sent using the SpoolPage program.  SpoolPage is responsible
  90. for figuring out who the message is going to, translating 8-bit characters
  91. to 7-bit "best" equivalents (such as ã -> a), breaking the message into
  92. multiple pages (if needed), and finally spooling the message to disk.
  93.  
  94. Once a message has been spooled, the DialIXO program is used to actually
  95. dial the pager central and upload all messages waiting for that service.
  96. DialIXO knows how to scan the spool directory to see which services have
  97. messages and will only dial out if it needs to deliver a message.
  98.  
  99. USING SPOOLPAGE
  100. ===============
  101.  
  102. SpoolPage understands the following arguments:
  103.  
  104.     TO/M/A,URGENT/S,LOGLEVEL/N/K,MESSAGE/F
  105.  
  106.     TO
  107.     used to specify the person or persons the message is for.
  108.     SpoolPage will first check to see if a name is listed in
  109.     the groups file.  If it is, it will try sending the page
  110.     to all people listed as part of that group.  If the name
  111.     is not found in the groups file, the aliases file will be
  112.     checked before an error is reported.
  113.  
  114.     messages can be spooled to people not in the aliases file
  115.     by entering an address in the form of:
  116.  
  117.         <service name>:<pin number>
  118.  
  119.     where <service name> is the name of a service found in the
  120.     services file and <pin number> is the pager number you
  121.     want to send the page to.
  122.  
  123.     URGENT
  124.     If specified, SpoolPage will try to start DialIXO after spooling
  125.     the message to disk.  The ALWAYSURGENT flag in the config file
  126.     can be used to force this option to always be on if desired.
  127.  
  128.     LOGLEVEL
  129.     controls the level of log output.  Higher numbers give more
  130.     output.  The current version of SpoolPage does not log
  131.     much extra when a level higher than default is used, so
  132.     this option is of dubious use at the moment.
  133.  
  134.     MESSAGE
  135.     if the message keyword is given, everything following it on
  136.     the command line will be interpreted as the text of the
  137.     message to be sent.  if the message keyword is not given
  138.     then SpoolPage will read the message text from it's standard
  139.     input, allowing one to pipe messages into SpoolPage.
  140.  
  141. USING DIALIXO
  142. =============
  143.  
  144. DialIXO understands the following arguments:
  145.  
  146.     SERVICE/K,MODEM/N/K,LOGLEVEL/N/K
  147.  
  148.     SERVICE
  149.     limits DialIXO to only checking if work exists for the
  150.     service listed.  Normally DialIXO tries to scan every
  151.     service for work pending.
  152.  
  153.     MODEM
  154.     allows one to specify a specific modem (as listed in the
  155.     configuration file) to try and dial out on.  when a modem
  156.     is specified, DialIXO will wait indefinately for the
  157.     modem to become free.  If no modem is specified, or
  158.     modem 0 is specified, DialIXO will try to hunt for a
  159.     modem currently not in use.  If no modem is available,
  160.     DialIXO will exit.
  161.  
  162.     LOGLEVEL
  163.     similar to the LOGLEVEL option in SpoolPage.  If you are having
  164.     trouble connecting to a service reliably, try using
  165.     loglevel 5.  This will dump all packets received from the
  166.     service into the log file and may aide you in determining
  167.     why things are failing (assuming you know what IXO result
  168.     packets are supposed to look like, of course... :->)  As of
  169.     release 1.1, DialIXO at loglevel 4 or higher will now log
  170.     each packet it is sending to the service as it uploads messages.
  171.  
  172. INSTALLING THE SOFTWARE
  173. =======================
  174.  
  175. Make a directory where you want the pager software to be located.  Assign
  176. PAGER: to this directory.  You'll also probably want to add this assign to
  177. your user-startup (or however you handle assigns at boot time; I use
  178. BindNames, for example).  Make a directory called libs in PAGER:.  Copy
  179. the pager-support.library to this directory.
  180.  
  181.     NOTE!  pager-support.library should __NEVER__ be placed in your
  182.     LIBS: directory.  SpoolPage and DialIXO expect it to be
  183.     located in PAGER:libs!
  184.  
  185. Choose a place for the spool directory.  The software defaults to
  186. PAGER:spool, however, this can be changed via an entry in the configuration
  187. file.  Make the directory.  It is perfectly legal to point the spool
  188. directory somewhere in RAM:.  However, if you do this, spooled pages not
  189. delivered by DialIXO will be lost when the system reboots.
  190.  
  191.     IMPORTANT!  If the spool directory does not exist, the software
  192.     WILL NOT BE ABLE TO SPOOL PAGES.
  193.  
  194. If you do not have OwnDevUnit.library installed on your system, copy it to
  195. LIBS: (not PAGER:libs).
  196.  
  197. Now you need to edit the following files (see the sample files provided for
  198. their format):
  199.  
  200.     PAGER:services
  201.     describes the various services that you need to connect to.
  202.     for each service, you need to indicate a name that it will be
  203.     known by to the rest of the CyberPager software, the phone number
  204.     to dial to connect to the service, the maximum baud rate the
  205.     service operates at (1200 in most cases these days, although
  206.     some are still limited to 300 and one or two support 2400),
  207.     the maximum page size the service supports (call the technical
  208.     support folks at your service to find this out -- in general,
  209.     most services only support page sizes between 196-230 bytes,
  210.     even though the IXO protocol supports an unlimited page size),
  211.     and whether or not your service supports multi-block IXO packets
  212.     (again, ask the tech support folks at your service -- in general,
  213.     most services don't and if you turn on multiblock when the
  214.     service doesn't support it then longer pages (>250 bytes) will
  215.     get trashed).  Finally, you must specify the password for the
  216.     service.  Most systems don't really make use of this, in which
  217.     case you must use "1000000" as the password.  The password is
  218.     limited to 15 characters.
  219.  
  220.     PAGER:aliases
  221.     describes people you commonly send pages to.  for each alias, you
  222.     need to indicate a name the person will be known by, the service
  223.     that the person subscribes to (must be defined in the
  224.     PAGER:services file), the PIN (pager identification number) of
  225.     the person, the maximum message length (in bytes) that the person
  226.     wishes to allow, and the max page size the person wishes to allow.
  227.  
  228.     PAGER:groups
  229.     allows one to describe groups of people in the same department,
  230.     etc., to easily send a single message to many people who it is
  231.     of interest to.  see the sample groups file for information on
  232.     how this file is set up.  if you don't plan to use any groups,
  233.     removing this file will speed up SpoolPage's processing a tad.
  234.  
  235.     PAGER:config
  236.     defines characteristics of your system, such as where the spool
  237.     directory is located, where to place the logfile, etc.  most
  238.     importantly, it defines the modem(s) to be used to dial out
  239.     on.  see the config file for comments on the format of each
  240.     entry type.  you MUST edit this file before you will be able to
  241.     use DialIXO (as my modem settings don't use the built-in
  242.     serial port).
  243.  
  244. Install the SpoolPage and DialIXO binaries somewhere in your search path.
  245. I recommend placing them in PAGER:bin and adding PAGER:bin to your path.
  246. This provides a consistant place for higher level scripts to find the
  247. binaries in.  Note that both SpoolPage and DialIXO are pure, and thus can
  248. be added to the resident list.
  249.  
  250. Once this is all done you should try sending yourself a page.  Suppose
  251. the alias you created for yourself was called 'me'.  You'd run SpoolPage
  252. with something like this:
  253.  
  254.     spoolpage me message this is a test
  255.  
  256. If spoolpage doesn't complain, try running DialIXO to actually deliver the
  257. message to the service.  If all goes well, your pager should go off fairly
  258. shortly thereafter.
  259.  
  260. Once you know that the software is installed properly and working, you
  261. should probably look into adding a cron event that will run DialIXO
  262. periodically to scan for any spool files waiting to be sent out.  I'd
  263. recommend a fairly regular running of DialIXO with no specific modem
  264. specified.  Then, at a less frequent interval, run DialIXO on a specific
  265. modem so that it will block for it to come free.  This way, if you are
  266. using all your modems when the hunt mode DialIXO is run, you will still
  267. have a lock mode IXO come around every now and again that will wait
  268. until you are done using one of your modems and upload all waiting pages
  269. at that time.
  270.  
  271. NOTES ON NETWORK SUPPORT
  272. ========================
  273.  
  274. At this time, it is __NOT__ safe to have multiple machines share the same
  275. spool directory (cross mounted from another machine).  The locking
  276. mechanism used for files does not extend beyond the local machine.  Thus,
  277. if you wish to use this in a networked environment, you must have all
  278. 'client' machines (i.e., the ones which DialIXO does not run on) rsh (or
  279. whatever) SpoolPage on the pager server.
  280.  
  281. FUTURE PLANS
  282. ============
  283.  
  284. Workbench support (currently SpoolPage will quitely exit when started from
  285.     Workbench, doing nothing).
  286. Add in localization support.
  287. Redo documentation as a texinfo file, allowing for beautiful hardcopy, an
  288.     AmigaGuide file and a text file to be generated from the same
  289.     doc file.
  290. A nice GUI interface for this.  Won't happen until MUI comes along,
  291.     though...
  292.  
  293. THANKS TO
  294. =========
  295.  
  296. Mike Meyer for all is comments and beta testing, not to mention letting me
  297. include the rexx scripts he wrote.
  298.  
  299. Brian Vargyas for getting me hooked on the alpha-numeric pager idea and not
  300. going totally wild when I got side-tracked from this other project he
  301. want's me to do in order to work on CyberPager... :-)
  302.  
  303. Nickey MacDonald for pointing out and helping track down a bug occuring
  304. on V37 machines.
  305.  
  306. CONTACTING THE AUTHOR
  307. =====================
  308.  
  309. If you happen to find a bug or have a suggestion for CyberPager, or just
  310. want to say "hey, cool program", please contact me using one of the ways
  311. listed below.  Even if you wanna say "CyberPager sucks", let me know and be
  312. sure to say why you feel this way so that I might be able to fix what you
  313. think is wrong with the program.
  314.  
  315. These electronic forms are the most prefered means of contacting me.  They
  316. will get you a response pretty quick.
  317.  
  318.     e-mail: caw@miroc.chi.il.us
  319.     BIX: caw
  320.  
  321. Snail Mail is pretty slow and I'm not known for being very good about
  322. responding to it...  :-)
  323.  
  324.     Christopher A. Wichura
  325.     5450 East View Park
  326.     Chicago, Il.  60615
  327.     USA
  328.  
  329. You can also reach me by phone.  However, please try to limit your calling
  330. to evening hours (I'm in the central time zone).  If I'm not home and you
  331. leave a message, call back again anyway.  Around here, one tends to get
  332. maybe 5% of the messages left for them, if lucky...  :-)
  333.  
  334.     (312)/684-2941
  335.  
  336. HISTORY
  337. =======
  338.  
  339. 1.0
  340.     Initial release
  341.  
  342. 1.1    (7/10/93, SpoolPage v0.136, DialIXO v0.219, library v1.23)
  343.     A bug in the checksum generator manifested itself when talking
  344.     to services which are more strict about the IXO protocol.
  345.     Many IXO services accept a space instead of a zero in the checksum.
  346.     Some, like SkyTell, appear not to.  DialIXO now uses zeros per
  347.     the IXO spec as written by Motorolla.
  348.  
  349.     Added a loglevel 4 entry to DialIXO that causes it to log the
  350.     exact packet being sent to the service when uploading each
  351.     page.
  352.  
  353.     Added a routine to intelligently add characters to the safe
  354.     buffer (i.e., non-printable characters converted to escaped
  355.     hex, etc, for display purposes).  DialIXO know displays
  356.     special characters of the IXO protocol, such as ACK, NAK, STX,
  357.     etc., as text rather than hex escape sequences to make
  358.     tracing loglevel 5 output easier.
  359.  
  360. 1.2    (7/20/93, SpoolPage v0.136, DialIXO v0.220, library v1.23)
  361.     Found a bug that affected people running KickStart V37.  The
  362.     wildcard mask DialIXO used to look for spool files would not
  363.     find any that had a letter in them (i.e., 00000a as opposed
  364.     to 000009 which would work).  This was due to the mask having
  365.     the alpha range specified in lowercase.  V37 has a bug that
  366.     doesn't uppercase alphabetic letters when a case-insensitive
  367.     compare is being made.  By changing the mask to specify the
  368.     alphabetics in uppercase, things now work properly on V37
  369.     machines.  Thanks to Nickey MacDonald <i6t4@jupiter.sun.csd.unb.ca>
  370.     for reporting this problem.
  371.  
  372. 1.3
  373.     Greg Peck had a problem with the 1stPage service where it was
  374.     sending out messages before ACKing the page (which the service
  375.     is not supposed to do).  CyberPager would report an "unknown
  376.     packet" and resend the page.  It would then see the ACK from
  377.     the previous page.  The end result was that he was getting
  378.     each page twice.  CyberPager no-longer resends the page on
  379.     unknown packets, but rather continues to look for an ACK or NAK
  380.     from the service.  Related to this, I changed the log level
  381.     of the "unknown packet" message to 2 (which is the same level
  382.     as the "saw NAK, retrying" message) so that people in Greg's
  383.     position wouldn't have their logfile explode due to the
  384.     unknown packet messages being dumped into it for every page.
  385.  
  386. 1.4
  387.     (2/7/94, SpoolPage v0.140, DialIXO v0.225, library v1.25)
  388.     David Varley reported that his makes use of the password
  389.     specification at login time.  This is the first time I heard
  390.     of any system actually making use of this, rather than always
  391.     using the default '1000000'.  I have modified the system to
  392.     have a password field in the services file.
  393.  
  394.     For most systems, simply specifying "1000000" should suffice.
  395.  
  396.     Note:  this change requires that you modify your services file
  397.     to include a password field for each service, even if it is
  398.     just "1000000".
  399.