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.20030510 ============================== BSF4Rexx is a package which allows Rexx interpreters to be used with the BSF (Bean Scripting Framework), originally developed by IBM and since fall 2003 under the control of Apache (cf. Jakarta project on http://www.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, Java can use (Object) Rexx as its 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 of BSF4Rexx is based on the one introduced in May 2001 to the Rexx world at the International Rexx Symposium organized by the Rexx Language Assocation (cf. http://www.RexxLA.org). An overview article with two short examples can be found at . The "Augsburg BSF4Rexx" version (v. 200.20030510) 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. All Rexx programs using BSF4Rexx are per se fully portable, ie. to any system which possesses Java and a Rexx interpreter, provided that the DLL/shared library is ported to that platform. 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.jar ... the Java archive of BSF 2.2 (IBM's version) bsf4rexx_bin.zip ... the DLL/shared libraries and some utility batch files bsf4rexx_samples.zip ... Rexx examples bsf4rexx_test.zip ... test programs bsf4rexx_src.zip ... source code bsf4rexx-apache.jar ... the Java archive of BSF 2.3 (Apache's version) bsf4rexx-src.jar ... the Java source code of BSF 2.2 bsf4rexx-src-apache.jar ... the Java source code of BSF 2.3 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. ): rexx -v or regina -v 2) "bsf4rexx.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.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. 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. 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: Under eComStation resp. OS/2, Windows: regina testVersion.rex Under Linux the thread-safe "regina" may be called "regina_ts": regina_ts testVersion.rex 6) Further infos ---------------- There are archives containing sample programs written in Rexx demonstrating what can be done with BSF4Rexx. bsf4rexx_src.zip ... source of BSF4Rexx.cc with all needed files to compile it bsf4rexx_samples.zip ... contains numerous examples in Rexx (and some in Object Rexx) to show some features possible with BSF4Rexx bsf4rexx_test.zip ... contains Rexx test programs to stress test specific features 7) Support and questions ------------------------ Please use the main Rexx newsgroup to post questions, example code etc.: 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-05-10