 
OBJECT REXX FOR OS/2 READ.ME

  This READ.ME file provides instructions on how to install Object REXX for 
  OS/2 and describes requirements and important information on using Object
  REXX. Please read this document before installing Object REXX.

  The information covered in this document includes:
 
   -- GENERAL OBJECT REXX BETA OBJECTIVES
   -- ENHANCEMENTS TO OBJECT REXX
   -- INSTRUCTIONS FOR INSTALLING OBJECT REXX ON OS/2
       -- MATERIALS
       -- DOCUMENTATION
       -- SYSTEM REQUIREMENTS
       -- INSTALLATION OF OBJECT REXX
   -- EXPLORING OBJECT REXX
   -- USING OBJECT REXX AS THE DEFAULT REXX
   -- NOTES ON RUNNING YOUR EXISTING REXX PROGRAMS
   -- USING OBJECT REXX WITH THE OS/2 WORKPLACE SHELL
   -- NOTES ON RUNNING OBJECT REXX WPS PROGRAMS
 

GENERAL OBJECT REXX BETA OBJECTIVES
 
  The objective of this Object REXX beta is to ensure upward compatibility
  with existing REXX and to expose you to the new Object REXX features that
  you can use to develop object-oriented programs. Sample programs and online
  documentation are also provided to assist you with Object REXX.

  This Object REXX beta does not contain a visual builder which would interact
  with Object REXX programs. It can however be run with some existing products
  such as VisPro/Rexx, VX-REXX (greater than version 1.0) and DrDialog (found
  elsewhere on this volume of The Developer Connection for OS/2).
 
  We are interested in your feedback on Object REXX and any problems you may
  find. Please use the SURVEY.YOU file provided to comment on this Object REXX
  beta.
 

ENHANCEMENTS TO OBJECT REXX 
 
  The following enhancements have been made to this Object REXX beta level:

    - Improved performance and reduced size of executables
    - Added Workplace Shell sample programs
    - Enhanced online documentation (new Object REXX Programming Guide)
    - Additional SOM support
    - Corrected miscellaneous bugs
 
 
INSTRUCTIONS FOR INSTALLING OBJECT REXX ON OS/2
 
MATERIALS:
 
  This directory contains the materials needed to install Object REXX
  on OS/2. No installation diskette images are provided with this level
  of Object REXX.
 
DOCUMENTATION:
 
  REXXPG.INF
     This on-line reference file is the latest Object REXX Programming
     Guide for OS/2. This file contains information on how to use Object
     REXX to develop object-oriented programs. To view this file, issue
     the command 'VIEW REXXPG.INF' at an OS/2 command prompt.
 
  OBJREXXO.INF
     This on-line reference file is the latest Object REXX Reference 
     information which describes Object REXX for OS/2. To view this file,
     issue the command 'VIEW OBJREXXO.INF' at an OS/2 command prompt.
 
  SOMREQ.DOC
     This text file discusses the requirements for building and using a
     SOM class in Object REXX. This file is installed with the Object REXX
     samples.
 

SYSTEM REQUIREMENTS:
 
     (1) OS/2 2.1 or later (with REXX installed) 
 
     (2) 2.9MB of hard disk space for the entire Object REXX package
         which includes the following components:
 
           Object REXX executables & documentation  (2.7MB)
           Object REXX samples                      (0.2MB)
 
 
     (3) *** IBM System Object Model (SOM) 2.1
 
         *** This level of Object REXX requires a newer level of SOM than
         previous levels. Make sure you have the required level of SOM
         installed BEFORE installing this level of Object REXX. 

         If running OS/2 2.1 or OS/2 2.11, you need to install the IBM
         System Object Model (SOM) 2.1 runtime. The required level of SOM
         can be found in the IBM Developers Toolkit for OS/2 WARP Version 3,
         located elsewhere on this volume of The Developer Connection for OS/2.
         Install the SOM Tools, which are located within the Development Tools
         selection shown by the toolkit installation.

         If running OS/2 WARP 3.0, the SOM 2.1 runtime is already included,
         so you do not need to install SOM 2.1.

 
