DosCreateSem

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:
• 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.

  ---

  [Back: DosCreateQueue]
  [Next: DosCreateThread]