◄Function Group►  ◄Overview►  ◄Changes►               ◄Up► ◄Next► ◄Previous►
────────────────────────────────────────────────────────────────────────────
 
#define INCL_DOSSEMAPHORES
 
USHORT DosSemRequest(hsem, lTimeOut)
HSEM hsem;        /* semaphore handle */
LONG lTimeOut;    /* time out         */
 
The DosSemRequest function obtains and sets a semaphore. If no previous
thread has set the semaphore, DosSemRequest sets the semaphore and returns
immediately. If the semaphore has already been set by another thread, the
function waits until a thread clears the semaphore (by using the
DosSemClear function) or until a time-out occurs. The DosSemRequest function
is also used to obtain ownership of a system semaphore created with the
CSEM_PRIVATE flag set (see DosCreateSem).
 
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 clear. If the
           value is greater then zero, this parameter specifies the number
           of milliseconds to wait before returning. If the value is
           SEM_IMMEDIATE_RETURN, the function returns immediately. If the
           value 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_INTERRUPT
     ERROR_SEM_OWNER_DIED
     ERROR_SEM_TIMEOUT
     ERROR_TOO_MANY_SEM_REQUESTS
 
Comments
 
If DosSemRequest is used to obtain exclusive ownership of a semaphore
created by another process, it will wait (if lTimeOut is non-zero) until the
semaphore is clear, or until the process that currently owns the semaphore
closes the semaphore or terminates. If the process owning the semaphore
terminates, DosSemRequest will return with an error value of
ERROR_SEM_OWNER_DIED, however ownership will be transferred and the
semaphore will be set and can be used by the calling process.
 
The effects of DosSemRequest are cumulative. If multiple calls to the
DosSemRequest function set the semaphore, the same number of calls to the
DosSemClear function are required to clear the semaphore.
 
If more than one thread has requested to set the semaphore, a thread may
have to wait through several changes of the semaphore before it continues
(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 DosSemRequest function can set system or RAM semaphores. A system
semaphore is initially clear when it is created. A RAM semaphore is clear if
its value is zero. Programs that use RAM semaphores should assign the
initial value of zero.
 
Example
 
This example uses the DosSemRequest function to create a RAM semaphore. It
also shows how to set and clear the semaphore.
 
ULONG hsem = 0;
DosSemRequest(&hsem,           /* address of handle  */
    SEM_INDEFINITE_WAIT);      /* waits indefinitely */
    .
    .
    .
DosSemClear(&hsem);            /* clears semaphore   */
 
See Also
 
DosCreateSem, DosExitList, DosMuxSemWait, DosOpenSem, DosSemClear,
DosSemSet, DosSemSetWait, DosSemWait
 
                                      ♦