SCOUG OS/2 For You - March 1997

A New, Great Programming Book

Finally, A Complete Warp Reference:
OS/2 Warp Programmer's SideKick

by Peter Skye

GLENDALE - "Nuts."

The greatest one-syllable response in American history (you do know its most famous usage, don't you?) applies right now, right here, as I and my OS/2 stalwarts face down the Microsoft storm troopers.

"Nuts."

Because I've just spent several days studying the book The OS/2 Warp Programmer's SideKick: Functions & Structures, a quick reference to OS/2 functions, macros, and structures, (Quarter Horse) and because I've just gotten off the phone with co-author Glade Diviney, and because I'm rejuvenated and excited once again about the OS/2 operating system. Compared to "the competition," it can do so much.

This book is not for the faint-of-heart, mind you. If you aren't a programmer and this nifty little text ambles up and rubs against your leg, beat it with a stick until it runs away. Instead, make it the unexpected gift for some OS/2 hotshot you can never understand when he speaks - there's stuff in here he's never heard of, guaranteed. Throw "DdfInform" and "DosGiveSharedMem" and "WinLockupSystem" (yes that's what it does!) at him and watch his loud mouth drop and fall silent, and then tuck this book into his limp hands to keep him quiet a while longer. (Tear out page 331 to keep your systems unlocked.)

When I write programs, I don't think in C, or PL/I (my all-time favorite), or Assembler, or even REXX. (I hate REXX. But don't tell Esther Schindler. Unless she's cute when she's angry.)

Instead, I think in machine language and low-level operating system calls. Then I choose a language which allows me to use the instructions and calls I want. This is "bottom-up" programming, and is exactly opposite to the "top-down" programming that every computer professor in the country will tell you is the proper way to code.

Nuts.

Hint 1: It was spoken by an American, but not on American soil

Glade Diviney and Keith Murray wrote the book because, more than anything, they wanted to use it. OS/2 has so much for a programmer to use that they found themselves searching through stacks of books every time they wanted to use a new function, or to see if such a function existed. How is an error code returned? What is the parameter block? Can I call GpiQueryElementPointer while in DM_DRAW mode?

If you've been programming for a while, and especially if you have experience on multiple platforms (okay, quick, what's an SVC?), you really need to sit down with this book and peruse it for a couple of hours. I'm not really a hyperlink-kinda-guy, but I found myself excitedly jumping all over the place as I cross-referenced mutexes and semaphores and (a per- sonal interest of mine) priority control.

Okay. I gleefully flip the pages and the book opens to page 174, GpiPolyFilletSharp - "Draws a curve with variable sharpness." Ever hear of that? It's a function that, among other things, allows you to draw a curve whose ends are at specific angles you specify. You have to be able to do this when con- necting two roadways with a tangential curve (or when designing model railroad track plans), and you can't do so with a Bezier curve.

Another gleeful flip. Chapter 9 - Structures! Page 431 has CNRLAZYDRAGINFO (Container Lazy Drag Information). You've probably lazily dragged a container a few times and didn't even know it, and you can lazily drag a few more if that hotshot (and loud-mouthed) OS/2 programmer down the hall has this book so he can remember how to code them. (Plus, to repeat, it will keep him quiet for a while.)

Hint 2: It was spoken just over 50 years ago

The OS/2 Warp Programmer's Sidekick is published by Quarter Horse Software & Publications (http://www.teleport.com/~qhorse ). They put the entire Presentation Manager section onto their web site where you can see it for free, but the experience isn't the same. With the book in your hands you see everything, and you can flip through the pages and find things and get ideas a lot faster than you can on a web site.

