NetRexx Frequently Asked Questions

The Freely Available Code Page

A Freely Available Code page has been added. It contains sample code and working applets to help you get your NetRexx projects going!

Info on NetRexx

Q: Can I only use NetRexx to develop programs for the World Wide Web?

A: No. NetRexx can be used to develop standalone applications, on any platform that can run java. Many platforms that support java also support Internet access and the world wide web, but NetRexx applications are not restricted to Browser applets only.

Q: Are there any other WWW pages with info on NetRexx?

A: The EurOS/2 NetRexx Page has some references to NetRexx info.
Also see the RxFile home page.

Q: Where is the NetRexx language documented?

A: The first draft of the NetRexx Language Specification is available in online (World-Wide Web) format and in printable (PostScript) format from the NetRexx home page. Comments welcome! This specification will be published by Prentice-Hall as part of a new book, "The NetRexx Language", later this year.

Q: Are there plans to implement an Integrated Development Environment for NetRexx?

A: We know of none at this time. Do it!

Q: Where do I get NetRexx?

A: The NetRexx home page is at IBM's Hursley lab site in the U.K. This site is also mirrored in the U.S.A.. From here you can download the latest version of NetRexx. Check it on a weekly basis.

Q: What is NetRexx?

A: NetRexx is a new programming language derived from both Rexx and Java(tm), written by the inventor of Rexx, Mike Cowlishaw. The rules of syntax closely follow those of Rexx, while the semantics often follow Java. It is a dialect of Rexx that can be as efficient and portable as Java, while preserving the low threshold to learning of the original Rexx language.

Q: Where can I go to find out more about NetRexx?

A: You should visit the NetRexx home page for the latest information on NetRexx, including a language definition.
There is a NetRexx Mailing List that you can subscribe to. If you use this link, please put the words subscribe ibm-netrexx in the body of the email.
Also see Massimiliano Marsiglietti's home page. Max is the author of RxFile and RxDBase.

Q: Are there any books available on NetRexx?

A: At this point, none are published. Mike Cowlishaw is currently preparing The NetRexx Language to be published. There was also an article about NetRexx Java made easier - Thanks to NetRexx in the September, 1996 issue of OS/2 Magazine.

Q: How do I run NetRexx applets under OS/2?

A: You'll need to use the OS/2 JDK applet program, and pass it some HTML to execute your applet. See some of the sample HTML files in the NetRexx package, e.g. nrexx\nervous.htm. You can also run applets using Netscape for OS/2 from IBM or the HotJava technology demo available from the Hursley Java site.
In OS/2 v4.0 there are several ways to run NetRexx applets, either from HTML or from the desktop.

Program Structure

Q: Is there a way to create your own 'Throwable' condition which can be used by SIGNAL and CATCH?

A: As follows:

class RxErrorSignal extends RuntimeException

/* Construct an Exception object */
method RxErrorSignal
  super()    

/* Construct an Exception object with details string */
method RxErrorSignal(arg=String)
  super(arg)

Q: What is the order of statements in a NetRexx source file?

A: As follows:

- A comment /* */ to start the source
- Optional package, imports and options statements
- One or more class definitions introduced by the class statement

If the first class definition is omitted, it is defaulted to the name of the file, without any extension. i.e. Shell.nrx implements the class Shell.

- One or more method definitions introduced by the method statement

Differences between NetRexx and Classic Rexx

Q: How do I do file I/O in NetRexx?

A: NetRexx does not currently support the Stream, LineIn, LineOut, Lines, CharIn, CharOut and Chars Rexx file Input/Output commands. A package RxFile, is available from Max Marsiglietti and is free!.

If you don't want to use the above package, you will need to use the following java.io package of classes:

