NextZXOS_and_esxDOS_APIs.pdf

(202 KB) Pobierz
NextZXOS and esxDOS APIs (Updated 24 May 2023)
This document describes the
NextZXOS API
(as at NextZXOS v2.08), which directly
descends from the
+3DOS API
present in the
Sinclair ZX Spectrum +2A/+2B/+3
and
the
IDEDOS API
additionally provided with the
ZX Spectrum +3e
ROMs.
It also describes the provided
esxDOS-compatible
API, which is compatible with
esxDOS 0.8.x, but contains several enhancements.
This should be read in conjunction with the other documents:
NextBASIC file-related commands and features
NextBASIC new commands and features
NextZXOS Editor features
A list of updates made to this document is now provided at the end.
Page 1 of 100
Available APIs
NextZXOS
provides 2 distinct and separate APIs:
•
a
+3DOS-compatible
API, providing the main
NextZXOS
API
•
an
esxDOS-compatible
API, providing file-based calls for SD card access
The
+3DOS-compatible
API descends directly from the original +3DOS, provided
with the Sinclair ZX Spectrum +3/+2A/+2B.
The
esxDOS-compatible
API is compatible with esxDOS 0.8.x, with some additional
facilities such as support for long filenames (LFNs), wildcards in filenames,
enhanced dot command features and a low-overhead file streaming facility.
Both APIs provide a set of general file-access calls, which are implemented as
thin layers on top of a lower level filesystem-access API (not currently exposed
to the user). The
esxDOS-compatible
API is generally easier to use, but lacks
some of the more advanced features of the
+3DOS-compatible
API, such as bank
allocation, BASIC command execution and file-browser dialogs.
The
+3DOS-compatible
API is described in the first section of the following
pages, with the
esxDOS-compatible
API described in second section.
Page 2 of 100
The +3DOS-compatible API
The
+3DOS-compatible
API provides most of the facilities available on both the
original +3/+2A/+2B, and the later +3e ROMs, with many additional facilities
specific to the Next.
To make a +3DOS API call, you must first ensure that the memory bank
configuration is set up correctly (with ROM 2 selected at the bottom of memory,
RAM bank 7 at the top of memory and the stack located below $BFE0).
Once this is done, call the address indicated in the API call. You then probably
want to restore the memory configuration to normal (with ROM 3 selected at the
bottom of memory, and RAM bank 0 at the top of memory).
Please note that a few calls require the memory configuration to be slightly
different on entry (with RAM bank 0 at the top of memory); this is noted in the
individual documentation for those calls, which are generally BASIC-releated (eg
IDE_STREAM_* and IDE_BASIC).
Some calls (eg IDE_BROWSER) may access the system variables region (eg for
keyboard scanning or other purposes). Therefore, you should generally ensure
that IY still points to the system variable ERR_NR ($5c3a) before making such a
call.
Useful example code showing how to use the API is available in the original +3
manual (section “Calling +3DOS from BASIC”), online here:
http://www.worldofspectrum.org/ZXSpectrum128+3Manual/chapter8pt26.html
This document does not describe unchanged calls, which are available in these
online documents:
http://www.worldofspectrum.org/ZXSpectrum128+3Manual/chapter8pt27.html
http://www.worldofspectrum.org/zxplus3e/idedos.html
Page 3 of 100
The following filesystem-related API calls are provided (*=effects have changed
since originally documented in +3 manual or on +3e website;
%=new
for
NextZXOS):
DOS_VERSION ($0103)
*DOS_OPEN ($0106)
DOS_CLOSE ($0109)
DOS_ABANDON ($010C)
DOS_REF_HEAD ($010F)
DOS_READ ($0112)
DOS_WRITE ($0115)
DOS_BYTE_READ ($0118)
DOS_BYTE_WRITE ($011B)
*DOS_CATALOG ($011E)
*DOS_FREE_SPACE ($0121)
DOS_DELETE ($0124)
DOS_RENAME ($0127)
DOS_BOOT ($012A)
DOS_SET_DRIVE ($012D)
DOS_SET_USER ($0130)
*DOS_GET_POSITION ($0133)
DOS_SET_POSITION ($0136)
*DOS_GET_EOF ($0139)
DOS_GET_1346 ($013C)
DOS_SET_1346 ($013F)
DOS_FLUSH ($0142)
DOS_SET_ACCESS ($0145)
DOS_SET_ATTRIBUTES ($0148)
DOS_SET_MESSAGE ($014E)
IDE_VERSION ($00A0)
*IDE_SWAP_OPEN ($00D9)
IDE_SWAP_CLOSE ($00DC)
IDE_SWAP_OUT ($00DF)
IDE_SWAP_IN ($00E2)
*IDE_SWAP_EX ($00E5)
IDE_SWAP_POS ($00E8)
IDE_SWAP_MOVE ($00EB)
IDE_SWAP_RESIZE ($00EE)
IDE_PARTITION_FIND ($00B5)
*IDE_DOS_MAP ($00F1)
*IDE_DOS_UNMAP ($00F4)
*IDE_DOS_MAPPING ($00F7)
*IDE_SNAPLOAD ($00FD)
*IDE_PATH ($01b1)
%IDE_CAPACITY ($01b4)
%IDE_GET_LFN ($01b7)
%IDE_BROWSER ($01ba)
%IDE_MOUNT ($01d2)
Get +3DOS issue and version numbers
Create and/or open a file
Close a file
Abandon a file
Point at the header data for this file
Read bytes into memory
Write bytes from memory
Read a byte
Write a byte
Catalog disk directory
Free space on disk
Delete a file
Rename a file
Boot an operating system or other program
Set/get default drive
Set/get default user number
Get file pointer for random access
Set file pointer for random access
Get end of file position for random access
Get memory usage in pages 1, 3, 4, 6
Re-allocate memory usage in pages 1, 3, 4, 6
Bring disk up to date
Change open file's access mode
Change a file's attributes
Enable/disable error messages
Get IDEDOS version number
Open a swap partition
Close a swap partition
Write block to swap partition
Read block from swap partition
Exchange block with swap partition
Get current block number in swap partition
Set current block number in swap partition
Change block size of swap partition
Find named partition
Map drive to partition
Unmap drive
Get drive mapping
Load a snapshot
Create, delete, change or get directory
Get card capacity
Get long filename
File browser
Unmount/remount SD cards
Page 4 of 100
The following non-filesystem-related API calls are provided:
IDE_STREAM_OPEN ($0056)
IDE_STREAM_CLOSE ($0059)
IDE_STREAM_IN ($005c)
IDE_STREAM_OUT ($005f)
IDE_STREAM_PTR ($0062)
%IDE_BANK ($01bd)
%IDE_BASIC ($01c0)
%IDE_WINDOW_LINEIN ($01c3)
%IDE_WINDOW_STRING ($01c6)
%IDE_INTEGER_VAR ($01c9)
%IDE_RTC ($01cc)
%IDE_DRIVER ($01cf)
%IDE_MODE ($01d5)
%IDE_TOKENISER ($01d8)
Open stream to a channel
Close stream and attached channel
Get byte from current stream
Write byte to current stream
Get or set pointer information for current stream
Allocate or free 8K banks in ZX or DivMMC memory
Execute a BASIC command line
Input line from current window stream
Output string to current window stream
Get or set NextBASIC integer variable
Query the real-time-clock module
Access the driver API
Query NextBASIC display mode info, or change mode
Convert BASIC between plain text & tokenised forms
The following API calls are related to floppy drives and will not be useful for
most software (included for use of legacy software running from .DSK images):
DOS_REF_XDPB ($0151)
DD_INTERFACE ($0157)
DD_INIT ($015A)
DD_SETUP ($015D)
DD_SET_RETRY ($0160)
DD_READ_SECTOR ($0163)
DD_ASK_1 ($017B)
DD_DRIVE_STATUS ($017E)
DD_ENCODE ($0184)
DD_L_XDPB ($0187)
DD_L_DPB ($018A)
DD_L_SEEK ($018D)
DD_L_READ ($0190)
DD_L_ON_MOTOR ($0196)
DD_L_T_OFF_MOTOR ($0199)
DD_L_OFF_MOTOR ($019C)
Point at XDPB for low level disk access
Is the floppy disk driver interface present?
Initialise disk driver
Specify drive parameters
Set try/retry count
Read a sector
Is unit 1 (external drive) present?
Fetch drive status
Set intercept routine for copy protection
Initialise an XDPB from a disk specification
Initialise a DPB from a disk specification
uPD765A seek driver
uPD765A read driver
Motor on, wait for motor-on time
Start the motor-off ticker
Turn the motor off
The following API calls are present but generally for system use only and not
useful for games/applications:
DOS_INITIALISE ($0100)
IDE_INTERFACE ($00A3)
IDE_INIT ($00A6)
IDE_DRIVE ($00A9)
*IDE_SECTOR_READ ($00AC)
*IDE_SECTOR_WRITE ($00AF)
IDE_PARTITON_READ ($00C4)
IDE_PARTITION_OPEN ($00CD)
IDE_PARTITION_CLOSE ($00D0)
IDE_PARTITIONS ($01a5)
Initialise +3DOS
Initialise card interfaces
Initialise IDEDOS
Get unit handle
Low-level sector read
Low-level sector write
Read a partition entry
Open a partition
Close a partition
Get number of open partitions
The following API calls were previously available in +3DOS/IDEDOS but are now
deprecated and will return an error of rc_notimp:
DOS_OPEN_DRIVE ($014B)
DOS_MAP_B ($0154)
DD_WRITE_SECTOR ($0166)
DD_CHECK_SECTOR ($0169)
DD_FORMAT ($016C)
DD_READ_ID ($016F)
DD_TEST_UNSUITABLE ($0172)
Open a drive as a single file
Map B: onto unit 0 or 1
Write a sector
Check a sector
Format a track
Read a sector identifier
Test media suitability
Page 5 of 100

Plik z chomika:

Inne pliki z tego folderu:

Inne foldery tego chomika:

Zgłoś jeśli naruszono regulamin