OS/2 Shareware BBS: 10 Tools/10-Tools.zip/PIPES.ZIP/PIPES.HLP

OS/2 Help File | 1990-01-08 | 24KB | 904 lines

ΓòÉΓòÉΓòÉ 1. Named Pipe Demo Overview ΓòÉΓòÉΓòÉ

The Named Pipes Demo program was written in order to provide OS2/PM programmers
with a working example of the coding requirements and functional
characteristics of named pipe processing.

The following overview topics may be selected:

 o What is a Named Pipe?
 o Restrictions
 o Method of Operation
 o Handshaking


ΓòÉΓòÉΓòÉ 1.1. Restrictions ΓòÉΓòÉΓòÉ

This demonstration module has been written in order to allow a programmer to
get some "hands on" experience with the operation of OS2 named pipes.  All of
the non-semaphore related operations have been included in the application.

The demo constructs pipes with the following characteristics:

 o Duplex pipe
 o Input  buffersize 512
 o Output buffersize 512
 o Pipe operations will block
 o Write behind will not be allowed
 o Unlimited instances
 o Message write mode
 o Message read  mode
 o Maximum of 8 characters for Pipe Name and Server name

 The demo has been constructed in such a way that you can initiate sequences
 that are not valid in pipe processing.  For example, there is nothing to stop
 you from trying to read from a pipe that you have not opened.  By doing these
 things, you can see the effect in the demo before you have to code for it in a
 program.

 There are some operations that are disabled to protect you from  disaster.
 You can not select either Client or Server functions until you have specified
 the pipe name and type.  Once you specify Client type you can not  select
 Server functions.  Once you select Server type you can not select Client
 functions.  Once you open or make a pipe you can not re-open, re-make, or Name
 the pipe again until the pipe has been closed.  Otherwise, the pipe calls you
 can perform are wide open.


ΓòÉΓòÉΓòÉ 1.2. Method of Operation ΓòÉΓòÉΓòÉ

The first thing you must do in the demo is identify the name of the pipe.  The
default name is Kiddo (the nickname my daughter once insisted upon ldl.)  Then
you must choose from one of the three named pipe modes:

 o LOCAL CLIENT mode sets the demo so that it will operate with another demo
   process running on YOUR PC that has been set to run in server mode.
 o REMOTE CLIENT mode sets the demo so that it will operate with another demo
   process running on your PC or another PC in your LAN.  If you select this
   item, the server process must be running on a PC that has been properly
   configured to respond as a server in the LAN.  You MUST provide that PC's
   remote server name (COMPUTERNAME) at the time of remote client mode
   selection.
 o SERVER mode sets the demo so that it will operate with another demo process
   running in either local or remote client modes.

 Once you have set the name and mode of the demo pipe process, you can select
 either Client or Server action bar items from the Process action bar as is
 appropriate for your chosen mode.

 As soon as you have established one end of the pipe, you need to start a
 process that will deal with the other end of the pipe.  If you are using ONLY
 one PC, select CLONE from the PROCESS action bar.  This will start another
 copy of the demo with which you may proceed.  If you are using TWO PCs in a
 LAN, you should go to the other PC and start a copy of the demo there.


ΓòÉΓòÉΓòÉ 1.3. Handshaking ΓòÉΓòÉΓòÉ

Named pipe processing has various requirements for correct processing and you
are encouraged to read the apropriate sections of the OS2 Programming Guide
before and during the demo.  If you are using IBM part number 64F0273, see
pages 35-11 through 35-17.

In general, here is enough to get you started:

 o The Server process must make the pipe.
 o The Server process must connect the pipe.
 o The Client process must open the pipe.
 o Both pipes may now read, write and do whatever.  It should be noted that
   pipe communication protocols are specific to the application.  (ie. There
   are no "First Speaker/Second Speaker" or other flow control features the
   programmer may be used to using in SNA or elsewhere.)

 State, Info, and Peek selections on the File action bar will complete without
 error once the pipe is made or opened.


