The Externals utility

Rexx2Nrx.Rexx2RT.External (vs 4.00, January 2003)

Introduction:

The class External is used by the Rexx2Nrx translator to resolve references to external functions and variables (called public methods and properties in NetRexx and Java).

The Externals utility program gives you access to this information from the cmd line.

A bit of history:

Functions/Subroutines, which correspond to an existing label in a classic Rexx program, are called internal functions. They consequently have the scope 'Internal' in Rexx2Nrx.

Classic Rexx, however, does allow you to use builtIn and external functions/routines as well. The calling sequence itself does not indicate, whichever scope the invoked function has. It may still be Builtin or External. In addition, those BuiltIn functions fall into one of two choices in the NetRexx language:

BuiltIn functions, which are available as methods in NetRexx (but use a different, object oriented notation). Good examples of those are the functions/methods word, wordpos, words etc.

classic Rexx Builtin functions, which are NOT available in Netrexx per se. Examples for those are simple functions like date(x), time(x), but also File I/O like stream(...), lines, linein, lineout, etc. Those routines are implemented in the Rexx2Nrx RunTime package (Rexx2Nrx.Rexx2RT), both in a function oriented and object oriented way where appropriate. The RunTime docu contains a full documentation of the functions(methods) available, and how those functions have been grouped into meaningful classes.

The third choice is that you have written your own 'external' functions. With the IBM REXX compiler, those functions may reside in external files, and are included by the %INCLUDE directive (which is denoted as a comment in the case of the IBM REXX compiler)

Hence

/*%INCLUDE strfun */

seaches for an 'externally stored' file 'strfun', where the filetype may be any of

    EXEC            (CMS REXX EXEC file)

    REXXINCL     (CMS REXX INCLUDE file)

    ... see the IBM REXX Compiler docu for the full set of filetypes available

The included file may actually contain multiple labels again, and each label may be used as a function/subroutine by the calling program.

The IBM Rexx Interpreter, however, does simply IGNORE those %INCLUDE directives (as it regards them as comments!). Don't ask me why this decision has been made ...

But the IBM REXX Interpreters automatically attempt to look for the external routines in a file with the same name (and filetype EXEC, in the CMS case). Obviously, each file might contain only 1 externally callable function in this case, and this must be the first one in the file to get executed,

The Rexx2Nrx Converter supports the %INCLUDE directive with the same semantics like the IBM REXX Compiler - unless a Java class file for this name is already available.

When the Java class file is already available, the %INCLUDE is ignored with an info message, and the precompiled Java class is used instead. That class is then used in turn, with all her methods and public properties accessible by the calling program.

The class External (implemented in Rexx2Nrx.Rexx2RT.External), is used for this purpose..

In order for this process to work correctly, you have to Convert the formerly included files BOTTOM UP, and all Java classes must reside in your current working directory. We will see later how you can group those Java classes into .jar-files using the Java jar utility program.

A simple example will show you the advantages of this technique:

----> BottomUp1

Please note that you may also invoke the different medhods of Class External by the Externals utility program available in Rexx2Nrx.