Apple Assembly Line
Volume 7 -- Issue 9 June 1987

In This Issue...

Return of Beneath Apple ProDOS

We've just received our copies from the newest printing of Beneath Apple ProDOS, so that excellent reference is available again. Our thanks to Quality Software for keeping such valuable information at our fingertips.

However, we do not expect that Quality Software will reprint either Understanding the Apple II or Understanding the Apple //e, so once the supplies run out that's the end of those books. If you are at all interested in the innermost details of how your Apple hardware works you need to get one of these outstanding books by Jim Sather. We've never seen anything to compare to these books for the wealth of information at the chip-by-chip level. See the S-C Software ad on page three for our price.

Latest from Lancaster

Don Lancaster just sent a copy of his latest book, Ask the Guru. Computer Shopper readers will recognize the title of his monthly column in that publication; this book is a collection of the columns from March, 1985 through March, 1987. Here are all of Don's writings on the inner workings of our favorite computer, especially how to get the most out of AppleWriter and/or the LaserWriter printer.

This is undoubtedly the best-printed self-published book I've ever seen: each copy is directly printed out on Don's Laser- Writer! Even subscribers to Computer Shopper will want this book, just to have all the information in one place rather than strung out through many pages of oversized newsprint. $24.50 from Synergetics, Box 809, Thatcher, AZ 85552. (602) 428-4073.

Selective CLEAR for Applesoft Variables Bruce E. Howell

A friend of mine wrote an Applesoft program that processes classroom grades. Certain information, such as the teacher's name, would be loaded and used throughout the program, while other information, such as student grades, had to be cleared often. One solution would be having a loop to clear certain variables. This would be quick and easy with simple variables, but with multi-dimensioned arrays this can be time consuming. Another solution would be to open a temporary file and store the static information there or to POKE it in a safe place in memory, such as at $300, issue the CLEAR command to clear all Applesoft variables, then re-load the variables. My solution to the problem is Selective Clear, which allows you to select a range of real, integer or string variables to clear, or to clear an entire, specific array. Note that Selective Clear sets real and integer variables to zero, and string variables to a null string. Applesoft's CLEAR command deletes the variables, requiring arrays to be re-defined after the CLEAR.


Selective Clear works with either ProDOS or DOS. To follow ProDOS convention, it is loaded at $2000, then moved up in memory to where it is used. If your Applesoft program is short, you can load Selective Clear from within your program. A longer Applesoft program would be overwritten by the initial loading of Selective Clear. To avoid this, use a short Applesoft program to load Selective Clear, then run the main program as follows:


To use Selective Clear in your application, it is best to define your simple variables and group them alphabetically so that those that you want to clear often are all at one end or the other of the alphabet. The syntax for simple variables is:

   & $ > G : REM clear all string variable greater than G
   & % < M : REM clear all integer variables less that M
   & R > T : REM clear all real variables greater than T

Following the ampersand, use $, % or R to indicate string, integer or real variables to clear. Following the variable type use the greater than (>) or less than (<) sign, then a single alpha character to show the range.

Array variables are cleared individually by placing the actual variable to clear in parenthesis following the ampersand as follows:

   & (AB$) : REM  To clear the string array AB$
   & (M)   : REM  To clear the real array M
   & (TT%) : REM  To clear the integer array TT%

Note that if you try to clear an array that has not been defined, you will get an error message of ARRAY ERROR.


To enter Selective Clear, you can use an assembler to type in the source code as listed. I use the ProDOS version of S-C Macro Assembler. You can also enter it directly into the monitor. If you do the latter, save it with the command:

     BSAVE B.SEL.CLEAR,A$2000,L$166


The first thing done is to identify which operating system is in effect, to properly reserve memory for Selective Clear. Then the routine is moved to the proper location in memory, the ampersand vector is set and control returns back to Applesoft.

To understand how simple variables can be selected and cleared, you must understand how variables are stored in memory. Locations $69,6A point to the start of a table of simple variables, normally set to LOMEM. For real and integer variables, the actual values are stored in the table, while for string variables the table contains pointers to where the strings are stored in memory (from HIMEM down). Each variable occupies seven locations or bytes in the table, the first two locations being the variable name.

With real variables, the first byte is the positive value of the first character of the variable name. The second byte is the positive value of the second character of the variable name. For integer variables, both bytes are the negative values for the variable name, while with string variables, the first byte is positive and the second is negative. Depending on which variable type is selected, two different masks (MASK1 and MASK2) are used to determine if the current entry in the table has a variable name with the proper signs for the type you want to select.

The other choice that Selective Clear needs to make is whether the variable in the table is less than or greater that the range that you have indicated. This is done by changing the program slightly each time it is called. If greater than is selected, then a Branch on Carry Clear (BCC) is placed where the variable name is compared to the selected range. Greater than stores a Branch on Carry Set (BCS). A no match of either the variable type or range skips to the next entry in the table until the end of the table is reached.

If the variable name is within the selected range and the signs match the variable type selected, then Selective Clear clears the variable by storing zeros in the next five locations in the table. For real numbers, the first location contains a one byte exponent followed by four bytes of mantissa. Integer numbers have the high byte first followed by the low byte of the number stored in the variable. The last three bytes of the entry are not used. String variables have a one byte string length followed by the low and high bytes of the address where the string is stored. With strings, the last two bytes of the table entry are not used.

Memory locations $6B,6C point to the start of the array table. Variable names are stored in the same way as with simple variables. Since you will manually select which array to clear, the routine finds the variable's location in the table by evaluating the expression within the parenthesis using an Applesoft routine at $DEB2, then searching the table for the variable name. The first two bytes following the name are an offset pointer to the next variable in the table. Selective Clear uses their value to determine when it is done clearing. The next byte is the number of dimensions present. It uses that value to bypass that number of sets of high-low bytes which follow, each set indicating the size of each dimension. After these sets of bytes is where the actual data is stored (or pointers to data if string arrays) in the same way that simple variables are stored. To clear, the routine zeros all locations till it reaches the next array variable name.


