1 - DOS_INITIALISE

Synopsys

• Initialise +3DOS.
• Initialise disk drivers.
• Initialise cache and the RAMdisk.
• All files closed.
• All drives logged out.
• Default drive A: (if disk interface present), else M:
• Default user 0.
• Retry count 15.
• Error messages disabled.

Entry Parameters

None

Exit Parameters

If OK:

Carry true

A corrupt

Otherwise:

Carry false

A=Error code

Always:

BC DE HL IX corrupt, all other registers preserved.

2 - DOS_VERSION

Synopsys

Get the DOS issue and version numbers.

Entry Parameters

None

Exit Parameters

If OK:

D = Issue

E = Version (within issue)

Otherwise:

Carry false

A=Error code

Always:

BC DE HL IX corrupt, all other registers preserved.

3 - DOS_OPEN

Synopsys

Create and/or open a file

Entry Parameters

Exit Parameters

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.

4 - DOS_CLOSE

Synopsys

Close a file

Entry Parameters

Exit Parameters

If OK:

Carry true

A corrupt

Otherwise:

Carry false

A=Error code

Always:

BC DE HL IX corrupt, all other registers preserved.

5 - DOS_ABANDON

Synopsys

Abandon a file

Similar to DOS CLOSE, except that any header, or data, or directory data yet to be written to disk is discarded. This routine should only be used to force a file closed in the event that DOS CLOSE is unable to close the file (for example, if the media is damaged or permanently changed or removed).

Entry Parameters

Exit Parameters

If OK:

Carry true

A corrupt

Otherwise:

Carry false

A=Error code

Always:

BC DE HL IX corrupt, all other registers preserved.

6 - DOS_REF_HEAD

Synopsys

Point at the header data for this file.

The header data area is 8 bytes long and may be used by the caller for any purpose whatsoever. It is available even if the file does not have a header; however, only files with a header and opened with write access will have the header data recorded on disk.

Note that +3 BASIC uses these 8 bytes (see the note under DOS OPEN which gives the details). If creating a file that will subsequently be LOADed within BASIC, then those bytes should be filled with the relevant values.

Entry Parameters

Exit Parameters

If OK:

Carry true

A corrupt

IX = Address of header data

Otherwise:

Carry false

A = Error code

IX corrupt

Always:

BC DE HL corrupt, all other registers preserved.

7 - DOS_READ

Synopsys

Read bytes from a file into memory, advancing the file pointer in the process.

This routine does not consider any soft-EOF in the file. Attempting to read past the EOF will produce an error.

Entry Parameters

Exit Parameters

If OK:

Carry true

A corrupt

DE corrupt

Otherwise:

Carry false

A = Error code

DE = Number of bytes remaining unread

Always:

BC HL IX corrupt, all other registers preserved.

The value of C is only used when HL is within the upper 16K of memory (0xC000…0xFFFF). If HL is in this range then C is the RAM bank to use. For most purposes C should be set to 0 which is the default RAM bank mapped to that region.

8 - DOS_Write

Synopsys

Write bytes from memory into a file, advancing the file pointer in the process.

Entry Parameters

Exit Parameters

If OK:

Carry true

A corrupt

DE corrupt

Otherwise:

Carry false

A = Error code

DE = Number of bytes remaining unwritten

Always:

BC HL IX corrupt, all other registers preserved.

The value of C is only used when HL is within the upper 16K of memory (0xC000…0xFFFF). If HL is in this range then C is the RAM bank to use. For most purposes C should be set to 0 which is the default RAM bank mapped to that region.

9 - DOS_READ_BYTE

Synopsys

Read a byte from a file, advancing the file pointer in the process. It tests for a soft EOF (0x1A) but it is possible to read past this. Reading to the hard EOF will return an error.

Entry Parameters

Exit Parameters

If OK - not soft-EOF (0x1A)

Carry true

Zero false

A corrupt

C Byte read

If OK - soft-EOF (0x1A)

Carry true

Zero true

A corrupt

C Byte read

Otherwise:

Carry false

A = Error code

C corrupt

Always:

BC DE HL IX corrupt, all other registers preserved.

10 - DOS_WRITE_BYTE

Synopsys

Write a byte to a file, advancing the file pointer in the process.

Entry Parameters

Exit Parameters

If OK

Carry true

A corrupt

Otherwise:

Carry false

A = Error code

Always:

BC DE HL IX corrupt, all other registers preserved.

11 - DOS_CATALOG

Synopsys

Fills a buffer with part of the directory (sorted).

The filename specifies the drive, user and a (possibly ambiguous) filename.

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.

Entry Parameters

Exit Parameters

If OK:

Carry true

A corrupt

B number of completed entries in buffer, 0…n.
If B=n then there may be more entries for subsequent calls

Otherwise:

Carry false

A=Error code

B corrupt

Always:

C DE HL IX corrupt, all other registers preserved.

Buffer format

The buffer passed to this routine consists of 2 or more entries, with the first one initialised with the first filename required. It is valid for the first entry to be all zero's.

If the buffer is too small for the directory then it can be called again with entry 0 being a copy of entry n from the previous call.

The file size is the disk space allocated, not the actual file size.

12 - DOS_FREE_SPACE

Synopsys

Return the amount of free space on a drive.

Entry Parameters

Exit Parameters

If OK:

Carry true

A corrupt

HL = Free space in KB

Otherwise:

Carry false

A=Error code

HL corrupt

Always:

BC DE IX corrupt, all other registers preserved.

13 - DOS_DELETE

Synopsys

Delete an existing file.

The file must not be open on any file number.

Entry Parameters

Exit Parameters

If OK:

Carry true

A corrupt

Otherwise:

Carry false

A=Error code

Always:

BC DE HL IX corrupt, all other registers preserved.

14 - DOS_RENAME

Synopsys

Return the amount of free space on a drive.

Entry Parameters

Exit Parameters

If OK:

Carry true

A corrupt

HL = Free space in KB

Otherwise:

Carry false

A=Error code

HL corrupt

Always:

BC DE IX corrupt, all other registers preserved.

15 - DOS_BOOT

Synopsys

Boot from Disk

This routine loads a single bootstrap sector from the disk in drive A: into memory and enters it. This is for loading games or other operating systems.

Entry Parameters

None

Exit Parameters

If OK:

No exit as the bootstrap has taken over

Otherwise:

Carry false

A=Error code

Always:

BC DE HL IX corrupt, all other registers preserved.

Bootstrap environment

16 - DOS_SET_DRIVE

Synopsys

Set the default drive (i.e. the drive implied by all filenames that do not specify a drive).

The default drive is initially A:

Does not access the drive, but merely checks that there is a driver for it (which does not imply that the drive exists).

This only affects routines that take filename parameters.

Entry Parameters

Exit Parameters

If OK:

Carry true

A = default drive

Otherwise:

Carry false

A=Error code

Always:

BC DE HL IX corrupt, all other registers preserved.

17 - DOS_SET_USER

Synopsys

Set the default user area, i.e. the user area implied by all filenames that do not specify a user number.

The default user number is initially 0.

This only affects routines that take filename parameters.

Entry Parameters

Exit Parameters

If OK:

Carry true

A = default user

Otherwise:

Carry false

A=Error code

Always:

BC DE HL IX corrupt, all other registers preserved.