PC Online 1997 May

home *** CD-ROM | disk | FTP | other *** search

/ PC Online 1997 May / PCO_5_97.ISO / FilesBBS / OS2 / NETREXX.ARJ / NETREXX.ZIP / NetRexx / nrinst.doc < prev next >

Wrap

Text File | 1997-01-03 | 27.5 KB | 682 lines

NetRexx 1.00 NetRexx Installation and User's Guide ===================================== Copyright(c) IBM Corporation, 1996, 1997. All rights reserved. Introduction """""""""""" This document is the "User's Guide" for the reference implementation of NetRexx. NetRexx is a new programming language; a blend of Rexx and Java; the rules of syntax closely follow those of Rexx, while the semantics often follow Java. It is a dialect of Rexx that is as efficient and portable as Java, while preserving the philosophy and ease of use of Rexx. This document covers: o Unpacking the NetRexx packages o Installing the NetRexx package -- documentation and samples o Installing the NetRexx executables (for any Java platform): o How to install the NetRexx compiler o Problem solving o How to install just the NetRexx runtime classes o Using the NetRexxC compiler o Using NetRexx classes with World Wide Web applets o Installing and using the NetRexx print package o Current restrictions, _etc._ The NetRexx documentation and software are distributed free of charge under the conditions of the IBM Employee Written Software program. If you download or use a NetRexx package you agree to the terms in the _IBM License Agreement_ included in the package as the file license.txt. For details of the NetRexx language, and the latest news, please see the NetRexx documentation included with this package or available on the World Wide Web, for example at: http://www2.hursley.ibm.com/netrexx/ Mike Cowlishaw IBM UK Laboratories Unpacking NetRexx packages """""""""""""""""""""""""" The NetRexx packages are shipped in two forms, identified by a suffix following the name: o .zip format -- commonly used on OS/2 and other operating systems for the IBM PC o .tar.Z format -- (tape archive plus compress) commonly used on AIX and other Unix systems. You probably know how to handle these, but a word of caution: the packages contain directory structures, and files with 'long names' (that is, not of 8.3 maximum length names) which are case-sensitive. Many utilities, including some versions of UNZIP and TAR, can lose case information, truncate names, or fail to restore directories. --- Unpacking .zip files --- The most common packages for 'unzipping' these are Info-ZIP and PKZIP: Here are some tips: o Ensure that you are unzipping to a disk that supports long file names (for example, an HPFS disk or equivalent on OS/2 or Windows). o Info-ZIP: use version 5.12 (August 1994) or later. The syntax for unzipping NetRexx.zip is simply unzip NetRexx which should create the files and directory structure directly. Please see later in this document for complete installation instructions. o PKZIP: use a version that supports long file names. The syntax for unzipping NetRexx.zip is pkunzip -d NetRexx which should create the files and directory structure directly. The '-d' flag indicates that directory structure should be preserved. --- Unpacking .tar.Z files --- You need an up-to-date version of two programs: 'tar' and 'uncompress'; these are available for most operating systems. Here are some tips: o Ensure that you are unpacking to a disk that supports long file names (for example, any Unix disk, or an HPFS disk or equivalent on OS/2 or Windows). o Ensure that the version of tar that you use preserves case in names. If all the files created by tar have all-lowercase names, you need a new version of tar. The process of unpacking the file takes two steps: 1. Uncompress the file, using uncompress (this may be called simply 'compress' on some systems). The syntax for uncompressing NetRexx.tar.Z is probably one of: uncompress NetRexx.tar.Z compress -d NetRexx.tar.Z (the '-d' means decompress, and may be optional). This should replace the file with one called NetRexx.tar 2. Unpack the files and directories from the .tar file. The syntax for this is tar -xvf NetRexx.tar This should create the files and directories from the package, displaying the name of each as it is unpacked. You may see error messages where directories already exist; these can be ignored. After unpacking the files, the .tar file can be erased. Installation procedure - online documentation and samples """"""""""""""""""""""""""""""""""""""""""""""""""""""""" The NetRexx package (NetRexx.zip, or NetRexx.tar.Z) contains the NetRexx online documentation, together with samples and examples, and the packages of executables. 1. Copy the package file to the root directory of your choice, preserving the original name. 2. With your chosen directory as your current directory, unpack the package, following the instructions in 'Unpacking NetRexx packages' above. This should add the directory 'NetRexx' to your chosen directory, containing the documentation and samples for NetRexx, along with the packages of executables. There should also be a subdirectory ('NetRexx/netrexx/lang' or 'NetRexx\netrexx\lang') containing runtime class files used by some of the samples. The online documentation comes in two forms: plain ASCII (files with extension '.doc'), and World Wide Web hypertext format (files with extension '.htm' or '.html', '.gif', etc.). To view the hypertext version, start your browser at the file "netrexx.htm". For example, if you are using the IBM Web Explorer then the command explore netrexx.htm (executed when the documentation directory is the current directory) should show the NetRexx front page. Included in the documentation collection are a number of examples and samples (Hello, HelloApplet, etc.). To run any of these, you must have the Java runtime environment installed. Some of the examples must be viewed using the Java toolkit applet-viewer or a Java-enabled browser. Please see the hypertext pages describing these for detailed instructions. In general, if you see a message from Java saying: void main(String argv[]) is not defined this means that the class cannot be run using just the 'java' command. Installation of NetRexx Executables """"""""""""""""""""""""""""""""""" [Note: if you installed NetRexx 0.88 (or an earlier version of NetRexx) please remove or rename the 'netrexx' directory under the Java 'classes' directory -- or wherever you put the NetRexx classes -- before installing later versions of NetRexx.] The NetRexx package includes two packages of software (each will have the same suffix as the package you unpacked it from, that is, '.zip' or '.tar.Z'): 1. nrtools -- the files for the NetRexx compiler, of which the most important is NetRexxC.zip, which contains the Java .class files that implement the compiler. The NetRexx compiler is in fact a translator; it translates NetRexx programs to Java source code, which is then compiled using the javac compiler (or you can use the Java compiler of your choice, if you prefer). This package requires that the Java toolkit (1.x) be installed. nrtools also includes a separate copy of the NetRexx runtime classes, in NetRexxR.zip 2. nrping -- the Pinger sample application. Please see Pinger.htm for information about this. To install and use either of these packages, you must have already installed the Java Development Kit (JDK) runtime (and toolkit, if you want to compile NetRexx programs). For more information on these: o For OS/2 and AIX and other IBM operating systems, see the _IBM Centre for Java Technology_ page at: http://ncc.hursley.ibm.com/javainfo/hurindex.html o For other operating systems, see the _Sun Microsystems Java_ page at http://www.javasoft.com, or other suppliers of Java toolkits. Installation of the NetRexx compiler '''''''''''''''''''''''''''''''''''' Here's how to install the NetRexx compiler and runtime classes: 1. Copy the 'nrtools.zip' or 'nrtools.tar.Z' file from the NetRexx documentation directory to the Java home directory, using the original name. The name of the Java home directory will vary depending on the operating system you are using. Some possibilities are: /java /jdk1.1/java \javaos2 \jdk1.1\java It will contain directories such as 'bin' and 'lib'. [Note: if your Java home directory is on a CD-ROM, or otherwise inaccessible, you'll need to choose a different directory and set up a CLASSPATH environment variable that points to it. Consult your Java toolkit documentation for details on how to do this. You'll also need to set the NetRexx home directory -- see below.] 2. With the Java home directory as your current directory, unpack the package, following the instructions in "Unpacking NetRexx packages" above. This should add the .zip files for the NetRexx runtime and compiler classes (NetRexxR.zip and NetRexxC.zip) and the compiler's error message file (NetRexxC.properties) to the Java 'lib' directory. In addition, some sample scripts and a test program should have been added to the Java 'bin' directory: hello.nrx -- a simple NetRexx program for testing NetRexxC.cmd -- the NetRexx compiler command in Rexx NetRexxC.bat -- similar NetRexx compiler command (Windows .bat) nrc.cmd -- shorter name for NetRexxC.cmd nrc.bat -- shorter name for NetRexxC.bat The .cmd files are simple Rexx scripts for making it easier to use the compiler. You don't have to use these, but they save some typing. They should require little modification to run under the Rexx interpreter for your platform; for details of Rexx interpreters, see: http://www2.hursley.ibm.com/rexx/ Under Windows, the .bat files should work -- they are not as flexible as the .cmd files, but will save typing. 3. Check that the names are correct in the 'lib' directory: there should be a file in the directory called 'NetRexxC.properties'; if the name is all in lowercase, or the word 'properties' is truncated, the package has not been unpacked correctly (see "Unpacking NetRexx packages"). 4. For Java to be able to find the NetRexx classes, you must update the CLASSPATH environment variable by adding the full path and name of the NetRexxC.zip file to the CLASSPATH setting. There will often already be a CLASSPATH variable set, including a path to the standard Java classes.zip file. Specify or add the full path (disk, directories, and file specification) for NetRexxC.zip, making sure that the case of every letter is exactly right (Java is very case-sensitive). For example, the full path might be something like: e:\java1.1\java\lib\NetRexxC.zip The procedure for setting the CLASSPATH variable depends on your operating system (and there may be more than one way). Here are some examples: o In OS/2 or Windows, use a SET CLASSPATH= command in CONFIG.SYS (for OS/2) or in AUTOEXEC.BAT (for Windows) and re-boot after changing. In both cases the command syntax is the same, and might look like this: set classpath=.;f:\javaos2\lib\NetRexxC.zip In this example, the first segment of the value (before the semicolon) lets classes in the current directory be found, and the second segment includes the classes needed by NetRexx. Both environments normally include the standard Java classes automatically. o For Unix (Korn shell or Bourne shell), use: CLASSPATH=<newdir>:$CLASSPATH export CLASSPATH and changes for re-boot or opening of a new window should be placed in your .login (Bourne) or .profile (Korn) file o For Unix (C shell), use: setenv CLASSPATH <newdir>:$CLASSPATH and 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. Note: If you add NetRexxC.zip to the CLASSPATH value then you do not need to add NetRexxR.zip; the latter contains only the NetRexx runtime classes (which are provided separately for people who don't want to run the NetRexx compiler). These runtime classes are also included in NetRexxC.zip. Whichever zip is used, the NetRexx runtime classes can be referred to from Java or NetRexx as being in the 'netrexx.lang' package. For example, a string might be of class 'netrexx.lang.Rexx'. --- Checking your installation is correct --- To check installation, change directory to the Java 'bin' directory, then (being very careful to get the case of letters correct): o Enter the command java COM.ibm.netrexx.process.NetRexxC hello This should run the NetRexx compiler, which converts 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 'hello.class'. The intermediate .java file is then deleted, unless an error occurred. o Enter the command java hello This runs (interprets bytecodes from) 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 (see above) so Java can find it. With the sample scripts provided (NetRexxC.cmd or NetRexxC.bat), or the equivalent in the scripting language of your choice, the steps above can be combined into a simple single command: NetRexxC -run hello This package also includes a trivial 'nrc.cmd' and matching 'nrc.bat' file that simply passes on its 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; unless running the OS/2 Rexx script, you will probably have to spell the name of the program exactly as it appears in the filename. You could also edit the nrc.cmd or nrc.bat and add your favourite 'default' NetRexxC options there (if you do this, keep a backup copy, so that if you install a new version of the NetRexx package you won't overwrite your changes). --- The NetRexx Home directory --- If you need to put the NetRexxC.properties (messages) file into a directory other than the 'lib' directory below the Java home directory, then you can set an alternative directory path that NetRexx will use to find the messages file. This alternative directory is called the NetRexx home directory and may be set using the -D option on the java command that invokes the NetRexx compiler. For example (perhaps for an OS/2 or Windows system): java -Dnetrexx.home=f:\nrhome COM.ibm.netrexx.process.NetRexxC hello which sets the directory path 'f:\nrhome' as the NetRexx home directory. With this setting, NetRexxC would look for the messages file as: f:\nrhome\lib\NetRexxC.properties In other words, NetRexxC expects its properties file to be in the 'lib' directory below the NetRexx home directory, and the default NetRexx home directory is the Java home directory. If you are using the NetRexxC.cmd on OS/2 to invoke the compiler, then this -D option will be set up automatically if the path is set as the value of an environment variable called NETREXX_HOME. Problems? ''''''''' If the 'hello' example doesn't work, one of the following problems may be the cause: o A "Can't find class COM.ibm.netrexx.process.NetRexxC..." message probably means that the NetRexxC.zip file has not been specified in your CLASSPATH setting. This is the setting that Java uses to find classes for execution; please refer to your Java installation instructions for information on setting the CLASSPATH. o A "Can't find class hello..." message may mean that the directory with the .class file is not in your CLASSPATH, or either the filename or name of the class (in the source) is spelled wrong (the java command is [very] case-sensitive). o You didn't install on a file system that supports long file names (for example, on OS/2 or Windows you should use an HPFS disk or equivalent). Like most Java applications, NetRexx uses long file names. o You have a down-level Unzip or Tar program. Check that the file 'NetRexxC.properties', with just three capital letters and neither part of the name truncated, exists in the subdirectory 'lib' below the Java home directory. o You have only the Java runtime installed, and not the toolkit. If the toolkit is installed, you should have a program called javac on your computer. o You have a down-level version of Java installed. NetRexxC will run on Java versions 1.0.1, 1.0.2, 1.1 (and probably later versions). You can check the version of Java you have installed using the command 'java -version'. o Your Java toolkit installation has .class files from an earlier installation in classes/java/lang, classes/netrexx/lang, or other subdirectories in the 'classes' directory below the Java home directory. A message that reports ambiguous class references is a likely sign of this problem. The easiest way to solve it is to re-install the Java toolkit in a clean subdirectory. o If, when reporting an error or warning, the compiler gives a rather cryptic identifier and reports 'Sorry, full message not available', this means that it could not find the NetRexxC.properties (error messages) file. Installation of just the NetRexx classes '''''''''''''''''''''''''''''''''''''''' To install only the NetRexx runtime classes (you don't need to do this if you already installed the NetRexxC compiler), follow the instructions for installing the compiler, but set your CLASSPATH to refer to NetRexxR.zip instead of NetRexxC.zip. Only the NetRexxR.zip is needed, so you may prefer to extract just this file from the nrtools package. The NetRexx class files can then be referred to from Java or NetRexx programs as from package 'netrexx.lang'. For example, a string might be of class 'netrexx.lang.Rexx'. Using the NetRexx compiler """""""""""""""""""""""""" 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. --- Invoking the compiler as a command --- 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 program names (the program files to be compiled). NetRexxC will add the extension '.nrx' to input program names (file specifications) if no extension was given. So, for example, to compile 'hello.nrx', 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. On completion, the command will exit with one of three return values: 0 if the compilation 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: o -keep keep the intermediate .java file. It is kept as xxx.java.keep, where xxx is the source file name. The file will be kept automatically if the javac compilation fails for any reason. o -nocompile do not compile (just translate). The intermediate Java program is kept as the file xxx.java, where xxx is the source file name. Use this option when you want to use a different Java compiler. o -time display translation, compile, and total times (for all files processed). If you are using the provided NetRexxC or nrc scripts, then an additional option is available: o -run run the resulting JAVA class as a stand-alone application, provided that the compilation had no errors. 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 -noverbose -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. See also the earlier section "The NetRexx home directory" if you need to change the place where the compiler finds its messages (for example, if error messages report 'Sorry, full message unavailable'). --- Invoking the compiler from Java --- The compiler may also 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) constant 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 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. 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. NetRexx classes and Applets for the Web """"""""""""""""""""""""""""""""""""""" If you write applets for the World Wide Web (or your intranet) in NetRexx, you will probably need to use the NetRexx classes (netrexx.lang.Rexx, _etc._); they will be used automatically if the default compilation options (specifically, options nobinary) are in effect. A good way of setting up an HTTP (Web) server for this is to keep all your applets in one subdirectory; you can then make the NetRexx runtime classes (that is, the classes in the package known by Java as netrexx.lang) available to all the applets by unzipping NetRexxR.zip into a subdirectory netrexx/lang below your applets directory. For example, if the root of your server tree is D:/mydata then you might put your applets into D:/mydata/applets and then the NetRexx classes (unzipped from NetRexxR.zip) should be in the directory D:/mydata/applets/netrexx/lang The same principle is applied if you have any other Java packages that you want to make available to your applets: the classes in a package called fred.math.quicksorts would go in a subdirectory below applets called fred/math/quicksorts, for example. Note that with Java 1.1 it should be possible to use the classes direct from the NetRexxR.zip file, providing that the browser being used is at a Java 1.1 level. See the Java 1.1 documentation for details. Printable documentation """"""""""""""""""""""" The NetRexx printable package (NetRexxD.zip, or NetRexxD.tar.Z) contains the printable NetRexx documentation, in PostScript format. 1. Copy the package file to the root directory of your choice for documentation, preserving the original name. 2. With your chosen directory as your current directory, unpack the package, following the instructions in 'Unpacking NetRexx packages' above. This should add the directory 'NetRexxD' to your chosen directory, containing the printable documentation for NetRexx. 3. You can print files from the new directory that have the extension '.ps' on any PostScript printer, using the appropriate method for printing for your operating system. There are also utilities, such as 'GhostScript', available from public sources for viewing PostScript files and for printing them on non-PostScript printers. Current restrictions """""""""""""""""""" The NetRexx processor is now functionally complete, though work continues on usability and performance improvements. As of this version there are still a number of restrictions, listed below. Please note that the presence of an item in this section is not a commitment to remove a restriction in some future update; NetRexx enhancements are dependent on on-going research, your feedback, and available resources. You should treat this list as a 'wish-list' (and please send in your wishes). --- Short-term restrictions --- NetRexxC by default uses the javac compiler to generate bytecodes (class file). o The 1.0 javac compiler will not let you compile a class that has the same name as a class in java.lang. This has been fixed for 1.1. The following problem may occur in larger methods, with Java 1.0.1 or 1.0.2 (it has been fixed in 1.1): o NetRexxC does not restrict the number of local variables used or generated. However, the 1.0 javac compiler fails with unrelated error messages (such as 'statement unreachable' or 'variable may be uninitialized') if asked to handle more than 63 local variables. --- Long term restrictions --- The following restrictions are due to the use of a translator, and would probably only be lifted if a direct-to-bytecodes NetRexx compiler were built. o Externally-visible names (property, method, and class names) cannot be Java reserved words (you probably want to avoid these anyway). JAVAC will report these, giving the line numbers in your NetRexx program. o Some binary floating point underflows may be treated as zero instead of being trapped as errors. o Side-effects of calls to this() and super() in constructors may be seen before the method and method call instructions are traced -- this is because Java does not permit tracing instructions to be added before the call to this() or super(). o The results of expressions consisting of the single term 'null' are not traced.