View source for DosCreateEventSem

This function is part of OS/2's [[Control Program]].

==Usage Explanation==
DosCreateEventSem creates a system event semaphore. The semaphore may be either private or shared and is accessable by all threads of the calling process.

==Syntax==
rc = DosCreateEventSem( pszSemaphoreName, phevSemaphore, ulAttributeFlags, f32InitialState );

==Parameters==
;PSZ pszSemaphoreName (input):This is a pointer to the null-terminated string containing the semaphore name. Any named semaphore is considered shared. An unnamed semaphore will be created with pszSemaphoreName set to NULL. The name of a semaphore must be prefixed by \SEM32\, cannot be longer than 255 characters and must conform to the naming conventions of the file system.
;PHEV phevSemaphore (output):This is a pointer to the HEV that will get the handle to the new semaphore.
;ULONG ulAttributeFlags (input):This contains the attribute flags relevant to the creation of the semaphore. As of this writing only one value may be set for ulAttributeFlags, it is DC_SEM_SHARED. ulAttributeFlags is checked for this value only if pszSemaphoreName is NULL. If ulAttributeFlags equals DC_SEM_SHARED then the semaphore is considered an unnamed, shared semaphore.
;BOOL32 f32InitialState (input):This boolean flag marks the initial state of the semaphore.
* Setting TRUE (0x00000001) makes the initial state of the semaphore owned and threads waiting on the semaphore will block.
* Setting FALSE (0x00000000) makes the initial state of the semaphore unowned and threads waiting on the semaphore will not block. 

==Returns==
APIRET rc

The following values can be returned 
 0	NO_ERROR	Semaphore created successfully
 8	ERROR_NOT_ENOUGH_MEMORY	Error, Memory limit has been exceeded
 87	ERROR_INVALID_PARAMETER	Error, Unrecognized parameter
 123	ERROR_INVALID_NAME	Error, Name in pszSemaphoreName was rejected by file system
 285	ERROR_DUPLICATE_NAME	Error, Name in pszSemaphoreName is in use
 290	ERROR_TOO_MANY_HANDLES	Error, System limit of 65536 semaphores has been exceeded

==Include Info==
 #define INCL_DOSSEMAPHORES
 #include <os2.h>

==Sample Code==
<PRE>
#define INCL_DOSSEMAPHORES
#include <os2.h>

UCHAR  SemName; /* Pointer to the Semaphore Name */
PHEV   phevMySemaphore; /* pointer to my new semaphore handle */
ULONG  ulAttribs= 0;     /* Attribute flags, not used in this case */
BOOL32 f32Owned= TRUE;  /* initial state of the semaphore, owned */

	/* put the semaphore name in SemName */
	strcpy(SemName,"\\SEM32\\MySem");  

	rc = DosCreateEventSem(SemName, phevMySemaphore, ulAttribs, f32Owned);

	if (rc != 0)
	{
	  /* We got an error to take care of. */
	}
	else
	{
	  /* creation was successful */
	  /* The semaphore may be accessed via the phevMySemaphore handle */
	}
</PRE>

==See Also==
* [[DosCloseEventSem]]
*[[DosOpenEventSem]]
*[[DosPostEventSem]]
*[[DosQueryEventSem]]
*[[DosResetEventSem]]
*[[DosWaitEventSem]]

==Alternative Version==
# OS2Linux project (Common Public License) created a clone for this function [https://github.com/OS2World/LINUX-SYSTEM-OS2Linux/blob/master/os2/semaphore.c].

[[Category:Dos]]