DosOpenMutexSem: Difference between revisions
m Ak120 moved page OS2 API:CPI:DosOpenMutexSem to DosOpenMutexSem |
mNo edit summary |
||
| Line 1: | Line 1: | ||
=== Syntax === | === Syntax === | ||
rc = DosOpenMutexSem( ''pszSemaphoreName'', | rc = DosOpenMutexSem( ''pszSemaphoreName'', | ||
''phmtxSemaphore'' ); | ''phmtxSemaphore'' ); | ||
=== Parameters === | === Parameters === | ||
PSZ ''pszSemaphoreName'' (input) | ;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 | ||
This is a pointer to a null-terminated string containing the name of the | |||
semaphore to gain access to. | |||
handle contained in ''phmtxSemaphore'' will be used. | 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 === | === Returns === | ||
APIRET rc | |||
The following values can be returned | The following values can be returned | ||
{| border="1" | {| border="1" | ||
|- | |- | ||
| Line 60: | Line 46: | ||
|Error, The usage count for the semaphore in question has exceeded the system limit of 65535 | |Error, The usage count for the semaphore in question has exceeded the system limit of 65535 | ||
|} | |} | ||
=== Usage Explanation === | === 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''. | |||
=== Sample Code === | === Sample Code === | ||
<pre> | <pre> | ||
#define INCL_DOSSEMAPHORES | #define INCL_DOSSEMAPHORES | ||
#include | #include <os2.h> | ||
UCHAR SemName[15]; | UCHAR SemName[15]; | ||
| Line 103: | Line 75: | ||
} | } | ||
</pre> | </pre> | ||
=== See Also === | === See Also === | ||
[[ | *[[DosCloseMutexSem]] | ||
[[ | *[[DosCreateMutexSem]] | ||
[[ | *[[DosQueryMutexSem]] | ||
[[ | *[[DosReleaseMutexSem]] | ||
[[ | *[[DosRequestMutexSem]] | ||
[[Category: | [[Category:Dos]] | ||
Revision as of 06:20, 9 January 2017
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
| 0 | NO_ERROR | Semaphore opened successfully |
| 6 | ERROR_INVALID_HANDLE | Error, The value in phmtxSemaphore does not point to a valid semaphore |
| 8 | ERROR_NOT_ENOUGH_MEMORY | Error, The system memory limit has been exceeded |
| 87 | ERROR_INVALID_PARAMETER | Error, One or more parameters is not recognized, See parameters above |
| 105 | ERROR_SEM_OWNER_DIED | Error, The process that owns the semaphore has died before releasing it, DosQueryMutexSem can determine which process died |
| 123 | ERROR_INVALID_NAME | Error, The name pointed to by pszSemaphoreName has been rejected by the file system |
| 187 | ERROR_SEM_NOT_FOUND | Error, There is no semaphore with the name in pszSemaphoreName |
| 291 | ERROR_TOO_MANY_OPENS | Error, The usage count for the semaphore in question has exceeded the system limit of 65535 |
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.
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 */
}