DosMakeNmPipe

This call creates the specified named pipe and returns its handle.

DosMakeNmPipe

(PipeName, PipeHandle, OpenMode, PipeMode, OutBufSize, InBufSize, TimeOut)

PipeName (PSZ) - input

Address of the ASCIIZ name of the pipe to be opened. Pipes are named \PIPE\PipeName.
PipeHandle (PHPIPE) - output
Address of the handle of the named pipe that is created.
OpenMode (USHORT) - input
The OpenMode parameter contains the following bit fields:

Bit

Description
15
Reserved and must be zero.
14
Write-Through flag: The file is opened as follows:

0 = Write-behind to remote pipes is allowed.

1 = Write-behind to remote pipes is not allowed.

Setting the Write-Through flag is meaningful only for a remote pipe. Occasionally, data written to a remote pipe is buffered locally and then sent across the network to the pipe at a later time. Setting the Write-Through bit ensures that data is sent to the remote pipe as soon as it is written.

13-8
Reserved and must be zero.
7
Inheritance flag: The file handle is as follows:

0 = Pipe handle is inherited by a spawned process resulting from a DosExecPgm call.

1 = Pipe handle is private to the current process and cannot be inherited.

6-2
Reserved and must be zero.
1-0
Access field: The pipe access is assigned as follows:

00 = In-bound pipe (client to server)

01 = Out-bound pipe (server to client)

10 = Duplex pipe (server to/from client)

Any other value is invalid.

PipeMode (USHORT) - input
The PipeMode parameter contains the following bit fields:

Bit

Description
15
Blocking flag: The pipe is defined as follows:

0 = Reads/Writes block if no data available.

1 = Reads/Writes return immediately if no data available.

Reads normally block until at least partial data can be returned. Writes by default block until all bytes requested have been written. Non-blocking mode (1) changes this behavior as follows:

DosRead returns immediately with error NO_DATA if no data is available.

DosWrite returns immediately with BytesWritten = 0 if insufficient buffer space is available in the pipe or the entire data area is transferred.

14-11
Reserved and must be zero.
10
Type of named pipe: The pipe is defined as follows:

0 = Pipe is a byte stream pipe.

1 = Pipe is a message stream pipe.

All writes to message stream pipes record the length of the write along with the written data (see DosWrite). The first two bytes of each message represents the length of that message and is called the message header. A header of all zeros is reserved. Zero length messages are not allowed (OS/2 no-ops zero-length I/Os).

9
Reserved and must be zero.
8
Read mode: The pipe is defined as follows:

0 = Read pipe as a byte stream.

1 = Read pipe as a message stream.

Message pipes can be read as byte or message streams, depending on this bit. Byte pipes can only be read as byte streams (see DosRead)

7-0
ICount field (Instance count): Byte wide (8-bit) count to control pipe instances. When making the first instance of a named pipe, ICount specifies how many instances can be created. Instances are as follows:
Value
Definition
1
This can be the only instance (pipe is unique).
1 < value < 255
The number of instances is limited to the value specified.
-1
The number of instances is unlimited.
0
Reserved value.
Subsequent attempts to make a pipe fails if the maximum number of allowed instances already exists. The ICount parameter is ignored when making any other than the first instance of a pipe. When multiple instances are allowed, multiple clients can simultaneously issue DosOpen to the same pipe name and get handles to distinct pipe instances.
OutBufSize (USHORT) - input
An advisory to the system of the number of bytes to allocate for the outgoing buffer.
InBufSize (USHORT) - input
An advisory to the system of the number of bytes to allocate for the incoming buffer.
TimeOut (ULONG) - input
Default value for the TimeOut parameter to DosWaitNmPipe. This value may be set only at the creation of the first instance of the pipe name. If the value is zero, a system wide default value (50 ms) is chosen.
rc (USHORT) - return
Return code descriptions are:
• NO_ERROR 3
  ERROR_PATH_NOT_FOUND
  8
  ERROR_NOT_ENOUGH_MEMORY
  84
  ERROR_OUT_OF_STRUCTURES
  87
  ERROR_INVALID_PARAMETER
  231
  ERROR_PIPE_BUSY
  Remarks

  A named pipe provides two-way communication between a server process and a number of client processes. In addition, the named pipe can have multiple instances created by multiple server processes.

  The server creates the pipe with DosMakeNmPipe. The ICount parameter is significant only for the first instance created of the named pipe. The ASCIIZ name string specified for the named pipe must include the prefix \PIPE\.

  After creating the named pipe, the server issues DosConnectNmPipe to wait for a client to open the pipe with DosOpen. If all instances of a named pipe are busy, a client process can issue DosWaitNmPipe and wait for an instance to become available before it reissues DosOpen. A client can determine whether the pipe is ready to accept a DosOpen by issuing DosPeekNmPipe to return the pipe's state.

  Server and client processes communicate by issuing DosRead, DosReadAsync, DosWrite, and DosWriteAsync calls. DosBufReset can be used to to synchronize read and write dialogs. A server process that need to support a large number of clients for a local named pipe can coordinate access to the pipe with DosSetNmPipeSem and DosQNmPipeSemState calls.

  Server and client processes can also communicate by means of transaction and procedure calls. DosTransactNmPipe and DosCallNmPipe are supported only for duplex message pipes.

  Issuing DosClose ends the client's access to the named pipe. To prepare the pipe for its next client, the server process issues DosDisConnectNmPipe followed by DosConnectNmPipe.

  When all handles to one end of the pipe are closed, the pipe is considered broken. If the pipe is broken and the server issues DosClose, the pipe is immediately deallocated.

  ---

  [Back: DosLockSeg]
  [Next: DosMakePipe]