The Firmware Jumpblock is the recommended method of communicating with the routines in the lower ROM - it is used by BASIC, and it should also be used by other programs. The reason for using the jumpblock is that the routines in the lower ROM are located at different positions on the different machines. The entries in the jumpblock, however, are all in the same place - the instructions in the jumpblock redirect the computer to the correct place in the lower ROM.

Thus, providing a program uses the jumpblock, it should work on any CPC computer. By altering the firmware jumpblock it is possible to make the computer run a different routine from normal. This could either be a different routine in the lower or upper ROM, or a routine written by the user - this is known as 'patching the jumpblock'. It is worth noting that because BASIC uses the firmware jumpblock quite heavily, it is possible to alter the effect of BASIC commands.

The following example will change the effect of calling SCR SET MODE (&BC0E) - instead of changing the mode, any calls to this location will print the letter 'A'. The first thing to do is to assemble the piece of code that will be used to print the letter - this is printed below and starts at &4000.

	ORG &4000
	LD A,65      ; 65 IS ASCII FOR 'A'
	CALL &BB5A   ; TXT OUTPUT
	RET          ; RETURN FROM SUBROUTINE

The jumpblock entry for SCR SET MODE is now patched so that it reroutes all calls to &BC0E away from the lower ROM and to our custom routine at &4000. This is done by changing the bytes at &BC0E, &BC0F and &BC10 to &C3, &00, &40 respectively (ie JP &4000). Any calls to &BC0E or MODE commands will now print the letter A instead of changing mode.

The indirections jumpblock contains a small number of routines which are called by the rest of the firmware. By altering this jumpblock, it is possible to alter the way in which the firmware operates on a large scale - thus it is not always necessary to patch large numbers of entries in the firmware jumpblock.

There are two jumpblocks which are to do with the Kernel (ie the high and low Kernel jumpblocks). The high jumpblock allows ROM states and interrupts to be altered, and also controls the introduction of RSXs. The low jumpblock contains general routines and restart instructions which are used by the computer for its own purposes.

Additionnal informations can be found in SOFT968.

Resets the computer as if it has just been switched on.

After initialisation of the hardware and firmware, control is handed over to ROM 0 (usually BASIC).

Jumps to a routine in either the lower ROM or low RAM.

• All the registers are passed to the destination routine unchanged.

• The registers are as set by the routine in the lower ROM or RAM or are returned unaltered.

The RST &08 instruction is followed by a two byte low address, which is defined as follows:

• if bit 15 is set, then the upper ROM is disabled.
• if bit 14 is set, then the lower ROM is disabled.
• bits 13 to 0 contain the address of the routine to jump to.

This command is used by the majority of entries in the main firmware jumpblock.

	rst &08		 ; LOW JUMP
	dw low_address	 ; address where to jump

Jumps to a routine in either the lower ROM or low RAM

• HL contains the low address.
• All the registers are passed to the destination routine unchanged.

* The registers are as set by the routine in the lower ROM or RAM or are returned unaltered.

The two byte low address in the HL register pair is defined as follows:

• if bit 15 is set, then the upper ROM is disabled.
• if bit 14 is set, then the lower ROM is disabled.
• bits 13 to 0 contain the address of the routine to jump to.

	ld hl,low_address	 ; address where to jump
	call &0B		 ; KL LOW PCHL

Jumps to the specified address.

• BC contains the address to jump to.
• All the registers are passed to the destination routine unaltered.

• The registers are as set by the destination routine or are returned unchanged.

Calls a routine in ROM, in a group of up to four foreground ROMs

• All the registers apart from IY are passed to the destination routine unaltered.

• IY is corrupt.
• The other registers are as set by the destination routine or are returned unchanged.

The RST &10 instruction is followed by a two byte side address, which is defined as follows:

• bits 14 and 15 give a number between 0 and 3, which is added to the main foreground ROM select address - this is then used as the ROM select address.
• bits 0 to 13 contain the address to which is added &C000 - this gives the address of the routine to be called.

	rst &10		 ; SIDE CALL
	dw call_address	 ; address to call

Calls a routine in another ROM.

• HL contains the side address.
• All the registers apart from IY are passed to the destination routine unaltered.

• IY is corrupt.
• The other registers are as set by the destination routine or are returned unchanged.

The two byte side address is defined as follows:

• bits 14 and 15 give a number between 0 and 3, which is added to the main foreground ROM select address - this is then used as the ROM select address.
• bits 0 to 13 contain the address to which is added &C000 - this gives the address of the routine to be called.

Jumps to the specified address.

• DE contains the address to jump to.
• All the registers are passed to the destination routine unaltered.

• The registers are as set by the destination routine or are returned unchanged.

Calls a routine anywhere in ROM or ROM.

• All the registers apart from IY are passed to the destination routine unaltered.

• IY is preserved.
• The other registers are as set by the destination routine or are returned unchanged.

The RST &18 instruction is followed by a two byte in-line address. At this address, there is a three byte far address, which is defined as follows:

• bytes 0 and 1 give the address of the routine to be called
• byte 2 is the ROM select byte which has values as follows:
  • &00 to &FB - select the given upper ROM, enable the upper ROM and disable the lower ROM
  • &FC - no change to the ROM selection, enable the upper and lower ROMs
  • &FD - no change to the ROM selection, enable the upper ROM and disable the lower ROM
  • &FE - no change to the ROM selection, disable the upper ROM and enable the lower ROM
  • &FF - no change to the ROM selection, disable the upper and lower ROMs

When it is retumed from, the ROM selection and state are restored to their settings before the RST 3 command.

Calls a routine, given by the far address in HL & C, anywhere in RAM or ROM.

• HL holds the address of the routine to be called.
• C holds the ROM select byte.
• All the registers apart from IY are passed to the destination routine unaltered.

• IY is preserved.
• The other registers are as set by the destination routine or are returned unchanged.

See FAR CALL above for more details on the ROM select byte.

Jumps to the specified address.

• HL contains the address to jump to.
• All the registers are passed to the destination routine unaltered.

• The registers are as set by the destination routine or are returned unchanged.

Puts the contents of a RAM memory location into the A register.

• HL contains the address of the memory location.

• A holds the contents of the memory location.
• All other registers are preserved.

This routine always reads from RAM, even if the upper or lower ROM is enabled.

Calls a routine anywhere in RAM or ROM.

• HL holds the address of the three byte far address that is to be used.
• All the registers apart from IY are passed to the destination routine unaltered.

• IY is preserved.
• The other registers are as set by the destination routine or are returned unchanged.

See FAR CALL for more details on the three byte far address.

Jumps to a routine in either the lower ROM or the central 32K of RAM.

• All the registers are passed to the destination routine unchanged.

• The registers are as set by the routine in the lower ROM or RAM or are returned unaltered.

The RST &28 instruction is followed by a two byte address, which is the address to jump to; before the jump is made, the lower ROM is enabled, and is disabled when the destination routine is returned from.

This is an RST instruction that may be set aside by the user for any purpose.

Defined by the user.

Defined by the user.

The bytes from &0030 to &0037 are available for the user to put their own code in if they wish.

Deals with normal interrupts.

• All registers are preserved.

The RST &38 instruction must not be used by the user; any external interrupts that are generated by hardware on the expansion port will be dealt with by the EXT INTERRUPT routine.

This area is set aside for dealing with external interrupts that are generated by any extra hardware.

• AF, BC, DE and HL are corrupt.
• All other registers are preserved.

If any external hardware is going to generate interrupts, then the user must patch the area from &003B to &003F so that the computer can deal with the external interrupt; when an external interrupt occurs, the lower ROM is disabled and the code at &003B is called; the default external interrupt routine at &003B simply returns, and this will cause the computer to hang because the interrupt will continue to exist!

Additionnal informations can be found in SOFT968.

Enables the current upper ROM.

• A contains the previous state of the ROM.
• The flags are corrupt.
• All other registers are preserved.

After this routine has been called, all reading from addresses between &C000 and &FFFF refers to the upper ROM, and not the top 16K of RAM which is usually the screen memory; any writing to these addresses still affects the RAM as, by its nature, ROM cannot be written to.

Disables the upper ROM.

• A contains the previous state of the ROM.
• The flags are corrupt.
• All other registers are preserved.

After this routine has been called, all reading from addresses between &C000 and &FFFF refers to the top 16K of RAM which is usually the screen memory.

Enables the lower ROM.

• A contains the previous state of the ROM.
• The flags are corrupt.
• All other registers are preserved.

After this routine has been called, all reading from addresses between &0000 and &4000 refers to the lower ROM, and not the bottom 16K of RAM; any writing to these addresses still affects the RAM as a ROM cannot be written to; the lower ROM is automatically enabled when a firmware routine is called, and is then disabled when the routine returns.

