ATTENTION - all NEW BEHAVIOUR!
- starting with version 200.20030510 you must not supply any type information
- should you need strict typing, then use invokeStrict, registerBeanStrict instead
(these allow the supplying of old style type information)
- all samples have been adjusted and tested with Regina 3.2 and Object Rexx 2.1.2
on Windows!
(As a result all those examples should be *much* easier to read and
to comprehend!)
BSF4Rexx, version 200.20030430, 201.20030530 ("The Augsburg version")
=====================================================================
BSF4Rexx is a package which allows Rexx interpreters to be used with the BSF (Bean
Scripting Framework), originally developed by IBM and since fall 2002 under the
control of Apache (cf. Jakarta project on http://jakarta.apache.org).
Brief overview
==============
BSF allows Java programs to call (invoke) script programs written in languages
other than Java. Such script programs are also able to call back into Java and
use all of Java's classes and objects.
- Hence, any Java application can use (Object) Rexx as a scripting language
- Hence, (Object) Rexx can use Java as a huge, operating system independent
function library. (The Object Rexx support enabled with "BSF.cls" makes Java
look like a huge Object Rexx class library!)
This version, "The Augsburg Version of BSF4Rexx" got introduced in May 2003 to
the Rexx world at the International Rexx Symposium organized by the Rexx Language
Assocation (cf. http://www.RexxLA.org).
The according overview article (dated: 2003-06-01) with short examples can be
found at:
<http://wi.wu-wien.ac.at/rgf/rexx/orx14/orx14_bsf4rexx-av.pdf>
(and for the forerunner at:
<http://wi.wu-wien.ac.at/rgf/rexx/orx12/JavaBeanScriptingWithRexx_orx12.pdf>).
The "Augsburg BSF4Rexx" version adds additional functionality introduced at the 2003
International Rexx Symposium for the first time to the public. The most notable addition
allows Rexx programs to invoke Java and thereafter use all of Java as if it was an
incredible huge and portable (ported) external Rexx function library! The logic is
implemented such, that the BSF infrastructure is used for allowing this support.
In addition, as a result of the discussions at the 2003 International Rexx symposium
the removal of strong typing from Rexx was implemented right away, instead of taking
time until the next symposium. This makes the invocation of Java methods from Rexx
remarkable simple and Java easy to use from Rexx.
All Rexx programs using BSF4Rexx are per se fully portable, ie. to any system which
possesses Java and a Rexx interpreter, provided that the JNI DLL/shared library is
ported to that platform (the source file to be ported/compiled is "BSF4Rexx.cc").
Out of the box the following operating systems are supported: eComStation and OS/2,
Linux (Intel), Windows.
Files and Archives
==================
readme.txt ... this file
bsf4rexx_samples.zip ... Rexx examples (short programs, *HIGHLY* recommended to look at!)
bsf4rexx_test.zip ... Rexx test programs (stressing some specific features of BSF4Rexx)
bsf4rexx.jar ... the Java archive of BSF 2.2 (IBM's version)
bsf4rexx-apache.jar ... the Java archive of BSF 2.3 (Apache's version)
bsf4rexx_bin.zip ... the compiled DLL/shared JNI libraries for Linux,
OS/2 (eComStation), Windows; some utility batch files
bsf4rexx_src.zip ... source code of the C++ JNI program ("BSF4Rexx.cc") and
make-files
bsf4rexx-src.jar ... the Java source code of IBM's version (BSF 2.2)
bsf4rexx-src-apache.jar ... the Java source code of Apache's version (BSF 2.3)
bsf4rexx_javadocs.zip ... javadocs (all in HTML-files) for the Java programs
bsf4rexx_javadocs_apache.zip ... javadocs (all in HTML-files) for the Java programs
Installation
============
1) General: Java and Rexx installed
-----------------------------------
You need to have Java installed and be able to use the executable called "java":
java -version
You need to hava a supported Rexx interpreter installed (Regina, Object Rexx,
any other Rexx interpreter which is supported by RexxTrans, cf.
<http://www.lightlink.com/hessling/>):
rexx -v
or
regina -v
2) "bsf4rexx.jar" ("bsf4rexx-apache.jar")
-----------------------------------------
You need to use the Java archive called "bsf4rexx.jar", as this archive includes
the Rexx support code. (Java archives can be viewed/manipulated also with any
popular zip-archive program.)
Java uses the environment symbol CLASSPATH to look for Java classes, also for
such Java archives, hence you need to add/define the path to "bsf4rexx.jar" as
part of this Java-needed CLASSPATH environment variable, e.g.
under eComStation resp. OS/2, Windows:
set CLASSPATH=x:\full\path\to\bsf4rexx.jar;.
under Linux (bash):
CLASSPATH=/full/path/to/bsf4rexx.jar:.
(Note the trailing dot, which tells Java to also include the active directory in
its search for Java classes.)
If using the Apache version then use its name instead (e.g. "bsf4rexx-apache.jar").
3) The Java Native Interface (JNI) DLL/shared library ("bsf4rexx_bin.zip")
--------------------------------------------------------------------------
"BSF4Rexx.dll" (eCS, OS/2, Windows) resp. "libBSF4Rexx.so" (Linux) is the bridge
between Java and Rexx, written in C++ and compiled for eCS resp. OS/2, Linux and
Windows. The binaries are in the archive "bsf4rexx_bin.zip".
Should you need it compiled for a different platform, you may do so by
compiling the source of it ("BSF4Rexx.cc") in the source archive "bsf4rexx_src.zip".
The distribution will have a few versions pre-compiled. You need to choose the
appropriate DLL/shared library and copy it under the name "BSF4Rexx.dll" or
"libBSF4Rexx.dll". Here's a possible list of supplied precompiled DLLs/shared
libraries:
eComStation resp. OS/2:
=======================
many OS/2 customers still have Java 1.1.8 in use, hence there is a special
version for 1.1.8 available; starting with Java 1.2 the JNI-interface can
be used a little bit different and "future safe"
BSF4Rexx_118.dll ... Java 1.1.8 *ONLY*
BSF4Rexx_130.dll ... Java 1.2 (sic!) and up (created and tested with 1.3,
should work with 1.4)
BSF4Rexx_118-apache.dll ... Java 1.1.8 *ONLY*
BSF4Rexx_130-apache.dll ... Java 1.2 (sic!) and up (created and tested with 1.3,
should work with 1.4)
E.g. using Object Rexx under eComStation resp. OS/2 with Java 1.2 or higher you
would copy:
copy BSF4Rexx_130.dll BSF4Rexx.dll
Linux:
======
libBSF4Rexx_OREXX.so ... uses the Object Rexx interpreter only
libBSF4Rexx_REGINA.so ... uses the Regina Rexx interpreter only;
NOTE: needs Regina 3.2 (available since
April 25th, 2003) or later!
The following DLLs will interface with Apache's BSF:
libBSF4Rexx_OREXX-apache.so
libBSF4Rexx_REGINA-apache.so
E.g. using Regina under Linux with the Apache version of BSF you would copy
(of course you could also create a symbolic/hard link with the name
"libBSF4Rexx.so"):
cp -p libBSF4Rexx_REGINA-apache.so libBSF4Rexx.so
Windows:
========
BSF4Rexx_REXXTRANS.dll ... allows any supported Rexx interpreter,
including Object Rexx and Regina; rexxtrans
will search for all supported Rexx interpreters
and use the first one it finds; you can use the
environment variable "REXXTRANS_INTERPRETER"
to force the usage of a specific Rexx interpreter
(e.g. "objectrexx", "regina", etc.)
-- in this case you need to copy "rexxtrans.dll" to
the same directory you copy "BSF4Rexx.dll" to
BSF4Rexx_OREXX.dll ... uses the Object Rexx interpreter only
BSF4Rexx_REGINA.dll ... uses the Regina Rexx interpreter only
The following DLLs will interface with Apache's BSF:
BSF4Rexx_REXXTRANS-apache.dll
BSF4Rexx_OREXX-apache.dll
BSF4Rexx_REGINA-apache.dll
E.g. using Object Rexx under Windows you would copy:
copy BSF4Rexx_OREXX.dll BSF4Rexx.dll
Depending on your operating system and Java runtime environment you need to copy
this DLL/shared library (used by Rexx *and* Java!) to the following directories:
eComStation resp. OS/2:
-----------------------
- Copy "BSF4Rexx.dll" to any directory which is in the environment variable
called "LIBPATH".
Linux:
------
- Copy (create a symbolic link maybe) to "/usr/lib" or any other directory
Linux looks for shared libraries. This way Rexx can locate and load this
shared library, if needed.
- Copy (create a symbolic link maybe) to one of the directories where
Java looks for shared libraries. Usually, this will be the directory
underneath the Java runtime environment "*/jre/lib/Intel386/".
If you cannot locate this directory or are unsure which directories are
searched by Java, then you can execute the supplied pre-compiled Java
program by issuing:
java QueryProperties
This will first display the value of the Java property named "java.library.path",
showing all directories Java will search for shared libraries. (Thereafter all
Java properties are dumped for informational purposes.) Choose one of the
directories to place the shared library "libBSF4Rexx.so". This will allow Java
to load this library and interface with Rexx.
Windows:
--------
- Copy "BSF4Rexx.dll" into one of the directories given in the PATH environment
variable
4) "rexxj", "rexxja" and "BSF.cls"
----------------------------------
Copy the following programs to a directory which gets searched for (one which is
defined in the environment variable called PATH):
The following batch files allow to load/start Rexx programs via Java using
IBM's BSF (dubbed "BSF version 2.2"):
rexxj.cmd ... eCS resp. OS/2, Windows
rexxj.sh ... Linux
The following batch files allow to load/start Rexx programs via Java using
Apache's BSF (dubbed "BSF version 2.3 and higher"):
rexxja.cmd ... eCS resp. OS/2, Windows
rexxja.sh ... Linux
The following Object Rexx program allows Object Rexx programmers to treat all
of Java as a huge Object Rexx class tree and all Java objects as if they are
Object Rexx objects:
BSF.cls ... all operating systems (note the case under Linux!)
5) Testing your BSF4Rexx installation
-------------------------------------
Issue the following command from the command line for IBM's BSF:
rexxj testVersion.rex
... this will first load Java, then have the Java program initialize the
scripting support, loading the BSF4Rexx DLL or shared library and handing
the Rexx interpreter the program "testVersion.rex" for execution. If everything
goes well, you should see the name and version of the Rexx interpreter, the
version of the DLL/shared library and the version of the Java Rexx supportive
code.
Issue the following command from the command line for Object Rexx:
rexx testVersion.rex
Issue the following command from the command line for Regina version 3.2:
regina testVersion.rex
6) Further infos
----------------
There are archives containing sample programs written in Rexx demonstrating
what can be done with BSF4Rexx.
bsf4rexx_samples.zip
... contains numerous examples in Rexx (and some in Object Rexx) to
show some features possible with BSF4Rexx; *HIGHLY* recommended, short
programs a *lot* to be easily learned from!
bsf4rexx_test.zip
... contains Rexx test programs to stress test specific features
bsf4rexx_src.zip
... source of BSF4Rexx.cc with all needed files to compile it
7) Support and questions
------------------------
Please use the main Rexx newsgroup to post questions, example code etc.:
news:comp.lang.rexx
Good luck and have fun!
Rony G. Flatscher
University of Economics and Business Administration (Wirtschaftsuniversitaet Wien)
University of Augsburg (Universitaet Augsburg)
2003-06-01
Download Latest Version
BSF4Rexx-apache-bsf-source.jar (405.8 kB)
