Open Object Rexx
Next

ooRexx Documentation 5.3.0

Open Object Rexx

Reference

Edition 2026.08.03 (last revised on 2026-07-14 with r13178)

W. David Ashley

Josep Maria Blasco

Rony G. Flatscher

Mark Hessling

Rick McGuire

Lee Peedin

Oliver Sims

Erich Steinböck

Jon Wolfers

Legal Notice

Copyright © 2005-2026 Rexx Language Association. All rights reserved.

Portions Copyright © 1995, 2004 IBM Corporation and others. All rights reserved.

This documentation and accompanying materials are made available under the terms of the Common Public License v1.0 which accompanies this distribution. A copy is also available as an appendix to this document and at the following address: https://www.oorexx.org/license.html.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

Neither the name of Rexx Language Association nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

1. Document Conventions

1.1. Typographic Conventions
1.2. Notes and Warnings

2. How to Read the Syntax Diagrams

3. Getting Help and Submitting Feedback

3.1. The Open Object Rexx SourceForge Site
3.2. The Rexx Language Association Mailing List

4. Related Information

1. Open Object Rexx General Concepts

1.1. What Is Object-Oriented Programming?

1.2. Modularizing Data

1.3. Modeling Objects

1.4. How Objects Interact

1.5. Methods

1.6. Data Abstraction

1.7. Classes and Instances

1.8. Polymorphism

1.9. Subclasses, Superclasses, and Inheritance

1.10. Structure and General Syntax

1.10.1. Characters
1.10.2. Whitespace
1.10.3. Comments
1.10.4. Tokens
1.10.5. Implied Semicolons
1.10.6. Continuations

1.11. Terms, Expressions, and Operators

1.11.1. Terms and Expressions
1.11.2. Operators
1.11.3. Parentheses and Operator Precedence
1.11.4. Message Terms
1.11.5. Message Sequences
1.11.6. Array Term
1.11.7. Variable Reference Term

1.12. Clauses and Instructions

1.12.1. Null Clauses
1.12.2. Directives
1.12.3. Labels
1.12.4. Instructions
1.12.5. Assignments
1.12.6. Message Instructions
1.12.7. Keyword Instructions
1.12.8. Commands

1.13. Assignments and Symbols

1.13.1. Extended Assignments
1.13.2. Constant Symbols
1.13.3. Simple Symbols
1.13.4. Stems
1.13.5. Compound Symbols
1.13.6. Environment Symbols

1.14. Namespaces

1.15. Message Instructions

1.16. Commands to External Environments

1.16.1. Environment
1.16.2. Commands

1.17. Using Rexx on Windows and Unix-like systems

1.17.1. Calling other Rexx scripts
1.17.2. Shebang support
1.17.3. Line-end characters
1.17.4. End-of-file character

2. Keyword Instructions

2.1. ADDRESS

2.7. EXPOSE

2.8. FORWARD

2.11. INTERPRET

2.12. ITERATE

2.13. LEAVE

2.16. NUMERIC

2.17. OPTIONS

2.18. PARSE

2.19. PROCEDURE

2.22. QUEUE

2.23. RAISE

2.24. REPLY

2.25. RETURN

2.27. SELECT

2.28. SIGNAL

2.29. TRACE

2.29.1. Trace Alphabetic Character (Word) Options
2.29.2. Prefix Option
2.29.3. Numeric Options
2.29.4. Tracing Tips
2.29.5. The Format of Trace Output

2.30.1. USE ARG, USE STRICT ARG
2.30.2. USE LOCAL

3. Directives

3.1. ::ANNOTATE
3.2. ::ATTRIBUTE
3.3. ::CLASS
3.4. ::CONSTANT
3.5. ::METHOD
3.6. ::OPTIONS
3.7. ::REQUIRES
3.8. ::RESOURCE
3.9. ::ROUTINE

4. Objects and Classes

4.1. Types of Classes

4.1.1. Object Classes
4.1.2. Mixin Classes
4.1.3. Abstract Classes
4.1.4. Metaclasses

