The Codesmith's Library
Written by Carsten Whimster
The Codesmith's Library is a monthly column which focuses on development oriented books and materials. The column is from a beginning PM programmer's eyes, because that's what I am. Pick up whichever book strikes your fancy, and join the growing group of people following our PM programming columns. I will review books aimed at beginners for a while, and then move on from there.
Please send me your comments and thoughts so that I can make this column as effective as possible. After all, the magazine will be more effective with good reader feedback.
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).
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
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 recieved 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.
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: