DosSetNPHState

Resets the blocking mode and the read mode of a named pipe.

Syntax

#define INCL_DOSNMPIPES
#include <os2.h>

HPIPE     hpipe;  /*  The named-pipe handle to reset. */
ULONG     state;  /*  The named-pipe handle state. */
APIRET    ulrc;   /*  Return Code. */

ulrc = DosSetNPHState(hpipe, state);

Parameters

hpipe (HPIPE) - input

The named-pipe handle to reset.

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

state (ULONG) - input

The named-pipe handle state.

This parameter consists of the following bit fields:

Bit    Description 
31-16  Reserved. 
15     Blocking mode. The blocking mode is defined as either "blocking"
       or "nonblocking," as follows:
       0   NP_WAIT (0x0000) 
           Blocking mode: DosRead and DosWrite wait if no data is available.
       1   NP_NOWAIT (0x8000)
           Nonblocking mode: DosRead and DosWrite return immediately if no data is available.

DosRead normally blocks (waits) until at least partial data can be returned. DosWrite blocks by default until all of the requested bytes have been written. Nonblocking mode changes this behavior as follows:

DosRead returns immediately with a value of zero for pcbActual if no data is available.

DosWrite returns a value of zero for pcbActual if there is not enough buffer space available in the pipe; otherwise, the entire data area is transferred.

14-10  Reserved. 
9-8    Read Mode. The read mode is defined as follows:
       00  NP_READMODE_BYTE (0x0000)
           Byte-read mode: Read the pipe as a byte stream. 
       01  NP_READMODE_MESSAGE (0x0100)
           Message-stream mode: Read the pipe as a message stream.
7-0    Reserved, must be set to 0.

Return Code

ulrc (APIRET) - returns

DosSetNPHState returns one of the following values:

• 0 NO_ERROR
• 87 ERROR_INVALID_PARAMETER
• 230 ERROR_BAD_PIPE
• 231 ERROR_PIPE_BUSY
• 233 ERROR_PIPE_NOT_CONNECTED

Remarks

DosSetNPHState resets the blocking mode and the read mode of a named pipe. Both the blocking mode and the read mode must be specified. However, the read mode cannot be changed if the pipe is a byte pipe. (Byte pipes can be read only as byte streams.) In addition, the blocking mode cannot be changed to nonblocking if another thread is currently blocked on an I/O request to the same end of the pipe.

Example Code

This example handles the client side of a pipe. It opens an existing named pipe, sets and queries the pipe handle state, sends a message to the host, reads the host reply, and finally closes the pipe.

Before running this example, compile and run the example code shown in the DosConnectNPipe, DosCreateNPipe, DosDisConnectNPipe, or DosSetNPipeSem functions, which handles the host side of the pipe.

 
#define INCL_DOSFILEMGR       /* DOS File Manager values */
#define INCL_DOSNMPIPES       /* DOS Named Pipes values */
#define INCL_DOSSEMAPHORES    /* DOS Semaphore values */
#define INCL_DOSERRORS        /* DOS Error values */
#include <os2.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

int main(VOID) {
   APIRET   rc                     = NO_ERROR;   /* Return code */
   CHAR     message[256]           = "";         /* Message buffer */
   HFILE    PipeHandle             = NULLHANDLE; /* Pipe handle */
   struct   _AVAILDATA  BytesAvail = {0};
   UCHAR    Buffer[200]            = {0};
   ULONG    bytes                  = 0;
   ULONG    Action                 = 0;
   ULONG    PipeState              = 0;
   ULONG    HandType               = 0;
   ULONG    FlagWord               = 0;
   ULONG    BytesRead              = 0;

   rc = DosOpen("\\PIPE\\EXAMPLE", &PipeHandle, &Action, 0, 0, FILE_OPEN,
                OPEN_ACCESS_READWRITE | OPEN_SHARE_DENYREADWRITE |
                OPEN_FLAGS_FAIL_ON_ERROR, NULL);
   if (rc != NO_ERROR) {
      printf("DosOpen error: error code = %u\n", rc);
      return 1;
   } else printf("Connected to HOST\n");

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

   rc = DosQueryNPHState(PipeHandle, &PipeState);
   if (rc != NO_ERROR) {
      printf("DosQueryNPHState error: error code = %u\n", rc);
      return 1;
   } else {
      printf("Pipe handle state is: %x\n", PipeState);
   }  /* endif */
   printf("Enter message to send to PIPEHOST: ");

   fflush(NULL);  /* Force above printf prompt to display */
   gets(message);

   rc = DosWrite(PipeHandle, message, strlen(message), &bytes);
   if (rc != NO_ERROR) {
      printf("DosWrite error: error code = %u\n", rc);
      return 1;
   }

   rc = DosRead(PipeHandle, message, sizeof(message), &bytes);
   if (rc != NO_ERROR) {
      printf("DosRead error: error code = %u\n", rc);
      return 1;
   }

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

   rc = DosClose(PipeHandle);
   /* Should check if (RC == NO_ERROR)  here... */

   printf("...Disconnected\n");
   return NO_ERROR;
}

Related Functions

• DosCallNPipe
• DosClose
• DosConnectNPipe
• DosCreateNPipe
• DosDisConnectNPipe
• DosDupHandle
• DosOpen
• DosPeekNPipe
• DosQueryNPHState
• DosQueryNPipeInfo
• DosQueryNPipeSemState
• DosRead
• DosResetBuffer
• DosSetNPipeSem
• DosTransactNPipe
• DosWaitNPipe
• DosWrite