Intro
-----

This is a package that demonstrates how to create and read Excel files on any operating
system platforms without Excel. This is achieved by taking advantage of Apache POI
(https://poi.apache.org/).

Usually exploring the class libraries from scratch would not really be feasible to become
quickly able to apply it. However, there are many tutorials to be found on the Internet,
one used for this package is:

   https://howtodoinjava.com/java/library/readingwriting-excel-files-in-java-poi-tutorial/

This demonstrates how to create and read Excel files, and apply various functions that are
available in Excel. Unfortunately, the Java programs are incomplete and sometimes
erroneous as is, such that I completed and corrected the Java programs such that one can
compile and use them.

The ooRexx programs are transcriptions from these Java programs, such that one can compare
the code and see how one would go about using ooRexx and POI. As POI supports .xls and the
newer .xlsx, the ooRexx programs demonstrate how easy it is to create and read both
formats.

Note # 1: there are many more POI tutorials on the Internet with different, additional
features they teach and demonstrate and which can be easily transcribed to ooRexx, if one
studies the ooRexx programs in this package.

Note # 2: many times it is necessary to get at the Java documentation ("javadoc") of these
POI Java classes as many classes have much more functionality than gets exploited.  As the
Java documentation is in HTML and therefore many Java packages supply their javadocs via
their webservers such that one can use search enginges to get at the Java documenation.
In the case of POI just enter something like

        javadoc poi cell

which should give you quite a few hits, some of them linking you directly to the official
javadocs.  Once there you can jump around the documentation by following the links.


Using this package
------------------

This package contains the Apache POI jar ("poi_and_ooxml-jar-with-dependencies.jar") with
all dependencies in the lib subdirectory.  To make its classes available to Java the fully
qualified path of the jar file must be put on the CLASSPATH environment variable.  To ease
that process one can run the setup scripts, which add the lib directory with an asterisk
(*, causes all jar files in that directory to be made available) to CLASSPATH.

Windows, run:
        setup.cmd

Unix (untested), issue manually:
        export CLASSPATH=$CLASSPATH:`pwd`"/lib/*"

Unix (untested), run:
        source sh ./setup.sh

Once CLASSPATH points to the Apache POI jar, the Java and ooRexx programs can run.

Running the Java programs, please note, that you only supply the classname (do not supply
'.class'), e.g. to run the compiled Java program "ReadExcelDemo.class" issue

        java ReadExcelDemo

to run the ooRexx scripts use the BSF4ooRexx launcher named "rexxjh.cmd" or "rexxjh.sh",
e.g.,

        rexxjh.cmd ReadExcelDemo.rxj    (Windows)

        rexxjh.sh  ReadExcelDemo.rxj    (Unix)

If there are any questions please ask them, e.g. in the BSF4ooRexx or ooRexx mailing
lists, or in the RexxLA mailing list.

rgf, 2026-02-04
