Make your own free website on
Table of Contents
Introduction to Regina                                           
  1. Purpose of this document                                   
  2. Implementation                                             
  3. Ports of Regina                                            
  4. Executing Rexx programs with Regina                        
     4.1 Switches                                                
     4.2 External Rexx programs                                  

Rexx Language Constructs                                         
  1. Definitions                                                
       Example: Binary transferring files                       
  2. Null clauses                                               
       Example: Tracing comments                                
       Example: Trailing comments                               
  3. Commands                                                   
     3.1 Assignments                                             
       Example: Multiple assignment                             
       Example: Emulating a default value                       
       Example: Space considerations                            
  4. Instructions                                               
     4.1 The ADDRESS Instruction                                 
       Example: Examples of the ADDRESS instruction             
       Example: The VALUE subkeyword                           
     4.2 The ARG Instruction                                    
       Example: Beware assignments                             
     4.3 The CALL Instruction                                   
       Example: Subroutines and trace settings                 
       Example: Labels are literals                            
     4.4 The DO/END Instruction                                 
       Example: Evaluation order                               
       Example: Loop convergence For the reasons just explained,
       the instruction:                                        
       Example: Difference between UNTIL and WHILE             
     4.5 The DROP Instruction                                   
       Example: Dropping compound variables                    
       Example: Tail-substitution in DROP                      
     4.6 The EXIT Instruction                                   
     4.7 The IF/THEN/ELSE Instruction                           
       Example: Dangling ELSE                                  
     4.8 The INTERPRET Instruction                              
       Example: Self-modifying Program                         
     4.9 The ITERATE Instruction                                
     4.10 The LEAVE Instruction                                 
       Example: Iterating a simple DO/END                      
     4.11 The NOP Instruction                                   
     4.12 The NUMERIC Instruction                               
       Example: Simulating relative accuracy with absolute
     4.13 The OPTIONS Instruction                               
       Example: Drawback of OPTIONS                            
     4.14 The PARSE Instruction                                 
     4.15 The PROCEDURE Instruction                             
       Example: Dynamic execution of PROCEDURE                 
       Example: Indirect exposing                              
       Example: Order of exposing                              
       Example: Global variables                               
     4.16 The PULL Instruction                                  
     4.17 The PUSH Instruction                                  
     4.18 The QUEUE Instruction                                 
     4.19 The RETURN Instruction                                
       Example: Multiple entry points                          
     4.20 The SELECT/WHEN/OTHERWISE Instruction                 
       Example: Writing SWITCH as IF                           
     4.21 The SIGNAL Instruction                                
       Example: Transferring control to inside a loop          
       Example: Naming condition traps                         
       Example: Named condition traps in TRL1                  
     4.22 The TRACE Instruction                                 
  5. Operators                                                 
     5.1 Arithmetic Operators                                   
     5.2 Assignment Operators                                   
     5.3 Comparative Operators                                  
     5.4 Concatenation Operators                                
     5.5 Logical Operators                                      
  6. Implementation-Specific Information                       
     6.1 Environments in Regina 0.05h                           
     6.2 List of All Environment Names in Use                   

REXX Built-in Functions                                         
  1. General Information                                       
     1.1 The Syntax Format                                      
     1.2 Precision and Normalization                            
     1.3 Standard Parameter Names                               
     1.4 Error Messages                                         
     1.5 Possible System Dependencies                           
     1.6 Blanks vs. Spaces                                      
  2. REXX Standard Built-in Functions                          
  3. Implementation specific documentation for Regina          
     3.1 Deviations from the Standard                           
     3.2 Interpreter Internal Debugging Functions               
     3.3 REXX UNIX Interface Functions                          

  1. What are Conditions                                       
     1.1 What Do We Need Conditions for?                        
     1.2 Terminology                                            
  2. The Mythical Standard Condition                           
     2.1 Information Regarding Conditions (data structures)     
     2.2 How to Set up a Condition Trap                         
     2.3 How to Raise a Condition                               
     2.4 How to Trigger a Condition Trap                        
     2.5 Trapping by Method SIGNAL                              
     2.6 Trapping by Method CALL                                
     2.7 The Current Trapped Condition                          
  3. The Real Conditions                                       
     3.1 The SYNTAX condition                                   
     3.2 The HALT condition                                     
     3.3 The ERROR condition                                    
     3.4 The FAILURE condition                                  
     3.5 The NOVALUE condition                                  
     3.6 The NOTREADY condition                                 
  4. Further Notes on Conditions                               
     4.1 Conditions under Language Level 3.50                   
     4.2 Pitfalls when Using Condition Traps                    
     4.3 The Correctness of this Description                    
  5. Conditions in Regina                                      
     5.1 How to Raise the HALT condition                        
     5.2 Extended built-in functions                            
     5.3 Extra Condition in Regina                              
     5.4 Various Other Existing Extensions                      
  6. Possible Future extensions                                

