Important Notice

The pages on this site contain documentation for very old MS-DOS software, purely for historical purposes. If you're looking for up-to-date documentation, particularly for programming, you should not rely on the information found here, as it will be woefully out of date.

◄Function Group►  ◄Overview►                          ◄Up► ◄Next► ◄Previous►
────────────────────────────────────────────────────────────────────────────
 
#define INCL_DOSSEMAPHORES
 
USHORT DosSemSetWait(hsem, lTimeOut)
HSEM hsem;        /* semaphore handle */
LONG lTimeOut;    /* time-out         */
 
The DosSemSetWait function sets the specified semaphore (if it is not
already set) and then waits for another thread to clear the semaphore (by
using the DosSemClear function) or for a time-out to occur. The only
difference between the DosSemSetWait function and the DosSemWait function is
that the DosSemSetWait function will first set the semaphore if it is not
already set.
 
Parameter  Description
────────────────────────────────────────────────────────────────────────────
 
hsem       Identifies the semaphore to set. This value can be the handle of
           a system semaphore that has been previously created or opened by
           using the DosCreateSem or DosOpenSem function, or it can be the
           address of a RAM semaphore.
 
lTimeOut   Specifies how long to wait for the semaphore to become clear. If
           the value is greater then zero, this parameter specifies the
           number of milliseconds to wait before returning. If it is
           SEM_IMMEDIATE_RETURN, the function returns immediately. If it is
           SEM_INDEFINITE_WAIT, the function waits indefinitely.
 
Return Value
 
The return value is zero if the function is successful. Otherwise, it is an
error value, which may be one of the following:
 
     ERROR_EXCL_SEM_ALREADY_OWNED
     ERROR_INTERRUPT
     ERROR_SEM_TIMEOUT
     ERROR_TOO_MANY_SEM_REQUESTS
 
Comments
 
If more than one thread is setting and clearing the semaphore, a thread may
have to wait through several changes of the semaphore before it can continue
(depending on which thread clears the semaphore and when the system
scheduler passes control to the thread). As long as the semaphore is set
(even if it has been cleared and reset since the thread originally called
the function), the thread must wait.
 
The DosSemSetWait function cannot be used to wait for a system semaphore
that is set by another process unless the semaphore is nonexclusive.
 
Example
 
This example calls DosSemSetWait to set the specified RAM semaphore and then
waits until another thread clears the semaphore. It waits for up to 5
seconds and then returns an ERROR_SEM_TIMEOUT error value if a time-out
occurs before the semaphore is cleared.
 
#define INCL_DOSERRORS       /* include error constants */
 
ULONG hsem = 0;
if (DosSemSetWait(&hsem, 5000L) == ERROR_SEM_TIMEOUT) {
    .
    . /* error processing */
    .
}
else {
 
See Also
 
DosCreateSem, DosMuxSemWait, DosOpenSem, DosSemClear, DosSemRequest,
DosSemWait
 
                                      ♦