dos.h

DOS_Exit0

void DOS_Exit0()

Exit program and return to DOS When this is called in MSX-DOS, the system is reset by jumping to 0000H. When MSX DISK-BASIC call this, it is “warm started”. That is, it returns to BASIC command level without destroying programs currently loaded. With MSX-DOS 2, this function terminates program with a zero return code.

MSX-DOS 1 Console IO

DOS_CharInput

c8 DOS_CharInput()

Input character A character will be read from the standard input (file handle 0 - usually the keyboard) and echoed to the standard output (file handle 1 - usually the screen). If no character is ready then this function will wait for one. Various control characters, as specified for the "console status" function (function 0Bh), will be trapped by this function for various control purposes. If one of these characters is detected then it will be processed and this function will wait for another character. Thus these characters will never be returned to the user by this function.

Return

Character from keyboard

DOS_CharOutput

void DOS_CharOutput(

chr

)

Output character The character passed in register E is written to the standard output (file handle 1 - usually the screen). If printer echo is enabled then the character is also written to the printer. Various control codes and escape sequences are interpreted as screen control codes. A list of these is included in the "Program Interface Specification", they are a sub-set of the standard VT-52 control codes. TABs will be expanded to every eighth column.

Parameters

chr

Character to be output

DOS_StringOutput

void DOS_StringOutput(

const

c8*

str

)

The characters of the string will be output. The string is terminated by "$" (ASCII 24h).

Parameters

str

const c8*

Address of string

DOS_Beep

inline void DOS_Beep()

Play bip sound

DOS_ClearScreen

inline void DOS_ClearScreen()

Clear console screen

DOS_Return

inline void DOS_Return()

Carriage return

MSX-DOS 1 File Handling

DOS_SetTransferAddr

void DOS_SetTransferAddr(

void*

data

)

Set transfer address This function simply records the address passed in DE as the disk transfer address. This address will be used for all subsequent FCB read and write calls, for "search for first" and "search for next" calls to store the directory entry, and for absolute read and write calls. It is not used by the new MSX-DOS read and write functions. The address is set back to 80h by a DISK RESET call.

Parameters

data

void*

Required Disk Transfer Address

DOS_OpenFCB

u8 DOS_OpenFCB(

DOS_FCB*

stream

)

Open file The unopened FCB must contain a drive which may be zero to indicate the current drive and a filename and extension which may be ambiguous. The current directory of the specified drive will be searched for a matching file and if found it will be opened. Matching entries which are sub-directories or system files will be ignored, and if the filename is ambiguous then the first suitable matching entry will be opened.

Parameters

stream

DOS_FCB*

Pointer to unopened FCB

Return

Error code (DOS_ERR_NONE if succeed)

DOS_GetSizeFCB

inline u32 DOS_GetSizeFCB(

DOS_FCB*

stream

)

Get the size of an opened file

Parameters

stream

DOS_FCB*

Pointer to unopened FCB

Return

File size

DOS_CloseFCB

u8 DOS_CloseFCB(

DOS_FCB*

stream

)

Close file

Parameters

stream

DOS_FCB*

Pointer to unopened FCB

Return

Error code (DOS_ERR_NONE if succeed)

Return

Error code (DOS_ERR_NONE if succeed)

DOS_CreateFCB

u8 DOS_CreateFCB(

DOS_FCB*

stream

)

Create file

Parameters

stream

DOS_FCB*

Pointer to unopened FCB

Return

Error code (DOS_ERR_NONE if succeed)

DOS_SequentialReadFCB

u8 DOS_SequentialReadFCB(

DOS_FCB*

stream

)

Sequential read

Parameters

stream

DOS_FCB*

Pointer to unopened FCB

Return

Error code (DOS_ERR_NONE if succeed)

DOS_SequentialWriteFCB

u8 DOS_SequentialWriteFCB(

DOS_FCB*

stream

)

Sequential write

Parameters

stream

DOS_FCB*

Pointer to unopened FCB

Return

Error code (DOS_ERR_NONE if succeed)

DOS_RandomBlockWriteFCB

u8 DOS_RandomBlockWriteFCB(

DOS_FCB*	stream,
u16	records

)

Random block write

Parameters

stream DOS_FCB*	Pointer to unopened FCB
records u16	Number of records to write

Return

Error code (DOS_ERR_NONE if succeed)