Disables the lower ROM.

• A contains the previous state of the ROM.
• The flags are corrupt.
• All other registers are preserved.

After this routine has been called, all reading from addresses between &0000 and &4000 refers to the bottom 16K of RAM; the lower ROM is automatically enabled when a firmware routine is called, and is then disabled when the routine returns.

Restores the ROM to its previous state.

• A contains the previous state of the ROM.

• AF is corrupt.
• All other registers are preserved.

The previous four routines all return values in the A register which are suitable for use by KL ROM RESTORE.

Selects an upper ROM and also enables it.

• C contains the ROM select address of the required ROM.

• C contains the ROM select address of the previous ROM.
• B contains the state of the previous ROM.

Gets the ROM select address of the current ROM.

• A contains the ROM select address of the current ROM.
• All other registers are preserved.

Gets the class and version of a specified ROM.

• C contains the ROM select address of the required ROM.

• A contains the class of the ROM.
• H holds the version number.
• L holds me mark number.
• B and the flags are corrupt.
• All other registers are preserved.

The ROM class may be one of ine following:

• &00 - a foregroumd ROM.
• &01 - a background ROM.
• &02 - an extension foreground ROM.
• &80 - the built in ROM (ie the BASIC ROM).

Selects the previous upper ROM and sets its state.

• C contains the ROM select address of the ROM to be reselected.
• B contains the state of the required ROM.

• C contains the ROM select address of the current ROM.
• B is corrupt.
• All other registers are preserved.

This routine reverses the action of KL ROM SELECT, and uses the values that it returns in B and C.

Switches off the upper and lower ROMs, and moves a block of memory.

As for a standard LDIR instruction:

• DE holds the destination location.
• HL points to the first byte to be moved.
• BC holds the length of the block to be moved.

• F, BC, DE and HL are set as for a normal LDIR instruction.
• All other registers are preserved.

Switches off the upper and lower ROMs, amd moves a block of memory.

As for a standard LDDR instruction:

• DE holds the first desination location.
• HL points to the highest byte in memory to be moved.
• BC holds the number of bytes to be moved.

• F, BC, DE and HL, are set as for a nommal LDDR instruction.
• All other registers are preserved.

Tests whether an event with a higher priority than the current event is waiting to be dealt with.

• If there is a higher priority event, then Carry is false.
• If there is no higher priority event, then Carry is true.

In either case:

• A and the other flags are corrupt.
• All other registers are preserved.

Ensures that the keyboard is scanned when the next ticker interrupt occurs.

• AF and HL are corrupt.
• All other registers are preserved.

This routine is useful for scanning the keyboard when interrupts are disabled and normal key scanning is not occuring.

The Key Manager is the pack associated with the keyboard. All the attributes of the keyboard are generated and controlled by the Key Manager. These attributes include repeat speed, shift and control keys, function keys and key translation. The joysticks are also scanned by the Key Manager.

Initialises the Key Manager and sets up everything as it is when the computer is first switched on:

• the key buffer is emptied
• Shift and Caps lock are turned off
• All the expansion and translation tables are reset to normal

See also the routine KM RESET below.

• AF, BC, DE and HL corrupt.
• All other registers are preserved.

Resets the Key Manager; the key buffer is emptied and all current keys/characters are ignored.

• AF, BC, DE and HL are corrupt.
• All other registers are preserved.

See also KM INITIALISE above: on the 664 or 6128, the key buffer can also be cleared separately by calling the KM FLUSH routine.

Waits for the next character from the keyboard buffer.

• Carry is true
• A holds the character value
• The other flags are corrupt
• All other registers are preserved.

Tests to see if a character is available from the keyboard buffer, but doesn't wait for one to become available.

• If a character was available, then Carry is true, and A contains the character
• otherwise Carry is false, and A is corrupt.

In both cases, the other registers are preserved.

Saves a character for the next use of KM WAIT CHAR or KM READ CHAR.

• A contains the ASCII code of the character to be put back.

• All registers are preserved.

Assigns a string to a key code.

• B holds the key code.
• C holds the length of the string.
• HL contains the address of the string (must be in RAM).

• If it is OK, then Carry is true, otherwise Carry is false.

In either case:

• A, BC, DE and HL are corrupt.
• All other registers are preserved.

Reads a character from an expanded string of characters.

• A holds an expansion token (ie a key code).
• L holds the character position number (starts from 0).

• If it is OK, then Carry is true, and A holds the character
• otherwise Carry is false, and A is corrupt.

In either case:

• DE and flags are corrupt.
• The other registers are preserved.

Sets aside a buffer area for character expansion strings.

• DE holds the address of the buffer.
• HL holds the length of the buffer.

• If it is OK, then Carry is true; otherwise Carry is false.*

In either case, A, BC, DE and HL are corrupt.

The buffer must be in the central 32K of RAM and must be at least 49 bytes long.

Waits for a key to be pressed - this routine does not expand any expansion tokens.

• Carry is true.
• A holds the character or expansion token
• All other registers are preserved.

Tests whether a key is available from the keyboard.

• If a key is available, then Carry is true, and A contains the character.
• Otherwise Carry is false, and A is corrupt.

In either case, the other registers are preserved.

Any expansion tokens are not expanded.

Tests if a particular key (or joystick direction or button) is pressed.

• A contains the key/joystick number.

• If the requested key is pressed, then Zero is false, otherwise Zero is true

In either case:

• Carry is false.
• A and HL are corrupt.
• C holds the Shift and Control status.
• All other registers are preserved.

After calling this, C will hold the state of shift and control:

• if bit 7 is set then Control was pressed.
• if bit 5 is set then Shift was pressed.

Gets the state of the Shift and Caps locks.

• If L holds &FF then the shift lock is on.
• If L holds &00 then the Shift lock is off.
• If H holds &FF then the caps lock is on.
• If H holds &00 then the Caps lock is off.

Whatever the outcome, all the other registers are preserved.

Reads the present state of any joysticks attached.

• H and A contains the state of joystick 0.
• L holds that state of joystick 1.
• All other registers are preserved.

The joystick states are bit significant and are as follows:

• Bit 0 - Up
• Bit 1 - Down
• Bit 2 - Left
• Bit 3 - Right
• Bit 4 - Fire2
• Bit 5 - Fire1
• Bit 6 - Spare
• Bit 7 - Always zero

The bits are set when the corresponding buttons or directions are operated.

Sets the token or character that is assigned to a key when neither Shift nor Control are pressed.

• A contains the key number.
• B contains the new token or character.

• AF and HL are corrupt.
• All other registers are preserved.

Special values for B are as follows:

• &80 to &9F: these values correspond to the expansion tokens.
• &FD: this causes the caps lock to toggle on and off.
• &FE: this causes the shift lock to toggle on and off.
• &FF: causes this key to be ignored.

Finds out what token or character will be assigned to a key when neither Shift nor Control are pressed.

• A contains the key number.

• A contains the token / character that is assigned.
• HL and flags are corrupt.
• All other registers are preserved.

See KM SET TRANSLATE for special values that can be returned.

Sets the token or character that will be assigned to a key when Shift is pressed as well.

• A contains the key number.
• B contains the new token or character.

• AF and HL are corrupt
• All other registers are preserved.

See KM SET TRANSLATE for special values that can be set.

Finds out what token/character will be assigned to a key when Shift is pressed as well.

• A contains the key number.

• A contains the token/character that is assigned
• HL and flags are corrupt
• All other registers are preserved.

See KM SET TRANSLATE for special values that can be returned.

Sets the token or character that will be assigned to a key when Control is pressed as well.

• A contains the key number and B contains the new token/character.

• AF and HL are corrupt.
• All other registers are preserved.

See KM SET TRANSLATE for special values that can be set.

Finds out what token or character will be assigned to a key when Control is pressed as well.

• A contains the key number.

• A contains the token/character that is assigned.
• HL and flags are corrupt.
• All other registers are preserved.

See KM SET TRANSLATE for special values that can be set.

Sets whether a key may repeat or not.

• A contains the key number.
• B contains &00 if there is no repeat and &FF if it is to repeat.

• AF, BC and HL are corrupt
• All other registers are preserved.

Finds out whether a key is set to repeat or not.

• A contains a key number.

• If the key repeats, then Zero is false.
• If the key does not repeat, then Zero is true.

In either case:

• A, HL and flags are corrupt.
• Carry is false.
• All other registers are preserved.

Sets the time that elapses before the first repeat, and also set the repeat speed.

• H contains the time before the first repeat.
• L holds the time between repeats (repeat speed).

