OS/2 e-Zine! - REXX Reference Summary Handbook, 4th ed.

REXX Reference Summary Handbook, 4th ed.

- by Dr. Dirk Terrell

As is so often the case, IBM has developed a very powerful tool (OS/2 REXX) and provided it to OS/2 users with only minimal documentation. I, and many others, have spent countless hours searching for information on how to use a particular REXX function -- especially those in the REXXUTIL library that comes with OS/2 REXX. What I, and many other REXX users, have always wanted is comprehensive REXX documentation.

Dick Goran's REXX Reference Summary Handbook is the documentation that IBM should have given us. OS/2 Magazine readers know Goran as the author of the REXX Column where he gave invaluable tips on using REXX under OS/2. His REXX Reference Summary Handbook concisely documents the REXX language as well as the OS/2 specific extensions to the language and gives useful tidbits of information that would be nearly impossible to find elsewhere. The latest version is an extensive update that covers many of the new REXX features of OS/2 Warp 4, including Object REXX.

The book begins with a brief summary of the language. Next is a list of the REXX keywords and functions with a short description of the keyword or function and its calling syntax. Most of the information in this chapter is also available in the online REXX help file that comes with OS/2, but the book includes are some valuable notes and examples that are not in the online documentation.

Chapter Two is where the book begins to really reveal its usefulness. This chapter deals with the REXUTIL library of functions that make it possible to interact with the rest of the OS/2 system such as the Workplace Shell. IBM's documentation of these functions is dismal and the REXX Handbook is a welcome supplement.

This is probably best illustrated by an example. The SysCreateObject function is used, as you might guess, to create WPS objects, and it can be very handy. Look up the SysCreateObject function in the online documentation or the REXX Reference Summary Handbook, and you will find that the calling form is:

SysCreateObject(class_name,title,location,setup_string,option)

Now, you can probably make a good guess as to what some of these things mean, but good documentation eliminates the guesswork. Here's what the online documentation says about class_name:

The name of the object class.

Gee, I never would have guessed that. Now look at what the REXX Reference Summary Handbook has to say:

Class_name is the name of the WPS class of which the object is a member and title is the new object's title. A new line character, '0A'x, can be included in title. The occurrence of the escape character ^ ('5E'x) also causes a new line to be created; however, 2nd and subsequent escape characters used for this purpose appear to be ignored.

It's little bits of information like this that make the REXX Reference Summary Handbook so useful. How many hours would be wasted trying to figure out things like that on your own? The description of the setup string is an even better example. IBM's documentation says:

A WinCreateObject setup string.

Say what? Searching on WinCreateObject reveals nothing. Here's what the REXX Reference Summary Handbook has to say:

Setup_string optionally must contain a WinCreateObject string which is comprised of a series of "keyname=value" pairs that change the behavior of the object. "Key names" are separated by semicolons and "values" are separated by commas.
Note: If a value includes a semicolon (; - '3B'x) or a comma (, - '2C'x), it must be "escaped" by preceding it with a caret (^, '5E'x).

and a note directs you to a section later in the book that gives all the details of building a setup string for various objects.

The next chapter deals with the extensive set of functions in the REXXLIB library from Quercus Systems. This library adds over 150 functions to REXX including mathematical functions, interprocess communications (semaphores, named pipes, etc.), sorting, and functions for performing actions on REXX stems. (A demo version of REXXLIB is available on the OS/2 Supersite [ZIP, 240k].)

Chapter 4 is the gold mine. This chapter covers the Workplace Shell in such detail that it will leave no REXX programmer unsatisfied. The first section lists most of the WPS object ID's and titles, including the Java objects that come with OS/2 Warp 4. Sections 2 through 4 list the WPS class names and corresponding DLL files for OS/2 2.1 and earlier, Warp 3, and Warp 4 respectively. Section 5 covers the key/value pairs used in the setup string for the SysCreateObject and SySetObjectData functions.

IBM has done a miserable job of documenting these functions, so most of the information in this section has come from detective work by Goran and others outside IBM. This is the most comprehensive documentation of these functions to be found anywhere.

Chapter 5 documents Henk Kelder's freeware WPTOOLS library. This library has functions that the advanced REXX programmer needs for cleaning system INI files, backing up the Desktop and more. It can be found on the C F S REXX page.

Chapter 6 has documentation for the RXFTP library about which I wrote in the REXX Files not too long ago. RXFTP lets you transfer files via the FTP protocol from within a REXX program and is included with the TCP/IP package in OS/2 Warp 4. If you are using an earlier version of OS/2, you can find it on the Watson ftp site (ZIP, 86k).

Appendix D is also a very useful source of information. It covers the error codes that one can encounter when running REXX programs. Not only is each error message explained, in some cases there are suggestions to try to eliminate the source of the error. IBM's error messages sometimes border on the cryptic; The REXX Reference Summary Handbook does a good job of explaining what is happening.

Conclusions

If your are a REXX programmer, this book is indispensable. The REXX Reference Summary Handbook is a book that you will want to have right next to you when you are programming. The book is thorough, well-indexed, and packed with information that would be difficult, if not impossible, to find anywhere else.

REXX Reference Summary Handbook
by Dick Goran
ISBN: 0-9639854-3-4
MSRP: US$31.95

Dr. Dirk Terrell is an astronomer at the University of Florida specializing in interacting binary stars. His hobbies include cave diving, martial arts, painting and writing OS/2 software such as HTML Wizard.

[Our Sponsor: K&S Systems - Riding the WAVE of Technology.]

This page is maintained by Falcon Networking. We welcome your suggestions.

Contents

Conclusions