Pipe Category

The functions in the Pipe category control interprocess communications (IPC) for named pipes.

Function	Description
DosCallNmPipe	Opens a named pipe, performs a write to the pipe followed by a read, and then closes the pipe.
DosClose	Closes a named pipe.
DosConnectNmPipe	Waits for a client process to open an instance of a named pipe.
DosDisConnectNmPipe	Forces closed a named pipe, denying a client process any further access to it.
DosDupHandle	Duplicates the handle to a named pipe.
DosMakeNmPipe	Creates a new named pipe or a new instance of an existing named pipe, and returns its handle.
DosOpen	Opens the client process end of a named pipe and returns its handle.
DosPeekNmPipe	Reads the data in a named pipe without removing it.
DosQFHandState	Retrieves information about whether a named pipe’s handle is inheritable and whether write-behind to remote pipes is allowed.
DosQHandType	Returns the type of a specified handle.
DosQNmPHandState	Returns information about the current state of a named pipe.
DosQNmPipeInfo	Retrieves information about the sizes of a specified named pipe’s incoming and outgoing buffers and how many instances are available.
DosRead	Reads data from a named pipe.
DosSetFHandState	Modifies a named pipe’s open mode state.
DosSetNmPHandState	Modifies a named pipe’s read mode and blocking mode states.
DosTransactNmPipe	Writes a message to and then reads a message from a named pipe.
DosWaitNmPipe	Enables a client process to wait for an available instance of a named pipe.
DosWrite	Writes data to a named pipe.

A named pipe is a bi-directional interprocess communications (IPC) facility that allows two processes, either local or remote, to communicate with each other over the network. A process that creates a named pipe is known as a server process, and a process that establishes a connection to a named pipe is known as a client process.

To create an instance of a named pipe on the local computer, an application must call the DosMakeNmPipe function. This function specifies information that enables the server process to control the named pipe and allows client processes to access the named pipe. In order to create a named pipe, DosMakeNmPipe must know the following information:

the name chosen for the named pipe, in the format \pipe\name for a local named pipe).

the directions (inbound, outbound, full-duplex) that the named pipe can send and/or receive data

whether or not the named pipe’s handle can be passed to spawned processes

the number of concurrent instances of the named pipe that can be created

An inbound or outbound named pipe (synonymous with anonymous pipes used with other multi-tasking operating systems) allows a process to read only or to write only via one handle. A full-duplex named pipe allows a process to both read and write data via one handle.

In some applications, especially those that are emulating anonymous pipes, the handle of a named pipe can not be passed to a spawned process. Each time DosMakeNmPipe is called with the same parameter information, another instance of the named pipe is created. Each instance is associated with a unique handle that is returned by DosMakeNmPipe. Thus, if DosMakeNmPipe is called five times with the same information, five different instances (or handles) of the same named pipe are created.

Other low-level operating system parameters, such as the stream type and blocking mode of the named pipe, can be set. For more information on low-level parameters, see the DosMakeNmPipe function description.

Even though a server process creates a named pipe on a computer, client processes cannot access an instance of that named pipe until the server process calls DosConnectNmPipe. This function informs Advanced Server that a client process has permission to access an instance of the named pipe.

To become a client process, an application must open an instance of the named pipe by calling the DosOpen function. DosOpen returns a handle to the client process that can be passed to other named pipe reading and writing functions. If DosOpen displays the return code ERROR_PIPE_BUSY (the pipe is currently being accessed by another process), the client process can call DosWaitNmPipe to wait for the named pipe to become available. DosWaitNmPipe can be configured to timeout after a particular period of time, or to wait indefinitely for an instance of the named pipe.

When an instance of the named pipe becomes available, Advanced Server allows DosWaitNmPipe to return to the waiting client process. At this point, the client process can call DosOpen to open the named pipe. After a client process has opened an instance of a named pipe, the client process can begin to read and write to the named pipe. To perform these tasks, the client process should call the DosRead and DosWrite functions. Both of these functions accept the handle returned by DosOpen, and operate on the same thread of execution as the client process.

Applications should be coded so that only normal terminations occur; that is, one side should send some indication that it is done. This message should be acknowledged before closing the pipe.

