DosWaitNPipe

Waits for a named-pipe instance to become available.

Syntax

DosWaitNPipe(pszName, msec)

Parameters

pszName (PSZ) - input

A pointer to the ASCIIZ name of the pipe to be opened.

msec (ULONG) - input

The maximum time, in milliseconds, to wait for a named-pipe instance to become available.

When a value of 0 is specified, DosWaitNPipe uses the value of msec that was specified when the pipe was created with DosCreateNPipe. When a value of -1 is specified, DosWaitNPipe waits indefinitely.

Return Code

ulrc (APIRET) - returns

DosWaitNPipe returns one of the following values:

• 0 NO_ERROR
• 2 ERROR_FILE_NOT_FOUND
• 95 ERROR_INTERRUPT
• 121 ERROR_SEM_TIMEOUT
• 230 ERROR_BAD_PIPE
• 231 ERROR_PIPE_BUSY

Remarks

DosWaitNPipe enables a client process to wait for a named-pipe instance to become available when all instances are busy. It should be used only when ERROR_PIPE_BUSY is returned from a call to DosOpen.

The msec parameter of DosWaitNPipe places a limit on the amount of time the calling process waits for a named-pipe instance to become available, as follows:

• If the time limit is reached before a pipe instance becomes available, ERROR_SEM_TIMEOUT is returned.
• If a time limit of 0 is specified, the system uses the default time-out value that was specified when the pipe was created with DosCreateNPipe.
• If a time limit of -1 is specified, DosWaitNPipe waits indefinitely.

If DosWaitNPipe is successful, the client must again call DosOpen to gain access to the pipe instance.

If more than one client process is blocked on a DosWaitNPipe request, the system gives the next available pipe instance to the process whose thread has the highest priority. If all of the waiting threads have the same priority, the thread that has been waiting the longest receives the next pipe instance.

Note

The priority of a thread can be changed by calling DosSetPriority.

ERROR_BAD_PIPE is returned if you specify an invalid name or file handle.

Example Code

This example handles the client side of a pipe. It attempts to open an existing named pipe, if the pipe is not available, it uses this API to wait until it becomes available and opens it. It then sets 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 == ERROR_PIPE_BUSY)
      if (DosWaitNPipe("\\PIPE\\EXAMPLE", 30000)) {
         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;
   }

   printf("Enter message to send to PIPEHOST: ");

   fflush(NULL);  /* Cause above printf to show on 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);
   printf("...Disconnected\n");
   return NO_ERROR;
}

Related Functions

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