View source for DosSemClear

==Description==
This call unconditionally clears a semaphore. If any threads were blocked on the semaphore, they are restarted.

==Syntax==
<PRE>
 DosSemClear

    (SemHandle)
</PRE>

==Parameters==
;  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.

==Return Code==
 rc (USHORT) - return

Return code descriptions are:

* 0          NO_ERROR
* 101        ERROR_EXCL_SEM_ALREADY_OWNED 

==Remarks==
DosSemClear typically is used to release a semaphore obtained through DosSemRequest. DosSemClear also is used with the semaphore signaling functions DosSemSetWait, DosSemWait, and DosMuxSemWait.

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.

Normally, DosSemClear cannot be issued against a system semaphore owned by another process unless the NoExclusive option is set by the DosCreateSem request that created the semaphore. However, at interrupt time any thread may clear an exclusively owned semaphore. 

==Example Code==
=== C Binding===
<PRE>
#define INCL_DOSSEMAPHORES

USHORT  rc = DosSemClear(SemHandle);

HSEM             SemHandle;     /* Semaphore handle */

USHORT           rc;            /* return code */

</PRE>
'''Example'''

The following example illustrates the serialization of access to a shared resource between threads of the same process. The program creates a nonexclusive system semaphore named resource.sem, requests access to the semaphore, clears it, and finally closes the semaphore. For an illustration of notification of events, see the example given in DosOpenSem, DosSemSet, or DosSemWait. 

<PRE>
#define INCL_DOSSEMAPHORES

#include <os2.h>

#define SEM_NAME "\\SEM\\resource.sem"  /* Semaphore name */
#define TIMEOUT 1500L                   /* Timeout (in milliseconds) */


main()
{
  HSEM SemHandle;
  USHORT rc;

  /* Note: the semaphore could have been created by another    */
  /*       thread.                                             */
  DosCreateSem(CSEM_PUBLIC,         /* Ownership - nonexclusive */
               &SemHandle,          /* Semaphore handle (returned) */
               SEM_NAME);           /* Semaphore name */
  if(!(rc = DosSemRequest(SemHandle,       /* Semaphore Handle */
                         TIMEOUT)))        /* Timeout Period   */
  {
    /* Semaphore obtained; resource may now be used. */
    /* Clear the semaphore after using resource.     */
    if(DosSemClear(SemHandle))
    {
      /* Semaphore exclusively owned by another process --  */
      /* cannot clear now.                                  */
    }
  }
  else
  {
    /* Semaphore not obtained: error processing (i.e. switch on rc) */
  }
  /* Semaphore no longer needed; close it */
  if(DosCloseSem(SemHandle))
  {
    /* Semaphore is still set -- cannot close now */
  }
}
</PRE>


===MASM Binding===
<PRE>
EXTRN  DosSemClear:FAR
INCL_DOSSEMAPHORES  EQU 1

PUSH   DWORD   SemHandle     ;Semaphore handle
CALL   DosSemClear

Returns WORD
</PRE>

==Related Functions==
* 

[[Category:The OS/2 API Project]]