DOS_RandomBlockReadFCB

u16 DOS_RandomBlockReadFCB(

DOS_FCB*	stream,
u16	records

)

Random block read

Parameters

stream DOS_FCB*	Pointer to unopened FCB
records u16	Number of records to write

Return

Number of records actually read

DOS_FindFirstFileFCB

u8 DOS_FindFirstFileFCB(

DOS_FCB*

stream

)

Search the first file matched with wildcard

Parameters

stream

DOS_FCB*

Pointer to unopened FCB

Return

Error code (DOS_ERR_NONE if succeed)

DOS_FindNextFileFCB

u8 DOS_FindNextFileFCB()

Search the second and after the second file matched wildcard

Return

Error code (DOS_ERR_NONE if succeed)

MSX-DOS 2 File Handling

DOS_OpenHandle

u8 DOS_OpenHandle(

const	c8*	path,
	u8	mode

)

Open file handle

Parameters

path const c8*	Drive/path/file ASCIIZ string
mode u8	Open mode

O_RDONLY     Open file for reading only
O_WRONLY     Open file for writing only
O_RDWR       Open file for reading and writing
O_INHERIT

Return

New file handle

DOS_CreateHandle

u8 DOS_CreateHandle(

const	c8*	path,
	u8	mode,
	u8	attr

)

Create file handle

Parameters

path const c8*	Drive/path/file ASCIIZ string
mode u8	Open mode

O_RDONLY     Open file for reading only
O_WRONLY     Open file for writing only
O_RDWR       Open file for reading and writing
O_INHERIT

attr - Required attributes

Return

New file handle

DOS_CloseHandle

u8 DOS_CloseHandle(

file

)

Close file handle

Parameters

file

File handle

Return

Error code

DOS_EnsureHandle

u8 DOS_EnsureHandle(

file

)

Ensure file handle

Parameters

file

File handle

Return

Error code

DOS_DuplicateHandle

u8 DOS_DuplicateHandle(

file

)

Duplicate file handle

Parameters

file

File handle

Return

Error code

DOS_ReadHandle

u16 DOS_ReadHandle(

u8	file,
void*	buffer,
u16	size

)

Read from file handle

Parameters

file u8	File handle
buffer void*	Buffer address
size u16	Number of bytes to read

Return

Number of bytes actually read

DOS_WriteHandle

u16 DOS_WriteHandle(

	u8	file,
const	void*	buffer,
	u16	size

)

Write to file handle

Parameters

file u8	File handle
buffer const void*	Buffer address
size u16	Number of bytes to read

Return

Number of bytes actually written

DOS_SeekHandle

u32 DOS_SeekHandle(

u8	file,
i32	offset,
u8	mode

) __CALLEE

Move file handle pointer

Parameters

file u8	File handle
offset i32	Signed offset
mode u8	Method code

SEEK_SET     Relative to the beginning of the file
SEEK_CUR     Relative to the current position
SEEK_END     Relative to the end of the file

Return

New file pointer

DOS_DeleteHandle

u8 DOS_DeleteHandle(

file

)

Delete file or subdirectory

Parameters

file

File handle

Return

Error code

DOS_RenameHandle

u8 DOS_RenameHandle(

	u8	file,
const	c8*	newPath

)

Rename file or subdirectory

Parameters

file

File handle

Return

Error code

DOS_MoveHandle

u8 DOS_MoveHandle(

	u8	file,
const	c8*	newPath

)

Move the file associated with the specified file handle to the directory specified by the new path string. A file handle cannot be moved if there are any other separately opened file handles for this file (".FOPEN" error), although it can be moved if there are copies of this file handle, and in this case the copies will also be moved. Moving a file handle will not alter the file pointer but it will do an implicit "ensure" operation.

Parameters

file

File handle

Return

Error code

DOS_SetAttributeHandle

u8 DOS_SetAttributeHandle(

u8	file,
u8	attr

)

Set the attributes byte of the file associated with the specified file handle. A file handle cannot have its attributes changed (although they can be read) if there are any other separately opened file handles for this file (".FOPEN" error). The file pointer will not be altered but an implicit "ensure" operation will be done.

Parameters

file

File handle

Return

Error code

DOS_GetAttributeHandle

u8 DOS_GetAttributeHandle(

file

)

