Interprocess communication
OS/2 provides several different methods of interprocess communication
that are all fairly easy to implement. In OS/2 1.x there were five distinct
ways available for a process to communicate with another process. These
communications methods used flags, semaphores, pipes, queues, and shared
memory to send and receive messages and signals. Four of the most common
methods were retained in 0S/2 2.0; the one that was dropped was the DosFlagProcess
API.
The functionality provided by DosFlagProcess is now provided
by DosRaiseException and related APIs.
The easiest interprocess communication (IPC) method to implement is
unnamed and named pipes. An unnamed pipe is a circular memory buffer that
can be used to communicate between related processes. The parent process
must set the inheritance flags to true in order for the child process to
inherit the handles and allow the parent and the child processes to communicate.
Communication is bidirectional, and the pipe remains open until both the
read handle and the write handle are closed. Named pipes are also an easy
way to provide remote communication. A process on the requester workstation
can communicate with a process running on the server workstation as well
as with a process running locally. However, the client-server remote connectivity
can be achieved only with the help of some type of local area network server.
An OS/2 Named Pipe Client-Server Example
SERVER.C is, as the name suggests, the server of the Named Pipe IPC mechanism.
The program allows remote and local communications and performs
simple character redirection. The characters are highlighted in different
colors to distinguish server and client modes of operation. As the user
types in characters at the client, they immediately echo on the server.
There is no implied limitation that the server can receive only, and the
client can send only. The particular implementation is specific to this
example.
The SERVER.EXE application can be started by simply typing Server
followed
by a carriage return from the command line. This will start the server
component of the program pair. The Server must be started first,
since it is the Server that creates the named pipe and allows the
Client
to connect to it. After the server starts successfully, the
Client
can be starred by typing Client [ServerName] followed
by a carriage return from the command line. Note that the [ServerName]
is an optional parameter and is used only if a remote pipe connection
is being attempted. If the Server and the Client are running
in the same workstation, and the workstation is capable of running the
IBM OS/2 LAN Server software, the Client-Server communication can
be achieved with both local and remote connections. However, if the
IBM OS/2 LAN Server is not active, or the user is not logged on to the
IBM OS/2 LAN Server domain, attempting a remote connection will produce
an error stating that the pipe name was not found. This is correct, and
usually points to an inactive server or an unauthorised user. The best
way to look at this example is to open two OS/2 window sessions and to
.allow one session to run the SERVER.EXE and the other to run the CLIENT.EXE.
This way it will be easier to see the
Client-Server communication.
SERVER.C
SERVER.H
SERVER.DEF
First, a DosExitList call is made in order to allow the SERVER.EXE to
clean up properly in an event of a Ctrl-C / Ctrl-Brk condition.
APIRET DosExitList(ULONG ulOrderCode, PFNEXITLIST pfn)
ulOrderCode consists of two lower-order bytes that have meaning and a high-order
word must be 0. The lower-order byte can have the values lined in Table
5.1.
Table 5.1 Values for Lower-Order Byte of ulOrderCode
| Value |
Description |
| EXLST_ADD |
Add an address to the termination list |
| EXLST_REMOVE |
Remove an address from the termination list |
| EXLST_EXIT |
When termination processing completes, transfer to the next
address on the termination list |
The high-order byte of the low-order word must be zero if EXLST_REMOVE,
or EXLST_EXIT is specified. If, however, EXLST_ADD is specified, the high-order
byte will indicate the invocation order.
The second parameter for DosExitList is an address
of the routine to be executed - pfn.
The CleanUp() routine closes the named pipe handle
and resets the window text color back to white black.
Next, ConnToClient() must issue two calls: DosCreateNPipe()
and DosConnectNPipe(). Issuing DosConnectNPipe
call is what allows the client to perform a DosOpen() successfully.
After the first few necessary setup APIs are called, a simple handshake
operation is performed by reading a known string from the pipe and writing
a known string back.
/* Creates a named pipe. */
PSZ pszName;
/* The ASCIIZ name of the pipe to be opened. */
PHPIPE pHpipe; /*
A pointer to the variable in which the system returns the handle of the
pipe that is created. */
ULONG openmode; /*
A set of flags defining the mode in which to open the pipe. */
ULONG pipemode; /*
A set of flags defining the mode of the pipe. */
ULONG cbOutbuf; /*
The number of bytes to allocate for the outbound (server to client) buffer.
*/
ULONG cbInbuf; /*
The number of bytes to allocate for the inbound (client to server) buffer.
*/
ULONG msec;
/* The maximum time, in milliseconds, to wait for a named-pipe
instance to become available. */
APIRET ulrc;
/* Return Code. */
ulrc = DosCreateNPipe(pszName, pHpipe, openmode,
pipemode, cbOutbuf, cbInbuf, msec);
The DosCreateNPipe() API expects seven arguments.
The first parameter, DEFAULT_PIPE_NAME, is a ASCII string that contains
the name of the pipe to be created, pszName. The second is a pointer to
the pipe handle that will be returned when the function returns. The next
parameter is the open mode used for the pipe. The flag used in the example
is NP_ACCESS_DUPLEX, which provides inbound and outbound communication.
The fourth parameter is the pipe mode. This parameter is a set of bitfields
that define the pipe mode. The flags used in this example are NP_WMESG
| NP_RMESG | 0x01. These flags indicate the pipe can send and receive messages,
and also that only one instance of the pipe can be created. The pipe can
be created in either byte or message mode only. If a byte mode pipe
is created, then DosRead() and DosWrite() must
use byte stream mode when reading from or writing to the pipe. If a message
mode pipe is created, then DosRead() and DosWrite()
automatically
will use the first two bytes of each message, called the header, to determine
the size of the message. Message mode pipes can be read from and written
to using byte or message streams. Byte mode pipes, on the other hand, can
be used only in byte stream mode. If a message stream is used, the operating
system will encode the message header without the user having to calculate
the value. Care should be taken when deciding what size buffers should
be used during communications. The transaction buffer should be two bytes
greater than the largest expected message
APIRET DosConnectNPipe(HPIPE hpipe);
The DosConnectNPipe() only takes one argument, the named pipe handle.
At this point, the pipe is ready for a client connection
CLIENT.C
CLIENT.DEF
COMMON.H
CLNTSVR.MAK
When the Client is started, the initialization call is made to
ConnToServer().
The client application must perform a DosOpen() first in
order to obtain a pipe handle. Once the pipe handle is obtained, the application
can freely read from the Pipe and write to the pipe. In this case, the
this case write/read pair is used for primitive handshaking communication.
The most interesting set of parameters for the DosOpen() call
on the client side is the ulOpenFlag, which contains the value OPEN_ACTION_OPEN_IF_EXISTS,
and the ulOpenMode, which contains the
OPEN_FLAGS_WRITE_THROUGH | OPEN_FLAGS__FAIL_ON_ERROR | OPEN_FLAGS_RANDOM
| OPEN_SHARE_DENYNONE | OPEN_ACCES_READWRITE
value.
Next, the while loop is entered. It can be stopped only if an
API error is encountered, or if the user presses the F3 function
key at the Client window. The buffer that is being transmitted from
the Client to the Server represents the character received
from the keyboard buffer used by the Client application. A double
word is used to allow proper character translation for the F1-F12 function
keys and some other extended keyboard keys. (The function key keystroke
generates two characters; the first is always a 0x00 followed by the 0xYY.
where YY is a unique function key identifier.)
The remote pipe connection from the Client to the Server is achieved
by starting the CLIENT.EXE with the following command-line syntax:
CLIENT [MYSERVER]
where MYSERVER is the remote Server machine name. (The NetBIOS machine
name for IBM OS/2 LAN Server is found in the IBMLAN.INI file). The pipe
names that are created by the Client have the following format:
| local named pipe name: |
|
\PIPE\MYPIPE |
| remote named pipe name: |
|
\\MYSRVR\PIPE\MYPIPE |
The functionality that this example application provides is the same
in both remote and local connectivity modes. As a matter of
fact,neither the Client nor the Server differentiates between
the remote and local case; only the pipe name is significant. This is the
subtle beauty of the named pipes IPC!
The main reason for choosing pipes as an IPC method is ease of implementation,
but it is not the best choice for all cases. Pipes are useful only
when a process has to send a lot of information to or receive information
from another process. Even though it is possible to allow pipe connections
with multiple processes, connect and disconnect algorithms must always
be implemented for such situations. The remote connection advantage of
named pipes sometimes outweighs the complexity of connect- disconnect algorithms.
Since it is not possible under 0S/2 to communicate remotely with queues
or remote shared memory, pipes sometimes become not only the best
bus the only IPC choice.
 |
