OS/2 Presentation Manager GPI Book Review

By Carsten Whimster

Introduction

In The Codesmith's Library, I focus on development books and materials. I write this column from the point of view of an intermediate programmer. Pick up whichever book strikes your fancy, and join the growing group of people following our programming columns.

Please send me your comments and thoughts so that I can make this column what you want it to be. I read and respond to all mail.

Errata

There are three things on my agenda this month.

First of all, I got mail from a couple of people who disagreed with my rosy evaluation of Writing OS/2 2.1 Device Drivers in C, 2nd Edition, Mastrianni. I guess I should have made a couple of things a little clearer. If you are to use the book, you need Mastrianni's library, unless you write your own DevHlp functions, and the library costs around $150 US. Secondly, the reason I feel strongly about his book is that Mastrianni has done a lot of work abstracting device driver writing away from naked assembler, giving the opportunity to many more people to write device drivers than otherwise would have attempted it. This is the main accomplishment, I think. In any case, you must judge for yourself whether it is worth it. If you do decide to write a device driver, you'll most likely need the device driver kit from IBM, but from what I have heard, it is in dire need of cleaning up. It is supposedly messy, expensive, and incomplete. IBM would really do us all a huge favour by putting out a better kit, and in fact, they may be headed in that direction. Supposedly Mastrianni has been hired by IBM, and I presume he'll be working on their kit development team. If anyone has any factual information on this development, I'd love to hear it. One can always hope. In any case, the book will help you get off to a faster, surer start than if you were to try it on your own.

Secondly, I have had a report of an inaccuracy in Real World Programming for OS/2 2.1, Blain, Delimon, and English. Here is the deal, courtesy of Gordon Zeglinski: on page 440, the following occurs:

!DosSubSet(pHeap,DOSSUB_SPARSE_OBJ|DOSSUB_SERIALIZE))

If we look in the header file however, we find:

#define DosSubSet       DosSubSetMem
#define DOSSUBSET       DosSubSetMem
APIRET APIENTRY  DosSubSetMem(PVOID pbBase,
                              ULONG flag,
                              ULONG cb);

So the code fragment does not even have the correct number of arguments. It will not compile without a warning in C, and will not compile at all under C++. Look at Gordon's C++ Queue Object column for the proper way to use this API.

Finally, from what I have heard, the new Watcom C/C++ 10.0 is imminent, and from reviews of the beta, it is something. It will have an IDE, and an assembler (yes!), on top of the usual stuff, and of course will include the new 2.1 toolkit. If you are about to buy a C/C++ compiler, wait until this comes out before you decide which one to spend your hard-earned money on. It looks like IBM may finally get a run for their money in the high-end compiler-department.

As a foot-note, I am working (with a little help from my friends here at EDM/2) on a tabular content format for what each book covers, and what it does not cover. Exiting stuff, and this may be just what you have been waiting for to be able to decide which book has what you need. Thanks to Gordon (again) for the great idea.

OS/2 Presentation Manager GPI

Sample code fans will like the layout of this book. In some ways, it is quite similar to Real World Programming for OS/2 2.1. Each chapter starts out with a small motivating section, followed by detail on how to actually apply the concepts being presented. The sample code follows at the end of the chapter, and consists of complete snippets of code, with some meaningful function, although whole programs are not included. This is in keeping with the author's stated objective of assisting the intermediate to advanced PM programmer in becoming a proficient GPI programmer. With its 318 pages, the book is fairly substantial, considering that it only covers one major topic.

Here are the chapter headings:

1. Introduction: Simple Text and Graphics Output
2. Presentation Spaces and Device Contexts
3. Drawing Primitives and Attributes
4. Fonts
5. Bitmaps
6. Color Tables
7. Coordinate Spaces and Transformation
8. Clipping and Regions
9. Orders, Elements, and Segments
10. Correlation and Boundary Data Accumulation
11. MetaFiles
12. Printing
13. The OS/2 2.0 32-Bit Operating System

