home *** CD-ROM | disk | FTP | other *** search
/ Black Box 4 / BlackBox.cdr / desqview / just1v12.arj / READ.ME < prev   
Text File  |  1991-07-25  |  8KB  |  195 lines
  1. JUSTONE (Version 1.1)
  2. (c) Copyright 1991 Heartsong Productions (tm)
  3.  
  4.  
  5. Overview
  6. ========
  7.  
  8. JUSTONE is a program designed for the DESQView (tm) multi-tasking
  9. environment.  It can be used to prevent multiple instances of the same
  10. program from running, or it can be used to prevent contention from
  11. programs that use the same resources.
  12.  
  13. JUSTONE makes use of the Shared Program facility of DESQView.  In case
  14. you aren't familiar with it, here is a brief explanation:
  15.  
  16. Most programs run under DESQView need to have their own address space to
  17. ensure that they do not collide with each other.  This is because most
  18. DOS programs don't need to communicate directly with other programs.
  19. However, under DESQView, you may want to be able to have two different
  20. programs communicate directly while they are running.  The Shared
  21. Program feature provides this facility.
  22.  
  23. A Shared Program is a program written specifically for DESQView that is
  24. loaded when you start up a program that makes reference to it in its
  25. PIF file (the Change Program screen in DESQView).  When a second
  26. program is run that makes reference to the same Shared Program, rather
  27. than using up additional memory resources loading a second copy of it,
  28. DESQView simply gives the second program access to the same copy as the
  29. first program.  If this sounds like it might confuse things, it very
  30. well could, except that DESQView gives the Shared Program clues about
  31. which program is running, so that it can keep things straight.  Shared
  32. Programs are specific to DESQView and cannot be run from the command
  33. line.
  34.  
  35. JUSTONE runs as a Shared Program.  Each time you run a program that
  36. calls out JUSTONE, DESQView gives JUSTONE control just long enough for
  37. it to look at the Shared Data from the PIF file.  This data field is an
  38. ASCII field where JUSTONE expects to find the name of a semaphore.  It
  39. then searches its list to see if any other program is currently using
  40. that semaphore, and if so, it displays an error message and switches to 
  41. the original instance of the program.  If there is no other program 
  42. using the semaphore, JUSTONE creates a semaphore and the program is 
  43. allowed to run.  When the program exits, DESQView removes the semaphore 
  44. from its list, so that next time, the program can run again.
  45.  
  46.  
  47. Installation
  48. ============
  49.  
  50. Installation of JUSTONE is very simple.  Copy the JUSTONE.SHP file to a
  51. directory in your PATH.  I recommend that you copy it to your /DV
  52. directory.
  53.  
  54.  
  55. Using JUSTONE
  56. =============
  57.  
  58. To use JUSTONE, you will need to modify the PIF file of the program(s)
  59. you want to control.  Tap the {DESQ} key (usually <Alt>), then select
  60. CP (Change Program) from the menu.  After selecting the program you
  61. want to change, the Change Program screen should come up.  You are
  62. looking at the PIF file.  The fields we are interested in are on the
  63. second page.  Press the F1 key to get to the second page.  Use the
  64. mouse, cursor keys, or tab key to move the cursor to the Shared Program
  65. block, specifically the Pathname field.  Type "JUSTONE.SHP" and press
  66. the Tab key or cursor keys to move to the Data field.  Type in a unique
  67. name, up to 64 characters into this field.  This is the semaphore name.
  68. Press the <Enter> key when you are finished, and that's it.
  69.  
  70. To test, start up a copy of the program you just modified.  Now try to
  71. run a second copy.  You should see an error message telling you that
  72. only one instance of the program is allowed.
  73.  
  74.  
  75. Controlling Access To Resources
  76. ===============================
  77.  
  78. Sometimes you also want to be able to control access to a single
  79. device, like a printer or a modem.  But you may have multiple programs
  80. that access it.  To ensure that only one is running at any one time,
  81. give all of the programs the same semaphore name.  Say, for instance,
  82. that you have a terminal program for communications with the modem, but
  83. you also have a dialing program that you use to speed-dial numbers for
  84. you.  It would be pretty disastrous if they both tried to access the
  85. modem at the same time.  By putting the semaphore name "Modem" in both
  86. program's Shared Program:Data field, only one will be allowed to run at
  87. a time.  You can use this same technique to control access to files, or
  88. other resources.
  89.  
  90.  
  91. CHKSEMA4
  92. ========
  93.  
  94. CHKSEMA4 is a program that allows you to check to see if a specific
  95. semaphore is in use.  As an example, let's say that you have used the
  96. semaphore name "Modem" to control access to your modem.  You can check
  97. to see if the semaphore is being used in a batch file as follows:
  98.  
  99.     chksema4 Modem
  100.     if not errorlevel 1 goto exit
  101.     echo Semaphore is in use
  102.     :exit
  103.  
  104. As you can tell from the previous example, CHKSEMA4 returns a 0 if the
  105. semaphore is not in use, or a 1 if it is in use.  It also returns a 2
  106. if you fail to specify a semaphore on the command line.  The included
  107. CHK.BAT file is a simple example of batch file usage of CHKSEMA4.
  108.  
  109. CHKSEMA4 is particularly useful in combination with EXEC which allows
  110. you to start background tasks from the command line or a batch file.
  111. You can check a semaphore, then start a task only if the semaphore is
  112. unlocked (or locked, if you choose).
  113.  
  114.  
  115. Error Messages
  116. ==============
  117.  
  118. "A non-swappable window is in the way"
  119.     Shared Programs require access to shared memory, which is
  120.     located in conventional RAM.  If you open a window that uses up
  121.     all of the conventional memory first, then DESQView does not
  122.     have memory to load the Shared Program.  You can prevent this
  123.     by running DESQView with the /MS option.  "/MS=1" will reserve
  124.     1K of shared memory for use by Shared Programs.  If you are
  125.     using other Shared Programs, you may need to increase this
  126.     number.
  127.  
  128. "Must have a semaphore name in the shared data field"
  129.     The semaphore name is a required field.  You must enter at
  130.     least one non-blank character into this field.
  131.  
  132. "Only one instance of this program allowed. 
  133.  Switching to original instance..."
  134.     This is the message you will get when you try to run a second
  135.     program that uses the same semaphore.  You will need to close
  136.     the first window before opening the second.
  137.  
  138. "Out of common memory"
  139.     JUSTONE uses Common Memory to keep track of the semaphores.  If
  140.     you receive this message, you don't have enough to open another
  141.     window as a shared program.  In fact, you are probably very
  142.     near to not being able to do anymore with DESQView.  If you
  143.     have this happen often, you should run DESQView Setup and
  144.     allocate more Common Memory in the advanced options.
  145.  
  146.  
  147. Acknowledgements
  148. ================
  149.  
  150. I'd like to acknowledge Phil Graham for providing me with the method 
  151. used to switch to the original program instance reliably.  I beat my 
  152. head against the wall trying to come up with something that worked, 
  153. including all kinds of hare-brained schemes, while Phil came up with 
  154. simple elegant solution.
  155.  
  156.  
  157. License And Disclaimer
  158. ======================
  159.  
  160. JUSTONE is distributed as shareware.  The registration fee is $10 US,
  161. (money order or check drawn on a US Bank) which will entitle you to
  162. telephone support and upgrade notices.  For a $15 registration, you
  163. will also receive the source code (please specify disk format).  The
  164. DESQView API manual and diskette are required to assemble the source
  165. code.  Registrations should be sent to the address below:
  166.  
  167.     Heartsong Productions
  168.     1 Tankers Road
  169.     Scotts Valley, CA  95066
  170.     (408) 438-5506 (voice & fax)
  171.     BIXname "dsparks"
  172.  
  173.  
  174. JUSTONE is supplied on an as-is basis only.  Heartsong Productions
  175. offers no warranty, express or implied, and will assume no liability
  176. as to the merchantibility or fitness to any purpose of this software,
  177. nor any liability for direct, indirect, special, incidental or
  178. consequential damages as a result of defects in this software or its
  179. documentation, even if advised of the possibility of such damages.
  180.  
  181.  
  182. Other DESQView Software Available From Heartsong Productions
  183. ============================================================
  184.  
  185. EXEC - A DOS command line program for starting up DESQView tasks.  You
  186. can start up a background task and have the program beep when it is
  187. finished, all from the comfort of your DOS command line.  Great for
  188. compiling programs or other background tasks that don't require input.
  189.  
  190.  
  191. TradeMarks
  192. ==========
  193. Heartsong Productions is a trademark of Heartsong Productions
  194. DESQView is a trademark of Quarterdeck Office Systems
  195.