Use the Spectrum 128 style menu below to navigate to the various sections detailing the Extended BASIC mechanism.

128 Extended BASIC Main Menu Title
Method of Operation
Extension Framework
Example Commands

Extension Framework

To simplify the process of the creating extensions to 128 BASIC, I've produced a framework that includes all the major components needed and therefore allows focus to be concentrated on the actual new commands themselves. The framework includes the installation mechanism, handles the invoking of the extended BASIC parser, performs keyword identification, parameter validation, conversion of keywords to upper case, and inserting of leading and trailing spaces as required. The framework contains a table where all new commands are listed, along with a definition of the parameters each expects, and the address of the handler routine to be called at run time (or syntax checking time as defined by the parameter definition bytes). The parameter definition list uses a similar 'class' mechanism to that employed in both ROM 0 and ROM 1, and reproduces classes 00 to 0A. Two of the classes have been given new purposes since their old roles were of limited use for new commands. The new class 04 allows a detailed specification of the type of a variable expected. The new class 07 allows a numeric parameter to be specified, but if absent then a specified default value is used. Further classes can be added as required, up to code $1F.

Each entry in the command definition table consists of the following:

The table is terminated with a $00 character.

The command classes supported are:

Classes 01, 04, 06, 08, 09, 0A must be followed by another parameter class (class 00 if the end of the parameter requirements has been reached). Classes 04 and 07 expect class specific additional bytes to follow.

New command keywords can be up to 255 characters long and can include embedded spaces. Symbols can form part of the command but to conform to the Sinclair BASIC standard, they should only be used as the final character of a command. The symbol '&' should not be used since the parser accepts these as a prefix to any new command so that it works as an immediate execution command. A '#' should only be used to denote the use of a stream, a '$' to denote the use of a string, and '!' to denote the use of the RAM disk. Symbols can either be embedded at the end of command name, and hence must be typed exactly as defined, i.e. no surplus spaces, or can be defined as a required parameter 'separator' following the keyword, in which can spaces can be inserted before it and will be ignored. Tokens can form part of the keyword also, thereby saving space within BASIC programs, e.g. the command TO UPPER could make use of the token TO for the initial word. A keyword should not include graphic characters, UDG characters, numbers, arithmetic operators or control codes. When the first character is a token, the standard BASIC command handler (either in ROM 1 or ROM 0) will be called first to process the command before handling is redirected to the extended BASIC parser. The command handler routines for the 128 BASIC commands based on ERASE, CAT and FORMAT explicitly check the characters that follow the token keyword and so if these fail syntax checking then these keywords used as the base for new commands.

Keywords that are a subset of other keywords, e.g. TRIM is a subset of TRIM LEFT, should be listed in the keyword table in order of longest string first. This ensures that a premature match on the shorter keyword does not occur.

Upon entry to a command handler, the next character to be interpreted is the byte after the command keyword characters and the A register will hold the character that caused the syntax error.

A variety of support functions are present within the Extended BASIC Framework and these can be utilised by command handlers. These include routines to abstract the paging of ROM and RAM banks and therefore aid in simplifying the command handler code.

The Extended BASIC Framework attempts to support all versions of the Spectrum 128 and Spectrum +2 by locating the address of the ROM routines the parser requires using the vector table located at $0100 within ROM 0. Offsets are then used to locate a couple of routines. The jump address from vector entry at $0112 is retrieved and $0009 subtracted from it to obtain the address of the Statement Return routine. This is the version of the routine which includes the check of the BREAK key. The jump address from vector entry at $0115 is retrieved and $0007 subtracted from it to obtain the address of the Check End routine. New commands that require explicit access to routines within ROM 0, must detect which version of the ROM is present and adjust its calls appropriately. To aid in this, a ROM version identification routine is included within the framework, along with a jump table mechanism to handle the differing ROM routine locations. The Spectrum model is identified by testing the byte at $2784 in ROM 0 since this holds a unique value for each the different versions of Spectrum 128 and Spectrum +2 that were produced. The following models of 128K Spectrum are supported:

The error trap code is located at $FE00 within RAM bank 0 and includes an area of unused space sandwiched between the intercept code for errors $00 to $1C, and the intercept code for error $FF. This space is available for use by any routines that the command handlers (or extensions to the parser) would like to have available within the conventional memory map. The framework occupies about 1.5K of RAM, approximately 550 bytes of which resides in conventional RAM (banks 5 and 0) whilst the majority resides within the last 8K of RAM bank 6. These leaves 6.5K of space free in RAM bank 6 for new commands.

Extended BASIC Framework Memory Map

Click here to download the Extended BASIC Framework source code, which contains a collection of example commands.

Implementing on the Spectrum +2A/B and +3

The principles of the extending 128 BASIC should also work on the various models of Spectrum +2A/B and Spectrum +3, but the Editor ROM routines are significantly re-arranged compared to those in the Spectrum 128 and Spectrum +2 models, appearing in ROM 1 instead of ROM 0 and with 48 BASIC appearing in ROM 3 instead of ROM 1. For this reason, there has been no attempt to make the framework support the Spectrum +2A/B and Spectrum +3 models.

The Extended BASIC Framework uses three routines within ROM 0 of the Spectrum 128, and equivalents appear in the Spectrum +3 ROM 1 as shown in the following table:

ROM Routine Spectrum +3
(UK, Version 4.0)
Spectrum +2A/+2B/+3
(UK, Version 4.1)
Spectrum +3
Statement Return $1031 $104D $1059
Check End $10B1 $10CD $10D9
Check Break Key $2AF9 $2C6B $2CA7

In addition to changing the references to these routines, the paging routines that switch between the Spectrum 128 ROM 0 and ROM 1 would also need to be changed to switch between the Spectrum +3 ROM 1 and ROM 3.