The Art of OS/2 2.1 C Programming Book Review

By Carsten Whimster

The Art of OS/2 2.1 C Programming finally got here. It turned out there was some kind of mix-up but once they realized, it got here double-fast. It is the first of a care-package of three books I was sent by Wiley-QED. I have been anxiously awaiting this one, and I heard of it long before becoming involved with EDM/2. It has a good reputation as a beginner's OS/2 and PM programming book, and also has a reputation of being hard to find. Hopefully this will change with time (the availability, that is).

Errata
I have been very busy this month, what with brain-storming about the layout design of EDM/2. Thanks go to Craig Rodrigues (did I get the spelling right? I don't have my mail here) for suggesting flattening the index a bit. I have also been busy reviewing Larry's The Art of OS/2 2.1 C Programming, trying to set up a universal table of contents for the books I review, which will hopefully debut next month (thanks Gordon), getting a start on a VX-REXX article, and setting up a database of ex- and current authors for EDM/2 in an effort to ensure that the stream of articles coming is more regular. In addition, I've been setting and marking assignments and midterms at UW. Whew.

I have been working a bit on my OS/2 WWW page. Check it out, and mail me your thoughts, corrections, and ideas.

On the other hand, is has been quiet with respect to mail from readers.

Watcom C/C++ 10.0 is on its way! I ordered it Friday June 24, and can hardly wait. Supposedly it is just beautiful, and has a very good IDE. In fact, the quality is supposedly so high that some people have been heard to complain about the low quality of the IBM OS/2 2.1 Toolkit, and hope that Watcom makes their own for the next release of the compiler! I never really felt a need to criticize the Toolkit, so 10.0 must be something! It comes on either 61 diskettes or 1 CD-ROM. Guess which I ordered :) A full installation takes up 172Mb (!), but I will only be installing the OS/2 stuff, as I have deep-sixed both DOS and Windows a long time ago.

I have a small confession to make here. Ever since Larry asked if I was going to review his book (well, their book. Kathleen Panov wrote the largest chunk, followed by Larry, and lastly Arthur Panov), I have been afraid of two things. First, what if I didn't like it? Although we have never met, I feel like I know him well at this point, and so I wouldn't want to offend him. Secondly, if I like it, how do I convince people that I am not just giving it a great review because of our (Internet) connection? I was a little relieved when Larry sent me a letter telling me that if I didn't review it fairly, and criticize it accordingly, then I was fired :) But I was still nervous.

At some point during my review I decided to be a little more critical than normal with this book, since I am in the unique position of knowing that it is in the process of an update, and of knowing that one of the authors is listening. Please don't take this extra criticism to heart, but remember why I am doing this. Anyhow, on to the review...

The Art of OS/2 2.1 C Programming
The Art of OS/2 2.1 C Programming is an OS/2 programming book for beginners. It has a few chapters on fundamental OS/2 programming issues such as threads and IPC, but it is mainly intended as a PM programming book. It comes with a 3.5" diskette, but no installation program. You are expected to use OS/2's unpack to copy the files over. Here are the chapters:
 * 1) Tools
 * 2) Memory Management
 * 3) File I/O and Extended Attributes
 * 4) Multitasking
 * 5) Interprocess Communication
 * 6) Windows and Messages
 * 7) Dialog Boxes
 * 8) Menus
 * 9) List Boxes
 * 10) Buttons
 * 11) Notebook
 * 12) Containers
 * 13) Value Set
 * 14) Spin Buttons
 * 15) Slider
 * 16) Font and File Dialogs
 * 17) Subclassing Windows
 * 18) Drag and Drop
 * 19) Help Manager
 * 20) Presentation Manager Printing
 * Appendix A - References

Chapter one is on C-Set++ and the OS/2 Programmer's Toolkit 2.1, and is a very brief introduction to the usage of the various tools included. I'll have more to say about that in the summary.

