This category includes the following APIs. These APIs are provided by the
OS/2 base operating system and supported by LAN Server across the network.
For more information about these functions, see the online information
with the IBM OS/2 Programming Toolkit and the ┌─────────────────────────┬────────────────────────────────────────────────────┐
│ FOR 16-BIT SUPPORT │ FOR 32-BIT SUPPORT │
├─────────────────────────┼────────────────────────────────────────────────────┤
│ DosBufReset │ DosResetBuffer │
├─────────────────────────┼────────────────────────────────────────────────────┤
│ DosCallNmPipe │ DosCallNPipe │
├─────────────────────────┼────────────────────────────────────────────────────┤
│ DosClose │ │
├─────────────────────────┼────────────────────────────────────────────────────┤
│ DosConnectNmPipe │ DosConnectNPipe │
├─────────────────────────┼────────────────────────────────────────────────────┤
│ DosDisConnectNmPipe │ DosDisconnectNPipe │
├─────────────────────────┼────────────────────────────────────────────────────┤
│ DosDupHandle │ │
├─────────────────────────┼────────────────────────────────────────────────────┤
│ DosMakeNmPipe │ DosCreateNPipe │
├─────────────────────────┼────────────────────────────────────────────────────┤
│ DosOpen │ │
├─────────────────────────┼────────────────────────────────────────────────────┤
│ DosPeekNmPipe │ DosPeekNPipe │
├─────────────────────────┼────────────────────────────────────────────────────┤
│ DosQFHandState │ DosQueryFHState │
├─────────────────────────┼────────────────────────────────────────────────────┤
│ DosQHandType │ DosQueryHType │
├─────────────────────────┼────────────────────────────────────────────────────┤
│ DosQNmPHandState │ DosQueryNPHState │
├─────────────────────────┼────────────────────────────────────────────────────┤
│ DosQNmPipeInfo │ DosQueryNPipeInfo │
├─────────────────────────┼────────────────────────────────────────────────────┤
│ DosQNmPipeSemState │ DosQueryNPipeSemState │
├─────────────────────────┼────────────────────────────────────────────────────┤
│ DosRead │ │
├─────────────────────────┼────────────────────────────────────────────────────┤
│ DosReadAsync │ │
├─────────────────────────┼────────────────────────────────────────────────────┤
│ DosSetFHandState │ DosSetFHState │
├─────────────────────────┼────────────────────────────────────────────────────┤
│ DosSetNmPHandState │ DosSetNPHState │
├─────────────────────────┼────────────────────────────────────────────────────┤
│ DosSetNmPipeSem │ DosSetNPipeSem │
├─────────────────────────┼────────────────────────────────────────────────────┤
│ DosTransactNmPipe │ DosTransactNPipe │
├─────────────────────────┼────────────────────────────────────────────────────┤
│ DosWaitNmPipe │ DosWaitNPipe │
├─────────────────────────┼────────────────────────────────────────────────────┤
│ DosWrite │ │
├─────────────────────────┼────────────────────────────────────────────────────┤
│ DosWrite Async │ │
└─────────────────────────┴────────────────────────────────────────────────────┘
The following named pipe APIs, which are exclusive to DOS, are documented in Named Pipe.
DosReadAsyncNmPipe
DosWriteAsyncNmPipe
Named pipe APIs control interprocess communication (IPC) for named pipes. A named pipe is a bidirectional interprocess communication facility that allows two processes, either local or remote, to communicate with each other over the network.
The APIs in the named pipe category are used with the OS2.H and NETCONS.H header files. These functions are provided by the base operating system and supported by OS/2 LAN Server across 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 calls the DosMakeNmPipe API. This function specifies information that enables the server process to control the named pipe and allows client processes to access the named pipe.
To create a named pipe, DosMakeNmPipe (or 32-bit DosCreateNPipe) requires the following:
An inbound or outbound named pipe (synonymous with anonymous pipes used with other multitasking operating systems) allows a process to read or write by way of one handle. A full-duplex named pipe allows a process to read and to write data by way of one handle.
Each time DosMakeNmPipe (or 32-bit DosCreateNPipe) is called with the same parameter information, another instance of the named pipe is created. Each instance is associated with a unique handle, which is returned by DosMakeNmPipe (or 32-bit DosCreateNPipe). Thus, if DosMakeNmPipe (or 32-bit DosCreateNPipe) is called five times with the same information, five different instances (or handles) of the same named pipe are created.
You also can set other low-level operating system parameters, such as the stream type and blocking mode of the named pipe. 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 (or 32-bit DosConnectNPipe). This function informs the system that a client process has permission to access an instance of the named pipe.
To become a client process, an application opens an instance of the named pipe by calling the DosOpen API. DosOpen returns a handle to the client process that can be passed to other named pipe reading and writing functions. If DosOpen returns the ERROR_PIPE_BUSY error code (pipe currently being accessed by another process), the client process should call DosWaitNmPipe (or 32-bit DosWaitNPipe) to wait for the named pipe to become available. DosWaitNmPipe (or 32-bit DosWaitNPipe) can be configured either to time out 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, the DosWaitNmPipe (or 32-bit DosWaitNPipe) API returns 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 from and write to the named pipe. To perform these tasks, the client process calls the DosRead and DosWrite APIs with the handle returned by DosOpen. If a server or client process requires that the reading and writing of named pipes be run on a separate thread, the process can call the DosReadAsync and DosWriteAsync APIs.
A remote named pipe can be written to by specifying the pipe name as \\server\pipe\name.
A process also can call the DosBufReset (or 32-bit DosResetBuffer) API to force all data to be written to a named pipe; normally, data written to a named pipe is held temporarily in a data buffer. The size of this buffer is specified in the initial DosMakeNmPipe (or 32-bit DosCreateNPipe) call.
Output cannot be redirected to a named pipe.
Since a named pipe must be written to before it is read from, a process can call DosPeekNmPipe (or 32-bit DosPeekNPipe) to see if there is any data written to a named pipe. DosPeekNmPipe (or 32-bit DosPeekNPipe) 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.
Two APIs are provided that decrease the overhead involved in writing to and reading from a named pipe. These two APIs are DosTransactNmPipe (or 32-bit DosTransactionNPipe) and DosCallNmPipe (or 32-bit DosCallNPipe). DosTransactNmPipe (or 32-bit DosTransactionNPipe) writes a message to and then reads a message from an opened named pipe. DosCallNmPipe (or 32-bit DosCallNPipe) 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 API can be called to close the named pipe.
Note: When a named pipe has been closed, DosRead and DosWrite give different return codes. DosRead returns an error code of 0 with pcbActual equal to 0. DosWrite returns 109 (ERROR_BROKEN_PIPE).
When a server process no longer requires an instance of a named pipe, the server process calls DosDisConnectNmPipe (or 32-bit DosDisconnectNPipe) to remove that instance by specifying its handle. If a client process is still accessing the named pipe, DosDisConnectNmPipe (or 32-bit DosDisconnectNPipe) forces the client process off.
The following APIs enable server or client processes to obtain information
about a named pipe or its handle. ┌────────────────────────┬─────────────────────────────────────────────────────┐│FUNCTION
│PURPOSE │
├────────────────────────┼─────────────────────────────────────────────────────┤
│ DosQFHandState (or │ Determines whether the handle can be inherited
and │
│ 32-bit │ if write-behind is allowed │
│ DosQueryFHState) │ │
├────────────────────────┼─────────────────────────────────────────────────────┤
│ DosQHandType (or │ Returns the type of handle │
│ 32-bit DosQueryHType) │ │
├────────────────────────┼─────────────────────────────────────────────────────┤
│ DosQNmPHandState (or │ Returns the low-level parameters associated with
a │
│ 32-bit │ handle and the operating mode of the pipe; declares │
│ DosQueryNPHState) │ the instance count │
├────────────────────────┼─────────────────────────────────────────────────────┤
│ DosQNmPipeInfo (or │ Returns the size of buffers and the number of
│
│ 32-bit │ instances currently available │
│ DosQueryNPipeInfo) │ │
├────────────────────────┼─────────────────────────────────────────────────────┤
│ DosQNmPipeSemState (or │ Returns the state of a semaphore associated with
a │
│ 32-bit │ named pipe │
│ DosQueryNPipeSemState) │ │
└────────────────────────┴─────────────────────────────────────────────────────┘
The following APIs enable server or client processes to set
specific information about a named pipe that can be queried. ┌────────────────────┬─────────────────────────────────────────────────────────┐
│ FUNCTION │ PURPOSE │
├────────────────────┼─────────────────────────────────────────────────────────┤
│ DosSetFHandState │ Specifies whether (1) a handle of a named pipe can
be │
│ (or 32-bit │ inherited, and (2) write-behind is allowed │
│ DosSetFHState) │ │
├────────────────────┼─────────────────────────────────────────────────────────┤
│ DosSetNmPHandState │ Sets low-level parameters associated with pipes,
such │
│ (or 32-bit │ as reading and writing mode │
│ DosSetNPHState) │ │
├────────────────────┼─────────────────────────────────────────────────────────┤
│ DosSetNmPipeSem │ Sets the association of a semaphore to a named pipe
│
│ (or 32-bit │ │
│ DosSetNPipeSem) │ │
└────────────────────┴─────────────────────────────────────────────────────────┘
The transfer mode of a named pipe is set by either DosMakeNmPipe (or 32-bit DosCreateNPipe) or DosSetNmPHandState (or 32-bit DosSetNPHState); 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 among the different messages (and size of each message) read from and written to that named pipe.
System calls operate on manual pipes and files in similar ways. Client processes use the DosOpen, DosRead, and DosClose APIs to open, read, and close both types of resources without reference to one resource being 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 │ NEXT STATE │
├─────────────────────────┼──────────────────────────┼─────────────────────────┤
│ Pipe does not exist │ DosMakeNmPipe (or 32-bit │ NP_DISCONNECTED
│
│ │ DosCreateNPipe) on the │ │
│ │ server │ │
├─────────────────────────┼──────────────────────────┼─────────────────────────┤
│ NP_DISCONNECTED │ DosConnectNmPipe (or │ NP_LISTENING │
│ │ 32-bit DosConnectNPipe) │ │
│ │ on the server │ │
├─────────────────────────┼──────────────────────────┼─────────────────────────┤
│ NP_LISTENING │ DosOpen on the client │ NP_CONNECTED │
├─────────────────────────┼──────────────────────────┼─────────────────────────┤
│ NP_CONNECTED │ DosDisConnectNmPipe (or │ DISCONNECTED │
│ │ 32-bit │ │
│ │ DosDisconnectNPipe) on │ │
│ │ the server │ │
├─────────────────────────┼──────────────────────────┼─────────────────────────┤
│ NP_CONNECTED │ DosClose on the client │ NP_CLOSING │
├─────────────────────────┼──────────────────────────┼─────────────────────────┤
│ NP_CLOSING │ DosDisConnectNmPipe (or │ DISCONNECTED │
│ │ 32-bit │ │
│ │ DosDisconnectNPipe) on │ │
│ │ the server │ │
├─────────────────────────┼──────────────────────────┼─────────────────────────┤
│ NP_CONNECTED │ DosClose on the server │ NP_CLOSING │
└─────────────────────────┴──────────────────────────┴─────────────────────────┘
Note: The OS/2 DosChgFilePtr API (and other APIs that perform seek operations on files) does not work with named pipes.