Testing the NetRexx Installation

Cours testing the NetRexx Installation, tutoriel & guide de travaux pratiques en pdf.

Installation

This chapter of the document tells you how to unpack, install, and test the NetRexx translator package. This will install documentation, samples, and executables. It will first state some generic steps that are sufficient for most users. The appendices contain very specific instructions for a range of platforms that NetRexx is used on. Note that to run any of the samples, or use the NetRexx translator, you must have already in-stalled the Java runtime (and toolkit, if you want to compile NetRexx programs using the default compiler). The NetRexx samples and translator, as of version 3.01, will run on Java version 1.5 or later4. To do anything more than run NetRexx programs with the runtime package, a Java software development kit is required. You can test whether Java is installed, and its version, by trying the following command at a command prompt:
java –version
which should display a response similar to this:
java version ”1.6.0_26”
Java(TM) SE Runtime Environment (build 1.6.0_26-b03-383-11A511)
Java HotSpot(TM) 64-Bit Server VM (build 20.1-b02-383, mixed mode)
For more information on Java installation:
1. For some operating environments
2. For other operating systems, see the Oracle Java web page5 – or other suppliers of Java toolkits.

Unpacking the NetRexx package
The NetRexx package is shipped as a collection of files compressed into the file Net-Rexx<version>.zip. Most modern operating environments can uncompress a .zip pack-age by doubleclicking.

Unpacking the NetRexx.zip file
An unzip command is included in most Linux distributions, and Mac OSX. You can also use the jar command which comes with all Java development kits. Choose where you want the NetRexx directory tree to reside, and unpack the zip file in the directory which will be the parent of the NetRexx tree. Here are some tips: The syntax for unzipping NetRexx.zip is simply
unzip NetRexx
which should create the files and directory structure directly.
. WinZip: all versions may be used
. Linux unzip: use the syntax: unzip –a NetRexx. The “–a” flag will automatically convert text files to Unix format if necessary
. jar: The syntax for unzipping NetRexx.zip is jar xf NetRexx.zip
which should create the files and directory structure directly. The “x” indicates that the contents should be extracted, and the “f” indicates that the zip file name is specified. Note that the extension (.zip) is required.
After unpacking, the following directories1 should have been created: -TODO-

Installing the NetRexx Translator

The NetRexx package includes the NetRexx translator – a Java application which can be used for compiling, interpreting, or syntax-checking NetRexx programs. The procedure for installation is briefly as follows6 (full details are given later):
1. Make the translator visible to the Java Virtual Machine (JVM) – either:
.Add the full path and filename of the NetRexx/lib/NetRexxC.jar to the CLASS-PATH environment variable for your operating system. Note: if you have a Net-RexxC.zip in your CLASSPATH from an earlier version of NetRexx, remove it (NetRexxC.jar replaces NetRexxC.zip).
.Or (deprecated): Copy the file NetRexx/lib/NetRexxC.jar to the jre/lib/ext direc-tory in the Java installation tree. The JVM will automatically find it there and make it available7.
2. Copy all the files in the NetRexx/bin directory to a directory in your PATH (perhaps the /bin directory in the Java installation tree). This is not essential, but makes shorthand scripts and a test case available.
3. Make the file /lib/tools.jar (which contains the javac compiler) in the Java tree visible to the JVM. You can do this either by adding its path and filename to the CLASSPATH environment variable, or by moving it to the jre/lib/ext directory in the Java tree. This file sometime goes under different names, that will be mentioned in the platform-specific appendices.
4. Test the installation by making the /bin directory the current directory and issuing the following two commands exactly as written:
java org.netrexx.process.NetRexxC hello java hello
The first of these should translate the test program and then invoke the javac com-piler to generate the class file (hello.class) for the program. The second should run the program and display a simple greeting.
6 For Windows operating system, forward slashes are backslashes.
7 This has serious drawbacks, however: This breaks NetRexx applications running in custom class loader environments such as jEdit and NetRexxScript, as well as some JSP containers. As soon as the Java version is updates, NetRexx applications may mysteriously – due to the now obsolete path – fail. Running multiple versions of Java and NetRexx for testing purposes will become very hard when this way of installing is chosen.
If you have any problems or errors in the above process, please read the detailed in-structions and problem-solving tips that follow.

Installing just the NetRexx Runtime
If you only want to run NetRexx programs and do not wish to compile or interpret them, or if you would like to use the NetRexx string (Rexx) classes from other languages, you can install just the NetRexx runtime classes.
To do this, follow the appropriate instructions for installing the compiler, but use the NetRexxR.jar instead of NetRexxC.jar. The NetRexxR.jar file can be found in the Ne-tRexx/runlib directory.
You do not need to use or copy the executables in the NetRexx/bin directory.
The NetRexx class files can then be referred to from Java or NetRexx programs by importing the package netrexx.lang. For example, a string might be of class net-rexx.lang.Rexx.
For information on the netrexx.lang.Rexx class and other classes in the runtime, see the NetRexx Language Reference document.
note If you have already installed the NetRexx translator (NetRexxC.jar) then you do not need to install NetRexxR.jar; the latter contains only the NetRexx runtime classes, and these are already included in NetRexxC.jar.

