lordcoxis wrote:With version 0.9.x the API will be considered "stable" and will be fully documented on release. The v0.8.x API was never considered stable, hence it was never publicly released. Everyone that asked for the API docs was alerted to this fact - unfortunately I was never contacted by the NextOS team (I think?) so I don't know if they are aware of this. This doesn't mean that all the work documenting/implementing it is wasted because most things will stay the same, but be prepared for some major changes.
Yes everyone's aware that the api was beta but at the same time, several years in the wild like that probably makes it one of the more stable spectrum apis out there 
I hope you will take a look at the api as is in the next and consider if some of it fits into esxdos as it is evolving. Speaking as a dev, I really would prefer to avoid having two slightly different apis to support. However, at the same time, I've prepared for exactly that by keeping esxdos and nextos-esx separate inside z88dk so that if things divurge, asm or c programs can be made to work with either system with a simple recompile.
There are some things that I think should be brought into the esxdos api:
; ***************************************************************************
; * M_DOSVERSION ($88) *
; ***************************************************************************
; Get API version/mode information.
; Entry:
; -
; Exit:
; For esxDOS <= 0.8.6
; Fc=1, error
; A=14 ("no such device")
;
; For NextZXOS:
; Fc=0, success
; B='N',C='X' (NextZXOS signature)
; DE=NextZXOS version in BCD format: D=major, E=minor version
; eg for NextZXOS v1.94, DE=$0194
; HL=A=0 if running in NextZXOS mode (and zero flag is set)
; HL,A<>0 if running in 48K mode (and zero flag is reset)
This is how I am detecting whether a program is running under esxdos or nextos. On the zx next both systems will be in use. At the moment I check for carry flag set on return to determine if esxdos is running but you could add version information too like has been done for the nextos side with carry reset.
; ***************************************************************************
; * M_ERRH ($95) *
; ***************************************************************************
; Install error handler for dot command.
; Entry: HL=address of error handler within dot command
; (0 to change back to standard handler)
;
; NOTES:
; Can only be used from within a dot command.
; If any BASIC error occurs during a call to ROM3 (using RST $10 or RST $18)
; then your error handler will be entered with:
; DE=address that would have been returned to if the error had not
; occurred
; A=BASIC error code-1 (eg 8=9 STOP statement)
This one registers a function that is called if a basic error occurs before the dot is exited. This is the only way to guarantee that file handles are properly cleaned up and on the next there is a larger problem of memory leaks if allocated pages are not returned to the system. Without this ability, someone pressing space at the scroll prompt to break out of a dot command will cause file handles to leak. Eventually the system will stop working because all the file handles are gone.
; ***************************************************************************
; * M_EXECCMD ($8f) *
; ***************************************************************************
; Execute a dot command.
; Entry:
; IX=address of commandline, excluding the leading "."
; terminated with $00 (or $0d, or ':')
; Exit (success):
; Fc=0
; Exit (failure):
; Fc=1
; A=error code (0 means user-defined error)
; HL=address of user-defined error message within dot command
;
; NOTES:
; The dot command name can be fully-pathed if desired. If just a name is
; provided, it is opened from the C:/BIN directory.
; eg: defm "hexdump afile.txt",0 ; runs c:/bin/hexdump
; defm "./mycommand.dot afile.txt",0 ; runs mycommand.dot in current
; ; directory
; If A=0, the dot command has provided its own error message but this is not
; normally accessible. It can be read using the M_GETERR hook.
; This hook cannot be used from within another dot command.
This one allows a dot command to be called by a program; it's not really essential to implement but in future I intend to generate libraries available as dot commands that can implement services outside of the spectrum's memory space. Things like time functions, network functions, environment functions, etc, that can be made easily available to running programs at essentially no cost except the time to load a divmmc page.
) and a lot of work went into reverse engineering dot commands and whatnot in order to document functions esxdos didn't formally document. So what we have now is a documented nextos esxdos api that is probably correct for esxdos itself. nextos has gone ahead and expanded the api by making available some services from the +3e api but that part can be ignored.
In 0.9.x there is another way to get the version, but I'll see if I can squeeze this in again.