Kilowatt Software L.L.C.
REXX Language Level 4.00 (TRL-2)
User's Guide

Index

This guide contains the following sections:

Introduction:

r4™ is a Classic Rexx language interpreter. This product implements features of the REXX language as documented in Michael Cowlishaw's famous book: 

    The Rexx Language : A Practical Approach to Programming [SECOND EDITION]

    Author: Michael Cowlishaw

    Published in 1990 by Prentice-Hall, Inc.

    ISBN 0-13-780651-5

The book identified above is commonly referenced as TRL-2. r4™ implements all REXX language features described in TRL-2.

The TRL-2 book can be obtained at one of the following internet sites:

A new 500 page Rexx book, written by Howard Fosdick, has been published by Wiley (ISBN: 0764579967). The book describes how to make the best use of Rexx tools and interfaces, with examples for both Linux and Microsoft® Windows®. A tutorial is provided with lots of examples to help you get up and running with Rexx. The book is available at the following online bookstores Amazon and Barnes and Noble.

Some other helpful REXX language internet sites are:

TRL-2 defines language capabilities for multiple system environments. The guide your are now viewing describes features that are specific to the r4™ implementation of Classic Rexx. Some features are adaptations associated with the Microsoft® Windows® system environments. If you have written Rexx programs in IBM mainframe environments you should be aware that Microsoft® Windows® environments use Ascii character encodings, instead of EBCDIC.

Kilowatt Software L.L.C. provides an extensive online Classic Rexx Tutorial. This tutorial describes all Rexx instructions and built-in functions. There are numerous example programs. If you are learning how to write Rexx programs you should spend some time reading the online tutorial. You should also obtain the TRL-2 book.

Usage:

The r4™ program operates as a Microsoft® Windows® 32 console application. The following is the syntax of a r4™ program request, that is entered as a DOS command prompt. There are four variations. In the first variation, r4™ is the only program that is executed. The remaining variations are command pipelines. The vertical bars separate pipeline command segments.

Within this line, r4 is a request to execute the r4™ program, which has a file name R4.EXE. You should add the directory that contains R4.EXE to your system PATH environment variable. See the environment setup section to determine how to revise the PATH environment variable.

The r4™ program can also process redirected files. The r4™ program can also participate in command pipelines.

Required program name argument:

Program search:

When a fully qualified program name is specified, that program is executed if it exists.

When a partially qualified program name is specified, a search is conducted for the program. This search begins in the current directory, and then proceeds through directories that are defined in the R4PATH environment variable. If a file is found, then that program is executed. Otherwise, an additional search is performed for a program with a default program extension.

Suggestion: always name your REXX program with the default program extension extension, and never create a file that has the same name without the extension. If both files exist, you will have to specify an explicit program extension with the programName argument of the r4 command.

In the first example above, only the fully qualified file name is tried.

In the second example above, an attempt is made to perform the named file, and then an implicit default extension is tried.

In the third example above, a search is performed for the named file in the current directory, and in the directories defined by the R4PATH environment variable.

In the fourth example above, if an extension-less file named 'copyfile' exists in the current directory, or the directories defined by the R4PATH environment variable, then that file will be executed. Often this will cause an error message to appear, because the file is not a REXX program.

In the fifth example above, a search for an implicit default' extension will not be conducted.

Optional additional text arguments:

Writing your first r4™ program

  1. Start the Notepad accessory

  2. Enter the following text:

  3. Save the file as HELLO.REX in the same directory that contains R4.EXE (i.e. c:\r4).

  4. Start a DOS command prompt

  5. At the command prompt enter the two lines shown below:

  6. Type your name at the prompt, then press the Enter key.

  7. The greeting should appear.

  8. You have successfully edited and performed your first r4™ program.

Program examples

An assortment of REXX programs are provided for your reference. A summary of these follows:

Environment variables:

The following environment variables can be specified to customize the execution of r4™ programs. For normal program execution you will not need to define any of these environment variables.

