
Introduction
------------

This package contains some tools to integrate Java and NetRexx 
development into the IBM Workframe 3 that comes with VisualAge C++ 
(while technically, you could integrate with any version of the 
workframe, these files build on the default C/C++ setup, so that you 
can easily develop with C, Java, and Netrexx all in one project.  The 
integration is not super-sophisticated (don't get too excited, there's 
no integration with the Visual Builder) but they do fit in well to the
integrated Workframe Environment.

Installation
------------

Installation is simple.  First, make sure you unzip the zip file 
to an HPFS drive.  If you are writing Java code, you will have to 
be using an HPFS drive anyway, so this shouldn't be a big deal.Copy
the file makerunner.cmd to a directory on your path (ibmcpp/bin if you
like).  Copy the remaining files (Java App, Java Applet, NetRexx App,
and NetRexx Applet to a directory where you keep your default
projects.  The one that comes with VACPP is normally in
\ibmcpp\mainprj, and you can put them there if you like, but I usually
keep mine in a separate directory, since if I re-install VisualAge,
they may get destroyed.

NOTE:  See EPM Support below for where to install the EPM support 
files.

Prerequisities
--------------

You should probably use the latest CSD for Workframe (current is 
CTW302) although I don't specifically know of anything I've done that 
requires it.  It would also be a good idea if you were using the 1.02 
SDK from IBM.  The main reason for this is, my run command has no way 
to distinguish whether the java class it is running uses AWT or not, 
so it always invokes the app with the java command, never with javapm. 
In SDK 1.02 this will work with both text and AWT java programs, but 
with previous versions it will not.

Using It
--------

Basically, all you do is create a new project for your Java app, and 
in the Inheritance tab of the settings, change from inheriting from 
the default project to one of the four supplied with this package (I 
think the names are pretty self-explanatory - if you're developing a 
Java Application, use "Java App", if you're developing an applet, use 
"Java Applet".  See below for specific differences between the two.

Java App
--------

Use this for developing Java text or AWT applications.  When you set 
up your project, you should set the target to be the class file that 
contains the entry point for your program (eg. main.class).  This is 
the class that the Run command will start running (eg. when you press 
the run button).  That's the only special thing about this class, 
since there's no compile-time linking with Java.

So, what is set up for you here?  First of all, there are a few new 
file types defined:

JavaSource  - Java source files (*.java)
JavaClass   - Java class files (*.class)
Html        - Html files (*.html).  This is only defined to be *.html,
              because .htm files have a special meaning for the "Java 
              Applet" project.


So, what can you do?  Well, in your build options, you will 
find a couple of new choices:  Compile::Java Compiler and 
Document::Document Java.  If you select Compile::Java Compiler, than 
doing a build will set up a make file to compile all the .java files 
into .class files.  If you also select Document::Document Java, html 
documentation files will automatically be generated for all the java 
files.  These projects have been set to use EPM as the default editor 
because files are provided to add syntax highlighting for Java and 
Netrexx and context-sensitive help for the AWT library if using EPM.

If you press the Run button, the class file named as the project 
target will be run.  If you press the debugger button, jdb will be 
started with the project target class file loaded.  You may also 
right-click on an individual .class file and select to either run or 
debug it.  Double-clicking on a .html file will cause the webexplorer 
to be loaded to display it, but you can edit it by right-clicking on 
it and selecting edit.

There is also a button on the toolbar, second from the right for Java 
help.  If you click this, the Web Explorer will be loaded, and Sun's 
Java home page will be displayed.  You can also select 
Project->Help->Java Help to get this, or if you select Project->Help->
Java Debugger Help the WebExplorer will be loaded and take you to some
information at Sun's site on how to use the Java debugger.

That's about it.  One thing that does _not_ work, unfortunately, is 
that if you double-click on an error message in the Monitor window, 
the editor will not automatically load the offending file and display 
the error message.  I don't know why it doesn't work, I've set it up 
as documented, but I just can't get it to work.  I'm inquiring with 
VACPP tech support to see if I can figure it out, if so, it will be 
fixed in a future version of this file.

Java Applet
-----------

This is exactly the same as Java App, except for one thing.  When you 
specify a target for the project, you should select the class that is 
the applet entry point, but give it a .htm extension, eg. 
HelloWeb.htm.  Then, in the Build options, you should select 
Compile:MakeAppletRunner in addition to whatever other things you 
select.  This will cause a small .htm file to be created which will 
display the applet.  If you double-click on a .htm file, the WorkFrame
assumes it is an applet, and displays it with the applet viewer. 
Pressing the Run button will display the .htm file specified in the 
project target using the applet viewer.  The program that creates the 
.htm file is makerunner.cmd, so it needs to be on your path somewhere 
for this to work.

NetRexx App
-----------

This is exactly the same as the Java App, except that it adds a 
NetRexxSource file type for .nrx files, and in the build options, you 
will see Compile::NetRexx Compiler.  Selecting this option will cause 
the builder to create a makefile which will compile all .nrx files to 
.class files.  The Compile::Java Compiler option is still available, 
so you can combine Java and Netrexx in one project if you want.  Other
than this, there are no real differences.

Double-clicking on error messages doesn't work for NetRexx either, and
it probably never will, the error message format of NetRexx doesn't 
fit very well with what Workframe expects.  Some day I may write a 
Rexx post-processor to convert it to something more manageable though.

NetRexx Applet
--------------

This is the same as Java Applet, but with the changes as specified for
NetRexx App above.

EPM Support
-----------

Included in this package are 3 files to help support Java and Netrexx 
using EPM:

epmkwds.java
epmkwds.nrx
rexxkwds.ndx

The first two should be put somewhere on the path specified by your 
EPMPATH (preferably the first directory on your EPMPATH).  These files
provide syntax-highlighting support for Java and Netrexx respectively. 
Note that you must manually turn on keyword highlighting for a file 
when you load it, unless you recompile your .e files to make it 
automatic.  They also highlight all of the class names in the standard
AWT classes supplied with Java.

The third file, rexxkwds.ndx should be placed either somewhere on your
EPMPATH, your DPATH, the EPM directory, or in your PATH.  It will be 
fastest if it is in the first directory on the EPMPATH.  You must now 
edit your config.sys.  If there is a SET HELPNDX entry in the 
config.sys, you should modify it, otherwise create a new one.  If you 
have workframe installed, there will almost certainly be one there. 
Here is what mine looks like after I modify it:

SET HELPNDX=rexxkwds.ndx+EPMKWHLP.NDX+CPP.NDX

This adds the capability that if your cursor is on the name of an AWT 
class and you press CTRL-H the webexplorer will be loaded and will 
display the documentation for that class.  Both the unqualified and 
qualified names will work, eg. both Frame and java.awt.Frame will 
cause java.awt.Frame.html to be displayed.  The file assumes that the 
documentation is in %JAVA_HOME%\docs\api, so your JAVA_HOME 
environment variable must be set correctly.

Also, help will be provided for all of the netrexx keywords, if you 
define the NREXXDOC environment variable.  It should point to where 
you installed NetRexx (if you did), for my machine, for example, it is

SET NREXXDOC=e:\apps\nrexx

This is normally where all the .htm files documenting netrexx are 
found.  Note that, as they change the documentation for Netrexx, these
may stop working, if the naming convention changes at all.

Well, that's it.  I hope these little files make your Java programming
life a bit easier, at least until VisualAge Java is released.  If you 
encounter any problems, you can e-mail me and I will try to fix them, 
but I don't make any promises.

Robert McDermid
mcdermid@hcl.com