4.2. Creating and Using Classes and Methods

4.2.1. Using Classes
4.2.2. Scope
4.2.3. Defining Instance Methods with SETMETHOD or ENHANCED
4.2.4. Method Names
4.2.5. Default Search Order for Method Selection
4.2.6. Defining an UNKNOWN Method
4.2.7. Changing the Search Order for Methods
4.2.8. Public, Package-Scope, and Private Methods
4.2.9. Initialization
4.2.10. Object Destruction and Uninitialization
4.2.11. Required String Values
4.2.12. Concurrency

4.3. Overview of Classes Provided by Rexx

4.3.1. The Class Hierarchy
4.3.2. Class Library Notes

5. Builtin Classes

5.1. Fundamental Classes

5.1.1. Class Class (Metaclass)
5.1.2. Message Class
5.1.3. Method Class
5.1.4. Object Class
5.1.5. Package Class
5.1.6. Routine Class
5.1.7. String Class

5.2. Stream Classes

5.2.1. InputOutputStream Class
5.2.2. InputStream Class
5.2.3. OutputStream Class
5.2.4. Stream Class

5.3. Collection Classes

5.3.1. Organization of the Collection Classes
5.3.2. Collection Class
5.3.3. MapCollection Class
5.3.4. OrderedCollection Class
5.3.5. SetCollection Class
5.3.6. Array Class
5.3.7. Bag Class
5.3.8. CircularQueue Class
5.3.9. Directory Class
5.3.10. IdentityTable Class
5.3.11. List Class
5.3.12. Properties Class
5.3.13. Queue Class
5.3.14. Relation Class
5.3.15. Set Class
5.3.16. Stem Class
5.3.17. StringTable Class
5.3.18. Table Class
5.3.19. Sorting Ordered Collections
5.3.20. Concept of Set Operations

5.4. Utility Classes

5.4.1. Alarm Class
5.4.2. AlarmNotification Class
5.4.3. Buffer Class
5.4.4. Comparable Class
5.4.5. Comparator Classes
5.4.6. DateTime Class
5.4.7. EventSemaphore Class
5.4.8. File Class
5.4.9. MessageNotification Class
5.4.10. Monitor Class
5.4.11. MutableBuffer Class
5.4.12. MutexSemaphore Class
5.4.13. Orderable Class
5.4.14. Pointer Class
5.4.15. RegularExpression Class
5.4.16. RexxContext Class
5.4.17. RexxInfo Class
5.4.18. RexxQueue Class
5.4.19. Singleton Class (Metaclass)
5.4.20. StackFrame Class
5.4.21. StreamSupplier Class
5.4.22. Supplier Class
5.4.23. Ticker Class
5.4.24. TimeSpan Class
5.4.25. TraceObject Class
5.4.26. Validate Class
5.4.27. VariableReference Class
5.4.28. WeakReference Class

6. Rexx Runtime Objects

6.1. The Environment Directory (.ENVIRONMENT)

6.1.1. The ENDOFLINE Constant (.ENDOFLINE)
6.1.2. The FALSE Constant (.FALSE)
6.1.3. The NIL Object (.NIL)
6.1.4. The RexxInfo Object (.RexxInfo)
6.1.5. The TRUE Constant (.TRUE)

6.2. The Local Directory (.LOCAL)

6.3. The Debug Input Monitor (.DEBUGINPUT)

6.4. The Error Monitor (.ERROR)

6.5. The Input Monitor (.INPUT)

6.6. The Output Monitor (.OUTPUT)

6.7. The Trace Output Monitor (.TRACEOUTPUT)

6.8. The STDERR Stream (.STDERR)

6.9. The STDIN Stream (.STDIN)

6.10. The STDOUT Stream (.STDOUT)

6.11. The STDQUE Queue (.STDQUE)

6.12. The SYSCARGS Array (.SYSCARGS)

6.13. The Rexx Context (.CONTEXT)

6.14. The Line Number (.LINE)

6.15. The METHODS StringTable (.METHODS)

