BSF4ooRexx, 2009-10-31, Beta 2 ============================== BSF4ooRexx, version 4.0.0: this version exploits the new APIs of ooRexx 4.0 and as such can only be used on ooRexx 4.0 only, hence the renaming of the package from "BSF4Rexx" to "BSF4ooRexx". Goals of beta 1: - test backward compatibility with the Vienna version of BSF4Rexx (all currently existing BSF4Rexx programs should run unchanged with this version of BSF4ooRexx!) - allow testing the new features and support, especially: - 32-bit and 64-bit versions on Linux and Windows - usage of synchroneous Java listeners implemented in Rexx - usage of Java interfaces and abstract classes, where the abstract methods are implemented in Rexx - usage of RexxProxy objects from Java, ie. sending messages to Rexx objects, fetching their results in Java BSF4ooRexx supports Java starting with version 1.4 up to the latest drop of Java. The files "changesBSF4ooRexx_40.txt" and "changesOOo_40.txt" give brief information about the applied changes, but does not document experiments and debugging efforts which for this version sometimes was almost unbearable (especially in the multithreading part). This version supports OpenOffice.org (StarOffice) as well such that you can script OpenOffice.org from the commandline or from within OpenOffice.org (in lieu of OOo Basic, if you wish). More information can be gathered from the file "readmeOOo.txt" Installation in a "Ten Second" Nutshell ======================================= * ATTENTION * The bitness of Java must match the bitness of ooRexx ("rexx -v"): - if ooRexx is 32-bit, then you must install the 32-bit version of Java, - if ooRexx is 64-bit, then you must install the 64-bit version of Java - * IMPORTANT * * IMPORTANT * * IMPORTANT * if you have an older version of BSF4Rexx or BSF4ooRexx installed already, then run the previous uninstall-script first, if any exist ! Order: Windows: - uninstallOOo.cmd - uninstallBSF.cmd Linux: - uninstallOOo.sh - uninstallBSF.sh - unzip the archive "BSF4ooRexx_install.zip" into the target directory (this will also unzip the OpenOffice/StarOffice-support files) - change into the created subdirectory "bsf4oorexx" - execute "rexx setupBSF.rex" - this will create customized scripts, among them a custom "installBSF.cmd" script on Windows and "installBSF.sh" on Linux - execute either "installBSF.cmd" or "./installBSF.sh" depending on your platform - on Windows the necessary path information will be added to the registry; after logging off and on, the new settings are in effect - on Linux the statement to be added to the bash resource script is shown; if appended there, then every new session will have the new settings - *IF* you have OpenOffice or StarOffice installed and wish to use ooRexx to drive it, then follow the instructions found in the file "readmeOOo.txt", at the top, section 'Installation in a Ten Second Nutshell' - more information about the installation in this readme file Brief overview ============== BSF4ooRexx is an extension to Rexx and ooRexx, consisting of an external Rexx function package ("BSF4ooRexx.dll", "libBSF4ooRexx") and a set of Java classes stored in a Java archive. BSF allows Java programs to call (invoke) script programs written in languages other than Java. Such script programs may also be able to call back into Java and use all of Java's classes and objects. (cf. ) - With "BSF4ooRexx" any Java application can use Open Object Rexx (ooRexx) as a scripting language. - Open Object Rexx (ooRexx) can use Java as a huge, operating system independent function library. The special ooRexx support enabled by requiring "BSF.CLS" makes Java appear like a huge Object Rexx class library! Preliminary versions of "The Vienna Version of BSF4ooRexx" package were partly introduced in April 2005 and April 2006 to the Rexx world at the International Rexx Symposium organized by the Rexx Language Association (cf. ) where it was used for enabling ooRexx to automate (remote control) OpenOffice.org in a platform independent manner. An overview article (dated: 2003-06-01) with short examples can be found at: (and for the forerunner at: ). Another (newer) document on BSF4ooRexx can be found at: The "Vienna version of BSF4ooRexx" 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). At the International Rexx Symposium in May 2009 an outlining talk was given about "BSF4Rexx 4.0" which now has been renamed to "BSF4ooRexx 4.0". All Rexx programs using BSF4ooRexx 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 "BSF4ooRexx.cc"). Out of the box the following operating systems are supported: Linux (Intel) and Windows, with the Mac OSX distribution of ooRexx incorporating BSF4Rexx. Files and Archives ================== By convention BSF4ooRexx scripts carry the extension ".rxj" (Rexx-Java), scripts that drive OpenOffice.org carry the extension ".rxo" (Rexx-OpenOffice). readmeBSF4ooRexx.txt ... this text file, explaining BSF4ooRexx and its installation readmeOOo.txt ... text file, explaining the OpenOffice.org/Staroffice support and its installation BSF4ooRexx_install.zip ... Archive that contains the binary distribution of, the sources of and the samples for BSF4ooRexx (including OpenOffice.org samples), the setup scripts for Linux and Windows changesBSF4ooRexx.txt ... text file containing a record of the most important changes changesOOo.txt ... text file containing a record of the most important changes since the 2005 International Rexx symposium ApacheLicense2.0.txt ... Apache license 2.0 text BSF4ooRexx_sources.zip ... Archive that contains the C++ and Java sources docs_bsf4oorexx.zip ... Archive that contains the documentation of the BSF4ooRexx Java programs, including add-ons docs_apache_bsf.zip ... Archive that contains the documentation of Apache's BSF Installation ============ !!! IF YOU HAVE ALREADY AN OLDER VERSION OF BSF4Rexx OR BSF4ooRexx INSTALLED, PLEASE UNINSTALL AND REMOVE IT FROM YOUR SYSTEM BEFORE INSTALLING THIS VERSION !!!! Archive 'BSF4ooRexx_install.zip' ============================== - Unzip the archive, which will create a subdirectoy named 'bsf4oorexx' in which all BSF4ooRexx supporting files and programs are stored - Change into the 'bsf4oorexx' subdirectory - Run the setup script "rexx setupBSF.rex" This will create the following files: - 'rexxj.cmd' (Windows) or 'rexxj.sh' (Linux) ... this script allows you to run any BSF4ooRexx program without a need to change your environment settings; the BSF4ooRexx program in this case will get started via Java (see below). - 'setEnvironment4BSF.cmd' (Windows) or 'setEnvironment4BSF.sh' (Linux) ... this script changes your session's environment such, that a) Java and b) BSF4ooRexx are accessible to Rexx programs. This will then allow BSF4ooRexx programs to demand load Java, if necessary. Problems FAQ: - If the script does not run, because the binary java[.exe] is not on the path, then invoke the script and supply explicitly the path: rexx setupBSF.rex path-to-java[.exe] 3) Testing your BSF4ooRexx installation ======================================= a) Issue one of the following commands from the command line (this will load Rexx via Java): Windows: rexxj infoBSF.rxj or rexxj infoBSF-oo.rxj Unix: rexxj.sh infoBSF.rxj or rexxj.sh infoBSF-oo.rxj b) Issue one of the following commands from the command line (this will cause Rexx to load Java, the 'setEnvironment4BSF' settings must be in effect for these tests to succed): rexx infoBSF.rxj or rexx infoBSF-oo.rxj If this does does not work, because Java cannot be found, please execute the script "setEnvironment4BSF.cmd" (Windows) or ". ./setEnvironment4BSF.sh" (Linux with bash shell). Then rerun the scripts above. 4) Next steps ============= - Run all the sample programs in "bsf4oorexx/samples/" and study them. - To study the new features introduced with "BSF4ooRexx 4.0" run and study all the programs in "bsf4oorexx/samples/version4" and its subdirectories. - If interested in scripting OpenOffice.org (the examples can be found in "bsf4oorexx/samples/OOo" and its subdirectories), then please follow the instructions in 'readmeOOo.txt' to install the specific OpenOffice support which makes it very easy to program/script OOo with ooRexx in an openplatform fashion. 5) Support, questions and discussion ==================================== Please use the main Rexx newsgroup to post questions, example code etc.: or Google's interface to this netnews group: Alternatively, enroll as a member to the non-profit organization "Rexx Language Asssociation" () and use the members only listserver list there. OpenOffice-only related questions (other than the Rexx support itself) should be posted on the respective listserver lists at (e.g. "dev", "udk", "framework"). 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 WU Vienna (Wirtschaftsuniversitaet Wien, "WU") Vienna, 2009-10-31 --- --- --- --- --- --- --- --- --- --- --- --- --- Some hints ad Java: ------------------- - 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 e.g. from: . - You can download the entire 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 this writing the following "J2SE API Docs" were accessible: ... Java 1.4.2 or overview: ... Java 1.5 aka or overview: Java 5.0 ... Java 1.6 aka or overview: Java 6.0 The overview URL also contains plenty of links to tutorials and other valuable Java info material. a) Installing Java, if not yet installed ======================================== Open a command window and enter: java -version If "java" is not found or not executing Java (but a stub program as is sometimes the case on Linux) or the Java version is smaller than 1.4, then get a new Java from the Internet for your operating system and install it on your machine. One free possibility is to download Java from Sun, the "father" of Java: http://java.sun.com It is sufficient to download the runtime version (JRE - Java runtime environment), but you can download the Java developer version (JDK - Java development kit) as well. To get free access at the full documentation of all Java classes, you may want to point your browser to: http://java.sun.com/docs/index.html Remark on Linux: ---------------- On Linux, if you cannot execute "java -version" successfully, then study your Linux installation directions to make your installed Java available via the command line. Alternatively, you can run the supplied script (*Linux* only, part of the archive 'BSF4ooRexx_install.zip'!): rexx setupJava.rex which will try to locate possible installed versions of Java and will create symbolic links to point to your Java installation. As a result you can invoke Java from any process and the command line. Installing ooRexx ================= Go and get the opensource and free "Open Object Rexx" (ooRexx) version 4.0 or higher interpreter from: Install ooRexx as per the instructions. Further information on BSF4ooRexx ================================= - International Rexx Symposia, cf. , look for "BSF" (should yield presentations and articles) - Students' works at the "WU" (Wirtschaftsuniversitaet Wien, Austria), look for "BSF", cf. -