The Vienna Version of BSF4Rexx (Beta), 2005-08-24
=================================================
BSF4Rexx, version 254.20050730 ("The Vienna Version of BSF4Rexx")
Please see also the text file "changesBSF4Rexx.txt" which contains important information about
changes (especially to the ooRexx wrapper 'BSF.CLS').
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!)
An earlier revision of this version, "The Vienna Version of BSF4Rexx", got
partly introduced in April 2005 to the Rexx world at the International Rexx
Symposium organized by the Rexx Language Association (cf.
http://www.RexxLA.org) where it was used for enabling ooRexx to automate (remote
control) OpenOffice.org in an openplatform manner.
An 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 "latest" documentation on BSF4Rexx can be found at:
<http://wi.wu-wien.ac.at/rgf/rexx/orx15/2004_orx15_bsf-orx-layer.pdf>
The "Viennese BSF4Rexx" version adds additional functionality, the most notable
addition allows ooRexx programs to address Java fields as if they were Object
Rexx attributes, as well as supplying the functions box() and unbox() to wrap
and unwrap primitive datatypes into/from their corresponding Java class (e.g.
needed for setting property values in OpenOffice.org - OOo).
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:
Linux (Intel), OS2 and Windows.
Files and Archives
==================
readmeBSF4Rexx.txt ... this text file
changesBSF4Rexx.txt ... text file containing a record of the most
important changes
bsf4rexx-apache-bsf.jar ... Apache version of BSF (Bean Scripting Framework)
and matching Rexx engine for BSF; point to it
via CLASSPATH; needs Java 1.2 or higher
bsf4rexx-bin.zip ... Binaries: Linux-, OS2- and Windows-DLLs; BSF.CLS - the
ooRexx support camouflaging Java as ooRexx
bsf4rexx-docs.zip ... HTML-documentation (created from the Apache version)
bsf4rexx-ibm-bsf.jar ... IBM version of BSF (Bean Scripting Framework)
and matching Rexx engine for BSF; point to it
via CLASSPATH; supports Java 1.1 (OS2!)
bsf4rexx-samples.zip ... archive containing numerous examples that should
work unchanged on all operating system platforms
bsf4rexx-sources.zip ... archive the Java and C++ sources for BSF4Rexx
bsf4rexx-test.zip ... archive containing numerous tests
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 have a supported Rexx interpreter installed, this version
recommends the opensoure, openplatform interpreter "ooRexx" available via
"http://www.ooRexx.org".
rexx -v
2) Installing the binaries
--------------------------
In this section the path "x:\full\path\to\bsf4rexx\" (Linux: "/full/path/to/bsf4rexx")
is assumed to point to the directory into which you have unzipped the archives above
and copied the jar-files to.
Unzip "bsf4rexx-bin.zip", its files will be stored in a directory named "bin".
Depending on your operating system copy "bin\linux\libBSF4Rexx.so", "bin\os2\BSF4Rex.dll",
"bin\windows\BSF4Rexx.dll" to the "bin" directory. (Just that everyone has the DLL in
the same place where "BSF.CLS" resides, see below.)
Make sure that the environment variable "PATH" points to the directory
"x:\full\path\to\bsf4rexx\bin" where "BSF.CLS" is located, such that ooRexx can
find the file.
For Java you need to point the "CLASSPATH" environment variable either to the
jar-file "bsf4rexx-ibm-bsf.jar" (if you use Java 1.1 or IBM WebSphere) or
"bsf4rexx-apache-bsf.jar" (if you use Java 1.2 or higher).
Further installation hints:
under OS/2 (eCS) or Windows:
set CLASSPATH=%CLASSPATH%;x:\full\path\to\bsf4rexx\bsf4rexx-apache-bsf.jar;.
or
set CLASSPATH=%CLASSPATH%;x:\full\path\to\bsf4rexx\bsf4rexx-ibm-bsf.jar;.
and in addition:
set PATH=%PATH%;x:\full\path\to\bsf4rexx\bin
and under OS/2 in addition ("BSF4Rexx.dll"):
set LIBPATH=%LIBPATH%;x:\full\path\to\bsf4rexx\bin
Also make sure that "PATH" contains the directory where the Java VM ("jvm.dll")
can be found, eg: "C:\Program Files\Java\jre\bin\client", if you have the runtime
version of Java installed and Windows is installed on drive c:. (This will allow
Rexx to be able to start Java, if necessary!)
Alternatively, you can download a Java SDK from Sun (cf. http://java.sun.com)
and use the path to the "PATH2SDK\jre\bin\client", where "PATH2SDK" is the path
to where you installed it.
under Linux (bash):
set CLASSPATH=$CLASSPATH:/full/path/to/bsf4rexx/bsf4rexx-apache-bsf.jar:.
or
set CLASSPATH=$CLASSPATH:/full/path/to/bsf4rexx/bsf4rexx-ibm-bsf.jar:.
and in addition:
set PATH=$PATH;/full/path/to/bsf4rexx/bin
(Note the trailing dot, which tells Java to also include the active directory in
its search for Java classes.)
Further remarks on the Linux installation
-----------------------------------------
The following briefly explains how you can successfully set up Java and BSF4Rexx
in a Red Hat (Fedora Core 3) environment. It is assumed that you created
"bsf4rexx" in your home, so "~/bsf4rexx" can be in this example to refer to it.
In this example it is assumed that you run as user "root", so replace that name in
path names with your own userid, usually "/home/your-userid".
- install ooRexx, which you can get via <http://www.ooRexx.org>
- install a Java SDK, in this example it will be Sun's Java SDK, version; this
example assumes that we are using "j2sdk1.4.2", replace it with the name of your
version.
export CLASSPATH=~/bsf4rexx:.
export PATH=$PATH:~/bsf4rexx/bin
ln -sf /usr/java/j2sdk1.4.2/jre/lib/i386/* /usr/lib
ln -sf /usr/java/j2sdk1.4.2/jre/lib/i386/client/libjvm.so /usr/lib
ln -sf /root/bsf4rexx/bin/libBSF4Rexx.so /usr/java/j2sdk1.4.2/jre/lib/i386/libBSF4Rexx.so
ln -sf /root/bsf4rexx/bin/libBSF4Rexx.so /usr/lib/libBSF4Rexx.so
ln -sf /usr/java/j2sdk1.4.2/bin/* /usr/bin
# --- optional ---
ln -sf /usr/java/j2sdk1.4.2/jre/bin/java /usr/local/bin/java
Hint for Java (all platforms)
-----------------------------
If you copy either "bsf4rexx-apache-bsf.jar" or "bsf4rexx-ibm-bsf.jar" to
"%JAVA_HOME%\lib\ext" (Windows) or "$JAVA_HOME/lib/ext" (Unix) makes those
classes availabe to Java (no need to specify them on the CLASSPATH variable
anymore)!
Java will always look through the jar-files found in that particular directory.
3) "rexxj", "rexxji" and "BSF.CLS"
----------------------------------
The following batch files allow to load/start Rexx programs via Java using
Apache's BSF (dubbed "BSF version 2.3" or higher, needs Java 1.2 or higher):
rexxj.cmd ... Windows
rexxj.sh ... Linux
The following batch files allow to load/start Rexx programs via Java using
IBM's BSF (dubbed "BSF version 2.2", allows using Java 1.1)
rexxji.cmd ... eCS resp. OS/2, Windows
rexxji.sh ... Linux
The following Object Rexx program allows Object/ooRexx programmers to treat all
of Java as a huge Object Rexx class tree and all Java objects as if they are
Object/ ooRexx objects:
BSF.CLS ... all operating systems
4) 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/ ooRexx:
rexx testVersion.rex
5) 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; if someone
is interested in turning these tests into the new ooRexx TestUnit-format
please contact the author or post on the RexxLA-list or news:comp.lang.rexx
bsf4rexx-sources.zip
... source of BSF4Rexx.cc and of the Java Rexx engine
7) Support and questions
------------------------
Please use the main Rexx newsgroup to post questions, example code etc.:
news:comp.lang.rexx
[Members of the Rexx Language Association (http://www.RexxLA.org) can use
the private RexxLA listserver list.]
Good luck and have fun!
... and please tell us what you are using it for such that others may learn of
interesting problem solving applications with this technology.
Rony G. Flatscher
University of Economics and Business Administration (Wirtschaftsuniversitaet Wien, "WU")
2005-08-25
---
Hints:
- In order to use Java as a huge external [oo]Rexx function library you
merely need to have the "Java runtime environment (JRE)" installed on your
machine. Probably it is installed already, due to support Java applets via
your WWW-browser. Otherwise you can download and install Java from:
<http://java.sun.com>.
- You can download the Java API documentation from Sun's Java site. The
documentation is merely a set of plain HTML documents that are linked with
each other. Alternatively, it is possible to point your WWW browser directly to Sun's
Java WWW pages offering the very same documentation:
<http://java.sun.com/docs/index.html>
... Overview page which allows you to choose which Java version's docs you
want to browse, e.g. as of 2005-06-04 the following "J2SE API Docs" were
accessible:
<http://java.sun.com/j2se/1.3/docs/api/index.html> ... Java 1.3
<http://java.sun.com/j2se/1.4.2/docs/api/index.html> ... Java 1.4
<http://java.sun.com/j2se/1.5.0/docs/api/index.html> ... Java 1.5 aka Java 5.0
The overview URL also contains plenty of links to tutorials and other
valuable Java info material.
------------------------------------------------------------
Old news, but maybe still noteworthy:
ATTENTION - all NEW BEHAVIOUR!
- starting with version 250.20050602 you can get and set fields of Java objects
as if they were ooRexx attributes; if the case of the field names is significant
you need to use the "strict" BSF4Rexx functions/methods to get/set fields in
Java objects
- by default only the org.apache.bsf (cf <http://jakarta.apache.org/bsf/index.html>)
and ooRexx (cf <http://www.ooRexx.org> are supported; the Makefiles allow for
using com.ibm.bsf and other Rexx interpreters like Regina;
- 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, very useful in rare
circumstances)