6.16. The ROUTINES StringTable (.ROUTINES)

6.17. The RESOURCES StringTable (.RESOURCES)

6.18. The Return Status (.RS)

7. Functions

7.1. Syntax

7.2. Functions and Subroutines

7.2.1. Search Order
7.2.2. Errors during Execution

7.3. Return Values

7.4. Built-in Functions

8. Rexx Utilities (RexxUtil)

8.1. A Note on Error Codes
8.2. List of Rexx Utility Functions
8.3. RxMessageBox (Windows only)
8.4. RxWinExec (Windows only)
8.5. SysAddRexxMacro
8.6. SysBootDrive (Windows only)
8.7. SysClearRexxMacroSpace
8.8. SysCls
8.9. SysCreatePipe (Unix-like systems only)
8.10. SysCurPos (Windows only)
8.11. SysCurState (Windows only)
8.12. SysDriveInfo (Windows only)
8.13. SysDriveMap (Windows only)
8.14. SysDropRexxMacro
8.15. SysDumpVariables
8.16. SysFileCopy
8.17. SysFileDelete
8.18. SysFileExists
8.19. SysFileMove
8.20. SysFileSearch
8.21. SysFileSystemType (Windows only)
8.22. SysFileTree
8.23. SysFork (Unix-like systems only)
8.24. SysFormatMessage
8.25. SysFromUnicode (Windows only)
8.26. SysGetErrorText
8.27. SysGetFileDateTime
8.28. SysGetKey
8.29. SysGetLongPathName (Windows only)
8.30. SysGetMessage (Unix-like systems only)
8.31. SysGetMessageX (Unix-like systems only)
8.32. SysGetShortPathName (Windows only)
8.33. SysIni (Windows only)
8.34. SysIsFile
8.35. SysIsFileCompressed (Windows only)
8.36. SysIsFileDirectory
8.37. SysIsFileEncrypted (Windows only)
8.38. SysIsFileLink
8.39. SysIsFileNotContentIndexed (Windows only)
8.40. SysIsFileOffline (Windows only)
8.41. SysIsFileSparse (Windows only)
8.42. SysIsFileTemporary (Windows only)
8.43. SysLinVer (Linux Only)
8.44. SysLoadRexxMacroSpace
8.45. SysMkDir
8.46. SysQueryProcess
8.47. SysQueryRexxMacro
8.48. SysReorderRexxMacro
8.49. SysRmDir
8.50. SysSaveRexxMacroSpace
8.51. SysSearchPath
8.52. SysSetFileDateTime
8.53. SysSetPriority
8.54. SysShutdownSystem (Windows only)
8.55. SysSleep
8.56. SysStemCopy
8.57. SysStemDelete
8.58. SysStemInsert
8.59. SysStemSort
8.60. SysSwitchSession (Windows only)
8.61. SysSystemDirectory (Windows only)
8.62. SysTempFileName
8.63. SysTextScreenRead (Windows only)
8.64. SysTextScreenSize (Windows only)
8.65. SysToUnicode (Windows only)
8.66. SysUtilVersion
8.67. SysVersion
8.68. SysVolumeLabel (Windows only)
8.69. SysWait (Unix-like systems only)
8.70. SysWaitNamedPipe (Windows only)
8.71. SysWinDecryptFile (Windows only)
8.72. SysWinEncryptFile (Windows only)
8.73. SysWinGetDefaultPrinter (Windows only)
8.74. SysWinGetPrinters (Windows only)
8.75. SysWinSetDefaultPrinter (Windows only)
8.76. SysWinVer (Windows only)

9.1. Simple Templates for Parsing into Words

9.1.1. Message Term Assignments
9.1.2. The Period as a Placeholder

9.2. Templates Containing String Patterns

9.3. Templates Containing Positional (Numeric) Patterns

9.3.1. Combining Patterns and Parsing into Words

9.4. Parsing with Variable Patterns

9.5. Using UPPER, LOWER, and CASELESS

9.6. Parsing Instructions Summary

9.7. Parsing Instructions Examples

