Getting Started with <B>Alice</B>

# Getting Started with Alice

In this chapter, we give a quick introduction to programming with Alice. We will cover the most commonly used commands and the general flow of an Alice session.

## Invoking Alice

First boot DOS according to the procedure given in the DOS manual. This usually involves inserting the DOS boot floppy, booting, and typing in a user name. To run Alice, you must have 320K of RAM, and more is better.

Next, if your PC has a colour/graphics display card, you may want to tell the system what kind of monitor you have. Enter the command

>     mode co80

if you have a colour monitor and

>     mode bw80

if you have a monochrome monitor, or if you don't want to use Alice's colour facilities. You should NOT enter these commands if your PC has a monochrome display adapter. As a matter of fact, a MODE command is often unnecessary, since the type of monitor you have is normally indicated by the dip switches in your computer. However, there are times when the MODE commands should be used.

Next insert the Alice disk in your main floppy drive. (Appendix D explains how to transfer Alice from floppy disk to hard disk; for now, however, we'll assume you're working from the floppy.) If you have two drives and they are both active, you can keep DOS in one drive and Alice in the other. Then type

>     alice

## The Starting Menu

Once Alice has performed its initializations, it will display the Starting Menu:

>     Edit a New Program
>     Load in an Existing Pascal Program
>     Quit the Alice System
>     Experiment in Immediate Mode
>     What is Alice All About?
>     How to Obtain this Program

To choose one of these options, you use the standard menu selection techniques described in the previous chapter.

The selection `Quit the Alice System` immediately quits Alice. This is for people who got into Alice accidentally somehow.

The `What is Alice All About?` selection will lead the user through a short introduction to the use of Alice.

The `How to Obtain this Program` selection is for people who are trying out someone else's copy of Alice. It tells how you can purchase your own Alice package.

The `Experiment in Immediate Mode` selection allows the user to ``play'' with Alice without actually writing a program. This feature is mainly for students using our textbook.

The other two options on the Starting Menu the ones most commonly used. We'll begin by looking at the selection `Load in an Existing Pascal Program` .

### File Name Menus

If you choose the `Load in an Existing Pascal Program` selection, Alice will show you a File Name Menu. This gives the names of all the files and sub-directories in your current directory. Directories are indicated by `<dir>` immediately following the name. The special entry `.. <dir>` refers to the parent of the current directory (i.e. the directory that contains the current directory).

If you are at the root of your file system, there will be no `.. <dir>` entry. Instead, you will see entries for the various storage devices of your system, written as letters followed by colons ("A:", "B:", "C:", etc.). The heading of this particular File Name Menu will give the name of your current storage device.

If you select a file from the File Name Menu, Alice will attempt to load a Pascal program from that file. If you select a directory, Alice will then display all the files and sub-directories from the directory you chose. You can choose the file you want from this new directory, or you can choose another directory and keep on looking.

On all File Name Menus, there is an entry that reads `Enter a File Name` . If you choose this, Alice will prompt with

>     File Name?

at the bottom of the screen. Enter the name of the file that contains the program you want to load, then press `[ENTER]`. DOS users should be aware that the maximum length of a file name is eight characters, plus the file name extension (".ap" for Alice Pascal programs). If you enter a name longer than this, it will be truncated.

All File Name Menus also have an entry that reads `Change Directory` . If you choose this, Alice will prompt with

>     Directory?

at the bottom of the screen. If you enter the name of a directory, then press `[ENTER]`, Alice will show you a File Name Menu for that directory.

File Name Menus are used by a number of commands, both for loading and saving programs. See the ``File Commands'' section in Chapter 4.

## Loading a Program

As noted earlier, you may load an existing program by choosing the `Load in an Existing Pascal Program` selection from the Starting Menu. You will be given a File Name Menu and asked to pick the file that contains the program you want to load.

If the file you pick ends in the suffix ``.pas'', Alice will assume that the file contains a Pascal program in normal ASCII text form. Alice will therefore invoke the APIN program to deal with this file. APIN comes with the Alice Pascal software package (on the Alice supplementary disk). It is important that APIN be located in a place where the system can find the program, e.g. in the same directory that holds the ALICE program itself. APIN's job is to translate Pascal programs from text to the special tree format that Alice uses to represent programs. In this way, Alice will automatically convert text programs to the correct internal format as the program is loaded. (Note: since Alice is in memory at the same time as APIN, APIN may not have the space to convert large programs. In such cases, APIN should be run separately -- see Chapter 5 for details.)

