When you have written some code that defines a new SuperBasic procedure or function, you must tell SuperBasic what it is called and where it lives. There is a vectored routine to do this and it is called BP_INIT (in QDOS) or SB_INIPR (in SMSQ). As an old hand at QDOS, I still use the QDOS definitions and names. As we are all using George Gwilt's GWASL assembler, and it uses the QDOS names, we shall continue to do so in this series.
Start up the QED editor (or your favourite) and type the following in :
start lea define,a1 ; Pointer to the definition table move.w BP_INIT,a2 ; The vector we need to use (= $110) jsr (a2) ; Call the vectored routine rts ; And return any errors back to SuperBasic
You will note that we only execute a small stub of code. This is simply because we are linking the new routines into SuperBasic and the actual code for the routines will be executed when a SuperBasic program uses one of the new routines. All will become clear.
The definition table required by BP_INIT has to be in the following format and it must start at an even address. A1.L points at the table when BP_INIT is called :
Table 7.1. Definition Block For BP_INIT
Size | Purpose |
---|---|
word | How many new procedures (A1 points here) |
Repeat for each procedure : | |
word | Offset to code start for this procedure |
byte | How many bytes in the procedure name |
bytes | The procedure name |
word | Zero = end of procedures |
word | How many new functions |
Repeat for each function : | |
word | Offset to code start for this function |
byte | How many bytes in the function name |
bytes | The function name |
word | Zero = end of functions & table |
As an example, our code file will introduce 1 new procedure and the definition table will be set up like the following which you should now type into the editor following on from the code that is already there :
define dc.w 1 ; 1 new procedure dc.w psi_cls-* dc.b 7,'PSI_CLS' dc.w 0 ; End of procedures dc.w 0 ; Number of functions dc.w 0 ; End of functions
Notice that the format of the procedure name is slightly different from normal QDOS string in that the size of the name is stored in a BYTE and not in a WORD.
Now then, there is a caveat - isn't there always? If the average length of the names of all the procedures, or functions, is greater than 7 then the simple word for the number of procedures or functions is changed to the value given by this calculation :
(total number of characters in proc names + number of proceduress + 7) / 8
Checking our table above we have a total of 7 characters in the procedure name and there is 1 new procedure. This gives an average of 7 characters per name (round up always !) so we are ok.
And that is it. On QL's of JM vintage and below, the machine must be NEW'd before you can use them. On JS and above, this need not be done.
Once a set of procedures and/or functions has been linked into SuperBasic, the definition block is no longer required. If your code requires the use of some workspace, then you can use the definition table. Just make sure that you don't use more bytes that there are available !
So, let's write our first procedure.