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: (and for the forerunner at: ). The "latest" documentation on BSF4Rexx can be found at: 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 - 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: . - 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: ... 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: ... Java 1.3 ... Java 1.4 ... 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 ) and ooRexx (cf 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)