If the file you pick from the File Name Menu does not end in ``.pas'', Alice will assume that the file contains a program that is already in the Alice format. The program will be loaded and the cursor placed wherever it was when the program was last saved.

## Creating Programs

The other commonly used selection on the Starting Menu is `Edit a New Program` . If you choose this, Alice will lay out the following template.

Screen Shot progtemp not available

This is a program made up of keywords and placeholders. In this manual, placeholders will always be underlined. The way placeholders are shown on your display screen depends on what kind of monitor you're using. Colour monitors normally show placeholders in blue, while monochrome monitors show placeholders more brightly than normal source code.

To create your program, fill in the placeholders with appropriate Pascal code. Note that some placeholders do not have to be filled in for a program to run; for example, you don't need to fill in the `program-name` or the opening `Comment` placeholder. It is even possible that your program does not need any declarations. The principles of program input are discussed in Chapter 3.

You will notice that Alice places

>     {Comment that says what the routine does}

immediately after the program statement. This encourages programmers to fill in a comment explaining what the program does and how it will be used. For the same reason, Alice also puts comment placeholders at the beginning of every subprogram declaration and at the end of every declaration in the various declaration sections (const, type, var, etc.).

### Screen Lay-Out

The empty program template is not the only thing to notice when you first start creating a program with Alice. You should also note the lay-out of the screen. The top line of the screen summarizes the use of the various function keys. For example, one entry on the line is

>     [F1]: Run

This indicates that pressing `[F1]` will run your program. Most of the function keys call up a menu of commands, so the top line tells you what kind of commands will be found on the menu.

The top line of the screen is also used to display diagnostic messages for errors and warnings. For this reason, it is sometimes called the error line.

The bottom line of the screen is known as the status line. This gives information about your editing session. You will see several entries on the line.

>     File: name

gives the name of the file associated with the program you are editing. This is either the file from which the program was loaded or the file where the program was last saved. If this is a new program that hasn't yet been saved in a file, the status line shows

>     File?

The status line also contains the entry

>     WS: name

This gives the name of your current workspace.

The status line is often used when you are entering input that is not Pascal source code. For example, if you want to save a program in a new file, you have to type in the name of the file. Alice will move the cursor to the bottom line of the screen and prompt for the file name with

>     File name?

The status line is also used to show a few short messages. For example, it shows the message `Program is running` when you start up a Pascal program.

Usually, the area between the error line and the status line is occupied by source code. However, in ``Debug'' mode (described later on), the screen will be split in two to show both source code and output.

## Running a Program

Once you have created a program, you may run it by pressing `[F1]`. This issues the RUN command (discussed fully in Chapter 4).

When you run your program, the source code shown on the screen will disappear. Output from the program will be written to the screen as it is generated. If your program requires terminal input, enter a line of input and press `[ENTER]` to show the line is finished.

When the program is finished, a message to this effect will be printed on the bottom line of the screen. The output for the program will remain on the screen so you can examine it. When you have finished looking at the output, press any key on the keyboard. Alice will return to your source code, with the cursor in the position it held before the program ran.

Output from the program may be saved in a file via the LOG command -- see Chapter 4 for details.

### Single-Stepping

The other important way of running your program is single-stepping. To do this, issue the STEP command (see Chapter 4 for full details).

The easiest way to issue the STEP command is to press `[F2]`. The first time you do this, you will see the display on the terminal screen split in two. The top half shows the source code of your program. The bottom half will be used for output from your program.

Each time you press `[F2]`, Alice executes a single instruction from your program. In the source code part of the screen, you will see the cursor move from one instruction to another. In the output part of the screen, you will see output appear as instructions like `writeln` are executed.

At any point, you may stop to examine the values of your variables by going into immediate mode. This is described in a later section. By checking your variables, you can see precisely what your program is doing from one step to the next. This can be of enormous help when debugging a program.

## Debugging the Program

Alice provides a wide selection of debugging aids. These are described in Chapter 4. For now, we will just discuss the difference between ``Debug'' mode and ``Debug Off.''

To enter ``Debug'' mode, press `[F6]` and choose the selection `Debug On` . You can also enter ``Debug'' mode by invoking one of the debugging commands listed in Chapter 4. For example, you automatically enter ``Debug'' mode by single-stepping through your program.

The screen lay-out for debugging is slightly different than normal.

Screen Shot debugscr not available

The top half of the screen shows source code for your program. The bottom half shows output from the program and from debugging facilities. Separating the two is a debugging status line. This provides debugging information about your program. The debugging status line contains the information found on the normal status line. When you have a suspended program, it also shows the following

