DosSetNmPipeSem

Bindings:  C, MASM 

This call attaches a system semaphore to a local named pipe. 

 DosSetNmPipeSem     (Handle, SemHandle, KeyHandle) 
 

 Handle (HPIPE) - input 
    Handle of the named pipe returned by DosMakeNmPipe or DosOpen. 

 SemHandle (HSEM) - input 
    A system semaphore handle that is cleared when the pipe (identified by 
    Handle) has read data or write space available. 

 KeyHandle (USHORT) - input 
    An arbitrary value that is used to associate named pipe actions with 
    result codes in DosQNmPipeSemState. 

 rc (USHORT) - return 
    Return code descriptions are: 

    0         NO_ERROR 
    6         ERROR_INVALID_HANDLE 
    87        ERROR_INVALID_PARAMETER 
    120       ERROR_INVALID_FUNCTION 
    187       ERROR_SEM_NOT_FOUND 
    230       ERROR_BAD_PIPE 
    233       ERROR_PIPE_NOT_CONNECTED 
 
 Remarks 

 This call is intended for use only with local named pipes. If an attempt 
 is made to attach a semaphore to a remote named pipe, 
 ERROR_INVALID_FUNCTION is returned. 

 DosSetNmPipeSem supports serving applications that need to handle a large 
 number of incoming pipes. By using semaphores, the application avoids 
 such resource-consuming methods as dedicating a thread for each incoming 
 pipe, or polling each pipe with non-blocking I/O. Instead, the 
 application issues a DosSemWait or a  DosMuxSemWait and waits for 
 notification that I/O can be performed. 

 The system semaphore indicated by SemHandle is attached to the named pipe 
 indicated by Handle. Up to two semaphores may be attached to a pipe, one 
 for the serving side and one for the client side.  If a semaphore is 
 already attached to a side of the pipe, the semaphore is overridden. 

 The arbitrary value assigned to KeyHandle as input for DosSetNmPipeSem is 
 used by DosQNmPipeSemState as output. This enables the application to 
 distinguish events specific to a particular pipe when several pipes are 
 attached to the same semaphore. DosQNmPipeSemState can be used to provide 
 additional information about the I/O that can be performed on the set of 
 pipes.