DosSetNPipeSem

Description

Attaches a shared event semaphore to a local named pipe.

Syntax

#define INCL_DOSNMPIPES
#include <os2.h>

HPIPE     hpipe;  /* The named-pipe handle to which a semaphore is to be attached. */
HSEM      hsem;   /* The handle of an event semaphore or a multiple-wait (muxwait) semaphore
                     that is posted when the pipe (hpipe) has either data to be read
                      or write space available. */
ULONG     key;    /* A key value that distinguishes events arriving on different named pipes
                     that are attached to the same semaphore. */
APIRET    ulrc;   /* Return Code. */

ulrc = DosSetNPipeSem(hpipe, hsem, key);

Parameters

hpipe (HPIPE) - input

The named-pipe handle to which a semaphore is to be attached.

The server handle is returned by DosCreateNPipe; the client handle is returned by DosOpen.

hsem (HSEM) - input

The handle of an event semaphore or a multiple-wait (muxwait) semaphore that is posted when the pipe (hpipe) has either data to be read or write space available.

key (ULONG) - input

A key value that distinguishes events arriving on different named pipes that are attached to the same semaphore.

Return Code

ulrc (APIRET) - returns

DosSetNPipeSem returns one of the following values:

• 0 NO_ERROR
• 1 ERROR_INVALID_FUNCTION
• 6 ERROR_INVALID_HANDLE
• 87 ERROR_INVALID_PARAMETER
• 187 ERROR_SEM_NOT_FOUND
• 230 ERROR_BAD_PIPE
• 233 ERROR_PIPE_NOT_CONNECTED

Remarks

DosSetNPipeSem can be used with local pipes or on the client end of a remote pipe. (A remote pipe is the client end of a pipe created on a remote named pipe server.) If an attempt is made to attach a semaphore to the server end of a remote pipe, DosSetNPipeSem returns 1 (ERROR_INVALID_FUNCTION).

If a semaphore is already attached to the specified handle, DosSetNPipeSem replaces the existing semaphore with the new one.

Example Code

This example handles the host end of a named pipe for several other named pipe examples. Some return code checking has been omitted for brevity.

#define INCL_BASE
#define INCL_DOSSEMAPHORES
#define INCL_DOSNMPIPES
#include <os2.h>
#include <stdio.h>
#include <string.h>

int main(VOID) {
CHAR     PipeName[256] = "\\PIPE\\EXAMPLE" ;     /* Pipe name */
HPIPE    PipeHandle    = NULLHANDLE;             /* Pipe handle */
HEV      hev           = NULLHANDLE;             /* Semaphore handle */
ULONG    ulBytes       = 0;                      /* Bytes read or written */
CHAR     message[256]  = "";                     /* Input/Output buffer */
APIRET   rc            = NO_ERROR;               /* Return code */

   rc = DosCreateNPipe(PipeName,                /* Name of pipe to create */
                       &PipeHandle,             /* Handle returned for pipe */
                       NP_ACCESS_DUPLEX,        /* Duplex pipe */
                       NP_WAIT |
                       NP_TYPE_MESSAGE |
                       NP_READMODE_MESSAGE |
                       NP_WMESG |               /* Write messages */
                       NP_RMESG |               /* Read messages */
                       0x01,                    /* Unique instance of pipe */
                       sizeof(message),         /* Output buffer size */
                       sizeof(message),         /* Input buffer size */
                       0L);                     /* Use default time-out */
   if (rc != NO_ERROR) {
     printf("DosCreateNPipe error: return code = %u\n",rc);
     return 1;
   }

   rc = DosCreateEventSem("\\SEM32\\PIPE\\EXAMPLE", &hev, 0L, 0L);
   /* Should check if (rc != NO_ERROR)  here... This semaphore is not
      always used.                                                     */

   rc = DosSetNPipeSem(PipeHandle,       /* Handle for pipe */
                       (HSEM) hev,       /* Handle of semaphore */
                       1L);              /* Used to distinguish among events */
   if (rc != NO_ERROR) {
     printf("DosSetNPipeSem error: return code = %u\n",rc);
     return 1;
   }

   printf("Waiting for connection to pipe %s...\n",PipeName);

   rc = DosConnectNPipe(PipeHandle);
   if (rc != NO_ERROR) {
     printf("DosConnectNPipe error: return code = %u\n",rc);
     return 1;
   }

   printf("\nCONNECTED\nWaiting for a message...\n");
   rc = DosRead(PipeHandle,            /* Handle of pipe */
                message,               /* Buffer for message read */
                sizeof(message),       /* Buffer size */
                &ulBytes);             /* Number of bytes actually read */
   if (rc != NO_ERROR) {
     printf("DosRead error: return code = %u\n",rc);
     return 1;
   }

   printf("\n\nMessage received was: %s\n\n", message);

   strcpy(message, "Thank you for your message!");
   rc = DosWrite(PipeHandle,           /* Handle of pipe */
                 message,              /* Buffer containing message to write */
                 strlen(message),      /* Length of message */
                 &ulBytes);            /* Number of bytes actually written */
   if (rc != NO_ERROR) {
     printf("DosWrite error: return code = %u\n",rc);
     return 1;
   }

   rc = DosCloseEventSem(hev);
   /* Should check if (rc != NO_ERROR)  here... */

   rc = DosDisConnectNPipe(PipeHandle);
   /* Should check if (rc != NO_ERROR)  here... */

   return NO_ERROR;
}

Related Functions

• DosCallNPipe
• DosClose
• DosCloseMuxWaitSem
• DosConnectNPipe
• DosCreateEventSem
• DosCreateNPipe
• DosDisConnectNPipe
• DosDupHandle
• DosOpen
• DosPeekNPipe
• DosQueryNPHState
• DosQueryNPipeInfo
• DosQueryNPipeSemState
• DosRead
• DosResetBuffer
• DosSetNPHState
• DosTransactNPipe
• DosWaitNPipe
• DosWaitEventSem
• DosWaitMuxWaitSem
• DosWrite