DosRequestMutexSem

DosRequestMutexSem blocks until ownership of a mutex semaphore may be obtained. Ownership of a semaphore with multiple threads requesting it is granted to the thread with the highest priority. Among threads with the same priority, ownership is granted in a First-In-First-Out (FIFO) manner.

Syntax
DosRequestMutexSem( hmtxSemaphore, ulTimeOut )

Parameters
returning.
 * HMTX hmtxSemaphore (input):The handle of the semaphore to be released.
 * ULONG ulTimeout (input):The number of milliseconds the function will wait before
 * Set to SEM_IMMEDIATE_RETURN (0), the function will return immediately regardless of whether or not the semaphore is free.
 * Set to SEM_INDEFINITE_WAIT (-1), the function will block indefinitely (forever) until the semaphore becomes free and ownership is obtained.

Returns

 * APIRET rc:The following values can be returned

Gotchas
The process calling DosRequestMutexSem must first obtain access to the semaphore in question or ERROR_INVALID_HANDLE will be returned.

Sample Code

 * 1) define INCL_DOSSEMAPHORES
 * 2) include 

HMTX hmtxMySemaphore;     /* MySemaphore handle */ ULONG TimeOut= -1;        /* the number of milliseconds the */ /* the caller will block for the sem */ /* this example will block forever */

/* access is gained to the semaphore in question */ /* either by DosCreateMutexSem ... */	/* ... or by DosOpenMutexSem */ /* its handle is placed in hmtxMySemaphore */

rc = DosRequestMutexSem(hmtxMySemaphore, TimeOut);

if (rc != 0) {	 /* We got an error to take care of. */	}