9.8. Advanced Topics in Parsing

9.8.1. Parsing Several Strings
9.8.2. Combining String and Positional Patterns
9.8.3. Conceptual Overview of Parsing

10. Numbers and Arithmetic

10.1. Precision

10.2. Arithmetic Operators

10.2.1. Multiplication
10.2.2. Power
10.2.3. Integer Division
10.2.4. Remainder
10.2.5. Operator Examples

10.3. Exponential Notation

10.4. Numeric Comparisons

10.5. Whole Numbers

10.6. Whole Number Limits

10.7. Arithmetic Errors

11. Conditions and Condition Traps

11.1. Action Taken when a Condition Is Not Trapped

11.2. Action Taken when a Condition Is Trapped

11.3. Condition Information

11.3.1. Descriptive Strings
11.3.2. Additional Object Information
11.3.3. The Special Variable RC
11.3.4. The Special Variable SIGL
11.3.5. Condition Object

12. Concurrency

12.1. Early Reply

12.2. Message Objects

12.3. Default Concurrency

12.3.1. Sending Messages within an Activity

12.4. Using Additional Concurrency Mechanisms

12.4.1. SETUNGUARDED Method and UNGUARDED Option
12.4.2. GUARD ON and GUARD OFF
12.4.3. Guarded Methods
12.4.4. Additional Examples

13. The Security Manager

13.1. Calls to the Security Manager

13.1.1. Example

14. Input and Output Streams

14.1. The Input and Output Model

14.1.1. Input Streams
14.1.2. Output Streams
14.1.3. External Data Queue
14.1.4. Default Stream Names
14.1.5. Line versus Character Positioning

14.2. Implementation

14.3. Operating System Specifics

14.4. Examples of Input and Output

14.5. Errors during Input and Output

14.6. Summary of Rexx I/O Instructions and Methods

15. Debugging Aids

15.1. Interactive Debugging of Programs

15.2. Debugging Aids

15.3. RXTRACE Variable

15.4. Debugging Multithreaded Programs

15.4.1. About Debugging Guarded and Unguarded Methods
15.4.2. Multithreaded Additions to TRACE
15.4.3. Examples

16. Reserved Keywords

17. Special Variables

18. Useful Services

18.1. Windows Commands

18.2. Linux Commands

18.3. Subcommand Handler Services

18.3.1. The RXSUBCOM Command

18.4. The RXQUEUE Filter

18.5. Distributing Programs without Source

A. Using DO and LOOP

A.1. Simple DO Group

A.2. Repetitive Loops

A.2.1. Simple Repetitive Loops
A.2.2. Controlled Repetitive Loops
A.2.3. Repetitive Loops over Collections
A.2.4. Repetitive Loops over Suppliers

A.3. Conditional Phrases (WHILE and UNTIL)

A.4. LABEL Phrase

A.5. COUNTER Phrase

A.6. Conceptual Model of Loops

B. Migration

B.1. Incompatible ooRexx features

B.1.1. RexxUtil SysTempFileName

B.2. Deprecated Rexx features

B.2.1. RexxUtil Semaphore functions
B.2.2. RexxUtil SysLoadFuncs/SysDropFuncs
B.2.3. ::OPTIONS NOVALUE ERROR directive
B.2.4. Class ArgUtil

C. Error Numbers and Messages

C.1. Error List

