home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 568a.lha / OwnDevUnit.library / ReadMeFirst < prev    next >
Text File  |  1991-10-28  |  9KB  |  201 lines
  1.                             OwnDevUnit.library
  2.  
  3.                 Copyright © 1991 by Christopher A. Wichura.
  4.                            All Rights Reserved.
  5.  
  6.  
  7.                                  Legalease
  8.  
  9. OwnDevUnit.library is copyrighted by Christopher A. Wichura.  It is freely
  10. redistributable.  You are free to copy it, as long as no charge is placed
  11. on it (cost of media and/or shipping is acceptable).
  12.  
  13. In using OwnDevUnit.library, you assume all responsibility for any loss of
  14. productivity and/or money that may occur during its use.  Mr. Wichura can
  15. not and will not be held accountable.
  16.  
  17.                    What is it?  And why might I need it?
  18.  
  19. To understand why OwnDevUnit.library was created, a little background
  20. information is needed.  For quite some time now, the Amiga community has
  21. had a number of programs that "sit on" a device/unit, waiting for it to do
  22. something.  An example of this is the program Getty, part of the AmigaUUCP
  23. distribution, which sits on a serial device waiting for a call to come in
  24. and then executing a program (usually uucico) after a login id has been
  25. established.  For quite a while, these programs were unfriendly to other
  26. programs wanting the device (such as a term program in the case of Getty).
  27. They provided no means for notifying them that another program wants the
  28. device/unit and more or less had to be killed and then restarted each time
  29. another program wanted to run.  Matt Dillon, the keeper of AmigaUUCP, has
  30. tried a couple of methods of implementing an extended locking mechanism
  31. whereby a program can ask Getty (or a similar program) to temporarily
  32. release the device it is looking at.  His original method, patching the
  33. OpenDevice() call, proved to be unstable, especially with serial devices
  34. other than the one built into an Amiga.  His second attempt works quite
  35. well.  However, it requires that programs that want to access the serial
  36. device either 1) be started by a wrapper program, LockSerial, that does the
  37. lock request or 2) compile and include Matt's locking code directly (to
  38. date, no program I know of uses this method).
  39.  
  40. I created OwnDevUnit.library to make option two, above, much easier to
  41. implement.  By having a shared library with a well defined set of routines,
  42. making a terminal program aware of the extended locking mechanisms required
  43. by programs such as Getty is trivial.  Term programs could be started
  44. directly, instead of the user having to use LockSerial.  An added benifit
  45. is that term programs that allow the user to switch the serial device/unit
  46. on the fly would be able to proplerly handle extended locking, instead of
  47. requiring the user to quit the term program and re-run it with a new
  48. device/unit specification given to LockSerial.
  49.  
  50. Unfortunately, Matt was not interested in my modifications, and currently I
  51. release modified executables of uucico, getty and lockserial that use
  52. OwnDevUnit.library's locking mechanism each time a new AmigaUUCP update
  53. comes out.  This is the reason I have not officially released any kind of
  54. programmer's kit for OwnDevUnit.library until now.  I figured, that if
  55. AmigaUUCP didn't support it, then what incentive was there for term program
  56. writers to support OwnDevUnit.library.  Recently, however, I have been
  57. contacted by the keeper of Amiga Welmat (Russel McOrmond,
  58. rwm@Atronx.OCUnix.On.Ca), another program which has a mode
  59. that works very much like Getty does, about the possibility of using
  60. OwnDevUnit.library and how this is an area where a couple different people
  61. are trying to solve essentially the same problem in different ways.
  62. Because of this, my interest in getting OwnDevUnit.library out and
  63. available has been rekindled and I have finally put together a developer's
  64. pack.
  65.  
  66.                   What is included in this distribution?
  67.  
  68. This distribution of OwnDevUnit.library contains the following files:
  69.  
  70.     c/lockserial
  71.  
  72.         My modified version of the LockSerial program from the AmigaUUCP
  73.         distribution that uses OwnDevUnit.library's locking mechanism.
  74.         Even if you don't plan to write any code that directly accesses
  75.         OwnDevUnit.library, you can use this program to provide locking
  76.         between programs used on your system.
  77.         
  78.         Usage is:
  79.         
  80.             LockSerial [-A] [-Ddevicename] [-Uunit] "command & args"
  81.         
  82.         The -A switch allows one to specify attempt mode, which will
  83.         fail and return the current owner's name if it refuses to
  84.         give up it's lock on the device.  If -A is not specified,
  85.         LockSerial will block indefinately waiting for the device
  86.         to become free.
  87.         
  88.         LockSerial defaults to serial.device unit 0.
  89.     
  90.     docs/OwnDevUnit.doc
  91.     
  92.         An ASCII format docfile for programming OwnDevUnit.library.  It
  93.         is in AutoDoc format, suitable for parsing by one of the various
  94.         AutoDoc hypertext scanners.
  95.     
  96.     docs/OwnDevUnit.tex
  97.     
  98.         The TeX version of OwnDevUnit.doc.  Note that this requires
  99.         AutoDoc.tex to be TeXified, a macro package I will not release
  100.         at this time.
  101.  
  102.     docs/OwnDevUnit.dvi
  103.     
  104.         This is a .dvi file generated from OwnDevUnit.tex.  If you have
  105.         access to a dvi output system then it is recommened that this
  106.         be printed over OwnDevUnit.doc, as it is better formatted and
  107.         easier to read.
  108.  
  109.     fd/OwnDevUnit.fd
  110.  
  111.         This is a .fd file for OwnDevUnit.library.  Using this, even
  112.         AmigaBASIC should be able to access OwnDevUnit.library.
  113.  
  114.     include/OwnDevUnit.h
  115.  
  116.         This is a 'C' style include file for people programming
  117.         OwnDevUnit.library.  It is tailored a little towards SAS/Lattice C.
  118.         I have not tried it under Manx.  (I don't have Manx...)
  119.  
  120.     lib/ODU.lib
  121.  
  122.         Link library with stubs for calling functions in
  123.         OwnDevUnit.library.  Provided for those that don't have access
  124.         to #pragmas of one sort or another.  Uses relative base addressing.
  125.  
  126.     lib/ODUnb.lib
  127.  
  128.         Same as above, except that non base relative addressing mode is
  129.         used.
  130.  
  131.     libs/OwnDevUnit.library
  132.  
  133.         This is the shared library which provides the locking mechanism.
  134.         It should be copied to your LIBS: directory.
  135.  
  136.     source/*
  137.  
  138.     The source and makefile for rebuilding OwnDevUnit.library.  This
  139.     is very SAS specific code.  Compiling with debug mode on will
  140.     include lots of kprintf()s.  You have been warned...
  141.  
  142.              Suggested use of OwnDevUnit.library in a program
  143.  
  144. I wrote OwnDevUnit.library such that it should be easy to use if it is
  145. there and equally as easy to not use if it is not there.  This way, a term
  146. program does not have to require OwnDevUnit.library to be present to run.
  147. It is suggested that term programs look for OwnDevUnit.library and if it is
  148. present call either LockDevUnit() or AttemptDevUnit() before calling
  149. OpenDevice() (you MUST still check the error return from OpenDevice(),
  150. though!).
  151.  
  152. It is recommended that term programs only use the AttemptDevUnit() call, as
  153. it is unfriendly to lock up the user's machine waiting for a device to
  154. become free.  The LockDevUnit() call is intended mainly for non-interactive
  155. applications (such as uucico) that periodically run in the background.
  156.  
  157. If you are writing a program similar to Getty then, obviously,
  158. OwnDevUnit.library will have to be hardcoded into it.  In such cases, I am
  159. willing to allow distribution of OwnDevUnit.library with your program so
  160. long as you first send me mail asking permission.  This way, I can insure
  161. that you are distributing the latest version of the library, and that if
  162. newer versions are created, you can be informed of them and change your
  163. distribution accordingly.
  164.  
  165. If you are someone who doesn't program at all then you can still use the
  166. LockSerial program to access OwnDevUnit.library, as was previously
  167. mentioned.  OwnDevUnit.library can also be added as an ARexx function host,
  168. using the rexx command
  169.  
  170.     addlib("OwnDevUnit.library", 0, -60, 2)
  171.  
  172. Note that to make full use of OwnDevUnit.library from ARexx, you will need
  173. to have an ARexx function host that gives you access to the exec.library
  174. functions AllocSignal() and Wait().  Without this, you __MUST__ specify
  175. zero in the NotifyBit argument of AttempDevUnit() and LockDevUnit().
  176.  
  177. Also note that when calling functions in OwnDevUnit.library from ARexx, you
  178. can not specify an owner name (a default, "ARexx", is supplied for you).
  179. This is due to internal limitations and can not easily be corrected.
  180. Because of this, LockDevUnit() and AttemptDevUnit() only have three
  181. arguments when called from ARexx, instead of four.  The argument template
  182. for both of these functions is
  183.  
  184.     return = function(device name, unit, notifybit)
  185.  
  186. Also, NameDevUnit is not available from ARexx.
  187.  
  188. Also note that when using ARexx, you should trap break (and other) signals
  189. and have a signal handler that will call FreeDevUnit() to release the lock
  190. on a device.  If you do not, and your program exits with a lock hanging,
  191. the __ONLY__ way to free that lock is to reboot the system.  (This warning
  192. also applies to people calling the library functions directly from C or ASM
  193. or whatever, too!)
  194.  
  195. -=> CAW
  196.  
  197. Christopher A. Wichura
  198. 5450 East View Park
  199. Chicago, IL.  60615
  200. (312)/684-2941 (evenings only, please -- I'm in the central time zone)
  201.