BASWORD - BASIC keyword manager for the Sharp PC-1500/A and the TRS-80 PC-2

Description:

BASWORD BASIC keyword manager for the Sharp PC-1500/A and the TRS-80 PC-2

Notes: This code is expected to run on the Sharp PC-1500/A and the TRS-80 PC-2. This version is still in pre-alpha release. It is not fully mature and bugs may be present.

Disclaimer:You use this software at your own risk! I am not responsible for any damage, data loss or corruption occurring when using this software. C.G.

One interesting property of the PC-1500/A/PC-2 is the possibility to create new BASIC instructions. Such new instructions consist of a Machine Language code, called a 'routine', and a BASIC keyword. This keyword is composed by a name (for example PRINT), a code used by the interpreter (&F097) and a routine address where the interpreter is branching when executing the instruction.

Because many new instructions were developed in the 'golden years' of the PC-1500 (see e.g. Basic1501 originally published in "Sharpentier" magazine), it became difficult to have the extension you really needed. So I started the development of BASWORD, a BASIC keyword manager. C.G.

In the following document, I use the following terms:
  . BASIC RAM stands for the "normal" BASIC program area.
  . RESERVE memory stands for the RESERVE area where the key F1..F6 are defined.
  . User ML code stands for an area reserved for your own ML code (i.e. space reserved by a NEW &nnnn).
  . User's keywords table and user's keyword table stand for the new custom BASIC instructions created by the user and the dedicated table where these keywords are stored. BASWORD performs the management of this table.

All the examples and addresses are assumed for a CE-161/CE-163 module.

For the different modules, base is mapped as follow:
  &0000 : CE-161/CE-163 (16K module)
  &2000 : CE-159 (8K module)
  &3800 : CE-155 (8K module)
  &4000 : Standard RAM (with or without CE-151 4K module)

And this is the memory organization with BASWORD loaded (CE-161/CE-163):
  base + &0008 .. &00C4 : RESERVE memory
  base + &00C5 .. &067F : BASWORD code [SHOULD NOT BE OVERWRITTEN]
  base + &0680 .. &07FF : Free for user's routines
  base + &0800 .. &0860 : Start-up BASWORD table
  base + &0861 .. &47FF : BASIC RAM for PC-1500/PC-2
  base + &0861 .. &57FF : BASIC RAM for PC-1500A

To be installed, BASWORD requires at least a CE-151 (4K module) for the PC-1500 or PC-2. But it may be installed without memory extension on a PC-1500A.

Please refer to the README in this zip archive for further information about installation and relocation.
Note that images for all extension modules (CE-151, CE-155, CE-159, CE-161) are provided into the zip archive.

Use it

BASWORD requires a PC-1500 with a new ROM version to work. To know if your PC-1500 is compatible, do:
PEEK &E2B9

If you get 56, BASWORD will run on your PC-1500/A/PC-2, else it will be not possible to use it. If you really need it, contact me to get a special ROM.

The keyboard driver

If your PC-1500 is compatible (new ROM), you may install an image with the keyboard driver. You will get:
  . Auto-repetition of the keys
  . Shift Ins will commute the auto-insert mode ON or OFF
  . CA and ON/BRK will clear the auto-insert mode
  . OFF will power-off without reinitializing the keyword and keyboard vectors
  . ENTER will compile the new keywords. These keywords may be also abbreviated with a ! character: B! will compile BASWORD
  . DEF <| (left-arrow) will jump to the begin of the line
  . DEF |> (right-arrow) will jump to the end of the line
  . DEF CL will clear from the cursor position to the end of the line
  . DEF MODE will move to the next :
  . DEF ( will give { (CHR$ &7B)
  . DEF ) will give } (CHR$ &7D)
  . DEF * will give the back pattern (CHR$ &7F)
  . DEF + will give ~ (CHR$ &7E)
  . DEF - will give _ (CHR$ &5F)
  . DEF / will give | (CHR$ &7C)
  . DEF . will give the Yen (CHR$ &5C)

The BASWORD instruction

Only the BASWORD instruction is initially added. But it is enough to manage the additional ones.
BASWORD will create, remove, list the other instructions, and will also help moving the keyword table to given location.

BASWORD =tt
will move the user's keyword table to the location &tt00, with the constraint to be aligned on a 2Kbytes boundary. So, valid values will be &08, &10, &18, &20, &28, &30, &38...

