DosCreateMuxWaitSem

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

• DosAddMuxWaitSem
• DosCloseMuxWaitSem
• DosDeleteMuxWaitSem
• DosOpenMuxWaitSem
• DosQueryMuxWaitSem
• DosWaitMuxWaitSem