ΓòÉΓòÉΓòÉ 1.4. What is a Named Pipe? ΓòÉΓòÉΓòÉ

A named pipe is an OS2 construct that allows two processes to communicate data.
There are several ways to communicate data between processes in OS2.  The most
effecient way to share data between processes running on the same PC is to
allocate and share memory.  What named pipes brings to the table is an ability
to share data between processes running on two different PC's in the same Local
Area Network.  This ability is the basis for Client/Server distributive
processing on the OS2 platform.

The way in which named pipes has been implimented in OS2 is relatively painless
for the application developer.  In a nutshell, named pipes interfaces mirror
file I/O processing.  The server process makes the pipe in a fashion similar to
creating a file.  The client process opens the named pipe using the same call
that would be made to open a file.  From that point on, both client and server
read and write to the pipe just as they would to a file.  The big difference is
that the "file" has intelligence as an application.  The record that the client
writes to the pipe is read by the server and processed in some fashion.  The
server may then respond to the client message (record) by writing to the pipe
information that the client may read from the pipe.

Named pipes can be defined with several variations.  You are encouraged to read
the apropriate sections of the OS2 Programming Guide before and during the
demo.  If you are using IBM part number 64F0273, see pages 35-11 through 35-17.

For your immediate information, this demo uses a DUPLEX pipe.  A duplex pipe
allows I/O in both directions from the same pipe.  The demo pipe allows
blocking.  Blocking means that several pipe functions (connect, wait, read,
write, etc.) will suspend the caller if the function is not immediately
executable.  That means that if you issue a read and there is no data in the
pipe you will wait until there is.  That's great in terms of relieving you of
the responsibility of writing retry routines for mundane processing.  However,
you must not allow window or dialog message processing routines to wait.  If
you do, the user's PC will lock up until the pipe block is relieved.  The demo
has implimented a relatively crude, but effective, method to circumvent this
problem using asynchronous threads in conjunction with modeless dialogs.

There are two types of I/O processing that may be done using named pipes, BYTE
stream and MESSAGE stream.  This demo uses message stream processing. Message
stream processing, simply put, allows you to read and write at the  record
level.  There may be some instance that makes byte level I/O more attractive
for an application.  However, I can't think of any.


ΓòÉΓòÉΓòÉ 2. Named Pipe Primary Window ΓòÉΓòÉΓòÉ

This is the demo primary help panel.

The following Topics may be selected from this menu:

 Overview:      Purpose and function

 Action Bar Items

 o File
 o Process
 o Help

 Panels

 o Pipes Control
 o Client Functions
 o Server Functions
 o Pipe State
 o Pipe Info
 o Peek Pipe
 o Message from Pipe
 o Message to Pipe
 o Async Thread Panel


ΓòÉΓòÉΓòÉ 2.1. File Action Bar Selection ΓòÉΓòÉΓòÉ

Named Pipe I/O is very similar to file I/O, so the File action bar selection is
appropriately named.  From the File action bar you may select one of the
following action items:

 Name:          Set Pipe Name and Type
 State:         DosQNmPHandState
 Info:          DosQNmPipeInfo
 Peek:          DosPeekNmPipe
 Exit:          Exit Demo


ΓòÉΓòÉΓòÉ 2.1.1. Set Pipe Name and Type ΓòÉΓòÉΓòÉ

The Name action item selection on the File action bar allows you to display the
Pipes Control  panel.  From there you may enter the name of the pipe that the
demo will use and the type of pipe it should process.


ΓòÉΓòÉΓòÉ 2.1.2. DosQNmPHandState ΓòÉΓòÉΓòÉ

The State action item selection on the File action bar executes
DosQNmPHandState for the named pipe being processed and presents panel Pipe
State.


ΓòÉΓòÉΓòÉ 2.1.3. DosQNmPipeInfo ΓòÉΓòÉΓòÉ

