*
*``````````````````````````````*
* DEMO.DOSFM.ASM               *
*                              *
* A DEMO FILE FOR THE DOS      *
* FILE MANAGER MACROS.         *
*                              *
* AUTHOR:    NATHAN RIGGS      *
* CONTACT:   NATHAN.RIGGS@     *
*            OUTLOOK.COM       *
*                              *
* DATE:      05-JUN-2021       *
* ASSEMBLER: MERLIN 8 PRO      *
* OS:        DOS 3.3           *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
** ASSEMBLER DIRECTIVES
*
         CYC   AVE
         EXP   OFF
         TR    ON
         DSK   DEMO.DOSFM
         OBJ   $BFE0
         ORG   $6000
*
*``````````````````````````````*
* TOP INCLUDES                 *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
         PUT   MIN.HEAD.REQUIRED.ASM
         USE   MIN.MAC.REQUIRED.ASM
         USE   MIN.MAC.DOSREQ.ASM
         USE   MIN.MAC.DOSFM.ASM
         PUT   MIN.HEAD.DOS.ASM
*
]HOME    EQU   $FC58
]ZSLOT   EQU   $6
]ZDRIVE  EQU   $2
*
*``````````````````````````````*
* PROGRAM MAIN BODY            *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
*``````````````````````````````*
* DOS FILE MANAGER MACROS      *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
** THE FOLLOWING MACROS BEING USED ARE EXAMPLES
** OF HOW TO USE EACH MACRO IN THE FILE MANAGER
** MACRO SELECTION OF THE DOS COLLECTION OF THE
** APPLEIIASM LIBRARY. NOTE THAT OTHER DEMO FILES
** EXIST FOR OTHER DOS FUNCTIONS, SUCH AS THE
** DEMO.DOSRWTS.ASM FILE FOR RWTS USAGE AND THE
** DEMO.DOSMORE.ASM FILE FOR MISCELLANEOUS MACROS
** THAT CAN BE OF USE WHILE USING APPLE DOS.
*
*``````````````````````````````*
* THE FCAT MACRO               *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
** THE FCAT MACRO SIMPLY RUNS THE CATALOG
** DOS COMMAND, WHICH LISTS THE FILES IN A
** DISK IN THE GIVEN SLOT AND DRIVE. A MORE
** ROBUST CATALOGING MACRO IS PLANNED AS PART
** OF THE DEMO.DOSMORE.ASM SELECTION.
*
         JSR   ]HOME
         _PRN  "THE FCAT MACRO",8D
         _PRN  "==============",8D8D
         _WAIT
         FCAT  #]ZSLOT;#]ZDRIVE
         _WAIT
*
*``````````````````````````````*
* THE FLOCK MACRO              *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
** THE FLOCK MACRO LOCKS A GIVEN FILE AT THE
** PROVIDED SLOT AND DRIVE NUMBERS.
*
         JSR   ]HOME
         _PRN  "THE FLOCK MACRO",8D
         _PRN  "===============",8D8D
         _PRN  "FIRST, CATALOG BEFORE LOCKING:",8D8D
         _WAIT
         FCAT  #]ZSLOT;#]ZDRIVE
         _WAIT
         _PRN  " ",8D
         _PRN  "NOW LOCK A FILE AND DO ANOTHER CAT:",8D8D
         FLOCK #FN5;#]ZSLOT;#]ZDRIVE
         _WAIT
         FCAT  #]ZSLOT;#]ZDRIVE
         _WAIT
*
*``````````````````````````````*
* THE FULCK MACRO              *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
** THE FULCK MACRO SIMPLY UNLOCKS A FILE IN
** THE GIVEN SLOT AND DRIVE.
*
         JSR   ]HOME
         _PRN  "THE FULCK MACRO",8D
         _PRN  "===============",8D8D
         _PRN  "FIRST, SHOW CATALOG WITH LOCKED FILE:",8D8D
         _WAIT
         FCAT  #]ZSLOT;#]ZDRIVE
         _WAIT
         _PRN  " ",8D
         _PRN  "NOW SHOW CATALOG WITH UNLOCKED FILE:",8D8D
         FULCK #FN5;#]ZSLOT;#]ZDRIVE
         _WAIT
         FCAT  #]ZSLOT;#]ZDRIVE
         _WAIT
