NextOS API
This document describes the NextOS API, 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.
Credits/Authors: Garry Lancaster and Phoebus Dokos.
Updates: 30 Nov 2017
Updated details of the IDE_BROWSER call. This now has a capabilities mask allowing selected functionality to be enabled or disabled as desired. Also added note about using as a save file dialog.
Updates: 23 Nov 2017
The IDE_STREAM_LINEIN call has been removed and replaced by a new IDE_WINDOW_LINEIN call.
Added new IDE_INTEGER_VAR call for accessing NextBASIC integer variables.
Noted that the IDE_STREAM_* calls may corrupt the alternate register set, in addition to the effects on the standard register set noted for each individual call. (The special note about memory configuration has also been removed for the IDE_WINDOW_* calls; this applies only to the IDE_STREAM_* calls).
Updates: 14 Nov 2017
Added note that it is now possible to use the wildcard character * in the IDE_BROWSER call to match remaining characters in the filetype (with examples).
Added more notes on the IDE_STREAM_LINEIN call.
Added new IDE_WINDOW_STRING call.
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
The following filesystem-related API calls are provided (*=effects have changed since originally documented in +3 manual or on +3e website; %=new for NextOS):
DOS_VERSION ($0103) Get +3DOS issue and version numbers
*DOS_OPEN ($0106) Create and/or open a file
DOS_CLOSE ($0109) Close a file
DOS_ABANDON ($010C) Abandon a file
DOS_REF_HEAD ($010F) Point at the header data for this file
DOS_READ ($0112) Read bytes into memory
DOS_WRITE ($0115) Write bytes from memory
DOS_BYTE_READ ($0118) Read a byte
DOS_BYTE_WRITE ($011B) Write a byte
*DOS_CATALOG ($011E) Catalog disk directory
*DOS_FREE_SPACE ($0121) Free space on disk
DOS_DELETE ($0124) Delete a file
DOS_RENAME ($0127) Rename a file
DOS_BOOT ($012A) Boot an operating system or other program
DOS_SET_DRIVE ($012D) Set/get default drive
DOS_SET_USER ($0130) Set/get default user number
*DOS_GET_POSITION ($0133) Get file pointer for random access
DOS_SET_POSITION ($0136) Set file pointer for random access
*DOS_GET_EOF ($0139) Get end of file position for random access
DOS_GET_1346 ($013C) Get memory usage in pages 1, 3, 4, 6
DOS_SET_1346 ($013F) Re-allocate memory usage in pages 1, 3, 4, 6
DOS_FLUSH ($0142) Bring disk up to date
DOS_SET_ACCESS ($0145) Change open file’s access mode
DOS_SET_ATTRIBUTES ($0148) Change a file’s attributes
DOS_SET_MESSAGE ($014E) Enable/disable error messages
IDE_VERSION ($00A0) Get IDEDOS version number
IDE_SWAP_OPEN ($00D9) Open a swap partition
IDE_SWAP_CLOSE ($00DC) Close a swap partition
IDE_SWAP_OUT ($00DF) Write block to swap partition
IDE_SWAP_IN ($00E2) Read block from swap partition
IDE_SWAP_EX ($00E5) Exchange block with swap partition
IDE_SWAP_POS ($00E8) Get current block number in swap partition
IDE_SWAP_MOVE ($00EB) Set current block number in swap partition
IDE_SWAP_RESIZE ($00EE) Change block size of swap partition
IDE_PARTITION_FIND ($00B5) Find named partition
*IDE_DOS_MAP ($00F1) Map drive to partition
*IDE_DOS_UNMAP ($00F4) Unmap drive
IDE_DOS_MAPPING ($00F7) Get drive mapping
*IDE_SNAPLOAD ($00FD) Load a snapshot
*IDE_PATH ($01b1) Create, delete, change or get directory
%IDE_CAPACITY ($01b4) Get card capacity
%IDE_GET_LFN ($01b7) Get long filename
%IDE_BROWSER ($01ba) File browser
The following non-filesystem-related API calls are provided:
IDE_STREAM_OPEN ($0056) Open stream to a channel
IDE_STREAM_CLOSE ($0059) Close stream and attached channel
IDE_STREAM_IN ($005c) Get byte from current stream
IDE_STREAM_OUT ($005f) Write byte to current stream
IDE_STREAM_PTR ($0062) Get or set pointer information for current stream
%IDE_BANK ($01bd) Allocate or free 8K banks in ZX or DivMMC memory
%IDE_BASIC ($01c0) Execute a BASIC command line
%IDE_WINDOW_LINEIN ($01c3) Input line from current window stream
%IDE_WINDOW_STRING ($01c6) Output string to current window stream
%IDE_INTEGER_VAR ($01c9) Get or set NextBASIC integer variable
The following API calls are related to floppy drives and will not be useful for most software (included for legacy software use only):
DOS_REF_XDPB ($0151) Point at XDPB for low level disk access
DOS_MAP_B ($0154) Map B: onto unit 0 or 1
DD_INTERFACE ($0157) Is the floppy disk driver interface present?
DD_INIT ($015A) Initialise disk driver
DD_SETUP ($015D) Specify drive parameters
DD_SET_RETRY ($0160) Set try/retry count
DD_READ_SECTOR ($0163) Read a sector
DD_WRITE_SECTOR ($0166) Write a sector
DD_CHECK_SECTOR ($0169) Check a sector
DD_FORMAT ($016C) Format a track
DD_READ_ID ($016F) Read a sector identifier
DD_TEST_UNSUITABLE ($0172) Test media suitability
DD_LOGIN ($0175) Log in disk, initialise XDPB
DD_SEL_FORMAT ($0178) Pre-initialise XDPB for DD FORMAT
DD_ASK_1 ($017B) Is unit 1 (external drive) present?
DD_DRIVE_STATUS ($017E) Fetch drive status
DD_EQUIPMENT ($0181) What type of drive?
DD_ENCODE ($0184) Set intercept routine for copy protection
DD_L_XDPB ($0187) Initialise an XDPB from a disk specification
DD_L_DPB ($018A) Initialise a DPB from a disk specification
DD_L_SEEK ($018D) uPD765A seek driver
DD_L_READ ($0190) uPD765A read driver
DD_L_WRITE ($0193) uPD765A write driver
DD_L_ON_MOTOR ($0196) Motor on, wait for motor-on time
DD_L_T_OFF_MOTOR ($0199) Start the motor-off ticker
DD_L_OFF_MOTOR ($019C) 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) Initialise +3DOS
IDE_INTERFACE ($00A3) Initialise card interfaces
IDE_INIT ($00A6) Initialise IDEDOS
IDE_DRIVE ($00A9) Get unit handle
*IDE_SECTOR_READ ($00AC) Low-level sector read
*IDE_SECTOR_WRITE ($00AF) Low-level sector write
*IDE_PARTITION_NEW ($00B8) Create partition
*IDE_PARTITION_INIT ($00BB) Initialise partition
IDE_PARTITON_READ ($00C4) Read a partition entry
IDE_PARTITION_OPEN ($00CD) Open a partition
IDE_PARTITION_CLOSE ($00D0) Close a partition
IDE_PARTITIONS ($01a5) 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) Open a drive as a single file
IDE_FORMAT ($00B2) Format a partition
IDE_PARTITION_ERASE ($00BE) Delete a partition
IDE_PARTITION_RENAME ($00C1) Rename a partition
IDE_PARTITION_WRITE ($00C7) Write a partition entry
IDE_PARTITION_WINFO ($00CA) Write type-specific partition information
IDE_PARTITION_GETINFO ($00D3) Get byte from type-specific partition information
IDE_PARTITION_SETINFO ($00D6) Set byte in type-specific partition information
IDE_DOS_UNPERMANENT ($00FA) Remove permanent drive mapping
IDE_IDENTIFY ($01a2) Return IDE drive identity information
Updated calls
The following calls have new/updated features, which are highlighted in GREEN. (Some changes are due to removed parameters which are not shown). NOTE: Calls for internal use only have not yet been included here.
It should additionally be noted that the IDE_STREAM_* calls may corrupt the alternate register set, in addition to the effects on the standard register set noted for each individual call.
As well as describing additional features, DOS_CATALOG contains additional text which clarifies points that are not obvious from the documentation in the original +3 manual.
DOS_OPEN
0106h (262)
Create and/or open a file
There is a choice of action depending on whether or not the file
already exists. The choices are ‘open action’ or ‘create action’, and
are specified in DE. If the file already exists, then the open action
is followed; otherwise the create action is followed.
Open action
- Error – File already exists.
- Open the file, read the header (if any). Position file
pointer after header.
- Open the file, ignore any header. Position file pointer at
000000h (0).
- Assume given filename is ‘filename.type’. Erase
‘filename.BAK’ (if it exists). Rename ‘filename.type’ to
‘filename.BAK’. Follow create action.
- Erase existing version. Follow create action.
Create action
- Error – File does not exist.
- Create and open new file with a header. Position file
pointer after header.
- Create and open new file without a header. Position file
pointer at 000000h (0).
(Example: To simulate the tape action of… ‘if the file exists open
it, otherwise create it with a header’, set open action = 1, create
action = 1.)
(Example: To open a file and report an error if it does not exist, set
open action = 1, create action = 0.)
(Example: To create a new file with a header, first renaming any
existing version to ‘.BAK’, set open action = 3, create action = 1.)
Files with headers have their EOF position recorded as the smallest
byte position greater than all written byte positions.
Files without headers have their EOF position recorded as the byte at
the start of the smallest 128 byte record position greater than all
written record positions.
Soft-EOF is the character 1Ah (26) and is nothing to do with the EOF
position, only the routine DOS BYTE READ knows about soft-EOF.
The header data area is 8 bytes long and may be used by the caller for
any purpose whatsoever. If open action = 1, and the file exists (and
has a header), then the header data is read from the file, otherwise
the header data is zeroised. The header data is available even if the
file does not have a header. Call DOS REF HEAD to access the header
data.
Note that +3 BASIC makes use of the first 7 of these 8 bytes as
follows:
+—————+——-+——-+——-+——-+——-+——-+——-+
| BYTE | 0 | 1 | 2 | 3 | 4 | 5 | 6 |
+—————+——-+——-+——-+——-+——-+——-+——-+
| Program 0 file length 8000h or LINE offset to prog |
| Numeric array 1 file length xxx name xxx xxx |
| Character array 2 file length xxx name xxx xxx |
| CODE or SCREEN$ 3 file length load address xxx xxx |
+———————————————————————–+
(xxx = doesn’t matter)
If creating a file that will subsequently be LOADed within BASIC, then
these bytes should be filled with the relevant values.
If the file is opened with exclusive-write or exclusive-read-write
access (and the file has a header), then the header is updated when
the file is closed.
A file that is already open for shared-read access on another file
number may only be opened for shared-read access on this file number.
A file that is already open for exclusive-read or exclusive-write or
exclusive-read-write access on another file number may not be opened
on this file number.
If the open action is 1 or 2 and the create action is 0 (ie only an existing file is to be opened) then the filename may optionally contain the wildcard characters * and ?. In this case, the first file that matches the wildcard will be opened.
ENTRY CONDITIONS
B = File number 0…15
C = Access mode required
Bits 0…2 values:
1 = exclusive-read
2 = exclusive-write
3 = exclusive-read-write
5 = shared-read
Bits 3…7 = 0 (reserved)
D = Create action
E = Open action
HL = Address of filename (no wildcards, unless D=0 and E=1 or 2)
EXIT CONDITIONS
If file newly created:
Carry true
Zero true
A corrupt
If existing file opened:
Carry true
Zero false
A corrupt
Otherwise:
Carry false
A = Error code
Always:
BC DE HL IX corrupt
All other registers preserved
DOS_CATALOG
011Eh (286)
Fills a buffer with part of the directory.
The filename optionally specifies the drive, path, user and a (possibly ambiguous) filename (which may contain wildcard characters ? and *).
Since the size of a directory is variable (and may be quite large),
this routine permits the directory to be catalogued in a number of
small sections. The caller passes a buffer pre-loaded with the first
required filename, or zeroes for the start of the directory. The
buffer is loaded with part (or all, if it fits) of the directory
sorted in ASCII order. If more of the directory is required, this
routine is re-called with the buffer re-initialised with the last file
previously returned. This procedure is followed repeatedly until all
of the directory has been catalogued.
Note that +3DOS format disks (which are the same as single-sided,
single track AMSTRAD PCW range format disks) may have a maximum of 64
directory entries.
Buffer format:
Entry 0
Entry 1
Entry 2
Entry 3
…to…
Entry n
Entry 0 must be preloaded with the first ‘filename.type’
required. Entry 1 will contain the first matching filename greater
than the preloaded entry (if any). A zeroised preload entry is OK.
If the buffer is too small for the directory, this routine can be
called again with entry 0 replaced by entry n to fetch the next part
of the directory.
Entry format (13 bytes long):
Bytes 0…7 – Filename (ASCII) left justified, space
filled
Bytes 6…10 – Type (ASCII) left justified, space filledd
Bytes 11…12 – Size in kilobytes (binary)
Any of the filename or extension characters may have bit 7 set, as described in the section on file attributes, so these should be masked off if not required.
The file size is the amount of disk space allocated to the file, not
necessarily the same as the amount used by the file.
ENTRY CONDITIONS
B = n+1, size of buffer in entries, >=2
C = Filter (if bit is set)
bit 0 = include system files
bit 1 = set bit 7 of f7 (the 7th character in the filename) if the entry has a valid LFN (long filename) which can be
obtained with the IDE_GET_LFN call
bit 2 = include directories, and set bit 7 of f8 (the 8th
character in the filename) if the entry is a directory
bits 3…7 = 0 (reserved)
DE = Address of buffer (first entry initialised)
HL = Address of filename (wildcards permitted)
EXIT CONDITIONS
If OK:
Carry true
A corrupt
B = Number of completed entries in buffer, 0…n.
(If B = n, there may be more to come).
HL = Directory handle, required to obtain long filenames
with IDE_GET_LFN
Otherwise:
Carry false
A = Error code
B HL corrupt
Always:
C DE HL IX corrupt
All other registers preserved
DOS_FREE_SPACE
0121h (289)
How much free space is there on this drive?
ENTRY CONDITIONS
A = Drive, ASCII ‘A’…’P’
EXIT CONDITIONS
If OK:
Carry true
A corrupt
HL = Free space (in kilobytes, clamped to maximum 65535K)
BCDE = Free space (in kilobytes)
Otherwise:
Carry false
A = Error code
HL corrupt
Always:
BC DE IX corrupt
All other registers preserved
DOS_GET_POSITION
0133h (307)
Get the file pointer.
ENTRY CONDITIONS
B = File number
EXIT CONDITIONS
If OK:
Carry true
A corrupt
DEHL = File pointer
(D holds most significant byte; L holds least
significant byte)
Otherwise:
Carry false
A = Error code
DE HL corrupt
Always:
BC IX corrupt
All other registers preserved
DOS_GET_EOF
0139h (313)
Get the end of file (EOF) file position greater than all written byte
positions.
Does not affect the file pointer.
Does not consider soft-EOF.
ENTRY CONDITIONS
B = File number
EXIT CONDITIONS
If OK:
Carry true
A corrupt
DEHL = File pointer
(D holds most significant byte; L holds least
significant byte)
Otherwise:
Carry false
A = Error code
DE HL corrupt
Always:
BC IX corrupt
All other registers preserved
IDE_DOS_MAP ($00F1)
Map a drive to the specified partition or physical device
IN: A=unit (0 or 1), or physical device:
2=floppy device 0
3=floppy device 1
4=RAMdisk
BC=partition number
L=drive letter ‘A’ to ‘P’ (uppercase)
OUT(s): Fc=1
OUT(f): Fc=0, A=error code
Register status on return:
……../IX same
AFBCDEHL/.. different
IDE_DOS_UNMAP ($00F4)
Remove mapping from the specified drive
IN: L=drive letter ‘A’ to ‘P’ (uppercase)
OUT(s): Fc=1
OUT(f): Fc=0, A=error code
Register status on return:
……../IX same
AFBCDEHL/.. different
IDE_SNAPLOAD ($00FD)
Load a snapshot
IN: HL=filespec, terminated with $ff
OUT(s): Does not return if successful
OUT(f): Fc=0, A=error code
Register status on return:
……../.. same
AFBCDEHL/IX different
Loads and runs a supported snapshot file (files with extension .Z80, .SNA, .O and .P are supported, with others potentially supported in future).
IDE_PATH ($01b1)
IN: A=reason code,
rc_path_change (0),
rc_path_get (1),
rc_path_make (2),
rc_path_delete (3)
HL=address of pathspec (terminated with $ff)
NB: For rc_path_get, this must also be a 256-byte buffer
into which the returned path will be written
OUT(s): Fc=1
OUT(f): Fc=0, A=error code
Register status on return:
……../…. same
AFBCDEHL/IXIY different
This call allows the current directory or path for a particular drive (and user area) to be changed or obtained. It also allows creation and deletion of directories.
For rc_path_change, rc_path_make and rc_path_delete, HL points to a directory specification, terminated by $ff. This may optionally include a drive letter, user area and full path (if not, the current default values are used). For rc_path_change, the current path on that drive is changed to the directory or path specified. For rc_path_make and rc_path_delete, the named directory is created or deleted.
For rc_path_get, HL points to a location specification (ie a drive and/or user area, terminated with a colon and $ff). The current path for that location will then be written to the buffer at HL and terminated with $ff.
Note that this call will return an error of rc_notimp if the drive on which it is operating is formatted with a filesystem that does not support directories (eg a +3DOS floppy drive or RAMdisk).
New calls
The following calls are new for NextOS.
IDE_CAPACITY ($01b4)
Get card capacity
IN: C=unit (0 or 1)
OUT(s): Fc=1
DEHL=total card capacity in 512-byte sectors
OUT(f): Fc=0, A=error code
Register status on return:
……../.. same
AFBCDEHL/IX different
IDE_GET_LFN ($01b7)
Obtain a long filename
IN: HL=address of filespec provided to the last DOS_CATALOG call
IX=directory handle returned by the last DOS_CATALOG call
DE=address of a file entry within buffer filled by the last DOS_CATALOG call
BC=address of a 261-byte buffer to receive the long filename
OUT(s): Fc=1
Buffer at BC is filled with the long filename for the requested entry,
terminated with $ff. If no long filename was available, the buffer will
contain the properly-formatted short filename instead.
OUT(f): Fc=0, A=error code
Register status on return:
……../.. same
AFBCDEHL/IX different
This call allows a long filename (or properly-formatted short filename) for an entry in the buffer returned by DOS_CATALOG to be obtained.
NOTE: No other +3DOS calls should be made between the DOS_CATALOG call and the (multiple) IDE_GET_LFN calls used to obtain the long filenames.
IDE_BROWSER ($01ba)
Run the file browser
IN: HL=address of supported filetypes buffer, laid out as follows:
+0 (1 byte) Length of next entry, n
+1 (n bytes) 1-3 byte extension, colon, optional BASIC command(s)
If n=$ff there are no further entries.
DE=address of $ff-terminated help text for 2 lines at bottom of screen
A=browser capabilities mask, made by ORing together any of:
$01, BROWSERCAPS_COPY – files may be copied
$02, BROWSERCAPS_RENAME – files/dirs may be renamed
$04, BROWSERCAPS_MKDIR – directories may be created
$08, BROWSERCAPS_ERASE – files/dirs may be erased
$10, BROWSERCAPS_REMOUNT- SD card may be remounted
$80, BROWSERCAPS_SYSCFG – system use only – use browser.cfg
Alternatively just use one of the two special values:
$00, BROWSERCAPS_NONE – no special capabilities
$1f, BROWSERCAPS_ALL – all capabilities enabled
OUT(s): Fc=1
If Fz=1, ENTER was pressed with a filetype that is present in the
filetype buffer, and:
HL=address of short filename (terminated with $ff) in RAM 7
If Fz=0, SPACE/BREAK was pressed
OUT(f): Fc=0, A=error
Register status on return:
……../.. same
AFBCDEHL/IX different
NOTES:
The help text can contain any standard full-screen mode window control codes, but if the character size is changed, it should be changed back to size 5 at the end.
It is intended that applications wishing to use the Browser as a “save file” dialog should direct the user to navigate to the correct drive/directory and press SPACE. At this point the call will exit with the current drive and directory set as the user selected and Fz=0 to indicate SPACE was pressed. Since the screen is not cleared on exit, the application can then request input of the filename on the bottom two lines of the screen, giving a seamless user experience.
Call does not return if a supported filetype was selected which had anything following the colon in the filetype buffer. In this case, the additional data is treated as plain text, then tokenized and executed as a BASIC command. NOTE: No terminator should be added to the end of the command.
The ? character may be used as a wildcard to match a single character in the filetype.
The * character may be used as a wildcard to match remaining characters in the filetype.
Most applications will not want a BASIC command to be executed and so should provide a simple list of all the filetypes that they want to be selectable.
Example filetype buffer contents:
defb 4 ; length of first entry
defm “XYZ:” ; match this filetype and return to caller with it
defb 12 ; length of second entry
defm “X:.hexdump |” ; match this filetype and execute .hexdump on it
defb 3 ; length of third entry
defm “Z?:” ; matches .z3, .z4, .z5 etc
defb 3 ; length of fourth entry
defm “Z*:” ; matches .z, .zip etc
defb $ff ; table terminator
To match all files, you can provide a simple table like this:
defb 2
defm “*:”
defb $ff
IDE_BANK ($01bd)
Allocate or free 8K RAM banks in main ZX memory or DivMMC memory
IN: H=bank type:
rc_banktype_zx (0), ZX memory half-banks (8K size)
rc_banktype_mmc (1), DivMMC memory banks (8K size)
L=reason:
rc_bank_total (0), return total number of 8K banks of specified type
rc_bank_alloc (1), allocate next available 8K bank
rc_bank_reserve (2), reserve bank specified in E (0..total-1)
rc_bank_free (3), free bank specified in E (0..total-1)
E=8K bank ID (0..total-1), for rc_bank_reserve/rc_bank_free
OUT(s): Fc=1
E=8K bank ID (0..total-1), for rc_bank_alloc
E=total number of 8K banks of specified type, for rc_bank_total
OUT(f): Fc=0
A=error: rc_inuse if no available banks to allocate
rc_badparam if H, L or E is invalid
Register status on return:
……../.. same
AFBCDEHL/IX different
NOTE:
This call is provided for applications that wish to co-exist with other applications, dot commands and BASIC programs without overwriting each other’s memory.
Bank IDs are for 8K half-banks, numbered from 0 upwards. For ZX memory they can be paged using the MMU instructions.
NextOS/NextBASIC normally reserves the first 18 x 8K banks of ZX memory for its own use, and the first 6 x 8K banks of DivMMC memory. However, BASIC programs or TSR machine code programs could also reserve memory before your program is loaded, so it is usually easier to allocate using rc_bank_alloc rather than rc_bank_reserve.
Take care to free any banks you allocate before exiting, otherwise they will be unavailable to the user until after a reset. A NEW command *does not* free reserved banks back into the system.
IDE_BASIC ($01c0)
Execute a BASIC command line
IN: HL=address of tokenized BASIC command line, terminated with $0d
OUT(s): Fc=1
System variable ERR_NR contains generated BASIC error code-1
($ff means BASIC command completed successfully)
Register status on return:
……../.. same
AFBCDEHL/IX different
NOTES:
This call must be made with the ROM2/RAM5/RAM2/RAM0 memory configuration rather than the usual +3DOS configuration. The stack must be located between STKEND and RAMTOP (the normal location for the stack during BASIC operation).
Any number of BASIC commands may be executed, separated by colons (:), and the line must be terminated with an ENTER character ($0d).
This call may be particularly useful for setting particular screen modes with the LAYER command, which will ensure that the system variables are correctly set up for printing to windows or the main screen in the selected mode.
IDE_WINDOW_LINEIN ($01c3)
Input line from current window stream
IN: required window has been made current via ROM 3 / $1601
HL=buffer address (must lie entirely below $c000)
A=buffer size (1..255 bytes)
E=number of characters already in the input buffer (0 for an entirely new
input). Must be less than A.
OUT: E=number of characters returned in input buffer
Register status on return:
……../.. same
AFBCDEHL/IX different
NOTES:
This call invokes the window line input handler, allowing the user to enter new characters and edit the input with the cursor keys and delete.
The input buffer can be primed with an initial string for the user to edit. If this is the case, E should be set to the number of characters in the initial string (otherwise, set E=0).
+3 BASIC errors may be invoked
IDE_WINDOW_STRING ($01c6)
Output string to current window stream
IN: required window has been made current via ROM 3 / $1601
HL=address of string (must lie entirely below $c000)
E=string termination condition:
if E=$ff, string is terminated with a $ff character
if E=$80, last character in the string has bit 7 set
if E<$80, E=number of characters in the string (may be
terminated earlier with $ff)
OUT: –
Register status on return:
……../.. same
AFBCDEHL/IX different
NOTES:
This call is intended for efficient outputting of strings to window channels, avoiding the significant per-character overhead associated with outputting each individual character via RST $10 or IDE_STREAM_OUT.
+3 BASIC errors may be invoked
IDE_INTEGER_VAR ($01c9)
Get or set NextBASIC integer variable
IN: B=0 for standard variable, B=1 for array
C=variable number (0=A,1=B…25=Z)
L=array index (0..63) if B=1
H=0 to get variable, 1 to set variable
DE=value (if H=1)
OUT(s): Fc=1
DE=value (if H=0)
OUT(f): Fc=0
A=error: rc_badparam if H, L or E is invalid
Register status on return:
……../.. same
AFBCDEHL/IX different
NOTE:
This call provides a convenient interface to pass values between BASIC and machine-code processes.
Error codes
The error codes that may be returned by +3DOS/IDEDOS calls are as follows:
Recoverable disk errors:
0 rc_ready Drive not ready
1 rc_wp Disk is write protected
2 rc_seek Seek fail
3 rc_crc CRC data error
4 rc_nodata No data
5 rc_mark Missing address mark
6 rc_unrecog Unrecognised disk format
7 rc_unknown Unknown disk error
8 rc_diskchg Disk changed whilst +3DOS was using it
9 rc_unsuit Unsuitable media for drive
Non-recoverable errors:
20 rc_badname Bad filename
21 rc_badparam Bad parameter
22 rc_nodrive Drive not found
23 rc_nofile File not found
24 rc_exists File already exists
25 rc_eof End of file
26 rc_diskfull Disk full
27 rc_dirfull Directory full
28 rc_ro Read-only file
29 rc_number File number not open (or open with wrong access)
30 rc_denied Access denied
31 rc_norename Cannot rename between drives
32 rc_extent Extent missing
33 rc_uncached Uncached
34 rc_toobig File too big
35 rc_notboot Disk not bootable
36 rc_inuse Drive in use
56 rc_invpartition Invalid partition
57 rc_partexist Partition already exists
58 rc_notimp Not implemented
59 rc_partopen Partition open
60 rc_nohandle Out of handles
61 rc_notswap Not a swap partition
62 rc_mapped Drive already mapped
63 rc_noxdpb No XDPB
64 rc_noswap No suitable swap partition
65 rc_invdevice Invalid device
67 rc_cmdphase Command phase error
68 rc_dataphase Data phase error
69 rc_notdir Not a directory