INSTALLATION OF OBJECT REXX:
 
     The Object REXX install program will take you through the installation
     of Object REXX for OS/2. You will be prompted for which components of
     Object REXX you want to install and the directories where you want
     the Object REXX files installed. The default directory used by the 
     install program is 'C:\OREXX'. This install program will not replace
     the existing REXX files already installed on your system. 

     Object REXX is installed in a way which allows it to coexist with the 
     existing REXX on your system. If you would like to use Object REXX as
     the default REXX running on your system, you will need to make additional
     changes (see "USING OBJECT REXX AS THE DEFAULT REXX" after you install
     Object REXX).

     NOTE: If you are currently running Object REXX as the default REXX on
           your system, you need to first remove Object REXX as the default
           BEFORE installing a new level or installing over an existing level.
           To remove Object REXX as the default, make the following changes
           to your CONFIG.SYS file. Move the Object REXX directory to the end
           of these statements and reboot your system.

              LIBPATH=...;C:\OREXX;
              SET PATH=...;C:\OREXX;
              SET DPATH=...;C:\OREXX;
              SET HELP=...;C:\OREXX;

     (1) Run the Object REXX install program:
 
             'INSTALL'

         If you have installed a previous level of Object REXX, the install
         program will allow you to delete the previous level and reinstall or
         update the previous level of Object REXX you have installed. If you
         elect to delete the previous level or elect to replace existing files,
         some Object REXX files may not be removed or replaced right away and
         you will need to reboot your system to allow these changes to occur.

         During install, you may elect to have your CONFIG.SYS file updated
         for you. If you elect not to have this file updated, you will need
         to make the following changes to your CONFIG.SYS file. Add your 
         Object REXX executables directory to the end of the LIBPATH, PATH, 
         DPATH, and HELP statements. Also, update the SOMIR environment 
         variable to add the paths for the Object REXX ".IR" files. These
         changes should be similiar to the following:

         LIBPATH=...;C:\OREXX;
         SET PATH=...;C:\OREXX;
         SET DPATH=...;C:\OREXX;
         SET HELP=...;C:\OREXX;
         SET SOMIR=.\SOM.IR;C:\SOM\ETC\SOM.IR;...;
           C:\OREXX\REXXWPS.IR;C:\OREXX\ORXSOM.IR;C:\OREXX\SAMPLES\ORXSMP.IR;

         After you have made your CONFIG.SYS changes, you will need to reboot
         your system before running Object REXX.
 

EXPLORING OBJECT REXX
 
  Once you have installed the Object REXX files, you can run Object REXX.
  Object REXX is not installed as your default REXX, so you can explore
  Object REXX while running your existing REXX programs at the same time.
 
  To run programs with Object REXX, you need to specify "ORX" prior to
  the name of the program you are running.
 
     For example, to run the REXXTRY program shipped with Object REXX,
     enter:
 
     'ORX REXXTRY'
 
     Within REXXTRY, you can try out the new Object REXX syntax,
     for instance:
 
       say .object                    /* displays 'The Object class'   */
       myarray=.array~of(4,3,2,1)     /* creates a 4 element array     */
       do i over myarray; say i; end  /* displays all 4 array elements */

     To help you explore programming in Object REXX, the following sample
     source programs and class definitions are provided:
 
       - animal:   interacts with SOM class ANIMAL
       - ccreply:  concurrent program using REPLY
       - complex:  complex number class
       - factor:   factorial program
       - greply:   concurrent program using WAIT and NOWAIT
       - guess:    a guessing game
       - ktguard:  concurrent program using START and GUARD
       - month:    displays days of the month of January
       - pipe:     a pipeline implementation 
       - qdate:    date query program
       - qtime:    time query program
       - semcls:   semaphore class 
       - stack:    program which uses a stack class
       - usecomp:  program which uses complex number class
       - usepipe:  program which uses pipeline implementation

  NOTE: While exploring Object REXX in this manner, you will not be able
        to use Object REXX with existing visual builders or programs that
        use the REXX API functions, including PMREXX. These programs will
        run with your existing REXX as before.
        

USING OBJECT REXX AS THE DEFAULT REXX
 
  If you would like to run Object REXX with existing visual builders or
  programs that use REXX API functions, you need to make the following
  changes to be able to use Object REXX as the default REXX running on
  your system. With this method of running Object REXX, all of your
  existing REXX programs will be using Object REXX.

  Update your CONFIG.SYS file to enable the Object REXX executables prior to
  OS/2 REXX. Move your Object REXX executables directory ahead of the \OS2\DLL
  directory in the LIBPATH statement of your CONFIG.SYS file. Move this same
  directory ahead of the \OS2 directory in your PATH, DPATH, and HELP statements
  as well. These changes should be similar to the following:

         LIBPATH=C:\OREXX;...;
         SET PATH=C:\OREXX;...;
         SET DPATH=C:\OREXX;...;
         SET HELP=C:\OREXX;...;

  Once you have made these changes to CONFIG.SYS, you will need to reboot
  your system (If at any time you need to back off using Object REXX as the
  default REXX, simply move the Object REXX executables directory back to
  the end of your paths in CONFIG.SYS and reboot).
 
  This will replace REXX, but while you run with Object REXX, you will still
  have the same REXX capabilities as before. Also, your programs can now
  be run with Object REXX, just as they are run with REXX today.
 
     For example, to run the REXXTRY program in Object REXX just as you 
     would with your existing REXX, enter:
 
     'REXXTRY'
 
     Within REXXTRY, you can try out the new Object REXX syntax here, too.
 

