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

#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 */
	}

See Also

• DosCloseEventSem
• DosOpenEventSem
• DosPostEventSem
• DosQueryEventSem
• DosResetEventSem
• DosWaitEventSem

Alternative Version

1. OS2Linux project (Common Public License) created a clone for this function [1].