Beruflich Dokumente
Kultur Dokumente
The AmigaDOS
Manual
Commodore-Amiga, Inc.
BANTAM BOOKS
TORONTO NEW YORK LONDON SYDNEY AUCKLAND
AMIGADOS MANUAL
1986
ISBN 0-553-34294-0
Published simultaneously
Bantam Books are published by Bantam Books, Inc. Its trademark, consisting of the
words "Bantam Books" and the portrayal of a rooster, is Registered in U.S. Patent
and Trademark Office and in other countries. Marca Registrada. Bantam Books,
Inc., 666 Fifth Avenue, Nezv York, New York 10103.
P R I N T E D IN T H E U N I T E D S T A T E S O F A M E R I C A
0 9 8 7 6 5 4 3 2 1
Contents
The AmigaDOS User's Manual
The AmigaDOS Developer's Manual
The AmigaDOS Technical Reference Manual
Preface
T h i s b o o k , The AmigaDOS
The AmigaDOS
The AmigaDOS
The AmigaDOS
Manual,
User's
Manual
Developer's
Manual
Technical Reference
Manual
T h e User's Manual
c o n t a i n s i n f o r m a t i o n of i n t e r e s t t o e v e r y A m i g a u s e r .
T h e r e are m a n y m o r e c o m m a n d s that A m i g a D O S understands t h a n are accessible f r o m t h e W o r k b e n c h . If a u s e r u s e s P r e f e r e n c e s to t u r n o n t h e C L I , t h e s e
n e w c o m m a n d s b e c o m e accessible.
T h e Developer's
Manual
describes h o w to use A m i g a D O S from within a
p r o g r a m r a t h e r t h a n f r o m a c o m m a n d line i n t e r f a c e . It a l s o fully d o c u m e n t s
the A m i g a Macro Assembler and Linker. (Note that the A m i g a Macro A s s e m b l e r is available a s a s e p a r a t e p r o d u c t . )
T h e Technical Reference Manual d e s c r i b e s t h e d a t a s t r u c t u r e s t h a t A m i g a D O S
u s e s i n t e r n a l l y . It i n c l u d e s d e s c r i p t i o n s of h o w D O S d i s k d a t a is s t o r e d , a n d
t h e f o r m a t of t h e " o b j e c t - f i l e s " t h a t A m i g a D O S u s e s . A d e v e l o p e r o r e x p e r t
u s e r w o u l d f i n d t h e i n f o r m a t i o n i n t h i s t e c h n i c a l s e c t i o n to b e v e r y u s e f u l .
T o g e t h e r these three publications, in this single v o l u m e , comprise the essential g u i d e t o A m i g a D O S .
AmigaDOS
Manual
Introduction
1.
2.
3.
4.
Introducing AmigaDOS
AmigaDOS Commands
EDThe Screen Editor
EDITThe Line Editor
Introduction
T h i s m a n u a l d e s c r i b e s t h e A m i g a D O S a n d its c o m m a n d s . T h e C o m m a n d L i n e
Interpreter (CLI) reads A m i g a D O S c o m m a n d s typed into a CLI w i n d o w a n d
translates t h e m into actions performed b y the computer. In this s e n s e , the CLI
is similar t o m o r e " t r a d i t i o n a l " c o m p u t e r i n t e r f a c e s : y o u t y p e in c o m m a n d s
a n d t h e i n t e r f a c e d i s p l a y s text in r e t u r n .
B e c a u s e t h e W o r k b e n c h i n t e r f a c e is sufficient a n d f r i e n d l y f o r m o s t u s e r s t h e
W o r k b e n c h diskettes are shipped with the CLI interface " d i s a b l e d " . T o u s e the
c o m m a n d s in t h i s m a n u a l y o u m u s t " e n a b l e " t h e C L I i n t e r f a c e . T h i s p u t s a
n e w icon, labeled " C L I " on your Workbench. W h e n you have selected and
o p e n e d t h i s i c o n , a C L I w i n d o w b e c o m e s a v a i l a b l e , a n d y o u c a n u s e it t o i s s u e
text c o m m a n d s directly to A m i g a D O S .
"Save"
( l o w e r r i g h t p a r t o f t h e P r e f e r e n c e s s c r e e n ) to l e a v e P r e f e r e n c e s .
INTRODUCTION
Chapter 1
Introducing AmigaDOS
T h i s c h a p t e r p r o v i d e s a g e n e r a l o v e r v i e w of t h e A m i g a D O S o p e r a t i n g s y s t e m ,
i n c l u d i n g d e s c r i p t i o n s of t e r m i n a l h a n d l i n g , t h e d i r e c t o r y s t r u c t u r e , a n d c o m m a n d u s e . A t t h e e n d of t h e c h a p t e r , y o u ' l l f i n d a s i m p l e e x a m p l e s e s s i o n w i t h
AmigaDOS
1.1
1.2
1.3
1.3.1
1.3.2
1.3.3
1.3.4
1.3.5
1.3.6
1.3.7
1.4
1.4.1
1.4.2
1.4.3
1.4.4
1.4.5
1.5
1.6
1.7
Chapter Overview
/
Terminal Handling
U s i n g t h e Filing S y s t e m
N a m i n g Files
Using Directories
Setting the Current Directory
Setting the Current Device
Attaching a Filenote
Understanding Device N a m e s
Using Directory Conventions and Logical Devices
Using AmigaDOS Commands
R u n n i n g C o m m a n d s in the Background
Executing C o m m a n d Files
Directing C o m m a n d Input and Output
Interrupting A m i g a D O S
Understanding Command Formats
Restart Validation Process
Commonly Used Commands: A n Example Session
Conventions Used
INTRODUCING AMIGADOS
t a n e o u s l y . Y o u c a n also u s e t h e m u l t i - p r o c e s s i n g facility to s u s p e n d o n e j o b
while you run another.
E a c h A m i g a D O S p r o c e s s r e p r e s e n t s a p a r t i c u l a r p r o c e s s of t h e o p e r a t i n g
s y s t e m f o r e x a m p l e , t h e filing s y s t e m . O n l y o n e p r o c e s s is r u n n i n g at a t i m e ,
w h i l e o t h e r p r o c e s s e s a r e e i t h e r w a i t i n g for s o m e t h i n g t o h a p p e n or h a v e b e e n
i n t e r r u p t e d a n d a r e w a i t i n g to b e r e s u m e d . E a c h p r o c e s s h a s a p r i o r i t y a s s o c i a t e d w i t h it, a n d t h e p r o c e s s w i t h t h e h i g h e s t priority t h a t is f r e e to r u n d o e s
so. Processes of l o w e r priority r u n only w h e n those of h i g h e r priority are
w a i t i n g f o r s o m e r e a s o n f o r e x a m p l e , w a i t i n g for i n f o r m a t i o n to arrive f r o m
the disk.
T h e s t a n d a r d A m i g a D O S s y s t e m u s e s a n u m b e r of p r o c e s s e s t h a t a r e n o t
available t o y o u , f o r e x a m p l e , t h e p r o c e s s t h a t h a n d l e s t h e serial l i n e . T h e s e
processes are k n o w n as private processes. O t h e r private processes h a n d l e the
t e r m i n a l a n d t h e filing s y s t e m o n a d i s k d r i v e . If t h e h a r d w a r e c o n f i g u r a t i o n
c o n t a i n s m o r e t h a n o n e d i s k d r i v e , t h e r e is a p r o c e s s for e a c h d r i v e .
A m i g a D O S p r o v i d e s a p r o c e s s t h a t y o u c a n u s e , called a C o m m a n d L i n e
I n t e r f a c e or C L I . T h e r e m a y b e s e v e r a l C L I p r o c e s s e s r u n n i n g s i m u l t a n e o u s l y ,
numbered from 1 onward. The CLI processes read commands and then
e x e c u t e t h e m . All c o m m a n d s a n d u s e r p r o g r a m s will r u n u n d e r a n y C L I . T o
m a k e additional CLI processes, you use the N E W C L I or R U N c o m m a n d s . T o
r e m o v e a C L I p r o c e s s u s e t h e E N D C L I c o m m a n d . ( Y o u c a n f i n d a full d e s c r i p t i o n of t h e s e c o m m a n d s i n C h a p t e r 2 of this m a n u a l . )
h a v e f i n i s h e d , it s t a r t s to d i s p l a y t h e o u t p u t t h a t it w a s h o l d i n g b a c k . If y o u
w i s h to s t o p t h e o u t p u t s o t h a t y o u c a n r e a d it, s i m p l y t y p e a n y c h a r a c t e r
( p r e s s i n g t h e s p a c e b a r is t h e e a s i e s t ) , a n d t h e o u t p u t s t o p s . T o r e s t a r t o u t p u t ,
p r e s s B A C K S P A C E , C T R L - X , or R E T U R N . P r e s s i n g R E T U R N c a u s e s A m i g a D O S
to try t o e x e c u t e t h e c o m m a n d line t y p e d a f t e r t h e c u r r e n t p r o g r a m e x i t s .
A m i g a D O S recognizes CTRLA as an end-of-file indicator. In certain circums t a n c e s , y o u u s e t h i s c o m b i n a t i o n to t e r m i n a t e a n i n p u t file. ( F o r a c i r c u m stance w h e n you would use CTRLA, see Section 1.3.6.)
If y o u f i n d t h a t s t r a n g e c h a r a c t e r s a p p e a r o n t h e s c r e e n w h e n y o u t y p e
anything on the keyboard, you have probably pressed C T R L - O by mistake.
A m i g a D O S r e c o g n i z e s this c o n t r o l c o m b i n a t i o n as a n i n s t r u c t i o n to t h e c o n s o l e
d e v i c e ( C O N : ) to d i s p l a y t h e a l t e r n a t i v e c h a r a c t e r set. T o u n d o t h i s c o n d i t i o n ,
you press C T R L - N . A n y further characters should then appear as normal. O n
t h e o t h e r h a n d , y o u c o u l d p r e s s E S C - C t o clear t h e s c r e e n a n d d i s p l a y n o r m a l
text.
Note: A n y input through the console device C O N : ignores function keys a n d
c u r s o r k e y s . If y o u w a n t t o r e c e i v e t h e s e k e y s , y o u s h o u l d u s e R A W : . ( F o r a
d e s c r i p t i o n of R A W : , s e e S e c t i o n 1 . 3 . 6 , " U n d e r s t a n d i n g D e v i c e N a m e s , " l a t e r
in t h i s c h a p t e r . )
F i n a l l y , A m i g a D O S r e c o g n i z e s all c o m m a n d s a n d a r g u m e n t s t y p e d in e i t h e r
u p p e r or lower case. A m i g a D O S displays a filename with the characters in the
c a s e u s e d w h e n it w a s c r e a t e d , b u t f i n d s t h e file n o m a t t e r w h a t c o m b i n a t i o n o f
c a s e s y o u u s e to s p e c i f y t h e f i l e n a m e .
INTRODUCING AMIGADOS
enclose the entire filename with double quotes. To introduce a double quote
c h a r a c t e r w i t h i n a f i l e n a m e , y o u m u s t t y p e a n a s t e r i s k (*) i m m e d i a t e l y b e f o r e
that character. In addition, to introduce a n asterisk, y o u m u s t type another
a s t e r i s k . T h i s m e a n s that a file n a m e d
A*B =
C"
s h o u l d b e t y p e d as f o l l o w s :
i n o r d e r f o r t h e C L I to a c c e p t it.
N o t e : T h i s u s e of t h e a s t e r i s k is in c o n t r a s t t o m a n y o t h e r o p e r a t i n g s y s t e m s
w h e r e it is u s e d a s a u n i v e r s a l w i l d c a r d . A n a s t e r i s k b y itself in A m i g a D O S
represents the keyboard and the current window. For example,
COPY f i l e n a m e to *
c o p i e s t h e f i l e n a m e to t h e s c r e e n .
A v o i d s p a c e s b e f o r e or after f i l e n a m e s b e c a u s e t h e y m a y c a u s e c o n f u s i o n .
W A R N I N G : W h e n y o u c r e a t e a file w i t h a f i l e n a m e t h a t a l r e a d y e x i s t s ,
A m i g a D O S d e l e t e s t h e p r e v i o u s c o n t e n t s of t h a t file. N o m e s s a g e to t h a t
effect appears o n the screen.
AMIGADOS USER'S M A N U A L
Y o u c a n a l s o u s e this d i r e c t o r y s t r u c t u r e to o r g a n i z e i n f o r m a t i o n o n t h e d i s k ,
k e e p i n g d i f f e r e n t sorts of files in d i f f e r e n t d i r e c t o r i e s .
A n e x a m p l e m i g h t h e l p to clarify t h i s . C o n s i d e r a d i s k t h a t c o n t a i n s t w o
d i r e c t o r i e s , called " b i l l " a n d " m a r y . " T h e d i r e c t o r y " b i l l " c o n t a i n s t w o files,
called " t e x t " a n d " l e t t e r " . T h e d i r e c t o r y " m a r y " c o n t a i n s a file c a l l e d " d a t a "
a n d t w o d i r e c t o r i e s called " l e t t e r " a n d " i n v o i c e " . T h e s e s u b - d i r e c t o r i e s e a c h
c o n t a i n a file called " j u n l 8 " . F i g u r e 1-A r e p r e s e n t s t h i s s t r u c t u r e a s f o l l o w s :
ROOT
BILL
MARY
TEXT
LETTER
DATA
LETTER
I
JLTN18
HSTVOICE
I
JTTJ5U8
INTRODUCING AMIGADOS
data
Ietter7juiil8
invoice/junl8
Y o u c a n s e t a n y d i r e c t o r y a s t h e c u r r e n t d i r e c t o r y . T o s p e c i f y a n y files w i t h i n
t h a t d i r e c t o r y , s i m p l y t y p e t h e n a m e of t h e file. T o s p e c i f y files w i t h i n s u b d i r e c t o r i e s , y o u n e e d t o t y p e t h e n a m e s of t h e d i r e c t o r i e s o n t h e p a t h f r o m t h e
current directory specified.
All t h e files o n t h e d i s k a r e still available e v e n t h o u g h y o u ' v e s e t u p a c u r r e n t
d i r e c t o r y . To_ i n s t r u c t A m i g a D O S to s e a r c h t h r o u g h t h e d i r e c t o r i e s f r o m t h e
r o o t d i r e c t o r y , y o u t y p e a c o l o n (:) at t h e b e g i n n i n g of t h e file d e s c r i p t i o n .
T h u s , w h e n y o u r file d e s c r i p t i o n h a s t h e c u r r e n t d i r e c t o r y s e t t o " m a r y " , y o u
c a n a l s o o b t a i n t h e file " d a t a " b y t y p i n g t h e d e s c r i p t i o n " : m a r y / d a t a " . U s i n g t h e
c u r r e n t d i r e c t o r y m e t h o d s i m p l y s a v e s t y p i n g , b e c a u s e all y o u h a v e t o d o i s
specify the filename " d a t a " .
T o o b t a i n t h e o t h e r files o n t h e d i s k , first t y p e " : b i l l / t e x t " a n d " : b i l l / l e t t e r "
r e s p e c t i v e l y . A n o t h e r w a y m i g h t b e t o C D or t y p e / b e f o r e a f i l e n a m e . S l a s h
d o e s n o t m e a n " r o o t " a s i n s o m e s y s t e m s , b u t r e f e r s to t h e d i r e c t o r y a b o v e t h e
c u r r e n t d i r e c t o r y . A m i g a D O S a l l o w s m u l t i p l e s l a s h e s . E a c h s l a s h r e f e r s to t h e
level a b o v e . S o a U n i x ( T M ) ../ is a / in A m i g a D O S . S i m i l a r l y , a n M S - D O S
.A is a / i n A m i g a D O S . t h u s , if t h e c u r r e n t d i r e c t o r y is " : m a r y / l e t t e r " , y o u m a y
s p e c i f y t h e file " : m a r y / i n v o i c e / j u n l 8 " a s " / i n v o i c e / j u n l 8 " . T o r e f e r to t h e files
in " : b i l l " , y o u c o u l d t y p e :
CD .-bill
or
CD //bill
T h e n y o u c o u l d s p e c i f y a n y file i n " b i l l " w i t h a s i n g l e f i l e n a m e . O f c o u r s e , y o u
c o u l d a l w a y s u s e t h e // f e a t u r e to r e f e r directly to a specific file. F o r e x a m p l e ,
T Y P E //bill/letter
d i s p l a y s t h e file w i t h o u t y o u r first s e t t i n g " b i l l " a s t h e c u r r e n t d i r e c t o r y . T o g o
s t r a i g h t t o t h e r o o t l e v e l , a l w a y s t y p e a c o l o n (:) f o l l o w e d b y a d i r e c t o r y n a m e . If
y o u use slashes, y o u m u s t k n o w the exact n u m b e r of levels back desired.
10
E a c h i n d i v i d u a l d i s k is also a s s o c i a t e d w i t h a u n i q u e n a m e , k n o w n a s a v o l u m e
n a m e (see b e l o w for m o r e details).
In a d d i t i o n , t h e logical d e v i c e S Y S : is a s s i g n e d to t h e d i s k y o u s t a r t e d t h e
s y s t e m u p f r o m . Y o u c a n u s e this n a m e i n p l a c e of a d i s k d e v i c e n a m e (like
DFO:).
T h e c u r r e n t d i r e c t o r y is also a s s o c i a t e d w i t h a c u r r e n t d r i v e , t h e d r i v e w h e r e
y o u m a y f i n d t h e d i r e c t o r y . A s y o u k n o w , p r e f a c i n g a file d e s c r i p t i o n w i t h a
c o l o n s e r v e s to i d e n t i f y t h e r o o t d i r e c t o r y of t h e c u r r e n t d r i v e . H o w e v e r , t o
g i v e t h e r o o t d i r e c t o r y of a specific d r i v e , y o u p r e c e d e t h e c o l o n w i t h t h e d r i v e
n a m e . T h u s , y o u h a v e y e t a n o t h e r w a y of s p e c i f y i n g t h e file " d a t a " in d i r e c t o r y
" m a r y " , t h a t is " D F l : m a r y / d a t a " . T h i s a s s u m e s t h a t y o u h a v e i n s e r t e d t h e d i s k
i n t o d r i v e D F 1 . S o , to r e f e r e n c e a file o n t h e d r i v e DFO called " p r o j e c t - r e p o r t " in
directory " p e t e r " , you would type "DFO:peter/project-report", no matter which
d i r e c t o r y y o u h a d s e t as t h e c u r r e n t o n e .
N o t e : W h e n y o u r e f e r to a d i s k drive or a n y o t h e r d e v i c e , o n its o w n o r w i t h
a directory n a m e , y o u should always type the colon, for e x a m p l e , D F 1 : .
F i g u r e 1-B illustrates t h e s t r u c t u r e of a file d e s c r i p t i o n . F i g u r e 1-C g i v e s s o m e
e x a m p l e s o f v a l i d file d e s c r i p t i o n s .
Left o f t h e :
R i g h t of t h e :
R i g h t o f a/
Device name
Directory n a m e
Subdirectory n a m e
or
or
or
Volume name
Filename
Filename
INTRODUCING AMIGADOS
11
A d e v i c e n a m e , u n l i k e a v o l u m e n a m e , is n o t really p a r t of t h e n a m e . F o r
e x a m p l e , A m i g a D O S c a n r e a d a file y o u c r e a t e d o n DFO: f r o m a n o t h e r d r i v e ,
s u c h a s D F 1 : , if y o u p l a c e t h e d i s k in t h a t d r i v e , a s s u m i n g of c o u r s e t h a t t h e
d r i v e s a r e i n t e r c h a n g e a b l e . T h a t i s , if y o u c r e a t e a file called " b i l l " o n a d i s k in
d r i v e DFO:, t h e file is k n o w n a s " D F O . b i l l " . If y o u t h e n m o v e t h e d i s k t o d r i v e
D F 1 : , A m i g a D O S c a n still r e a d t h e file, w h i c h is t h e n k n o w n a s " D F l : b i l l " .
RAM:
i m p l e m e n t s a filing s y s t e m i n m e m o r y t h a t s u p p o r t s a n y o f t h e n o r m a l filing
system commands.
N o t e : R A M : r e q u i r e s t h e library 1 / r a m - h a n d l e r to b e o n t h e d i s k .
O n c e the device R A M : exists, you can, for instance, create a directory to
c o p y all t h e c o m m a n d s i n t o m e m o r y . T o d o t h i s , t y p e t h e f o l l o w i n g c o m m a n d s :
12
MAKEDIR ram:c
COPY s y s : c TO r a m : c
A S S I G N C: R A M : C
Y o u c o u l d t h e n l o o k at
d i r e c t o r y " c " ( D I R lists t h i s
q u i c k b u t w o u l d l e a v e little
R A M : d e v i c e a r e lost w h e n
t h e o u t p u t w i t h D I R R A M : . It w o u l d i n c l u d e t h e
as c(dir).) T h i s w o u l d m a k e l o a d i n g c o m m a n d s v e r y
r o o m in m e m o r y for a n y t h i n g e l s e . A n y files in t h e
y o u reset the machine.
A m i g a D O S a l s o p r o v i d e s a n u m b e r of o t h e r d e v i c e s t h a t y o u c a n u s e i n s t e a d
of a r e f e r e n c e to a d i s k file. T h e f o l l o w i n g p a r a g r a p h s d e s c r i b e t h e s e d e v i c e s
i n c l u d i n g N I L : , S E R : , P A R : , P R T : , C O N : , a n d R A W : . In p a r t i c u l a r , t h e d e v i c e
N I L : is. a d u m m y device. A m i g a D O S simply throws away output written to
NIL:. While reading from NIL:, A m i g a D O S gives an immediate "end-of-file"
indication. For example, you would type the following
E D I T a b c TO n i l :
t o u s e t h e e d i t o r to b r o w s e t h r o u g h a file, w h i l e A m i g a D O S t h r o w s a w a y t h e
edited output.
Y o u u s e t h e d e v i c e called S E R : to r e f e r to a n y d e v i c e c o n n e c t e d t o t h e serial
line ( o f t e n a p r i n t e r ) . T h u s , y o u w o u l d t y p e t h e f o l l o w i n g c o m m a n d s e q u e n c e :
C O P Y x y z TO s e r :
t o i n s t r u c t A m i g a D O S t o s e n d t h e c o n t e n t s of t h e file " x y z " d o w n t h e serial l i n e .
N o t e t h a t t h e serial d e v i c e o n l y c o p i e s in m u l t i p l e s of 4 0 0 b y t e s at a t i m e .
Copying with SER: can therefore appear granular.
T h e d e v i c e P A R : r e f e r s to t h e p a r a l l e l p o r t i n t h e s a m e w a y .
A m i g a D O S a l s o p r o v i d e s t h e d e v i c e P R T : (for P R i n T e r ) . P R T : is t h e p r i n t e r
y o u chose in the " p r e f e r e n c e s " program. In this program, y o u can define your
p r i n t e r t o b e c o n n e c t e d t h r o u g h e i t h e r t h e serial o r p a r a l l e l p o r t . T h u s , t h e
command sequence
C O P Y xyz T O PRT:
p r i n t s t h e file " x y z , " n o m a t t e r h o w t h e p r i n t e r is c o n n e c t e d .
P R T : t r a n s l a t e s e v e r y l i n e f e e d c h a r a c t e r i n a file to c a r r i a g e r e t u r n p l u s
l i n e f e e d . S o m e p r i n t e r s , h o w e v e r , r e q u i r e files w i t h o u t t r a n s l a t i o n . T o s e n d a
file w i t h t h e l i n e f e e d s a s j u s t l i n e f e e d s , y o u u s e P R T : R A W i n s t e a d of P R T : .
A m i g a D O S supports multiple windows. To make a n e w w i n d o w , you can
s p e c i f y t h e d e v i c e C O N : . T h e f o r m a t f o r C O N : is a s f o l l o w s :
CON:x/y/width/height/[title]
^INTRODUCING AMIGADOS
13
w h e r e " x " and " y " are coordinates, " w i d t h " and " h e i g h t " are integers describi n g t h e w i d t h a n d h e i g h t of t h e n e w w i n d o w , a n d " t i t l e " , w h i c h is o p t i o n a l , is
a s t r i n g . T h e title a p p e a r s o n t h e w i n d o w ' s title b a r . Y o u m u s t i n c l u d e all t h e
s l a s h e s (/), i n c l u d i n g t h e last o n e . Y o u r title c a n i n c l u d e u p to t h i r t y c h a r a c t e r s
( i n c l u d i n g s p a c e s ) . If t h e title h a s s p a c e s , y o u m u s t e n c l o s e t h e w h o l e d e s c r i p t i o n ii d o u b l e q u o t e s (") as s h o w n i n t h e f o l l o w i n g e x a m p l e :
"CON:20/10/300/100/my window"
T h e r e is a n o t h e r w i n d o w d e v i c e c a l l e d R A W : , b u t it is o f little u s e to t h e
g e n e r a l u s e r . ( S e e C h a p t e r 2 of t h e AmigaDOS
Developer's
Manual i n t h i s b o o k
f o r f u r t h e r d e t a i l s . ) Y o u c a n u s e R A W : to c r e a t e a r a w w i n d o w d e v i c e similar t o
C O N : . H o w e v e r , unlike C O N : , R A W : does no character translation and does
n o t allow y o u to c h a n g e the contents of a line. That is to say, R A W : accepts
i n p u t a n d r e t u r n s o u t p u t i n exactly t h e s a m e f o r m t h a t it w a s originally t y p e d .
T h i s m e a n s c h a r a c t e r s are s e n t to a p r o g r a m i m m e d i a t e l y w i t h o u t l e t t i n g y o u
erase anything with the B A C K S P A C E key. Y o u usually use R A W : from a
p r o g r a m w h e r e y o u might w a n t to do input and output without character
translation.
W A R N I N G : R A W : is i n t e n d e d f o r t h e a d v a n c e d u s e r . D o n o t u s e R A W :
experimentally.
T h e r e is o n e s p e c i a l n a m e , w h i c h is * ( a s t e r i s k ) . Y o u u s e t h i s t o r e f e r t o t h e
current w i n d o w , both for input or for output. Y o u can u s e the C O P Y c o m m a n d to c o p y f r o m o n e file t o a n o t h e r . U s i n g *, y o u c a n c o p y f r o m t h e c u r r e n t
w i n d o w to a n o t h e r w i n d o w , for e x a m p l e ,
COPY * TO C01ir:20/S0/350/150/
f r o m t h e c u r r e n t w i n d o w t o t h e c u r r e n t w i n d o w , for e x a m p l e ,
COPY * TO *
o r f r o m a file t o t h e c u r r e n t w i n d o w , f o r e x a m p l e ,
COPY b i l l / l e t t e r TO *
A m i g a D O S f i n i s h e s c o p y i n g w h e n it c o m e s to t h e e n d of t h e file. T o tell
A m i g a D O S to s t o p c o p y i n g f r o m *, y o u m u s t g i v e t h e C T R L A c o m b i n a t i o n .
N o t e t h a t * is N O T t h e u n i v e r s a l w i l d c a r d .
14
Description
SYS:
C:
L:
s:
LIBS:
DEVS:
FONTS:
D e v i c e for O p e n D e v i c e calls
L o a d a b l e f o n t s for O p e n F o n t s
Temporary workspace
Directory
C
L
S
LIBS
DEVS
FONTS
T
device name:
SYS:
directory name:
My.Boot.Disk:
device
Typical
directory
name:
C:
name:
My.Boot.Diskx
device
Typical
directory
name:
L:
name:
My.Boot.Disk:l
INTRODUCING AMIGADOS
15
My.Boot.Disk:c
My.Boot.Disk:l
S:
LIBS:
DEVS:
FONTS:
My.Boot.Disk: s
My.Boot.Disk.libs
My.Boot.Disk:devs
My.Boot.Disk:fonts
16
If a d i r e c t o r y is n o t p r e s e n t , t h e c o r r e s p o n d i n g logical d e v i c e is a s s i g n e d to
the root directory.
If y o u a r e s o l u c k y a s to h a v e a h a r d d i s k (called DHO:) a n d y o u w a n t t o u s e
t h e s y s t e m files o n it, y o u m u s t i s s u e t h e f o l l o w i n g c o m m a n d s to t h e s y s t e m :
ASSIGN
ASSIGN
ASSIGN
ASSIGN
SYS:
C
L:
S
ASSIGN LIBS:
ASSIGN DEVS:
A S S I G N FONTS:
DHO:
DHO:C
DHO:L
DHO:S
DHO:LIBS
DHO:DEVS
DHO:FONTS
Commands
A n A m i g a D O S c o m m a n d c o n s i s t s of t h e c o m m a n d n a m e a n d its a r g u m e n t s , if
a n y . T o e x e c u t e a n A m i g a D O S c o m m a n d , y o u t y p e t h e c o m m a n d n a m e a n d its
a r g u m e n t s after the CLI prompt.
W h e n y o u t y p e a c o m m a n d n a m e , t h e c o m m a n d r u n s a s p a r t of t h e C o m m a n d Line Interface (CLI). Y o u can type other c o m m a n d n a m e s ahead, but
A m i g a D O S does n o t execute t h e m until the current c o m m a n d has finished.
W h e n a c o m m a n d h a s f i n i s h e d , t h e c u r r e n t C L I p r o m p t a p p e a r s . I n this c a s e ,
t h e c o m m a n d is r u n n i n g interactively.
T h e C L I p r o m p t is initially n > , w h e r e n is t h e n u m b e r of t h e C L I p r o c e s s .
H o w e v e r , it c a n b e c h a n g e d to s o m e t h i n g else w i t h t h e P R O M P T c o m m a n d .
( F o r f u r t h e r details o n t h e P R O M P T c o m m a n d , s e e C h a p t e r 2 of t h i s m a n u a l . )
17
INTRODUCING AMIGADOS
W A R N I N G : If y o u r u n a c o m m a n d i n t e r a c t i v e l y a n d it fails, A m i g a D O S
c o n t i n u e s to e x e c u t e t h e n e x t c o m m a n d y o u t y p e d a n y w a y . T h e r e f o r e , it
c a n b e d a n g e r o u s to t y p e m a n y c o m m a n d s a h e a d . F o r e x a m p l e , if y o u
type
C O P Y a TO b
DELETE a
a n d t h e C O P Y c o m m a n d fails ( p e r h a p s b e c a u s e t h e d i s k is full), t h e n D E L E T E
e x e c u t e s a n d y o u l o s e y o u r file.
a s k A m i g a D O S t o carry o u t s e v e r a l c o m m a n d s u s i n g R U N . R U N
c o m m a n d a n d carries it o u t in t h e g i v e n o r d e r . T h e l i n e c o n t a i n i n g
a f t e r R U N is called a c o m m a n d l i n e . T o t e r m i n a t e t h e c o m m a n d
R E T U R N . T o e x t e n d y o u r c o m m a n d line o v e r s e v e r a l l i n e s , t y p e a
( + ) b e f o r e p r e s s i n g R E T U R N o n e v e r y line e x c e p t t h e last. F o r
18
A m i g a D O S d o e s n o t e x e c u t e s u b s e q u e n t c o m m a n d s o n t h e R U N line or in t h e
file u s e d b y E X E C U T E , u n l e s s y o u h a v e u s e d t h e F A I L A T c o m m a n d . S e e
C h a p t e r 2 of t h i s m a n u a l f o r details o n t h e F A I L A T c o m m a n d . T h e C L I o n l y
gives p r o m p t s after executing c o m m a n d s that have run interactively.
text_file
S e e C h a p t e r 2 of t h e User's
symbols.
Manual
f o r a full s p e c i f i c a t i o n of t h e <
and
>
INTRODUCING AMIGADOS
19
I n t h i s c a s e , y o u p r o v i d e t h e a r g u m e n t s in t h e s a m e o r d e r a s t h e
k e y w o r d list i n d i c a t e s .
In this c a s e , t h e o r d e r d o e s n o t m a t t e r , a n d y o u p r e c e d e e a c h
argument with the relevant keyword.
F o r e x a m p l e , if t h e c o m m a n d M Y C O M M A N D r e a d f r o m o n e file a n d w r o t e to
another, the argument template would be:
FROMTO
Y o u could use the c o m m a n d specifying the arguments by position:
MYCOMMAND input-file output-file
or u s i n g t h e k e y w o r d s :
M Y C O M M A N D F R O M i n p u t - f i l e TO o u t p u t - f i l e
M Y C O M M A N D TO o u t p u t - f i l e F R O M i n p u t - f i l e
Y o u could also combine the positional and keyword argument specifications,
for e x a m p l e , with the following:
M Y C O M M A N D i n p u t - f i l e TO o u t p u t - f i l e
w h e r e y o u give t h e F R O M a r g u m e n t b y p o s i t i o n , a n d t h e T O a r g u m e n t b y
k e y w o r d . N o t e t h a t t h e f o l l o w i n g f o r m is i n c o r r e c t :
MYCOMMAND output-file FROM input-file
b e c a u s e t h e c o m m a n d a s s u m e s t h a t ' o u t p u t - f i l e ' is t h e first p o s i t i o n a l a r g u m e n t
(that i s , t h e F R O M file).
20
name
T h e a r g u m e n t is r e q u i r e d a n d m a y n o t b e o m i t t e d .
T h e argument must be given with the keyword and may not be used
positionally.
/S
T h e k e y w o r d is a s w i t c h (that i s , a t o g g l e ) a n d t a k e s n o a r g u m e n t .
command
D E L E T E s i m p l y t a k e s a n u m b e r of files for A m i g a D O S to d e l e t e . In t h i s c a s e ,
y o u simply omit the k e y w o r d value, b u t the c o m m a s normally u s e d to separate
t h e k e y w o r d s r e m a i n in t h e t e m p l a t e . T h u s , t h e t e m p l a t e f o r D E L E T E , t h a t c a n
t a k e u p to t e n f i l e n a m e s , is
) ) ) ) )
F i n a l l y , c o n s i d e r t h e c o m m a n d T Y P E . T h e a r g u m e n t t e m p l a t e is
FROM/A,TO,OPT/K
w h i c h m e a n s t h a t y o u m a y g i v e t h e first a r g u m e n t b y p o s i t i o n or b y k e y w o r d ,
b u t t h a t first a r g u m e n t is r e q u i r e d . T h e s e c o n d a r g u m e n t ( T O ) is o p t i o n a l , a n d
y o u m a y o m i t t h e k e y w o r d . T h e O P T a r g u m e n t is o p t i o n a l , b u t if it is g i v e n ,
y o u m u s t p r o v i d e t h e k e y w o r d . S o , t h e f o l l o w i n g a r e all valid f o r m s of t h e
TYPE command:
INTRODUCING AMIGADOS
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
TYPE
21
filename
PROM filename
f i l e n a m e TO o u t p u t - f i l e
f i l e n a m e output-file
TO o u t p u t - f i l e F R O M f i l e n a m e OPT n
f i l e n a m e OPT n
f i l e n a m e OPT n TO o u t p u t - f i l e
DATE
c o m m a n d . If y o u d o n o t s p e c i f y t h e s y s t e m d a t e , A m i g a D O S s e t s t h e s y s t e m
d a t e to t h e d a t e a n d t i m e o f t h e m o s t r e c e n t l y c r e a t e d file o n t h e i n s e r t e d d i s k .
T h i s e n s u r e s t h a t n e w e r v e r s i o n s of files h a v e m o r e r e c e n t d a t e s , e v e n t h o u g h
t h e a c t u a l t i m e a n d d a t e will b e i n c o r r e c t .
If y o u a s k f o r t h e d a t e a n d t h e t i m e b e f o r e t h e v a l i d a t i o n is c o m p l e t e ,
A m i g a D O S displays the date a n d time as unset. Y o u can t h e n either wait for
t h e v a l i d a t i o n t o c o m p l e t e o r u s e D A T E to e n t e r t h e c o r r e c t d a t e a n d t i m e .
V a l i d a t i o n s h o u l d h a p p e n at o n c e ; o t h e r w i s e , it s h o u l d n e v e r t a k e l o n g e r t h a n
one minute.
22
t o d i s p l a y a list of files ( a n d d i r e c t o r i e s ) in t h e c u r r e n t
disk
d i r e c t o r y . T h i s is a list o f files t h a t m a k e s u p y o u r W o r k b e n c h . Y o u m a y n o t i c e
t h a t t h e r e a r e m a n y m o r e files in t h i s d i r e c t o r y t h a n t h e r e a r e i c o n s o n t h e
W o r k b e n c h . T h e r e a s o n f o r this is t h a t W o r k b e n c h will o n l y d i s p l a y file " X " if it
h a s a n a s s o c i a t e d " X . i n f o " file. In fact t h e " . i n f o " ( p r o n o u n c e d " d o t i n f o " ) file
c o n t a i n s all of t h e i c o n d i s p l a y i n f o r m a t i o n .
F o r e x a m p l e , t h e d i s k c o p y p r o g r a m h a s t w o files a s s o c i a t e d w i t h it. T h e
file " D i s k c o p y " c o n t a i n s t h e p r o g r a m a n d " D i s k c o p y . i n f o " c o n t a i n s t h e W o r k b e n c h i n f o r m a t i o n a b o u t it. I n t h e c a s e o f p a i n t i n g d a t a files l i k e " m o u n t . p i c " ,
t h e file " m o u n t . p i c . i n f o " c o n t a i n s i c o n i n f o r m a t i o n a n d t h e n a m e of t h e p r o g r a m (default) t h a t s h o u l d p r o c e s s it ( G r a p h i C r a f t ) . In this c a s e , w h e n
the
INTRODUCING AMIGADOS
23
24
T e l l A m i g a D O S w h e r e to l o o k for c e r t a i n t h i n g s ( A S S I G N )
Open a new CLI window (NEWCLI)
Close an existing CLI w i n d o w (ENDCLI)
All of the c o m m a n d sequences below a s s u m e that y o u have started your
s y s t e m w i t h a C L I disk r a t h e r t h a n a W o r k b e n c h d i s k , or t h a t y o u h a v e t u r n e d
o n the CLI using the preferences tool a n d h a v e entered the CLI b y that path.
T h e s e q u e n c e for t u r n i n g o n t h e C L I is p r o v i d e d earlier i n t h i s m a n u a l .
How to Begin
Before y o u begin this section, b e sure y o u h a v e two blank, double-sided
d i s k e t t e s , a n d e i t h e r y o u r W o r k b e n c h disk or y o u r C L I d i s k . B e f o r e y o u b e g i n ,
write-protect your master diskette, and write-enable the blank diskettes. M o s t
of t h e c o m m a n d s g i v e n b e l o w a s s u m e t h a t y o u h a v e a s i n g l e - d r i v e s y s t e m ;
h o w e v e r , for c o n v e n i e n c e of t h o s e w i t h d u a l - d r i v e s y s t e m s , t h e d u a l - d r i v e
version of the c o m m a n d is occasionally given.
C o m m a n d s t h a t i n s t r u c t A m i g a D O S t o e x e c u t e are s h o w n i n t h e f o l l o w i n g
s e c t i o n s , i n d e n t e d f r o m t h e left m a r g i n . A f t e r t y p i n g e a c h c o m m a n d , p r e s s t h e
R E T U R N k e y to r e t u r n c o n t r o l to A m i g a D O S . A l t h o u g h t h e c o m m a n d s are all
s h o w n i n capital l e t t e r s , t h i s is s i m p l y t o d i s t i n g u i s h t h e m f r o m t h e r e s t of
t h e text. A m i g a D O S will a c c e p t t h e c o m m a n d s i n l o w e r c a s e a s w e l l a s u p p e r
case.
In the sections that follow, the notations "dfO:" and "drive 0 " refer to the
d i s k drive t h a t is built i n t o t h e A m i g a . T h e n o t a t i o n " d f l : " r e f e r s to t h e first
e x t e r n a l 3y2-inch disk d r i v e .
Y o u will o c c a s i o n a l l y s e e a s e m i c o l o n o n a c o m m a n d line t h a t y o u are t o l d t o
t y p e . W h a t f o l l o w s t h e s e m i c o l o n is t r e a t e d a s a c o m m e n t b y A m i g a D O S . S i n c e
A m i g a D O S i g n o r e s t h e r e s t of t h e l i n e , y o u d o n ' t n e e d to t y p e t h e c o m m e n t
a l o n g w i t h t h e c o m m a n d . It is f o r y o u r i n f o r m a t i o n o n l y .
F o r m o s t c o m m a n d s , y o u c a n g e t a v e r y l i m i t e d f o r m of h e l p b y t y p i n g t h e
c o m m a n d n a m e , f o l l o w e d b y a q u e s t i o n m a r k (?) a n d p r e s s i n g R E T U R N . It
s h o w s y o u t h e " t e m p l a t e " of a c o m m a n d , c o n t a i n i n g t h e s e q u e n c e of p a r a m e t e r s it e x p e c t s a n d t h e k e y w o r d s it r e c o g n i z e s .
INTRODUCING AMIGADOS
25
Copying a Disk
Y o u c a n u s e t h i s s e q u e n c e to b a c k u p y o u r s y s t e m m a s t e r d i s k o r a n y o t h e r
disk.
For a 1 disk system
D I S K C O P Y F R O M dfO: TO dfO:
For a 2 disk system
D I S K C O P Y F R O M dfO: TO d f l :
F o l l o w t h e i n s t r u c t i o n s as t h e y a p p e a r . F o r a single drive s y s t e m , y o u ' l l b e
instructed to insert the master ( F R O M ) disk. T h e n , as the copying progresses,
A m i g a D O S a s k s y o u to i n s e r t t h e c o p y ( T O ) d i s k , s w a p p i n g m a s t e r a n d c o p y
i n a n d o u t u n t i l all of t h e d i s k e t t e h a s b e e n d u p l i c a t e d . F o r a t w o d i s k s y s t e m ,
y o u ' l l b e i n s t r u c t e d t o p u t t h e m a s t e r d i s k e t t e i n t o d r i v e dfO: ( t h e b u i l t - i n
drive) a n d t h e c o p y d i s k e t t e o n t o w h i c h to c o p y i n t o d f l : ( t h e first e x t e r n a l
drive).
R e m o v e y o u r m a s t e r d i s k e t t e (either W o r k b e n c h o r C L I d i s k ) a n d p u t y o u r
m a s t e r d i s k e t t e in a safe p l a c e . L e a v e t h e c o p y w r i t e - e n a b l e d s o t h a t y o u c a n
s t o r e i n f o r m a t i o n o n it. I n s e r t t h e c o p y y o u h a v e j u s t m a d e i n t o t h e b u i l t - i n
d r i v e a n d r e b o o t y o u r s y s t e m f r o m t h e c o p y . ( S e e I n t r o d u c t i o n T o A m i g a for
the reboot process).
A f t e r t h e r e b o o t , r e e n t e r t h e C L I m o d e a g a i n . If y o u b o o t w i t h a C L I d i s k ,
t h e r e b o o t e n t e r s t h e C L I a u t o m a t i c a l l y . If y o u a r e u s i n g a W o r k b e n c h d i s k ,
y o u m u s t o p e n t h e C L I i c o n in t h e s y s t e m d r a w e r of t h e W o r k b e n c h .
Formatting a Disk
T o t r y t h i s c o m m a n d , y o u r W o r k b e n c h or C L I d i s k e t t e c o p y s h o u l d b e in d r i v e
0, a n d y o u should have a blank diskette available.
S o m e t i m e s r a t h e r t h a n s i m p l y c o p y a d i s k , y o u ' l l w a n t to p r e p a r e a d a t a d i s k
f o r y o u r s y s t e m . T h e n later y o u c a n c o p y s e l e c t e d files to this d a t a d i s k . F o r m a t
your s e c o n d blank disk b y using the F O R M A T c o m m a n d :
F O R M A T D R I V E dfO: N A M E " A n y N a m e "
F o l l o w t h e i n s t r u c t i o n s . Y o u c a n f o r m a t d i s k e t t e s in e i t h e r d r i v e 0 (dfO:, b u i l t in
to y o u r A m i g a ) or a n e x t e r n a l d r i v e .
A f t e r t h e f o r m a t is c o m p l e t e d , w a i t for t h e d i s k activity l i g h t to g o off a n d
26
r e m o v e t h e f r e s h l y f o r m a t t e d d i s k e t t e . R e i n s e r t y o u r W o r k b e n c h or C L I d i s k e t t e . T h e f o r m a t t e d d i s k e t t e c a n n o w b e u s e d to h o l d d a t a files. It is n o t
bootable, however.
INTRODUCING AMIGADOS
27
R E N A M E P R O M s / s t a r t u p - s e q u e n c e TO s / N O - s t a r t u p - s e q u e n c e
N o w if y o u w a i t f o r t h e d i s k activity l i g h t t o g o off a n d p e r f o r m a full r e s e t ,
y o u r W o r k b e n c h d i s k e t t e c o p y will h a v e b e c o m e a C L I . T o r e s t o r e t h e W o r k bench, perform the rename again, but with the n a m e sequence reversed. You
s e e , if A m i g a D O S c a n ' t f i n d a file w i t h t h e e x a c t n a m e " s t a r t u p - s e q u e n c e " in
t h e " s " d i r e c t o r y , it will e n t e r c o m m a n d m o d e a n d w a i t f o r y o u to t y p e a
command.
Relabeling a Disk
B e f o r e y o u try t h i s c o m m a n d , y o u r W o r k b e n c h or C L I d i s k e t t e c o p y s h o u l d b e
in d r i v e 0.
If, a f t e r e i t h e r c o p y i n g or f o r m a t t i n g a d i s k e t t e , y o u a r e n o t s a t i s f i e d w i t h t h e
v o l u m e n a m e y o u h a v e g i v e n it, y o u c a n c h a n g e t h e n a m e of t h e v o l u m e b y
using the RELABEL command:
relabel AnyName: DifferentName
I n t h i s e x a m p l e , w e h a v e r e f e r r e d t o t h e d i s k e t t e w e j u s t f o r m a t t e d b y its
v o l u m e n a m e . Y o u will b e a s k e d t o i n s e r t v o l u m e A n y N a m e i n t o a n y d i s k
d r i v e s o t h a t R E L A B E L c a n r e l a b e l it.
After this c o m m a n d completes, r e m o v e the diskette a n d reinsert y o u r
W o r k b e n c h or CLI diskette. T h e diskette you removed n o w has the n e w n a m e .
28
AMIGADOS USER'S M A N U A L
DIR dfl:
lists t h e c o n t e n t s o f a d i s k e t t e i n s e r t e d i n d r i v e 1 ( t h e first e x t e r n a l d r i v e if y o u
have one attached).
Y o u c a n e v e n l o o k at t h e d i r e c t o r y of a d i s k e t t e t h a t i s n ' t c u r r e n t l y i n t h e
d r i v e b y s p e c i f y i n g its v o l u m e n a m e . F o r e x a m p l e , t h e c o n t e n t s of t h a t f r e s h l y
formatted diskette w h o s e n a m e w e changed can be displayed b y the c o m m a n d :
DIR DifferentName:
A m i g a D O S will a s k y o u to i n s e r t d i s k e t t e D i f f e r e n t N a m e i n t o t h e d r i v e s o t h a t
D I R c a n r e a d it a n d r e p o r t t h e c o n t e n t s of t h e d i r e c t o r y . D o n ' t d o it y e t ,
h o w e v e r , b e c a u s e t h e r e a r e n o files p r e s e n t f o r D I R to r e a d . W e ' l l a d d s o m e
files l a t e r .
29
INTRODUCING AMIGADOS
" . N o w if y o u
try:
DELETE myfile
AmigaDOS responds:
"Not Deleted - file is p r o t e c t e d f r o m deletion"
T o r e e n a b l e d e l e t i o n o f t h e file:
P R O T E C T m y f i l e d or P R O T E C T m y f i l e r w e d
the
INFO
It tells y o u h o w m u c h s p a c e is u s e d a n d h o w m u c h is free o n y o u r d i s k e t t e s ,
w h e t h e r t h e y a r e r e a d - o n l y or r e a d - w r i t e , a n d t h e n a m e of t h e v o l u m e . Y o u
c a n m a k e m o r e s p a c e o n t h e d i s k e t t e b y d e l e t i n g files. Y o u c a n c h a n g e t h e
n a m e of t h e v o l u m e b y u s i n g t h e R E L A B E L c o m m a n d .
If y o u w a n t to g e t i n f o r m a t i o n a b o u t a d i s k t h a t i s n ' t in y o u r s i n g l e - d r i v e at
the m o m e n t , issue the c o m m a n d as:
INFO ?
AmigaDOS responds:
none:
30
AMIGADOS USER'S M A N U A L
INTRODUCING AMIGADOS
31
datefile
E x e c u t e t h e c o m m a n d s o t h a t y o u c a n u s e t h e datefile d e s c r i b e d b e l o w . T h i s
c o m m a n d creates (or overwrites) a file n a m e d " d a t e f i l e " in y o u r c u r r e n t directory.
O r , j u s t to h a v e s o m e t h i n g o n t h a t f o r m a t t e d d i s k e t t e n a m e d D i f f e r e n t N a m e ,
type the following:
DATE >
DifferentName:datefile
A m i g a D O S p r o m p t s y o u to i n s e r t t h e v o l u m e w i t h t h a t n a m e . A f t e r t h e d i s k
activity l i g h t g o e s o u t , r e m o v e D i f f e r e n t N a m e a n d r e i n s e r t y o u r C L I o r W o r k b e n c h diskette. N o w issue the c o m m a n d :
DIR DifferentName:
Again y o u are p r o m p t e d to insert DifferentName into any drive. A m i g a D O S
lists t h e d i r e c t o r y of this d i s k e t t e , w h i c h n o w c o n t a i n s a file n a m e d d a t e f i l e .
R e p l a c e y o u r C L I or W o r k b e n c h d i s k e t t e i n t h e d r i v e .
32
Deleting Files
T o try t h i s c o m m a n d , y o u r W o r k b e n c h or C L I d i s k e t t e s h o u l d b e i n d r i v e 0.
Y o u m a y b e w o r k i n g o n s e v e r a l v e r s i o n s of a p r o g r a m o r textfile, a n d
e v e n t u a l l y w i s h t o d e l e t e v e r s i o n s of t h a t file t h a t y o u d o n ' t n e e d a n y m o r e .
T h e D E L E T E c o m m a n d lets y o u e r a s e files a n d r e l e a s e s t h e d i s k s p a c e to
A m i g a D O S for reuse.
N o t e : If y o u D E L E T E files, it is n o t p o s s i b l e to r e t r i e v e t h e m . B e c e r t a i n t h a t
y o u really d o w i s h t o d e l e t e t h e m .
H e r e is a s a m p l e c o m m a n d s e q u e n c e , t h a t c r e a t e s a file u s i n g t h e r e d i r e c t i o n
c o m m a n d , t y p e s it to v e r i f y t h a t it is really t h e r e , t h e n d e l e t e s it.
DIR > directorystuff
TYPE directorystuff
DELETE directorystuff
TYPE directorystuff
T o t h e final c o m m a n d in t h e a b o v e s e q u e n c e , A m i g a D O S r e s p o n d s :
INTRODUCING AMIGADOS
33
Copying Files
Before y o u enter this c o m m a n d , your W o r k b e n c h or CLI diskette should b e in
d r i v e 0.
O n a d u a l - d r i v e s y s t e m , c o p y i n g files is e a s y :
C O P Y F R O M d f O : s o u r c e p a t h TO d f l : d e s t i n a t i o n p a t h
or
COPY dfO:sourcepath d f l : d e s t l n a t i o n p a t h
O n a s i n g l e - d r i v e s y s t e m , c o p y i n g files is a little m o r e c o m p l e x . Y o u m u s t
c o p y c e r t a i n s y s t e m files f r o m y o u r s y s t e m d i s k e t t e i n t o t h e s y s t e m m e m o r y .
T h i s is also called u s i n g t h e R A M : d e v i c e , o f t e n k n o w n a s a r a m d i s k . C o p y t h e
file(s) t o t h e r a m d i s k , c h a n g e y o u r d i r e c t o r y to t h e r a m d i s k , t h e n c o p y f r o m t h e
r a m d i s k o n t o t h e d e s t i n a t i o n d i s k e t t e . H e r e is a s a m p l e s e q u e n c e .
B e s u r e y o u r W o r k b e n c h or C L I d i s k e t t e is i n t h e i n t e r n a l d i s k d r i v e . I s s u e
the commands:
C O P Y dfO:c/cd R A M :
COPY ofO:c/copy R A M :
CD R A M :
I n s e r t t h e s o u r c e d a t a d i s k e t t e i n t o t h e d r i v e . ( F o r this e x a m p l e , c o p y s o m e t h i n g f r o m t h e W o r k b e n c h or C L I d i s k e t t e , w h i c h is a l r e a d y i n t h e d r i v e ) .
Type:
COPYdfO:c/executeram:execute
or
COPY dfO:c/execute e x e c u t e
or
COPY dfO:c/execute r a m :
R e m o v e the source diskette, and insert the destination diskette into the
drive. Type:
COPY ram-.execute dfO:execute
or
C O P Y e x e c u t e d f O : e x e c u t e (If y o u d i d t h e CD R A M : t h i s f o r m w o r k s . )
R e m o v e t h e d e s t i n a t i o n d i s k e t t e a n d i n s e r t y o u r C L I or W o r k b e n c h d i s k e t t e
again. Type:
34
CD dfO:
a n d y o u are b a c k w h e r e you started. T h e only other c o m m a n d y o u m a y w a n t
t o p e r f o r m is:
DELETE RAM:cd RAM:copy RAM:execute
w h i c h r e l e a s e s t h e r a m d i s k m e m o r y t o t h e s y s t e m for o t h e r u s e s .
l o o k s in t h e n e w d r a w e r ,
a n d s h o w s y o u t h a t t h e file
named
" n e w n a m e " is t h e r e .
only
INTRODUCING AMIGADOS
35
o n e d i r e c t o r y at a t i m e . Y o u c a n u s e t h e D I R c o m m a n d w i t h o n e of its
options:
D I R OPT A
w h i c h lists all d i r e c t o r i e s a n d s u b d i r e c t o r i e s o n t h e d i s k e t t e . K e e p in m i n d t h e
< s p a c e > < B A C K S P > c o m b i n a t i o n to p a u s e a n d restart t h e listing.
T o g e t a c l o s e r l o o k at t h e d i s k ' s c o n t e n t s , y o u m i g h t r e d i r e c t t h e o u t p u t t o a
file:
D I R > m y d i s k d i r OPT A
Notice that the redirect-the-output c o m m a n d character and filename M U S T
c o m e b e f o r e t h e list of o p t i o n s for t h e D I R c o m m a n d .
N o w , if y o u w i s h , y o u c a n T Y P E t h e file m y d i s k d i r a n d p r e s s t h e s p a c e b a r
to p a u s e t h e listing. U s e t h e R E T U R N k e y t o r e s u m e t h e listing. O r , y o u c a n
u s e E D t o v i e w t h e file, as f o l l o w s :
ED mydiskdir
U s e t h e c u r s o r k e y s t o m o v e u p a n d d o w n i n t h e file.
U s e t h e k e y c o m b i n a t i o n E S C t h e n T < R E T U R N > t o m o v e t o t h e t o p of
t h e file.
S u c h a c o m b i n a t i o n c a n b e r e f e r r e d t o as " E S C - T " , m e a n i n g E S C f o l l o w e d
b y T.
U s e t h e k e y c o m b i n a t i o n E S C - B < R E T U R N > t o m o v e t o t h e b o t t o m of t h e
file.
U s e the key combination E S C - M then a n u m b e r < R E T U R N > to m o v e to
a specific line n u m b e r w i t h i n t h e file.
U s e t h e k e y c o m b i n a t i o n E S C - Q < R E T U R N > to Q U I T w i t h o u t c h a n g i n g
t h e file o r
U s e E S C - X < R E T U R N > t o w r i t e a n y c h a n g e s to y o u r file b a c k i n t o t h e
original file n a m e .
C h a p t e r 3 of t h e AmigaDOS
User's Manual
using ED.
36
AMIGADOS USER'S M A N U A L
(load t h e W o r k b e n c h p r o g r a m ) a n d E N D C L I w h i c h b a s i c a l l y l e a v e s t h e W o r k b e n c h p r o g r a m i n c o n t r o l . Y o u c a n m a k e u p y o u r o w n S t a r t u p S e q u e n c e file
u s i n g E D o r E D I T to c r e a t e a c u s t o m v e r s i o n of a n e x e c u t e c o m m a n d
s e q u e n c e . T h e E X E C U T E c o m m a n d s u m m a r y a n d t u t o r i a l s e c t i o n in t h e
AmigaDOS
User's Manual
h a s details a b o u t v a r i o u s c o m m a n d s t h a t y o u c a n
h a v e in t h i s file. N o t e t h a t S t a r t u p S e q u e n c e c a n also b e u s e d t o a u t o - r u n a
program.
W A R N I N G : T a k e c a r e to m o d i f y o n l y a c o p y of y o u r d i s k e t t e
never modify the master diskette
if y o u d e c i d e to c h a n g e
Startup Sequence.
the
type:
DIR
A m i g a D O S p r o m p t s " i n s e r t W o r k b e n c h [or w h a t e v e r t h e b o o t d i s k e t t e n a m e
w a s ] in a n y d r i v e " . It k n o w s , f r o m b o o t t i m e , t h a t t h e D I R c o m m a n d is in t h e
boot diskette, c directory. A m i g a D O S reads the DIR c o m m a n d , then asks
" i n s e r t m y d i s k in a n y d r i v e " . A n y o t h e r A m i g a D O S c o m m a n d also r e s u l t s i n
the n e e d for a diskette s w a p . To avoid this, u s e the A S S I G N c o m m a n d as
follows:
A S S I G N " c: m y d l s k : c
INTRODUCING AMIGADOS
37
SYS: mydisk:
S: m y d i s k : s
DEVS: mydisk:devs
L: m y d i s k : l
FONTS: mydlsk:fonts
LIBS: mydisk:libs
T o c r e a t e this e x e c u t e file, u s e t h e c o m m a n d :
C O P Y F R O M * TO r e a s s i g n
T h e n t y p e t h e a b o v e A S S I G N l i n e s . A f t e r y o u ' v e t y p e d t h e last l i n e , e n t e r
t h e k e y c o m b i n a t i o n C T R L A w h i c h e n d s t h e file. T h e " * " s t a n d s f o r t h e
k e y b o a r d a n d c u r r e n t C L I w i n d o w , s o t h i s m e t h o d of c r e a t i n g a file is o n e
p o s s i b l e a l t e r n a t i v e t o u s i n g E D or E D I T .
38
2>
Y o u c a n m o v e t h e n e w w i n d o w a r o u n d , m a k e it b i g g e r , m a k e it s m a l l e r a n d
s o o n . T o i s s u e c o m m a n d s t o t h e n e w C L I , click w i t h i n its w i n d o w . N o w
a n y t h i n g y o u t y p e g o e s i n t o t h e w i n d o w w h e r e y o u clicked t h e s e l e c t i o n
button most recently. Try the following:
1. C l i c k i n w i n d o w 1, t h e n t y p e :
D I R dfO:c
2 . Q u i c k l y click i n w i n d o w 2 , a n d t y p e :
INFO
B o t h C L I s will w o r k at t h e s a m e t i m e to fulfill y o u r r e q u e s t s . T h i s d e m o n s t r a t e s t h e m u l t i - t a s k i n g capabilities of t h e A m i g a . N o t i c e t h a t y o u a r e n ' t
l i m i t e d t o o n l y t w o C L I s , y o u c a n , if t h e r e is m e m o r y a v a i l a b l e , o p e n a s m a n y
as 20 CLIs.
Closing a CLI
Y o u f i n i s h w i t h a C L I a n d c l o s e its w i n d o w w i t h t h e c o m m a n d E N D C L I . Click
t h e s e l e c t i o n b u t t o n of t h e m o u s e in t h e w i n d o w for t h e C L I y o u w i s h t o c l o s e ,
and type:
ENDGLI
T h a t ' s all t h e r e is to it.
Closing Comments
T h e a b o v e s e r i e s of c o m m a n d d e s c r i p t i o n s i n t r o d u c e s y o u to t h e k i n d s of
things y o u can do with A m i g a D O S c o m m a n d s from the CLI. T h e r e are several
c o m m a n d s t h a t h a v e n ' t b e e n c o v e r e d in t h e a b o v e s e s s i o n at all. In a d d i t i o n ,
INTRODUCING AMIGADOS
39
m o s t of t h e c o m m a n d s d e s c r i b e d a b o v e h a v e o t h e r " t e m p l a t e s " ( w a y s y o u c a n
e n t e r t h e c o m m a n d s ) a n d o p t i o n s that h a v e n ' t b e e n d e m o n s t r a t e d .
C h a p t e r 2 of t h e AmigaDOS
User's Manual c o n t a i n s a r e f e r e n c e s e c t i o n t h a t
s h o w s t h e t e m p l a t e s for e a c h of t h e c o m m a n d s in A m i g a D O S . Y o u c a n l o o k at
t h e d e s c r i p t i o n for e a c h c o m m a n d to f i n d m o r e i n f o r m a t i o n . O n c e y o u a r e
f a m i l i a r w i t h t h e c o m m a n d s , a n d t h e f o r m s in w h i c h y o u c a n u s e t h e m , t h e
q u i c k r e f e r e n c e listing at t h e e n d of t h e c h a p t e r will b e u s e f u l t o r e m i n d y o u of
t h e c o m m a n d s t h a t are a v a i l a b l e .
[ ]
<name>*
F o r A m i g a D O S C L I c o m m a n d s , u n l e s s s o m e f o r m of p u n c t u a t i o n , s u c h as a
c o m m a or a p l u s - s i g n is actually i n c l u d e d in t h e c o m m a n d F o r m a t l i n e , y o u
must always separate the parameters with blank spaces. Don't confuse the
Format information with the " T e m p l a t e " for the c o m m a n d . T h e c o m m a n d
t e m p l a t e is e x p l a i n e d in s e c t i o n 1.4.5 of t h e AmigaDOS
User's
Manual.
Chapter 2
AmigaDOS Commands
T h i s c h a p t e r is d i v i d e d i n t o t w o p a r t s : t h e first p a r t d e s c r i b e s t h e u s e r c o m m a n d s available on the Amiga; the second describes the developer c o m m a n d s .
T h e u s e r c o m m a n d s fall i n t o s e v e r a l c a t e g o r i e s : file utilities, C L I c o n t r o l ,
c o m m a n d sequence control, and system and storage m a n a g e m e n t . Part I prov i d e s a l p h a b e t i z e d c o m m a n d d e s c r i p t i o n s t h a t give t h e f o r m a t , t e m p l a t e , p u r p o s e , a n d s p e c i f i c a t i o n of e a c h c o m m a n d as w e l l as a n e x a m p l e of its u s e . Part
2 has the same organization.
T h e c h a p t e r starts w i t h a list of unfamiliar terminology. A t t h e e n d of the c h a p t e r
t h e r e is a q u i c k C o n t e n t s r e f e r e n c e card t h a t lists all t h e c o m m a n d s b y f u n c t i o n .
2.1
2.2
2.3
s t a r t u p . It c o m e s f r o m t h e e x p r e s s i o n " p u l l i n g y o u r s e l f u p b y
your bootstraps."
Default
initial s e t t i n g o r , in o t h e r w o r d s , w h a t h a p p e n s if y o u d o
n o t h i n g . S o t h a t , in this m a n u a l , " d e f a u l t " is u s e d t o m e a n
" i n a b s e n c e of s o m e t h i n g e l s e " .
Device name
p a r t of a n a m e t h a t p r e c e d e s t h e c o l o n (:), f o r e x a m p l e , C O N : ,
D F O : , PRT:, and so forth.
AMIGADOS COMMANDS
41
File handle
a n i n t e r n a l A m i g a D O S v a l u e t h a t r e p r e s e n t s a n o p e n file or
device.
Logical device
Object code
b i n a r y o u t p u t f r o m a n a s s e m b l e r or c o m p i l e r , a n d
input to a linker.
Reboot
restart.
Stream
a n o p e n file or d e v i c e t h a t is a s s o c i a t e d w i t h a file h a n d l e . F o r
e x a m p l e , t h e i n p u t s t r e a m c o u l d b e f r o m a file a n d t h e o u t p u t
s t r e a m c o u l d b e to t h e c o n s o l e d e v i c e .
System disk
Volume name
a n a m e y o u give to a p h y s i c a l d i s k .
binary
N o t e : C o m m a n d f o r m a t is e x p l a i n e d i n s e c t i o n 1.7; c o m m a n d t e m p l a t e is
e x p l a i n e d in s e c t i o n 1 . 4 . 5 .
Format:
[<command>];[<comment>]
Template:
"command";"comment"
Purpose:
T o a d d c o m m e n t s to c o m m a n d l i n e s .
Specification:
T h e C L I i g n o r e s e v e r y t h i n g a f t e r t h e s e m i c o l o n (;).
Examples:
;This line is only a c o m m e n t
i g n o r e s t h e p a r t of t h e line c o n t a i n i n g " T h i s line is o n l y a c o m m e n t . "
copy < f i l e > to prt: ; p r i n t t h e file
c o p i e s t h e file t o t h e p r i n t e r , b u t i g n o r e s t h e c o m m e n t " p r i n t t h e f i l e . "
See also:
EXECUTE
><
Format:
Template:
Purpose:
<command>[>outputfilename][inputfilename][<commandargs*]
" c o m m a n d " > " T O " < "FROM" "args"
To direct c o m m a n d input a n d output.
42
AMIGADOS USER'S M A N U A L
Specification:
Y o u u s e t h e s y m b o l s > a n d < t o d i r e c t t h e o u t p u t a n d i n p u t of a c o m m a n d .
T h e d i r e c t i o n of t h e p o i n t of t h e a n g l e b r a c k e t i n d i c a t e s t h e d i r e c t i o n of
information flow. Y o u can u s e these symbols to change w h e r e any c o m m a n d
reads input or writes output. T h e output from a c o m m a n d usually goes to the
c u r r e n t w i n d o w . H o w e v e r , if y o u t y p e a > s y m b o l after a c o m m a n d a n d b e f o r e
a f i l e n a m e , t h e c o m m a n d w r i t e s t h e o u t p u t to t h a t file i n s t e a d . S i m i l a r l y , if y o u
t y p e t h e < s y m b o l b e f o r e a f i l e n a m e , t h e c o m m a n d r e a d s f r o m t h a t file i n s t e a d
of f r o m t h e k e y b o a r d .
Y o u d o n o t h a v e to s p e c i f y b o t h t h e T O a n d F R O M d i r e c t i o n s a n d files. T h e
e x i s t e n c e a n d n u m b e r of " a r g s " d e p e n d s o n t h e c o m m a n d y o u u s e d . R e d i r e c t i o n o n l y h a p p e n s f o r t h e c o m m a n d y o u s p e c i f i e d . A m i g a D O S r e v e r t s to t h e
initial or " d e f a u l t " i n p u t a n d o u t p u t (that i s , t h e k e y b o a r d a n d c u r r e n t w i n d o w )
a f t e r w a r d . N o t i c e t h a t r e d i r e c t i o n m u s t precede t h e a r g u m e n t s .
Examples:
DATE >
dlary_dates
program < my
tells m y
program
keyboard.
input
to accept i n p u t f r o m m y
input instead
of f r o m
the
AMIGADOS COMMANDS
43
ASSIGN
Format:
ASSIGN
[[<name>]<dir>][LIST]
Template:
ASSIGN "NAME,DIR,LIS17S"
Purpose:
T o a s s i g n a logical d e v i c e n a m e to a filing s y s t e m d i r e c t o r y .
Specification:
N A M E is t h e logical d e v i c e n a m e g i v e n to t h e d i r e c t o r y s p e c i f i e d b y D I R .
If y o u j u s t g i v e t h e N A M E , A m i g a D O S d e l e t e s t h e logical d e v i c e n a m e g i v e n
(that i s , it r e m o v e s t h e a s s i g n m e n t ) .
A S S I G N w i t h o u t a n y p a r a m e t e r s or t h e s w i t c h L I S T d i p l a y s a listing of all
current assignments.
W h e n y o u u s e A S S I G N , y o u m u s t e n s u r e t h a t t h e r e is a d i s k i n s e r t e d i n t h e
d r i v e . T h i s is i m p o r t a n t b e c a u s e A S S I G N m a k e s a n a s s i g n m e n t t o a d i s k v o l u m e
and not to a drive.
N o t e t h a t t h e effect o f A S S I G N is lost w h e n y o u r e s t a r t o r " r e b o o t " y o u r
computer.
Examples:
ASSIGN sources: :new/work
S e t s u p t h e logical d e v i c e n a m e " s o u r c e s " to t h e d i r e c t o r y " : n e w / w o r k " . T h e n
t o g a i n a c c e s s t o files in " : n e w / w o r k " , y o u c a n u s e t h e logical d e v i c e n a m e
" s o u r c e s " , as in
TYPE sources:xyz
w h i c h d i s p l a y s t h e file " : n e w / w o r k / x y z " .
ASSIGN LIST
lists t h e c u r r e n t logical d e v i c e n a m e s in u s e .
BREAK
Format:
BREAK <task>[ALL][C][D][E][F]
Template:
BREAK "TASK/A,ALL/S,C/S,D/S,E/S,F/S"
Purpose:
T o set a t t e n t i o n flags i n t h e g i v e n p r o c e s s .
Specification:
B R E A K s e t s t h e s p e c i f i e d a t t e n t i o n flags i n t h e p r o c e s s . C s e t s t h e C T R L - C flag,
D s e t s t h e C T R L - D flag, a n d s o o n . A L L sets all t h e flags f r o m C T R L - C t h r o u g h
44
C T R L - F . B y d e f a u l t , A m i g a D O S o n l y s e t s t h e C T R L - C flag. T h e a c t i o n o f
B R E A K is i d e n t i c a l to s e l e c t i n g t h e r e l e v a n t p r o c e s s b y m o v i n g t h e m o u s e t o
t h e w i n d o w , clicking t h e S e l e c t i o n B u t t o n , a n d p r e s s i n g t h e r e q u i r e d c o n t r o l
key combination.
Examples:
BREAK 7
s e t s t h e C T R L - C a t t e n t i o n flag of p r o c e s s 7. T h i s is i d e n t i c a l t o s e l e c t i n g p r o c e s s
7 and pressing CTRL-C.
BREAK 5 D
s e t s t h e C T R L - D a t t e n t i o n flag of p r o c e s s 5 .
BREAK 3 D E
sets both C T R L - D a n d CTRL-E.
CD
Format:
Template:
CD[<dir>]
CD "DIR"
Purpose:
T o s e t o r c h a n g e a c u r r e n t d i r e c t o r y or d r i v e .
Specification:
C D w i t h n o p a r a m e t e r s d i s p l a y s t h e n a m e of t h e c u r r e n t d i r e c t o r y . In t h e
f o r m a t list a b o v e , < d i r > i n d i c a t e s a n e w c u r r e n t d i r e c t o r y (that i s , o n e i n
w h i c h u n q u a l i f i e d f i l e n a m e s a r e l o o k e d u p ) . If t h e d i r e c t o r y y o u s p e c i f y is n o t
o n t h e c u r r e n t d r i v e , t h e n C D also c h a n g e s t h e c u r r e n t d r i v e .
T o c h a n g e t h e c u r r e n t d i r e c t o r y t o t h e d i r e c t o r y t h a t o w n s t h e c u r r e n t o n e (if
o n e e x i s t s ) , t y p e C D f o l l o w e d b y a single s l a s h (/). T h u s C D / m o v e s t h e
current directory o n e level u p in the hierarchy unless the current directory is a
r o o t d i r e c t o r y (that i s , t h e t o p level in t h e filing s y s t e m ) . M u l t i p l e s l a s h e s a r e
a l l o w e d ; e a c h s l a s h r e f e r s to a n a d d i t i o n a l level a b o v e .
Examples:
CD d f l : w o r k
s e t s t h e c u r r e n t d i r e c t o r y to " w o r k " o n disk " d f l " , a n d s e t s t h e c u r r e n t d r i v e
to " d f l " .
45
AMIGADOS COMMANDS
CD S Y S : C O M / B A S I C
CD /
s e t s t h e c u r r e n t d i r e c t o r y to " S Y S : C O M " .
COPY
Format:
COPY
[[FROM]<name>][TO<name>][ALL][QUIET]
Template:
COPY "FROM,TO/A,ALL/S,QUIET/S"
Purpose:
T o c o p y a file o r d i r e c t o r y f r o m o n e p l a c e t o a n o t h e r .
Specification:
C O P Y p l a c e s a c o p y of t h e file o r d i r e c t o r y i n t h e file or d i r e c t o r y s p e c i f i e d a s
T O . T h e p r e v i o u s c o n t e n t s of T O , if a n y , are l o s t .
If y o u s p e c i f y a d i r e c t o r y n a m e a s F R O M , C O P Y c o p i e s all t h e files in t h e
F R O M d i r e c t o r y to t h e T O d i r e c t o r y . If y o u d o n o t s p e c i f y t h e F R O M d i r e c t o r y ,
A m i g a D O S u s e s t h e c u r r e n t directory. T h e T O directory m u s t exist for C O P Y to
w o r k ; it is n o t c r e a t e d b y C O P Y .
If y o u s p e c i f y A L L , C O P Y a l s o c o p i e s t h e files i n a n y s u b d i r e c t o r i e s . I n t h i s
c a s e , it a u t o m a t i c a l l y c r e a t e s s u b d i r e c t o r i e s in t h e T O d i r e c t o r y , a s r e q u i r e d .
T h e n a m e of t h e c u r r e n t file b e i n g c o p i e d is d i s p l a y e d o n t h e s c r e e n a s it
h a p p e n s u n l e s s y o u give t h e Q U I E T s w i t c h .
Y o u c a n also s p e c i f y t h e s o u r c e d i r e c t o r y a s a p a t t e r n . I n this c a s e , A m i g a D O S
c o p i e s a n y files t h a t m a t c h t h e p a t t e r n . S e e t h e c o m m a n d L I S T f o r a full
d e s c r i p t i o n of p a t t e r n s . Y o u m a y s p e c i f y d i r e c t o r y l e v e l s a s w e l l a s p a t t e r n s .
Examples:
C O P Y f U e l TO : w o r k / f i l e 2
copies 'filel' in the current directory to " f i l e 2 " in the directory " : w o r k " .
C O P Y TO d f l : b a c k u p
c o p i e s all t h e files i n t h e c u r r e n t d i r e c t o r y t o " d f L b a c k u p " . It d o e s n o t c o p y a n y
s u b d i r e c t o r i e s , a n d d f l : b a c k u p m u s t a l r e a d y exist.
C O P Y dfO: t o d f l : A L L Q U I E T
m a k e s a logical c o p y of d i s k " d f O " o n d i s k " d f l " w i t h o u t a n y r e f l e c t i o n
filenames.
COPY t e s t - # ? to dfl:xyz
of
46
C O P Y * TO CON: 1 0 / 1 0 / 2 0 0 / 1 0 0 /
C l i c k t h e w i n d o w t h a t y o u t y p e d t h e c o p y c o m m a n d i n t o . T h i s " r e a c t i v a t e s " it
s o t h a t c o n s o l e i n p u t is t a k e n f r o m t h e r e . E v e r y t i m e y o u t y p e a l i n e it will b e
displayed in the n e w w i n d o w . Press CTRLA w h e n you are d o n e a n d the n e w
w i n d o w will c l o s e .
C O P Y D F 0 : ? / # ? TO D F 1 : A L L
c o p i e s e v e r y file in a n y o n e c h a r a c t e r s u b d i r e c t o r y of DFO: t o t h e r o o t d i r e c t o r y
of D F 1 : .
See also:
JOIN
DATE
Format:
DATE [<date>][<time>][TO|VER<name>]
Template:
DATE "DATE,TIME,TO = VER/K"
Purpose:
T o d i s p l a y or s e t t h e s y s t e m d a t e or t i m e .
Specification:
D A T E with n o parameter displays the currently set system date a n d time. This
i n c l u d e s t h e d a y of t h e w e e k . T i m e is d i s p l a y e d u s i n g a 2 4 - h o u r c l o c k .
D A T E < d a t e > s e t s t h e d a t e . T h e f o r m of < d a t e > is D D - M M M - Y Y . If t h e
d a t e is a l r e a d y s e t , y o u c a n r e s e t it b y s p e c i f y i n g a d a y n a m e (this s e t s t h e d a t e
f o r w a r d to t h a t d a y ) or b y s p e c i f y i n g ' t o m o r r o w ' or ' y e s t e r d a y ' .
D A T E < t i m e > s e t s t h e t i m e . T h e f o r m of < t i m e > i s H H : M M (for H o u r s
and Minutes). You should use leading zeros w h e n necessary. Note that,
if y o u u s e a c o l o n (:), A m i g a D O S r e c o g n i z e s t h a t y o u h a v e s p e c i f i e d t h e t i m e
r a t h e r t h a n t h e d a t e . T h a t is t o s a y , y o u c a n s e t b o t h t h e d a t e a n d t h e t i m e , o r
e i t h e r d a t e o r t i m e in a n y o r d e r b e c a u s e D A T E o n l y r e f e r s to t h e t i m e w h e n
you use the form H H : M M .
If y o u d o n o t s e t t h e d a t e , t h e restart d i s k v a l i d a t i o n p r o c e s s s e t s t h e s y s t e m
d a t e to t h e d a t e of t h e m o s t r e c e n t l y c r e a t e d file. S e e C h a p t e r 1 for details o n t h e
restart validation process.
AMIGADOS COMMANDS
47
10:50
s e t s t h e c u r r e n t t i m e to t e n 'til e l e v e n .
DATE 2 3 : 0 0
s e t s t h e c u r r e n t t i m e to 1 1 : 0 0 P.M.
DATE 0 1 - J A N - 0 2
s e t s t h e d a t e to J a n u a r y 1st, 2 0 0 2 . ( T h e earliest d a t e y o u c a n s e t is 0 1 - J A N - 7 8 . )
DELETE
Format:
DELETE
Template:
<name>[<name>*][ALL][Q|QUIET]
Purpose:
T o d e l e t e u p to t e n files or d i r e c t o r i e s .
Specification:
D E L E T E a t t e m p t s to d e l e t e e a c h file y o u s p e c i f y . If it c a n n o t d e l e t e a f i l e ,
the screen displays a m e s s a g e , and A m i g a D O S attempts to delete the next
file i n t h e list. Y o u m a y n o t d e l e t e a d i r e c t o r y if it c o n t a i n s a n y files.
48
Y o u c a n also u s e a p a t t e r n to s p e c i f y t h e f i l e n a m e . S e e t h e d e s c r i p t i o n of t h e
c o m m a n d L I S T for full details of p a t t e r n s . T h e p a t t e r n m a y s p e c i f y d i r e c t o r y
l e v e l s as w e l l a s f i l e n a m e s . In this c a s e , all files t h a t m a t c h t h e p a t t e r n a r e
deleted.
If y o u s p e c i f y A L L w i t h a d i r e c t o r y n a m e , D E L E T E will d e l e t e t h a t d i r e c t o r y
a n d all s u b d i r e c t o r i e s a n d files w i t h i n t h a t d i r e c t o r y a n d its s u b d i r e c t o r i e s .
U n l e s s y o u s p e c i f y t h e s w i t c h Q U I E T (or u s e t h e a l t e r n a t i v e , Q ) , t h e n a m e of
t h e file b e i n g d e l e t e d a p p e a r s o n t h e s c r e e n a s it h a p p e n s .
Examples:
D E L E T E old-file
d e l e t e s t h e file " o l d - f i l e " .
DELETE work/prog 1 work/prog2 work
d e l e t e s t h e files " p r o g l " a n d " p r o g 2 " i n t h e directory " w o r k " , a n d t h e n d e l e t e s
the directory " w o r k " .
DELETE
t#?/#?(H2)
DIR
Format:
Template:
Purpose:
T o p r o v i d e a d i s p l a y of t h e files in a d i r e c t o r y i n s o r t e d o r d e r . D I R
c a n also i n c l u d e t h e files i n s u b d i r e c t o r i e s , a n d y o u c a n u s e D I R in
interactive m o d e .
Specification:
D I R a l o n e s h o w s t h e files in t h e c u r r e n t d i r e c t o r y . D I R f o l l o w e d b y a d i r e c t o r y
p r o v i d e s t h e files i n t h a t d i r e c t o r y . T h e f o r m of t h e d i s p l a y is first a n y
49
AMIGADOS COMMANDS
s u b d i r e c t o r i e s , f o l l o w e d b y a s o r t e d list o f t h e files in t w o c o l u m n s . If y o u w a n t
to k n o w if a file e x i s t s t y p e L I S T f i l e n a m e .
T y p i n g D I R f i l e n a m e , w h e r e f i l e n a m e is a file w h i c h e x i s t s r e s u l t s in t h e
A m i g a r e s p o n d i n g w i t h : " f i l e n a m e is n o t a d i r e c t o r y . "
T o pass options to DIR, use the O P T k e y w o r d . U s e the A option to include
a n y s u b d i r e c t o r i e s b e l o w t h e s p e c i f i e d o n e i n t h e list. E a c h s u b l i s t o f files is
indented.
T o list o n l y t h e d i r e c t o r y n a m e s u s e t h e D o p t i o n .
T h e I o p t i o n s p e c i f i e s t h a t D I R is to r u n in i n t e r a c t i v e m o d e . I n t h i s c a s e , t h e
files a n d d i r e c t o r i e s a r e d i s p l a y e d w i t h a q u e s t i o n m a r k f o l l o w i n g e a c h n a m e .
P r e s s R E T U R N to d i s p l a y t h e n e x t n a m e in t h e list. T o quit t h e p r o g r a m , t y p e
Q . T o g o b a c k to t h e p r e v i o u s d i r e c t o r y l e v e l o r t o s t o p (if a t t h e l e v e l o f t h e
initial d i r e c t o r y ) , t y p e B .
If t h e n a m e d i s p l a y e d is t h a t o f a d i r e c t o r y , t y p e E to e n t e r t h a t d i r e c t o r y a n d
d i s p l a y t h e files a n d s u b d i r e c t o r i e s . U s e E a n d B to s e l e c t d i f f e r e n t l e v e l s .
T y p i n g t h e c o m m a n d D E L (that i s , t y p i n g t h e t h r e e l e t t e r s D E L , n o t p r e s s i n g
t h e D E L k e y ) c a n b e u s e d to d e l e t e a d i r e c t o r y , b u t t h i s o n l y w o r k s if t h e
d i r e c t o r y is e m p t y .
If t h e n a m e is t h a t o f a file, t y p i n g D E L d e l e t e s t h e file, or t y p i n g T T y p e s
( t h a t i s , d i s p l a y s ) t h e file o n t h e s c r e e n . I n t h e last c a s e , p r e s s C T R L - C to s t o p
it " t y p i n g " a n d r e t u r n t o i n t e r a c t i v e m o d e .
T o f i n d t h e p o s s i b l e r e s p o n s e s to a n i n t e r a c t i v e r e q u e s t , t y p e ? .
Examples:
DIR
p r o v i d e s a list o f files in c u r r e n t d i r e c t o r y .
D I R dfO: OPT a
lists t h e e n t i r e d i r e c t o r y s t r u c t u r e o f t h e d i s k " d f O " .
DISKCOPY
Format:
DISKCOPY [FROM]<disk>TO<disk>[NAME
Template:
DISKCOPY
<name>]
Purpose:
T o c o p y t h e c o n t e n t s o f o n e 3-Vi i n c h f l o p p y d i s k t o a n o t h e r .
"FROM/A,TO/A/K,NAME/K''
Specifications:
D I S K C O P Y m a k e s a c o p y of the entire contents of the disk y o u specified as
F R O M , overwriting the previous contents of t h e entire disk y o u specified as
50
T O . D I S K C O P Y a l s o f o r m a t s a n e w d i s k as it c o p i e s . Y o u n o r m a l l y u s e t h e
c o m m a n d to p r o d u c e b a c k u p f l o p p y d i s k s .
O n c e y o u h a v e g i v e n t h e c o m m a n d , A m i g a D O S p r o m p t s y o u to i n s e r t t h e
correct disks. At this point, you insert the correct source a n d destination disks.
Y o u c a n u s e t h e c o m m a n d to c o p y a n y 3-V2 i n c h A m i g a D O S d i s k to a n o t h e r ,
b u t t h e s o u r c e a n d d e s t i n a t i o n d i s k s m u s t b e i d e n t i c a l in size a n d s t r u c t u r e . T o
c o p y information b e t w e e n different sized disks, y o u use C O P Y .
Y o u c a n a l s o u s e t h e c o m m a n d to c o p y a f l o p p y d i s k u s i n g a s i n g l e f l o p p y
d r i v e . If y o u s p e c i f y t h e s o u r c e a n d d e s t i n a t i o n a s t h e s a m e d e v i c e , t h e n t h e
p r o g r a m r e a d s in as m u c h of t h e s o u r c e d i s k i n t o m e m o r y as p o s s i b l e . It t h e n
p r o m p t s y o u to p l a c e t h e d e s t i n a t i o n disk i n t h e drive a n d t h e n c o p i e s t h e
i n f o r m a t i o n f r o m m e m o r y o n t o t h e d e s t i n a t i o n d i s k . T h i s s e q u e n c e is r e p e a t e d
as m a n y t i m e s a s r e q u i r e d .
If y o u d o n o t s p e c i f y a n e w n a m e for y o u r d i s k , D I S K C O P Y c r e a t e s a n e w
d i s k w i t h t h e s a m e n a m e as t h e old o n e . H o w e v e r , A m i g a D O S c a n tell t h e
d i f f e r e n c e b e t w e e n t w o d i s k s w i t h t h e s a m e n a m e b e c a u s e e v e r y d i s k is
a s s o c i a t e d w i t h t h e d a t e a n d t i m e of its c r e a t i o n . D I S K C O P Y g i v e s t h e n e w
d i s k t h e c u r r e n t s y s t e m d a t e as its c r e a t i o n d a t e a n d t i m e .
N o t e : T o c o p y p a r t of a d i s k , y o u c a n u s e C O P Y t o R A M : .
Examples:
D I S K C O P Y F R O M dfO: TO d f l :
m a k e s a b a c k u p c o p y of t h e d i s k " d f O " o n t o d i s k " d f l " .
D I S K C O P Y F R O M dfO: T o dfO:
m a k e s a b a c k u p c o p y of t h e d i s k in drive " d f O " u s i n g o n l y a s i n g l e d r i v e .
See also:
COPY
ECHO
Format:
ECHO <string>
Template:
ECHO " "
Purpose:
T o display the argument given.
Specification:
E C H O w r i t e s t h e s i n g l e a r g u m e n t to t h e c u r r e n t o u t p u t s t r e a m ( w h i c h c a n b e a
file or a d e v i c e ) . T h i s is n o r m a l l y o n l y u s e f u l w i t h i n a c o m m a n d s e q u e n c e or a s
p a r t of a R U N c o m m a n d . If y o u give t h e a r g u m e n t i n c o r r e c t l y , a n e r r o r is
displayed.
AMIGADOS COMMANDS
51
Examples:
RUN" C O P Y : w o r k / p r o g t o d f l : w o r k A L L Q U I E T
Copy finished
If t h e f o l l o w i n g E x e c u t e file e x i s t s
ECHO " S t a r t i n g 'MYCOPY' E x e c u t e file"
C O P Y D F 1 : A B C TO R A M : A B C
C O P Y D F L X Y Z TO R A M : X Y Z
ECHO " R e m o v e t h e diskette i n D F 1 : "
ECHO " I n s e r t t h e n e w diskette i n D F 1 : "
WAIT 1 0 SECS
C O P Y R A M : A B C TO D F 1 : A B C
C O P Y R A M : X Y Z TO D F 1 : A B C
ECHO " D o n e "
then
EXECUTE MYCOPY
c o p i e s 2 files to R A M d i s k a n d b a c k .
ED
Format:
ED[FROM]<name>[SIZE<n>]
Template:
ED "FROM/A, SIZE"
Purpose:
T o e d i t t e x t files.
Specification:
E D is a s c r e e n e d i t o r . Y o u c a n u s e E D as a n a l t e r n a t i v e to t h e line e d i t o r E D I T .
T h e file y o u specify as F R O M is r e a d into m e m o r y , t h e n E D a c c e p t s y o u r editing
i n s t r u c t i o n s . If F R O M f i l e n a m e d o e s n o t exist, A m i g a D O S c r e a t e s a n e w file.
B e c a u s e t h e file is r e a d i n t o m e m o r y , t h e r e is a limit t o t h e s i z e o f file y o u c a n
e d i t w i t h E D . U n l e s s y o u s p e c i f y o t h e r w i s e , w o r k s p a c e size is 4 0 , 0 0 0 b y t e s .
T h i s w o r k s p a c e size is u s u a l l y s u f f i c i e n t for m o s t files. H o w e v e r , to a l t e r t h e
w o r k s p a c e , y o u s p e c i f y a s u i t a b l e v a l u e after t h e S I Z E k e y w o r d .
T h e r e is a full s p e c i f i c a t i o n of E D in C h a p t e r 3 .
52
Examples:
ED work/prog
e d i t s t h e file " w o r k / p r o g " , a s s u m i n g it e x i s t s ; o t h e r w i s e , E D c r e a t e s t h e file.
ED huge-file SIZE 5 0 0 0 0
e d i t s a v e r y l a r g e file " h u g e - f i l e " , u s i n g a w o r k s p a c e of 5 0 , 0 0 0 b y t e s .
EDIT
Format:
Template:
EDIT
Purpose:
T o e d i t t e x t files.
[OPT<option>]
"FROM/A,TO,WITH/K,VER/K,OPT/K"
Specification:
E D I T is a l i n e e d i t o r ( t h a t i s , it e d i t s a s e q u e n t i a l file line b y l i n e ) . If y o u s p e c i f y
T O , E D I T c o p i e s f r o m file F R O M to file T O . O n c e y o u h a v e c o m p l e t e d t h e
e d i t i n g , t h e file T O c o n t a i n s t h e e d i t e d r e s u l t , a n d t h e file F R O M is u n c h a n g e d .
I f y o u d o n o t s p e c i f y T O , t h e n E D I T w r i t e s t h e e d i t e d t e x t t o a t e m p o r a r y file.
If y o u g i v e t h e E D I T c o m m a n d s Q or W , t h e n E D I T r e n a m e s t h i s t e m p o r a r y file
F R O M , h a v i n g first s a v e d t h e o l d v e r s i o n of F R O M in t h e file " : t / e d i t - b a c k u p " .
If y o u g i v e t h e E D I T c o m m a n d S T O P , t h e n E D I T m a k e s n o c h a n g e to t h e file
FROM.
E D I T r e a d s c o m m a n d s f r o m t h e c u r r e n t i n p u t s t r e a m , or f r o m a W I T H file if
it is s p e c i f i e d .
E D I T s e n d s e d i t o r m e s s a g e s a n d v e r i f i c a t i o n o u t p u t to t h e file y o u s p e c i f y
w i t h V E R . If y o u o m i t V E R , t h e t e r m i n a l is u s e d i n s t e a d .
O P T s p e c i f i e s o p t i o n s : P n s e t s t h e m a x i m u m n u m b e r o f p r e v i o u s l i n e s to n ;
W n s e t s t h e m a x i m u m line w i d t h . T h e initial s e t t i n g is P 4 O W 1 2 0 .
Note: You cannot use the <
and >
s y m b o l s to r e d i r e c t i n p u t a n d o u t p u t
w h e n y o u call E D I T .
S e e C h a p t e r 4 for a full s p e c i f i c a t i o n o f E D I T .
Examples:
EDIT work/prog
e d i t s t h e file " w o r k / p r o g " .
When
e d i t i n g is c o m p l e t e , E D I T s a v e s t h e
old
AMIGADOS COMMANDS
53
ENDCLI
Format:
ENDCLI
Template:
ENDCLI
Purpose:
Specification:
A m i g a D O S only allows E N D C L I as an interactive c o m m a n d . E N D C L I r e m o v e s
the CLI currently selected by the mouse.
You shouldn't use E N D C L I except on a CLI created by the N E W C L I comm a n d . If t h e initial C L I ( p r o c e s s 1) is e n d e d , a n d n o o t h e r h a s b e e n s e t u p b y
t h e N E W C L I c o m m a n d , t h e n t h e e f f e c t is to t e r m i n a t e t h e A m i g a D O S s e s s i o n .
N o t e t h a t t h e r e a r e n o a r g u m e n t s to t h e E N D C L I c o m m a n d , a n d n o c h e c k
for invalid a r g u m e n t s .
Note: Do not experiment with E N D C L I before you've used N E W C L I . Using
E N D C L I o n t h e initial C L I a l w a y s p u l l s t h e r u g o u t f r o m u n d e r y o u b y
t e r m i n a t i n g t h a t C L I . If y o u s t a r t e d t h e C L I f r o m t h e W o r k b e n c h , t h e n t h e r e is
n o p r o b l e m a s y o u a r e r e t u r n e d to t h e W o r k b e n c h . If y o u s t a r t e d A m i g a D O S
w i t h just t h e C L I r u n n i n g , t h e n ending the last C L I gives y o u n o w a y of
creating a n e w one.
Examples:
T h e following sequence:
NEWCLI
LIST
ENDCLI
o p e n s a n e w w i n d o w , lists t h e d i r e c t o r y , a n d c l o s e s t h e w i n d o w a g a i n .
54
AMIGADOS USER'S M A N U A L
EXECUTE
Format:
EXECUTE
<commandfile>[<arg>*]
Template:
EXECUTE "command-file","args"
Purpose:
T o e x e c u t e a file of c o m m a n d s w i t h a r g u m e n t s u b s t i t u t i o n .
Specification:
Y o u n o r m a l l y u s e E X E C U T E t o s a v e t y p i n g . T h e c o m m a n d file c o n t a i n s c o m m a n d s executed by the C o m m a n d Line Interface. A m i g a D O S executes these
c o m m a n d s o n e at a t i m e , j u s t a s t h o u g h y o u h a d t y p e d t h e m at t h e k e y b o a r d .
If t h e e x e c u t i o n c r e a t e s a n e w C L I w i n d o w , t h e r e s u l t s m a y n o t b e i d e n t i c a l t o
t y p i n g at t h e k e y b o a r d .
Y o u can also u s e E X E C U T E to p e r f o r m p a r a m e t e r (that is, value)
stitution,
where
you
can
give
certain n a m e s
as p a r a m e t e r s .
Before
subthe
c o m m a n d file is e x e c u t e d , A m i g a D O S c h e c k s t h e p a r a m e t e r n a m e s w i t h t h o s e
y o u ' v e g i v e n a f t e r t h e E X E C U T E c o m m a n d . If a n y m a t c h , A m i g a D O S
uses
t h e v a l u e s y o u s p e c i f i e d i n s t e a d of t h e p a r a m e t e r n a m e . P a r a m e t e r s
may
h a v e v a l u e s s p e c i f i e d t h a t A m i g a D O S u s e s if y o u d o n o t explicitly s e t t h e
p a r a m e t e r . If y o u h a v e n o t s p e c i f i e d a p a r a m e t e r , a n d if t h e r e is n o d e f a u l t ,
t h e n t h e v a l u e of t h e p a r a m e t e r is e m p t y a n d n o t h i n g is s u b s t i t u t e d
for
it.
T o u s e p a r a m e t e r s u b s t i t u t i o n , y o u give directives to t h e E X E C U T E c o m m a n d . T o i n d i c a t e t h e s e , y o u start a line w i t h a s p e c i a l c h a r a c t e r , w h i c h is
initially a p e r i o d o r " d o t " (.). T h e d i r e c t i v e s a r e as f o l l o w s :
.KEY
A r g u m e n t t e m p l a t e , u s e d to s p e c i f y
t h e f o r m a t of t h e a r g u m e n t s , m a y b e a b b r e v i a t e d
.DOT
ch
to . K
C h a n g e dot character (initially".") to ch
.BRA
ch
.KET
ch
.DOLLAR
ch
.DEF
k e y w o r d v a l u e G i v e d e f a u l t to p a r a m e t e r
C o m m e n t line
abbreviated to . D O L
.<space>
.<newline>
B l a n k c o m m e n t line
B e f o r e e x e c u t i o n , A m i g a D O S s c a n s t h e c o n t e n t s of t h e file for a n y i t e m s
enclosed by B R A and K E T characters ( " < " and " > " ) . Such items m a y consist
of a k e y w o r d or a k e y w o r d a n d a default v a l u e for A m i g a D O S to u s e if y o u h a v e
left t h e k e y w o r d u n s e t . (To s e p a r a t e t h e k e y w o r d a n d t h e d e f a u l t , if t h e r e is
o n e , y o u t y p e a dollar s i g n " $ " ) . T h u s , A m i g a D O S r e p l a c e s < A N I M A L > w i t h
AMIGADOS COMMANDS
55
t h e v a l u e y o u a s s o c i a t e d w i t h t h e k e y w o r d A N I M A L , w h i l e it r e p l a c e s
< A N I M A L $ W O M B A T > w i t h t h e v a l u e of A N I M A L if it h a s o n e , a n d o t h e r w i s e it d e f a u l t s to W O M B A T .
A file c a n o n l y u s e t h e d o t c o m m a n d s if t h e first l i n e h a s a d o t c o m m a n d
o n it. T h e C L I l o o k s at t h e first l i n e . If it s t a r t s w i t h a d o t c o m m a n d ,
f o r e x a m p l e , a c o m m e n t ( . < s p a c e > t x t ) t h e n t h e C L I s c a n s t h e file l o o k i n g
f o r p a r a m e t e r s u b s t i t u t i o n a n d b u i l d s a t e m p o r a r y file in t h e :T d i r e c t o r y .
If t h e file d o e s n ' t start w i t h a d o t c o m m a n d , t h e n it is a s s u m e d t h a t t h e r e
a r e N O d o t c o m m a n d s i n t h e file, w h i c h a l s o m e a n s n o p a r a m e t e r s u b s t i t u t i o n is p e r f o r m e d . F o r t h e n o - d o t c a s e , t h e C L I starts e x e c u t i n g t h e file
d i r e c t l y w i t h o u t h a v i n g t o c o p y it t o : T . N o t e t h a t y o u c a n still e m b e d
c o m m e n t s in a n e x e c u t e file b y u s i n g t h e C L I ' s c o m m e n t c h a r a c t e r , t h e
s e m i c o l o n (;). If y o u d o n ' t n e e d p a r a m e t e r s u b s t i t u t i o n a n d d o t c o m m a n d s ,
d o n ' t use t h e m . T h e y save you extra accesses to the disk for the t e m p o r a r y
file.
A m i g a D O S p r o v i d e s a n u m b e r of c o m m a n d s t h a t a r e o n l y u s e f u l in c o m m a n d s e q u e n c e files. T h e s e i n c l u d e I F , S K I P , L A B , a n d Q U I T . T h e s e c a n b e
n e s t e d in a c o m m a n d file.
N o t e t h a t y o u c a n also n e s t E X E C U T E files. T h a t is, y o u c a n h a v e a c o m m a n d file t h a t c o n t a i n s E X E C U T E c o m m a n d s .
T o s t o p t h e e x e c u t i o n of a c o m m a n d file, y o u p r e s s C T R L - D . If y o u a r e
n e s t i n g c o m m a n d files, t h a t i s , if o n e c o m m a n d file calls a n o t h e r , y o u c a n s t o p
t h e e n t i r e s e t of E X E C U T E c o m m a n d s b y p r e s s i n g C T R L - C . C T R L - D o n l y s t o p s
t h e c u r r e n t c o m m a n d file f r o m e x e c u t i n g .
Examples:
A s s u m e t h e file " l i s t " c o n t a i n s t h e f o l l o w i n g :
.k f i l e n a m e / a
r u n copy < f i l e n a m e > to prt: +
echo "Printing of < f i l e n a m e > done"
T h e n the following c o m m a n d
EXECUTE list test/prg
a c t s a s t h o u g h y o u h a d t y p e d t h e f o l l o w i n g c o m m a n d s at t h e k e y b o a r d .
RUN copy test/prg to prt: +
ECHO " P r i n t i n g of test/prg done"
A n o t h e r e x a m p l e , " d i s p l a y " , u s e s m o r e of t h e f e a t u r e s d e s c r i b e d a b o v e :
56
.key n a m e / a
IF EXISTS < n a m e >
T Y P E < n a m e > OPT n
(If t h e file g i v e n is o n t h e c u r r e n t d i r e c t o r y , t y p e it
w i t h line n u m b e r s )
ELSE
ECHO " < n a m e > is n o t o n t h i s d i r e c t o r y "
ENDIF
RUN EXECUTE display work/prg2
s h o u l d d i s p l a y t h e file w o r k / p r g 2 w i t h line n u m b e r s o n t h e t e r m i n a l if it exists
o n t h e c u r r e n t d i r e c t o r y . If t h e file is n o t t h e r e , t h e s c r e e n d i s p l a y s t h e
following message:
;,IF,SKIP,FAILAT,LAB,ECHO,RUN,QUIT
Command:
Example # 2
Parameter Substitution by Keyword Name and/or Position
T h e . K E Y (or . K ) s t a t e m e n t s u p p l i e s b o t h k e y w o r d n a m e s a n d p o s i t i o n s in
c o m m a n d files. It tells E X E C U T E h o w m a n y p a r a m e t e r s t o e x p e c t a n d h o w t o
i n t e r p r e t t h e m . I n o t h e r w o r d s , . K E Y s e r v e s as a " t e m p l a t e " f o r t h e p a r a m e t e r
v a l u e s y o u s p e c i f y . O n l y o n e . K E Y s t a t e m e n t is a l l o w e d p e r c o m m a n d file. If
p r e s e n t , it s h o u l d b e t h e first c o m m a n d line in t h e file.
W h e n y o u enter a c o m m a n d line, A m i g a D O S resolves parameter substitutions for t h e k e y w o r d s in t w o w a y s : b y specification of the k e y w o r d in front of
t h e p a r a m e t e r , a n d b y t h e relative p o s i t i o n s o f t h e p a r a m e t e r s in t h e l i n e .
Keyword n a m e substitution takes precedence.
A s s u m e t h a t t h e e x e c u t e file n a m e d D E M O l c o n t a i n s t h e f o l l o w i n g . K E Y
statement:
.KEY flash,pan
tells A m i g a D O S to e x p e c t t w o p a r a m e t e r s u b s t i t u t i o n s , < f l a s h > a n d < p a n > .
( T h e a n g l e b r a c k e t s i n d i c a t e t h e k e y w o r d v a l u e to b e s u b s t i t u t e d at e x e c u t i o n
time.)
S u p p o s e y o u e n t e r t h e f o l l o w i n g c o m m a n d line:
AMIGADOS COMMANDS
57
58
A s a n e x a m p l e o f t h e u s e o f t h e /k o p t i o n , s u p p o s e y o u h a v e c r e a t e d a n
e x e c u t e file n a m e d C O M P I L E a n d it lets y o u o p t i o n a l l y s p e c i f y a f i l e n a m e to
w h i c h a p r i n t o u t o f t h e c o m p i l a t i o n is to b e d i r e c t e d . Y o u r . k e y
statement
might read:
.key compilewhat/a,printfile/k
If a u s e r e n t e r s a l i n e s u c h a s :
s i n c e m y p r i n t is s p e c i f i e d a s t h e t a r g e t
Thus
output
file.
Example # 2
Assigning Default Parameters and Different Bracket Characters
.KEY wordl
T h e . D E F d i r e c t i v e e s t a b l i s h e s a d e f a u l t v a l u e for a k e y w o r d if t h e u s e r d o e s
not specify a value on the c o m m a n d line. T o detect an unsupplied parameter
v a l u e , y o u c a n c o m p a r e it t o " "
must
p e r f o r m t h i s c o m p a r i s o n b e f o r e e x e c u t i n g a n y . D E F s t a t e m e n t in t h e e x e c u t e
file.
Y o u c a n a s s i g n d e f a u l t s i n e i t h e r o f t w o w a y s . T h e first w a y r e q u i r e s t h a t
y o u specify the default every time y o u reference a parameter, using the " $ "
operator.
For example, in the following statement:
AMIGADOS COMMANDS
59
T h e o u t p u t of b o t h of t h e a b o v e E C H O s t a t e m e n t s will b e :
.DEF wordl a
New default
ECHO " < w o r d l > is STILL the default for Wordl."
( T h e first a s s i g n m e n t , " d e f w o r d l " will b e s u b s t i t u t e d f o r w o r d l a t e x e c u t i o n
time.)
Example # 3
T h e I F s t a t e m e n t lets y o u p e r f o r m t e s t s a n d c a u s e d i f f e r e n t a c t i o n s b a s e d o n
t h e r e s u l t s of t h o s e t e s t s . A m o n g t h e p o s s i b l e t e s t s a r e t e s t i n g s t r i n g s f o r
e q u a l i t y a n d t e s t i n g t o s e e if a file e x i s t s . Y o u c a n u s e a n E L S E s t a t e m e n t w i t h
60
a n I F to s p e c i f y w h a t s h o u l d b e d o n e i n c a s e t h e I F c o n d i t i o n is n o t t r u e . T h e
E L S E s t a t e m e n t , if u s e d , is c o n s i d e r e d a p a r t o f t h e I F s t a t e m e n t b l o c k .
An
E N D I F t e r m i n a t e s a n IF s t a t e m e n t b l o c k .
T h e example programs below also use a SKIP statement. T h e SKIP statement
l e t s y o u s k i p F O R W A R D O N L Y w i t h i n y o u r e x e c u t e file to a l a b e l d e f i n e d b y a
LAB statement.
T h e I F . . . E N D I F s t r u c t u r e is i l l u s t r a t e d b y t h e f o l l o w i n g s h o r t e x a m p l e . It is
g e n e r a l l y a g o o d i d e a t o t e s t f o r k e y w o r d s t h a t m i g h t b e o m i t t e d , or m i g h t b e
entered as null ( " " ) in quotes, as s h o w n below:
prevents
EXECUTE
f r o m r e p o r t i n g a n e r r o r if t h e k e y w o r d
IF
is
omitted.
If y o u o m i t t h e d o u b l e q u o t e s a n d t h e v a l u e is n o t s u p p l i e d , t h e r e s u l t c a n b e
a line that reads:
IF EQ "usage"
This p r o d u c e s an error, b e c a u s e the t w o operators IF a n d E Q are adjacent.
U s i n g d o u b l e q u o t e s a r o u n d t h e k e y w o r d r e p l a c e m e n t i n d i c a t o r s r e s u l t s in a
line that reads:
IF "" EQ "usage"
w h i c h is l e g a l .
Y o u c a n u s e N O T in a n I F s t a t e m e n t to r e v e r s e t h e m e a n i n g o f t h e t e s t y o u
perform. For example:
For
AMIGADOS COMMANDS
61
; ( A s s i g n p a r a m e t e r list)
; ( C h e c k f o r a F R O M file)
; ( C h e c k f o r a T O file)
; ( N o file, s h o w u s e r h o w to)
; ( N o file, s h o w u s e r h o w t o u s e )
; ( C h e c k if T O file e x i s t s . )
;(Did the user supply " O " )
ECHO " R e p l a c e d file n a m e d < t o > w i t h a copy of file n a m e d < f r o m > "
ECHO " R e q u e s t fulfilled."
ELSE
ECHO " C o m m a n d will o v e r w r i t e a n e x i s t i n g file ONLY i f '
ECHO " t h e 0 p a r a m e t e r is specified."
ECHO " R e q u e s t Denied"
SKIP usage
ENDIF
; ( E x p l a i n h o w to u s e t h i s file)
AMIGADOS USER'S M A N U A L
62
ELSE
Example # 4
The SKIP command allows only forward jumps. To create a loop structure
within a command file, use EXECUTE iteratively. That is, use the EXECUTE
command within the file itself to send execution backwards to a label. The
following executable example illustrates looping.
This file displays five messages:
"This message
"Loop number
"Loop number
"Loop number
"This message
AMIGADOS COMMANDS
63
LAB lst-loop
I F " < l o o p c n t > " EQ " I I I "
SKIP loopend-<looplabel>
ENDIF
;(Yes, unwind.)
EXECUTE, loop.sample " < p a r m l > " " < p a r m 2 > " < l o o p c n t > I
lst-loop
LAB loopend-<looplabel>
I F NOT " < l o o p c n t > " EQ " "
SKIP EXIT
ENDIF
;(End of loop)
ECHO " T h i s m e s s a g e p r i n t s once at t h e end. [ < p a r m l > , < p a r m 2 > ) "
LAB E X I T
FAILAT
Format:
FAILAT
Template:
<n>
Purpose:
T o i n s t r u c t a c o m m a n d s e q u e n c e t o fail if a p r o g r a m r e t u r n s a n e r r o r
c o d e g r e a t e r t h a n or e q u a l t o t h i s n u m b e r .
Specification:
C o m m a n d s i n d i c a t e t h a t t h e y h a v e failed in s o m e w a y b y s e t t i n g a r e t u r n c o d e .
A nonzero return code indicates that the c o m m a n d has found an error of s o m e
s o r t . A r e t u r n c o d e g r e a t e r t h a n or e q u a l to a c e r t a i n limit ( t h e fail limit)
terminates a s e q u e n c e of noninteractive c o m m a n d s (that is, t h e
commands
t h a t y o u s p e c i f y a f t e r R U N o r in a n E X E C U T E file). T h e r e t u r n c o d e i n d i c a t e s
h o w s e r i o u s t h e e r r o r w a s , a n d is n o r m a l l y 5 , 1 0 , or 2 0 .
Y o u m a y u s e t h e F A I L A T c o m m a n d to a l t e r t h i s fail l e v e l f r o m its initial
v a l u e o f 1 0 . If y o u i n c r e a s e t h e l e v e l , y o u i n d i c a t e t h a t c e r t a i n c l a s s e s o f e r r o r
s h o u l d n o t b e r e g a r d e d as fatal, a n d t h a t e x e c u t i o n o f s u b s e q u e n t c o m m a n d s
m a y p r o c e e d after an error. T h e a r g u m e n t should be a positive n u m b e r . T h e
fail l e v e l is r e s e t t o t h e initial v a l u e o f 10 o n exit f r o m t h e c o m m a n d s e q u e n c e .
You must use FAILAT before commands
c o m m a n d h a s failed; otherwise,
s u c h as I F t o t e s t to s e e if a
the c o m m a n d
sequence terminates
before
executing the IF c o m m a n d .
If y o u o m i t t h e a r g u m e n t , t h e c u r r e n t v a l u e o f t h e fail l e v e l is d i s p l a y e d .
Examples:
FAILAT 2 5
64
T h e c o m m a n d s e q u e n c e o n l y t e r m i n a t e s b e f o r e t h e e n d if a c o m m a n d s t o p s
w i t h a r e t u r n c o d e g r e a t e r t h a n or e q u a l to ( > = ) 2 5 .
See also: I F , E X E C U T E , R U N , Q U I T
FAULT
Format:
FAULT[<n>*]
Template:
FAULT " , "
Purpose:
T o display t h e m e s s a g e s c o r r e s p o n d i n g t o t h e fault c o d e s y o u s u p p l y .
Specification:
A m i g a D O S looks u p the n u m b e r s a n d displays the corresponding messages. U p
to ten m e s s a g e s m a y b e displayed.
Examples:
FAULT 2 2 2
d i s p l a y s t h e m e s s a g e for fault 2 2 2 .
FAULT 2 2 1 1 0 3 1 2 1 2 1 8
d i s p l a y s t h e m e s s a g e s for faults 2 2 1 , 1 0 3 , 1 2 1 , a n d 2 1 8 .
FILENOTE
Format:
F I L E N O T E [FILE] < f i l e > C O M M E N T < s t r i n g >
Template:
FILENOTE "FILE/A,COMMENT/K"
Purpose:
T o a t t a c h a c o m m e n t o r a n o t e to a file.
Specification:
F I L E N O T E a s s i g n s a c o m m e n t to a s p e c i f i e d file.
T h e k e y w o r d C O M M E N T introduces a n optional c o m m e n t o f u p to 80
c h a r a c t e r s . A c o m m e n t m a y b e m o r e t h a n o n e w o r d (that i s , c o n t a i n s p a c e s
b e t w e e n characters). In this case, y o u m u s t enclose the c o m m e n t within double
quotes (").
A c o m m e n t is a s s o c i a t e d w i t h a p a r t i c u l a r file. W h e n y o u e x a m i n e t h e file
w i t h t h e c o m m a n d L I S T , t h e c o m m e n t a p p e a r s o n t h e line b e l o w :
prog
3 0 rwed Today 1 1 : 0 7 : 3 3
: version 3.2 - 2 3 - m a r - 8 5
W h e n y o u c r e a t e a n e w file, it d o e s n o t n o r m a l l y h a v e a c o m m e n t . If y o u
o v e r w r i t e a n e x i s t i n g file t h a t h a s a c o m m e n t , t h e n t h e c o m m e n t is r e t a i n e d
AMIGADOS COMMANDS
65
e v e n t h o u g h t h e c o n t e n t s o f t h e file h a v e c h a n g e d . T h e c o m m a n d C O P Y c o p i e s
a file. If a file w i t h a c o m m e n t is c o p i e d , t h e n e w file d o e s n o t h a v e t h e
c o m m e n t f r o m t h e o r i g i n a l a t t a c h e d t o it a l t h o u g h t h e d e s t i n a t i o n file m a y h a v e
a c o m m e n t w h i c h is r e t a i n e d .
Examples:
F I L E N O T E p r o g 2 C O M M E N T " V e r 3.3
26-mar-85"
LIST
FORMAT
Format:
Template:
Purpose:
T o f o r m a t a n d initialize a n e w 3 /2-inch f l o p p y d i s k .
Specification:
1
W A R N I N G : F O R M A T f o r m a t s a n d initializes a d i s k a s a n e m p t y d i s k . If
y o u u s e a d i s k t h a t is n o t e m p t y , y o u ' l l l o s e t h e p r e v i o u s c o n t e n t s o f t h e
disk.
T h e n a m e a s s i g n e d s h o u l d b e u n i q u e . It m a y b e o n e to t h i r t y c h a r a c t e r s i n
l e n g t h a n d c o m p o s e d o f o n e or m o r e w o r d s s e p a r a t e d b y s p a c e s . If t h e
n a m e is m o r e t h a n o n e w o r d , y o u s h o u l d e n c l o s e it i n d o u b l e q u o t e s .
N o t e : It is n o t n e c e s s a r y t o f o r m a t a d i s k if y o u a r e a b o u t t o D I S K C O P Y t o it.
Examples:
F O R M A T D R I V E dfO: N A M E " W o r k d i s k "
f o r m a t s a n d initializes t h e d i s k in drive " d f O " w i t h t h e n a m e " W o r k d i s k " .
See also:
AMIGADOS USER'S M A N U A L
66
IF
Format:
IF[NOT][WARN][ERROR][FAIL][<str>EQ<str>][EXISTS
Template:
IF
Purpose:
<name>]
"NOT/S,WARN/S,ERROR/S,FAIL/S,EQ/K,EXISTS/K"
Specification:
Y o u c a n o n l y u s e t h i s c o m m a n d in a n E X E C U T E c o m m a n d file. If o n e or m o r e
of t h e s p e c i f i e d c o n d i t i o n s is s a t i s f i e d , IF carries o u t all t h e f o l l o w i n g c o m m a n d s u n t i l it f i n d s a c o r r e s p o n d i n g E N D I F or E L S E c o m m a n d ; o t h e r w i s e , if
t h e c o n d i t i o n s a r e n o t s a t i s f i e d , it carries o u t w h a t e v e r f o l l o w s a c o r r e s p o n d i n g
E L S E c o m m a n d . ( E N D I F a n d E L S E a r e o n l y u s e f u l in c o m m a n d s e q u e n c e s
containing IF.) E N D I F terminates an IF c o m m a n d ; E L S E provides an alternative
if t h e I F c o n d i t i o n s fail. N o t e t h a t t h e c o n d i t i o n s a n d c o m m a n d s in I F a n d
E L S E c o m m a n d s c a n s p a n m o r e t h a n o n e line b e f o r e their c o r r e s p o n d i n g
ENDIFs.
T h e following table s h o w s s o m e of the w a y s y o u can u s e t h e IF, E L S E , a n d
ENDIF commands:
IF < c o n d i t i o n >
< command >
ENDIF
IF < c o n d i t i o n >
<command>
ELSE
<command>
ENDIF
IF < c o n d i t i o n >
< command >
IF < c o n d i t i o n >
<command>
ENDIF
ENDIF
N o t e t h a t E L S E is o p t i o n a l a n d t h a t n e s t e d I F s j u m p to t h e n e a r e s t E N D I F .
E R R O R is o n l y available if y o u set F A I L A T t o g r e a t e r t h a n 1 0 . S i m i l a r l y ,
F A I L is o n l y a v a i l a b l e if y o u s e t F A I L A T t o g r e a t e r t h a n 2 0 .
Keyword
NOT
WARN
ERROR
FAIL
<a>EQ<b>
Function
reverses the result.
s a t i s f i e d if p r e v i o u s r e t u r n c o d e > = 5 .
// // // // // //
> = 10.
// // // //
// // // //
> = 20.
s a t i s f i e d if t h e text of a a n d b is
identical (disregarding case),
s a t i s f i e d if t h e file e x i s t s .
AMIGADOS COMMANDS
67
Examples:
IF EXISTS work/prog
TYPE work/prog
ELSE
ECHO "file not found"
ENDIF
If t h e file " w o r k / p r o g " exists, t h e n A m i g a D O S displays it. O t h e r w i s e , A m i g a D O S
displays the m e s s a g e "file not f o u n d " and executes the next c o m m a n d in the
command sequence.
IF ERROR
SKIP errlab
ENDIF
If t h e p r e v i o u s c o m m a n d s t o p p e d w i t h a r e t u r n c o d e > = 1 0 , t h e n A m i g a D O S
s k i p s t h e c o m m a n d s e q u e n c e u n t i l y o u d e f i n e a label " e r r l a b " w i t h t h e L A B
command.
IF ERROR
IF EXISTS fred
ECHO "The file 'fred' exists, but an error occurred anyway."
ENDIF
ENDIF
See also:
FAILAT,SKIP,LAB,EXECUTE,QUIT
INFO
Format:
Template:
Purpose:
INFO
INFO
T o g i v e i n f o r m a t i o n a b o u t t h e filing s y s t e m .
Specification:
T h e c o m m a n d d i s p l a y s a line of i n f o r m a t i o n a b o u t e a c h d i s k u n i t . T h i s
i n c l u d e s t h e m a x i m u m size of t h e d i s k , t h e c u r r e n t u s e d a n d f r e e s p a c e ,
t h e n u m b e r of s o f t d i s k e r r o r s t h a t h a v e o c c u r r e d , a n d t h e s t a t u s of t h e
disk.
Examples:
INFO
68
Unit
Size
Errs
Status
Name
DF1:
880K
Used
2
Free
1756
Full
0%
Read/Write
Test-6
DFO:
880K
1081
677
61%
Read/Write
AmigaDOS CLI
Volumes available:
Test-6 [Mounted]
A m i g a D O S CLI [ M o u n t e d ]
INSTALL
Format:
INSTALL[DRIVE]<drive>
Template:
INSTALL "DRIVE/A"
Purpose:
Specification:
T h e p u r p o s e o f t h e I N S T A L L c o m m a n d is to m a k e a d i s k b o o t a b l e ( t h a t i s , y o u
c a n u s e I N S T A L L t o m a k e a d i s k t h a t starts u p y o u r A m i g a ) . T o d o t h i s , y o u
simply type t h e n a m e of the drive w h e r e y o u h a v e inserted the disk that y o u
w a n t to b e c o m e t h e b o o t ( s t a r t u p ) d i s k . T h e r e a r e f o u r p o s s i b l e d r i v e n a m e s :
DF0:,DF1:,DF2:, and DF3:.
Examples:
I N S T A L L dfO:
m a k e s t h e d i s k in d r i v e " d f O : " a b o o t a b l e d i s k .
JOIN
Format:
Template:
Purpose:
T o c o n c a t e n a t e u p to 15 files t o f o r m a n e w file.
Specification:
A m i g a D O S c o p i e s t h e s p e c i f i e d files in t h e o r d e r y o u g i v e i n t o t h e n e w
file. N o t e t h a t t h e n e w file c a n n o t h a v e t h e s a m e n a m e a s a n y o f t h e i n p u t
files.
Examples:
J O I N p a r t i p a r t 2 AS textfile
69
AMIGADOS COMMANDS
LAB
Format:
LAB <string>
Template:
Purpose:
T o i m p l e m e n t l a b e l s in c o m m a n d s e q u e n c e files.
Specification:
T h e c o m m a n d ignores a n y parameters you give. U s e L A B to define a label
" t e x t " t h a t is l o o k e d for b y t h e c o m m a n d S K I P .
Examples:
LAB errlab
d e f i n e s t h e l a b e l " e r r l a b " to w h i c h S K I P m a y j u m p .
See also:
SKIP,IF,EXECUTE
LIST
Format:
LIST[[DIR]<dir>][P|PAT
<pat>][KEYS][DATES][NODATES][TO
<name>][S<str>][SINCE <date>][UPTO
<date>][QUICK]
Template:
Purpose:
T o e x a m i n e a n d list s p e c i f i e d i n f o r m a t i o n a b o u t a d i r e c t o r y or file.
SINCE/K,UPTO/K,QUICK/S"
Specification:
If y o u d o n o t s p e c i f y a n a m e ( t h e p a r a m e t e r D I R ) , L I S T d i s p l a y s t h e c o n t e n t s o f
t h e c u r r e n t d i r e c t o r y . T h e first p a r a m e t e r L I S T a c c e p t s is D I R . Y o u h a v e t h r e e
o p t i o n s . D I R m a y b e a f i l e n a m e , in w h i c h c a s e L I S T d i s p l a y s t h e file i n f o r m a t i o n f o r t h a t o n e file. S e c o n d l y , D I R m a y b e a d i r e c t o r y n a m e . I n t h i s c a s e L I S T
d i s p l a y s file i n f o r m a t i o n for files ( a n d o t h e r d i r e c t o r i e s ) w i t h i n t h e s p e c i f i e d
d i r e c t o r y . L a s t l y , if y o u o m i t t h e D I R p a r a m e t e r , L I S T d i s p l a y s i n f o r m a t i o n
a b o u t files a n d d i r e c t o r i e s w i t h i n t h e c u r r e n t d i r e c t o r y (for f u r t h e r d e t a i l s o n
the current directory, see the C D c o m m a n d ) .
N o t e : L I S T , u n l i k e D I R , d o e s N O T sort t h e d i r e c t o r y b e f o r e d i s p l a y i n g it.
If n o o t h e r o p t i o n s a r e s p e c i f i e d , L I S T d i s p l a y s :
file name
: comment
70
T h e s e f i e l d s a r e d e f i n e d as f o l l o w s :
file
name:
size:
N a m e o f file or d i r e c t o r y .
T h e size o f t h e file in b y t e s . If t h e r e is n o t h i n g in t h e file, t h i s
field will s t a t e " e m p t y " . F o r d i r e c t o r i e s t h i s e n t r y s t a t e s " d i r " .
protection:
T h i s s p e c i f i e s t h e a c c e s s a v a i l a b l e for t h i s file; r w e d i n d i c a t e s
Read, Write, Execute, and Delete.
T h e file c r e a t i o n d a t e a n d t i m e .
comment:
T h i s is t h e c o m m e n t p l a c e d o n t h e file u s i n g t h e F I L E N O T E
c o m m a n d . N o t e t h a t it is p r e c e d e d w i t h a c o l o n (:).
O p t i o n s available:
TO
KEYS
D i s p l a y s t h e b l o c k n u m b e r o f e a c h file h e a d e r o r d i r e c t o r y .
DATES
NODATES
SINCE
<date>
<date>
c a n b e in t h e f o r m D D - M M M - Y Y or a d a y n a m e in t h e last
w e e k (for e x a m p l e , M O N D A Y ) or T O D A Y o r Y E S T E R D A Y .
UPTO
<date>
P<pat>
S<str>
QUICK
J u s t d i s p l a y s t h e n a m e s of files a n d d i r e c t o r i e s (like t h e D I R
command).
Y o u c a n s p e c i f y t h e r a n g e of f i l e n a m e s d i s p l a y e d i n t w o w a y s . T h e s i m p l e s t
w a y is to u s e t h e S k e y w o r d , w h i c h r e s t r i c t s t h e listing to t h o s e files c o n t a i n i n g
the specified substring. To specify a m o r e complicated search expression, use
t h e P o r P A T k e y w o r d . T h i s is f o l l o w e d b y a p a t t e r n t h a t m a t c h e s as d e s c r i b e d
below.
A p a t t e r n c o n s i s t s o f a n u m b e r of s p e c i a l c h a r a c t e r s w i t h s p e c i a l m e a n i n g s ,
a n d a n y other characters that m a t c h t h e m .
T h e special characters are: ' ( ) ? % # |
I n o r d e r t o r e m o v e t h e s p e c i a l e f f e c t o f t h e s e c h a r a c t e r s , p r e f a c e t h e m w i t h '.
T h u s '? m a t c h e s ? a n d ' ' m a t c h e s ' .
71
AMIGADOS COMMANDS
M a t c h e s a n y single character.
# < p >
M a t c h e s z e r o or m o r e o c c u r r e n c e s of t h e p a t t e r n
<pl><p2>
<pl>l<p2>
()
<p>.
match.
Thus:
LIST PAT A # B C
M a t c h e s A C A B C A B B C , a n d so forth.
M a t c h e s A D A B D A B C D , a n d so forth.
M a t c h e s A A B A B B A C B , a n d so forth.
LIST PAT A # ? B
M a t c h e s A B A X X B A Z X Q B , a n d so forth.
M a t c h e s ? # ? A B # ? ? # # , and so forth
M a t c h e s A A B C A C C C , a n d so forth.
LIST PAT # ( A B )
M a t c h e s A B A B A B A B A B A B , and so forth.
Examples:
LIST
d i s p l a y s i n f o r m a t i o n a b o u t all t h e files a n d d i r e c t o r i e s c o n t a i n e d in t h e c u r r e n t
directory. For example,
File_l
File 2
File.3
:comment
File004
LIST work S new
d i s p l a y s i n f o r m a t i o n a b o u t files i n t h e d i r e c t o r y " w o r k " w h o s e n a m e s c o n t a i n
t h e text " n e w " . N o t e t h a t L I S T S p r o d u c e s t h e r e s p o n s e : " A r g s n o g o o d f o r
k e y " b e c a u s e t h e r e is a n " S "
directory's
contents.
LIST w o r k P new#?(x|y)
e x a m i n e s t h e d i r e c t o r y " w o r k " , a n d d i s p l a y s i n f o r m a t i o n a b o u t all files t h a t
start w i t h t h e l e t t e r s " n e w " a n d t h a t e n d w i t h e i t h e r " x " o r " y " .
L I S T Q U I C K TO o u t f i l e
72
DATE, DIR,FILENOTE,PROTECT
MAKEDIR
Format:
Template:
MAKEDIR
Purpose:
T o m a k e a n e w directory.
"IA"
Specification:
M A K E D I R creates a directory with the n a m e y o u specify. T h e c o m m a n d only
c r e a t e s o n e d i r e c t o r y at a t i m e , s o a n y d i r e c t o r i e s o n t h e p a t h m u s t a l r e a d y
e x i s t . T h e c o m m a n d fails if t h e d i r e c t o r y o r a file o f t h e s a m e n a m e a l r e a d y
e x i s t s i n t h e d i r e c t o r y a b o v e it i n t h e h i e r a r c h y .
Examples:
MAKEDIR tests
creates a directory " t e s t s " in the current directory.
M A K E D I R dfl:xyz
c r e a t e s a d i r e c t o r y " x y z " i n t h e r o o t d i r e c t o r y of d i s k " d f l " .
M A K E D I R dfl:xyz/abc
creates a directory " a b c " in t h e parent directory " x y z " o n disk " d f l " . H o w e v e r ,
" x y z " m u s t exist for this c o m m a n d to w o r k .
See also:
DELETE
NEWCLI
Format:
NEWCLI[<window>]
Template:
NEWCLI
Purpose:
"WINDOW"
73
AMIGADOS COMMANDS
Specification:
A m i g a D O S creates a n e w CLI w i n d o w . T h e n e w w i n d o w b e c o m e s the currently selected process. T h e n e w w i n d o w has the same set directory
and
p r o m p t s t r i n g a s t h e o n e w h e r e N E W C L I is e x e c u t e d . E a c h C L I w i n d o w is
independent, allowing separate input, output, and program execution.
T o c o n n e c t t h e k e y b o a r d to y o u r n e w C L I , m o v e t h e m o u s e to p o i n t t h e c u r s o r
at t h e n e w w i n d o w , a n d p r e s s t h e left m o u s e b u t t o n ( t h a t i s , t h e S e l e c t i o n
B u t t o n ) . Y o u c a n p o i n t at a n y position o n t h e w i n d o w w h e n selecting a n e w C L I .
W h e n y o u give N E W C L I with n o argument, A m i g a D O S creates a w i n d o w of
s t a n d a r d size a n d p o s i t i o n . T o c h a n g e t h e size o f t h e w i n d o w , m o v e t h e m o u s e
to p o i n t t h e c u r s o r at t h e b o t t o m r i g h t c o r n e r ( s i z i n g G a d g e t ) , a n d p r e s s t h e
Selection Button. Y o u can then change the w i n d o w size. T o c h a n g e the position
o f t h e w i n d o w , m o v e t h e m o u s e to t h e D r a g B a r , p r e s s t h e left m o u s e b u t t o n
a n d m o v e t h e m o u s e to w h e r e y o u w a n t t h e w i n d o w .
T o customize a CLI w i n d o w , y o u can give an exact position a n d size or e v e n
a n e w title o n t h e title b a r . T h e " w i n d o w " s y n t a x to d o t h i s is a s f o l l o w s :
CON:x/y/width/height/title
w h e r e " C O N : " denotes a console w i n d o w , " x " and " y " are the coordinates
describing the w i n d o w ' s position, " w i d t h " a n d " h e i g h t " are the size of t h e
w i n d o w , a n d " t i t l e " is t h e s t r i n g y o u w a n t o n t h e title b a r . Y o u n e e d n o t s p e c i f y
a title s t r i n g a s it is o p t i o n a l , b u t y o u m u s t g i v e t h e f i n a l s l a s h
(/).
All
C0N:10/30/300/100/myCLI
c r e a t e s a n e w C L I at t h e p o s i t i o n 1 0 , 3 0 , o f size 3 0 0 x 1 0 0 p i x e l s , w i t h t h e title
"myCLl".
NEWCLI "C0N:20/15/300/100/my o w n CLI"
D o u b l e q u o t e s a l l o w t h e title t o h a v e s p a c e s . F o r f u r t h e r i n f o r m a t i o n o n t h e
console device, C O N : , see Section 1.3.6, Understanding Device N a m e s .
Note: Unlike a background process created with the R U N c o m m a n d ,
N E W C L I p r o c e s s h a n g s a r o u n d after y o u h a v e c r e a t e d it.
See also: E N D C L I , R U N
74
PROMPT
Format:
PROMPT<prompt>
Template:
PROMPT "PROMPT"
Purpose:
Specification:
It y o u d o n o t g i v e a p a r a m e t e r , t h e n A m i g o D O S r e s e t s t h e p r o m p t to t h e
s t a n d a r d s t r i n g ( " > " ) . O t h e r w i s e , t h e p r o m p t is s e t t o t h e s t r i n g y o u s u p p l y .
A m i g a D O S a l s o a c c e p t s o n e s p e c i a l c h a r a c t e r c o m b i n a t i o n ( % N ) . T h i s is d e m o n s t r a t e d in t h e e x a m p l e b e l o w .
Examples:
PROMPT
resets the current p r o m p t to " > " .
PROMPT " % N >
"
process
number.
PROTECT
Format:
Template:
Purpose:
Specification:
P R O T E C T t a k e s a file a n d s e t s its p r o t e c t i o n s t a t u s .
T h e k e y w o r d F L A G S t a k e s f o u r o p t i o n s : r e a d (r), w r i t e ( w ) , d e l e t e ( d ) , a n d
e x e c u t e ( e ) . T o s p e c i f y t h e s e o p t i o n s y o u t y p e a n r, w , d , o r e a f t e r t h e n a m e o f
t h e file. If y o u o m i t a n o p t i o n , P R O T E C T a s s u m e s t h a t y o u d o n o t r e q u i r e it.
F o r i n s t a n c e , if y o u g i v e all t h e o p t i o n s e x c e p t d, P R O T E C T e n s u r e s t h a t y o u
c a n n o t d e l e t e t h e file. R e a d , w r i t e , a n d d e l e t e c a n r e f e r t o a n y k i n d o f file.
A m i g a D O S o n l y p a y s a t t e n t i o n to t h e d e l e t e (d) flag in t h e c u r r e n t r e l e a s e .
U s e r s a n d u s e r p r o g r a m s , h o w e v e r , c a n s e t a n d t e s t t h e s e flags if t h e y w i s h .
Examples:
PROTECT p r o g l FLAGS r
75
AMIGADOS COMMANDS
s e t s t h e p r o t e c t i o n s t a t u s of p r o g r a m 1 as r e a d o n l y .
PROTECT p r o g 2 r w d
sets the protection of program 2 as read/write/delete.
See also:
LIST
QUIT
Format:
QUIT[<returncode>]
Template:
Purpose:
T o exit f r o m a c o m m a n d s e q u e n c e w i t h a g i v e n e r r o r c o d e .
Specification:
Q U I T r e a d s t h r o u g h t h e c o m m a n d file a n d t h e n s t o p s w i t h a r e t u r n c o d e . T h e
d e f a u l t r e t u r n c o d e is z e r o .
Examples:
QUIT
exits t h e current c o m m a n d s e q u e n c e .
FAILAT 3 0
IF ERROR
QUIT 2 0
ENDIF
If t h e last c o m m a n d w a s in error, this terminates t h e c o m m a n d
sequence
EXECUTE,IF,LAB,SKIP
RELABEL
Format:
Template:
Purpose:
T o c h a n g e t h e v o l u m e n a m e of a disk.
EXECUTE
76
Specification:
R E L A B E L c h a n g e s t h e v o l u m e n a m e o f a d i s k to t h e < n a m e >
you specify.
V o l u m e n a m e s a r e s e t initially w h e n y o u f o r m a t a d i s k .
Examples:
FORMAT
RENAME
Format:
Template:
Purpose:
T o r e n a m e a file or d i r e c t o r y .
Specification:
R E N A M E r e n a m e s t h e F R O M file w i t h t h e s p e c i f i e d T O n a m e . F R O M a n d T O
m u s t b e f i l e n a m e s o n t h e s a m e d i s k . T h e F R O M n a m e m a y r e f e r t o a file o r t o a
d i r e c t o r y . If t h e f i l e n a m e r e f e r s to a d i r e c t o r y , R E N A M E l e a v e s t h e c o n t e n t s o f
t h e d i r e c t o r y u n c h a n g e d ( t h a t i s , t h e d i r e c t o r i e s a n d files w i t h i n t h a t d i r e c t o r y
keep the same contents and names).
O n l y t h e n a m e o f t h e d i r e c t o r y is c h a n g e d w h e n y o u u s e R E N A M E . If y o u
r e n a m e a d i r e c t o r y , o r if y o u u s e R E N A M E t o g i v e a file a n o t h e r
directory
n a m e (for e x a m p l e , r e n a m e :bill/letter a s : m a r y / l e t t e r ) , A m i g a D O S c h a n g e s t h e
p o s i t i o n o f t h e d i r e c t o r y , or file, i n t h e filing s y s t e m h i e r a r c h y . U s i n g R E N A M E
is l i k e c h a n g i n g t h e title o f a file a n d t h e n m o v i n g it t o a n o t h e r s e c t i o n o r
d r a w e r in t h e filing c a b i n e t . S o m e o t h e r s y s t e m s d e s c r i b e t h e a c t i o n a s " m o v i n g " a file o r d i r e c t o r y .
T h e R E N A M E c o m m a n d will n o t e x e c u t e if t h e o n l y c h a n g e is t h e " c a s e " o f
o n e or m o r e letters. For example,
77
AMIGADOS COMMANDS
RUN
Atw-crf fa -
Format:
Template:
Purpose:
Specification:
R U N creates a noninteractive C o m m a n d Line Interface (CLI) process a n d gives
it t h e r e s t o f t h e c o m m a n d line a s i n p u t . T h e b a c k g r o u n d C L I e x e c u t e s t h e
c o m m a n d s a n d t h e n d e l e t e s itself.
T h e n e w C L I h a s t h e s a m e set d i r e c t o r i e s a n d c o m m a n d s t a c k size a s t h e C L I
w h e r e y o u called R U N .
To separate c o m m a n d s , type a plug sign ( + ) a n d press R E T U R N .
interprets the next line after a +
RUN
same
several
SEARCH
Format:
Template:
Purpose:
Specification:
S E A R C H l o o k s t h r o u g h all t h e files in t h e s p e c i f i e d d i r e c t o r y , a n d a n y files in
s u b d i r e c t o r i e s if y o u s p e c i f y A L L . S E A R C H d i s p l a y s a n y l i n e t h a t c o n t a i n s t h e
78
t e x t y o u s p e c i f i e d as S E A R C H . It a l s o d i s p l a y s t h e n a m e o f t h e file c u r r e n t l y
being searched.
Y o u can also replace the directory F R O M with a pattern. (See the c o m m a n d
L I S T f o r a full d e s c r i p t i o n o f p a t t e r n s . ) If y o u u s e a p a t t e r n , S E A R C H o n l y
l o o k s t h r o u g h files t h a t m a t c h t h e s p e c i f i e d p a t t e r n . T h e n a m e m a y a l s o
c o n t a i n d i r e c t o r i e s s p e c i f i e d as a p a t t e r n .
A m i g a D O S l o o k s for e i t h e r u p p e r or l o w e r c a s e o f t h e s e a r c h s t r i n g . N o t e
that y o u m u s t place quotation marks a r o u n d a n y text containing a space.
A s u s u a l , to a b a n d o n the c o m m a n d , p r e s s C T R L - C , the attention flag. T o
a b a n d o n t h e s e a r c h o f t h e c u r r e n t file a n d c o n t i n u e o n to t h e n e x t file, if a n y ,
press CTRL-D.
Examples:
SEARCH SEARCH vflag
s e a r c h e s t h r o u g h t h e files in t h e c u r r e n t d i r e c t o r y l o o k i n g f o r t h e text " v f l a g " .
S E A R C H dfO: " H a p p y d a y " A L L
l o o k s for files c o n t a i n i n g t h e t e x t " H a p p y d a y " o n t h e e n t i r e d i s k " d f O : " .
SEARCH t e s t - # ? vflag
l o o k s for t h e text " v f l a g " in all files in t h e c u r r e n t d i r e c t o r y s t a r t i n g w i t h " t e s t - " .
SKIP
Format:
Template:
Purpose:
T o p e r f o r m a j u m p in a c o m m a n d s e q u e n c e .
Specification:
Y o u u s e S K I P in conjunction with L A B . (See L A B for details.) S K I P reads
t h r o u g h t h e c o m m a n d file l o o k i n g f o r a l a b e l y o u d e f i n e d w i t h L A B , w i t h o u t
executing any commands.
Y o u c a n u s e S K I P e i t h e r w i t h o r w i t h o u t a l a b e l ; w i t h o u t o n e , it f i n d s t h e
n e x t u n n a m e d L A B c o m m a n d . W i t h o n e , it a t t e m p t s to f i n d a L A B d e f i n i n g a
l a b e l , as s p e c i f i e d . L A B m u s t b e t h e first i t e m o n a l i n e o f t h e file. If S K I P d o e s
n o t find the label y o u specified, the sequence terminates a n d
displays the following message:
label " < l a b e l > " not found b y Skip
AmigaDOS
AMIGADOS COMMANDS
79
S K I P o n l y j u m p s f o r w a r d in t h e c o m m a n d s e q u e n c e .
Examples:
SKIP
s k i p s to t h e n e x t L A B c o m m a n d w i t h o u t a n a m e f o l l o w i n g it.
IF ERROR
SKIP errlab
ENDIF
If t h e last c o m m a n d s t o p p e d w i t h a r e t u r n c o d e > = 2 0 , t h i s s e a r c h e s for t h e
l a b e l " e r r l a b " l a t e r in t h e c o m m a n d file.
FAILAT
100
ASSEM text
IF ERROR
SKIP ERROR
ENDIF
LINK
S K I P DONE
LAB ERROR
ECHO " E r r o r doing A s s e m "
L A B DONE
ECHO " N e x t c o m m a n d p l e a s e "
See also:
EXECUTE,LAB,IF,FAILAT,QUIT
SORT
Format:
SORT[FROM]<name>[[TO]<name>][COLSTART<n>]
Template:
SORT
Purpose:
T o sort s i m p l e files.
"FROM/A,TO/A,COLSTART/K"
Specification:
T h i s c o m m a n d is a v e r y s i m p l e sort p a c k a g e . Y o u c a n u s e S O R T t o s o r t files
a l t h o u g h it i s n ' t fast for l a r g e files, a n d it c a n n o t sort files t h a t d o n ' t fit i n t o
memory.
Y o u s p e c i f y t h e s o u r c e a s F R O M , a n d t h e s o r t e d r e s u l t g o e s t o t h e file T O .
S O R T a s s u m e s t h a t F R O M is a n o r m a l t e x t file w h e r e e a c h l i n e is s e p a r a t e d
80
w i t h a c a r r i a g e r e t u r n . E a c h line in t h e file is s o r t e d i n t o i n c r e a s i n g a l p h a b e t i c
order without distinguishing between upper and lower cases.
T o alter t h i s in a v e r y l i m i t e d w a y , u s e t h e C O L S T A R T k e y w o r d t o s p e c i f y
t h e first c o l u m n w h e r e t h e c o m p a r i s o n is to t a k e p l a c e . S O R T t h e n c o m p a r e s
t h e c h a r a c t e r s o n t h e line f r o m t h e s p e c i f i e d s t a r t i n g p o s i t i o n to t h e e n d ; if t h e
l i n e s still m a t c h a f t e r t h i s , t h e n t h e r e m a i n i n g c o l u m n s f r o m t h e first t o j u s t
b e f o r e t h e c o l u m n s p e c i f i e d as C O L S T A R T a r e i n c l u d e d in t h e c o m p a r i s o n .
N o t e : T h e initial s t a c k size ( t h a t i s , 4 0 0 0 b y t e s ) is o n l y s u i t a b l e for s m a l l files
of l e s s t h a n 2 0 0 l i n e s or s o . If y o u w a n t to s o r t larger f i l e s , y o u m u s t u s e t h e
S T A C K c o m m a n d to increase the stack size; h o w m u c h y o u should increase the
s i z e is p a r t skill a n d p a r t g u e s s w o r k .
W A R N I N G : T h e A m i g a will c r a s h if S T A C K is t o o s m a l l . If y o u a r e n o t
s u r e , it is b e t t e r to o v e r e s t i m a t e t h e a m o u n t y o u n e e d .
Examples:
X ,
STACK
STACK
Format:
Template:
STACK[<n>]
STACK "SIZE"
Purpose:
T o d i s p l a y o r s e t t h e s t a c k size for c o m m a n d s .
Specification:
W h e n y o u r u n a p r o g r a m , it u s e s a c e r t a i n a m o u n t of stack s p a c e . In m o s t
c a s e s , t h e initial s t a c k s i z e , 4 0 0 0 b y t e s , is sufficient, b u t y o u c a n alter it u s i n g
the S T A C K c o m m a n d . To do this, you type S T A C K followed by the n e w stack
81
AMIGADOS COMMANDS
v a l u e . Y o u s p e c i f y t h e v a l u e o f t h e s t a c k size in b y t e s . S T A C K a l o n e d i s p l a y s
the currently set stack size.
T h e o n l y c o m m a n d t h a t y o u w o u l d n o r m a l l y n e e d t o alter t h e s t a c k s i z e f o r
is t h e S O R T c o m m a n d . R e c u r s i v e c o m m a n d s s u c h a s D I R n e e d a n i n c r e a s e d
s t a c k if y o u u s e t h e m o n a d i r e c t o r y s t r u c t u r e m o r e t h a n a b o u t six l e v e l s d e e p .
W A R N I N G : T h e o n l y i n d i c a t i o n t h a t y o u h a v e r u n o u t o f s t a c k is t h a t t h e
A m i g a c r a s h e s ! If y o u a r e n o t s u r e , it is b e t t e r t o o v e r e s t i m a t e t h e a m o u n t
you need.
Examples:
STACK
displays the current stack size.
STACK 8 0 0 0
s e t s t h e s t a c k to 8 0 0 0 b y t e s .
See also: R U N , S O R T
STATUS
Format:
STATUS[<process>][FULL][TCB][SEGS][CLI|ALL]
Template:
Purpose:
Specification:
S T A T U S a l o n e lists t h e n u m b e r s o f t h e C L I p r o c e s s e s a n d t h e p r o g r a m r u n n i n g
in e a c h .
P R O C E S S specifies a process n u m b e r a n d only gives information about that
p r o c e s s . O t h e r w i s e , i n f o r m a t i o n is d i s p l a y e d a b o u t all p r o c e s s e s .
FULL =
SEGS + TCB +
CLI
S E G S d i s p l a y s t h e n a m e s of t h e s e c t i o n s o n t h e s e g m e n t list o f e a c h p r o c e s s .
T C B displays information about the priority, stacksize, a n d global vector size
of each process.
For further details on stack a n d global vector size,
see the
AmigaDOS
82
Examples:
STATUS
d i s p l a y s b r i e f i n f o r m a t i o n a b o u t all p r o c e s s e s .
STATUS 4 FULL
d i s p l a y s full i n f o r m a t i o n a b o u t p r o c e s s 4 .
TYPE
Format:
Template:
Purpose:
Specification:
T O i n d i c a t e s t h e o u t p u t file t h a t y o u s p e c i f y ; if y o u o m i t t h i s , o u t p u t is t o t h e
c u r r e n t o u t p u t s t r e a m , w h i c h m e a n s , in m o s t c a s e s , t h a t t h e o u t p u t g o e s t o t h e
current window.
T a b s t h a t y o u h a v e g i v e n in t h e file a r e e x p a n d e d . H o w e v e r , t a b s are n o t
t r e a t e d as s p e c i a l b y T Y P E ; t h e c o n s o l e d r i v e r p r o c e s s e s t h e m . T o i n t e r r u p t
o u t p u t , p r e s s C T R L - C . T o s u s p e n d o u t p u t , p r e s s t h e s p a c e b a r or t y p e a n y
o t h e r c h a r a c t e r . T o r e s u m e o u t p u t , p r e s s R E T U R N or C T R L - X .
O P T s p e c i f i e s a n o p t i o n to T Y P E . T h e first o p t i o n to T Y P E is " n " ,
which
i n c l u d e s l i n e n u m b e r s in t h e o u t p u t .
T h e s e c o n d o p t i o n y o u c a n g i v e T Y P E is " h . " U s e t h e " h " o p t i o n to w r i t e o u t
e a c h w o r d o f t h e F R O M file as a h e x n u m b e r .
Examples:
TYPE work/prog
d i s p l a y s t h e file " w o r k / p r o g " .
T Y P E w o r k / p r o g OPT n
d i s p l a y s t h e file " w o r k / p r o g " w i t h l i n e n u m b e r s .
T Y P E o b j / p r o g OPT h
d i s p l a y s t h e c o d e s t o r e d in " o b j / p r o g " in h e x a d e c i m a l .
83
AMIGADOS COMMANDS
WAIT
Format:
WAIT <n>[SEC|SECS][MIN|MINS][UNTIL
Template:
<time>]
Purpose:
T o w a i t for t h e s p e c i f i e d t i m e .
Specification:
Y o u c a n u s e W A I T in c o m m a n d s e q u e n c e s or a f t e r R U N t o w a i t f o r a c e r t a i n
p e r i o d , or t o w a i t u n t i l a c e r t a i n t i m e o f d a y . U n l e s s y o u s p e c i f y o t h e r w i s e , t h e
w a i t i n g t i m e is o n e s e c o n d .
T h e p a r a m e t e r s h o u l d b e a n u m b e r , s p e c i f y i n g t h e n u m b e r o f s e c o n d s (or
m i n u t e s , if M I N S is g i v e n ) to w a i t .
U s e t h e k e y w o r d U N T I L to w a i t u n t i l a specific t i m e o f d a y , g i v e n i n t h e
format H H : M M .
Examples:
WAIT
waits 1 second.
WAIT 10 MINS
w a i t s 10 m i n u t e s .
WAIT UNTIL 2 1 : 1 5
w a i t s u n t i l q u a r t e r p a s t n i n e at n i g h t .
WHY
Format:
WHY
Template:
WHY
Purpose:
Specification:
U s u a l l y w h e n a c o m m a n d fails t h e s c r e e n d i s p l a y s a b r i e f m e s s a g e t h a t s o m e t h i n g w e n t w r o n g . T h i s t y p i c a l l y i n c l u d e s t h e n a m e o f t h e file (if t h a t w a s t h e
p r o b l e m ) , b u t d o e s n o t go into a n y m o r e detail. For e x a m p l e , the c o m m a n d
COPY fred TO *
m i g h t fail a n d d i s p l a y t h e m e s s a g e
84
these
c a s e s , b e c a u s e u s u a l l y t h e u s e r k n o w s w h a t is w r o n g . H o w e v e r , i m m e d i a t e l y
after y o u c o m e across a c o m m a n d that h a s failed, y o u can type W H Y and press
R E T U R N t o d i s p l a y a m u c h fuller m e s s a g e , d e s c r i b i n g i n d e t a i l w h a t w e n t
wrong.
Examples:
TYPE DFO:
c a n t open DFO:
WHY
b e c a u s e A m i g a D O S w o n ' t let y o u t y p e a d e v i c e .
See also:
FAULT
ALINK[[FROM|ROOT]<filename>[,<filename>*| + <filename*]]
[TO < n a m e > ] [ W I T H < n a m e > ] [ L I B R A R Y | L I B < n a m e > ]
<map>][XREF <name>][WIDTH
Template:
ALINK
[MAP
<n>]
" F R O M = R O O T , T O / K , W I T H / K , V E R / K , L I B R A R Y = LIB/K,
MAP/K,XREF/K,WIDTH/K"
Purpose:
T o l i n k t o g e t h e r s e c t i o n s o f c o d e i n t o a n e x e c u t a b l e file.
Specification:
ALINK
instructs
AmigaDOS
t o l i n k files t o g e t h e r .
It a l s o h a n d l e s
m a t i c l i b r a r y r e f e r e n c e s a n d b u i l d s o v e r l a y files. T h e o u t p u t f r o m
is a file l o a d e d
by
the
the
overlay
autoALINK
supervisor,
if
required.
F o r d e t a i l s a n d a full s p e c i f i c a t i o n o f t h e A L I N K c o m m a n d , s e e C h a p t e r 4 o f
t h e AmigaDOS
Developer's
Manual
in t h i s b o o k .
AMIGADOS COMMANDS
85
Examples:
A L I N K a + b + c TO o u t p u t
l i n k s t h e files " a " , " b " , a n d " c " , p r o d u c i n g a n o u t p u t file " o u t p u t " .
ASSEM
Format:
Template:
Purpose:
T o a s s e m b l e a p r o g r a m in M C 6 8 0 0 0 a s s e m b l y l a n g u a g e .
Specification:
A S S E M a s s e m b l e s p r o g r a m s in M C 6 8 0 0 0 a s s e m b l y l a n g u a g e . S e e C h a p t e r 3 o f
t h e AmigaDOS
Developer's
Manual
in t h i s b o o k f o r d e t a i l s .
PROG
is t h e s o u r c e file.
-O
is t h e o b j e c t file ( t h a t i s , b i n a r y o u t p u t f r o m t h e a s s e m b l e r ) .
-V
is t h e file f o r m e s s a g e s . ( U n l e s s y o u s p e c i f y - V , m e s s a g e s g o to t h e
terminal.)
-L
is t h e l i s t i n g file.
-C
s p e c i f i e s o p t i o n s to t h e a s s e m b l e r .
-H
is a h e a d e r file w h i c h c a n b e r e a d a s if i n s e r t e d at t h e f r o n t o f t h e
s o u r c e (like I N C L U D E in t h e s o u r c e i t s e l f ) .
-I
-E
p r o d u c e a s y m b o l t a b l e d u m p a s p a r t o f t h e o b j e c t file.
p r o d u c e a c r o s s - r e f e r e n c e file.
W<size>
s e t w o r k s p a c e to < s i z e > .
Examples:
86
A S S E M p r o g . a s m TO p r o g . o b j - h s l i b - 1 p r o g - l i s t
a s s e m b l e s t h e s a m e p r o g r a m to t h e s a m e o u t p u t , b u t i n c l u d e s t h e file " s l i b " in
t h e a s s e m b l y , a n d p l a c e s a n a s s e m b l y listing in t h e file " p r o g - l i s t " .
A S S E M f o o . a s m -o f o o . o b j o p t w 8 0 0 0
a s s e m b l e s a very s m a l l p r o g r a m .
DOWNLOAD
Template:
DOWNLOAD
Purpose:
T o d o w n l o a d p r o g r a m s to t h e A m i g a .
"FROM/A,TO/A"
Specification:
The c o m m a n d D O W N L O A D downloads programs written on another comp u t e r (for e x a m p l e , a S u n ) to t h e A m i g a .
T o u s e D O W N L O A D , y o u m u s t h a v e a B i l l B o a r d . T h e n , to d o w n l o a d y o u r
l i n k e d l o a d file f r o m t h e S u n to t h e A m i g a , y o u t y p e o n t h e S u n :
b i n l o a d -p &
(this o n l y n e e d s to b e d o n e o n c e ) , t h e n t y p e o n t h e A m i g a :
download < s u n filename> <amiga filename>
(Before y o u boot your S u n , y o u m u s t m a k e sure that both the BillBoard a n d
A m i g a are already on a n d powered u p , otherwise they won't be recognized by
the Sun.) The
<sun
filename>
.Id.
Once
Developer's
Manual
i n t h i s b o o k d e s c r i b e s in d e t a i l
h o w t o d o w n l o a d p r o g r a m s f r o m a n I B M P C to A m i g a , f r o m t h e S u n t o t h e
A m i g a , a n d e v e n g i v e s s o m e h i n t s o n h o w to d o w n l o a d f r o m u n s u p p o r t e d
computers.
AMIGADOS COMMANDS
87
Examples:
b l n l o a d -p &
download test.ld test.
or
d o w n l o a d /usr7fred/DOS/test.ld t e s t
then type the following:
test
These commands
filenames.
download
the
specified
Sun
filenames
to
the
Amiga
READ
Template:
READ "TO/A,SERIAL/S"
Purpose:
R E A D r e a d s d a t a f r o m t h e p a r a l l e l p o r t or serial l i n e a n d s t o r e s it in
a file.
Specification:
The command
R E A D l i s t e n s t o t h e parallel p o r t a n d e x p e c t s a s t r e a m
of
h e x a d e c i m a l c h a r a c t e r s . If y o u p r e s s t h e S E R I A L s w i t c h , R E A D l i s t e n s , i n s t e a d ,
t o t h e serial l i n e . E a c h h e x p a i r is s t o r e d a s a b y t e in m e m o r y . R E A D r e c o g n i z e s
Q as the h e x stream terminator. R E A D also recognizes the A S C I I digits 0 - 9 a n d
t h e capital l e t t e r s A t h r o u g h F . R E A D i g n o r e s s p a c e s , n e w l i n e s , a n d t a b s . Y o u
m u s t s e n d a n A S C I I h e x digit f o r e v e r y n i b b l e , a n d y o u m u s t h a v e a n e v e n
n u m b e r o f n i b b l e s . W h e n t h e s t r e a m is c o m p l e t e , R E A D w r i t e s t h e b y t e s f r o m
m e m o r y to t h e d i s k file y o u s p e c i f i e d .
N o t e : Y o u c a n u s e t h i s c o m m a n d to t r a n s f e r b i n a r y or t e x t f i l e s .
W A R N I N G 1 : B e c a r e f u l w h e n R E A D i n g to t h e s a m e file t w i c e . R E A D
overwrites the original contents the s e c o n d time.
W A R N I N G 2 : Y o u m a y l o s e c h a r a c t e r s if y o u u s e h i g h b a u d r a t e s w i t h
t h e serial c o n n e c t i o n .
Examples:
R E A D TO d f O : n e w
88
Utilities
<>
COPY
DELETE
DIR
ED
EDIT
FILENOTE
JOIN
LIST
MAKEDIR
PROTECT
RENAME
SEARCH
SORT
TYPE
CLI
Control
BREAK
c o m m e n t character.
direct c o m m a n d input a n d output respectively.
c o p i e s o n e file t o a n o t h e r or c o p i e s all t h e files f r o m o n e
directory to another.
d e l e t e s u p to 10 files o r d i r e c t o r i e s .
s h o w s f i l e n a m e s in a d i r e c t o r y .
e n t e r s a s c r e e n e d i t o r f o r text files.
e n t e r s a line b y line e d i t o r .
a t t a c h e s a n o t e w i t h a m a x i m u m of 8 0 c h a r a c t e r s t o a s p e c i f i e d
file.
c o n c a t e n a t e s u p to 15 files t o f o r m a n e w file.
e x a m i n e s a n d d i s p l a y s d e t a i l e d i n f o r m a t i o n a b o u t a file o r
directory.
creates a directory with a specified n a m e ,
s e t s a file's p r o t e c t i o n s t a t u s ,
r e n a m e s a file or d i r e c t o r y .
l o o k s for a s p e c i f i e d text s t r i n g in all t h e files of a d i r e c t o r y ,
sorts s i m p l e files.
t y p e s a file to t h e s c r e e n t h a t y o u c a n o p t i o n a l l y s p e c i f y a s
text o r h e x .
s e t s a t t e n t i o n flags in a g i v e n p r o c e s s .
CD
ENDCLI
NEWCLI
PROMPT
RUN
e x e c u t e s c o m m a n d s as b a c k g r o u n d p r o c e s s e s .
STACK
d i s p l a y s or s e t s t h e s t a c k size f o r c o m m a n d s .
AMIGADOS COMMANDS
89
STATUS
displays information
existence.
WHY
Command
Sequence
Control
ECHO
d i s p l a y s t h e m e s s a g e s p e c i f i e d in a c o m m a n d a r g u m e n t .
EXECUTE
e x e c u t e s a file o f c o m m a n d s .
FAILAT
in
fails a c o m m a n d s e q u e n c e if a p r o g r a m r e t u r n s a n e r r o r c o d e
g r e a t e r t h a n or e q u a l t o t h i s n u m b e r .
IF
LAB
QUIT
SKIP
j u m p s f o r w a r d to L A B in a c o m m a n d s e q u e n c e ( s e e L A B ) .
WAIT
w a i t s f o r , or u n t i l , a s p e c i f i e d t i m e .
System
and Storage
ASSIGN
Management
a s s i g n s a logical d e v i c e n a m e to a filing s y s t e m d i r e c t o r y .
DATE
DISKCOPY
FAULT
time.
d i s p l a y s m e s s a g e s c o r r e s p o n d i n g to s u p p l i e d f a u l t o r e r r o r
codes.
FORMAT
f o r m a t s a n d initializes a n e w 3V2-inch f l o p p y d i s k .
INFO
g i v e s i n f o r m a t i o n a b o u t t h e filing s y s t e m .
INSTALL
RELABEL
c h a n g e s t h e v o l u m e n a m e of a disk.
Developer's Commands
Development
ALINK
System
l i n k s s e c t i o n s o f c o d e i n t o a file f o r e x e c u t i o n ( s e e J O I N ) .
ASSEM
DOWNLOAD
d o w n l o a d s p r o g r a m s to t h e A m i g a .
READ
and
Chapter 3
T h i s c h a p t e r d e s c r i b e s h o w to u s e t h e s c r e e n e d i t o r E D . Y o u c a n u s e t h i s
p r o g r a m t o alter or c r e a t e text files.
3.1
3.2
3.2.1
3.2.2
3.2.3
3.2.4
3.2.5
3.3
3.3.1
3.3.2
3.3.3
3.3.4
3.3.5
3.3.6
Quick
Introducing E D
Immediate Commands
Cursor Control
Inserting Text
Deleting Text
Scrolling
Repeating Commands
Extended Commands
Program Control
Block Control
M o v i n g the Current Cursor Position
Searching and Exchanging
Altering Text
Repeating Commands
Reference Card
3.1 Introducing ED
Y o u c a n u s e t h e e d i t o r E D to c r e a t e a n e w file or to alter a n existing o n e . Y o u disp l a y text o n t h e s c r e e n , a n d y o u c a n scroll it vertically or horizontally, as r e q u i r e d .
E D accepts the following template:
ED "FROM/A,SIZE/K"
F o r e x a m p l e , to call E D , y o u t y p e
ED fred
91
ED fred SIZE 4 5 0 0 0
T h e initial size is b a s e d o n t h e size o f t h e file y o u e d i t , w i t h a m i n i m u m o f
40,000 bytes.
N o t e : Y o u c a n n o t e d i t e v e r y k i n d o f file w i t h E D . F o r e x a m p l e , E D d o e s n o t
a c c e p t s o u r c e files c o n t a i n i n g b i n a r y c o d e . T o e d i t files s u c h a s t h e s e , y o u
should use the editor EDIT.
W A R N I N G : E D a l w a y s a p p e n d s a l i n e f e e d e v e n if t h e file d o e s n o t e n d
with one.
W h e n E D is r u n n i n g , t h e b o t t o m l i n e o f t h e s c r e e n is a m e s s a g e a r e a a n d
c o m m a n d line. Error m e s s a g e s appear here a n d remain until y o u give a n o t h e r
ED command.
E D c o m m a n d s fall i n t o t w o c a t e g o r i e s :
immediate commands
extended commands
You use immediate
commands
extended
c o m m a n d s i n e x t e n d e d m o d e . E D is a l r e a d y in i m m e d i a t e m o d e w h e n
you
after
E D h a s e x e c u t e d t h e c o m m a n d l i n e , it r e t u r n s a u t o m a t i c a l l y t o
immediate
mode.
In i m m e d i a t e m o d e , E D executes c o m m a n d s right a w a y . Y o u specify
an
ED
92
E D a t t e m p t s to k e e p t h e s c r e e n u p t o d a t e . H o w e v e r , if y o u e n t e r a f u r t h e r
c o m m a n d w h i l e it is a t t e m p t i n g to r e d r a w t h e d i s p l a y , E D e x e c u t e s t h e c o m m a n d a t o n c e a n d u p d a t e s t h e d i s p l a y w h e n t h e r e is t i m e . T h e c u r r e n t l i n e is
a l w a y s d i s p l a y e d first a n d is a l w a y s u p to d a t e .
scrolls
v e r t i c a l l y a l i n e at a t i m e a n d h o r i z o n t a l l y t e n c h a r a c t e r s at a t i m e . Y o u c a n n o t
m o v e t h e c u r s o r off t h e t o p o r b o t t o m of t h e file, or off t h e left h a n d e d g e o f
t h e text.
C T R L - ] , t h a t i s , C T R L a n d t h e s q u a r e c l o s i n g b r a c k e t " ] " t a k e s t h e c u r s o r to
t h e r i g h t h a n d e d g e of t h e c u r r e n t l i n e u n l e s s t h e c u r s o r is a l r e a d y t h e r e . W h e n
t h e c u r s o r is a l r e a d y at t h e r i g h t h a n d e d g e , C T R L - ] m o v e s it b a c k to t h e left
h a n d e d g e o f t h e l i n e . T h e t e x t is s c r o l l e d h o r i z o n t a l l y , if r e q u i r e d . I n a s i m i l a r
f a s h i o n , C T R L - E p l a c e s t h e c u r s o r a t t h e start o f t h e first l i n e o n t h e s c r e e n
u n l e s s t h e c u r s o r is a l r e a d y t h e r e . If t h e c u r s o r is a l r e a d y t h e r e , C T R L - E p l a c e s
it a t t h e e n d o f t h e last l i n e o n t h e s c r e e n .
C T R L - T t a k e s t h e c u r s o r to t h e start of t h e n e x t w o r d . C T R L - R t a k e s t h e
c u r s o r t o t h e s p a c e f o l l o w i n g t h e p r e v i o u s w o r d . I n t h e s e t w o c a s e s , t h e t e x t is
s c r o l l e d v e r t i c a l l y or h o r i z o n t a l l y , as r e q u i r e d .
T h e T A B k e y m o v e s t h e c u r s o r t o t h e n e x t t a b p o s i t i o n , w h i c h is a m u l t i p l e
o f t h e t a b s e t t i n g (initially 3 ) . It d o e s N O T i n s e r t T A B c h a r a c t e r s i n t o t h e file.
mode,
E D is a l s o in I N S E R T m o d e
so a n y
ordinary
c h a r a c t e r s y o u t y p e will b e i n s e r t e d at t h e c u r r e n t c u r s o r p o s i t i o n . E D h a s n o
type-over mode.
To replace a w o r d or line, y o u m u s t
delete the
desired
93
c o n t e n t s a n d i n s e r t n e w i n f o r m a t i o n in its p l a c e . A n y l e t t e r t h a t y o u t y p e i n
i m m e d i a t e m o d e a p p e a r s a t t h e c u r r e n t c u r s o r p o s i t i o n u n l e s s t h e l i n e is t o o
l o n g ( t h e r e is a m a x i m u m o f 2 5 5 c h a r a c t e r s in a l i n e ) . If y o u t r y t o m a k e a l i n e
l o n g e r t h a n the m a x i m u m limit, E D refuses to a d d a n o t h e r character
and
this,
w h e n e v e r y o u type a line that exceeds that margin, E D e n d s the line before the
last w o r d a n d m o v e s t h e w o r d a n d t h e c u r s o r d o w n o n t o a n e w l i n e . T h i s is
c a l l e d " w o r d w r a p . " ( N o t e t h a t if y o u h a v e a l i n e w i t h n o s p a c e s , E D w o n ' t
k n o w w h e r e to break the " w o r d " a n d the automatic m a r g i n c a n n o t
work
p r o p e r l y . ) I n d e t a i l , if y o u t y p e a c h a r a c t e r a n d t h e c u r s o r is at t h e e n d o f t h e
line a n d at the right margin position, t h e n E D automatically generates a n e w
line. Unless the character you typed w a s a space, E D m o v e s d o w n the half
c o m p l e t e d w o r d at t h e e n d o f t h e l i n e t o t h e n e w l y g e n e r a t e d l i n e . H o w e v e r , if
y o u i n s e r t s o m e t e x t w h e n t h e c u r s o r is N O T at t h e e n d o f a l i n e ( t h a t i s , w i t h
text already to the right of the cursor), t h e n setting a right m a r g i n d o e s n o t
w o r k . Initially, t h e r i g h t m a r g i n is s e t u p at c o l u m n 7 9 . Y o u c a n t u r n off, o r
" d i s a b l e " , the right m a r g i n w i t h the E X c o m m a n d . (For further details
on
94
t h e r i g h t ( a n d it m o v e s t h e c u r s o r e v e n if t h e r e is n o c a s e t o flip). S o t h a t , a f t e r
y o u h a v e c h a n g e d t h e c a s e of a letter w i t h C T R L - F , t h e c u r s o r m o v e s r i g h t t o
p o i n t at t h e n e x t c h a r a c t e r . If t h e n e x t c h a r a c t e r is a l e t t e r , y o u c a n p r e s s
C T R L - F a g a i n t o c h a n g e its c a s e ; y o u c a n t h e n r e p e a t t h e c o m m a n d u n t i l y o u
h a v e c h a n g e d all t h e l e t t e r s o n t h e l i n e . ( N o t e t h a t if y o u c o n t i n u e t o p r e s s
C T R L - F a f t e r t h e last letter o n t h e l i n e , t h e c u r s o r k e e p s m o v i n g r i g h t e v e n
t h o u g h t h e r e is n o t h i n g left t o c h a n g e . ) F o r e x a m p l e , if y o u h a d t h e l i n e
The Walrus and the Carpenter were walking hand in hand
a n d y o u k e p t C T R L - F p r e s s e d d o w n , t h e line w o u l d b e c o m e
the walrus and the carpenter were walking hand in hand
O n the other h a n d , the following line:
IF <file> < =
becomes
if < F I L E > < =
95
3.2.4 Scrolling
B e s i d e s v e r t i c a l l y s c r o l l i n g o n e l i n e at a t i m e b y m o v i n g t h e c u r s o r t o t h e e d g e
o f t h e s c r e e n , y o u c a n v e r t i c a l l y scroll t h e t e x t 12 l i n e s at a t i m e w i t h t h e c o n t r o l
keys CTRL-U and CTRL-D.
C T R L - D m o v e s t h e c u r s o r to p r e v i o u s l i n e s , w h i l e s c r o l l i n g t h e t e x t d o w n ;
C T R L - U scrolls t h e t e x t u p a n d m o v e s t h e c u r s o r to l i n e s f u r t h e r o n in t h e file.
C T R L - V r e f r e s h e s t h e e n t i r e s c r e e n , w h i c h is u s e f u l if a n o t h e r
program
command
l i n e , p r e s s e i t h e r E S C or R E T U R N . If y o u p r e s s E S C , t h e e d i t o r r e m a i n s i n
e x t e n d e d m o d e a f t e r e x e c u t i n g t h e c o m m a n d l i n e . O n t h e o t h e r h a n d , if y o u
p r e s s R E T U R N , it r e v e r t s t o i m m e d i a t e m o d e . T o l e a v e t h e c o m m a n d
line
96
e m p t y , j u s t p r e s s R E T U R N a f t e r p r e s s i n g E S C t o g o b a c k to i m m e d i a t e m o d e .
In this case, E D returns to immediate c o m m a n d m o d e .
E x t e n d e d c o m m a n d s c o n s i s t of o n e or t w o l e t t e r s , w i t h u p p e r a n d l o w e r c a s e
considered the s a m e . Y o u can give multiple c o m m a n d s on the s a m e c o m m a n d
line b y separating t h e m with a semicolon. C o m m a n d s are s o m e t i m e s followed
b y a n a r g u m e n t , s u c h as a n u m b e r o r a s t r i n g . A s t r i n g is a s e q u e n c e of l e t t e r s
i n t r o d u c e d a n d t e r m i n a t e d b y a d e l i m i t e r , w h i c h is a n y c h a r a c t e r e x c e p t l e t t e r s ,
n u m b e r s , space, semicolon, or brackets. T h u s , valid strings m i g h t b e :
/happy/
!23 feet!
.Hello!: " W
Most immediate commands have a corresponding extended version.
See
t h e T a b l e o f E x t e n d e d C o m m a n d s at t h e e n d o f this c h a p t e r f o r a c o m p l e t e
list.
SA !:doc/savedtext!
or
SA
97
S A is p a r t i c u l a r l y u s e f u l in g e o g r a p h i c a l a r e a s s u b j e c t t o p o w e r f a i l u r e or
surge.
H i n t : S A f o l l o w e d b y Q is e q u i v a l e n t to t h e X c o m m a n d .
If y o u m a k e a n y a l t e r a t i o n s b e t w e e n t h e S A a n d t h e Q c o m m a n d s ,
the
or
i n s e r t i n g a l i n e ) . E D a l s o r e p l a c e s t h e c o p y w h e n it p e r f o r m s a n y s c r o l l i n g
e i t h e r v e r t i c a l l y or h o r i z o n t a l l y . T h e U c o m m a n d d i s c a r d s t h e c h a n g e d c o p y
a n d u s e s t h e o l d v e r s i o n o f t h e c u r r e n t line i n s t e a d .
98
c o m m a n d s . T o d o t h i s , m o v e t h e c u r s o r to a n y w h e r e o n t h e first l i n e t h a t
y o u w a n t in t h e b l o c k a n d g i v e t h e B S c o m m a n d . T h e n , m o v e t h e c u r s o r t o t h e
last line that y o u w a n t in the block, using the cursor control c o m m a n d s or a
s e a r c h c o m m a n d , a n d g i v e t h e B E c o m m a n d to m a r k t h e e n d o f t h e b l o c k .
N o t e : O n c e y o u h a v e d e f i n e d a b l o c k w i t h B S a n d B E , if y o u m a k e A N Y
c h a n g e t o t h e t e x t , t h e start a n d e n d o f t h e b l o c k b e c o m e u n d e f i n e d o n c e m o r e .
T h e o n l y e x c e p t i o n t o t h i s is if y o u u s e I B ( I n s e r t B l o c k ) .
T o i d e n t i f y o n e l i n e a s t h e c u r r e n t b l o c k , m o v e to t h e l i n e y o u w a n t , p r e s s
E S C , and type:
BS;BE
T h e current line t h e n b e c o m e s the current block.
N o t e : Y o u c a n n o t start or f i n i s h a b l o c k i n t h e m i d d l e o f a l i n e . T o d o t h i s ,
y o u m u s t first split t h e l i n e b y p r e s s i n g R E T U R N .
O n c e y o u h a v e i d e n t i f i e d a b l o c k , y o u c a n m o v e a c o p y o f it i n t o a n o t h e r p a r t
o f t h e file w i t h t h e I B ( I n s e r t B l o c k ) c o m m a n d . W h e n y o u g i v e t h e I B c o m m a n d , E D inserts a c o p y of the block immediately after the current line. Y o u
c a n i n s e r t m o r e t h a n o n e c o p y o f t h e b l o c k , a s it r e m a i n s d e f i n e d u n t i l y o u
c h a n g e the text, or delete the block.
T o delete a block, y o u u s e the D B (Delete Block) c o m m a n d . D B deletes the
block of text you defined with the B S and BE c o m m a n d s . H o w e v e r , w h e n y o u
h a v e d e l e t e d t h e b l o c k , t h e b l o c k start a n d e n d v a l u e s b e c o m e u n d e f i n e d . T h i s
m e a n s t h a t y o u C A N N O T d e l e t e a b l o c k a n d t h e n i n s e r t a c o p y o f it ( D B
followed b y IB); however, you can insert a copy of the block and then delete
t h e b l o c k (IB f o l l o w e d b y D B ) .
Y o u c a n a l s o u s e b l o c k m a r k s to r e m e m b e r a p l a c e in a file. T h e S B ( S h o w
B l o c k ) c o m m a n d r e s e t s t h e s c r e e n w i n d o w o n t h e file s o t h a t t h e first l i n e i n
t h e b l o c k is a t t h e t o p o f t h e s c r e e n .
T o w r i t e a b l o c k to a n o t h e r file, y o u u s e t h e W B c o m m a n d ( W r i t e B l o c k ) .
This c o m m a n d takes a string that represents a filename. For example,
WB !:doc/example!
w r i t e s t h e c o n t e n t s o f t h e b l o c k t o t h e file " e x a m p l e " in t h e d i r e c t o r y " : d o c " .
R e m e m b e r : if y o u u s e t h e f i l e n a m e - d i v i d e r s l a s h (/) t o s e p a r a t e d i r e c t o r i e s a n d
f i l e s , y o u s h o u l d n o t u s e s l a s h a s a d e l i m i t e r . E D t h e n c r e a t e s a file w i t h t h e
n a m e t h a t y o u s p e c i f i e d , p o s s i b l y d e s t r o y i n g a p r e v i o u s file w i t h t h a t n a m e ,
a n d finally w r i t e s t h e b u f f e r to it.
T o i n s e r t a file i n t o t h e c u r r e n t file, y o u u s e t h e I F c o m m a n d ( I n s e r t F i l e ) . E D
r e a d s i n t o m e m o r y t h e file w i t h t h e n a m e y o u g a v e as t h e a r g u m e n t s t r i n g t o
IF, at the point immediately following the current line. For e x a m p l e ,
99
IF !:doc/example!
i n s e r t s t h e file : d o c / e x a m p l e i n t o t h e c u r r e n t file b e g i n n i n g i m m e d i a t e l y a f t e r
the current line.
the cursor
to t h e five h u n d r e d
a n d t h i r d l i n e in t h e file. T h e
c o m m a n d is a q u i c k w a y of r e a c h i n g a k n o w n p o s i t i o n i n y o u r file. Y o u c a n , f o r
i n s t a n c e , m o v e to t h e c o r r e c t l i n e in y o u r file b y g i v i n g a r e p e a t c o u n t t o t h e N
c o m m a n d , b u t it is m u c h s l o w e r .
100
AMIGADOS USER'S M A N U A L
E /wombat/zebra/
w o u l d c h a n g e t h e n e x t o c c u r r e n c e of t h e text " w o m b a t " to " z e b r a " . T h e e d i t o r
s t a r t s s e a r c h i n g f o r t h e first s t r i n g at t h e c u r r e n t c u r s o r p o s i t i o n a n d c o n t i n u e s
t h r o u g h t h e file. A f t e r t h e e x c h a n g e is c o m p l e t e d , t h e c u r s o r m o v e s to t h e e n d
of t h e e x c h a n g e d t e x t .
Y o u can specify e m p t y strings by typing two delimiters with n o t h i n g b e t w e e n
t h e m . If t h e first, o r " s e a r c h " , s t r i n g is e m p t y , t h e e d i t o r i n s e r t s t h e s e c o n d
s t r i n g at t h e c u r r e n t c u r s o r p o s i t i o n . If t h e s e c o n d s t r i n g is e m p t y , t h e n e x t
occurrence of the search string is e x c h a n g e d for n o t h i n g (that is, the search
s t r i n g is d e l e t e d ) .
N o t e : E D i g n o r e s m a r g i n s e t t i n g s w h i l e y o u a r e e x c h a n g i n g text.
T h e E Q c o m m a n d ( E x c h a n g e a n d Q u e r y ) is a v a r i a n t o n t h e E c o m m a n d .
W h e n y o u u s e E Q , E D asks you w h e t h e r y o u w a n t the exchange to take place.
T h i s is u s e f u l w h e n y o u w a n t t h e e x c h a n g e t o t a k e p l a c e in s o m e c i r c u m s t a n c e s , b u t n o t in o t h e r s . F o r e x a m p l e , a f t e r t y p i n g
EQ /wombat/zebra/
the following message
Exchange?
a p p e a r s o n t h e c o m m a n d l i n e . If y o u r e s p o n d w i t h a n N , t h e n t h e c u r s o r
m o v e s p a s t t h e s e a r c h s t r i n g ; o t h e r w i s e , if y o u t y p e Y , t h e c h a n g e t a k e s p l a c e
a s n o r m a l . Y o u u s u a l l y o n l y g i v e E Q in r e p e a t e d g r o u p s .
T h e search a n d exchange c o m m a n d s usually m a k e a distinction
between
u p p e r a n d l o w e r c a s e w h i l e m a k i n g t h e s e a r c h . T o tell all s u b s e q u e n t s e a r c h e s
n o t to m a k e a n y d i s t i n c t i o n b e t w e e n u p p e r a n d l o w e r c a s e , y o u u s e t h e U C
c o m m a n d . O n c e y o u h a v e given U C , the search string " w o m b a t "
"Wombat",
"WOMBAT",
"WoMbAt",
a n d so on. To have E D
matches
distinguish
101
inserts the string " I n s e r t this B E F O R E the current l i n e " as a n e w , separate line
Before the line containing the cursor. Y o u u s e the A c o m m a n d (insert After) in
the s a m e w a y except that E D inserts the n e w line after the current line. T h a t is,
A /Insert this A F T E R the current line/
i n s e r t s t h e s t r i n g " I n s e r t t h i s A F T E R t h e c u r r e n t l i n e " as a n e w l i n e A f t e r t h e
line containing the cursor.
T o split t h e c u r r e n t l i n e at t h e c u r s o r p o s i t i o n , y o u u s e t h e S c o m m a n d . S i n
e x t e n d e d m o d e is j u s t like p r e s s i n g R E T U R N in i m m e d i a t e m o d e (see Section
3.2.2 for further details on splitting lines).
T h e J c o m m a n d j o i n s t h e n e x t l i n e to t h e e n d o f t h e c u r r e n t o n e .
T h e D c o m m a n d d e l e t e s t h e c u r r e n t line i n t h e s a m e w a y a s C T R L - B in
immediate m o d e . T h e D C c o m m a n d deletes the character a b o v e the cursor in
t h e s a m e w a y as D E L .
command
commands
inserts three b l a n k lines (copies of the null string) after every line c o n t a i n i n g
" b a n d e r s n a t c h " . Notice that this c o m m a n d line only w o r k s from the cursor to
t h e e n d o f t h e file. T o a p p l y t h e c o m m a n d t o e v e r y l i n e i n t h e file, y o u s h o u l d
first m o v e t o t h e t o p o f t h e file.
N o t e t h a t s o m e c o m m a n d s are p o s s i b l e , b u t silly. F o r e x a m p l e ,
102
RP SR 6 0
s e t s t h e r i g h t m a r g i n t o 6 0 ad infinitum.
H o w e v e r , to interrupt a n y s e q u e n c e of
the
command sequence.
Action
BACKSPACE
D e l e t e c h a r a c t e r to left o f c u r s o r
DEL
D e l e t e c h a r a c t e r at c u r s o r
ESC
RETURN
Split l i n e at c u r s o r a n d c r e a t e a n e w l i n e
TAB
<up-arrow>
M o v e cursor u p
<down-arrow>
M o v e cursor d o w n
<left-arrow>
M o v e c u r s o r left
<right-arrow>
M o v e cursor right
Immediate Commands
Command
Action
CTRL-A
Insert line
CTRL-B
Delete line
CTRL-D
Scroll text d o w n
CTRL-E
M o v e to t o p or b o t t o m o f s c r e e n
CTRL-F
Flip case
CTRL-G
R e p e a t last e x t e n d e d c o m m a n d l i n e
CTRL-H
D e l e t e c h a r a c t e r left o f c u r s o r ( B A C K S P A C E )
CTRL-I
CTRL-M
RETURN
CTRL-O
CTRL-R
C u r s o r to e n d of previous w o r d
CTRL-T
C u r s o r t o start o f n e x t w o r d
CTRL-U
S c r o l l text u p
CTRL-V
Verify screen
CTRL-Y
D e l e t e to e n d o f l i n e
CTRL-[
CTRL-]
C u r s o r t o e n d or start of line
103
Extended Commands
T h i s is a full list o f e x t e n d e d c o m m a n d s i n c l u d i n g t h o s e t h a t a r e
merely
e x t e n d e d v e r s i o n s o f i m m e d i a t e c o m m a n d s . I n t h e list, I si i n d i c a t e s a s t r i n g ,
Isltl i n d i c a t e s t w o e x c h a n g e s t r i n g s , a n d " n " i n d i c a t e s a n u m b e r .
Command
Action
A/s/
M o v e to b o t t o m of file
BE
B l o c k e n d at c u r s o r
B F Is/
Backward find
BS
B l o c k start at c u r s o r
CE
M o v e c u r s o r to e n d o f l i n e
CL
M o v e c u r s o r o n e p o s i t i o n left
CR
CS
M o v e c u r s o r to start of l i n e
DB
Delete block
DC
D e l e t e c h a r a c t e r at c u r s o r
E /s/t/
E Q /s/t/
EX
F/s/
Find string
I Is/
IB
Insert c o p y of block
"s"
I F Is/
I n s e r t file
J
LC
"s"
M n
M o v e to l i n e n u m b e r " n "
M o v e to start o f n e x t l i n e
M o v e t o start o f p r e v i o u s l i n e
Q
RP
Split l i n e at c u r s o r
SA
S a v e t e x t t o file
SB
S h o w block on screen
SH
Show information
SL n
S e t left m a r g i n
SRn
104
Command
Action
ST n
M o v e to t o p o f file
U n d o c h a n g e s o n current line
UC
E q u a t e U / C a n d 1/c in s e a r c h e s
W B I si
Exit, w r i t i n g t e x t i n t o m e m o r y
Chapter 4
Introducing EDIT
Calling EDIT
Using EDIT C o m m a n d s
The Current Line
Line Numbers
Selecting a Current Line
Qualifiers
M a k i n g C h a n g e s to t h e C u r r e n t L i n e
Deleting Whole Lines
Inserting N e w Lines
C o m m a n d Repetition
Leaving EDIT
A C o m b i n e d E x a m p l e : P u l l i n g It All T o g e t h e r
A C o m p l e t e S p e c i f i c a t i o n of E D I T
C o m m a n d Syntax
Command Names
Arguments
Strings
Multiple Strings
Qualified Strings
Search Expressions
Numbers
Switch Values
Command Groups
C o m m a n d Repetition
Processing EDIT
106
4.2.2.1
Prompts
4.2.2.2
4.2.2.3
Line Numbers
4.2.2.4
Qualified Strings
4.2.2.5
Output Processing
4.2.2.6
End-of-File Handling
4.2.3
Functional G r o u p i n g s of E D I T C o m m a n d s
4.2.3.1
Selection of a C u r r e n t Line
4.2.3.2
4.2.4
Line Windows
4.2.4.1
4.2.4.2
4.2.5
4.2.5.1
4.2.5.2
T h e Null String
4.2.5.3
Pointing Variant
4.2.5.4
4.2.6
4.2.6.1
4.2.7
4.2.8
C o n t r o l o f C o m m a n d , I n p u t , a n d O u t p u t Files
4.2.8.1
C o m m a n d Files
4.2.8.2
Input Files
4.2.8.3
O u t p u t Files
4.2.9
Loops
4.2.10
Global Operations
4.2.10.1
4.2.10.2
4.2.10.3
4.2.11
4.2.12
4.2.13
4.2.14
Miscellaneous C o m m a n d s
4.2.15
A b a n d o n i n g Interactive Editing
the
c o n t r o l o f e d i t i n g c o m m a n d s . E D I T m o v e s t h r o u g h t h e i n p u t , o r s o u r c e file,
p a s s i n g e a c h l i n e (after a n y p o s s i b l e a l t e r a t i o n s ) t o a s e q u e n t i a l o u t p u t file, t h e
d e s t i n a t i o n file. A n E D I T r u n , t h e r e f o r e , m a k e s a c o p y o f t h e s o u r c e file t h a t
contains any changes that y o u requested with the editing c o m m a n d s .
107
A l t h o u g h E D I T u s u a l l y p r o c e s s e s t h e s o u r c e file in a f o r w a r d
sequential
m a n n e r , it h a s t h e c a p a b i l i t y t o m o v e b a c k w a r d a l i m i t e d n u m b e r o f l i n e s .
T h i s is p o s s i b l e b e c a u s e E D I T d o e s n ' t w r i t e t h e l i n e s t h a t h a v e b e e n p a s s e d t o
t h e d e s t i n a t i o n file i m m e d i a t e l y , b u t h o l d s t h e m i n s t e a d in a n o u t p u t q u e u e .
T h e size of t h i s q u e u e d e p e n d s o n t h e a m o u n t o f m e m o r y a v a i l a b l e . If y o u
w a n t t o h o l d m o r e i n f o r m a t i o n in m e m o r y , y o u c a n select t h e E D I T o p t i o n , O P T ,
d e s c r i b e d in t h e n e x t s e c t i o n , to i n c r e a s e t h e a m o u n t .
Y o u can m a k e m o r e than one pass through the text.
T h e E D I T c o m m a n d s let y o u
a) c h a n g e p a r t s o f t h e s o u r c e ,
b) o u t p u t parts of t h e source to other destinations, a n d
c) i n s e r t m a t e r i a l f r o m o t h e r s o u r c e s .
the
k e y w o r d . A r g u m e n t s w i t h j u s t a f o l l o w i n g /K ( s u c h a s W I T H , V E R , a n d O P T )
are optional, but y o u m u s t type the k e y w o r d to specify t h e m .
Arguments
108
T h e a r g u m e n t F R O M r e p r e s e n t s t h e s o u r c e file t h a t y o u w a n t to e d i t . T h e
a r g u m e n t m u s t a p p e a r , b u t t h e k e y w o r d itself is o p t i o n a l . ( T h a t i s , A m i g a D O S
a c c e p t s t h e F R O M file b y its p o s i t i o n . ) It d o e s n o t r e q u i r e y o u to t y p e t h e
k e y w o r d F R O M as well.
T h e T O file r e p r e s e n t s t h e d e s t i n a t i o n file. T h i s is t h e file w h e r e E D I T s e n d s
t h e o u t p u t i n c l u d i n g t h e e d i t i n g c h a n g e s . If y o u o m i t t h e T O a r g u m e n t , E D I T
u s e s a t e m p o r a r y file t h a t it r e n a m e s a s t h e F R O M file w h e n e d i t i n g is c o m p l e t e . If y o u g i v e t h e E D I T c o m m a n d S T O P , t h i s r e n a m i n g d o e s n o t t a k e p l a c e ,
a n d t h e o r i g i n a l F R O M file is u n t o u c h e d .
T h e W I T H k e y w o r d r e p r e s e n t s t h e file c o n t a i n i n g t h e e d i t i n g c o m m a n d s . If
you omit the W I T H argument, EDIT reads from the terminal.
T h e V E R k e y w o r d r e p r e s e n t s t h e file w h e r e E D I T s e n d s e r r o r m e s s a g e s a n d
l i n e v e r i f i c a t i o n s . If y o u o m i t t h e V E R a r g u m e n t , E D I T u s e s t h e t e r m i n a l .
Y o u c a n u s e t h e O P T k e y w o r d t o s p e c i f y o p t i o n s to E D I T . V a l i d o p t i o n s a r e
P < n > , w h i c h s e t s t h e n u m b e r o f p r e v i o u s l i n e s available t o t h e i n t e g e r
a n d W < n > , w h i c h s e t s t h e m a x i m u m l i n e l e n g t h h a n d l e d to < n >
<n>,
characters.
memory.
commands
many
syntax
a n d o f all c o m m a n d s a p p e a r s i n S e c t i o n 4 . 2 , " A C o m p l e t e S p e c i f i c a t i o n
EDIT."
of
109
4.1.2.1
The Current
Line
A s E D I T reads lines from the source and writes t h e m to the destination, the
l i n e t h a t it h a s " i n its h a n d " at a n y t i m e is c a l l e d t h e c u r r e n t l i n e . E D I T m a k e s
all t h e t e x t u a l c h a n g e s to t h e c u r r e n t l i n e . E D I T a l w a y s i n s e r t s n e w l i n e s b e f o r e
t h e c u r r e n t l i n e . W h e n y o u first e n t e r E D I T , t h e c u r r e n t l i n e is t h e first l i n e o f
the source.
4 . 1 . 2 . 2 Line
Numbers
command.
E D I T a s s i g n s t h e l i n e n u m b e r s e a c h t i m e y o u e n t e r t h e file. T h e l i n e n u m b e r s ,
therefore, may not be the same w h e n you re-enter.
4.1.2.3
Selecting a Current
Line
T o select a current line in E D I T , y o u can u s e o n e of three m e t h o d s :
a) c o u n t i n g l i n e s ,
b ) s p e c i f y i n g t h e c o n t e x t , or
c) s p e c i f y i n g t h e l i n e n u m b e r .
T h e s e three m e t h o d s are described b e l o w .
By Line
Counting
T h e N a n d P c o m m a n d s a l l o w y o u t o m o v e t o t h e n e x t or p r e v i o u s l i n e s . If
y o u g i v e a n u m b e r b e f o r e t h e N or P c o m m a n d , y o u c a n m o v e t h a t n u m b e r o f
l i n e s f o r w a r d or b a c k w a r d . T o m o v e f o r w a r d to t h e n e x t l i n e , t y p e :
N
For a n y EDIT c o m m a n d , y o u can type either upper or lower case letters.
T o m o v e four lines forward, type:
4N
to m a k e the fourth line from the current line y o u r n e w current line.
T o m o v e back to a line above the current line, type:
P
110
to a Specific
Line
Number
T h e M c o m m a n d a l l o w s y o u to s e l e c t a n e w c u r r e n t l i n e b y s p e c i f y i n g its l i n e
n u m b e r . Y o u type t h e M c o m m a n d a n d t h e desired line n u m b e r . For e x a m p l e ,
t h e c o m m a n d M 4 5 tells E D I T to M o v e t o l i n e 4 5 . If y o u a r e b e y o n d l i n e 4 5 , t h i s
c o m m a n d m o v e s b a c k to it p r o v i d e d it is still i n m a i n m e m o r y .
Y o u c a n c o m b i n e t h e s p e c i f i c line n u m b e r a n d l i n e c o u n t i n g c o m m a n d s . F o r
example,
M12; 3N
T o s e p a r a t e c o n s e c u t i v e c o m m a n d s o n t h e s a m e l i n e , t y p e ; (a s e m i c o l o n ) .
By
Context
( F i n d ) to s e l e c t a c u r r e n t l i n e b y c o n t e x t .
For
example,
F/Jabberwocky/
m e a n s t o f i n d t h e l i n e c o n t a i n i n g " J a b b e r w o c k y " . T h e s e a r c h s t a r t s at t h e
c u r r e n t l i n e a n d m o v e s f o r w a r d t h r o u g h t h e s o u r c e u n t i l t h e r e q u i r e d l i n e is
f o u n d . If E D I T r e a c h e s t h e e n d o f t h e s o u r c e w i t h o u t f i n d i n g a m a t c h i n g l i n e , it
displays the following message:
SOURCE EXHAUSTED
It is a l s o p o s s i b l e to s e a r c h b a c k w a r d b y u s i n g t h e B F c o m m a n d ( B a c k w a r d
Find). For example,
111
is e n c l o s e d
in m a t c h i n g
single
slashes
(/). T h i s
desired
text
spaces
t h e c o m m a n d n a m e a n d t h e first d e l i m i t e r , b u t c o n s i d e r s
spaces
s i n c e it m a t c h e s t h e c o n t e x t e x a c t l y .
For
example,
F/jubjub bird/; U; F
finds the s e c o n d occurrence of a line containing " j u b j u b b i r d " . T h e N c o m m a n d
b e t w e e n t h e t w o F c o m m a n d s is n e c e s s a r y b e c a u s e a n F c o m m a n d
always
s t a r t s b y s e a r c h i n g t h e c u r r e n t l i n e . If y o u o m i t t e d N , t h e s e c o n d F w o u l d f i n d
t h e s a m e l i n e a s t h e first.
4.2.2.4
Qualifiers
T h e b a s i c f o r m of t h e F c o m m a n d d e s c r i b e d a b o v e f i n d s a l i n e t h a t c o n t a i n s
t h e g i v e n s t r i n g a n y w h e r e i n its l e n g t h . T o restrict t h e s e a r c h t o t h e b e g i n n i n g o r
the e n d of lines, y o u can place o n e of t h e letters B or E in front of t h e string. In
this case, y o u m u s t type o n e or m o r e spaces after F. For e x a m p l e ,
F B/slithy toves/
m e a n s Find t h e line Beginning with "slithy t o v e s " , while
F E/bandersnatch/
m e a n s F i n d t h e line E n d i n g w i t h " b a n d e r s n a t c h " . A s w e l l a s p u t t i n g f u r t h e r
conditions o n the context required, the u s e of B or E s p e e d s u p t h e search, as
EDIT only n e e d s to consider part of each line.
B a n d E a s u s e d a b o v e a r e e x a m p l e s o f q u a l i f i e r s , a n d t h e w h o l e a r g u m e n t is
112
a-sitting on a gate
H o w e v e r , E D I T does not find the line:
a-sitting on a gate.
To find an e m p t y line (Precisely n o t h i n g ) , y o u can use an e m p t y string w i t h
the P qualifier, for e x a m p l e ,
F P//
Y o u c a n g i v e m o r e t h a n o n e qualifier i n a n y o r d e r .
4.1.2.5
Making
Changes
to the Current
Line
T h i s s e c t i o n d e s c r i b e s h o w to u s e t h e E , A , a n d B c o m m a n d s t o a l t e r t h e t e x t
on your current line.
Exchanging
strings
T h e E c o m m a n d E x c h a n g e s o n e s t r i n g o f c h a r a c t e r s in t h e l i n e f o r a n o t h e r . F o r
example:
E/Wonderland/Looking Glass/
r e m o v e s t h e s t r i n g " W o n d e r l a n d " f r o m t h e c u r r e n t l i n e , a n d r e p l a c e s it w i t h
" L o o k i n g G l a s s " . N o t e that y o u u s e a single central delimiter to separate the
t w o s t r i n g s . T o d e l e t e p a r t s o f t h e l i n e ( e x c h a n g e text f o r n o t h i n g ) , y o u c a n u s e
a null s e c o n d string, as follows:
E / m o n s t r o u s crow//
T o a d d n e w m a t e r i a l t o t h e l i n e , y o u c a n u s e t h e A or B c o m m a n d s . T h e A
c o m m a n d i n s e r t s its s e c o n d s t r i n g A f t e r t h e first o c c u r r e n c e o f t h e first s t r i n g
113
o n t h e c u r r e n t l i n e . S i m i l a r l y , t h e B c o m m a n d i n s e r t its s e c o n d s t r i n g B e f o r e
t h e first o c c u r r e n c e of t h e first string o n t h e c u r r e n t l i n e . F o r e x a m p l e , if t h e
c u r r e n t line c o n t a i n e d
NO MATCH
S e e S e c t i o n 4 . 1 . 1 , " C a l l i n g E D I T " for details o n t h e v e r i f i c a t i o n file.
4.1.2.6
Deleting
Whole
Lines
T h i s s e c t i o n d e s c r i b e s h o w to r e m o v e l i n e s of text f r o m y o u r file. T o d e l e t e a
r a n g e of l i n e s , y o u c a n s p e c i f y t h e i r line n u m b e r s in a D c o m m a n d . T o u s e t h e
D c o m m a n d , t y p e D a n d t h e line n u m b e r . If y o u t y p e a s p a c e a n d a s e c o n d
n u m b e r a f t e r D , E D I T r e m o v e s all t h e l i n e s f r o m t h e first line n u m b e r t o t h e
last. For e x a m p l e ,
D97
104
114
d e l e t e s l i n e s 9 7 t o 1 0 4 i n c l u s i v e , l e a v i n g l i n e 105 a s t h e n e w c u r r e n t l i n e .
T o delete the current line, type D without a qualifying n u m b e r . For example,
F/plum cake/; D
d e l e t e s t h e l i n e c o n t a i n i n g " p l u m c a k e " , a n d t h e line f o l l o w i n g it b e c o m e s t h e
n e w current line. Y o u can c o m b i n e a qualified search with a delete c o m m a n d ,
as follows:
F B/The/; 4D
T h i s c o m m a n d s e q u e n c e d e l e t e s f o u r l i n e s , t h e first o f w h i c h is t h e l i n e
beginning with " T h e " .
Y o u c a n a l s o t y p e a p e r i o d (.) o r a n a s t e r i s k (*) i n s t e a d o f l i n e n u m b e r s . T o
r e f e r t o t h e c u r r e n t l i n e , t y p e a p e r i o d . T o r e f e r to t h e e n d - o f - f i l e , t y p e a n
asterisk. For example,
D. *
deletes t h e rest of t h e source including the current line.
4.1.2.7
Inserting
New
Lines
T h i s s e c t i o n d e s c r i b e s h o w to i n s e r t text i n t o y o u r file w i t h E D I T . T o i n s e r t o n e
or m o r e l i n e s o f n e w m a t e r i a l B E F O R E a g i v e n l i n e , y o u u s e t h e I c o m m a n d .
Y o u c a n g i v e t h e I c o m m a n d a l o n e o r w i t h a l i n e n u m b e r , a p e r i o d ( . ) , or a n
a s t e r i s k (*). E D I T i n s e r t s t e x t b e f o r e t h e c u r r e n t line if y o u g i v e I o n its o w n , o r
f o l l o w it w i t h a p e r i o d (.). If y o u t y p e a n a s t e r i s k (*) a f t e r I, y o u r t e x t is i n s e r t e d
at t h e e n d o f t h e file ( t h a t i s , b e f o r e t h e e n d - o f - f i l e l i n e ) . A n y t e x t t h a t y o u t y p e
is i n s e r t e d b e f o r e t h e l i n e y o u s p e c i f i e d .
T o indicate t h e e n d of y o u r insertion, press R E T U R N , type Z , a n d p r e s s
R E T U R N again. For example,
I 468
The little fishes of the sea,
They sent an answer back to me.
Z
i n s e r t s t h e t w o l i n e s o f t e x t b e f o r e line 4 6 8 .
If y o u o m i t t h e l i n e n u m b e r f r o m t h e c o m m a n d , E D I T i n s e r t s t h e
material before the current line. For example,
new
115
F/corkscrew/; I
He said, "I'll go and wake them, if ..."
Z
T h i s multiple c o m m a n d finds the line containing " c o r k s c r e w " ( w h i c h t h e n
b e c o m e s t h e c u r r e n t line) a n d i n s e r t s t h e s p e c i f i e d n e w l i n e .
A f t e r a n I c o m m a n d c o n t a i n i n g a l i n e n u m b e r , t h e c u r r e n t l i n e is t h e l i n e o f
t h a t n u m b e r ; o t h e r w i s e , t h e c u r r e n t l i n e is u n c h a n g e d .
T o i n s e r t m a t e r i a l at t h e e n d o f t h e file, t y p e I*.
T o save y o u typing, E D I T provides the R (Replace) c o m m a n d , the
exact
R19 2 6
In winter when the fields are white
Z
d e l e t e s l i n e s 19 to 2 6 i n c l u s i v e , t h e n i n s e r t s t h e n e w m a t e r i a l b e f o r e l i n e 2 7 ,
w h i c h b e c o m e s the current line.
4.1.2.8
Command
Repetition
6(F
VII;
D)
d e l e t e s t h e n e x t six b l a n k l i n e s in t h e s o u r c e . C o m m a n d
groups may
not
116
6
7
8
A s b l a c k a s a tar b a r r e l
W h i c h f r i g h t e n e d b o t h t h e h e r o e s so
T h e y quite forgot their quorell
117
< c o m m a s at e n d o f l i n e s >
< F i s , in f a c t , r e d u n d a n t >
<Windup>
T h e f o l l o w i n g t e x t ( w i t h n e w line n u m b e r s ) is t h e r e s u l t .
1
A g r e e d to have a battle,
For T w e e d l e d u m said T w e e d l e d e e
H a d s p o i l e d h i s n i c e n e w rattle.
5
6
A s b l a c k a s a tar b a r r e l ,
N o t e : If y o u e x p e r i m e n t w i t h e d i t i n g t h i s s o u r c e file, y o u ' l l f i n d t h a t y o u
d o n ' t have to u s e the c o m m a n d s in the example above. For instance, on the
second line, you could use the following c o m m a n d :
E/a/have aJ
to produce the s a m e result. In other w o r d s , E E x c h a n g e s " a " for " h a v e a " , a n d
B p l a c e s " h a v e " B e f o r e " a " to p r o d u c e " h a v e a " .
118
C o m m a n d syntax
C o n t r o l o f C o m m a n d , I n p u t , a n d O u t p u t Files
Processing EDIT
Functional G r o u p i n g s of E D I T C o m m a n d s
Line W i n d o w s
String Operations on the Current Line
Miscellaneous Current Line C o m m a n d s
I n s p e c t i n g Parts of the Source: T h e T y p e C o m m a n d s
Control of C o m m a n d , Input, a n d O u t p u t Files
Loops
Global Operations
Displaying the Program State
Terminating an EDIT Run
Current Line Verification
Miscellaneous Commands
A b a n d o n i n g Interactive Editing
consist of a c o m m a n d
O n e or more
name
followed by zero or
a c o m m a n d n a m e a n d t h e first a r g u m e n t , b e t w e e n n o n - s t r i n g
more
between
arguments,
a n d b e t w e e n c o m m a n d s . A s p a c e c h a r a c t e r is o n l y n e c e s s a r y i n t h e s e p l a c e s
to separate
successive
items
otherwise
treated as one
(for e x a m p l e ,
two
numbers).
E D I T u n d e r s t a n d s t h a t a c o m m a n d is f i n i s h e d i n a n y o f t h e f o l l o w i n g w a y s :
when
you press
RETURN; when
of the
command
a r g u m e n t s ; o r w h e n E D I T r e a d s a s e m i c o l o n (;), o r c l o s i n g p a r e n t h e s e s ( ) ) , t h a t
you have typed.
Y o u u s e p a r e n t h e s e s to delimit c o m m a n d g r o u p s .
T o separate c o m m a n d s that appear o n the s a m e line of input, y o u type a
s e m i c o l o n . T h i s is o n l y strictly n e c e s s a r y i n c a s e s o f a m b i g u i t y w h e r e a c o m m a n d h a s a v a r i a b l e n u m b e r o f a r g u m e n t s . E D I T a l w a y s tries t o r e a d
the
longest possible c o m m a n d .
E x c e p t w h e r e t h e y a p p e a r a s p a r t of a c h a r a c t e r s t r i n g , E D I T t h i n k s o f u p p e r
a n d l o w e r case letters as the s a m e .
4.2.1.1
Command
Names
A c o m m a n d n a m e is e i t h e r a s e q u e n c e o f l e t t e r s or a s i n g l e s p e c i a l c h a r a c t e r
(for e x a m p l e , # ) . A n alphabetic c o m m a n d n a m e e n d s with a n y nonletter; o n l y
t h e first f o u r l e t t t e r s o f t h e n a m e a r e s i g n i f i c a n t . O n e or m o r e s p a c e s
may
a p p e a r b e t w e e n c o m m a n d n a m e s a n d t h e i r a r g u m e n t s ; E D I T r e q u i r e s at l e a s t
one space w h e n
name.
4.2.1.2
a n a r g u m e n t s t a r t i n g w i t h a letter f o l l o w s a n
119
alphabetic
Arguments
T h e f o l l o w i n g s e c t i o n s d e s c r i b e t h e six d i f f e r e n t t y p e s o f a r g u m e n t s y o u c a n
use with EDIT commands:
strings
qualified strings
search expressions
numbers
switch values
command groups
4.2.1.3
Strings
A s t r i n g is a s e q u e n c e o f u p to 8 0 c h a r a c t e r s e n c l o s e d in d e l i m i t e r s . Y o u m a y
u s e a n e m p t y ( n u l l ) s t r i n g . ( A n u l l s t r i n g is e x a c t l y w h a t it s o u n d s l i k e : a
n o n s t r i n g , t h a t i s , d e l i m i t e r s e n c l o s i n g n o t h i n g , f o r e x a m p l e , //.) T h e c h a r a c t e r
t h a t y o u d e c i d e to u s e to d e l i m i t a p a r t i c u l a r s t r i n g m a y n o t a p p e a r i n t h e
s t r i n g . T h e t e r m i n a t i n g d e l i m i t e r m a y b e o m i t t e d if it is i m m e d i a t e l y f o l l o w e d
b y t h e e n d of t h e c o m m a n d line.
T h e following characters are available for u s e as delimiters:
/+-,?:*
that is, c o m m o n English punctuation characters ( e x c e p t ; ) a n d the four arithmetic o p e r a t o r s .
H e r e are s o m e e x a m p l e s of strings:
IAI
*Menai Bridge*
??
+ String with final delimiter omitted
4.2.1.4
Multiple
Strings
A /King/The Red /
F o r all s u c h c o m m a n d s t h e s e c o n d s t r i n g s p e c i f i e s r e p l a c e m e n t t e x t . If y o u
o m i t t h e s e c o n d s t r i n g , E D I T u s e s t h e n u l l s t r i n g . If y o u d o t h i s w i t h t h e A a n d
120
Qualified
Strings
C o m m a n d s t h a t s e a r c h for c o n t e x t s , e i t h e r i n t h e c u r r e n t l i n e o r s c a n n i n g
t h r o u g h the source, specify the context with qualified strings. A
qualified
s t r i n g is a s t r i n g p r e c e d e d b y z e r o or m o r e q u a l i f i e r s . T h e q u a l i f i e r s a r e s i n g l e
letters. T h e y m a y appear in any order. For example,
BTJ/Abc/
S p a c e s m a y n o t a p p e a r b e t w e e n t h e q u a l i f i e r s . Y o u m a y f i n i s h a list o f
qualifiers w i t h a n y delimiter character. T h e available qualifiers are B (Beginn i n g ) , E ( E n d ) , L (Left o r L a s t ) , P ( P r e c i s e l y ) , a n d U ( U p p e r c a s e ) .
4 . 2 . 1 . 6 Search
Commands
Expressions
t h a t s e a r c h for a p a r t i c u l a r l i n e in t h e s o u r c e t a k e a
search
e x p r e s s i o n a s a n a r g u m e n t . A s e a r c h e x p r e s s i o n is a s i n g l e q u a l i f i e d s t r i n g . F o r
example,
F B/Tweedle/
tells E D I T to l o o k f o r a l i n e b e g i n n i n g w i t h t h e s t r i n g " T w e e d l e " .
4.2.1.7
Numbers
A n u m b e r is a s e q u e n c e o f d e c i m a l d i g i t s . L i n e n u m b e r s a r e a s p e c i a l f o r m o f
number
and must
a line
number
appears, the characters " . " and " * " may appear instead. A period represents
t h e c u r r e n t l i n e , a n d a n a s t e r i s k r e p r e s e n t s t h e last l i n e a t t h e e n d o f t h e s o u r c e
file. F o r e x a m p l e ,
M*
i n s t r u c t s E D I T t o m o v e to t h e e n d o f t h e s o u r c e file.
4.2.1.8
Switch
Values
C o m m a n d s t h a t alter E D I T s w i t c h e s t a k e a s i n g l e c h a r a c t e r as a n a r g u m e n t .
T h e c h a r a c t e r m u s t b e e i t h e r a + o r - . F o r e x a m p l e , in
Vt h e m i n u s s i g n (-) i n d i c a t e s t h a t E D I T s h o u l d t u r n off t h e v e r i f i c a t i o n . If y o u
121
Command
Groups
Unmatched parenthesis
N o t e t h a t it is o n l y n e c e s s a r y t o u s e p a r e n t h e s e s w h e n y o u i n t e n d t o r e p e a t a
c o m m a n d group more than once.
4.2.1.10
Command
Repetition
24N
If y o u g i v e a v a l u e o f z e r o , t h e n E D I T e x e c u t e s t h e c o m m a n d i n d e f i n i t e l y (or
u n t i l e n d - o f - f i l e is r e a c h e d ) . F o r e x a m p l e , if y o u t y p e
0 ( e /dum/dee/;n)
EDIT exchanges every occurrence of " d u m " for " d e e " to the e n d of the
file.
Y o u c a n specify repeat counts for c o m m a n d g r o u p s in t h e s a m e w a y as for
individual c o m m a n d s :
122
Prompts
W h e n E D I T is b e i n g r u n i n t e r a c t i v e l y , t h a t i s , w i t h b o t h t h e c o m m a n d file
c o n n e c t e d to t h e k e y b o a r d a n d t h e v e r i f i c a t i o n file c o n n e c t e d to a w i n d o w , it
d i s p l a y s a p r o m p t w h e n it is r e a d y t o r e a d a n e w l i n e o f c o m m a n d s . A l t h o u g h ,
if t h e last c o m m a n d o f t h e p r e v i o u s l i n e c a u s e d v e r i f i c a t i o n o u t p u t , E D I T d o e s
not return a prompt.
If y o u t u r n t h e v e r i f i c a t i o n s w i t c h V o n , E D I T v e r i f i e s t h e c u r r e n t l i n e i n
place of a p r o m p t in the following circumstances:
if it h a s n o t a l r e a d y v e r i f i e d t h e c u r r e n t l i n e ,
if y o u h a v e m a d e a n y c h a n g e s t o t h e l i n e s i n c e it w a s last v e r i f i e d , o r
if y o u h a v e c h a n g e d t h e p o s i t i o n o f t h e o p e r a t i o n a l w i n d o w .
O t h e r w i s e , w h e n E D I T d o e s n o t v e r i f y t h e c u r r e n t l i n e , it d i s p l a y s a c o l o n
c h a r a c t e r (:) t o i n d i c a t e t h a t it is r e a d y f o r a n e w l i n e o f c o m m a n d s . T h i s c o l o n
is t h e u s u a l E D I T p r o m p t .
E D I T n e v e r gives p r o m p t s w h e n you are inserting lines.
4 . 2 . 2 . 2 The Current
Line
A s E D I T r e a d s l i n e s f r o m t h e s o u r c e file a n d w r i t e s t h e m to t h e d e s t i n a t i o n
file, t h e l i n e t h a t E D I T h a s in its h a n d at a n y t i m e is c a l l e d t h e c u r r e n t l i n e .
Every c o m m a n d that y o u type refers to the current line. EDIT inserts n e w lines
b e f o r e t h e c u r r e n t l i n e . W h e n y o u start e d i t i n g w i t h E D I T , t h e c u r r e n t l i n e is
t h e first l i n e o f t h e s o u r c e .
4.2.2.3
Line
Numbers
E D I T i d e n t i f i e s e a c h line i n t h e s o u r c e b y a u n i q u e l i n e n u m b e r . T h i s is n o t
p a r t of t h e i n f o r m a t i o n s t o r e d i n t h e file. E D I T c o m p u t e s t h e s e n u m b e r s b y
c o u n t i n g t h e l i n e s a s it r e a d s t h e m . E D I T d o e s n o t a s s i g n l i n e n u m b e r s to a n y
n e w lines that y o u insert into the source.
E D I T d i s t i n g u i s h e s b e t w e e n original a n d n o n o r i g i n a l l i n e s . O r i g i n a l l i n e s
a r e s o u r c e l i n e s t h a t h a v e n o t b e e n split or i n s e r t e d ; n o n o r i g i n a l l i n e s a r e split
l i n e s a n d i n s e r t e d l i n e s . C o m m a n d s t h a t t a k e l i n e n u m b e r s as a r g u m e n t s m a y
o n l y r e f e r to o r i g i n a l l i n e s . E D I T m o v e s f o r w a r d , o r b a c k w a r d u p t o a s e t limit,
a c c o r d i n g t o w h e t h e r t h e l i n e n u m b e r y o u t y p e is g r e a t e r o r l e s s t h a n
the
123
c u r r e n t l i n e n u m b e r . E D I T p a s s e s o v e r o r d e l e t e s (if a p p r o p r i a t e ) n o n o r i g i n a l
l i n e s in s e a r c h e s f o r a g i v e n original l i n e .
W h e n y o u t y p e a p e r i o d (.) i n s t e a d o f a l i n e n u m b e r , E D I T a l w a y s u s e s t h e
c u r r e n t l i n e w h e t h e r original or n o n o r i g i n a l . ( F o r a n e x a m p l e o f its u s e , s e e
Section 4.1.2.6, Deleting Whole Lines.)
Y o u c a n r e n u m b e r l i n e s w i t h t h e " = " c o m m a n d . T h i s e n s u r e s t h a t all l i n e s
following the current line are original. T y p e :
= 15
to n u m b e r the current line as 15, the next line 16, the next 17, a n d so o n to the
e n d o f t h e file. T h i s is h o w y o u a l l o c a t e l i n e n u m b e r s t o n o n o r i g i n a l l i n e s . If
y o u do not qualify the = c o m m a n d with a n u m b e r , E D I T displays the m e s s a g e :
Strings
position,
w h i c h is t h e b e g i n n i n g o f t h e l i n e e x c e p t a s s p e c i f i e d b e l o w . I n t h e a b s e n c e o f
a n y q u a l i f i e r s , E D I T m a y f i n d t h e g i v e n s t r i n g a n y w h e r e in a l i n e . Q u a l i f i e r s
specify additional conditions for the context. E D I T recognizes five qualifiers B ,
E , L , P, a n d U a s f o l l o w s :
B
w h e r e the string m u s t b e at t h e B e g i n n i n g of the line. This qualifier m a y n o t
a p p e a r w i t h E , L , or P .
E
w h e r e the string m u s t b e at the E n d of the line. This qualifier m a y n o t a p p e a r
w i t h B , L , o r P . If E a p p e a r s w i t h t h e n u l l s t r i n g , it m a t c h e s w i t h t h e e n d o f t h e
l i n e . ( T h a t i s , l o o k f o r n o t h i n g at t h e e n d o f a l i n e . )
L
w h e r e t h e s e a r c h f o r t h e s t r i n g is t o t a k e p l a c e L e f t w a r d f r o m t h e e n d o f t h e
line instead of rightward from the b e g i n n i n g .
I f t h e r e is m o r e t h a n
one
o c c u r r e n c e o f t h e s t r i n g i n a l i n e , t h i s qualifier m a k e s s u r e t h a t t h e L a s t o n e is
f o u n d i n s t e a d o f t h e first. L m a y n o t a p p e a r w i t h B , E , o r P . If L a p p e a r s w i t h
t h e n u l l s t r i n g , it m a t c h e s w i t h t h e e n d o f t h e l i n e . ( T h a t i s , l o o k l e f t w a r d f r o m
t h e e n d of t h e line for an occurrence of n o t h i n g . )
124
AMIGADOS USER'S M A N U A L
P
w h e r e t h e line m u s t m a t c h t h e s t r i n g P r e c i s e l y a n d m u s t c o n t a i n n o o t h e r
c h a r a c t e r s . P m u s t n o t a p p e a r w i t h B , E , or L . If P a p p e a r s w i t h a n u l l s t r i n g , it
matches with an empty line.
U
w h e r e t h e s t r i n g m a t c h is to t a k e p l a c e w h e t h e r or n o t u p p e r or l o w e r c a s e is
u s e d . (That is, as though y o u translated both the string and the line into
U p p e r c a s e letters before comparing t h e m . ) For example, w h e n y o u specify U,
the following string
/TWEEDledum/
should m a t c h a line containing
TweedleDUM
as w e l l a s a n y o t h e r c o m b i n a t i o n i n u p p e r o r l o w e r c a s e .
4.2.2.5
Output
Processing
E D I T d o e s n o t w r i t e l i n e s r e a d in a f o r w a r d d i r e c t i o n t o t h e d e s t i n a t i o n file
i m m e d i a t e l y , b u t i n s t e a d it a d d s t h e m to a n o u t p u t q u e u e i n m a i n m e m o r y .
W h e n E D I T h a s u s e d u p t h e m e m o r y available for s u c h l i n e s , it w r i t e s o u t t h e
l i n e s at t h e h e a d of t h e q u e u e a s n e c e s s a r y . U n t i l E D I T h a s a c t u a l l y w r i t t e n o u t
a l i n e t o t h e d e s t i n a t i o n file, y o u c a n m o v e b a c k a n d m a k e it t h e c u r r e n t l i n e
again.
Y o u c a n a l s o s e n d p o r t i o n s of t h e o u t p u t t o d e s t i n a t i o n files o t h e r t h a n T O .
W h e n y o u s e l e c t a n a l t e r n a t i v e d e s t i n a t i o n file, E D I T w r i t e s o u t t h e q u e u e of
l i n e s for t h e c u r r e n t o u t p u t file.
4.2.2.6
End-of-File
Handling
W h e n E D I T r e a c h e s t h e e n d o f a s o u r c e file, a d u m m y e n d - o f - f i l e l i n e
b e c o m e s c u r r e n t . T h i s e n d - o f - f i l e line h a s a line n u m b e r o n e g r e a t e r t h a n t h e
n u m b e r of l i n e s in t h e file. E D I T v e r i f i e s t h e line b y d i s p l a y i n g t h e line n u m b e r
a n d an asterisk.
W h e n t h e e n d - o f - f i l e l i n e is c u r r e n t , c o m m a n d s to m a k e c h a n g e s to t h e
c u r r e n t l i n e , a n d c o m m a n d s t o m o v e f o r w a r d , p r o d u c e a n e r r o r . A l t h o u g h , if
y o u c o n t a i n t h e s e k i n d s o f c o m m a n d s w i t h i n a n infinitely r e p e a t i n g g r o u p ,
E D I T does not give an error on reaching the end-of-file line. T h e E (Exchange)
c o m m a n d is a n e x a m p l e of a c o m m a n d t o m a k e c h a n g e s t o t h e c u r r e n t l i n e .
T h e N ( N e x t ) c o m m a n d is a n e x a m p l e of a c o m m a n d to m o v e f o r w a r d .
125
characters
Description
a,b
l i n e n u m b e r s (or. or*)
g
m,n
command group
q
se
q u a l i f i e r list ( p o s s i b l y e m p t y )
s,t
sw
/
numbers
search expression
switch value ( + or - )
string delimiter
Table 4.1: Notation for Command Descriptions
N o t e : C o m m a n d d e s c r i p t i o n s t h a t a p p e a r in t h e r e s t o f t h i s m a n u a l w i t h t h e
a b o v e notation s h o w t h e S Y N T A X of t h e c o m m a n d ; t h e y are n o t e x a m p l e s of
w h a t y o u actually type. Examples always appear as follows in
this typeface.
4.2.3.1
Selection
of a Current
Line
E D I T q u e u e s u p l i n e s t h a t it h a s p a s s e d i n a
backward
d i r e c t i o n r e a d y f o r s u b s e q u e n t r e p r o c e s s i n g in a f o r w a r d d i r e c t i o n . M t a k e s a
line n u m b e r , period, or asterisk. S o , using the c o m m a n d notation described
a b o v e , t h e c o r r e c t s y n t a x for M is a s f o l l o w s :
Ma
w h e r e M a m o v e s f o r w a r d or b a c k w a r d to l i n e " a " i n t h e s o u r c e . O n l y o r i g i n a l
lines can b e accessed b y line n u m b e r .
M +
m a k e s t h e last l i n e a c t u a l l y r e a d f r o m t h e file c u r r e n t l i n e . M +
moves through
all t h e l i n e s c u r r e n t l y h e l d i n m e m o r y u n t i l t h e last o n e is r e a c h e d .
AMIGADOS USER'S M A N U A L
126
Mm a k e s t h e l a s t l i n e o n t h e o u t p u t q u e u e c u r r e n t . T h i s is like s a y i n g t o E D I T :
" M o v e b a c k as far as y o u c a n . "
N
m o v e s f o r w a r d t o t h e n e x t l i n e i n t h e s o u r c e . W h e n t h e c u r r e n t l i n e is t h e last
l i n e of t h e s o u r c e , e x e c u t i n g a n N c o m m a n d d o e s n o t c r e a t e a n e r r o r . E D I T
i n c r e a s e s t h e line n u m b e r b y a d d i n g o n e to it a n d c r e a t e s a s p e c i a l e n d - o f - f i l e
l i n e . H o w e v e r , if -you try to u s e a n N c o m m a n d w h e n y o u a r e a l r e a d y at t h e
e n d of t h e s o u r c e file, E D I T r e t u r n s a n e r r o r .
P
m o v e s b a c k to t h e p r e v i o u s l i n e . Y o u c a n m o v e m o r e t h a n o n e l i n e b a c k b y
e i t h e r r e p e a t i n g P , o r g i v i n g a n u m b e r b e f o r e it. T h e n u m b e r t h a t y o u g i v e
s h o u l d b e e q u a l t o t h e n u m b e r of l i n e s y o u w a n t to m o v e b a c k .
T h e s y n t a x f o r t h e F ( F i n d ) c o m m a n d is
F se
S o , F f i n d s t h e line y o u s p e c i f y w i t h t h e s e a r c h e x p r e s s i o n " s e " . T h e s e a r c h
s t a r t s at t h e c u r r e n t line a n d m o v e s f o r w a r d t h r o u g h t h e s o u r c e . T h e s e a r c h
s t a r t s at t h e c u r r e n t line in o r d e r t o c o v e r t h e c a s e w h e r e t h e c u r r e n t line h a s
b e e n r e a c h e d as a side effect of previous c o m m a n d s s u c h as line deletion. A n
F c o m m a n d w i t h n o a r g u m e n t s e a r c h e s u s i n g t h e last e x e c u t e d s e a r c h e x p r e s s i o n .
T h e s y n t a x f o r t h e B F ( B a c k w a r d F i n d ) c o m m a n d is
B F se
B F b e h a v e s like F e x c e p t t h a t it starts at t h e c u r r e n t line a n d m o v e s b a c k w a r d
u n t i l it f i n d s a l i n e t h a t m a t c h e s its s e a r c h e x p r e s s i o n .
4.2.3.2
Line Insertion
and
Deletion
C o m m a n d s m a y s e l e c t a n e w c u r r e n t line a s a s i d e e f f e c t of t h e i r m a i n
f u n c t i o n . T h o s e f o l l o w e d b y i n - l i n e i n s e r t i o n m a t e r i a l m u s t b e t h e last c o m m a n d o n a l i n e . T h e i n s e r t i o n m a t e r i a l is o n s u c c e s s i v e l i n e s t e r m i n a t e d b y Z
o n a line b y itself. Y o u c a n u s e t h e Z c o m m a n d t o c h a n g e t h e t e r m i n a t o r . E D I T
r e c o g n i z e s t h e t e r m i n a t o r y o u g i v e in e i t h e r u p p e r or l o w e r c a s e . F o r e x a m p l e ,
using the same notation,
127
la
< i n s e r t i o n m a t e r i a l , as m a n y
lines as n e c e s s a r y >
inserts the insertion material before " a " . R e m e m b e r that " a " can b e a specific
l i n e n u m b e r , a p e r i o d ( r e p r e s e n t i n g t h e c u r r e n t l i n e ) , or a n a s t e r i s k ( r e p r e s e n t i n g t h e last l i n e o f t h e s o u r c e file). If y o u o m i t " a " , E D I T i n s e r t s t h e m a t e r i a l
before the current line; otherwise, line " a " b e c o m e s the current line.
I/s/
i n s e r t s t h e c o n t e n t s o f t h e file " s " ( r e m e m b e r , " s " m e a n s a n y s t r i n g ) b e f o r e t h e
current line.
Rab
Replacement material>
Z
Ra b/s/
T h e R c o m m a n d is e q u i v a l e n t to D f o l l o w e d b y I. T h e s e c o n d l i n e n u m b e r
m u s t b e g r e a t e r t h a n o r e q u a l t o t h e first. Y o u m a y o m i t t h e s e c o n d n u m b e r if
y o u w a n t to r e p l a c e j u s t t h e o n e l i n e ( t h a t i s , if b =
n u m b e r s if y o u w a n t t o r e p l a c e t h e c u r r e n t l i n e . T h e l i n e f o l l o w i n g l i n e
searches
AMIGADOS USER'S M A N U A L
128
26.
>
t h e o p e r a t i o n a l w i n d o w c o n t a i n s t h e c h a r a c t e r s t o t h e r i g h t of t h e p o i n t e r : " l i n e
2 6 t h i s i s . " E D I T o m i t s t h e i n d i c a t o r if it is at t h e start o f t h e l i n e .
T h e left e d g e of t h e w i n d o w is also called t h e c h a r a c t e r p o i n t e r i n t h i s
c o n t e x t , a n d t h e f o l l o w i n g c o m m a n d s a r e available for m o v i n g it:
>
m o v e s t h e p o i n t e r o n e c h a r a c t e r to t h e r i g h t .
<
m o v e s t h e p o i n t e r o n e c h a r a c t e r to t h e left.
PR
P o i n t e r R e s e t s e t s t h e p o i n t e r t o t h e start of t h e l i n e .
T h e s y n t a x f o r t h e P A ( P o i n t A f t e r ) c o m m a n d is
P A q/s/
P o i n t A f t e r s e t s t h e p o i n t e r s o t h a t t h e first c h a r a c t e r i n t h e w i n d o w is t h e first
c h a r a c t e r f o l l o w i n g t h e s t r i n g s. F o r e x a m p l e ,
129
P A VI
m o v e s t h e p o i n t e r to t h e e n d o f t h e l i n e .
T h e s y n t a x f o r t h e P B ( P o i n t B e f o r e ) c o m m a n d is
P B q/s/
P o i n t B e f o r e is t h e s a m e a s P A , b u t i n c l u d e s t h e s t r i n g itself in t h e w i n d o w .
4.2.4.2
Single
Character
Operations
on the Current
Line
$
f o r c e s l o w e r c a s e (Dollar for D o w n ) .
The command
%
forces u p p e r case (Percent for uP).
The "
" ( u n d e r s c o r e ) c o m m a n d c h a n g e s t h e first c h a r a c t e r in t h e w i n d o w
the
right.
The command
#
d e l e t e s t h e first c h a r a c t e r i n t h e w i n d o w . T h e r e m a i n d e r o f t h e w i n d o w m o v e s
o n e c h a r a c t e r to t h e l e f t , l e a v i n g t h e c h a r a c t e r p o i n t e r p o i n t i n g a t t h e n e x t
c h a r a c t e r i n t h e l i n e . T h e c o m m a n d is e x a c t l y e q u i v a l e n t to
E/s//
w h e r e " s " is t h e first c h a r a c t e r in t h e w i n d o w . T o r e p e a t t h e e f f e c t , y o u s p e c i f y a
n u m b e r b e f o r e t h e " # " c o m m a n d . If t h e v a l u e is " n " , f o r e x a m p l e , t h e n t h e
r e p e a t e d c o m m a n d is e q u i v a l e n t to t h e s i n g l e c o m m a n d
E/s//
130
5#
d e l e t e s t h e n e x t f i v e c h a r a c t e r s in t h e w i n d o w . If y o u t y p e a n u m b e r e q u a l t o
or greater t h a n the n u m b e r of characters in the w i n d o w , E D I T deletes
the
c o n t e n t s o f t h e e n t i r e w i n d o w . E D I T t r e a t s a s e q u e n c e o f " # " c o m m a n d s in t h e
s a m e w a y a s a s i n g l e , r e p e a t e d " # " c o m m a n d . S o , # # # # # is t h e s a m e a s
t y p i n g a single # , pressing R E T U R N after each single # , five times.
Y o u can u s e a c o m b i n a t i o n of " > " % " $ "
they
a f f e c t . T h e f o l l o w i n g t e x t a n d c o m m a n d s illustrate t h i s :
Basic String
Operations
T h r e e s i m i l a r c o m m a n d s a r e a v a i l a b l e for a l t e r i n g p a r t s o f t h e c u r r e n t l i n e .
T h e A , B , a n d E c o m m a n d s i n s e r t t h e i r s e c o n d (string) a r g u m e n t A f t e r , B e f o r e ,
o r i n E x c h a n g e f o r t h e i r first a r g u m e n t r e s p e c t i v e l y . Y o u m a y q u a l i f y t h e first
a r g u m e n t . If t h e current line w e r e
131
E U/carpenter/Walrus/
<Exchange>
B/bese/did /
A L//;/
w o u l d c h a n g e t h e line to
String
Y o u c a n u s e t h e n u l l , or e m p t y s t r i n g (//) a f t e r a n y s t r i n g c o m m a n d . If y o u
u s e the null string as the second string in an E c o m m a n d , EDIT r e m o v e s the
first s t r i n g f r o m t h e l i n e . P r o v i d e d E D I T f i n d s t h e first s t r i n g , a n A o r B
c o m m a n d with a null second string does nothing; otherwise, EDIT returns a n
e r r o r . A n u l l first s t r i n g i n a n y o f t h e t h r e e c o m m a n d s m a t c h e s at t h e initial
s e a r c h p o s i t i o n . T h e initial s e a r c h p o s i t i o n is t h e c u r r e n t c h a r a c t e r
(initially t h e b e g i n n i n g
is present,
o f t h e line) u n l e s s e i t h e r o f t h e E o r L
position
qualifiers
i n w h i c h c a s e t h e i n i t i a l p o s i t i o n is t h e e n d o f t h e l i n e .
For
example,
A//carpenter/
p u t s t h e t e x t c a r p e n t e r A f t e r n o t h i n g , t h a t i s , at t h e b e g i n n i n g o f t h e l i n e .
Whereas
A L//carpenter
p u t s c a r p e n t e r a t t h e e n d of t h e l i n e A f t e r t h e L a s t n o t h i n g .
4.2.5.3
Pointing
The AP
Variant
EP
syntax
132
BP/s/t/
is e q u i v a l e n t to
B/s/t/;PA/ts/
and
2 E P U/tweadle/Tweedle/
would change
Parts
of the Current
Line
Y o u u s e t h e c o m m a n d s D T A ( D e l e t e Till A f t e r ) a n d D T B ( D e l e t e Till B e f o r e )
t o d e l e t e f r o m t h e b e g i n n i n g o f t h e line (or c h a r a c t e r p o i n t e r ) to a s p e c i f i e d
string. To delete from a given context until the e n d of t h e line, y o u u s e the
c o m m a n d s D F A ( D e l e t e F r o m A f t e r ) a n d D F B ( D e l e t e F r o m B e f o r e ) . If t h e
current line w e r e
King's men
while
DTA/horses /
w o u l d c h a n g e it to
133
that explain h o w to
repeat
c o m m a n d s i n v o l v i n g s t r i n g s , h o w t o split t h e c u r r e n t l i n e , a n d h o w t o j o i n
lines together.
W h e n e v e r E D I T e x e c u t e s a s t r i n g a l t e r a t i o n c o m m a n d (for e x a m p l e , A , B , o r
E ) , it b e c o m e s t h e c u r r e n t s t r i n g a l t e r a t i o n c o m m a n d . T o r e p e a t t h e c u r r e n t
s t r i n g a l t e r a t i o n c o m m a n d , y o u c a n t y p e a s i n g l e q u o t e ('). T h e ' c o m m a n d h a s
n o a r g u m e n t s . It t a k e s its a r g u m e n t s f r o m t h e last A , B , or E c o m m a n d .
W A R N I N G : U n e x p e c t e d e f f e c t s o c c u r if y o u u s e s e q u e n c e s s u c h a s
E / c a s t l e / k n i g h t / ; 4(';
E/pawn/queen/)
T h e s e c o n d a n d s u b s e q u e n t e x e c u t i o n s of t h e ' c o m m a n d r e f e r t o a
d i f f e r e n t c o m m a n d t h a n t h e first. T h e a b o v e e x a m p l e w o u l d
castle a n d knight twice a n d exchange p a w n
and queen
exchange
seven
times
instead of e x c h a n g i n g castle a n d knight once a n d t h e n four times exchanging castle a n d knight a n d p a w n a n d queen.
4.2.6.1
Splitting
and Joining
Lines
E D I T is p r i m a r i l y a l i n e e d i t o r . M o s t E D I T e d i t i n g c o m m a n d s d o n o t o p e r a t e
over line boundaries, but this section describes c o m m a n d s for splitting a line
into m o r e than o n e line a n d for joining together t w o or m o r e successive lines.
T o split a l i n e b e f o r e a s p e c i f i e d c o n t e x t , y o u u s e t h e S B c o m m a n d .
The
s y n t a x f o r t h e S B c o m m a n d is
S B q/s/
S B t a k e s a n o p t i o n a l qualifier r e p r e s e n t e d h e r e b y q, a n d a s t r i n g Isl.
SB
the
l i n e A f t e r t h e c o n t e x t y o u s p e c i f y w i t h t h e qualifier a n d s t r i n g .
T o c o n c a t e n a t e a l i n e , y o u u s e t h e C L c o m m a n d . T h e s y n t a x f o r C L is
134
CL/s/
C L t a k e s a n o p t i o n a l s t r i n g t h a t is r e p r e s e n t e d h e r e b y Is/. C L o r C o n c a t e n a t e
Line f o r m s a n e w current line b y concatenating the current line, the string y o u
s p e c i f i e d , a n d t h e n e x t l i n e f r o m t h e s o u r c e , in t h a t o r d e r . If t h e s t r i n g is a n u l l
string, y o u m a y type the c o m m a n d C L without specifying a string.
For an e x a m p l e of splitting a n d joining lines, look at the text
SA /; /; 2CL/ /
c h a n g e the line into
135
as
the
option.
(To
find
out
more
about
the
option,
refer
to
S e c t i o n 4 . 1 . 1 , C a l l i n g E D I T ) . T h e a d v a n t a g e o f t h e T N c o m m a n d is t h a t e v e r y t h i n g v i s i b l e d u r i n g t h e t y p i n g o p e r a t i o n is a v a i l a b l e i n m e m o r y t o P
and
BF commands.
T h e s y n t a x f o r t h e T L ( T y p e w i t h L i n e n u m b e r s ) c o m m a n d is a s f o l l o w s :
TLn
T L n t y p e s n l i n e s as f o r T , b u t w i t h l i n e n u m b e r s a d d e d . I n s e r t e d
and
non-
+ . (Remember that y o u
136
command,
input,
and
output
files t h a t y o u
set u p
when
you
enter
EDIT.
4.2.8.1
Command
Files
W h e n y o u e n t e r E D I T , it r e a d s c o m m a n d s f r o m t h e t e r m i n a l or t h e file t h a t
y o u s p e c i f y as W I T H . T o r e a d c o m m a n d s f r o m a n o t h e r file, y o u c a n u s e t h e C
c o m m a n d . T h e s y n t a x for t h e c o m m a n d is
C .8.
w h e r e the string " s " represents a filename. A s A m i g a D O S uses the
slash
s y m b o l (/) t o s e p a r a t e f i l e n a m e s , y o u s h o u l d u s e p e r i o d s (.), o r s o m e o t h e r
s y m b o l , to d e l i m i t t h e f i l e n a m e . A s y m b o l f o u n d in a s t r i n g s h o u l d n o t b e u s e d
a s a d e l i m i t e r . W h e n E D I T h a s f i n i s h e d all t h e c o m m a n d s in t h e file (or y o u
g i v e a Q c o m m a n d ) , it c l o s e s t h e file a n d c o n t r o l r e v e r t s to t h e
command
Input
Files
T o i n s e r t t h e e n t i r e c o n t e n t s o f a file at a s p e c i f i c p o i n t in t h e s o u r c e , y o u u s e
the I and R commands.
4.1.2.7
137
w h e r e t h e s t r i n g " s " is a f i l e n a m e . A F R O M c o m m a n d w i t h n o
argument
r e s e l e c t s t h e o r i g i n a l s o u r c e file.
W h e n E D I T executes a F R O M c o m m a n d , the current line r e m a i n s current;
h o w e v e r , the next line c o m e s f r o m the n e w source.
E D I T d o e s n o t c l o s e a s o u r c e file w h e n t h e file c e a s e s t o b e c u r r e n t ; y o u c a n
r e a d f u r t h e r l i n e s f r o m t h e s o u r c e file b y r e s e l e c t i n g it l a t e r .
T o c l o s e a n o u t p u t file t h a t y o u o p e n e d i n E D I T , a n d t h a t s u b s e q u e n t l y y o u
w a n t t o o p e n f o r i n p u t (or t h e o t h e r w a y a r o u n d ) , y o u m u s t u s e t h e C F ( C l o s e
File) c o m m a n d . T h e C F c o m m a n d h a s t h e f o l l o w i n g f o r m :
C F .s.
w h e r e the string " s " represents a filename. W h e n y o u e n d an E D I T session,
E D I T c l o s e s a u t o m a t i c a l l y all t h e files y o u o p e n e d i n E D I T .
N o t e : A n y t i m e y o u o p e n a file, E D I T starts at t h e b e g i n n i n g o f t h a t file. If
y o u c l o s e a file w i t h C F , E D I T starts o n t h e first line o f t h a t file if y o u r e o p e n
it, a n d n o t at t h e line it w a s o n w h e n y o u c l o s e d t h e file.
A n e x a m p l e o f t h e u s e o f t h e F R O M c o m m a n d t o m e r g e l i n e s f r o m t w o files
follows:
Command
Action
M10
F R O M .XYZ.
Select
M6
FROM
Reselect
M14
F R O M .XYZ.
Reselect
new input,
the FROM
FROM,
XYZ
XYZ,
FROM
XYZ
FROM
Reselect
FROM,
the rest of
XYZ
FROM
CF .XYZ.
Close
M*
file
current
FROM
M*
4.2.8.3
(source)
line 10 remains
XYZ
(lines 15 till
end-of-file)
Files
E D I T u s u a l l y s e n d s o u t p u t t o t h e file w i t h f i l e n a m e T O . H o w e v e r , E D I T d o e s
n o t s e n d t h e o u t p u t i m m e d i a t e l y . It k e e p s a c e r t a i n n u m b e r o f l i n e s i n a q u e u e
in m a i n m e m o r y as long as possible. T h e s e lines are previous current lines or
lines that EDIT has passed before reaching the present current line. T h e n u m ber of lines that E D I T can k e e p d e p e n d s o n the options y o u specified w h e n
y o u c a l l e d E D I T . B e c a u s e E D I T k e e p s t h e s e l i n e s , it h a s t h e c a p a b i l i t y
for
m o v i n g b a c k w a r d in the source.
T o a s s o c i a t e t h e o u t p u t q u e u e w i t h a file o t h e r t h a n t h a t w i t h t h e f i l e n a m e
T O , y o u c a n also u s e the T O c o m m a n d . T h e T O c o m m a n d h a s the form
138
T O .s.
w h e r e " s " is a f i l e n a m e .
W h e n E D I T e x e c u t e s a T O c o m m a n d , it w r i t e s o u t t h e e x i s t i n g q u e u e o f
o u t p u t l i n e s if t h e o u t p u t file is s w i t c h e d .
E D I T d o e s n o t c l o s e a n o u t p u t file w h e n it is n o l o n g e r c u r r e n t . B y r e s e l e c t i n g t h e file, y o u c a n a d d f u r t h e r l i n e s to it. T h e f o l l o w i n g e x a m p l e s h o w s
h o w y o u c a n split u p t h e s o u r c e b e t w e e n t h e m a i n d e s t i n a t i o n T O a n d a n
alternate destination XYZ.
Command
Action
Mil
TO.XYZ.
Switch
M21
to
to TO
to
output
to TO
file
XYZ
TO
M31
TO.XYZ.
M41
XYZ
TO
If y o u w a n t t o r e u s e a file, y o u m u s t explicitly c l o s e it. T h e c o m m a n d
CF .filename.
c l o s e s t h e file w i t h t h e f i l e n a m e y o u s p e c i f y as t h e a r g u m e n t .
T h e s e i n p u t / o u t p u t c o m m a n d s a r e u s e f u l w h e n y o u w a n t to m o v e p a r t o f t h e
s o u r c e file to a l a t e r p l a c e in t h e o u t p u t . F o r e x a m p l e ,
Command
Action
T O .:T/1.
Output
1000N
Advance
TO
Revert
to temporary
through
file
source
to TO
C F . :T/1.
Close output
12000. : T / 1 .
Reuse
file
as input
:T.l
file
If y o u u s e t h e C F c o m m a n d o n files y o u h a v e f i n i s h e d w i t h , t h e a m o u n t o f
m e m o r y y o u n e e d is m i n i m i z e d .
4.2.9 Loops
Y o u can type a n u n s i g n e d decimal n u m b e r before m a n y c o m m a n d s to indicate
repetition, for e x a m p l e ,
139
84N
Y o u c a n a l s o s p e c i f y r e p e a t c o u n t s for c o m m a n d g r o u p s in t h e s a m e w a y a s
for i n d i v i d u a l c o m m a n d s , for e x a m p l e ,
W A R N I N G : Be careful w h e n y o u m o v e b a c k w a r d t h r o u g h the
source
n o t t o l e a v e a n y a c t i v e or " e n a b l e d " g l o b a l s . T h e s e e n a b l e d g l o b a l s c o u l d
u n d o a lot o f y o u r w o r k !
4.2.10.1
Setting
Global
Changes
140
4.2.10.2
Cancelling
Global
Changes
T h e R E W I N D c o m m a n d c a n c e l s all g l o b a l o p e r a t i o n s a u t o m a t i c a l l y . Y o u c a n
u s e t h e C G ( C a n c e l G l o b a l ) c o m m a n d t o c a n c e l i n d i v i d u a l c o m m a n d s at a n y
time.
W h e n a g l o b a l o p e r a t i o n is set u p b y o n e o f t h e c o m m a n d s G A , G B , o r G E ,
t h e o p e r a t i o n is a l l o c a t e d a n i d e n t i f i c a t i o n n u m b e r w h i c h is o u t p u t t o t h e
v e r i f i c a t i o n file (for e x a m p l e , G l ) . T h e a r g u m e n t f o r C G is t h e n u m b e r o f t h e
g l o b a l o p e r a t i o n to b e c a n c e l l e d . If C G is e x e c u t e d w i t h n o a r g u m e n t , E D I T
c a n c e l s all g l o b a l s .
4.2.10.3
Suspending
Global
Changes
argument,
all g l o b a l s a r e t u r n e d off or o n ( d i s a b l e d o r e n a b l e d ) , a s a p p r o p r i a t e .
expression
matches.
141
B A C K U P . T h i s b a c k u p file i s , o f c o u r s e , o n l y a v a i l a b l e u n t i l t h e n e x t t i m e E D I T
is run.
T h e S T O P c o m m a n d s t o p s E D I T i m m e d i a t e l y . N o f u r t h e r i n p u t o r o u t p u t is
attempted. In particular, the S T O P c o m m a n d stops E D I T from overwriting the
o r i g i n a l s o u r c e file. T y p i n g S T O P e n s u r e s t h a t n o c h a n g e is m a d e t o t h e i n p u t
information.
The Q c o m m a n d stops EDIT from executing the current c o m m a n d
( E D I T initially a c c e p t s c o m m a n d s f r o m t h e k e y b o a r d , b u t y o u c a n
file
specify
a c o m m a n d file w i t h t h e W I T H k e y w o r d o r w i t h t h e C c o m m a n d ) a n d m a k e s
it r e v e r t t o t h e p r e v i o u s o n e . A Q at t h e o u t e r m o s t l e v e l d o e s t h e
same
as a W .
s i n c e it m a d e
or c h a n g e d
since the
last
verification.
W h e n E D I T h a s m o v e d p a s t a l i n e t h a t it h a s c h a n g e d , b u t n o t y e t v e r i f i e d .
W h e n E D I T displays an error m e s s a g e .
I n t h e first t w o c a s e s , t h e v e r i f i c a t i o n o n l y o c c u r s if t h e V s w i t c h is o n . T h e
command
V sw
c h a n g e s t h e s e t t i n g o f t h e V s w i t c h . It is set O N (V + ) if t h e initial s t a t e o f E D I T
is i n t e r a c t i v e ( c o m m a n d s a n d v e r i f i c a t i o n s b o t h c o n n e c t e d to a t e r m i n a l ) , a n d
t o O F F (V-) o t h e r w i s e .
T o explicitly r e q u e s t v e r i f i c a t i o n o f t h e c u r r e n t l i n e , y o u u s e t h e f o l l o w i n g
command:
?
T h i s c o m m a n d v e r i f i e s t h e c u r r e n t l i n e . It is p e r f o r m e d a u t o m a t i c a l l y if t h e V
s w i t c h is o n a n d t h e i n f o r m a t i o n i n t h e line h a s b e e n c h a n g e d . T h e v e r i f i c a t i o n
c o n s i s t s o f t h e l i n e n u m b e r (or +
+ if t h e l i n e is n o t o r i g i n a l ) , w i t h t h e
nonprinting
142
T h e ! c o m m a n d verifies t h e c u r r e n t line w i t h c h a r a c t e r i n d i c a t o r s . E D I T
p r o d u c e s t w o l i n e s of v e r i f i c a t i o n . T h e first is t h e c u r r e n t line in w h i c h E D I T
r e p l a c e s all t h e n o n g r a p h i c c h a r a c t e r s w i t h t h e first c h a r a c t e r of t h e i r h e x a d e c i m a l v a l u e . In t h e s e c o n d l i n e , E D I T d i s p l a y s a m i n u s s i g n u n d e r all t h e
p o s i t i o n s c o r r e s p o n d i n g t o u p p e r c a s e l e t t e r s a n d t h e s e c o n d h e x a d e c i m a l digit
in t h e p o s i t i o n s c o r r e s p o n d i n g to n o n g r a p h i c c h a r a c t e r s . All o t h e r p o s i t i o n s
contain space characters.
T h e following example uses the ? and ! c o m m a n d s . T o verify the current
l i n e , y o u u s e t h e ? c o m m a n d . If, f o r i n s t a n c e , t h e f o l l o w i n g a p p e a r s w h e n y o u
use the ? c o m m a n d :
?
1.
The Walrus and the ??
t h e n y o u m i g h t try t o
However, EDIT may
q u e s t i o n m a r k s if t h e
ters. T o find out w h a t
1.
The Walrus and the 11
- - 44
T o correct the line, y o u can use the character pointer a n d # c o m m a n d to
d e l e t e t h e s p u r i o u s c h a r a c t e r s b e f o r e i n s e r t i n g t h e c o r r e c t text. ( F o r f u r t h e r
details o n using the character pointer and # c o m m a n d , see Section 4 . 2 . 4 , Line
Windows.)
143
T o t u r n trailing s p a c e s o n or off, y o u u s e t h e T R ( T R a i l i n g s p a c e s ) c o m m a n d .
The T R c o m m a n d takes the following form:
TR sw
w h e r e s w r e p r e s e n t s a s w i t c h ( + for O N ; - f o r O F F ) . E D I T u s u a l l y s u p p r e s s e s
all trailing s p a c e s . T R +
a l l o w s trailing s p a c e s t o r e m a i n o n b o t h i n p u t a n d
output lines.
To r e n u m b e r the source lines, you use the =
command. The =
command
"n"
represents a number.
The command
=n
line
n u m b e r to " n " . If y o u t h e n m o v e t o t h e l i n e s b e l o w t h e c u r r e n t l i n e , E D I T
r e n u m b e r s all t h e f o l l o w i n g original a n d n o n o r i g i n a l l i n e s . A l t h o u g h , if y o u
m o v e b a c k to p r e v i o u s l i n e s a f t e r u s i n g t h e =
c o m m a n d , E D I T m a r k s all t h e
p r e v i o u s l i n e s i n t h e o u t p u t q u e u e as n o n o r i g i n a l . W h e n y o u r e w i n d
the
command.
T o r e w i n d t h e s o u r c e file, y o u u s e t h e R E W I N D c o m m a n d . F o r e x a m p l e ,
REWIND
This c o m m a n d
r e w i n d s t h e i n p u t file s o t h a t l i n e 1 is t h e c u r r e n t
line
a g a i n . F i r s t E D I T s c a n s t h e r e s t o f t h e s o u r c e (for g l o b a l s , a n d s o f o r t h ) .
Then
it w r i t e s t h e l i n e s to t h e d e s t i n a t i o n ,
o p e n e d as a n e w
w h i c h is t h e n c l o s e d a n d
s o u r c e . It c l o s e s t h e original s o u r c e u s i n g a
re-
temporary
file a s a d e s t i n a t i o n . A n y g l o b a l s t h a t y o u s p e c i f y a r e c a n c e l l e d . E D I T
does
n o t n e c e s s a r i l y r e q u i r e y o u to t y p e t h e c o m p l e t e w o r d ( t h a t i s , R E W I N D ) . T o
m o v e to t h e b e g i n n i n g , y o u c a n t y p e a n y o f t h e f o l l o w i n g : R E W I , R E W I N , o r
REWIND.
*** BREAK
144
Description
qs
Qualified string
String
L i n e n u m b e r , o r . o r * ( c u r r e n t a n d last line)
sw
+ o r - ( o n or off)
<
Action
M o v e c h a r a c t e r p o i n t e r left
>
#
$
%
P A qs
M o v e c h a r a c t e r p o i n t e r to a f t e r q s
PB qs
M o v e c h a r a c t e r p o i n t e r to b e f o r e q s
PR
R e s e t c h a r a c t e r p o i n t e r t o start o f l i n e
L o w e r c a s e c h a r a c t e r at p o i n t e r
U p p e r c a s e c h a r a c t e r at p o i n t e r
T u r n c h a r a c t e r at p o i n t e r to s p a c e
Positioning Commands
Command
M n
Action
M o v e to l i n e n
M o v e t o h i g h e s t l i n e in m e m o r y
M o v e to lowest line in m e m o r y
N e x t line
Previous line
REWIND
R e w i n d i n p u t file
Search Commands
Command
Action
F qs
Find string qs
BF qs
S a m e as F , b u t m o v e b a c k w a r d t h r o u g h file
D F qs
S a m e as F , b u t d e l e t e l i n e s a s t h e y a r e p a s s e d
Text Verification
Command
Action
T y p e t o e n d o f file
Tn
Type n lines
TLn
TN
TP
M - , t h e n t y p e t o last l i n e in b u f f e r
V sw
S e t v e r i f i c a t i o n o n or off
Action
A qs t
A P qs t
B qs t
B P qs t
S a m e as B , b u t m o v e c h a r a c t e r p o i n t e r
CL t
C o n c a t e n a t e c u r r e n t l i n e , s t r i n g t, a n d n e x t l i n e
D
D F A qs
D F B qs
D T A qs
D T B qs
E qs t
EP qs t
I
II
R
R t
S A qs
S B qs
D e l e t e c u r r e n t line
Delete from after qs to e n d of line
D e l e t e f r o m b e f o r e q s to e n d o f l i n e
D e l e t e f r o m start o f l i n e to a f t e r q s
D e l e t e f r o m start o f l i n e to b e f o r e q s
E x c h a n g e string qs with string t
S a m e as E , b u t m o v e c h a r a c t e r p o i n t e r
Insert material from terminal before line
I n s e r t f r o m file t
Replace material from terminal
R e p l a c e m a t e r i a l f r o m file t
Split l i n e a f t e r q s
Split line before qs
Globals
Command
Action
G A qs t
G l o b a l l y p l a c e t after q s
G B qs t
G E qs t
CG n
DG n
EG n
SHG
G l o b a l l y e x c h a n g e q s for t
C a n c e l g l o b a l n (all if n o m i t t e d )
D i s a b l e g l o b a l n (all if n o m i t t e d )
E n a b l e g l o b a l n (all if n o m i t t e d )
Display info o n globals used
145
146
Input/Output Manipulation
Command
Action
FROM
T a k e s o u r c e f r o m original
FROM t
T a k e s o u r c e f r o m file t
TO
R e v e r t to original d e s t i n a t i o n
TO t
P l a c e o u t p u t l i n e s i n file t
CF t
C l o s e file t
Other Commands
Command
Action
Repeat previous A, B, or E c o m m a n d
Set line n u m b e r to n
Ct
T a k e c o m m a n d s f r o m file t
Hn
S e t h a l t at l i n e n . If n = * t h e n h a l t a n d u n s e t h
Q
SHD
Exit f r o m c o m m a n d l e v e l ; w i n d u p if at level 1
STOP
Stop
S h o w data
TR sw
S e t / u n s e t trailing s p a c e r e m o v a l
Windup
Zt
S e t i n p u t t e r m i n a t o r to s t r i n g t
Appendix
User Errors
103: insufficient free
Probable
cause:
store
suggestion:
148
module
cause:
E i t h e r y o u m i s s p e l l e d t h e c o m m a n d n a m e , or t h i s file m a y n o t b e i n l o a d a b l e
file f o r m .
Recovery
suggestion:
E i t h e r r e t y p e t h e file n a m e , or m a k e s u r e t h a t t h e file is a b i n a r y p r o g r a m
file. R e m e m b e r t h a t i n o r d e r t o e x e c u t e a c o m m a n d s e q u e n c e t h e c o m m a n d
E X E C U T E m u s t b e u s e d b e f o r e t h e file n a m e .
1 2 2 : invalid
202:
resident
object
Probable
library
during
load
in use
cause:
T h e file o r d i r e c t o r y s p e c i f i e d is a l r e a d y b e i n g u s e d b y a n o t h e r a p p l i c a t i o n i n
a m a n n e r i n c o m p a t i b l e w i t h t h e w a y y o u w a n t to u s e it.
Recovery
suggestion:
If a n o t h e r a p p l i c a t i o n is w r i t i n g to a file, t h e n n o b o d y e l s e c a n r e a d f r o m it. If
a n o t h e r a p p l i c a t i o n is r e a d i n g f r o m a file, t h e n n o b o d y e l s e c a n w r i t e t o it. If a n
a p p l i c a t i o n is u s i n g a d i r e c t o r y or r e a d i n g f r o m a file, t h e n n o b o d y e l s e m a y
d e l e t e o r r e n a m e t h e file or d i r e c t o r y . Y o u m u s t s t o p t h e o t h e r a p p l i c a t i o n
u s i n g t h e file o r d i r e c t o r y a n d t h e n try a g a i n .
203:
object
Probable
already
exists
cause:
T h e o b j e c t n a m e t h a t y o u s p e c i f i e d is t h a t o f a n o b j e c t t h a t a l r e a d y e x i s t s .
Recovery
suggestion:
not
not
found
found
cause:
A m i g a D O S c a n n o t f i n d t h e d e v i c e or file y o u s p e c i f i e d . Y o u h a v e p r o b a b l y
m a d e a t y p o g r a p h i c a l or s p e l l i n g e r r o r .
Recovery
suggestion:
C h e c k d e v i c e n a m e s a n d f i l e n a m e s for c o r r e c t s p e l l i n g s . Y o u a l s o g e t t h i s
e r r o r if y o u a t t e m p t t o c r e a t e a file in a d i r e c t o r y t h a t d o e s n o t exist.
206:
invalid
Probable
window
cause:
Y o u h a v e e i t h e r m a d e t h e d i m e n s i o n s t o o b i g o r t o o s m a l l , or y o u h a v e f a i l e d
to d e f i n e a n e n t i r e w i n d o w . (For e x a m p l e , y o u m u s t n o t f o r g e t t h e f i n a l s l a s h . )
149
Y o u c a n a l s o g e t t h i s e r r o r f r o m N E W C L I if y o u s u p p l y a d e v i c e n a m e t h a t is
not a window.
Recovery
suggestion:
stream
component
name
cause:
Y o u h a v e i n c l u d e d a n i n v a l i d c h a r a c t e r in t h e f i l e n a m e y o u h a v e s p e c i f i e d , o r
t h e f i l e n a m e is t o o l o n g . E a c h file o r d i r e c t o r y m u s t b e l e s s t h a n 3 0 c h a r a c t e r s
long. A filename cannot contain control characters.
2 2 2 : object
Probable
not of required
type
cause:
versa.
the
suggestion:
C h e c k o n t h e c o m m a n d u s a g e in C h a p t e r 2 o f t h e AmigaDOS
User's
Manual
in t h i s b o o k .
2 2 3 : disk not
Probable
validated
cause:
E i t h e r y o u j u s t i n s e r t e d a d i s k a n d t h e d i s k v a l i d a t i o n p r o c e s s is i n p r o g r e s s ,
o r it m a y b e a b a d d i s k .
Recovery
suggestion:
W a i t f o r t h e d i s k v a l i d a t i o n p r o c e s s to f i n i s h i t n o r m a l l y o n l y t a k e s l e s s
t h a n a m i n u t e . If A m i g a D O S c a n n o t v a l i d a t e t h e d i s k b e c a u s e it is b a d , t h e n
the disk remains unvalidated. In this case, y o u can only read from the disk a n d
y o u m u s t copy your information onto another disk.
2 2 4 : disk
Probable
write-protected
cause:
T h i s d i s k is w r i t e - p r o t e c t e d . T h e A m i g a c a n n o t w r i t e o v e r i n f o r m a t i o n t h a t is
already o n the disk. Y o u can only read information f r o m this disk. Y o u c a n n o t
store a n y information of y o u r o w n h e r e .
Recovery
suggestion:
S a v e y o u r i n f o r m a t i o n o n a d i s k t h a t is n o t w r i t e - p r o t e c t e d , o r c h a n g e t h e
write-protect tab on the disk.
2 2 5 : rename
Probable
across
devices
attempted
cause:
R E N A M E only changes a filename on the same device, although you can use
150
it t o r e n a m e a file f r o m o n e d i r e c t o r y i n t o a n o t h e r o n t h e s a m e d e v i c e .
Recovery
suggestion:
C o p y t h e file to t h e o b j e c t d e v i c e a n d d e l e t e it f r o m t h e s o u r c e d e v i c e .
216: directory not empty
Probable
cause:
Y o u c a n n o t d e l e t e a d i r e c t o r y u n l e s s it is e m p t y .
Recovery
suggestion:
D e l e t e t h e c o n t e n t s of t h e d i r e c t o r y . S t u d y t h e c o m m a n d s p e c i f i c a t i o n f o r
D E L E T E i n C h a p t e r 2 of t h i s m a n u a l .
218: device not
mounted
Probable
cause:
T h e w o r d " m o u n t e d " here m e a n s "inserted into the drive"; either you've
m a d e a typographical error, or the disk with the desired n a m e isn't m o u n t e d .
Recovery
suggestion:
C h e c k t h e s p e l l i n g of t h e d e v i c e s , or i n s e r t t h e c o r r e c t d i s k .
2 2 0 : comment too big
Probable
cause:
Y o u r f i l e n o t e h a s e x c e e d e d t h e m a x i m u m n u m b e r of c h a r a c t e r s
(80).
allowed
Recovery
suggestion:
R e t y p e t h e f i l e n o t e a d h e r i n g to t h e s e l i m i t s .
2 2 1 : disk full
Probable
cause:
Y o u d o n o t h a v e sufficient r o o m o n t h e d i s k to d o this o p e r a t i o n .
Recovery
suggestion:
U s e a n o t h e r d i s k or d e l e t e s o m e u n n e c e s s a r y files o r d i r e c t o r i e s .
2 2 2 : file is protected from
deletion
Probable
cause:
T h e file or d i r e c t o r y h a s b e e n p r o t e c t e d f r o m d e l e t i o n .
Recovery
suggestion:
Y o u e i t h e r d i d n o t m e a n to d e l e t e t h a t file, or y o u really d i d m e a n it. If
y o u really d i d m e a n it, y o u m u s t u s e t h e P R O T E C T c o m m a n d t o alter t h e
p r o t e c t i o n s t a t u s . R e f e r t o t h e P R O T E C T c o m m a n d in C h a p t e r 2 . A l s o u s e
t h e L I S T c o m m a n d to c h e c k o n w h a t t h e p r o t e c t i o n s of t h i s p a r t i c u l a r file o r
disk are.
2 2 3 : file is protected
Probable
cause:
from
writing
151
T h e file o r d i r e c t o r y h a s b e e n p r o t e c t e d f r o m b e i n g o v e r w r i t t e n .
Recovery
suggestion:
Y o u e i t h e r d i d n o t m e a n t o w r i t e t o t h a t file, o r y o u really d i d m e a n it. If y o u
really d i d m e a n it, y o u m u s t u s e t h e P R O T E C T c o m m a n d to a l t e r t h e p r o t e c t i o n s t a t u s . R e f e r to t h e P R O T E C T
c o m m a n d in C h a p t e r 2 . A l s o u s e
the
L I S T c o m m a n d to c h e c k o n t h e p r o t e c t i o n s o f t h i s p a r t i c u l a r file or d i s k .
224: file is protected
Probable
from
reading
cause:
T h e file o r d i r e c t o r y h a s b e e n p r o t e c t e d f r o m b e i n g r e a d .
Recovery
suggestion:
Y o u e i t h e r d i d n o t m e a n to r e a d f r o m t h a t file, or y o u r e a l l y d i d m e a n it. If
y o u r e a l l y d i d m e a n it, y o u m u s t u s e t h e P R O T E C T c o m m a n d to a l t e r t h e
p r o t e c t i o n s t a t u s . R e f e r t o t h e P R O T E C T c o m m a n d in C h a p t e r 2 . A l s o u s e t h e
L I S T c o m m a n d t o c h e c k o n t h e p r o t e c t i o n s o f t h i s p a r t i c u l a r file o r d i s k .
2 2 5 : not a DOS
Probable
disk
cause:
T h e d i s k in t h e d r i v e is n o t a f o r m a t t e d D O S d i s k .
Recovery
suggestion:
P l a c e a s u i t a b l y f o r m a t t e d D O S d i s k in t h e drive i n s t e a d , o r e l s e f o r m a t t h e
d i s k u s i n g t h e F O R M A T c o m m a n d if y o u d o n ' t w a n t a n y o f t h e i n f o r m a t i o n o n
it.
2 2 6 : no disk in
Probable
cause:
drive
Y o u h a v e a t t e m p t e d to r e a d or w r i t e to a d i s k d r i v e w h e r e t h e r e is n o d i s k .
Recovery
suggestion:
P l a c e a s u i t a b l y f o r m a t t e d D O S d i s k in t h e d r i v e .
Programmer Errors
209: packet
Probable
request
type
unknown
cause:
Y o u h a v e a s k e d a d e v i c e h a n d l e r to a t t e m p t a n o p e r a t i o n it c a n n o t d o ( f o r
example, the console handler cannot rename anything).
Recovery
suggestion:
C h e c k t h e r e q u e s t c o d e p a s s e d to d e v i c e h a n d l e r s .
2 1 1 : invalid
Probable
object
lock
cause:
Y o u h a v e u s e d s o m e t h i n g t h a t is n o t a v a l i d l o c k .
152
Recovery
suggestion:
C h e c k y o u r c o d e s o t h a t y o u o n l y p a s s valid l o c k s to A m i g a D O S calls t h a t
expect locks.
219: seek error
Probable
cause:
Y o u h a v e a t t e m p t e d to call S E E K w i t h i n v a l i d a r g u m e n t s .
Recovery
suggestion:
M a k e s u r e t h a t y o u o n l y S E E K w i t h i n t h e file. Y o u c a n n o t S E E K o u t s i d e
t h e b o u n d s of t h e file.
2 3 2 : no more entries in
directory
Probable
cause:
T h e r e are n o m o r e entries in the directory that y o u are examining.
Recovery
suggestion:
T h i s e r r o r c o d e i n d i c a t e s t h a t t h e A m i g a D O S call E X N E X T h a s n o m o r e
e n t r i e s i n t h e d i r e c t o r y y o u a r e e x a m i n i n g to h a n d b a c k t o y o u . S t o p calling
EXNEXT.
Glossary
Arguments
A d d i t i o n a l i n f o r m a t i o n s u p p l i e d to c o m m a n d s .
Character pointer
P o i n t e r t o t h e left e d g e of a line w i n d o w in E D I T . Y o u u s e it t o d e f i n e t h e
p a r t of a line t h a t E D I T m a y alter.
Character string
S e q u e n c e of p r i n t a b l e c h a r a c t e r s .
Command
A n i n s t r u c t i o n y o u g i v e directly to t h e c o m p u t e r .
C o m m a n d L i n e I n t e r f a c e (CLI)
A process that decodes user input.
Console handler
See terminal handler.
C o m m a n d template
T h e m e t h o d of d e f i n i n g t h e s y n t a x f o r e a c h c o m m a n d .
Control combination
A c o m b i n a t i o n of t h e C T R L k e y a n d a letter or s y m b o l . T h e C T R L k e y is
p r e s s e d d o w n w h i l e t h e letter or s y m b o l is t y p e d . It a p p e a r s i n t h e d o c u m e n t a t i o n , for e x a m p l e , in the form C T R L - A .
Current cursor position
T h e p o s i t i o n t h e c u r s o r is c u r r e n t l y at.
APPENDIX: GLOSSARY
153
Current directory
T h i s is e i t h e r t h e r o o t d i r e c t o r y or t h e last d i r e c t o r y y o u set y o u r s e l f in w i t h
the c o m m a n d C D .
Current drive
T h e d i s k d r i v e t h a t is i n s e r t e d a n d d e c l a r e d to b e c u r r e n t . T h e d e f a u l t is
SYS:.
Current line
T h e l i n e t h a t E D I T h a s in its h a n d at a n y
time.
same
154
Process
A job requested by the operating system or the user.
Qualifiers
Characters that specify additional conditions for the context in string.
Qualified string
A s t r i n g p r e c e d e d b y o n e or m o r e q u a l i f i e r s .
Queue
See Output queue.
Root directory
T h e t o p l e v e l in t h e filing s y s t e m . F i l e s a n d d i r e c t o r i e s w i t h i n t h e
root
d i r e c t o r y h a v e t h e i r n a m e s p r e c e d e d b y a c o l o n (:).
S e q u e n t i a l files
A file t h a t c a n b e a c c e s s e d at a n y p o i n t b y s t a r t i n g a t t h e b e g i n n i n g a n d
s c a n n i n g s e q u e n t i a l l y u n t i l t h e p o i n t is r e a c h e d .
S o u r c e file
File b e i n g read from.
Syntax
T h e f o r m a t or " g r a m m a r " y o u u s e for g i v i n g a c o m m a n d .
Terminal handler
A p r o c e s s h a n d l i n g i n p u t a n d o u t p u t f r o m t h e t e r m i n a l or c o n s o l e .
Volume name
T h e unique n a m e associated with a disk.
Wild card
S y m b o l s u s e d to match any pattern.
AmigaDOS
Manual
Developer'
Contents
1.
2.
3.
4.
Using Preferences
T h e d e f a u l t text s i z e o n t h e A m i g a a l l o w s u p t o 6 0 c h a r a c t e r s p e r l i n e i n a
f u l l - w i d t h C L I w i n d o w . M a n y d e v e l o p e r s p r e f e r to u s e 8 0 c h a r a c t e r s p e r l i n e .
Y o u c a n c h a n g e t h e text style b y u s i n g t h e P r e f e r e n c e s t o o l f r o m y o u r W o r k b e n c h d i s k ; h o w e v e r , t h e n e w text w i d t h will n o t n e c e s s a r i l y t a k e e f f e c t o n a n y
w i n d o w s t h a t y o u c u r r e n t l y h a v e o p e n e d . T h a t i s , a n y old w i n d o w s in t h e
s y s t e m r e m a i n w i t h a text size of 6 0 . T o i n c o r p o r a t e text s i z e i n t o t h e s y s t e m ,
y o u n e e d t o c r e a t e a n e w w i n d o w , select t h e o l d w i n d o w , a n d f i n a l l y d e l e t e
the old w i n d o w .
Follow these steps:
1. U s e t h e N E W C L I c o m m a n d .
2. Select the old w i n d o w .
3 . U s e t h e E N D C L I c o m m a n d i n t h e old w i n d o w to d e l e t e t h e o l d w i n d o w .
If y o u a l t e r t h e C L I s e l e c t i o n , t h e c h a n g e m a y n o t t a k e e f f e c t i m m e d i a t e l y . If
y o u save the n e w preferences a n d reboot, they take effect.
Chapter 1
Introduction
1.2
1.2.1
P r o g r a m D e v e l o p m e n t for t h e A m i g a
Getting Started
1.2.2
1.2.3
1.3
1.3.1
1.3.2
1.3.3
1.3.4
1.4
1.5
1.5.1
1.5.2
1.5.3
1.1 Introduction
T h e A m i g a D O S p r o g r a m m i n g e n v i r o n m e n t is available o n t h e A m i g a ,
and IBM PC.
Sun,
T h i s m a n u a l a s s u m e s t h a t y o u h a v e s o m e familiarity w i t h e i t h e r C or A s s e m b l e r . It d o e s n o t a t t e m p t to t e a c h e i t h e r of t h e s e l a n g u a g e s . A n i n t r o d u c t i o n to
C c a n b e f o u n d i n t h e b o o k The C Programming
Language b y B r i a n W . K e r n i g h a n
a n d D e n n i s M . Ritchie, published b y Prentice Hall. T h e r e are a n u m b e r of
b o o k s o n w r i t i n g 6 8 0 0 0 a s s e m b l e r , i n c l u d i n g Programming
the MC68000
by Tim
King a n d Brian Knight, published by A d d i s o n W e s l e y .
158
User's Manual
in t h i s b o o k .
following
items:
1. D o c u m e n t a t i o n o n A m i g a D O S a n d o t h e r s y s t e m r o u t i n e s t h a t y o u c a n call.
F o r e x a m p l e , y o u n e e d t h e AmigaDOS
a n d p o s s i b l y t h e AmigaDOS
Technical
User's
Manual,
Reference
Manual
ROM
Kernel
Manual,
as well.
2 . D o c u m e n t a t i o n o n t h e l a n g u a g e y o u i n t e n d to u s e . If y o u i n t e n d t o u s e
A s s e m b l e r o r C , t h e n t h i s m a n u a l tells y o u h o w to u s e t h e s e t o o l s a l t h o u g h
it d o e s n o t c o n t a i n a n y specific i n f o r m a t i o n n o r m a l l y f o u n d in a l a n g u a g e
reference manual.
3 . H e a d e r files c o n t a i n i n g t h e n e c e s s a r y A m i g a s t r u c t u r e d e f i n i t i o n s a n d t h e
values for calling the sytem routines that y o u n e e d .
Commodore-Amiga
For
159
f o r t h a t r e s i d e n t l i b r a r y in r e g i s t e r A 6 a n d t h e n j u m p i n g t o a s u i t a b l e n e g a t i v e
o f f s e t f r o m t h a t p o i n t e r . T h e o f f s e t s a r e available to y o u a s a b s o l u t e e x t e r n a l s i n
t h e A m i g a library, with n a m e s of the form
could be J S R
L V O n a m e . S o , f o r i n s t a n c e , a call
L V O n a m e ( A 6 ) , w h e r e y o u h a v e l o a d e d A 6 w i t h a suitable library
b a s e p o i n t e r . T h e s e b a s e p o i n t e r s a r e a v a i l a b l e to y o u f r o m t h e O p e n l i b r a r y
call t o E x e c ; y o u c a n f i n d t h e b a s e p o i n t e r f o r E x e c at l o c a t i o n 4 ( t h e o n l y
a b s o l u t e l o c a t i o n u s e d in t h e A m i g a ) . T h i s l o c a t i o n is also k n o w n as A b s E x e c B a s e
w h i c h is d e f i n e d i n A m i g a . l i b . ( S e e t h e ROM
Kernel
Manual
on Exec.)
Y o u c a n call c e r t a i n R A M - b a s e d r e s i d e n t libraries a n d t h e A m i g a D O S library
in t h i s w a y , if r e q u i r e d . N o t e t h a t t h e A m i g a D O S library is c a l l e d " d o s . l i b r a r y " .
H o w e v e r , y o u d o n o t n e e d to u s e A 6 t o h o l d a p o i n t e r to t h e l i b r a r y b a s e ; y o u
m a y u s e a n y o t h e r r e g i s t e r if y o u n e e d t o . I n a d d i t i o n , y o u m a y call A m i g a D O S
u s i n g t h e r e s i d e n t l i b r a r y call f e a t u r e o f t h e l i n k e r . I n t h i s c a s e , s i m p l y c o d e a
J S R t o t h e e n t r y p o i n t a n d t h e l i n k e r n o t e s t h e fact t h a t y o u h a v e u s e d a
r e f e r e n c e to a r e s i d e n t library. W h e n y o u r c o d e is l o a d e d i n t o ' m e m o r y ,
the
l o a d e r a u t o m a t i c a l l y o p e n s t h e library a n d c l o s e s it f o r y o u w h e n y o u h a v e
u n l o a d e d . T h e l o a d e r a u t o m a t i c a l l y p a t c h e s r e f e r e n c e s to A m i g a D O S
entry
p o i n t s to r e f e r t o t h e c o r r e c t o f f s e t f r o m t h e library b a s e p o i n t e r .
and D O W N L O A D
programs
on the Amiga
to
t r a n s f e r c h a r a c t e r or b i n a r y files.
2. Assemble or compile your program.
3. Link your program together, including any startup code you m a y require
at t h e b e g i n n n i n g , a n d s c a n t h e A m i g a library a n d a n y o t h e r s y o u m a y n e e d
to satisfy a n y external references.
4 . L o a d y o u r p r o g r a m i n t o t h e A m i g a a n d w a t c h it r u n !
old-fashioned
160
l i n e - o r i e n t e d T T Y s y s t e m a l t h o u g h y o u m i g h t f i n d a C L I u s e f u l , f o r e x a m p l e , to
p o r t y o u r p r o g r a m o v e r to y o u r A m i g a a s a first s t e p in d e v e l o p m e n t . T o l o a d
a n d e n t e r y o u r p r o g r a m , y o u s i m p l y t y p e t h e n a m e o f t h e file t h a t c o n t a i n s t h e
binary a n d possibly follow this with a n u m b e r of a r g u m e n t s .
or
by
in t h e l i n k e r i n p u t .
This m e a n s
your
p r o g r a m at t h e startup code entry point. This section of c o d e scans the argum e n t list a n d m a k e s t h e a r g u m e n t s a v a i l a b l e i n " a r g v " , w i t h t h e n u m b e r o f
a r g u m e n t s in " a r g c " a s u s u a l . It a l s o o p e n s t h e A m i g a D O S library a n d calls
I n p u t ( ) a n d O u t p u t ( ) for y o u , p l a c i n g t h e r e s u l t i n g file h a n d l e s i n t o " s t d i n " a n d
" s t d o u t " . It t h e n calls t h e C f u n c t i o n " m a i n " .
161
162
f o r t h i s initial m e s s a g e b e f o r e y o u start to d o a n y t h i n g . Y o u m u s t r e t a i n t h e
m e s s a g e a n d r e t u r n it t o W o r k b e n c h w h e n y o u r p r o g r a m h a s f i n i s h e d , s o t h a t
W o r k b e n c h can u n l o a d the code of your p r o g r a m .
F o r C p r o g r a m m e r s , t h i s is all d o n e b y s i m p l y u s i n g a d i f f e r e n t
startup
code
onto
the
Amiga.
This
section
describes
the
special
support
C o m m o d o r e - A m i g a gives to S u n Microsystem a n d M S D O S e n v i r o n m e n t s . It
a l s o d e s c r i b e s h o w to c r o s s - d e v e l o p i n o t h e r e n v i r o n m e n t s w i t h o u t t h i s s p e c i a l
support.
a n d it a c c e p t s
It
.c files a n d p l a c e s t h e r e s u l t i n g o b j e c t
program
in the current directory with the s a m e filename, but ending with .obj. T h e
s u f f i x . o b j d e n o t e s a n o b j e c t file. T h e c o m p i l e r a s s u m e s t h a t files
in
.asm
are
assembly
source
programs.
You
can
use
the
ending
assembler
to
a s s e m b l e t h e s e a n d p r o d u c e a n o b j e c t file ( e n d i n g w i t h . o b j ) i n t h e c u r r e n t
directory.
T h e compiler metacc takes m a n y options with the following format:
metacc
[<optl>[,<opt2>[,..<optn>]]][<file>[,...<filen>]]
T h e o p t i o n s a v a i l a b l e a r e as f o l l o w s :
-c -g - g o - w - p - p g - 0 [ < o p t f l a g s > ] - f s i n g l e
- S -E - C - X 7 0 - o < o u t p u t > - D < n a m e = d e f >
- U < n a m e > -I < d i r > -B < s t r i n g > - t [ p 0 1 2 ]
163
T h e f o l l o w i n g o p t i o n s i n s t r u c t m e t a c c to:
-c
produced
e v e n if it o n l y c o m p i l e s o n e p r o g r a m .
-g
-go
older
A l s o , p a s s t h e -lg
flag
t o Id.
-w
s u p p r e s s all w a r n i n g m e s s a g e s .
-p
p r o d u c e p r o f i l i n g c o d e to c o u n t t h e n u m b e r o f t i m e s e a c h
r o u t i n e is c a l l e d . If l o a d i n g t a k e s p l a c e , r e p l a c e t h e s t a n d a r d
s t a r t u p r o u t i n e b y o n e t h a t is a u t o m a t i c a l l y c a l l e d b y t h e
m o n i t o r a n d u s e s a s p e c i a l p r o f i l i n g library i n s t e a d o f t h e
s t a n d a r d C library.
U s e the prof program to generate an execution profile.
-pg
p r o d u c e p r o f i l i n g c o d e like - p , b u t i n v o k e a r u n - t i m e r e c o r d i n g m e c h a n i s m t h a t k e e p s m o r e e x t e n s i v e statistics a n d
p r o d u c e s a g m o n . o u t file at n o r m a l t e r m i n a t i o n .
U s e t h e g p r o f p r o g r a m to g e n e r a t e a n e x e c u t i o n p r o f i l e .
-0[<optflags>]
use
the
generated
code.
If " o p t f l a g s " a p p e a r s , y o u i n c l u d e < o p t f l a g s > in t h e c o m m a n d line to run the optimizer. Y o u can u s e - O to
pass
option flags.
-fsingle
use
single-precision
a r i t h m e t i c in c o m p u t a t i o n s
involving
o n l y flo at n u m b e r s ; t h a t i s , d o n o t c o n v e r t e v e r y t h i n g to
double (that is, the default).
N o t e : F l o a t i n g - p o i n t p a r a m e t e r s a r e still c o n v e r t e d t o d o u b l e p r e c i s i o n , a n d f u n c t i o n s t h a t r e t u r n v a l u e s still r e t u r n d o u b l e precision values.
164
-S
-E
-c
-X70
-o < o u t p u t >
-D<name = def>
d e f i n e " n a m e " to t h e p r e p r o c e s s o r , as if b y # d e f i n e . If n o
d e f i n i t i o n is g i v e n , d e f i n e t h e n a m e a s "1".
-U<name>
-I<dir>
a l w a y s l o o k for # i n c l u d e files w h o s e n a m e s d o n o t b e g i n
w i t h " / " first in t h e d i r e c t o r y of t h e < f i l e > a r g u m e n t , t h e n
l o o k in t h e < d i r > s p e c i f i e d in t h e -I o p t i o n , a n d finally l o o k
in the /usr/include directory.
-B<string>
find substitute
c o m p i l e r p a s s e s i n t h e files
specified
by
f i n d o n l y t h e d e s i g n a t e d c o m p i l e r p a s s e s in t h e files w h o s e
n a m e s a r e c o n s t r u c t e d b y a - B o p t i o n . I n t h e a b s e n c e of a - B
o p t i o n , a s s u m e < s t r i n g > to b e / u s r / n e w / .
T h e letter a n d n u m b e r c o m b i n a t i o n s t h a t y o u c a n s p e c i f y f o r
t h e -t o p t i o n h a v e t h e f o l l o w i n g m e a n i n g s :
p
cppthe C preprocessor
m e t a c o m b o t h p h a s e s of t h e C c o m p i l e r , b u t n o t t h e
optimizer.
I g n o r e d i n this s y s t e m t h i s o p t i o n w o u l d b e f o r t h e
s e c o n d p h a s e of a t w o - p h a s e c o m p i l e r b u t in t h e S u n
system; ccom includes both phases.
165
option.
If a s i n g l e C p r o g r a m is c o m p i l e d a n d l o a d e d all a t o n c e , t h e i n t e r m e d i a t e .o
file is d e l e t e d .
F i g u r e 1-A lists t h e f i l e n a m e s of s p e c i a l m e t a c c files a n d t h e i r d e s c r i p t i o n s .
Special Files
File Description
Filename
C source code
file.c
A s s e m b l e r s o u r c e file
file, a s m
O b j e c t file
file.o
L i b r a r y o f o b j e c t files
file.lib
E x e c u t a b l e o u t p u t files
a. o u t
T e m p o r a r y files
/tmp/ctm
Preprocessor
Compiler
/lib/cpp
/lib/ccom
Optional optimizer
/lib/c2
R u n t i m e startoff
/lib/crtO.o
/lib/mcrtO.o
/usr/lib/gcrtO.o
S t a n d a r d library
/lib/libc.a
P r o f i l i n g library
/usr/lib/libc
Standard directory ( # i n c l u d e .
/usr/include
p. a
by prof
File p r o d u c e d f o r a n a l y s i s
gmon.out
by gprof
have
the
special
hardware
device
called
a BillBoard,
you
can
166
g a i n s a c c e s s to files o n t h e S u n r e l a t i v e t o
the
d i r e c t o r y w h e r e b i n l o a d s t a r t e d . If t h e d i r e c t o r y o n t h e S u n w a s / u s r / c o m m o d o r e /
a m i g a / V 2 4 / e x a m p l e s / D O S a s a b o v e , t h e f i l e n a m e t e s t . l d is all t h a t is n e c e s s a r y .
If y o u c a n n o t r e m e m b e r t h e d i r e c t o r y w h e r e b i n l o a d s t a r t e d , y o u m u s t s p e c i f y
t h e full n a m e . T o s t o p b i n l o a d , d o a " p s " a n d t h e n a " k i l l " o n its P I D . N o t e
t h a t t h e s o f t r e s e t o f t h e c o m p u t e r tells b i n l o a d t o w r i t e a m e s s a g e t o i t s
s t a n d a r d o u t p u t ( t h e d e f a u l t is t h e w i n d o w w h e r e it s t a r t e d ) . If t h e t r a n s f e r
h a n g s , p r e s s C T R L - C at t h e A m i g a t o kill D O W N L O A D . ( S e e S e c t i o n 3 . 2 in t h e
AmigaDOS
User's Manual
i n t h i s b o o k for f u r t h e r i n f o r m a t i o n o n t h e A m i g a D O S
A S C I I files t o t h e A m i g a
via t h e p a r a l l e l p o r t
by
167
If y o u d o n o t g i v e " s e n d " a n y a r g u m e n t s , t h e s t a n d a r d i n p u t is u s e d . T h e
d e f a u l t o u t p u t d e v i c e is /dev/lpO, w h i c h is u s u a l l y c o r r e c t . T o c h a n g e t h e
d e f a u l t o u t p u t , u s e t h e -o a r g u m e n t .
2. O n the A m i g a , type the following:
READ demo
R E A D t h e n r e a d s c h a r a c t e r s f r o m t h e parallel p o r t a n d p l a c e s t h e m i n t h e
file n a m e d " d e m o " .
3. O n c e R E A D has finished, type
demo
to run the program d e m o .
Y o u c a n a l s o d o w n l o a d files serially. T o d o t h i s , f o l l o w t h e s e s t e p s :
1. C o n v e r t t h e B i n a r y L o a d File i n t o a n A S C I I h e x file e n d i n g w i t h Q b y t y p i n g
convert <demo.ld >demo.dl
( w h e r e . d l , b y c o n v e n t i o n , s t a n d s for D o w n L o a d ) . T h e a b o v e r u l e e x i s t s i n
t h e i n c l u d e d m a k e f i l e , m a k e a m i g a . ( S e e t h e AmigaDOS
Manual,
2.
Technical
Reference
Type
tip a m i g a
demo.dl
5 . W h e n t h e R E A D c o m p l e t e s o n t h e A m i g a , t y p e t h e f i l e n a m e " d e m o " to r u n
it.
W A R N I N G : T h e S u n serial l i n k o f t e n h a n g s for n o a p p a r e n t
R e b o o t t h e S u n if t h i s h a p p e n s .
reason.
168
If t h e S u n serial link s h o u l d h a p p e n t o h a n g , r e b o o t t h e S u n , t h e n t y p e
tip
a n d within tip, type
Q
t o g e t t h e R E A D o n t h e A m i g a to c o m p l e t e . O n c e this is d o n e , start a n e w
R E A D and type the following symbols on the Sun:
">
file
to t h e p r o g r a m .
169
is t h e w a y t h a t R E A D a c c e p t s d a t a ) , a n d a w a y o f p u t t i n g t h i s d a t a o u t f r o m a
serial o r p a r a l l e l p o r t .
O n c e y o u h a v e c r e a t e d a s u i t a b l e b i n a r y file, y o u m u s t t r a n s f e r t h i s to t h e
A m i g a u s i n g t h e R E A D c o m m a n d (as d e s c r i b e d in S e c t i o n 1 . 5 . 2 o f t h i s m a n u a l ) . If y o u h a v e t h e A m i g a l i n k e r r u n n i n g o n y o u r c o m p u t e r , t h e n y o u c a n
t r a n s f e r c o m p l e t e b i n a r y l o a d files; o t h e r w i s e , y o u ' l l h a v e t o t r a n s f e r b i n a r y
o b j e c t files i n t h e f o r m a t a c c e p t e d b y A L I N K , a n d t h e n p e r f o r m t h e l i n k s t e p
on the Amiga.
Chapter 2
Calling AmigaDOS
This chapter describes the functions provided b y the A m i g a D O S resident
library. T o h e l p y o u , it p r o v i d e s t h e following: a n e x p l a n a t i o n of t h e s y n t a x , a full
d e s c r i p t i o n o f e a c h f u n c t i o n , a n d a quick r e f e r e n c e card o f t h e available f u n c t i o n s .
2.1
2.2
Syntax
A m i g a D O S Functions
Quick Reference Card
2.1 Syntax
T h e s y n t a x u s e d i n t h i s c h a p t e r s h o w s t h e C f u n c t i o n call f o r e a c h A m i g a D O S
f u n c t i o n a n d t h e c o r r e s p o n d i n g register y o u u s e w h e n y o u p r o g r a m in a s s e m b l e r .
2.1.2 Case
T h e letter c a s e (that i s , l o w e r o r u p p e r c a s e ) I S s i g n i f i c a n t . F o r e x a m p l e , y o u
m u s t e n t e r t h e w o r d " F i l e l n f o B l o c k " w i t h t h e first l e t t e r o f e a c h c o m p o n e n t
word in upper case.
171
CALLING AMIGADOS
2.2.4 Values
All v a l u e s a r e l o n g w o r d s ( t h a t i s , 4 b y t e v a l u e s o r 3 2 b i t s ) . V a l u e s r e f e r r e d to a s
" s t r i n g " are 32-bit pointers to NULL-terminated series of characters.
used
a f t e r " F o r m a t : " . R e s u l t d e s c r i b e s w h a t is r e t u r n e d b y t h e f u n c t i o n ( t h a t i s ,
t h e left of t h e e q u a l s i g n ) . A r g u m e n t d e s c r i b e s w h a t t h e f u n c t i o n e x p e c t s t o
w o r k o n ( t h a t i s , t h e list in p a r e n t h e s e s ) . F i g u r e 2 - A s h o u l d h e l p e x p l a i n t h e
syntax.
Format
of function
result =
Function(argument)
Register
Example
lock =
Register
CreateDir(name)
DO
Dl
AmigaDOS
r e s i d e n t library. E a c h f u n c t i o n is a r r a n g e d a l p h a b e t i c a l l y u n d e r t h e f o l l o w i n g
h e a d i n g s : File H a n d l i n g , P r o c e s s H a n d l i n g , a n d L o a d i n g C o d e . T h e s e h e a d ings indicate the action of the functions they cover. U n d e r each function n a m e ,
t h e r e is a b r i e f d e s c r i p t i o n of t h e f u n c t i o n ' s p u r p o s e , a s p e c i f i c a t i o n o f t h e
f o r m a t a n d t h e r e g i s t e r v a l u e s , a fuller d e s c r i p t i o n o f t h e f u n c t i o n , a n d
an
File Handling
Close
Purpose:
T o c l o s e a file for i n p u t or o u t p u t .
Form:
Close( file )
Dl
172
Argument:
filefile h a n d l e
Description:
T h e file h a n d l e " f i l e " i n d i c a t e s t h e file t h a t C l o s e s h o u l d c l o s e . Y o u o b t a i n t h i s
file h a n d l e a s a r e s u l t o f a call t o O p e n . Y o u m u s t r e m e m b e r t o c l o s e e x p l i c i t l y
all t h e files y o u o p e n in a p r o g r a m . H o w e v e r , y o u s h o u l d n o t c l o s e i n h e r i t e d
file h a n d l e s o p e n e d e l s e w h e r e .
CreateDir
Purpose:
T o create a n e w directory.
Form:
lock
Argument:
name-string
Result:
= CreateDir(
DO
name)
Dl
Description:
C r e a t e D i r c r e a t e s a n e w d i r e c t o r y w i t h t h e n a m e y o u s p e c i f i e d , if p o s s i b l e . It
r e t u r n s a n e r r o r if it fails. R e m e m b e r t h a t A m i g a D O S c a n o n l y c r e a t e d i r e c t o ries o n devices w h i c h support t h e m , for e x a m p l e , disks.
A return of zero m e a n s that A m i g a D O S h a s f o u n d an error (such as: disk
w r i t e p r o t e c t e d ) , y o u s h o u l d t h e n call I o E r r ( ) ; o t h e r w i s e , C r e a t e D i r r e t u r n s a
shared read lock o n t h e n e w directory.
CurrentDir
Purpose:
Form:
Argument:
Result:
Description:
working
DO
Dl
l o c k - p o i n t e r to a l o c k
o l d L o c k - p o i n t e r to a l o c k
DeleteFile
Purpose:
T o d e l e t e a file or d i r e c t o r y .
Form:
success
DO
DeleteFilei
name
Dl
CALLING AMIGADOS
Argument:
n a m e - string
Result:
success - boolean
173
Description:
D e l e t e F i l e a t t e m p t s to d e l e t e t h e file or d i r e c t o r y " n a m e " . It r e t u r n s a n e r r o r if
t h e d e l e t i o n fails. N o t e t h a t y o u m u s t d e l e t e all t h e files w i t h i n a d i r e c t o r y
b e f o r e y o u c a n d e l e t e t h e d i r e c t o r y itself.
DupLock
Purpose:
To duplicate a lock.
Form:
newLock
DO
DupLock(
lock)
Dl
Argument:
l o c k - p o i n t e r to a l o c k
Result:
n e w L o c k - pointer to a lock
Description:
D u p L o c k t a k e s a s h a r e d filing s y s t e m r e a d l o c k a n d r e t u r n s a n o t h e r s h a r e d
r e a d l o c k t o t h e s a m e o b j e c t . It is i m p o s s i b l e to c r e a t e a c o p y o f a w r i t e l o c k .
(For m o r e information on locks, see L O C K . )
Examine
Purpose:
Form:
Argument:
T o e x a m i n e a d i r e c t o r y o r file a s s o c i a t e d w i t h a l o c k .
success = Examine( lock, FilelnfoBlock
)
DO
Dl
D2
lock - pointer to a lock
F i l e l n f o B l o c k - p o i n t e r t o a file i n f o b l o c k
success - boolean
Result:
Description:
E x a m i n e fills in i n f o r m a t i o n in t h e F i l e l n f o B l o c k c o n c e r n i n g t h e file o r d i r e c t o r y
associated with the lock. This information includes the n a m e , size, creation
d a t e , a n d w h e t h e r it is a file or d i r e c t o r y .
N o t e : F i l e l n f o B l o c k m u s t b e l o n g w o r d a l i g n e d . Y o u c a n e n s u r e t h i s in t h e
C l a n g u a g e if y o u u s e A l l o c m e m . ( S e e t h e ROM Kernal Manual
for further
d e t a i l s o n t h e e x e c call A l l o c m e m . )
E x a m i n e g i v e s a r e t u r n c o d e of z e r o of it fails.
ExNext
Purpose:
Form:
174
Argument:
l o c k - p o i n t e r to a l o c k
F i l e l n f o B l o c k - p o i n t e r to a file i n f o b l o c k
Result:
success - boolean
Description:
T h i s r o u t i n e is p a s s e d a l o c k , u s u a l l y a s s o c i a t e d w i t h
a directory,
and
F i l e l n f o B l o c k filled in b y a p r e v i o u s call to E x a m i n e . T h e F i l e l n f o B l o c k c o n t a i n s
i n f o r m a t i o n c o n c e r n i n g t h e first file o r d i r e c t o r y s t o r e d i n t h e d i r e c t o r y a s s o c i ated with the lock. ExNext also modifies the FilelnfoBlock so that s u b s e q u e n t
calls r e t u r n i n f o r m a t i o n a b o u t e a c h f o l l o w i n g e n t r y i n t h e d i r e c t o r y .
E x N e x t g i v e s a r e t u r n c o d e o f z e r o if it fails f o r s o m e r e a s o n . O n e r e a s o n f o r
failure is r e a c h i n g t h e last e n t r y in t h e d i r e c t o r y . H o w e v e r , IoErrQ h o l d s a c o d e
t h a t m a y g i v e m o r e i n f o r m a t i o n o n t h e e x a c t c a u s e of a f a i l u r e . W h e n E x N e x t
f i n i s h e s a f t e r t h e last e n t r y , it r e t u r n s E R R O R
NO
MORE
ENTRIES
S o , f o l l o w t h e s e s t e p s to e x a m i n e a d i r e c t o r y :
1) U s e
Examine
to g e t a F i l e l n f o B l o c k
to
examine.
2) P a s s E x N e x t t h e l o c k r e l a t e d t o t h e d i r e c t o r y a n d t h e F i l e l n f o B l o c k filled in
b y t h e p r e v i o u s call to E x a m i n e .
3) K e e p c a l l i n g E x N e x t u n t i l it fails w i t h t h e e r r o r c o d e h e l d in I o E r r ( ) e q u a l
to E R R O R
NO
MORE
ENTRIES.
4 ) N o t e t h a t if y o u d o n ' t k n o w w h a t y o u a r e e x a m i n i n g , i n s p e c t t h e t y p e
field o f t h e F i l e l n f o B l o c k r e t u r n e d f r o m E x a m i n e t o f i n d o u t w h e t h e r it is a
file or a d i r e c t o r y w h i c h is w o r t h c a l l i n g E x N e x t f o r .
T h e t y p e field in t h e F i l e l n f o B l o c k h a s t w o v a l u e s : if it is n e g a t i v e ,
then
t h e file s y s t e m o b j e c t is a file; if it is p o s i t i v e , t h e n it is a d i r e c t o r y .
Info
Purpose:
Form:
success
DO
Argument:
Result:
Description:
Data
D2
l o c k - p o i n t e r to a l o c k
Info Data - pointer to an Info
success - boolean
Data structure
I n f o f i n d s o u t i n f o r m a t i o n a b o u t a n y d i s k in u s e . " l o c k " r e f e r s t o t h e d i s k , o r
a n y file o n t h e d i s k . I n f o r e t u r n s t h e I n f o
a b o u t t h e size o f t h e d i s k , n u m b e r o f f r e e b l o c k s , a n d a n y soft e r r o r s . N o t e t h a t
Info
175
CALLING AMIGADOS
Input
Form:
file
= Input
()
DO
Result:
file - file h a n d l e
Description:
T o i d e n t i f y t h e p r o g r a m ' s initial i n p u t file h a n d l e , y o u u s e I n p u t . ( T o i d e n t i f y
t h e initial o u t p u t , s e e O U T P U T . )
IoErr
Purpose:
T o r e t u r n extra i n f o r m a t i o n f r o m t h e s y s t e m .
Form:
error
IoErrO
DO
Result:
error - integer
Description:
I/O r o u t i n e s r e t u r n z e r o to i n d i c a t e a n e r r o r . W h e n a n e r r o r o c c u r s , call t h i s
r o u t i n e to f i n d o u t m o r e i n f o r m a t i o n . S o m e r o u t i n e s u s e I o E r r ( ) , f o r e x a m p l e ,
D e v i c e P r o c , to p a s s b a c k a s e c o n d a r y r e s u l t .
Islnteractive
Purpose:
T o d i s c o v e r w h e t h e r a file is c o n n e c t e d t o a v i r t u a l t e r m i n a l or n o t .
Form:
bool
= Islnteractivei
file )
DO
Dl
Argument:
file - file h a n d l e
Result:
bool - boolean
Description:
The function
This indicates
whether
Lock
Purpose:
T o l o c k a d i r e c t o r y or file.
Form:
lock
= Lock( name,
DO
Argument:
Dl
accessMode
D2
name-string
accessMode - integer
Result:
176
Description:
L o c k r e t u r n s , if p o s s i b l e , a filing s y s t e m l o c k o n t h e file or d i r e c t o r y " n a m e " . If
t h e a c c e s s M o d e is A C C E S S
a c c e s s M o d e is A C C E S S .
R E A D , t h e l o c k is a s h a r e d r e a d l o c k ; if t h e
W R I T E , t h e n it is a n e x c l u s i v e w r i t e l o c k . If L O C K fails
s o t h a t , if y o u w a n t to t e s t to s e e if a file e x i s t s , y o u s h o u l d
an
use
L o c k . O f c o u r s e , o n c e y o u ' v e f o u n d t h a t it e x i s t s , y o u h a v e t o u s e O p e n t o
o p e n it.
Open
Purpose:
T o o p e n a file for i n p u t o r o u t p u t
Form:
file
DO
Open(
name,
Dl
accessMode)
D2
Argument:
Result:
file - file h a n d l e
Description:
O p e n o p e n s " n a m e " a n d r e t u r n s a file h a n d l e . If t h e a c c e s s M o d e is M O D E
O L D F I L E ( = 1 0 0 5 ) , O P E N o p e n s a n e x i s t i n g file f o r r e a d i n g or w r i t i n g . H o w e v e r , O p e n c r e a t e s a n e w file for w r i t i n g if t h e v a l u e is M O D E
NEWFILE
User's Manual
f o r s o m e r e a s o n , it r e t u r n s t h e v a l u e z e r o (0). In t h i s c a s e , a call t o t h e r o u t i n e
IoErr() supplies a secondary error c o d e .
F o r t e s t i n g t o s e e if a file e x i s t s , s e e L O C K .
Output
Form:
file
Output()
DO
Result:
file - file h a n d l e
Description:
T o i d e n t i f y t h e p r o g r a m ' s initial o u t p u t file h a n d l e , y o u u s e O u t p u t .
i d e n t i f y t h e initial i n p u t , s e e I N P U T . )
(To
177
CALLING AMIGADOS
ParentDir
Purpose:
T o o b t a i n t h e p a r e n t o f a d i r e c t o r y or file.
Form:
Lock
= ParentDir(
DO
lock )
Dl
Argument:
l o c k - p o i n t e r to a l o c k
Result:
l o c k - p o i n t e r to a l o c k
Description:
T h i s f u n c t i o n r e t u r n s a l o c k a s s o c i a t e d w i t h t h e p a r e n t d i r e c t o r y o f a file or
d i r e c t o r y . T h a t i s , P a r e n t D i r t a k e s a l o c k a s s o c i a t e d w i t h a file or d i r e c t o r y a n d
r e t u r n s t h e l o c k o f its p a r e n t d i r e c t o r y .
N o t e : T h e r e s u l t o f P a r e n t D i r m a y b e z e r o (0) f o r t h e r o o t o f t h e c u r r e n t filing
system.
Read
Purpose:
T o r e a d b y t e s o f d a t a f r o m a file.
Form:
actualLength
= Read( file,
DO
Argument:
Dl
buffer,
D2
length
D3
file - file h a n d l e
buffer - pointer to buffer
length - integer
Result:
actualLength - integer
Description:
Y o u can c o p y data w i t h a combination of R e a d a n d Write. R e a d r e a d s bytes of
i n f o r m a t i o n f r o m a n o p e n e d file ( r e p r e s e n t e d h e r e b y t h e a r g u m e n t " f i l e " ) i n t o
t h e m e m o r y b u f f e r i n d i c a t e d . R e a d a t t e m p t s to r e a d a s m a n y b y t e s a s fit i n t o
t h e b u f f e r a s i n d i c a t e d b y t h e v a l u e of l e n g t h . Y o u s h o u l d a l w a y s m a k e s u r e
t h a t t h e v a l u e y o u g i v e a s t h e l e n g t h really d o e s r e p r e s e n t t h e s i z e o f t h e
b u f f e r . R e a d m a y r e t u r n a r e s u l t i n d i c a t i n g t h a t it r e a d l e s s b y t e s t h a n y o u
r e q u e s t e d , f o r e x a m p l e , w h e n r e a d i n g a line o f d a t a t h a t y o u t y p e d at t h e
terminal.
T h e v a l u e r e t u r n e d is t h e l e n g t h o f t h e i n f o r m a t i o n a c t u a l l y r e a d . T h a t is t o
s a y , w h e n " a c t u a l L e n g t h " is g r e a t e r t h a n z e r o , t h e v a l u e o f " a c t u a l L e n g t h " is
t h e n u m b e r of characters r e a d . A value of zero m e a n s that end-of-file h a s b e e n
r e a c h e d . Errors are indicated b y a value of - 1 . R e a d from t h e c o n s o l e returns a
v a l u e w h e n a r e t u r n is f o u n d o r t h e b u f f e r is full.
A call to R e a d a l s o m o d i f i e s or c h a n g e s t h e v a l u e o f I o E r r ( ) . I o E r r ( ) g i v e s
m o r e i n f o r m a t i o n a b o u t a n e r r o r (for e x a m p l e , a c t u a l L e n g t h e q u a l s -1) w h e n it
is c a l l e d .
178
Rename
Purpose:
T o r e n a m e a d i r e c t o r y or file.
Form:
success
= Rename(
DO
Argument,
oldName,
Dl
newName)
D2
o l d N a m e - string
n e w N a m e - string
Result:
success - boolean
Description:
R e n a m e a t t e m p t s to r e n a m e t h e file or d i r e c t o r y s p e c i f i e d as " o l d N a m e " w i t h
t h e n a m e " n e w N a m e " . If t h e file o r d i r e c t o r y " n e w N a m e " e x i s t s , R e n a m e fails
and R e n a m e returns an error.
Both the " o l d N a m e " and the " n e w N a m e " can be complex filenames containi n g a d i r e c t o r y s p e c i f i c a t i o n . In t h i s c a s e , t h e file will b e m o v e d f r o m
one
d i r e c t o r y to a n o t h e r . H o w e v e r , t h e d e s t i n a t i o n d i r e c t o r y m u s t e x i s t b e f o r e y o u
do this.
N o t e : It is i m p o s s i b l e to r e n a m e a file f r o m o n e v o l u m e to a n o t h e r .
Seek
Purpose:
T o m o v e t o a logical p o s i t i o n in a file.
Form:
oldPosition
Seek( file,
DO
Argument:
Dl
position,
D2
mode
D3
file - file h a n d l e
position - integer
Result:
Description:
m o d e - integer
oldPosition - integer
CALLING AMIGADOS
179
SetComment
Purpose:
To set a c o m m e n t .
Form:
Success
SetCommenH
name,
DO
Argument:
Dl
comment)
D2
n a m e - file n a m e
c o m m e n t - pointer to a string
Result:
success - boolean
Description:
S e t C o m m e n t s e t s a c o m m e n t o n a file o r d i r e c t o r y . T h e c o m m e n t is a p o i n t e r to
a n u l l - t e r m i n a t e d s t r i n g of u p to 8 0 c h a r a c t e r s .
SetProtection
Purpose:
T o s e t file, or d i r e c t o r y , p r o t e c t i o n .
Form:
Success
SetProtection(
name,
mask )
Dl
D2
DO
Argument:
n a m e - file n a m e
mask - the protection mask required
Result:
success - boolean
Description:
S e t P r o t e c t i o n s e t s t h e p r o t e c t i o n a t t r i b u t e s o n a file o r d i r e c t o r y . T h e
lower
f o u r bits o f t h e m a s k are a s f o l l o w s :
b i t 3 : if 1 t h e n r e a d s n o t a l l o w e d , e l s e r e a d s a l l o w e d .
bit 2 : if 1 t h e n w r i t e s n o t a l l o w e d , e l s e w r i t e s a l l o w e d .
bit 1: if 1 t h e n e x e c u t i o n n o t a l l o w e d , e l s e e x e c u t i o n a l l o w e d .
bit 0 : if 1 t h e n d e l e t i o n n o t a l l o w e d , e l s e d e l e t i o n a l l o w e d .
Bits 31-4 R e s e r v e d .
O n l y d e l e t e is c h e c k e d f o r in t h e c u r r e n t r e l e a s e o f A m i g a D O S . R a t h e r t h a n
r e f e r r i n g to bits b y n u m b e r y o u s h o u l d u s e t h e d e f i n i t i o n s in " i n c l u d e / l i b r a r i e s /
dos.h".
UnLock
Purpose:
T o u n l o c k a d i r e c t o r y or file.
Form:
Unlock(
lock)
Dl
Argument:
l o c k - p o i n t e r to a l o c k
180
Description:
UnLock
removes
DupLock,
or
CreateDir.
WaitForChar
Purpose:
T o i n d i c a t e w h e t h e r c h a r a c t e r s a r r i v e w i t h i n a t i m e limit o r n o t .
Form:
bool
WaitForCharf
DO
Argument:
file,
timeout)
Dl
D2
file - file h a n d l e
timeout - integer
Result:
bool - boolean
Description:
If a c h a r a c t e r is a v a i l a b l e t o b e r e a d f r o m t h e file a s s o c i a t e d w i t h t h e h a n d l e
" f i l e " w i t h i n a c e r t a i n t i m e , i n d i c a t e d b y " t i m e o u t " , W a i t F o r C h a r r e t u r n s -1
( T R U E ) ; o t h e r w i s e , it r e t u r n s 0 ( F A L S E ) . If a c h a r a c t e r is a v a i l a b l e , y o u c a n
u s e R e a d t o r e a d i t . N o t e t h a t W a i t F o r C h a r is o n l y v a l i d w h e n
the
I/O
s t r e a m s a r e c o n n e c t e d t o a v i r t u a l t e r m i n a l d e v i c e . " T i m e o u t " is s p e c i f i e d in
microseconds.
Write
Purpose:
T o w r i t e b y t e s o f d a t a t o a file.
Form:
returnedLength
DO
Argument:
Write( file,
Dl
buffer,
length
D2
D3
file - file h a n d l e
buffer - pointer to buffer
length - integer
Result:
returnedLength - integer
Description:
Y o u can c o p y data with a combination of R e a d a n d Write. Write writes b y t e s of
d a t a to t h e o p e n e d file " f i l e " ; " l e n g t h " r e f e r s t o t h e a c t u a l l e n g t h o f d a t a to b e
t r a n s f e r r e d ; " b u f f e r " r e f e r s to t h e b u f f e r s i z e .
Write returns a value that indicates t h e length of information actually writt e n . T h a t is to s a y , w h e n " l e n g t h " is g r e a t e r t h a n z e r o , t h e v a l u e o f " l e n g t h " is
t h e n u m b e r o f c h a r a c t e r s w r i t t e n . A v a l u e o f -1 i n d i c a t e s a n e r r o r . T h e u s e r o f
t h i s call m u s t a l w a y s c h e c k f o r a n e r r o r r e t u r n w h i c h m a y ,
i n d i c a t e t h a t t h e d i s k is full.
for
example,
CALLING AMIGADOS
181
Process Handling
CreateProc
Purpose:
T o create a n e w process.
Form:
process
CreateProc(
DO
Argument:
name,
Dl
pri, segment,
D2
stackSize
D3
D4
n a m e - string
pri - integer
s e g m e n t - p o i n t e r to a s e g m e n t
stackSize - integer
Result:
Description:
C r e a t e P r o c c r e a t e s a p r o c e s s w i t h t h e n a m e " n a m e " . T h a t is t o s a y , C r e a t e P r o c
allocates a process control structure from the free m e m o r y area a n d t h e n
i n i t i a l i z e s it.
C r e a t e P r o c t a k e s a s e g m e n t list as t h e a r g u m e n t " s e g m e n t " . ( S e e a l s o u n d e r
L O A D S E G a n d U N L O A D S E G . ) T h i s s e g m e n t list r e p r e s e n t s t h e s e c t i o n o f
c o d e t h a t y o u i n t e n d to r u n a s a n e w p r o c e s s . C r e a t e P r o c e n t e r s t h e c o d e a t t h e
first s e g m e n t in t h e s e g m e n t list, w h i c h s h o u l d c o n t a i n s u i t a b l e i n i t i a l i z a t i o n
c o d e or a j u m p to s u c h .
" S t a c k S i z e " r e p r e s e n t s t h e size o f t h e r o o t s t a c k in b y t e s w h e n C r e a t e P r o c
activates the process. " P r i " specifies the required priority of t h e n e w p r o c e s s .
T h e r e s u l t is t h e p r o c e s s i d e n t i f i e r o f t h e n e w p r o c e s s , o r z e r o if t h e r o u t i n e
failed.
T h e argument " n a m e " specifies the process n a m e .
A zero return code implies an error of s o m e kind.
DateStamp
Purpose:
Form:
Argument:
Description:
T o o b t a i n t h e d a t e a n d t i m e in i n t e r n a l f o r m a t .
v: = DateStampi
v )
v - pointer
D a t e S t a m p t a k e s a v e c t o r o f t h r e e l o n g w o r d s t h a t is s e t t o t h e c u r r e n t t i m e .
T h e first e l e m e n t in t h e v e c t o r is a c o u n t o f t h e n u m b e r o f d a y s . T h e s e c o n d
e l e m e n t is t h e n u m b e r o f m i n u t e s e l a p s e d in t h e d a y . T h e t h i r d is t h e n u m b e r
o f ticks e l a p s e d in t h e c u r r e n t m i n u t e . A tick h a p p e n s 5 0 t i m e s a s e c o n d .
D a t e S t a m p e n s u r e s t h a t t h e d a y a n d m i n u t e a r e c o n s i s t e n t . All t h r e e e l e m e n t s
a r e z e r o if t h e d a t e is u n s e t . D a t e S t a m p c u r r e n t l y o n l y r e t u r n s e v e n m u l t i p l e s
o f 5 0 t i c k s . T h e r e f o r e t h e t i m e y o u g e t is a l w a y s a n i n t e g r a l n u m b e r o f s e c o n d s .
182
Delay
Purpose:
T o d e l a y a p r o c e s s for a s p e c i f i e d t i m e .
Form:
Delay(
timeout)
Dl
Argument:
timeout - integer
Description:
T h e f u n c t i o n D e l a y t a k e s a n a r g u m e n t " t i m e o u t " ; " t i m e o u t " a l l o w s y o u to
s p e c i f y h o w l o n g t h e p r o c e s s s h o u l d w a i t i n t i c k s (50 p e r s e c o n d ) .
DeviceProc
Purpose:
T o r e t u r n t h e p r o c e s s i d e n t i f i e r of t h e p r o c e s s h a n d l i n g t h a t I / O .
Form:
process
DeviceProci
DO
name
Dl
Argument:
n a m e - string
Result:
Description:
D e v i c e P r o c r e t u r n s the p r o c e s s identifier of the p r o c e s s that h a n d l e s
the
the
h a n d l e r p r o c e s s w h e r e t h e s y s t e m s h o u l d s e n d its m e s s a g e s .
Exit
Purpose:
T o exit f r o m a p r o g r a m .
Form:
Exit( returnCode
Dl
Argument:
returnCode - integer
Description:
Exit a c t s d i f f e r e n t l y d e p e n d i n g o n w h e t h e r y o u a r e r u n n i n g a p r o g r a m u n d e r a
C L I or n o t . If y o u r u n , as a c o m m a n d u n d e r a C L I , a p r o g r a m t h a t calls Exit,
t h e c o m m a n d f i n i s h e s a n d c o n t r o l r e v e r t s to t h e C L I . Exit t h e n i n t e r p r e t s t h e
argument " r e t u r n C o d e " as the return code from the program.
If y o u
as a distinct process,
Exit deletes t h e
process
a n d r e l e a s e s t h e s p a c e a s s o c i a t e d w i t h t h e s t a c k , s e g m e n t list, a n d p r o c e s s
structure.
CALLING AMIGADOS
183
Loading Code
Execute
Purpose:
Form:
Argument:
Result:
Description:
input,
D2
output)
D3
T h i s f u n c t i o n t a k e s a string ( c o m m a n d S t r i n g ) t h a t s p e c i f i e s a C L I c o m m a n d
a n d a r g u m e n t s , a n d a t t e m p t s to e x e c u t e it. T h e C L I s t r i n g c a n c o n t a i n a n y
v a l i d i n p u t t h a t y o u c o u l d t y p e directly at a C L I , i n c l u d i n g i n p u t a n d o u t p u t
indirection using > and < .
T h e i n p u t file h a n d l e will n o r m a l l y b e z e r o , a n d in t h i s c a s e t h e E X E C U T E
c o m m a n d will p e r f o r m w h a t e v e r w a s r e q u e s t e d in t h e c o m m a n d S t r i n g a n d
t h e n r e t u r n . If t h e i n p u t file h a n d l e is n o n z e r o t h e n after t h e ( p o s s i b l y n u l l )
c o m m a n d S t r i n g is p e r f o r m e d s u b s e q u e n t i n p u t is r e a d f r o m t h e s p e c i f i e d i n p u t
file h a n d l e u n t i l e n d of file is r e a c h e d .
I n m o s t c a s e s t h e o u t p u t file h a n d l e m u s t b e p r o v i d e d , a n d will b e u s e d b y
t h e C L I c o m m a n d s as t h e i r o u t p u t s t r e a m u n l e s s r e d i r e c t i o n w a s s p e c i f i e d . If
t h e o u t p u t file h a n d l e is s e t to z e r o t h e n t h e c u r r e n t w i n d o w , n o r m a l l y
s p e c i f i e d a s *, is u s e d . N o t e t h a t p r o g r a m s r u n n i n g u n d e r t h e W o r k b e n c h d o
not normally have a current window.
T h e E x e c u t e f u n c t i o n m a y also b e u s e d to c r e a t e a n e w i n t e r a c t i v e C L I
p r o c e s s j u s t like t h o s e c r e a t e d w i t h t h e N E W C L I f u n c t i o n . In o r d e r to d o t h i s
y o u s h o u l d call E x e c u t e w i t h a n e m p t y c o m m a n d S t r i n g , a n d p a s s a file h a n d l e
r e l a t i n g t o a n e w w i n d o w a s t h e i n p u t file h a n d l e . T h e o u t p u t file h a n d l e
s h o u l d b e s e t to z e r o . T h e C L I will r e a d c o m m a n d s f r o m t h e n e w w i n d o w , a n d
will u s e t h e s a m e w i n d o w for o u t p u t . T h i s n e w C L I w i n d o w c a n o n l y b e
terminated b y using the E N D C L I c o m m a n d . For this c o m m a n d to w o r k the
p r o g r a m C : R U N m u s t b e p r e s e n t in C : .
LoadSeg
Purpose:
Form:
Argument:
DO
n a m e - string
Dl
184
Result:
s e g m e n t - p o i n t e r to a s e g m e n t
Description:
T h e file " n a m e " is a l o a d m o d u l e p r o d u c e d b y t h e l i n k e r . L o a d S e g t a k e s t h i s
a n d scatter-loads the code s e g m e n t s into m e m o r y ,
chaining the
segments
t o g e t h e r o n t h e i r first w o r d s . It r e c o g n i z e s a z e r o as i n d i c a t i n g t h e e n d o f t h e
chain.
If a n e r r o r o c c u r s , L o a d S e g u n l o a d s a n y l o a d e d b l o c k s a n d r e t u r n s a f a l s e
(zero) result.
If all g o e s w e l l ( t h a t i s , L o a d S e g h a s l o a d e d t h e m o d u l e c o r r e c t l y ) ,
then
L o a d s e g r e t u r n s a p o i n t e r to t h e b e g i n n i n g o f t h e list or b l o c k s . O n c e y o u h a v e
f i n i s h e d w i t h t h e l o a d e d c o d e , y o u c a n u n l o a d it w i t h a call t o U n L o a d S e g . ( F o r
using the loaded code, see C R E A T E P R O C . )
UnLoadSeg
Purpose:
Form:
UnLoadSeg(
Argument:
s e g m e n t - p o i n t e r to a s e g m e n t
segment)
Dl
Description:
U n L o a d S e g unloads the s e g m e n t identifier that was returned b y
LoadSeg.
t o c l o s e a file f o r i n p u t o r o u t p u t .
CreateDir
to create a n e w directory.
CurrentDir
to m a k e a d i r e c t o r y a s s o c i a t e d w i t h a l o c k t h e c u r r e n t w o r k i n g
directory.
DeleteFile
to d e l e t e a file or d i r e c t o r y .
DupLock
to d u p l i c a t e a l o c k .
Examine
to e x a m i n e a d i r e c t o r y o r file a s s o c i a t e d w i t h a l o c k .
ExNext
to e x a m i n e t h e n e x t e n t r y i n a d i r e c t o r y .
Info
to r e t u r n i n f o r m a t i o n a b o u t t h e d i s k .
Input
to i d e n t i f y t h e initial i n p u t file h a n d l e .
IoErr
t o r e t u r n extra i n f o r m a t i o n f r o m t h e s y s t e m .
Islnteractive
t o d i s c o v e r w h e t h e r a file is c o n n e c t e d t o a v i r t u a l
or n o t .
Lock
to l o c k a file or d i r e c t o r y .
terminal
CALLING AMIGADOS
185
Open
Output
ParentDir
to o p e n a file for i n p u t or o u t p u t .
to i d e n t i f y t h e initial o u t p u t file h a n d l e .
to o b t a i n t h e p a r e n t of a d i r e c t o r y or file.
Read
Rename
Seek
SetComment
SetProtection
Unlock
to
to
to
to
to
to
WaitForChar
to i n d i c a t e w h e t h e r c h a r a c t e r s arrive w i t h i n a t i m e l i m i t o r
not.
Write
t o w r i t e b y t e s of d a t a to a file.
r e a d b y t e s o f d a t a f r o m a file.
r e n a m e a file o r d i r e c t o r y .
m o v e to a logical p o s i t i o n in a file.
set a c o m m e n t .
set file, o r d i r e c t o r y , p r o t e c t i o n .
u n l o c k a file or d i r e c t o r y .
Process Handling
CreateProc
DateStamp
Delay
DeviceProc
Exit
to
to
to
to
to
create a n e w process.
obtain the date a n d time in internal format.
d e l a y a p r o c e s s for a s p e c i f i e d time.
r e t u r n t h e p r o c e s s i d e n t i f i e r of t h e p r o c e s s h a n d l i n g t h a t I / O .
exit f r o m a p r o g r a m .
Loading Code
Execute
LoadSeg
to e x e c u t e a C L I c o m m a n d .
to l o a d a l o a d m o d u l e i n t o m e m o r y .
UnloadSeg
to u n l o a d a s e g m e n t p r e v i o u s l y l o a d e d b y L O A D S E G .
Chapter 3
T h i s c h a p t e r d e s c r i b e s t h e A m i g a D O S M a c r o A s s e m b l e r . It g i v e s a b r i e f i n t r o d u c t i o n t o t h e 6 8 0 0 0 m i c r o c h i p . T h i s c h a p t e r is i n t e n d e d f o r t h e r e a d e r w h o is
acquainted with an assembly language on another computer.
3.1
3.2
3.3
3.3.1
3.3.2
3.3.2.1
3.3.2.2
3.3.2.3
3.3.2.4
3.3.2.5
3.4
3.4.1
3.4.2
3.4.3
3.4.4
3.5
3.6
3.7
I n t r o d u c t i o n to t h e 6 8 0 0 0 M i c r o c h i p
Calling the Assembler
Program Encoding
Comments
Executable Instructions
Label Field
Local Labels
O p c o d e Field
O p e r a n d Field
C o m m e n t Field
Expressions
Operators
O p e r a n d T y p e s for Operators
Symbols
Numbers
Addressing Modes
Variants on Instruction Types
Directives
187
distinct
r e g i s t e r s : t h e s y s t e m s t a c k p o i n t e r a v a i l a b l e in s u p e r v i s o r m o d e a n d t h e u s e r
s t a c k p o i n t e r a v a i l a b l e in u s e r m o d e .
T h e m a i n m e m o r y c o n s i s t s o f a n u m b e r of b y t e s o f m e m o r y . E a c h b y t e h a s
a n i d e n t i f y i n g n u m b e r c a l l e d its a d d r e s s . M e m o r y is u s u a l l y ( b u t n o t a l w a y s )
a r r a n g e d s o t h a t its b y t e s h a v e a d d r e s s e s 0 , 1 , 2 , . . ., N - 2 , N - l w h e r e t h e r e a r e
N b y t e s o f m e m o r y in total. T h e size o f m e m o r y t h a t y o u c a n d i r e c t l y a c c e s s is
v e r y l a r g e u p to 16 m i l l i o n b y t e s . T h e 6 8 0 0 0 c a n p e r f o r m o p e r a t i o n s o n b y t e s ,
w o r d s , or l o n g w o r d s o f m e m o r y . A w o r d is t w o c o n s e c u t i v e b y t e s . I n a w o r d ,
t h e first b y t e h a s a n e v e n a d d r e s s . A l o n g w o r d is f o u r c o n s e c u t i v e b y t e s a l s o
s t a r t i n g a t a n e v e n a d d r e s s . T h e a d d r e s s o f a l o n g w o r d is t h e e v e n a d d r e s s o f
its l o w e s t n u m b e r e d first b y t e .
A s well as h o l d i n g items of data b e i n g m a n i p u l a t e d b y t h e c o m p u t e r , t h e
m a i n m e m o r y a l s o h o l d s t h e i n s t r u c t i o n s t h a t tell t h e c o m p u t e r w h a t to d o .
E a c h instruction occupies from o n e to 5 w o r d s , consisting of an o p e r a t i o n w o r d
b e t w e e n zero and four operand w o r d s . T h e operation w o r d specifies
what
a c t i o n is to b e p e r f o r m e d ( a n d i m p l i c i t l y h o w m a n y w o r d s t h e r e a r e i n t h e
w h o l e i n s t r u c t i o n ) . T h e o p e r a n d w o r d s i n d i c a t e w h e r e in t h e r e g i s t e r s or m a i n
m e m o r y a r e t h e i t e m s to b e m a n i p u l a t e d , a n d w h e r e t h e r e s u l t s h o u l d b e
placed.
T h e a s s e m b l e r u s u a l l y e x e c u t e s i n s t r u c t i o n s o n e at a t i m e in t h e o r d e r t h a t
t h e y o c c u r i n m e m o r y , like t h e w a y y o u f o l l o w t h e s t e p s i n a r e c i p e o r p l a y t h e
n o t e s in a p i e c e o f w r i t t e n m u s i c . T h e r e is a s p e c i a l r e g i s t e r c a l l e d t h e p r o g r a m
c o u n t e r ( P C ) w h i c h y o u u s e to h o l d t h e a d d r e s s o f t h e i n s t r u c t i o n y o u w a n t t h e
a s s e m b l e r to e x e c u t e n e x t . S o m e i n s t r u c t i o n s , c a l l e d j u m p s o r b r a n c h e s , u p s e t
the usual order, and force the assembler to continue executing the instruction
at a s p e c i f i c a d d r e s s . T h i s lets t h e c o m p u t e r p e r f o r m a n a c t i o n r e p e a t e d l y , o r
d o different things d e p e n d i n g o n the values of data items.
T o r e m e m b e r particular things about the state of the c o m p u t e r , y o u can u s e
o n e other special register called the status register (SR).
188
the
a s s e m b l e r s h o u l d s e a r c h for I N C L U D E d f i l e s . T h e a s s e m b l e r initially s e a r c h e s
t h e c u r r e n t d i r e c t o r y b e f o r e a n y o t h e r s . T h u s a n y file t h a t y o u I N C L U D E i n a
p r o g r a m m u s t b e in t h e c u r r e n t d i r e c t o r y , or i n o n e o f t h e d i r e c t o r i e s l i s t e d in
t h e -i list. F o r i n s t a n c e , if t h e p r o g r a m " f r e d " I N C L U D E S , a p a r t f r o m files i n t h e
c u r r e n t d i r e c t o r y , a file f r o m t h e d i r e c t o r y " i n t r n l / i n c l " , a file f r o m t h e d i r e c t o r y
" i n c l u d e / a s m " , a n d a file f r o m t h e d i r e c t o r y " e x t r n l / i n c l " , y o u c a n g i v e t h e -i
d i r e c t o r y list i n t h e s e t h r e e w a y s :
189
a s s e m f r e d -i i n t r n l / i n c l , i n c l u d e / a s m , e x t r n l / i n c l
a s s e m f r e d -i m t r n l / i n c l + I n c l u d e / a s m + e x t r n l / l n c l
a s s e m f r e d -i " i n t r n l / i n c l i n c l u d e / a s m e x t r n l / i n c l "
o r , b y u s i n g t h e s p a c e s e p a r a t o r o n t h e S u n u n d e r U n i x , like t h i s
a s s e m f r e d -i V ' i n t r n l / i n c l i n c l u d e / a s m e x t r n l / i n c l V
T h e -c k e y w o r d a l l o w s y o u to p a s s c e r t a i n o p t i o n s t o t h e a s s e m b l e r .
Each
o p t i o n c o n s i s t s o f a s i n g l e c h a r a c t e r (in e i t h e r u p p e r or l o w e r c a s e ) , p o s s i b l y
followed immediately b y a n u m b e r . Valid options follow h e r e :
S
p r o d u c e s a s y m b o l d u m p a s a p a r t o f t h e o b j e c t file.
i n h i b i t s t h e d u m p i n g o f local l a b e l s as p a r t o f a s y m b o l d u m p . ( F o r C
p r o g r a m m e r s , a n y l a b e l b e g i n n i n g w i t h a p e r i o d is c o n s i d e r e d a l o c a l
label.)
i g n o r e s t h e d i s t i n c t i o n b e t w e e n u p p e r a n d l o w e r c a s e in l a b e l s .
p r o d u c e s a c r o s s - r e f e r e n c e t a b l e at t h e e n d o f t h e l i s t i n g file.
Examples
a s s e m f r e d . a s m -o fred.o
a s s e m b l e s t h e file " f r e d . a s m " a n d p r o d u c e s a n o b j e c t m o d u l e i n t h e
fred.o.
file
a s s e m f r e d . a s m -o f r e d . o -1 f r e d . 1st
a s s e m b l e s t h e file f r e d . a s m , p r o d u c e s a n o b j e c t m o d u l e i n t h e file f r e d . o , a n d
p r o d u c e s a listing file in " f r e d . 1 s t " .
190
3.3.1 Comments
To introduce c o m m e n t s into the p r o g r a m , you can u s e three different m e t h o d s :
1. T y p e a s e m i c o l o n (;) a n y w h e r e o n a line a n d f o l l o w it w i t h t h e text of t h e
c o m m e n t . For example,
C M P A . L A l , A2 ; A r e t h e p o i n t e r s e q u a l ?
2 . T y p e a n a s t e r i s k (*) in c o l u m n o n e of a line a n d f o l l o w it w i t h t h e text of t h e
comment. For example,
* This entire line is a c o m m e n t
3 . F o l l o w a n y c o m p l e t e i n s t r u c t i o n o r directive w i t h at l e a s t o n e s p a c e a n d
s o m e text. F o r e x a m p l e ,
M O V E Q # I O , D O p l a c e i n i t i a l v a l u e i n DO
In addition,
note
t h a t all b l a n k l i n e s
are
treated by
the
assembler
as
c o m m e n t lines.
[<operand>[,<operand>]...[<comment>]
T o s e p a r a t e e a c h field f r o m t h e n e x t , p r e s s t h e S P A C E B A R or T A B k e y . T h i s
produces a separator character. Y o u m a y use m o r e than one space to separate
fields.
3.3.2.1 Label Field
A label is a u s e r s y m b o l , o r p r o g r a m m e r - d e f i n e d n a m e , t h a t e i t h e r
a) S t a r t s i n t h e first c o l u m n a n d is s e p a r a t e d f r o m t h e n e x t field b y at l e a s t o n e
space, or
b ) S t a r t s in a n y c o l u m n , a n d is f o l l o w e d i m m e d i a t e l y w i t h a c o l o n (:).
If a label is p r e s e n t , t h e n it m u s t b e t h e first n o n b l a n k i t e m o n t h e l i n e . T h e
a s s e m b l e r a s s i g n s t h e v a l u e a n d t y p e of t h e p r o g r a m c o u n t e r , t h a t i s , t h e
m e m o r y a d d r e s s o f t h e first b y t e of t h e i n s t r u c t i o n or d a t a b e i n g r e f e r e n c e d , to
t h e l a b e l . L a b e l s a r e a l l o w e d o n all i n s t r u c t i o n s , a n d o n s o m e d i r e c t i v e s , or
191
Local
Labels
specification.
T h e y t a k e t h e f o r m n n n $ a n d are o n l y valid b e t w e e n a n y p r o p e r ( n a m e d ) l a b e l s .
T h u s , in this example code s e g m e n t
Labels
Opcodes
Operands
FOO:
MOVE.L
D6,D0
1$:
MOVE.B
(A0) + ,(A1) +
DBRA
D0,1$
MOVEQ
#20,D0
TRAP
#4
BAA:
t h e l a b e l 1$ is o n l y a v a i l a b l e f r o m t h e l i n e f o l l o w i n g t h e o n e l a b e l l e d F O O t o t h e
l i n e b e f o r e t h e o n e l a b e l l e d B A A . I n this c a s e , y o u c o u l d t h e n u s e t h e l a b e l 1$
in a d i f f e r e n t s c o p e e l s e w h e r e i n t h e p r o g r a m .
3 . 3 . 2 . 3 Opcode
Field
T h e O p c o d e field f o l l o w s t h e L a b e l field a n d is s e p a r a t e d f r o m it b y at l e a s t
o n e s p a c e . E n t r i e s in t h i s field a r e o f t h r e e t y p e s .
1. T h e M C 6 8 0 0 0 o p e r a t i o n c o d e s , as d e f i n e d in t h e MC68000
2.
User
Manual.
Assembler Directives.
3. Macro invocations.
T o enter instructions a n d directives that can operate o n m o r e t h a n o n e data
s i z e , y o u u s e a n o p t i o n a l S i z e - S p e c i f i e r s u b f i e l d , w h i c h is s e p a r a t e d f r o m t h e
o p c o d e b y t h e p e r i o d (.) c h a r a c t e r . P o s s i b l e size s p e c i f i e r s a r e a s f o l l o w s :
B - B y t e - s i z e d d a t a (8 b i t s )
W - W o r d - s i z e d d a t a (16 bits)
L - L o n g W o r d - s i z e d d a t a (32 b i t s )
or L o n g Branch specifier
S - Short B r a n c h specifier
T h e size s p e c i f i e r m u s t m a t c h w i t h t h e i n s t r u c t i o n or d i r e c t i v e t y p e t h a t y o u
use.
3.3.2.4
Operand
Field
If p r e s e n t , t h e o p e r a n d field c o n t a i n s o n e or m o r e o p e r a n d s to t h e i n s t r u c -
192
t i o n or d i r e c t i v e , a n d m u s t b e s e p a r a t e d f r o m it b y at l e a s t o n e s p a c e . W h e n
you h a v e t w o or m o r e o p e r a n d s in the field, y o u m u s t separate t h e m with a
c o m m a (,). T h e o p e r a n d field t e r m i n a t e s w i t h a s p a c e o r n e w l i n e c h a r a c t e r (a
n e w l i n e c h a r a c t e r is w h a t t h e a s s e m b l e r r e c e i v e s w h e n y o u p r e s s R E T U R N ) , s o
you must not use spaces between operands.
3 . 3 . 2 . 5 Comment
Field
3.4 Expressions
A n e x p r e s s i o n is a c o m b i n a t i o n o f s y m b o l s , c o n s t a n t s , a l g e b r a i c o p e r a t o r s , a n d
p a r e n t h e s e s t h a t y o u c a n u s e t o s p e c i f y t h e o p e r a n d field t o i n s t r u c t i o n s or
d i r e c t i v e s . Y o u m a y i n c l u d e relative s y m b o l s i n e x p r e s s i o n s , b u t t h e y c a n o n l y
b e operated o n b y a subset of t h e operators.
3.4.1 Operators
T h e a v a i l a b l e o p e r a t o r s a r e listed b e l o w i n o r d e r o f p r e c e d e n c e .
1. U n a r y M i n u s , L o g i c a l N O T ( - a n d " )
2. Lshift, Rshift
( a n d )
3 . L o g i c a l A N D , L o g i c a l O R ( & a n d !)
4 . M u l t i p l y , D i v i d e (* a n d / )
5. A d d , Subtract ( +
and - )
in
represents
r e l a t i v e s y m b o l s . T h e t a b l e s h o w s all t h e p o s s i b l e o p e r a t o r / o p e r a n d c o m b i n a tions,
with
the type
of t h e resulting v a l u e ,
"x"
indicates
an
error.
an
The
absolute
193
Operands
Operators
A op A
R op R
A op R
R op A
&
3.4.3 Symbols
A s y m b o l is a s t r i n g o f u p to 3 0 c h a r a c t e r s . T h e first c h a r a c t e r o f a s y m b o l m u s t
b e o n e of t h e following:
A n a l p h a b e t i c c h a r a c t e r , t h a t i s , a t h r o u g h z , or A t h r o u g h Z .
An underscore (
).
A p e r i o d (.).
T h e r e s t o f t h e c h a r a c t e r s in t h e s t r i n g c a n b e a n y o f t h e s e c h a r a c t e r s o r a l s o
n u m e r i c (0 t h r o u g h 9 ) . I n all s y m b o l s , t h e l o w e r c a s e c h a r a c t e r s ( a - z ) a r e
not
truncates
t h e m to 3 0 c h a r a c t e r s , g i v i n g a w a r n i n g t h a t it h a s d o n e s o . T h e I n s t r u c t i o n
names,
Directive n a m e s ,
Register names,
a n d special symbols
CCR,
SR,
S P , a n d U S P c a n n o t b e u s e d as u s e r s y m b o l s . A s y m b o l c a n b e o n e o f t h r e e
types:
Absolute
a) T h e s y m b o l w a s S E T or E Q U a t e d t o a n A b s o l u t e v a l u e .
194
Relative
a) T h e s y m b o l w a s S E T or E Q U a t e d to a R e l a t i v e v a l u e .
b ) T h e s y m b o l w a s u s e d as a l a b e l .
Register
a ) T h e s y m b o l w a s s e t t o a r e g i s t e r n a m e u s i n g E Q U R ( T h i s is a n e x t e n s i o n
from the Motorola specification).
T h e r e is a s p e c i a l s y m b o l " * " , w h i c h h a s t h e v a l u e a n d t y p e o f t h e c u r r e n t
p r o g r a m c o u n t e r , t h a t i s , t h e a d d r e s s o f t h e c u r r e n t i n s t r u c t i o n or d i r e c t i v e t h a t
t h e a s s e m b l e r is a c t i n g o n .
3.4.4 Numbers
Y o u m a y u s e a n u m b e r a s a t e r m o f a n e x p r e s s i o n , or a s a s i n g l e v a l u e . N u m b e r s
A L W A Y S h a v e a b s o l u t e v a l u e s a n d c a n t a k e o n e of t h e f o l l o w i n g f o r m a t s :
Decimal
(a s t r i n g o f d e c i m a l digits)
Example: 1234
Hexadecimal
($ f o l l o w e d b y a s t r i n g of h e x digits)
Example: $89AB
Octal
( @ f o l l o w e d b y a s t r i n g o f o c t a l digits)
Example: @ 7 4 3
Binary
(% f o l l o w e d b y z e r o s a n d o n e s )
Example: %10110111
A S C I I Literal
(Up to 4 A S C I I characters within quotes)
E x a m p l e s : ' A B C D ' '*'
S t r i n g s o f l e s s t h a n 4 c h a r a c t e r s a r e j u s t i f i e d to t h e r i g h t , u s i n g n u l as t h e
packing character.
T o obtain a quote character in the string, you m u s t use two quotes.
e x a m p l e o f t h i s is
'It' 's'
An
195
and
long w o r d references, access more than one byte, and the address for these
must be word aligned.
In t h e following table, D n represents o n e of the data registers ( D 0 - D 7 ) , " A n "
represents o n e of the address registers ( A 0 - A 7 , S P a n d P C ) , " a " r e p r e s e n t s an
a b s o l u t e e x p r e s s i o n , " r " r e p r e s e n t s a relative e x p r e s s i o n , a n d " X n " r e p r e s e n t s
A n o r D n , w i t h a n o p t i o n a l " . W " or " . L " size specifier. T h e s y n t a x f o r e a c h o f
t h e m o d e s is a s f o l l o w s :
Dn
An
Example:
(An)
M O V E D0,-(A7)
a(An,Xn)
M O V E (A7) + , D 0
a(An)
M O V E D0,(A1)
-(An)
MOVEA A0,A1
(An) +
M O V E DO, D l
A d d r e s s Register Direct
M O V E 20(A0),D1
M O V E 0(A0,D0),D1
M O V E 12(A1,A0.L),D2
M O V E 120(A0,D6.W),D4
S h o r t a b s o l u t e (16 bits)
Example:
Example:
r
M O V E $1000,D0
L o n g a b s o l u t e (32 bits)
M O V E $10000,D0
MOVE ABQDO
( A B C is relative)
r(Xn)
MOVE ABC(D0.L),D1
( A B C is relative)
196
#a
Immediate data
Example:
MOVE #1234,D0
USP
CCR
Special addressing m o d e s
SR
Example:
MOVE A0,USP
MOVE D0,CCR
MOVE D1,SR
3.7 Directives
A l l a s s e m b l e r d i r e c t i v e s ( w i t h t h e e x c e p t i o n o f D C a n d D C B ) a r e i n s t r u c t i o n s to
the assembler, rather than instructions to be translated into object code. At the
beginning
of this section,
t h e r e is a list o f all t h e d i r e c t i v e s ( T a b l e
3-C),
a r r a n g e d b y f u n c t i o n ; at t h e e n d t h e r e is a n i n d i v i d u a l d e s c r i p t i o n f o r e a c h
directive, arranged b y function.
N o t e that the assembler only allows labels on directives w h e r e specified. For
e x a m p l e , E Q U is a l l o w e d a l a b e l . It is o p t i o n a l f o r R O R G , b u t n o t a l l o w e d f o r
L L E N or T T L .
T h e f o l l o w i n g t a b l e lists t h e d i r e c t i v e s b y f u n c t i o n :
197
Control
Symbol
Data
Listing
Directive
Description
SECTION
Program section
RORG
Relocatable origin
OFFSET
Define offsets
END
Program end
Definition
Directive
Description
EQU
EQUR
REG
SET
Definition
Directive
Description
DC
Define constants
DCB
DS
Define storage
Control
Directive
Description
PAGE
P a g e - t h r o w t o listing
LIST
Turn o n listing
NOLIST (NOL)
T u r n off listing
SPC n
NOPAGE
T u r n off p a g i n g
LLEN n
S e t l i n e l e n g t h (60 <
PLEN n
S e t p a g e l e n g t h (24 <
TTL
S e t p r o g r a m title ( m a x 4 0 c h a r s . )
NOOBJ
n < =
= n <
FAIL
FORMAT
N o action
NOFORMAT
Conditional
132)
=
N o action
Assembly
Directive
Description
CNOP
C o n d i t i o n a l N O P for a l i g n m e n t
IFEQ
A s s e m b l e if e x p r e s s i o n is 0
IFNE
A s s e m b l e if e x p r e s s i o n is n o t 0
IFGT
A s s e m b l e if e x p r e s s i o n >
100)
198
Macro
External
General
Directive
Description
IFGE
A s s e m b l e if e x p r e s s i o n >
IFLT
A s s e m b l e if e x p r e s s i o n <
IFLE
A s s e m b l e if e x p r e s s i o n <
IFC
A s s e m b l e if s t r i n g s a r e i d e n t i c a l
IFNC
A s s e m b l e if s t r i n g s are n o t i d e n t i c a l
0
0
IFD
A s s e m b l e if s y m b o l is d e f i n e d
IFND
A s s e m b l e if s y m b o l is n o t d e f i n e d
ENDC
E n d of conditional a s s e m b l y
Directives
Directive
Description
MACRO
NARG
Special symbol
ENDM
E n d of macro definition
MEXIT
Exit t h e m a c r o e x p a n s i o n
Symbols
Directive
Description
XDEF
Define external n a m e
XREF
Reference external n a m e
Directives
Directive
Description
INCLUDE
I n s e r t file in t h e s o u r c e
MASK2
N o action
IDNT
N a m e program unit
Program Section
Format:
[<label>] SECTION
<name>[,<type>]
T h i s d i r e c t i v e tells t h e a s s e m b l e r to r e s t o r e t h e c o u n t e r t o t h e last l o c a t i o n
a l l o c a t e d i n t h e n a m e d s e c t i o n (or t o z e r o if u s e d f o r t h e first t i m e ) .
< n a m e > is a c h a r a c t e r s t r i n g o p t i o n a l l y e n c l o s e d in d o u b l e q u o t e s .
< t y p e > if i n c l u d e d , m u s t b e o n e o f t h e f o l l o w i n g k e y w o r d s :
CODE
indicates
default.
that
the
section
contains
relocatable
code.
DATA
BSS
This
is
the
199
The assembler
c a n m a i n t a i n u p to 2 5 5 s e c t i o n s . Initially, t h e
assembler
Format:
[<label>] RORG
<absexp>
T h e R O R G d i r e c t i v e c h a n g e s t h e p r o g r a m c o u n t e r to b e < a b s e x p >
bytes
f r o m t h e start o f t h e c u r r e n t r e l o c a t a b l e s e c t i o n . T h e a s s e m b l e r a s s i g n s r e l o c a t a b l e
m e m o r y l o c a t i o n s to s u b s e q u e n t s t a t e m e n t s , s t a r t i n g w i t h t h e v a l u e a s s i g n e d
to t h e p r o g r a m c o u n t e r . T o d o a d d r e s s i n g in r e l o c a t a b l e s e c t i o n s , y o u u s e t h e
" p r o g r a m c o u n t e r relative with d i s p l a c e m e n t " addressing m o d e . T h e label value
a s s i g n m e n t is t h e s a m e a s for S E C T I O N .
OFFSET
Define offsets
Format:
OFFSET
<absexp>
T o d e f i n e a t a b l e o f o f f s e t s via t h e D S d i r e c t i v e b e g i n n i n g at t h e a d d r e s s
< a b s e x p > , y o u u s e the O F F S E T directive. Symbols defined in a n O F F S E T table
a r e k e p t i n t e r n a l l y , b u t n o c o d e - p r o d u c i n g i n s t r u c t i o n s or d i r e c t i v e s
may
SEC-
T I O N , or E N D d i r e c t i v e .
END
E n d of p r o g r a m
Format:
[<label>] END
T h e E N D d i r e c t i v e tells t h e a s s e m b l e r t h a t t h e s o u r c e is f i n i s h e d , a n d t h e
assembler ignores
the assembler
en-
c o u n t e r s t h e E N D d i r e c t i v e d u r i n g t h e first p a s s , it b e g i n s t h e s e c o n d p a s s . If,
h o w e v e r , it d e t e c t s a n e n d - o f - f i l e b e f o r e a n E N D d i r e c t i v e , it g i v e s a w a r n i n g
m e s s a g e . If t h e l a b e l field is p r e s e n t , t h e n t h e a s s e m b l e r a s s i g n s t h e v a l u e
of t h e current
program
c o u n t e r to t h e l a b e l b e f o r e
it e x e c u t e s
the
END
directive.
Format:
<label> EQU
<exp>
T h e E Q U d i r e c t i v e a s s i g n s t h e v a l u e o f t h e e x p r e s s i o n in t h e o p e r a n d field t o
t h e s y m b o l in t h e l a b e l field. T h e v a l u e a s s i g n e d is p e r m a n e n t , s o y o u m a y n o t
d e f i n e t h e l a b e l a n y w h e r e e l s e in t h e p r o g r a m .
Note: D o not insert forward references within the expression.
200
EQUR
Format:
<label> EQUR
<register>
D e f i n e r e g i s t e r list
Format:
<label>REG<register list>
T h e R E G d i r e c t i v e a s s i g n s a v a l u e to label t h a t t h e a s s e m b l e r c a n t r a n s l a t e
i n t o t h e r e g i s t e r list m a s k f o r m a t u s e d i n t h e M O V E M i n s t r u c t i o n .
<register
l i s t > is o f t h e f o r m
R l [-R2][/R3[-R4]]. . .
SET
Format:
<exp>
T h e S E T d i r e c t i v e a s s i g n s t h e v a l u e of t h e e x p r e s s i o n i n t h e o p e r a n d field to
t h e s y m b o l in t h e l a b e l field. S E T is i d e n t i c a l t o E Q U , a p a r t f r o m t h e fact t h a t
t h e a s s i g n m e n t is t e m p o r a r y . Y o u c a n a l w a y s c h a n g e S E T l a t e r o n i n
the
program.
Note: You should not insert forward references within the expression
or
r e f e r f o r w a r d to s y m b o l s t h a t y o u d e f i n e d w i t h S E T .
Define Constant
Format:
[<label>] DC[.<size>]
<list>
T h e D C d i r e c t i v e d e f i n e s a c o n s t a n t v a l u e in m e m o r y . It m a y h a v e
any
n u m b e r o f o p e r a n d s , s e p a r a t e d b y c o m m a s (,). T h e v a l u e s i n t h e list m u s t b e
c a p a b l e o f b e i n g h e l d in t h e d a t a l o c a t i o n w h o s e size is g i v e n b y t h e
size
s p e c i f i e r o n t h e d i r e c t i v e . If y o u d o n o t g i v e a size s p e c i f i e r , D C a s s u m e s it is
. W . If t h e size is . B , t h e n t h e r e is o n e o t h e r d a t a t y p e t h a t c a n b e u s e d : t h a t o f
t h e A S C I I s t r i n g . T h i s is a n arbitrarily l o n g s e r i e s o f A S C I I c h a r a c t e r s ,
con-
t a i n e d w i t h i n q u o t a t i o n m a r k s . A s w i t h A S C I I literals, if y o u r e q u i r e a q u o t a t i o n
m a r k i n t h e s t r i n g , t h e n y o u m u s t e n t e r t w o . If t h e size is . W or . L , t h e n t h e
a s s e m b l e r aligns the data onto a w o r d b o u n d a r y .
DCB
Format:
[<label>] DCB[.<size>]
<absexp>,<exp>
Y o u u s e t h e D C B d i r e c t i v e to s e t a n u m b e r ( g i v e n b y < a b s e x p > ) o f b y t e s ,
201
Define Storage
Format:
[<label>] DS[.<size>]
<absexp>
handling
alignment.
Page Throw
PAGE
T u r n on Listing
Format:
LIST
T h e L I S T d i r e c t i v e tells t h e a s s e m b l e r to p r o d u c e t h e a s s e m b l y l i s t i n g file.
L i s t i n g c o n t i n u e s u n t i l it e n c o u n t e r s e i t h e r a n E N D or a N O L I S T d i r e c t i v e . T h i s
d i r e c t i v e is o n l y a c t i v e w h e n t h e a s s e m b l e r is p r o d u c i n g a l i s t i n g file. T h e L I S T
d i r e c t i v e d o e s n o t a p p e a r o n t h e o u t p u t listing.
NOLIST
Format:
T u r n off L i s t i n g
NOLIST
NOL
T h e N O L I S T o r N O L d i r e c t i v e t u r n s off t h e p r o d u c t i o n o f t h e
assembly
l i s t i n g file. L i s t i n g c e a s e s u n t i l t h e a s s e m b l e r e n c o u n t e r s e i t h e r a n E N D o r a
LIST directive. T h e N O L I S T directive d o e s not a p p e a r o n the p r o g r a m listing.
SPC
Format:
SPC
<number>
S P C directive d o e s not a p p e a r o n
the
202
NOPAGE
T u r n off P a g i n g
Format:
NOPAGE
The NOPAGE
d i r e c t i v e t u r n s off t h e p r i n t i n g o f p a g e t h r o w s a n d
title
h e a d e r s o n the a s s e m b l y listing.
LLEN
Format:
LLEN
<number>
T h e L L E N d i r e c t i v e s e t s t h e l i n e l e n g t h o f t h e a s s e m b l y l i s t i n g file t o t h e
v a l u e y o u s p e c i f i e d i n t h e o p e r a n d f i e l d . T h e v a l u e m u s t lie b e t w e e n 6 0 a n d
1 3 2 , a n d c a n o n l y b e set o n c e in t h e p r o g r a m . T h e L L E N d i r e c t i v e d o e s n o t
a p p e a r o n t h e a s s e m b l y listing. T h e d e f a u l t is 1 3 2 c h a r a c t e r s .
PLEAT
Format:
PLEN
The PLEN
<number>
d i r e c t i v e s e t s t h e p a g e l e n g t h o f t h e a s s e m b l y listing file to
t h e v a l u e y o u s p e c i f i e d in t h e o p e r a n d f i e l d . T h e v a l u e m u s t lie
between
2 4 a n d 1 0 0 , a n d y o u c a n o n l y s e t it o n c e in t h e p r o g r a m . T h e d e f a u l t is 6 0
lines.
TTL
S e t P r o g r a m Title
Format:
TTL
<title string>
T h e T T L d i r e c t i v e s e t s t h e title o f t h e p r o g r a m to t h e s t r i n g y o u g a v e i n t h e
o p e r a n d f i e l d . T h i s s t r i n g a p p e a r s a s t h e p a g e h e a d i n g in t h e a s s e m b l y l i s t i n g .
T h e s t r i n g s t a r t s at t h e first n o n b l a n k c h a r a c t e r a f t e r t h e T T L , a n d c o n t i n u e s
u n t i l t h e e n d o f l i n e . It m u s t n o t b e l o n g e r t h a n 4 0 c h a r a c t e r s i n l e n g t h . T h e
T T L directive d o e s not appear o n the p r o g r a m listing.
NOOBJ
Format:
NOOBJ
T h e N O O B J d i r e c t i v e d i s a b l e s t h e p r o d u c t i o n of t h e o b j e c t c o d e file a t t h e
e n d o f a s s e m b l y . T h i s d i r e c t i v e d i s a b l e s t h e p r o d u c t i o n o f t h e c o d e file, e v e n if
y o u specified a filename w h e n y o u called the assembler.
FAIL
G e n e r a t e a user error
Format:
FAIL
The FAIL
directive
tells t h e a s s e m b l e r
to f l a g a n e r r o r f o r t h i s
input
line.
FORMAT
N o action
Format:
FORMAT
T h e a s s e m b l e r a c c e p t s t h i s d i r e c t i v e b u t t a k e s n o a c t i o n o n r e c e i v i n g it.
F O R M A T is i n c l u d e d f o r c o m p a t i b i l i t y w i t h o t h e r a s s e m b l e r s .
203
NOFORMAT
N o action
Format:
NOFORMAT
it.
N O F O R M A T is i n c l u d e d for c o m p a t i b i l i t y w i t h o t h e r a s s e m b l e r s .
Conditional N O P
Format:
[<label>] CNOP
<number>,<number>
T h i s d i r e c t i v e is a n e x t e n s i o n f r o m t h e M o t o r o l a s t a n d a r d a n d a l l o w s
s e c t i o n o f c o d e to b e a l i g n e d o n a n y b o u n d a r y . I n p a r t i c u l a r , it a l l o w s a n y d a t a
s t r u c t u r e or e n t r y p o i n t to b e a l i g n e d to a l o n g w o r d b o u n d a r y .
T h e first e x p r e s s i o n r e p r e s e n t s a n o f f s e t , w h i l e t h e s e c o n d e x p r e s s i o n r e p r e s e n t s t h e a l i g n m e n t r e q u i r e d for t h e b a s e . T h e c o d e is a l i g n e d to t h e s p e c i f i e d
offset from the nearest required alignment b o u n d a r y . T h u s
C N O P 0,4
aligns code to the next long word boundary while
C N O P 2,4
a l i g n s c o d e to t h e w o r d b o u n d a r y 2 b y t e s b e y o n d t h e n e a r e s t l o n g
word
aligned boundary.
IFEQ
A s s e m b l e if e x p r e s s i o n = 0
IFNE
A s s e m b l e if e x p r e s s i o n < > 0
IFGT
A s s e m b l e if e x p r e s s i o n > 0
IFGE
A s s e m b l e if e x p r e s s i o n > = 0
IFLT
A s s e m b l e if e x p r e s s i o n < 0
IFLE
A s s e m b l e if e x p r e s s i o n < = 0
Format:
IFxx
<absexp>
Y o u u s e t h e I F x x r a n g e of d i r e c t i v e s to e n a b l e or d i s a b l e a s s e m b l y , d e p e n d i n g o n t h e v a l u e o f t h e e x p r e s s i o n in t h e o p e r a n d f i e l d . If t h e c o n d i t i o n is n o t
T R U E (for e x a m p l e , I F E Q 2 + 1 ) , a s s e m b l y c e a s e s ( t h a t i s , it is d i s a b l e d ) . T h e
conditional a s s e m b l y switch remains active until the assembler finds a matching E N D C statement. Y o u can nest conditional a s s e m b l y switches arbitrarily,
terminating each level of nesting with a matching E N D C .
IFC
IFNC
Format:
Assemble
Assemble
IFC
IFNC
T h e strings m u s t
if s t r i n g s a r e i d e n t i c a l
if s t r i n g s a r e n o t i d e n t i c a l
<string>,<string>
<string>,<string>
b e a s e r i e s of A S C I I c h a r a c t e r s e n c l o s e d in s i n g l e q u o t e s ,
204
for e x a m p l e ,
' F O O ' or ( t h e e m p t y
s t r i n g ) . If t h e c o n d i t i o n is n o t
TRUE,
a s s e m b l y c e a s e s ( t h a t is, it is d i s a b l e d ) . A g a i n t h e c o n d i t i o n a l a s s e m b l y s w i t c h
remains active until the assembler finds a matching E N D C statement.
IFD
A s s e m b l e if s y m b o l d e f i n e d
IFND
A s s e m b l e if s y m b o l n o t d e f i n e d
Format:
IFD
IFND
the
a s s e m b l e r e n a b l e s or d i s a b l e s a s s e m b l y u n t i l it f i n d s a m a t c h i n g E N D C .
ENDC
Format:
E n d conditional assembly
ENDC
T o t e r m i n a t e a c o n d i t i o n a l a s s e m b l y , y o u u s e t h e E N D C d i r e c t i v e , set u p
with a n y of the 8 IFxx directives above. E N D C m a t c h e s the m o s t recently
e n c o u n t e r e d condition directive.
Macro Directives
MACRO
Format:
<label>
MACRO
M A C R O introduces a macro definition. E N D M terminates a macro definition. Y o u m u s t provide a label, w h i c h the assembler uses as the n a m e of t h e
m a c r o ; s u b s e q u e n t u s e s of t h a t label as a n o p e r a n d e x p a n d t h e c o n t e n t s o f t h e
macro and insert t h e m into the source code. A macro can contain any opcode,
m o s t a s s e m b l e r d i r e c t i v e s , or a n y p r e v i o u s l y d e f i n e d m a c r o . A p l u s s i g n ( + ) i n
t h e listing m a r k s a n y c o d e g e n e r a t e d b y m a c r o e x p a n s i o n . W h e n y o u u s e a
macro n a m e , y o u m a y a p p e n d a n u m b e r of arguments, separated by c o m m a s .
If t h e a r g u m e n t c o n t a i n s a s p a c e (for e x a m p l e , a s t r i n g c o n t a i n i n g a s p a c e ) t h e n
y o u m u s t e n c l o s e t h e e n t i r e a r g u m e n t w i t h i n < (less t h a n ) a n d > ( g r e a t e r t h a n )
symbols.
T h e a s s e m b l e r s t o r e s u p a n d s a v e s t h e s o u r c e c o d e t h a t y o u e n t e r (after a
M A C R O d i r e c t i v e a n d b e f o r e a n E N D M d i r e c t i v e ) as t h e c o n t e n t s o f t h e m a c r o .
T h e code can contain any n o r m a l source code. In addition,
the symbol \
c o m b i n a t i o n it h a s e n c o u n t e r e d . T h i s is n o r m a l l y u s e d
to
g e n e r a t e u n i q u e labels within a m a c r o .
Y o u m a y not nest macro defintions, that is, y o u c a n n o t define a
macro
w i t h i n a m a c r o , a l t h o u g h y o u c a n call a m a c r o y o u p r e v i o u s l y d e f i n e d . T h e r e
205
set
at t e n .
M a c r o e x p a n s i o n stops w h e n the assembler e n c o u n t e r s the e n d of t h e stored
m a c r o t e x t , o r w h e n it f i n d s a M E X I T d i r e c t i v e .
NARG
Special symbol
Format:
NARG
T h e s y m b o l N A R G is a s p e c i a l r e s e r v e d s y m b o l a n d t h e a s s e m b l e r a s s i g n s it
t h e i n d e x o f t h e last a r g u m e n t p a s s e d t o t h e m a c r o in t h e p a r a m e t e r list ( e v e n
nulls). O u t s i d e of a macro expansion, N A R G h a s the value 0.
ENDM
Format:
ENDM
Exit f r o m m a c r o e x p a n s i o n
Format:
MEXIT
External Symbols
XDEF
Format:
XDEF
<label>[,<label>...]
O n e o r m o r e a b s o l u t e or r e l o c a t a b l e l a b e l s m a y f o l l o w t h e X D E F d i r e c t i v e .
Each label defined here generates an external symbol definition.
make references
level language)
to t h e s y m b o l in other m o d u l e s
and
You
(possibly from a
If y o u
can
high-
use
this
Define an external n a m e
Format:
XREF
One
<label>[,<label>...]
o r m o r e l a b e l s t h a t m u s t n o t h a v e b e e n d e f i n e d e l s e w h e r e in
program
Subsequent
u s e s of t h e l a b e l tell
the
the
a s s e m b l e r t o g e n e r a t e a n e x t e r n a l r e f e r e n c e for t h a t l a b e l . Y o u u s e t h e l a b e l a s
if it r e f e r r e d to a n a b s o l u t e or r e l o c a t a b l e v a l u e d e p e n d i n g o n w h e t h e r
the
m a t c h i n g X D E F r e f e r r e d t o a n a b s o l u t e or r e l o c a t a b l e s y m b o l .
T h e a c t u a l v a l u e u s e d is filled in f r o m a n o t h e r m o d u l e b y t h e l i n k e r . T h e
206
l i n k e r a l s o g e n e r a t e s a n y r e l o c a t i o n i n f o r m a t i o n t h a t m a y b e r e q u i r e d in o r d e r
for the resulting code to b e relocatable.
E x t e r n a l s y m b o l s a r e n o r m a l l y u s e d a s f o l l o w s . T o s p e c i f y a r o u t i n e in o n e
p r o g r a m s e g m e n t as a n e x t e r n a l d e f i n i t i o n , y o u p l a c e a label at t h e start o f t h e
r o u t i n e a n d q u o t e t h e label after a n X D E F d i r e c t i v e . A n o t h e r p r o g r a m m a y call
t h a t r o u t i n e if it d e c l a r e s a label via t h e X R E F d i r e c t i v e a n d t h e n j u m p s to t h e
label so declared.
General Directives
INCLUDE
I n s e r t a n e x t e r n a l file
Format:
INCLUDE
It is o f t e n c o n v e n i e n t t o
place
N O L I S T a n d L I S T d i r e c t i v e s at t h e h e a d a n d tail o f files y o u i n t e n d t o i n c l u d e
via I N C L U D E . A m i g a D O S s e a r c h e s f o r t h e file s p e c i f i c a t i o n first i n t h e c u r r e n t
d i r e c t o r y , t h e n in e a c h s u b s e q u e n t d i r e c t o r y in t h e list y o u g a v e in t h e -i
option.
MASK2
N o action
Format:
MASK2
T h e a s s e m b l e r a c c e p t s t h e M A S K 2 d i r e c t i v e , b u t it t a k e s n o a c t i o n o n r e c e i v i n g it.
IDNT
N a m e program unit
Format:
IDNT
<string>
A p r o g r a m u n i t , w h i c h c o n s i s t s o f o n e or m o r e s e c t i o n s , m u s t h a v e a n a m e .
U s i n g t h e I D N T directive, y o u can define a n a m e consisting of a string optionally e n c l o s e d in d o u b l e q u o t e s . If t h e a s s e m b l e r d o e s n o t f i n d a n I D N T d i r e c t i v e ,
it o u t p u t s a p r o g r a m u n i t n a m e t h a t is a n u l l s t r i n g .
Chapter 4
The Linker
Introduction
4.2
4.2.1
C o m m a n d Line Syntax
4.2.2
W I T H Files
4.2.3
4.2.4
4.3
Overlaying
4.3.1
O V E R L A Y Directive
4.3.2
R e f e r e n c e s to S y m b o l s
4.3.3
Cautionary Points
4.4
Error C o d e s and M e s s a g e s
4.1 Introduction
A L I N K p r o d u c e s a s i n g l e b i n a r y o u t p u t file f r o m o n e o r m o r e i n p u t files.
T h e s e i n p u t files, k n o w n a s o b j e c t f i l e s , m a y c o n t a i n e x t e r n a l s y m b o l i n f o r m a t i o n . T o p r o d u c e o b j e c t files, y o u u s e y o u r a s s e m b l e r or l a n g u a g e t r a n s l a t o r .
B e f o r e p r o d u c i n g t h e o u t p u t , o r l o a d f i l e , t h e l i n k e r r e s o l v e s all r e f e r e n c e s
to symbols.
T h e l i n k e r c a n also p r o d u c e a link m a p a n d s y m b o l c r o s s - r e f e r e n c e t a b l e .
A s s o c i a t e d w i t h t h e l i n k e r is a n o v e r l a y s u p e r v i s o r . Y o u c a n u s e t h e o v e r l a y
s u p e r v i s o r to o v e r l a y p r o g r a m s w r i t t e n i n a v a r i e t y of l a n g u a g e s . T h e l i n k e r
p r o d u c e s l o a d files s u i t a b l e f o r o v e r l a y i n g in this w a y .
Y o u c a n d r i v e t h e l i n k e r in t w o w a y s :
208
1. A s a C o m m a n d l i n e . Y o u c a n s p e c i f y m o s t o f t h e i n f o r m a t i o n n e c e s s a r y f o r
running the linker in the c o m m a n d parameters.
2 . A s a P a r a m e t e r file. A s a n a l t e r n a t i v e , if a p r o g r a m is b e i n g l i n k e d r e p e t i t i v e l y , y o u c a n u s e a p a r a m e t e r file to s p e c i f y all t h e d a t a f o r t h e l i n k e r .
T h e s e t w o m e t h o d s c a n t a k e t h r e e t y p e s o f i n p u t files:
1. P r i m a r y b i n a r y i n p u t . T h i s r e f e r s to o n e or m o r e o b j e c t files t h a t f o r m t h e
initial b i n a r y i n p u t t o t h e l i n k e r . T h e s e files a r e a l w a y s o u t p u t t o t h e l o a d
file, a n d t h e p r i m a r y i n p u t m u s t n o t b e e m p t y .
2 . O v e r l a y f i l e s . If o v e r l a y i n g , t h e p r i m a r y i n p u t f o r m s t h e r o o t o f t h e o v e r l a y
t r e e , a n d t h e o v e r l a y files f o r m t h e r e s t o f t h e s t r u c t u r e .
3. Libraries. This refers to specified code that the linker incorporates automatically. L i b r a r i e s m a y b e r e s i d e n t or s c a n n e d . A r e s i d e n t l i b r a r y is a l o a d file
w h i c h m a y b e r e s i d e n t in m e m o r y , or l o a d e d as p a r t o f t h e " l i b r a r y o p e n "
call i n t h e o p e r a t i n g s y s t e m . A s c a n n e d l i b r a r y is a n o b j e c t file w i t h i n a n
a r c h i v e f o r m a t file. T h e l i n k e r o n l y l o a d s t h e file if t h e r e a r e a n y o u t s t a n d i n g
e x t e r n a l r e f e r e n c e s to t h e library.
T h e l i n k e r w o r k s in t w o p a s s e s .
1. I n t h e first p a s s , t h e l i n k e r r e a d s all t h e p r i m a r y , l i b r a r y , a n d o v e r l a y f i l e s ,
and records the code segments and external symbol information. At the e n d
o f t h e first p a s s , t h e l i n k e r o u t p u t s t h e m a p a n d c r o s s - r e f e r e n c e t a b l e , if
required.
2 . If y o u s p e c i f y a n o u t p u t file, t h e n t h e l i n k e r m a k e s a s e c o n d p a s s t h r o u g h t h e
i n p u t . F i r s t it c o p i e s t h e p r i m a r y i n p u t files t o t h e o u t p u t , r e s o l v i n g s y m b o l
r e f e r e n c e s i n t h e p r o c e s s , a n d t h e n it c o p i e s o u t t h e r e q u i r e d library c o d e
s e g m e n t s i n t h e s a m e w a y . N o t e t h a t t h e library c o d e s e g m e n t s f o r m p a r t o f
t h e root of t h e overlay tree. Next, t h e linker p r o d u c e s data for t h e overlay
s u p e r v i s o r , a n d finally o u t p u t s t h e o v e r l a y files.
I n t h e first p a s s , a f t e r r e a d i n g t h e p r i m a r y a n d o v e r l a y i n p u t f i l e s , t h e l i n k e r
i n s p e c t s its t a b l e o f s y m b o l s , a n d if t h e r e a r e a n y r e m a i n i n g u n r e s o l v e d r e f e r e n c e s , it r e a d s t h e f i l e s , if a n y , t h a t y o u s p e c i f i e d a s t h e library i n p u t .
The
l i n k e r t h e n m a r k s a n y c o d e s e g m e n t s c o n t a i n i n g e x t e r n a l d e f i n i t i o n s for t h e s e
u n r e s o l v e d r e f e r e n c e s f o r s u b s e q u e n t i n c l u s i o n i n t h e l o a d file. T h e l i n k e r o n l y
includes those library code s e g m e n t s that y o u have referenced.
THE LINKER
209
ALINK a
ALLKTK ROOT a + b + c + d MAP map-file WIDTH 120
ALUSTK a,b,c TO output LIBRARY :flib/lib,obj/newlib
W h e n y o u g i v e a list o f files, t h e l i n k e r r e a d s t h e m i n t h e o r d e r y o u s p e c i f y .
T h e parameters have the following meanings:
FROM:
S p e c i f i e s t h e o b j e c t files t h a t y o u w a n t a s t h e p r i m a r y b i n a r y i n p u t .
T h e l i n k e r a l w a y s c o p i e s t h e c o n t e n t s o f t h e s e files t o t h e l o a d file
to f o r m p a r t o f t h e o v e r l a y r o o t . A t l e a s t o n e p r i m a r y b i n a r y i n p u t
file m u s t b e s p e c i f i e d . R O O T is a s y n o n y m f o r F R O M .
TO:
S p e c i f i e s t h e d e s t i n a t i o n for t h e l o a d file. If t h i s p a r a m e t e r is n o t
given, the linker omits the second pass.
WITH:
210
VER:
s p e c i f i e s t h e d e s t i n a t i o n o f m e s s a g e s f r o m t h e l i n k e r . If y o u d o n o t
s p e c i f y V E R , t h e l i n k e r s e n d s all m e s s a g e s to t h e s t a n d a r d o u t p u t
(usually the terminal).
LIBRARY:
s p e c i f i e s t h e files t h a t y o u w a n t to b e s c a n n e d a s t h e l i b r a r y . T h e
l i n k e r i n c l u d e s o n l y r e f e r e n c e c o d e s e g m e n t s . L I B is a v a l i d a l t e r n a tive for L I B R A R Y .
MAP:
s p e c i f i e s t h e d e s t i n a t i o n of t h e l i n k m a p .
XREF:
s p e c i f i e s t h e d e s t i n a t i o n of t h e c r o s s - r e f e r e n c e o u t p u t .
WIDTH:
file
LIBRARY
files
MAP
[file]
XREF
[file]
OVERLAY
tree specification
#
WIDTH
line
p a r a m e t e r s a n d W I T H files. S i m i l a r l y , if y o u s p e c i f y a p a r a m e t e r m o r e t h a n
o n c e in W I T H files, t h e l i n k e r u s e s t h e first o c c u r r e n c e .
THE LINKER
211
N o t e : I n t h e s e c o n d e x a m p l e b e l o w , t h i s is t r u e e v e n if t h e first v a l u e g i v e n
t o a p a r a m e t e r is n u l l .
E x a m p l e s o f W I T H files a n d t h e c o r r e s p o n d i n g A L I N K calls:
A L I N K W I T H link-file
where "link-file" contains
FROM
obj/main,obj/s
TO
bin/test
LIBRARY
obj/lib
MAP
XREF
xo
is t h e s a m e as s p e c i f y i n g
A L I N K F R O M o b j / m a i n , o b j / s TO b i n / t e s t L I B R A R Y o b j / l i b X R E F x o
The command
ALINK WITH lkin LIBRARY ""
w h e r e 'lkin' contains
FROM
bin/prog,bin/subs
LIBRARY
nag/fortlib
TO
linklib/prog
is t h e s a m e a s t h e c o m m a n d l i n e
A L I N K F R O M b i n / p r o g , b i n / s u b s TO l i n k l i b . p r o g
N o t e : In the example above, the null parameter for L I B R A R Y o n the c o m m a n d l i n e o v e r r i d e s t h e v a l u e " n a g / f o r t l i b " in t h e W I T H file, a n d s o t h e l i n k e r
d o e s not read a n y libraries.
self-explanatory
and
refer
to t h e
failure
to o p e n
files,
or to
errors
in c o m m a n d o r b i n a r y file f o r m a t . A f t e r a n e r r o r , t h e l i n k e r t e r m i n a . e s
at
once.
T h e r e are a f e w m e s s a g e s that are warnings only. T h e m o s t
important
212
and
l i n k i n g t h e n t e r m i n a t e s at o n c e .
S i n c e t h e l i n k e r o n l y u s e s t h e first d e f i n i t i o n o f a n y s y m b o l , it is i m p o r t a n t
t h a t y o u u n d e r s t a n d t h e f o l l o w i n g o r d e r i n w h i c h files a r e r e a d .
1. P r i m a r y ( F R O M or R O O T ) i n p u t .
2 . O v e r l a y files.
3 . L I B R A R Y files.
W i t h i n e a c h g r o u p , t h e l i n k e r r e a d s t h e files i n t h e o r d e r t h a t y o u s p e c i f y i n
t h e file list. T h u s d e f i n i t i o n s in t h e p r i m a r y i n p u t o v e r r i d e t h o s e i n t h e o v e r l a y
f i l e s , a n d t h o s e i n t h e libraries h a v e l o w e s t p r i o r i t y .
o u t p u t a l s o lists e a c h c o d e s e g m e n t ,
with the
same
header as in the m a p .
T h e h e a d e r is f o l l o w e d b y a list o f t h e s y m b o l s w i t h t h e i r r e f e r e n c e s . E a c h
reference consists of a pair of integers, giving the offset of the reference a n d
t h e n u m b e r o f t h e c o d e s e g m e n t i n w h i c h it o c c u r s . T h e c o d e s e g m e n t n u m b e r
refers to the n u m b e r given in each header.
THE LINKER
213
4.3 Overlaying
T h e automatic overlay system provided by the linker and the overlay supervisor allows programs to occupy less m e m o r y w h e n
running,
without
any
this
overlay
file p r o d u c e d
o v e r l a y s u p e r v i s o r is i n v i s i b l e to t h e
from
program
running.
#
N o t e : T h e overlay directive can s p a n m a n y lines. T h e linker recognizes a
h a s h s i g n ( # ) or t h e e n d - o f - f i l e as a t e r m i n a t o r for t h e d i r e c t i v e .
E a c h line after O V E R L A Y specifies o n e n o d e of the tree, a n d consists of a
c o u n t " X " a n d a file list.
T h e l e v e l o f a n o d e s p e c i f i e s its " d e p t h " in t h e t r e e , s t a r t i n g at z e r o , w h i c h is
t h e l e v e l o f t h e r o o t . T h e c o u n t " X " , g i v e n in t h e d i r e c t i v e , c o n s i s t s o f z e r o o r
m o r e a s t e r i s k s , a n d t h e o v e r l a y l e v e l o f t h e n o d e is g i v e n b y X +
1.
A s w e l l as t h e l e v e l , e a c h n o d e o t h e r t h a n t h e r o o t h a s a n o r d i n a t e v a l u e .
214
T h i s r e f e r s to t h e o r d e r in w h i c h t h e l i n k e r s h o u l d r e a d t h e d e s c e n d e n t s o f e a c h
n o d e , a n d starts at 1, for t h e first " o f f s p r i n g " of a p a r e n t n o d e .
N o t e : T h e r e m a y b e n o d e s with the same level a n d ordinate, but
with
different parents.
W h i l e r e a d i n g t h e O V E R L A Y directive, t h e linker r e m e m b e r s t h e c u r r e n t level,
a n d , for e a c h n e w n o d e , c o m p a r e s t h e level specified w i t h this v a l u e . If l e s s , t h e n
t h e n e w n o d e is a d e s c e n d e n t of a p r e v i o u s o n e . If e q u a l , t h e n e w n o d e h a s t h e
s a m e p a r e n t a s t h e c u r r e n t o n e . If g r e a t e r , t h e n e w n o d e is a direct d e s c e n d a n t o f
t h e c u r r e n t o n e , a n d s o t h e n e w level m u s t b e o n e g r e a t e r t h a n t h e c u r r e n t v a l u e .
A n u m b e r o f e x a m p l e s m a y h e l p to clarify t h i s :
Directive
Level
Ordinate
Tree
ROOT
OVERLAY
a
a b c
#
ROOT
OVERLAY
a
*c
*d
b
c d
#
ROOT
OVERLAY
1
*c
*d
*g
*h
**i
**j
*k
1
ab
c d
e f 1
ghk
#
Figure 4-A
T h e l e v e l a n d o r d i n a t e v a l u e s g i v e n a b o v e r e f e r to t h e n o d e s p e c i f i e d o n t h e
s a m e l i n e . N o t e t h a t all t h e files g i v e n in t h e e x a m p l e s a b o v e c o u l d h a v e b e e n
file lists. S i n g l e l e t t e r s a r e for clarity. F o r e x a m p l e , F i g u r e 4 - B :
THE LINKER
215
ROOT bin/mainaaa
OVERLAY
bin/mambbb,bin/mamccc,bm^
*bin/makereal
*bin/trbblock,bln/transtot,bin/transr*
bin/transri
bin/outcode
#
Figure 4-B
specifies the tree in the following figure:
bin/mainaaa
bin/mainbbb
bin/outcode
bin/mainccc
bin/mainddd
bin/makereal
bin/trbblock
bin/transint
bin/transr
bin/transri
Figure 4-C
D u r i n g l i n k i n g , t h e l i n k e r r e a d s t h e o v e r l a y files in t h e o r d e r y o u s p e c i f i e d i n
the directive, line b y line. T h e linker preserves this order in the m a p a n d cross
reference output, a n d so y o u can d e d u c e the exact tree structure f r o m
the
216
/i\
B C
D E F
W h e n t h e l i n k e r first l o a d s t h e p r o g r a m , o n l y A is in m e m o r y . W h e n t h e
l i n k e r f i n d s a r e f e r e n c e in A t o a s y m b o l in B , it l o a d s a n d e n t e r s B . If B in t u r n
calls D t h e n a g a i n a n e w n o d e is l o a d e d . W h e n B r e t u r n s t o A , b o t h B a n d D
a r e left i n m e m o r y , a n d t h e l i n k e r d o e s n o t r e l o a d t h e m if t h e p r o g r a m r e q u i r e s
t h e m l a t e r . N o w s u p p o s e t h a t A calls C . First t h e l i n k e r u n l o a d s t h e c o d e
s e g m e n t s t h a t it d o e s n o t r e q u i r e , a n d w h i c h it m a y o v e r w r i t e . In t h i s c a s e ,
t h e s e a r e B a n d D . O n c e it h a s r e c l a i m e d t h e m e m o r y f o r t h e s e , t h e l i n k e r c a n
load C.
T h u s , w h e n t h e l i n k e r e x e c u t e s a g i v e n n o d e , all t h e n o d e ' s " a n c e s t o r s " , u p
t o t h e r o o t a r e i n m e m o r y , a n d p o s s i b l y s o m e of its d e s c e n d e n t s .
not
THE LINKER
217
an overlay
the overlay
of the form
use symbols
T h e l i n k e r g a t h e r s t o g e t h e r all p r o g r a m s e c t i o n s w i t h t h e s a m e s e c t i o n n a m e .
It d o e s this s o t h a t it c a n t h e n l o a d t h e m c o n t i n u o u s l y in m e m o r y .
I n v a l i d u s e of s y m b o l
I n v a l i d u s e of c o m m o n
I n v a l i d u s e of o v e r l a y r e f e r e n c e
10
B a d o f f s e t d u r i n g 3 2 bit r e l o c a t i o n
11
B a d o f f s e t d u r i n g 6/8 b i t r e l o c a t i o n
12
B a d o f f s e t w i t h 3 2 bit r e f e r e n c e
13
B a d o f f s e t w i t h 6/8 bit r e f e r e n c e
14
U n e x p e c t e d e n d o f file
15
Hunk.end missing
16
I n v a l i d t e r m i n a t i o n of file
17
P r e m a t u r e t e r m i n a t i o n of file
18
P r e m a t u r e t e r m i n a t i o n o f file
Internal Errors
19
I n v a l i d t y p e i n h u n k list
20
I n t e r n a l e r r o r d u r i n g library s c a n
21
22
Appendix
Introduction
T h i s a p p e n d i x d e s c r i b e s s e v e r a l w a y s to d o c o n s o l e ( k e y b o a r d a n d s c r e e n )
input and output on the Amiga. Y o u can open the console as y o u would any
o t h e r A m i g a D O S file (with " * " , " C O N : " , " R A W : " ) o r d o d i r e c t calls to
c o n s o l e . l i b r a r y . T h e a d v a n t a g e s o f u s i n g e a c h a r e listed b e l o w :
*
" A s t e r i s k " d o e s n o t o p e n a n y w i n d o w s ; it j u s t u s e s t h e e x i s t i n g
CLI w i n d o w . Y o u do not receive any complex character seq u e n c e s . Y o u do receive lower case letters a - z , u p p e r c a s e
letters A - Z , n u m b e r s , ASCII special symbols, a n d control chara c t e r s . B a s i c a l l y , if a t e l e t y p e c a n g e n e r a t e t h e c h a r a c t e r w i t h a
s i n g l e k e y s t r o k e , y o u c a n r e c e i v e it. In a d d i t i o n t o t h e s e c h a r a c t e r s , y o u c a n r e c e i v e e a c h of t h e m w i t h t h e h i g h - o r d e r b i t s e t
( $ 8 0 - $ F F ) . L i n e e d i t i n g is also p e r f o r m e d for y o u . T h i s m e a n s
A m i g a D O S accepts < B A C K S P A C E > a n d C T R L - X for character
a n d line d e l e t i o n s . Y o u d o n o t h a v e to d e a l w i t h t h e s e . A n y
< C S I > s e q u e n c e is s w a l l o w e d for y o u as w e l l a s c o n t r o l c h a r acters: C, D , E, F, H, a n d X. A n y < C R > or C T R L - M characters
a r e c o n v e r t e d to C T R L - J ( n e w - l i n e ) .
CON:
RAW:
T h e s i m p l e c a s e : W i t h R A W : (as c o m p a r e d to C O N : ) y o u l o s e
t h e line e d i t i n g f u n c t i o n s a n d y o u g a i n a c c e s s t o t h e f u n c t i o n
a n d a r r o w k e y s . T h e s e a r e s e n t a s s e q u e n c e s of c h a r a c t e r s
w h i c h y o u m u s t p a r s e in a n i n t e l l i g e n t m a n n e r .
T h e " c o m p l e x " c a s e s : B y i s s u i n g a d d i t i o n a l c o m m a n d s to t h e
c o n s o l e p r o c e s s o r (by d o i n g w r i t e s to R A W : ) , y o u c a n g e t e v e n
more detailed information. For example, y o u can request key
219
See
t h i s m e t h o d , y o u h a v e full c o n t r o l o v e r t h e
console
own
220
0
0
0
0
0
1
b(,
0
0
1
0
tiK
b?
00 01
bl
0 0 0 0 00
0 0 1 0 02
1
0
II
08
11
1 1 0 0 12
8
9
E
E
<
>
SHY
mm
13
14
>
15
EE
? o ?
b'
07
1.5
a
a
a
A" 0
1
0
1 0 1 0 10
.WW.*
09
>
&
1
1
12 13 14
+ A
06
NBSP
0
0
1
1
1
0
1
1
0
1
0
0
1
1
0
0
0
0 1 0 1 05
0
1
3
1
0
0
04
03
r1
02 0 3 0 4 0 5 06 0 7 08 09 1 0 11
SP
0 0 0 1 01
0
1
'
u*
u
0
u
*
I
I
*
y
221
Hex
Name
Definition
08
BS
BACKSPACE
M o v e t h e c u r s o r left
09
TAB
TAB
M o v e right 1 c o l u m n
J
K
OA
LF
LINE FEED
OB
VT
VERTICAL TAB
1 column
M o v e c u r s o r u p 1,
scroll
if n e c e s s a r y
L
M
OC
0D
FF
CR
FORM FEED
CARRIAGE RETURN
M o v e to first c o l u m n
0E
SO
SHIFT OUT
Set M S B of each
character before
displaying
OF
IB
SI
SHIFT IN
Undo SHIFT O U T
ESC
ESCAPE
See below
P r e c e d e t h e f o l l o w i n g c h a r a c t e r s w i t h < E S C > to p e r f o r m t h e i n d i c a t e d a c t i o n s .
Chr
Name
Definition
RIS
Chr
IND
E
M
Name
INDEX:
NEL
RI
CSI
or press C T R L - A L T a n d the
Definition
m o v e the active position d o w n o n e line
NEXT LINE:
REVERSE INDEX:
CONTROL SEQUENCE INTRODUCER:
s e e n e x t list
222
"0"
"1"
"2"
"3"
"4"
"8"
indicates
indicates
indicates
indicates
indicates
indicates
no parameters allowed.
0 or 1 numeric parameters.
2 numeric parameters ("14;94").
any n u m b e r of numeric parameters, separated by semicolons.
exactly 4 numeric parameters.
exactly 8 numeric parameters.
Definition
INSERT CHARACTER
Inserts 1 or m o r e s p a c e s , shifting
t h e r e m a i n d e r of t h e line t o t h e
right.
1J
1 K
1 L
CUD
CUF
CUB
CNL
CPL
CUP
ED
EL
IL
CURSOR UP
CURSOR DOWN
CURSOR FORWARD
CURSOR BACKWARD
CURSOR NEXT LINE
C U R S O R PRECEDING LINE
CURSOR POSITION
ERASE IN DISPLAY
ERASE IN LINE
INSERT LINE
1 M
DL
DELETE LINE
1 P
2 R
DCH
CPR
1 S
SU
1 T
SD
3h
SM
3 1
3 m
1 n
RM
SGR
DSR
DELETE CHARACTER
C U R S O R P O S I T I O N R E P O R T (in R e a d s t r e a m o n l y )
F o r m a t of r e p o r t :
"<CSI>row;columnR"
R e m o v e s line f r o m t o p of s c r e e n .
SCROLL UP
M o v e s all o t h e r l i n e s u p o n e .
B l a n k s last l i n e .
R e m o v e s line from b o t t o m of
SCROLL DOWN
screen.
M o v e s all o t h e r l i n e s d o w n o n e .
Blanks top line.
< C S I > 2 0 h causes R A W :
SET M O D E
t o c o n v e r t < L F > to
< n e w l i n e > on output.
< C S I > 2 0 1 undoes SET M O D E 20
RESET M O D E
SELECT GRAPHIC RENDITION
DEVICE STATUS REPORT
1
1
1
1
1
1
2
A
B
C
D
E
F
H
cuu
D o w n n lines to c o l u m n 1
U p n l i n e s to c o l u m n 1
"<CSI>row;columnH"
( o n l y t o e n d of d i s p l a y )
(only to eol)
I n s e r t s a b l a n k line
B E F O R E t h e line
containing the cursor.
Removes the current
l i n e . M o v e s all
lines b e l o w u p b y
one. Blanks the
bottom line.
223
1 u
1 X
i y
3 {
8
3 }
1 '
IP
Oq
4 r
a W B R W I N D O W B O U N D S R E P O R T (read)
a S K R S P E C I A L K E Y R E P O R T (read)
< E s c > p t u r n s t h e c u r s o r off
Examples:
M o v e c u r s o r r i g h t b y 1:
< C S I > C or < T a b > or < C S I > 1 C
M o v e cursor right by 20:
<CSI>20C
M o v e c u r s o r to u p p e r left c o r n e r ( h o m e ) :
< C S I > H or < C S I > 1 ; 1 H or < C S I > ; 1 H or < C S I > 1 ; H
M o v e c u r s o r to t h e f o u r t h c o l u m n o f t h e first l i n e o f t h e w i n d o w :
< C S I > 1 ; 4 H or
<CSI>;4H
{clear s c r e e n c h a r a c t e r } o r
<CSI>H<CSI>J
{ h o m e a n d clear to e n d of screen} or
<CSI>H<CSI>23M
{ h o m e a n d delete 23 lines} or
<CSI>1;1H<CSI>23L
224
Unshifted Sends
<CSI>0'
Shifted Sends
<CSI>2~
<CSI>3
<CSI>4'
<CSI>5"
<CSI>12'
<CSI>13"
<CSI>14
<CSI>15"
<CSI>6"
<CSI>7'
<CSI>16"
<CSI>17'
<CSI>8~
<CSI>9'
<CSI>?'
<CSI>18~
<CSI>19'
< C S I > ? ' (same)
<csi>r
CSI>10"
<csi>ir
Arrow keys:
Up
Down
Left
Right
<CSI>A
<CSI>B
<CSI>C
<CSI>D
<CSI>T'
<CSI>S'
< C S I > A " (note space)
< C S I > @ " (note space)
225
Description
nop
R A W keyboard input
R A W mouse input
Event
Used internally.
S e n t w h e n e v e r y o u r w i n d o w is
m a d e active.
Pointer position
(unused)
Timer
Gadget pressed
Gadget released
R e q u e s t e r activity
10
Menu numbers
11
Close Gadget
12
W i n d o w resized
13
Window refreshed
14
Preferences changed
15
Disk removed
16
Disk inserted
If y o u s e l e c t a n y o f t h e s e e v e n t s , y o u start to g e t i n f o r m a t i o n a b o u t
the
<CSIXclass>
< subclass >
<keycode>
<qualifiers>
<x>
<y>
<seconds>
<microseconds >
< C S I > is a o n e b y t e f i e l d . It is t h e C o n t r o l S e q u e n c e I n t r o d u c e r , 9 B h e x .
< c l a s s > is t h e R A W i n p u t e v e n t t y p e , f r o m t h e a b o v e t a b l e .
< s u b c l a s s > is n o t c u r r e n t l y u s e d a n d is a l w a y s z e r o ( 0 ) .
< k e y c o d e > indicates w h i c h key n u m b e r w a s pressed (see Figure A - l
and
226
AMIGADOS DEVELOPER'S M A N U A L
Bit
Mask
0
1
2
0001
0002
0004
3
4
13
14
0008
0010
0020
0040
0080
0100
0200
0400
0800
1000
2000
4000
15
8000
5
6
7
8
9
10
11
12
Key
left shift
r i g h t shift
caps lock
control
left alt
* special, see b e l o w
r i g h t alt
left A m i g a k e y p r e s s e d
right Amiga k e y pressed
numeric pad
repeat
interrupt
multi broadcast
left m o u s e b u t t o n
right m o u s e button
middle mouse button
( n o t available o n s t d m o u s e )
relative m o u s e
T h e C A P S L O C K k e y is h a n d l e d in a s p e c i a l m a n n e r . It o n l y g e n e r a t e s a
k e y c o d e w h e n it is p r e s s e d , n o t w h e n it is r e l e a s e d . H o w e v e r , t h e u p a n d
d o w n b i t (80 h e x ) is still u s e d a n d r e p o r t e d . If p r e s s i n g t h e C A P S L O C K k e y
t u r n s o n t h e L E D , t h e n k e y c o d e 6 2 ( C A P S L O C K p r e s s e d ) is s e n t . If p r e s s i n g
the C A P S L O C K k e y extinguishes the L E D , t h e n key c o d e 190 ( C A P S L O C K
r e l e a s e d ) is s e n t . I n e f f e c t , t h e k e y b o a r d r e p o r t s t h i s k e y b e i n g h e l d d o w n u n t i l
it is s t r u c k a g a i n .
T h e < s e c o n d s > a n d < m i c r o s e c o n d s > fields a r e s y s t e m time s t a m p t a k e n at
t h e t i m e t h e e v e n t o c c u r r e d . T h e s e v a l u e s a r e s t o r e d as l o n g w o r d s b y t h e
s y s t e m a n d a s s u c h c o u l d (theoretically) r e a c h 4 b i l l i o n .
With R A W : keyboard input,
c h a r a c t e r "A"
to " Z " b u t r a t h e r r e t u r n r a w k e y c o d e r e p o r t s w i t h t h e f o l l o w i n g
form:
<CSI>l;0;<keycode>;<qualifiers>;0;0;<secs>;<microsecs>|
F o r e x a m p l e , if t h e u s e r p r e s s e d a n d r e l e a s e d t h e " B " k e y w i t h t h e left
S H I F T a n d r i g h t A m i g a k e y s also p r e s s e d , y o u m i g h t r e c e i v e t h e f o l l o w i n g
data:
<CSI>1;0;35;129;0;0;23987;99|
< C S I > 1 ;0; 1 6 3 ; 1 2 9 ; 0 ; 0 ; 2 4 0 0 3 ; 18|
227
isc
45
bo
F1
F3
50
01
T*|
42
CTHL
63
10
CAtt
LOCK
F3
51
0 2W
52
i
03 0 4
E
11
S
It
12
13
62
54
05
06
34
40
58
59
DEL
46
SACK
SPACE
OC 0D
41
P
HELP
i
!
1 9 1/1 1 B 4 4 5 F
18
0B
IF) I T UA N
27
26
36
OA
0 90
ft
35
17
16
57
56
'08
07
F10
55
1 4 1H 5
c
2 3 24 25
2 0 21 22
C
z
60
30 31 3 2 3 3
ALT
A
64
66
SHIFT
F7
FS
53
28
29
2 A | 2E3
3E
30
4
3F
4C
2E
a
1D I E
2F
2D
1
1F
37
38
39
3A
A.
67
61
65
4F
4E
OF
3C
INTiFl
4D
4A
43
228
T h e d e f a u l t v a l u e s g i v e n in t h e f o l l o w i n g c o r r e s p o n d t o :
1) T h e v a l u e s t h e C O N : d e v i c e r e t u r n s w h e n t h e s e k e y s a r e p r e s s e d , a n d
2) T h e keycaps as shipped with the standard American keyboard.
Table A - 2 : Converting from Keycodes to Keys
Raw
Unshifted
Shifted
Key
Default
Default
Number
Value
Value
00
'<Accent grave>
" <tilde>
01
02
03
04
05
06
07
&
08
09
OA
0B
- <Hyphen>
<Underscore>
0C
0D
0E
undefined
OF
0 <Numeric pad>
10
11
12
13
14
15
16
17
U
I
u
i
18
19
1A
IB
1C
undefined
ID
1 <Numeric pad>
IE
2 <Numeric pad>
IF
3 <Numeric pad>
Unshifted
Shifted
Key
Default
Default
Number
Value
Value
20
21
22
23
24
25
g
h
26
27
J
K
j
k
28
29
2A
2B
2C
<RESERVED>
undefined
(RESERVED)
2D
4 <Numeric pad>
2E
5 <Numeric pad>
2F
6 <Numeric pad>
30
<RESERVED>
(RESERVED)
31
32
33
34
c
V
35
36
37
38
<
, <comma>
3A
39
>
3B
undefined
3C
3D
3E
8 <Numeric pad>
3F
9 <Numeric pad>
. <Numeric pad>
40
Space
41
BACKSPACE
42
TAB
43
ENTER
44
RETURN
45
Escape
46
DEL
7 <Numeric pad>
229
230
AMIGADOS DEVELOPER'S M A N U A L
Raw
Unshifted
Key
Number
Default
47
48
49
4A
4B
4C
4D
4E
4F
50
51
52
53
54
55
56
57
58
59
5A
5B
5C
5D
5E
5F
60
61
62
63
64
65
66
Value
Shifted
Default
Value
undefined
undefined
undefined
-
- <Numeric pad>
undefined
Cursor Up
Cursor D o w n
Cursor Forward
Cursor Backward
Fl
F2
F3
F4
F5
F6
F7
F8
F9
F10
undefined
undefined
undefined
undefined
undefined
Help
SHIFT < l e f t of space b a r >
S H I F T < r i g h t of s p a c e b a r >
Caps Lock
Control
Left Alt
Right Alt
" A m i g a " < l e f t of space b a r >
Scroll d o w n
Scroll u p
Scroll left
Scroll r i g h t
<CSI>10~
<csi>ir
<CSI>12'
<CSI>13~
<CSI>14'
<CSI>15'
<CSI>16"
<CSI>17~
<CSI>18"
<CSI>19"
67
68
Left M o u s e Button
< n o t converted>
69
mouse connected
to Intuition,
Raw
Unshifted
Shifted
Key
Default
Default
Number
Value
Value
6A
231
currently
"gameport" one.
6B
undefined
6C
undefined
6D
undefined
6E
undefined
6F
undefined
70-7F
undefined
80-F8
U p transition < r e l e a s e
or u n p r e s s k e y >
of o n e of
the
FA
FB
FC
K e y b o a r d self-test failed.
FD
FE
FF
(undefined, reserved)
FF
<not
AmigaDOS Technical
Reference Manual
Contents
1. Filing System
2. Amiga Binary File Structure
3. AmigaDOS Data Structures
Chapter 1
A m i g a D O S File S t r u c t u r e
Root Block
User Directory Blocks
File H e a d e r B l o c k
File List B l o c k
Data Block
D I S K E D T h e Disk Editor
FILING SYSTEM
235
E a c h filing s y s t e m b l o c k c o n t a i n s a c h e c k s u m , w h e r e t h e s u m ( i g n o r i n g
o v e r f l o w ) o f all t h e w o r d s i n t h e b l o c k is z e r o .
T h e figure b e l o w describes t h e layout of t h e root block.
0 I
T. S H O R T
1 |_
2 |
3 I
4 f
L
0
_0_ _
Type
^
Header k e y (always zero)
HTSIZE
____o____J
CHJCKSJJJMJ
hash
table
SIZE-51 I
SIZE-50 [ ] _ B M F L A G
SIZE-49 |
I
SIZE-24 |
Bitmap
P 8
a
e s
SIZE-23 I
DAYS
SIZE-22 I
NflNS
SIZE-21
TICKS
SIZE-20 |
|
H a s h t a b l e size ( = b l o c k s i z e - 5 6 )
6l
SIZE-7
I
1
_j
_]j
T R U E if B i t m a p o n d i s k is v a l i d
U s e d to indicate t h e blocks
I
|
1
I
V o l u m e last a l t e r e d
date a n d time
DISK
V o l u m e n a m e as a B C P L string
NAME
of < = 3 0 characters
I CREATEDAYS I
SIZE-6
I CJREATEMINS I
SIZE-5
^CMATETICKS^
V o l u m e creation date
and
time
SIZE-4
SIZE-3
SIZE-2
]j
SIZE-1
ST.ROOT
236
0 I _Tj5HORT _
1
Type
E - - ^ H e a d e r
2 [_
3
k e y ( p o i n t e r t o self)
L c9s_y_M J
s
I
I
I
hash
table
I
I
/
SIZE-51 I
SIZE-50
^pare_
SIZE-48 J
PROTECT
Protection bits
SIZE-47 I
U n u s e d (always zero)
S I Z E - 4 6 !~
COMMENT
Stored as a B C P L string
S I Z E - 2 4 [_
SIZE-23 |
DAYS
SIZE-22 I
MINS
SIZE-21
TICKS
|
I
SIZE-20 | D I R E C T O R Y
|
NAME
SIZE-4
| HASHCHATNJ
SIZE-3
r_JPARENT__
SIZE-2
SIZE-1
Stored as a B C P L string
of < = 30 characters
Next entry with same hash value
L J P l ^ S E R D J R J
secondary type
FILING SYSTEM
237
238
0 I _ T^HORT _
Type
1 j]_OWN_KEY_J
2
Header key
L ^ G H E ^ S E Q J
3 I
D A T A SIZE_
Li^^KSUM
o f
b l o c k s in file
First d a t a b l o c k
DATA BLK 3
I DATA BLK 2
N u m b e r o f d a t a b l o c k slots u s e d
4 FIRST DATA J
5
list of d a t a b l o c k k e y s
S I Z E - 5 1 I D A T A B L K 1_ I
SIZE-50
^pare_
SIZE-48 |
PROTJCT
Protection bits
S I Z E - 4 7 I _B_YTE S I Z E _
T o t a l size o f file i n b y t e s
SIZE-46 T
1
COMMENT
SIZE-24 j
C o m m e n t as B C P L s t r i n g
j
SIZE-23 |
DAYS
SIZE-22 I
MINS
SIZE-21 T
TICKS
SIZE-20 |
FILE
|_
NAME
Ly . i =?i i^ J
SIZE-3
I _J'ARENT__
SIZE-2
J^XTENSION_ J
SIZE-1
L _ _ ? T i l
I (
Stored as a B C P L string
_|
SIZE-4
of < = 30 characters
e n t r
B a c k p o i n t e r to p a r e n t d i r e c t o r y
Z e r o o r p o i n t e r to first e x t e n s i o n b l o c k
L
Secondary type
FILING SYSTEM
239
0 I
1
T.LIST
I
1
j
OWNKEY
Type
Header key
2 [BLOCK COUNT]
= n u m b e r o f d a t a b l o c k s i n b l o c k list
3 I J^ATA_SrZE_
Same as above
4 FIRST DATA J
5
First d a t a b l o c k
L i ^ C K S J J M
I BLOCK N + 3 I
I BLOCK N + 2 I
SIZE-51 I BLOCK_N + l I
1
S I Z E - 5 0 |~
j
E x t e n d e d list o f d a t a b l o c k k e y s
info
(unused)
|
SIZE-4
SIZE-3
I _J'ARENT__
SIZE-2
J^EXTE^IOnJ
SIZE-1
|_
secondary type
ST.FILE
N e x t i n h a s h list ( a l w a y s z e r o )
240
T h e r e a r e a s m a n y file e x t e n s i o n b l o c k s a s r e q u i r e d to list t h e d a t a b l o c k s t h a t
m a k e u p t h e file. T h e l a y o u t o f t h e b l o c k is v e r y similar t o t h a t o f a file h e a d e r
b l o c k , e x c e p t t h a t t h e t y p e is d i f f e r e n t a n d t h e d a t e a n d f i l e n a m e fields a r e n o t
used.
0 I _ JJDATA__
1 j
2 |
_ HEADER _
SE_Q_NUM
type
I
J
header key
sequence number
3 I JDATA_SIZE_ I
4
5
NEXT DATA
DATA
I
Figure 1-E: Data Block
FILING SYSTEM
241
242
T h e f o l l o w i n g is a c o m p l e t e list o f t h e available c o m m a n d s .
Command
Bn
Function
S e t logical b l o c k n u m b e r b a s e t o n
G[n]
Cn
H name
Calculate H a s h value of n a m e
C h e c k b l o c k c h e c K s u m ( a n d c o r r e c t if w r o n g )
L o c a t e w o r d s t h a t m a t c h V a l u e u n d e r M a s k ( l w b a n d u p b restrict
L[lwb upb]
search)
M n
N[lwb upb]
Pn
( d e f a u l t is t h e c u r r e n t b l o c k n u m b e r )
Q
S char
S e t M a s k (for L a n d N c o m m a n d s ) t o n
Q u i t (do n o t w r i t e to disk)
char
C - > characters
S - > string
O - > octal
X - > hex
D - > decimal
T lwb upb
Vn
W
T y p e r a n g e o f o f f s e t s in b l o c k
Set Value for L a n d N c o m m a n d s
Windup ( = PQ)
Invert write protect state
X
Yn
Z e r o all w o r d s o f b u f f e r
number
/[n]
D i s p l a y w o r d at c u r r e n t o f f s e t or u p d a t e v a l u e to n
'chars'
P u t c h a r s at c u r r e n t o f f s e t
"chars"
T o i n d i c a t e o c t a l or h e x , y o u c a n start n u m b e r s w i t h # o r # X ( t h a t i s , #
for
o c t a l , # X for h e x ) . Y o u c a n a l s o i n c l u d e B C P L s t r i n g e s c a p e s (*N a n d s o f o r t h )
in strings.
Chapter 2
Introduction
Terminology
O b j e c t File S t r u c t u r e
hunk
unit
hunk
name
hunk
code
hunk
data
hunk
bss
hunk
reloc32
hunk
hunk
hunk
relocl6
reloc8
ext
hunk
symbol
hunk
debug
hunk
end
Load Files
hunk
header
hunk
overlay
hunk_break
Examples
2.1 Introduction
C h a p t e r 2 d e t a i l s t h e s t r u c t u r e of B i n a r y O b j e c t files f o r t h e A m i g a , a s
p r o d u c e d b y a s s e m b l e r s a n d c o m p i l e r s . It also d e s c r i b e s t h e f o r m a t of B i n a r y
L o a d files, w h i c h are p r o d u c e d b y the linker a n d read into m e m o r y b y t h e
l o a d e r . T h e f o r m a t of l o a d files s u p p o r t s o v e r l a y i n g . A p a r t f r o m d e s c r i b i n g t h e
244
f o r m a t of l o a d files, t h i s c h a p t e r e x p l a i n s t h e u s e of c o m m o n s y m b o l s , a b s o l u t e
external references, and program units.
2.1.1 Terminology
S o m e of t h e t e c h n i c a l t e r m s u s e d i n t h i s c h a p t e r a r e e x p l a i n e d b e l o w .
External
References
Y o u c a n u s e a n a m e to s p e c i f y a r e f e r e n c e b e t w e e n s e p a r a t e p r o g r a m u n i t s .
T h e d a t a s t r u c t u r e lets y o u h a v e a n a m e l o n g e r t h a n 1 6 M b y t e s , a l t h o u g h t h e
l i n k e r restricts n a m e s to 2 5 5 c h a r a c t e r s . W h e n y o u l i n k t h e o b j e c t files i n t o a
s i n g l e l o a d file, y o u m u s t e n s u r e t h a t all e x t e r n a l r e f e r e n c e s m a t c h c o r r e s p o n d ing external definitions. T h e external reference may b e of byte size, w o r d , or
long w o r d ; external definitions refer to relocatable values, absolute values, or
r e s i d e n t libraries. R e l o c a t a b l e b y t e a n d w o r d r e f e r e n c e s r e f e r t o P C r e l a t i v e
a d d r e s s m o d e s a n d t h e s e a r e e n t i r e l y h a n d l e d b y t h e l i n k e r . H o w e v e r , if y o u
h a v e a program containing long w o r d relocatable references, relocation m a y
take place w h e n y o u load the program.
N o t e t h a t t h e s e s i z e s o n l y r e f e r t o t h e l e n g t h o f t h e r e l o c a t i o n field; it is
possible to load a w o r d from a long external address, for e x a m p l e , a n d the
l i n k e r m a k e s n o a t t e m p t to c h e c k t h a t y o u a r e c o n s i s t e n t i n y o u r u s e of
externals.
Object
File
A n a s s e m b l e r or c o m p i l e r p r o d u c e s a b i n a r y i m a g e , called a n o b j e c t file.
An
o b j e c t file c o n t a i n s
one or more
p r o g r a m u n i t s . It m a y a l s o
contain
e x t e r n a l r e f e r e n c e s t o o t h e r o b j e c t files.
Load
File
T h e l i n k e r p r o d u c e s a b i n a r y i m a g e f r o m a n u m b e r of o b j e c t files. T h i s
binary
image
is
called
load
file.
load
file
does
not
contain
any
A p r o g r a m u n i t is t h e s m a l l e s t e l e m e n t t h e l i n k e r c a n h a n d l e . A
pro-
Unit
g r a m u n i t c a n c o n t a i n o n e or m o r e h u n k s ; o b j e c t files c a n c o n t a i n o n e o r
more
program
units.
If
the
linker
finds
suitable
external
reference
w i t h i n a p r o g r a m u n i t w h e n it i n s p e c t s t h e s c a n n e d libraries, it i n c l u d e s
t h e e n t i r e p r o g r a m u n i t in t h e l o a d file. A n a s s e m b l e r u s u a l l y p r o d u c e s a
single program unit from one assembly (containing one or more h u n k s ) ; a
compiler such as F O R T R A N produces a p r o g r a m unit for each
main
program,
or Block Data. H u n k n u m b e r i n g
subroutine,
within
245
e a c h p r o g r a m u n i t ; t h e o n l y w a y y o u c a n r e f e r e n c e o t h e r p r o g r a m u n i t s is
through external references.
Hunks
A h u n k c o n s i s t s of a b l o c k of c o d e or d a t a , r e l o c a t i o n i n f o r m a t i o n , a n d a list
of d e f i n e d or r e f e r e n c e d e x t e r n a l s y m b o l s . D a t a h u n k s m a y s p e c i f y initialized
d a t a or u n i n i t i a l i z e d d a t a ( b s s ) . b s s h u n k s m a y c o n t a i n e x t e r n a l d e f i n i t i o n s
b u t n o e x t e r n a l r e f e r e n c e s n o r a n y v a l u e s r e q u i r i n g r e l o c a t i o n . If y o u p l a c e
initialized d a t a b l o c k s i n o v e r l a y s , t h e l i n k e r s h o u l d n o t n o r m a l l y a l t e r t h e s e
d a t a b l o c k s , s i n c e it r e l o a d s t h e m f r o m d i s k d u r i n g t h e o v e r l a y p r o c e s s . H u n k s
m a y b e n a m e d o r u n n a m e d , a n d t h e y m a y c o n t a i n a s y m b o l t a b l e in o r d e r to
provide symbolic debugging information. T h e y m a y also contain further
d e b u g g i n g i n f o r m a t i o n for t h e u s e of h i g h l e v e l l a n g u a g e d e b u g g i n g t o o l s .
E a c h h u n k within a p r o g r a m unit has a n u m b e r , starting from zero.
Resident
Library
246
unit
h e a d e r is a l s o a b l o c k w i t h t h i s f o r m a t .
T h e f o r m a t o f a p r o g r a m u n i t is a s f o l l o w s :
Program unit header block
hunks
T h e b a s i c f o r m a t o f a h u n k is a s f o l l o w s :
hunk name block
Relocatable block
Relocation information block
External symbol information block
S y m b o l table block
Debug block
End block
Y o u m a y o m i t all t h e s e b l o c k t y p e s , e x c e p t t h e e n d b l o c k .
T h e following subsections describe the format of each of t h e s e blocks. T h e
v a l u e o f t h e t y p e w o r d a p p e a r s in d e c i m a l a n d h e x a f t e r t h e t y p e n a m e , for
e x a m p l e , h u n k _ u n i t h a s t h e v a l u e 9 9 9 i n d e c i m a l a n d 3 E 7 in h e x .
hunk
247
unit
_ _ N _ _
N
long words
of
name
hunk
name
N
N
long words
of
name
248
hunk
code
N
N
long words
of
code
hunk
data
N
N
long words
of
data
hunk
bss
N
Figure 1-E: h u n k _ b s s (1003/3EB)
249
w h e r e N is t h e size of b l o c k y o u r e q u i r e in l o n g w o r d s . T h e m e m o r y u s e d f o r
b s s b l o c k s is z e r o e d b y t h e l o a d e r w h e n it is a l l o c a t e d .
T h e r e l o c a t a b l e b l o c k w i t h i n a h u n k m u s t b e o n e of h u n k c o d e , h u n k
data, or h u n k
bss.
2 . 2 . 6 hunk_reloc32 (1004/3EC)
A hunk
r e l o c 3 2 b l o c k s p e c i f i e s 32-bit r e l o c a t i o n t h a t t h e l i n k e r is t o p e r f o r m
w i t h i n t h e c u r r e n t relocatable b l o c k . T h e relocation i n f o r m a t i o n is a r e f e r e n c e to
a location within the current h u n k or any other within the program unit. Each
h u n k w i t h i n t h e unit is n u m b e r e d , starting f r o m z e r o . T h e linker a d d s t h e a d d r e s s
of t h e b a s e of t h e specified h u n k to e a c h of the l o n g w o r d s in t h e p r e c e d i n g relocatable block that the list of offsets indicates. T h e offset list only includes r e f e r e n c e d
h u n k s a n d a c o u n t of z e r o i n d i c a t e s t h e e n d of t h e list. Its f o r m a t is a s f o l l o w s :
hunk
reloc32
Nl
Hunk Number 1
Nl
offsets
_N2_
Hunk Number 2
N2
offsets
_Nn_
Hunk Number n
Nn
offsets
250
2 . 2 . 7 hunkrelocl6 (1005/3ED)
A hunk
w i t h t h e s a m e n a m e , s o t h a t t h e l i n k e r c a n p e r f o r m t h e r e l o c a t i o n w h i l e it
c o a g u l a t e s ( t h a t i s , g a t h e r s t o g e t h e r ) similarly n a m e d h u n k s .
r e l o c 8 b l o c k s p e c i f i e s 8-bit r e l o c a t i o n t h a t t h e l i n k e r s h o u l d p e r f o r m
w i t h i n t h e c u r r e n t r e l o c a t a b l e b l o c k . T h e r e l o c a t i o n i n f o r m a t i o n r e f e r s to 8-bit
p r o g r a m c o u n t e r r e l a t i v e r e f e r e n c e s t o o t h e r h u n k s in t h e p r o g r a m u n i t . T h e
f o r m a t is t h e s a m e a s h u n k
reloc32 blocks. T h e s e references m u s t b e to h u n k s
w i t h t h e s a m e n a m e , s o t h a t t h e l i n k e r c a n p e r f o r m t h e r e l o c a t i o n w h i l e it
c o a g u l a t e s similarly n a m e d h u n k s .
hunk
ext
Symbol
data
unit
Symbol
data
unit
251
T h e t y p e b y t e s p e c i f i e s w h e t h e r t h e s y m b o l is a d e f i n i t i o n o r a r e f e r e n c e , a n d
s o f o r t h . A m i g a D O S u s e s v a l u e s 0 - 1 2 7 for s y m b o l d e f i n i t i o n s , a n d 1 2 8 - 2 5 5 f o r
references.
A t t h e m o m e n t , t h e v a l u e s are as f o l l o w s :
Name
ext
symb
ext
def
ext
abs
ext
res
ext_ref32
ext
common
ext
refl6
ext: ref8
Value
0
1
2
3
129
130
131
132
Meaning
Symbol tablesee symbol block below
Relocatable definition
Absolute definition
R e s i d e n t library d e f i n i t i o n
32-bit r e f e r e n c e t o s y m b o l
32-bit r e f e r e n c e t o C O M M O N
16-bit r e f e r e n c e to s y m b o l
8-bit r e f e r e n c e to s y m b o l
252
def/abs/res
Symbol value
ext__ref32/16/8
typ J N a m e Length N L
N L long words
of symbol n a m e
C o u n t of references N R
N L long words
of symbol references
ext
common
130 J_N_ame_Length N L
N L long words
of symbol n a m e
_Size_of c o m m o n b l o c k
C o u n t of references N R
N R long words
of symbol references
253
2.2.10 hunksymbol
(1008/3F0)
hunk
symbol
Symbol
data
unit
L _ 9. L ^ L " ? ^ t
2
i}%
N L long words
of symbol n a m e
Symbol value
254
2.2.11 hunk_Jebug
(1009/3F1)
A m i g a D O S p r o v i d e s t h e d e b u g b l o c k s o t h a t a n o b j e c t file c a n c a r r y f u r t h e r
d e b u g g i n g i n f o r m a t i o n . F o r e x a m p l e , h i g h level l a n g u a g e c o m p i l e r s m a y n e e d
t o m a i n t a i n d e s c r i p t i o n s of d a t a s t r u c t u r e s for u s e b y h i g h level d e b u g g e r s . T h e
d e b u g b l o c k m a y h o l d this i n f o r m a t i o n . A m i g a D O S d o e s n o t i m p o s e a f o r m a t
o n t h e d e b u g b l o c k e x c e p t t h a t it m u s t start w i t h t h e h u n k
a n d b e f o l l o w e d b y a l o n g w o r d that i n d i c a t e s t h e size of t h e b l o c k in l o n g w o r d s .
T h u s t h e f o r m a t is as f o l l o w s :
hunk
debug
N
N
long words
of
debug data
end.
255
Primary node
O v e r l a y table b l o c k (*)
O v e r l a y n o d e s s e p a r a t e d b y b r e a k b l o c k s (*)
T h e r e l o c a t i o n b l o c k s w i t h i n t h e h u n k s are a l w a y s of t y p e h u n k r e l o c 3 2 , a n d
i n d i c a t e t h e r e l o c a t i o n to b e p e r f o r m e d at l o a d t i m e . T h i s i n c l u d e s b o t h t h e 3 2 bit r e l o c a t i o n s p e c i f i e d w i t h h u n k r e l o c 3 2 b l o c k s in t h e o b j e c t file a n d e x t r a
r e l o c a t i o n r e q u i r e d f o r t h e r e s o l u t i o n of e x t e r n a l s y m b o l s .
E a c h e x t e r n a l r e f e r e n c e in t h e o b j e c t files is h a n d l e d a s f o l l o w s . T h e l i n k e r
s e a r c h e s t h e p r i m a r y i n p u t f o r a m a t c h i n g e x t e r n a l d e f i n i t i o n . If it d o e s n o t f i n d
o n e , it s e a r c h e s t h e s c a n n e d library a n d i n c l u d e s in t h e l o a d file t h e e n t i r e
p r o g r a m unit w h e r e the definition was defined. This m a y m a k e further extern a l r e f e r e n c e s b e c o m e o u t s t a n d i n g . A t t h e e n d of t h e first p a s s , t h e l i n k e r
k n o w s all t h e e x t e r n a l d e f i n i t i o n s a n d t h e total n u m b e r of h u n k s t h a t it is g o i n g
t o u s e . T h e s e i n c l u d e t h e h u n k s w i t h i n t h e l o a d file a n d t h e h u n k s a s s o c i a t e d
w i t h t h e r e s i d e n t libraries. O n t h e s e c o n d p a s s , t h e l i n k e r p a t c h e s t h e l o n g w o r d
e x t e r n a l r e f e r e n c e s s o t h a t t h e y r e f e r to t h e r e q u i r e d o f f s e t w i t h i n t h e h u n k
w h i c h d e f i n e s t h e s y m b o l . It p r o d u c e s a n e x t r a e n t r y in t h e r e l o c a t i o n b l o c k s o
t h a t , w h e n t h e h u n k s a r e l o a d e d , it a d d s to e a c h e x t e r n a l r e f e r e n c e t h e b a s e
a d d r e s s of t h e h u n k d e f i n i n g t h e s y m b o l . T h i s m e c h a n i s m a l s o w o r k s f o r
r e s i d e n t libraries.
Before the loader can make these cross-hunk
n u m b e r a n d size of t h e h u n k s in t h e n o d e s .
i n f o r m a t i o n , a s d e s c r i b e d b e l o w . T h e l o a d file
m a t i o n in a n o v e r l a y table b l o c k . B r e a k b l o c k s
r e f e r e n c e s , it n e e d s to k n o w t h e
The header block provides this
m a y also contain overlay inforseparate the overlay nodes.
256
T h e n e x t l o n g w o r d F r e f e r s to t h e first slot in t h e h u n k t a b l e t h e l o a d e r
should use w h e n loading. For a primary n o d e that does not reference a
r e s i d e n t library, t h i s v a l u e is z e r o ; o t h e r w i s e , it is t h e n u m b e r of h u n k s in t h e
r e s i d e n t libraries. T h e l o a d e r c o p i e s t h e s e e n t r i e s f r o m t h e h u n k table a s s o c i a t e d w i t h t h e library f o l l o w i n g a library o p e n call. F o r a n o v e r l a y n o d e , t h i s
v a l u e is t h e n u m b e r of h u n k s in a n y r e s i d e n t libraries p l u s t h e n u m b e r of
h u n k s a l r e a d y l o a d e d in a n c e s t o r n o d e s .
T h e n e x t l o n g w o r d L r e f e r s to t h e last h u n k slot t h e l o a d e r is t o l o a d a s p a r t
o f t h i s l o a d e r call. T h e total n u m b e r of h u n k s l o a d e d is t h e r e f o r e L - F + 1.
hunk
header
_N1_
N l long words
of n a m e
_N2_
N2 long words
of n a m e
0
T a b l e size
First H u n k F
Last H u n k L
L-F + 1
sizes
2.3.2 hunk
257
overlay (1013/3F5)
T h e o v e r l a y table b l o c k i n d i c a t e s to t h e l o a d e r t h a t it is l o a d i n g a n o v e r l a i d
p r o g r a m , a n d c o n t a i n s all t h e d a t a f o r t h e o v e r l a y t a b l e . O n e n c o u n t e r i n g it,
the loader sets u p the table, a n d returns, leaving the input channel to the load
file still o p e n . Its f o r m a t is a s f o l l o w s :
hunk
overlay
T a b l e size
_ _M +_2_ _
M +
zeros
Overlay
data
table
2.4 Examples
T h e f o l l o w i n g s i m p l e s e c t i o n s of c o d e s h o w h o w t h e l i n k e r a n d l o a d e r h a n d l e
external symbols. For example,
258
IDNT
XREF
A
BILLY, JOHN
XDEF
MARY
* The next long word requires relocation
0000' 0000 0008
DC.L
FRED
0 0 0 4 ' 1 2 3 C OOFF
MOVE.B
#$FF,D1
0008'7001
F R E D MOVEQ
#1,D0
*External entry point
000A'4E71
M A R Y NOP
000C 4EB9 0000 0000
JSR
BILLY
Call e x t e r n a l
0012' 2239 0000 0000
M0VE.L JOHN.D1 Reference external
END
p r o d u c e s t h e f o l l o w i n g o b j e c t file:
hunk
unit
00000001
Size i n l o n g w o r d s
41000000
Name, padded to long w o r d
hunk
code
00000006
Size i n l o n g w o r d s
00000008 123C00FF 70014E71 4EB90000 00002239
hunk-reloc32
00000001
Number in hunk 0
00000000
hunk 0
00000000
Offset to b e r e l o c a t e d
00000000
Zero to m a r k end
hunk
ext
01000001
X D E F , Size 1 long w o r d
4D415259
MARY
Offset of definition
0000000A
X R E F , Size 1 long w o r d
81000001
4A4F484E
JOHN
N u m b e r of references
00000001
Offset of r e f e r e n c e
00000014
81000002
42494C4C
59000000
00000001
0000000E
00000000
hunk
end
X R E F , Size 2 long w o r d s
BILLY
(zeros to pad)
Number of references
Offset o f r e f e r e n c e
E n d of e x t e r n a l block
T h e m a t c h i n g p r o g r a m to t h i s is as f o l l o w s :
00000000
IDNT
XDEF
XREF
0 0 0 0 ' 2A3C AAAA AAAA
* External entry point
0006' 4E71
* External entry point
0008' 7201
M0VE.L
259
B
BILLY,J0HN
MARY
#$AAAAAAAAJD5
BILLY
NOP
JOHN"
MOVEQ
#1,D1
JMP
END
MARY
*Call e x t e r n a l r e f e r e n c e
000A' 4EF9 0000 0000
Size i n l o n g w o r d s
Unit n a m e
00000004
Size i n l o n g w o r d s
2A3CAAAA AAAA4E71 7 2 0 1 4 E F 9
hunk
ext
01000001
4A4F484E
00000008
01000002
42494C4C
59000000
00000006
81000001
4D415259
00000001
0000000C
00000000
hunk
end
00000000
X D E F , Size 1 long w o r d
JOHN
Offset o f d e f i n i t i o n
X D E F , Size 2 long w o r d s
BILLY
(zeros to pad)
Offset o f d e f i n i t i o n
X R E F , Size 1 long w o r d
MARY
N u m b e r of references
Offset o f r e f e r e n c e
E n d of e x t e r n a l block
O n c e y o u p a s s e d t h i s t h r o u g h t h e l i n k e r , t h e l o a d file w o u l d h a v e
following format:
hunk
header
00000000
No h u n k n a m e
00000002
Size of h u n k table
00000000
First hunk
00000001
Last h u n k
the
260
00000006
Size of hunk 0
00000004
Size of hunk 1
hunk code
0 0 0 0 0 0 0 6 Size of code in long words
0 0 0 0 0 0 0 8 123C00FF 70014E71 4EB90000 0 0 0 6 2 2 3 9 0 0 0 0 0 0 0 8
hunk reloc32
00000001
Number in hunk 0
00000000
hunk 0
00000000
Offset to be relocated
00000002
Number in hunk 1
00000001
hunk 1
00000014
Offset to be relocated
0000000E
Offset to be relocated
00000000
Zero to mark end
hunk end
hunk code
00000004
Size of code in long words
2A3CAAAA AAAA4E71 72014EF9 0000000A
hunk reloc32
00000001
Number in hunk 0
00000000
hunk 0
0000000C
Offset to be relocated
00000000
Zero to mark end
hunk end
W h e n t h e l o a d e r l o a d s t h i s c o d e i n t o m e m o r y , it r e a d s t h e h e a d e r b l o c k a n d
a l l o c a t e s a h u n k t a b l e o f t w o l o n g w o r d s . It t h e n a l l o c a t e s s p a c e b y c a l l i n g a n
operating system routine a n d requesting t w o areas of sizes 6 and 4 long words
r e s p e c t i v e l y . A s s u m i n g t h e t w o a r e a s it r e t u r n e d w e r e at l o c a t i o n s 3 0 0 0 a n d
7000, the h u n k table w o u l d contain 3000 a n d 7000.
T h e l o a d e r r e a d s t h e first h u n k a n d p l a c e s t h e c o d e at 3 0 0 0 ; it t h e n h a n d l e s
r e l o c a t i o n . T h e first i t e m s p e c i f i e s r e l o c a t i o n w i t h r e s p e c t t o h u n k 0 , s o it a d d s
3 0 0 0 to t h e l o n g w o r d at o f f s e t 0 c o n v e r t i n g t h e v a l u e s t o r e d t h e r e f r o m 0 0 0 0 0 0 0 8
to 00003008. T h e s e c o n d item specifies relocation with respect to h u n k
1.
A l t h o u g h t h i s is n o t l o a d e d , w e k n o w t h a t it will b e l o a d e d at l o c a t i o n 7 0 0 0 , s o
t h i s is a d d e d to t h e v a l u e s s t o r e d at 3 0 0 E a n d 3 0 1 4 . N o t e t h a t t h e l i n k e r h a s
already inserted the offsets 00000006 a n d 00000008 into the references in h u n k
0 s o t h a t t h e y r e f e r t o t h e c o r r e c t o f f s e t i n h u n k 1 for t h e d e f i n i t i o n . T h u s t h e
long words specifying the external references e n d u p containing the values
0 0 0 0 7 0 0 6 a n d 0 0 0 0 7 0 0 8 , w h i c h is t h e c o r r e c t p l a c e o n c e t h e s e c o n d h u n k is
loaded.
In the s a m e w a y , the loader loads the second h u n k into m e m o r y at location
261
7 0 0 0 a n d t h e r e l o c a t i o n i n f o r m a t i o n s p e c i f i e d a l t e r s t h e l o n g w o r d at 7 0 0 C f r o m
0 0 0 0 0 0 0 A ( t h e o f f s e t o f M A R Y in t h e first h u n k ) to 0 0 0 0 3 0 0 A ( t h e a d d r e s s o f
M A R Y in m e m o r y ) .
T h e l o a d e r h a n d l e s r e f e r e n c e s t o r e s i d e n t libraries in t h e s a m e w a y , e x c e p t
t h a t , a f t e r it h a s o p e n e d t h e l i b r a r y , it c o p i e s t h e l o c a t i o n s o f t h e
hunks
c o m p r i s i n g t h e l i b r a r y i n t o t h e start o f t h e h u n k t a b l e . It t h e n p a t c h e s r e f e r e n c e s to t h e r e s i d e n t library to r e f e r t o t h e c o r r e c t p l a c e b y a d d i n g t h e b a s e o f
t h e library h u n k s .
Chapter 3
Introduction
Process Data Structures
Global Data Structure
Info Substructure
M e m o r y Allocation
S e g m e n t Lists
File H a n d l e s
Locks
Packets
Packet Types
3.1 Introduction
A m i g D O S p r o v i d e s d e v i c e i n d e p e n d e n t i n p u t a n d o u t p u t . It a c h i e v e s t h i s b y
creating a h a n d l e r process for each device y o u u s e . T h e handler process
a c c e p t s a s t a n d a r d s e t of I/O r e q u e s t s a n d c o n v e r t s t h e s e to d e v i c e specific
r e q u e s t s w h e r e r e q u i r e d . All A m i g a D O S clients r e f e r to t h e h a n d l e r p r o c e s s
r a t h e r t h a n t h e d e v i c e directly, a l t h o u g h it is p o s s i b l e to u s e a d e v i c e w i t h o u t
t h e h a n d l e r if this is r e q u i r e d . T h i s c h a p t e r d e s c r i b e s t h e d a t a s t r u c t u r e s w i t h i n
A m i g a D O S , i n c l u d i n g t h e f o r m a t of a p r o c e s s , c e n t r a l s h a r e d d a t a s t r u c t u r e s ,
a n d t h e s t r u c t u r e of h a n d l e r r e q u e s t s .
I n a d d i t i o n t o n o r m a l A m i g a v a l u e s s u c h as L O N G a n d A P T R , A m i g a D O S
u s e s B P T R . B P T R is a B C P L p o i n t e r , w h i c h is a p o i n t e r to a l o n g w o r d - a l i g n e d
m e m o r y b l o c k d i v i d e d b y 4 . S o , to r e a d a B P T R in C , y o u s i m p l y shift left b y 2 .
T o c r e a t e a B P T R , y o u m u s t e i t h e r u s e m e m o r y o b t a i n e d via a call to A l l o c M e m
or a s t r u c t u r e o n y o u r stack w h e n y o u k n o w y o u h a v e o n l y allocated l o n g w o r d s
263
Function
SegArray
StackSize
GlobVec
TaskNum
StackBase
IoErr
CurrentDir
CIS
COS
CoHand
FiHand
CLIStruct
ReturnAddr
PktWait
WindowPtr
Description
A r r a y of S e g L i s t s u s e d b y this p r o c e s s
S i z e of p r o c e s s s t a c k i n b y t e s
G l o b a l V e c t o r f o r this p r o c e s s
C L I T a s k n u m b e r or z e r o if n o t a C L I
P o i n t e r to h i g h m e m o r y e n d of p r o c e s s s t a c k
V a l u e of s e c o n d a r y r e s u l t f r o m last call
Lock associated with current directory
Current CLI input stream
Current CLI output stream
C o n s o l e h a n d l e r p r o c e s s for c u r r e n t w i n d o w
File h a n d l e r p r o c e s s f o r c u r r e n t d r i v e
P o i n t e r to a d d i t i o n a l C L I i n f o r m a t i o n
Pointer to previous stackframe
F u n c t i o n t o b e called w h e n a w a i t i n g m e s s a g e
Pointer to w i n d o w
264
s t a c k a C L I u s e s w h e n it calls a p r o g r a m .
its
c o m m a n d s t a c k j u s t b e f o r e it r u n s a p r o g r a m a n d y o u m a y alter t h e size o f t h i s
stack with the S T A C K c o m m a n d . W h e n y o u create a process,
AmigaDOS
obtains t h e process stack and stores the size in StackSize. T h e pointer to the
s p a c e for t h e p r o c e s s c o n t r o l b l o c k a n d t h e s t a c k is a l s o s t o r e d in t h e M e m E n t r y
f i e l d o f t h e t a s k s t r u c t u r e . W h e n t h e p r o c e s s t e r m i n a t e s t h i s s p a c e is r e t u r n e d
via a call t o F r e e M e m . Y o u c a n a l s o c h a i n a n y m e m o r y y o u o b t a i n i n t o t h i s list
s t r u c t u r e s o t h a t it, t o o , g e t s p u t b a c k w h e n t h e t a s k t e r m i n a t e s .
If a call to C r e a t e P r o c c r e a t e s t h e p r o c e s s , G l o b V e c is a p o i n t e r to t h e S h a r e d
Global Vector. H o w e v e r , s o m e internal handler processes u s e a private G l o b V e c .
T h e v a l u e o f T a s k N u m is n o r m a l l y z e r o ; a C L I p r o c e s s s t o r e s t h e
small
i n t e g e r t h a t i d e n t i f i e s t h e i n v o c a t i o n of t h e C L I h e r e .
T h e pointer StackBase points to t h e h i g h - m e m o r y e n d of t h e process stack.
T h i s is t h e e n d o f t h e s t a c k w h e n u s i n g l a n g u a g e s s u c h a s C o r A s s e m b l e r ; it is
t h e b a s e o f t h e s t a c k for l a n g u a g e s s u c h as B C P L .
T h e v a l u e s o f I o E r r a n d C u r r e n t D i r are t h o s e h a n d l e d b y t h e similarly n a m e d
A m i g a D O S calls. C I S a n d C O S a r e t h e v a l u e s I n p u t a n d O u t p u t r e t u r n a n d
r e f e r to t h e file h a n d l e s y o u s h o u l d u s e w h e n r u n n i n g a p r o g r a m u n d e r t h e
C L I . I n o t h e r c a s e s C I S a n d C O S are z e r o .
C o H a n d a n d F i H a n d refer to the console h a n d l e r for the current w i n d o w a n d
t h e file h a n d l e r f o r t h e c u r r e n t d e v i c e . Y o u u s e t h e s e v a l u e s w h e n a t t e m p t i n g
t o o p e n t h e * d e v i c e o r a file b y a r e l a t i v e p a t h n a m e .
T h e C L I S t r u c t p o i n t e r is n o n z e r o o n l y for C L I p r o c e s s e s . I n t h i s c a s e it r e f e r s
to a f u r t h e r s t r u c t u r e t h e C L I u s e s w i t h t h e f o l l o w i n g f o r m a t :
Value
Function
Description
LONG
Result2
V a l u e o f I o E r r f r o m last c o m m a n d
BSTR
SetName
N a m e of current directory
BPTR
CommandDir
LONG
ReturnCode
R e t u r n c o d e f r o m last c o m m a n d
BSTR
CommandName
N a m e of current c o m m a n d
LONG
FailLevel
Fail l e v e l (set b y F A I L A T )
BSTR
Prompt
C u r r e n t p r o m p t (set b y P R O M P T )
BPTR
Standardln
BPTR
Currentln
Value
BSTR
LONG
LONG
BPTR
LONG
BPTR
BPTR
Function
Description
CommandFile
Interactive
Background
CurrentOut
DefaultStack
StandardOut
Module
N a m e of E X E C U T E c o m m a n d file
B o o l e a n ; T r u e if p r o m p t s r e q u i r e d
B o o l e a n ; T r u e if C L I c r e a t e d b y R U N
Current CLI output
S t a c k size to b e o b t a i n e d (in l o n g w o r d s )
Default (terminal) CLI output
S e g L i s t of c u r r e n t l y l o a d e d c o m m a n d
265
T h e Exit f u n c t i o n u s e s t h e v a l u e of R e t u m A d d r w h i c h p o i n t s t o j u s t a b o v e
t h e r e t u r n a d d r e s s o n t h e c u r r e n t l y active s t a c k . If a p r o g r a m exits b y p e r f o r m i n g a n R T S o n a n e m p t y s t a c k , t h e n c o n t r o l p a s s e s to t h e c o d e a d d r e s s p u s h e d
o n t o t h e s t a c k b y C r e a t e P r o c o r b y t h e C L I . If a p r o g r a m t e r m i n a t e s w i t h a call
t o Exit, t h e n A m i g a D O S u s e s t h i s p o i n t e r t o e x t r a c t t h e s a m e r e t u r n a d d r e s s .
T h e v a l u e o f P k t W a i t is n o r m a l l y z e r o . If it is n o n z e r o , t h e n A m i g a D O S calls
P k t W a i t w h e n e v e r a p r o c e s s is a b o u t to g o to s l e e p to a w a i t a s i g n a l i n d i c a t i n g
that a m e s s a g e h a s arrived. In the s a m e way as G e t M s g , the function should
r e t u r n a m e s s a g e w h e n o n e is a v a i l a b l e . U s u a l l y , y o u u s e t h i s f u n c t i o n t o filter
o u t a n y p r i v a t e m e s s a g e s arriving at t h e s t a n d a r d p r o c e s s m e s s a g e p o r t t h a t
are not i n t e n d e d for A m i g a D O S .
T h e v a l u e of W i n d o w P t r is u s e d w h e n A m i g a D O S d e t e c t s a n e r r o r t h a t
normally requires the u s e r to take s o m e action. Examples of these errors are
a t t e m p t i n g to w r i t e to a w r i t e - p r o t e c t e d d i s k , or w h e n t h e d i s k is full. If t h e
v a l u e of W i n d o w P t r is - 1 , t h e n t h e e r r o r is r e t u r n e d to t h e calling p r o g r a m as
a n e r r o r c o d e f r o m t h e A m i g a D O S call of O p e n , W r i t e , or w h a t e v e r . If t h e
v a l u e is z e r o , t h e n A m i g a D O S p l a c e s a r e q u e s t b o x o n t h e W o r k b e n c h s c r e e n
i n f o r m i n g t h e u s e r of t h e e r r o r a n d p r o v i d i n g t h e o p p o r t u n i t y to r e t r y t h e
o p e r a t i o n or to c a n c e l it. If t h e u s e r s e l e c t s c a n c e l , t h e n A m i g a D O S r e t u r n s t h e
e r r o r c o d e to t h e calling p r o g r a m . If t h e u s e r s e l e c t s r e t r y , o r i n s e r t s a d i s k ,
then A m i g a D O S attempts the operation once more.
If y o u p l a c e a p o s i t i v e v a l u e i n t o t h e W i n d o w P t r f i e l d , t h e n A m i g a D O S t a k e s
t h i s to b e a p o i n t e r to a W i n d o w s t r u c t u r e . N o r m a l l y y o u w o u l d p l a c e t h e
W i n d o w s t r u c t u r e of t h e w i n d o w y o u a r e c u r r e n t l y u s i n g h e r e . In this c a s e ,
A m i g a D O S displays the error m e s s a g e within the w i n d o w y o u have specified,
rather than using the W o r k b e n c h screen. You can always leave the W i n d o w P t r
field as z e r o , b u t if y o u a r e u s i n g a n o t h e r s c r e e n , t h e n t h e m e s s a g e s A m i g a D O S
displays a p p e a r o n the W o r k b e n c h s c r e e n , possibly o b s c u r e d b y y o u r o w n s c r e e n .
T h e initial v a l u e of W i n d o w P t r is i n h e r i t e d f r o m t h e p r o c e s s t h a t c r e a t e d t h e
c u r r e n t o n e . If y o u d e c i d e t o alter W i n d o w P t r f r o m w i t h i n a p r o g r a m t h a t r u n s
u n d e r t h e C L I , t h e n y o u s h o u l d s a v e t h e original v a l u e a n d r e s t o r e it w h e n y o u
finish; otherwise, the CLI process contains a W i n d o w P t r that refers to
w i n d o w t h a t is n o l o n g e r p r e s e n t .
266
Function
Description
BPTR
TaskTable
BPTR
CLISegList
S e g L i s t for t h e C L I
LONG
Days
N u m b e r o f d a y s in c u r r e n t t i m e
LONG
Mins
LONG
Ticks
BPTR
RestartSeg
BPTR
Info
N u m b e r of m i n u t e s i n c u r r e n t t i m e
N u m b e r o f ticks i n c u r r e n t t i m e
SegList for the disk validator process
Pointer to the Info substructure
T h e T a s k T a b l e is a n a r r a y w i t h t h e size o f t h e a r r a y s t o r e d in T a s k T a b l e [ 0 ] .
T h e p r o c e s s i d (in o t h e r w o r d s , t h e M s g P o r t a s s o c i a t e d w i t h t h e p r o c e s s ) f o r
e a c h C L I is s t o r e d in t h e a r r a y . T h e p r o c e s s i d for t h e C L I w i t h T a s k N u m " n " is
s t o r e d i n T a s k T a b l e [ n ] . A n e m p t y slot is filled w i t h a z e r o . T h e
commands
R U N a n d N E W C L I s c a n t h e T a s k T a b l e to i d e n t i f y t h e n e x t f r e e s l o t , a n d u s e
t h i s as t h e T a s k N u m for t h e C L I c r e a t e d .
T h e C L I S e g L i s t is t h e S e g L i s t for t h e c o d e of t h e C L I . R U N a n d N E W C L I u s e
this value to create a n e w instance of a CLI.
T h e rootnode stores the current date a n d time; normally y o u should use the
A m i g a D O S function D a t e S t a m p to return a consistent set of values. T h e values
D a y s , M i n s , a n d T i c k s s p e c i f y t h e d a t e a n d t i m e . T h e v a l u e o f D a y s is t h e
n u m b e r o f d a y s s i n c e J a n u a r y 1st, 1 9 7 8 . T h e v a l u e o f M i n s is t h e n u m b e r o f
m i n u t e s s i n c e m i d n i g h t . A tick is o n e fiftieth of a s e c o n d , b u t t h e t i m e is o n l y
updated once per second.
T h e R e s t a r t S e g is t h e S e g L i s t f o r t h e c o d e o f t h e d i s k v a l i d a t o r , w h i c h is a
process that A m i g a D O S creates w h e n e v e r you insert a n e w disk into a drive.
267
Function
Description
BPTR
BPTR
McName
Devlnfo
N e t w o r k n a m e of this m a c h i n e ; currently z e r o
D e v i c e list
BPTR
Devices
Currently zero
BPTR
Handlers
Currently zero
APTR
NetHand
M o s t o f t h e fields i n t h e I n f o s u b s t r u c t u r e a r e e m p t y a t t h e m o m e n t ,
but
C o m m o d o r e - A m i g a i n t e n d to u s e t h e m f o r e x p a n d i n g t h e s y s t e m .
T h e D e v l n f o s t r u c t u r e is a l i n k e d list. Y o u u s e it t o i d e n t i f y all t h e d e v i c e
n a m e s that A m i g a D O S k n o w s about; this includes A S S I G N e d n a m e s and disk
v o l u m e n a m e s . T h e r e a r e t w o p o s s i b l e f o r m a t s f o r t h e list e n t r i e s d e p e n d i n g o n
w h e t h e r t h e e n t r y r e f e r s to a d i s k v o l u m e or n o t . F o r a n e n t r y d e s c r i b i n g a
d e v i c e or a d i r e c t o r y (via A S S I G N ) t h e e n t r y is a s f o l l o w s :
Value
Function
Description
BPTR
Next
P o i n t e r to n e x t list e n t r y o r z e r o
LONG
Type
List e n t r y t y p e ( d e v i c e o r dir)
APTR
Task
BPTR
Lock
File s y s t e m l o c k or z e r o
BSTR
Handler
File n a m e o f h a n d l e r or z e r o
LONG
StackSize
S t a c k size f o r h a n d l e r p r o c e s s
LONG
Priority
LONG
Startup
BPTR
SegList
S e g L i s t for h a n d l e r p r o c e s s o r z e r o
BPTR
GlobVec
BSTR
Name
N a m e of device or A S S I G N e d n a m e
d e v i c e ) or 1 (dt
dir). Y o u c a n m a k e a d i r e c t o r y e n t r y
w i t h t h e A S S I G N c o m m a n d . T h i s c o m m a n d a l l o c a t e s a n a m e to a d i r e c t o r y t h a t
y o u c a n t h e n u s e as a d e v i c e n a m e . If t h e list e n t r y r e f e r s t o a d i r e c t o r y , t h e n
t h e T A S K r e f e r s t o t h e file s y s t e m p r o c e s s h a n d l i n g t h a t d i s k , a n d t h e L o c k
field c o n t a i n s a p o i n t e r t o a l o c k o n t h a t d i r e c t o r y .
If t h e list e n t r y r e f e r s to a d e v i c e , t h e n t h e d e v i c e m a y or m a y n o t
be
r e s i d e n t . If it is r e s i d e n t , t h e T a s k i d e n t i f i e s t h e h a n d l e r p r o c e s s , a n d t h e L o c k
268
is n o r m a l l y z e r o . If t h e d e v i c e is n o t r e s i d e n t , t h e n t h e T A S K is z e r o
and
A m i g a D O S u s e s t h e r e s t o f t h e list s t r u c t u r e .
If t h e S e g L i s t is z e r o , t h e n t h e c o d e f o r t h e d e v i c e is n o t i n m e m o r y .
The
H a n d l e r f i e l d is a s t r i n g s p e c i f y i n g t h e file c o n t a i n i n g t h e c o d e (for e x a m p l e ,
S Y S : L / R A M - H A N D L E R ) . A call t o L o a d S e g l o a d s t h e c o d e f r o m t h e file a n d
inserts the result into the SegList field.
A M i g a D O S n o w creates a n e w handler process with the SegList, StackSize,
a n d P r i v a l u e s . T h e n e w p r o c e s s is a B C P L p r o c e s s a n d r e q u i r e s a G l o b a l
V e c t o r ; t h i s is e i t h e r t h e v a l u e y o u s p e c i f i e d i n G l o b V e c o r a n e w p r i v a t e g l o b a l
v e c t o r if G l o b V e c is z e r o .
The
new
p r o c e s s is p a s s e d
a message
containing
the n a m e
originally
s p e c i f i e d , t h e v a l u e s t o r e d i n S t a r t u p a n d t h e b a s e o f t h e list e n t r y .
The
to the
device
name
use
the
same
handler
refer-
task; this is w h a t
the
o f t h e list s t r u c t u r e is s l i g h t l y d i f f e r e n t .
Value
Function
Description
BPTR
Next
P o i n t e r t o n e x t list e n t r y or z e r o
LONG
Type
APTR
Task
H a n d l e r p r o c e s s or z e r o
BPTR
Lock
File s y s t e m l o c k
LONG
VolDays
V o l u m e creation date
LONG
VolMins
LONG
VolTicks
BPTR
LockList
L i s t o f active l o c k s for t h i s v o l u m e
LONG
DiskType
T y p e of disk
LONG
Spare
Not used
BSTR
Name
Volume name
I n t h i s c a s e , t h e N a m e field is t h e n a m e o f t h e v o l u m e , a n d t h e T a s k field
r e f e r s t o t h e h a n d l e r p r o c e s s if t h e v o l u m e is c u r r e n t l y i n s e r t e d ; o r t o z e r o if t h e
v o l u m e is n o t i n s e r t e d . T o d i s t i n g u i s h d i s k s w i t h t h e s a m e n a m e , A m i g a D O S
t i m e s t a m p s t h e v o l u m e o n c r e a t i o n a n d t h e n s a v e s t h e t i m e s t a m p i n t h e list
structure. A m i g D O S can therefore c o m p a r e the t i m e s t a m p s of different volumes whenever necessary.
I f a v o l u m e i s n o t c u r r e n t l y i n s e r t e d , t h e n A m i g a D O S s a v e s t h e list o f c u r r e n t l y a c t i v e l o c k s i n t h e L o c k L i s t f i e l d . It u s e s t h e D i s k T y p e f i e l d to i d e n t i f y
269
t h e t y p e o f d i s k . C u r r e n t l y , t h i s is a l w a y s a n A m i g a D O S d i s k . T h e d i s k t y p e
is u p t o f o u r c h a r a c t e r s p a c k e d i n t o a l o n g w o r d a n d p a d d e d o n t h e r i g h t
with nulls.
Function
Description
LONG
BlockSize
Size of m e m o r y block
LONG
FirstData
First d a t a s e g m e n t , B P T R to b l o c k p o i n t s h e r e
Function
Description
LONG
NextSeg
B P T R to n e x t s e g m e n t or z e r o
LONG
FirstCode
First v a l u e f r o m b i n a r y file
270
Value
LONG
LONG
LONG
BPTR
LONG
LONG
APTR
APTR
APTR
LONG
LONG
Function
Link
Interact
ProcessID
Buffer
CharPos
BufEnd
ReadFunc
WriteFunc
CloseFunc
Argl
Arg2
Description
Not used
B o o l e a n , T R U E if i n t e r a c t i v e
P r o c e s s id of h a n d l e r p r o c e s s
Buffer for internal u s e
Character position for internal use
E n d p o s i t i o n for i n t e r n a l u s e
Function called w h e n buffer exhausted
F u n c t i o n called w h e n b u f f e r full
F u n c t i o n called w h e n h a n d l e c l o s e d
A r g u m e n t ; d e p e n d s o n file h a n d l e t y p e
A r g u m e n t ; d e p e n d s o n file h a n d l e t y p e
M o s t of t h e fields a r e o n l y u s e d b y A m i g a D O S i n t e r n a l l y ; n o r m a l l y R e a d or
W r i t e u s e s t h e file h a n d l e t o i n d i c a t e t h e h a n d l e r p r o c e s s a n d a n y a r g u m e n t s t o
b e p a s s e d . V a l u e s s h o u l d n o t b e a l t e r e d w i t h i n t h e file h a n d l e b y u s e r p r o g r a m s , e x c e p t t h a t t h e first field m a y b e u s e d t o link file h a n d l e s i n t o a s i n g l y
l i n k e d list.
T h i s d e s c r i p t i o n d o e s N O T m a t c h d o s e x t e n s . h o r .i. U s e t h e i n c l u d e file
information instead.
3.7 Locks
T h e filing s y s t e m e x t e n s i v e l y u s e s a d a t a s t r u c t u r e called a l o c k . T h i s s t r u c t u r e
s e r v e s t w o p u r p o s e s . F i r s t , it s e r v e s a s t h e m e c h a n i s m to o p e n files f o r m u l t i p l e r e a d s or a s i n g l e w r i t e . N o t e t h a t o b t a i n i n g a s h a r e d r e a d l o c k o n a
directory does not stop that directory being updated.
S e c o n d , t h e l o c k p r o v i d e s a u n i q u e i d e n t i f i c a t i o n f o r a file. A l t h o u g h a
p a r t i c u l a r file m a y b e s p e c i f i e d in m a n y w a y s , t h e l o c k is a s i m p l e h a n d l e o n
t h a t file. T h e l o c k c o n t a i n s t h e actual d i s k b l o c k l o c a t i o n of t h e d i r e c t o r y o r file
h e a d e r a n d is t h u s a s h o r t h a n d w a y of s p e c i f y i n g a p a r t i c u l a r file s y s t e m
o b j e c t . T h e s t r u c t u r e of a l o c k is as f o l l o w s :
Value
BPTR
LONG
LONG
APTR
BPTR
Function
NextLock
DiskBlock
AccessType
ProcessID
VolNode
Description
B P T R to next in chain, else zero
B l o c k n u m b e r of d i r e c t o r y or file h e a d e r
Shared or exclusive access
P r o c e s s id of h a n d l e r t a s k
V o l u m e e n t r y for this lock
B e c a u s e A m i g a D O S u s e s t h e N e x t L o c k field to c h a i n l o c k s t o g e t h e r , y o u
s h o u l d n o t alter it. T h e filing s y s t e m fills i n D i s k B l o c k field to r e p r e s e n t t h e
271
l o c a t i o n o n d i s k o f t h e d i r e c t o r y b l o c k or t h e file h e a d e r b l o c k . T h e A c c e s s T y p e
s e r v e s to i n d i c a t e w h e t h e r t h i s is a s h a r e d r e a d l o c k , w h e n it h a s t h e v a l u e - 2 ,
or a n e x c l u s i v e w r i t e l o c k w h e n it h a s t h e v a l u e - 1 . T h e P r o c e s s I D f i e l d
c o n t a i n s a p o i n t e r t o t h e h a n d l e r p r o c e s s for t h e d e v i c e c o n t a i n i n g t h e file t o
w h i c h t h i s l o c k r e f e r s . F i n a l l y t h e V o l N o d e field p o i n t s to t h e n o d e in t h e
D e v l n f o structure that identifies the v o l u m e to w h i c h this lock refers. V o l u m e
e n t r i e s i n t h e D e v l n f o s t r u c t u r e r e m a i n t h e r e if a d i s k is i n s e r t e d o r if t h e r e a r e
a n y locks o p e n on that volume.
N o t e that a lock can also b e a zero. T h e special case of lock z e r o indicates
t h a t t h e l o c k r e f e r s to t h e r o o t o f t h e initial filing s y s t e m , a n d t h e F i H a n d f i e l d
within the process data structure gives the handler process.
3.8 Packets
P a c k e t p a s s i n g h a n d l e s all c o m m u n i c a t i o n p e r f o r m e d b y A m i g a D O S b e t w e e n
p r o c e s s e s . A p a c k e t is a s t r u c t u r e b u i l t o n t o p o f t h e m e s s a g e - p a s s i n g m e c h a nism provided by the Exec kernel.
A n E x e c m e s s a g e is a s t r u c t u r e , d e s c r i b e d e l s e w h e r e , t h a t i n c l u d e s a N a m e
f i e l d . A m i g a D O S u s e s t h e field a s a n A P T R to a n o t h e r s e c t i o n o f m e m o r y
called a packet. A packet m u s t be long word aligned, a n d h a s the following
general structure.
Value
Function
APTR
MsgPtr
APTR
MsgPort
Description
LONG
PktType
LONG
Resl
First r e s u l t field
LONG
Res2
S e c o n d r e s u l t field
LONG
Argl
LONG
Arg2
LONG
ArgN
T h e f o r m a t o f a s p e c i f i c p a c k e t d e p e n d s o n its t y p e ; b u t i n all c a s e s , it
contains a b a c k pointer to t h e M e s s a g e structure, t h e M g s P o r t for t h e reply,
a n d t w o r e s u l t f i e l d s . W h e n A m i g a D O S s e n d s a p a c k e t , t h e r e p l y p o r t is
overwritten with the process identifier of t h e s e n d e r so that the packet c a n b e
returned. Thus, w h e n sending a packet to an A m i g a D O S handler process, you
m u s t fill in t h e r e p l y M s g P o r t e a c h t i m e ; o t h e r w i s e , w h e n t h e p a c k e t r e t u r n s ,
A m i g a D O S h a s o v e r w r i t t e n t h e original p o r t . A m i g a D O S m a i n t a i n s all o t h e r
fields except the result fields.
A l l A m i g a D O S p a c k e t s a r e s e n t to t h e m e s s a g e p o r t c r e a t e d a s p a r t o f a
272
p r o c e s s ; t h i s m e s s a g e p o r t is i n i t i a l i z e d s o t h a t a r r i v i n g m e s s a g e s c a u s e s i g n a l 8
t o b e s e t . A n A m i g a D O S p r o c e s s w h i c h is w a i t i n g f o r a m e s s a g e w a i t s f o r
signal 8 to b e set. W h e n the process w a k e s u p b e c a u s e this e v e n t h a s occurred,
G e t M s g takes the m e s s a g e from the message port and extracts the
packet
a d d r e s s . If t h e p r o c e s s is a n A m i g a D O S h a n d l e r p r o c e s s , t h e n t h e
packet
argument
fields c o n t a i n
specific
i n f o r m a t i o n s u c h a s t h e a d d r e s s a n d size o f t h e b u f f e r w h e r e t h e c h a r a c t e r s
goW h e n t h e h a n d l e r process h a s completed t h e w o r k required to satisfy this
request, the packet returns to the sender, using the s a m e m e s s a g e structure.
Both the message structure and the packet structure must be allocated b y the
client a n d m u s t not b e deallocated before the reply has b e e n received. N o r m a l l y A m i g a D O S is c a l l e d b y t h e c l i e n t t o s e n d t h e p a c k e t , s u c h a s w h e n a call
t o R e a d is m a d e . H o w e v e r , t h e r e a r e c a s e s w h e n a s y n c h r o n o u s I O is r e q u i r e d ,
a n d in this case the client m a y s e n d packets to the handler processes
required. T h e packet and message structures must be allocated, and
as
the
p r o c e s s i d f i e l d filled i n w i t h t h e m e s s a g e p o r t w h e r e t h i s p a c k e t m u s t r e t u r n .
A call t o P u t M s g t h e n s e n d s t h e m e s s a g e to t h e d e s t i n a t i o n . N o t e t h a t m a n y
packets m a y b e sent out returning to either the same or different
message
ports.
in m o s t c a s e s ) . T o o b t a i n
this
additional
i n f o r m a t i o n , y o u c a n call I o E r r w h e n m a k i n g a s t a n d a r d A m i g a D O S call.
LONG
Action.PindInput ( 1 0 0 5 )
Argl
Arg2
Arg3
BPTR
BPTR
BSTR
FileHandle
Lock
Name
Resl
LONG
Boolean
A t t e m p t s to o p e n a n e x i s t i n g file f o r i n p u t o r o u t p u t ( s e e t h e f u n c t i o n O p e n
i n C h a p t e r 2 , " C a l l i n g A m i g a D O S , " o f t h e AmigaDOS
Developer's
Manual
in this
b o o k f o r f u r t h e r d e t a i l s o n o p e n i n g files f o r I / O ) . T o o b t a i n t h e v a l u e o f l o c k ,
273
you call DeviceProc to obtain the handler Processld and then IoErr which
returns the lock. Alternatively the lock and Processld can be obtained directly
from the Devlnfo structure. Note that the lock refers to the directory owning
the file, not to the file itself.
The caller must allocate and initialize FileHandle. This is done by clearing all
fields to zero except for the CharPos and BufEnd fields which should be set to
-1. The ProcessID field within the FileHandle must be set to the process id of
the handler process.
The result is zero if the call failed, in which case the Res2 field provides more
information on the failure and the FileHandle should be released.
LONG
BPTR
BPTR
BSTR
Action. FindOutput ( 1 0 0 6 )
FileHandle
Lock
Name
Resl
LONG
Boolean
Read
Type
LONG
Action.Read ( 8 2 )
Argl
Arg2
Arg3
BPTR
APTR
LONG
FileHandle Argl
Buffer
Length
Resl
LONG
Actual Length
To read from a file handle, the process id is extracted from the ProcessID
field of the file handle, and the Argl field from the handle is placed in the Argl
field of the packet. The buffer address and length are then placed in the other
two argument fields. The result indicates the number of characters readsee
the function Read for more details. An error is indicated by returning -1
whereupon the Res2 field contains more information.
Write
Type
LONG
Action.Write ( 8 7 )
Argl
Arg2
Arg3
BPTR
APTR
LONG
FileHandle Argl
Buffer
Length
Resl
LONG
Actual Length
274
The arguments are the same as those for Read. See the Write function for
details of the result field.
Close
Type
LONG
Action.End ( 1 0 0 7 )
Argl
BPTR
FileHandle Argl
Resl
LONG
TRUE
You use this packet type to close an open file handle. The process id of the
handler is obtained from the file handle. The function normally returns TRUE.
After a file handle has been closed, the space associated with it should be
returned to the free pool.
Seek
Type
LONG
Actlon.Seek ( 1 0 0 8 )
Argl
Arg2
Arg3
BPTR
LONG
LONG
FlleHandle Argl
Position
Mode
Resl
LONG
OldPosition
This packet type corresponds to the SEEK call. It returns to the old position,
or -1 if an error occurs. The process id is obtained from the file handle.
WaitChar
Type
LONG
Action.WaitChar ( 2 0 )
Argl
LONG
Timeout
Resl
LONG
Boolean
This packet type implements the WaitForChar function. You must send the
packet to a console handler process, with the timeout required in Argl. The
packet returns when either a character is waiting to be read, or when the
timeout expires. If the result is TRUE, then at least one character may be
obtained by a subsequent READ.
ExamineObj ect
Type
LONG
Action.ExamineObject ( 2 3 )
Argl
Arg2
BPTR
BPTR
Lock
FilelnfoBlock
Resl
LONG
Boolean
275
This packet type implements the Examine function. It extracts the process id
of the handler from the ProcessID field of the lock. If the lock is zero, then it
uses the default file handler, which is kept in the FiHand field of the process.
The result is zero if it fails, with more information in Res2. The FilelnfoBlock
returns with the name and comment fields as BSTRs.
ExamineNext
Type
Argl
Arg2
LONG
BPTR
BPTR
Action.ExamineNext ( 2 4 )
Lock
FilelnfoBlock
Resl
LONG
Boolean
This call implements the ExNext function, and the arguments are similar to
those for Examine above. Note that the BSTR representing the filename must
not be disturbed between calls of ExamineObject and different calls to
ExamineNext, as it uses the name as a place saver within the directory being
examined.
Disklnfo
Type
LONG
Action.DiskInfo ( 2 5 )
Argl
BPTR
InfoData
Resl
LONG
TRUE
This implements the Info function. A suitable lock on the device would
normally obtain the process id for the handler. This packet can also be sent to a
console handler process, in which case the Volume field in the InfoData
contains the window pointer for the window opened on your behalf by the
console handler.
Parent
Type
LONG
Action.Parent ( 2 9 )
Argl
BPTR
Lock
Resl
LONG
ParentLock
This packet returns a lock representing the parent of the specified lock, as
provided by the ParentDir function call. Again it must obtain the process id of
the handler from the lock, or from the FiHand field of the current process if the
lock is zero.
276
DeleteObject
Type
Argl
Arg2
LONG
BPTR
BSTR
Action.DeleteObject ( 1 6 )
Lock
Name
Resl
LONG
Boolean
This packet type implements the Delete function. It must obtain the
lock from a call to IoErr() immediately following a successful call to DeviceProc which returns the process id. The lock actually refers to the directory
owning the object to be deleted, as in the Open New and Open Old
requests.
CreateDir
Type
LONG
Action.CreateDir ( 2 2 )
Argl
Arg2
BPTR
BSTR
Lock
Name
Resl
BPTR
Lock
This packet type implements the CreateDir function. Arguments are the
same as for DeleteObject. The result is zero or a lock representing the new
directory.
LocateObject
Type
LONG
Action.LocateObject ( 8 )
Argl
Arg2
Arg3
BPTR
BSTR
LONG
Lock
Name
Mode
Resl
BPTR
Lock
This implements the lock function and returns the lock or zero. Arguments
as for CreateDir with the addition of the Mode as Arg3. Mode refers to the type
of lock, shared or exclusive.
CopyDir
Type
LONG
Action.CopyDir ( 1 9 )
Argl
BPTR
Lock
Resl
BPTR
Lock
277
FreeLock
Type
LONG
Action.FreeLock ( 1 5 )
Argl
BPTR
Lock
Resl
LONG
Boolean
This call implements the UnLock function. It obtains the process id from the
lock. Note that freeing the zero lock takes no action.
SetProtect
Type
LONG
Action.SetProtect ( 2 1 )
Argl
Arg2
Arg3
Arg4
Not used
BPTR
Lock
BSTR
Name
LONG Mask
Resl
LONG
Boolean
This implements the SetProtection function. The lock is a lock on the owning
directory obtained from DeviceProc as described for DeleteObject above. The
least significant four bits of "Mask" represent Read, Write, Execute, and Delete
in that order. Delete is bit zero.
SetComxnent
Type
LONG
Action.SetComment ( 2 8 )
Argl
Arg2
Arg3
Arg4
Not used
BPTR
Lock
BSTR
Name
BSTR
Comment
Resl
LONG
Boolean
278
RenameObject
Type
Argl
Arg2
Arg3
Arg4
LONG
BPTR
BPTR
BPTR
BPTR
Action.RenameObject ( 1 7 )
FromLock
FromName
ToLock
ToName
Resl
LONG
Boolean
Inhibit
Type
LONG
Action.Inhibit ( 3 1 )
Argl
LONG
Boolean
Resl
LONG
Boolean
This packet type implements a filing system operation that is not available as
an AmigaDOS call. The packet contains a Boolean value indicating whether
the filing system is to be stopped from attempting to verify any new disks
placed into the drive handled by that handler process. If the Boolean is
true, then you may swap disks without the filesystem process attempting to
verify the disk. While disk change events are inhibited, the disk type is
marked as "Not a DOS disk" so that other processes are prevented from
looking at the disk.
If the Boolean is false, then the file system reverts to normal after having
verified the current disk in the drive.
This request is useful if you wish to write a program such as DISKCOPY
where there is much swapping of disks that may have a half completed
structure. If you use this packet request then you can avoid having error messages
from the disk validator while it attempts to scan a half completed disk.
RenameDisk
Type
LONG
Action.RenameDisk ( 9 )
Argl
BFTR
NewName
Resl
Again,
tion call.
currently
packet is
BPTR
Boolean
this implements an operation not normally available through a funcThe single argument indicates the new name required for the disk
mounted in the drive handled by the filesystem process where the
sent. The volume name is altered both in memory and on the disk.
Chapter 4
AmigaDOS Additional
Information for the Advanced
Developer
This chapter describes certain topics which are likely to be of interest to the
advanced developer who may wish to create new devices to be added to the
Amiga or who wish their code to run with Amiga computers which have been
expanded beyond a 512K memory size.
The following topics are covered here:
Overlay Hunk Description
for developers putting together large programs
ATOM utility
works on a new binary file format to change allow developer to set the
appropriate load bits. Assures that program code and data that must be
resident in CHIP memory (the lowest 512K of the system) for the program
to function will indeed be placed there by AmigaDOS when it is loaded.
Otherwise the program code may not work on an extended memory
machine.
Linking in a new DISK-device to AmigaDOS
lets a developer add a hard disk or disk-like device as a name-addressable
part of the filing system.
Linking in a new non-disk-device to AmigaDOS
lets a developer add such things as additional serial ports, parallel ports,
graphics tablets, RAM-disks or what-have-you to AmigaDOS (non filing
system related).
Using AmigaDOS without using Intuition
for developers who may prefer to install and use their own screen handling in place of that provided by Intuition.
280
Hunk Overlay
TableOverview
When overlays are used, the linker basically produces one very large file
containing all of the object modules as hunks of relocatable code. The hunk
overlay table contains a data structure that describes the hunks and their
relationship to each other.
When you are designing a program to use overlays, you must keep in mind
how the overlay manager (also called the overlay supervisor) handles the
interaction between the various segments of the file. What you must do,
basically, is build a tree that reflects the relationships between the various code
modules that are a part of the overall program and tell the linker how this tree
should be constructed.
The hunk overlay table is generated as a set of 8 long words, each describing a particular overlay node that is part of the overall file. Each 8 long word
entry is comprised of the following data:
HUNK OVERLAY SYMBOL TABLE-ENTRY DATA STRUCTURE:
long seekOffset;
/* where in the file to find this node */
long dummyl;
/* a value of 0 . . . compatibility item */
long dummy2;
/* a value of 0 . . . compatibility item */
long level;
/* level in the tree */
long ordinate;
/* item number at that level */
long firstHunk;
/* hunk number of the first hunk containing
* this node. */
long symbolHunk;
/* the hunk number in which this symbol is
* located */
long symbolOffsetX; /* (offset + 4 ) , where offset is the offset
* within the symbol hunk at which this
* symbol's entry is located. */
Each of these items is explained further in the sections that follow.
Let's say that you have, for example, the files main, a, b, c, d, e, f, g, h, i, and j,
and that main can call a,b,c, and d and that each of these files can call main.
Additionally let's say that routine e can be called from a,b,c,d, or main, but has
no relationship to routine f. Thus, if a routine in e is to be run, then a,b,c, and
d need to be memory-resident as well. Routine f is like e; that is, it needs
nothing in e to be present, but can be called from a, b, c, or d. This means that
the overlay manager can share the memory space between routines e and f,
since neither need ever be memory-coresident with the other in order to run.
If you consider routine g to share the same space as the combination of a,b,c,
and d and routines h,i, and j sharing the same space, you have the basis for
constructing the overlay tree for this program structure:
281
f(2,2)
g (1,2).
h(2,l)
i(2,2)
)(2,3)
Not only have we drawn the tree, but we have labeled its branches to match
the hunk overlay (level, ordinate) numbers that are found in the hunk overlay
table that matches the nodes to which they are assigned.
From the description above, you can see that if main is to call any routine in
program segment a-d, then all of those segments should be resident in memory at the same time. Thus they have all been assigned to a single node by the
linker. While a-d are resident, if you call routines in e, the linker will automatically load routine e from disk, and reinitialize the module (each time it is again
brought in), so that its subroutines will be available to be run. If any segment
a-d calls a routine in f, the linker replaces e with the contents of f and
initializes it. Thus a-d are at level 1 in the overlay tree, and routines e and f are
at level 2, requiring that a-d be loaded before e or f can be accessed and loaded
for execution.
Note: A routine can only perform calls to routines in other nodes which
either are currently memory resident (the ancestors of the node in which the
routine now in use is located), or a routine in a direct child node. That is, main
cannot call e directly, but e can call routines in main since main is an ancestor.
Note also that within each branch of each subnode, the ordinate numbers
begin again withi number 1 for a given level.
This description tells the linker that a,b,c,d are part of a single node at a
given level (in this case level 1), and the asterisk in front of e and f each say
that these are one each on the next level down from a-d, and accessible only
through a-d or anything closer toward the root of the tree. The name g has no
asterisk, so it is considered on the same level as a-d, telling the linker that
282
Amount
The first value for each node in the overlay table is the seek offset. As
specified earlier, the overlay linker builds a large single file containing all of the
overlay nodes. The seek offset number is that value that can be given to the
seek(file, byte offset) routine to point to the first byte of the hunk header of a
node.
initialHunk
The initialHunk value in the overlay symbol table is used by the overlay
manager when unloading a node. It specifies the initial hunk that must have
been loaded in order to have loaded the node that contains this symbol. When
a routine is called at a different level and ordinate (unless it is a direct, next
level, child of the current node), it will become necessary to free the memory
utilized by invalid hunks, so as to make room to overlay with the hunk(s)
containing the desired symbol.
SymbolHunk
and
SymbolOffsetX
These table entries for the symbols are used by the overlay manager to
actually locate the entry point once it has either determined it is already loaded
or has loaded it. The symbolHunk shows in which hunk to locate the symbol.
SymbolOffsetX-4 shows the offset from the start of that hunk at which the
entry point is actually located.
This document describes the ATOM utility, including its development history,
the manner in which it has been implemented, and alternatives to its use.
The "problem":
Previous Solutions
The recommended way of dealing with this was to do an AllocMem with the
chip memory bit set and copy data from where it was loaded ("fast" memory)
to where it belonged (chip memory), then use pointers to get to it. This
involved having two copies of your data in memory, the first loaded with your
program, the second copied into the first 512K of memory.
The other "solution" is to have the program not run in machines with more
than 512K. This should quickly become an unacceptable solution.
283
Future Solutions
The assembler and Lattice " C " may be changed to generate the new hunk
types under programmer control.
The hunk size is a word containing the number of words in the hunk. Therefore, for the foreseeable future, including 32-bit address space machines, the
upper 2 bits are unused. The bits have been redefined as follows:
I
Bit31 MEMF FAST
|
j
Bit30 MEMFCHIP
0
0
If neither bit is set, then get whatever memory is available; this is
"backward" compatible. Preference is given to "Fast" memory.
1
0
Loader must get FAST memory, or fail.
0
1
Loader must get CHIP memory, or fail.
1
1
If Bit31 and Bit30 are both set, then there is extra information
available following this long word. This is reserved for future expansion, as needed. It is not currently used.
284
Perceived Impact
Old programs, programs that have not been compiled or assembled with the
new options, and programs that have not been run through ATOM will run (or
not run) as well as ever. This includes crashing in extended memory, if poorly
programmed. The "previous solutions" mentioned at the beginning of this
chapter still hold.
Program development and test on a 512K machine could follow EXACTLY
the same loop you have nowedit, compile, link, execute, test, edit, . . .
UNTIL you are about to release. Then you edit, compile, ATOM, Alink, add
external memory (>512K) and test. This works well for all three environments
(Amiga, IBM, and Sun).
For native (Amiga) development on a >512K machine you may want to
ATOM the few required object files so you can both run your linked program
in an extended memory machine and take advantage of a large RAM: disk. The
development cycle then becomes: edit, compile, optionally ATOM (if this code
or data contains items needed by the blitter), link, exteute, test, edit. . . .
"New programs" will not load in a VI.0 Kickstart environment. The result
will be error 103 (not enough memory).
Old (VI.0 and before) versions of dumpobj and OMD will not work on files
after ATOM has been run on them.
Working Environment
To get all of this to work together you need Release 1.1 compatible copies of:
ATOM (Version 1.0 or later)
Alink (Version 3.30 or later)
Kickstart (Release 1.1 or later) for DOS LOADER.
DumpObj (Version 2.1) Needed if you wish to examine programs modified by
ATOM.
[-P[CIDIB]]
Where:
<infile>
<outfile>
-C
-F
-P
C
D
B
285
In most cases there is no need to place CODE hunks in chip memory. Sometimes DATA and BSS hunks do need to be placed in chip memory; therefore
the following is a fairly common usage of ATOM. To cause all Code hunks to
go into Public RAM, Data and BSS hunks to go into chip RAM type:
ATOM infile.obj outfile.obj -pc -cdb
Example # 2
To cause all the hunks in object file to be loaded into chip memory type:
ATOM infile.obj outfile.obj -c
Example # 3
Example # 4
This is an interactive example. User input is in lower case, computer output is
in upper case. In this example the code hunk is set to "Fast", the data hunk is
set to "Chip". There were no BSS hunks. Note that help was requested in the
beginning.
2 > atom from.o from.set -i
AMIGA OBJECT MODIFIER VI.0
UNIT NAME FROM
HUNK NAME NONE
HUNK TYPE CODE
MEMORY ALLOCATION PUBLIC
DISPLAY SYMBOLS [Y/N] y
base..
xcovf.
_CXD22..
printf.
main...
MEMORY TYPE? [FlclP] ?
Please enter F for fast
C for Chip
P for Public
286
Q to quit
W to windup
N for Next hunk
MEMORY TYPE? [FfclP] f
UNIT NAME 0 0 0 0
HUNKNAME NONE
HUNK TYPE DATA
MEMORY ALLOCATION PUBLIC
DISPLAY SYMBOLS? [Y/N] n
MEMORY TYPE? [FfolP] c
UNIT NAME 0 0 0 0
HUNKNAME NONE
HUNK TYPE BSS
MEMORY ALLOCATION PUBLIC
DISPLAY SYMBOLS? [Y/N] y
MEMORY TYPE? [FiClP] p
2>_
Error Messages
287
Error This utility can only be used on files that have NOT been passed through
ALINK:
The input file you specified has already been processed by the linker.
External symbols have been removed and hunks coagulated. You need to
run ATOM on the object files produced by the C compiler or Macro
Assembler BEFORE they are linked.
the Amiga
ROM
Kernel
Manual.
Second, you must make this new device available as an AmigaDOS device.
This process involves writing a suitable device handler (see ROM Kernel Manual) and installing it into the AmigaDOS structures.
This installation is handled by creating a suitable device-node structure for
your new device. This is similar to creating a Devlnfo slot for a new disk
device, except that the startup argument can be anything you want. The
Segment list slot is zero, and the file name of your disk-resident device handler
is placed in the Filename slot.
0
0
0
0
BSTR
NNN
NN
XXX
0
0
BSTR
Next
dt device
Task (or process idsee below)
Lock
Filename of handler code
Stacksize required
Priority required
Startup information
SegList (nonzero if you load the code)
Global vector required
Device Name
The device handler is the interface between your device and an application
program. This is normally written in BCPL, and the AmigaDOS kernel will
attempt to load the code of the handler and create a new process for it when it
is first referenced. This is handled automatically when the kernel notices that
the Task field in the Devlnfo structure is zero. If the code is already loaded, the
code segment pointer is placed in the SegList field. If this field is zero, the
288
kernel loads the code from the filename given in the Filename field and
updates the SegList field.
If you want this automatic loading and process initialization to work, you
must create a code module, which is written in BCPL or is written in assembler
to look like a BCPL module. This ensures that the dynamic linking used by the
kernel will work correctly.
If you are writing in assembler, the format of the code section must be as
shown below. Note that you may use DATA and BSS sections, but each section
must have the same format as described here.
StartModule DC.L
EntryPoint
CNOP
DC.L
DC.L
DC.L
DC.L
END
"LIBHDR"
"IOHDR"
"MANHDR"
"EXECHDR"
LET read.pkt
LET write.pkt
LET openstring
LET inpkt
LET outpkt
LETIOB
LETIOBO
LET error
LET devname
LET open
LET node
289
0
0
parm.pktlpkt.argl
VEC pkt.resl
VEC pkt.resl
VEC IO.blocksize
VEC IO.blocksize
FALSE
"serial.device*XOO"
FALSE (flag to show whether device has been "opened"
with act.findinput or act.findoutput).
parm.pkt!pkt.arg3
(Zero the block first so that we can see what goes into it when we call
Opendevice.)
FOR i = 0 TO IO.blocksize DO IOBIi : = 0
IF OpenDevice ( IOB, devname, 0, 0 ) = 0 THEN error : = TRUE
IF error THEN
$( returnpkt (parm.pkt,FALSE,error,objectinuse)
return
$)
CASE act.fmdinput:
CASE act.findoutput:
$( LET scb = p!pkt.argl
open : = TRUE
scblscbld : = TRUE
returnpkt (p,TRUE)
LOOP
f)
(Open.)
(Interactive.)
290
CASE act.end:
nodeldev.task : = 0
open : = FALSE
returnpkt (p,TRTJE)
LOOP
(C!
(Close.)
(Ri
(Remove process id from device node.)
CASE act.read:
(Read request returning.)
inpkt: = p
handle.return (IOBO,read.pkt)
LOOP
CASE act.write:
(Write request returning.)
outpkt: = p
handle.return(IOBO,write.pkt)
LOOP
CASE 'R':
(A rread request.)
read.pkt: = p
handle.request(IOB,IOC.read,p,inpkt)
inpkt : = 0
LOOP
(A write request.)
CASE 'W:
write.pkt : = p
handle.request(IOBO,IOC.write,p,outpkt)
outpkt : = 0
LOOP
DEFAULT:
UNLESS open DO nodeldev.task : = 0 (Remove process id unless open.)
$)
291
Next
dt device
Task
Lock
Handler
Stacksize
Priority
Global vector
The BSTR to a name is a BCPL pointer to the name of your new device (such
as HDO:) represented as the length of the string in the first byte, and the
characters following.
The Seglist must be the segment list of the filing system task. To obtain
292
this, you must access a field in the process base of one of the filing system
tasks.
The code as follows can be used for this purpose:
TTBYTE *port;
port = DeviceProc( "DFO:");
/* Returns msg port of
filesystem task */
task = (struct Task *) (port-sizeof(struct Task); /* Task structure is
below port */
list = ( task.pr Seglist )
/* make machine ptr
from SegArray */
segl = list[3];
/* Third element in
SegArray is filesystem
seglist */
Next, you must set up the startup info (again, remember to use BPTRs
where needed). This info consists of a BPTR to three long words which
contain:
Unit number (do not use unit zero)
Device driver name, stored as a BPTR to the device driver name which
must be terminated by a null byte which is included in the count (e.g.,
4/'H7'D7'070) BPTR to disk information
The disk size information contains the following long word fields:
11
128
0
Number of surfaces
1
Number of blocks
per track
2
Size of table
Disk block size in long words (assuming 512-byte
blocksize)
Sector origin (i.e., first sector is sector zero)
(e.g., 2 for floppy disk)
Number of sectors per black
(e.g. 11 for floppy disk)
(or more, indicating number of blocks to be reserved
at start)
Preallocation factor
Interleave factor
(commonly 0)
0
0
Lowest cylinder
number
Highest cylinder
(e.g., 7 9 for floppy disk)
number
5
(or more, indicating number of cache blocks)
Finally, the device node must be attached to the end of the list (note the
Next fields are all BPTRs) of device nodes within the Info substructure.
293
WARNING: The list to which this refers is NOT the same kind of list
that is referenced in the Exec portion of the Amiga ROM Kernel
Manual,
but is instead the kind of list described in this book.
To partition a hard disk you make two or more device nodes and set the
lowest and highest cylinder numbers to partition the disk as desired.
Workbench/Intuition
294
Index
296
INDEX
Exchanging, 99-100
Execute (function), 183
EXECUTE (user's command), 54-63
Exit, 182, 265
ExNext (function), 173-174
Expressions, 192-194
Extended mode, 91, 153
External references, 244
External symbols, 205-206, 251, 258
INDEX
Input (function), 175
Input, console, 218-231
Input files, 136-137, 175
INSTALL (user's command), 68-69
Instructions, 187, 190-192, 196
Interruption, 18
IoErr, 175
Islnteractive (function), 175
Jumps, 187
Keyboard input, 219-220, 224
Keywords, 18-20, 153
LAB (user's command), 69
Labels, 69, 190-191
Letter case, 170
Libraries, 158, 170-185, 208, 245, 256, 266
Library base pointer, 266
Line deletions, 113, 114, 126-127
Line editor, 5 2 - 5 3 , 105-154
Line insertions, 114-115, 126-127
Line numbers, 109-110, 120, 122-123, 143
Line splitting and joining, 133-134
Line windows, 128-130, 153
Linker, 8 4 - 8 5 , 168-169, 207-231, 257
Linking, new disk device, 291-293
Linking, new non-disk device, 293-294
LIST (user's command or directive), 28, 6 9 - 7 2
Listing control directives, 201-203
Load file, 207, 244, 255-257
Loader, 257, 261
Loading code, 183-184, 185
LoadSeg (function), 183-184
LocateObject (call packet), 276
Location zero, 212
Lock (function), 175-176
Lock duplication, 173
Locks, 270-271
Logical devices, 14-16, 41, 43, 267
Logical position, 178
Long word, 187
Loops, 138-139
Macro assembler, 186-206
Macro directives, 204-205
MAKEDIR (user's command), 72
MAP output, 212
MC68000 assembly language, 85
Memory, 153, 183-184, 247-248, 269
Memory variant, 196
MS-DOS, 168
Multiple strings, 119-120
Multi-processing, 4 - 5 , 153
Object code, 41
Object files, 207, 208, 244, 246-254
Octal numbers, 194
Opcode field, 191
Open (function), 176
Open New File (call packet), 273
Open Old File (call packet), 272-273
Operand field, 191-192
Operand types, 192
Operand word, 187
Operation word, 187
Operators, 192
Output (function), 176
Output, console, 218-231
Output files, 137-138
Output processing, 124
Output queue, 153
OVERLAY (directive), 213-215
Overlay files, 208
Overlay nodes, 245, 257
Overlay number, 217
Overlay references, 216
Overlay supervisor, 207
Over table block, 257
Overlaying, 213
Packets, 271-278
Parallel port, 87
Parameter file, 208
Parameter substitution, 5 6 - 5 8
Parent (call packet), 275
ParentDir (function), 177, 275
Pointing variant, 131-132
Primary binary input, 208
Priority, 5, 153
Processes, 5, 154, 181-182, 263-266
Program control, 9 6 - 9 7
Program counter, 187
Program development, 158-159
Program encoding, 189-192
Program termination, 161
Program unit, 244-245, 246
Programming, 157-169
PROMPT (user's command), 74
Prompts, 74, 122
PROTECT (user's command), 29, 74-75
Qualified strings, 120, 123-124, 154
Qualifiers, 111-112, 154
297
298
QUIT (user's command), 75
INDEX
System disk, 41
System management, 89