Open Object Rexx™

Programming Guide

Version 4.0.0 Edition


August 14, 2009

W. David Ashley
Rony G. Flatscher
Mark Hessling
Rick McGuire
Mark Miesfeld
Lee Peedin
Rainer Tammer
Jon Wolfers

Table of Contents
1. About This Book
Who Should Read This Book
What You Should Know before Reading This Book
Getting Help
The Rexx Language Association Mailing List
The Open Object Rexx SourceForge Site
comp.lang.rexx Newsgroup
2. Meet Open Object Rexx (ooRexx)
The Main Attractions
Object-Oriented Programming
An English-Like Language
Cross-Platform Versatility
Fewer Rules
Interpreted, Not Compiled
Built-In Classes and Functions
Typeless Variables
String Handling
Clear Error Messages and Powerful Debugging
Impressive Development Tools
Rexx and the Operating System
A Classic Language Gets Classier
From Traditional Rexx to Object Rexx
The Object Advantage
The Next Step
3. A Quick Tour of Traditional Rexx
What Is a Rexx Program?
Running a Rexx Program
Elements of Rexx
Writing Your Program
Testing Your Program
Variables, Constants, and Literal Strings
Assignments
Using Functions
Program Control
Subroutines and Procedures
4. Into the Object World
What Is Object-Oriented Programming?
Modularizing Data
Modeling Objects
How Objects Interact
Methods
Polymorphism
Classes and Instances
Data Abstraction
Subclasses, Superclasses, and Inheritance
5. The Basics of Classes
Rexx Classes for Programming
The Alarm Class
The Collection Classes
The Message Class
The Monitor Class
The Stem Class
The Stream Class
The String Class
The Supplier Class
Rexx Classes for Organizing Objects
The Object Class
The Class Class
Rexx Classes: The Big Picture
Creating Your Own Classes Using Directives
What Are Directives?
The Directives Rexx Provides
How Directives Are Processed
A Sample Program Using Directives
Another Sample Program
Defining an Instance
Types of Classes
Object Classes
Mixin Classes
Abstract Classes
Metaclasses
6. A Closer Look at Objects
Using Objects in Rexx
Common Methods
Initializing Instances Using INIT
Returning String Data Using STRING
Uninitializing and Deleting Instances Using UNINIT
Special Method Variables
Public, Local, and Built-In Environment Objects
The Public Environment Object (.environment)
The Local Environment Object (.local)
Built-In Environment Objects
The Default Search Order for Environment Objects
Determining the Scope of Methods and Variables
Objects with a Class Scope
Objects with Their Own Unique Scope
More about Methods
The Default Search Order for Selecting a Method
Changing the Search Order for Methods
Public versus Private Methods
Defining an UNKNOWN Method
Concurrency
Inter-Object Concurrency
Intra-Object Concurrency
7. Commands
How to Issue Commands
Rexx and Batch Files
Using Variables to Build Commands
Using Quotation Marks
ADDRESS Instruction
Using Return Codes from Commands
Subcommand Processing
Trapping Command Errors
Instructions and Conditions
Disabling Traps
Using SIGNAL ON ERROR
Using CALL ON ERROR
A Common Error-Handling Routine
8. Input and Output
More about Stream Objects
Reading a Text File
Reading a Text File into an Array
Reading Specific Lines of a Text File
Writing a Text File
Reading Binary Files
Reading Text Files a Character at a Time
Writing Binary Files
Closing Files
Direct File Access
Checking for the Existence of a File
Getting Other Information about a File
Using Standard I/O
Using Windows Devices
9. Rexx C++ Application Programming Interfaces
Rexx Interpreter API
RexxCreateInterpreter
Interpreter Instance Options
Data Types Used in APIs
Rexx Object Types
Rexx Numeric Types
Introduction to API Vectors
Threading Considerations
Garbage Collection Considerations
Rexx Interpreter Instance Interface
Rexx Thread Context Interface
Rexx Method Context Interface
Rexx Call Context Interface
Rexx Exit Context Interface
Building an External Native Library
Defining Library Routines
Defining Library Methods
Rexx Exits Interface
Writing Context Exit Handlers
Context Exit Definitions
Command Handler Interface
Rexx Interface Methods Listing
Array
ArrayAppend
ArrayAppendString
ArrayAt
ArrayDimension
ArrayItems
ArrayOfFour
ArrayOfThree
ArrayOfTwo
ArrayOfOne
ArrayPut
ArraySize
AttachThread
BufferData
BufferLength
BufferStringData
BufferStringLength
CallProgram
CallRoutine
CheckCondition
ClearCondition
CString
DecodeConditionInfo
DetachThread
DirectoryAt
DirectoryPut
DirectoryRemove
Double
DoubleToObject
DoubleToObjectWithPrecision
DropContextVariable
DropObjectVariable
DropStemArrayElement
DropStemElement
False
FindClass
FindContextClass
FindPackageClass
FinishBufferString
ForwardMessage
GetAllContextVariables
GetAllStemElements
GetApplicationData
GetArgument
GetArguments
GetCallerContext
GetConditionInfo
GetContextDigits
GetContextForm
GetContextFuzz
GetContextVariable
GetGlobalEnvironment
GetLocalEnvironment
GetMessageName
GetMethod
GetMethodPackage
GetObjectVariable
GetPackageClasses
GetPackageMethods
GetPackagePublicClasses
GetPackagePublicRoutines
GetPackageRoutines
GetRoutine
GetRoutineName
GetRoutinePackage
GetScope
GetSelf
GetStemArrayElement
GetStemElement
GetStemValue
GetSuper
Halt
HaltThread
HasMethod
InvalidRoutine
Int32
Int32ToObject
Int64
Int64ToObject
InterpreterVersion
Intptr
IntptrToObject
IsArray
IsBuffer
IsDirectory
IsInstanceOf
IsMethod
IsOfType
IsPointer
IsRoutine
IsStem
IsString
LanguageLevel
LoadLibrary
LoadPackage
LoadPackageFromData
Logical
LogicalToObject
NewArray
NewBuffer
NewBufferString
NewDirectory
NewMethod
NewPointer
NewRoutine
NewStem
NewString
NewSupplier
Nil
NullString
ObjectToCSelf
ObjectToDouble
ObjectToInt32
ObjectToInt64
ObjectToIntptr
ObjectToLogical
ObjectToString
ObjectToStringSize
ObjectToStringValue
ObjectToUintptr
ObjectToUnsignedInt32
ObjectToUnsignedInt64
ObjectToValue
ObjectToWholeNumber
PointerValue
RaiseCondition
RaiseException
RaiseException0
RaiseException1
RaiseException2
RegisterLibrary
ReleaseGlobalReference
ReleaseLocalReference
RequestGlobalReference
ResolveStemVariable
SendMessage
SendMessage0
SendMessage1
SendMessage2
SetContextVariable
SetGuardOff
SetGuardOn
SetObjectVariable
SetStemArrayElement
SetStemElement
SetThreadTrace
SetTrace
String
StringData
StringGet
StringLength
StringLower
StringSize
StringSizeToObject
StringUpper
SupplierAvailable
SupplierIndex
SupplierItem
SupplierNext
Terminate
True
Uintptr
UintptrToObject
UnsignedInt32
UnsignedInt32ToObject
UnsignedInt64
UnsignedInt64ToObject
ValuesToObject
ValueToObject
WholeNumber
WholeNumberToObject
10. Classic Rexx Application Programming Interfaces
Handler Characteristics
RXSTRINGs
Calling the Rexx Interpreter
From the Operating System
From within an Application
The RexxStart Function
The RexxWaitForTermination Function (Deprecated)
The RexxDidRexxTerminate Function (Deprecated)
Subcommand Interface
Registering Subcommand Handlers
Subcommand Interface Functions
External Function Interface
Registering External Functions
Calling External Functions
External Function Interface Functions
Registered System Exit Interface
Writing System Exit Handlers
System Exit Definitions
System Exit Interface Functions
Variable Pool Interface
Interface Types
RexxVariablePool Restrictions
RexxVariablePool Interface Function
Dynamically Allocating and De-allocating Memory
The RexxAllocateMemory() Function
The RexxFreeMemory() Function
Queue Interface
Queue Interface Functions
Halt and Trace Interface
Halt and Trace Interface Functions
Macrospace Interface
Search Order
Storage of Macrospace Libraries
Macrospace Interface Functions
Windows Scripting Host Interface
Concurrency
WSH Features
A. Distributing Programs without Source
B. Sample Rexx Programs
C. Notices
Trademarks
Source Code For This Document
D. Common Public License Version 1.0
Definitions
Grant of Rights
Requirements
Commercial Distribution
No Warranty
Disclaimer of Liability
General
Index
List of Figures
2-1. Objects in a Billing Application
4-1. Modular Data—a Report Object
4-2. A Ball Object
4-3. Ball Object with Variable Names and Values
4-4. Encapsulated 5 Object
4-5. A Simple Class
4-6. Icon Class
4-7. Instances of the Icon Class
4-8. Superclass and Subclasses
4-9. The Screen-Object Superclass
4-10. Multiple Inheritance
5-1. How Subclasses Inherit Instance Methods from the Class Class
5-2. Classes and Inheritance (part 1 of 9)
5-3. Classes and Inheritance (part 2 of 9)
5-4. Classes and Inheritance (part 3 of 9)
5-5. Classes and Inheritance (part 4 of 9)
5-6. Classes and Inheritance (part 5 of 9)
5-7. Classes and Inheritance (part 6 of 9)
5-8. Classes and Inheritance (part 7 of 9)
5-9. Classes and Inheritance (part 8 of 9)
5-10. Classes and Inheritance (part 9 of 9)
6-1. Instance Methods and Class Methods
6-2. Instances in the Part Class
6-3. Scope of the Number Class
6-4. Searching the Hierarchy for a Method