The Info action item selection on the File action bar executes DosQNmPipeInfo
for the  named pipe being processed and presents panel Pipe Info.


ΓòÉΓòÉΓòÉ 2.1.4. DosPeekNmPipe ΓòÉΓòÉΓòÉ

The Peek action item selection on the File action bar executes DosPeekNmPipe
for the  named pipe being processed and presents panel Pipe Peek.


ΓòÉΓòÉΓòÉ 2.1.5. Exit ΓòÉΓòÉΓòÉ

The Exit action item selection on the File action bar quits the program.


ΓòÉΓòÉΓòÉ 2.2. Process Action Bar Selection ΓòÉΓòÉΓòÉ

The Process action bar selection allows you access to client and server pipe
functions as well as enabling you to start another PIPES DEMO process to play
with local pipes.

From the Process action bar you may select the following action items:

 Client         open, close, etc.
 Server         make, close, etc.
 Clone          Start another process.


ΓòÉΓòÉΓòÉ 2.2.1. Client Functions ΓòÉΓòÉΓòÉ

The Client action item selection on the Process action bar allows you to
perform operations that are valid for the client end of the pipe.


ΓòÉΓòÉΓòÉ 2.2.2. Server Functions ΓòÉΓòÉΓòÉ

The Server action item selection on the Process action bar allows you to
perform operations that are valid for the server end of the pipe. You may
accomplish these using panel Server Functions.


ΓòÉΓòÉΓòÉ 2.2.3. Clone ΓòÉΓòÉΓòÉ

The Clone action item selection on the Process action bar allows you to start
another demo session in order to use the demo to process both sides of a local
pipe.  You can also create multiple servers and/or clients to emulate more
complex pipe environments.


ΓòÉΓòÉΓòÉ 2.3. Help Action Bar Selection ΓòÉΓòÉΓòÉ

This action bar item allows you to select functions from the help subsystem.

Valid help subsystem action items are:

 Help for help  explains help functions in detail
 Extended Help  retrieves pipes demo  primary help panel
 Keys Help      explains use of special key combinations
 Help Index     presents help topics in an indexed list
 About Demo     displays program version and author info


ΓòÉΓòÉΓòÉ 2.3.1. Help for help ΓòÉΓòÉΓòÉ

This action bar item allows you to request instructions regarding the use of
the help subsystem.


ΓòÉΓòÉΓòÉ 2.3.2. Extended Help ΓòÉΓòÉΓòÉ

This action bar item allows you to request general help about the active
application window.


ΓòÉΓòÉΓòÉ 2.3.3. Keys Help ΓòÉΓòÉΓòÉ

This action bar item allows you to request instructions about special key
functions.


ΓòÉΓòÉΓòÉ 2.3.4. Help Index ΓòÉΓòÉΓòÉ

This action bar item allows you to access the index of Help topics.


ΓòÉΓòÉΓòÉ 2.3.5. About ΓòÉΓòÉΓòÉ

This action bar item displays the active application program version level and
author.


ΓòÉΓòÉΓòÉ 3. Pipes Control Panel ΓòÉΓòÉΓòÉ

The Pipes Control panel is used to set the demo global parameters.  You must
complete this panel before you may exercise pipe functions.

Controls on this panel are:

 Pipe Name      Set name of pipe
 Computername   Identify remote server
 Local Client   Set mode to local client
 Remote Client  Set mode to remote client
 Server         Set mode to server
 OK             Execute specifications
 Cancel         Ignore specifcations


ΓòÉΓòÉΓòÉ 3.1. Pipe Name ΓòÉΓòÉΓòÉ

The Pipe Name is used to identify the Pipe resource to the processes that are
using it.  This is a required field.


ΓòÉΓòÉΓòÉ 3.2. Computername ΓòÉΓòÉΓòÉ