Stream - mostly covered by the java.io.File, java.io.FileDescriptor, java.io.RandomAccessFile classes using various methods
LineIn - covered by the readLine method of most java.io.InputStream class descendents
LineOut - covered by the java.io.PrintStream class, printLn method
Lines - no analogy in the java classes
CharIn - covered by the readByte and read methods of java.io.InputStream classes
CharOut - covered by the write or print methods of java.io.OutputStream classes
Chars - covered by the available method of java.io.InputStream classes Here's an example of reading from a file and storing in a Rexx stem:

   
/* Read a file into a stem */
  inFileName = 'c:\\config.sys'

  /* Use Do-catch-end block to catch bad file errors */
  Do
    inRAFile = DataInputStream(FileInputStream(File(inFileName)))
  catch ex 
    inRAFile = null
  End

  If inRAFile \= null Then Do
    /* initialise the stem */
    line = Rexx('')
    i = 0

    /* Read until EOF */
    Loop while inRAFile.available \= 0
      i = i + 1
      line[i] = inRAFile.readLine
    Catch ex
      say 'Problem reading the file: ' ex.getMessage
    End

    /* Store number of lines in the stem.0 element */
    line[0] = i
  End

Q: How do I do Charin/Charout screen I/O in NetRexx?

A: To do screen I/O in java, you use the System.in and System.out objects. To write a character to the screen, use System.out.print('x'). To read a character, use System.in.read.

To do the equivalent of a Charout, you could also use:-

 Say 'x\-'

Q: How do I run system commands in NetRexx?

A:You'll need to get an instance of the java.lang.Runtime and ask it to exec the command. e.g.

   r = Runtime
   process = r.exec("cmd /c dir /w")

You can then use the process returned to read the output (and write input) to the running program.

Warning: In the current JDK, using a command that doesn't exist on the system in the exec method will cause your program to end immediately.

Q: What is the difference between NetRexx and Classic Rexx?

A: There are many. The most obvious to programmers is that the syntax is slightly different. e.g. You can use -- for single line comments:

  /* Hello to my users */
  Say 'Hi There!' -- Tell the user we like them upbeat

Another noticeable difference is the use of object oriented concepts such as classes, methods and properties. Along with these concepts comes new statements, such as class and method, and new syntax to access these methods and properties. Arrays have finally been introduced to Rexx.

To some, the use of NetRexx as an easy way of writing portable java that will run on many platforms, and over the internet is seen as a big plus. You have the friendly syntax of Rexx with the advantages of Java.

Q: How do I use "stem" variables in NetRexx?

A: Stem variables in NetRexx are implemented using array syntax. In classic Rexx, you would use:

   
 /* */
  stem. = ''
  stem.1.name = 'this is a test'
  say stem.1.name' for me'

to access a stem element. To achieve this in NetRexx, use:

 
  /* */
  stem = ''
  stem[1,'name'] = 'this is a test'
  say stem[1,'name'] ' for me'

Note that you must either declare the stem as a variable of type Rexx, or use the NOBINARY option (the default), so that strings are Rexx strings, not java Strings.

Q: How do I enable tracing in NetRexx?

A: Tracing in NetRexx is not interactive at this point. It will show you only the statements being executed, not values of variables...you will need to Say any values you would like to see on the screen.

You can TRACE OFF, TRACE METHODS (traces method calls), TRACE ALL or TRACE RESULTS. Trace statements should be placed before the first method in a class to affect all methods. It can be used anywhere in a method to affect tracing.

Differences between NetRexx and Object Rexx

Q: Is NetRexx a superset or a subset of Object Rexx?

A: In short, neither. NetRexx is a deliberate break from some of the syntax of classic Rexx and Object Rexx in an effort to keep down the translation effort. The syntax is similar in many cases, but has some very noticeable deviations. For example, Object Rexx uses the twiddle character ~ as the message delimiter, whereas NetRexx uses the period.

Both are object oriented languages, with their heritage firmly based in classic Rexx.

NetRexx: Java in the clothes of REXX. It's advantage is that it's easier to code, taking advantage of previous REXX knowledge. It creates true and native (compilable) Java-code.

ObjectRexx: True, backwardly compatible with REXX.

Differences

