ARexx User's Reference Manual The REXX Language for the Amiga ARexx User's Reference Manual Version 1.0 The REXX Language for the Amiga Copyright © 1987 William S. Hawes All Rights Reserved 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 Lattice 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 TgX using AmigaTgK, 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 Organization of this Document 1 Using this Manual .... 2 Typographic Conventions 2 Future Directions Chapter 1, What is ARexx? . 1 Language Features 2 ARexx on the Amiga .... 3 Further Information .... Chapter 2. Getting Acquainted 1 Installing ARexx 1 ARexx and WorkBench 2 Installation 3 Starting the Resident Process . . 4 Naming Conventions 5 The REXX : Directory 2 Program Examples Chapter 3. Elements of the Language 1 Format 2 Tokens 1 Comment Tokens . . . 2 Symbol Tokens .... 3 String Tokens 4 Operators 5 Special Character Tokens 3 Clauses 1 Null Clauses 2 Label Clauses 3 Assignment Clauses 4 Instruction Clauses 5 Command Clauses . 6 Clause Classification 4 Expressions 1 Symbol Resolution . . . . 2 Order of Evaluation . . . . 5 Numbers and Numeric Precision 1 Boolean Values 2 Numeric Precision 6 Operators 1 Arithmetic Operators . . . 2 Concatenation Operators . , 3 Comparison Operators . . . 4 Logical (Boolean) Operators 7 Stems and Compound Symbols . 1 . 1 . 2 . 2 . 2 . 3 . 3 . 4 . 4 . 5 . 5 . 5 . 5 . 6 . 6 . 6 . 7 11 11 11 11 11 12 12 13 14 14 14 14 15 15 15 16 16 16 17 17 17 18 18 20 20 21 21 ARexx User's Reference Manual v^napier o, Jtiiemeius ui Hie uaiiguage ^ct 3 Input and Output Chapter 4. Instructions 1 ADDRESS ............ 2 ARG 3 BREAK 4 CALL 5 DO 6 DROP 7 ECHO 9 END 10 EXIT 11 IF 12 INTERPRET 13 ITERATE 14 LEAVE 15 NOP 16 NUMERIC 17 OPTIONS 18 OTHERWISE 19 PARSE 1 Input Sources 2 Templates 20 PROCEDURE 21 PULL 22 PUSH 23 QUEUE 24 RETURN 25 SAY 26 SELECT 27 SHELL 28 SIGNAL 29 THEN 30 TRACE . 31 UPPER 32 WHEN Chapter 5, Commands 1 Command Clauses 2 The Host Address 3 The Command Interface ...... 4 Using Commands in Macro Programs . 5 Using ARexx with Command Shells 11 22 22 22 23 24 25 25 25 26 26 27 2o 28 28 29 29 29 30 30 31 31 31 32 32 33 33 34 35 35 36 37 37 38 38 38 38 39 40 40 41 43 43 44 44 45 45 46 Table of Contents Chapter 8. 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 ABBREVQ 51 2 ABSQ 51 3 ADDLIBQ 51 4 ADDRESSQ 51 5 ARGQ 52 6 B2CQ 52 7 BITANDQ 52 8 BITCHGQ 52 9 BITCLRQ 53 10 BITCOMPQ 53 11 BITORQ 53 12 BITSETQ 53 13 BITTSTQ 53 14 BITXORQ 54 15 C2BQ 54 16 C2DQ 54 17 C2XQ 54 18 CENTERQ or CENTREQ 55 19 CLOSEQ 55 20 COMPRESSQ , 55 21 COMPAREQ 55 22 COPIBSQ 55 23D2C0 56 24 DATATYPBQ . 56 25 DELSTRQ 56 26 DELWORDQ 57 27 EOFQ 57 28 ERRORTEXTQ 57 29 BXISTSQ 57 30 EXPORTQ 57 31 FREESPACEQ 58 32 GETCLIPQ 58 33 GETSPACEQ 58 34 HASHQ 58 35 IMPORTQ 59 36 INDEXQ 59 37 LNSERTQ 59 38 LASTPOSQ 59 39 LEFTQ 60 40 LENGTHQ 60 ARexx User's Reference Manual 41 MAXQ . 42 MINQ . 43 OPENQ . 44 OVERLAYQ 45 POSQ . . 46 PRAGMAQ 47 RANDOMQ 48 RANDUQ . 49 READCHQ 50 READLNQ 51 REMLIBQ 52 REVERSEQ 53 RIGHTQ . 54 SEEKQ . . 55 SETCLIPQ 56 SHOWQ . 57 SIGNQ . . 58 SPACEQ , 59 STORAGEQ . . 60 STRIPQ .... 61 SUBSTRQ . . . 62 SUBWORDQ . . 63 SYMBOLQ . . . 64 TIMEQ 65 TRACEQ .... 66 TRANSLATEQ . 67 TRIMQ 68 UPPERQ .... 69 VALUEQ .... 70 VERIFYQ . . . 71 WORDQ .... 72 WORDINDEXQ . 73 WORDLENGTHQ 74 WORDSQ .... 75 WRITECHQ . . 76 WRITELNQ . . 77 X2CQ 78 XRANGEQ . . . Chapter 7. Tracing and Interrupt 1 Tracing Options 2 Display Formatting 1 Tracing Output 2 Command Inhibition . . . 3 Interactive Tracing 1 Error Processing .... 2 The External Tracing Flag 4 Interrupts 60 60 60 61 61 61 62 62 62 63 63 63 63 63 64 64 64 64 65 65 65 66 66 66 67 67 67 67 68 68 68 68 68 69 69 69 69 69 71 71 72 72 73 73 74 74 74 Table of Contents Chapter 8. Parsing and Templates 1 Template Structure 1 Template Objects 2 The Scanning Process . . . , 2 Templates in Action 1 Parsing by Tokenization . . . 2 Pattern Parsing 3 Positional Markers 4 Multiple Templates Chapter 9. The Resident Process . 1 Command Utilities 1 HI 2 RX 3RXSET . . . 4 RXC 5TCC 6 TC0 7TE 8TS ..... 2 Resource Management . > . . . 1 The Global Tracing Console 2 The Library List 3 The Clip List Chapter 10. Interfacing to ARexx 1 Basic Structures 2 Designing a Command Interface . 1 Receiving Command Messages 2 Result Fields 3 Multiple Host Processes . . . 3 Invoking ARexx Programs 1 Message Packets . . 2 Command Invocations 3 Function Invocations . 4 Search Order .... 5 Extension Fields . . 6 Interpreting the Result Fields . 4 Communicating with the Resident 1 Command (Action) Codes 2 Modifier Flags 3 Result Fields 5 External Function Libraries 1 Design Considerations . 2 Calling Convention . . 3 Parameter Conversion . 4 Returned Values . . . Proce; 6 Direct Manipulation of Data Structures 77 77 78 78 79 79 80 80 80 83 83 83 84 84 84 84 84 84 84 85 85 85 86 89 90 91 92 92 92 93 93 94 95 95 96 97 97 97 99 100 100 100 101 101 101 102 ARexx User's Reference Manual Appendix A. Error Messages ' 103 Appendix B. Limits and Compatibility 109 1 Limits 109 2 Compatibility 109 Appendix C. The ARexx Systems Library Ill 1 Functional Groups Ill 2 Library Functions 113 Appendix D. The ARexx Support Library 127 1 ALLOCMEMQ 127 2 CLOSEPORTQ 127 3 FREEMEMQ 128 4 GETARGQ 128 5 GETPKTQ 128 6 OPENPORTQ 128 7 REPLYQ 129 8 SHOWDIRQ 129 9 SHOWLISTQ 129 10 STATEFQ 130 11 WAITPKTQ 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 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 programs. t 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 Syst...
Amiga789