Polski English Russian
Home Guide RSXes Files Functions Versions Releases Users Download

ZXVGS functions

All ZXVGS functions are called by RST #08 with number of function placed in following byte (hook code) and the program is continued from address next to hook code.

        RST  #08
        DEFB funcion

On the next tables, in the columns titled input are registers that contain arguments of the function. In the columns titled output are registers in which the function returns its values - other ones are not changed. AF is ignored on input and returned F is not defined. In some situations a function can set bit 7 in R register what means one or more frame INT is missed.

Meaning of the byte after RST 8.
#00 #01 #02 #03 #04 #05 #06 #07 #08 #09 #0A #0B #0C #0D #0E #0F
errors #00 BASIC interpreter errors
errors, I1 #10 BASIC interpreter errors Interface 1 hook codes
I1 #20 Interface 1 hook codes
I1, DISCiPLE #30 I1 h.c. DISCiPLE command codes
DISCiPLE #40 DISCiPLE command codes
internal #70 used internally by RSXes #7F
input, speed #80 joysticks mouse speed keyboard
screen output #90 scrreen support - not used yet #9F
control #A0 informations config sound screen RSXes
memory #B0 memory banks
disks #C0 current path directories disk informations file managing
files #D0 direct file access
data #E0 handling files with headers images savegames raw data fileselectors
printer, overlays #F0 printer overlays system OK
#00 #01 #02 #03 #04 #05 #06 #07 #08 #09 #0A #0B #0C #0D #0E #0F


Internal ROM call

Code #7F is reserved for internal system code. It is used to call the ZXROM from inside of the system.


Note. Calls of #80..#83 functions can be interrupted by user. To prevent from quiting program without saving user work, use function #A3 (will be available in next releases).

