Atari ST series Technical Reference Manual page 38

XBIOS handler, which reads the command number on the
top of the stack, and directs program execution to the appro­
priate function. When the function terminates, the program
returns to user mode, and the results, if any, are returned in
register dO. When an XBIOS function call is completed, the
calling program has the responsibility to adjust the stack in
order to remove the command parameters and command
number.
The following program fragment demonstrates how to
change the value of color register 0 (the background color) to
yellow ($770) using BIOS command number 7:
move.w #$770, -(s p )
move.w # 0 , - (sp)
move.w # 7 , - (sp)
trap # 1 4
addq.l
# 6,sp
Calling the XBIOS routines from C is much simpler.
Most C compilers come with a library routine called xbios()
that stacks the parameters and executes the TRAP #14 in­
struction. For example, the sample call illustrated above
could be accomplished in C by the single statement:
xbios(7,0,0x770);
Since it's easier to remember a command name than a
command number, most C compilers include a header file
called OBSIND.H that defines macros for all of the XBIOS
functions. For example, the macro definition for XBIOS com­
mand 7 is:
#define Setcolor (a,b)
Therefore, after you #include OBSIND.H in your program,
call your sample function like this:
Setcolor(0,0x777);
As this format is more readable than the other, the ma­
cros will be used in the discussion of XBIOS routines and
sample programs. Just remember that in order to use XBIOS
functions in your C programs, #include OSBIND.H if you
use the macros, and link your program with the compiler li­
brary that contains the xbios() function.
30
CHAPTER 3
* push color value on stack
* push color register number on stack
* push XBIOS command number on
* stack
* call XBIOS handler
* P°P parameters (6 bytes) off stack
xbios(7,a,b)