Apple-2-SW/AppleIIAsm-Collection
1
0
Fork 0
mirror of https://github.com/nathanriggs/AppleIIAsm-Collection.git synced 2024-06-01 15:41:27 +00:00
Code Issues Projects Releases Wiki Activity
c28c9d87da
AppleIIAsm-Collection/documentation/AppleIIAsm Library Collection Technical Manual/0.6.1/35.0 Detailed_Reference_D6_DOS.md

4457 lines
164 KiB
Markdown
Raw Normal View History

preliminary update This is a preliminary update to all disks in the library, along with documentation up to the hires collection. This is simply to make sure the library is backed up; the complete rewrite of the library will be coming after the speaker routines are finished along with the rest of the documentation.
2021-05-31 22:27:42 +00:00
# Disk 6: Apple DOS
- [Part I: The DOS Collection](#part-i-the-dos-collection)
- [DOS Components](#dos-components)
- [DOS Header File](#dos-collection-header-file)
- [_SETRWTS](#the-_setrwts-subroutine)
- [_FMGETPARM](#the-_fmgetparm-subroutine)
- [_FMBUFSCAN](#the-_fmbufscan-subroutine)
- [_SETPBUFFS](#the-_setpbuffs-subroutine)
- [_NAMESTR](#the-_namestr-subroutine)
- [_NAMESTR2](#the-_namestr2-subroutine)
- [_FN2BUFF](#the-_fn2buff-subroutine)
- [_FMNM2](#the-_fmnm2-subroutine)
- [_BUFFCLEAR](#the-_buffclear-subroutine)
- [_FMPSET](#the-_fmpset-subroutine)
- [_FMPSETA](#the-_fmpseta-subroutine)
- [_FMPGET](#the-_fmpget-subroutine)
- [_FMPGETA](#the-_fmpgeta-subroutine)
- [Required DOS Macros](#required-dos-macros)
- [FMFIL](#the-fmfil-macro)
- [FMNAM](#the-fmnam-macro)
- [FRWB](#the-frwb-macro)
- [FWRTB](#the-fwrtb-macro)
- [FRDB](#the-frdb-macro)
- [FRWR](#the-frwr-macro)
- [FRDR](#the-frdr-macro)
- [FWRTR](#the-fwrtr-macro)
- [DOS File Manager Macros and Subroutines](#dos-file-manager-macros)
- [FCAT](#the-fcat-macro)
- [FULCK](#the-fulck-macro)
- [FLOCK](#the-flock-macro)
- [FDEL](#the-fdel-macro)
- [FVFY](#the-fvfy-macro)
- [FCLOS](#the-fclos-macro)
- [FRENM](#the-frenm-macro)
- [FOPEN](#the-fopen-macros)
- [BLOAD](#the-bload-macro)
- [FBLOAD](#the-fbload-subroutine)
- [BSAVE](#the-bsave-macro)
- [FBSAVE](#the-fbsave-subroutine)
- [Miscellaneous DOS Macros and Subroutines](#miscellaneous-dos-macros)
- [DVER](#the-dver-macro)
- [DOSIN](#the-dosin-macro)
- [ABAS](#the-abas-macro)
- [IBEX](#the-ibex-macro)
- [ABEX](#the-abex-macro)
- [Part II: DOS Collection Demos](#part-ii-dos-collection-demos)
- File Manager Demo
- Miscellaneous DOS Macros Demo
---
## Part I: The DOS Collection
The sixth disk of the AppleIIAsm library is dedicated to DOS operations. For the most part, the macros and subroutines here act as an abstraction layer between the lower level functions of DOS and the programmer. Unfortunately, this does carry with it some substantial overhead in terms of bytes used, but the ease of functionality is usually worth it unless memory is an extreme concerned. In such a case, the DOS collection can be narrowed to only the functions that are needed.
There are a number of macros and subroutines that are likely to go unused by most programmers, as they are mostly meant for internal use by the collection. These are covered as part of this documentation, but are not the primary focus of functionality. Those macros and subroutines that are the primary focus includes functions for the following:
- Disk Catalog
- File Locking and Unlocking
- File Deletion
- File Verification
- File Renaming
- File Opening and Closing
- Binary File Loading and Saving
- DOS Version Checking
- Integer and Applesoft Runtime Checking
- RWTS Access
---
## DOS Components
The DOS Collection contains the following components:
- A head file that includes a number of hooks, vectors and subroutines that are necessary for the operation of the whole collection.
- A macro library that is required to be included for using the rest of the collection.
- Two further sets of macro files, MAC.DOSFM.ASM and MAC.DOSMORE.ASM. The former contains macros used for managing files while the latter contains miscellaneous macros related to DOS.
- Two demo files that illustrate how all of the major macros are used. Note that this does not include macros that are meant for internal use.
---
## DOS Collection Header File
| Condition | Value |
| ------------- | ------------------------------------------------------------ |
| Name | File: HEAD.DOS.ASM |
| Type | Header File |
| Author | Nathan Riggs |
| Last Revision | 07-MAY-2021 |
| Assembler | Merlin 8 Pro |
| OS | Apple DOS 3.3 |
| Purpose | Provide appropriate hooks and routines for the DOS collection |
| Dependencies | none |
| Bytes | 584 |
| Notes | none |
| See Also | none |
---
*DETAILS*
The DOS Header file includes a number of required subroutines that are detailed later in this section.
`LISTING 6.00: HEAD.DOS.ASM Hooks & Vectors Source`
```assembly
*
*``````````````````````````````*
* HEAD.DOS.ASM *
* *
* THIS HEADER FILE IS USED BY *
* THE DOS COLLECTION AS A *
* REPOSITORY FOR VARIABLE *
* SPACE, HOOKS, SUBROUTINES *
* NECESSARY FOR THE REST OF *
* THE COLLECTION AND OTHER *
* MISCELLANEOUS TASKS. *
* *
* CURRENTLY, THIS COLLECTION *
* HAS QUITE A BIT OF OVERHEAD *
* IN TERMS OF BYTES. THIS WILL *
* HOPEFULLY BE REDUCED IN *
* FUTURE REVISIONS. *
* *
* NOTE THAT THE METHOD USED *
* FOR FINDING AN EMPTY FILE *
* BUFFER IS ADAPTED FROM A *
* LISTING IN DON WORTH'S AND *
* PETER LECHNER'S /BENEATH *
* APPLE DOS AND BENEAT APPLE *
* PRODOS 2020/. AS SUCH, THE *
* LICENSE MAY VARY. *
* *
* AUTHOR: NATHAN RIGGS *
* CONTACT: NATHAN.RIGGS@ *
* OUTLOOK.COM *
* *
* DATE: 07-MAY-2021 *
* ASSEMBLER: MERLIN PRO 8 *
* OS: DOS 3.3 *
* *
* SIZE: 584 BYTES (OVERHEAD) *
* *
* SUBROUTINES: *
* *
* _SETRWTS *
* _FMGETPARM *
* _FMBUFSCAN *
* _SETPBUFFS *
* _NAMESTR *
* _NAMESTR2 *
* _FN2BUFF *
* _FMNM2 *
* _BUFFCLEAR *
* _FMPSET *
* _FMPSETA *
* _FMPGET *
* _FMPGETA *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
*``````````````````````````````*
* RWTS EQUATES *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
]RWTSPTR EQU ADDR4 ; WORK POINTER FOR RWTS ROUTINES
]RWTSRD EQU 1 ; READ CODE FOR RWTS
]RWTSWR EQU 1 ; WRITE CODE FOR RWTS
]LOCRPL EQU $3E3 ; LOCATE RWTS PARAMLIST
]RWTS EQU $3D9 ; RWTS ROUTINE
*
]RPLIOB EQU $0 ; IOB TYPE, ALWAYS $01
]RPLSLT EQU $1 ; IOB SLOT * 16
]RPLDRV EQU $2 ; IOB DRIVE
]RPLVOL EQU $3 ; IOB VOLUME (#0 FOR ANY)
]RPLTRK EQU $4 ; IOB TRACK
]RPLSEC EQU $5 ; IOB SECTOR
]RPLDCT EQU $6 ; IOB ADDR TO DCT ($6,$7)
]RPLBUF EQU $8 ; IOB ADDR TO BUFFER ($8,$9)
]RPLSIZ EQU $A ; IOB SIZE ($A,$B)
]RPLCMD EQU $C ; IOB COMMAND
]RPLCNL EQU $00 ; NULL COMMAND
]RPLCRD EQU $01 ; READ COMMAND
]RPLCWR EQU $02 ; WRITE COMMAND
]RPLCFM EQU $04 ; FORMAT COMMAND
]RPLRCD EQU $D ; IOB RETURN CODE
]RPLRWP EQU $10 ; WRITED PROTECTED ERROR
]RPLRVM EQU $20 ; VOLUME MISMATCH ERROR
]RPLRDE EQU $40 ; DRIVE ERROR
]RPLRRE EQU $80 ; READ ERROR
]RPLTVL EQU $E ; IOB TRUE VOLUME
]RPLPSL EQU $F ; IOB PREVIOUS SLOT
]RPLPDR EQU $10 ; IOB PREVIOUS DRIVE
*
*``````````````````````````````*
* FILE PARAMETER LIST EQUATES *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
]FMPADDR EQU $3DC ; FILE MGR PARAM ADDR GET
]FMRUN EQU $3D6 ; RUN FILE MAMAGER ROUTINE
]DOSWARM EQU $3D0 ; DOS WARM START
*
]TYP_TXT EQU $00 ; FILE TYPE TEXT VALUE
]TYP_INT EQU $01 ; FILE TYPE INT VALUE
]TYP_APP EQU $02 ; FILE TYPE APPLESOFT VALUE
]TYP_BIN EQU $04 ; FILE TYPE BINARY VALUE
]TYP_REL EQU $08 ; FILE TYPE REL VALUE
]TYP_S EQU $10 ; FILE TYPE S VALUE
]TYP_A EQU $20 ; FILE TYPE A VALUE
]TYP_B EQU $40 ; FILE TYPE B VALUE
*
]SC_NON EQU $00 ; SUBCODE NOTHING VALUE
]SC_RWB EQU $01 ; SUBCODE READ OR WRITE A BYTE VALUE
]SC_RWR EQU $02 ; SUBCODE READ OR WRITE RANGE VALUE
]SC_PRWB EQU $03 ; SUBCODE POSITION THEN RW 1 BYTE VAL
]SC_PRWR EQU $04 ; SUBCODE POSITION THEN RW RANGE VAL
*
]FC_OPEN EQU $01 ; COMMAND CODE FOR OPEN
]FC_CLOS EQU $02 ; COMMAND CODE FOR CLOSE
]FC_READ EQU $03 ; COMMAND CODE FOR READ
]FC_WRIT EQU $04 ; COMMAND CODE FOR WRITE
]FC_DEL EQU $05 ; COMMAND CODE FOR DELETE
]FC_CAT EQU $06 ; COMMAND CODE FOR CATALOG
]FC_LOCK EQU $07 ; COMMAND CODE FOR LOCK
]FC_UNLK EQU $08 ; COMMAND CODE FOR UNLOCK
]FC_REN EQU $09 ; COMMAND CODE FOR RENAME
]FC_POS EQU $0A ; COMMAND CODE FOR POSITION
]FC_INIT EQU $0B ; COMMAND CODE FOR INIT
]FC_VFY EQU $0C ; COMMAND CODE FOR VERIFY
*
]P_CMD EQU $00 ; PARAM COMMAND OFFSET
]P_REC EQU $02 ; PARAM RECORD OFFSET
]P_VOL EQU $04 ; PARAM VOLUME OFFSET
]P_DRV EQU $05 ; PARAM DRIVE OFFSET
]P_SLOT EQU $06 ; PARAM SLOT OFFSET
]P_TYPE EQU $07 ; PARAM TYPE OFFSET
]P_NAMAD EQU $08 ; PARAM NAME BUFFER ADDRESS OFFSET
]P_WORK EQU $0C ; PARAM WORKAREA BUFFER ADDRESS OFFSET
]P_TSLS EQU $0E ; PARAM TSLS BUFFER ADDRESS OFFSET
]P_DATA EQU $10 ; PARAM DATA BUFFER ADDRESS OFFSET
]P_RETC EQU $0A ; PARAM RETURN CODE OFFSET
]P_RDWR EQU $00 ; READ OR WRITE OFFSET
]P_SUBC EQU $01 ; PARAM SUBCODE OFFSET
]P_BOFF EQU $04 ; PARAM BYTE OFFSET OFFSET
]P_RLEN EQU $06 ; PARAM RANGE LENGTH OFFSET
]P_RADDR EQU $08 ; PARAM RANGE ADDRESS OFFSET
]P_BYTE EQU $08 ; PARAM SINGLE WRITE BYTE OFFSET
]P_DPAGE EQU $01 ; PARAM 1ST DOS PAGE ADDR OFFSET
*
JMP __DHEXIT ; {6C3B} PASS OVER ROUTINES
*
MSLOT DFB $60 ; {0C1B} MASTER SLOT
MDRIVE DFB $2 ; {0C1B} MASTER DRIVE
MTRACK DFB $11 ; {0C1B} MASTER TRACK FOR RWTS
MSECTOR DFB $0 ; {0C1B} MASTER SECTOR FOR RWTS
MBUFFER DFB $9000 ; {0C1B} MASTER BUFFER ADDRESS FOR RWTS
DFB $9000/$100 ; {0C1B}
MCMD DFB $1 ; {0C1B} MASTER COMMAND FOR RWTS
MVOL DFB $0 ; {0C1B} MASTER VOLUME FOR RWTS
*
]TEMP HEX 0000 ; {0C2B}
]TEMP2 HEX 0000 ; {0C2B}
]FPARM HEX 0000 ; {0C2B} FILE MGR PARAM ADDRESS
]FNBUF HEX 0000 ; {0C2B} FILE NAME BUFFER
]FWORK HEX 0000 ; {0C2B} FILE WORKAREA BUFFER
]FDATA HEX 0000 ; {0C2B} FILE DATA BUFFER
]FTSLS HEX 0000 ; {0C2B} FILE TRACK/SECTOR LIST BUFFER
]FNAME DS 30 ; {0C30B} FILENAME TEMP STORAGE
]FNAME2 DS 30 ; {0C30B} SECOND FILENAME BUFFER
```
---
### THE _SETRWTS SUBROUTINE
_SUMMARY_
| Condition | Value |
| --------------- | -------------------------- |
| Name | `_SETRWTS` |
| Type | Subroutine |
| File | `HEAD.DOS.ASM` |
| Author | Nathan Riggs |
| Last Revision | 07-MAY-2021 |
| Assembler | Merlin Pro 8 |
| OS | Apple DOS 3.3 |
| Purpose | Set common RWTS parameters |
| Input | none |
| Output | none |
| Dependencies | none |
| Flags Destroyed | NZCV |
| Cycles | 142+ |
| Bytes | 78 |
| Notes | none |
| See Also | none |
---
*DETAILS*
The `_SETRWTS` routine sets the parameters for the **Input/Output Control Block** **(IOB)** before calling the **Read/Write Track/Sector** **(RWTS)** Routine. For the most part, this is used internally, and is not meant to be used by the end programmer. The following parameters are set in the **IOB** via the values given in global variables, which are set via another routine:
- Slot
- Drive
- Volume
- Track
- Sector
- Buffer
- Command
While the DOS collection makes knowing the format of the **Input/Output Control Block** unnecessary, there may be cases where one needs to access DOS at a lower level. Thus, the format of the **IOB** is listed here:
**INPUT / OUTPUT CONTROL BLOCK**
| Byte | Description |
|------------------|------------------------|
|00| Table type, must always be #00 |
|01| Slot number * 16 ($10, $20, $30, $40, $50, $60, $70) |
|02| Drive number |
|03| Volume number (#00 for any) |
|04| Track number |
|05| Sector number |
|06-07| Address of the Device Characteristics Table (DCT) |
|08-09| Address of the 256 byte buffer for READ/WRITE |
|0A| Unused |
|0B| Byte count for partial sector |
|0C| Command Code:<br />#$00 = SEEK<br />#$01 = READ<br />#$02 = WRITE<br />#$04 = FORMAT |
|0D| Return Code. The CARRY flag is set upon returning from RWTS to indicate that an error has occurred. The following values are passed here to communicate the type of error:<br />#$00 = No error<br />#$08 = Initialization error<br />#$10 = Write protect error<br />#$20 = Volume mismatch<br />#$40 = Drive error<br />#$80 = Read error |
|0E| Volume number last accessed |
|0F| Slot number last accessed * 16 |
|10| Drive number last accessed |
While the **Device Characteristics Table (DCT)** is almost always the same and should remain unchanged (for a Disk II drive), its format is also listed here for reference:
**DEVICE CHARACTERISTICS TABLE**
| Byte | Description |
|--------|-------------------|
|00| Device Type (should be #$00) |
|01| Phases per track (should be #$01) |
|02-03| Motor on time count (should be #$EFD8) |
`LISTING 6.01: HEAD.DOS.ASM _SETRWTS Routine Source`
```assembly
*
*``````````````````````````````*
* _SETRWTS *
* *
* SET THE RWTS IOB PARAMETERS *
* *
* INPUT *
* *
* NONE. *
* *
* DESTROY: NZCIDV *
* ^^^ ^ *
* *
* CYCLES: 142+ *
* SIZE: 78 BYTES *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
_SETRWTS
JSR ]LOCRPL ; {6C3B} LOCATE RWTS PARAMETER LIST
STY ]RWTSPTR ; {4C3B} SAVE POINTER LOW AND HIGH
STA ]RWTSPTR+1 ; {4C3B}
LDA MSLOT ; {4C3B} GET DEFAULT SLOT
ASL ; {2C1B} MULTIPLY BY 16
ASL ; {2C1B} TO GET APPROPRIATE VALUE
ASL ; {2C1B}
ASL ; {2C1B}
LDY #]RPLSLT ; {3C2B} LOAD IOB SLOT OFFSET
STA (]RWTSPTR),Y ; {6C2B} STORE SLOT VAL AT OFFSET
LDA MDRIVE ; {4C3B} LOAD DEFAULT DRIVE
LDY #]RPLDRV ; {3C2B} GET IOB DRIVE OFFSET
STA (]RWTSPTR),Y ; {6C2B} STORE DRIVE IN IOB
LDA MTRACK ; {4C3B} GET MASTER TRACK
LDY #]RPLTRK ; {3C2B} OFFSET IN PARAM LIST
STA (]RWTSPTR),Y ; {6C2B} STORE TRACK IN IOB
LDA MSECTOR ; {4C3B} GET MASTER SECTOR
CMP #16 ; {3C2B} BIGGER THAN 16?
BCC :SOK ; {3C2B} NOPE, IT'S OKAY
LDA #0 ; {3C2B} ELSE YES, SO CLEAR
STA MSECTOR ; {4C3B} MASTER SECTOR
:SOK LDY #]RPLSEC ; {3C2B} OFFSET IN PARMLIST
STA (]RWTSPTR),Y ; {6C2B} STORE SECTOR IN IOB
LDY #]RPLBUF ; {3C2B} OFFSET IN PARAMLIST
LDA MBUFFER ; {4C3B} GET LOW BYTE OF BUFFER ADDR
STA (]RWTSPTR),Y ; {6C2B} STORE LOW BYTE OF BUFF IN IOB
INY ; {2C1B} INCREASE OFFSET
LDA MBUFFER+1 ; {4C3B} GET HIGH BYTE
STA (]RWTSPTR),Y ; {6C2B} STORE HIGH BYTE IN IOB
LDA MCMD ; {4C3B} GET RWTS MASTER COMMAND
LDY #]RPLCMD ; {3C2B} OFFSET OF PARMLIST
STA (]RWTSPTR),Y ; {6C2B} STORE COMMAND IN IOB
LDA MVOL ; {4C3B} GET RWTS MASTER VOLUME
LDY #]RPLVOL ; {3C2B} OFFSET
STA (]RWTSPTR),Y ; {6C2B} STORE VOLUME IN IOB
RTS ; {6C1B}
```
---
### THE _FMGETPARM SUBROUTINE
_SUMMARY_
| Condition | Value |
| --------------- | ------------------- |
| Name | `_FMGETPARM` |
| Type | Subroutine |
| File | `HEAD.DOS.ASM` |
| Author | Nathan Riggs |
| Last Revision | 07-MAY-2021 |
| Assembler | Merlin Pro 8 |
| OS | Apple DOS 3.3 |
| Purpose | Get the FPL Address |
| Input | none |
| Output | none |
| Dependencies | none |
| Flags Destroyed | NZCV |
| Cycles | 20+ |
| Bytes | 10 |
| Notes | none |
| See Also | `_SETPBUFFS` |
---
*DETAILS*
The `_FMGETPARM` subroutine gets the address of the **File Manager Parameter List (FPL)** and returns it in **.Y** (low byte) and **.A** (high byte), with the addition of storing it in the ]FPARM variable space. This is different from the usual passing of addresses in **.A** and **.X** due to the nature of how DOS was programmed; since this is used internally, however, this should not present a problem.
If the format of the **File Manager Parameter List (FPL)** is needed, it is available under the `SETPBUFFS` entry.
`LISTING 6.02: HEAD.DOS.ASM _FMGETPARM Routine Source`
```assembly
*
*``````````````````````````````*
* _FMGETPARM (NATHAN RIGGS) *
* *
* GET THE ADDRESS OF THE FILE *
* PARAMETER LIST. *
* *
* INPUT *
* *
* NONE. *
* *
* DESTROY: NZCIDV *
* ^^^ ^ *
* *
* CYCLES: 20+ *
* SIZE: 10 BYTES *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
_FMGETPARM
*
JSR ]FMPADDR ; {6C3B} GET PARAM ADDRESS
STA ]FPARM+1 ; {4C3B} STORE HIGH BYTE
STY ]FPARM ; {4C3B} STORE LOW BYTE
RTS ; {6C1B}
*
```
---
### THE _FMBUFSCAN SUBROUTINE
_SUMMARY_
| Condition | Value |
| --------------- | ----------------------- |
| Name | `_FMBUFSCAN` |
| Type | Subroutine |
| File | `HEAD.DOS.ASM` |
| Author | Nathan Riggs |
| Last Revision | 07-MAY-2021 |
| Assembler | Merlin Pro 8 |
| OS | Apple DOS 3.3 |
| Purpose | Find a free file buffer |
| Input | none |
| Output | none |
| Dependencies | none |
| Flags Destroyed | NZCV |
| Cycles | 211+ |
| Bytes | 117 |
| Notes | none |
| See Also | `_BUFFCLEAR` |
---
*DETAILS*
The `_FMBUFSCAN` subroutine finds an open file buffer and stores the addresses to various necessary sections in the appropriate memory locations. Primarily, this includes the **File Workarea**, the **Filename Buffer**, the **Data Sector Buffer**, and the **T/S List Sector (TSLS) Buffer**. If no file buffers are available then the carry is set to indicate an error, and the memory locations are all cleared to zero. A file buffer is considered clear if the first byte of the filename buffer carries a value of **#0**.
While the DOS collection makes it unnecessary to know the inner workings of DOS, it may be useful for the programmer to know the format of each file buffer. The format is as follows:
|BYTE | DESCRIPTION|
|--------------|--------------------|
|000-0FF | Data Sector Buffer (256 bytes)|
|100-1FF | T/S List Sector Buffer (256 bytes)|
|200-22C | File Manager Workarea Buffer (45 bytes)|
|22D-24A | File Name Buffer (30 bytes)|
|24B-24C | Address of File Manager Work Area Buffer|
|24D-24E | Address of T/S List Sector Buffer|
|24F-250 | Address of Data Sector Buffer|
|251-252 | Address of the File Name Buffer in the next File Buffer. If this is the last buffer available, then the value is #0000.|
`LISTING 6.03: HEAD.DOS.ASM _FMBUFSCAN Routine Source`
```assembly
*
*``````````````````````````````*
* _FMBUFSCAN (NATHAN RIGGS) *
* *
* FIND A FREE FILE BUFFER. IF *
* NONE EXISTS, RETURN #0. *
* *
* INPUT *
* *
* NONE. *
* *
* DESTROY: NZCIDV *
* ^^^ ^ *
* *
* CYCLES: 211+ *
* SIZE: 117 BYTES *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
_FMBUFFSCAN
*
LDA $3D2 ; {4C3B} LOCATE DOS LOAD POINT
STA ADDR1+1 ; {3C2B} STORE THIS AS FIRST FNAME BUFF
LDY #0 ; {3C2B} LOW BYTE SHOULD START AT 0
STY ADDR1 ; {3C2B}
:GBUF0
LDA (ADDR1),Y ; {6C2B} LOCATE NEXT DOS BUFFER
PHA ; {3C1B} TEMPORARILY HOLD
INY ; {2C1B} INCREASE .Y INDEX
LDA (ADDR1),Y ; {6C2B} LOAD HIGH BYTE OF ADDRESS
STA ADDR1+1 ; {3C2B} STORE HIGH BYTE IN ZERO PAGE
PLA ; {3C1B} PULL BACK EARLIER VALUE
STA ADDR1 ; {3C2B} STORE AS LOW BYTE ON ZERO
BNE :GBUF ; {4C3B} FOUND A BUFFER
LDA ADDR1+1 ; {3C2B} ELSE LOAD HIGH BYTE
BEQ :NBUF ; {4C3B} IF ZERO, NO BUFFER
:GBUF
LDY #0 ; {3C2B} GET FILENAME FIRST CHAR
LDA (ADDR1),Y ; {6C2B} FROM THE BUFFER
BEQ :GOTBUF ; {3C2B} IF 0, THEN BUFFER IS UNUSED
LDY #36 ; {3C2B} IF NOT, SKIP TO NEXT LINK
BNE :GBUF0 ; {3C2B} AND RERUN THE SEARCH LOOP
:GOTBUF
LDA ADDR1 ; {3C2B} LOAD FNAME BUFFER LOW BYTE
STA ]FNBUF ; {4C3B} STORE FILENAME BUFFER ADDRESS
LDA ADDR1+1 ; {3C2B} READ THE HIGH BYTE
STA ]FNBUF+1 ; {4C3B} AND STORE AS POINTER ADDRESS
LDY #30 ; {3C2B} INDEX TO FILE MANAGER WORKAREA
LDA (ADDR1),Y ; {6C2B} FOR CONVENIENT STORAGE
STA ]FWORK ; {4C3B} STORE WORKAREA POINTER
INY ; {2C1B} INCREASE .Y INDEX
LDA (ADDR1),Y ; {6C2B} LOAD THE HIGH BYTE
STA ]FWORK+1 ; {4C3B} AND HOLD IT IN ]FWORK
INY ; {2C1B} POINTER TO T/S LIST SECTOR BUFF
LDA (ADDR1),Y ; {6C2B} LOAD LOW BYTE OF TS BUFFER
STA ]FTSLS ; {4C3B} HOLD POINTER IN MEMORY
INY ; {2C1B} INCREASE .Y INDEX
LDA (ADDR1),Y ; {6C2B} LOAD HIGH BYTE
STA ]FTSLS+1 ; {4C3B} AND HOLD
INY ; {6C2B} INC POINTER TO DATA BUFFER
LDA (ADDR1),Y ; {6C2B} LOAD LOW BYTE OF ADDRESS
STA ]FDATA ; {4C3B} STORE IN MEMORY
INY ; {2C1B} INCREASE .Y INDEX
LDA (ADDR1),Y ; {6C2B} LOAD THE HIGH BYTE
STA ]FDATA+1 ; {4C3B} AND STORE AS WELL
CLC ; {2C1B} CLR CARRY TO INDICATE NO ERR
RTS ; {6C1B}
:NBUF
LDA #0 ; {4C3B} LOAD #0 AND CLEAR OUT
STA ]FNBUF ; {4C3B} ALL OF THE ADDRESS POINTERS
STA ]FNBUF+1 ; {4C3B}
STA ]FWORK ; {4C3B}
STA ]FWORK+1 ; {4C3B}
STA ]FTSLS ; {4C3B}
STA ]FTSLS+1 ; {4C3B}
STA ]FDATA ; {4C3B}
STA ]FDATA+1 ; {4C3B}
SEC ; {2C1B} SET CARRY TO INDICATE ERR
RTS ; {6C1B}
*
```
---
### THE _SETPBUFFS SUBROUTINE
_SUMMARY_
| Condition | Value |
| --------------- | -------------------------------------------------------- |
| Name | `_SETPBUFFS` |
| Type | Subroutine |
| File | `HEAD.DOS.ASM` |
| Author | Nathan Riggs |
| Last Revision | 07-MAY-2021 |
| Assembler | Merlin Pro 8 |
| OS | Apple DOS 3.3 |
| Purpose | Set the buffers in the File Manager Parameter List (FPL) |
| Input | none |
| Output | none |
| Dependencies | none |
| Flags Destroyed | NZCV |
| Cycles | 119+ |
| Bytes | 64 |
| Notes | none |
| See Also | `_FMBUFSCAN` |
---
*DETAILS*
The `_SETPBUFFS` subroutine sets the buffer addresses in the **File Manager Parameter List (FPL)** to the appropriate addresses in an open file buffer, as set by `_FMBUFSCAN`. The buffers set include the **Filename Buffer**, the **TS/LS Buffer**, **Data Sector Buffer** and the **File Workarea Buffer**.
The format of the **FPL** slightly changes depending on the command being called, and the number of minor differences are too many to list here for any useful purposes. For a detailed list of how the **FPL** is formatted according to call type, see Don Worth's and Pieter Lechner's *Beneath Apple DOS*. However, there is a general format to the **FPL**, as follows:
**File Manager Parameter List (FPL)**
| Byte | Description |
|--------|-------------------|
|00| Command/Call Type:<br />$01 = OPEN<br />$02 = CLOSE<br />$03 = READ<br />$04 = WRITE<br />$05 = DELETE<br />$06 = CATALOG<br />$07 = LOCK<br />$08 = UNLOCK<br />$09 = RENAME<br />$0A = POSITION<br />$0B = INIT<br />$0C = VERIFY |
|01| Sub-command/Sub-Call Type for READ or WRITE<br />$00 = No operation<br />$01 = READ or WRITE a byte<br />$02 = READ or WRITE a range of bytes<br />$03 = POSITION then READ or WRITE a byte<br />$04 = POSITION then READ or WRITE a range of bytes |
|02-09| Parameters change based on call type. |
|0A| Return Code. Upon returning from the file manager, the CARRY flag is set to indicate a non-zero return code is present. The number here can then be accessed to further understand the return status.<br />$00 = No errors<br />$01 = Language Not Available<br />$02 = Bad call type<br />$03 = Bad sub-call type<br />$04 = Write protected<br />$05 = End of Data<br />$06 = File not found<br />$07 = Volume mismatch<br />$08 = Disk I/O error<br />$09 = Disk full<br />$0A = File locked |
|0B| Unused |
|0C-0D| Address of File Manager Workarea Buffer |
|0E-0F| Address of the TS/LS Buffer |
|10-11| Address of the Data Sector Buffer |
`LISTING 6.04: HEAD.DOS.ASM _SETPBUFFS Routine Source`
```assembly
*
*``````````````````````````````*
* _SETPBUFFS (NATHAN RIGGS) *
* *
* SET THE FILENAME BUFFER, *
* TS/LS BUFFER, DATA BUFFER *
* AND THE FILE WORKAREA *
* BUFFER. *
* *
* INPUT *
* *
* NONE. *
* *
* DESTROY: NZCIDV *
* ^^^ ^ *
* *
* CYCLES: 119+ *
* SIZE: 64 BYTES *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
_SETPBUFFS
*
LDA ]FPARM ; {4C3B} GET PARAMATER ADDRESS LOW BYTE
STA ADDR1 ; {3C2B} AND HOLD IN ZERO PAGE
LDA ]FPARM+1 ; {4C3B} LOAD HIGH BYTE
STA ADDR1+1 ; {3C2B} INTO ZERO PAGE TOO
LDY #$10 ; {3C2B} POINT TO DATA BUFFER POINTER
LDA ]FDATA ; {4C3B} LOAD DATA BUFFER ADDRESS LOW
STA (ADDR1),Y ; {6C2B} COPY POINTER TO PARAM LOCATION
INY ; {2C1B} INCREASE .Y INDEX
LDA ]FDATA+1 ; {4C3B} LOAD DATA BUFFER ADDR HIGH BYTE
STA (ADDR1),Y ; {6C2B} COPY TO PARAM LOCATION
LDY #$08 ; {3C2B} POINT TO FILENAME BUFFER
LDA ]FNBUF ; {4C3B} LOAD FILENAME BUFFER POINTER ADDR
STA (ADDR1),Y ; {6C2B} AND COPY TO PARAM LOCATION
INY ; {2C1B} INCREASE .Y POINTER
LDA ]FNBUF+1 ; {4C3B} LOAD THE HIGH BYTE
STA (ADDR1),Y ; {6C2B} AND COPY AS WELL
LDY #$0E ; {3C2B} T/S LIST SECTOR BUFFER POINTER
LDA ]FTSLS ; {4C3B} LOAD CURRENT POINTER LOW BYTE
STA (ADDR1),Y ; {6C2B} AND COPY TO PARAM LOCATION
INY ; {2C1B} INCREASE .Y INDEX
LDA ]FTSLS+1 ; {3C2B} LOAD THE HIGH BYTE
STA (ADDR1),Y ; {6C2B} AND COPY TO PARAM LOCATION
LDY #$0C ; {3C2B} WORKAREA BUFFER OFFSET IN PARAM
LDA ]FWORK ; {4C3B} LOAD CURRENT WORKAREA POINTER
STA (ADDR1),Y ; {6C2B} COPY TO PARAMETER LIST
INY ; {2C1B} INCREASE .Y INDEX
LDA ]FWORK+1 ; {4C3B} LOAD HIGH BYTE
STA (ADDR1),Y ; {6C2B} AND COPY AS WELL
*
RTS ; {6C3B}
*
```
---
### THE _NAMESTR SUBROUTINE
_SUMMARY_
| Condition | Value |
| --------------- | ------------------------------------------------------------ |
| Name | `_NAMESTR` |
| Type | Subroutine |
| File | `HEAD.DOS.ASM` |
| Author | Nathan Riggs |
| Last Revision | 07-MAY-2021 |
| Assembler | Merlin Pro 8 |
| OS | Apple DOS 3.3 |
| Purpose | Copy filename from standard string format to the 30-byte string expected by DOS |
| Input | none |
| Output | none |
| Dependencies | none |
| Flags Destroyed | NZCV |
| Cycles | 64+ |
| Bytes | 42 |
| Notes | none |
| See Also | `_NAMESTR2` `_FN2BUFF` `_FMNM2` |
---
*DETAILS*
The `_NAMESTR` subroutine is an internal procedure for transferring a standard preceding length-byte string to a temporary fixed 30-byte memory address that fills the empty bytes with spaces (this is determined by subtracting the string length from 30, which equals the number of trailing spaces needed). This subroutine should be called prior to calling the File Manager, given that the filename is not the same as the previous call.
`LISTING 6.05: HEAD.DOS.ASM _NAMESTR Routine Source`
```assembly
*
*``````````````````````````````*
* _NAMESTR (NATHAN RIGGS) *
* *
* COPY FILENAME FROM STANDARD *
* STRING TO THE 30-BYTE STRING *
* EXPECTED BY DOS IN A TEMP *
* MEMORY AREA. *
* *
* INPUT *
* *
* .A = FILENAME STR ADDR LOW *
* .X = HIGH BYTE *
* *
* DESTROY: NZCIDV *
* ^^^ ^ *
* *
* CYCLES: 64+ *
* SIZE: 42 BYTES *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
_NAMESTR
*
LDY #0 ; {3C2B}
STA ADDR1 ; {3C2B} CLEAR OUT ZERO LOCATION
STX ADDR1+1 ; {3C2B}
LDA (ADDR1),Y ; {6C2B} GET STRING LENGTH
STA BPAR1 ; {3C2B} HOLD TEMP IN ZERO PAGE
LDY #0 ; {3C2B} RESET .Y INDEX
LDX #255 ; {3C2B} SET .X INDEX TO -1
:_NSLP1
INX ; {2C1B} INCREASE .X INDEX
INY ; {2C1B} INCREASE .Y INDEX
LDA (ADDR1),Y ; {6C2B} GET CHARACTER
STA ]FNAME,X ; {5C3B} STORE AT Y-1 LOC IN HOLD AREA
CPX #29 ; {3C2B} COMPARE TO MAX STRING LENGTH
BEQ :_NSEXIT ; {3C2B} IF MAX IS REACHED, EXIT
CPY BPAR1 ; {3C2B} OTHERWISE COMPARE TO STRING LENGTH
BNE :_NSLP1 ; {3C2B} IF NOT EQUAL, RELOOP TO NEXT CHAR
:_NSLP2
INX ; {2C1B} STILL INCREASE .X INDEX
LDA #" " ; {4C3B} NEXT CHAR IS SPACE
STA ]FNAME,X ; {5C3B} STORE IN NAME AREA AT .X
CPX #29 ; {3C2B} CHECK NEW STRING LENGTH
BNE :_NSLP2 ; {3C2B} IF < 30, KEEP LOOPING
:_NSEXIT
RTS ; {6C1B}
*
```
---
### THE _NAMESTR2 SUBROUTINE
_SUMMARY_
| Condition | Value |
| --------------- | ------------------------------------------------------------ |
| Name | `_NAMESTR2` |
| Type | Subroutine |
| File | `HEAD.DOS.ASM` |
| Author | Nathan Riggs |
| Last Revision | 07-MAY-2021 |
| Assembler | Merlin Pro 8 |
| OS | Apple DOS 3.3 |
| Purpose | Copy second filename from standard string <br />format to the 30-byte string expected by DOS |
| Input | none |
| Output | none |
| Dependencies | none |
| Flags Destroyed | NZCV |
| Cycles | 64+ |
| Bytes | 42 |
| Notes | none |
| See Also | `_NAMESTR` `_FN2BUFF` `_FMNM2` |
---
*DETAILS*
The `_NAMESTR2` subroutine accomplishes the same task as `_NAMESTR`, but does so for a second filename that is needed for procedures like renaming a file. This subroutine will likely be merged with the `_NAMESTR` subroutine in future revisions.
`LISTING 6.06: HEAD.DOS.ASM _NAMESTR2 Routine Source`
```assembly
*
*``````````````````````````````*
* _NAMESTR2 (NATHAN RIGGS) *
* *
* FULFILLS THE SAME FUNCTION *
* AS _NAMESTR, EXCEPT FOR A *
* SECOND STRING USED BY CMDS *
* LIKE RENAME. *
* *
* .A = STRING ADDR LOW BYTE *
* .X = STRING ADDR HIGH BYTE *
* *
* DESTROY: NZCIDV *
* ^^^ ^ *
* *
* CYCLES: 64+ *
* SIZE: 42 BYTES *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
_NAMESTR2
*
LDY #0 ; {3C2B}
STA ADDR1 ; {3C2B} CLEAR OUT ZERO LOCATION
STX ADDR1+1 ; {3C2B}
LDA (ADDR1),Y ; {6C3B} GET STRING LENGTH
STA BPAR1 ; {3C2B} HOLD TEMP IN ZERO PAGE
LDY #0 ; {3C2B} RESET .Y INDEX
LDX #255 ; {3C2B} SET .X INDEX TO -1
:_NSLP1
INX ; {2C1B} INCREASE .X INDEX
INY ; {2C1B} INCREASE .Y INDEX
LDA (ADDR1),Y ; {6C2B} GET CHARACTER
STA ]FNAME2,X ; {5C2B} STORE AT Y-1 LOC IN HOLD AREA
CPX #29 ; {3C2B} COMPARE TO MAX STRING LENGTH
BEQ :_NSEXIT ; {3C2B} IF MAX IS REACHED, EXIT
CPY BPAR1 ; {3C2B} OTHERWISE COMPARE TO STRING LENGTH
BNE :_NSLP1 ; {3C2B} IF NOT EQUAL, RELOOP TO NEXT CHAR
:_NSLP2
INX ; {2C1B} STILL INCREASE .X INDEX
LDA #" " ; {4C3B} NEXT CHAR IS SPACE
STA ]FNAME2,X ; {5C2B} STORE IN NAME AREA AT .X
CPX #29 ; {2C2B} CHECK NEW STRING LENGTH
BNE :_NSLP2 ; {3C2B} IF < 30, KEEP LOOPING
:_NSEXIT
RTS ; {6C1B}
*
```
---
### THE _FN2BUFF SUBROUTINE
_SUMMARY_
| Condition | Value |
| --------------- | ------------------------------------------------------- |
| Name | `_FN2BUFF` |
| Type | Subroutine |
| File | `HEAD.DOS.ASM` |
| Author | Nathan Riggs |
| Last Revision | 07-MAY-2021 |
| Assembler | Merlin Pro 8 |
| OS | Apple DOS 3.3 |
| Purpose | Copy temporary 30-byte filename to the filename buffer. |
| Input | none |
| Output | none |
| Dependencies | none |
| Flags Destroyed | NZCV |
| Cycles | 41+ |
| Bytes | 22 |
| Notes | none |
| See Also | `_NAMESTR` `_NAMESTR2` `_FMNM2` |
---
*DETAILS*
The `_FN2BUFF` subroutine simply copies the 30-byte filename created by `_NAMESTR` to the filename buffer for use by the File Manager.
`LISTING 6.07: HEAD.DOS.ASM _FN2BUFF Routine Source`
```assembly
*
*``````````````````````````````*
* _FN2BUFF (NATHAN RIGGS) *
* *
* MOVE THE TEMPORARY 30-BYTE *
* FILENAME STRING INTO THE *
* FILENAME BUFFER OF THE FILE *
* BUFFER IN USE. *
* *
* INPUT *
* *
* NONE. *
* *
* DESTROY: NZCIDV *
* ^^^ ^ *
* CYCLES: 41+ *
* SIZE: 22 BYTES *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
_FN2BUFF
*
LDA ]FNBUF ; {4C3B} LOAD FILENAME BUFFER ADDR
STA ADDR2 ; {3C2B} STORE LOW IN ZERO
LDA ]FNBUF+1 ; {4C3B}
STA ADDR2+1 ; {3C2B} STORE HIGH IN ZERO
LDY #255 ; {3C2B} SET .Y INDEX TO -1
:_LPC1
INY ; {2C1B} INCREASE .Y INDEX
LDA ]FNAME,Y ; {5C2B} GET CHAR STORED IN NAME AREA
STA (ADDR2),Y ; {6C2B} STORE IN FILENAME BUFFER
CPY #29 ; {2C2B} IS THE END OF STRING REACHED?
BNE :_LPC1 ; {3C2B} IF NO, KEEP LOOPING
RTS ; {6C1B}
*
```
---
### THE _FMNM2 SUBROUTINE
_SUMMARY_
| Condition | Value |
| --------------- | ------------------------------------------------------------ |
| Name | `_FMNM2` |
| Type | Subroutine |
| File | `HEAD.DOS.ASM` |
| Author | Nathan Riggs |
| Last Revision | 07-MAY-2021 |
| Assembler | Merlin Pro 8 |
| OS | Apple DOS 3.3 |
| Purpose | Register the address of the second filename<br /> to be used by the File Manager. |
| Input | none |
| Output | none |
| Dependencies | none |
| Flags Destroyed | NZCV |
| Cycles | 55+ |
| Bytes | 30 |
| Notes | none |
| See Also | `_NAMESTR` `_NAMESTR2` `_FN2BUFF` |
---
*DETAILS*
The `_FMNM2` subroutine is functionally equivalent to the `_FN2BUFF` subroutine except for a second filename, which is usually a destination filename. Although equivalent, the process for `_FMNM2` is different than `_FN2BUFF` and therefore cannot be merged into a single subroutine.
`LISTING 6.08: HEAD.DOS.ASM _FMNM2 Routine Source`
```assembly
*
*``````````````````````````````*
* _FMNM2 (NATHAN RIGGS) *
* *
* REGISTER THE ADDRESS OF THE *
* SECOND FILENAME IN THE FILE *
* PARAMETER LIST. *
* *
* INPUT *
* *
* NONE. *
* *
* DESTROY: NZCIDV *
* ^^^ ^ *
* CYCLES: 55+ *
* SIZE: 30 BYTES *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
_FMNM2
LDA #]FNAME2 ; {3C2B}
LDX #>]FNAME2 ; {3C2B}
STA ADDR2 ; {3C2B} LOW BYTE OF REC ADDRESS IN .A
STX ADDR2+1 ; {3C2B} HIGH BYTE IN .X
LDA ]FPARM ; {4C3B} LOAD PARAM ADDRESS
STA ADDR1 ; {3C2B} AND HOLD IN ZERO PAGE
LDA ]FPARM+1 ; {4C3B} ALSO DO FOR HIGH BYTE
STA ADDR1+1 ; {3C2B}
LDY #$02 ; {3C2B} OFFSET TO THE RECORD VARIABLE
LDA ADDR2 ; {3C2B} LOAD LOW BYTE
STA (ADDR1),Y ; {6C2B} AND STORE IN PARAM LIST
INY ; {2C1B} INCREASE .Y INDEX
LDA ADDR2+1 ; {3C2B} LOAD HIGH BYTE
STA (ADDR1),Y ; {6C2B} AND STORE IN PARAM LIST
RTS ; {6C1B}
*
```
---
### THE _BUFFCLEAR SUBROUTINE
_SUMMARY_
| Condition | Value |
| --------------- | -------------------------------------------- |
| Name | `_BUFFCLEAR` |
| Type | Subroutine |
| File | `HEAD.DOS.ASM` |
| Author | Nathan Riggs |
| Last Revision | 07-MAY-2021 |
| Assembler | Merlin Pro 8 |
| OS | Apple DOS 3.3 |
| Purpose | Clear the current file buffer for use again. |
| Input | none |
| Output | none |
| Dependencies | none |
| Flags Destroyed | NZCV |
| Cycles | 31+ |
| Bytes | 17 |
| Notes | none |
| See Also | `_FMBUFFSCAN` |
---
*DETAILS*
The `_BUFFCLEAR` subroutine clears out the last used file buffer for use again in the future. It does this by replacing the first byte in the filename buffer with the value **#$00**, which indicates to DOS that the buffer is free. This subroutine should be called whenever a program is finished using a file and closes it; otherwise, the file buffer will not be cleared, and multiple uses of the file buffers will eventually result in error.
`LISTING 6.09: HEAD.DOS.ASM _BUFFCLEAR Routine Source`
```assembly
*
*``````````````````````````````*
* _BUFFCLEAR (NATHAN RIGGS) *
* *
* CLEAR THE FILE BUFFER THAT *
* IS CURRENTLY IN USE SO THAT *
* THE BUFFER MAY BE REUSED. *
* *
* INPUT *
* *
* NONE. *
* *
* CYCLES: 31+ *
* SIZE: 17 BYTES *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
_BUFFCLEAR
*
LDA ]FNBUF ; {4C3B} GET FILENAME BUFFER ADDR
STA ADDR2 ; {3C2B} STORE IN ZERO
LDA ]FNBUF+1 ; {4C3B} DO SAME FOR HIGH BYTE
STA ADDR2+1 ; {3C2B}
LDA #0 ; {3C2B} RESET .A
TAY ; {2C1B} AND .Y
STA (ADDR2),Y ; {6C3B} STORE #00 IN FIRST SPOT
RTS ; {6C1B} TO INDICATE EMPTY BUFFER
*
```
---
### THE _FMPSET SUBROUTINE
_SUMMARY_
| Condition | Value |
| --------------- | ------------------------------------------ |
| Name | `_FMPSET` |
| Type | Subroutine |
| File | `HEAD.DOS.ASM` |
| Author | Nathan Riggs |
| Last Revision | 07-MAY-2021 |
| Assembler | Merlin Pro 8 |
| OS | Apple DOS 3.3 |
| Purpose | Set a file parameter. |
| Input | .A = Value<br />.Y = File Parameter Offset |
| Output | none |
| Dependencies | none |
| Flags Destroyed | NZCV |
| Cycles | 30+ |
| Bytes | 16 |
| Notes | none |
| See Also | `_FMPSETA` `_FMPGET` `_FMPGETA` |
---
*DETAILS*
The `_FMPSET` subroutine sets a file parameter in the **FPL** indicated by the offset held in the **.Y** register to the value held in the **.A** register. This only sets a single byte.
`LISTING 6.10: HEAD.DOS.ASM _FMPSET Routine Source`
```assembly
*
*``````````````````````````````*
* _FMPSET (NATHAN RIGGS) *
* *
* SET A FILE PARAMTER TO THE *
* VALUE HELD IN .A AT THE *
* OFFSET INDICATED BY .Y. *
* *
* INPUT *
* *
* .A = VALUE *
* .Y = FILE PARAMETER OFFSET *
* *
* DESTROY: NZCIDV *
* ^^^ ^ *
* *
* CYCLES: 30+ *
* SIZE: 16 BYTES *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
_FMPSET
; .Y HOLDS THE OFFSET
TAX ; {2C1B} .A HOLDS THE VALUE
LDA ]FPARM ; {4C3B} LOAD FILE MGR PARAMETER LOW
STA ADDR1 ; {3C2B} HOLD ON ZERO PAGE
LDA ]FPARM+1 ; {4C3B} LOAD HIGH BYTE
STA ADDR1+1 ; {3C2B} ONTO ZERO PAGE
TXA ; {2C1B} RETURN VALUE BACK TO .A
STA (ADDR1),Y ; {6C3B} STORE VALUE AT OFFSET IN PARAMS
RTS ; {6C1B}
*
```
---
### THE _FMPSETA SUBROUTINE
_SUMMARY_
| Condition | Value |
| --------------- | ------------------------------------------------------------ |
| Name | `_FMPSETA` |
| Type | Subroutine |
| File | `HEAD.DOS.ASM` |
| Author | Nathan Riggs |
| Last Revision | 07-MAY-2021 |
| Assembler | Merlin Pro 8 |
| OS | Apple DOS 3.3 |
| Purpose | Set a file parameter. |
| Input | .A = Value Low Byte<br />.X = Value High Byte<br />.Y = File Parameter Offset |
| Output | none |
| Dependencies | none |
| Flags Destroyed | NZCV |
| Cycles | 46+ |
| Bytes | 26 |
| Notes | none |
| See Also | `_FMPSET` `_FMPGET` `_FMPGETA` |
---
*DETAILS*
The `_FMPSETA` subroutine sets a file parameter address in the **FPL** indicated by the offset held in the **.Y** register to the value held in the **.A** register (low byte) and the **.X** register (high byte), setting a two consecutive bytes.
`LISTING 6.11: HEAD.DOS.ASM _FMPSETA Routine Source`
```assembly
*
*``````````````````````````````*
* _FMPSETA (NATHAN RIGGS) *
* *
* SET A TWO-BYTE VALUE, SUCH *
* AS AN ADDRESS, IN THE FILE *
* PARAMETER LIST. *
* *
* INPUT *
* *
* .A = LOWEST BYTE *
* .X = HIGHEST BYTE *
* .Y = OFFSET VALUE *
* *
* DESTROY: NZCIDV *
* ^^^ ^ *
* *
* CYCLES: 46+ *
* SIZE: 26 BYTES *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
_FMPSETA
; .Y HOLDS THE OFFSET
STA ADDR2 ; {3C2B} .A HOLDS LOW BYTE OF ADDR
STX ADDR2+1 ; {3C2B} .X HOLDS ADDR HIGH BYTE
LDA ]FPARM ; {4C3B} LOAD FILE MGR PARAMETER LOW
STA ADDR1 ; {3C2B} HOLD ON ZERO PAGE
LDA ]FPARM+1 ; {4C3B} LOAD HIGH BYTE
STA ADDR1+1 ; {3C2B} ONTO ZERO PAGE
LDA ADDR2 ; {3C2B}
STA (ADDR1),Y ; {6C3B} STORE VAL AT OFFSET IN PARAMS
LDA ADDR2+1 ; {3C2B}
INY ; {2C1B}
STA (ADDR1),Y ; {6C3B}
RTS ; {6C1B}
*
```
---
### THE _FMPGET SUBROUTINE
_SUMMARY_
| Condition | Value |
| --------------- | --------------------------------------- |
| Name | `_FMPGET` |
| Type | Subroutine |
| File | `HEAD.DOS.ASM` |
| Author | Nathan Riggs |
| Last Revision | 07-MAY-2021 |
| Assembler | Merlin Pro 8 |
| OS | Apple DOS 3.3 |
| Purpose | Retrieve a file parameter from the FPL. |
| Input | .Y = File Parameter Offset |
| Output | none |
| Dependencies | none |
| Flags Destroyed | NZCV |
| Cycles | 26+ |
| Bytes | 14 |
| Notes | none |
| See Also | `_FMPGETA` `_FMPSET` `_FMPSETA` |
---
*DETAILS*
The `_FMPGET` subroutine retrieves a single byte from a given parameter in the **FPL**, as indicated by the offset held in **.Y**.
`LISTING 6.12: HEAD.DOS.ASM _FMPGET Routine Source`
```assembly
*
*``````````````````````````````*
* _FMPGET (NATHAN RIGGS) *
* *
* GET A VALUE RETURNED FROM *
* THE FILE MANAGER AFTER IT *
* RUNS. THIS VALUE IS HELD AT *
* AN OFFSET IN THE FILE PARAM *
* LIST. *
* *
* INPUT: *
* *
* .Y = OFFSET TO READ *
* *
* DESTROY: NZCIDV *
* ^^^ ^ *
* *
* CYCLES: 26+ *
* SIZE: 14 BYTES *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
_FMPGET
; OFFSET IS PASSED IN .Y
LDA ]FPARM ; {4C3B}
STA ADDR1 ; {3C2B}
LDA ]FPARM+1 ; {4C3B}
STA ADDR1+1 ; {3C2B}
LDA (ADDR1),Y ; {6C3B} VALUE RETURNED IN .A
RTS ; {6C1B}
*
```
---
### THE _FMPGETA SUBROUTINE
_SUMMARY_
| Condition | Value |
| --------------- | -------------------------------------------------------- |
| Name | `_FMPGETA` |
| Type | Subroutine |
| File | `HEAD.DOS.ASM` |
| Author | Nathan Riggs |
| Last Revision | 07-MAY-2021 |
| Assembler | Merlin Pro 8 |
| OS | Apple DOS 3.3 |
| Purpose | Retrieve a two-byte address file parameter from the FPL. |
| Input | .Y = File Parameter Offset |
| Output | none |
| Dependencies | none |
| Flags Destroyed | NZCV |
| Cycles | 42+ |
| Bytes | 21 |
| Notes | none |
| See Also | `_FMPGET` `_FMPSET` `_FMPSETA` |
---
*DETAILS*
The `_FMPGETA` subroutine retrieves two consecutive bytes from the offset held in **.Y** in the **FPL**. This is usually an address; the low byte is returned in **.A** and the high byte is returned in **.X**.
`LISTING 6.13: HEAD.DOS.ASM _FMPGETA Routine Source`
```assembly
*
*``````````````````````````````*
* _FMPGETA (NATHAN RIGGS) *
* *
* RETRIEVE A 2-BYTE VALUE LIKE *
* AN ADDRESS FROM THE FILE *
* PARAMETER LIST AT THE GIVEN *
* OFFSET. *
* *
* INPUT *
* *
* .Y = OFFSET INDEX *
* *
* DESTROY: NZCIDV *
* ^^^ ^ *
* *
* CYCLES: 42+ *
* SIZE: 21 BYTES *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
_FMPGETA
; OFFSET PASSED IN .Y
LDA ]FPARM ; {4C3B}
STA ADDR1 ; {3C2B}
LDA ]FPARM+1 ; {4C3B}
STA ADDR1+1 ; {3C2B}
LDA (ADDR1),Y ; {6C3B} GET LOW BYTE
PHA ; {3C1B} HOLD ON STACK
INY ; {2C1B} INCREASE INDEX
LDA (ADDR1),Y ; {6C3B} GET HIGH BYTE
TAX ; {2C1B} PASS BACK IN .X
PLA ; {3C1B} PASS LOW IN .A
RTS ; {6C1B}
*
```
---
## Required DOS Macros
The MAC.DOSREQ.ASM file contains various macros that are required to be included (USE) in order for the entire DOS collection to function. This is unlike other collections, which usually do not require a separate macro file that the other macros and subroutines depend upon. While these macros could be replaced in each macro and subroutine with the appropriate code, the Merlin 8 Pro compiler would quickly run into memory management issues due to limitations on file size.
Most of these macros call a combination of the subroutines found in the HEAD.DOS.ASM file, and should be used in place of calling the subroutines directly.
`LISTING 6.20: MAC.DOSREQ.ASM Heading Source`
```assembly
*
*``````````````````````````````*
* MAC.DOSREQ.ASM *
* *
* THESE MACROS ARE REQUIRED *
* FOR USING THE DOS MACROS AND *
* SUBROUTINES. GENERALLY, THIS *
* INCLUDES LOW LEVEL ROUTINES *
* AND MACRO SHORTCUTS TO SAVE *
* MEMORY DURING ASSEMBLY. *
* *
* AUTHOR: NATHAN RIGGS *
* CONTACT: NATHAN.RIGGS@ *
* OUTLOOK.COM *
* *
* DATE: 06-MAY-2021 *
* ASSEMBLER: MERLIN 8 PRO *
* OS: DOS 3.3 *
* *
* SUBROUTINE FILES USED *
* *
* *
* LIST OF MACROS *
* *
* SRWTS : SET RWTS PARAMETERS *
* GRWTS : RUN RWTS ROUTINE *
* FMFIL : FILL FILE MGR PARAMS *
* FMNAM : STRING TO PARAM AREA *
* FRWB : BYTE READ/WRITE MAC *
* FWRTB : WRITE A BYTE TO FILE *
* FRDB : READ BYTE FROM FILE *
* FRWR : RANGE READ/WRITE MAC *
* FRDR : READ RANGE FROM FILE *
* FWRTR : WRITE RANGE TO FILE *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
```
---
### THE SRWTS MACRO
_SUMMARY_
| Condition | Value |
| --------------- | ------------------------------------------------------------ |
| Name | `SRWTS` |
| Type | Macro |
| File | `MAC.DOSREQ.ASM` |
| Author | Nathan Riggs |
| Last Revision | 07-MAY-2021 |
| Assembler | Merlin Pro 8 |
| OS | Apple DOS 3.3 |
| Purpose | Set common RWTS parameters. |
| Input | ]1 = Slot<br />]2 = Drive<br />]3 = Volume<br />]4 = Track<br />]5 = Sector<br />]6 = Buffer Address<br />]7 = Command |
| Output | none |
| Dependencies | `_SETRWTS` |
| Flags Destroyed | NZCV |
| Cycles | 228+ |
| Bytes | 141 |
| Notes | none |
| See Also | `_SETRWTS` |
---
*DETAILS*
The `SRWTS` macro sets the most common parameters used in the **IOB** before calling the **RWTS** routine. This includes the slot, drive, volume, track, sector, buffer address and **RWTS** command. If the volume is set to **#0**, then any volume will be acceptable for **RWTS**.
`LISTING 6.21: MAC.DOSREQ.ASM SRWTS Macro Source`
```assembly
*
*``````````````````````````````*
* SETRWTS *
* *
* SET THE PARAMETERS FOR RWTS. *
* *
* PARAMETERS *
* *
* ]1 = RWTS SLOT *
* ]2 = RWTS DRIVE *
* ]3 = RWTS VOLUME *
* ]4 = RWTS TRACK *
* ]5 = RWTS SECTOR *
* ]6 = RWTS BUFFER *
* ]7 = RWTS COMMAND *
* *
* CYCLES: 228+ *
* SIZE: 141 BYTES *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
SRWTS MAC
LDA ]1 ; {4C3B} RWTS SLOT
STA MSLOT ; {4C3B}
LDA ]2 ; {4C3B} RWTS DRIVE
STA MDRIVE ; {4C3B}
LDA ]3 ; {4C3B} RWTS VOLUME
STA MVOL ; {4C3B}
LDA ]4 ; {4C3B} RWTS TRACK
STA MTRACK ; {4C3B}
LDA ]5 ; {4C3B} RWTS SECTOR
STA MSECTOR ; {4C3B}
IF #=]6 ; IF VALUE IS A LITERAL
LDA ]6 ; {4C3B} THEN STORE LITERAL
STA MBUFFER ; {4C3B} LOW AND HIGH BYTES
LDA ]6/$100 ; {4C3B}
STA MBUFFER+1 ; {4C3B}
ELSE ; OTHERWISE,
LDA ]6 ; {4C3B} LOAD VALUE FROM ADDRESS
STA MBUFFER ; {4C3B} AND STORE IN BUFFER
LDA ]6+1 ; {4C3B} ADDRESS POINTER
STA MBUFFER+1 ; {4C3B}
FIN
LDA ]7 ; {4C3B} RWTS COMMAND
STA MCMD ; {4C3B}
JSR _SETRWTS ; {148C81B} SET THE PARAMETERS
<<<
*
```
---
### THE GRWTS MACRO
_SUMMARY_
| Condition | Value |
| --------------- | ------------------------- |
| Name | `GRWTS` |
| Type | Macro |
| File | `MAC.DOSREQ.ASM` |
| Author | Nathan Riggs |
| Last Revision | 07-MAY-2021 |
| Assembler | Merlin Pro 8 |
| OS | Apple DOS 3.3 |
| Purpose | Run the DOS RWTS Routine. |
| Input | none |
| Output | none |
| Dependencies | none |
| Flags Destroyed | NZCV |
| Cycles | 19+ |
| Bytes | 11 |
| Notes | none |
| See Also | `SRWTS` |
---
*DETAILS*
The `GRWTS` macro simply runs the **RWTS** routine found in DOS. At the very least, the `SRWTS` macro should be called beforehand to set the various parameters used by **RWTS**.
`LISTING 6.22: MAC.DOSREQ.ASM GRWTS Macro Source`
```assembly
*
*``````````````````````````````*
* GRWTS *
* *
* RUN THE RWTS ROUTINE. *
* *
* PARAMETERS *
* *
* NONE. *
* *
* CYCLES: 19+ *
* SIZE: 11 BYTES *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
GRWTS MAC
JSR ]LOCRPL ; {6C3B} (GET ]LOCRPL CYCLES/SIZE)
JSR ]RWTS ; {6C3B} (GET CYCLES/SIZE)
LDA #0 ; {3C2B}
STA $48 ; {4C3B} FIX P REG FOR DOS
<<<
*
```
---
### THE FMFIL MACRO
_SUMMARY_
| Condition | Value |
| --------------- | ------------------------------------------------------------ |
| Name | `FMFIL` |
| Type | Macro |
| File | `MAC.DOSREQ.ASM` |
| Author | Nathan Riggs |
| Last Revision | 07-MAY-2021 |
| Assembler | Merlin Pro 8 |
| OS | Apple DOS 3.3 |
| Purpose | Fill the most common parameters in the FPL. |
| Input | ]1 = Command<br />]2 = Slot<br />]3 = Drive<br />]4 = Volume<br />]5 = Record Number |
| Output | none |
| Dependencies | `_FMGETPARM` `_FMBUFFSCAN` `_SETPBUFFS` `_FMPSET` `_FMPSETA` |
| Flags Destroyed | NZCV |
| Cycles | 603+ |
| Bytes | 303 |
| Notes | none |
| See Also | `SRWTS` `FMNAM` |
---
*DETAILS*
The `FMFIL` macro fills out the most common parameters used in the **File Parameter List (FPL)**. This includes the file command, slot, drive, volume, and record number. Note that not all of these are applicable to every use. Like with `SRWTS`, the volume can be set to **#0** to indicate that any volume is acceptable.
`LISTING 6.23: MAC.DOSREQ.ASM FMFIL Macro Source`
```assembly
*
*``````````````````````````````*
* FMFIL (NATHAN RIGGS) *
* *
* FILLS THE MOST COMMON AREAS *
* IN THE FILE PARAMETERS. THIS *
* INCLUDES THE COMMAND, SLOT, *
* DISK, VOLUME AND RECORD. *
* *
* PARAMETERS *
* *
* ]1 = COMMAND *
* ]2 = SLOT *
* ]3 = DRIVE *
* ]4 = VOLUME (0 FOR ANY) *
* ]5 = RECORD NUMBER *
* *
* CYCLES: 603+ *
* SIZE: 303 BYTES *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
FMFIL MAC
JSR _FMGETPARM ; {26C13B} GET FILE PARAMS ADDRESS
JSR _FMBUFFSCAN ; {217C120B} SCAN FOR FREE FILE BUFF
JSR _SETPBUFFS ; {125C67B} SET PARAMETER BUFFERS
LDA ]1 ; {4C3B} COMMAND TO PARAMETERS
LDY #]P_CMD ; {3C2B} SET INDEX TO COMMAND OFFSET
JSR _FMPSET ; {36C19B} SET COMMAND
LDA ]2 ; {4C3B} SLOT TO PARAMETERS
LDY #]P_SLOT ; {3C2B} SET INDEX TO SLOT OFFSET
JSR _FMPSET ; {36C19B} SET SLOT
; VOLUME AND RECORD NUMBER
LDA ]3 ; {4C3B} DRIVE TO PARAMETERS
LDY #]P_DRV ; {3C2B} SET INDEX TO DRIVE OFFSET
JSR _FMPSET ; {36C19B} SET DRIVE
LDA ]4 ; {4C3B} VOLUME TO PARAMS, 0 FOR ANY
LDY #]P_VOL ; {3C2B} SET INDEX TO VOLUME OFFSET
JSR _FMPSET ; {36C19B} SET VOLUME
_AXLIT ]5 ; {8C6B}
LDY #]P_REC ; {3C2B} SET INDEX TO RECORD OFFSET
JSR _FMPSETA ; {52C29B} SET RECORD LOW AND HIGH
<<<
*
```
---
### THE FMNAM MACRO
_SUMMARY_
| Condition | Value |
| --------------- | ------------------------------------------------------------ |
| Name | `FMNAM` |
| Type | Macro |
| File | `MAC.DOSREQ.ASM` |
| Author | Nathan Riggs |
| Last Revision | 07-MAY-2021 |
| Assembler | Merlin Pro 8 |
| OS | Apple DOS 3.3 |
| Purpose | Copy a string with a preceding length-byte to the filename buffer. |
| Input | ]1 = Source string address |
| Output | none |
| Dependencies | `_NAMESTR` `_FN2BUFF` |
| Flags Destroyed | NZCV |
| Cycles | 117+ |
| Bytes | 70 |
| Notes | none |
| See Also | `FMFIL` |
---
*DETAILS*
The `FMNAM` macro copies a string with a preceding length-byte into a 30-byte memory location, filling the unused bytes in the destination with spaces. This is then copied to the **Filename Buffer** in a currently used file buffer. This filename is used for commands such as deletion, verification, opening and closing, and so on. This is also used with the renaming command, with the addition of a destination filename.
`LISTING 6.24: MAC.DOSREQ.ASM FMNAM Macro Source`
```assembly
*
*``````````````````````````````*
* FMNAM (NATHAN RIGGS) *
* *
* COPY A STRING HOLDING THE *
* NAME OF A FILE BEING HANDLED *
* TO A 30-BYTE LOCATION FILLED *
* WITH SPACES, THEN COPY THAT *
* TO THE FILE PARAMETER LIST. *
* *
* PARAMETERS *
* *
* ]1 = ADDRESS OF STRING *
* *
* CYCLES: 117+ *
* SIZE: 70 BYTES *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
FMNAM MAC
_AXLIT ]1
JSR _NAMESTR ; {70C45B} COPY STRING TO TEMP BUFF
JSR _FN2BUFF ; {47C25B} COPY TEMP BUFF TO FNAME BUFF
<<<
*
```
---
### THE FRWB MACRO
_SUMMARY_
| Condition | Value |
| --------------- | ------------------------------------------------------------ |
| Name | `FRWB` |
| Type | Macro |
| File | `MAC.DOSREQ.ASM` |
| Author | Nathan Riggs |
| Last Revision | 07-MAY-2021 |
| Assembler | Merlin Pro 8 |
| OS | Apple DOS 3.3 |
| Purpose | Read or write a byte in a file. |
| Input | ]1 = Read/Write flag<br />]2 = Command<br />]3 = Slot<br />]4 = Drive<br />]5 = Volume<br />]6 = Record Number<br />]7 = Byte offset<br />]8 = Byte to write, if writing |
| Output | none |
| Dependencies | `FMFIL` `_FMPSET` `_FMPSETA` |
| Flags Destroyed | NZCV |
| Cycles | 779+ |
| Bytes | 404 |
| Notes | none |
| See Also | `FWRTB` `FRDB` `FRWR` `FRDR` `FWRTR` |
---
*DETAILS*
The `FRWB` Macro either reads or writes a single byte in an open file, depending on which flag is provided the macro in the first parameter. Usually, this macro is used internally, rather than by the end user; the `FWRTB` macro and the `FRDB` macro are used instead to write and read a byte in a file. If writing, the eighth parameter is set to the byte to write; if not, this parameter is ignored. It should also be noted that this macro does not return a value when reading a byte; instead, this is handled by the `FRDB` macro, as the byte is returned by the file manager in the **File Parameter List (FPL)**.
As usual, a **#0** value can be passed to the volume parameter to indicate that any volume is acceptable.
`LISTING 6.25: MAC.DOSREQ.ASM FRWB Macro Source`
```assembly
*
*``````````````````````````````*
* FRWB (NATHAN RIGGS) *
* *
* EITHER READ OR WRITE A BYTE. *
* THIS USUALLY ISN'T CALLED *
* DIRECTLY, BUT THROUGH *
* ANOTHER MACRO. *
* *
* PARAMETERS *
* *
* ]1 = READ/WRITE FLAG (#3/4) *
* ]2 = COMMAND *
* ]3 = SLOT *
* ]4 = DRIVE *
* ]5 = VOLUME (0 FOR ANY) *
* ]6 = RECORD NUMBER *
* ]7 = BYTE OFFSET *
* ]8 = BYTE TO WRITE (0 READ) *
* *
* CYCLES: 779+ *
* SIZE: 404 BYTES *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
FRWB MAC
*
FMFIL ]2;]3;]4;]5;]6 ; {603C303B}
*
LDA ]1 ; {4C3B} READ OR WRITE FLAG
LDY #]P_RDWR ; {3C2B} INDEX TO READ/WRITE FLAG
JSR _FMPSET ; {30C16B} SET THE READ/WRITE FLAG
LDA #]SC_PRWB ; {3C2B} SET POS THEN READ OR WRITE
LDY #]P_SUBC ; {3C2B} SET INDEX TO SUBCODE OFFSET
JSR _FMPSET ; {30C16B} SET THE SUBCODE
_AXLIT ]7 ; {8C6B}
LDY #]P_BOFF ; {3C2B} INDEX TO BYTE OFFSET
JSR _FMPSETA ; {46C26B} SET TWO BYTE OFFSET VALUE
LDA ]8 ; {4C3B} BYTE TO WRITE, IF WRITING
LDY #]P_BYTE ; {3C2B} WRITE BYTE
JSR _FMPSET ; {30C16B} SET BYTE
LDX #1 ; {3C2B} DON'T CREATE NEW FILE
JSR ]FMRUN ; {6C3B} RUN FILE MANAGER
<<<
*
```
---
### THE FWRTB MACRO
_SUMMARY_
| Condition | Value |
| --------------- | ------------------------------------------------------------ |
| Name | `FWRTB` |
| Type | Macro |
| File | `MAC.DOSREQ.ASM` |
| Author | Nathan Riggs |
| Last Revision | 07-MAY-2021 |
| Assembler | Merlin Pro 8 |
| OS | Apple DOS 3.3 |
| Purpose | Write a byte to a file. |
| Input | ]1 = Slot<br />]2 = Drive<br />]3 = Volume<br />]4 = Record number<br />]5 = Byte offset<br />]6 = Byte to write |
| Output | none |
| Dependencies | `_FMPGET` `_BUFFCLEAR` |
| Flags Destroyed | NZCV |
| Cycles | 665+ |
| Bytes | 337 |
| Notes | none |
| See Also | `FRWB` `FRDB` `FRWR` `FRDR` `FWRTR` `FOPEN` `FCLOS` |
---
*DETAILS*
The `FWRTB` macro is used for writing a single byte at a time to an open file. Like with most File Manager operations, a value of **#0** placed in the volume parameter indicates that any volume is acceptable.
Records in files work much the same way as they do in Applesoft BASIC: each record in a file is separated by a carriage return (**#$8D**), with the zeroth record being the first string of text prior to the first carriage return. These are usually used with text files, which are only marginally supported by the DOS collection: binary files make much more sense to use in Assembly, even when the data itself represents text characters. This is not to say that text files cannot be used--the `FOPEN` macro allows you to read and write text files--but that it is better for the end programmer to devise his or her own system for dealing with text files, as there is no standard method for recognizing an End-of-File (EOF) marker. Both binary files and text files can be fully read into memory before being parsed by a given routine.
The byte offset is particularly useful with `FWRTB`, as without it only the first byte of the file could be written. A byte counter can be used to read or write each consecutive byte at a time, passing the counter value via the offset.
The `FOPEN` macro should be called before `FWRTB`, and the `FCLOS` macro should be called when all operations on the file are finished.
`LISTING 6.26: MAC.DOSREQ.ASM FWRTB Macro Source`
```assembly
*
*``````````````````````````````*
* FWRTB (NATHAN RIGGS) *
* *
* WRITE A BYTE TO A FILE. *
* *
* PARAMETERS *
* *
* ]1 = SLOT *
* ]2 = DRIVE *
* ]3 = VOLUME *
* ]4 = RECORD NUMBER *
* ]5 = BYTE OFFSET *
* ]6 = BYTE TO WRITE (0 READ) *
* *
* CYCLES: 665+ *
* SIZE: 337 BYTES *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
FWRTB MAC
*
** FRWB ARGUMENTS
**
** ]1 = READ OR WRITE CODE (3 = READ, 4 = WRITE)
** ]2 = READ OR WRITE COMMAND
** ]3 = SLOT
** ]4 = DRIVE
** ]5 = VOLUME (0 FOR ANY)
** ]6 = RECORD NUMBER
** ]7 = BYTE OFFSET
** ]8 = BYTE TO WRITE, IF WRITING
*
FRWB #4;#]FC_WRIT;]1;]2;]3;]4;]5;]6 ; {603C303B}
*
LDY #]P_RETC ; {3C2B} INDEX TO RETURN CODE OFFSET
JSR _FMPGET ; {26C14B} GET THE RETURN CODE
TAX ; {2C1B} PASS BACK IN .X
JSR _BUFFCLEAR ; {31C17B} CLEAR FILE BUFFER FOR USE
<<<
*
```
---
### THE FRDB MACRO
_SUMMARY_
| Condition | Value |
| --------------- | ------------------------------------------------------------ |
| Name | `FRDB` |
| Type | Macro |
| File | `MAC.DOSREQ.ASM` |
| Author | Nathan Riggs |
| Last Revision | 07-MAY-2021 |
| Assembler | Merlin Pro 8 |
| OS | Apple DOS 3.3 |
| Purpose | Read a byte from a file. |
| Input | ]1 = Slot<br />]2 = Drive<br />]3 = Volume<br />]4 = Record number<br />]5 = Byte offset<br />]6 = Byte to write (always 0) |
| Output | none |
| Dependencies | `_FMPGET` `_BUFFCLEAR` |
| Flags Destroyed | NZCV |
| Cycles | 700+ |
| Bytes | 357 |
| Notes | none |
| See Also | `FRWB` `FWRTB` `FRWR` `FRDR` `FWRTR` |
---
*DETAILS*
The `FRDB` macro reads a byte from an open file and returns the byte in the **.A** register. If the volume is set to **#0**, any volume will be accepted.
Records in files work much the same way as they do in Applesoft BASIC: each record in a file is separated by a carriage return (**#$8D**), with the zeroth record being the first string of text prior to the first carriage return. These are usually used with text files, which are only marginally supported by the DOS collection: binary files make much more sense to use in Assembly, even when the data itself represents text characters. This is not to say that text files cannot be used--the `FOPEN` macro allows you to read and write text files--but that it is better for the end programmer to devise his or her own system for dealing with text files, as there is no standard method for recognizing an End-of-File (EOF) marker. Both binary files and text files can be fully read into memory before being parsed by a given routine.
The byte offset is particularly useful with `FRDB`, as without it only the first byte of the file could be read. A byte counter can be used to read or write each consecutive byte at a time, passing the counter value via the offset.
The `FOPEN` macro should be called before `FWRTB`, and the `FCLOS` macro should be called when all operations on the file are finished.
`LISTING 6.27: MAC.DOSREQ.ASM FRDB Macro Source`
```assembly
*
*``````````````````````````````*
* FRDB (NATHAN RIGGS) *
* *
* READ A BYTE FROM A FILE. *
* *
* PARAMETERS *
* *
* ]1 = SLOT *
* ]2 = DRIVE *
* ]3 = VOLUME *
* ]4 = RECORD NUMBER *
* ]5 = BYTE OFFSET *
* ]6 = BYTE TO WRITE (0 READ) *
* *
* CYCLES: 700+ *
* SIZE: 357 BYTES *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
FRDB MAC
*
** FWRB ARGUMENTS
**
** ]1 = READ OR WRITE CODE (3 = READ, 4 = WRITE)
** ]2 = READ OR WRITE COMMAND
** ]3 = SLOT
** ]4 = DRIVE
** ]5 = VOLUME (0 FOR ANY)
** ]6 = RECORD NUMBER
** ]7 = BYTE OFFSET
** ]8 = BYTE TO WRITE, IF WRITING
*
FRWB #3;#]FC_READ;]1;]2;]3;]4;]5;]6 ; {603C303B}
*
LDY #]P_BYTE ; {3C2B} INDEX TO BYTE TO READ
JSR _FMPGET ; {26C14B} GET BYTE IN THE PARAMETERS
STA BPAR1 ; {3C2B} HOLD IN ZERO PAGE
LDY #]P_RETC ; {3C2B} INDEX TO THE RETURN CODE OFFSET
JSR _FMPGET ; {26C14B} GET THE RETURN CODE
TAX ; {2C1B} PASS BACK IN .X
JSR _BUFFCLEAR ; {31C17B} CLEAR FILE BUFFER FOR USE
LDA BPAR1 ; {3C2B} PASS READ BYTE IN .A
<<<
*
```
---
### THE FRWR MACRO
_SUMMARY_
| Condition | Value |
| --------------- | ------------------------------------------------------------ |
| Name | `FRWR` |
| Type | Macro |
| File | `MAC.DOSREQ.ASM` |
| Author | Nathan Riggs |
| Last Revision | 07-MAY-2021 |
| Assembler | Merlin Pro 8 |
| OS | Apple DOS 3.3 |
| Purpose | Read or write a range of bytes in a file. |
| Input | ]1 = READ/WRITE flag<br />]2 = Command<br />]3 = Slot<br />]4 = Drive<br />]5 = Volume<br />]6 = Record number<br />]7 = Byte offset<br />]8 = Range Address<br />]TEMP = Range length |
| Output | none |
| Dependencies | `_FMPSET` `_FMPSETA` |
| Flags Destroyed | NZCV |
| Cycles | 846+ |
| Bytes | 451 |
| Notes | none |
| See Also | `FRWB` `FWRTB` `FRDB` `FRDR` `FWRTR` |
---
*DETAILS*
The `FRWR` macro reads or writes a range of bytes from or to an open file, with the Range Address either containing the bytes to be written up to the specified length or the memory area to store the bytes read from the file at the given length. It is notable that because **Merlin 8 Pro** can only handle eight built-in variables (]1 - ]8), the ]TEMP variable is used to pass the range length. Additionally, and like usual, a value of **#0** in the volume parameter indicates that any volume number is valid.
For the most part, this macro is meant to be used internally. The end user should use the `FRDR` macro for reading a range of bytes and the `FWRTR` macro for writing a range of bytes.
`LISTING 6.28: MAC.DOSREQ.ASM FRWR Macro Source`
```assembly
*
*``````````````````````````````*
* FRWR (NATHAN RIGGS) *
* *
* READ OR WRITE A RANGE. *
* *
* PARAMETERS *
* *
* ]1 = READ/WRITE FLAG *
* ]2 = COMMAND *
* ]3 = SLOT *
* ]4 = DRIVE *
* ]5 = VOLUME *
* ]6 = RECORD NUMBER *
* ]7 = BYTE OFFSET *
* ]8 = RANGE ADDRESS *
* ]TEMP = RANGE LENGTH *
* *
* CYCLES: 846+ *
* SIZE: 451 BYTES *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
FRWR MAC
*
** SET THE COMMAND, SLOT, DRIVE, VOLUME AND RECORD NUMBER
*
FMFIL ]2;]3;]4;]5;]6 ; {603C303B}
*
LDA ]1 ; {4C3B} LOAD READ OR WRITE FLAG
LDY #]P_RDWR ; {3C2B} INDEX TO RD/WRT FLAG OFFSET
JSR _FMPSET ; {30C16B} SET READ OR WRITE FLAG
LDA #]SC_PRWR ; {3C2B} SUBCODE FOR POS AND READ/WRITE
LDY #]P_SUBC ; {3C2B} INDEX TO SUBCODE OFFSET
JSR _FMPSET ; {30C16B} SET SUBCODE
_AXLIT ]7 ; {8C6B}
LDY #]P_BOFF ; {3C2B} INDEX TO BYTE OFFSET
JSR _FMPSETA ; {46C26B} SET BYTE OFFSET
_AXLIT ]8 ; {8C6B}
LDY #]P_RADDR ; {3C2B} INDEX TO RANGE ADDR OFFSET
JSR _FMPSETA ; {46C26B} SET RANGE ADDRESS
LDA ]TEMP ; {4C3B} GET RANGE LENGTH
LDX ]TEMP+1 ; {4C3B} LOW BYTE AND HIGH BYTE
LDY #]P_RLEN ; {3C2B} INDEX TO RANGE LENGTH OFFSET
JSR _FMPSETA ; {46C26B} SET RANGE LENGTH
LDX #1 ; {3C2B} DON'T CREATE NEW FILE
JSR ]FMRUN ; {6C3B} RUN FILE MANAGER
<<<
*
```
---
### THE FRDR MACRO
_SUMMARY_
| Condition | Value |
| --------------- | ------------------------------------------------------------ |
| Name | `FRDR` |
| Type | Macro |
| File | `MAC.DOSREQ.ASM` |
| Author | Nathan Riggs |
| Last Revision | 07-MAY-2021 |
| Assembler | Merlin Pro 8 |
| OS | Apple DOS 3.3 |
| Purpose | Read a range of bytes from a file. |
| Input | ]1 = Slot<br />]2 = Drive<br />]3 = Volume<br />]4 = Record number<br />]5 = Byte offset<br />]6 = Range address<br />]7 = Range length |
| Output | none |
| Dependencies | `_FMPGET` `FRWR` `_BUFFCLEAR` |
| Flags Destroyed | NZCV |
| Cycles | 697+ |
| Bytes | 361 |
| Notes | none |
| See Also | `FRWB` `FWRTB` `FRDB` `FRWR` `FWRTR` |
---
*DETAILS*
The `FRDR` macro reads a range of bytes from an open file, storing the range starting at the given range address through to the given range length (two bytes). As per the collection standard, a value of **#0** in the volume parameter indicates that any volume number is valid.
Records in files work much the same way as they do in Applesoft BASIC: each record in a file is separated by a carriage return (**#$8D**), with the zeroth record being the first string of text prior to the first carriage return. These are usually used with text files, which are only marginally supported by the DOS collection: binary files make much more sense to use in Assembly, even when the data itself represents text characters. This is not to say that text files cannot be used--the `FOPEN` macro allows you to read and write text files--but that it is better for the end programmer to devise his or her own system for dealing with text files, as there is no standard method for recognizing an End-of-File (EOF) marker. Both binary files and text files can be fully read into memory before being parsed by a given routine.
The byte offset is used to start reading or writing the range at a particular location in the file.
The `FOPEN` macro should be called before `FRDR`, and the `FCLOS` macro should be called when all operations on the file are finished.
`LISTING 6.29: MAC.DOSREQ.ASM FRDR Macro Source`
```assembly
*
*``````````````````````````````*
* FRDR (NATHAN RIGGS) *
* *
* READ A RANGE FROM A FILE. *
* *
* PARAMETERS *
* *
* ]1 = SLOT *
* ]2 = DRIVE *
* ]3 = VOLUME *
* ]4 = RECORD NUMBER *
* ]5 = BYTE OFFSET *
* ]6 = RANGE ADDRESS *
* ]7 = RANGE LENGTH *
* *
* CYCLES: 697+ *
* SIZE: 361 BYTES *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
FRDR MAC
IF #=]7 ; IF RANGE ADDR IS A LITERAL
LDA ]7/$100 ; {4C3B} THEN LOAD HIGH BYTE
STA ]TEMP+1 ; {4C3B} AND STORE
LDA ]7 ; {4C3B} AND LOAD LOW BYTE
STA ]TEMP ; {4C3B} AND STORE IN TEMP
ELSE
LDA ]7+1 ; {4C3B} LOAD HIGH BYTE
STA ]TEMP+1 ; {4C3B} STORE HIGH BYTE
LDA ]7 ; {4C3B} LOAD LOW BYTE
STA ]TEMP ; {4C3B} STORE LOW BYTE
FIN
*
FRWR #3;#]FC_READ;]1;]2;]3;]4;]5;]6 ; {603C303B}
*
LDY #]P_RETC ; {3C2B} INDEX TO RETURN CODE
JSR _FMPGET ; {26C14B} GET RETURN CODE
TAX ; {2C1B} HOLD IN .X
JSR _BUFFCLEAR ; {31C17B} CLEAR FILE BUFFER FOR USE
<<<
*
```
---
### THE FWRTR MACRO
_SUMMARY_
| Condition | Value |
| --------------- | ------------------------------------------------------------ |
| Name | `FWRTR` |
| Type | Macro |
| File | `MAC.DOSREQ.ASM` |
| Author | Nathan Riggs |
| Last Revision | 07-MAY-2021 |
| Assembler | Merlin Pro 8 |
| OS | Apple DOS 3.3 |
| Purpose | Write a range of bytes to a file. |
| Input | ]1 = Slot<br />]2 = Drive<br />]3 = Volume<br />]4 = Record number<br />]5 = Byte offset<br />]6 = Range address<br />]7 = Range length |
| Output | none |
| Dependencies | `_FMPGET` `FRWR` `_BUFFCLEAR` |
| Flags Destroyed | NZCV |
| Cycles | 940+ |
| Bytes | 509 |
| Notes | none |
| See Also | `FRWB` `FWRTB` `FRDB` `FRWR` `FRDR` |
---
*DETAILS*
The `FWRTR` macro writes to an open file a range of bytes found at a given starting range address through a given range length. As per the collection standard, a value of #0 in the volume parameter indicates that any volume number is valid.
Records in files work much the same way as they do in Applesoft BASIC: each record in a file is separated by a carriage return (**#$8D**), with the zeroth record being the first string of text prior to the first carriage return. These are usually used with text files, which are only marginally supported by the DOS collection: binary files make much more sense to use in Assembly, even when the data itself represents text characters. This is not to say that text files cannot be used--the `FOPEN` macro allows you to read and write text files--but that it is better for the end programmer to devise his or her own system for dealing with text files, as there is no standard method for recognizing an End-of-File (EOF) marker. Both binary files and text files can be fully read into memory before being parsed by a given routine.
The byte offset is used to start reading or writing the range at a particular location in the file.
The `FOPEN` macro should be called before `FWRTR`, and the `FCLOS` macro should be called when all operations on the file are finished.
`LISTING 6.30: MAC.DOSREQ.ASM FWRTR Macro Source`
```assembly
*
*``````````````````````````````*
* FWRTR (NATHAN RIGGS) *
* *
* WRITE A RANGE TO A FILE. *
* *
* PARAMETERS *
* *
* ]1 = SLOT *
* ]2 = DRIVE *
* ]3 = VOLUME *
* ]4 = RECORD NUMBER *
* ]5 = BYTE OFFSET *
* ]6 = RANGE ADDRESS *
* ]7 = RANGE LENGTH *
* *
* CYCLES: 940+ *
* SIZE: 509 BYTES *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
FWRTR MAC
IF #=]7 ; IF RANGE LENGTH IS A LITERAL THEN
LDA ]7/$100 ; {4C3B} LOAD HIGH BYTE
STA ]TEMP+1 ; {4C3B} AND STORE IN TEMP
LDA ]7 ; {4C3B} LOAD LOW BYTE
STA ]TEMP ; {4C3B} AND STORE IN TEMP
ELSE ; OTHERWISE
LDA ]7+1 ; {4C3B} LOAD HIGH BYTE
STA ]TEMP+1 ; {4C3B} AND STORE IN TEMP
LDA ]7 ; {4C3B} LOAD LOW BYTE
STA ]TEMP ; {4C3B} AND STORE IN TEMP
FIN
*
FRWR #4;#]FC_WRIT;]1;]2;]3;]4;]5;]6 ; {846C451B}
*
LDY #]P_RETC ; {3C2B} INDEX TO RETURN CODE
JSR _FMPGET ; {26C14B} GET RETURN CODE
TAX ; {2C1B} PASS BACK IN .X
JSR _BUFFCLEAR ; {31C17B} CLEAR FILE BUFFER FOR USE
<<<
*
```
---
## DOS File Manager Macros
The MAC.DOSFM.ASM file contains various macros that are used for most file operations. Currently, this includes disk cataloging, locking and unlocking files, deleting files, verifying files, opening and closing files, reading and writing files (both text and binary), renaming files, and bloading and bsaving binary files. Additionally, subroutines are provided for using DOS's **RWTS** routine for low-level access to a disk, though this is mostly limited to reading and writing bytes in a given track and sector.
It should be noted that all of these macros need to have both the HEAD.DOS.ASM file and the MAC.DOSREQ.ASM file included (PUT and USE, respectively) in order to function properly (or, rather, at all).
`LISTING 6.40: MAC.DOSFM.ASM Heading Source`
```assembly
*
*``````````````````````````````*
* MAC.DOSFM.ASM *
* *
* THIS FILE CONTAINS MACROS *
* USED TO INTERFACE TO THE DOS *
* FILE MANAGER. NOTE THE *
* FOLLOWING: *
* *
* 1) THIS COLLECTION CURRENTLY *
* HAS A LOT OF OVERHEAD DUE TO *
* THE TIGHTLY INTEGRATED *
* NATURE OF THE FILE MANAGER. *
* *
* 2) THIS COLLECTION IS THE *
* ONLY ONE IN THE LIBRARY THAT *
* ALLOWS FOR USING THE MACROS *
* WITHIN THE SUBROUTINES, SAVE *
* FOR THE REQUIRED COLLECTION. *
* THIS IS TO MAKE EACH OF THE *
* SUBROUTINES MORE LEGIBLE, AS *
* JUST THE ACT OF PASSING *
* VARIABLES TO OTHER ROUTINES *
* CAN TAKE UP A SIGNIFICANT *
* NUMBER OF BYTES. *
* *
* AUTHOR: NATHAN RIGGS *
* CONTACT: NATHAN.RIGGS@ *
* OUTLOOK.COM *
* *
* DATE: 20-APR-2021 *
* ASSEMBLER: MERLIN 8 PRO *
* OS: DOS 3.3 *
* *
* SUBROUTINE FILES USED *
* *
* *
* LIST OF MACROS *
* *
* FCAT : CATALOG *
* FULCK : UNLOCK FILE *
* FLOCK : LOCK FILE *
* FDEL : DELETE FILE *
* FVFY : VERIFY FILE *
* FCLOS : CLOSE FILE *
* FRENM : RENAME FILE *
* FOPEN : OPEN FILE *
* BLOAD : LOAD BINARY FILE *
* BSAVE : SAVE BINARY FILE *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
```
---
### THE FCAT MACRO
_SUMMARY_
| Condition | Value |
| --------------- | -------------------------------- |
| Name | `FCAT` |
| Type | Macro |
| File | `MAC.DOSFM.ASM` |
| Author | Nathan Riggs |
| Last Revision | 07-MAY-2021 |
| Assembler | Merlin Pro 8 |
| OS | Apple DOS 3.3 |
| Purpose | Catalog the disk. |
| Input | ]1 = Slot<br />]2 = Drive |
| Output | A disk catalog to the screen. |
| Dependencies | `_FMFIL` `_FMPGET` `_BUFFCLEAR` |
| Flags Destroyed | NZCV |
| Cycles | 657+ |
| Bytes | 348 |
| Notes | none |
| See Also | none |
---
*DETAILS*
The `FCAT` macro simply requests a disk catalog to be printed to the text screen. This macro does not provide any way to manipulate the data present in the **Volume Table of Contents (VTOC)**; this feature will be added as a separate macro in later revisions of the collection.
`LISTING 6.41: MAC.DOSFM.ASM FCAT Macro Source`
```assembly
*
*``````````````````````````````*
* FCAT (NATHAN RIGGS) *
* *
* SIMPLY LIST THE DISK CATALOG *
* TO THE SCREEN. *
* *
* PARAMETERS *
* *
* ]1 = SLOT *
* ]2 = DRIVE *
* *
* CYCLES: 657+ *
* SIZE: 348 BYTES *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
FCAT MAC
*
FMFIL #]FC_CAT;]1;]2;#0;#0 ; {603C303B} SET CMD SLOT DRIVE
*
LDX #1 ; {3C2B} DON'T CREATE NEW FILE
JSR ]FMRUN ; {6C3B} RUN THE FILE MANAGER
LDY #]P_RETC ; {3C2B} SET INDEX TO RETURN CODE
JSR _FMPGET ; {32C17B} GET RETURN CODE FROM PARAMS
TAX ; {2C1B} HOLD CODE IN .X
JSR _BUFFCLEAR ; {37C20B} CLEAR THE FILE BUFF FOR USE
<<<
*
```
---
### THE FULCK MACRO
_SUMMARY_
| Condition | Value |
| --------------- | ---------------------------------------------------- |
| Name | `FULCK` |
| Type | Macro |
| File | `MAC.DOSFM.ASM` |
| Author | Nathan Riggs |
| Last Revision | 07-MAY-2021 |
| Assembler | Merlin Pro 8 |
| OS | Apple DOS 3.3 |
| Purpose | Unlock a file. |
| Input | ]1 = Filename address<br />]2 = Slot<br />]3 = Drive |
| Output | none. |
| Dependencies | `_FMFIL` `FMNAM` `_FMPGET` `_BUFFCLEAR` |
| Flags Destroyed | NZCV |
| Cycles | 629+ |
| Bytes | 353 |
| Notes | none |
| See Also | `FLOCK` |
---
*DETAILS*
The `FULCK` macro unlocks a file with the specified filename.
`LISTING 6.42: MAC.DOSFM.ASM FULCK Macro Source`
```assembly
*
*``````````````````````````````*
* FULCK (NATHAN RIGGS) *
* *
* UNLOCK A FILE. *
* *
* PARAMETERS *
* *
* ]1 = FILENAME STR ADDRESS *
* ]2 = SLOT *
* ]3 = DRIVE *
* *
* CYCLES: 629+ *
* SIZE: 353 BYTES *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
FULCK MAC
*
FMFIL #]FC_UNLK;]2;]3;#0;#0 ; {603C303B}
*
FMNAM ]1 ; {4C3B} SET FILENAME
LDX #1 ; {4C3B} DON'T CREATE A NEW FILE
JSR ]FMRUN ; {6C3B} RUN FILE MANAGER
LDY #]P_RETC ; {4C3B} SET INDEX TO RETURN CODE
JSR _FMPGET ; {32C17B} GET RETURN CODE FROM PARAMS
TAX ; {2C1B} HOLD IN .X
JSR _BUFFCLEAR ; {37C20B} CLEAR FILE BUFF FOR USE
<<<
*
```
---
### THE FLOCK MACRO
_SUMMARY_
| Condition | Value |
| --------------- | ---------------------------------------------------- |
| Name | `FLOCK` |
| Type | Macro |
| File | `MAC.DOSFM.ASM` |
| Author | Nathan Riggs |
| Last Revision | 07-MAY-2021 |
| Assembler | Merlin Pro 8 |
| OS | Apple DOS 3.3 |
| Purpose | Lock a file. |
| Input | ]1 = Filename address<br />]2 = Slot<br />]3 = Drive |
| Output | none. |
| Dependencies | `_FMFIL` `FMNAM` `_FMPGET` `_BUFFCLEAR` |
| Flags Destroyed | NZCV |
| Cycles | 172+ |
| Bytes | 116 |
| Notes | none |
| See Also | `FULCK` |
---
*DETAILS*
The `FLOCK` macro locks a file with the specified filename.
`LISTING 6.43: MAC.DOSFM.ASM FLOCK Macro Source`
```assembly
*
*``````````````````````````````*
* FLOCK (NATHAN RIGGS) *
* *
* LOCK A FILE. *
* *
* PARAMETERS *
* *
* ]1 = FILENAME STR ADDRESS *
* ]2 = SLOT *
* ]3 = DRIVE *
* *
* CYCLES: 172+ *
* SIZE: 116 BYTES *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
FLOCK MAC
*
*
FMFIL #]FC_LOCK;]2;]3;#0;#0 ; {603C303B}
*
FMNAM ]1 ; {117C70B} SET FILENAME
LDX #1 ; {4C3B} DON'T CREATE A NEW FILE
JSR ]FMRUN ; {6C3B} RUN FILE MANAGER
LDY #]P_RETC ; {3C2B} SET INDEX TO RETURN CODE
JSR _FMPGET ; {32C17B} GET RETURN CODE FROM PARAMS
TAX ; {2C1B} HOLD IN .X
JSR _BUFFCLEAR ; {37C20B} CLEAR FILE BUFF FOR USE
<<<
*
```
---
### THE FDEL MACRO
_SUMMARY_
| Condition | Value |
| --------------- | ---------------------------------------------------- |
| Name | `FDEL` |
| Type | Macro |
| File | `MAC.DOSFM.ASM` |
| Author | Nathan Riggs |
| Last Revision | 07-MAY-2021 |
| Assembler | Merlin Pro 8 |
| OS | Apple DOS 3.3 |
| Purpose | Delete a file. |
| Input | ]1 = Filename address<br />]2 = Slot<br />]3 = Drive |
| Output | none. |
| Dependencies | `_FMFIL` `FMNAM` `_FMPGET` `_BUFFCLEAR` |
| Flags Destroyed | NZCV |
| Cycles | 791+ |
| Bytes | 412 |
| Notes | none |
| See Also | none |
---
*DETAILS*
The `FDEL` macro deletes a file with the specified filename.
`LISTING 6.44: MAC.DOSFM.ASM FDEL Macro Source`
```assembly
*
*``````````````````````````````*
* FDEL (NATHAN RIGGS) *
* *
* DELETE A FILE. *
* *
* PARAMETERS *
* *
* ]1 = FILENAME STR ADDRESS *
* ]2 = SLOT *
* ]3 = DRIVE *
* *
* CYCLES: 791+ *
* SIZE: 412 BYTES *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
FDEL MAC
*
FMFIL #]FC_DEL;]2;]3;#0;#0 ; {603C303B}
*
FMNAM ]1 ; {117C70B} SET FILE NAME
LDX #1 ; {3C2B} DON'T CREATE NEW FILE
JSR ]FMRUN ; {6C3B} RUN FILE MANAGER
LDY #]P_RETC ; {3C2B} SET INDEX TO RETURN CODE
JSR _FMPGET ; {26C14B} GET CODE FROM PARAMS
TAX ; {2C1B} HOLD IN .X
JSR _BUFFCLEAR ; {31C17B} CLEAR FILE BUFF FOR USE
<<<
*
```
---
### THE FVFY MACRO
_SUMMARY_
| Condition | Value |
| --------------- | ---------------------------------------------------- |
| Name | `FVFY` |
| Type | Macro |
| File | `MAC.DOSFM.ASM` |
| Author | Nathan Riggs |
| Last Revision | 07-MAY-2021 |
| Assembler | Merlin Pro 8 |
| OS | Apple DOS 3.3 |
| Purpose | Verify a file. |
| Input | ]1 = Filename address<br />]2 = Slot<br />]3 = Drive |
| Output | none. |
| Dependencies | `_FMFIL` `FMNAM` `_FMPGET` `_BUFFCLEAR` |
| Flags Destroyed | NZCV |
| Cycles | 791+ |
| Bytes | 411 |
| Notes | none |
| See Also | none |
---
*DETAILS*
The `FVFY` macro verifies a file with the specified filename.
`LISTING 6.45: MAC.DOSFM.ASM FVFY Macro Source`
```assembly
*
*``````````````````````````````*
* FVFY (NATHAN RIGGS) *
* *
* VERIFY A FILE. *
* *
* PARAMETERS *
* *
* ]1 = FILENAME STR ADDRESS *
* ]2 = SLOT *
* ]3 = DRIVE *
* *
* CYCLES: 791+ *
* SIZE: 411 BYTES *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
FVFY MAC
*
FMFIL #]FC_VFY;]2;]3;#0;#0 ; {603C303B}
*
FMNAM ]1 ; {117C70B} SET FILE NAME
LDX #1 ; {3C2B} DON'T CREATE A NEW FILE
JSR ]FMRUN ; {6C3B} RUN THE FILE MANAGER
LDY #]P_RETC ; {3C2B} SET INDEX TO RETURN CODE
JSR _FMPGET ; {26C14B} GET CODE FROM PARAMETERS
TAX ; {2C1B} HOLD IN .X
JSR _BUFFCLEAR ; {31C17B} CLEAR FILE BUFF FOR USE
<<<
*
```
---
### THE FCLOS MACRO
_SUMMARY_
| Condition | Value |
| --------------- | ---------------------------------------------------- |
| Name | `FCLOS` |
| Type | Macro |
| File | `MAC.DOSFM.ASM` |
| Author | Nathan Riggs |
| Last Revision | 07-MAY-2021 |
| Assembler | Merlin Pro 8 |
| OS | Apple DOS 3.3 |
| Purpose | Close a file. |
| Input | ]1 = Filename address<br />]2 = Slot<br />]3 = Drive |
| Output | none. |
| Dependencies | `_FMFIL` `FMNAM` `_FMPGET` `_BUFFCLEAR` |
| Flags Destroyed | NZCV |
| Cycles | 797+ |
| Bytes | 415 |
| Notes | none |
| See Also | none |
---
*DETAILS*
The `FCLOS` macro closes a file with the specified filename.
`LISTING 6.46: MAC.DOSFM.ASM FCLOS Macro Source`
```assembly
*
*``````````````````````````````*
* FCLOS (NATHAN RIGGS) *
* *
* CLOSE A FILE. *
* *
* PARAMETERS *
* *
* ]1 = FILENAME STR ADDRESS *
* ]2 = SLOT *
* ]3 = DRIVE *
* *
* CYCLES: 797+ *
* SIZE: 415 BYTES *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
FCLOS MAC
*
FMFIL #]FC_CLOS;]2;]3;#0;#0 ; {603C303B}
*
FMNAM ]1 ; {117C70B} SET FILENAME
LDX #1 ; {3C2B} DON'T CREATE NEW FILE
JSR ]FMRUN ; {6C3B} RUN FILE MANAGER
LDY #]P_RETC ; {3C2B} SET INDEX TO RETURN CODE
JSR _FMPGET ; {32C17B} GET RETURN CODE
TAX ; {2C1B} AND HOLD IN .X
JSR _BUFFCLEAR ; {31C17B} CLEAR FILE BUFF FOR USE
<<<
*
```
---
### THE FRENM MACRO
_SUMMARY_
| Condition | Value |
| --------------- | ------------------------------------------------------------ |
| Name | `FRENM` |
| Type | Macro |
| File | `MAC.DOSFM.ASM` |
| Author | Nathan Riggs |
| Last Revision | 07-MAY-2021 |
| Assembler | Merlin Pro 8 |
| OS | Apple DOS 3.3 |
| Purpose | Rename a file. |
| Input | ]1 = Filename address<br />]2 = New filename address<br />]3 = Slot<br />]4 = Drive |
| Output | none. |
| Dependencies | `_FMFIL` `FMNAM` `_FMPGET` `_BUFFCLEAR` `_FMNM2` |
| Flags Destroyed | NZCV |
| Cycles | 927+ |
| Bytes | 578 |
| Notes | none |
| See Also | none |
---
*DETAILS*
The `FRENM` macro renames a file with the filename given in the first parameter to the filename given in the second parameter.
`LISTING 6.47: MAC.DOSFM.ASM FRENM Macro Source`
```assembly
*
*``````````````````````````````*
* FRENM (NATHAN RIGGS) *
* *
* RENAME A FILE. *
* *
* PARAMETER *
* *
* ]1 = FILENAME STR ADDRESS *
* ]2 = NEW NAME STR ADDRESS *
* ]3 = SLOT *
* ]4 = DRIVE *
* *
* CYCLES: 927+ *
* SIZE: 578 BYTES *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
FRENM MAC
*
FMFIL #]FC_REN;]3;]4;#0;#0 ; {603C303B}
*
FMNAM ]1 ; {117C70B} SET FILENAME
_AXLIT ]2 ; {8C6B}
JSR _NAMESTR2 ; {64C42B} COPY TO 2ND FILENAME BUFF
JSR _FMNM2 ; {64C42B} SET ADDRESS IN PARAMS
LDX #1 ; {3C2B} DON'T CREATE NEW FILE
JSR ]FMRUN ; {6C3B} RUN FILE MANAGER
LDY #]P_RETC ; {3C2B} SET INDEX TO RETURN CODE
JSR _FMPGET ; {26C14B} GET RETURN CODE
TAX ; {2C1B} AND HOLD IN .X
JSR _BUFFCLEAR ; {31C17B} CLEAR FILE BUFFER FOR USE
<<<
*
```
---
### THE FOPEN MACRO
_SUMMARY_
| Condition | Value |
| --------------- | ------------------------------------------------------------ |
| Name | `FOPEN` |
| Type | Macro |
| File | `MAC.DOSFM.ASM` |
| Author | Nathan Riggs |
| Last Revision | 07-MAY-2021 |
| Assembler | Merlin Pro 8 |
| OS | Apple DOS 3.3 |
| Purpose | Open a file. |
| Input | ]1 = Filename address<br />]2 = Slot<br />]3 = Drive<br />]4 = Volume<br />]5 = Record<br />]6 = File type |
| Output | none. |
| Dependencies | `_FMFIL` `FMNAM` `_FMPGET` `_BUFFCLEAR` `_FMPSET` |
| Flags Destroyed | NZCV |
| Cycles | 828+ |
| Bytes | 433 |
| Notes | none |
| See Also | `FCLOS` |
---
*DETAILS*
The `FOPEN` macro opens a file for reading or writing, which is determined by the `FRDB`, `FWRTB`, `FRDR` and `FWRTR` macros. Beyond opening the file for use, `FOPEN` determines the type of file that will be read or written to. The following table describes which type of file corresponds to the value passed in parameter number six, along with a variable name to be used in place of a number for ease of use:
| Value | Variable Name | File Type |
|----------|-----------------------|--------------|
|$00| TYP_TXT | Text File |
|$01| TYP_INT | Integer BASIC File |
|$02| TYP_APP | Applesoft BASIC File |
|$04| TYP_BIN | Binary File |
|$08| TYP_REL | Relocatable File |
|$10| TYP_S | S Type File |
|$20| TYP_A | A Type File |
|$40| TYP_B | B Type File |
`LISTING 6.48: MAC.DOSFM.ASM FOPEN Macro Source`
```assembly
*
*``````````````````````````````*
* FOPEN (NATHAN RIGGS) *
* *
* OPEN FILE FOR READ OR WRITE. *
* *
* PARAMETERS *
* *
* ]1 = FILENAME STR ADDRESS *
* ]2 = SLOT *
* ]3 = DRIVE *
* ]4 = VOLUME (0 FOR ANY) *
* ]5 = RECORD NUMBER *
* ]6 = FILE TYPE *
* *
* CYCLES: 828+ *
* SIZE: 433 BYTES *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
FOPEN MAC
*
FMFIL #]FC_OPEN;]2;]3;]4;]5 ; {603C303B}
*
LDA ]6 ; {4C3B} FILE TYPE IF NEW FILE
LDY #]P_TYPE ; {3C2B} SET TYPE FOR WRITING
JSR _FMPSET ; {30C16B}
FMNAM ]1 ; {117C70B} SET THE FILENAME
LDX #0 ; {3C2B} NEW FILE ON OPEN
JSR ]FMRUN ; {6C3B} RUN FILE MANAGER
LDY #]P_RETC ; {3C2B} SET INDEX TO RETURN CODE OFFSET
JSR _FMPGET ; {26C14B} GET RETURN CODE
TAX ; {2C1B} HOLD IT IN .X
JSR _BUFFCLEAR ; {31C17B} CLEAR FILE BUFFER FOR USE
<<<
*
```
---
### THE BLOAD MACRO
_SUMMARY_
| Condition | Value |
| --------------- | ------------------------------------------------------------ |
| Name | `BLOAD` |
| Type | Macro |
| File | `MAC.DOSFM.ASM` |
| Author | Nathan Riggs |
| Last Revision | 07-MAY-2021 |
| Assembler | Merlin Pro 8 |
| OS | Apple DOS 3.3 |
| Purpose | Binary-load a file. |
| Input | ]1 = Filename address<br />]2 = Loading address<br />]3 = Slot<br />]4 = Drive<br />]5 = Volume |
| Output | none. |
| Dependencies | `FBLOAD` |
| Flags Destroyed | NZCV |
| Cycles | 3768+ |
| Bytes | 2735 |
| Notes | none |
| See Also | `BSAVE` `FBSAVE` `FBLOAD` |
---
*DETAILS*
The `BLOAD` macro loads the contents of a binary file into memory either at a specified address or, if the address passed is **#$0000**, at the address stored in the start of the file. Like with all properly saved binary file, both the default address and the file byte-length is stored in the first four bytes of the file; these are not copied to the specified location. The length is passed back to the calling program via the **.A** register (low) and **.X** register (high).
`LISTING 6.49: MAC.DOSFM.ASM BLOAD Macro Source`
```assembly
*
*``````````````````````````````*
* BLOAD (NATHAN RIGGS) *
* *
* LOAD A MACHINE LANGUAGE FILE *
* INTO MEMORY AT A SPECIFIED *
* ADDRESS. IF THE ADDRESS IS *
* #0000, THEN USE THE DEFAULT *
* ADDRESS PROVIDED AT THE *
* START OF THE FILE. THE FILE *
* LENGTH IS ALSO HELD AT THE *
* BEGINNING OF THE FILE, SO *
* THERE IS NO NEED TO PASS IT *
* HERE. THIS LENGTH IS PASSED *
* BACK TO THE USER VIA THE *
* .A (LOW) AND .X (HIGH) *
* REGISTERS. *
* *
* PARAMETERS *
* *
* ]1 = FILENAME STRING ADDR *
* ]2 = LOADING ADDRESS *
* ]3 = SLOT *
* ]4 = DRIVE *
* ]5 = VOLUME *
* *
* DESTROYS: NZCIDV *
* ^^^ ^ *
* *
* CYCLES: 3768+ *
* SIZE: 2735 BYTES *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
BLOAD MAC
_MLIT ]1;WPAR1 ; {16C12B} PARSE STRING ADDRESS
_MLIT ]2;WPAR2 ; {16C12B} PARSE LOAD ADDRESS
LDA ]3 ; {4C3B} LOAD SLOT
STA BPAR1 ; {3C2B} AND STORE ON ZERO
LDA ]4 ; {4C3B} LOAD DRIVE
STA BPAR2 ; {3C2B} AND STORE ON ZERO
LDA ]5 ; {4C3B} LOAD VOLUME
STA BPAR3 ; {3C2B} AND STORE ON ZERO
JSR FBLOAD ; {3715C2696B} RUN FBLOAD SUBROUTINE
<<<
*
```
---
### THE FBLOAD SUBROUTINE
_SUMMARY_
| Condition | Value |
| --------------- | ------------------------------------------------------------ |
| Name | `FBLOAD` |
| Type | Subroutine |
| File | `SUB.FBLOAD.ASM` |
| Author | Nathan Riggs |
| Last Revision | 07-MAY-2021 |
| Assembler | Merlin Pro 8 |
| OS | Apple DOS 3.3 |
| Purpose | Binary-load a file. |
| Input | WPAR1 = Filename string address<br />WPAR2 = Loading Address<br />BPAR1 = Slot<br />BPAR2 = Drive<br />BPAR3 = Volume |
| Output | none. |
| Dependencies | none |
| Flags Destroyed | NZCV |
| Cycles | 3715+ |
| Bytes | 2696 |
| Notes | none |
| See Also | `BSAVE` `FBSAVE` `BLOAD` |
---
*DETAILS*
The `FBLOAD` subroutine loads a binary file into the designated memory address, with the length being determined by a preceding length-byte in the file. If the memory address passed is **#$0000**, then the default address found in the first two bytes of the file is used in place of the address passed. These first four bytes of the file, signifying the default memory address and the length of the range in bytes, are not copied along with the rest of the file.
The length of the data is store in **.A** (low byte) and **.X** (high byte), as well as in `RETURN`. `RETLEN` carries **#$02**.
`LISTING 6.50: SUB.FBLOAD.ASM Source`
```assembly
*
*``````````````````````````````*
* FBLOAD (NATHAN RIGGS) *
* *
* BLOAD A FILE'S MACHINE *
* LANGUAGE CONTENTS TO A GIVEN *
* MEMORY RANGE. NOTE THAT THE *
* FIRST FOUR BYTES OF A BIN *
* FILE CONTAINS THE LOADING *
* ADDRESS (TWO BYTES) AND THE *
* LENGTH OF THE CODE (TWO *
* BYTES). IF THE ADDRESS *
* EQUALS #0000, THEN THESE *
* VALUES WILL BE USED INSTEAD. *
* *
* INPUT *
* *
* WPAR1 = FILENAME STR ADDR *
* WPAR2 = LOAD ADDRESS *
* BPAR1 = SLOT *
* BPAR2 = DRIVE *
* BPAR3 = VOLUME *
* *
* DESTROY: NZCIDV *
* ^^^ ^ *
* *
* CYCLES: 3715+ *
* SIZE: 2696 BYTES *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
]FNSTR EQU WPAR1 ; FILENAME STRING
]LDADDR EQU WPAR2 ; LOADING ADDRESS
]FLEN EQU WPAR3 ; FILE LENGTH
]SLOT EQU BPAR1
]DRIVE EQU BPAR2
]VOL EQU BPAR3
]FLDADDR EQU ADDR4 ; ADDRESS STORED IN FILE
*
FBLOAD
*
** FIRST, READ FIRST TWO BYTES TO GET THE
** DEFAULT ADDRESS. IF THE ADDRESS PASSED IS
** #0000, THEN THE DEFAULT ADDRESS IS USED INSTEAD.
*
FOPEN ]FNSTR;]SLOT;]DRIVE;]VOL;#0;#]TYP_BIN ; {828C433B}
FRDB ]SLOT;]DRIVE;#0;#0;#0;#0 ; {700C357B}
STA ]FLDADDR ; {4C3B}
FRDB ]SLOT;]DRIVE;#0;#0;#1;#0 ; {700C357B}
STA ]FLDADDR+1 ; {4C3B}
*
** NOW GET THE LENGTH OF THE FILE. THEORETICALLY,
** THIS SHOULDN'T INCLUDE THE FIRST 4 BYTES?
*
FRDB ]SLOT;]DRIVE;#0;#0;#2;#0 ; {700C357B}
STA ]FLEN ; {4C3B}
FRDB ]SLOT;]DRIVE;#0;#0;#3;#0 ; {700C357B}
STA ]FLEN+1 ; {4C3B}
*
** IF PASSED ADDRESS IS ZERO, THEN USE THE
** DEFAULT ADDRESS. OTHERWISE, COPY THE PASSED
** ADDRESS INTO THE DEFAULT ADDRESS VARIABLE.
*
LDA ]LDADDR ; {4C3B}
CMP #0 ; {3C2B}
BNE :SET ; {3C2B}
LDA ]LDADDR+1 ; {4C3B}
CMP #0 ; {3C2B}
BNE :SET ; {3C2B}
JMP :SKIP ; {633B}
:SET
LDA ]LDADDR ; {4C3B}
STA ]FLDADDR ; {4C3B}
LDA ]LDADDR+1 ; {4C3B}
STA ]FLDADDR+1 ; {4C3B}
*
** NOW READ THE RANGE OF THE ENTIRE FILE AND
** STORE IT IN MEMORY AT THE APPROPRIATE LOCATION.
*
:SKIP
FRDR ]SLOT;]DRIVE;#0;#0;#4;]FLDADDR;]FLEN ; {697C361B}
FCLOS ]FNSTR;]SLOT;]DRIVE ; {797C415B}
*
LDA ]FLEN ; {4C3B} LOAD LENGTH LOW BYTE
STA RETURN ; {4C3B} AND HOLD IN .A AND RETURN
LDX ]FLEN+1 ; {4C3B} LOAD LENGTH HIGH BYTE
STA RETURN+1 ; {4C3B} AND HOLD IN .X AND RETURN+1
LDY #2 ; {3C2B} LOAD BYTE LENGTH OF RETURN
STY RETLEN ; {4C3B} AND STORE IN RETLEN
RTS ; {6C1B}
*
```
---
### THE BSAVE MACRO
_SUMMARY_
| Condition | Value |
| --------------- | ------------------------------------------------------------ |
| Name | `BSAVE` |
| Type | Macro |
| File | `MAC.DOSFM.ASM` |
| Author | Nathan Riggs |
| Last Revision | 07-MAY-2021 |
| Assembler | Merlin Pro 8 |
| OS | Apple DOS 3.3 |
| Purpose | Binary-save a range of memory. |
| Input | ]1 = Filename address<br />]2 = Loading address<br />]3 = Range length<br />]4 = Slot<br />]5 = Drive<br />]6 = Volume |
| Output | none. |
| Dependencies | `FBSAVE` |
| Flags Destroyed | NZCV |
| Cycles | 5300+ |
| Bytes | 2758 |
| Notes | none |
| See Also | `BLOAD` `FBSAVE` `FBLOAD` |
---
*DETAILS*
The `BSAVE` macro stores a range of memory from a starting address to a given byte-length in a binary file, holding the starting address in the first two bytes of the file and the range length in the third and fourth bytes. This is how all binary files are stored in DOS, or should be stored.
`LISTING 6.51: MAC.DOSFM.ASM BSAVE Macro Source`
```assembly
*
*``````````````````````````````*
* BSAVE (NATHAN RIGGS) *
* *
* STORES A MEMORY RANGE IN A *
* FILE STARTING AT THE LOADING *
* ADDRESS AND CONTINUING FOR *
* THE GIVEN RANGE LENGTH. THE *
* FIRST TWO BYTES OF THE FILE *
* HOLD THE LOADING ADDRESS, *
* AND THE 3RD AND 4TH BYTES *
* HOLD THE RANGE LENGTH. *
* *
* PARAMETERS *
* *
* ]1 = FILENAME STRING ADDR *
* ]2 = LOADING ADDRESS *
* ]3 = RANGE LENGTH *
* ]4 = SLOT *
* ]5 = DRIVE *
* ]6 = VOLUME *
* *
* DESTROYS: NZCIDV *
* ^^^ ^ *
* *
* CYCLES: 5300+ *
* SIZE: 2758 BYTES *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
BSAVE MAC
_MLIT ]1;WPAR1 ; {16C12B} PARSE STRING ADDRESS
_MLIT ]2;WPAR2 ; {16C12B} PARSE LOAD ADDRESS
_MLIT ]3;WPAR3 ; {16C12B}
LDA ]4 ; {4C3B} LOAD SLOT
STA BPAR1 ; {3C2B} AND STORE ON ZERO
LDA ]5 ; {4C3B} LOAD DRIVE
STA BPAR2 ; {3C2B} AND STORE ON ZERO
LDA ]6 ; {4C3B} LOAD VOLUME
STA BPAR3 ; {3C2B} AND STORE ON ZERO
JSR FBSAVE ; {5231C2707B} RUN FBLOAD SUBROUTINE
<<<
*
```
---
### THE FBSAVE SUBROUTINE
_SUMMARY_
| Condition | Value |
| --------------- | ------------------------------------------------------------ |
| Name | `FBSAVE` |
| Type | Subroutine |
| File | `SUB.FBSAVE.ASM` |
| Author | Nathan Riggs |
| Last Revision | 07-MAY-2021 |
| Assembler | Merlin Pro 8 |
| OS | Apple DOS 3.3 |
| Purpose | Binary-save a file. |
| Input | WPAR1 = Filename string address<br />WPAR2 = Loading Address<br />WPAR3 = Range length<br />BPAR1 = Slot<br />BPAR2 = Drive<br />BPAR3 = Volume |
| Output | none. |
| Dependencies | none |
| Flags Destroyed | NZCV |
| Cycles | 3715+ |
| Bytes | 2696 |
| Notes | none |
| See Also | `BSAVE` `FBLOAD` `BLOAD` |
---
*DETAILS*
The `FBSAVE` subroutine saves a memory range to a binary file that starts at a given address. The first two bytes of the file holds the starting address, while the next two bytes hold the range length.
`LISTING 6.52: SUB.FBSAVE.ASM Source`
```assembly
*
*``````````````````````````````*
* FBSAVE (NATHAN RIGGS) *
* *
* THIS SUBROUTINE TAKES AN *
* ADDRESS AND A BYTE LENGTH, *
* THEN SAVES THAT MEMORY RANGE *
* TO A FILE. THE FIRST TWO *
* BYTES HOLD THE ADDRESS WHERE *
* THE MEMORY WAS STORED, AND *
* THE THIRD AND FOURTH BYTES *
* OF THE FILE HOLD THE LENGTH *
* OF THE FILE (NOT INCLUDING *
* THE FOUR PRECEDING BYTES). *
* *
* INPUT *
* *
* WPAR1 = FILENAME STR ADDR *
* WPAR2 = LOAD ADDRESS *
* WPAR3 = RANGE LENGTH *
* BPAR1 = SLOT *
* BPAR2 = DRIVE *
* BPAR3 = VOLUME *
* *
* DESTROY: NZCIDV *
* ^^^ ^ *
* *
* CYCLES: 5231+ *
* SIZE: 2707 BYTES *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
]FNSTR EQU WPAR1
]LDADDR EQU WPAR2
]FLEN EQU WPAR3
]SLOT EQU BPAR1
]DRIVE EQU BPAR2
]VOL EQU BPAR3
*
FBSAVE
*
** FIRST, OPEN THE FILE FOR BINARY WRITING
*
FOPEN ]FNSTR;]SLOT;]DRIVE;]VOL;#0;#]TYP_BIN ; {828C433B}
*
** NEXT, STORE THE STARTING ADDRESS OF THE
** MEMORY RANGE AT THE FIRST TWO BYTES OF THE FILE.
*
FWRTB ]SLOT;]DRIVE;]VOL;#0;#0;]LDADDR ; {665C337B}
FWRTB ]SLOT;]DRIVE;]VOL;#0;#1;]LDADDR+1 ; {665C337B}
*
** NOW STORE THE LENGTH IN THE THIRD AND FOURTH
** BYTES OF THE FILE.
*
FWRTB ]SLOT;]DRIVE;]VOL;#0;#2;]FLEN ; {665C337B}
FWRTB ]SLOT;]DRIVE;]VOL;#0;#3;]FLEN+1 ; {665C337B}
*
** THEN STORE THE MEMORY RANGE IN THE FILE, OFFSETTING
** BY FOUR TO ACCOUNT FOR THE PRECEDING ADDRESS AND
** LENGTH BYTES.
*
FWRTR ]SLOT;]DRIVE;]VOL;#0;#4;]LDADDR;]FLEN ; {940C509B}
*
** CLOSE FILE, RETURN TO CALLER
*
FCLOS ]FNSTR;]SLOT;]DRIVE {797C416B}
RTS ; {6C1B}
```
---
## Miscellaneous DOS Macros
The MAC.DOSMORE.ASM file contains macros that are primarily concerned with DOS functions but are not required and do not fit neatly in with file management. This includes macros for checking the DOS version, verifying if DOS or Applesoft is loaded, and macros for telling if an Applesoft or Integer BASIC program is running.
`LISTING 6.60: MAC.DOSMORE.ASM Heading`
```assembly
*
*``````````````````````````````*
* MAC.DOSMORE.ASM *
* *
* *
* AUTHOR: NATHAN RIGGS *
* CONTACT: NATHAN.RIGGS@ *
* OUTLOOK.COM *
* *
* DATE: 20-APR-2021 *
* ASSEMBLER: MERLIN 8 PRO *
* OS: DOS 3.3 *
* *
* SUBROUTINE FILES USED *
* *
* NONE *
* *
* LIST OF MACROS *
* *
* DVER : CHECK DOS VERSION *
* DOSIN : CHECK IF DOS LOADED *
* ABAS : IS APPLESOFT LOADED *
* IBEX : IS INTEGER BASIC *
* PROGRAM RUNNING *
* ABEX : IS APPLESOFT BASIC *
* PROGRAM RUNNING *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
```
---
### THE DVER MACRO
_SUMMARY_
| Condition | Value |
| --------------- | --------------------- |
| Name | `DVER` |
| Type | Macro |
| File | `MAC.DOSMORE.ASM` |
| Author | Nathan Riggs |
| Last Revision | 07-MAY-2021 |
| Assembler | Merlin Pro 8 |
| OS | Apple DOS 3.3 |
| Purpose | Check the DOS version |
| Input | none |
| Output | none. |
| Dependencies | none |
| Flags Destroyed | NZCV |
| Cycles | 28+ |
| Bytes | 18 |
| Notes | none |
| See Also | none |
---
*DETAILS*
The `DVER` macro checks the current version of DOS in memory and returns the version number in the **.A** register.
`LISTING 6.61: MAC.DOSMORE.ASM DVER Macro Source`
```assembly
*
*``````````````````````````````*
* DVER (NATHAN RIGGS) *
* *
* RETURN THE DOS VERSION. THIS *
* IS ADAPTED FROM DON WORTH'S *
* AND PIETER LECHNER'S *
* /BENEATH APPLE DOS/. THE *
* LICENSE MAY ACCORDINGLY *
* VARY. *
* *
* PARAMETERS *
* *
* NONE *
* *
* CYCLES: 28 *
* SIZE: 18 BYTES *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
DVER MAC
CLC ; {2C1B} CLEAR CARRY FLAG
LDA #0 ; {3C2B} CLEAR ACCUMULATOR
ADC #$BE ; {2C2B} ADD #$16BE TO DOS LOAD POINT
STA ADDR1 ; {3C2B} STORE LOW BYTE
LDA $3D2 ; {4C3B} LOAD DOS LOADING POINT
ADC #$16 ; {2C2B} ADD OFFSET
STA ADDR1+1 ; {3C2B} STORE HIGH BYTE
LDY #0 ; {3C2B} SET INDEX TO 0
LDA (ADDR1),Y ; {6C2B} RETURNS #2 OR #3 FOR
; THE DOS VERSION IN .A
<<<
*
```
---
### THE DOSIN MACRO
_SUMMARY_
| Condition | Value |
| --------------- | ---------------------- |
| Name | `DOSIN` |
| Type | Macro |
| File | `MAC.DOSMORE.ASM` |
| Author | Nathan Riggs |
| Last Revision | 07-MAY-2021 |
| Assembler | Merlin Pro 8 |
| OS | Apple DOS 3.3 |
| Purpose | Check if DOS is loaded |
| Input | none |
| Output | none. |
| Dependencies | none |
| Flags Destroyed | NZCV |
| Cycles | 17+ |
| Bytes | 12 |
| Notes | none |
| See Also | none |
---
*DETAILS*
The `DOSIN` macro checks if DOS is currently loaded into memory. The **CARRY** flag is set if DOS is loaded, and it is cleared if DOS is not loaded.
`LISTING 6.62: MAC.DOSMORE.ASM DOSIN Macro Source`
```assembly
*
*``````````````````````````````*
* DOSIN *
* *
* CHECKS IF DOS IS LOADED. *
* THIS SHOULD BE CALLED BEFORE *
* RUNNING RWTS OR THE FILE *
* MANAGER. *
* *
* THIS IS ADAPTED FROM DON *
* WORTH'S AND PIETER LECHNER'S *
* /BENEATH APPLE DOS/, SO THE *
* LICENSE MAY VARY ACCORDINGLY *
* *
* PARAMETERS *
* *
* NONE *
* *
* CYCLES: 17 *
* SIZE: 12 BYTES *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
DOSIN MAC
LDA $3D0 ; {4C3B} GET VECTOR JUMP
CMP #$4C ; {3C2B} IS IT A JUMP?
BNE ]NODOS ; {3C2B} NOPE, JUMP TO NONE
SEC ; {2C1B} CARRY SET, MEANING DOS LOADED
JMP ]EXIT ; {3C3B}
]NODOS
CLC ; {2C1B} CARRY CLEAR, MEANING NO DOS
]EXIT
<<<
*
```
---
### THE ABAS MACRO
_SUMMARY_
| Condition | Value |
| --------------- | ------------------------------------- |
| Name | `ABAS` |
| Type | Macro |
| File | `MAC.DOSMORE.ASM` |
| Author | Nathan Riggs |
| Last Revision | 07-MAY-2021 |
| Assembler | Merlin Pro 8 |
| OS | Apple DOS 3.3 |
| Purpose | Find out which BASIC system is loaded |
| Input | none |
| Output | none. |
| Dependencies | none |
| Flags Destroyed | NZCV |
| Cycles | 40+ |
| Bytes | 29 |
| Notes | none |
| See Also | none |
---
*DETAILS*
The `ABAS` macro determines whether it is Applesoft BASIC or Integer BASIC that is currently loaded. If Applesoft BASIC is loaded, then the **CARRY** is set; if it is Integer BASIC loaded, then the **CARRY** is cleared.
`LISTING 6.63: MAC.DOSMORE.ASM ABAS Macro Source`
```assembly
*
*``````````````````````````````*
* ABAS *
* *
* DETERMINE WHICH BASIC IS *
* LOADED. IF CARRY IS CLEAR, *
* THEN INTEGER BASIC IS *
* LOADED--ELSE, APPLESOFT IS. *
* *
* THIS IS ADAPTED FROM DON *
* WORTH'S AND PIETER LECHNER'S *
* /BENEATH APPLE DOS/, SO THE *
* LICENSE MAY VARY ACCORDINGLY *
* *
* PARAMETERS *
* *
* NONE *
* *
* CYCLES: 40 *
* SIZE: 29 BYTES *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
ABAS MAC
LDA #$4C ; {4C3B} CODE FOR APPLESOFT
; #$20 IS FOR INTEGER BASIC
CMP $E000 ; {4C3B} CORRECT BASIC ALREADY THERE?
BEQ ]APPLES ; {3C2B} YES, GOTO RETURN CARRY
STA $C080 ; {4C3B} NOW IS IT THERE?
CMP $E000 ; {4C3B} NOW IS IT THERE?
BEQ ]APPLES ; {3C2B} YEP, GOTO RETURN CARRY
STA $C081 ; {4C3B} STILL NO, TRY ROM CARD
CMP $E000 ; {4C3B} THERE NOW?
BEQ ]APPLES ; {3C2B} YEP, GOTO RETURN CARRY
; NOPE, DON'T RETURN CARRY
CLC ; {2C1B}
JMP ]EXIT ; {3C3B}
]APPLES
SEC ; {2C1B}
]EXIT
<<<
*
```
---
### THE IBEX MACRO
_SUMMARY_
| Condition | Value |
| --------------- | -------------------------------------------- |
| Name | `IBEX` |
| Type | Macro |
| File | `MAC.DOSMORE.ASM` |
| Author | Nathan Riggs |
| Last Revision | 07-MAY-2021 |
| Assembler | Merlin Pro 8 |
| OS | Apple DOS 3.3 |
| Purpose | Check if an Integer BASIC program is running |
| Input | none |
| Output | none. |
| Dependencies | none |
| Flags Destroyed | NZCV |
| Cycles | 17+ |
| Bytes | 12 |
| Notes | none |
| See Also | none |
---
*DETAILS*
The `IBEX` macro sets the **CARRY** flag if an Integer BASIC program is currently running; otherwise, the **CARRY** is cleared.
`LISTING 6.64: MAC.DOSMORE.ASM IBEX Macro Source`
```assembly
*
*``````````````````````````````*
* IBEX *
* *
* CHECK IF AN INTEGER BASIC *
* PROGRAM IS RUNNING. *
* *
* THIS IS ADAPTED FROM DON *
* WORTH'S AND PIETER LECHNER'S *
* /BENEATH APPLE DOS/, SO THE *
* LICENSE MAY VARY ACCORDINGLY *
* *
* PARAMETERS *
* *
* NONE *
* *
* CYCLES: 17 *
* SIZE: 12 BYTES *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
IBEX MAC
LDA $D9 ; {4C3B} CHECK BASIC
BMI ]YES ; {3C2B} IF NEG, THEN INT BASIC RUNNING
BPL ]NO ; {3C2B} IF POSITIVE, THEN NOT
]YES
SEC ; {2C1B} INT BASIC RUNNING, SET CARRY
JMP ]EXIT ; {3C3B} AND EXIT
]NO
CLC ; {2C1B} NOT RUNNING, SO CLEAR CARRY
]EXIT ; AND EXIT
<<<
*
```
---
### THE ABEX MACRO
_SUMMARY_
| Condition | Value |
| --------------- | ---------------------------------------------- |
| Name | `ABEX` |
| Type | Macro |
| File | `MAC.DOSMORE.ASM` |
| Author | Nathan Riggs |
| Last Revision | 07-MAY-2021 |
| Assembler | Merlin Pro 8 |
| OS | Apple DOS 3.3 |
| Purpose | Check if an Applesoft BASIC program is running |
| Input | none |
| Output | none. |
| Dependencies | none |
| Flags Destroyed | NZCV |
| Cycles | 26+ |
| Bytes | 18 |
| Notes | none |
| See Also | none |
---
*DETAILS*
The `ABEX` macro sets the **CARRY** flag if an Applesoft BASIC program is currently running; otherwise, the **CARRY** is cleared.
`LISTING 6.65: MAC.DOSMORE.ASM ABEX Macro Source`
```assembly
*
*``````````````````````````````*
* ABEX *
* *
* CHECK IF AN APPLESOFT BASIC *
* PROGRAM IS RUNNING. *
* *
* THIS IS ADAPTED FROM DON *
* WORTH'S AND PIETER LECHNER'S *
* /BENEATH APPLE DOS/, SO THE *
* LICENSE MAY VARY ACCORDINGLY *
* *
* PARAMETERS *
* *
* NONE *
* *
* CYCLES: 26 *
* SIZE: 18 BYTES *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
ABEX MAC
LDX $76 ; {4C3B} GET LINE NUMBER
INX ; {2C1B}
BEQ ]NO ; {3C2B}
LDX $33 ; {4C3B} GET PROMPT CHARACTER
CPX #$DD ; {3C2B} IS PROMPT A "]" ?
BEQ ]NO ; {3C2B} YES, SO NOT EXECUTING
SEC ; {2C1B} ELSE, IS EXECUTING--SET CARRY
JMP ]EXIT ; {3C3B}
]NO
CLC ; {2C1B}
]EXIT
<<<
*
```
---
## Part II: DOS Collection Demos
This section lists two demo files, DEMO.DOSFM.ASM and DEMO.DOSMORE.ASM, that illustrate how to use the various macros in the DOS collection. This only concerns the macros found in the MAC.DOSFM.ASM file and the MAC.DOSMORE.ASM file, as the macros in DOS.DOSREQ.ASM are meant for internal use only.
`Listing 6.70: DEMO.DOSFM.ASM Source`
```assembly
*
*``````````````````````````````*
* DEMO.DOSFM.ASM *
* *
* A DEMO FILE FOR THE DOS *
* FILE MANAGER MACROS. *
* *
* AUTHOR: NATHAN RIGGS *
* CONTACT: NATHAN.RIGGS@ *
* OUTLOOK.COM *
* *
* DATE: 21-APR-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
*
```
`Listing 6.71: DEMO.DOSMORE.ASM Source`
```assembly
*
*``````````````````````````````*
* DEMO.DOSMORE.ASM *
* *
* A DEMO FILE FOR VARIOUS DOS *
* MACROS AND SUBROUTINES. *
* *
* AUTHOR: NATHAN RIGGS *
* CONTACT: NATHAN.RIGGS@ *
* OUTLOOK.COM *
* *
* DATE: 07-MAY-2021 *
* ASSEMBLER: MERLIN 8 PRO *
* OS: DOS 3.3 *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
** ASSEMBLER DIRECTIVES
*
CYC AVE
EXP OFF
TR ON
DSK DEMO.DOSMORE
OBJ $BFE0
ORG $6000
*
*``````````````````````````````*
* TOP INCLUDES *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
PUT MIN.HEAD.REQUIRED.ASM
USE MIN.MAC.REQUIRED.ASM
USE MIN.MAC.DOSREQ.ASM
USE MIN.MAC.DOSMORE.ASM
PUT MIN.HEAD.DOS.ASM
]HOME EQU $FC58
*
*``````````````````````````````*
* PROGRAM MAIN BODY *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
*``````````````````````````````*
* MISC. DOS MACROS *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
*``````````````````````````````*
* DVER *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
** THE DVER MACRO TESTS WHICH DOS VERSION IS
** BEING USED. IT RETURNS #2 FOR DOS 3.2 AND #3
** FOR DOS 3.X.
*
JSR ]HOME
_PRN "DOS VERSION MACRO (DVER)",8D
_PRN "========================",8D8D
DVER
CMP #3
BEQ THREE
_PRN "USING DOS 2.X",8D
JMP NEXT1
THREE _PRN "USING DOS 3.X",8D
NEXT1
_WAIT
*
*``````````````````````````````*
* THE DOSIN MACRO *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
** THE DOSIN MACRO CHECK WHETHER DOS IS LOADED.
** THIS IS NECESSARY TO CHECK BEFORE TRYING TO
** USE THE DOS FILE MANAGER OR THE RWTS ROUTINES.
*
JSR ]HOME
_PRN "THE DOSIN MACRO",8D
_PRN "===============",8D8D
DOSIN
BCC NODOS
_PRN "DOS IS CURRENTLY LOADED."
JMP NEXT2
NODOS _PRN "DOS IS NOT LOADED."
NEXT2
_WAIT
*
*``````````````````````````````*
* THE ABAS MACRO *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
** THE ABAS MACRO TESTS WHICH VERSION OF
** BASIC IS LOADED: INTEGER OR APPLESOFT.
** IF APPLESOFT IS LOADED, THEN THE CARRY IS
** RETURNED AS TRUE; IF INTEGER BASIC IS LOADED,
** THEN THE CARRY IS RETURNED CLEAR.
*
JSR ]HOME
_PRN "THE ABAS MACRO",8D
_PRN "==============",8D8D
ABAS
BCC INTBAS
_PRN "APPLESOFT IS LOADED."
JMP NEXT3
INTBAS _PRN "INTEGER BASIC IS LOADED."
NEXT3 _WAIT
*
*``````````````````````````````*
* THE IBEX MACRO *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
** THE IBEX MACRO TESTS WHETHER INTEGER BASIC
** IS RUNNING. THE CARRY IS RETURNED AS TRUE IF SO,
** AND CLEAR IF NOT. NOTE THAT YOU SHOULD TEST IF
** INTEGER BASIC IS LOADED BEFOREHAND; OTHERWISE,
** A FALSE POSITIVE MAY RESULT.
*
JSR ]HOME
_PRN "THE IBEX MACRO",8D
_PRN "==============",8D8D
IBEX
BCC INTNORUN
_PRN "INTEGER BASIC IS RUNNING."
JMP NEXT4
INTNORUN _PRN "INTEGER BASIC IS NOT RUNNING."
NEXT4 _WAIT
*
*``````````````````````````````*
* THE ABEX MACRO *
*,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
*
** THE ABEX MACRO TESTS WHETHER AN APPLESOFT
** PROGRAM IS CURRENTLY RUNNING.
*
JSR ]HOME
_PRN "THE ABEX MACRO",8D
_PRN "==============",8D8D
ABEX
BCC NOAPP
_PRN "APPLESOFT PROGRAM IS RUNNING."
JMP NEXT5
NOAPP _PRN "APPLESOFT PROGRAM IS NOT RUNNING."
NEXT5 _WAIT
*
JSR ]HOME
_PRN "FIN!",8D8D
*
EXIT
JMP $3D0
*
PUT MIN.LIB.REQUIRED.ASM
*
```
Reference in New Issue Copy Permalink