FN_SEMOPEN()
 Open or create a semaphore
------------------------------------------------------------------------------
 Syntax
 
       fn_semOpen( <cName>, <nInitVal>, <@nHandle>, <@nOpenCnt> ) -> nRc
 
 Arguments

      <cName> is the semaphore name, maximum length is 127 characters.

      <nInitVal> is the initial value for the semaphore.  It must start
      as a positive number, to a maximum of 127.

      <@nHandle> is the semaphore handle.  THIS MUST BE PASSED BY
      REFERENCE!  On exit, <nHandle> will contain a numeric value that
      refers to the opened semaphore.  You will need it to pass to
      other semaphore functions!  PASS IT BY REFERENCE!

      <@nOpenCnt> is the number of stations that have opened the
      semaphore.  THIS MUST BE PASSED BY REFERENCE! On exit, <nOpenCnt>
      will contain a numeric value.

 Returns

      nRc, a numeric result code, as follows:

            0 - success
          254 - Invalid semaphore name length
          255 - Invalid semaphore value

      <nHandle> will contain the semaphore handle, and
      <nOpenCnt> will contain the number of stations that have opened
      the semaphore.

 Description

      A semaphore is simply a label that indirectly controls network
      activity.  There is a semaphore name, which can be up to 127
      characters, and an associated value, which can range from 0 to
      127.

      A semaphore can be used for many things, but is most often used
      to limit the number of users in an application, and to control
      access to a network resource.

      A semaphore essentially allows you to place locks on resources
      other than files.

      An application begins the process by calling fn_semOpen().
      If the semaphore doesn't exist, NetWare will create it.
      fn_semOpen() returns a handle that is used in other semaphore
      calls.

      Applications use fn_semWait() to wait for a semaphore to
      become available.  fn_semWait() decrements the semaphore's
      value by 1.  If the value > 0, then the application should
      be allowed to access the semaphore's resource.  If the value
      goes negative, then the application is placed in a queue.
      How long your app is in the queue is determined by how you
      set the timeout parameter.  If you can't get the resource in
      the time you allot, you're let out of the queue and the
      value increments by 1 again.

      When an application finishes with a semaphore, it should
      call fn_semSig() to increment the value, and then
      fn_semClos() to close the semaphore.  When the semaphore's
      open count goes to 0, NetWare deletes it.

      fn_semEx() can be used to examine the value and open count
      without affecting them.

      For an interesting discussion on the operating system aspects
      of semaphores, check "Operating Systems Design and Implementation"
      by A. Tanenbaum, page 60.  For more details on NetWare's
      semaphore facilities, refer to Charles Rose's "Programmer's
      Guide to NetWare".  The "Programmer's Guide" will make an
      excellent companion guide to the source code for all NetWare
      functions in the Nanforum Toolkit.

 Examples

      LOCAL nInitVal, nRc, nHandle, nOpenCnt

      nInitVal := 2
      nRc      := fn_semOpen( "Semaphore Test", nInitVal, ;
                                @nHandle, @nOpenCnt )

      IF nRc != 0
        QOUT =: "Error: " + STR( nRc ) )
        QUIT
      ENDIF


 Source: N:\SRC\SYNCHRO\SEMA.PRG

 Author: Glenn Scott