Get the attributes byte of the file associated with the specified file handle. A file handle cannot have its attributes changed (although they can be read) if there are any other separately opened file handles for this file (".FOPEN" error). The file pointer will not be altered but an implicit "ensure" operation will be done.

Parameters

file

File handle

Return

Error code

DOS_GetDiskParam

u8 DOS_GetDiskParam(

u8	drv,
DOS_DiskParam*	param

)

Get disk parameters

DOS_Exit

void DOS_Exit(

err

)

Terminate with error code

DOS_Explain

void DOS_Explain(

u8	err,
c8*	str

)

Explain error code

DOS_GetLastError

inline u8 DOS_GetLastError()

Get last error code

DOS_FindFirstEntry

DOS_FIB* DOS_FindFirstEntry(

const	c8*	filename,
	u8	attr

)

Find first entry

DOS_FindNextEntry

DOS_FIB* DOS_FindNextEntry()

Find next entry

DOS_GetLastFileInfo

inline DOS_FIB* DOS_GetLastFileInfo()

Get last file info

DOS_GetFileYear

inline u16 DOS_GetFileYear(

const

DOS_FIB*

fib

)

Get last error code

Parameters

fib

const DOS_FIB*

Pointer to File Info Block structure

Return

Year (from 1980)

DOS_GetFileMonth

inline u8 DOS_GetFileMonth(

const

DOS_FIB*

fib

)

Get last error code

Parameters

fib

const DOS_FIB*

Pointer to File Info Block structure

Return

Month number

DOS_GetFileDay

inline u8 DOS_GetFileDay(

const

DOS_FIB*

fib

)

Get last error code

Parameters

fib

const DOS_FIB*

Pointer to File Info Block structure

Return

Day number

DOS_GetFileHour

inline u8 DOS_GetFileHour(

const

DOS_FIB*

fib

)

Get last error code

Parameters

fib

const DOS_FIB*

Pointer to File Info Block structure

Return

Hours

DOS_GetFileMinute

inline u8 DOS_GetFileMinute(

const

DOS_FIB*

fib

)

Get last error code

Parameters

fib

const DOS_FIB*

Pointer to File Info Block structure

Return

Minutes

DOS_GetFileSecond

inline u8 DOS_GetFileSecond(

const

DOS_FIB*

fib

)

Get last error code

Parameters

fib

const DOS_FIB*

Pointer to File Info Block structure

Return

Seconds

DOS_Delete

u8 DOS_Delete(

const

c8*

path

)

Delete file or subdirectory

Parameters

path

const c8*

Drive/path/file ASCIIZ string or fileinfo block pointer

Return

Error code

DOS_Rename

u8 DOS_Rename(

const	c8*	path,
const	c8*	newPath

)

Rename file or subdirectory

Parameters

path const c8*	Drive/path/file ASCIIZ string or fileinfo block pointer
newPath const c8*	New filename ASCIIZ string

Return

Error code

DOS_Move

u8 DOS_Move(

const	c8*	path,
const	c8*	newPath

)

Move file or subdirectory

Parameters

path const c8*	Drive/path/file ASCIIZ string or fileinfo block pointer
newPath const c8*	New filename ASCIIZ string

Return

Error code

DOS_SetAttribute

u8 DOS_SetAttribute(

const	c8*	path,
	u8	attr

)

Set file attributes

Parameters

path const c8*	Drive/path/file ASCIIZ string or fileinfo block pointer
attr u8	New attributes byte

Return

Error code

DOS_GetAttribute

u8 DOS_GetAttribute(

const

c8*

path

)

Get file attributes

Parameters

path

const c8*

Drive/path/file ASCIIZ string or fileinfo block pointer

Return

Error code

DOS_GetDirectory

u8 DOS_GetDirectory(

	u8	drive,
const	c8*	path

)

Get current directory

Parameters

drive u8	Drive number
path const c8*	Pointer to 64 byte buffer (Filled in with current path after call)

Return

Error code

DOS_GetCurrentDiskDirectory

inline u8 DOS_GetCurrentDiskDirectory(

const

c8*

path

)

Get directory in the current drive

Parameters

path

const c8*

Pointer to 64 byte buffer (Filled in with current path after call)

Return

Error code

DOS_ChangeDirectory

u8 DOS_ChangeDirectory(

const

c8*

path

)

Change current directory

Parameters

path

const c8*

Drive/path/file ASCIIZ string

Return

Error code