IBM Object REXX for Windows Interpreter Edition Version 2.1.1 Update
README
This installation package updates an installed Object REXX for
Windows Interpreter 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 Interpreter Edition Version
2.1 must be installed. Download the ORXI211UZIP.EXE file, double-click
it from Windows Explorer, select a temporary target directory and
click Extract. Double-click on the extracted file ORXI211U.EXE and
follow the installation instructions.
Under certain circumstances the installation will terminate at the
beginning. If this happens, perform an "Administrative Install".
Start the ORXI211U.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
Don't 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
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").
will cause an invocation of VALUE with the given arguments. For
objects that have the name of any 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 the
possible parameters.
no parameter : Verify if 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 which 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.