*
*``````````````````````````````*
* DEMO.REQUIRED                *
*                              *
* THIS IS A DEMO OF THE CORE   *
* SUBROUTINES THAT THE WHOLE   *
* LIBRARY USES TO FUNCTION.    *
* MOST OF THESE ARE NOT USED   *
* BY THE PROGRAMMER, BUT ARE   *
* INTERNAL TO THE WORKINGS OF  *
* OTHER SUBROUTINES.           *
*                              *
* AUTHOR:    NATHAN RIGGS      *
* CONTACT:   NATHAN.RIGGS@     *
*            OUTLOOK.COM       *
*                              *
* DATE:      04-JUN-2021       *
* ASSEMBLER: MERLIN 8 PRO      *
* OS:        DOS 3.3           *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
** ASSEMBLER DIRECTIVES
*
         CYC   AVE
         EXP   OFF
         TR    ON
         DSK   DEMO.REQUIRED
         OBJ   $BFE0
         ORG   $6000
*
*``````````````````````````````*
*  TOP INCLUDES (HOOKS,MACROS) *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
         PUT   MIN.HEAD.REQUIRED.ASM
         USE   MIN.MAC.REQUIRED.ASM
*
]COUT    EQU   $FDF0
]HOME    EQU   $FC58
*
         JSR   ]HOME
*
*``````````````````````````````*
*      PROGRAM MAIN BODY       *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
*** SINCE THIS GROUP OF MACROS ARE PRIMARILY USED
*** INTERNALLY FOR THE LIBRARIES, DEMONSTRATIONS OF
*** THEIR USAGE WILL NOT BE GIVEN HERE. HOWEVER, A
*** QUICK LOOK AT ALMOST ANY LIBRARY'S MACRO FILE
*** WILL SHOW QUITE EASILY HOW THESE MACROS ARE USED.
*
* THE _AXLIT MACRO - .AX LITERAL
* THE _AXSTR MACRO - .AX STRING
* THE _ISLIT MACRO - IS LITERAL
* THE _ISSTR MACRO - IS STRING
* THE _MLIT MACRO  - MEMORY LITERAL
* THE _MSTR MACRO  - MEMORY STRING
*
*``````````````````````````````*
* _PRN, _WAIT AND BEEP         *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
*** THE _PRN, _WAIT AND BEEP MACROS ARE MOSTLY
*** AVAILABLE FOR DEBUGGING PURPOSES, AND ARE NOT
*** MEANT TO BE USED IN ACTUAL USER PROGRAMS
*** BEYOND THAT CAPACITY.
*
** THE _PRN MACRO   - PRINT
*
** THE _PRN MACRO SIMPLY PRINTS A LITERAL STRING
** TO THE SCREEN, AND HAS VERY LIMITED USE. WHEN
** OUTPUT IS MORE IMPORTANT THAN AN ERROR MESSAGE
** OR THE LIKE, USE THE MACROS PROVIDED BY THE
** STDIO LIBRARY.
*
         _PRN  "THIS IS A TEST.",8D8D
         _WAIT
*
* THE _WAIT MACRO  - WAIT
*
** LIKEWISE, THE _WAIT MACRO IS FOR USES OF
** CONVENIENCE ONLY, AND THE STDIO LIBRARY
** SHOULD BE USED INSTEAD WHENEVER POSSIBLE.
** NONETHELESS, THE _WAIT MACRO SIMPLY WAITS
** FOR A KEYPRESS BEFORE EXECUTION CONTINUES.
*
         _PRN  "THE WAIT MACRO",8D
         _PRN  "==============",8D8D
         _WAIT
*
* THE BEEP MACRO   - BEEP
*
** UNSURPRISINGLY, THE BEEP MACRO SENDS A STANDARD
** NUMBER OF TICKS TO THE SPEAKER TO PRODUCE A BEEP
** THAT CAN BE A LENGTH BETWEEN 1 AND 255.
*
         _PRN  "BEEEEEEEEEEEEEEP",8D8D
         BEEP  #255
         _WAIT
*
*``````````````````````````````*
* MEMORY MANIPULATION MACROS   *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
* THE DUMP MACRO   - MEMORY DUMP
*
** THE DUMP MACRO HAS ACTUALLY ALREADY BEEN
** USED TO SHOW THE CONTENTS RETURNED BY SOME
** OF THE 65C02 EMULATION MACROS. THE MACRO
** SIMPLY DUMPS A BLOCK OF MEMORY SPECIFIED BY
** THE PARAMETERS PASSED. THEREFORE:
*
         _PRN  "THE DUMP MACRO",8D
         _PRN  "==============",8D8D
         LDA   #$BB
         STA   $300
         LDA   #$AA
         STA   $301
         _PRN  "VALUES IN $301-$302:"
         DUMP  #$300;#2
         _WAIT
         _PRN  " ",8D8D