Object Rexx is interpreted, NetRexx is translated to Java, which is then compiled.
Object Rexx is more of a Script/Macro and Application language. It allows for defining all sorts of objects, methods, messages, full-fledged classes at run-time, including definition of class and instance variables; allows for one-off objects (classes and instances), multiple-inheritance (dynamically changeable at run-time), etc.
NetRexx is bound to the Java architecture, e.g. it's not possible to define classes at run-time - except for loading text containing class definitions
NetRexx allows non-C-programmers to really tackle and master Java. It is syntactically easier to learn, easier to develop, maintain apps and therefore cheaper, due to its Rexx roots/layout.
ObjectRexx is a very different beast, and probably the easiest language to learn OO-stuff, due to its Rexx underpinning and it being an interpreter; e.g. one can directly experiment with various classes, especially WPS-, SOM- and DSOM.

Platform Info

Q: What environmental info is available to my NetRexx app?

A: System properties are always available. Use the following to access them:

  /* Get some system properties */
  OPTIONS BINARY NOTRACE
  propList = Rexx ''
  propList[0] = 14
  propList[1] = "java.version"
  propList[2] = "java.vendor"
  propList[3] = "java.vendor.url"
  propList[4] = "java.class.version"
  propList[5] = "java.class.path"
  propList[6] = "os.name"
  propList[7] = "os.version"
  propList[8] = "file.separator"
  propList[9] = "path.separator"
  propList[10] = "line.separator"
  propList[11] = "user.name"
  propList[12] = "user.home"
  propList[13] = "user.dir"
  propList[14] = "awt.toolkit"
  loop i = 1 to propList[0]
    Say "The value of "propList[i]" is: "System.getProperty(propList[i])
  end

Q: Which platforms will NetRexx run on?

A: NetRexx is written in NetRexx and will (hopefully) run on any platform on which java will run. I know that NetRexx has been successfully run on the following platforms: OS/2, AIX, Linux, Windows 95, Windows NT, Solaris 2.4 and 2.5, HP-UX 9.05, Win 3.1 (IBM ADK Beta 2 or greater), MVS.

If you have run NetRexx on another platform, please let me know!

Q: How do I get the operating system that my NetRexx app is running on?

A: Use this code:

 
  OSName = System.getProperty("os.name")
  OSVer  = System.getProperty("os.version")

Thanks to Craig Schwarze

Classes in NetRexx

Q: How can I split text into pieces?

A: You have two choices, using Parse or StringTokeniser.
For example:

    path = 'c:\;c:\os2;'
    parse path first ';' second ';'

Splits the path into the first two directories, breaking on a semicolon.
To do this using StringTokeniser:

 
    path = 'c:\;c:\os2;'
    StringTokenizer st = StringTokenizer(path, ';');
    first = st.nextToken
    second = st.NextToken

Q: How can I detect the right mouse button in NetRexx?

A: If the event modifier attribute passed to the mouseDown method when bitwise and'ed with Event.META_MASK gives 0 (i.e. e.modifiers & Event.META_MASK = 0), then button two has been pressed down.

Q: Can I simulate a tree-view container in NetRexx?

A: You need to create a Container or Panel subclass to simulate a tree view. There are 3rd party tree view container objects available on Gamelan, but it looks like most of them are commercial.

Q: I don't seem to find ANY Rexx.date() functions. Are they there, or do I use the Java date functions?

A: Use the java class. See the nrexx\qtime.nrx file for an example on how to do this.

Q: How do I create hierarchies of classes in NetRexx?

A: Use the package statement. e.g.

   

  /* My hierarchical class - in file Hello.nrx */
  package dions.classes
  class Hello
  method sayit
    Say 'Hello'

will create a file Hello.class, which you can reference by the fully qualified name, dions.classes.Hello

Q: How do use other peoples hierarchical classes in NetRexx?

A: Use the imports statement. e.g.

  /* My use of a hierarchical class - in file TestHello.nrx */
  imports dions.classes
    a = Hello
    a.sayit