• AF is corrupt.
• All other registers are preserved.

The values for the times are given in 1/50th seconds, and a value of 0 counts as 256.

Finds out the time that elapses before the first repeat and also the repeat speed.

• H contains the time before the first repeat
• L holds the time between repeats.
• All others are preserved.

Arms the Break mechanism.

• DE holds the address of the Break handling routine.
• C holds the ROM select address for this routine.

• AF, BC, DE and HL are corrupt.
• All the other registers are preserved.

Disables the Break mechanism.

• AF and HL are corrupt.
• All the other registers are preserved.

Generates a Break interrupt if a Break routine has been specified by KM ARM BREAK.

• AF and HL are corrupt.
• All other registers are preserved.

The Text VDU is a character based screen driver. It controls 8 different streams each of which can have an area of screen allocated to it (a window). The Text VDU allows characters to be written to the screen and read from the screen. It also treats certain 'characters' as 'control codes' which can have various effects, from moving the cursor to setting the colour of an ink.

Initialise the text VDU to its settings when the computer is switched on:

• resetting all the text VDU indirections.
• selecting Stream 0.
• resetting the text paper to pen 0 and the text pen to pen 1.
• moving the cursor to the top left corner of the screen and setting the writing mode to be opaque.

• AF, BC, DE and HL are corrupt, and all other registers are preserved.

Resets the text VDU indirections and the control code table.

• AF, BC, DE and HL are corrupt, and all other registers are preserved.

Allows characters to be printed on the screen in the current stream.

• AF is corrupt, and all other registers are preserved.

Prevents characters from being printed to the current stream.

• AF is corrupt, and all the other registers are preserved.

Output a character or control code (&00 to &1F) to the screen.

• A contains the character to output.

• All registers are preserved.

Any control codes are obeyed and nothing is printed if the VDU is disabled; characters are printed using the TXT OUT ACTION indirection; if using graphics printing mode, then control codes are printed and not obeyed.

Print a character at the current cursor position - control codes are printed and not obeyed.

• A contains the character to be printed.

• AF, BC, DE and HL are corrupt, and all others are preserved.

This routine uses the TXT WRITE CHAR indirection to put the character on the screen.

Read a character from the screen at the current cursor position.

• If it was successful then A contains the character that was read from the screen and Carry is true;
• Otherwise Carry is false, and A holds 0.

In either case, the other flags are corrupt, and all registers are preserved.

This routine uses the TXT UNWRITE indirection.

Enables or disables graphics print character mode.

• To switch graphics printing mode on, A must be non-zero.
• To turn it off, A must contain zero.

• AF corrupt, and all other registers are preserved.

When turned on, control codes are printed and not obeyed; characters are printed by GRA WR CHAR.

Sets the boundaries of the current text window - uses physical coordinates.

• H holds the column number of one edge.
• D holds the column number of the other edge.
• L holds the line number of one edge.
• E holds the line number of the other edge.

• AF, BC, DE and HL are corrupt.

The window is not cleared but the cursor is moved to the top left corner of the window.

Returns the size of the current window - returns physical coordinates.

• H holds the column number of the left edge.
• D holds the column number of the right edge.
• L holds the line number of the top edge.
• E holds the line number of the bottom edge.
• A is corrupt.
• Carry is false if the window covers the entire screen, and the other registers are always preserved.

Clears the window (of the current stream) and moves the cursor to the top left corner of the window.

• AF, BC, DE and HL are corrupt, and all others are preserved.

Sets the cursor's horizontal position.

• A contains the logical column number to move the cursor to.

• AF and HL are corrupt, and all the other registers are preserved.

See also TXT SET CURSOR.

Sets the cursor's vertical position.

• A contains the logical line number to move the cursor to.

• AF and HL are corrupt, and all other registers are preserved.

See also TXT SET CURSOR.

Sets the cursor's vertical and horizontal position.

• H contains the logical column number.
• L contains the logical line number.

• AF and HL are corrupt, and all other registers are preserved.

See also TXT SET COLUMN and TXT SET ROW.

Gets the cursor's current position.

• H holds the logical column number.
• L holds the logical line number.
• A contains the roll count.
• The flags are corrupt, and all the other registers are preserved.

The roll count is increased when the screen is scrolled down, and is decreased when it is scrolled up.

Allows the text cursor to be displayed (if it is allowed by TXT CUR ON) - intended for use by the user.

• AF is corrupt, and all other registers are preserved.

Prevents the text cursor from being displayed -intended for use by the user.

• AF is corrupt, and all others are preserved.

Allows the text cursor to be displayed - intended for use by the operating system.

• All registers and flags are preserved.

Prevents the text cursor from being displayed -intended for use by the operating system.

• All registers and flags are preserved.

Checks whether a cursor position is within the current window.

• H contains the logical column number to check.
• L holds the logical line number.

• H holds the logical column number where the next character will be printed.
• L holds the logical line number.
• If printing at this position would make the window scroll up, then Carry is false and B holds &FF.
• If printing at this position would make the window scroll down, then Carry is false and B contains &00.
• If printing at the specified cursor position would not scroll the window, then Carry is true and B is corrupt;
• A and the other flags are corrupt, and all other registers are preserved.

Puts a 'cursor blob' on the screen at the current cursor position.

• AF is corrupt, and all other registers are preserved.

It is possible to have more than one cursor in a window (see also TXT DRAW CURSOR); do not use this routine twice without using TXT REMOVE CURSOR between.

Removes a 'cursor blob' from the current cursor position.

• AF is corrupt, and all the others are preserved.

This should be used only to remove cursors created by TXT PLACE CURSOR, but see also TXT UNDRAW CURSOR.

Sets the foreground PEN for the current stream.

• A contams the PEN number to use.

• AF and HL are corrupt, and all other registers are preserved.

Gets the foreground PEN for the current stream.

• A contains the PEN number.
• The flags are corrupt, and all other registers are preserved.

Sets the background PAPER for the current stream.

• A contains the PEN number to use.

• AF and HL are corrupt, and all other registers are preserved.

Gets the background PAPER for the current stream.

• A contains the PEN number
• The flags are corrupt, and all other registers are preserved.

Swaps the current PEN and PAPER colours over for the current stream.

• AF and HL are corrupt, and all others are preserved.

Sets the character write mode to either opaque or transparent.

• For transparent mode, A must be non-zero.
• For opaque mode, A has to hold zero.

• AF and HL are corrupt, and all other registers are preserved.

Setting the character write mode has no effects on the graphics VDU.

Gets the character write mode for the current stream.

• If in transparent mode, A is non-zero.
• If in opaque mode, A is zero.
• In either case DE, HL and flags are corrupt, and the other registers are preserved.

Gets the address of a character matrix.

• A contains the character whose matrix is to be found.

• If it is a user-defined matrix, then Carry is true.
• If it is in the lower ROM then Carry is false.

In either case:

• HL contains the address of the matrix.
• A and other flags are corrupt, and others are preserved.

The character matrix is stored in 8 bytes; the first byte is for the top row of the character, and the last byte refers to the bottom row of the character; bit 7 of a byte refers to the leftmost pixel of a line, and bit 0 refers to the rightmost pixel in Mode 2..

Installs a matrix for a user-defined character.

• A contains the character which is being defined.
• HL contains the address of the matrix to be used.

• If the character is user-definable then Carry is true; otherwise Carry is false, and no action is taken.
• In both cases AF, BC, DE and HL are corrupt, and all other registers are preserved.

Sets the address of a user-defined matrix table.

• DE is the first character in the table.
• HL is the table's address (in the central 32K of RAM).

• If there are no existing tables then Carry is false, and A and HL are both corrupt
• otherwise Carry is true, A is the first character and HL is the table's address.
• In both cases BC, DE and the other flags are corrupt.

Gets the address of a user-defined matrix table.

See TXT SET M TABLE above for details of the values that can be returned.

Gets the address of the control code table.

• HL contains the address of the table.
• All other registers are preserved.

The table has 32 entries, and each entry has three bytes: byte 1 is the number of parameters needed by the control code, bytes 2 and 3 are the address of the routine, in the Lower ROM, to execute the control code.

Selects a new VDU text stream.

• A contains the value of the stream to change to.

• A contains the previously selected stream.
• HL and the flags are corrupt, and all other registers are preserved.

Swaps the states of two stream attribute tables.

• B contains a stream number.
• C contains the other stream number.

• AF, BC, DE and HL are corrupt, and all other registers are preserved.

The foreground pen and paper, the window size, the cursor position, the character write mode and graphic character mode are all exchanged between the two streams.