Chapters two through five discuss some fundamental OS/2 programming techniques, many of which are crucial to certain types of programs. For example, anything network related or network aware will probably need pipes, named pipes, IPC, or other goodies. All programs should use good memory management and most should probably use use threads. Most programs use files.This early coverage of these topics allows you to see clearly how to use the appropriate calls, without having to sift through the guts of a PM program's code to try to extract the necessary information. These first few chapters are interesting, instructive and well-written.

The real PM programming issues start in chapter six. This chapter is an introduction to the basic APIs and structure used in a PM program. First, you must get a handle to an anchor block. Next, you set up a message queue, and register your program's class with OS/2. Then you create your window with whatever options you want. Finally, the message loop is set up, and when the program exits this, it cleans up and quits. The window procedure is explained last, which wraps up your basic PM application. To this basic skeleton many frills can be added, and chapter six introduces a few of them.

There are an incredible number of messages and defined constants in OS/2 PM programming, and this book does a good job of listing and explaining the important ones. Occasionally, I felt that a bit more of an explanation was in order; an explanation by way of a sample use is the easiest to understand. Chapter six lists a lot of these, and it is a fairly big and hairy chapter to get through. Since anyone reading this chapter will be a first-time PM programmer, I feel that pulling the constants and messages into a new chapter seven, with lots of forward references to them, would be helpful to the organization of the book. Either that, or split the chapter into an introductory and an intermediate fundamental window programming chapter. The reason I mention this is that I practically flew through the first five chapters, but took the longest time to get through chapter six. The sheer amount of material and data in this chapter hinders learning a bit, I find. I also find the WM message section at the end of the chapter a little lacking in readability. Anyhow, onwards we go...

By the way, I love the little "Gotcha!" sections that explain and warn about certain things. I find that they really enhance the understanding of the material, and add a little extra interest too.

The next two chapters on dialog boxes and menus are both short and sweet. They present the necessary information, and not much more. Both ways of creating and designing dialog boxes are explained, and all basic types of menus are demonstrated. Again, however, I found the message sections at the end of the chapters a little hard to read, and it is hard to find what you want there, or even to know what you are looking for. A slightly different layout, and a few more explanations of intended usage would probably go a long way towards alleviating this.

The next two chapters on list boxes and buttons are a little sparse. Only the resource file creation method is demonstrated, which doesn't satisfy all uses. The examples are a little too simplistic; perhaps another one or two should be added to each chapter. For example, the listbox sample doesn't demonstrate how to add items, delete items, and so on, and the button example doesn't demonstrate how to do anything useful with the buttons; it only shows you what the various styles look like. On my screen (1024x768x256 svga with a modified ibmdev32.dll) the information icon overflows the borders of the icon button a bit. I suppose that may be my fault for modifying ibmdev32.dll for the smaller 32x32 icons, but I wonder if there is some logical way of fixing it, or programming around it?

The notebook and container chapters are both good, and pretty thorough. The only thing I missed was a run-down on the BKA constants for notebook. The other constants are listed, why not these? They are mentioned in the text, however.

Another little note here: throughout the text there are little hints on style, mainly following the CUA guidelines. This is a great idea, since a lot of books skip this. It is not always intuitive which way of doing something will yield the best results, and the people who designed the CUA guidelines have spent a lot of time studying interfaces and so on. In general, your applications should follow the CUA guidelines quite closely, unless you have a very specific reason for deviating from them. This will insure that most application can be learned quickly and easily. On the other hand, who has the time to find, get, and read the CUA documents? The hints in this book help you make the right decisions.

In the spin-button chapter, code is finally given to create a control right in the application instead of jumping to some dialog. Unfortunately, I didn't have the luxury of knowing my window size ahead of time like the example code did, so I had to resort to other methods of calculating the spin-button position for me program. I tried to post a user-defined message to myself from the WM_CREATE message handling as suggested in chapter six, but could not get this to work. No matter what I did, the WinQuerySysValue returned a size of zero for the window. It would have been good to see some real code to do this. The rest of the functionality of the spin-button is well-explained, though. The use of accelerator keys to jump from spin-button to spin-button is neat.

