Power-Programmierung

home *** CD-ROM | disk | FTP | other *** search

/ Power-Programmierung / CD1.mdf / rexx / dosrexx / rexxpc_1.doc < prev next >

Wrap

Text File | 1988-03-16 | 92.9 KB | 2,597 lines

REXXPC88 Programmer's Guide version 0.55 Sam Detweiler IBM North Central Marketing Detroit, MI 48343 (SDETWEIL at DETVMIC4) UPDATED - June 23rd, 1987 PRINTED - July 10th, 1987 ACKNOWLEDGEMENTS I want to acknowledge some of the people who have contributed to each version of REXXPC88. The original code and documentation for REXXPC88 was created by Derek Lieber. Additional code and documentation was supplied by Marvin Boswell. Code from Larry Margolis to implement the EXTLOAD function(s), and the AX=7 support code. Each and every user who has commented on both positive and negative items throughout the life of REXX88 and REXXPC88. Without your contributions we could not have brought you this tool. SUPPORT Support for REXXPC88 is provided by the current owner (Sam Detweiler). The package containing REXXPC88 is REXX88 PACKAGE and is available from PCTOOLS. There is a forum on IBMPC dedicated to REXXPC88 named REXX88 FORUM. Any praise, criticism or bug reports should be directed to REXX88 FORUM and not to any of the people named in this document. Problems with REXXPC88 will be acknowledged and handled in as timely a manner as pos- sible. Acknowledgements ii PREFACE * PREFACE TO RELEASE 0.55 * * * Changes for release 0.55 dated 6/23/87 * * 1. Correct stack error when external program uses STORE variable * interface and trace is on * 2. Corrected and improved performance of variable dictionary * management. * a. Fixed bug with variables with null strings as part of * compound variables * * Example: * did yield 0 instead of 1 * * n='';a.n='hello';say a.n == 'hello' * * b. Fixed bug with Mixed Case compound variables * * Example: * a.='none' * lower='a' * upper='A' * a.lower='lower case subscript' * a.upper='UPPER case subscript' * say 'a. = 'a. * say 'a.lower = 'a.lower * say 'a.upper = 'a.upper * * 3. Made resident version uninstallable * * NEW parameter ((/u to uninstall * * 2 new error messages * ∙ DET998 Can't uninstall resident version * * some non-conforming program is resident above REXXIBMr * ∙ DET999 Resident version does not support uninstall * * The currently installed REXXIBMr is downlevel and does not sup- * port the uninstall operation * * Note: requires new device driver level * 4. As resident version is now uninstallable, allowed resident extension * to be installed PRIOR to the actual REXX processor instead of as * currently required after. * * This assumes that the Resident extension code does INT 7Ch not CALL * [previous] for other functions (i.e. load/store/queue calls) * * Note: required new device driver level * 5. Added function to append x'1A' EOF to text file before token image * if one was not found. * 6. Fixed bug with recursion error * 7. Fixed bug if program name passed by environment not found * 8. Updated doc referencing VM REXX FIND function * 9. Added note about quoted literal string processing difference * * * * PREFACE TO RELEASE 0.54 * * * Changes for release 0.54 dated 6/5/87 * * 1. Add code for bi-lingual bat file support * 2. Add builtin function to identify resident or standalone version * REXXRES() = 1 if resident else = 0 if standalone * 3. Fix bug in stem variable direct retrieval Preface iii PREFACE TO RELEASE 0.53 Changes for release 0.53 dated 6/1/87 1. Fix pgm search algorithm when extension specified 2. Fix SIGNAL ON NOVALUE errors 3. Fix for FORMAT error 4. Fix for quoted function calls 'ARG' and external function extensions 5. Additional code for environment interface (tracing and errors) PREFACE TO RELEASE 0.52 Changes for release 0.52 dated 4/4/87 1. Added Support for PC/DOS 3.3 '@' batch file command prefix 2. Added PC/DOS 3.3 'CHCP' internal command to table 3. Fix for external queue interface 4. Updated doc in limitations section for nested PC/DOS batch files PREFACE TO RELEASE 0.51 Changes for release 0.51 dated 3/25/87 1. Fix for OTHERWISE on SELECT/WHEN/OTHERWISE PREFACE TO RELEASE 0.50 Changes for release 0.50 dated 3/24/87 1. Fix for problems introduced with 0.47 item 3. 2. Fix for TRUNC not formatting date correctly and hanging system 3. Added some of the environment interface code trace data support is not included at this point. 4. Added REXXIBMr installed process call int 7c, ax=9 if installed returns ax=AAAA else ax=FFFF 5. Fix for v 0.46 interupt fix. 6. Fix for SELECT/WHEN/OTHERWISE 7. Fix for Parse Pull and PULL truncating long queued strings 8. Added support for AX=7 extension loaded call 9. Added new function EXTLOAD supporting AX=7 call above. 10. Fix for DO WHILE 11. Fix for storage fragmentation with new read buffer size 12. Fix for storage loss within Do I= loops 13. Fix for STEM variables not clearing array 14. Fix for REXXSYS.SYS and EXT interaction 15. Fix for CONTROL-BREAK not being reset when SIGNAL ON HALT used and control-break or control-c pressed 16. Fix for extension returned strings not being freed PREFACE TO RELEASE 0.49 Changes for release 0.49 dated 2/21/87 1. fix for problems introduced with 0.47 item 3. Preface iv PREFACE TO RELEASE 0.48 Changes for release 0.48 dated 2/20/87 1. Fix for problems introduced with 0.47 for ANSI.SYS fix (item 2). 2. Fix for problems with error messages with out of storage on long return strings PREFACE TO RELEASE 0.47 Changes for release 0.47 dated 2/19/87 1. Fix for problems with HOSTSYS device driver(s) 2. Fix for problems with EGAXI and other ANSI replacements 3. Fix for appended space on DOS commands - standalone version 4. Add support for variable name on END statements in controlled do loops 5. Fix for command parsing with redirection or pipe chanracters 6. Added code to support reads of longer than 132 bytes default = 256 new parm allows any size (( nnnnR 7. Fix for external queue interface with messages queued to PUSH/PULL queue running out of storage 8. Remove string length restriction for STORE function Variable name length remains at 127 max 9. Removed string length restriction for strings returned from enten- sions 10. Added new parms to new ENVIRONMENT control block to facilitate true subcommand environment 11. REXXSYS.SYS fix for some environments (partial batch file line re-execution) PREFACE TO RELEASE 0.46 Changes for release 0.46 dated 2/2/87 1. Fix for subcommand environment not restoring registers 2. Fix for incorrect message on numeric overflow 3. Fix for large programs crashing system with resident version 4. Fix for CONTROL-BREAK/C not being reset with standalone version 5. Fix for Secondary call via interpret looping REXXSYS.SYS change 1. Correction for some environments PREFACE TO RELEASE 0.45 Changes for release 0.45 dated 1/13/87 1. Fix for command search when drive or path specified 2. Compile no longer changes files date or time 3. Trace output fixes DO loop repetition now displayed PREFACE TO RELEASE 0.44 Changes for release 0.44 dated 1/12/87 1. Fix for read file problems 2. Addition of Critical Error handling on file I/O functions 3. Addition of auto compile function Preface v PREFACE TO RELEASE 0.43 Changes for release 0.43 dated 1/11/87 1. Fix for storage problem in DO I= loops 2. Fix for INTERPRET instruction error PREFACE TO RELEASE 0.42 Changes for release 0.42 dated 1/7/87 1. Fix for equal compare operator (=) 2. Fix for EXIT or RETURN within INTERPRET instruction stream PREFACE TO RELEASE 0.41 Changes to release 0.41 dated 1/6/87 1. Fix for ARG OPTIONS or other keyword 2. Fix for SIGNAL xxx, dropped to base level of program rather than current routine as VM REXX 3. Fix for external interface to stop function for resident version 4. Fix for CONTROL-BREAK and CONTROL-C crashing system 5. Fix for write to new file 6. Additional of additional word on initialize call dw 1 REXX processor will search path for rexx program of appro- priate name before returning command to caller This is really any non-zero value (not just 1) dw 0 all commands will be passed to caller for processing imme- diately PREFACE TO RELEASE 0.40 This is a major function upgrade to the REXXPC88 package. The major changes are: ∙ Floating Point Support, including true Divide and Power operators ∙ More Built-in Functions for Floating Point ∙ Fixes for CONTROL-BREAK and CONTROL-C handling ∙ Fixes for Command line parsing ∙ Addition of Elapsed Time functions TIME('E') and TIME('R') ∙ Addition of RANDOM() function ∙ Addition of SIGNAL ON/OFF [HALT|SYNTAX|NOVALUE] The storage size used for the resident version is approx 77k in default work pool size (14k) vs REXX88r + REXXFUNS at 71k with a default work pool size of 24k. Preface vi TABLE OF CONTENTS Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Execution a REXXPC88 program . . . . . . . . . . . . . . . . . . . . 2 Syntactic elements . . . . . . . . . . . . . . . . . . . . . . . . . 4 Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 Symbols. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 Strings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Words. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Notes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Expressions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 Terms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 Operators. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 Arithmetic operators . . . . . . . . . . . . . . . . . . . . . . . 27 Comparison operators . . . . . . . . . . . . . . . . . . . . . . . 27 Logical operators. . . . . . . . . . . . . . . . . . . . . . . . . 28 String operators . . . . . . . . . . . . . . . . . . . . . . . . . 28 Operator precedence. . . . . . . . . . . . . . . . . . . . . . . . . 29 Notes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 Compound variables . . . . . . . . . . . . . . . . . . . . . . . . . 31 Procedures and Functions . . . . . . . . . . . . . . . . . . . . . . 32 Argument passing and name hiding . . . . . . . . . . . . . . . . . . 32 Return values. . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Built-in routines. . . . . . . . . . . . . . . . . . . . . . . . . . 33 General purpose routines . . . . . . . . . . . . . . . . . . . . . 33 File management routines . . . . . . . . . . . . . . . . . . . . . 48 The Parse Instruction. . . . . . . . . . . . . . . . . . . . . . . . 51 Simple template. . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Template with patterns . . . . . . . . . . . . . . . . . . . . . . . 52 Template with absolute column positions. . . . . . . . . . . . . . . 52 Template with relative column positions. . . . . . . . . . . . . . . 52 Template with variables as specifications. . . . . . . . . . . . . . 52 Further examples . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Appendix A. Debugging. . . . . . . . . . . . . . . . . . . . . . . . 54 Appendix B. Special files. . . . . . . . . . . . . . . . . . . . . . 56 Appendix C. Special variables. . . . . . . . . . . . . . . . . . . . 57 The special variable "result". . . . . . . . . . . . . . . . . . . . 57 The special variable "rc". . . . . . . . . . . . . . . . . . . . . . 57 Appendix D. Installation and Use . . . . . . . . . . . . . . . . . . 58 The Choices. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 Which version is for you?. . . . . . . . . . . . . . . . . . . . . . 58 Characteristics of Resident Version. . . . . . . . . . . . . . . . 58 Characteristics of Standalone Version. . . . . . . . . . . . . . . 58 * Bi-Lingual Batch File Support. . . . . . . . . . . . . . . . . . . . 58 The Distribution Diskette. . . . . . . . . . . . . . . . . . . . . . 59 Installing the resident version. . . . . . . . . . . . . . . . . . . 59 Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 Appendix E. External Program Interfaces. . . . . . . . . . . . . . . 61 User program invocation of the interpreter . . . . . . . . . . . . . 61 Initialization call. . . . . . . . . . . . . . . . . . . . . . . . 61 Values taken:. . . . . . . . . . . . . . . . . . . . . . . . . . 61 Environment Service routine parameters and return codes. . . . . . 62 Example Environment control block in MASM. . . . . . . . . . . . . 65 Values returned: . . . . . . . . . . . . . . . . . . . . . . . . 66 Register use:. . . . . . . . . . . . . . . . . . . . . . . . . . 66 Interpretation call. . . . . . . . . . . . . . . . . . . . . . . . 67 Values taken . . . . . . . . . . . . . . . . . . . . . . . . . . 67 Values returned: . . . . . . . . . . . . . . . . . . . . . . . . 67 Register use:. . . . . . . . . . . . . . . . . . . . . . . . . . 67 Table of Contents vii Termination call . . . . . . . . . . . . . . . . . . . . . . . . . 67 Values taken:. . . . . . . . . . . . . . . . . . . . . . . . . . 67 Values returned: . . . . . . . . . . . . . . . . . . . . . . . . 67 Load call. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 Values taken:. . . . . . . . . . . . . . . . . . . . . . . . . . 67 Values returned: . . . . . . . . . . . . . . . . . . . . . . . . 68 Register use:. . . . . . . . . . . . . . . . . . . . . . . . . . 68 Store call . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 Values taken:. . . . . . . . . . . . . . . . . . . . . . . . . . 68 Values returned: . . . . . . . . . . . . . . . . . . . . . . . . 68 Register use:. . . . . . . . . . . . . . . . . . . . . . . . . . 68 REXXPC88 invocation of user written Extensions . . . . . . . . . . . 68 Values passed in . . . . . . . . . . . . . . . . . . . . . . . . 69 Values passed out. . . . . . . . . . . . . . . . . . . . . . . . 69 Register use . . . . . . . . . . . . . . . . . . . . . . . . . . 69 Stack use. . . . . . . . . . . . . . . . . . . . . . . . . . . 69 Queue call . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 Values taken:. . . . . . . . . . . . . . . . . . . . . . . . . . 69 Values Returned: . . . . . . . . . . . . . . . . . . . . . . . . 70 Register use:. . . . . . . . . . . . . . . . . . . . . . . . . . 70 Loaded call. . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 Values taken:. . . . . . . . . . . . . . . . . . . . . . . . . . 70 Values returned: . . . . . . . . . . . . . . . . . . . . . . . . 70 Register use:. . . . . . . . . . . . . . . . . . . . . . . . . . 70 Reserved call. . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Values taken:. . . . . . . . . . . . . . . . . . . . . . . . . . 71 Values returned: . . . . . . . . . . . . . . . . . . . . . . . . 71 Installed call . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Values taken:. . . . . . . . . . . . . . . . . . . . . . . . . . 71 Values returned: . . . . . . . . . . . . . . . . . . . . . . . . 71 * Uninstall resident version . . . . . . . . . . . . . . . . . . . . 71 * Values taken:. . . . . . . . . . . . . . . . . . . . . . . . . . 71 * Values returned: . . . . . . . . . . . . . . . . . . . . . . . . 71 Appendix F. REXXPC88 vs. REXX370 . . . . . . . . . . . . . . . . . . 72 Missing Features . . . . . . . . . . . . . . . . . . . . . . . . . 72 Added Features . . . . . . . . . . . . . . . . . . . . . . . . . . 72 Appendix G. Bugs and Limitations . . . . . . . . . . . . . . . . . . 73 Appendix H. Sample Program . . . . . . . . . . . . . . . . . . . . . 74 Appendix I. Syntax Diagrams. . . . . . . . . . . . . . . . . . . . . 76 Appendix J. Keywords . . . . . . . . . . . . . . . . . . . . . . . . 78 Appendix K. Error messages . . . . . . . . . . . . . . . . . . . . . 79 Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 Table of Contents viii INTRODUCTION REXXPC88 is a command interpreter for the IBM Personal Computer. It runs as an extension to the standard DOS command interpreter, COMMAND.COM, and accepts a program control language identical to (a subset of) the REXX language available on IBM mainframe computers (herein after referred to as REXX370). REXXPC88 programs have a filetype of ".BAT", the same as the standard batch file programs currently recognized by DOS, but are distinguished from standard batch file programs by the first character of the file, * which must be the slash of a "/* REXXPC88 comment */" or the header of a * bi-lingual program ":/". REXXPC88 programs may execute other REXXPC88 programs recursively (i.e. the programs may be nested) however standard DOS ".BAT" programs may not be nested since DOS doesn't allow it. REXXPC88 feature summary: 1. structured programming constructs, somewhat in the style of PL/I a. conditionals (if..else) b. blocks (do..end) c. loops (do..repetitor..end) d. functions and procedures, with arguments and local variables 2. typeless data (everything, including numbers, is a string) 3. string oriented expression evaluation (automatic concatenation of adjacent terms in expressions, undefined variables treated as li- terals rather than as errors) 4. A special instruction for parsing strings into component words or fields 5. a hierarchy for resolving function and procedure names a. user-defined functions and procedures (program labels) b. built-in functions and procedures c. external routines 1) other REXXPC88 programs 2) operating system commands 3) compiled programs 6. operation is transparent to DOS batch file executor Introduction 1 EXECUTING A REXXPC88 PROGRAM Command line syntax: [REXXIBM[r]] execname execargs [ rexxdelim [NNk] [NNf} [NNr] [c] [/u] ] where: REXXIBMr installs the resident version REXXIBM invokes the standalone version rexxdelim is "((" for DOS NNk means "use workspace of NN kbytes" NNf means "allow up to NN files open at once" NNr means "allow reads UP to NN bytes", the default is 256 * /u means uninstall previously installed copy of resident version. c means "compile" Notes: 1. On all but the first invocation of the resident version, the NNk op- tion is ignored. 2. On the first invocation of the resident version, the execname and execargs are ignored. 3. If NNf is not specified, at most 5 files can be open at once. 4. If NNk is not specified, a workspace size of 14k is allocated. 5. The maximum possible workspace is 64k. 6. There is a subtle difference between the resident and standalone versions concerning the NNr parameter. The resident version remembers the last use of NNr and the standalone version does not. * 7. ((/u is ONLY suported by REXXIBMR Note: These option characteristics are now treated correctly in upper as well as lower case. A REXXPC88 exec is executed by typing its name on the system command line followed by arguments to be passed to the exec followed by arguments to be passed to the REXXPC88 interpreter itself. The latter must be preceded by double left parentheses. If the standalone version of REXXPC88 is being used, the command line must be preceded by "REXXIBM". Arguments preceding the double left parentheses are passed to the REXXPC88 exec exactly as they appear on the command line. The other arguments are used to control the interpreter. If the argument following the (( is NOT a REXXPC88 parameter the entire command line will be passed on to the REXXPC88 program. Examples: REXXIBM foo arg1 arg2 arg3 ((40k 10f REXXIBM foo ((c REXXIBMr ((40k foo ((c REXXIBM foo ((format) * REXXIBMr ((/u ∙ The first example uses the standalone version of REXXIBM to execute the exec names f00 with an argument of 'arg1 arg2 arg3', using 40k for the interpreter's workspace and allowing up to 10 files open at once. ∙ The second example uses the standalone version of REXXIBM to compile the exec named foo. A 'compiled' exec will load much more quickly than an 'uncompiled' exec, especially if it is too large. ∙ The third example installs the REXXIBM interpreter as a resident DOS extension, allocating a 40k workspace and allowing up to 5 files open at once (the default). ∙ The fourth example uses the resident interpreter to compile the exec named foo. ∙ the fifth example uses the standalone interpreter to execute the exec named foo, passing '((format)' as the parameters. Executing a REXXPC88 Program 2 ∙ The sixth example attempts to uninstall the resident processor. REXXPC88 does not actually compile in the conventional sense of producing executable machine code; rather, it converts the program into a list of tokens that can be quickly loaded and interpreted the next time the pro- gram is invoked. The "tokenized" version of the program is simply ap- pended to the source text after the end of file mark, where it is invisible to system programs such as text editors and the 'type' command, but where it can be found by REXXPC88 the next time the program needs to * be executed. If an end of file mark, x'1A' is not found one is appended * before the tokenized image is appended. The program may be "de-tokenized" by simply editing it (since well behaved DOS editors don't read past the end of file mark). You can expect large REXXPC88 programs to load about 10 times faster if they have been "compiled" using the ((c option. Executing a REXXPC88 Program 3 SYNTACTIC ELEMENTS A REXXPC88 program is composed of comments, symbols, strings, and words. These are called tokens and are the basic syntactic elements of the lan- guage. COMMENTS A comment is anything enclosed within the character pairs "/*" and "*/". Comments may be nested and may span any number of lines. Comments may appear between any two tokens of a REXXPC88 program. A comment is syn- tactically equivalent to a single blank. Examples: /* this is a single comment */ /* this * is * a /* nested */ comment */ SYMBOLS A symbol is a single character which is neither a letter nor a digit. The following symbols are part of the REXXPC88 language: ; semicolon : colon ( open paren ) close paren + plus - minus * asterisk / slash % percent = equal < less than > greater than | vertical bar (pc broken vertical bar) & ampersand . dot blank \ unary not (pc backslash) Syntactic elements 4 STRINGS A string is 1. a sequence of characters enclosed in quotes (a character string) 2. a sequence of decimal digits (a decimal string) 3. a sequence of hexidecimal digits enclosed in quotes and followed by "x" (a hex string) Examples: 'This is quoted text' 'This line contains ''embedded'' quoted text' '1234' 1234 '31323334'x '' A character string is a list formed by concatenating the characters as given, but without the surrounding quotes. A quote which appears twice in a row (as in the second example) is taken literally as part of the string. A decimal string is a list formed by concatenating the characters exactly as given. A hex string is a list formed by concatenating the characters whose values are equal to the hexidecimal codes specified within the quotes. The quotes themselves (as well as the trailing "x") are discarded. Each character is represented by two hexidecimal digits (0-9, a-f, A-F). Each hexidecimal string br represented by its two hexidecimal digits and no non-hexidecimal digits are allowed in the string except spaces (e.g. spaces are allowed between each pair of hex values). Notes on the preceding examples: 1. The strings in the third, fourth and fifth examples are all exactly equivalent (on a non-ASCII machine, this would not be true for the fifth string). 2. A string may be empty, as in the last example. 3. Either double or single quotes may be used to delimit strings. 4. The values of the strings in the preceding examples, as they would be printed by the say instruction are: This is quoted text This line contains 'embedded' quoted text 1234 1234 1234 Observe that saying the empty string prints 0 characters. WORDS A word is any sequence of letters or digits. The first character must be a letter. Examples: x xyz REXXIBM aMixedCaseWord Words may be used as names of variables, as names of functions or proce- dures, as REXXPC88 language keywords, or as implicit literals (con- stants). The latter is the default if none of the others apply (more on this later). Syntactic elements 5 A compound word is a sequence of words separated by dots. The first word in such a sequence is called the stem. The remaining words are called subscripts. Examples: foo. /* a stem */ foo.1.2 /* a compound word */ foo.this.that /* another compound word */ foo..bar /* still another */ Compound words may be used as names of variables and to perform indexing and associative lookup operations (See "Compound variables" on page 31). Syntactic elements 6 INSTRUCTIONS ┌───────────────────────────────────────────────────────────────────────┐ │ expression [ ; ] │ └───────────────────────────────────────────────────────────────────────┘ The expression is evaluated and passed to the operating system (as a string) for execution as a command or program. The special variable "rc" is assigned the exit code returned by the com- mand that was executed. This variable may be examined to test for the successful completion of the command. See "Appendix C. Special variables" on page 57. ┌────────────────────────────────────────────────────────────────────────┐ │ name = expression [ ; ] │ └────────────────────────────────────────────────────────────────────────┘ The expression on the right is evaluated and assigned to the variable named on the left. If the variable does not exist, it is created. If the variable already exists, its old value is discarded and replaced by the new value. The variable name appearing on the left may be spelled in either upper, lower, or mixed case, all of which refer to the same variable. ┌───────────────────────────────────────────────────────────────────────┐ │ name : │ └───────────────────────────────────────────────────────────────────────┘ This instruction marks the start of a user-defined procedure or function, but is otherwise a no-op. Name is a label that may serve as the target of a procedure call or function reference from elsewhere in the program. Note that a semicolon need not follow a label. The colon alone suffices. The label may be spelled in either upper, lower, or mixed case, all of which are equivalent. ┌───────────────────────────────────────────────────────────────────────┐ │ ADDRESS [environment [expression] │ [VALUE] expression ] ; │ └───────────────────────────────────────────────────────────────────────┘ The ADDRESS instruction is used to affect a temporary or permanent change to the destination of commands. Commands are strings sent to an external environment, and may be sent by clauses of just an expression, as well as by the ADDRESS instruction. To send a single command to a specified environment, an environment name followed by an expression is given. The expression is evaluated, and the resulting command string is submitted to the given environment. After execution of the command the previously selected environment will be un- changed. Example: address DOS 'DIR MOV1.ALL' would send the command 'DIR MOV1.ALL" to the environment called DOS. The special variable RC is set, just as it would be for other commands. Errors and failures in commands executed this way are trapped or traced as usual. If only an environment name is specified, a new environment for commands is selected. All following commands will be routed to the new command environment, until the next ADDRESS instruction is executed. The previ- ously selected environment is saved. Example: address CMS /* Send following command to CMS */ 'STATE PROFILE EXEC' if rc=0 then 'COPY PROFILE EXEC a TEMP = =' address 'XEDIT' /* and now all commands to XEDIT */ Instructions 7 Similarly, the VALUE form may be used to select a new environment - here the expression (which of course may be simply a reference to a variable) is evaluated, and the result forms the name of the new environment. The sub-keyword VALUE may be omitted if the expression does not begin with a symbol or literal string (i.e., if it starts with a special character, such as an operator or parenthesis). If ADDRESS is specified without either an environment name or an ex- pression, then commands will be routed back to the environment that was selected before the previous lasting change on environment was made (and the current environment name is saved). Repeated execution of just "AD- DRESS" will therefore switch the command destination between two alter- native environments. The two environment names maintained by REXXPC88 are automatically saved across subroutine and internal function calls. See the CALL instruction for more details. The current ADDRESS setting may be retrieved using the ADDRESS built-in function. ┌───────────────────────────────────────────────────────────────────────┐ │ ARG [ template ] [ ; ] │ └───────────────────────────────────────────────────────────────────────┘ ARG is used to retrieve the argument string or strings provided to a program or internal routine and put them into variables. It is just a shorter form of the instruction PARSE UPPER ARG [template]; Unless a subroutine or internal function is being executed, the strings passed as parameters to the program will be translated to upper case and then parsed into variables according to the rules described in the section on parsing. Use the PARSE ARG instruction if upper case translation is not desired. If a subroutine or internal function is being executed, then the data used will be the argument string(s) passed to the routine. The ARG (and PARSE ARG) instructions may be executed repeatedly (typically with different templates) and will always parse the same current data. There are no restrictions on the length or content of the data parsed except those imposed by the caller. In the case of a subroutine or internal function, multiple arguments may be parsed in a single instruction by placing a comma between the parse templates. Each argument will be parsed according to the template in that position. Note: ALL variables in ALL templates will be assigned values even if the argument does not exist. In this case the variables in the effected tem- plate will be assigned the NULL string ''. call x '1 2 3 4','5 6 7 8','this is a test' in x use the PARSE ARG instruction as follows: parse arg a1 b1 c1 d1 , a2 b2 c2 d3 , a3 b3 c3 d3 , x1 x2 [;] The variables will be assigned values as follows: a1 '1' b1 '2' c1 '3' d1 '4' a2 '5' b2 '6' c2 '7' d2 '8' a3 'this' b3 'is' c3 'a' d3 'test' x '' Instructions 8 Note: The parameters to a REXXPC88 program are treated as a single string, and as such are only ONE argument. ┌───────────────────────────────────────────────────────────────────────┐ │ CALL name [expression] [,expression]]... [ ; ] │ └───────────────────────────────────────────────────────────────────────┘ CALL is used to invoke a routine. The routine may be an internal routine, an external routine or a built-in function. It may optionally return a result, and is functionally identical to the clause result=name([expression] [,[expression]] ...); except that the variable RESULT will become uninitialized if no result is returned by the routine invoked. The name given in the CALL instruction must be a symbol, which is treated literally, or a literal string. If a literal string is used for the name (that is, the name is specified in quotes) the search for internal labels is bypassed and only a built-in function or an external routine will be invoked. Note that the names of built-in functions are in upper case, hence the name in the literal string MUST be in upper case for the search to succeed. The expressions following the name are evaluated in order from left to right, and for the argument string(s) during execution of the routine. The ARG and PARSE ARG instructions (and the ARG built-in function) will access these string(s) rather than any active previously, until control returns to the CALL instruction. Expressions may be omitted, if appropri- ate, by including "extra" commas. The CALL then causes a branch to the routine called name using exactly the same mechanism as function calls. Therefore the CALL instruction may be used to invoke internal routines, external routines and programs, or even built-in functions. The order of search for these routines is de- scribed below. Internal (Unless the routine name is specified in quotes.) Internal routines are sequences of REXXPC88 instructions inside the same program, which starts at the label that matches the symbol fol- lowing the keyword CALL. The RETURN instruction is used to complete execution of the routine. Built-in These are routines defined as part of the language. Most are usually called as functions, and all return a string that con- tains the result of the routine. External It is usually possible to write or make use of routines that are external to a program. These routines may be written in any language (including REXXPC88) which supports the system de- pendent interfaces used by the REXXPC88 language processor to invoke them. A REXXPC88 program may be invoked as a subroutine by the CALL instruction, and in this case may be passed more than one argument string. These may be retrieved by using the ARG or PARSE ARG instructions, or the ARG built-in function. Note: Only REXXPC88 programs are currently supported. During execution of an internal routine, all variables previously known are normally accessable. However, the Procedure instruction may be used to set up a local variables environment to protect the subroutine and caller from each other. The EXPOSE option on the PROCEDURE instruction may further be used to expose selected variables to a routine. Eventually the subroutine should execute a RETURN instruction, and at that point, control will return to the original CALL instruction for com- pletion. If the RETURN instruction specified an expression, then the variable RESULT will be set to the value of that expression. Otherwise the variable RESULT is dropped (becomes uninitialized). Internal routines may include calls to other internal routines. If a routine calls itself (either directly, or indirectly via one or more other routines), this is termed a recursive call. Note: The limit of CALL nesting is 70 for this version of REXXPC88. Instructions 9 During internal routine (and function) execution the following pieces of information are automatically saved and are then restored upon return from the routine: ∙ The status of DO loops and other structures. ∙ Trace settings. Once a subroutine has been debugged, you may insert a "TRACE Off" (or other appropriate setting) instruction at the beginning of it, and this will not affect the tracing of the caller. Conversely, if you only wish to debug a subroutine, you could insert a "TRACE Results" instruction at the start - tracing will automatically be restored to the conditions at entry (for example, "Off") upon return. Interactive tracing status is included in the saved setting. See "Procedures and Functions" on page 32 for details on the workings of a procedure call. ┌───────────────────────────────────────────────────────────────────────┐ │ DO [ repetitor ] [ conditional ][ ; ] │ │ [ instructionlist ] │ │ END [ symbol ] [ ; ] │ │ │ │ Where repetitor is one of: │ │ │ │ name = expr [TO exprt] [BY exprb] (FOR exprf] │ │ │ │ exprr │ │ │ │ FOREVER │ │ │ │ and conditional is either of: │ │ │ │ WHILE exprw │ │ │ │ UNTIL expru │ │ │ │ and instructionlist │ │ │ │ is any sequence of instructions. │ │ │ └───────────────────────────────────────────────────────────────────────┘ The DO instruction is used to group instructions together and optionally to execute them repetitively. During repetitive execution a control var- iable, name, may be stepped through a series of values. Syntax notes: ∙ exprr, expri, exprb, exprt and exprf may be any expression that evaluates to a number. exprr and exprf are further restricted to re- sult in a non-negative whole number. ∙ exprw or expru may be any expression that evaluates to a '1' or '0'. ∙ the TO, BY and FOR phrases may be in any order and will be evaluated in the order they are written. ∙ any instruction is allowed in instructionlist, including any of the more complex constructs such as IF, SELECT, or the DO instruction itself. ∙ the sub-keywords TO, BY, FOR, FOREVER, WHILE, and UNTIL are reserved within a DO instruction, in that they cannot name variables in the expression(s). ∙ exprb defaults to '1', if relevant. DO is the most complex of the REXXPC88 instructions. It can be treated as a simple grouping construct, a pre-determined repetitive loop, and as a loop with a bounding condition that is recalculated on each iteration. Simple DO group If neither repetitor nor conditional is given, then the construct merely groups a number of instructions together; these are executed once. Instructions 10 Example: if a=3 then do a=a+2 say 'Smile!' end If either repetitor or conditional is given, the group of instructions forms a repetitive DO loop, and the instruction list is executed according to the repetitor phrase, optionally modified by the conditional phrase. Simple repetitive loops If the repetitor is FOREVER (or if no repetitor is given, but there is a conditional, see below), then the instruction list will nominally be ex- ecuted "forever", that is until the condition is satisfied or a LEAVE, SIGNAL, EXIT, or RETURN instruction is executed. Example: do forever say 'Go caving!' if random(5)=1 then leave end Alternatively, in the numeric form or repetitor, the expression exprr is evaluated immediately (and must result in a whole number that is 0 or positive), and the loop is then executed that many times. Example: do 5 say 'Hello' end Note that, similar to the destinction between a command and an assignment, if the first token of exprr is a symbol and the second token is an "=", then the controlled form of repetitor is expected. Controlled repetitive loops The controlled form specifies a control variable, name, which is given an initial value (the result of expri) before the first execution of the instruction list. The variable is then stepped (by adding the result of exprb before the second and subsequent times that the instruction list is executed. The instruction list is executed repeatedly while the end condition (de- termined by the result of exprt) is not met. If exprb is positive, then the loop will be terminated when name is greater than exprt. The expressions expri, exprt, and exprb must result in numbers. They are evaluated only once, before the loop begins and before the control vari- able is set to its initial value. The default value for exprb is 1. If no exprt is given then the loop will execute indefinitely unless it is terminated by some other condition. Example: do i=3 to -2 by -1 say i end /* would type out: 3,2,1,0,-1,-2 */ Note that the numbers do not have to be whole numbers. Instructions 11 Example: x=0.3 do y=x to x+4 by 0.7 say y end /* would type out: 0.3, 1.0, 1.7 */ The control variable may be altered within the loop, and this may affect the interation of the loop. Altering the value of the control variable is normally considered to be suspect programming practice, though it may be appropriate in certain circumstances. Note that the end condition is tested at the start of each iteration (and after the control variable is stepped, on the second and subsequent it- ations). It is therefore possible for the instruction list to be skipped entirely if the end condition is met immediately. Note also that the control variable is referenced by name. If, for exam- ple, the compound name "A.I" was used for the control variable, then al- tering "I" within the loop will cause a change in the control variable. The execution of a controlled loop may further be bounded by a FOR phrase. In this case, exprf must be given and must evaluate to a non-negative whole number. This acts just like the repetition count in a simple re- petitive loop, and sets a limit to the number of iterations around the loop if it is not terminated by some other condition. Like the TO and BY expressions it is evaluated once only, when the DO instruction is first executed and before the control variable is given its initial value. Like the TO condition, the FOR count is checked at the start of each iteration. Example: do y=0.3 to 4.3 by 0.7 for 3 say y end /* would type out: 0.3, 1.0, 1.7 */ In a controlled loop, the symbol describing the control variable may be specified on the END clause. REXXPC88 will then check that the symbol exactly matches the symbol naming the control variable in the DO clause (in all respects except case). Note that no substitution for compound variables is carried out. If the symbol does not match, then the program is in error - this enables the nesting of loops to be checked automat- ically. Example: do K=1 to 10 ... ... end k /* checks that this is the END for K loop */ Note: The values taken by the control variable may be affected by the NUMERIC settings, since normal REXXPC88 arithmetic rules apply to the computation of the stepping of the control variable. Conditional phrases (WHILE and UNTIL) Any of the forms of repetitor (none, FOREVER, numeric or controlled) can be followed by a conditional phrase which may cause termination of the loop. If WHILE or UNTIL is specified, the expression following it is evaluated each time around the loop using the latest values of all vari- ables (and must evaluate to either '0' or '1'), and the instruction list will be repeatedly executed either while the results is '1', or until the result is '1'. For a "WHILE" loop, the condition is evaluated before the instruction list is executed, and for an "UNTIL" loop the condition is evaluated after the instruction list is executed - before the control variable has been stepped. Instructions 12 Example: do i=1 to 10 by 2 until i>6 say i end /* would type out: 1, 3, 5, 7 */ Note that the execution of repetitive loops may also be modified by using the LEAVE or ITERATE instructions. ┌───────────────────────────────────────────────────────────────────────┐ │ DROP namelist [ ; ] │ └───────────────────────────────────────────────────────────────────────┘ This instruction causes subsequent references to the variables named in namelist to return the name of the variable rather than the value of the variable (i.e. the variables become uninitialized). This instruction frees the storage used by the named variables and makes it available for re-use by other variables. If any of the variables in namelist are stems, then all variables with the same stem are dropped (including variables that may be shared with other procedures via the EXPOSE instruction). It is not an error to specify a name more than once, or to DROP a variable that is not known. For example: proc1: list. = '???' list.1 = 'foo' list.2 = 'bar' call proc2 return /* share 'list.' with proc1 */ proc2: procedure expose list say list.1 list.2 /* says 'foo bar' */ drop list.1 say list.1 list.2 /* says '??? bar' */ drop list. say list.1 list.2 /* says 'list.1 list.2' */ return ┌───────────────────────────────────────────────────────────────────────┐ │ EXIT [ expression ] [ ; ] │ └───────────────────────────────────────────────────────────────────────┘ EXIT is used to unconditionally leave a program, and optionally return a character string to the caller. The program is terminated immediately, even if an internal routine is currently being executed. If no internal routine is active, then RETURN and EXIT are identical in function. If an expression is given, it is evaluated and the string resulting from the evaluation is then passed back to the caller when the program termi- nates. If no expression is given, no character string is passed back to the caller. Note: "Running off the end" of a program is always equivalent to the in- struction "EXIT;", in that it terminates the whole program and returns no result string. Note: This is a change from previous releases of REXXPC88. Also, for PC/DOS the string resulting from expression is lost. ┌───────────────────────────────────────────────────────────────────────┐ │ IF expression [ ; ] THEN [ ; ] instruction1 [ ; ] │ │ [ ELSE [ ; ] instruction2 ] [ ; ] │ └───────────────────────────────────────────────────────────────────────┘ The IF instruction is used to conditionally execute an instruction or group of instructions. It can also be used to select between two alter- natives. Instructions 13 The expression is evaluated and must result in '0' or '1'. If the result was '1' then the instruction after the THEN is executed. If the result was '0' and an ELSE was given, then the instruction after the ELSE is executed. Example: if answer='YES' then say 'OK!' else say 'Why not?' Remember that if the ELSE clause is on the same line as the last clause of the THEN part, then you need a semicolon to terminate the clause. Example: if answer='YES' then say 'OK!'; else say 'Why not?' The ELSE binds to the nearest IF at the same level. This means that any IF that is used as the instruction following the THEN in an IF construct that has an ELSE clause, must itself have an ELSE clause (which may be followed by the dummy instruction, NOP). Example: if answer='YES' then if name='FRED' then say 'OK,Fred.' else say 'OK.' else say 'Why not?' Note: ∙ An instruction includes all the more complex constructions such as DO groups and SELECT groups, as well as simpler ones and the IF in- struction itself. A null clause is not an instruction, so putting an extra semicolon after a WHEN clause is not equivalent to putting a dummy instruction (as it would be in PL/I). The NOP instruction is provided for this purpose. ∙ A variable called THEN cannot be used within expression, because the keyword THEN is treated differently, in that it need not start a clause. This allows then expression on the WHEN clause to be termi- nated by the THEN, without a ; (delimiter) being required - this is consistent with the treatment of THEN following an IF clause. ┌──────────────────────────────────────────────────────────────────────┐ │ INTERPRET expression [ ; ] │ └──────────────────────────────────────────────────────────────────────┘ INTERPRET is used to execute instructions that have been built dynamically by evaluating an expression (in contrast to those that already exist in the program). The expression is evaluated, and will be executed (interpreted) just as though the result string were a line inserted in the program (and brack- eted by a DO; and an END;). Any instructions (including INTERPRET instructions) are allowed, but note that construction such as DO...END and SELECT...END must be complete. For example, a string of instructions being interpreted cannot contain a LEAVE or ITERATE instruction (valid only within a repetitive DO loop) unless it also contains the whole repetitive DO...END construct. Label clauses are not permitted in the interpreted character string. A semicolon is implied at the end of the expression during execution, as a service to the user. Example: data='FRED' interpret data '= 4' /* Will a) build the string "FRED = 4" */ /* b) execute "FRED = 4" */ /* Thus the variable FRED will be set to '4' */ Instructions 14 Note: If you are new to the concept of the INTERPRET instruction and are getting results that you do not understand, then you may find that exe- cuting it with "TRACE R" or "TRACE I" set is useful. Example: The program: /* here we have a small program */ trace Intermediates name='Kitt' Indirect='name' Interpret 'say "Hello"' Indirect'"!"' when run gives the trace: *-* name='Kitt' >L> "Kitt" *-* Indirect='name' >L> "name" *-* Interpret 'say "Hello"' Indirect'"!"' >L> "say "Hello"" >V> "name" >O> "say "Hello" name" >L> ""!"" >O> "say "Hello" name"!"" *-* say "Hello" name"!" >L> "Hello" >V> "Kitt" >O> "Hello Kitt" >L> "!" >O> "Hello Kitt!" Hello Kitt! Here, as shown in the trace, two assignments set the variables used in the INTERPRET instruction. Execution of the INTERPRET instruction pro- ceeds in two stages. First the string to be interpreted is built up, using a literal string, a variable (INDIRECT), and another literal string. The resulting pure character string is then interpreted, just as though it were actually part of the original program. Since it is a new clause, it is traced as such (the second "*-*" trace flag under the interpret in- struction) and is then executed. Again a literal string is concatenated to the value of the variable (NAME) and another literal string, and the final result ("Hello Kitt!") is then displayed. For many purposes, the VALUE function may be used instead of the INTERPRET instruction. The last example INTERPRET instruction could have been re- placed by: say "Hello" value(indirect)"!" INTERPRET is usually required only in special cases such as when more than one instruction is to be interpreted at once, or when an expression is to be evaluated dynamically. ┌───────────────────────────────────────────────────────────────────────┐ │ ITERATE [ name ] [ ; ] │ └───────────────────────────────────────────────────────────────────────┘ ITERATE alters the flow within a repetitive DO loop (that is, any DO construct other than the plain DO). Execution of the group of instructions stops, and control is passed to the DO instruction just as though the bottom of the group of instructions had been reached. The UNTIL expression (if any) is tested, the control variable (if any) is incremented and tested, and the WHILE expression (if any) is tested. If these tests indicate that the conditions of the loop have not yet been satisfied, the group of instructions is executed again (iterated), beginning at the top. If name is not specified, ITERATE will step the innermost active repeti- tive loop. If name is specified, it must be the name of the control var- Instructions 15 iable of a currently active loop (which may be the innermost), and this is the loop that is stepped. Any active loops inside the one selected for iteration are terminated (as though by a LEAVE instruction). Example: do i=1 to 4 if i=2 then iterate say i end /* would display the numbers: 1, 3, 4 */ Note: 1. The name, if specified, must match that on the DO instruction exactly. No substitution for compound variables is carried out when the com- parison is made. 2. A loop is active if it is currently being executed. If a subroutine is called during execution of the loop, the loop becomes inactive until the subroutine has returned. ITERATE cannot be used to step an inactive loop. 3. If more than one active loop uses the same control variable, the innermost loop will be the one selected by ITERATE. ┌───────────────────────────────────────────────────────────────────────┐ │ LEAVE [ name ] [ ; ] │ └───────────────────────────────────────────────────────────────────────┘ LEAVE causes immediate exit from one or more repetitive DO loops (i.e., any DO construct other than that with a plain DO). Execution of the instruction list is terminated, and control is passed to the instruction following the END clause, just as though the END clause had been encountered and the termination condition had been met normally, except that on exit the control variable (if any) will contain the value it had when the LEAVE instruction was executed. If no name is specified, then LEAVE will terminate the innermost active repetitive loop. If a name is specified, then it must be the name of the control variable of a currently active loop (which may be the innermost), and that loop (and any active loops inside it) is then terminated. Control then passes to the clause following the END that matches the DO clause of the selected loop. Example: do i=1 to 5 say i if i=3 then leave end /* would type out the numbers: 1, 2, 3 */ Note: 1. The name, if specified, must match that on the DO instruction exactly. No substitution for compound variables is carried out when the com- parison is made. 2. A loop is active if it is currently being executed. If a subroutine is called during execution of the loop, the loop becomes inactive until the subroutine has returned. LEAVE cannot be used to terminate an inactive loop. 3. If more than one active loop uses the same control variable, the innermost loop will be the one selected by LEAVE. ┌───────────────────────────────────────────────────────────────────────┐ │ NOP [ ; ] │ └───────────────────────────────────────────────────────────────────────┘ NOP is a dummy instruction that has no effect. It can be useful as the target of an ELSE, WHEN, or THEN clause. Instructions 16 Example: Select when a=b then nop /* do nothing */ when a>b then say 'A > B' otherwise say 'A < B' end Note: Putting an extra semicolon instead of the NOP would merely insert a null clause, which would just be ignored by REXXPC88. The second WHEN clause would then immediately follow the first, and hence would be treated as a syntax error. NOP is a true instruction, however, and is therefore a valid target for the WHEN clause. ┌───────────────────────────────────────────────────────────────────────┐ │ NUMERIC DIGITS [ expression ] [ ; ] │ │ NUMERIC FUZZ [ expression ] [ ; ] │ │ NUMERIC FORM [ SCIENTIFIC ] [ ; ] │ │ NUMERIC FORM [ ENGINEERING ] [ ; ] │ │ NUMERIC FORM [ [ VALUE ] expression ] [ ; ] │ └───────────────────────────────────────────────────────────────────────┘ The NUMERIC instruction is used to change the way in which arithmetic operations are carried out. The effects of this instruction are as follows: NUMERIC DIGITS controls the precision to which arithmetic operations will be computed. The expression (if specified) must evaluate to a positive whole number. If no expression is given then the de- fault value of 9 is used. The value used must be larger than the current FUZZ setting. Note: The implementation maximum is 9. Note that small values of NUMERIC DIGITS (for example, values less than 6) are generally only useful fore specialized appli- cations. The setting of NUMERIC DIGITS affects ALL computa- tions, so even the operation of loops may be affected by rounding if small values are used. The current setting of NUMERIC DIGITS may be retrieved with the DIGITS built-in function. NUMERIC FORM controls which form of exponential notation is to be used by REXXPC88. This may be either scientific (in which case only one, non-zero, digits will appear before the decimal point), or engineering (in which case the power of ten will always be a multiple of three). The default is scientific. The form is set either directly by the sub-keywords SCIENTIFIC or ENGINEERING, or is taken from the result of evaluating the expression following VALUE. The result in this case MUST be either 'SCIENTIFIC' or 'ENGINEERING'. The sub-keyword VALUE may be omitted if the expression does not begin with a symbol or a literal string (i.e., if it starts with a special charac- ter, such as an operator or parenthesis). The current setting of NUMERIC FORM may be retrieved with the FORM built-in function. NUMERIC FUZZ controls how many digits, at full precision, will be ignored during a numeric comparison operation. The expression (if specified) must result in a zero or positive whole number that must be less than the current DIGITS setting. If no expression is given then the default value of 0 is used. The effect of NUMERIC FUZZ is to temporarily reduce the value of NUMERIC DIGITS the NUMERIC FUZZ value during every numeric comparison operation, so that numbers are subtracted under a precision of DIGITS-FUZZ digits during the comparison and the result is then compared with 0. The current setting of NUMERIC FUZZ may be retrieved with the FUZZ built-in function. Instructions 17 Note: The three numeric settings are automatically saved across subroutine and internal function calls. ┌───────────────────────────────────────────────────────────────────────┐ │ OPTIONS expression [ ; ] │ └───────────────────────────────────────────────────────────────────────┘ The OPTIONS instruction is used to pass special requests to the language processor. There are no recognized options at this time. The result of the expression is ignored. This instruction is supplied as part of the 3.5 spec level support. ┌───────────────────────────────────────────────────────────────────────┐ │ PARSE [UPPER] SOURCE template [ ; ] │ │ PARSE [UPPER] VERSION template [ ; ] │ │ PARSE [UPPER] VALUE expression WITH template [ ; ] │ │ PARSE [UPPER] VAR name template [ ; ] │ │ PARSE [UPPER] ARG template [ ; ] │ │ PARSE [UPPER] PULL template [ ; ] │ │ PARSE [UPPER] LINEIN template [ ; ] │ └───────────────────────────────────────────────────────────────────────┘ The PARSE instruction is used to assign data (from various sources) to one or more variables according to the rules described in the section on parsing. If UPPER is specified, then any character strings to be parsed are first translated to upper case. Otherwise no translation takes place during the parsing. If no template is given, then no variables will be set but action will be taken to get the data ready for parsing if necessary. Thus for PARSE LINEIN and PARSE PULL a line will be removed from the appropriate char- acter stream or data queue, for PARSE VALUE the expression will be eval- uated, and for PARSE VAR the variable will be checked to ensure that it has a value. The following list describes the data used for each variant of the PARSE instruction. PARSE ARG The string(s) passed to the program, subroutine, or function as the input arguments are parsed. The argument string(s) to a REXXPC88 program may also be re- trieved or checked by using the ARG built-in function. PARSE LINEIN The next line from the default character input stream is parsed. PARSE LINEIN is a shorter form of the instruction PARSE VALUE LINEIN() WITH [template]; If no line is available, program execution will normally pause until a line is complete. Note that PARSE LINEIN should only be used when direct access to the character input stream is necessary. Normnal line-by-line dialogue should be carried out with the PULL or PARSE PULL instructions, to maintain general- ity and programmability. The number of lines available in the default character input stream may be found with the LINES built-in function. PARSE PULL The next string from the data queue is parsed. The queue is implementation defined, but will at least support the ability to save a series of arbitrary data strings of reasonable length. If the data queue is empty, lines will be read from the default character input stream, and the program will pause if necessary until a line is complete. Strings can be added to the head or tail of the queue using the PUSH and QUEUE instructions respectively. The queue may also be altered by other programs in the system, and may be usable as a means of communication between programs. Instructions 18 The number of lines currently in the data queue may be found with the QUEUED built-in function. PARSE SOURCE The character string parsed describes the source of the program being executed in some implementation dependent way. The string is fixed (will not change) during the execution of the program. The first word will identify the system or im- plementation under which execution is progressing, the second should state how the program was invoked, and the remainder is entirely implementation dependent but would normally include the full name of the program. For example, under IBM PC/DOS, the string contains the charac- ters "MSDOS", followed by either "COMMAND", "FUNCTION", or "SUBROUTINE" depending on whether the program was invoked as some kind of command (for example, a Batch file or editor macro), or from a function call in an expression, or via the CALL instruction. The two words are followed by the drive, path, and filename and extension of the program being executed. The string parsed might therefore look like this MSDOS COMMAND c:\tools\logon.bat or MSDOS FUNCTION c:\tools\cleanup.bat PARSE VALUE The expression is evaluated, and the resulting character string is parsed. If no expression is given then the null string is used. Note: WITH is a sub-keyword in this context and is reserved because it marks the end of the expression. It cannot be used as a symbol within the expression. PARSE VAR The value of the variable specified by name is parsed. The name must be a symbol that is valid as a variable name (i.e., it may not start with a period or digit). The variable itself is not changed unless it appears in the template, so that for example: parse var string word1 string will remove the first word from STRING and put it in the variable WORD1, and assign the remainder back to STRING. PARSE VERSION Information describing the language level and the date of the language processor is parsed. This consists of five words delimited by blanks. They are: 1. A word describing the language. The first four letters will be the characters "REXX", and the remainder may be used to identify a particular implementation or processor. This word may not include any periods. Note: For this release onward, the string will be "REXXPC88" 2. The language level description, for example, "3.50". For this release the level number is "0.55" 3. Three tokens describing the language processor release date in the foormat as the default for the DATE() function. For this release (0.55) the date string is "23 June 1987" Note: The template on the PARSE instruction may refer to more than one string only if PARSE ARG is specified. The other options process a single string and so a comma special operator may not be included in the template (except within a literal string pattern, i.e., in quotes). This rather complex instruction is described in a separate section (See "The Parse Instruction" on page 51). ┌────────────────────────────────────────────────────────────────────────┐ │ PROCEDURE [ EXPOSE namelist ] [ ; ] │ └────────────────────────────────────────────────────────────────────────┘ The PROCEDURE instruction may be used within an internal routine (sub- routine or function) to protect all the existing variables by making them unknown to following instructions. Selected variables may be exposed to the internal routine by using the EXPOSE option. On executing a RETURN instruction, the original variables environment is restored, and any variables used in the routine which were not exposed are dropped. Instructions 19 A routine need not include a PROCEDURE instruction, in which case the variables it is manipulating are those "owned" by the caller. If a PRO- CEDURE instruction is included, it MUST be the first instruction executed after the call or function invocation - that is, it must be the first instruction following the label. If the EXPOSE option is used, then the specified variables of the caller are exposed, so that any references to them (including setting them and dropping them) refer to the variables environment owned by the caller. Hence the values of existing variables are accessible, and any changes are persistent even on RETURN from the routine. The symbols in namelist must be valid variable names and are exposed in sequence from left to right. It is not an error to specify a name more than once, or to specify a name that has not been used as a variable by the caller. j=1; x.1='a' call somevars say j k m /* would type '1 7 M' */ exit somevars: procedure expose j k x.j say j k x.j /* would type '1 K a' */ k=7; m=3 /* note "M" is not exposed */ return Note that if the "X.J" in the expose list had been placed before the "J" then the caller's value of "J" would not have been visible at that time, so "X.1" would not have been exposed. An entire collection of variables may be exposed by specifying their stem in namelist. (The stem is that part of the name up to and including the first period). Again, the variables are exposed for all operations. Variables may be exposed through several generations of routines, if de- sired, by ensuring that they are included (exposed) on all intermediate PROCEDURE instructions. ┌────────────────────────────────────────────────────────────────────────┐ │ PULL [ template ] [ ; ] │ └────────────────────────────────────────────────────────────────────────┘ PULL is used to read a string from the data queue. It is just a short form of the instruction PARSE UPPER PULL [template] [;] The current head-of-queue will be read as one string. If no template is specified, no further action is taken (and the data is thus effectively discarded). Otherwise the data is translated to upper case and then parsed into variables according to the rules described in the section on parsing. Use the PARSE PULL instruction if upper case translation is not desired. Example: say 'Do you want to erase the file? Answer Yes or No:' pull answer . if answer='YES' then erase filename Here the dummy placeholder "." is used on the template so the first word typed by the user is isolated ready for the comparison. The number of lines currently in the data queue may be found with the QUEUED built-in function. Note: If the data queue is empty, then a console read will occur. If you "type-ahead" before a REXXPC88 program asks for your input, then your input will be read at the appropriate timne. The length of the console input buffer can be up to 127 characters. Instructions 20 ┌────────────────────────────────────────────────────────────────────────┐ │ PUSH [ expression ] [ ; ] │ └────────────────────────────────────────────────────────────────────────┘ The string resulting from the expression will be stacked LIFO (Last In, First Out) onto the data queue. If no expression is specified, a null string is stacked. Example: a="Fred' push /* Puts a null line onto the stack */ push a 2 /* Puts "Fred 2" onto the stack */ The number of lines currently in the data queue may be found with the QUEUED built-in function. ┌────────────────────────────────────────────────────────────────────────┐ │ QUEUE [ expression ] [ ; ] │ └────────────────────────────────────────────────────────────────────────┘ The string resulting from expression will be queued onto the data queue. Stacked FIFO (First In, First Out). If no expression is specified, a null string is queued. Example: a='Toft' queue a 2 /* Enqueues "Toft 2" */ queue /* Enqueues a null line behind the last */ The number of lines currently on the data queue may be found with the QUEUED built-in function. ┌────────────────────────────────────────────────────────────────────────┐ │ RETURN [ expression ] [ ; ] │ └────────────────────────────────────────────────────────────────────────┘ RETURN is used to return control (and possibly a result) from a REXXPC88 program or internal routine to the point of its invocation. If no internal routine (subroutine or function) is active, then RETURN is essentially identical to EXIT. If a subroutine is being executed (see the CALL instruction) then the expression (if any) is evaluated, control passes back to the caller, and the variable "RESULT" is set to the value of the expression. If no ex- pression is specified, the variable "RESULT" is dropped (becomes unini- tialized). The various settings saved at the time of the CALL (tracing, etc) are also restored - see under the CALL instruction for details of these. If a function is being executed, then the action taken is identical, ex- cept that an expression must be specified on the RETURN instruction. The result of the expression is then used in the original expression at the point where the function was invoked. If a PROCEDURE instruction was executed within the routine (subroutine or internal function), then all local variables are dropped (and the previous generation is exposed) after the expression is evaluated and before the result is used or assigned to "RESULT". ┌────────────────────────────────────────────────────────────────────────┐ │ SAY expression [ ; ] │ └────────────────────────────────────────────────────────────────────────┘ The evaluated expression is written to the standard output stream, fol- lowed by a carriage return and a linefeed. Instructions 21 ┌────────────────────────────────────────────────────────────────────────┐ │ SELECT [ ; ] │ │ whenlist │ │ [ OTHERWISE [ ; ] [ instructionlist ] ] │ │ END [ ; ] │ │ │ │ where whenlist is : │ │ │ │ one or more whenconstructs │ │ │ │ and whenconstruct is: │ │ │ │ WHEN expression[;] THEN [;] instructionlist │ │ │ │ and instructionlist is: │ │ │ │ any sequence of instructions. │ └────────────────────────────────────────────────────────────────────────┘ SELECT is used to conditionally execute one of several atlernative in- structions. Each expression following a WHEN is evaluated in turn and must result in 0 or 1. If the result is 1, the instruction following the THEN ( which may be a complex instruction such as IF, DO, SELECT) is executed and control will then pass to the END. If the result is 0, control will pass to the next when clause. If none of the WHEN expressions succeed, control will pass to the instruction(s), if any, following OTHERWISE. In this situation, the ab- sence of an OTHERWISE will cause an error. Example: a=words(x) select when a=0 then do say 'no words in a' iterate end when a>10 then say 'can''t handle more than 10 words in a string' otherwise end Notes: ∙ A null clause is not an instruction, so putting an extra semicolon after a WHEN clause is not equivalent to putting a dummy instruction (as it would be in PL/I). The NOP instruction is provided for this purpose. ∙ A variable called THEN cannot be used within expression, because the keyword THEN is treated differently, in that it need not start a clause. This allows the expression on the WHEN clause to be termi- nated by the THEN, without a ; (delimiter) being required - this is consistent wiith the treatment of THEN following an IF clause. ┌────────────────────────────────────────────────────────────────────────┐ │ SIGNAL labelname [ ; ] │ │ SIGNAL [ VALUE ] expression [ ; ] │ │ SIGNAL [ ON │ OFF ] condition [ ; ] │ │ │ │ │ │ wnere condition or labelname is a single symbol or │ │ literal string which is taken as a constant, │ │ and expression evaluates to a label name. │ └────────────────────────────────────────────────────────────────────────┘ In case of neither ON or OFF being specified: A label name is either taken directly from labelname, or is taken from the result of evaluating the expression following VALUE. The sub-keyword VALUE may be omitted if the expression does not begin with a symbol or a literal string (i.e., if it starts with a special character, such as an operator or parenthesis). Instructions 22 All active pending DO loops, DO groups, IF constructs, SELECT constructs, and INTERPRET instructions in the current routine are then terminated (i.e., they cannot be reactivated). Control then passes to the first label in the program that matches the given name, as though the search had started from the top of the program. If labelname is a symbol, the matching takes place independently of alphabetic case, but otherwise the label must match exactly. In case of either ON or OFF being specified: A particular exception trap is either enabled or disabled. The specified condition must be one of the following: HALT raised if an external attempt is made to interrupt execution of the program. This error is raised if either Control-Break or Control-C is pressed while the REXXPC88 program is execution. NOVALUE raised if an uninitialized variable is used in an evaluated expression of following the VAR sub-keyword of the PARSE in- struction, (or in a compound variable in either of these cir- cumstances). SYNTAX raised if an interpretation error is detected. If ON is specified, the given condition is enabled; and if OFF is speci- fied, the condition is disabled. The initial setting of all conditions if OFF. When a condition is currently enabled and the specified event occurs, instead of the usual action at that point, execution of the current in- struction will immediately cease. A "SIGNAL XXX" (where XXX is HALT, NOVALUE, or SYNTAX) is then executed automatically. The condition will be disabled before the signal takes place, and a new SIGNAL ON instruction is required to re-enable it. For example, if the required label is not found, a normal syntax error event will occur. This (if not itself trapped) will report the clause in which the event occurred before term- minating the program. The conditions are saved on entry to a subroutine and are then restored on RETURN. This means that SIGNAL ON and SIGNAL OFF may be used in a subroutine without affecting the conditions set up by the caller. ┌────────────────────────────────────────────────────────────────────────┐ │ TRACE [ tracesetting ] [ ; ] │ │ TRACE [ [ VALUE ] expression ] [ ; ] │ │ │ │ where tracesetting is a symbol or │ │ literal string which is taken as a constant. │ └────────────────────────────────────────────────────────────────────────┘ The TRACE instruction is used to control the tracing of execution of a REXXPC88 program, and is primarily used for debugging. Its syntax is more concise than other REXXPC88 instructions, since it is commonly typed manually during interactive tracing. For this use, economy of keystrokes is considered to be more important than readability. The trace setting is either taken directly from tracesetting, or is taken from the result of evaluating the expression following VALUE. The sub- keyword VALUE may be omitted if the expression does not begin with a symbol or a literal string (i.e., if it starts with a special character, such as an operator or parenthesis). Trace setting may start with one or more "?" characters. If so these will either swith on or switch off interactive tracing. If any other charac- ters are in the setting then TRACE will take action according to the first of them. The permitted values for the alphabetic part of the setting are: A (e.g., "ALL") all clauses are traced before execution. C (e.g., "Commands") all host commands are traced before exe- cution. If the command results in an error or failure, then the return code from the command is also shown. Instructions 23 E (e.g., "Error") any host command resulting in an error or failure is traced (after execution) together with the return code from the command. F (e.g., "Failure") any host command resulting in a failure is traced (after execution) together with the return code from the command. This is the same as "TRACE N". I (e.g., "Intermediates") is the same as "R" except that all terms and intermediate results during expression evaluation (and sub- stituted names) are also traced. L (e.g., "Labels") only traces labels passed during execution. This is especially useful while tracing interactively, when the REXXPC88 language processor will pause after each label; or if one wishes to note all internal subroutine calls and signals. N (e.g., "Normal") nothing is traced except for hosts commands resulting in failure. These are traced (after execution) to- gether with the return code from the command. O (e.g., "Off") nothing is traced, and interactive tracing is also switched off. Note: This is the default setting. R (e.g., "Results") all clauses are traced before execution, to- gether with the final result of any expression evaluated. Values assigned during PULL, ARG and PARSE instructions are also displayed. Note: This setting is recommended for general debugging. If no setting is specified or if the setting is the null string, then tracing is reset to its initial (default) setting, that is "Off" and "Interactive tracing OFF". The current setting may be retrieved by using the TRACE built-in function. For "TRACE A" and for "TRACE C", commands traced before execution have the final value of the command (that is, the string passed to the command environment) traced as well as the clause generating it. Whenever any command resulting in an error or failure is traced, the return code from the command is also traced. Note: The trace setting is automatically saved across subroutine and internal function calls. Interactive trace setting The "?" prefix on the trace setting is used to control interactive trac- ing. During normal execution, executing a TRACE instruction with a "?" setting prefix causes interactive tracing to be switched on. While tracing interactively, interpretation will pause after most clauses that are traced. The state of interactive tracing is saved and restored across internal routine calls. As an example, the instruction "TRACE ?Errors" will make the REXXPC88 language processor pause for input after executing any host command that returns a non-zero return code. Interactive tracing may be switched off by executing a TRACE instruction with a prefix "?" during an interactive pause, or by executing "TRACE Off". Using the "?" prefix therefore switches you alternately in or out of interactive tracing. The prefix may be specified more than once in the same setting, if desired, and each occurrence of the prefix reverses the previous setting. The format of TRACE output Every clause traced will be displayed with automatic formatting (inden- tation) according to its logical depth of nesting. Results (if requested) are indented an extra two spaces and have leading and trailing quotes so that leading and trailing spaces are apparent. All lines displayed during tracing have a three-character prefix to identify the type of data being traced. These may be: '*-*' Identifies the source of a single clause, i.e., the data actu- ally in the program. Instructions 24 '+++' Identifies a trace message. This may be an error or failure return code from a command. '>>>' Identifies the result of an expression (for TRACE Results), or the value assigned to a variable during parsing, or the value returned from a call to a subroutine or function. '>.>' Identifies the value "assigned" to a placeholder during parsing. The following prefixes are only used if "TRACE Intermediate" is in effect: '>V>' The string traced is the contents of a variable. '>L>' The string traced is literal (constant symbol, uninitialized variable, or literal string). '>F>' The string traced is the result of a function call. '>P>' The string traced is the result of a prefix operation. '>O>' The string traced is the result of an operation on two terms. '>C>' The string traced is the name of a compound variable. It is traced after substitution and before use. See "Appendix A. Debugging" on page 54 for more information. NOTES 1. An expressionlist is a sequence of zero or more expressions, separated by commas. 2. A namelist is a sequence of one or more variable names separated by blanks. 3. An instructionlist is a sequence of one or more instructions. 4. Observe that instructions fall into one of the following four cate- gories based on the first (and possibly second) tokens of the in- struction. The possibilities are listed in the order in which they are resolved by REXXPC88: The first token may be... in which case... a keyword the (keyword) instruction is executed by REXXPC88. followed by "=" a word the (assignment) instruction is executed by REXXPC88. followed by ":" a word the (label) instruction is ignored by REXXPC88. string a word or the expression is evaluated by REXXPC88 and the resulting string is passed to the operating system for execution as a command or program. 5. Instructions may be either written entirely on one line (exactly as shown in the instructions definitions in the preceding section) or they may be split into several lines. However, an instruction may only be split at positions where a semicolon appears in the instruct- ion definition. We'll call the components of the instruction which appear between semicolons clauses. Thus, for example, an instruction defined as xxxx ; yyyy ; zzzz ; (consisting of three clauses) may also be written xxxx ; yyyy ; zzzz ; or Instructions 25 xxxx ; yyyy ; zzzz ; 6. If a semicolon is the last token on a line, it may be omitted. Thus the preceding example might also have been written xxxx ; yyyy ; zzzz or xxxx yyyy ; zzzz or xxxx yyyy zzzz 7. Sometimes a clause may be too large to fit conveniently on a single line, as when a long expression is written. In these cases the clause may be continued on successive lines by placing a comma at the end of the line(s) to be continued. The comma functions as a continuation character but is otherwise ignored. For example, the instruction if (a == b) & (c == d) & (e == f) then call foo might also be written if (a == b), & (c == d), & (e == f) then call foo The comma may not appear in the middle of a token. 8. Any number of blanks and/or tabs and/or comments may appear between the tokens which comprise an instruction, provided the preceding rules are obeyed. Thus, the preceding example might also be written: if (a == b) /* a comment */ & (c == d), & (e == f) /* another comment */ then call foo /* final comment */ Instructions 26