*
*``````````````````````````````*
* THE FRENM MACRO              *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
** THE FRENM MACRO RENAMES A FILE FROM A SOURCE
** FILENAME TO A DESTINATION FILENAME, BOTH IN
** THE SAME SLOT AND DRIVE.
*
         JSR   ]HOME
         _PRN  "THE FRENM MACRO",8D
         _PRN  "===============",8D8D
         _PRN  "CATALOG WITH RENAMED FILE:",8D8D
         FRENM #FN5;#FN3;#]ZSLOT;#]ZDRIVE
         _WAIT
         FCAT  #]ZSLOT;#]ZDRIVE
         _PRN  " ",8D
         _WAIT
         _PRN  "CATALOG WITH FILE RENAMED BACK:",8D8D
         _WAIT
         FRENM #FN3;#FN5;#]ZSLOT;]ZDRIVE
         FCAT  #]ZSLOT;#]ZDRIVE
         _WAIT
*
*``````````````````````````````*
* THE FWRTB MACRO              *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
** THE FWRTB MACRO, WHICH STANDS FOR
** (F)ILE (WR)I(T)E (B)YTE, WRITES A SINGLE BYTE
** TO A FILE ON A DISK AT A GIVEN SLOT, DRIVE AND
** VOLUME. NOTE THAT THIS CAN BE ANY FILE TYPE.
*
** OTHER THAN THE RETURN CODE, THERE IS NO OUTPUT
** BEYOND THE "A" BEING PUT INTO THE FILE. WE CANNOT
** TEST THIS UNTIL WE ALSO USE A BYTE READING FUNCTION,
** WHICH WE WILL COVER NEXT.
*
** ALSO NOTE THAT THIS MAKES USE OF THE FOPEN AND FCLOS
** MACROS. THESE WILL BE EXHIBITED AGAIN TOWARD THE END
** OF THE DEMO.
*
         FOPEN #FN5;#]ZSLOT;#]ZDRIVE;#0;#0;#]TYP_TXT
         FWRTB #]ZSLOT;#]ZDRIVE;#0;#0;#0;#"A"
         FCLOS #FN5;#]ZSLOT;#]ZDRIVE
*
*``````````````````````````````*
* THE FRDB MACRO               *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
** THE FRDB MACRO, WHICH STANDS FOR
** (F)ILE (R)EA(D) (B)YTE, READS A BYTE FROM
** A FILE ON A DISK IN THE GIVEN SLOT, DRIVE AND
** VOLUME.
*
         JSR   ]HOME
         _PRN  "THE FRDB AND FWRTB MACROS",8D
         _PRN  "=========================",8D8D
         _PRN  "THE FIRST BYTE OF THE FILE IS: "
         FOPEN #FN5;#]ZSLOT;#]ZDRIVE;#0;#0;#]TYP_TXT
         FRDB  #]ZSLOT;#]ZDRIVE;#0;#0;#0;#0
         JSR   $FDF0
         FCLOS #FN5;#]ZSLOT;#]ZDRIVE
         _WAIT
