CW CHAPTER 1

CHAPTER 1: INITIALIZING A GEM PROGRAM
--------------------------------------

[NOTE: Words enclosed in asterisks (i.e. *word*) should be 
read as italicized text. This text file is copyright 1993 by
Clayton Walnum. All rights reserved.]

In volume 1 of the *Assembly Language Workshop* we learned 
to write TOS programs--that is, programs that use the ST's 
operating system, yet don't contain any calls to GEM, the 
ST's graphical user interface. We delayed learning about GEM 
because a GEM program is much more complex than a straight 
TOS program. For one thing, a GEM program requires some 
tricky initialization, as well as some data structures we 
weren't prepared to discuss previously. However, now that we 
understand the basics of assembly language programming on 
the ST, we can press forward and learn how to write GEM 
programs.
	In this chapter, we'll see what initialization is 
required to get a GEM program up and running, including 
setting up our own stack, returning unused memory to the 
system, and defining the various data arrays that GEM 
requires in order to pass information between our programs 
and the operating system. We'll also see how to call AES 
functions.

--The Components of GEM--

We previously learned that TOS, the ST's operating system, 
is made up of several components: GEMDOS, BIOS, and the 
XBIOS. Likewise, GEM, the interface that isolates the user 
from the complexities of TOS, is divided into different 
components: the AES (Application Environment Services) and 
the VDI (Virtual Device Interface).
	The AES is the part of GEM that handles menus, dialog 
boxes, and windows. The VDI is the part of GEM that the AES 
uses to construct those menus, dialog boxes, and windows.  
In short, the VDI is a collection of graphics primitives 
(low-level graphics functions) that do things such as draw 
lines, rectangles, and circles. The VDI also provides 
functions for reading the mouse buttons and mouse position, 
among other things.

--The Program--

In this chapter, we'll see how to initialize a GEM 
application and how to call the AES. In the CHAP1 folder of 
your *ST Assembly Language Workshop* disk, you'll find two 
files. PROG1.S is the source code for this chapter's sample 
program, which is reprinted at the end of this chapter. 
PROG1.PRG is the assembled, runnable program file. If you 
would like to assemble the program yourself, please consult 
your assembler's manual or refer to this book's Appendix A.
	To run the program, double-click the PROG1.PRG file. 
When you do, an alert box will appear on the screen with the 
message "My first alert box!" To exit the program, click the 
alert box's button.

--Initializing GEM--

Considering the size of the source code, this chapter's 
program sure doesn't do much, does it? The fact is, most of 
the source code does nothing more than initialize the 
program. Only about half a dozen lines do anything that we 
can actually see on the screen.
	To initialize, run, and terminate a GEM application 
program, we must perform at least six main steps:

1) Set up a stack.
2) Calculate the size of our program and return unused 
memory back to the system.
3) Call *appl_init* to initialize the application.
4) Perform our main program code.
5) Call *appl_exit* to close down our application.
6) Call *pterm0* to return to the desktop (or the calling 
program).

	If we are going to use the VDI, there are also a couple 
of other steps that we must perform. However, because we are 
currently concerned only with a minimum GEM application--one 
that makes no calls to the VDI (except through the AES)--we 
can save those details until later.

--Setting Up Our Own Stack--

When we were writing simple TOS programs, we didn't worry 
too much about where our stack was located. We just let the 
system take care of it. However, because GEM allows several 
programs to be loaded at once (desk accessories), as well as 
allows one program to load another, we need a stack for each 
program. Obviously, we can't have one program using another 
program's stack. The result would almost certainly be a line 
of bombs on the screen.
	So, the first step in initiaizing a GEM program is to 
set up our own stack. In this chapter's sample program, the 
first two lines perform this important step.  They look like 
this:

move.l  a7,a5
lea     stack,sp

