2. Linking To SuperBasic

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

SizePurpose
wordHow many new procedures (A1 points here)
Repeat for each procedure : 
wordOffset to code start for this procedure
byteHow many bytes in the procedure name
bytesThe procedure name
wordZero = end of procedures
wordHow many new functions
Repeat for each function : 
wordOffset to code start for this function
byteHow many bytes in the function name
bytesThe function name
wordZero = 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.