*
*``````````````````````````````*
* DEMO.COMMON                  *
*                              *
* A DEMO OF THE MACROS AND     *
* SUBROUTINES IN THE COMMON    *
* APPLEIIASM LIBRARY.          *
*                              *
* AUTHOR:    NATHAN RIGGS      *
* CONTACT:   NATHAN.RIGGS@     *
*            OUTLOOK.COM       *
*                              *
* DATE:      30-JUN-2019       *
* ASSEMBLER: MERLIN 8 PRO      *
* OS:        DOS 3.3           *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
** ASSEMBLER DIRECTIVES
*
         CYC   AVE
         EXP   ONLY
         TR    ON
         DSK   DEMO.COMMON
         OBJ   $BFE0
         ORG   $6000
*
*``````````````````````````````*
*  TOP INCLUDES (HOOKS,MACROS) *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
         PUT   MIN.HEAD.REQUIRED
         USE   MIN.MAC.REQUIRED
         PUT   MIN.HOOKS.COMMON
         USE   MIN.MAC.COMMON
]HOME    EQU   $FC58
*
*``````````````````````````````*
*      PROGRAM MAIN BODY       *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
         JSR   ]HOME
         _PRN  "COMMON SUBROUTINE LIBRARY",8D
         _PRN  "=========================",8D8D
         _PRN  "THIS LIBRARY CONTAINES MACROS AND",8D
         _PRN  "SUBROUTINES THAT MIGHT BE COMMONLY",8D
         _PRN  "USED BY A BROAD RANGE OF PROGRAMS.",8D8D
         _PRN  "THIS DEMO WILL ALSO ILLUSTRATE THE",8D
         _PRN  "USE OF SOME MACROS IN THE REQUIRED",8D
         _PRN  "LIBRARY FOR THE FIRST TIME. WE WILL",8D
         _PRN  "MAKE IT CLEAR WHEN WE SWITCH LIBRARIES,",8D
         _PRN  "BUT FOR QUICK REFERENCE THE MACROS",8D
         _PRN  "IN EACH LIBRARY ARE:",8D8D
         _WAIT
         _PRN  "REQUIRED MACROS: _ISLIT,_AXLIT,",8D
         _PRN  "_ISSTR,_AXSTR,GRET,SPAR,DUMP,_PRN,",8D
         _PRN  "_WAIT,ERRH,CLRHI",8D8D
         _WAIT
         _PRN  "COMMON: MFILL,MMOVE,MSWAP,BEEP,DELAY,",8D
         _PRN  "ZSAVE,ZLOAD",8D8D
         _WAIT
         _PRN  "LET'S START WITH THE MOST USED REQUIRED MACROS."
         _WAIT
         JSR   ]HOME
         _PRN  "REQUIRED LIBRARY: MOST USED",8D
         _PRN  "===========================",8D8D
         _PRN  "BY 'MOST USED' HERE, WE MEAN MOST",8D
         _PRN  "USED BY THESE SHORT DEMOS. IN",8D
         _PRN  "REALITY, OTHER MACROS ARE PROBABLY",8D
         _PRN  "UTILIZED MUCH MORE OFTEN, BUT IT",8D
         _PRN  "HAPPENS BEHIND THE SCENES.",8D8D
         _WAIT
         _PRN  "THE TWO MOST APPARENT MACROS ",8D
         _PRN  "SHOULD BE FAMILIAR IF YOU HAVE",8D
         _PRN  "ALREADY EXPLORED THE STDIO LIBRARY:",8D
         _PRN  "_PRN AND _WAIT. THESE ARE NEAR",8D
         _PRN  "CARBON COPIES OF THEIR EQUIVALENT",8D
         _PRN  "ROUTINES IN STDIO, AND ARE HERE FOR",8D
         _PRN  "THE MOSTLY RARE CASES WHEN SOME",8D
         _PRN  "MINOR INPUT AND OUTPUT ARE NECESSARY",8D
         _PRN  "BUT WITHOUT THE NEED FOR USING THE",8D
         _PRN  "STDIO LIBRARY. SINCE THESE EXIST",8D
         _PRN  "AS PART OF THE ERQUIRED LIBRARY, YOU",8D
         _PRN  "CAN USE THESE IN PLACE OF STDIO IF",8D
         _PRN  "YOUR PROGRAM REQUIRES NO MORE THAN THIS",8D
         _PRN  "BASIC FUNCTIONALITY."
         _WAIT
         JSR   ]HOME
         _PRN  "THE _PRN MACRO PRINTS A STRING THAT",8D
         _PRN  "IS EITHER GIVEN AS A PARAMETER OR",8D
         _PRN  "RESIDES AT A GIVEN ADDRESS AND IS",8D
         _PRN  "TERMINATED BY A NULL BYTE ($00). THUS:",8D8D
         _WAIT
         _PRN  "   _PRN 'HELLO, WORLD!'",8D
         _PRN  "   _PRN #STRING1",8D
         _PRN  "   _PRN INDIRECT",8D8D
         _WAIT
         _PRN  "ARE ALL VALID USES OF _PRN. THE FIRST",8D
         _PRN  "PRINTS THE GIVEN STRING, THE SECOND",8D
         _PRN  "PRINTS NULL-TERMINATED STRING AT THE",8D
         _PRN  "STRING1 ADDRESS, AND THE THIRD PRINTS",8D
         _PRN  "A NULL-TERMINATED STRING AT THE",8D
         _PRN  "ADDRESS POINTED TO IN THE ADDRESS HELD",8D
         _PRN  "IN INDIRECT.",8D8D
         _WAIT
         _PRN  "THE WAIT MACRO DOES EXACTLY WHAT ",8D
         _PRN  "IT SAYS: IT WAITS FOR A KEYPRESS. THE",8D
         _PRN  "KEY PRESSED IS PASSED BACK IN .A"
         _WAIT
         JSR   ]HOME
         _PRN  "MEMORY DUMPS",8D
         _PRN  "============",8D8D
         _PRN  "THE OTHER MACRO MOST USED IN",8D
         _PRN  "THESE DEMOS IS THE DUMP MACRO, WHICH",8D
         _PRN  "OUTPUTS THE HEX VALUES AT A GIVEN",8D
         _PRN  "ADDRESS RANGE. THEREFORE:",8D8D
         _WAIT
         _PRN  "   LDA #$33",8D
         _PRN  "   STA $300",8D
         _PRN  "   STA $301",8D
         _PRN  "   STA $302",8D
         _PRN  "   DUMP #$300;#10",8D8D
         _PRN  "WILL OUTPUT",8D8D
         _WAIT
         LDA   #$33
         STA   $300
         STA   $301
         STA   $302
         DUMP  #$300;#10
         _WAIT
         JSR   ]HOME
         _PRN  "PARAMETERS AND RETURNS",8D
         _PRN  "======================",8D8D
         _PRN  "NEARLY EVERY SUBROUTINE IN THIS",8D
         _PRN  "SET OF LIBRARIES UTILIZES THE",8D
         _PRN  "SAME MEMORY LOCATION FOR RETURNING",8D
         _PRN  "RESULTS, SAVE FOR THOSE THAT RETURN",8D
         _PRN  "NOTHING. THIS LOCATION IS REFERENCED",8D
         _PRN  "IN THE CODE AS THE 'RETURN' HOOK.",8D8D
         _WAIT
         _PRN  "THE GRET MACRO CAN BE USED TO COPY",8D
         _PRN  "THE RETURNED DATA TO A MORE PERMANENT",8D
         _PRN  "LOCATION FOR RETRIEVAL LATER ON. SO:",8D8D
         _PRN  "   GRET #$300",8D8D
         _WAIT
         _PRN  "COPIES THE DATA FROM RETURN INTO THE",8D
         _PRN  "SPECIFIED LOCATION ($300). NOTE THAT",8D
         _PRN  "THE LENGTH OF THE RETURN VALUE IS",8D
         _PRN  "KNOWN VIA THE 'RETLEN' HOOK, WHICH",8D
         _PRN  "POINTS TO A LENGTH BYTE PRECEDING RETURN"
         _WAIT
         JSR   ]HOME
         _PRN  "INTERNAL MACROS",8D
         _PRN  "===============",8D8D
         _PRN  "THE MACROS _ISLIT, _AXLIT,",8D
         _PRN  "_ISSTR AND _AXSTR ARE ALL MACROS USED",8D
         _PRN  "BY OTHER MACROS TO DETERMINE WHAT",8D
         _PRN  "KIND OF DATA IS BEING MASSED, THEN",8D
         _PRN  "TRANSLATING THAT TO A MACHINE-FRIENDLY",8D
         _PRN  "FORM. THESE MACROS ARE RESPONSIBLE",8D
         _PRN  "FOR A MACRO'S ABILITY TO ACCEPT",8D
         _PRN  "DIRECT OR INDIRECT ADDRESSING, AS",8D
         _PRN  "WELL AS LITERAL STRINGS.",8D8D
         _WAIT
         _PRN  "THIS CAN BE EASILY SEEN IN",8D
         _PRN  "MANY MACROS THAT ACCEPT EITHER ",8D
         _PRN  "STRINGS OR ADDRESSES. FIRST, THE",8D
         _PRN  "PARAMETER IS PASSED TO EITHER THE",8D
         _PRN  "_ISSTR MACRO OR THE _AXSTR MACRO;",8D
         _PRN  "THESE ARE FUNCTIONALLY EQUIVALENT AND",8D
         _PRN  "TEST WHETHER OR NOT THE PARAMETER",8D
         _PRN  "IS A STRING OR ADDRESS, BUT DIFFER IN",8D
         _PRN  "HOW THAT DATA IS THEN PASSED TO THE",8D
         _PRN  "APPROPRIATE SUBROUTINE.",8D
         _WAIT
         JSR   ]HOME
         _PRN  "_ISSTR PASSES DATA VIA THE STACK,",8D
         _PRN  "WHEREAS_AXSTR PASSES VIA .A AND .X,"8D
         _PRN  "WHICH HOLD THE LO AND HI BYTES OF THE",8D
         _PRN  "ADDRESS OF THE STRING, RESPECTIVELY.",8D
         _PRN  "WHICH MACRO TO USE IS PRIMARILY",8D
         _PRN  "DETERMINED BY THE SUBROUTINE BEING",8D
         _PRN  "CALLED, AS THEY EITHER USE ONE OR",8D
         _PRN  "THE OTHER METHODS OF PASSING",8D
         _PRN  "PARAMETERS. A RULE OF THUMB IS THAT",8D
         _PRN  "IF THERE ARE FEWER THAN 4 BYTES",8D
         _PRN  "TO BE PASSED, THEN PASSING IS DONE",8D
         _PRN  "VIA REGISTERS TO SPARE A FEW CYCLES;",8D
         _PRN  "OTHERWISE, THE STACK IS USED.",8D8D
         _WAIT
         _PRN  "_ISLIT AND _AXLIT USE THE SAME LOGIC",8D
         _PRN  "FOR THE PASSING OF PARAMETERS, BUT ARE",8D
         _PRN  "USED TO DETERMINE WHETHER THE PARAMETER",8D
         _PRN  "BEING PASSED IS A LITERAL VALUE OR A",8D
         _PRN  "MEMORY LOCATION. IF THE PARAMETER IS",8D
         _PRN  "A LITERAL, THEN THE MACRO SENDS IT",8D
         _PRN  "AS A 2-BYTE ADDRESS THAT INDICATES",8D
         _PRN  "THE DATA IS LOCATED AT THAT ADDRESS.",8D
         _PRN  "IF, HOWEVER, A NON-LITERAL ADDRESS IS",8D
         _PRN  "PASSED, THE LIBRARY INTERPRETS THIS AS",8D
         _PRN  "AN INDIRECT REFERENCE, WHERE THE ",8D
         _PRN  "ADDRESS PASSED IS A POINTER TO THE",8D
         _PRN  "ACTUAL ADDRESS OF THE DATA."
         _WAIT
         JSR   ]HOME
         _PRN  "THE REQUIRED LEFTOVERS",8D
         _PRN  "======================",8D8D
         _PRN  "OTHER MACROS IN THE REQUIRED LIBRARY",8D
         _PRN  "ARE RARELY USED OUTSIDE OF THE",8D
         _PRN  "LIBRARY ITSELF IN THE DEMOS, IF AT ALL.",8D
         _PRN  "THIS INCLUDES THE ERRH AND CLRHI MACROS.",8D8D
         _WAIT
         _PRN  "CLRHI TAKES ONE BYTE AND CLEARS ITS",8D
         _PRN  "HIGH NIBBLE, AND IS USEFUL FOR THE",8D
         _PRN  "IMPLEMENTATION OF LOOKUP TABLES, AMONG ",8D
         _PRN  "OTHER USES. THE ERRH MACRO PASSES THE",8D
         _PRN  "PROVIDED ADDRESS TO APPLESOFT AS A HOOK",8D
         _PRN  "FOR ERROR-HANDLING, AND CAN BE THOUGHT",8D
         _PRN  "OF AS A 'ONERR GOTO ###' COMMAND FOR",8D
         _PRN  "ASSEMBLY. NOTE THAT THIS DOESN'T CATCH",8D
         _PRN  "JUST ANY ERRORS IN YOUR CODE--YOU ",8D
         _PRN  "STILL HAVE TO FIGURE THAT OUT YOURSELF.",8D
         _PRN  "THE ERROR-HANDLING IS SPECIFIC TO ",8D
         _PRN  "INTERFACING WITH APPLESOFT."
         _WAIT
