Workshop_Users_Guide_Beta_Apr83 Workshop Users Guide Beta Apr83

Workshop_Users_Guide_Beta_Apr83 Workshop_Users_Guide_Beta_Apr83

User Manual: Workshop_Users_Guide_Beta_Apr83

Open the PDF directly: View PDF .
Page Count: 124

Download
Open PDF In Browser	View PDF

WORKSHOP USER'S GUIDE
for the Lisa -

Beta Dmft
ApriJ 1983

CO ....... TENTS
1.

INTRODUCTION
The WorKshop proll i des tool s for program delJe 1opmen t.
It proll ides
fac iIi ties for ed it i ng, 1 anguage process i ng, and debugg i og, as we 11 as
commands for managing files and configuring the system. The system
al so i ncl udes many other ut iIi ties.

2. THE Fl LE MANAGER
The FileManager allowsyou tomanage andmanipulate files and volumes.
3. THE SYSTEM MANAGER
The System Manager allows you to set default
parameters for the Lisa, and manage processes.

and configuration

4. THE EDITOR
The Editor allows you to create andmodif>' text files. These text file,:.
are used as input to the Comp i leI' and the Assembl er.
5. THE PASCAL Cct1PI LER
The Compiler translates Pascal source code into object code.
Translation requires two steps: first the compiler translates Pascal
into I-code; then the code Generator translates the I-code into obj«Ct
code •.
6 • THE ASSEMBLER
The Assembl er trans 1a tes assembl y J anguage programs into obj ect code.
7. THE LINKER
The Linker combines object code fi les into executable programs.
8. THE DEBUGGER
The Debugger allows you to examine memory, set breaKpoints,
other run-time debugging functions.
9.

USlNG EXEC FILES
e:xec files allow you to execute
automatically.

a series of commands

and perform

and programs

10. THE UTI LITI ES
Util ity programs are provided for debugging, configuring the system,
and man i pul at i ng files.

APPENDICES
A. ERROR MESSAGES

WorKshop· User's Guide for the Lisa

Introdudion

Cha.pter 1

INTRODUCTION
1.1 The Workshop

•••••••••••••••••••••••••••••.••••••••••••••••••••••• 1-1

The WorKshop provides the functions necessary to develop and run programs
on the Lisa. The WorKshop can be booted from either a disKette or a. Profile.
1.2 Starting the Work$hop •. . . . . . • • • • • . . . . • . . . • . . . . . . . . . . . . . . . . ... . • . . .• 1-1
The WorKshop is started by booting the Lisa from a disK· containing the
WorKshop software. You can use the e:nvironments window to select one of
several available environments.

1.3 The WorKshop User Interface • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • •• 1-3
The WorKshop user interface consists of three command lines: the WorKshop
command line, the File Manager, and the System Manager.
1.4 File System Organization and Naming •••••••••••••••••••••••••••••• 1-4
Files are stored on disk volumes and are accessed by specifying the volume
name and the file name.
1.5 Using Utility Programs • • • • • • • • • • • • • • • •• • • • • • • • • • • • • • • • • • • • • • • • • • •• 1-7
Utility programs provide additional functions for the WorKshop. A· utility
program is started by choosing the RUN command from the WorKshop
command line.
1.6 How do I Write and Run a Pascal Program? .......................... 1-8
A Pascal program is written with the e:ditor. The source file must be
compiled and linKed before it can be run.
1.7 How do I write and Run an Assembly language Program? ............ 1-8
An assembly language program is written with the e:ditor. It must be
assembled and linked with a Pascal main program before it can be run.
1.8 How do I Use the BASIC Interpreter? • • • • • • • • • • • • • • • • • • • • • • • • • • • • • •• 1-8
A BASIC program can be written using either the Editor or the BASIC
interpreter to create the source file. The BASIC interpreter will run the
program.
1.9 How do I write a COBOL Program? ................................. 1-8
A COBOL program is written with the e:ditor. After writing the program,
enter. the COBOL language system to compile and run the program. The
COBOL system is invoKed by pressing C in response to the WorKshop command
prompt.

1.1 e The Operating Syst8'm ............. . • . . • • . . . . . . . . . . . . . . . . . . . . • . . .. 1-8
The WorKshop runs under the Operating System for the lisa computer. You
can access operating system routines through the SYSCAll interface. More
information about this interface can be found in the Operating System
Reference Manual for the Lisa.

alpha draft

1-1

27 January 1983

WorKshop

a I pha draft

User's Guide for the lisa

Introduction

1-2

27 January 1983

WorKshop

User's Guide for

~he

Introduction

Lisa

INTRODUCTION
1.1

The WorKshop Manager.
The Workshop allows you to develop and run programs on the Lisa. It provides
tools necessary to write, debug, and run programs in Pascal, BASIC, and
COBOL. This manual explains how to use ~he WorKshop and all of its tools.
Access to all WorKshop functions is provided by command
command line, WORKSHOP allows you to edit programs, run
programs, and use the various languages available on the
provides access ~o two SUbsystems; the File Manager,
Manager.

lines. The main
utilities or user
system. It also
and the System

The File Manager allows you to copy, delete, rename, and list disK files. It
includes a bacKup function, and functions for manipulating volumes. These
functions . are listed in the FILE- MGR command line, which is similar to the
main command line. (See Chapter 2.>
The System Manager provides for system configuration and defaults and
process managment. Its commands are listed in the SYS-MGR command line.
(See Chapter 3.)
All command lines are displayed at the top of the Lisa screen. If there are
more commands than will fit on one line, a U?" is at the end of the line.
Pressing U?U will display the remaining commands. To access any command,
press the first character· of the command name. To redisplay the first
command line, press RE:TURN.
Most commands will asK for additional information. Type in the information
using the Lisa keyboard. Some questions have a default value, displayed in
square bracKets «(defaultJ). To accept the default value, press RE:TURN. If
you don't want the default value, type in the value you want.
The Lisa system can display one of two screens, called the main screen and
the alternate screen. The WorKshop system normally displays on the main
screen. The alternate screen is used by the system debugger. You can
change to the other screen display by pressing the right hand OPTION and
E:NTER Keys. The System Manager contains the Console command, which can
be used to spet:ify where the WorKshop should display.
The WorKshop can be used to write programs in Pascal, COBOL, and BASIC.
To use these languages, refer to the appropriate language manuals. In
addition to this manual, you will need:
For Pascal Programming:
• Pascal Reference Manual for the Lisa
• MC68000 16 Bii: Microprocessor
programming)
• Operating System Reference
system calls)

aJpha draft

User's Manual (for assembly language

Manual

1-3

