Introducing Rexx2Nrx:

Exploit the new vision of running classic REXX programs under JAVA!



The new NetRexx language. which has been designed by M.F.Cowlishaw as the successor of the classic REXX language, has some important differences in notation and semantics to the REXX language.

Whilst REXX essentially is a very powerful procedural scripting language, with natural structured statements, NetRexx is a blend of REXX and Java, and fully object-oriented.

Unfortunately, the two languages are NOT upwards compatible: Major language differences include:

REXX stems (ie. Abc.def) have changed their notation and have been replaced by indexed strings (i.e. abc[def]), and need to be defined before their first usage.

NetRexx introduces the capability/necessity to declare variables in front of their usage.

expressions on instruction level are not automatically thrown as COMMANDS to the underlying language command processor.

Hence, whilst the two languages look very similar at the first glance (as they have very similar structured statements available), the language differences in syntax and semantics are significant. Thus, it is not possible to directly use programs written in REXX within NetRexx, as a significant amount of recoding is needed.

The Rexx to NetRexx converter (Rexx2Nrx) has been developed to support you in the task to convert existing REXX programs or program parts to NetRexx. This converter parses your classic REXX program, analyses it, and finally converts it to NetRexx as far as possible.

As an immediate advantage, your classic REXX programs become available to all JAVA platforms, and dont need any platform specific code anymore.



The converter is delivered as a single ZIP-file containing a number of JAVA classes, their corresponding NetRexx source code, and some external control tables which drive the converter.

It is recommended that you put the converter in a separate directory,\Rexx2Nrx\, for instance.

Unpack the Rexx2Nrx.ZIP file as usual using the EXTRACT command of WINZIP. Your \Rexx2Nrx\ directory should now contain the following files:

Rexx2Nrx.doc:  The documentation of the converter  (the doc you are just reading, but with annotated examples).

Rexx2Nrx.bat :  A short batch file invoking the REXX to NetRexx converter, with detailed conversion messages, and implicit NetRexx and Java compilation.

Rx2n.bat :  the short form of Rexx2Nrx, without detailed conversion messages, and with implicit NetRexx and Java compilation, too.

wc.bat: the compact form of Rexx2Nrx ('we compile'). Only Warnings and errors are displayed in this case. 

Rexx.Builtin:  The REXX builtin function definition file

Rexx2Nrx.renames:  A file containing the necessary RENAME rules (as your classic REXX code might use some JAVA reserved words as variable names/labels). Please list this file and adapt it to your needs as necessary.

Rexx2Nrx.jar:  A jar-file containing the run-time package routines, mainly emulations for the classic Rexx runtime-routines not provided by NetRexx. This JAR-file also contains the classes rex_pars  the parser, 'rex_type' - the program analysis and type detection algorithms, and rex_nrx - the actual Rexx to NetRexx converter, as well as some utility routines delivered with the package.

Readme.txt:  the read-me file, which contains some basic instructions as well as a list of known bugs/open issues.


The run-time package provided includes:


RexxStk.class implements the classic REXX Stacking mechanisms (the classic REXX verbs pull, push, queue and the queued() function).

RexxTime.class implements the classic REXX functions Date and Time.

RexxFile.class implements the File-IO routines stream, linein, lineout, lines and chars, charin, charout as defined for classic Rexx, but in an object oriented fashion. Also, a couple of utility methods are provided to open, close, access, delete, etc files. Those methods are used to implement the various functionalities provided by the stream function in classic Rexx. Whilst the original versions of the converter did use Max Marsigliettis RXFile, the whole package has now been re-written from scratch for performance reasons and compatibility to CMS or Risc 6000, for instance. See RexxFile.doc for an accurate docu.

RexxBits.class The Rexx Bits class and associated methods (namely bitand, bitor, and bitxor). These routines are currenlty NOT yet released!

SysCmd.class A number of methods to execute System commands, as well as Rexx, NetRexx, or Java commands.

What to do next

In order to work with the Rexx2Nrx converter, you now have to do 2 steps:

1.) Copy or move the Rexx2Nrx run time package file (Rexx2Nrx.jar) to your JAVA runtime extensions directory, typically called \java\jre\lib\ext , so that NetRexx and JAVA will find the JAVA classes of the converter and the run-time. Altenatively, you may modify your CLASSPATH to directly point to \Rexx2Nrx\Rexx2Nrx.jar.

