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
 7.  Views
 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

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

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

PARAMETERS

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.

RETURNS

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

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

HOW TO OVERRIDE
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.

OTHER INFO
Include file: wpobject.h

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

NOTES
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.

SAMPLE CODE
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.

Summary

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
Appendices:
 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
Overview

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:

WinNextChar  INCL_WINCOUNTRY

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

Errors
   0x100B   PMERR_INVALID_STRING_PARM

Notes
  - This function works for both double-byte and single byte
    character sets.
  - See page 522 for a list of code pages.

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+.

Summary

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