NOTES ON RUNNING YOUR EXISTING REXX PROGRAMS:
 
 For the most part, any existing REXX programs you have should
 work with Object REXX.  There are, however, some differences.
 
   - Some error codes have changed and some have been added.  Also,
     for most errors you will now receive 2 error messages.  The
     first should be similar (if not identical) to the message you
     would have seen previously.  The second provides additional
     and more detailed information.  So, for example, where you formerly
     received "Invalid Call to Routine", you will now get further
     information on what is wrong with the call.
 
   - Some errors are now detected earlier.  Formerly, REXX would wait
     until it encountered an error during execution to report it
     to you.  Now, some errors will be reported before the first
     instruction in your REXX script is run.  In particular, syntax
     errors which indicate your program is not well-formed REXX
     (there is a missing END or an unmatched parenthesis, for example)
     will be reported after you have invoked the program but before it
     begins executing.
 
   - The SEEK command used with the STREAM function will require an
     option (READ, WRITE, etc) when used to set the position within
     a stream that is opened for both reading and writing.
 
   - When using "ORX" to run your REXX programs, Object REXX searches
     first for ".ORX" file extensions.
 

USING OBJECT REXX WITH THE OS/2 WORKPLACE SHELL
 
  If you would like to use Object REXX with WorkPlace Shell objects, you
  need to first make sure you are running Object REXX as the default REXX
  on your system (see "USING OBJECT REXX AS THE DEFAULT REXX" above).

  Then, follow these steps:
 
     (1) Update the SOMIR environment variable in your CONFIG.SYS file 
         to add the path for the Object REXX ".IR" files. The SOMIR
         statement should be similar to the following.

           SET SOMIR=.\SOM.IR;C:\SOM\ETC\SOM.IR;...
           C:\OREXX\REXXWPS.IR;C:\OREXX\ORXSOM.IR;C:\OREXX\SAMPLES\ORXSMP.IR;

         If you elected to have your CONFIG.SYS file updated for you during
         install, the Object REXX install program will have made this change.
         Make sure the SOMIR environment variable in your CONFIG.SYS file is
         correct and then follow the next step.

         Otherwise, you will need to make this change to your CONFIG.SYS file
         and reboot your system. When you return, continue to the next step
         to complete the setup for using Object REXX with the WorkPlace Shell.
 
     (2) Run the Object REXX class install program which will register the
         necessary WorkPlace Shell classes used with Object REXX.
         Enter the following at the OS/2 command prompt:

         Change to your Object REXX directory, for example:
 
             'CD OREXX'

         Then enter:

             'WPSINST'

         The WPSINST.CMD program will register Object REXX classes with the
         WorkPlace Shell. You can also use this program at any time to query
         these Object REXX classes, and to register and deregister them.

         If at any time you need to back off using Object REXX with the OS/2
         WorkPlace Shell, deregister the Object REXX classes by entering the 
         following command at the OS/2 command prompt:

             'WPSINST -'

     NOTE: We recommend that you deregister the Object REXX classes before 
           installing a new level of Object REXX or at any time that you
           decide to remove Object REXX as the default REXX on your system.
 
     To help you use Object REXX with the OS/2 Workplace Shell, the following
     sample source programs and class definitions are provided:
 
       - wpsorxcl: Workplace Shell example using OREXX classes
       - wpsorxfl: Workplace Shell folder example


NOTES ON RUNNING OBJECT REXX WPS PROGRAMS:

   - Section 'REXX and the Workplace Shell' in the online Object REXX
     reference refers you to the OS/2 Technical Library for documentation
     of the workplace classes and methods.  You can find this information
     in the OS/2 WARP Toolkit provided as part of this volume of The
     Developer Connection for OS/2.  See the following online books,
     "Workplace Shell Programming Guide" (file WPSGUIDE.INF) and
     "WorkPlace Shell Reference" (files WPS1.INF, WPS2.INF, and WPS3.INF)
     for information on OS/2 Workplace Shell programming interfaces.
 
   - Use caution if you are deleting WPS objects (via wpDelete method).
     Drop the WPS object variable after a wpDelete to ensure all references
     have been removed.

   - Use of WPPort, WPPdr, WPQdr classes are currently not supported.