The Graphics VDU allows individual pixels (dots) on the screen to be set or tested and lines to be drawn. The plotting takes place on an ideal screen that is always 640 points wide and 400 points high. This means that more than one point on the ideal screen will map onto a particular pixel on the real screen. The width of the ideal screen (640 points) is chosen to be the horizontal number of pixels on the screen in the highest resolution mode (mode 2). The height of the ideal screen (400 points) is chosen to be twice the vertical number of pixels on the screen in all modes. This ensures that the aspect ratio of the screen is approximately unity, i.e. a circle looks circular and not elliptical.

Initialises the graphics VDU to its default set-up (ie its set-up when the computer is switched on).

• AF, BC, DE and HL are corrupt, and all other registers are preserved.

Sets the graphics indirections to their defaults, sets the graphic paper to text pen 0 and the graphic pen to text pen 1, reset the graphics origin and move the graphics cursor to the bottom left of the screen, reset the graphics window and write mode to their defaults.

Resets the graphics VDU.

• AF, BC, DE and HL are corrupt, and all other registers are preserved.

Resets the graphics indirections and the graphics write mode to their defaults.

Moves the graphics cursor to an absolute screen position.

• DE contains the user X-coordinate.
• HL holds the user Y-coordinate.

• AF, BC, DE and HL are corrupt, and all other registers are preserved.

Moves the graphics cursor to a point relative to its present screen position.

• DE contains the X-distance to move.
• HL holds the Y- distance.

• AF, BC, DE and HL are corrupt, and all other registers are preserved.

Gets the graphics cursor's current position.

• DE holds the user X-coordirlate.
• HL holds the user Y- coordinate.
• AF is corrupt, and all other registers are preserved.

Sets the graphics user origin's screen position.

• DE contains the standard X-coordinate.
• HL holds the standard Y-coordinate.

• AF, BC, DE and HL are corrupt, and all other registers are preserved.

Gets the graphics user origin's screen position.

• DE contains the standard X-coordinate.
• HL holds the standard Y-coordinate.
• All other registers are preserved.

Sets the left and right edges of the graphics window.

• DE contains the standard X-coordinate of one edge.
• HL holds the standard X-coordinate of the other side.

• AF, BC, DE and HL are corrupt, and all the other registers are preserved.

The default window covers the entire screen and is restored to its default when the mode is changed; used in conjunction with GRA WIN HEIGHT.

Sets the top and bottom edges of the graphics window.

• DE contains the standard Y-coordinate of one side.
• HL holds the standard Y-coordinate of the other side.

• AF, BC, DE and HL are corrupt, and all other registers are preserved.

See GRA WIN WIDTH for further details.

Gets the left and right edges of the graphics window.

• DE contains the standard X-coordinate of the left edge.
• HL contains the standard Y-coordinate of the right edge.
• AF is corrupt, and all other registers are preserved.

Gets the top and bottom edges of the graphics window.

• DE contains the standard Y-coordinate of the top edge.
• HL contains the standard Y-coordinate of the bottom edge
• AF is corrupt, and all other registers are preserved.

Clears the graphics window to the graphics paper colour and moves the cursor back to the user origin.

• AF, BC, DE and HL are corrupt, and all other registers are preserved.

Sets the graphics PEN.

• A contains the required text PEN number.

• AF is corrupt, and all other registers are preserved.

Gets the graphics PEN.

• A contains the text PEN number.
• The flags are corrupt, and all other registers are preserved.

Sets the graphics PAPER.

• A contains the required text PEN number.

• AF corrupt, and all others are preserved.

Gets the graphics PAPER.

• A contains the text PEN number.
• The flags are corrupt, and all other registers are preserved.

Plots a point at an absolute user coordinate, using the GRA PLOT indirection.

• DE contains the user X-coordinate.
• HL holds the user Y-coordinate.

• AF, BC, DE and HL are corrupt, and all other registers are preserved.

Plots a point at a position relative to the current graphics cursor, using the GRA PLOT indirection.

• DE contains the relative X-coordinate.
• HL contains the relative Y-coordinate.

• AF, BC, DE and HL are corrupt, and all other registers are preserved.

Moves to an absolute position, and tests the point there using the GRA TEST indirection.

• DE contains the user X-coordinate.
• HL holds the user Y-coordinate for the point you wish to test.

• A contains the pen at the point.
• BC, DE, HL and flags are corrupt, and all other registers are preserved.

Moves to a position relative to the current position, and tests the point there using the GRA TEST indirection.

• DE contains the relative X-coordinate.
• HL contains the relative Y-coordinate.

• A contains the pen at the point.
• BC, DE, HL and flags are corrupt, and all other registers are preserved.

Draws a line from the current graphics position to an absolute position, using GRA LINE.

• DE contains the user X-coordinate.
• HL holds the user Y-coordinate of the end point.

• AF, BC, DE and HL are corrupt, and all other registers are preserved.

The line will be plotted in the current graphics pen colour (may be masked to produce a dotted line on a 6128).

Draws a line from the current graphics position to a relative screen position, using GRA LINE.

• DE contains the relative X-coordinate.
• HL contains the relative Y-coordinate.

• AF, BC, DE and HL are corrupt, and all other registers are preserved.

See GRA LINE ABSOLUTE above for details of how the line is plotted.

Writes a character onto the screen at the current graphics position.

• A contains the character to be put onto the screen.

• AF, BC, DE and HL are corrupt, and all the other registers are preserved.

As in BASIC, all characters including control codes are printed; the character is printed with its top left comer at the current graphics position; the graphics position is moved one character width to the right so that it is ready for another character to be printed.

The Screen Pack is used by the Text and Graphics VDUs to access the hardware of the screen. It also controls the features of the screen that affect both the Text VDU and Graphics VDU, such as what mode the screen is in.

Initialises the Screen Pack to the default values used when the computer is first switched on.

• AF, BC, DE and HL are corrupt, and all other registers are preserved.

All screen indirections are restored to their default settings, as are inks and flashing speeds; the mode is switched to MODE 1 and the screen is cleared with PEN 0; the screen address is moved to &C000 and the screen offset is set to zero.

Resets the Screen Pack's indirections, flashing speeds and inks to their default values.

• AF, BC, DE and HL are corrupt, and all other registers are preserved.

Sets the screen offset to the specified values - this can cause the screen to scroll.

• HL contains the required offset, which should be even.

• AF and HL are corrupt, and all other registers are preserved.

The screen offset is reset to 0 whenever its mode is set, or it is cleared by SCR CLEAR (but not BASIC's CLS).

Sets the location in memory of the screen - effectively can only be &C000 or &4000.

• A contains the most significant byte of the screen address required.

• AF and HL are corrupt, and all other registers are preserved.

The screen memory can only be set at 16K intervals (ie &0000, &4000, &8000, &C000) and when the computer is first switched on the 16K of screen memory is located at &C000).

Gets the location of the screen memory and also the screen offset.

• A holds the most significant byte of the screen address.
• HL holds the current offset.
• All other registers are preserved.

Sets the screen mode.

• A contains the mode number - it has the same value and characteristics as in BASIC.

• AF, BC, DE and HL are corrupt, and all other registers are preserved.

The windows are set to cover the whole screen and the graphics origin is set to the bottom left corner of the screen; in addition, the current stream is set to zero, and the screen offset is zeroed.

Gets the current screen mode.

• If the mode is 0, then:
  • Carry is true.
  • Zero is false.
  • A contains 0.
• If the mode is 1, then:
  • Carry is false.
  • Zero is true.
  • A contains 1.
• If the mode is 2, then:
  • Carry is false.
  • Zero is false.
  • A contains 2.
• In all cases the other flags are corrupt and all the other registers are preserved.

Clears the whole of the screen.

• AF, BC, DE and HL are corrupt, and all other registers are preserved.

Gets the size of the whole screen in terms of the numbers of characters that can be displayed.

• B contains the number of characters across the screen.
• C contains the number of characters down the screen.
• AF is corrupt, and all other registers are preserved.

Gets the memory address of the top left corner of a specified character position.

• H contains the character physical column.
• L contains the character physical row.

• HL contains the memory address of the top left comer of the character.
• B holds the width in bytes of a character in the present mode.
• AF is corrupt, and all other registers are preserved.

Gets the memory address of a pixel at a specified screen position.

• DE contains the base X-coordinate of the pixel.
• HL contains the base Y-coordinate.

• HL contains the memory address of the pixel.
• C contains the bit mask for this pixel.
• B contains the number of pixels stored in a byte minus 1.
• AF and DE are corrupt, and all other registers are preserved.

Calculates the screen address of the byte to the right of the specified screen address (may be on the next line).

• HL contains the screen address.

