home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 18 REXX / 18-REXX.zip / rexxsem.zip / rexxsem.txt < prev   
Text File  |  1997-01-07  |  9KB  |  233 lines
  1.                                REXXSEM
  2.                                =======
  3.  
  4.     After years of using REXX and months trying to get multiline
  5. support for my BBS in rexx, I got fed up.  I wanted semaphore support -
  6. both to interface with Squish (which uses 16-bit semaphores) and
  7. everything else (using 32-bit semaphores which will be faster under
  8. OS/2 2.0+).  I wanted to prevent programs which were too dumb to
  9. provide their own semaphoring from running simultaneously with each
  10. other.  And here's the rexx routines I came up with.  If they help you,
  11. I'd be happy to know.  If there are some extentions you would like to
  12. see, let me know as well.  And if you would like to offer some example
  13. rexx scripts, that would be great, too.
  14.  
  15.     In the meantime, here's RexxSem, version 0.2 beta.  The
  16. routines are:
  17.  
  18. -------
  19. SemLoad
  20. -------
  21.  
  22.     Use this to load all the routines.  Sample usage:
  23.  
  24. call RxFuncAdd 'SemLoad', 'RexxSem', 'SemLoad'
  25. call SemLoad /* this will load all the routines */
  26.  
  27. -------
  28. SemDrop
  29. -------
  30.  
  31.     Use this to unload all the routines.  All semaphores in use
  32. will still be in use, though!  You will have to physically unload the
  33. DLL to kill the semaphores at this point (i.e., exit your CMD
  34. session!).  Sample usage:
  35.  
  36. call SemDrop /* doesn't return anything */
  37.  
  38. --------------
  39. SemCreateMutex
  40. --------------
  41.  
  42.     This function will create a 32-bit semaphore without claiming
  43. it.  You must name the semaphore something that starts with "\sem32\",
  44. otherwise this function will abort your script.  It is up to you to
  45. ensure this!  It will return a semhandle that will be required in all
  46. future semaphore operations.  Sample usage:
  47.  
  48. semhandle = SemCreateMutex("\sem32\some\semaphore.sem")
  49.  
  50.     Note that if the semaphore is already "created" (for example,
  51. by another process), this will simply open it and return the handle for
  52. that.  Also, even though the system will accept /sem32/blah/blah, this
  53. rexx function will not.  This may be addressed in future versions.  The
  54. system does not see a difference, however, between /sem32/blah/blah and
  55. \sem32\blah\blah.
  56.  
  57. --------------
  58. SemCreateSem16
  59. --------------
  60.  
  61.     This function will create a 16-bit semaphore without claiming
  62. it.  You must name the semaphore something that starts with "\sem\",
  63. otherwise this function will abort your script.  It is up to you to
  64. ensure this!  It will return a semhandle that will be required in all
  65. future semaphore operations.  Sample usage:
  66.  
  67. semhandle = SemCreateSem16("\sem\squish\default")
  68.  
  69.     Note that if the semaphore is already "created" (for example,
  70. by another process), this will simply open it and return the handle for
  71. that.  Also, even though the system will accept /sem/blah/blah, this
  72. rexx function will not.  This may be addressed in future versions.  The
  73. system does not see a difference, however, between /sem/blah/blah and
  74. \sem\blah\blah.
  75.  
  76. --------
  77. SemClaim
  78. --------
  79.  
  80.     This function claims a semaphore, with an optional timeout
  81. value.  Sample usage:
  82.  
  83. rc = SemClaim(semhandle, 150)
  84. rc = SemClaim(semhandle)
  85.  
  86.     The semhandle can be any semhandle created by this library. 
  87. Whether it is a Sem16 or a Mutex semaphore does not matter.  If you
  88. want to change whether you use a 16-bit or 32-bit semaphore, you only
  89. have to change the create function, but nothing else.  If the semhandle
  90. is not a valid pending handle, this will abort your script.
  91.  
  92.     The optional second parameter is a timeout in milliseconds.  If
  93. the timeout value is not acceptable (i.e., negative), it will abort
  94. your script.  If this parameter is not given, there will be no timeout,
  95. and the script will block until the semaphore is available.
  96.  
  97.     If the timeout passes without the semaphore becoming available,
  98. rc will be "TIMEOUT", otherwise it will be "CLAIMED".
  99.  
  100. ----------
  101. SemRelease
  102. ----------
  103.  
  104.     This function releases a semaphore.  Sample usage:
  105.  
  106. call SemRelease semhandle
  107.  
  108.     The semhandle can be any semhandle created by this library. 
  109. Whether it is a Sem16 or a Mutex semaphore does not matter.  If you
  110. want to change whether you use a 16-bit or 32-bit semaphore, you only
  111. have to change the create function, but nothing else.  If the semhandle
  112. is not a valid pending handle, this will abort your script.
  113.  
  114.     There is never a value returned.
  115.  
  116. --------
  117. SemClose
  118. --------
  119.  
  120.     This function closes the semaphore after it is no longer
  121. needed.  Sample usage:
  122.  
  123. call SemClose semhandle
  124.  
  125.     The semhandle can be any semhandle created by this library. 
  126. Whether it is a Sem16 or a Mutex semaphore does not matter.  If you
  127. want to change whether you use a 16-bit or 32-bit semaphore, you only
  128. have to change the create function, but nothing else.  If the semhandle
  129. is not a valid pending handle, this will abort your script.
  130.  
  131.     The semhandle is no longer a valid pending handle after this
  132. function is called.
  133.  
  134. -----------
  135. SemLogState
  136. -----------
  137.  
  138.     This function simply logs the current state - which semaphores
  139. are available, and what the next handle will be.  This is just for
  140. debugging purposes and may not give the same output next release. 
  141. Sample usage:
  142.  
  143.     call SemLogState 'my.log.file'
  144.  
  145.     The my.log.file will be the file to log all the information to.
  146. The most important thing would be to ensure that you are using SemClose
  147. on all available semaphores before your script ends as this may block a
  148. lot of other threads if you forget!  The logfile will tell you which
  149. semhandles have not been closed for this purpose.
  150.  
  151. --------------------
  152. SemReturnValidAlways
  153. --------------------
  154.  
  155.     This function actually prevents ANY function from returning
  156. "Invalid function call" and aborting your script.  This is primarily
  157. intended for debugging your rexx scripts.  This functionality became so
  158. useful to me that I left it in to help you before having to email me. 
  159. Sample usage:
  160.  
  161. call SemReturnValidAlways 'On'  /* never aborts script - debug mode */
  162. call SemReturnValidAlways 'Off' /* always abort script on error */
  163.  
  164.     Note, however, that timeing out on a timed claim is _not_ an
  165. error, and will never abort the script.
  166.  
  167.     Whenever an error occurs, the function will always return a
  168. string that starts with 'ERROR:'.  The rest of the string will contain
  169. an explanation of the error.  The following errors are currently used:
  170.  
  171. =====================================================================
  172.  
  173. SemLoad cannot have arguments
  174. SemDrop cannot have arguments
  175. SemCreateMutex requires the mutex name to create
  176. SemCreateSem16 requires the 16-bit semaphore name to create
  177. SemClaim requires 1 or 2 parameters to claim a semaphore
  178. SemRelease requires the semaphore handle to release it
  179. SemClose requires the handle to a semaphore to close it
  180. SemLogState requires exactly one argument: a file name
  181. SemReturnInvalid requires a yes/no parameter to turn the feature on and off
  182.  
  183.     These are self-explanatory.  You did not call the function
  184. properly.
  185.  
  186. =====================================================================
  187.  
  188. SemClose cannot find the given handle to close it
  189. SemClaim cannot find the given semaphore handle to claim it
  190. SemRelease cannot find the given semaphore handle to release it
  191.  
  192.     The meaning here is that your semhandle that you passed to
  193. these functions do not match what the SemRexx functions recall that
  194. this rexx process has available to it.
  195.  
  196. =====================================================================
  197.  
  198. Out of memory in SemCreateMutex?
  199. Out of memory in SemCreateSem16?
  200.  
  201.     These errors you should never face, but they are
  202. self-explanatory.  (i.e., if you see them, you have bigger problems
  203. than a failed SEMREXX call...)
  204.  
  205. =====================================================================
  206.  
  207. SemCreateMutex detected invalid semaphore name
  208. SemCreateSem16 detected invalid semaphore name
  209.  
  210.     The create functions know a lot about what is a valid semaphore
  211. name and what isn't.  This means we have detected a known invalid
  212. semaphore name.  Go back to the function descriptions and ensure that
  213. you are using a valid semaphore name.
  214.  
  215. =====================================================================
  216.  
  217. Failed to create/open mutex sem (Sys: xxx)
  218. Failed to create/open 16-bit sem (Sys: xxx)
  219.  
  220.     OS/2 reported an error that we didn't know how to handle.  For
  221. OS/2 programmers, the 'xxx' is the OS/2 error number for the create or
  222. open functions.  I especially want to know what you are using for a
  223. semaphore name if you get error 123 here, although I wouldn't mind
  224. hearing about other errors.
  225.  
  226. =====================================================================
  227.  
  228.  
  229. How to contact the author:
  230.  
  231. I can be reached, for now, at mcbride@ee.ualberta.ca.  I am in a heavy
  232. courseload right now, but I'll try to answer any questions.
  233.