I chose to clear arrays individually, since a normal program uses very few arrays. You can modify the routine to clear a range of arrays using the technique outlined for simple vari- ables. If you need to clear either simple variables only or arrays only, you can shorten the routine enough to fit at $300. You could also modify the routine to set the variable to some required value, passed to the routine, instead of clearing it.

  1010 *--------------------------------
  1020 *
  1030 * Selective CLEAR 
  1040 *
  1050 * Copyright 1987 by Bruce E. Howell, D.D.S.
  1060 *                   2531 Cartwright Rd.
  1070 *                   Missouri City, Texas  77459
  1080 *
  1090 * Format for simple variables is:  &type>range
  1100 *                                  &type<range
  1110 *
  1120 * Where 'type' is:  $ to clear string variables
  1130 *                   % to clear integer variables 
  1140 *                   R to clear real variables
  1150 *
  1160 *       'range' is a single alpha character.
  1170 *       Variables greater (>) or less (<) than
  1180 *            this character are cleared.
  1190 *
  1200 *
  1210 * Format for array variables is:
  1220 *
  1230 *       & (C$)     to clear the string array C$
  1240 *       & (C)      to clear the real array C
  1250 *       & (C%)     to clear the integer array C%
  1260 *
  1270 *--------------------------------
  1280 CHRGET .EQ $00B1 
  1290 CHRGOT .EQ $00B7
  1300 AMPER  .EQ $03F5    Ampersand Vector
  1310 *--------------------------------
  1330 GETBUF .EQ $BEF5    ProDOS Obtain Buffer
  1340 *--------------------------------
  1350 ERROR  .EQ $D412    PRINT ERROR
  1360 ADDON  .EQ $D998    Add (Y) to ChrPtr
  1370 SCAN   .EQ $D9A3    SCAN TO :/EOL
  1390 *--------------------------------
  1410 *--------------------------------
  1450 *--------------------------------
  1460 VARTAB .EQ $69,6A   START OF VARS
  1490 FRETOP .EQ $6F,70
  1500 HIMEM  .EQ $73,74
  1510 VARNAM .EQ $81,82
  1520 LOC    .EQ $E0,E1  
  1530 HOLD   .EQ $E8,E9
  1540 RANGE  .EQ $E4
  1550 MASK1  .EQ $E5
  1560 MASK2  .EQ $E6 
  1570 *--------------------------------
  1580 JMP.OP .EQ $4C      JMP OP CODE
  1590 MASK   .EQ $80
  1600 BCC.OP .EQ $90      BCC OP CODE
  1610 BCS.OP .EQ $B0      BCS OP CODE
  1620 *--------------------------------
  1630        .MA SET
  1640        LDA #]2
  1650        STA ]1
  1660        LDA /]2
  1670        STA ]1+1
  1680        .EM
  1690 *--------------------------------
  1700        .MA MOV
  1710        LDA ]2
  1720        STA ]1
  1730        LDA ]2+1
  1740        STA ]1+1
  1750        .EM
  1760 *--------------------------------
  1770        .OR $2000
  1780        .TF B.SEL.CLEAR
  1790 *--------------------------------
  1810        CMP #JMP.OP  SEE IF ACTIVE
  1820        BEQ PRODOS   YES DO PRODOS
  1830 *---Assume in DOS 3.3------------
  1840 DOS    LDA #SELCLR
  1850        STA HIMEM
  1860        STA FRETOP
  1870        LDA /SELCLR
  1880        STA HIMEM+1
  1890        STA FRETOP+1
  1910 *---Assume in ProDOS-------------
  1930        LDA #2       GET TWO PAGES
  1940        JSR GETBUF
  1950 *---Move routine into hole-------
  1960 DOMOVE >SET SSA,FROM   Starting address of source
  1970        >SET SEA,THRU   Ending address of source
  1980        >SET DSA,SELCLR Starting address of destination
  1990        JSR MOVMEM
  2010        STA AMPER
  2020        >SET AMPER+1,SELCLR
  2030        RTS          RETURN
  2040 *--------------------------------
  2050 FROM
  2060        .PH $9800    WHERE WE END UP 
  2070 SELCLR JSR CHRGOT   Get char after "&"
  2080        LDY #MASK    If "R":  X=$80, Y=$80
  2090        LDX #MASK    If "$":  X=$80, Y=$00
  2100        CMP #'R'     If "%":  X=$00, Y=$00
  2110        BEQ .3       ...REAL VARIABLE
  2120        CMP #'$'     SEE IF STRING
  2130        BEQ .2       ...STRING VARIABLE
  2140        CMP #'%'     SEE IF INTEGER 
  2150        BEQ .1       ...INTEGER VARIABLE
  2170 .1     LDX #$00     CHECK FOR NEG
  2180 .2     LDY #$00
  2190 .3     STX MASK1    SET MASKS FOR
  2200        STY MASK2    TWO CHAR. NAME
  2210 *---Get and save relop-----------
  2220        JSR CHRGET   GET FUNCTION <>
  2230        STA FUNC
  2240 *---Get and save letter----------
  2250        JSR CHRGET   GET RANGE OF Variable Name
  2260        STA RANGE
  2270 *---Modify code for relop--------
  2280        LDA FUNC
  2290        CMP #$CF     SEE IF GT >
  2300        BNE .4       ...not >
  2310        INC RANGE    SO > RANGE NOT =
  2320        LDA #BCC.OP  SET UP GT >   
  2330        BNE .6       ...always
  2340 .4     CMP #$D1     SEE IF LT <
  2350        BEQ .5 is <
  2360        LDX #$10     REPORT SYNTAX ERROR
  2370        JMP ERROR
  2380 .5     LDA #BCS.OP  SET UP LT <   
  2390 .6     STA FUNC     FUNNY TRICK
  2400 *--------------------------------
  2420        LDY #0       FOR INDEX
  2450        CMP ARYTAB+1  
  2460        BNE .1
  2470        LDA LOC 
  2480        CMP ARYTAB  
  2490        BCC .1
  2500        JSR SCAN     YES SCAN EOL
  2510        JMP ADDON    GO APPLESOFT
  2520 *--------------------------------
  2530 .1     LDA (LOC),Y  GET VARIABLE NAME
  2540        AND #$7F     MASK HIGH BIT
  2560 *
  2570 FUNC   BCC .1       ***Opcode modified to BCC or BCS***
  2580 *
  2590        LDA (LOC),Y  GET VARIABLE TYPE
  2600        AND #MASK
  2610        EOR MASK1
  2620        BNE .3
  2630 .1     JSR INCLOC
  2640        JSR INCLOC
  2650 .2     LDA LOC      SKIP FIVE 
  2660        CLC  
  2670        ADC #$05  
  2680        STA LOC
  2690        BCC SIMPLE
  2700        INC LOC+1  
  2710        BCS SIMPLE   ALWAYS
  2720 *--------------------------------
  2730 .3     JSR INCLOC
  2740        LDA (LOC),Y
  2750        AND #MASK
  2760        EOR MASK2
  2770        BEQ .2       ...not correct type
  2780 *---Clear the value--------------
  2790        JSR INCLOC   PASS 2ND   
  2800        LDX #5
  2810        LDA #0       Store zero in 5 bytes
  2820 .4     STA (LOC),Y
  2830        JSR INCLOC
  2840        DEX
  2850        BNE .4
  2860        BEQ SIMPLE   ...always
  2870 *--------------------------------
  2890        BNE .1
  2900        INC LOC+1    ADVANCE HIGH
  2910 .1     RTS  
  2920 *--------------------------------
  2940        JSR PARCHK   ERROR IF NOT
  2960 .1     LDY #0       FOR INDEX
  2970        LDA (LOC),Y  GET 1ST. CHAR.
  2980        BEQ .99      NONE PRESENT
  3000        BNE .5       FIND NEXT ARRAY
  3010        INY
  3020        LDA (LOC),Y  GET 2ND CHAR.
  3030        CMP VARNAM+1
  3040        BNE .5       FIND NEXT ARRAY
  3050        INY          PASS 1ST NAME
  3060        LDA (LOC),Y  GET LOW OFFSET
  3070        CLC          CLEAR CARRY
  3080        ADC LOC      ADD TO CURRENT
  3090        STA HOLD     LOW END OF ARRAY
  3100        INY          
  3110        LDA (LOC),Y  GET HIGH OFFSET
  3120        ADC LOC+1    ADD TO CURRENT
  3130        STA HOLD+1   HIGH END OF ARRAY
  3140        INY
  3150 .2     JSR INCLOC
  3160        DEY
  3170        BNE .2
  3180        LDA (LOC),Y  # OF DIMS
  3190        TAX          COUNTER
  3200        JSR INCLOC   PASS # DIMS
  3210 .3     JSR INCLOC   PASS SIZE H
  3220        JSR INCLOC   PASS SIZE L
  3230        DEX
  3240        BNE .3
  3250        LDA #$00
  3260 .4     STA (LOC),Y  
  3270        JSR INCLOC
  3280        LDX LOC      SEE IF END OF
  3290        CPX HOLD     THIS ARRAY YET
  3300        BNE .4       NOT END OF ARRAY
  3310        LDX LOC+1    CHECK AGAIN
  3320        CPX HOLD+1
  3330        BNE .4
  3340        RTS          RETURN BASIC
  3350 *---Find Next Array--------------
  3360 .5     LDY #$02
  3370        LDA (LOC),Y
  3380        CLC
  3390        ADC LOC
  3400        STA HOLD     NEXT ADDRESS LOW
  3410        INY
  3420        LDA (LOC),Y
  3430        ADC LOC+1
  3440        STA LOC+1    NEXT ADDRESS HIGH
  3450        LDA HOLD
  3460        STA LOC 
  3470        CMP STREND
  3480        BNE .1
  3490        LDA LOC+1
  3500        CMP STREND+1
  3510        BNE .1
  3520 *
  3530 .99    LDX #$80     DIDN'T FIND 
  3540        JMP ERROR    say ARRAY ERROR
  3550        .EP
  3560 THRU
  3570 *--------------------------------