• HL holds the screen address of the byte to the right of the original screen address.
• AF is corrupt, all others are preserved.

Calculates the screen address of the byte to the left of the specified screen address (this address may actually be on the previous line).

• HL contains the screen address.

• HL holds the screen address of the byte to the left of the original address.
• AF is corrupt, all others are preserved.

Calculates the screen address of the byte below the specified screen address.

• HL contains the screen address.

• HL contains the screen address of the byte below the original screen address.
• AF is corrupt, and all the other registers are preserved.

Calculates the screen address of the byte above the specified screen address.

• HL contains the screen address.

• HL holds the screen address of the byte above the original address.
• AF is corrupt, and all other registers are preserved.

Converts a PEN to provide a mask which, if applied to a screen byte, will convert all of the pixels in the byte to the appropriate PEN.

• A contains a PEN number.

• A contains the encoded value of the PEN.
• Flags are corrupt, and all other registers are preserved.

The mask returned is different in each of the screen modes.

Converts a PEN mask into the PEN number (see SCR INK ENCODE for the reverse process).

• A contains the encoded value of the PEN.

• A contains the PEN number.
• Flags are corrupt, and all other registers are preserved.

Sets the colours of a PEN - if the two values supplied are different then the colours will alternate (flash).

• A contains the PEN number.
• B contains the first colour.
• C holds the second colour.

• AF, BC, DE and HL are corrupt, and all other registers are preserved.

Gets the colours of a PEN.

• A contains the PEN number.

• B contains the first colour.
• C holds the second colour.
• AF, DE and HL are corrupt, and all other registers are preserved.

Sets the colours of the border - again if two different values are supplied, the border will flash.

• B contains the first colour.
• C contains the second colour.

• AF, BC, DE and HL are corrupt, and all other registers are preserved.

Gets the colours of the border.

• B contains the first colour.
• C holds the second colour.
• AF, DE and HL are corrupt, and all other registers are preserved.

Sets the speed with which the border's and PENs colours flash.

• H holds the time that the first colour is displayed.
• L holds the time the second colour is displayed for.

• AF and HL are corrupt, and all other registers are preserved.

The length of time that each colour is shown is measured in 1/50ths of a second, and a value of 0 is taken to mean 256 * 1/50 seconds - the default value is 10 * 1/50 seconds.

Gets the periods with which the colours of the border and PENs flash.

• H holds the duration of the first colour.
• L holds the duration of the second colour.
• AF is corrupt, and all other registers are preserved.

See SCR SET FLASHING for the units of time used.

Fills an area of the screen with an ink - this only works for 'character-sized' blocks of screen.

• A contains the mask for the ink that is to be used.
• H contains the left hand colurnn of the area to fill.
• D contains the right hand column.
• L holds the top line.
• E holds the bottom line of the area (using physical coordinates).

• AF, BC, DE and HL are corrupt, and all other registers are preserved.

Fills an area of the screen with an ink - this only works for 'byte-sized' blocks of screen.

• C contains the encoded PEN that is to be used.
• HL contains the screen address of the top left hand corner of the area to fill.
• D contains the width of the area to be filled in bytes.
• E contains the height of the area to be filled in screen lines.

• AF, BC, DE and HL are corrupt, and all other registers are preserved.

The whole of the area to be filled must lie on the screen otherwise unpredictable results may occur.

Inverts a character's colours; all pixels in one PEN's colour are printed in another PEN's colour, and vice versa.

• B contains one encoded PEN.
• C contains the other encoded PEN.
• H contains the physical column number.
• L contains the physical line number of the character that is to be inverted.

• AF, BC, DE and HL are corrupt, and all the other registers are preserved.

.

Scrolls the entire screen up or down by eight pixel rows (ie one character line).

• B holds the direction that the screen will roll.
• A holds the encoded PAPER which the new line will appear in.

• AF, BC, DE and HL are corrupt, and all other registers are preserved.

This alters the screen offset; to roll down, B must hold zero, and to roll upwards B must be non-zero.

Scrolls part of the screen up or down by eight pixel lines - only for 'character-sized' blocks of the screen.

• B holds the direction to roll the screen.
• A holds the encoded PAPER which the new line will appear in.
• H holds the left column of the area to scroll.
• D holds the right column.
• L holds the top line.
• E holds the bottom line.

• AF, BC, DE and HL are corrupt, and all other registers are preserved.

The area of the screen is moved by copying it; to roll down, B must hold zero, and to roll upwards B must be non-zero; this routine uses physical roordinates.

Changes a character matrix from its eight byte standard form into a set of pixel masks which are suitable for the current mode - four *8 bytes are needed in mode 0, two *8 bytes in mode 1, and 8 bytes in mode 2.

• HL contains the address of the matrix.
• DE contains the address where the masks are to be stored.

• AF, BC, DE and HL are corrupt, and all other registers are preserved.

Changes a set of pixel masks (for the current mode) into a standard eight byte character matrix.

• A contains the encoded foreground PEN to be matched against (ie the PEN that is to be regarded as being set in the character).
• H holds the physical column of the character to be 'repacked'.
• L holds the physical line of the character.
• DE contains the address of the area where the character matrix will be built.

• AF, BC, DE and HL are corrupt, and all the others are preserved.

Sets the screen write mode for graphics.

• A contains the write mode (0=Fill, 1=XOR, 2=AND, 3=OR).

• AF, BC, DE and HL are corrupt, amd all other registers are preserved.

The fill mode means that the ink that plotting was requested in is the ink that appears on the screen; in XOR mode, the specified ink is XORed with ink that is at that point on the screen already before plotting; a similar situation occurs with the AND and OR modes.

Puts a pixel or pixels on the screen regardless of the write mode specified by SCR ACCESS above.

• B contains the mask of the PEN to be drawn with.
• C contains the pixel mask.
• HL holds the screen address of the pixel.

• AF is corrupt, amd all others are preserved.

Draws a honzontal line on the screen using the current graphics write mode.

• A contains the encoded PEN to be drawn with.
• DE contains the base X-coordinate of the start of the line.
• BC contains the end base X-coordinate.
• HL contains the base Y-coordinate.

• AF, BC, DE and HL are conupt, and all other registers are preserved.

The start X-coordinate must be less than the end X-coordinate.

Draws a vertical line on the screen using the current graphics write mode.

• A contains the encoded PEN to be drawn with.
• DE contains the base X-coordinate of the line.
• HL holds the start base Y-coordinate.
• BC contains the end base Y-coordinate - the start coordinate must be less than the end coordinate.

• AF, BC, DE and HL are corrupt, and all the other registers are preserved.

Initialises the cassette manager.

• AF, BC, DE and HL are corrupt, and all the other registers are preserved.

Both read and write streams are closed. Tape messages are switched on and the default speed is reselected

Sets the speed at which the cassette manager saves programs.

• HL holds the length of 'half a zero' bit.
• A contains the amount of precompensation.

• AF and HL are corrupt.

The value in HL is the length of time that half a zero bit is written as; a “one” bit is twice the length of a “zero” bit; the default values (ie SPEED WRITE 0) are 333 microseconds (HL) and 25 microseconds (A) for SPEED WRITE 1, the values are given as 107 microseconds and 50 microseconds respectively.

Enables or disables the display of cassette handling messages.

• To enable the messages then A must be 0, otherwise the messages are disabled.

• AF is corrupt, and all other registers are preserved.

Switches on the tape motor.

• If the motor operates properly then Carry is true.
• If ESC was pressed then Carry is false.
• In either case:
  • A contains the motor's previous state.
  • Flags are corrupt, and all other registers are preserved.

Switches off the tape motor.

• If the motor turns off then Carry is true.
• If ESC was pressed then Carry is false.
• In both cases:
  • A holds tbe motor's previous state.
  • Flags are corrupt, all others are preserved.

Resets the tape motor to its previous state.

• A contains the previous state of the motor (eg from CAS START MOTOR or CAS STOP MOTOR)

• If the motor operates properly then Carry is true.
• If ESC was pressed then Carry is false.
• In all cases, A and the other flags are corrupt and all others are preserved.

Opens an input buffer and reads the first block of the file.

• B contains the length of the filename.
• HL contains the filename's address.
• DE contains the address of the 2K buffer to use for reading the file.

• If the file was opened successfully, then:
  • Carry is true.
  • Zero is false.
  • HL holds the address of a buffer containing the file header data.
  • DE holds the address of the destination for the file.
  • BC holds the file length.
  • A holds the file type.
• If the read stream is already open then:
  • Carry and Zero are false.
  • A contains an error number (664/6128 only).
  • BC, DE and HL are corrupt.