*
*``````````````````````````````*
* THE FWRTR MACRO              *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
** THE FWRTR MACRO, WHICH STANDS FOR (F)ILE
** (WR)I(T)E RANGE, WRITES A RANGE OF BYTES IN
** MEMORY TO A FILE (THE TYPE IS UP TO THE USER).
** THIS IS USED IN CONJUNCTION WITH THE FRDR MACRO
** TO READ AND WRITE MULTIPLE BYTES FROM AND TO FILES.
*
** THIS MACRO ONLY OUTPUTS TO A FILE, SAVE FOR THE
** RETURN CODE STORED IN THE .X REGISTER. THE NEXT
** MACRO'S EXPLANATION WILL INCLUDE PRINTING THE TEXT
** SAVED TO A FILE HERE.
*
** NOTE THAT WHEN WRITING A RANGE OF BYTES, THE LENGTH
** OF THE BYTES TO BE WRITTEN SHOULD BE REDUCED BY ONE.
** THIS IS DUE TO AN INCONSISTENCY IN DOS.
*
         FOPEN #FN5;#]ZSLOT;#]ZDRIVE;#0;#0;#]TYP_TXT
         FWRTR #]ZSLOT;#]ZDRIVE;#0;#0;#0;#RANGE+1;#24
         FCLOS #FN5;#]ZSLOT;#]ZDRIVE
*
*``````````````````````````````*
* THE FRDR MACRO               *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
** THE FRDR MACRO, WHICH STANDS FOR (F)ILE
** (R)EA(D) (R)ANGE, READS A RANGE OF BYTES
** FROM A FILE ON A DISK AT A GIVEN SLOT AND DISK,
** STORING THE DATA AT A PROVIDED ADDRESS. IT
** IS IMPORTANT TO KNOW THE SIZE OF THE FILE
** PRIOR TO READING IT, SINCE READING PAST THE
** END OF THE FILE CAN HAVE UNPREDICTABLE
** CONSEQUENCES.
*
         JSR   ]HOME
         _PRN  "THE FRDR AND FWRTR MACROS",8D
         _PRN  "=========================",8D8D
         _PRN  "THE FILE CONTAINS:",8D8D
         FOPEN #FN5;#]ZSLOT;#]ZDRIVE;#0;#0;#0
         FRDR  #]ZSLOT;#]ZDRIVE;#0;#0;#0;#RDRANGE;#25
         FCLOS #FN5;#]ZSLOT;#]ZDRIVE
         LDY   #255
LOOP1
         INY
         LDA   RDRANGE,Y
         JSR   $FDF0
         CPY   #24
         BNE   LOOP1
         _WAIT
*
*``````````````````````````````*
* THE BLOAD MACRO              *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
** THE BLOAD MACRO WORKS MUCH LIKE THE BLOAD
** COMMAND IN DOS, BUT THERE IS NO BLOAD COMMAND
** FOR THE FILE MANAGER; IT HAS TO BE BUILT FROM
** THE ALREADY AVAILABLE COMMANDS.
*
** WHEN USED, THE BLOAD MACRO LOADS A BINARY FILE'S
** CONTENTS AND STORES THEM IN THE PROVIDED ADDRESS ON
** THE DISK IN THE GIVEN SLOT AND DRIVE. IF THE ADDRESS
** PASSED IS #0000, THEN THE MACRO/SUBROUTINE ASSUMES
** THAT THE DEFAULT ADDRESS WILL BE USED, WHICH IS
** STORED IN THE FIRST TWO BYTES OF THE FILE. THE LENGTH
** IS ALSO STORED AT THE BEGINNING OF THE FILE IN BYTES
** THREE AND FOUR, FOLLOWED BY THE ACTUAL DATA REQUESTED.
*
** IT SHOULD BE NOTED THAT THERE IS NO TEXT FILE
** EQUIVALENT TO BLOAD BECAUSE ANYONE WITH ANY SENSE
** WILL USE BINARY FILES TO STORE AND RETRIEVE DATA ON
** THE DISK, AS IT IS BOTH FASTER AND EASIER--TEXT
** FILES, FOR INSTANCE, DO NOT EASILY PROVIDE THE
** LENGTH OF THE FILE. IF A TEXT ROUTINE AS SUCH IS
** NEEDED, IT IS BEST TO BUILD YOUR OWN USING FWRTR,
** FRDR, FWRTB AND FRDB, AS YOU WILL LIKELY CREATE YOUR
** OWN STRUCTURE TO THE FILE.
*
         JSR   ]HOME
         _PRN  "THE BLOAD MACRO",8D
         _PRN  "===============",8D8D
         _PRN  "$300 NOW HOLDS:",8D8D
         BLOAD #FN6;#$0000;#]ZSLOT;#]ZDRIVE;#0
         DUMP  #$300;#$40
         _WAIT