*
         JSR   ]HOME
         _PRN  "COMMON MACROS, FINALLY!",8D
         _PRN  "=======================",8D8D
         _PRN  "WE CAN NOW MOVE ON TO THE",8D
         _PRN  "MACROS IN THE COMMON LIBRARY. MOST",8D
         _PRN  "OF THESE CURRENTLY FOCUS ON MEMORY",8D
         _PRN  "MANAGEMENT, AND WE WILL ADDRESS THOSE",8D
         _PRN  "FIRST: MFILL, MMOVE, MSWAP, ZLOAD AND",8D
         _PRN  "ZSAVE."
         _WAIT
         JSR   ]HOME
         _PRN  "MEMORY MANAGEMENT",8D
         _PRN  "=================",8D8D
         _PRN  "MFILL FILLS A RANGE OF MEMORY STARTING",8D
         _PRN  "AT THE GIVEN ADDRESS WITH THE GIVEN",8D
         _PRN  "FILL VALUE. THUS:",8D8D
         _PRN  "   MFILL #$300;#10;#0",8D8D
         _PRN  "FILLS $300-$309 WITH ZEROS. WE CAN",8D
         _PRN  "VERIFY THIS WITH A DUMP:",8D
         _WAIT
         MFILL #$300;#10;#0
         DUMP  #$300;#10
         _WAIT
         JSR   ]HOME
         _PRN  "MMOVE SUITABLY MOVES (OR COPIES) A",8D
         _PRN  "BLOCK OF MEMORY FROM ONE ADDRESS",8D
         _PRN  "RANGE TO ANOTHER. SO:",8D8D
         _WAIT
         _PRN  "   MMOVE #$300;#$320;#10",8D
         _PRN  "   DUMP #$320;#10",8D8D
         _PRN  "WILL COPY THE TEN ZEROS AT $300",8D
         _PRN  "TO $320-$329, THEN DUMP THE RESULTS:",8D
         MMOVE #$300;#$320;#10
         DUMP  #$320;#10
         _WAIT
         JSR   ]HOME
         _PRN  "SIMILARLY, MSWAP SWAPS THE DATA IN ",8D
         _PRN  "THE GIVEN MEMORY RANGES. SO, TO SWAP",8D
         _PRN  "$300-309 WITH $310-$319, WE'D WRITE:",8D8D
         _PRN  "   MSWAP #$300;#$310;#10",8D8D
         _PRN  "NOW WHEN WE DUMP $300 AGAIN, IT HAS:",8D
         _WAIT
         MSWAP #$300;#$310;#10
         DUMP  #$300;#10
         DUMP  #$310;#10
         _WAIT
         JSR   ]HOME
         _PRN  "ZERO-PAGE BACKUPS",8D
         _PRN  "=================",8D8D
         _PRN  "THIS LIBRARY USES NEARLY EVERY",8D
         _PRN  "PART OF THE ZERO PAGE THAT IS",8D
         _PRN  "UNUSED BY DOS, APPLESOFT OR THE ",8D
         _PRN  "MONITOR. AT TIMES, YOU MAY WANT TO",8D
         _PRN  "USE THOSE LOCATIONS YOURSELF WITHOUT",8D
         _PRN  "THE RISK OF THE LIBRARY WRITING OVER",8D
         _PRN  "YOUR DATA. THAT'S WHERE ZSAVE AND",8D
         _PRN  "ZLOAD COME INTO PLAY.",8D8D
         _WAIT
         _PRN  "ZSAVE BACKUPS THE ZERO-PAGE MEMORY THAT",8D
         _PRN  "IS UNUSED BY DOS/APPLESOFT/MONITOR,",8D
         _PRN  "COPYING IT TO THE SPECIFIED LOCATION. ",8D
         _PRN  "THEN, ZLOAD IS USED TO RESTORE THOSE",8D
         _PRN  "'UNUSED' BYTES TO YOUR OWN DATA AFTER A",8D
         _PRN  "LIBRARY ROUTINE IS CALLED.",8D
         _WAIT
         JSR   ]HOME
         _PRN  "SO, WE CAN SAVE THE ZERO-PAGE AT $300",8D
         _PRN  "WITH THE FOLLOWING:",8D8D
         _PRN  "   ZSAVE #$300",8D8D
         _PRN  "AND THEN CHANGE THE ZERO PAGE SLIGHTLY:",8D8D
         _PRN  "   LDA #$99",8D
         _PRN  "   STA $06",8D
         _PRN  "   STA $07",8D
         _PRN  "   STA $08",8D
         _PRN  "   STA $09",8D
         _PRN  "   STA $19",8D8D
         ZSAVE #$300
         LDA   #$99
         STA   $06
         STA   $07
         STA   $08
         STA   $09
         STA   $19
         _WAIT
         JSR   ]HOME
         _PRN  "NOW WE'LL DUMP THE ZERO PAGE TO",8D
         _PRN  "SHOW THE CHANGES:",8D
         DUMP  #$0;#10
         DUMP  #10;#10
         DUMP  #20;#10
         _PRN  " ",8D8D
         _PRN  "NOTE THAT ALREADY, THE $10 HAS BEEN",8D
         _PRN  "CHANGED BY THE LIBRARY! THUS THE",8D
         _PRN  "NEED FOR A BACKUP. SO, IN ORDER",8D
         _PRN  "TO RECOVER OUR ZERO PAGE, USE ZLOAD:",8D8D
         _PRN  "   ZLOAD #$300",8D8D
         _WAIT
         _PRN  "WHICH WILL THEN LEAVE US WITH:",8D
         _WAIT
         ZLOAD #$300
         DUMP  #0;#10
         DUMP  #10;#10
         DUMP  #20;#10
         _WAIT
         JSR   ]HOME
         _PRN  "BEEP AND DELAY",8D
         _PRN  "==============",8D8D
         _PRN  "LASTLY, WE HAVE THE BEEP MACRO",8D
         _PRN  "AND THE DELAY MACRO FROM THE",8D
         _PRN  "COMMON LIBRARY. THESE ARE PRETTY",8D
         _PRN  "SELF-EXPLANATORY: 'BEEP' SENDS THE",8D
         _PRN  "STANDARD TONE TO THE SPEAKER FOR ",8D
         _PRN  "SPECIFIED NUMBER OF CYCLES, WHILE ",8D
         _PRN  "DELAY SUSPENDS EXECUTION FOR THE",8D
         _PRN  "SPECIFIED NUMBER OF MILLISECONDS. ",8D
         _PRN  "SO: ",8D8D
         _PRN  "   BEEP #10",8D
         _PRN  "   DELAY #255",8D
         _PRN  "   BEEP #20",8D
         _PRN  "   DELAY #255",8D
         _PRN  "   BEEP #30",8D8D
         _PRN  "RESULTS IN:",8D8D
         _WAIT
         BEEP  #10
         DELAY #255
         BEEP  #20
         DELAY #255
         BEEP  #30
         _WAIT
         JSR   ]HOME
         _PRN  "WE'RE DONE HERE!",8D8D8D
*
         JMP   REENTRY
*
*``````````````````````````````*
*        BOTTOM INCLUDES       *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
** BOTTOM INCLUDES
*
         PUT   MIN.LIB.REQUIRED
*
** INDIVIDUAL SUBROUTINE INCLUDES
*
*  COMMON LIBRARY SUBROUTINES
*
         PUT   MIN.SUB.DELAYMS
         PUT   MIN.SUB.MEMFILL
         PUT   MIN.SUB.MEMMOVE
         PUT   MIN.SUB.MEMSWAP
         PUT   MIN.SUB.ZMSAVE
         PUT   MIN.SUB.ZMLOAD