• If ESC was pressed by the user, then:
  • Carry is false.
  • Zero is true.
  • A holds an error number (664/6128 only).
  • BC, DE and HL are corrupt.
• In all cases, IX and the other flags are corrupt, and the others are preserved.

A filename of zero length means “read the next file on the tape”. The stream remains open until it is closed by either CAS IN CLOSE or CAS IN ABANDON.

Disc: Similar to tape except that if there is no header on the file, then a fake header is put into memory by this routine.

Closes an input file.

• If the file was closed successfully, then Carry is true and A is corrupt.
• If the read stream was not open, then Carry is false, and A holds an error code (664/6128 only).
• In both cases, BC, DE, HL and the other flags are all corrupt.

Disc: All the above applies, but also if the file failed to close for any other reason, then Carry is false, Zero is true and A contains an error number.

In all cases the drive motor is turned off immediately.

Abandons an input file.

• AF, BC, DE and HL are corrupt, and all other registers are preserved.

Disc: All the above applies for the disc routine.

Reads in a single byte from a file.

• If a byte was read, then Carry is true, Zero is false, and A contains the byte read from the file.
• If the end of file was reached, then Carry and Zero are false, A contains an error number (664/6128 only) or is corrupt (for the 464).
• If ESC was pressed, then Carry is false, Zero is true, and A holds an error number (664/6128 only) or is corrupt (for the 464).
• In all cases, IX and the other flags are corrupt, and all other registers are preserved.

Disc: All the above applies for the disc routine.

Reads an entire file directly into memory.

• HL contains the address where the file is to be placed in RAM.

• If the operation was successful, then:
  • Carry is true.
  • Zero is false.
  • HL contains the entry address.
  • A is corrupt.
• If it was not open, then:
  • Carry and Zero are both false.
  • HL is corrupt.
  • A holds an error code (664/6128) or is corrupt (464).
• If ESC was pressed:
  • Carry is false.
  • Zero is true.
  • HL is corrupt.
  • A holds an error code (664/6128 only).
• In all cases, BC, DE and IX and the other flags are corrupt, and the others are preserved.

This routine cannot be used once CAS IN CHAR has been used.

Disc: All the above applies to the disc routine.

Puts the last byte read back into the input buffer so that it can be read again at a later time.

• All registers are preserved.

The routine can only return the last byte read and at least one byte must have been read.

Disc: All the above applies to the disc routine.

Tests whether the end of file has been encountered.

• If the end of file has been reached, then Carry and Zero are false, and A is corrupt.
• If the end of file has not been encountered, then Carry is true, Zero is false, and A is corrupt.
• If ESC was pressed then Carry is false, Zero is true and A contains an error number (664/6128 only).
• In all cases, IX and the other flags are corrupt, and all other registers are preserved.

Disc: All the above applies to the disc routine.

Opens an output file

• B contains the length of the filename.
• HL contains the address of the filename.
• DE holds the address of the 2K buffer to be used.

• If the file was opened correctly, then:
  • Carry is true.
  • Zero is false.
  • HL holds the address of the buffer containing the file header data that will be written to each block.
  • A is corrupt.
• If the write stream is already open, then:
  • Carry and Zero are false.
  • A holds an error number (664/6128).
  • HL is corrupt.
• If ESC was pressed then:
  • Carry is false.
  • Zero is true.
  • A holds an error number 664/6128).
  • HL is corrupt.
• In all cases, BC, DE, IX and the other flags are corrupt, and the others are preserved.

The buffer is used to store the contents of a file block before it is actually written to tape.

Disc: The same as for tape except that the filename must be present in its usual AMSDOS format.

Closes an output file.

• If the file was closed successfully, then Carry is true, Zero is false, and A is corrupt.
• If the write stream was not open, then Carry and Zero are false and A holds an error code (664/6128 only).
• If ESC was pressed then Carry is false, Zero is true, and A contains an error code (664/6128 only).
• In all cases, BC, DE, HL, IX and the other flags are all corrupt.

The last block of a file is written only when this routine is called; if writing the file is to be abandoned, then CAS OUT ABANDON should be used instead.

Disc: All the above applies to the disc routine.

Abandons an output file.

• AF, BC, DE and HL are corrupt, and all others are preserved.

When using this routine, the current last block of the file is not written to the tape.

Disc: Similar to the tape routine; if more than 16K of a file has been written to the disc, then the first 16K of the file will exist on the disc with a file extension of .$$$ because each 16K section of the file requires a separate directory entry.

Writes a single byte to a file.

• A contains the byte to be written to the file output buffer.

• If a byte was written to the buffer, then Carry is true, Zero is false, and A is corrupt.
• If the file was not open, then Carry and Zero are false, and A contains an error number (664/6128 only) or is corrupt (on the 464).
• If ESC was pressed, then Carry is false, Zero is true, and A contains an error number (664/6128 only) or it is corrupt (on the 464).
• In all cases, IX and the other flags are corrupt, and all other registers are preserved.

If the 2K buffer is full of data then it is written to the tape before the new character is placed in the buffer; it is important to call CAS OUT CLOSE when all the data has been sent to the file so that the last block is written to the tape.

Disc: All the above applies to the disc routine.

Writes an entire file directly to tape.

• HL contains the address of the data which is to be written to tape.
• DE contains the length of this data.
• BC contains the execution address.
• A contains the file type.

• If the operation was successful, then Carry is true, Zero is false, and A is corrupt.
• If the file was not open, Carry and Zero are false, A holds an error number (664/6128) or is corrupt (464).
• If ESC was pressed, then Carry is false, Zero is true, and A holds an error code (664/6128 only).
• In all cases BC, DE, HL, IX and the other flags are corrupt, and the others are preserved.

This routine cannot be used once CAS OUT CHAR has been used.

Disc: All the above applies to the disc routine.

Creates a catalogue of all the files on the tape.

• DE contains the address of the 2K buffer to be used to store the information.

• If the operation was successful, then Carry is true, Zero is false, and A is corrupt.
• If the read stream is already being used, then Carry and Zero are false, and A holds an error code (664/6128) or is corrupt (for the 464).
• In all cases, BC, DE, HL, IX and the other flags are corrupt and all other registers are preserved.

This routine is only left when the ESC key is pressed (cassette only) and is identical to BASIC's CAT command.

Disc: All tbe above applies, except that a sorted list of files is displayed; system files are not listed by this routine.

Writes data to the tape in one long file (ie not in 2K blocks).

• HL contains the address of the data to be written to tape.
• DE contains the length of the data to be written.
• A contains the sync character.

• If the operation was successful, then Carry is true and A is corrupt.
• If an error occurred then Carry is false and A contains an error code.
• In both cases, BC, DE, HL and IX are corrupt, and all other registers are preserved.

For header records the sync character is &2C, and for data it is &16; this routine starts and stops the cassette motor and also turns off interrupts whilst writing data.

Reads data from the tape in one long file (ie as originally written by CAS WRITE only).

• HL holds the address to place the file.
• DE holds the length of the data.
• A holds the expected sync character.

• If the operation was successful, then Carry is true and A is corrupt.
• If an error occurred then Carry is false and A contains an error code.
• In both cases, BC, DE, HL and IX are corrupt, and all other registers are preserved.

For header records the sync character is &2C, and for data it is &16; this routine starts and stops the cassette motor and turns off interrupts whilst reading data.

Compares the contents of memory with a file record (ie header or data) on tape.

• HL contains the address of the data to check.
• DE contains the length of the data.
• A holds the sync character that was used when the file was originally written to the tape.

• If the two are identical, then Carry is true and A is corrupt.
• If an error occurred then Carry is false and A holds an error code.
• In all cases, BC, DE, HL, IX and other flags are corrupt, and all other registers are preserved.

For header records the sync character is &2C, and for data it is &16; this routine starts and stops the cassette motor and turns off interrupts whilst reading data; does not have to read the whole of a record, but must start at the beginning.

Resets the sound manager by clearing the sound queues and abandoning any current sounds.

• AF, BC, DE and HL are corrupt, and all others are preserved.

Adds a sound to the sound queue of a channel.

• HL contains the address of a series of bytes which define the sound and are stored in the central 32K of RAM.

• If the sound was successfully added to the queue, then Carry is true and HL is corrupt.
• If one of the sound queues was full, then Carry is false and HL is preserved.
• In either case, A, BC, DE, IX and the other flags are corrupt, and all others are preserved.

The bytes required to define the sound are as follows:

• byte 0 - channel status byte
• byte 1 - volume envelope to use
• byte 2 - tone envelope to use
• bytes 3&4 - tone period
• byte 5 - noise period
• byte 6 - start volume
• bytes 7&8 - duration of the sound, or envelope repeat count

