DosSemRequest

Bindings:  C, MASM 

This call obtains a semaphore and sets the semaphore as owned by the 
thread that requested it. 

 DosSemRequest     (SemHandle, Timeout) 
 

 SemHandle (HSEM) - input 
    Reference to the semaphore. 

    For a system semaphore, this reference is the handle returned by a 
    DosCreateSem or DosOpenSem request that granted the requesting thread 
    access to the semaphore. 

    For a RAM semaphore, this reference is the address of a doubleword of 
    storage, allocated and initialized to zero by the application. This 
    sets the semaphore as unowned. Other than initializing the doubleword 
    to zero, an application must not modify a RAM semaphore directly; 
    instead it manipulates the semaphore with semaphore function calls. 

 Timeout (LONG) - input 
    Action taken by the requesting thread when the semaphore is owned by 
    another thread.  The values that can be specified are: 

    Value     Definition 
     -1       The requesting thread waits indefinitely for the semaphore 
              to be cleared. 
      0       The requesting thread returns immediately. 
     > 0      The requesting thread waits the indicated number of 
              milliseconds for the semaphore to be cleared before resuming 
              execution. 

 rc (USHORT) - return 
    Return code descriptions are: 

    0         NO_ERROR 
    95        ERROR_INTERRUPT 
    100       ERROR_TOO_MANY_SEMAPHORES 
    105       ERROR_SEM_OWNER_DIED 
    121       ERROR_SEM_TIMEOUT 
 
 Remarks 

 Typically, DosSemRequest is called to set a semaphore for the purpose of 
 accessing a protected resource. DosSemRequest checks the status of the 
 semaphore.  If the semaphore is not set (that is, not owned) by another 
 thread, DosSemRequest sets the semaphore as owned by the current thread 
 and returns immediately to the caller. 

 If the semaphore is already owned by another thread, DosSemRequest 
 optionally can block the requesting thread until the semaphore becomes 
 available. The unblocking of a thread blocked by a DosSemRequest is 
 level-triggered. That is, DosSemRequest does not return until the 
 semaphore remains clear long enough for the affected thread to be 
 redispatched and successfully claim the semaphore. Thus, if a number of 
 threads are blocked indefinitely on DosSemRequest calls for the 
 semaphore, only the thread that sets the semaphore is actually unblocked. 
 If a milliseconds value is specified for the Timeout parameter, this 
 places an upper limit on the amount of time the requesting thread remains 
 blocked, waiting for the semaphore to become available. 

 When a thread no longer requires the protected resource, it issues 
 DosSemClear to clear the semaphore, so another thread may claim it with a 
 successful DosSemRequest. If the semaphore is an exclusive system 
 semaphore, it has a use count associated with it, which is incremented by 
 a DosSemRequest and decremented by a DosSemClear. The semaphore is not 
 actually cleared and made available to the next thread that wants to 
 access the resource until the semaphore has been cleared the same number 
 of times it has been requested. This means that exclusive system 
 semaphores can be used in recursive routines.  When the use count is 0, 
 the semaphore is available to be claimed by the next user of the 
 protected resource. 

 If a process terminates while owning a nonexclusive system semaphore, 
 ERROR_SEM_OWNER_DIED is returned to the thread that next gets the 
 semaphore through DosSemRequest. That thread takes steps to ensure the 
 integrity of the resource.  The thread can release the resource by 
 issuing a DosSemClear, or it can reset the ERROR_SEM_OWNER_DIED return 
 code condition flagged in the semaphore data structure. 

 Note:  To request a Fast-Safe RAM semaphore, a thread calls 
        DosFSRamSemRequest.