home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 2: PC / frozenfish_august_1995.bin / bbs / d09xx / d0907.lha / CyberPager / DOCUMENTATION < prev    next >
Text File  |  1993-08-28  |  14KB  |  353 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).
  216.  
  217.     PAGER:aliases
  218.     describes people you commonly send pages to.  for each alias, you
  219.     need to indicate a name the person will be known by, the service
  220.     that the person subscribes to (must be defined in the
  221.     PAGER:services file), the PIN (pager identification number) of
  222.     the person, the maximum message length (in bytes) that the person
  223.     wishes to allow, and the max page size the person wishes to allow.
  224.  
  225.     PAGER:groups
  226.     allows one to describe groups of people in the same department,
  227.     etc., to easily send a single message to many people who it is
  228.     of interest to.  see the sample groups file for information on
  229.     how this file is set up.  if you don't plan to use any groups,
  230.     removing this file will speed up SpoolPage's processing a tad.
  231.  
  232.     PAGER:config
  233.     defines characteristics of your system, such as where the spool
  234.     directory is located, where to place the logfile, etc.  most
  235.     importantly, it defines the modem(s) to be used to dial out
  236.     on.  see the config file for comments on the format of each
  237.     entry type.  you MUST edit this file before you will be able to
  238.     use DialIXO (as my modem settings don't use the built-in
  239.     serial port).
  240.  
  241. Install the SpoolPage and DialIXO binaries somewhere in your search path.
  242. I recommend placing them in PAGER:bin and adding PAGER:bin to your path.
  243. This provides a consistant place for higher level scripts to find the
  244. binaries in.  Note that both SpoolPage and DialIXO are pure, and thus can
  245. be added to the resident list.
  246.  
  247. Once this is all done you should try sending yourself a page.  Suppose
  248. the alias you created for yourself was called 'me'.  You'd run SpoolPage
  249. with something like this:
  250.  
  251.     spoolpage me message this is a test
  252.  
  253. If spoolpage doesn't complain, try running DialIXO to actually deliver the
  254. message to the service.  If all goes well, your pager should go off fairly
  255. shortly thereafter.
  256.  
  257. Once you know that the software is installed properly and working, you
  258. should probably look into adding a cron event that will run DialIXO
  259. periodically to scan for any spool files waiting to be sent out.  I'd
  260. recommend a fairly regular running of DialIXO with no specific modem
  261. specified.  Then, at a less frequent interval, run DialIXO on a specific
  262. modem so that it will block for it to come free.  This way, if you are
  263. using all your modems when the hunt mode DialIXO is run, you will still
  264. have a lock mode IXO come around every now and again that will wait
  265. until you are done using one of your modems and upload all waiting pages
  266. at that time.
  267.  
  268. NOTES ON NETWORK SUPPORT
  269. ========================
  270.  
  271. At this time, it is __NOT__ safe to have multiple machines share the same
  272. spool directory (cross mounted from another machine).  The locking
  273. mechanism used for files does not extend beyond the local machine.  Thus,
  274. if you wish to use this in a networked environment, you must have all
  275. 'client' machines (i.e., the ones which DialIXO does not run on) rsh (or
  276. whatever) SpoolPage on the pager server.
  277.  
  278. FUTURE PLANS
  279. ============
  280.  
  281. Workbench support (currently SpoolPage will quitely exit when started from
  282.     Workbench, doing nothing).
  283. Add in localization support.
  284. Redo documentation as a texinfo file, allowing for beautiful hardcopy, an
  285.     AmigaGuide file and a text file to be generated from the same
  286.     doc file.
  287. A nice GUI interface for this.  Won't happen until MUI comes along,
  288.     though...
  289.  
  290. THANKS TO
  291. =========
  292.  
  293. Mike Meyer for all is comments and beta testing, not to mention letting me
  294. include the rexx scripts he wrote.
  295.  
  296. Brian Vargyas for getting me hooked on the alpha-numeric pager idea and not
  297. going totally wild when I got side-tracked from this other project he
  298. want's me to do in order to work on CyberPager... :-)
  299.  
  300. CONTACTING THE AUTHOR
  301. =====================
  302.  
  303. If you happen to find a bug or have a suggestion for CyberPager, or just
  304. want to say "hey, cool program", please contact me using one of the ways
  305. listed below.  Even if you wanna say "CyberPager sucks", let me know and be
  306. sure to say why you feel this way so that I might be able to fix what you
  307. think is wrong with the program.
  308.  
  309. These electronic forms are the most prefered means of contacting me.  They
  310. will get you a response pretty quick.
  311.  
  312.     e-mail: caw@miroc.chi.il.us
  313.     BIX: caw
  314.  
  315. Snail Mail is pretty slow and I'm not known for being very good about
  316. responding to it...  :-)
  317.  
  318.     Christopher A. Wichura
  319.     5450 East View Park
  320.     Chicago, Il.  60615
  321.     USA
  322.  
  323. You can also reach me by phone.  However, please try to limit your calling
  324. to evening hours (I'm in the central time zone).  If I'm not home and you
  325. leave a message, call back again anyway.  Around here, one tends to get
  326. maybe 5% of the messages left for them, if lucky...  :-)
  327.  
  328.     (312)/684-2941
  329.  
  330. HISTORY
  331. =======
  332.  
  333. 1.0
  334.     Initial release
  335.  
  336. 1.1    (7/10/93, SpoolPage v0.136, DialIXO v0.219, library v1.23)
  337.     A bug in the checksum generator manifested itself when talking
  338.     to services which are more strict about the IXO protocol.
  339.     Many IXO services accept a space instead of a zero in the checksum.
  340.     Some, like SkyTell, appear not to.  DialIXO now uses zeros per
  341.     the IXO spec as written by Motorolla.
  342.  
  343.     Added a loglevel 4 entry to DialIXO that causes it to log the
  344.     exact packet being sent to the service when uploading each
  345.     page.
  346.  
  347.     Added a routine to intelligently add characters to the safe
  348.     buffer (i.e., non-printable characters converted to escaped
  349.     hex, etc, for display purposes).  DialIXO know displays
  350.     special characters of the IXO protocol, such as ACK, NAK, STX,
  351.     etc., as text rather than hex escape sequences to make
  352.     tracing loglevel 5 output easier.
  353.