Gotcha!
Is is not unusual for an application to receive a return value of ERROR_TOO_MANY_HANDLES
when attempting to open additional pipes. The system initially allows 20
file handles per process; once the limit is reached, the above error will
appear. To prevent this from happening, the DosSetMaxFH(ULONG ulNumberHandlers)
call must be issued, where ulNumberHandlers is the new maximum number of
handles allowed to be open. This call will be successful if system resources
have not been exhausted. It is a good idea to issue this call only when
needed, since additional file handles consume system resources that may
be used elsewhere in the system.
|
DOS-OS/2 Client-Server Connection
To make the pipe connectivity example complete, a DOS-named pipe client
must be discussed. The DOS based, D_CLIENT.EXE. is only slightly different
from its big brother, the OS/2 based CLIENT.EXE. There are no logical differences
between the two; the difference lies in the APIs. The DosOpen()/DosRead()/DosWrite()
OS/2 calls are replaced with open()/read()/write() DOS
calls.
D_CLIENT.C
D_CLIENT.MAK
D_CLIENT.DEF
DCOMMON.H
An OS/2 QUEUE Client-Server Example
The next example pair is QSERVER.C and QCLIENT.C. In this example. the
communication process is a little bit more complex than the one in the
named pipe illustration. Here the point is to show how several different
processes can communicate with one central process. The functionality is
similar to the named pipe example, but with one key difference: The queue
Server process does not send anything to the queue Client processes.
In fact, only the queue Client process can send information to the
queue Server. However, this does not mean that the queue Server
cannot issue a DosWriteQueue() call to itself;
it is just not part of this example. It is left to the reader to implement
this additional functionality. By using the QSERVER.C as a prototype template,
the WriteToQue function call can enhance the
QSERVER.C example program to issue DosWriteQueue calls.
The QSERVER.C-QCLIENT.C example makes use of both the OS/2 queue APIs and
named shared memory segments.
The concept of an OS/2 queue is somewhat simple. It is, in fact, an
ordered set of elements. The elements are 32-bit values that are passed
from the Client to the Server of the queue. The Server
of the queue is the process that created the queue by issuing the DosCreateQueue()
API call.
APIRET DosCreateQueue(PHQUEUE
pha, ULONG ulPriority, PSZ pszName )
phq is a pointer to the queue handle of the queue that is being
created. ulPriority is a set of two flags OR'ed together. The first
flag can have the values listed in Table 5.2. The second flag can have
the values listed in Table 5.3.
Table 5.2 Values of Low Byte of ulPriority.
| Value |
Description |
| QUE_FIFO |
FIFO queue |
| QUE_LIFO |
LIFO queue |
| QUE_PRIORITY |
Priority queue |
|
Table 5.3. Values of High Byte of ulPriority.
| Value |
Description |
| QUE_NOCONERT_ADDRESS |
Does not convert addresses of 16-bit elements that are placed
in the queue |
| QUE_CONVERT_ADDRESS |
Convert 'addresses of 16-bit elements to 32-bit elements |
|
The last parameter is a pointer to the ASCII name of the queue.
Only the Server of the queue can read from the queue. When the
queue is read, one element is removed from it. The Server and the
Client
can
both issue calls to write, query, and close the queue. However only the
Server can issue calls to create, read, peek, and purge the queue.
The Client must issue a DosOpenQueue
call prior to attempting to write elements to the queue or to query the
queue elements.
APIRET DosOpenQueue ( PPID ppid,
PHQUEUE phq, PSZ pszName);
ppid is a pointer to the process ID of the queue's server process.
phq
is
a pointer to the write handle of the queue. pszName is the ASCII
name of the queue to be opened.
The queue elements can be prioritized and processed in particular order.
The order depends on the ulQueueFlags value used when creating the
queue. This value cannot be changed once the queue has been created.
Specifying a priority will cause the DosReadQueue
API to read the queue elements in descending priority order. Priority 15
is the highest, and 0 is the lowest. FIFO order will be used for the elements
with equal priority. The elements of the queue can be used to pass data
to the server directly or indirectly. The indirection comes front using
pointers to shared memory. When pointers are used, the shared memory can
be of two types: named shared memory and unnamed shared memory. Related
processes generally use named shared memory, while the rest use unnamed
shared memory. In this example, the named shared memory method is implemented.
OS/2 queues do not perform any data copying. They only pass pointers. They
leave the rest of the work for the programmer.
/* Reads an element from
a queue. */
HQUEUE
hque; /* The handle of the queue from
which an element is to be removed. */
PREQUESTDATA
pRequest; /* A pointer to a REQUESTDATA that returns a PID
and an event code. */
PULONG
pcbData; /* A pointer to the length, in bytes, of the
data that is being removed. */
PPVOID
ppBuf; /* A pointer to the element that is
being removed from the queue. */
ULONG
ulElement; /* An indicator that specifies whether to remove the first
element in the queue or the queue element that was previously examined
by DosPeekQueue. */
BOOL32
bWait; /* The action to be performed when
no entries are found in the queue. */
PBYTE
pbPriority; /* The address of the element's priority value. */
HEV
hSem; /* The handle of an event semaphore
that is to be posted when data is added to the queue and wait is set to
1. */
APIRET
ulrc; /* Return Code. */
ulrc = DosReadQueue(hq,
pRequest, pcbData,
ppBuf, element, wait, pbPriority,
hsem);
hQue is a handle of the queue to be read from. pRequest
is a pointer to a REQUESTDATA structure that returns a PID and an event
code. pcbData is an output parameter that specifies the length
of the data to be removed. ppBuf is an output parameter that is
a pointer to the element being removed from the queue.
ulElement is an indicator that can be either 0, meaning remove
the first element from the queue, or a value returned by DosPeekQueue.
Table 5.4 lists the values for bWait.
Table 5.4. Values for bWait
| Value |
Description |
| DCWW_WAIT |
The thread will wait for an element to be added to the queue |
| DCWW_NOWAIT |
Return immediately with ERROR_QUE_EMPTY if no data is available |
pbPriority is an output parameter that indicates the priority
of the element being read. hSem is a handle of an event semaphore
that will be posted when data is added to the queue, and DCWW_NOWAIT is
specified.
The OS/2 QUEUE Client-Server example is best illustrated by starting
several OS/2 window sessions from the desktop and making all of them visible
to the user at the same time. The queue Server process must be started
first. Once the queue is created and the queue Server is started,
the queue Clients can use the queue to pass various information
to the queue Server. In this case the information that is
passed is the keystrokes the user enters from each one of the Client
processes.
Figure 5.1 illustrates this procedure.
 |