In order to connect a remote client with a server on another PC, you must
specify the name with which that PC has identified itself to the network
(COMPUTERNAME).  This field is required if you specify a mode of  Remote
Client.


ΓòÉΓòÉΓòÉ 3.3. Local Client Pipe Radio Button ΓòÉΓòÉΓòÉ

Selecting a local client type of pipe allows you to connect with a server
process on your PC.


ΓòÉΓòÉΓòÉ 3.4. Server Pipe Radio Button ΓòÉΓòÉΓòÉ

Selecting a server type of pipe sets the mode to server in the demo process.


ΓòÉΓòÉΓòÉ 3.5. Remote Client Pipe Radio Button ΓòÉΓòÉΓòÉ

Selecting a remote server type allows you to connect to server demo processes
that are running your PC or on other PC's in the network.  If you select this
pipe mode you must specify Computername.


ΓòÉΓòÉΓòÉ 3.6. OK Button ΓòÉΓòÉΓòÉ

The OK button executes items selected and input on the Pipes Control panel.


ΓòÉΓòÉΓòÉ 3.7. Cancel Button ΓòÉΓòÉΓòÉ

The Cancel button ignores any changes or inputs on the Pipes Control panel.


ΓòÉΓòÉΓòÉ 4. Client Functions Panel ΓòÉΓòÉΓòÉ

The Client Functions panel allows you to invoke pipe functions that are valid
for processes owning the client end of a named pipe.

Valid Client named pipe functions are:

 Open           Open a named pipe
 Wait           Wait for available pipe instance
 Read           Wait for server message
 Write          Send pipe message
 Close          Deallocate pipe resource

 Other controls:

 Ok             Execute selection
 Cancel         Ignore selection


ΓòÉΓòÉΓòÉ 4.1. Open Radio Button ΓòÉΓòÉΓòÉ

The Open radio button on panel Client Functions  allows you to open a named
pipe by call DosOpen.  Various pipe control parameters are hard coded within
the  program.  You may use State and Info from the Files action bar to
determine the pipe parameters used.

Once the pipe has been opened, the Open radio button is disabled (until the
pipe has been closed.)  This is done so that you do not inadvertantly destroy
the pipe handle.


ΓòÉΓòÉΓòÉ 4.2. Wait Radio Button ΓòÉΓòÉΓòÉ

The Wait radio button on panel Client Functions  allows you to create a
sub-task (thread) for your process that issues  DosWaitNmPipe to wait for a
server process to issue a make and connect for its end of the named pipe.  You
should only use the wait function if you receive an ERROR_PIPE_BUSY return from
DosOpen.  You will receive this return code when:

 o The server has made the pipe and not yet issued the connect for it.
 o All existing instances of the named pipe have already been opened by other
   client processes.

 An asynchronous thread is required for this purpose because the pipe was
 created using blocked mode.  (See State action item selection.)


ΓòÉΓòÉΓòÉ 4.3. Read Radio Button ΓòÉΓòÉΓòÉ

The Read radio button on panel Client Functions  allows you to create a
sub-task (thread) for your process that issues a  DosRead and waits for a
message to be received from the server end of the pipe.

An asynchronous thread is required for this purpose because the pipe was
created using blocked mode.  (See State action item selection.)

When DosRead returns with a non-zero length message, you are presented with
panel Message from Pipe that displays the  message that was received.


ΓòÉΓòÉΓòÉ 4.4. Write Radio Button ΓòÉΓòÉΓòÉ

The Write radio button on panel Client Functions  allows you to input a
multiline text message using panel  "Message to Pipe."  Once you enter the
message text, a sub-task (thread) is created for your process issues DosWrite
to write the message and waits for the write to the pipe to complete.

An asynchronous thread is required for this purpose because the pipe was
created using blocked mode.  (See State action item selection.)


ΓòÉΓòÉΓòÉ 4.5. Close Radio Button. ΓòÉΓòÉΓòÉ