A third note: many of the programs supplied run badly when run from another directory. The slides programs are one example. When run from the parent directory, the ribbon-strip doesn't show up. Giving an error would have been preferable, I think. I am not really sure why they act like this. Because of the numerous directories for the sample programs, I was running the programs from the parent directory until I realized that some of them didn't work when run like this. (Just in case this is a bug in the OS, I am running the 2.11 CSD for OS/2 2.1 GA.)

The slider chapter has some neat thread and object-window examples, but I missed an example on a non-read-only slider. Considering that there are three (!) sample programs for this chapter, I think there should be at least one on a regular slider. Apart from that, it is good.

The standard file and font dialog chapter has a standard example of each type. Perhaps it would have been nice with another tweaked example, but this will get most people started.

Subclassing windows is a very important topic for anyone interested in doing things a little differently than the designers of OS/2 had envisioned. Most of the controls have a very tightly defined standard behaviour which doesn't always suit your needs. Subclassing windows gives you the opportunity to keep what behaviour you like, and modify what you don't. As an example, look at EPM. It has extra buttons on the title for rotating through the files you have loaded. This was most likely accomplished through subclassing the titlebar window. Unfortunately, IBM designed EPM with slightly different button shading depth for these buttons, so it looks a little odd, but it works in any case. Subclassing requires that you write an alternate window procedure for the window in interest to handle the different behaviour, and then pass the rest of the messages on to the original window procedure. This chapter explains this concept well with a nice flow-chart. I would have liked to see another, more complicated example, but the one supplied does demonstrate the basics.

The drag and drop chapter introduces what is probably a fairly alien concept to most programmers. We have likely all used it, but few of us realize what really goes into programming this behaviour. It is a little weird-alice, but there are two examples to help us along. Unfortunately, both examples have the minimized icon behaviour disabled, so it is impossible to tell how much of what was programmed will work on an icon, and how much won't. It would have been informative to have at least one of these examples demonstrate this. The chapter otherwise does an excellent job of explaining what is a difficult topic.

