IBM Object REXX for Windows Development Edition Version 2.1.1 Update
README

This installation package updates an installed Object REXX for Windows 
Development Edition Version 2.1 to Version 2.1.1. For additional 
information please refer to the README file for version 2.1.

CONTENTS

1.0 INSTALLATION
1.1 Running Installation Silently
2.0 CHANGES SINCE VERSION 2.1
2.1 New features
2.1.1 New RegularExpressions Class
2.1.2 Additions to the REXXUTIL function package
2.1.3 Windows Script Host (WSH) extensions
2.1.4 Support for Microsoft Internet Explorer Security Manager
2.1.5 RXAPI.EXE as a service
2.1.6 Utility to terminate REXX
2.1.7 REXXRT to pre-2.1 format
2.1.8 New method for WindowsProgramManager class
2.1.9 MakeArray method for String Class
2.1.10 MakeArray method for WindowsClipboard Class
2.1.11 Modified NEW method of method class
2.1.12 Modified SETMETHOD method of Object Class
3.0 SUPPORT AND ADDITIONAL INFORMATION
4.0 NOTICES
4.1 Trademarks and service marks


1.0 INSTALLATION

To install this update, the Object REXX Development Edition Version 
2.1 must be installed. Download the ORXD211UZIP.EXE file, double-click 
it from the Windows Explorer, select a temporary target directory 
and click Extract. Double-click the extracted file ORXD211U.EXE and 
follow the installation instructions.

The Object REXX Runtime Update is available as a separate package. 
It includes the SETUPRT.EXE file and the files from the REDIST 
directory. 

Under certain circumstances the installation might terminate at the 
beginning. If this happens, perform an "Administrative Install". 
Start the ORXD211U.EXE with parameter /A. This unpacks the "IBM 
Object REXX for Windows ....2.1.1.msi" and some other files to the 
selected directory. Change to this directory and select the ".msi" 
file with the right mouse button and select Install.

Another problem might occur, if an older version of the Microsoft 
Software Installer is installed on the target system. If this happens, 
download and install the newest version from the Microsoft internet 
site:

http://www.microsoft.com/downloads/


1.1 Running Installation Silently

These are the possible arguments for the installation routine. Note 
that all parameters are case sensitive.

/S
Do not display the SETUP.EXE progress bar.