More Than Just Saving the Registers Bob Sander-Cederlof

When you are writing a program it is frequently advantageous to code some parts as subroutines. Some of these subroutines will be useful enough that you may wish to use them in lots of programs. In order to make them usable in a variety of circumstances, you have to be sure that they do not have any hidden side-effects. A subroutine for general use should not change any registers, any memory, or any part of the machine state unless the change is a desired function of that subroutine.

It is getting harder and harder to live up to that ideal, as the Apple II grows. In the beginning there was only the plain vanilla 6502, and at most 48K RAM. There was plenty of memory, plenty of stack space, plenty of zero page. Every subroutine could have its own private work area, and not worry too much about RAM or register usage. Machine state was pretty much the same all day long, with the exception of the text and graphics modes. But now we have the IIgs and the 65816 with more registers, megabytes of RAM to manage, bank switching, shadowing, interrupts, variable speed processing, emulation, and so on endlessly.

It used to be enough to just save and restore the A-, X-, and Y-registers. For example, you might find the following at the beginning and end of a 6502 subroutine:

       Beginning           End
     ---------------     -------------------
       PHA    Save A       PLA     Restore Y
       TXA                 TAY
       PHA    Save X       PLA     Restore X
       TYA                 TAX
       PHA    Save Y       PLA     Restore A

This code saves and restores all three machine registers, so that they may all be used for any other purpose inside the subroutine.

