Tips and Tricks from Another Source

By Richard K. Goran

REXX Tips & Tricks - Version 1.8 27
I'm sure if you are either a professional programmer using REXX or a casual REXX user you have a place where you store miscellaneous bits of information that you save for future reference. You then have to remember where that tiny fragment that you read about some particular REXX command or function is salted away.

Bernd Schemmer of Frankfurt, Germany has made life simpler for all of us by collecting these REXX-related tidbits and publishing them collectively. If there's been a helpful suggestion or tip posted in any of the electronic forums devoted to REXX, its a good bet that it is included in Schemmer's collection. He updates this free file on a regular basis and amazes this REXX professional with the breadth of the material he has gathered into a single document. His report is available on many electronic repositories with a file name of rxtt18.exe (with the numeric portion of the file name indicating the release level of the file). The self-extracting file expands into an .inf file that can be viewed and searched with the OS/2 VIEW program like any of the system .inf files.

Since Schemmer's first language is German, you may find an occasional incorrect word usage or grammatical structure that is not quite correct but the hundreds of items contained in his Tips & Tricks is otherwise well presented. He credits all of his sources and provides hyper-linked references to the appropriate source's E-mail addresses. Some of the subject matter is not explained in enough detail to provide a full explanation of the topic; however, the mere presence of the topic is frequently enough to provide insight into the matter being discussed. Table 1 contains a brief list of the hundreds topics contained in Tips & Tricks.

Tips & Tricks contains numerous sample programs that can be extracted from the .inf file. Schemmer details a technique to extract these program using the View program menu entries Services / Copy to File while the window with the source code is the active window. The View program creates a file named text.tmp in the current directory. You can then adjust the contents of text.tmp for your own needs and save it as a .cmd file.

While I'm pleased to say that I have contributed numerous items to this extensive collection of REXX-related items, I always manage to find something that makes me say "I didn't know that" each time Schemmer releases an updated version of his Tips & Tricks. With Schemmer's permission, I have included some of the more obscure items. I have made some minor corrections to spelling and grammar.

Special environment variables for REXX programs
The following environment variables have a special meaning for REXX programs:


 * RXTRACE:If the environment variable RXTRACE is set to ON before executing a REXX program, the REXX program is executed in single step mode. This is the equivalent of including the REXX TRACE command with the parameter ?R. Any other value for the RXTRACE variable is ignored by the REXX interpreter. To prevent the execution of a REXX program in single step mode even if the environment variable RXTRACE is set to ON, use the statement: CALL TRACE 'OFF' as first statement of your program. This is very useful to prevent tracing programs like PMREXX or a REXX program "compiled" with programs like REXXCC.


 * RXQUEUE:This environment variable contains the name of the queue which the program RXQUEUE.EXE (subcommand) should use if the queue name is NOT specified within RXQUEUE is launched. The default queue name used by RXQUEUE is the default REXX data queue name of SESSION.

Output & Input control
To ensure that the output of your program goes to the screen regardless of the current target for STDOUT use: call LineOut "CON", "This output always goes to the screen!"

rather than outputting the line with the SAY instruction. To print messages to STDOUT or STDERR you can use these names for the output device. For example: /* print a string to STDERR */ call LineOut "STDERR",, "This output goes to STDERR" /* print a string to STDOUT */ call LineOut "STDOUT", "This output goes to STDOUT" To ensure that the input for your program comes from the keyboard regardless of the current source for STDIN use userInput = LineIn( "CON" ) It is important to note that functions LINEOUT and LINEIN use normal file handles for the output devices. Therefore, be sure to close the device with the STREAM function after using it. Note that there is no way to direct output to the handles 3 to 9 in REXX.

Special variables
A special variable is one that may be set automatically during processing of a REXX program. There are 3 special variables used by the classic REXX interpreter and 5 special variables in Object Oriented REXX.


 * RC:This special variable contains the return code of the last external non-REXX command called; for example, OS/2 commands like DIR or EAUTIL. In case of a SYNTAX error this variable is set to the syntax error number (1-99). After an ERROR or FAILURE condition RC contains the command return code. Commands executed manually while tracing interactively do not change the value of RC.


 * RESULT:This special variable contains the return code of an internal or external REXX function if called with the CALL statement. The special variable RESULT is dropped if the REXX function doesn't return a return code. RESULT is also dropped if the function is called in an implicit or explicit assignment (a = myFunc; if myFunc = 4 then).


 * SELF:(Object Oriented REXX only) - This special variable is set when a method is activated. Its value is the object that forms the execution context for the method (that is, the receiver object of the activating message).


 * SIGL:This special variable is set to the line number of the last instruction that caused a transfer of control to a label (any SIGNAL, CALL, internal function call, or trapped condition).


 * SUPER:(Object Oriented REXX only) - This special variable is set when a method is activated. Its value is the class object that is the usual starting point for a super class method lookup for the SELF object.

All of these special variables can be changed just like any other REXX variable. You should save the values of the special variables in another variable if you want to use them in other statements.

Opening files
The default mode for opening files in REXX is READ/WRITE (even if you open the file implicitly via the LINEIN function). This prevents other programs from opening the file even if the first program opening this file only wants to read from the file. To avoid this, I (Schemmer) suggest you use an explicit call to the STREAM function to open a file in READ mode if you only want to read from it.

Closing files
Because the number of possible file handles is restricted in OS/2 sessions, you should always close every file you've opened as soon as possible. You also need to close a file (and perhaps reopen it again) if you want to call another program to write into or read from this file. You should only use call STREAM filename, "C", "CLOSE" to close a file. The other method, using LINEOUT or CHAROUT without the second parameter, is only valid for files to which you have write access (even if you've only read from the file).

Tips & Tricks contains the most complete list of OS/2 REXX-related freeware and shareware that I have ever seen. Schemmer has also included the pertinent information about all of the printed REXX books and articles currently available. Tip & Tricks almost has too much information in it. However, since it is in .inf format and viewable with the standard OS/2 VIEW program, you can search it by keyword for items of special interest to you. Schemmer includes instructs for converting the .inf file to ASCII text or HTML format for printing.

Object REXX
As I write this column, I have come to the conclusion that Object REXX may have been left dangling in the breeze by IBM PSP. In addition, the person who has served as the lead developer of Object REXX for the past couple of years has moved on and is entrenched in his new surroundings at Lotus - not the IBM Glendale Laboratories in Endicott, NY. However, I have been told that the new REXXUTIL API that I wrote about in my August, 1995 column will still be released with the next version of Warp (code name Merlin) - when and if that occurs.

Object REXX users who have been waiting for a newer beta than that which was made available on the DevCon 8 CD-ROM will have to wait for DevCon 10. The IBM Developer Connection folks in Boca Raton have announced that the DevCon 9 CD-ROM will not contain any updates to Object REXX.