How to define or revise an environment variable,
in Microsoft® Windows® NT/2000/XP

  1. Select 'Settings' of the 'Start' menu.
  2. Select the 'System' applet on the 'Control Panel',
  3. Click the 'Environment' tab.
  4. Locate the variable name in the 'System' or 'User' list if you are revising an existing value.
  5. Or, enter the variable name in the 'Variable' input field.
  6. Type or revise the value of the variable in the 'Value' input field.
  7. Click the 'Set' button.
  8. Click the 'OK' button.

If you have never revised an environment variable, you might ask a friend or colleague who is familiar with this process to help you make this change.

How to define or revise an environment variable,
in Microsoft® Windows® 98 or ME

  1. Edit the C:\AUTOEXEC.BAT file

  2. If you are adding an environment variable, add a line similar to the following:

  3. If you are revising the PATH or R4PATH environment variable, locate a line similar to the following:

    Add the new directory to the path, separating it from other directories by a semicolon.

  4. Save your changes to the AUTOEXEC.BAT.

  5. Then, restart your computer so that the AUTOEXEC.BAT file changes will take effect.

If you have never revised the AUTOEXEC.BAT file, you might ask a friend or colleague who is familiar with this process to help you make this change.

Implementation limits:

r4™ implements TRL-2 language features using values that are generally limited by available Microsoft® Windows® memory. This means that variable names and values can be very large. The NUMERIC DIGITS setting can also be large. The following features are implemented with more finite limits.

  1. The largest C2D result is 18446744073709551615.

  2. The largest D2C numeric argument is 18446744073709551615.

  3. The largest D2X numeric argument is 18446744073709551615.

  4. The largest X2D numeric argument is 'FFFFFFFFFFFFFFFF'x => 18446744073709551615.

  5. File stream accesses are buffered in memory until the r4™ program finishes processing.

    Default input stream and default output stream accesses are not buffered. The 'start' value is not valid for CHARIN and CHAROUT builtin function requests associated with the default input or default output stream. Similarly, the 'line' value is not valid for LINEIN and LINEOUT builtin function requests associated with these streams.

