
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:

   -- ENHANCEMENTS TO OBJECT REXX
   -- INSTRUCTIONS FOR INSTALLING OBJECT REXX ON OS/2
       -- MATERIALS
       -- DOCUMENTATION
       -- SYSTEM REQUIREMENTS
       -- INSTALLATION OF OBJECT REXX
       -- SOLVING PROBLEMS USING OBJECT REXX
   -- EXPLORING OBJECT REXX
   -- SWITCHING REXX INTERPRETERS
   -- NOTES ON RUNNING YOUR EXISTING REXX PROGRAMS
   -- USING OBJECT REXX WITH THE OS/2 WORKPLACE SHELL
   -- NOTES ON RUNNING OBJECT REXX WPS PROGRAMS
   -- NOTES ON OPENDOC


ENHANCEMENTS TO OBJECT REXX

  The following enhancements have been made to this Object REXX level:

    - Bugs corrected in 99/05 release:
       * Calling function Trace() with an invalid option no longer
         causes an access violation.
       * Function FORMAT() no longer creates extranuous trailing blanks
         for certain numbers.
       * Sliding window algorithm for two digit years adjusted for
         some cases in Date() function.
       * Several syntax errors reported will now show the correct
         source line location in the user program.
       * A single LF that falls on the internal buffer boundary is no
         longer ignored.
       * Piped input no longer contains additional characters.
       * Literals no longer cause and error with the VALUE() function.
       * DATE("S") with output separator specified now formatted correctly.
       * Memory leak when reading from streams has been removed.
       * Memory leak when creating many stream objects has been removed.
       * ARRAYIN method of the stream class no longer raises the NOTREADY
         condition.
       * When a stack overflow is encountered it will be handled correctly
         without causing an application error.
       * RANDOM(1,,99) no longer causes an application error.
       * STREAM("STDIN","C","CLOSE) no longer causes a trap.

    - Features added in 99/05 release:
       * New REXXUTIL functions:
           SysDumpVariables, SysGetFileDateTime, SysSetFileDateTime,
           SysStemCopy, SysStemDelete, SysStemInsert, SysStemSort,
           SysUtilVersion, SysVersion
       * If the first line contains a Unix style shell definition starting
         with #! it will be ignored (seen as a comment).

    - Bugs corrected in 98/10 release:
       * OPTIONS EXMODE not working correctly
       * SysFileTree did not work correctly with absolute path from root
         (e.g. "\OS2")
       * Subclassing class STREAM could cause a trap
       * Closing files after changing directories sometimes did not work
       * Broken error message for bad hexadecimal strings
       * Internal memory handling problem
       * Trap with many threads depending on timing at thread termination
       * DO..OVER binary files caused system resources to be exhausted
       * UNINIT method not called when defined in a parent class
       * Last line was ignored by SysFileSearch when not terminated with CR/LF
       * Drop of an object didn't invoke the UNINIT method
       * Stream SEEK command no longer requires READ/WRITE attribute, if none
         is specified BOTH is assumed (to be compatible with classic REXX)
       * TRANSLATE("abc","","") gives incorrect result
       * Trap or unpredictable results with long parse statements
       * Accessing an unqualified filename (no path information) sometimes
         failed after changing the current directory
       * String comparison with padded characters fails if excess character
         is greater than ASCII 127
       * SysFileTree fails to find Win95 LFN directories
       * Long message evaluation expressions not protected from garbage
         collection

    - Features added in 98/10 release:
       * New input and output separators for DATE() function according to
         revised ANSI standard
       * Use double dash -- as line comment according to request by ANSI
         comittee
       * Use single dash - as line continuation character according to
         request by ANSI comittee
       * Default stream open behaviour is now non-shared (as with classic
         REXX). Three new options available to open files in shared mode:
           SHARED     - allow reading and writing from other processes
           SHAREREAD  - allow reading from other processes
           SHAREWRITE - allow writing from other processes
         e.g.:
           CALL STREAM "MYFILE.DAT","C","OPEN READ SHARED"
           CALL STREAM "LOGFILE.TXT","OPEN BOTH SHAREREAD"


    - Bugs corrected in 98/02 release:
       * SysFileTree error when using the 'O' option
       * Speed up processing of LINES() built-in function
       * Stream Query Size returns wrong value for not existing files
       * Memory problems with objects larger than 16 MB
       * CHARS() built-in function returned -1 for certain files
       * Memory leak when working with many files
       * LINES() method and built-in function didn't recognize a single
         character after CR/LF
       * Line count wrong for files ending in CR-LF-EOF
       * WPS support not persistent between reboots

    - Bugs corrected in 97/11 release:
       * External programs can not be started in the foreground
       * FILESPEC returns empty string for certain filename specifications
       * Problem with line continuation character in mixed CRLF/LF files
       * Trap after garbage collection
       * Problem parsing mixed SBCS/DBCS strings
       * Trap when trying to access memory from different processes
       * Corrected a problem with duplicate freed memory in SysIni
       * Wrong error location for duplicate method

    - Features added in 97/11 release:
       * Added functions SysQueryExtLibPath, SysSetExtLibPath,
         SysQuerySwitchList and SysSwitchSession to REXXUTIL.DLL
       * Enable SysIni function to work in non-PM environments (requires
         SHPIINST.DLL in LIBPATH, this REXXUTIL.DLL can be used together
         with REXXCRT.DLL in classic REXX environments)


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.

  REXX.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 REXX.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 WARP 3.0 or later (with REXX installed)

     (2) 2.8MB of hard disk space for the entire Object REXX package
         which includes the following components (all components will
         be installed automatically):

            - executables
            - online documentation
            - sample programs

     (3) IBM System Object Model (SOM) 2.1

         This level of Object REXX requires SOM 2.1. Make sure you have
         the required level of SOM installed BEFORE installing Object REXX.

         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.

         NOTE: If you are planning to create your own DSOM classes you have to
               make sure that SOM is at least at fix level CSD211 since
               earlier versions of SOM toolkits have a bug that will cause
               Object REXX programs to trap if they access DSOM classes built
               with a previous level of the SOM toolkit.


INSTALLATION OF OBJECT REXX:

     The Object REXX install program will take you through the installation
     of Object REXX for OS/2. If you have installed a previous version of
     Object REXX you need to select the 'Delete and reinstall' option.

     Most of the files will be installed to your OS/2 directory for the
     switching mechanism between classic REXX and Object REXX. You will only
     be able to select the drive and directory for the Object REXX sample
     files. The default directory used by the install program is 'C:\OREXX'.

     The installation process makes backup copies of your existing REXX files
     and activates Object REXX for the next reboot of your system. If you
     want to switch back to the classic REXX interpreter see the description
     in chapter "SWITCHING REXX INTERPRETERS".

     NOTE: If you are installing this version of Object REXX on OS/2 WARP 4.0
           it will overwrite the version of Object REXX included with it. If
           you later decide to remove Object REXX from your system you will
           not be able to restore the original Object REXX from OS/2 WARP 4.0.
           Also this installation will not be supported by OS/2 WARP 4.0
           FixPacks.

     (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. You
         have to select the option 'Delete and reinstall' at this point. After
         the current files have been deleted you will be asked to reboot your
         system to activate the changes of the deletion. After the reboot you
         will be able to install Object REXX by running the install program
         again.

         If you encounter problems deleting the currently installed version
         of Object REXX it may be related to the information Software Installer
         remembers for installed products. A small utility is provided that
         helps you removing the old information of Object REXX from the
         Software Installer database. The utility is called ZAPINI.CMD and
         must be called with the drive letter where the EPFIS.INI file is
         located as the first parameter. Normally this would be the boot drive
         of your system. If you have installed OS/2 on drive E: you would
         invoke the utility with:

             'ZAPINI E:'


SOLVING PROBLEMS USING OBJECT REXX

  If you encounter problems after installing Object REXX, here are some hints:

     (1) After running WPSINST.CMD you get an error popup with the message
         'SYS2070 - A program encountered a problem and cannot continue'

         Please select the 'Display register information' radiobutton and
         look at the additional information displayed. Most likely you will
         see the message
           'The system could not demand load the applications's segment. ...'

         This means that Object REXX is not installed as the default REXX on
         your system. Please follow the steps described in "SWITCHING REXX
         INTERPRETERS" below.


EXPLORING OBJECT REXX

  Once you have installed the Object REXX files, you can immediately run
  Object REXX programs.

     For example, you can run the REXXTRY program shipped with Object REXX.
     Enter:

     '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


SWITCHING REXX INTERPRETERS

  A small utility has been added to allow you to switch between the two
  flavours of the REXX interpreters. After installation Object REXX will
  be your system default REXX. If you want to switch back to classic REXX
  or from classic REXX to Object REXX, enter the following on your OS/2
  command prompt:

     'SWITCHRX'

  You will be prompted to confirm the switching mechanism. At this point
  enter "Y" to proceed with the switching algorithm or any other value to
  abort the operation. If you have confirmed the switching operation the
  operation continues. In order to activate the changes you will have to
  reboot the system.

  If you have installed WPS support for Object REXX it will be removed
  when switching from Object REXX to classic REXX. After switching back
  to Object REXX you have to activate WPS support again manually. See
  section "USING OBJECT REXX WITH THE OS/2 WORKPLACE SHELL" below.


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 REXXC utility can be used to perform only
     the syntax checking.

   - 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.

   - The parameters "//T" and "//t" used with a REXX program are the only
     "//" parameters reserved by REXX. All other "//" parameters can now be
     used with REXX programs.

 If you encounter problems running existing REXX programs you can always
 switch back to the classic REXX interpreter. See chapter "SWITCHING REXX
 INTERPRETERS" above.


USING OBJECT REXX WITH THE OS/2 WORKPLACE SHELL

  OS/2 WARP 3.0 is required in order to use the WorkPlace Shell support.
  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 "SWITCHING REXX INTERPRETERS" above).

  Then, follow these steps:

     (1) 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:

             '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 -'

     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.


NOTES ON OPENDOC:
   This level of Object REXX is an updated level compared to the one shipped
   with the OpenDoc Pack on DevCon 9 Special Edition. If you want to use the
   updated version you have to make sure that the directories in LIBPATH,
   PATH, DPATH and HELP pointing to the Object REXX interpreter included in
   the OpenDoc Pack are removed from CONFIG.SYS.

