The following calls are part of the built-in ResiDOS package.
Available from: v1.40
IN: A=error code returned by ResiDOS/IDEDOS
B=package ID (only needed if A=rc_pkg_*)
OUT: -
Register status on return:
(call does not return)
Generates report message for specified ResiDOS/IDEDOS error code.
Example:
ld a,rc_noswap ; "no swap partition" exx ; switch to alternate set ld b,PKG_RESIDOS ; ResiDOS package ld hl,RESI_REPORT ; ResiDOS call ID rst RST_HOOK ; invoke the package call hook code defb HOOK_PACKAGE
Available from: v1.84
IN: IY=address of routine in BASIC ROM
Other parameters as required by routine
OUT: Outputs from routine in BASIC ROM
Register status on return:
As defined by BASIC ROM routine
Calls a routine in the current BASIC ROM. This isn't terribly useful for normal programs, but is provided to allow packages to call standard routines in the BASIC ROM. Note that the "current" BASIC ROM may be an alternate such as Gosh Wonderful or SE BASIC and so only well-known entry points should be used. The IY register pair is set to ERRNR ($5c3a) by ResiDOS before the BASIC ROM routine is called.
Example:
ld ix,$4000 ; parameters needed by
ld de,$1b00 ; BASIC ROM's "SA-BYTES"
ld a,$ff ; routine to save a screen to tape
ld iy,$04c2 ; SA-BYTES routine address
exx ; switch to alternate set
ld b,PKG_RESIDOS ; ResiDOS package
ld hl,RESI_BASIC ; ResiDOS call ID
call PACKAGE_CALL_PKG ; make the call from this package
Available from: v1.84
IN: DE=address of 32-byte area to hold paging routine
OUT: Fc=1, success
Register status on return:
......../IXIY same
AFBCDEHL/.... different
Installs a routine to the specified location which can be used to switch built-in interface memory to the bottom 16K ($0000-$3fff), where the BASIC ROM is normally located. The routine can be located anywhere you like within the Spectrum's standard memory map (you should allow a space of 32 bytes to hold the routine). If running on a 128K Spectrum, you can place it within any of the additional pages (although it is your responsibility to ensure the correct page is switched in).
Once you have obtained this routine, you can call it at any time with a "bank ID" in A which has previously been provided to you by the calls RESI_FINDPKG, RESI_FINDBASIC or RESI_ALLOC. Do not use any other values! After calling the routine, the 16K memory bank indicated by the "bank ID" will be located at $0000-$3fff. If you are switching in a bank obtained by RESI_ALLOC, don't forget to disable interrupts first, otherwise you may crash. It is safe to leave interrupts enabled when paging in a package or BASIC, provided the interrupt mode is 1.
The paging routine is called as follows:
IN: A=bank ID
OUT: -
Register status on return:
AFBCDEHL/IXIY same
......../.... different
An example of using the call, and the paging routine is as follows:
ld de,mypager ; location for paging routine exx ld b,PKG_RESIDOS ld hl,RESI_GETPAGER ; get paging routine rst RST_HOOK defb HOOK_PACKAGE jr nc,failed ; call failed if Fc=0 .... ; more program di ; disable interrupts ld a,(mybank) ; bank obtained by RESI_ALLOC call mypager ; switch it in to $0000-$3fff .... ; more program ld a,(basicbank) ; bank obtained by RESI_FINDBASIC call mypager ; switch BASIC ROM back in ei ; re-enable interrupts .... ; more program .mypager defs 32 ; 32 bytes to hold paging routine
Available from: v1.84
IN: A=package ID
OUT(s): Fc=1, A=bank ID
OUT(f): Fc=0, A=error code
Register status on return:
....DEHL/IXIY same
AFBC..../.... different
Obtains the bank ID for a package, so that the programmer can page in the package directly using a pager routine obtained with RESI_GETPAGER.
Example:
ld a,PKG_IDEDOS ; request bank for IDEDOS package exx ld b,PKG_RESIDOS ld hl,RESI_FINDPKG ; get bank rst RST_HOOK defb HOOK_PACKAGE jr nc,failed ; call failed if Fc=0 ld (idedos_bank),a ; save for later
Available from: v1.84
IN: -
OUT(s): Fc=1, A=bank ID
OUT(f): Fc=0, A=error code
Register status on return:
..BCDEHL/IXIY same
AF....../.... different
Obtains the bank ID for the version of BASIC currently being used, so that the programmer can page it back in directly using a pager routine obtained with RESI_GETPAGER.
Example:
exx ld b,PKG_RESIDOS ld hl,RESI_FINDBASIC ; get bank rst RST_HOOK defb HOOK_PACKAGE jr nc,failed ; call failed if Fc=0 ld (basic_bank),a ; save for later
Available from: v1.84
IN: -
OUT(s): Fc=1, A=bank ID
OUT(f): Fc=0, A=error code
Register status on return:
......../IXIY same
AFBCDEHL/.... different
Requests a 16K bank of RAM for the program's use. If successful, the bank can be switched in to $0000-$3fff by disabling interrupts and using a pager routine obtained with RESI_GETPAGER. A program or package can request as many banks as it likes, and switch between them using the pager routine.
Example:
exx ld b,PKG_RESIDOS ld hl,RESI_ALLOC ; get free bank rst RST_HOOK defb HOOK_PACKAGE jr nc,failed ; call failed if Fc=0 ld (mybank),a ; save for later
Available from: v1.84
IN: A=bank ID
OUT(s): Fc=1
OUT(f): Fc=0, A=error code
Register status on return:
......../IXIY same
AFBCDEHL/.... different
Frees a 16K bank of RAM previously obtained with RESI_ALLOC. After using this call, the program or package may not access the bank again. If a program fails to de-allocate its banks, they will be reclaimed by the system the next time that ResiDOS starts up. If a package fails to de-allocate its banks when it is uninstalled, they will not be freed (this would be considered to be a bug in the package).
Example:
ld a,(mybank) exx ld b,PKG_RESIDOS ld hl,RESI_DEALLOC ; release bank rst RST_HOOK defb HOOK_PACKAGE
Available from: v2.00
IN: C=screen line
B=screen column
OUT(s): Fc=1
OUT(f): Fc=0, A=error code
Register status on return:
......../IXIY same
AFBCDEHL/.... different
Displays any interface-specific graphical logo at the requested position on screen. If the interface used by this version of ResiDOS does not have a logo (currently only ZXCF interfaces use a logo), then this call returns an error of rc_notimp.
Example:
ld bc,$0800 ; line 0, column 8 exx ld b,PKG_RESIDOS ld hl,RESI_LOGO ; display logo rst RST_HOOK defb HOOK_PACKAGE
Available from: v2.00
IN: A=error code
B=package ID (only needed if A=rc_pkg_*)
DE=address of 23-byte buffer
OUT(s): Fc=1
OUT(f): Fc=0, A=error code
Register status on return:
......../IXIY same
AFBCDEHL/.... different
This call allows you to obtain the text description of any ResiDOS/IDEDOS/ package error obtained from a previous call. The text returned is the same as that which would be generated by the RESI_REPORT call. The buffer you provide at DE must be at least 23 bytes long. If the error code in A is a package-specific error (rc_pkg_error_0...rc_pkg_error_31) then you should also supply the package ID for the call that produced the error in B. Messages obtained are terminated with bit 7 set in the last character.
Example:
ld a,rc_notimp ; get text for "rc_notimp" error
ld b,PKG_RESIDOS ; generated by ResiDOS package
; (not actually needed in this case)
ld de,mybuffer
exx
ld b,PKG_RESIDOS
ld hl,RESI_MESSAGE ; get message to DE
rst RST_HOOK
defb HOOK_PACKAGE
Available from: v2.00
IN: B=reason code:
nmisvc_getregs (0) to obtain NMI register record
nmisvc_putregs (1) to update NMI register record
HL=address of NMI register record
OUT(s): Fc=1
OUT(f): Fc=0, A=error code
Register status on return:
......../.... same
AFBCDEHL/IXIY different
This call is only for the use of packages which implement an NMI handler (ie have PKGCAPS_NMI set in their package capabilities) and should only be called during execution of their package_nmi call.
It allows any NMI handler to obtain the set of register values that were in force at the time that the NMI button was pressed, and to change these before returning from the package_nmi call. This allows the state of the Spectrum to be changed by the NMI handler (Task Manager does this when switching tasks, for example).
The NMI register record obtained is held in the same format as the 30-byte header of v1.45 Z80 snapshot files (described here).
Example:
ld b,nmisvc_getregs ; obtain NMI register record
ld hl,z80hdrbuffer ; address of 30-byte buffer
exx
ld b,PKG_RESIDOS
ld hl,RESI_NMISVC ; get record to HL
call PACKAGE_CALL_PKG ; make the call from this package
Available from: v2.00
IN: A=reason code
BC/DE/HL/IX=parameters, dependent on reason code
OUT(s): Fc=1
Register status on return:
..BCDEHL/IXIY same
AF....../.... different
This call broadcasts an expansion call to all currently-installed packages (using their package_exp call). Any parameters required can be passed in BC/DE/HL/IX and will be preserved; return results from each package called are simply ignored.
Any reason code may be provided to this function; only packages which support the reason code will be affected. Reason codes that are currently supported by one or more packages are:
Note that none of the above reason codes should be broadcast by applications or other packages - they are for internal ResiDOS use only. If you wish to add a new expansion call reason code, please discuss it with me first.
Example:
ld a,exp_boot ; initialise all packages
; DO NOT USE THIS REASON!
exx
ld b,PKG_RESIDOS
ld hl,RESI_BROADCASTEXP ; broadcast to all packages
rst RST_HOOK
defb HOOK_PACKAGE
Available from: v2.00
IN: A=reason code:
rc_config_getvalue (0), to read a numeric value
rc_config_gettext (1), to read a text value
rc_config_setvalue (2), to write a numeric value
rc_config_settext (3), to write a text value
rc_config_delete (4), to delete a value
DE=address of setting name (lower-case, $ff-terminated)
HL=numeric value, or address of text buffer
OUT(s): Fc=1
HL=numeric value (for rc_config_getvalue only)
OUT(f): Fc=0, A=error code
Register status on return:
......../IXIY same
AFBCDEHL/.... different
This call accesses the ResiDOS configuration file, residos.cfg on the boot drive. It can be used to read, write or delete any named entry.
NOTE: It is important that the buffers pointed to be DE and HL do not lie in the top 2K of RAM. They must lie between $4000 and $f800.
Example:
ld b,rc_config_setvalue ; set a numeric value
ld hl,3 ; number to set
ld de,configname ; address of setting name (lower-case, $ff-terminated)
exx
ld b,PKG_RESIDOS
ld hl,RESI_CONFIG
rst RST_HOOK
defb HOOK_PACKAGE
Available from: v2.12
IN: A=reason code:
channelsvc_parseint (0), to parse an integer from a string
channelsvc_parseintmax (1), to parse an integer up to a maximum value from a string
channelsvc_parseintcomma (2), to parse an integer preceded by a comma from a string
channelsvc_parseintcommamax (3), to parse an integer up to a maximum value, preceded by a comma, from a string
channelsvc_create (4), to create a channel
channelsvc_delete (5), to delete a channel
channelsvc_grow (6), to increase the size of a channel
channelsvc_shrink (7), to decrease the size of a channel
For the channelsvc_parseint* calls:
HL=address of string to parse
BC=length of string to parse
DE=maximum value allowable (*max versions only)
For channelsvc_create:
D=channel name (uppercase letter)
Bit 7 may be used as a flag, and is ignored by ResiDOS
E=package ID which handles this channel
H=package call number for output to this channel
L=package call number for input from this channel
BC=total length of channel data (min 11 bytes if no user data)
For channelsvc_delete:
HL=address of channel
For channelsvc_grow, channelsvc_shrink:
HL=address of channel
BC=number of bytes to grow or shrink channel by
OUT(s): Fc=1
For the channelsvc_parseint* calls:
HL=address of string after integer
BC=length of string after integer
DE=value (defaults to zero if no integer found)
For channelsvc_create:
HL=address of channel
DE=address of user data (ie DE=HL+chandata_userdata)
OUT(f): Fc=0, A=error code
Register status on return:
......../IXIY same
AFBCDEHL/.... different
This call provides services for packages that implement extended channels. Only packages can provide channels (since the input/output handlers are always package calls) so application programs should generally not use this call, although they may wish to use the channelsvc_parseint* reasons for non-channel-related purposes.
The channelsvc_parseint* reasons are intended to allow a package to easily parse parameters present in a channel specifier string. A default of zero is used if no integer is found. Therefore, a string "A>,76" would provide values of 0 and 76 when parsed with a channelsvc_parseint followed by a channelsvc_parseintcomma.
The channelsvc_create reason creates a channel in the CHANS area, updating all system variables as appropriate. The layout of all ResiDOS-compatible channels is as follows (as defined in packages.def):
defw $0008 ; "output" routine (switch to ResiDOS)
defw $0008 ; "input" routine (switch to ResiDOS)
defb 'A' ; channel name (single uppercase letter)
defw pkgout ; package call for output routine
defw pkgin ; package call for input routine
defw length ; total length of channel (11+size of user data)
...optional user data follows...
The channelsvc_delete reason deletes a channel, updating all system variables as appropriate.
The channelsvc_grow and channelsvc_shrink reasons increase or decrease the size of a channel, by adding or removing data from the end of the user data area. Channels may not be shrunk to less than 11 bytes. Again, all system variables are kept up-to-date.
Example:
ld a,channelsvc_create ; create a channel
ld d,'X' ; channel name
ld e,MYPKG_ID
ld h,MYOUTCALL
ld l,MYINCALL
ld bc,11+4 ; "X" channel has 4 bytes of user data
exx
ld b,PKG_RESIDOS
ld hl,RESI_CHANNELSVC
call PACKAGE_CALL_PKG ; make the call from this package
Available from: v2.14
IN: A=stream (0..15)
DE=address of string specifying channel to open
BC=length of string specifying channel to open
OUT(s): Fc=1
OUT(f): Fc=0,
Fz=0, A=ResiDOS/IDEDOS/package error code
B=package id (for package error codes)
Fz=1, A=BASIC error code - 1
Register status on return:
......../..IY same
AFBCDEHL/IX.. different
This call allows you to open a stream to any channel descriptor. This can be one of the standard (S, P, or K) channels, or a new channel provided by ResiDOS or a package. This call is directly equivalent to using the BASIC command OPEN #.
Note that, in common with the other RESI_STREAM_* calls, errors generated can be ResiDOS/IDEDOS/package errors (as normally returned by other calls) or they may be a BASIC error code (-1). You should check the zero flag to determine which type of error has been returned. Typically, the only BASIC errors generated are likely to be "O Invalid Stream" (Fz=1, A=$17) or "J Invalid I/O Device" (Fz=1, A=$12).
Example:
ld a,4 ; stream 4
ld de,msg_chan_start
ld bc,msg_chan_end-msg_chan_start
exx
ld b,PKG_RESIDOS
ld hl,RESI_STREAM_OPEN ; open stream to channel
rst RST_HOOK
defb HOOK_PACKAGE
....
.msg_chan_start
defm "i>a:data.txt"
.msg_chan_end
Available from: v2.14
IN: A=stream (0..15)
OUT(s): Fc=1
OUT(f): Fc=0,
Fz=0, A=ResiDOS/IDEDOS/package error code
B=package id (for package error codes)
Fz=1, A=BASIC error code - 1
Register status on return:
......../..IY same
AFBCDEHL/IX.. different
This call closes a stream. If the stream is in the range 0..3, then it is re-attached to its default channel. This call is directly equivalent to using the BASIC command CLOSE #.
Note that, in common with the other RESI_STREAM_* calls, errors generated can be ResiDOS/IDEDOS/package errors (as normally returned by other calls) or they may be a BASIC error code (-1). You should check the zero flag to determine which type of error has been returned. Typically, the only BASIC errors generated are likely to be "O Invalid Stream" (Fz=1, A=$17) or "J Invalid I/O Device" (Fz=1, A=$12).
Example:
ld a,4 ; stream 4
exx
ld b,PKG_RESIDOS
ld hl,RESI_STREAM_CLOSE ; close stream
rst RST_HOOK
defb HOOK_PACKAGE
Available from: v2.14
IN: -
OUT(s): Fc=1,
Fz=0, A=character
Fz=1, character not currently available
(this is not an EOF condition)
OUT(f): Fc=0,
Fz=0, A=ResiDOS/IDEDOS/package error code
B=package id (for package error codes)
Fz=1, A=BASIC error code - 1
Register status on return:
......../..IY same
AFBCDEHL/IX.. different
This call reads a single character from the currently active stream, if one is available. If Fc=1 and Fz=1, a character was not available, but you can loop back and wait until Fc=1 and Fz=0. If the stream is permanently unable to provide a character (an end-of-file condition, for example) then an error will be returned.
NOTE: If the current stream is open to one of the standard channels (K, S or P) then if an error occurs, a BASIC error report may be generated, and no return made to the caller.
Note that, in common with the other RESI_STREAM_* calls, errors generated can be ResiDOS/IDEDOS/package errors (as normally returned by other calls) or they may be a BASIC error code (-1). You should check the zero flag to determine which type of error has been returned. Typically, the only BASIC errors generated are likely to be "O Invalid Stream" (Fz=1, A=$17) or "J Invalid I/O Device" (Fz=1, A=$12).
Example:
exx ld b,PKG_RESIDOS ld hl,RESI_STREAM_IN ; read from stream rst RST_HOOK defb HOOK_PACKAGE
Available from: v2.14
IN: A=character
OUT(s): Fc=1
OUT(f): Fc=0,
Fz=0, A=ResiDOS/IDEDOS/package error code
B=package id (for package error codes)
Fz=1, A=BASIC error code - 1
Register status on return:
......../..IY same
AFBCDEHL/IX.. different
This call writes a single character to the currently active stream.
NOTE: If the current stream is open to one of the standard channels (K, S or P) then if an error occurs, a BASIC error report may be generated, and no return made to the caller.
Note that, in common with the other RESI_STREAM_* calls, errors generated can be ResiDOS/IDEDOS/package errors (as normally returned by other calls) or they may be a BASIC error code (-1). You should check the zero flag to determine which type of error has been returned. Typically, the only BASIC errors generated are likely to be "O Invalid Stream" (Fz=1, A=$17) or "J Invalid I/O Device" (Fz=1, A=$12).
Example:
ld a,'*' exx ld b,PKG_RESIDOS ld hl,RESI_STREAM_OUT ; write '*' to stream rst RST_HOOK defb HOOK_PACKAGE
Available from: v2.14
IN: A=reason code:
streamptr_getptr (0), to obtain the current stream pointer
streamptr_setptr (1), to change the current stream pointer
streamptr_extent (2), to obtain the current stream size
For streamptr_setptr:
DEBC=pointer
OUT(s): Fc=1
For streamptr_getptr:
DEBC=pointer
For streamptr_extent:
DEBC=size
OUT(f): Fc=0,
Fz=0, A=ResiDOS/IDEDOS/package error code
B=package id (for package error codes)
Fz=1, A=BASIC error code - 1
Register status on return:
......../..IY same
AFBCDEHL/IX.. different
This call gets or sets the read/write pointer or size of the currently active stream. If the current stream does not support the requested operation, then the BASIC error code "J Invalid I/O Device" (Fc=0, Fz=1, A=$12) will be returned.
Note that, in common with the other RESI_STREAM_* calls, errors generated can be ResiDOS/IDEDOS/package errors (as normally returned by other calls) or they may be a BASIC error code (-1). You should check the zero flag to determine which type of error has been returned. Typically, the only BASIC errors generated are likely to be "O Invalid Stream" (Fz=1, A=$17) or "J Invalid I/O Device" (Fz=1, A=$12).
Example:
ld a,streamptr_getptr exx ld b,PKG_RESIDOS ld hl,RESI_STREAM_PTR ; get the current stream pointer rst RST_HOOK defb HOOK_PACKAGE
Available from: v2.14
IN: A=stream (0..15)
OUT(s): Fc=1
OUT(f): Fc=0,
Fz=0, A=ResiDOS/IDEDOS/package error code
B=package id (for package error codes)
Fz=1, A=BASIC error code - 1
Register status on return:
......../IXIY same
AFBCDEHL/.... different
This call sets the current stream. This is the stream that all input and output (via BASIC commands and RST $10 as well as through the other RESI_STREAM_* calls) will be sent through.
Note that, in common with the other RESI_STREAM_* calls, errors generated can be ResiDOS/IDEDOS/package errors (as normally returned by other calls) or they may be a BASIC error code (-1). You should check the zero flag to determine which type of error has been returned. Typically, the only BASIC errors generated are likely to be "O Invalid Stream" (Fz=1, A=$17) or "J Invalid I/O Device" (Fz=1, A=$12).
Example:
ld a,4 exx ld b,PKG_RESIDOS ld hl,RESI_STREAM_SELECT ; set the current stream to #4 rst RST_HOOK defb HOOK_PACKAGE
Available from: v2.19
IN: HL=command/function handler ID
floating-point stack: as required by command/function
IX=address of 32-byte parameter buffer (commands only)
IY=ERR_NR ($5c3a)
(IY+0)=command option flags (commands only)
OUT(s): Fc=1
floating-point stack: contains result (functions only)
OUT(f): Fc=0,
Fz=0, A=ResiDOS/IDEDOS/package error code
B=package id (for package error codes)
Fz=1, A=BASIC error code - 1
Register status on return:
......../..IY same
AFBCDEHL/IX.. different
This powerful call allows the machine-code programmer to perform any ResiDOS BASIC command or function (including any supplied by installed packages). On entry, HL contains a command/function handler ID for the required BASIC command or function. These IDs are documented separately for ResiDOS and (optionally) for each package supplying commands and functions.
For functions, the BASIC floating-point stack should contain all the input values required by the function (with the final function parameter being topmost on the floating-point stack). When the function completes, the topmost value on the floating-point stack is the result of the function (if any); all inputs to the function will have been consumed.
For commands, IX should point to a 32-byte buffer containing input parameters for the command (as documented separately for each command). IY should point to the system variable ERR_NR ($5c3a), and this should contain an 8-bit field of command options (as documented separately for each command). Finally, some commands may also require parameters to be loaded on the BASIC floating-point stack (although this is not usual - none of the built-in ResiDOS commands do this). Again, this requirement is documented separately for each command.
If the command or function fails for any reason, a BASIC error report is not generated, but the error status is returned to the caller. If desired, the caller can then generate the BASIC error using the RESI_REPORT call.
Note that this call is not intended to replace the finer control that machine-code programs can obtain by calling lower-level +3DOS, IDEDOS, ResiDOS or package calls, but it can be useful to access functionality that isn't readily exposed except through BASIC commands.
NOTE: Packages may execute commands or functions provided by ResiDOS or other packages, but not from within a command or function handler.
Example:
ld ix,parambuffer
; don't need to set string address,
; as length is zero
ld (ix+2),0 ; string length 0 (low byte)
ld (ix+3),0 ; string length 0 (high byte)
ld (ix+4),2 ; stream 2
ld (iy+0),$80 ; option 7 ("+", expanded catalog)
ld hl,HANDLERID_CAT ; CAT command handler
exx
ld b,PKG_RESIDOS
ld hl,RESI_COMMAND ; execute command: CAT+ #2;""
; (ie same as just CAT+)
rst RST_HOOK
defb HOOK_PACKAGE
...
ld (iy+0),$ff ; remember to reset ERR_NR before
... ; returning to BASIC (also restore H'L')
.parambuffer
defs 32
Available from: v2.20
IN: A=reason code:
im1svc_reg (0) to register the IM1 handler for this package
im1svc_dereg (1) to de-register the IM1 handler for this package
OUT(s): Fc=1
OUT(f): Fc=0, A=error code
Register status on return:
......../IXIY same
AFBCDEHL/.... different
This call is only for the use of packages. By calling this function, a package can register itself to be called whenever an interrupt occurs. When this happens, the package will continue to receive a call to their standard _EXP call with a reason of A=exp_im1. At this point they can perform any operations they like, although it is desirable to keep processing to a minimum. The package must preserve the BCDEHLIXIY registers.
Packages may register or de-register a handler at any time. The interrupt chain is preserved across resets and power cycles. Therefore, packages which enable/ disable interrupt handlers in response to commands or other events may wish to ensure that they deregister their interrupt handler at boot (when EXP_BOOT is supplied to their _EXP call), in case a power cycle/reset occurred when one was still active. It is also important to remember to de-register your package's interrupt handler before allowing it to be uninstalled (ie when your _BYE call is invoked).
Example:
ld a,im1svc_reg ; register interrupt handler
exx
ld b,PKG_RESIDOS
ld hl,RESI_IM1SVC
call PACKAGE_CALL_PKG ; make the call from this package
Available from: v2.21
IN: A=reason code:
tempsvc_lock (0) to lock the temp buffer for this package
tempsvc_unlock (1) to unlock the temp buffer
tempsvc_save (2) to save data to the temp buffer
tempsvc_restore (3) to restore data from the temp buffer
For tempsvc_save & tempsvc_restore:
HL=offset into 2K temporary buffer (0...2047)
DE=memory address to save/restore from
BC=size to save/restore
OUT(s): Fc=1
OUT(f): Fc=0, A=error code
Register status on return:
......../IXIY same
AFBCDEHL/.... different
ResiDOS contains an internal 2K temporary buffer, which it uses to hold data from main memory when performing a memory-intensive operation. The buffer is used during the %CP and CAT BASIC commands, and also during configuration file processing operations. At other times, the buffer is available for the use of a package to save and restore data to.
This call is only for the use of packages, and may not be used during an NMI or IM1 interrupt. Filesystem packages should also not use this call at times when they are likely to be called by the ResiDOS config processing or %CP or CAT commands.
Typically, a package can use this buffer during processing of a BASIC command or other call that it is implementing. On return to the caller, it should always release the temp buffer so that it can be used for other purposes again.
To use the buffer, a package must first lock it using the tempsvc_lock reason. This may fail (with rc_resi_no_room) if the temp buffer is locked by another package. Once locked, the package may issue any number of calls with tempsvc_save and tempsvc_restore to save and restore data in the temp buffer. It is up to the package to manage the 2K area as desired. Finally, the package must unlock the buffer with the tempsvc_unlock reason.
Example:
ld a,tempsvc_lock ; lock the temp buffer
exx
ld b,PKG_RESIDOS
ld hl,RESI_TEMPSVC
call PACKAGE_CALL_PKG ; make the call from this package
jr nc,handle_errors
....
ld a,tempsvc_save ; save data to temp buffer
ld hl,0 ; use offset 0 (start of buffer)
ld de,$c000 ; save from $c000
ld bc,1024 ; 1K to save
exx
ld b,PKG_RESIDOS
ld hl,RESI_TEMPSVC
call PACKAGE_CALL_PKG ; make the call from this package
jr nc,handle_errors
....
ld a,tempsvc_restore ; restore data from temp buffer
ld hl,0 ; use offset 0 (start of buffer)
ld de,$c000 ; restore to $c000
ld bc,1024 ; 1K to restore
exx
ld b,PKG_RESIDOS
ld hl,RESI_TEMPSVC
call PACKAGE_CALL_PKG ; make the call from this package
jr nc,handle_errors
....
ld a,tempsvc_unlock ; unlock the temp buffer
exx
ld b,PKG_RESIDOS
ld hl,RESI_TEMPSVC
call PACKAGE_CALL_PKG ; make the call from this package
jr nc,handle_errors
Available from: v2.23
IN: HL=buffer address
BC=buffer size
OUT(s): Fc=1,
HL=address in buffer following input data
BC=number of characters received
OUT(f): Fc=0,
Fz=0, A=ResiDOS/IDEDOS/package error code
B=package id (for package error codes)
Fz=1, A=BASIC error code - 1
Register status on return:
......../..IY same
AFBCDEHL/IX.. different
This call reads characters from the currently active stream into a buffer until a CR (ASCII 13) character is received. The CR is not added to the buffer (nor is any other terminator). The return values provide the size of the input data returned and the address following the last data byte (so that the user can easily append a terminator if required).
If the buffer is filled before a CR is received, this call will continue to poll the stream and discard all further characters until a CR is obtained.
This call differs from manually calling RESI_STREAM_IN until a CR is received. Some channels provide a special routine for line input, and this will only be invoked by RESI_STREAM_LINEIN, not by RESI_STREAM_IN. For example, window channels will provide an on-screen user prompt where a line can be typed and edited before ENTER is pressed and the result returned. Using RESI_STREAM_IN would only use the character input routine, which provides no on-screen feedback for window channels.
New channels which provide only character input can still be accessed using this routine, which gives a convenient way of obtaining an entire line of input at once. However, the standard channels (of which only "K" allows input) may not be accessed with this routine - use RESI_STREAM_IN instead for this case.
Note that, in common with the other RESI_STREAM_* calls, errors generated can be ResiDOS/IDEDOS/package errors (as normally returned by other calls) or they may be a BASIC error code (-1). You should check the zero flag to determine which type of error has been returned. Typically, the only BASIC errors generated are likely to be "O Invalid Stream" (Fz=1, A=$17) or "J Invalid I/O Device" (Fz=1, A=$12).
Example:
ld hl,buffer ld bc,bufsize exx ld b,PKG_RESIDOS ld hl,RESI_STREAM_LINEIN ; read line from stream rst RST_HOOK defb HOOK_PACKAGE