DosCloseSem

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.

C

 * 1) 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. 
 * 1) define INCL_DOSSEMAPHORES


 * 1) define SEM_OWNERSHIP 0
 * 2) 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. 
 * 1) define INCL_DOSSEMAPHORES


 * 1) include 


 * 1) define SEM_NAME "\\SEM\\resource.sem" /* Semaphore name */
 * 2) 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 */ } } 