Gets the status of a sound channel.

• A contains the channel to test - for channel A, bit 0 set; for channel B, bit 1 set; for channel C, bit 2 set.

• A contains the channel status.
• BC, DE, HL and flags are corrupt, and all other registers are preserved.

The channel status returned is bit significant, as follows:

• bits 0 to 2 - the number of free spaces in the sound queue
• bit 3 - trying to rendezvous with channel A
• bit 4 - trying to rendezvous with channel B
• bit 5 - trying to rendezvous with channel C
• bit 6 - holding the channel
• bit 7 - producing a sound

Sets up an event which will be activated when a space occurs in a sound queue.

• A contains the channel to set the event up for (see SOUND CHECK for the bit values this can take).
• HL holds the address of the event block.

• AF, BC, DE and HL are corrupt, and all other registers are preserved.

The event block must be initialised by KL INIT EVENT and is disarmed when the event itself is run.

Allows the playing of sounds on specific channels that had been stopped by SOUND HOLD.

• A contains the sound channels to be released (see SOUND CHECK for the bit values this can take).

• AF, BC, DE, HL and IX are corrupt, and all other registers are preserved.

Immediately stops all sound output (on all channels).

• If a sound was being made, then Carry is true.
• If no sound was being made, then Carry is false.
• In all cases, A, BC, HL and other flags are corrupt, and all other registers are preserved.

When the sounds are restarted, they will begin from exactly the same place that they were stopped.

Restarts all sound output (on all channels).

• AF, BC, DE and IX are corrupt, and all other registers are preserved.

Sets up a volume envelope.

• A holds an envelope number (from 1 to 15).
• HL holds the address of a block of data for the envelope.

• If it was set up properly:
  • Carry is true.
  • HL holds the data block address + 16.
  • A and BC are corrupt.
• If the envelope number is invalid, then:
  • Carry is false
  • A, B and HL are preserved.
• In either case, DE and the other flags are corrupt, and all other registers are preserved.

All the rules of enevelopes in BASIC also apply; the block of the data for the envelope is set up as follows:

• byte 0 - number of sections in the envelope
• bytes 1 to 3 - first section of the envelope
• bytes 4 to 6 - second section of the envelope
• bytes 7 to 9 - third section of the envelope
• bytes 10 to 12 - fourth section of the envelope
• bytes 13 to 15 - fifth section of the envelope

Each section of the envelope has three bytes set out as follows:

• byte 0 - step count (with bit 7 set)
• byte 1 - step size
• byte 2 - pause time or if it is a hardware envelope, then each section takes the following form:
  • byte 0 - envelope shape (with bit 7 not set)
  • bytes 1 and 2 - envelope period

See also SOUND TONE ENVELOPE below.

Sets up a tone envelope.

• A holds an envelope number (from 1 to 15).
• HL holds the address of a block of data for the envelope.

• If it was set up properly:
  • Carry is true.
  • HL holds the data block address + 16.
  • A and BC are corrupt.
• If the envelope number is invalid, then Carry is false, and A, B and HL are preserved.
• In either case, DE and the other flags are corrupt, and all other registers are preserved.

All the rules of envelopes in BASIC also apply; the block of the data for the envelope is set up as follows:

• byte 0 - number of sections in the envelope
• bytes 1 to 3 - first section of the envelope
• bytes 4 to 6 - second section of the envelope
• bytes 7 to 9 - third section of the envelope
• bytes 10 to 12 - fourth section of the envelope
• bytes 13 to 15 - fifth section of the envelope

Each section of the envelope has three bytes set out as follows:

• byte 0 - step count
• byte 1 - step size
• byte 2 - pause time

See also SOUND AMPL ENVELOPE above.

Gets the address of the data block associated with a volume envelope.

• A contains an envelope number (from 1 to 15).

• If it was found, then:
  • Carry is true
  • HL holds the data block's address.
  • BC holds its length.
• If the envelope number is invalid, then Carry is false, HL is corrupt and BC is preserved.
• In both cases, A and the other flags are corrupt, and all other registers are preserved.

Gets the address of the data block associated with a tone envelope.

• A contains an envelope number (from 1 to 15).

• If it was found, then:
  • Carry is true.
  • HL holds the data block's address.
  • BC holds its length.
• If the envelope number is invalid, then Carry is false, HL is corrupt and BC is preserved.
• In both cases, A and the other flags are corrupt, and all others are preserved.

Clears all event queues and timer lists, with the exception of keyboard scanning and sound routines.

• B contains the foreground ROM select address (if any)
• DE contains the ROM entry address.
• C holds the ROM select address for a RAM foreground program.
• AF and HL are corrupt, and all other registers are preserved.

Finds and initialises all background ROMs.

• DE holds the address of the first usable byte of memory.
• HL holds the address of the last usable byte.

• DE holds the address of the new first usable byte of memory.
• HL holds the address of the new last usable byte.
• AF and BC are corrupt, and all other registers are preserved.

This routine looks at the ROM select addresses from 0 to 15 (1 to 7 for the 464) and calls the initialisation routine of any ROMs present; these routines may reserve memory by adjusting DE and HL before returning control to KL ROM WALK, and the ROM is then added to the list of command handling routines.

Finds and initialises a specific background ROM.

• C contains the ROM select address of the ROM.
• DE holds the address of the first usable byte of memory.
• HL holds the address of the last usable byte of memory.

• DE holds the address of the new first usable byte of memory.
• HL holds the address of the new last usable byte.
• AF and B are corrupt, and all other registers are preserved.

The ROM select address must be in the range of 0 to 15 (or 1 to 7 for the 464) although address 7 is tor the AMSDOS/CPM ROM if present. The ROM's initialisation routine is then called and some memory may be reserved for the ROM by adjusting the values of DE and HL before returning control to KL INlT BACK.

Logs on a new RSX to the firmware.

• BC contains the address of the RSX's command table.
• HL contains the address of four bytes exclusively for use by the firmware.

• DE is corrupt, and all other registers are preserved.

Searches an RSX, background ROM or foreground ROM, to find a command in its table.

• HL contains the address of the command name (in RAM only) which is being searched for.

• If the name was found in a RSX or background ROM then:
  • Carry is true
  • C contains the ROM select address.
  • HL contains the address of the routine
• If the command was not found, then:
  • Carry is false.
  • C and HL are corrupt.
• In either case, A, B and DE are corrupt, and all other registers are preserved.

The command names should be in upper case and the last character should have &80 added to it; the sequence of searching is RSXs, then ROMs with lower numbers before ROMs with higher numbers.

Sets up a frame flyback event block which will be acted on whenever a frame flyback occurs.

• HL contains the address of the event block in the central 32K of RAM.
• B contains the event class.
• C contains the ROM select address (if any).
• DE contains the address if the event routine.

• AF, DE and HL are corrupt, and all other registers are preserved.

Adds an existing but deleted frame flyback event block to the list of routines run when a frame flyback occurs.

• HL contains the address of the event block (in the central 32K of RAM).

• AF, DE and HL are corrupt, and all other registers are preserved.

Removes a frame flyback event block from the list of routines which are mn when a frame flyback occurs.

• HL contains the address of the event block.

• AF, DE and HL are corrupt, and all other registers are preserved.

Sets up a fast ticker event block which will be run whenever the 1/300th second ticker interrupt occurs.

• HL contains the address of the event block (in the central 32K of RAM).
• B contains the event class.
• C contains the ROM select address (if any).
• DE contains the address of the event routine.

• AF, DE and HL are corrupt, and all other registers are preserved.

Adds an existing but deleted fast ticker event block to the list of routines which are run when the 1/300th sec ticker interrupt occurs.

• HL contains the address of the event block.

• AF, DE and HL are corrupt, and all other registers are preserved.

Removes a fast ticker event block from the list of routines run when the 1/300th sec ticker interrupt occurs.

• HL contains the address of the event block.

• AF, DE and HL are corrupt, and all other registers are preserved.

Sets up a ticker event block which will be run whenever a 1/50th second ticker interrupt occurs.

• HL contains the address of the event block (in the central 32K of RAM).
• DE contains the initial value for the counter.
• BC holds the value that the counter will be given whenever it reaches zero.

• AF, BC, DE and HL are corrupt, and all the other registers are preserved.

Every 1/50th of a second all the tick blocks are looked at and their counter is decreased by 1; when the counter reaches zero, the event is 'kicked' and the counter is loaded with the value in BC; any tick block with a counter of 0 is ignored, and therefore if the value in BC is 0, the event will be kicked only once and ignored after that.

Removes a ticker event block from the list of routines that are run when a l/50th sec ticker interrupt occurs.

