DosCreateMuxWaitSem

From EDM2
Jump to: navigation, search

DosCreateMuxWaitSem creates a private or shared MuxWait semaphore. The usage count is incremented to 1. The process creating the semaphore does not need to open it also.

Syntax

rc = DosCreateMuxWaitSem(  pszSemaphoreName,
                           phmuxSemaphore,
                           ulNumberOfRecords,
                           pSemaphoreRecord,
                           ulfAttributes );

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.
PHMUX phmuxSemaphore (output)
This is a pointer to the HMUX that will get the handle to the new semaphore.
ULONG ulNumberOfRecords (input)
This is the number of records that are pointed to by pSemaphoreRecord. 64 is the maximum number of records allowable in a muxwait list.
PSEMRECORD pSemaphoreRecord (input)
This points to an array of SEMRECORD structures that are to be added to the muxwait list.
ULONG ulfAttributes (input)
This contains the attribute flags relevant to the creation of the semaphore. As of this writing three values may be set for ulAttributeFlags, they are

DC_SEM_SHARED, DCMW_WAIT_ANY and DCMW_WAIT_ALL.

  • ulAttributeFlags is checked for DC_SEM_SHARED value only if pszSemaphoreName is NULL. If ulAttributeFlags equals DC_SEM_SHARED then the semaphore is considered an unnamed, shared semaphore.
  • DCMW_WAIT_ANY indicates the semaphore is to unblock if any of the semaphores in the muxwait list post (event semaphore) or release (mutex semaphore).
  • DCMW_WAIT_ALL indicates the semaphore is to unblock only if all of the semaphores in the muxwait list post (event semaphore) or release (mutex semaphore).

Returns

APIRET rc

The following values can be returned

0 NO_ERROR Operation was successful.
6 ERROR_INVALID_HANDLE Error, The calling process must first have access to the shared semaphore in question before adding it to the muxwait list
8 ERROR_NOT_ENOUGH_MEMORY Error, Memory limit has been exceeded
87 ERROR_INVALID_PARAMETER Error, Unrecognized parameter
100 ERROR_TOO_MANY_SEMAPHORES Error, The value in ulNumberOfRecords cannot exceed 64
105 ERROR_SEM_OWNER_DIED Error, The owner of a semaphore in the muxwait list has died before releasing it
123 ERROR_INVALID_NAME Error, Name in pszSemaphoreName was rejected by file system
284 ERROR_DUPLICATE_HANDLE Error, The muxwait list pointed to by pSemaphoreRecord contains duplicate entries
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
292 ERROR_WRONG_TYPE Error, One or more entries in the muxwait list pointed to by pSemaphoreRecord is of the wrong type, MuxWait semaphores may not be added to a muxwait list, if the MuxWait semaphore is shared then only shared semaphores may be added to the list, If the MuxWait semaphore is private than the list may contain both shared and private semaphores

Sample Code

#define INCL_DOSSEMAPHORES
#include <os2.h>
#include <string.h>

PUCHAR    SemName;          /* Pointer to the Semaphore Name          */
PHMUX     phmuxMySemaphore; /* pointer to my new semaphore handle     */
ULONG     ulAttribs= 0;     /* Attribute flags, not used in this case */
SEMRECORD SemRecord;        /* Record containing info about the sem
                               I want to add to MySemaphore's list    */
int main(){
   /* put the semaphore name in SemName */
   strcpy(SemName,"\\SEM32\\MySem");

   /* SemRecord is filled with appropriate information about
      the semaphore I wish to add to hmuxMySemaphore's list  */
   rc = DosCreateMuxWaitSem( SemName,
                             phmuxMySemaphore,
 	                      1,                /* 1 record to add */
	                      &SemRecord,
	                      ulAttribs);

    if (rc != 0){
	 /* We got an error to take care of. */
    }
}

See Also