On the other hand, you might not find this code, because most subroutines written in the years gone by used one or more of the three registers to pass parameters. To use such a subroutine, you would first place the values used by the subroutine into the registers; then you would call the subroutine. If the subroutine was supposed to return an answer, it might be returned in the same registers. If the subroutine needed to use page zero at all, it might have its own private locations.

When page zero became over-crowded, we started saving and restoring chunks of page zero. If only a few bytes were needed, they could be saved on the stack. If a larger block was needed, the subroutine might save the block in a private area of RAM outside of page zero.

The IIgs and 65816 are so complicated now that I almost despair of ever writing a completely safe subroutine. Each subroutine must be careful analyzed to see what information needs to be saved and restored and what internal states, modes, and values need to be used.

Rather than try to give you a complete entry-setup-exit template, I am going to show you the components and let you construct your own as you require them.

The first item that occurs to me has to do with the native and emulation modes. If you are writing a subroutine that can be called from both modes yet internally must use one particular mode, you need to save the caller's mode. The standard way of doing this is:

       Beginning                  End
     -------------------------  ------------------
       PHP   Save m and x         PLP  Get caller's mode
       SEC   (or CLC)             XCE
       XCE  Get into my mode      PLP  Get caller's m,x
       PHP  Save caller's mode    RTS

Seeing that RTS at the end reminds me of another difficulty. A subroutine cannot possibly know whether it was called with a JSR or a JSL instruction. JSR pushes a two-byte return address on the stack, while JSL pushes a three byte return address. If a subroutine was called with a JSR, it must end with an RTS. Likewise, if the call was made with JSL, the return must be an RTL. You have to decide what you are going to use and write the subroutine accordingly. If you need both, you will have to write two different subroutines (although they might share some code internally).

If you need to save and restore the three main registers (A, X, and Y) without knowing ahead of time which mode the caller was in, you need to be sure and save all 16-bits of each of them. Here is how I do that:

       Beginning                  End
     -------------------------  ------------------
       PHP   Save m and x         CLC  (Unless still in
       CLC   Native mode          XCE   the native mode)
       XCE                        REP #$30
       PHP   Save caller's mode   PLY  Restore Y
       REP #$30  Full 16-bit      PLX  Restore X
       PHA   Save A               PLA  Restore A
       PHX   Save X               PLP
       PHY   Save Y               XCE  Restore caller's mode
                                  PLP  Caller's m and x

If the subroutine is being called with a JSL, it is possibly being called from a different bank. That means I may need to worry about the Data Bank Register. In the 65816 there is an 8-bit B-register which contains the bank number to use with all 16-bit addressing modes used to read or write data. If my subroutine needs to use local data or variables which are in the same bank as my subroutine, and the caller was in a different bank, I will most likely need to save his B-register and set up my own. There is also a Program Bank Register, called the K-register, which is changed automatically by the JSL and RTL instructions. To save the B-register and make it the same as my K-register, so I can refer to local data and variables, I need the following lines near the beginning of my subroutine:

       PHB     Save the caller's B-register
       PHK     Push Program Bank
       PLB     Use it as Data Bank also

Then near the end of the subroutine I need the corresponding line:

       PLB     Restore the caller's B-register

It is conceivable that the caller may have the Stack Pointer set to some weird value. In the 6502 the S-register is only 8-bits wide, but in the 65816 it has 16 bits. The stack can be made to start anywhere in bank 0 when you are in native mode. If you have programs that use more than one stack area, you may need to save and restore the caller's stack pointer and use your own inside your subroutine. In particular, if you are going to use Emulation Mode, or call monitor subroutines which do so, you will need to use the standard stack in page 1 inside your subroutine. The following four lines will save the current stack pointer and set up your own, assuming you are already in Native mode with both m- and x-bits cleared for full 16-bit operation:

       TSC     current stack pointer to A (16-bits)
       LDX ##xxxx   new value of stack pointer
       PHA     save previous value on new stack

You may think of other ways to do this, but something of the sort must be done. If you use the above, then near the end of your subroutine you need to restore the original stack pointer as follows:


In a 6502 there is only one page zero, at addresses $0000 through $00FF. In the 65816 page zero may start anywhere in bank 0, because there is a 16-bit D-register which defines the starting address of the so-called "direct" page. If your programs fiddle with the D-register, then your subroutine might need to save and restore it. If your are calling any of the old monitor subroutines, be aware that they require a "standard" page zero. In 16-bit mode you can do it this way:

       Save               Restore
     ----------------   ---------------------
       PHD  Old D-reg     PLD   Get old D-reg
       PEA $xxxx
       PLD  New D-reg

So far I have only been worrying about the 65816 itself. What about all the Apple soft switches? The //e and //c were enough of a challenge, with all the memory banking and 80-column options. Now along comes the IIgs, an order of magnitude more complex!

In fact it is so complex that I have not mastered it yet. For now all I am going to point out is the rules for calling the old monitor subroutines and the new "tools". To use the old monitor subroutines you must be in Emulation mode, and running in bank 0 with normal page zero and stack pointers. The monitor itself must "be" in bank 0. Since the ROM is really in bank FF, you have the option of copying it to RAM in bank 0 or using the soft switch at $C081, $C089, $C082, or $C08A to map ROM into bank 0.

To call the new "tools" you must be in full 16-bit native mode. I think that is just about the only requirement. Then you use JSL to call the tools via the vectors in bank $E1.

Beyond this elementary level, it is easy to get lost. It reminds me of the "twisty little passages" in the Original Adventure Game. My advice: be careful; keep close track of everything you change; put everything back the way you found it. If your subroutine works, you may have done it correctly. Maybe not. You might not find out what you left out till next year when you try to use it from a new environment.

Recent articles in Call APPLE have discussed some of the same ideas, and you may profit by reading them. Look at David Sparks' "The Ethical Subroutine" in the June 1987 issue, and Bob Bishop's "Modular Assembly Language Programming" series in earlier issues this year.

Correction to ProDOS Patcher Bob Sander-Cederlof

