Product SiteDocumentation Site

ooRexx Documentation 4.2

Open Object Rexx™

Reference

Edition 1

W. David Ashley

Rony G. Flatscher

Mark Hessling

Rick McGuire

Lee Peedin

Oliver Sims

Jon Wolfers

Legal Notice

Copyright © 2005-2014 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: http://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.
Preface
1. Document Conventions
1.1. Typographic Conventions
1.2. Pull-quote Conventions
1.3. 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
3.3. comp.lang.rexx Newsgroup
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. Polymorphism
1.7. Classes and Instances
1.8. Data Abstraction
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.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. 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. Message Instructions
1.15. Commands to External Environments
1.15.1. Environment
1.15.2. Commands
1.16. Using Rexx on Windows and Unix
2. Keyword Instructions
2.1. ADDRESS
2.2. ARG
2.3. CALL
2.4. DO
2.5. DROP
2.6. EXIT
2.7. EXPOSE
2.8. FORWARD
2.9. GUARD
2.10. IF
2.11. INTERPRET
2.12. ITERATE
2.13. LEAVE
2.14. LOOP
2.15. NOP
2.16. NUMERIC
2.17. OPTIONS
2.18. PARSE
2.19. PROCEDURE
2.20. PULL
2.21. PUSH
2.22. QUEUE
2.23. RAISE
2.24. REPLY
2.25. RETURN
2.26. SAY
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. USE
3. Directives
3.1. ::ATTRIBUTE
3.2. ::CLASS
3.3. ::CONSTANT
3.4. ::METHOD
3.5. ::OPTIONS
3.6. ::REQUIRES
3.7. ::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 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. The Builtin Classes
5.1. The Fundamental Classes
5.1.1. The Object Class
5.1.2. The Class Class
5.1.3. The String Class
5.1.4. The Method Class
5.1.5. The Routine Class
5.1.6. The Package Class
5.1.7. The Message Class
5.2. The Stream Classes
5.2.1. The InputStream Class
5.2.2. The OutputStream Class
5.2.3. The InputOutputStream Class
5.2.4. The Stream Class
5.3. The Collection Classes
5.3.1. Organization of the Collection Classes
5.3.2. The Collection Class
5.3.3. The MapCollection Class
5.3.4. The OrderedCollection Class
5.3.5. The SetCollection Class
5.3.6. The Array Class
5.3.7. The Bag Class
5.3.8. The CircularQueue Class
5.3.9. The Directory Class
5.3.10. The List Class
5.3.11. The Properties Class
5.3.12. The Queue Class
5.3.13. The Relation Class
5.3.14. The Set Class
5.3.15. The Stem Class
5.3.16. The Table Class
5.3.17. The IdentityTable Class
5.3.18. Sorting Ordered Collections
5.3.19. The Concept of Set Operations
5.4. The Utility Classes
5.4.1. The DateTime Class
5.4.2. The Alarm Class
5.4.3. The TimeSpan Class
5.4.4. The Comparable Class
5.4.5. The Orderable Class
5.4.6. The Comparator Class
5.4.7. The CaselessComparator Class
5.4.8. The ColumnComparator Class
5.4.9. The CaselessColumnComparator Class
5.4.10. The DescendingComparator Class
5.4.11. The CaselessDescendingComparator Class
5.4.12. The InvertingComparator Class
5.4.13. The NumericComparator Class
5.4.14. The Monitor Class
5.4.15. The MutableBuffer Class
5.4.16. The RegularExpression Class
5.4.17. The RexxQueue Class
5.4.18. The Supplier Class
5.4.19. The StreamSupplier Class
5.4.20. The RexxContext Class
5.4.21. The StackFrame Class
5.4.22. The WeakReference Class
5.4.23. The Pointer Class
5.4.24. The Buffer Class
5.4.25. The File 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 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 Rexx Context (.CONTEXT)
6.13. The Line Number (.LINE)
6.14. The METHODS Directory (.METHODS)
6.15. The ROUTINES Directory (.ROUTINES)
6.16. 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
7.4.1. ABBREV (Abbreviation)
7.4.2. ABS (Absolute Value)
7.4.3. ADDRESS
7.4.4. ARG (Argument)
7.4.5. B2X (Binary to Hexadecimal)
7.4.6. BEEP
7.4.7. BITAND (Bit by Bit AND)
7.4.8. BITOR (Bit by Bit OR)
7.4.9. BITXOR (Bit by Bit Exclusive OR)
7.4.10. C2D (Character to Decimal)
7.4.11. C2X (Character to Hexadecimal)
7.4.12. CENTER (or CENTRE)
7.4.13. CHANGESTR
7.4.14. CHARIN (Character Input)
7.4.15. CHAROUT (Character Output)
7.4.16. CHARS (Characters Remaining)
7.4.17. COMPARE
7.4.18. CONDITION
7.4.19. COPIES
7.4.20. COUNTSTR
7.4.21. D2C (Decimal to Character)
7.4.22. D2X (Decimal to Hexadecimal)
7.4.23. DATATYPE
7.4.24. DATE
7.4.25. DELSTR (Delete String)
7.4.26. DELWORD (Delete Word)
7.4.27. DIGITS
7.4.28. DIRECTORY
7.4.29. ENDLOCAL (Linux only)
7.4.30. ERRORTEXT
7.4.31. FILESPEC
7.4.32. FORM
7.4.33. FORMAT
7.4.34. FUZZ
7.4.35. INSERT
7.4.36. LASTPOS (Last Position)
7.4.37. LEFT
7.4.38. LENGTH
7.4.39. LINEIN (Line Input)
7.4.40. LINEOUT (Line Output)
7.4.41. LINES (Lines Remaining)
7.4.42. LOWER
7.4.43. MAX (Maximum)
7.4.44. MIN (Minimum)
7.4.45. OVERLAY
7.4.46. POS (Position)
7.4.47. QUALIFY
7.4.48. QUEUED
7.4.49. RANDOM
7.4.50. REVERSE
7.4.51. RIGHT
7.4.52. RXFUNCADD
7.4.53. RXFUNCDROP
7.4.54. RXFUNCQUERY
7.4.55. RXQUEUE
7.4.56. SETLOCAL (Linux only)
7.4.57. SIGN
7.4.58. SOURCELINE
7.4.59. SPACE
7.4.60. STREAM
7.4.61. STRIP
7.4.62. SUBSTR (Substring)
7.4.63. SUBWORD
7.4.64. SYMBOL
7.4.65. TIME
7.4.66. TRACE
7.4.67. TRANSLATE
7.4.68. TRUNC (Truncate)
7.4.69. UPPER
7.4.70. USERID
7.4.71. VALUE
7.4.72. VAR
7.4.73. VERIFY
7.4.74. WORD
7.4.75. WORDINDEX
7.4.76. WORDLENGTH
7.4.77. WORDPOS (Word Position)
7.4.78. WORDS
7.4.79. X2B (Hexadecimal to Binary)
7.4.80. X2C (Hexadecimal to Character)
7.4.81. X2D (Hexadecimal to Decimal)
7.4.82. XRANGE (Hexadecimal Range)
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. SysCloseEventSem
8.9. SysCloseMutexSem
8.10. SysCls
8.11. SysCreateEventSem
8.12. SysCreateMutexSem
8.13. SysCreatePipe (Unix only)
8.14. SysCurPos (Windows only)
8.15. SysCurState (Windows only)
8.16. SysDriveInfo (Windows only)
8.17. SysDriveMap (Windows only)
8.18. SysDropFuncs
8.19. SysDropRexxMacro
8.20. SysDumpVariables
8.21. SysFileCopy
8.22. SysFileDelete
8.23. SysFileExists
8.24. SysFileMove (Windows only)
8.25. SysFileSearch
8.26. SysFileSystemType (Windows only)
8.27. SysFileTree
8.28. SysFork (Unix only)
8.29. SysFromUnicode (Windows only)
8.30. SysGetErrortext
8.31. SysGetFileDateTime
8.32. SysGetKey
8.33. SysGetMessage (Unix only)
8.34. SysGetMessageX (Unix only)
8.35. SysIni (Windows only)
8.36. SysIsFile
8.37. SysIsFileCompressed (Windows only)
8.38. SysIsFileDirectory
8.39. SysIsFileEncrypted (Windows only)
8.40. SysIsFileLink
8.41. SysIsFileNotContentIndexed (Windows only)
8.42. SysIsFileOffline (Windows only)
8.43. SysIsFileSparse (Windows only)
8.44. SysIsFileTemporary (Windows only)
8.45. SysLinVer (Linux Only)
8.46. SysLoadFuncs
8.47. SysLoadRexxMacroSpace
8.48. SysMkDir
8.49. SysOpenEventSem
8.50. SysOpenMutexSem
8.51. SysPostEventSem
8.52. SysPulseEventSem (Windows only)
8.53. SysQueryProcess
8.54. SysQueryRexxMacro
8.55. SysReleaseMutexSem
8.56. SysReorderRexxMacro
8.57. SysRequestMutexSem
8.58. SysResetEventSem
8.59. SysRmDir
8.60. SysSaveRexxMacroSpace
8.61. SysSearchPath
8.62. SysSetFileDateTime
8.63. SysSetPriority
8.64. SysShutdownSystem (Windows only)
8.65. SysSleep
8.66. SysStemCopy
8.67. SysStemDelete
8.68. SysStemInsert
8.69. SysStemSort
8.70. SysSwitchSession (Windows only)
8.71. SysSystemDirectory (Windows only)
8.72. SysTempFileName
8.73. SysTextScreenRead (Windows only)
8.74. SysTextScreenSize (Windows only)
8.75. SysToUnicode (Windows only)
8.76. SysUtilVersion
8.77. SysVersion
8.78. SysVolumeLabel (Windows only)
8.79. SysWait (Unix only)
8.80. SysWaitEventSem
8.81. SysWaitNamedPipe (Windows only)
8.82. SysWinDecryptFile (Windows only)
8.83. SysWinEncryptFile (Windows only)
8.84. SysWinGetDefaultPrinter (Windows only)
8.85. SysWinGetPrinters (Windows only)
8.86. SysWinSetDefaultPrinter (Windows only)
8.87. SysWinVer (Windows only)
9. Parsing
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. Power
10.2.2. Integer Division
10.2.3. Remainder
10.2.4. Operator Examples
10.3. Exponential Notation
10.4. Numeric Comparisons
10.5. Limits and Errors when Rexx Uses Numbers Directly
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 Objects
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
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.3.2. The RXQUEUE Filter
18.4. 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.3. Repetitive Loops over Collections
A.4. Conditional Phrases (WHILE and UNTIL)
A.5. LABEL Phrase
A.6. Conceptual Model of Loops
B. Migration
B.1. Error Codes and Return Codes
B.2. Error Detection and Reporting
B.3. Environment Variables
B.4. Stems versus Collections
B.5. Input and Output Using Functions and Methods
B.6. .Environment
B.7. Deleting Environment Variables
B.8. Trace in Macrospace
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 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 string 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 parameter REGISTER is incorrect.
C.2.2. Error 117 - The RXSUBCOM parameter DROP is incorrect.
C.2.3. Error 118 - The RXSUBCOM parameter LOAD is incorrect.
C.2.4. Error 125 - The RXSUBCOM parameter QUERY is incorrect.
C.3. RXQUEUE Utility Program
C.3.1. Error 119 - The REXX queuing system is not initialized.
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 InProgramName [OutProgramName] [/S]
C.4.4. Error 130 - Without OutProgramName REXXC only performs a syntax check
C.4.5. Error 133 - SYNTAX: REXXC InProgramName [OutProgramName] [-s]
D. Notices
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
Index