User's Guide - Using the NetRexxA API

NetRexx User's Guide, version 2.02 Copyright (c) IBM Corporation, 2001. All rights reserved. ©	Draft of 22 May 2001
[previous \| contents \| next]

Using the NetRexxA API

As described elsewhere, the simplest way to use the NetRexx interpreter is to use the command interface (NetRexxC) with the -exec or -arg flags. There is a also a more direct way to use the interpreter when calling it from another NetRexx (or Java) program, as described here. This way is called the NetRexxA Application Programming Interface (API).

The NetRexxA class is in the same package as the translator (that is, COM.ibm.netrexx.process), and comprises a constructor and two methods. To interpret a NetRexx program (or, in general, call arbitrary methods on interpreted classes), the following steps are necessary:

Construct the interpreter object by invoking the constructor NetRexxA(). At this point, the environment's classpath is inspected and known compiled packages and extensions are identified.
Decide on the program(s) which are to be interpreted, and invoke the NetRexxA parse method to parse the programs. This parsing carries out syntax and other static checks on the programs specified, and prepares them for interpretation. A ‘stub’ class is created and loaded for each class parsed, which allows access to the classes through the JVM reflection mechanisms.
At this point, the classes in the programs are ready for use. To invoke a method on one, or construct an instance of a class, or array, etc., the Java reflection API (in java.lang and java.lang.reflect) is used in the usual way, working on the Class objects created by the interpreter. To locate these Class objects, the API's getClassObject method must be used.

Once step 2 has been completed, any combination or repetition of using the classes is allowed. At any time (provided that all methods invoked in step 3 have returned) a new or edited set of source files can be parsed as described in step 2, and after that, the new set of class objects can be located and used. Note that operation is undefined if any attempt is made to use a class object that was located before the most recent call to the parse method.

Here's a simple example, a program that invokes the main method of the hello.nrx program's class:

  -- Try the NetRexxA interface

  options binary

  import COM.ibm.netrexx.process.NetRexxA

  

  interpreter=NetRexxA()             -- make interpreter

  

  files=['hello.nrx']                -- a file to interpret

  flags=['nocrossref', 'verbose0']   -- flags, for example

  interpreter.parse(files, flags)    -- parse the file(s), using the flags

  

  helloClass=interpreter.getClassObject(null, 'hello') -- find the hello Class

  

  -- find the 'main' method; it takes an array of Strings as its argument

  classes=[interpreter.getClassObject('java.lang', 'String', 1)]

  mainMethod=helloClass.getMethod('main', classes)

  

  -- now invoke it, with a null instance (it's static) and an empty String array

  values=[Object String[0]]

  

  loop for 10    -- let's call it ten times, for fun...

    mainMethod.invoke(null, values)

  end

Compiling and running (or interpreting!) this example program will illustrate some important points, especially if a trace all instruction is added near the top. First, the performance of the interpreter (or indeed the compiler) is dominated by JVM and other start-up costs; constructing the interpreter is expensive as the classpath has to be searched for duplicate classes, etc. Similarly, the first call to the parse method is slow because of the time taken to load, verify, and JIT-compile the classes that comprise the interpreter. After that point, however, only newly-referenced classes require loading, and execution will be very much faster.

The remainder of this section describes the constructor and the two methods of the NetRexxA class in more detail.

The NetRexxA constructor

Syntax:

  NetRexxA()

This constructor takes no arguments and builds an interpeter object. This process includes checking the classpath and other libraries known to the JVM and identifying classes and packages which are available.

The parse method

Syntax:

  parse(files=String[], flags=String[]) returns boolean

The parse method takes two arrays of Strings. The first array contains a list of one or more file specifications, one in each element of the array; these specify the files that are to be parsed and made ready for interpretation.

The second array is a list of zero or more option words; these may be any option words understood by the interpreter (but excluding those known only to the NetRexxC command interface, such as time).^[1] The parse method prefixes the nojava flag automatically, to prevent .java files being created inadvertently. In the example, nocrossref is supplied to stop a cross-reference file being written, and verbose0 is added to prevent the logo and other progress displays appearing.

The parse method returns a boolean value; this will be 1 (true) if the parsing completed without errors, or 0 (false) otherwise. Normally a program using the API should test this result an take appropriate action; it will not be possible to interpret a program or class whose parsing failed with an error.

The getClassObject method

Syntax:

  getClassObject(package=String, name=String [,dimension=int]) returns Class

This method lets you obtain a Class object (an object of type java.lang.Class) representing a class (or array) known to the interpreter, including those newly parsed by a parse instruction.

The first argument, package, specifies the package name (for example, ‘com.ibm.math’). For a class which is not in a package, null should be used (not the empty string, '').

The second argument, name, specifies the class name (for example, ‘BigDecimal’). For a minor (inner) class, this may have more than one part, separated by dots.

The third, optional, argument, specifies the number of dimensions of the requested class object. If greater than zero, the returned class object will describe an array with the specified number of dimensions. This argument defaults to the value 0.

An example of using the dimension argument is shown above where the java.lang.String[] array Class object is requested.

Once a Class object has been retrieved from the interpreter it may be used with the Java reflection API as usual. The Class objects returned are only valid until the parse method is next invoked.

Footnotes:

[1]	Note that the option words are not prefixed with a ‘`-`’.

[previous | contents | next]