home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 18 REXX / 18-REXX.zip / rxsem104.zip / rexxsem.txt < prev    next >
Text File  |  2000-08-17  |  8KB  |  206 lines
  1.                                REXXSEM
  2.                                =======
  3.                              The Read-me
  4.                             +-----------+
  5.  
  6. REXXSEM - WHY!?!?!?
  7. -------------------
  8.  
  9.         After years of using REXX and months trying to get multiline
  10. support for my BBS in REXX, I got fed up.  I wanted semaphore support -
  11. both to interface with Squish (which uses 16-bit mutex semaphores) and
  12. everything else (using 32-bit mutex semaphores which will be faster
  13. under OS/2 2.0+).  I wanted to prevent programs which were too dumb to
  14. provide their own semaphoring from running simultaneously with each
  15. other.  And here's the rexx routines I came up with.  If they help you,
  16. I'd be happy to know.  If there are some extentions you would like to
  17. see, let me know as well.  And if you would like to offer some example
  18. rexx scripts, that would be great, too.
  19.  
  20.  
  21. What REXXSEM does
  22. -----------------
  23.  
  24.     REXXSEM is a REXX-extention DLL.  That is, it is a DLL that is
  25. written to allow REXX scripts to call it.  This works similar to the
  26. REXXUTIL that come with OS/2's REXX.
  27.  
  28.     The REXXUTIL were written to give basic access to some very
  29. useful OS/2 API functions dealing with file systems, WPS, and other
  30. areas. REXXSEM was written to give basic access to some other very
  31. useful OS/2 APIs: the mutual-exclusion (mutex) semaphores.
  32.  
  33.     REXXSEM's semaphores, then, work the same way as the OS/2 API
  34. semaphore functions.  This includes using OS/2's ability to block your
  35. REXX script until the desired semaphore is available (to use zero CPU
  36. cycles while waiting), priority-based scheduling (if a high-priority
  37. program is waiting on your semaphore, you will get its priority until
  38. you release the semaphore), and priority-based semaphore ordering (the
  39. highest priority thread that is waiting for a semaphore will get it
  40. next).
  41.  
  42.  
  43. When to use REXXSEM
  44. -------------------
  45.  
  46.     The "old" (DOS?) way of finding out whether another script is
  47. running is to look for a "semaphore" file.  If it doesn't exist, create
  48. it and continue.  If it does exist, wait a second and look again in a
  49. loop until it no longer exists.  When you're done, delete the file.
  50.  
  51.     This is tedious, error prone, and CPU (and disk!) intensive. 
  52. Every time you want to do this, you need to write your code out, and,
  53. if you code like me, you'll forget something different each time,
  54. ensuring a fun time debugging.
  55.  
  56.     This is where other languages excel: they allow you to call the
  57. OS's semaphores.  Well, now you can do the same thing in REXX.
  58.  
  59.     Actually, you could before if you have ObjectREXX which has
  60. semaphoring functions built in.  What I found is that ObjectREXX
  61. couldn't perform at all on my old 486dx2/66.  Since then, I haven't
  62. switched back even though I have a faster machine.  If you don't want
  63. the overhead of ObjectREXX but want semaphores, this is the perfect
  64. package.
  65.  
  66.  
  67. What else?
  68. ----------
  69.  
  70.     REXXSEM does not have to abort your script with some cryptic
  71. "bad function call" message.  If you use the SemReturnValidAlways
  72. function to turn this feature on, all functions will always return
  73. valid, but will provide an explanation of what the problem is.  In
  74. fact, these messages can be translated and used in whichever language
  75. you want, if I can find a translator from English to your language.
  76.  
  77.     Mind you, these messages can get a little long for a single
  78. string, so there is a WordWrap function to wrap the words at whatever
  79. width you want (defaulting to the current session's width).  (This may
  80. not work well in a PM REXX session - but you can specify a width to
  81. use.)
  82.  
  83.     Other neat features added were the ability to open Netscape
  84. windows ... without unnecessarily starting new processes. 
  85. OpenNetscapeWindow will let you open a URL without starting new
  86. processes - a method that is rapidly faster than just typing "start
  87. netscape <url>", and consumes vastly less memory.  You can specify
  88. whether to use an existing (OLD) netscape window, or to have Netscape
  89. create a new (NEW) window.
  90.  
  91.     Of course, somewhere in there the REXXSEM dll must determine
  92. whether or not netscape is running, so I externalized part of this as
  93. well: ProcessIDsOf will tell you all process ID's of any given process
  94. name(s).  You can find out how many CMD sessions are running, even
  95. their process ID's (which may come in handy for other purposes later
  96. on, such as killing them).  This method is faster than using pstat with
  97. rxqueue and reading it line-by-line if you just need to know whether
  98. the process exists or not.  It uses some new APIs to do this which
  99. preclude pre-Warp OS/2, and even preclude some fixpaks of Warp 3.
  100.  
  101.     In 0.7, VIO-window-handling functions were added. 
  102. RxWinSetTitle will let you set the title of the current session.
  103.  
  104.     In 1.0, priority-handling functions were added.  You can now
  105. query, and set, your priority, or the priority of any of your children
  106. (if you're not blocked on them).
  107.  
  108.     Is there anything missing?  Have a favourite function that
  109. you'd like to see in a REXX DLL?  If you have it written in
  110. VAC-compatable code, send it in and I'll try to get it in!
  111.  
  112.  
  113. How to use REXXSEM
  114. ------------------
  115.  
  116.     REXXSEM uses standard REXX methods: put the dll in your libpath
  117. somewhere, and read the reference (rxsemref.htm)!  We assume you know
  118. how to use REXX.  If not, find a book on REXX (there are many good
  119. ones), and sit down and read.  It's not a hard language.  :-)
  120.  
  121.     (<phew>, that was easy. :-)
  122.  
  123.  
  124. REXXSEM licencing
  125. -----------------
  126.  
  127.     REXXSEM is distributed as licenced shareware.  REXXSEM ("the
  128. Program") is copyright 1997, 2000 by the author and all rights are
  129. reserved.
  130.  
  131.     Under this licence, you may:
  132.  
  133. 1. use the Program in binary form only.
  134. 2. make copies of the original file you downloaded and distribute it,
  135.    provided that you transfer a copy of this licence to the other party.
  136.  
  137.     You may NOT:
  138.  
  139. 1. reverse assemble, reverse compile, or otherwise translate the
  140.    program.
  141. 2. distribute the Program, in whole or in part, with any shareware or
  142.    commercial application.
  143. 3. use your program key on more than one computer where they may be in
  144.    use on more than one computer at a time.
  145.  
  146. A separate licence is available for licensing with shareware and
  147. commercial distribution.
  148.  
  149.     The author expressly disclaims all liabilities arising from the
  150. use of the Program, including, but not limited to, (i) third-party
  151. claims against you, (ii) loss of, or damage to, your records or data,
  152. (iii) economic consequential damages (including lost profits or
  153. savings) or incidental damages, even if the author is informed of their
  154. possibility.
  155.  
  156.     THERE ARE NO WARRANTIES, EXPRESS OR IMPLIED, INCLUDING THE
  157. IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  158. PURPOSE.
  159.  
  160.     You may not sell, transfer, assign, or subcontract any of your
  161. rights or obligations under this license. Any attempt to do so is void.
  162.  
  163. This license is governed by the laws of Ontario, Canada.
  164.  
  165.  
  166. Registering REXXSEM
  167. -------------------
  168.  
  169.     There are a number of functions in REXXSEM marked "Registered".
  170. These functions will only be unlocked by registering REXXSEM.  While
  171. the core functionality (the semaphore functions) will always work,
  172. these extra functions are the incentive or reward for registering the
  173. product.
  174.  
  175.     To register the product, I only accept registrations through
  176. BMTMicro.  Go to https://secure.bmtmicro.com/order1476.html to get
  177. directly to the order form.  The price is currently $20 US.
  178.  
  179.  
  180. REXXSEM Mailing list
  181. --------------------
  182.  
  183.     REXXSEM has a mailing list now.  Send a note to
  184. majormajor@tower.to.org with 'subscribe RxSem' in the body.  I use
  185. Peter Moylan's software exclusively here - Weasel and MajorMajor.
  186.  
  187.  
  188. REXXSEM's author
  189. ----------------
  190.  
  191. Darin McBride - longtime OS/2 abuser, longertime sysop.  Obviously he
  192. enjoys causing himself headaches.  If you have a cure for these
  193. headaches, or just some general REXXSEM questions, you can contact him
  194. as below:
  195.  
  196. EMail:    dmcbride@tower.to.org       (preferred)
  197.           d.mcbride@home.com
  198.  
  199. Web:      http://tower.to.org/rexxsem
  200.  
  201. Fidonet: <arf, arf!>
  202.  Netmail: Darin McBride, 1:250/102
  203.  Echos:   C_ECHO, C_PLUSPLUS, OS2PROG 
  204.           (REXXSEM is only on-topic in OS2PROG and OS2REXX, although I
  205.           don't read OS2REXX)
  206.