The ooRexx OpenOffice.org Support (Using the Vienna Version of BSF4Rexx), 2006-07-20 ==================================================================================== Please see also the text file "changesOOo.txt" which contains important information about changes in the OpenOffice.org (OOo) /Staroffice (SO) support. 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 ============== The ooRexx OpenOffice.org (StarOffice) support is based on BSF4Rexx as it uses the Java interfaces to and from OOo. The component technology OOo uses is built with the programming language independent "Universal Network Objects (UNO)", which can be used on its own for creating cross-platform applications. The ooRexx support is created at the UNO-level and can therefore be used for interfacing with any UNO component technology, not only OOo! The following ooRexx programs constitute the UNO support with specific OOo support built on top of it: UNO.CLS ... an ooRexx module defining UNO proxies and making it easy to query interface objects from service objects by merely sending the (unqualified) interface name to the UNO proxy; UNO_XINTERFACES.REX ... an ooRexx module defining the names of all OOo interface classes as of OOo version 2.0.3 (July 2006) which increases performance; since July 2006 UNO.CLS has a fall-back solution in place, which uses the UNO reflection mechanism at runtime [UNO_CREATE_INTERFACE_LIST.REX] ... not needed, but could be used to create the above ooRexx program "UNO_XINTERFACES.REX"; it is part of the distribution for completeness only The following Java archive enables OOo to use ooRexx as a macro language: ScriptProviderForooRexx.jar ... Java archive containing the glue code between OOo's Java based scripting framework and ooRexx, employing the Jakarta BSF framework (it would be very easy to use BSF to add additional languages as macro languages to OOo) The OOo ("scripting") support allows to create (commandline) ooRexx openplatform scripts that can interface and remote control OOo on the one hand. On the other hand OOo itself can invoke ooRexx macros. 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 ... text file, explaining BSF4Rexx and its installation readmeOOo.txt ... this text file, explaining the OpenOffice.org/Staroffice support and its installation 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 The following Java archive enables OOo to use ooRexx as a macro language: ScriptProviderForooRexx.jar ... Java archive containing the glue code between OOo's Java based scripting framework and ooRexx, employing the Jakarta BSF framework (it would be very easy to use BSF to add additional languages as macro languages to OOo) Installation ============ 0) Install BSF4Rexx ------------------- Cf. "readmeBSF4Rexx.txt" for instructions. 1) Get and install OpenOffice.org (OOo) / StarOffice (SO) --------------------------------------------------------- You need to have OpenOffice.org installed before being able to install the specific ooRexx support for it. 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 open-standard OASIS document format is used! Installation is done within a minute or two and off you go... Note (especially for Linux users): if your installed version of OpenOffice.org does not include the Java support, then ooRexx cannot interact with that version. (Some Linux distributions compile OpenOffice.org without the Java support!) In such a case please download the "genuine" OpenOffice.org package and install that. 2) Make sure that Java is enabled for OpenOffice.org ---------------------------------------------------- - 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" - make sure that the same version of Java is used as the Java version for which BSF4Rexx got installed (BSF4Rexx is installed as a Java extension) - If you had to change the OOo Java configuration then you need to close *all* running instances of OOo; do not forget to close the quick-launcher as well! This will make sure that on the next start of any OOo component this new configuration takes in effect as OOo has to re-read the configuration from scratch. 3) Install the OOo support -------------------------- - 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): --> this is the installer which is tailored to your specific environment; run it to install the ooRexx OpenOffice.org support - "uninstallOOo.cmd" ("uninstallOOo.sh" on Unix): --> this is the uninstaller which matches the tailored installation script above; run it to uninstall the ooRexx OpenOffice.org support - "setEnvironment4OOo.cmd" ("setEnvironment4OOo.sh" on Unix): --> this a script that sets the environment variables to point to OpenOffice.org Java archive files, such that you can run ooRexx scripts from the command line; run it, before invoking any ooRexx script that drives OpenOffice.org (hint: you can put those environment variable definitions into your logon-script or into your machine's set of pre-set environment variables); then start your ooRexx-OOo-scripts by issuing "rexx my-ooRexx-scriptfile.rex" - Testing the installation: - After running "installOOo.{cmd|sh} you must close *all* running instances of OOo; do not forget to close the quick-launcher as well! This will make sure that on the next start of any OOo component this new configuration takes in effect as OOo has to re-read the configuration from scratch. This will make sure that the following test-scripts can run successfully, if the installation was successfull! - To test your ooRexx-OOo installation open a new command line window and issue the following commands (file extension ".cmd" for Windows, ".sh" for Linux): Windows: setEnvironment4OOo.cmd rexx testOOo.rex rexx testOOo2.rex rexxj.cmd testOOo.rex rexxj.cmd testOOo2.rex Linux: . ./setEnvironment4OOo.sh rexx testOOo.rex rexx testOOo2.rex rexxj.sh testOOo.rex rexxj.sh testOOo2.rex 4) Install the ooRexx Macro Support Within OOo ---------------------------------------------- The install script "installOOo.{cmd|sh}" adds the package 'ScriptProviderForooRexx.jar' to OpenOffice.org, which makes it possible to invoke ooRexx macros from within OOo. This way wherever a (Basic, Python) script can be defined within OOo one can now define an ooRexx script as well. One can remove and then add that package from the commandline by issuing either Windows: unopkg %OOoHOME%\program\unokpg remove -shared ScriptProviderForooRexx.jar Linux: unopkg $OOoHOME/program/unokpg remove -shared ScriptProviderForooRexx.jar or (to add the removed package later on): Windows: unopkg %OOoHOME%\program\unokpg add -shared ScriptProviderForooRexx.jar Linux: unopkg $OOoHOME/program/unokpg add -shared ScriptProviderForooRexx.jar After removing or adding that package, you must close all instances of OOo, including the quick starter. This forces the OOo modules to read the (new) configuration from scratch, the next time one gets invoked. 5) Information/documentation on Automating OOo/SO with BSF4Rexx - Information resources at the WU (Wirtschaftsuniversitaet Wien): point your browser to and locate all entries having the name "OOo" or "OpenOffice" in the title. Starting with fall 2005 the explanations and ooRexx nutshell examples should work with the current UNO.CLS ooRexx module (earlier work was dependent on the outdated ooRexx module OOO.CLS). The nutshell examples from the following two papers are part of the BSF4Rexx distribution and stored in subdirectories of "samples/OOo": Andreas Ahammer: OpenOffice.org Automation: Object Model, Scripting Languages, "Nutshell"-Examples Martin Burger: OpenOffice.org Automatisation with Object Rexx 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. - The following pointers may be of help as well: Please note: the file 'OOO.CLS' has been replaced/superceded by 'UNO.CLS'. - The OOo-homepage with links to the *excellent* DeveloperGuide (a *must* !): OOo homepage: *Excellent* "OOo Developer's Guide" homepage (there exists also a PDF version): *Excellent* Snippets homepage (featuring ooRexx samples since 2006-07 !): Good luck and have fun ! --- Rony G. Flatscher University of Economics and Business Administration (Wirtschaftsuniversitaet Wien, "WU") Vienna, 2006-07-20