DosCloseSem

Legacy Function Warning
It is recommended to use a newer replacement for this function.
Replacement:
Remarks:	This function is part of the OS2 1.x API. It is not recommended to be used for modern development on OS/2.

This call closes a handle to a system semaphore, obtained with a DosCreateSem or DosOpenSem request.

Syntax

DosCloseSem (SemHandle)

Parameters

SemHandle (HSEM) - input

Handle returned from a previous DosCreateSem or DosOpenSem call.

Return Code

rc (USHORT) - return

Return code descriptions are:

• 0 NO_ERROR
• 102 ERROR_SEM_IS_SET

Remarks

DosCloseSem is issued to close a handle to a system semaphore. When all processes that obtained handles to the semaphore with DosCreateSem or DosOpenSem requests have issued DosCloseSem, the semaphore is deleted and must be redefined by the next user with a call to DosCreateSem.

If a process has created a nonexclusive system semaphore and terminates while the semaphore is open, the system closes the handle to the semaphore that was returned by DosCreateSem. If the process is currently holding the semaphore when it terminates, OS/2 clears the semaphore and returns ERROR_SEM_OWNER_DIED to the next thread that gets the resource because of a DosSemRequest call. This error message alerts the holder of the semaphore that the semaphore owner may have ended abnormally; consequently, the resource is in an indeterminate state. The thread should take appropriates steps to protect the integrity of the resource. Upon completion of cleanup activity, the thread can release the semaphore by calling DosSemClear. This call resets the error condition flagged in the semaphore data structure and makes the semaphore available to the next user of the resource. The semaphore remains available to all processes that obtained handles to it with DosOpenSem requests until they call DosCloseSem to release the semaphore handles.

If a process has created an exclusive system semaphore and terminates while the semaphore is open, ownership of the semaphore is transferred to the thread executing any exit list routines. If no exit list routines have been identified to the system with DosExitList, the system closes the handle to the semaphore.

Bindings

C

#define INCL_DOSSEMAPHORES

USHORT  rc = DosCloseSem(SemHandle);

HSEM    SemHandle;     /* Semaphore handle  */

USHORT  rc;            /* return code */

MASM

EXTRN  DosCloseSem:FAR
INCL_DOSSEMAPHORES  EQU 1

PUSH   DWORD   SemHandle     ;Semaphore handle
CALL   DosCloseSem

Returns WORD

Example

This example creates a semaphore named timeout.sem, then closes it.

#define INCL_DOSSEMAPHORES

#define SEM_OWNERSHIP 0
#define SEM_NAME "\\SEM\\timeout.sem"

HSEM   SemHandle;
USHORT rc;

   if(!DosCreateSem(SEM_OWNERSHIP,    /* Indicate ownership */
                    &SemHandle,       /* Semaphore handle */
                    SEM_NAME))        /* Semaphore name string */
      rc = DosCloseSem(SemHandle);    /* Semaphore handle */

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.

#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 */
  }
}