Feedback Search Top Backward Forward

The Codesmith's Library

Written by Carsten Whimster



The Codesmith's Library

In The Codesmith's Library, I focus on development books and materials. I have written this column from the point of view of an intermediate PM C programmer and intermediate REXX programmer. Pick up whichever book strikes your fancy, and join the growing group of people following our PM programming columns. I have already reviewed a number of beginner's books, and will try to concentrate a bit more on intermediate techniques and special topics from now on.

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.

Due to the large number of books I have received in late '95, I am reviewing two books this month:

OS/2 Warp Workplace Shell API is the third and (currently) last book in the Wiley API series.

The OS/2 Warp Programmer's Sidekick, Functions and Structures is a new concise Warp reference book from Quarter Horse.


Well, I have just moved, so not much is new here other than mess (but that's not new either).

I have recently received a letter from a reader who expressed concern regarding my giving OS/2 Certification Handbook an A- when he felt a B was more appropriate due to the numerous errors in the book. I feel that the errors that I came across were easily caught, and that the value of the book is more in the fact that it demonstrates what depth of knowledge and what breadth of subjects is covered on the actual tests, but I can also see his point. I intend to add an "Errors" page to the site, and put a link directly in the column of issue 3-9, to let people catch these errors and to let them judge for themselves. If anyone has found any errors in this book, please pass them on, and we can keep track of them here. In fact, that goes for any of the books I have reviewed. A central site to check for errors would be very beneficial, I feel, so hopefully we can get this thing together.

Due to the large number of books I received all at once in late '95 and due to the understandable anxiousness of some of the authors, I have decided to review two books this month. Because they are both reference books, and because they don't in any way compete with each other, there should be no concern as to the fairness of these reviews, hopefully. They are each useful in their own way, and have quite different philosophies, so actually contrasting them with each other seems like a useful thing to do. Be sure not to miss the second review.

If you look over the most recent few books that I have reviewed, you will notice that I have been giving a lot of A's and A+'s. This is not coincidence, and it is not a sell-out. Unlike the me- too market of Windows programming books, the OS/2 market seems to have fewer, but higher quality books and references, and naturally I gravitate towards the best ones. I will try to find some lousy books to review, just so that you, the readers, can stay convinced that I am doing my job, and not just taking the easy way out. Please read on for another couple of A+'s ...

OS/2 Warp Workplace Shell API

This month's book is third and currently last in a new series of three API references from John Wiley and Sons, covering the Control Program, Presentation Manager, and Workplace Shell APIs. Here are the chapters:

 1.  Workplace Shell Overview
 2.  Installing Workplace Classes
 3.  Object Manipulation
 4.  Instance and Class Data
 5.  General Object Settings
 6.  In-Use List
 8.  Settings Notebooks
 9.  Pop-up Menus
10.  Drag/Drop
11.  File System Objects
12.  Folder Objects
13.  Programs and Associations
14.  Disk Objects
15.  Shadow Objects
16.  Launch Pad Objects
17.  Palette Objects
18.  Help
19.  Printing
20.  Miscellaneous Methods
21.  System Object Model (SOM)
Appendix A.   Setup String Keynames
Appendix B.   DOS Settings Keynames
Appendix C.   Settings Page Methods
Appendix D.   Workplace Default Object IDs
Appendix E.   Predefined Views
Appendix F.   Device Object Settings
Unlike the previous two month's books, publishing deadlines did not get in the way of creating a decent number of examples to demonstrate the APIs in this book, and I feel that this has strengthened the presentation of the material greatly. I would like to see more sample code for the material later in the book, but this is a small detail. It does seem as if time may have run out for examples for the last few chapters, though, with some exceptions, notably printing and finding objects. Hopefully the next revisions of the other two books will allow a similar level of detail to be added.

Similar to both the other books, the major organization of the book is as follows:

  • each major topic is given its own chapter (see above)
  • each chapter has a few introductory paragraphs, tutorial and explanatory in nature
  • each function/method which comes under this chapter's heading is then given, as follows:
    • name and type of API (ie. chapter heading repeated)
    • brief description
    • syntax
    • parameters, each with a brief explanation, and tables of possible values, if appropriate
    • returns, with value and description of error codes
    • a "How to call" section which describes why and when to call this method
    • a "How to override" section which explains the benefits of overriding the method
    • other info, including include file, define, ordinal, and DLL API resides in
    • see also, with related APIs, each with a page number
    • notes, which usually lists any additional "gotchas" to be aware of
    • restrictions/warnings
    • sample code for many methods, but sometimes another method is referred to

The two "How to" sections, the restrictions/warnings and the notes section are particularly well implemented in this book, with many great explanations of otherwise difficult material, and counter-intuitive behaviour. I really feel that an extra effort was put forth in this area, and from what I know of WPS programming, this extra care and attention is invaluable, and very necessary. Sometimes the explanations seem a little more than is called for, but I far prefer this approach to the opposite one, in which the author assumes that you know things which in fact you don't.

The first two chapters serve only as an introduction to WPS and a quick synopsis of the "normal" Win/Sys functions from the Warp APIs which are relevant to WPS programming. Chapter three introduces the first actual WPS methods. The differences between classes and instances, and their methods, and when to use which is carefully explained. It is not always obvious which is which, but read this material carefully, and I am sure that even people almost as dense as me can understand it.

The introductions to each chapter are extremely informative, and very well written. They are concise, but invariably manage to communicate a large quantity of cautions and explanations. There are many potential pitfalls in WPS programming, and while I cannot guarantee that they are all taken care of, the book certainly conveys the impression of having done just that.

At the end of each chapter, there is a small section which lists all structures used by the methods of that chapter.

Finally, at the end of the book are several appendices which list many useful constants, setup strings, and so on.

Here is an example of the care with which this book is crafted, the wpViewObject instance method:

wpViewObject WPObject instance method

Opens a view of an object

HWND wpViewObject (HWND hwndCnr, ULONG ulView, ULONG param)

hwndCnr - input The window handle for the container from which this object is opened. This can be set to NULLHANDLE. The system usually sets this parameter when the user opens an object.
ulView - input The numerical value that represents the view to open. See Appendix E for a list of predefined Workplace views.
param - input Application-defined parameter for the view. For predefined Workplace views, this value should be NULLHANDLE.

(nonzero value) The handle for the opened view.
NULLHANDLE An error occurred.

Call this method on any object to open a view. Calling this method is preferred over calling wpOpen directly.

Override this method to change its behaviour, but do not use this override to process the opening of application-defined views; wpOpen should be overridden for that purpose.

Include file: wpobject.h

wpClose - 158, wpclsQueryDefaultView - 178, wpHide - 159, wpOpen - 160, wpQueryDefaultView - 165, wpRegisterView - 167, wpRestore - 168, wpSetDefaultView - 171, wpSwitchTo - 173.

The WPObject class processes this method first by checking the concurrent view behaviour of the object with wpQueryConcurrentView. If concurrent views are allowed, wpOpen is called, passing the same parameters that were passed to wpViewObject. If concurrent views are not allowed, an existing view is searched for with wpSwitchTo. If wpSwitchTo then returns FALSE, wpOpen is called. The net effect is that a view of the requested type is brought to the foreground.

The following sample demonstrates how to call wpViewObject by opening the icon view of the System Setup Folder.

SOMAny *Folder;

/* get the object pointer for the system setup folder */
Folder = _wpclsQueryFolder (_WPObject, "", TRUE);
if (Folder)
     /* open the folder and unlock the object because we are through with it */
     _wpViewObject (Folder, NULLHANDLE, OPEN_CONTENTS, 0);
     _wpUnlockObject (Folder);

I think it is fairly obvious from this sample that this book was not whipped together, but it is probably the most carefully written and put together book in my collection, and as a book reviewer, that is not inconsequential. Even more so than the first two books in this series, both excellent, this book represents incredible quality at a good price, and I can say with faith that this book is a very worthwhile addition to the library of any OS/2 WPS programmer. When you realize that Mindy Pollack was part of the WPS development team, you can begin to appreciate the depth of knowledge presented here. It almost sounds like I have sold out or something, and when you look back over the books I have reviewed, many have good marks, but this trio really is quite outstanding. Another A+ with no hesitation.

I should make one caution here, however: as good as the book is, it does not teach WPS programming, but assumes that you know PM, SOM, and at least the WPS basics. This is not anything to be held against the book, but rather something to be aware of.


This is one solid book. Great explanations, well thought-out section for each method, good sample code, and useful appendices go a long way towards making this one of the best books in my library. A+. Another must-have for serious PM programmers. I have nothing bad to say about this book.

This is the third and last book in this series. I am very happy with these three books, but I would be even happier if Marc Stock went on to have a book written on each of the GPI, Messages, and SOM. I hope that many more authors this good will come forward and write books for OS/2, and I hope that more publishers will allow this amount of care to be put into each of their books. These are some of the best programming references I have ever seen.

OS/2 Warp Workplace Shell API, Pollack

  • John Wiley and Sons. ISBN 0-471-03872-5. US$29.99, CAN$40
  • OS/2 C WPS Programmers
  • Mark: A+

The OS/2 Warp Programmer's Sidekick, Functions and Structures

This month's second book is also a reference manual, but with a different slant. The first and most noticeable difference is that this book is ring-bound rather than the more normal paperback cover. This helps it lie flat where you open it. Each chapter and appendix also has a little gray blotch at the right edge of the pages, helping you to quickly jump from chapter to chapter without having to go to the index to look up page numbers. Here are the chapters:

General Notes
 1.  Dynamic Data Formatting Functions
 2.  Device Context Functions
 3.  Control Program Functions
 4.  Direct Manipulation Functions
 5.  Graphics Programming Interface Functions
 6.  Profile Manipulation Functions
 7.  Presentation Manager Functions
 8.  Macros
 9.  Structures
10.  Error Codes
 1.  Character Codes
 2.  Virtual Key Codes
 3.  Code Pages
 4.  Default Country Codes
 5.  Scan Codes
 6.  Control Style Flags
 7.  Graphics Primitve Attributes
 8.  Raster Operation Codes
 9.  Drawing Mode Contexts
10.  GPI Function Scopes

As you can see from this list of chapters, this book apparently has a lot more information than the previous reference books I have reviewed. That is both true and false. There is a lot more APIs covered in total, but the ones covered are covered in a less detailed fashion that the Wiley series. Through this different emphasis, this book should appeal to more experienced programmers who have already used many APIs a few times, and just have to freshen their memory. There is a lot less information about usage than there is in the Wiley series, but all the most important stuff is there, of course, and more...

Chapters 1 through 7 cover the Ddf, Dev, Dos, Drg, Gpi, Prf, and Win functions and macros. Each of these chapters starts out with about one page of cautions and information about the functions in that chapter. There is not a lot of detailed information here, but some good points are made. Each function is described more or less in the following format:

  • name.
  • include.
  • one-line description.
  • syntax, including explanation of values allowed for restricted parameters.
  • returns, which explains all possible return values.
  • errors, which lists all error messages, both hex value and #define.
  • notes, which lists a small amount of usage information and some cautions.

One or more of these sections may be missing, depending on the nature of the function. For example, some functions are missing the returns section if the return value is obvious and unambiguous, such as an HWND. This return value would then be mentioned in the description. One thing I would like to see added is a note for each parameter which explains whether it is input or output. Sometimes this is obvious, and other times it seems obvious, but is in fact misleading. Sometimes parameters can be both input and output, and this should be listed too. As an example, some functions normally take a size, but if the size passed is NULL or 0, then the appropriate size is returned. Perhaps this omission is deliberate, and in keeping with the general "you used to know this but forgot" approach of the book.

Surprisingly, I have found myself using this book much more frequently than one would expect from a novice-to-intermediate OS/2 programmer. It is just very handy, and it is easy to find what you are looking for. The functions are all in pure alphabetical order. Then when I stumble across what I was looking for, but can't figure out how to use it, I defer to a more detailed reference or a programming book. Three quarters of the time, though, I am able to find what I want in this book, and can then move on to the next problem.

An example of the level of detail provided can be seen in this function:


Returns the address of the character after the current character.

PSZ NoName WinNextChar (
   HAB     Anchor,       Anchor block
   ULONG   CodePage,     Code page, or 0 for process default
   ULONG   CountryCode,  Country code, or 0 for system default
   PSZ     Current )     Pointer to current string position


  - This function works for both double-byte and single byte
    character sets.
  - See page 522 for a list of code pages.
While not as detailed as the Wiley series, this allows the authors to pack much more information in a similarly sized book, and I challenge anyone to find a book this size with this much information. The main source for this book is the Warp Toolkit, but apparently many of the errors in the toolkit have been found and corrected, and some ambiguities corrected.

Starting in chapter 8, macros, structures, and error codes are given. The macros are useful, and you can learn quite a bit about the implementation of OS/2 by studying these and the structures. The error codes I have yet to use, but they are there.

The appendices have all kinds of tidbits and goodies, and several times already, I have found something in these appendices that I could not find conveniently anywhere else. As an example, I have used the control style flags many times, and each of these comes with a quick explanation, unlike most of the other stuff in the appendices. In this section you can find slider styles, container styles, value set styles, and so on. The list of GPI primitve attributes is also quite handy. This is a section of lists of GPI related things, followed by a large table of all GPI functions, cross-listed by the drawing modes they are available in. This table has also been put to use by me.

Finally, after the appendices, there is a large section which is modestly called "Overview". This section has a list of all the functions in the whole book, along with a half-line explanation for each. This is a great way of browsing for a function that you know should exist, but you can't find.

All in all, this book is leaner, but has much wider coverage than the Wiley series, and so is aimed more at programmers who already know what they are doing with OS/2. It is biased towards PM programming, but also has extensive control program support. I can heartily recommend this book as the cure to your I-can-never- find-what-I-am-looking-for ailment, as long as you can live with the leanness of the presentation. An undisputed A+.


This is now also my favorite PM reference book :), alongside the Wiley series. A great book, and without competition as a wide- coverage, quick-reference PM reference book. If you want detail, and more help, the Wiley reference series is for you. If you want extensive coverage, and don't need as much help, the quick- reference Sidekick is for you. Yet another must-have for serious PM programmers.

The OS/2 Warp Programmer's Sidekick, Functions and Structures, Murray and Diviney

  • Quarter Horse Software and Publications. ISBN 0-9647472-8-6. US$39.95, CAN$53.95
  • Intermediate and Advanced OS/2 C PM Programmers
  • A+

    Reviewed Books

    Our Bookstore has reviews and links to Amazon for all books we have reviewed in the past, as well as several books waiting to be reviewed, and others which we recommend.