DosOpenEventSem: Difference between revisions
mNo edit summary |
|||
| (2 intermediate revisions by the same user not shown) | |||
| Line 1: | Line 1: | ||
== Syntax == | |||
DosOpenEventSem( ''pszSemaphoreName'', ''phevSemaphore'' ) | |||
=== 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 handle contained in ''phevSemaphore'' will be used. | |||
This is a pointer to a null-terminated string containing the name of the semaphore to gain access to. | ;PHEV ''phevSemaphore'' (input/output) | ||
:This is a pointer to the HEV 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 ''phevSemaphore'' must be NULL or ERROR_INVALID_PARAMETER will be returned. On successful return of this function, ''phevSemaphore'' will point to a Event handle (HEV) containing the opened semaphore. | |||
PHEV ''phevSemaphore'' (input/output) | |||
=== Returns === | === Returns === | ||
;APIRET rc:The following values can be returned: | |||
:{|class="wikitable" | |||
The following values can be returned | |0||NO_ERROR||Semaphore opened successfully | ||
{| | |||
| | |||
| | |||
|NO_ERROR | |||
|Semaphore opened successfully | |||
|- | |- | ||
|6 | |6||ERROR_INVALID_HANDLE||Error, The value in ''phevSemaphore'' does not point to a valid semaphore | ||
|ERROR_INVALID_HANDLE | |||
|Error, The value in ''phevSemaphore'' does not point to a valid semaphore | |||
|- | |- | ||
|8 | |8||ERROR_NOT_ENOUGH_MEMORY||Error, The system memory limit has been exceeded | ||
|ERROR_NOT_ENOUGH_MEMORY | |||
|Error, The system memory limit has been exceeded | |||
|- | |- | ||
|87 | |87||ERROR_INVALID_PARAMETER||Error, One or more parameters is not recognized, See parameters above | ||
|ERROR_INVALID_PARAMETER | |||
|Error, One or more parameters is not recognized, See parameters above | |||
|- | |- | ||
|123 | |123||ERROR_INVALID_NAME||Error, The name pointed to by ''pszSemaphoreName'' has been rejected by the file system | ||
|ERROR_INVALID_NAME | |||
|Error, The name pointed to by ''pszSemaphoreName'' has been rejected by the file system | |||
|- | |- | ||
|187 | |187||ERROR_SEM_NOT_FOUND||Error, There is no semaphore with the name in ''pszSemaphoreName'' | ||
|ERROR_SEM_NOT_FOUND | |||
|Error, There is no semaphore with the name in ''pszSemaphoreName'' | |||
|- | |- | ||
|291 | |291||ERROR_TOO_MANY_OPENS||Error, The usage count for the semaphore in question has exceeded the system limit of 65535 | ||
|ERROR_TOO_MANY_OPENS | |} | ||
|Error, The usage count for the semaphore in question has exceeded the system limit of 65535 | |||
|} | |||
=== Usage Explanation === | === Usage Explanation === | ||
DosOpenEventSem gains access to a shared semaphore for the calling process. When access is granted to the calling process, DosOpenEventSem increments, by one (1), the usage count for the semaphore pointed to by ''phevSemaphore'' 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 95: | Line 56: | ||
=== See Also === | === See Also === | ||
[[ | *[[DosCloseEventSem]] | ||
*[[DosCreateEventSem]] | |||
*[[DosPostEventSem]] | |||
*[[DosQueryEventSem]] | |||
*[[DosResetEventSem]] | |||
*[[DosWaitEventSem]] | |||
[[Category: | [[Category:Dos]] | ||
Latest revision as of 01:50, 21 February 2020
Syntax
DosOpenEventSem( pszSemaphoreName, phevSemaphore )
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 phevSemaphore will be used.
- PHEV phevSemaphore (input/output)
- This is a pointer to the HEV 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 phevSemaphore must be NULL or ERROR_INVALID_PARAMETER will be returned. On successful return of this function, phevSemaphore will point to a Event handle (HEV) 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 phevSemaphore 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 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
DosOpenEventSem gains access to a shared semaphore for the calling process. When access is granted to the calling process, DosOpenEventSem increments, by one (1), the usage count for the semaphore pointed to by phevSemaphore or named in pszSemaphoreName.
Sample Code
#define INCL_DOSSEMAPHORES
#include <os2.h>
UCHAR SemName[15];
PHEV phevMySemaphore= NULL; /* pointer to my semaphore handle */
/* a shared Event semaphore is successfully created in another process */
/* its name happens to be \SEM32\MySem */
strcpy(SemName,"\\SEM32\\MySem");
rc = DosOpenEventSem(SemName, phevMySemaphore);
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, phevMySemaphore */
}