The subject of help is one of my favorites. Obviously, writing for this magazine gives me a unique depth of knowledge of IPFC and the INF format compared to normal programmers. In addition to this, I have always been extra pleased when I have used a program for which the author took the time to write a really good help interface. There is nothing more frustrating than looking up the help for the control that is supposed to accomplish function X, but which you are having trouble getting to work, and reading either "This control does X", or "This is the help file. This program does XYZ." but no specific help on what you are looking for. The help is one of the most important details, because it tells your user what to do when your best efforts at making your application intuitive have failed. The help chapter is one of the best in the book. It is well organized, and the example covers pretty well everything that you need to know. It is NOT a tutorial on how to make IPF documents, but then the Toolkit covers that pretty well. The example goes one step further than is common in showing how to set up a chain of help through a message box, and into the help document, if required. It is good to see that this important topic has received the full treatment it needs. A lot of shareware programs out there, and even some commercial programs (even some IBM programs, but I won't mention that) have abysmal help facilities. When evaluating a program, if I run into a snag and the help facility is poor, then the program usually goes the way of the dodo bird immediately. I don't often feel like using Zen to try to imagine what the "right way" of doing something is. If the help isn't helpful, it can seriously ruin the enjoyment of an otherwise good program. Lecture over. By the way, this chapter's example program is another that doesn't run from the parent directory. This is understandable, since it can't find the help file, but it should really give an error message instead of just not working. Luckily by this time I was accustomed to jumping into the proper directory.

The final chapter of the book is on Presentation Manager printing. This is a topic which I have traditionally skipped over lightly, partly because I don't have a printer. I use the printers at school whenever I need to print a resume, or whatever. A second reason is that I don't tend to write programs which need to print, like most of us. BUT, since it is the last chapter of an otherwise enjoyable book, I decided to read it anyway. As I have come to expect by this time, the chapter is well written, covers the basics well, and makes sure that when you do have questions which this book can't answer, you are ready for a more advanced book anyway. The example doesn't do much fancy printing, but then that should probably be covered in a different type of chapter anyway. It does give a proper foundation in setting it all up, and shows you the potential pitfalls to avoid.

Well, that's the book. Appendix A has references to all the standard reference books you could want.

Summary
Ever since I opened The Art of OS/2 2.1 C Programming and started reading through the chapters, I realized that this would become one of my favorite OS/2 programming books. It is an easy read, but reasonably thorough in its coverage of the basic issues. It has humour, which you'll realize is important to me, if you have been following my column at all. It doesn't assume too much knowledge from you, but it doesn't treat you like a dolt either. I can recommend this book with a clear conscience to anyone starting out in GUI and OS/2 PM programming. It needs a few additions, but is reasonably complete in its current state. Including a few introductory OS/2 chapters on basic (non-PM) matters was a stroke of brilliance. It isn't obvious at all how important it is to include this until you read the book, and think "why isn't this in my other books?". Anyhow, enough evangelizing.

I debated with myself for a long time about whether to give this book an A- or a B+. I finally decided that there were too many little niggling things which I would like to see fixed to give it an A-, so B+ is what it got. This book obviously has very good potential though, and could easily be improved with a revision. There are a few of suggestions I would like to make:
 * This book really should support compilers other than just C-Set++. I personally own Watcom C/C++ 9.5 (and soon 10.0), and had to use the makefile from Real World Programming for OS/2 2.1 to get the programs to compile. I imagine Borland C++ owners (of which I am one, although I don't use it) and owners of other compilers have similar problems. Similarly, the tools chapter only describes the OS/2 2.1 Toolkit. Watcom C/C++ uses the Toolkit, but Borland C++ has its own tools, so Borland C++ programmers are left out in the cold a bit. And what about EMX? Ideally, the book should support IBM C-Set++ (both FirstStep and the full-blown version; they should be the same), Watcom C/C++ 9.5 and 10.0, Borland C++ 1.0 and 1.5, EMX, and Symantec's C++ compiler, maybe even MetaWare's High C/C++ and MicroWay's C++ compiler. At the very least, C-Set++, Watcom C/C++, Borland C++, and GNU makefiles should be covered. We can't all afford C-Set++ :)
 * The diagrams in the book are a little cheap-looking, considering that we are dealing with a tour-de-force in graphical environments, OS/2 2.1. That is probably the luck of the draw when you are a new author, though. Hopefully this will be alleviated in the next edition.
 * The sample programs really need a graphical installation program. I was unlucky, and got a pseudo-bad disk, and only after much fiddling was I able to install and unpack all the samples. The disk wouldn't be the authors' fault, but the installation procedure is.
 * Chapters on SOM, WPS, GPI, interfacing with REXX, DLLs, bitmaps, colour palettes, and perhaps an intro to C++ should be added. I have been considering recommending an introductory VIO chapter, but I am not sure whether that is a good idea, since VIO is old hat. On the other hand, VIO programs certainly do fill a niche. A chapter should be added with loose ends like WinMessageBox.
 * The index needs beefing up too, roughly doubling should do. One can't always know the thing one is looking for by name, and there are very few keyword topics in the index.
 * More depth is needed in control window creation and manipulation, like sizing them upon window creation when you don't know what size your window will be, resizing list boxes on the fly and so on. A lot of the example code is dialog template based, and there aren't a lot of examples on how to create and manipulate the various windows right in your application. When I had to do this, I found it helpful to peek in another one of my books.

Note that I am nit-picking here. These are more after-thoughts than things I really missed when I went through the first time, except for the window creation and manipulation stuff. Consider this "polishing" what in many ways is a great book.

I have been told that there is a revision on the way, with more in-depth coverage, and new chapters on key subjects, but that's all I know so far. If the stuff is added I mentioned above, this book should easily qualify for an A, maybe even an A+. Of course, if everything I mentioned was added, then the book would probably be more of a beginning and intermediate programmer book, and it would be much larger too :)


 * The Art of OS/2 2.1 C Programming, Panov, Salomon, Panov
 * ISBN 0471588024
 * Intended audience: Experienced PM Programmers
 * Mark: B+