Here, the first line saves the contents of a7. (Remember, a7 
is the stack pointer; at the start of the program it 
contains an important address that we'll soon learn about.) 
In the second line, we load the address of our own stack 
into the stack pointer (a7), which is all we need to do to 
tell the system where our stack is located.
	But where is our stack? Take a look at the *bss* 
section of our program. You'll see these lines:

	ds.l    255
stack:  ds.l    1

These two lines reserve 256 longwords of storage (1K) for 
our stack. In most cases, a 1K stack is plenty large enough. 
(If your program uses a lot of recursion or other stack-
intensive operations, your stack may need to be larger.)
	But wait a minute! Why is our address label *stack* at 
the end of this area? Don't we normally put a label on the 
starting address of a block rather than at the ending 
address? We sure do. And in the case of a stack, the block's 
ending address is actually the stack's starting address. (Is 
your head spinning yet?) Remember: A stack stores values 
backward through memory, not forward. If we were to label 
the first byte of our stack area, the first time we came 
across an instruction like *move.w #1,-(sp)*, we'd end up 
tromping all over our program's other data. This can yield 
some hard-to-find bugs, believe me.

--Finding the Size of a Program--

When the ST runs a program, it allocates all of the 
available memory to that program. When we were running non-
GEM programs, that wasn't a problem. Then, we weren't 
concerned with memory considersations such loading resource 
files and dealing with desk accessories. With a GEM program, 
however, we must be concerned with these issues. For 
example, most GEM programs use menus and dialog boxes. The 
data that defines these graphical objects are usually 
contained in a resource file that must be loaded by the 
program at run time. If the ST gives our program all the 
memory in the system, and we don't bother to return what we 
don't need, where are we going to put our resources?
	The second step in initializing a GEM application, 
then, is to calculate the size of our program and return all 
unused memory to the heap (a strange word that's used to 
describe unallocated system memory). To calculate the size 
of a program, we need to know a little about how the ST 
loads a program into memory.

--The Transient Program Area--

A program is loaded into what is called a Transient Program 
Area (TPA). Upon a program's start-up, the TPA contains 
three main sections (see Figure 1.1): the base page, the 
program code (including its data), and the heap. The base 
page contains important information about the program, 
including the starting and ending addresses of the TPA, and 
the addresses and lengths of each of the program segments. 
The program section contains the program's text segment (the 
code), the data segment (initialized data), the BSS segment 
(uninitialized storage), and the stack. The heap, of course, 
contains all the system's remaining memory. It is this 
portion of the TPA that we must return to the system.

[INSERT FIGURE 1.1 HERE]

	In order to know how much memory we can return to the 
system, we need to calculate how much we need. The amount of 
memory we need is the memory that comprises the TPA minus 
the size of the heap. It would have been nice if the ST's 
designers had calculated this value for us. Unfortunately, 
we need to calculate it ourselves, by adding together the 
sizes of each section of the TPA.
	Look at the sample program. Right after we initialize 
our stack, you'll see these lines:

move.l  4(a5),a5
move.l  12(a5),d0
add.l   20(a5),d0
add.l   28(a5),d0
add.l   #$100,d0

These instructions calculate the size of our program. In the 
first line, we change A5 to the address of our TPA, which is 
also the address of the base page. This weird-looking 
instruction probably requires a little explanation.
	If you recall, we previously loaded the address of the 
old stack into A5, right before we changed A7 to point to 
our own stack. At this point, we actually have two stack 
pointers. A5 points to the old stack, and A7 points to the 
new stack. When we ran our program, the system placed the 
address of the TPA into the second word of the system stack, 
the stack now pointed to by A5. So, to load A5 with the 
address of the TPA, we need to load it with the second word 
of the old stack. To get to the second word of the stack, we 
use address register indirect addressing with displacement, 
using the stack pointer as the address register. Don't let 
it bother you that the source and destination registers are 
the same. In the first line above, all we're doing is moving 
the second word pointed to by A5 into A5. This makes A5 
point to our TPA.
	Now that A5 is pointing to the start of the base page, 
we can start to figure out the size of our program space. At 
an offset of 12 bytes from the start of the TPA, we'll find 
the length of our program's text segment. The second line 
above loads that value into D0. Now, we need to add the 
sizes of the data and BSS segments. Those values are found 
at offsets of 20 and 28, respectively. The third and fourth 
lines above add those values to D0. Finally, we need only 
add the size of the base page, which is 256 bytes or $100 in 
hexadecimal. The last line above takes care of that.

