DosOpenSem

This call opens an existing system semaphore that has been created by another process.

Syntax

DosOpenSem (SemHandle, SemName)

Parameters

SemHandle (PHSEM) - output 

Address of the handle of the system semaphore created by DosCreateSem. This handle must be supplied by any requests directed to the same semaphore.

SemName (PSZ) - input 

Address of the name of the system semaphore created by using DosCreateSem.

Return Code

rc (USHORT) - return

Return code descriptions are:

• 0 NO_ERROR
• 100 ERROR_TOO_MANY_SEMAPHORES
• 106 ERROR_SEM_USER_LIMIT
• 123 ERROR_INVALID_NAME
• 187 ERROR_SEM_NOT_FOUND

Remarks

A system semaphore that is created by a call to DosCreateSem with NoExclusive=1 specified returns a handle, which the creating process uses to access the semaphore. Another process that needs to access the semaphore must call DosOpenSem after the semaphore's creation. DosOpenSem merely returns the handle of the semaphore; it does not test or change the value of the semaphore.

If a process has access to any semaphores at the time it issues DosExecPgm to start a child process, the new process inherits the handles to these semaphores. However, the new process initially does not own any inherited semaphores, even if the parent process owns them at the time the child process is started. Semaphore ownership is obtained by a successful DosSemRequest call, and only one process can own the semaphore at a time.

When the last process that opened a particular semaphore with a DosCreateSem or DosOpenSem request closes its handle with a DosCloseSem request, the semaphore is deleted from memory and must be redefined by its next user with a call to DosCreateSem.

Bindings

C

#define INCL_DOSSEMAPHORES

USHORT  rc = DosOpenSem(SemHandle, SemName);

PHSEM   SemHandle;     /* Semaphore handle (returned) */
PSZ     SemName;       /* Semaphore name string */

USHORT  rc;            /* return code */

MASM

EXTRN  DosOpenSem:FAR
INCL_DOSSEMAPHORES  EQU 1

PUSH@  DWORD   SemHandle  ;Semaphore handle (returned)
PUSH@  ASCIIZ  SemName    ;Semaphore name string
CALL   DosOpenSem

Returns WORD

Example

The following example illustrates the notification of an event between threads of different processes. Process1 creates a nonexclusive system semaphore named process1.sem and sets it. It then invokes process2 to run asynchronously. Process1 then waits, with a timeout of 4.5 seconds, for process2 to open the semaphore and clear it, thereby notifying process1 to resume. Notice that there is a small possibility of process1 missing the notification because process2 may clear the semaphore before process1 issues DosSemWait. See the example for DosSemSetWait for an alternative that would correct this.

/* ----- process1.c ---- */

#define INCL_DOSSEMAPHORES
#define INCL_DOSPROCESS

#include <os2.h>


#define SEM_NAME "\\SEM\\process1.sem" /* Semaphore name */
#define TIMEOUT 4500L                  /* Timeout period */
#define START_PROGRAM "process2.exe"   /* Name of program file */

main()
{
  HSEM          SemHandle;
  CHAR          ObjFail [50];
  PSZ           Args;
  PSZ           Envs;
  RESULTCODES   ReturnCodes;
  USHORT        rc;

  printf("Process1 now running. \n");
  rc = DosCreateSem(CSEM_PUBLIC,       /* Ownership - nonexclusive */
                    &SemHandle,        /* Semaphore handle (returned) */
                    SEM_NAME);         /* Semaphore name string */
  printf("Process1.sem created; return code is %d \n", rc);

  /*** SET the semaphore. ***/
  if((rc = DosSemSet(SemHandle)))      /* Semaphore handle */

  /****************************************/
  {
    /* Cannot set semaphore -- error processing */
  }
  /* Start a separate process */
  if(!(DosExecPgm(ObjFail,           /* Object name buffer */
                  sizeof(ObjFail),   /* Length of obj. name buffer */
                  EXEC_ASYNC,        /* Execution flag - asynchronous */
                  Args,              /* Ptr. to argument string */
                  Envs,              /* Ptr. to environment string */
                  &ReturnCodes,      /* Ptr. to resultcodes struct. */
                  START_PROGRAM)))   /* Name of program file */
    printf("Process2 started. Process1 will try to wait for notification. \n");

  /*** WAIT for a notification from process2 on process1.sem ***/
  if((rc = DosSemWait(SemHandle,     /* Semaphore handle */
                      TIMEOUT)))     /* Timeout period */

  /****************************************/
  {
    /* No notification (either interrupt or timeout); error processing */
  }
  else
  {
    /* Notification received.  Normal processing */
    printf("Process2 cleared semaphore; process1 running again. \n");
  }
}

/* ----- process2.c ----*/

#define INCL_DOSSEMAPHORES

#include <os2.h>

#define SEM_NAME "\\SEM\\process1.sem"    /* Semaphore name */

main()
{
  HSEM SemHandle;
  USHORT rc;

  /* Obtain access to semaphore created by process1 via OPEN */
  if((rc=DosOpenSem(&SemHandle,           /* Semaphore handle
                                                  (returned) */
                    SEM_NAME)))           /* Semaphore Name */
  /****************************************/
  {
    /* Could not open -- error processing (switch on rc). */
  }
  else
  {
    /* Opened semaphore; normal processing.  Clear semaphore when done. */
    printf("Semaphore OPENED. \n");
    if(!(rc=DosSemClear(SemHandle)))      /* Semaphore handle */
      printf("Semaphore CLEARED. \n");
  }
}