PCjs Machines
Home of the original IBM PC emulator for browsers.
Microsoft Systems Journal (Vol. 6)
The following document is from the Microsoft Programmer’s Library 1.3 CD-ROM.
Microsoft Systems Journal Volume 6
────────────────────────────────────────────────────────────────────────────
Volume 6 - Number 1
────────────────────────────────────────────────────────────────────────────
Adapting Extended Processes to the Cooperative Multitasking of Microsoft
Windows
William S. Hall
Programming a lengthy process in the Microsoft Windows graphical environment
requires unique considerations. Unlike single-tasking or preemptive
multitasking operating environments, Windows1 uses message-driven,
cooperative multitasking to perform tasks. Windows programs do not execute
until a message is received; once received, the message must be processed
quickly so that control of the CPU can be relinquished to permit other
Windows programs to run. Performing a time-consuming process by coding a
single uninterrupted thread of execution is completely unsatisfactory
because Windows will never run any other task and will appear frozen to the
user during that time.
Fortunately, large tasks can often be broken down into smaller ones, each of
which can be quickly executed whenever the program is allowed to run. If
some means can be found for gaining control at appropriate intervals and
dispatching each task in the proper sequence, then it should be possible to
implement an extended process smoothly in Windows.
Asynchronous file transfer between two computers serves as a good example of
an extended process, because it can take hours over conventional
communication lines. This article demonstrates how to coordinate an extended
process into Windows using the popular Kermit file transfer protocol. One
common approach to writing a Kermit program involves breaking the protocol
into a sequence of tasks controlled by a finite state machine. I'll describe
modifications of this approach that fit the requirements of Windows and
illustrate how the program can be made to schedule its next task without the
use of a timing mechanism.
An implementation of Kermit that can be easily integrated into a Windows
terminal emulator is provided, as well as a sample terminal program that
uses this implementation. The program is capable of sending and receiving
files in text and binary formats over 7- and 8-bit wide data paths while
employing any of three methods of error detection and run-length encoding
for efficiency. Wildcards can be used to transfer groups of files in a
single operation. Although server mode and extensions such as long and
attribute packets are not included, the program is quite complete.
A total of 40 files are used to build Kermit and the two terminal emulators
described here. Partial listings taken from the Kermit and terminal programs
are included with this article. The complete source code needed to build
Kermit, the simple Windows terminal emulator, and the same emulator with
embedded Kermit is available on any MSJ bulletin board.
Realizing Kermit's Session Layer in Windows
In a Kermit session, information is exchanged by encapsulating blocks of
data in various types of packets that are normally less than 100 bytes in
length, unless an extended packet type is being used (see Figure 1).
Although Kermit is not a layered protocol as specified in the ISO open
system standards, most versions of Kermit are written with these layers in
mind to isolate functionality and make it easy to extend and maintain.
The Kermit session layer acts as the basic controlling mechanism for the
protocol. When sending or receiving a file, the session layer is driven by
the packet type received from the remote Kermit. This session layer can be
thought of as a finite state machine.
A public-domain tool called Wart has been developed for Kermit that allows a
programmer to describe such state machines very elegantly (see the sidebar
"Building a Finite State Machine with Wart" ). The Wart tool converts the
protocol description into a table-driven case statement, which is entered at
run time by calling the wart() function. The current state is maintained in
a static variable; thepacket type is obtained by the wart() function's call
to the transport layer function input() (the Kermit code implements its
protocol description using wart() in the file WNKERM.W, as shown in Figure
2). In turn, input() calls a data link layer function, rpack (see Figure 3),
to obtain a complete packet. Figure 4 diagrams the various states of the
Kermit protocol implemented in WNKERM.W.
In Kermit implementations written for single-tasking or preemptive
multitasking operating systems, once wart() is entered it never returns
until the entire session is complete or has been aborted. Likewise, input()
does not return to wart() until a properly formed packet with the correct
sequence number has been found. In turn, rpack does not return to input()
until a complete packet with a correct checksum has been obtained or a
time-out (usually of several seconds) has elapsed.
Of course, none of this waiting around is acceptable in Windows. Suppose
wart() is called from a Windows program as the result of a message. If
wart() runs as above, no other Windows program can run until the file
transfer has completed. Even if wart() returns after the action associated
with each state has been executed, long delays could still be experienced
while rpack tries to read in a complete packet from the communications line.
In fact, a complete packet might never arrive.
On the other hand, the actions associated with each state complete without
significant delay because they involve reading or writing small chunks of
data from a file, encoding or decoding this data, forming it into a packet,
and writing it out to the communications buffer. The solution is to violate
the layering principle and allow the session layer to recognize an
incomplete packet whose associated action is simply to return from wart().
This simple addition to the packet types plus a mechanism to build a packet
incrementally from successive reads of the communications line allows
Windows to release the CPU to other programs in a timely fashion.
This is how it works. Periodically the Windows procedure is entered with a
programmer-defined message that calls wart(), which then calls input(). If a
packet is ready, the action for that state is executed and another call to
input() is made. This time input() most likely returns an incomplete packet
and wart() returns control to Windows. Other tasks can then run; the result
is a nearly seamless multitasking functionality that handles the file
transfer almost transparently.
Of course, the way wart() is scheduled to run has not been explained. But
first, let's look at how the data link layer is handled.
The Data Link Layer
After the input() function calls rpack in the data link layer to get the
next packet, rpack calls getpacket, which parses the input stream into the
packet fields (see Figure 3). The getpacket function frames a packet by
detecting the start-of-packet character; the length of the data field is
used to determine when a complete packet has arrived. On any single call to
getpacket, the input stream may not contain enough data to build a complete
packet, and it may take several calls to this function before a packet can
be delivered.
This means that getpacket must be designed so that when it exhausts the
current data stream, it remembers how far along it has progressed and the
point from which it must continue when called again with more data. A state
machine implementation is again implied; it is easily realized by a case
statement because of the simplicity of getpacket. The state variable itself
is maintained in a globally visible structure that also contains the other
fields of the current packet. Each time getpacket is called, the case
statement is executed from the current state and returns when the buffer is
exhausted. This way, getpacket and its caller rpack do not need to wait for
more data to arrive from the communications line, and input can return
immediately to wart() with an incomplete packet type.
Waking Up the Session Layer
The missing piece in the above scenario is the scheduling of the session
layer. An obvious solution is to use a timer and place the call to wart() on
this thread. A timer, however, does not adjust to changing load conditions
and extra effort must be made to set the timing interval according to the
current baud rate.
A more satisfactory method is to replace the conventional GetMessage call in
the Windows message loop with PeekMessage. Whereas GetMessage does not
return to the program until a message has been placed into its queue,
PeekMessage always returns whether there is a message or not.
To use PeekMessage, your program processes any Windows messages that can be
pulled from the queue, or, if there are none, it does something else for a
short period. In the design used here, the communications port is polled
during this time, and any pending data is loaded into a local buffer. Then a
programmer-defined message is posted back to the window. The next call to
PeekMessage retrieves this message and the associated action is to call
wart(). Getpacket is entered via calls to input and rpack with the buffer
that was filled when the communications port was polled by PeekMessage. If a
complete packet is built, the next action in the session layer state machine
is executed. Otherwise, wart() sees an incomplete packet, and returns to
Windows. Figure 5 shows the message loop and excerpts of the WinProc used in
the sample terminal emulator.
Sample Application
The complete source code for a Windows-based terminal emulator with embedded
Kermit support (see Figure 6) can be found on any MSJ bulletin board. You'll
need the Microsoft Windows Software Development Kit (SDK) Version 3.0 and
Microsoft C Version 5.1 or 6.0 to build the application. A typical Windows
program, the terminal program consists of three parts: source, resources,
and definitions. Of course, the additions needed to add Kermit functionality
affect each of these three components.
For the most part, the Kermit module is independent of the terminal source
code. This module is a library to be added at link time. Of course the
terminal program cannot be entirely ignorant of certain Kermit functions,
and Kermit itself needs to be aware of certain variables such as the main
window and instance handles, the current communications channel, and the
location of the buffer used for reading data from the port. However, all of
these details can be handled fairly easily in the terminal source. By using
conditional compilation, the changes to the original code become clearly
marked, making adaptation to other terminal programs fairly straightforward.
Trying to maintain this same degree of isolation with respect to resources
is another matter. Kermit requires a user interface, so a string table, menu
item, and several dialog boxes have been added. Although the resource
compiler supplied with Version 3.0 of the SDK is a definite improvement over
its 2.x predecessor, it is still difficult to maintain multiple compilations
with a single source. In the end, it is necessary to build one RC source
file for the plain terminal emulator (without Kermit), another for the
emulator with Kermit, and then #include other resource files as needed.
Of course, the additional Kermit code and resources also affect the DEF file
because they require more function exports and segment names. But since it
is possible to have more than one SEGMENTS and EXPORTS section in a single
DEF file, it is quite simple to create a combined DEF file by concatenation.
Of course, segment names as well as function export numbers should be
unique.
There are three make files that control the sources. The first, WNTERM,
simply builds the original terminal program, WNTERM.EXE. It is provided so
you can see clearly what has to change when the Kermit code is added. The
second, WNKERM, makes the Kermit library and compiles the Kermit resources.
The third make file, WNKTERM, builds the terminal with embedded Kermit
support, WNKTERM.EXE.
The Kermit Header File
Each of the Kermit modules as well as the terminal code that references
Kermit variables or constants must include the header WNKERM.H (see Figure
7). It consists of Kermit function prototypes, a menu, resource strings,
general manifests, and a number of structures associated with dialog boxes
or the protocol. All Kermit variables are defined in this header file. At
least one module in the terminal code should include WNKERM.H to declare the
data. To avoid possible conflicts with the terminal code, all variables and
functions begin with the prefix krm. All manifests include the string KRM_.
Thus, IDS_KRM_XXX names a string stored in the resource file, IDM_KRM_XXX, a
menu item, and IDD_KRM_XXX, a dialog box control. Strings use a reference
value, and other strings' manifests base themselves from this reference. The
base value is set to 10,000, but can be changed to avoid possible conflict
with the terminal code. The same is true of menus.
The Kermit code expects certain variables to be available from the terminal.
These are copied to Kermit variables at initialization. One of these, the
handle of the main window, is good for the lifetime of the program. Other
values may change periodically. For example, the communications port
identifier (cid) may vary if the user selects a different port. Because of
this, the Kermit code uses a pointer to reference the cid. Kermit must also
be able to reference a linear character buffer along with its current count,
so the count and the start of the buffer are kept as pointers by Kermit.
Kermit also expects that there are routines in the terminal to fill this
buffer by reading the com port and delivering the input to Kermit via a call
to the state switcher wart().
Kermit and the Terminal's Main WinProc
Of course, the terminal's main WinProc is also affected by the addition of
Kermit support. When the main terminal window is created, a call is made to
Kermit at WM_CREATE time to pass along information such as the window
handle, buffer information, and the location of the communications port
identifier. Except for the handle, this information changes dynamically, so
pointer variables are needed. During the initialization, WIN.INI is also
read under the subhead [Kermit] to provide user settings pertaining to the
protocol and inbound and outbound packets. The Kermit menu is also added to
the end of the terminal's main menu. Finally, if the port to be used is not
yet known, the Kermit menu should be initially disabled.
In the event either Windows or the program is closed, any global resources
used by Kermit must be freed. If termination is attempted in the middle of a
transfer, the user must have a chance to change his or her mind. In the
Kermit exit code, a message box appears if a transfer is still in progress.
If the reply is to shut down (IDYES), an error packet is sent to the remote
Kermit, all files are closed (incompletely received files are deleted if
this option has been set), and the response to WM_CLOSE or
WM_QUERYENDSESSION proceeds as usual. Otherwise, the session continues as if
nothing happened.
The Kermit menu allows the user to send a group of files (see Figure 8),
receive a group of files, cancel a transfer in one of several ways, and
select default values for several protocol and packet parameters (see
Figures 9 and 10). The Kermit menu processor returns TRUE if a menu item was
recognized and handled. Otherwise it returns FALSE; this is a signal for the
terminal to execute its own handler for WM_COMMAND.
When Kermit is in action, any child windows on the screen are hidden and a
modeless dialog box is posted to show the state of the transfer (see Figure
11). Of course, the transfer continues even if the terminal program is
minimized. If the terminal program draws its own icon rather than using a
class icon, Kermit will show the number of packets exchanged like an
odometer (with rollover every 10,000 packets) in the icon window. This lets
the user monitor progress even when he or she is performing other tasks and
the terminal is running in the background (see Figure 12). This display is
managed in response to the WM_PAINT message.
Finally, as already noted, Kermit calls the state machine in response to a
programmer-defined message. You have already seen how such a message is
generated by PeekMessage.
Conclusion
By breaking up a long process into naturally occurring shorter ones, it is
possible to preserve the cooperative multitasking feature of Windows and
still get the job done. Although Kermit has been used to illustrate specific
techniques, the principles presented here can be applied to other
communication protocols, as well as complex, time-consuming tasks that can
be described with a finite state machine approach.
1 For ease of reading, "Windows" refers to the Microsoft Windows graphical
environment. "Windows" refers to this Microsoft product only and is not
intended to refer to such products generally.
2 As used herein, "DOS" refers to the MS-DOS and PC-DOS operating systems.
The Kermit File Transfer Protocol
Like its famous puppet namesake, the Kermit file transfer protocol is
internationally known. Since its introduction in 1980, Kermit has become a
mainstay of academic and business computing, supported on machines from the
largest mainframes to the tiniest microcomputers. Operating systems
supporting this protocol include VM/CMS, DOS2, OS/2, CP/M, UNIX, and even
the USCD P-System. Kermit has been written in Algol, Pascal, C, FORTRAN,
BASIC, BCPL, CROSS, Compass, FORTH, PAL-8, MUMPS, BLISS, PL/1, Ratfor, PL/M,
Modula-2, LISP, and quite a few assembly languages. Kermit's importance is
rivaled only by the XMODEM protocol. There is even an IBM 370 version of
Kermit in Russian.
Kermit was written to answer the need for a reliable means of transferring
files from micros to mainframes. Simply uploading and downloading files is
often unreliable. Unusual file formats, noisy lines, or busy mainframes
expecting input at human typing speed frequently result in a trashed
transfer. To address this problem, Frank da Cruz and his associates at
Columbia University developed a protocol that supported operations between
DECSYSTEM-20 or IBM 370 systems and microcomputers running CP/M and DOS.
These early programs were made available to users along with the source
code. Today, Kermit remains free and is widely available at no more than the
cost of distribution. This policy has not only broadened the support base
for Kermit, it has also contributed to its astounding acceptance by the
computing community.
At first, Kermit was only capable of transferring text files in packets
containing at most 94 characters, using a simple 1-byte checksum. Since
then, Kermit has been extended to include binary transfers over 7- and 8-bit
wide paths, run-length encoding, CRC checksums, long packets, transfers over
networks, server modes, and more recently, sliding windows. Today, you can
not only send your file, you can preserve its attributes including its date
and time of creation. Kermit can even translate between varying character
sets such as ASCII, ISO Latin I, ISO Latin/Cyrillic, ISO Latin/Hebrew, and
Japanese JIS X 0208. Kermit has special features for users with visual,
hearing, or motor impairments, including speech synthesis, a simple
command-line interface, and special program documentation.
Most Kermit programs offer sophisticated terminal emulation as well as file
transfer. For example, Version 3.0 for DOS, written by Joe Doupnik of Utah
State University, emulates DEC VT320 terminals and supports Tektronix
graphics. Other features include screen rollback, Windows compatibility, a
visual bell for deaf users, right-to-left screen display for Hebrew and
Arabic, and a complete scripting language. Kermit rivals commercially
available products, but costs at most $20.00.
Building a Finite State Machine with Wart
Wart, written by Jeff Damens of Columbia University, is a tool that builds
state table switchers. Wart contains a small subset of the UNIX lexical
analyzer generator, lex, and may be freely distributed (lex, which means
"word" in Latin, translates to wort in German, which sounds like wart on a
frog).
Wart accepts as input a C program in the following format.
lines to be copied | %state <state names...>
%%
<state> | <state,state,...> CHAR { actions }
.
.
.
%%
The %state directive declares the program's states. The section enclosed
between the %% delimiters is the state table. A typical entry has the form
<state>X {action}
which is read as
"if in state <state> with input X, perform {action}".
The optional <state> field names the states the program must be in to
perform the related action. If no state is specified, the action is carried
out regardless of the current state. If more than one state is specified,
the action is performed in any of the listed states. Multiple states are
separated by commas.
The required input field consists of a single literal character. In a given
state, if the input is the specified character, the associated action is
performed. The character . matches any input character. No pattern matching
or range notation is provided. The input character itself is obtained from a
function called input(), which the user must define. Input should return an
alphanumeric character or one of the following characters.
% - _ $ @ .
The action statement is a series of zero or more C statements enclosed in
curly braces. Wart also provides the BEGIN macro, which is defined as state
= , as it is in lex. Wart is invoked at the command line as follows:
wart file.w file.c
In this example, Wart reads FILE.W and produces FILE.C, which can then be
compiled as an ordinary C program. Wart's output contains the function
called wart(), whose form depends on the state declarations and the state
transition table. Wart loops through calls to input() and uses the result to
index into a case statement created from the state table.
The following program demonstrates some of the capabilities and limitations
of Wart. BINTODEC.W accepts a binary number from the command line, preceded
by an optional minus sign and possibly containing a fractional part, and
prints the decimal equivalent.
BINTODEC.W
#include <stdio.h>
int state, s = 1, m = 0, d;
float f;
char *b;
/* Declare wart states */
%states sign mantissa fraction
/* Begin state table */
%%
<sign>- { s = -1; BEGIN mantissa; } /* Look for sign */
<sign>0 { m = 0; BEGIN mantissa; } /*Got digit,start mantissa */
<sign>1 { m = 1; BEGIN mantissa; }
<sign>. { fatal("bad input"); } /* Detect bad format */
<mantissa>0 { m *= 2; } /* Accumulate mantissa */
<mantissa>1 { m = 2 * m + 1; }
<mantissa>$ { printf("%d\n", s * m); return; }
<mantissa>. { f=0.0; d = 1; BEGIN fraction; } /* Start fraction */
<fraction>0 { d *= 2; } /* Accumulate fraction */
<fraction>1 { d *= 2; f += 1.0 / d; }
<fraction>$ { printf("%f\n", s * (m + f) ); return; }
<fraction>. { fatal("bad input\n"); }
%%
input(void) { /* Define input() function */
int x;
return(((x = *b++) = = '\0') ? '$' : x );
}
fatal(char *s) { /* Error exit */
fprintf(stderr,"fatal - %s\n",s);
exit(1);
}
main(int argc,char **argv) { /* Main program */
if (argc < 2) {
fprintf(stderr, "Not enough input\n");
exit(1);
}
b = *++argv;
state = sign; /* Initialize state */
wart(); /* Invoke state switcher */
exit(0); /* Done */
}
The following code is generated by processing BINTODEC.W with WART.EXE:
BINTODEC.C
/* WARNING --This C source program generated by Wart preprocessor.*/
/* Don't edit this C file; edit the Wart-format .W file instead, */
/* and then run it through Wart to produce a new C source file. */
/* Wart Version Info: */
char *wartv = "Wart Version 1A(006) Jan 1989";
#include <stdio.h>
int state, s = 1, m = 0, d;
float f;
char *b;
/* Declare wart states */
#define sign 1
#define mantissa 2
#define fraction 3
/* Begin state table */
#define BEGIN state =
int state = 0;
wart()
{
int c,actno;
extern short tbl[];
while (1) {
c = input();
if ((actno = tbl[c + state*128]) != -1)
switch(actno) {
case 1:
{ s = -1; BEGIN mantissa; }
break;
case 2:
{ m = 0; BEGIN mantissa; }
break;
case 3:
{ m = 1; BEGIN mantissa; }
break;
case 4:
{ fatal("bad input"); }
break;
case 5:
{ m *= 2; }
break;
case 6:
{ m = 2 * m + 1; }
break;
case 7:
{ printf("%d\n", s * m); return; }
break;
case 8:
{ f = 0.0; d = 1; BEGIN fraction; }
break;
case 9:
{ d *= 2; }
break;
case 10:
{ d *= 2; f += 1.0 / d; }
break;
case 11:
{ printf("%f\n", s * (m + f) ); return; }
break;
case 12:
{ fatal("bad input\n"); }
break;
}
}
}
short tbl[] = {
-1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
-1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
-1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
-1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
-1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
-1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
-1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
-1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
-1, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4,
4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4,
4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 1, 4, 4,
2, 3, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4,
4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4,
4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4,
4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4,
4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4,
-1, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8,
8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8,
8, 8, 8, 8, 7, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8,
5, 6, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8,
8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8,
8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8,
8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8,
8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8,
0, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12,
12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12,
12, 12, 12, 12, 11, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12,
9, 10, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12,
12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12,
12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12,
12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12,
12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12,
};
input(void) { /* Define input() function */
int x;
return(((x = *b++) = = '\0') ? '$' : x );
}
fatal(char *s) { /* Error exit */
fprintf(stderr,"fatal - %s\n",s);
exit(1);
}
main(int argc,char **argv) { /* Main program */
if (argc < 2) {
fprintf(stderr, "Not enough input\n");
exit(1);
}
b = *++argv;
state = sign; /* Initialize state */
wart(); /* Invoke state switcher */
exit(0); /* Done */
}
Creating a Network Service Using the Client-Server Model and LAN Manager 2.0
Brendan W. Dixon
As the PC industry has matured, concepts and techniques pioneered on larger
systems have been adapted for PC users. Many of these, such as preemptive
multitasking, virtual memory and paging, are little changed on PCs. Others
have been combined with features unique to PCs, producing new uses for
computers. For example, when the graphical capability of the PC was combined
with the large-system approach to document preparation, a whole new
industry, desktop publishing, was created. The client-server model combines
the large-system concept of centralized resources with the PC's peer-to-peer
approach to networking, and lays the groundwork for distributed processing.
The client-server model is an application design approach that distributes
resources and processing between systems in a network. Unlike the standard
network model, where each client participates in resource management, the
client-server model divides responsibilities and intelligence. Servers
contain all of the intelligence necessary to own and manage the resource
(for example, a database server, as in Figure 1). Clients contain only
nominal information about the resource (that it is a database, for instance)
and do not assist in its management; they pass requests to the server, which
the server decides to accept or reject. Conversely, servers are unaware of
the client's intentions. A server only responds to requests for the resource
it is managing (say, a database transaction). Centralizing resource
management onto the server simplifies error handling and reduces the network
load. Removing resource management tasks from the clients reduces processing
requirements on workstation hardware and allows them to focus on their
primary responsibilities such as interfacing with the end user.
Microsoft LAN Manager is designed to support client-server programming.
While LAN Manager provides all of the facilities of standard PC networks
(that is, file and printer sharing), it also provides a platform that
simplifies the construction of client-server-based applications and network
communication.
This article examines the building of a LAN Manager service. Creating and
managing a group of remote named pipes will be discussed in a future
article, as well as the construction of a LAN Manager client under the
Microsoft Windows and OS/2 Presentation Manager graphical environments.
The LAN Manager Application Programming Interface (API) gives the programmer
a robust set of function calls to communicate with LAN Manager and issue
network requests. Almost any network task that can be performed from the
command line or by using LAN Manager's full-screen interface can also be
done through in-line code. There are nearly 130 API calls (see Figure 2),
and many take modal parameters that can be used to tune the function.
Most important for client-server programmers is LAN Manager's support of
remote named pipes. Named pipes are one-way or bidirectional facilities that
allow processes to communicate. They offer guaranteed delivery and built-in
buffering, simplified error detection, and access security.
Another feature of LAN Manager is nonconnection oriented messaging through
mailslots. Mailslots are useful for peer-to-peer communication, message
broadcasting, and client-server communication that does not require all the
facilities of a named pipe. Mailslots are either first-class (with
guaranteed delivery) or second-class (without guaranteed delivery). Remote
first-class mailslots, which can receive messages from remote workstations,
must be created on a LAN Manager server. But any workstation may send or
receive remote messages on a second-class mailslot.
Named pipes and mailslots enable the programmer to build applications that
utilize the network without being network-aware. LAN Manager also makes it
easy for the network administrator to control access to named pipes and
mailslots, and therefore the network. These facilities lead to easily built,
easily maintained, and easily controlled client-server applications.
Sample LAN Manager Service
In order to provide a consistent method of control for the network
administrator, LAN Manager was designed as an extensible system, implemented
as a group of services. A LAN Manager service is a detached OS/2 process
(that is, no console I/O) running as an extension of LAN Manager. Such a
service can be controlled (that is, started, paused, continued, or stopped)
through LAN Manager. Developing a LAN Manager service requires only that the
service be listed in the LANMAN.INI file, that it register itself with LAN
Manager as part of its start-up processing, and that it respond to LAN
Manager requests, which are sent to the service through the OS/2 signal
mechanism. Additionally, a LAN Manager service may take tuning parameters;
these are also normally specified in the LANMAN.INI file.
In the client-server model, the server makes resources available to the
client and manages those resources for the client. One server resource,
normally unavailable to clients, is the ownership of remote named pipes.
While a client may open and communicate on a remote named pipe, it cannot
create the pipe; remote named pipes are a resource provided by a LAN Manager
server and must be created on the server.
A sample LAN Manager service designed for this article, PBX, can serve as
the foundation for real-world client-server applications. PBX gives clients
the ability to establish peer-to-peer communications using named pipes
through a transparent routing mechanism. Clients register with PBX and
request connections with other clients. Once a connection is established
between two clients, PBX maintains the image of a peer-to-peer named pipe
connection for each client until the connection is broken. PBX creates at
least three threads in addition to the main thread created when PBX is given
control. Each thread is named after its C routine (see Figure 3). This
article examines the main thread, which initializes PBX and communicates
with LAN Manager. A future article will examine the remaining threads, which
create and maintain the virtual named pipe connections (see Figure 4 for the
source code files used to build PBXSRV.EXE).
To build a LAN Manager application, you will need either the Microsoft LAN
Manager Programmer's Toolkit or the Microsoft LAN Manager Developer's
Toolkit. These toolkits include the C header files and libraries utilized
in a LAN Manager application.
To support a LAN Manager API category in your program, you add one or more
#define statements and a #include for LAN.H in your C source file. Figure 2
lists the C preprocessor constants for each LAN Manager API category. For
example, to include support for mailslots, you would add the following to
your program file:
#define INCL_NETMAILSLOT // Include mailslots
#define INCL_NETERRORS // Include error constants
#include <lan.h>
As for linking your application, most LAN Manager applications need to link
only with LAN.LIB, so you simply add this library to those you would
normally use (see Figure 5).
To build a LAN Manager service you will need to include support for the
service APIs by including a #define statement for INCL_NETSERVICE before you
#include LAN.H. Your program must also contain an OS/2 signal handler and
use the service APIs to maintain a simple communication protocol with LAN
Manager. These points will be covered in more detail further on.
Installing a LAN Manager Service
A service is started from the command line using the LAN Manager NET command
or using the LAN Manager full-screen interface. The PBX service could be
started from an OS/2 command prompt by typing:
NET START PBX
Services can also be started and stopped automatically when the LAN Manager
Workstation or Server service starts or stops by adding the service name to
either the wrkservices or srvservices line in LANMAN.INI (see the Microsoft
LAN Manager Administrator's Reference for details on LANMAN.INI).
When requested to start a service, LAN Manager scans the services section of
LANMAN.INI for an entry describing where to find the EXE to execute. Each
entry under the services section names a service and supplies the location
and name of the EXE file to be executed to start the service.
[services]
.
.
.
service_name = service_exe_path
The service_name is the name the service is known by to LAN Manager and the
user; with our sample, it's PBX. The service_exe_path describes the path of
the EXE file to execute. If the service EXE is in the LAN Manager directory,
the pathname can be relative. This is the case for the services shipped with
LAN Manager. If the EXE is outside the LAN Manager directory, the full
pathname and drive must be supplied.
Optionally, a service may take configuration parameters. These are also
specified in LANMAN.INI (though the user may override them when starting the
service),
and should be placed under a section whose heading name is the same as the
service. PBX has five configuration parameters; they would be listed in
LANMAN.INI as shown in Figure 6.
Start-up of a LAN Manager Service
A LAN Manager service receives control at the C main function like any other
C program. Immediately upon receiving control, a service obtains its own
process identifier (PID) and registers with LAN Manager by calling the
NetServiceStatus API:
PIDINFO pidInfo; // OS/2 PID info
struct service_status ssStatus; // LM Service info
// Obtain the process ID of this process
usRetCode = DosGetPID(&pidInfo);
.
.
.
// Inform LAN Manager that this service is in the
// process of installation
// Because the signal handler is not yet installed,
// the service cannot be uninstalled or paused
ssStatus.svcs_pid = pidInfo.pid;
ssStatus.svcs_status = SERVICE_INSTALL_PENDING |
SERVICE_NOT_UNINSTALLABLE |
SERVICE_NOT_PAUSABLE;
ssStatus.svcs_code=SERVICE_CCP_CODE (PBXINSTALLTIME,
0);
usRetCode = NetServiceStatus((char _far *)&ssStatus,
sizeof(ssStatus));
The NetServiceStatus API call takes as its primary argument a pointer to a
buffer that must contain a service_status structure (see Figure 7). LAN
Manager needs the PID of the service to pass control requests to the
service. When a request is made to control a service (for example, NET PAUSE
PBX), LAN Manager signals the service through the OS/2 signal mechanism,
passing a request code in the first byte of the signal argument.
NetServiceStatus is also used by the service to pass status or error
information to LAN Manager. For example, if your service takes more than a
few seconds to install or respond to any LAN Manager request, it should
periodically inform LAN Manager that the request is still pending by calling
NetServiceStatus. Status and error information is passed by setting the
svcs_status and svcs_code fields in the service_status structure. Your
service should set the svcs_status field to the bitwise OR of the
appropriate values (see Figure 8). The service uses the SERVICE_CCP_CODE
macro to set the svcs_code field during installation and while responding to
requests from LAN Manager. The first macro argument is the approximate time
the service will take to install or complete the request in tenths of a
second. The second argument is a checkpoint counter that should be
incremented each time the service informs LAN Manager a request is still
pending.
If an error occurs and your service cannot install, set the svcs_status
field to SERVICE_UNINSTALLED and use the SERVICE_UIC_CODE macro to set the
svcs_code with the uninstall information code (UIC). Some UICs allow an
additional text string to be passed in the svcs_text field. The first
argument to the macro is the code and the second is an optional modifier
(see Figure 9). When the service is uninstalled, use the SERVICE_UIC_CODE
macro to supply LAN Manager with a reason code. For instance,
SERVICE_UIC_NORMAL is the proper UIC during a normal uninstall.
After registering with LAN Manager, the service should next establish a
signal handler for communication with LAN Manager. As mentioned, LAN Manager
communicates with a service by sending OS/2 signals. It does this using the
OS/2 DosFlagProcess API. OS/2 defines three process flags (that is,
signals): PFLG_A, PFLG_B, and PFLG_C. LAN Manager sends requests to a
service using the process flag A (PFLG_A) signal. LAN Manager also defines a
special constant, SERVICE_RCV_SIG_FLAG, which equates to PFLG_A, that can be
used when registering a signal handler to inform OS/2 that the service
should receive signals from LAN Manager. After establishing your signal
handler, inform OS/2 that your handler will ignore CTRL-C, break, and kill
process signals. You want your service to shut down only if requested to by
LAN Manager. Additionally, unless they are used by your service for
communication, process flags B (PFLG_B) and C (PFLG_C) should be regarded as
errors. The InstallSignals function in SIGNALS.C (see Figure 4) demonstrates
the proper technique for establishing a signal handler to communicate with
LAN Manager. Once your signal handler is in place, your service should call
NetServiceStatus again and update LAN Manager with its new status. For
instance, once the signal handler is installed, PBX can be uninstalled,
though it cannot be paused until installation is complete.
Communicating with LAN Manager
LAN Manager control requests are passed to your signal handler in the low
byte of the signal argument, the first argument passed to an OS/2 signal
handler. Again, your handler should respond to these requests quickly or
give LAN Manager status hints as your service is responding. Currently, LAN
Manager passes one of four arguments (see Figure 10). Values 0 through
127 are reserved, leaving 128 through 255 available for your internal
communication. The simplest way to build your signal handler is to use a
switch statement with a case for each possible argument. The PBX signal
handler, SignalHandler in SIGNALS.C, follows the format shown in Figure 11.
The requests SERVICE_CTRL_UNINSTALL and SERVICE_CTRL_INTERROGATE must be
supported by your service. When a SERVICE_CTRL_UNINSTALL is received, your
service should take whatever steps are appropriate for clean up and exit.
Prior to exiting, call NetServiceStatus one last time with the appropriate
UIC code to inform LAN Manager that your service has successfully
uninstalled. The ExitHandler routine in SIGNALS.C handles all exit requests,
error or otherwise, for PBX.
In response to a SERVICE_CTRL_INTERROGATE request, your service should call
NetServiceStatus with the current state of the service. PBX maintains a
global service_status structure that always reflects the current
state of PBX and is returned in response to SERVICE_CTRL_INTERROGATE
requests.
If you allow pausing of your service (as PBX does), you need to process
SERVICE_CTRL_PAUSE and SERVICE_CTRL_CONTINUE requests. A simple and
efficient method is to use OS/2 semaphores to control child threads. If the
semaphore is set, the child thread waits until it is cleared.
Initializing a LAN Manager Service
Once your service is registered with LAN Manager and your signal handler is
in place, you can proceed with initialization. All services should redirect
file handles zero, one, and two (corresponding to standard input, standard
output, and standard error) to the NUL device. The technique used by the
RedirectFiles routine in PBXSRV.C (see Figure 4) is the easiest: it opens
the NUL device for I/O and redirects handles zero through two by calling
DosDupHandle.
After disabling the standard file handles, your service can perform any
specific initialization it has. At this point, most services process the
configurable parameters that were specified either in LANMAN.INI or by the
user when the service was started. LAN Manager passes these parameters to
your service as a standard OS/2 argument string. Values explicitly specified
by the user when the service was started are passed first, followed by any
values from your service's section in LANMAN.INI that were not overridden
when starting the service. These values arrive as the standard C argc-argv
pair. For example, if PBX was started from the command line as below,
NET START PBX /Lines:200 /Connsperthread:10
and LANMAN.INI contained the values listed in Figure 6, PBX would receive
the following in argv:
argv[0] = Pathname of PBX .EXE file
argv[1] = "Lines=200"
argv[2] = "Connsperthread=10"
argv[3] = "LINEBUFSIZE=1024"
argv[4] = "OPENLINES=20"
argv[5] = "AUDITING=NO"
As you can see, the keywords are not in any specific order or case. LAN
Manager preprocesses the keywords to remove blanks and converts the
separating colon to an equal-sign (the user may specify either a colon or an
equal-sign when entering the keyword and its value). Any text following the
equal-sign or colon is treated as the keyword value, including comments, and
is passed to your service. If while overriding a keyword in LANMAN.INI the
user enters only a part of the keyword name, LAN Manager still passes the
full keyword from LANMAN.INI (if it exists). Since explicitly specified
keywords always come first, you may want to ignore second and subsequent
occurrences of a keyword; this allows the user to override values in
LANMAN.INI using short-cuts when starting the service.
Making a Service Known
Some services, such as PBX, offer a resource that will be used
intermittently by clients. In such situations, it benefits the client
application if the service can be automatically detected on the network. PBX
informs clients of its existence by waiting for broadcasts on a mailslot and
then responding with a message containing the name of the computer on which
it is executing.
A mailslot name looks like a pathname without a drive specification whose
root directory is named MAILSLOT. Remote mailslot names are preceded with
either the name of an individual computer (both first-class and second-class
mailslots) or a logical group of computers called a domain, which is used
with second-class mailslots only. A second class message sent to a mailslot
with the following name
\\*\MAILSLOT\mailslotname
sends the message to all machines in the same domain as the sending LAN
Manager workstation. It is recommended that the first qualifier in a
mailslot name, after the keyword MAILSLOT, be a corporate or product
identifier to avoid conflicts with other applications. PBX creates a
mailslot with the following name, using MSJ as the qualifier:
\mailslot\msj\pbx
When a message arrives on its mailslot, PBX responds by sending the name of
the computer on which it is executing prefixed with two backslashes, as in
the start of a remote name. As a message from the client, PBX expects the
computer name on which the client application is executing prefixed with two
backslashes. PBX calls the NetWkstaGetInfo function to get the computer name
on which it is executing. The call is issued twice, the first time with a
zero-length buffer and the second time with the actual buffer size needed.
Any LAN Manager call that returns a structure containing pointers to strings
or other data (instead of a fixed-length array) returns the structure and
the data addressed by the structure in the supplied buffer. Since the buffer
size cannot be statically predetermined, you should make the LAN Manager API
call twice. On the first call your service would pass a zero-length buffer.
LAN Manager will return NERR_BufTooSmall for a return code and the actual
number of bytes needed in the appropriate argument (the last argument on the
NetWkstaGetInfo call). Next, you allocate a buffer of the required size and
make the call again to retrieve the data.
If it is necessary to ensure that only a single instance of your service
exists in a particular LAN Manager domain, a similar approach may be used.
Your service would create a mailslot and wait for messages to arrive, as PBX
does; if a message is received, your service would send an appropriate
response. To determine if an instance of your service is already executing,
your service should send a broadcast message on the mailslot while it is
initializing, and briefly wait for a response. If no response is received,
your service could assume that it is running alone.
Multiple Threads in a LAN Manager Service
When writing a service it's best to use a multithreaded design. Since LAN
Manager communicates with a service through the OS/2 signal mechanism, your
service's main thread will be used to process LAN Manager signals. With
simpler services, it won't be a problem if one thread is used for all
processing. But in more complex programs, the sudden interruption of
processing may leave your service in an unstable state. After initialization
is completed, your main application thread should sleep. This is done most
efficiently by waiting on a dummy OS/2 semaphore.
When its initialization is completed, PBX uses its main thread for
processing signals and responding to broadcasts arriving on its mailslot.
// Run until PBX is shutdown
do {
// Wait until a signal is received or a message
// arrives on the mailslot (which means a client is /// looking for the PBX)
usRetCode = DosReadMailslot(
pbPBXMem->hMailslot, // Handle
pbPBXMem->pbMSlotBuf, // Buffer
&usByteCnt, // Bytes read
&usNextCnt, // Next msg size
&usNextPriority, // Next msg
priority
MAILSLOT_NO_TIMEOUT); // Wait forever
// If control has been returned because a client
// sent a message,return to the client the computer
// name of the machine on which PBX is executing
if (usRetCode == NERR_Success &&
usByteCnt != 0 ) {
strcat(pbPBXMem->pbMSlotBuf, ANNOUNCELINE);
usRetCode = DosWriteMailslot(
pbPBXMem->pbMSlotBuf, // Mailslot
pbPBXMem->pszPBXMsg, // Message
pbPBXMem->usPBXMsgSize, // Message
size
9, // Priority
2, // 2nd class
0L); // No wait
}
} while (usRetCode == ERROR_INTERRUPT ||
usRetCode == ERROR_SEM_TIMEOUT );
// Control never arrives here; the ExitHandler
// always exits PBX
return;
}
Logging Events with LAN Manager
To assist the network administrator, your service should log significant
events with LAN Manager. LAN Manager provides API support for two event
logs, an error event log and a non-error (or audit) log. At the very least,
errors that cause your service to shut down should be reported to LAN
Manager in the svcs_code field of the service_status structure (as noted
above). However, for these and other errors, your service should also log
the event with LAN Manager.
Whenever a significant error is encountered, PBX writes a message to the LAN
Manager error log using NetErrorLogWrite. The second argument passed to this
function is the error number. There are more than 120 error numbers. Most
are specific to services shipped with LAN Manager, some may be used by your
service, and one, NELOG_OEM_Code, was designed for third-party services.
Your service can pass NULL-separated substitution strings for the message
and the number of substitution strings as the sixth and seventh parameters
to NetErrorLogWrite. The NELOG_OEM_Code error message is defined as nine
substitutable strings (with no predefined text). It is recommended that the
first four strings be the company name, service name, error severity (such
as error versus warning), and subidentifier code. The remaining five strings
should contain additional data or be initialized to empty.
PBX writes all of its error messages to the error log via the ErrorRpt
routine in PERROR.C (see Figure 4) using the NELOG_OEM_Code error code. In
addition to the recommended data, PBX supplies the filename and line number
of the place where the error occurred as part of the message. While this may
be unnecessary after you ship your service, it is extremely helpful during
debugging when similar errors may occur along different code paths.
In addition to logging errors, PBX logs significant, non-error events in the
LAN Manager audit log by calling the NetAuditWrite function at the
appropriate times. Audit logging is enabled/disabled in PBX by the AUDITING
keyword, which defaults to YES. Each record in the LAN Manager audit log is
variable length and contains a fixed header, followed by a variable amount
of event-specific data, and a 2-byte field. The fixed header contains the
total length of the record (the length value at the end of the record is
redundant), the type of the record, and the time the record was written.
Your service does not build either the fixed header nor the length field at
the end of the record. You supply only the type of the audit event and the
event-specific data; everything else is built and supplied by the
NetAuditWrite function. Microsoft reserves audit event types 0 through
32,767; audit event types in the range 32,768 through 65,535 may be used by
third-party applications.
To record an audited event, your service calls NetAuditWrite, passing the
appropriate audit event type, a pointer to the event specific data, and the
length of the data. To simplify the logic of your program, NetAuditWrite
returns NERR_Success even if LAN Manager is not currently maintaining an
audit log. The user can disable all auditing when starting the server
service.
If your service does write audit records, you should also supply either a
facility to examine the records in the audit log or at least the necessary
constants and structures to interpret the records written by your service.
The audit event type used by PBX and the structure that maps the variable
portion of the PBX audit record is contained in PBXSRV.H (see Figure 4).
Debugging a LAN Manager Service
Although messages written to the LAN Manager error log can be helpful during
development to track problems, it may be even more useful to build a debug
version of your service that writes more than just error messages to the
error log. Informational messages could be written at critical checkpoints
to track flow of control and processing of requests handled by your service.
Since a service is a detached OS/2 process, your service cannot write to
standard output or standard error to report problems. It also makes it
difficult to use tools such as the Microsoft CodeView debugger. Therefore,
as you develop your service you may want to consider writing and debugging
the bulk of the application prior to converting it to a LAN Manager service.
Also, once your application has been converted to a service, instead of
redirecting standard output to the NUL device, you could direct it to a disk
file and use printf or fprintf to record debugging information. This
technique was used very successfully while developing PBX.
The next article will concentrate on the portions of PBX that create and
manage the named pipes and demonstrate how to build a sophisticated named
pipe server. It will explain multiple threads, managing multiple instances
of a pipe, client-server race conditions, and offer a brief discussion on
the two types of pipes supported by OS/2 and LAN Manager, byte and message
mode pipes.
Figure 2
Category: Access Permissions
Description: Functions to examine or modify resource access
permissions
C Define: INCL_NETACCESS
Category: Alert
Description: Functions to notify services and applications of
network events
C Define: INCL_NETALERT
Category: Auditing
Description: Functions to access and control the LAN Manager
audit log
C Define: INCL_NETAUDIT
Category: Character Device
Description: Functions to control shared communication
devices (such as COM ports) and their queues
C Define: INCL_NETCHARDEV
Category: Configuration
Description: Functions to read the LANMAN.INI file
C Define: INCL_NETCONFIG
Category: Connection
Description: Functions to list connections on a LAN Manager server
C Define: INCL_NETCONNECTION
Category: Domain
Description: Functions to retrieve domain information
C Define: INCL_NETDOMAIN
Category: Error Logging
Description: Functions to access and control the LAN Manager
error log
C Define: INCL_NETERRORLOG
Category: File
Description: Functions to monitor and close file, device, and
pipe resources on a server
C Define: INCL_NETFILE
Category: Group
Description: Functions to control groups of user (part of the
LAN Manager user account subsystem)
C Define: INCL_NETGROUP
Category: Handle
Description: Functions to retrieve or set information for
character device or named pipe specified by a handle
C Define: INCL_NETHANDLE
Category: Mailslot
Description: Functions supporting LAN Manager mailslots
C Define: INCL_NETMAILSLOT
Category: Message
Descripton: Functions to send and receive messages, and
manipulate message aliases
C Define: INCL_NETMESSAGE
Category: Print Destination
Description: Functions to control printers that receive
spooled jobs
C Define: Uses PMSPL.H or DOSPMSPL.H
Category: Print Job
Description: Functions to control jobs in a printer queue
C Define: Uses PMSPL.H or DOSPMSPL.H
Category: Printer Queue
Description: Functions to control printer queues
C Define: Uses PMSPL.H or DOSPMSPL.H
Category: Remote Utility
Description: Functions to support remote file copy and move, the
execution of remote programs, and accessing time-of-day
on a remote server
C Define: INCL_NETREMUTIL
Category: Server
Description: Functions to perform adminstrative tasks on a server
C Define: INCL_NETSERVER
Category: Service
Description: Functions to control LAN Manager services
C Define: INCL_NETSERVICE
Category: Session
Description: Functions to control sessions between workstations
and a server
C Define: INCL_NETSESSION
Category: Share
Description: Functions to control shared resources
C Define: INCL_NETSHARE
Category: Statistics
Description: Functions to retrieve or clear statistics for a
server or workstation
C Define: INCL_NETSTATS
Category: Use
Description: Functions to examine or control uses between a
workstation and a server
C Define: INCL_NETUSE
Category: User
Description: Functions to control a user's account in the user
account subsystem
C Define: INCL_NETUSER
Category: Workstation
Description: Functions to control the operation of a workstation
C Define: INCL_NETWKSTA
Figure 5
■ OS/2 1.2 PMSPL.LIB Print functions (DosPrintxxx)
LAN.LIB All other functions
■ OS/2 1.1 NETSPOOL.LIB Print functions
LAN.LIB All other functions
■ DOS 3.1 and up DOSLAN.LIB All functions
■ Windows 3.0 PMSPL.LIB Print functions
LAN.LIB All other functions
■ Windows 2.x PMSPL.LIB Print functions
LAN.LIB All other functions
Figure 6
[pbx]
lines = 100
linebufsize = 1024
openlines = 20
connsperthread = 5
auditing = no
Figure 7
struct service_status {
unsigned short svcs_status; /* Current service state */
unsigned long svcs_code; /* Install/Uninstall code */
unsigned short svcs_pid; /* Process identifier of service */
char svcs_text[64];/* Additional text buffer */
};
Figure 8
■ General status SERVICE_UNINSTALLED
SERVICE_INSTALL_PENDING
SERVICE_UNINSTALL_PENDING
SERVICE_INSTALLED
■ Paused/Active status SERVICE_ACTIVE
SERVICE_CONTINUE_PENDING
SERVICE_PAUSE_PENDING
SERVICE_PAUSED
■ Uninstallable indication SERVICE_NOT_UNINSTALLABLE
SERVICE_UNINSTALLABLE
■ Pausable status SERVICE_NOT_PAUSABLE
SERVICE_PAUSABLE
Figure 11
// Extract signal argument
fSigArg = (UCHAR)(usSigArg & 0x00FF);
// And take the appropriate action
switch (fSigArg) {
// Uninstall PBX
case SERVICE_CTRL_UNINSTALL:
// Pause PBX
case SERVICE_CTRL_PAUSE:
// Continue (a paused) PBX
case SERVICE_CTRL_CONTINUE:
// Return service information
// Unrecognized arguments should be treated as
// interrogate requests
case SERVICE_CTRL_INTERROGATE:
default:
}
// Acknowledge with OS/2 when signal processing is
// complete
DosSetSigHandler(0, 0, 0, SIGA_ACKNOWLEDGE, usSigNum);
Improve Windows Application Memory Use with Subsegment Allocation and Custom
Resources
Paul Yao
Improved memory usage is one of the most important enhancements in the
Microsoft Windows graphical environment Version 3.0. Protected mode Windows1
lets you access up to 16Mb of RAM, and in 386 enhanced mode, a virtual
address space as large as four times the available physical RAM can be
created. On a machine with 16Mb of RAM and sufficient room on the swap disk,
a 64Mb virtual address space is possible. This is quite an improvement over
the 640Kb limitation that plagued earlier versions.
Windows lets you choose among several types of memory. This article explores
application memory use in Windows and identifies every place that you can
store a byte of data, concluding with sample programs that demonstrate
subsegment allocation and the creation of custom resources.
Subsegment allocation uses the Windows local heap management routines, such
as LocalAlloc and LocalFree, to manage a dynamically allocated segment.
Programmers working in OS/2 systems will recognize this as something
performed by the DosSubAlloc routine, and OS/2 Presentation Manager
programmers may recall that the WinAllocMem routine provides this service.
In the second half of this article, I'm going to show how to use a little
assembly language programming to access this service in a Windows program.
Windows has built-in support for several types of resources: dialog box
templates, menu templates, icons, cursors, and so on, as well as
custom-written resources. Resources are quite memory-efficient because
they are read-only data objects that can be demand-loaded at any time, and
can be discarded (purged) from memory when system memory is low. When a
resource is needed again, it can be reloaded from disk. I'll demonstrate
creating and using custom resources with a sample program.
Memory Management Factors
Four factors are important when dealing with memory: allocation, visibility,
lifetime, and overhead.
"Allocation" refers to who sets aside a piece of memory (see Figure 1). In
some cases, the compiler allocates memory in response to the declaration of
variables. In other cases, memory is allocated in response to calls made to
dynamic allocation routines. Windows has two distinct dynamic allocation
packages: one to allocate segments, and one to partition segments into
smaller pieces. Memory allocation can also occur as a side effect of
creating graphical and user interface objects. For example, when you create
a pen in the Graphics Device Interface, space is set aside in GDI's local
heap. When you create a window or a menu, the Windows user interface manager
allocates memory in its own local heap.
"Visibility" describes who can access memory. Some objects have a very
limited visibility, such
as automatic variables declared inside a function. Other objects, such as
dynamically allocated segments, are visible systemwide. These objects are
the most suitable for sharing data among programs, and are central to the
implementation of the Windows Clipboard and Dynamic Data Exchange (DDE)
mechanisms.
"Lifetime" pertains to the way memory is reclaimed. Generally, when a
program terminates, Windows frees the memory the program allocated. Proper
reclamation of memory is essential to the health and well-being of Windows
as a whole. A few pitfalls require extra care when programming. For example,
programs must explicitly free GDI objects and user interface objects such as
menus before ending. A future version of Windows will hopefully reclaim
memory allocated for these types of objects as well.
"Overhead" refers to the extra cost of using a specific type of memory over
and above the actual bytes used. It is a factor primarily in the context of
dynamically allocated memory. For example, every global memory object has a
minimum overhead of 24 bytes. If you are used to allocating many small,
dynamic memory objects, you need to rethink your use of dynamic memory. In
most cases, arrays of data structures are a more efficient means of storing
data in Windows than linked lists, which are popular with C programmers.
Since Windows is built on top of the segmented architecture of the Intel-86
family of processors, the following discussion is organized in terms of the
segments that are present in the Windows global heap.
Default Data Segment
Windows uses two types of executable files: application programs and
dynamic-link libraries (DLLs). Applications are the active "clients" that
directly interact with users. DLLs are the passive "servers" that provide
code, data, and device support to applications. Both are referred to as
modules.
In Windows, every module can have a private data segment, which is sometimes
referred to as a default data segment. The C compiler, the linker, and the
Windows multitasking switcher together ensure that every module has access
to its correct data segment. From an architectural point of view, this means
that the processor's data segment (DS) register is set up every time a
module boundary is crossed. From a programming point of view, module
boundaries can only
be crossed by calling exported functions. Exported functions are listed in
the EXPORTS section of a module definition file or defined with the _exports
pragma.
Because of the manner in which Windows maintains the DS register for
different modules, you must use either the small or medium compiler model.
These memory models, after all, are built for a single data segment. Other
compiler models such as compact, large, and huge can be used, but they
impose certain restrictions on programs. One reason to use these models is
that they support multiple data segments. However, Windows allows only one
instance of a program to run if it has multiple data segments. Furthermore,
in real mode multiple data segments must be declared FIXED in the program's
DEF file. Unfortunately, this causes problems using the local heap, since a
fixed heap cannot grow beyond its initial size. This is why most Windows
programmers have concluded that these compiler models aren't worth the
trouble.
In Figure 2, HeapWalker is shown displaying the segments belonging to the
Windows Calculator. The highlighted segment is CALC's default data segment.
In many respects, a program's default data segment is like any other segment
in the global heap: it is allocated with a call to GlobalAlloc and has a
maximum size of 64Kb.
In other ways, a module's default data segment is different from other
segments. For one, it is automatically locked whenever a program receives a
message. Unlike most data segments, a program's default data segment is
automatically locked, so you don't have to lock it explicitly.
Another way in which the default data segment differs from other segments is
that it is accessible with near data pointers. That's because the DS
register points to the default data segment. When a Windows program calls a
DLL routine (such as TextOut), the processor's DS register is set up to
point to the library's default data segment. The same thing happens when
Windows calls a program's WinMain, or when it calls a WinProc. Handshaking
ensures that the DS register is assigned so that it references the module's
default data segment.
A typical default data segment consists of a header, a static data area, a
stack, a local heap, and an optional atom table (see Figure 3).
The header is a 16-byte data area containing pointers that Windows uses to
manage a default data segment. A Windows program must leave this area alone
since it is automatically allocated at compile/link time and managed by
Windows at run time.
The header contains five pointers. Perhaps the most important is pLocalHeap,
which points to the beginning of the local heap in the default data segment.
The local heap management routines use this pointer to find the heap. A
Windows program should not use it directly to manipulate the heap but
instead should call the Windows library routines.
Three of the pointers reference the stack: pStackBot, pStackMin, and
pStackTop. When running the debug version of Windows, these pointers are
used to check for stack overflow. It is a good idea to test your programs in
this special version to detect stack overflow and other error conditions.
The fifth pointer, pAtomTable, points to a local atom table if the program
has created one. An atom table stores variable length strings in a common
hash table. An atom is identified by a 2-byte handle, which allows variable
length strings to be referenced using a fixed-length 2-byte value. The atom
table is itself part of the default data segment's local heap.
The header does not contain any pointers to the static data area. The
compiler defines the static data area and generates code that correctly
accesses it.
The Static Data Area
The static data area contains the static variables, which C programmers
sometimes refer to as global variables. The static variables are those
declared outside a function boundary, and all variables declared with the
static keyword. In addition, all literal strings are stored as static data
objects.
In the following code fragment, four objects are allocated in the static
data area:
char *pchFile;
long lLength;
long FAR PASCAL WndProc (HWND hwnd, WORD wMsg,
WORD wParam, LONG lParam)
{
static int iCount;
PAINTSTRUCT ps;
switch (wMsg)
{
case WM_PAINT:
BeginPaint (hwnd, &ps);
TextOut (ps.hdc, 10, 10, "Windows", 7);
EndPaint (hwnd, &ps);
The two variables defined outside the procedure, pchFile and lLength, are
allocated in the static data area, as you would expect. So is iCount, which
uses the static keyword. This keyword makes iCount visible only within this
routine. But as a static object, it has a lifetime as long as the program
itself and therefore it resides in the static data area.
The fourth object that is allocated in the static data area is the string
"Windows". Every literal string gets its own data area even if two strings
are the same. If a string is going to be used in several places, it is a
good idea to define it once as an array and then reference the array by
name. Even better, use a string table to minimize the impact of literal
strings on the size of the static data area. A string table is a resource
that keeps strings on disk until they are needed. When needed, a string is
read from disk into its own discardable data segment. This way, when your
program is finished using them, string resources can be purged from system
memory.
The Stack
The stack is a dynamic data area that is managed by high-level languages
like C. The stack is so important that 80x86 processors have a set of
registers dedicated to its support and maintenance: the SS (stack segment)
register, the BP (base pointer) register, and the SP (stack pointer)
register.
When the call machine instruction is executed, a return address is
automatically pushed onto the stack by the CPU. When the return (ret)
instruction is executed, the return address is popped from the stack to
determine the instruction to which control is to be passed.
The C compiler and the CPU store three things on the stack: automatic or
"local" variables, arguments to called functions, and return addresses. The
STACKSIZE statement in a program's DEF file sets the size of a stack, with a
minimum stack of 5Kb allocated by the Windows loader.
Automatic variables are allocated on entry into a function and freed upon
exit. All variables declared inside the boundaries of a function without the
static keyword are automatic variables. In the code fragment shown earlier,
the PAINTSTRUCT variable ps is an automatic variable. If a program uses a
lot of automatic variables, the STACKSIZE may need to be increased to
reflect this.
Figure 4 shows a function being called in C, the corresponding assembly
language instructions that are generated, and the arrangement of the stack
after a function has been called and the stack set up. Each push instruction
copies two bytes to the stack. In this case, the called function, y, takes
three integer parameters, so three push instructions are generated to put
these parameters in place. The call instruction places a return address on
the stack, then passes control to the called function.
Inside the called function, the compiler creates code to adjust the BP
register to establish the stack frame. The base pointer then serves as the
anchor point from which parameters can be referenced as positive offsets
from the base pointer. For example, this assembly language instruction
places the third parameter into AX.
mov ax, [bp+04]
If there are local variables, the compiler creates code to adjust the SP
register to reserve space on the stack for them. This is done by the
following assembly language instruction, which is found in Figure 4:
sub sp,6
Local variables are accessed as negative offsets from the base pointer. For
example, this instruction copies the third local variable in the example
into the AX register.
mov ax, [bp-06]
Though the workings of the stack are somewhat esoteric and complex, the C
compiler usually insulates you from needing to understand every detail of
its operation. Hopefully this brief explanation has clarified the role of
the stack, and therefore the rationale behind the size that you specify in
the STACKSIZE statement.
The Local Heap
The local heap provides a private area in the default data segment from
which memory can be dynamically allocated. Every program's default data
segment has a local heap, which is automatically set up by the program
loader. A local heap is set up by calling the LocalInit routine. Allocating
and using memory in a local heap involves making calls to the local heap
management routines (see Figure 5).
Windows local heap management routines support three types of memory
objects: fixed, moveable, and discardable. These are the same types that can
be allocated on the global heap. Windows local heap routines are much more
sophisticated than the C malloc routine, which allocates only fixed objects.
To support moveable and discardable objects, the local heap manager uses a
handle-based memory allocation scheme. In other words, when a call is made
to the local heap allocation routine LocalAlloc, it returns a memory handle,
not a pointer. A memory handle is an identifier. By hiding the location of
the memory object, the local heap manager can move or discard objects when
necessary to satisfy allocation requests.
To access a local memory object, you lock the object by calling LocalLock.
This routine does two things: it increments the lock count of an object and
it returns a pointer to the object. You can keep an object locked for as
long as you need to access the object. However, since locking prevents the
local heap from being reorganized, it's often a good idea to keep a lock on
for a very short time, perhaps only for the duration of a single message.
Remove a lock by calling LocalUnlock.
To free a memory object that has been allocated on the local heap, you must
first unlock it, and then call LocalFree. The following code fragment
demonstrates allocating a memory object and copying a string into the
object.
HANDLE hMem;
PSTR pstr;
/* Allocate a 15-byte moveable object. */
hMem = LocalAlloc (LMEM_MOVEABLE, 15);
/* Lock the object, getting a pointer. */
pstr = LocalLock (hMem);
if (!pstr)
return (ERROR);
lstrcpy (pstr, "Hello World");
/* Unlock the object. */
LocalUnlock (hMem);
As you can see, error checking is important when you allocate memory. You
have no guarantee that the system will be able to satisfy your allocation
request. And if you write to the NULL pointer returned by LocalLock when it
fails, you overwrite the bytes at the bottom of the data segment. Remember,
the segment header is located at the base of your default data segment.
Overwriting it could be disastrous.
Local Atom Table
A program can create an atom table in its default data segment with a call
to InitAtomTable. This routine creates an atom table in the local heap. An
atom table efficiently stores variable-length strings. Once stored, a 2-byte
atom is returned, which is in some ways analogous to a handle. When a
duplicate string is added to an atom table, the same atom value is returned,
minimizing the duplication of variable-length strings.
In addition to the local atom table, Windows provides a global atom table.
DDE uses the global atom table to pass the names of data topics between
programs.
Dynamically Allocated Segments
Dynamically allocated segments are the most flexible type of read/write
memory for a program. Up to the limit of available system memory, a program
can have as many dynamically allocated segments as it wants, and each
allocated segment can be as large as 64Kb. In fact, you can allocate
segments that are larger than 64Kb, although that is beyond the scope of
this article.
Windows 3.0 has a systemwide limit of 8192 segments in real mode and in 386
enhanced mode. In standard mode, the limit is 4096 segments. The standard
mode limitation reflects the fact that two entries in the system handle
table, also known as the Local Descriptor Table (LDT), are required for each
segment. One entry is for the allocated segment and the other is for a
16-byte header that is attached to every allocated segment. Because real
mode and 386 enhanced mode do not require this extra handle table entry,
they are able to support twice the number of segments as standard mode.
In a future version of Windows, the limit to standard mode segments should
eventually be raised to 8192. This limit will change from a systemwide limit
to a per-task limit for both standard mode and 386 enhanced mode. Windows
will then have one LDT per task instead of the current implementation of one
LDT for the entire system in protected mode.
Programs allocate and manage dynamic segments using Windows global heap
management routines (see Figure 6). Where applicable, routines in Figure 6
are paired as a "top slice" and a "bottom slice" in a construction I call
the Windows sandwich.
My Windows sandwich has three parts: two outside pieces of bread that hold
the third part, the filling (see Figure 7). The first piece of bread
represents the code that borrows a system resource. The second piece of
bread represents the code that relinquishes the resource. The filling
represents code with which a program uses the resource. The idea is that the
filling is always used inside the sandwich, never by itself. The most common
type of sandwich is probably the following, a standard response to a
WM_PAINT message:
case WM_PAINT:
{
PAINTSTRUCT ps;
BeginPaint (hwnd, &ps); // top slice
TextOut (ps.hdc, x, y, "Hi", 2); // filling
EndPaint (hwnd, &ps); // bottom slice
.
.
.
Segment allocation mirrors local heap allocation in that both use a
handle-based memory management scheme. A call to GlobalAlloc returns a
handle, which identifies the memory but does not reveal its location.
Segments can be allocated as fixed, moveable, or discardable. To determine
the attributes of a specific segment, you can run HeapWalker and look for
objects that are identified as type Task. Using Figure 8 as a guide, the
three types of memory attributes can be easily identified. Note that a
discardable segment is also a moveable segment.
To access a global memory object, a call must be made to GlobalLock. Like
its local heap counterpart, LocalLock, GlobalLock increments a memory
object's lock count and returns a pointer to the object. Again, it is a
good idea to keep a lock only as long as an object is being used, which in
most cases means for the duration of a message. Unlocking an object involves
making a call to GlobalUnlock, which decrements the lock count on an object.
The following code fragment allocates a global memory object and copies a
string into the allocated memory.
HANDLE hMem;
LPSTR lpstr;
/* Allocate a 15-byte moveable object. */
hMem = GlobalAlloc (GMEM_MOVEABLE, 15);
/* Lock the object, getting a pointer. */
lpstr = GlobalLock (hMem);
if (!lpstr)
return (ERROR);
lstrcpy (lpstr, "Hello World");
/* Unlock the object. */
GlobalUnlock (hMem);
Error checking is just as important when using global heap objects. There is
no guarantee that Windows will be able to satisfy all of your requests for
memory, so you should plan accordingly. The above code fragment checks the
return value of GlobalLock; many Windows programmers also check for a valid
(nonzero) return value from GlobalAlloc.
For a program to run properly in all operating modes, it's a good idea to
keep global memory objects only for the duration of a single message.
However, if a program is to run solely in protected mode, it can take a
shortcut that is unthinkable in real mode. It can lock global memory objects
once, upon allocation, and keep them locked for as long as the object needs
to be in memory.
This can be fatal in real mode because global memory objects are locked in
the physical address space and quickly create memory sandbars. In protected
mode, however, such objects are not locked in the physical address space.
These objects can be moved unbeknownst to the application program.
Resources
A resource is a read-only data object that has been merged into a module's
executable (DLL, DRV, FON, or EXE) file by the resource compiler. When the
data is needed, it can be read into a discardable segment. When the memory
manager needs to use that memory for other purposes, it can discard or purge
the segment containing the resource.
Locating a resource with HeapWalker is easy, since resources are labeled
clearly. HeapWalker knows if a particular resource is a menu template,
dialog box template, or whatever. HeapWalker can even show the bitmap
associated with a particular resource (see Figure 9). Windows has built-in
support for accelerator tables, bitmaps, cursors, dialog box templates,
fonts, icons, menu templates, and string tables. These resources are used to
support several Windows user-interface objects: menus and dialog boxes, to
name two. In addition, several GDI objects are stored as resources: fonts
and bitmaps, for example.
Each resource resides in a separate segment. A program with one menu
template, three dialog box templates, and two cursors has six segments'
worth of resources. Each resource is put in its own segment so that each can
be loaded and discarded individually.
If you are writing a Windows program that has a fairly large block of
read-only data, you should consider putting the data into a resource. If
your data does not fit easily
into one of the predefined resource types, it's simple to create a custom
resource. I will demonstrate this in the CUSTRES program.
GDI Data Segment
Windows programs can call GDI routines that cause objects to be allocated in
GDI's default data segment. Whenever a call is made to a GDI routine that
contains the word Create (such as CreateDC, CreatePen, CreateFontIndirect),
you know that the routine allocates memory in GDI's local heap (see Figure
10). Fonts and bitmaps also cause memory to be allocated from the global
heap.
In general, if a program creates an object, it should make sure that it
deletes the object. In all versions of Windows, GDI expects every program to
clean up after itself. If a program forgets to delete an object, the
allocated memory is lost to the system. GDI was designed this way to allow
programs and instances of programs to share GDI drawing objects. For
example, the first instance of a program could create the GDI drawing
objects to be used by all instances. When subsequent instances start up,
they access the existing drawing objects either by sending messages or
calling the GetInstanceData routine, which copies the value of static data
objects from one instance's data segment to another instance's data segment.
Unfortunately, this design has resulted in a problem. If a program does not
free a GDI object when it terminates, the memory is lost forever. For this
reason, in a future version of Windows, Microsoft should consider changing
GDI so that, upon termination of a program, all GDI objects created by the
program are automatically destroyed. Until that time, you should ensure that
your program explicitly deletes all GDI objects that it has created (and
that it has not passed to other programs on the Clipboard).
USER Data Segment
The Windows USER module supports Windows user-interface objects, such as
windows, menus, dialog boxes, cursors, carets, and accelerator tables.
Unlike GDI objects, USER objects are not designed to be shared between
programs. For the most part, when a program terminates, USER frees the
memory that has been allocated for the user interface objects. Nevertheless,
you should be aware of the ways that a Windows program can cause memory to
be allocated in USER's local heap, because it is a limited resource that is
shared by all applications.
Quite a few user interface objects are stored in their own segments. In
fact, this is true for all user interface objects that are created as
resources. Others are allocated in USER's local heap, as shown in Figure 11.
While these objects are small, there are a few "gotchas" to avoid.
If you create several different menus and attach some of them to a window
using SetMenu, you have to be careful when your program terminates. Menus
that are connected to a window are automatically freed. Menus that are not
connected to a window, however, must be explicitly freed by your program
when it terminates.
A second "gotcha" occurs when you register a window class. As you may
recall, class registration involves filling in the values of a structure of
type WNDCLASS and passing a pointer to the RegisterClass routine. Make sure
that you fill in all elements of the WNDCLASS structure. If you don't fill
in the values of two fields, cbWndExtra and cbClassExtra, you may be in for
a surprise. These values define the amount of extra bytes to be allocated in
USER's data segment: cbWndExtra defines the extra bytes to be allocated for
each window, and cbClassExtra defines the extra bytes to be allocated for
the class. If you forget to initialize these fields, the USER module
allocates extra bytes using whatever values it finds in the data structure.
Of course, you may wish to use the often-overlooked window or class extra
bytes. They may be accessed via the functions found in Figure 12. They can
be used to connect a window efficiently to its data. For example, two window
extra bytes might be allocated to hold a memory handle for the data to be
displayed in a window. Or two class extra bytes could be allocated for GDI
drawing objects shared by the windows in a class.
Window extra bytes can be very useful when creating custom dialog box
controls, or for creating MDI windows. In general, if you are creating a
window class that will support multiple windows in a single application,
window extra bytes provide an easy way to connect a window's data to the
window itself.
Subsegment Allocation
As already discussed, there are two dynamic memory allocation packages in
Windows: local heap allocation and global memory allocation. By default,
every Windows program has a local heap. The heap is created by a routine
called InitApp, which is undocumented but is part of the standard start-up
sequence of every program. One advantage of the local heap is that the
overhead for objects is low (4 to 6 bytes), and with a granularity of 4
bytes, waste is kept to a minimum. The only problem with the local heap is
that it is too small for many uses. Depending on the size of your stack and
the static data, the room remaining for the largest default local heap might
be 30Kb--50Kb.
This problem can be solved by using the global heap. On 386 systems, this
implies taking advantage of disk swap space in addition to physical RAM.
With the global heap, however, the overhead per object is high. Also, at a
minimum of 32 bytes per segment, the granularity of segments is too high to
be used for very small objects. Only large objects or arrays of small
objects are suitable for storage in objects allocated from the global heap.
To get the benefits of both local and global heap management, it's possible
to create a local heap in a dynamically allocated global segment. You can
allocate small objects from this heap, all managed by the local heap
manager, that share the segment efficiently with other objects.
To do this, keep in mind that the first 16 bytes of a segment are reserved
for the use of the local heap manager. At offset 06H, it stores a pointer to
the local heap. This allows the local heap to sit at the end of an
application's default data segment, after its static data and stack.
A second concern involves local heap initialization, which is accomplished
by calling LocalInit. This code fragment allocates a segment and initializes
a local heap in it.
HANDLE hMem;
int pStart, pEnd;
LPSTR lp;
WORD wSeg;
hMem = GlobalAlloc (GMEM_MOVEABLE, 4096L);
if (!hMem)
goto ErrorOut;
lp = GlobalLock (hMem);
wSeg = HIWORD (lp);
pStart = 16;
pEnd = (int)GlobalSize (hMem)-1;
LocalInit (wSeg, pStart, pEnd);
GlobalUnlock(hMem);
GlobalUnlock(hMem);
Notice the two calls to GlobalUnlock. The first counteracts the call to
GlobalLock; the second is needed because LocalInit leaves a segment locked.
Without the second call, the data segment would still be locked. In
protected mode, this doesn't present a problem, but segments that are
unnecessarily locked can create memory sandbars in real mode.
As always, GlobalAlloc's return value should be checked to determine whether
the requested memory is available. Even though you asked for a 4096-byte
segment, because different operating modes align on different segment
boundaries, call GlobalSize to make sure you know the exact size of the
segment. To make room for the header, pStart is set to 16. Set pEnd to the
offset of the last byte in the segment, which is the segment size minus one.
Another way to do this is to set pStart to zero, and set pEnd to the actual
size of the local heap.
pEnd = (int)GlobalSize(hMem)-16;
LocalInit(wSeg, 0, pEnd);
You subtract 16 from the size of the segment to set aside space for the
segment's header.
Accessing the local heap requires some programming in assembly language
because the segment selector of the heap must be placed in DS. Any of the
local heap management routines may then be called to operate on the local
heap.
When the DS register is pointing at a heap segment, don't try referencing
any static variables. You won't be able to access them, but you will
overwrite some of the heap segment instead.
If you are using Microsoft C Version 6.0, you can use the _asm pragma to
embed assembly language in your C code. The following saves DS on the stack,
sets up the DS register to point to the heap segment, allocates memory from
the heap, and restores DS to point to the default data segment.
LPSTR lp;
HANDLE hmem;
WORD wHeapDS; /* Must be a stack variable! */
lp = GlobalLock (hmem); /* Where local heap lives */
wHeapDS = HIWORD (lp);
_asm{
push DS
mov AX, wHeapDS
mov DS, AX
}
hmem = LocalAlloc (LMEM_MOVEABLE, 16);
_asm{
pop DS
}
GlobalUnlock (hmem);
Using a local heap in a dynamically allocated segment requires calls to two
routines, one for the segment and one for the local heap object. To obtain a
pointer to the allocated memory, calls to GlobalLock and LocalLock are
required. And to prevent fragmentation in the global heap or the local heap,
you'll probably want to unlock at both levels.
There are other methods, of course. A program can make all local heap
objects fixed, removing the need to perform the second lock. To be most
effective, it makes sense to build a small subroutine library to manage the
two-level allocation scheme. This might be as simple as creating your own
32-bit handles, using half for the local handle and half for the global
handle. This is the approach used in the sample program, SUBSEG (see Figure
13). Another alternative is for a subroutine package to issue its own
private 16-bit handles that reference a table of segments and local memory
objects.
SUBSEG
The SUBSEG program demonstrates subsegment allocation in a dynamically
allocated segment. I borrow the term subsegment allocation from OS/2, since
it describes this procedure better than the term local allocation. This
program contains a set of subsegment allocation routines that mirror the
Windows standard memory allocation routines. A routine called SubAlloc takes
the same parameters as LocalAlloc. Four other routines provide the basic
allocation services. Another function, SubInitialize, allocates and
initializes the dynamically allocated segment.
SUBSEG displays information about the allocated data objects (see Figure
14). To convince you that it works as advertised, it reads this information
from the object itself. As you can see, the actual size of objects is a
little larger than requested, reflecting the 4-byte granularity of the local
heap manager.
Unlike the handles generated by the local and global heap managers, the
handles issued by the memory management routines in SUBMEM.C are 32-bit. The
HIWORD contains a global memory handle, and the LOWORD contains a local
memory handle. You may want to devise your own scheme for identifying memory
objects, but for many purposes this is fast and simple enough.
If you've examined the code, you may have noticed that the segment allocated
by SUBSEG is never freed. Well, do as I say, not as I do. In other words,
please be sure to free any memory you allocate, unlock any memory you lock,
and in general undo whatever needs undoing to free any resource you use.
Custom Resources
Custom resources, as I said earlier, let you exploit the built-in memory
management features of resources with a minimum of effort. The best custom
resources are data objects that won't change. The sample resource I'll
demonstrate contains a table for determining sine and cosine values. This
look-up table supplies an integer sine value, which is simply a sine value
multiplied by 10,000. Look-up tables are commonly used because they are
often faster than on-the-fly calculations. Also, because 80386 and earlier
Intel processors do not have built-in floating point support, you'll get
faster performance if you limit your calculations to integer arithmetic. (By
the way, this fact influenced Microsoft enough to build Windows without
using any floating point arithmetic.)
CUSTRES contains two routines that calculate sine and cosine values for an
angle in measured degrees. With two functions and 360 degrees, there are 720
different values required for the look-up table. By taking advantage of the
symmetry of sines and cosines and doing a little folding and rotating, I
produce the same results with a single table of 91 sine values.
I obtained the table by writing a C program that calculates sine values and
writes them as ASCII text to a data file. Why ASCII text? I'm going to show
you a trick that lets you build complex binary data objects from ASCII text
files. The only tools required are a macro assembler, the linker, and a
special converter called EXE2BIN.EXE that comes with DOS. Figure 15 contains
the program files that create the custom resource.
The data file created by this program is an assembly language file
containing data definitions but no machine code. Instead, I use the macro
assembler to convert the data definitions into a binary format. The assembly
language file that SINE.EXE creates is SINEDATA.ASM (see Figure 16).
After the data file SINEDATA.ASM has been run through the macro assembler
and the linker, you have a "ready-to-run" EXE file that contains no code.
Next, EXE2BIN is used to isolate the data into a pure binary object; this
program is ordinarily used to create COM files from EXE files. A COM file is
simply a memory image that can be loaded and run as is. Since that's exactly
what you want--a pure, binary image--EXE2BIN does the trick to create the
sine table resource.
To test the sine and cosine functions, CUSTRES connects 360 points to draw a
circle with a radius of 100 pixels (see Figure 17). While this is slower and
rougher than you would expect from a call to GDI's Ellipse routine, it does
show that the generated sine and cosine values at least look right in the
range 0 to 360 degrees.
CUSTRES (see Figure 18) does all its work during the WM_CREATE, WM_PAINT,
and WM_DESTROY messages. All of the sine and cosine information is contained
in two routines, intSin and intCos. The second function actually cheats;
since a cosine is always 90 degrees out of phase with a sine, the intCos
function subtracts 90 degrees from the actual angle and calls the intSin
function.
Using a custom resource requires the FindResource, LoadResource, and
LockResource routines. The first two are called in response to the WM_CREATE
message. The result is a memory handle stored in hresSinData. FindResource
searches for the reference to a resource in the module database, which is
simply an abbreviated memory image of the module's file header. FindResource
takes three parameters:
FindResource (hInstance, lpName, lpType)
The first, hInstance, is an instance handle. The second, lpName, is a long
pointer to a character string with the resource name. The third, lpType, is
a long pointer to a character string with the resource type.
Even though lpName and lpType are pointers to character strings, this is not
the most efficient way to identify a resource, since a string comparison is
more "expensive" than an integer comparison. Because of this, I use a macro,
MAKEINTRESOURCE, which lets me define integers and use them in place of a
character string. Following are the two integers defined in CUSTRES:
#define TABLE 100 /* Custom resource type. */
#define SINE 100 /* ID of sine table. */
These integers are used in the call to FindResource, as follows:
hRes = FindResource (hInst,
MAKEINTRESOURCE(SIN), /* Name. */
MAKEINTRESOURCE(TABLE)); /* Type. */
The MAKEINTRESOURCE macro creates a pseudo-pointer, with 0 for a segment
identifier and the integer value for the offset value. It casts this value
as an LPSTR. When the FindResource routine sees this value, it does not
treat it as a pointer (this would be a fatal error). Instead it uses the
2-byte integer value to find the resource definition, using the following
line in the resource file.
SIN TABLE sinedata.bin DISCARDABLE
This line causes the data in the resource file, SINEDATA.BIN, to be copied
entirely into CUSTRES.EXE at compile/link time. This means that CUSTRES is a
standalone program and doesn't need the original resource data file to be
present at run time.
Once FindResource has provided a resource identifier, a call to LoadResource
provides a global memory handle for the resource itself. LoadResource, the
next routine called, is defined as follows:
LoadResource (hInstance, hresInfo)
Its first parameter, hInstance, is the instance handle; the second
parameter, hresInfo, is the handle returned by the FindResource routine.
In spite of its name, LoadResource does not load a resource. It allocates a
global memory object with a size of 0. No memory is set aside; only a global
memory handle is assigned. CUSTRES stores this value in hresSinData.
The routine that causes a resource to be loaded into memory is LockResource.
CUSTRES calls this routine only when it needs to access the sine table data.
By postponing the loading of such a memory object, CUSTRES helps minimize
the demands it makes on system memory. LockResource itself performs several
tasks: it loads the resource into memory, locks it in place, and returns a
pointer to the data. LockResource is defined as follows.
LPSTR LockResource (hResData)
hResData is the handle returned by the LoadResource function. LockResource
returns a long pointer to a string. CUSTRES casts this return value to a
long pointer to integers.
int FAR * fpSin;
fpSin = (int FAR *)LockResource (hresSinData);
if (fpSin == NULL)
return (0);
Casting prevents the compiler from complaining about a type-mismatch error.
Notice that a check is made on the return value from LockResource, in case
something (like insufficient memory) prevented the resource from being
loaded.
The LockResource routine should always be used with UnlockResource (remember
the sandwich?). This construction was discussed earlier as a way to organize
the use of a shared resource, in this case memory. LockResource loads a
resource and ties it down in memory. UnlockResource unties the resource to
allow it to move, or to be discarded. In CUSTRES, the intSin function uses
these two routines to bracket its use of the sine data, creating a Windows
sandwich that ensures that the object is locked when you need it, and
unlocked when not. UnlockResource is defined as follows. hResData is the
handle returned by the LoadResource function.
BOOL UnlockResource (hResData)
The final routine involved with handling custom resources is FreeResource,
which frees the memory associated with a custom resource. Again, hResData is
the handle returned by the LoadResource function.
FreeResource (hResData)
CUSTRES calls FreeResource in response to the WM_DESTROY message to
deallocate the sine resource. This program doesn't actually need to call
FreeResource, since the resource will be freed when CUSTRES terminates, but
good programmers clean up after themselves.
This program draws using the default MM_TEXT mapping mode. The circle in
Figure 17 is perfectly round only if the program is displayed on a VGA
monitor with a 1:1 aspect ratio. CUSTRES moves the origin of the logical
coordinate system to the middle of the window with the following code:
GetClientRect (hwnd, &r);
SetViewportOrg (ps.hdc, r.right/2, r.bottom/2);
Conclusion
As a Windows programmer, you have many options for allocating and working
with memory. Knowing how to exploit the different ways of packaging data in
Windows should help you write programs that take better advantage of what
the system has to offer.
1 For ease of reading, "Windows" refers to the Microsoft Windows graphical
environment. "Windows" refers to this Microsoft product and is not intended
to refer to such products generally.
Figure 5. Local Heap Management Routines
■ LocalAlloc
Allocates memory from a local heap.
■ LocalCompact
Reorganizes a local heap.
■ LocalDiscard
Discards an unlocked, discardable object.
■ LocalFlags
Provides information about a specific memory object.
■ LocalFree
Frees a local memory object.
■ LocalHandle
Provides the handle of a local memory object
associated with a given memory address.
■ LocalInit
Initializes a local heap.
■ LocalLock
Increments the lock count on a local memory
object and returns its address.
■ LocalReAlloc
Changes the size of a local memory object.
■ LocalShrink
Reorganizes a local heap and reduces the size of
the heap (if possible) to the initial, starting size.
If this routine is successful, it reduces the size of the data segment
that contains the heap, so that
the memory can be reclaimed by the global heap.
■ LocalSize
Returns the current size of a local memory object.
■ LocalUnlock
Decrements the lock count on a local memory object.
Figure 10. Memory Used in GDI's Local Heap
Object Size
■ Bitmap 28--32 bytes
■ Brush 32 bytes
■ Device context 100 bytes per device for fixed overhead +
200 bytes per DC allocated
■ Font 40--44 bytes
■ Palette 28 bytes
■ Pen 28 bytes
■ Region 28--104 bytes
Figure 11. Memory Used in USER's Local Heap
Object Size
■ Menu 20 bytes per menu +20 bytes per menu item
■ Window class 40--50 bytes
■ Window 6070 bytes
Figure 12. Memory Used in USER's Local Heap
Window Extra Bytes Routines Description
■ SetWindowWord Copies two bytes into window extra bytes
■ SetWindowLong Copies four bytes into window extra bytes
■ GetWindowWord Retrieves two bytes from window extra bytes
■ GetWindowLong Retrieves four bytes from window extra bytes
Class Extra Bytes Routine Description
■ SetClassWord Copies two bytes into class extra bytes
■ SetClassLong Copies four bytes into class extra bytes
■ GetClassWord Retrieves two bytes from class extra bytes
■ GetClassLong Retrieves four bytes from class extra bytes
Figure 15. SINE
SINE.MAK
sine.obj: sine.c
cl -c sine.c
sine.exe: sine.obj
link sine;
sinedata.asm: sine.exe
sine
sinedata.bin: sinedata.asm
masm sinedata.asm, sinedata.obj;
link sinedata, sinedata.exe;
exe2bin sinedata.exe
SINE.C
/*-------------------------------------------------------------*\
| SINE.C - Creates an .ASM data file containing sine values |
| from 0 to 90 degrees. This file is suitable |
| for creating a custom Windows resource. |
\*-------------------------------------------------------------*/
#include "stdio.h"
#include "math.h"
char achFileHeader[] =
";\n"
"; Sine/Cosine Data Table\n"
";\n"
";\n"
"; Table of Sine values from 0 to 90 degrees\n"
";\n"
"SINDATA segment public\n";
char achFileFooter[] =
"\n"
"SINDATA ends\n"
"END\n";
main()
{
double dbPI = 3.1415926536;
double dbRad;
FILE * fp;
int iAngle;
int iSin;
if (!(fp = fopen("sinedata.asm", "w")))
{
printf("Can't create sinedata.asm.\n");
exit(1);
}
fprintf (fp, achFileHeader);
fprintf (fp, "DW ");
for (iAngle = 0; iAngle <= 90; iAngle++)
{
dbRad = (((double)iAngle) * dbPI) / 180.0;
iSin = sin(dbRad) * 10000.0 + 0.5;
fprintf(fp, " %5d", iSin);
if (iAngle % 8 == 7)
fprintf (fp, "\nDW ");
else if (iAngle != 90)
fprintf (fp, ",");
}
fprintf(fp, achFileFooter);
fclose(fp);
}
Figure 16. SINEDATA.ASM, Generated by SINE.EXE
;
; Sine/Cosine Data Table
;
;
; Table of Sine values from 0 to 90 degrees
;
SINDATA segment public
DW 0, 175, 349, 523, 698, 872, 1045, 1219
DW 1392, 1564, 1736, 1908, 2079, 2250, 2419, 2588
DW 2756, 2924, 3090, 3256, 3420, 3584, 3746, 3907
DW 4067, 4226, 4384, 4540, 4695, 4848, 5000, 5150
DW 5299, 5446, 5592, 5736, 5878, 6018, 6157, 6293
DW 6428, 6561, 6691, 6820, 6947, 7071, 7193, 7314
DW 7431, 7547, 7660, 7771, 7880, 7986, 8090, 8192
DW 8290, 8387, 8480, 8572, 8660, 8746, 8829, 8910
DW 8988, 9063, 9135, 9205, 9272, 9336, 9397, 9455
DW 9511, 9563, 9613, 9659, 9703, 9744, 9781, 9816
DW 9848, 9877, 9903, 9925, 9945, 9962, 9976, 9986
DW 9994, 9998, 10000
SINDATA ends
END
Learning Windows Part IV: Integrating Controls and Dialog Boxes
Marc Adler
Dialog boxes and the control windows within them are an integral part of the
Microsoft Windows graphical environment. The topic is broad enough to devote
two articles, both the previous article in this "Learning Windows" series as
well as this one, entirely to it. First, I conclude the discussion of
controls with a look at combo boxes, scroll bars, and user-defined controls,
then I place the controls into their proper setting: a dialog box. Finally,
adding dialog boxes to the sample stock quoting application gives it most of
its functionality.
Combo Boxes
The combo box, which was introduced in Windows1 Version 3.0, combines a
single-line edit control and a list box into one control window. It can be
used to enter a value in an edit field or to choose one string from a
predefined list of text strings. A combo box can replace a series of radio
buttons in a dialog box, taking up less space. In a word processing
application, you might want to enter the type size, in points, of the font
you will be using. A combo box could display a list of existing point sizes
and permit you to type in another number. A radio button group could be used
for this task, but if there were many point sizes, the radio button group
would probably take too much room in the dialog box. In addition, the number
of choices in a combo box can vary throughout the lifetime of an
application, but a radio button group generally has a fixed number of
choices. To add another choice to a combo box control, all the developer has
to do is append a text string to a combo box's list box; adding another
option to a radio group probably means creating a new radio button and
rearranging the entire group.
The first element of a combo box is a single-line edit control. A button
control to the right of the edit field is the second element, and the third
element is a list box control just below the edit control. As you scroll
through the list box, the current selection is displayed in the edit
control. A list box control in a combo box has the standard Windows 3.0 list
box features, including possible owner-draw items.
Windows 3.0 supports three styles of combo boxes. The simple combo box
style, which is the least used, has the CBS_SIMPLE style flag. In a simple
combo box, the list box is always visible. This kind of combo box has no
advantage over defining a separate edit control and list box control, except
that you don't have to code the list-box-to-edit tracking logic.
The other two combo box styles are drop-down (see Figure 1) and drop-down
list, defined by the CBS_DROPDOWN and the CBS_DROPDOWNLIST styles. The only
difference between them is that the edit control is disabled in the
drop-down list combo box, so users cannot enter their own values in the edit
field. This is useful if you want to make users choose from a list of
predefined values only.
The nice thing about the drop-down and drop-down list styles is that the
list box is hidden until you pull it down. You can pull it down either by
clicking on the control's button or by pressing the Alt-Down key
combination. You can use the Up, Down, Page Up and Page Down keys while the
focus is on the control to scroll through the list box items.
The messages and notification codes that are processed by the combo box
message interface are similar to those used by the standard list box and
edit controls. The only difference is that the prefixes CB_ or CBN_ are
used instead of the EM_, EN_, LB_, and
LBN_ prefixes. The single unique message, CB_SHOWDROPDOWN, is used to
display or hide the list box portion of a drop-down or drop-down list combo
box. Just before the list box portion is made visible, the CBN_DROPDOWN
notification code is sent to the parent of the combo box. This gives the
programmer a chance to modify the contents of the list box before it is
shown to the user.
Scroll Bars
Many Windows applications use a window as a "viewport" into some sort of
large data set. A list box window is a viewport into a series of strings, a
word processing document window is a viewport into a portion of the data
file, and so on.
Scroll bars are the primary means for the user to inform the application
that he or she wants to move the viewport to a new position in the data set.
A scroll bar control can be either vertical or horizontal. It has two
primary attributes: the range of values that the length of the scroll bar
represents, and the current position in the range. The current position is
indicated with a square icon called a thumb.
Scroll bars are usually attached to a window when it is created. To attach a
vertical scroll bar to a window, you simply give the window the WS_VSCROLL
style during creation. Similarly, the WS_HSCROLL style attaches a horizontal
scroll bar to the bottom of the window.
Scroll bars can also be used as standalone control windows. A good example
can be seen in the Edit Colors dialog box of Windows Paintbrush (see Figure
2).
A standalone scroll bar control is created in the same way as any other kind
of control window--using CreateWindow or defining the control as part of a
dialog box in a resource file. Vertical control scroll bars have the
SBS_VERT style, and horizontal scroll bars have the SBS_HORZ style.
Windows API functions allow you to query and set the current position and
the range of the scroll bar. The five scroll bar functions are as follows:
int GetScrollPos(hWnd, nBar)
void GetScrollRange(hWnd, nBar, lpMin, lpMax)
int SetScrollPos(hWnd, nBar, iPos, bRedraw)
void SetScrollRange(hWnd, nBar, nMin, mMax, bRedraw)
void ShowScroll bar(hWnd, nBar, bShow)
The first parameter, hWnd, can be either the handle of a scroll bar (when
dealing with a control scroll bar), or the handle of the window that
contains the scroll bar. The second parameter, nBar, details which scroll
bar you want. If nBar is SB_CTL, the hWnd parameter is the handle of a
control scroll bar. If nBar is SB_VERT, hWnd is the handle of a window
containing the vertical scroll bar; if nBar is SB_HORZ, hWnd is the handle
of a window with a horizontal scroll bar.
Scroll bars, unlike other control windows, do not generate WM_COMMAND
messages when the parent window needs to be notified of some event. Instead,
they generate WM_VSCROLL and WM_HSCROLL messages. WM_VSCROLL messages are
sent by vertical scroll bars, and WM_HSCROLL messages are sent by horizontal
scroll bars. The notification codes for these messages are the same, and are
passed in wParam (see Figure 3). If the message was generated by a control
scroll bar, the handle of the scroll bar is passed in the HIWORD of the
lParam (otherwise, the HIWORD of lParam is 0). The LOWORD of the lParam
contains the current thumb position for two of these notification messages.
When the top arrow of a vertical scroll bar or the left arrow of a
horizontal scroll bar is clicked, the SB_LINEUP notification code is sent to
the parent window. Clicking on the down arrow or the right arrow generates
an SB_LINEDOWN code. Clicking in the area between the top or left side of
the scroll bar and the thumb causes the SB_PAGEUP code to be sent. And if
you click between
the bottom or right side of the scroll bar and the thumb, the SB_PAGEDOWN
message is generated. As you drag the thumb, the scroll bar generates a
series of SB_THUMBTRACK notification codes with the current position of the
thumb in the LOWORD of lParam. The SB_THUMBTRACK notification codes allow
the developer to vary the contents of the window continuously as the thumb
is dragged. However, it is not always possible to update the contents of a
window dynamically as the user is scrolling (this is often the case if the
window's contents are too complex). When dragging stops, the scroll bar
generates the SB_THUMBPOSITION message, which contains the final position of
the thumb in the LOWORD of lParam. If dynamic scrolling of the window is not
feasible, the window can be updated once at this point to reflect the new
position of the viewport.
When these notification codes are sent to the WinProc of the scroll bar's
parent, the WinProc must update the scroll bar thumb to reflect the new
position. The WinProc must scroll the data in the window as well. Windows
automatically handles scrolling for list boxes, combo boxes, and edit
controls that have scroll bars.
Sample Scroll Bar Use
Assume that you have written a simple Windows application that constantly
generates a tone (like a program that aids guitarists in tuning their
instruments). You attach a vertical scroll bar to the main window of the
program; the range of the scroll bar represents eight octaves (there are 12
notes in an octave, for a total of 96 notes), and the current position of
the thumb represents the note that is currently sounded. (You have a
function called SoundTone that accepts a note value and generates the
corresponding tone.)
First, create a window with a scroll bar and set the range of the scroll bar
from 1 to 96. Also, the initial tone is set to an A-440Hz, the 22nd note in
your range (see Figure 4).
To get to the next or previous note in the range, the user must click on the
down or up arrow of the scroll bar. To increase or decrease the octave, set
up the scroll bar so that the user can click between the thumb and the down
arrow, or the thumb and the up arrow. Dragging the thumb produces a sliding
glissando sound (see Figure 5). The WM_VSCROLL messages that are sent to the
main window must be processed and the tone adjusted accordingly. You must
also reposition the thumb so that it ends up at the correct location in the
scroll bar.
Dialog Boxes
Dialog boxes can be thought of as the glue that binds groups of control
windows together. A dialog box is simply a pop-up window containing one or
more child windows. These child windows can be in one of the previously
discussed control classes, or they can be custom developed. Two
characteristics distinguish a dialog box from an ordinary pop-up window.
First, a dialog box can be defined in an external ASCII resource file.
Second, a dialog box manager in Windows handles the interaction between the
user and the dialog box.
The dialog box manager processes the keystrokes that occur in a dialog box
and performs the actions indicated by the keystroke. If the user presses
Tab, the dialog box manager must search forward, starting after the control
that currently has the focus, for the next control on which the focus can be
set (that is, a control with the WS_TABSTOP style). If the user presses Esc,
the dialog box manager generates a WM_COMMAND message with the IDCANCEL
value and sends it to the user-defined dialog box procedure.
Several steps are involved in using a dialog box in your Windows
application. First, you must define a dialog box in the resource file (RC),
compile it using the resource compiler, and attach it to the EXE file of
your application. Second, your application must define a dialog box
procedure to handle the messages sent to the dialog box. Third, your
application must load the dialog box from the resource file and call the
dialog box manager to display it so it can interact with the user.
There are two types of dialog boxes, modal and modeless. Most applications
use modal dialog boxes to gather information from the user. A modal dialog
box does not permit you to interact with or switch to any other window in
your application until you are finished using the dialog box. In fact, when
you invoke a modal dialog box, the dialog box manager goes into its own
message loop and dispatches only those messages meant for the dialog box or
one of its controls. Usually a user gets out of a dialog box by clicking on
an OK or Cancel push button or pressing Esc or Enter.
Modeless dialog boxes allow you to switch the focus from them to the rest of
the application. You switch the focus by clicking the mouse on another
window. The Windows PIF Editor serves as a good example. In the PIF Editor,
you can activate the pull-down menu while the focus is set to one of the
modeless dialog box controls. Since the methods for loading and using
modeless and modal dialog boxes are quite different, both will be discussed.
Defining a Dialog Box in a Resource File
Defining a dialog box and its controls by hand in a resource file is
something that an experienced Windows programmer avoids, because it's much
simpler and easier to use the Windows Dialog Editor (see Figure 6) supplied
in the Microsoft Windows Software Development Kit (SDK). Dialog boxes and
control windows can have many different options and styles. The Dialog
Editor allows you to draw and edit a dialog box interactively and generate
the necessary resource file definition.
Figure 7 shows the syntax for a sample dialog box definition. The first line
specifies the name, load options, memory options, and coordinates of the
dialog box. The default load and memory options are LOADONCALL
and MOVEABLE. A LOADONCALL resource is not loaded into memory until the
application needs it. This is one of the primary advantages of resource
files.
The coordinates specified in dialog box definitions work in a special way.
Because Windows applications should be as device-independent as possible,
your dialog boxes should look the same no matter what sort of video display
adapter is used. If a dialog box is meant to encompass the entire display,
it should do so whether the video adapter is at 640 x 350 or 1024 x 768
resolution. To ensure this, the dialog box coordinate system is based upon
the dialog base unit. This is a unit of measurement that is calculated based
on the current system font. In a dialog box definition, the x coordinate and
the width are measured in 1/8 of a dialog base unit. The y coordinate and
the height are 1/4 of a dialog base unit. To determine the exact number of
pixels in the horizontal and vertical dialog base units, use the new Windows
3.0 function GetDialogBaseUnits.
After you define the name, load options, memory options, and coordinates of
the dialog box, you can define other dialog box options. The STYLE statement
can be used to give the dialog box certain style attributes, the same kind
that are used in the CreateWindow function. Four styles are specific to
dialog boxes. These styles are DS_LOCALEDIT, DS_MODALFRAME,
DS_NOIDLEMSG, and DS_SYSMODAL. The DS_SYSMODAL style creates a system
modal dialog box, in which all windows in the system are disabled until you
exit the dialog box. This style of dialog box could be used, for example, to
signal a fatal error that would affect the performance of the Windows
session.
You can give the dialog box a title with the CAPTION statement. Other
options are the MENU statement, the CLASS statement, and the FONT statement.
The FONT statement, new to Windows 3.0, allows you to specify the type style
and point size of the text inside the dialog box.
Once this header information has been defined in the resource definition,
all you need to do is define a list of the control windows between the BEGIN
and END statements. However, the Windows SDK Dialog Editor does all of this
work for you, allowing you to assemble controls graphically, while it builds
the actual RC file of definitions.
The definition of the Add Tick dialog box (see Figure 18) for the stock
charting application is shown in Figure 7. This definition was generated by
the Dialog Editor. You can usually tell if a dialog box definition was
generated by the Dialog Editor because it generates the longer CONTROL-style
statements to define controls as opposed to the handwritten format.
Tab Stops and Groups
I previously stated that the dialog box manager handles keystrokes within a
dialog box, and that when Tab is pressed, the dialog box manager moves the
input focus to the next control. How does it know which control to move the
input focus to?
The WS_TABSTOP style bit must be set for every control window to which you
can move by pressing Tab or BackTab. This is especially important for
programmer-defined controls, since the dialog box manager has no other way
of knowing if a custom control is used for output only or can interact with
the user. (If a static control has the WS_TABSTOP style set, the dialog box
manager must search for the next nonstatic control after the static control
in order to set the input focus to a valid control.)
The dialog box manager also supports something called a control group. This
is a group of controls organized so that you can move among them by pressing
the arrow keys instead of Tab and BackTab. The most common example is a
group box that contains radio buttons. If the first radio button in the
group box has the WS_GROUP style and the first control defined outside of
the group also has the WS_GROUP style, you will be able to move among the
radio buttons by using the arrow keys. If you want to move to a control that
resides outside of the radio group, you must use Tab. In general, to create
a control group, give the first control in the group the WS_GROUP style and
give the first control defined outside of the group the WS_GROUP style too.
If you want to find the window handle of the next item in a control group,
you can use the GetNextDlgGroupItem function. This function is useful to set
up custom keyboard handling in a dialog box. For example, if you have a
Windows application that offers customized keyboard mapping, the user might
define a key combination to be the same as the down arrow key (for instance,
Ctrl-X in WordStar). When the user presses Ctrl-X in a dialog box, you may
want to set the input focus to the next member in a control group. You can
use the GetNextDlgGroupItem function to get the window handle of the next
control in the group and set the focus to it. A similar function,
GetNextDlgTabItem, is used for controls with the WS_TABSTOP style.
Loading a Dialog Box
Now that the dialog box has been defined, compiled, and attached to the EXE
file, you want to load it into your application. Four functions allow you to
load or create a modal dialog box and have it processed by the dialog manager
of the functions, DialogBox and DialogBoxParam, load the dialog box from the
RES file that is attached to the EXE. The other functions, DialogBoxIndirect
and DialogBoxIndirectParam, create dialog boxes from a description stored in
a template in your application. Since this method is uncommon, I will not
discuss it.
The function used to load and invoke a dialog box is DialogBox.
FARPROC lpfn;
lpfn = MakeProcInstance((FARPROC) OpenDlg,
hThisInstance);
DialogBox(hThisInstance, "Open", hWnd, lpfn);
FreeProcInstance(lpfn);
The MakeProcInstance call takes the address of the programmer-defined dialog
box procedure and creates a small piece of code known as a thunk. A thunk
first binds the data specified by hThisInstance to the function pointed to
by OpenDlg, and then branches to that function. MakeProcInstance returns a
far address to the thunk. When finished with the dialog box invocation, free
the thunk by calling FreeProcInstance. (Thunks are a complex mechanism and
are described in greater detail in Programming Windows, Microsoft Press,
1990)
The DialogBox function takes four arguments; the handle of the application's
instance (remember, this is a unique program identifier so that Windows can
distinguish multiple copies of the same application that are running
simultaneously); the name of the dialog box to load; the handle of the owner
window; and the pointer to the instance thunk. The value returned by
DialogBox is the value that the programmer-defined dialog box procedure
returns. (Actually, the return value is the value that is passed as the
second argument to the EndDialog function.)
Dialog Box Procedure
Every dialog box must have a programmer-defined dialog box procedure
associated with it. The dialog box procedure is similar to a standard
WinProc, but dialog box procedures and WinProcs differ slightly. First, a
dialog box procedure returns a Boolean value, TRUE or FALSE.
Unlike a standard WinProc, your dialog box procedure must return TRUE if
it processes a message and FALSE if it does not.
When you invoke a modal dialog box, the dialog box manager goes into its own
internal message loop. If it receives a message intended for the dialog box,
it passes the message to your dialog box procedure first. If the dialog box
procedure returns FALSE, the dialog box manager passes the message to its
own internal default dialog box procedure. If your dialog box procedure
returns TRUE, the dialog box manager does nothing further with the message
and reads the next message. Windows 3.0 allows the advanced programmer to
access the default dialog box procedure, DefDlgProc. Microsoft distributes
the source code to DefDlgProc with the Windows 3.0 SDK.
The dialog box procedure should be defined as follows:
BOOL FAR PASCAL MyDialogProc(hDlg, message,
wParam, lParam)
HWND hDlg;
WORD message;
WORD wParam;
DWORD lParam;
This header looks exactly like a WinProc, except for the BOOL return value.
And, just like a WinProc, the dialog box procedure must be exported in your
application's DEF file.
EXPORTS
.
.
.
MYDialogProc
If a dialog box does not seem to be behaving correctly, check that you have
exported the dialog box function. This is a common error among novice
Windows programmers (and experienced ones too).
Most simple dialog box procedures process only the WM_INITDIALOG and
WM_COMMAND messages. WM_INITDIALOG, similar to the WM_CREATE message, is
sent by the dialog box manager just before the dialog box is displayed for
the first time. This message gives the dialog box procedure the opportunity
to initialize the contents of the controls in the dialog box. The dialog box
procedure, for example, could fill in the contents of edit fields with
default values, fill list boxes with strings, and check certain radio
buttons and check boxes. If you do not want the dialog box manager to set
the initial focus to the first control with the WS_TABSTOP style
automatically, you can set the focus to another control at this point. If
you do change the focus, the dialog box procedure must return FALSE after
processing the WM_INITDIALOG message. If it returns TRUE, the dialog box
manager will set the focus automatically. (This message is the exception to
the rule stated earlier about the Boolean values returned by your dialog box
procedure.)
The lParam of the WM_INITDIALOG message was not used in previous versions of
Windows. Windows 3.0 allows you to pass the dialog box manager a long value
that the dialog box manager will in turn pass to your dialog box procedure
as the lParam value of the WM_INITDIALOG message. To do this, use the
DialogBoxParam function. This function is identical to DialogBox, except
that a fifth argument is added, the long value to pass in the WM_INITDIALOG
message.
Other than processing the WM_INITDIALOG message, your dialog box procedure
mainly handles the WM_COMMAND messages generated when the user manipulates a
control window. These WM_COMMAND messages usually come in two varieties: the
ones generated when you click on a button control, and the ones sent with
notification codes in the HIWORD of lParam.
When the user clicks the OK or Cancel button, it usually means the user
wants to dismiss the dialog box. A WM_COMMAND message is sent to the dialog
box procedure with wParam set to the control identifier of the push
button. The dialog box manager is informed that the user is through with the
dialog box by a call to EndDialog.
EndDialog takes two arguments, the handle of the dialog box, and a
word-length value. This value will be used as the return value from the call
to DialogBox.
switch (message)
{
case WM_COMMAND :
switch (wParam)
{
case IDOK :
EndDialog(hDlg, TRUE);
break;
case IDCANCEL :
EndDialog(hDlg, FALSE);
break;
If the user pressed OK, EndDialog is called to tell the dialog box manager
that the dialog box should be dismissed. The value TRUE will be returned by
the dialog box manager to the application. In the following statement the
value TRUE would be returned and assigned to the variable rc.
rc = DialogBox(hInstance, "AddTick", hWndMain,
lpfnDialogProc);
Similarly, if the user clicked on the Cancel push button, the value False
would be returned to the application.
EndDialog does not dismiss the dialog box immediately. It sets a bit in a
private data structure that the dialog box manager allocates for each dialog
box. (It also copies the value of the second argument into this structure.)
When your dialog box procedure returns control to the dialog box manager,
the manager examines this bit, and if it is set, the manager breaks out of
its message loop.
Message Boxes
Windows programs commonly inform the user of a potential or existing error
condition. For instance, if the user attempts to exit a word processing
application without first saving the document, the application should bring
up a dialog box that contains a warning message and a choice of actions. The
dialog box should have a message such as "Save the document before exiting?"
as well as three push buttons labeled Yes, No, and Cancel.
It would be extremely tedious if the Windows programmer had to design dialog
boxes for each possible error or warning condition. Fortunately, you can
call a single function to display some text in a dialog box and attach one
or more predefined buttons to it. This kind of dialog box is called a
message box; not surprisingly, the function that creates and displays one is
called MessageBox.
The nice thing about using message boxes is that Windows itself contains the
dialog box procedure for all message boxes and handles all the WM_COMMAND
messages. You don't have to create your own dialog box procedure, export it,
and load the dialog box. All you have to do is process the return code from
MessageBox.
The syntax of the MessageBox function is shown below.
int MessageBox(HWND hWndParent, LPSTR lpText,
LPSTR lpCaption, WORD wType)
The first parameter is the handle of the owner window. The second parameter
is the static text that will appear inside the message box. If it is too
long to fit on one line, Windows wraps the text to the next line and
increases the height of the message box accordingly. The third parameter is
an optional title that will appear in the caption of the message box. The
fourth parameter consists of bit flags that tell Windows what kinds of
buttons and icons you want put into the message box. If you want a push
button other than the predefined push buttons, you must define your own
dialog box to be used as a message box. Windows gives you Yes, No, Cancel,
Abort, Ignore, and Retry push buttons. It also allows you to place one of
several predefined system icons on the left side of the message box (see
Figure 8).
The value returned from MessageBox is the control identifier of the push
button the user selected. (If the user presses OK, the IDOK value is
returned; if the user presses No, the IDNO value is returned, and so on.)
The complete list of identifiers of these buttons can be found in WINDOWS.H
(see Figure 9).
A typical use of a message box is:
rc=MessageBox(hWndMain,
"Do you want to exit the application?",
"Exit",MB_YESNO | MB_ICONQUESTION);
if (rc == IDYES)
PostQuitMessage(0);
Modeless Dialog Boxes Revisited
Modeless dialog boxes can be thought of as a hybrid of normal overlapped
windows and modal dialog boxes. To create a modeless dialog box, use the
CreateDialog function. The syntax of CreateDialog is exactly the same as the
DialogBox function. However, when you create a modeless dialog box, the
CreateDialog function returns immediately with the handle of the dialog box;
Windows does not invoke the internal dialog box manager. A typical call to
create a modeless dialog box is shown below.
hDlgModeless=CreateDialog(hInstance,"MyModelessDlg",
hWndMain, lpfnProc);
Since a modeless dialog box is simply a standard overlapped window with
child windows, messages get sent to it as they do to any other window in
your application. All you need is your application's normal message loop:
while (GetMessage(&msg, 0, 0, 0))
{
TranslateMessage(&msg);
DispatchMessage(&msg);
}
But there is something missing. Suppose the input focus is set to one of the
controls in the modeless dialog box and you press Tab. Nothing happens,
because there is no dialog box manager that processes the keystrokes and
gives a special significance to the Tab key. Of course, you could put code
in your application to handle Tab, but it would be a lot easier to "call the
dialog box manager" temporarily.
Windows allows you to do this. The function
IsDialogMessage(hDlg, &msg)
tests to see if the message contained in the passed MSG structure is meant
for the dialog box whose handle is passed in the first argument. If so,
IsDialogMessage performs all of the necessary keystroke translations and
dispatches the message itself to the dialog box. It takes care of all of the
keystroke interpretations. It then returns TRUE if the message has been
processed, and FALSE if not. The standard message loop modified to include
the use of IsDialogMessage looks like this:
while (GetMessage(&msg, 0, 0, 0))
{
if (!hDlgModeless ||
!IsDialogMessage(hDlgModeless, &msg))
{
TranslateMessage(&msg);
DispatchMessage(&msg);
}
}
After obtaining the message, the message is passed to IsDialogMessage. If it
returns TRUE, you know it processed the message fully and there is no reason
to call TranslateMessage and DispatchMessage.
The only other concern with modeless dialog boxes is that since the dialog
manager is not used with modeless dialog boxes, the EndDialog function
cannot be used to terminate dialog box processing and destroy the dialog
box. Instead, you must use the standard DestroyWindow call. You also have to
invalidate the dialog box handle so that the IsDialogMessage function won't
be called in your message loop.
DestroyWindow(hDlg);
hDlgModeless = 0;
Sample Application
At the end of the previous article in this series, the stock charting
application had a complete pull-down menu system and MDI capabilities.
Every time you chose the File/New menu item, a new MDI child window was
created. Items on the Window pull-down menu automatically tiled and cascaded
the child windows, and arranged minimized windows nicely. But that was all
the application did; there was no code actually relating to stocks.
Now that you understand dialog boxes, an entry form will be implemented that
prompts the user for information about the stocks. You'll need to decide
what kind of information should be associated with each stock, and create a
data structure describing a stock object. The stock information will also
need to be stored for easy access. Since this application is not designed to
be a commercial application (and since this application is designed to teach
Windows programming, not data structures), ease of implementation and
comprehension will be favored over performance. When applicable, I will
discuss alternatives you can use to obtain more palatable results.
The modules to build the version of STOCK.EXE discussed here are shown in
Figure 10. A real-time stock charting system is not being created, so the
application will not continuously monitor a stock's performance as it is
traded throughout the business day. The only concern is the stock's closing
price and perhaps its volume. Other types of analyses might involve the
average price during the day or the high and low prices, but that is left as
an exercise to the reader.
You may also want to keep track of each date. Here's a structure to hold the
date:
typedef struct tagDate
{
BYTE chMonth;
BYTE chDay;
BYTE chYear;
} DATE;
Six bytes are used for each date; however, I could probably get away with
two bytes if I stored the date as an offset from January 1, 1900 and put it
in an unsigned int. Some analysis programs do not store the date along with
every tick; they are just concerned with a series of price and volume data.
To avoid the overhead of floating point arithmetic, you can store the price
as a four-byte value using the following formula.
price = (dollar amount) X (fraction denominator) + (fractional amount)
For instance, a price of 16 7/8 would be stored as (16 * 8) + 7 = 135.
Now you can define a structure that holds the daily trade information:
typedef DWORD PRICE;
typedef DWORD VOLUME;
typedef struct tagTick
{
PRICE price;
VOLUME dwVolume;
DATE date;
} TICK, FAR *LPTICK;
You also need a data structure that describes the properties of a stock
graph (see Figure 11). A future article will delve further into the logic of
creating graphs. This data structure will be discussed more fully at that
time.
All this information must be transferable to and from disk, or the program
would be pretty useless. Besides the ticker information, you want to save
the name of the stock (an up-to-five letter symbol), a description of the
stock, the graphing parameters, and the number of ticks. You also want to
store a signature at the beginning of the file for data integrity to ensure
that the file read from disk really is one of the stock files (see Figure
12).
Finally, a structure is needed to keep track of all of the stock information
while the application is running. In addition to all of the information that
resides in the stock file, you need to store the filename of the stock file,
the handle of the MDI child window in which the stock information is
displayed, a handle to the memory buffer that holds the tick data, and some
state flags that record the current status of the stock. All the stocks are
linked together in a single-linked list; a handle to the next stock
information data structure is kept in each structure (see Figure 13).
Each stock is stored in its own separate file whose name is comprised of the
stock symbol and an STO extension. For a commercial application, you would
most likely use a Windows-compatible commercial database access library.
Using Dialog Boxes
To demonstrate dialog boxes, examine a dialog box in the stock-charting
application. When the user chooses the File Open menu item, a dialog box
should be displayed that lists the files with the STO extension found in the
current directory. The user should be allowed to change directories and disk
drives to search for other STO files. Almost all Windows applications have a
File Open dialog box. Unfortunately, Windows provides no standard File Open
dialog box, so each vendor implements his or her own in a slightly different
way. The stock-charting application makes use of some sample code that comes
with the Windows SDK for a typical File Open dialog box.
You must first define the dialog box in the resource file. The resource
definition is shown in Figure 14.
The dialog box's name is Open; it has a caption and a system menu (see
Figure 15). An edit field lets the user input a filename or specification
other than the default *.STO. The edit field also tracks the current
selection in the file list box, which contains the names of all the files in
the current directory matching the file specification. It also contains a
list of subdirectories in the current directory, and a list of all disk
drives on the system. Finally, there is an OK push button that the user can
click to open the file, and a CANCEL button that aborts the Open operation.
The OK push button is the default, so if the user presses Enter, a
WM_COMMAND message with IDOK in wParam is sent to the user-defined dialog
box procedure.
The WinProc of the main window in the application processes the WM_COMMAND
message, and when wParam is set to ID_OPEN, invokes the File Open dialog
box.
case ID_OPEN :
lpfn = MakeProcInstance((FARPROC) OpenDlg,
hThisInstance);
DialogBox(hThisInstance, "Open", hWnd, lpfn);
FreeProcInstance(lpfn);
break;
You want the dialog box procedure to return a handle to the opened stock
file rather than a TRUE/FALSE value or a control window identifier. A file
handle returned by the Windows OpenFile function is a WORD value, so it can
be returned to the application by passing it as the second argument to
EndDialog.
Here is the heading of the dialog box procedure:
BOOL FAR PASCAL OpenDlg(hDlg, message,
wParam, lParam)
HWND hDlg;
unsigned message;
WORD wParam;
LONG lParam;
{
WORD index;
PSTR pTptr;
HANDLE hFile;
switch (message)
{
.
.
.
The only two messages that you need to process in the dialog box procedure
are the WM_INITDIALOG and the WM_COMMAND messages. First, look at the small
function called UpdateListBox below. This function forms a complete pathname
with a file specification at the end by concatenating two string variables,
one holding the current path and the other holding the current filespec. It
then calls a Windows function called DlgDirList.
DlgDirList takes five arguments: a handle to a dialog
box, the identifier of a file list box within that dialog box, the
identifier of a static text field also within that dialog box, a string
containing a path and file specification, and a value representing file
attributes. It then searches the path for all files matching the file
specification and the desired attributes. The name of each matching file is
placed into the list box, and the full pathname is placed into the static
text field. DlgDirList also places the subdirectory and drive names in the
list box automatically.
Finally, UpdateListBox sets the contents of the dialog box's edit field to
the default file specification by calling SetDlgItemText. This function
takes the identifier of a control window in a dialog box, determines the
window handle of the control, and sends a WM_SETTEXT message to it.
void UpdateListBox(hDlg)
HWND hDlg;
{
strcpy(str, DefPath);
strcat(str, DefSpec);
DlgDirList(hDlg, str, IDC_LISTBOX, IDC_PATH, 0x4010);
SetDlgItemText(hDlg, IDC_EDIT, DefSpec);
}
Next the WM_INITDIALOG message is processed. A call to UpdateListBox fills
the list box with the names of the STO files and sets the contents of the
file specification edit control to *.STO. The EM_SETSEL message is then sent
to the edit control to highlight the entire field. If you want to send a
message to any control within a dialog box, and you only know the identifier
of the control, you can use SendDlgItemMessage. This is equivalent to the
following statement.
SendMessage(GetDlgItem(hDlg, ID_CONTROL), msg,
wParam, lParam);
You also set the initial focus to the edit control.
case WM_INITDIALOG: /* message: initialize */
UpdateListBox(hDlg);
SendDlgItemMessage(hDlg,/* dialog handle */
IDC_EDIT, /* where to send message */
EM_SETSEL, /* select characters */
NULL, /* additional information */
MAKELONG(0, 0x7fff)); /* entire contents */
SetFocus(GetDlgItem(hDlg, IDC_EDIT));
return (FALSE);
/* Indicates the focus is set to a control */
Now it's time to process the WM_COMMAND message. You want the edit control
to track the currently selected item in the list box. When the current
selection of a list box changes, the list box notifies the dialog box by
sending a WM_COMMAND message with the identifier of the list box in wParam
and the LBN_SELCHANGE notification code in the HIWORD of lParam (see Figure
16). An easy way to get the text of the currently selected item is to call
the built-in Windows function DlgDirSelect.
Why aren't LB_GETCURSEL and LB_GETTEXT messages sent to the list box? Other
than the fact that I have to write more code to do this, the DlgDirSelect
function removes the square brackets surrounding the name of a directory and
the square brackets and hyphens surrounding the names of disk drives in the
list box. It returns zero if the selected item was a filename and nonzero if
it was a directory name. In this case, if the currently selected item is a
filename, you fill the edit control with the name of that file, and if it is
a directory name, you refresh the list box.
Double-clicking a list box selection has the same result as single-clicking
a list box item and then clicking OK. When the LBN_DLBCLK notification code
for the list box is received, the program simply jumps to the code that is
responsible for opening the file (see Figure 17).
Finally, you must process the two push buttons in the dialog box. Remember,
when a button is pressed, a WM_COMMAND message is sent to the parent window
with wParam set to the control identifier of the button. If the user clicks
Cancel, you simply end the dialog box processing and return NULL for the
value of the file handle. If the user clicks OK, you have a lot more work to
do. First, examine the contents of the edit field and see if the filename
contains a wildcard. If it does, assume that the user wants to search for a
new filespec. You get the file specification, separate it into a pathname
and a filespec, and refill the file directory list box with files matching
the new spec. If the edit field is empty, put up a message box warning the
user and return control to the dialog box manager. If neither is the case,
you have a valid filename in the edit field: open the file and return the
file handle.
There you have it--your first dialog box. Once you code a few dialog boxes,
you will find yourself churning out dialog box code by rote.
Adding a Tick
After a day of trading activity, you need to input the closing price and the
total trading volume for each stock in the database. To do this, select the
Add Tick item from the Edit menu. The Add Tick dialog box is displayed
forthe current stock (see Figure 18); you can fill in the various fields to
append a single tick to the list of tickers for that stock. The Add Tick
dialog has three fields; the trading date, the volume, and the final price
(the final price must be an integer for now). At this intermediate stage of
the application, the date and the volume fields are basically ignored in the
code--only the final price is important. Also, at this time, a tick cannot
be inserted in the middle of the ticker list. This will be remedied in a
future version of the code.
Options Dialog Box
The characteristics of a stock and how its graph is displayed can be
controlled through the Options dialog box (see Figure 19). Actually, the
same dialog box is displayed when you add a new stock to the database and
when you change the properties of an existing stock. The only difference is
that in the latter case, the field that contains the name of the stock is
disabled; this is the only piece of information that cannot be altered in an
existing stock. The following lines of code disable the symbol control if we
are altering the characteristics of an existing stock.
if (lpStockInfo->hTicks != NULL)
.
.
.
EnableWindow(GetDlgItem(hDlg, ID_SYMBOL), FALSE);
As mentioned above, at this stage of the program, some of the fields in this
dialog box are ignored by the code. The minimum and maximum prices define
the range of the y-axis of the stock graph. The scale factor is a number
that all of the numeric data is divided by before the number is plotted on
the graph. If the price range of a stock is from 100 to 300, a ticker price
can be 201 different values (assuming that each price is a whole number).
Instead of having the y-axis of the graph divided into 201 points, you can
have the y-axis represent 20 different points if you divide each price by a
scale factor of 10. The tick interval is the interval between two successive
tick marks on the y-axis. The price denominator field is ignored in this
release. It represents the denominator in the fractional part of the stock
price. (Most stocks are traded in either eighths or sixteenths.) The final
component of the Options dialog box is the owner-draw combo box that
contains the styles for the various pens that draw the horizontal and
vertical grids of the graph.
Trying It Out
The function StockFileRead reads a stock file into the application. You can
test this application using the stock file included with the application.
StockFileRead first allocates space for the stock header and then reads the
header. The number field of the header is examined to ensure that it is a
valid stock file. You allocate memory to hold all of the ticker information
and then read the tickers. Then, call GraphCreateWindow to create an MDI
child window for this stock. The handle of the MDI child is returned and
stored in the stock information structure. Likewise, the memory handle of
the stock information structure is stored in the "extra-bytes" area in the
window by using the SetWindowWord function. This makes it possible to
determine stock information associated with a given window very quickly.
When a stock window is displayed, some text about the stock is also
displayed. A future installment will discuss graphics in Windows. I will
then expand this application to show graphical information about each stock.
This article focused on dialog boxes, which are often the most important
objects in a Windows application. You saw how to define one in a resource
file, load it into an application, and create a user-defined dialog box
procedure to handle the messages. The next article finishes the discussion
of dialog boxes, and discusses some of the graphical capabilities of
Windows.
1 As used herein, "Windows" refers to the Microsoft Windows graphical
environment. Windows refers only to this Microsoft product and is not
intended to refer to such products generally.
Figure 7. Definition of the Add Tick Dialog Box
ADDTICK DIALOG LOADONCALL MOVEABLE DISCARDABLE 112, 31, 106, 86
CAPTION "Add a Tick"
STYLE WS_BORDER | WS_CAPTION | WS_DLGFRAME | WS_POPUP
BEGIN
CONTROL "Date:", -1, "static", SS_LEFT | WS_CHILD, 2, 7, 22, 8
CONTROL "", ID_TICK_DATE, "edit", ES_LEFT | WS_BORDER | WS_TABSTOP |
WS_CHILD, 53, 5, 48, 12
CONTROL "Closing price:", -1, "static", SS_LEFT | WS_CHILD, 2, 26, 55, 11
CONTROL "", ID_TICK_PRICE, "edit", ES_LEFT | WS_BORDER | WS_TABSTOP |
WS_CHILD, 57, 25, 44, 12
CONTROL "Volume:", -1, "static", SS_LEFT | WS_CHILD, 2, 44, 32, 8
CONTROL "", ID_TICK_VOLUME, "edit", ES_LEFT | WS_BORDER | WS_TABSTOP |
WS_CHILD, 38, 43, 63, 12
CONTROL "OK", 1, "button", BS_DEFPUSHBUTTON | WS_TABSTOP | WS_CHILD, 9,
66, 28, 14
CONTROL "Cancel", 2, "button", BS_PUSHBUTTON | WS_TABSTOP | WS_CHILD, 63,
66, 32, 14
END
Figure 11. Graph Data Structure
/*
Data structure describing how we draw the graph
*/
typedef struct tagGraphInfo
{
PRICE dwMinPrice;
PRICE dwMaxPrice;
DWORD dwScaleFactor;
DWORD dwTickInterval;
WORD iDenominator; /* the fractional amount used for this stock */
WORD iGridPen;
} GRAPHINFO, FAR *LPGRAPHINFO;
Figure 12. Tagging a Stock File
#define MAXSTOCKNAME 5
#define MAXDESCRIPTION 32
#define MAXFILENAME 13
typedef struct tagStockFile
{
DWORD dwMagic;
#define MAGIC_COOKIE 66666666L
char szStock[MAXSTOCKNAME];
char szDescription[MAXDESCRIPTION];
GRAPHINFO graphinfo;
WORD nTicks;
/*
TICK aTicks[1];
*/
} STOCKFILE;
Figure 13. Structure to Track Stock Information
typedef struct tagInCoreStockInfo
{
char szFileName[MAXFILENAME]; /* file name where the stock data is
kept */
STOCKFILE StockFile; /* a copy of the stock file header */
HANDLE hTicks;
HWND hWnd; /* window in which stock is shown */
DWORD dwFlags; /* any kind of status bits we need
to keep */
#define STATE_HAS_VGRID 1L
#define STATE_HAS_HGRID 2L
HANDLE hNextStockInfo; /* link to next stock info struct */
} STOCKINFO, FAR *LPSTOCKINFO;
Figure 14. Open Dialog Box Definition
Open DIALOG 10, 10, 148, 112
STYLE DS_MODALFRAME | WS_CAPTION | WS_SYSMENU
CAPTION "Open "
BEGIN
LTEXT "Open File &Name:", IDC_FILENAME, 4, 4, 60, 10
EDITTEXT IDC_EDIT, 4, 16, 100, 12, ES_AUTOHSCROLL
LTEXT "&Files in", IDC_FILES, 4, 40, 32, 10
LISTBOX, IDC_LISTBOX, 4, 52, 70, 56, WS_TABSTOP
LTEXT "", IDC_PATH, 40, 40, 100, 10
DEFPUSHBUTTON "&Open" , IDOK, 87, 60, 50, 14
PUSHBUTTON "Cancel", IDCANCEL, 87, 80, 50, 14
END
Figure 16. Processing the WM_COMMAND Message
case WM_COMMAND:
switch (wParam)
{
case IDC_LISTBOX:
switch (HIWORD(lParam))
{
case LBN_SELCHANGE:
if (!DlgDirSelect(hDlg, str, IDC_LISTBOX))
{
SetDlgItemText(hDlg, IDC_EDIT, str);
SendDlgItemMessage(hDlg,
IDC_EDIT,
EM_SETSEL,
NULL,
MAKELONG(0, 0x7fff));
}
else
{
strcat(str, DefSpec);
DlgDirList(hDlg, str, IDC_LISTBOX, IDC_PATH, 0x4010);
}
break;
case LBN_DBLCLK:
goto openfile;
}
return TRUE;
Figure 17. Opening a File When OK Is Pressed
case IDOK:
openfile:
GetDlgItemText(hDlg, IDC_EDIT, OpenName, 128);
if (strchr(OpenName, '*') || strchr(OpenName, '?'))
{
SeparateFile(hDlg, (LPSTR) str, (LPSTR) DefSpec,
(LPSTR) OpenName);
if (str[0])
strcpy(DefPath, str);
ChangeDefExt(DefExt, DefSpec);
UpdateListBox(hDlg);
return TRUE;
}
if (!OpenName[0])
{
MessageBox(hDlg, "No filename specified.", NULL,
MB_OK | MB_ICONHAND);
return TRUE;
}
AddExt(OpenName, DefExt);
/* The routine to open the file would go here, and the */
/* handle would be returned instead of NULL. */
StockFileRead((LPSTR) OpenName);
EndDialog(hDlg, hFile);
return (TRUE);
case IDCANCEL:
EndDialog(hDlg, NULL);
return (TRUE);
}
break;
}
return FALSE;
}
Questions & Answers - Windows
Q:
I'm curious about what a window handle (hWnd) object really is physically.
Is it a global memory handle? A segment or selector? An array index?
Josh Trupin
Stamford, CT
A:
When you call CreateWindow or CreateWindowEx, you are calling functions in
the Windows USER.EXE dynamic-link library (DLL). These functions perform the
following call:
LocalAlloc(LMEM_FIXED | LMEM_ZEROINIT, 64)
and then a LocalLock, resulting in a NEAR pointer (PSTR) to 64 bytes inside
of USER's data segment (DGROUP). This pointer is returned as a window handle
(HWND) after USER fills out the 64 bytes that it refers to.
To fill out this 64-byte "window object," USER actually employs an internal
structure similar to the following.
typedef struct tagWND // bytes
// from
{ //length end GetWindow...
//------ ----- -------------
WORD Undocumented[22]; // 44 -64
DWORD ExStyle; // 4 -20 GWL_EXSTYLE
DWORD Style; // 4 -16 GWL_STYLE
WORD ID; // 2 -12 GWW_ID
WORD hWndText; // 2 -10 GWW_HWNDTEXT
HWND hWndParent; // 2 -8 GWW_HWNDPARENT
HANDLE hInstance; // 2 -6 GWW_HINSTANCE
FARPROC WndProc; // 4 -4 GWL_WNDPROC
} WND; // 64
typedef WND NEAR *PWND;
The elegance in this design is that when you make USER calls (functions
whose first argument is usually an HWND), hWnd is cast inside of USER as a
PWND so that the above WND structure elements can be addressed directly;
that is, the following refers to the window's parent.
((PWND)hWnd)->hWndParent
Code that refers to the window structures is therefore
very efficient.
Some of the arguments in the CreateWindow or CreateWindowEx call are placed
directly in the structure; others are determined by USER.
((PWND)hWnd)->ExStyle =dwExStyle;
((PWND)hWnd)->WndProc =<WndProc from WNDCLASS of ClassName>;
((PWND)hWnd)->hWndText =<another local pointer to WindowName> ;
((PWND)hWnd)->Style =dwStyle;
((PWND)hWnd)->hWndParent =hWndParent;
((PWND)hWnd)->ID =hMenu; //if child window,=child ID
((PWND)hWnd)->hInstance =hInstance;
If your window class has extra bytes requested (specified by cbWndExtra in
the WNDCLASS structure of the RegisterClass call), then additional bytes are
allocated at the end of the 64-byte WND structure in the LocalAlloc call. In
other words, the LocalAlloc call that USER performs is really as follows.
LocalAlloc(LMEM_FIXED | LMEM_ZEROINIT, 64 +
<cbWndExtra from WNDCLASS of ClassName> )
This allows you to attach (with SetWindowWord and SetWindowLong)
window-specific information to the window in an object-oriented way in your
application.
From all of the above you can see how SetWindowWord, SetWindowLong,
GetWindowWord, and GetWindowLong work. When you make these calls, USER adds
64 bytes to the hWnd pointer and then adds the nIndex.
(PSTR)hWnd + sizeof(WND) + nIndex
The resulting local offset refers to the value you are setting or getting
with SetWindowWord and SetWindowLong and GetWindowWord and GetWindowLong.
This is how application-specific extra window information is referred to
with a base index of 0, and why the GWW_XXX and GWL_XXX indexes have
negative offsets.
There is little to no protection when using window handles, because no
protected-mode selectors are being used. It is very easy to corrupt USER's
DGROUP by using invalid window handles. A bad window handle could cause USER
to corrupt its DGROUP without a protection violation occurring. Also, it is
very easy to see how you could use another application's valid window
handles to modify its window structures.
Finally, you can see that window handles are reused. Since they are just
offsets to structures that are created and destroyed, it is possible that
another CreateWindow or CreateWindowEx call could return the same "handle"
of a previously destroyed window, if the LocalAlloc resulted in the same
physical offset inside USER's DGROUP.
Therefore, a window handle is really an offset into USER's DGROUP at which a
structure exists that defines a window. If you're still curious, you can
look at these structures using HeapWalker. Just perform Object LocalWalk and
Object Show operations on USER DATA and look for 68-byte memory objects.
They're shown by HeapWalker as 68 bytes because of the additional 4 bytes at
the beginning of every local memory object that KERNEL uses to manage local
heaps.
Q:
I've written an application that uses more than 100 child windows. The
windows are created when the application starts, but only some of them are
visible at the same time. I have two problems.
First, I can only run a few instances of my application. When Free System
Resources (as reported in the Program Manager's About box, for example) gets
close to 0% I get failures trying to create new windows. I have tons of
memory, so I don't understand why this is happening.
Second, it seems as if my application is very slow to initialize. I'm in the
dark on this, since I can't find any documentation on what would cause it to
be slow.
Michael J. Paschal
Waterbury, CT
A:
Windows maintains all windows inside the USER.EXE DLL. USER's data segment
(DGROUP), like all C medium-model DGROUPs, is limited to 64Kb in size. All
windows that are created consume space inside this DGROUP, as do menus,
title-bar names, and so on, so you are bumping up against the 64Kb
segment-size limit. The Free System Resources percentage reflects this
constraint. The amount of global memory you have is irrelevant; the DGROUP
can only grow to 64Kb.
If you want to be able to start many instances of your application, you will
have to change your window creation strategy. If you can get by creating
your windows only as needed (Program Manager does this for its icon and
application-name windows), you should operate that way. If you can destroy
windows when they are not displayed, you should do that (although Program
Manager doesn't). Hiding windows does not reduce their USER memory
requirements.
Your ability to do these things depends on your application. If you are
creating all your windows in advance because you need to be positive you
have them before you start, you are stuck with your current situation. If
you can deal with a possible lack of windows further into run time, change
your strategy.
Each window you create requires a minimum of 68 bytes inside USER's 64Kb
maximum DGROUP. In theory you could therefore have a maximum of about 960
windows. But that estimation ignores the amount of static memory required by
USER, any window text, any menus, and so on. I wrote a small program to test
the maximum number of windows I could create. It turned out that the maximum
number of really bare-bones windows I could create was around 700. Assuming
you would more likely have some trimmings (menus, title-bar text), a more
realistic estimate is 350.
Your application is slow to start up because of KERNEL.EXE's local heap
memory manager. Since local heaps start off being relatively small, KERNEL
has to expand them as more local memory is requested; this takes a small
amount of time. What is more time consuming is that LMEM_MOVEABLE objects
inside USER's DGROUP have to be moved higher so that the LMEM_FIXED window
structures can be created low. Your initialization is slow because KERNEL
has to move the entire upper part (where LMEM_MOVEABLE objects are kept) of
your USER DGROUP and adjust all the local handle table entries, doing this
more than 100 times at start-up in your case.
Q:
I am creating a few edit class windows in my application by using
CreateWindow. They are displayed in my main client area as children of my
main window. The problem I am having is that the text that gets put in or
created in these windows ends up being stored in my application's local
heap, and space there has gotten very tight. Is there any way that edit
class windows can be coerced into having their text stored in the global
heap?
B.D. Beykpour
San Francisco, CA
A:
In edit controls in dialog boxes created with calls such as DialogBox and
CreateDialog, edit control text is stored in the global heap by default. To
have this text stored in the local heap, you must specify the DS_LOCALEDIT
style.
For edit class windows outside a dialog box that are created with
CreateWindow, the reverse is true. By default, edit class window text is
stored in the application's local heap. To force it to be stored in the
global heap, use the following trick. When you call CreateWindow, replace
the hInstance argument with a global handle to a small block of zeroed
memory. Specifically, create the global memory object as follows.
auto GLOBALHANDLE aGhEditBuffer;
aGhEditBuffer=GlobalAlloc(GMEM_MOVEABLE | GMEM_ZEROINIT,
256L);
Then call CreateWindow with aGhEditBuffer as the hInstance argument. If you
specify some initial text with the lpWindowName argument, it appears as the
initial text in the edit window. The edit window operates as normal, but
using the global heap for the edit text. The global memory block grows
automatically as the text gets longer. When you destroy the edit window, the
global memory buffer is automatically freed in the same way a local memory
buffer is freed.
Q:
In WINDOWS.H a section labeled OEMRESOURCE appears to refer to the
user-interface bitmaps, but I can't find much documentation on them. What
are all these bitmaps and can I access them?
Alex Polozoff
Austin, TX
A:
Figure 1 identifies these bitmaps and shows which version of Windows they
were developed for. The resolution of each bitmap depends on the display
driver you have installed. In the Windows environment, Versions 1.x and 2.x,
these were monochrome bitmaps; in Windows1 3.0 many of them are full-color
format bitmaps, although only the colors black, white, and gray are actually
used. In some cases (the Close bitmaps, for example) the bitmap really
contains two or more equally-sized bitmaps arranged in rows; these
"sub-bitmaps" would have to be extracted if you wanted to use them.
The following code, which loads OBM_ZOOM, is an example of how to access
these bitmaps:
auto HDC ahDc;
auto HBITMAP ahBm;
auto BITMAP aBm;
ahDc = CreateCompatibleDC(0);
ahBm = LoadBitmap(0, MAKEINTRESOURCE(OBM_ZOOM));
GetObject(ahBm, sizeof(aBm), (LPSTR)&aBm);
/* aBm now has the bmWidth and bmHeight for
BitBlt'ing */
ahBm = SelectObject(ahDc, ahBm);
/* the OBM_ZOOM bitmap can now be BitBlt'ed
here from ahDc using the bmWidth and bmHeight
in aBm */
ahBm = SelectObject(ahDc, ahBm);
DeleteObject(ahBm);
DeleteDC(ahDc);
Q:
I have a child window that has a title bar in my client area. The child
window looks similar to the PageMaker Toolbox window. The title bar is meant
simply to label the window, though; I do not want the user to be able to
move the child window by grabbing the title bar with the mouse. How do I
lock down a child window that has a title bar?
Frank Mena
San Jose, CA
A:
What you want to do is prevent Windows from processing the move system
command for the child. The following code fragment, which would be placed at
the end of the child's WndProc message switch, shows how to do this.
switch (awMsg)
{
.
.
.
case WM_SYSCOMMAND:
if ((awParam & 0xFFF0) == SC_MOVE)
break;
default:
return DefWindowProc(ahWnd, awMsg, awParam,
alParam);
}
return 0L;
As you can see in this code, all system commands except SC_MOVE are
processed by DefWindowProc. By not
sending the WM_SYSCOMMAND/SC_MOVE message to DefWindowProc, you will prevent
the default processing of this message, which is for Windows to move the
child window. This technique can be used to disable any WM_SYSCOMMAND
subcommands.
Reader Feedback
Regarding the fourth question in the September Windows Q&A, MSJ (Vol. 5, No.
5), Dean White of Dallas, Texas, notes that the following
rem >%temp%\dosapp.sem
accomplishes the same end and is better than
echo %0 >%temp%\dosapp.sem
He's right. Not only is no disk sector space wasted with his method, it is
faster. A file entry with a length of zero is all that is created as a
semaphore in the temporary files subdirectory.
1 For ease of reading, "Windows" refers to the Microsoft Windows graphical
environment. "Windows" refers only to this Microsoft product and is not
intended to refer to such products generally.
child window. This technique can be used to disable any WM_SYSCOMMAND
subcommands.