REXX Reference Summary Handbook Book Review

by Carsten Whimster

Introduction
In The Codesmith's Library, I focus on development books and materials. I write this column from the point of view of an intermediate programmer. Pick up whichever book strikes your fancy, and join the growing group of people following our programming columns.

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.

Errata
Not much to say this month; it was quiet on the EDM/2 front.

It was very busy at home though. I upgraded my computer to an S3 805 card, and spent a lot of time figuring out how to set it up, locating drivers, and so on. Eventually, it all worked, but man, what a hassle. Hopefully OS/2 3.0 will do away with much of this. I now run 800x600x65k, and I may rearrange my column slightly to accommodate this format better, just in case I had missed something when I was running 1024x768x256. Hopefully I can afford the extra meg of RAM soon, so I can run 1024x768x65k :) Then again, I may not want the slowdown, so I might stick with 800x600x65k.

I also ditched the 486sx25 in favour of a 486dx2-50 (which was hard to find, by the way). This means I should be spending more time ray-tracing and programming soon, and I'll probably update POV-Panel/2 soon. I will likely write an article on programming in VX-REXX and use POV-Panel/2 as an example. Hopefully I can afford to upgrade to VX-REXX 2.1 before then.

I have been tinkering with the Warp-II beta, and absolutely love it. It addresses about 80% of my complaints with OS/2! Now for the last 20%... It did cause some problems, however, one of which I finally traced to incompatibilities between Warp-II and the 2.1 toolkit. Now I can finally compile with IPFC again (important when you work on EDM/2).

Anyhow, on to more programming oriented things...

REXX Reference Summary Handbook
The REXX Reference Summary Handbook is a small, but dense handbook of REXX commands and their syntax. It is ring-bound, and lies flat on the table without changing pages on you. It covers both standard REXX and also some extension libraries. It even has a small pseudo-tutorial for those who have forgotten how REXX handles expressions and so on. The chapters are as follows (I have included the sub-chapter headings to give a better idea of what it covers):
 * 1) Language Summary
 * Basic Fundamentals and Structure
 * Keyword Instructions
 * System Commands & Subcommand Environments
 * Built-in Functions
 * 1) SAA REXX External Function Modules
 * REXXUTIL Functions
 * 1) Other Rexx (sic) External Function Modules
 * REXXLIB Functions
 * RXWINDOW Functions
 * 1) Work Place Shell
 * WPS Objects
 * WPS Classes
 * WPS Object Key-Pairs
 * DOS / WIN-OS/2 Settings
 * Appendix A: ASCII and IBM Character Set
 * Appendix B: Codes Returned by SysGetKey
 * Appendix C: REXXLIB Video Attributes
 * Appendix D: REXX Error Codes

Chapter one covers standard REXX as implemented in OS/2. It describes the instruction layout and semantics briefly before launching into a summary of OS/2 SAA REXX keywords (referred to as REXX from here on in). The descriptions are very terse, but informational, as can be seen in this small excerpt/example:


 * QUEUE [expression]:Places the value of expression at the bottom (/FIFO) of the currently active REXX data queue. If expression is omitted, a null string is stacked.

Only the needed information, but it is all there. In the third sub-section of chapter one, the RXQUEUE and RXSUBCOM functions are described. Lastly, in section four, a complete list of all standard REXX functions is presented, including all the most common ones, and also such pearls as complete descriptions of what effect using CHARIN, CHAROUT, and CHARS have on opening and closing files, all very neatly and clearly described in just a few lines. IBM take notice. Both system calls such as DIRECTORY, text tools such as RXMESSAGEBOX and standard library functions such as RANDOM are explained.

Chapter two covers the functions available in the REXXUTIL library, and shows how to set REXXUTIL up. The REXXUTIL library is a collection of mostly system functions, such as SysGetEA, SysPutEA, SysCreateObject, and so on. Many of these are quite powerful, and enable you to manipulate WPS objects, files, cursor position, et cetera. There may or may not be enough information in this little chapter to get you going with REXXUTIL, but if you have a fair idea of what is available, then there is more than enough information here to refresh your memory, or point out syntactic details. Some of the text functions described do not work in PMREXX, or other PM environments.

The third chapter describes the use of the REXXLIB and RXWINDOW libraries from Quercus. REXXLIB contains the following: mathematical functions, stem and array functions for sorting and so on, extended attribute support, file control, various system functions, hardware information and access functions, and a collection of semaphore functions. Many of these functions go a long way towards making REXX a viable option to C when programming small applications. REXXLIB is available from Quercus as part of Personal REXX, and is also available on many ftp sites. The RXWINDOW library contains functions to manipulate windows in the PM environment, and include functions to mirror most mouse actions, examine window styles, and so on.

Chapter four starts with a list of Object IDs for various programs and objects. This list enables you to access most, if not all of the OS/2 desktop. The WPS classes are then listed, and although it is not quite complete, it should be adequate for most uses. Only some of the more esoteric pieces of the hierarchy have not been placed into the tree. The third section lists the WPS Object Key-Pairs. These consist of key names, values, and descriptions, and are needed for the SysCreateObject and SysSetObjectData functions. Finally, key-pairs are listed for setting DOS and Windows session settings.

Appendix A is a complete ASCII and IBM character set table, with ASCII values up to 255.

Appendix B lists all the various codes that are returned by SysGetKey, and includes all shifted, alt'ed, and control'ed characters, and all the combinations of the above.

Appendix C lists the REXXLIB video attributes, i.e. the foreground and background colour codes, and explains how to combine the two numbers to get the combined code.

The last Appendix in the book, Appendix D, lists REXX error codes with explanations for the non-obvious codes.

Finally, and all authors and publishers should pay attention here, the index is a masterpiece of cross-referencing, and although all books should have this good an index, very few do. This is a sign of excellent attention to detail and a high quality publication.

Summary
This diminutive, but packed reference book is very high quality, and includes all kinds of un-called for details that you simply cannot find anywhere else in one place. A lot of work has gone into every aspect of this book, and it shows. It won an OS/2 Magazine Editor's Award, and if I was in the business of giving out awards, I would give it one as well. The REXX Reference Summary Handbook has a very clear goal, and fulfils it well. It doesn't try to be everything to everyone; it merely covers standard REXX, and some of the most popular add-on libraries completely. All REXX programmers should own a copy. This book has no right to be reasonably priced, considering what it contains, but it is.

I give it an A.

REXX Reference Summary Handbook, Goran
 * CFS Nevada. ISBN 0-9639854-1-8, $US20, $25CAN.
 * Intended audience: Beginning to Expert Rexx Programmers
 * Mark: A