. 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[]

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

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[]

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][[TO]][COLSTART]

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[] 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[][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 [SEC|SECS][MIN|MINS][UNTIL

Template:

WAIT ",SEC = SECS/S,MIN = MINS/S,UNTIL/K"

]

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][,*| + ] [ W I T H < n a m e > ] [ L I B R A R Y | L I B < n a m e > ] ][XREF ][WIDTH

Template:

ALINK

[MAP

]

" 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][-0 ][-V ][-L ]

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

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> (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



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 < =

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)



M o v e cursor u p



M o v e cursor d o w n



M o v e c u r s o r left



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 >

,

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



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/



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




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

[[,[,..]]][[,...]]

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[]

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

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

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

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

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> 3. T o run the program, type 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.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 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

[-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 : []

[[,]...[]

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
SET



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:

[] DC[.]



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:

[] DCB[.]

,

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:

[] DS[.]



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



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



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



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



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:

[] CNOP

,

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 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 , , 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:



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

[,...]

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

[,...]

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

" "

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



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

{




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 : "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 "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: 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

;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

HJ

{ h o m e a n d clear to e n d of screen} or

H23M

{ h o m e a n d delete 23 lines} or

1;1H23L

{ 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 0'

Shifted Sends

2~ 3 4' 5"

12' 13" 14 15"

6" 7'

16" 17'

8~ 9' ?'

18~ 19' < C S I > ? ' (same)

r

_

CSI>10"

ir

_

Arrow keys: Up Down Left Right

A B C D

T' 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:

< subclass > < 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: l;0;;;0;0;;| 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: 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

'

"

01

1

!

02

2

@

03

3

#

04

4

$

05

5

%

06

6

07

7

&

08

8

*

09

9

(

OA

0

)

0B

-



0C

+

0D

\

0E

undefined

|

OF

0

0

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

IE

2

2

IF

3

3

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

undefined

(RESERVED)

2D

4

4

2E

5

5

2F

6

6

30



(RESERVED)

31

Z

z

32

X

33

c

34

c V

V

35

B

b

36

N

n

37

M

m

38




x

. < period >

3B

undefined

3C 3D

7

3E

8

8

3F

9

9

.

40

Space

41

BACKSPACE

42

TAB

43

ENTER

44

RETURN

45

Escape

46

DEL

7

ENTER

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 -

-

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 10~

ir

12' 13~ 14' 15' 16" 17~ 18" 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>

/ 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 [-1] or ATOM [-C[CtDlB]] [-F[CtDB]]

[-P[CIDIB]]

Where: -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