--Returning Unused Memory to the System--

With the size of our program area safely tucked away in D0, 
we're ready to call the GEMDOS function *Mshrink* (opcode 
#74), which returns the memory we don't need back to the 
system. We do this with the following lines:

move.l  d0,-(sp)
move.l  a5,-(sp)
clr.w   -(sp)
move.w  #MSHRINK,-(sp)
trap    #1
add.l   #12,sp

As you can see, the *Mshrink* function requires three 
parameters on the stack: the size of our program area, the 
address of the TPA, and a dummy word. After this system 
call, the ST will again have access to any unused memory.

--Getting Ready for the AES--

In our sample program, we call the AES in order to display 
an alert box. Before we can call the AES, though, we need to 
do some further initialization. Specifically, we must supply 
the AES with seven arrays: the global array, the control 
array, the int_in array, the int_out array, the addr_in 
array, the addr_out array, and the AES parameter block. 
Yikes!

--The Global Array--

The global array, which comprises nine elements, contains 
important information required by the AES library. The first 
three elements are words (two bytes). The rest are longwords 
(four bytes). How do we initialize the global array? We need 
do nothing more than provide space for it in our BSS 
segment. Look the the sample program's BSS segment. At the 
top of this area, you'll see the label *global*, which marks 
the beginning of the global array. After that label, you'll 
see each of the nine elements defined, three words and six 
longwords. Note that, for documentation's sake at least, 
each of the array's elements has an appropriate label.
	After we define the global array, we can forget it. The 
AES will deal with it as it sees fit, all behind our back, 
as it were.

--The Control Array--

The control array comprises five two-byte (word) elements. 
We must use the control array to pass information to AES 
when we call its functions, rather than using the stack as 
we do when calling TOS functions. In turn, the AES uses the 
control array to pass information back to us, after a 
particular function has executed.
	We define the control array similarly to how we defined 
the global array, by creating space for it in our BSS 
segment. If you look in this chapter's program listing, 
you'll see the control array defined right after the global 
array. The label *control* marks the beginning of the array, 
while the labels *control0* through *control4* hold the 
adresses of each element of the array. By using these 
labels, we can easily access any of the five elements.

--The Input and Output Arrays--

The int_in, int_out, addr_in, and addr_out arrays are used 
in conjunction with the control array to pass information 
from our program to the AES and from the AES back to our 
program. We use the "in" arrays to send information to the 
AES. The AES uses the "out" arrays to return function 
results to us.
	The number of elements in the arrays vary, depending on 
the AES functions we plan to call. This is because different 
functions have different numbers of parameters. In our 
sample program, right after the control array, we've 
reserved only one element for each of the arrays. That's all 
we need for the function we'll be calling.
	Because the int_in and int_out arrays are for storing 
integers, their elements need to be word sized. The addr_in 
and addr_out arrays, however, hold addresses, so their 
elements must be longwords.

--The AES Parameter Block--

Of course, before the AES can use any of the arrays we've 
set up for it, it must know where they are. We communicate 
this information with the AES parameter block (APB). The APB 
is nothing more than a table of addresses. Specifically, it 
contains the addresses of the control, global, int_in, 
int_out, addr_in, and addr_out arrays, in that order. You'll 
find our sample program's APB in the data segment, above the 
global array.

--Calling an AES Function--

Now that we know all about the AES's arrays, we're ready to 
learn to call the AES. To call the AES, we must follow the 
steps below:

1) Place the appropriate values into the control array.
2) If required, place the appropriate parameters into the 
int_in and addr_in arrays.
3) Load the address of the APB into D1.
4) Load the AES ID into D0.
5) Perform a *trap #2*.

	Let's take a look at the sample program to see how all 
this works. Look at the section of code following the 
*MShrink* call. You'll see the following instructions:

clr.l   ap_ptree
clr.l   ap_1resv
clr.l   ap_2resv
clr.l   ap_3resv
clr.l   ap_4resv