The Close radio button on panel Client Functions  allows you to issue the
DosClose call for the named pipe resource.  DosClose will deallocate the pipe
resource for your client process.  It will not flush any unread server
messages.

A DosPeekNmPipe issued by the server will indicate that the pipe is in a
"closing" state.  The server may continue to read messages that are buffered in
the pipe until no more messages remain.  A read on the empty pipe will return
EOF.


ΓòÉΓòÉΓòÉ 4.6. OK Button ΓòÉΓòÉΓòÉ

The OK button executes items selected the Client Functions panel.


ΓòÉΓòÉΓòÉ 4.7. Cancel Button ΓòÉΓòÉΓòÉ

The Cancel button ignores items selected on the Client Functions panel.


ΓòÉΓòÉΓòÉ 5. Server Functions Panel ΓòÉΓòÉΓòÉ

The Server Functions panel allows you to invoke pipe functions that are valid
for processes owning the server end of a named pipe.

Valid Server named pipe functions are:

 Make           Create a named pipe
 Connect        Wait for client to open
 Read           Wait for client message
 Write          Send pipe message
 Disconnect     Break client connection
 Close          Deallocate pipe resource

 Other controls:

 Ok             Execute selection
 Cancel         Ignore selection


ΓòÉΓòÉΓòÉ 5.1. Make Radio Button ΓòÉΓòÉΓòÉ

The Make radio button on panel Server Functions  allows you to create a named
pipe by call DosMakeNmPipe. Various pipe control parameters are hard coded
within the  program.  You may use State and Info from the Files action bar to
determine the pipe parameters used.

Once the pipe has been made, the Make radio button is disabled (until the  pipe
has been closed.)  This is done so that you do not inadvertantly destroy the
pipe handle.


ΓòÉΓòÉΓòÉ 5.2. Connect Radio Button ΓòÉΓòÉΓòÉ

The Connect radio button on panel Server Functions  allows you to create a
sub-task (thread) for your process that issues  DosConnectNmPipe to wait for a
client process to open its end of the named pipe.

An asynchronous thread is required for this purpose because the pipe was
created using blocked mode.  (See State action item selection.)


ΓòÉΓòÉΓòÉ 5.3. Read Radio Button ΓòÉΓòÉΓòÉ

The Read radio button on panel Server Functions  allows you to create a
sub-task (thread) for your process that issues a  DosRead and waits for a
message to be received from the client end of the pipe.

An asynchronous thread is required for this purpose because the pipe was
created using blocked mode.  (See State action item selection.)

When DosRead returns with a non-zero length message, you are presented with
panel Message from Pipe that displays the  message that was received.


ΓòÉΓòÉΓòÉ 5.4. Write Radio Button ΓòÉΓòÉΓòÉ

The Write radio button on panel Server Functions  allows you to input a
multiline text message using panel  "Message to Pipe."  Once you enter the
message text, a sub-task (thread) is created for your process issues DosWrite
to write the message and waits for the write to the pipe to complete.

An asynchronous thread is required for this purpose because the pipe was
created using blocked mode.  (See State action item selection.)


ΓòÉΓòÉΓòÉ 5.5. Disconnect Radio Button ΓòÉΓòÉΓòÉ

The Disconnect radio button on panel Server Functions  allows you to execute
DosDisConnectNmPipe for the named pipe that you made.  Disconnect flushes any
messages that you have written but have not been read by the client from the
pipe.  The next read issued by the client will return ERROR_PIPE_DISCONNECTED.

After you disconnect the pipe, you may Close it (completely deallocate the
resource) or you may re-issue the Connect to accept a new client open.


ΓòÉΓòÉΓòÉ 5.6. Close Radio Button. ΓòÉΓòÉΓòÉ

The Close radio button on panel Server Functions  allows you to issue the
DosClose call for the named pipe resource.  DosClose will deallocate the pipe
resource for your server process.  It will not flush any unread client
messages.

