Category : Files from Magazines
Archive   : PJ76.ZIP
Filename : WPMAUX.DOC

WINAUX/PMAUX

William S. Hall
3665 Benton Street, #66
Santa Clara, CA 95051

Introduction


Winaux is a Windows program capable of displaying text sent
to it by another window. PMaux is the corresponding version for
presentation manager. Acting as a simple scrolling window, each
performs many of the operations of an auxiliary terminal. They
are particularly useful for analyzing the behavior of Windows or
PM functions and for print-statement debugging.

We begin by describing Winaux. Please read this section even
if you are planning to use PMaux.


Using Winaux

Winaux is very easy to use. When Winaux runs, it leaves a
copy of its Window handle in win.ini. Another program can then
write to Winaux by sending it a message using the call

SendMessage(hWnd, WM_USER, (WORD)len, (LONG)(LPSTR)str);

where hWnd is the window handle (which can be retrieved from
win.ini), str is a string of characters, and len is its length.
In practice, the operation is made simpler by writing a function
which will carry out the operations of retrieving the handle,
calculating the length, and sending the message. This function
can be placed into an include file and used as needed by the
target program.

Winaux also creates a file called Winaux.log. Using the
Options menu, you can choose to log part or all of the session to
disk. The file is automatically closed when Winaux is exited.
You should rename it if you want to preserve its contents before
the next use of Winaux.

When Winaux exits, it resets the value of the handle in
win.ini to 0. Hence programs which test for a valid window
handle before attempting the SendMessage call will usually not
risk the danger of accessing an invalid window. However, if
Windows is terminated abruptly by a crash, the handle in win.ini
will not be NULL. A program which calls Winaux using this handle
may crash the system if it runs before and makes a call to
Winaux. Under these circumstances, you should edit win.ini and
change the handle entry to 0.

Only one instance of Winaux is allowed.

The very first time Winaux runs, it will choose a default
position and size on the screen and write these parameters to
win.ini. The user can modify these values to place Winaux as
desired. A typical entry in win.ini is as follows:

[Winaux]
x=100
y=275
cx=540
cy=75
hWnd=4589

This window will be positioned at pixel location (100,275) on the
display and will be 540 pixels wide and 75 high. On an EGA, this
will place the window in the lower right corner.

If you are using Winaux to help you debug a Windows program,
then you will find it useful to experiment with the position and
size and then add Winaux to your load or run line in win.ini. As
you go repeatedly through the compile-program, run-Windows,
test-program, exit-Windows cycle, you will appreciate WINAUX more
if you do not have to bother with running and positioning its
window repeatedly.

Winaux creates a text buffer with as many lines as your
maximized display can show when using the system font.
Similarly, the number of characters per line is computed based on
the maximum width of the display and the size of the system font.

Lines are displayed at the bottom of the window and scroll
upward. The bigger the window the more lines will be visible.
Currently, there are no scroll bars, so once a line number
exceeds the maximum number of lines, it is lost.

Winaux converts newlines to a carriage-return line-feed
pair. A menu option allows you to kill this option. However,
lines are wrapped if they exceed the maximum number of horizontal
characters on a line.

At any time, you can clear the sreen with the corresponding
menu item.

To illustrate the program's application, we have included a
simple Windows template called Smltpl in which a sprintf
statement has been added at the top of the message loop. All
message parameters, and a counter, are printed to a buffer which
is sent by the function auxprt to the Winaux window. Auxprt
itself is defined in the include files auxprt.c and auxprt.h.