2.) Modify your PATH variable to include \Rexx2Nrx\, as the converter will need to find

 couple of batch-files and auxiliary files distributed with the package. These files include:

Rexx2Nrx.bat, Rx2n.bat, Rexx.Builtin, Rexx2Nrx.renames.

Otherwise you will have to copy those files to every directory where you are executing

the converter from!


Invoking the converter

The classic REXX to NetRexx converter is usually invoked from the shell with the command

Rexx2Nrx (or 'rx2n' or 'wc' for brevity)

cmd>Rexx2Nrx abc (for the verbose form with detailed conversion messages)

cmd>rx2n abc (for the short form without detailed conversion messages, and with implicit NetRexx and Java compilation)

where abc.rexx (or abc.exec or abc.cmd) contains your source classic REXX program: Note that the filetype (extension) must be ommited, as it is provided automatically. Otherwise the NetRexx Compiler would be invoked with your source Rexx program. Hence, please OMIT the filetype when invoking rx2n.

The file-types rexx, rex, cmd, exec, srx, rexxincl, or rexxpack are searched for the corresponding source file (in this sequence).


Options might be entered in UNIX/Windows style, prefixed by a hyphen, or may be entered in CMS-style (enclosed in parenthesis), for example

cmd>Rx2n modulename binary quiet notime -nostats

cmd>Rexx2Nrx modulename (binary quiet verbose1)

Conversion steps

The conversion is carried out in the following steps:

1.) First, the given file is parsed, and external references are resolved using the Run-Time-package routines and properties when required.

2.) Next, the program is analysed in logical order of execution, and the variable types are determines.

3.) Finally, the actual conversion takes plasce.

Look at the attached system documentation for a couple of examples.

When the classic REXX to NetRexx converter is invoked, a progress report is displayed on the screen. Concurrently, these displays are recorded in the log-file PP.LOG for further inspection. PP.LOG is the general preprocessor log-file used by the converter.

The generated final NetRexx program is put to the associated NRX-file, and optionally compiled using NetRexx and Javac in turn.


A couple of notes are worthwhile:

The converter performs an automatic typing algorithm trying to find the best type for each item. In order to do so, the source code is analysed in logical order of execution, i.e. each local subroutine/function/procedure is analysed at its first potential point of execution. When you use option type, the item-type detected is used to specify the type of each item. You may use option NOTYPE to suppress those typing results (all variables will be of type 'Rexx' in this case). 

For each local subroutine, function, or procedure, a  method is generated implementing the same functionality.

All global variables are defined ahead at the top of the program unit, with their proper NetRexx Type, and a proper initialization value. Note that you may change the proper types used by options short (for short integers) and options binary (see below). Also note, that by default each yet unused variable is initialized to the UPPERCASE variable name by default in classic Rexx, a feature which is NOT available in NetRexx. Those variables are called an Id in the converter.

When necessary, local variables are renamed so that they dont conflict with global variables or function parameters.

When necessary, simple variables are renamed so that they dont conflict with a Rexx stem of the same name (Note, that in classic Rexx a stem may have the same name as a simple variable, which is NOT allowed in NetRexx &)

The same renaming applies, if function names and variable names conflict (note again, that in classic Rexx a function and a variable might have the same name)

To avoid conflicts with Java, all variables with a name identical to a Java reserved word are renamed, in turn. These renames may be tailored by the entries in file Rexx2Nrx.renames, which is provided in a standard form for your usage and/or expansion.

All string literals are analysed and converted to the proper NetRexx syntax when necessary. In particular, as the backslash is an escape-character in NetRexx, all single backslashes are replicated to conform to NetRexx syntax.

All references to qualified variables (stems in classic Rexx) are changed to their proper NetRexx syntax, i.e: abc.def.hig becomes abc[def,hig]

All references to builtin methods (like word, wordpos, etc) become changed in their notation to use the NetRexx object oriented style. Those builtin methods are defined in file Rexx.Builtin, and maybe tailored by you to your specific needs when appropriate.

When classic REXX builtin functions or verbs are used, which dont have an equivalent in NetRexx, than an appropriate emulation is called, e.g.:

QUEUE abc becomes RexxStk. Queue(abc)