Stream Input and Output                                         
  1. Background and Historical Remarks                         
  2. REXX’s Notion of a Stream                                 
  3. Short Crash-Course                                        
  4. Naming Streams                                            
       Example: Specifying file names                          
       Example: Internal file handles                          
       Example: Unix temporary files                           
       Example: Files in different directories                 
  5. Persistent and Transient Streams                          
       Example: Determining stream type                        
  6. Opening a Stream                                          
       Example: Not closing files                              
  7. Closing a Stream                                          
  8. Character-wise and Line-wise I/O                          
       Example: Character-wise handling of EOL                 
  9. Reading and Writing                                       
       Example: Counting lines, words, and characters          
  10. Determining the Current Position                         
       Example: Retrieving current position                    
       Example: Improved ftell function                        
  11. Positioning Within a File                                
       Example: Repositioning in empty files                   
       Example: Relative repositioning                         
       Example: Destroying linecount                           
  12. Errors: Discovery, Handling, and Recovery                
       Example: General NOTREADY condition handler             
  13. Common Differences and Problems with Stream I/O          
     13.1 Where Implementations are Allowed to Differ           
     13.2 Where Implementations might Differ anyway             
     13.3 LINES() and CHARS() are Inaccurate                    
       Example: File reading idiom                             
     13.4 The Last Line of a Stream                             
     13.5 Other Parts of the I/O System                         
     13.6 Implementation-Specific Information                   
     13.7 Stream I/O in Regina 0.07a                            
     13.8 Functionality to be Implemented Later                 
     13.9 Stream I/O in ARexx 1.15                              
     13.10 Main Differences from Standard REXX                 
     13.11 Stream I/O in BRexx 1.0b                            
     13.12 Problems with Binary and Text Modes                 
       Example: Differing end-of-lines                        

  1. Why Have Extensions                                      
  2. Extensions and Standard REXX                             
  3. Specifying Extensions in Regina                          
  4. The Trouble Begins                                       
  5. The Format of the OPTIONS clause                         
       Example: Extensions changing parsing                   
  6. Why You Should Seriously Consider Not Using Extensions   
  7. The Fundamental Extensions                               
  8. Meta-extensions                                          
  9. Semi-standards                                           
  10. Standards                                               

The Stack                                                      
  1. Background and history                                   
  2. General functionality of the stack                       
     2.1 Basic functionality                                   
       Example: Using the stack to transfer parameters        
     2.2 LIFO and FIFO stack operations                        
     2.3 Using multiple buffers in the stack                   
     2.4 The zeroth buffer                                     
       Example: Process all strings in the stack              
       Example: How to empty the stack                        
     2.5 Creating new stacks                                   
       Example: Counting the number of buffers                
  3. The interface between REXX and the stack                 
  4. Strategies for implementing stacks                       
       Example: Commands takes input from the stack           
       Example: “Execing” commands                            
  5. Specific implementations of stacks                       
     5.1 Implementation of the stack in Regina 0.05h           

Interfacing Rexx to other programs                             
  1. Overview of functions in SAA                             
     1.1 Include Files and Libraries                           
     1.2 Preprocessor Symbols                                  
     1.3 Allocating and De-allocating Space                    
     1.4 Data structures and data types                        
  2. The Subcommand Handler Interface                         
     2.1 What is a Subcommand Handler                          
     2.2 The RexxRegisterSubcomExe() function                  
     2.3 The RexxRegisterSubcomDll() function                  
     2.4 The RexxDeregisterSubcom() function                   
     2.5 The RexxQuerySubcom() function                        
  3. The External Function Handler Interface                  
     3.1 What is an External Function Handler                  
     3.2 The RexxRegisterFunctionExe() function                
     3.3 The RexxRegisterFunctionDll() function                
     3.4 The RexxDeregisterFunction() function                 
     3.5 The RexxQueryFunction() function                      
  4. Executing REXX Code                                      
     4.1 The RexxStart() function                              
  5. Variable Pool Interface                                  
     5.1 Symbolic or Direct                                    
     5.2 The SHVBLOCK structure                                
     5.3 Regina Notes for the Variable Pool                    
     5.4 The RexxVariablePool() function                       
  6. The System Exit Handler Interface                        
     6.1 The System Exit Handler                               
     6.2 List of System Exit Handlers                          

Implementation Limits                                          
  1. Why Use Limits?                                          
  2. What Limits to Choose?                                   
  3. Required Limits                                          
  4. Older (Obsolete) Limits                                  
  5. What the Standard does not Say                           
  6. What an Implementation is Allowed to “Ignore”            
  7. Limits in Regina