home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 18 REXX / 18-REXX.zip / orexx.zip / READ.ME < prev    next >
Text File  |  1998-03-25  |  14KB  |  313 lines
  1.  
  2. OBJECT REXX FOR OS/2 - READ.ME
  3.  
  4.   This READ.ME file provides instructions on how to install Object REXX for
  5.   OS/2 and describes requirements and important information on using Object
  6.   REXX. Please read this document before installing Object REXX.
  7.  
  8.   The information covered in this document includes:
  9.  
  10.    -- ENHANCEMENTS TO OBJECT REXX
  11.    -- INSTRUCTIONS FOR INSTALLING OBJECT REXX ON OS/2
  12.        -- MATERIALS
  13.        -- DOCUMENTATION
  14.        -- SYSTEM REQUIREMENTS
  15.        -- INSTALLATION OF OBJECT REXX
  16.        -- SOLVING PROBLEMS USING OBJECT REXX
  17.    -- EXPLORING OBJECT REXX
  18.    -- SWITCHING REXX INTERPRETERS
  19.    -- NOTES ON RUNNING YOUR EXISTING REXX PROGRAMS
  20.    -- USING OBJECT REXX WITH THE OS/2 WORKPLACE SHELL
  21.    -- NOTES ON RUNNING OBJECT REXX WPS PROGRAMS
  22.    -- NOTES ON OPENDOC
  23.  
  24.  
  25. ENHANCEMENTS TO OBJECT REXX
  26.  
  27.   The following enhancements have been made to this Object REXX level:
  28.  
  29.     - Corrected several bugs:
  30.        * SysFileTree error when using the 'O' option
  31.        * Speed up processing of LINES() built-in function
  32.        * Stream Query Size returns wrong value for not existing files
  33.        * Memory problems with objects larger than 16 MB
  34.        * CHARS() built-in function returned -1 for certain files
  35.        * Memory leak when working with many files
  36.        * LINES() method and built-in function didn't recognize a single
  37.          character after CR/LF
  38.        * Line count wrong for files ending in CR-LF-EOF
  39.        * WPS support not persistent between reboots
  40.  
  41.  
  42. INSTRUCTIONS FOR INSTALLING OBJECT REXX ON OS/2
  43.  
  44. MATERIALS:
  45.  
  46.   This directory contains the materials needed to install Object REXX
  47.   on OS/2. No installation diskette images are provided with this level
  48.   of Object REXX.
  49.  
  50. DOCUMENTATION:
  51.  
  52.   REXXPG.INF
  53.      This on-line reference file is the latest Object REXX Programming
  54.      Guide for OS/2. This file contains information on how to use Object
  55.      REXX to develop object-oriented programs. To view this file, issue
  56.      the command 'VIEW REXXPG.INF' at an OS/2 command prompt.
  57.  
  58.   REXX.INF
  59.      This on-line reference file is the latest Object REXX Reference
  60.      information which describes Object REXX for OS/2. To view this file,
  61.      issue the command 'VIEW REXX.INF' at an OS/2 command prompt.
  62.  
  63.   SOMREQ.DOC
  64.      This text file discusses the requirements for building and using a
  65.      SOM class in Object REXX. This file is installed with the Object REXX
  66.      samples.
  67.  
  68.  
  69. SYSTEM REQUIREMENTS:
  70.  
  71.      (1) OS/2 WARP 3.0 or later (with REXX installed)
  72.  
  73.      (2) 2.8MB of hard disk space for the entire Object REXX package
  74.          which includes the following components (all components will
  75.          be installed automatically):
  76.  
  77.             - executables
  78.             - online documentation
  79.             - sample programs
  80.  
  81.      (3) IBM System Object Model (SOM) 2.1
  82.  
  83.          This level of Object REXX requires SOM 2.1. Make sure you have
  84.          the required level of SOM installed BEFORE installing Object REXX.
  85.  
  86.          If running OS/2 WARP 3.0, the SOM 2.1 runtime is already included,
  87.          so you do not need to install SOM 2.1.
  88.  
  89.          NOTE: If you are planning to create your own DSOM classes you have to
  90.                make sure that SOM is at least at fix level CSD211 since
  91.                earlier versions of SOM toolkits have a bug that will cause
  92.                Object REXX programs to trap if they access DSOM classes built
  93.                with a previous level of the SOM toolkit.
  94.  
  95.  
  96. INSTALLATION OF OBJECT REXX:
  97.  
  98.      The Object REXX install program will take you through the installation
  99.      of Object REXX for OS/2. If you have installed a previous version of
  100.      Object REXX you need to select the 'Delete and reinstall' option.
  101.  
  102.      Most of the files will be installed to your OS/2 directory for the
  103.      switching mechanism between classic REXX and Object REXX. You will only
  104.      be able to select the drive and directory for the Object REXX sample
  105.      files. The default directory used by the install program is 'C:\OREXX'.
  106.  
  107.      The installation process makes backup copies of your existing REXX files
  108.      and activates Object REXX for the next reboot of your system. If you
  109.      want to switch back to the classic REXX interpreter see the description
  110.      in chapter "SWITCHING REXX INTERPRETERS".
  111.  
  112.      NOTE: If you are installing this version of Object REXX on OS/2 WARP 4.0
  113.            it will overwrite the version of Object REXX included with it. If
  114.            you later decide to remove Object REXX from your system you will
  115.            not be able to restore the original Object REXX from OS/2 WARP 4.0.
  116.            Also this installation will not be supported by OS/2 WARP 4.0
  117.            FixPacks.
  118.  
  119.      (1) Run the Object REXX install program:
  120.  
  121.              'INSTALL'
  122.  
  123.          If you have installed a previous level of Object REXX, the install
  124.          program will allow you to delete the previous level and reinstall or
  125.          update the previous level of Object REXX you have installed. You
  126.          have to select the option 'Delete and reinstall' at this point. After
  127.          the current files have been deleted you will be asked to reboot your
  128.          system to activate the changes of the deletion. After the reboot you
  129.          will be able to install Object REXX by running the install program
  130.          again.
  131.  
  132.          If you encounter problems deleting the currently installed version
  133.          of Object REXX it may be related to the information Software Installer
  134.          remembers for installed products. A small utility is provided that
  135.          helps you removing the old information of Object REXX from the
  136.          Software Installer database. The utility is called ZAPINI.CMD and
  137.          must be called with the drive letter where the EPFIS.INI file is
  138.          located as the first parameter. Normally this would be the boot drive
  139.          of your system. If you have installed OS/2 on drive E: you would
  140.          invoke the utility with:
  141.  
  142.              'ZAPINI E:'
  143.  
  144.  
  145. SOLVING PROBLEMS USING OBJECT REXX
  146.  
  147.   If you encounter problems after installing Object REXX, here are some hints:
  148.  
  149.      (1) After running WPSINST.CMD you get an error popup with the message
  150.          'SYS2070 - A program encountered a problem and cannot continue'
  151.  
  152.          Please select the 'Display register information' radiobutton and
  153.          look at the additional information displayed. Most likely you will
  154.          see the message
  155.            'The system could not demand load the applications's segment. ...'
  156.  
  157.          This means that Object REXX is not installed as the default REXX on
  158.          your system. Please follow the steps described in "SWITCHING REXX
  159.          INTERPRETERS" below.
  160.  
  161.  
  162. EXPLORING OBJECT REXX
  163.  
  164.   Once you have installed the Object REXX files, you can immediately run
  165.   Object REXX programs.
  166.  
  167.      For example, you can run the REXXTRY program shipped with Object REXX.
  168.      Enter:
  169.  
  170.      'REXXTRY'
  171.  
  172.      Within REXXTRY, you can try out the new Object REXX syntax,
  173.      for instance:
  174.  
  175.        say .object                    /* displays 'The Object class'   */
  176.        myarray=.array~of(4,3,2,1)     /* creates a 4 element array     */
  177.        do i over myarray; say i; end  /* displays all 4 array elements */
  178.  
  179.      To help you explore programming in Object REXX, the following sample
  180.      source programs and class definitions are provided:
  181.  
  182.        - animal:   interacts with SOM class ANIMAL
  183.        - ccreply:  concurrent program using REPLY
  184.        - complex:  complex number class
  185.        - factor:   factorial program
  186.        - greply:   concurrent program using WAIT and NOWAIT
  187.        - guess:    a guessing game
  188.        - ktguard:  concurrent program using START and GUARD
  189.        - month:    displays days of the month of January
  190.        - pipe:     a pipeline implementation
  191.        - qdate:    date query program
  192.        - qtime:    time query program
  193.        - semcls:   semaphore class
  194.        - stack:    program which uses a stack class
  195.        - usecomp:  program which uses complex number class
  196.        - usepipe:  program which uses pipeline implementation
  197.  
  198.  
  199. SWITCHING REXX INTERPRETERS
  200.  
  201.   A small utility has been added to allow you to switch between the two
  202.   flavours of the REXX interpreters. After installation Object REXX will
  203.   be your system default REXX. If you want to switch back to classic REXX
  204.   or from classic REXX to Object REXX, enter the following on your OS/2
  205.   command prompt:
  206.  
  207.      'SWITCHRX'
  208.  
  209.   You will be prompted to confirm the switching mechanism. At this point
  210.   enter "Y" to proceed with the switching algorithm or any other value to
  211.   abort the operation. If you have confirmed the switching operation the
  212.   operation continues. In order to activate the changes you will have to
  213.   reboot the system.
  214.  
  215.   If you have installed WPS support for Object REXX it will be removed
  216.   when switching from Object REXX to classic REXX. After switching back
  217.   to Object REXX you have to activate WPS support again manually. See
  218.   section "USING OBJECT REXX WITH THE OS/2 WORKPLACE SHELL" below.
  219.  
  220.  
  221. NOTES ON RUNNING YOUR EXISTING REXX PROGRAMS:
  222.  
  223.  For the most part, any existing REXX programs you have should
  224.  work with Object REXX.  There are, however, some differences.
  225.  
  226.    - Some error codes have changed and some have been added.  Also,
  227.      for most errors you will now receive 2 error messages.  The
  228.      first should be similar (if not identical) to the message you
  229.      would have seen previously.  The second provides additional
  230.      and more detailed information.  So, for example, where you formerly
  231.      received "Invalid Call to Routine", you will now get further
  232.      information on what is wrong with the call.
  233.  
  234.    - Some errors are now detected earlier.  Formerly, REXX would wait
  235.      until it encountered an error during execution to report it
  236.      to you.  Now, some errors will be reported before the first
  237.      instruction in your REXX script is run.  In particular, syntax
  238.      errors which indicate your program is not well-formed REXX
  239.      (there is a missing END or an unmatched parenthesis, for example)
  240.      will be reported after you have invoked the program but before it
  241.      begins executing.  The REXXC utility can be used to perform only
  242.      the syntax checking.
  243.  
  244.    - The SEEK command used with the STREAM function will require an
  245.      option (READ, WRITE, etc) when used to set the position within
  246.      a stream that is opened for both reading and writing.
  247.  
  248.    - The parameters "//T" and "//t" used with a REXX program are the only
  249.      "//" parameters reserved by REXX. All other "//" parameters can now be
  250.      used with REXX programs.
  251.  
  252.  If you encounter problems running existing REXX programs you can always
  253.  switch back to the classic REXX interpreter. See chapter "SWITCHING REXX
  254.  INTERPRETERS" above.
  255.  
  256.  
  257. USING OBJECT REXX WITH THE OS/2 WORKPLACE SHELL
  258.  
  259.   OS/2 WARP 3.0 is required in order to use the WorkPlace Shell support.
  260.   If you would like to use Object REXX with WorkPlace Shell objects, you
  261.   need to first make sure you are running Object REXX as the default REXX
  262.   on your system (see "SWITCHING REXX INTERPRETERS" above).
  263.  
  264.   Then, follow these steps:
  265.  
  266.      (1) Run the Object REXX class install program which will register the
  267.          necessary WorkPlace Shell classes used with Object REXX.
  268.          Enter the following at the OS/2 command prompt:
  269.  
  270.              'WPSINST'
  271.  
  272.          The WPSINST.CMD program will register Object REXX classes with the
  273.          WorkPlace Shell. You can also use this program at any time to query
  274.          these Object REXX classes, and to register and deregister them.
  275.  
  276.          If at any time you need to back off using Object REXX with the OS/2
  277.          WorkPlace Shell, deregister the Object REXX classes by entering the
  278.          following command at the OS/2 command prompt:
  279.  
  280.              'WPSINST -'
  281.  
  282.      To help you use Object REXX with the OS/2 Workplace Shell, the following
  283.      sample source programs and class definitions are provided:
  284.  
  285.        - wpsorxcl: Workplace Shell example using OREXX classes
  286.        - wpsorxfl: Workplace Shell folder example
  287.  
  288.  
  289. NOTES ON RUNNING OBJECT REXX WPS PROGRAMS:
  290.  
  291.    - Section 'REXX and the Workplace Shell' in the online Object REXX
  292.      reference refers you to the OS/2 Technical Library for documentation
  293.      of the workplace classes and methods.  You can find this information
  294.      in the OS/2 WARP Toolkit provided as part of this volume of The
  295.      Developer Connection for OS/2.  See the following online books,
  296.      "Workplace Shell Programming Guide" (file WPSGUIDE.INF) and
  297.      "WorkPlace Shell Reference" (files WPS1.INF, WPS2.INF, and WPS3.INF)
  298.      for information on OS/2 Workplace Shell programming interfaces.
  299.  
  300.    - Use caution if you are deleting WPS objects (via wpDelete method).
  301.      Drop the WPS object variable after a wpDelete to ensure all references
  302.      have been removed.
  303.  
  304.    - Use of WPPort, WPPdr, WPQdr classes are currently not supported.
  305.  
  306.  
  307. NOTES ON OPENDOC:
  308.    This level of Object REXX is an updated level compared to the one shipped
  309.    with the OpenDoc Pack on DevCon 9 Special Edition. If you want to use the
  310.    updated version you have to make sure that the directories in LIBPATH,
  311.    PATH, DPATH and HELP pointing to the Object REXX interpreter included in
  312.    the OpenDoc Pack are removed from CONFIG.SYS.
  313.