PULL abc becomes RexxStk.pull_upper(abc)

Those methods are provided in the Rexx2Nrx.jar file, which is deployed with the package..

Last, not least, the generated code is indented properly to reformat your program nicely for readability. This has, however, the trade-off that the line-numbers will no longer refer to your original Rexx program. Note, however, that the converter is usually invoked only for the conversion process, as many users will like to tune the converted program after the initial conversion effort.

A complete, annotated listing of all items comprising your program and the translations executed is available in the $LIST-file for your inspection, if option LIST is used. Please see again the system documentation for annotated examples.

When builtin functions of classic Rexx are used, those are translated to proper Netrexx emulations. Appropriate import-statements are inserted at the top of the program. The stream-function, for example, belongs to Rexx2Nrx.Rexx2RT.RexxFile. You will also recognize, that proper object oriented methods are used for File I/O, for instance. See RexxFile.doc for a detailed documentation of those routines.

commands, like  @del temp.bin,  are thrown to the SysCmd.cmd routine. A standard version of SysCmd is provided, which emulates some CMS functions like MAKEBUF or DESBUF, for instance. Note, howver, that system commands which are literally notated, are directly converted to the proper Java method when possible, thus eliminating the overhead of a system command.

When you like to support commands from other operating systems, you should enhance the SysCmd routine. (the NetRexx source code is provided as a basis ).

For performance reasons, the charin function uses a default length of 8K bytes, so that 8K bytes are read at once by default to speed things up a bit&

rx2n, the short form of the converter, automatically invokes the NetRexx & Java compiler after successful conversion for you convenience.


Operation modes :


The operation of the converter may be adapted to your needs by a number of options, which should work as close as possible to the equivalent NetRexx options. These options include :

-nologo suppress the LOGO information at the top of each converter step

-notime suppress the timing messages given

-nostats suppress all statistic informations

-type explicitely type all generated Rexx variables

-verbosen set the verbosity of the converter output (n=0 thru 5)

-pause pause after giving a full screen of messages (very similiar to the CMS More ... message). The default is nopause currently, but on quick machines you might not be able to read the messages given anymore. With option pause, the ouput will halt after every full screen of messages for your inspection. But, anyway, those messages are also recorded in the preprocessor LOG-file PP.LOG for later inspection!

-binary generate NetRexx binary code (preceeded by the NetRexx option binary) whenever possible

-strictassign generate NetRexx option strictassign and strict assignment statements.

  • -noformat retain source line numbers (but be careful, you might no longer be able to read the generated NetRexx code). This option is still in an experimental stage (28.8.2001) and not yet fully operable..

  • -nowarn will even suppress warning messages (use with care)

  • -noattention will even suppress attention messages (use with care).

  • -quiet do not display messages on the screen, but do still record them in the LOG-file (file PP.LOG)

  • -list generate a detailed listing of all variables and terms used in your program. The list is written to fn.$LIST for later inspection.

  • As you see, the prefix no switches an option off, to mirror the equivalent NetRexx options as far as possible.


    Current Limitations:

    Due to the inherent differences between Java and classic REXX, it is currently not possible to support a couple of classic REXX features, namely:

  • The INTERPRET statement is not available.

  • SIGNAL ON and CALL ON are not yet implemented.

  • I do hope, that in a concerted approach, a solution for those missing links might be found later, but at the time being, I have found no way to implement those features in Java. Ideas how to overcome these restrictions are welcome, of course !

    Language reference:

    Rexx2Nrx has been implemented based on Mike Cowlishaws book

    The Rexx language - second edition  

     Prentice Hall, ISBN 0-13-780651-5

    with the addition of implementing the %INCLUDE statement. It also should be compatible to the IBM REXX compiler, available for CMS and MVS.

    System requirements:

    The converter should be run on an Intel Pentium with at least 500 MHZ and 128 MB RAM (or a comparable other brand) for appropriate performance.


    Technical support is available thru e-mail. In case of troubles, please send the original source file and the LOG-file of your translation effort (always available in file: PP.LOG) to my current e-mail address:

    Or give me a phone call at:

    0043/1/81102/638 during Austrian office times

    0043/1/955 57 00 during American office times

    Enjoy the new vision of running classic REXX programs under JAVA!


    Thomas Schneider IT-Consulting