Portability considerations:

  1. The Microsoft® Windows® environment uses text characters that are encoded in the Ascii representation. This differs significantly from the EBCDIC representation that is used on IBM mainframe computers. The following is the character layout of the Ascii representation:

    Ascii table
          0   1   2   3   4   5   6   7   8   9   A   B   C   D   E   F
  00  NUL SOH STX ETX EOT ENQ ACK BEL BS  HT  LF  VT  FF  CR  SO  SI
  10  DLE DC1 DC2 DC3 DC4 NAK SYN ETB CAN EM  SUB ESC FS  GS  RS  US
  20  spc !   "   #   $   %   &   '   (   )   *   +   ,   -   .   /
  30  0   1   2   3   4   5   6   7   8   9   :   ;   <   =   >   ?
  40  @   A   B   C   D   E   F   G   H   I   J   K   L   M   N   O
  50  P   Q   R   S   T   U   V   W   X   Y   Z   [   \   ]   ^   _
  60  `   a   b   c   d   e   f   g   h   i   j   k   l   m   n   o
  70  p   q   r   s   t   u   v   w   x   y   z   {   |   }   ~   DEL
    'spc' indicates a space.
    Entries in this table are determined by taking the two hexadecimal digits at the left hand side of the table, and adding the hexadecimal value at the top of the table.
    The letter X is in the row that starts with 50, and column 8. Thus, the Ascii value of X is hexadecimal 58.
    The letter O is in the row that starts with 40, and column F. Thus, the Ascii value of O is hexadecimal 4F.
    Character values less than hexadecimal 20 are control characters. HT ('09'x) is a horizontal tab, which is commonly referred to as a tab. LF ('0A'x) is a line feed character. CR ('0D'x) is a carriage return.
    'DEL' ('7F'x) is a rubout control character.
    Character values in excess of hexadecimal 7F are extended Ascii characters, these are omitted in the above table because of their effect on HTML browsers. You can execute the ASCII.REX program to view extended Ascii characters.

    Note: uppercase letters are less than lowercase letters in collating order. This can be significant during string comparisons -- i.e. the Compare built-in function, and comparison operators (=, <=, etc.). Consequently, 'Bob' will be considered less than 'bill' when character case is significant.

    The sequence of lower case Ascii characters can be generated by the XRANGE builtin function as follows:

    A text value can be converted to lower case by using the XRANGE and TRANSLATE builtin functions as follows:

  2. Tab characters within text values are problematic, as these have an appearance similar to spaces. The r4™ implementation attempts to treat tabs as equivalent to spaces for most circumstances where spaces have special meaning; such as, the WORD... set of builtin functions. Tabs are also considered equivalent to spaces within the value that is parsed by the PARSE, ARG, and PULL keyword instructions. You can parse for an explicit tab character in the PARSE, ARG, and PULL keyword instructions by specifying '09'x in the parse template.

  3. The standard character that is supported for the not operator is a backslash ('\'). A backslash is the only not operator character that is recommended in Ansi REXX. r4™ also accepts the Ascii code page 37 'AA'x character (¬) as an alternate not-sign character. If you are porting programs to/from mainframe environments, then you should ensure that the mainframe not-sign character ('5F'x) is converted to an Ascii 'AA'x character. You can make this character appear like a not-sign character in your programs if you set your editor's font to OEM Fixed.

  4. A non-standard character that is supported for the not operator is a forward slash ('/'). A backslash is the only not operator character that is recommended in Ansi REXX. r4™ also accepts the forward slash for compatibility with programs written for mainframe environments. The forward slash is only treated as a not operator when used in combination with other comparison operators (see list below). The forward slash is not accepted as a prefix operator.

  5. When the first word of a command is the name of an R4 program, the program is invoked as an external procedure. The remainder of the command line is passed as the first and only argument of the external procedure. For example:
      'execio * diskr INDD (LIFO OPEN FINIS'

    Invokes EXECIO.REX as an external procedure, if EXECIO.REX can be located by a procedure search (R4PATH).


    Observe: if the first word of a command is associated with an .EXE or .BAT file that can be located in any directory (folder) that is defined in the PATH environment variable, then the EXE or BAT file is invoked instead of the external procedure. This avoids a recursion problem that might occur if the REXX external procedure tried to invoke an EXE or BAT file with the same name as the procedure. This problem was reported !

  6. R4 allows an external procedure to begin with the PROCEDURE instruction. This enables exposure of the caller's variables to the external procedure. In addition, the EXPOSEALL keyword is supported on the PROCEDURE instruction.

    The example EXECIO.REX program uses the EXPOSEALL keyword, in order to reference or revise the caller's stem variables.

  7. The TRL-2 book does not specify the following capabilities that are found in some REXX programming environments:
    All of the above commands, except EXECIO, are implemented internally within r4™. The EXECIO command is supported in EXECIO.REX, which is an external procedure that executes as a command.

  8. The positional values associated with the SOURCE option of the PARSE keyword instruction are:

    Note: all of the above values are in UPPERCASE, with the exception of the leading 'Win32' value.

  9. The value associated with the VERSION option of the PARSE keyword instruction is:

  10. Lines that are read by the LINEIN builtin function are terminated when one of the following Ascii character sequences is discovered:

    This allows your programs to easily process text files that are received from other system environments; such as, UNIX, or Linux.

  11. The CHARIN builtin function obtains all character values, including line terminators, exactly as these arrive from the input stream.

  12. The CHAROUT builtin function writes all character values, including line terminators, exactly as these are passed in the string value. Isolated line feed or carriage return characters are not converted to a carriage return THEN line feed sequence, as performed by other programming languages.

  13. When the selector option of the VALUE function is specified, it is interpreted as follows:

  14. Interactive trace requests can not exceed 255 characters.

  15. The only supported address associated with the ADDRESS keyword instruction is:
      'system'
    which is the Microsoft® Windows® system command interpreter.

    Commands sent to the system can include file redirections, and command pipelines. For example:

    As mentioned previously, you should consult Microsoft® Windows® documentation for the use of file redirection and command pipelines.

    When you perform commands, you should make sure that the <, >, and | characters are enclosed within quotes. Otherwise, these will be treated as LESS THAN, GREATER THAN, or OR operator requests.

  16. External procedures are programmed in REXX only -- EXEs are not invoked.

  17. The trace marker >A> indicates variable assignment.

  18. Trace markers >V> and >A> show the associated variable name in square brackets at the end of the trace output line.

  19. R4 supports the special "(stack" command line directive. The end of a command is compared with the characters " (stack", which can include upper case characters. When this special directive is specified, the command's standard output lines are queued to the R4 external data queue.

    Note: the output of the command is redirected to an implicit temporary file. When you use the "(stack" directive, you must avoid using the '>' file redirection operator elsewhere within the command.

    The following is an example of the use of the "(stack" command line directive.

  20. Similarly, R4 supports special "<!queue" and ">!queue" command redirection requests, each of which may include upper case characters. When the "<!queue" directive is specified, contents of the external data queue are passed to the command's standard input stream. When the ">!queue" directive is specified, the command's standard output lines are queued to the R4 external data queue.

    As with the "(stack" directive, implicit temporary files are used for "<!queue" and ">!queue" command redirection requests. You you must avoid using the '<' elsewhere within the command if the "<!queue" directive is specified. And, you you must avoid using the '>' elsewhere within the command if the ">!queue" directive is specified.

    The following is an example of the use of "<!queue" and ">!queue" command redirection requests.

  21. The HALT condition is activated, from the keyboard, by pressing either the Ctrl and the C keys simultaneously, or by pressing the Ctrl and the Break keys simultaneously. There are two Ctrl keys, on either side of the space bar. The Break key is usually near the top right of the keyboard.

    The REXXTRY.REX example shows how the HALT condition can be handled.

  22. When a '1A'X character is written to the default output stream it acts as an explicit end of file character. This is standard operational behavior for Microsoft® Windows® system environments. This impacts output that is written to the console, to a redirected file, or in command pipeline redirections. Subsequent output written to the default output stream is not transferred.

    A '1A'X character can be written to output streams that are associated with disk files. Subsequent output will appear in the disk files.

Environment variable access

The following shows how the VALUE function is used to set and reference environment variable values.

Registry value access

Access to system registry information allows r4™ to prepare and reference information that is used by other system software. This is a powerful capability. However, since system registry information is critical to correct system operation, r4™ can only perform some registry operations. You should be particularly careful when revising registry values. Erroneous revisions can have serious consequences. These changes cannot be undone.

Due to the sensitivity of system registry information, r4™ can only be used to access and revise registry values. The product does not provide capabilities for accessing registry keys directly, and registry keys and values can not be removed. All registry values that are accessed by r4™ must be strings. No other registry value format is supported.

As an extra precaution, registry revisions are only permitted when the R4REGISTRYWRITE environment variable has value: 'Y'. You can locally alter this value, as shown in the example below. No error occurs if this environment variable has not been set.

You are strongly advised to B-A-C-K-U-P the system registry before attempting to revise it with an R4 program.

If you are unfamiliar with the detailed characteristics of the system registry, you should discuss what you plan to do with a business colleague or friend, BEFORE attempting to revise registry information.

Registry values are accessed using a three part name, that has the following structure:
  root\keyPath[valueName]

The keyPath consists of a hierarchy of keys separated by backslashes.

The valueName must be enclosed in square brackets.

The root must be one of the following:
  'HKEY_CLASSES_ROOT'
  'HKEY_CURRENT_USER'
  'HKEY_LOCAL_MACHINE'
  'HKEY_USERS'
  'HKEY_CURRENT_CONFIG'
  'HKEY_DYN_DATA'

The following root aliases are supported:

The following shows how the VALUE function is used to access and revise system registry values.

STREAM builtin function

The implementation of the STREAM builtin function is customized to the Microsoft® Windows® system environment. r4™ supports the following STREAM syntax, that conforms with TRL-2:

name is the name of the item associated with the request, which may be a stream, a file name, a directory name, and so forth.

operation is either Command, Description, or State. All are treated as described in TRL-2.

streamcommand is the name of the stream associated with the request. These are interpreted as described in the table below. The character case of the stream command is insignificant. Thus, chdir, CHDIR, and ChDir are equivalent.

option is optional text associated with the streamcommand.

Supported STREAM commands

The following table summarizes the supported stream commands. You should study the STREAM examples below to gain an improved understanding of these requests.

1 If the CHDIR request succeeds it returns the name of the previous directory associated with the current disk. If the CHDIR request FAILS, it returns the empty string.

If the directory name is absent, the CHDIR request returns the currently active directory associated with the current disk.

2 If the CHDSK request succeeds it returns the name of the previously active disk. If the CHDSK request FAILS, it returns the empty string.

If the disk name is absent, the CHDISK request returns the currently active disk.

3 The DIRS request returns the number of directories that were located. Directory names are stored in the external data queue, and are accessed by using PARSE PULL for the number of directories that were located.

4 If the directory pattern is absent, the DIRS request returns all directories under the active directory.

5 The DRIVE request gets information describing a specific disk drive. The information has the following format.

6 The DRIVES request returns the number of disk drives that were located. Disk drive information is stored in the external data queue, and is accessed by using PARSE PULL for the number of disk drives that were located. Each line of drive information returned by a DRIVES request has the same format as a DRIVE request.

7 The FILEINFO request gets information describing a specific file. The information has the following format.

The fileModificationDateAndTime value is formatted as YYYY/MM/DD-HH:MM:SS

The dirOrSize value is 'DIR' if the file is a directory, otherwise it is the number of bytes withinin the file.

The accessability value is 'RW' if the file is writeable, and 'RO' if the file is read-only.

8 The FILES request returns the number of files that were located. File names are stored in the external data queue. The names can be acquired by using PARSE PULL for the number of files that were located.

9 If the file pattern is absent, the FILES request returns all files under the active directory.

10 The GETKEY request returns a two byte hexadecimal literal associated with a console keystroke; such as, F1, F2, or an arrow key. The values that are returned do not follow a particular pattern. Thus, the following quote is appropriate:

The GETKEY example below provides a simple program that you can use experimentally to determine the values that are returned for specific console keystrokes.

Hint: The first character is '00'x or 'E0'x when a function key, or a special key is pressed.

11 The LINEBREAK option string is formatted as described in the R4LINEBREAK section above.

12 The stream name can be a short MS-DOS 8.3 name of a file or directory. The corresponding long name is returned.

13 The operation of a PURGE request depends on whether the file is currently open or not.

14 A RECYCLE request implicitly fully-qualifies the file name. It is recommended that the file name parameter be fully-qualified. You should also consider prompting before sending files to the recycle bin.

The following values are returned from a recycle request.

15 The short name of a file or directory is in MS-DOS 8.3 format.

STREAM builtin function examples

The following are examples of STREAM builtin function usage. You can copy the text within these examples and paste it into your REXX programs.

Preparing binary programs, with CHILL.REX

There are various occasions when you will want to convert r4™ source programs to binary equivalents, so that others can use your program without being able to see your logic. Some algorithms are copyrighted with provisions that you can distribute them to others as long as the source is unreadable. The CHILL.REX program allows you to do prepare binary programs that can be executed, without associated visible source.

Executing CHILL.REX

The process of converting a REXX program to a 'chilled' binary file is fairly simple. Here are several examples

The .\ice subdirectory contains 'chilled' programs

Chilled programs (aka _ice files) are created in the .\ice subdirectory. Chilled programs have the same name and extension as the original file, with '_ice' added before the extension. For example, if the original program is named:

then, the chilled program will be in the .\ice subdirectory with the following name:

The .\iceSource subdirectory contains source of 'chilled' programs

When a program is chilled it is imperative to retain the corresponding source program. This allows you to debug problems when 'chilled' programs are used on other systems. The corresponding source files are saved in the .\iceSource subdirectory. The saved source programs have the same name and extension as the original file, with a date and time suffix added before the extension. For example, if the original program is named:

then, the saved source file program will be in the .\iceSource subdirectory with the following name:

Saved source files are created with the read-only attribute. This is a precaution to avoid accidental renaming or removal.

Warning: you should backup saved source files files on alternate media .. i.e. CD-ROM.

Log of 'chilled' programs

The CHILL.REX program keeps a log of all requests in file CHILL.LOG. The log file is maintained in the active working directory when CHILL.REX is started. When you need to find which saved source file corresponds with a specific '_ice' file you can locate the associated information in the CHILL.LOG file as follows:

  1. Search for the name of the '_ice' file
  2. Make sure the file date and time match the '_ice' files date and time
  3. The name of the corresponding source file is contained on the same line

Other CHILL.REX considerations

Remarks:

  1. If you are going to use stream output to replace the contents of an existing file, you probably want to ERASE the file beforehand. Otherwise, if the new content is less extensive than the file's prior contents, then some of the prior contents will remain at the end. This phenomenon is quite surprising when you first encounter it.

  2. The MS-DOS® environment supported various escape sequences for changing the screen via the ANSI.SYS driver. Among the escape sequences was the ability to alter the foreground color of text, and the corresponding background color. When text is written to the display (via CHAROUT, LINEOUT, or SAY) r4™ emulates the ANSI.SYS escape sequences that alter text foreground and background color. A text escape sequence is coded as '1B'x (ESC), followed by '[', a series of decimal numbers separated by semicolons, and concludes with a lower case 'm'. The following shows the word Hello with a yellow foreground color, and a black background color.

    The following tables identify the numeric values associated with foreground and background colors.

    The foreground color can be normal or highlighted. A numeric escape value of 1 highlights the foreground text color. For example, the 1 after the '[' turns on highlighting below.

    A numeric escape value of 0 deactivates highlighting. For example, the 0 after the '[' turns off highlighting below.

    No other ANSI.SYS escape sequences are emulated.

  3. The Changestr builtin function is provided for compatibility with other REXX implementations. There are 2 variants of the Changestr function -- ANSI and NetRexx/Roo!™. By default r4™ supports the ANSI variant. The NetRexx/Roo!(TM) variant can be optionally activated by setting the R4_ANSI environment variable to No.

    The syntax of the function variants is:

    The result of the Changestr function replaces all non-overlapping occurrences of needle in haystack with replacement. When needle is the empty string, then the result is haystack.

    The following examples illustrate the operation of the Changestr function. The parenthesized value following the say keyword is the result of the associated Changestr function request. In these examples, only the ANSI variant is illustrated

  4. The Countstr builtin function is provided for compatibility with other REXX implementations. There are 2 variants of the Countstr function -- ANSI and NetRexx/Roo!™). By default r4™ supports the ANSI variant. The NetRexx/Roo!™ variant can be optionally activated by setting the R4_ANSI environment variable to No.

    The syntax of the function variants is:

    The result of the Countstr function counts all non-overlapping occurrences of needle in haystack. When needle is the empty string, then the result is 0.

    The following examples illustrate the operation of the Countstr function. The parenthesized value following the say keyword is the result of the associated Countstr function request. In these examples, only the ANSI variant is illustrated

  5. The Find builtin function is provided for compatibility with other REXX implementations. The function syntax is:

    The Find builtin function is identical in operation to the Wordpos builtin function, with the exception that the string and word arguments are in the opposite order.

  6. The Index builtin function is provided for compatibility with other REXX implementations. The function syntax is:

    The Index builtin function is identical in operation to the Pos builtin function, with the exception that the haystack and needle arguments are in the opposite order.

  7. The Justify builtin function is provided for compatibility with other REXX implementations. The function syntax is:

    The result of the Justify function always returns a string with length: length. There is always at least one word in the result, which might be truncated (as in the first example below). When more than one word is present in the result, the last word is not truncated. Spaces are added between the words as necessary to produce a result that has the requested length. If specified pad characters are added instead of spaces.

    The following examples illustrate the operation of the Justify function. The parenthesized value following the say keyword is the result of the associated Justify function request.

  8. The Linesize builtin function is provided for compatibility with other REXX implementations. The function syntax is:

    The result of the Linesize function is the number of characters per console line -- i.e. 80.

  9. The Qualify builtin function is provided for compatibility with other REXX implementations. The function syntax is:

    The result of the Qualify function is the fully qualified name of streamName, in UPPERCASE. The empty string is returned if streamName is absent, or an empty string.

    The following examples illustrate the operation of the Justify function. The parenthesized value following the say keyword is the result of the associated Justify function request.

  10. The Scrsize builtin function is provided for compatibility with other REXX implementations. The function syntax is:

    The result of the Scrsize function is two numbers separated by a space. The first number is the number of console lines (i.e. 24), the second number is the number of characters per console line (i.e. 80).

  11. The Userid builtin function is provided for compatibility with other REXX implementations. The function syntax is:

    The result is set to: ComputerName/Userid

    The following is an example of the operation of the Userid function. 

        parse value userid() with ComputerName '/' UserName
  say 'Hello' UserName'.'
  say 'Your computer name is:' ComputerName'.'

  • The following commands are performed within r4. The modifications associated with these are effective within r4's execution scope. When r4 returns the prior state is automatically restored.

    The above commands should be properly quoted. Otherwise, backslashes within directory paths are treated as REXX not operators, and the '=' sign in a SET command is a relational operator.

  • The default input stream and default output stream are connected to the standard Microsoft® Windows® files that are identified as stdin and stdout respectively. This allows your REXX programs to operate with redirected files, and participate in command pipelines. Consult Microsoft® Windows® documentation for the use of file redirection and command pipelines.

    The following shows how a COPYFILE program can be used with redirected files:

    The following shows how the lines of the DIR command can be counted:

    The associated programs follow:

  • 'console' is a special stream name. Stream builtin functions that access the 'console' stream interact with the Microsoft® Windows® command console. A single exclamation point ('!') is an abbreviated alias for the 'console' stream.

    The following is a simple program that interacts with the console user:

    Notice that the exclamation point does not require quotes.

  • The CHARS and LINES functions operate differently, depending on whether input is being typed from the keyboard, or received from a file.

    When the default input stream is not redirected from a file (or pipeline), the CHARS and LINES functions both return '1' when more input is available, and '0' when the end of the input stream is encountered.

    When the default input stream is redirected from a file (or pipeline), the CHARS and LINES functions return the actual number of characters or lines remaining in the stream.

    For file streams the CHARS and LINES functions return the actual number of characters or lines remaining in the stream.

    For the 'console' stream the CHARS and LINES functions both return '1' when more input is available, and '0' when the end of the input stream is encountered. The only difference is that the order of the first two arguments is reversed.

  • The MAKEBUF, DROPBUF, NEWSTACK, and DELSTACK commands are builtin into the r4 command environment. These builtin commands are provided for compatibility with other REXX implementations; such as, IBM's MVS TSO and VM implementations. All of these commands have no additional arguments.

    If you are a new REXX programmer you can skip the description of these capabilities.

    With respect to the MAKEBUF, DROPBUF, NEWSTACK, and DELSTACK commands, the external data queue is divided into a sequence of stacks, each of which can contain a sequence of buffers. Initially there is a single stack that contains a single buffer.

    A NEWSTACK command establishes a new stack division within the external data queue.

    A MAKEBUF command establishes a new buffer position within a stack division. Subsequent QUEUE requests will insert lines after a buffer position, but before all other lines within that buffer. A QUEUED builtin function request returns the number of lines that follow a buffer position.

    The following diagram shows how the external data queue is divided into stack divisions and buffers.

    A DROPBUF request removes a buffering position established by a prior MAKEBUF command.

    Similarly, a DELSTACK request removes all lines from the top of the external data queue to a stack division point, only if a prior NEWSTACK division is established. If a prior NEWSTACK division was not established, then a DELSTACK request is ignored -- all lines in the external data queue remain.

    PUSH requests are unaffected by any of these commands. Pushed lines are always added at the last position of the external data queue.

    The MAKEBUF command returns a queue position, which is assigned to the RC variable. This queue position can optionally be passed to the DROPBUF command. The following shows how to use the queue position.

    R4 to EXE transform program (R4XFORM)

    The R4XFORM program allows you to create executable modules (EXEs) that encapsulate your REXX programs. The created modules can then be performed at command prompts, within batch scripts, or DOSKEY macros.

    Usage, R4XFORM:

    The R4XFORM program operates as a standard Microsoft® Windows® application. The following is the syntax of an R4XFORM program request, that is entered as a DOS command prompt.

    Within this line, R4XFORM is a request to execute the R4XFORM program, which has a file name R4XFORM.EXE. You should add the directory that contains R4XFORM.EXE to your system PATH environment variable. See the environment setup section to determine how to revise the PATH environment variable.

    The optional moduleName argument is specified when you want to revise a previously created R4XFORM executable module. Spaces are not permitted in the moduleName argument.

    R4XFORM input fields

    The underlined characters above are accelerator keys. When you hold down the 'Alt' key, and press one of the underlined characters the cursor will move to the associated input field.

    The 'OK' button is disabled until the module name AND the R4 source program AND the working directory field ALL contain text.

    An R4XFORM example

    Here is an example of how to convert an R4 program to an executable module.

    The following is a simple program that shows a greeting.

    After you click the OK button, look in the same directory as the R4XFORM program, and you will observe that a new GREET.EXE file exists.

    Start a command prompt window. Switch to the directory that contains the program. Then enter:


    The following output appears:

    If instead you enter:


    The following output appears:

    How R4XFORM works

    In order to use R4XFORM effectively you need to understand how it works. Perhaps you believe that R4XFORM compiled the REXX program into an executable module. This is not the case. R4XFORM works as follows:

    1. There is a module named TEENSY.EXE that is in the same directory as R4XFORM.EXE. The GREET.EXE file that was created above is a copy of TEENSY.EXE, with a different file name.

    2. The copied TEENSY.EXE module invokes another module called BECOME.EXE that is in the same directory. All of the arguments that were passed to TEENSY are passed onward to BECOME.

    3. R4XFORM prepares registry information which is processed by BECOME.EXE to determine how to perform the GREET program. The registry information is stored with the following keys:

        \\HKEY_LOCAL_MACHINE\Software\Kilowatt Software\Become\GREET

      And,

        \\HKEY_LOCAL_MACHINE\Software\Kilowatt Software\Become\GREET\Environment

      You can use the standard system registry editor to see the information that was created. You can start this program by Selecting 'Run' from the 'Start' menu, and entering the command REGEDIT. Search downwards through the registry tree for the path shown above. You will locate the registry information that was prepared for the GREET program.

    4. BECOME.EXE does the following:
      1. Determines the registry key from the arguments that are passed by GREET.EXE
      2. Acquires the registry information
      3. Establishes the working directory
      4. Prepares environment settings for R4PATH and R4LINEBREAK if these were defined
      5. Prepares the command
      6. Adds the arguments that were passed onward to GREET.EXE to the command
      7. Performs the command

    If you comprehend the above process you will find that you can use the combination of TEENSY.EXE and BECOME.EXE to encapsulate other command shells as well. These two programs are not directly interrelated with r4™ or the R4XFORM program.

    Text file viewing program --Revu™

    r4™ is accompanied by the Revu™ text file viewing accessory. This related product is particularly helpful when viewing Rexx source files. It is similarly useful for viewing C/C++, Java, JavaScript, Perl, XML and HTML files. Click here to study the related Revu™ program.

    Revu™ is implicitly used by r4™ for source presentation during interactive tracing. The current line is continually updated, as the program is debugged. When the program being debugged concludes, the associated Revu™ window is automatically closed.

    Product updates:

    When r4™ is updated, the latest version of R4.EXE and the updated User's Guide R4.HTM can be found in the following internet location:
    http://www.kilowattsoftware.com/latest/

    REXX programming examples may be found in the same location. These are files that have a '.rex' extension.

    Support:

    If you have comments, questions, or concerns regarding r4™ you can send these via e-mail to:

    E-Mail: r4support@kilowattsoftware.com

    Enjoy r4™, and start REXXing !

    Kilowatt Software L.L.C. also offers:
    Poof!™ -- A collection of Microsoft® Windows® command line utilities
    AuroraWare!™ -- A collection of helpful Microsoft® Windows® visual accessories

    REXX Language Level 4.00
    Build date: 5 Jan 2005
    Copyright © 2001-2014
    All Rights Reserved.
    Web: http://www.kilowattsoftware.com/
    E-Mail: r4support@kilowattsoftware.com

    Last updated on: 17 Aug 2013