>     SUSPEND(N)  frame I/J

where `N` , `I` , and `J` are all integers.

The `N` after `SUSPEND` indicates tells how many suspended programs you have. A suspended program is one that has begun execution but has not finished. Programs may be suspended because you are single-stepping through them, because they are stopped at a breakpoint, because they encountered an error, and so on.

Execution of suspended programs can often be resumed with the CONTINUE command (described in Chapter 4). However, you may not resume programs that stopped due to error, nor may you resume programs that have been changed since they were suspended.

The `I/J` after the word `frame` on the debugging status line provides information about the subprograms of suspended programs. The `J` tells how many active subprograms were stacked up at the time that the most recent program was suspended. If no subprograms were active (i.e. the program was in the mainline), `J` will be zero. The `I` before the slash gives the number of the active subprogram that you are currently examining. This can change if you use the TRACEBACK command -- see Chapter 4.

Alice holds on to information about such suspended programs so you can examine them (e.g. the values of variables). Before you can execute another program, however, the information about the suspended program must be discarded. To do this, the suspended program must be cleaned away with the POP command (described in Chapter 4). The RUN command (obtained by pressing `[F1]`) automatically POPs away all suspended programs, so you don't have to do any POPping if you just want to RUN your program.

It is possible that you can have several programs suspended at once. In this case, you will have to POP them all before running a new program. To find out how many suspended programs you have, check the debugging status line.

The Alice screen remains split in two as long as you are in ``Debug'' mode. To go to ``Debug Off'' mode, press `[F6]` and choose the `Debug Off` selection. Alice will return to the normal screen lay-out, showing only source code.

### Immediate Mode

Immediate mode is one of the most important features of Alice. It allows you to execute Pascal statements immediately.

Most people will use immediate mode a great deal when debugging. As mentioned earlier, it is particularly useful when single-stepping. Suppose you single-step a few instructions into your program and then want to see what has happened to certain variables so far. To do so, press `[F6]` to call up the Run-Time/Debugging Menu, and choose the `Immediate Mode Block` selection. You will see that Alice puts the following in the middle of your source code.

>     {<-------------Immediate Statement Block--------
>     Declarations
>     begin
>     Statement
>     ----------End Immediate Statements------->}

This is an immediate mode block. Instructions entered in the `Statement` placeholder will be executed immediately: just type in the instruction, then press `[ENTER]`. (Pressing `[ENTER]` is what actually tells Alice to execute the instruction.) Pressing `[ENTER]` also creates another `Statement` placeholder after the instruction you typed in.

The most commonly used instruction will probably be a `writeln` . For example,

>     writeln(a);

will write out the current value of a variable `a` . If you have single-stepped into the middle of your program, this will be the value that `a` has at this point in execution. If you execute a few more instructions and write out the value again, you can see if this value has changed.

As noted in Chapter 3, the question mark ``?'' is a shorthand for

>     writeln(Value);

This can save a lot of typing if you issue a lot of `writeln` instructions in Immediate Mode. For example, to write out the value of a variable `a` , all you would have to type would be a question mark (to get a `writeln` instruction), an `a` (to fill the `Value` placeholder in the `writeln` ), and then `[ENTER]` (to execute the instruction).

You may also use Immediate Mode to change values in your program. For example, you can enter the immediate instruction

>     a := 1;

to assign a value to `a` . This could be useful to see how your program handles specific values for a variable.

You can execute single instructions from your program at any time, even if the instructions aren't in the immediate block. Move the cursor to the instruction you want to execute and select (highlight) the instruction using the standard selection techniques. When you have done this, press `[F6]` to get the Run-Time Menu and choose the `Execute this Statement` selection. The only difference between this and Immediate Mode is that pressing `[ENTER]` also executes an Immediate Block statement -- you don't have to go through the `Execute this statement` business.

To return to normal execution, issue the POP command. You can then return to single-stepping or anything else you like. However, you will notice that the immediate mode block stays where it is in your program. If you go back into immediate mode, you can re-execute a command in the immediate block by moving the cursor to the command and pressing `[ENTER]`.

If you want to delete an Immediate Mode Block, select (highlight) the code in the usual way and issue the DELETE command.

Usually, if you stop your program and go into immediate mode, you can continue program execution with a POP followed by a CONTINUE command (`Continue` on the Run-Time Menu). If, however, you have edited your program outside the immediate block while the program was stopped, you will not be able to continue program execution. If you change declarations in your program, you will not even be able to examine variable values while in immediate mode.