Appendix 1: DevOpenDC Parameters

Appendix 2: PMPRINT Queue Processor Parameters

Appendix 3: Introduction to Transforms and Matrices

Appendix 4: Sample MetaFile Internals

Appendix 5: Sample Orders

Appendix 6: GPI Functions Supported only by a Normal-PS

Before using this book, you should already know how to set up a skeleton program, with message queue, window procedure, and all the rest of the trimmings. This book ONLY talks about the GPI and a few Dev functions.

The first chapter introduces the methodology and intent of the GPI APIs. Brief explanations of device contexts, presentation spaces, and so on are presented. Personally, I would have liked a section explaining the design choices made in the GPI APIs, but that doesn't hurt the coverage of the book. One thing I did miss, though, was a little humour. Like so many programming books, humour is conspicuous by its absence. I am not calling for a Monty Python-esque treatment of the material, just a little light-hearted jesting. This would make it more enjoyable, and less dry. Oh well, it's not the first time I have missed that, and it won't be the last.

The general feeling of the subsequent chapters is one of a programmer who knows his field very well, but has a lot to cover. Each sentence has terse information to present, and it never lets up. This is not a book you sit down and read in a couple of days! Every sentence has to be thought through after reading it! You probably have to try the code from each chapter in your own applications before really understanding what's going on.

Chapter two lays the ground-work for all GPI programming. Device contexts and presentation spaces are explained again in much greater detail than the first time. There are limitations to each choice of PS, and the correct type of DC must be used. This seems logical at first sight, but can be complicated when your requirements are not clearly delineated. Unfortunately, the diagrams used in the book look like something the original word-processors might have produced, not very professional. Not good for a book on presentation graphics and printing.

The various drawing primitives and attribute groups, characters and text, lines and curves, filled areas or patterns, markers, and image and bitblt pixel operations are introduced in depth, and their relationship to each other are explained. Non-bundle attributes are explained next. Many functions and their related possibilities are explained.

Each of chapters four to eleven introduces its own area, and finally in chapter twelve, the particular problems of printing are demonstrated. I did feel that chapter five on bitmaps was short, given the disproportionate amount of interest this particular topic usually has.

There are a lot of gotchas in GPI programming, and a lot of little rules you have to be aware of. Most people will not really use that much of the GPI, except to output a text-string here and there, and for these people, this book is overkill. It is not intended as a reference book, there are other books for that purpose. This book is intended, in the author's own words "...to provide answers (illustrated by programming examples) to any questions that Application Developers may have concerning the GPI and Dev functions. Rather than providing a tutorial description, I have concentrated on making the description of each topic as comprehensive as possible." The end result is a book which is similar to a reference in coverage, but more like a tutorial in presentation.

My final impression is a good one, even if the book is a little dry. It concentrates on presenting OS/2's way of programming with graphics, not on teaching the uninitiated about graphics programming. The one major short-coming is that it was written for 16-bit OS/2 1.3. I find it strange that the book has not been re-written for OS/2 2.x, but perhaps the sales of this book were disappointing because of the slowness with which 1.3 caught on. Now is a different story, though. With over 5 million copies of OS/2 sold at last count, we need an updated version of this book. My final evaluation of this book reflects this.

Summary

This book ought to be updated. There aren't many books on the market specifically about the GPI, and with the current boom going on with OS/2 2.1, 2.11, warp/personal OS/2, and so on, it would be perfect timing to have a new edition now. The book is terse, well-written and accurate, but needs descriptions of the 32-bit functions, the new functions, and how to interface the two with 16-bit functions.

Therefore I give it a C+.

OS/2 Presentation Manager GPI, Winn,

Van Nostrand Reinhold. ISBN 0-442-00739-6. US$35, CAN$45.

Intended audience: Intermediate to advanced PM C Programmers

Mark: C+