/V 
Parameters immediately following this flag are passed to the 
installation program. If more than one argument is used, all arguments
must be enclosed within quotation marks. If quotation marks are used 
inside this quotation marks, they must preceded with an \ (for example, 
\"firstArgument secondArgument\" )

/QN
Run Microsoft Software Installer in silent mode also.

/S /V/QN
Run silent installation.

INSTALLDIR=
Specifies the installation drive and directory. If the path includes 
blanks, it must be enclosed within quotation marks.

SETUP /S /V"/QN INSTALLDIR=\"c:\My Programs\ObjREXX\""
Installs all Object REXX features in the directory 
c:\My Programs\ObjREXX\

ADDLOCAL=
Specifies the features to be installed, separated by commas.
Available features:
	ApplicationFiles
	SocketAndFTPFiles
        OODialogFiles

SETUP /S /V"/QN INSTALLDIR=c:\ObjREXX\ ADDLOCAL=ApplicationFiles"
Installs the Object REXX application files only, in the directory 
c:\objrexx\

ALLUSERS=
Specifies whether Object REXX should be installed for all or the 
current user only. If set to 1, Object REXX is installed for all 
users. If omitted, it is installed for the current user.

SETUP /S /V"/QN INSTALLDIR=c:\ObjREXX\ ADDLOCAL=ApplicationFiles ALLUSERS=1"
Installs the Object REXX application files only, in the directory 
c:\objrexx\, for all users.


2.0 CHANGES SINCE VERSION 2.1

This version provides improved processing speed for stem operations 
and several new and improved features.


2.1 New features


2.1.1 New RegularExpressions Class

This class provides support for regular expressions. A regular
expression is a pattern you can use to match strings against.

Here is a description of the syntax:

|    OR operator between the left and right expression
?    Matches any single character
*    Matches the previous expression zero or more times
+    Matches the previous expression one or more times
\    "Escape" symbol: use the next character literally
()   Expression in parenthesis (use where needed)
{n}  Matches previous expression n times (n>1)
[]   Set definition: matches any single character out of the defined
     set.
     A '^' right after the opening bracket means that none of the
     following characters should be matched.
     A '-' (if not used with '\') defines a range between the last
     specified character and the one following '-'. If it is the
     first character in the set definition, it is used literally.

The following symbolic names (all starting and ending with ':') can
be used to abbreviate common sets:

:ALPHA:        Characters in the range A-Z and a-z
:LOWER:        Characters in the range a-z
:UPPER:        Characters in the range A-Z
:DIGIT:        Characters in the range 0-9
:ALNUM:        Characters in :DIGIT: and :ALPHA:
:XDIGIT:       Characters in :DIGIT:, A-F and a-f
:BLANK:        Space and tab characters
:SPACE:        Characters '09'x to '0D'x and space
:CNTRL:        Characters '00'x to '1F'x and '7F'x
:PRINT:        Characters in the range '20'x to '7E'x
:GRAPH:        Characters in :PRINT: without space
:PUNCT:        All :PRINT: characters without space and not
               in :ALNUM:


Examples:

     "(Hi|Hello) World"      Matches "Hi World" and
                             "Hello World".
     "file.???"              Matches any file with three
                             characters after '.'
     "file.?{3}"             Same as above.
     "a *b"                  Matches all strings that begin with
                             'a' and end with 'b' and have an
                             arbitrary number of spaces in between
                             both.
     "a +b"                  Same as above, but at least one space
                             must be present.
     "file.[bd]at"           Matches "file.bat" and "file.dat".
     "[A-Za-z]+"             Matches any string containing only
                             letters.
     "[:ALPHA:]+"            Same as above, using symbolic names.
     "[^0-9]*"               Matches any string containing no
                             numbers, including the empty string.
     "[:DIGIT::LOWER:]"      A single character, either a digit or
                             a lower case character.
     "This is (very )+nice." Matches all strings with one or more
                             occurrences of "very " between
                             "This is " and "nice.".

The RegularExpression class is not a built-in class. It is defined
in the RXREGEXP.CLS file. This means, you must use a
::requires statement to activate its functionality, as follows:

::requires "RXREGEXP.CLS"


Methods available to the RegularExpression class:

Init
Match
Parse
Pos
Position


Init

                     +-,-"MAXIMAL"--+
>>-Init(-+---------+-+--------------+-)--------------------><
         '-Pattern-' +-,-"MINIMAL"--+

Instantiates a RegularExpression object. The optional parameter
'Pattern' lets you define a pattern that will be used to match
strings. See the introductory text below for a description of the
syntax. If the strings match, you can decide wether you want
"greedy" matching (a maximum-length match) or "non-greedy"
matching (a minimum-length match).

Examples:

     myRE1 = .RegularExpression~new
     myRE2 = .RegularExpression~new("Hello?*")


Match

>>-Match(-String-)-><

This method tries to match the given string to the regular
expression that was defined on the "new" invocation or on the
"parse" invocation. It returns 0 on an unsuccessful match and 1
on a successful match. For an example see "Parse".



Parse

                  +-,-"CURRENT"--+
>>-Parse(-Pattern-+--------------+-------------------------><
                  +-,-"MAXIMAL"--+
                  +-,-"MINIMAL"--+

This method creates the automation used to match a string from the
regular expression specified with 'Pattern'. The RegularExpression
object uses this regular expression until a new invocation of Parse
takes place. The second (optional) parameter specifies whether to
use minimal or maximal matching. The default is to use the current
matching behaviour.

Return values:

0    Regular expression was parsed successfully.
1    An unexpected symbol was met during parsing.
2    A missing ')' was found.
3    An illegal set was defined.
4    The regular expression ended unexpectedly.
5    An illegal number was specified.


Example 1:

     a.0 = "does not match regular expression"
     a.1 = "matches regular expression"
     b = .array~of("This is a nice flower.",
                   "This is a yellow flower.",,
                   "This is a blue flower.",
                   "Hi there!")

     myRE = .RegularExpression~new
     e = myRE~parse("This is a ???? flower.")
     if e == 0 then do
       do i over b
         j = myRE~match(i)
         say i~left(24) ">>" a.j
       end
     end
     else
       say "Error" e "occured!"
     exit

     ::requires "rxregexp.cls"

Output:

This is a nice flower.   >> Does match regular expression
This is a yellow flower. >> Does not match regular expression
This is a blue flower.   >> Does match regular expression
Hi there!                >> Does not match regular expression

Example 2:

     a.0 = "an invalid number!"
     a.1 = "a valid number."
     b = .array~of("1","42","0","5436412","1a","f43g")
     myRE = .RegularExpression~new("[1-9][0-9]*")
     do i over b
       j = myRE~match(i)
       say i "is" a.j
     end
     say

     /* Now allow "hex" numbers and a single 0 */
     if myRE~parse("0|([1-9a-f][0-9a-f]*)") == 0 then do
       do i over b
         j = myRE~match(i)
         say i "is" a.j
       end
     end
     else
       say "invalid regular expression!"

     exit

     ::requires "rxregexp.cls"

Example 3:

     str = "<p>Paragraph 1</p><p>Paragraph 2</p>"
     myRE1 = .RegularExpression~new("<p>?*</p>","MINIMAL")
     myRE1~match(str)
     myRE2 = .RegularExpression~new("<p>?*</p>","MAXIMAL")
     myRE2~match(str)

     say "myRE1 (minimal) matched" str~substr(1,myRE1~position)
     say "myRE2 (maximal) matched" str~substr(1,myRE2~position)

     ::requires "rxregexp.cls"

Output:

myRE1 (minimal) matched <p>Paragraph 1</p>
myRE2 (maximal) matched <p>Paragraph 1</p><p>Paragraph 2</p>



Pos

>>-Pos-(-Haystack-)-><

This method tries to locate a string defined by the regular
expression on the "new" invocation or on the "parse" invocation
in the given haystack string.
It returns 0 on an unsuccessful match or the starting position
on a successful match. The end position of the match can be
retrieved with the POSITION method.

Example:

     str = "It is the year 2002!"
     myRE = .RegularExpression~new("[1-9][0-9]*")
     begin = myRE~pos(str)
     if begin > 0 then do
       year = str~substr(begin, myRE~position - begin + 1)
       say "Found the number" year "in this sentence."
     end

     ::requires "rxregexp.cls"

Output:

Found the number 2002 in this sentence.



Position

>>-Position------------------------------------------------><

Returns the character position at which either Parse, Pos or Match
ended, depending on what was invoked last.

Example:

     myRE = .RegularExpression~new
     myRE~Parse("[abc")                    -- illegal set definition
     say myRE~Position                     -- will be 4

     myRE = .RegularExpression~new("[abc]12")
     myRE~Match("c12")
     say myRE~Position                     -- will be 3

     myRE~Match("a13")
     say myRE~Position                     -- will be 2 (failure to match)

     ::requires "rxregexp.cls"

2.1.2 Additions to the REXXUTIL function package

Printer access functions

There are three new functions in the REXXUTIL function package for 
Windows:

SysWinGetPrinters       - get a list of available printers
SysWinGetDefaultPrinter - get default printer
SysWinSetDefaultPrinter - set default printer


SysWinGetPrinters

>>--SysWinGetPrinters(stem.)--------><

Fills a stem with the available printer descriptions.

stem.0 - number of entries
stem.i - entry

Each entry is of the form "Printername, Drivername, Portname".

Returns:

0 - Success
1 - Failure


SysWinGetDefaultPrinter

>>--SysWinGetDefaultPrinter-------><

Returns the current default printer in the form 
"Printername,Drivername,Portname".


SysWinSetDefaultPrinter

>>--SysWinSetDefaultPrinter(description)----><

Sets the default printer. The description must have the form 
"Printername,Drivername,Portname".

Returns:

0        - Success
non-zero - System error codes. Use SysGetErrorText() to get a 
           description of the error.


Sample program:

     /* set default printer */

     default = SysWinGetDefaultPrinter()
     parse var default default",".

     if SysWinGetPrinters(list.) == 0 then do
       say "List of available printers (* = default):"
       do i=1 to list.0
         parse var list.i pname",".
         if pname == default then
           say i list.i "*"
         else
           say i list.i
       end
       say
       say "Please enter number of new default printer (0 = keep default)"
       pull i
       if i > 0 then call SysWinSetDefaultPrinter(list.i)
     end

     exit


2.1.3 Windows Script Host (WSH) extensions

A selector called "WSHENGINE" was added to the VALUE function 
when a REXX script is run in a WSH scripting context (running via 
cscript, wscript or as embedded code in HTML for the Microsoft 
Internet Explorer). The only currently supported value is 
"NAMEDITEMS". Calling VALUE with these parameters returns an array 
with the names of the named items that were added at script start.

Example: 	

     myArray = VALUE("NAMEDITEMS",,"WSHENGINE")

The value NAMEDITEMS is read-only, writing to it is prohibited.


Object REXX scripts running via the scripting engine (in WSH 
context) can now call the default method of an object as a function 
call with the object name.

Example: 

The SESSION object of ASP (Active Server Pages) has the default 
method VALUE. The usual (and recommended) way of using the SESSION 
object would be to use 

SESSION~VALUE("key","value").

Because VALUE is the default method, a function call 

SESSION("key","value")
SESSION~VALUE("key","value"). 

causes cause an invocation of VALUE with the given arguments. For 
objects that have the name of a REXX function, an explicit call to 
the default method must be made, because REXX functions have priority 
over this implicit method invocation mechanism.


2.1.4 Support for Microsoft Internet Explorer Security Manager

Support for Microsoft Internet Explorer Security Manager was 
implemented, removing the warning message that popped up when Object 
REXX was embedded in HTML.


2.1.5 RXAPI.EXE as a service

The RXAPI.EXE normally runs in the background as a WIN32 application 
without a window. It has no user interactions.

To run it as a service, it must be registered/deregistered with the 
service manager. The RXAPI.EXE now supports the following parameters:

/i 			: Install and register RXAPI.EXE as service, 
                          but do not start the service.
/u 			: Deinstall and deregister RXAPI.EXE as 
                          service.
/v			: Show the version number and whether it is 
                          registered as service.
any other parameter 	: Gives a short help message about possible 
                          parameters.
no parameter 		: Verify if it is registered as a service, 
                          and start as service or regularly.

If started with a parameter, the action and the result are shown in 
a message box. After registration, the RXAPI.EXE can be started as a 
service using the Windows Services dialog box.


2.1.6 Utility to terminate REXX

The REXXTERMINATE.EXE utility can be used to terminate REXX.EXE and 
RXAPI.EXE. Use it carefully because any running REXX script may hang 
immediately!


2.1.7 REXXRT to pre-2.1 format

The re-tokenizer now allows to convert to pre-2.1 format as well.

Usage: rexxrt [/1|/2] oldfile newfile

options: /1 tokenize to pre-2.1 format
         /2 tokenize to 2.1 format (default)


2.1.8 New method for WindowsProgramManager class
 
                                +-"PERSONAL"-+
DeleteDesktopIcon--(--name--,---+------------+-)
                                +-"COMMON"---+

Deletes a shortcut from the Windows desktop that was previously 
created with AddDesktopIcon.

The arguments are: 
 
name 	: The name of the shortcut to be deleted.

location: Either of the following locations: 
 
          "PERSONAL" 

          The shortcut was previously created with AddDektopIcon 
          and the location option "PERSONAL". This is the default.

          "COMMON" 

          The shortcut was previously created with AddDektopIcon 
          and the location option "COMMON".
 
Return codes:  

0  Shortcut deleted successfully. 
2  Shortcut not found. 
3  Path to shortcut not found.
5  Access denied or busy. 
26 Not a DOS disk. 
32 Sharing violation. 
36 Sharing buffer exceeded. 
87 Does not exist. 
206 Shortcut name exceeds range error.

Note: Return code 2 is also returned when a "PERSONAL" should be 
      deleted that was previously created with "COMMON" and vice 
      versa.
      

Example:

     pm = .WindowsProgramManager~new                                              
     if pm~InitCode \= 0 then exit                                                
                                                                             
     rc = pm~DeleteDesktopIcon("MyNotepad1","%SystemRoot%\system32\notepad.exe")   
     if rc \= 0 then do                                                           
       say "Error deleting shortcut: My Notepad 1"                                
       exit                                                                       
     end                                                                          
                                                                             
     exit                                                                         
                                                                             
     ::requires "winsystm.cls"      


2.1.9 MakeArray method for String Class

>>-MAKEARRAY(-+-----------+-)----><
              '-Separator-'

This method returns an array of strings containing the single 
lines that were separated using the separator character. The 
default separator is the newline character.

Example:

     nl = '0d0a'x
     string = "hello"nl"world"nl"this is an array."
     array = string~makearray
     say "the second line is:" array[2]

     string = "hello*world*this is an array."
     array = string~makearray('*')
     say "the third line is:" array[3]	


2.1.10 MakeArray method for WindowsClipboard Class

>>-MAKEARRAY------><

If the content of the clipboard is a string with newline characters 
in it, makeArray can be used to split up the string into individual 
lines. An array is returned containing those lines.


2.1.11 Modified NEW method of method class

 Another parameter was added to the NEW method of the Method class:

>>-NEW(name,source--+-----------------+-----------><
                    +--,methodobject--+

The third parameter influences the scope of the method. If none is 
given, the program scope is used. If another method object is given, 
its scope is used.


2.1.12 Modified SETMETHOD method of Object Class

A third parameter was added to the SETMETHOD method of the Object class:

                                      +-"FLOAT"--+
>>-SETMETHOD(methodname-+----,----+-,-+----------+--)------><
                        '-,method-'   '-"OBJECT"-'

This parameter describes if the method that is attached to an 
object should have object or float scope. "Float" scope means that 
it shares the same scope with methods that were defined outside of 
a class. "Object" scope means it shares the scope with other, 
potentially statically defined, methods of the object it is 
attached to.


3.0 SUPPORT AND ADDITIONAL INFORMATION

You can report any problems relating to IBM Object REXX via the 
Internet page

http://www.ibm.com/software/ad/obj-rexx/support.html

See the Object REXX home page 

http://www.ibm.com/software/ad/obj-rexx/

for information about news, features, function packages, tutorials, 
books, and so on.


4.0 NOTICES

This information was developed for products and services offered 
in the U.S.A. IBM may not offer the products,services, or features 
discussed in this document in other countries. Consult your local 
IBM representative for information on the products and services 
currently available in your area. Any reference to an IBM product, 
program, or service is not intended to state or imply that only 
that IBM product, program, or service may be used. Any functionally 
equivalent product, program, or service that does not infringe any 
IBM intellectual property right may be used instead. However, it is 
the user's responsibility to evaluate and verify the operation of 
any non-IBM product, program, or service. 

IBM may have patents or pending patent applications covering subject 
matter described in this document. The furnishing of this document 
does not give you any license to these patents. You can send license 
inquiries, in writing, to: 
  IBM Director of Licensing
  IBM Corporation
  North Castle Drive
  Armonk, NY 10504-1785
  U.S.A.

For license inquiries regarding double-byte (DBCS) information, 
contact the IBM Intellectual Property Department in your country 
or send inquiries, in writing, to: 
  IBM World Trade Asia Corporation
  Licensing
  2-31 Roppongi 3-chome, Minato-ku
  Tokyo 106, Japan

The following paragraph does not apply to the United Kingdom or any 
other country where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION 
"AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, 
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, 
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not 
allow disclaimer of express orimplied warranties in certain transactions, 
therefore, this statement may not apply to you. 

This information could include technical inaccuracies or 
typographical errors. Changes are periodically made to the information 
herein; these changes will be incorporated in new editions of the 
publication. IBM may make improvements and/or changes in the product(s) 
and/or the program(s) described in this publication at any time without 
notice. 

Licensees of this program who wish to have information about it for 
the purpose of enabling: (i) the exchange of information between 
independently created programs and other programs (including this one) 
and (ii) the mutual use of the information which has been exchanged, 
should contact: 

  IBM Deutschland
  Informationssysteme GmbH
  Department 3982
  Pascalstrasse 100
  70569 Stuttgart
  Germany

Such information may be available, subject to appropriate terms and 
conditions, including in some cases, payment of a fee.

The licensed program described in this document and all licensed 
material available for it are provided by IBM under terms of the 
IBM Customer Agreement, IBM International Program License Agreement 
or any equivalent agreement between us.

COPYRIGHT LICENSE: 

This information contains sample application programs in source 
language, which illustrates programming techniques on various 
operating platforms. You may copy, modify, and distribute these 
sample programs in any form without payment to IBM, for the purposes 
of developing, using, marketing or distributing application programs 
conforming to the application programming interface for the operating 
platform for which the sample programs are written. These examples 
have not been thoroughly tested under all conditions. IBM, therefore, 
cannot guarantee or imply reliability, serviceability, or function of 
these programs. You may copy, modify, and distribute these sample 
programs in any form without payment to IBM for the purposes of 
developing, using, marketing, or distributing application programs 
conforming to IBM's application programming interfaces. 


4.1 Trademarks and service marks

Microsoft, Windows, Windows NT, and the Windows logo are trademarks 
of Microsoft Corporation in the United States, other countries, or both.