Mike McConnell called with a correction to my Applesoft ProDOS Patcher that affected its ability to find and fix versions 1.1.1 and 1.2. Lines 430 and 440 PEEKed at A, A+1, A+2, and A+3; in fact they should be PEEKing at A, A+3, A+6, and A+9. Change those two lines to:

     430 IF PEEK(A)<>157 OR PEEK(A+3)<>157 THEN 500
     440 IF PEEK(A+6)<>157 OR PEEK(A+9<>157 THEN 500

Then I noticed an error in the REMark at line 450. What it should say is:

     450 REM ---FOUND VERSION 1.1.1 OR 1.2,
                        SO CHANGE "STA" TO "LDA"---

Using the S-C Macro Assembler
with an Echo Speech Synthesizer
Rick Hayner

In 1977, I went to college to train to become a computer programmer. I was programming an IBM 360-30 main frame, with output which was not usable by me, since I am totally blind, and couldn't read the print output. My first programming language was IBM 360 Assembly Language. Depending on sighted readers who knew nothing about computers to read the listings, and having them help me find errors on IBM cards which sometimes had been punched on a keypunch which didn't print on the tops of the cards, was enough to drive a sane person crazy. Ever since then, I have had the desire to become a good Assembly Language programmer.

After getting an Apple //e, in 1985, I thought that using the ECHO Speech Synthesizer with an editor/assembler would be great. The problem was finding one which would talk.

While talking with Larry Skutchan, a friend of mine who is also a blind programmer, I asked him if he knew about an assembler that would talk, and he recommended the S-C Macro Assembler. I work part time for a company on designing software to help physically handicapped people. My boss, Scott Atwood, asked me if I would be willing to learn 6502 Assembly Language, and if I knew of an assembler which would talk, and I told him about the S-C Macro Assembler. About a week later, Scott brought the assembler to me, and using the instructions in the manual, which I was able to obtain as textfiles on diskette, I had the assembler talking within 10 minutes of getting it.

The ECHO Speech Synthesizer uses a prgoram called Textalker, which resides in the language card area. This means I must use the "main memory" version of the S-C Macro Assembler. The instructions for patching the assembler gave the address of the instructions which had to be patched out in the main memory version, so there were no problems encountered in patching the assembler.

The thing which stops most Machine Language programs from talking is a "JSR $FE89" followed by a "JSR $FE93". These instructions are like doing an "IN#0" and a "PR#0". The problem is that Textalker changes the I/O hooks, and these routines disconnect Textalker. Changing these two instructions to six "NOP" instructions, allows the S-C Macro Assembler to talk. Another thing which stops programs from talking, is people sometimes store data directly into screen memory locations, instead of using "COUT". Fortunately, the S-C Macro Assembler doesn't do this, but you do have to patch out the JSR's mentioned above.

I really like the S-C Macro Assembler. I haven't figured out how to use all of its features yet, but I use it almost every day, and always learn something new about it every time I use it.

I have written some macros for controlling the Echo, and I have included them here for other Echo users.

I want to thank all the people at S-C Software for their help in learning to use the S-C Macro Assembler. They have always been willing to answer all questions, whether they have been about the assembler or about programming. I would recommend the S-C Macro Assembler to anyone who is interested in Assembly Language, whether they are blind or sighted.

  1010 *--------------------------------
  1020 *
  1030 *   Macros for ECHO Speech Synthesizer, by Rick Hayner
  1040 *
  1050 *   Requires Textalker Version 3.1.1 or later.
  1060 *
  1070 *--------------------------------
  1080 *   Generic ECHO Command:  >ECHO "X"  (X is command letter)
  1090 *--------------------------------
  1100        .MA ECHO
  1110        LDA #$85     Control-E
  1120        JSR MON.COUT
  1130        LDA #"]1"    Command letter
  1140        JSR MON.COUT
  1150        .EM
  1160 *--------------------------------
  1170 * TURN ECHO OFF:  >OFF
  1180        .MA OFF
  1190        >ECHO "O"
  1200        .EM
  1210 *--------------------------------
  1220 * TURN ECHO ON:  >ON
  1230        .MA ON
  1240        >ECHO "B"
  1250        .EM
  1260 *--------------------------------
  1280        .MA TALK
  1290        >ECHO "T"
  1300        .EM
  1310 *--------------------------------
  1330        .MA LETTER
  1340        >ECHO "L"
  1350        .EM
  1360 *--------------------------------
  1380        .MA WORD
  1390        >ECHO "W"
  1400        .EM
  1410 *--------------------------------
  1430        .MA USPELL
  1440        >ECHO "K"
  1450        .EM
  1460 *--------------------------------
  1480        .MA USPELLOFF
  1490        >ECHO "N"
  1500        .EM
  1510 *--------------------------------
  1530        .MA SOME
  1540        >ECHO "S"
  1550        .EM
  1560 *--------------------------------
  1580        .MA MOST
  1590        >ECHO "M"
  1600        .EM
  1610 *--------------------------------
  1630        .MA ALL
  1640        >ECHO "A"
  1650        .EM
  1660 *--------------------------------

Assembly Listings on ProDOS Text Files John L. Hanna

From the ProDOS version of the S-C Macro Assembler, how does one direct the assembly listing to a text file for later inclusion in a word processor file? Articles in AAL some years ago showed how to do th is for the DOS 3.3 version, but the techniques given do not work with the ProDOS version.

After some head scratching and some snooping, I did find a way that works. By patching the PBITS entries for the OPEN and WRITE commands I can make them into DIRECT commands. (Without the patches, OPEN and WRITE are not legal as DIRECT commands.) I'll show how to make these two patches in a moment.

Once the patches are installed, by merely typing "OPEN LISTING" and "WRITE LISTING" an output textfile starts absorbing all screen-directed information. I make sure I am ready to assemble, and then type the OPEN and WRITE commands. At this point the screen output disappears, because it is all going to the text file instead. Then I type the ASM command, and the listing is written on the text file. At the end of the assembly the text file is automatically closed, and the prompt re-appears.

There are some "gotchas". First, the S-C Macro Assembler has a fixed number of file buffers. If I use one of them to send the listing to a text file, it is not possible to also have a target file (.TF file) at the same time. This could restrict your possibilities when working with large programs, because the object code does have to go somewhere. Judicious use of the .TA, .DU, or .PH directives could enable you to a assemble even large programs while directing the listing to a text file.

Second, the text file will not be truncated if a short listing is written on a previously exisitng file which was longer. The solution is to always DELETE such a file before you OPEN it.

As a test, I assembled the S-C DisAssembler (an excellent product, by the way) and sent the listing to a text file. I first removed the .TI line so that the resulting file would not have page breaks. Working with two floppy drives, the source code on one and the output listing file on the other, it produced a 177 block text file in just under five minutes. I moved the file into Appleworks with no problems. After adjusting the margins to 0 inches it was 123K, 2298 lines, and saved onto a 95K AWP file.

Now, how do you make those two patches? First you have to find the two bytes to change. Bob has produced several slightly different versions so this requires a little snooping. With the S-C Macro Assembler loaded and running, enter the monitor command "$B900.B99F". This will display the area containing the two bytes that need changing. In some of the monitor versions it will display in both hex and ASCII, but in most just in hex. There are two strings of bytes you need to find:

       4F 50 45 CE xx xx 2D
       57 52 49 54 C5 xx xx 21

The first string starts somewhere near $B918, and the second somewhere near $B958. The "xx xx" indicates two bytes which could have various values. The "2D" and "21" are the two bytes to patch. In my copy of the S-C Macro Assembler, these were at $B91F and $B95F, respectively. Be sure you find and use the correct addresses for yours. Change the 2D to 0D, and the 21 to 01, as follows:

       :$B91F:0D N B95F:01

That is all there is to it! Note that the change is temporary, because it does not modify the SCASM.SYSTEM file. You could find the appropriate place and do that if you wish, but it is just as effective to create a small EXEC file to install the changes whenever you need them.

Printing a Tiny Address Booklet Bob Sander-Cederlof

Do you have trouble remembering all the phone numbers and addresses of your family and friends? I sure do. At work I keep a Rolodex file for the most frequently needed ones, but I can hardly carry it around in my pocket. I could buy a little blank address book at any store, but my handwriting is too poor and they all take up too much space.

I had a vision of a tiny address booklet, no bigger than a credit card, which could hold about 100 names, addresses, and phone numbers. I could carry it in my credit card wallet, so it would almost always be with me when I need it.

It is easy enough to use a word processor to type all the information into my Apple. Last year I did just that, and printed it all out in the condensed mode on my NEC 8023 dot matrix printer. I then cut the printout into little pages and pasted them up in booklet format. Using a Minolta copying machine, I "xeroxed" the paste-up onto both sides of the same sheet of paper. Then using scissors and staples I assembled a little booklet the same size as a credit card, with 12 pages counting the front and back covers. I left those covers plain white, and covered them with clear packing tape, so it could last a little longer.

Indeed it did last, for about a year. Now there are so many changes that it is getting hard to read. I need to bring it up to date. But can the computer do a little more of the work?

Of course it can. Especially with the help of the new Epson EX-800 dot matrix printer I just bought, for only $399 plus tax at the local Soft Warehouse. It prints a lot faster than my other printers, which is why I bought it. But it also has a lot of new features. One of them is the ability to print subscripts and and superscripts. I found out that in this mode, with Condensed and Elite also selected, the printout is not only very small, but very clear and easy to read. The characters are shorter, allowing me to adjust the vertical spacing to 5/72 inch per line. This gets over 150 lines on each sheet of paper! It also lets me get 50 lines (including top and bottom margin) in the 3.5 inches of my booklet pages. And I can print 33 characters per line on each one of the pages, leaving a nice left and right margin. The Epson EX-800 makes two passes over each line in this mode, so that the miniature print is "near letter quality".

The printer helps, but I still wanted some automatic way to layout the individual pages and print them in booklet order, on BOTH SIDES of the same sheet of paper. I started to do it in Applesoft, but suddenly it seemed easier in Assembly Language. The resulting program prints all of the "front sides" and then waits while I take the paper out of the printer, turn it over, and put it back in. Then it prints the "back sides". All I have to do is fold the sheet down the middle, slice it into three 4-page folders, stack them up, and staple them together. It worked beautifully, and the result is nestling nicely in my shirt pocket right now.

To understand my program a little more easily, it might help to take three small pieces of paper, stack them up, fold the stack in half, and call it a booklet. Then label the pages from front to back. Label the front cover "FC", the inside pages 0 through 9, and the back cover "BC". Then take the booklet apart and look at each sheet. I call the outer sheet "FC/0--9/BC", the next sheet "1/2--7/8", and the inner sheet "3/4--5/6". My program prints on pages 0 through 9, and leaves FC and BC blank.

My program works under the assumption that the text file containing all the names and addresses is already in memory. It just happens in my case to begin at $2121. Each character is in ASCII with the high bit on, and the file image ends with a $00 byte. You could make obvious adjustments to the program to work with text in some other position or a different format.

My program also assumes that there are blank lines between each entry, and no blank lines within any entry. This helps me to easily be sure that an entry is not printed partly on one page and partly on another. I counted the number of lines in my entire directory, finding 341 lines. Since I am printing on ten pages, that is about 34 lines per page. I decided to print at least 32 lines on each page, and then finish printing whatever entry was in progress. This resulted in the last page being a little shorter than the rest, and left enough bottom margin on most pages for adding extra names later.

My program begins by setting up the Epson printer. You will need to modify this setup to correspond with the capabilities of your own printer and interface card. Lines 1220-1250 install the printer hook. As you can see, my printer interface card was in slot 5, which is highly unusual. Yours is probably in slot 1, so you will want to change the "$C500" to "$C100". The setup string is shown in lines 1640-1720. The first two lines are control-I commands to the interface card, and the rest are ESCAPE commands to the Epson printer.

The next major activity in my program involves building a table of addresses which point to the beginning of each booklet page in the text buffer. The subroutine which does this is shown in lines 2450-2700. It simply starts with the first page at the given address of $2121 (probably different in your case), scans to the beginning of the next page and saves the address, and so on for 11 pages. The extra page does not really exist, but it helps me set up another table which is used to mark the END of each page. I store the addresses in two different tables: PAGES and SPAGES. PAGES is used for the beginning and current address in each page, and is modified during printout. SPAGES is used to find the end of each page, and is not modified during printout.

Another value you may want to change is the number 32 in line 2780. This is the minimum number of lines to be printed on each page. It turns out my longes page had 35 lines printed on it. If you use a different booklet size or a different ver- tical spacing, you will probably want a different value here.

Looking back at the main program, lines 1360-1450 print the front side of the sheet. Line 1470 pauses the program so that I can turn the paper over and re-insert it into the printer, and then lines 1480-1540 print the back side. My subroutine PRINT.TWO.PAGES does the real work here. The page number (0-9) of the left page is in the A-register and that of the right page in the X-register.

PRINT.TWO.PAGES assumes there are a total of 50 lines per page. You should change the number on line 1830 for a different size page. This count includes the top and bottom margin. I forgot to include a little extra for trimming, but it worked out all right for me. The number 42 on line 1860 controls the starting column for the right-hand page. I had a 33-character line, a 9-character center page gap, and the right page starts in column 43. You may need to change this number also.

The number 35 on line 1880 was arrived at experimentally. Between adjusting the tractors left and right to position the paper, and changing this number 35 up or down, you can center the blank space between the left and right pages exactly over the center of the printer paper. This is important, because when we turn the paper over and print on the back side we want the pages to line up correctly.

Lines 1900-1960 print a line for the left-hand page and tab to the starting column for the right-hand page. Then lines 1980-2040 print a corresponding line for the right-hand page. Of course, either or both of these may be blank lines.

I wish I could show you what the finished product looks like, but that is not practical. If you stop by some time, I will show it to you. Meanwhile, you could adapt this to your own printer and needs and make your own booklet.

A project comes to mind, which one of you might like to tackle. How about parameterizing the variables so that it could make booklets of various dimensions and page counts, and integrate it into a word processor? The S-C Word Processor naturally comes to mind, since so many of you have purchased it with the source code.

  1010 *--------------------------------
  1020        .DUMMY
  1030        .OR 0        DEFINE PAGE ZERO VARIABLES
  1040 PAGES  .BS 24       Room for 12 pointers
  1050 PAGE   .BS 1
  1060 PNTR   .BS 2
  1070 LPAGE  .BS 1
  1080 RPAGE  .BS 1
  1090 LINES  .BS 1
  1100 TABBER .BS 1
  1110        .ED          END OF DUMMY SECTION
  1120 *--------------------------------
  1130 MON.CH .EQ $24
  1140 *--------------------------------
  1150 BEGIN  .EQ $2121    My text buffer starts here
  1160 *                   and ends with a 00 byte.
  1170 *--------------------------------
  1180 CROUT  .EQ $FD8E
  1190 COUT   .EQ $FDED
  1200 *--------------------------------
  1210 T
  1220        LDA #$C500   Hook into my printer card
  1230        STA $36          in slot 5
  1240        LDA /$C500   (Yours is probably in slot 1)
  1250        STA $37
  1260 *---Setup Printer----------------
  1270        LDY #0       Send setup characters to my 
  1280 .1     LDA STRING,Y      printer interface card
  1290        JSR COUT          and to my Epson EX-800
  1300        INY               Printer.
  1310        CPY #STR.LEN
  1320        BCC .1
  1330 *---Find the pages---------------
  1350 *---Print the front side---------
  1360        JSR CROUT
  1370        LDA #2       Print front side of 1/2--7/8
  1380        LDX #7
  1390        JSR PRINT.TWO.PAGES
  1400        LDA #4       Print front side of 3/4--5/6
  1410        LDX #5
  1420        JSR PRINT.TWO.PAGES
  1430        LDA #0       Print front side of FC/0--9/BC
  1440        LDX #9
  1450        JSR PRINT.TWO.PAGES
  1460 *---Print the back side----------
  1470        JSR FLIP.PAPER.OVER
  1480        JSR CROUT
  1490        LDA #8       Print back side of 1/2--7/8
  1500        LDX #1
  1510        JSR PRINT.TWO.PAGES
  1520        LDA #6       Print back side of 3/4--5/6
  1530        LDX #3
  1540        JSR PRINT.TWO.PAGES
  1550 *---Disconnect Printer-----------
  1560        LDA #$C300   Rehook the 80-column screen
  1570        STA $36
  1580        LDA /$C300
  1590        STA $37
  1600        RTS
  1610 *--------------------------------
  1620 *   Printer Setup String
  1630 *--------------------------------
  1640 STRING .HS 09.4E    Turn off Video
  1650        .HS 09.58    Bit 7 = 0
  1660        .HS 1B.53.01 Subscript
  1670        .HS 1B.41.05 5/72 inch vertical
  1680        .HS 1B.23    Cancel Bit 7
  1690        .HS 1B.3D    Bit 7 = 0
  1700        .HS 1B.4D    Elite
  1710        .HS 1B.0F    Condensed
  1730 *--------------------------------
  1750 .1     LDA $C000    Really just wait until I
  1760        BPL .1       manually turn it over.
  1770        STA $C010    Signal by typing any key.
  1780        RTS
  1790 *--------------------------------
  1810        STA LPAGE    Left Page Number
  1820        STX RPAGE    Right Page Number
  1830        LDA #50      Print 50 Lines per Page
  1840        STA LINES
  1850 *---Print left side--------------
  1860 .1     LDA #42      Right Page begins in col. 43
  1870        STA TABBER
  1880        LDA #35      Left Margin to center on page
  1890        STA MON.CH
  1900        LDA LPAGE
  1910        JSR SETUP.PAGE.PNTR
  1920        BCS .2       ...end of this page
  1930        JSR PRINT.LINE
  1940 .2     JSR TAB.TO.MIDDLE
  1950        LDA LPAGE
  1960        JSR UPDATE.PAGE.PNTR
  1970 *---Print right side-------------
  1980        LDA RPAGE
  1990        JSR SETUP.PAGE.PNTR
  2000        BCS .3       ...end of this page
  2010        JSR PRINT.LINE
  2020 .3     JSR CROUT
  2030        LDA RPAGE
  2040        JSR UPDATE.PAGE.PNTR
  2050 *--------------------------------
  2060        DEC LINES    Count down for the page
  2070        BNE .1       More lines on this page
  2080        RTS          Finished
  2090 *--------------------------------
  2110        ASL          Double page number for index
  2120        TAX
  2130        LDA PAGES,X  Get pointer to current
  2140        STA PNTR          to current place on page
  2150        CMP SPAGES+2,X to end of page
  2160        LDA PAGES+1,X
  2170        STA PNTR+1
  2180        SBC SPAGES+3,X    Leave .CS. if end of page.
  2190        RTS               ...or .CC. if not end yet.
  2200 *--------------------------------
  2220        ASL          Double page number for index
  2230        TAX
  2240        LDA PNTR     Save current place on page
  2250        STA PAGES,X       for next line
  2260        LDA PNTR+1
  2270        STA PAGES+1,X
  2280        RTS
  2290 *--------------------------------
  2310 .1     JSR NEXT.CHAR     Print up to <RETURN>
  2320        BCS .2            ...or end of text
  2330        DEC TABBER        Count the character
  2340        JSR COUT          and print it.
  2350        JMP .1   character
  2360 .2     RTS
  2370 *--------------------------------
  2390 .1     LDA #" "          TABBER has remaining
  2400        JSR COUT          blank count to reach
  2410        DEC TABBER        the right side.
  2420        BNE .1
  2430        RTS
  2440 *--------------------------------
  2460        LDA #BEGIN        Start at the beginning 
  2470        STA PNTR              of my text buffer.
  2480        STA PAGES         First page starts here.
  2490        LDA /BEGIN        Hi byte of same...
  2500        STA PNTR+1
  2510        STA PAGES+1
  2520        LDA #1            for PAGE = 1 to 11
  2530        STA PAGE
  2540 *--------------------------------
  2550 .1     JSR SCAN.TO.END.OF.PAGE
  2560        LDA PAGE     Save pointer to beginning of page
  2570        ASL               double for index
  2580        TAX
  2590        LDA PNTR          It is also END+1 for
  2600        STA PAGES,X           previous page.
  2610        STA SPAGES,X
  2620        LDA PNTR+1        Hi-byte of same.
  2630        STA PAGES+1,X
  2640        STA SPAGES+1,X
  2650 *--------------------------------
  2660        INC PAGE          next PAGE
  2670        LDA PAGE
  2680        CMP #12           (up to 12)
  2690        BCC .1   another page
  2700        RTS               finished
  2710 *--------------------------------
  2730        JSR SCAN.32.LINES
  2750        RTS
  2760 *--------------------------------
  2770 SCAN.32.LINES
  2780        LDX #32
  2790 .1     JSR SCAN.TO.NEXT.LINE
  2800        DEX
  2810        BNE .1
  2820        RTS
  2830 *--------------------------------
  2850 .1     JSR SCAN.TO.NEXT.LINE
  2860        JSR NEXT.CHAR
  2870        BCC .1       ...not <RETURN> or end-of-text
  2880        BEQ .4       ...found end-of-text
  2890 .2     JSR NEXT.CHAR
  2900        BEQ .4       ...found end-of-text
  2910        BCS .2       ...found another <RETURN>
  2920        LDA PNTR     Backup the text pointer
  2930        BNE .3            to the <RETURN>
  2940        DEC PNTR+1
  2950 .3     DEC PNTR
  2960 .4     RTS
  2970 *--------------------------------
  2990 .1     JSR NEXT.CHAR
  3000        BCC .1       ...not end-of-text or <RETURN>
  3010        RTS
  3020 *--------------------------------
  3030 *   Get next character from text buffer
  3040 *      Return .CC. if not <RETURN> or end-of-text
  3050 *             .CS. and .EQ. if end-of-text
  3060 *             .CS. and .NE. if <RETURN>
  3070 *--------------------------------
  3080 NEXT.CHAR
  3090        SEC          Return .CS. if <eot> or <return>
  3100        LDY #0
  3110        LDA (PNTR),Y
  3120        BEQ .2 is end-of-text
  3130        INC PNTR
  3140        BNE .1
  3150        INC PNTR+1
  3160 .1     CMP #$8D
  3170        BEQ .3
  3180        CLC
  3190 .2     RTS
  3200 .3     INY          Return .CS. and .NE. if <RETURN>
  3210        RTS
  3220 *--------------------------------
  3230 SPAGES .BS 24
  3240 *--------------------------------
  9999   .LIF

Apple Assembly Line (ISSN 0889-4302) is published monthly by S-C SOFTWARE CORPORATION, P.O. Box 280300, Dallas, Texas 75228. Phone (214) 324-2050. Subscription rate is $18 per year in the USA, sent Bulk Mail; add $3 for First Class postage in USA, Canada, and Mexico; add $14 postage for other countries. Back issues are available for $1.80 each (other countries add $1 per back issue for postage).

All material herein is copyrighted by S-C SOFTWARE CORPORATION, all rights reserved. (Apple is a registered trademark of Apple Computer, Inc.)