home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 18 REXX / 18-REXX.zip / netrexx.zip / NetRexx / nrinst.doc < prev    next >
Text File  |  1998-12-22  |  39KB  |  968 lines

  1.                                                            NetRexx 1.148
  2. NetRexx Installation and User's Guide
  3. =====================================
  4.  
  5. Copyright(c) IBM Corporation, 1996, 1998.  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 OS/2 or Windows, use a SET CLASSPATH= command in CONFIG.SYS
  284.          (for OS/2) or in AUTOEXEC.BAT (for Windows) and re-boot after
  285.          changing.  In both cases the command syntax is the same, and
  286.          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 can be set using Start,
  297.          Settings, Control Panel, System, Environment tab, System
  298.          Variables, and clicking on CLASSPATH.
  299.  
  300.        o For Unix (Korn shell or Bourne shell), use:
  301.  
  302.            CLASSPATH=<newdir>:$CLASSPATH
  303.            export CLASSPATH
  304.  
  305.          and changes for re-boot or opening of a new window should be
  306.          placed in your .login (Bourne) or .profile (Korn) file
  307.  
  308.        o For Unix (C shell), use:
  309.  
  310.            setenv CLASSPATH <newdir>:$CLASSPATH
  311.  
  312.          and changes for re-boot or opening of a new window should be
  313.          placed in your .cshrc file
  314.  
  315.      If you are unsure of how to do this, check the documentation you
  316.      have for installing the Java toolkit.
  317.  
  318.   5. If you are running Java 1.2, and want NetRexx to use the javac
  319.      compiler (which is the default) then you will also need to add the
  320.      Sun tools collection to the classpath.  This is usually found in
  321.      a file called tools.jar in the lib directory.  For example:
  322.  
  323.        set classpath=%CLASSPATH%;c:\java12\lib\tools.jar
  324.  
  325.      (with the path changed as appropriate) would add the tools.jar to
  326.      the existing classpath in an OS/2 or Windows system.
  327.  
  328.   6. If you are running Java 1.2, you may also need to add the current
  329.      directory to the classpath, for example:
  330.  
  331.        set classpath=.;%CLASSPATH%
  332.  
  333.      as this is no longer added automatically by the Java Virtual
  334.      Machine.
  335.  
  336. Note: If you add NetRexxC.zip to the CLASSPATH value then you do not
  337. need to add NetRexxR.zip; the latter contains only the NetRexx runtime
  338. classes (which are provided separately for people who don't want to run
  339. the NetRexx compiler).  These runtime classes are also included in
  340. NetRexxC.zip.  Whichever zip is used, the NetRexx runtime classes can be
  341. referred to from Java or NetRexx as being in the 'netrexx.lang' package.
  342. For example, a string might be of class 'netrexx.lang.Rexx'.
  343.  
  344. --- Checking your installation is correct ---
  345.  
  346. To check installation, change directory to the Java 'bin' directory,
  347. then (being very careful to get the case of letters correct):
  348.  
  349.   o  Enter the command
  350.  
  351.        java COM.ibm.netrexx.process.NetRexxC hello
  352.  
  353.      This should run the NetRexx compiler, which converts the NetRexx
  354.      program 'hello.nrx' to the Java program 'hello.java'.  It then
  355.      invokes the default Java compiler (javac), to compile the file
  356.      'hello.java' to make 'hello.class'.  The intermediate .java file
  357.      is then deleted, unless an error occurred.
  358.  
  359.   o  Enter the command
  360.  
  361.        java hello
  362.  
  363.      This runs (interprets bytecodes from) the 'hello.class' file,
  364.      which should display a simple greeting.  On some systems, you may
  365.      first have to add the directory that contains the 'hello.class'
  366.      file to the CLASSPATH setting (see above) so Java can find it.
  367.  
  368. With the sample scripts provided (NetRexxC.cmd or NetRexxC.bat), or the
  369. equivalent in the scripting language of your choice, the steps above can
  370. be combined into a simple single command:
  371.  
  372.   NetRexxC -run hello
  373.  
  374. This package also includes a trivial 'nrc.cmd' and matching 'nrc.bat'
  375. file that simply passes on its arguments to NetRexxC; 'nrc' is just a
  376. shorter name that saves keystrokes, so for the last example you could
  377. type:
  378.  
  379.   nrc -run hello
  380.  
  381. Note that scripts may be case-sensitive; unless running the OS/2 Rexx
  382. script, you will probably have to spell the name of the program exactly
  383. as it appears in the filename.
  384.  
  385. You could also edit the nrc.cmd or nrc.bat and add your favourite
  386. 'default' NetRexxC options there (if you do this, keep a backup copy, so
  387. that if you install a new version of the NetRexx package you won't
  388. overwrite your changes).
  389.  
  390. --- Using JDK1.1.5 and later ---
  391.  
  392. JDK 1.1.5 (and later toolkits) sometimes has a Just-In-Time compiler
  393. (JIT) that slows down rather than speeds up both the NetRexx and Java
  394. compilers: programs can take between two and three times as long to
  395. compile as compared to using JDK 1.1.4.  You can measure compilation
  396. times by using (for example):
  397.  
  398.   nrc hello -time
  399.  
  400. You can turn off the JIT to measure its effect.  If you are using the
  401. nrc or NetRexxC .cmd or .bat file then set the environment variable:
  402.  
  403.   SET NETREXX_JAVA=-nojit
  404.  
  405. Or specify the -nojit flag directly on the java command used to run the
  406. NetRexx compiler. Otherwise, and on some platforms, this can also
  407. usually be achieved by:
  408.  
  409.   SET JAVA_COMPILER=XXX
  410.  
  411. (You may then get a message that the 'XXX' compiler could not be found.
  412. Ignore this message.)
  413.  
  414. --- Installing NetRexx for use on EBCDIC systems ---
  415.  
  416. (Many thanks to Mark Cathcart and John Kearney for the details in this
  417. section.)
  418.  
  419. The simplest way to do this is to first install the package on a
  420. workstation, following the instructions above, then copy or FTP the
  421. files you need to the EBCDIC machine.  Specifically:
  422.  
  423.   o The NetRexxC.zip file should be copied 'as-is', that is, use FTP
  424.     or other file transfer with the BINARY option.  The CLASSPATH
  425.     should be set to include this NetRexxC.zip file.
  426.  
  427.   o Other files (documentation, etc.) should be copied as Text (that
  428.     is, they will be translated from ASCII to EBCDIC).
  429.  
  430. In general, binary files (.class files, and .zip files containing .class
  431. files) should always be transferred as BINARY -- the same binaries run
  432. on all platforms.
  433.  
  434. For specific hints and tips for installing on OS/390, see Mark
  435. Cathcart's web site at
  436.  
  437.   http://www.s390.ibm.com/corner
  438.  
  439. which includes a presentation that describes OS/390 Java and NetRexx
  440. installation.  Setting the classpath might look like this:
  441.  
  442.   export CLASSPATH=$CLASSPATH:/u/j390/j1.1.1/lib/NetRexxC.zip
  443.  
  444. --- Installing NetRexx for use with Visual J++ ---
  445.  
  446. (Many thanks to Bill Potvin and Bernhard Hurzeler for the details in
  447. this and the following section.)
  448.  
  449.   1. Copy the following file into the [java_root]\Lib directory:
  450.  
  451.        NetRexxC.zip
  452.  
  453.      For example, if [java_root] is "E:\Java":
  454.  
  455.        C:\>copy NetRexxC.zip E:\Java\Lib
  456.  
  457.   2. Similarly, copy the nrc.bat and NetRexxC.bat files to the
  458.      [java_root]\Bin directory.
  459.  
  460.   3. Add the zip file explicitly to the CLASSPATH:
  461.  
  462.        C:\>set CLASSPATH=%CLASSPATH%;[java_root]\Lib\NetRexxC.zip;
  463.  
  464.      For example, if [java_root] is "E:\Java", your CLASSPATH
  465.      might then look like this:
  466.  
  467.        CLASSPATH=E:\Java\Lib;E:\Java\TrustLib;E:\Java\Lib\NetRexxC.zip;
  468.  
  469.      Under Windows NT 4.0 this can be done using Start, Settings,
  470.      Control Panel, System, Environment tab, System Variables, and
  471.      clicking on CLASSPATH.
  472.  
  473. --- Using NetRexx with Visual J++ ---
  474.  
  475.   1. Use the J++ "jview" command to invoke the NetRexx translator to
  476.      convert a NetRexx program (e.g., hello.nrx) into a Java program
  477.      (hello.java).
  478.  
  479.      Note that some versions of the jview package do not provide a
  480.      "classes.zip" file by default, but the NetRexx compiler needs this
  481.      to determine information about classes that you use.  If this is
  482.      the case, you will get a 'class not found' error for
  483.      "java.lang.Object".  In this case, run the command
  484.  
  485.        clspack -auto
  486.  
  487.      from a MS-DOS prompt to create the classes.zip file.
  488.  
  489.      When running the NetRexx compiler, you must specify the
  490.      "-nocompile" option to NetRexx in order to prevent it from trying
  491.      to invoke the Java toolkit compiler (which isn't in the MicroSoft
  492.      J++ classes).
  493.  
  494.      For example, if hello.nrx is in the current directory:
  495.  
  496.        jview COM.ibm.netrexx.process.NetRexxC hello -nocompile
  497.  
  498.      The result of this step should be a Java source file called
  499.      "hello.java".
  500.  
  501.   2. Use the J++ "jvc" command to compile the Java source file:
  502.  
  503.        jvc hello.java
  504.  
  505.      The result of this step should be a Java .class file called
  506.      "hello.class".
  507.  
  508.   3. Execute the class file with the J++ command "jview":
  509.  
  510.        jview hello
  511.  
  512. Note that all the commands above probably have to be typed exactly as
  513. shown (Java is very case-sensitive).  The supplied NetRexxC.bat can be
  514. modified to work with the above commands by using 'jview' instead of the
  515. 'java' command and adding the 'jvc' step.
  516.  
  517.  
  518. Problems?
  519. '''''''''
  520. If the 'hello' example doesn't work, one of the following problems
  521. may be the cause:
  522.  
  523.   o A "Can't find class COM.ibm.netrexx.process.NetRexxC..." message
  524.     probably means that the NetRexxC.zip file has not been specified in
  525.     your CLASSPATH setting, or is misspelled, or is in the wrong case.
  526.     The CLASSPATH is the setting that Java uses to find classes for
  527.     execution; please refer to your Java installation instructions for
  528.     information on setting the CLASSPATH.
  529.  
  530.   o A "Can't find class hello..." message may mean that the directory
  531.     with the hello.class file is not in your CLASSPATH, or either the
  532.     filename or name of the class (in the source) is spelled wrong (the
  533.     java command is [very] case-sensitive).
  534.  
  535.   o You didn't install on a file system that supports long file
  536.     names (for example, on OS/2 or Windows you should use an HPFS disk
  537.     or equivalent).  Like most Java applications, NetRexx uses long file
  538.     names.
  539.  
  540.   o You have a down-level Unzip or Tar program.  Check that the
  541.     file 'NetRexxC.zip', with just three capital letters, exists in the
  542.     subdirectory 'lib' below the Java home directory.
  543.  
  544.   o You have only the Java runtime installed, and not the toolkit.  If
  545.     the toolkit is installed, you should have a program called javac
  546.     on your computer.
  547.  
  548.   o You have a down-level version of Java installed.  NetRexxC 1.1xx
  549.     will run only on Java version 1.1.0 (and later versions).  You can
  550.     check the version of Java you have installed using the command 'java
  551.     -version'.  An older version of the NetRexx package is available for
  552.     Java 1.0, however that version will no longer be enhanced or
  553.     supported in any way.
  554.  
  555.   o Your Java toolkit installation has .class files from an earlier
  556.     installation of NetRexx in classes/java/lang, classes/netrexx/lang,
  557.     or other subdirectories in the 'classes' directory below the Java
  558.     home directory.
  559.  
  560.     A message that reports ambiguous class references is a likely sign
  561.     of this problem.  The easiest way to solve it is to re-install the
  562.     Java toolkit in a clean subdirectory.
  563.  
  564.   o An 'Out of environment space' message when trying to set CLASSPATH
  565.     under Win95-DOS can be remedied by adding /e:4000 to the 'Cmd line'
  566.     entry for the MS-DOS prompt properties (try 'command /?' for more
  567.     information).
  568.  
  569.   o If, when reporting an error or warning, the compiler gives a rather
  570.     cryptic identifier and reports 'Sorry, full message not available',
  571.     this means that it could not find the NetRexxC.properties (error
  572.     messages) file, which should be in the COM.ibm.netrexx.process
  573.     package (in NetRexxC.zip).
  574.  
  575.   o A java.lang.OutOfMemoryError when running the compiler probably
  576.     means that the maximum heap size is not sufficient.  The initial
  577.     size depends on your Java virtual machine; you can change it to
  578.     (say) 24 MegaBytes by setting the environment variable:
  579.  
  580.       SET NETREXX_JAVA=-mx24M
  581.  
  582.     The NetRexxC.cmd and .bat files add the value of this environment
  583.     variable to the options passed to java.exe.
  584.  
  585.   o An exception, apparently in the Rexx translate method, when
  586.     compiling with Microsoft Java SDK 3.1 (and possibly later SDKs) is
  587.     caused by a bug in the just-in-time compiler (JIT) in that SDK.
  588.     Turn off the JIT using Start -> Settings -> Control Panel ->
  589.     Internet to get to the Internet Properties dialog, then select
  590.     Advanced, scroll to the Java VM section, and uncheck 'Java JIT
  591.     compiler enabled'.
  592.  
  593.   o An 'Exception 0005' when using the OS/2 beta Java 1.1.1 toolkit is
  594.     probably caused by the just-in-time compiler.  Try turning it off
  595.     before running NetRexxC by setting the environment variable:
  596.  
  597.       SET JAVA_COMPILER=no
  598.  
  599.     (and ignore the 'unable to load dll' message).
  600.  
  601.   o An ArrayIndexOutOfBoundsException when compiling hello.nrx under AIX
  602.     is caused by an early faulty JIT.  Either disable the JIT (as for
  603.     OS/2) or update your AIX Java SDK.
  604.  
  605.  
  606. Installation of just the NetRexx classes
  607. ''''''''''''''''''''''''''''''''''''''''
  608. To install only the NetRexx runtime classes (you don't need to do this
  609. if you already installed the NetRexxC compiler), follow the instructions
  610. for installing the compiler, but set your CLASSPATH to refer to
  611. NetRexxR.zip instead of NetRexxC.zip.  Only the NetRexxR.zip is needed,
  612. so you may prefer to extract just this file from the nrtools package.
  613.  
  614. The NetRexx class files can then be referred to from Java or NetRexx
  615. programs as from package 'netrexx.lang'.  For example, a string might be
  616. of class 'netrexx.lang.Rexx'.
  617.  
  618.  
  619. Using the NetRexx compiler
  620. """"""""""""""""""""""""""
  621. The installation instructions for the NetRexx compiler describe how to
  622. use the package you installed to compile and run a simple NetRexx
  623. program.  This section explains more of the options available to you.
  624.  
  625. --- Invoking the compiler as a command ---
  626.  
  627. The compiler is a Java program (class) which is called
  628. COM.ibm.netrexx.process.NetRexxC (NetRexxC for short). This can be
  629. invoked using the Java interpreter, for example, by the command:
  630.  
  631.   java COM.ibm.netrexx.process.NetRexxC
  632.  
  633. or by using a system-specific command (such as 'NetRexxC' or 'nrc').  In
  634. either case, the compiler invocation is followed by one or more file
  635. specifications (these are the names of the files containing the NetRexx
  636. source code for the programs to be compiled).
  637.  
  638. File specifications may include a path; if no path is given then
  639. NetRexxC will look in the current (working) directory for the file.
  640. NetRexxC will add the extension '.nrx' to input program names (file
  641. specifications) if no extension was given.
  642.  
  643. So, for example, to compile 'hello.nrx' in the current directory, you
  644. can use any of:
  645.  
  646.   java COM.ibm.netrexx.process.NetRexxC hello
  647.   java COM.ibm.netrexx.process.NetRexxC hello.nrx
  648.   NetRexxC hello.nrx
  649.   nrc hello
  650.  
  651. (the first two should always work, the last two require that the
  652. system-specific command be available).  The resulting .class file is
  653. placed in the current directory, and the .crossref (cross-reference)
  654. file is placed in the same directory as the source file (if there are
  655. any variables and the compilation has no errors).
  656.  
  657. Here's an example of compiling two programs, one of which is in the
  658. directory 'D:\myprograms':
  659.  
  660.   nrc hello d:\myprograms\test2.nrx
  661.  
  662. In this case, again, the .class file is placed in the current directory.
  663.  
  664. Note that when more than one program is specified, they are all compiled
  665. with the same class context: that is, they can 'see' the classes,
  666. properties, and methods of the other programs being compiled, much as
  667. though they were all in one file.  This allows mutually interdependent
  668. programs and classes to be compiled in a single operation (but see the
  669. section "Compiling multiple programs" below, if you use the PACKAGE
  670. instruction).
  671.  
  672. The programs do, however, maintain their independence (that is, they may
  673. have different options, import, and package instructions).
  674.  
  675. On completion, the NetRexxC command will exit with one of three return
  676. values: 0 if the compilation of all programs was successful, 1 if there
  677. were one or more Warnings, but no errors, and 2 if there were one or
  678. more Errors.
  679.  
  680. As well as file names, you can also specify various option words, which
  681. are distinguished by the first character of the word being '-'.  These
  682. may be any of the option words allowed on the NetRexx OPTIONS
  683. instruction (see the NetRexx language documentation), prefixed with '-'.
  684. These options words can be freely mixed with file specifications.
  685.  
  686. The compiler also implements some additional option words, which cannot
  687. be used on the OPTIONS instruction:
  688.  
  689.   o -keep       keep the intermediate .java file for each program.  It
  690.                 is kept in the same directory as the NetRexx source file
  691.                 as xxx.java.keep, where xxx is the source file name.
  692.                 The file will also be kept automatically if the javac
  693.                 compilation fails for any reason.
  694.  
  695.   o -nocompile  do not compile (just translate).  Use this option when
  696.                 you want to use a different Java compiler.  The .java
  697.                 file for each program is kept in the same directory as
  698.                 the NetRexx source file, as the file xxx.java (where xxx
  699.                 is the source file name); any -keep option is ignored.
  700.  
  701.   o -noconsole  do not display compiler messages on the console (command
  702.                 display screen).
  703.  
  704.   o -savelog    write compiler messages to the file NetRexxC.log, in the
  705.                 current directory.
  706.  
  707.   o -time       display translation, javac compile, and total times (for
  708.                 the sum of all programs processed).
  709.  
  710. If you are using the provided NetRexxC or nrc scripts, then an
  711. additional option is available:
  712.  
  713.   o -run        run the resulting JAVA class as a stand-alone
  714.                 application, provided that the compilation had no
  715.                 errors.
  716.  
  717. Here are some examples:
  718.  
  719.   java COM.ibm.netrexx.process.NetRexxC hello -keep -strictargs
  720.   java COM.ibm.netrexx.process.NetRexxC -keep hello wordclock
  721.   java COM.ibm.netrexx.process.NetRexxC hello wordclock -nocompile
  722.   nrc hello
  723.   nrc hello.nrx
  724.   nrc -run hello
  725.   nrc -run Spectrum -keep
  726.   nrc hello -binary -verbose1
  727.   nrc hello -noconsole -savelog -format -keep
  728.  
  729. Option words may be specified in lowercase, mixed case, or uppercase.
  730. File specifications are platform-dependent and may be case sensitive,
  731. though NetRexxC will always prefer an exact case match over a mismatch.
  732.  
  733. Note that the -run option is implemented by the script, not the
  734. compiler; some scripts (such as NetRexxC.bat) may require that the
  735. '-run' be the first word of the command arguments, and/or be in
  736. lowercase.  They may also require that only the name of the file be
  737. given if the -run option is used.
  738.  
  739. --- Compiling multiple programs and using packages ---
  740.  
  741. When you specify more than one program for NetRexxC to compile, they are
  742. all compiled with the same class context: that is, they can 'see' the
  743. classes, properties, and methods of the other programs being compiled,
  744. much as though they were all in one file.
  745.  
  746. This allows mutually interdependent programs and classes to be compiled
  747. in a single operation.  For example, consider the following two programs
  748. (assumed in your current directory, as the files X.nrx and Y.nrx):
  749.  
  750.   /* X.nrx */
  751.   class X
  752.     why=Y null
  753.  
  754.   /* Y.nrx */
  755.   class Y
  756.     exe=X null
  757.  
  758. each contains a reference to the other, so neither can be compiled in
  759. isolation.  However, if you compile them together, using the command:
  760.  
  761.   nrc X Y
  762.  
  763. then the cross-references will be resolved correctly.
  764.  
  765. The total elapsed time will be significantly less, too, as the classes
  766. on the CLASSPATH need to be located only once, and the class files used
  767. by the NetRexxC compiler or the programs themselves will also only be
  768. loaded once.
  769.  
  770. This example works as you would expect for programs that are not in
  771. packages.  There's a restriction, though, if the classes you are
  772. compiling _are_ in packages (that is, they include a PACKAGE
  773. instruction).  Currently, NetRexxC uses the javac compiler to generate
  774. the .class files, and for mutually-dependent files like these, javac
  775. requires that the source files be in the Java CLASSPATH, in the
  776. sub-directory described by the PACKAGE instruction.
  777.  
  778. So, for example, if your project is based on the tree:
  779.  
  780.   D:\myproject
  781.  
  782. then if the two programs above specified a package, thus:
  783.  
  784.   /* X.nrx */
  785.   package foo.bar
  786.   class X
  787.     why=Y null
  788.  
  789.   /* Y.nrx */
  790.   package foo.bar
  791.   class Y
  792.     exe=X null
  793.  
  794. then:
  795.  
  796.   1. You should put these source files in the directory: D:\myproject\foo\bar
  797.  
  798.   2. The directory D:\myproject should appear in your CLASSPATH setting
  799.      (if you don't do this, javac will complain that it cannot find one
  800.      or other of the classes).
  801.  
  802.   3. You should then make the current directory be D:\myproject\foo\bar
  803.      and then compile the programs using the command 'nrc X Y', as
  804.      above.
  805.  
  806. With this procedure, you should end up with the .class files in the same
  807. directory as the .nrx files, and therefore also on the CLASSPATH and
  808. immediately usable by other packages.  In general, this arrangement is
  809. recommended whenever you are writing programs that reside in packages.
  810.  
  811. Note that when javac is used to generate the .class files, no new .class
  812. files will be created if any of the programs being compiled together had
  813. errors -- this avoids accidentally generating mixtures of new and old
  814. .class files that cannot work with each other.
  815.  
  816. Note also that if class is abstract or is an adapter class then it
  817. should be placed in the list before any classes that extend it (as
  818. otherwise any automatically generated methods will not be visible to the
  819. subclasses).
  820.  
  821. --- Invoking the compiler from Java ---
  822.  
  823. The compiler may be called from a Java program directly, by invoking the
  824. method in the COM.ibm.netrexx.process.NetRexxC class described as
  825. follows:
  826.  
  827.   method main(arg=Rexx, log=PrintWriter null) static returns int
  828.  
  829. The Rexx string passed to the method can be any combination of program
  830. names and options (except -run), as described above.  A sample NetRexx
  831. program that invokes the NetRexx compiler to compile a program called
  832. 'test' is:
  833.  
  834.  /* compiletest.nrx */
  835.  s='test -keep -verbose4 -utf8'
  836.  say COM.ibm.netrexx.process.NetRexxC.main(s)
  837.  
  838. The returned int value will be one of the return values described above.
  839.  
  840. The second argument to the main method is an optional PrintWriter
  841. stream.  If provided, compiler messages will be written to that stream
  842. (in addition to displaying them on the console, unless -noconsole is
  843. specified).  It is the responsibility of the caller to create the stream
  844. (autoflush is recommended) and to close it after calling the compiler.
  845. The -savelog compiler option is ignored if a PrintWriter is provided
  846. (the -savelog option creates a PrintWriter for the file NetRexxC.log).
  847.  
  848. NetRexxC is thread-safe (the only static properties are constants), but
  849. it is not known whether javac is thread-safe.  Hence the invocation of
  850. multiple instances of NetRexxC on different threads should probably
  851. specify -nocompile, for safety.
  852.  
  853.  
  854. NetRexx classes and Applets for the Web
  855. """""""""""""""""""""""""""""""""""""""
  856. If you write applets for the World Wide Web (or your intranet) in
  857. NetRexx, you will probably need to use the NetRexx classes
  858. (netrexx.lang.Rexx, _etc._); they will be used automatically if the
  859. default compilation options (specifically, options nobinary) are in
  860. effect.
  861.  
  862. A good way of setting up an HTTP (Web) server for this is to keep all
  863. your applets in one subdirectory; you can then make the NetRexx runtime
  864. classes (that is, the classes in the package known by Java as
  865. netrexx.lang) available to all the applets by unzipping NetRexxR.zip
  866. into a subdirectory netrexx/lang below your applets directory.
  867.  
  868. For example, if the root of your server tree is
  869.  
  870.   D:/mydata
  871.  
  872. then you might put your applets into
  873.  
  874.   D:/mydata/applets
  875.  
  876. and then the NetRexx classes (unzipped from NetRexxR.zip) should be in
  877. the directory
  878.  
  879.   D:/mydata/applets/netrexx/lang
  880.  
  881. The same principle is applied if you have any other Java packages that
  882. you want to make available to your applets: the classes in a package
  883. called fred.math.quicksorts would go in a subdirectory below applets
  884. called fred/math/quicksorts, for example.
  885.  
  886. Note that with Java 1.1 it should be possible to use the classes direct
  887. from the NetRexxR.zip file (which is in fact a Java 'jar' file),
  888. providing that the browser being used is at a Java 1.1 level.  See the
  889. Java 1.1 documentation for details.
  890.  
  891.  
  892. Printable documentation
  893. """""""""""""""""""""""
  894. The NetRexx printable package (NetRexxD.zip, or NetRexxD.tar.Z) contains
  895. the printable NetRexx documentation, in PostScript format.
  896.  
  897.   1. Copy the package file to the root directory of your choice for
  898.      documentation, preserving the original name.
  899.  
  900.   2. With your chosen directory as your current directory, unpack the
  901.      package, following the instructions in 'Unpacking NetRexx packages'
  902.      above.
  903.  
  904.      This should add the directory 'NetRexxD' to your chosen directory,
  905.      containing the printable documentation for NetRexx.
  906.  
  907.   3. You can print files from the new directory that have the extension
  908.      '.ps' on any PostScript printer, using the appropriate method for
  909.      printing for your operating system.  There are also utilities, such
  910.      as 'GhostScript', available from public sources for viewing
  911.      PostScript files and for printing them on non-PostScript printers.
  912.  
  913.  
  914. Current restrictions
  915. """"""""""""""""""""
  916. The NetRexx processor is now functionally complete, though work
  917. continues on usability and performance improvements.  As of this version
  918. there are still a number of restrictions, listed below.
  919.  
  920. Please note that the presence of an item in this section is not a
  921. commitment to remove a restriction in some future update; NetRexx
  922. enhancements are dependent on on-going research, your feedback, and
  923. available resources.  You should treat this list as a 'wish-list' (and
  924. please send in your wishes).
  925.  
  926. --- Short-term restrictions ---
  927.  
  928. The following problem may occur in larger methods, with Java 1.0.1,
  929. 1.0.2, or 1.1.2 (it seems to have been fixed in later versions):
  930.  
  931.   o NetRexxC does not restrict the number of local variables used or
  932.     generated.  However, the 1.0 javac compiler fails with unrelated
  933.     error messages (such as 'statement unreachable' or 'variable may be
  934.     uninitialized') if asked to handle more than 63 local variables.
  935.  
  936. --- Long term restrictions ---
  937.  
  938. The following restrictions are due to the use of a translator, and would
  939. probably only be lifted if a direct-to-bytecodes NetRexx compiler were
  940. built.
  941.  
  942.   o Externally-visible names (property, method, and class names) cannot
  943.     be Java reserved words (you probably want to avoid these anyway),
  944.     and cannot start with '$0'.
  945.  
  946.   o There are various restrictions on naming and the contents of
  947.     programs (the first class name must match the program name, etc.).
  948.  
  949.   o The javac compiler requires that mutually-dependent source files be
  950.     on the CLASSPATH, so javac can find the source files.  NetRexxC does
  951.     not have this restriction, but when using javac for the final
  952.     compilation you will need to follow the convention described under
  953.     'Compiling multiple programs', above.
  954.  
  955.   o The 'symbols' option applies to all programs compiled together if
  956.     any of them specify that option.
  957.  
  958.   o Some binary floating point underflows may be treated as zero instead
  959.     of being trapped as errors.
  960.  
  961.   o Side-effects of calls to this() and super() in constructors may be
  962.     seen before the method and method call instructions are traced --
  963.     this is because Java does not permit tracing instructions to be
  964.     added before the call to this() or super().
  965.  
  966.   o The results of expressions consisting of the single term 'null' are
  967.     not traced.
  968.