A DosPeekNmPipe issued by the client will indicate that the pipe is in a
"closing" state.  The client may continue to read messages that are buffered in
the pipe until no more messages remain.  A read on the empty pipe will return
EOF.


ΓòÉΓòÉΓòÉ 5.7. OK Button ΓòÉΓòÉΓòÉ

The OK button executes items selected on the Server Functions panel.


ΓòÉΓòÉΓòÉ 5.8. Cancel Button ΓòÉΓòÉΓòÉ

The Cancel button ignores items selected on the Server Functions panel.


ΓòÉΓòÉΓòÉ 6. Message from Pipe Panel ΓòÉΓòÉΓòÉ

When a DosRead returns with a message length greater than zero, the Message
from Pipe panel presents the message in a multi-line edit dialog control.

Both the OK and Cancel buttons serve only to end the dialog and return you to
the application window.


ΓòÉΓòÉΓòÉ 7. Message to Pipe Panel ΓòÉΓòÉΓòÉ

When you select the Write radio button from either the Client or Server
Function panels, you are presented with the Message to Pipe panel.  You can
enter text in the multi-line edit dialog control on the panel.  Lines will
automatically wrap at word boundaries.  The scroll bar control will activate if
you enter more lines than can be displayed in the edit area.  You may enter
messages of up to 510 characters.  You may not enter zero length messages.  If
you decide not to send a message, you may press the cancel button.  Otherwise,
press the OK button.

Pressing the OK button causes the demo to start an asynchronous task (thread)
that writes the message to the pipe using DosWrite.

An asynchronous thread is required for this purpose because the pipe was
created using blocked mode.  (See State action item selection.)


ΓòÉΓòÉΓòÉ 8. Asychronous Thread Panel ΓòÉΓòÉΓòÉ

The Asynchronous Thread panel is displayed when you select a function that has
the potential to block.

The following pipe functions may block during execution:

 Connect        DosConnectNmPipe
 Wait           DosWaitNmPipe
 Read           DosRead
 Write          DosWrite

 Blocking simply means that if the operation can not be performed imediately,
 the issuer waits until it completes.  By using blocking, you do not have to
 develop methods to retry failed operations.  However, under the presentation
 manager, you must not allow window or dialog procedures to become
 non-dispatchable. If you do so, the user's PC becomes locked up until the
 block is relieved. (This is basic to the PM event driven message processing
 model.)  Therefore, you must create asynchronous tasks (threads) to accomplish
 the dirty work.  If you want to display a message to the user that describes
 the thread activity, as in the case of this panel, you may do so by developing
 an association between the thread and a modeless dialog.


ΓòÉΓòÉΓòÉ 8.1. Connect Thread ΓòÉΓòÉΓòÉ

The Connect check box is marked to indicate that the server process has issued
a DosConnectNmPipe to wait for a client process to open its end of the pipe.


ΓòÉΓòÉΓòÉ 8.2. Wait Thread ΓòÉΓòÉΓòÉ

The Wait Pipe Instance check box is marked to indicate that the client has
issued a DosWaitNmPipe to wait for an available and connected server pipe
instance.


ΓòÉΓòÉΓòÉ 8.3. Read Thread ΓòÉΓòÉΓòÉ

The Read check box is marked to indicate that the client or server process has
issued a DosRead in order to wait for a message to be written to the other end
of the pipe.


ΓòÉΓòÉΓòÉ 8.4. Write Thread ΓòÉΓòÉΓòÉ

The Write check box is marked to indicate that the client or server process has
issued a DosWrite in order to place a message into the pipe.  This process has
the potential to block, but normally completes imediately.


ΓòÉΓòÉΓòÉ 9. Pipe State Panel ΓòÉΓòÉΓòÉ

The Pipe State panel displays the results of a call to DosQNmPHandState.

Fields on this panel are:

 o Blocking
 o Mode
 o Type
 o Readmode
 o Instance


