The Vienna Version of BSF4Rexx, 2006-04-10 ========================================== BSF4Rexx, version 2.60 ("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'). This version also supports OpenOffice.org (StarOffice) such that you can script OpenOffice.org from the commandline or from within OpenOffice.org (in lieu of OOo Basic, if you wish). Support ======= Post on the Internet newsgroup . 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"). Brief overview ============== 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. - With "BSF4RExx" any Java application can use (Object) Rexx as a scripting language - Open 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 preliminiary issue 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 a platform independent 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: (A new article about this particular version of BSF4Rexx can be expected.) The "Vienna version of BSF4Rexx" 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) and Windows. Files and Archives ================== readmeBSF4Rexx.txt ... this text file changesBSF4Rexx.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 BSF4Rexx_install.zip ... Archive that contains the binary distribution of, the sources of and the samples for BSF4Rexx (including OpenOffice.org samples), the setup scripts for Linux and Windows BSF4Rexx_sources.zip ... Archive that contains the C++ and Java sources docs_bsf4rexx.zip ... Archive that contains the documentation of the BSF4Rexx Java programs, including add-ons docs_apache_bsf.zip ... Archive that contains the documentation of Apache's BSF Installation ============ 0) Install 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!): rexx setupJava.rex from the archive 'BSF4Rexx_install.zip' (see step #2 below), 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. 1) Install ooRexx ----------------- Go and get the opensource and free "Open Object Rexx" (ooRexx) interpreter from: http://www.ooRexx.org http://sourceforge.net/project/showfiles.php?group_id=119701 Install ooRexx as per the instructions. 2) Archive 'BSF4Rexx_install.zip' --------------------------------- IF YOU HAVE ALREADY AN OLDER VERSION OF BSF4REXX INSTALLED, PLEASE UNINSTALL AND REMOVE IT FROM YOUR SYSTEM BEFORE INSTALLING THIS VERSION! - Unzip the archive, change into the subdirectory 'bsf4rexx' - Run the setup script "rexx setupBSF.rex" - This will create the scripts: "bsf4rexx.cmd", "installBSF4Rexx.cmd", "uninstallBSF4Rexx.cmd" and "setEnvironment4BSF4Rexx.cmd"; on Linux systems the extension will be ".sh" instead of ".cmd" - If the script does not run, because java.exe is not on the path, then invoke the script and supply explicitly the path: rexx setupBSF.rex path-to-java.exe - Run "installBSF4Rexx": this will install the Java extension "BSF4Rexx" on your machine. You may need to run as user "root" (Linux) or "Adminstrator" (Windows) - A few BSF4Rexx-supporting scripts will get copied into the Rexx directory, including all of the generated scripts. This way you are always able to uninstall the Java extension "BSF4Rexx" - Invoke BSF4Rexx-scripts with the dispatcher program "rexxj.cmd" ("rexxj.sh" on Linux), e.g. "rexxj infoBSF.rex" which will give you information about the configuration BSF4Rexx uses 3) "rexxj" ---------- 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.3 or higher): rexxj.cmd ... Windows rexxj.sh ... Linux 4) Testing your BSF4Rexx installation ------------------------------------- a) Issue the following command from the command line (this will load Rexx via Java): rexxj infoBSF.rex or rexxj infoBSF-oo.rex b) Issue the following command from the command line (this will cause Rexx to load Java): rexx infoBSF.rex or rexx infoBSF-oo.rex If this does does not work, because Java cannot be find, please execute the script "setEnvironment4BSF4Rexx.cmd" (Windows) or ". ./setEnvironment4BSF4Rexx.sh" (Linux with bash shell). Rerun the scripts above. 5) Next steps ------------- Unzip the archive "BSF4Rexx_samples.zip". Study all the programs in there and run them. If interested in OpenOffice.org see the directions below, especially the link to Mr. Ahammer's work which contains numerous little nutshell examples to jump start your productivity in scripting/automating/remote-controlling that great product in an openplatform manner (all scripts should run under Windows and Linux). 6) Support, questions and discussion ------------------------------------ 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. --- 7) Ad OpenOffice.org (OOo) /StarOffice (SO) support --------------------------------------------------- - Go and get OpenOffice.org from : it is free, opensource, small in size, multiplatform and is able to read and write Microsoft Office documents! Starting with version 2.0 the OASIS document format is used! Installation is done within a minute or two and off you go... - For automating/remote-controlling OOo/SO via BSF4Rexx, Java must be enabled in OOo: - start e.g. OOo Writer, choose the menu option 'Tools -> Options... -> OpenOffice.org -> Java": make sure that the check-box is set next to "Use a Java runtime-environment" - Run "rexx setupOOo.rex path-to-OOo-directory" - e.g. "rexx setupOOo.rex d:\Programme\OpenOffice.org 2.0" This will create the following scripts: - "installOOo.cmd" ("installOOo.sh" on Unix): installs the OpenOffice support - "uninstallOOo.cmd" ("uninstallOOo.sh" on Unix): uninstalls the OpenOffice support - "setEnvironment4OOo.cmd" ("setEnvironment4OOo.sh" on Unix): contains the appropriate OOo/SO definitions for the environment variable "CLASSPATH" which Java uses to locate jar-archives. Whenever you run a Rexx script from the command-line run "setEnvironment4OOo.cmd" (Windows) or ". ./setEnvironment4OOo.sh" (Linux) first and then start your Rexx script via "rexx my-Rexx-script" or "rexxj my-Rexx-script". To test your installation issue one of the following commands (file extension ".cmd" for Windows, ".sh" for Linux): rexx testOOo.rex rexxj.cmd testOOo.rex rexxj.sh testOOo.rex rexx testOOo2.rex rexxj.cmd testOOo2.rex rexxj.sh testOOo2.rex - If running OOo 2.0 or greater you can activate the ooRexx script support from *within* OOo (ie. you can use ooRexx everywhere where one can use the built-in 'OOo Basic'!): - start e.g. OOo Writer, choose the menu option 'Tools -> Package Manager ... -> Add...', locate the file 'ScriptProviderForooRexx.jar' in the BSF4Rexx installation directory ('bsf4rexx'); this support is local to the user who installed it **OR** (system wide) from the commandline in the home directory of OOo/SO issue: unopkg add -shared ScriptProviderForooRexx.jar ... the above will add this support to OOo/SO and makes it available to any OOo/SO user - close all instances of OOo (including the quickstarter!) such that the new package will get loaded the next time you load any module of OOo - Information/documentation on automating OOo/SO with BSF4Rexx can be found at: (Andreas Ahammer) All the nutshell examples of this work should run out of the box on your machine under Windows and Linux, and help you jump-start controlling OOo from Rexx! All of the nutshell examples are distributed with this package under "samples/OOo" in a slightly edited form. This work also has further pointers to infos on the net, which explains the specific ooRexx support via BSF4Rexx: Please note: the file 'OOO.CLS' has been replaced/superceded by 'UNO.CLS'. The OOo-homepage with links to the *excellent* DeveloperGuide (a must!): Good luck and have fun ! --- Rony G. Flatscher University of Economics and Business Administration (Wirtschaftsuniversitaet Wien, "WU") Vienna, 2006-04-10 ------------------------------------------------------------ Old news, but some maybe still noteworthy, helpful: ATTENTION - all NEW BEHAVIOUR! - starting with version 250.20050602 (2.50 as of 2005-06-02) 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) 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 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.