The Codesmith's Library OS/2 Warp REXX Reference Summary Handbook Written by Carsten Whimster

Introduction In The Codesmith's Library, we focus on development books and materials. Pick up whichever book strikes your fancy, and join the growing group of people following our programming columns. Please send your comments and thoughts so that we can make this column what you want it to be. OS/2 Warp REXX Reference Summary Handbook The OS/2 Warp REXX Reference Summary Handbook is a REXX reference book in the truest sense of the word. It does little or no hand-holding, and its aim is to inform the initiated. This OS/2 Accredited book won an OS/2 Magazine Editor's Award, and may well win more awards as the popularity of OS/2 and REXX increases. The OS/2 Warp 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 1. Basic Fundamentals and Structure 2. Keyword Instructions 3. System Commands & Subcommand Environments 4. Built-in Functions 2. REXX External Function Modules 1. REXXUTIL Functions 3. Other Rexx External Function Modules 1. REXXLIB Functions 2. RXWINDOW Functions 4. Work Place Shell 1. WPS Objects 2. WPS Classes - Prior to Warp 3 3. WPS Classes - Warp Version 3 4. WPS Classes - Warp Version 4 5. WPS Objects: Key Values / Pairs 6. DOS / WIN-OS/2 Settings 5. WPTools 1. WPTools Functions 6. RxFTP - REXX File Transfer Protocol 1. RxFTP Return Values 2. RxFTP Functions 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. There is some new material in chapter 1, including an expanded introduction, and some minor updates to the REXX functionality and syntax, in addition to many new examples. 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. Again, there are a number of updates in this chapter, including a longer intro, a bunch of new functions, and some updates to existing functions. 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. Quercus' address has been added to this chapter, the latest additions to REXXLIB, and some other minor stuff, but this chapter is largely the same. 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 keynames, values, and descriptions, and are needed for the SysCreateObject() and SysSetObjectData() functions. Finally, key-pairs are listed for setting DOS and Windows session settings. This chapter is the most changed in the book. Lots of new information has been added, including lots of new object IDs for all the exciting new Warp 3 and 4 stuff, and three sections on WPS classes in the various versions of OS/2. Again, a lot of new key/value pairs have been added. The DOS and Win-OS/2 settings are mostly unchanged. Chapters 5 and 6 are entirely new. Chapter 5 documents the WPTools API. Many of you may know of the program Checkini, which is part of WPTools. Henk Kelder put a lot of work into the two functions in his WPTOOLS.DLL library, and Dick Goran has put together the material for his reference book. In chapter 6, Dick documents the RxFTP API. 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. The above appendices and the index are largely unchanged, except for the addition of minor stuff generally related to changes described above. Summary This diminutive, but packed reference book is of 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 OS/2 Warp 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. My previous conclusions on this reference book still hold completely, but even more so. Nowhere else will you find so much REXX reference material in one place, and much of this information simply cannot be found elsewhere. If you do anything with REXX beyond simple scripts, you need this book! OS/2 Warp REXX Reference Summary Handbook, Goran C F S Nevada, ISBN 0-9639854-3-4, $US 34.95 Intended audience: REXX Programmers Mark: A+ This book can be purchased from http://www.cfsrexx.com/. 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.