will import all of the classes in dions/classes in one of the directories in your CLASSPATH, and create an object of class dions.classes.Hello, and run its sayit method.

Q: Why can I reference some methods without qualification, and others require it?

A: In general, you can call methods without qualifying them (i.e. without a class or object/variable name) when those methods are implemented/inherited by the class whose methods you are writing.
For example, the command setFont is referred to without qualification, while other examples use (as an example) Toolkit.getDefaultToolkit.getScreenSize. Let's take this code snippet from Pinger.nrx:

   setLayout(BorderLayout())         -- we must have a layout
   add("Center", PingerComponent())  -- add new pinger image
   this.pack                         -- recalculate the frame

   -- position centre-screen
   sizex=200; sizey=175
   screen=Toolkit.getDefaultToolkit.getScreenSize

The setLayout method is implemented in the applet class, or one of it's parents.

The screen variable is assigned the current screen size. It does this by accessing the Java Toolkit class, calling it's static method getDefaultToolkit which returns an object. This returned object has a method which will return the screen size.

When qualifying methods with a class name, rather than creating or declaring an object, you will be running a static method. If you would like to make your code more explicit, you can prefix methods on the active object with this. The setLayout call would look like this:

    this.setLayout(BorderLayout())  -- we must have a layout

NetRexx and Graphics

Q: How do I use sound from NetRexx?

A: For an applet, see the PlayClip example in the NetRexx package. For a stand-alone program that uses sound, see the Pinger example.
The OS/2 Warp BonusPak includes a Multimedia Viewer that has support for .au sound files as one of it's components. Use the install program on the BonusPak Installation disk, select Multimedai Viewer, then select AU/SND support.

Q: NetRexx's ability to control the layout of objects on a window seems quite limited. Is this true?

A: NetRexx uses LayoutManagers to control the positioning of objects within a window/panel/container. Rather than using absolute (x,y) positioning of objects within the container, you use relative positioning (such as "Object A is to the left of Object B") and then let the layoutmanager handle absolute positioning. There are several layoutmanagers in the base package, such as BorderLayout CardLayout, GridLayout, and GridBagLayout. You can create your own LayoutManager (by subclassing the default one and overriding methods). You can also use absolute positioning if you REALLY want to, but it is very frowned upon (much like including C++ native code in Java/NetRexx apps).

Q: Can I write graphical applications in NetRexx?

A: Yes. You can access the java.awt library from NetRexx, and even write Applets directly in NetRexx!

Q: How do I simulate the clipboard in NetRexx?

A: The TextArea class extends TextComponent, which has the following methods:

public String getSelectedText()
public int getSelectionEnd()
public int getSelectionStart()
public void selectAll()

Thanks to Craig Schwarze (arnie@mailbox.tabnsw.com.au)

Translator/Compiler errors

Q: How do I cast objects from one type to another?

A: Simply place the type that you would like the object to become, in front of the variable that holds it. e.g. You may see the following error message.

 
 175 +++   temp = e.arg
     +++          ^
     +++ Error: cannot.assign [java.lang.Object => java.lang.String]

This is NetRexx telling you that you are trying to assign variables of different types. Try the following instead:

temp = String e.arg

This takes the variable e.arg and casts it to a String.

Q: How do I fix "Applet can't start: class toast is not constructed properly" inside a browser?

A: Typically, this means you've tried to run a class that does not inherit from the Applet class. To run in a browser environment, you need to be running a subclass of that class.

Q: What does the NetRexx compiler error "invalid character" mean on the very last character?

A: Typically, this means you've edited NetRexx source with an editor that writes out either a null or EOF character to the end of the file. Remove this character, save and recompiler your NetRexx source.

Q: What does the java compiler error "Exception java.io.IOException must be caught, or it must be declared in the throws clause of this method" mean?

A: You are issuing a java method call that may throw an exception (unexpected condition). You must use the catch keyword to handle that exception, or use the Signals statement on the method definition. e.g.

   
  Do
    inRAFile = DataInputStream(FileInputStream(File(inFileName)))
  catch ex 
    inRAFile = null
  End