ΓòÉΓòÉΓòÉ 9.1. Blocking ΓòÉΓòÉΓòÉ

If blocking is enabled (ON), certain pipe operations will suspend the caller
until the operation is executable.  For example, if a server process calls
DosMakeNmPipe, it will be suspended until a client calls DosOpen for the pipe
instance.

If blocking is disabled (OFF), pipe operation calls will return immediately if
they are not executable.

This demo has enabled blocking.  Since it is an OS2/PM application, it uses
asynchronous threads to call functions that may block.  In that way, the
dialog and window message processing routines are always responsive to the
user.


ΓòÉΓòÉΓòÉ 9.2. Mode ΓòÉΓòÉΓòÉ

Named pipes connect TWO processes, a client and a server.  DosQPHandState
indicates which mode is associated with the handle.


ΓòÉΓòÉΓòÉ 9.3. Type ΓòÉΓòÉΓòÉ

Named pipes may be defined so that they may be written to a BYTE at a time or a
record (MESSAGE) at a time.

This demo has enabled message writes.


ΓòÉΓòÉΓòÉ 9.4. Readmode ΓòÉΓòÉΓòÉ

Named pipes may be set to provide data to DosRead a BYTE at a time or a record
(MESSAGE) at a time.

The server end is set to byte or message during DosMakeNmPipe processing.

The client opens the pipe using DosOpen.  There is no way to specify byte or
message reads with this call.  The pipe defaults to byte read mode.  If the
client wishes message read mode, it must issue the DosSetNmPHandState call to
set the pipe to read mode.

This demo enables message reads.


ΓòÉΓòÉΓòÉ 9.5. Instance ΓòÉΓòÉΓòÉ

When a server calls DosMakeNmPipe, it specifies the maximum number of
occurrences (instances) of a pipe with that name.  The maxinstance
specification is ignored for all subsequent calls to DosMakeNmPipe.  A server
may make as many named pipes with the same name as is allowed by the
maxinstance parameter on the first call. This is an obvious limit to the number
of concurrent client/server connections available to a named pipe.

This demo uses a special case of the maxinstance parameter.  A value of -1 may
be specified to provide unlimited named pipe occurrences.

Do not be confused by this instance concept.  Every time a call is made to
DosMakeNmPipe, a unique handle is returned to represent a pipe instance.  A
named pipe instance may only connect ONE server process to ONE client process.
There are NO MANY TO ONE relationships available with a named pipe.


ΓòÉΓòÉΓòÉ 10. Pipe Info Panel ΓòÉΓòÉΓòÉ

The Pipe Info panel displays the results of a call to DosQNmPipeInfo.

Presented information fields are:

 o Buffersize
 o Instances
 o Name


ΓòÉΓòÉΓòÉ 10.1. Buffersize ΓòÉΓòÉΓòÉ

When a server creates a named pipe instance using DosMakeNmPipe, it must
specify the size of the pipe's input and output buffers.  The buffersize limits
the size of the largest message and the number of messages smaller than
buffersize that may be queued in the pipe.

This demo creates pipes with an input and output buffersize of 512.


ΓòÉΓòÉΓòÉ 10.2. Instances ΓòÉΓòÉΓòÉ

When a server creates a named pipe instance using DosMakeNmPipe, it must
specify the maximum number of concurrent instances of a pipe with that name.
(See  instance field of panel Pipe State.)

DosQNmPipeInfo returns both the instance number of the current pipe handle and
the max instance specified when the first named pipe instance was created.

This demo uses a special case of the maxinstance parameter.  A value of -1 may
be specified to provide unlimited named pipe occurrences.


ΓòÉΓòÉΓòÉ 10.3. Name ΓòÉΓòÉΓòÉ

DosQNmPipeInfo returns the length of the ASCII string for the name of the
current pipe handle.  It also returns the actual string if the structure
provided by the caller is large enough to store it.

