FT_NWSEMOPEN()
Open or create a NetWare semaphore
Syntax
FT_NWSEMOPEN( <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 FT_NWSEMOPEN().
If the semaphore doesn't exist, NetWare will create it.
FT_NWSEMOPEN() returns a handle that is used in other semaphore
calls.
Applications use FT_NWSEMWAIT() to wait for a semaphore to
become available. FT_NWSEMWAIT() 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 FT_NWSEMSIG() to increment the value, and then
FT_NWSEMCLOSE() to close the semaphore. When the semaphore's
open count goes to 0, NetWare deletes it.
FT_NWSEMEX() 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 := FT_NWSEMOPEN( "Semaphore Test", nInitVal, ;
@nHandle, @nOpenCnt )
IF nRc != 0
QOUT =: "Error: " + STR( nRc ) )
QUIT
ENDIF
Source: NWSEM.PRG
Author: Glenn Scott
See Also: FT_NWSEMEX() FT_NWSEMWAIT() FT_NWSEMSIG() FT_NWSEMCLOSE() FT_NWSEMLOCK()
