A client process can open the client end of a named pipe by using DosOpen. DosOpen opens the client end of a pipe by name and returns a handle. The application must use the appropriate pipe name and access modes to open the pipe for reading, writing, or both. (To open a pipe on a remote computer, the client process must also specify the name of the computer system as part of the pipe name, as follows:
\\ComputerName\PIPE\PipeName.)
If a pipe name includes a remote LAN server name, DosOpen attempts to open the pipe on a remote computer. The server process can then read input from the client process through the pipe.
The following code fragment opens a remote pipe, reads from the standard input (usually the keyboard), and sends the information to the server process through the pipe:
#define INCL_DOSQUEUES /* Queue values */
#include <os2.h>
#define PIPESIZE 256
#define SERVER_PIPE_NAME "\\\\myserver\\pipe\\mypipe"
#define HF_STDIN 0 /* Standard input handle */
HPIPE hp;
BYTE abBuf[PIPESIZE];
ULONG ulAction, ulRead, ulWritten;
APIRET ulrc;
ulrc = DosOpen(SERVER_PIPE_NAME,
&hp,
&ulAction,
0,
FILE_NORMAL,
FILE_OPEN,
OPEN_ACCESS_READWRITE |
OPEN_SHARE_DENYNONE,
(PEAOP) NULL);
if (ulrc)
DosExit(EXIT_PROCESS,
0); /* Open pipe failed */
do { /* Open pipe succeeded */
DosRead(HF_STDIN,
abBuf,
sizeof(abBuf),
&ulRead);
DosWrite(hp,
abBuf,
ulRead,
&ulWritten); /* Writes to the pipe */
} while (ulRead > 2); /* Stop on a blank line */
DosClose(hp);
The client process checks the return value from DosOpen to verify that the pipe was actually opened. If the server process has not yet created the pipe, DosOpen returns an error. When the client process finishes using the pipe, it closes the pipe by using DosClose.
When a named pipe is opened, its initial state is set by the system to block read and write operations (blocking mode), and to read data as a byte stream (byte-read mode). However, the client can change these modes by calling DosSetNPHState. A call to DosOpen fails if all instances of the named pipe are already open.
The open also fails if the pipe has been closed by a client, but the server has not called DosDisConnectNPipe (to acknowledge the client's close), followed by DosConnectNPipe (to prepare the pipe for the next client). In both of these situations, ERROR_PIPE_BUSY is returned.
If all instances of a named pipe are busy, a client process can call DosWaitNPipe to wait for an instance to become available before it calls DosOpen again.
After a pipe instance has been opened by a client, that same instance cannot be opened by another client at the same time. However, the opening process can duplicate the handle as many times as desired by calling DosDupHandle. This enables child processes to share access to a pipe instance with a parent process.
The access-mode and sharing-mode fields that are specified for DosOpen must be the same as those that were specified by the server when it created the pipe with DosCreateNPipe.