Copyright Notice ARexx software and documentation are Copyright ©1987 by William S. Hawes. No part of the software or documentation may be reproduced, transmitted, translated into other languages, posted to a network, or distributed in any way without the express written permission of the author. Disclaimer This product is offered for sale "as is" with no representation of fitness for any particular purpose. The user assumes all risks and responsibilities related to its use. The material within is believed to be accurate, but the author reserves the right to make changes to the software or documentation without notice. Distribution ARexx software and documentation are available from: William S. Hawes P.O. Box 308 Maynard, MA 01754 (508) 568-8695 Please direct orders or inquiries about this product to the above address. Site licenses are available; write for further information. About ... ARexx was developed on an Amiga 1000 computer with 512K bytes of memory and two floppy disk drives. The language prototype was developed in C using I,attice C, and the production version was written in assembly-language using the Metacomco Assembler. The documention was created using the TxEd editor, and was set in 'lEX using Amiga'lEX. This is a 100% Amiga product. Trademarks Amiga, Amiga WorkBench, and Intuition are trademarks of Commodore-Amiga, Inc. Table of Contents ARexx User's Reference Manual Introduction. · 1 1 Organization of this Document . · 1 1 Using this Manual .... .2 2 Typographic Conventions · 2 2 Future Directions · 2 Chapter 1. What is ARexx? · 3 1 Language Features . · 3 2 ARexx on the Amiga . .4 3 Further Information .4 Chapter 2. Getting Acquainted · 5 1 Installing ARexx . · 5 1 ARexx and WorkBench · 5 2 Installation . · 5 3 Starting the Resident Process · 6 4 Naming Conventions . · 6 5 The REXX: Directory. · 6 2 Program Examples . · 7 Chapter 3. Elements of the Language . 11 1 Format ..... 11 2 Tokens ..... 11 1 Comment Tokens 11 2 Symbol Tokens 11 3 String Tokens. 12 4 Operators 12 5 Special Character Tokens . 13 3 Clauses .... 14 1 Null Clauses 14 2 Label Clauses 14 3 Assignment Clauses 14 4 Instruction Clauses 15 5 Command Clauses . 15 6 Clause Classification 15 4 Expressions . 16 1 Symbol Resolution 16 2 Order of Evaluation 16 5 Numbers and Numeric Precision 17 1 Boolean Values . 17 2 Numeric Precision .. 17 6 Operators . 18 1 Arithmetic Operators 18 2 Concatenation Operators 20 3 Comparison Operators . 20 4 Logical (Boolean) Operators 21 7 Stems and Compound Symbols 21 ARexx User's Reference Manual Chapter 3. Elements of the Language (cont.) 11 8 The Execution Environment . 22 1 The External Environment 22 2 The Internal Environment 22 3 Input and Output . 23 4 Resource Tracking . 24 Chapter 4. Instructions . 25 1 ADDRESS 25 2ARG .. 25 3 BREAK. 26 4 CALL 26 5 DO .. 27 6 DROP 28 7 ECHO 28 8 ELSE. 28 9 END. 29 10 EXIT 29 11 IF .. 29 12 INTERPRET . 30 13 ITERATE 30 14 LEAVE . 31 15 NOP 31 16 NUMERIC 31 17 OPTIONS 32 18 OTHERWISE 32 19 PARSE 33 1 Input Sources . 33 2 Templates . 34 20 PROCEDURE 35 21 PULL . 35 22 PUSH .. 36 23 QUEUE . 37 24 RETURN 37 25 SAY .. 38 26 SELECT 38 27 SHELL 38 28 SIGNAL 38 29 THEN. 39 30 TRACE 40 31 UPPER 40 32 WHEN 41 Chapter 5. Commands 43 1 Command Clauses . 43 2 The Host Address . 44 3 The Command Interface 44 4 Using Commands in Macro Programs . 45 5 Using ARexx with Command Shells 45 6 Command Inhibition . 46 ii Table of Contents ''''..­ Chapter 6. Functions 47 1 Syntax and Search Order 47 1 Search Order . 47 2 Internal Functions . 48 3 Built-In Functions . 49 4 External Function Libraries . 49 5 Function Hosts . 50 2 The Built-In Function Library 50 1 ABBREVO . 51 2 ABSO ... 51 3 ADDLIBO . 51 4 ADDRESSO 51 5 ARGO .. 52 6 B2CO .. 52 7 BITANDO . 52 8 BITCH GO . 52 9 BITCLRO 53 10 BITCOMPO . 53 11 BITORO 53 12 BITSETO . 53 13 BITTSTO . 53 14 BITXORO 54 15 C2BO 54 16 C2DO .. 54 17 C2XO .. 54 18 CENTERO or CENTREO 55 19 CLOSEO .. 55 20 COMPRESSO 55 21 COMPAREO 55 22 COPIESO .. 55 23 D2CO ... 56 24 DATATYPEO 56 25 DELSTRO 56 26 DELWORDO 57 27 EOFO ... 57 28 ERRORTEXTO 57 29 EXISTSO ... 57 30 EXPORTO .. 57 31 FREESPACEO 58 32 GETCLIPO . 58 33 GETSPACEO 58 34 HASHO .. 58 35IMPORTO 59 36INDEX() 59 37INSERTO . 59 38 LASTPOSO 59 39 LEFTO .. 60 40 LENGTHO 60 ARexx User's Reference Manual iii 41 MAXO .. 60 42 MINO .. 60 43 OPENO .. 60 440VERLAYO 61 45 POSO 61 46 PRAGMAO 61 47 RANDOMO 62 48 RANDUO . 62 49 READCHO 62 50 READLNO 63 51 REMLIBO 63 52 REVERSEO . 63 53 RIGIITO 63 54 SEEKO .. 63 55 SETCLIPO 64 56 SIIOW() 64 57 SIGNO .. 64 58 SPACEO 64 59 STORAGEO 65 60 STRIPO .. 65 61 SUBSTRO 65 62 SUBWORDO 66 63 SYMBOLO 66 64 TIMEO ... 66 65 TRACEO .. 67 66 TRANSLATEO 67 67 TRIMO .. 67 68 UPPERO . 67 69 VALUEO ... 68 70 VERIFYO 68 71 WORDO ... 68 72 WORDINDEXO 68 73 WORDLENGTHO 68 74 WORDSO .. 69 75 WRITECIIO 69 76 WRITELNO 69 77 X2CO 69 78 XRANGEO . 69 Chapter 7. Tracing and Interrupts 71 1 Tracing Options . 71 2 Display Formatting. 72 1 Tracing Output . 72 2 Command Inhibition . 73 3 Interactive Tracing . 73 1 Error Processing .. 74 2 The External Tracing Flag 74 4 Interrupts . 74 iv Table of Contents Chapter 8. Parsing and Templates 77 1 Template Structure . 77 1 Template Objects . 78 2 The Scanning Process 78 2 Templates in Action 79 1 Parsing by Tokenization 79 2 Pattern Parsing . 80 3 Positional Markers 80 4 Multiple Templates 80 Chapter 9. The Resident Process 83 1 Command Utilities 83 1 HI. .. 83 2 RX 84 3 RXSET 84 4RXC 84 5 TCC. 84 6TCO 84 7 TE 84 8 TS 84 2 Resource Management 85 1 The Global Tracing Console 85 2 The Library List ..... 85 3 The Clip List . 86 Chapter 10. Interfacing to ARexx 89 1 Basic Structures . 90 2 Designing a Command Interface . 91 1 Receiving Command Messages 92 2 Result Fields . 92 3 Multiple Host Processes 92 3 Invoking ARexx Programs . 93 1 Message Packets 93 2 Command Invocations 94 3 Function Invocations . 95 4 Search Order . 95 5 Extension Fields 96 6 Interpreting the Result Fields 97 4 Communicating with the Resident Process . 97 1 Command (Action) Codes 97 2 Modifier Flags 99 3 Result Fields . 100 5 External Function Libraries 100 1 Design Considerations 100 2 Calling Convention 101 3 Parameter Conversion 101 4 Returned Values 101 6 Direct Manipulation of Data Structures 102 ARexx User's Reference Manual v ~-~- Appendix A. Error Messages . 103 Appendix B. Limits and Compatibility 109 1 Limits ............. 109 2 Compatibility . 109 Appendix C. The ARexx Systems Library · 111 1 Functional Groups . · 111 2 Library Functions .......... · 113 Appendix D. The ARexx Support Library 127 1 ALLOCMEMO 127 2 CLOSEPORTO 127 3 FREEMEMO 128 4 GETARGO .. · 128 5 GETPKTO .. 128 60PENPORTO 128 7 REPLYO ... 129 8 SHOWDIRO . 129 9 SHOWLISTO . 129 10 STATEFO 130 11 WAITPKTO · 130 Appendix E. Distribution Files 131 1 Directories ...... 131 1 The : C Directory . 131 2 The : INCLUDE Directory 131 3 The :LIBS Directory . 132 4 The : REXX Directory . 132 5 The :TOOLS Directory 132 6 Miscellaneous Files · 132 2 Listings of Header Files · 133 1 storage.h 133 2 rxslib.h · 139 3 rexxio.h · 142 4 errors.h · 144 Glossary. · 147 Index. · 151 vi Table of Contents Introduction Welcome to ARexx, an implementation of the REXX language for the Amiga computer. ARexx is a powerful programming tool, but one which by virtue of its clean syntax and sparse vocabulary is also easy to learn and easy to use. 1 Organization of this Document This document will attempt to fill the roles of User's Manual, Language Reference, and Programmer's Guide. The chapters that follow have been organized to provide a gentle introduction to the language. • Chapter 1, What is ARexx?, gives an overview of the ARexx language and its imple­ mentation on the Amiga. • Chapter 2, Getting Acquainted, tells how to install ARexx on your Amiga and presents several example programs to illustrate the features of the language. • Chapter 3, Elements of the Language, introduces the language structure and syntax. • Chapter 4, Instructions, describes the action statements of ARexx. • Chapter 5, Commands, describes the program statements used to communicate with external programs. • Chapter 6, Functions, explains how functions are called and documents the Built-In Function library. • Chapter 7, Tracing and Interrupts, describes the source-level debugging features useful for developing and testing p.rograms. • Chapter 8, Parsing and Templates, describes the instructions used to extract words or fields from strings. • Chapter 9, The Resident Process, describes the capabilities of the global communica­ tions and resources manager. • Chapter 10, Interfacing to ARexx, describes how to design and implement an interface between ARexx and an external program. • Appendix A, Error Messages, lists the error messages issued by the interpreter. • Appendix B, Limits and Compatibility, discusses the compatibility of ARexx with the language standard. • Appendix C, The ARexx Systems Library, documents the functions in the ARexx sys­ tems library. • Appendix D, The Support Library, documents the library of Amiga-specific functions. • Appendix E, Distribution Files, lists the files on the distribution disk. Finally, a Glossary and an Index are provided. 1 Using this Manual If you are new to the REXX language, or perhaps to programming itself, you should review chapters 1 through 4 and then play with ARexx by running some of the sample programs given in chapter 2.