It is possible to use 4 independent joysticks. Usually first two are used. The meaning of bits 0..4 is compatibile with value readed from Kempston port (#1F, b0=right, b1=left, b2=down, b3=up, b4=fire). Bit 5 is second fire (usually not used). Bits 6 and 7 are common to all joysticks means two more buttons. Bit 6 (HALT) should cause pause in game (when set) or activate options. Bit 7 (EXIT) should stop the game or go to main menu.

number name description input output
#80 J0 read joysick 0 none A=state
#81 J1 read joysick 1
#82 J2 read joysick 2
#83 J3 read joysick 3

Using the mouse

You can use external mouse (serviced outside main program), also one that generates interrups. Calculating absolute coordinates, painting of pointer and events detection belong to your program duties. To use mouse in any program follow these points.

  1. Disable interrupts! Select IM 2.
  2. Set value of I register (best are #80..#FE). It can't point to ROM!
  3. Fill interrupt page (257 bytes started from I*256) with the same byte value. Caution! Some types of mice (AMX) will generate IM 2 vectors!
  4. At address pointed by I register page place:
            JP   ownint
    The "ownint" is address of standard frame interrupt service. If you don't need own frame interrupt service, you can place EI: RETI instead of this jump.
  5. Reserve 128B buffer for mouse service code. Place its address in HL (#5B00..#FF80). You can't write to this area after installing mouse.
  6. Reserve byte for horizontal change. Place its address in BC.
  7. Reserve byte for vertical change. Place its address in DE.
  8. Call function #84. It will fill the buffer and change the NOPs. Also will change interrupt table if neccesary.
  9. Enable interrupts!

For old programs it is adviced to place XOR A:RET at the beginning of the buffer to avoid program crash while call before mouse initialization.

The coordinates will be changed at given addresses. They are 8 bit values, you can only read them and compare to former value to determine changes. To check buttons just call the beginning of the buffer. It will return button status in A, preserving other registers (b0=LMB, b7=RMB; set means pressed).

Please note that some kinds of mouse (RS232, AMX) can generate own interrupts that aren't useful for the program. All the non-frame interrupts are "eaten" (return address is POPed). And if return address points to byte after HALT opcode, it will be decremented to continue HALT til frame interrupt.

Mouse can be deactivated by giving 0 as buffer address (in HL). Values returned in this case are useful for RSXes - they can uninstall driver used by main program, install own driver to operate an requester, then uninstall own driver and install back the driver of main program.

number name description input output
#84 MSEINI install mouse I=page
ask about mouse HL=??? A=result
uninstall mouse HL=0 A=result
#85 MSEGET get status - only for internal use (driver) none A=keys


Function #87 switches the CPU into high speed mode. The extra speed isn't defined - just the program works faster.

Function #88 switches the CPU back to 3.5MHz.

number name description input output
#87 FAST (Scorpion) - switches Z80 clock up none A=result
#88 SLOW (Scorpion) - switches Z80 clock to 3.5MHz


Extended keyboard should be used to enter text in some programs. Allows use of some additional keys (emulators, SAM Coupé, ZX128 keypad).

Will be used in BASIC if patches or INT traps are available.

Call of function #8F??? should be placed in IM 2 service, at least after pushing AF. Or with disabled interrupts should be called about 50 times per second.

Do not use!!! This isn't finished!!!

number name description input output
#8C? KBDGET get char from buffer ()(A)
#8D? KBDTST read char from buffer and leave it ()(A)
#8E? KBDMOD mode selection (BC)(A=result)
#8F? KBDINT sync. interrupt ()(A)

Screen support

Functions #90..#9F are designed to generate menu, move mouse pointer and display texts in 42, 51 or 64 colums. Also on additional screen modes.

Function #9F prints character on standard screeen using 64 columns mode. Put row in D, column in E, and the character in C. B should be 0 for future compatibility (will select character set for characters 128..255).

They are not available in present ZXVGS release!

number name description input output
#9E? CHOICE ask user what to do HL=^title
#9F CHOUT print character in 64 columns mode D=row

Config and system info

number name description input output
#A0? undefined none

Config of functions

Functions #A2 and #A3 are to control hardware dependent functions. They should not be used in applications (including reading the release number), except config dedicated ones. In D is number of function being configured or #A2 for release number reading. Function #A2 returns current setting in E while the release number in AE. Function #A3 changes setting and returns effective setting (old one when no change were made, new one when change is accepted). Both function return A=0 when getting or setting configuration passed correctly (except for release number reading).

changes value in D value in E means
Joystick type. #80
0 no change
1 Sinclair 1
2 Sinclair 2
3 Kempston
4 Fuller
5 SAM Coupé arrows and <CNTRL>
6 SAM Coupé function keys
7 (undefined)
8 TC2068 left (AY #F5, #F6)
9 TC2068 right (AY #F5, #F6)
Mouse hardware type.
The change fails if mouse
driver is in active mode.
#84 0 Kempston Mouse
1 server mouse
2 SAM Mouse
3 J3 mouse
4 AMX Mouse
5 AY mouse (from Ukraine)
6 (undefined)
7 (undefined)
8 M$ Mouse in YAMOD.8250/0
9 M$ Mouse in YAMOD.8250/1
10 M$ Mouse in YAMOD.8250/2
11 M$ Mouse in YAMOD.8250/3
Release number. #A2 AE - four BCD digits (read only)
Sound info binary mask. #A4 binary mask set bit means "off"
Printer output type. #F7 not defined yet
number name description input output
#A2 GETCFG get current setting of some functions D=function A=error
get ZXVGS release number D=#A2 AE=release
#A3 SETCFG change parametes of some functions D=function

Config of sound

Function #A4 provides information about available sound interfaces. Bit 0 coresponds with beeper in port #FE, bit 1 - BEEPER procedure in ZXROM. Reseted bit means don't generate sound this way (the user don't want to hear such effect). Set bit 2 means the AY-3-8910/2 in ports #BFFD i #FFFD (also #BEFD and #FEFD for some wrong written players) is opened, set bit 3 - the SAA 1099 (SAM Coupé) in ports #00FF i #01FF is opened. When bit of these two isn't set, you mustn't use these ports! It can crash the computer!

When this function is called without prior call of #A5 function (after #AF), it allocates all possible sound devices (near back compatibility, will be removed).

Function #A5 can be used to allocate and deallocate sound device. The device number is provided in D and some parameters in E. (Asterisk "*" means the device has fixed port addresses.) They are:

Parameters for function #A5
register D device register E
#01* AY-3-891X (ZX128) channels (like register 7)
#02* AY-3-8912 (TC2068) channels (like register 7)
#03* both above (1 & 2) channels (like register 7)
#04* SAA1099 (SAM) channels (like register 14 & 15; b6,b7 select)
#08 8255 D/A (MB-02) channels b0..b3
number name description input output
#A4 SOUND sound interface none A=flags
#A5 OPENSOUND allocate sound device D=device

Config of screen

Function #A6 retuns ULA type in D, current screen mode in E and current frame length in BC.

Function #A7 opens video mode. When the frame length is not important, set BC=#0000 and D=#FF. When BC>#0000 or D is different from #FF, ZXVGS will try to change ULA properties (what is possible on emulators and dedicated hardware). Value in D has higher priority than BC (however this is another way to swith the ZS Scorpion into fast mode).

Functions #E8, #E9, #F3 use the screenmode value to load, save or print the screen.

BC - frame length between interrupts in Z80 tacts, measured in IM2, both code and IM 2 table are in fast RAM (not slowed by ULA). To get number of tacts per frame, multiply the BC value by 18 and add 66 (ZX48) or 60 (ZX128) tacts. (However for the Sam Coupé BC must be multiplied by 20, not 18.) Please note that while both ZX48 and TC2048 have the same frame length, the starts of screen drawig are in different tacts.

Parameters - BC and D registers
country number
in D
timing in BC computer name graphics
England #00 3879 Sinclair ZX Spectrum (+) ULA 6C001E-7
#01 3936 Sinclair ZX+ 128 AMSTRAD 40056
#02 3936 Amstrad ZX +2 ULA 7K010E5
#03 3936 Amstrad ZX +2A/+2B/+3 GATE ARRAY 40077
#0C 5987 MGT SAM Coupé ASIC
(+ USA)
#20 3257 Timex Sinclair 2068 TS 2068 - 60Hz
#21 3879 Timex Computer 2068 TS 2068 - 50Hz, grey
#22 3879 Timex Computer 2048 TS 2068 - 50Hz, black
Poland #80 (unknown) ELWRO 800 Junior ?
#?? (unknown) Solum ?
Russia #C0 3979 Pentagon ?
#C1 slow: 3879
fast: 7762
ZS Scorpion ?
Other #F0 3879 Warajevo emulator
#FF ? unknown

LINT: +#80

LINT interface generates interrupt before line set in port #F9 is displayed. Interrupts can be recognized by reading port #F9. Presence should be checked with function #A???. (At this moment only SAM Coupé contains this feature.)

base modes switched modes
value in register E description value in register E description
#00 standard screen at #4000 #08 standard screens at #4000 and #C000
#01 standard screen at #6000 #09 standard screens at #4000 and #6000
#02 high colour screen at #4000 #0A high colour screens at #4000 and #C000
#03 hires screen at #4000 #0B hires screens at #4000 and #C000
#04 standard screen at #C000 #0C four standard screens at #4000, #6000, #C000 and #E000
#05 standard screen at #E000 #0D standard screens at #C000 and #E000
#06 high colour screen at #C000 #0E high colour screen at #4000 and #C000 - 1:3
#07 hires screen at #C000 #0F hires screen at #4000 and #C000 - 1:2

For HL>#4000 at HL is placed relocateable code to select one of base screen mode. In this case L contains length of the code and H - number of tacts it needs. For calls with H=0 the mode is selected directly.

number name description input output
#A6? VIDEO screen informations ? A
#A7 OPENVIDEO sets screen mode BC=frame

Management of Resident System Extensions (RSX)

Function #AC is used to load RSX into system memory without activation. In case of no error (A=0), the handle for selected RSX is returned in D.

Function #AD? calls internal functions of present RSX.

Function #AE is dedicated to control all loaded RSXes. For E=0 places at HL name of file that cause to load the program or error when the program was run directly, not by its file. BC should contain buffer size, at least #0080.

Function #AF loads RSX specified by extension of file name and then this RSX loads required file. E.g. for file "GAME.Z80" the RSX is loaded from file "ZX:Z80.RZX". This doesn't happen for extensions "V00" (ZXVGS native program) and "RZX" (loads RSX directly, not "RZX.RZX").

Function #AF loads:

number name description input output
#AC RSXINIT get RSX DE=^rsxname D=handle
#AD? RSXCTRL call RSX function D=handle
#AE RSXINFO info about RSX E=what
#AF RSXLOAD load file with RSX DE=^filename A=error

Memory banks

With these functions you can manage up to 4MB RAM. (What gives totally 4128kB in 16kB mode or 8208kB in 32kB mode.)


There is 16kB of RAM switched in section D (#C000..#FFFF). It is possible to use virtual banks, which contents will be software moved. Banks #00..#07 are privileged and can be switched faster, with separate functions #B0..#B7 without arguments.

The bank must be opened before any operation on it. If while opening there's no enough memory (RAM for non-virtual bank or external one for virtual) fatal error is generated. Check free space before! Opened bank is filled with zeros. None of functions check PC, SP nor I contents, so using them in wrong context will cause system crash.

If because of hardware reasons it isn't possible to switch section D, only virtual banks are allowed (long time switching). If because of hardware reasons only both C and D sections can be switched together at a time (32kB, #8000..#FFFF) then switching of section D can be simulated with or without rewriting section C. In this case it isn't possible to open bank that is switched fast and don't modifies C section. Section C is copied while opening.

There are three types of banks:

  1. Individual - numbers 0..15 - each can be opened in different mode.
  2. Parametrical - numbers from 16 to the value returned in A by function #BF. This group exists only if function #BF returns in A value greater than 15. Mode of opening is determined for the first opened bank from this group and is the same for all other banks.
  3. Virtual - over value given by #BF function. This group exists only if function #BF returns in A value lower than 255. Mode of opening is determined for the first opened bank from this group and is the same for all other banks. These banks can be opened only as virtual. To open first virtual bank at least one of real banks must be opened as not fast (bit 0 in D reset) - the recent one will change its state to virtual and is used as hardware bank for data of virtual banks (opened formely will keep being real ones).


Functions #B0..#B7 select one of ptivileged bank. Function #B8 selects any bank - its number is provided in E register.

Function #B9 provides informations about banks. Do not use. To get current bank number and its mode, use #BF function.

Function #BA is used to get code that switches bank. See next section for details.

Function #BB copies present section C contents to all other opened 32kB banks or is ignored in case of 16kB chunk switching.

Function #BC tries to opens bank E in mode D, returns effective mode in D. See paramers table.

Function #BD closes bank E. If E means bank actually selected, contents of D section becomes undefined (e.g. can contain ROM contents or values #FF) till selection of another bank.

Function #BE closes all banks. Contents of D section becomes undefined.

Function #BF returns in register E the number of currently selected bank, in register D its mode. In B is returned the amount of opened banks. Register A contains amount of additional banks (not including virtual):

bit in D input for function #BC output of functions #BD and #BF
when set (1) when reseted (0) when set (1)
0 has to switch fast (not virtual)
bit 1
0 1
bit 0 0 16kB virtual 32kB real with section C software moved
1 32kB real 16kB real
1 its choice can't change #8000..#BFFF area
2 has to have displayable screen screen can't be displayed from this bank it is possible to display screen
3 has to correspond with ZX128 bank
OUT (#7FFD),E+#10
not compatibile with #7FFD port corresponds with ZX128 bank
OUT (#7FFD),E+#10
4 has to allow IM 2 table without snowing IM 2 table in this bank causes scereen snowing IM 2 table can be placed in this bank
5 CPU can't be slowed by ULA ULA slowes CPU CPU isn't slowed by ULA
6 must allow 8 graphics bitplanes (???) one bitplane available offers 8 graphics bitplanes (???)
7 open also when requiments not meet opened not opened

Function #BA - Fast bank switching

This feature allows much faster switching of banks. Follow these points.

  1. Determine whether your program will work with 32kB switching. If no, use mode %XXXXXX11 (will not work on some hardware). Otherwise there will be 32kB or 16kB switched at a time. Pay attention to stack and interrupts.
  2. Open bank with function #BC.
  3. Reserve 32B for switching code. The code is always relocateable. To use the code without moving it, you can fill the buffer with "NOP" (#00) and follow with your code. Or fill 33B with "RET" (#C9) or "JP (HL)" (#E9), depending on your program structure.
  4. Reserve two bytes in #5B00..#7FFE, place address of first in BC for first call of #BA functions (for next #BC call is ignored until called with BC=0).
  5. Call function #BA to place switching code for bank E into the buffer adressed with HL. This function will return the real length of code in BC and number of Z80 tacts in A. DE will point to the byte just after code, so you can add (with LDIR) own code here.
  6. To select bank, execute the code.


number name description input output
#B0..#B7 BNK0..BNK7 select privileged bank
generates fatal error if bank isn't opened
none A=?
#B8 BNKE select any bank
generates fatal error if bank isn't opened
E=number A=?
#B9 BNKCTRL bank control - do not use DE=infonumber A
#BA BNKCODE get switching code E=number
#BB BNKCOPY copy C section to other banks none A=?
#BC BNKOPEN open bank D=mode0
#BD BNKCLOSE close bank E=number A=?
#BE BNKRESET close all banks none A=?
#BF BNKINFO bank informations none B=opened

Current path

number name description input output
#C0 GETPATH Returns current path (disk and directories). The returned path always begins with disk name (followed by ":"). DE=^buf A=error
#C1 SETPATH Changes current path. DE=^name A=error

Reading directory contents

Function #C2 gets entry from directory selected by function #C3. HL points to format string (defined by function #C3 is used when either H=0 or HL points to 0 byte; internal system structure is returned when H=1), DE points to a buffer. The entry as plain ASCII (ready to display) is placed at DE. (Use HL=0 to fill the fileselector, then HL=^'%f%n' to get filename selected by user in requester.)

Function #C3 selects directory, counts entries, copies entries to the internal buffer. (The buffer must be released (DE=0) after reading directory is finished.) HL points to format string (system default one is used when either H=0 or HL points to 0 byte; internal system structure is returned when H=1). Following formatters can be used:

Other characters are copied without change. A decimal number between the "%" and letter means the fixed field size. Positive values result right justification, negative - left. Value after dot means number of characters in string to cut. Examples:

"%-16.16m %-3.3e %l" - NeOS 1.0 style (DEC)

"%-8.8m<%1.1e>%3b%13l" - TR-DOS style (start values unavailable)

"%x %-9g%-9u%8l %6d %5t %n" - U*IX style (ls -l)

"%-9.8m%-4.3e%13l%9.8d%9t" - MS-DOS 6.20 style (default)

Internal system structure consists of following fields (not fully defined):

Free disk space can be get with #C4 or #C5 functions.

Note: some disks (mostly the network disks like "TCP:", "HTTP:" or "FTP:") will not show all possible subdirectories, only those that were used recently (or present in bookmarks).

number name description input output
#C2 GETDIR get dir entry BC=number
#C3 SETDIR set dir mask HL=^format

Disk informations

Functions #C4 and #C6 returns informaton of given disk/path or file. Functions #C5 and #C7 change the informaton of given disk/path or file, but only if it is possible.

register C return #C4 #C6
#00 free space on disk in kilobytes HL string ASCIIZ
#01 directory nesting level(1=root) L string ASCIIZ
#?? free space in allocation units DEHL string ASCIIZ
#?? free entries in directory HL string ASCIIZ
#?? allocation unit size in bytes DEHL string ASCIIZ
#?? maximal filename length L string ASCIIZ
#?? disk status HL string ASCIIZ
#?? is place for file of length DEHL L string ASCIIZ
#?? get sector size
BC-cylinder, D-track, E-number
HL string ASCIIZ
#?? get allocation unit size DEHL string ASCIIZ
#?? load/save allocation unit
CDE-unit numer
- unit contents
#?? load/save sector
BC-cylinder, D-track, E-number
string ASCIIZ
#?? buffer address
BC-cylinder, D-track, E-number
err string ASCIIZ
number name description input output
#C4 GETINFO get parameters as numbers DE=^name
#C5 SETINFO set parameters as numbers DE=^name
#C6 GETINF$ get parameters as strings DE=^name
#C7 SETINF$ set parameters as strings DE=^name

Managing of files

Function #CB removes files or directory (directory must be empty).

Function #CC checks whether given file exists (error if not).

Others are still not defined.

number name description input output
#C8? RESET initialize filesystem none A=error
#C9? FLUSH write all buffers to disks
#CA? MAKE creates file or directory DE=^name
#CB KILL removes file or directory (must be empty)
#CC EXIST checks whether file or directory exists
#CD? ASSIGN mounts new disk DE=^name
#CE? MOVE moves or renames files and directories DE=^oldname
#CF? COPY duplicate files and directories DE=^sourcename

Primitive file functions

These functions are for file handling. If you want to load whole file into memory or save memory part as file check #E0..#ED functions first.

Function #D0 always closes file of given handle. If 0 is given as handle, all opened files will be closed. Function #D1 opens file for input (returns error if file not exists). Function #D2 opens file for output - will delete existing file and make new with null length. Function #D3 opens file both for input and output. If file not exists, will be created with first writing.

Functions #D4..#D7 are for read and write file. Functions #D4 and #D5 send given amount of bytes (returns amount of bytes actually sent - lower value than required generates error). Function #D6 reads bytes from file to the limit or to recognize #00 or #0D values (including them). Function #D7 writes bytes till #00 value, which isn't written. Byte #00 will be written only if is first pointed byte.

Function #D8 returns present file position. Function #D9 allows move present file position of any file and returns position before operation. Shift is counted dependly on B regiser: #FF means from beginning, #00 actual position and #01 from end of file. Error value is returned when end or beginning of file are crossed. It is possible to address file of 8MB length (23 bits of address). Function #DA informs whether file is in end position. Function #DB truncates file at actual position.

Following functions are nearly direct calls of FILEDISK system structure. Its definitions can still change in future.

number name description input output
#D0 CLOSE close file D=handle A=error
#D1 OPENI open file for input DE=^name A=error
#D2 OPENO open file for output
#D3 OPENB open file for input and output
#D4 READ read from file D=handle
#D5 WRITE write to file D=handle
#D6? GETL get line from file D=handle
#D7? PUTL put line to file D=handle
#D8 FPOS get file position D=handle EHL=pos
#D9 SEEK set file position D=handle
#DA? EOF end of file info D=handle A=error
#DB? TRUNC truncate file at current position

Files with header

Functions #E0..#E7 are designed to handle files with headers (similar to tape files).

Before calling functions #E4..#E6 the header type must be set by one of #E0..#E3 function. This setting is valid until next call of any #E0..#E3 function. If the file exists then in specified registers will be returned values taken from header of this file. If the file not exists or required header type is collision with readed, error code is returned. This error may be ignored if write to file will be performed, but reads of that file will always resulult error.

On entry to #E3 function the buffer size can be provided in BC. Length returned in BC is limited by this size, while DE contains real size. This is to avoid the tape limitation - you cannot load from real tape some first bytes of longer file as the checksum cannot be checked. Also, BC=#1B00 and HL=#4000 will be recognized as you want to load or save the screen (however you can still load it to or save from other address).

Loading and saving give error when less bytes than reqired were readed or written. Check BC in that case. Verification is equivalent to reading and acts similar to tape one - error is submitted if data varies or file is too short.

Function #E7 called before one of #E4..#E6 function alows set the shift, what gives the possibility of seqential processing of the file. It means e.g. reading succeeding parts of file to different memory banks. Error is retuned when position exceeds file length. Functions #E0..#E3 always set the shift to zero (just after header).

Calling any function of #E4..#E7 without prior call of any of #E0..#E3 causes fatal error.

The file with header can be 65535 bytes long (not including header). The rest will be truncated. The header format may vary in different filesystems. So it is not adviced to process files with header using other functions, unless they are e.g. screens or savegames.

For files with filename extension different from ".CZX", ".DZX", ".DAT", ".ROM", ".SCR" proper RSX is called. So you can e.g. load data or BASIC program from "*.Z80" file! See RSXes description for details.

number name description input output
#E0 HEADER0 program file select DE=^name
#E1 HEADER1 numeric array file select DE=^name
#E2 HEADER2 string array file select
#E3 HEADER3 binary file select DE=^name
#E4 LOAD load memory from selected file BC=len
#E5 SAVE save memory to selected file BC=len
#E6 VERIFY compare memory with selected file BC=len
#E7 SHIFT change position in selected file DE=shift A=error

Screenimage files

To save or load ZX screen, functions #E8 and #E9 should be used. Operation always means 6912 bytes of memory. Separation of these functions allows graphics conversion from/to popular graphics formats. Saved screen has 256x192 pixels and 16 colours, but exceptions are possible. If contents of loaded file isn't compatibile with Spectrum limitations, the result is not defined. Error is returned if file wasn't saved or not exists or the format wasn't recognized.

In future ZXVGS releases RSX will be used to load and save images of file exentions different from ".SCR" and ".CZX". These functions can also display requester with list of available formats when no file extension is given or file not exists (loading) or the filename is empty.

Other screen modes will be also supported.

number name description input output
#E8 LOADSCR load screen from file DE=^name
#E9 SAVESCR save screen to file

Savegame files

Functions #EA and #EB are designed to store and recall the state of game or configuration of utility program. Calling these funtions allows the user to select one of 10 such files. While saving user can comment the file. Files are saved with name of current program and one of "SV0".."SV9" extension (this is selected by user).

For D=0 the requester will not appear and the file with extension ".SV?" as default will be loaded or saved. In this case E contains code of character placed as 3rd one in file suffix (invalid characters are changed to "!"). This feature is to load default configuration at start of program or save configuration on exit. The comment string while saving is set to "Autosaved" (date and time can be included). This can be used together with standard calls (when the user selects an entry).

For function #EA, when HL=0, the address from header is used.

The extension "SV@" (E=#40) is reserved to store high scores file of a game. If the file exists, ZXVGS loads "*.SV@" it just after the "*.V00" file. Then, the file is saved when the user calls ZXVGS menu. In new programs it should be saved with function #EB at every highs scores table modification.

The "*.SV?" files are saved to and loaded from the "SV:" disk.

number name description input output
#EA LOADCFG load settings DE=^title
#EB SAVECFG save settings

Files without header

Function #EC should be used to load whole or initial part of any file to memory. Error code is returned if there were loaded less bytes than required.

Function #ED should be used to save continous area of memory to file. Error code is returned if there are saved less bytes than required (no disk space).

Always check BC in case of error.

number name description input output
#EC LOADANY load any file DE=^name
#ED SAVEANY save any file A=error

File seclectors

Functions #EE and #EF are designed to allow user select or enter file or directory name in easy way. It is possible to give default name and limit choice by mask. Mask can be edited by user, except "*/" what means directory selection. There is also title of operation. For result path 128 bytes of buffer must be reserved. Functions return error when fileselector was exited by <EDIT> or name is empty.

Function #EE always leaves screen (memory area #4000..#5AFF) unchanged, what in some situations manifests in limited form of selector. Function #EF always uses full-screen interface, but leaves screen in random state. Screen refresh is needed.

It is adviced to use file selectors for every file with name defined by user.

When "*.SZX" or "*.SCR" is as the mask, the requester can also allow to select other graphics file format and change file extension respectively.

number name description input output
#EE FILESELL fileselector without screen modification DE=^default
#EF FILESELH fileselector which can modify screen


Function #F0 returns printer control code. In E is code number, in HL addres of buffer for it. In BC is the maximal length (B is ignored - should be 0). When control codes fitted in buffer, BC (B=0) contains number of control characters and A is 0. If the buffer was too small, BC returns required space and A>0. If control code is not available, BC=0 and A>0.

Function #F1 sends required control code directly to printer. See also function #F0.

Function #F2 is equivalent to BASIC COPY.

Function #F3 prints screen (256?192) taken from given address.

Function #F4 simulates ZX Printer on normal character printer.

Function #F5 simulates ZX Printer on matrix printer, but for character printer acts like function #F4.

Function #F6 is dedicated to print texts with national characters. If there's no recoding in system is equivalent to function #F7. Values 1..5 in register D mean ISO-8859-D character set.

Function #F7 sends byte directly to printer (control sequences can be taken with #F0 function).

Functions #F0..#F6 are driven by PRINTER.RZX.

Printer control codes for functions #F0 and #F1
code meaning default for printers
Epson FX
Helwett-Packard Laser Jet
#00 number of wires 8 8
#01 before screen dump 27,65,8 ?
#02 number of dots in mode1 224,1 ?
#03 mode1 selection 27,75,224,1 ?
#04 number of dots in mode2 192,3 ?
#05 mode2 selection 27,76,192,3 ?
#06 code for CR 13 13
#07 code for LF 10 10
number name description input output
#F0 GETPRINT get printer control code E=code
#F1? SETPRINT send printer control code E=code A=error
#F2 DUMP print 22 lines of screen graphics none A=?
#F3? DUMPANY print 24 lines of screen graphics HL=address
#F4 ZXPRINT print one character like ZX Printer E=character
#F5? HLPRINT print character defined at HL like ZX Printer HL=^pattern
#F6? DEPRINT print character with modificator D=modificator
#F7 LPRINT direct printer output E=character


Functions #F8..#FB are for overlays management. Usually overlays are next levels of game. Overlay can be loaded by calling #F8 function with number of overlay. Preparation (function #F9) has only sense in server systems and allow speed up loading (e.g. with Timex FDD 3000) - isn't necessary. Loading overlays into buffer (function #FA) causes faster loading. This is ignored when there's not enough RAM for store. It should be used instead of loading overlays directly into memory banks (like games for both ZX48 and ZX128), because in the buffer overlays are in compressed form and can be also stored in RAM available under ZXROM (MB-02). Function #FB removes overlay from buffer. All functions return amount of free buffer storage in kilobytes. If there's more free space than 254kB, value 255 is returned.

number name description input output
#F8 OVRLOAD load overlay E=0 means main program E=number A=free
#F9 OVRPREPARE load overlay into buffer only if multitasking
#FA OVRSTORE copy overlay into internal buffer
#FB OVRREMOVE remove overlay from internal buffe

System calls

Functions #FC..#FF are for exiting from program to the system menu and quiting program.

Function #FC only calls system menu. The program is continuable. Function #FD ends the program after its finish (closes all opened files, banks, clears overlay buffer, etc.). Function #FE is similar to #FD, but displays given message before menu.

Function #FF is reserved for BASIC interpreter that executes it after last instruction. It is useless for ZXVGS programs. Usually (without RSX) word from XPTR #5C5F will be copied to CHADD #5C5D, #FF will be placed in ERRNR #5C3A and program will be continued from #0058 (error service).

number name description input output
#FC MENU exit to menu, return with "Continue" option none A=???
#FD QUIT quit to menu with message "Program finished" no return
#FE FATAL quit to menu with given message (fatal error) DE=^text
#FF OK used by BASIC none jump to #0058

© 2004-06-30 12:39:51 Jarek Adamski zxvgs@yarek.com, http://zxvgs.yarek.com