long FAR PASCAL MainWndProc( hWnd, message, wParam, lParam )
HWND hWnd;
unsigned message;
WORD wParam;
LONG lParam;
{
PAINTSTRUCT ps;

/* print messages to Winaux */
sprintf(auxbuf,"hWnd = %4x message = %4x wParam = %4x lParam = %8lx\n",
hWnd, message, wParam, lParam);
auxprt(auxbuf);

........


Near the top of the program is an include statement

#include "auxprt.c"

Auxprt.c contains the coded needed to communicate with WINAUX and
is placed in the program's main module before WinMain. Auxprt.c
itself has an include statement for auxprt.h, a file containing
a data declaration and a function prototype. This file should
be placed in any other module in which auxprt is to be called.

Auxprt.c and auxprt.h together have the following general form:

char auxbuf[80];
auxprt(char *str)
{
HWND hWnd;
int len = strlen(str);

#if defined(WINAUX)
hWnd = (HWND)GetProfileInt((LPSTR)"Winaux", (LPSTR)"hWnd", 0);
if (IsWindow(hWnd))
SendMessage(hWnd, WM_USER, (WORD)len, (LONG)(LPSTR)str);
#endif

.... /* code for PM */
}

Whenever a message is received, sprintf formats it and hands
it to auxbuf. The function auxbuf reads the Winaux handle,
computes the length of the string, verifies that the handle
received is valid, and sends it to Winaux.

You can watch the messages being displayed by running
Winaux, then Smltpl. The action is especially swift as the mouse
is moved over the Smltpl window. You can also run more than one
instance of the program and see the messages for each.

Although reading the handle from win.ini may seem wasteful,
it is an (almost) solid guarantee that the handle retrieved is
either valid (Winaux is running) or NULL (Winaux has exited).
Also note the use of SendMessage rather than PostMessage. Since
Winaux will be retrieving a long pointer to data, SendMessage
insures that the pointer is valid during the time that the data
is being displayed.


Using PMaux

When PMaux runs, it leaves a copy of its window handle in
os2.ini. However, it is more difficult in PM to get the buffer
from the other program over to PMaux since the data segment of
one program is not accessible to another in protected mode. In
this case it is necessary to create a global, shareable buffer in
the program calling PMaux, fill it, and pass the handle and the
buffer length over to PMaux. The following excerpt from the
include files auxprt.c/auxprt.h describes the method.

char auxbuf[80];
auxprt(char *str)
{
HWND hWnd;
int len = strlen(str);

... /* code for Windows */

#if defined(PMAUX)
char hbuf[40];
SEL sel;
PCH pchBuf;
int i;

/* get the string representation of the handle for pmaux from OS2.INI */
WinQueryProfileString(hAB, "PMaux", "hWnd", "", hbuf, 40);
/* convert to a handle */
hWnd = (HWND)atol(hbuf);
/* create a shared buffer which can be read by another process */
if (DosAllocSeg(len, &sel, SEG_GETTABLE) == 0) {
/* make a long pointer to the buffer */
pchBuf = MAKEP(sel,0);
/* load it up */
for (i = 0; i < len; i++)
*(pchBuf+i) = *(str+i);
/* send it over */
if (WinIsWindow(hAB, hWnd))
WinSendMsg(hWnd, WM_USER, (MPARAM)len, (MPARAM)sel);
/* free the buffer */
DosFreeSeg(sel);
}
else /* error, ring the bell */
WinAlarm(HWND_DESKTOP, WA_WARNING);
#endif

To illustrate its usage, we have included a Presentation
Manager template Spmtpl especially modified to transmit all
messages received in the message loop to PMaux. The technique is
similar to that used in the corresponding Windows program.

Most of the other features of Winaux are applicable to PMaux
except that currently there is no logging capability and the
initial placement and size of the window cannot be modified. The
latter feature was not implemented since in PM, one can run
PMaux, size and place it once, and leave it for the duration of
the OS2 session.


Remarks

If you are trying to use Winaux or PMaux with a dynamic link
library, you can still use the techniques described above for
passing the message. However, methods other than sprintf must be
used to format the string since none of the printf family can be
used when the stack segment does not coincide with the data
segment of your program.

Finally, note that both Spmtpl and Smltpl are very useful
templates which can help you in starting your own Windows or PM
program.