DosMakeNmPipe

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

Syntax

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

Parameters

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:

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:

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 behaviour 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.

Return Code

rc (USHORT) - return

Return code descriptions are:

• 0 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.

Bindings

C

#define INCL_DOSNMPIPES

USHORT  rc = DosMakeNmPipe(PipeName, PipeHandle, OpenMode, PipeMode,
                             OutBufSize, InBufSize, TimeOut);

PSZ     PipeName;      /* Pipe name */
PHPIPE  PipeHandle;    /* Pipe handle (returned) */
USHORT  OpenMode;      /* DOS open mode of pipe */
USHORT  PipeMode;      /* Pipe open mode */
USHORT  OutBufSize;    /* Advisory outgoing buffer size */
USHORT  InBufSize;     /* Advisory incoming buffer size */
ULONG   TimeOut;       /* Timeout for DosWaitNmPipe */

USHORT  rc;            /* return code */

MASM

EXTRN  DosMakeNmPipe:FAR
INCL_DOSNMPIPES     EQU 1

PUSH@  ASCIIZ  PipeName      ;Pipe name
PUSH@  WORD    PipeHandle    ;Pipe handle (returned)
PUSH   WORD    OpenMode      ;DOS open mode of pipe
PUSH   WORD    PipeMode      ;Pipe open mode
PUSH   WORD    OutBufSize    ;Advisory outgoing buffer size
PUSH   WORD    InBufSize     ;Advisory incoming buffer size
PUSH   DWORD   TimeOut       ;Timeout for DosWaitNmPipe
CALL   DosMakeNmPipe

Returns WORD

Related Functions

• DosWaitNmPipe