NetRexxDE documentation

This is documentation for version 1.0.2c of NetRexxDE which supercedes NetRexxJe 1.0.2b.

An always updated html version of this documentation is included with every release of the project. You may access it vía jEdit's built-in help system.

Introduction

NetRexxDE stands for NetRexx Development Environment. It aims to be just that, an IDE like environment for Mike Colishaw's NetRexx programming language.

The NetRexxDE plugin provides a quick and easy way to compile and run your NetRexx or Java program from within the jEdit environment.

This software was previously known as NetRexxJe to which you're most probably already acquainted if you're involved in NetRexx development at all. See the History section below for details on how and why NetRexxJe became NetRexxDE.

Please, see the rest of this doc for detailed features description.

Requirements

The minimum requirements are

• JDK 1.5
• jEdit 4.2
• NetRexx 2.05 (included with the plugin)
• ErrorList Plugin 1.2.3
• CommonControls 0.2
• SideKick 0.1

Download

Download current and archived releases from the project's files area. Developers releases include full source code as well as an apache ant based build system.

Also download links for external libraries or tools (as Martin Lafaix' Workspace for NetRexx).

Installation

jEdit can install the plugin for you or you can install it manually.

• To let jEdit install the plugin
  • Go to the jEdit menu and select Plugins.
  • From the drop down menu select Plugin manager and follow the instructions.
  • Unfortunatelly NetRexxDE is not a jEdit team sanctioned plugin yet so this method won't work for the time being.
• To install it manually
  • Download the NetRexxDE-x.xx.jar / .tgz / .zip file
  • Extract NetRexxDE.jar and NetRexxC.jar file from it.
  • Copy both jar files to:
    • jars folder under jEdit home directory (install for all users)
    • jars folder under jEdit user settings directory (install just for you)

Note: jEdit will show actual location of both these directories when opening the menu "Utilities".

Getting Started

To start the plugin

• Go to the jEdit menubar and select "Plugins".
• On the Plugins drop down Menu select "NetRexxDE" to start NetRexxDE. (Select it again to stop the Plugin.)

Hopefully this is all you would need to do to get going.

But if a message box pops up asking you to set some paths or you are having problem later on while using NetrexxDE then read on.

Issues with paths

Every time NetRexxDE is started it checks to see if certain paths are set and that they are valid.

• If a path is not set it will try to set it itself.
• If a path is set then it will check to see if the it is valid i.e. if it exits.
• If it is unable to set a path or if it finds that a path is invalid it will pop up a message box warning you of that and will ask you to set it manually.

To set/check/change the paths set by NetRexxDE -

• Go to the jEdit menubar and select "Plugins" -> "Plugin Options...".
  This will bring up the Plugin options dialog box.
• In this dialog box select "NetRexxDE" on the left pane
  This should bring up the NetRexxDE option panel on the right.
• You should see three fields which will have to be set. These are
  • Path to JVM.
    This should be set to where your java jre is.
    On windows this might be c:\jdk1.5\bin\javaw.exe.
    On linux this might be /usr/local/java/jdk1.5/bin/java.
  • Path to NetRexxC.jar.
    This should be set to where the NetRexx compiler & runtime library file viz NetRexxC.jar file is. Because the NetRexxC.jar file is included in the plugin this path will be set to point to the plugin directory. You can change this to point to another version of NetRexxC.jar file.
  • Path to tools.jar.
    This should be set to where the java compiler file tools.jar file is.
    - On Windows this might be c:\jdk1.5\lib\tools.jar.
    - On Linux this might be /usr/local/java/jdk1.5/lib/tools.jar
    - On Mac OS X this might be /System/Library/Frameworks/JavaVM.framework/Classes/classes.jar, which should always point to actual path on your system.
• After changing the paths click OK to save the paths and come out.(The values are saved across jEdit Sessions.) If you had cleared a field or had left it blank NetRexxDE will try to set it again. If it fails then it would leave the field blank and warn you of that.

Linux

On some Linux installations NetRexx seems to ignore the tools.jar path setting during compilation. If you get the error message "java.lang.NoClassDefFoundError:sun/tools/javac/Main" every time you try to compile your program, then either copy the tools.jar to your java's jre/lib/ext directory or create a link to tools.jar in your java's jre/lib/ext directory.

Mac OS X

Looks like Mac OS X does not provide a tools.jar file instead the same functionality is provided by classes.jar

Using the Navigator

The Structure Browser

Displays the structure of programs and helps moving around the code.

Structure browser has been implemented using the SideKick Plugin.

The NetRexxDE Plugin scans your source code for NetRexx tokens (classes, properties and methods), creates a tree model and passes that over to the SideKick plugin. The SideKick Plugin displays the tree in a separate docked\undocked Structure Browser window.

• When you click a node on the tree the Structure Browser moves the cursor\caret over to the line containing the class, property or method referred to by that node.
• When you click a node while pressing the Shift key the Structure browser selects the whole class, property or method referred to by that node.
• When you click a node while pressing the Ctrl key the Structure browser displays the the whole class, property or method referred to by that node and hides the rest of the code. Clicking another node redisplays the rest of the code.
• As you move around your code the corresponding node on the tree is automatically selected.
• Clicking the refresh button will force the Structure Browser to parse and refresh the tree.

You can also set options to automatically parse at certain time intervals or when certain events occur. To do so go to Global Options and set the properties of the SideKick Plugin

The Structure browser can also be docked using global options, docking.

Since 0.0.1 you can select different options for node sorting and node grouping on the structure tree. Be sure to play a bit with the different available combinations sou you get what suits better your own tastes. There're 28 different setups in total.

Note: The NetRexxDE plugin uses simple regular expression for parsing your code. It is not a true Parser. It will not validate your code. If your code does not compile properly you might get unexpected results.

Compiling your Program

The NetRexx / Java Compiler.

The compile button is a toggle button and will remain pressed during the compile process. To abort the compile process any time press the Compile button again.

If the compile process was error free then a class file would be created in the same directory as that of the source file.

Any warning or error messages reported by the compiler will be passed on to the EditBus. If you have installed the ErrorList Plugin then these messages will be displayed in the ErrorList plugin panel. Clicking a message on the ErrorList panel will highlight the erring phrase in your source code.

If the file type of the program is 'java' then the plugin would invoke the java compiler otherwise it would invoke the NetRexx compiler.

If you are compiling a java program you can add/change compile options by typing them in the 'Args/Stdin' text box. For example to compile the java program with the 'verbose' option just type -verbose in the 'Args/Stdin' text box and press the Compile button.

Note: While compiling netrexx program the plugin uses the NetRexx compiler's "compact" option to make it display the messages in particular format. If this option is overridden, using the option keyword in your source program, then the plugin will not be able to capture the messages.

Creating the Java Program

Netrexx to Java.

Like the compile button the Java button is also a toggle button and will remain pressed during the whole process. To abort the Java process anytime press the Java button again.

Pressing the Java button also invokes the NetRexx compiler. But this time the compiler merely parses the source file and creates the equivalent java file. It does not create the class file.

At the end of the process if there were no errors a java file is created in the same directory as your source file and is also displayed in another edit pane.

By default the file is given the name of your program and an extension of "JAVA.KEEP". This can be overridden to give an extension of "JAVA". To do this go the Global Option dialog box and select the NetRexxDE option "Change file type from JAVA.KEEP to JAVA after the java Processing". Changing file ext to "JAVA" can be helpful because then you can use other Java Plugins like JBrowse etc to analyze your code.

If the "JAVA.KEEP" to "JAVA" option was chosen in the Global Options dialog box then remember to also override the noreplace compiler options. Normally the compiler complains if it finds a JAVA file already there.

Error messages are handled in the same manner as the Compile process described above.

Changing Compiler Options

NetRexx compiler options.

Pressing the Options button will replace the NetRexx console panel by the compiler option panel. Pressing the Options button again will restore the console panel.

The compiler option panel contains a list of the DEFAULT options used by the compiler. To override an option just go and select it. The selections made are saved across jEdit sessions.

Changing Classpath

You can change the classpath used by the NetRexx & Java compiler by typing in a new classpath in the ClassPath field. You can also set the path interactively by clicking the ClassPath button.

The ClassPaths set by you are stored in the jEdit's History file. They are available when you start jedit again.The number of ClassPaths stored is determined by the 'History entries' setting in the General Global Option.

To select a previous classpath click the drop down box and pick one from the drop down list.

The plugin automatically adds the following paths to what you selected:

• the path to the source file viz '.'
• the system classpath which is basically the classpath found when jEdit was started
• path to NetRexxC.jar
• path to tools.jar

Note: In windows if you started jEdit using the jar option (eg java -jar jedit.jar) then your system classpath would be just jedit.jar

Running Your Program

Run NetRexx / Java program.

This is a toggle button and will remain pressed and its icon will change to during the run. To abort the run anytime press the Run button again.

To pass any arguments to your program type in those arguments in the Args/Stdin field or pick one more the drop down box before running the pgm. To store your arguments in the history press ENTER after entering the arguments.

Your program will run with the classpath set as described above and with the arguments typed in the Args/Stdin field

If your program reads from the STDIN during it's run ie. if it uses ask or readln etc then you can pass data to it by typing the data into the Args/Stdin field or picking one from the drop down box and pressing the ENTER key on the keyboard. The data is stored in the history.

Using then TRACE console

The TRACE console.

This is a toggle button that will switch panels to the brand new separate TRACE console. Clicking the button again will switch back to the regular stdin/stdout console. At any time you may use this console get at any trace output generated by previous programm runs.

While the TRACE console is active its button icon will change to . Additionally TRACE console's background color is a shade of gray to help identifiying current active console.

If at any time a running process generates some TRACE output while this console is not the active one, NetRexxDE will notify you of the event animating its button like this

NetRexxDE's output parsing engine will identify lines corresponding to source lines and make them 'active'. That is, lines styled as underlined and blue can be clicked and jEdit will jump to the buffer containing that file. The line in question will be selected. A new buffer will be created in the event of the source file not being previously openend.

Note: NetRexxDE will do its best to find nrx souce files in the classpath. As the NetRexx translator provides no path information in its output, some issues might still arise in some corner cases when having two or more same-named files in the same run.

Using then ERROR console

The ERROR console.

This is a toggle button tha will switch panels to the new separate ERROR console. Clicking the button again will switch back to the regular stdin/stdout console. At any time you may use this console get at any error output generated by previous programm runs.

While the ERROR console is active its button icon will change to . Additionally ERROR console's background color is a shade of red to help identifiying current active console.

If at any time a running process generates some output on the System.err stream (as per System.err.println() or Exception.printStackTrace()) while this console is not the active one, NetRexxDE will notify you of the event animating its button like this

NetRexxDE's output parsing engine will identify lines corresponding to source lines in stack traces and make them 'active'. That is, lines styled as underlined and blue can be clicked and jEdit will jump to the buffer containing that file. The line in question will be become selected. A new buffer will be created in the event of the source file not being previously openend.

Using Keyboard Shortcuts

All of the tasks that you can perform by clicking buttons on the plugin toolbar can also be performed by pressing certain keyboard keys. Before you can do this you need to assign certain keyboard combinations to a task.

To do this:

• go to the jedit menu and select Utilities > Global Options. This would bring up the Global Options window.
• Select jEdit Options > ShortCuts.
• On the right pane click the Edit ShortCuts drop down menu and select Plugin:NetRexxDE.This would list out all the task/commands available.
• Enter the Key Combination that you want to use for a task/command.

For more help on setting and using keyboard shortcuts see the jEdit Help.

CC

General notes

Compiler optimization

The compile and create java process uses the NetRexx compiler -prompt option.

The compiler runs in a separate thread and does not stop after a compilation or parsing is completed. It just keeps waiting in the background. As a result of this subsequent compilations are quite fast. The compiler restarts only if the file to be compiled or parsed is in a directory which is different from the directory of the file last compiled or if the classpath was changed.

NetRexxC default package

During Compile, Java or Run process the source code directory is made the current working directory. The reason for this is the way netrexx compiler handles default packages. This might change in the future. (This was the main reason for using JDK1.3. JDK1.3 provides a simple way to change working directory)

To Do

These are the additional features that are being considered

• Add a compiler option panel for changing Java Compiler options.
• Add online help for NetRexx keywords.
• Utility to quicky create JavaDoc files for netrexx programs
• Provide the means to interface to the NetRexx interpreter. Maybe allowing for 'live' NetRexx expression evaluation.
• Mass Compiles, aka 'Project mode'.

This one came a little nearer into being as the new build system has demonstrated that integration with ant's optional netrexxc task is indeed posible. Now considering integration with Project Viewer and/or AntFarm plugins.

Change log

NetRexxDE has endured a somewhat convoluted life starting as NetRexxJe by Satguru P Srivastava, then startted being maintained by David Requena under a new version number schema, and finally as NetRexxDE.

Changelog entries below are grouped according to these said periods

NetRexxDE releases

Releases under the new NetRexxDE nomenclature by David Requena.

Version 1.0.2c (February 2010) by David Requena

• A change in Sun's Hotspot VM default heap values prevented NetRexxDE to compile NetRexx code in JRE/SDK v. 1.8u18 and up. Hot fix released with minimum heap size increased to 16 MB. This will be better fixed on next version.

Please, be sure to check Issue Tracker to see what's to come in NetRexxDE v. 1.1.0

NetRexxJe 1.0.x releases

These were releases by David Requena which included new features and functionalities. They had limited distribution among ibm-netrexx mailing list members. Some versions are available for download from the Archived downloads area.

Version 1.0.2b (February 2010) by David Requena

• A minor change in jEdit v. 4.3 final API was preventing NetRexxJe from building against most recent jEdit versions. Fixed by explicitly casting classes to EBComponent before insertion in jEdit's Edit Bus.

Version 1.0.2a (August 2009) by David Requena

• A minor aesthetic bug preventing the run button to go back to inactive icon on process abortion was fixed
• Several misspellings on written docs were fixed.
• Some debug logging code had inadvertedly left on final release.

Version 1.0.2 (August 2009) by David Requena

• New build system. Now you can take the full distribution, put containes folders anywhere on your disk and buld using ant and the provided build.xml file.

In addition build system now uses ant's netrexxc task for compilation instead of the previous, clever, hack. Ant is able to determine if the compilation went well as well as which source files need recompilation. Previously it recompiled everithing on each run and packaged even when errors arose.

Note: If you're using Jedit plus ant and AntFarm plugins to build NetRexxDE you'll need to get ant-netrexxc.jar elsewhere and configure it at AntFarm's settings. This is so because ant plugin does not include ant's optional taskdefs.

• Distribution packages generated are now apt for installation vía Plugin Manager. For the time being manual installation is still needed as PM requires plugin download from Plugin Central to which I've no access...
• NetRexxC.jar v. 2.05 is now included in the distribution.
• New TRACE console for uncluttered tracing of programs. Source lines get identified and hyperlinked.
• New Error console gets standard error output. Source lines get identified and hyperlinked.
• Ability to sort nodes in the structure browser. Case sensitive/unsentive sorting option.
• Grouping of method nodes in the structure browser in several ways with optional identification of constructor methods
• Several graphics tweaks across the UI: insets adjusting, layouts, some icons, etc.
• Now classpaths directly typed in the classpath field are also added to classpath history. Previously only the ones entered through path builder were.
• Preliminary work for Project Viewer plugin integration done. Some (disabled) options present in the option pane.

Version 1.0.1 (Feburary 2008) by David Requena

• Adapted to use java's standard regex support instead of the former jEdit built-in one. Got some trouble with the new GNU regex plug-in.
• Minimum JDK versión is now 1.5 as a requirement of previous item. Actual requirement would be 1.4 in fact but doesn't matter much as jEdit's java baseline is now 1.5. Anyway this allowed eliminating some deprecation warnings when building on 1.5+ jdks.
• Changed version number format.
• NetRexxDE has been for a long time 'frozen' with no bug reports and the like so once properly loading on jEdit 4.3x I'll consider it as a 1.0 release. Any further modifications will be new features/fixes on my own and will follow the more standard x.x.x plugin version number scheme.

Version 0.10 (June 2008) by David Requena

• Adapted to JEdit's new plug-in loading mechanism introduced in v. 4.2.

NetRexxJe 0.0x releases

This is Satguru's changelog for his NetRexxJe releases

Version 0.09 (March 2003)

• Replaced NetRexx Source Code Navigator by SideKick plugin's Structure Browser

The Sidekick plugin includes a structure tree dockable window, commands for moving the caret and folding based on language tokens.

Version 0.08 (October 2002)

• Added capability to define keyboard shortcuts.
• Args/Stdin data is now stored in jEdit history file for later recall.
• Fixed bug in source code navigator. This source code navigator displayed properties erroneously when no classes or methods were explicitly defined in the source code.

Version 0.07 (June 2002)

• A source code navigator added. This presents the netrexx pgm as a Tree with nodes of classes, properties and methods. User can move around his code by clicking nodes on the Tree.
• GUI changed.
• Floating tool bar removed.
• Switched to smaller standard Java L&F icons.
• GUI elements rearranged.
• ClassPaths now stored in jEdit history file instead of property file
• jEedit's History Textfield is now used to get ClassPath. Much better than JComboBox used initially.
• Number of classpaths stored changed from 5 to a value determined by 'History Entries' setting in Global General Options

Version 0.06 (May 2002)

• Made jEdit 4.0 compatible
• Changes were made to DockableWindow, EditBus and Errorlist code
• DockableWindow now created through dockables.xml file
• Added code to interactively set Classpath
• This is done using the CommonControls Plugin
• Added ANT script file (build.xml) for building the Plugin

Version 0.05 (October 2001)

• Removed code which used the old Action API.
• The Action API has been deprecated since jEdit 3.0 and will be gone in jEdit 4.0.
• Actions are now defined using 'actions.xml' and 'NetRexxDE.props' files.
• EndUser should not see any difference.

Version 0.04 (March 2001)

• Added code to compile Java Programs too.
• Now both NetRexx & Java programs can be compiled from within the plugin.
• The NetRexx compiler & run time library file 'NetRexxC.jar' is included separately in the plugin package. In the previous version it was included as a part of the plugin file 'NetRexxJe.jar'. The new way is the standard way of including external packages in a plugin package.

Version 0.03 (March 2001)

• Added NetRexxC.jar file to the plugin. This avoids installing NetRexx separately.
• Added code to automatically set various paths.

Version 0.02 (Nov. 2000)

• bugs fixed
• gui revamped
• minor optimizations for speed

Version 0.01 (Oct. 2000)

• First version released

NetRexxDE history

This project started life as NetRexxJe, by Satguru P Srivastava who at some point in time got out of reach, leaving it somewhat 'abandoned'. Most users went on using Satguru's outstanding work as it just worked fine.

Now jEdit development went on and with the advent of 4.3preXX releases some changes to its plugin subsystem prevented NetRexxJe from loading. At this point, I made required modifications so I could go on using NetrexxJe for my personal projects.

Fast forward some 14 months and someone asked at the ibm-netrexx list about an updated NetrexxJe plugin. Ofering what I had at the time seemed to stir some interest among NetRexx practitioners so I went on and released a couple new versions and bugfixes at the same list.

Well, it's been more than 2 years trying to contact Satguru now, his project at Sourceforge is of course locked to him. I have some interesting ideas for further development of the product but never feel comfortable tinkering with a fellow programmer's code without his knowing and/or consent. That in combination of NetRexxJe being GPL 2.0 licensed is why I decided to simply fork the product into a brand new project : NetRexxDE.

To Mr. Srivastava

Dear Mr. Srivastava,

If you ever happen to read this, I would be more than happy having you
cantact me so we could discus the topic of the fork and the possibility
a re-merge.

Rest assured I'm open to any proposal you might have in mind on the
subject.

Kind regards
David Requena, 02/02/2010

Feedback, issues, bugs

I'll be more than happy to hear from you, be it with suggestions, found issues or bugs, or just plain comments on NetRexxDE

Preferred channel for defect info is filling a bug with the project's Issue Tracker.

Failing that, please send email to one of the following lists.

• issues@netrexx-misc.kenai.com- Bug reporting.
• feedback@netrexx-misc.kenai.com - General feedback on the product, new feature suggestions, etc.

Thanks,
David Requena