• HL contains the address of the event block.

• If the event block was found, then Carry is true, and DE holds the value remaining of the counter.
• If the event block was not found, then Carry is false, and DE is corrupt.
• In both cases, A, HL and the other flags are corrupt, and all other registers are preserved.

Initialises an event block.

• HL contains the address of the event block (in the central 32K of RAM).
• B contains the class of event.
• C contains the ROM select address.
• DE holds the address of the event routine.

• HL holds the address of the event block+7, and all other registers are preserved.

The event class is derived as follows:

• bit 0 -indicates a near address
• bits 1 to 4 - hold the synchronous event priority
• bit 5 - always zero
• bit 6 - if it is set, then it is an express event
• bit 7 - if it is set, then it is an asynchronous event.

• Asynchronous events do not have priorities.
• If it is an express asynchronous event, then its event routine is called from the interrupt path.
• If it is a normal asynchronous event, then its event routine is called just before returning from the interrupt.
• If it is an express synchronous event, then it has a higher priority than normal synchronous events, and it may not be disabled through use of KL EVENT DISABLE.
• If the near address bit is set, then the routine is located in the central 32K of RAM and is called directly, so saving time; no event may have a priority of zero.

Kicks an event block.

• HL contains the address of the event block.

• AF, BC, DE and HL are corrupt, and all other registers are preserved.

Clears the synchronous event queue.

• AF and HL are corrupt, and all other registers are preserved.

When using this routine, all events that are waiting to be dealt with are simply discarded.

Removes a synchronous event from the event queue.

• HL contains the address of the event block.

• AF, BC, DE and HL are corrupt, and all other registers are preserved.

Finds out if there is a synchronous event with a higher priority.

• If there is an event to be processed, then:
  • Carry is true.
  • HL contains the address of the event block.
  • A contains the priority of the previous event.
• If there is no event to be processed, then:
  • Carry is false.
  • A and HL are corrupt.
• In either case, DE is corrupt, and all other registers are preserved.

Runs a synchronous event routine.

• HL contains the address of the event block.

• AF, BC, DE and HL are corrupt, and all other registers are preserved.

See KL DONE SYNC below.

Finishes running a synchronous event routine.

• A contains the priority of the previous event.
• HL contains the address of the event block.

• AF, BC, DE and HL are corrupt, and all other registers are preserved.

When an event that is waiting to be processed has been found by KL NEXT SYNC, the event routine should be run by KL DO SYNC; after this KL DONE SYNC should be called so that the event counter can be decreased - if the counter is greater than zero then the event is placed back on the synchronous event queue.

Disables normal synchronous events.

• HL is corrupt, and all other registers are preserved.

Enables normal synchronous events.

• HL is corrupt, and all other registers are preserved.

Disarms a specific event and stops it from occurring.

• HL contains the address of the event block.

• AF is corrupt, and all other registers are preserved.

This routine should be used to disarm only asynchronous events; see also KL DEL SYNCHRONOUS.

Returns the time that has elapsed since the computer was switched on or reset (in 1/300ths of a second).

• DEHL contains the four byte count of the time elapsed.
• All other registers are preserved.

D holds the most signifilcant byte of the time elapsed, and L holds the least significant; the four byte count overflows after approximately l66 days have elapsed.

Sets the elapsed time (in 1/300ths of a second).

• DEHL contains the four byte count of the time to set.

• AF is corrupt, and all other registers are preserved.

Loads a program into RAM and then executes it.

• HL contains the address of the routine which is used to load the program.

Control is handed over to the program and so the routine is not returned from.

• All events, sounds and interrupts are turned off.
• The firmware indirections are returned to their default settings.
• The stack is reset.

The routine to run the program should be in the central block of memory, and should obey the following exit conditions:

• If the program was loaded successfully:
  • Carry is true
  • HL contains the prograrn entry point.
• If the program failed to load:
  • Carry is false
  • HL is corrupt.

In either case, A, BC, DE, IX, IY and the other flags are all corrupt. Should the program fail to load, control is returned to the previous foreground program.

Runs a foreground program.

• HL contains the entry point for the program.
• C contains the ROM selection number.

Control is handed over to the program and so the routine is not returned from.

Waits until a frame flyback occurs.

• All registers are preserved.

When the frame flyback occurs the screen is not being written to and so the screen can be manipulated during this period without any flickering or ghosting on the screen.

Sets the screen mode.

• A contains the required mode.

• AF is corrupt, and all other registers are preserved.

Although this routine changes the screen mode it does not inform the routines which write to the screen that the mode has been changed; therefore these routines will write to the screen as if the mode had not been changed; however as the hardware is now interpreting these signals differently, unusual effects may occur.

Sets the screen offset.

• A contains the screen base.
• HL contains the screen offset.

• AF is corrupt, and all other registers are preserved.

As with MC SET MODE, this routine changes the hardware setting without telling the routines that write to the screen; therefore these routines may cause unpredictable effects if called; the default screen base is &C0.

Sets all the PENs and the border to one colour, so making it seem as if the screen has been cleared.

• DE contains the address of the ink vector.

• AF is corrupt, and all other registers are preserved.

The ink vector takes the following form:

• byte 0 - holds the colour for the border
• byte 1 - holds the colour for all of the PENs.

The values for the colours are all given as hardware values.

Sets the colours of all the PENs and the border.

• DE contains the address of the ink vector.

• AF is corrupt, and all other registers are preserved.

The ink vector takes the following form:

• byte 0 - holds the colour for the border
• byte 1 - holds the colour for PEN 0
• …
• byte 16 - holds the colour for PEN 15

The values for the colours are all given as hardware values; the routine sets all sixteen PEN's.

Sets the MC WAIT PRINTER indirection to its original routine.

• AF, BC, DE and HL are corrupt, and all other registers are preserved.

Sends a character to the printer and detects if it is busy for too long (more than 0.4 seconds).

• A contains the character to be printed - only characters upto ASCII 127 can be printed.

• If the character was sent properly, then Carry is true.
• If the printer was busy, then Carry is false.
• In either case, A and the other flags are corrupt, and all other registers are preserved.

This routine uses the MC WAIT PRINTER indirection.

Tests to see if the printer is busy.

• If the printer is busy, then Carry is true.
• If the printer is not busy, then Carry is false.
• In both cases, the other flags are corrupt, and all other registers are preserved.

Sends a character to the printer, which must not be busy.

• A contains the character to be printed - only characters up to ASCII 127 can be printed.

• Carry is true.
• A and the other flags are corrupt, and all other registers are preserved.

Sends data to a sound chip register

• A contains the register number.
• C contains the data to be sent.

AF and BC are corrupt, and all other registers are preserved.

Restores the jumpblock to its default state.

• AF, BC, DE and HL are corrupt, and all other registers are preserved.

This routine does not affect the indirections jumpblock, but restores all entries in the main jumpblock.

Turns the shift and caps locks on and off.

• H contains the caps lock state.
• L contains the shift lock state.

• AF is corrupt, and all others are preserved.

In this routine, &00 means turned off, and &FF means turned on.

Empties the key buffer.

• AF is corrupt, and all other registers are preserved.

This routine also discards any current expansion string.

Gets the VDU and cursor state.

• A contains the VDU and cursor state.
• Flags are corrupt, and all other registers are preserved.

The value in the A register is bit significant, as follows:

• if bit 0 is set, then the cursor is disabled, otherwise it is enabled.
• if bit 1 is set, then the cursor is turned off, otherwise it is on.
• if bit 7 is set, then the VDU is enabled, otherwise it is disabled.

Sets the graphics VDU to its default mode.

• AF, BC, DE and HL are corrupt, and all other registers are preserved.

Sets the background to opaque, the first point of line is plotted, lines aren't dotted, and the write mode is force.

Sets the graphics background mode to either opaque or transparent.

• A holds zero if opaque mode is wanted, or holds &FF to select transparent mode.

• All registers are preserved.

Sets whether the first point of a line is plotted or not.

• A holds zero if the first point is not to be plotted, or holds &FF if it is to be plotted.

• All registers are preserved.

Sets how the points in a line are plotted - ie defines whether a line is dotted or not.

• A contains the line mask that will be used when drawing lines.

• All registers are preserved.

The first point in the line corresponds to bit 7 of the line mask and after bit 0 the mask repeats; if a bit is set then that point will be plotted; the mask is always applied from left to right, or from bottom to top.

Converts user coordinates into base coordinates.

• DE contains the user X coordinate.
• HL contains the user Y coordinate.

• DE holds the base X coordinate.
• HL holds the base Y coordinate.
• AF is corrupt, and all other registers are preserved.