VOLUME 50 National CP/M Users Group DESCRIPTION: STAGE2 MACRO PROCESSOR By: Dick Curtiss 843 NW 54th Seattle, WA 98107 <> STAGE2 is a macro programming language, documented sufficiently on this disk to effectively use it. Examples given include a library of extensions for assembler programming, (ALX) including WHILE, REPEAT, IF, BRANCH (a CASE statement), etc. STAGE2 is a general-purpose text-replacement processor, not limited to programming language applications. Those interested in transporting it to other machines, or in studying its background and implementation will want to purchase: "Software Tools for Non-Numeric Applications" by: Wm. M. Waite from: Prentice Hall, Inc. Rt. 59 at Brook Hill Dr. P.O. Box 505 West Nyack, NY 10994 for: $24.95 + 1.00 tax + 1.85 Postage/handling NUMBER SIZE NAME COMMENTS CATALOG.051 CONTENTS OF CP/M VOL. 51 51.1 2K ABSTRACT.051 Overview of volume 51.2 16K ALX.S2M Assembly Language Extension macros 51.3 3K ALX-.DOC Doc on above 51.4 3K ALXTEST.ALX Sample macros to test above, including ALXTEST.ALX errors to be detected. 51.5 4K CIO.ALX Console I/O routines in ALX 51.6 2K CRCK.COM Keith Petersen's program to CRC check files 51.7 1K CRCKLIST.CRC Contains the CRCs for all files on this disk. (except itself) 51.8 2K DEMO.S2M Interactive STAGE2 demo macros. 51.9 17K DISKIO2.SRC (*) disk I/O for STAGE2 processor 51.10 6K DISKIO2-.DOC (*) DOC on above 51.11 5K FLD1.DAT (*) Sample data for FLUB test 51.12 4K FLD2.DAT (*) " 51.13 13K FLT1.FLB (*) Sample program for FLUB test 51.14 11K FLT2.FLB (*) " 51.15 1K FLUB$.SUB (*) Submit file for FLT1, FLT2, STG2. 51.16 4K FLUB8080.S2M (*) Macros to turn FLUB into 8080 asm 51.17 3K HELP.DOC First-timer's "to do" list. 51.18 2K IMPL.DOC (*) Notes on implementing STAGE2 51.19 2K INTERACT.S2M Another macro demo. 51.20 22K INTRO.DOC Sufficient info to "read" STAGE2 macros, and with diligence, write them. 51.22 1K IOOP$.SUB (*) submit file for macro pass + asm of above 51.21 16K IOOP.SRC (*) I/O processor 8080 source 51.23 1K MEMORY.INP Another macro demo. 51.24 2K ST2T.DAT (*) 51.25 12K STAGE2.COM The executable macro processor itself. 51.26 48K STG2.FLB (*) Source for STAGE2 in FLUB code 51.27 5K STG2MATH.ASM (*) STAGE2 support routines 51.28 5K STG2SUP.ASM (*) " 51.29 8K TERM.ALX Sample 8080 terminal program w/ALX macros. 51.30 3K TERMSUP.ASM Subroutines for TERM.ALX 51.31 2K USE.DOC How to execute STAGE2. 51.32 6K VDB.ALX TDL video driver in ALX, a "state machine". 51.33 5K VOLUME51.DOC Dick Curtiss' own excellent documentation. (*) Files are necessary only to change STAGE2. NOTE: Included on this volume for the first time, is a file of CRC's for each file. Thus people concerned that a copy when wrong somewhere, can check the CRC of the file, and compare it to the one stored in CRCKLIST.CRC. Thanks to Keith Petersen for this excellent program. Abstract for National CP/M Users Group Vol. 51, "STAGE2 Macro Processor" Richard Curtiss implemented STAGE2, wrote many of the sample programs, and did an excellent job of commenting on his own work. INTRO.DOC and VOLUME51.DOC, provide not only doc- umentation, but "insight", which is normally the service an "abstract" serves. Because of such good documentation, (and this disk is full), this abstract will be brief. STAGE2 is "cryptic", but quite interesting. Many of you will enjor "experimenting with it", and many will make regular use of it. What is a "macro processor"? A program, which "trans- forms" or "expands" character strings, into something else. Traditional uses were in assembler programming, allowing you to say, for example, " OPEN MYFILE,INPUT,4096", rather than having to code the necessary assembler instructions. Richard Curtiss uses it to expand ANY language he uses on his micro, to add structured programming: IF/THEN, WHILE, REPEAT, etc. The macros generate the proper GOTOs, etc, no matter what the language STAGE2 was written in "FLUB", a machine-independent simple language. The FLUB source for STAGE2 is on the disk. IMPL.DOC goes into the details. You could transport STAGE2 to some other processor, quite readily. The only thing missing is some documentation on the "state machine" macros of ALX. VDB.ALX, a video driver for a memory-mapped display, uses them. You are normally in ST1 (state 1) waiting for characters. If you get an ESC, you go to ST2, because you are awaiting a control sequence. Then, if you receive a "Y", it is cursor addressing, so you set the next state to ST3 via "SETNEXT ( NSTATE = ST3 )" to get the row, then when its received, "SETNEXT ( NSTATE = ST4 )", i.e. state 4 to receive the column. Then reset to state 1. The NSTATE DW is the address of the next state (rou- tine) you will be in, and "EXECUTE ( NSTATE )" expands to "branch to what is stored in NSTATE. Abstract by Ward Christensen STAGE2 IS: STAGE2 is a versatile macro processor developed by William M. Waite. Operating on a generalized pattern recognition principle, it can be used for language translation, textual data filtering, limited printer output formatting, batch file editing and other text processing applications. FEATURES: Pattern matching Symbol table (storage and retrieval under user control) Symbol generator Integer arithmetic Arithmetic expression evaluator Scan controlled iteration (search for specific characters) Count controlled iteration Conditional and unconditional branching (skips) I/O channel control Limited output formatting Recursion Error traceback showing all macro calls STRONG POINTS: Highly transportable Some applications are an order of magnitude simpler to implement with STAGE2 than with conventional algorithmic languages. WEAK POINTS: A bit slow Uses lots of memory for large applications (language translation) Macro code is very cryptic in appearance REFERENCES: STAGE2 is in the public domain and is documented by the author in the book: Implementing Software for Non-numeric Applications by W. M. Waite 1973 Prentice Hall Chapter 9 and appendix A include STAGE2 user information, source listings and implementation directions. STAGE2 is also documented by the author in: "Communications of the ACM" Volume 13 / Number 7 July 1970 Pages 415-421 STAGE2 for CP/M: This 8080 implementation was accomplished by: Dick Curtiss 843 NW 54th Seattle, Washington 98107 (206) 784-8018 and is in the public domain. DEVIATIONS FROM THE VERSION DISTRIBUTED BY WAITE: Variable length lines for input and output (132 char max) Input lines Carriage return terminates Line feeds are ignored Nulls are ignored Deletes are ignored Output lines Carriage return and line feed on every line Channel 5 implemented for console input and output IMPLEMENTATION LIMITATIONS: STAGE2 is modeled on an abstract machine called the FLUB machine. FLUB stands for First Language Under Bootstrap. The FLUB machine word is made up of three fields: Pointer field 16 bits in this CP/M implementation Value field 8 bits Flag field 8 bits (only two used) Since the value field is sometimes used to hold string length, strings are limited to 255 characters maximum. Under some circumstances the value field is considered to be signed so that strings longer than 127 characters may cause strange results, but NOT a crash. STAGE2 seems to be extremely well protected against crashes. Since the pointer field is used for arithmetic operations, values are limited to the range -32767 to 32767. -32768 causes trouble. Each character stored by STAGE2 takes 1 FLUB word or 4 bytes in this implementation. CP/M VERSION AVAILABILITY: CP/M Users' Group 1651 Third Avenue New York, NY 10028 DISCLAIMER: )()!&(%$#"#"%!!$(%!##!(!$!!$=(00(!#=!! so there! Use it at your own risk. MORE INFORMATION: HELP.DOC For the STAGE2 novice - start here USE.DOC STAGE2 I/O summary and command line specification INTRO.DOC Introduction to the STAGE2 processor IMPL.DOC STAGE2 implementation notes EXAMPLE FILES: ALX.S2M Assembly Language eXtension translator macros ALX-.DOC Notes on ALX.MAC ALXTEST.ALX Test case for the ALX macros TERM.ALX Sample program (incomplete) VDB.ALX TDL video display driver for H19 emulation CIO.ALX CP/M console I/O with PMMI modem in "parallel" MEMORY.INP Macros and source for memory demonstration INTERACT.S2M Macros to demonstrate interactive use of STAGE2 DEMO.S2M Macros for interactive exercise of most conversions and a few processor functions. This is to be used while reading the INTRO.DOC file. IMPLEMENTATION FILES: IOOP.SRC Initialization and input/output package DISKIO2.SRC General CP/M disk input/output package DISKIO2-.DOC Documentation for above IOOP$.SUB Submit file for creating IOOP.HEX FLT1.FLB FLUB translation test program 1 FLD1.DAT Test data for FLT1 FLT2.FLB FLUB translation test program 2 FLD2.DAT Test data for FLT2 STG2.FLB Source program for STAGE2 ST2T.DAT Test data for STAGE2 FLUB8080.S2M STAGE2 macros for translating FLUB into 8080 code STG2SUP.ASM Support routines for the FLUB machine STG2MATH.ASM 16 bit math routines for the FLUB machine FLUB$.SUB Submit file for assembling FLT1, FLT2 or STG2 Getting Started for the STAGE2 Novice 3/20/81 Step 1. Print the following files: HELP.DOC USE.DOC INTRO.DOC DEMO.S2M Step 2. Read through INTRO.DOC but do not get bogged down in trying to under- stand it. The idea on this first pass is to become a little familiar with what is there. Step 3. Run STAGE2 using DEMO.S2M for input. A>STAGE2 DEMO.S2M ; make sure printer is on or A>STAGE2 CON:,CON:=DEMO.S2M ; if you do not have a printer STAGE2 error messages go to channel 4 which is defaulted to the list device if nothing is specified on the command line. Step 4. Type the following examples and carefully observe the results. Go through all of the examples once to become familiar with them but do not try to understand what is going on. Then start over and do each example while referring to the listings DEMO.S2M and INTRO.DOC in an effort to understand the operations being performed. Don't get dis- couraged as it may not make sense at first. Perseverance is in order. HELP C0 ABC ; simple copy C1 ABC ; symbol undefined in memory F3 ABC=XYZ ; defines symbol in memory C1 ABC ; symbol now defined - ; note difference from previous C1 F3 ABC=IJK ; new value for ABC in memory C1 ABC S ; next symbol from generator S S C2 ABC ; similar to C1 except if symbol is not ; defined it will be given the next ; value from the symbol generator C2 PDQ S C2 PDQ C4 2+3*(4-7/3) ; expression evaluation C4 PDQ-6 ; will use value of PDQ from memory C4 XXX+3 ; XXX is undefined so value is 0 C4 ABC+3 ; causes error message to channel 4 X ; because ABC has non-numeric value ; in memory C5 ABCDEFGHIJK ; length of string C6 MAGIC ; parameter redefinition C7 ONE,TWO;THREE ; scanner operation C8 A C8 B ; internal code for character F1 ; output request F7 2+3 ; count controlled iteration F7 PDQ FE ; error trace back F0 ; terminates - WARM BOOT ASSEMBLY LANGUAGE EXTENSION PREPROCESSOR This application of STAGE2 to enhance assembly language programs with a few control structures is included with this STAGE2 package mainly for example. No user documentation is provided but it should not be difficult to see how to use it by trying the examples provided. Examples: STAGE2 ALXTEST.ASM,ALXTEST.LST=ALX.MAC,ALXTEST.ALX STAGE2 BOUT.ASM,BOUT.LST=ALX.MAC,BOUT.ALX IMPLEMENTATION NOTES: > means push ^ means pop C means condition Stack Source Statements Generated Code >n >K IF ( C ) JCF n ^K ^n FIN n: ----------------------------------------------------------- >n >n+1 >W WHEN ( C ) JCF n+1 ^W >E FIN JMP n ^E ^n+1 >K ELSE n+1: ^K ^n FIN n: ----------------------------------------------------------- >B BRANCH ( V1 ) L1 CPI V1 JZ L1 ( V2 | V3 | V4 ) L2 CPI V2 JZ L2 CPI V3 JZ L2 CPI V4 JZ L2 ( OTHERWISE ) L3 JMP L3 ^B FIN ----------------------------------------------------------- >n >S SELECT >n+1 >I ( V1 ) CPI V1 JNZ n+1 ^I ^n+1 FIN JMP n n+1: >n+3 >I ( V2 | V3 | V4 ) CPI V2 JZ n+2 CPI V3 JZ n+2 CPI V4 JNZ n+3 n+2: ^I ^n+3 FIN JMP n n+3: >O ( OTHERWISE ) ^O FIN ^S ^n FIN n: ----------------------------------------------------------- >n >n+1 >L WHILE ( C ) n+1: JCF n ^L ^n+1 ^n FIN JMP n+1 n: ----------------------------------------------------------- >n >R REPEAT n: ^R ^n UNTIL ( C ) JCF n ----------------------------------------------------------- Statement is allowed if top of stack is one of the following: I,K,L,O,R,W,*. Otherwise particular control statements are expected. I,K,L,O,W statement or FIN R statement or UNTIL E ELSE only S SELECT ITEM or FIN B BRANCH ITEM or FIN