EDM/2 - The Codesmith's Library

The Codesmith's Library

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.
OS/2 Warp Control Program API is a new reference book from Wiley which covers the Control Program API (surprise), both documented and undocumented.
Errata

My Web page has recently had over 3500 hits. I have plans to improve several sections of it, at the expense of others. Specifically, I have plans to expand the developer, software and hardware sections, at the expense of the news and "other" sections. Check it out at http://www.undergrad.math.uwaterloo.ca/~bcrwhims/os2.html .
I have just acquired a copy of IBM Visual Age C++, which runs on the edge of sluggishness on my DX4-100 with 20 Megabytes of RAM! That is only the Visual Builder component of it, for which IBM recommends 24 Mb! Hopefully they will rewrite the environment in C++ with the help of VAC++, from the current Smalltalk implementation. In addition to this, it takes up 170 Mb on my hard drive. In any case, the upshot of this is that I will soon be reviewing more IBM C-Set++ and VAC++ specific books than I have in the past (i.e. more than none). See the "Coming Up" section for some specific examples of such books.
OS/2 Warp Control Program API

This month's book is one of a new series of three API references from John Wiley and Sons, covering the Control Program, Presentation Manager, and Workplace Shell APIs. This particular book promises to cover more than just what the Warp Toolkit online references cover, while presenting the material in a well-structured, easy-to-use manner. We will soon see whether it lives up to these high self-imposed expectations. Here are the chapters:

Device I/O
Dynamic Linking & Resources
Error Processing
Exceptions
File Management
File System
Memory Management
Message Management
National Language Support
Pipes
Processes & Threads
Queues
Semaphores
Session Management
Timers
Miscellaneous
The one proviso given, with respect to what is covered, is that the DosDevIOCtl() and DosDebug() APIs are not covered in depth, due to the scope of the book, and the size requirements of a solid coverage of these topics. This should not matter to 99% of all users of this book, however. The one note about the material in this book is that publishing deadlines did not allow the development of examples for each API, but the author, Marc Stock, has promised that these examples will become available on CompuServe as they become available. (If anyone can confirm this, please mail me, and even better, upload a copy to Hobbes as well).
With that out of the way, the rest is pure joy, and smooth sailing. The 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 in nature
each function which comes under this chapter's heading is then given, as follows:

name and type of API (i.e. 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
other info, including include file, define, ordinal, and DLL API resides in
see also, with related APIs, each with a page number
notes, including warnings, restrictions and so on

This very simple layout makes it very simple to navigate, and very powerful. In addition to the above information, each chapter has a section at the end which outlines and describes all the relevant data structures, complete with data types for each field in structures, hex values and so on.
The Miscellaneous chapter has the DosFlatToSel() and DosSelToFlat() APIs for conversion between 16-bit and 32-bit addresses, and the DosQueryExtLIBPATH() and DosSetExtLIBPATH() APIs for using the new BEGINLIBPATH and ENDLIBPATH DLL seaarch path environment variables. This means that when you run your application's installation routine, you do not have to force the user to reboot before your application can get at its DLLs any more! Just use these APIs to temporarily extend the LIBPATH until a real reboot does occur. The appendix contains the late-breaking addition of the DosCancelLockRequest() API.
That is it! The whole book is like this! It is great reading. Believe it or not, I read a large part of this book while travelling back and forth between Toronto and Waterloo, a one-and-a-half hour bus ride, and I was never bored. It is very well written, and very complete (as far as I can tell, although I am not an expert in the Control Program API).
This review is a little short, so to give you an idea of the quality of this book, I have excerpted one API for your perusal:
DosCreatePipe Unnamed Pipes
Creates an unnamed pipe.
SYNTAX
APIRET DosCreatePipe(PHFILE phfReadHandle, PHFILE phfWriteHandle, ULONG ulPipeSize)
PARAMETERS
phfReadHandle - output The address of an HFILE that will receive the read handle of the unnamed pipe.
phfWriteHandle - output The address of an HFILE that will receive the write handle of the unnamed pipe.
ulPipeSize - input The size, in bytes up to 65535, of the pipe buffer. If zero is specified, a 512-byte buffer is used.
RETURNS

0 NO_ERROR

8 ERROR_NOT_ENOUGH_MEMORY

87 ERROR_INVALID_PARAMETER

OTHER INFO
Include file: bsedos.h
Define: INCL_DOSQUEUES
Ordinal: 239
DLL: DOSCALLS
SEE ALSO
DosClose - 220
DosDupHandle - 221
DosRead - 225
DosWrite - 227
NOTES
Unnamed pipes can only be used between related processes (parent/child).
If the system cannot allocate its internal structures or the pipe buffer, then ERROR_NOT_ENOUGH_MEMORY is returned.
The size of the pipe specified in ulPipeSize is oly a recommendation to the system. The actual size of the pipe will depend on available memory. If the value specified for ulPipeSize is greater than 65535, then ERROR_INVALID_PARAMETER is returned.
Notice neat helpful stuff like ordinal numbers, and the "Notes" section. If you didn't know that the pipe size is only a suggestion, you might have spent hours trying to track down obscure bugs caused by a reliance on the size of the pipe, or something similar.
This should be enough to see what the layout is like. Of course, everyone has their preference, but I have personally found what I am looking for.
Due to the rather rosy nature of this review, I feel compelled to emphasize that I have absolutely no affiliation with either John Wiley or IBM. I don't know, and have never either spoken to, or conversed with by mail, the author, Marc Stock. I just like his book.
Summary

This is so far my favorite OS/2 reference of any kind! It is very thoughtfully set up, and I love the mini-tutorial sections at the start of each chapter. The only unfortunate part is that the examples are not in the book. The author's intention of providing these free on the CompuServe forums helps a lot, but he needs to make sure that they end up on the Internet too. In spite of this minor inconvenience, I have no hesitation in giving this an unqualified A+. It is quite simply an excellent book.
OS/2 Warp Control Program API, Stock

John Wiley and Sons. ISBN 0-471-03887-3. US$29.99, CAN$40
OS/2 C Programmers
Mark: 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.