The AmigaDOS Manual

The AmigaDOS Manual
Bantam Computer Books
A s k y o u r bookseller for the b o o k s you have missed
THE AMIGADOS USER'S MANUAL
b y C o m m o d o r e - A m i g a , Inc.
T H E A P P L E //c B O O K
b y Bill O ' B r i e n
T H E C O M M O D O R E 64 S U R V I V A L M A N U A L
b y W i n n L. R o s c h
C O M M O D O R E 128 P R O G R A M M E R ' S R E F E R E N C E G U I D E
b y C o m m o d o r e B u s i n e s s M a c h i n e s , Inc.
E X P L O R I N G A R T I F I C I A L I N T E L L I G E N C E O N Y O U R A P P L E II
b y T i m Hartnell
E X P L O R I N G A R T I F I C I A L I N T E L L I G E N C E O N Y O U R C O M M O D O R E 64
b y T i m Hartnell
EXPLORING THE UNIX ENVIRONMENT
b y T h e Waite G r o u p / Irene Pasternack
FRAMEWORK FROM THE GROUND UP
b y T h e Waite G r o u p / Cynthia Spoor a n d Robert Warren
H O W T O G E T T H E M O S T O U T O F C O M P U S E R V E , 2d e d .
b y Charles B o w e n a n d David P e y t o n
H O W TO GET THE M O S T OUT OF THE SOURCE
b y Charles B o w e n a n d David P e y t o n
THE MACINTOSH
b y Bill O ' B r i e n
T H E N E W jr. A G U I D E T O I B M ' S PC;>
b y W i n n L. R o s c h
ORCHESTRATING SYMPHONY
b y T h e Waite G r o u p / D a n Shafer
PC-DOS / MS-DOS
User's Guide to the Most Popular Operating System for Personal
Computers
b y Alan M . B o y d
P O W E R PAINTING: COMPUTER GRAPHICS O N THE MACINTOSH
b y V e r n e B a u m a n a n d Ronald Kidd / illustrated by G a s p e r Vaccaro
SMARTER TELECOMMUNICATIONS
Hands-On Guide to On-Line Computer
Services
b y Charles B o w e n a n d Stewart S c h n e i d e r
SWING WITH JAZZ:
Lotus jazz on the Macintosh
b y Data tech Publications C o r p . / Michael McCarty
U S E R ' S G U I D E T O T H E A T & T P C 6300 P E R S O N A L C O M P U T E R
b y David B . Peatroy, Ricardo A. Anzaldua, H . A. W o h l w e n d ,
a n d Data tech Publications C o r p .
The AmigaDOS
Manual
Commodore-Amiga, Inc.
BANTAM BOOKS
TORONTO • NEW YORK • LONDON • SYDNEY • AUCKLAND
AMIGADOS MANUAL
A Bantam Book I February
1986
Cover design by }. Caroff Associates
All rights reserved.
Copyright © 1986 by Commodore Capital, Inc.
This book may not be reproduced in whole or in part, by
mimeograph or any other means, without permission.
For information address: Bantam Books, Inc.
ISBN 0-553-34294-0
Published simultaneously
in the United States and Canada
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
H
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,
is a c o m b i n a t i o n of three separate publications:
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
ED—The Screen Editor
EDIT—The Line Editor
Appendix: Error Codes and Messages
Glossary
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 .
How to Enable the Command Line Interface
Boot your c o m p u t e r using t h e Kickstart a n d W o r k b e n c h diskettes. O p e n the
diskette icon. O p e n the " P r e f e r e n c e s " tool. N e a r the left-hand side of the
s c r e e n , a b o u t t w o - t h i r d s o f t h e w a y d o w n y o u will n o t i c e " C L I " w i t h a b u t t o n
f o r " O N " a n d a b u t t o n for " O F F " . S e l e c t t h e " O N " b u t t o n . S e l e c t
"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 .
How to Open a CLI Window
To use the CLI commands, you open a CLI window. O p e n the " S y s t e m "
d r a w e r . T h e C L I i c o n (a c u b e c o n t a i n i n g " 1 > " ) s h o u l d n o w b e v i s i b l e . O p e n
it.
Using the CLI
T o u s e t h e C L I i n t e r f a c e select t h e C L I w i n d o w a n d t y p e t h e d e s i r e d C L I
c o m m a n d s . T h e C L I w i n d o w ( s ) m a y b e s i z e d a n d m o v e d j u s t like m o s t o t h e r s .
To close the CLI w i n d o w , type " E N D C L I " .
INTRODUCTION
3
Workbench and CLI, Their Relationship and Differences
T y p e " D I R " to 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 d i s k
d i r e c t o r y . T h i s is a list of 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 are m o r e files in this 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 . W o r k b e n c h o n l y d i s p l a y s file " X " if t h a t file h a s a n a s s o c i a t e d " X . i n f o "
file. W o r k b e n c h u s e s t h e " . i n f o " file to m a n i p u l a t e t h e i c 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. T h e file " D i s k c o p y " c o n tains the p r o g r a m a n d " D i s k c o p y . i n f o " contains the W o r k b e n c h information
a b o u t it. I n t h e c a s e of p a i n t i n g d a t a files like " 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 ) . I n this c a s e , w h e n t h e u s e r " o p e n s " t h e d a t a
file ( m o u n t . p i c ) W o r k b e n c h r u n s t h e p r o g r a m a n d p a s s e s t h e d a t a file n a m e
( m o u n t . p i c ) t o it.
A m i g a D O S s u b d i r e c t o r i e s c o r r e s p o n d to W o r k b e n c h d r a w e r s . R a n d o m a c c e s s b l o c k d e v i c e s s u c h as d i s k s (DFO:) c o r r e s p o n d t o t h e d i s k e t t e i c o n s y o u
have seen.
N o t all p r o g r a m s or c o m m a n d s c a n b e r u n u n d e r b o t h W o r k b e n c h a n d t h e
C L I e n v i r o n m e n t . N o n e of t h e C L I c o m m a n d s d e s c r i b e d in C h a p t e r 2 of t h i s
m a n u a l can b e run from W o r k b e n c h . For example, there are t w o separate
D i s k c o p y c o m m a n d s . T h e o n e i n t h e :cl d i r e c t o r y is r u n f r o m A m i g a D O S ( C L I ) .
T h e o n e in t h e s y s t e m d i r e c t o r y ( d r a w e r ) is r u n f r o m W o r k b e n c h .
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
1.1 Chapter Overview
A m i g a D O S is a m u l t i - p r o c e s s i n g o p e r a t i n g s y s t e m d e s i g n e d f o r t h e A m i g a .
A l t h o u g h y o u c a n u s e it a s a m u l t i - u s e r s y s t e m , y o u n o r m a l l y r u n A m i g a D O S
f o r a s i n g l e u s e r . T h e m u l t i - p r o c e s s i n g facility lets m a n y j o b s t a k e p l a c e s i m u l -
INTRODUCING AMIGADOS
5
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 . )
1.2 Terminal Handling
Y o u c a n d i r e c t i n f o r m a t i o n t h a t y o u e n t e r at t h e t e r m i n a l t o a C o m m a n d L i n e
I n t e r f a c e ( C L I ) t h a t tells A m i g a D O S to l o a d a p r o g r a m , o r y o u c a n d i r e c t t h e
i n f o r m a t i o n to a p r o g r a m r u n n i n g u n d e r t h a t C L I . In e i t h e r c a s e , a t e r m i n a l (or
console) handler processes input and output. This terminal handler also perf o r m s local line e d i t i n g a n d c e r t a i n o t h e r f u n c t i o n s . Y o u c a n t y p e a h e a d a s
m a n y as 2 5 5 c h a r a c t e r s — t h e m a x i m u m line l e n g t h .
T o c o r r e c t m i s t a k e s , y o u p r e s s t h e B A C K S P A C E k e y . T h i s e r a s e s t h e last
character y o u typed. To rub out an entire line, hold d o w n the C T R L key while
y o u p r e s s X . T h i s control c o m b i n a t i o n is r e f e r r e d t o f r o m t h i s p o i n t o n in t h e
manual as CTRL-X.
If y o u t y p e a n y t h i n g , A m i g a D O S w a i t s until y o u h a v e f i n i s h e d t y p i n g b e f o r e
d i s p l a y i n g a n y o t h e r o u t p u t . B e c a u s e A m i g a D O S w a i t s f o r y o u to f i n i s h , y o u
can type ahead without your input and output becoming intermixed. 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 f i n i s h e d a line w h e n y o u p r e s s t h e R E T U R N k e y . Y o u
c a n also tell A m i g a D O S t h a t y o u h a v e f i n i s h e d w i t h a line b y c a n c e l l i n g it. T o
c a n c e l a l i n e , y o u c a n e i t h e r p r e s s C T R L - X or p r e s s B A C K S P A C E u n t i l all t h e
c h a r a c t e r s o n t h e line h a v e b e e n e r a s e d . O n c e A m i g a D O S is s a t i s f i e d t h a t y o u
6
AMIGADOS USER'S MANUAL
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 .
1.3 Using the Filing System
T h i s s e c t i o n d e s c r i b e s t h e A m i g a D O S filing s y s t e m . In p a r t i c u l a r , it e x p l a i n s
h o w to n a m e , o r g a n i z e , a n d recall y o u r files.
A file is t h e s m a l l e s t n a m e d o b j e c t u s e d b y A m i g a D O S . T h e s i m p l e s t identific a t i o n of a file is b y its f i l e n a m e , d i s c u s s e d b e l o w i n S e c t i o n 1 . 3 . 1 . H o w e v e r , it
m a y b e n e c e s s a r y t o i d e n t i f y a file m o r e fully. S u c h a n i d e n t i f i c a t i o n m a y
i n c l u d e t h e d e v i c e or v o l u m e n a m e , a n d / o r d i r e c t o r y n a m e ( s ) a s w e l l a s t h e
f i l e n a m e . T h e s e will b e d i s c u s s e d i n f o l l o w i n g s e c t i o n s .
1.3.1 Naming Files
A m i g a D O S h o l d s i n f o r m a t i o n o n d i s k s i n a n u m b e r of files, n a m e d s o t h a t y o u
c a n i d e n t i f y a n d recall t h e m . T h e filing s y s t e m a l l o w s f i l e n a m e s to h a v e u p t o
thirty characters, w h e r e the characters m a y be any printing character except
s l a s h (/) a n d c o l o n (:). T h i s m e a n s t h a t y o u c a n i n c l u d e s p a c e ( ) , e q u a l s ( = ) ,
p l u s ( + ) , a n d d o u b l e q u o t e ( " ) , all s p e c i a l c h a r a c t e r s r e c o g n i z e d b y t h e C L I ,
w i t h i n a f i l e n a m e . H o w e v e r , if y o u u s e t h e s e special c h a r a c t e r s , y o u m u s t
INTRODUCING AMIGADOS
7
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 .
1.3.2 Using Directories
T h e filing s y s t e m also a l l o w s t h e u s e of d i r e c t o r i e s as a w a y t o g r o u p files
t o g e t h e r i n t o logical u n i t s . F o r e x a m p l e , y o u m a y u s e t w o d i f f e r e n t d i r e c t o r i e s
to s e p a r a t e p r o g r a m s o u r c e f r o m p r o g r a m d o c u m e n t a t i o n , o r t o k e e p files
b e l o n g i n g t o o n e p e r s o n distinct f r o m t h o s e b e l o n g i n g t o a n o t h e r .
E a c h file o n a d i s k m u s t b e l o n g to a d i r e c t o r y . A n e m p t y d i s k c o n t a i n s o n e
d i r e c t o r y , called t h e root d i r e c t o r y . If y o u c r e a t e a file o n a n e m p t y d i s k , t h e n
t h a t file b e l o n g s t o t h i s r o o t d i r e c t o r y . H o w e v e r , d i r e c t o r i e s m a y t h e m s e l v e s
c o n t a i n f u r t h e r d i r e c t o r i e s . E a c h d i r e c t o r y m a y t h e r e f o r e c o n t a i n f i l e s , or y e t
m o r e d i r e c t o r i e s , or a m i x t u r e of b o t h . A n y f i l e n a m e is u n i q u e o n l y w i t h i n t h e
d i r e c t o r y it b e l o n g s t o , s o t h a t t h e file " f r e d " i n t h e d i r e c t o r y " b i l l " is a c o m p l e t e l y d i f f e r e n t file f r o m t h e o n e called " f r e d " i n t h e d i r e c t o r y " m a r y " .
T h i s filing s t r u c t u r e m e a n s t h a t t w o p e o p l e s h a r i n g a d i s k d o n o t h a v e to
w o r r y a b o u t a c c i d e n t a l l y o v e r w r i t i n g files c r e a t e d b y s o m e o n e e l s e , as l o n g as
t h e y a l w a y s c r e a t e files i n t h e i r o w n d i r e c t o r i e s .
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.
8
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
Figure 1-A: Using Directory Structure
N o t e : T h e d i r e c t o r y " b i l l " h a s a file c a l l e d " l e t t e r , " w h i l e 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 d i r e c t o r y called " l e t t e r " . H o w e v e r , t h e r e is n o c o n f u s i o n
h e r e b e c a u s e b o t h files a r e in d i f f e r e n t d i r e c t o r i e s . T h e r e is n o limit to t h e
depth that y o u can " n e s t " directories.
T o s p e c i f y a file fully, y o u m u s t i n c l u d e t h e d i r e c t o r y t h a t o w n s it, t h e
d i r e c t o r y o w n i n g t h a t d i r e c t o r y , a n d s o o n . T o s p e c i f y a file, y o u give t h e
n a m e s of all t h e d i r e c t o r i e s o n t h e p a t h to t h e d e s i r e d file. T o s e p a r a t e e a c h
directory n a m e from the next directory or filename, y o u type a following slash
(/). T h u s , t h e full s p e c i f i c a t i o n o f t h e d a t a files o n t h e d i s k s h o w n in F i g u r e 1-A
a b o v e is as f o l l o w s :
bill/text
bill/letter
mary/data
mary/letter/junl8
mary/lnvoice/junl 8
1.3.3 Setting the Current Directory
A full file d e s c r i p t i o n c a n g e t e x t r e m e l y c u m b e r s o m e to t y p e , s o t h e filing
s y s t e m m a i n t a i n s t h e i d e a of a c u r r e n t d i r e c t o r y . T h e filing s y s t e m s e a r c h e s f o r
files i n t h i s 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 t h e c u r r e n t d i r e c t o r y , y o u u s e t h e C D
( C u r r e n t D i r e c t o r y ) c o m m a n d . If y o u h a v e s e t " m a r y " a s y o u r c u r r e n t d i r e c t o r y ,
t h e n t h e f o l l o w i n g n a m e s w o u l d b e sufficient to specify t h e files in that d i r e c t o r y :
INTRODUCING AMIGADOS
9
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.
2.3.4 Setting the Current Device
Finally, y o u m a y h a v e m a n y disk drives available. E a c h disk device h a s a
n a m e , i n t h e f o r m D F n (for e x a m p l e , D F 1 ) , w h e r e t h e " n " r e f e r s t o t h e n u m b e r
o f t h e d e v i c e . ( C u r r e n t l y , A m i g a D O S a c c e p t s t h e d e v i c e n a m e s DFO t o D F 3 . )
10
AMIGADOS USER'S MANUAL
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
Figure 1-B: The Structure of a File Description
SYS c o m m a n d s
DFO:bill
DFLmary/letter
DF2:mary/letter/junl8
DOC:report/sectionl/figures
FOMTS:smy-font
C:cls
Figure 1-C: Examples of File Descriptions
T o g a i n a c c e s s t o a file o n a p a r t i c u l a r d i s k , y o u c a n t y p e its u n i q u e n a m e ,
w h i c h is k n o w n a s t h e d i s k ' s v o l u m e n a m e , i n s t e a d of t h e d e v i c e n a m e . F o r
i n s t a n c e , if t h e file is o n t h e d i s k " M C C " , y o u c a n s p e c i f y t h e s a m e file b y
typing the n a m e " M C G p e t e r / p r o j e c t - r e p o r t " . Y o u can use the v o l u m e n a m e to
r e f e r to a d i s k r e g a r d l e s s of t h e drive it is i n . Y o u a s s i g n a v o l u m e n a m e to a
d i s k w h e n y o u f o r m a t it (for f u r t h e r d e t a i l s , s e e " F O R M A T " in C h a p t e r 2 ,
" C o m m a n d s , " later in t h i s m a n u a l ) .
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 " .
1.3.5 Attaching a Filenote
A l t h o u g h a f i l e n a m e c a n g i v e s o m e i n f o r m a t i o n a b o u t its c o n t e n t s , it is o f t e n
n e c e s s a r y t o l o o k in t h e file itself t o f i n d o u t m o r e . A m i g a D O S p r o v i d e s a
s i m p l e s o l u t i o n t o this p r o b l e m . Y o u c a n u s e t h e c o m m a n d c a l l e d F I L E N O T E
to attach a n associated c o m m e n t . Y o u can m a k e u p a c o m m e n t of u p to 80
c h a r a c t e r s ( y o u m u s t e n c l o s e c o m m e n t s c o n t a i n i n g s p a c e s in d o u b l e q u o t e s ) .
A n y t h i n g c a n b e p u t in a file c o m m e n t : t h e d a y of t h e file's c r e a t i o n , w h e t h e r
or n o t a b u g h a s b e e n f i x e d , t h e v e r s i o n n u m b e r of a p r o g r a m , a n d a n y t h i n g
e l s e t h a t m a y h e l p t o i d e n t i f y it.
Y o u m u s t a s s o c i a t e a c o m m e n t w i t h a p a r t i c u l a r f i l e — n o t all files h a v e t h e m .
T o a t t a c h c o m m e n t s , y o u u s e t h e F I L E N O T E c o m m a n d . If y o u c r e a t e a n e w
file, it will n o t h a v e a c o m m e n t . E v e n if t h e n e w file is a c o p y of a file t h a t h a s a
c o m m e n t , t h e c o m m e n t is n o t c o p i e d t o t h e n e w file. H o w e v e r , a n y c o m m e n t
a t t a c h e d to a file w h i c h is o v e r w r i t t e n is r e t a i n e d . T o w r i t e a p r o g r a m t o c o p y a
file a n d its c o m m e n t , y o u ' l l h a v e to d o s o m e e x t r a w o r k to c o p y t h e c o m m e n t .
F o r d e t a i l s , s e e C h a p t e r 2 of t h e AmigaDOS
Developer's
Manual.
W h e n y o u r e n a m e a file, t h e c o m m e n t a s s o c i a t e d w i t h it d o e s n ' t c h a n g e . T h e
R E N A M E c o m m a n d o n l y c h a n g e s t h e n a m e o f a file. T h e file's c o n t e n t s a n d
c o m m e n t r e m a i n t h e s a m e r e g a r d l e s s of t h e n a m e c h a n g e . F o r m o r e d e t a i l s ,
s e e L I S T a n d F I L E N O T E in C h a p t e r 2 of t h i s m a n u a l .
2.3.6 Understanding Device Names
D e v i c e s h a v e n a m e s s o t h a t y o u c a n r e f e r to t h e m b y n a m e . D i s k n a m e s s u c h
a s DFO: a r e e x a m p l e s of d e v i c e n a m e s . N o t e t h a t y o u m a y r e f e r t o d e v i c e
n a m e s , like f i l e n a m e s , u s i n g e i t h e r u p p e r o r l o w e r c a s e . F o r d i s k s , y o u f o l l o w
t h e d e v i c e n a m e b y a f i l e n a m e b e c a u s e A m i g a D O S s u p p o r t s files o n t h e s e
devices. Furthermore, the filename can include directories because A m i g a D O S
also supports directories.
Y o u c a n also c r e a t e files in m e m o r y w i t h t h e d e v i c e c a l l e d R A M : .
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
AMIGADOS USER'S MANUAL
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
AMIGADOS USER'S MANUAL
1.3.7 Using Directory Conventions and Logical Devices
In addition to the aforementioned physical devices, A m i g a D O S supports a
v a r i e t y of u s e f u l l o g i c a l d e v i c e s . A m i g a D O S u s e s t h e s e d e v i c e s to f i n d t h e files
that your p r o g r a m s require from time to time. (So that your p r o g r a m s can refer
t o a s t a n d a r d d e v i c e n a m e r e g a r d l e s s of w h e r e t h e file actually is.) All of t h e s e
"logical d e v i c e s " m a y be reassigned b y you to reference any directory.
T h e logical d e v i c e s d e s c r i b e d in this s e c t i o n a r e a s f o l l o w s :
Name
Description
SYS:
S y s t e m disk root directory
C o m m a n d s directory
Library directory
Sequence Library
L i b r a r y f o r O p e n L i b r a r y calls
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
Figure 1-D: Logical Devices
Logical
Typical
device name:
SYS:
directory name:
My.Boot.Disk:
" S Y S " r e p r e s e n t s t h e S Y S t e m d i s k r o o t d i r e c t o r y . W h e n y o u first start u p
t h e A m i g a s y s t e m , A m i g a D O S assigns S Y S : to t h e root directory n a m e
of t h e d i s k i n DFO:. If, for i n s t a n c e , t h e d i s k i n d r i v e DFO: h a s t h e v o l u m e
n a m e M y . B o o t V D i s k , t h e n A m i g a D O S a s s i g n s S Y S : to M y . B o o t . D I S K : . A f t e r
this a s s i g n m e n t , a n y p r o g r a m s t h a t r e f e r to S Y S : u s e t h a t d i s k ' s r o o t d i r e c t o r y .
Logical
device
Typical
directory
name:
C:
name:
My.Boot.Diskx
' C represents the C o m m a n d s directory. W h e n y o u type a c o m m a n d to the CLI
( D I R < c r > , f o r e x a m p l e ) , A m i g a D O S first s e a r c h e s for t h a t c o m m a n d in y o u r
c u r r e n t d i r e c t o r y . If t h e s y s t e m c a n n o t f i n d t h e c o m m a n d in t h e c u r r e n t
d i r e c t o r y , it t h e n l o o k s f o r " C : D I R " . S o t h a t , if y o u h a v e a s s i g n e d " C : " t o
a n o t h e r d i r e c t o r y (for e x a m p l e , " B o o t d i s k : c " ) , A m i g a D O S r e a d s a n d e x e cutes from "Boot
disk:c/DIR".
Logical
device
Typical
directory
name:
L:
name:
My.Boot.Disk:l
" L " r e p r e s e n t s t h e L i b r a r y d i r e c t o r y . T h i s d i r e c t o r y k e e p s t h e o v e r l a y s for large
c o m m a n d s a n d n o n r e s i d e n t p a r t s of t h e o p e r a t i n g s y s t e m . F o r i n s t a n c e , t h e
d i s k b a s e d r u n - t i m e libraries ( R a m - H a n d l e r , P o r t - H a n d l e r , D i s k - V a l i d a t o r , a n d
s o f o r t h ) a r e k e p t h e r e . A m i g a D O S r e q u i r e s t h i s d i r e c t o r y to o p e r a t e .
INTRODUCING AMIGADOS
15
Logical device name: S:
Typical directory name: M y . B o o t . D i s k : s
" S " r e p r e s e n t s t h e S e q u e n c e library. S e q u e n c e files c o n t a i n c o m m a n d s e q u e n c e s
t h a t t h e E X E C U T E c o m m a n d s e a r c h e s for a n d u s e s . E X E C U T E first l o o k s for
t h e s e q u e n c e (or b a t c h ) file in y o u r c u r r e n t d i r e c t o r y . If E X E C U T E c a n n o t f i n d
it t h e r e , it l o o k s i n t h e d i r e c t o r y t h a t y o u h a v e a s s i g n e d S: t o .
Logical device name: L I B S :
Typical directory name: M y . B o o t . D i s k : L I B S
O p e n L i b r a r y f u n c t i o n calls l o o k h e r e for t h e library if it is n o t a l r e a d y l o a d e d
in m e m o r y .
Logical device name: D E V S :
Typical directory name: M y . B o o t . D i s k : D E V S
O p e n D e v i c e calls l o o k h e r e for t h e d e v i c e if it is n o t a l r e a d y l o a d e d in m e m o r y .
Logical device name: F O N T S :
Typical directory name: M y . B o o t . D i s k : F O N T S
O p e n F o n t s l o o k h e r e for y o u r l o a d a b l e f o n t s if t h e y a r e n o t a l r e a d y l o a d e d in
memory.
N o t e : In a d d i t i o n to t h e a b o v e a s s i g n a b l e d i r e c t o r i e s , m a n y p r o g r a m s o p e n files
i n t h e " : T " d i r e c t o r y . A s y o u recall, y o u f i n d file ( o r d i r e c t o r y ) n a m e s p r e d i c a t e d
w i t h a " : " i n t h e r o o t directory. T h e r e f o r e " : T " is t h e directory T , w i t h i n t h e r o o t ,
o n t h e c u r r e n t d i s k . Y o u u s e t h i s d i r e c t o r y t o store t e m p o r a r y files. P r o g r a m s
s u c h as e d i t o r s p l a c e t h e i r t e m p o r a r y w o r k files, or b a c k u p c o p i e s o f t h e last
file e d i t e d , i n t h i s d i r e c t o r y . If y o u r u n o u t of s p a c e o n a d i s k , t h i s is o n e of t h e
first p l a c e s y o u s h o u l d l o o k f o r files t h a t a r e n o l o n g e r n e e d e d .
W h e n t h e s y s t e m is first b o o t e d , A m i g a D O S initially a s s i g n s C : t o t h e : C
d i r e c t o r y . T h i s m e a n s that if y o u b o o t w i t h a d i s k t h a t y o u h a d f o r m a t t e d b y
issuing the c o m m a n d :
F O R M A T D R I V E DFO: N A M E " M y . B o o t . D i s k "
S Y S : is a s s i g n e d to " M y . B o o t . D i s k " . T h e " l o g i c a l d e v i c e " C : is a s s i g n e d t o t h e
C d i r e c t o r y o n t h e s a m e d i s k (that i s , M y . B o o t . D i s k : c ) . L i k e w i s e , t h e f o l l o w i n g
a s s i g n m e n t s are m a d e
C:
L:
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
AMIGADOS USER'S MANUAL
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
P l e a s e k e e p i n m i n d t h a t a s s i g n m e n t s a r e g l o b a l t o all C L I p r o c e s s e s . C h a n g i n g a n a s s i g n m e n t w i t h i n o n e w i n d o w c h a n g e s it for all w i n d o w s .
If y o u w a n t t o u s e y o u r o w n special f o n t library, t y p e
A S S I G N FONTS: "Special font disk:myfonts"
If y o u w a n t y o u r c o m m a n d s to l o a d f a s t e r ( a n d y o u h a v e m e m o r y " t o b u r n " ) ,
type
makedlr ram:c
copy sys:c r a m : c all
a s s i g n c: r a m : c
T h i s c o p i e s all o f t h e n o r m a l A m i g a D O S c o m m a n d s t o t h e R A M d i s k a n d
reassigns the c o m m a n d s directory so that the s y s t e m finds t h e m there.
1.4 Using AmigaDOS
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.
1.4.1 Running Commands in the Background
Y o u c a n i n s t r u c t A m i g a D O S to r u n a c o m m a n d , or c o m m a n d s , i n t h e b a c k g r o u n d . T o d o t h i s , y o u u s e t h e R U N c o m m a n d . T h i s c r e a t e s a n e w C L I as a
s e p a r a t e p r o c e s s of l o w e r priority. I n t h i s c a s e , A m i g a D O S e x e c u t e s s u b s e q u e n t c o m m a n d l i n e s at t h e s a m e t i m e a s t h o s e t h a t h a v e b e e n R U N . F o r
e x a m p l e , y o u c a n e x a m i n e t h e c o n t e n t s of y o u r d i r e c t o r y at t h e s a m e t i m e as
s e n d i n g a c o p y of y o u r text file to t h e p r i n t e r . T o d o t h i s , t y p e
RUN TYPE t e x t _ f i l e to PRT:
LIST
R U N c r e a t e s a n e w C L I a n d carries o u t y o u r p r i n t i n g w h i l e y o u list y o u r
d i r e c t o r y files o n y o u r original C L I w i n d o w .
You can
takes each
commands
line, press
plus sign
example,
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
RUN J O I N t e x t _ f i l e 1 text—file2 AS text—file
S O R T t e x t — f i l e TO s o r t e d t e x t +
T Y P E sorted
text to PRT:
+
1.4.2 Executing Command Files
Y o u c a n a l s o u s e t h e E X E C U T E c o m m a n d t o e x e c u t e c o m m a n d l i n e s i n a file
i n s t e a d of t y p i n g t h e m in directly. T h e C L I r e a d s t h e s e q u e n c e of c o m m a n d s
f r o m t h e file u n t i l it f i n d s a n e r r o r o r t h e e n d of t h e file. If it f i n d s a n e r r o r ,
18
AMIGADOS USER'S MANUAL
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.
1.4.3 Directing Command Input and Output
A m i g a D O S p r o v i d e s a w a y for y o u to redirect s t a n d a r d i n p u t a n d o u t p u t . Y o u
u s e t h e > a n d < s y m b o l s as c o m m a n d s . W h e n y o u t y p e a c o m m a n d , A m i g a D O S
u s u a l l y d i s p l a y s t h e o u t p u t f r o m t h a t c o m m a n d o n t h e s c r e e n . T o tell A m i g a D O S
to s e n d t h e o u t p u t to a file, y o u c a n u s e t h e > c o m m a n d . T o tell A m i g a D O S to
a c c e p t t h e i n p u t to a p r o g r a m f r o m a s p e c i f i e d file r a t h e r t h a n f r o m t h e
k e y b o a r d , y o u u s e t h e < c o m m a n d . T h e < a n d > c o m m a n d s act like traffic
c o p s w h o direct t h e f l o w of i n f o r m a t i o n . F o r e x a m p l e , to direct t h e o u t p u t f r o m
t h e D A T E c o m m a n d a n d w r i t e it to t h e file n a m e d " t e x t
the following c o m m a n d line:
DATE >
file", you would type
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
>
1.4.4 Interrupting AmigaDOS
A m i g a D O S a l l o w s y o u to indicate four levels of a t t e n t i o n i n t e r r u p t w i t h C T R L - C ,
C T R L - D , C T R L - E , a n d C T R L - F . T o s t o p t h e c u r r e n t c o m m a n d f r o m w h a t e v e r it
w a s d o i n g , p r e s s C T R L - C . In s o m e c a s e s , s u c h a s E D I T , p r e s s i n g C T R L - C
i n s t r u c t s t h e c o m m a n d to s t o p w h a t it w a s d o i n g a n d t h e n t o r e t u r n to r e a d i n g
m o r e E D I T c o m m a n d s . T o tell t h e C L I to s t o p a c o m m a n d s e q u e n c e initiated b y
the E X E C U T E c o m m a n d as soon as the current c o m m a n d being executed
finishes, press C T R L - D . C T R L - E a n d CTRL-F are only u s e d b y certain c o m m a n d s in s p e c i a l c a s e s . S e e t h e Developer's Manual in t h i s b o o k f o r d e t a i l s .
N o t e : It is t h e p r o g r a m m e r ' s r e s p o n s i b i l i t y to d e t e c t a n d r e s p o n d to t h e s e
i n t e r r u p t i o n f l a g s . A m i g a D O S will n o t kill a p r o g r a m b y itself.
1.4.5 Understanding Command Formats
T h i s s e c t i o n e x p l a i n s t h e s t a n d a r d f o r m a t or a r g u m e n t t e m p l a t e u s e d b y m o s t
A m i g a D O S c o m m a n d s t o s p e c i f y t h e i r a r g u m e n t s . C h a p t e r 2 of t h i s m a n u a l
i n c l u d e s t h i s a r g u m e n t t e m p l a t e in t h e d o c u m e n t a t i o n of e a c h of t h e c o m m a n d s . T h e t e m p l a t e p r o v i d e s y o u w i t h a g r e a t deal of flexibility i n t h e o r d e r
a n d f o r m of t h e s y n t a x of y o u r c o m m a n d s .
T h e a r g u m e n t t e m p l a t e s p e c i f i e s a list of k e y w o r d s t h a t y o u m a y u s e as
INTRODUCING AMIGADOS
19
s y n o n y m s , so that you type the alternatives after the k e y w o r d , a n d separate
them with an =
For example,
A B C , W W W , X Y Z = ZZZ
specifies k e y w o r d s , A B C , W W W , and X Y Z . T h e user m a y u s e k e y w o r d Z Z Z as
a n a l t e r n a t i v e to t h e k e y w o r d X Y Z .
T h e s e k e y w o r d s s p e c i f y t h e n u m b e r a n d f o r m of t h e a r g u m e n t s t h a t t h e
p r o g r a m e x p e c t s . T h e a r g u m e n t s m a y b e o p t i o n a l or r e q u i r e d . If y o u g i v e t h e
a r g u m e n t s , y o u m a y s p e c i f y t h e m in o n e of t w o w a y s :
By position
By keyword
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
AMIGADOS USER'S MANUAL
If t h e a r g u m e n t is n o t a s i n g l e w o r d (that i s , s u r r o u n d e d or " d e l i m i t e d " b y
s p a c e s ) , t h e n y o u m u s t e n c l o s e it w i t h q u o t a t i o n m a r k s ( " ) . If t h e a r g u m e n t h a s
t h e s a m e v a l u e a s o n e of t h e k e y w o r d s , y o u m u s t also e n c l o s e it w i t h q u o t a t i o n
marks. For example, the following:
M Y C O M M A x T D " f i l e n a m e " TO " d e s t i n a t i o n "
s u p p l i e s t h e text " f i l e n a m e " as t h e F R O M a r g u m e n t , a n d t h e file
name
" d e s t i n a t i o n " as the T O argument.
T h e k e y w o r d s in t h e s e a r g u m e n t lists h a v e c e r t a i n qualifiers a s s o c i a t e d w i t h
t h e m . T h e s e qualifiers a r e r e p r e s e n t e d b y a s l a s h (/) a n d a specific l e t t e r . T h e
m e a n i n g s of t h e qualifiers a r e a s f o l l o w s :
/A
/K
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 .
T h e qualifiers A a n d K m a y be c o m b i n e d , so that the template
DRIVE/A/K
m e a n s that y o u m u s t give the a r g u m e n t and k e y w o r d D R I V E .
In s o m e cases, no keywords m a y b e given. For example, the
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
A l t h o u g h this m a n u a l lists all t h e a r g u m e n t s e x p e c t e d b y t h e c o m m a n d s , y o u
c a n d i s p l a y t h e a r g u m e n t t e m p l a t e b y s i m p l y t y p i n g t h e n a m e of t h e c o m m a n d , f o l l o w e d b y a s p a c e a n d a q u e s t i o n m a r k (?).
If t h e a r g u m e n t s y o u s p e c i f y d o n o t m a t c h t h e t e m p l a t e , m o s t c o m m a n d s
simply display the m e s s a g e " B a d a r g s " or " B a d a r g u m e n t s " a n d stop. Y o u m u s t
retype the c o m m a n d n a m e and argument. To display on the screen help on
w h a t arguments the c o m m a n d expected, you can always type a question mark
(?)•
1.5 Restart Validation Process
W h e n y o u first i n s e r t a d i s k f o r u p d a t i n g , A m i g a D O S c r e a t e s a p r o c e s s at l o w
priority. This validates the entire structure on the disk. Until the restart process
h a s c o m p l e t e d this j o b , y o u c a n n o t c r e a t e files o n t h e d i s k . It is p o s s i b l e ,
h o w e v e r , t o r e a d files.
W h e n t h e r e s t a r t p r o c e s s c o m p l e t e s , A m i g a D O S c h e c k s t o s e e if y o u h a v e s e t
the system date a n d time. T o set the date a n d time, y o u u s e the
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.
1.6 Commonly Used Commands: An Example Session
This manual describes the various A m i g a D O S c o m m a n d s . T h e C o m m a n d Line
I n t e r p r e t e r (CLI) r e a d s A m i g a D O S c o m m a n d s t y p e d i n t o a C L I w i n d o w a n d
t r a n s l a t e s t h e m i n t o a c t i o n s p e r f o r m e d b y t h e c o m p u t e r . I n this s e n s e t h e C L I
22
AMIGADOS USER'S MANUAL
is similar to 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 s u f f i c i e n t a n d f r i e n d l y f o r m o s t u s e r s ,
the W o r k b e n c h diskettes are s h i p p e d with the CLI interface " d i s a b l e d " . To u s e
t h e c o m m a n d s i n this 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 this 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 to i s s u e
t e x t c o m m a n d s directly to A m i g a D O S .
How to Enable the Command Line Interface
B o o t y o u r c o m p u t e r u s i n g t h e K i c k s t a r t d i s k e t t e a n d a w r i t a b l e c o p y of y o u r
W o r k b e n c h diskette. O p e n the W o r k b e n c h diskette icon. O p e n the "Prefere n c e s " t o o l . N e a r t h e l e f t - h a n d s i d e of t h e s c r e e n , a b o u t t w o - t h i r d s of t h e w a y
d o w n y o u will n o t i c e " C L I " w i t h a b u t t o n for " O N " a n d a b u t t o n " O F F " .
S e l e c t t h e " O N " b u t t o n . S e l e c t " S a v e " ( l o w e r r i g h t p a r t of 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 .
How to Make a New CLI Window
To use the CLI c o m m a n d s , you open a CLI window. O p e n the " S y s t e m "
d r a w e r . T h e C L I i c o n (a c u b e c o n t a i n i n g " 1 > " ) s h o u l d n o w b e v i s i b l e . O p e n it.
Using the CLI
To use the CLI interface, select the CLI w i n d o w a n d type the desired C L I
c o m m a n d s ( d e s c r i b e d w i t h i n this m a n u a l ) . T h e C L I w i n d o w ( s ) m a y b e s i z e d
a n d m o v e d j u s t like m a n y o t h e r s . T o c l o s e t h e C L I w i n d o w , t y p e " E N D C L I " .
Workbench and CLI: Their Relationships and Differences
Type " D I R "
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
u s e r " o p e n s " t h e d a t a file ( m o u n t . p i c . i n f o ) , W o r k b e n c h r u n s t h e p r o g r a m a n d
p a s s e s t h e d a t a file n a m e ( m o u n t , pic) to it.
A m i g a D O S sub-directories correspond to W o r k b e n c h drawers. R a n d o m acc e s s b l o c k d e v i c e s s u c h as d i s k s (DFO:) c o r r e s p o n d t o t h e d i s k e t t e i c o n s y o u
have seen.
N o t all p r o g r a m s o r c o m m a n d s c a n b e r u n u n d e r b o t h W o r k b e n c h a n d t h e
C L I e n v i r o n m e n t . N o n e of t h e C L I c o m m a n d s d e s c r i b e d in C h a p t e r 2 o f t h e
AmigaDOS
User's Manual c a n b e r u n f r o m W o r k b e n c h . F o r e x a m p l e , t h e r e a r e
t w o s e p a r a t e D i s k c o p y c o m m a n d s . T h e o n e i n t h e :c/ d i r e c t o r y w o r k s w i t h
A m i g a D O S ( C L I ) . T h e o n e in t h e s y s t e m d i r e c t o r y ( d r a w e r ) w o r k s w i t h
Workbench.
An Introduction to Some of the AmigaDOS Commands
A l t h o u g h all of t h e c o m m a n d s t h a t a r e available t h r o u g h t h e C L I a r e e x p l a i n e d
in detail in t h e r e f e r e n c e p a r t of t h e AmigaDOS
User's Manual, w e h a v e f o u n d
t h a t m o s t u s e r s will u s e v e r y f e w of t h e a d v a n c e d o p t i o n s . T h e r e f o r e w e h a v e
p r o v i d e d a s u m m a r y h e r e s h o w i n g v a r i o u s c o m m a n d s in t h e i r m o s t c o m m o n
form.
T h e c o m m a n d s summarized b e l o w (along with the actual A m i g a D O S c o m m a n d n a m e ) a s k A m i g a D O S to d o s u c h c o m m a n d s as
• C o p y a diskette ( D I S K C O P Y )
• Format a n e w diskette ( F O R M A T )
• M a k e a formatted diskette bootable;
create a CLI disk (INSTALL)
• Relabel a diskette (RELABEL)
• 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 ( D I R )
• G e t i n f o r m a t i o n a b o u t files ( L I S T )
• P r e v e n t a file f r o m a c c i d e n t a l d e l e t i o n ( P R O T E C T )
• G e t I n f o r m a t i o n a b o u t a file s y s t e m ( I N F O )
• C h a n g e a current directory (CD)
• Set the date and time (DATE)
• R e d i r e c t t h e o u t p u t of a c o m m a n d ( > )
• T y p e a text file to t h e s c r e e n ( T Y P E )
• R e n a m e a file ( R E N A M E )
• D e l e t e a file ( D E L E T E )
• Create a n e w directory ( M A K E D I R )
• C o p y files o n a d u a l - d r i v e s y s t e m ( C O P Y )
• C o p y files o n a s i n g l e - d r i v e s y s t e m ( C O P Y )
• F i n d files o n a d i s k e t t e ( D I R O P T A )
• D o s o m e t h i n g a u t o m a t i c a l l y at b o o t t i m e ( u s i n g S t a r t u p - S e q u e n c e )
24
AMIGADOS USER'S MANUAL
• 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 .
For a New User
F o r a n e w u s e r , w e s u g g e s t t h a t y o u r e a d a n d try e a c h o f t h e s e i t e m s i n
s e q u e n c e . E a c h c o m m a n d t h a t is s h o w n b e l o w l e a v e s a test d i s k in a k n o w n
s t a t e so t h a t t h e c o m m a n d t h a t i m m e d i a t e l y f o l l o w s will w o r k e x a c t l y a s
s h o w n . L a t e r , w h e n y o u are m o r e familiar w i t h t h e s y s t e m , t h e p a r a g r a p h
titles s h o w n b e l o w will s e r v e to r e f r e s h y o u r m e m o r y .
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
AMIGADOS USER'S MANUAL
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.
Making a Disk Bootable
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 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 h a v e your freshly formatted disk available.
T h e r e a r e s e v e r a l d i f f e r e n t w a y s t o c r e a t e a C L I d i s k e t t e . T w o of t h e s e w a y s
are s h o w n below.
A b o o t a b l e d i s k is o n e t h a t y o u c a n u s e to start u p y o u r A m i g a f o l l o w i n g t h e
Kickstart process. Y o u can c h a n g e a formatted disk into a CLI disk b y typing
the command:
INSTALL ?
Note: to use this c o m m a n d on a single drive s y s t e m , you M U S T u s e the
q u e s t i o n m a r k ! O t h e r w i s e A m i g a D O S will try t o d o t h e install o n t h e d i s k
c u r r e n t l y in d r i v e 0.
AmigaDOS responds:
DRIVE/A
R e m o v e y o u r W o r k b e n c h diskette copy and insert the formatted disk. T h e n
type:
dfO:
a n d p r e s s R E T U R N . A m i g a D O S c o p i e s b o o t s e c t o r s to t h e d i s k e t t e . N o w , if y o u
w a i t u n t i l t h e d i s k activity light g o e s o u t , y o u c a n t h e n p e r f o r m a full r e s e t
( C T R L - A m i g a - A m i g a ) . W h e n t h e s y s t e m r e b o o t s , y o u will g o d i r e c t l y i n t o t h e
CLI rather than into the Workbench.
Your formatted diskette n o w contains a CLI a n d nothing else. This m e a n s that
a l t h o u g h y o u s e e t h e i n t e r p r e t e r , it c a n ' t p e r f o r m a n y of t h e c o m m a n d s s h o w n
in t h i s s e c t i o n . A C L I n e e d s s e v e r a l files b e f o r e its c o m m a n d s c a n b e p e r f o r m e d .
A l l o f t h e c o m m a n d files a r e l o c a t e d i n t h e C d i r e c t o r y o f y o u r m a s t e r d i s k e t t e .
T h e s e c o n d w a y to p r o d u c e a C L I d i s k g i v e s y o u a m o r e u s e f u l d i s k in t h a t it
l e a v e s t h e C L I c o m m a n d d i r e c t o r i e s i n t a c t . H e r e is a s t e p - b y - s t e p p r o c e s s to
c h a n g e a w r i t a b l e c o p y of a W o r k b e n c h d i s k e t t e i n t o a C L I d i s k e t t e :
1. C o p y y o u r W o r k b e n c h d i s k e t t e .
2. O p e n the CLI as described above.
3. Click the selection b u t t o n on the CLI w i n d o w a n d type the c o m m a n d :
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 .
Looking at the Directory
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 o r 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.
Y o u l o o k at t h e c o n t e n t s of a d i s k e t t e w i t h t h e c o m m a n d :
D I R o r D I R dfO:
T h i s f o r m lists t h e c o n t e n t s of y o u r c u r r e n t d i r e c t o r y . Y o u c a n list t h e c o n t e n t s
of a d i f f e r e n t d i r e c t o r y b y s p e c i f y i n g t h e p a t h n a m e for t h a t d i r e c t o r y . F o r
example, the c o m m a n d :
D I R dfO:C o r D I R c
lists t h e c o n t e n t s of t h e c(dir) o n d r i v e dfO. D i r e c t o r i e s a r e e q u i v a l e n t to t h e
d r a w e r s y o u s e e w h e n t h e W o r k b e n c h s c r e e n is v i s i b l e .
Y o u c a n l o o k at t h e d i r e c t o r y of a d i f f e r e n t d i s k u n i t , if y o u h a v e o n e , b y
s p e c i f y i n g its n a m e . F o r e x a m p l 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 .
Using the LIST Command
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 c o p y s h o u l d b e i n d r i v e
0.
T h e D I R c o m m a n d tells y o u t h e n a m e s of files t h a t a r e i n y o u r d i r e c t o r y . T h e
L I S T c o m m a n d p r o v i d e s a d d i t i o n a l i n f o r m a t i o n a b o u t t h o s e files. T y p e t h e
command:
L I S T o r L I S T dfO:
A m i g a D O S p r o v i d e s i n f o r m a t i o n a b o u t all files in t h e c u r r e n t d i r e c t o r y ,
i n c l u d i n g h o w l a r g e e a c h file i s , w h e t h e r it m a y o r m a y n o t b e d e l e t e d ,
w h e t h e r it is a file o r a d i r e c t o r y , a n d t h e d a t e a n d t i m e of its c r e a t i o n .
If y o u s p e c i f y t h e n a m e of a d i r e c t o r y w i t h L I S T , it lists i n f o r m a t i o n a b o u t
t h e files w i t h i n t h a t d i r e c t o r y :
LIST c
T h e " r w e d " a r e called p r o t e c t i o n f l a g s , for r e a d , w r i t e , e x e c u t e , a n d d e l e t e .
W h e n e a c h flag is s e t , u s i n g t h e P R O T E C T c o m m a n d , a file is s u p p o s e d t o b e
r e a d a b l e , writable, e x e c u t a b l e , or deleteable. A s of t h e c u r r e n t r e l e a s e , 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 t o t h e d e l e t e - f l a g . If t h e " d " d o e s n ' t s h o w u p in t h e
" r w e d " c o l u m n for a f i l e n a m e , A m i g a D O S w o n ' t d e l e t e t h a t file d u r i n g a
DELETE command.
29
INTRODUCING AMIGADOS
Using the Protect Command
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 o r 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.
T h i s c o m m a n d p r o t e c t s (or u n p r o t e c t s ) a file f r o m b e i n g d e l e t e d a c c i d e n t a l l y .
Try the c o m m a n d :
DATE > myfile
PROTECT myfile
LIST myfile
Y o u will s e e t h a t all of t h e p r o t e c t - f l a g s h a v e b e e n s e t t o "
" . 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
Getting Information About the File System
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 still b e in d r i v e 0. T y p e
command:
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
A m i g a D O S has loaded the I N F O c o m m a n d from your CLI disk a n d s h o w s
y o u t h e t e m p l a t e for t h e c o m m a n d . T h e r e s p o n s e " n o n e : " s a y s t h a t y o u d o n ' t
h a v e t o t y p e a n y t h i n g o t h e r t h a n a R E T U R N k e y t o h a v e it p e r f o r m t h e c o m m a n d . R e m o v e your C L I disk and insert the disk on which you want I N F O to
o p e r a t e . W a i t f o r t h e d i s k activity light to g o o n a n d off. T h e n p r e s s R E T U R N .
A m i g a D O S gives you I N F O about this other disk. This w o r k s for D I R as well
as I N F O .
Changing Your Current Directory
U n t i l n o w , w e h a v e o n l y s t a y e d at t h e " r o o t " or t o p m o s t h i e r a r c h i c a l level of
t h e d i s k e t t e d i r e c t o r y . Y o u will f i n d m o r e i n f o r m a t i o n a b o u t t h e d i r e c t o r y t r e e
structure in section 1.3 of this m a n u a l . T o see the level at w h i c h y o u are currently
positioned in your directory tree, y o u u s e the c o m m a n d :
CD
T o c h a n g e to a d i f f e r e n t c u r r e n t d i r e c t o r y , y o u tell t h e s y s t e m w h i c h d i r e c t o r y
is t o b e c o m e t h e c u r r e n t o n e . F o r e x a m p l e , w h e n y o u did a " d i r " c o m m a n d o n
dfO: t h e C L I d i s k e t t e y o u s a w a n e n t r y c(dir). If y o u w a n t to m a k e this d i r e c t o r y
the current one, you issue the command:
CD C o r CD dfO:c
N o w w h e n y o u i s s u e t h e c o m m a n d D I R , it s h o w s t h e c o n t e n t s of this l e v e l
of t h e filing s y s t e m . T h e c o m m a n d C D ( a l o n e ) s h o w s y o u t h e n a m e of y o u r
c u r r e n t d i r e c t o r y . Y o u g o u p to t h e r o o t d i r e c t o r y ( t h e t o p level) b y s p e c i f y i n g :
CD:
o n t h e c u r r e n t v o l u m e (if y o u r e f e r to y o u r d i s k e t t e s b y v o l u m e n a m e ) o r
CD dfO:
o n t h e built-in drive.
Setting the Date and Time
Y o u can set the A m i g a D O S clock b y using the D A T E c o m m a n d :
D A T E 1 2 : 0 0 : 0 0 12-OCt-85
N o w t h e s y s t e m c l o c k c o u n t s u p f r o m this d a t e a n d t i m e .
INTRODUCING AMIGADOS
31
Redirecting the Output of a Command
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 s h o u l d b e i n
d r i v e 0.
N o r m a l l y t h e o u t p u t of all c o m m a n d s g o e s t o t h e m o n i t o r s c r e e n . Y o u c a n
c h a n g e w h e r e the system puts the output b y using the redirect c o m m a n d " > " .
T h e f o r w a r d a r r o w s y m b o l m e a n s s e n d t h e o u t p u t t o w a r d t h i s o u t p u t file
name. Here's an example:
DATE >
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 .
Typing a Textfile to the Screen
Y o u c a n s e e t h e c o n t e n t s of a textfile b y u s i n g t h e T Y P E c o m m a n d :
T Y P E datefile
T h i s c o m m a n d will d i s p l a y w h a t e v e r y o u h a v e in t h e s p e c i f i e d file. If y o u
w i s h to s t o p t h e o u t p u t m o m e n t a r i l y to r e a d s o m e t h i n g o n t h e s c r e e n , p r e s s
t h e s p a c e b a r . T o restart it p r e s s t h e B A C K S P k e y . If y o u w i s h to e n d t h e T Y P E
c o m m a n d , hold d o w n the CTRL key, and press the C key.
If y o u w i s h to v e r i f y t h a t a n o t h e r d i s k e t t e a l s o h a s t h e datefile c o n t e n t s o n it,
you can perform the command:
TYPE DifferentName:datefile
AMIGADOS USER'S MANUAL
32
Changing the Name of a File
Before y o u try this c o m m a n d , your W o r k b e n c h or CLI diskette copy should b e
in d r i v e 0.
Y o u c a n c h a n g e t h e n a m e of a file b y u s i n g t h e R E N A M E c o m m a n d :
R E N A M E F R O M d a t e f i l e TO n e w n a m e
or
R E N A M E datefile n e w n a m e
N o w use T Y P E to verify that the n e w n a m e refers to the same contents.
TYPE newname
Notice that the alternate form of the c o m m a n d doesn't require that y o u use
t h e F R O M a n d T O . M o s t of t h e A m i g a D O S c o m m a n d s h a v e a n a l t e r n a t e f o r m ,
abbreviated from that s h o w n in this preface section. T h e longer form h a s b e e n
u s e d p r i m a r i l y to i n t r o d u c e y o u to w h a t t h e c o m m a n d d o e s . B e s u r e to
e x a m i n e t h e s u m m a r y p a g e s t o familiarize y o u r s e l f w i t h t h e a l t e r n a t e c o m m a n d forms that are available.
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 :
Cant Open directory-stuff
i n d i c a t i n g t h a t t h e file c a n ' t b e f o u n d , b e c a u s e y o u d e l e t e d it.
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
AMIGADOS USER'S MANUAL
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 .
Creating a New Directory
Y o u can create a n e w directory (newdrawer) within the current directory b y
using the M A K E D I R command:
MAKEDIR newdrawer
N o w if y o u i s s u e t h e D I R c o m m a n d , y o u will s e e t h a t t h e r e is a n e n t r y for:
newdrawer (dir)
Y o u c a n a l s o u s e t h e R E N A M E c o m m a n d to m o v e a file f r o m o n e d i r e c t o r y
( d r a w e r ) to a n o t h e r o n t h e s a m e d i s k e t t e :
MAKEDIR newdrawer
R E N A M E F R O M n e w n a m e TO n e w d r a w e r / n e w n a m e
m o v e s t h e file f r o m t h e c u r r e n t d i r e c t o r y i n t o t h e n e w d r a w e r y o u h a v e c r e a t e d .
T o c h e c k t h a t it h a s really b e e n m o v e d , i s s u e t h e c o m m a n d :
DIR
T h e n type:
DIR newdrawer
AmigaDOS
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 .
Is My File Somewhere on This Disk?
B e f o r e y o u e n t e r 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 i n d r i v e 0.
S o m e t i m e s y o u w i s h to s e e e v e r y t h i n g o n t h e d i s k e t t e , i n s t e a d of
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
has m o r e detailed information on
using ED.
Doing Something Automatically at Boot Time
T h e r e is a file in t h e " s " s u b d i r e c t o r y o n 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 a l l e d
S t a r t u p S e q u e n c e . T h i s is a n e x e c u t e file. It c o n t a i n s a s e q u e n c e of C L I c o m m a n d s t h a t A m i g a D O S p e r f o r m s w h e n e v e r y o u r e b o o t t h e s y s t e m . T h e last
t w o c o m m a n d s in y o u r W o r k b e n c h d i s k e t t e S t a r t u p S e q u e n c e a r e L o a d W b
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
Assigning the Diskette on Which AmigaDOS Looks for Things
B e f o r e y o u e n t e r 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.
O c c a s i o n a l l y , y o u m i g h t w i s h to c h a n g e to a d i f f e r e n t d i s k e t t e a n d t h e n
continue your work. For example, you may have booted the system using a
W o r k b e n c h d i s k e t t e , t h e n w i s h to c h a n g e to a C L I d i s k e t t e . If t h e C L I d i s k e t t e
h a s a d i r e c t o r y o n it t h a t c o n t a i n s t h e e x e c u t a b l e c o m m a n d s y o u w a n t t o
p e r f o r m , (for e x a m p l e , a c(dir)), y o u c a n c h a n g e to t h a t d i s k e t t e b y u s i n g t h e
ASSIGN command.
If y o u d o n ' t u s e A S S I G N , y o u will h a v e to s w a p d i s k e t t e s t o g e t c o m m a n d s
d o n e . H e r e is a n e x a m p l e t h a t d o e s n ' t u s e A S S I G N . T h e i n t e n t is to c h a n g e
d i s k e t t e s a n d b e g i n u s i n g " m y d i s k : " as t h e m a i n d i s k e t t e . A n y u n n e e d e d files
h a v e a l r e a d y b e e n d e l e t e d s o a s to p r o v i d e w o r k s p a c e .
CD m y d i s k :
A m i g a D O S r e s p o n d s " i n s e r t m y d i s k i n t o a n y d r i v e " . I n s e r t it, t h e n
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
A m i g a D O S a s k s " i n s e r t m y d i s k i n t o a n y d r i v e " . F r o m n o w o n , all c o m m a n d s to A m i g a D O S will b e s o u g h t f r o m t h e c o m m a n d (c) d i r e c t o r y of t h i s
o t h e r d i s k e t t e a n d A m i g a D O S w o n ' t a s k f o r t h e original d i s k e t t e b a c k f o r
simple commands.
O n c e y o u ' v e d o n e t h i s , y o u ' l l p r o b a b l y w a n t to t y p e :
CD m y d i s k :
T h e r e a r e o t h e r t h i n g s t h a t A m i g a D O S c a n a s s i g n . If y o u i s s u e t h e c o m m a n d
ASSIGN LIST
y o u will s e e t h e o t h e r t h i n g s as w e l l . If y o u r u n a p r o g r a m t h a t r e q u i r e s a serial
d e v i c e ( m o d e m , p r i n t e r ) o r a parallel d e v i c e ( p r i n t e r ) , A m i g a D O S l o o k s i n t h e
d i r e c t o r y c u r r e n t l y a s s i g n e d to D E V S : to locate t h e d e v i c e . If all of t h e s y s t e m
d i r e c t o r i e s a r e o n this n e w m a i n d i s k e t t e , y o u c a n a v o i d h a v i n g A m i g a D O S a s k
y o u t o r e i n s e r t t h e original d i s k e t t e b y p r o v i d i n g a n e x e c u t e file o n y o u r
d i s k e t t e s t h a t r e a s s i g n s all d e v i c e s t o t h a t d i s k e t t e . T h e c o n t e n t s of t h i s e x e c u t e
file for a d i s k e t t e n a m e d " m y d i s k " a r e as f o l l o w s :
ASSIGN
ASSIGN
ASSIGN
ASSIGN
ASSIGN
ASSIGN
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 .
Creating a New CLI
A m i g a D O S is a m u l t i - t a s k i n g s y s t e m . Y o u c a n h a v e m u l t i p l e w i n d o w s o p e n at
t h e s a m e t i m e , e a c h w i t h its o w n c u r r e n t d i r e c t o r y a n d e x e c u t i n g s e p a r a t e
c o m m a n d s . Y o u create a n e w CLI by using the c o m m a n d N E W C L I :
NEWCLI
38
AMIGADOS USER'S MANUAL
This o p e n s a separate w i n d o w , with a p r o m p t that identifies the current
p r o c e s s . F o r e x a m p l e , if t h e first w i n d o w h a s a p r o m p t :
1>
then the n e w CLI might have a prompt:
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 .
1.7 Conventions Used
In C h a p t e r 2 of t h i s m a n u a l , i n t h e " F o r m a t " d e s c r i p t i o n for t h e A m i g a D O S
c o m m a n d s , y o u will f i n d t h e f o l l o w i n g n o t a t i o n s u s e d :
<name>
[ ]
I
<name>*
I n d i c a t e s a p a r a m e t e r n a m e t h a t y o u s h o u l d fill in for this c o m mand. Example: E X E C U T E < c o m m a n d f i l e > w h e r e the n a m e
of t h e c o m m a n d file is a r e q u i r e d p a r a m e t e r .
S q u a r e b r a c k e t s a r e u s e d to i n d i c a t e t h a t a n i t e m is o p t i o n a l . It
n e e d n ' t b e p r o v i d e d f o r t h e c o m m a n d to f u n c t i o n b u t , if p r o vided, conveys additional information to A m i g a D O S about h o w
to p e r f o r m t h e c o m m a n d . E x a m p l e : Q U I T [ < c o d e > ]
A vertical b a r tells y o u t h a t y o u c a n select o n e o r a n o t h e r of t h e
a l t e r n a t i v e s t h a t a r e s e p a r a t e d b y t h e vertical b a r f o r a c o m m a n d .
E x a m p l e : D I R [ O P T A 111 A I ] T h e e x a m p l e i n d i c a t e s t h a t y o u c a n
c h o o s e A , I or A I for t h e s p e c i f i c a t i o n .
I n d i c a t e s o n e - o r - m o r e o c c u r r e n c e s of a p a r a m e t e r n a m e ; if y o u
supply more than one such parameter, individual parameters
m u s t b e s e p a r a t e d b y at l e a s t o n e b l a n k s p a c e .
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
AmigaDOS User's Commands
AmigaDOS Developer's Commands
A m i g a D O S C o m m a n d s Quick Reference Card
2.1 AmigaDOS User's Commands
Unfamiliar Terminology
In t h i s m a n u a l y o u c o u l d f i n d s o m e t e r m s t h a t y o u h a v e n o t s e e n b e f o r e . T h e
list b e l o w i n c l u d e s s o m e c o m m o n t e r m s t h a t a r e c o n f u s i n g if y o u a r e u n f a m i l iar w i t h t h e m .
Boot
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
a n a m e you can give to a directory with A S S I G N that y o u can
then use as a device n a m e .
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
a disk containing the W o r k b e n c h a n d c o m m a n d s .
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
w r i t e s t h e o u t p u t of t h e D A T E c o m m a n d (that is, t o d a y ' s d a t e a n d t i m e ) t o t h e
file " d i a r y
dates".
my
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
LIST > temp
S O R T t e m p TO *
p r o d u c e s a s o r t e d list of files a n d d i s p l a y s t h e m o n t h e s c r e e n .
T h e following sequence:
ECHO > 2nd.date 0 2 - j a n - 7 8
DATE < 2nd.date ?
DELETE 2nd.date
c r e a t e s a file called 2 n d . d a t e t h a t c o n t a i n s t h e text " 0 2 - j a n - 7 8 < l i n e f e e d > " . N e x t
it u s e s t h i s file as i n p u t to t h e c o m m a n d D A T E . N o t e t h a t t h e " ? " is n e c e s s a r y
for D A T E to accept input from the standard input, rather t h a n the c o m m a n d
l i n e . F i n a l l y , a s y o u n o l o n g e r n e e d t h e file, t h e D E L E T E c o m m a n d d e l e t e s
2nd. date.
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
AMIGADOS USER'S MANUAL
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
i
of
46
AMIGADOS USER'S MANUAL
c o p i e s all files in t h e c u r r e n t d i r e c t o r y t h a t start " t e s t - " to t h e d i r e c t o r y x y z o n
t h e d i s k " d f l " , a s s u m i n g t h a t " x y z " a l r e a d y e x i s t s . (For a n e x p l a n a t i o n of p a t t e r n s , s u c h a s " # ? " , s e e t h e c o m m a n d L I S T in this c h a p t e r . )
COPY t e s t _ f i l e to PRT:
c o p i e s t h e file " t e s t
file" to your printer.
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
To specify the destination of the verification, y o u u s e t h e equivalent k e y w o r d s T O a n d V E R . T h e d e s t i n a t i o n is t h e terminal u n l e s s y o u specify o t h e r w i s e .
N o t e : If y o u t y p e D A T E b e f o r e t h e r e s t a r t v a l i d a t i o n h a s c o m p l e t e d , t h e t i m e
is d i s p l a y e d as u n s e t . T o s e t t h e t i m e , y o u c a n e i t h e r u s e D A T E o r j u s t w a i t
u n t i l t h e v a l i d a t i o n p r o c e s s is f i n i s h e d .
Examples:
DATE
displays the current date.
DATE 06-Sep-82
s e t s t h e d a t e to t h e 6 t h o f S e p t e m b e r 1 9 8 2 . T h e t i m e is n o t r e s e t .
DATE t o m o r r o w
resets the date to one day ahead.
D A T E TO f r e d
s e n d s t h e c u r r e n t d a t e to t h e file " f r e d " .
DATE
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:
DELETE " „ „ „ „ „ A L L / S , Q = QUIET/S"
<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
AMIGADOS USER'S MANUAL
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)
d e l e t e s all t h e files t h a t e n d in " 1 " or "2" i n directories t h a t start w i t h " t " . ( F o r
a n explanation of patterns, such as " # ? " , see the c o m m a n d LIST later in this
chapter.)
DELETE D F 1 : # ? ALL
d e l e t e s all t h e files o n D F 1 : .
See also: D I R ( 1 - D E L o p t i o n )
DIR
Format:
Template:
D I R [ < n a m e > ] [ O P T A|I|AI]
DIR "DIR,OPT/K"
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
AMIGADOS USER'S MANUAL
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
+
ECHO "Copy f i n i s h e d "
c r e a t e s a n e w C L I to c o p y t h e s p e c i f i e d d i r e c t o r y a s a b a c k g r o u n d p r o c e s s .
W h e n it h a s f i n i s h e d , t h e s c r e e n d i s p l a y s
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 .
AMIGADOS USER'S MANUAL
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:
EDIT [ F R O M ] < n a m e > [ [ T O ] < n a m e > ] [ W I T H < n a m e > ] [ V E R < n a m e > ]
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
v e r s i o n o f " w o r k / p r o g " in " : t / e d i t - b a c k u p " .
old
AMIGADOS COMMANDS
53
EDIT work/prog TO work/newprog
e d i t s t h e file " w o r k / p r o g " , p l a c i n g t h e e d i t e d r e s u l t in t h e file " w o r k / n e w p r o g " .
EDIT work/prog WITH edits/O VER nil:
e d i t s t h e file " w o r k / p r o g " w i t h t h e edit c o m m a n d s s t o r e d i n t h e file " e d i t s / 0 " .
V e r i f i c a t i o n o u t p u t f r o m E D I T is s e n t to t h e d u m m y d e v i c e " n i l : " .
ENDCLI
Format:
ENDCLI
Template:
ENDCLI
Purpose:
To e n d a n interactive CLI process.
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
C h a n g e b r a c h a r a c t e r (initially " < " ) t o c h
.KET
ch
C h a n g e k e t c h a r a c t e r (initially " > " ) t o c h
.DOLLAR
ch
C h a n g e d e f a u l t - c h a r (initially " $ " ) to c h , m a y b e
.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 :
AMIGADOS USER'S MANUAL
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:
work/prg2 is not on this directory.
See also:
;,IF,SKIP,FAILAT,LAB,ECHO,RUN,QUIT
Additional Examples for the EXECUTE
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
EXECUTE DEM01 pan somename flash other-name
T h e v a l u e " o t h e r n a m e " is a s s i g n e d to < f l a s h > , a n d t h e v a l u e " s o m e n a m e " is
assigned to < p a n > .
Y o u c a n o m i t t h e k e y w o r d n a m e s if t h e p a r a m e t e r s u b s t i t u t i o n s a r e i n t h e
o r d e r g i v e n i n t h e . K E Y s t a t e m e n t . F o r e x a m p l e , t h e f o l l o w i n g s t a t e m e n t is
equivalent to the preceding one:
EXECUTE DEMOl othername somename
T h i s is b e c a u s e t h e v a l u e s c o r r e s p o n d to t h e k e y w o r d o r d e r s p e c i f i e d in t h e
.KEY statement.
Y o u c a n a l s o m i x t h e t w o m e t h o d s of p a r a m e t e r s u b s t i t u t i o n . S u p p o s e y o u
h a v e a .KEY statement with several parameters, as follows:
.KEY wordl, word2, word3, word4
T h e e x e c u t e file p r o c e s s o r r e m o v e s p a r a m e t e r n a m e s f r o m t h e i n p u t l i n e
to fill t h e m e a n i n g s of a n y k e y w o r d v a l u e s it f i n d s . T h e n , w i t h a n y r e m a i n i n g
i n p u t , it fills t h e l e f t o v e r k e y w o r d p o s i t i o n s a c c o r d i n g to t h e p o s i t i o n of t h e
input value.
For example:
EXECUTE DEM02 word3 ccc wordl aaa bbb ddd
T h e processor assigns ccc to < w o r d 3 > , aaa to < w o r d l > , a n d h a s t w o
p a r a m e t e r s left o v e r . S c a n n i n g f r o m left t o r i g h t in t h e . K E Y s t a t e m e n t , it f i n d s
t h a t < w o r d 2 > is still u n a s s i g n e d . T h u s , < w o r d 2 > g e t s t h e n e x t i n p u t w o r d ,
b b b . F i n a l l y , < w o r d 4 > h a s n ' t b e e n a s s i g n e d e i t h e r , s o it g e t s t h e l a s t i n p u t
word, ddd.
Y o u can indicate special conditions for parameter substitution, as follows:
.KEY namel/a, name2/a, name3, name4/k
T h e "la." i n d i c a t e s t h a t a v a l u e m u s t b e s u p p l i e d to fill t h e p a r a m e t e r s f o r
n a m e l a n d n a m e 2 . V a l u e s f o r n a m e 3 a n d n a m e 4 a r e o p t i o n a l , t h o u g h t h e "Ik"
i n d i c a t e s t h a t < n a m e 4 > (if s u p p l i e d ) m u s t b e p r e c e d e d b y t h e explicit k e y w o r d
" n a m e 4 . " For example:
EXECUTE DEM03 fee fie foe name4 fum
If t h e u s e r d o e s n o t s u p p l y a r e q u i r e d p a r a m e t e r ( s u c h a s n a m e l or n a m e 2 in
the preceding example), E X E C U T E issues an error m e s s a g e .
AMIGADOS USER'S MANUAL
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 :
EXECUTE COMPILE myfile PRINTFILE myprint
t h e e x e c u t e file s a y s t h e k e y w o r d P R I N T F I L E is o p t i o n a l a n d n e e d n o t b e
s u p p l i e d , b u t if u s e d , t h e r e m u s t b e a v a l u e e n t e r e d a l o n g w i t h it.
t h e a b o v e l i n e is c o r r e c t ,
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 " "
(two double-quotes in a row). Y o u
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:
ECHO "<wordl$defwordl> is the default for Wordl."
" d e f w o r d l " is t h e d e f a u l t s p e c i f i e d for w o r d l a n d is p r i n t e d w h e n t h e a b o v e
s t a t e m e n t e x e c u t e s . T h e s e c o n d w a y is t o d e f i n e a d e f a u l t o n c e . F o r e x a m p l e ,
with the following assignment:
.DEF wordl "defwordl"
you can execute the following statement:
ECHO " < w o r d l > is the default for Wordl."
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 :
defwordl is the default for Wordl.
N o t e t h a t a s e c o n d u s e of . D E F f o r a g i v e n p a r a m e t e r h a s n o effect:
.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.)
Assigning Different Bracket Characters
W h e r e v e r E X E C U T E f i n d s e n c l o s i n g a n g l e b r a c k e t s , it l o o k s w i t h i n t h e m t o s e e
if it c a n s u b s t i t u t e a p a r a m e t e r . A n u n s u p p l i e d p a r a m e t e r w i t h n o d e f a u l t
b e c o m e s a " n u l l " string.
S u p p o s e y o u w a n t to u s e a s t r i n g t h a t c o n t a i n s t h e a n g l e b r a c k e t c h a r a c t e r s ,
< a n d > . Y o u c a n u s e t h e directives . B R A a n d . K E T to d e f i n e s u b s t i t u t e s f o r
the bracket characters. For example,
ECHO "This line does WOT print <angle> brackets."
.BRA{
.KET }
ECHO "This line DOES print <angle> brackets."
ECHO "The default for wordl is {wordl}."
T h e first E C H O s t a t e m e n t c a u s e s t h e p r o c e s s o r to l o o k for t h e p a r a m e t e r
s u b s t i t u t i o n f o r " a n g l e , " s i n c e t h a t ' s t h e c u r r e n t m e a n i n g of t h e a n g l e b r a c k e t
c h a r a c t e r s . S i n c e " a n g l e " w a s n ' t i n c l u d e d in t h e . K E Y s t a t e m e n t , t h e p r o c e s s o r
s u b s t i t u t e s t h e n u l l s t r i n g for it. T h e n , a f t e r t h e . B R A a n d . K E T d i r e c t i v e s
r e d e f i n e t h e b r a c k e t c h a r a c t e r s , the s e c o n d E C H O s t a t e m e n t prints t h e c h a r a c t e r s :
This line DOES print <angle> brackets.
T h e t h i r d E C H O s t a t e m e n t illustrates that t h e b r a c e s ( { a n d } ) n o w f u n c t i o n
t o e n c l o s e k e y w o r d s f o r t h e p u r p o s e of p a r a m e t e r s u b s t i t u t i o n .
Example # 3
Showing Command File Structures
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
AMIGADOS USER'S MANUAL
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:
IF " < w o r d l > " EQ "usage"
SKIP USAGE
ENDIF
IF " < w o r d 2 > " EQ ""
SKIP USAGE
ENDIF
E n c l o s i n g y o u r p a r a m e t e r s u b s t i t u t i o n w o r d s in d o u b l e q u o t e s w i t h i n
statements
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:
IF NOT exists < f r o m >
T h e r e c a n b e n o t h i n g o n the IF line other t h a n the test condition.
e x a m p l e , t h e f o l l o w i n g is i n c o r r e c t :
IF <something> EQ true SKIP DONE
T h e c o r r e c t f o r m o f t h e a b o v e s t a t e m e n t is as f o l l o w s :
For
AMIGADOS COMMANDS
61
I F < s o m e t h i n g > EQ " t r u e "
S K I P DONE
ENDIF
A s the e x a m p l e above s h o w s , the string constant tested for n e e d not be
e n c l o s e d in d o u b l e q u o t e s ; in t h e p r e c e d i n g e x a m p l e , e i t h e r " T R U E " or T R U E
is a c c e p t a b l e .
A s s h o w n i n t h e s a m p l e c o m m a n d file b e l o w , IF s t a t e m e n t s c a n b e n e s t e d s o
that c o m m a n d s can b e executed based on multiple true statements. N o t e that
E X E C U T E lets y o u i n d e n t t o m a k e t h e n e s t i n g of I F s t a t e m e n t s m o r e r e a d a b l e .
T h e f o l l o w i n g s a m p l e c o m m a n d file s i m u l a t e s a file c o p y i n g utility t h a t
i l l u s t r a t e s c e r t a i n u s e f u l s t r u c t u r e s in a c o m m a n d file: I F . . . [ E L S E ] . . .
ENDIF, LAB, and SKIP.
.KEY from, to
I F " < f r o m > " eq ""
being supplied.
SKIP usage
use.
ENDIF
; ( 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)
I F " < t o > " eq ""
b e i n g supplied.
SKIP usage
ENDIF
; ( 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 )
I F NOT e x i s t s < f r o m >
; ( C h e c k if F R O M file d o e s n ' t exist)
ECHO " T h e f r o m file y o u selected ; ( < f r o m > ) could not be f o u n d . "
E C H O " P l e a s e u s e t h e D I R o r L I S T c o m m a n d a n d try a g a i n . "
S K I P DONE
;(Note: W e can SKIP out of an IF.)
ENDIF
IF exists < t o >
I F " < o > " EQ "0"
on the line?
copy f r o m < f r o m > to < t o >
; ( 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
ECHO "copy from < f r o m > to < t o > . "
ENDIF
SKIP DONE
LAB usage
ECHO "cp: usage...."
ECHO "The following copy forms are supported:"
ECHO " x cp FROM sourcefile TO destlnationfile"
ECHO " x cp FROM sourcefile destinationfile"
ECHO " x cp sourcefile TO destinationffle"
ECHO " x cp sourcefile destinationfile"
ECHO " x cp TO destinationfile FROM sourcefile"
ECHO " x cp sourcefile destinationfile 0"
ECHO " x cp FROM sourcefile TO destinationfile 0"
ECHO " x cp 0 FROM sourcefile TO destinationfile"
ECHO "where: x is short for EXECUTE; cp is the name o f
ECHO "this command file, and "0" means 'overwrite existing file'."
LAB DONE
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
prints once at the beginning, (parml, parm2)"
I."
II."
III."
prints once at the end. (parml, parm2)"
.KEY parml,parm2, loopcnt, looplabel
FAILAT 20
IF NOT "<looplabel>" EQ ""
;(Called with label?)
SKIP <looplabel>
;(Yes, then loop.)
ENDIF
ECHO "This message prints once ;(Start of loop)
at the beginning. ( < p a r m l > , < p a r m 2 > ) "
AMIGADOS COMMANDS
63
LAB lst-loop
I F " < l o o p c n t > " EQ " I I I "
;(Are w e done looping?)
SKIP loopend-<looplabel>
ENDIF
;(Yes, unwind.)
ECHO "Loop n u m b e r < l o o p c n t > I . "
; ( G o " b a c k w a r d s " in t h i s file.)
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:
FAILAT " R C L I M "
<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
AMIGADOS USER'S MANUAL
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"
attaches the c o m m e n t " V e r 3.3 2 6 - m a r - 8 5 " to program 2.
See also:
LIST
FORMAT
Format:
Template:
F O R M A T DRIVE < d r i v e n a m e > N A M E < s t r i n g >
FORMAT"DRIVE/A/K,NAME/A/K"
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
T h e p r o g r a m formats a n e w floppy disk in the m e t h o d required for A m i g a D O S .
O n c e t h e d i s k is f o r m a t t e d , it is initialized a n d a s s i g n e d t h e n a m e y o u s p e c i f y .
Notice that y o u m u s t give b o t h the D R I V E a n d N A M E k e y w o r d s . T h e only
v a l i d o p t i o n s t h a t y o u c a n g i v e a f t e r t h e D R I V E k e y w o r d a r e DFO:, D F 1 : ,
D F 2 : , o r D F 3 : . Y o u c a n t y p e a n y s t r i n g a f t e r N A M E , b u t if y o u u s e 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 s t r i n g in d o u b l e q u o t e s ( " ) .
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:
DISKCOPY, INSTALL, RELABEL
AMIGADOS USER'S M A N U A L
66
IF
Format:
IF[NOT][WARN][ERROR][FAIL][<str>EQ<str>][EXISTS
Template:
IF
Purpose:
To allow conditionals within c o m m a n d sequences.
<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 .
EXISTS < f i l e >
Y o u c a n u s e I F E Q to d e t e c t a n u n s e t p a r a m e t e r in a c o m m a n d file b y u s i n g
the form:
IF < a > EQ " "
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
AMIGADOS USER'S MANUAL
Unit
Size
Errs
Status
Name
DF1:
880K
Used
2
Free
1756
Full
0%
0
Read/Write
Test-6
DFO:
880K
1081
677
61%
0
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:
T o m a k e a formatted disk bootable.
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:
JOIN < n a m e > < n a m e > [ < n a m e > * ] A S < n a m e >
JOIN " „ „ „ „ „ „ „ A S / A / K "
/
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
j o i n s t h e t w o files t o g e t h e r , p l a c i n g t h e r e s u l t i n " t e x t f i l e " . T h e t w o o r i g i n a l files
r e m a i n u n c h a n g e d , while " t e x t f i l e " contains a c o p y of " p a r t i " a n d a c o p y of
"part2".
LAB
Format:
LAB <string>
Template:
LAB < t e x t >
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:
LIST "DIR, P = PAT/K, KEYS/S, DATES/S, N O D A T E S / S , T O / K , S/K,
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
size protection date time
70
AMIGADOS USER'S MANUAL
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.
date and time:
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
T h i s s p e c i f i e s t h e file (or d e v i c e ) to o u t p u t t h e file l i s t i n g t o . If
o m i t t e d , t h e o u t p u t g o e s to t h e c u r r e n t C L I w i n d o w .
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
Displays dates in the form D D - M M M - Y Y (the default unless
you use QUICK).
NODATES
SINCE
<date>
D o e s not display date a n d time information.
D i s p l a y s o n l y files last u p d a t e d o n o r a f t e r < d a t e > .
<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>
D i s p l a y s o n l y files l a s t u p d a t e d o n o r b e f o r e < d a t e > .
P<pat>
S e a r c h e s for files w h o s e n a m e s m a t c h < p a t > .
S<str>
Searches for filenames containing substring < s t r > .
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.
%
M a t c h e s the null string.
# < 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>
M a t c h e s a s e q u e n c e of pattern < p l > followed b y < p 2 > .
<pl>l<p2>
M a t c h e s if e i t h e r p a t t e r n < p l > o r p a t t e r n < p 2 >
()
Groups patterns together.
<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.
LIST PAT A#(BlC)D
M a t c h e s A D A B D A B C D , a n d so forth.
LIST PAT A?B
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.
LIST P A T ' ? # ? ' #
M a t c h e s ? # ? A B # ? ? # # , and so forth
LIST PAT A(Bl%)#C
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
(notice that File.3 h a s a c o m m e n t )
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 "
d i r e c t o r y . L I S T " s " will list t h i 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
AMIGADOS USER'S MANUAL
s e n d s j u s t t h e n a m e s , o n e o n e a c h l i n e , t o t h e file " o u t f i l e " . Y o u c a n t h e n e d i t
t h e file a n d i n s e r t t h e c o m m a n d T Y P E at t h e b e g i n n i n g o f e a c h l i n e . T h e n t y p e :
E X E C U T E outfile
to display t h e files.
See also:
DATE, DIR,FILENOTE,PROTECT
MAKEDIR
Format:
M A K E D I R < dir >
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:
To create a w i n d o w associated with a n e w interactive CLI process.
"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
d i m e n s i o n s are in screen pixels.
Examples:
NEWCLI
c r e a t e s a n e w C L I p r o c e s s a n d m a k e s it t h e c u r r e n t C L I .
NEWCLI
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
a
AMIGADOS USER'S MANUAL
74
PROMPT
Format:
PROMPT<prompt>
Template:
PROMPT "PROMPT"
Purpose:
To change the p r o m p t in the current CLI.
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 >
"
r e s e t s t h e c u r r e n t p r o m p t t o " n > " , w h e r e n is t h e c u r r e n t p r o c e s s n u m b e r .
A m i g a D O S interprets the special character combination % N as the
process
number.
PROTECT
Format:
Template:
Purpose:
PROTECT[FILE] < f ilename> [FLAGS< status>]
PROTECT"FILE,FLAGS/K"
T o s e t a file's p r o t e c t i o n s t a t u s .
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:
QUIT " R C "
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
with return code 20.
For m o r e on c o m m a n d s e q u e n c e s , see the specification for the
c o m m a n d earlier in t h i s c h a p t e r .
See also:
EXECUTE,IF,LAB,SKIP
RELABEL
Format:
R E L A B E L [ D R I V E ] < drive > [ N A M E ] < n a m e >
Template:
RELABEL "DRIVE/A, NAME/A"
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
AMIGADOS USER'S MANUAL
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:
RELABEL dfl: "My other disk"
See also:
FORMAT
RENAME
Format:
R E N A M E [ F R O M ] < n a m e > [ T O [AS] < n a m e >
Template:
RENAME "FROM/A,TO = AS/A"
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,
RENAME fox to Fox
does not work.
N o t e : If y o u a l r e a d y h a v e a file w i t h e x a c t l y t h e s a m e n a m e a s t h e T O file,
R E N A M E w o n ' t w o r k . T h i s s h o u l d s t o p y o u f r o m o v e r w r i t i n g y o u r files b y
accident.
Examples:
RENAME work/progl AS :arthur/example
77
AMIGADOS COMMANDS
r e n a m e s t h e file " w o r k / p r o g l " a s t h e file " a r t h u r / e x a m p l e " . T h e r o o t d i r e c t o r y
m u s t c o n t a i n " a r t h u r " f o r t h i s c o m m a n d to w o r k .
RUN
Atw-crf fa -
^
c
Format:
RUN < c o m m a n d >
Template:
RUN command + command
^
Purpose:
To execute commands as background processes.
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
(RETURN) as a continuation of the
c o m m a n d line. T h u s , y o u can m a k e u p a single c o m m a n d line of
same
several
physical lines that each end with a plus sign.
R U N displays t h e process n u m b e r of the n e w l y created process.
Examples:
R U N COPY :t/0 P R T : +
D E L E T E :t/0 +
ECHO " P r i n t i n g f i n i s h e d "
p r i n t s t h e file " : t / 0 " b y c o p y i n g it t o t h e l i n e p r i n t e r d e v i c e , d e l e t e s it, t h e n
displays the given message.
RUN EXECUTE comseq
e x e c u t e s i n t h e b a c k g r o u n d all t h e c o m m a n d s in t h e file " c o m s e q " .
SEARCH
Format:
S E A R C H [ F R O M ] < n a m e > | < p a t > [SEARCH] < string> [ALL]
Template:
SEARCH "FROM, SEARCH/A,ALL/S"
Purpose:
T o l o o k for a t e x t s t r i n g y o u s p e c i f y i n all t h e files i n a d i r e c t o r y .
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
AMIGADOS USER'S MANUAL
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:
SKIP < l a b e l >
Template:
SKIP " L A B E L "
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
AMIGADOS USER'S MANUAL
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:
SORT text TO sorted-text
s o r t s e a c h l i n e of i n f o r m a t i o n in " t e x t " a l p h a b e t i c a l l y a n d p l a c e s t h e r e s u l t i n
"sorted-text".
SORT index TO sorted-index COLSTART 4
s o r t s t h e file " i n d e x " , w h e r e e a c h r e c o r d c o n t a i n s t h e p a g e n u m b e r in t h e first
t h r e e c o l u m n s a n d t h e i n d e x e n t r y o n t h e r e s t of t h e l i n e , a n d p u t s t h e o u t p u t
in " s o r t e d - i n d e x " sorted b y the index entry, and matching index entries sorted
by page number.
See also:
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:
STATUS "PROCESS, FULL/S,TCB/S,SEGS/S,CLI = ALL/S"
Purpose:
To display information about the currently existing CLI processes.
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
Technical Reference in this b o o k .
CLI identifies C o m m a n d Line Interface processes and displays the section
n a m e ( s ) o f t h e c u r r e n t l y l o a d e d c o m m a n d (if a n y ) .
82
AMIGADOS USER'S MANUAL
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:
T Y P E [ F R O M ] < n a m e > [ [ T O ] < n a m e > ] [ O P T N|H]
Template:
TYPE "FROM/A,TO, OPT/K"
Purpose:
T o t y p e a text file or to t y p e a file o u t a s h e x a d e c i m a l n u m b e r s .
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:
WAIT ",SEC = SECS/S,MIN = MINS/S,UNTIL/K"
<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:
To explain w h y the previous c o m m a n d failed.
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
AMIGADOS USER'S MANUAL
Cant open fred
T h i s c o u l d h a p p e n for a n u m b e r o f r e a s o n s — f o r e x a m p l e , " f r e d " m i g h t a l r e a d y
b e a d i r e c t o r y , o r t h e r e m i g h t n o t b e e n o u g h s p a c e o n t h e d i s k t o o p e n t h e file,
o r it m i g h t b e a r e a d - o n l y d i s k . C O P Y m a k e s n o d i s t i n c t i o n b e t w e e n
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
Last command failed because object not of required type
W H Y gives y o u a hint about w h y your c o m m a n d failed. T Y P E D F O : failed
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
2.2 AmigaDOS Developer's Commands
ALINK
Format:
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
loader and run under
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:
ASSEM[PROG|FROM]<prog>[-0 <code>][-V <ver>][-L <listing>]
Template:
ASSEM " P R O G = FROM/A,-0/K,-V/K,-L/K,-H/K,-E/K,-C = OPT/K,-I/K"
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 .
[-E] [-C|OPT < o p t > ] [ - I < d i r l i s t > ]
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
s e t s u p a list o f d i r e c t o r i e s t o b e s e a r c h e d for i n c l u d e d files.
-E
is t h e file t h a t r e c e i v e s t h e " e q u a t e s " d i r e c t i v e ( E Q U ) a s s i g n m e n t s
f r o m y o u r s o u r c e . Y o u u s e - E to g e n e r a t e a h e a d e r file c o n t a i n i n g
these directives.
T h e options y o u can specify with O P T or -C are as follows:
S
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.
X
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:
ASSEM prog.asm TO prog.obj
a s s e m b l e s t h e s o u r c e p r o g r a m in " p r o g . a s m " , p l a c i n g t h e r e s u l t i n t h e file
" p r o g . o b j " . It w r i t e s a n y e r r o r m e s s a g e s t o t h e t e r m i n a l , b u t d o e s n o t p r o d u c e
a n y a s s e m b l y listing.
AMIGADOS USER'S MANUAL
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>
by convention should end with
.Id.
Once
y o u ' v e d o n e t h i s , to r u n t h e p r o g r a m , y o u t y p e t h e < a m i g a f i l e n a m e > .
N o t e t h a t t h e c o m m a n d " b i n l o a d " is n o t a n A m i g a D O S c o m m a n d . Y o u u s e
b i n l o a d o n a S u n to l o a d files i n b i n a r y for d o w n l o a d i n g to y o u r A m i g a .
N o t e t h a t D O W N L O A D a l w a y s a c c e s s e s files o n t h e S u n r e l a t i v e to t h e
d i r e c t o r y i n w h i c h b i n l o a d w a s s t a r t e d . 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
in w h i c h b i n l o a d w a s 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
o n t h e S u n , y o u c a n 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 to w r i t e a m e s s a g e t o its s t a n d a r d o u t p u t
( t h e d e f a u l t b e i n g t h e w i n d o w w h e r e it s t a r t e d ) . If D O W N L O A D h a n g s , p r e s s
C T R L - C t o kill it.
C h a p t e r 1 o f t h e AmigaDOS
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
AMIGADOS USER'S MANUAL
88
R E A D s t o t h e file " d f O : n e w " f r o m t h e parallel p o r t .
READ new SERIAL
R E A D s t o t h e file " n e w " f r o m t h e serial l i n e .
2.3 AmigaDOS Commands Quick Reference Card
User's Commands
File
Utilities
r
<>
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
sets a current directory and/or drive.
ENDCLI
ends an interactive CLI process.
NEWCLI
creates a n e w interactive CLI process.
PROMPT
changes the prompt in the current CLI.
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
explains w h y a previous c o m m a n d failed.
Command
Sequence
about the CLI processes currently
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
tests specified actions within a c o m m a n d s e q u e n c e .
LAB
defines a label (see S K I P ) .
QUIT
exits f r o m a c o m m a n d s e q u e n c e with a given error c o d e .
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
displays or sets the system date a n d
DISKCOPY
copies the contents of o n e entire floppy disk to a n o t h e r .
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
makes a formatted disk bootable.
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
assembles MC68000 language.
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
reads information f r o m t h e parallel port or serial line
s t o r e s it i n a file.
and
Chapter 3
ED—The Screen Editor
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
ED—THE SCREEN EDITOR
91
E D m a k e s a n a t t e m p t to o p e n t h e file y o u h a v e s p e c i f i e d a s " f r e d " ( t h a t is, t h e
F R O M file), a n d if t h i s s u c c e e d s , t h e n E D r e a d s t h e file i n t o m e m o r y a n d
d i s p l a y s t h e first l i n e s o n t h e s c r e e n . O t h e r w i s e , E D p r o v i d e s a b l a n k s c r e e n ,
r e a d y for t h e a d d i t i o n o f n e w i n f o r m a t i o n . T o a l t e r t h e t e x t b u f f e r t h a t E D u s e s
to h o l d t h e file, y o u s p e c i f y a s u i t a b l e v a l u e a f t e r t h e S I Z E k e y w o r d , f o r
example,
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
in immediate m o d e ; you use
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
start editing. To enter e x t e n d e d m o d e , y o u press the E S C k e y . T h e n ,
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
immediate c o m m a n d with a single k e y or control k e y combination. T o indicate
a control key combination, you press and hold d o w n the C T R L key while you
type the given letter, so that C T R L - M , for e x a m p l e , m e a n s hold d o w n C T R L
while you type M.
In extended m o d e , anything you type appears on the c o m m a n d line.
ED
does n o t execute c o m m a n d s until y o u finish the c o m m a n d line. Y o u m a y type
a n u m b e r of e x t e n d e d c o m m a n d s o n a single c o m m a n d line. Y o u m a y also
g r o u p a n y c o m m a n d s together a n d even get E D to repeat t h e m automatically.
Most immediate commands have a matching extended version.
AMIGADOS USER'S MANUAL
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 .
3.2 Immediate Commands
T h i s section describes t h e type of c o m m a n d s that E D executes immediately.
Immediate c o m m a n d s deal with the following:
• cursor control
• text insertion
• text deletion
• text scrolling
• repetition of c o m m a n d s
3.2.1 Cursor Control
T o m o v e t h e c u r s o r o n e p o s i t i o n in a n y d i r e c t i o n , y o u p r e s s t h e a p p r o p r i a t e
c u r s o r c o n t r o l k e y . If t h e c u r s o r is o n t h e r i g h t h a n d e d g e o f t h e s c r e e n , E D
scrolls t h e t e x t t o t h e left t o m a k e t h e r e s t of t h e t e x t v i s i b l e . E D
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.
3.2.2 Inserting Text
While in immediate
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
ED—THE SCREEN EDITOR
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
displays the following message:
Line too long
H o w e v e r , o n shorter lines, E D m o v e s a n y characters to the right of t h e
c u r s o r t o m a k e r o o m f o r t h e n e w t e x t . If t h e l i n e e x c e e d s t h e s i z e o f t h e s c r e e n ,
t h e left h a n d e n d o f t h e l i n e d i s a p p e a r s f r o m v i e w . T h e n E D r e d i s p l a y s t h e e n d
o f t h e l i n e b y s c r o l l i n g t h e t e x t h o r i z o n t a l l y . If y o u m o v e t h e c u r s o r b e y o n d t h e
e n d o f t h e l i n e , f o r e x a m p l e , w i t h t h e T A B or c u r s o r c o n t r o l k e y s , E D i n s e r t s
spaces b e t w e e n the e n d of the line a n d a n y n e w character y o u insert.
T o split t h e c u r r e n t l i n e a t t h e c u r s o r a n d g e n e r a t e a n e w l i n e , p r e s s R E T U R N . If t h e c u r s o r is at t h e e n d o f a l i n e , E D c r e a t e s a n e w b l a n k l i n e a f t e r t h e
c u r r e n t o n e . A l t e r n a t i v e l y , y o u p r e s s C T R L - A to g e n e r a t e a b l a n k l i n e a f t e r t h e
c u r r e n t o n e , w i t h n o split o f t h e c u r r e n t l i n e t a k i n g p l a c e . I n e i t h e r c a s e , t h e
c u r s o r a p p e a r s o n t h e n e w l i n e at t h e p o s i t i o n i n d i c a t e d b y t h e left m a r g i n
(initially, c o l u m n o n e ) .
T o e n s u r e that E D gives a carriage return automatically at a certain position
o n the screen, y o u can set u p a right margin. O n c e y o u h a v e d o n e
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
setting margins, see Section 3.3.1, "Program Control".)
If y o u t y p e s o m e t e x t in t h e w r o n g c a s e (for e x a m p l e , in l o w e r c a s e i n s t e a d o f
u p p e r c a s e ) , y o u c a n c o r r e c t it w i t h C T R L - F , T o d o t h i s , y o u m o v e t h e c u r s o r t o
p o i n t a t t h e l e t t e r y o u w a n t to c h a n g e a n d t h e n p r e s s C T R L - F . If t h e l e t t e r is i n
l o w e r c a s e , C T R L - F flips t h e l e t t e r i n t o u p p e r c a s e . O n t h e o t h e r h a n d , if t h e
l e t t e r is in u p p e r c a s e , C T R L - F flips it i n t o l o w e r c a s e . H o w e v e r , if t h e c u r s o r
p o i n t s a t s o m e t h i n g t h a t is n o t a l e t t e r (for e x a m p l e , a s p a c e o r s y m b o l ) ,
C T R L - F d o e s n o t h i n g to it.
C T R L - F n o t o n l y flips l e t t e r s ' c a s e s b u t it a l s o m o v e s t h e c u r s o r o n e p l a c e t o
AMIGADOS USER'S MANUAL
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> < =
x
becomes
if < F I L E > < =
X
w h e r e the letters c h a n g e case a n d the symbols remain the s a m e .
3.2.3 Deleting Text
T h e B A C K S P A C E k e y d e l e t e s t h e c h a r a c t e r to t h e left of t h e c u r s o r a n d m o v e s
t h e c u r s o r o n e p o s i t i o n left u n l e s s it is at t h e b e g i n n i n g of a l i n e . E D scrolls t h e
t e x t , if r e q u i r e d . T h e D E L k e y d e l e t e s t h e c h a r a c t e r at t h e c u r r e n t c u r s o r
position without moving the cursor. As with any deletion, characters remaini n g o n the line shift back, a n d text that w a s invisible b e y o n d the right h a n d
e d g e of t h e s c r e e n b e c o m e s v i s i b l e .
T h e a c t i o n of C T R L - O d e p e n d s o n t h e c h a r a c t e r at t h e c u r s o r . If t h i s c h a r a c t e r is a s p a c e , t h e n C T R L - O d e l e t e s all s p a c e s u p t o t h e n e x t n o n s p a c e
c h a r a c t e r o n t h e l i n e . O t h e r w i s e , it d e l e t e s c h a r a c t e r s f r o m t h e c u r s o r , a n d
m o v e s text left, u n t i l a s p a c e o c c u r s .
C T R L - Y d e l e t e s all c h a r a c t e r s f r o m t h e c u r s o r t o t h e e n d of t h e l i n e .
C T R L - B deletes the entire current line. Y o u m a y u s e extended c o m m a n d s to
d e l e t e b l o c k s of text.
ED—THE SCREEN EDITOR
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
b e s i d e s t h e editor alters the screen. H o w e v e r , in typical u s e , m e s s a g e s f r o m
other processes appear in the w i n d o w b e h i n d the editor w i n d o w .
3.2.5 Repeating Commands
T h e editor r e m e m b e r s a n y e x t e n d e d c o m m a n d line y o u type. T o execute this
s e t o f e x t e n d e d c o m m a n d s a g a i n at a n y t i m e , p r e s s C T R L - G . I n t h i s w a y , y o u
c a n s e t u p a s e a r c h c o m m a n d a s a n e x t e n d e d c o m m a n d . If t h e first o c c u r r e n c e
o f a s t r i n g is n o t t h e o n e y o u n e e d , p r e s s C T R L - G to r e p e a t t h e s e a r c h . Y o u c a n
set u p a n d execute c o m p l e x sets of editing c o m m a n d s m a n y times.
N o t e : W h e n y o u g i v e a n e x t e n d e d c o m m a n d as a c o m m a n d g r o u p w i t h a
r e p e t i t i o n c o u n t , E D r e p e a t s t h e c o m m a n d s in t h e g r o u p t h a t n u m b e r o f t i m e s
each time y o u press C T R L - G . S e e the next section for m o r e details o n e x t e n d e d
commands.
3.3 Extended Commands
T h i s s e c t i o n d e s c r i b e s t h e c o m m a n d s a v a i l a b l e t o y o u in e x t e n d e d m o d e . T h e s e
c o m m a n d s cover:
• program control
• block control
• movement
• searching text
• e x c h a n g i n g text
• altering text
• inserting text
To enter extended c o m m a n d m o d e , press the E S C key. Subsequent input
t h e n a p p e a r s o n t h e c o m m a n d l i n e at t h e b o t t o m of t h e s c r e e n . Y o u c a n c o r r e c t
m i s t a k e s w i t h B A C K S P A C E in t h e n o r m a l w a y . T o t e r m i n a t e t h e
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
AMIGADOS USER'S MANUAL
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.
3.3.1 Program Control
T h i s s e c t i o n p r o v i d e s a s p e c i f i c a t i o n of t h e p r o g r a m c o n t r o l c o m m a n d s X
(eXit), Q (Quit), S A (SAve), U (Undo), S H ( S H o w ) , S T (Set Tab), S L a n d S R
(Set Left a n d Set Right), a n d E X (EXtend).
T o i n s t r u c t t h e e d i t o r t o exit, y o u u s e t h e c o m m a n d X . A f t e r y o u h a v e g i v e n
t h e e x i t c o m m a n d , E D w r i t e s o u t t h e text it i s h o l d i n g i n m e m o r y t o t h e
o u t p u t , o r d e s t i n a t i o n file a n d t h e n t e r m i n a t e s . If y o u l o o k at t h i s file, y o u c a n
s e e t h a t all t h e c h a n g e s y o u m a d e a r e t h e r e .
E D a l s o w r i t e s a t e m p o r a r y b a c k u p t o : T / E D - B A C K U P . T h i s b a c k u p file
r e m a i n s u n t i l y o u exit f r o m E D a g a i n , at w h i c h t i m e , E D o v e r w r i t e s t h e file
with a n e w backup.
T o g e t o u t of t h e e d i t o r w i t h o u t k e e p i n g a n y c h a n g e s , y o u u s e t h e Q
c o m m a n d . W h e n y o u u s e Q , E D t e r m i n a t e s i m m e d i a t e l y w i t h o u t w r i t i n g to t h e
b u f f e r a n d d i s c a r d s a n y c h a n g e s y o u h a v e m a d e . B e c a u s e of t h i s , if y o u h a v e
a l t e r e d t h e c o n t e n t s of t h e file, E D a s k s y o u to c o n f i r m t h a t y o u really w a n t to
quit.
A f u r t h e r c o m m a n d lets y o u to t a k e a " s n a p s h o t " c o p y o f t h e file w i t h o u t
c o m i n g o u t of E D . T h i s is t h e S A c o m m a n d . S A s a v e s t h e text t o a n a m e d file
o r , in t h e a b s e n c e of a n a m e d file, to t h e c u r r e n t file. F o r e x a m p l e ,
SA !:doc/savedtext!
or
SA
97
ED—THE SCREEN EDITOR
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
following message appears:
Edits will be lost—type Y to confirm:
If y o u h a v e m a d e n o a l t e r a t i o n s , E D q u i t s i m m e d i a t e l y w i t h t h e c o n t e n t s o f
y o u r s o u r c e file u n c h a n g e d . S A is a l s o u s e f u l b e c a u s e it a l l o w s y o u t o s p e c i f y a
f i l e n a m e o t h e r t h a n t h e c u r r e n t o n e . It is t h e r e f o r e p o s s i b l e t o m a k e c o p i e s a t
d i f f e r e n t s t a g e s a n d p l a c e t h e m i n d i f f e r e n t files or d i r e c t o r i e s .
T o u n d o t h e last c h a n g e , y o u u s e t h e U c o m m a n d . T h e e d i t o r m a k e s a c o p y
o f t h e l i n e t h e c u r s o r is o n , a n d t h e n it m o d i f i e s t h i s c o p y w h e n e v e r y o u a d d o r
d e l e t e c h a r a c t e r s . E D p u t s t h e c h a n g e d c o p y b a c k i n t o t h e file w h e n y o u m o v e
t h e c u r s o r o f f t h e c u r r e n t l i n e ( e i t h e r b y c u r s o r c o n t r o l , or b y d e l e t i n g
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 .
W A R N I N G : E D does not u n d o a line deletion. O n c e y o u h a v e m o v e d
f r o m t h e c u r r e n t l i n e , t h e U c o m m a n d c a n n o t fix t h e m e s s y o u h a v e g o t
yourself into.
T o s h o w t h e current state of the editor, y o u u s e t h e S H c o m m a n d . T h e
screen displays information such as the value of tab s t o p s , current m a r g i n s ,
b l o c k m a r k s , a n d t h e n a m e o f t h e file b e i n g e d i t e d .
T a b s a r e initially s e t at e v e r y t h r e e c o l u m n s . T o c h a n g e t h e c u r r e n t s e t t i n g o f
tabs, y o u u s e the S T c o m m a n d followed by a n u m b e r " n " , w h i c h sets tabs at
every " n " column.
T o s e t t h e left m a r g i n a n d r i g h t m a r g i n , y o u u s e t h e S L a n d S R c o m m a n d s ,
a g a i n f o l l o w e d b y a n u m b e r i n d i c a t i n g t h e c o l u m n p o s i t i o n . T h e left m a r g i n
s h o u l d n o t b e set b e y o n d the width of the screen.
To extend margins, you use the EX command. O n c e you have given EX, E D
takes n o account of the right margin o n the current line. O n c e y o u m o v e the
cursor from the current line, E D turns the margins on again.
3.3.2 Block Control
T o m o v e , insert, or delete text, you use the block control c o m m a n d s described
in this section.
Y o u c a n i d e n t i f y a b l o c k o f text w i t h t h e B S ( B l o c k S t a r t ) a n d B E ( B l o c k E n d )
AMIGADOS USER'S MANUAL
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 ,
ED—THE SCREEN EDITOR
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.
3.3.3 Moving the Current Cursor Position
T h e c o m m a n d T m o v e s t h e c u r s o r t o t h e t o p o f t h e file, s o t h a t t h e first l i n e i n
t h e file is t h e first l i n e o n t h e s c r e e n . T h e B c o m m a n d m o v e s t h e c u r s o r t o t h e
b o t t o m o f t h e file, s o t h a t t h e last l i n e in t h e file is t h e b o t t o m l i n e o n t h e
screen.
T h e c o m m a n d s N a n d P m o v e t h e c u r s o r t o t h e start o f t h e n e x t l i n e a n d
previous line, respectively. The c o m m a n d s C L and C R m o v e the cursor one
p l a c e to t h e left or o n e p l a c e to t h e r i g h t , w h i l e C E p l a c e s t h e c u r s o r a t t h e e n d
o f t h e c u r r e n t l i n e , a n d C S p l a c e s it at t h e start.
T h e c o m m a n d M m o v e s the cursor to a specific line. T o m o v e , y o u type M
followed b y the line n u m b e r of t h e line y o u w a n t as the n e w current line. For
example,
M 503
moves
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
M
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 .
3.3.4 Searching and Exchanging
Alternatively y o u can m o v e the screen w i n d o w to a particular context with t h e
c o m m a n d F ( F i n d ) f o l l o w e d b y a s t r i n g t h a t r e p r e s e n t s t h e t e x t to b e l o c a t e d .
T h e s e a r c h starts at o n e p l a c e b e y o n d 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
f o r w a r d t h r o u g h t h e file. If t h e s t r i n g is f o u n d , t h e c u r s o r a p p e a r s at t h e s t a r t
o f t h e l o c a t e d s t r i n g . T h e s t r i n g m u s t b e i n q u o t e s (or o t h e r d e l i m i t e r s " / " ,
" ! " , a n d s o o n ) . I n o r d e r for a m a t c h to o c c u r t h e s t r i n g s m u s t b e o f t h e s a m e
c a s e , u n l e s s t h e U C c o m m a n d is u s e d (see b e l o w ) .
To search b a c k w a r d through the text, y o u use the c o m m a n d BF (Backward
F i n d ) in t h e s a m e w a y a s F . B F f i n d s t h e last o c c u r r e n c e o f t h e s t r i n g b e f o r e t h e
c u r r e n t c u r s o r p o s i t i o n . ( T h a t i s , B F l o o k s f o r t h e s t r i n g t o t h e left o f t h e c u r s o r
a n d t h e n t h r o u g h all t h e l i n e s b a c k to t h e b e g i n n i n g o f t h e file.) T o f i n d t h e
earliest o c c u r r e n c e , y o u u s e T (Top-of-file) followed b y F. T o find the last
occurrence, you u s e B (Bottom-of-file) followed by B F .
T h e E (Exchange) c o m m a n d takes two strings separated with delimiter chara c t e r s a n d e x c h a n g e s t h e first s t r i n g f o r t h e l a s t . S o , f o r e x a m p l e ,
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
between upper and lower case again, you use LC.
3.3.5 Altering Text
Y o u cannot use the E c o m m a n d to insert a n e w line into the text. Y o u use the I
a n d A c o m m a n d s instead. Follow the I c o m m a n d (Insert before) with a string
t h a t y o u w a n t to m a k e i n t o a n e w l i n e . E D i n s e r t s t h i s n e w l i n e b e f o r e t h e
current line. For example,
I /Insert this BEFORE the current line/
ED—THE SCREEN EDITOR
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 .
3.3.6 Repeating Commands
T o r e p e a t a n y c o m m a n d a c e r t a i n n u m b e r o f t i m e s , p r e c e d e it w i t h t h e d e s i r e d
number. For example,
4 E /slithy/brillig/
c h a n g e s the next four occurrences of " s l i t h y " to "brillig". E D verifies t h e screen
after each c o m m a n d . Y o u u s e the R P (Repeat) c o m m a n d to repeat a c o m m a n d
u n t i l E D r e t u r n s a n e r r o r , s u c h a s r e a c h i n g t h e e n d o f t h e file. F o r e x a m p l e ,
T; R P E / s l i t h y / b r i l l i g /
c h a n g e s all o c c u r r e n c e s o f " s l i t h y " t o " b r i l l i g " . N o t i c e t h a t y o u n e e d t h e T
c o m m a n d to e n s u r e t h a t A L L o c c u r r e n c e s o f " s l i t h y " a r e c h a n g e d , o t h e r w i s e
only those after the current position are c h a n g e d .
To execute
command
groups repeatedly, you can group the
commands
together in parentheses. Y o u can also n e s t c o m m a n d groups within c o m m a n d
groups. For example,
R P ( F / b a n d e r s n a t c h / ; 3 AJI
)
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
AMIGADOS USER'S MANUAL
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
e x t e n d e d c o m m a n d s , a n d particularly repeated o n e s , y o u type a n y character
w h i l e t h e c o m m a n d s a r e t a k i n g p l a c e . If a n e r r o r o c c u r s , E D a b a n d o n s
the
command sequence.
Quick Reference Card
Special Key Mappings
Command
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
Enter extended command mode
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
M o v e cursor right to next tab position (does N O T insert a
T A B character)
<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
M o v e cursor right to next tab position
CTRL-M
RETURN
CTRL-O
Delete word or spaces
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
ED—THE SCREEN EDITOR
CTRL-[
Escape (enter extended mode)
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/
Insert line after current line
B
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
M o v e cursor one position right
CS
M o v e c u r s o r to start of l i n e
D
Delete current line
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/
Exchange " s " into " t "
E x c h a n g e b u t q u e r y first
EX
Extend right margin
F/s/
Find string
I Is/
Insert line b e f o r e current
IB
Insert c o p y of block
"s"
I F Is/
I n s e r t file
J
LC
Join current line with next
"s"
Distinguish between upper and
l o w e r c a s e in s e a r c h e s
M n
M o v e to l i n e n u m b e r " n "
N
M o v e to start o f n e x t l i n e
P
M o v e t o start o f p r e v i o u s l i n e
Q
RP
Q u i t without saving text
S
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
Set right margin
Repeat until error
104
AMIGADOS USER'S MANUAL
Command
Action
ST n
Set tab distance
T
M o v e to t o p o f file
U
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
W r i t e b l o c k t o file " s "
X
Exit, w r i t i n g t e x t i n t o m e m o r y
Chapter 4
EDIT—The Line Editor
T h i s c h a p t e r d e s c r i b e s in detail h o w t o u s e t h e line e d i t o r E D I T . T h e first p a r t
introduces the reader to the editor. T h e second part gives a complete specificat i o n of E D I T . T h e r e is a q u i c k r e f e r e n c e c a r d c o n t a i n i n g all t h e E D I T c o m m a n d s
at t h e e n d of t h e c h a p t e r .
4.1
4.1.1
4.1.2
4.1.2.1
4.1.2.2
4.1.2.3
4.1.2.4
4.1.2.5
4.1.2.6
4.1.2.7
4.1.2.8
4.1.3
4.1.4
4.2
4.2.1
4.2.1.1
4.2.1.2
4.2.1.3
4.2.1.4
4.2.1.5
4.2.1.6
4.2.1.7
4.2.1.8
4.2.1.9
4.2.1.10
4.2.2
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
AMIGADOS USER'S MANUAL
4.2.2.1
Prompts
4.2.2.2
The Current Line
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
Line Insertion and Deletion
4.2.4
Line Windows
4.2.4.1
The Operational Window
4.2.4.2
Single Character Operations on the Current Line
4.2.5
String Operations on the Current Line
4.2.5.1
Basic String Operations
4.2.5.2
T h e Null String
4.2.5.3
Pointing Variant
4.2.5.4
Deleting Parts of the C u r r e n t Line
4.2.6
Miscellaneous Current Line Commands
4.2.6.1
Splitting a n d Joining Lines
4.2.7
Inspecting Parts of t h e Source: T h e T y p e C o m m a n d s
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
Setting Global Changes
4.2.10.2
Cancelling Global Changes
4.2.10.3
Suspending Global Changes
4.2.11
Displaying the Program State
4.2.12
Terminating an EDIT Run
4.2.13
Current Line Verification
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
4.1 Introducing EDIT
E D I T is a t e x t e d i t o r t h a t p r o c e s s e s s e q u e n t i a l files l i n e b y l i n e u n d e r
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
EDIT—THE LINE EDITOR
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 .
4.1.1 Calling EDIT
This section describes the format of t h e a r g u m e n t s y o u can give every time y o u
call t h e E D I T c o m m a n d . E D I T e x p e c t s t h e f o l l o w i n g a r g u m e n t s :
FROM/A,TO,WITH/K,VER/K,OPT/K
T h e c o m m a n d t e m p l a t e d e s c r i b e d i n C h a p t e r 1 is a m e t h o d o f d e f i n i n g t h e
syntax for each c o m m a n d . A m i g a D O S accepts c o m m a n d a r g u m e n t s according
to the format described in the c o m m a n d template. For example, s o m e argum e n t s are optional, s o m e m u s t appear with a k e y w o r d , a n d others do not n e e d
k e y w o r d s b e c a u s e t h e y a p p e a r o n l y i n a specific p o s i t i o n . A r g u m e n t s w i t h a
f o l l o w i n g / A (like F R O M ) m u s t a p p e a r , b u t y o u d o n o t h a v e to t y p e
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
without a following / ( T O , for example), are optional. A m i g a D O S recognizes
a r g u m e n t s w i t h o u t a f o l l o w i n g s l a s h (/) b y t h e i r p o s i t i o n a l o n e . If y o u f o r g e t
the syntax for E D I T , type:
EDIT ?
a n d A m i g a D O S d i s p l a y s t h e full t e m p l a t e o n t h e s c r e e n . ( F o r m o r e d e t a i l s o n
using c o m m a n d s , see Chapters 1 a n d 2 of this manual.)
U s i n g a n o t h e r m e t h o d o f d e s c r i p t i o n , t h e c o m m a n d s y n t a x f o r E D I T is a s
follows:
[ F R O M ] < f i l e > [ [ T O ] < f i l e > ] [ W I T H < f i l e > ] [ V E R < f i l e > ] [ O P T Pn|Wn|Pn
Wn]
108
AMIGADOS USER'S MANUAL
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.
Unless y o u specify otherwise, A m i g a D O S sets the options P 4 0 W 1 2 0 .
Y o u c a n u s e O P T to i n c r e a s e , or d e c r e a s e , t h e s i z e o f a v a i l a b l e
memory.
E D I T u s e s P * W (that is, the n u m b e r of previous lines multiplied b y the line
w i d t h ) to d e t e r m i n e t h e a v a i l a b l e m e m o r y . T o c h a n g e t h e m e m o r y s i z e , a d j u s t
the P a n d W n u m b e r s . P50 allocates m o r e m e m o r y than usual; P30 allocates
less m e m o r y t h a n usual.
H e r e a r e s o m e e x a m p l e s o f h o w y o u c a n call E D I T :
EDIT program! TO programl
new WITH edit
commands
EDIT programl OPT P50W240
EDIT programl VER v e r ^ i l e
N o t e : U n l i k e E D , y o u c a n n o t u s e E D I T to c r e a t e a n e w file. If y o u a t t e m p t t o
c r e a t e a n e w file, A m i g a D O S r e t u r n s a n e r r o r b e c a u s e it c a n n o t f i n d t h e n e w
file in t h e c u r r e n t d i r e c t o r y .
4.1.2 Using EDIT Commands
This section introduces s o m e of the basic EDIT c o m m a n d s omitting
many
of the a d v a n c e d features. A c o m p l e t e description of the c o m m a n d
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
EDIT—THE LINE EDITOR
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
E D I T a s s i g n s e a c h line i n t h e s o u r c e a u n i q u e line n u m b e r . T h i s line n u m b e r is
n o t p a r t o f t h e i n f o r m a t i o n s t o r e d in t h e file, b u t E D I T c o m p u t e s it b y c o u n t i n g
t h e l i n e s as t h e y a r e r e a d . W h e n y o u ' r e u s i n g E D I T , y o u c a n r e f e r t o a s p e c i f i c
l i n e b y u s i n g its l i n e n u m b e r . A l i n e t h a t h a s b e e n r e a d r e t a i n s its o r i g i n a l l i n e
n u m b e r all t h e t i m e it is i n m a i n m e m o r y , e v e n w h e n y o u d e l e t e l i n e s b e f o r e o r
a f t e r it, or i n s e r t s o m e e x t r a l i n e s . T h e l i n e n u m b e r s r e m a i n u n c h a n g e d u n t i l
y o u r e w i n d t h e file, or u n t i l y o u r e n u m b e r t h e l i n e s w i t h t h e =
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
AMIGADOS USER'S MANUAL
T h e P c o m m a n d also takes a n u m b e r . For example, type:
4P
T h i s m a k e s t h e f o u r t h l i n e a b o v e t h e c u r r e n t l i n e y o u r n e w c u r r e n t l i n e . It i s
o n l y p o s s i b l e t o g o b a c k to p r e v i o u s l i n e s t h a t E D I T h a s n o t y e t w r i t t e n t o t h e
o u t p u t . E D I T u s u a l l y l e t s y o u g o b a c k 4 0 l i n e s . T o b e a b l e to m o v e b a c k m o r e
than this, y o u specify m o r e previous lines with the P option w h e n y o u enter
E D I T ( s e e S e c t i o n 4 . 1 . 1 earlier i n t h i s c h a p t e r f o r f u r t h e r details o n t h e P o p t i o n ) .
Moving
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
You use the F command
( 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,
BF/gyre and gimble/
B F a l s o s t a r t s w i t h t h e c u r r e n t l i n e , b u t E D I T m o v e s b a c k w a r d u n t i l it f i n d s
t h e d e s i r e d l i n e . If E D I T r e a c h e s t h e h e a d o f t h e o u t p u t q u e u 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 d i s p l a y s t h e f o l l o w i n g m e s s a g e :
111
EDIT—THE LINE EDITOR
NO MOKE PREVIOUS LINES
N o t i c e t h a t i n t h e e x a m p l e s a b o v e , t h e d e s i r e d text ( J a b b e r w o c k y a n d g y r e
and gimble)
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
is c a l l e d a c h a r a c t e r s t r i n g . T h e c h a r a c t e r s y o u u s e to i n d i c a t e t h e b e g i n n i n g a n d e n d of t h e character string are called delimiter characters. In t h e
e x a m p l e s a b o v e , / w a s u s e d as the delimiter. A n u m b e r of special characters
s u c h as : . , a n d * are available for u s e as delimiters; naturally, t h e string
itself m u s t n o t contain t h e delimiter character.
between
EDIT ignores the
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
within the string as significant,
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 /turn turn tree/
d o e s n o t f i n d " t u r n - t u r n t r e e " o r " t u r n turn t r e e " .
If y o u u s e a n F c o m m a n d w i t h n o a r g u m e n t , E D I T r e p e a t s t h e p r e v i o u s
search. 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
AMIGADOS USER'S MANUAL
called a q u a l i f i e d string. A n u m b e r of other qualifiers are also available. For
example,
F P/a-sitting on a gate/
m e a n s F i n d t h e n e x t l i n e c o n t a i n i n g P r e c i s e l y t h e text " a - s i t t i n g o n a g a t e " . T h e
r e q u i r e d l i n e 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 , e i t h e r b e f o r e or a f t e r t h e g i v e n
s t r i n g . T h a t is to s a y , w h e n y o u g i v e t h i s c o m m a n d , E D I T f i n d s t h e n e x t l i n e
containing:
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
EDIT—THE LINE EDITOR
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
If seven maids with, seven mops
then the following c o m m a n d sequence:
A/seven/ty/; B L/seven/sixty-/
w o u l d t u r n it i n t o :
If seventy maids with, sixty-seven mops
If y o u h a d o m i t t e d t h e L qualifier f r o m t h e B c o m m a n d a b o v e , t h e r e s u l t
would have been:
If sixty-seventy maids with seven mops
b e c a u s e t h e s e a r c h f o r a s t r i n g u s u a l l y p r o c e e d s f r o m left t o r i g h t , a n d E D I T
u s e s t h e first o c c u r r e n c e t h a t it f i n d s . Y o u u s e t h e qualifier L to s p e c i f y t h a t t h e
s e a r c h s h o u l d p r o c e e d L e f t w a r d . T h e L qualifier f o r c e s t h e c o m m a n d t h a t it
q u a l i f i e s to act o n t h e L a s t o c c u r r e n c e o f its first a r g u m e n t .
If t h e first s t r i n g i n a n A , B , or E c o m m a n d is e m p t y , E D I T 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 b e g i n n i n g or t h e e n d of t h e l i n e . T o f u r t h e r q u a l i f y t h e p o s i t i o n of
t h e s e c o n d s t r i n g , y o u u s e or o m i t t h e L or t h e E q u a l i f i e r s .
If y o u g i v e E D I T a n A , B , o r E c o m m a n d o n a line t h a t d o e s n o t m a t c h t h e
q u a l i f i e d s t r i n g g i v e n a s t h e first a r g u m e n t , t h e f o l l o w i n g m e s s a g e a p p e a r s
e i t h e r o n t h e s c r e e n or i n a verification file t h a t y o u s p e c i f i e d w h e n y o u e n t e r e d
EDIT.
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
AMIGADOS USER'S MANUAL
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
EDIT—THE LINE EDITOR
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
equivalent of typing D I (D for Delete followed b y I for Insert). F o r e x a m p l e ,
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
Y o u can also use individual repeat counts as s h o w n in the e x a m p l e s for N
and D above with many EDIT commands.
In addition, y o u can repeat
a
collection of c o m m a n d s b y forming t h e m into a c o m m a n d g r o u p u s i n g p a r e n theses as follows:
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
e x t e n d over m o r e t h a n o n e line of c o m m a n d input.
4.1.3 Leaving EDIT
T o e n d a n E D I T s e s s i o n , y o u u s e t h e c o m m a n d W (for W i n d u p ) . E D I T " w i n d s
t h r o u g h " to t h e e n d o f t h e s o u r c e , c o p y i n g it to t h e d e s t i n a t i o n , a n d e x i t s .
U n l e s s y o u s p e c i f y a T O file, E D I T r e n a m e s t h e t e m p o r a r y o u t p u t file a s t h e
F R O M filename.
E D I T can accept c o m m a n d s from a n u m b e r of c o m m a n d sources. In t h e
s i m p l e s t c a s e , E D I T a c c e p t s c o m m a n d s directly f r o m t h e t e r m i n a l ( t h a t i s , f r o m
t h e k e y b o a r d ) ; t h i s is called t h e p r i m a r y c o m m a n d l e v e l . E D I T c a n , h o w e v e r ,
a c c e p t c o m m a n d s f r o m o t h e r s o u r c e s , for e x a m p l e , c o m m a n d files or W I T H
files.
116
AMIGADOS USER'S MANUAL
Y o u c a n call c o m m a n d files f r o m w i t h i n E D I T , a n d f u r t h e r c o m m a n d files
f r o m w i t h i n c o m m a n d files, w i t h t h e C c o m m a n d , s o t h a t e a c h n e s t e d c o m m a n d file b e c o m e s a s e p a r a t e c o m m a n d level. E D I T s t o p s e x e c u t i n g t h e c o m m a n d s i n t h e c o m m a n d file w h e n it c o m e s to t h e e n d of t h e c o m m a n d file, o r
w h e n it f i n d s a Q . W h e n E D I T r e c e i v e s a Q c o m m a n d in a c o m m a n d file, o r it
c o m e s to t h e e n d of t h e file, it i m m e d i a t e l y s t o p s e x e c u t i n g c o m m a n d s f r o m
t h a t file, a n d r e v e r t s to t h e p r e v i o u s c o m m a n d l e v e l . If E D I T f i n d s a Q
c o m m a n d i n a n e s t e d c o m m a n d file, it r e t u r n s t o e x e c u t i n g c o m m a n d s i n t h e
c o m m a n d file at t h e l e v e l a b o v e . If y o u s t o p e d i t i n g at t h e p r i m a r y c o m m a n d
l e v e l , b y t y p i n g Q , o r if E D I T f i n d s a Q in a W I T H file, t h e n E D I T w i n d s u p a n d
exits i n t h e s a m e w a y a s it d o e s w i t h W .
T h e c o m m a n d S T O P terminates EDIT without any further processing. In
p a r t i c u l a r , E D I T d o e s n o t w r i t e o u t a n y p e n d i n g l i n e s of o u t p u t still in m e m o r y
s o t h a t t h e d e s t i n a t i o n file is i n c o m p l e t e . If y o u o n l y s p e c i f y t h e F R O M
a r g u m e n t , E D I T d o e s N O T o v e r w r i t e t h e s o u r c e file w i t h t h e ( i n c o m p l e t e )
e d i t e d file. Y o u s h o u l d o n l y u s e S T O P if y o u d o n o t n e e d t h e o u t p u t f r o m t h e
EDIT run.
E D I T w r i t e s a t e m p o r a r y b a c k u p to : T / E D - B A C K U P w h e n y o u exit w i t h t h e
W or Q c o m m a n d s . T h i s b a c k u p file r e m a i n s until y o u exit f r o m E D I T w i t h
t h e s e c o m m a n d s a g a i n , w h e r e u p o n E D I T o v e r w r i t e s t h e file w i t h a n e w b a c k u p .
If y o u u s e t h e S T O P c o m m a n d , E D I T d o e s n o t w r i t e to t h i s file.
4.1.4 A Combined Example: Pulling It All Together
Y o u can m e e t most simple editing requirements with the c o m m a n d s already
described. This section presents an example that uses several c o m m a n d s . T h e
text in italics f o l l o w i n g t h e e d i t i n g c o m m a n d s i n t h e e x a m p l e is a c o m m e n t .
Y o u are not m e a n t to type these c o m m e n t s ; EDIT does not allow c o m m e n t s in
c o m m a n d lines.
T o m a k e it e a s i e r for y o u to f o l l o w w h a t is h a p p e n i n g , w e h a v e i n c l u d e d t h i s
file a s " E d i t S a m p l e " o n y o u r a c c o m p a n y i n g d i s k .
T a k e t h e f o l l o w i n g s o u r c e text ( w i t h line n u m b e r s ) :
1
2
3
4
5
Tweedledee and Tweedledum
a g r e e d t o a. b a t t l e ,
F o r T w e e d l e d u m said T w e e d l e d e e
a d s p o i l e d his n i c e n e w rattle.
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
Execute these EDIT commands:
EDIT—THE LINE EDITOR
Ml; E/dum/dee/; E/dee/dum/
N; E/a/A/; B /a /have /
F B/ad/; B//H/
F P//; W; I
Just then flew down a monstrous
crow,
Z
M6; 2 ( A UIJ; N)
F/quore/; E/quorell/quarrel./
117
< t h e order of t h e E c o m m a n d s m a t t e r s ! >
< n o w a t line 2 >
< H at l i n e s t a r t >
< b e f o r e line after b l a n k o n e >
< 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 >
W
<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
Tweedledum and Tweedledee
2
A g r e e d to have a battle,
3
For T w e e d l e d u m said T w e e d l e d e e
4
H a d s p o i l e d h i s n i c e n e w rattle.
5
6
Just then flew d o w n a monstrous crow,
7
A s b l a c k a s a tar b a r r e l ,
8
Which frightened both the heroes so,
9
T h e y quite forgot their quarrel.
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 " .
4.2 A Complete Specification of EDIT
A f t e r r e a d i n g t h e first p a r t o f t h i s c h a p t e r o n t h e b a s i c f e a t u r e s o f E D I T , y o u
s h o u l d b e a b l e t o u s e t h e e d i t o r i n a s i m p l e w a y . T h e r e s t o f t h i s c h a p t e r is a
r e f e r e n c e s e c t i o n t h a t p r o v i d e s a full s p e c i f i c a t i o n o f all t h e f e a t u r e s o f E D I T .
Y o u m a y n e e d to c o n s u l t t h i s s e c t i o n if y o u h a v e a n y p r o b l e m s w h e n e d i t i n g o r
if y o u w a n t to u s e E D I T in a m o r e s o p h i s t i c a t e d w a y .
T h e features described in this section are as follows:
AMIGADOS USER'S MANUAL
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
4.2.1 Command Syntax
EDIT commands
arguments.
consist of a c o m m a n d
O n e or more
name
followed by zero or
space characters m a y optionally appear
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
EDIT reaches the end
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
EDIT—THE LINE EDITOR
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
C o m m a n d s that take two string a r g u m e n t s use the s a m e delimiter for
b o t h a n d d o n o t d o u b l e it b e t w e e n t h e a r g u m e n t s . A n e x a m p l e is t h e A
command:
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
AMIGADOS USER'S MANUAL
120
B c o m m a n d , t h e n nothing h a p p e n s b e c a u s e y o u have asked EDIT to insert
n o t h i n g a f t e r o r b e f o r e t h e first s t r i n g . H o w e v e r , if y o u o m i t t h e s e c o n d s t r i n g
a f t e r a n E c o m m a n d , E D I T d e l e t e s t h e first s t r i n g .
4.2.1.5
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
always be greater than zero. Wherever
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
EDIT—THE LINE EDITOR
121
t h e n type V + , E D I T turns the verification o n again. In this c a s e , y o u c a n
consider + as " o n " a n d - as " o f f " .
4.2.1.9
Command
Groups
T o m a k e a n u m b e r of individual EDIT c o m m a n d s into a c o m m a n d group,
y o u c a n enclose t h e m in p a r e n t h e s e s . For e x a m p l e , the following line:
(f/Walms/;e/Walrus/Large Marine Mammal/)
f i n d s t h e n e x t o c c u r r e n c e o f ' W a l r u s ' a n d c h a n g e s it t o ' L a r g e M a r i n e M a m mal'. C o m m a n d g r o u p s , h o w e v e r , m a y n o t span m o r e than o n e line of input.
F o r i n s t a n c e , if y o u t y p e a c o m m a n d g r o u p t h a t i s l o n g e r t h a n o n e l i n e , E D I T
o n l y a c c e p t s t h e c o m m a n d s u p to t h e e n d of t h e first l i n e . T h e n , b e c a u s e E D I T
d o e s n o t f i n d a c l o s i n g p a r e n t h e s i s at t h e e n d o f t h a t l i n e , it d i s p l a y s t h e
following error m e s s a g e :
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
EDIT accepts m a n y c o m m a n d s preceded by an unsigned decimal n u m b e r to
indicate repetition. For example
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 :
12(F/handsome/; E/handsome/hansom/; 3N)
AMIGADOS USER'S MANUAL
122
4.2.2 Processing EDIT
T h i s s e c t i o n d e s c r i b e s w h a t h a p p e n s w h e n y o u r u n E D I T . It g i v e s d e t a i l s a b o u t
where input comes from and where the output goes, what should appear on
y o u r s c r e e n , a n d w h a t s h o u l d e v e n t u a l l y a p p e a r i n y o u r file a f t e r y o u h a v e r u n
EDIT.
4.2.2.1
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
EDIT—THE LINE EDITOR
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 :
Number expected after =
4 . 2 . 2 . 4 Qualified
Strings
T o specify contexts for EDIT searches, y o u can use qualified strings. E D I T
a c c e p t s t h e n u l l s t r i n g a n d a l w a y s m a t c h e s it at t h e initial s e a r c h
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 .
EDIT—THE LINE EDITOR
125
4.2.3 Functional Groupings of EDIT Commands
T h i s s e c t i o n c o n t a i n s d e s c r i p t i o n s o f all E D I T c o m m a n d s split u p b y f u n c t i o n .
A s u m m a r y a n d a n a l p h a b e t i c a l list o f c o m m a n d s a p p e a r l a t e r .
T h e f o l l o w i n g d e s c r i p t i o n s u s e s l a s h e s (/) t o i n d i c a t e d e l i m i t e r
characters
(that is, characters that enclose strings). C o m m a n d n a m e s appear in u p p e r
c a s e ; a r g u m e n t t y p e s a p p e a r in l o w e r c a s e as f o l l o w s :
Notation
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
/
strings of arbitrary characters
c
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
T h e s e c o m m a n d s have n o function other than to select a n e w current line.
E D I T a d d s l i n e s t h a t it h a s p a s s e d i n a f o r w a r d d i r e c t i o n to t h e d e s t i n a t i o n
o u t p u t q u e u e (for f u r t h e r d e t a i l s o n t h e o u t p u t q u e u e , s e e S e c t i o n 4 . 1 , " I n t r o ducing EDIT").
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,
EDIT—THE LINE EDITOR
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 =
a). Y o u m a y omit both
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
b
b e c o m e s the n e w current line.
T h e s y n t a x for t h e D ( D e l e t e ) c o m m a n d is a s f o l l o w s :
Dab
S o , D d e l e t e s all l i n e s f r o m a t o b i n c l u s i v e . Y o u m a y o m i t t h e s e c o n d l i n e
n u m b e r if y o u w a n t t o d e l e t e j u s t t h e o n e line ( t h a t is, if b = a ) . Y o u m a y o m i t
b o t h n u m b e r s if y o u w a n t to d e l e t 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 b
b e c o m e s the n e w current line.
T h e s y n t a x of t h e D F ( D e l e t e F i n d ) c o m m a n d is
D F se
T h e c o m m a n d D F ( D e l e t e F i n d ) tells E D I T to d e l e t e s u c c e s s i v e l i n e s f r o m
t h e s o u r c e u n t i l it f i n d s a l i n e m a t c h i n g t h e s e a r c h e x p r e s s i o n . T h i s l i n e t h e n
b e c o m e s the n e w current line. A D F c o m m a n d with n o argument
( d e l e t i n g a s it g o e s ) u s i n g t h e last s e a r c h e x p r e s s i o n y o u t y p e d .
searches
AMIGADOS USER'S M A N U A L
128
4.2.4 Line Windows
E D I T usually acts o n a complete current line. H o w e v e r , y o u can define parts of
t h e line w h e r e E D I T c a n e x e c u t e y o u r s u b s e q u e n t c o m m a n d s . T h e s e p a r t s o f
lines are called line w i n d o w s . This section describes the c o m m a n d s y o u u s e to
define a window.
4.2.4.1
The Operational
Window
E D I T u s u a l l y s c a n s all t h e c h a r a c t e r s i n a l i n e w h e n l o o k i n g f o r a g i v e n
s t r i n g . H o w e v e r it is p o s s i b l e t o s p e c i f y a " l i n e w i n d o w " , s o t h a t t h e s c a n f o r a
c h a r a c t e r s t a r t s at t h e b e g i n n i n g of t h e w i n d o w , a n d n o t at t h e start of t h e l i n e .
I n all t h e d e s c r i p t i o n s o f E D I T c o n t e x t c o m m a n d s , " t h e b e g i n n i n g o f t h e l i n e "
a l w a y s m e a n s " t h e b e g i n n i n g of t h e o p e r a t i o n a l w i n d o w . "
W h e n e v e r E D I T verifies a c u r r e n t l i n e , it i n d i c a t e s t h e p o s i t i o n of t h e o p e r a t i o n a l w i n d o w b y d i s p l a y i n g a " > " c h a r a c t e r directly b e n e a t h t h e l i n e . F o r
example in the following:
26.
This is line 86 this is.
>
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 ,
EDIT—THE LINE EDITOR
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
T h e following two c o m m a n d s move the character pointer one place to the
r i g h t a f t e r f o r c i n g t h e first l e t t e r i n t o e i t h e r u p p e r o r l o w e r c a s e . If t h e first
c h a r a c t e r is n o t a l e t t e r , o r is a l r e a d y in t h e r e q u i r e d c a s e , t h e s e c o m m a n d s a r e
equivalent to > .
The command
$
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
into a space character, t h e n m o v e s the character pointer o n e place to
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//
AMIGADOS USER'S MANUAL
130
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 " , for 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 t o t h e s i n g l e c o m m a n d
E/s//
w h e r e " s " is t h e first " n " c h a r a c t e r in t h e w i n d o w or t h e w h o l e o f t h e c o n t e n t s
o f t h e w i n d o w , w h i c h e v e r is t h e s h o r t e r . C o n s i d e r t h e f o l l o w i n g e x a m p l e :
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 " > " % " $ "
" a n d " # " c o m m a n d s to e d i t a l i n e
character by character, the c o m m a n d s appearing under the characters
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 :
o Oysters,, Come ANDDWALK with
us
%>$$$$$$$#»$$$$$$$$_$$$$$$$$$$###
T h e c o m m a n d s i n t h e e x a m p l e a b o v e c h a n g e t h e l i n e to
O oysters, come and walk with us
leaving the character pointer immediately before the word " u s " .
4.2.5 String Operations on the Current Line
T o s p e c i f y w h i c h p a r t o f t h e c u r r e n t l i n e to q u a l i f y , y o u c a n e i t h e r a l t e r t h e
b a s i c s t r i n g o r p o i n t to a v a r i a n t , a s d e s c r i b e d in t h e n e x t t w o s e c t i o n s .
4.2.5.1
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
The Carpenter beseech
then the commands
131
EDIT—THE LINE EDITOR
E U/carpenter/Walrus/
<Exchange>
B/bese/did /
< i n s e r t string b e f o r e >
A L//;/
< I n s e r t string a f t e r >
w o u l d c h a n g e t h e line to
The Walrus did beseech;
4 . 2 . 5 . 2 The Null
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
(insert After a n d Point), B P
(insert Before a n d Point), a n d
EP
(Exchange a n d Point) c o m m a n d s take two strings as arguments a n d act exactly
like A , B , a n d E . H o w e v e r , A P , B P , a n d E P h a v e a n a d d i t i o n a l f e a t u r e : w h e n
t h e o p e r a t i o n is c o m p l e t e , t h e c h a r a c t e r p o i n t e r is left p o i n t i n g t o t h e first
character following b o t h text strings. S o , using the s a m e c o m m a n d
notation,
AP/s/t/
is e q u i v a l e n t t o
A/s/t/;PA/st/
while
syntax
132
AMIGADOS USER'S MANUAL
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
tweadledum and TWEADLEdee
into
Tweedledum and Tweedledee
leaving the character pointer just before dee.
4 . 2 . 5 . 4 Deleting
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
All the King's horses and all the King's men
then the command
DTB L/Klng's/
w o u l d c h a n g e it t o
King's men
while
DTA/horses /
w o u l d c h a n g e it to
and all the King's men
133
EDIT—THE LINE EDITOR
4.2.6 Miscellaneous Current Line Commands
This section includes some further c o m m a n d s
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
Splits t h e current line Before the context y o u specify with t h e qualifier a n d
s t r i n g . E D I T s e n d s t h e first p a r t o f t h e l i n e t o t h e o u t p u t a n d m a k e s
the
remainder into a n e w , nonoriginal current line.
T o split a l i n e a f t e r 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 A c o m m a n d . T h e s y n t a x
for S A is
S A q/s/
S A t a k e s a n o p t i o n a l q u a l i f i e r a n d a s t r i n g (q a n d Isl).
S A Splits the current
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
AMIGADOS USER'S MANUAL
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
Humpty Dumpty sat on a wall; Humpty
Dumpty had a
great fall.
T h e o l d v e r s e a p p e a r s d i s j o i n t e d ; t h e l i n e s n e e d to b e b a l a n c e d . If y o u m a k e
t h e first l i n e t h e c u r r e n t l i n e , t h e c o m m a n d s
SA /; /; 2CL/ /
c h a n g e the line into
Humpty Dumpty sat on a wall;
leaving
Humpty Dumpty had a great fall.
as t h e n e w c u r r e n t l i n e .
4.2.7 Inspecting Parts of the Source: The Type Commands
T h e f o l l o w i n g c o m m a n d s all tell E D I T to a d v a n c e t h r o u g h t h e s o u r c e , s e n d i n g
t h e l i n e s it p a s s e s to t h e v e r i f i c a t i o n file as w e l l a s to t h e n o r m a l o u t p u t ( w h e r e
r e l e v a n t ) . B e c a u s e t h e s e c o m m a n d s are m o s t f r e q u e n t l y u s e d i n t e r a c t i v e l y ( t h a t
i s , w i t h v e r i f i c a t i o n to t h e s c r e e n ) , t h e y a r e k n o w n a s t h e " t y p e " c o m m a n d s .
T h e y h a v e t h i s n a m e b e c a u s e y o u c a n u s e t h e m to " t y p e " o u t t h e l i n e s y o u
specify on the screen. This does not h o w e v e r m e a n that y o u cannot use t h e m
to s e n d o u t p u t t o a file. A f t e r E D I T h a s e x e c u t e d o n e o f t h e s e c o m m a n d s , t h e
last l i n e it " t y p e d " ( t h a t i s , d i s p l a y e d ) b e c o m e s t h e n e w c u r r e n t l i n e .
T h e s y n t a x f o r t h e T ( T y p e ) c o m m a n d is
Tn
T n t y p e s " n " l i n e s . If y o u o m i t " n " , t y p i n g c o n t i n u e s u n t i l t h e e n d o f t h e
source. However, you can always interrupt the typing with CTRL-C.
135
EDIT—THE LINE EDITOR
Note: T h r o u g h o u t this m a n u a l w h e n y o u see a h y p h e n b e t w e e n two k e y s ,
y o u p r e s s t h e m at t h e s a m e t i m e . S o C T R L - C m e a n s t o h o l d d o w n t h e C T R L
k e y while y o u type C.
W h e n y o u u s e t h e T c o m m a n d , t h e first l i n e E D I T t y p e s is t h e c u r r e n t l i n e ,
so that, for e x a m p l e ,
F /It's my own invention/; T6
t y p e s six l i n e s s t a r t i n g w i t h t h e o n e c o n t a i n i n g " I t ' s m y o w n i n v e n t i o n " . ( N o t e
t h a t to f i n d t h e c o r r e c t l i n e , y o u m u s t t y p e t h e " I " in " I t ' s " i n u p p e r c a s e . )
The command
TP
t y p e s t h e l i n e s i n t h e o u t p u t q u e u e . T h u s , T P ( T y p e P r e v i o u s ) is e q u i v a l e n t to
E D I T e x e c u t i n g M - f o l l o w e d b y t y p i n g u n t i l it r e a c h e s t h e l a s t l i n e it a c t u a l l y
read from the source.
The command
TN
t y p e s u n t i l E D I T h a s c h a n g e d all t h e l i n e s in t h e o u t p u t q u e u e . ( F o r m o r e
information on the output queue, see Section 4 . 1 , "Introducing E D I T . " ) S o ,
a T N (Type Next) c o m m a n d types N lines, where N was the n u m b e r specified
as
the
P
option.
(To
find
out
more
about
the
P
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
split l i n e s d o n o t h a v e l i n e n u m b e r s , E D I T d i s p l a y s a " + + + + " i n s t e a d . F o r
example,
20 0 oysters, come and walk with, us
+ + + + and then we'll have some tea
T h e o r i g i n a l l i n e s t a r t i n g w i t h " O o y s t e r s " h a s a line n u m b e r . T h e
o r i g i n a l l i n e , i n s e r t e d a f t e r l i n e 2 0 , starts w i t h +
+
+
non-
+ . (Remember that y o u
can u s e the = c o m m a n d to r e n u m b e r nonoriginal lines.)
136
AMIGADOS USER'S MANUAL
4.2.8 Control of Command, Input, and Output Files
E D I T u s e s f o u r t y p e s o f files:
• command
• input
• output
• verification
O n c e y o u h a v e e n t e r e d E D I T , y o u c a n n o t c h a n g e t h e v e r i f i c a t i o n file w i t h
a c o m m a n d . ( T o f i n d o u t m o r e a b o u t t h e v e r i f i c a t i o n file, s e e S e c t i o n 4 . 1 . 1 ,
"Calling E D I T . " ) The following sections describe c o m m a n d s that can change
the
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
following the C c o m m a n d . For example, the c o m m a n d
C .:T/XYZ.
r e a d s a n d e x e c u t e s c o m m a n d s f r o m t h e file : T / X Y Z
4.2.8.2
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.
T h e s e c o m m a n d s are described in Section
4.1.2.7
earlier in this chapter.
S e c t i o n 4 . 1 . 1 d e s c r i b e d h o w to call E D I T . I n t h a t s e c t i o n , t h e s o u r c e file w a s
r e f e r r e d t o a s t h e F R O M file. H o w e v e r , y o u c a n a l s o a s s o c i a t e t h e F R O M file
w i t h other files, u s i n g the c o m m a n d F R O M . T h e F R O M c o m m a n d h a s the
following form:
F R O M .s.
137
EDIT—THE LINE EDITOR
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
Pass lines 1-9 from
F R O M .XYZ.
Select
M6
Pass line 10 from
FROM
Reselect
M14
Pass line 6 from
F R O M .XYZ.
Reselect
new input,
the FROM
FROM,
lines 1-5 from
XYZ
XYZ,
lines 11-13 from
FROM
XYZ
Pass line 14 from
FROM
Reselect
FROM,
the rest of
XYZ
FROM
CF .XYZ.
Close
M*
Pass the rest of FROM
Output
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
AMIGADOS USER'S MANUAL
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
Pass lines 1-10
TO.XYZ.
Switch
M21
Pass lines 11-20
to
Pass lines 21-30
to TO
Pass lines 31-40
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 ,
EDIT—THE LINE EDITOR
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 ,
12(F/handsome/; E/handsome/hansom/; 3N)
I f y o u g i v e a r e p e a t c o u n t o f z e r o ( 0 ) , t h e c o m m a n d o r c o m m a n d g r o u p is
r e p e a t e d i n d e f i n i t e l y or u n t i l E D I T r e a c h e s t h e e n d of t h e s o u r c e .
4.2.10 Global Operations
Global operations are operations that take place automatically as E D I T scans
t h e s o u r c e i n a f o r w a r d d i r e c t i o n . Y o u c a n start a n d s t o p g l o b a l o p e r a t i o n s w i t h
s p e c i a l c o m m a n d s , d e s c r i b e d in t h e f o l l o w i n g s e c t i o n s .
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
Three c o m m a n d s , G A , G B , a n d G E are provided for simple string c h a n g e s
o n e a c h l i n e . T h e i r s y n t a x is a s f o l l o w s :
G A q/s/t/
G B q/s/t/
G E q/s/t/
T h e s e c o m m a n d s a p p l y a n A , B , or E c o m m a n d , a s a p p r o p r i a t e , t o a n y
o c c u r r e n c e o f s t r i n g " s " in a n e w c u r r e n t l i n e . T h e y a l s o a p p l y t o t h e l i n e t h a t
is c u r r e n t at t h e t i m e t h e c o m m a n d is e x e c u t e d .
G c o m m a n d s d o n o t r e s c a n t h e i r r e p l a c e m e n t text; f o r e x a m p l e , t h e f o l l o w ing command
GE/Tiger Lily/Tiger Lily/
w o u l d n o t l o o p f o r e v e r , b u t w o u l d h a v e n o visible e f f e c t o n a n y l i n e . H o w e v e r ,
as a result of t h e " c h a n g e " , E D I T w o u l d verify certain lines.
E D I T a p p l i e s t h e g l o b a l c h a n g e s t o e a c h n e w c u r r e n t l i n e in t h e o r d e r in
which you gave the commands.
140
4.2.10.2
AMIGADOS USER'S MANUAL
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
Y o u can s u s p e n d individual global operations, a n d later r e s u m e using t h e m
with D G (Disable Global) a n d E G (Enable Global) c o m m a n d s . T h e s e take the
g l o b a l i d e n t i f i c a t i o n n u m b e r a s t h e i r a r g u m e n t . If y o u o m i t t h e
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 .
4.2.11 Displaying the Program State
T w o c o m m a n d s b e g i n n i n g w i t h S H (for S H o w ) o u t p u t i n f o r m a t i o n a b o u t t h e
s t a t e o f E D I T to t h e v e r i f i c a t i o n file.
T h e c o m m a n d S H D (SHow Data) takes the form
SHD
a n d d i s p l a y s s a v e d i n f o r m a t i o n v a l u e s , s u c h a s t h e last s e a r c h e x p r e s s i o n .
T h e c o m m a n d S H G ( S H o w Globals) takes the form
SHG
a n d displays the current global c o m m a n d s , together with their identification
n u m b e r s . It a l s o g i v e s t h e n u m b e r o f t i m e s e a c h g l o b a l s e a r c h
expression
matches.
4.2.12 Terminating an EDIT Run
T o " w i n d t h r o u g h " t h e rest of the source, you u s e t h e W c o m m a n d ( W i n d u p ) .
N o t e t h a t W is i l l e g a l if o u t p u t is n o t c u r r e n t l y d i r e c t e d t o T O . E D I T e x i t s w h e n
it h a s r e a c h e d t h e e n d o f t h e s o u r c e , c l o s e d all t h e f i l e s , a n d r e l i n q u i s h e d t h e
m e m o r y . R e a c h i n g t h e e n d o f t h e h i g h e s t l e v e l c o m m a n d file h a s t h e s a m e e f f e c t
a s W . If y o u call E D I T s p e c i f y i n g o n l y t h e F R O M f i l e n a m e , E D I T r e n a m e s t h e
t e m p o r a r y o u t p u t file it c r e a t e d w i t h t h e s a m e n a m e a s t h e o r i g i n a l ( t h a t i s , t h e
F R O M f i l e n a m e ) , w h i l e it r e n a m e s t h e o r i g i n a l i n f o r m a t i o n a s t h e file : T / E D I T -
141
EDIT—THE LINE EDITOR
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 .
4.2.13 Current Line Verification
T h e following circumstances can cause automatic verification to occur:
• W h e n y o u type a n e w line of c o m m a n d s for a current line that E D I T h a s
not verified
s i n c e it m a d e
the line current,
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
text o n the next line.
A n alternate f o r m of verification, useful for lines c o n t a i n i n g
c h a r a c t e r s , is p r o v i d e d b y t h e c o m m a n d
nonprinting
142
AMIGADOS USER'S MANUAL
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
use the E c o m m a n d to e x c h a n g e " ? ? " for " C a r p e n t e r " .
n o t r e c o g n i z e t h e text it d i s p l a y e d w i t h " ? ? " as t w o
" ? ? " characters correspond to two nongraphic characreally is t h e r e , y o u u s e t h e ! c o m m a n d a s f o l l o w s :
!
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.)
4.2.14 Miscellaneous Commands
T h i s s e c t i o n d e s c r i b e s all t h o s e c o m m a n d s t h a t d o n o t fit n e a t l y i n t o a n y of t h e
p r e v i o u s c a t e g o r i e s . It d e s c r i b e s h o w t o c h a n g e a t e r m i n a t i o n c h a r a c t e r , t u r n
trailing s p a c e s off, r e n u m b e r l i n e s , a n d r e w i n d t h e s o u r c e file.
T o c h a n g e t h e t e r m i n a t o r for t e x t i n s e r t i o n , y o u u s e t h e Z c o m m a n d . T h e Z
c o m m a n d has the following form:
Z/s/
w h e r e /s/ r e p r e s e n t s a s t r i n g . T h e s t r i n g m a y b e of a n y l e n g t h u p t o 16
c h a r a c t e r s . T h e s t r i n g is m a t c h e d in e i t h e r c a s e . In e f f e c t , t h e s e a r c h f o r t h e
t e r m i n a t o r is d o n e u s i n g t h e qualifiers P U . T h e initial t e r m i n a t o r s t r i n g is Z .
143
EDIT—THE LINE EDITOR
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
takes the form:
= n
where
"n"
represents a number.
The command
=n
sets the current
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
s o u r c e file, E D I T r e n u m b e r s all t h e l i n e s in t h e file-original, n o n o r i g i n a l , a n d
those previously renumbered with 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.
4.2.15 Abandoning Interactive Editing
T o a b a n d o n m o s t c o m m a n d s t h a t r e a d t e x t , y o u p r e s s C T R L - C . I n p a r t i c u l a r , if
y o u realize that a search expression h a s b e e n m i s t y p e d , t h e n C T R L - C stops the
s e a r c h . S i m i l a r l y t h e T c o m m a n d t y p e s to t h e e n d o f t h e s o u r c e , b u t C T R L - C
a b a n d o n s this action.
After you press CTRL-C, EDIT responds with the message
*** BREAK
144
AMIGADOS USER'S MANUAL
a n d r e t u r n s to reading c o m m a n d s . T h e current line d o e s , of course, d e p e n d o n
exactly w h e n you pressed C T R L - C .
Quick Reference Card
T h i s list u s e s t h e f o l l o w i n g a b b r e v i a t i o n s :
Notation
Description
qs
Qualified string
t
String
n
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)
Character Pointer Commands (Line Window Commands)
Command
<
Action
M o v e c h a r a c t e r p o i n t e r left
>
M o v e character pointer right
#
$
%
—
Delete character at pointer
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
+
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
-
M o v e to lowest line in m e m o r y
N
N e x t line
P
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
EDIT—THE LINE EDITOR
Text Verification
Command
Action
?
Verify current line
!
Verify with character indicators
T
T y p e t o e n d o f file
Tn
Type n lines
TLn
Type n lines with line n u m b e r s
TN
Type until buffer c h a n g e d
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
Operations on the Current Line
Command
Action
A qs t
Place string t after qs
A P qs t
S a m e as A, but m o v e character pointer
B qs t
Place string t before qs
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
Globally place t before qs
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
AMIGADOS USER'S MANUAL
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
=
n
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
W
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
Error Codes and Messages
T h e error m e s s a g e s that appear on the screen w h e n y o u use the F A U L T or
W H Y c o m m a n d fall i n t o t w o g e n e r a l c a t e g o r i e s :
1. u s e r e r r o r s
2. programmer errors.
This a p p e n d i x gives the probable cause a n d a suggestion for recovery for
e a c h of t h e s e e r r o r c o d e s . T h e c o d e s a p p e a r i n n u m e r i c a l o r d e r w i t h i n t h e i r
category.
User Errors
103: insufficient free
Probable
cause:
store
Y o u d o n ' t h a v e e n o u g h physical m e m o r y on the A m i g a to carry this operation out.
Recovery
suggestion:
First, try t o s t o p s o m e of t h e a p p l i c a t i o n s t h a t a r e r u n n i n g t h a t y o u d o n ' t
n e e d . For example, close any unnecessary w i n d o w s . Otherwise, b u y m o r e
m e m o r y . S t o p s o m e of t h e tasks t h a t are less i m p o r t a n t to y o u a n d r e i s s u e t h e
c o m m a n d . It m a y b e t h a t y o u h a v e e n o u g h m e m o r y , b u t it h a s b e c o m e
" f r a g m e n t e d " ; rebooting may help.
104: task table full
Probable
cause:
L i m i t e d to 2 0 C L I t a s k s , or e q u i v a l e n t .
2 2 0 : argument line invalid or too long
Probable
cause:
Y o u r a r g u m e n t for this c o m m a n d is i n c o r r e c t or c o n t a i n s t o o m a n y o p t i o n s .
Recovery
suggestion:
C o n s u l t t h e c o m m a n d s p e c i f i c a t i o n s in C h a p t e r 2 of t h i s m a n u a l f o r t h e
correct a r g u m e n t template.
AMIGADOS USER'S MANUAL
148
221: file is not an object
Probable
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:
Y o u m u s t first d e l e t e t h e d i r e c t o r y or file if y o u really w a n t to r e u s e t h a t
name.
204: directory
205: object
Probable
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
APPENDIX: ERROR CODES AND MESSAGES
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:
You should respecify the window.
2 2 0 : invalid
Probable
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:
M a y b e y o u ' v e tried to do a n operation that requires a filename a n d y o u gave
it a d i r e c t o r y n a m e o r vice
versa.
For example, you might have given
the
c o m m a n d T Y P E dir, w h e r e " d i r " is a d i r e c t o r y . A m i g a D O S d o e s n ' t a l l o w y o u
to d i s p l a y a d i r e c t o r y , o n l y f i l e s .
Recovery
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
AMIGADOS USER'S MANUAL
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
APPENDIX: ERROR CODES AND MESSAGES
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
AMIGADOS USER'S MANUAL
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.
Current string alteration c o m m a n d
A n instruction that c h a n g e s the current string.
Delimiter characters
C h a r a c t e r s u s e d at t h e b e g i n n i n g a n d e n d o f a c h a r a c t e r s t r i n g .
Destination file
File b e i n g written to.
Device name
U n i q u e n a m e g i v e n to a d e v i c e , e . g . DFO: = f l o p p y d r i v e 0:.
Directory
A collection of f i l e s .
Editing commands
C o m m a n d s input from the keyboard that control an editing session.
Extended mode
C o m m a n d s a p p e a r o n the c o m m a n d line a n d are not e x e c u t e d until y o u
finish the c o m m a n d line.
File
A collection of related data.
Filename
A n a m e g i v e n to a file f o r i d e n t i f i c a t i o n p u r p o s e s .
Immediate mode
C o m m a n d s that are executed immediately.
Keyword
A r g u m e n t s t o c o m m a n d s t h a t m u s t b e s t a t e d explicitly.
Line windows
P a r t s o f a l i n e for E D I T to 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 .
Memory
T h i s is s o m e t i m e s k n o w n as s t o r e a n d is w h e r e a c o m p u t e r s t o r e s its d a t a
and instructions.
Multi-processing
T h e e x e c u t i o n o f t w o or m o r e p r o c e s s e s in p a r a l l e l , t h a t i s , at t h e
time.
Output queue
B u f f e r in m e m o r y h o l d i n g d a t a b e f o r e b e i n g w r i t t e n o u t to f i l e .
Priority
T h e relative i m p o r t a n c e of a p r o c e s s .
same
154
AMIGADOS USER'S MANUAL
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.
Programming on the Amiga
Calling AmigaDOS
The Macro Assembler
The Linker
Appendix: Console Input and Output on the Amiga
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
Programming on the Amiga
T h i s c h a p t e r i n t r o d u c e s t h e r e a d e r to p r o g r a m m i n g i n C o r A s s e m b l e r u n d e r
AmigaDOS.
1.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
Calling Resident Libraries
Creating an Executable Program
Running a Program Under the CLI
Initial E n v i r o n m e n t in A s s e m b l e r
Initial E n v i r o n m e n t i n C
F a i l u r e of R o u t i n e s
Terminating a Program
1.4
1.5
1.5.1
1.5.2
Running a Program Under the Workbench
Cross Development
Cross Development on a Sun Microsystem
Cross Development Under M S - D O S
1.5.3
Cross Development on Other Computers
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 .
AMIGADOS DEVELOPER'S MANUAL
158
1.2 Program Development for the Amiga
T h i s s e c t i o n d e s c r i b e s h o w to d e v e l o p p r o g r a m s for t h e A m i g a . It d e s c r i b e s
w h a t y o u n e e d b e f o r e y o u start, h o w y o u c a n call t h e s y s t e m r o u t i n e s , a n d
h o w t o c r e a t e a file t h a t y o u c a n e x e c u t e o n t h e A m i g a .
W A R N I N G : Before you do A N Y T H I N G , you should make a backup copy
o f y o u r s y s t e m d i s k . F o r i n s t r u c t i o n s , s e e t h e s e c t i o n , " B a c k i n g U p , " at
t h e b e g i n n i n g o f t h e AmigaDOS
User's Manual
in t h i s b o o k .
1.2.1 Getting Started
B e f o r e y o u start w r i t i n g p r o g r a m s for t h e A m i g a , y o u n e e d t h e
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
p r o v i d e s t h e s e h e a d e r files as i n c l u d e d files for e i t h e r C (usually e n d i n g in .h)
o r a s s e m b l e r ( e n d i n g in . i ) . T o u s e a p a r t i c u l a r r e s i d e n t l i b r a r y , y o u m u s t
i n c l u d e o n e o r m o r e h e a d e r files c o n t a i n i n g t h e r e l e v a n t d e f i n i t i o n s .
For
e x a m p l e , to u s e A m i g a D O S f r o m C , y o u m u s t i n c l u d e t h e file " d o s . h " .
4 . A n a s s e m b l e r or c o m p i l e r e i t h e r r u n n i n g o n t h e A m i g a itself or o n o n e o f
the cross development environments.
5 . T h e A m i g a l i n k e r , a g a i n r u n n i n g o n t h e A m i g a or o n a n o t h e r c o m p u t e r , a s
w e l l as t h e s t a n d a r d A m i g a library c o n t a i n i n g f u n c t i o n s , i n t e r f a c e r o u t i n e s ,
and various absolute values.
6. T o o l s to d o w n l o a d p r o g r a m s if y o u are u s i n g a c r o s s - d e v e l o p m e n t e n v i r o n m e n t .
2.2.2 Calling Resident Libraries
Y o u s h o u l d n o t e t h a t t h e r e a r e t w o w a y s o f calling s y s t e m r o u t i n e s f r o m a u s e r
a s s e m b l y p r o g r a m . C p r o g r a m m e r s s i m p l y call t h e f u n c t i o n as s p e c i f i e d . Y o u
u s u a l l y call a s y s t e m r o u t i n e in a s s e m b l e r b y p l a c i n g t h e library b a s e p o i n t e r
PROGRAMMING ON THE AMIGA
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
for further details
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 .
1.2.3 Creating an Executable Program
T o p r o d u c e a file t h a t y o u c a n e x e c u t e o n t h e A m i g a , y o u s h o u l d f o l l o w t h e f o u r
s t e p s b e l o w . Y o u c a n d o e a c h s t e p e i t h e r o n t h e A m i g a itself o r o n a s u i t a b l e
cross-development computer.
1. G e t y o u r p r o g r a m s o u r c e i n t o t h e A m i g a . T o d o t h i s , y o u c a n t y p e it d i r e c t l y
i n u s i n g a n e d i t o r , o r y o u c a n t r a n s f e r it f r o m a n o t h e r c o m p u t e r . N o t e t h a t
you can use the R E A D
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 !
1.3 Running a Program Under the CLI
T h e r e are t w o w a y s y o u can run a p r o g r a m . First, y o u can r u n y o u r p r o g r a m
under a CLI ( C o m m a n d Line Interface). Second, you can run your program
u n d e r t h e W o r k b e n c h . T h i s s e c t i o n d e s c r i b e s t h e first o f t h e t w o w a y s .
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 is a little like u s i n g a n
old-fashioned
AMIGADOS DEVELOPER'S MANUAL
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 .
1.3.1 Initial Environment in Assembler
W h e n you load a program under a CLI, you type the n a m e of the program and
a set of a r g u m e n t s . Y o u m a y also specify input or o u t p u t redirection b y m e a n s
o f t h e " > " a n d " < " s y m b o l s . T h e C L I a u t o m a t i c a l l y p r o v i d e s all t h i s i n f o r m a t i o n f o r t h e p r o g r a m w h e n it starts u p .
W h e n t h e C L I s t a r t s u p a p r o g r a m , it a l l o c a t e s a s t a c k f o r t h a t p r o g r a m . T h i s
s t a c k is initially 4 0 0 0 b y t e s , b u t y o u m a y c h a n g e t h e s t a c k size w i t h t h e S T A C K
c o m m a n d . A m i g a D O S o b t a i n s t h i s s t a c k f r o m t h e g e n e r a l free m e m o r y h e a p j u s t
b e f o r e y o u r u n t h e p r o g r a m ; it is n o t , h o w e v e r , t h e s a m e as t h e s t a c k t h a t t h e
C L I u s e s . A m i g a D O S p u s h e s a s u i t a b l e r e t u r n a d d r e s s o n t o t h e s t a c k t h a t tells
t h e C L I t o r e g a i n c o n t r o l a n d u n l o a d y o u r p r o g r a m . B e l o w t h i s o n t h e s t a c k at
4 ( S P ) is t h e s i z e o f t h e s t a c k i n b y t e s , w h i c h m a y b e u s e f u l if y o u w i s h t o
perform stack checking.
Y o u r p r o g r a m starts w i t h r e g i s t e r AO p o i n t i n g to t h e a r g u m e n t s y o u ,
or
a n y o n e else r u n n i n g y o u r p r o g r a m t y p e d . A m i g a D O S stores the a r g u m e n t line
in m e m o r y within the CLI stack a n d this pointer r e m a i n s valid t h r o u g h o u t
y o u r p r o g r a m . R e g i s t e r DO i n d i c a t e s t h e n u m b e r o f c h a r a c t e r s i n t h e a r g u m e n t
l i n e . Y o u c a n u s e t h e s e initial v a l u e s to d e c o d e t h e a r g u m e n t line to find o u t w h a t
t h e u s e r r e q u i r e s . N o t e t h a t all r e g i s t e r s m a y b e c o r r u p t e d b y a u s e r p r o g r a m .
T o m a k e t h e initial i n p u t a n d o u t p u t file h a n d l e s a v a i l a b l e , y o u call t h e
A m i g a D O S r o u t i n e s I n p u t ( ) a n d O u t p u t ( ) . R e m e m b e r t h a t y o u m a y h a v e to
o p e n t h e A m i g a D O S library b e f o r e y o u d o t h i s . T h e calls r e t u r n file h a n d l e s
that refer to the standard input and output the user requires. This standard
i n p u t a n d o u t p u t is u s u a l l y t h e t e r m i n a l u n l e s s y o u r e d i r e c t e d t h e I/O
by
i n c l u d i n g " > " or " < " o n t h e a r g u m e n t l i n e . Y o u s h o u l d n o t c l o s e t h e s e file
h a n d l e s w i t h y o u r p r o g r a m ; t h e C L I o p e n e d t h e m for y o u a n d it will c l o s e
t h e m , if r e q u i r e d .
1.3.2 Initial Environment in C
W h e n p r o g r a m m i n g in C , y o u s h o u l d a l w a y s i n c l u d e t h e s t a r t u p c o d e a s t h e
first e l e m e n t
in t h e l i n k e r i n p u t .
This m e a n s
that the linker enters
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 " .
PROGRAMMING ON THE AMIGA
161
1.3.3 Failure of Routines
M o s t A m i g a D O S r o u t i n e s r e t u r n a z e r o if t h e y fail; t h e e x c e p t i o n s a r e t h e R e a d
a n d W r i t e calls t h a t r e t u r n -1 o n f i n d i n g a n e r r o r . If y o u r e c e i v e a n e r r o r r e t u r n ,
y o u c a n call IoErr() to o b t a i n m o r e i n f o r m a t i o n o n t h e f a i l u r e . I o E r r ( ) r e t u r n s a n
i n t e g e r t h a t c o r r e s p o n d s t o a full e r r o r c o d e , a n d y o u m a y w i s h t o t a k e
d i f f e r e n t a c t i o n s d e p e n d i n g o n e x a c t l y w h y t h e call f a i l e d . A c o m p l e t e list of
e r r o r c o d e s a n d m e s s a g e s c a n b e f o u n d at t h e e n d of t h e AmigaDOS
User's
Manual in t h i s b o o k .
1.3.4 Terminating a Program
T o exit f r o m a p r o g r a m , it is sufficient to g i v e a s i m p l e R T S u s i n g t h e initial
s t a c k p o i n t e r ( S P ) . In t h i s c a s e , y o u s h o u l d p r o v i d e a r e t u r n c o d e i n r e g i s t e r
DO. T h i s is z e r o if y o u r p r o g r a m s u c c e e d e d ; o t h e r w i s e , it is a p o s i t i v e n u m b e r .
If y o u r e t u r n a n o n z e r o n u m b e r , t h e n t h e C L I n o t i c e s a n e r r o r . D e p e n d i n g o n
t h e c u r r e n t fail v a l u e (set b y t h e c o m m a n d F A I L A T ) , a n o n i n t e r a c t i v e C L I ,
such as o n e r u n n i n g a c o m m a n d s e q u e n c e set u p b y the E X E C U T E c o m m a n d ,
t e r m i n a t e s . A p r o g r a m w r i t t e n in C c a n s i m p l y r e t u r n f r o m " m a i n " w h i c h
r e t u r n s to t h e s t a r t u p c o d e ; this c l e a r s DO a n d p e r f o r m s a n R T S .
A l t e r n a t i v e l y a p r o g r a m m a y call t h e A m i g a D O S f u n c t i o n Exit, w h i c h t a k e s
t h e r e t u r n c o d e a s a r g u m e n t . T h i s instructs y o u r p r o g r a m to exit n o m a t t e r w h a t
value the stack pointer has.
It is i m p o r t a n t at t h i s s t a g e t o s t r e s s t h a t A m i g a D O S d o e s n o t c o n t r o l a n y
r e s o u r c e s ; t h i s is left e n t i r e l y u p to t h e p r o g r a m m e r . A n y files t h a t a u s e r
program opens must be closed before the program terminates. Likewise, any
l o c k s it o b t a i n s m u s t b e f r e e d , a n y c o d e it l o a d s m u s t b e u n l o a d e d , a n d a n y
m e m o r y it a l l o c a t e s r e t u r n e d . O f c o u r s e , t h e r e m a y b e c a s e s w h e r e y o u d o n o t
w i s h to r e t u r n all r e s o u r c e s , f o r e x a m p l e , w h e n y o u h a v e w r i t t e n a p r o g r a m
t h a t l o a d s a c o d e s e g m e n t i n t o m e m o r y for later u s e . T h i s is p e r f e c t l y a c c e p t able, but y o u m u s t h a v e a m e c h a n i s m for eventually returning a n y m e m o r y ,
file l o c k s , a n d s o o n .
1.4 Running a Program Under the Workbench
T o run a p r o g r a m u n d e r the W o r k b e n c h , y o u n e e d to appreciate the different
w a y s in w h i c h a p r o g r a m m a y b e r u n o n t h e A m i g a . U n d e r t h e C L I y o u r
p r o g r a m is r u n n i n g as p a r t of t h e C L I p r o c e s s . It c a n i n h e r i t I/O s t r e a m s a n d
other information from the CLI, such as the arguments y o u provided.
If a p r o g r a m is r u n n i n g u n d e r t h e W o r k b e n c h , t h e n A m i g a D O S s t a r t s it a s a
n e w p r o c e s s r u n n i n g at t h e s a m e t i m e a s W o r k b e n c h . W o r k b e n c h l o a d s t h e
p r o g r a m a n d t h e n s e n d s a m e s s a g e to g e t it s t a r t e d . Y o u m u s t t h e r e f o r e w a i t
AMIGADOS DEVELOPER'S MANUAL
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
routine. For assembly language p r o g r a m m e r s , this w o r k m u s t be d o n e yourself.
Y o u s h o u l d a l s o n o t e t h a t a p r o g r a m r u n n i n g as a n e w p r o c e s s i n i t i a t e d b y
W o r k b e n c h has n o default input and output streams. Y o u must ensure that
y o u r p r o g r a m o p e n s all t h e I/O c h a n n e l s t h a t it n e e d s , a n d t h a t it c l o s e s t h e m
all w h e n it h a s f i n i s h e d .
1.5 Cross Development
It y o u a r e u s i n g a c r o s s - d e v e l o p m e n t e n v i r o n m e n t , t h e n y o u n e e d t o d o w n l o a d
your
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.
1.5.1 Cross Development on a Sun Microsystem
T h e tools available o n the S u n Microsystem for cross d e v e l o p m e n t include the
a s s e m b l e r , l i n k e r , a n d t w o C c o m p i l e r s . T h e a r g u m e n t f o r m a t s of t h e a s s e m b l e r a n d l i n k e r o n t h e S u n M i c r o s y s t e m a r e i d e n t i c a l to t h o s e o n t h e A m i g a
w h e n r u n n i n g u n d e r t h e C L I . T h e G r e e n h i l l s C c o m p i l e r is o n l y a v a i l a b l e o n
t h e S u n M i c r o s y s t e m a n d is d e s c r i b e d h e r e .
T h e c o m p i l e r is c a l l e d m e t a c c ,
a n d it a c c e p t s
several types of files.
It
a s s u m e s t h a t f i l e n a m e s e n d i n g i n .c r e p r e s e n t C s o u r c e p r o g r a m s . T h e c o m piler then compiles these
.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
PROGRAMMING ON THE AMIGA
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
just compile the program, suppressing the loading phase of
t h e c o m p i l a t i o n , a n d f o r c i n g a n o b j e c t file t o b e
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
p r o d u c e a d d i t i o n a l s y m b o l table i n f o r m a t i o n for t h e d e b u g g e r d b x a n d t o p a s s t h e -lg flag to Id.
-go
produce additional symbol table information in a n
format set b y the adb debugger.
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 object code optimizer to improve
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.
W A R N I N G : Certain programs run m u c h faster using the -fsingle option,
b u t b e w a r e t h a t y o u c a n l o s e s i g n i f i c a n c e d u e to l o w e r p r e c i s i o n i n t e r m e diate values.
164
-S
AMIGADOS DEVELOPER'S MANUAL
compile the specified C program(s) and leave the assemblerl a n g u a g e o u t p u t o n c o r r e s p o n d i n g files e n d i n g w i t h . o b j .
-E
run only the C preprocessor on the named C program(s) and
s e n d t h e r e s u l t to t h e s t a n d a r d o u t p u t .
-c
prevent the C preprocessor from removing comments.
-X70
generate code using A m i g a floating point format. This c o d e
is c o m p a t i b l e w i t h t h e f l o a t i n g p o i n t m a t h R O M library
provided on the Amiga.
-o < o u t p u t >
n a m e t h e final o u t p u t file " o u t p u t " . If y o u u s e t h i s o p t i o n ,
t h e file a . o u t is left u n d i s t u r b e d .
-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>
r e m o v e a n y initial d e f i n i t i o n of " n a m e " .
-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
< s t r i n g > w i t h t h e e n d i n g s c p p , c c o m , a n d c 2 . If " s t r i n g " is
empty, use a backup version.
-t[p012]
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
cpp—the C preprocessor
0
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.
1
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.
2
c2—the object code optimizer.
T h e compiler metacc a s s u m e s that other a r g u m e n t s are loaded option argum e n t s , o b j e c t p r o g r a m s , or libraries of o b j e c t p r o g r a m s . U n l e s s y o u s p e c i f y - c ,
- S , o r - E , m e t a c c l o a d s t h e s e p r o g r a m s a n d libraries t o g e t h e r w i t h t h e r e s u l t s of
a n y c o m p i l a t i o n s or a s s e m b l i e s s p e c i f i e d , (in t h e o r d e r g i v e n ) to p r o d u c e a n
165
PROGRAMMING ON THE AMIGA
executable program n a m e d a.out. To override the n a m e a.out, y o u can use the
loader's -o < n a m e >
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
Startoff for profiling
/lib/mcrtO.o
Startoff for gprof-profiling
/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
Files p r o d u c e d for analysis
mon.out
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
Figure l . A : Special metacc Filenames
Y o u c a n d o w n l o a d t h e files y o u p r o d u c e f r o m t h e l i n k e r o n t h e S u n t o y o u r
A m i g a in t h r e e w a y s : t h e first, a n d b y far t h e e a s i e s t , r e q u i r e s a B i l l B o a r d ; t h e
s e c o n d r e q u i r e s a p a r a l l e l p o r t ; a n d t h e t h i r d r e q u i r e s a serial l i n e .
If y o u
have
the
special
hardware
device
called
a BillBoard,
you
can
d o w n l o a d y o u r l i n k e d l o a d file (by c o n v e n t i o n t h i s s h o u l d e n d w i t h .Id) a s
follows:
1. S t a r t u p t h e p r o g r a m " b i n l o a d " o n t h e S u n
b i n l o a d -p &
(this n e e d o n l y b e d o n e o n c e )
166
AMIGADOS DEVELOPER'S MANUAL
2. Then on the Amiga, type
download < s u n filename> <amiga filename>
3. T o run the program, type
<amiga filename>
For example:
O n the Sun, type
b i n l o a d -p 6?
O n the Amiga, type
download testld test
or type
download /usr/commodore/amiga/V24/examples/DOS/test.ld test
then type
test
Note that D O W N L O A D
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
control conventions CTRL-C, CTRL-D, CTRL-E, and CTRL-F.)
If y o u d o n o t h a v e a B i l l B o a r d , y o u c a n d o w n l o a d files t h r o u g h a p a r a l l e l
port. To do this, follow these steps:
1. S e n d t h e d o w n l o a d
typing
send demold
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
PROGRAMMING ON THE AMIGA
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
C h a p t e r 2, for further details o n the A m i g a Binary L o a d files.)
Type
tip a m i g a
3. O n the Amiga, type
READ demo serial
4. Within tip, type
">
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
AMIGADOS DEVELOPER'S MANUAL
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:
">
1.5.2 Cross Development Under MS-DOS
T o c r o s s - d e v e l o p o n a c o m p u t e r r u n n i n g M S - D O S for y o u r A m i g a , y o u n e e d
v a r i o u s t o o l s t h a t a r e s u p p l i e d i n t h e d i r e c t o r y \V25\bin. T h e s e i n c l u d e t h e C
compiler, assembler, and linker as well as c o m m a n d s to assist in d o w n l o a d i n g .
Y o u u s e t h e s a m e s y n t a x for t h e t o o l s r u n n i n g u n d e r M S - D O S a s u n d e r t h e C L I
on the Amiga.
T o d o w n l o a d via a n I B M P C serial p o r t (called A U X ) , f o l l o w t h e s e s t e p s :
1. T y p e o n y o u r A m i g a
READ file SERIAL
2. O n the P C , type
convert <file.ld >AUX:
3. O n your Amiga, you can n o w type
file
to t h e p r o g r a m .
1.5.3 Cross Development on Other Computers
Y o u ' l l n e e d to h a v e a s u i t a b l e c r o s s c o m p i l e r or a s s e m b l e r , a n d to i n c l u d e
files d e f i n i n g all t h e e n t r y p o i n t s . Y o u ' l l a l s o n e e d e i t h e r t h e A m i g a l i n k e r
A L I N K r u n n i n g o n y o u r e q u i p m e n t or o n t h e A m i g a . Finally y o u ' l l n e e d a w a y
t o c o n v e r t a b i n a r y file i n t o a h e x a d e c i m a l s t r e a m t e r m i n a t e d w i t h a Q (as t h i s
PROGRAMMING ON THE AMIGA
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.1 Register Values
T h e l e t t e r / n u m b e r c o m b i n a t i o n (DO. . . D n ) r e p r e s e n t s r e g i s t e r s . T h e text t o t h e
left o f a n e q u a l s s i g n r e p r e s e n t s t h e r e s u l t of a f u n c t i o n . A r e g i s t e r (that i s , DO)
a p p e a r i n g u n d e r s u c h text i n d i c a t e s t h e r e g i s t e r v a l u e o f t h e r e s u l t . T e x t t o t h e
r i g h t o f a n e q u a l s s i g n r e p r e s e n t s a f u n c t i o n a n d its a r g u m e n t s , w h e r e t h e t e x t
e n c l o s e d in p a r e n t h e s e s is a list o f t h e a r g u m e n t s . A r e g i s t e r (for e x a m p l e , D 2 )
appearing u n d e r a n argument indicates the register value of that argument.
N o t e t h a t n o t all f u n c t i o n s r e t u r n a r e s u l t .
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.1.3 Boolean returns
-1 ( T R U E o r S U C C E S S ) , 0 ( F A L S E or F A I L U R E ) .
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.
2.2.5 Format, Argument, and Result
L o o k at " A r g u m e n t : " a n d " R e s u l t : " for f u r t h e r d e t a i l s o n t h e s y n t a x
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
Figure 2-A: Format of Functions and Registers
2.2 AmigaDOS Functions
This reference section describes the functions provided by the
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
explanation of t h e syntax of the a r g u m e n t s a n d result. To u s e a n y o f t h e s e
f u n c t i o n s , y o u m u s t link w i t h a m i g a . l i b .
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:
AMIGADOS DEVELOPER'S MANUAL
file—file 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:
lock - pointer to a lock
= 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:
To m a k e a directory associated with a lock the current
directory.
oldLock = CurrentDir(
lock )
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
CurrentDir m a k e s current a directory associated with a lock. (See also L O C K . )
It r e t u r n s t h e o l d c u r r e n t d i r e c t o r y l o c k .
A v a l u e o f z e r o is a v a l i d r e s u l t h e r e a n d i n d i c a t e s t h a t t h e c u r r e n t d i r e c t o r y
is t h e r o o t o f t h e initial s t a r t u p d i s 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:
To examine the next entry in a directory.
success = ExNext( lock, FilelnfoBlock
)
DO
Dl
D2
174
AMIGADOS DEVELOPER'S MANUAL
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
a
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
about the directory y o u wish
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:
Returns information about the disk.
Form:
success
DO
Argument:
Result:
Description:
= Info( lock, Info.
Dl
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
Data structure with information
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
Data must be longword aligned.
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
Islnteractive gives a boolean return.
This indicates
whether
o r n o t t h e file a s s o c i a t e d w i t h t h e file h a n d l e " f i l e " is c o n n e c t e d t o a v i r t u a l
terminal.
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:
lock - pointer to a lock
)
176
AMIGADOS DEVELOPER'S MANUAL
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
( t h a t is, if it c a n n o t o b t a i n 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 ) it r e t u r n s
a zero.
N o t e t h a t t h e o v e r h e a d for d o i n g a L o c k is l e s s t h a n t h a t for d o i n g
Open,
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:
n a m e - string accessMode - integer
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
( = 1006). T h e " n a m e " can be a filename (optionally prefaced by a device n a m e ) ,
a s i m p l e d e v i c e s u c h a s N I L : , a w i n d o w s p e c i f i c a t i o n s u c h as C O N : o r R A W :
followed b y w i n d o w p a r a m e t e r s , or *, r e p r e s e n t i n g t h e current w i n d o w .
For further details o n the devices N I L : , C O N : , a n d R A W : , see C h a p t e r 1 of
t h e AmigaDOS
User's Manual
in this b o o k . If O p e n c a n n o t o p e n t h e file " n a m e "
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
AMIGADOS DEVELOPER'S MANUAL
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
S e e k s e t s t h e r e a d / w r i t e c u r s o r f o r t h e file " f i l e " to t h e p o s i t i o n " p o s i t i o n " . B o t h
R e a d a n d W r i t e u s e t h i s p o s i t i o n as a p l a c e t o start r e a d i n g or w r i t i n g . If all
g o e s w e l l , t h e r e s u l t is t h e p r e v i o u s p o s i t i o n in t h e file. If a n e r r o r o c c u r s , t h e
r e s u l t is - 1 . Y o u c a n t h e n u s e IoErr() to f i n d o u t m o r e i n f o r m a t i o n a b o u t t h e
error.
" M o d e " can be O F F S E T
B E G I N N I N G ( = 1 ) , O F F S E T — C U R R E N T ( = 0) o r
OFFSET
E N D ( = 1 ) . Y o u u s e it t o s p e c i f y t h e r e l a t i v e start p o s i t i o n . F o r e x a m p l e , 2 0 f r o m c u r r e n t is a p o s i t i o n t w e n t y b y t e s f o r w a r d f r o m c u r r e n t , - 2 0 f r o m
e n d is 2 0 b y t e s b e f o r e t h e e n d o f t h e c u r r e n t file.
T o f i n d o u t t h e c u r r e n t file p o s i t i o n w i t h o u t a l t e r i n g it, y o u call t o S e e k
specifying an offset of zero from the current position.
T o m o v e to t h e e n d o f a file, S e e k to e n d - o f - f i l e o f f s e t w i t h z e r o p o s i t i o n .
N o t e t h a t y o u c a n a p p e n d i n f o r m a t i o n to a file b y m o v i n g t o t h e e n d o f a file
w i t h S e e k a n d t h e n w r i t i n g . Y o u c a n n o t S e e k b e y o n d t h e e n d o f a file.
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
AMIGADOS DEVELOPER'S MANUAL
180
Description:
UnLock
removes
a filing s y s t e m lock obtained f r o m L o c k ,
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:
process - process identifier
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 .
AMIGADOS DEVELOPER'S MANUAL
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:
process - process identifier
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
device associated with the specified n a m e . If DeviceProc c a n n o t find a process
h a n d l e r , t h e r e s u l t is z e r o . If " n a m e " r e f e r s t o a file o n a m o u n t e d d e v i c e , t h e n
IoErr() r e t u r n s a p o i n t e r to a d i r e c t o r y l o c k .
Y o u can u s e this function to determine the process identification of
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
run the program
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:
To execute a CLI command.
Form:
Success = Execute( commandString,
DO
Dl
c o m m a n d S t r i n g - string
i n p u t - file h a n d l e
o u t p u t - file h a n d l e
Success - boolean
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:
To load a load module into m e m o r y .
segment = LoadSeg( name )
Argument:
DO
n a m e - string
Dl
AMIGADOS DEVELOPER'S MANUAL
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:
To unload a segment previously loaded by L O A D S E G .
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.
" s e g m e n t " m a y be zero.
Quick Reference Card
File Handling
Close
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
The Macro Assembler
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
3.1 Introduction to the 68000 Microchip
T h i s s e c t i o n g i v e s a brief 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 . It s h o u l d h e l p
y o u to u n d e r s t a n d t h e c o n c e p t s i n t r o d u c e d later i n t h e c h a p t e r . It a s s u m e s t h a t
y o u have already h a d experience with assembly language on another computer.
T h e m e m o r y available to t h e 6 8 0 0 0 c o n s i s t s of
THE MACRO ASSEMBLER
187
• the internal registers (on the chip), and
• the external main m e m o r y .
T h e r e a r e 17 r e g i s t e r s , b u t o n l y 16 a r e a v a i l a b l e at a n y g i v e n m o m e n t . E i g h t
o f t h e m a r e d a t a r e g i s t e r s n a m e d DO t o D 7 , a n d t h e o t h e r s a r e a d d r e s s r e g i s t e r s
c a l l e d AO to A 7 . E a c h r e g i s t e r c o n t a i n s 3 2 b i t s . I n m a n y c o n t e x t s , y o u m a y u s e
either k i n d of register, b u t others d e m a n d a specific k i n d . For i n s t a n c e , y o u
m a y u s e a n y r e g i s t e r for o p e r a t i o n s o n w o r d (16-bit) a n d l o n g w o r d (32-bit)
quantities or for i n d e x e d addressing of m a i n m e m o r y . A l t h o u g h , for operations
o n b y t e (8-bit) o p e r a n d s , y o u m a y o n l y u s e d a t a r e g i s t e r s , a n d f o r a d d r e s s i n g
m a i n m e m o r y , y o u m a y only use address registers as stack pointers or b a s e
r e g i s t e r s . R e g i s t e r A 7 is t h e s t a c k p o i n t e r , a n d t h i s is i n fact t w o
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
AMIGADOS DEVELOPER'S MANUAL
3.2 Calling the Assembler
T h e c o m m a n d t e m p l a t e f o r a s s e m is
" P R O G = FROM/A,-0/K,-V/K,-L/K,-H/K,-C/K,-I/K"
Alternatively, the format of the c o m m a n d line can b e described as
assem <sourcefile>
[-o < o b j e c t f i l e > ]
[-1 < l i s t i n g f i l e > ]
[-v < v e r i f i c a t i o n f i l e > ]
[-h < h e a d e r f i l e > ]
[-c < o p t i o n s > ]
[-i < i n c l u d e d i r l i s t > ]
T h e a s s e m b l e r d o e s n o t p r o d u c e a n o b j e c t file or a listing file u n l e s s y o u
r e q u e s t t h e m explicitly.
A s t h e a s s e m b l e r is r u n n i n g , it g e n e r a t e s d i a g n o s t i c m e s s a g e s ( e r r o r s , w a r n i n g s , a n d a s s e m b l y statistics) a n d s e n d s t h e m to t h e s c r e e n u n l e s s y o u s p e c i f y
a v e r i f i c a t i o n file.
T o f o r c e t h e i n c l u s i o n o f t h e n a m e d file i n t h e a s s e m b l y a t t h e h e a d o f t h e
s o u r c e file, y o u u s e - h < f i l e n a m e > o n t h e c o m m a n d l i n e . T h i s h a s t h e s a m e
effect as using
INCLUDE " < f f l e n a r n e > "
o n l i n e 1 o f t h e s o u r c e file.
T o s e t u p t h e list o f d i r e c t o r i e s t h a t t h e a s s e m b l e r s h o u l d s e a r c h for a n y
I N C L U D E d f i l e s , y o u u s e t h e -i k e y w o r d . Y o u s h o u l d s p e c i f y as m a n y d i r e c t o r i e s a s y o u r e q u i r e a f t e r t h e - i , s e p a r a t i n g t h e d i r e c t o r y n a m e s b y a c o m m a (,), a
p l u s s i g n ( + ) , o r a s p a c e . N o t e t h a t if y o u u s e a s p a c e , y o u m u s t e n c l o s e t h e
e n t i r e d i r e c t o r y list in d o u b l e q u o t e s ( " ) . U n i x u s e r s , h o w e v e r , m u s t e s c a p e a n y
d o u b l e q u o t e s w i t h a b a c k s l a s h (\").
T h e o r d e r o f t h e list d e t e r m i n e s t h e o r d e r o f t h e d i r e c t o r i e s w h e r e
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 :
THE MACRO ASSEMBLER
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.
D
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.)
C
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 .
X
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 " .
3.3 Program Encoding
A p r o g r a m a c c e p t a b l e to t h e a s s e m b l e r t a k e s t h e f o r m o f a s e r i e s o f i n p u t l i n e s
that can include a n y of the following:
• C o m m e n t or B l a n k l i n e s
• Executable Instructions
• A s s e m b l e r Directives
AMIGADOS DEVELOPER'S MANUAL
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.
3.3.2 Executable Instructions
T h e s o u r c e s t a t e m e n t s h a v e t h e g e n e r a l overall f o r m a t :
[<label>] <opcode>
[<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
THE MACRO ASSEMBLER
191
they m a y stand alone o n a line. See the specifications of individual directives in
S e c t i o n 3 . 7 f o r w h e t h e r a l a b e l field is a l l o w e d .
Note: Y o u m u s t not give multiple definitions to labels. Also, y o u m u s t n o t
use instruction n a m e s , macro n a m e s , directives, or register n a m e s as labels.
3.3.2.2
Local
Labels
Local labels are provided as an extension to the Motorola
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 -
AMIGADOS DEVELOPER'S MANUAL
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
A n y t h i n g after t h e terminating s p a c e of t h e o p e r a n d field is i g n o r e d . S o t h e
assembler treats any characters y o u insert after a space as a c o m m e n t .
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 - )
To override t h e p r e c e d e n c e of t h e operators, enclose sub-expressions
in
p a r e n t h e s e s . T h e a s s e m b l e r evaluates operators of equal p r e c e d e n c e f r o m left
t o r i g h t . N o t e t h a t , n o r m a l l y , y o u s h o u l d n o t h a v e a n y s p a c e s in a n e x p r e s s i o n ,
as a s p a c e is r e g a r d e d a s a d e l i m i t e r b e t w e e n o n e field a n d a n o t h e r .
3.4.2 Operand Types for Operators
In the following table, " A " represents absolute symbols, a n d " R "
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
Unary minus and
operand.
of t h e resulting v a l u e ,
"x"
indicates
an
the Logical operators are only valid with
error.
an
The
absolute
THE MACRO ASSEMBLER
193
Operands
Operators
A op A
R op R
A op R
R op A
+
A
X
R
R
-
A
A
X
R
*
A
X
X
X
/
A
X
X
X
&
A
X
X
X
!
A
X
X
X
A
X
X
X
A
X
X
X
»
«
Table 3-A: Operand Types for Operators
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
treated as s y n o n y m s with their u p p e r case equivalents (unless y o u u s e the
o p t i o n C w h e n y o u i n v o k e t h e a s s e m b l e r ) . S o " f r e d " is d i f f e r e n t f r o m " F R E D "
a n d " F R e d " . H o w e v e r , the assembler recognizes instruction o p c o d e s , direct i v e s , a n d r e g i s t e r n a m e s in e i t h e r u p p e r or l o w e r c a s e . A l a b e l e q u a t e d t o a
r e g i s t e r n a m e w i t h E Q U R is a l s o r e c o g n i z e d b y t h e a s s e m b l e r in e i t h e r u p p e r
o r l o w e r c a s e . S y m b o l s c a n b e u p t o 3 0 c h a r a c t e r s i n l e n g t h , all o f w h i c h
are significant. T h e assembler takes symbols longer t h a n this a n d
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 .
AMIGADOS DEVELOPER'S MANUAL
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
THE MACRO ASSEMBLER
195
3.5 Addressing Modes
T h e effective address m o d e s define t h e operands to instructions a n d directives,
a n d y o u c a n f i n d a d e t a i l e d d e s c r i p t i o n of t h e m i n a n y g o o d r e f e r e n c e b o o k o n
t h e 6 8 0 0 0 . A d d r e s s e s r e f e r to i n d i v i d u a l b y t e s , b u t i n s t r u c t i o n s , w o r d
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 :
Table 3-B: Macro Assembler Address Modes and Registers
Address Mode
Description and Examples
Dn
Data Register Direct
Example:
An
Example:
(An)
M O V E D0,-(A7)
A d d r e s s Register Indirect with Displacement
Example:
a(An,Xn)
M O V E (A7) + , D 0
Address Register Indirect Pre D e c r e m e n t
Example:
a(An)
M O V E D0,(A1)
Address Register Indirect Post Increment
Example:
-(An)
MOVEA A0,A1
Address Register Indirect
Example:
(An) +
M O V E DO, D l
A d d r e s s Register Direct
M O V E 20(A0),D1
A d d r e s s Register Indirect with Index
Example:
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
a
S h o r t a b s o l u t e (16 bits)
Example:
a
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
Program Counter Relative with Displacement
Example:
MOVE ABQDO
( A B C is relative)
r(Xn)
Program C o u n t e r Relative with Index
Example:
MOVE ABC(D0.L),D1
( A B C is relative)
196
AMIGADOS DEVELOPER'S MANUAL
#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.6 Variants on Instruction Types
C e r t a i n i n s t r u c t i o n s (for e x a m p l e , A D D , C M P ) h a v e a n a d d r e s s v a r i a n t ( t h a t
refers to address registers as destinations), immediate and quick forms ( w h e n
i m m e d i a t e d a t a p o s s i b l y w i t h i n a r e s t r i c t e d size r a n g e a p p e a r s a s a n o p e r a n d ) ,
and a m e m o r y variant (where both operands must be a postincrement address).
T o f o r c e a p a r t i c u l a r v a r i a n t to b e u s e d , y o u m a y a p p e n d A , Q , I, or M t o t h e
instruction m n e m o n i c . In this c a s e , t h e assembler u s e s the specified form of
t h e i n s t r u c t i o n , if it e x i s t s , or g i v e s a n e r r o r m e s s a g e .
If, h o w e v e r , y o u s p e c i f y n o p a r t i c u l a r v a r i a n t , t h e a s s e m b l e r a u t o m a t i c a l l y
c o n v e r t s to t h e " I " , " A " , or " M " f o r m s w h e r e a p p r o p r i a t e . H o w e v e r , it d o e s
not convert to the " Q " form. For example, the assembler converts the following:
ADD.L A 2 , A l
to
ADDA.L A 2 , A l
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
THE MACRO ASSEMBLER
Table 3-C: Directives
Assembly
Control
Symbol
Data
Listing
Directive
Description
SECTION
Program section
RORG
Relocatable origin
OFFSET
Define offsets
END
Program end
Definition
Directive
Description
EQU
Assign permanent value
EQUR
Assign p e r m a n e n t register value
REG
Assign permanent value
SET
Assign temporary value
Definition
Directive
Description
DC
Define constants
DCB
Define Constant Block
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
Skip n blank lines
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
Disable object code output
n < =
= n <
FAIL
Generate an assembly error
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 >
0
100)
198
Macro
External
General
AMIGADOS DEVELOPER'S MANUAL
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 <
0
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
Define a macro name
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
Assembly Control Directives
SECTION
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
Indicates that the section contains initialized data (only).
BSS
indicates that the section contains uninitialized data.
This
is
the
199
THE MACRO ASSEMBLER
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
begins with an u n n a m e d C O D E section. T h e assembler assigns the optional
s y m b o l < l a b e l s > t o t h e v a l u e o f t h e p r o g r a m c o u n t e r a f t e r it h a s e x e c u t e d t h e
S E C T I O N d i r e c t i v e . I n a d d i t i o n , w h e r e a s e c t i o n is u n n a m e d , t h e s h o r t h a n d
f o r t h a t s e c t i o n is t h e k e y w o r d C O D E .
RORG
Set Relative Origin
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
appear. To terminate an O F F S E T section, y o u use a R O R G , O F F S E T ,
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
subsequent source statements. W h e n
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.
Symbol Definition Directives
EQU
Equate symbol value
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
AMIGADOS DEVELOPER'S MANUAL
EQUR
Equate register value
Format:
<label> EQUR
<register>
This directive lets y o u equate o n e of the processor registers w i t h a u s e r
s y m b o l . O n l y t h e A d d r e s s a n d D a t a r e g i s t e r s a r e v a l i d , s o s p e c i a l s y m b o l s like
S R , C C R , a n d U S P a r e illegal h e r e . T h e r e g i s t e r is p e r m a n e n t , s o y o u c a n n o t
define t h e label a n y w h e r e else in the program. T h e register m u s t n o t b e a
f o r w a r d r e f e r e n c e to a n o t h e r E Q U R s t a t e m e n t . T h e a s s e m b l e r m a t c h e s l a b e l s
d e f i n e d in t h i s w a y w i t h o u t d i s t i n g u i s h i n g b e t w e e n u p p e r a n d l o w e r c a s e .
REG
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
Set symbol value
Format:
< l a b e l > SET
<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 .
Data Definition Directives
DC
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
Define Constant Block
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 ,
THE MACRO ASSEMBLER
201
w o r d s , o r l o n g w o r d s to t h e v a l u e o f t h e e x p r e s s i o n < e x p > . D C B . < s i z e > n , e x p
is e q u i v a l e n t t o r e p e a t i n g n t i m e s t h e s t a t e m e n t D C . < s i z e > e x p .
DS
Define Storage
Format:
[<label>] DS[.<size>]
<absexp>
T o reserve m e m o r y locations, y o u u s e the D S directive. D S , h o w e v e r , does
n o initialization. T h e a m o u n t of space the a s s e m b l e r allocates d e p e n d s o n t h e
d a t a s i z e ( t h a t y o u g i v e w i t h 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 ) , a n d 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 . T h e a s s e m b l e r i n t e r p r e t s t h i s a s t h e
n u m b e r o f d a t a i t e m s o f t h a t s i z e to a l l o c a t e . A s w i t h D C , if t h e size s p e c i f i e r is
. W or .L, D S aligns the space onto a w o r d boundary. S o , D S . W 0 has the effect
o f a l i g n i n g t o a w o r d b o u n d a r y o n l y . If y o u d o n o t g i v e a s i z e s p e c i f i e r , D S
a s s u m e s a default of . W . S e e C N O P for a m o r e general w a y of
handling
alignment.
Listing Control Directives
PAGE
Format:
Page Throw
PAGE
Unless paging h a s b e e n inhibited, P A G E advances the assembly listing to
the top of the next page. T h e P A G E directive d o e s not a p p e a r o n the o u t p u t
listing.
LIST
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
Space Blank Lines
Format:
SPC
<number>
T h e S P C directive outputs t h e n u m b e r of blank lines given b y the o p e r a n d
field, to the a s s e m b l y listing. T h e
p r o g r a m listing.
S P C directive d o e s not a p p e a r o n
the
AMIGADOS DEVELOPER'S MANUAL
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
Set Line Length
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
Set Page Length
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
Disable Object C o d e Generation
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
THE MACRO ASSEMBLER
NOFORMAT
N o action
Format:
NOFORMAT
T h e a s s e m b l e r accepts this directive b u t takes n o action o n receiving
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 Assembly Directives
CNOP
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
a
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
AMIGADOS DEVELOPER'S MANUAL
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
< symbol n a m e >
IFND
< symbol n a m e >
D e p e n d i n g o n w h e t h e r or not you have already defined the symbol,
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
Start a macro definition
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 \
( b a c k s l a s h ) h a s a special m e a n i n g . B a c k s l a s h f o l l o w e d b y a n u m b e r " n " i n d i c a t e s
t h a t t h e v a l u e o f t h e n t h a r g u m e n t is to b e i n s e r t e d i n t o t h e c o d e . If t h e n t h
a r g u m e n t is o m i t t e d t h e n n o t h i n g is i n s e r t e d . B a c k s l a s h f o l l o w e d b y t h e s y m b o l "(a " t e l l s t h e a s s e m b l e r t o g e n e r a t e t h e t e x t " . n n n " , w h e r e n n n is t h e n u m b e r
o f t i m e s t h e \(a
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
THE MACRO ASSEMBLER
is a limit t o t h e l e v e l o f n e s t i n g o f m a c r o calls. T h i s limit is c u r r e n t l y
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
Terminate a macro definition
Format:
ENDM
This terminates a macro definition introduced by a M A C R O directive.
MEXIT
Exit f r o m m a c r o e x p a n s i o n
Format:
MEXIT
Y o u u s e this directive to exit f r o m m a c r o e x p a n s i o n m o d e , u s u a l l y i n conduction
w i t h t h e I F E Q a n d I F N E d i r e c t i v e s . It a l l o w s c o n d i t i o n a l e x p a n s i o n o f m a c r o s .
O n c e it h a s e x e c u t e d t h e d i r e c t i v e , t h e a s s e m b l e r s t o p s e x p a n d i n g t h e c u r r e n t
m a c r o as t h o u g h there w e r e no m o r e stored text to include.
External Symbols
XDEF
Define an internal label as an external entry
point
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
satisfy the references w i t h a linker.
If y o u
can
high-
use
this
directive or X R E F , t h e n y o u c a n n o t directly execute the c o d e p r o d u c e d b y the
assembler.
XREF
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
follow the X R E F directive.
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
AMIGADOS DEVELOPER'S MANUAL
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
"<file n a m e > "
T h e I N C L U D E d i r e c t i v e a l l o w s t h e i n c l u s i o n o f e x t e r n a l files i n t o t h e p r o g r a m s o u r c e . Y o u set u p t h e file t h a t I N C L U D E i n s e r t s w i t h t h e s t r i n g d e s c r i p t o r in t h e o p e r a n d f i e l d . Y o u c a n n e s t I N C L U D E d i r e c t i v e s u p t o a d e p t h o f
t h r e e , e n c l o s i n g t h e f i l e n a m e s in q u o t e s as s h o w n . I N C L U D E is e s p e c i a l l y
u s e f u l w h e n y o u r e q u i r e a s t a n d a r d s e t o f m a c r o d e f i n i t i o n s or E Q U s i n s e v e r a l
programs.
Y o u c a n p l a c e t h e d e f i n i t i o n s in a s i n g l e file a n d t h e n r e f e r to t h e m f r o m
other programs with a suitable I N C L U D E .
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
This chapter describes the A m i g a D O S Linker. The A m i g a D O S Linker produces
a s i n g l e b i n a r y l o a d file f r o m o n e or m o r e i n p u t files. It c a n also p r o d u c e
overlaid programs.
4.1
Introduction
4.2
Using the Linker
4.2.1
C o m m a n d Line Syntax
4.2.2
W I T H Files
4.2.3
Errors and Other Exceptions
4.2.4
M A P and XREF Output
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
AMIGADOS DEVELOPER'S MANUAL
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
4.2 Using the Linker
To u s e the linker, y o u must k n o w the c o m m a n d syntax, the type of input a n d
output that the linker uses, a n d the possible errors that m a y occur. This section
attempts to explain these things.
4.2.1 Command Line Syntax
T h e A L I N K c o m m a n d has the following parameters:
A L I N K [ F R O M | R O O T ] files [ T O file] [ W I T H file]
[ V E R file] [ L I B R A R Y | L I B files] [ M A P file]
[ X R E F file] [ W I D T H n ]
T h e k e y w o r d t e m p l a t e is
" 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"
I n t h e a b o v e , " f i l e " m e a n s a s i n g l e file n a m e , " f i l e s " m e a n s z e r o o r m o r e file
n a m e s , s e p a r a t e d b y a c o m m a o r p l u s s i g n , a n d " n " is a n i n t e g e r .
T h e f o l l o w i n g a r e e x a m p l e s o f valid u s e s o f t h e A L I N K c o m m a n d :
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:
S p e c i f i e s files c o n t a i n i n g t h e l i n k e r p a r a m e t e r s , for e x a m p l e , n o r m a l c o m m a n d l i n e s . U s u a l l y y o u o n l y u s e o n e file h e r e , b u t , f o r
c o m p l e t e n e s s , y o u c a n g i v e a list o f files. N o t e t h a t p a r a m e t e r s o n
t h e c o m m a n d line o v e r r i d e t h o s e i n W I T H files. Y o u c a n f i n d a full
description of t h e s y n t a x of t h e s e files in S e c t i o n 4 . 2 . 2 o f this m a n u a l .
210
AMIGADOS DEVELOPER'S MANUAL
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:
specifies the output width that the linker can u s e w h e n producing
t h e l i n k 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 . F o r e x a m p l e , if y o u s e n d
o u t p u t to a p r i n t e r , y o u m a y n e e d t h i s p a r a m e t e r .
4.2.2 WITH Files
W I T H files c o n t a i n p a r a m e t e r s for t h e l i n k e r . Y o u u s e t h e m t o s a v e t y p i n g a
l o n g a n d c o m p l e x A L I N K c o m m a n d line m a n y t i m e s .
A W I T H file c o n s i s t s o f a s e r i e s o f p a r a m e t e r s , o n e p e r l i n e , e a c h c o n s i s t i n g
o f a k e y w o r d f o l l o w e d b y d a t a . Y o u c a n t e r m i n a t e l i n e s w i t h a s e m i c o l o n (;),
w h e r e t h e linker ignores the rest of the line. Y o u can t h e n u s e t h e rest of t h e
l i n e a f t e r t h e s e m i c o l o n to i n c l u d e a c o m m e n t . T h e l i n k e r i g n o r e s b l a n k l i n e s .
T h e k e y w o r d s available are as follows:
F R O M (or R O O T ) files
TO
file
LIBRARY
files
MAP
[file]
XREF
[file]
OVERLAY
tree specification
#
WIDTH
n
w h e r e " f i l e " is a s i n g l e f i l e n a m e , " f i l e s " is o n e or m o r e f i l e n a m e s , " [ f i l e ] " is a n
o p t i o n a l f i l e n a m e , a n d " n " is a n i n t e g e r . Y o u m a y u s e a n a s t e r i s k s y m b o l (*) to
split l o n g l i n e s ; p l a c i n g o n e at t h e e n d o f a l i n e tells t h e p r i n t e r t o r e a d t h e n e x t
l i n e a s a c o n t i n u a t i o n l i n e . If t h e f i l e n a m e after M A P or X R E F is o m i t t e d , t h e
o u t p u t g o e s t o t h e V E R file ( t h e t e r m i n a l b y d e f a u l t ) .
P a r a m e t e r s o n t h e c o m m a n d l i n e o v e r r i d e t h o s e in a W I T H file, s o t h a t y o u
can make
small variations o n standard links b y c o m b i n i n g c o m m a n d
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.
4.2.3 Errors and Other Exceptions
V a r i o u s e r r o r s c a n o c c u r w h i l e t h e l i n k e r is r u n n i n g . M o s t o f t h e m e s s a g e s
are
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
AMIGADOS DEVELOPER'S MANUAL
o n e s refer to undefined or multiply-defined symbols. T h e linker should not
terminate after receiving a warning.
If a n y u n d e f i n e d s y m b o l s r e m a i n at t h e e n d o f t h e first p a s s , t h e l i n k e r
p r o d u c e s a w a r n i n g , a n d outputs a table of such s y m b o l s . D u r i n g the s e c o n d
p a s s , r e f e r e n c e s t o t h e s e s y m b o l s b e c o m e r e f e r e n c e s to l o c a t i o n z e r o .
If t h e l i n k e r f i n d s m o r e t h a n o n e d e f i n i t i o n o f a s y m b o l d u r i n g t h e first p a s s ,
it p u t s o u t a w a r n i n g , a n d i g n o r e s t h e l a t e r d e f i n i t i o n . T h e l i n k e r d o e s n o t
p r o d u c e t h i s m e s s a g e if t h e s e c o n d d e f i n i t i o n o c c u r s i n a library file, s o t h a t
y o u c a n r e p l a c e library r o u t i n e s w i t h o u t it p r o d u c i n g s p u r i o u s m e s s a g e s .
s e r i o u s e r r o r f o l l o w s if t h e l i n k e r f i n d s i n c o n s i s t e n t s y m b o l r e f e r e n c e s ,
A
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 .
4.2.4 MAP and XREF Output
T h e l i n k m a p , w h i c h t h e l i n k e r p r o d u c e s a f t e r t h e first p a s s , lists all t h e c o d e
s e g m e n t s t h a t t h e l i n k e r o u t p u t to t h e l o a d file in t h e s e c o n d p a s s , in t h e o r d e r
that they m u s t be written.
For each code s e g m e n t , the linker outputs a header, starting with the n a m e
o f t h e file ( t r u n c a t e d to e i g h t l e t t e r s ) , t h e c o d e s e g m e n t r e f e r e n c e n u m b e r , t h e
t y p e ( t h a t i s , d a t a , c o d e , b s s , or C O M M O N ) , a n d s i z e . If t h e c o d e s e g m e n t w a s
in a n o v e r l a y file, t h e l i n k e r a l s o g i v e s t h e o v e r l a y l e v e l a n d o v e r l a y o r d i n a t e .
After the header, the linker prints each symbol defined in the code s e g m e n t ,
t o g e t h e r w i t h its v a l u e . It p r i n t s t h e s y m b o l s i n a s c e n d i n g o r d e r o f t h e i r v a l u e s ,
a p p e n d i n g a n a s t e r i s k (*) to a b s o l u t e v a l u e s .
T h e v a l u e of t h e W I D T H p a r a m e t e r d e t e r m i n e s t h e n u m b e r of s y m b o l s p r i n t e d
p e r l i n e . If t h i s is t o o s m a l l , t h e n t h e l i n k e r p r i n t s o n e s y m b o l o n e a c h l i n e .
The cross-reference
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
alterations to the program structure.
W h e n using overlaying, you should consider the program as a tree structure.
That is, with t h e root of the tree as the primary binary input, t o g e t h e r w i t h
l i b r a r y c o d e s e g m e n t s a n d C O M M O N b l o c k s . T h i s r o o t is a l w a y s r e s i d e n t i n
m e m o r y . T h e o v e r l a y files t h e n f o r m t h e o t h e r n o d e s o f t h e t r e e , a c c o r d i n g to
s p e c i f i c a t i o n s in t h e O V E R L A Y d i r e c t i v e .
T h e o u t p u t f r o m t h e l i n k e r w h e n o v e r l a y i n g , a s i n t h e u s u a l c a s e , is a s i n g l e
b i n a r y file, w h i c h c o n s i s t s o f all t h e c o d e s e g m e n t s , t o g e t h e r w i t h i n f o r m a t i o n
g i v i n g t h e l o c a t i o n w i t h i n t h e file o f e a c h n o d e o f t h e o v e r l a y t r e e . W h e n y o u
l o a d t h e p r o g r a m o n l y t h e r o o t is b r o u g h t i n t o m e m o r y . A n o v e r l a y s u p e r v i s o r
takes care of loading a n d unloading the overlay s e g m e n t s automatically. T h e
linker includes
this
overlay
a link using overlays. T h e
supervisor in the output
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.
4.3.1 OVERLAY Directive
T o specify the tree structure of a p r o g r a m to the linker, y o u u s e t h e O V E R L A Y
d i r e c t i v e . T h i s d i r e c t i v e is e x c e p t i o n a l i n t h a t y o u c a n o n l y u s e it i n W I T H f i l e s .
A s w i t h o t h e r p a r a m e t e r s , t h e l i n k e r u s e s t h e first O V E R L A Y d i r e c t i v e y o u
g i v e it.
T h e f o r m a t o f t h e d i r e c t i v e is
OVERLAY
Xfiles
#
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 .
AMIGADOS DEVELOPER'S MANUAL
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
1
b
1
c
1
a b c
#
ROOT
OVERLAY
a
1
b
1
*c
2
*d
2
a
b
c d
#
ROOT
OVERLAY
1
1
b
1
2
*c
2
1
*d
2
2
e
1
3
f
1
4
*g
*h
**i
2
1
2
2
**j
3
1
3
2
2
3
1
5
a
*k
1
ab
c d
e f 1
ghk
A
#
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
overlay level a n d ordinate the linker prints with each code s e g m e n t .
4.3.2 References to Symbols
While linking an overlaid program, the linker checks each symbol reference
for validity.
AMIGADOS DEVELOPER'S MANUAL
216
S u p p o s e that t h e r e f e r e n c e is in a tree n o d e " R " , a n d t h e s y m b o l in a n o d e " S " .
T h e n t h e r e f e r e n c e is legal if o n e of t h e f o l l o w i n g is t r u e .
(a) R a n d S a r e t h e s a m e n o d e .
(b) R is a d e s c e n d e n t of S .
(c) R is t h e p a r e n t of S.
R e f e r e n c e s o f t h e third t y p e a b o v e a r e k n o w n a s o v e r l a y r e f e r e n c e s . I n t h i s
c a s e , t h e l i n k e r e n t e r s t h e o v e r l a y s u p e r v i s o r w h e n t h e p r o g r a m is r u n . T h e
o v e r l a y s u p e r v i s o r t h e n c h e c k s t o s e e if t h e c o d e s e g m e n t c o n t a i n i n g t h e
s y m b o l is a l r e a d y in m e m o r y . If n o t , first t h e c o d e s e g m e n t , if a n y , at t h i s
l e v e l , a n d all its d e s c e n d e n t s a r e u n l o a d e d , a n d t h e n t h e n o d e c o n t a i n i n g t h e
s y m b o l is b r o u g h t i n t o m e m o r y . A n o v e r l a i d c o d e s e g m e n t r e t u r n s directly t o
its caller, a n d s o is n o t u n l o a d e d f r o m m e m o r y u n t i l a n o t h e r n o d e is l o a d e d o n
t o p of it.
F o r e x a m p l e , s u p p o s e t h a t t h e tree is:
A
A
/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 .
4.3.3 Cautionary Points
T h e l i n k e r a s s u m e s t h a t all o v e r l a y r e f e r e n c e s a r e j u m p s o r s u b r o u t i n e calls,
a n d routes t h e m through the overlay supervisor. T h u s , you should not use
o v e r l a y s y m b o l s a s data l a b e l s .
Try to avoid impure code w h e n overlaying because the linker does
a l w a y s l o a d a n o d e t h a t is f r e s h f r o m t h e l o a d file.
not
THE LINKER
T h e linker gives each symbol that has an overlay reference
n u m b e r . It u s e s t h i s v a l u e , w h i c h is z e r o or m o r e , to c o n s t r u c t
s u p e r v i s o r e n t r y label a s s o c i a t e d w i t h t h a t s y m b o l . T h i s l a b e l is
" O V L Y n n n n " , w h e r e n n n n is t h e o v e r l a y n u m b e r . Y o u s h o u l d n o t
with this format elsewhere.
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 .
4.4 Error Codes and Messages
T h e s e e r r o r s s h o u l d b e r a r e . If t h e y d o o c c u r , t h e e r r o r is p r o b a b l y in t h e
c o m p i l e r a n d n o t in y o u r p r o g r a m . H o w e v e r , y o u s h o u l d first c h e c k to s e e
t h a t y o u s e n t t h e l i n k e r a p r o p e r p r o g r a m (for e x a m p l e , a n i n p u t p r o g r a m
m u s t h a v e a n i n t r o d u c t o r y p r o g r a m u n i t t h a t tells t h e l i n k e r t o e x p e c t a
program).
Invalid Object Modules
2
Invalid use of overlay symbol
3
I n v a l i d u s e of s y m b o l
4
I n v a l i d u s e of c o m m o n
5
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
6
Nonzero overlay reference
7
Invalid external block relocation
8
Invalid bss relocation
9
Invalid program unit relocation
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
Invalid argument freevector
22
S y m b o l n o t defined in second pass
Appendix
Console Input and Output
on the Amiga
N o t e : T h r o u g h o u t this a p p e n d i x , t h e c h a r a c t e r s " < C S I > " r e p r e s e n t t h e C o n trol S e q u e n c e I n t r o d u c e r . F o r o u t p u t , y o u m a y e i t h e r u s e t h e t w o c h a r a c t e r
s e q u e n c e E s c - [ or t h e o n e b y t e v a l u e $ 9 B ( h e x ) . F o r i n p u t , y o u r e c e i v e $ 9 B s .
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:
Is j u s t like " * " e x c e p t that y o u also g e t to d e f i n e a n e w w i n d o w .
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
APPENDIX: CONSOLE INPUT AND OUTPUT O N THE AMIGA
219
press and release information or data on m o u s e events.
See
" S e l e c t i o n of R A W I n p u t E v e n t s " o n page 2 2 4 for details o n
requesting this information.
console.device: With
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
device. Y o u m a y change the K e y M a p to o n e of y o u r
own
design and completely " r e d e s i g n " your keyboard.
Helpful AmigaDOS Commands
T w o v e r y h e l p f u l A m i g a D O S c o m m a n d s let y o u p l a y w i t h t h e s e f u n c t i o n s . T h e
first:
TYPE RAW: 10/10/100/30/ opt h
a c c e p t s i n p u t f r o m a R A W : w i n d o w a n d d i s p l a y s t h e r e s u l t s in h e x a n d A S C I I .
I f y o u w a n t to k n o w f o r s u r e w h a t c h a r a c t e r s t h e k e y b o a r d is s e n d i n g , t h i s
c o m m a n d provides a very simple way.
The second:
COPY "RAW: 10/10/100/30/RAW Input" "RAW: 100/I0/200/100/RAW Output"
lets y o u type s e q u e n c e s into the input w i n d o w a n d w a t c h the cursor m o v e m e n t s in the output w i n d o w . C O P Y cannot detect end-of-file o n R A W : input,
so y o u have to reboot w h e n y o u are finished with this c o m m a n d .
CON Keyboard Input
If y o u r e a d f r o m t h e C O N : d e v i c e , t h e k e y b o a r d i n p u t s are p r e p r o c e s s e d for y o u .
Y o u g e t t h e A S C I I c h a r a c t e r s like " B " . M o s t n o r m a l t e x t g a t h e r i n g p r o g r a m s
r e a d f r o m t h e C O N : device. Special p r o g r a m s like w o r d processors a n d m u s i c
keyboard programs use RAW:.
T o generate the international a n d special characters at the k e y b o a r d , y o u can
press either A L T key. This sets the high bit of the A S C I I code r e t u r n e d for the
key pressed.
G e n e r a t i n g $ F F ( u m l a u t y ) is a s p e c i a l c a s e . If it f o l l o w e d t h e s t a n d a r d
c o n v e n t i o n , it w o u l d b e g e n e r a t e d b y A L T - D E L . B u t s i n c e t h e A S C I I c o d e
< D e l > ( h e x 7 F ) is n o t g e n e r a l l y a p r i n t a b l e c h a r a c t e r a n d it is o u r p h i l o s o p h y
that Alt-nonprinting character should not generate a printing character, w e
have substituted ALT-numeric p a d " - " .
T a b l e A - l lists t h e c h a r a c t e r s y o u c a n d i s p l a y o n t h e A m i g a . T h e c h a r a c t e r s
N B S P ( n o n b r e a k space) a n d S H Y (soft h y p h e n ) are u s e d to r e n d e r a s p a c e a n d
h y p h e n in t e x t p r o c e s s i n g w i t h a d d i t i o n a l m e a n i n g a b o u t t h e p r o p e r t i e s o f t h e
character.
AMIGADOS DEVELOPER'S MANUAL
220
0
0
0
0
0
1
b(,
0
0
1
0
„
0
tiK
t
b?
00 01
bl
0 0 0 0 00
0 0 1 0 02
1
0
1
1
a
P
•
q
II
2
B
R
b
r
%
c
1
7
G
w
g
w
08
(
H
X
h
X
*
11
+
1
0
1
1
1 1 0 0 12
8
9
I
y
©
E
•
£
E
E
K
C
k
{
<
L
\
I
1
«»
:
m
>
SHY
n
mm
13
-
=
M
1
1
1
0
14
•
>
N
/
i
15
i
1
z
1
1
6
E
t
J
0
1
EE
? o ?
•
Z
1
1
Y
§
J
•
1
1
6
b'
07
0
-
®
0
^
0
§
k
1
n
0
6
1
b
#
a
S
1
1.5
a
a
a
1
A" 0
u
r
1
a
e
1
1
0
0
A
U
0
1 0 1 0 10
t
E
V
)
0
5
f
•.WW.*
N
t
V
09
3
A
€>
d
F
1
A
T
6
0
1
D
&
0
o
£
0
1
1
12 13 14
+ A
i
:
06
1
NBSP
0
0
1
s
0
0
p
1
1
1
1
1
0
1
c
1
0
1
0
1
S
3
1
0
0
0
1
2
0
1
1
1
1
0
0
0
P
a
0 1 0 1 05
0
0
1
1
3
Q
4
0
t
3
1
A
$
1
1
0
0
0
1
04
0
1
n
1
#
0
1
0
03
0
r1
02 0 3 0 4 0 5 06 0 7 08 09 1 0 11
SP
0 0 0 1 01
0
1
0
•
'
0
«
u*
u
0
I
u
*
Y
U
§
u
e
u
u
*
\
I
I
i
M
M
I
1
?
l
i
*
y
y
Table A-l: International Character Code
N o t e : A m i g a D O S u s e s C O N : i n p u t for t h e C L I a n d m o s t o t h e r c o m m a n d s .
W h e n it d o e s t h i s , it filters o u t A L L of t h e f u n c t i o n k e y a n d c u r s o r k e y i n p u t s .
P r o g r a m s t h a t r u n u n d e r A m i g a D O S c a n ( a n d s o m e d o ) still o p e n t h e R A W :
console handler and process function key input.
N o t e : " N B S P " is a n o n b r e a k s e q u e n c e .
" S H Y " is a s o f t - h y p h e n .
APPENDIX: CONSOLE INPUT AND OUTPUT ON THE AMIGA
221
CON Screen Output
C O N : s c r e e n o u t p u t is j u s t like R A W : s c r e e n o u t p u t e x c e p t t h a t < L F > ( h e x OA)
is t r a n s l a t e d i n t o a n e w l i n e c h a r a c t e r . T h e n e t e f f e c t is t h a t t h e c u r s o r m o v e s t o
t h e first c o l u m n o f t h e n e x t l i n e w h e n e v e r a < L F > is d i s p l a y e d .
RAW Screen Output
A N S I X 3 . 6 4 C O D E S S U P P O R T E D F o r w r i t i n g t e x t to t h e d i s p l a y :
Independent Control Functions (no introducer):
Ctrl
Hex
Name
Definition
H
08
BS
BACKSPACE
M o v e t h e c u r s o r left
I
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
Clear the screen
CARRIAGE RETURN
M o v e to first c o l u m n
N
0E
SO
SHIFT OUT
Set M S B of each
character before
displaying
O
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
c
RIS
RESET TO INITIAL STATE
Precede the following characters with < E s c >
l e t t e r 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 .
Hex
845tD
85
8D
9B
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
C o n t r o l s e q u e n c e s ( i n t r o d u c e d b y < C S I > ) w i t h p a r a m e t e r s . T h e first c h a r a c t e r in t h e f o l l o w i n g table ( u n d e r t h e < C S I > c o l u m n ) r e p r e s e n t s t h e n u m b e r o f
a l l o w a b l e p a r a m e t e r s , as f o l l o w s :
222
"0"
"1"
"2"
"3"
"4"
"8"
AMIGADOS DEVELOPER'S MANUAL
indicates
indicates
indicates
indicates
indicates
indicates
< C S I > Name
ICH
1 @
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.
APPENDIX: CONSOLE INPUT AND OUTPUT O N THE AMIGA
223
T h e following are not A N S I standard sequences; rather, t h e y are private
Amiga sequences.
1 t
aSLPP SET PAGE LENGTH
1 u
aSLL SET LINE LENGTH
1 X
aSLO SET LEFT OFFSET
i y
3 {
aSTO SET TOP OFFSET
I
aSRE SET R A W EVENTS
a l E R I N P U T E V E N T R E P O R T (read)
8
3 }
1 '
aRRE RESET R A W EVENTS
IP
aSCR SET CURSOR RENDITION
Oq
aWSR WINDOW STATUS REQUEST
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 the screen:
< F F > or C T R L - L
{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
{ h o m e and insert 23 lines}
224
AMIGADOS DEVELOPER'S MANUAL
RAW Keyboard Input
Reading input from the R A W : console device returns an A N S I
X3.64
standard byte stream. This stream may contain normal characters and/or R A W
input event information. Y o u m a y also request other R A W input events
using the SET R A W E V E N T S (aSRE) and RESET R A W E V E N T S (aRRE) control s e q u e n c e s d i s c u s s e d b e l o w . S e e " S e l e c t i o n of R A W I n p u t E v e n t s " b e l o w
for details.
If y o u i s s u e a R A W i n p u t r e q u e s t a n d t h e r e is n o p e n d i n g i n p u t , t h e r e a d
c o m m a n d w a i t s u n t i l s o m e i n p u t is r e c e i v e d . Y o u c a n test f o r c h a r a c t e r s
pending by doing "WaitforChar" requests.
In the default state, the function and arrow keys cause the following seq u e n c e s to b e s e n t to y o u r p r o c e s s :
Key
Fl
F2
F3
F4
F5
F6
F7
F8
F9
F10
HELP
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)
Selection of RAW Input Events:
If y o u a r e u s i n g R A W b y d e f a u l t , y o u g e t t h e A N S I d a t a a n d c o n t r o l
s e q u e n c e s m e n t i o n e d a b o v e . If t h i s d o e s n o t give y o u e n o u g h i n f o r m a t i o n
about input events, y o u can request additional information from the console
driver.
If, for e x a m p l e , y o u n e e d to k n o w w h e n e a c h k e y is p r e s s e d a n d r e l e a s e d ,
y o u w o u l d r e q u e s t " R A W k e y b o a r d i n p u t . " T h i s is d o n e b y w r i t i n g " < C S I > 1 { "
t o t h e c o n s o l e . T h e f o l l o w i n g is a list of valid R A W i n p u t r e q u e s t s :
APPENDIX: CONSOLE INPUT AND OUTPUT ON THE AMIGA
225
RAW Input Event Types
Request
Number
Description
0
nop
1
R A W keyboard input
2
R A W mouse input
3
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.
4
Pointer position
5
(unused)
6
Timer
7
Gadget pressed
8
Gadget released
9
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
events in the following form:
<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
Table A-2). This field can also b e u s e d for m o u s e information.
T h e < q u a l i f i e r s > field i n d i c a t e s t h e s t a t e o f t h e k e y b o a r d a n d s y s t e m . T h e
q u a l i f i e r s a r e d e f i n e d as f o l l o w s :
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
Not currently used
T h i s (active) or all w i n d o w s
Indicates m o u s e coordinates are
relative, not absolute
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"
selected keys no longer return a simple
1
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
APPENDIX: CONSOLE INPUT AND OUTPUT ON THE AMIGA
T h e " 0 ; 0 ; " fields a r e n o t u s e d f o r k e y b o a r d i n p u t b u t a r e , r a t h e r , u s e d if
y o u s e l e c t m o u s e i n p u t . F o r m o u s e i n p u t , t h e s e fields w o u l d i n d i c a t e t h e X a n d
Y coordinates of t h e m o u s e .
T h e < k e y c o d e > field is a n A S C I I d e c i m a l v a l u e r e p r e s e n t i n g t h e k e y p r e s s e d
o r r e l e a s e d . A d d i n g 128 t o t h e p r e s s e d k e y c o d e r e s u l t s in t h e r e l e a s e d k e y c o d e .
F i g u r e A - l lets y o u c o n v e r t q u i c k l y f r o m a k e y to its k e y c o d e . T a b l e A - 2 l e t s
y o u convert quickly from a keycode to a key.
isc
45
bo
F1
F3
50
?
01
T*|
0
42
CTHL
63
10
CAtt
LOCK
A
F«
F3
51
0 2W
52
i
03 0 4
E
11
S
K
»
It
12
13
O
F
62
54
05
1
06
T
i
34
t
J
40
58
59
DEL
46
SACK
SPACE
7
OC 0D
41
P
HELP
i
!
1 9 1/1 1 B 4 4 5 F
18
0B
IF) I T UA N
L
27
26
36
OA
0 90
K
ft
35
i
9
17
16
57
56
'08
07
V
•
V
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
9
3E
30
4
3F
S
4C
M
2E
a
1D I E
2F
2D
1
%
3
1F
0
37
38
39
3A
A.
67
61
65
4F
«
4E
OF
3C
INTiFl
4D
Figure A-l: Reduced copy of keyboard template
4A
43
228
AMIGADOS DEVELOPER'S MANUAL
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
1
!
02
2
@
03
3
#
04
4
$
05
5
%
06
6
07
7
&
08
8
*
09
9
(
OA
0
)
0B
- <Hyphen>
<Underscore>
0C
+
0D
\
0E
undefined
|
OF
0
0 <Numeric pad>
10
Q
q
11
W
w
12
E
e
13
R
r
14
T
t
15
Y
y
16
17
U
I
u
i
18
O
o
19
P
p
1A
{
[
IB
}
]
1C
undefined
ID
1
1 <Numeric pad>
IE
2
2 <Numeric pad>
IF
3
3 <Numeric pad>
APPENDIX: CONSOLE INPUT AND OUTPUT ON THE AMIGA
Raw
Unshifted
Shifted
Key
Default
Default
Number
Value
Value
20
A
a
21
S
s
22
D
d
23
F
f
24
G
25
H
g
h
26
27
J
K
j
k
28
L
1
29
2A
' < single quote >
2B
2C
<RESERVED>
undefined
(RESERVED)
2D
4
4 <Numeric pad>
2E
5
5 <Numeric pad>
2F
6
6 <Numeric pad>
30
<RESERVED>
(RESERVED)
31
Z
z
32
X
33
c
34
c
V
V
35
B
b
36
N
n
37
M
m
38
<
, <comma>
3A
?
/
39
>
x
. < period >
3B
undefined
3C
3D
7
3E
8
8 <Numeric pad>
3F
9
9 <Numeric pad>
. <Numeric pad>
40
Space
41
BACKSPACE
42
TAB
43
ENTER
44
RETURN
45
Escape
46
DEL
7 <Numeric pad>
ENTER <Numeric p a d >
<Esc>
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
" A m i g a " < r i g h t of s p a c e b a r >
68
Left M o u s e Button
< n o t converted>
Inputs are only
for the
69
Right Mouse Button
< n o t converted>
mouse connected
to Intuition,
APPENDIX: CONSOLE INPUT AND OUTPUT ON THE AMIGA
Raw
Unshifted
Shifted
Key
Default
Default
Number
Value
Value
6A
Middle Mouse Button
< n o t converted>
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
above keys. 80 for 00, F8 for 7F.
F9
Last keycode w a s bad (was sent in order to resync)
FA
Keyboard buffer overflow.
FB
undefined; reserved for keyboard processor catastrophe
FC
K e y b o a r d self-test failed.
FD
P o w e r - u p key stream start. K e y s p r e s s e d or stuck at
power-up are sent b e t w e e n F D a n d F E .
FE
Power-up key stream end.
FF
(undefined, reserved)
FF
M o u s e event, movement only, N o button change.
converted>
<not
Notes about the preceding table:
1) " u n d e f i n e d " i n d i c a t e s t h a t t h e c u r r e n t k e y b o a r d d e s i g n s h o u l d n o t g e n e r a t e t h i s n u m b e r . If y o u a r e u s i n g " S e t K e y M a p " t o c h a n g e t h e k e y m a p , t h e
e n t r i e s f o r t h e s e n u m b e r s m u s t still b e i n c l u d e d .
2) T h e " < n o t c o n v e r t e d > " r e f e r s t o m o u s e b u t t o n e v e n t s . Y o u m u s t u s e t h e
s e q u e n c e " < C S I > 2 { " to inform the console driver that y o u w i s h to receive
m o u s e events; otherwise, these are not transmitted.
3) " ( R E S E R V E D ) " i n d i c a t e s t h a t t h e s e k e y c o d e s h a v e b e e n r e s e r v e d f o r n o n - U . S .
k e y b o a r d s . T h e " 2 B " c o d e k e y is b e t w e e n t h e d o u b l e q u o t e a n d r e t u r n k e y s .
T h e " 3 0 " c o d e k e y is b e t w e e n t h e S H I F T a n d " Z " k e y s .
AmigaDOS Technical
Reference Manual
Contents
1. Filing System
2. Amiga Binary File Structure
3. AmigaDOS Data Structures
Chapter 1
The Filing System
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 filing s y s t e m . It i n c l u d e s i n f o r m a t i o n o n
h o w to patch a disk corrupted b y hardware errors.
1.1
1.1.1
1.1.2
1.1.3
1.1.4
1.1.5
1.2
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
1.1 AmigaDOS File Structure
T h e A m i g a D O S file h a n d l e r u s e s a d i s k t h a t is f o r m a t t e d w i t h b l o c k s o f e q u a l
s i z e . It p r o v i d e s a n i n d e f i n i t e l y d e e p h i e r a r c h y of d i r e c t o r i e s , w h e r e e a c h
d i r e c t o r y m a y c o n t a i n o t h e r d i r e c t o r i e s a n d files, o r j u s t files. T h e s t r u c t u r e is a
pure tree—that is, loops are not allowed.
T h e r e is sufficient r e d u n d a n c y i n t h e m e c h a n i s m to a l l o w y o u t o p a t c h
t o g e t h e r m o s t , if n o t all, o f t h e c o n t e n t s of a d i s k a f t e r a s e r i o u s h a r d w a r e
e r r o r , for e x a m p l e . T o p a t c h t h e c o n t e n t s of a d i s k , y o u u s e t h e D I S K E D
c o m m a n d . F o r f u r t h e r d e t a i l s o n t h e s y n t a x of D I S K E D , s e e S e c t i o n 1 . 2 ,
" D I S K E D — T h e D i s k E d i t o r , " later in t h i s c h a p t e r . B e f o r e y o u c a n p a t c h t o gether the contents of a disk, y o u m u s t understand the layout. T h e subsections
b e l o w d e s c r i b e t h e l a y o u t of d i s k p a g e s .
1.1.1 Root Block
T h e r o o t of t h e tree is t h e R o o t B l o c k , w h i c h is at a fixed p l a c e o n t h e d i s k . T h e
r o o t is like a n y o t h e r d i r e c t o r y , e x c e p t t h a t it h a s n o p a r e n t , a n d its s e c o n d a r y
type is different. A m i g a D O S stores the n a m e of the disk v o l u m e in the n a m e
field of t h e r o o t b l o c k .
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
I
T. S H O R T
1 |_
2 |
3 I
I
4 f
L
5
0
_0_ _
Type
^
Header k e y (always zero)
J
Highest seq n u m b e r (always zero)
HTSIZE
I
____o____J
CHJCKSJJJMJ
I
I
hash
I
I
table
I
SIZE-51 I
I
SIZE-50 [ ] _ B M F L A G
SIZE-49 |
I
SIZE-24 |
r
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 )
1
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
|
containing the bitmap
1
I
V o l u m e last a l t e r e d
date a n d time
I
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
r
1
SIZE-6
I CJREATEMINS I
SIZE-5
^CMATETICKS^
V o l u m e creation date
and
time
Next entry o n this h a s h chain (always zero)
SIZE-4
j
0
|
Parent directory (always zero)
SIZE-3
I
0
I
Extension (always zero)
SIZE-2
£
0
]j
Secondary type indicates root block
SIZE-1
J
ST.ROOT
|
Figure 1-A: Root Block
236
AMIGADOS TECHNICAL REFERENCE MANUAL
1.1.2 User Directory Blocks
T h e following figure describes t h e layout of t h e contents of a user directory
block.
0 I _Tj5HORT _
1
5
6
Type
E - - ^ — H e a d e r
2 [_
3
I
I
0
J
0
I
k e y ( p o i n t e r t o self)
Highest seq n u m b e r (always zero)
L c™9s_y_M J
s
I
I
I
I
hash
table
/
I
I
/
\
\
SIZE-51 I
I
SIZE-50 £
^pare_
SIZE-48 J
PROTECT
|
Protection bits
SIZE-47 I
0
I
U n u s e d (always zero)
1
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
_
Creation date a n d time
0
i
Stored as a B C P L string
|
of < = 30 characters
Next entry with same hash value
I
Back pointer to parent directory
Extension (always zero)
L J P l ^ S E R D J R J
secondary type
Figure 1-B: User Directory Blocks
FILING SYSTEM
237
U s e r d i r e c t o r y b l o c k s h a v e t y p e T. S H O R T a n d s e c o n d a r y t y p e S T . U S E R D I R E C T O R Y . T h e six i n f o r m a t i o n w o r d s at t h e start o f t h e b l o c k also i n d i c a t e t h e
block's o w n k e y (that is, t h e block n u m b e r ) as a consistency c h e c k a n d the size
o f t h e h a s h t a b l e . T h e 5 0 i n f o r m a t i o n w o r d s at t h e e n d o f t h e b l o c k c o n t a i n t h e
d a t e a n d time o f c r e a t i o n , t h e n a m e o f t h e d i r e c t o r y , a p o i n t e r to t h e n e x t file o r
directory on the h a s h chain, and a pointer to the directory above.
T o f i n d a file o r s u b d i r e c t o r y , y o u m u s t first a p p l y a h a s h f u n c t i o n t o its
n a m e . T h i s h a s h f u n c t i o n y i e l d s a n o f f s e t in t h e h a s h t a b l e , w h i c h is t h e k e y o f
t h e first b l o c k o n a c h a i n l i n k i n g t h o s e w i t h t h e s a m e h a s h v a l u e (or z e r o , if
there are n o n e ) . A m i g a D O S reads the block with this k e y a n d c o m p a r e s the
n a m e o f t h e b l o c k w i t h t h e r e q u i r e d n a m e . If t h e n a m e s d o n o t m a t c h , it r e a d s
the next block on the chain, and so on.
AMIGADOS TECHNICAL REFERENCE MANUAL
238
1.1.3 File Header Block
T h e f o l l o w i n g f i g u r e d e s c r i b e s t h e l a y o u t o f t h e file h e a d e r b l o c k .
0 I _ T^HORT _
Type
I
1 j]_OWN_KEY_J
2
Header key
L ^ G H E ^ S E Q J
3 I
T
D A T A SIZE_
I
Li^^KSUM
a
l
n
u
m
b
e
r
o f
d
a
t
b l o c k s in file
a
First d a t a b l o c k
J
DATA BLK 3
I
I DATA BLK 2
I
I
t
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
o
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 _
I
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
A
Creation date and time
of < = 30 characters
A
N
e
x
t
e n t r
y
w
i
t
h
s
a
m
e
h
a
s
h
v
a
l
u
e
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
I
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
l
;
_
I
Secondary type
Figure 1-C: File Header Block
FILING SYSTEM
239
E a c h t e r m i n a l file starts w i t h a file h e a d e r b l o c k , w h i c h h a s t y p e T . S H O R T
a n d s e c o n d a r y t y p e S T . F I L E . T h e start a n d e n d o f t h e b l o c k c o n t a i n n a m e ,
t i m e , a n d r e d u n d a n c y i n f o r m a t i o n similar t o t h a t i n a d i r e c t o r y b l o c k . T h e
b o d y o f t h e file c o n s i s t s o f D a t a b l o c k s w i t h s e q u e n c e n u m b e r s f r o m 1 u p ward. A m i g a D O S stores the addresses of these blocks in consecutive words
d o w n w a r d f r o m o f f s e t size-51 i n t h e b l o c k . I n g e n e r a l , A m i g a D O S d o e s n o t
u s e all t h e s p a c e for this list a n d t h e last d a t a b l o c k is n o t full.
1.1.4 File List Block
If t h e r e a r e m o r e b l o c k s i n t h e file t h a n c a n b e s p e c i f i e d i n t h e b l o c k list, t h e n
t h e E X T E N S I O N field is n o n z e r o a n d p o i n t s to a n o t h e r d i s k b l o c k w h i c h
c o n t a i n s a f u r t h e r d a t a b l o c k list. T h e f o l l o w i n g figure e x p l a i n s t h e s t r u c t u r e o f
t h e file list b l o c k .
0 I
1
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
I
4 £ FIRST DATA J
5
6
First d a t a b l o c k
L i ^ C K S J J M
J
I
I
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
J
(unused)
1
|
SIZE-4
|
0
SIZE-3
I _J'ARENT__
SIZE-2
J^EXTE^IOnJ
Next extension block
SIZE-1
|_
secondary type
ST.FILE
J
|
N e x t i n h a s h list ( a l w a y s z e r o )
I
File h e a d e r b l o c k o f this file
Figure 1-D: File List Block
AMIGADOS TECHNICAL REFERENCE MANUAL
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.
1.1.5 Data Block
T h e following figure explains t h e layout of a data block.
0 I _ JJDATA__
1 j
]
2 |
_ HEADER _
SE_Q_NUM
type
I
J
|
header key
sequence number
3 I JDATA_SIZE_ I
4
5
6
NEXT DATA
L
next data block
J
I
I
J
I
DATA
I
I
I
Figure 1-E: Data Block
D a t a b l o c k s c o n t a i n o n l y six w o r d s o f filing s y s t e m i n f o r m a t i o n . T h e s e six
w o r d s refer to the following:
• type (T.DATA)
• p o i n t e r to t h e file h e a d e r b l o c k
• s e q u e n c e n u m b e r of t h e data block
• n u m b e r o f w o r d s of d a t a
• pointer to the next data block
• checksum
N o r m a l l y , all d a t a b l o c k s e x c e p t t h e last a r e full ( t h a t i s , t h e y h a v e a size
b l o c k s i z e - 6 ) . T h e last d a t a b l o c k h a s a f o r w a r d p o i n t e r o f z e r o .
=
FILING SYSTEM
241
1.2 DISKED—The Disk Editor
T o inspect or patch disk blocks, y o u m a y use the A m i g a D O S disk editor,
D I S K E D . B e c a u s e D I S K E D w r i t e s to t h e d i s k directly, y o u s h o u l d u s e it w i t h
c a r e . N e v e r t h e l e s s , y o u c a n u s e it to g o o d effect i n r e c o v e r i n g i n f o r m a t i o n f r o m
a corrupt floppy disk, for example. A disk d o e s n o t h a v e to b e inserted to b e
examined by DISKED.
Y o u s h o u l d o n l y u s e D I S K E D w i t h r e f e r e n c e to t h e l a y o u t of a n A m i g a D O S
d i s k . ( F o r a d e s c r i p t i o n of t h e l a y o u t , s e e S u b s e c t i o n s 1 . 1 . 1 t h r o u g h 1 . 1 . 5 in t h e
first p a r t of t h i s c h a p t e r . ) D I S K E D k n o w s a b o u t t h i s s t r u c t u r e — f o r e x a m p l e , t h e
R ( R o o t B l o c k ) c o m m a n d p r i n t s t h e k e y of t h e r o o t b l o c k . T h e G ( G e t b l o c k )
c o m m a n d followed b y this k e y n u m b e r reads the block into m e m o r y , w h e r e u p o n the I (Information) c o m m a n d prints out the information contained in the
first a n d last l o c a t i o n s , w h i c h i n d i c a t e t h e t y p e of b l o c k , t h e n a m e , t h e h a s h
l i n k s , a n d s o o n . If y o u s p e c i f y a n a m e a f t e r a n H ( H a s h ) c o m m a n d , D I S K E D
g i v e s y o u t h e o f f s e t o n a d i r e c t o r y p a g e t h a t s t o r e s a s t h e first k e y h e a d e r s w i t h
n a m e s t h a t h a s h to t h e n a m e y o u s u p p l i e d . If y o u t h e n t y p e t h e n u m b e r t h a t
D I S K E D r e t u r n s f o l l o w e d b y a s l a s h (/), D I S K E D d i s p l a y s t h e k e y o f t h a t
h e a d e r page. Y o u can then read this with further G c o m m a n d s , a n d so on.
C o n s i d e r d e l e t i n g a file t h a t , d u e to h a r d w a r e e r r o r s , m a k e s t h e filing s y s t e m
r e s t a r t p r o c e s s fail. First, y o u m u s t l o c a t e t h e d i r e c t o r y p a g e t h a t h o l d s t h e
r e f e r e n c e t o t h e file. Y o u d o t h i s b y s e a r c h i n g t h e d i r e c t o r y s t r u c t u r e f r o m t h e
root block, u s i n g the h a s h codes. T h e n , y o u m u s t locate the slot that references
t h e f i l e — t h i s is e i t h e r t h e d i r e c t o r y b l o c k or a h e a d e r b l o c k o n t h e s a m e h a s h
c h a i n . T h i s slot s h o u l d c o n t a i n t h e k e y of t h e file's h e a d e r b l o c k . T o s e t t h e slot
t o z e r o , y o u t y p e t h e slot o f f s e t , f o l l o w e d b y a s l a s h (/) f o l l o w e d b y z e r o ( t h a t
is, < o f f s e t > / 0 ) . T h e n correct the c h e c k s u m with the K (checKsum) c o m m a n d .
Y o u should disable the write protection with X a n d write b a c k the u p d a t e d
b l o c k w i t h P (for P u t b l o c k ) or W (for W i n d u p ) . T h e r e is n o n e e d t o d o
a n y t h i n g e l s e , a s t h e b l o c k s t h a t t h e file u s e d i n e r r o r b e c o m e a v a i l a b l e o n c e
m o r e after the R E S T A R T process h a s successfully s c a n n e d the disk.
D I S K E D c o m m a n d s a r e all s i n g l e c h a r a c t e r s , s o m e t i m e s w i t h a r g u m e n t s .
T h e f o l l o w i n g is a c o m p l e t e list of t h e available c o m m a n d s .
AMIGADOS TECHNICAL REFERENCE MANUAL
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]
Display n characters from current offset
G e t b l o c k n f r o m d i s k ( 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 )
Cn
H name
Calculate H a s h value of n a m e
I
Display block Information
K
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
Locate words that do not match Value u n d e r M a s k
N[lwb upb]
Put block in m e m o r y to block n o n disk
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 )
R
Display block n u m b e r of root block
Q
S char
Set display Style
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
Set cYlinder base to n
Z
Z e r o all w o r d s o f b u f f e r
number
Set current w o r d offset in block = Display values set in program
/[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"
P u t string at current offset
Table 1-A: DISKED Commands
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
Amiga Binary File Structure
This chapter describes:
2.1
2.1.1
2.2
2.2.1
2.2.2
2.2.3
2.2.4
2.2.5
2.2.6
2.2.7
2.2.8
2.2.9
2.2.10
2.2.11
2.2.12
2.3
2.3.1
2.3.2
2.3.3
2.4
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
AMIGADOS TECHNICAL REFERENCE MANUAL
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
a
load
file.
A
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-
unresolved external references.
Program
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
a
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,
starts from zero
within
AMIGA BINARY FILE STRUCTURE
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
L o a d files a r e also k n o w n a s " l i b r a r i e s " . L o a d files m a y b e r e s i d e n t in m e m o r y ; a l t e r n a t i v e l y , t h e o p e r a t i n g s y s t e m m a y l o a d t h e m as p a r t of t h e " l i b r a r y
o p e n " call. Y o u c a n r e f e r e n c e r e s i d e n t libraries t h r o u g h e x t e r n a l r e f e r e n c e s ; t h e
d e f i n i t i o n s a r e in a h u n k c o n t a i n i n g n o c o d e , j u s t a list of r e s i d e n t library
d e f i n i t i o n s . U s u a l l y , t o p r o d u c e t h e s e h u n k s , y o u a s s e m b l e a file c o n t a i n i n g
n o t h i n g b u t a b s o l u t 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 n p a s s it t h r o u g h a s p e c i a l
s o f t w a r e t o o l t o c o n v e r t t h e a b s o l u t e d e f i n i t i o n s t o r e s i d e n t library d e f i n i t i o n s .
T h e l i n k e r u s e s t h e h u n k n a m e as t h e n a m e of t h e r e s i d e n t l i b r a r y , a n d it
p a s s e s t h i s t h r o u g h i n t o t h e l o a d file s o t h a t t h e l o a d e r c a n o p e n t h e r e s i d e n t
library b e f o r e u s e .
Scanned
Library
A s c a n n e d library c o n s i s t s of o b j e c t files t h a t c o n t a i n p r o g r a m u n i t s w h i c h
a r e o n l y l o a d e d 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 m . Y o u
m a y u s e o b j e c t files as libraries a n d p r o v i d e t h e m a s p r i m a r y i n p u t t o t h e
l i n k e r , i n w h i c h c a s e t h e i n p u t i n c l u d e s all t h e p r o g r a m u n i t s t h e o b j e c t files
c o n t a i n . N o t e t h a t y o u m a y c o n c a t e n a t e o b j e c t files.
Node
A n o d e c o n s i s t s of at l e a s t o n e h u n k . A n o v e r l a i d l o a d file c o n t a i n s a r o o t
n o d e , w h i c h is r e s i d e n t i n m e m o r y all t h e t i m e t h a t t h e p r o g r a m is r u n n i n g ,
a n d a n u m b e r of o v e r l a y n o d e s w h i c h are b r o u g h t i n t o m e m o r y a s r e q u i r e d .
246
AMIGADOS TECHNICAL REFERENCE MANUAL
2.2 Object File Structure
A n o b j e c t file is t h e o u t p u t o f t h e a s s e m b l e r or a l a n g u a g e t r a n s l a t o r . T o u s e a n
o b j e c t file, y o u m u s t first r e s o l v e all t h e e x t e r n a l r e f e r e n c e s . T o d o t h i s , y o u
p a s s t h e o b j e c t file t h r o u g h t h e l i n k e r . A n o b j e c t file c o n s i s t s o f o n e o r m o r e
p r o g r a m u n i t s . E a c h p r o g r a m u n i t starts w i t h a h e a d e r a n d is f o l l o w e d b y a
series of h u n k s j o i n e d e n d to e n d , each of w h i c h contains a n u m b e r of " b l o c k s "
o f v a r i o u s t y p e s . E a c h b l o c k starts w i t h a l o n g w o r d w h i c h d e f i n e s its t y p e , a n d
t h i s is f o l l o w e d b y z e r o o r m o r e a d d i t i o n a l l o n g w o r d s . N o t e t h a t e a c h b l o c k is
a l w a y s r o u n d e d u p to t h e n e a r e s t l o n g w o r d b o u n d a r y . T h e p r o g r a m
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 .
2.2.2 hunk^unit (999/3E7)
T h i s s p e c i f i e s t h e start o f a p r o g r a m u n i t . It c o n s i s t s o f a t y p e w o r d , f o l l o w e d
b y t h e l e n g t h of t h e u n i t n a m e in l o n g w o r d s , f o l l o w e d b y t h e n a m e itself
p a d d e d t o a l o n g w o r d b o u n d a r y w i t h z e r o s , if r e q u i r e d . I n d i a g r a m a t i c f o r m ,
t h e f o r m a t is a s f o l l o w s :
AMIGA BINARY FILE STRUCTURE
hunk
247
unit
_ _ N _ _
N
long words
of
name
Figure 2-A: hunk_unit (999/3E7)
2.2.2 hunk_name (1000/3E8)
T h i s d e f i n e s t h e n a m e of a h u n k . N a m e s a r e o p t i o n a l ; if t h e l i n k e r f i n d s
t w o or m o r e n a m e d h u n k s w i t h t h e s a m e n a m e , it c o m b i n e s t h e h u n k s i n t o a
s i n g l e h u n k . N o t e t h a t 8- or 16-bit p r o g r a m c o u n t e r r e l a t i v e e x t e r n a l r e f e r ences can only be resolved between h u n k s with the same n a m e . A n y external
r e f e r e n c e s in a l o a d f o r m a t file a r e b e t w e e n d i f f e r e n t h u n k s a n d r e q u i r e 3 2 bit relocatable references; although, as the loader scatterloads the h u n k s
i n t o m e m o r y , y o u c a n n o t a s s u m e t h a t t h e y a r e w i t h i n 3 2 K of e a c h o t h e r .
N o t e t h a t t h e l e n g t h is i n l o n g w o r d s a n d t h e n a m e b l o c k , like all b l o c k s ,
is r o u n d e d u p t o a l o n g w o r d b o u n d a r y b y p a d d i n g w i t h z e r o s . T h e f o r m a t is
as follows:
hunk
name
N
N
long words
of
name
Figure 2-B: hunk_name (1000/3E8)
2.2.3 hunk—code (1001/3E9)
T h i s d e f i n e s a b l o c k of c o d e t h a t is to b e l o a d e d i n t o m e m o r y a n d p o s s i b l y
r e l o c a t e d . Its f o r m a t is as f o l l o w s :
248
AMIGADOS TECHNICAL REFERENCE MANUAL
hunk
code
N
N
long words
of
code
Figure 1-C: hunk_code (1001/3E9)
2.2.4 hunk_data (1002/3EA)
T h i s d e f i n e s a b l o c k o f initialized d a t a w h i c h is t o b e l o a d e d i n t o m e m o r y a n d
p o s s i b l y r e l o c a t e d . T h e l i n k e r s h o u l d n o t alter t h e s e b l o c k s if t h e y a r e p a r t o f
a n o v e r l a y n o d e , a s it m a y n e e d t o r e r e a d t h e m f r o m d i s k d u r i n g o v e r l a y
h a n d l i n g . T h e f o r m a t is a s f o l l o w s :
hunk
data
N
N
long words
of
data
Figure 1-D: hunk_data (1002/3EA)
2.2.5 hunk—bss (1003/3EB)
T h i s s p e c i f i e s a b l o c k o f u n i n i t i a l i z e d w o r k s p a c e w h i c h is a l l o c a t e d b y t h e
loader, b s s blocks are used for such things as stacks a n d for F O R T R A N
C O M M O N b l o c k s . I t is n o t p o s s i b l e t o r e l o c a t e i n s i d e a b s s b l o c k , b u t s y m b o l s
c a n b e d e f i n e d w i t h i n o n e . I t s f o r m a t is a s f o l l o w s :
hunk
bss
N
Figure 1-E: h u n k _ b s s (1003/3EB)
AMIGA BINARY FILE STRUCTURE
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
Figure 2-F: hunk_reIoc32 (1004/3EC)
250
AMIGADOS TECHNICAL REFERENCE MANUAL
2 . 2 . 7 hunk—relocl6 (1005/3ED)
A hunk
reloc 16 b l o c k specifies 16-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
within t h e current relocatable block. T h e relocation information refers to 16 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 to o t h e r h u n k s i n 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 as 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 ( 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 .
2.2.8 hunk_reloc8 (1006/3EE)
A hunk
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 .
2.2.9 hunk—ext (1007/3EF)
T h i s b l o c k c o n t a i n s 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 . It c o n t a i n s e n t r i e s b o t h d e f i n i n g s y m b o l s a n d l i s t i n g r e f e r e n c e s t o t h e m . Its f o r m a t is as f o l l o w s :
I
hunk
ext
I
I
Symbol
I
I
data
I
I
unit
I
I
Symbol
I
I
data
I
I
unit
I
0
Figure 2-G: hunk_ext (1007/3EF)
w h e r e t h e r e is o n e " s y m b o l d a t a u n i t " f o r e a c h s y m b o l u s e d , a n d t h e b l o c k e n d s
with a zero word.
E a c h s y m b o l data unit consists of a type byte, the symbol n a m e length (three
b y t e s ) , t h e s y m b o l n a m e itself, a n d f u r t h e r d a t a . Y o u s p e c i f y t h e s y m b o l n a m e
l e n g t h i n l o n g w o r d s , a n d p a d t h e n a m e field to t h e n e x t l o n g w o r d b o u n d a r y
with zeros.
AMIGA BINARY FILE STRUCTURE
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 table—see 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
Table 2-A: External Symbols
T h e l i n k e r faults all o t h e r v a l u e s . F o r e x t d e f t h e r e is o n e d a t a w o r d , t h e
v a l u e of t h e s y m b o l . T h i s is m e r e l y t h e o f f s e t of t h e s y m b o l f r o m t h e start o f
t h e h u n k . F o r e x t a b s t h e r e is also o n e d a t a v a l u e , w h i c h is t h e a b s o l u t e v a l u e
t o b e a d d e d i n t o t h e c o d e . T h e l i n k e r t r e a t s t h e v a l u e for ext r e s in t h e s a m e
w a y a s ext d e f , e x c e p t that it a s s u m e s t h e h u n k n a m e is t h e library n a m e a n d it
c o p i e s this n a m e t h r o u g h to t h e l o a d file. T h e t y p e b y t e s e x t — r e f 3 2 , e x t — r e f l 6 ,
a n d e x t ref8 a r e f o l l o w e d b y a c o u n t a n d a list of r e f e r e n c e s , a g a i n s p e c i f i e d a s
o f f s e t s f r o m t h e start of t h e h u n k .
T h e t y p e e x t c o m m o n h a s t h e s a m e structure e x c e p t that it h a s a C O M M O N
b l o c k size b e f o r e t h e c o u n t . T h e l i n k e r t r e a t s s y m b o l s s p e c i f i e d a s c o m m o n i n
t h e f o l l o w i n g w a y : if it e n c o u n t e r s a d e f i n i t i o n f o r a s y m b o l r e f e r e n c e d a s
c o m m o n , t h e n it u s e s this v a l u e ( t h e o n l y time a d e f i n i t i o n s h o u l d arise is i n
t h e F O R T R A N B l o c k D a t a c a s e ) . O t h e r w i s e , it a l l o c a t e s s u i t a b l e b s s s p a c e u s i n g
t h e m a x i m u m size y o u s p e c i f i e d f o r e a c h c o m m o n s y m b o l r e f e r e n c e .
T h e l i n k e r h a n d l e s e x t e r n a l r e f e r e n c e s d i f f e r e n t l y a c c o r d i n g to t h e t y p e of t h e
c o r r e s p o n d i n g d e f i n i t i o n . It a d d s a b s o l u t e v a l u e s to t h e l o n g w o r d , or b y t e
field a n d g i v e s a n e r r o r if t h e s i g n e d v a l u e d o e s n o t fit. R e l o c a t a b l e 32-bit
r e f e r e n c e s h a v e t h e s y m b o l v a l u e a d d e d t o t h e field a n d a r e l o c a t i o n r e c o r d is
p r o d u c e d f o r t h e l o a d e r . 16- a n d 8-bit r e f e r e n c e s a r e h a n d l e d a s P C r e l a t i v e
r e f e r e n c e s a n d m a y o n l y b e m a d 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
h u n k s a r e c o a g u l a t e d b y t h e l i n k e r b e f o r e t h e y a r e l o a d e d . It is also p o s s i b l e f o r
P C relative r e f e r e n c e s t o fail if t h e r e f e r e n c e a n d t h e d e f i n i t i o n a r e t o o far a p a r t .
T h e l i n k e r m a y o n l y a c c e s s r e s i d e n t library d e f i n i t i o n s w i t h 32-bit r e f e r e n c e s ,
w h i c h it t h e n h a n d l e s a s r e l o c a t a b l e 32-bit r e f e r e n c e s . T h e s y m b o l d a t a u n i t
formats are as follows:
252
AMIGADOS TECHNICAL REFERENCE MANUAL
ext
def/abs/res
Figure 2-H: Symbol Data Unit
l_ _ _ty_p I N a m e L e n g t h N L
NL long words
of symbol n a m e
I
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
AMIGA BINARY FILE STRUCTURE
2.2.10 hunksymbol
(1008/3F0)
Y o u u s e this block to attach a symbol table to a h u n k so that y o u can u s e a
symbolic debugger on the code. T h e linker passes symbol table blocks through
a t t a c h e d t o t h e h u n k a n d , if t h e h u n k s are c o a g u l a t e d , c o a g u l a t e s t h e s y m b o l
t a b l e s . T h e l o a d e r d o e s n o t l o a d s y m b o l t a b l e b l o c k s i n t o m e m o r y ; w h e n t h i s is
r e q u i r e d , t h e d e b u g g e r is e x p e c t e d t o r e a d t h e l o a d file. T h e f o r m a t o f t h e
s y m b o l t a b l e b l o c k is t h e s a m e a s t h e 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 b l o c k w i t h
s y m b o l t a b l e u n i t s for e a c h n a m e y o u u s e . T h e t y p e c o d e o f z e r o is u s e d
w i t h i n t h e s y m b o l d a t a u n i t s . T h e v a l u e of t h e s y m b o l is t h e o f f s e t o f t h e s y m b o l
f r o m t h e s t a r t o f t h e h u n k . T h u s t h e f o r m a t is a s f o l l o w s :
hunk
symbol
Symbol
data
unit
I
I
0
Figure 2-1: hunk_symbol (1008/3F0)
w h e r e each symbol data unit has the following format:
L _ 9. L ^ L " ? ^ t
2
e
i}§%
J
_
I
N L long words
I
I
of symbol n a m e
I
Symbol value
Figure 2-J: Symbol Data Unit
254
AMIGADOS TECHNICAL REFERENCE M A N U A L
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
debug long word
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
Figure 2-K: hunk_debug (1009/3F1)
2.2.12 hunk__end (1010/3F2)
T h i s s p e c i f i e s t h e e n d of a h u n k . It c o n s i s t s of a s i n g l e l o n g w o r d , h u n k
end.
2.3 Load Files
T h e f o r m a t of a l o a d file ( t h a t i s , t h e o u t p u t f r o m t h e l i n k e r ) is similar t o t h a t of
a n o b j e c t file. I n p a r t i c u l a r , it c o n s i s t s of a n u m b e r of h u n k s w i t h a similar
f o r m a t t o t h o s e i n a n o b j e c t file. T h e m a i n d i f f e r e n c e is t h a t t h e h u n k s n e v e r
c o n t a i n a 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 b l o c k , a s all e x t e r n a l s y m b o l s h a v e
b e e n r e s o l v e d , a n d t h e p r o g r a m u n i t i n f o r m a t i o n is n o t i n c l u d e d . I n a s i m p l e
l o a d file t h a t is n o t o v e r l a i d , t h e file c o n t a i n s a h e a d e r b l o c k w h i c h i n d i c a t e s
t h e total n u m b e r of h u n k s in t h e l o a d file a n d a n y r e s i d e n t libraries t h e
p r o g r a m r e f e r e n c e d . T h i s b l o c k is f o l l o w e d b y t h e h u n k s , w h i c h m a y b e t h e
r e s u l t of c o a g u l a t i n g a n u m b e r of i n p u t h u n k s if t h e y h a d t h e s a m e n a m e . T h i s
c o m p l e t e s t r u c t u r e is r e f e r r e d to a s a n o d e . L o a d files m a y also c o n t a i n o v e r l a y
i n f o r m a t i o n . I n t h i s c a s e , a n o v e r l a y table f o l l o w s t h e p r i m a r y n o d e , a n d a
s p e c i a l b r e a k b l o c k s e p a r a t e s t h e o v e r l a y n o d e s . T h u s t h e l o a d file s t r u c t u r e c a n
b e s u m m a r i z e d a s f o l l o w s , w h e r e t h e i t e m s m a r k e d w i t h a n a s t e r i s k (*) a r e
optional.
AMIGA BINARY FILE STRUCTURE
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.
2.3.1 hunk—header (1011/3F3)
T h i s b l o c k g i v e s i n f o r m a t i o n a b o u t t h e n u m b e r of h u n k s t h a t a r e to b e l o a d e d ,
a n d t h e size of e a c h o n e . It also c o n t a i n s t h e n a m e s of a n y r e s i d e n t libraries
w h i c h m u s t b e o p e n e d w h e n t h e n o d e is l o a d e d .
T h e f o r m a t of t h e h u n k h e a d e r is d e s c r i b e d i n F i g u r e 2 - L . T h e first p a r t of
t h e h e a d e r b l o c k c o n t a i n s t h e n a m e s of r e s i d e n t libraries t h a t t h e l o a d e r m u s t
o p e n w h e n this n o d e is l o a d e d . E a c h n a m e c o n s i s t s of a l o n g w o r d i n d i c a t i n g
t h e l e n g t h of t h e n a m e i n l o n g w o r d s a n d t h e text n a m e p a d d e d t o a l o n g w o r d
b o u n d a r y w i t h z e r o s . T h e n a m e list e n d s w i t h a l o n g w o r d of z e r o . T h e n a m e s
a r e i n t h e o r d e r i n w h i c h t h e l o a d e r is t o o p e n t h e m .
W h e n it l o a d s a p r i m a r y n o d e , t h e l o a d e r a l l o c a t e s a table in m e m o r y w h i c h
it u s e s t o k e e p track of all t h e h u n k s it h a s l o a d e d . T h i s table m u s t b e l a r g e
e n o u g h for all t h e h u n k s i n t h e l o a d file, i n c l u d i n g t h e h u n k s i n o v e r l a y s . T h e
l o a d e r a l s o u s e s t h i s table t o k e e p a c o p y of t h e h u n k t a b l e s a s s o c i a t e d w i t h a n y
r e s i d e n t libraries. T h e n e x t l o n g w o r d i n t h e h e a d e r b l o c k is t h e r e f o r e t h i s t a b l e
s i z e , w h i c h is e q u a l to t h e m a x i m u m h u n k n u m b e r r e f e r e n c e d p l u s o n e .
256
AMIGADOS TECHNICAL REFERENCE MANUAL
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
Figure 2-L: hunk__header (1011/3F3)
T h e header block continues with L - F + 1 long words w h i c h indicate the
size of e a c h h u n k w h i c h is to b e l o a d e d a s p a r t of t h i s call. T h i s e n a b l e s t h e
l o a d e r t o p r e a l l o c a t e t h e s p a c e for t h e h u n k s a n d h e n c e p e r f o r m t h e r e l o c a t i o n
b e t w e e n h u n k s w h i c h is r e q u i r e d a s t h e y are l o a d e d . O n e h u n k m a y b e t h e b s s
h u n k w i t h a size g i v e n a s z e r o ; in t h i s c a s e t h e l o a d e r u s e s a n o p e r a t i n g s y s t e m
v a r i a b l e t o g i v e t h e size a s d e s c r i b e d in h u n k b s s o n p a g e 2 4 8 .
AMIGA BINARY FILE STRUCTURE
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 +
1
zeros
Overlay
data
table
Figure 2-M: hunk_overIay (1013/3F5)
T h e first l o n g w o r d is t h e u p p e r b o u n d of t h e c o m p l e t e o v e r l a y t a b l e (in
long words).
M is t h e m a x i m u m level of t h e o v e r l a y tree u s e s w i t h t h e r o o t l e v e l b e i n g
z e r o . T h e n e x t M + 1 w o r d s f o r m t h e o r d i n a t e t a b l e s e c t i o n of t h e o v e r l a y
table.
T h e r e s t of t h e b l o c k is t h e o v e r l a y d a t a t a b l e , a s e r i e s of e i g h t - w o r d e n t r i e s ,
o n e f o r e a c h o v e r l a y s y m b o l . If 0 is t h e m a x i m u m o v e r l a y n u m b e r u s e d , t h e n
t h e size of t h e o v e r l a y d a t a table is (0 + 1 ) * 8 , s i n c e t h e first o v e r l a y n u m b e r is
z e r o . S o , t h e o v e r l a y table size is e q u a l to (0 + 1)*8 + M + 1.
2.3.3 hunk_break (1014/3F6)
A b r e a k b l o c k i n d i c a t e s t h e e n d of a n o v e r l a y n o d e . It c o n s i s t s of a s i n g l e
long word, hunk
break.
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,
AMIGADOS TECHNICAL REFERENCE MANUAL
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
AMIGA BINARY FILE STRUCTURE
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
and the corresponding output code would be:
hunk
unit
00000001
42000000
hunk
code
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
AMIGADOS TECHNICAL REFERENCE MANUAL
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
AMIGA BINARY FILE STRUCTURE
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
AmigaDOS Data Structures
T h i s c h a p t e r d e s c r i b e s A m i g a D O S d a t a s t r u c t u r e s in m e m o r y a n d i n files. It
d o e s n o t d e s c r i b e t h e l a y o u t of a d i s k , w h i c h is d e s c r i b e d i n C h a p t e r 1.
3.1
3.2
3.3
3.3.1
3.4
3.5
3.6
3.7
3.8
3.8.1
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
AMIGADOS DATA STRUCTURES
263
o n t h e s t a c k s o far ( t h e initial s t a c k is l o n g w o r d a l i g n e d ) . Y o u s h o u l d t h e n shift
t h i s p o i n t e r r i g h t b y 2 to c r e a t e t h e B P T R .
A m i g a D O S a l s o h a s a B S T R , w h i c h is a B C P L s t r i n g . B S T R c o n s i s t s of a
B P T R t o m e m o r y t h a t c o n t a i n s t h e l e n g t h of t h e s t r i n g in t h e first b y t e , a n d t h e
bytes within the string following.
A n u m b e r of r e f e r e n c e s to t h e G l o b a l V e c t o r a p p e a r w i t h i n this c h a p t e r . T h e
G l o b a l V e c t o r is a j u m p table u s e d b y B C P L a n d is a p o i n t e r t o a s t a n d a r d
s h a r e d G l o b a l V e c t o r . S o m e p r o c e s s e s , s u c h as t h e file h a n d l e r , u s e a p r i v a t e
global vector.
T h e i n c l u d e files d o s . h a n d d o s e x t e n s . h c o n t a i n C l a n g u a g e d e f i n i t i o n s f o r
t h e f o l l o w i n g s t r u c t u r e s . T h e .i files f o r a s s e m b l y l a n g u a g e .
3.2 Process Data Structures
T h e s e v a l u e s a r e c r e a t e d a s p a r t of a n A m i g a D O S p r o c e s s ; t h e r e is a c o m p l e t e
set for each process.
A p r o c e s s i s a n E x e c t a s k w i t h a n u m b e r of e x t r a d a t a s t r u c t u r e s a p p e n d e d .
T h e p r o c e s s s t r u c t u r e c o n s i s t s of:
Exec task structure
Exec message port
A m i g a D O S process values
T h e p r o c e s s i d e n t i f i e r A m i g a D O S u s e s i n t e r n a l l y is a p o i n t e r to t h e E x e c
m e s s a g e port (from w h i c h the Exec task m a y be obtained).
A m i g a D O S p r o c e s s v a l u e s are as f o l l o w s :
Value
BPTR
LONG
APTR
LONG
BPTR
LONG
BPTR
BPTR
BPTR
APTR
APTR
BPTR
APTR
APTR
APTR
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
AMIGADOS TECHNICAL REFERENCE MANUAL
264
T o identify the s e g m e n t s that a particular process u s e s , y o u u s e S e g A r r a y .
S e g A r r a y is a n a r r a y o f l o n g w o r d s w i t h its size i n S e g A r r a y [ 0 ] . O t h e r e l e m e n t s
are either zero or a B P T R to a SegList. CreateProc creates this array with the
first t w o e l e m e n t s o f t h e a r r a y p o i n t i n g t o r e s i d e n t c o d e a n d t h e t h i r d e l e m e n t
b e i n g t h e S e g L i s t p a s s e d a s a r g u m e n t . W h e n a p r o c e s s t e r m i n a t e s , F r e e M e m is
u s e d to r e t u r n t h e s p a c e f o r t h e S e g A r r a y .
S t a c k S i z e i n d i c a t e s t h e size o f t h e p r o c e s s s t a c k , a s s u p p l i e d b y t h e u s e r
w h e n c a l l i n g C r e a t e P r o c . N o t e t h a t t h e p r o c e s s s t a c k is n o t t h e s a m e a s t h e
command
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 .
The CLI obtains
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
Lock associated with c o m m a n d directory
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
Default (terminal) CLI input
BPTR
Currentln
Current CLI input
AMIGADOS DATA STRUCTURES
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 .
a
AMIGADOS TECHNICAL REFERENCE MANUAL
266
3.3 Global Data Structure
T h i s d a t a s t r u c t u r e o n l y e x i s t s o n c e ; h o w e v e r , all A m i g a D O S p r o c e s s e s u s e it.
If y o u m a k e a call t o O p e n L i b r a r y , y o u c a n o b t a i n t h e library b a s e p o i n t e r . T h e
b a s e o f t h e d a t a s t r u c t u r e is a p o s i t i v e o f f s e t f r o m t h e l i b r a r y b a s e p o i n t e r . T h e
library b a s e pointer points to the following structure:
Library N o d e structure
A P T R to D O S R o o t N o d e
A P T R to D O S Shared Global Vector
D O S private register d u m p
A l l i n t e r n a l A m i g a D O S calls u s e t h e S h a r e d G l o b a l V e c t o r , w h i c h is a j u m p
t a b l e . Y o u s h o u l d n o t n o r m a l l y u s e it, e x c e p t t h r o u g h t h e s u p p l i e d i n t e r f a c e
c a l l s , a s it i s l i a b l e t o c h a n g e w i t h o u t w a r n i n g .
T h e R o o t N o d e s t r u c t u r e is a s f o l l o w s :
Value
Function
Description
BPTR
TaskTable
Array of CLI processes currently r u n n i n g
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.
AMIGADOS DATA STRUCTURES
267
3.3.1 Info Substructure
To access a further substructure with the following format, y o u use the Info
pointer.
Value
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
Network handler process id, currently zero
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
Handler process or zero
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
Priority for h a n d l e r process
S t a r t u p v a l u e to b e p a s s e d to h a n d l e r p r o c e s s
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
Global Vector for handler process or zero
BSTR
Name
N a m e of device or A S S I G N e d n a m e
T h e N e x t field l i n k s all t h e list e n t r i e s t o g e t h e r , a n d t h e n a m e o f t h e l o g i c a l
d e v i c e n a m e is h e l d in t h e N a m e field.
T h e T y p e field is 0 (dt
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
AMIGADOS TECHNICAL REFERENCE MANUAL
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
n e w h a n d l e r process m a y t h e n decide to patch into the T a s k slot the p r o c e s s
i d o r n o t as r e q u i r e d . If t h e T a s k slot is p a t c h e d , t h e n s u b s e q u e n t
ences
to the
device
name
use
the
same
handler
refer-
task; this is w h a t
the
R A M : device d o e s . If t h e T a s k slot is n o t p a t c h e d , t h e n further references
t o t h e d e v i c e r e s u l t in n e w p r o c e s s i n v o c a t i o n s ; t h i s is w h a t t h e C O N : d e v i c e
does.
I f t h e T y p e field w i t h i n t h e list e n t r y is e q u a l t o 2 ( d t
volume), then the format
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
List entry type (volume)
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
AMIGADOS DATA STRUCTURES
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.
3.4 Memory Allocation
A m i g a D O S o b t a i n s all t h e m e m o r y it a l l o c a t e s b y calling t h e A l l o c M e m f u n c tion p r o v i d e d b y E x e c . I n t h i s w a y , A m i g a D O S o b t a i n s s t r u c t u r e s s u c h a s l o c k s
a n d file h a n d l e s ; it u s u a l l y p l a c e s t h e m b a c k in t h e f r e e p o o l b y c a l l i n g
F r e e M e m . E a c h m e m o r y s e g m e n t a l l o c a t e d b y A m i g a D O S is i d e n t i f i e d b y a
B P T R t o t h e s e c o n d l o n g w o r d i n t h e s t r u c t u r e . T h e first l o n g w o r d a l w a y s
c o n t a i n s t h e l e n g t h of t h e e n t i r e s e g m e n t i n b y t e s . T h u s t h e s t r u c t u r e o f
a l l o c a t e d m e m o r y is a s f o l l o w s :
Value
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
3.5 Segment Lists
T o o b t a i n a s e g m e n t list, y o u call L o a d S e g . T h e r e s u l t is a B P T R t o a l l o c a t e d
m e m o r y , s o t h a t t h e l e n g t h o f t h e m e m o r y b l o c k c o n t a i n i n g e a c h list e n t r y i s
s t o r e d at -4 f r o m t h e B P T R . T h i s l e n g t h is 8 m o r e t h a n t h e s i z e o f t h e s e g m e n t
list e n t r y , a l l o w i n g f o r t h e l i n k field a n d t h e s i z e field itself.
T h e S e g L i s t is a list l i n k e d t o g e t h e r b y B P T R s a n d t e r m i n a t e d b y z e r o . T h e
r e m a i n d e r of e a c h s e g m e n t list e n t r y c o n t a i n s t h e c o d e l o a d e d . T h u s t h e f o r m a t
is
Value
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
3.6 File Handles
File h a n d l e s a r e c r e a t e d b y t h e A m i g a D O S f u n c t i o n O p e n , a n d y o u u s e t h e m
as arguments to other functions such as Read and Write. A m i g a D O S returns
t h e m a s a B P T R to t h e f o l l o w i n g s t r u c t u r e :
AMIGADOS TECHNICAL REFERENCE MANUAL
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
AMIGADOS DATA STRUCTURES
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
Pointer back to m e s s a g e structure
APTR
MsgPort
Description
LONG
PktType
Message port where the reply should be sent
Packet type
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
Argument; depends on packet type
LONG
Arg2
Argument; depends on packet type
LONG
ArgN
Argument; depends on packet type
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
AMIGADOS TECHNICAL REFERENCE MANUAL
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
c o n t a i n s a value in t h e P k t T y p e field w h i c h indicates a n action to b e performed,
such as reading s o m e data. T h e
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.
3.8.1 Packet Types
A m i g a D O S s u p p o r t s t h e f o l l o w i n g p a c k e t t y p e s . N o t all t y p e s a r e v a l i d t o all
h a n d l e r s , f o r e x a m p l e a r e n a m e r e q u e s t is o n l y v a l i d t o h a n d l e r s s u p p o r t i n g a
filing s y s t e m . F o r e a c h p a c k e t t y p e t h e a r g u m e n t s a n d r e s u l t s a r e d e s c r i b e d .
T h e a c t u a l d e c i m a l c o d e f o r e a c h t y p e a p p e a r s n e x t t o t h e s y m b o l i c n a m e . I n all
c a s e s , t h e R e s 2 field c o n t a i n s a d d i t i o n a l i n f o r m a t i o n c o n c e r n i n g a n e r r o r ( i n d i cated b y a zero value for R e s l
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.
Open Old File
Type
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 ,
AMIGADOS DATA STRUCTURES
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.
Open New File
Type
Argl
Arg2
Arg3
LONG
BPTR
BPTR
BSTR
Action. FindOutput ( 1 0 0 6 )
FileHandle
Lock
Name
Resl
LONG
Boolean
Arguments as for previous entry.
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 read—see
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
AMIGADOS TECHNICAL REFERENCE MANUAL
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
AMIGADOS DATA STRUCTURES
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
AMIGADOS TECHNICAL REFERENCE MANUAL
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
AMIGADOS DATA STRUCTURES
277
This implements the DupLock function. If the lock requiring duplication is
zero, then the duplicate is zero. Otherwise, the process id is extracted from the
lock and this packet type sent. The result is the new lock or zero if an error was
detected.
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
This implements the SetComment function. Arguments as for SetProtect
above, except that Arg4 is a BSTR representing the comment.
278
AMIGADOS TECHNICAL REFERENCE MANUAL
RenameObject
Type
Argl
Arg2
Arg3
Arg4
LONG
BPTR
BPTR
BPTR
BPTR
Action.RenameObject ( 1 7 )
FromLock
FromName
ToLock
ToName
Resl
LONG
Boolean
This implements the Rename function. It must contain an owning directory
lock and a name for both the source and the destination. The owning directories
are obtained from DeviceProc as mentioned under the entry for the DeleteObject.
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
AMIGADOS TECHNICAL REFERENCE MANUAL
Hunk Overlay
Table—Overview
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.
Designing an Overlay Tree
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
AMIGADOS ADDITIONAL INFORMATION
main (root level of the tree)
a,b,c,d (1,1)
e (2,1)
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.
Describing the Tree
You create the tree by telling the overlay linker about its structure. The
numerical values, similar to those noted in the figure above, are assigned
sequentially by the linker itself and appear in the hunk node table. Here is the
sequence of overlay link statements that cause the figure above to be built:
OVERLAY
a,b,c,d
g
*h
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
AMIGADOS TECHNICAL REFERENCE MANUAL
282
either a-d or g will be memory-resident, but not both simultaneously. Names
h,i, and j are shown to be related to g, one level down.
The above paragraphs have explained the origin of the hunk node level and
the hunk ordinate in the hunk overlay symbol table.
Seek Offset
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.
ATOM: (Alink Temporary Object Modifier)
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":
Programmers need/want to be able to specify that parts of their program go
into "chip" memory (the first 512K) so that the custom chips can access it.
They also need/want to treat this data just like any other data in their program
and therefore have it link and load normally.
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.
AMIGADOS ADDITIONAL INFORMATION
283
The ATOM Solution
1. Compile or assemble normally.
2. Pass the object code through a post- (or pre-) processor called "ATOM".
ATOM will interact with the user and the object file(s). It will flag the
desired hunks (or all hunks) as "for chip memory" by changing the hunk
type.
3. The linker will now take nine (9) hunk types instead of 3. The old types
were hunk code, hunk data, and hunk_bss. The new ones will be:
hunk code chip = hunk code + bit 30 set
hunk code fast = hunk code + bit 31 set
hunk data chip = hunk data + bit 30 set
hunk data fast = hunk data + bit 31 set
hunk bss chip = hunk bss 4- bit 30 set
hunk bss fast
= hunk bss + bit 31 set
The linker will pass all hunk types through to the LOADER (coagulating if
necessary). The LOADER uses the hunk header information when loading.
You will recall from the information provided in the linker documentation
that CODE hunks contain executable (68000) machine language, DATA
hunks contain initialized data (constants, . . .) and BSS hunks contain
unintialized data (arrays, variable declarations, . . .).
4. The LOADER will load according to information from step 3 above. Hunks
will go into the designated memory type.
5. Old versions of the LOADER will interpret the new hunk types as VERY
large hunk and not load (error 103, not enough memory).
Future Solutions
The assembler and Lattice " C " may be changed to generate the new hunk
types under programmer control.
How the Bits Work
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 MEMF—CHIP
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
AMIGADOS TECHNICAL REFERENCE MANUAL
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 now—edit, 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.
ATOM Command Line Syntax
The command line syntax is:
ATOM <infile> <outfile> [-1]
or
ATOM <inffle> <outfile> [-C[CtDlB]] [-F[CtDB]]
[-P[CIDIB]]
Where:
<infile>
<outfile>
-C
-F
-P
Represents an object file, just compiled, assembled or ATOMed
(Yes, you can re-ATOM an object file).
The destination for the converted file.
Change memory to CHIP
Change memory to FAST
Change memory to "Public". (Any type of memory available.)
AMIGADOS ADDITIONAL INFORMATION
C
D
B
285
Change CODE hunks
Change DATA hunks
Change BSS hunks
Command Line Examples
Example #1
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
To set all data hunks to load into chip memory type:
atom myfile.o myfile.set.o -cd
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
{Note: code hunk}
{Note: request for help}
f
286
AMIGADOS TECHNICAL REFERENCE MANUAL
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
{cancels the operation, no output file is
created}
{does not change the rest of the file,
just passes it through}
{skip this hunk, show next}
{Note: data hunk}
Error Bad Args:
a) An option does not start with a "-"
b) wrong number of parameters
c) "-" not followed by I, C, F, or P.
d) -x supplied in addition to -I, etc.
Error Bad infile:
File not found.
Error Bad Outfile:
File cannot be created.
Error Bad Type # # :
ATOM has detected a hunk type that it does not recognize. The object file
may be corrupt.
Error empty input:
Input file does not contain any data.
Error ReadExternals:
External reference or definition if of an undefined type. Object file may be
corrupt.
Error premature end of file:
An end of file condition (out of data) was detected while ATOM was still
expecting input. Object file may be corrupt.
AMIGADOS ADDITIONAL INFORMATION
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.
Creating a New Device to Run Under AmigaDOS
This section provides information about adding devices that are NOT part of
the DOS filing system. The next section provides information about adding
file-system-related devices (hard disks, floppy disks)—that is, devices that DOS
can use to read and write files with their associated directories.
You would want to use this information to add a new device such as a new
serial port or a new parallel port. In this case you may be creating a device
named "SER2:" which is to act just like "SER:" as far as DOS is concerned.
There are two steps involved here. First, you must create a suitable device, a
process that is not addressed here.
Note: The code for creating a skeleton disk-resident device is contained in
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 id—see 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
AMIGADOS TECHNICAL REFERENCE MANUAL
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
(EndModule-StartModule)/4 Size of module in 1 words
(your code)
0,4
0
1
EntryPoint-StartModule
1
Align to lword boundary
End marker
Define Global 1
Offset of entry point
Highest global used
In assembler, you will be started with register Dl holding a BCPL pointer to
the initial packet passed from the kernel.
If you are writing in BCPL, a skeleton routine will appear as follows. The
main job of the device handler is to convert Open, Read, Write, and Close
requests into the device read and write requests. Other packet types are
marked as an error.
"Include files containing useful constants"
GET
GET
GET
GET
"LIBHDR"
"IOHDR"
"MANHDR"
"EXECHDR"
This is a handler for a skeleton Task.
When the task is created, the parameter packet contains the following:
parm.pkt!pkt.argl = BPTR to BCPL string of device name, (i.e., "SKEL:")
parm.pkt!pkt.arg2 = extra info (if needed)
parm.pkt!pkt.arg3 = BPTR to device info node
MANIFEST
$(
IO.blocksize = 30 (size of devices IO blocks)
*)
LET start (parm.pkt) BE
$(
LET extratnfo
= parm.pkt!pkt.arg2
AMIGADOS ADDITIONAL INFORMATION
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
$)
(Copy all the necessary info to the Output buffer too.)
FOR i = 0 TO IO.blocksize DO IOBOli : = I0B!i
outpktlpkt.type : = act.write
inpktlpkt.type : = act.read
nodeldev.task : = taskid()
(Insert process id into device node.)
(Finished with parameter packet . . . send back. . . .)
returnpkt (parm.pkt, TRUE )
(This is the main repeat loop waiting for an event.)
$( LET p = taskwait ( )
SWITCHON plpkt.type INTO
$(
CASE act.fmdinput:
CASE act.findoutput:
$( LET scb = p!pkt.argl
open : = TRUE
scblscbld : = TRUE
returnpkt (p,TRUE)
LOOP
f)
(Open.)
(Interactive.)
AMIGADOS TECHNICAL REFERENCE MANUAL
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.)
$)
$ ) REPEAT/WHILE open I outpkt = 0 I Inpkt = 0
Termination
CloseDevice( IOB )
(Handle an IO request. Passed command, transmission packet (tp) and
request packet (rp). rp contains buffer and length in arg2/3.) AND handle,
request (IOB, command rp, tp ) BE
LET buff = rp!pkt.arg2
LET len = rp!pkt.arg3
SetIO( IOB, command, ?, rp!pkt.arg3, 0 )
putlong ( IOB, IO.data, buff )
SendIO(IOB, tp )
Handle a returning IO request. The user request packet is passed as p, and must
be returned with success/failure message. AND handle.return (IOB, p ) BE
$(
LET errcode = IOB O.error
LET len = getlong( IOB, IO.actual )
AMIGADOS ADDITIONAL INFORMATION
291
TEST errcode = 0 THEN
(No error.)
returnpkt(p, len )
ELSE
returnpkt(p, —1, errcode )
If you wish to write your device handler in C, you cannot use the automatic
load and process creation provided by the kernel. In this case, you must load
the code yourself and use a call to CreateProc to create a process. The result
from this call should be stored in the Task field of the Devlnfo structure. You
must then send a message to the new process to get it started. This message
might contain such things as the unit number of the device involved. The
handler process should then wait for Open, Read, Write, and Close calls and
handle them as described in the example above. C code does not need to insert
the process id into the device node because this is done when code is loaded,
as described above.
Making New Disk Devices
To create a new disk device, you must construct a new device node as
described in Section 3.3.1 of the AmigaDOS
Technical
Reference
Manual.
You
must also write a device driver for the new disk device.
A device driver for a new disk device must mimic the calls that are performed by the trackdisk device (described in the Amiga ROM Kernel Manual). It
must include the ability to respond to commands such as Read, Write, Seek, and
return status information in the same way as described for the trackdisk driver.
For the following description, note that most pointers are of the type BPTR (as
described earlier in the AmigaDOS Technical Reference Manual), a machine pointer
to some long word-aligned memory location (such as returned by AllocMem)
shifted right by two.
Construct the new node with the following fields:
0
0
0
0
0
210
10
BPTR to startup info
Seglist
0
BSTR to name
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
AMIGADOS TECHNICAL REFERENCE MANUAL
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.
AMIGADOS ADDITIONAL INFORMATION
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.
Using AmigaDOS Without
Workbench/Intuition
This information is provided to give developers some information about how
AmigaDOS and Intuition interact with each other. As of this writing, it is not
possible to fully close down Intuition or the input device. It is possible to install
one's own input handler within the input stream (as is demonstrated in the
Amiga ROM Kernel Manual, Input Device description) and thereby handle input
events yourself, after your program has been loaded and started by AmigaDOS.
If, after that point, you take over the machine in some manner, you can
prevent AmigaDOS from trying to put up system requesters or otherwise
interacting with the screen by modifying DOS as shown below. Basically, your
own program must provide alternate ways to handle errors that would normally cause DOS to put up a requester.
Another alternative for taking over the machine is to ignore the AmigaDOS
filing system altogether, and use the trackdisk. device to boot your code and
data on your own. You will find details about the disk boot block and the track
formatting in the Amiga ROM Kernel Manual, allowing this alternate means if
you so choose.
Here are the details about AmigaDOS and Intuition:
AmigaDOS initializes itself and opens Intuition. It then attempts to open the
configuration file (created by Preferences) and passes this to Intuition. It then
opens the initial CLI window via Intuition and attempts to run the first CLI
command. This is commonly a loadwb (load Workbench), followed by an
endcli on the initial CLI.
An application program can be made to behave like Workbench, in that it
spawns a new process. The next CLI command is then endcli, which closes
everything down, leaving only the new process running (along with the
filesystem processes). This process would set the pr WindowPtr field to - 1 ,
which indicates that the DOS should report errors quietly. Note that the
application MUST handle all errors. There are further details on this in Chapter
3. DOS will also have initialized the TrapHandler field of the user task to point
to code that will display a requester after an error; this should be replaced by a
user-provided routine. This will stop all uses of Intuition from the user task,
provided there are no serious memory corruption problems found, in which
case DOS will call Exec Alert directly.
There is still the problem that the filesystem processes may ask for a requester, in the event of a disk error or if the filesystem task crashes due to
294
AMIGADOS TECHNICAL REFERENCE M A N U A L
memory corruption. To stop this, the pr WindowPtr and tc TrapHandler
fields of the filesystem tasks must be set to -1 and a private Trap handler must
be provided in the same way as was done for the user task. This is easily done
as shown below.
Find the message port for each filesystem task by calling DeviceProc(),
passing DFO, DF1, etc. An error indicates that the device is not present. From
the message port you can find the task base for each filesystem task, and hence
patch these two slots. This should be repeated for each disk unit.
The application program can now close Intuition. Workbench has, of course,
never been invoked. Note that as of this writing, it is not possible to stop DOS
from opening Intuition.
Note that if the applications want to use any other device such as SER:, the
handler process must be patched in exactly the same way as the filesystem
processes. The application should obviously not attempt to open the CON: or
RAW: once Intuition has become inactive.
Index
Absolute (symbol), 193
Address, 187
Address modes, 195-196
Address registers, 187
Address variant, 196
ALINK (developer's command), 8 4 - 8 5 ,
168-169, 207, 209-211
Arguments, 6, 50, 119, 152, 153
ASCII literal numbers, 194
ASSEM (developer's command), 85-86
Assembler, 160, 188-189
Assembly control directives, 198-199
Assembly language, 8 5 - 8 6
ASSIGN (user's command), 36-37, 43
ATOM (Alink Temporary Object Modifier),
282-287
Binary file structure, 243-261
Binary numbers, 194
Block control, 9 7 - 9 9
Boolean returns, 171, 175
Boot, 40
Bootable disk. See Disk, bootable
Bracket characters, 59
Branches, 187
BREAK (user's command), 4 3 - 4 4
Break block, 257
C, initial environment in, 160
Calling (AmigaDOS), 170-185
CD (user's command), 44-45
Character pointer, 152
Character string, 152
CLI. See Command Line Interface
Close (call packet), 274
Close function, 171-172
Command definition, 152
Command file structures, 5 9 - 6 2
Command files, 17-18, 136
Command formats, 18-21
Command groups, 121
Command input and output, 18, 31
Command line, 208
Command Line Interface (CLI), 5, 22, 3 7 - 3 8 ,
53, 72-74, 81, 88-89, 152, 159-161, 264-266
Command names, 118-119
Command sequence, 7 8 - 7 9 , 89
Command syntax, 118-121, 209
Command template, 152
Commands, background, 17, 77
Commands, commonly used, 21-22, 2 3 - 2 4
Commands, developer's, 84-88, 89
Commands, execution of, 5, 17-18, 54-63, 77, 183
Commands, extended, 95-96, 103-104
Commands, immediate, 92, 102-103
Commands, recognition of, 6
Commands, repetition of, 95, 101-102, 115
Commands, use of, 16-17
Commands, user's, 40-84, 8 8 - 8 9
Comments, 190, 192
Conditional assembly directives, 203-204
Conditionals, 66
Console handler. See Terminal handler
Control combination, 152
COPY (user's command), 4 5 - 4 6
CopyDir (call packet), 276-277
CreateDir (call packet), 276
CreateDir (function), 172, 276
CreateProc (function), 181, 264, 265
Cross development, 162-169
CTRL-X (control combination), 5 - 6 , 152
Current device, 9-11
Current directory, 8-10, 27, 39, 153, 172
Current drive, 10, 153
Current line, 109-111, 112-113, 122, 125-126,
130-134, 141-142, 153
Current string, 153
CurrentDir (function), 172
Cursor control, 92
Cursor position, 99, 152
Data block, 240, 248
Data definition directives, 200-201
296
INDEX
Data registers, 187
Data structures, 262-278
DATA (user's command), 30, 46-47
Dates, 30, 46-47, 181
DateStamp (function), 181
Debug block, 254
Decimal numbers, 194
Default, 40
Default parameters, 58-59
Delay (function), 182
DELETE (user's command), 4 7 - 4 8
DeleteFile (function), 172-173
DeleteObject (call packet), 276
Delimiter characters, 153
Destination file, 153
Device names, 11-13, 40, 43, 153, 267
DeviceProc (function), 182
Devices, logical. See Logical devices
DIR (user's command), 4 8 - 4 9
Directives, 196-206
Directories, 7-10, 2 7 - 2 8 , 4 3 - 4 5 , 4 7 - 4 8 , 69-72,
153
Directory blocks, 236-237
Directory conventions, 14-16
Directory creation, 34, 172
Directory deletion, 172-173
Directory examination, 173-174
Directory locking, 175-176, 179-180
Directory names, 76, 178
Directory parent, 177
Directory protection, 179
Disk, bootable, 26, 28
Disk copying, 25
Disk, floppy, 65
Disk formatting, 2 5 - 2 6
Disk information, 174
Disk relabeling, 27
DISKCOPY (user's command), 4 9 - 5 0
DISKED (disk editor), 241-242
Diskette assignation, 3 6 - 3 7
Disklnfo (call packet), 275
D O W N L O A D (developer's command), 8 6 - 8 7
Downloading programs, 86-87
DupLock (function), 173, 277
E C H O (user's command), 50-51
ED (user's command), 51-52, 90-104
EDIT (user's command), 52-53
Editing. See Line editor; Screen editor
ENDCLI (user's command), 53
End-of-file handling, 124
Errors, 63, 75, 83-84, 147-152, 161, 175,
211-212, 217
Examine (function), 173, 275
ExamineNext (call packet), 275
ExamineObject (call packet), 2 7 4 - 2 7 5
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
FAILAT (user's command), 6 3 - 6 4
Failures. See Errors
FAULT (user's command), 64
File copy simulation, 5 9 - 6 2
File copying, 33-34
File data, 177, 180
File definition, 153
File deletion, 32, 172-173
File examination, 173
File formation, 68
File handles, 41, 175, 176, 269-270, 273-274
File handling, 171-180
File header block, 238-239
File linking, 84-85
File list block, 2 3 9 - 2 4 0
File location, 34-35
File locking, 175-176, 179-180
File opening, 176
File parent, 177
File protection, 179
File structure, 234, 243-261
File system, 6-16, 2 9 - 3 0 , 67, 234-241
File utilities, 88
Filename, 6-7, 32, 76, 153, 178
FILENOTE (user's command), 11, 64-65
Floppy disk. See Disk, floppy
FORMAT (user's command), 65
FreeLock (call packet), 277
Functions, 171-184
Global data structure, 266-269
Global operations, 139-140
Handler process, 262
Hexadecimal numbers, 194
Hunks, 245, 246-261
Hunk Overlay Table, 280-282
IF (user's command), 66-67
Immediate mode, 91, 153
Info (function), 174, 275
INFO (user's command), 67-68
Info substructure, 267-269
Inhibit (call packet), 278
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
NEWCLI (user's command), 72-73
Node, 245, 257
Null string, 131
Numbers, 194
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
RAM (device), 11-12
READ (developer's command), 87-$$
Read (function), 177
Read call, 273
Rebooting, 35, 41
Register (symbol), 194
Register values, 170
RELABEL (user's command), 75-76
Relative (symbol), 194
Relocation, 2 4 9 - 2 5 0
Rename (function), 178
RENAME (user's command), 76-77
RenameDisk (call packet), 278
RenameObject (call packet), 278
Resident libraries, 158, 170-185, 208, 245, 255
Restart validation process, 21
Root block, 234-235
Root directory, 7, 154
R U N (user's command), 77
Sample looping batch file, 6 2 - 6 3
Scanned library, 208, 245
Screen editor, 51-52, 90-104
Screen output, 221-223
Scrolling, 95
SEARCH (user's command), 77-78
Searching, 77-78, 99-100, 120
Seek (call packet), 274
Seek (function), 178
Segment lists, 269
Sequential files, 154
Serial line, 87
SetComment (call packet), 277
SetComment (function), 179, 277
SetProtect (call packet), 277
SetProtection (function), 179, 277
68000 microchip, 186-187
SKIP (user's command), 78-79
SORT (user's command), 79-80
Source file, 154
STACK (user's command), 80-81
STATUS (user's command), 8 1 - 8 2
Status register, 187
Startup-Sequence (execute file), 35
Storage, 89
Stream, 41
Strings, 119-120, 123, 130-132
Sun (computer), 162-168
Switch values, 120
Symbol definition directives, 199-200
Symbols, 193-194, 205-206, 215-216, 253,
257
Syntax, 118-121, 154, 170-171
INDEX
System disk, 41
System management, 89
Terminal handler, 5 - 6 , 154
Text alteration, 100-101
Text deletion, 94
Text insertion, 92-94, 142
Text string, 77
Textfiles, 31, 51-52
Time, 30, 46-47, 180, 181-182
Trailing spaces, 143
TYPE (user's command), 31, 82
Type commands, 134, 135
UnLoadSeg (option), 184
UnLock (option), 179-180, 277
Values, 171
Virtual terminal, 175
Volume name, 10, 41, 75, 154
WAIT (user's command), 83
WaitChar (call packet), 274
WaitForChar (function), 180, 274
W H Y (user's command), 8 3 - 8 4
Wild card, 7, 154
WITH files, 210-211
Word, 187
Workbench, 2 2 - 2 3 , 161-162
Workspace, uninitialized, 248
Write (function), 180
Write call, 273-274
XREF output, 212