*
*``````````````````````````````*
* THE BSAVE MACRO              *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
** THE BSAVE MACRO IS FUNCTIONALLY EQUIVALENT TO
** THE BSAVE COMMAND FROM THE DOS PROMPT. FIRST,
** THE PROVIDED ADDRESS IS STORED IN THE FIRST TWO
** BYTES OF THE FILE TO SUPPLY THE DEAULT LOADING
** ADDRESS. FOLLOWING THAT, THE LENGTH OF THE DATA
** IS STORED IN THE THIRD AND FOURTH BYTES. THE
** DATA IS THEN STORED FOLLOWING THESE BYTES. THIS
** IS HOW DOS ITSELF HANDLES BINARY FILES, AND
** YOUR BINARY FILES SHOULD ALSO FOLLOW THIS SCHEME
** TO AVOID ANGERING THE GODS.
*
** WE WON'T BE GOING THROUGH THE OUTPUT HERE, BUT IF
** YOU EXAMINE THE FILE WITH A TOOL LIKE CIDERPRESS,
** YOU WILL SEE THAT THE FILE SIMPLY CONTAINS THE
** VALUES #$01 TO #$40. BE FOREWARNED THAT YOU WILL
** NOT SEE THE FIRST FOUR BYTES, AS CIDERPRESS HIDES
** THESE TO PREVENT CONFUSION. YOU CAN VIEW THE FIRST
** FOUR BYTES BY LOOKING AT THE SECTOR THE FILE STARTS
** AT.
*
** NOTE AGAIN THAT AN EQUIVALENT MACRO OR SUBROUTINE
** IS NOT PROVIDED IN THIS COLLECTION.
*
         JSR   ]HOME
         _PRN  "THE BSAVE MACRO",8D
         _PRN  "===============",8D8D
         _PRN  "SAVING BINARY DATA..."
         BSAVE #FN7;#MEM40;#$39;#6;#2;#0
         _PRN  "DONE!!!",8D8D
         _WAIT
*
*``````````````````````````````*
* THE FOPEN AND FCLOS MACROS   *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
** THE FOPEN MACRO MUST BE RUN BEFORE READING
** OR WRITING A FILE, AND THE FCLOS MACRO MUST
** BE USED AFTERWARDS. IF FOPEN IS NEGLECTED, THE
** FILE WILL NOT BE CREATED; IF FCLOS IS NEGLECTED,
** THEN THAT FILE BUFFER WILL REMAIN IN USE. SINCE
** WE GENERALLY LIKE TO ACTUALLY USE OUR FILES, IT'S
** GOOD PRACTICE TO USE FOPEN AND FCLOS BECAUSE
** UM.. FILE INPUT AND OUTPUT WOULD NOT HAPPEN OTHERWISE.
*
** IF A FILE DOES NOT ALREADY EXIST, FOPEN AUTOMATICALLY
** CREATES A NEW ONE WITH THE PROVIDED FILENAME. HERE,
** WE WILL CREATE A FILE CALLED "TODELETE" THAT WILL BE
** DELETED IN THE NEXT MACRO'S EXPLANATION.
*
         JSR   ]HOME
         _PRN  "FOPEN AND FCLOS",8D
         _PRN  "===============",8D8D
         _PRN  "CATALOG BEFORE FILE CREATION:",8D8D
         _WAIT
         FCAT  #]ZSLOT;#]ZDRIVE
         _WAIT
         _PRN  " ",8D
         _PRN  "CATALOG AFTER FILE CREATION:",8D8D
         FOPEN #FN8;#]ZSLOT;#]ZDRIVE;#0;#0;#]TYP_TXT
         FCLOS #FN8;#]ZSLOT;#]ZDRIVE
         _WAIT
         FCAT  #]ZSLOT;#]ZDRIVE
         _WAIT