BASWORD +"n....";"ccaaaap"
will create a new instruction named n.... (up to 8 characters, beginning by an uppercase letter, with the code &F0cc, and starting at the address &aaaa. The p parameter defines the type of the instruction as follows:
  p = N, the instruction may be executed in RUN mode or while a program is running like PRINT, POKE or SIN
  p = P, the instruction may be programmed only executed while a program is running like FOR, DATA or AREAD
  p = U, the instruction may be only executed in RUN or PRO mode, but while a program is running like NEW, LIST or CONT
When BASWORD + returns, the new instruction will be found, compiled, decoded and executed.

BASWORD -"n...."
will remove the instruction n.... if it exists. When BASWORD - returns the instruction will no more be compiled or decoded, and if present in a program or in RESERVE memory, it will decoded as a ~. Trying to execute a removed instruction will produce an ERROR 27.

BASWORD
will display all the instructions in the user keyword table. Use OFF or ON/BREAK to exit, and the down-arrow to display the next instruction in the table. After the last instruction, BASWORD goes back to BASIC.

BASWORD "n...."
will display all the instructions starting at the given instruction if it exists. Use OFF or ON/BREAK to exit, and the down-arrow to display the next instruction in the table. After the last instruction, BASWORD goes back to BASIC.

BASWORD "/p"
will display the instructions of the table given by the /p parameter as follows:
  /U is the User's keyword table (BASWORD, ...)
  /M is the Main BASIC table (AREAD, PRINT, ...)
  /P is the Printer table (LPRINT, ROTATE, ...)
  /C is the Cassette interface table (CSAVE, CLOAD, ...)
Use OFF or ON/BREAK to exit, and the down-arrow to display the next instruction in the table. After the last instruction, BASWORD go back to BASIC.

A first example - ERN and ERL

For this example, we assume that the image BASWORD-00C5 is loaded.
Since in this example the user's keyword table will grow, we first do:
NEW &900
This reserves more space for the user's keyword table.

-------------------------- IMPORTANT NOTE ---------------------------
Since BASWORD is developed to handle the creation of new instructions,
IT IS HIGHLY RECOMMENDED TO RESERVE SOME SPACE after the end of the
user's keyword table to allow it to grow.
If the user's keyword table ends in &x860, please, before starting to
create new keywords, do at least a:
NEW &x900

This will give 160 bytes free for the new keywords. Remember that a
keyword need 5 bytes + its length. So BASWORD requires 12 bytes for
registering.
----------------------------------------------------------------------

Do the following:
POKE &680,&A5,&78,&9B,&BA,&D9,&E4
POKE &686,&F4,&78,&B4,&BA,&DA,&6C
BASWORD +"ERN";"5E0680N"
BASWORD +"ERL";"5F0686N"

Now the new functions ERN and ERL are available. ERN will return the last error code, and ERL the line number where the error has occurred. The ERN and ERL instructions are taken from 'Basic1501' (published in 'Sharpentier' #6).

Do:
1/0
You will see ERROR 38
ERN
gives 38.

In PRO mode, do:
NEW
10 ON ERROR GOTO 100
20 GOTO 1234567890
30 END
100 BEEP 1: PRINT "Error ";ERN ;" line "; ERL :END

and now in RUN mode do:
RUN
you hear a beep and see: Error 19 line 20

As explained later, the new keywords may be abbreviated with !, so E! will be ERN in our example.

A second example - BUILD

For this example, it is assumed that the image BASWORD-00C5 is loaded.
Since in this example the user's keyword table will growth, we do first:
NEW &900
This will reserve more space for the user's keyword table.

Do:
POKE &068C,&FD,&98,&BE,&00,&C5,&FD,&98,&CC,&90,&CA,&00,&BE,&D0,&2B,&DC,&45
POKE &069C,&B7,&7C,&89,&02,&B5,&22,&51,&88,&0A,&56,&B5,&0D,&51,&BE,&06,&67
POKE &06AC,&BE,&F9,&57,&BE,&CF,&27,&03,&09,&08,&00,&CC,&00,&CA,&90,&FD,&1A
POKE &06BC,&E2,&FD,&1A,&FD,&1A,&68,&D0,&54,&E0
BASWORD +"BUILD";"C8068CN"

And now do:
BUILD "99PR.|Hello!|:B.1:E."

Go in PRO mode and do:
LIST 99
You see: 99 PRINT "Hello!":BEEP 1:END
The keyword of the user's table are also encoded and may be abbreviated by a !. The | character will be replaced by a " to let you enter double-quoted strings.
Of course BUILD is programmable. There is only one restriction. The new line generated by BUILD should have a higher number than the line where BUILD is executed. If an error occurs while BUILD is working, the ERROR 208 will be raised.

Do:
NEW
10 INPUT "Your function(X) ";F$
20 BUILD "100 Y="+F$+":RET."
30 FOR X=1TO 10
40 GOSUB 100
50 PRINT "F(";X;")=";Y
60 NEXT X
70 END

Then go back in mode RUN, and do
RUN
See: Your function(X)
X^2
And now
F( 1)= 1
F( 2)= 4
. . .
F( 10)= 100

If you look at line 100, you will see: 100 Y=X^2:RETURN

Copyright and license

BASWORD is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License version 2 as published by the Free Software Foundation. Note that I am not granting permission to redistribute or modify BASWORD under the terms of any later version of the General Public License.

This program is distributed in the hope that it will be useful (or at least amusing), but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program (in the file "COPYING"); if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

Return to main page