*
*``````````````````````````````*
* THE WEIRDOS: CLRHI, GBIT AND *
* NEGA MACROS.                 *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
*** THESE MACROS CAN BE HIGHLY USEFUL,
*** BUT SO FAR DO NOT FIT WELL WITH ANY
*** OTHER GROUPING OF MACROS.
*
* THE CLRHI MACRO  - CLEAR HIGH NIBBLE
*
** THE CLRHI MACRO CLEARS THE HIGH NIBBLE IN .A
** BYTE TO %0000. THIS HAS VARIOUS USES THAT NEED
** NOT BE GONE OVER HERE.
*
         _PRN  "THE CLRHI MACRO",8D
         _PRN  "===============",8D8D
         LDA   #$FF
         CLRHI
         STA   $300
         DUMP  #$300;#1
         _PRN  "^^ THE HIGH NIBBLE WAS CLEARED"
         _PRN  " ",8D8D
         _WAIT
*
* THE GBIT MACRO   - GET BIT VALUE
*
** THE GBIT MACRO RETURNS THE BIT VALUE
** OF THE GIVEN POSITION IN THE PARAMETER.
*
         _PRN  "THE GBIT MACRO",8D
         _PRN  "==============",8D8D
         GBIT  #0;%00100101
         STA   $300
         DUMP  #$300;#1
         _WAIT
*
** THE NEGA MACRO
*
** THE NEGA MACRO SIMPLY RETURNS IN .A THE NEGATIVE
** EQUIVALENT OF THE VALUE ALREADY IN .A.
*
         LDA   #$80
         NEGA
         STA   $300
         DUMP  #$300;#1
         _WAIT
*
         JSR   ]HOME
*
*``````````````````````````````*
* 8080 ALIAS MACROS            *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
*** THE 8080 ALIAS MACROS ARE APPROXIMATIONS
*** OF SOME OF THE INSTRUCTIONS IN THE 8080
*** INSTRUCTION SET, FOR USE BY THOSE WHO ARE
*** USED TO PROGRAMMING IN 8080 ASSEMBLY. NOTE
*** AGAIN THE WORD **APPROXIMATION**, AS I AM
*** NOT AN 8080 PROGRAMMER.
*
*** ALSO NOTE THAT YOU CAN ONLY USE ONE SET OF
*** ALIAS FILES AT A TIME; OTHERWISE, MACROS
*** WITH THE SAME NAME IN EACH ALIAS FILE WILL
*** CAUSE AN ASSEMBLY ERROR. THIS IS MOST NOTABLE
*** WITH INSTRUCTIONS LIKE 'RET' OR 'CALL."
*
*** SINCE ALL OF THESE MACROS ARE FAIRLY SIMPLE,
*** EXAMPLES ARE NOT GIVEN HERE. A FEW MACROS MAY
*** NEED EXAMPLES IN THE FUTURE, BUT THESE MOSTLY
*** WORK THE WAY YOU MIGHT EXPECT.
*
*
* CALL  - MIMICS JSR INSTRUCTION
* RET   - MIMICS RTS INSTRUCTION
* JA    - JMP IF .A > CMP RESULT
* JAE   - JMP IF .A => CMP RESULT
* JB    - JMP IF .A < CMP RESULT
* JBE   - JMP IF .A =< CMP RESULT
* JC    - JMP IF C = 1
* JE    - JMP IF BEQ
* JG    - JMP IF .A > CMP RESULT
* JGE   - JMP IF .A >= CMP RESULT
* JL    - JMP IF .A < CMP RESULT
* JLE   - JMP IF .A <= CMP RESULT
* JNC   - JMP IF C = 0
* JZ    - JMP IF Z = 0
* JNZ   - JMP IF Z = 1
* JS    - JMP IF SIGNED
* JNS   - JMP IF NOT SIGNED
* JO    - JMP IF V = 1
* JNO   - JMP IF V = 0
* ANC   - ADD NO CARRY
* SNC   - SUBTRACT NO CARRY
* PUSHA - PUSH ALL REGISTERS
* PULLA - PULL ALL REGISTERS
* POPA  - PULL ALL REGISTERS
*
*``````````````````````````````*
* Z80 ALIAS MACROS             *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
*** THESE MACROS ARE APPROXIMATIONS OF
*** SOME INSTRUCTIONS IN THE Z80 SET, AND
*** ARE MEANT TO AID THE PROGRAMMER WHO IS
*** USED TO A Z80 CPU. CURRENTLY, ALL OF THESE
*** EXAMPLES ARE COMMENTED OUT DUE TO THE FACT
*** THAT SOME OF THE MACRO NAMES CONFLICT WITH
*** THE 8080 ALIAS SET. TO SEE THESE IN ACTION,
*** YOU MUST FIRST COMMENT OUT THE 8080 EXAMPLES
*** AND THEN COMMENT OUT THE 8080 ALIAS FILE
*** INCLUDE AT THE END, WHILE ALSO UNCOMMENTING
*** THE Z80 ALIAS FILE INCLUSION.
*
* CALL  - JSR EQUIVALENT
* CPL   - INVERTS BITS IN .A
* JP    - JMP EQUIVALENT
* LD    - MOV VALUE FROM SRC TO DEST
* POP   - PULL FROM STACK
* RET   - RTS EQUIVALENT
* SCF   - C = 1
*
         JMP   REENTRY
*
*``````````````````````````````*
*        BOTTOM INCLUDES       *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
** BOTTOM INCLUDES
*
         PUT   MIN.LIB.REQUIRED.ASM
         USE   MIN.MAC.ALIAS.8080.ASM
         USE   MIN.MAC.ALIAS.Z80.ASM
*