The AmigaDOS Manual

Bantam Computer Books

A s k y o u r bookseller for the b o o k s you have missed

THE AMIGADOS USER'S MANUAL

b y C o m m o d o r e - A m i g a , Inc.
T H E A P P L E //c B O O K
b y Bill O ' B r i e n
T H E C O M M O D O R E 64 S U R V I V A L M A N U A L
b y W i n n L. R o s c h
C O M M O D O R E 128 P R O G R A M M E R ' S R E F E R E N C E G U I D E
b y C o m m o d o r e B u s i n e s s M a c h i n e s , Inc.
E X P L O R I N G A R T I F I C I A L I N T E L L I G E N C E O N Y O U R A P P L E II
b y T i m Hartnell
E X P L O R I N G A R T I F I C I A L I N T E L L I G E N C E O N Y O U R C O M M O D O R E 64
b y T i m Hartnell
EXPLORING THE UNIX ENVIRONMENT
b y T h e Waite G r o u p / Irene Pasternack
FRAMEWORK FROM THE GROUND UP
b y T h e Waite G r o u p / Cynthia Spoor a n d Robert Warren
H O W T O G E T T H E M O S T O U T O F C O M P U S E R V E , 2d e d .
b y Charles B o w e n a n d David P e y t o n
H O W TO GET THE M O S T OUT OF THE SOURCE
b y Charles B o w e n a n d David P e y t o n
THE MACINTOSH
b y Bill O ' B r i e n
T H E N E W jr. A G U I D E T O I B M ' S PC;>
b y W i n n L. R o s c h
ORCHESTRATING SYMPHONY
b y T h e Waite G r o u p / D a n Shafer
PC-DOS / MS-DOS
User's Guide to the Most Popular Operating System for Personal Computers
b y Alan M . B o y d
P O W E R PAINTING: COMPUTER GRAPHICS O N THE MACINTOSH
b y V e r n e B a u m a n a n d Ronald Kidd / illustrated by G a s p e r Vaccaro
SMARTER TELECOMMUNICATIONS
Hands-On Guide to On-Line Computer Services
b y Charles B o w e n a n d Stewart S c h n e i d e r
SWING WITH JAZZ:
Lotus jazz on the Macintosh
b y Data tech Publications C o r p . / Michael McCarty
U S E R ' S G U I D E T O T H E A T & T P C 6300 P E R S O N A L C O M P U T E R
b y David B . Peatroy, Ricardo A. Anzaldua, H . A. W o h l w e n d ,
a n d Data tech Publications C o r p .
The AmigaDOS
Manual
Commodore-Amiga, Inc.

BANTAM BOOKS
TORONTO • NEW YORK • LONDON • SYDNEY • AUCKLAND
 AMIGADOS MANUAL

A Bantam Book I February 1986

Cover design by }. Caroff Associates

All rights reserved.

Copyright © 1986 by Commodore Capital, Inc.
This book may not be reproduced in whole or in part, by
mimeograph or any other means, without permission.
For information address: Bantam Books, Inc.

ISBN 0-553-34294-0

Published simultaneously in the United States and Canada

Bantam Books are published by Bantam Books, Inc. Its trademark, consisting of the
words "Bantam Books" and the portrayal of a rooster, is Registered in U.S. Patent
and Trademark Office and in other countries. Marca Registrada. Bantam Books,
Inc., 666 Fifth Avenue, Nezv York, New York 10103.

P R I N T E D IN T H E U N I T E D S T A T E S O F A M E R I C A

H 0 9 8 7 6 5 4 3 2 1
Contents

The AmigaDOS User's Manual

The AmigaDOS Developer's Manual
The AmigaDOS Technical Reference Manual
Preface

T h i s b o o k , The AmigaDOS Manual, is a c o m b i n a t i o n of three separate publications:

The AmigaDOS User's Manual

The AmigaDOS Developer's Manual
The AmigaDOS Technical Reference Manual

T h e User's Manual c o n t a i n s i n f o r m a t i o n of i n t e r e s t t o e v e r y A m i g a u s e r .
T h e r e are m a n y m o r e c o m m a n d s that A m i g a D O S understands t h a n are acces-
sible f r o m t h e W o r k b e n c h . If a u s e r u s e s P r e f e r e n c e s to t u r n o n t h e C L I , t h e s e
n e w c o m m a n d s b e c o m e accessible.
T h e Developer's Manual describes h o w to use A m i g a D O S from within a
p r o g r a m r a t h e r t h a n f r o m a c o m m a n d line i n t e r f a c e . It a l s o fully d o c u m e n t s
the A m i g a Macro Assembler and Linker. (Note that the A m i g a Macro A s s e m -
b l e r is available a s a s e p a r a t e p r o d u c t . )
T h e Technical Reference Manual d e s c r i b e s t h e d a t a s t r u c t u r e s t h a t A m i g a D O S
u s e s i n t e r n a l l y . It i n c l u d e s d e s c r i p t i o n s of h o w D O S d i s k d a t a is s t o r e d , a n d
t h e f o r m a t of t h e " o b j e c t - f i l e s " t h a t A m i g a D O S u s e s . A d e v e l o p e r o r e x p e r t
u s e r w o u l d f i n d t h e i n f o r m a t i o n i n t h i s t e c h n i c a l s e c t i o n to b e v e r y u s e f u l .
T o g e t h e r these three publications, in this single v o l u m e , comprise the essen-
tial g u i d e t o A m i g a D O S .
AmigaDOS
Manual

Introduction

1. Introducing AmigaDOS
2. AmigaDOS Commands
3. ED—The Screen Editor
4. EDIT—The Line Editor

Appendix: Error Codes and Messages

Glossary
Introduction

T h i s m a n u a l d e s c r i b e s t h e A m i g a D O S a n d its c o m m a n d s . T h e C o m m a n d L i n e
Interpreter (CLI) reads A m i g a D O S c o m m a n d s typed into a CLI w i n d o w a n d
translates t h e m into actions performed b y the computer. In this s e n s e , the CLI
is similar t o m o r e " t r a d i t i o n a l " c o m p u t e r i n t e r f a c e s : y o u t y p e in c o m m a n d s
a n d t h e i n t e r f a c e d i s p l a y s text in r e t u r n .
B e c a u s e t h e W o r k b e n c h i n t e r f a c e is sufficient a n d f r i e n d l y f o r m o s t u s e r s t h e
W o r k b e n c h diskettes are shipped with the CLI interface " d i s a b l e d " . T o u s e the
c o m m a n d s in t h i s m a n u a l y o u m u s t " e n a b l e " t h e C L I i n t e r f a c e . T h i s p u t s a
n e w icon, labeled " C L I " on your Workbench. W h e n you have selected and
o p e n e d t h i s i c o n , a C L I w i n d o w b e c o m e s a v a i l a b l e , a n d y o u c a n u s e it t o i s s u e
text c o m m a n d s directly to A m i g a D O S .

How to Enable the Command Line Interface

Boot your c o m p u t e r using t h e Kickstart a n d W o r k b e n c h diskettes. O p e n the
diskette icon. O p e n the " P r e f e r e n c e s " tool. N e a r the left-hand side of the
s c r e e n , a b o u t t w o - t h i r d s o f t h e w a y d o w n y o u will n o t i c e " C L I " w i t h a b u t t o n
f o r " O N " a n d a b u t t o n for " O F F " . S e l e c t t h e " O N " b u t t o n . S e l e c t "Save"
( l o w e r r i g h t p a r t o f t h e P r e f e r e n c e s s c r e e n ) to l e a v e P r e f e r e n c e s .

How to Open a CLI Window

To use the CLI commands, you open a CLI window. O p e n the " S y s t e m "
d r a w e r . T h e C L I i c o n (a c u b e c o n t a i n i n g " 1 > " ) s h o u l d n o w b e v i s i b l e . O p e n
it.

Using the CLI

T o u s e t h e C L I i n t e r f a c e select t h e C L I w i n d o w a n d t y p e t h e d e s i r e d C L I
c o m m a n d s . T h e C L I w i n d o w ( s ) m a y b e s i z e d a n d m o v e d j u s t like m o s t o t h e r s .
To close the CLI w i n d o w , type " E N D C L I " .
 INTRODUCTION 3

Workbench and CLI, Their Relationship and Differences

T y p e " D I R " to d i s p l a y a list of files ( a n d d i r e c t o r i e s ) in t h e c u r r e n t d i s k
d i r e c t o r y . T h i s is a list of files t h a t m a k e s u p y o u r W o r k b e n c h . Y o u m a y n o t i c e
t h a t t h e r e are m o r e files in this d i r e c t o r y t h a n t h e r e a r e i c o n s o n t h e W o r k -
b e n c h . W o r k b e n c h o n l y d i s p l a y s file " X " if t h a t file h a s a n a s s o c i a t e d " X . i n f o "
file. W o r k b e n c h u s e s t h e " . i n f o " file to m a n i p u l a t e t h e i c o n .
F o r e x a m p l e , t h e d i s k c o p y p r o g r a m h a s t w o files. T h e file " D i s k c o p y " c o n -
tains the p r o g r a m a n d " D i s k c o p y . i n f o " contains the W o r k b e n c h information
a b o u t it. I n t h e c a s e of p a i n t i n g d a t a files like " m o u n t . p i c " t h e file " m o u n t . p i c . -
i n f o " c o n t a i n s i c o n i n f o r m a t i o n a n d t h e n a m e of t h e p r o g r a m (default) t h a t
s h o u l d p r o c e s s it ( G r a p h i C r a f t ) . I n this c a s e , w h e n t h e u s e r " o p e n s " t h e d a t a
file ( m o u n t . p i c ) W o r k b e n c h r u n s t h e p r o g r a m a n d p a s s e s t h e d a t a file n a m e
( m o u n t . p i c ) t o it.
A m i g a D O S s u b d i r e c t o r i e s c o r r e s p o n d to W o r k b e n c h d r a w e r s . R a n d o m a c -
c e s s b l o c k d e v i c e s s u c h as d i s k s (DFO:) c o r r e s p o n d t o t h e d i s k e t t e i c o n s y o u
have seen.
N o t all p r o g r a m s or c o m m a n d s c a n b e r u n u n d e r b o t h W o r k b e n c h a n d t h e
C L I e n v i r o n m e n t . N o n e of t h e C L I c o m m a n d s d e s c r i b e d in C h a p t e r 2 of t h i s
m a n u a l can b e run from W o r k b e n c h . For example, there are t w o separate
D i s k c o p y c o m m a n d s . T h e o n e i n t h e :cl d i r e c t o r y is r u n f r o m A m i g a D O S ( C L I ) .
T h e o n e in t h e s y s t e m d i r e c t o r y ( d r a w e r ) is r u n f r o m W o r k b e n c h .
Chapter 1
Introducing AmigaDOS

T h i s c h a p t e r p r o v i d e s a g e n e r a l o v e r v i e w of t h e A m i g a D O S o p e r a t i n g s y s t e m ,
i n c l u d i n g d e s c r i p t i o n s of t e r m i n a l h a n d l i n g , t h e d i r e c t o r y s t r u c t u r e , a n d c o m -
m a n d u s e . A t t h e e n d of t h e c h a p t e r , y o u ' l l f i n d a s i m p l e e x a m p l e s e s s i o n w i t h
AmigaDOS

1.1 Chapter Overview /

1.2 Terminal Handling
1.3 U s i n g t h e Filing S y s t e m
1.3.1 N a m i n g Files
1.3.2 Using Directories
1.3.3 Setting the Current Directory
1.3.4 Setting the Current Device
1.3.5 Attaching a Filenote
1.3.6 Understanding Device N a m e s
1.3.7 Using Directory Conventions and Logical Devices
1.4 Using AmigaDOS Commands
1.4.1 R u n n i n g C o m m a n d s in the Background
1.4.2 Executing C o m m a n d Files
1.4.3 Directing C o m m a n d Input and Output
1.4.4 Interrupting A m i g a D O S
1.4.5 Understanding Command Formats
1.5 Restart Validation Process
1.6 Commonly Used Commands: A n Example Session
1.7 Conventions Used

1.1 Chapter Overview

A m i g a D O S is a m u l t i - p r o c e s s i n g o p e r a t i n g s y s t e m d e s i g n e d f o r t h e A m i g a .
A l t h o u g h y o u c a n u s e it a s a m u l t i - u s e r s y s t e m , y o u n o r m a l l y r u n A m i g a D O S
f o r a s i n g l e u s e r . T h e m u l t i - p r o c e s s i n g facility lets m a n y j o b s t a k e p l a c e s i m u l -
 INTRODUCING AMIGADOS 5

t a n e o u s l y . Y o u c a n also u s e t h e m u l t i - p r o c e s s i n g facility to s u s p e n d o n e j o b
while you run another.
E a c h A m i g a D O S p r o c e s s r e p r e s e n t s a p a r t i c u l a r p r o c e s s of t h e o p e r a t i n g
s y s t e m — f o r e x a m p l e , t h e filing s y s t e m . O n l y o n e p r o c e s s is r u n n i n g at a t i m e ,
w h i l e o t h e r p r o c e s s e s a r e e i t h e r w a i t i n g for s o m e t h i n g t o h a p p e n or h a v e b e e n
i n t e r r u p t e d a n d a r e w a i t i n g to b e r e s u m e d . E a c h p r o c e s s h a s a p r i o r i t y a s s o c i -
a t e d w i t h it, a n d t h e p r o c e s s w i t h t h e h i g h e s t priority t h a t is f r e e to r u n d o e s
so. Processes of l o w e r priority r u n only w h e n those of h i g h e r priority are
w a i t i n g f o r s o m e r e a s o n — f o r e x a m p l e , w a i t i n g for i n f o r m a t i o n to arrive f r o m
the disk.
T h e s t a n d a r d A m i g a D O S s y s t e m u s e s a n u m b e r of p r o c e s s e s t h a t a r e n o t
available t o y o u , f o r e x a m p l e , t h e p r o c e s s t h a t h a n d l e s t h e serial l i n e . T h e s e
processes are k n o w n as private processes. O t h e r private processes h a n d l e the
t e r m i n a l a n d t h e filing s y s t e m o n a d i s k d r i v e . If t h e h a r d w a r e c o n f i g u r a t i o n
c o n t a i n s m o r e t h a n o n e d i s k d r i v e , t h e r e is a p r o c e s s for e a c h d r i v e .
A m i g a D O S p r o v i d e s a p r o c e s s t h a t y o u c a n u s e , called a C o m m a n d L i n e
I n t e r f a c e or C L I . T h e r e m a y b e s e v e r a l C L I p r o c e s s e s r u n n i n g s i m u l t a n e o u s l y ,
numbered from 1 onward. The CLI processes read commands and then
e x e c u t e t h e m . All c o m m a n d s a n d u s e r p r o g r a m s will r u n u n d e r a n y C L I . T o
m a k e additional CLI processes, you use the N E W C L I or R U N c o m m a n d s . T o
r e m o v e a C L I p r o c e s s u s e t h e E N D C L I c o m m a n d . ( Y o u c a n f i n d a full d e s c r i p -
t i o n of t h e s e c o m m a n d s i n C h a p t e r 2 of this m a n u a l . )

1.2 Terminal Handling

Y o u c a n d i r e c t i n f o r m a t i o n t h a t y o u e n t e r at t h e t e r m i n a l t o a C o m m a n d L i n e
I n t e r f a c e ( C L I ) t h a t tells A m i g a D O S to l o a d a p r o g r a m , o r y o u c a n d i r e c t t h e
i n f o r m a t i o n to a p r o g r a m r u n n i n g u n d e r t h a t C L I . In e i t h e r c a s e , a t e r m i n a l (or
console) handler processes input and output. This terminal handler also per-
f o r m s local line e d i t i n g a n d c e r t a i n o t h e r f u n c t i o n s . Y o u c a n t y p e a h e a d a s
m a n y as 2 5 5 c h a r a c t e r s — t h e m a x i m u m line l e n g t h .
T o c o r r e c t m i s t a k e s , y o u p r e s s t h e B A C K S P A C E k e y . T h i s e r a s e s t h e last
character y o u typed. To rub out an entire line, hold d o w n the C T R L key while
y o u p r e s s X . T h i s control c o m b i n a t i o n is r e f e r r e d t o f r o m t h i s p o i n t o n in t h e
manual as CTRL-X.
If y o u t y p e a n y t h i n g , A m i g a D O S w a i t s until y o u h a v e f i n i s h e d t y p i n g b e f o r e
d i s p l a y i n g a n y o t h e r o u t p u t . B e c a u s e A m i g a D O S w a i t s f o r y o u to f i n i s h , y o u
can type ahead without your input and output becoming intermixed. A m i g a D O S
r e c o g n i z e s t h a t y o u h a v e f i n i s h e d a line w h e n y o u p r e s s t h e R E T U R N k e y . Y o u
c a n also tell A m i g a D O S t h a t y o u h a v e f i n i s h e d w i t h a line b y c a n c e l l i n g it. T o
c a n c e l a l i n e , y o u c a n e i t h e r p r e s s C T R L - X or p r e s s B A C K S P A C E u n t i l all t h e
c h a r a c t e r s o n t h e line h a v e b e e n e r a s e d . O n c e A m i g a D O S is s a t i s f i e d t h a t y o u
6 AMIGADOS USER'S MANUAL

h a v e f i n i s h e d , it s t a r t s to d i s p l a y t h e o u t p u t t h a t it w a s h o l d i n g b a c k . If y o u
w i s h to s t o p t h e o u t p u t s o t h a t y o u c a n r e a d it, s i m p l y t y p e a n y c h a r a c t e r
( p r e s s i n g t h e s p a c e b a r is t h e e a s i e s t ) , a n d t h e o u t p u t s t o p s . T o r e s t a r t o u t p u t ,
p r e s s B A C K S P A C E , C T R L - X , or R E T U R N . P r e s s i n g R E T U R N c a u s e s A m i g a D O S
to try t o e x e c u t e t h e c o m m a n d line t y p e d a f t e r t h e c u r r e n t p r o g r a m e x i t s .
A m i g a D O S recognizes CTRLA as an end-of-file indicator. In certain circum-
s t a n c e s , y o u u s e t h i s c o m b i n a t i o n to t e r m i n a t e a n i n p u t file. ( F o r a c i r c u m -
stance w h e n you would use CTRLA, see Section 1.3.6.)
If y o u f i n d t h a t s t r a n g e c h a r a c t e r s a p p e a r o n t h e s c r e e n w h e n y o u t y p e
anything on the keyboard, you have probably pressed C T R L - O by mistake.
A m i g a D O S r e c o g n i z e s this c o n t r o l c o m b i n a t i o n as a n i n s t r u c t i o n to t h e c o n s o l e
d e v i c e ( C O N : ) to d i s p l a y t h e a l t e r n a t i v e c h a r a c t e r set. T o u n d o t h i s c o n d i t i o n ,
you press C T R L - N . A n y further characters should then appear as normal. O n
t h e o t h e r h a n d , y o u c o u l d p r e s s E S C - C t o clear t h e s c r e e n a n d d i s p l a y n o r m a l
text.
Note: A n y input through the console device C O N : ignores function keys a n d
c u r s o r k e y s . If y o u w a n t t o r e c e i v e t h e s e k e y s , y o u s h o u l d u s e R A W : . ( F o r a
d e s c r i p t i o n of R A W : , s e e S e c t i o n 1 . 3 . 6 , " U n d e r s t a n d i n g D e v i c e N a m e s , " l a t e r
in t h i s c h a p t e r . )
F i n a l l y , A m i g a D O S r e c o g n i z e s all c o m m a n d s a n d a r g u m e n t s t y p e d in e i t h e r
u p p e r or lower case. A m i g a D O S displays a filename with the characters in the
c a s e u s e d w h e n it w a s c r e a t e d , b u t f i n d s t h e file n o m a t t e r w h a t c o m b i n a t i o n o f
c a s e s y o u u s e to s p e c i f y t h e f i l e n a m e .

1.3 Using the Filing System

T h i s s e c t i o n d e s c r i b e s t h e A m i g a D O S filing s y s t e m . In p a r t i c u l a r , it e x p l a i n s
h o w to n a m e , o r g a n i z e , a n d recall y o u r files.
A file is t h e s m a l l e s t n a m e d o b j e c t u s e d b y A m i g a D O S . T h e s i m p l e s t identifi-
c a t i o n of a file is b y its f i l e n a m e , d i s c u s s e d b e l o w i n S e c t i o n 1 . 3 . 1 . H o w e v e r , it
m a y b e n e c e s s a r y t o i d e n t i f y a file m o r e fully. S u c h a n i d e n t i f i c a t i o n m a y
i n c l u d e t h e d e v i c e or v o l u m e n a m e , a n d / o r d i r e c t o r y n a m e ( s ) a s w e l l a s t h e
f i l e n a m e . T h e s e will b e d i s c u s s e d i n f o l l o w i n g s e c t i o n s .

1.3.1 Naming Files

A m i g a D O S h o l d s i n f o r m a t i o n o n d i s k s i n a n u m b e r of files, n a m e d s o t h a t y o u
c a n i d e n t i f y a n d recall t h e m . T h e filing s y s t e m a l l o w s f i l e n a m e s to h a v e u p t o
thirty characters, w h e r e the characters m a y be any printing character except
s l a s h (/) a n d c o l o n (:). T h i s m e a n s t h a t y o u c a n i n c l u d e s p a c e ( ) , e q u a l s ( = ) ,
p l u s ( + ) , a n d d o u b l e q u o t e ( " ) , all s p e c i a l c h a r a c t e r s r e c o g n i z e d b y t h e C L I ,
w i t h i n a f i l e n a m e . H o w e v e r , if y o u u s e t h e s e special c h a r a c t e r s , y o u m u s t
 INTRODUCING AMIGADOS 7

enclose the entire filename with double quotes. To introduce a double quote
c h a r a c t e r w i t h i n a f i l e n a m e , y o u m u s t t y p e a n a s t e r i s k (*) i m m e d i a t e l y b e f o r e
that character. In addition, to introduce a n asterisk, y o u m u s t type another
a s t e r i s k . T h i s m e a n s that a file n a m e d

A*B = C"

s h o u l d b e t y p e d as f o l l o w s :

i n o r d e r f o r t h e C L I to a c c e p t it.
N o t e : T h i s u s e of t h e a s t e r i s k is in c o n t r a s t t o m a n y o t h e r o p e r a t i n g s y s t e m s
w h e r e it is u s e d a s a u n i v e r s a l w i l d c a r d . A n a s t e r i s k b y itself in A m i g a D O S
represents the keyboard and the current window. For example,

COPY f i l e n a m e to *

c o p i e s t h e f i l e n a m e to t h e s c r e e n .
A v o i d s p a c e s b e f o r e or after f i l e n a m e s b e c a u s e t h e y m a y c a u s e c o n f u s i o n .

1.3.2 Using Directories

T h e filing s y s t e m also a l l o w s t h e u s e of d i r e c t o r i e s as a w a y t o g r o u p files
t o g e t h e r i n t o logical u n i t s . F o r e x a m p l e , y o u m a y u s e t w o d i f f e r e n t d i r e c t o r i e s
to s e p a r a t e p r o g r a m s o u r c e f r o m p r o g r a m d o c u m e n t a t i o n , o r t o k e e p files
b e l o n g i n g t o o n e p e r s o n distinct f r o m t h o s e b e l o n g i n g t o a n o t h e r .
E a c h file o n a d i s k m u s t b e l o n g to a d i r e c t o r y . A n e m p t y d i s k c o n t a i n s o n e
d i r e c t o r y , called t h e root d i r e c t o r y . If y o u c r e a t e a file o n a n e m p t y d i s k , t h e n
t h a t file b e l o n g s t o t h i s r o o t d i r e c t o r y . H o w e v e r , d i r e c t o r i e s m a y t h e m s e l v e s
c o n t a i n f u r t h e r d i r e c t o r i e s . E a c h d i r e c t o r y m a y t h e r e f o r e c o n t a i n f i l e s , or y e t
m o r e d i r e c t o r i e s , or a m i x t u r e of b o t h . A n y f i l e n a m e is u n i q u e o n l y w i t h i n t h e
d i r e c t o r y it b e l o n g s t o , s o t h a t t h e file " f r e d " i n t h e d i r e c t o r y " b i l l " is a c o m -
p l e t e l y d i f f e r e n t file f r o m t h e o n e called " f r e d " i n t h e d i r e c t o r y " m a r y " .
T h i s filing s t r u c t u r e m e a n s t h a t t w o p e o p l e s h a r i n g a d i s k d o n o t h a v e to
w o r r y a b o u t a c c i d e n t a l l y o v e r w r i t i n g files c r e a t e d b y s o m e o n e e l s e , as l o n g as
t h e y a l w a y s c r e a t e files i n t h e i r o w n d i r e c t o r i e s .

W A R N I N G : W h e n y o u c r e a t e a file w i t h a f i l e n a m e t h a t a l r e a d y e x i s t s ,
A m i g a D O S d e l e t e s t h e p r e v i o u s c o n t e n t s of t h a t file. N o m e s s a g e to t h a t
effect appears o n the screen.
8 AMIGADOS USER'S M A N U A L

Y o u c a n a l s o u s e this d i r e c t o r y s t r u c t u r e to o r g a n i z e i n f o r m a t i o n o n t h e d i s k ,
k e e p i n g d i f f e r e n t sorts of files in d i f f e r e n t d i r e c t o r i e s .
A n e x a m p l e m i g h t h e l p to clarify t h i s . C o n s i d e r a d i s k t h a t c o n t a i n s t w o
d i r e c t o r i e s , called " b i l l " a n d " m a r y . " T h e d i r e c t o r y " b i l l " c o n t a i n s t w o files,
called " t e x t " a n d " l e t t e r " . T h e d i r e c t o r y " m a r y " c o n t a i n s a file c a l l e d " d a t a "
a n d t w o d i r e c t o r i e s called " l e t t e r " a n d " i n v o i c e " . T h e s e s u b - d i r e c t o r i e s e a c h
c o n t a i n a file called " j u n l 8 " . F i g u r e 1-A r e p r e s e n t s t h i s s t r u c t u r e a s f o l l o w s :

ROOT

BILL MARY

TEXT LETTER DATA LETTER HSTVOICE

I I
JLTN18 JTTJ5U8
Figure 1-A: Using Directory Structure

N o t e : T h e d i r e c t o r y " b i l l " h a s a file c a l l e d " l e t t e r , " w h i l e t h e d i r e c t o r y

" m a r y " c o n t a i n s a d i r e c t o r y called " l e t t e r " . H o w e v e r , t h e r e is n o c o n f u s i o n
h e r e b e c a u s e b o t h files a r e in d i f f e r e n t d i r e c t o r i e s . T h e r e is n o limit to t h e
depth that y o u can " n e s t " directories.
T o s p e c i f y a file fully, y o u m u s t i n c l u d e t h e d i r e c t o r y t h a t o w n s it, t h e
d i r e c t o r y o w n i n g t h a t d i r e c t o r y , a n d s o o n . T o s p e c i f y a file, y o u give t h e
n a m e s of all t h e d i r e c t o r i e s o n t h e p a t h to t h e d e s i r e d file. T o s e p a r a t e e a c h
directory n a m e from the next directory or filename, y o u type a following slash
(/). T h u s , t h e full s p e c i f i c a t i o n o f t h e d a t a files o n t h e d i s k s h o w n in F i g u r e 1-A
a b o v e is as f o l l o w s :

bill/text
bill/letter
mary/data
mary/letter/junl8
mary/lnvoice/junl 8

1.3.3 Setting the Current Directory

A full file d e s c r i p t i o n c a n g e t e x t r e m e l y c u m b e r s o m e to t y p e , s o t h e filing
s y s t e m m a i n t a i n s t h e i d e a of a c u r r e n t d i r e c t o r y . T h e filing s y s t e m s e a r c h e s f o r
files i n t h i s c u r r e n t d i r e c t o r y . T o s p e c i f y t h e c u r r e n t d i r e c t o r y , y o u u s e t h e C D
( C u r r e n t D i r e c t o r y ) c o m m a n d . If y o u h a v e s e t " m a r y " a s y o u r c u r r e n t d i r e c t o r y ,
t h e n t h e f o l l o w i n g n a m e s w o u l d b e sufficient to specify t h e files in that d i r e c t o r y :
 INTRODUCING AMIGADOS 9

data
Ietter7juiil8
invoice/junl8

Y o u c a n s e t a n y d i r e c t o r y a s t h e c u r r e n t d i r e c t o r y . T o s p e c i f y a n y files w i t h i n
t h a t d i r e c t o r y , s i m p l y t y p e t h e n a m e of t h e file. T o s p e c i f y files w i t h i n s u b -
d i r e c t o r i e s , y o u n e e d t o t y p e t h e n a m e s of t h e d i r e c t o r i e s o n t h e p a t h f r o m t h e
current directory specified.
All t h e files o n t h e d i s k a r e still available e v e n t h o u g h y o u ' v e s e t u p a c u r r e n t
d i r e c t o r y . To_ i n s t r u c t A m i g a D O S to s e a r c h t h r o u g h t h e d i r e c t o r i e s f r o m t h e
r o o t d i r e c t o r y , y o u t y p e a c o l o n (:) at t h e b e g i n n i n g of t h e file d e s c r i p t i o n .
T h u s , w h e n y o u r file d e s c r i p t i o n h a s t h e c u r r e n t d i r e c t o r y s e t t o " m a r y " , y o u
c a n a l s o o b t a i n t h e file " d a t a " b y t y p i n g t h e d e s c r i p t i o n " : m a r y / d a t a " . U s i n g t h e
c u r r e n t d i r e c t o r y m e t h o d s i m p l y s a v e s t y p i n g , b e c a u s e all y o u h a v e t o d o i s
specify the filename " d a t a " .
T o o b t a i n t h e o t h e r files o n t h e d i s k , first t y p e " : b i l l / t e x t " a n d " : b i l l / l e t t e r "
r e s p e c t i v e l y . A n o t h e r w a y m i g h t b e t o C D or t y p e / b e f o r e a f i l e n a m e . S l a s h
d o e s n o t m e a n " r o o t " a s i n s o m e s y s t e m s , b u t r e f e r s to t h e d i r e c t o r y a b o v e t h e
c u r r e n t d i r e c t o r y . A m i g a D O S a l l o w s m u l t i p l e s l a s h e s . E a c h s l a s h r e f e r s to t h e
level a b o v e . S o a U n i x ( T M ) ../ is a / in A m i g a D O S . S i m i l a r l y , a n M S - D O S ™
.A is a / i n A m i g a D O S . t h u s , if t h e c u r r e n t d i r e c t o r y is " : m a r y / l e t t e r " , y o u m a y
s p e c i f y t h e file " : m a r y / i n v o i c e / j u n l 8 " a s " / i n v o i c e / j u n l 8 " . T o r e f e r to t h e files
in " : b i l l " , y o u c o u l d t y p e :

CD .-bill

or

CD //bill

T h e n y o u c o u l d s p e c i f y a n y file i n " b i l l " w i t h a s i n g l e f i l e n a m e . O f c o u r s e , y o u

c o u l d a l w a y s u s e t h e // f e a t u r e to r e f e r directly to a specific file. F o r e x a m p l e ,

T Y P E //bill/letter

d i s p l a y s t h e file w i t h o u t y o u r first s e t t i n g " b i l l " a s t h e c u r r e n t d i r e c t o r y . T o g o

s t r a i g h t t o t h e r o o t l e v e l , a l w a y s t y p e a c o l o n (:) f o l l o w e d b y a d i r e c t o r y n a m e . If
y o u use slashes, y o u m u s t k n o w the exact n u m b e r of levels back desired.

2.3.4 Setting the Current Device

Finally, y o u m a y h a v e m a n y disk drives available. E a c h disk device h a s a
n a m e , i n t h e f o r m D F n (for e x a m p l e , D F 1 ) , w h e r e t h e " n " r e f e r s t o t h e n u m b e r
o f t h e d e v i c e . ( C u r r e n t l y , A m i g a D O S a c c e p t s t h e d e v i c e n a m e s DFO t o D F 3 . )
10 AMIGADOS USER'S MANUAL

E a c h i n d i v i d u a l d i s k is also a s s o c i a t e d w i t h a u n i q u e n a m e , k n o w n a s a v o l u m e
n a m e (see b e l o w for m o r e details).
In a d d i t i o n , t h e logical d e v i c e S Y S : is a s s i g n e d to t h e d i s k y o u s t a r t e d t h e
s y s t e m u p f r o m . Y o u c a n u s e this n a m e i n p l a c e of a d i s k d e v i c e n a m e (like
DFO:).
T h e c u r r e n t d i r e c t o r y is also a s s o c i a t e d w i t h a c u r r e n t d r i v e , t h e d r i v e w h e r e
y o u m a y f i n d t h e d i r e c t o r y . A s y o u k n o w , p r e f a c i n g a file d e s c r i p t i o n w i t h a
c o l o n s e r v e s to i d e n t i f y t h e r o o t d i r e c t o r y of t h e c u r r e n t d r i v e . H o w e v e r , t o
g i v e t h e r o o t d i r e c t o r y of a specific d r i v e , y o u p r e c e d e t h e c o l o n w i t h t h e d r i v e
n a m e . T h u s , y o u h a v e y e t a n o t h e r w a y of s p e c i f y i n g t h e file " d a t a " in d i r e c t o r y
" m a r y " , t h a t is " D F l : m a r y / d a t a " . T h i s a s s u m e s t h a t y o u h a v e i n s e r t e d t h e d i s k
i n t o d r i v e D F 1 . S o , to r e f e r e n c e a file o n t h e d r i v e DFO called " p r o j e c t - r e p o r t " in
directory " p e t e r " , you would type "DFO:peter/project-report", no matter which
d i r e c t o r y y o u h a d s e t as t h e c u r r e n t o n e .
N o t e : W h e n y o u r e f e r to a d i s k drive or a n y o t h e r d e v i c e , o n its o w n o r w i t h
a directory n a m e , y o u should always type the colon, for e x a m p l e , D F 1 : .
F i g u r e 1-B illustrates t h e s t r u c t u r e of a file d e s c r i p t i o n . F i g u r e 1-C g i v e s s o m e
e x a m p l e s o f v a l i d file d e s c r i p t i o n s .

Left o f t h e : R i g h t of t h e : R i g h t o f a/

Device name Directory n a m e Subdirectory n a m e

or or or

Volume name Filename Filename

Figure 1-B: The Structure of a File Description

SYS c o m m a n d s
DFO:bill
DFLmary/letter
DF2:mary/letter/junl8
DOC:report/sectionl/figures
FOMTS:smy-font
C:cls

Figure 1-C: Examples of File Descriptions

T o g a i n a c c e s s t o a file o n a p a r t i c u l a r d i s k , y o u c a n t y p e its u n i q u e n a m e ,
w h i c h is k n o w n a s t h e d i s k ' s v o l u m e n a m e , i n s t e a d of t h e d e v i c e n a m e . F o r
i n s t a n c e , if t h e file is o n t h e d i s k " M C C " , y o u c a n s p e c i f y t h e s a m e file b y
typing the n a m e " M C G p e t e r / p r o j e c t - r e p o r t " . Y o u can use the v o l u m e n a m e to
r e f e r to a d i s k r e g a r d l e s s of t h e drive it is i n . Y o u a s s i g n a v o l u m e n a m e to a
d i s k w h e n y o u f o r m a t it (for f u r t h e r d e t a i l s , s e e " F O R M A T " in C h a p t e r 2 ,
" C o m m a n d s , " later in t h i s m a n u a l ) .
 INTRODUCING AMIGADOS 11

A d e v i c e n a m e , u n l i k e a v o l u m e n a m e , is n o t really p a r t of t h e n a m e . F o r
e x a m p l e , A m i g a D O S c a n r e a d a file y o u c r e a t e d o n DFO: f r o m a n o t h e r d r i v e ,
s u c h a s D F 1 : , if y o u p l a c e t h e d i s k in t h a t d r i v e , a s s u m i n g of c o u r s e t h a t t h e
d r i v e s a r e i n t e r c h a n g e a b l e . T h a t i s , if y o u c r e a t e a file called " b i l l " o n a d i s k in
d r i v e DFO:, t h e file is k n o w n a s " D F O . b i l l " . If y o u t h e n m o v e t h e d i s k t o d r i v e
D F 1 : , A m i g a D O S c a n still r e a d t h e file, w h i c h is t h e n k n o w n a s " D F l : b i l l " .

1.3.5 Attaching a Filenote

A l t h o u g h a f i l e n a m e c a n g i v e s o m e i n f o r m a t i o n a b o u t its c o n t e n t s , it is o f t e n
n e c e s s a r y t o l o o k in t h e file itself t o f i n d o u t m o r e . A m i g a D O S p r o v i d e s a
s i m p l e s o l u t i o n t o this p r o b l e m . Y o u c a n u s e t h e c o m m a n d c a l l e d F I L E N O T E
to attach a n associated c o m m e n t . Y o u can m a k e u p a c o m m e n t of u p to 80
c h a r a c t e r s ( y o u m u s t e n c l o s e c o m m e n t s c o n t a i n i n g s p a c e s in d o u b l e q u o t e s ) .
A n y t h i n g c a n b e p u t in a file c o m m e n t : t h e d a y of t h e file's c r e a t i o n , w h e t h e r
or n o t a b u g h a s b e e n f i x e d , t h e v e r s i o n n u m b e r of a p r o g r a m , a n d a n y t h i n g
e l s e t h a t m a y h e l p t o i d e n t i f y it.
Y o u m u s t a s s o c i a t e a c o m m e n t w i t h a p a r t i c u l a r f i l e — n o t all files h a v e t h e m .
T o a t t a c h c o m m e n t s , y o u u s e t h e F I L E N O T E c o m m a n d . If y o u c r e a t e a n e w
file, it will n o t h a v e a c o m m e n t . E v e n if t h e n e w file is a c o p y of a file t h a t h a s a
c o m m e n t , t h e c o m m e n t is n o t c o p i e d t o t h e n e w file. H o w e v e r , a n y c o m m e n t
a t t a c h e d to a file w h i c h is o v e r w r i t t e n is r e t a i n e d . T o w r i t e a p r o g r a m t o c o p y a
file a n d its c o m m e n t , y o u ' l l h a v e to d o s o m e e x t r a w o r k to c o p y t h e c o m m e n t .
F o r d e t a i l s , s e e C h a p t e r 2 of t h e AmigaDOS Developer's Manual.
W h e n y o u r e n a m e a file, t h e c o m m e n t a s s o c i a t e d w i t h it d o e s n ' t c h a n g e . T h e
R E N A M E c o m m a n d o n l y c h a n g e s t h e n a m e o f a file. T h e file's c o n t e n t s a n d
c o m m e n t r e m a i n t h e s a m e r e g a r d l e s s of t h e n a m e c h a n g e . F o r m o r e d e t a i l s ,
s e e L I S T a n d F I L E N O T E in C h a p t e r 2 of t h i s m a n u a l .

2.3.6 Understanding Device Names

D e v i c e s h a v e n a m e s s o t h a t y o u c a n r e f e r to t h e m b y n a m e . D i s k n a m e s s u c h
a s DFO: a r e e x a m p l e s of d e v i c e n a m e s . N o t e t h a t y o u m a y r e f e r t o d e v i c e
n a m e s , like f i l e n a m e s , u s i n g e i t h e r u p p e r o r l o w e r c a s e . F o r d i s k s , y o u f o l l o w
t h e d e v i c e n a m e b y a f i l e n a m e b e c a u s e A m i g a D O S s u p p o r t s files o n t h e s e
devices. Furthermore, the filename can include directories because A m i g a D O S
also supports directories.
Y o u c a n also c r e a t e files in m e m o r y w i t h t h e d e v i c e c a l l e d R A M : . RAM:
i m p l e m e n t s a filing s y s t e m i n m e m o r y t h a t s u p p o r t s a n y o f t h e n o r m a l filing
system commands.
N o t e : R A M : r e q u i r e s t h e library 1 / r a m - h a n d l e r to b e o n t h e d i s k .
O n c e the device R A M : exists, you can, for instance, create a directory to
c o p y all t h e c o m m a n d s i n t o m e m o r y . T o d o t h i s , t y p e t h e f o l l o w i n g c o m m a n d s :
 12 AMIGADOS USER'S MANUAL

MAKEDIR ram:c
COPY s y s : c TO r a m : c
A S S I G N C: R A M : C

Y o u c o u l d t h e n l o o k at t h e o u t p u t w i t h D I R R A M : . It w o u l d i n c l u d e t h e
d i r e c t o r y " c " ( D I R lists t h i s as c(dir).) T h i s w o u l d m a k e l o a d i n g c o m m a n d s v e r y
q u i c k b u t w o u l d l e a v e little r o o m in m e m o r y for a n y t h i n g e l s e . A n y files in t h e
R A M : d e v i c e a r e lost w h e n y o u reset the machine.
A m i g a D O S a l s o p r o v i d e s a n u m b e r of o t h e r d e v i c e s t h a t y o u c a n u s e i n s t e a d
of a r e f e r e n c e to a d i s k file. T h e f o l l o w i n g p a r a g r a p h s d e s c r i b e t h e s e d e v i c e s
i n c l u d i n g N I L : , S E R : , P A R : , P R T : , C O N : , a n d R A W : . In p a r t i c u l a r , t h e d e v i c e
N I L : is. a d u m m y device. A m i g a D O S simply throws away output written to
NIL:. While reading from NIL:, A m i g a D O S gives an immediate "end-of-file"
indication. For example, you would type the following

E D I T a b c TO n i l :

t o u s e t h e e d i t o r to b r o w s e t h r o u g h a file, w h i l e A m i g a D O S t h r o w s a w a y t h e
edited output.
Y o u u s e t h e d e v i c e called S E R : to r e f e r to a n y d e v i c e c o n n e c t e d t o t h e serial
line ( o f t e n a p r i n t e r ) . T h u s , y o u w o u l d t y p e t h e f o l l o w i n g c o m m a n d s e q u e n c e :

C O P Y x y z TO s e r :

t o i n s t r u c t A m i g a D O S t o s e n d t h e c o n t e n t s of t h e file " x y z " d o w n t h e serial l i n e .

N o t e t h a t t h e serial d e v i c e o n l y c o p i e s in m u l t i p l e s of 4 0 0 b y t e s at a t i m e .
Copying with SER: can therefore appear granular.
T h e d e v i c e P A R : r e f e r s to t h e p a r a l l e l p o r t i n t h e s a m e w a y .
A m i g a D O S a l s o p r o v i d e s t h e d e v i c e P R T : (for P R i n T e r ) . P R T : is t h e p r i n t e r
y o u chose in the " p r e f e r e n c e s " program. In this program, y o u can define your
p r i n t e r t o b e c o n n e c t e d t h r o u g h e i t h e r t h e serial o r p a r a l l e l p o r t . T h u s , t h e
command sequence

C O P Y xyz T O PRT:

p r i n t s t h e file " x y z , " n o m a t t e r h o w t h e p r i n t e r is c o n n e c t e d .

P R T : t r a n s l a t e s e v e r y l i n e f e e d c h a r a c t e r i n a file to c a r r i a g e r e t u r n p l u s
l i n e f e e d . S o m e p r i n t e r s , h o w e v e r , r e q u i r e files w i t h o u t t r a n s l a t i o n . T o s e n d a
file w i t h t h e l i n e f e e d s a s j u s t l i n e f e e d s , y o u u s e P R T : R A W i n s t e a d of P R T : .
A m i g a D O S supports multiple windows. To make a n e w w i n d o w , you can
s p e c i f y t h e d e v i c e C O N : . T h e f o r m a t f o r C O N : is a s f o l l o w s :

CON:x/y/width/height/[title]
 ^INTRODUCING AMIGADOS 13

w h e r e " x " and " y " are coordinates, " w i d t h " and " h e i g h t " are integers describ-
i n g t h e w i d t h a n d h e i g h t of t h e n e w w i n d o w , a n d " t i t l e " , w h i c h is o p t i o n a l , is
a s t r i n g . T h e title a p p e a r s o n t h e w i n d o w ' s title b a r . Y o u m u s t i n c l u d e all t h e
s l a s h e s (/), i n c l u d i n g t h e last o n e . Y o u r title c a n i n c l u d e u p to t h i r t y c h a r a c t e r s
( i n c l u d i n g s p a c e s ) . If t h e title h a s s p a c e s , y o u m u s t e n c l o s e t h e w h o l e d e s c r i p -
t i o n ii d o u b l e q u o t e s (") as s h o w n i n t h e f o l l o w i n g e x a m p l e :

"CON:20/10/300/100/my window"

T h e r e is a n o t h e r w i n d o w d e v i c e c a l l e d R A W : , b u t it is o f little u s e to t h e
g e n e r a l u s e r . ( S e e C h a p t e r 2 of t h e AmigaDOS Developer's Manual i n t h i s b o o k
f o r f u r t h e r d e t a i l s . ) Y o u c a n u s e R A W : to c r e a t e a r a w w i n d o w d e v i c e similar t o
C O N : . H o w e v e r , unlike C O N : , R A W : does no character translation and does
n o t allow y o u to c h a n g e the contents of a line. That is to say, R A W : accepts
i n p u t a n d r e t u r n s o u t p u t i n exactly t h e s a m e f o r m t h a t it w a s originally t y p e d .
T h i s m e a n s c h a r a c t e r s are s e n t to a p r o g r a m i m m e d i a t e l y w i t h o u t l e t t i n g y o u
erase anything with the B A C K S P A C E key. Y o u usually use R A W : from a
p r o g r a m w h e r e y o u might w a n t to do input and output without character
translation.

W A R N I N G : R A W : is i n t e n d e d f o r t h e a d v a n c e d u s e r . D o n o t u s e R A W :
experimentally.

T h e r e is o n e s p e c i a l n a m e , w h i c h is * ( a s t e r i s k ) . Y o u u s e t h i s t o r e f e r t o t h e
current w i n d o w , both for input or for output. Y o u can u s e the C O P Y c o m -
m a n d to c o p y f r o m o n e file t o a n o t h e r . U s i n g *, y o u c a n c o p y f r o m t h e c u r r e n t
w i n d o w to a n o t h e r w i n d o w , for e x a m p l e ,

COPY * TO C01ir:20/S0/350/150/

f r o m t h e c u r r e n t w i n d o w t o t h e c u r r e n t w i n d o w , for e x a m p l e ,

COPY * TO *

o r f r o m a file t o t h e c u r r e n t w i n d o w , f o r e x a m p l e ,

COPY b i l l / l e t t e r TO *

A m i g a D O S f i n i s h e s c o p y i n g w h e n it c o m e s to t h e e n d of t h e file. T o tell
A m i g a D O S to s t o p c o p y i n g f r o m *, y o u m u s t g i v e t h e C T R L A c o m b i n a t i o n .
N o t e t h a t * is N O T t h e u n i v e r s a l w i l d c a r d .
14 AMIGADOS USER'S MANUAL

1.3.7 Using Directory Conventions and Logical Devices

In addition to the aforementioned physical devices, A m i g a D O S supports a
v a r i e t y of u s e f u l l o g i c a l d e v i c e s . A m i g a D O S u s e s t h e s e d e v i c e s to f i n d t h e files
that your p r o g r a m s require from time to time. (So that your p r o g r a m s can refer
t o a s t a n d a r d d e v i c e n a m e r e g a r d l e s s of w h e r e t h e file actually is.) All of t h e s e
"logical d e v i c e s " m a y be reassigned b y you to reference any directory.
T h e logical d e v i c e s d e s c r i b e d in this s e c t i o n a r e a s f o l l o w s :

Name Description Directory

SYS: S y s t e m disk root directory

C: C o m m a n d s directory C
L: Library directory L
s: Sequence Library S
LIBS: L i b r a r y f o r O p e n L i b r a r y calls LIBS
DEVS: D e v i c e for O p e n D e v i c e calls DEVS
FONTS: L o a d a b l e f o n t s for O p e n F o n t s FONTS
Temporary workspace T

Figure 1-D: Logical Devices

Logical device name: SYS:

Typical directory name: My.Boot.Disk:
" S Y S " r e p r e s e n t s t h e S Y S t e m d i s k r o o t d i r e c t o r y . W h e n y o u first start u p
t h e A m i g a s y s t e m , A m i g a D O S assigns S Y S : to t h e root directory n a m e
of t h e d i s k i n DFO:. If, for i n s t a n c e , t h e d i s k i n d r i v e DFO: h a s t h e v o l u m e
n a m e M y . B o o t V D i s k , t h e n A m i g a D O S a s s i g n s S Y S : to M y . B o o t . D I S K : . A f t e r
this a s s i g n m e n t , a n y p r o g r a m s t h a t r e f e r to S Y S : u s e t h a t d i s k ' s r o o t d i r e c t o r y .

Logical device name: C:

Typical directory name: My.Boot.Diskx
' C represents the C o m m a n d s directory. W h e n y o u type a c o m m a n d to the CLI
( D I R < c r > , f o r e x a m p l e ) , A m i g a D O S first s e a r c h e s for t h a t c o m m a n d in y o u r
c u r r e n t d i r e c t o r y . If t h e s y s t e m c a n n o t f i n d t h e c o m m a n d in t h e c u r r e n t
d i r e c t o r y , it t h e n l o o k s f o r " C : D I R " . S o t h a t , if y o u h a v e a s s i g n e d " C : " t o
a n o t h e r d i r e c t o r y (for e x a m p l e , " B o o t d i s k : c " ) , A m i g a D O S r e a d s a n d e x e -
cutes from "Boot disk:c/DIR".

Logical device name: L:

Typical directory name: My.Boot.Disk:l
" L " r e p r e s e n t s t h e L i b r a r y d i r e c t o r y . T h i s d i r e c t o r y k e e p s t h e o v e r l a y s for large
c o m m a n d s a n d n o n r e s i d e n t p a r t s of t h e o p e r a t i n g s y s t e m . F o r i n s t a n c e , t h e
d i s k b a s e d r u n - t i m e libraries ( R a m - H a n d l e r , P o r t - H a n d l e r , D i s k - V a l i d a t o r , a n d
s o f o r t h ) a r e k e p t h e r e . A m i g a D O S r e q u i r e s t h i s d i r e c t o r y to o p e r a t e .
 INTRODUCING AMIGADOS 15

Logical device name: S:

Typical directory name: M y . B o o t . D i s k : s
" S " r e p r e s e n t s t h e S e q u e n c e library. S e q u e n c e files c o n t a i n c o m m a n d s e q u e n c e s
t h a t t h e E X E C U T E c o m m a n d s e a r c h e s for a n d u s e s . E X E C U T E first l o o k s for
t h e s e q u e n c e (or b a t c h ) file in y o u r c u r r e n t d i r e c t o r y . If E X E C U T E c a n n o t f i n d
it t h e r e , it l o o k s i n t h e d i r e c t o r y t h a t y o u h a v e a s s i g n e d S: t o .

Logical device name: L I B S :

Typical directory name: M y . B o o t . D i s k : L I B S
O p e n L i b r a r y f u n c t i o n calls l o o k h e r e for t h e library if it is n o t a l r e a d y l o a d e d
in m e m o r y .

Logical device name: D E V S :

Typical directory name: M y . B o o t . D i s k : D E V S
O p e n D e v i c e calls l o o k h e r e for t h e d e v i c e if it is n o t a l r e a d y l o a d e d in m e m o r y .

Logical device name: F O N T S :

Typical directory name: M y . B o o t . D i s k : F O N T S
O p e n F o n t s l o o k h e r e for y o u r l o a d a b l e f o n t s if t h e y a r e n o t a l r e a d y l o a d e d in
memory.

N o t e : In a d d i t i o n to t h e a b o v e a s s i g n a b l e d i r e c t o r i e s , m a n y p r o g r a m s o p e n files
i n t h e " : T " d i r e c t o r y . A s y o u recall, y o u f i n d file ( o r d i r e c t o r y ) n a m e s p r e d i c a t e d
w i t h a " : " i n t h e r o o t directory. T h e r e f o r e " : T " is t h e directory T , w i t h i n t h e r o o t ,
o n t h e c u r r e n t d i s k . Y o u u s e t h i s d i r e c t o r y t o store t e m p o r a r y files. P r o g r a m s
s u c h as e d i t o r s p l a c e t h e i r t e m p o r a r y w o r k files, or b a c k u p c o p i e s o f t h e last
file e d i t e d , i n t h i s d i r e c t o r y . If y o u r u n o u t of s p a c e o n a d i s k , t h i s is o n e of t h e
first p l a c e s y o u s h o u l d l o o k f o r files t h a t a r e n o l o n g e r n e e d e d .
W h e n t h e s y s t e m is first b o o t e d , A m i g a D O S initially a s s i g n s C : t o t h e : C
d i r e c t o r y . T h i s m e a n s that if y o u b o o t w i t h a d i s k t h a t y o u h a d f o r m a t t e d b y
issuing the c o m m a n d :

F O R M A T D R I V E DFO: N A M E " M y . B o o t . D i s k "

S Y S : is a s s i g n e d to " M y . B o o t . D i s k " . T h e " l o g i c a l d e v i c e " C : is a s s i g n e d t o t h e

C d i r e c t o r y o n t h e s a m e d i s k (that i s , M y . B o o t . D i s k : c ) . L i k e w i s e , t h e f o l l o w i n g
a s s i g n m e n t s are m a d e

C: My.Boot.Disk:c
L: My.Boot.Disk:l
S: My.Boot.Disk: s
LIBS: My.Boot.Disk.libs
DEVS: My.Boot.Disk:devs
FONTS: My.Boot.Disk:fonts
16 AMIGADOS USER'S MANUAL

If a d i r e c t o r y is n o t p r e s e n t , t h e c o r r e s p o n d i n g logical d e v i c e is a s s i g n e d to
the root directory.
If y o u a r e s o l u c k y a s to h a v e a h a r d d i s k (called DHO:) a n d y o u w a n t t o u s e
t h e s y s t e m files o n it, y o u m u s t i s s u e t h e f o l l o w i n g c o m m a n d s to t h e s y s t e m :

ASSIGN SYS: DHO:

ASSIGN C DHO:C
ASSIGN L: DHO:L
ASSIGN S DHO:S
ASSIGN LIBS: DHO:LIBS
ASSIGN DEVS: DHO:DEVS
A S S I G N FONTS: DHO:FONTS

P l e a s e k e e p i n m i n d t h a t a s s i g n m e n t s a r e g l o b a l t o all C L I p r o c e s s e s . C h a n g -
i n g a n a s s i g n m e n t w i t h i n o n e w i n d o w c h a n g e s it for all w i n d o w s .
If y o u w a n t t o u s e y o u r o w n special f o n t library, t y p e

A S S I G N FONTS: "Special font disk:myfonts"

If y o u w a n t y o u r c o m m a n d s to l o a d f a s t e r ( a n d y o u h a v e m e m o r y " t o b u r n " ) ,
type

makedlr ram:c
copy sys:c r a m : c all
a s s i g n c: r a m : c

T h i s c o p i e s all o f t h e n o r m a l A m i g a D O S c o m m a n d s t o t h e R A M d i s k a n d
reassigns the c o m m a n d s directory so that the s y s t e m finds t h e m there.

1.4 Using AmigaDOS Commands

A n A m i g a D O S c o m m a n d c o n s i s t s of t h e c o m m a n d n a m e a n d its a r g u m e n t s , if
a n y . T o e x e c u t e a n A m i g a D O S c o m m a n d , y o u t y p e t h e c o m m a n d n a m e a n d its
a r g u m e n t s after the CLI prompt.
W h e n y o u t y p e a c o m m a n d n a m e , t h e c o m m a n d r u n s a s p a r t of t h e C o m -
m a n d Line Interface (CLI). Y o u can type other c o m m a n d n a m e s ahead, but
A m i g a D O S does n o t execute t h e m until the current c o m m a n d has finished.
W h e n a c o m m a n d h a s f i n i s h e d , t h e c u r r e n t C L I p r o m p t a p p e a r s . I n this c a s e ,
t h e c o m m a n d is r u n n i n g interactively.
T h e C L I p r o m p t is initially n > , w h e r e n is t h e n u m b e r of t h e C L I p r o c e s s .
H o w e v e r , it c a n b e c h a n g e d to s o m e t h i n g else w i t h t h e P R O M P T c o m m a n d .
( F o r f u r t h e r details o n t h e P R O M P T c o m m a n d , s e e C h a p t e r 2 of t h i s m a n u a l . )
 INTRODUCING AMIGADOS 17

W A R N I N G : If y o u r u n a c o m m a n d i n t e r a c t i v e l y a n d it fails, A m i g a D O S
c o n t i n u e s to e x e c u t e t h e n e x t c o m m a n d y o u t y p e d a n y w a y . T h e r e f o r e , it
c a n b e d a n g e r o u s to t y p e m a n y c o m m a n d s a h e a d . F o r e x a m p l e , if y o u
type

C O P Y a TO b
DELETE a

a n d t h e C O P Y c o m m a n d fails ( p e r h a p s b e c a u s e t h e d i s k is full), t h e n D E L E T E
e x e c u t e s a n d y o u l o s e y o u r file.

1.4.1 Running Commands in the Background

Y o u c a n i n s t r u c t A m i g a D O S to r u n a c o m m a n d , or c o m m a n d s , i n t h e b a c k -
g r o u n d . T o d o t h i s , y o u u s e t h e R U N c o m m a n d . T h i s c r e a t e s a n e w C L I as a
s e p a r a t e p r o c e s s of l o w e r priority. I n t h i s c a s e , A m i g a D O S e x e c u t e s s u b s e -
q u e n t c o m m a n d l i n e s at t h e s a m e t i m e a s t h o s e t h a t h a v e b e e n R U N . F o r
e x a m p l e , y o u c a n e x a m i n e t h e c o n t e n t s of y o u r d i r e c t o r y at t h e s a m e t i m e as
s e n d i n g a c o p y of y o u r text file to t h e p r i n t e r . T o d o t h i s , t y p e

RUN TYPE t e x t _ f i l e to PRT:

LIST

R U N c r e a t e s a n e w C L I a n d carries o u t y o u r p r i n t i n g w h i l e y o u list y o u r
d i r e c t o r y files o n y o u r original C L I w i n d o w .
You can a s k A m i g a D O S t o carry o u t s e v e r a l c o m m a n d s u s i n g R U N . R U N
takes each c o m m a n d a n d carries it o u t in t h e g i v e n o r d e r . T h e l i n e c o n t a i n i n g
commands a f t e r R U N is called a c o m m a n d l i n e . T o t e r m i n a t e t h e c o m m a n d
line, press R E T U R N . T o e x t e n d y o u r c o m m a n d line o v e r s e v e r a l l i n e s , t y p e a
plus sign ( + ) b e f o r e p r e s s i n g R E T U R N o n e v e r y line e x c e p t t h e last. F o r
example,

RUN J O I N t e x t _ f i l e 1 text—file2 AS text—file +

S O R T t e x t — f i l e TO s o r t e d t e x t +
T Y P E sorted text to PRT:

1.4.2 Executing Command Files

Y o u c a n a l s o u s e t h e E X E C U T E c o m m a n d t o e x e c u t e c o m m a n d l i n e s i n a file
i n s t e a d of t y p i n g t h e m in directly. T h e C L I r e a d s t h e s e q u e n c e of c o m m a n d s
f r o m t h e file u n t i l it f i n d s a n e r r o r o r t h e e n d of t h e file. If it f i n d s a n e r r o r ,
18 AMIGADOS USER'S MANUAL

A m i g a D O S d o e s n o t e x e c u t e s u b s e q u e n t c o m m a n d s o n t h e R U N line or in t h e
file u s e d b y E X E C U T E , u n l e s s y o u h a v e u s e d t h e F A I L A T c o m m a n d . S e e
C h a p t e r 2 of t h i s m a n u a l f o r details o n t h e F A I L A T c o m m a n d . T h e C L I o n l y
gives p r o m p t s after executing c o m m a n d s that have run interactively.

1.4.3 Directing Command Input and Output

A m i g a D O S p r o v i d e s a w a y for y o u to redirect s t a n d a r d i n p u t a n d o u t p u t . Y o u
u s e t h e > a n d < s y m b o l s as c o m m a n d s . W h e n y o u t y p e a c o m m a n d , A m i g a D O S
u s u a l l y d i s p l a y s t h e o u t p u t f r o m t h a t c o m m a n d o n t h e s c r e e n . T o tell A m i g a D O S
to s e n d t h e o u t p u t to a file, y o u c a n u s e t h e > c o m m a n d . T o tell A m i g a D O S to
a c c e p t t h e i n p u t to a p r o g r a m f r o m a s p e c i f i e d file r a t h e r t h a n f r o m t h e
k e y b o a r d , y o u u s e t h e < c o m m a n d . T h e < a n d > c o m m a n d s act like traffic
c o p s w h o direct t h e f l o w of i n f o r m a t i o n . F o r e x a m p l e , to direct t h e o u t p u t f r o m
t h e D A T E c o m m a n d a n d w r i t e it to t h e file n a m e d " t e x t file", you would type
the following c o m m a n d line:

DATE > text_file

S e e C h a p t e r 2 of t h e User's Manual f o r a full s p e c i f i c a t i o n of t h e < and >

symbols.

1.4.4 Interrupting AmigaDOS

A m i g a D O S a l l o w s y o u to indicate four levels of a t t e n t i o n i n t e r r u p t w i t h C T R L - C ,
C T R L - D , C T R L - E , a n d C T R L - F . T o s t o p t h e c u r r e n t c o m m a n d f r o m w h a t e v e r it
w a s d o i n g , p r e s s C T R L - C . In s o m e c a s e s , s u c h a s E D I T , p r e s s i n g C T R L - C
i n s t r u c t s t h e c o m m a n d to s t o p w h a t it w a s d o i n g a n d t h e n t o r e t u r n to r e a d i n g
m o r e E D I T c o m m a n d s . T o tell t h e C L I to s t o p a c o m m a n d s e q u e n c e initiated b y
the E X E C U T E c o m m a n d as soon as the current c o m m a n d being executed
finishes, press C T R L - D . C T R L - E a n d CTRL-F are only u s e d b y certain c o m -
m a n d s in s p e c i a l c a s e s . S e e t h e Developer's Manual in t h i s b o o k f o r d e t a i l s .
N o t e : It is t h e p r o g r a m m e r ' s r e s p o n s i b i l i t y to d e t e c t a n d r e s p o n d to t h e s e
i n t e r r u p t i o n f l a g s . A m i g a D O S will n o t kill a p r o g r a m b y itself.

1.4.5 Understanding Command Formats

T h i s s e c t i o n e x p l a i n s t h e s t a n d a r d f o r m a t or a r g u m e n t t e m p l a t e u s e d b y m o s t
A m i g a D O S c o m m a n d s t o s p e c i f y t h e i r a r g u m e n t s . C h a p t e r 2 of t h i s m a n u a l
i n c l u d e s t h i s a r g u m e n t t e m p l a t e in t h e d o c u m e n t a t i o n of e a c h of t h e c o m -
m a n d s . T h e t e m p l a t e p r o v i d e s y o u w i t h a g r e a t deal of flexibility i n t h e o r d e r
a n d f o r m of t h e s y n t a x of y o u r c o m m a n d s .
T h e a r g u m e n t t e m p l a t e s p e c i f i e s a list of k e y w o r d s t h a t y o u m a y u s e as
 INTRODUCING AMIGADOS 19

s y n o n y m s , so that you type the alternatives after the k e y w o r d , a n d separate

them with an =
For example,

A B C , W W W , X Y Z = ZZZ

specifies k e y w o r d s , A B C , W W W , and X Y Z . T h e user m a y u s e k e y w o r d Z Z Z as

a n a l t e r n a t i v e to t h e k e y w o r d X Y Z .
T h e s e k e y w o r d s s p e c i f y t h e n u m b e r a n d f o r m of t h e a r g u m e n t s t h a t t h e
p r o g r a m e x p e c t s . T h e a r g u m e n t s m a y b e o p t i o n a l or r e q u i r e d . If y o u g i v e t h e
a r g u m e n t s , y o u m a y s p e c i f y t h e m in o n e of t w o w a y s :

By position I n t h i s c a s e , y o u p r o v i d e t h e a r g u m e n t s in t h e s a m e o r d e r a s t h e
k e y w o r d list i n d i c a t e s .
By keyword In this c a s e , t h e o r d e r d o e s n o t m a t t e r , a n d y o u p r e c e d e e a c h
argument with the relevant keyword.

F o r e x a m p l e , if t h e c o m m a n d M Y C O M M A N D r e a d f r o m o n e file a n d w r o t e to
another, the argument template would be:

FROMTO

Y o u could use the c o m m a n d specifying the arguments by position:

MYCOMMAND input-file output-file

or u s i n g t h e k e y w o r d s :

M Y C O M M A N D F R O M i n p u t - f i l e TO o u t p u t - f i l e
M Y C O M M A N D TO o u t p u t - f i l e F R O M i n p u t - f i l e

Y o u could also combine the positional and keyword argument specifications,

for e x a m p l e , with the following:

M Y C O M M A N D i n p u t - f i l e TO o u t p u t - f i l e

w h e r e y o u give t h e F R O M a r g u m e n t b y p o s i t i o n , a n d t h e T O a r g u m e n t b y
k e y w o r d . N o t e t h a t t h e f o l l o w i n g f o r m is i n c o r r e c t :

MYCOMMAND output-file FROM input-file

b e c a u s e t h e c o m m a n d a s s u m e s t h a t ' o u t p u t - f i l e ' is t h e first p o s i t i o n a l a r g u m e n t

(that i s , t h e F R O M file).
20 AMIGADOS USER'S MANUAL

If t h e a r g u m e n t is n o t a s i n g l e w o r d (that i s , s u r r o u n d e d or " d e l i m i t e d " b y

s p a c e s ) , t h e n y o u m u s t e n c l o s e it w i t h q u o t a t i o n m a r k s ( " ) . If t h e a r g u m e n t h a s
t h e s a m e v a l u e a s o n e of t h e k e y w o r d s , y o u m u s t also e n c l o s e it w i t h q u o t a t i o n
marks. For example, the following:

M Y C O M M A x T D " f i l e n a m e " TO " d e s t i n a t i o n "

s u p p l i e s t h e text " f i l e n a m e " as t h e F R O M a r g u m e n t , a n d t h e file name

" d e s t i n a t i o n " as the T O argument.
T h e k e y w o r d s in t h e s e a r g u m e n t lists h a v e c e r t a i n qualifiers a s s o c i a t e d w i t h
t h e m . T h e s e qualifiers a r e r e p r e s e n t e d b y a s l a s h (/) a n d a specific l e t t e r . T h e
m e a n i n g s of t h e qualifiers a r e a s f o l l o w s :

/A T h e a r g u m e n t is r e q u i r e d a n d m a y n o t b e o m i t t e d .
/K T h e argument must be given with the keyword and may not be used
positionally.

/S T h e k e y w o r d is a s w i t c h (that i s , a t o g g l e ) a n d t a k e s n o a r g u m e n t .

T h e qualifiers A a n d K m a y be c o m b i n e d , so that the template

DRIVE/A/K
m e a n s that y o u m u s t give the a r g u m e n t and k e y w o r d D R I V E .
In s o m e cases, no keywords m a y b e given. For example, the command
D E L E T E s i m p l y t a k e s a n u m b e r of files for A m i g a D O S to d e l e t e . In t h i s c a s e ,
y o u simply omit the k e y w o r d value, b u t the c o m m a s normally u s e d to separate
t h e k e y w o r d s r e m a i n in t h e t e m p l a t e . T h u s , t h e t e m p l a t e f o r D E L E T E , t h a t c a n
t a k e u p to t e n f i l e n a m e s , is

» ) ) » ) » ) » )

F i n a l l y , c o n s i d e r t h e c o m m a n d T Y P E . T h e a r g u m e n t t e m p l a t e is

FROM/A,TO,OPT/K

w h i c h m e a n s t h a t y o u m a y g i v e t h e first a r g u m e n t b y p o s i t i o n or b y k e y w o r d ,
b u t t h a t first a r g u m e n t is r e q u i r e d . T h e s e c o n d a r g u m e n t ( T O ) is o p t i o n a l , a n d
y o u m a y o m i t t h e k e y w o r d . T h e O P T a r g u m e n t is o p t i o n a l , b u t if it is g i v e n ,
y o u m u s t p r o v i d e t h e k e y w o r d . S o , t h e f o l l o w i n g a r e all valid f o r m s of t h e
TYPE command:
 INTRODUCING AMIGADOS 21

TYPE filename
TYPE PROM filename
TYPE f i l e n a m e TO o u t p u t - f i l e
TYPE f i l e n a m e output-file
TYPE TO o u t p u t - f i l e F R O M f i l e n a m e OPT n
TYPE f i l e n a m e OPT n
TYPE f i l e n a m e OPT n TO o u t p u t - f i l e

A l t h o u g h this m a n u a l lists all t h e a r g u m e n t s e x p e c t e d b y t h e c o m m a n d s , y o u

c a n d i s p l a y t h e a r g u m e n t t e m p l a t e b y s i m p l y t y p i n g t h e n a m e of t h e c o m -
m a n d , f o l l o w e d b y a s p a c e a n d a q u e s t i o n m a r k (?).
If t h e a r g u m e n t s y o u s p e c i f y d o n o t m a t c h t h e t e m p l a t e , m o s t c o m m a n d s
simply display the m e s s a g e " B a d a r g s " or " B a d a r g u m e n t s " a n d stop. Y o u m u s t
retype the c o m m a n d n a m e and argument. To display on the screen help on
w h a t arguments the c o m m a n d expected, you can always type a question mark
(?)•

1.5 Restart Validation Process

W h e n y o u first i n s e r t a d i s k f o r u p d a t i n g , A m i g a D O S c r e a t e s a p r o c e s s at l o w
priority. This validates the entire structure on the disk. Until the restart process
h a s c o m p l e t e d this j o b , y o u c a n n o t c r e a t e files o n t h e d i s k . It is p o s s i b l e ,
h o w e v e r , t o r e a d files.
W h e n t h e r e s t a r t p r o c e s s c o m p l e t e s , A m i g a D O S c h e c k s t o s e e if y o u h a v e s e t
the system date a n d time. T o set the date a n d time, y o u u s e the DATE
c o m m a n d . If y o u d o n o t s p e c i f y t h e s y s t e m d a t e , A m i g a D O S s e t s t h e s y s t e m
d a t e to t h e d a t e a n d t i m e o f t h e m o s t r e c e n t l y c r e a t e d file o n t h e i n s e r t e d d i s k .
T h i s e n s u r e s t h a t n e w e r v e r s i o n s of files h a v e m o r e r e c e n t d a t e s , e v e n t h o u g h
t h e a c t u a l t i m e a n d d a t e will b e i n c o r r e c t .
If y o u a s k f o r t h e d a t e a n d t h e t i m e b e f o r e t h e v a l i d a t i o n is c o m p l e t e ,
A m i g a D O S displays the date a n d time as unset. Y o u can t h e n either wait for
t h e v a l i d a t i o n t o c o m p l e t e o r u s e D A T E to e n t e r t h e c o r r e c t d a t e a n d t i m e .
V a l i d a t i o n s h o u l d h a p p e n at o n c e ; o t h e r w i s e , it s h o u l d n e v e r t a k e l o n g e r t h a n
one minute.

1.6 Commonly Used Commands: An Example Session

This manual describes the various A m i g a D O S c o m m a n d s . T h e C o m m a n d Line
I n t e r p r e t e r (CLI) r e a d s A m i g a D O S c o m m a n d s t y p e d i n t o a C L I w i n d o w a n d
t r a n s l a t e s t h e m i n t o a c t i o n s p e r f o r m e d b y t h e c o m p u t e r . I n this s e n s e t h e C L I
22 AMIGADOS USER'S MANUAL

is similar to m o r e " t r a d i t i o n a l " c o m p u t e r i n t e r f a c e s : y o u t y p e in c o m m a n d s

a n d t h e i n t e r f a c e d i s p l a y s text in r e t u r n .
B e c a u s e t h e W o r k b e n c h i n t e r f a c e is s u f f i c i e n t a n d f r i e n d l y f o r m o s t u s e r s ,
the W o r k b e n c h diskettes are s h i p p e d with the CLI interface " d i s a b l e d " . To u s e
t h e c o m m a n d s i n this m a n u a l y o u m u s t " e n a b l e " t h e C L I i n t e r f a c e . T h i s p u t s a
n e w icon, labeled " C L I " on your Workbench. W h e n you have selected and
o p e n e d this i c o n , a C L I w i n d o w b e c o m e s a v a i l a b l e , a n d y o u c a n u s e it to i s s u e
t e x t c o m m a n d s directly to A m i g a D O S .

How to Enable the Command Line Interface

B o o t y o u r c o m p u t e r u s i n g t h e K i c k s t a r t d i s k e t t e a n d a w r i t a b l e c o p y of y o u r
W o r k b e n c h diskette. O p e n the W o r k b e n c h diskette icon. O p e n the "Prefer-
e n c e s " t o o l . N e a r t h e l e f t - h a n d s i d e of t h e s c r e e n , a b o u t t w o - t h i r d s of t h e w a y
d o w n y o u will n o t i c e " C L I " w i t h a b u t t o n for " O N " a n d a b u t t o n " O F F " .
S e l e c t t h e " O N " b u t t o n . S e l e c t " S a v e " ( l o w e r r i g h t p a r t of t h e P r e f e r e n c e s
s c r e e n ) to l e a v e P r e f e r e n c e s .

How to Make a New CLI Window

To use the CLI c o m m a n d s , you open a CLI window. O p e n the " S y s t e m "
d r a w e r . T h e C L I i c o n (a c u b e c o n t a i n i n g " 1 > " ) s h o u l d n o w b e v i s i b l e . O p e n it.

Using the CLI

To use the CLI interface, select the CLI w i n d o w a n d type the desired C L I
c o m m a n d s ( d e s c r i b e d w i t h i n this m a n u a l ) . T h e C L I w i n d o w ( s ) m a y b e s i z e d
a n d m o v e d j u s t like m a n y o t h e r s . T o c l o s e t h e C L I w i n d o w , t y p e " E N D C L I " .

Workbench and CLI: Their Relationships and Differences

Type " D I R " t o d i s p l a y a list of files ( a n d d i r e c t o r i e s ) in t h e c u r r e n t disk
d i r e c t o r y . T h i s is a list o f files t h a t m a k e s u p y o u r W o r k b e n c h . Y o u m a y n o t i c e
t h a t t h e r e a r e m a n y m o r e files in t h i s d i r e c t o r y t h a n t h e r e a r e i c o n s o n t h e
W o r k b e n c h . T h e r e a s o n f o r this is t h a t W o r k b e n c h will o n l y d i s p l a y file " X " if it
h a s a n a s s o c i a t e d " X . i n f o " file. In fact t h e " . i n f o " ( p r o n o u n c e d " d o t i n f o " ) file
c o n t a i n s all of t h e i c o n d i s p l a y i n f o r m a t i o n .
F o r e x a m p l e , t h e d i s k c o p y p r o g r a m h a s t w o files a s s o c i a t e d w i t h it. T h e
file " D i s k c o p y " c o n t a i n s t h e p r o g r a m a n d " D i s k c o p y . i n f o " c o n t a i n s t h e W o r k -
b e n c h i n f o r m a t i o n a b o u t it. I n t h e c a s e o f p a i n t i n g d a t a files l i k e " m o u n t . p i c " ,
t h e file " m o u n t . p i c . i n f o " c o n t a i n s i c o n i n f o r m a t i o n a n d t h e n a m e of t h e p r o -
g r a m (default) t h a t s h o u l d p r o c e s s it ( G r a p h i C r a f t ) . In this c a s e , w h e n the
 INTRODUCING AMIGADOS 23

u s e r " o p e n s " t h e d a t a file ( m o u n t . p i c . i n f o ) , W o r k b e n c h r u n s t h e p r o g r a m a n d

p a s s e s t h e d a t a file n a m e ( m o u n t , pic) to it.
A m i g a D O S sub-directories correspond to W o r k b e n c h drawers. R a n d o m ac-
c e s s b l o c k d e v i c e s s u c h as d i s k s (DFO:) c o r r e s p o n d t o t h e d i s k e t t e i c o n s y o u
have seen.
N o t all p r o g r a m s o r c o m m a n d s c a n b e r u n u n d e r b o t h W o r k b e n c h a n d t h e
C L I e n v i r o n m e n t . N o n e of t h e C L I c o m m a n d s d e s c r i b e d in C h a p t e r 2 o f t h e
AmigaDOS User's Manual c a n b e r u n f r o m W o r k b e n c h . F o r e x a m p l e , t h e r e a r e
t w o s e p a r a t e D i s k c o p y c o m m a n d s . T h e o n e i n t h e :c/ d i r e c t o r y w o r k s w i t h
A m i g a D O S ( C L I ) . T h e o n e in t h e s y s t e m d i r e c t o r y ( d r a w e r ) w o r k s w i t h
Workbench.

An Introduction to Some of the AmigaDOS Commands

A l t h o u g h all of t h e c o m m a n d s t h a t a r e available t h r o u g h t h e C L I a r e e x p l a i n e d
in detail in t h e r e f e r e n c e p a r t of t h e AmigaDOS User's Manual, w e h a v e f o u n d
t h a t m o s t u s e r s will u s e v e r y f e w of t h e a d v a n c e d o p t i o n s . T h e r e f o r e w e h a v e
p r o v i d e d a s u m m a r y h e r e s h o w i n g v a r i o u s c o m m a n d s in t h e i r m o s t c o m m o n
form.
T h e c o m m a n d s summarized b e l o w (along with the actual A m i g a D O S c o m -
m a n d n a m e ) a s k A m i g a D O S to d o s u c h c o m m a n d s as

• C o p y a diskette ( D I S K C O P Y )
• Format a n e w diskette ( F O R M A T )
• M a k e a formatted diskette bootable;
create a CLI disk (INSTALL)
• Relabel a diskette (RELABEL)
• L o o k at t h e d i r e c t o r y of a d i s k e t t e ( D I R )
• G e t i n f o r m a t i o n a b o u t files ( L I S T )
• P r e v e n t a file f r o m a c c i d e n t a l d e l e t i o n ( P R O T E C T )
• G e t I n f o r m a t i o n a b o u t a file s y s t e m ( I N F O )
• C h a n g e a current directory (CD)
• Set the date and time (DATE)
• R e d i r e c t t h e o u t p u t of a c o m m a n d ( > )
• T y p e a text file to t h e s c r e e n ( T Y P E )
• R e n a m e a file ( R E N A M E )
• D e l e t e a file ( D E L E T E )
• Create a n e w directory ( M A K E D I R )
• C o p y files o n a d u a l - d r i v e s y s t e m ( C O P Y )
• C o p y files o n a s i n g l e - d r i v e s y s t e m ( C O P Y )
• F i n d files o n a d i s k e t t e ( D I R O P T A )
• D o s o m e t h i n g a u t o m a t i c a l l y at b o o t t i m e ( u s i n g S t a r t u p - S e q u e n c e )
24 AMIGADOS USER'S MANUAL

• T e l l A m i g a D O S w h e r e to l o o k for c e r t a i n t h i n g s ( A S S I G N )
• Open a new CLI window (NEWCLI)
• Close an existing CLI w i n d o w (ENDCLI)

All of the c o m m a n d sequences below a s s u m e that y o u have started your

s y s t e m w i t h a C L I disk r a t h e r t h a n a W o r k b e n c h d i s k , or t h a t y o u h a v e t u r n e d
o n the CLI using the preferences tool a n d h a v e entered the CLI b y that path.
T h e s e q u e n c e for t u r n i n g o n t h e C L I is p r o v i d e d earlier i n t h i s m a n u a l .

For a New User

F o r a n e w u s e r , w e s u g g e s t t h a t y o u r e a d a n d try e a c h o f t h e s e i t e m s i n
s e q u e n c e . E a c h c o m m a n d t h a t is s h o w n b e l o w l e a v e s a test d i s k in a k n o w n
s t a t e so t h a t t h e c o m m a n d t h a t i m m e d i a t e l y f o l l o w s will w o r k e x a c t l y a s
s h o w n . L a t e r , w h e n y o u are m o r e familiar w i t h t h e s y s t e m , t h e p a r a g r a p h
titles s h o w n b e l o w will s e r v e to r e f r e s h y o u r m e m o r y .

How to Begin
Before y o u begin this section, b e sure y o u h a v e two blank, double-sided
d i s k e t t e s , a n d e i t h e r y o u r W o r k b e n c h disk or y o u r C L I d i s k . B e f o r e y o u b e g i n ,
write-protect your master diskette, and write-enable the blank diskettes. M o s t
of t h e c o m m a n d s g i v e n b e l o w a s s u m e t h a t y o u h a v e a s i n g l e - d r i v e s y s t e m ;
h o w e v e r , for c o n v e n i e n c e of t h o s e w i t h d u a l - d r i v e s y s t e m s , t h e d u a l - d r i v e
version of the c o m m a n d is occasionally given.
C o m m a n d s t h a t i n s t r u c t A m i g a D O S t o e x e c u t e are s h o w n i n t h e f o l l o w i n g
s e c t i o n s , i n d e n t e d f r o m t h e left m a r g i n . A f t e r t y p i n g e a c h c o m m a n d , p r e s s t h e
R E T U R N k e y to r e t u r n c o n t r o l to A m i g a D O S . A l t h o u g h t h e c o m m a n d s are all
s h o w n i n capital l e t t e r s , t h i s is s i m p l y t o d i s t i n g u i s h t h e m f r o m t h e r e s t of
t h e text. A m i g a D O S will a c c e p t t h e c o m m a n d s i n l o w e r c a s e a s w e l l a s u p p e r
case.
In the sections that follow, the notations "dfO:" and "drive 0 " refer to the
d i s k drive t h a t is built i n t o t h e A m i g a . T h e n o t a t i o n " d f l : " r e f e r s to t h e first
e x t e r n a l 3y2-inch disk d r i v e .
Y o u will o c c a s i o n a l l y s e e a s e m i c o l o n o n a c o m m a n d line t h a t y o u are t o l d t o
t y p e . W h a t f o l l o w s t h e s e m i c o l o n is t r e a t e d a s a c o m m e n t b y A m i g a D O S . S i n c e
A m i g a D O S i g n o r e s t h e r e s t of t h e l i n e , y o u d o n ' t n e e d to t y p e t h e c o m m e n t
a l o n g w i t h t h e c o m m a n d . It is f o r y o u r i n f o r m a t i o n o n l y .
F o r m o s t c o m m a n d s , y o u c a n g e t a v e r y l i m i t e d f o r m of h e l p b y t y p i n g t h e
c o m m a n d n a m e , f o l l o w e d b y a q u e s t i o n m a r k (?) a n d p r e s s i n g R E T U R N . It
s h o w s y o u t h e " t e m p l a t e " of a c o m m a n d , c o n t a i n i n g t h e s e q u e n c e of p a r a m e -
t e r s it e x p e c t s a n d t h e k e y w o r d s it r e c o g n i z e s .
 INTRODUCING AMIGADOS 25

Copying a Disk
Y o u c a n u s e t h i s s e q u e n c e to b a c k u p y o u r s y s t e m m a s t e r d i s k o r a n y o t h e r
disk.

For a 1 disk system

D I S K C O P Y F R O M dfO: TO dfO:

For a 2 disk system

D I S K C O P Y F R O M dfO: TO d f l :

F o l l o w t h e i n s t r u c t i o n s as t h e y a p p e a r . F o r a single drive s y s t e m , y o u ' l l b e

instructed to insert the master ( F R O M ) disk. T h e n , as the copying progresses,
A m i g a D O S a s k s y o u to i n s e r t t h e c o p y ( T O ) d i s k , s w a p p i n g m a s t e r a n d c o p y
i n a n d o u t u n t i l all of t h e d i s k e t t e h a s b e e n d u p l i c a t e d . F o r a t w o d i s k s y s t e m ,
y o u ' l l b e i n s t r u c t e d t o p u t t h e m a s t e r d i s k e t t e i n t o d r i v e dfO: ( t h e b u i l t - i n
drive) a n d t h e c o p y d i s k e t t e o n t o w h i c h to c o p y i n t o d f l : ( t h e first e x t e r n a l
drive).
R e m o v e y o u r m a s t e r d i s k e t t e (either W o r k b e n c h o r C L I d i s k ) a n d p u t y o u r
m a s t e r d i s k e t t e in a safe p l a c e . L e a v e t h e c o p y w r i t e - e n a b l e d s o t h a t y o u c a n
s t o r e i n f o r m a t i o n o n it. I n s e r t t h e c o p y y o u h a v e j u s t m a d e i n t o t h e b u i l t - i n
d r i v e a n d r e b o o t y o u r s y s t e m f r o m t h e c o p y . ( S e e I n t r o d u c t i o n T o A m i g a for
the reboot process).
A f t e r t h e r e b o o t , r e e n t e r t h e C L I m o d e a g a i n . If y o u b o o t w i t h a C L I d i s k ,
t h e r e b o o t e n t e r s t h e C L I a u t o m a t i c a l l y . If y o u a r e u s i n g a W o r k b e n c h d i s k ,
y o u m u s t o p e n t h e C L I i c o n in t h e s y s t e m d r a w e r of t h e W o r k b e n c h .

Formatting a Disk
T o t r y t h i s c o m m a n d , y o u r W o r k b e n c h or C L I d i s k e t t e c o p y s h o u l d b e in d r i v e
0, a n d y o u should have a blank diskette available.
S o m e t i m e s r a t h e r t h a n s i m p l y c o p y a d i s k , y o u ' l l w a n t to p r e p a r e a d a t a d i s k
f o r y o u r s y s t e m . T h e n later y o u c a n c o p y s e l e c t e d files to this d a t a d i s k . F o r m a t
your s e c o n d blank disk b y using the F O R M A T c o m m a n d :

F O R M A T D R I V E dfO: N A M E " A n y N a m e "

F o l l o w t h e i n s t r u c t i o n s . Y o u c a n f o r m a t d i s k e t t e s in e i t h e r d r i v e 0 (dfO:, b u i l t in
to y o u r A m i g a ) or a n e x t e r n a l d r i v e .
A f t e r t h e f o r m a t is c o m p l e t e d , w a i t for t h e d i s k activity l i g h t to g o off a n d
26 AMIGADOS USER'S MANUAL

r e m o v e t h e f r e s h l y f o r m a t t e d d i s k e t t e . R e i n s e r t y o u r W o r k b e n c h or C L I d i s k -
e t t e . T h e f o r m a t t e d d i s k e t t e c a n n o w b e u s e d to h o l d d a t a files. It is n o t
bootable, however.

Making a Disk Bootable

T o try t h i s c o m m a n d , y o u r W o r k b e n c h or C L I d i s k e t t e c o p y s h o u l d b e in d r i v e
0. a n d y o u should h a v e your freshly formatted disk available.
T h e r e a r e s e v e r a l d i f f e r e n t w a y s t o c r e a t e a C L I d i s k e t t e . T w o of t h e s e w a y s
are s h o w n below.
A b o o t a b l e d i s k is o n e t h a t y o u c a n u s e to start u p y o u r A m i g a f o l l o w i n g t h e
Kickstart process. Y o u can c h a n g e a formatted disk into a CLI disk b y typing
the command:

INSTALL ?

Note: to use this c o m m a n d on a single drive s y s t e m , you M U S T u s e the

q u e s t i o n m a r k ! O t h e r w i s e A m i g a D O S will try t o d o t h e install o n t h e d i s k
c u r r e n t l y in d r i v e 0.
AmigaDOS responds:

DRIVE/A

R e m o v e y o u r W o r k b e n c h diskette copy and insert the formatted disk. T h e n

type:

dfO:

a n d p r e s s R E T U R N . A m i g a D O S c o p i e s b o o t s e c t o r s to t h e d i s k e t t e . N o w , if y o u
w a i t u n t i l t h e d i s k activity light g o e s o u t , y o u c a n t h e n p e r f o r m a full r e s e t
( C T R L - A m i g a - A m i g a ) . W h e n t h e s y s t e m r e b o o t s , y o u will g o d i r e c t l y i n t o t h e
CLI rather than into the Workbench.
Your formatted diskette n o w contains a CLI a n d nothing else. This m e a n s that
a l t h o u g h y o u s e e t h e i n t e r p r e t e r , it c a n ' t p e r f o r m a n y of t h e c o m m a n d s s h o w n
in t h i s s e c t i o n . A C L I n e e d s s e v e r a l files b e f o r e its c o m m a n d s c a n b e p e r f o r m e d .
A l l o f t h e c o m m a n d files a r e l o c a t e d i n t h e C d i r e c t o r y o f y o u r m a s t e r d i s k e t t e .
T h e s e c o n d w a y to p r o d u c e a C L I d i s k g i v e s y o u a m o r e u s e f u l d i s k in t h a t it
l e a v e s t h e C L I c o m m a n d d i r e c t o r i e s i n t a c t . H e r e is a s t e p - b y - s t e p p r o c e s s to
c h a n g e a w r i t a b l e c o p y of a W o r k b e n c h d i s k e t t e i n t o a C L I d i s k e t t e :

1. C o p y y o u r W o r k b e n c h d i s k e t t e .
2. O p e n the CLI as described above.
3. Click the selection b u t t o n on the CLI w i n d o w a n d type the c o m m a n d :
 INTRODUCING AMIGADOS 27

R E N A M E P R O M s / s t a r t u p - s e q u e n c e TO s / N O - s t a r t u p - s e q u e n c e

N o w if y o u w a i t f o r t h e d i s k activity l i g h t t o g o off a n d p e r f o r m a full r e s e t ,

y o u r W o r k b e n c h d i s k e t t e c o p y will h a v e b e c o m e a C L I . T o r e s t o r e t h e W o r k -
bench, perform the rename again, but with the n a m e sequence reversed. You
s e e , if A m i g a D O S c a n ' t f i n d a file w i t h t h e e x a c t n a m e " s t a r t u p - s e q u e n c e " in
t h e " s " d i r e c t o r y , it will e n t e r c o m m a n d m o d e a n d w a i t f o r y o u to t y p e a
command.

Relabeling a Disk
B e f o r e y o u try t h i s c o m m a n d , y o u r W o r k b e n c h or C L I d i s k e t t e c o p y s h o u l d b e
in d r i v e 0.
If, a f t e r e i t h e r c o p y i n g or f o r m a t t i n g a d i s k e t t e , y o u a r e n o t s a t i s f i e d w i t h t h e
v o l u m e n a m e y o u h a v e g i v e n it, y o u c a n c h a n g e t h e n a m e of t h e v o l u m e b y
using the RELABEL command:

relabel AnyName: DifferentName

I n t h i s e x a m p l e , w e h a v e r e f e r r e d t o t h e d i s k e t t e w e j u s t f o r m a t t e d b y its
v o l u m e n a m e . Y o u will b e a s k e d t o i n s e r t v o l u m e A n y N a m e i n t o a n y d i s k
d r i v e s o t h a t R E L A B E L c a n r e l a b e l it.
After this c o m m a n d completes, r e m o v e the diskette a n d reinsert y o u r
W o r k b e n c h or CLI diskette. T h e diskette you removed n o w has the n e w n a m e .

Looking at the Directory

B e f o r e y o u try t h i s c o m m a n d , y o u r W o r k b e n c h o r C L I d i s k e t t e c o p y s h o u l d b e
in d r i v e 0.

Y o u l o o k at t h e c o n t e n t s of a d i s k e t t e w i t h t h e c o m m a n d :

D I R o r D I R dfO:
T h i s f o r m lists t h e c o n t e n t s of y o u r c u r r e n t d i r e c t o r y . Y o u c a n list t h e c o n t e n t s
of a d i f f e r e n t d i r e c t o r y b y s p e c i f y i n g t h e p a t h n a m e for t h a t d i r e c t o r y . F o r
example, the c o m m a n d :

D I R dfO:C o r D I R c

lists t h e c o n t e n t s of t h e c(dir) o n d r i v e dfO. D i r e c t o r i e s a r e e q u i v a l e n t to t h e

d r a w e r s y o u s e e w h e n t h e W o r k b e n c h s c r e e n is v i s i b l e .
Y o u c a n l o o k at t h e d i r e c t o r y of a d i f f e r e n t d i s k u n i t , if y o u h a v e o n e , b y
s p e c i f y i n g its n a m e . F o r e x a m p l e :
28 AMIGADOS USER'S M A N U A L

DIR dfl:

lists t h e c o n t e n t s o f a d i s k e t t e i n s e r t e d i n d r i v e 1 ( t h e first e x t e r n a l d r i v e if y o u
have one attached).
Y o u c a n e v e n l o o k at t h e d i r e c t o r y of a d i s k e t t e t h a t i s n ' t c u r r e n t l y i n t h e
d r i v e b y s p e c i f y i n g its v o l u m e n a m e . F o r e x a m p l e , t h e c o n t e n t s of t h a t f r e s h l y
formatted diskette w h o s e n a m e w e changed can be displayed b y the c o m m a n d :

DIR DifferentName:

A m i g a D O S will a s k y o u to i n s e r t d i s k e t t e D i f f e r e n t N a m e i n t o t h e d r i v e s o t h a t
D I R c a n r e a d it a n d r e p o r t t h e c o n t e n t s of t h e d i r e c t o r y . D o n ' t d o it y e t ,
h o w e v e r , b e c a u s e t h e r e a r e n o files p r e s e n t f o r D I R to r e a d . W e ' l l a d d s o m e
files l a t e r .

Using the LIST Command

T o try t h i s c o m m a n d , y o u r W o r k b e n c h or C L I d i s k e t t e c o p y s h o u l d b e i n d r i v e
0.
T h e D I R c o m m a n d tells y o u t h e n a m e s of files t h a t a r e i n y o u r d i r e c t o r y . T h e
L I S T c o m m a n d p r o v i d e s a d d i t i o n a l i n f o r m a t i o n a b o u t t h o s e files. T y p e t h e
command:

L I S T o r L I S T dfO:

A m i g a D O S p r o v i d e s i n f o r m a t i o n a b o u t all files in t h e c u r r e n t d i r e c t o r y ,
i n c l u d i n g h o w l a r g e e a c h file i s , w h e t h e r it m a y o r m a y n o t b e d e l e t e d ,
w h e t h e r it is a file o r a d i r e c t o r y , a n d t h e d a t e a n d t i m e of its c r e a t i o n .
If y o u s p e c i f y t h e n a m e of a d i r e c t o r y w i t h L I S T , it lists i n f o r m a t i o n a b o u t
t h e files w i t h i n t h a t d i r e c t o r y :

LIST c

T h e " r w e d " a r e called p r o t e c t i o n f l a g s , for r e a d , w r i t e , e x e c u t e , a n d d e l e t e .

W h e n e a c h flag is s e t , u s i n g t h e P R O T E C T c o m m a n d , a file is s u p p o s e d t o b e
r e a d a b l e , writable, e x e c u t a b l e , or deleteable. A s of t h e c u r r e n t r e l e a s e , A m i g a D O S
o n l y p a y s a t t e n t i o n t o t h e d e l e t e - f l a g . If t h e " d " d o e s n ' t s h o w u p in t h e
" r w e d " c o l u m n for a f i l e n a m e , A m i g a D O S w o n ' t d e l e t e t h a t file d u r i n g a
DELETE command.
 INTRODUCING AMIGADOS 29

Using the Protect Command

T o try t h i s c o m m a n d , y o u r W o r k b e n c h o r C L I d i s k e t t e c o p y s h o u l d b e in d r i v e
0.
T h i s c o m m a n d p r o t e c t s (or u n p r o t e c t s ) a file f r o m b e i n g d e l e t e d a c c i d e n t a l l y .
Try the c o m m a n d :

DATE > myfile

PROTECT myfile
LIST myfile

Y o u will s e e t h a t all of t h e p r o t e c t - f l a g s h a v e b e e n s e t t o " " . N o w if y o u

try:

DELETE myfile

AmigaDOS responds:

"Not Deleted - file is p r o t e c t e d f r o m deletion"

T o r e e n a b l e d e l e t i o n o f t h e file:

P R O T E C T m y f i l e d or P R O T E C T m y f i l e r w e d

Getting Information About the File System

Y o u r W o r k b e n c h or C L I d i s k e t t e c o p y s h o u l d still b e in d r i v e 0. T y p e the
command:

INFO

It tells y o u h o w m u c h s p a c e is u s e d a n d h o w m u c h is free o n y o u r d i s k e t t e s ,
w h e t h e r t h e y a r e r e a d - o n l y or r e a d - w r i t e , a n d t h e n a m e of t h e v o l u m e . Y o u
c a n m a k e m o r e s p a c e o n t h e d i s k e t t e b y d e l e t i n g files. Y o u c a n c h a n g e t h e
n a m e of t h e v o l u m e b y u s i n g t h e R E L A B E L c o m m a n d .
If y o u w a n t to g e t i n f o r m a t i o n a b o u t a d i s k t h a t i s n ' t in y o u r s i n g l e - d r i v e at
the m o m e n t , issue the c o m m a n d as:

INFO ?

AmigaDOS responds:

none:
30 AMIGADOS USER'S M A N U A L

A m i g a D O S has loaded the I N F O c o m m a n d from your CLI disk a n d s h o w s

y o u t h e t e m p l a t e for t h e c o m m a n d . T h e r e s p o n s e " n o n e : " s a y s t h a t y o u d o n ' t
h a v e t o t y p e a n y t h i n g o t h e r t h a n a R E T U R N k e y t o h a v e it p e r f o r m t h e c o m -
m a n d . R e m o v e your C L I disk and insert the disk on which you want I N F O to
o p e r a t e . W a i t f o r t h e d i s k activity light to g o o n a n d off. T h e n p r e s s R E T U R N .
A m i g a D O S gives you I N F O about this other disk. This w o r k s for D I R as well
as I N F O .

Changing Your Current Directory

U n t i l n o w , w e h a v e o n l y s t a y e d at t h e " r o o t " or t o p m o s t h i e r a r c h i c a l level of
t h e d i s k e t t e d i r e c t o r y . Y o u will f i n d m o r e i n f o r m a t i o n a b o u t t h e d i r e c t o r y t r e e
structure in section 1.3 of this m a n u a l . T o see the level at w h i c h y o u are currently
positioned in your directory tree, y o u u s e the c o m m a n d :

CD

T o c h a n g e to a d i f f e r e n t c u r r e n t d i r e c t o r y , y o u tell t h e s y s t e m w h i c h d i r e c t o r y
is t o b e c o m e t h e c u r r e n t o n e . F o r e x a m p l e , w h e n y o u did a " d i r " c o m m a n d o n
dfO: t h e C L I d i s k e t t e y o u s a w a n e n t r y c(dir). If y o u w a n t to m a k e this d i r e c t o r y
the current one, you issue the command:

CD C o r CD dfO:c

N o w w h e n y o u i s s u e t h e c o m m a n d D I R , it s h o w s t h e c o n t e n t s of this l e v e l
of t h e filing s y s t e m . T h e c o m m a n d C D ( a l o n e ) s h o w s y o u t h e n a m e of y o u r
c u r r e n t d i r e c t o r y . Y o u g o u p to t h e r o o t d i r e c t o r y ( t h e t o p level) b y s p e c i f y i n g :

CD:

o n t h e c u r r e n t v o l u m e (if y o u r e f e r to y o u r d i s k e t t e s b y v o l u m e n a m e ) o r

CD dfO:

o n t h e built-in drive.

Setting the Date and Time

Y o u can set the A m i g a D O S clock b y using the D A T E c o m m a n d :

D A T E 1 2 : 0 0 : 0 0 12-OCt-85

N o w t h e s y s t e m c l o c k c o u n t s u p f r o m this d a t e a n d t i m e .
 INTRODUCING AMIGADOS 31

Redirecting the Output of a Command

B e f o r e y o u try t h i s c o m m a n d , y o u r W o r k b e n c h or C L I d i s k e t t e s h o u l d b e i n
d r i v e 0.
N o r m a l l y t h e o u t p u t of all c o m m a n d s g o e s t o t h e m o n i t o r s c r e e n . Y o u c a n
c h a n g e w h e r e the system puts the output b y using the redirect c o m m a n d " > " .
T h e f o r w a r d a r r o w s y m b o l m e a n s s e n d t h e o u t p u t t o w a r d t h i s o u t p u t file
name. Here's an example:

DATE > datefile

E x e c u t e t h e c o m m a n d s o t h a t y o u c a n u s e t h e datefile d e s c r i b e d b e l o w . T h i s
c o m m a n d creates (or overwrites) a file n a m e d " d a t e f i l e " in y o u r c u r r e n t directory.
O r , j u s t to h a v e s o m e t h i n g o n t h a t f o r m a t t e d d i s k e t t e n a m e d D i f f e r e n t N a m e ,
type the following:

DATE > DifferentName:datefile

A m i g a D O S p r o m p t s y o u to i n s e r t t h e v o l u m e w i t h t h a t n a m e . A f t e r t h e d i s k
activity l i g h t g o e s o u t , r e m o v e D i f f e r e n t N a m e a n d r e i n s e r t y o u r C L I o r W o r k -
b e n c h diskette. N o w issue the c o m m a n d :

DIR DifferentName:

Again y o u are p r o m p t e d to insert DifferentName into any drive. A m i g a D O S

lists t h e d i r e c t o r y of this d i s k e t t e , w h i c h n o w c o n t a i n s a file n a m e d d a t e f i l e .
R e p l a c e y o u r C L I or W o r k b e n c h d i s k e t t e i n t h e d r i v e .

Typing a Textfile to the Screen

Y o u c a n s e e t h e c o n t e n t s of a textfile b y u s i n g t h e T Y P E c o m m a n d :

T Y P E datefile

T h i s c o m m a n d will d i s p l a y w h a t e v e r y o u h a v e in t h e s p e c i f i e d file. If y o u
w i s h to s t o p t h e o u t p u t m o m e n t a r i l y to r e a d s o m e t h i n g o n t h e s c r e e n , p r e s s
t h e s p a c e b a r . T o restart it p r e s s t h e B A C K S P k e y . If y o u w i s h to e n d t h e T Y P E
c o m m a n d , hold d o w n the CTRL key, and press the C key.
If y o u w i s h to v e r i f y t h a t a n o t h e r d i s k e t t e a l s o h a s t h e datefile c o n t e n t s o n it,
you can perform the command:

TYPE DifferentName:datefile
32 AMIGADOS USER'S MANUAL

Changing the Name of a File

Before y o u try this c o m m a n d , your W o r k b e n c h or CLI diskette copy should b e
in d r i v e 0.

Y o u c a n c h a n g e t h e n a m e of a file b y u s i n g t h e R E N A M E c o m m a n d :

R E N A M E F R O M d a t e f i l e TO n e w n a m e

or

R E N A M E datefile n e w n a m e

N o w use T Y P E to verify that the n e w n a m e refers to the same contents.

TYPE newname
Notice that the alternate form of the c o m m a n d doesn't require that y o u use
t h e F R O M a n d T O . M o s t of t h e A m i g a D O S c o m m a n d s h a v e a n a l t e r n a t e f o r m ,
abbreviated from that s h o w n in this preface section. T h e longer form h a s b e e n
u s e d p r i m a r i l y to i n t r o d u c e y o u to w h a t t h e c o m m a n d d o e s . B e s u r e to
e x a m i n e t h e s u m m a r y p a g e s t o familiarize y o u r s e l f w i t h t h e a l t e r n a t e c o m -
m a n d forms that are available.

Deleting Files
T o try t h i s c o m m a n d , y o u r W o r k b e n c h or C L I d i s k e t t e s h o u l d b e i n d r i v e 0.
Y o u m a y b e w o r k i n g o n s e v e r a l v e r s i o n s of a p r o g r a m o r textfile, a n d
e v e n t u a l l y w i s h t o d e l e t e v e r s i o n s of t h a t file t h a t y o u d o n ' t n e e d a n y m o r e .
T h e D E L E T E c o m m a n d lets y o u e r a s e files a n d r e l e a s e s t h e d i s k s p a c e to
A m i g a D O S for reuse.
N o t e : If y o u D E L E T E files, it is n o t p o s s i b l e to r e t r i e v e t h e m . B e c e r t a i n t h a t
y o u really d o w i s h t o d e l e t e t h e m .
H e r e is a s a m p l e c o m m a n d s e q u e n c e , t h a t c r e a t e s a file u s i n g t h e r e d i r e c t i o n
c o m m a n d , t y p e s it to v e r i f y t h a t it is really t h e r e , t h e n d e l e t e s it.

DIR > directorystuff

TYPE directorystuff
DELETE directorystuff
TYPE directorystuff

T o t h e final c o m m a n d in t h e a b o v e s e q u e n c e , A m i g a D O S r e s p o n d s :

Cant Open directory-stuff

i n d i c a t i n g t h a t t h e file c a n ' t b e f o u n d , b e c a u s e y o u d e l e t e d it.

 INTRODUCING AMIGADOS 33

Copying Files
Before y o u enter this c o m m a n d , your W o r k b e n c h or CLI diskette should b e in
d r i v e 0.
O n a d u a l - d r i v e s y s t e m , c o p y i n g files is e a s y :

C O P Y F R O M d f O : s o u r c e p a t h TO d f l : d e s t i n a t i o n p a t h

or

COPY dfO:sourcepath d f l : d e s t l n a t i o n p a t h

O n a s i n g l e - d r i v e s y s t e m , c o p y i n g files is a little m o r e c o m p l e x . Y o u m u s t
c o p y c e r t a i n s y s t e m files f r o m y o u r s y s t e m d i s k e t t e i n t o t h e s y s t e m m e m o r y .
T h i s is also called u s i n g t h e R A M : d e v i c e , o f t e n k n o w n a s a r a m d i s k . C o p y t h e
file(s) t o t h e r a m d i s k , c h a n g e y o u r d i r e c t o r y to t h e r a m d i s k , t h e n c o p y f r o m t h e
r a m d i s k o n t o t h e d e s t i n a t i o n d i s k e t t e . H e r e is a s a m p l e s e q u e n c e .
B e s u r e y o u r W o r k b e n c h or C L I d i s k e t t e is i n t h e i n t e r n a l d i s k d r i v e . I s s u e
the commands:

C O P Y dfO:c/cd R A M :
COPY ofO:c/copy R A M :
CD R A M :

I n s e r t t h e s o u r c e d a t a d i s k e t t e i n t o t h e d r i v e . ( F o r this e x a m p l e , c o p y s o m e -
t h i n g f r o m t h e W o r k b e n c h or C L I d i s k e t t e , w h i c h is a l r e a d y i n t h e d r i v e ) .
Type:

COPYdfO:c/executeram:execute
or
COPY dfO:c/execute e x e c u t e
or
COPY dfO:c/execute r a m :

R e m o v e the source diskette, and insert the destination diskette into the
drive. Type:

COPY ram-.execute dfO:execute

or
C O P Y e x e c u t e d f O : e x e c u t e (If y o u d i d t h e CD R A M : t h i s f o r m w o r k s . )

R e m o v e t h e d e s t i n a t i o n d i s k e t t e a n d i n s e r t y o u r C L I or W o r k b e n c h d i s k e t t e
again. Type:
34 AMIGADOS USER'S MANUAL

CD dfO:

a n d y o u are b a c k w h e r e you started. T h e only other c o m m a n d y o u m a y w a n t

t o p e r f o r m is:

DELETE RAM:cd RAM:copy RAM:execute

w h i c h r e l e a s e s t h e r a m d i s k m e m o r y t o t h e s y s t e m for o t h e r u s e s .

Creating a New Directory

Y o u can create a n e w directory (newdrawer) within the current directory b y
using the M A K E D I R command:

MAKEDIR newdrawer

N o w if y o u i s s u e t h e D I R c o m m a n d , y o u will s e e t h a t t h e r e is a n e n t r y for:

newdrawer (dir)

Y o u c a n a l s o u s e t h e R E N A M E c o m m a n d to m o v e a file f r o m o n e d i r e c t o r y
( d r a w e r ) to a n o t h e r o n t h e s a m e d i s k e t t e :

MAKEDIR newdrawer
R E N A M E F R O M n e w n a m e TO n e w d r a w e r / n e w n a m e

m o v e s t h e file f r o m t h e c u r r e n t d i r e c t o r y i n t o t h e n e w d r a w e r y o u h a v e c r e a t e d .
T o c h e c k t h a t it h a s really b e e n m o v e d , i s s u e t h e c o m m a n d :

DIR

T h e n type:

DIR newdrawer

AmigaDOS l o o k s in t h e n e w d r a w e r , a n d s h o w s y o u t h a t t h e file named

" n e w n a m e " is t h e r e .

Is My File Somewhere on This Disk?

B e f o r e y o u e n t e r t h i s c o m m a n d , y o u r W o r k b e n c h or C L I d i s k e t t e c o p y s h o u l d
b e i n d r i v e 0.
S o m e t i m e s y o u w i s h to s e e e v e r y t h i n g o n t h e d i s k e t t e , i n s t e a d of only
 INTRODUCING AMIGADOS 35

o n e d i r e c t o r y at a t i m e . Y o u c a n u s e t h e D I R c o m m a n d w i t h o n e of its
options:

D I R OPT A

w h i c h lists all d i r e c t o r i e s a n d s u b d i r e c t o r i e s o n t h e d i s k e t t e . K e e p in m i n d t h e
< s p a c e > < B A C K S P > c o m b i n a t i o n to p a u s e a n d restart t h e listing.
T o g e t a c l o s e r l o o k at t h e d i s k ' s c o n t e n t s , y o u m i g h t r e d i r e c t t h e o u t p u t t o a
file:

D I R > m y d i s k d i r OPT A

Notice that the redirect-the-output c o m m a n d character and filename M U S T

c o m e b e f o r e t h e list of o p t i o n s for t h e D I R c o m m a n d .
N o w , if y o u w i s h , y o u c a n T Y P E t h e file m y d i s k d i r a n d p r e s s t h e s p a c e b a r
to p a u s e t h e listing. U s e t h e R E T U R N k e y t o r e s u m e t h e listing. O r , y o u c a n
u s e E D t o v i e w t h e file, as f o l l o w s :

ED mydiskdir

U s e t h e c u r s o r k e y s t o m o v e u p a n d d o w n i n t h e file.
U s e t h e k e y c o m b i n a t i o n E S C t h e n T < R E T U R N > t o m o v e t o t h e t o p of
t h e file.
S u c h a c o m b i n a t i o n c a n b e r e f e r r e d t o as " E S C - T " , m e a n i n g E S C f o l l o w e d
b y T.
U s e t h e k e y c o m b i n a t i o n E S C - B < R E T U R N > t o m o v e t o t h e b o t t o m of t h e
file.
U s e the key combination E S C - M then a n u m b e r < R E T U R N > to m o v e to
a specific line n u m b e r w i t h i n t h e file.
U s e t h e k e y c o m b i n a t i o n E S C - Q < R E T U R N > to Q U I T w i t h o u t c h a n g i n g
t h e file o r
U s e E S C - X < R E T U R N > t o w r i t e a n y c h a n g e s to y o u r file b a c k i n t o t h e
original file n a m e .

C h a p t e r 3 of t h e AmigaDOS User's Manual has m o r e detailed information on

using ED.

Doing Something Automatically at Boot Time

T h e r e is a file in t h e " s " s u b d i r e c t o r y o n y o u r W o r k b e n c h or C L I d i s k e t t e c a l l e d
S t a r t u p S e q u e n c e . T h i s is a n e x e c u t e file. It c o n t a i n s a s e q u e n c e of C L I c o m -
m a n d s t h a t A m i g a D O S p e r f o r m s w h e n e v e r y o u r e b o o t t h e s y s t e m . T h e last
t w o c o m m a n d s in y o u r W o r k b e n c h d i s k e t t e S t a r t u p S e q u e n c e a r e L o a d W b
36 AMIGADOS USER'S M A N U A L

(load t h e W o r k b e n c h p r o g r a m ) a n d E N D C L I w h i c h b a s i c a l l y l e a v e s t h e W o r k -
b e n c h p r o g r a m i n c o n t r o l . Y o u c a n m a k e u p y o u r o w n S t a r t u p S e q u e n c e file
u s i n g E D o r E D I T to c r e a t e a c u s t o m v e r s i o n of a n e x e c u t e c o m m a n d
s e q u e n c e . T h e E X E C U T E c o m m a n d s u m m a r y a n d t u t o r i a l s e c t i o n in t h e
AmigaDOS User's Manual h a s details a b o u t v a r i o u s c o m m a n d s t h a t y o u c a n
h a v e in t h i s file. N o t e t h a t S t a r t u p S e q u e n c e c a n also b e u s e d t o a u t o - r u n a
program.

W A R N I N G : T a k e c a r e to m o d i f y o n l y a c o p y of y o u r d i s k e t t e
never modify the master diskette if y o u d e c i d e to c h a n g e the
Startup Sequence.

Assigning the Diskette on Which AmigaDOS Looks for Things

B e f o r e y o u e n t e r t h i s c o m m a n d , y o u r W o r k b e n c h or C L I d i s k e t t e c o p y s h o u l d
b e in d r i v e 0.
O c c a s i o n a l l y , y o u m i g h t w i s h to c h a n g e to a d i f f e r e n t d i s k e t t e a n d t h e n
continue your work. For example, you may have booted the system using a
W o r k b e n c h d i s k e t t e , t h e n w i s h to c h a n g e to a C L I d i s k e t t e . If t h e C L I d i s k e t t e
h a s a d i r e c t o r y o n it t h a t c o n t a i n s t h e e x e c u t a b l e c o m m a n d s y o u w a n t t o
p e r f o r m , (for e x a m p l e , a c(dir)), y o u c a n c h a n g e to t h a t d i s k e t t e b y u s i n g t h e
ASSIGN command.
If y o u d o n ' t u s e A S S I G N , y o u will h a v e to s w a p d i s k e t t e s t o g e t c o m m a n d s
d o n e . H e r e is a n e x a m p l e t h a t d o e s n ' t u s e A S S I G N . T h e i n t e n t is to c h a n g e
d i s k e t t e s a n d b e g i n u s i n g " m y d i s k : " as t h e m a i n d i s k e t t e . A n y u n n e e d e d files
h a v e a l r e a d y b e e n d e l e t e d s o a s to p r o v i d e w o r k s p a c e .

CD m y d i s k :

A m i g a D O S r e s p o n d s " i n s e r t m y d i s k i n t o a n y d r i v e " . I n s e r t it, t h e n type:

DIR

A m i g a D O S p r o m p t s " i n s e r t W o r k b e n c h [or w h a t e v e r t h e b o o t d i s k e t t e n a m e
w a s ] in a n y d r i v e " . It k n o w s , f r o m b o o t t i m e , t h a t t h e D I R c o m m a n d is in t h e
boot diskette, c directory. A m i g a D O S reads the DIR c o m m a n d , then asks
" i n s e r t m y d i s k in a n y d r i v e " . A n y o t h e r A m i g a D O S c o m m a n d also r e s u l t s i n
the n e e d for a diskette s w a p . To avoid this, u s e the A S S I G N c o m m a n d as
follows:

A S S I G N " c: m y d l s k : c
 INTRODUCING AMIGADOS 37

A m i g a D O S a s k s " i n s e r t m y d i s k i n t o a n y d r i v e " . F r o m n o w o n , all c o m -

m a n d s to A m i g a D O S will b e s o u g h t f r o m t h e c o m m a n d (c) d i r e c t o r y of t h i s
o t h e r d i s k e t t e a n d A m i g a D O S w o n ' t a s k f o r t h e original d i s k e t t e b a c k f o r
simple commands.
O n c e y o u ' v e d o n e t h i s , y o u ' l l p r o b a b l y w a n t to t y p e :

CD m y d i s k :

T h e r e a r e o t h e r t h i n g s t h a t A m i g a D O S c a n a s s i g n . If y o u i s s u e t h e c o m m a n d

ASSIGN LIST

y o u will s e e t h e o t h e r t h i n g s as w e l l . If y o u r u n a p r o g r a m t h a t r e q u i r e s a serial
d e v i c e ( m o d e m , p r i n t e r ) o r a parallel d e v i c e ( p r i n t e r ) , A m i g a D O S l o o k s i n t h e
d i r e c t o r y c u r r e n t l y a s s i g n e d to D E V S : to locate t h e d e v i c e . If all of t h e s y s t e m
d i r e c t o r i e s a r e o n this n e w m a i n d i s k e t t e , y o u c a n a v o i d h a v i n g A m i g a D O S a s k
y o u t o r e i n s e r t t h e original d i s k e t t e b y p r o v i d i n g a n e x e c u t e file o n y o u r
d i s k e t t e s t h a t r e a s s i g n s all d e v i c e s t o t h a t d i s k e t t e . T h e c o n t e n t s of t h i s e x e c u t e
file for a d i s k e t t e n a m e d " m y d i s k " a r e as f o l l o w s :

ASSIGN SYS: mydisk:

ASSIGN S: m y d i s k : s
ASSIGN DEVS: mydisk:devs
ASSIGN L: m y d i s k : l
ASSIGN FONTS: mydlsk:fonts
ASSIGN LIBS: mydisk:libs

T o c r e a t e this e x e c u t e file, u s e t h e c o m m a n d :

C O P Y F R O M * TO r e a s s i g n

T h e n t y p e t h e a b o v e A S S I G N l i n e s . A f t e r y o u ' v e t y p e d t h e last l i n e , e n t e r
t h e k e y c o m b i n a t i o n C T R L A w h i c h e n d s t h e file. T h e " * " s t a n d s f o r t h e
k e y b o a r d a n d c u r r e n t C L I w i n d o w , s o t h i s m e t h o d of c r e a t i n g a file is o n e
p o s s i b l e a l t e r n a t i v e t o u s i n g E D or E D I T .

Creating a New CLI

A m i g a D O S is a m u l t i - t a s k i n g s y s t e m . Y o u c a n h a v e m u l t i p l e w i n d o w s o p e n at
t h e s a m e t i m e , e a c h w i t h its o w n c u r r e n t d i r e c t o r y a n d e x e c u t i n g s e p a r a t e
c o m m a n d s . Y o u create a n e w CLI by using the c o m m a n d N E W C L I :

NEWCLI
38 AMIGADOS USER'S MANUAL

This o p e n s a separate w i n d o w , with a p r o m p t that identifies the current

p r o c e s s . F o r e x a m p l e , if t h e first w i n d o w h a s a p r o m p t :

1>

then the n e w CLI might have a prompt:

2>

Y o u c a n m o v e t h e n e w w i n d o w a r o u n d , m a k e it b i g g e r , m a k e it s m a l l e r a n d
s o o n . T o i s s u e c o m m a n d s t o t h e n e w C L I , click w i t h i n its w i n d o w . N o w
a n y t h i n g y o u t y p e g o e s i n t o t h e w i n d o w w h e r e y o u clicked t h e s e l e c t i o n
button most recently. Try the following:

1. C l i c k i n w i n d o w 1, t h e n t y p e :

D I R dfO:c

2 . Q u i c k l y click i n w i n d o w 2 , a n d t y p e :

INFO

B o t h C L I s will w o r k at t h e s a m e t i m e to fulfill y o u r r e q u e s t s . T h i s d e m o n -
s t r a t e s t h e m u l t i - t a s k i n g capabilities of t h e A m i g a . N o t i c e t h a t y o u a r e n ' t
l i m i t e d t o o n l y t w o C L I s , y o u c a n , if t h e r e is m e m o r y a v a i l a b l e , o p e n a s m a n y
as 20 CLIs.

Closing a CLI
Y o u f i n i s h w i t h a C L I a n d c l o s e its w i n d o w w i t h t h e c o m m a n d E N D C L I . Click
t h e s e l e c t i o n b u t t o n of t h e m o u s e in t h e w i n d o w for t h e C L I y o u w i s h t o c l o s e ,
and type:

ENDGLI

T h a t ' s all t h e r e is to it.

Closing Comments
T h e a b o v e s e r i e s of c o m m a n d d e s c r i p t i o n s i n t r o d u c e s y o u to t h e k i n d s of
things y o u can do with A m i g a D O S c o m m a n d s from the CLI. T h e r e are several
c o m m a n d s t h a t h a v e n ' t b e e n c o v e r e d in t h e a b o v e s e s s i o n at all. In a d d i t i o n ,
 INTRODUCING AMIGADOS 39

m o s t of t h e c o m m a n d s d e s c r i b e d a b o v e h a v e o t h e r " t e m p l a t e s " ( w a y s y o u c a n
e n t e r t h e c o m m a n d s ) a n d o p t i o n s that h a v e n ' t b e e n d e m o n s t r a t e d .
C h a p t e r 2 of t h e AmigaDOS User's Manual c o n t a i n s a r e f e r e n c e s e c t i o n t h a t
s h o w s t h e t e m p l a t e s for e a c h of t h e c o m m a n d s in A m i g a D O S . Y o u c a n l o o k at
t h e d e s c r i p t i o n for e a c h c o m m a n d to f i n d m o r e i n f o r m a t i o n . O n c e y o u a r e
f a m i l i a r w i t h t h e c o m m a n d s , a n d t h e f o r m s in w h i c h y o u c a n u s e t h e m , t h e
q u i c k r e f e r e n c e listing at t h e e n d of t h e c h a p t e r will b e u s e f u l t o r e m i n d y o u of
t h e c o m m a n d s t h a t are a v a i l a b l e .

1.7 Conventions Used

In C h a p t e r 2 of t h i s m a n u a l , i n t h e " F o r m a t " d e s c r i p t i o n for t h e A m i g a D O S
c o m m a n d s , y o u will f i n d t h e f o l l o w i n g n o t a t i o n s u s e d :

<name> I n d i c a t e s a p a r a m e t e r n a m e t h a t y o u s h o u l d fill in for this c o m -

mand. Example: E X E C U T E < c o m m a n d f i l e > w h e r e the n a m e
of t h e c o m m a n d file is a r e q u i r e d p a r a m e t e r .
[ ] S q u a r e b r a c k e t s a r e u s e d to i n d i c a t e t h a t a n i t e m is o p t i o n a l . It
n e e d n ' t b e p r o v i d e d f o r t h e c o m m a n d to f u n c t i o n b u t , if p r o -
vided, conveys additional information to A m i g a D O S about h o w
to p e r f o r m t h e c o m m a n d . E x a m p l e : Q U I T [ < c o d e > ]
I A vertical b a r tells y o u t h a t y o u c a n select o n e o r a n o t h e r of t h e
a l t e r n a t i v e s t h a t a r e s e p a r a t e d b y t h e vertical b a r f o r a c o m m a n d .
E x a m p l e : D I R [ O P T A 111 A I ] T h e e x a m p l e i n d i c a t e s t h a t y o u c a n
c h o o s e A , I or A I for t h e s p e c i f i c a t i o n .
<name>* I n d i c a t e s o n e - o r - m o r e o c c u r r e n c e s of a p a r a m e t e r n a m e ; if y o u
supply more than one such parameter, individual parameters
m u s t b e s e p a r a t e d b y at l e a s t o n e b l a n k s p a c e .

F o r A m i g a D O S C L I c o m m a n d s , u n l e s s s o m e f o r m of p u n c t u a t i o n , s u c h as a
c o m m a or a p l u s - s i g n is actually i n c l u d e d in t h e c o m m a n d F o r m a t l i n e , y o u
must always separate the parameters with blank spaces. Don't confuse the
Format information with the " T e m p l a t e " for the c o m m a n d . T h e c o m m a n d
t e m p l a t e is e x p l a i n e d in s e c t i o n 1.4.5 of t h e AmigaDOS User's Manual.
Chapter 2
AmigaDOS Commands

T h i s c h a p t e r is d i v i d e d i n t o t w o p a r t s : t h e first p a r t d e s c r i b e s t h e u s e r c o m -
m a n d s available on the Amiga; the second describes the developer c o m m a n d s .
T h e u s e r c o m m a n d s fall i n t o s e v e r a l c a t e g o r i e s : file utilities, C L I c o n t r o l ,
c o m m a n d sequence control, and system and storage m a n a g e m e n t . Part I pro-
v i d e s a l p h a b e t i z e d c o m m a n d d e s c r i p t i o n s t h a t give t h e f o r m a t , t e m p l a t e , p u r -
p o s e , a n d s p e c i f i c a t i o n of e a c h c o m m a n d as w e l l as a n e x a m p l e of its u s e . Part
2 has the same organization.
T h e c h a p t e r starts w i t h a list of unfamiliar terminology. A t t h e e n d of the c h a p t e r
t h e r e is a q u i c k C o n t e n t s r e f e r e n c e card t h a t lists all t h e c o m m a n d s b y f u n c t i o n .

2.1 AmigaDOS User's Commands

2.2 AmigaDOS Developer's Commands
2.3 A m i g a D O S C o m m a n d s Quick Reference Card

2.1 AmigaDOS User's Commands

Unfamiliar Terminology
In t h i s m a n u a l y o u c o u l d f i n d s o m e t e r m s t h a t y o u h a v e n o t s e e n b e f o r e . T h e
list b e l o w i n c l u d e s s o m e c o m m o n t e r m s t h a t a r e c o n f u s i n g if y o u a r e u n f a m i l -
iar w i t h t h e m .

Boot s t a r t u p . It c o m e s f r o m t h e e x p r e s s i o n " p u l l i n g y o u r s e l f u p b y
your bootstraps."

Default initial s e t t i n g o r , in o t h e r w o r d s , w h a t h a p p e n s if y o u d o
n o t h i n g . S o t h a t , in this m a n u a l , " d e f a u l t " is u s e d t o m e a n
" i n a b s e n c e of s o m e t h i n g e l s e " .

Device name p a r t of a n a m e t h a t p r e c e d e s t h e c o l o n (:), f o r e x a m p l e , C O N : ,

D F O : , PRT:, and so forth.
 AMIGADOS COMMANDS 41

File handle a n i n t e r n a l A m i g a D O S v a l u e t h a t r e p r e s e n t s a n o p e n file or

device.

Logical device a n a m e you can give to a directory with A S S I G N that y o u can

then use as a device n a m e .

Object code b i n a r y o u t p u t f r o m a n a s s e m b l e r or c o m p i l e r , a n d binary

input to a linker.

Reboot restart.

Stream a n o p e n file or d e v i c e t h a t is a s s o c i a t e d w i t h a file h a n d l e . F o r

e x a m p l e , t h e i n p u t s t r e a m c o u l d b e f r o m a file a n d t h e o u t p u t
s t r e a m c o u l d b e to t h e c o n s o l e d e v i c e .

System disk a disk containing the W o r k b e n c h a n d c o m m a n d s .

Volume name a n a m e y o u give to a p h y s i c a l d i s k .

N o t e : C o m m a n d f o r m a t is e x p l a i n e d i n s e c t i o n 1.7; c o m m a n d t e m p l a t e is
e x p l a i n e d in s e c t i o n 1 . 4 . 5 .

Format: [<command>];[<comment>]
Template: "command";"comment"
Purpose: T o a d d c o m m e n t s to c o m m a n d l i n e s .
Specification:
T h e C L I i g n o r e s e v e r y t h i n g a f t e r t h e s e m i c o l o n (;).

Examples:

;This line is only a c o m m e n t

i g n o r e s t h e p a r t of t h e line c o n t a i n i n g " T h i s line is o n l y a c o m m e n t . "

copy < f i l e > to prt: ; p r i n t t h e file

c o p i e s t h e file t o t h e p r i n t e r , b u t i g n o r e s t h e c o m m e n t " p r i n t t h e f i l e . "

See also: EXECUTE

><
Format: <command>[>outputfilename][inputfilename][<commandargs*]
Template: " c o m m a n d " > " T O " < "FROM" "args"
Purpose: To direct c o m m a n d input a n d output.
42 AMIGADOS USER'S M A N U A L

Specification:
Y o u u s e t h e s y m b o l s > a n d < t o d i r e c t t h e o u t p u t a n d i n p u t of a c o m m a n d .
T h e d i r e c t i o n of t h e p o i n t of t h e a n g l e b r a c k e t i n d i c a t e s t h e d i r e c t i o n of
information flow. Y o u can u s e these symbols to change w h e r e any c o m m a n d
reads input or writes output. T h e output from a c o m m a n d usually goes to the
c u r r e n t w i n d o w . H o w e v e r , if y o u t y p e a > s y m b o l after a c o m m a n d a n d b e f o r e
a f i l e n a m e , t h e c o m m a n d w r i t e s t h e o u t p u t to t h a t file i n s t e a d . S i m i l a r l y , if y o u
t y p e t h e < s y m b o l b e f o r e a f i l e n a m e , t h e c o m m a n d r e a d s f r o m t h a t file i n s t e a d
of f r o m t h e k e y b o a r d .
Y o u d o n o t h a v e to s p e c i f y b o t h t h e T O a n d F R O M d i r e c t i o n s a n d files. T h e
e x i s t e n c e a n d n u m b e r of " a r g s " d e p e n d s o n t h e c o m m a n d y o u u s e d . R e d i r e c -
t i o n o n l y h a p p e n s f o r t h e c o m m a n d y o u s p e c i f i e d . A m i g a D O S r e v e r t s to t h e
initial or " d e f a u l t " i n p u t a n d o u t p u t (that i s , t h e k e y b o a r d a n d c u r r e n t w i n d o w )
a f t e r w a r d . N o t i c e t h a t r e d i r e c t i o n m u s t precede t h e a r g u m e n t s .

Examples:

DATE > dlary_dates

w r i t e s t h e o u t p u t of t h e D A T E c o m m a n d (that is, t o d a y ' s d a t e a n d t i m e ) t o t h e

file " d i a r y dates".

my program < my input

tells m y program to accept i n p u t f r o m m y input instead of f r o m the

keyboard.

LIST > temp

S O R T t e m p TO *

p r o d u c e s a s o r t e d list of files a n d d i s p l a y s t h e m o n t h e s c r e e n .

T h e following sequence:

ECHO > 2nd.date 0 2 - j a n - 7 8

DATE < 2nd.date ?
DELETE 2nd.date

c r e a t e s a file called 2 n d . d a t e t h a t c o n t a i n s t h e text " 0 2 - j a n - 7 8 < l i n e f e e d > " . N e x t

it u s e s t h i s file as i n p u t to t h e c o m m a n d D A T E . N o t e t h a t t h e " ? " is n e c e s s a r y
for D A T E to accept input from the standard input, rather t h a n the c o m m a n d
l i n e . F i n a l l y , a s y o u n o l o n g e r n e e d t h e file, t h e D E L E T E c o m m a n d d e l e t e s
2nd. date.
 AMIGADOS COMMANDS 43

ASSIGN
Format: ASSIGN [[<name>]<dir>][LIST]
Template: ASSIGN "NAME,DIR,LIS17S"
Purpose: T o a s s i g n a logical d e v i c e n a m e to a filing s y s t e m d i r e c t o r y .
Specification:
N A M E is t h e logical d e v i c e n a m e g i v e n to t h e d i r e c t o r y s p e c i f i e d b y D I R .
If y o u j u s t g i v e t h e N A M E , A m i g a D O S d e l e t e s t h e logical d e v i c e n a m e g i v e n
(that i s , it r e m o v e s t h e a s s i g n m e n t ) .
A S S I G N w i t h o u t a n y p a r a m e t e r s or t h e s w i t c h L I S T d i p l a y s a listing of all
current assignments.
W h e n y o u u s e A S S I G N , y o u m u s t e n s u r e t h a t t h e r e is a d i s k i n s e r t e d i n t h e
d r i v e . T h i s is i m p o r t a n t b e c a u s e A S S I G N m a k e s a n a s s i g n m e n t t o a d i s k v o l u m e
and not to a drive.
N o t e t h a t t h e effect o f A S S I G N is lost w h e n y o u r e s t a r t o r " r e b o o t " y o u r
computer.

Examples:

ASSIGN sources: :new/work

S e t s u p t h e logical d e v i c e n a m e " s o u r c e s " to t h e d i r e c t o r y " : n e w / w o r k " . T h e n

t o g a i n a c c e s s t o files in " : n e w / w o r k " , y o u c a n u s e t h e logical d e v i c e n a m e
" s o u r c e s " , as in

TYPE sources:xyz

w h i c h d i s p l a y s t h e file " : n e w / w o r k / x y z " .

ASSIGN LIST

lists t h e c u r r e n t logical d e v i c e n a m e s in u s e .

BREAK
Format: BREAK <task>[ALL][C][D][E][F]
Template: BREAK "TASK/A,ALL/S,C/S,D/S,E/S,F/S"
Purpose: T o set a t t e n t i o n flags i n t h e g i v e n p r o c e s s .
Specification:
B R E A K s e t s t h e s p e c i f i e d a t t e n t i o n flags i n t h e p r o c e s s . C s e t s t h e C T R L - C flag,
D s e t s t h e C T R L - D flag, a n d s o o n . A L L sets all t h e flags f r o m C T R L - C t h r o u g h
 44 AMIGADOS USER'S MANUAL

C T R L - F . B y d e f a u l t , A m i g a D O S o n l y s e t s t h e C T R L - C flag. T h e a c t i o n o f
B R E A K is i d e n t i c a l to s e l e c t i n g t h e r e l e v a n t p r o c e s s b y m o v i n g t h e m o u s e t o
t h e w i n d o w , clicking t h e S e l e c t i o n B u t t o n , a n d p r e s s i n g t h e r e q u i r e d c o n t r o l
key combination.

Examples:

BREAK 7

s e t s t h e C T R L - C a t t e n t i o n flag of p r o c e s s 7. T h i s is i d e n t i c a l t o s e l e c t i n g p r o c e s s
7 and pressing CTRL-C.

BREAK 5 D

s e t s t h e C T R L - D a t t e n t i o n flag of p r o c e s s 5 .

BREAK 3 D E

sets both C T R L - D a n d CTRL-E.

CD
Format: CD[<dir>]
Template: CD "DIR"
Purpose: T o s e t o r c h a n g e a c u r r e n t d i r e c t o r y or d r i v e .
Specification:
C D w i t h n o p a r a m e t e r s d i s p l a y s t h e n a m e of t h e c u r r e n t d i r e c t o r y . In t h e
f o r m a t list a b o v e , < d i r > i n d i c a t e s a n e w c u r r e n t d i r e c t o r y (that i s , o n e i n
w h i c h u n q u a l i f i e d f i l e n a m e s a r e l o o k e d u p ) . If t h e d i r e c t o r y y o u s p e c i f y is n o t
o n t h e c u r r e n t d r i v e , t h e n C D also c h a n g e s t h e c u r r e n t d r i v e .
T o c h a n g e t h e c u r r e n t d i r e c t o r y t o t h e d i r e c t o r y t h a t o w n s t h e c u r r e n t o n e (if
o n e e x i s t s ) , t y p e C D f o l l o w e d b y a single s l a s h (/). T h u s C D / m o v e s t h e
current directory o n e level u p in the hierarchy unless the current directory is a
r o o t d i r e c t o r y (that i s , t h e t o p level in t h e filing s y s t e m ) . M u l t i p l e s l a s h e s a r e
a l l o w e d ; e a c h s l a s h r e f e r s to a n a d d i t i o n a l level a b o v e .

Examples:

CD d f l : w o r k

s e t s t h e c u r r e n t d i r e c t o r y to " w o r k " o n disk " d f l " , a n d s e t s t h e c u r r e n t d r i v e

to " d f l " .
 AMIGADOS COMMANDS 45

CD S Y S : C O M / B A S I C
CD /

s e t s t h e c u r r e n t d i r e c t o r y to " S Y S : C O M " .

COPY
Format: COPY [[FROM]<name>][TO<name>][ALL][QUIET]
Template: COPY "FROM,TO/A,ALL/S,QUIET/S"
Purpose: T o c o p y a file o r d i r e c t o r y f r o m o n e p l a c e t o a n o t h e r .
Specification:
C O P Y p l a c e s a c o p y of t h e file o r d i r e c t o r y i n t h e file or d i r e c t o r y s p e c i f i e d a s
T O . T h e p r e v i o u s c o n t e n t s of T O , if a n y , are l o s t .
If y o u s p e c i f y a d i r e c t o r y n a m e a s F R O M , C O P Y c o p i e s all t h e files in t h e
F R O M d i r e c t o r y to t h e T O d i r e c t o r y . If y o u d o n o t s p e c i f y t h e F R O M d i r e c t o r y ,
A m i g a D O S u s e s t h e c u r r e n t directory. T h e T O directory m u s t exist for C O P Y to
w o r k ; it is n o t c r e a t e d b y C O P Y .
If y o u s p e c i f y A L L , C O P Y a l s o c o p i e s t h e files i n a n y s u b d i r e c t o r i e s . I n t h i s
c a s e , it a u t o m a t i c a l l y c r e a t e s s u b d i r e c t o r i e s in t h e T O d i r e c t o r y , a s r e q u i r e d .
T h e n a m e of t h e c u r r e n t file b e i n g c o p i e d is d i s p l a y e d o n t h e s c r e e n a s it
h a p p e n s u n l e s s y o u give t h e Q U I E T s w i t c h .
Y o u c a n also s p e c i f y t h e s o u r c e d i r e c t o r y a s a p a t t e r n . I n this c a s e , A m i g a D O S
c o p i e s a n y files t h a t m a t c h t h e p a t t e r n . S e e t h e c o m m a n d L I S T f o r a full
d e s c r i p t i o n of p a t t e r n s . Y o u m a y s p e c i f y d i r e c t o r y l e v e l s a s w e l l a s p a t t e r n s .

Examples:

C O P Y f U e l TO : w o r k / f i l e 2

copies 'filel' in the current directory to " f i l e 2 " in the directory " : w o r k " .

C O P Y TO d f l : b a c k u p

c o p i e s all t h e files i n t h e c u r r e n t d i r e c t o r y t o " d f L b a c k u p " . It d o e s n o t c o p y a n y

s u b d i r e c t o r i e s , a n d d f l : b a c k u p m u s t a l r e a d y exist.

C O P Y dfO: t o d f l : A L L Q U I E T

m a k e s a logical c o p y of d i s k " d f O " o n d i s k " d f l " w i t h o u t a n y r e f l e c t i o n of

filenames.

COPY t e s t - # ? to dfl:xyz

i
 46 AMIGADOS USER'S MANUAL

c o p i e s all files in t h e c u r r e n t d i r e c t o r y t h a t start " t e s t - " to t h e d i r e c t o r y x y z o n

t h e d i s k " d f l " , a s s u m i n g t h a t " x y z " a l r e a d y e x i s t s . (For a n e x p l a n a t i o n of p a t -
t e r n s , s u c h a s " # ? " , s e e t h e c o m m a n d L I S T in this c h a p t e r . )

COPY t e s t _ f i l e to PRT:

c o p i e s t h e file " t e s t file" to your printer.

C O P Y * TO CON: 1 0 / 1 0 / 2 0 0 / 1 0 0 /

C l i c k t h e w i n d o w t h a t y o u t y p e d t h e c o p y c o m m a n d i n t o . T h i s " r e a c t i v a t e s " it
s o t h a t c o n s o l e i n p u t is t a k e n f r o m t h e r e . E v e r y t i m e y o u t y p e a l i n e it will b e
displayed in the n e w w i n d o w . Press CTRLA w h e n you are d o n e a n d the n e w
w i n d o w will c l o s e .

C O P Y D F 0 : ? / # ? TO D F 1 : A L L

c o p i e s e v e r y file in a n y o n e c h a r a c t e r s u b d i r e c t o r y of DFO: t o t h e r o o t d i r e c t o r y
of D F 1 : .

See also: JOIN

DATE
Format: DATE [<date>][<time>][TO|VER<name>]
Template: DATE "DATE,TIME,TO = VER/K"
Purpose: T o d i s p l a y or s e t t h e s y s t e m d a t e or t i m e .
Specification:
D A T E with n o parameter displays the currently set system date a n d time. This
i n c l u d e s t h e d a y of t h e w e e k . T i m e is d i s p l a y e d u s i n g a 2 4 - h o u r c l o c k .
D A T E < d a t e > s e t s t h e d a t e . T h e f o r m of < d a t e > is D D - M M M - Y Y . If t h e
d a t e is a l r e a d y s e t , y o u c a n r e s e t it b y s p e c i f y i n g a d a y n a m e (this s e t s t h e d a t e
f o r w a r d to t h a t d a y ) or b y s p e c i f y i n g ' t o m o r r o w ' or ' y e s t e r d a y ' .
D A T E < t i m e > s e t s t h e t i m e . T h e f o r m of < t i m e > i s H H : M M (for H o u r s
and Minutes). You should use leading zeros w h e n necessary. Note that,
if y o u u s e a c o l o n (:), A m i g a D O S r e c o g n i z e s t h a t y o u h a v e s p e c i f i e d t h e t i m e
r a t h e r t h a n t h e d a t e . T h a t is t o s a y , y o u c a n s e t b o t h t h e d a t e a n d t h e t i m e , o r
e i t h e r d a t e o r t i m e in a n y o r d e r b e c a u s e D A T E o n l y r e f e r s to t h e t i m e w h e n
you use the form H H : M M .
If y o u d o n o t s e t t h e d a t e , t h e restart d i s k v a l i d a t i o n p r o c e s s s e t s t h e s y s t e m
d a t e to t h e d a t e of t h e m o s t r e c e n t l y c r e a t e d file. S e e C h a p t e r 1 for details o n t h e
restart validation process.
 AMIGADOS COMMANDS 47

To specify the destination of the verification, y o u u s e t h e equivalent k e y -

w o r d s T O a n d V E R . T h e d e s t i n a t i o n is t h e terminal u n l e s s y o u specify o t h e r w i s e .
N o t e : If y o u t y p e D A T E b e f o r e t h e r e s t a r t v a l i d a t i o n h a s c o m p l e t e d , t h e t i m e
is d i s p l a y e d as u n s e t . T o s e t t h e t i m e , y o u c a n e i t h e r u s e D A T E o r j u s t w a i t
u n t i l t h e v a l i d a t i o n p r o c e s s is f i n i s h e d .

Examples:
DATE

displays the current date.

DATE 06-Sep-82

s e t s t h e d a t e to t h e 6 t h o f S e p t e m b e r 1 9 8 2 . T h e t i m e is n o t r e s e t .

DATE t o m o r r o w

resets the date to one day ahead.

D A T E TO f r e d

s e n d s t h e c u r r e n t d a t e to t h e file " f r e d " .

DATE 10:50

s e t s t h e c u r r e n t t i m e to t e n 'til e l e v e n .

DATE 2 3 : 0 0

s e t s t h e c u r r e n t t i m e to 1 1 : 0 0 P.M.

DATE 0 1 - J A N - 0 2

s e t s t h e d a t e to J a n u a r y 1st, 2 0 0 2 . ( T h e earliest d a t e y o u c a n s e t is 0 1 - J A N - 7 8 . )

DELETE
Format: DELETE <name>[<name>*][ALL][Q|QUIET]
Template: DELETE " „ „ „ „ „ A L L / S , Q = QUIET/S"
Purpose: T o d e l e t e u p to t e n files or d i r e c t o r i e s .
Specification:
D E L E T E a t t e m p t s to d e l e t e e a c h file y o u s p e c i f y . If it c a n n o t d e l e t e a f i l e ,
the screen displays a m e s s a g e , and A m i g a D O S attempts to delete the next
file i n t h e list. Y o u m a y n o t d e l e t e a d i r e c t o r y if it c o n t a i n s a n y files.
48 AMIGADOS USER'S MANUAL

Y o u c a n also u s e a p a t t e r n to s p e c i f y t h e f i l e n a m e . S e e t h e d e s c r i p t i o n of t h e
c o m m a n d L I S T for full details of p a t t e r n s . T h e p a t t e r n m a y s p e c i f y d i r e c t o r y
l e v e l s as w e l l a s f i l e n a m e s . In this c a s e , all files t h a t m a t c h t h e p a t t e r n a r e
deleted.
If y o u s p e c i f y A L L w i t h a d i r e c t o r y n a m e , D E L E T E will d e l e t e t h a t d i r e c t o r y
a n d all s u b d i r e c t o r i e s a n d files w i t h i n t h a t d i r e c t o r y a n d its s u b d i r e c t o r i e s .
U n l e s s y o u s p e c i f y t h e s w i t c h Q U I E T (or u s e t h e a l t e r n a t i v e , Q ) , t h e n a m e of
t h e file b e i n g d e l e t e d a p p e a r s o n t h e s c r e e n a s it h a p p e n s .

Examples:

D E L E T E old-file

d e l e t e s t h e file " o l d - f i l e " .

DELETE work/prog 1 work/prog2 work

d e l e t e s t h e files " p r o g l " a n d " p r o g 2 " i n t h e directory " w o r k " , a n d t h e n d e l e t e s

the directory " w o r k " .

DELETE t#?/#?(H2)

d e l e t e s all t h e files t h a t e n d in " 1 " or "2" i n directories t h a t start w i t h " t " . ( F o r

a n explanation of patterns, such as " # ? " , see the c o m m a n d LIST later in this
chapter.)

DELETE D F 1 : # ? ALL

d e l e t e s all t h e files o n D F 1 : .

See also: D I R ( 1 - D E L o p t i o n )

DIR
Format: D I R [ < n a m e > ] [ O P T A|I|AI]
Template: DIR "DIR,OPT/K"
Purpose: T o p r o v i d e a d i s p l a y of t h e files in a d i r e c t o r y i n s o r t e d o r d e r . D I R
c a n also i n c l u d e t h e files i n s u b d i r e c t o r i e s , a n d y o u c a n u s e D I R in
interactive m o d e .
Specification:
D I R a l o n e s h o w s t h e files in t h e c u r r e n t d i r e c t o r y . D I R f o l l o w e d b y a d i r e c t o r y
p r o v i d e s t h e files i n t h a t d i r e c t o r y . T h e f o r m of t h e d i s p l a y is first a n y
 AMIGADOS COMMANDS 49

s u b d i r e c t o r i e s , f o l l o w e d b y a s o r t e d list o f t h e files in t w o c o l u m n s . If y o u w a n t
to k n o w if a file e x i s t s t y p e L I S T f i l e n a m e .
T y p i n g D I R f i l e n a m e , w h e r e f i l e n a m e is a file w h i c h e x i s t s r e s u l t s in t h e
A m i g a r e s p o n d i n g w i t h : " f i l e n a m e is n o t a d i r e c t o r y . "
T o pass options to DIR, use the O P T k e y w o r d . U s e the A option to include
a n y s u b d i r e c t o r i e s b e l o w t h e s p e c i f i e d o n e i n t h e list. E a c h s u b l i s t o f files is
indented.
T o list o n l y t h e d i r e c t o r y n a m e s u s e t h e D o p t i o n .
T h e I o p t i o n s p e c i f i e s t h a t D I R is to r u n in i n t e r a c t i v e m o d e . I n t h i s c a s e , t h e
files a n d d i r e c t o r i e s a r e d i s p l a y e d w i t h a q u e s t i o n m a r k f o l l o w i n g e a c h n a m e .
P r e s s R E T U R N to d i s p l a y t h e n e x t n a m e in t h e list. T o quit t h e p r o g r a m , t y p e
Q . T o g o b a c k to t h e p r e v i o u s d i r e c t o r y l e v e l o r t o s t o p (if a t t h e l e v e l o f t h e
initial d i r e c t o r y ) , t y p e B .
If t h e n a m e d i s p l a y e d is t h a t o f a d i r e c t o r y , t y p e E to e n t e r t h a t d i r e c t o r y a n d
d i s p l a y t h e files a n d s u b d i r e c t o r i e s . U s e E a n d B to s e l e c t d i f f e r e n t l e v e l s .
T y p i n g t h e c o m m a n d D E L (that i s , t y p i n g t h e t h r e e l e t t e r s D E L , n o t p r e s s i n g
t h e D E L k e y ) c a n b e u s e d to d e l e t e a d i r e c t o r y , b u t t h i s o n l y w o r k s if t h e
d i r e c t o r y is e m p t y .
If t h e n a m e is t h a t o f a file, t y p i n g D E L d e l e t e s t h e file, or t y p i n g T T y p e s
( t h a t i s , d i s p l a y s ) t h e file o n t h e s c r e e n . I n t h e last c a s e , p r e s s C T R L - C to s t o p
it " t y p i n g " a n d r e t u r n t o i n t e r a c t i v e m o d e .
T o f i n d t h e p o s s i b l e r e s p o n s e s to a n i n t e r a c t i v e r e q u e s t , t y p e ? .

Examples:

DIR

p r o v i d e s a list o f files in c u r r e n t d i r e c t o r y .

D I R dfO: OPT a

lists t h e e n t i r e d i r e c t o r y s t r u c t u r e o f t h e d i s k " d f O " .

DISKCOPY
Format: DISKCOPY [FROM]<disk>TO<disk>[NAME <name>]
Template: DISKCOPY "FROM/A,TO/A/K,NAME/K''
Purpose: T o c o p y t h e c o n t e n t s o f o n e 3-Vi i n c h f l o p p y d i s k t o a n o t h e r .
Specifications:
D I S K C O P Y m a k e s a c o p y of the entire contents of the disk y o u specified as
F R O M , overwriting the previous contents of t h e entire disk y o u specified as
50 AMIGADOS USER'S MANUAL

T O . D I S K C O P Y a l s o f o r m a t s a n e w d i s k as it c o p i e s . Y o u n o r m a l l y u s e t h e
c o m m a n d to p r o d u c e b a c k u p f l o p p y d i s k s .
O n c e y o u h a v e g i v e n t h e c o m m a n d , A m i g a D O S p r o m p t s y o u to i n s e r t t h e
correct disks. At this point, you insert the correct source a n d destination disks.
Y o u c a n u s e t h e c o m m a n d to c o p y a n y 3-V2 i n c h A m i g a D O S d i s k to a n o t h e r ,
b u t t h e s o u r c e a n d d e s t i n a t i o n d i s k s m u s t b e i d e n t i c a l in size a n d s t r u c t u r e . T o
c o p y information b e t w e e n different sized disks, y o u use C O P Y .
Y o u c a n a l s o u s e t h e c o m m a n d to c o p y a f l o p p y d i s k u s i n g a s i n g l e f l o p p y
d r i v e . If y o u s p e c i f y t h e s o u r c e a n d d e s t i n a t i o n a s t h e s a m e d e v i c e , t h e n t h e
p r o g r a m r e a d s in as m u c h of t h e s o u r c e d i s k i n t o m e m o r y as p o s s i b l e . It t h e n
p r o m p t s y o u to p l a c e t h e d e s t i n a t i o n disk i n t h e drive a n d t h e n c o p i e s t h e
i n f o r m a t i o n f r o m m e m o r y o n t o t h e d e s t i n a t i o n d i s k . T h i s s e q u e n c e is r e p e a t e d
as m a n y t i m e s a s r e q u i r e d .
If y o u d o n o t s p e c i f y a n e w n a m e for y o u r d i s k , D I S K C O P Y c r e a t e s a n e w
d i s k w i t h t h e s a m e n a m e as t h e old o n e . H o w e v e r , A m i g a D O S c a n tell t h e
d i f f e r e n c e b e t w e e n t w o d i s k s w i t h t h e s a m e n a m e b e c a u s e e v e r y d i s k is
a s s o c i a t e d w i t h t h e d a t e a n d t i m e of its c r e a t i o n . D I S K C O P Y g i v e s t h e n e w
d i s k t h e c u r r e n t s y s t e m d a t e as its c r e a t i o n d a t e a n d t i m e .
N o t e : T o c o p y p a r t of a d i s k , y o u c a n u s e C O P Y t o R A M : .

Examples:

D I S K C O P Y F R O M dfO: TO d f l :

m a k e s a b a c k u p c o p y of t h e d i s k " d f O " o n t o d i s k " d f l " .

D I S K C O P Y F R O M dfO: T o dfO:

m a k e s a b a c k u p c o p y of t h e d i s k in drive " d f O " u s i n g o n l y a s i n g l e d r i v e .

See also: COPY

ECHO
Format: ECHO <string>
Template: ECHO " "
Purpose: T o display the argument given.
Specification:
E C H O w r i t e s t h e s i n g l e a r g u m e n t to t h e c u r r e n t o u t p u t s t r e a m ( w h i c h c a n b e a
file or a d e v i c e ) . T h i s is n o r m a l l y o n l y u s e f u l w i t h i n a c o m m a n d s e q u e n c e or a s
p a r t of a R U N c o m m a n d . If y o u give t h e a r g u m e n t i n c o r r e c t l y , a n e r r o r is
displayed.
 AMIGADOS COMMANDS 51

Examples:

RUN" C O P Y : w o r k / p r o g t o d f l : w o r k A L L Q U I E T +
ECHO "Copy f i n i s h e d "

c r e a t e s a n e w C L I to c o p y t h e s p e c i f i e d d i r e c t o r y a s a b a c k g r o u n d p r o c e s s .
W h e n it h a s f i n i s h e d , t h e s c r e e n d i s p l a y s

Copy finished

If t h e f o l l o w i n g E x e c u t e file e x i s t s

ECHO " S t a r t i n g 'MYCOPY' E x e c u t e file"

C O P Y D F 1 : A B C TO R A M : A B C
C O P Y D F L X Y Z TO R A M : X Y Z
ECHO " R e m o v e t h e diskette i n D F 1 : "
ECHO " I n s e r t t h e n e w diskette i n D F 1 : "
WAIT 1 0 SECS
C O P Y R A M : A B C TO D F 1 : A B C
C O P Y R A M : X Y Z TO D F 1 : A B C
ECHO " D o n e "

then

EXECUTE MYCOPY

c o p i e s 2 files to R A M d i s k a n d b a c k .

ED
Format: ED[FROM]<name>[SIZE<n>]
Template: ED "FROM/A, SIZE"
Purpose: T o e d i t t e x t files.
Specification:
E D is a s c r e e n e d i t o r . Y o u c a n u s e E D as a n a l t e r n a t i v e to t h e line e d i t o r E D I T .
T h e file y o u specify as F R O M is r e a d into m e m o r y , t h e n E D a c c e p t s y o u r editing
i n s t r u c t i o n s . If F R O M f i l e n a m e d o e s n o t exist, A m i g a D O S c r e a t e s a n e w file.
B e c a u s e t h e file is r e a d i n t o m e m o r y , t h e r e is a limit t o t h e s i z e o f file y o u c a n
e d i t w i t h E D . U n l e s s y o u s p e c i f y o t h e r w i s e , w o r k s p a c e size is 4 0 , 0 0 0 b y t e s .
T h i s w o r k s p a c e size is u s u a l l y s u f f i c i e n t for m o s t files. H o w e v e r , to a l t e r t h e
w o r k s p a c e , y o u s p e c i f y a s u i t a b l e v a l u e after t h e S I Z E k e y w o r d .
T h e r e is a full s p e c i f i c a t i o n of E D in C h a p t e r 3 .
52 AMIGADOS USER'S MANUAL

Examples:

ED work/prog

e d i t s t h e file " w o r k / p r o g " , a s s u m i n g it e x i s t s ; o t h e r w i s e , E D c r e a t e s t h e file.

ED huge-file SIZE 5 0 0 0 0

e d i t s a v e r y l a r g e file " h u g e - f i l e " , u s i n g a w o r k s p a c e of 5 0 , 0 0 0 b y t e s .

EDIT
Format: EDIT [ F R O M ] < n a m e > [ [ T O ] < n a m e > ] [ W I T H < n a m e > ] [ V E R < n a m e > ]
[OPT<option>]
Template: EDIT "FROM/A,TO,WITH/K,VER/K,OPT/K"
Purpose: T o e d i t t e x t files.
Specification:
E D I T is a l i n e e d i t o r ( t h a t i s , it e d i t s a s e q u e n t i a l file line b y l i n e ) . If y o u s p e c i f y
T O , E D I T c o p i e s f r o m file F R O M to file T O . O n c e y o u h a v e c o m p l e t e d t h e
e d i t i n g , t h e file T O c o n t a i n s t h e e d i t e d r e s u l t , a n d t h e file F R O M is u n c h a n g e d .
I f y o u d o n o t s p e c i f y T O , t h e n E D I T w r i t e s t h e e d i t e d t e x t t o a t e m p o r a r y file.
If y o u g i v e t h e E D I T c o m m a n d s Q or W , t h e n E D I T r e n a m e s t h i s t e m p o r a r y file
F R O M , h a v i n g first s a v e d t h e o l d v e r s i o n of F R O M in t h e file " : t / e d i t - b a c k u p " .
If y o u g i v e t h e E D I T c o m m a n d S T O P , t h e n E D I T m a k e s n o c h a n g e to t h e file
FROM.
E D I T r e a d s c o m m a n d s f r o m t h e c u r r e n t i n p u t s t r e a m , or f r o m a W I T H file if
it is s p e c i f i e d .
E D I T s e n d s e d i t o r m e s s a g e s a n d v e r i f i c a t i o n o u t p u t to t h e file y o u s p e c i f y
w i t h V E R . If y o u o m i t V E R , t h e t e r m i n a l is u s e d i n s t e a d .
O P T s p e c i f i e s o p t i o n s : P n s e t s t h e m a x i m u m n u m b e r o f p r e v i o u s l i n e s to n ;
W n s e t s t h e m a x i m u m line w i d t h . T h e initial s e t t i n g is P 4 O W 1 2 0 .
Note: You cannot use the < and > s y m b o l s to r e d i r e c t i n p u t a n d o u t p u t
w h e n y o u call E D I T .
S e e C h a p t e r 4 for a full s p e c i f i c a t i o n o f E D I T .

Examples:

EDIT work/prog

e d i t s t h e file " w o r k / p r o g " . When e d i t i n g is c o m p l e t e , E D I T s a v e s t h e old

v e r s i o n o f " w o r k / p r o g " in " : t / e d i t - b a c k u p " .
 AMIGADOS COMMANDS 53

EDIT work/prog TO work/newprog

e d i t s t h e file " w o r k / p r o g " , p l a c i n g t h e e d i t e d r e s u l t in t h e file " w o r k / n e w p r o g " .

EDIT work/prog WITH edits/O VER nil:

e d i t s t h e file " w o r k / p r o g " w i t h t h e edit c o m m a n d s s t o r e d i n t h e file " e d i t s / 0 " .

V e r i f i c a t i o n o u t p u t f r o m E D I T is s e n t to t h e d u m m y d e v i c e " n i l : " .

ENDCLI
Format: ENDCLI
Template: ENDCLI
Purpose: To e n d a n interactive CLI process.
Specification:
A m i g a D O S only allows E N D C L I as an interactive c o m m a n d . E N D C L I r e m o v e s
the CLI currently selected by the mouse.
You shouldn't use E N D C L I except on a CLI created by the N E W C L I com-
m a n d . If t h e initial C L I ( p r o c e s s 1) is e n d e d , a n d n o o t h e r h a s b e e n s e t u p b y
t h e N E W C L I c o m m a n d , t h e n t h e e f f e c t is to t e r m i n a t e t h e A m i g a D O S s e s s i o n .
N o t e t h a t t h e r e a r e n o a r g u m e n t s to t h e E N D C L I c o m m a n d , a n d n o c h e c k
for invalid a r g u m e n t s .
Note: Do not experiment with E N D C L I before you've used N E W C L I . Using
E N D C L I o n t h e initial C L I a l w a y s p u l l s t h e r u g o u t f r o m u n d e r y o u b y
t e r m i n a t i n g t h a t C L I . If y o u s t a r t e d t h e C L I f r o m t h e W o r k b e n c h , t h e n t h e r e is
n o p r o b l e m a s y o u a r e r e t u r n e d to t h e W o r k b e n c h . If y o u s t a r t e d A m i g a D O S
w i t h just t h e C L I r u n n i n g , t h e n ending the last C L I gives y o u n o w a y of
creating a n e w one.

Examples:
T h e following sequence:

NEWCLI
LIST
ENDCLI

o p e n s a n e w w i n d o w , lists t h e d i r e c t o r y , a n d c l o s e s t h e w i n d o w a g a i n .
54 AMIGADOS USER'S M A N U A L

EXECUTE
Format: EXECUTE <commandfile>[<arg>*]
Template: EXECUTE "command-file","args"
Purpose: T o e x e c u t e a file of c o m m a n d s w i t h a r g u m e n t s u b s t i t u t i o n .
Specification:
Y o u n o r m a l l y u s e E X E C U T E t o s a v e t y p i n g . T h e c o m m a n d file c o n t a i n s c o m -
m a n d s executed by the C o m m a n d Line Interface. A m i g a D O S executes these
c o m m a n d s o n e at a t i m e , j u s t a s t h o u g h y o u h a d t y p e d t h e m at t h e k e y b o a r d .
If t h e e x e c u t i o n c r e a t e s a n e w C L I w i n d o w , t h e r e s u l t s m a y n o t b e i d e n t i c a l t o
t y p i n g at t h e k e y b o a r d .
Y o u can also u s e E X E C U T E to p e r f o r m p a r a m e t e r (that is, value) sub-
stitution, where you can give certain n a m e s as p a r a m e t e r s . Before the
c o m m a n d file is e x e c u t e d , A m i g a D O S c h e c k s t h e p a r a m e t e r n a m e s w i t h t h o s e
y o u ' v e g i v e n a f t e r t h e E X E C U T E c o m m a n d . If a n y m a t c h , A m i g a D O S uses
t h e v a l u e s y o u s p e c i f i e d i n s t e a d of t h e p a r a m e t e r n a m e . P a r a m e t e r s may
h a v e v a l u e s s p e c i f i e d t h a t A m i g a D O S u s e s if y o u d o n o t explicitly s e t t h e
p a r a m e t e r . If y o u h a v e n o t s p e c i f i e d a p a r a m e t e r , a n d if t h e r e is n o d e f a u l t ,
t h e n t h e v a l u e of t h e p a r a m e t e r is e m p t y a n d n o t h i n g is s u b s t i t u t e d for
it.
T o u s e p a r a m e t e r s u b s t i t u t i o n , y o u give directives to t h e E X E C U T E c o m -
m a n d . T o i n d i c a t e t h e s e , y o u start a line w i t h a s p e c i a l c h a r a c t e r , w h i c h is
initially a p e r i o d o r " d o t " (.). T h e d i r e c t i v e s a r e as f o l l o w s :

.KEY A r g u m e n t t e m p l a t e , u s e d to s p e c i f y
t h e f o r m a t of t h e a r g u m e n t s , m a y b e a b b r e v i a t e d
to . K
.DOT ch C h a n g e dot character (initially".") to ch
.BRA ch C h a n g e b r a c h a r a c t e r (initially " < " ) t o c h
.KET ch C h a n g e k e t c h a r a c t e r (initially " > " ) t o c h
.DOLLAR ch C h a n g e d e f a u l t - c h a r (initially " $ " ) to c h , m a y b e
abbreviated to . D O L
.DEF k e y w o r d v a l u e G i v e d e f a u l t to p a r a m e t e r
.<space> C o m m e n t line
.<newline> B l a n k c o m m e n t line

B e f o r e e x e c u t i o n , A m i g a D O S s c a n s t h e c o n t e n t s of t h e file for a n y i t e m s
enclosed by B R A and K E T characters ( " < " and " > " ) . Such items m a y consist
of a k e y w o r d or a k e y w o r d a n d a default v a l u e for A m i g a D O S to u s e if y o u h a v e
left t h e k e y w o r d u n s e t . (To s e p a r a t e t h e k e y w o r d a n d t h e d e f a u l t , if t h e r e is
o n e , y o u t y p e a dollar s i g n " $ " ) . T h u s , A m i g a D O S r e p l a c e s < A N I M A L > w i t h
 AMIGADOS COMMANDS 55

t h e v a l u e y o u a s s o c i a t e d w i t h t h e k e y w o r d A N I M A L , w h i l e it r e p l a c e s
< A N I M A L $ W O M B A T > w i t h t h e v a l u e of A N I M A L if it h a s o n e , a n d o t h e r -
w i s e it d e f a u l t s to W O M B A T .
A file c a n o n l y u s e t h e d o t c o m m a n d s if t h e first l i n e h a s a d o t c o m m a n d
o n it. T h e C L I l o o k s at t h e first l i n e . If it s t a r t s w i t h a d o t c o m m a n d ,
f o r e x a m p l e , a c o m m e n t ( . < s p a c e > t x t ) t h e n t h e C L I s c a n s t h e file l o o k i n g
f o r p a r a m e t e r s u b s t i t u t i o n a n d b u i l d s a t e m p o r a r y file in t h e :T d i r e c t o r y .
If t h e file d o e s n ' t start w i t h a d o t c o m m a n d , t h e n it is a s s u m e d t h a t t h e r e
a r e N O d o t c o m m a n d s i n t h e file, w h i c h a l s o m e a n s n o p a r a m e t e r s u b s t i -
t u t i o n is p e r f o r m e d . F o r t h e n o - d o t c a s e , t h e C L I starts e x e c u t i n g t h e file
d i r e c t l y w i t h o u t h a v i n g t o c o p y it t o : T . N o t e t h a t y o u c a n still e m b e d
c o m m e n t s in a n e x e c u t e file b y u s i n g t h e C L I ' s c o m m e n t c h a r a c t e r , t h e
s e m i c o l o n (;). If y o u d o n ' t n e e d p a r a m e t e r s u b s t i t u t i o n a n d d o t c o m m a n d s ,
d o n ' t use t h e m . T h e y save you extra accesses to the disk for the t e m p o r a r y
file.
A m i g a D O S p r o v i d e s a n u m b e r of c o m m a n d s t h a t a r e o n l y u s e f u l in c o m -
m a n d s e q u e n c e files. T h e s e i n c l u d e I F , S K I P , L A B , a n d Q U I T . T h e s e c a n b e
n e s t e d in a c o m m a n d file.
N o t e t h a t y o u c a n also n e s t E X E C U T E files. T h a t is, y o u c a n h a v e a c o m -
m a n d file t h a t c o n t a i n s E X E C U T E c o m m a n d s .
T o s t o p t h e e x e c u t i o n of a c o m m a n d file, y o u p r e s s C T R L - D . If y o u a r e
n e s t i n g c o m m a n d files, t h a t i s , if o n e c o m m a n d file calls a n o t h e r , y o u c a n s t o p
t h e e n t i r e s e t of E X E C U T E c o m m a n d s b y p r e s s i n g C T R L - C . C T R L - D o n l y s t o p s
t h e c u r r e n t c o m m a n d file f r o m e x e c u t i n g .

Examples:

A s s u m e t h e file " l i s t " c o n t a i n s t h e f o l l o w i n g :

.k f i l e n a m e / a
r u n copy < f i l e n a m e > to prt: +
echo "Printing of < f i l e n a m e > done"

T h e n the following c o m m a n d

EXECUTE list test/prg

a c t s a s t h o u g h y o u h a d t y p e d t h e f o l l o w i n g c o m m a n d s at t h e k e y b o a r d .
RUN copy test/prg to prt: +
ECHO " P r i n t i n g of test/prg done"

A n o t h e r e x a m p l e , " d i s p l a y " , u s e s m o r e of t h e f e a t u r e s d e s c r i b e d a b o v e :
56 AMIGADOS USER'S MANUAL

.key n a m e / a
IF EXISTS < n a m e >
T Y P E < n a m e > OPT n (If t h e file g i v e n is o n t h e c u r r e n t d i r e c t o r y , t y p e it
w i t h line n u m b e r s )
ELSE
ECHO " < n a m e > is n o t o n t h i s d i r e c t o r y "
ENDIF

RUN EXECUTE display work/prg2

s h o u l d d i s p l a y t h e file w o r k / p r g 2 w i t h line n u m b e r s o n t h e t e r m i n a l if it exists

o n t h e c u r r e n t d i r e c t o r y . If t h e file is n o t t h e r e , t h e s c r e e n d i s p l a y s t h e
following message:

work/prg2 is not on this directory.

See also: ;,IF,SKIP,FAILAT,LAB,ECHO,RUN,QUIT

Additional Examples for the EXECUTE Command:

Example # 2
Parameter Substitution by Keyword Name and/or Position
T h e . K E Y (or . K ) s t a t e m e n t s u p p l i e s b o t h k e y w o r d n a m e s a n d p o s i t i o n s in
c o m m a n d files. It tells E X E C U T E h o w m a n y p a r a m e t e r s t o e x p e c t a n d h o w t o
i n t e r p r e t t h e m . I n o t h e r w o r d s , . K E Y s e r v e s as a " t e m p l a t e " f o r t h e p a r a m e t e r
v a l u e s y o u s p e c i f y . O n l y o n e . K E Y s t a t e m e n t is a l l o w e d p e r c o m m a n d file. If
p r e s e n t , it s h o u l d b e t h e first c o m m a n d line in t h e file.
W h e n y o u enter a c o m m a n d line, A m i g a D O S resolves parameter substitu-
tions for t h e k e y w o r d s in t w o w a y s : b y specification of the k e y w o r d in front of
t h e p a r a m e t e r , a n d b y t h e relative p o s i t i o n s o f t h e p a r a m e t e r s in t h e l i n e .
Keyword n a m e substitution takes precedence.
A s s u m e t h a t t h e e x e c u t e file n a m e d D E M O l c o n t a i n s t h e f o l l o w i n g . K E Y
statement:

.KEY flash,pan

tells A m i g a D O S to e x p e c t t w o p a r a m e t e r s u b s t i t u t i o n s , < f l a s h > a n d < p a n > .

( T h e a n g l e b r a c k e t s i n d i c a t e t h e k e y w o r d v a l u e to b e s u b s t i t u t e d at e x e c u t i o n
time.)
S u p p o s e y o u e n t e r t h e f o l l o w i n g c o m m a n d line:
 AMIGADOS COMMANDS 57

EXECUTE DEM01 pan somename flash other-name

T h e v a l u e " o t h e r n a m e " is a s s i g n e d to < f l a s h > , a n d t h e v a l u e " s o m e n a m e " is

assigned to < p a n > .
Y o u c a n o m i t t h e k e y w o r d n a m e s if t h e p a r a m e t e r s u b s t i t u t i o n s a r e i n t h e
o r d e r g i v e n i n t h e . K E Y s t a t e m e n t . F o r e x a m p l e , t h e f o l l o w i n g s t a t e m e n t is
equivalent to the preceding one:

EXECUTE DEMOl othername somename

T h i s is b e c a u s e t h e v a l u e s c o r r e s p o n d to t h e k e y w o r d o r d e r s p e c i f i e d in t h e
.KEY statement.
Y o u c a n a l s o m i x t h e t w o m e t h o d s of p a r a m e t e r s u b s t i t u t i o n . S u p p o s e y o u
h a v e a .KEY statement with several parameters, as follows:

.KEY wordl, word2, word3, word4

T h e e x e c u t e file p r o c e s s o r r e m o v e s p a r a m e t e r n a m e s f r o m t h e i n p u t l i n e
to fill t h e m e a n i n g s of a n y k e y w o r d v a l u e s it f i n d s . T h e n , w i t h a n y r e m a i n i n g
i n p u t , it fills t h e l e f t o v e r k e y w o r d p o s i t i o n s a c c o r d i n g to t h e p o s i t i o n of t h e
input value.
For example:

EXECUTE DEM02 word3 ccc wordl aaa bbb ddd

T h e processor assigns ccc to < w o r d 3 > , aaa to < w o r d l > , a n d h a s t w o

p a r a m e t e r s left o v e r . S c a n n i n g f r o m left t o r i g h t in t h e . K E Y s t a t e m e n t , it f i n d s
t h a t < w o r d 2 > is still u n a s s i g n e d . T h u s , < w o r d 2 > g e t s t h e n e x t i n p u t w o r d ,
b b b . F i n a l l y , < w o r d 4 > h a s n ' t b e e n a s s i g n e d e i t h e r , s o it g e t s t h e l a s t i n p u t
word, ddd.
Y o u can indicate special conditions for parameter substitution, as follows:

.KEY namel/a, name2/a, name3, name4/k

T h e "la." i n d i c a t e s t h a t a v a l u e m u s t b e s u p p l i e d to fill t h e p a r a m e t e r s f o r
n a m e l a n d n a m e 2 . V a l u e s f o r n a m e 3 a n d n a m e 4 a r e o p t i o n a l , t h o u g h t h e "Ik"
i n d i c a t e s t h a t < n a m e 4 > (if s u p p l i e d ) m u s t b e p r e c e d e d b y t h e explicit k e y w o r d
" n a m e 4 . " For example:

EXECUTE DEM03 fee fie foe name4 fum

If t h e u s e r d o e s n o t s u p p l y a r e q u i r e d p a r a m e t e r ( s u c h a s n a m e l or n a m e 2 in
the preceding example), E X E C U T E issues an error m e s s a g e .
58 AMIGADOS USER'S MANUAL

A s a n e x a m p l e o f t h e u s e o f t h e /k o p t i o n , s u p p o s e y o u h a v e c r e a t e d a n
e x e c u t e file n a m e d C O M P I L E a n d it lets y o u o p t i o n a l l y s p e c i f y a f i l e n a m e to
w h i c h a p r i n t o u t o f t h e c o m p i l a t i o n is to b e d i r e c t e d . Y o u r . k e y statement
might read:

.key compilewhat/a,printfile/k

If a u s e r e n t e r s a l i n e s u c h a s :

EXECUTE COMPILE myfile PRINTFILE myprint

t h e e x e c u t e file s a y s t h e k e y w o r d P R I N T F I L E is o p t i o n a l a n d n e e d n o t b e
s u p p l i e d , b u t if u s e d , t h e r e m u s t b e a v a l u e e n t e r e d a l o n g w i t h it. Thus
t h e a b o v e l i n e is c o r r e c t , s i n c e m y p r i n t is s p e c i f i e d a s t h e t a r g e t output
file.

Example # 2
Assigning Default Parameters and Different Bracket Characters
.KEY wordl

T h e . D E F d i r e c t i v e e s t a b l i s h e s a d e f a u l t v a l u e for a k e y w o r d if t h e u s e r d o e s
not specify a value on the c o m m a n d line. T o detect an unsupplied parameter
v a l u e , y o u c a n c o m p a r e it t o " " (two double-quotes in a row). Y o u must
p e r f o r m t h i s c o m p a r i s o n b e f o r e e x e c u t i n g a n y . D E F s t a t e m e n t in t h e e x e c u t e
file.
Y o u c a n a s s i g n d e f a u l t s i n e i t h e r o f t w o w a y s . T h e first w a y r e q u i r e s t h a t
y o u specify the default every time y o u reference a parameter, using the " $ "
operator.
For example, in the following statement:

ECHO "<wordl$defwordl> is the default for Wordl."

" d e f w o r d l " is t h e d e f a u l t s p e c i f i e d for w o r d l a n d is p r i n t e d w h e n t h e a b o v e

s t a t e m e n t e x e c u t e s . T h e s e c o n d w a y is t o d e f i n e a d e f a u l t o n c e . F o r e x a m p l e ,
with the following assignment:

.DEF wordl "defwordl"

you can execute the following statement:

ECHO " < w o r d l > is the default for Wordl."

 AMIGADOS COMMANDS 59

T h e o u t p u t of b o t h of t h e a b o v e E C H O s t a t e m e n t s will b e :

defwordl is the default for Wordl.

N o t e t h a t a s e c o n d u s e of . D E F f o r a g i v e n p a r a m e t e r h a s n o effect:

.DEF wordl a New default

ECHO " < w o r d l > is STILL the default for Wordl."

( T h e first a s s i g n m e n t , " d e f w o r d l " will b e s u b s t i t u t e d f o r w o r d l a t e x e c u t i o n

time.)

Assigning Different Bracket Characters

W h e r e v e r E X E C U T E f i n d s e n c l o s i n g a n g l e b r a c k e t s , it l o o k s w i t h i n t h e m t o s e e
if it c a n s u b s t i t u t e a p a r a m e t e r . A n u n s u p p l i e d p a r a m e t e r w i t h n o d e f a u l t
b e c o m e s a " n u l l " string.
S u p p o s e y o u w a n t to u s e a s t r i n g t h a t c o n t a i n s t h e a n g l e b r a c k e t c h a r a c t e r s ,
< a n d > . Y o u c a n u s e t h e directives . B R A a n d . K E T to d e f i n e s u b s t i t u t e s f o r
the bracket characters. For example,

ECHO "This line does WOT print <angle> brackets."

.BRA{
.KET }
ECHO "This line DOES print <angle> brackets."
ECHO "The default for wordl is {wordl}."
T h e first E C H O s t a t e m e n t c a u s e s t h e p r o c e s s o r to l o o k for t h e p a r a m e t e r
s u b s t i t u t i o n f o r " a n g l e , " s i n c e t h a t ' s t h e c u r r e n t m e a n i n g of t h e a n g l e b r a c k e t
c h a r a c t e r s . S i n c e " a n g l e " w a s n ' t i n c l u d e d in t h e . K E Y s t a t e m e n t , t h e p r o c e s s o r
s u b s t i t u t e s t h e n u l l s t r i n g for it. T h e n , a f t e r t h e . B R A a n d . K E T d i r e c t i v e s
r e d e f i n e t h e b r a c k e t c h a r a c t e r s , the s e c o n d E C H O s t a t e m e n t prints t h e c h a r a c t e r s :

This line DOES print <angle> brackets.

T h e t h i r d E C H O s t a t e m e n t illustrates that t h e b r a c e s ( { a n d } ) n o w f u n c t i o n
t o e n c l o s e k e y w o r d s f o r t h e p u r p o s e of p a r a m e t e r s u b s t i t u t i o n .

Example # 3
Showing Command File Structures
T h e I F s t a t e m e n t lets y o u p e r f o r m t e s t s a n d c a u s e d i f f e r e n t a c t i o n s b a s e d o n
t h e r e s u l t s of t h o s e t e s t s . A m o n g t h e p o s s i b l e t e s t s a r e t e s t i n g s t r i n g s f o r
e q u a l i t y a n d t e s t i n g t o s e e if a file e x i s t s . Y o u c a n u s e a n E L S E s t a t e m e n t w i t h
60 AMIGADOS USER'S MANUAL

a n I F to s p e c i f y w h a t s h o u l d b e d o n e i n c a s e t h e I F c o n d i t i o n is n o t t r u e . T h e
E L S E s t a t e m e n t , if u s e d , is c o n s i d e r e d a p a r t o f t h e I F s t a t e m e n t b l o c k . An
E N D I F t e r m i n a t e s a n IF s t a t e m e n t b l o c k .
T h e example programs below also use a SKIP statement. T h e SKIP statement
l e t s y o u s k i p F O R W A R D O N L Y w i t h i n y o u r e x e c u t e file to a l a b e l d e f i n e d b y a
LAB statement.
T h e I F . . . E N D I F s t r u c t u r e is i l l u s t r a t e d b y t h e f o l l o w i n g s h o r t e x a m p l e . It is
g e n e r a l l y a g o o d i d e a t o t e s t f o r k e y w o r d s t h a t m i g h t b e o m i t t e d , or m i g h t b e
entered as null ( " " ) in quotes, as s h o w n below:

IF " < w o r d l > " EQ "usage"

SKIP USAGE
ENDIF
IF " < w o r d 2 > " EQ ""
SKIP USAGE
ENDIF

E n c l o s i n g y o u r p a r a m e t e r s u b s t i t u t i o n w o r d s in d o u b l e q u o t e s w i t h i n IF
statements prevents EXECUTE f r o m r e p o r t i n g a n e r r o r if t h e k e y w o r d is
omitted.
If y o u o m i t t h e d o u b l e q u o t e s a n d t h e v a l u e is n o t s u p p l i e d , t h e r e s u l t c a n b e
a line that reads:

IF EQ "usage"

This p r o d u c e s an error, b e c a u s e the t w o operators IF a n d E Q are adjacent.

U s i n g d o u b l e q u o t e s a r o u n d t h e k e y w o r d r e p l a c e m e n t i n d i c a t o r s r e s u l t s in a
line that reads:

IF "" EQ "usage"

w h i c h is l e g a l .
Y o u c a n u s e N O T in a n I F s t a t e m e n t to r e v e r s e t h e m e a n i n g o f t h e t e s t y o u
perform. For example:

IF NOT exists < f r o m >

T h e r e c a n b e n o t h i n g o n the IF line other t h a n the test condition. For

e x a m p l e , t h e f o l l o w i n g is i n c o r r e c t :

IF <something> EQ true SKIP DONE

T h e c o r r e c t f o r m o f t h e a b o v e s t a t e m e n t is as f o l l o w s :
 AMIGADOS COMMANDS 61

I F < s o m e t h i n g > EQ " t r u e "

S K I P DONE
ENDIF

A s the e x a m p l e above s h o w s , the string constant tested for n e e d not be

e n c l o s e d in d o u b l e q u o t e s ; in t h e p r e c e d i n g e x a m p l e , e i t h e r " T R U E " or T R U E
is a c c e p t a b l e .
A s s h o w n i n t h e s a m p l e c o m m a n d file b e l o w , IF s t a t e m e n t s c a n b e n e s t e d s o
that c o m m a n d s can b e executed based on multiple true statements. N o t e that
E X E C U T E lets y o u i n d e n t t o m a k e t h e n e s t i n g of I F s t a t e m e n t s m o r e r e a d a b l e .
T h e f o l l o w i n g s a m p l e c o m m a n d file s i m u l a t e s a file c o p y i n g utility t h a t
i l l u s t r a t e s c e r t a i n u s e f u l s t r u c t u r e s in a c o m m a n d file: I F . . . [ E L S E ] . . .
ENDIF, LAB, and SKIP.

.KEY from, to ; ( A s s i g n p a r a m e t e r list)

I F " < f r o m > " eq "" ; ( C h e c k f o r a F R O M file)
being supplied.
SKIP usage ; ( N o file, s h o w u s e r h o w to)
use.
ENDIF
I F " < t o > " eq "" ; ( C h e c k f o r a T O file)
b e i n g supplied.
SKIP usage ; ( N o file, s h o w u s e r h o w t o u s e )
ENDIF

I F NOT e x i s t s < f r o m > ; ( C h e c k if F R O M file d o e s n ' t exist)

ECHO " T h e f r o m file y o u selected ; ( < f r o m > ) could not be f o u n d . "
E C H O " P l e a s e u s e t h e D I R o r L I S T c o m m a n d a n d try a g a i n . "
S K I P DONE ;(Note: W e can SKIP out of an IF.)
ENDIF

IF exists < t o > ; ( C h e c k if T O file e x i s t s . )

I F " < o > " EQ "0" ;(Did the user supply " O " )
on the line?
copy f r o m < f r o m > to < t o >
ECHO " R e p l a c e d file n a m e d < t o > w i t h a copy of file n a m e d < f r o m > "
ECHO " R e q u e s t fulfilled."
ELSE
ECHO " C o m m a n d will o v e r w r i t e a n e x i s t i n g file ONLY i f '
ECHO " t h e 0 p a r a m e t e r is specified."
ECHO " R e q u e s t Denied"
SKIP usage ; ( E x p l a i n h o w to u s e t h i s file)
ENDIF
62 AMIGADOS USER'S M A N U A L

ELSE
ECHO "copy from < f r o m > to < t o > . "
ENDIF
SKIP DONE

LAB usage
ECHO "cp: usage...."
ECHO "The following copy forms are supported:"
ECHO " x cp FROM sourcefile TO destlnationfile"
ECHO " x cp FROM sourcefile destinationfile"
ECHO " x cp sourcefile TO destinationffle"
ECHO " x cp sourcefile destinationfile"
ECHO " x cp TO destinationfile FROM sourcefile"
ECHO " x cp sourcefile destinationfile 0"
ECHO " x cp FROM sourcefile TO destinationfile 0"
ECHO " x cp 0 FROM sourcefile TO destinationfile"
ECHO "where: x is short for EXECUTE; cp is the name o f
ECHO "this command file, and "0" means 'overwrite existing file'."

LAB DONE

Example # 4

The SKIP command allows only forward jumps. To create a loop structure
within a command file, use EXECUTE iteratively. That is, use the EXECUTE
command within the file itself to send execution backwards to a label. The
following executable example illustrates looping.
This file displays five messages:

"This message prints once at the beginning, (parml, parm2)"

"Loop number I."
"Loop number II."
"Loop number III."
"This message prints once at the end. (parml, parm2)"
.KEY parml,parm2, loopcnt, looplabel
FAILAT 20
IF NOT "<looplabel>" EQ "" ;(Called with label?)
SKIP <looplabel> ;(Yes, then loop.)
ENDIF

ECHO "This message prints once ;(Start of loop)

at the beginning. ( < p a r m l > , < p a r m 2 > ) "
 AMIGADOS COMMANDS 63

LAB lst-loop
I F " < l o o p c n t > " EQ " I I I " ;(Are w e done looping?)
SKIP loopend-<looplabel> ;(Yes, unwind.)
ENDIF
ECHO "Loop n u m b e r < l o o p c n t > I . " ; ( G o " b a c k w a r d s " in t h i s file.)
EXECUTE, loop.sample " < p a r m l > " " < p a r m 2 > " < l o o p c n t > I lst-loop

LAB loopend-<looplabel>
I F NOT " < l o o p c n t > " EQ " "
SKIP EXIT
ENDIF
;(End of loop)
ECHO " T h i s m e s s a g e p r i n t s once at t h e end. [ < p a r m l > , < p a r m 2 > ) "

LAB E X I T

FAILAT
Format: FAILAT <n>
Template: FAILAT " R C L I M "
Purpose: T o i n s t r u c t a c o m m a n d s e q u e n c e t o fail if a p r o g r a m r e t u r n s a n e r r o r
c o d e g r e a t e r t h a n or e q u a l t o t h i s n u m b e r .
Specification:
C o m m a n d s i n d i c a t e t h a t t h e y h a v e failed in s o m e w a y b y s e t t i n g a r e t u r n c o d e .
A nonzero return code indicates that the c o m m a n d has found an error of s o m e
s o r t . A r e t u r n c o d e g r e a t e r t h a n or e q u a l to a c e r t a i n limit ( t h e fail limit)
terminates a s e q u e n c e of noninteractive c o m m a n d s (that is, t h e commands
t h a t y o u s p e c i f y a f t e r R U N o r in a n E X E C U T E file). T h e r e t u r n c o d e i n d i c a t e s
h o w s e r i o u s t h e e r r o r w a s , a n d is n o r m a l l y 5 , 1 0 , or 2 0 .
Y o u m a y u s e t h e F A I L A T c o m m a n d to a l t e r t h i s fail l e v e l f r o m its initial
v a l u e o f 1 0 . If y o u i n c r e a s e t h e l e v e l , y o u i n d i c a t e t h a t c e r t a i n c l a s s e s o f e r r o r
s h o u l d n o t b e r e g a r d e d as fatal, a n d t h a t e x e c u t i o n o f s u b s e q u e n t c o m m a n d s
m a y p r o c e e d after an error. T h e a r g u m e n t should be a positive n u m b e r . T h e
fail l e v e l is r e s e t t o t h e initial v a l u e o f 10 o n exit f r o m t h e c o m m a n d s e q u e n c e .
You must use FAILAT before commands s u c h as I F t o t e s t to s e e if a
c o m m a n d h a s failed; otherwise, the c o m m a n d sequence terminates before
executing the IF c o m m a n d .
If y o u o m i t t h e a r g u m e n t , t h e c u r r e n t v a l u e o f t h e fail l e v e l is d i s p l a y e d .

Examples:

FAILAT 2 5
64 AMIGADOS USER'S MANUAL

T h e c o m m a n d s e q u e n c e o n l y t e r m i n a t e s b e f o r e t h e e n d if a c o m m a n d s t o p s
w i t h a r e t u r n c o d e g r e a t e r t h a n or e q u a l to ( > = ) 2 5 .

See also: I F , E X E C U T E , R U N , Q U I T

FAULT
Format: FAULT[<n>*]
Template: FAULT " „ „ „ „ , "
Purpose: T o display t h e m e s s a g e s c o r r e s p o n d i n g t o t h e fault c o d e s y o u s u p p l y .
Specification:
A m i g a D O S looks u p the n u m b e r s a n d displays the corresponding messages. U p
to ten m e s s a g e s m a y b e displayed.

Examples:

FAULT 2 2 2

d i s p l a y s t h e m e s s a g e for fault 2 2 2 .

FAULT 2 2 1 1 0 3 1 2 1 2 1 8

d i s p l a y s t h e m e s s a g e s for faults 2 2 1 , 1 0 3 , 1 2 1 , a n d 2 1 8 .

FILENOTE
Format: F I L E N O T E [FILE] < f i l e > C O M M E N T < s t r i n g >
Template: FILENOTE "FILE/A,COMMENT/K"
Purpose: T o a t t a c h a c o m m e n t o r a n o t e to a file.
Specification:
F I L E N O T E a s s i g n s a c o m m e n t to a s p e c i f i e d file.
T h e k e y w o r d C O M M E N T introduces a n optional c o m m e n t o f u p to 80
c h a r a c t e r s . A c o m m e n t m a y b e m o r e t h a n o n e w o r d (that i s , c o n t a i n s p a c e s
b e t w e e n characters). In this case, y o u m u s t enclose the c o m m e n t within double
quotes (").
A c o m m e n t is a s s o c i a t e d w i t h a p a r t i c u l a r file. W h e n y o u e x a m i n e t h e file
w i t h t h e c o m m a n d L I S T , t h e c o m m e n t a p p e a r s o n t h e line b e l o w :

prog 3 0 rwed Today 1 1 : 0 7 : 3 3

: version 3.2 - 2 3 - m a r - 8 5

W h e n y o u c r e a t e a n e w file, it d o e s n o t n o r m a l l y h a v e a c o m m e n t . If y o u
o v e r w r i t e a n e x i s t i n g file t h a t h a s a c o m m e n t , t h e n t h e c o m m e n t is r e t a i n e d
 AMIGADOS COMMANDS 65

e v e n t h o u g h t h e c o n t e n t s o f t h e file h a v e c h a n g e d . T h e c o m m a n d C O P Y c o p i e s
a file. If a file w i t h a c o m m e n t is c o p i e d , t h e n e w file d o e s n o t h a v e t h e
c o m m e n t f r o m t h e o r i g i n a l a t t a c h e d t o it a l t h o u g h t h e d e s t i n a t i o n file m a y h a v e
a c o m m e n t w h i c h is r e t a i n e d .

Examples:

F I L E N O T E p r o g 2 C O M M E N T " V e r 3.3 26-mar-85"

attaches the c o m m e n t " V e r 3.3 2 6 - m a r - 8 5 " to program 2.

See also: LIST

FORMAT
Format: F O R M A T DRIVE < d r i v e n a m e > N A M E < s t r i n g >
Template: FORMAT"DRIVE/A/K,NAME/A/K"
Purpose: T o f o r m a t a n d initialize a n e w 3 /2-inch f l o p p y d i s k .
1

Specification:
T h e p r o g r a m formats a n e w floppy disk in the m e t h o d required for A m i g a D O S .
O n c e t h e d i s k is f o r m a t t e d , it is initialized a n d a s s i g n e d t h e n a m e y o u s p e c i f y .
Notice that y o u m u s t give b o t h the D R I V E a n d N A M E k e y w o r d s . T h e only
v a l i d o p t i o n s t h a t y o u c a n g i v e a f t e r t h e D R I V E k e y w o r d a r e DFO:, D F 1 : ,
D F 2 : , o r D F 3 : . Y o u c a n t y p e a n y s t r i n g a f t e r N A M E , b u t if y o u u s e s p a c e s ,
y o u m u s t e n c l o s e t h e w h o l e s t r i n g in d o u b l e q u o t e s ( " ) .

W A R N I N G : F O R M A T f o r m a t s a n d initializes a d i s k a s a n e m p t y d i s k . If
y o u u s e a d i s k t h a t is n o t e m p t y , y o u ' l l l o s e t h e p r e v i o u s c o n t e n t s o f t h e
disk.

T h e n a m e a s s i g n e d s h o u l d b e u n i q u e . It m a y b e o n e to t h i r t y c h a r a c t e r s i n
l e n g t h a n d c o m p o s e d o f o n e or m o r e w o r d s s e p a r a t e d b y s p a c e s . If t h e
n a m e is m o r e t h a n o n e w o r d , y o u s h o u l d e n c l o s e it i n d o u b l e q u o t e s .
N o t e : It is n o t n e c e s s a r y t o f o r m a t a d i s k if y o u a r e a b o u t t o D I S K C O P Y t o it.

Examples:

F O R M A T D R I V E dfO: N A M E " W o r k d i s k "

f o r m a t s a n d initializes t h e d i s k in drive " d f O " w i t h t h e n a m e " W o r k d i s k " .

See also: DISKCOPY, INSTALL, RELABEL

66 AMIGADOS USER'S M A N U A L

IF
Format: IF[NOT][WARN][ERROR][FAIL][<str>EQ<str>][EXISTS <name>]
Template: IF "NOT/S,WARN/S,ERROR/S,FAIL/S,EQ/K,EXISTS/K"
Purpose: To allow conditionals within c o m m a n d sequences.
Specification:
Y o u c a n o n l y u s e t h i s c o m m a n d in a n E X E C U T E c o m m a n d file. If o n e or m o r e
of t h e s p e c i f i e d c o n d i t i o n s is s a t i s f i e d , IF carries o u t all t h e f o l l o w i n g c o m -
m a n d s u n t i l it f i n d s a c o r r e s p o n d i n g E N D I F or E L S E c o m m a n d ; o t h e r w i s e , if
t h e c o n d i t i o n s a r e n o t s a t i s f i e d , it carries o u t w h a t e v e r f o l l o w s a c o r r e s p o n d i n g
E L S E c o m m a n d . ( E N D I F a n d E L S E a r e o n l y u s e f u l in c o m m a n d s e q u e n c e s
containing IF.) E N D I F terminates an IF c o m m a n d ; E L S E provides an alternative
if t h e I F c o n d i t i o n s fail. N o t e t h a t t h e c o n d i t i o n s a n d c o m m a n d s in I F a n d
E L S E c o m m a n d s c a n s p a n m o r e t h a n o n e line b e f o r e their c o r r e s p o n d i n g
ENDIFs.
T h e following table s h o w s s o m e of the w a y s y o u can u s e t h e IF, E L S E , a n d
ENDIF commands:

IF < c o n d i t i o n > IF < c o n d i t i o n > IF < c o n d i t i o n >

< command > <command> < command >
ENDIF ELSE IF < c o n d i t i o n >
<command> <command>
ENDIF ENDIF
ENDIF

N o t e t h a t E L S E is o p t i o n a l a n d t h a t n e s t e d I F s j u m p to t h e n e a r e s t E N D I F .
E R R O R is o n l y available if y o u set F A I L A T t o g r e a t e r t h a n 1 0 . S i m i l a r l y ,
F A I L is o n l y a v a i l a b l e if y o u s e t F A I L A T t o g r e a t e r t h a n 2 0 .

Keyword Function
NOT reverses the result.
WARN s a t i s f i e d if p r e v i o u s r e t u r n c o d e > = 5 .
> = 10.
// // // // // //
ERROR
// // // //
FAIL
// // // //
> = 20.
s a t i s f i e d if t h e text of a a n d b is
<a>EQ<b> identical (disregarding case),
s a t i s f i e d if t h e file e x i s t s .
EXISTS < f i l e >
Y o u c a n u s e I F E Q to d e t e c t a n u n s e t p a r a m e t e r in a c o m m a n d file b y u s i n g
the form:

IF < a > EQ " "

 AMIGADOS COMMANDS 67

Examples:

IF EXISTS work/prog
TYPE work/prog
ELSE
ECHO "file not found"
ENDIF

If t h e file " w o r k / p r o g " exists, t h e n A m i g a D O S displays it. O t h e r w i s e , A m i g a D O S

displays the m e s s a g e "file not f o u n d " and executes the next c o m m a n d in the
command sequence.

IF ERROR
SKIP errlab
ENDIF

If t h e p r e v i o u s c o m m a n d s t o p p e d w i t h a r e t u r n c o d e > = 1 0 , t h e n A m i g a D O S
s k i p s t h e c o m m a n d s e q u e n c e u n t i l y o u d e f i n e a label " e r r l a b " w i t h t h e L A B
command.

IF ERROR
IF EXISTS fred
ECHO "The file 'fred' exists, but an error occurred anyway."
ENDIF
ENDIF

See also: FAILAT,SKIP,LAB,EXECUTE,QUIT

INFO
Format: INFO
Template: INFO
Purpose: T o g i v e i n f o r m a t i o n a b o u t t h e filing s y s t e m .
Specification:
T h e c o m m a n d d i s p l a y s a line of i n f o r m a t i o n a b o u t e a c h d i s k u n i t . T h i s
i n c l u d e s t h e m a x i m u m size of t h e d i s k , t h e c u r r e n t u s e d a n d f r e e s p a c e ,
t h e n u m b e r of s o f t d i s k e r r o r s t h a t h a v e o c c u r r e d , a n d t h e s t a t u s of t h e
disk.

Examples:

INFO
68 AMIGADOS USER'S MANUAL

Unit Size Used Free Full Errs Status Name

DF1: 880K 2 1756 0% 0 Read/Write Test-6
DFO: 880K 1081 677 61% 0 Read/Write AmigaDOS CLI

Volumes available:
Test-6 [Mounted]
A m i g a D O S CLI [ M o u n t e d ]

INSTALL

Format: INSTALL[DRIVE]<drive>
Template: INSTALL "DRIVE/A"
Purpose: T o m a k e a formatted disk bootable.
Specification:
T h e p u r p o s e o f t h e I N S T A L L c o m m a n d is to m a k e a d i s k b o o t a b l e ( t h a t i s , y o u
c a n u s e I N S T A L L t o m a k e a d i s k t h a t starts u p y o u r A m i g a ) . T o d o t h i s , y o u
simply type t h e n a m e of the drive w h e r e y o u h a v e inserted the disk that y o u
w a n t to b e c o m e t h e b o o t ( s t a r t u p ) d i s k . T h e r e a r e f o u r p o s s i b l e d r i v e n a m e s :
DF0:,DF1:,DF2:, and DF3:.

Examples:

I N S T A L L dfO:

m a k e s t h e d i s k in d r i v e " d f O : " a b o o t a b l e d i s k .

JOIN

Format: JOIN < n a m e > < n a m e > [ < n a m e > * ] A S < n a m e >
Template: JOIN " „ „ „ „ „ „ „ A S / A / K "
/

Purpose: T o c o n c a t e n a t e u p to 15 files t o f o r m a n e w file.

Specification:
A m i g a D O S c o p i e s t h e s p e c i f i e d files in t h e o r d e r y o u g i v e i n t o t h e n e w
file. N o t e t h a t t h e n e w file c a n n o t h a v e t h e s a m e n a m e a s a n y o f t h e i n p u t
files.

Examples:

J O I N p a r t i p a r t 2 AS textfile
 AMIGADOS COMMANDS 69

j o i n s t h e t w o files t o g e t h e r , p l a c i n g t h e r e s u l t i n " t e x t f i l e " . T h e t w o o r i g i n a l files

r e m a i n u n c h a n g e d , while " t e x t f i l e " contains a c o p y of " p a r t i " a n d a c o p y of
"part2".

LAB
Format: LAB <string>
Template: LAB < t e x t >
Purpose: T o i m p l e m e n t l a b e l s in c o m m a n d s e q u e n c e files.
Specification:
T h e c o m m a n d ignores a n y parameters you give. U s e L A B to define a label
" t e x t " t h a t is l o o k e d for b y t h e c o m m a n d S K I P .

Examples:

LAB errlab

d e f i n e s t h e l a b e l " e r r l a b " to w h i c h S K I P m a y j u m p .

See also: SKIP,IF,EXECUTE

LIST
Format: LIST[[DIR]<dir>][P|PAT <pat>][KEYS][DATES][NODATES][TO
<name>][S<str>][SINCE <date>][UPTO <date>][QUICK]
Template: LIST "DIR, P = PAT/K, KEYS/S, DATES/S, N O D A T E S / S , T O / K , S/K,
SINCE/K,UPTO/K,QUICK/S"
Purpose: T o e x a m i n e a n d list s p e c i f i e d i n f o r m a t i o n a b o u t a d i r e c t o r y or file.
Specification:
If y o u d o n o t s p e c i f y a n a m e ( t h e p a r a m e t e r D I R ) , L I S T d i s p l a y s t h e c o n t e n t s o f
t h e c u r r e n t d i r e c t o r y . T h e first p a r a m e t e r L I S T a c c e p t s is D I R . Y o u h a v e t h r e e
o p t i o n s . D I R m a y b e a f i l e n a m e , in w h i c h c a s e L I S T d i s p l a y s t h e file i n f o r m a -
t i o n f o r t h a t o n e file. S e c o n d l y , D I R m a y b e a d i r e c t o r y n a m e . I n t h i s c a s e L I S T
d i s p l a y s file i n f o r m a t i o n for files ( a n d o t h e r d i r e c t o r i e s ) w i t h i n t h e s p e c i f i e d
d i r e c t o r y . L a s t l y , if y o u o m i t t h e D I R p a r a m e t e r , L I S T d i s p l a y s i n f o r m a t i o n
a b o u t files a n d d i r e c t o r i e s w i t h i n t h e c u r r e n t d i r e c t o r y (for f u r t h e r d e t a i l s o n
the current directory, see the C D c o m m a n d ) .
N o t e : L I S T , u n l i k e D I R , d o e s N O T sort t h e d i r e c t o r y b e f o r e d i s p l a y i n g it.
If n o o t h e r o p t i o n s a r e s p e c i f i e d , L I S T d i s p l a y s :

file name size protection date time

: comment
70 AMIGADOS USER'S MANUAL

T h e s e f i e l d s a r e d e f i n e d as f o l l o w s :

file name: N a m e o f file or d i r e c t o r y .

size: T h e size o f t h e file in b y t e s . If t h e r e is n o t h i n g in t h e file, t h i s

field will s t a t e " e m p t y " . F o r d i r e c t o r i e s t h i s e n t r y s t a t e s " d i r " .

protection: T h i s s p e c i f i e s t h e a c c e s s a v a i l a b l e for t h i s file; r w e d i n d i c a t e s

Read, Write, Execute, and Delete.

date and time: T h e file c r e a t i o n d a t e a n d t i m e .

comment: T h i s is t h e c o m m e n t p l a c e d o n t h e file u s i n g t h e F I L E N O T E
c o m m a n d . N o t e t h a t it is p r e c e d e d w i t h a c o l o n (:).

O p t i o n s available:
TO T h i s s p e c i f i e s t h e file (or d e v i c e ) to o u t p u t t h e file l i s t i n g t o . If
o m i t t e d , t h e o u t p u t g o e s to t h e c u r r e n t C L I w i n d o w .

KEYS D i s p l a y s t h e b l o c k n u m b e r o f e a c h file h e a d e r o r d i r e c t o r y .

DATES Displays dates in the form D D - M M M - Y Y (the default unless

you use QUICK).

NODATES D o e s not display date a n d time information.

SINCE <date> D i s p l a y s o n l y files last u p d a t e d o n o r a f t e r < d a t e > . <date>

c a n b e in t h e f o r m D D - M M M - Y Y or a d a y n a m e in t h e last
w e e k (for e x a m p l e , M O N D A Y ) or T O D A Y o r Y E S T E R D A Y .

UPTO <date> D i s p l a y s o n l y files l a s t u p d a t e d o n o r b e f o r e < d a t e > .

P<pat> S e a r c h e s for files w h o s e n a m e s m a t c h < p a t > .

S<str> Searches for filenames containing substring < s t r > .

QUICK J u s t d i s p l a y s t h e n a m e s of files a n d d i r e c t o r i e s (like t h e D I R

command).

Y o u c a n s p e c i f y t h e r a n g e of f i l e n a m e s d i s p l a y e d i n t w o w a y s . T h e s i m p l e s t
w a y is to u s e t h e S k e y w o r d , w h i c h r e s t r i c t s t h e listing to t h o s e files c o n t a i n i n g
the specified substring. To specify a m o r e complicated search expression, use
t h e P o r P A T k e y w o r d . T h i s is f o l l o w e d b y a p a t t e r n t h a t m a t c h e s as d e s c r i b e d
below.
A p a t t e r n c o n s i s t s o f a n u m b e r of s p e c i a l c h a r a c t e r s w i t h s p e c i a l m e a n i n g s ,
a n d a n y other characters that m a t c h t h e m .
T h e special characters are: ' ( ) ? % # |
I n o r d e r t o r e m o v e t h e s p e c i a l e f f e c t o f t h e s e c h a r a c t e r s , p r e f a c e t h e m w i t h '.
T h u s '? m a t c h e s ? a n d ' ' m a t c h e s ' .
 AMIGADOS COMMANDS 71

? M a t c h e s a n y single character.
% M a t c h e s the null string.
# < p > M a t c h e s z e r o or m o r e o c c u r r e n c e s of t h e p a t t e r n <p>.
<pl><p2> M a t c h e s a s e q u e n c e of pattern < p l > followed b y < p 2 > .
<pl>l<p2> M a t c h e s if e i t h e r p a t t e r n < p l > o r p a t t e r n < p 2 > match.
() Groups patterns together.

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 "IA"
Purpose: T o m a k e a n e w directory.
Specification:
M A K E D I R creates a directory with the n a m e y o u specify. T h e c o m m a n d only
c r e a t e s o n e d i r e c t o r y at a t i m e , s o a n y d i r e c t o r i e s o n t h e p a t h m u s t a l r e a d y
e x i s t . T h e c o m m a n d fails if t h e d i r e c t o r y o r a file o f t h e s a m e n a m e a l r e a d y
e x i s t s i n t h e d i r e c t o r y a b o v e it i n t h e h i e r a r c h y .

Examples:

MAKEDIR tests

creates a directory " t e s t s " in the current directory.

M A K E D I R dfl:xyz

c r e a t e s a d i r e c t o r y " x y z " i n t h e r o o t d i r e c t o r y of d i s k " d f l " .

M A K E D I R dfl:xyz/abc

creates a directory " a b c " in t h e parent directory " x y z " o n disk " d f l " . H o w e v e r ,
" x y z " m u s t exist for this c o m m a n d to w o r k .

See also: DELETE

NEWCLI
Format: NEWCLI[<window>]
Template: NEWCLI "WINDOW"
Purpose: To create a w i n d o w associated with a n e w interactive CLI process.
 AMIGADOS COMMANDS 73

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 cur-
rently 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 , a
N E W C L I p r o c e s s h a n g s a r o u n d after y o u h a v e c r e a t e d it.

See also: E N D C L I , R U N
74 AMIGADOS USER'S MANUAL

PROMPT
Format: PROMPT<prompt>
Template: PROMPT "PROMPT"
Purpose: To change the p r o m p t in the current CLI.
Specification:
It y o u d o n o t g i v e a p a r a m e t e r , t h e n A m i g o D O S r e s e t s t h e p r o m p t to t h e
s t a n d a r d s t r i n g ( " > " ) . O t h e r w i s e , t h e p r o m p t is s e t t o t h e s t r i n g y o u s u p p l y .
A m i g a D O S a l s o a c c e p t s o n e s p e c i a l c h a r a c t e r c o m b i n a t i o n ( % N ) . T h i s is d e m -
o n s t r a t e d in t h e e x a m p l e b e l o w .

Examples:

PROMPT

resets the current p r o m p t to " > " .

PROMPT " % N > "

r e s e t s t h e c u r r e n t p r o m p t t o " n > " , w h e r e n is t h e c u r r e n t p r o c e s s n u m b e r .

A m i g a D O S interprets the special character combination % N as the process
number.

PROTECT
Format: PROTECT[FILE] < f ilename> [FLAGS< status>]
Template: PROTECT"FILE,FLAGS/K"
Purpose: 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
 AMIGADOS COMMANDS 75

s e t s t h e p r o t e c t i o n s t a t u s of p r o g r a m 1 as r e a d o n l y .

PROTECT p r o g 2 r w d

sets the protection of program 2 as read/write/delete.

See also: LIST

QUIT
Format: QUIT[<returncode>]
Template: QUIT " R C "
Purpose: T o exit f r o m a c o m m a n d s e q u e n c e w i t h a g i v e n e r r o r c o d e .
Specification:
Q U I T r e a d s t h r o u g h t h e c o m m a n d file a n d t h e n s t o p s w i t h a r e t u r n c o d e . T h e
d e f a u l t r e t u r n c o d e is z e r o .

Examples:

QUIT

exits t h e current c o m m a n d s e q u e n c e .

FAILAT 3 0
IF ERROR
QUIT 2 0
ENDIF

If t h e last c o m m a n d w a s in error, this terminates t h e c o m m a n d sequence

with return code 20.
For m o r e on c o m m a n d s e q u e n c e s , see the specification for the EXECUTE
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.
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

 AMIGADOS COMMANDS 77

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 . RUN
interprets the next line after a + (RETURN) as a continuation of the same
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 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 AmigaDOS
displays the following message:

label " < l a b e l > " not found b y Skip

 AMIGADOS COMMANDS 79

S K I P o n l y j u m p s f o r w a r d in t h e c o m m a n d s e q u e n c e .

Examples:

SKIP

s k i p s to t h e n e x t L A B c o m m a n d w i t h o u t a n a m e f o l l o w i n g it.

IF ERROR

SKIP errlab

ENDIF

If t h e last c o m m a n d s t o p p e d w i t h a r e t u r n c o d e > = 2 0 , t h i s s e a r c h e s for t h e

l a b e l " e r r l a b " l a t e r in t h e c o m m a n d file.

FAILAT 100
ASSEM text
IF ERROR
SKIP ERROR
ENDIF
LINK
S K I P DONE
LAB ERROR
ECHO " E r r o r doing A s s e m "
L A B DONE

ECHO " N e x t c o m m a n d p l e a s e "

See also: EXECUTE,LAB,IF,FAILAT,QUIT

SORT
Format: SORT[FROM]<name>[[TO]<name>][COLSTART<n>]
Template: SORT "FROM/A,TO/A,COLSTART/K"
Purpose: T o sort s i m p l e files.
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: STACK[<n>]
Template: 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
 AMIGADOS COMMANDS 81

v a l u e . Y o u s p e c i f y t h e v a l u e o f t h e s t a c k size in b y t e s . S T A C K a l o n e d i s p l a y s
the currently set stack size.
T h e o n l y c o m m a n d t h a t y o u w o u l d n o r m a l l y n e e d t o alter t h e s t a c k s i z e f o r
is t h e S O R T c o m m a n d . R e c u r s i v e c o m m a n d s s u c h a s D I R n e e d a n i n c r e a s e d
s t a c k if y o u u s e t h e m o n a d i r e c t o r y s t r u c t u r e m o r e t h a n a b o u t six l e v e l s d e e p .

W A R N I N G : T h e o n l y i n d i c a t i o n t h a t y o u h a v e r u n o u t o f s t a c k is t h a t t h e
A m i g a c r a s h e s ! If y o u a r e n o t s u r e , it is b e t t e r t o o v e r e s t i m a t e t h e a m o u n t
you need.

Examples:

STACK

displays the current stack size.

STACK 8 0 0 0

s e t s t h e s t a c k to 8 0 0 0 b y t e s .

See also: R U N , S O R T

STATUS
Format: STATUS[<process>][FULL][TCB][SEGS][CLI|ALL]
Template: STATUS "PROCESS, FULL/S,TCB/S,SEGS/S,CLI = ALL/S"
Purpose: To display information about the currently existing CLI processes.
Specification:
S T A T U S a l o n e lists t h e n u m b e r s o f t h e C L I p r o c e s s e s a n d t h e p r o g r a m r u n n i n g
in e a c h .
P R O C E S S specifies a process n u m b e r a n d only gives information about that
p r o c e s s . O t h e r w i s e , i n f o r m a t i o n is d i s p l a y e d a b o u t all p r o c e s s e s .
FULL = SEGS + TCB + CLI
S E G S d i s p l a y s t h e n a m e s of t h e s e c t i o n s o n t h e s e g m e n t list o f e a c h p r o c e s s .
T C B displays information about the priority, stacksize, a n d global vector size
of each process.
For further details on stack a n d global vector size, see the AmigaDOS
Technical Reference in this b o o k .
CLI identifies C o m m a n d Line Interface processes and displays the section
n a m e ( s ) o f t h e c u r r e n t l y l o a d e d c o m m a n d (if a n y ) .
82 AMIGADOS USER'S MANUAL

Examples:

STATUS

d i s p l a y s b r i e f i n f o r m a t i o n a b o u t all p r o c e s s e s .

STATUS 4 FULL

d i s p l a y s full i n f o r m a t i o n a b o u t p r o c e s s 4 .

TYPE
Format: T Y P E [ F R O M ] < n a m e > [ [ T O ] < n a m e > ] [ O P T N|H]
Template: TYPE "FROM/A,TO, OPT/K"
Purpose: T o t y p e a text file or to t y p e a file o u t a s h e x a d e c i m a l n u m b e r s .
Specification:
T O i n d i c a t e s t h e o u t p u t file t h a t y o u s p e c i f y ; if y o u o m i t t h i s , o u t p u t is t o t h e
c u r r e n t o u t p u t s t r e a m , w h i c h m e a n s , in m o s t c a s e s , t h a t t h e o u t p u t g o e s t o t h e
current window.
T a b s t h a t y o u h a v e g i v e n in t h e file a r e e x p a n d e d . H o w e v e r , t a b s are n o t
t r e a t e d as s p e c i a l b y T Y P E ; t h e c o n s o l e d r i v e r p r o c e s s e s t h e m . T o i n t e r r u p t
o u t p u t , p r e s s C T R L - C . T o s u s p e n d o u t p u t , p r e s s t h e s p a c e b a r or t y p e a n y
o t h e r c h a r a c t e r . T o r e s u m e o u t p u t , p r e s s R E T U R N or C T R L - X .
O P T s p e c i f i e s a n o p t i o n to T Y P E . T h e first o p t i o n to T Y P E is " n " , which
i n c l u d e s l i n e n u m b e r s in t h e o u t p u t .
T h e s e c o n d o p t i o n y o u c a n g i v e T Y P E is " h . " U s e t h e " h " o p t i o n to w r i t e o u t
e a c h w o r d o f t h e F R O M file as a h e x n u m b e r .

Examples:

TYPE work/prog

d i s p l a y s t h e file " w o r k / p r o g " .

T Y P E w o r k / p r o g OPT n

d i s p l a y s t h e file " w o r k / p r o g " w i t h l i n e n u m b e r s .

T Y P E o b j / p r o g OPT h

d i s p l a y s t h e c o d e s t o r e d in " o b j / p r o g " in h e x a d e c i m a l .
 AMIGADOS COMMANDS 83

WAIT
Format: WAIT <n>[SEC|SECS][MIN|MINS][UNTIL <time>]
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]<filename>[,<filename>*| + <filename*]]
[TO < n a m e > ] [ W I T H < n a m e > ] [ L I B R A R Y | L I B < n a m e > ] [MAP
<map>][XREF <name>][WIDTH <n>]
Template: ALINK " 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 auto-
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 ALINK
is a file l o a d e d by the loader and run under the overlay supervisor, if
required.
F o r d e t a i l s a n d a full s p e c i f i c a t i o n o f t h e A L I N K c o m m a n d , s e e C h a p t e r 4 o f
t h e AmigaDOS Developer's Manual in t h i s b o o k .
 AMIGADOS COMMANDS 85

Examples:

A L I N K a + b + c TO o u t p u t

l i n k s t h e files " a " , " b " , a n d " c " , p r o d u c i n g a n o u t p u t file " o u t p u t " .

ASSEM
Format: ASSEM[PROG|FROM]<prog>[-0 <code>][-V <ver>][-L <listing>]
[-E] [-C|OPT < o p t > ] [ - I < d i r l i s t > ]
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 .
Specification:
A S S E M a s s e m b l e s p r o g r a m s in M C 6 8 0 0 0 a s s e m b l y l a n g u a g e . S e e C h a p t e r 3 o f
t h e AmigaDOS Developer's Manual in t h i s b o o k f o r d e t a i l s .

PROG is t h e s o u r c e file.
-O is t h e o b j e c t file ( t h a t i s , b i n a r y o u t p u t f r o m t h e a s s e m b l e r ) .
-V is t h e file f o r m e s s a g e s . ( U n l e s s y o u s p e c i f y - V , m e s s a g e s g o to t h e
terminal.)
-L is t h e l i s t i n g file.
-C s p e c i f i e s o p t i o n s to t h e a s s e m b l e r .
-H is a h e a d e r file w h i c h c a n b e r e a d a s if i n s e r t e d at t h e f r o n t o f t h e
s o u r c e (like I N C L U D E in t h e s o u r c e i t s e l f ) .
-I s e t s u p a list o f d i r e c t o r i e s t o b e s e a r c h e d for i n c l u d e d files.
-E is t h e file t h a t r e c e i v e s t h e " e q u a t e s " d i r e c t i v e ( E Q U ) a s s i g n m e n t s
f r o m y o u r s o u r c e . Y o u u s e - E to g e n e r a t e a h e a d e r file c o n t a i n i n g
these directives.

T h e options y o u can specify with O P T or -C are as follows:

S p r o d u c e a s y m b o l t a b l e d u m p a s p a r t o f t h e o b j e c t file.
X p r o d u c e a c r o s s - r e f e r e n c e file.
W<size> s e t w o r k s p a c e to < s i z e > .

Examples:

ASSEM prog.asm TO prog.obj

a s s e m b l e s t h e s o u r c e p r o g r a m in " p r o g . a s m " , p l a c i n g t h e r e s u l t i n t h e file

" p r o g . o b j " . It w r i t e s a n y e r r o r m e s s a g e s t o t h e t e r m i n a l , b u t d o e s n o t p r o d u c e
a n y a s s e m b l y listing.
86 AMIGADOS USER'S MANUAL

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 "FROM/A,TO/A"
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 .
Specification:
The c o m m a n d D O W N L O A D downloads programs written on another com-
p u t e r (for e x a m p l e , a S u n ) to t h e A m i g a .
T o u s e D O W N L O A D , y o u m u s t h a v e a B i l l B o a r d . T h e n , to d o w n l o a d y o u r
l i n k e d l o a d file f r o m t h e S u n to t h e A m i g a , y o u t y p e o n t h e S u n :

b i n l o a d -p &

(this o n l y n e e d s to b e d o n e o n c e ) , t h e n t y p e o n t h e A m i g a :

download < s u n filename> <amiga filename>

(Before y o u boot your S u n , y o u m u s t m a k e sure that both the BillBoard a n d

A m i g a are already on a n d powered u p , otherwise they won't be recognized by
the Sun.) The <sun filename> by convention should end with .Id. Once
y o u ' v e d o n e t h i s , to r u n t h e p r o g r a m , y o u t y p e t h e < a m i g a f i l e n a m e > .
N o t e t h a t t h e c o m m a n d " b i n l o a d " is n o t a n A m i g a D O S c o m m a n d . Y o u u s e
b i n l o a d o n a S u n to l o a d files i n b i n a r y for d o w n l o a d i n g to y o u r A m i g a .
N o t e t h a t D O W N L O A D a l w a y s a c c e s s e s files o n t h e S u n r e l a t i v e to t h e
d i r e c t o r y i n w h i c h b i n l o a d w a s s t a r t e d . If y o u c a n n o t r e m e m b e r t h e d i r e c t o r y
in w h i c h b i n l o a d w a s s t a r t e d , y o u m u s t s p e c i f y t h e full n a m e . T o s t o p b i n l o a d
o n t h e S u n , y o u c a n d o a " p s " a n d t h e n a " k i l l " o n its P I D . N o t e t h a t t h e s o f t
r e s e t o f t h e c o m p u t e r tells b i n l o a d to w r i t e a m e s s a g e t o its s t a n d a r d o u t p u t
( t h e d e f a u l t b e i n g t h e w i n d o w w h e r e it s t a r t e d ) . If D O W N L O A D h a n g s , p r e s s
C T R L - C t o kill it.
C h a p t e r 1 o f t h e AmigaDOS Developer's Manual i n t h i s b o o k d e s c r i b e s in d e t a i l
h o w t o d o w n l o a d p r o g r a m s f r o m a n I B M P C to A m i g a , f r o m t h e S u n t o t h e
A m i g a , a n d e v e n g i v e s s o m e h i n t s o n h o w to d o w n l o a d f r o m u n s u p p o r t e d
computers.
 AMIGADOS COMMANDS 87

Examples:

b l n l o a d -p &

download test.ld test.

or

d o w n l o a d /usr7fred/DOS/test.ld t e s t

then type the following:

test

These commands download the specified Sun filenames to the Amiga

filenames.

READ
Template: READ "TO/A,SERIAL/S"
Purpose: R E A D r e a d s d a t a f r o m t h e p a r a l l e l p o r t or serial l i n e a n d s t o r e s it in
a file.
Specification:
The command R E A D l i s t e n s t o t h e parallel p o r t a n d e x p e c t s a s t r e a m of
h e x a d e c i m a l c h a r a c t e r s . If y o u p r e s s t h e S E R I A L s w i t c h , R E A D l i s t e n s , i n s t e a d ,
t o t h e serial l i n e . E a c h h e x p a i r is s t o r e d a s a b y t e in m e m o r y . R E A D r e c o g n i z e s
Q as the h e x stream terminator. R E A D also recognizes the A S C I I digits 0 - 9 a n d
t h e capital l e t t e r s A t h r o u g h F . R E A D i g n o r e s s p a c e s , n e w l i n e s , a n d t a b s . Y o u
m u s t s e n d a n A S C I I h e x digit f o r e v e r y n i b b l e , a n d y o u m u s t h a v e a n e v e n
n u m b e r o f n i b b l e s . W h e n t h e s t r e a m is c o m p l e t e , R E A D w r i t e s t h e b y t e s f r o m
m e m o r y to t h e d i s k file y o u s p e c i f i e d .
N o t e : Y o u c a n u s e t h i s c o m m a n d to t r a n s f e r b i n a r y or t e x t f i l e s .

W A R N I N G 1 : B e c a r e f u l w h e n R E A D i n g to t h e s a m e file t w i c e . R E A D
overwrites the original contents the s e c o n d time.

W A R N I N G 2 : Y o u m a y l o s e c h a r a c t e r s if y o u u s e h i g h b a u d r a t e s w i t h
t h e serial c o n n e c t i o n .

Examples:

R E A D TO d f O : n e w
88 AMIGADOS USER'S MANUAL

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 c o m m e n t character.
<> direct c o m m a n d input a n d output respectively.
COPY 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.
DELETE 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 .
DIR 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 .
ED e n t e r s a s c r e e n e d i t o r f o r text files.
EDIT e n t e r s a line b y line e d i t o r .
FILENOTE 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.
JOIN 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.
LIST 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.
MAKEDIR creates a directory with a specified n a m e ,
PROTECT s e t s a file's p r o t e c t i o n s t a t u s ,
RENAME r e n a m e s a file or d i r e c t o r y .
SEARCH 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 ,
SORT sorts s i m p l e files.
TYPE 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 .

CLI Control
BREAK 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 about the CLI processes currently in

existence.
WHY explains w h y a previous c o m m a n d failed.

Command Sequence Control

ECHO d i s p l a y s t h e m e s s a g e s p e c i f i e d in a c o m m a n d a r g u m e n t .
EXECUTE e x e c u t e s a file o f c o m m a n d s .
FAILAT 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 Management

ASSIGN 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 time.
DISKCOPY copies the contents of o n e entire floppy disk to a n o t h e r .
FAULT 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 System
ALINK 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 and
s t o r e s it i n a file.
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 Introducing E D
3.2 Immediate Commands
3.2.1 Cursor Control
3.2.2 Inserting Text
3.2.3 Deleting Text
3.2.4 Scrolling
3.2.5 Repeating Commands
3.3 Extended Commands
3.3.1 Program Control
3.3.2 Block Control
3.3.3 M o v i n g the Current Cursor Position
3.3.4 Searching and Exchanging
3.3.5 Altering Text
3.3.6 Repeating Commands
Quick 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 dis-
p 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.
92 AMIGADOS USER'S MANUAL

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
94 AMIGADOS USER'S MANUAL

t h e r i g h t ( a n d it m o v e s t h e c u r s o r e v e n if t h e r e is n o c a s e t o flip). S o t h a t , a f t e r
y o u h a v e c h a n g e d t h e c a s e of a letter w i t h C T R L - F , t h e c u r s o r m o v e s r i g h t t o
p o i n t at t h e n e x t c h a r a c t e r . If t h e n e x t c h a r a c t e r is a l e t t e r , y o u c a n p r e s s
C T R L - F a g a i n t o c h a n g e its c a s e ; y o u c a n t h e n r e p e a t t h e c o m m a n d u n t i l y o u
h a v e c h a n g e d all t h e l e t t e r s o n t h e l i n e . ( N o t e t h a t if y o u c o n t i n u e t o p r e s s
C T R L - F a f t e r t h e last letter o n t h e l i n e , t h e c u r s o r k e e p s m o v i n g r i g h t e v e n
t h o u g h t h e r e is n o t h i n g left t o c h a n g e . ) F o r e x a m p l e , if y o u h a d t h e l i n e

The Walrus and the Carpenter were walking hand in hand

a n d y o u k e p t C T R L - F p r e s s e d d o w n , t h e line w o u l d b e c o m e

the walrus and the carpenter were walking hand in hand

O n the other h a n d , the following line:

IF <file> < = x

becomes

if < F I L E > < = X

w h e r e the letters c h a n g e case a n d the symbols remain the s a m e .

3.2.3 Deleting Text

T h e B A C K S P A C E k e y d e l e t e s t h e c h a r a c t e r to t h e left of t h e c u r s o r a n d m o v e s
t h e c u r s o r o n e p o s i t i o n left u n l e s s it is at t h e b e g i n n i n g of a l i n e . E D scrolls t h e
t e x t , if r e q u i r e d . T h e D E L k e y d e l e t e s t h e c h a r a c t e r at t h e c u r r e n t c u r s o r
position without moving the cursor. As with any deletion, characters remain-
i 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
96 AMIGADOS USER'S MANUAL

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
 ED—THE SCREEN EDITOR 97

S A is p a r t i c u l a r l y u s e f u l in g e o g r a p h i c a l a r e a s s u b j e c t t o p o w e r f a i l u r e or
surge.
H i n t : S A f o l l o w e d b y Q is e q u i v a l e n t to t h e X c o m m a n d .
If y o u m a k e a n y a l t e r a t i o n s b e t w e e n t h e S A a n d t h e Q c o m m a n d s , the
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 )
98 AMIGADOS USER'S MANUAL

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 char-
a 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 " matches
"Wombat", "WOMBAT", "WoMbAt", a n d so on. To have E D distinguish
between upper and lower case again, you use LC.

3.3.5 Altering Text

Y o u cannot use the E c o m m a n d to insert a n e w line into the text. Y o u use the I
a n d A c o m m a n d s instead. Follow the I c o m m a n d (Insert before) with a string
t h a t y o u w a n t to m a k e i n t o a n e w l i n e . E D i n s e r t s t h i s n e w l i n e b e f o r e t h e
current line. For example,

I /Insert this BEFORE the current line/

 ED—THE SCREEN EDITOR 101

inserts the string " I n s e r t this B E F O R E the current l i n e " as a n e w , separate line
Before the line containing the cursor. Y o u u s e the A c o m m a n d (insert After) in
the s a m e w a y except that E D inserts the n e w line after the current line. T h a t is,

A /Insert this A F T E R the current line/

i n s e r t s t h e s t r i n g " I n s e r t t h i s A F T E R t h e c u r r e n t l i n e " as a n e w l i n e A f t e r t h e
line containing the cursor.
T o split t h e c u r r e n t l i n e at t h e c u r s o r p o s i t i o n , y o u u s e t h e S c o m m a n d . S i n
e x t e n d e d m o d e is j u s t like p r e s s i n g R E T U R N in i m m e d i a t e m o d e (see Section
3.2.2 for further details on splitting lines).
T h e J c o m m a n d j o i n s t h e n e x t l i n e to t h e e n d o f t h e c u r r e n t o n e .
T h e D c o m m a n d d e l e t e s t h e c u r r e n t line i n t h e s a m e w a y a s C T R L - B in
immediate m o d e . T h e D C c o m m a n d deletes the character a b o v e the cursor in
t h e s a m e w a y as D E L .

3.3.6 Repeating Commands

T o r e p e a t a n y c o m m a n d a c e r t a i n n u m b e r o f t i m e s , p r e c e d e it w i t h t h e d e s i r e d
number. For example,

4 E /slithy/brillig/

c h a n g e s the next four occurrences of " s l i t h y " to "brillig". E D verifies t h e screen

after each c o m m a n d . Y o u u s e the R P (Repeat) c o m m a n d to repeat a c o m m a n d
u n t i l E D r e t u r n s a n e r r o r , s u c h a s r e a c h i n g t h e e n d o f t h e file. F o r e x a m p l e ,

T; R P E / s l i t h y / b r i l l i g /

c h a n g e s all o c c u r r e n c e s o f " s l i t h y " t o " b r i l l i g " . N o t i c e t h a t y o u n e e d t h e T

c o m m a n d to e n s u r e t h a t A L L o c c u r r e n c e s o f " s l i t h y " a r e c h a n g e d , o t h e r w i s e
only those after the current position are c h a n g e d .
To execute command groups repeatedly, you can group the commands
together in parentheses. Y o u can also n e s t c o m m a n d groups within c o m m a n d
groups. For example,

R P ( F / b a n d e r s n a t c h / ; 3 AJI )

inserts three b l a n k lines (copies of the null string) after every line c o n t a i n i n g
" b a n d e r s n a t c h " . Notice that this c o m m a n d line only w o r k s from the cursor to
t h e e n d o f t h e file. T o a p p l y t h e c o m m a n d t o e v e r y l i n e i n t h e file, y o u s h o u l d
first m o v e t o t h e t o p o f t h e file.
N o t e t h a t s o m e c o m m a n d s are p o s s i b l e , b u t silly. F o r e x a m p l e ,
102 AMIGADOS USER'S MANUAL

RP SR 6 0

s e t s t h e r i g h t m a r g i n t o 6 0 ad infinitum. H o w e v e r , to interrupt a n y s e q u e n c e of
e x t e n d e d c o m m a n d s , a n d particularly repeated o n e s , y o u type a n y character
w h i l e t h e c o m m a n d s a r e t a k i n g p l a c e . If a n e r r o r o c c u r s , E D a b a n d o n s the
command sequence.

Quick Reference Card

Special Key Mappings

Command Action
BACKSPACE D e l e t e c h a r a c t e r to left o f c u r s o r
DEL D e l e t e c h a r a c t e r at c u r s o r
ESC Enter extended command mode
RETURN Split l i n e at c u r s o r a n d c r e a t e a n e w l i n e
TAB M o v e cursor right to next tab position (does N O T insert a
T A B character)
<up-arrow> M o v e cursor u p
<down-arrow> M o v e cursor d o w n
<left-arrow> M o v e c u r s o r left
<right-arrow> M o v e cursor right

Immediate Commands
Command Action
CTRL-A Insert line
CTRL-B Delete line
CTRL-D Scroll text d o w n
CTRL-E M o v e to t o p or b o t t o m o f s c r e e n
CTRL-F Flip case
CTRL-G R e p e a t last e x t e n d e d c o m m a n d l i n e
CTRL-H D e l e t e c h a r a c t e r left o f c u r s o r ( B A C K S P A C E )
CTRL-I M o v e cursor right to next tab position
CTRL-M RETURN
CTRL-O Delete word or spaces
CTRL-R C u r s o r to e n d of previous w o r d
CTRL-T C u r s o r t o start o f n e x t w o r d
CTRL-U S c r o l l text u p
CTRL-V Verify screen
CTRL-Y D e l e t e to e n d o f l i n e
 ED—THE SCREEN EDITOR 103

CTRL-[ Escape (enter extended mode)

CTRL-] C u r s o r t o e n d or start of line

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/ Exchange " s " into " t "
E Q /s/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 "s"
I Is/ Insert line b e f o r e current
IB Insert c o p y of block
I F Is/ I n s e r t file "s"
J Join current line with next
LC 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 Q u i t without saving text
RP Repeat until error
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
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 specifica-
t 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 Introducing EDIT

4.1.1 Calling EDIT
4.1.2 Using EDIT C o m m a n d s
4.1.2.1 The Current Line
4.1.2.2 Line Numbers
4.1.2.3 Selecting a Current Line
4.1.2.4 Qualifiers
4.1.2.5 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
4.1.2.6 Deleting Whole Lines
4.1.2.7 Inserting N e w Lines
4.1.2.8 C o m m a n d Repetition
4.1.3 Leaving EDIT
4.1.4 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
4.2 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
4.2.1 C o m m a n d Syntax
4.2.1.1 Command Names
4.2.1.2 Arguments
4.2.1.3 Strings
4.2.1.4 Multiple Strings
4.2.1.5 Qualified Strings
4.2.1.6 Search Expressions
4.2.1.7 Numbers
4.2.1.8 Switch Values
4.2.1.9 Command Groups
4.2.1.10 C o m m a n d Repetition
4.2.2 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 .
 EDIT—THE LINE EDITOR 107

A l t h o u g h E D I T u s u a l l y p r o c e s s e s t h e s o u r c e file in a f o r w a r d sequential
m a n n e r , it h a s t h e c a p a b i l i t y t o m o v e b a c k w a r d a l i m i t e d n u m b e r o f l i n e s .
T h i s is p o s s i b l e b e c a u s e E D I T d o e s n ' t w r i t e t h e l i n e s t h a t h a v e b e e n p a s s e d t o
t h e d e s t i n a t i o n file i m m e d i a t e l y , b u t h o l d s t h e m i n s t e a d in a n o u t p u t q u e u e .
T h e size of t h i s q u e u e d e p e n d s o n t h e a m o u n t o f m e m o r y a v a i l a b l e . If y o u
w a n t t o h o l d m o r e i n f o r m a t i o n in m e m o r y , y o u c a n select t h e E D I T o p t i o n , O P T ,
d e s c r i b e d in t h e n e x t s e c t i o n , to i n c r e a s e t h e a m o u n t .
Y o u can m a k e m o r e than one pass through the text.
T h e E D I T c o m m a n d s let y o u

a) c h a n g e p a r t s o f t h e s o u r c e ,
b) o u t p u t parts of t h e source to other destinations, a n d
c) i n s e r t m a t e r i a l f r o m o t h e r s o u r c e s .

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 argu-
m 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 <n>,
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 of
EDIT."
 EDIT—THE LINE EDITOR 109

4.1.2.1 The Current Line

A s E D I T reads lines from the source and writes t h e m to the destination, the
l i n e t h a t it h a s " i n its h a n d " at a n y t i m e is c a l l e d t h e c u r r e n t l i n e . E D I T m a k e s
all t h e t e x t u a l c h a n g e s to t h e c u r r e n t l i n e . E D I T a l w a y s i n s e r t s n e w l i n e s b e f o r e
t h e c u r r e n t l i n e . W h e n y o u first e n t e r E D I T , t h e c u r r e n t l i n e is t h e first l i n e o f
the source.

4 . 1 . 2 . 2 Line Numbers
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 :
 EDIT—THE LINE EDITOR 111

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. EDIT ignores the spaces
between 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
114 AMIGADOS USER'S MANUAL

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 new
material before the current line. For example,
 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 Tweedledee and Tweedledum

2 a g r e e d t o a. b a t t l e ,
3 F o r T w e e d l e d u m said T w e e d l e d e e
4 a d s p o i l e d his n i c e n e w rattle.
5
6 A s b l a c k a s a tar b a r r e l
7 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
8 T h e y quite forgot their quorell

Execute these EDIT commands:

 EDIT—THE LINE EDITOR 117

Ml; E/dum/dee/; E/dee/dum/ < 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; E/a/A/; B /a /have / < n o w a t line 2 >
F B/ad/; B//H/ < H at l i n e s t a r t >
F P//; W; I < b e f o r e line after b l a n k o n e >
Just then flew down a monstrous
crow,
Z
M6; 2 ( A UIJ; N) < c o m m a s at e n d o f l i n e s >
F/quore/; E/quorell/quarrel./
< F i s , in f a c t , r e d u n d a n t >
W <Windup>

T h e f o l l o w i n g t e x t ( w i t h n e w line n u m b e r s ) is t h e r e s u l t .

1 Tweedledum and Tweedledee

2 A g r e e d to have a battle,
3 For T w e e d l e d u m said T w e e d l e d e e
4 H a d s p o i l e d h i s n i c e n e w rattle.
5
6 Just then flew d o w n a monstrous crow,
7 A s b l a c k a s a tar b a r r e l ,
8 Which frightened both the heroes so,
9 T h e y quite forgot their quarrel.

N o t e : If y o u e x p e r i m e n t w i t h e d i t i n g t h i s s o u r c e file, y o u ' l l f i n d t h a t y o u
d o n ' t have to u s e the c o m m a n d s in the example above. For instance, on the
second line, you could use the following c o m m a n d :

E/a/have aJ

to produce the s a m e result. In other w o r d s , E E x c h a n g e s " a " for " h a v e a " , a n d

B p l a c e s " h a v e " B e f o r e " a " to p r o d u c e " h a v e a " .

4.2 A Complete Specification of EDIT

A f t e r r e a d i n g t h e first p a r t o f t h i s c h a p t e r o n t h e b a s i c f e a t u r e s o f E D I T , y o u
s h o u l d b e a b l e t o u s e t h e e d i t o r i n a s i m p l e w a y . T h e r e s t o f t h i s c h a p t e r is a
r e f e r e n c e s e c t i o n t h a t p r o v i d e s a full s p e c i f i c a t i o n o f all t h e f e a t u r e s o f E D I T .
Y o u m a y n e e d to c o n s u l t t h i s s e c t i o n if y o u h a v e a n y p r o b l e m s w h e n e d i t i n g o r
if y o u w a n t to u s e E D I T in a m o r e s o p h i s t i c a t e d w a y .
T h e features described in this section are as follows:
118 AMIGADOS USER'S MANUAL

• 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 consist of a c o m m a n d name followed by zero or more
arguments. O n e or more space characters m a y optionally appear between
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 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 119

one space w h e n 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 alphabetic

name.

4.2.1.2 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 arithme-

tic 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
120 AMIGADOS USER'S MANUAL

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 (Begin-
n 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 Expressions
Commands 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

V-

t 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)

122 AMIGADOS USER'S MANUAL

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 :

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 .

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 . )

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

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.

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
c command group
m,n numbers
q q u a l i f i e r list ( p o s s i b l y e m p t y )
se search expression
s,t strings of arbitrary characters
sw 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 .
126 AMIGADOS USER'S M A N U A L

M-

m 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 . "

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 .

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 searches
( 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 .
128 AMIGADOS USER'S M A N U A L

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//
130 AMIGADOS USER'S MANUAL

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

 EDIT—THE LINE EDITOR 131

E U/carpenter/Walrus/ <Exchange>
B/bese/did / < i n s e r t string b e f o r e >
A L//;/ < I n s e r t string a f t e r >

w o u l d c h a n g e t h e line to

The Walrus did beseech;

4 . 2 . 5 . 2 The Null String

Y o u c a n u s e t h e n u l l , or e m p t y s t r i n g (//) a f t e r a n y s t r i n g c o m m a n d . If y o u
u s e the null string as the second string in an E c o m m a n d , EDIT r e m o v e s the
first s t r i n g f r o m t h e l i n e . P r o v i d e d E D I T f i n d s t h e first s t r i n g , a n A o r B
c o m m a n d with a null second string does nothing; otherwise, EDIT returns a n
e r r o r . A n u l l first s t r i n g i n a n y o f t h e t h r e e c o m m a n d s m a t c h e s at t h e initial
s e a r c h p o s i t i o n . T h e initial s e a r c h p o s i t i o n is t h e c u r r e n t c h a r a c t e r position
(initially t h e b e g i n n i n g 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 qualifiers
is present, 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 Variant

The AP (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 syntax
notation,

AP/s/t/

is e q u i v a l e n t t o

A/s/t/;PA/st/

while
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

 EDIT—THE LINE EDITOR 133

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 exchange
castle a n d knight twice a n d exchange p a w n and queen 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 ex-
changing 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.
 EDIT—THE LINE EDITOR 135

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 speci-
fied 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 non-

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 + + + + . (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.
 EDIT—THE LINE EDITOR 137

w h e r e t h e s t r i n g " s " is a f i l e n a m e . A F R O M c o m m a n d w i t h n o argument

r e s e l e c t s t h e o r i g i n a l s o u r c e file.
W h e n E D I T executes a F R O M c o m m a n d , the current line r e m a i n s current;
h o w e v e r , the next line c o m e s f r o m the n e w source.
E D I T d o e s n o t c l o s e a s o u r c e file w h e n t h e file c e a s e s t o b e c u r r e n t ; y o u c a n
r e a d f u r t h e r l i n e s f r o m t h e s o u r c e file b y r e s e l e c t i n g it l a t e r .
T o c l o s e a n o u t p u t file t h a t y o u o p e n e d i n E D I T , a n d t h a t s u b s e q u e n t l y y o u
w a n t t o o p e n f o r i n p u t (or t h e o t h e r w a y a r o u n d ) , y o u m u s t u s e t h e C F ( C l o s e
File) c o m m a n d . T h e C F c o m m a n d h a s t h e f o l l o w i n g f o r m :

C F .s.

w h e r e the string " s " represents a filename. W h e n y o u e n d an E D I T session,

E D I T c l o s e s a u t o m a t i c a l l y all t h e files y o u o p e n e d i n E D I T .
N o t e : A n y t i m e y o u o p e n a file, E D I T starts at t h e b e g i n n i n g o f t h a t file. If
y o u c l o s e a file w i t h C F , E D I T starts o n t h e first line o f t h a t file if y o u r e o p e n
it, a n d n o t at t h e line it w a s o n w h e n y o u c l o s e d t h e file.
A n e x a m p l e o f t h e u s e o f t h e F R O M c o m m a n d t o m e r g e l i n e s f r o m t w o files
follows:

Command Action
M10 Pass lines 1-9 from the FROM (source) file
F R O M .XYZ. Select new input, line 10 remains current
M6 Pass line 10 from FROM, lines 1-5 from XYZ
FROM Reselect FROM
M14 Pass line 6 from XYZ, lines 11-13 from FROM
F R O M .XYZ. Reselect XYZ
M* Pass line 14 from FROM, the rest of XYZ
FROM Reselect FROM
CF .XYZ. Close XYZ
M* Pass the rest of FROM (lines 15 till end-of-file)

4.2.8.3 Output 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 TO
TO.XYZ. Switch output file
M21 Pass lines 11-20 to XYZ
TO
M31 Pass lines 21-30 to TO
TO.XYZ.
M41 Pass lines 31-40 to 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 to temporary file
1000N Advance through source
TO Revert to TO
C F . :T/1. Close output file :T.l
12000. : T / 1 . Reuse as input 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 AMIGADOS USER'S MANUAL

4.2.10.2 Cancelling Global Changes

T h e R E W I N D c o m m a n d c a n c e l s all g l o b a l o p e r a t i o n s a u t o m a t i c a l l y . Y o u c a n
u s e t h e C G ( C a n c e l G l o b a l ) c o m m a n d t o c a n c e l i n d i v i d u a l c o m m a n d s at a n y
time.
W h e n a g l o b a l o p e r a t i o n is set u p b y o n e o f t h e c o m m a n d s G A , G B , o r G E ,
t h e o p e r a t i o n is a l l o c a t e d a n i d e n t i f i c a t i o n n u m b e r w h i c h is o u t p u t t o t h e
v e r i f i c a t i o n file (for e x a m p l e , G l ) . T h e a r g u m e n t f o r C G is t h e n u m b e r o f t h e
g l o b a l o p e r a t i o n to b e c a n c e l l e d . If C G is e x e c u t e d w i t h n o a r g u m e n t , E D I T
c a n c e l s all g l o b a l s .

4.2.10.3 Suspending Global Changes

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 -
 EDIT—THE LINE EDITOR 141

B A C K U P . T h i s b a c k u p file i s , o f c o u r s e , o n l y a v a i l a b l e u n t i l t h e n e x t t i m e E D I T
is run.
T h e S T O P c o m m a n d s t o p s E D I T i m m e d i a t e l y . N o f u r t h e r i n p u t o r o u t p u t is
attempted. In particular, the S T O P c o m m a n d stops E D I T from overwriting the
o r i g i n a l s o u r c e file. T y p i n g S T O P e n s u r e s t h a t n o c h a n g e is m a d e t o t h e i n p u t
information.
The Q c o m m a n d stops EDIT from executing the current c o m m a n d file
( 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 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 nonprinting
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
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 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 " .

However, EDIT may 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
q u e s t i o n m a r k s if t h e " ? ? " characters correspond to two nongraphic charac-
ters. T o find out w h a t really 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 .
 EDIT—THE LINE EDITOR 143

T o t u r n trailing s p a c e s o n or off, y o u u s e t h e T R ( T R a i l i n g s p a c e s ) c o m m a n d .
The T R c o m m a n d takes the following form:

TR sw

w h e r e s w r e p r e s e n t s a s w i t c h ( + for O N ; - f o r O F F ) . E D I T u s u a l l y s u p p r e s s e s
all trailing s p a c e s . T R + a l l o w s trailing s p a c e s t o r e m a i n o n b o t h i n p u t a n d
output lines.
To r e n u m b e r the source lines, you use the = command. The = command
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 , w h i c h is t h e n c l o s e d a n d re-
o p e n e d as a n e w 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 temporary
file a s a d e s t i n a t i o n . A n y g l o b a l s t h a t y o u s p e c i f y a r e c a n c e l l e d . E D I T does
n o t n e c e s s a r i l y r e q u i r e y o u to t y p e t h e c o m p l e t e w o r d ( t h a t i s , R E W I N D ) . T o
m o v e to t h e b e g i n n i n g , y o u c a n t y p e a n y o f t h e f o l l o w i n g : R E W I , R E W I N , o r
REWIND.

4.2.15 Abandoning Interactive Editing

T o a b a n d o n m o s t c o m m a n d s t h a t r e a d t e x t , y o u p r e s s C T R L - C . I n p a r t i c u l a r , if
y o u realize that a search expression h a s b e e n m i s t y p e d , t h e n C T R L - C stops the
s e a r c h . S i m i l a r l y t h e T c o m m a n d t y p e s to t h e e n d o f t h e s o u r c e , b u t C T R L - C
a b a n d o n s this action.
After you press CTRL-C, EDIT responds with the message

*** BREAK
144 AMIGADOS USER'S MANUAL

a n d r e t u r n s to reading c o m m a n d s . T h e current line d o e s , of course, d e p e n d o n

exactly w h e n you pressed C T R L - C .

Quick Reference Card

T h i s list u s e s t h e f o l l o w i n g a b b r e v i a t i o n s :

Notation Description
qs Qualified string
t String
n L i n e n u m b e r , o r . o r * ( c u r r e n t a n d last line)
sw + o r - ( o n or off)

Character Pointer Commands (Line Window Commands)

Command Action
< M o v e c h a r a c t e r p o i n t e r left

> M o v e character pointer right

# Delete character at pointer
$ 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
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

Positioning Commands
Command Action
M n 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 145

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 e l e t e c u r r e n t line
D F A qs Delete from after qs to e n d of line
D F B qs 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 T A qs 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 T B qs 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 qs t E x c h a n g e string qs with string t
EP qs 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
I Insert material from terminal before line
II I n s e r t f r o m file t
R Replace material from terminal
R t R e p l a c e m a t e r i a l f r o m file t
S A qs Split l i n e a f t e r q s
S B qs 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 G l o b a l l y e x c h a n g e q s for t
CG n C a n c e l g l o b a l n (all if n o m i t t e d )
DG n D i s a b l e g l o b a l n (all if n o m i t t e d )
EG n E n a b l e g l o b a l n (all if n o m i t t e d )
SHG Display info o n globals used
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 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
SHD S h o w data
STOP Stop
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 store
Probable cause:
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 opera-
tion 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.
148 AMIGADOS USER'S MANUAL

221: file is not an object module

Probable 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 resident library during load

202: object in use

Probable 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 already exists

Probable 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 not found

205: object not found

Probable 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 window

Probable 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 . )
 APPENDIX: ERROR CODES AND MESSAGES 149

Y o u c a n a l s o g e t t h i s e r r o r f r o m N E W C L I if y o u s u p p l y a d e v i c e n a m e t h a t is
not a window.
Recovery suggestion:
You should respecify the window.

2 2 0 : invalid stream component name

Probable 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 not of required type

Probable 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 validated

Probable 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 write-protected
Probable 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 across devices attempted

Probable cause:
R E N A M E only changes a filename on the same device, although you can use
150 AMIGADOS USER'S MANUAL

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 allowed
(80).
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 from writing

Probable cause:
 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 from reading

Probable 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 disk

Probable 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 drive
Probable cause:
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 request type unknown
Probable 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 object lock

Probable 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 AMIGADOS USER'S MANUAL

Recovery suggestion:
C h e c k y o u r c o d e s o t h a t y o u o n l y p a s s valid l o c k s to A m i g a D O S calls t h a t
expect locks.

219: seek error

Probable cause:
Y o u h a v e a t t e m p t e d to call S E E K w i t h i n v a l i d a r g u m e n t s .
Recovery suggestion:
M a k e s u r e t h a t y o u o n l y S E E K w i t h i n t h e file. Y o u c a n n o t S E E K o u t s i d e
t h e b o u n d s of t h e file.

2 3 2 : no more entries in directory

Probable cause:
T h e r e are n o m o r e entries in the directory that y o u are examining.
Recovery suggestion:
T h i s e r r o r c o d e i n d i c a t e s t h a t t h e A m i g a D O S call E X N E X T h a s n o m o r e
e n t r i e s i n t h e d i r e c t o r y y o u a r e e x a m i n i n g to h a n d b a c k t o y o u . S t o p calling
EXNEXT.

Glossary
Arguments
A d d i t i o n a l i n f o r m a t i o n s u p p l i e d to c o m m a n d s .
Character pointer
P o i n t e r t o t h e left e d g e of a line w i n d o w in E D I T . Y o u u s e it t o d e f i n e t h e
p a r t of a line t h a t E D I T m a y alter.
Character string
S e q u e n c e of p r i n t a b l e c h a r a c t e r s .
Command
A n i n s t r u c t i o n y o u g i v e directly to t h e c o m p u t e r .
C o m m a n d L i n e I n t e r f a c e (CLI)
A process that decodes user input.
Console handler
See terminal handler.
C o m m a n d template
T h e m e t h o d of d e f i n i n g t h e s y n t a x f o r e a c h c o m m a n d .
Control combination
A c o m b i n a t i o n of t h e C T R L k e y a n d a letter or s y m b o l . T h e C T R L k e y is
p r e s s e d d o w n w h i l e t h e letter or s y m b o l is t y p e d . It a p p e a r s i n t h e d o c u -
m e n t a t i o n , for e x a m p l e , in the form C T R L - A .
Current cursor position
T h e p o s i t i o n t h e c u r s o r is c u r r e n t l y at.
 APPENDIX: GLOSSARY 153

Current directory
T h i s is e i t h e r t h e r o o t d i r e c t o r y or t h e last d i r e c t o r y y o u set y o u r s e l f in w i t h
the c o m m a n d C D .
Current drive
T h e d i s k d r i v e t h a t is i n s e r t e d a n d d e c l a r e d to b e c u r r e n t . T h e d e f a u l t is
SYS:.
Current line
T h e l i n e t h a t E D I T h a s in its h a n d at a n y time.
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 same
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 .
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 Developer'
Manual
Contents

1. Programming on the Amiga

2. Calling AmigaDOS
3. The Macro Assembler
4. 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 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
1.2.1 Getting Started
1.2.2 Calling Resident Libraries
1.2.3 Creating an Executable Program
1.3 Running a Program Under the CLI
1.3.1 Initial E n v i r o n m e n t in A s s e m b l e r
1.3.2 Initial E n v i r o n m e n t i n C
1.3.3 F a i l u r e of R o u t i n e s
1.3.4 Terminating a Program
1.4 Running a Program Under the Workbench
1.5 Cross Development
1.5.1 Cross Development on a Sun Microsystem
1.5.2 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 , Sun,
and IBM PC.
T h i s m a n u a l a s s u m e s t h a t y o u h a v e s o m e familiarity w i t h e i t h e r C or A s s e m -
b l e r . It d o e s n o t a t t e m p t to t e a c h e i t h e r of t h e s e l a n g u a g e s . A n i n t r o d u c t i o n to
C c a n b e f o u n d i n t h e b o o k The C Programming Language b y B r i a n W . K e r n i g h a n
a n d D e n n i s M . Ritchie, published b y Prentice Hall. T h e r e are a n u m b e r of
b o o k s o n w r i t i n g 6 8 0 0 0 a s s e m b l e r , i n c l u d i n g Programming the MC68000 by Tim
King a n d Brian Knight, published by A d d i s o n W e s l e y .
158 AMIGADOS DEVELOPER'S MANUAL

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 User's Manual, ROM Kernel Manual,
a n d p o s s i b l y t h e AmigaDOS Technical Reference 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 L V O n a m e . S o , f o r i n s t a n c e , a call
could be J S R 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
160 AMIGADOS DEVELOPER'S MANUAL

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 argu-
m 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
162 AMIGADOS DEVELOPER'S MANUAL

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 ending
in .asm are assembly source programs. You can use the assembler to
a s s e m b l e t h e s e a n d p r o d u c e a n o b j e c t file ( e n d i n g w i t h . o b j ) i n t h e c u r r e n t
directory.
T h e compiler metacc takes m a n y options with the following format:

metacc [<optl>[,<opt2>[,..<optn>]]][<file>[,...<filen>]]

T h e o p t i o n s a v a i l a b l e a r e as f o l l o w s :

-c -g - g o - w - p - p g - 0 [ < o p t f l a g s > ] - f s i n g l e
- S -E - C - X 7 0 - o < o u t p u t > - D < n a m e = d e f >
- U < n a m e > -I < d i r > -B < s t r i n g > - t [ p 0 1 2 ]
 PROGRAMMING ON THE AMIGA 163

T h e f o l l o w i n g o p t i o n s i n s t r u c t m e t a c c to:

-c 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 older

format set b y the adb debugger. A l s o , p a s s t h e -lg flag
t o Id.

-w s u p p r e s s all w a r n i n g m e s s a g e s .

-p p r o d u c e p r o f i l i n g c o d e to c o u n t t h e n u m b e r o f t i m e s e a c h
r o u t i n e is c a l l e d . If l o a d i n g t a k e s p l a c e , r e p l a c e t h e s t a n d a r d
s t a r t u p r o u t i n e b y o n e t h a t is a u t o m a t i c a l l y c a l l e d b y t h e
m o n i t o r a n d u s e s a s p e c i a l p r o f i l i n g library i n s t e a d o f t h e
s t a n d a r d C library.
U s e the prof program to generate an execution profile.

-pg p r o d u c e p r o f i l i n g c o d e like - p , b u t i n v o k e a r u n - t i m e r e -
c o r d i n g m e c h a n i s m t h a t k e e p s m o r e e x t e n s i v e statistics a n d
p r o d u c e s a g m o n . o u t file at n o r m a l t e r m i n a t i o n .
U s e t h e g p r o f p r o g r a m to g e n e r a t e a n e x e c u t i o n p r o f i l e .

-0[<optflags>] use the object code optimizer to improve the generated

code.
If " o p t f l a g s " a p p e a r s , y o u i n c l u d e < o p t f l a g s > in t h e c o m -
m a n d line to run the optimizer. Y o u can u s e - O to pass
option flags.

-fsingle use single-precision a r i t h m e t i c in c o m p u t a t i o n s involving

o n l y flo at n u m b e r s ; t h a t i s , d o n o t c o n v e r t e v e r y t h i n g to
double (that is, the default).
N o t e : F l o a t i n g - p o i n t p a r a m e t e r s a r e still c o n v e r t e d t o d o u b l e -
p r e c i s i o n , a n d f u n c t i o n s t h a t r e t u r n v a l u e s still r e t u r n d o u b l e -
precision values.

W A R N I N G : Certain programs run m u c h faster using the -fsingle option,

b u t b e w a r e t h a t y o u c a n l o s e s i g n i f i c a n c e d u e to l o w e r p r e c i s i o n i n t e r m e -
diate values.
164 AMIGADOS DEVELOPER'S MANUAL

-S compile the specified C program(s) and leave the assembler-

l a n g u a g e o u t p u t o n c o r r e s p o n d i n g files e n d i n g w i t h . o b j .

-E run only the C preprocessor on the named C program(s) and

s e n d t h e r e s u l t to t h e s t a n d a r d o u t p u t .

-c prevent the C preprocessor from removing comments.

-X70 generate code using A m i g a floating point format. This c o d e

is c o m p a t i b l e w i t h t h e f l o a t i n g p o i n t m a t h R O M library
provided on the Amiga.

-o < o u t p u t > n a m e t h e final o u t p u t file " o u t p u t " . If y o u u s e t h i s o p t i o n ,

t h e file a . o u t is left u n d i s t u r b e d .

-D<name = def> d e f i n e " n a m e " to t h e p r e p r o c e s s o r , as if b y # d e f i n e . If n o

d e f i n i t i o n is g i v e n , d e f i n e t h e n a m e a s "1".

-U<name> r e m o v e a n y initial d e f i n i t i o n of " n a m e " .

-I<dir> a l w a y s l o o k for # i n c l u d e files w h o s e n a m e s d o n o t b e g i n

w i t h " / " first in t h e d i r e c t o r y of t h e < f i l e > a r g u m e n t , t h e n
l o o k in t h e < d i r > s p e c i f i e d in t h e -I o p t i o n , a n d finally l o o k
in the /usr/include directory.

-B<string> find substitute c o m p i l e r p a s s e s i n t h e files specified by

< s t r i n g > w i t h t h e e n d i n g s c p p , c c o m , a n d c 2 . If " s t r i n g " is
empty, use a backup version.

-t[p012] f i n d o n l y t h e d e s i g n a t e d c o m p i l e r p a s s e s in t h e files w h o s e
n a m e s a r e c o n s t r u c t e d b y a - B o p t i o n . I n t h e a b s e n c e of a - B
o p t i o n , a s s u m e < s t r i n g > to b e / u s r / n e w / .
T h e letter a n d n u m b e r c o m b i n a t i o n s t h a t y o u c a n s p e c i f y f o r
t h e -t o p t i o n h a v e t h e f o l l o w i n g m e a n i n g s :

p cpp—the C preprocessor
0 m e t a c o m — b o t h p h a s e s of t h e C c o m p i l e r , b u t n o t t h e
optimizer.
1 I g n o r e d i n this s y s t e m — t h i s o p t i o n w o u l d b e f o r t h e
s e c o n d p h a s e of a t w o - p h a s e c o m p i l e r b u t in t h e S u n
system; ccom includes both phases.
2 c2—the object code optimizer.

T h e compiler metacc a s s u m e s that other a r g u m e n t s are loaded option argu-

m 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
 PROGRAMMING ON THE AMIGA 165

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 /lib/cpp
Compiler /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 p. a
Standard directory ( # i n c l u d e . /usr/include
Files p r o d u c e d for analysis
by prof mon.out
File p r o d u c e d f o r a n a l y s i s
by gprof gmon.out

Figure l . A : Special metacc Filenames

Y o u c a n d o w n l o a d t h e files y o u p r o d u c e f r o m t h e l i n k e r o n t h e S u n t o y o u r
A m i g a in t h r e e w a y s : t h e first, a n d b y far t h e e a s i e s t , r e q u i r e s a B i l l B o a r d ; t h e
s e c o n d r e q u i r e s a p a r a l l e l p o r t ; a n d t h e t h i r d r e q u i r e s a serial l i n e .
If y o u have the special hardware device called a BillBoard, you can
d o w n l o a d y o u r l i n k e d l o a d file (by c o n v e n t i o n t h i s s h o u l d e n d w i t h .Id) a s
follows:

1. S t a r t u p t h e p r o g r a m " b i n l o a d " o n t h e S u n

b i n l o a d -p &

(this n e e d o n l y b e d o n e o n c e )
166 AMIGADOS DEVELOPER'S MANUAL

2. Then on the Amiga, type

download < s u n filename> <amiga filename>

3. T o run the program, type

<amiga filename>

For example:

O n the Sun, type

b i n l o a d -p 6?

O n the Amiga, type

download testld test

or type

download /usr/commodore/amiga/V24/examples/DOS/test.ld test

then type

test
Note that D O W N L O A D g a i n s a c c e s s to files o n t h e S u n r e l a t i v e t o the
d i r e c t o r y w h e r e b i n l o a d s t a r t e d . If t h e d i r e c t o r y o n t h e S u n w a s / u s r / c o m m o d o r e /
a m i g a / V 2 4 / e x a m p l e s / D O S a s a b o v e , t h e f i l e n a m e t e s t . l d is all t h a t is n e c e s s a r y .
If y o u c a n n o t r e m e m b e r t h e d i r e c t o r y w h e r e b i n l o a d s t a r t e d , y o u m u s t s p e c i f y
t h e full n a m e . T o s t o p b i n l o a d , d o a " p s " a n d t h e n a " k i l l " o n its P I D . N o t e
t h a t t h e s o f t r e s e t o f t h e c o m p u t e r tells b i n l o a d t o w r i t e a m e s s a g e t o i t s
s t a n d a r d o u t p u t ( t h e d e f a u l t is t h e w i n d o w w h e r e it s t a r t e d ) . If t h e t r a n s f e r
h a n g s , p r e s s C T R L - C at t h e A m i g a t o kill D O W N L O A D . ( S e e S e c t i o n 3 . 2 in t h e
AmigaDOS User's Manual i n t h i s b o o k for f u r t h e r i n f o r m a t i o n o n t h e A m i g a D O S
control conventions CTRL-C, CTRL-D, CTRL-E, and CTRL-F.)
If y o u d o n o t h a v e a B i l l B o a r d , y o u c a n d o w n l o a d files t h r o u g h a p a r a l l e l
port. To do this, follow these steps:

1. S e n d t h e d o w n l o a d 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
typing

send demold
 PROGRAMMING ON THE AMIGA 167

If y o u d o n o t g i v e " s e n d " a n y a r g u m e n t s , t h e s t a n d a r d i n p u t is u s e d . T h e
d e f a u l t o u t p u t d e v i c e is /dev/lpO, w h i c h is u s u a l l y c o r r e c t . T o c h a n g e t h e
d e f a u l t o u t p u t , u s e t h e -o a r g u m e n t .
2. O n the A m i g a , type the following:

READ demo

R E A D t h e n r e a d s c h a r a c t e r s f r o m t h e parallel p o r t a n d p l a c e s t h e m i n t h e
file n a m e d " d e m o " .
3. O n c e R E A D has finished, type

demo

to run the program d e m o .

Y o u c a n a l s o d o w n l o a d files serially. T o d o t h i s , f o l l o w t h e s e s t e p s :

1. C o n v e r t t h e B i n a r y L o a d File i n t o a n A S C I I h e x file e n d i n g w i t h Q b y t y p i n g

convert <demo.ld >demo.dl

( w h e r e . d l , b y c o n v e n t i o n , s t a n d s for D o w n L o a d ) . T h e a b o v e r u l e e x i s t s i n
t h e i n c l u d e d m a k e f i l e , m a k e a m i g a . ( S e e t h e AmigaDOS Technical Reference
Manual, 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.)

2. 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 reason.

R e b o o t t h e S u n if t h i s h a p p e n s .
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

t o g e t t h e R E A D o n t h e A m i g a to c o m p l e t e . O n c e this is d o n e , start a n e w
R E A D and type the following symbols on the Sun:

">

1.5.2 Cross Development Under MS-DOS

T o c r o s s - d e v e l o p o n a c o m p u t e r r u n n i n g M S - D O S for y o u r A m i g a , y o u n e e d
v a r i o u s t o o l s t h a t a r e s u p p l i e d i n t h e d i r e c t o r y \V25\bin. T h e s e i n c l u d e t h e C
compiler, assembler, and linker as well as c o m m a n d s to assist in d o w n l o a d i n g .
Y o u u s e t h e s a m e s y n t a x for t h e t o o l s r u n n i n g u n d e r M S - D O S a s u n d e r t h e C L I
on the Amiga.
T o d o w n l o a d via a n I B M P C serial p o r t (called A U X ) , f o l l o w t h e s e s t e p s :

1. T y p e o n y o u r A m i g a

READ file SERIAL

2. O n the P C , type

convert <file.ld >AUX:

3. O n your Amiga, you can n o w type

file

to t h e p r o g r a m .

1.5.3 Cross Development on Other Computers

Y o u ' l l n e e d to h a v e a s u i t a b l e c r o s s c o m p i l e r or a s s e m b l e r , a n d to i n c l u d e
files d e f i n i n g all t h e e n t r y p o i n t s . Y o u ' l l a l s o n e e d e i t h e r t h e A m i g a l i n k e r
A L I N K r u n n i n g o n y o u r e q u i p m e n t or o n t h e A m i g a . Finally y o u ' l l n e e d a w a y
t o c o n v e r t a b i n a r y file i n t o a h e x a d e c i m a l s t r e a m t e r m i n a t e d w i t h a Q (as t h i s
 PROGRAMMING ON THE AMIGA 169

is t h e w a y t h a t R E A D a c c e p t s d a t a ) , a n d a w a y o f p u t t i n g t h i s d a t a o u t f r o m a
serial o r p a r a l l e l p o r t .
O n c e y o u h a v e c r e a t e d a s u i t a b l e b i n a r y file, y o u m u s t t r a n s f e r t h i s to t h e
A m i g a u s i n g t h e R E A D c o m m a n d (as d e s c r i b e d in S e c t i o n 1 . 5 . 2 o f t h i s m a n -
u a l ) . If y o u h a v e t h e A m i g a l i n k e r r u n n i n g o n y o u r c o m p u t e r , t h e n y o u c a n
t r a n s f e r c o m p l e t e b i n a r y l o a d files; o t h e r w i s e , y o u ' l l h a v e t o t r a n s f e r b i n a r y
o b j e c t files i n t h e f o r m a t a c c e p t e d b y A L I N K , a n d t h e n p e r f o r m t h e l i n k s t e p
on the Amiga.
Chapter 2

Calling AmigaDOS

This chapter describes the functions provided b y the A m i g a D O S resident

library. T o h e l p y o u , it p r o v i d e s t h e following: a n e x p l a n a t i o n of t h e s y n t a x , a full
d e s c r i p t i o n o f e a c h f u n c t i o n , a n d a quick r e f e r e n c e card o f t h e available f u n c t i o n s .

2.1 Syntax
2.2 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.
 CALLING AMIGADOS 171

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 Register
Example lock = 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 AMIGADOS DEVELOPER'S MANUAL

Argument: 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 = CreateDir( name)
DO Dl
Argument: name-string
Result: lock - pointer to a lock
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: To m a k e a directory associated with a lock the current working
directory.
Form: oldLock = CurrentDir( lock )
DO Dl
Argument: l o c k - p o i n t e r to a l o c k
Result: o l d L o c k - p o i n t e r to a l o c k
Description:
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 = DeleteFilei name )
DO Dl
 CALLING AMIGADOS 173

Argument: n a m e - string
Result: success - boolean
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 = DupLock( lock)
DO 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: 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 .
Form: success = Examine( lock, FilelnfoBlock )
DO Dl D2
Argument: 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
Result: success - boolean
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: To examine the next entry in a directory.
Form: 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 = Info( lock, Info. Data )
DO Dl D2
Argument: l o c k - p o i n t e r to a l o c k
Info Data - pointer to an Info Data structure
Result: success - boolean
Description:
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.
 CALLING AMIGADOS 175

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, accessMode )
DO Dl D2
Argument: 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 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
a c c e s s M o d e is A C C E S S . 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 an
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 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 = Open( name, accessMode)
DO Dl 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 . (To
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 . )
 CALLING AMIGADOS 177

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( lock )
DO 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, buffer, length )
DO Dl D2 D3
Argument: 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( oldName, newName)
DO Dl D2
Argument, 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 contain-
i 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, position, mode )
DO Dl D2 D3
Argument: file - file h a n d l e
position - integer
m o d e - integer
Result: oldPosition - integer
Description:
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, comment)
DO Dl D2
Argument: 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 )
DO Dl D2
Argument: n a m e - file n a m e
mask - the protection mask required
Result: success - boolean
Description:
S e t P r o t e c t i o n s e t s t h e p r o t e c t i o n a t t r i b u t e s o n a file o r d i r e c t o r y . T h e lower
f o u r bits o f t h e m a s k are a s f o l l o w s :
b i t 3 : if 1 t h e n r e a d s n o t a l l o w e d , e l s e r e a d s a l l o w e d .
bit 2 : if 1 t h e n w r i t e s n o t a l l o w e d , e l s e w r i t e s a l l o w e d .
bit 1: if 1 t h e n e x e c u t i o n n o t a l l o w e d , e l s e e x e c u t i o n a l l o w e d .
bit 0 : if 1 t h e n d e l e t i o n n o t a l l o w e d , e l s e d e l e t i o n a l l o w e d .

Bits 31-4 R e s e r v e d .

O n l y d e l e t e is c h e c k e d f o r in t h e c u r r e n t r e l e a s e o f A m i g a D O S . R a t h e r t h a n
r e f e r r i n g to bits b y n u m b e r y o u s h o u l d u s e t h e d e f i n i t i o n s in " i n c l u d e / l i b r a r i e s /
dos.h".

UnLock
Purpose: T o u n l o c k a d i r e c t o r y or file.
Form: Unlock( lock)
Dl
Argument: l o c k - p o i n t e r to a l o c k
180 AMIGADOS DEVELOPER'S MANUAL

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 file, timeout)
DO Dl D2
Argument: 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 = Write( file, buffer, length )
DO Dl D2 D3
Argument: 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 writ-
t 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 , for example,
i n d i c a t e t h a t t h e d i s k is full.
 CALLING AMIGADOS 181

Process Handling

CreateProc
Purpose: T o create a n e w process.
Form: process = CreateProc( name, pri, segment, stackSize )
DO Dl D2 D3 D4
Argument: 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: 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 .
Form: v: = DateStampi v )
Argument: v - pointer
Description:
D a t e S t a m p t a k e s a v e c t o r o f t h r e e l o n g w o r d s t h a t is s e t t o t h e c u r r e n t t i m e .
T h e first e l e m e n t in t h e v e c t o r is a c o u n t o f t h e n u m b e r o f d a y s . T h e s e c o n d
e l e m e n t is t h e n u m b e r o f m i n u t e s e l a p s e d in t h e d a y . T h e t h i r d is t h e n u m b e r
o f ticks e l a p s e d in t h e c u r r e n t m i n u t e . A tick h a p p e n s 5 0 t i m e s a s e c o n d .
D a t e S t a m p e n s u r e s t h a t t h e d a y a n d m i n u t e a r e c o n s i s t e n t . All t h r e e e l e m e n t s
a r e z e r o if t h e d a t e is u n s e t . D a t e S t a m p c u r r e n t l y o n l y r e t u r n s e v e n m u l t i p l e s
o f 5 0 t i c k s . T h e r e f o r e t h e t i m e y o u g e t is a l w a y s a n i n t e g r a l n u m b e r o f s e c o n d s .
182 AMIGADOS DEVELOPER'S MANUAL

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 name )
DO 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, input, output)
DO Dl D2 D3
Argument: 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
Result: Success - boolean
Description:
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: To load a load module into m e m o r y .
Form: segment = LoadSeg( name )
DO Dl
Argument: n a m e - string
184 AMIGADOS DEVELOPER'S MANUAL

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( segment)
Dl
Argument: s e g m e n t - p o i n t e r to a s e g m e n t
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 terminal
or n o t .
Lock to l o c k a file or d i r e c t o r y .
 CALLING AMIGADOS 185

Open to o p e n a file for i n p u t or o u t p u t .

Output 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 .
ParentDir 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 to r e a d b y t e s o f d a t a f r o m a file.
Rename to r e n a m e a file o r d i r e c t o r y .
Seek to m o v e to a logical p o s i t i o n in a file.
SetComment to set a c o m m e n t .
SetProtection to set file, o r d i r e c t o r y , p r o t e c t i o n .
Unlock to u n l o c k a file or d i r e c t o r y .
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.

Process Handling
CreateProc to create a n e w process.
DateStamp to obtain the date a n d time in internal format.
Delay to 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.
DeviceProc to 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 to exit f r o m a p r o g r a m .

Loading Code
Execute to e x e c u t e a C L I c o m m a n d .
LoadSeg 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 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
3.2 Calling the Assembler
3.3 Program Encoding
3.3.1 Comments
3.3.2 Executable Instructions
3.3.2.1 Label Field
3.3.2.2 Local Labels
3.3.2.3 O p c o d e Field
3.3.2.4 O p e r a n d Field
3.3.2.5 C o m m e n t Field
3.4 Expressions
3.4.1 Operators
3.4.2 O p e r a n d T y p e s for Operators
3.4.3 Symbols
3.4.4 Numbers
3.5 Addressing Modes
3.6 Variants on Instruction Types
3.7 Directives

3.1 Introduction to the 68000 Microchip

T h i s s e c t i o n g i v e s a brief i n t r o d u c t i o n to t h e 6 8 0 0 0 m i c r o c h i p . It s h o u l d h e l p
y o u to u n d e r s t a n d t h e c o n c e p t s i n t r o d u c e d later i n t h e c h a p t e r . It a s s u m e s t h a t
y o u have already h a d experience with assembly language on another computer.
T h e m e m o r y available to t h e 6 8 0 0 0 c o n s i s t s of
 THE MACRO ASSEMBLER 187

• the internal registers (on the chip), and

• the external main m e m o r y .

T h e r e a r e 17 r e g i s t e r s , b u t o n l y 16 a r e a v a i l a b l e at a n y g i v e n m o m e n t . E i g h t
o f t h e m a r e d a t a r e g i s t e r s n a m e d DO t o D 7 , a n d t h e o t h e r s a r e a d d r e s s r e g i s t e r s
c a l l e d AO to A 7 . E a c h r e g i s t e r c o n t a i n s 3 2 b i t s . I n m a n y c o n t e x t s , y o u m a y u s e
either k i n d of register, b u t others d e m a n d a specific k i n d . For i n s t a n c e , y o u
m a y u s e a n y r e g i s t e r for o p e r a t i o n s o n w o r d (16-bit) a n d l o n g w o r d (32-bit)
quantities or for i n d e x e d addressing of m a i n m e m o r y . A l t h o u g h , for operations
o n b y t e (8-bit) o p e r a n d s , y o u m a y o n l y u s e d a t a r e g i s t e r s , a n d f o r a d d r e s s i n g
m a i n m e m o r y , y o u m a y only use address registers as stack pointers or b a s e
r e g i s t e r s . R e g i s t e r A 7 is t h e s t a c k p o i n t e r , a n d t h i s is i n fact t w o distinct
r e g i s t e r s : t h e s y s t e m s t a c k p o i n t e r a v a i l a b l e in s u p e r v i s o r m o d e a n d t h e u s e r
s t a c k p o i n t e r a v a i l a b l e in u s e r m o d e .
T h e m a i n m e m o r y c o n s i s t s o f a n u m b e r of b y t e s o f m e m o r y . E a c h b y t e h a s
a n i d e n t i f y i n g n u m b e r c a l l e d its a d d r e s s . M e m o r y is u s u a l l y ( b u t n o t a l w a y s )
a r r a n g e d s o t h a t its b y t e s h a v e a d d r e s s e s 0 , 1 , 2 , . . ., N - 2 , N - l w h e r e t h e r e a r e
N b y t e s o f m e m o r y in total. T h e size o f m e m o r y t h a t y o u c a n d i r e c t l y a c c e s s is
v e r y l a r g e — u p to 16 m i l l i o n b y t e s . T h e 6 8 0 0 0 c a n p e r f o r m o p e r a t i o n s o n b y t e s ,
w o r d s , or l o n g w o r d s o f m e m o r y . A w o r d is t w o c o n s e c u t i v e b y t e s . I n a w o r d ,
t h e first b y t e h a s a n e v e n a d d r e s s . A l o n g w o r d is f o u r c o n s e c u t i v e b y t e s a l s o
s t a r t i n g a t a n e v e n a d d r e s s . T h e a d d r e s s o f a l o n g w o r d is t h e e v e n a d d r e s s o f
its l o w e s t n u m b e r e d first b y t e .
A s well as h o l d i n g items of data b e i n g m a n i p u l a t e d b y t h e c o m p u t e r , t h e
m a i n m e m o r y a l s o h o l d s t h e i n s t r u c t i o n s t h a t tell t h e c o m p u t e r w h a t to d o .
E a c h instruction occupies from o n e to 5 w o r d s , consisting of an o p e r a t i o n w o r d
b e t w e e n zero and four operand w o r d s . T h e operation w o r d specifies what
a c t i o n is to b e p e r f o r m e d ( a n d i m p l i c i t l y h o w m a n y w o r d s t h e r e a r e i n t h e
w h o l e i n s t r u c t i o n ) . T h e o p e r a n d w o r d s i n d i c a t e w h e r e in t h e r e g i s t e r s or m a i n
m e m o r y a r e t h e i t e m s to b e m a n i p u l a t e d , a n d w h e r e t h e r e s u l t s h o u l d b e
placed.
T h e a s s e m b l e r u s u a l l y e x e c u t e s i n s t r u c t i o n s o n e at a t i m e in t h e o r d e r t h a t
t h e y o c c u r i n m e m o r y , like t h e w a y y o u f o l l o w t h e s t e p s i n a r e c i p e o r p l a y t h e
n o t e s in a p i e c e o f w r i t t e n m u s i c . T h e r e is a s p e c i a l r e g i s t e r c a l l e d t h e p r o g r a m
c o u n t e r ( P C ) w h i c h y o u u s e to h o l d t h e a d d r e s s o f t h e i n s t r u c t i o n y o u w a n t t h e
a s s e m b l e r to e x e c u t e n e x t . S o m e i n s t r u c t i o n s , c a l l e d j u m p s o r b r a n c h e s , u p s e t
the usual order, and force the assembler to continue executing the instruction
at a s p e c i f i c a d d r e s s . T h i s lets t h e c o m p u t e r p e r f o r m a n a c t i o n r e p e a t e d l y , o r
d o different things d e p e n d i n g o n the values of data items.
T o r e m e m b e r particular things about the state of the c o m p u t e r , y o u can u s e
o n e other special register called the status register (SR).
188 AMIGADOS DEVELOPER'S MANUAL

3.2 Calling the Assembler

T h e c o m m a n d t e m p l a t e f o r a s s e m is

" P R O G = FROM/A,-0/K,-V/K,-L/K,-H/K,-C/K,-I/K"

Alternatively, the format of the c o m m a n d line can b e described as

assem <sourcefile> [-o < o b j e c t f i l e > ]

[-1 < l i s t i n g f i l e > ]
[-v < v e r i f i c a t i o n f i l e > ]
[-h < h e a d e r f i l e > ]
[-c < o p t i o n s > ]
[-i < i n c l u d e d i r l i s t > ]

T h e a s s e m b l e r d o e s n o t p r o d u c e a n o b j e c t file or a listing file u n l e s s y o u

r e q u e s t t h e m explicitly.
A s t h e a s s e m b l e r is r u n n i n g , it g e n e r a t e s d i a g n o s t i c m e s s a g e s ( e r r o r s , w a r n -
i n g s , a n d a s s e m b l y statistics) a n d s e n d s t h e m to t h e s c r e e n u n l e s s y o u s p e c i f y
a v e r i f i c a t i o n file.
T o f o r c e t h e i n c l u s i o n o f t h e n a m e d file i n t h e a s s e m b l y a t t h e h e a d o f t h e
s o u r c e file, y o u u s e - h < f i l e n a m e > o n t h e c o m m a n d l i n e . T h i s h a s t h e s a m e
effect as using

INCLUDE " < f f l e n a r n e > "

o n l i n e 1 o f t h e s o u r c e file.
T o s e t u p t h e list o f d i r e c t o r i e s t h a t t h e a s s e m b l e r s h o u l d s e a r c h for a n y
I N C L U D E d f i l e s , y o u u s e t h e -i k e y w o r d . Y o u s h o u l d s p e c i f y as m a n y d i r e c t o -
r i e s a s y o u r e q u i r e a f t e r t h e - i , s e p a r a t i n g t h e d i r e c t o r y n a m e s b y a c o m m a (,), a
p l u s s i g n ( + ) , o r a s p a c e . N o t e t h a t if y o u u s e a s p a c e , y o u m u s t e n c l o s e t h e
e n t i r e d i r e c t o r y list in d o u b l e q u o t e s ( " ) . U n i x u s e r s , h o w e v e r , m u s t e s c a p e a n y
d o u b l e q u o t e s w i t h a b a c k s l a s h (\").
T h e o r d e r o f t h e list d e t e r m i n e s t h e o r d e r o f t h e d i r e c t o r i e s w h e r e the
a s s e m b l e r s h o u l d s e a r c h for I N C L U D E d f i l e s . T h e a s s e m b l e r initially s e a r c h e s
t h e c u r r e n t d i r e c t o r y b e f o r e a n y o t h e r s . T h u s a n y file t h a t y o u I N C L U D E i n a
p r o g r a m m u s t b e in t h e c u r r e n t d i r e c t o r y , or i n o n e o f t h e d i r e c t o r i e s l i s t e d in
t h e -i list. F o r i n s t a n c e , if t h e p r o g r a m " f r e d " I N C L U D E S , a p a r t f r o m files i n t h e
c u r r e n t d i r e c t o r y , a file f r o m t h e d i r e c t o r y " i n t r n l / i n c l " , a file f r o m t h e d i r e c t o r y
" i n c l u d e / a s m " , a n d a file f r o m t h e d i r e c t o r y " e x t r n l / i n c l " , y o u c a n g i v e t h e -i
d i r e c t o r y list i n t h e s e t h r e e w a y s :
 THE MACRO ASSEMBLER 189

a s s e m f r e d -i i n t r n l / i n c l , i n c l u d e / a s m , e x t r n l / i n c l
a s s e m f r e d -i m t r n l / i n c l + I n c l u d e / a s m + e x t r n l / l n c l
a s s e m f r e d -i " i n t r n l / i n c l i n c l u d e / a s m e x t r n l / i n c l "

o r , b y u s i n g t h e s p a c e s e p a r a t o r o n t h e S u n u n d e r U n i x , like t h i s

a s s e m f r e d -i V ' i n t r n l / i n c l i n c l u d e / a s m e x t r n l / i n c l V

T h e -c k e y w o r d a l l o w s y o u to p a s s c e r t a i n o p t i o n s t o t h e a s s e m b l e r . Each
o p t i o n c o n s i s t s o f a s i n g l e c h a r a c t e r (in e i t h e r u p p e r or l o w e r c a s e ) , p o s s i b l y
followed immediately b y a n u m b e r . Valid options follow h e r e :

S p r o d u c e s a s y m b o l d u m p a s a p a r t o f t h e o b j e c t file.
D i n h i b i t s t h e d u m p i n g o f local l a b e l s as p a r t o f a s y m b o l d u m p . ( F o r C
p r o g r a m m e r s , a n y l a b e l b e g i n n i n g w i t h a p e r i o d is c o n s i d e r e d a l o c a l
label.)
C i g n o r e s t h e d i s t i n c t i o n b e t w e e n u p p e r a n d l o w e r c a s e in l a b e l s .
X p r o d u c e s a c r o s s - r e f e r e n c e t a b l e at t h e e n d o f t h e l i s t i n g file.

Examples

a s s e m f r e d . a s m -o fred.o

a s s e m b l e s t h e file " f r e d . a s m " a n d p r o d u c e s a n o b j e c t m o d u l e i n t h e file

fred.o.

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
190 AMIGADOS DEVELOPER'S MANUAL

3.3.1 Comments
To introduce c o m m e n t s into the p r o g r a m , you can u s e three different m e t h o d s :

1. T y p e a s e m i c o l o n (;) a n y w h e r e o n a line a n d f o l l o w it w i t h t h e text of t h e

c o m m e n t . For example,

C M P A . L A l , A2 ; A r e t h e p o i n t e r s e q u a l ?

2 . T y p e a n a s t e r i s k (*) in c o l u m n o n e of a line a n d f o l l o w it w i t h t h e text of t h e

comment. For example,

* This entire line is a c o m m e n t

3 . F o l l o w a n y c o m p l e t e i n s t r u c t i o n o r directive w i t h at l e a s t o n e s p a c e a n d
s o m e text. F o r e x a m p l e ,

M O V E Q # I O , D O p l a c e i n i t i a l v a l u e i n DO

In addition, note t h a t all b l a n k l i n e s are treated by the assembler as

c o m m e n t lines.

3.3.2 Executable Instructions

T h e s o u r c e s t a t e m e n t s h a v e t h e g e n e r a l overall f o r m a t :

[<label>] <opcode> [<operand>[,<operand>]...[<comment>]

T o s e p a r a t e e a c h field f r o m t h e n e x t , p r e s s t h e S P A C E B A R or T A B k e y . T h i s
produces a separator character. Y o u m a y use m o r e than one space to separate
fields.

3.3.2.1 Label Field

A label is a u s e r s y m b o l , o r p r o g r a m m e r - d e f i n e d n a m e , t h a t e i t h e r

a) S t a r t s i n t h e first c o l u m n a n d is s e p a r a t e d f r o m t h e n e x t field b y at l e a s t o n e
space, or
b ) S t a r t s in a n y c o l u m n , a n d is f o l l o w e d i m m e d i a t e l y w i t h a c o l o n (:).

If a label is p r e s e n t , t h e n it m u s t b e t h e first n o n b l a n k i t e m o n t h e l i n e . T h e
a s s e m b l e r a s s i g n s t h e v a l u e a n d t y p e of t h e p r o g r a m c o u n t e r , t h a t i s , t h e
m e m o r y a d d r e s s o f t h e first b y t e of t h e i n s t r u c t i o n or d a t a b e i n g r e f e r e n c e d , to
t h e l a b e l . L a b e l s a r e a l l o w e d o n all i n s t r u c t i o n s , a n d o n s o m e d i r e c t i v e s , or
 THE MACRO ASSEMBLER 191

they m a y stand alone o n a line. See the specifications of individual directives in

S e c t i o n 3 . 7 f o r w h e t h e r a l a b e l field is a l l o w e d .
Note: Y o u m u s t not give multiple definitions to labels. Also, y o u m u s t n o t
use instruction n a m e s , macro n a m e s , directives, or register n a m e s as labels.

3.3.2.2 Local Labels

Local labels are provided as an extension to the Motorola specification.
T h e y t a k e t h e f o r m n n n $ a n d are o n l y valid b e t w e e n a n y p r o p e r ( n a m e d ) l a b e l s .
T h u s , in this example code s e g m e n t

Labels Opcodes Operands

FOO: MOVE.L D6,D0
1$: MOVE.B (A0) + ,(A1) +
DBRA D0,1$
MOVEQ #20,D0
BAA: TRAP #4

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 User Manual.

2. Assembler Directives.
3. Macro invocations.

T o enter instructions a n d directives that can operate o n m o r e t h a n o n e data

s i z e , y o u u s e a n o p t i o n a l S i z e - S p e c i f i e r s u b f i e l d , w h i c h is s e p a r a t e d f r o m t h e
o p c o d e b y t h e p e r i o d (.) c h a r a c t e r . P o s s i b l e size s p e c i f i e r s a r e a s f o l l o w s :

B - B y t e - s i z e d d a t a (8 b i t s )
W - W o r d - s i z e d d a t a (16 bits)
L - L o n g W o r d - s i z e d d a t a (32 b i t s )
or L o n g Branch specifier
S - Short B r a n c h specifier

T h e size s p e c i f i e r m u s t m a t c h w i t h t h e i n s t r u c t i o n or d i r e c t i v e t y p e t h a t y o u
use.

3.3.2.4 Operand Field

If p r e s e n t , t h e o p e r a n d field c o n t a i n s o n e or m o r e o p e r a n d s to t h e i n s t r u c -
192 AMIGADOS DEVELOPER'S MANUAL

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 of t h e resulting v a l u e , "x" indicates an error. The
Unary minus and the Logical operators are only valid with an absolute
operand.
 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 , direc-
t 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 .
194 AMIGADOS DEVELOPER'S MANUAL

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. An
e x a m p l e o f t h i s is

'It' 's'
 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: M O V E DO, D l
An A d d r e s s Register Direct
Example: MOVEA A0,A1
(An) Address Register Indirect
Example: M O V E D0,(A1)
(An) + Address Register Indirect Post Increment
Example: M O V E (A7) + , D 0
-(An) Address Register Indirect Pre D e c r e m e n t
Example: M O V E D0,-(A7)
a(An) A d d r e s s Register Indirect with Displacement
Example: M O V E 20(A0),D1
a(An,Xn) 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: M O V E $1000,D0
a L o n g a b s o l u t e (32 bits)
Example: M O V E $10000,D0
r 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 :
 THE MACRO ASSEMBLER 197

Table 3-C: Directives

Assembly Control
Directive Description
SECTION Program section
RORG Relocatable origin
OFFSET Define offsets
END Program end

Symbol 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

Data Definition
Directive Description
DC Define constants
DCB Define Constant Block
DS Define storage

Listing 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 < = n < = 132)
PLEN n S e t p a g e l e n g t h (24 < = n < = 100)
TTL S e t p r o g r a m title ( m a x 4 0 c h a r s . )
NOOBJ Disable object code output
FAIL Generate an assembly error
FORMAT N o action
NOFORMAT N o action

Conditional Assembly
Directive Description
CNOP C o n d i t i o n a l N O P for a l i g n m e n t
IFEQ A s s e m b l e if e x p r e s s i o n is 0
IFNE A s s e m b l e if e x p r e s s i o n is n o t 0
IFGT A s s e m b l e if e x p r e s s i o n > 0
198 AMIGADOS DEVELOPER'S MANUAL

Directive Description
IFGE A s s e m b l e if e x p r e s s i o n > = 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
IFC A s s e m b l e if s t r i n g s a r e i d e n t i c a l
IFNC A s s e m b l e if s t r i n g s are n o t i d e n t i c a l
IFD A s s e m b l e if s y m b o l is d e f i n e d
IFND A s s e m b l e if s y m b o l is n o t d e f i n e d
ENDC E n d of conditional a s s e m b l y

Macro Directives
Directive Description
MACRO Define a macro name
NARG Special symbol
ENDM E n d of macro definition
MEXIT Exit t h e m a c r o e x p a n s i o n

External Symbols
Directive Description
XDEF Define external n a m e
XREF Reference external n a m e

General Directives
Directive Description
INCLUDE I n s e r t file in t h e s o u r c e
MASK2 N o action
IDNT N a m e program unit

Assembly Control Directives

SECTION Program Section
Format: [<label>] SECTION <name>[,<type>]
T h i s d i r e c t i v e tells t h e a s s e m b l e r to r e s t o r e t h e c o u n t e r t o t h e last l o c a t i o n
a l l o c a t e d i n t h e n a m e d s e c t i o n (or t o z e r o if u s e d f o r t h e first t i m e ) .

< n a m e > is a c h a r a c t e r s t r i n g o p t i o n a l l y e n c l o s e d in d o u b l e q u o t e s .
< t y p e > if i n c l u d e d , m u s t b e o n e o f t h e f o l l o w i n g k e y w o r d s :

CODE indicates that the section contains relocatable code. This is the
default.
DATA Indicates that the section contains initialized data (only).
BSS indicates that the section contains uninitialized data.
 THE MACRO ASSEMBLER 199

The assembler c a n m a i n t a i n u p to 2 5 5 s e c t i o n s . Initially, t h e assembler

begins with an u n n a m e d C O D E section. T h e assembler assigns the optional
s y m b o l < l a b e l s > t o t h e v a l u e o f t h e p r o g r a m c o u n t e r a f t e r it h a s e x e c u t e d t h e
S E C T I O N d i r e c t i v e . I n a d d i t i o n , w h e r e a s e c t i o n is u n n a m e d , t h e s h o r t h a n d
f o r t h a t s e c t i o n is t h e k e y w o r d C O D E .

RORG Set Relative Origin

Format: [<label>] RORG <absexp>
T h e R O R G d i r e c t i v e c h a n g e s t h e p r o g r a m c o u n t e r to b e < a b s e x p > bytes
f r o m t h e start o f t h e c u r r e n t r e l o c a t a b l e s e c t i o n . T h e a s s e m b l e r a s s i g n s r e l o c a t a b l e
m e m o r y l o c a t i o n s to s u b s e q u e n t s t a t e m e n t s , s t a r t i n g w i t h t h e v a l u e a s s i g n e d
to t h e p r o g r a m c o u n t e r . T o d o a d d r e s s i n g in r e l o c a t a b l e s e c t i o n s , y o u u s e t h e
" p r o g r a m c o u n t e r relative with d i s p l a c e m e n t " addressing m o d e . T h e label value
a s s i g n m e n t is t h e s a m e a s for S E C T I O N .

OFFSET Define offsets

Format: OFFSET <absexp>
T o d e f i n e a t a b l e o f o f f s e t s via t h e D S d i r e c t i v e b e g i n n i n g at t h e a d d r e s s
< a b s e x p > , y o u u s e the O F F S E T directive. Symbols defined in a n O F F S E T table
a r e k e p t i n t e r n a l l y , b u t n o c o d e - p r o d u c i n g i n s t r u c t i o n s or d i r e c t i v e s may
appear. To terminate an O F F S E T section, y o u use a R O R G , O F F S E T , SEC-
T I O N , or E N D d i r e c t i v e .

END E n d of p r o g r a m
Format: [<label>] END
T h e E N D d i r e c t i v e tells t h e a s s e m b l e r t h a t t h e s o u r c e is f i n i s h e d , a n d t h e
assembler ignores subsequent source statements. W h e n the assembler en-
c o u n t e r s t h e E N D d i r e c t i v e d u r i n g t h e first p a s s , it b e g i n s t h e s e c o n d p a s s . If,
h o w e v e r , it d e t e c t s a n e n d - o f - f i l e b e f o r e a n E N D d i r e c t i v e , it g i v e s a w a r n i n g
m e s s a g e . If t h e l a b e l field is p r e s e n t , t h e n t h e a s s e m b l e r a s s i g n s t h e v a l u e
of t h e current program c o u n t e r to t h e l a b e l b e f o r e it e x e c u t e s the END
directive.

Symbol Definition Directives

EQU Equate symbol value
Format: <label> EQU <exp>
T h e E Q U d i r e c t i v e a s s i g n s t h e v a l u e o f t h e e x p r e s s i o n in t h e o p e r a n d field t o
t h e s y m b o l in t h e l a b e l field. T h e v a l u e a s s i g n e d is p e r m a n e n t , s o y o u m a y n o t
d e f i n e t h e l a b e l a n y w h e r e e l s e in t h e p r o g r a m .
Note: D o not insert forward references within the expression.
200 AMIGADOS DEVELOPER'S MANUAL

EQUR Equate register value

Format: <label> EQUR <register>
This directive lets y o u equate o n e of the processor registers w i t h a u s e r
s y m b o l . O n l y t h e A d d r e s s a n d D a t a r e g i s t e r s a r e v a l i d , s o s p e c i a l s y m b o l s like
S R , C C R , a n d U S P a r e illegal h e r e . T h e r e g i s t e r is p e r m a n e n t , s o y o u c a n n o t
define t h e label a n y w h e r e else in the program. T h e register m u s t n o t b e a
f o r w a r d r e f e r e n c e to a n o t h e r E Q U R s t a t e m e n t . T h e a s s e m b l e r m a t c h e s l a b e l s
d e f i n e d in t h i s w a y w i t h o u t d i s t i n g u i s h i n g b e t w e e n u p p e r a n d l o w e r c a s e .

REG D e f i n e r e g i s t e r list
Format: <label>REG<register list>
T h e R E G d i r e c t i v e a s s i g n s a v a l u e to label t h a t t h e a s s e m b l e r c a n t r a n s l a t e
i n t o t h e r e g i s t e r list m a s k f o r m a t u s e d i n t h e M O V E M i n s t r u c t i o n . <register
l i s t > is o f t h e f o r m

R l [-R2][/R3[-R4]]. . .

SET Set symbol value

Format: < l a b e l > SET <exp>
T h e S E T d i r e c t i v e a s s i g n s t h e v a l u e of t h e e x p r e s s i o n i n t h e o p e r a n d field to
t h e s y m b o l in t h e l a b e l field. S E T is i d e n t i c a l t o E Q U , a p a r t f r o m t h e fact t h a t
t h e a s s i g n m e n t is t e m p o r a r y . Y o u c a n a l w a y s c h a n g e S E T l a t e r o n i n the
program.
Note: You should not insert forward references within the expression or
r e f e r f o r w a r d to s y m b o l s t h a t y o u d e f i n e d w i t h S E T .

Data Definition Directives

DC Define Constant
Format: [<label>] DC[.<size>] <list>
T h e D C d i r e c t i v e d e f i n e s a c o n s t a n t v a l u e in m e m o r y . It m a y h a v e any
n u m b e r o f o p e r a n d s , s e p a r a t e d b y c o m m a s (,). T h e v a l u e s i n t h e list m u s t b e
c a p a b l e o f b e i n g h e l d in t h e d a t a l o c a t i o n w h o s e size is g i v e n b y t h e size
s p e c i f i e r o n t h e d i r e c t i v e . If y o u d o n o t g i v e a size s p e c i f i e r , D C a s s u m e s it is
. W . If t h e size is . B , t h e n t h e r e is o n e o t h e r d a t a t y p e t h a t c a n b e u s e d : t h a t o f
t h e A S C I I s t r i n g . T h i s is a n arbitrarily l o n g s e r i e s o f A S C I I c h a r a c t e r s , con-
t a i n e d w i t h i n q u o t a t i o n m a r k s . A s w i t h A S C I I literals, if y o u r e q u i r e a q u o t a t i o n
m a r k i n t h e s t r i n g , t h e n y o u m u s t e n t e r t w o . If t h e size is . W or . L , t h e n t h e
a s s e m b l e r aligns the data onto a w o r d b o u n d a r y .

DCB Define Constant Block

Format: [<label>] DCB[.<size>] <absexp>,<exp>
Y o u u s e t h e D C B d i r e c t i v e to s e t a n u m b e r ( g i v e n b y < a b s e x p > ) o f b y t e s ,
 THE MACRO ASSEMBLER 201

w o r d s , o r l o n g w o r d s to t h e v a l u e o f t h e e x p r e s s i o n < e x p > . D C B . < s i z e > n , e x p

is e q u i v a l e n t t o r e p e a t i n g n t i m e s t h e s t a t e m e n t D C . < s i z e > e x p .

DS Define Storage
Format: [<label>] DS[.<size>] <absexp>
T o reserve m e m o r y locations, y o u u s e the D S directive. D S , h o w e v e r , does
n o initialization. T h e a m o u n t of space the a s s e m b l e r allocates d e p e n d s o n t h e
d a t a s i z e ( t h a t y o u g i v e w i t h t h e size s p e c i f i e r o n t h e d i r e c t i v e ) , a n d t h e v a l u e
o f t h e e x p r e s s i o n in t h e o p e r a n d f i e l d . T h e a s s e m b l e r i n t e r p r e t s t h i s a s t h e
n u m b e r o f d a t a i t e m s o f t h a t s i z e to a l l o c a t e . A s w i t h D C , if t h e size s p e c i f i e r is
. W or .L, D S aligns the space onto a w o r d boundary. S o , D S . W 0 has the effect
o f a l i g n i n g t o a w o r d b o u n d a r y o n l y . If y o u d o n o t g i v e a s i z e s p e c i f i e r , D S
a s s u m e s a default of . W . S e e C N O P for a m o r e general w a y of handling
alignment.

Listing Control Directives

PAGE Page Throw
Format: 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 T u r n off L i s t i n g
Format: NOLIST
NOL
T h e N O L I S T o r N O L d i r e c t i v e t u r n s off t h e p r o d u c t i o n o f t h e assembly
l i s t i n g file. L i s t i n g c e a s e s u n t i l t h e a s s e m b l e r e n c o u n t e r s e i t h e r a n E N D o r a
LIST directive. T h e N O L I S T directive d o e s not a p p e a r o n the p r o g r a m listing.

SPC Space Blank Lines

Format: SPC <number>
T h e S P C directive outputs t h e n u m b e r of blank lines given b y the o p e r a n d
field, to the a s s e m b l y listing. T h e S P C directive d o e s not a p p e a r o n the
p r o g r a m listing.
202 AMIGADOS DEVELOPER'S MANUAL

NOPAGE T u r n off P a g i n g
Format: NOPAGE
The NOPAGE d i r e c t i v e t u r n s off t h e p r i n t i n g o f p a g e t h r o w s a n d title
h e a d e r s o n the a s s e m b l y listing.

LLEN Set Line Length

Format: LLEN <number>
T h e L L E N d i r e c t i v e s e t s t h e l i n e l e n g t h o f t h e a s s e m b l y l i s t i n g file t o t h e
v a l u e y o u s p e c i f i e d i n t h e o p e r a n d f i e l d . T h e v a l u e m u s t lie b e t w e e n 6 0 a n d
1 3 2 , a n d c a n o n l y b e set o n c e in t h e p r o g r a m . T h e L L E N d i r e c t i v e d o e s n o t
a p p e a r o n t h e a s s e m b l y listing. T h e d e f a u l t is 1 3 2 c h a r a c t e r s .

PLEAT Set Page Length

Format: PLEN <number>
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 <title string>
T h e T T L d i r e c t i v e s e t s t h e title o f t h e p r o g r a m to t h e s t r i n g y o u g a v e i n t h e
o p e r a n d f i e l d . T h i s s t r i n g a p p e a r s a s t h e p a g e h e a d i n g in t h e a s s e m b l y l i s t i n g .
T h e s t r i n g s t a r t s at t h e first n o n b l a n k c h a r a c t e r a f t e r t h e T T L , a n d c o n t i n u e s
u n t i l t h e e n d o f l i n e . It m u s t n o t b e l o n g e r t h a n 4 0 c h a r a c t e r s i n l e n g t h . T h e
T T L directive d o e s not appear o n the p r o g r a m listing.

NOOBJ Disable Object C o d e Generation

Format: NOOBJ
T h e N O O B J d i r e c t i v e d i s a b l e s t h e p r o d u c t i o n of t h e o b j e c t c o d e file a t t h e
e n d o f a s s e m b l y . T h i s d i r e c t i v e d i s a b l e s t h e p r o d u c t i o n o f t h e c o d e file, e v e n if
y o u specified a filename w h e n y o u called the assembler.

FAIL G e n e r a t e a user error

Format: FAIL
The FAIL directive tells t h e a s s e m b l e r to f l a g a n e r r o r f o r t h i s input
line.

FORMAT N o action
Format: FORMAT
T h e a s s e m b l e r a c c e p t s t h i s d i r e c t i v e b u t t a k e s n o a c t i o n o n r e c e i v i n g it.
F O R M A T is i n c l u d e d f o r c o m p a t i b i l i t y w i t h o t h e r a s s e m b l e r s .
 THE MACRO ASSEMBLER 203

NOFORMAT N o action
Format: NOFORMAT
T h e a s s e m b l e r accepts this directive b u t takes n o action o n receiving it.
N O F O R M A T is i n c l u d e d for c o m p a t i b i l i t y w i t h o t h e r a s s e m b l e r s .

Conditional Assembly Directives

CNOP Conditional N O P
Format: [<label>] CNOP <number>,<number>
T h i s d i r e c t i v e is a n e x t e n s i o n f r o m t h e M o t o r o l a s t a n d a r d a n d a l l o w s a
s e c t i o n o f c o d e to b e a l i g n e d o n a n y b o u n d a r y . I n p a r t i c u l a r , it a l l o w s a n y d a t a
s t r u c t u r e or e n t r y p o i n t to b e a l i g n e d to a l o n g w o r d b o u n d a r y .
T h e first e x p r e s s i o n r e p r e s e n t s a n o f f s e t , w h i l e t h e s e c o n d e x p r e s s i o n r e p r e -
s e n t s t h e a l i g n m e n t r e q u i r e d for t h e b a s e . T h e c o d e is a l i g n e d to t h e s p e c i f i e d
offset from the nearest required alignment b o u n d a r y . T h u s

C N O P 0,4

aligns code to the next long word boundary while

C N O P 2,4

a l i g n s c o d e to t h e w o r d b o u n d a r y 2 b y t e s b e y o n d t h e n e a r e s t l o n g word
aligned boundary.

IFEQ A s s e m b l e if e x p r e s s i o n = 0
IFNE A s s e m b l e if e x p r e s s i o n < > 0
IFGT A s s e m b l e if e x p r e s s i o n > 0
IFGE A s s e m b l e if e x p r e s s i o n > = 0
IFLT A s s e m b l e if e x p r e s s i o n < 0
IFLE A s s e m b l e if e x p r e s s i o n < = 0
Format: IFxx <absexp>
Y o u u s e t h e I F x x r a n g e of d i r e c t i v e s to e n a b l e or d i s a b l e a s s e m b l y , d e p e n d -
i n g o n t h e v a l u e o f t h e e x p r e s s i o n in t h e o p e r a n d f i e l d . If t h e c o n d i t i o n is n o t
T R U E (for e x a m p l e , I F E Q 2 + 1 ) , a s s e m b l y c e a s e s ( t h a t i s , it is d i s a b l e d ) . T h e
conditional a s s e m b l y switch remains active until the assembler finds a match-
ing 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 Assemble if s t r i n g s a r e i d e n t i c a l
IFNC Assemble if s t r i n g s a r e n o t i d e n t i c a l
Format: IFC <string>,<string>
IFNC <string>,<string>
T h e strings m u s t 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 E n d conditional assembly

Format: ENDC
T o t e r m i n a t e a c o n d i t i o n a l a s s e m b l y , y o u u s e t h e E N D C d i r e c t i v e , set u p
with a n y of the 8 IFxx directives above. E N D C m a t c h e s the m o s t recently
e n c o u n t e r e d condition directive.

Macro Directives
MACRO Start a macro definition
Format: <label> MACRO
M A C R O introduces a macro definition. E N D M terminates a macro defini-
tion. 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
 THE MACRO ASSEMBLER 205

is a limit t o t h e l e v e l o f n e s t i n g o f m a c r o calls. T h i s limit is c u r r e n t l y set

at t e n .
M a c r o e x p a n s i o n stops w h e n the assembler e n c o u n t e r s the e n d of t h e stored
m a c r o t e x t , o r w h e n it f i n d s a M E X I T d i r e c t i v e .

NARG Special symbol

Format: NARG
T h e s y m b o l N A R G is a s p e c i a l r e s e r v e d s y m b o l a n d t h e a s s e m b l e r a s s i g n s it
t h e i n d e x o f t h e last a r g u m e n t p a s s e d t o t h e m a c r o in t h e p a r a m e t e r list ( e v e n
nulls). O u t s i d e of a macro expansion, N A R G h a s the value 0.

ENDM Terminate a macro definition

Format: ENDM
This terminates a macro definition introduced by a M A C R O directive.

MEXIT Exit f r o m m a c r o e x p a n s i o n
Format: MEXIT
Y o u u s e this directive to exit f r o m m a c r o e x p a n s i o n m o d e , u s u a l l y i n conduction
w i t h t h e I F E Q a n d I F N E d i r e c t i v e s . It a l l o w s c o n d i t i o n a l e x p a n s i o n o f m a c r o s .
O n c e it h a s e x e c u t e d t h e d i r e c t i v e , t h e a s s e m b l e r s t o p s e x p a n d i n g t h e c u r r e n t
m a c r o as t h o u g h there w e r e no m o r e stored text to include.

External Symbols
XDEF Define an internal label as an external entry
point
Format: XDEF <label>[,<label>...]
O n e o r m o r e a b s o l u t e or r e l o c a t a b l e l a b e l s m a y f o l l o w t h e X D E F d i r e c t i v e .
Each label defined here generates an external symbol definition. You can
make references to t h e s y m b o l in other m o d u l e s (possibly from a high-
level language) and satisfy the references w i t h a linker. If y o u 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 <label>[,<label>...]
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 the
program follow the X R E F directive. Subsequent u s e s of t h e l a b e l tell the
a s s e m b l e r t o g e n e r a t e a n e x t e r n a l r e f e r e n c e for t h a t l a b e l . Y o u u s e t h e l a b e l a s
if it r e f e r r e d to a n a b s o l u t e or r e l o c a t a b l e v a l u e d e p e n d i n g o n w h e t h e r the
m a t c h i n g X D E F r e f e r r e d t o a n a b s o l u t e or r e l o c a t a b l e s y m b o l .
T h e a c t u a l v a l u e u s e d is filled in f r o m a n o t h e r m o d u l e b y t h e l i n k e r . T h e
206 AMIGADOS DEVELOPER'S MANUAL

l i n k e r a l s o g e n e r a t e s a n y r e l o c a t i o n i n f o r m a t i o n t h a t m a y b e r e q u i r e d in o r d e r
for the resulting code to b e relocatable.
E x t e r n a l s y m b o l s a r e n o r m a l l y u s e d a s f o l l o w s . T o s p e c i f y a r o u t i n e in o n e
p r o g r a m s e g m e n t as a n e x t e r n a l d e f i n i t i o n , y o u p l a c e a label at t h e start o f t h e
r o u t i n e a n d q u o t e t h e label after a n X D E F d i r e c t i v e . A n o t h e r p r o g r a m m a y call
t h a t r o u t i n e if it d e c l a r e s a label via t h e X R E F d i r e c t i v e a n d t h e n j u m p s to t h e
label so declared.

General Directives
INCLUDE I n s e r t a n e x t e r n a l file
Format: INCLUDE "<file n a m e > "
T h e I N C L U D E d i r e c t i v e a l l o w s t h e i n c l u s i o n o f e x t e r n a l files i n t o t h e p r o -
g r a m s o u r c e . Y o u set u p t h e file t h a t I N C L U D E i n s e r t s w i t h t h e s t r i n g d e s c r i p -
t o r in t h e o p e r a n d f i e l d . Y o u c a n n e s t I N C L U D E d i r e c t i v e s u p t o a d e p t h o f
t h r e e , e n c l o s i n g t h e f i l e n a m e s in q u o t e s as s h o w n . I N C L U D E is e s p e c i a l l y
u s e f u l w h e n y o u r e q u i r e a s t a n d a r d s e t o f m a c r o d e f i n i t i o n s or E Q U s i n s e v e r a l
programs.
Y o u c a n p l a c e t h e d e f i n i t i o n s in a s i n g l e file a n d t h e n r e f e r to t h e m f r o m
other programs with a suitable I N C L U D E . It is o f t e n c o n v e n i e n t t o place
N O L I S T a n d L I S T d i r e c t i v e s at t h e h e a d a n d tail o f files y o u i n t e n d t o i n c l u d e
via I N C L U D E . A m i g a D O S s e a r c h e s f o r t h e file s p e c i f i c a t i o n first i n t h e c u r r e n t
d i r e c t o r y , t h e n in e a c h s u b s e q u e n t d i r e c t o r y in t h e list y o u g a v e in t h e -i
option.

MASK2 N o action
Format: MASK2
T h e a s s e m b l e r a c c e p t s t h e M A S K 2 d i r e c t i v e , b u t it t a k e s n o a c t i o n o n r e c e i v -
i n g it.

IDNT N a m e program unit

Format: IDNT <string>
A p r o g r a m u n i t , w h i c h c o n s i s t s o f o n e or m o r e s e c t i o n s , m u s t h a v e a n a m e .
U s i n g t h e I D N T directive, y o u can define a n a m e consisting of a string option-
ally 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 automati-
cally. 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 . A
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 , 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 supervi-
sor 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 supervisor in the output file p r o d u c e d from
a link using overlays. T h e 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 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 .
214 AMIGADOS DEVELOPER'S MANUAL

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

OVERLAY ROOT
a 1
b 1 a b c
c 1
#

OVERLAY ROOT
a 1
b 1 a b
*c 2
*d 2 c d
#
OVERLAY ROOT
a 1 1
b 1 2
*c 2 1 ab e f 1
*d 2 2
e 1 3 c d ghk
f 1 4

*g 2 1 A
*h 2 2
**i 3 1
**j 3 2
*k 2 3
1 1 5
#
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.
216 AMIGADOS DEVELOPER'S MANUAL

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
/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 not
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.
 THE LINKER 217

T h e linker gives each symbol that has an overlay reference an overlay

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 the overlay
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 of the form
" 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 use symbols
with this format elsewhere.
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 se-
q 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 char-
a 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.
220 AMIGADOS DEVELOPER'S MANUAL

tiK 0 0 0 r1 n 0 3 3 1 1 1 1 1 1 1 1
b?

b(,
0
0
0
0 1t 0
1 0
t
0
1
1
1
1
0
0
0
0
0
1
0
1
1
0
1
0
1
1
1
1

p
„ 0 1 0 1 0 1 0 1 0 1 1 0 1 0 1
00 01 02 0 3 0 4 0 5 06 0 7 08 09 1 0 11 12 13 14 1.5
bl
o
0 0 0 0 00 SP 0 a P •
P NBSP A €> a b

+ A
#
1 1 A Q a q i N n
0 0 0 1 01 a
0 0 1 0 02
II
2 B R b r
2
A 0 a ^
0

£
t
0 0 1 1 03 # 3 c S c s
3
A 0 a 0

0 1 0 0 04 $ 4 D T d t :
r
A" 0 a 0

0 1 0 1 05 % 5 E U e u S 6 § 6
0 1 1 0 06 & 6 F V f V k b' EE 6
0 1 1 1 07
1
7 G w g w §
•
? o ? • '

1 0 0 0 08 ( 8 H X h X
t E 0
1 «
1 0 0 1 09 ) 9 I Y i y © E U
u*
•.WW.*

* • £
1 0 1 0 10 •
J Z J z E § u

+ u
0
C k
«» e
1 0 1 1 11 K { E u

1 1 0 0 12 < L \ I 1 I u u
1 1 0 1 13 - = M : m > SHY * Y * *
I l y
> \ ?
mm
1 1 1 0 14 • N n ® I i

-
M M

/ i 0 i y
1 1 1 1 15 0
I 1

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
1 column
I 09 TAB TAB M o v e right 1 c o l u m n
J OA LF LINE FEED
K OB VT VERTICAL TAB 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 OC FF FORM FEED Clear the screen
M 0D CR 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 SI SHIFT IN Undo SHIFT O U T
[ IB 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 > or press C T R L - A L T a n d the

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 Chr Name Definition

845tD IND INDEX: m o v e the active position d o w n o n e line
85 E NEL NEXT LINE:
8D M RI REVERSE INDEX:
9B [ CSI 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 AMIGADOS DEVELOPER'S MANUAL

"0" indicates no parameters allowed.

"1" indicates 0 or 1 numeric parameters.
"2" indicates 2 numeric parameters ("14;94").
"3" indicates any n u m b e r of numeric parameters, separated by semicolons.
"4" indicates exactly 4 numeric parameters.
"8" indicates exactly 8 numeric parameters.

< C S I > Name Definition

1 @ ICH 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.
1 A cuu CURSOR UP
1 B CUD CURSOR DOWN
1 C CUF CURSOR FORWARD
1 D CUB CURSOR BACKWARD
1 E CNL CURSOR NEXT LINE D o w n n lines to c o l u m n 1
1 F CPL C U R S O R PRECEDING LINE U p n l i n e s to c o l u m n 1
2 H CUP CURSOR POSITION "<CSI>row;columnH"
1J ED ERASE IN DISPLAY ( o n l y t o e n d of d i s p l a y )
1 K EL ERASE IN LINE (only to eol)
1 L IL INSERT LINE 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.
1 M DL DELETE LINE 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.
1 P DCH DELETE CHARACTER
2 R CPR C U R S O R P O S I T I O N R E P O R T (in R e a d s t r e a m o n l y )
F o r m a t of r e p o r t :
"<CSI>row;columnR"
1 S SU SCROLL UP R e m o v e s line f r o m t o p of s c r e e n .
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 .
1 T SD SCROLL DOWN R e m o v e s line from b o t t o m of
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.
3h SM SET M O D E < C S I > 2 0 h causes R A W :
t o c o n v e r t < L F > to
< n e w l i n e > on output.
3 1 RM RESET M O D E < C S I > 2 0 1 undoes SET M O D E 20
3 m SGR SELECT GRAPHIC RENDITION
1 n DSR DEVICE STATUS REPORT
 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 aSTO SET TOP OFFSET
3 { aSRE SET R A W EVENTS
8 I a l E R I N P U T E V E N T R E P O R T (read)
3 } aRRE RESET R A W EVENTS
1 ' a S K R S P E C I A L K E Y R E P O R T (read)
IP aSCR SET CURSOR RENDITION
< E s c > p t u r n s t h e c u r s o r off
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)

Examples:
M o v e c u r s o r r i g h t b y 1:

< C S I > C or < T a b > or < C S I > 1 C

M o v e cursor right by 20:

<CSI>20C

M o v e c u r s o r to u p p e r left c o r n e r ( h o m e ) :

< C S I > H or < C S I > 1 ; 1 H or < C S I > ; 1 H or < C S I > 1 ; H

M o v e c u r s o r to t h e f o u r t h c o l u m n o f t h e first l i n e o f t h e w i n d o w :

< C S I > 1 ; 4 H or <CSI>;4H

Clear the screen:

< F F > or C T R L - L {clear s c r e e n c h a r a c t e r } o r

<CSI>H<CSI>J { h o m e a n d clear to e n d of screen} or
<CSI>H<CSI>23M { h o m e a n d delete 23 lines} or
<CSI>1;1H<CSI>23L { h o m e and insert 23 lines}
224 AMIGADOS DEVELOPER'S MANUAL

RAW Keyboard Input

Reading input from the R A W : console device returns an A N S I X3.64
standard byte stream. This stream may contain normal characters and/or R A W
input event information. Y o u m a y also request other R A W input events
using the SET R A W E V E N T S (aSRE) and RESET R A W E V E N T S (aRRE) con-
trol 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 se-
q 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 Unshifted Sends Shifted Sends

Fl <CSI>0' CSI>10"
F2 <csi>r <csi>ir
F3 <CSI>2~ <CSI>12'
F4 <CSI>3 _
<CSI>13"
F5 <CSI>4' <CSI>14 _

F6 <CSI>5" <CSI>15"
F7 <CSI>6" <CSI>16"
F8 <CSI>7' <CSI>17'
F9 <CSI>8~ <CSI>18~
F10 <CSI>9' <CSI>19'
HELP <CSI>?' < C S I > ? ' (same)

Arrow keys:

Up <CSI>A <CSI>T'
Down <CSI>B <CSI>S'
Left <CSI>C < C S I > A " (note space)
Right <CSI>D < 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 Used internally.
1 R A W keyboard input
2 R A W mouse input
3 Event S e n t w h e n e v e r y o u r w i n d o w is
m a d e active.
4 Pointer position
5 (unused)
6 Timer
7 Gadget pressed
8 Gadget released
9 R e q u e s t e r activity
10 Menu numbers
11 Close Gadget
12 W i n d o w resized
13 Window refreshed
14 Preferences changed
15 Disk removed
16 Disk inserted

If y o u s e l e c t a n y o f t h e s e e v e n t s , y o u start to g e t i n f o r m a t i o n a b o u t the
events in the following form:

<CSIXclass>
< subclass >
<keycode>
<qualifiers>
<x>
<y>
<seconds>
<microseconds >

< C S I > is a o n e b y t e f i e l d . It is t h e C o n t r o l S e q u e n c e I n t r o d u c e r , 9 B h e x .
< c l a s s > is t h e R A W i n p u t e v e n t t y p e , f r o m t h e a b o v e t a b l e .
< s u b c l a s s > is n o t c u r r e n t l y u s e d a n d is a l w a y s z e r o ( 0 ) .
< k e y c o d e > indicates w h i c h key n u m b e r w a s pressed (see Figure A - l and
Table A-2). This field can also b e u s e d for m o u s e information.
T h e < q u a l i f i e r s > field i n d i c a t e s t h e s t a t e o f t h e k e y b o a r d a n d s y s t e m . T h e
q u a l i f i e r s a r e d e f i n e d as f o l l o w s :
226 AMIGADOS DEVELOPER'S M A N U A L

Bit Mask Key

0 0001 left shift
1 0002 r i g h t shift
2 0004 caps lock * special, see b e l o w
3 0008 control
4 0010 left alt
5 0020 r i g h t alt
6 0040 left A m i g a k e y p r e s s e d
7 0080 right Amiga k e y pressed
8 0100 numeric pad
9 0200 repeat
10 0400 interrupt Not currently used
11 0800 multi broadcast T h i s (active) or all w i n d o w s
12 1000 left m o u s e b u t t o n
13 2000 right m o u s e button
14 4000 middle mouse button
( n o t available o n s t d m o u s e )
15 8000 relative m o u s e 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, selected keys no longer return a simple 1
c h a r a c t e r "A" to " Z " b u t r a t h e r r e t u r n r a w k e y c o d e r e p o r t s w i t h t h e f o l l o w i n g
form:

<CSI>l;0;<keycode>;<qualifiers>;0;0;<secs>;<microsecs>|

F o r e x a m p l e , if t h e u s e r p r e s s e d a n d r e l e a s e d t h e " B " k e y w i t h t h e left

S H I F T a n d r i g h t A m i g a k e y s also p r e s s e d , y o u m i g h t r e c e i v e t h e f o l l o w i n g
data:

<CSI>1;0;35;129;0;0;23987;99|
< C S I > 1 ;0; 1 6 3 ; 1 2 9 ; 0 ; 0 ; 2 4 0 0 3 ; 18|
 APPENDIX: CONSOLE INPUT AND OUTPUT ON THE AMIGA 227

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 F1 F3 F3 F« FS F7 F10 DEL

45 50 51 52 53 54 55 56 57 58 59 46
? i K
» 1 i i
SACK
SPACE
7 9

bo 01 0 2W 03 0 4 05 06 '08 OA 0B OC 0D 41 30 3E 3F
07 9
T*| 0 E It
T V t 0 90 P
! i
HELP 4 S

42 10 11 12 13 16 17 18 1 9 1/1 1 B 4 4 5 F 2D 2E 2F
1 4 1H 5
CTHL CAtt
LOCK
A S O F
c J K L IF) I T UA N %
1
a 3

63 2 0 21 22
62 2 3 24 25 26 27 28 29 2 A | 2E3 4C 1D I E 1F
• ft
SHIFT
z C V M 0

60 30 31 3 2 3 3 34 35 36 37 38 39 3A 61 4F 4E OF 3C
ALT
A A. « INTiFl

64 66 40 67 65 4D 4A 43

Figure A-l: Reduced copy of keyboard template

228 AMIGADOS DEVELOPER'S MANUAL

T h e d e f a u l t v a l u e s g i v e n in t h e f o l l o w i n g c o r r e s p o n d t o :

1) T h e v a l u e s t h e C O N : d e v i c e r e t u r n s w h e n t h e s e k e y s a r e p r e s s e d , a n d
2) T h e keycaps as shipped with the standard American keyboard.

Table A - 2 : Converting from Keycodes to Keys

Raw Unshifted Shifted

Key Default Default
Number Value Value

00 '<Accent grave> " <tilde>

01 1 !
02 2 @
03 3 #
04 4 $
05 5 %
06 6
07 7 &
08 8 *
09 9 (
OA 0 )
0B - <Hyphen> <Underscore>
0C +
0D \ |
0E undefined
OF 0 0 <Numeric pad>
10 Q q
11 W w
12 E e
13 R r
14 T t
15 Y y
16 U u
17 I i
18 O o
19 P p
1A { [
IB } ]
1C undefined
ID 1 1 <Numeric pad>
IE 2 2 <Numeric pad>
IF 3 3 <Numeric pad>
 APPENDIX: CONSOLE INPUT AND OUTPUT ON THE AMIGA 229

Raw Unshifted Shifted

Key Default Default
Number Value Value

20 A a
21 S s
22 D d
23 F f
24 G g
25 H h
26 J j
27 K k
28 L 1
29
2A ' < single quote >
2B <RESERVED> (RESERVED)
2C undefined
2D 4 4 <Numeric pad>
2E 5 5 <Numeric pad>
2F 6 6 <Numeric pad>
30 <RESERVED> (RESERVED)
31 Z z
32 X x
33 c c
34 V V
35 B b
36 N n
37 M m
38 < , <comma>
39 > . < period >
3A ? /
3B undefined
3C . <Numeric pad>
3D 7 7 <Numeric pad>
3E 8 8 <Numeric pad>
3F 9 9 <Numeric pad>
40 Space
41 BACKSPACE
42 TAB
43 ENTER ENTER <Numeric p a d >
44 RETURN
45 Escape <Esc>
46 DEL
230 AMIGADOS DEVELOPER'S M A N U A L

Raw Unshifted Shifted

Key Default Default
Number Value Value

47 undefined
48 undefined
49 undefined
4A - - <Numeric pad>
4B undefined
4C Cursor Up Scroll d o w n
4D Cursor D o w n Scroll u p
4E Cursor Forward Scroll left
4F Cursor Backward Scroll r i g h t
50 Fl <CSI>10~
51 F2 <csi>ir
52 F3 <CSI>12'
53 F4 <CSI>13~
54 F5 <CSI>14'
55 F6 <CSI>15'
56 F7 <CSI>16"
57 F8 <CSI>17~
58 F9 <CSI>18"
59 F10 <CSI>19"
5A undefined
5B undefined
5C undefined
5D undefined
5E undefined
5F Help
60 SHIFT < l e f t of space b a r >
61 S H I F T < r i g h t of s p a c e b a r >
62 Caps Lock
63 Control
64 Left Alt
65 Right Alt
66 " A m i g a " < l e f t of space b a r >
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 231

Raw Unshifted Shifted

Key Default Default
Number Value Value

6A Middle Mouse Button

< n o t converted> 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. <not
converted>

Notes about the preceding table:

1) " u n d e f i n e d " i n d i c a t e s t h a t t h e c u r r e n t k e y b o a r d d e s i g n s h o u l d n o t g e n e r -
a t e t h i s n u m b e r . If y o u a r e u s i n g " S e t K e y M a p " t o c h a n g e t h e k e y m a p , t h e
e n t r i e s f o r t h e s e n u m b e r s m u s t still b e i n c l u d e d .
2) T h e " < n o t c o n v e r t e d > " r e f e r s t o m o u s e b u t t o n e v e n t s . Y o u m u s t u s e t h e
s e q u e n c e " < C S I > 2 { " to inform the console driver that y o u w i s h to receive
m o u s e events; otherwise, these are not transmitted.
3) " ( R E S E R V E D ) " i n d i c a t e s t h a t t h e s e k e y c o d e s h a v e b e e n r e s e r v e d f o r n o n - U . S .
k e y b o a r d s . T h e " 2 B " c o d e k e y is b e t w e e n t h e d o u b l e q u o t e a n d r e t u r n k e y s .
T h e " 3 0 " c o d e k e y is b e t w e e n t h e S H I F T a n d " Z " k e y s .
 AmigaDOS Technical
Reference Manual
Contents

1. Filing System
2. Amiga Binary File Structure
3. AmigaDOS Data Structures
Chapter 1
The Filing System

T h i s c h a p t e r d e s c r i b e s t h e A m i g a D O S filing s y s t e m . It i n c l u d e s i n f o r m a t i o n o n
h o w to patch a disk corrupted b y hardware errors.

1.1 A m i g a D O S File S t r u c t u r e
1.1.1 Root Block
1.1.2 User Directory Blocks
1.1.3 File H e a d e r B l o c k
1.1.4 File List B l o c k
1.1.5 Data Block
1.2 D I S K E D — T h e Disk Editor

1.1 AmigaDOS File Structure

T h e A m i g a D O S file h a n d l e r u s e s a d i s k t h a t is f o r m a t t e d w i t h b l o c k s o f e q u a l
s i z e . It p r o v i d e s a n i n d e f i n i t e l y d e e p h i e r a r c h y of d i r e c t o r i e s , w h e r e e a c h
d i r e c t o r y m a y c o n t a i n o t h e r d i r e c t o r i e s a n d files, o r j u s t files. T h e s t r u c t u r e is a
pure tree—that is, loops are not allowed.
T h e r e is sufficient r e d u n d a n c y i n t h e m e c h a n i s m to a l l o w y o u t o p a t c h
t o g e t h e r m o s t , if n o t all, o f t h e c o n t e n t s of a d i s k a f t e r a s e r i o u s h a r d w a r e
e r r o r , for e x a m p l e . T o p a t c h t h e c o n t e n t s of a d i s k , y o u u s e t h e D I S K E D
c o m m a n d . F o r f u r t h e r d e t a i l s o n t h e s y n t a x of D I S K E D , s e e S e c t i o n 1 . 2 ,
" D I S K E D — T h e D i s k E d i t o r , " later in t h i s c h a p t e r . B e f o r e y o u c a n p a t c h t o -
gether the contents of a disk, y o u m u s t understand the layout. T h e subsections
b e l o w d e s c r i b e t h e l a y o u t of d i s k p a g e s .

1.1.1 Root Block

T h e r o o t of t h e tree is t h e R o o t B l o c k , w h i c h is at a fixed p l a c e o n t h e d i s k . T h e
r o o t is like a n y o t h e r d i r e c t o r y , e x c e p t t h a t it h a s n o p a r e n t , a n d its s e c o n d a r y
type is different. A m i g a D O S stores the n a m e of the disk v o l u m e in the n a m e
field of t h e r o o t b l o c k .
 FILING SYSTEM 235

E a c h filing s y s t e m b l o c k c o n t a i n s a c h e c k s u m , w h e r e t h e s u m ( i g n o r i n g
o v e r f l o w ) o f all t h e w o r d s i n t h e b l o c k is z e r o .
T h e figure b e l o w describes t h e layout of t h e root block.

0 I T. S H O R T I Type
I 1 ^
1 |_ 0 _j Header k e y (always zero)

2 | _0_ _ J Highest seq n u m b e r (always zero)

3 I HTSIZE I H a s h t a b l e size ( = b l o c k s i z e - 5 6 )
I 1
4 f ____o____J
5
L CHJCKSJJJMJ
6l I
I hash I
I table I

SIZE-51 I I

SIZE-50 [ ] _ B M F L A G _]j T R U E if B i t m a p o n d i s k is v a l i d

SIZE-49 | Bitmap | U s e d to indicate t h e blocks

I P 8
a e s
I containing the bitmap
SIZE-24 | |

r 1
SIZE-23 I DAYS I V o l u m e last a l t e r e d
date a n d time
SIZE-22 I NflNS I
SIZE-21 £ TICKS

SIZE-20 | DISK | V o l u m e n a m e as a B C P L string

| NAME | of < = 3 0 characters
SIZE-7 I CREATEDAYS I V o l u m e creation date

r 1
and time

SIZE-6 I CJREATEMINS I

SIZE-5 ^CMATETICKS^ Next entry o n this h a s h chain (always zero)

SIZE-4 j 0 | Parent directory (always zero)

SIZE-3 I 0 I Extension (always zero)

SIZE-2 £ 0 ]j Secondary type indicates root block

SIZE-1 J ST.ROOT |
Figure 1-A: Root Block
236 AMIGADOS TECHNICAL REFERENCE MANUAL

1.1.2 User Directory Blocks

T h e following figure describes t h e layout of t h e contents of a user directory
block.

0 I _Tj5HORT _ I Type
1
E - - ^ — H e a d e r k e y ( p o i n t e r t o self)
2 [_ 0 J Highest seq n u m b e r (always zero)
3 I 0 I

5
L c™9s_y_M J
s

6 I I
I hash I
I table I
/ /

\ \

SIZE-51 I I

SIZE-50 £ ^pare_

SIZE-48 J PROTECT | Protection bits

SIZE-47 I 0 I U n u s e d (always zero)

S I Z E - 4 6 !~ 1
COMMENT Stored as a B C P L string
S I Z E - 2 4 [_ |
SIZE-23 | DAYS | Creation date a n d time

SIZE-22 I MINS I
SIZE-21 TICKS
SIZE-20 | D I R E C T O R Y i Stored as a B C P L string
| NAME | of < = 30 characters

SIZE-4 | HASHCHATNJ Next entry with same hash value

SIZE-3 r_JPARENT__ I Back pointer to parent directory

SIZE-2 _ 0 Extension (always zero)

SIZE-1 L J P l ^ S E R D J R J secondary type

Figure 1-B: User Directory Blocks

 FILING SYSTEM 237

U s e r d i r e c t o r y b l o c k s h a v e t y p e T. S H O R T a n d s e c o n d a r y t y p e S T . U S E R -
D I R E C T O R Y . T h e six i n f o r m a t i o n w o r d s at t h e start o f t h e b l o c k also i n d i c a t e t h e
block's o w n k e y (that is, t h e block n u m b e r ) as a consistency c h e c k a n d the size
o f t h e h a s h t a b l e . T h e 5 0 i n f o r m a t i o n w o r d s at t h e e n d o f t h e b l o c k c o n t a i n t h e
d a t e a n d time o f c r e a t i o n , t h e n a m e o f t h e d i r e c t o r y , a p o i n t e r to t h e n e x t file o r
directory on the h a s h chain, and a pointer to the directory above.
T o f i n d a file o r s u b d i r e c t o r y , y o u m u s t first a p p l y a h a s h f u n c t i o n t o its
n a m e . T h i s h a s h f u n c t i o n y i e l d s a n o f f s e t in t h e h a s h t a b l e , w h i c h is t h e k e y o f
t h e first b l o c k o n a c h a i n l i n k i n g t h o s e w i t h t h e s a m e h a s h v a l u e (or z e r o , if
there are n o n e ) . A m i g a D O S reads the block with this k e y a n d c o m p a r e s the
n a m e o f t h e b l o c k w i t h t h e r e q u i r e d n a m e . If t h e n a m e s d o n o t m a t c h , it r e a d s
the next block on the chain, and so on.
238 AMIGADOS TECHNICAL REFERENCE MANUAL

1.1.3 File Header Block

T h e f o l l o w i n g f i g u r e d e s c r i b e s t h e l a y o u t o f t h e file h e a d e r b l o c k .

0 I _ T^HORT _ I Type
1 j]_OWN_KEY_J Header key
2
L ^ G H E ^ S E Q J T o t a l n u m b e r o f d a t a
b l o c k s in file

3 I D A T A SIZE_ I N u m b e r o f d a t a b l o c k slots u s e d
4 £ FIRST DATA J First d a t a b l o c k

5
Li^^KSUM J

I DATA BLK 3 I
I DATA BLK 2 I list of d a t a b l o c k k e y s
S I Z E - 5 1 I D A T A B L K 1_ I

SIZE-50 £ ^pare_

SIZE-48 | PROTJCT | Protection bits

S I Z E - 4 7 I _B_YTE S I Z E _ I T o t a l size o f file i n b y t e s

SIZE-46 T 1
COMMENT C o m m e n t as B C P L s t r i n g
SIZE-24 j j
SIZE-23 | DAYS | Creation date and time
SIZE-22 I MINS |

SIZE-21 T TICKS

SIZE-20 | FILE | Stored as a B C P L string

|_ NAME _| of < = 30 characters

SIZE-4 Ly §. i =?i i^ J
A I ( A N e x t e n t r
y w i t h s a m e h a s h v a l u e

SIZE-3 I _J'ARENT__ I B a c k p o i n t e r to p a r e n t d i r e c t o r y

SIZE-2 £ J^XTENSION_ J Z e r o o r p o i n t e r to first e x t e n s i o n b l o c k

SIZE-1 L _ _ ? T i l L
l ;
_ I Secondary type
Figure 1-C: File Header Block
 FILING SYSTEM 239

E a c h t e r m i n a l file starts w i t h a file h e a d e r b l o c k , w h i c h h a s t y p e T . S H O R T

a n d s e c o n d a r y t y p e S T . F I L E . T h e start a n d e n d o f t h e b l o c k c o n t a i n n a m e ,
t i m e , a n d r e d u n d a n c y i n f o r m a t i o n similar t o t h a t i n a d i r e c t o r y b l o c k . T h e
b o d y o f t h e file c o n s i s t s o f D a t a b l o c k s w i t h s e q u e n c e n u m b e r s f r o m 1 u p -
ward. A m i g a D O S stores the addresses of these blocks in consecutive words
d o w n w a r d f r o m o f f s e t size-51 i n t h e b l o c k . I n g e n e r a l , A m i g a D O S d o e s n o t
u s e all t h e s p a c e for this list a n d t h e last d a t a b l o c k is n o t full.

1.1.4 File List Block

If t h e r e a r e m o r e b l o c k s i n t h e file t h a n c a n b e s p e c i f i e d i n t h e b l o c k list, t h e n
t h e E X T E N S I O N field is n o n z e r o a n d p o i n t s to a n o t h e r d i s k b l o c k w h i c h
c o n t a i n s a f u r t h e r d a t a b l o c k list. T h e f o l l o w i n g figure e x p l a i n s t h e s t r u c t u r e o f
t h e file list b l o c k .

0 I T.LIST I Type
I 1
1 1
OWNKEY j Header key
2 [BLOCK COUNT] = n u m b e r o f d a t a b l o c k s i n b l o c k list
3 I J^ATA_SrZE_ I Same as above
4 £ FIRST DATA J First d a t a b l o c k
5
L i ^ C K S J J M J
6 I I

I BLOCK N + 3 I
I BLOCK N + 2 I E x t e n d e d list o f d a t a b l o c k k e y s
SIZE-51 I BLOCK_N + l I
S I Z E - 5 0 |~ 1

j info J (unused)
| 1
SIZE-4 | 0 | N e x t i n h a s h list ( a l w a y s z e r o )
SIZE-3 I _J'ARENT__ I File h e a d e r b l o c k o f this file
SIZE-2 J^EXTE^IOnJ Next extension block
SIZE-1 |_ ST.FILE J secondary type

Figure 1-D: File List Block

240 AMIGADOS TECHNICAL REFERENCE MANUAL

T h e r e a r e a s m a n y file e x t e n s i o n b l o c k s a s r e q u i r e d to list t h e d a t a b l o c k s t h a t
m a k e u p t h e file. T h e l a y o u t o f t h e b l o c k is v e r y similar t o t h a t o f a file h e a d e r
b l o c k , e x c e p t t h a t t h e t y p e is d i f f e r e n t a n d t h e d a t e a n d f i l e n a m e fields a r e n o t
used.

1.1.5 Data Block

T h e following figure explains t h e layout of a data block.

0 I _ JJDATA__ I type

1 j ] _ HEADER _ J header key

2 | SE_Q_NUM | sequence number

3 I JDATA_SIZE_ I
next data block
4 NEXT DATA J
5
L J
6 I I

I DATA I

I I
Figure 1-E: Data Block

D a t a b l o c k s c o n t a i n o n l y six w o r d s o f filing s y s t e m i n f o r m a t i o n . T h e s e six

w o r d s refer to the following:

• type (T.DATA)
• p o i n t e r to t h e file h e a d e r b l o c k
• s e q u e n c e n u m b e r of t h e data block
• n u m b e r o f w o r d s of d a t a
• pointer to the next data block
• checksum

N o r m a l l y , all d a t a b l o c k s e x c e p t t h e last a r e full ( t h a t i s , t h e y h a v e a size =

b l o c k s i z e - 6 ) . T h e last d a t a b l o c k h a s a f o r w a r d p o i n t e r o f z e r o .
 FILING SYSTEM 241

1.2 DISKED—The Disk Editor

T o inspect or patch disk blocks, y o u m a y use the A m i g a D O S disk editor,
D I S K E D . B e c a u s e D I S K E D w r i t e s to t h e d i s k directly, y o u s h o u l d u s e it w i t h
c a r e . N e v e r t h e l e s s , y o u c a n u s e it to g o o d effect i n r e c o v e r i n g i n f o r m a t i o n f r o m
a corrupt floppy disk, for example. A disk d o e s n o t h a v e to b e inserted to b e
examined by DISKED.
Y o u s h o u l d o n l y u s e D I S K E D w i t h r e f e r e n c e to t h e l a y o u t of a n A m i g a D O S
d i s k . ( F o r a d e s c r i p t i o n of t h e l a y o u t , s e e S u b s e c t i o n s 1 . 1 . 1 t h r o u g h 1 . 1 . 5 in t h e
first p a r t of t h i s c h a p t e r . ) D I S K E D k n o w s a b o u t t h i s s t r u c t u r e — f o r e x a m p l e , t h e
R ( R o o t B l o c k ) c o m m a n d p r i n t s t h e k e y of t h e r o o t b l o c k . T h e G ( G e t b l o c k )
c o m m a n d followed b y this k e y n u m b e r reads the block into m e m o r y , w h e r e -
u p o n the I (Information) c o m m a n d prints out the information contained in the
first a n d last l o c a t i o n s , w h i c h i n d i c a t e t h e t y p e of b l o c k , t h e n a m e , t h e h a s h
l i n k s , a n d s o o n . If y o u s p e c i f y a n a m e a f t e r a n H ( H a s h ) c o m m a n d , D I S K E D
g i v e s y o u t h e o f f s e t o n a d i r e c t o r y p a g e t h a t s t o r e s a s t h e first k e y h e a d e r s w i t h
n a m e s t h a t h a s h to t h e n a m e y o u s u p p l i e d . If y o u t h e n t y p e t h e n u m b e r t h a t
D I S K E D r e t u r n s f o l l o w e d b y a s l a s h (/), D I S K E D d i s p l a y s t h e k e y o f t h a t
h e a d e r page. Y o u can then read this with further G c o m m a n d s , a n d so on.
C o n s i d e r d e l e t i n g a file t h a t , d u e to h a r d w a r e e r r o r s , m a k e s t h e filing s y s t e m
r e s t a r t p r o c e s s fail. First, y o u m u s t l o c a t e t h e d i r e c t o r y p a g e t h a t h o l d s t h e
r e f e r e n c e t o t h e file. Y o u d o t h i s b y s e a r c h i n g t h e d i r e c t o r y s t r u c t u r e f r o m t h e
root block, u s i n g the h a s h codes. T h e n , y o u m u s t locate the slot that references
t h e f i l e — t h i s is e i t h e r t h e d i r e c t o r y b l o c k or a h e a d e r b l o c k o n t h e s a m e h a s h
c h a i n . T h i s slot s h o u l d c o n t a i n t h e k e y of t h e file's h e a d e r b l o c k . T o s e t t h e slot
t o z e r o , y o u t y p e t h e slot o f f s e t , f o l l o w e d b y a s l a s h (/) f o l l o w e d b y z e r o ( t h a t
is, < o f f s e t > / 0 ) . T h e n correct the c h e c k s u m with the K (checKsum) c o m m a n d .
Y o u should disable the write protection with X a n d write b a c k the u p d a t e d
b l o c k w i t h P (for P u t b l o c k ) or W (for W i n d u p ) . T h e r e is n o n e e d t o d o
a n y t h i n g e l s e , a s t h e b l o c k s t h a t t h e file u s e d i n e r r o r b e c o m e a v a i l a b l e o n c e
m o r e after the R E S T A R T process h a s successfully s c a n n e d the disk.
D I S K E D c o m m a n d s a r e all s i n g l e c h a r a c t e r s , s o m e t i m e s w i t h a r g u m e n t s .
T h e f o l l o w i n g is a c o m p l e t e list of t h e available c o m m a n d s .
242 AMIGADOS TECHNICAL REFERENCE MANUAL

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 Function
Bn S e t logical b l o c k n u m b e r b a s e t o n
Cn Display n characters from current offset
G[n] 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 )
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)
S e t M a s k (for L a n d N c o m m a n d s ) t o n
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 u i t (do n o t w r i t e to disk)
Q
S char Set display Style
char C - > characters
S - > string
O - > octal
X - > hex
D - > decimal
T lwb upb T y p e r a n g e o f o f f s e t s in b l o c k
Vn Set Value for L a n d N c o m m a n d s
W Windup ( = PQ)
X Invert write protect state
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 Introduction
2.1.1 Terminology
2.2 O b j e c t File S t r u c t u r e
2.2.1 hunk unit
2.2.2 hunk name
2.2.3 hunk code
2.2.4 hunk data
2.2.5 hunk bss
2.2.6 hunk reloc32
2.2.7 hunk relocl6
2.2.8 hunk reloc8
2.2.9 hunk ext
2.2.10 hunk symbol
2.2.11 hunk debug
2.2.12 hunk end
2.3 Load Files
2.3.1 hunk header
2.3.2 hunk overlay
2.3.3 hunk_break
2.4 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
unresolved external references.

Program Unit
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-
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 subroutine,
main program, or Block Data. H u n k n u m b e r i n g 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 247

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

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 relo-
catable 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

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 Value Meaning

ext symb 0 Symbol table—see symbol block below
ext def 1 Relocatable definition
ext abs 2 Absolute definition
ext res 3 R e s i d e n t library d e f i n i t i o n
ext_ref32 129 32-bit r e f e r e n c e t o s y m b o l
ext common 130 32-bit r e f e r e n c e t o C O M M O N
ext refl6 131 16-bit r e f e r e n c e to s y m b o l
ext: ref8 132 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
 AMIGA BINARY FILE STRUCTURE 253

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 0 I
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 exter-
n 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 r e f e r e n c e s , it n e e d s to k n o w t h e
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 . The header block provides this
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 y also contain overlay infor-
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 separate 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 257

2.3.2 hunk 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,
258 AMIGADOS TECHNICAL REFERENCE MANUAL

IDNT A
XREF 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 00000000
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
0000000A Offset of definition
81000001 X R E F , Size 1 long w o r d
4A4F484E JOHN
00000001 N u m b e r of references
00000014 Offset of r e f e r e n c e
81000002 X R E F , Size 2 long w o r d s
42494C4C BILLY
59000000 (zeros to pad)
00000001 Number of references
0000000E Offset o f r e f e r e n c e
00000000 E n d of e x t e r n a l block
hunk end

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 :
 AMIGA BINARY FILE STRUCTURE 259

IDNT B
XDEF BILLY,J0HN
XREF MARY
0 0 0 0 ' 2A3C AAAA AAAA M0VE.L #$AAAAAAAAJD5
* External entry point
0006' 4E71 BILLY NOP
* External entry point
0008' 7201 JOHN" MOVEQ #1,D1
*Call e x t e r n a l r e f e r e n c e
000A' 4EF9 0000 0000 JMP MARY
END

and the corresponding output code would be:

hunk unit
00000001 Size i n l o n g w o r d s
42000000 Unit n a m e
hunk code
00000004 Size i n l o n g w o r d s
2A3CAAAA AAAA4E71 7 2 0 1 4 E F 9 00000000
hunk ext
01000001 X D E F , Size 1 long w o r d
4A4F484E JOHN
00000008 Offset o f d e f i n i t i o n
01000002 X D E F , Size 2 long w o r d s
42494C4C BILLY
59000000 (zeros to pad)
00000006 Offset o f d e f i n i t i o n
81000001 X R E F , Size 1 long w o r d
4D415259 MARY
00000001 N u m b e r of references
0000000C Offset o f r e f e r e n c e
00000000 E n d of e x t e r n a l block
hunk end

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 the
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
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 Introduction
3.2 Process Data Structures
3.3 Global Data Structure
3.3.1 Info Substructure
3.4 M e m o r y Allocation
3.5 S e g m e n t Lists
3.6 File H a n d l e s
3.7 Locks
3.8 Packets
3.8.1 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 Function Description

BPTR SegArray 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
LONG StackSize S i z e of p r o c e s s s t a c k i n b y t e s
APTR GlobVec G l o b a l V e c t o r f o r this p r o c e s s
LONG TaskNum 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
BPTR StackBase 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
LONG IoErr 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
BPTR CurrentDir Lock associated with current directory
BPTR CIS Current CLI input stream
BPTR COS Current CLI output stream
APTR CoHand 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
APTR FiHand 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
BPTR CLIStruct 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
APTR ReturnAddr Pointer to previous stackframe
APTR PktWait 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
APTR WindowPtr Pointer to w i n d o w
264 AMIGADOS TECHNICAL REFERENCE MANUAL

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 265

Value Function Description

BSTR CommandFile N a m e of E X E C U T E c o m m a n d file
LONG Interactive 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
LONG Background 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
BPTR CurrentOut Current CLI output
LONG DefaultStack 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 )
BPTR StandardOut Default (terminal) CLI output
BPTR Module 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

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 a
w i n d o w t h a t is n o l o n g e r p r e s e n t .
266 AMIGADOS TECHNICAL REFERENCE MANUAL

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 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
LONG Ticks N u m b e r o f ticks i n c u r r e n t t i m e
BPTR RestartSeg SegList for the disk validator process
BPTR Info 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 McName 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
BPTR Devlnfo 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
LONG Startup 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
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
268 AMIGADOS TECHNICAL REFERENCE MANUAL

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 refer-
ences to the device name use the same handler 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 vol-
umes 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 :
270 AMIGADOS TECHNICAL REFERENCE MANUAL

Value Function Description

LONG Link Not used
LONG Interact B o o l e a n , T R U E if i n t e r a c t i v e
LONG ProcessID P r o c e s s id of h a n d l e r p r o c e s s
BPTR Buffer Buffer for internal u s e
LONG CharPos Character position for internal use
LONG BufEnd E n d p o s i t i o n for i n t e r n a l u s e
APTR ReadFunc Function called w h e n buffer exhausted
APTR WriteFunc F u n c t i o n called w h e n b u f f e r full
APTR CloseFunc 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
LONG Argl 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
LONG Arg2 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 Function Description

BPTR NextLock B P T R to next in chain, else zero
LONG DiskBlock 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
LONG AccessType Shared or exclusive access
APTR ProcessID P r o c e s s id of h a n d l e r t a s k
BPTR VolNode 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 Description

APTR MsgPtr Pointer back to m e s s a g e structure
APTR MsgPort Message port where the reply should be sent
LONG PktType 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
272 AMIGADOS TECHNICAL REFERENCE MANUAL

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 per-
formed, 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
go-
W 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 as
required. T h e packet and message structures must be allocated, and 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 BPTR FileHandle
Arg2 BPTR Lock
Arg3 BSTR 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 LONG Action. FindOutput ( 1 0 0 6 )
Argl BPTR FileHandle
Arg2 BPTR Lock
Arg3 BSTR Name
Resl LONG Boolean

Arguments as for previous entry.

Read
Type LONG Action.Read ( 8 2 )
Argl BPTR FileHandle Argl
Arg2 APTR Buffer
Arg3 LONG 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 BPTR FileHandle Argl
Arg2 APTR Buffer
Arg3 LONG Length
Resl LONG Actual Length
274 AMIGADOS TECHNICAL REFERENCE MANUAL

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 BPTR FlleHandle Argl
Arg2 LONG Position
Arg3 LONG 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 BPTR Lock
Arg2 BPTR 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 LONG Action.ExamineNext ( 2 4 )
Argl BPTR Lock
Arg2 BPTR 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 LONG Action.DeleteObject ( 1 6 )
Argl BPTR Lock
Arg2 BSTR 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 Device-
Proc 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 BPTR Lock
Arg2 BSTR 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 BPTR Lock
Arg2 BSTR Name
Arg3 LONG 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 Not used
Arg2 BPTR Lock
Arg3 BSTR Name
Arg4 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 Not used
Arg2 BPTR Lock
Arg3 BSTR Name
Arg4 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 LONG Action.RenameObject ( 1 7 )
Argl BPTR FromLock
Arg2 BPTR FromName
Arg3 BPTR ToLock
Arg4 BPTR 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 BPTR Boolean
Again, this implements an operation not normally available through a func-
tion call. The single argument indicates the new name required for the disk
currently mounted in the drive handled by the filesystem process where the
packet is 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 han-
dling 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 describ-
ing 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:
 AMIGADOS ADDITIONAL INFORMATION 281

main (root level of the tree)

a,b,c,d (1,1) g (1,2).

e (2,1) f(2,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 mem-
ory 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 automati-
cally 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
282 AMIGADOS TECHNICAL REFERENCE MANUAL

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. There-
fore, 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 ex-
pansion, as needed. It is not currently used.
284 AMIGADOS TECHNICAL REFERENCE MANUAL

Perceived Impact
Old programs, programs that have not been compiled or assembled with the
new options, and programs that have not been run through ATOM will run (or
not run) as well as ever. This includes crashing in extended memory, if poorly
programmed. The "previous solutions" mentioned at the beginning of this
chapter still hold.
Program development and test on a 512K machine could follow EXACTLY
the same loop you have now—edit, compile, link, execute, test, edit, . . .
UNTIL you are about to release. Then you edit, compile, ATOM, Alink, add
external memory (>512K) and test. This works well for all three environments
(Amiga, IBM, and Sun).
For native (Amiga) development on a >512K machine you may want to
ATOM the few required object files so you can both run your linked program
in an extended memory machine and take advantage of a large RAM: disk. The
development cycle then becomes: edit, compile, optionally ATOM (if this code
or data contains items needed by the blitter), link, exteute, test, edit. . . .
"New programs" will not load in a VI.0 Kickstart environment. The result
will be error 103 (not enough memory).
Old (VI.0 and before) versions of dumpobj and OMD will not work on files
after ATOM has been run on them.
Working Environment
To get all of this to work together you need Release 1.1 compatible copies of:
ATOM (Version 1.0 or later)
Alink (Version 3.30 or later)
Kickstart (Release 1.1 or later) for DOS LOADER.
DumpObj (Version 2.1) Needed if you wish to examine programs modified by
ATOM.

ATOM Command Line Syntax

The command line syntax is:
ATOM <infile> <outfile> [-1]
or
ATOM <inffle> <outfile> [-C[CtDlB]] [-F[CtDB]] [-P[CIDIB]]

Where:
<infile> Represents an object file, just compiled, assembled or ATOMed
(Yes, you can re-ATOM an object file).
<outfile> The destination for the converted file.
-C Change memory to CHIP
-F Change memory to FAST
-P Change memory to "Public". (Any type of memory available.)
 AMIGADOS ADDITIONAL INFORMATION 285

C Change CODE hunks

D Change DATA hunks
B Change BSS hunks

Command Line Examples

Example #1
In most cases there is no need to place CODE hunks in chip memory. Some-
times 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 {Note: code hunk}
MEMORY ALLOCATION PUBLIC
DISPLAY SYMBOLS [Y/N] y
base..
xcovf.
_CXD22..
printf.
main...
MEMORY TYPE? [FlclP] ? {Note: request for help}
Please enter F for fast f

C for Chip
P for Public
286 AMIGADOS TECHNICAL REFERENCE MANUAL

Q to quit {cancels the operation, no output file is

created}
W to windup {does not change the rest of the file,
just passes it through}
N for Next hunk {skip this hunk, show next}
MEMORY TYPE? [FfclP] f
UNIT NAME 0 0 0 0
HUNKNAME NONE
HUNK TYPE DATA {Note: data hunk}
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
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 Man-
ual) 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 Next
0 dt device
0 Task (or process id—see below)
0 Lock
BSTR Filename of handler code
NNN Stacksize required
NN Priority required
XXX Startup information
0 SegList (nonzero if you load the code)
0 Global vector required
BSTR 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 (EndModule-StartModule)/4 Size of module in 1 words
EntryPoint
(your code)
CNOP 0,4 Align to lword boundary
DC.L 0 End marker
DC.L 1 Define Global 1
DC.L EntryPoint-StartModule Offset of entry point
DC.L 1 Highest global used
END
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 "LIBHDR"
GET "IOHDR"
GET "MANHDR"
GET "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 289

LET read.pkt 0
LET write.pkt 0
LET openstring parm.pktlpkt.argl
LET inpkt VEC pkt.resl
LET outpkt VEC pkt.resl
LETIOB VEC IO.blocksize
LETIOBO VEC IO.blocksize
LET error FALSE
LET devname "serial.device*XOO"
LET open FALSE (flag to show whether device has been "opened"
with act.findinput or act.findoutput).
LET node 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: (Open.)
CASE act.findoutput:
$( LET scb = p!pkt.argl
open : = TRUE
scblscbld : = TRUE (Interactive.)
returnpkt (p,TRUE)
LOOP
f)
290 AMIGADOS TECHNICAL REFERENCE MANUAL

CASE act.end: (C!

(Close.)
nodeldev.task : = 0 (Ri
(Remove process id from device node.)
open : = FALSE
returnpkt (p,TRTJE)
LOOP
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
CASE 'W: (A write request.)
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 per-
formed 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 Next
0 dt device
0 Task
0 Lock
0 Handler
210 Stacksize
10 Priority
BPTR to startup info
Seglist
0 Global vector
BSTR to name
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 Size of table
128 Disk block size in long words (assuming 512-byte
blocksize)
0 Sector origin (i.e., first sector is sector zero)
Number of surfaces (e.g., 2 for floppy disk)
1 Number of sectors per black
Number of blocks (e.g. 11 for floppy disk)
per track
2 (or more, indicating number of blocks to be reserved
at start)
0 Preallocation factor
0 Interleave factor
Lowest cylinder (commonly 0)
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 nor-
mally 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 re-
quester, 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 Command input and output, 18, 31

Address, 187 Command line, 208
Address modes, 195-196 Command Line Interface (CLI), 5, 22, 3 7 - 3 8 ,
Address registers, 187 53, 72-74, 81, 88-89, 152, 159-161, 264-266
Address variant, 196 Command names, 118-119
ALINK (developer's command), 8 4 - 8 5 , Command sequence, 7 8 - 7 9 , 89
168-169, 207, 209-211 Command syntax, 118-121, 209
Arguments, 6, 50, 119, 152, 153 Command template, 152
ASCII literal numbers, 194 Commands, background, 17, 77
ASSEM (developer's command), 85-86 Commands, commonly used, 21-22, 2 3 - 2 4
Assembler, 160, 188-189 Commands, developer's, 84-88, 89
Assembly control directives, 198-199 Commands, execution of, 5, 17-18, 54-63, 77, 183
Assembly language, 8 5 - 8 6 Commands, extended, 95-96, 103-104
ASSIGN (user's command), 36-37, 43 Commands, immediate, 92, 102-103
ATOM (Alink Temporary Object Modifier), Commands, recognition of, 6
282-287 Commands, repetition of, 95, 101-102, 115
Commands, use of, 16-17
Commands, user's, 40-84, 8 8 - 8 9
Binary file structure, 243-261 Comments, 190, 192
Binary numbers, 194 Conditional assembly directives, 203-204
Block control, 9 7 - 9 9 Conditionals, 66
Boolean returns, 171, 175 Console handler. See Terminal handler
Boot, 40 Control combination, 152
Bootable disk. See Disk, bootable COPY (user's command), 4 5 - 4 6
Bracket characters, 59 CopyDir (call packet), 276-277
Branches, 187 CreateDir (call packet), 276
BREAK (user's command), 4 3 - 4 4 CreateDir (function), 172, 276
Break block, 257 CreateProc (function), 181, 264, 265
Cross development, 162-169
CTRL-X (control combination), 5 - 6 , 152
C, initial environment in, 160 Current device, 9-11
Calling (AmigaDOS), 170-185 Current directory, 8-10, 27, 39, 153, 172
CD (user's command), 44-45 Current drive, 10, 153
Character pointer, 152 Current line, 109-111, 112-113, 122, 125-126,
Character string, 152 130-134, 141-142, 153
CLI. See Command Line Interface Current string, 153
Close (call packet), 274 CurrentDir (function), 172
Close function, 171-172 Cursor control, 92
Command definition, 152 Cursor position, 99, 152
Command file structures, 5 9 - 6 2
Command files, 17-18, 136
Command formats, 18-21 Data block, 240, 248
Command groups, 121
Data definition directives, 200-201
296 INDEX

Data registers, 187 Exchanging, 99-100

Data structures, 262-278 Execute (function), 183
DATA (user's command), 30, 46-47 EXECUTE (user's command), 54-63
Dates, 30, 46-47, 181 Exit, 182, 265
DateStamp (function), 181 ExNext (function), 173-174
Debug block, 254 Expressions, 192-194
Decimal numbers, 194 Extended mode, 91, 153
Default, 40 External references, 244
Default parameters, 58-59 External symbols, 205-206, 251, 258
Delay (function), 182
DELETE (user's command), 4 7 - 4 8
DeleteFile (function), 172-173 FAILAT (user's command), 6 3 - 6 4
DeleteObject (call packet), 276 Failures. See Errors
Delimiter characters, 153 FAULT (user's command), 64
Destination file, 153 File copy simulation, 5 9 - 6 2
Device names, 11-13, 40, 43, 153, 267 File copying, 33-34
DeviceProc (function), 182 File data, 177, 180
Devices, logical. See Logical devices File definition, 153
DIR (user's command), 4 8 - 4 9 File deletion, 32, 172-173
Directives, 196-206 File examination, 173
Directories, 7-10, 2 7 - 2 8 , 4 3 - 4 5 , 4 7 - 4 8 , 69-72, File formation, 68
153 File handles, 41, 175, 176, 269-270, 273-274
Directory blocks, 236-237 File handling, 171-180
Directory conventions, 14-16 File header block, 238-239
Directory creation, 34, 172 File linking, 84-85
Directory deletion, 172-173 File list block, 2 3 9 - 2 4 0
Directory examination, 173-174 File location, 34-35
Directory locking, 175-176, 179-180 File locking, 175-176, 179-180
Directory names, 76, 178 File opening, 176
Directory parent, 177 File parent, 177
Directory protection, 179 File protection, 179
Disk, bootable, 26, 28 File structure, 234, 243-261
Disk copying, 25 File system, 6-16, 2 9 - 3 0 , 67, 234-241
Disk, floppy, 65 File utilities, 88
Disk formatting, 2 5 - 2 6 Filename, 6-7, 32, 76, 153, 178
Disk information, 174 FILENOTE (user's command), 11, 64-65
Disk relabeling, 27 Floppy disk. See Disk, floppy
DISKCOPY (user's command), 4 9 - 5 0 FORMAT (user's command), 65
DISKED (disk editor), 241-242 FreeLock (call packet), 277
Diskette assignation, 3 6 - 3 7 Functions, 171-184
Disklnfo (call packet), 275
D O W N L O A D (developer's command), 8 6 - 8 7
Global data structure, 266-269
Downloading programs, 86-87
Global operations, 139-140
DupLock (function), 173, 277

Handler process, 262

E C H O (user's command), 50-51 Hexadecimal numbers, 194
ED (user's command), 51-52, 90-104 Hunks, 245, 246-261
EDIT (user's command), 52-53 Hunk Overlay Table, 280-282
Editing. See Line editor; Screen editor
ENDCLI (user's command), 53
End-of-file handling, 124 IF (user's command), 66-67
Errors, 63, 75, 83-84, 147-152, 161, 175, Immediate mode, 91, 153
211-212, 217 Info (function), 174, 275
Examine (function), 173, 275 INFO (user's command), 67-68
ExamineNext (call packet), 275 Info substructure, 267-269
ExamineObject (call packet), 2 7 4 - 2 7 5 Inhibit (call packet), 278
 INDEX 297

Input (function), 175 NEWCLI (user's command), 72-73

Input, console, 218-231 Node, 245, 257
Input files, 136-137, 175 Null string, 131
INSTALL (user's command), 68-69 Numbers, 194
Instructions, 187, 190-192, 196
Interruption, 18
IoErr, 175 Object code, 41
Islnteractive (function), 175 Object files, 207, 208, 244, 246-254
Octal numbers, 194
Opcode field, 191
Jumps, 187
Open (function), 176
Open New File (call packet), 273
Keyboard input, 219-220, 224 Open Old File (call packet), 272-273
Keywords, 18-20, 153 Operand field, 191-192
Operand types, 192
Operand word, 187
LAB (user's command), 69 Operation word, 187
Labels, 69, 190-191 Operators, 192
Letter case, 170 Output (function), 176
Libraries, 158, 170-185, 208, 245, 256, 266 Output, console, 218-231
Library base pointer, 266 Output files, 137-138
Line deletions, 113, 114, 126-127 Output processing, 124
Line editor, 5 2 - 5 3 , 105-154 Output queue, 153
Line insertions, 114-115, 126-127 OVERLAY (directive), 213-215
Line numbers, 109-110, 120, 122-123, 143 Overlay files, 208
Line splitting and joining, 133-134 Overlay nodes, 245, 257
Line windows, 128-130, 153 Overlay number, 217
Linker, 8 4 - 8 5 , 168-169, 207-231, 257 Overlay references, 216
Linking, new disk device, 291-293 Overlay supervisor, 207
Linking, new non-disk device, 293-294 Over table block, 257
LIST (user's command or directive), 28, 6 9 - 7 2 Overlaying, 213
Listing control directives, 201-203
Load file, 207, 244, 255-257
Loader, 257, 261 Packets, 271-278
Loading code, 183-184, 185 Parallel port, 87
LoadSeg (function), 183-184 Parameter file, 208
LocateObject (call packet), 276 Parameter substitution, 5 6 - 5 8
Location zero, 212 Parent (call packet), 275
Lock (function), 175-176 ParentDir (function), 177, 275
Lock duplication, 173 Pointing variant, 131-132
Locks, 270-271 Primary binary input, 208
Logical devices, 14-16, 41, 43, 267 Priority, 5, 153
Logical position, 178 Processes, 5, 154, 181-182, 263-266
Long word, 187 Program control, 9 6 - 9 7
Loops, 138-139 Program counter, 187
Program development, 158-159
Program encoding, 189-192
Macro assembler, 186-206 Program termination, 161
Macro directives, 204-205 Program unit, 244-245, 246
MAKEDIR (user's command), 72 Programming, 157-169
MAP output, 212 PROMPT (user's command), 74
MC68000 assembly language, 85 Prompts, 74, 122
Memory, 153, 183-184, 247-248, 269 PROTECT (user's command), 29, 74-75
Memory variant, 196
MS-DOS, 168
Multiple strings, 119-120 Qualified strings, 120, 123-124, 154
Multi-processing, 4 - 5 , 153 Qualifiers, 111-112, 154
298 INDEX

QUIT (user's command), 75 System disk, 41

System management, 89

RAM (device), 11-12

READ (developer's command), 87-$$ Terminal handler, 5 - 6 , 154
Read (function), 177 Text alteration, 100-101
Read call, 273 Text deletion, 94
Rebooting, 35, 41 Text insertion, 92-94, 142
Register (symbol), 194 Text string, 77
Register values, 170 Textfiles, 31, 51-52
RELABEL (user's command), 75-76 Time, 30, 46-47, 180, 181-182
Relative (symbol), 194 Trailing spaces, 143
Relocation, 2 4 9 - 2 5 0 TYPE (user's command), 31, 82
Rename (function), 178 Type commands, 134, 135
RENAME (user's command), 76-77
RenameDisk (call packet), 278 UnLoadSeg (option), 184
RenameObject (call packet), 278 UnLock (option), 179-180, 277
Resident libraries, 158, 170-185, 208, 245, 255
Restart validation process, 21 Values, 171
Root block, 234-235 Virtual terminal, 175
Root directory, 7, 154 Volume name, 10, 41, 75, 154
R U N (user's command), 77

WAIT (user's command), 83

Sample looping batch file, 6 2 - 6 3 WaitChar (call packet), 274
Scanned library, 208, 245 WaitForChar (function), 180, 274
Screen editor, 51-52, 90-104 W H Y (user's command), 8 3 - 8 4
Screen output, 221-223 Wild card, 7, 154
Scrolling, 95 WITH files, 210-211
SEARCH (user's command), 77-78 Word, 187
Searching, 77-78, 99-100, 120 Workbench, 2 2 - 2 3 , 161-162
Seek (call packet), 274 Workspace, uninitialized, 248
Seek (function), 178 Write (function), 180
Segment lists, 269 Write call, 273-274
Sequential files, 154
Serial line, 87
SetComment (call packet), 277 XREF output, 212
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