This information is of dubious value since the caller must have already made or
opened the named pipe (by name of course) BEFORE it can successfully call
DosQNmPipeInfo with a valid handle.


ΓòÉΓòÉΓòÉ 11. Pipe Peek Panel ΓòÉΓòÉΓòÉ

The Pipe Peek panel displays the information returned by a call to
DosPeekNmPipe.

Fields displayed are:

 o Bytes Buffered
 o Pipe State

 A feature of Peek that is not shown by this demo, is the ability for the
 caller to retrieve all or part of the next message in the input buffer without
 removing any data from the buffer.


ΓòÉΓòÉΓòÉ 11.1. Bytes Buffered ΓòÉΓòÉΓòÉ

A DosPeekNmPipe call returns two length related integers.  The first count is
of the total number of bytes in the pipe input buffer.  This count includes the
two length bytes contained in each message.  The second count is of the length
of the next message to be read from the buffer.  This count DOES NOT include
the two bytes contain the length of that message.


ΓòÉΓòÉΓòÉ 11.2. Pipe State ΓòÉΓòÉΓòÉ

DosPeekNmPipe returns an indicator of the current state of the pipe.  A named
pipe may be in one of four states:

 o A pipe is DISCONNECTED just after a server has made it, but BEFORE the
   server issue a DosConnectNmPipe.  Additionally, a pipe may be disconnected
   specifically by a server process that issues a DosDisConnectNmPipe.
 o A pipe is LISTENING after a server issues a DosConnectNmPipe, but BEFORE a
   client issues a DosOpen for the pipe.
 o A pipe is CONNECTED after the client issues a DosOpen for the pipe.
 o A pipe is CLOSING after either the client or server issues a DosClose for
   the pipe.


ΓòÉΓòÉΓòÉ 12. Help for Key Assignments ΓòÉΓòÉΓòÉ

The list of keys is arranged in groups.

ACCELERATOR KEYS

 Ctrl+c
      Perform Client Pipe Functions

 Ctrl+s
      Perform Server Pipe Functions

 Ctrl+l
      Create another Pipes Demo Window (Clone)

 Ctrl+t
      Execute DosQNmPHandState for the pipe

 Ctrl+i
      Execute DosQNmPipeInfo for the pipe

 Ctrl+p
      Execute DosPeekNmPipe for the pipe

 F3
      Exit program

 HELP KEYS

 F1
      Get help

 F2
      Get extended help (from within any help window)

 Alt+F4
      End help

 F9
      Go to a list of keys (from within any help window)

 F11
      Go to the help index (from within any help window)

 Esc
      Previous Help Panel, or End help if only one panel

 Alt+F6
      Go to/from help and programs

 Shift+F10
      Get help for help

 SYSTEM KEYS

 Alt+F6
      Switch to the next windowed program

 Alt+Esc
      Switch to the next program, including full-screen programs

 Ctrl+Esc
      Switch to the Task List

 WINDOW KEYS

 F3
      Close a window

 F10
      Go to/from the action bar

 Arrow keys
      Move among choices

 End
      Go to the last choice in a pull-down

 Esc
      Cancel a pull-down or the system menu

 Home
      Go to the first choice in a pull-down

 PgUp
      Scroll the contents of the window up one page

 PgDn
      Scroll the contents of the window down one page

 Underlined letter
      Move among the choices on the action bar and pull-downs

 Alt+F10
      Go to/from the action bar

 Alt+F4 or F3
      Close the window

 Alt+F5
      Restore the window

 Alt+F7
      Move the window

 Alt+F8
      Size the window

 Alt+F9
      Minimize the window

 Alt+F10
      Maximize the window

 Ctrl+PgDn or Shift+F8
      Scroll the contents of the window right one page

 Ctrl+PgUp or Shift+F7
      Scroll the contents of the window left one page

 Shift+Esc or Alt+Spacebar
      Go to/from the system menu

 Shift+Esc or Alt
      Go to/from the system menu of a text window