Wouldn't it be nice to do this instead of the above :

PSI_CLS #1, RED, GREEN, BLACK

In SuperBasic this would be done either by :

DEFine FuNction RED
    return 2
END DEFine RED

DEFine FuNction GREEN
    return 4
END DEFine GREEN

DEFine FuNction BLACK
    return 0
END DEFine BLACK

OK, I know it could be done like this :

RED = 2
GREEN = 4
BLACK = 0

but we are dealing with machine code functions and this is more illustrative of what we are about to do. (So there !)

We shall now extend our original example so that we can specify colour values by name - this is much more friendly in my opinion.

The following two lines in the definition block need to be removed :

        dc.w    0               ; Number of functions
        dc.w    0               ; End of functions

And replaced by the following :

        dc.w    8               ; There are 8 functions

        dc.w    black-*         ; First function
        dc.b    5,'BLACK'

        dc.w    blue-*          ; Second function
        dc.b    4,'BLUE'

        dc.w    red-*           ; Third function
        dc.b    3,'RED'

        dc.w    cyan-*          ; Fourth function
        dc.b    4,'CYAN'

        dc.w    green-*         ; Fifth function
        dc.b    5,'GREEN'

        dc.w    magenta-*       ; Sixth function
        dc.b    7,'MAGENTA'

        dc.w    yellow-*        ; Seventh function
        dc.b    6,'YELLOW'

        dc.w    white-*         ; Eighth function
        dc.b    5,'WHITE'

        dc.w    0               ; End of functions

The following is the code for the new functions, type it into the file after the end of the 'channel_id' subroutine :

black       moveq   #0,d7
            bra.s   return_d7

blue        moveq   #1,d7
            bra.s   return_d7

red         moveq   #2,d7
            bra.s   return_d7

magenta     moveq   #3,d7
            bra.s   return_d7

green       moveq   #4,d7
            bra.s   return_d7

cyan        moveq   #5,d7
            bra.s   return_d7

yellow      moveq   #6,d7
            bra.s   return_d7

white       moveq   #7,d7

*------------------------------------------------------------------------------
* This routine returns the word value in d7 to SuperBasic as the result of the
* function we are running. It requires two bytes on the top of the maths stack
* and because there were no parameters supplied to any of the functions, I can
* safely ask QDOS for these two bytes.
*------------------------------------------------------------------------------
return_d7   move.l  bv_rip(a6),a1   ; Because we had no parameters passed
            moveq   #2,d1           ; Size of stack space required
            move.w  bv_chrix,a2     ; Routine to allocate maths stack space
            jsr     (a2)            ; Go get some space NO ERRORS OCCUR !

*------------------------------------------------------------------------------
* The maths stack has been extended by two bytes BUT it may have moved around in
* memory so we need to get the stack pointer into A1 again.
*------------------------------------------------------------------------------
            move.l  bv_rip(a6),a1   ; New top of stack
            subq.l  #2,a1           ; Make space for our integer result
            move.w  d7,0(a6,a1.l)   ; Stack the result
            move.w  #3,d4           ; Signal word result on stack
            move.l  a1,bv_rip(a6)   ; Store new top of stack for SuperBasic
            clr.l   d0              ; No errors
            rts                     ; Return result to SuperBasic

That is the end of the code. Assemble it, debug it and test it using the following :

PAPER GREEN
STRIP RED
INK BLACK
CLS
PRINT "Hello world"

or, if you like :

PSI_CLS GREEN, RED, BLACK
PRINT "Hello world"

In the procedure, PSI_CLS, we obtained some parameters for the various colours and channels. I shall now discuss how this is done in much more detail.