for the Lisa (for information

27 January 1983

WorKshop

User's Guide for the Lisa

Introduction

For BASIC Programming:
• BASIC User's Guide for the Lisa
For COBOL

Programming:

• COBOL User's Guide for the Lisa.
• COBOL Reference

Manual for the Lisa

If you have only a BASIC or COBOL system, you will not have all the software
described in this manual. The portions of this manual that will be most useful
to BASIC and COBOL programmers are:

• The Introduction,

which describes how to use the1NorKshop;

• The File Manager, which describes files and how to manipUlate them.
• The System
Manager,
which
configuration parameters.

describes

setting

the

system

• The E:ditor, which describes how to create and modify text files that are
used as source files.
You may also use some of the utilities if they are included in your software.
1.2

Starting the Workshop
The WorKshop can be booted from a disKette
commonly be used with a. Profile.

or a Profile.

It will most

To start the system, boot from a disK that contains the WorKshop software.
If your disK contains only· the WorKshop environment, the WorKshop command
line will appear at the top of the screen.
If you have more than one
environment (for example, the Workshop and the desKtop) you can use the
E:nvironments window to start up the environment you want, and switch
between them.
The E:nvironments Window allows you to seled the environment you wan1: to
s1:art.
You can also set a default environment that will be started
automatically when you boot the system. To access the environments window
while booting the system, press any Key while 1:he Lisa is starting up. The
environments window will be displayed.
The E:nvironments window is shown in Figure 1-1. It displays five buttons:
Power Off
Restart
Start
Set Default
No Default

Turn off the Lisa
Reboot or reset the Lisa
Start the selected environment
Set the default· to the selected environmen1:
The E:nvironments window will always be displayed on
startup.

To select an environment, move the pointer to the checKbox of that
environment and click the mouse button. Then move the pointer to the sta.rt
button and clicK. The selected environment will start. .
To access the Environments

alpha draft

window from the WorKshop,

1-4

and select another

27 ,January 1983

Workshop

User's C;",ide for the Lisa

Introduction

environment, use the Quit command from the WorKshop command line, or
press the on-off button.
To access the Environments window from the
DesKtop, press the on-off button while holding down the (apple) Key.

Environments

( Restart

o
•
o

au ice

System

( Set Dehult )

Workshop

Figure i -1.

1.3

( Power Off

Start

The Environments

Window

The Workshop User Inter-face.
When the worKshop environment· is selec1ed, the system will come up with the
WorKshop command line at the top of the screen. This command line lists all
the actions you can currently request of the system. The WorKshop line
displayed contains only some of the commands available. The rest of the
commands can be displayed by pressing "?" I the last symbol on the line. The
original command line can be redisplayed by pressing RETURN. A command is
executed by pressing the first letter of the command name.
There are two other subsystems that have separate command

a. Jpha. draft

1-5

lines; the

27 ,Tanuary 1983

WorKshop

Userls Guide for the Lisa

Introduction

File-Manager, and the System-Manager.
Their command lines can be
accessed from the WorKshop command line, and are used the same way.
You can terminate the operation of most commands by pressing (apple)
period. You can turn off the Lisa by pressing the on-off button at any time.
The system will shut down in a.n orderly ma.nner. A disKette can be inserted at
any time. It will automatically be mounted and accessible. DisKettes are
ejected by pressing the disKette button.
The main, or WorKshop, command line is as follows:
WORKSHOP: Fl LE-MGR, SYSTEM-MGR, Ed it, Run, Pasc a 1 , Bas i c, Cobol, Qu it, ?
The additional portion, displayed by pressing "?", is:
Assemble, Debug, Link, MakeBackground, Generah
All the main command line commands are described below.
FILE-MGR (F)
This command puts you into the File Manager subsystem, which is used to
manipUlate the files and volumes on the system. For more information on the
file manager, see Chapter 2 in this manual.
SYSTEM-MGR (S)
This command puts you into the System Manager subsystem. This subsystem
provides various configuration and utility functions. See Chapter 3 in this
manual for more information.
Edit (E)
The Edit command puts you into the text editor, which is used to create and
modify text files. The e:ditor is used to create source files for BASIC,
COBOL, and Pascal. It is also used for assembly language programming and to
create exec files. The e:ditor is described in Chapter 4 in this manua.l.
Run (R)

The Run command causes a compiled and linKed program to e>:ecute. This
command is used for user-written Pascal programs, utility programs, and any
other software that runs under the WorKshop. The Run command asKs you for
the file to run. This file must be an executable object file or an exec file. (An
exec file name must be preceded by a "<" .) If you do not give it a complete
pathname, the Run command will search through up to three default volumes
for the file.
These defaults can be set by the File-Managerls Prefix
command. See the Prefi>: command in Chapter 2 for more information.
The Run command will also accept an "exec file" as input. An exec file is a
scenario of commands for the WorKshop system to carry out. An exec file
name must be preceded by a "<" to be processed correctly.
For mor-e
information on e:
The Generate command converts intermediate code files produced by the
Pascal compiler into object code. It is used with the Pascal compiler and is
described in Chapter 5.
1.4

File system organization and naming
Files are stored on volumes, that are mounted on devices. A volume has a
name and a directory of files tha.t it contains. A file is specified by giving the
name of the volume and the name of the file:
-volumename-filename

aJpha draft

1-7

27 January 1983

WorKshop

User's Guide for the Lisa

Introduction

The WorKshop maintains a worKing directory; you can access files in it
without specifying a volume name. The worKing directory can be. changed by·
using the File Manager's Prefix command. Files on the worKing directory can
be specified by just the file name. with no leading "_":
filename
Further information on the file system can be found in Chapter 2 of this
manual and in the Operating System Reference Manual for the Lisa.•
1.5

Utility Progra.ms.
There are various utility programs provided with the WorKshop.
used for functions not as commonly used as the commands.
The utilities are described in Chapter

These are

1e.

You must Run utilities. Select the Run command from the main command line
by preSSing R when the main command line is displayed. The system will ask
you for the name of the file to run. Type in the name of the utility you want to
run.

1.6

How do I Write and Run a Pascal Program?
To write and run a Pascal program, proceed as follows:
1.

Use the Editor to create a text file with the Pascal source program. See
Chapter 4 in this manual for more information on editing the file. See
the Pascal Reference Manual for the LIsa for information on the
language.

Compile the program using the Pascal command (press P while the
Workshop command line is displayed) from the main command line. The
output from the compiler is an intermediate file.

The output from the Pascal command is an I-code file. Use the Generate
command to convert the I-code file into an object file. To use the
Generator, press G when the WorKshop command line is displayed. See
Chapter 5 for more information on compiling Pascal programs.

linK the program using the linK command. In order to be executable,
the program must be linl? ds=
COpy to wha t new f i 1e? -bacl.
• The maximum number of files on the device. The default is a good value
unless you are using a large number of very small files or a few very large
files.
The volume is initialized, with an empty directory. (If the device is a disl:istin9 volume on it, and give you a. chance to change your
mind before destroying the existing volume.
After initialization, the device is automatically
2.9

mounted so it can be used.

How do I Change thlt Name of a File or Volume?
The Rename command allows you to change the name of any file.
i.

If you are not in the File Manager subsystem, enter it by typing F in
response to the Worl or on the alternate'
screen (where LisaBug 'displays), or on an external terminal connected to the
RS232A or B port.
FilesPrivate (F)
The FilesPrivate command selects whether or not the private system files
should be displayed by the List command. The default is to not display the
private files. Private files are any files with a name beginning with "{".
These file names are used by the system for files you should not normally need
a.ccess to.
Validate (V)
The validate command is used ~o set up defaults for verifying operations.
Currently the only default of this type tells if the system will verify file
copies or not. The system verifies a copy by comparing the original file with
the copy to be sure they are the same. The boot default is to never verify.
You should have no reason to verify unless you something is wrong with your
disK.
S.3

The Preferences Tool
The Preferences tool is started by pressing P in resporlse to the System
Manager command line. After you are finished with it, you can exit bacK to
the System Manager by selecting Quit from the Tools menu.
The Preferences tool allows you to set up your WorKshop system the way you
want it. It contains four sections:
• Convenience settings ~hat allow you to set up the screen contrast, the
speaKer volume, and repeat delays.
• Device connections that tell the Lisa system what external devices are
connected.
• Startup that tells the Lisa what device to use as a. startup device.
• WorKshop defaults that set up things the WorKshop needs to Know.
These default settings are stored in parameter memory, a small area of
memory that is preserved as long as the Lisa is plugged into a worKing outlet
and for up to 10 hours when the Lisa is unplugged. If your Lisa is without
power for longer than this, the preference settings will be restored from
information on the startup disK.
Any changes made with the Preferences tool change. Parameter Memory
immediately, but some of them, such as device connections and startup

Alpha draft

3-4

F~bl'uary

1983

WorKshop

The System Manager

User's Guide for the Lisa

options have no effect until the system is booted again.
The preferences tool displays a window containing a number of buttons and
You set the values you want by using the mouse to move the
checKboxes.
pointer to the desired options and clicKing.
These four areas are described briefly below. More information on the firs1:
three areas can be found in the Lisa Owners Guide Section D. Select the
area you want 1:0 view or change by moving the pointer with the mouse to the
checKbox in front of the section name and clicl:tthat is copied is placed on The Clipboard and also left in place in the
active document.
..
The contents of The Clipboard may be inserted at any point in the active
document by moving the insertion point to where you want the text inserted
and selecting Paste from the edit menu.

4.2.2

The Menus
Operations are provided in five menus: File, Edit, Search, Type Style,and
Print. The File menu is used to access things outside the e:ditor, such as
documents and stationery. The Edit menu contains the editing operations.
Search provides for finding strings in the active document. The Type Style
menu selects the font for document display. The Print menu controls
printing. e:ach of these menus is described in more detail below.
You select an operation from a menu by moving the arrow pointer to the menu
name on the menu bar and holding down the button. The menu is displayed.
Seled the menu item by moving the mouse up Dr down until the right item
appears in reverse video. Releasing the button starts the operation.

4.2.3

Creating and Using Stationery
Stationery for a special purpose (such as a letterhead) can be created with
the e:ditor. Stationery is just a regular document containing the desired
text. To use any stationery other than the default blanK paper, select Tear
Off Stationery from the File menu, and type the name of the document
containing the stationery when it asKs you for the stationery name.
To create stationery, maKe a document containing the standard text you
want on the stationery.
Save this document on the disK. To use this
stationery, selec1: Tear Off Stationel'Y from the Edit .menUt and give it the
file name of the stationery you created.

Alpha draft

4-4

27 .tal'lual'Y 1983

WorKshop
4.2.4

The Editor

User's Guide for the Lisa

Editing Multiple Files
More than one file may be open at one time, but only one document is the
active document. To read in a document when you already have an active
document, select Open from the File menu. Itwill asK you for the document
name. The new document will be read in to a window on the screen and will
become the active document. To maKe another document the active
document, . use the mouse to move the pointer into a portion of that document
and clicK.
This capability may be used to copy text from one file to another by using the
following sequence of operations:
• Open the document containing the text you want to copy.
• Select the text you want to copy and select Copy from the Edit menu.
This places a copy of the text onto the Clipboard. You can use Cut if you
want the text to be removed from its original file.
• Open the document
active document.

you want the ted to be copied to. It becomes the

• Move the insertion point to the place you want the text to be inserted.
• Select Paste, which will copy the text from the Clipboard to the active
document.
Further information on each of these operations may be found below.
4.3

Selecting Text
The basic editing functions are Cut, Copy, and
Copy text, you must select the text to be cut
move the insertion point to where you want the
text and move the insertion point by using the
the screen.

Paste. Before you
or copied. Before
text to be placed.
mouse to move the

can Cut or
you Paste,
You select
pointer on

When there is an active document, the pointer will have one of two shapes:
Text pointer in a document
Arrow pointer for menus and scroll bars
Use the mouse to move the pointer on the screen. The shape of the pointer
will change when you move in and out of the document display window.
Within the display window, the text pointer is used to move the insertion
point and to select text.
In selecting text, you may select characters, '....ords, or lines. You may also
select any number of characters, words, or lines. Selected text is displayed
inreverse video.
4.3.1

How do I Move the Insertion Point?
The insertion point is indicated by a blinKing vertical line where the ne>:t
character will be inserted. All insertion, whether from typing or pasting,
taKes place a:t this point in the file, even if it is not visible in the window.
To move the insertion point, move the text pointer to where you want it to be

Al pha draft

4-5

27 January 1983

WorKshop

The Editor

User:'s Guide for the Lisa

and clicK. Note that the insertion point is also moved when you select text.
4.3.2

How do I Select Characters?
To select characters, move the text pointer to the beginning of the
characters you want selected, press and hold the button while moving to the
last character you want selected.
An alternate way of selecting characters, which is especially useful when
selecting a. large blocK of text, is as follows. Move the pointer to the
beginning of the text you want selected· and clicK. Then move the pointer to
the end of the text you want selected and shift clicK (hold down the shift Key
on the Keyboard and clicl< the mouse button). You may use the scrolling
controls to display the. end of the, text you want selected if it is too big to fit
in the window.
. .

4.3.3

How do I Select Words and Lines?
To select a word, move the te>:t painter into the word and clicK twice.
select a line, move the pointer into the line and clicl< three times.

To select multiple words or lines, clicK the required number of times, and
hold. Move the pointer to the last word or line you want selected and release.
An alternate method, especially useful when you want to select more text
than will fit in one display window, is as follows. ClicK the required number of
times to select the first word or line. Scroll the wir.dow if necessary to
display the last item you want selected. Move the pointer to the last item you
want selected, shiH clicK, and the entire blocK of text will be selected.
4.3.4

4.4

How do I Adjust the Amount of Text Selected?
To change the amount of text selected, move the pointer to the position ~hat
you want the selection to extend to and shift clicl<. This can be used to either
expand or contract the selection.

Scrolling and Moving the Display
When a document is longer than will fit into the display window, only part of
the document is displayed at one time. You can change what part is displayed
by "scrolling" through the display. The vertical bar on the right side of the
active window is the scroll bar. An example of a text· window showing the
scroll bar is in Figure 4-1.
The display window can be changed in size and moved on the screen. This
allows you to have multiple files displayed on the screen. These operations
are done using the title bar and size control box.

4.4.1

Scrolling the Display
There are three ways of moving the display window through the document.
The first is by using the elevator. The elevator is the white rectangle in the
scroll bar. Its position in the "elevator shaft" (the grey portion of the bar)
indicates the relative position of the currently displaydtext window in the
document. If the elevator is near the top, you are near the beginning of the
document. If it is near the middle, the text displayed on the screen is near the
middle Ot the document, and so on. To change the position of the text window,
you can use the mouse to move the arrow pointer into the elevator, clicK and

AI pha draft

4-6

27 Jar.uary 1983

WorKshop

User's Guide for the Lisa

The Editor

hold the button down while you move the eleva.tor to the position in the
document you want to display. When you release the button, the display will
be updated to the new position.
The second way of moving the window maKes use of the view buttons. The
view buttons are the boxes at each end of the elevator shaft. If you move the
arrow pointer to a view button and clicK, the display will move one text
window toward the beginning or end of the document, depending on which
button you clicKed.
The third way of moving the window uses the scroll arrows, which are just
above and below the view buttons. If you move the arrow pointer to the
bottom scroll arrow and clicK, the display window will move' one line toward
I f you hold the button down, the window will
the end of the document.
continue to move a line at a. time until you release it. The upper scroll arrow
worKs the same way, except it moves the window towards the beginning of the
document.

4.4.2

Moving the Display
You can move the display window on the screen and change its size. This lets
you display multiple files on the screen. You can maKe any visible window be
the active window by moving the pointer into it and clicKing.
To move a window, move the pointer to the title bar, press the mouse button
and hold it while you move the window. When you release the button, the
window will be redisplayed at the new location.
To change the size or shape of the active windowt move the pointer to the
size control boxt press the button, and move the pointer until the window is
the right sin and shape. Release the button and the resized window will be
displayed. The size control box is the box in the lower right hand corner of
the window. Only the active window can be resized.

4.5

The File Functions
The file menu provides functions for communicating with the outside world.
Functions are provided for reading in and writing out documents, and for
exiting the Editor. The Filing menu is shown in Figure 4-2. Each function is
explained below.
fi J iogmenu

Figure 4-2.

Alpha draft

The Filing Menu

4-7

27 January 1983

Workshop

User's Guide for the Lisa

The Editor

Save & Put Away
This writes out the active document and closes it.
Save a Copy in ...
This writes out a copy of the active document to another file name. You are
prompted for the name of the file to write to.
Sa ve & Continue
This saves all changes made so far by writing out the document
without closing the document •.

Revert to Previous Version
This returns the document to the way it was before you started editing
when you lasi .saved it. This is done by reading in the file from the disK.

disi<~

ii~

Open ...
This tells the Editor to get a new document. 11: prompis you for the document
name~ then reads it in and mai:amplet to move a blocl< of te>:t from one place in a document to anothert
follow these steps:
1.

Select the blocl< of text to be moved.

Select Cut from the Edit menu. The te>:t is removed from the active
document and placed on the Clipboard.

Move the insertion point to where you want the ted to be.

Select Paste from the Edit menu. The te>:t on The Clipboard is inserted
a t the insertion point.

The edit menu also allows you to adjust selected te>:t left
inserting or deleting spaces. It also allows you to set tabs.

01'

right by

Some edit functions may also be done by holding down (apple) and pressing
another Key. The Key that corresponds to each function is shown in the edit
menu. See figure 4-3.
Undo Last Change
This command puts the document bacK to the '/Jay it was before the previous
operation if possible. The system will tell you if the last operation cannot be
undone.
Cut
Cut places a copy of the currently selected text into The Clipboard a.nd
removes the text from the active document. You may also Cut by pressing
(apple) X.
Copy
Copy places a copy of the currently selected text onto Tn€' Clipboard, but
does not remove it from the active document. You can also Copy by pressing
(apple) C.
Paste
Paste inserts a. copy of the text on The Clipboard at the insertion point in the
active document. You can also Paste by pressing (apple) V.
Shift Left
Shift Left moves selected text left by deleting a single space from the left of
each line. It will not delete any characters other than spaces. It is most
often used to adjust the left margin of a blocK of text. You can shift left by
pressing (apple) L
Shift Right
Shift Right is similar to Shift Left, e}(cept that it moves the selected text to
the right by inserting spaces at the beginning of each line. This can also be
done by pressing (apple) R.
Set Tabs ...
Set Tabs allows you to set the spacing of the tab stops.
Select All of Document

Al pha draft

4-9

27 ,lanuary 1983

l..Jorl:t string in the active
document. The basic operation is Find. 'Nhich locates the newt occurrence of
the string and selects it. Find & Paste All will replace each occurrence of the
string with the contents of The Clipboard. Several options are provided to
specify how tt-Ie match isto be found. The Search menu is shown in Figure 4-4.

Find...

~~-~F

Find Some
Find & Paste All

tiS :

v'Separate Identifiers
All Occurrences
v'Cases Need Not Agree
Cases Must Agree

Figure 4-4.

The Search

All searches start at the insertion point, and go to the end of the file.
There are three search operations in the Search menu, as follows:

Find ...
Find prompts you for the string to search for, then finds the ne>:t occurrence
of the string. If a match is found, it will be selected al""d wisplayed. The Find
command can also be executed by pressing (apple) F.
Find Same
Find Same repeats a previously specified Find, and selects the
occurence of the string. You may do a Find Same by pressing (apple) S.

Find 8. Paste All
This finds all occurrences of the specified string from the current insertion
point to the end of the file, and replaces eacb of them with the contents of
the Clipboard.
The other four items in the search menu tell how a match
There are t'NO areas to describe: searching for tol;t file as input, and produces:. a machine language (.OBJ)file
as output.
6.3 The Assembler Opcodes ...•••..•.••••••••.•...••••.•••.•••••.•••••••••• 6-5

The assembler opcodes are the standard 6:::000 opcodes, with a few
0.1 ter·na te fc.rms for some instructions.
6.4 Assembler Syntax ••••••••••• ~ •••••••••••••••••••••••••••••••••••••••••• 6-7
An assembler statement consists of an optic.nallabel, the opcode, and one
ortwo operands. The operandscan contain e>:pressions.

6.5 Assembler Directives .................................................. 6-9
The assembler directives provide for procedure and function definition,
macros, label and constant declara tion tlisting control, storage allocation,
and conditional assembly.
6.6 COITHTIUnication wilh Pasca.l ....•...............•..................... 6-11

AI pha draft

6-1

7 January 1983

Wor!:ecuted.
Assembly language routines are used to implemerlt low level or time
critical functions. Thischapter describeshow to use the assembler/and the
syntax of asse mbly larlguage progr·ams. Irlforma tion on the machine
instructions available on the 6:::000 processor is found in the Mptorola
manual.

0.2 Using the Assembler
To assemble a program, pressA from the INorKshop comma.nd line. Then
specify the input file (the file that contains your source program) and two
output files: the object file (the file that contains the machine-language
code produced by the assembler)and an optionallistingfile.
The input file must be a te:d file containing assembly language source
statements. You can maKe this file with the editor. The output file
produced is an object file (.OBJ),that must be linKed with a Pascal main
program tobe run.

0.2.1 Assembler Options
When you start the assembler, the option settingsare displayed. You may
change the options by responding to the input file prompt with U?/I. There
are two assembler options:
P
S

Pretty Listing.
Print information about available space.

Each option may be sette + or-:
+

On
Off

When Pr·etty Listing is on, the forward jump addressesare filled in with the
correct values.
After setting any options desired,pressreturn,and the assembler asKs you
for the name of the input file. The assembler then asKs you forthe name of
thelisting, and the output files.

6.2.2 The Input File
The input file is a text file contairling assembler language source
statements. A file created using the Editorwillbe in te>:tfile format.
When the assembler asK·; you for the name of the input file, type "?" if you
want to change assembler options at this time; otherv.Jise type the
pathname of your source file.

Al pha draft

6-3

7 January 1983

Wori-. If Pretty Listing is ont the actual value will be filled in.
Source :.tatement error'sare flagged irl the listing. Refer to the Appendi:·:
for a listof assembler errormessages.
Arl e>:ample clf an assembler'listingfile isshown in Figure6-1.
assemblerl isting
TAIL
PAGE 00001
00001
00021
00041
00061
00061
OOOAI
OOOCI
OOOEI
OOOEI
00101
00121
00161
00181
OOlAI
OOlAI
OOlCI
001EI
OOlEI
001FI
00261
00201
00341
00381
00421
00451
00461
00461
00461
00461

Me --------1
5 ASMSTR

FILE: EX/ASM/STR. TEXT

205F
225F
2FOA

.proc
move. 1
move. 1

AsmStr
fa7l+' aO

move. 1

a2, - (a7)

45FA 0016
4280
1012

lea
clr. I
move.b

dO
(a2 ), dO

get size of string

120A
5340
6500 0006
120A
60F6

COP!;! subq
blo
move.b
bra

(a2)+,(a1)+
#l,dO

COP!;! size of string (first b!;!te of str ing )
done cop!;!ing string?

245F
4EOO

done

26
74
72
20
68
20
6C
00

68
69
66
65
61
65

move~b

move. 1

jmp
69
6E
72
20
73

73
67
6F
4C
73

20
20
60
49
65

73
69
20
53
60

74
73
74
41
62

size
m!;!Str

+~al

return address

address of string passed from Pasca I pgm
save scratch reg a2

size~a2

done

yes,

(a2)+,(a1)+
COP!;!

COP!;!

f:~

l+' a2

return to pasca 1
one char of the string

restore scratch reg

return to pascal

"b!;!te
. asc i i

38
'this string is from the LISA assembler"

. align

72
just to be sure next

instruction

is on UJord

boundar!;! (even address)
j.

end

Figure 6-1. Assembler Listing

Al pha draft

6-4

7 January 1983

WorKshop Refererlce Manual for the Lisa

The Assembler

If you specify a device name such as -PRINTER or -CONSOLEforthe listing
file, the listing will be printed on that device. If you specify a.disK file, the

listing will be created as a textfileiYou may thenprintitby usingthe Copy
command in the File Hanager commarld line.
6.3 Assembler Opcodes
The 6:::000 opcodes are described in the Motorola MC68000 Microprocessor
User's Hanual. The assembler has two variant mnemonics for branches
(BHS for BCC arid BLOforBCS). The variantm.me!:. are more indicative of
how the instruction is being used afterl.Jnsigned comparisons. The default
radi:{ isdecimal.
The size of an operation (byte, 'Nord, or long) is !:.pecified by appending
either .B, .W, or.L tothe instruction. The default operation size isword. To
cause a short for ...... ard branch, append a .S to the instruction. The default
branch size is Long.
6.3.1 Optimization
It should be noted that the Assembler accepts generic instructions and
assembles the correct form. The instruction ADD, for e::t.
becomes

ADD
ADDA

D3,A5
D3,AS.

MOVE ,eMP, and SUB are handled in a similar manner.
6.4 Assembler Syrrtax
This section describes the form in which the assembler e: section of non code generating
operations. This is usually where any constants or macros are defined.
Ne:d itconains one or more procedures (.PROG) or functions(.FUNC). These
each contain a sequence of code generating opera.tionsand directives. A
procedure or function is ended when the a.ssembler encounters the ne}:t
.PROC or .FUNe. A .END directive is the last statement in the program.
Any te>:tbeyond the .8: ND is ignored.

Al pha draft

7 January 1983

The Assembler

WorKshop Reference Manual for the Lisa

non code gener'a ting opera tions
.PROC (or .FUND
code gener'a ting opera tionsand any directive:, needed
.PROC
etc •
.END
Figure 6-2. Structure of an Assembly Language Program
The non code generatingdirectivesare:
.EG.U
.RE:F
.DEF

.MACRO
.E: NDl1

.IF
.E:LSE:
.E:NDC

.LIST
.NOLIST
.PAGE:
.TITLE:

.MACROLIST
.NOMACROLIST
.PATCHLIST
.NOPATCHLIST

6.4.2 Constants
Constants in the A:.sembler ca.n be either'rlumeric clr string constants.
6.4.2.1 Numeric Constants
Numeric constar,ts in the assembler can be e>:pressed in decimal,
hexadecimal, octal, or·binary. Th~ defaultradi;( isdecimal. The otherthree
base:·are e:-:pr·e:.sedas follolNs:
He>:adecimal
He>: numbers can be e>:pressedin two ways:
1.

Preceed the number with a "$". E:>:amples of thisare:
$FF13
$127

Fallow the number with an "H". UsinCl this farm, the number must
startwith a digit (0-9). E:xamples:
OFF13H
195H

Octa.l
Octal numbers are followed by the cha.racter "0". Note tha.t this i·:; the letter
O,not the chara.cter zero (0). E:>:amples:
770
1040

Al pna draft

7 January 1983

WorKshop Reference Hanual for the Lisa

The Assembler

Einary
Einarynumbers are followed by the character" B". E>:amples:
1011E
111000E

6.4.2.2 String Constants
String constants are delimited by matching pairsof single or dc.uble quotes.
E >: am pIe s of string cons tants are:
"thisis a str'ingconstant"
'using single quotesas delimiters lets you include "double" quotes'
6.4.3

IdentHiers
Only the first eight characters of identifier names are mea.ningful to the
assembler. The first character must be alphabetic; the rest must be
alphanumeric, period,underbar,or percent sign.
8::-:a.mples of identifiersare:
LOOP
EXIT_PRC

NUM

•
6.4.4 Labels and Local Labels
Labelsbegin in column one. They can be followed by a colon, if you liKe.
Local labels can be used to avoid using up the storage space required by
regular labels. The local label stacK can handle 21 labels at a time. ltis
cleared every time a regular label is encountered. Local labels in this
assembler start with the character ';iI. A local label is an '@ followed by a
string of decimal digits(O-9). E>:amples oflocallabelsare:
'@123
'@2
'@79
6.4.5 8:xpressionsand opera:tors
All quantities are 32 bits in size unless constr·a.ined by the instruction.
8::

There is no operator precedence in e>:pressions. For e:, or' the operand:. can be r·eorder·ed
as: 9 * 4 + 2.
6.4.6

Addressing Modes
The following i~. a ~·umrrta.ry of the addr'essing mode synta:< for the 6:3000.
Refer to the Motorola 6:::000 manual for information on the addressing
modes supported by the 6:::000. Table 6-1 gives a summa.ry of the
addressingmades including theirsynta.:<.
Table 6-1. Summary of Addressing Hodes
Made
0
1

2
3
4

5
6
7
7
7
7
7

0 •• 7
0 •• 7
0 •• 7
0 •• 7
0 •• 7
0 •• 7
0
1

..,
'"

3
4

Synta>:
Di
Ai
U-.i)

(Ai)+
-(Ail
e(Ail
e(Ai,Ril
e
e
e
e(Ri)
*Fe

Meaning

ExtraWords

Data direct
Addressdirect
Indirect
Postincre ment
Predecre ment
Inde>:ed
Offsetinde>:ed
Absolute shortaddress
Absolute long address
PC Relative
PC Relative inde::ample, to push registersDO through D2, D4, and AO through A4 onto the
top of the stacK:
II / " .

t10VEM. L

DO-D2/D4/AO-A4! -(An

6.5 Assembler Direc1:ives.
The Assembler directives (pseudo-ops}are:

Al pha draft

.PROC
.FUNC
.DEF
.REF
.SEG
,8:ND

C,E:{ pr J
:pr J

(identifier-list>
'(name>'

begin procedure with 8:::prargs
maKe identifierse:'

,WORD

.LONG
.ALIGN

<8::

place ASCII string in code
alloca te a byte in code for each value
allocate length bytesof value
a110ca te a word for each value
a.llocate a. long word for each value
allignrle>:t code on multiple of 8:>:pr

.ORG
.RORG

place next byte at
same as .ORG

,8:G.U

setlabelequalto

c,value J

6-9

7 ,January 1983

WorKshop Reference M'anua] for theUs'a

The Assembler

.MACRO
.ENDM

begin macro definition
end macro de fini tion

.IF
.ELSE
.ENDC

begin conditional assembly
optional 0.1 terna te to .1 F block
end conditional assembly

.LIST
.NOLIST
.PAGE
':pansionlisting
turnoff expansion listing
turnon patc:hlist
turnoff patchlist

.INCLUDe:

insert< filename> into assembly

6.5.2 Space Allocation Directives.
The space allocatio,n directives are .ASCII, .BYTEl:, .WORD, .LONG, and
.BLOCK•

•ASCII 'string'
converts 'string'ir.to the equivalent ASCII byte constants and places the
bytesin the code stream. The string delimiters must be matching singleor
double quotes. To insert a single quote intothe code use double quotes as
delimiters. Similarly for double quotes:
.ASCI I

.ASCI I

"AB/CD"
'AB"CD'

; string containing a single quote
; string containing a double-quote

.EYTE
allocates a byte of space in the code stream for each of the values giver,.
e:ach value must be between -128 and 255 •
•ELOCK (,value J
allocates bytes, each filled with the value given. If no value is
given, a blocl< of zeros is allocated •
•WORD
allocates a word of space in the code stream for each of the values listed.
The values must be between -32768 and 65535.

Alpha draft

6-10

7 January 1983

WorKshop Reference Manual for the Lisa

TEMP

.WORD

The Assembler

0,65535,-2,17

creates the assembled output:

0000

FFFF
FFFE
0011
.LONG
allocates two wordsof space foreach value in the list. Fore: .EG.U
assigrls(value> to . can be an expressioncontaining other
labels •
•ORG
puts the next byte of code at relative to the beginning of the
assembly file. Bytes of zero are inserted from the current location to
.
•RORG
is similar to .ORG. It indicates that the code is relocatable. Because the
loader does not support absolute loading, .ORG and .RORG accomplish the
same function. All addressing must be PC relative.
RORG (without the leading period) is the same a.s .RORG. Similarly, END =
.E:ND,EQU = .E:QU, PAGE = .PAGE:, LIST = .LIST,NOL= .NOLIST.
6.5.3

Macro Directives.
A macro consists of a macro name, optional arguments, and a macro body.
When the assembler encounters the macro name, it substitutesthe macro
body for- the macro name in the assembly text. Wherever %noccurs in the
macro body (where n is a single decimal digit), the te:d of the n-th
parameter is substi tuted. I f parameters are omitted, a null string is used in
the macro e::c1ude sections of code at assembly time based on the value of
some e>:pression •

•IF :pression>isconsidered
to be false if it evaluates to zero. Any non-zero value is considered true.
The e>:pressioncan also involve a testfor equality (using <> or =). Strings
and arithmetic e>:pressionscan be compared. If {e::amples of the use of conditionals. The
general form is:
.IF

{expr}
jassembled if (expr) is true

[ .ELSE)

jOp tiona I
;assembled if (e>:pr} is false

.ENDC

6.5.5 8:xternal Reference Directives.
Separate routines. can shar'e data structures and subroutirlesby linl
identifies labels defined in the current routine as available to other
assembly routines through matching .REFs. The .PROC and .FUNC
directives also generate code similar to that gem?rated by a .DEF with the
same namet so assembly routines can call e>:ternal .PROCs and .FUNCs
with .RE Fs.

.PROC

Simple,!

.DEF

Alpha, Beta

BNE
Alpha

- Beta

t10~)E

RTS

Beta HOVE
RTS

.END
This e:{ample defines two labelst Alpha a.nd Eeta.twhich another assembly
routine can access with .RE: I' .
• REF

used in the cur-rent routirle as
available from some other assembly routines which defined these
id e rlti fie rsusing th e .DE F directi ve •

• PROC

Simp 1e

.REF

Al pha

JSR

Alpha

.END
uses the label' Alpha' dedar-ed in the .DE: F e::ternal reference with an address pointer to the word of OIS
following the opcode. If the referenced label and the reference are in the
same segment modulet the linKer changes the addressing mode from short
absolute to single-word PC relative. I fthowevert the referenced procedure
is in a different segment, the linKer converts the reference to an inde>: ed
addressing mode (off AS) and the word of zeros iscorlVerted ir,to the proper

Alpha draft

6-13

7 January 1983

The A:.:.embler

WorKshop Reference Manual for the Lisa:

entry offsetin the jump ·table;, If the referenced procedure is in an intrinsic
unit (and therefore in a. differentsegmenU, the IUJSR, IULEA, IU.JMP, and
IUPEA instructions are used (seepage ##). The linKer blindly assumes that
the word immediately before the word of zeros is an opcode in which the
low order6 bitsare the effective address. Thusta .RE F label cannot be used
with any ar·bitraryinstruction. The .REF labels are intended for JSR t J14P,
PE At and LE A instructions •
•SEG
default segmerlt name is"
" (E: blanKs).
code in segment called "segment name".
6.5~6

,SE!:,G"sel~.ment

name" puts the

Listing Control Directives.
The directives that control the Assembler's listing file output are .LIST,
.NOLISTt.PAGE, .TITLE,.MACROLIST, .NOMACROLIST, .PATCHLIST, and
.NOPATCHLIST. If you do ilot specify a name for the listing file iii response
tothe Assembler'sprornpt:
. Listing file «cr> for nOile)the listing directives are ignored.
The defaultforthe assemblerisfor.LIST,.MACROLIST, and .PATCHLIST to
be in effect when the assembler starts .. TITLEdefaultsto blanK •
•LIST and .NOLIST
can be used to select portions of the source to be listed. The lis1:inggoes to
the specified output file when .LISTis encountered •• NOLISTturnsoff the
listing. .LIST and .NOLIST can occur any numberclf times during an
assembly .
•PAGE
iilsertsa page feed into the listiilgfile •
•TITLE
'{title)'
specifies a title for the listing page. can' contain up to :30
characters, and can be enclosed in either single or double quotes •
. TITLE

'Interpreter'

places the word, Interpretertatthe head of each page oUhe listing •
•PATCHLIST
patches the forward referenced labels iii the listiilg. It must be on if you
want prettylisting •
•NOPATCHLIST
tumsoff pa tching of forward references •
•MACROLIST
turnsonlistingofthe e:<panded code from a macro.

Al pha draft

6-14

7 January 1983

The Assembler

WorKshop Reference Manual for the Lisa

.NOMACROLIST
turns off listing of macro e>:pansion. See Figure 6-3 for e>:amples of the
macro listing options.
00241
"00241
00261
00261
00261
00261
00281
002AI
002AI
002AI
002AI
00311
00321
00341
00341
00341
00381
00381
00381

4E5E

2E91"
4E75

#
#
#
#
#
#
#
#
#

31 32 33 34 35 36 37 #
#
38
4E71

4,'12345679'
eai 1
A6
UNLK
• I I"
4
0
. ELSE
.II"
4
4
MOVE.L
(SP )+, (SP)
RTS
• ELSE
.ENDC
.ENDC
• ASCII
'12345678'

nap
. namacro 1ist
head

. include

ex/asm/str

Figure 6-3. Ma.cro Listing Options
6.S.7

File Directives.
The pseudo-op
.INCLUDE
<filename}
causes the contents of <filename> to be assembled a.t the point of the
.INCLUDE. <filename> need not specify the. TEXT suHi>: .An included file
cannot itselfcontain a .INCLUDE statement.

6.6 Communication with Pascal.
Pascal programs can call as':sembly language procedures. The Pascal
program declares the assembly language procedure or function to be
EXTERNAL. IHhe assembly routine does not return a value,use .PROe. If
.FUNC is used, space for the returned value is inserted on the stacK just
befor'e the functiorl parameters, if any. The amount of space inserted
depends on the type of the function. A LongIntor Real function resulttaKes
two wor'ds,a Boolean result taKes one word with the result in the high order
byte, and other types taKe one word. In the following e>:ample, we linK a
bit-twiddling assembly language routine into a Pascal program. The Pascal
hostfile is:
PROGRAt'l BITTEST;
I ,J: INTEGER;
FUNCTION I and( i , j : INTEGER) : INTEGER;
EXTERNAL;
<* external =Assembly language *)

~)AR

BEGIN
i := 255;
j := 33;
I,.JRITELN (1 ,J,' AND = .' ,land (I, J»);
END.

AI pha draft

6-15

7 January 1983

WorKshop Reference Manual for tne Lisa.

The Assembler

The Assembler file is:
• FlINC
MOI,)E .L
t101,)E .W
t10'v'E .W
AND.I,~

~10'JE

.I,oJ

Jt1P

IAND,2
(A7) + ,AD
(A7)+ , DO

(A7)+,Dl
D1 , DO
DO, (A7)
(AD)

ar gurne n t s
return address

tr.'iO

J
I
I AND J

put function result on stacK

.END
In the e>:ample given above we have made little attempt to maKe the
assembly language procedure mimic the structure of a procedure generated
by the Pascal Compiler. A complete description of this structure requires
some preliminary discourse.
6.6.1 The Run Time StacK
Automatic stacK exparlsion code maKes procedure entries a little
complicated. To ensure that the stacK segment is large enough before the
procedure is entered, the compiler emits code to 'touch' the lowest point
that will be needed by the procedure. If we 'touch' an illegal location
(outside the current stacK bounds), the MMU hardware signals a bus error
that causes the 68000 to generate a hardware e:<ception and passcontrol to .
arl e>:ception handler. Thiscode, provided by the operatirlgsystem, must be
able to restore the stateof the world at the time ofthe e:<ceptiont and then
allocate erloughe>:tra memory to the stacK that the originalins.tructioncan
be re-e:<ecuted without problem. To be able to bacK IJp, the instruction that
caused the exception must not change the registers,soa TST.W instruction
with indirect addressingisused.
In the normal case, the procedure's LINK instruction should be preceded by
a TST.W e(A7) which attempts to reach the stacK location that can
accomodate the static and dynamic stacK requirementsofthe procedure. If
the static and dynamic stacK requirements of your assembly language
procedure ar·e less than 256 bytes,you can assume that the compiler's fudge
factor will prated the assembly language procedure, so the TST.W can be
omitted. If the requirements are greater than 32K bytes,e(A7) may not be
sufficient because only 16 bits of addressabilityare available (the 68000
does call a 16-bit processor). In this caset the compiler currently emits
code something liKe:
MO'JE. L
SlIB.L
TST .I,oJ

A7,AO
*,Size,AO
(AD)

j#size=dynamic + static needed

If the compiler option D+ is in effect <the default),the firsteight bytes of
the data area following the final RTS or JMP (AO) contain the procedure
name. LisaBug gets the procedure name from thisblocK, maKing debugging
much more pleasant. The following e>:ample is provided to show how an
assembly language progr·ammer can provide Lisa Bug with all the
information itneeds to perform fully symbolic low level debugging.

Al pha draft

6-16

7 January 1983

The Assembler

WorKshop Reference Manual for the Lisa.

ASSEt1BL Y LANGUAGE EXAMPLE
true

DEBUGF .EQU
proc names

all OIN debugg i ng

1,1/

i th

HEAD -- This t1ACRO can be used to signal the
beg inn i ng of an assembly 1anguage procedure '. HEAD
should be used when you do not want to build a stack
frame based on A6, but do want debugging information.
No arguments
.t1ACRO HEAD
• IF
DEBUGF
LINK
A6,#O
.ENDC
.ENDM

fancy NOP used by debugger

TAl L -- Th is t1ACRO can be used as a genera I i zed ex i t
sequence. There are hllo cases. First I if you bu i I d
a stack frame, TAIL can be used to undo the stacK
frame, delete the parameters (if any) and return.
Seco~d! if 'IOU do not want to build a stacK frame
based on A6, this MACRO can be used to signal the
end of an assembly language procedure. In either
case if DEBUGF is true, the Procedure_name
is dropped br the t1ACRO as an 8-charac ter name.
TINa arguments:
1) Number of bytes of parameters to delete
2) Procedure_Name as string exactly 8 characters
.t1ACRO TAl L
UNLK
A6
.IF

RTS
.ELSE
• IF
Xl = 4
t10VE. L (A7)+,(A7)
RTS
.ELSE
t10VE .L (A7)+,AO
#;~1 ,A7
ADD.W
(AO)
JMP
.ENDC
.ENDC

Al pha draft

6-17

bytes of parameters

b;des of parame ters

put return addr into AO
remove params from stack
return to caller

7 January 1983

Workshop Reference' MamJal for the Lisa

. IF

The Assembler

DEBUGF
.ASCI I

~~2

.ENDC
.ENDM
The following example demonstrates the use of the
TAIL macro for the purpose of debugging. The example
assumes th~t you want to build a st~ck frame based
on A6. In a real assembly language procedure the
zeroes be 101,<) I.AJOU 1 d be rep 1 aced by the 1oca 1 ~. i ze and,
parameter size.

.PROC

SIt1PlE ,0

LINK

A6,#0

NOP
TAll

o, ~ SIt1PlE

zero bytes of locals
body of procedure
zero bytes of parameters

. END
These macros ar'e sufficient for the programmer writing small assembly
language routinesto be called from Pascal.
Upon entry to the assembly routine,the stacK is as shown in Figure6-4.

caners StaCk Frane

... ..-------

caners Dynamic Un<

...

Funct1Cn Result

i>rDCeCkae ArgI.ments
statiC Link
Return AdCITesS
DynamiC Unk

I..;..

Local Frane

(A7)

--+

Dyrmrtc Requirements
L

Figure 6-4. The Pascal Run Time StacK
The function result is present only if the Pascal declaration is for a.
function. Itiseitherone or two words. If the resultfitsin a single byte (a
boolean, for example), the most significant half (the lower addressedhalf)
getstheresultvalue.
Parameters are present only if parameters are passed from Pascal. They
are pushed on the stacK in the order of declaration; All reference
parameters are repreE.ented as 32 bit addresses .. Value pa.ra.meters less

Al pha draft

6-18

7 January 1983

WorKshop Reference Manual for the Lisa

The Assembler

than 16 bitsin size alwaysl:JCcupy a fullword.All non-set value para.meters
larger· than 4 bytes are pa.ssed by reference. It is the pr·ocedure's
responsibilityto copy them. All large setvalue para.meters are pushed onto
the stacK by the calling routine.
The static linK is present only if the external procedure's level of
decla.ration is n.ot global. The linK is a 4 byte pointer to the enclosing static
scope.
It is the responsibility of the assembly la.nguage procedure to deallocate

the return addresst the static linK (if any) I and the parameters (if any). The
SP must point to the function result or to the previous top of the stacK upon
return.RegistersD4 through D7 and A3 through A7 must be preserved.ltis
recommended thatyoualsopreserveD3 andA2.
6.6.2 Register Conventions
The following are the registerconverltionsused in the Lisasystem. 1tisthe
responsibilityofthe programmer to preserve these registers.
DO-D2lAO-Al :
D3,A2:
D4-D7/A3 ,A4:

AS:
A6:

SP:

Scratch registers (can be clobbered)
Scratch registers, but should be preserved
. Used for code optimization
Pointer to user globals (must be preserved)
Pointer to base of stack (must be preser'.)ed)
Top of stack

RegistersD3 and A2 may be used at some time in the future by the compiler·
for code optimizationt so the assembly language programmer should
preserve them also.
6.6.3 Assembly Language E:xamples
The following e:·:amples show how to use certain featuresof the assembly
langua.ge.
The first exa.mple illustrates the use of .REF and .DE:F. These two
directives allow an assembly language routine to reference another
asse mbly routirle.
The Pascal hostfile is:
program WasteTime;
procedure Wait (time
ex terna 1 i

integer);

begi n

writeln ('Going to waste some time');
l;.Ja it (50);
writeln ('Finished wasting time');
end.

Alpha draft

6-19

7 January 1983

Workshop Reference Manual for the Lisa

The Assembler

The assembly language file is:

• proc
.ref

IAia it
cycle

.ref
move.l
move.w

more~time
(.=o7):,au

jsr
jsr
jmp

c;/cle
mor-e_time
(aO)

need to use a piece of code
whose entry point is cycle
defined outside procedure wait
another outside procedure
return address in aO
need to wait this many cycles
a parameter for c:/cle

(a7)+,dO

waste more time
return

the subroutine used by wait is defined in the
follolAiing code. this proc could do other things
; besides the cycle routine
.proc
def_cycle
.def
cycle
; cycle visible to other procs
code

can go here

nap

example of aline of code
beginning of the cycle routine
parameter is in dO

c :/C I e

sub
bne
rts

#l,dO
cycle
more code can go here

.proc
elr
add
bne
rts

more_t ime
dO
#2,dO

I,<laste more time
use dO as timer

OJl

• end
The following program illustrates how to pass a Pascal string to an
assembly language program, modify the string ,and returnit. Pascal strings
have their lerlgth stored as the firstbyte in the string.

.proe
move. I
move.l
move. 1

Alpha draft

AsmStr
(A7)+ ,AO
(A7)+ ,Ai
A2,-(A7)

;return address saved in AO
;address of string from Pascal
;save scratch register A2

6-20

7 January 1983

Worl<shop Referer,ce Manual for the Lisa

lea
c 11'.1
move.b
coPY

done

Alpha dra.ft

size,A2
DO

(A2) ,DO

; ge t size of string

(A2)+, (A1)+

jCopy size of string
jdone COPy i og string?
iyes, return to Pasea 1
jone char of string

move.b
subq
blo
mOlJe.b
bra

done
(A2)+, (Al) +
coPY

move .1
jmp

(A7)+ ,A2
(AO)

size .byte
myStr .asc i i

The Assembler

#1,00

jrestore sera tch register
jreturn to Pasea 1

38
/ th is string is from the LISA a.ssembl er'

6-21

7 January19B3

WorKshop

The linKer

User's Guide for the Lisa

Cha.pter?
THE LI N l<E R

........................................................

7-2
7.1 The LinKer
The linKer is a program that .combines object files to create an executable
file.
7.2 Using the linl<er •••....•.....•..••.••....••..•...............•....• 7-3
The linKer is started by pressing ilL" in response to the WorKshop command
prompt. Inputs to the LinKer are object files, command files, or options.

7.3 The linKer Opiions •••.••••••••••.••.••.••.•••••.•••••..••••.••.•.• 7-3
The LinKer options control how a linK is performed. A list of the current
option settings is displayed when you enter a "?" to the input file prompt.

7.4 How do I LinK a Main Program? ••••••••••••••••••••••••••••••••••••• 7-4
A main program is linKed by giving the linKer the object file from a Pascal
program, along' with all assembly language routines, compiled units, and
libraries that the program uses.
7.5 Regula.r and Intrinsic Units •••••• • • • • • •• • • • • •• • • • • • • • • • • • • • • • • • • • •• 7-5
Regular and intrinsic units are both are Pascal units, separately compiled. A
regular unit is linKed with a main program, and becomes part of the
executable file. An intrinsic unit is shared among all programs that use it,
both on disK and in memory.
7.6 The Linker Us ting ......•..•..
7-6
The LinKer listing provides a summary of the linl<ing process and resources
used. Optionally you can request lists of all symbols used.
'.1 •

• • •

•

• • •

• •

•

• •

•

• •

•

• •

•

• • •

• •

•

• •

•

••

7.7 Resolving &:xtemal Names ••••••••••••••••••••••••••••••••••••••••• 7-7
External names are symbolic references to separatly compiled modules. The
linKer maps them to real addresses.
7.8 Module Inclusion . • . . . . . . . . . . . . . . . . . . . .. . . • . . . . • . . . . . .. . . . . . . . . . . •. 7-7
The linKer only includes modules that are actually referenced.
7.9 Segmentation •••.•••
7-7
Segmenting a program allows portions of it to be swapped out of memory when
they are not being used. Segmentation is controled by a combination of
compiler commands and linKer options.
1 I

7.18 Error Messages •••

I' I

I •••••••• I ••• I

I 11 • • 1 • • 1 • • • • • • • • • • • • • • • • • • • I .

• • 1 • • • • 1 • • • • • • •. I • • I • • • • • • • • • • • • • • • • • • • • • • • • •

7-8

There are three types of error messages: warnings, errors, and fatal errors.
They are listed in Appendix A.

Alpha draft

7-1

29 January 1983

Worl<shop

Alpha draft

The Linl<er

User's Guide for 'the Lisa

7-2

29 January 1983

WorKshop

THE
7.1

The linKer

User's Guide for the Lisa

LINKER

The LinKer.
The linKer combines object files. Its input consists of commands and object
files. I1:s output consists of object files, linK-map informatio"n, and error
messages. The output of the Pascal compiler must be linKed with IOSPASLIB
before it can be executed.
Other object files, including intrinsic unit
libraries, and object files produced by the Assembler, can also be linKed into
the output object file.
What the LinKer does is as follows. When a program is compiled into an object
file, it contains the following sorts of things:
• Object code, similar to machine language, that expresses the algorithm of
the program.
• Symbolic (named) addresses of all code whose location was unKnown to the
compiler. These include externally compiled routines (units and intrinsic
units) and the Pascal library support routines (PASLIB).
• Other information to be used by the Linker.
The purpose of the LinKer is to connect up all the necessary things (!inl<ing
them together), and output an object file that can be executed.
The LinKer does this by going through the main program, and, each time it
finds a symbolic address, it looKs up that address in all the units and libraries
it was given as input, and converts the symbolic address into a real address
that will be correct when the program is loaded to be executed.
If the LinKer can't find something that is addressed symbolically, this is an

error. An error message will be printed, indicating the missing module. This
process of finding the real addresses that correspond to the symbolic
addresses is called resolving the external references.
The linKer expects to find the file INTRINSIC.LIB even if you are not using
any intrinsic units. INTRINSIC.LIB is a directory of libraries and intrinsic
units, and includes information for the use of the linKer. INTRINSIC.LIB
defines all the intrinsic units supplied with the WorKshop system.
7.1.1

Creating an Executable File.
To create an executable file, the linKer must have the following inputs:
• the object file from a main Pascal program.
• object files for all external procedures referenced by the main program.
These may be as Pascal units, assembly language routines, or intrinsiC
units defined in INTRINSIC.LIB.
• All units used by the units the main program uses.
• IOSPASLIB to provide the standard Pascal procedures and functions.
The Linker combines these files and creates an executable object file. If it is

Alpha draft

7-3

29 January 1983

WorKshop

User's Guide for the lisa

The linKer

unable to linK these files correctly to create a legitimate output file, the
LinKer will display an error message. If there is an error, the object file
produced is not executable.
When linking a main program, all references
resolved. Partial linKs are not allowed.

to external objects must be

While it is linking the program, the linKer does a "dead codeanalysis" and
does not include any routines that are not referenced. Unnecessary routines
are eliminated from the main prog~am, and from the units and libraries given
as inputs to the linK.
7.2

Using the LinKer.
The LinKer is s"tarted by pressing "L" in response to the WorKshop command
prompt. The LinKer promp"ts you for the input files, the listing file and the
output file. Options may be entered as a response to the input file promp"t.
After all file names and options are entered, the linK begins. This means that
the set of options in effect are the same throughout the linK. l"t is not
possible to change options part way through the linK. When entering an input
file name, it is not necessary to enter the .OEJ extension, the linKer will
provide that for all inputs.
The linKer will accept option commands and input file names from a command
file. A command file is a te>:t file containing the file names and options, one
per line. If there is a blanK line in the file, the LinKer treats this as the
RETURN that Signals the end of the input files. You use a command file by
typing "(" followed by the name of the text file the commands are in. Create
the text file by using the Editor.
The default listing file is the -CONSOLE. You may send the listing to a te>:t
file by entering its name in response to the listing file prompt.
After entering the ouput file name, the linK begins. If no errors occur during
the linK and all external references are resolved, the output file is
executable. A message is printed at the end of the linK to tell you if the
output is executable.

7.3

The linl<er Options.
LinKer options can be entered at any time in response to the prompt for an
input file name. The order in which options are entered is unimportant,
because they have no effect until the linK begins. The last value entered for
an option is the value used when the linK is performed.
A U+" in front of the
Options are represented by a single character.
character maKes that option taKe effect. A "_" sets the linKer so that option
will not happen. In addition to being set on or off, some options have
Numeric parameters can be in either decimal or
. additional parameters.
hexadecimal. Hexadecimal numbers are indicated with a leading "$". The
current setting of all options can be displayed by entering a "?" in response
to the request for an input file.
The linKer options are as follows:

Alpha draft

7-4

29 January 1983

· WorKshop

User's Guide for the Lisa

The linKer

Alphabetical listing of symbols. The default is -A.

Debug inforr:nation.

+H num

+H sets the maximum amount of heap space the Operating
System can give a program before terminating it. Here, as in
the other options, 'num' can be either decimal or hexadecimal.

-Hnum

-H sets the minimum amount of heap space needed by a program.

Copy interface
default is -I.

Location ordered listing of symbols. The default is -L. The
location is the segment name plus offset.

The default is -D.

information

into intrinsic library files.

The

+M from Name toName
+M maps all occurrences of the segment 'from Name' to the
segment 'toName'.
This allows you to map several small
segments into a single larger segment.
You can thereby
postpone the segmentation decision until linK time by using
many segment names in the source code.
NOTE:
Because options have an effect only when the linK begins, it is not
possible to map a segment name to several different names using this
option.

7.4

Production linK. The default is -Po +P produces a 'production'
.OBJ file.
A production object file does not contain
information used by the debugger and the linKer, and intrinsic
unit files do not contain a jump table. The production object
file can be executed, but cannot be handled by the LinKer or the
debugger.

+S num

+5 sets the starting dynamic stacKsi:ze to 'num'. The default is
10000.

+T num

+T sets the maximum allowed location of the top of the stacK to
'num'. The default is 128K.

+ W tells the linKer to get intrinsic unit information from a file
other than INTRINSIC.LIB.

Prints the options available and their current values.

How do I LinK a Main Program?
A main program consists of a Pascal program linKed with all routines
necessary for it to run. A main program is the only type of executable object
file produced by the linKer. To linK a main program you must have the
following:
o A compiled pascal PROGRAM

Alpha draft

object file.

7-5

29 January 1983

WorKshop

User's Guide for the Lisa

The LinJ.<er

• Object files for all the units the program uses. This includes files for
regular units and assembly language routines. Any intrinsic units used
must be defined in INTRINSIC.LIB •
• IOSPASLIB.
When you have all the above files, proceeq as follows:

Execute the Linker by pressing "L" when the WorKshop command prompt
is displayed. The Linker will display a header and asK you for an input
file.

Enter any desired options. See section 7.3 in this chapter for more
information. Press RETURN' after each option entered.

Enter the file names for' all the object files, pressing RETURN after
each one. The file names can be entered in any order. Do not enter the
.OBJ extension, the linKer automatically appends it.

Press RETURN to indicate the end of the input files.

ihe LinKer prompts you for a listing file. Enter the file name desired,
or press RETURN to accept the default of displaying the listing on the
-CONSOLE.

The LinKer prompts you for the output file. Enter the name of the
executable file you want produced. Do not enter the .OBJ extension,
that will be supplied automatically.

The linKing process begins when you press RETURN after entering the output
file name. If the linK is successful, the message "Output is executable" will
be displayed. If the linK is not successful, error messages will be displayed.
7.5

Regular and Intrinsic Units.
The two types of units are regular units and intrinsic units. Both of them are
separatly compiled code modules that may be used by a main program or
another unit.
The syntax of a Pascal unit is explained in the Pascal Reference
the Lisa.

Manual for

A regular unit is combined with a main program by the Linker and included in

the resulting object file. An intrinsic unit, on the other hand, is stored
separately on the disk, and loaded at run time.. Thus only one copy of an
intrinsic unit is Kept on the disk, no mater how many main progra.ms use
routines in it. In addition to being shared on the disK, an intrinsic unit is also
shared in memory.
NOTE
In the current implementation, there is no provlslon for creating
intrinsic units. Only intrinsic units supplied by Apple can be used.
7.5.1

How do I use a Regular Unit?

Al pha draft

7-6

29 January 1983

WorKshop

User's Guide for the Lisa

The linKer

A regular unit is a separately compiled segment of code. Ii is written in
Pascalt compiled t and code generated. See the Pascal Reference Manual for
the Lisa for information on how to write a unit. See Chapter 5 in this manual
for information on compiling the unit.
After you have created a unitt the routines in it may be accessed from any
other program or regular unit you write. The linKer is used to combine a main
program with all units it uses. The result is an executable object file
containing all the needed routines.
To use regular units with a main programt follow the procedure in section 7.4.
As inputt you must give the linKer:
• The object file of the main program.
• The object files of all units used by the ma.in program.
• The object files of all units used by other units.
• IOSPASLIB.
The linKer will combine all these object files into an executable object file.
It will also do a "dead code analysis" to eliminate any routines that are not
used t thus preventing the object file from becoming any larger than is
necessary.
When regular units are used by more than one main programt a separate copy
of each routine used is stored in each executable object file. This "waste" of
disK space and memory can be prevented by using intrinsic units instead.
7.6

The linKer Listing.
A listing is produced each time a program is linKed. This listing can be sent to
a file. or displayed on the console (the default). The +A option will give you
an alphabetical list of the symbols (procedure names) used in the linK. The +l
option gives you a list of the names in order of their location. The listing is
produced in stages. as follows:
1.

The input files are read t and a summary of the resources used is printed.

The linKing process begins. Information about the size of each segment
is printed.

Errors are reported, and you are told if the output is executable or not.

If you requested optional listings, they will also be printed. An example of a
LinKer listing with no options requested is shown in Figure 7-1.

linkl!rlisting

Alpha draft

7-7

29 January 1983

WorKshop

User's Guide for the Lisa

The linKer

Figure', 7~ 1." A Linl<er
7.7

Listing.

Resolving External Names.
An ex1:ernal name is a symbolic entry poin1: in1:o an object module. All such
names are visibl,eat all times-'"'"there is no no1:ion of the nesting level of an
external name. Exterrlal names can be either global or local. A local name
begins with a $ followed by 1 to 7 digits. No other characters are allowed. A
global name is any name which is not a local name.
The scope of a global name is the entire program being linKed. Unsatisfied
references to global names are allowed. Only one definition of a given global
name may occur in a given linK. (The one exception to this is that the LinKer
will accept duplicate names where one instance is in a main program or
regular unit, and the other is in an intrinsic library file. In this case, a
warning is issued, and the entry in the main program or regular unit is used.>
The scope of the local name is limited to the file in which it resides~ When a
linK is done, global names are passed through to the output file unmodified,
but local names are renamed so that no conflicts occur between local names
defined in different files. All references to a given local name must occur
within the same input file.

7.S

Module Inclusion.
There are two di Herent cases of what modules the linKer includes in the
output file. When linKing an intrinsic unit, all code modules in the unit are
included. When linKing a main program with regular units, the linKer does a
dead code analYSis and does not include any modules that are not used.

7.9

Segmentation.
Segmenting a program maKes i1: possible for portions of the program that are
not being used to be swapped out to disK, thus maKing better use of memory.
The way a program is segmented will have important effects on its
performance.
Segmen1:ation is controlled by two things:
• The $6 Compiler command,
modules.
Ii

that assigns segment names to source code

The +M linKer option, that allows you to remap compiler segment names
into new segment names.

The usual stra1:egy for segmenting a program is to use. the $8 compiler
command to divide 1:he code into many small segments, then to map these
segments into a few larger physical segments with ttle +M Lini<er option.
This will allow you to change the segmentation of the program by ~st
relinKing it. The segmentation can then easily be adjusted to produce the

Alpha draft

7-9

29 January 1983

WorKshop . User's Guide for the Lisa

The linKer

best swapping characteristics.
Assembly language routines are by default placed in the blanK se·gment. You
can use the .SEG directive to specify another segment, or change the
segment with the ChangeSeg utility. See the Chapters 6 and 10 for more
information.
7.10

Error Messages.
The linKer produces three different types of error messages, depending on
the severity of the error it encountered.
The first, and least severe type of message, is called a warning. A warning
message is given when the linKer detects a condition that is potentially
dangerous, but not definitly an error. A warning message always begins with:

*** Warning
I f the warning

message occurs while entering a command or file name, you
may simply reenter the command correctly, and the linKer will proceed as
though nothing had happened.

The second type of message is called an error. An error means that the
linKer has discovered a condition that maKes it impossible to complete the
linK successfully. The linK process is continued, so that any further errors
can be discovered. An error message begins:

*** Error
A fatal error is a condition that maKes it impossible for the linKer to
continue the linK. The linK is terminated immediatly, and a message is
displayed beginning:

***

Fatal Error

A complete list of all linKer messages is given in Appendix A.

AI pha draft

7-9

29 January 1983

WorKshop

User's Guide for the Lisa

The Debugger

Chapter8

THE DEEUGGER

8.1 The Debugger ••.•.•.•.•••••••••••••••••••••••••••••••••••••••••••• 8-2
The Debugger allows you to examine and modify memory, set breaKpoints,
assemble and disassemble instructions, and other functions for run-time
debugging.

8.2 Using the Debugger ..... . . . . . . . . . . • . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. 8-2
E:nter the debugger by pressing D in response to the command prompt, or by
pressing the NMI Key. The debugger prompt 0) indicates that it is ready to
accept commands.
8.3 The Debugger Commands ••• • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • •• S-S

Commands are available for assembly and disassembly of instructions,
displaying memory and registers, setting breaKpoints and traces, memory
management, and base conversions.

8.4 Summary of Debugger Commands

•••••••••••••••••••••••••••••••••• 8-10

Al pha draft

8-1

27 January 1983

WorKshop

User's Guide for the Lisa

AI pha draft

The Debugger

8-2

27 January 19B3

WorKshop

User's Guide for the Lisa

THE

The Debugger

DEBUGGER

8.1 The Debugger.
The Debugger allows you to examine and modify memory, set breal<points,
. assemble and disassemble instructions, and perform other functions for
r·un-time debugging.
Procedure names are available to the debugger for program units compiled
with the D option on. The debugger uses the symbolic names wherever
appropriate.
The debugger's symbol table combines the user symbol table and the
distributed procedure names. The user symbol table contains symbols the
user defines while using the debugger and the predefined symbols for
registers. Each entry contains twelve bytes. The first eight bytes are the
symbol name, and the last four bytes are the symbol's value. Section 6.4 in
this manual contains more information about the run-time environment of
programs.
8.2

Using the Debugger.
Type D to the command prompt to invoKe the debugger. It asKs:
Debug what OS file?
Enter the name of the object file you want to debug. It will be Run with a
breaKpoint at the first instruction that will drop you into the debugger
The debugger command prompt is '>'. The default radix is
immediately.
hexadecimal.
Another way of getting into the debugger is by pressing the NMI (non
masKable interrupt) Key which is the "_" Key in the top row of the numeric
Keypad.
When you get the command prompt, the debugger is ready to accept commands
that allow you to:
• Display and set memory locations
• Set and display registers
• Assemble and disassemble instructions
• Set breal<points, patch points, and traces
• Manipulate the memory management hardware
• Set up timing bucKets for ex ecution timing
• Perform utility functions including:
• symbol and base conversion
• move the debugger window

8.2.1

Examples of Using the Debugger.
This section gives examples of how to use the debugger.

AI pha draft

8-3

An explanation of all

27 January 1983

WorKshop

User~s

Guide for the Lisa

The Debugger

debugger commands is given below in Section B.3. A summary of all debugger
commands is given in Section B.4.
I f you type a file name to the prompt from the Debug command, the debugger
star1:s up wi1:h the program counter at the start of the program. To see one'
instruction disassembled (say at 32F96), type
>ID 32F96
ID stands for Immediate, Disassemble. Each subsequent ID command, if given
without any address, disassembles the next instruction found. In addition to
printing the value of each byte, the debugger prints the ASCII equivalent of
that value, if a printable one exists. If none exists, it prints a period •...
To disassemble 20 consecutive addresses, type
>IL
IL <Immediate Disassemble Lines) can also be followed by an address.
Subsequent IL commands disassemble successive bloc\(s of 20 consecutive
locations in memory.
If the object file being examined was compiled wi1:h the D+ compiler option,

the procedure names are available in the debugger and can be used in any
expressions. For example,
}IL Foo 5
(

disassembles the first 5 lirres of procedure 'F 00'.
)BR Foo+40
sets a breaK point 40 bytes into procedure 'Foo'.
You can also use labels in immediate assemblies:
>sy Ken 6000
)A Ken NOP

assembles a MOP instruction at the address 'Ken', which in this case is 6000.
>A 6000
>Rich: JMP $100

><RETURN>
enters the immediate assembler
assembles a JMP instruction.

S.3

at 6000, defines the label 'Rich',

The Debugger Commands.
This section gives the definition of each debugger command.
are grouped together according to function.

S.3.1

I>efirdtions.
Constant
SConstant
&Constant

Alpha draft

and

The commands

A constant in the default base.
A hex constant.
A decimal constant.

8-4

27 January 1983

WorKshop

User's Guide for the Lisa

The Debugger

'ASCII String'
Name
e:xpr

An ASCII string.
A symbol in the symbol table.
An expression. Expressions can contain names, regnames,
strings, and constants. Legal operators are + - * /.
Expressions are evaluated left to right. * and / taKe
precedence over + and -. (and ) can be used to indicate
indirection. < and > can be used to nest expressions. In
those cases where an odd value is probably a mistaKe, the
debugger warns you that you are trying to use an odd
address. If you decide to go ahead, it subtracts one from
the address given. If the compiler option D+ is used,
procedure names are legal in expressions.
Exprlist
A list of expressions separa.ted by blanKs.
The name for any of the 68000 registers, a.s follows:
Register
D0 ••D7 are the. data registers, A0 •• A7 are the address
registers, the program counter PC, the status registers
SRI US, or 5S. Note that A7 is SP (the stacK pointer).
RegName
RD0 ••RD7, RA0 .. RA7, PC, US, or SS. A predefined symbol
in the symbol table with a value set by the debugger. The
value is equal to the value of the register in question. The
debugger automatically updates the values of these
symbols. The 'R' is appended to distinguish the register
names from hexadecimal numbers.
8.3.2 Display and set memory locations.
The following commands a.re used to display a.nd set memory locations.
SM exprl exprlist
Set memory with exprlist starting at exprl. SM assumes that each element of
e:<prlist is 32 bits long. To load different length quantities, use SB or SW
described below. If the expression given ls10nger than 32 bits, SM taKes just
the upper 32. For example, if we asK 1:he debugger to:
SM 1000 'ABCDE

it deposits 1:he ASCII equivalen1: of 'ABCD' starting at 1000.
SB expr1 exprlist
Set memory in bytes with exprlist starting at exprl
SW exprl exprlist
Set memory in words with exprlist star1:ing at expr1
Sl expr1 exprlist
Set memory in long words with exprlist s1:arting a.t expr1. For example,
Sl 100 1
is equivalent 1:0
SM 100 0000 0001
DM expr
Display memory. Display 16 bytes of memory s1:arting at expr. DM RA3+10,
for example, displays the contents of memory from 10 bytes beyond the

Alpha draft

8-5

27 January 1983

WorKshop

User's Guide for the Lisa

The Debugger

address pointed to by A3. DM (110) displays the contents of the memory
location addressed by the contents of location 110.
DM expr1 expr2
Display memory. If expr! < expr2, then display memory from expr1 to expr2.
Otherwise, display memory for expr2 bytes starting at exprl.
DB expr
Display memory as bytes.
DWexpr
Display memory as words.
DL expr··
Display memory as long words.
JiB starting_addr count data
Jiind Byte. Find the byte or bytes 'data' in memory between 'starting_addr'
and 'starting_Addr'+'count'.

S.3.3

JiM starting_addr
Jiind Memory.

count data

JiW starting_addr
Find Word.

count data

JiL starting_addr
Jiind Long word.

count data

Set and display registers.

TD
Display the Trace Display at the current PC. An example of the trace display
is shown in Figure 8-1. It shows the instruction executing at the time the
program was interrupted, the current value of all the registers, and the
current domain and process.
tracedisplay

-Jiigure S-1.

-The Trace

Display.

register
Display the current value of the register. 00, for example, is a command to
the debugger to displa.y the current value in the register D0. RD0, on the
other hand, is a name automatically placed in the symbol table to give you a
handle on the contents of De in an expression. Thus, to display the current

Al pha draft

8-6

27 Jariuar)' 1983

Workshop

The Debugger

User's Guide for the Lisa

value in the D0 data register, type the command D0. To display the
instruction pointed to by the A0 address register, type the command ID RA0
<Immediate dissassemble at the address RA0, which is predefined to be the
contents of the A0 register)
register expr
Set the register to expr. For example, to set register- D3 to zero, type D3 0.
8.3.4

Assemble and disassemble instructions.
These commands are used to display code in assembly language format, and to
enter code in the form of assembly language statements.
A expr statement
Assemble one or more assembly language statements (instructions) starting
at e>:pr. You can continue assembling instructions into consecutive
locations, pressing Re:TURN· after each statement. Type just Re:TURN to
e>:it the immediate assembler. Note that the immediate assembler cannot
assemble any intrinsic unit instructions, but they will be correctly
disassembled. Code segments may be write-protected, which will prevent
you from assembling instructions into them. This can be overridden with the
WP 0 command to disable write protection.
A expr
If you use the form A expr, the debugger prompts you for the statement to be

assembled.
ID
Disassemble one line at the ne){t address
ID expr
Disassemble one line at expr
IL
Disassemble 20 lines at the next address
IL expr
Disassemble 20 lines starting at expr
IL expd expr2
Disassemble expr2 lines starting at expr1
IX statement
Immediate execution of a single instruction.
this operation.
8.3.5

The users PC is not changed by

Set breaKpoints and traces •
. These commands are used to trace program execution.

BR
Display the breaKpoints currently set. You can set up to 16 breaKpoints with
the debugger. Break points are displayed both as addresses and as symbols.
An asterisK marKs the point of the breaKpoint in the disassembly.
SR exprlist
Set each breaKpoint in exprlist. Symbols are legal, of course, so we can:

Alpha draft

B-7

27 January 1983

Worl<shop

The Debugger

User's Guide for the Lisa
SR Ralph+4
if Ralph is a Known symbol.

Expressions can be of the form:
pp:aaaaa
where pp is the process number, and aaaaa is the address in that process
where you want the breal<point set. If the process number is 0, the breaKpoint
is set in system code in domain 0. If no process is given, the current process is
assumed. The current process is shown in the TD display described above.
Sreal<points' cannot be set on intrinsic unit instructions.
CL
Clear all breal<points
CL exprlist
Clear each breal<point in exprlist
G

Start running at the current PC
G expr
Starting running at expr

Trace: one insiruction at the current PC
Texpr
Trace one instruction at expr
SC expr
StacK Crawl. Display the user cal1 chain. e:xpr sets the depth of the display.
It can be omitted.
RS
Reboot. This command should not be used while you are in the WorKshop.
Lisa is reset.

The

procedure name
This calls a user procedure or function. It is the users responsibility to save
and restore registers and push any necessary parameters.
I f you want
execution to stop upon return, you must set a breaKpoint on the current PC.
For example:
SR PC
IX MOva:M.L

set breaK point on PC.
save registers.
; push params if needed.
FOO
i call procedure FOO.
IX MOVe:M.L (A7)+,D0-A6
i restore registers.
Ct PC
j remove breaK point.
A function can be called in a similar manner. Remember to allocate space for
the function result before pushing any parameters. Use either CtR.W -(A7)
1'0 CLR.L -(A7).

Alpha draft

D0-A6,-(A7)

i
i

:::-8

27 January 1983

l,..}orKshop

User's Guide for the Lisa

The Debugger

A procedure that may need to be called is OSQUIT. It exits from the OS. We
reccomended' that you avoid this whenever possible.
8.3.6

Manipulate the Memory Management Hardware.
These commands change the memory management hardware of the Lisa. More
information on the memory managment hardware can be found in the Lisa
hardware manual. CHECK NAME.

L? expr
Convert logical address to physical address.
DO expr
Set the SgGi/SgG2 bits. These bits determine the hardware domain number.
If the Status Register shows that you are in supervisor state, then the
effective domain is zero, and the domain number returned by the debugger is
the domain that would be active if the SR were changed to user state.

\oJp 00r 1
Diable (e) or e:nable

(1)

l,..}rite Protection.

The default is i.

MM start [end_or_cDuntJ
11M with one or two arguments displays information about the MMU
registers. The second argument defaults to 1. If the starting address is
greater than the second argument, the second argument is a count of the
number of 11MU registers to be displayed. If the starting address is less than
the second argument, the second argument is the last register displayed.
MM 70
displays
SegmentE70J Origin[000J LimitC00J ControHCJ
These values are the Segment Origin, Limit, and Control bits stored by the
hardware for each MMll register. As can be seen from a careful perusal of
the hardware documentation, a Control value of C means the segment in
question is unused (invalid). If the Control value is valid (7, for e>:ample), the
debugger also displays the Physical Start and Stop addresses of the segment.
MM &100 8
displays the MMU register
register 64 (decimal 100).

information

for the ::: registers

starting

MM num org lim cntrl [end_or _countJ
The MM command followed by four arguments sets the MMU information for
segment 'num'. The Origin, Limit, and control bits can be changed.

MM 70 100 ff 7
sets the Origin of segment 70 to 100 and the control bits to 7 (a r·egular
segment). The segment limit of -1 maKes the segment 512 bytes long.
S.3.7

Timing Functions.
The debugger allows you to create up to 10 timing bucKets for measuring
e>:ecution times.
Using the microsecond
timer in Drivers, time is

AI pha draft

8-9

27 January 1983

WorKshop

User's Guide for the Lisa

The Debugger

accumulated in each bucil;et and saved along with a count of the number of
times the bucil;et was entered.
Typically, this would be done as follows:
1.

Enter the debugger for a given process and create one or more timing
bucKets with the TB command.

Set

Go.

When the breajl;point
command.

Use the End Timing (E1) command to remove all timing bucKets.

a: breaK point to stop execution at some

pOint~

is reached, print the timing summary with the PT

The timing commands are as follows:
B1 expr
Begin timing. bpI' specifies the process number. If the B1 command is not
given,· the current process is assumed. A process number of 0 can be used to
indicate domain 0.
1B addr1 addr2
A timing bucil;et is created from addr1 to addr2.

PT
Print timing summary. There are five columns. printed:.
1.

2.
3.
4.
5.

Bucket number
Total time in this bucKet.
Number of times this bucKet was entered.
Starting address for this bucKet.
Ending address for this bucKet.

ET
End timing. This command prints the timing summary and removes all the
timing bucKets.
KB expr
Kill BucKet. This can be used to remove a single bucKet.
of the bucket to remove.

Expr is the number

Reset timers. This resets the timing and count tables while leaving the
bucKet definitions intact.
Note that all addresses are in the same process. The process number is
defined by either the BT command or the first TB, PT, KEf or RT command. If
the process number is not given in the ST command the current process is
assumed.
S.3.S

Utility functions.
including:

o symbol and base conversion

Al pha draft

8-10

27 Janua,..y 1983

WorKshop

The Debugger

User's Guide for the Lisa
o moving the debugger window
o Setting the NMI Key

8.3.S.1

Symbols and Base Conversion

SY
Display the values of all symbols
5Y name
Display the value of the symbol name
5Y name expr
Assign expr to the symbol name

CV exprlist
Display the value of each expression in hex and decimal.

SH
Set the default radix to hex
5D

Set the default radix to decimal
Moving the Debugger Window:
P expr
Set port number to expr. Valid port numbers are:

8.3.8.2

Lisa Keyboard· and screen (default)

UART Port A (farthest from Power Supply)

UART Port B

If you move the port to a UART t you must have a modem eliminator connected
to that port.

RS
Display the patch Return address Stac\(
8.3.8.3
NM

Setting the NMI key: .

Displays the Key code for the NMI Key.
NM expr
Sets the NMI Key to be Key code expr. A value of zero disables the NMI Key.

For example:
>NM $21

Sets the NMI Key to be he>: 21t which is the "_" Key in the top row of the
numeric Keypad.
8.4

Summary of the Debugger Commands.
procedure name
Call the procedure.
register
Display the current value of the register.
register expr
Set the register to expr·
A expr statement

Al pha draft

3-11

27 January 1983

WorKshop

User's Guide for the Lisa
A expr
BR
BR exprlist
BT expr
CL
CL exprlist
CY exprlist
DB expr
DL expr
DM expr1 expr2
DO expr
DR
DWexpr
ET

FB starting_addr count
FL starting_addr count
FM starting_addr count
FW starting_addr count
G
G expr
ID
ID expr
IL
IL e>:pr
IL expr1 expr2
IX statement
KB expr
L? expr
MM expr1 expr2
MM num org lim ctrl
MR
NM
NM expr
P expr
PT
RB
RS
RT
SB expr1 exprlist
SC expr
SD

SH
SL expri exprlist

Alpha draft

data
data
data
data

The Debugger
at
Assemble one statement (instruction)
expr.
Display the breaKpoints currently set.
Set each breaKpoint in exprlist.
Begin timing process expr
Clear all breaKpoints
Clear each breaKpoint in exprlist
Display the value of each expression in hex
and decimal.
Display memory as bytes.
Display memory as long words.
Display memory.
Set the SEG1/SEG2 bits.
Display index or ranges of dump RAM.
Display memory as words.
End Timing - print summary and remove
bucKets
Find Byte.
Find Long
Find Memory
Find Word
Start running at the current PC
Starting running at expr
Disassemble one line at the .next address.
Disassemble one line at expr
Disassemble 20 lines at the next address
Disassemble 20 lines starting at e>:pr
Disassemble expr2 lines starting at expr1
Immediate e>:ecution of one instruction
Kill BucKet ex pI'
Convert logical address to physical address.
Display MMU information
Set MMU information
Set a value level #5 interrupt on a word
change.
Displays the Keycode of the NMI Key
Sets NMI Keycode to expr
Set port number to ex Pl'.
Print timing summary
Reboot.
Display the patch Return address StacK
Reset timers
Set memory in bytes with exprlist starting at
expri
Stadt; Crawl.
Set the default radix to decimal
Set the default radix to ·hex
Set memory in long words with expr1ist
starting at expr1.

8-12

27 January 1983

WorKshop

User IS Guide for the Lisa

8M expr1 exprlist
SWexpr1 exprlist
8Y
5Y name
5Y name expr
T
T expr
TB addr1 addr2
TD
WP00rl

Alpha draft

The Debugger

Set memory with e>:prlist starting at expr1.
Set memory. in words wfth exprlist starting at
expr1
Display the values of all symbols
Display the value of the symbol name
Assign expr to the symbol name
Trace one instruction at the current PC
Trace one instruction a.t expr
Create Timing BucKet from addri to addr2
Display the Trace Display at the current PC
Diable (0) or e:nable (1) Write Protection.

3-13

27 January 1983

WorKs!1.op Reference Manual for the Lisa

Using E:<ec Files

Chapter9
USINGB:Xa:C FILE:S
9.1 8:}(ecfiiles .•...........•..••...••.••..•••.•....•..••...••.••........•..•. 9-3
E>:ec filesare scenariosofcommands to be automa.tica.lly performed by the
WorKshop system. They can use parameters, and conditional e>:ecution.

9·,2 B:xec File Sta.tements ..•.......•.......•...•.......••.••...........•...• 9-3
E}:ec file statements are of twa types: normal lines,tha.tcontain Worl<shop
commands, and exec command lines, that tell how to process the exec file.
8:>:ec command lines include lines to: set para.meter values, perform input
and output, and to control conditional e}:ecution.
9.3 Using Exec Files ........................................................ 9-10
Exec files are inVOKed using the WorKshop Run command. ThisinvoKation
lirle can set the values of parameters, as well as select ell, ec options.

9.4 B:x ample Exec Files .•....•..•.....•..........•........................• 9-14
This section contains e:<amples of e}:ec files.

9.S E:(ec File Programming Tips .......................................... 9-18
Thissectioncontains tipson how to'Nrite el{eC files.
9.6 Exec FileErrors ••............•......................................... 9-18

Al pha draft

9-1

7 February 1983

WorKshop Refer'erlce Manual for the Lisa

Using 8:>:ec Files

AI pha draft

9-2

7 February 1983

Worl<shop Reference Manual for the Lisa

Using

S:~·::ec:

Using E>:ec Files

Files

9.1 Exec Files

E>:ec files are scenarios of commands to the worKshop system. They are
contained in a te:<t file~created with the B:ditor~and are el<ecuted with the
Run command. They consist of the actual characters you would type to the
WorKshop to perform the function you want,interspersedwithspecial e>:ec
file commands that allow you to use parameters and conditions to vary
some portions of the scenario.
In its simplest form, an exec file contains the charader's you would pressto
perform the desired operation. Fore:<ample~ to compile a Pascal program,
the exec file would contain:
Pmyprog
The P invoKes the Pascal compiler, myprog is the name of the source file.
This could be followed by further lines to Generate, linK, and Run the
program.
Special e:<ec file commarlds allow you to use parameters arid conditionally
perform the Worl<shop commands. This would allow you to setup arl e>:ec
file to compile, Generate, and optionilly linK any Pascal program. Such an
el<ec file isshown in Figure9-1
·$EXEC
.$ { Th i s exec f i 1e comp i I es and Genera tes a Pasca 1 program. )
$ { I f the second parame ter is L (or l) the program is L i nl<ed )
·$1 F /~O "THEN {no parame ter en tered}
$l~RITE 'Comp i 1 e what f i I e?1
$READLN XO
·$ENDIF

PXO
{no I isting file}
{ de +au 1 t I -c ode f i Ie}

GXO
{defaul t object f i 1e)
$ I F UPPERCASE CI, 1) = I L' THEN

LXO
IOSPASLIB
{ end of 1 i nl<er inpu t }
{nolistfile}
~{O{ output f i 1 e name)
$ENDIF
'$ENDEXEC

Figure 9-1. Example Exec File
9.2 Exec File Statements
E>:ec file statements are contained on one line. There are two typesofe:-:ec
file lines, e:<ec command lines, and normal lines. Normal lines contain

Al pha draft

9-3

7 F€-bruary 1983

WorKshop Referenc:e Ma.nual for the Lisa.
commands to be processed by the WorKshop system. E>:ec command lines
handle the other featuresof e:{ec filestsuch as parameters and conditional
statements.
you may use up to 10 parameters in an e:< ec file t numbered as %0 through
%9. These receive their values from the invocation ofthe e>:ec file,orthey
are aSSigned values during the exec file execution. When a parameter
appears in a normal linet it is replaced by the string value of that
parameter. These parameters can be used both as inputs to the exec file
and astemporary variableswithinit.
Exec command lines startwith a $; they control the operation of the restof
the exec file. 8::·:ec command lines are free format, as long asthe order of
thier' elements is preserved. Any number of blanKs can occur before any
element of a command line.
Normal command lines contain commands forthe WorKshop system. These
lines are sentto the WorKshop exactly as they appear. Any e:dra blanKs will
be sent to the WorKshop and will be treated exactly as if you had typed in
those blani-<s.
Comments are delimited by curly braces ({and ). They can appear in either
a normal or an e>:ec command line. Comments are completely removed
fr'om rlormallines.
The tilde r isused as a literalizing character in normal lines. Itpassesthe
following character through without processing it. This allows you to pass
$, %, and -{ to the WorKshop syste m wi thout having the m be interpreted as an
exec command t a parameter, or a comment. Tilde can be passed ,3,s,,,w
o

,,)

The followingisa de scription of each e:{ec command line type.
9.2.1

Beginning and e:nding e:xec Files
The gener'al form of exec fHesis they must begin with a "Se:XEC line and
must end with a I/Se:NDEXEC" line. The e>:ceptions to this basic rule (for
those miscreants who embed their e>:ec filesin their program sources)are:
(1) one line ofte>:t may preceed the "$EXEC" line ifthe "I"invocation option
is used, and (2) any amount of text may follow the "$ENDe:XEC" line/butit
will be ignored.
1/

9.2.2 Setting Parameter Values

You can setparametervaluesinane>:ec file by usingtheSETand DEFAULT
operations. The REG.UEST operation prompts the user for the value of do
parameter.
SETand DEFAULT
The SE T and DE F AUL T com mands provide a way of changing the value of a
parameter inside of an e:<ec file. The form of thesecommands is:
$

SB:T <%n> TO <strexpr>

and
$

Alpha draft

DEFAULT <%n> TO <strexpr>

9-4

7 February 1983

WorKshop Reference Manual for the Lisa

Using E>:ec Files

where <%n> is a parameter reference and <stre:<pr> is a str-inge:·:pressionas
described in the followirlgsectiorl.
The effect of the SE:T command is to change the value of the specified
parameter to the value of the given string e:<pres.sion. The effect of the
DEF AULT command is similar to that of the SET command, however, the
assi.grlmerlt only taKes place if the value of the specified parameter is the
null string when the DE FAULT command is encountered. Thus, this
command can be used to supply default values to parameters that have
been left unspecified or empty in the e:<ec invocation line.
RE:QUEST
The REG.UE:ST command provides a way to prompt for values from the
console. Itsform is:
$

REG.UEST <%n> WITH <strexpr>

The REG.UE:ST command will print the given string e>:pression to the
console and will read a line from the console which it will assign to the
specified parameter. Thus the <str e>:pr> is the prompt that you will
requestwith.
9.2.3 Input and Output
Input to an e:{ec file isrequestedby the RE:ADLN of READCH command.
The WRITE: and WRITELN commands allow you to output values.
READLN and RE:ADCH
The READLN and RE:ADCH commarlds allowe>:ec filestoreadinte:dfrom
the console and to assign it to a parameter variable. This mechanism may
be used to obtain parameter values, to obtain values to control conditional
selection, to pause until the user indicates to continue, or for any other
purpose. The form of these commands is:
$

READLN <%n>

and
$

RE:ADCH <%n>

READLN will read aline from the console and will assignitto the specified
parameter. READCH will read a single character from the console (if
<return>is typed that character will be a bla.nK).
WRITE and WRITELN
The I..JRITE and WRITE:LN commands allow e:{ec files to write te>:t to the
console screen. This te>:t may be used for informatory messagestprompts,
orforany other purpose. The form of these commands is:
$

l..JRITE C (stre>:pr> C , <stre:<pr} lIE- J

and
$

Al pha draft

WRITE:LN C <stre>:pr} C , <strexpr> J* J

9-5

7 February 1983

Using E>:ec Files

WorKshop Refer'ence Manual for the LisC\.

That is, these commands taKe an arbitrary number of str'ing e>:pressions,
:.eparated by commas, as arguments. The stringsare writtento the curr'ent
console line, and in the case of WFHTELN a final carriage returnis written.
9.2.4 Conditiona.l sta.tements
Conditional statements allow you to perform certain commands depending
on the conditions at the time the e){ec file is r·un. These conditions can be
ba.sed on the value of parameters and on the filesavailable to process. The
condition is stated irt the for'm of a boolean e)·:pression,a.nd can inr:lude
builtin boolean functions to determine the condition of files.
The IFStatement
The IF, ELSEIF ,ELSE a.nd ENDIF commands allow conditional selection in
e>:ec files. The synta:< of these commands is as follows:
$
[$
[$
$

IF <bool e>:pr} THE N
<stuff>
ELSEIF (boole>:pr> THEN
{stuff> J*
ELSE
{stuff> J
ENDIF

where <bool e>:pr> is a boolean e>:pression as described in the following
section and <stuff> is made up of arbitrary normal and command lines
(other than commands that 'would be a partof the current IF construct). Trte
c. •• J*" constructabove indicates that zero or more ELSEIFcommands may
appear between the IF and the ENDIF commartd, while the" [ .•• J"indicates·
that zero Drone ELSE command may appear justbefore the ENDIF.
II

The IF construct is evaluated in the usual way. Fir:.t, the boolean
e>:pression on the IF command it':;elf is evaluated; if it is true then the
<stuff>between the IF and the ne>:t ELSEIF(ifany) or ELSE (itany) or E NDIF
is selected; otherwise it is not selected. All remaining parts of the IF
construct up to the E NDIF will be parsed but will nc,t be selected once one
of the (bool e>:pr>s is true and i tscorresponding <stuff>is ·:;elected. To say
that <stuff>is selected means that any normal line:. will gerterate te:dand
that any command lines will be processed. Conversely, to say that <stuff>
is not selected means that any nor'mal lines will not generate te:d and that
command lines will be parsed (for correctness) but not e:<ecuted. If the
<bool e>:pr> on the IF is nc,t true thert the fc,llowirlg ELSEIFor ELSE will be
processed. If an ELSEIFis ne>:t, its <bool e:·:pr) will be evaluated, and, if
true, its following <·:;tuff> will t,e selected and the remainder of the IF
construct will not be selected. Processing of the IF construct continues
urttilone of the <bool e:·:pr>s art art IF c,r ELSEIFistrue or until the E NDIF is
reached. If no(bool e:<pr'> is true before the ELSE (if any) is reached, its
<stuff>willbe selected.
IFconstructs may be nestedwithineach otherto an arbitraryleveL

Al pha. draft

9-6

7 Februa.ry 1'183

WorKshop Reference Manual for the Lisa

Using E:<ec Files

BooleanExpressions--comparison arid logical operators
Booleanse:<pressions«bool e>:pr>s) enable you to testof string values and
checK properties of files. The grammar for boolean expressionsis as
follows:

<bool ter·m> C(binarylogic op> (bool e>:pr) J*

<binar},logic op>

AND
lOR

(bool term>

<bool factor>
I ( <bool e:<pr> )
I NOT ( <bool expr) )

<stre:<pr> <strop> <stre>:pr>
I <boolfunction>

<strop>

=
I <>

. The basic element of a boolean e>:pression (a <bool fa.ctor» is either a.
boolean function (see the ne>:t section) or a. string comparison, testing for
equality or inequality. These basic elements may be combined using the
logical opera tor-sAND, OR a.nd NOT ,wi th par'enthesesused forgroupirlg. All
these opera torsfunction in the usual way.
Boolean Functions-- EXISTS and N8:WER
Several functions returning boolean results are provided for use with the
conditionalcontructs.
The EXISTS function a.llows you to determine whether a. file or volume
e>:ists. The function has the following form:
B:XISTS ( <stre>:pr) )
where <str e:<pr) is a. string ex pression whose value is the name of a file.
Typically this <str e>:pr} will be an e:<panded string constant (discussed
above),such as"% 1.obj".
The NEWER function allows you to determine whether one file is newer
than another file, that is, whether its last-modified date is more recent
than the la.st-modified date of arlther file. The function has the following
synta:<:
NB:WB:R ( (stre:<pr D,{strexpr2»
where the <: str expr>s specify file names. TRUE will be returned if the first
file is newer than the second. A preprocessor run-time error will occur if
one of the filesdoes not e>:ist.

Al pha draft

9-7

7 February 1983

Workshop Reference' Hanuat for the Lisa

USing E:<ec F·nes

9.2.5 String Expressions
A str'irig expression« strexpr » may specify a string by a number of meanSf
as noted in the following grammar.

<stre>:pr)

.. -

<parameter reference>
I <: strconstant>
I {expanded strconsi:ant)
I <si:rfunction>
I {e>:ec function call>

A parameter 'reference has i:he usual II %n" form. A string constant has the
si:andar'd form of te>:i: delimited by sir,gle quotes (') ,with a quote inside the
string specified by the double quote rule, as in 'That"sall, foll\s!'. An
expanded string constant is similar to a stringconstant,e>:cept tha. t double
quotes (") are used as delimiters and parameter references are expanded
within the string. A stringfunci:ion is a preprocessorfunc1:ion which returns
a string value (these are described in the following section). An e>:ec
function call is an invocation of an e:<ec file which returnsa. string value (as
described in a following section, "E :.: ec F unction Calls").
String Functions-- CONCAT and UPPERCASE
The string functions CONCA T and UPPERCASE may' be applied to other
stringe>:pressionsi:oproduce r,ew strir,gvalues.
The CONCAT funci:ion allows severalstringe:<pressionsi:o be combined to
produce a result which is a single string. The CONCAT function has the
form:
CONCAT ( <strexpr> (,

<streHpr> J*)

Thatis,CONCAT tal\es a listofstringe>:pressions,separatedby commas.
The UPPERCASe: function conver·i:s ar,y lower case lettersir, its argument
toupper case. Ithas the following form:
UPPERCASE «stre>:pr»
An e:<ample of the use of this function is
$

SET%OTOUPPERCASe: (%0)

which willsetparameter 0 to an uppercase version of itspreviousvalue.
9.2.6

Nesting exec Files
E>:ec files can be nested by ,:alling another e:<ec file by using the SUBt'lIT

command. The called file can be a fundion, which means that it will
RETURN a value to a parameter in the calling e:<ec file.
SUBMIT
The SUBHIi command allows nesting of e:<ec files, that is, it allows
another e>:ec file to be called from within an eHec file. The form of the
SUBMIT command is:
$

Al pha draft

SUBMIT {e:<ec command>

9 _':;''-'

7 February 1983

Using Exec Files

WorKshop Reference Manual for the Lisa

where {e:<ec command> isan e:<ec command of the same form as you would
have following the "e>:ec!" or "<" at the t';orK5hop shell command level.
This e:<ec command may include parameters and e:<ec options in the usual
fashion.
The effect of the SUBMIT command is to process the specified e:<ec file,
putting any generated e>:ec output text into the current e:<ec temporary
file. Thus,while a single exec flle may have sever~_!:-,a-s'tedsub-e:<ec files,
only a single temporary output file is generated which includes the output
gerlerated by all of the input files. E:<ec files may be nestedtoan arbitrary
level.
Within the text of the <exec command>, references to "%n"parameters will
be expanded and the literalizing character ("-'~II)will be processed. Be aware
that this is the only processing that taKes place within an exec command.
Everything up to the first" (" or the end of the line (if no parameter listis
present) will be taKen to be the ex ec file name. If there is a "(" the
parameter list will be taKen to be everything between this
and the nex t
")", An (e:<ec command} may notbe splitacrosslines.
II ( "

Note that only the "I" <Ignore first line) and "B" (BlanKs. significant) options
are valid on a SUBMIT command, while the "R" <:ReRIJn), "5" (Step mode) and
"T" (Temporary file saved) options are only applicable from the main e>:ec
invocation line.
$RETURN -- Exec Functions
The RETUR N command allows exec files to return string values to other
(calling) exec files. Thusthe RETURN command can turnan el<ec fileintoa
function. The form of the RETURN command is:
$

RETURN C-(stre:<pr) J

Executing a RETURN command will terminate the current e>:ec file and
return to the calling exec file with the specified string value. The method
by which exec functions are called isdescribed in the following section.
E>:ec functions can be used to do such things as determining whether a
program file (and itscorresponding include files,if any) have been modified
since their last compilation, and may thusbe used to conditionally submit
compiles. If written generally enough, such a function could be used by
many exec files.
E:xec functions can produce side effects, that is, they may contain normal
lines which will get placed in the temporary file. While the intentional use
of such side effects is unliKe ly, inadvertentinstances rna y occur and will be
potentially hazardous to your e>:ec files. (An une:<pected blanK line in the
middle of an exec file can often throw itout of sync.)
Exec FunctionCalls
E:xec function calls return string values, and are thus ar-e orle of the basic
elements of string expressions. They may also appear in boolean
ex pressions,supplying arguments for string comparisons •. (A typical use of

Al pha draft

9-9

7 February 1983

Using E}:ec Files

WorKshop Re'fererlce Manual for the Lisa

an e:<ec function would be to returna boolean value by returningeitherthe
string'TI or 'F',) The form of an exec function call is:
<

E( -=: arg list) ) J

where II ( " is the char'acter that signals a function invoca tion (justin the way
that this character identifiese>:ec files for the Worl<Shop's Run command).
The <file rill-me) and optional (arg list> are the same as in the SUBMIT
command.
Due to our liberal conventions concerning what characters (including
blanKs) may appear in file names, the preprocessor must maKe some
assumptions a.bout how to identify the ex ec function file name and the
argument list. Recognizing the file name. is more of a problem in the case
elf e:<ec functions tharl it for the SUBMIT command, since exec function"
calls may appear inside of arbitrary string e>:pressions, while an e>:ec
invocation appears by itselfin a SUBMIT command, The simple rule the
preprocessor uses is: if the e>:ec function invocation has an argument list,
the file name is assumed to be everything between the "(" and the "("
beginning the argumen't list; otherwise, the file name is assumed to be
everything between the "{" and the end of the line, which means that you
will have to supply an empty argument list to an exec funtion with no
arguments if the function call is not the las1:thirlg orl the com mand lirle.
The proceSSing ofthe te>:tof a function call is the same as that ofa SUBMIT
command, that is,the only processing that will taKe place is e>:pansion of
"%n" parameters and recognition of the literalizing character ("'.~"). This
means, for instance, that the text of a function call may not conta.in an
embedded function call. Note also that a function call may not be split
across lines,
9.3

Using 8:xec Files
An invoca tiorl line for th e pre proce ssorhas th e following form:
(e>:ec command> <exec file>

r «parameter list»

E{e>:ec options> JJ

The <exec command) can be either "EXEC/" or "<", The <exec file> is the
name of the e:<ec file you wish to run. A ".T8:XT" e:densionwill be assumed
if one is not specified; however, you may override the mechardsm which
supplies the ".TEXT" e:densionby ending your <e:<ec file> name withadot;
e.g" using II foo." will cause the preprocessor to 1001< for the file" foo" rather
than"foo.tex1:".
The optional <parameter list) is enclosed in par·en1:heses. The parameter
list may be empty or it may include up to ten parameters delimited by
commas. For example, we may have an e:<ec file to run compiles which
taKes volume and source file parameters, which we might invoKe with
"compile (foo,-worK-)", Parameters may be omitted (leaving them as null
paramters) by specifying them with the null string, a.s in "compile(foo,)" t
which omits the volume from our previous e:<ample.
Alternately,
pa.rameters may be left unspecified altogether, as in "compile(foo)" t in

AI pha draft

9-10

7 February 1983

WorKshop Reference Manual for the Lisa

Using E::<ec Files

. . Jhich case they also get null values. Onereasonforleaving off parameters
is that the e:<ec file may have been set up to supply default values. as is
described below.
The <exec options> which follow the closing ")" of the parameter list
consist of single letter commands which will modify the behavior of the
preprocessorj for e>:ample. "S" is used to indiCate that you want to step
through the e>:ec file asitisbeing processed. conditionally selecting which
commands will be sent to the WorKShop shell. The e:-:ec options are
discussed in detail in the "E::<ec Invocation Options"sectionbelow.
The preprocessor's output is a te mporary file with a " .. TE XT" e:dension.
The temporary file is the processed versionof your ex ec com mands, tha tis.
all preprocessor--oriented commands will have been processed and
removed. leaving only the WorKShop-related commands. This temporary
file is passed to the WorKShop shell e>:ecutive when the preprocessor is
done. The WorKShop shell will then run the temporary e>:ec file and delete
it automatically when completed.
Note that the preprocessor is nat case-sensitive,but it does preserve thecase ofparameters and strings supplied by the user.
E:<ec Invoca:tionOp1:ions
A rlumber of options are available when running the preprocessor. These
options may be specified when invoKing the preprocessor or on SUBMIT
commands. The options are specified by single lettercommands following
the eHec parameter list. (A null parameter listshouldbe used if you want to
use c.ptionswithout parameters,as in U< fooOs" .)The optionsare as follows:
"B" indicates that the preprocessor should not trim blanKs on output lines.
Normally the preprocessor will trim off leading and trailing blanKs on
the linesthatitoutputstothetemporary file. This allows you to indent
normal lines (lines which are not e>:ec command lines) without
worrying about generating spurious blanKs. Thus the preprocessor
assumes that leading and trailing blarlKs are insignificant (which isthe
case for WorKShop commands, but which may not be true for some
perverse programs you may run via exec files). Thisoptionwill tell the
preprocessor not to trim such blanKs. The option applies only to the
exec file being run or SUBMITted, and not to any nestedexec files.
"I" indicates that the first line of the exec file is to be ignored by the
preprocessor. This option is intended for deviants who liKe to embed
their e:< ec files in their program sources, in which case the firstline of
the source should be a "(*" and a "*)" should follow the end of the e>:ec
filet thus commenting it out of the program source. (Note that" (*" and
"*)" should be used in preference to "("and "}"since the latter are used
. as comment characters in the preprocessor.)
liT" indicates that the temporary file which is created (i.e., the e:<panded
form of the e:<ec file) should not be removed after it is run. Dnereason
to use this option is to maKe it possible to rerun an e:-:ec file created
with the step option (see below) without going through the stepping

AI pha draft

9-11

7 February 1$'83

Using E:<eC

Worl<shop Reference Mariual for the Lisi.

File~

prompts a 5.econd time by running a previously created e:<panded e:<ec
file. The "R" e:<ec option (described below) is used to run old temporary
e>:ec files. Note that the liT" option is not allowed on SUBHIT
commands.
"R" indicates that the a exec temporary file which has been sa.ved with the
"T" option should'be rerun~ bypassing the normal processing by which
the temporary was created. For e:<ample, "foo" may be an e>:ec file
which generates a complicated system via a large number of nested
e>:ec fileswhich taKe a significantamount of time forthe preprocessor
to digest. If we Know we are going to run" faa" repeatedly ~ we may
warlt to gerlerate the temporary file only once but runitseveral times.
The first time we would invol<e the preprocessor with "<fooOt" to
irldicate that the temporary file should not be automatically deleted
after it is run. Subsequently~we would invol<e the preprocessor with
"{fooOr"to rerurlthe old temporary file. Note that the "R" option will
override any others that may be specified~ and it is not allow'ed on
SUBMIT commands.
"S" indicates that the exec file should be processed in "Step Mode" which
allows selective sKipping of output lines and SUBMITs. Ifthisoptionis
used~ the following message will appear when you invoKe the
preprocessor:
Step Mode:
-- in response to "Include?" answer: V, N~ A (Abort),I( (Keep r'est)~ or I <Ignore Rest).
-- in response to "Submit ';''' answer: Vt Nt S (Step), A (Abort), K (Keep Rest), or I
<Ignore Rest).
More details';' [No]
I f you repond with "Y" (yes) to the "t1ore deta i 1s ?" promp t you 1,oJ ill
get further i nformat i on on l)Jhat each of stepp i n9 responses means.
When you invoKe a.n e>:ec file with the step option you will be prompted
when a line has been generated and is about to go into the temporary file.
The line will be displayed followed by "{= Include?". A responseof V" will
incll.Jde the line in the e>:pa.nded exec file. A responseof Nil will cause the
displayed line to be omitted. A response of "A" will abort out of the e)<ec
file preprocessor and no e:<ec file will be run. A response of "K" willl<eep
(include) all the remaining lirles of the e>:ec file~leaving step mode, while a
responseof "I" 'Nill ignore the remainder of the eHec file.
II

When a SUBIHT command is encountered when stepping~the SUBMIT line
will be displayed followed by "<= Submit ?". A response of "Y" will perform
the SUBMIT unconditiorlally~ that is~ without stepping thr'ough it. A
response of "Nil will ignore the SUBHIT. A response of S" will stepthrough
the SUBMIT file. A response of "A" will abort out of the e:<ec file
preprocessor and no e:< ec file will be run. A response of II K" 'Nill Keep the
rest of the e>:ec file,leaving step mode, while a response of "I" will ignore
the re mainder oHhe eHec file.
II

Al pha draft

9-12

7 Februar:' 1983

WorKshop Reference Manual for the Lisa

Using 8:<ec. Files

Note that a reponse of "?" to a "Submit ?" or "Include?" prompt will elicit an
e>:planationof the accepted responses.
Following are some e:<amples of how to use the preprocessor'ssteppirlg
facility.
Stepping may be used to resume execution of an ~xec file which did not run
to termination. For e>:ample, if our e:<ample "compile" exec file includes
both a compile and a generate step and if we wish to resume with the
generate
step
we
could
invoKe
the
preprocessor
with
"compile(foo,-worK-}s". Then, in response to the "Include?" prompts for
lines corresponding to the compile stepwe would hit "N" to sKip the lines.
Upon reaching the first line of the generate step we would respond with "K"
to Keep the restof the file ,and the generate stepof the e:<ec process would
be performed.
The stepping mechanism may be used to run only selected parts of an e>:ec
file. Say, for instance, that we have a modular set of exec. files which
generate a whole system of progr'ams, such as the WorKShop development
system, and that one e>:ec file called "maKe/all" can generate the whole
system by SUBMITtinge:<ec files for each ofthe component programs. The
e:<ec files for each component program (development system tooD maKe
use of other e:<ec files to perform such standard activities as compiling
(and generating) a Pascal ur:lit or program, performing an assembly,
installing a library, or manipulating files with the WorKShop's filer. If we
are performing a system build and find ourselves constantly having to
regenerate parts of the system due to bugs, late deliveries or whatever,
then the ability to step by SUBMITs peoves to be very useful. Arbitrary
parts of the system carl be regenerated by running "{maKela1l0s" (i.e.,our
master e>:ec file invoKed with the stepping option) and selectively
submitting the sub-exec filesforonly thosethingswhich we wish to rebuild
while stepping over the others.
Stepping in cort.iuction with the "T" option (for saving the temporary file
created by the preprocessor) can be useful when we are going to be
regenera ting a single component of a program or syste m a number of times
in succession, such as when we are fi>:ing a bug in an element of a system
build and we expect that several iterations will be needed to correct the
problem. To continue our previouse>:ample, suppose that we are having a
problem with the" FileIO"unit of the "ObjIOLib"librarywhile building the
development system, and that an exec file called "maKe/ObjIOLib"
generates and installsthe library,submitting compiles and assemblies for
all of its units, linKing everything together, and finally performing the
irlstallation. By invoKing the preprocessor with "maKe/ObjIOLibOst"wecan
go into step mode and submit only those things related to the compilation
of the "FileIO" unit, the linK, and the installation of the library in the
Intrinsic Library. Then, after each successive refinement of "FileIO",we
could rurl the saved temporary file by r'unning "(maKe/Ob,iIOLibOr"without
having to go thru the stepping process. Ouralternativesto this procedure

Alpha draft

9-13

7 February 1983

Workshop P,eference Manual for the

Lisa.

Using S:xec' Files

are crea.ting a.rlother e>:ec file to genera.te only the selected parts, or
running (and rerunning) the e>:ec file for the whole library,or running each
sub-processindependently (which requires more of your attention).
Note that typing Apple-period while the preprocessor is running will abort
the processing of the el<ec file.
9.4

Example Exec Files
E>:ample 1 -- an e>:ec file to do a Pascal compile
This e:<ec file does a Pascal compile and generate. Note how comments
have been us.ed to maKe the single-character WorKShop commands more
intelligible.
$E)(EC {"camp" -- perform a Pascal compi le
;~O -- the name of the un i t to camp i 1 e )
P{Pascal compi le):1.0{source)
(nalistfile)
(default i-code file)
G{genera te code )/:O
(default obj file)
'$ENDEXEC
!h:ample 2 -- ane>:ec file to do an assembly
Thisexec file performs an assembly, and allows for an optional output file
rlame which may be differentfrom the source name.
$EXEC { "assemb" -- perform an assembl"l
~~O -- the name of the un i t to assembl e }
~~1 -- (opt i anal) 011 ternate name af OBJ output)
'$DEFAULT ~~1 TO %0 { use :·c.urce name if no au tpu t name is given}
A{assemble)/:O{source}
{nolistfile}
;~1{obj f i 1e}
$ENDE)(EC
E>:ample 3 -- a more flexiblee>:ec file·to do Pascal compiles
This e>:ec file performs compiles; it allows for an output file with a
differentname than the souce and permits the use c.f a.n alternate intrinsic
library.
$EXEC { "comp 1" -- perform a Pasca 1 comp i 1 e
/:0 -- the name of the un it to comp i 1 e
~~1 -- (opt i onal) al ternate name for 08 ...T f i 1e
%2--(optional) alternate intrinsic library}
'$DEFAULT %1 TO ;~O { if no a i terna te 08.J name use same name as source}
$IF/:2 {) '-' THEN {useal ternate intrinsic 1 ibrary}
P{Pascal comp i 1e}?{opt i on fl agJ
;Q{al ternate intrinsic 1 ib)
;~O{source}

'$ELSE
P{Pascal
'$ENDIF

Alpha draft

compile);~O{saurce}

9-14

7 February 1983

WorKshop Reference Manual for the Lisa

Using E:<ec Files

{nolistfile}
{default i-code file)
G{genera te code )%0
;~1{OBJ fi Ie)
$ENDEXEC

e:>:ample 4 -- yet another exec file t~do Pascal compiles
Thiscompile exec file will only perform the compile ifeitherthe object file
does not e:<istor the source file is newer than the object file (i.e.tthe source
has changed since it was last compiled).
$E)(EC

{

Icomp2"

-- perform a Pascal

compile

(only

if really

required)
%0 -- the name of the un it to comp i 1e
;~1 -- (op tiona 1) a 1 terna te name for OBJ f i 1 e
;~2 -- (optional) OIl ternate intrinsic J ibrary}
$DEFAULT /~9 TO ;~1 { se t /~9 to name of ou tpu t OBJ f i 1 e }
$DEFAULT %9 TO ;~O
$IF EXISTS (1I%9.obJ") THEN
SIF NEWER (1%0.text l ,I%9.obj") THEN {recomp if source newer
than object}
"$SUBMIT compl G~O ,%1 ,;~2)
SENDIF
$ELSE {OBJ f i 1 e does not ex i st, so genera te i t }
SSUBt1IT comp 1 (%0 ,;~1 ,%2)
"$ENDIF
$ENDEXEC

It is left as an e>:ercise as to how to change the above €n:ample to taKe into
account the fact thata unit may have an arbitrar~tnumber of include filesirl
addition to its main source file,and thai:the unii:willhave tobe recompiled
Hone or more of these change.
e:>:ample 5 -- exec file "chaining"
This e:<ample ("maKe/Prog") uses the "smart" compile e:<ec file (licomp2")
defined in the last example to demonstrate how to "chain" e)<ec file
e}: ecution. Assume we want to generate a particular program made up of
three units (unit1..unit3)and that we ha.ve written"linK/Prog" ta smart exec
file which performs a. linK only when one of the object files for one of the
units is newer than the linKed program file. Our generation e>:ec file will
use these smart e:<ec filesto perform the minimal required amount of worK,
thusit may be used to determine whether we have the latestversionofthe
program without fear of wasting time.

AI pha draft

9-15

7 February 1983

Wor~<shop

Reference 14anUal for the Lisa

Using E:·:ec Files

'$E:<EC {"make/Prog"

-- smart version, on);1 recompi les&) inKsl,<)hen
ithasto}
'$SUBt1IT comp2(un i t1)
'$SU8t1lT comp2( un i t2)
$SUBt1IT comp2(un i t3)
{ run 1 i nit. exec f i 1e af tel' ,:c,mp i 1es have
R{l ink/Prog
run so that it will get the correct
fi le dates}
'$ENDEXEC

Nc,te that in the last line of the at,ove e){ec file we have scheduled an e:·:ec
file to be run at a later time t as opposed to SUBMITting it nOWtSO thatthe
file dates for' the linf< step will be accessed after the compiles have had a
chance to run. The differences between running and submitting and e:·:ec
files ar-e demorlstrated in the following scenario. trJhen an e:<ec file is
submitted it is processed immediately by the prepraces':;ortwith itsoutput
going to the temporary filet which is then passed bacK to the It}orf<Shop
·:;hel1. The then shell runs the commands in the tempora.ry file until it
carnes tc, the command to rur,another' e:·:ec file,atwhich point it discards
the remainder of the temporary file and runsthe preprocessor-with the new
e>:ec command.
This e)·:ec file invocation in turn results in another
temporary file of commands which is then run by the shell.
Example 6 -- a recursive exec file to do Pascal compiles
This compile e>: ec file will perform up to 10 compiles. It1:aKes arl argument
listwith the na.mes of the units to be compiled.
':f;EXEC { "rcomp" -- perform ani number (up to 10) Pa';cal comp i 1 es.
I t calls "c omp" on its fir star gume n t an d the n calls i t se If
recurs i Ile 1 ;/IIJ i th its argumen ts sh i f ted 1 ef t }
'$1 F ;~O <> .'.' THEN
'$SUBt1IT compC~O)
{ "comp" the first one}
·$SUBt'1ITrcompC~1,/'2,~~3,;~4,;·~5,;~6,;Q,~~8,~~9) {"rccmp" the rest, less
first}
'$ENDI F
$ENDEXEC

8:xample 7 -- a Ba.sicexample
This e:<ec file demonstrates some of the constructs in the preprocessor":;
meta-Ianguaget by generating the BASIC interpreter. The comments in the
body of the e>:ample should be sufficient to describe what is taf<ing place.
The essentialidea is that Basic is made out of three componentSt and that
we may want togenerate c,rlly one or mor'e e,fthem a.t a. time.
'$EXEC { "maKe/bas i c" -- genera te the BASI C in terpre tel'.
There are three parameters -- if a parameter is a "Y" (/es.)
the corr'espond i 09 par t of the system shou 1d be genera ted:
(0) the b-code inter·pr·eter
(1) the r'un-time s;istem
(2) the command in t erpr'e ter'

Al pha draft

9-16

7 February 1983

Using E>:ec Files

WorKshop Reference Manual for the Lisa

I f no parame ters are spec i f jed, the exec f i 1e IJJ ill promp t to see
wha t par t s of the sys tern shou 1d be genera ted. }
$IAlRITELl'1 'Start i ng generat i on of the BASIC system'
"$1 F ;{O
AND /:1
U
AND ;{2 U THEN {no params supp 1 i ed -- promp t
for info}
"
$WRITE 'do you want to assemble the b-code interpreter? (y or

= /.'

[n])

"$READCH ;{O
"$WRITELN {th i s ~ljr i te 1n pu ts us on a nel,ll 1 i ne for the next promp t }
$IAlR ITE 'do you ~<Jan t to camp i 1 e the run - time S;IS tern? (y or [n]) I
"$READCH %1
$I;JRITELN
$l.o.lRITE 'do ;IOU l,Ilan t to camp i 1e the command in terpre ter? (y or
[n] ) .-

"$READCH ;{2
$I,.JRITELN
"$ENDIF
$

= /",(-'

"$IF UPPERCASE(Y,O)
THEN
$SUBt1IT assemb ( in t .ma in)
"$ENDIF
$

$IF UPPERCASEe{1)
'Y' THEN
$SUBMIT comp (b. r tun it)
"$ENDI F

{assemble the b-code interpreter}

{compi le the run-time uni t }

"$IF UPPERCASE(Y,2) = "(' OR UPPERCASEG{l) = 'Yo' THEN
"${ comp i 1 e the command in terpre ter }
${ comp i 1 e also if the run-t ime un it has changed}
"$SUBr1IT comp (b. bas i c)
$ENDIF
$
"${

1 inK it all together}

l { 1 inK

}-p {note tha t "_ p II ge ts around ali nKer bug)
b.basic
b.rtunit
in t .ma i n
hwi ntl
i osf p 1 i b
iospasl ib

basic{e:<ecutable output)
"$ENDEXEC

e --

E>:ample
an e}:ec file function
This e>: ec file is a function which will prompt the user for the location of a
Profiletreturning a string with the name of the device to 'olhich the Profile

Alpha draft

9-17

7 February 1983

WorKshop liefer·ence Manual fo'r the Lisa

Using E>:ec .Files

is attached. Note that the function calls itself recursively until a valid
device name isspecified.
'$EXEC {"GetProfLoc" -- get location of profile byasKinguser}
'$REQUEST %9 WITH
'IJJhere
is
the
profile
attached?
(parapor Us 1ot2chanl/s 1 ot2chan2) .'
'$SET ~~9 TO UPPERCASE (~~9)
'$1 F C~9 <> .' PARAPORT") AND (/~$' <> I SLOT2CHAtH") AND (~~9 <>
.' SLOT2CHAN2 ' ) THEN
$WRITELN 'Tha t i s not a 1)0. 1 i d del} ice name. Le t·, I s try ago. in •..'
$RETURN <Ge tProfLoc {recurs i l}e co. 11 )
'$ELSE
$RETURN %9
'$ENDI F
'$ENDEXEC

9.5 Exec File Programming Tips
The following few points may be useful to remember' when cr'eating e:<ec
files:
Use modular e:<ec files. It may helpful-to thinK of exec filesasprocedures
which are called via the SUBMIT command. The more modular your e>:ec
files are , the easierit will be to use the stepping facility on them.
Create si:andard e:<ec files for common functions; fore:<amplet use one
e>:ec file to perform all your compila hons. One advantage of thisis that you
only have to edit one file when the ~nterface tothe tool changes (asit hasin
the ca.se of the asse mbler).
' "
.
Use. opi:ional parameters to supporHe a tureswhich are not 0.1 WOo ys (or often)
used (such as the ability to compile against an 0.1 terna teintrinsiclibrary in
your compile e>:ec file). The parameter mechanism is such that you ca.n
remain oblivious to optional parameters if you don't need the functions
they support.
Write your exec files -to prompt for informa-tion which was not supplied in
parameters. This way you don't need to remember the meaning of a large
number of parameters.
9.6

Exec File Errors
The preprocessor ca.rl recogrlize a number of er·rors during its irlVocation
and e>:ecution. The format in which most errorsare reported is:
e:RROR in <err loc>
<curr line>
<err ma:rKer>
<errmsg>
where
<err'loc>

Al pha draft

is either 'invocation line/or 'line #<n> of file "< file>'"

9-18

7 February 1983

WorKshop Refer'erlce Manual for the Lisa

Using E:xec Files

is the current e:<ec line when the errorwas detected

<err marKer> is a line with a question marK indicating wher'e the
preprocessor was in <curl' line> when the error was
detected
<errmsg>

is one of the messages listedbelow.

10 errors are followed by anadditiorlallirle with the ted of the OS errl~r
raised during the IOoperation. The errorsdetected are as follows:

10 Errors:
Unable
Unable
Unable
Unable

toopen input file "(file)".
toopen temporaryfile "(file)".
to access file "{file)".
torerun file "(file)".

Other Errors:
F i 1e does not beg i n ~II i th "$EXEC" •
End of Exec f i 1e before "$ENDEXEC".
$EXEC command other than at start.
No Exec f i 1e spec i f i ed.
More than 10 parame ters.
Noclosing")" found.
Line buffer overf low ()255 chars) •
lnval id Exec option: (option char).
Inval id Exec option on SUBMIT: (option char>.
End of Exec f i 1 e in comment.
Inval id percent: not "~{n" form.
Garbage at end of command.
No argument to SUBt1IT.
ELSE, ELSElFor ENDlFnot in IF.
ELSEl F after ELSE.
F i 1e con ta ins un fin i sh e d IF.
No t h i n 9 f 0 11 O~II i n g " <til de)" •
Out of memory. Processing aborted.
Bad temp file name generated: "(file)".
No value returned from fi le called as function.
RETURN 1/oJ i t h val u e i n f i 1e not c a 11 e d as fun ct i on •
and
I nva 1 i d command. (toKen) expec ted.
~<)here <toKen:> may be:
String value
"~~n" parameter
Term ina tin g 5 t I' i n g de 1 i mit er
"=" or II <:>"
"()"

Boolean value
Comma (1 ist del imi tel')

Alpha draft

II (

!I)

9-19

7 February 1983

WorKshop Reference Ha.:nua1 for the liS-a.

Using E;.:ec Files

I,) a 1 i

d command Keyword
Command

Alpha draft

9-20

7 February 19B3

WorKshop Reference

Manual for the Lisa

The Utilities

Chapter 10
THE UTILITIES
10.1

Introduction

•.. . a- • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • 10-2

Utilities are Executed by the Run command from the WorKshop.
section explains the method for running a utility, and the common
interface.
10.2

Byt!Diff ...........•...........•..........•........................... 10-3

ByteDiff compares
different.
10.3

This
user

ChangeSeg

two files, byte by byte, and shows where they are
.......••.•....•..•••.••.......•..•••..•....•..••......••. 10-4

ChangeSe.g allows you to change the segment name of an object.
10.4 Code Size •••••••••••••••••••••••••••••••••••••••••••••••••••••••••••• 10-5
CodeSize gives you a summary of the contents of an object file

••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••. 10-6
10.5 Diff
Diff compares two text files and shows their differences.
10.6 DumpObj ••••.••..••..•.•.•.••.•.••••••••.•••••••••••••••.••••••••••. 1O~ 7
DumpObj displays the contents of an object file.
10.7

DumpPa tch

DumpPatch
10.8

...•..•...•......••
displays and edits the contents of any file.
I

••••••• I ..............................

fiileDiv and FileJoin •...........•..•...

1 •••••••••••••••••••••••••••

10-7

10-8

FileDiv divides large files into smaller ones. FileJoin rejoins the resulting
small files bacK into the original large file.
10.9

Grep

••••..•••••••.•••••••••••.•••.••..••••••..••..•••.••..••..••..• 10-9

Searches for Id's.
10.10

GxRef

•••••••••••••••••••••••••••••

I ••••••••••••••••••••••••••••••••

10-9

GxRef provides a global cross reference.
10.11 Pacl<Seg ......•..........•...•..................................... 10-10
PacKSeg pacKs object code files.
10.12 SegMlp ...•......................................................• 10-11
SegMap produces a segment map for one or more object files.
10.13 SxRef ............................................................ 10-12
SxRef produces a cross reference.

Alpha draft

10-1

7 February 1983

WorKshop

Alpha draft

Reference

Manual for the Lisa

10-2

The Utilities

7 February 1983

Worl<shop

Reference· Manual· for the Lisa

THE

The Utilities

LIT I L I T I ES

10.1

Iniroduction
how to run utilities

10.2

ByteDHf
BYTEDIFF compares any binary files, but once it finds a difference between
the two files, it does not always find where the differences end.

10.3 ChangeSeg
CHANGES8G changes the segment name in the modules in an object file.
The first prompt asl<s for the object file you want to change:
File to change:
Changes are made in place (the file itself is changed). You are next asl<ed:
Map all Names (YIN)
If you want to change segment names in all modules, respond Y. If you want

to be prompted for the new segment name for each module, type N. A
response of <cr> accepts the defa.ult name.
10.4
10.5

Code Size
DiH.
DI F F is a program for comparing ". T8XT" files, in the LISA Pascal
development environment.
DIFF is strongly oriented toward use with
Pascal or Assembler source files.
DIFF is not sensitive to upperllower case differences. All input is shifted to
a uniform case before comparison is done. This is in conformance with the
language processors, which igno~e case differences.
DIFF is not sensitive to blanKs. All blanKs are sKipped during comparison.
This is a potential source of undetected changes, since some blanl<s are
significant (in string constants, for instance). However, DIF F is insensitive
to "trivial" changes, such as indentation adjustments, or insertion and
deletion of spaces around operators.
DIFF does not accept a matching context which is "too small". The current
threshold for accepting a match is 3 consecutive matches. The M option
allows you to change this number. This has two effects:
Areas of the source where almost "every other line" has been changed will
be reported as a single change blocK, rather than being broKen into several
small change blocKs.
Areas of the source which are "entirely different" are not broKen into
different change blocKs because of trivial similarities (such as blanK lines,
lines with only "begin" or "end", etc.)
DIFF mal<es a second pass through the input files, to report the changes
detected, and to verify that matching hash codes actually represent
matching lines. Any spurious match found during verification is reported as

AJ pha draft

10-3

7 February 19B3

WorKshop

Reference

Manual for the Lisa

The Utilities

a "JACKPOT".
The probability of a JAC1.'POT is very low, since two
different lines must hash to the same code at a location in each file which
extends the longest common subsequence, and in a matching context which
islarge enough to exceed the threshold for acceptance.
DIF'F' can handle files with up to 2000 lines.
DIF'F' first prompts you for two input file names:. the "new" file, and the "old"
file. DIF'F' appends ".TEXT" to these file names, if it is not present. DlF'F'
then prompts you for a filename for the listing file. Type carriage-return to
send the listing to the console.
DIF'F' does not (currently) Know about INCLUDE files; However, . DIF'F' does
allow the processing of several pairs of files to be sent to the same listing
file. Thus, when DIF'F' is finished with one pair of files, it prompts you for
another pair of input files. To terminate DIF'F', simply type carriag~-return
in response to the prompt for an input file name.
The output produced by DIF'F' consists of blocKs of "changed" lines. Each
blocl< of changes is surrounded by a few lines of "conted" to aid in finding
the lines in a hard-copy listing of the files.
There are three Kinds of change blocKs:
INS8:RTION -- a blocK of lines in the "new" file which does not appear in the
"old" file.
D8:L8:TION -- a blocK of lines in the "old" file which does not appear in the
"new"file.
R8:PLACEMENT -- a blocK of lines in the "new" file which. replaces a
corresponding blocK of different lines in the old file.
Large blocKs of changes are printed in summary fashion: a few lines at the
beginning of the changes and a few lines at the end of the changes, with an
indication of how many lines were sKipped.
DIF'F' has three options which allow you to change the number of context
lines displayed (+C), the number of lines required to constitute a match (+M),
and the number of lines displayed at the beginning of a long blocl< of
differences (+D). To set one of these numbers, type the option name
followed by the new number to the prompt for the first input file name. +D
100, for example, causes DIF'F' to print out up to 100 lines of a block of
differences before using an ellipsis. The maximum number of context lines
you can get is 8.
10.6

DumpObj.
DUMPOBJ is a disassembler for 68000 code. It can disassemble either an
entire file, or specific modules (procedures) within the file. DUMPOBJ
replaces DUMPMCODB:.
DUMPOBJ first asl<s for the input file which should be an unlinKed obJec"t
file. The output <listing) file defaults to CONSOLE:. You. are asKed whether
you want to dump

AI pha draft

10-'1

7 February 1983

WorKshop

Reference

Manual for the. Lisa

The Utilities

Am, S(ome, or P(articular modules.
If you respond S(ome, DUMPOBJ asKs you for confirmation

before dumping
each module. A response of <E:SC) gets you bacK to the top level. If you
respond P(articular , DUMPOBJ asKs you for the particular module(s) you
want dumped.
The next question is: 'Dump file positions CNJ?'The file position isa number
of the form CO,OOOJwhere the first digit is the blocK number (decimal) within
the file and the second number is the byte number (hexadecimal) within the
blocK at which the module starts. This information can be used in
conjunction with the PATCH program. Finally, DUMPOBJ asKs if you want
the object code disassembled.

10.7

DumpPaich
DumpPatch

is a combination of DumpHex

and Patch.

DumpHex provides a textual representation of the contents of any file. The
file dump is blocK-oriented with the hexadecimal representation on the left
and the corresponding ASCII representation on the right. If a byte cannot be
converted to a printable character, a dot is substituted.
When DumpHex is Run, it asKs you for the name of the output file. A .TE:XT
extension is added if necessary. To direct the output to the console, type
carriage re1:urn. After getting a valid ou1:put file name, DumpHex asKs for
the inpu1: file to be dumped. No ex1:ensions are appended, so give the full
filename. Once a file has been comple1:ely dumped, DumpHex asl<s you for
the next file to dump. Type carriage return to exit the program.
After opening the input file, DumpHex asl<s you which blocl< to dump. The
default (carriage return) is blocK 0. If the output is going 1:0 a file, you are
asKed which. blocK is the last you want dumped. The defaul1: here (carriage
re1:urn) is the last blocK in the file.
The format of the console output depends on the number of lines your screen
has. If fewer than 33 lines are available, the output is displayed only a half
blocK at a time. Between blocl<s or blocK halves you have the option to
Type <space) to continue, <escape) to exit.
E:scape returns to the prompt for an inpu1: file.
Pa1:ch allows you to examine and change the contents of any file. Tho
display of the file's conten1:s is exac1:ly liKe that of DumpHex. With Patch,
however, you can use the cursor control Keys 1:0 move around in the blocK
and change the value of any byte using either the hexadecimal
representation on the leH or the ASCII representa1:ion on the righ1:.
After Running Pa1:ch you are asKed for the full name of the file to pa1:ch.
Carriage return exits Pa1:ch. No extension is appended to the file name. You
are then asKed for the number of the blocl< you want to mess around with.
Carriage return here returns you to the file name prompt •

The blocK is displayed with the cursor in the upper left corner at word 0 of
the blocK. The arrow Keys can be used to move around in the blocK. If you

Alpha draft

10-5

7 February 1983

WorKshop

Reference

Manual

for the Lisa

The Utilities

move the cursor up from the top ,line, you get the bottom line of the
preceding blocK. Similarly, if you move down from the bottom line, you
move into the top line of the next blocK.
When the cursor is on the hexadecimal side of the display, you can change
any byte by typing the new hexadecimal value. Any non-hex characters are
ignored. You can impress your friends by pointing out that the change is
reflected automatically in the ASCII portion of the display. When the
cursor is on the ASCIl side, type any character to replace the value of the
byte.
Until you move ., out
<escape).
10.8

ofth~

block you can undo any changes'. by typing

FileDiv a.nd FileJoin.
It is often necessary to distribute files that a.re too large to fit onto a single
floppy disKette. FILEDIV can be used to breaK a large file into several
disKette-sized pieces. lilLEDIV can then be used to rejoin these pieces a.t
the file/s destination. These two programs replace the TRANSFER program.
To divide a large text or object file, Run FILEDIV.
Input file: <give the name of the file to be divided>
Output file: <give the name to be used for the output files>
Do not include the suffix in the file name. If, for example, you want to
divide TEMP.TEXT, give TEMP as the input file, and TEMP (or whatever) as
the output file. FILEDIV will create a group of files named TEMP.i.TEXT,
TEMP.2.TEXT, and so on, until TEMP.TEXT is completely divided up. If you
use the drive number (#9:, for example), rather than the volume name, the
new files can be written to multiple disKettes. When space on a disKette is
exhausted, FILEDIV asKs you to insert another disKette.
To rejoin the pieces of the file, Run FILE JOIN. Using the example given
above, we can rejoin TEMP.i.TEXT and friends into TEMP.TEXT by
responding:
Input file: TEMP
Output file: TEMP

FILEDIV and FILE JOIN use regular directories, so a. spurious sex change
cannot destroy your file. Files are verified in both directions.
10.9 Gl"ep
10.10 <n!Ref.
GXRE Ii lists all the modules which call a given procedure, a.nd a.ll the
modules which tha.t procedure calls. It provides a global cross reference of
subroutines and modules.

10.11 Pad<seg
10.12 SegHa.p
SEGMAP
prompt:

Alpha. draft

produces a segment map of one or more object files. The first

10-6

7 February 1983

WorKshop

Reference

Manual for the Lisa

The Utilities

F'iles to Map ?
a.ccepts either an object file name or a command file name. A command
. file must be preceded with a <. SEGMAP adds the .TEXT suffix to the
command file name. The next prompt:
Listing F'ile "?
directs the map information to the file given. A response of # 1: or
CONSOLE:. for example. send the map information to the screen. The map
information includes the object file name. the name of the unit in the file.
the names of the segments used in that unit (if any). and the new segment
names.
10.13

SxRef

Alpha draft

10-7

7 February 1983

:::::~~~'I"'-' MANUAL

was produced using
LisaWrite, LisaDraw, and
LisaList.

~Lisa1M

... we use it ourselves.

......_...-......-...................................................................................................._.............................- FaO ..........................-.........-................................................................................................................

/ ... "

,",,--/1

@J
AC£
STIIIP
HENE

f\PPl.E aMUTER lNC.

POS Publlcations Department
20525 Marlani Avenue, MS 2-0
Cupertino, california 95014
\ '-_."

TIIPF tR STAPLE

Worksnop User's Guide {'or tile Lisa

Mail Back

Apple publications would like to learn about readers and what you think about
this manual in order to make better manuals in the future. Please fill out this
form~ orwritealloverit7 andsendittous. We promise to read it.
Is it quick and easy to find the information you need in this manual?
[] always [] often [] sometimes [] seldom [1 never
COnunents _________________________________________________________
What made this manual easy to use? _________________________________
What made this manual hard to use? ______________________________
How are you using this manual?
[] learning to use the product [1 reference [1 both reference and learning
[] other _______________________________________________________
Please comment o~ for exam.ple, accuracy, level of detail, number and
usefulness of exam.ples, length or brevity of explanatio~ style, use of
graphics, usefulness of the index, organizatio~ suitability to your particular
needs, readability.

What do you like most about the manual? _________________________
What do you like least about the manual.? _________________
In school have you completed?
[] high school [] some college [] BA/BS [] MAIMS [J more
COnunents __________~------------------------What is your job title? _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ ___
How long have you been prog:ramming?
[] 0-1 years [] 1-3 [] 4-7 [] over 7 [J not a programmer
COmments ___________________________________________________
What languages do you use on your Lisa? (check each)
[] Pascal. [] BASIC (] COBOL [] other _ _ _ _ _ _ _ _ _ _ _ _ __
COnunents ___________________________________________________

What magazines do you read? _____________________________________

</pre><hr>Source Exif Data: <br /><pre>File Type : PDF
File Type Extension : pdf
MIME Type : application/pdf
PDF Version : 1.3
Linearized : No
XMP Toolkit : Adobe XMP Core 4.2.1-c043 52.372728, 2009/01/18-15:56:37
Create Date : 2011:07:09 20:26:11-08:00
Modify Date : 2011:07:09 21:51:14-07:00
Metadata Date : 2011:07:09 21:51:14-07:00
Producer : Adobe Acrobat 9.45 Paper Capture Plug-in
Format : application/pdf
Document ID : uuid:f05cf4a7-431d-4a6a-ae9c-d12a90ece3c1
Instance ID : uuid:28b125b5-c362-4214-8f0a-61aa624ee95b
Page Layout : SinglePage
Page Mode : UseOutlines
Page Count : 124
</pre>
<small>EXIF Metadata provided by <a href="https://exif.tools/">EXIF.tools</a></small>

<div id="ezoic-pub-ad-placeholder-110">
<script async src="//pagead2.googlesyndication.com/pagead/js/adsbygoogle.js"></script>

<ins class="adsbygoogle"
style="display:block"
data-ad-client="ca-pub-0545639743190253"
data-ad-slot="6172135303"
data-ad-format="link"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>
</div>
</div>
<div id="catlinks" class="catlinks catlinks-allhidden" data-mw="interface"></div> <div class="visualClear"></div>
</div>
</div>
<div id="mw-navigation">
<h2>Navigation menu</h2>

<form action="https://usermanual.wiki/search.php" id="searchform">
<div id="simpleSearch">
<input type="search" name="search" placeholder="Search UserManual.wiki" title="Search UserManual.wiki [ctrl-option-f]" accesskey="f" id="searchInput" tabindex="1" autocomplete="off"><input type="hidden" value="Special:Search" name="title"><input type="submit" name="go" value="Go" title="Find a User Manual" id="searchButton" class="searchButton"> </div>
</form>
</div>-->
<ul>
<li id="pt-mycontris"><a href="https://usermanual.wiki/upload" title="Upload User Manual" accesskey="y">Upload a User Manual</a></li>
</ul>
</div>
<div id="left-navigation">
<div id="p-namespaces" role="navigation" class="vectorTabs" aria-labelledby="p-namespaces-label">
<h3 id="p-namespaces-label">Versions of this User Manual:</h3>
<ul>
<li id="ca-nstab-main"><span><a href="https://usermanual.wiki/Document/WorkshopUsersGuideBetaApr83.397732840" title="User Manual Wiki" accesskey="c">Wiki Guide</a></span></li> <li id="ca-nstab-main"><span><a href="https://usermanual.wiki/Document/WorkshopUsersGuideBetaApr83.397732840/html" title="HTML" accesskey="c">HTML</a></span></li> <li id="ca-nstab-main" class="selected" ><span><a href="https://usermanual.wiki/Document/WorkshopUsersGuideBetaApr83.397732840/help" title="Discussion / FAQ / Help" accesskey="c">Download & Help</a></span></li>
</ul>
</div>
</div>
<div id="right-navigation">
<div id="p-views" role="navigation" class="vectorTabs" aria-labelledby="p-views-label">
<h3 id="p-views-label">Views</h3>
<ul>

<li id="ca-view"><span><a href="#">User Manual</a></span></li>

<li class="selected" id="ca-edit"><span><a href="https://usermanual.wiki/Document/WorkshopUsersGuideBetaApr83.397732840/help" title="Ask a question" accesskey="e">Discussion / Help</a></span></li>

</ul>
</div>
</div>
</div>
<div id="mw-panel">
<div id="p-logo" role="banner"><a class="mw-wiki-logo" href="https://usermanual.wiki/Main_Page" title="Visit the main page"></a></div>
<div class="portal" role="navigation" id="p-navigation" aria-labelledby="p-navigation-label">
<h3 id="p-navigation-label">Navigation</h3>

</div>
<div class="portal" role="navigation" id="p-tb" aria-labelledby="p-tb-label">

</div>
</div>
</div>
<div id="footer" role="contentinfo">
<ul id="footer-info">
<li id="footer-info-lastmod">© 2024 UserManual.wiki</li>
</ul>
<ul id="footer-places">
<li id="footer-places-privacy"><a href="https://usermanual.wiki/ContactUs" title="UserManual.wiki:Contact Us">Contact Us</a></li>
<li id="footer-places-about"><a href="https://usermanual.wiki/DMCA" title="UserManual.wiki:DMCA">DMCA</a></li>
</ul>
<ul id="footer-icons" class="noprint">
<li id="footer-poweredbyico">

</li>
</ul>

</div>

</div></body></html>
<script src="/cdn-cgi/scripts/7d0fa10a/cloudflare-static/rocket-loader.min.js" data-cf-settings="865286bae73d613c38bad35a-|49" defer></script>