Here, the catch statement matches any exception thrown, and sets a variable to null as an indicator of the error condition.

Q: How do I fix Error: unknown.class [netrexx.lang.Rexx]?

A: This is usually the result of not following the installation instructions, or using an unzip that does not preserve case. Reinstall NetRexx using a working unzipper.

Q: Why do I get Java compiler errors sometimes, but not NetRexx compile errors?

A: NetRexx strives to pick up any situation that may lead to a java compiler error. It may not pick up all such errors, especially those involving exceptions needing to be caught. The java compile error should match the NetRexx line of code that caused the error.

Please report all of these to the NetRexx Mailing List.

Check the NRINST.DOC file for known restrictions in this area.

Q: How do I fix 'class xxx not found' errors?

A: NetRexx looks for classes in the CLASSPATH environment variable. The default classpath (i.e. not SET in CONFIG.SYS or anywhere else is .;x:\javaos2\classes;

This means it will search the current directory, the javaos2\classes and the standard java classes. The normal cause for this error is either:
- You've created your own SET CLASSPATH and left out one of the defaults

You didn't unzip the nrtools.zip (or other zip file) when installing
You're not using the full class name (i.e. myclass.category.className) and should be.

Q: How do I use objects I've stored in a Java Vector or Hashtable?

A: You will need to cast the objects retrieved from the Vector and/or HashTable to their original class to work with them. This is a feature of the classes, they only accept objects of type Object -- hence when you get them back out again you have to convert them back to their original class in order for them to work the way you expect. (You have to do this in Java, too -- though intuitively one feels that it shouldn't be necessary.) Hence you need:

  x.addElement(y)
  z=Oblong x.elementAt(1)  -- get the Object and make it an Oblong
  say z.print              -- print it

or

   
  x.addElement(y)
  say (Oblong x.elementAt(1)).print

Q: What does "Can't make static reference to method xxx.yyyy(zz) in class" mean?

A: Typically, you are trying to run a method that is not static, without first creating an object of that class.

Java

Q: Recommended Java books?

A: "Teach Yourself Java in 21 Days" by Laura Lemay and Charles L. Perkins. (SAMS.NET, Indianapolis, 1996, ISBN: 1-57521-030-4) "Java in a Nutshell" by David Flanagan (O'Reilly & Associates, Feb 1996, ISBN 1-56592-183-6) Also see Sun's list of java books at http://sunsite.unc.edu/javafaq/books.html for other books that have been published

Q: Is there a sample shipped with NetRexx that is a direct port of a Java app?

A: For a very small one, see NervousTexxt.nrx in the samples & examples. This is a one-for-one port of the NervousText.java example from the Sun java page. There are also ports of Java applets found on the FAC page. Also, try the -keep option on the NetRexx translator -- that will leave a copy of the Java produced by the translator, so you can compare directly. Remember the Freely Available Code page.

Q: Do I need to know Java to use NetRexx?

A: Knowledge of Java is not necessary to write standalone applications in NetRexx, although if you want to write Web Applets, or complex applications, you'll need to know how to access the Java API, and what it provides from NetRexx, until there are some books specifically written for NetRexx programming that introduce the Java API in native NetRexx syntax. See the NetRexx API Page for details on using java classes in NetRexx.

Q: Where can I get the Java API documentation?

A: The Java API documentation is shipped with the OS/2 JDK which you can get from IBM Hursley or you can download it from Sun's site.

Q: Where can I get the Java Language specification?

A: The Java Language spec is available from Sun

Q: Are there mailing lists on Java?

A:Yes. Sun has a listing of some Java mailing lists available from one of their many websites. See http://www.javasoft.com/mail.html for more info.

Q: Are there newsgroups for Java?

A:Yes.

- comp.lang.java.announce
- comp.lang.java.api
- comp.lang.java.misc
- comp.lang.java.programmer
- comp.lang.java.security
- comp.lang.java.setup
- comp.lang.java.tech
- alt.www.hotjava