Purpose

DosCreateEventSem creates an event semaphore.

Syntax

#define INCL DOSSEMAPHORES
#include  os2.h 

APIRET DosCreateEventSem

(PSZ pszName, PHEV phev, ULONG flAttr, BOOL32 fState)

Parameters

pszName PSZ) input

A pointer to the ASCIIZ name of the semaphore.

Semaphore names are validated by the file system, and must include the prefix \SEM32\. A maximum of 255 characters is allowed. If these requirements are not met, ERROR_INVALID_NAME is returned. If the semaphore already exists, ERROR_DUPLICATE_NAME is returned.

If this field is null, the semaphore is unnamed. Unnamed event semaphores can be either private or shared, depending on flAttr. They are identified by the semaphore handle that phev points to.

By default, all named semaphores are shared.

phev PHEV) output
A pointer to the handle of the event semaphore.
flAttr ULONG) input
A set of flags that specify the attributes of the event semaphore.

DC_SEM_SHARED

If the DC_SEM_SHARED bit is set, the semaphore is shared. Otherwise, this flag should be set to 0L. This bit is checked only if the semaphore is unnamed (that is, if pszName is null), because all named semaphores are shared.
DCE_AUTORESET (0x1000)
Causes the semaphore to be reset automatically at the time it is posted. 0x1000
DCE_POSTONE (0x0800)
Causes one thread only to be posted where multiple threads are waiting on an event semaphore created with this attribut. DCE_POSTONE also causes the semaphore to be reset automatically when it is posted.
fState BOOL32) input
Initial state of the semaphore.

Possible values are defined in the list below

• FALSE

  The initial state of the semaphore is reset.

• TRUE

  The initial state of the semaphore is posted.

Returns

ulrc APIRET) returns

Return Code.

DosCreateEventSem returns one of the following values

• NO_ERROR

• ERROR_NOT_ENOUGH_MEMORY

  87

  ERROR_INVALID_PARAMETER
  123
  ERROR_INVALID_NAME
  285
  ERROR_DUPLICATE_NAME
  290
  ERROR_TOO_MANY_HANDLES

  • DosCloseEventSem

  • DosOpenEventSem

  • DosPostEventSem

  • DosQueryEventSem

  • DosResetEventSem

  • DosWaitEventSem

  Example Code

  This example creates an event semaphore, and the asynchronous timer posts to it when its time interval expires. Finally, the event semaphore is closed.

  #define INCL_DOSSEMAPHORES   /* Semaphore values */#define INCL_DOSDATETIME     /* Timer support    */
  #define INCL_DOSERRORS       /* DOS error values */
  #include  os2.h 
  #include  stdio.h 
  
  int main(VOID)  
  
  PSZ     szSemName  = "\\SEM32\\TIMER\\THREAD1\\EVENT1"; /* Semaphore name */
  HEV     hevEvent1     = 0;                   /* Event semaphore handle    */
  HTIMER  htimerEvent1  = 0;                   /* Timer handle              */
  APIRET  rc            = NO_ERROR;            /* Return code               */
  
  rc = DosCreateEventSem(szSemName,      /* Name of semaphore to create  */
   hevEvent1,     /* Handle of semaphore returned */
  DC_SEM_SHARED,  /* Shared semaphore             */
  FALSE);         /* Semaphore is in RESET state  */
  if (rc != NO_ERROR)  
  printf("DosCreateEventSem error  return code = %u\n", rc);
  return 1;        
  
  rc = DosAsyncTimer(7000L,    /* 7 second interval            */
  (HSEM) hevEvent1,            /* Semaphore to post            */
   htimerEvent1);              /* Timer handler (returned)     */
  if (rc != NO_ERROR)  
  printf("DosAsyncTimer error  return code = %u\n", rc);
  return 1;
    else  
  printf("Timer will expire in about 7 seconds...\n");
   
  
  /* ... add your other processing here... */
  
  rc = DosWaitEventSem(hevEvent1,            /* Wait for AsyncTimer event */
  (ULONG) SEM_INDEFINITE_WAIT);              /* As long as it takes       */
  if (rc != NO_ERROR)  
  printf("DosWaitEventSem error  return code = %u\n", rc);
  return 1;
   
  
  rc = DosCloseEventSem(hevEvent1);      /* Get rid of semaphore       */
  if (rc != NO_ERROR)  
  printf("DosCloseEventSem error  return code = %u", rc);
  return 1;
   
  
  return NO_ERROR;
   
  

  ---

  [Back] [Next]