'bsf4rexx'-Package ('http://nestroy.wi-inf.uni-essen.de/Forschung/rgf/')
------------------
This package roots in a seminar paper done by Peter Kalender under the
assignment and supervision of Rony G. Flatscher at the University of Essen
(http://www.Uni-Essen.de) in the winter semester of 2000/2001.
In April Rony G. Flatscher re-worked, re-wrote and enhanced the functionality
in order to allow Rexx and Object Rexx become an additional scripting
language of IBM's free and open sourced 'Bean Scripting Framework' (BSF).
This work was also created for the presentation on the '12th International
Rexx Symposium' of the 'Rexx Language Association', Research Triangle Park,
N.C., in May 2001. (cf. 'http://www.RexxLA.org')
BSF allows Java programs to invoke scripts (even written in non-Java
languages) or to call them as functions, returning values to Java. Once a
script is active, the BSF allows for calling back into Java and interact with
Java objects.
There are two packages available:
========================== package # 1 ==================================
1) 'mega_BSF4Rexx.zip' for people having no IBM BSF 2.2 so far and wanting
it easy on them (SUGGESTED!):
-----------------------------------------------------------------------
- unzip 'megaBSF4Rexx.zip' and you'll get
- bsf2_2rx.jar ... copy of IBM's BSF 2.2 with Rexx engine included;
add the full path to this file (including the
filename with extension!) to your CLASSPATH
environment variable; that's all you need and
you are set !
(BTW, JAR's - Java archives - are basically ZIP-
archives)
- rexx/bin/ ... subdirectory containing an Object Rexx
wrapper class ('BSF.cls') to be put into the
PATH; you need this, if executing the supplied
Object Rexx sample programs (contain 'oo' in
their file names)
- rexx/bin/linux ... the Linux shared libraries (Object Rexx, Regina),
to be renamed to 'libBSF4Rexx.so' and put either
into '/usr/lib' or added to the environment
variable 'LD_LIBRARY_PATH'
- rexx/bin/os2 ... the OS/2-DLL (Rexx, Object Rexx) to be put
into the LIBPATH
- rexx/bin/win32 ... the Windows-DLLs (for Object Rexx, Regina,
RexxTrans) to be renamed to 'BSF4Rexx.dll' and
put into the PATH
- rexx/test.zip ... contains various test programs, highlighting
different aspects of this package
- rexx/samples.zip ... contains the BSF 2.2-samples with the additions
of Rexx counterpart samples where appropriate;
contains pure Rexx and Object Rexx samples
demonstrating what this package can do (in
addition it contains those IBM supplied BSF
examples for which I wrote Rexx and Object Rexx
counterparts)
- rexx/docs.zip ... contains the documentation of the Java classes,
the "RexxAndJava" documents the available subfunctions
available to Rexx
- rexx/source.zip ... contains the source files of this package, i.e.
the Java programs, the C++ file and the makefiles
========================== package # 2 ==================================
2) 'pure_BSF4Rexx.zip' for people having IBM BSF 2.2 installed already or
wishing to do so by hand (for whatever reasons;):
-----------------------------------------------------------------------
Pre-requisites:
---------------
- Java: you need Java installed at your machine (at least the Java runtime
environment, 'JRE', eg. look at 'http://http://www.sun.com/java')
version 1.1.x or later,
- BSF: IBM's 'Bean Scripting Framework' (BSF), version 2.2 (March 2001),
because of packaging changes from 2.1 (com.ibm.cs.* moved to the
com.ibm.bsf.* branch)
(cf. 'http://oss.software.ibm.com/developerworks/projects/bsf')
- 'bsf4rexx': this package
(maybe at 'http://nestroy.wi-inf.uni-essen.de/Forschung/rgf/Entwicklung.html')
Setting up your environment
---------------------------
install IBM's BSF:
- unjar/unzip the 'bsf.jar' file ('Java Archive Files' can be dealt
with 'jar.exe' or 'zip'-archivers), if not already available in an
expanded form; a subdirectory structure is created like '.\com\ibm\bsf\...'
- set the 'CLASSPATH' variable to point in to the (sub)directory
where the entry 'com' is located
install 'bsf4rexx':
- install 'bsf4rexx' by unzipping it in the same directory where the 'com'
entry is located; it will create a directory '.\com\ibm\bsf\engines\rexx'
and therein subdirectories 'docs', 'source_cc', 'source_java', 'samples'
and 'test'.
- edit the file '.\com\ibm\bsf\Languages.properties' with a text editor and
add (if not there already) the following line:
rexx = com.ibm.bsf.engines.rexx.RexxEngine, rex | cmd | cls | rexx
this will allow BSF to automatically choose the RexxEngine based on the
file extension; this feature of BSF is used in the Java-program
'.\com\ibm\bsf\Main', which allows to start scripts and programs in any
of the supported languages
- add the absolute path of '.\com\ibm\bsf\rexx' to the environment variable
'PATH'; this allows Object Rexx to find the supporting Object Rexx class
'BSF.cls' to be found by Object Rexx programs (this allows to use the
OO-features of Object Rexx in a much easier way)
- Windows: add the absolute path of '.\com\ibm\bsf\rexx\win32' to the environment
variable 'PATH'; this allows Windows to find the dynamic link
library 'BSF4rexx.dll'. If you did that already to allow for adding
specialized Object Rexx support, then skip this step.
- If you are using IBM's Object Rexx for Windows
(cf. 'http://www2.hursley.ibm.com/netrexx'), then rename
'BSF4Rexx.dll.orexx' to 'BSF4Rexx.dll'
- If you are using the free Rexx interpreter 'Regina' for Windows
(cf. 'http://www.lightlink.com/hessling/'), then rename
'BSF4Rexx.dll.regina' to 'BSF4Rexx.dll'
testing your installation
- change into the directory '.\com\ibm\bsf\engines\rexx\test' and issue one
(or all) of the following commands:
- 'java TestSimpleExec' ... this Java program invokes Rexx, if everything
worked, then 'Rexx was here!' is returned
- 'tst_exec' ... will execute the Rexx statements in 'input.txt'
- 'tst_eval' ... will evaluate the Rexx statements in 'input.txt'
and using the Rexx result string
- 'UseTest' ... this batch file will load the Rexx program
'UseTestRGF.rex', which interacts with the
Java class 'TestRGF', creating objects,
invoking the Java methods, reading and
setting field values
- 'java TestCallRexx' ... this Java program contains a Rexx program
which gets called with Java-supplied
arguments; the Rexx program will dump the
received Java arguments and return a string
value displayed by the Java program
learning more
- use IBM's BSF infos/docs as well as the ones from 'bsf4rexx' in the
subdirectory 'docs' (just point your browser to the file 'index.html')
- look at the samples in the subdirectory 'samples'; NOTE: most of the
samples were translated 1:1 from classic Rexx to Object Rexx; therefore
they may serve as little tutorials on Object Rexx as well
- there is another subdirectory containing Rexx examples of the samples
supplied by IBM with BSF 2.2
========================== further remarks ==============================
some little remarks on Java
- Java *is* case sensitive on *any* platform, i.e. 'testrexxcall' is
*different* to 'TestRexxCall' on DOS, Linux/Unix, Mac, OS/2,
Windows 3.1/95/98/ME/NT/2000/?
- Java programs are platform independent; you may get the source files
(file type usually '.java') and/or the compiled files (file type usually
'.class'); if you got the source files only, then it is very easy to
compile them with:
javac *.java
This will invoke the java compiler and compile all files according to the
pattern (in the above example all files with the extension '.java'). The
compiled files will *always* have the extension '.class'.
- Invoking a compiled Java program is fairly easy as well, e.g.
java TestRexxCall
will load the file 'TestRexxCall.class' (note that the invocation must
not have a file extension!) and execute it
- On the 'CLASSPATH' variable: the directories given in this environment
variable serve Java as the only starting points for seeking compiled Java
classes; sometimes zip-files, called 'Java Archives' (file-endings '.jar')
containing compiled classes, are given too. The content of such archives
is treated as if it was part of the directory and may include subdirectory
entries as well.
If Java programs refer to Java classes by full name, i.e. include path
information, then the delimiter is a dot and not a (back-) slash, e.g.
the relative path to 'com/ibm/bsf/BSFEngine.class' or
'com\ibm\bsf\BSFEngine.class' can be referred to in Java programs as
'com.ibm.bsf.BSFEngine'.
In the above example, if the absolute path to 'BSFEngine.class' was
'G:\great\stuff\com\ibm\bsf\BSFEngine.class' then the CLASSPATH environment
variable must have an entry 'G:\great\stuff\' in order for Java to find
the class at runtime.
If everything was moved into a Java archive (can be created with a
zip-archiver as well), e.g. named 'G:\great\stuff\bsf.jar', then the
CLASSPATH environment variable must have an entry 'G:\great\stuff\bsf.jar'.
Further questions, remarks
- please direct your questions remarks to the Rexx and Object Rexx
newsgroup:
news:comp.lang.rexx
Credits:
- Mark Hessling from Australia, author of numerous great Rexx function
packages and maintainer of Regina, a great open source and free Rexx
interpreter see his great site at:
http://www.lightlink.com/hessling/
- John Small from the USA, who helped out in creating the first beta
OS/2 DLL and helped to quality assure the Rexx BSF-function package
in May 2001
Rony G. Flatscher, Vienna, Austria, Europe, 2001-04-27 ... 2001-06-03
========================== Post Scriptum ================================
P.S.: For those wishing to compile the C-program to create versions of the
DLL for other operating systems and different Rexx interpreters, here's
a very short roundup (and please let us know in
about it!):
- INCLUDE-environment
- 'BSF4RExx.cc' uses the 'Java native interface' (JNI)
- you need to include the 'Java native interface' JNI header
files, located in the 'Java Development Kit' (JDK) subdirectory
'include' and the respective platform dependent
subdirectory 'include/{linux|os2|win32}'
- JNI-header file for the 'BSF4Rexx' support
- this file is supplied in the './rexx/source' directory as
com_ibm_bsf_engines_rexx_Rexx2Java.h
you may recreate this file at any time by issuing
javah -jni com.ibm.bsf.engines.rexx.Rexx2Java
- DEF-file (OS/2, Windows): './rexx/source_cc/BSF4Rexx.def'
- OR: check out the Make-files to be run with 'make' (Linux) or
'nmake' (OS/2, Windows):
linux_bsf4rexx.mak (gcc, g++)
os2_bsf4rexx.mak (IBM's Visual Age C++, 3.x)
win_bsf4rexx.mak (MS's Visual C++ 6.x)