C.1.1. Error 3 - Failure during initialization.
C.1.2. Error 4 - Program interrupted.
C.1.3. Error 5 - System resources exhausted.
C.1.4. Error 6 - Unmatched "/*" or quote.
C.1.5. Error 7 - WHEN or OTHERWISE expected.
C.1.6. Error 8 - Unexpected THEN or ELSE.
C.1.7. Error 9 - Unexpected WHEN or OTHERWISE.
C.1.8. Error 10 - Unexpected or unmatched END.
C.1.9. Error 11 - Control stack full.
C.1.10. Error 13 - Invalid character in program.
C.1.11. Error 14 - Incomplete DO/LOOP/SELECT/IF.
C.1.12. Error 15 - Invalid hexadecimal or binary string.
C.1.13. Error 16 - Label not found.
C.1.14. Error 17 - Unexpected PROCEDURE.
C.1.15. Error 18 - THEN expected.
C.1.16. Error 19 - String or symbol expected.
C.1.17. Error 20 - Symbol expected.
C.1.18. Error 21 - Invalid data on end of clause.
C.1.19. Error 22 - Invalid character string.
C.1.20. Error 23 - Invalid data string.
C.1.21. Error 24 - Invalid TRACE request.
C.1.22. Error 25 - Invalid subkeyword found.
C.1.23. Error 26 - Invalid whole number.
C.1.24. Error 27 - Invalid DO or LOOP syntax.
C.1.25. Error 28 - Invalid LEAVE or ITERATE.
C.1.26. Error 29 - Environment name too long.
C.1.27. Error 30 - Name or symbol too long.
C.1.28. Error 31 - Name starts with number or ".".
C.1.29. Error 33 - Invalid expression result.
C.1.30. Error 34 - Logical value not 0 or 1.
C.1.31. Error 35 - Invalid expression.
C.1.32. Error 36 - Unmatched "(" or "[" in expression.
C.1.33. Error 37 - Unexpected ",", ")", or "]".
C.1.34. Error 38 - Invalid template or pattern.
C.1.35. Error 39 - Evaluation stack overflow.
C.1.36. Error 40 - Incorrect call to routine.
C.1.37. Error 41 - Bad arithmetic conversion.
C.1.38. Error 42 - Arithmetic overflow/underflow.
C.1.39. Error 43 - Routine not found.
C.1.40. Error 44 - Function or message did not return data.
C.1.41. Error 45 - No data specified on function RETURN.
C.1.42. Error 46 - Invalid variable reference.
C.1.43. Error 47 - Unexpected label.
C.1.44. Error 48 - Failure in system service.
C.1.45. Error 49 - Interpretation error.
C.1.46. Error 88 - Invalid argument.
C.1.47. Error 89 - Variable or message term expected.
C.1.48. Error 90 - External name not found.
C.1.49. Error 91 - No result object.
C.1.50. Error 92 - OLE error.
C.1.51. Error 93 - Incorrect call to method.
C.1.52. Error 97 - Object method not found.
C.1.53. Error 98 - Execution error.
C.1.54. Error 99 - Translation error.

C.2. RXSUBCOM Utility Program

C.2.1. Error 116 - The RXSUBCOM REGISTER parameters are incorrect.
C.2.2. Error 117 - The RXSUBCOM DROP parameters are incorrect.
C.2.3. Error 118 - The RXSUBCOM LOAD parameters are incorrect.
C.2.4. Error 125 - The RXSUBCOM QUERY parameters are incorrect.

C.3. RXQUEUE Utility Program

C.3.1. Error 119 - The REXX rxapi queuing system is not available.
C.3.2. Error 120 - The size of the data is incorrect.
C.3.3. Error 121 - Storage for data queues is exhausted.
C.3.4. Error 122 - The name %1 is not a valid queue name.
C.3.5. Error 123 - The queue access mode is not correct.
C.3.6. Error 124 - The queue %1 does not exist.
C.3.7. Error 131 - The syntax of the command is incorrect.
C.3.8. Error 132 - System error occurred while processing the command.

C.4. rexxc Utility Program

C.4.1. Error 127 - The rexxc command parameters are incorrect.
C.4.2. Error 128 - Output file name must be different from input file name.
C.4.3. Error 129 - SYNTAX: rexxc inputfile [outputfile] [-s] [-e]
C.4.4. Error 130 - Without outputfile rexxc only performs a syntax check.

D.1. Trademarks
D.2. Source Code For This Document

E. Common Public License Version 1.0

E.1. Definitions
E.2. Grant of Rights
E.3. Requirements
E.4. Commercial Distribution
E.5. No Warranty
E.6. Disclaimer of Liability
E.7. General

F. Revision History

NextPreface