Furthermore, the book not only contains the information in many other references (including the IBM OS/2 Warp Developer's Toolkit), but it also contains the results of extensive function testing by Diviney and Murray. They kicked the tires pretty good on these functions and corrected the errors they found in IBM's documentation.

Because this is a concise reference volume, you need to read every page - all 579 of them - so you don't miss anything important. Make sure you tell this to that loud-mouthed OS/2 programmer hotshot when you hand him the book. The longer you can keep him quiet, the better. Start with General Notes on page 1 and keep going. DDF (Dynamic Data Formatting) functions are covered in Chapter 1 (15 functions in nine pages), and seven Device Context Functions are covered in the 12 pages of Chapter 2. DevQueryCaps (Device Query Capabilities), detailed in Chapter 2, lets you ask your printer such things as "Are you PostScript-capable?" ask both your screen and printer "How big are your pixels?" (returned as pixels per meter), and ask your mouse how many buttons it has.

Then take a deep breath for the 88 pages of Chapter 3 - Control Program Functions. This chapter is a programmer's delight, covering things like named pipes, semaphores, file locks, executing programs from other programs, moving files without copying, getting system and disk info, changing thread priorities and, for you neophytes, right there on page 28, DosBeep.

Chapter 4 covers drag and drop, and Chapter 5 (another big one) covers the Graphics Programming Interface. Chapter 6 covers the ten Profile Manage- ment Functions for cooking your .INI files. I have absolutely no interest in Profile Management Functions, read the chapter as fast as I could, and promptly forgot everything I read. So, if you want to know about PMFs, don't ask me. Buy the book or go bug Terry Warren over in the Programmers SIG.

However, Chapter 7 was much more fun to read and shows how prescient authors Diviney and Murray are. For, and this is an "inside joke" for all Warp 4 programmers, the very first sentence of Chapter 7 - Presentation Manager Functions says "Any thread that uses Presentation Manager functions must call WinInitialize (page 322) to obtain an anchor block handle," and further states that "Any thread that uses Presentation Manager calls must make this call first." The "inside joke" is that some earlier OS/2 programs didn't, and Warp 4 is, shall we say, very unhappy about this. For more info, go bug Randell Flint over at Sundial, or visit http://www.sundialsystems.com and click on "Sundial Systems has important informa- tion about OS/2 Warp 4." And make sure you get Warp 4 upgrades for all your software that uses Presentation Manager.

Chapter 8 covers Macros, Chapter 9 is Structures (quick! what's the 2nd parameter in _ACCELTABLE?) and Chapter 10 lists error codes. Then come the Appendices (ten of them) and, finally, what the authors call an Overview and I call a Summary Listing showing all functions by type. So, for example, you can look under Alarms and find that DosBeep is on page 28 and "Causes the PC speaker to beep."

Well, not finally. Finally is the order form and, once again, this is the one book you have to have within two feet of your keyboard. The $39.95 list price (Indelible Blue carries it) is discounted to $29.95 if you buy through SCOUG or any other user group. Since co-author Glade Diviney is also co-owner of Quarter Horse, and since neither Glade nor Quarter Horse's cover letter were too clear on specifics, and since I don't see any reason for somebody in SCOUG to have to play middleman just to get you a book, send a check (no phone orders at this special price) to Glade at Quarter Horse right now and tell him you want the book and you want the special SCOUG price. Tell him Skye sent you. If he has a problem with that, I'll have Rock and Boomer drive up there and pay him a personal visit. Expect a $3 shipping charge. Order it and read the entire book. You'll learn a lot and, if you give a copy to that loud-mouth OS/2 programmer down the hall, you'll end up with better programs faster and he'll stay quiet for a merciful few days.

Uh, why are you all handing me copies of The OS/2 Warp Programmer's SideKick?

Nuts!

On December 22, 1944, during the World War II Battle of the Bulge, the Germans demanded the surrender of the encircled U.S. 101st Airborne Division troops at Bastogne, Belgium. U.S. Brigadier General Anthony C. McAuliffe gave the Germans his famous one-word reply: "Nuts!" (The Americans were able to hold out until additional U.S. forces ended the siege of Bastogne four days later.)

Indelible Blue, 800/776-8284 (eastern time - North Carolina), http://www.indelible-blue.com

SCOUG is a trademark of the Southern California OS/2 User Group.
OS/2, Workplace Shell, and IBM are registered trademarks of International Business Machines Corporation.
All other trademarks remain the property of their respective owners.