Setting the CLASSPATH
Most implementations of Java use an environment variable called CLASSPATH to indi-cate a search path for Java classes. The Java Virtual Machine and the NetRexx transla-tor rely on the CLASSPATH value to find directories, zip files, and jar files which may contain Java classes. The procedure for setting the CLASSPATH environment variable depends on your operating system (and there may be more than one way). Please refer to Appendix 1 for your specific platform.
. For Linux and Unix (BASH, Korn, or Bourne shell), use:
CLASSPATH=<newdir>:\$CLASSPATH export CLASSPATH
. Changes for re-boot or opening of a new window should be placed in your /etc/profile,
.login, or .profile file, as appropriate.
. For Linux and Unix (C shell), use:
setenv CLASSPATH <newdir>:\$CLASSPATH
Changes for re-boot or opening of a new window should be placed in your .cshrc file. If you are unsure of how to do this, check the documentation you have for installing the Java toolkit.
. For Windows operating systems, it is best to set the system wide environment, which is accessible using the Control Panel (a search for “environment” offsets the many attempts to relocate the exact dialog in successive Windows Control Panel versions somewhat).
. In Windows Powershell, limitations set by the administrator can determine which kind of scripting (using Powershell, not NetRexx ) can be undertaken. It might be difficult to modify the enviroment, and a different from scripting under the cmd.exe processor is that the environment is local to an execution unit of a line. When chang-ing the environment is allowed, and a Powershell script is used to start the NetRexx translator, this is how it can be done:
$env:path = ”c:\program files\java\jdk1.7.0_02\bin;\Users\rvjansen\bin;” $env:classpath = ”.;\Users\rvjansen\lib\NetRexxC.jar”
. When using an IBM JVM or JRE, make sure that the file vm.jar is on the CLASS-PATH – NetRexx will complain about missing java.lang.Object when it is not.

Testing the NetRexx Installation

After installing NetRexx, it is recommended that you test that it is working correctly. If there are any problems, check the Installation Problems section. To test your installation, make the directory to which you copied the executables the current directory, then (being very careful to get the case of letters correct):

1. Enter the command
java org.netrexx.process.NetRexxC hello
Make sure that the userid that you are using for this has write authorization for the directory that contains the source.8 This should run the NetRexx compiler, which first translates the NetRexx program hello.nrx to the Java program hello.java. It then invokes the default Java compiler (javac), to compile the file hello.java to make the binary class file hello.class. The intermediate .java file is then deleted, unless an error occurred or you asked for it to be kept.
2. Enter the command
java hello
This runs (interprets the bytecodes in) the hello.class file, which should display a simple greeting. On some systems, you may first have to add the directory that contains the hello.class file to the CLASSPATH setting so Java can find it.
3. With the sample scripts provided (NetRexxC.cmd, NetRexxC.bat, or NetRexxC.sh,), or the equivalent in the scripting language of your choice, the steps above can be combined into a simple single command such as:
NetRexxC.sh –run hello
This package also includes a trivial nrc, and matching nrc.cmd and nrc.bat scripts, which simply pass on their arguments to NetRexxC; “nrc” is just a shorter name that saves keystrokes, so for the last example you could type:
nrc –run hello
Note that scripts may be case-sensitive, and you will probably have to spell the name of the program exactly as it appears in the filename. Also, to use –run, you may need to omit the .nrx extension. You could also edit the appropriate nrc.cmd, nrc.bat, or nrc script and add your favourite “default” NetRexxC options there. For example, you might want to add the –prompt flag (described later) to save
8 For example, more modern versions of Windows do not allow non-admin userids to write into the program files directories. In this case, make a directory under your home directory and copy the hello.nrx file there, and start the nrc command from the same location. reloading the translator before every compilation. If you do change a script, keep a backup copy so that if you install a new version of the NetRexx package you won’t overwrite your changes.

Introduction 
1 A Quick Tour of NetRexx 
1.1 NetRexx programs
1.2 Expressions and variables
1.3 Control instructions
1.4 NetRexx arithmetic
1.5 Doing things with strings
1.6 Parsing strings
1.7 Indexed strings
1.8 Arrays
1.9 Things that aren’t strings
1.10 Extending classes
1.11 Tracing
1.12 Binary types and conversions
1.13 Exception and error handling
1.14 Summary and Information Sources
2 Installation 
2.1 Unpacking the NetRexx package
2.2 Installing the NetRexx Translator
2.3 Installing just the NetRexx Runtime
2.4 Setting the CLASSPATH
2.5 Testing the NetRexx Installation
3 Installing on an IBM Mainframe 
4 Running on a JRE-only environment
4.1 Eclipse Batch Compiler
4.2 The nrx.compiler property
4.3 Interpreting
5 Using the translator 
5.1 Using the translator as a Compiler
5.2 The translator command
5.3 Compiling multiple programs and using packages
5.4 Programmatic use of the NetRexxC translator
6 Using the prompt option 
6.1 Using the translator as an Interpreter
6.2 Interpreting – Hints and Tips
6.3 Interpreting – Performance
7 Troubleshooting 
8 Current Restrictions 
8.1 General restrictions
8.2 Compiler restrictions
8.3 Interpreter restrictions
Index