Open Object Rexx™

Reference

Version 3.2.0 Edition

Revision 0

October 25, 2007

W. David Ashley
Rony G. Flatscher
Mark Hessling
Rick McGuire
Mark Miesfeld
Lee Peedin

Table of Contents
About This Book
Related Information
How to Read the Syntax Diagrams
A Note About Program Examples in this Document
Getting Help
The Rexx Language Association Mailing List
The Open Object Rexx SourceForge Site
comp.lang.rexx Newsgroup
1. Object Rexx General Concepts
What Is Object-Oriented Programming?
Modularizing Data
Modeling Objects
How Objects Interact
Methods
Polymorphism
Classes and Instances
Data Abstraction
Subclasses, Superclasses, and Inheritance
Structure and General Syntax
Characters
Comments
Tokens
Implied Semicolons
Continuations
Terms, Expressions, and Operators
Terms and Expressions
Operators
Parentheses and Operator Precedence
Message Terms
Message Sequences
Clauses and Instructions
Null Clauses
Directives
Labels
Instructions
Assignments
Commands
Assignments and Symbols
Extended Assignments
Constant Symbols
Simple Symbols
Stems
Compound Symbols
Environment Symbols
Message Instructions
Commands to External Environments
Environment
Commands
Using Rexx on Windows and Unix
2. Keyword Instructions
ADDRESS
ARG
CALL
DO
DROP
EXIT
EXPOSE
FORWARD
GUARD
IF
INTERPRET
ITERATE
LEAVE
LOOP
NOP
NUMERIC
PARSE
PROCEDURE
PULL
PUSH
QUEUE
RAISE
REPLY
RETURN
SAY
SELECT
SIGNAL
TRACE
Alphabetic Character (Word) Options
Prefix Option
Numeric Options
USE
3. Directives
::ATTRIBUTE
::CLASS
::METHOD
::REQUIRES
::ROUTINE
4. Objects and Classes
Types of Classes
Object Classes
Mixin Classes
Abstract Classes
Metaclasses
Creating and Using Classes and Methods
Using Classes
Scope
Defining Instance Methods with SETMETHOD or ENHANCED
Method Names
Default Search Order for Method Selection
Defining an UNKNOWN Method
Changing the Search Order for Methods
Public and Private Methods
Initialization
Object Destruction and Uninitialization
Required String Values
Concurrency
Overview of Classes Provided by Rexx
The Class Hierarchy
Cross-reference of Methods
5. The Builtin Classes
The Fundamental Classes
The Object Class
The Class Class
The String Class
The Method Class
The Message Class
The Stream Classes
The InputStream Class
The OutputStream Class
The InputOutputStream Class
The Stream Class
The Collection Classes
Organization of the Collection Classes
The Collection Class
The MapCollection Class
The OrderedCollection Class
The SetCollection Class
The Array Class
The Bag Class
The CircularQueue Class
The Directory Class
The List Class
The Properties Class
The Queue Class
The Relation Class
The Set Class
The Stem Class
The Table Class
Sorting Arrays
The Concept of Set Operations
The Utility Classes
The DateTime Class
The Alarm Class
The TimeSpan Class
The Comparable Class
The Comparator Class
The CaselessColumnComparator Class
The CaselessComparator Class
The ColumnComparator Class
The CaselessDescendingComparator Class
The DescendingComparator Class
The InvertingComparator Class
The Monitor Class
The MutableBuffer Class
The RegularExpression Class
The RexxQueue Class
The StreamSupplier Class
The Supplier Class
The Windows Specific Classes
The Windows MenuObject Class
The Windows OLEObject Class
The Windows OLEVariant Class
The WindowsClipboard Class
The WindowsEventLog Class
The WindowsManager Class
The WindowObject Class
The WindowsProgramManager Class
The WindowsRegistry Class
6. Rexx Runtime Objects
The Environment Directory (.ENVIRONMENT)
The ENDOFLINE Constant (.ENDOFLINE)
The FALSE Constant (.FALSE)
The NIL Object (.NIL)
The TRUE Constant (.TRUE)
The Local Directory (.LOCAL)
The Error Monitor (.ERROR)
The Input Monitor (.INPUT)
The Output Monitor (.OUTPUT)
The STDERR Stream (.STDERR)
The STDIN Stream (.STDIN)
The STDOUT Stream (.STDOUT)
The STDQUE Queue (.STDQUE)
The Line Number (.LINE)
The METHODS Directory (.METHODS)
The Return Status (.RS)
7. Functions
Syntax
Functions and Subroutines
Search Order
Errors during Execution
Return Values
Built-in Functions
ABBREV (Abbreviation)
ABS (Absolute Value)
ADDRESS
ARG (Argument)
B2X (Binary to Hexadecimal)
BEEP
BITAND (Bit by Bit AND)
BITOR (Bit by Bit OR)
BITXOR (Bit by Bit Exclusive OR)
C2D (Character to Decimal)
C2X (Character to Hexadecimal)
CENTER (or CENTRE)
CHANGESTR
CHARIN (Character Input)
CHAROUT (Character Output)
CHARS (Characters Remaining)
COMPARE
CONDITION
COPIES
COUNTSTR
D2C (Decimal to Character)
D2X (Decimal to Hexadecimal)
DATATYPE
DATE
DELSTR (Delete String)
DELWORD (Delete Word)
DIGITS
DIRECTORY
ENDLOCAL (Linux only)
ERRORTEXT
FILESPEC
FORM
FORMAT
FUZZ
INSERT
LASTPOS (Last Position)
LEFT
LENGTH
LINEIN (Line Input)
LINEOUT (Line Output)
LINES (Lines Remaining)
LOWER
MAX (Maximum)
MIN (Minimum)
OVERLAY
POS (Position)
QUEUED
RANDOM
REVERSE
RIGHT
RXFUNCADD
RXFUNCDROP
RXFUNCQUERY
RXQUEUE
SETLOCAL (Linux only)
SIGN
SOURCELINE
SPACE
STREAM
STRIP
SUBSTR (Substring)
SUBWORD
SYMBOL
TIME
TRACE
TRANSLATE
TRUNC (Truncate)
UPPER
USERID
VALUE
VAR
VERIFY
WORD
WORDINDEX
WORDLENGTH
WORDPOS (Word Position)
WORDS
X2B (Hexadecimal to Binary)
X2C (Hexadecimal to Character)
X2D (Hexadecimal to Decimal)
XRANGE (Hexadecimal Range)
8. Rexx Utilities (RexxUtil)
List of Rexx Utility Functions
RxMessageBox (Windows only)
RxWinExec (Windows only)
SysAddRexxMacro
SysBootDrive (Windows only)
SysClearRexxMacroSpace
SysCloseEventSem
SysCloseMutexSem
SysCls
SysCreateEventSem
SysCreateMutexSem
SysCreatePipe (AIX only)
SysCurPos (Windows only)
SysCurState (Windows only)
SysDriveInfo (Windows only)
SysDriveMap (Windows only)
SysDropFuncs
SysDropRexxMacro
SysDumpVariables
SysFileCopy (Windows only)
SysFileDelete
SysFileMove (Windows only)
SysFileSearch
SysFileSystemType (Windows only)
SysFileTree
SysFork (Linux, AIX, Solaris only)
SysFromUnicode (Windows only)
SysGetErrortext
SysGetFileDateTime
SysGetKey
SysGetMessage
SysGetMessageX (Unix only)
SysIni (Windows only)
SysIsFile
SysIsFileCompressed (Windows only)
SysIsFileDirectory
SysIsFileEncrypted (Windows only)
SysIsFileLink
SysIsFileNotContentIndexed (Windows only)
SysIsFileOffline (Windows only)
SysIsFileSparse (Windows only)
SysIsFileTemporary (Windows only)
SysLoadFuncs
SysLoadRexxMacroSpace
SysMkDir
SysOpenEventSem
SysOpenMutexSem
SysPostEventSem
SysPulseEventSem (Windows only)
SysQueryProcess
SysQueryRexxMacro
SysReleaseMutexSem
SysReorderRexxMacro
SysRequestMutexSem
SysResetEventSem
SysRmDir
SysSaveRexxMacroSpace
SysSearchPath
SysSetFileDateTime
SysSetPriority
SysShutdownSystem (Windows only)
SysSleep
SysStemCopy
SysStemDelete
SysStemInsert
SysStemSort
SysSwitchSession (Windows only)
SysSystemDirectory (Windows only)
SysTempFileName
SysTextScreenRead (Windows only)
SysTextScreenSize (Windows only)
SysToUnicode (Windows only)
SysUtilVersion
SysVersion
SysWait (AIX only)
SysWaitEventSem
SysWaitNamedPipe (Windows only)
SysWinDecryptFile (Windows only)
SysWinEncryptFile (Windows only)
SysWinGetDefaultPrinter (Windows only)
SysWinGetPrinters (Windows only)
SysWinSetDefaultPrinter (Windows only)
SysWinVer Windows only)
9. Parsing
Simple Templates for Parsing into Words
Message Term Assignments
The Period as a Placeholder
Templates Containing String Patterns
Templates Containing Positional (Numeric) Patterns
Combining Patterns and Parsing into Words
Parsing with Variable Patterns
Using UPPER, LOWER, and CASELESS
Parsing Instructions Summary
Parsing Instructions Examples
Advanced Topics in Parsing
Parsing Several Strings
Combining String and Positional Patterns
Conceptual Overview of Parsing
10. Numbers and Arithmetic
Precision
Arithmetic Operators
Power
Integer Division
Remainder
Operator Examples
Exponential Notation
Numeric Comparisons
Limits and Errors when Rexx Uses Numbers Directly
11. Conditions and Condition Traps
Action Taken when a Condition Is Not Trapped
Action Taken when a Condition Is Trapped
Condition Information
Descriptive Strings
Additional Object Information
The Special Variable RC
The Special Variable SIGL
Condition Objects
12. Concurrency
Early Reply
Message Objects
Default Concurrency
Sending Messages within an Activity
Using Additional Concurrency Mechanisms
SETUNGUARDED Method and UNGUARDED Option
GUARD ON and GUARD OFF
Guarded Methods
Additional Examples
13. The Security Manager
Calls to the Security Manager
Example
14. Input and Output Streams
The Input and Output Model
Input Streams
Output Streams
External Data Queue
Default Stream Names
Line versus Character Positioning
Implementation
Operating System Specifics
Examples of Input and Output
Errors during Input and Output
Summary of Rexx I/O Instructions and Methods
15. Debugging Aids
Interactive Debugging of Programs
Debugging Aids
RXTRACE Variable
16. Reserved Keywords
17. Special Variables
18. Useful Services
Windows Commands
Linux Commands
Subcommand Handler Services
The RXSUBCOM Command
The RXQUEUE Filter
Distributing Programs without Source
19. Windows Scripting Host Engine
Object Rexx as a Windows Scripting Host Engine
Windows Scripting Host Overview
Scripting in the Windows Style
Invocation by the Browser
WSH File Types and Formats
Invocation from a Command Prompt
Invocation as a COM Object
WSH Samples
Interpretation of and Deviation from the WSH Specification
Windows Scripting Host (WSH) Advanced Overview
Object Rexx in the WSH Environment
Properties
The Object Rexx "Sandbox"
Features Duplicated in Object Rexx and WSH
A. Using DO and LOOP
Simple DO Group
Repetitive Loops
Simple Repetitive Loops
Controlled Repetitive Loops
Repetitive Loops over Collections
Conditional Phrases (WHILE and UNTIL)
LABEL Phrase
Conceptual Model of Loops
B. Migration
Error Codes and Return Codes
Error Detection and Reporting
Environment Variables
Stems versus Collections
Input and Output Using Functions and Methods
.Environment
Deleting Environment Variables
Queuing
Trace in Macrospace
The RxMessageBox Function
C. Error Numbers and Messages
Error List
Error 3 - Failure during initialization
Error 4 - Program interrupted
Error 5 - System resources exhausted
Error 6 - Unmatched "/*" or quote
Error 7 - WHEN or OTHERWISE expected
Error 8 - Unexpected THEN or ELSE
Error 9 - Unexpected WHEN or OTHERWISE
Error 10 - Unexpected or unmatched END
Error 11 - Control stack full
Error 13 - Invalid character in program
Error 14 - Incomplete DO/SELECT/IF
Error 15 - Invalid hexadecimal or binary string
Error 16 - Label not found
Error 17 - Unexpected PROCEDURE
Error 18 - THEN expected
Error 19 - String or symbol expected
Error 20 - Symbol expected
Error 21 - Invalid data on end of clause
Error 22 - Invalid character string
Error 23 - Invalid data string
Error 24 - Invalid TRACE request
Error 25 - Invalid subkeyword found
Error 26 - Invalid whole number
Error 27 - Invalid DO syntax
Error 28 - Invalid LEAVE or ITERATE
Error 29 - Environment name too long
Error 30 - Name or string too long
Error 31 - Name starts with number or "."
Error 33 - Invalid expression result
Error 34 - Logical value not 0 or 1
Error 35 - Invalid expression
Error 36 - Unmatched "(" or "[" in expression
Error 37 - Unexpected ",", ")", or "]"
Error 38 - Invalid template or pattern
Error 39 - Evaluation stack overflow
Error 40 - Incorrect call to routine
Error 41 - Bad arithmetic conversion
Error 42 - Arithmetic overflow/underflow
Error 43 - Routine not found
Error 44 - Function or message did not return data
Error 45 - No data specified on function RETURN
Error 46 - Invalid variable reference
Error 47 - Unexpected label
Error 48 - Failure in system service
Error 49 - Interpretation error
Error 88 - Invalid argument
Error 89 - Variable or message term expected
Error 90 - External name not found
Error 91 - No result object
Error 92 - OLE error
Error 93 - Incorrect call to method
Error 97 - Object method not found
Error 98 - Execution error
Error 99 - Translation error
RXSUBCOM Utility Program
Error 116 - The RXSUBCOM parameter REGISTER is incorrect.
Error 117 - The RXSUBCOM parameter DROP is incorrect.
Error 118 - The RXSUBCOM parameter LOAD is incorrect.
Error 125 - The RXSUBCOM parameter QUERY is incorrect.
RXQUEUE Utility Program
Error 119 - The REXX queuing system is not initialized.
Error 120 - The size of the data is incorrect.
Error 121 - Storage for data queues is exhausted.
Error 122 - The name %1 is not a valid queue name.
Error 123 - The queue access mode is not correct.
Error 124 - The queue %1 does not exist.
Error 131 - The syntax of the command is incorrect
Error 132 - System error occurred while processing the command
RexxC Utility Program
Error 127 - The REXXC command parameters are incorrect.
Error 128 - Output file name must be different from input file name.
Error 129 - SYNTAX: REXXC InProgramName [OutProgramName] [/S]
Error 130 - Without OutProgramName REXXC only performs a syntax check
D. Notices
Trademarks
Source Code For This Document
E. Common Public License Version 1.0
Definitions
Grant of Rights
Requirements
Commercial Distribution
No Warranty
Disclaimer of Liability
General
Index
List of Tables
4-1. Summary of Methods and the Classes Defining Them
5-1. Stem Information
5-2. Stem Information
5-3. OLE/Rexx Types
5-4. Methods Available to the WindowsProgramManager Class
5-5. Symbolic Names for Virtual Keys
8-1. Rexx Utility Library Functions
9-1. Parsing Source Strings
10-1. Whole Number Limits
List of Figures
1-1. Modular Data--a Report Object
1-2. A Ball Object
1-3. Ball Object with Variable Names and Values
1-4. Encapsulated 5 Object
1-5. A Simple Class
1-6. Icon Class
1-7. Instances of the Icon Class
1-8. Superclass and Subclasses
1-9. The Screen-Object Superclass
1-10. Multiple Inheritance
4-1. Classes and Inheritance (part 1 of 7)
4-2. Classes and Inheritance (part 2 of 7)
4-3. Classes and Inheritance (part 3 of 7)
4-4. Classes and Inheritance (part 4 of 7)
4-5. Classes and Inheritance (part 5 of 7)
4-6. Classes and Inheritance (part 6 of 7)
4-7. Classes and Inheritance (part 7 of 7)
5-1. The Object class and methods
5-2. The Class class and methods
5-3. The String class and methods
5-4. The Method class and methods
5-5. The Message class and methods
5-6. The InputStream class and methods
5-7. The OutputStream class and methods
5-8. The InputOutputStream class
5-9. The Stream class and methods
5-10. The Collection Class
5-11. The MapCollection class
5-12. The OrderedCollection class
5-13. The SetCollection class
5-14. The Array class and methods
5-15. The Bag class and methods
5-16. The CircularQueue class and methods
5-17. The Directory class and methods
5-18. The List class and methods
5-19. The Properties class and methods
5-20. The Queue class and methods
5-21. The Relation class and methods
5-22. The Set class and methods
5-23. The Stem class and methods
5-24. The Table class and methods
5-25. The DateTime class and methods
5-26. The Alarm class and methods
5-27. The TimeSpan class and methods
5-28. The Comparable class and methods
5-29. The Comparator class and methods
5-30. The CaselessColumnComparator class and methods
5-31. The CaselessComparator class and methods
5-32. The ColumnComparator class and methods
5-33. The CaselessDescendingComparator class and methods
5-34. The DescendingComparator class and methods
5-35. The InvertingComparator class and methods
5-36. The Monitor class and methods
5-37. The MutableBuffer class and methods
5-38. The RegularExpression class and methods
5-39. The RexxQueue class and methods
5-40. The StreamSupplier class and methods
5-41. The Supplier class and methods
7-1. Function and Routine Resolution and Execution
9-1. Conceptual Overview of Parsing
9-2. Conceptual View of Finding Next Pattern
9-3. Conceptual View of Word Parsing
12-1. Early Reply
12-2. Before REPLY
12-3. After REPLY
12-4. Indirect Object Recursion
12-5. Example of a Rexx Semaphore Class
13-1. Agent Program
13-2. Example of Server Implementing Security Manager
14-1. Sample Rexx Procedure Using a Queue
A-1. Concept of a Loop
A-2. Concept of Repetitive Loop over Collection