The installation instructions for the NetRexx compiler describe how to use the package you installed to compile and run a simple NetRexx program. This section explains more of the options available to you.
The compiler is a Java program (class) which is called COM.ibm.netrexx.process.NetRexxC (NetRexxC for short). This can be invoked using the Java interpreter, for example, by the command:
java COM.ibm.netrexx.process.NetRexxC
or by using a system-specific command (such as 'NetRexxC' or 'nrc'). In either case, the compiler invocation is followed by one or more file specifications (these are the names of the files containing the NetRexx source code for the programs to be compiled).
File specifications may include a path; if no path is given then NetRexxC will look in the current (working) directory for the file. NetRexxC will add the extension '.nrx' to input program names (file specifications) if no extension was given.
So, for example, to compile 'hello.nrx' in the current directory, you can use any of:
java COM.ibm.netrexx.process.NetRexxC hello java COM.ibm.netrexx.process.NetRexxC hello.nrx NetRexxC hello.nrx nrc hello
(the first two should always work, the last two require that the system-specific command be available). The resulting .class file is placed in the current directory, and the .crossref (cross-reference) file is placed in the same directory as the source file (if there are any variables and the compilation has no errors).
Here's an example of compiling two programs, one of which is in the directory 'D:\myprograms':
nrc hello d:\myprograms\test2.nrx
In this case, again, the .class file is placed in the current directory.
Note that when more than one program is specified, they are all compiled with the same class context: that is, they can 'see' the classes, properties, and methods of the other programs being compiled, much as though they were all in one file. This allows mutually interdependent programs and classes to be compiled in a single operation (but see the section "Compiling multiple programs" below, if you use the PACKAGE instruction).
The programs do, however, maintain their independence (that is, they may have different options, import, and package instructions).
On completion, the NetRexxC command will exit with one of three return values: 0 if the compilation of all programs was successful, 1 if there were one or more Warnings, but no errors, and 2 if there were one or more Errors.
As well as file names, you can also specify various option words, which are distinguished by the first character of the word being '-'. These may be any of the option words allowed on the NetRexx OPTIONS instruction (see the NetRexx language documentation), prefixed with '-'. These options words can be freely mixed with file specifications.
The compiler also implements some additional option words, which cannot be used on the OPTIONS instruction:
If you are using the provided NetRexxC or nrc scripts, then an additional option is available:
Here are some examples:
java COM.ibm.netrexx.process.NetRexxC hello -keep -strictargs java COM.ibm.netrexx.process.NetRexxC -keep hello wordclock java COM.ibm.netrexx.process.NetRexxC hello wordclock -nocompile nrc hello nrc hello.nrx nrc -run hello nrc -run Spectrum -keep nrc hello -binary -verbose1 nrc hello -noconsole -savelog -format -keep
Option words may be specified in lowercase, mixed case, or uppercase. File specifications are platform-dependent and may be case sensitive, though NetRexxC will always prefer an exact case match over a mismatch.
Note that the -run option is implemented by the script, not the compiler; some scripts (such as NetRexxC.bat) may require that the '-run' be the first word of the command arguments, and/or be in lowercase. They may also require that only the name of the file be given if the -run option is used.
When you specify more than one program for NetRexxC to compile, they are all compiled with the same class context: that is, they can 'see' the classes, properties, and methods of the other programs being compiled, much as though they were all in one file.
This allows mutually interdependent programs and classes to be compiled in a single operation. For example, consider the following two programs (assumed in your current directory, as the files X.nrx and Y.nrx):
/* X.nrx */
class X
why=Y null
/* Y.nrx */
class Y
exe=X null
each contains a reference to the other, so neither can be compiled in isolation. However, if you compile them together, using the command:
nrc X Y
then the cross-references will be resolved correctly.
The total elapsed time will be significantly less, too, as the classes on the CLASSPATH need to be located only once, and the class files used by the NetRexxC compiler or the programs themselves will also only be loaded once.
This example works as you would expect for programs that are not in packages. There's a restriction, though, if the classes you are compiling are in packages (that is, they include a PACKAGE instruction). Currently, NetRexxC uses the javac compiler to generate the .class files, and for mutually-dependent files like these, javac requires that the source files be in the Java CLASSPATH, in the sub-directory described by the PACKAGE instruction.
So, for example, if your project is based on the tree:
D:\myproject
then if the two programs above specified a package, thus:
/* X.nrx */
package foo.bar
class X
why=Y null
/* Y.nrx */
package foo.bar
class Y
exe=X null
then:
With this procedure, you should end up with the .class files in the same directory as the .nrx files, and therefore also on the CLASSPATH and immediately usable by other packages. In general, this arrangement is recommended whenever you are writing programs that reside in packages.
Note that when javac is used to generate the .class files, no new .class files will be created if any of the programs being compiled together had errors -- this avoids accidentally generating mixtures of new and old .class files that cannot work with each other.
Note also that if class is abstract or is an adapter class then it should be placed in the list before any classes that extend it (as otherwise any automatically generated methods will not be visible to the subclasses).
The compiler may be called from a Java program directly, by invoking the method in the COM.ibm.netrexx.process.NetRexxC class described as follows:
method main(arg=Rexx, log=PrintWriter null) static returns int
The Rexx string passed to the method can be any combination of program names and options (except -run), as described above. A sample NetRexx program that invokes the NetRexx compiler to compile a program called 'test' is:
/* compiletest.nrx */ s='test -keep -verbose4 -utf8' say COM.ibm.netrexx.process.NetRexxC.main(s)
The returned int value will be one of the return values described above.
The second argument to the main method is an optional PrintWriter stream. If provided, compiler messages will be written to that stream (in addition to displaying them on the console, unless -noconsole is specified). It is the responsibility of the caller to create the stream (autoflush is recommended) and to close it after calling the compiler. The -savelog compiler option is ignored if a PrintWriter is provided (the -savelog option creates a PrintWriter for the file NetRexxC.log).
NetRexxC is thread-safe (the only static properties are constants), but it is not known whether javac is thread-safe. Hence the invocation of multiple instances of NetRexxC on different threads should probably specify -nocompile, for safety.
[ previous section | contents | next section ]
From 'nrinst.doc', version 1.148.
Copyright(c) IBM Corporation, 1996, 1998. All rights reserved. ©