|
Figure 5.1 Diagram of a queue.
|
Table 5.5 Queue client Text Colors
| Number |
Color |
| Client 1 |
Red |
| Client 2 |
Green |
| Client 3 |
Yellow |
| Client 4 |
Blue |
| Client 5 |
Magenta |
|
Each one of the queue Clients will send keystroke characters
the queue Server via FIFO queue. Once the characters are received
by the queue Server. they will be displayed in color depending on
the Client that sent them. Table 5.5 describes the queue client
text colors.
The QSERVER.EXE allows only up to five active QCLIENT.EXE connections
at any one time. Once the maximum number of clients has been reached, entering
QCLIENT.EXE followed by a carriage return from the command line will produce
a program error message describing the maximum number of clients.
The complete listing of QSERVER.C follows.
|
QSERVER.C
QSERVER.DEF
Now that the intended operation of the OS/2 QUEUE Client - Server has
been described, the implementation itself can be discussed in greater detail.
During the initialization Server uses the InitServerQueEnv()
first to allocate the named shared memory segment, next to create the queue,
and last to create the queue event semaphore.
The named shared memory segment is used as a common communications area
for all of the Clients and the Server. The shared named memory
segment later will contain client-specific information: the Client process
ID. and the client text color ANSI escape sequence. The memory map in Figure
5.2 shows the way the shared named memory segment is used
| |
Color string |
PID |
|
| 0x000 |
Red |
|
<------- Client 0 Area |
| |
Green |
|
<------- Client 1 Area |
| |
Yellow |
|
<------- Client 2 Area |
| |
Blue |
|
<------- Client 3 Area |
| |
Magenta |
|
<------- Client 4 Area |
|
0x0fff |
UNUSED MEMORY |
|
Shared memory map (\SHAREDMEM\MYQUEUE.SHR)
Figure 5.2 Shared memory map.
A client area is dedicated to each one of the queue Clients and
contains the entire MYQUESTRUCT structure. After the shared memory is allocated,
the queue Server creates the queue and initializes the named shared
segment to nulls. The last API that is called by the initialization routine
is DosCreateEventSem. Even though the semaphore that
is created will not be used as a semaphore during this application, its
handle is required later for the DosReadQueue. The
reason it is required in this case because the queue is read in nonblocking
mode, and the API requires a semaphore handle in that case. Choosing to
read the queue in nonblocking fashion allows the queue Server main
thread to perform other functions while waiting for the new queue elements.
APIRET DosCreateEventSem( PSZ pszName,
PHEV phev, ULONG flAttr, BOOL32 fState )
przName is a pointer to the ASCII name of the semaphore, phev
is an output parameter that is a pointer to the semaphore handle. flAttr
is
either DC_SEM_SHARED to indicate the semaphore is shared, or 0. All named
semaphores are shared, so if pszName is not null, this argument is unused.
fState can be either TRUE, meaning the semaphore is initially
"posted" or FALSE, meaning the semaphore is initially "set."
In the initialization of the queue Client environment, the InitClientQueEnv()
function call attempts to obtain the named shared memory handle. Once the
handle is returned, the queue Client begins to scan the client areas,
checking for the valid color string. The moment the Client finds
an unused color string area, it assumes it is free and copies its color
attribute there. It also saves the unique position identification number
in the global sIndex variable. If the Client determines that five
other Clients are already active, it will display an error
message and exit. On the other hand, if the sIndex value is acceptable
(less
than maximum number of Clients), the Client will issue the
DosOpenQueue() API call, thus completing the initialization
by connecting to the queue.
QCLIENT.C
QCLIENT.DEF
QCOMMON.H
Q_CS.MAK
First, the queue server attempts to read the queue; if any elements are
present, they are decoded and displayed in their corresponding color; otherwise
the Server loops to check for the next queue element. The ERROR_QUE_EMPTY
is ignored and reset to 0. It is normal for the Server to receive
this particular error since it is possible for the queue to have no messages
from any of the Clients.
Readers may wonder why the queue is read continuously in nonblocking
mode when it can be read in blocking mode, which will assure a returned
queue element prior to completing the DosReadQueue
call. The answer is simple. If the DosReadQueue API
was implemented with the blocking flag set to true, it would be difficult
for the main thread to do anything other than wait. An additional thread
would have to implemented to handle any other type of work. It is also
possible to implement a separate thread that waits on the queue event semaphore
and displays the characters only when the semaphore was posted. Because
either method would be more complex, we chose the current implementation
for this sample program. The point here is to show the differences between
the OS/2 queues and the OS/2 named pipes.
The Client does nothing more than read a keystroke character
and write that character to the queue by issuing a WriteToQue()
function call, which in turn calls the DosWriteQueue() API.
APIRET DosWriteQueue( HQUEUE hQue, ULONG ulRequest, ULONG
cbData, PVOID pbData, ULONG ilPrority)
hQue is a handle of the queue to which data is to be written. ulRequest
is a user-defined value passed with DosPeekQueue. cbData
is length of the data that is being written. pbData is a pointer
to the data. ulPriority is a priority of the data being added to
the queue. Any value between 0 and 15 is accepted. A value of 15 indicates
the element is added to the top of the queue, and a value of 0 indicates
the clement is the last element in the queue.
This example shows that the OS/2 queues are somewhat cumbersome to
implement; however, they are very useful when several processes have to
talk to a single process, even if the processes are unrelated.
Note: The InitClientQueEnv function
has a potential timing problem. If multiple clients decide to initialize
concurrently, a race condition will ensue. To avoid a potential problem.
a Mutes semaphore should be installed to protect the access to the shared
memory. The implementation is left as an exercise for the reader.
An OS/2 Semaphore vs. Flag Variable Example
There are three different types of semaphores: Event, Mutes, and MuxWait.
Event semaphores are used when a thread or a process needs to notify other
threads or processes that some event has occurred. Mutes semaphores enable
multiple threads or processes to coordinate or serialize their access to
some shared resource. MuxWait semaphores, on the other hand, enable threads
or processes to wait for multiple events to occur.
With this brief introduction, here is the last IPC example pair: STHREAD.C
and FTHREARC. This case uses the concept of semaphores for task or event
synchronization, also known as signaling. If a process is waiting for a
resource to become available, such an a file or a port access right, and
the resource is being used by another process, the current task must wait.
In the earlier DOS operating systems the synchronization was accomplished
primitively through the use of flags. The developer would set a flag, then
wait for the flag to be cleared, thus signaling that the resource was free
to be used. Since only one process could execute at a time under DOS, this
was an acceptable form of pseudo interprocess communication. Under OS/2,
however, it is not a good idea to use flags to perform the equivalent semaphore
functions. An example of this bad flag synchronization processing is evident
in FIILREAD.C, which employs the following construct:
while (FlagBusy); /* Wait for flag
to clear */
If a task requires this type of processing, a semaphore should be used.
The STHREAD.C example demonstrates the difference in the number of machine
cycles that are spent waiting for a semaphore to clear as opposed to waiting
for a flag to clear. The STHREAD.EXE creates several threads and then decides
to wait on a semaphore. The default number of threads is 10, but that number
can be changed by providing an input argument to the STHREAD.EXE program.
While this wait is in process, the user is free to type characters at the
keyboard, which will be echoed to the console immediately. In contrast,
the FTHREAD.EXE uses the same logic but employs a flag variable to perform
the wait inside the threads, which dramatically increases CPU usage, and
the keystrokes will appear greatly delayed. The FTHREAD.EXE also can accept
an input argument specifying the number of threads to be created to wait
on the same flag variable. Even with as little as 30 threads, the difference
between waiting on a flag variable and waiting on a semaphore is dramatic.
FTHREAD.C
FTHREAD.DEF
STHREAD.C
STHREAD.DEF
SFTHREAD.MAK
Example of usage:
FTHREAD [NUMTHREADS]
or
STHREAD [NUMTHREADS]
The first command-line argument, NUMTHREADS, should be a number in
the range of 11 to 255. The default number of threads created is 10; specifying
a number less than 10 is unnecessary. It is not recommended to go over
100 threads with FTHREAD.EXE. Doing so even on a superfast Pentium PC will
cause the system to respond to keystrokes very slowly. For example, once
the C'TRL-ESC keys are pressed, it may take the system several minutes
to paint the PM/WPS screen. STHREAD.EXE, on the other hand, is perfectly
capable of handling 255 threads in the wait state and will still provide
reasonable keyboard and display response.