A remote named pipe can be written to by specifying the pipe name as follows: \\computer\pipe\name.

A process may call DosPeekNmPipe to see if there is any data written to a named pipe. DosPeekNmPipe reads the data in a named pipe but does not remove the data.

If necessary, either a server or client process can call DosDupHandle to replicate a handle to a named pipe. DosDupHandle returns a new handle to the same instance of a named pipe that an old handle represented. This handle can be passed to any named pipe function that could use the old handle.

Advanced Server provides two functions that decrease the overhead involved in writing to and reading from a named pipe. These two functions are DosTransactNmPipe and DosCallNmPipe. DosTransactNmPipe writes a message to and then reads a message from an opened named pipe.

DosCallNmPipe opens, writes to, reads from, and then closes a named pipe. This four-in-one process is helpful when implementing a remote procedure call (RPC) on the network.

When a client process no longer requires access to a named pipe, the DosClose function can be called to close the named pipe.

When a server process no longer requires an instance of a named pipe, the server process calls DosDisConnectNmPipe to remove that instance of the named pipe by specifying its handle. If a client process is still accessing the named pipe, DosDisConnectNmPipe forces the client process off.

Advanced Server provides the following functions that enable server or client processes to obtain information about a named pipe or its handle:

DosQFHandState

DosQHandType

DosQNmPHandState

DosQNmPipeInfo

Advanced Server also provides the following functions that enable server or client processes to set specific information about a named pipe that can be queried:

DosSetFHandState

DosSetNmPHandState

The transfer mode of a named pipe is set either by DosMakeNmPipe or DosSetNmPHandState. A named pipe transfers data in byte-stream or message-stream mode.

A named pipe operating in byte-stream mode operates like an anonymous pipe where all data written is transferred without any special processing performed on it. When operating in message-stream mode, a named pipe can distinguish between the different messages (and size of each message) read from and written to that named pipe.

Named pipes are designed so that a client process need not know what type of resource it is opening (pipe or file). Client processes use the DosOpen, DosRead, and DosClose functions to open, read, and close both types of resources respectively, without being aware that one resource is a file and the other a named pipe.

The following table describes the transition state of a named pipe, based on the action a server or client process indicates:

Current State	Action/Process	Next State
Pipe does not exist	DosMakeNmPipe, server	NP_DISCONNECTED
NP_DISCONNECTED	DosConnectNmPipe, server	NP_LISTENING
NP_LISTENING	DosOpen, client	NP_CONNECTED
NP_CONNECTED	DosDisConnectNmPipeserver	DISCONNECTED
NP_CONNECTED	DosClose, client	NP_CLOSING
NP_CLOSING	DosDisConnectNmPipeserver	DISCONNECTED
NP_CONNECTED	DosClose, server	NP_CLOSING

Pipe Category Data Structures

The PIPEINFO data structure is used by DosQNmPipeInfo. Its format is as follows:

typedef struct _PIPEINFO {

USHORT cbOut;

USHORT cbIn;

BYTE cbMaxInst;

BYTE cbCurInst;

BYTE cbName;

CHAR szName[1];

} PIPEINFO;

Within this structure, the following parameters are defined:

cbOut specifies the size (in bytes) of the named pipe’s outgoing I/O buffer.

cbIn specifies the size of the named pipe’s incoming I/O buffer.

cbMaxInst specifies how many instances are allowed for the pipe.

cbCurInst specifies how many instances of the pipe are open.

cbName specifies the length of the pipe’s name.

szName points to a variable-length string containing the pipe name.

Naming Conventions

The Pipe data structures and the Pipe functions use OS/2 conventions for names and type definitions. The os2def.h header files defines these types:

MS Type Definition	C Language Type
BYTE	char
CHAR	char
HFILE	unsigned short
HPIPE	unsigned short
HSEM	long
PBYTE	unsigned char *
PHFILE	unsigned short *
PHPIPE	unsigned short *
PSZ	unsigned char *
PUSHORT	unsigned short *
PULONG	unsigned long *
PVOID	pointer to a void
SPLERR	unsigned
ULONG	unsigned long
USHORT	unsigned short