*
*``````````````````````````````*
* THE FDEL MACRO               *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
** LASTLY (FOR GOOD REASON), THE FDEL MACRO
** DELETES A FILE WITH THE GIVEN NAME IN THE
** NOTED SLOT AND DISK DRIVE. HERE, LET US
** DELETE THE LAST FILE WE CREATED, "TODELETE".
*
         JSR   ]HOME
         _PRN  "THE FDEL MACRO",8D
         _PRN  "==============",8D8D
         _PRN  "LOOK MA, NO TODELETE FILE!",8D8D
         FDEL  #FN8;#]ZSLOT;#]ZDRIVE
         _WAIT
         FCAT #]ZSLOT;#]ZDRIVE
         _WAIT
*
*``````````````````````````````*
* RWTS MACROS                  *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
** WHILE THE RWTS ROUTINE HAS NOT BEEN ABSTRACTED
** TOO MUCH, THIS IS FOR GOOD REASON: OUR HEADER
** FILE IS GETTING TOO BIG FOR ITS BRITCHES!
*
** THE RWTS ROUTINE LETS YOU READ AND WRITE DIRECTLY
** TO A DISK, BYPASSING CONVENTIONS USED BY DOS.
** IT GOES WITHOUT SAYING THAT THIS IS DANGEROUS: THE
** SMALLEST ACCIDENT CAN DESTROY A DISK FOR GOOD, SO
** USE THIS AT YOUR OWN DISCRETION.
*
** THERE ARE TWO MAIN MACROS FOR USING RWTS: THE SRWTS
** MACRO ( (S)ET RWTS ) AND THE GRWTS MACRO. THE SRWTS
** MACRO MUST ALWAYS BE RUN BEFORE GRWTS, AS IT SETS
** THE VARIABLES NEEDED FOR RWTS TO WORK. SINCE THERE
** IS SUCH A THREAT OF DISK CORRUPTION, WE ARE ONLY
** SHOWING HOW TO USE RWTS TO READ THE DISK, NOT WRITE
** IT; HOWEVER, THE PROCESS IS THE SAME FOR BOTH.
*
         JSR   ]HOME
         _PRN  "THE RWTS MACROS",8D
         _PRN  "===============",8D8D
         JSR   ]LOCRPL
         STY   ]RWTSPTR
         STA   ]RWTSPTR+1
*
         SRWTS #]ZSLOT;#]ZDRIVE;#0;#$11;#0;#$9000;#1
         GRWTS
         _PRN  "HERE'S THE DISK VTOC:",8D8D
         DUMP  #$9000;#$F
         DUMP  #$9010;#$F
         DUMP  #$9020;#$F
         DUMP  #$9030;#$F
         DUMP  #$9040;#$F
         DUMP  #$9050;#$F
         DUMP  #$9060;#$F
         DUMP  #$9070;#$F
         _PRN  " ",8D
         _PRN  ".....",8D
         _WAIT
*
         JSR   ]HOME
         _PRN  "FIN!",8D8D
*
EXIT
         JMP   $3D0
*
         PUT   MIN.SUB.FBLOAD.ASM
         PUT   SUB.FBSAVE.ASM
         PUT   MIN.LIB.REQUIRED.ASM
*
FN3      STR   "RENAMED"
FN5      STR   "WRITERANGE"
FN6      STR   "BINLOAD"
FN7      STR   "BINSAVE"
FN8      STR   "TODELETE"
MEM40    HEX   000102030405060708091A1B1C1D1E1F
         HEX   101112131415161718191A1B1C1D1E1F
         HEX   202122232425262728292A2B2C2D2E2F
         HEX   303132333435363738393A3B3C3D3E3F
RANGE    STR   "ONE RING TO RULE THEM ALL"
RDRANGE  DS    25
*