Here, we're clearing five elements of the global array, as 
is suggested by Atari's OS documentation. If we didn't clear 
these fields, probably nothing bad would happen to our 
program. But Atari says to do it. That's good enough for me.
	After initializing the global array, we make our first 
AES function call with the following code:

move.w  #APPL_INIT,control0
clr.w   control1
move.w  #1,control2
clr.w   control3
clr.w   control4
jsr     aes
cmpi    #$FFFF,ap_id
beq     end

This is a call to the AES function *appl_init* (opcode #10), 
which initializes a new GEM application. Every GEM program 
must call this function before making any other GEM calls. 
The *appl_init* function notifies the OS of our program, so 
that it can set up the required resources. This call also 
stores important information into some elements of the 
global array, the most important of which is our 
application's ID.
	In the first line, we place the *appl_init* opcode into 
*control0*. The opcode of the AES function we're calling 
always goes into this array element. Next, we place a zero 
in *control1*, which tells the AES that we are passing no 
values in the int_in array. Then, we place a 1 in 
*control2*, telling the AES that we expect one value (the 
application's ID) to be returned in the int_out array. 
Because we are passing no addresses in the addr_in array, 
and because we expect no addresses returned to us in the 
addr_out array, we place zeros in *control3* and *control4*.
	After the appropriate arrays are initialized, a call to 
the AES is always done the same way, so in our sample 
program, we've placed the necessary code into a subroutine. 
The instruction *jsr aes* above calls this subroutine, which 
is located at the end of the program, right above our data 
segment. The subroutine looks like this:

movem.l a0-a7/d0-d7,-(sp)
move.l  #apb,d1
move.l  #AES_OPCODE,d0
trap    #2
movem.l (sp)+,a0-a7/d0-d7
rts

First, we save the contents of the registers. Then we move the
address of our APB into D1 and the AES opcode into D0. Finally,
we call the AES with a *trap #2*. The AES then uses the APB to
find the addresses of the arrays it needs, and it performs the
instructions in finds in those arrays.

--Displaying an Alert Box--

After we've called *appl_init*, we're all ready to take full 
advantage of some of the great stuff that GEM has to offer. 
(We can't yet call the VDI directly, however; further 
initialization is required for that.) One of the easiest 
things we can do with GEM is call up an alert box. And in 
the next section of code, we do just that. But before we 
look at the code, let's talk a bit about alert boxes.
	As you probably know, GEM supports a special input 
window called a dialog box. Dialog boxes come in many, many 
types, most of which are designed by the application's 
programmer. The AES, however, supplies a couple of ready-
made dialog boxes that we can use without having to create 
it in a resource file. The simplest of these ready-made 
dialog boxes is the alert box.
	An alert box may contain several elements: an icon, up 
to five lines of text (maximum of 32 characters per line), 
and up to three labeled buttons. One of the three buttons 
may be a default button, which is automatically chosen when 
the user presses Return. The default button always has a 
darker border than the other buttons.
	When we tell the AES to construct an alert box for us, 
we must tell it what icon and text to display. We must also 
tell it how many buttons we want in the box, and which of 
the buttons, if any, is to be the default. All of this 
information is transferred to the AES via the control, 
int_in, and int_out arrays.
	Take a look at the sample program. Right below our call 
to *appl_init*, you'll see the following code:

move.w  #FORM_ALERT,control0
move.w  #1,control1
move.w  #1,control2
move.w  #1,control3
move.w  #0,control4
move.w  #1,int_in
move.l  #string,addr_in
jsr     aes

This is the code that creates and displays the alert box. In 
the first line, we move the opcode for the AES function, 
*form_alert* (opcode #52), into *control1*. In the next four 
lines, we tell the AES that the int_in, int_out, and addr_in 
arrays are each one element long, and that the addr_out 
array is zero elements long. We then place a 1 in the first 
element of int_in, which tells the AES that we want the 
first button to be the default button. This value can be any 
of the following:

0 -- no default button
1 -- first button is the default
2 -- second button is the default
3 -- third button is the default

After setting the default button, we load the address of a 
string into the first element of addr_in. What string, you 
ask? The string that tells *form_alert* what icon, text, and 
buttons to display. The string is made up of three parts, 
each part surrounded by square brackets:

[ICON #][BOX TEXT][BUTTON TEXT]

ICON # tells *form_alert* which icon to display. BOX TEXT is 
the text that we want to appear in the alert box. Each line 
of text must be separated by the OR character (|), like 
this:

[LINE1|LINE2|LINE3|LINE 4|LINE5]

BUTTON TEXT tells *form_alert* what text to put into the 
buttons. Again, if there is more than one button, the text 
for each must be separated by the OR character, like this:

[BUTTON1|BUTTON2|BUTTON3]

So, a string used to create a typical alert box might look 
something like this:

[1][Your File has been changed.|Do you want to save 
it?][YES|NO]

You can find the string used in the sample program to create 
the alert box, in the data section of the program listing.
	Getting back to our program, after we load the address 
of the alert-box text string into addr_in, we call our *aes* 
subroutine, and the alert box is displayed on the screen. 
The user can exit the alert box onLy by clicking one of its 
buttons. The number of the button the user clicks is 
returned in the first element of the int_out array. The 
alert box in our sample program has only one button, so we 
don't need to use the information stored in the int_out 
array, but if we had had more than one choice, we would have 
used the value from int_out to decide what to do next.

--Shutting Down a GEM Application--

The complement of the *appl_init* function is *appl_exit* 
(opcode #19). Before returning to the desktop from a GEM 
program, we must be sure to call this function, because it 
tells the AES that the program is terminating and that the 
AES should return to the system whatever resources were 
allocated. We call the *appl_exit* function like this:

move.w  #APPL_EXIT,control0
move.w  #0,control1
move.w  #1,control2
move.w  #0,control3
move.w  #0,control4
jsr     aes

After a call to *appl_exit*, the first element of int_out 
will contain a zero if an error occurred or a number greater 
than zero if no error occurred.
	Once we've terminated the GEM program, all we must do 
to end the program is return to the desktop. We do this just 
as we did before, with a call to *Pterm0*.

--Conclusion--

Now you know why we saved GEM programming for volume 2 of 
the workshop. Just doing something simple like bringing an 
alert box up on the screen takes many lines of code and 
requires much knowledge of the way GEM works. Take your time 
with this chapter and be sure you understand it all. It's 
the basis for all to follow.

--Summary--

* GEM comprises two main components: the AES and the VDI.

* The AES handles menus, dialog, boxes, and windows. The AES 
calls upon the VDI, which contains a library of graphics 
primitives, as well as functions for handling the mouse, 
among other things.

* To initialize, run, and terminate a GEM application, we 
must perform six main steps: Set up a stack, return unused 
memory to the system, call *appl_init*, perform the main 
program code, call *appl_exit*, and call *Pterm0*.

* We set up a stack by allocating space for it in our BSS, 
and then setting the stack pointer to that space.

* To return unused memory to the system, we must first 
calculate the size of our program. We use the information 
found in the Trasient Program Area (TPA) to do this.

* The address of the TPA can be found in the second word of 
the system's stack upon program startup.

* The GEMDOS function #74, *Mshrink*, returns unused memory 
to the system.

* In order to function properly, the AES requires seven 
arrays to receive information from and to send information 
to our program. They are the global array, the control 
array, the int_in array, the int_out array, the addr_in 
array, the addr_out array, and the AES parameter block.

* To call an AES routine, we must perform five main steps: 
Place the appropriate values into the control array, place 
the appropriate parameters into the int_in and addr_in 
arrays, load the address of the APB into D1, load the AES ID 
into D0, and perform a *trap #2*.

* The AES function #10, *appl_init* initializes a new GEM 
application.

* An alert box is one of the ready-made dialog boxes that 
GEM provides.

* The AES function #52, *form_alert*, creates an alert box 
on the screen.

* The AES function #19, *appl_exit*, terminates a GEM 
application, returning all its resources to the system.

CW_PROG1.s (Source of the chapter)

Back to Assembly_language_tutorials