• 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:

----> example3

 

Using the Externals utility program:

The  Externals utility program,   may be used to get a listing of all classes/methods/properties contained in a directory or jar file. It uses the class External in course to get access to this Java information.:

cmd>Externals directory -options

   or

cmd>Externals jar-file-name -options

In the default mode (without options) you get a listing of all Java classes in your directory/jar-file, with all method signatures available, the return type, the public properties with their types, an the public methods available.

 

Options for the EXTERNALS utility include:

 

Option	Purpose	Default	Property
MAIN	do show main programs, as well	NOMAIN (see note 1)	show_main=boolean 0
PROPS	do show all (public) properties	PROPS	show_props=boolean 1
METHODS	do show all (public) methods	METHODS	show_methods=boolean 1
LOAD	perform automatic LOADING of all available classes	LOAD	opt_load=boolean 1
PAUSE	pause after full screen	RexxMsg.PAUSE	RexxMsg.opt_pause=boolan 0
XREF	display cross-references	NOXREF	opt_xref=boolan 0
TRACE	trace internal actions	NOTRACE (see note 2)	opt_trace=0
DISPLAY	display results (otherwise process only)	DISPLAY (see note 3)	opt_display=boolean 1 or 0 (see note 3)
SEARCH	search for not yet defined methods and properties in the library given to find the proper class(es) containing this method/property..	NOSEARCH	opt_search=boolean 1
IGNORE	Ignore methods which are always there	IGNORE (see note 4)	opt_ignore = boolean 1

Notes:

1. The option NOMAIN  is the default as your JAR-file or directory may contain a couple of Test-programs. You are normally not really interested to analyse the test-programs, but to see which classes are defined in each library/directory available, which methods are available in each class, and what (public) propertyies each class has for your own usage (you cannot use private properties directlly, but public properties are directly available to You!). 
2. You should only invoke TRACE in case of suspected errors. It will actually trace which methods of the class External are performed to resolve the task in question. Invoking trace is very similar to the NetRexx clause 'trace methods', but may be changed ast RunTime when desired.
3. When the Externals is invoked as a main program (from the command line) option DISPLAY is the default. When, however, the methods of the class External are invoked by another Java Program, NODISPLAY is the default, as you are normally only interested to get the results in core.
4. There are a couple of Java methods which are available in each and every CLASS. Those methods are

            ignore_list='hashCode wait getClass equals toString notify notifyAll'

      Those methods and their properties are deliberately supressed, unless NOIGNORE is in effect.

         

If you click on the button below, you will see an excerpt of

cmd> Externals Rexx2Nrx.Rexx2RT.jar:

     click here  to get the  example JAR-Listing

Thus, you might have a quick look at directories or Jar files to get a short doc of the methods/properties available. Might be useful, when you have no doc available, and also to get a quick glance of the architecture of a given NetRexx/Java application. It might also be useful to document your own application, of course.