[ Home | Alpha index | Topic index | Tutorials | Download | Feedback ]

The OS/2 API Project

DosOpenMutexSem

[ Syntax | Params | Returns | Include | Usage | Structs | Gotchas | Code | Also ]

Syntax

 rc = DosOpenMutexSem( pszSemaphoreName, phmtxSemaphore );

Parameters
PSZ pszSemaphoreName (input)
This is a pointer to a null-terminated string containing the name of the semaphore to gain access to. If pszSemaphoreName equals NULL then the handle contained in phmtxSemaphore will be used.

PHMTX phmtxSemaphore (input/output)
This is a pointer to the HMTX containing the handle of the semaphore to be opened. If the semaphore is to be opened by name using pszSemaphoreName then the input value of phmtxSemaphore must be NULL or ERROR_INVALID_PARAMETER will be returned. On successful return of this function, phmtxSemaphore will point to a mutex handle (HMTX) containing the opened semaphore.

Returns
APIRET rc
The following values can be returned
0NO_ERRORSemaphore opened successfully
6ERROR_INVALID_HANDLEError, The value in phmtxSemaphore does not point to a valid semaphore
8ERROR_NOT_ENOUGH_MEMORYError, The system memory limit has been exceeded
87ERROR_INVALID_PARAMETERError, One or more parameters is not recognized, See parameters above
105ERROR_SEM_OWNER_DIEDError, The process that owns the semaphore has died before releasing it, DosQueryMutexSem can determine which process died
123ERROR_INVALID_NAMEError, The name pointed to by pszSemaphoreName has been rejected by the file system
187ERROR_SEM_NOT_FOUNDError, There is no semaphore with the name in pszSemaphoreName
291ERROR_TOO_MANY_OPENSError, The usage count for the semaphore in question has exceeded the system limit of 65535

Include Info

 #define INCL_DOSSEMAPHORES
#include <os2.h>

Usage Explanation

 DosOpenMutexSem gains access to a shared semaphore for the calling process. When access is granted to the calling process, DosOpenMutexSem increments, by one (1), the usage count for the semaphore pointed to by phmtxSemaphore or named in pszSemaphoreName.

Relevant Structures

Gotchas

Sample Code

 #define INCL_DOSSEMAPHORES #include <os2.h> UCHAR SemName[15]; PHMTX phmtxMySemaphore= NULL; /* pointer to my semaphore handle */ /* a shared mutex semaphore is successfully created in another process */ /* its name happens to be \SEM32\MySem */ strcpy(SemName,"\\SEM32\\MySem"); rc = DosOpenMutexSem(SemName, phmtxMySemaphore); if (rc != 0) { /* We got an error to take care of. */ } else { /* The semaphore was successfully opened */ /* it may be accessed via the handle pointer, phmtxMySemaphore */ }

See Also

 DosCloseMutexSem, DosCreateMutexSem, DosQueryMutexSem, DosReleaseMutexSem, DosRequestMutexSem

Author

Joe Phillips - jaiger@eng2.uconn.edu

Additions

Last modified May 27/1996
Please send all errors, comments, and suggestions to: timur@vnet.ibm.com

The OS/2 API Project

DosOpenMutexSem