DosCreateSem

Bindings:  C, MASM 

This call creates a system semaphore used by multiple asynchronous threads 
to serialize their access to resources. 

 DosCreateSem     (NoExclusive, SemHandle, SemName) 
 

 NoExclusive (USHORT) - input 
    Indicates whether or not the process creating the semaphore wants 
    exclusive use of the semaphore. The meanings for the settings of this 
    flag are: 

    Value     Definition 
    0         The creating process has exclusive use of the semaphore. 
              Only threads of the creating process may alter the state of 
              the semaphore with semaphore function calls. 
    1         The creating process has nonexclusive use of the semaphore. 
              Threads of other processes, as well as those of the creating 
              process, may alter the state of the semaphore with semaphore 
              function calls. 

 SemHandle (PHSYSSEM) - output 
    Address of handle of the new system semaphore. 

 SemName (PSZ) - input 
    Address of the name of the system semaphore. A system semaphore is 
    defined within the file system name space as a pseudo file; thus, a 
    semaphore has a full path name. The ASCIIZ string specifying the name 
    must include \SEM\ as the first element of the path. For example, 
    \SEM\RETRIEVE\SIGNAL.SEM is a valid semaphore name. 

    Although a system semaphore name takes the form of a file in a 
    subdirectory called \SEM, this subdirectory does not exist. System 
    semaphores and their names are kept in memory. 

    If your application provides long name support for an installable file 
    system, a semaphore name is not restricted to the DOS 8.3 filename 
    format. 

 rc (USHORT) - return 
    Return code descriptions are: 

    0         NO_ERROR 
    87        ERROR_INVALID_PARAMETER 
    100       ERROR_TOO_MANY_SEMAPHORES 
    123       ERROR_INVALID_NAME 
    183       ERROR_ALREADY_EXISTS 
 
 Remarks 

 A call to DosCreateSem creates a system semaphore, which can be 
 manipulated by threads issuing semaphore function calls. Manipulation of 
 a system semaphore is most often used to control access to a serially 
 reusable resource. Manipulation of the semaphore is also used to signal 
 the occurrence of an event to waiting threads. 

 To control access to a serially reusable resource, a process creates the 
 system semaphore with a call to DosCreateSem. If the users of the 
 resource are asynchronous threads of the creating process, NoExclusive=0 
 is specified to create an exclusive system semaphore. If the users of the 
 resource include threads of other processes, NoExclusive=1 is specified 
 to create a nonexclusive system semaphore. 

 DosCreateSem returns a semaphore handle used by the creating process and 
 any of its threads to access the semaphore. If the semaphore is 
 nonexclusive, a process other than the semaphore creator calls DosOpenSem 
 for a handle to access the semaphore. 

 Ownership of the system semaphore is established by a successful 
 DosSemRequest call. If another thread issues DosSemRequest while the 
 semaphore is owned, the thread can block and wait for the semaphore to 
 become available, or it can return immediately. 

 After accessing the resource, the owning thread can clear the semaphore 
 by a call to DosSemClear. If the semaphore is an exclusive system 
 semaphore, it has a use count associated with it, which is incremented by 
 DosSemRequest calls and decremented by DosSemClear calls. The semaphore 
 is not actually cleared and made available to the next thread waiting to 
 use the resource until the semaphore has been cleared the same number of 
 times it has been requested. This means that exclusive system semaphores 
 can be used in recursive routines. 

 If a process has created a nonexclusive system semaphore and terminates 
 while the semaphore is open, the system closes the handle to the 
 semaphore that was returned by DosCreateSem. If the process is currently 
 holding the semaphore when it terminates, OS/2 clears the semaphore and 
 returns ERROR_SEM_OWNER_DIED to the next thread that gets the resource 
 because of a DosSemRequest call. This error message alerts the holder of 
 the semaphore that the semaphore owner may have ended abnormally; 
 consequently, the resource is in an indeterminate state.  The thread 
 should take appropriates  steps to protect the integrity of the resource. 
  Upon completion of cleanup activity, the thread can release the 
 semaphore by calling DosSemClear. This call resets the error condition 
 flagged in the semaphore data structure and makes the semaphore available 
 to the next user of the resource. The semaphore remains available to all 
 processes that obtained handles to it with DosOpenSem requests until they 
 call DosCloseSem to release the semaphore handles. 

 If a process has created an exclusive system semaphore and terminates 
 while the semaphore is open, ownership of the semaphore is transferred to 
 the thread executing any exit list routines. If no exit list routines 
 have been identified to the system with DosExitList, the system closes 
 the handle to the semaphore. 

 In addition to controlling access to serially reusable resources, a 
 nonexclusive system semaphore is also used to signal an event, such as 
 the removal of an element from a queue, to other processes. A process 
 that sets the semaphore waits for another process to clear the semaphore, 
 signaling the event. When the signaling process issues a DosSemClear, any 
 waiting threads resume execution. Calls that support setting and waiting 
 upon a nonexclusive semaphore by one or more threads are DosSemSet, 
 DosSemWait,  DosSemSetWait, and DosMuxSemWait. 

 Note:  If a thread needs to signal another thread of the same process, a 
        RAM semaphore is used.