home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 18 REXX / 18-REXX.zip / netrx116.zip / nrinst.doc < prev    next >
Text File  |  2000-07-11  |  43KB  |  1,025 lines
  1.                                                            NetRexx 1.160
  2. NetRexx Installation and User's Guide
  3. =====================================
  4.  
  5. Copyright(c) IBM Corporation, 1996, 2000.  All rights reserved.
  6.  
  7.  
  8. Introduction
  9. """"""""""""
  10. This document is the "User's Guide" for the reference implementation of
  11. NetRexx.
  12.  
  13. NetRexx is a new programming language; a blend of Rexx and Java; the
  14. rules of syntax closely follow those of Rexx, while the semantics often
  15. follow Java.  It is a dialect of Rexx that is as efficient and portable
  16. as Java, while preserving the philosophy and ease of use of Rexx.
  17.  
  18. This document covers:
  19.  
  20.   o Unpacking the NetRexx packages
  21.  
  22.   o Installing the NetRexx package -- documentation and samples
  23.  
  24.   o Installing the NetRexx executables (for any Java platform):
  25.  
  26.       o How to install the NetRexx compiler
  27.  
  28.       o Problem solving
  29.  
  30.       o How to install just the NetRexx runtime classes
  31.  
  32.   o Using the NetRexxC compiler
  33.  
  34.       o Compiling multiple programs and using packages
  35.  
  36.       o Invoking the compiler from Java
  37.  
  38.   o Using NetRexx classes with World Wide Web applets
  39.  
  40.   o Installing and using the NetRexx print package
  41.  
  42.   o Current restrictions, _etc._
  43.  
  44. The NetRexx documentation and software are distributed free of charge
  45. under the conditions of the IBM Employee Written Software program.
  46. If you download or use a NetRexx package you agree to the terms in the
  47. _IBM License Agreement_ included in the package as the file license.txt.
  48.  
  49. For details of the NetRexx language, and the latest news, please see the
  50. NetRexx documentation included with this package or available on the
  51. World Wide Web, for example at: http://www2.hursley.ibm.com/netrexx/
  52.  
  53. Mike Cowlishaw
  54. IBM UK Laboratories
  55.  
  56.  
  57. Unpacking NetRexx packages
  58. """"""""""""""""""""""""""
  59. The NetRexx packages are shipped in two forms, identified by a suffix
  60. following the name:
  61.  
  62.   o .zip format -- commonly used on OS/2 and other operating systems for
  63.     the IBM PC
  64.  
  65.   o .tar.Z format -- (tape archive plus compress) commonly used on AIX
  66.     and other Unix systems.
  67.  
  68. You probably know how to handle these, but a word of caution: the
  69. packages contain directory structures, and files with 'long names'
  70. (that is, not of 8.3 maximum length names) which are case-sensitive.
  71. Many utilities, including some versions of UNZIP and TAR, can lose
  72. case information, truncate names, or fail to restore directories.
  73.  
  74. --- Unpacking .zip files ---
  75.  
  76. The most common packages for 'unzipping' these are Info-ZIP and PKZIP:
  77. Here are some tips:
  78.  
  79.   o Ensure that you are unzipping to a disk that supports long file
  80.     names (for example, an HPFS disk or equivalent on OS/2 or Windows).
  81.  
  82.   o Info-ZIP: use version 5.12 (August 1994) or later.  The syntax for
  83.     unzipping NetRexx.zip is simply
  84.  
  85.       unzip NetRexx
  86.  
  87.     which should create the files and directory structure directly.
  88.     Please see later in this document for complete installation
  89.     instructions.
  90.  
  91.   o PKZIP: use a version that supports long file names.  The syntax for
  92.     unzipping NetRexx.zip is
  93.  
  94.       pkunzip -d NetRexx
  95.  
  96.     which should create the files and directory structure directly.  The
  97.     '-d' flag indicates that directory structure should be preserved.
  98.  
  99. --- Unpacking .tar.Z files ---
  100.  
  101. You need an up-to-date version of two programs: 'tar' and 'uncompress';
  102. these are available for most operating systems.  Here are some tips:
  103.  
  104.   o Ensure that you are unpacking to a disk that supports long file
  105.     names (for example, any Unix disk, or an HPFS disk or equivalent on
  106.     OS/2 or Windows).
  107.  
  108.   o Ensure that the version of tar that you use preserves case in names.
  109.     If all the files created by tar have all-lowercase names, you need a
  110.     new version of tar.
  111.  
  112. The process of unpacking the file takes two steps:
  113.  
  114.   1. Uncompress the file, using uncompress (this may be called
  115.      simply 'compress' on some systems).  The syntax for uncompressing
  116.      NetRexx.tar.Z is probably one of:
  117.  
  118.        uncompress  NetRexx.tar.Z
  119.        compress -d NetRexx.tar.Z
  120.  
  121.      (the '-d' means decompress, and may be optional).  This should
  122.      replace the file with one called NetRexx.tar
  123.  
  124.   2. Unpack the files and directories from the .tar file.  The syntax
  125.      for this is
  126.  
  127.        tar -xvf NetRexx.tar
  128.  
  129.      This should create the files and directories from the package,
  130.      displaying the name of each as it is unpacked.  You may see error
  131.      messages where directories already exist; these can be ignored.
  132.  
  133. After unpacking the files, the .tar file can be erased.
  134.  
  135.  
  136. Installation procedure - online documentation and samples
  137. """""""""""""""""""""""""""""""""""""""""""""""""""""""""
  138. The NetRexx package (NetRexx.zip, or NetRexx.tar.Z) contains the NetRexx
  139. online documentation, together with samples and examples, and the
  140. packages of executables.
  141.  
  142.   1. Copy the package file to the root directory of your choice,
  143.      preserving the original name.
  144.  
  145.   2. With your chosen directory as your current directory, unpack the
  146.      package, following the instructions in 'Unpacking NetRexx packages'
  147.      above.
  148.  
  149.      This should add the directory 'NetRexx' to your chosen directory,
  150.      containing the documentation and samples for NetRexx, along with
  151.      the packages of executables.  There should also be a subdirectory
  152.      ('NetRexx/netrexx/lang' or 'NetRexx\netrexx\lang') containing runtime
  153.      class files used by some of the samples.
  154.  
  155. The online documentation comes in two forms: plain ASCII (files with
  156. extension '.doc'), and World Wide Web hypertext format (files with
  157. extension '.htm' or '.html', '.gif', etc.).  To view the hypertext
  158. version, start your browser at the file "netrexx.htm".  For example, if
  159. you are using the IBM Web Explorer then the command
  160.  
  161.   explore netrexx.htm
  162.  
  163. (executed when the documentation directory is the current directory)
  164. should show the NetRexx front page.
  165.  
  166. Included in the documentation collection are a number of examples and
  167. samples (Hello, HelloApplet, etc.).  To run any of these, you must have
  168. the Java runtime environment installed.
  169.  
  170. Some of the examples must be viewed using the Java toolkit applet-viewer
  171. or a Java-enabled browser.  Please see the hypertext pages describing
  172. these for detailed instructions.  In general, if you see a message from
  173. Java saying:
  174.  
  175.   void main(String argv[]) is not defined
  176.  
  177. this means that the class cannot be run using just the 'java' command.
  178.  
  179.  
  180. Installation of NetRexx Executables
  181. """""""""""""""""""""""""""""""""""
  182. The NetRexx package includes two packages of software (each will have
  183. the same suffix as the package you unpacked it from, that is, '.zip' or
  184. '.tar.Z'):
  185.  
  186.   1. nrtools -- the files for the NetRexx compiler, of which the most
  187.      important is NetRexxC.zip, which contains the Java .class files
  188.      that implement the compiler.  The NetRexx compiler is in fact a
  189.      translator; it translates NetRexx programs to Java source code,
  190.      which is then compiled using the javac compiler (or you can use the
  191.      Java compiler of your choice, if you prefer).  This package
  192.      requires that the Java toolkit (1.1.0 or later) be installed.
  193.  
  194.      nrtools also includes a separate copy of the NetRexx runtime
  195.      classes, in NetRexxR.zip
  196.  
  197.   2. nrping -- the Pinger sample application.  Please see Pinger.htm for
  198.      information about this.
  199.  
  200. To install and use either of these packages, you must have already
  201. installed the Java Development Kit (JDK) runtime (and toolkit, if you
  202. want to compile NetRexx programs).  For more information on these:
  203.  
  204.   o For OS/2, AIX, and other IBM operating systems, Java is probably
  205.     already installed with our operating system.  If not, see the _IBM
  206.     Centre for Java Technology_ page at:
  207.  
  208.     http://ncc.hursley.ibm.com/javainfo/hurindex.html
  209.  
  210.   o For other operating systems, see the _Sun Microsystems Java_ page
  211.     at http://www.javasoft.com, or other suppliers of Java toolkits.
  212.  
  213.  
  214. Installation of the NetRexx compiler
  215. ''''''''''''''''''''''''''''''''''''
  216. Here's how to install the NetRexx compiler and runtime classes.  These
  217. instructions apply to the majority of Java platforms (for use with
  218. Visual J++, please see below).
  219.  
  220.   1. Copy the 'nrtools.zip' or 'nrtools.tar.Z' file from the NetRexx
  221.      documentation directory to the Java home directory, using the
  222.      original name.  The name of the Java home directory will vary
  223.      depending on the operating system you are using.  Some
  224.      possibilities are:
  225.  
  226.         /java
  227.         \java11
  228.         \jdk1.1.6
  229.  
  230.      It will contain directories such as 'bin' and 'lib'.
  231.  
  232.      [Note: if your Java home directory is on a CD-ROM, or otherwise
  233.      inaccessible, you'll need to choose a different directory and set
  234.      up a CLASSPATH environment variable that points to it.  Consult
  235.      your Java toolkit documentation for details on how to do this.]
  236.  
  237.   2. With the Java home directory as your current directory, unpack the
  238.      package, following the instructions in "Unpacking NetRexx packages"
  239.      above.
  240.  
  241.      This should add the .zip files for the NetRexx runtime and compiler
  242.      classes (NetRexxR.zip and NetRexxC.zip) to the Java 'lib' directory.
  243.  
  244.      In addition, some sample scripts and a test program should have
  245.      been added to the Java 'bin' directory:
  246.  
  247.        hello.nrx    -- a simple NetRexx program for testing
  248.        NetRexxC.cmd -- the NetRexx compiler command in Rexx
  249.        NetRexxC.bat -- similar NetRexx compiler command (Windows .bat)
  250.        nrc.cmd      -- shorter name for NetRexxC.cmd
  251.        nrc.bat      -- shorter name for NetRexxC.bat
  252.  
  253.      The .cmd files are simple Rexx scripts for making it easier to use
  254.      the compiler.  You don't have to use these, but they save some
  255.      typing.  They should require little modification to run under
  256.      the Rexx interpreter for your platform; for details of Rexx
  257.      interpreters, see: http://www2.hursley.ibm.com/rexx/
  258.  
  259.      Under Windows, the .bat files should serve the same purpose -- they
  260.      are not as flexible as the Rexx .cmd files, but will save typing.
  261.  
  262.   3. Check that the names are correct in the 'lib' directory: there
  263.      should be a file in the directory called 'NetRexxC.zip'; if
  264.      the name is all in upercase or all in lowercase the package has not
  265.      been unpacked correctly (see "Unpacking NetRexx packages").
  266.  
  267.   4. For Java to be able to find the NetRexx classes, you must update
  268.      the CLASSPATH environment variable by adding the full path and name
  269.      of the NetRexxC.zip file to the CLASSPATH setting.  There will
  270.      often already be a CLASSPATH variable set, including a path to the
  271.      standard Java classes.zip file.  Specify or add the full path
  272.      (disk, directories, and file specification) for NetRexxC.zip,
  273.      making sure that the case of every letter is exactly right (Java is
  274.      very case-sensitive). For example, the full path might be something
  275.      like:
  276.  
  277.        e:\java11\lib\NetRexxC.zip
  278.  
  279.      The procedure for setting the CLASSPATH variable depends on your
  280.      operating system (and there may be more than one way).  Here are
  281.      some examples:
  282.  
  283.        o In Windows or OS/2, use a SET CLASSPATH= command in
  284.          AUTOEXEC.BAT (for Windows) or in CONFIG.SYS (for OS/2), and
  285.          then re-boot after changing.  In both cases the command syntax
  286.          is the same, and might look like this:
  287.  
  288.            set classpath=.;f:\javaos2\lib\NetRexxC.zip
  289.  
  290.          In this example, the first segment of the value (before the
  291.          semicolon) lets classes in the current directory be found, and
  292.          the second segment includes the classes needed by NetRexx.
  293.          Both environments normally include the standard Java classes
  294.          automatically.
  295.  
  296.          Under Windows NT 4.0 the CLASSPATH should be set using Start,
  297.          Settings, Control Panel, System, Environment tab, System
  298.          Variables, and clicking on CLASSPATH; new command windows will
  299.          then inherit the new setting immediately.
  300.  
  301.        o For Unix (Korn shell or Bourne shell), use:
  302.  
  303.            CLASSPATH=<newdir>:$CLASSPATH
  304.            export CLASSPATH
  305.  
  306.          and changes for re-boot or opening of a new window should be
  307.          placed in your .login (Bourne) or .profile (Korn) file
  308.  
  309.        o For Unix (C shell), use:
  310.  
  311.            setenv CLASSPATH <newdir>:$CLASSPATH
  312.  
  313.          and changes for re-boot or opening of a new window should be
  314.          placed in your .cshrc file
  315.  
  316.      If you are unsure of how to do this, check the documentation you
  317.      have for installing the Java toolkit.
  318.  
  319.   5. If you are running Java 1.2, and want NetRexx to use the javac
  320.      compiler (which is the default) then you will also need to add the
  321.      Sun tools collection to the classpath.  This is usually found in
  322.      a file called tools.jar in the lib directory.  For example:
  323.  
  324.        set classpath=%CLASSPATH%;c:\java12\lib\tools.jar
  325.  
  326.      (with the path changed as appropriate) would add the tools.jar to
  327.      the existing classpath in an OS/2 or Windows system.
  328.  
  329.   6. If you are running Java 1.2, you may also need to add the current
  330.      directory to the classpath, for example:
  331.  
  332.        set classpath=.;%CLASSPATH%
  333.  
  334.      as this is no longer added automatically by the Java Virtual
  335.      Machine.
  336.  
  337. Note: If you add NetRexxC.zip to the CLASSPATH value then you do not
  338. need to add NetRexxR.zip; the latter contains only the NetRexx runtime
  339. classes (which are provided separately for people who don't want to run
  340. the NetRexx compiler).  These runtime classes are also included in
  341. NetRexxC.zip.  Whichever zip is used, the NetRexx runtime classes can be
  342. referred to from Java or NetRexx as being in the 'netrexx.lang' package.
  343. For example, a string might be of class 'netrexx.lang.Rexx'.
  344.  
  345. --- Checking your installation is correct ---
  346.  
  347. To check installation, change directory to the Java 'bin' directory,
  348. then (being very careful to get the case of letters correct):
  349.  
  350.   o  Enter the command
  351.  
  352.        java COM.ibm.netrexx.process.NetRexxC hello
  353.  
  354.      This should run the NetRexx compiler, which converts the NetRexx
  355.      program 'hello.nrx' to the Java program 'hello.java'.  It then
  356.      invokes the default Java compiler (javac), to compile the file
  357.      'hello.java' to make 'hello.class'.  The intermediate .java file
  358.      is then deleted, unless an error occurred.
  359.  
  360.      If you get errors from Java and you're running Java 1.2.x, then
  361.      recheck steps 5 and 6 above.
  362.  
  363.   o  Enter the command
  364.  
  365.        java hello
  366.  
  367.      This runs (interprets bytecodes from) the 'hello.class' file,
  368.      which should display a simple greeting.  On some systems, you may
  369.      first have to add the directory that contains the 'hello.class'
  370.      file to the CLASSPATH setting (see above) so Java can find it.
  371.  
  372. With the sample scripts provided (NetRexxC.cmd or NetRexxC.bat), or the
  373. equivalent in the scripting language of your choice, the steps above can
  374. be combined into a simple single command:
  375.  
  376.   NetRexxC -run hello
  377.  
  378. This package also includes a trivial 'nrc.cmd' and matching 'nrc.bat'
  379. file that simply passes on its arguments to NetRexxC; 'nrc' is just a
  380. shorter name that saves keystrokes, so for the last example you could
  381. type:
  382.  
  383.   nrc -run hello
  384.  
  385. Note that scripts may be case-sensitive; unless running the OS/2 Rexx
  386. script, you will probably have to spell the name of the program exactly
  387. as it appears in the filename.
  388.  
  389. You could also edit the nrc.cmd or nrc.bat and add your favourite
  390. 'default' NetRexxC options there (if you do this, keep a backup copy, so
  391. that if you install a new version of the NetRexx package you won't
  392. overwrite your changes).
  393.  
  394. --- Using JDK1.1.5 and later ---
  395.  
  396. JDK 1.1.5 (and later toolkits) sometimes has a Just-In-Time compiler
  397. (JIT) that slows down rather than speeds up both the NetRexx and Java
  398. compilers: programs can take between two and three times as long to
  399. compile as compared to using JDK 1.1.4.  You can measure compilation
  400. times by using (for example):
  401.  
  402.   nrc hello -time
  403.  
  404. You can turn off the JIT to measure its effect.  If you are using the
  405. nrc or NetRexxC .cmd or .bat file then set the environment variable:
  406.  
  407.   SET NETREXX_JAVA=-nojit
  408.  
  409. In some versions of the java command, the -nojit flag can be specified
  410. directly on the java command used to run the NetRexx compiler.
  411. Otherwise, on most platforms, this can also be achieved by:
  412.  
  413.   SET JAVA_COMPILER=NONE
  414.  
  415. (You may then get a message that the 'NONE' compiler could not be found.
  416. Ignore this message.)
  417.  
  418. --- Installing NetRexx for use on EBCDIC systems ---
  419.  
  420. (Many thanks to Mark Cathcart and John Kearney for the details in this
  421. section.)
  422.  
  423. The NetRexx binaries are identical for all operating systems.  However,
  424. during installation it is important to ensure that binary files are
  425. treated as binary files, whereas text files (such as the accompanying
  426. HTML files) are translated to the local code page as required.
  427.  
  428. The simplest way to do this is to first install the package on a
  429. workstation, following the instructions above, then copy or FTP the
  430. files you need to the EBCDIC machine.  Specifically:
  431.  
  432.   o The NetRexxC.zip file should be copied 'as-is', that is, use FTP
  433.     or other file transfer with the BINARY option.  The CLASSPATH
  434.     should be set to include this NetRexxC.zip file.
  435.  
  436.   o Other files (documentation, etc.) should be copied as Text (that
  437.     is, they will be translated from ASCII to EBCDIC).
  438.  
  439. In general, binary files (.class files, and .zip files containing .class
  440. files) should always be transferred as BINARY -- the same binaries run
  441. on all platforms.
  442.  
  443. For specific hints and tips for installing on OS/390, see Mark
  444. Cathcart's web site at
  445.  
  446.   http://www.s390.ibm.com/corner
  447.  
  448. which includes a presentation that describes OS/390 Java and NetRexx
  449. installation.  Setting the classpath might look like this:
  450.  
  451.   export CLASSPATH=$CLASSPATH:/u/j390/j1.1.1/lib/NetRexxC.zip
  452.  
  453. --- Installing NetRexx for use with Visual J++ ---
  454.  
  455. (Many thanks to Bill Potvin and Bernhard Hurzeler for the details in
  456. this and the following section.)
  457.  
  458.   1. Copy the following file into the [java_root]\Lib directory:
  459.  
  460.        NetRexxC.zip
  461.  
  462.      For example, if [java_root] is "E:\Java":
  463.  
  464.        C:\>copy NetRexxC.zip E:\Java\Lib
  465.  
  466.   2. Similarly, copy the nrc.bat and NetRexxC.bat files to the
  467.      [java_root]\Bin directory.
  468.  
  469.   3. Add the zip file explicitly to the CLASSPATH:
  470.  
  471.        C:\>set CLASSPATH=%CLASSPATH%;[java_root]\Lib\NetRexxC.zip;
  472.  
  473.      For example, if [java_root] is "E:\Java", your CLASSPATH
  474.      might then look like this:
  475.  
  476.        CLASSPATH=E:\Java\Lib;E:\Java\TrustLib;E:\Java\Lib\NetRexxC.zip;
  477.  
  478.      Under Windows NT 4.0 this can be done using Start, Settings,
  479.      Control Panel, System, Environment tab, System Variables, and
  480.      clicking on CLASSPATH.
  481.  
  482. --- Using NetRexx with Visual J++ ---
  483.  
  484.   1. Use the J++ "jview" command to invoke the NetRexx translator to
  485.      convert a NetRexx program (e.g., hello.nrx) into a Java program
  486.      (hello.java).
  487.  
  488.      Note that some versions of the jview package do not provide a
  489.      "classes.zip" file by default, but the NetRexx compiler needs this
  490.      to determine information about classes that you use.  If this is
  491.      the case, you will get a 'class not found' error for
  492.      "java.lang.Object".  In this case, run the command
  493.  
  494.        clspack -auto
  495.  
  496.      from a MS-DOS prompt to create the classes.zip file.
  497.  
  498.      When running the NetRexx compiler, you must specify the
  499.      "-nocompile" option to NetRexx in order to prevent it from trying
  500.      to invoke the Java toolkit compiler (which isn't in the MicroSoft
  501.      J++ classes).
  502.  
  503.      For example, if hello.nrx is in the current directory:
  504.  
  505.        jview COM.ibm.netrexx.process.NetRexxC hello -nocompile
  506.  
  507.      The result of this step should be a Java source file called
  508.      "hello.java".
  509.  
  510.   2. Use the J++ "jvc" command to compile the Java source file:
  511.  
  512.        jvc hello.java
  513.  
  514.      The result of this step should be a Java .class file called
  515.      "hello.class".
  516.  
  517.   3. Execute the class file with the J++ command "jview":
  518.  
  519.        jview hello
  520.  
  521.   4. Note that some versions of jview fail with an exception (an
  522.      ArrayIndexOutOfBoundsException in RexxUtil.translate) when
  523.      compiling hello.nrx.  This is due to a bug in the JIT; the
  524.      workaround is to turn the JIT off.
  525.  
  526.  
  527. Note that all the commands above probably have to be typed exactly as
  528. shown (Java is very case-sensitive).  The supplied NetRexxC.bat can be
  529. modified to work with the above commands by using 'jview' instead of the
  530. 'java' command and adding the 'jvc' step.
  531.  
  532.  
  533. Problems?
  534. '''''''''
  535. If the 'hello' example doesn't work, one of the following problems
  536. may be the cause:
  537.  
  538.   o A "Can't find class COM.ibm.netrexx.process.NetRexxC..." message
  539.     probably means that the NetRexxC.zip file has not been specified in
  540.     your CLASSPATH setting, or is misspelled, or is in the wrong case.
  541.     The CLASSPATH is the setting that Java uses to find classes for
  542.     execution; please refer to your Java installation instructions for
  543.     information on setting the CLASSPATH.
  544.  
  545.   o A "Can't find class hello..." message may mean that the directory
  546.     with the hello.class file is not in your CLASSPATH (you may need to
  547.     add a '.;' to the CLASSPATH, signifying the current directory), or
  548.     either the filename or name of the class (in the source) is spelled
  549.     wrong (the java command is [very] case-sensitive).
  550.  
  551.   o The compiler appears to work, but towards the end fails with
  552.     "Exception ... NoClassDefFoundError: sun/tools/javac/Main".
  553.     This indicates that you are running Java 1.2 but did not add the
  554.     Java tools to your classpath (hence Java could not find the javac
  555.     compiler).  See installation instructions above for more details.
  556.  
  557.   o You have an extra blank or two in the CLASSPATH.  Blanks should only
  558.     occur in the middle of directory names (and even then, you probably
  559.     need some double quotes around the SET command or the classpath
  560.     segment with the blank).  The JVM is sensitive about this.
  561.  
  562.   o You didn't install on a file system that supports long file
  563.     names (for example, on OS/2 or Windows you should use an HPFS disk
  564.     or equivalent).  Like most Java applications, NetRexx uses long file
  565.     names.
  566.  
  567.   o You have a down-level Unzip or Tar program.  Check that the
  568.     file 'NetRexxC.zip', with just three capital letters, exists in the
  569.     subdirectory 'lib' below the Java home directory.
  570.  
  571.   o You have only the Java runtime installed, and not the toolkit.  If
  572.     the toolkit is installed, you should have a program called javac
  573.     on your computer.  (Try running that from a commandline prompt.)
  574.  
  575.   o An 'Out of environment space' message when trying to set CLASSPATH
  576.     under Win95-DOS can be remedied by adding /e:4000 to the 'Cmd line'
  577.     entry for the MS-DOS prompt properties (try 'command /?' for more
  578.     information).
  579.  
  580.   o An exception, apparently in the Rexx translate method, when
  581.     compiling with Microsoft Java SDK 3.1 (and possibly later SDKs) is
  582.     caused by a bug in the just-in-time compiler (JIT) in that SDK.
  583.     Turn off the JIT using Start -> Settings -> Control Panel ->
  584.     Internet to get to the Internet Properties dialog, then select
  585.     Advanced, scroll to the Java VM section, and uncheck 'Java JIT
  586.     compiler enabled'.  Alternatively, turn of the JIT by setting the
  587.     environment variable:
  588.  
  589.       SET MSJAVA_ENABLE_JIT=0
  590.  
  591.     (this can be placed in a batch file which invokes NetRexxC, if
  592.     desired).
  593.  
  594.   o An 'Exception 0005' when using the OS/2 beta Java 1.1.1 toolkit is
  595.     probably caused by the just-in-time compiler.  Try turning it off
  596.     before running NetRexxC by setting the environment variable:
  597.  
  598.       SET JAVA_COMPILER=no
  599.  
  600.     (and ignore the 'unable to load dll' message).
  601.  
  602.   o An ArrayIndexOutOfBoundsException when compiling hello.nrx under AIX
  603.     is caused by an early faulty JIT.  Either disable the JIT (as for
  604.     OS/2) or update your AIX Java SDK.
  605.  
  606.   o A java.lang.OutOfMemoryError when running the compiler probably
  607.     means that the maximum heap size is not sufficient.  The initial
  608.     size depends on your Java virtual machine; you can change it to
  609.     (say) 24 MegaBytes by setting the environment variable:
  610.  
  611.       SET NETREXX_JAVA=-mx24M
  612.  
  613.     In Java 1.2.2 or later, use:
  614.  
  615.       SET NETREXX_JAVA=-Xmx24M
  616.  
  617.     The NetRexxC.cmd and .bat files add the value of this environment
  618.     variable to the options passed to java.exe.
  619.  
  620.   o You have a down-level version of Java installed.  NetRexxC 1.1xx
  621.     will run only on Java version 1.1.0 (and later versions).  You can
  622.     check the version of Java you have installed using the command 'java
  623.     -version'.  An older version of the NetRexx package is available for
  624.     Java 1.0, however that version will no longer be enhanced or
  625.     supported in any way.
  626.  
  627.   o Your Java toolkit installation has .class files from an earlier
  628.     installation of NetRexx in classes/java/lang, classes/netrexx/lang,
  629.     or other subdirectories in the 'classes' directory below the Java
  630.     home directory.
  631.  
  632.     A message that reports ambiguous class references is a likely sign
  633.     of this problem.  The easiest way to solve it is to re-install the
  634.     Java toolkit in a clean subdirectory.
  635.  
  636.   o If, when reporting an error or warning, the compiler gives a rather
  637.     cryptic identifier and reports 'Sorry, full message not available',
  638.     this means that it could not find the NetRexxC.properties (error
  639.     messages) file, which should be in the COM.ibm.netrexx.process
  640.     package (in NetRexxC.zip).
  641.  
  642.  
  643. Installation of just the NetRexx classes
  644. ''''''''''''''''''''''''''''''''''''''''
  645. To install only the NetRexx runtime classes (you don't need to do this
  646. if you already installed the NetRexxC compiler), follow the instructions
  647. for installing the compiler, but set your CLASSPATH to refer to
  648. NetRexxR.zip instead of NetRexxC.zip.  Only the NetRexxR.zip is needed,
  649. so you may prefer to extract just this file from the nrtools package.
  650.  
  651. The NetRexx class files can then be referred to from Java or NetRexx
  652. programs as from package 'netrexx.lang'.  For example, a string might be
  653. of class 'netrexx.lang.Rexx'.
  654.  
  655.  
  656. Using the NetRexx compiler
  657. """"""""""""""""""""""""""
  658. The installation instructions for the NetRexx compiler describe how to
  659. use the package you installed to compile and run a simple NetRexx
  660. program.  This section explains more of the options available to you.
  661.  
  662. --- Invoking the compiler as a command ---
  663.  
  664. The compiler is a Java program (class) which is called
  665. COM.ibm.netrexx.process.NetRexxC (NetRexxC for short). This can be
  666. invoked using the Java interpreter, for example, by the command:
  667.  
  668.   java COM.ibm.netrexx.process.NetRexxC
  669.  
  670. or by using a system-specific command (such as 'NetRexxC' or 'nrc').  In
  671. either case, the compiler invocation is followed by one or more file
  672. specifications (these are the names of the files containing the NetRexx
  673. source code for the programs to be compiled).
  674.  
  675. File specifications may include a path; if no path is given then
  676. NetRexxC will look in the current (working) directory for the file.
  677. NetRexxC will add the extension '.nrx' to input program names (file
  678. specifications) if no extension was given.
  679.  
  680. So, for example, to compile 'hello.nrx' in the current directory, you
  681. can use any of:
  682.  
  683.   java COM.ibm.netrexx.process.NetRexxC hello
  684.   java COM.ibm.netrexx.process.NetRexxC hello.nrx
  685.   NetRexxC hello.nrx
  686.   nrc hello
  687.  
  688. (the first two should always work, the last two require that the
  689. system-specific command be available).  The resulting .class file is
  690. placed in the current directory, and the .crossref (cross-reference)
  691. file is placed in the same directory as the source file (if there are
  692. any variables and the compilation has no errors).
  693.  
  694. Here's an example of compiling two programs, one of which is in the
  695. directory 'D:\myprograms':
  696.  
  697.   nrc hello d:\myprograms\test2.nrx
  698.  
  699. In this case, again, the .class file is placed in the current directory.
  700.  
  701. Note that when more than one program is specified, they are all compiled
  702. with the same class context: that is, they can 'see' the classes,
  703. properties, and methods of the other programs being compiled, much as
  704. though they were all in one file.  This allows mutually interdependent
  705. programs and classes to be compiled in a single operation (but see the
  706. section "Compiling multiple programs" below, if you use the PACKAGE
  707. instruction).
  708.  
  709. The programs do, however, maintain their independence (that is, they may
  710. have different options, import, and package instructions).
  711.  
  712. On completion, the NetRexxC command will exit with one of three return
  713. values: 0 if the compilation of all programs was successful, 1 if there
  714. were one or more Warnings, but no errors, and 2 if there were one or
  715. more Errors.
  716.  
  717. As well as file names, you can also specify various option words, which
  718. are distinguished by the first character of the word being '-'.  These
  719. may be any of the option words allowed on the NetRexx OPTIONS
  720. instruction (see the NetRexx language documentation), prefixed with '-'.
  721. These options words can be freely mixed with file specifications.
  722.  
  723. The compiler also implements some additional option words, which cannot
  724. be used on the OPTIONS instruction:
  725.  
  726.   o -keep       keep the intermediate .java file for each program.  It
  727.                 is kept in the same directory as the NetRexx source file
  728.                 as xxx.java.keep, where xxx is the source file name.
  729.                 The file will also be kept automatically if the javac
  730.                 compilation fails for any reason.
  731.  
  732.   o -nocompile  do not compile (just translate).  Use this option when
  733.                 you want to use a different Java compiler.  The .java
  734.                 file for each program is kept in the same directory as
  735.                 the NetRexx source file, as the file xxx.java (where xxx
  736.                 is the source file name); any -keep option is ignored.
  737.  
  738.   o -noconsole  do not display compiler messages on the console (command
  739.                 display screen).
  740.  
  741.   o -savelog    write compiler messages to the file NetRexxC.log, in the
  742.                 current directory.
  743.  
  744.   o -time       display translation, javac compile, and total times (for
  745.                 the sum of all programs processed).
  746.  
  747. If you are using the provided NetRexxC or nrc scripts, then an
  748. additional option is available:
  749.  
  750.   o -run        run the resulting JAVA class as a stand-alone
  751.                 application, provided that the compilation had no
  752.                 errors.
  753.  
  754. Here are some examples:
  755.  
  756.   java COM.ibm.netrexx.process.NetRexxC hello -keep -strictargs
  757.   java COM.ibm.netrexx.process.NetRexxC -keep hello wordclock
  758.   java COM.ibm.netrexx.process.NetRexxC hello wordclock -nocompile
  759.   nrc hello
  760.   nrc hello.nrx
  761.   nrc -run hello
  762.   nrc -run Spectrum -keep
  763.   nrc hello -binary -verbose1
  764.   nrc hello -noconsole -savelog -format -keep
  765.  
  766. Option words may be specified in lowercase, mixed case, or uppercase.
  767. File specifications are platform-dependent and may be case sensitive,
  768. though NetRexxC will always prefer an exact case match over a mismatch.
  769.  
  770. Note that the -run option is implemented by the script, not the
  771. compiler; some scripts (such as NetRexxC.bat) may require that the
  772. '-run' be the first word of the command arguments, and/or be in
  773. lowercase.  They may also require that only the name of the file be
  774. given if the -run option is used.
  775.  
  776. --- Compiling multiple programs and using packages ---
  777.  
  778. When you specify more than one program for NetRexxC to compile, they are
  779. all compiled with the same class context: that is, they can 'see' the
  780. classes, properties, and methods of the other programs being compiled,
  781. much as though they were all in one file.
  782.  
  783. This allows mutually interdependent programs and classes to be compiled
  784. in a single operation.  For example, consider the following two programs
  785. (assumed in your current directory, as the files X.nrx and Y.nrx):
  786.  
  787.   /* X.nrx */
  788.   class X
  789.     why=Y null
  790.  
  791.   /* Y.nrx */
  792.   class Y
  793.     exe=X null
  794.  
  795. each contains a reference to the other, so neither can be compiled in
  796. isolation.  However, if you compile them together, using the command:
  797.  
  798.   nrc X Y
  799.  
  800. then the cross-references will be resolved correctly.
  801.  
  802. The total elapsed time will be significantly less, too, as the classes
  803. on the CLASSPATH need to be located only once, and the class files used
  804. by the NetRexxC compiler or the programs themselves will also only be
  805. loaded once.
  806.  
  807. This example works as you would expect for programs that are not in
  808. packages.  There's a restriction, though, if the classes you are
  809. compiling _are_ in packages (that is, they include a PACKAGE
  810. instruction).  Currently, NetRexxC uses the javac compiler to generate
  811. the .class files, and for mutually-dependent files like these, javac
  812. requires that the source files be in the Java CLASSPATH, in the
  813. sub-directory described by the PACKAGE instruction.
  814.  
  815. So, for example, if your project is based on the tree:
  816.  
  817.   D:\myproject
  818.  
  819. then if the two programs above specified a package, thus:
  820.  
  821.   /* X.nrx */
  822.   package foo.bar
  823.   class X
  824.     why=Y null
  825.  
  826.   /* Y.nrx */
  827.   package foo.bar
  828.   class Y
  829.     exe=X null
  830.  
  831. then:
  832.  
  833.   1. You should put these source files in the directory: D:\myproject\foo\bar
  834.  
  835.   2. The directory D:\myproject should appear in your CLASSPATH setting
  836.      (if you don't do this, javac will complain that it cannot find one
  837.      or other of the classes).
  838.  
  839.   3. You should then make the current directory be D:\myproject\foo\bar
  840.      and then compile the programs using the command 'nrc X Y', as
  841.      above.
  842.  
  843. With this procedure, you should end up with the .class files in the same
  844. directory as the .nrx files, and therefore also on the CLASSPATH and
  845. immediately usable by other packages.  In general, this arrangement is
  846. recommended whenever you are writing programs that reside in packages.
  847.  
  848. Note that when javac is used to generate the .class files, no new .class
  849. files will be created if any of the programs being compiled together had
  850. errors -- this avoids accidentally generating mixtures of new and old
  851. .class files that cannot work with each other.
  852.  
  853. Note also that if class is abstract or is an adapter class then it
  854. should be placed in the list before any classes that extend it (as
  855. otherwise any automatically generated methods will not be visible to the
  856. subclasses).
  857.  
  858. --- Invoking the compiler from Java ---
  859.  
  860. The compiler may be called from a Java program directly, by invoking the
  861. method in the COM.ibm.netrexx.process.NetRexxC class described as
  862. follows:
  863.  
  864.   method main(arg=Rexx, log=PrintWriter null) static returns int
  865.  
  866. The Rexx string passed to the method can be any combination of program
  867. names and options (except -run), as described above.  Program names may
  868. be enclosed in double-quote characters (and must be if the name
  869. includes any blanks in its specification).  A sample NetRexx program
  870. that invokes the NetRexx compiler to compile a program called 'test' is:
  871.  
  872.  /* compiletest.nrx */
  873.  s='test -keep -verbose4 -utf8'
  874.  say COM.ibm.netrexx.process.NetRexxC.main(s)
  875.  
  876. Alternatively, the compiler may be called using the method:
  877.  
  878.   method main2(arg=String[], log=PrintWriter null) static returns int
  879.  
  880. in which case each element of the arg array must contain either a name
  881. or an option (except -run, as before).  In this case, names must not be
  882. enclosed in double-quote characters, and may contain blanks.
  883.  
  884. For both methods, the returned int value will be one of the return
  885. values described above, and the second argument to the method is an
  886. optional PrintWriter stream.  If the PrintWriter stream is provided,
  887. compiler messages will be written to that stream (in addition to
  888. displaying them on the console, unless -noconsole is specified).
  889. It is the responsibility of the caller to create the stream (autoflush
  890. is recommended) and to close it after calling the compiler.  The
  891. -savelog compiler option is ignored if a PrintWriter is provided (the
  892. -savelog option creates a PrintWriter for the file NetRexxC.log).
  893.  
  894. NetRexxC is thread-safe (the only static properties are constants), but
  895. it is not known whether javac is thread-safe.  Hence the invocation of
  896. multiple instances of NetRexxC on different threads should probably
  897. specify -nocompile, for safety.
  898.  
  899.  
  900. NetRexx classes and Applets for the Web
  901. """""""""""""""""""""""""""""""""""""""
  902. If you write applets for the World Wide Web (or your intranet) in
  903. NetRexx, you will probably need to use the NetRexx classes
  904. (netrexx.lang.Rexx, _etc._); they will be used automatically if the
  905. default compilation options (specifically, options nobinary) are in
  906. effect.
  907.  
  908. A good way of setting up an HTTP (Web) server for this is to keep all
  909. your applets in one subdirectory; you can then make the NetRexx runtime
  910. classes (that is, the classes in the package known by Java as
  911. netrexx.lang) available to all the applets by unzipping NetRexxR.zip
  912. into a subdirectory netrexx/lang below your applets directory.
  913.  
  914. For example, if the root of your server tree is
  915.  
  916.   D:/mydata
  917.  
  918. then you might put your applets into
  919.  
  920.   D:/mydata/applets
  921.  
  922. and then the NetRexx classes (unzipped from NetRexxR.zip) should be in
  923. the directory
  924.  
  925.   D:/mydata/applets/netrexx/lang
  926.  
  927. The same principle is applied if you have any other Java packages that
  928. you want to make available to your applets: the classes in a package
  929. called fred.math.quicksorts would go in a subdirectory below applets
  930. called fred/math/quicksorts, for example.
  931.  
  932. Note that with Java 1.1 it should be possible to use the classes direct
  933. from the NetRexxR.zip file (which is in fact a Java 'jar' file),
  934. providing that the browser being used is at a Java 1.1 level.  See the
  935. Java 1.1 documentation for details.
  936.  
  937.  
  938. Printable documentation
  939. """""""""""""""""""""""
  940. The NetRexx printable package (NetRexxD.zip, or NetRexxD.tar.Z) contains
  941. the printable NetRexx documentation, in PostScript format.
  942.  
  943.   1. Copy the package file to the root directory of your choice for
  944.      documentation, preserving the original name.
  945.  
  946.   2. With your chosen directory as your current directory, unpack the
  947.      package, following the instructions in 'Unpacking NetRexx packages'
  948.      above.
  949.  
  950.      This should add the directory 'NetRexxD' to your chosen directory,
  951.      containing the printable documentation for NetRexx.
  952.  
  953.   3. You can print files from the new directory that have the extension
  954.      '.ps' on any PostScript printer, using the appropriate method for
  955.      printing for your operating system.  There are also utilities, such
  956.      as 'GhostScript', available from public sources for viewing
  957.      PostScript files and for printing them on non-PostScript printers.
  958.  
  959.  
  960. Current restrictions
  961. """"""""""""""""""""
  962. The NetRexx processor is now functionally complete, though work
  963. continues on usability and performance improvements.  As of this version
  964. there are still a number of restrictions, listed below.
  965.  
  966. Please note that the presence of an item in this section is not a
  967. commitment to remove a restriction in some future update; NetRexx
  968. enhancements are dependent on on-going research, your feedback, and
  969. available resources.  You should treat this list as a 'wish-list' (and
  970. please send in your wishes).
  971.  
  972. --- Compiler restrictions ---
  973.  
  974. The following problem may occur in larger methods, with Java 1.0.1,
  975. 1.0.2, or 1.1.2 (it seems to have been fixed in later versions):
  976.  
  977.   o NetRexxC does not restrict the number of local variables used or
  978.     generated.  However, the 1.0 javac compiler fails with unrelated
  979.     error messages (such as 'statement unreachable' or 'variable may be
  980.     uninitialized') if asked to handle more than 63 local variables.
  981.  
  982.   o Certain forward references (in particular, references to methods
  983.     later in a program from the argument list of an earlier method) are
  984.     not handled by the compiler.  For these, try reordering the methods,
  985.     if possible.
  986.  
  987. --- Long term restrictions ---
  988.  
  989. The following restrictions are due to the use of a translator, and would
  990. probably only be lifted if a direct-to-bytecodes NetRexx compiler were
  991. built.
  992.  
  993.   o Externally-visible names (property, method, and class names) cannot
  994.     be Java reserved words (you probably want to avoid these anyway, as
  995.     people who have to write in Java cannot refer to them), and cannot
  996.     start with '$0'.
  997.  
  998.   o There are various restrictions on naming and the contents of
  999.     programs (the first class name must match the program name, etc.).
  1000.  
  1001.   o The javac compiler requires that mutually-dependent source files be
  1002.     on the CLASSPATH, so javac can find the source files.  NetRexxC does
  1003.     not have this restriction, but when using javac for the final
  1004.     compilation you will need to follow the convention described under
  1005.     'Compiling multiple programs', above.
  1006.  
  1007.   o The 'symbols' option applies to all programs compiled together if
  1008.     any of them specify that option.
  1009.  
  1010.   o Some binary floating point underflows may be treated as zero instead
  1011.     of being trapped as errors.
  1012.  
  1013.   o Side-effects of calls to this() and super() in constructors may be
  1014.     seen before the method and method call instructions are traced --
  1015.     this is because the Java language does not permit tracing
  1016.     instructions to be added before the call to this() or super().
  1017.  
  1018.   o The results of expressions consisting of the single term 'null' are
  1019.     not traced.
  1020.  
  1021.   o When a minor class is explicitly imported, its parent class or
  1022.     classes must also be explicitly imported, or javac will report that
  1023.     the class cannot be found.
  1024.  
  1025.