ATARI®

MACRO ASSEMBLER

JI\_
ATARI®
(IA Warner Communications Company

Every effort has been made to ensure that this manual accurately documents this product of the ATARI Home Computer Division.
However, because of the ongoing improvement and update of the computer software and hardware, ATARI, INC. cannot guarantee the
accuracy of printed material after the date of publication and cannot accept responsibility for errors .::>r omissions.

Reproduction is forbidden without the specific written permission of ATARI, INC., Sunnyvale, CA 94086. No right to reproduce this docu­
ment, nor the subject matter thereof, is granted unless by written agreement with, or written permission from the Corporation.

PRINTED IN U.S.A. MANUAL AND PROGRAM CONTENTS ©1981 ATARI, INC.

 CONTENTS

1 INTRODUCTION 1

Features of This Package 1

Macros 1
Conditional Assembly and Code Duplication 1
Systext Files 1
Program Listing Control 1
Cross-Reference Tables 1
Standard ATARI Computer and 6502 Mnemonics 2

Contents of This Software Package 2

Procedures 2
Program Loading Instructions 2
Creating a Source Program 2
Assembling a Source Program 3

Purpose of This Manual 3

References 3

2 ASS EM BLER EXECU TION 5

Command Line Syntax 5

Command Line Options 5
Command Line Examples 6
User Interface 7

3 FILE U S AG E 9

Source Input Files 9

System Text Files 9
Object Output File 9
Listing File 9
Source Listing Format 10
Sample Listing 10
Symbol Map Format 14

4 LANGU AGE STRU CTUR E 15

Statements 15
Label Field 15
Operation Field 15
Variable Field 15

Contents iii
 Statement Termination 16
Comments 16
Definitions 16
Symbols and Names 16
Numbers 17
Character Strings 17
Expressions 18
Operands 18

5 M ACRO FACILITY 21

Macro Definition 21
Macro Call 21
Code Duplication 22
Nesting 22

6 PS EU DO-O P ERATIONS 23

ASSERT 23
DB 24
DC 24
OS 24
ow 25
ECHO ... ENDM 25
EJECT 26
END 26
EQU or= 27
ERR 27
IF ... ENDIF, IF ... ELSE ... ENDIF 27
INCLUDE 28
LINK 29
LIST 31
LOC 32
MACRO ... ENDM 33
ORG 35
PROC ... EPROC 35
REAL6 36
SET 36
SPACE 36
SUBTTL 37
TITLE 37
USE 38
VFD 38

iv Contents
 7 PS EU DO-O P QU ICK R EFER ENC E 41

8 INS TRUCTION MN EMONICS 43

9 U SING T H E AT ARI MACRO ASS EM BLER

WITH T H E AT ARI ASS EM B L ER EDITOR
SOU RC E FILES 49

10 ERROR COD ES 51

Contents v
 1

INTRODUCTION

The ATARI® Macro Assembler is a software deve lopment tool for writing 6502
assembly la ngu age programs for the ATARI 800™ Home Computer The featu res of
this assem bler i n c l ude mac ros, cond itio nal assembly, code du p l i cation, access to
l i bra ry defi nitions, program- l i st i n g control, a nd c ross-reference tabl es. I t offers fast
compil ation and uses standard 6502 m nemonics.

FEATURES OF MACROS
THIS PACKAGE
The m a c ro featu re a l l ows you to define code words to represent m u l t i p l e instruc­
tions. I t makes it easy for you to use a seq uence of code many times i n a progra m .

CON DITIONAL ASSEMBLY AN D CODE DUPLICATION

Conditional asse m b l y al l ows the generation of s o u rce code based on certa i n c o n d i­

tions. Combi ned with macros this offers a powe rfu l and versati l e way of cod i n g
assem b l y la ngu age progra ms. A n E CHO pseudo-operation enables y o u t o repeat
sections of code (sim i l a r to the m a c ro featu re, but it does not a l l ow parameter
passing).

SYSTEXT FILES

Often you w i l l want to c reate and store sym bols and macro def i n itions on a l i brary
f i l e . O nce c reated , the sym bols can be referenced by any of you r sou rce programs.
S u c h a library f i l e can ease yo u r program d evelopment effort.

PROGRAM LISTIN G CONTROL

The L I ST pseudo-op l ets you tailor and an notate programs to fit you r exact needs.
The pseudo-op m akes doc u mentation eas ier by a l l owing l i sti ng control and page
headings.

CROSS-REFERENCE TABLES

The Macro Asse m b l e r a l so i n c l udes a n optional c ross-refe rence table so that you
can reference labels and variables in the sou rce program quickly.

I n troduction 1
 STANDARD ATARI COMPUTER AN D 6502 MN EMONICS

A fi le conta i n i ng the ATA R I Home Computer Hardware Reg ister add resses and O S
S hadow Register add resses is i n c l uded on you r M a c r o Assembler d i s kette . You may
reference standard AT A R I Com puter m nemon ics i n your programs u s i ng this fi le.
See Systext reference i n "Command L i n e Options" in Section 2.

Sta ndard MOS Tec hnol ogy 6502 m ic roprocessor cod i n g format is u sed in this
assem b l er. The formation of expressions a l so fo l l ows the standard conventions.

CONT ENTS OF The Macro Assem bler i n c l u des:

THIS SOFTWARE
• A d i s kette containing both the Macro Asse m b l e r and P rogram-Text E d i tor™
PACKAGE software
• A reference card giving pseudo-ops, error codes, and Program-Text E d i tor
commands and messages
• T h i s refere nce m a n u a l for the AT A R I Macro Assem b l er
• An operators m a n u a l for the ATA R I Program-Text E d itor

PROCEDURES PROGRAM LOADING INSTRUCTION S

1. Connect the ATA R I 800 Home Computer to a te levis ion set and to a wa l l
outlet as instructed i n the operators m a n u a l .

2. Connect the ATARI 810™ Disk Drive t o the com puter console a n d t o a wal l
outlet as instructed i n the ATARI 810 Disk Drive Operators Manual. Verify
that the d i s k d r ive is set to D R I V E CODE 1 as i nstru cted in the operators
manual.

3. Open the cartridge door on the top of the computer console. Remove a l l
cartridges from the top front cartri dge s l ots. C l ose the cartridge door.

4. T u r n on your te levision set.

5. T u rn the d i s k d r ive POW E R (PWR) switch to O N . Two red l i ghts (the B U SY

l i ght and the PWR ON l ight) wi l l come o n .

6. When the B U SY l ight goes o u t, open the disk d r ive door by press i n g the door
hand l e release lever.

7. I nsert the d i skette conta i n i ng the Macro Assembler and P rogram-Text E d itor
programs i nto disk drive 1.

8. Switc h t h e POW E R ( PW R) switc h on the compute r c o nso le t o O N .

T h e D O S I I M e n u wi l l now appear on y o u r screen.

CREATING A SOURCE PROGRAM

To use the ed itor, refer to the ATARI Program-Text Editor Manual.

2 I n troduction
 After you c reate your source program, exit the Progra m-Text E d itor u s i n g the com­
m a nds that wi l l return you to DOS:
1. P ress lmmll
2. Type EXIT and press (Th i s retu rns you to DOS.)
Then, to asse m b l e you r sou rce program:
1. Type the l etter L and press
2. Type AMAC a n d press

ASSEMBLING A SOURCE PROGRAM

1. Refer to "Com mand L i n e Syntax" ( i n Section 2) for the command l i ne syntax

a nd c o m m a nd l i ne options. Press after the command l i ne.
2. After the assem b ly, press the to retu rn to DOS. Your DOS d i rec-
tory wi l l now s how that you c reated an obj ect f ile with an extension,
O BJ.

PURPOS E OF T h i s m a n u a l is i ntended to s how you how to use the Macro Assembler. I f you p l a n
t o use the Progra m-Text E d itor for c reat i n g you r source program , it is suggested
THIS MANUAL
that you read the ATARI Program-Text Editor Manual, then practice c reat i n g f i les.

A k nowledge of asse m b l y l angu age and AT ARI DOS 11 is a l so necessary. The texts
l isted below w i l l assist in your study of asse m b l y la ngu age. I f you wish to become
fam i l i a r with the spec i a l featu res of the AT A R I Home Computer, a copy of the
ATARI Technical Users Notes wi l l be needed.

REFERENCES We recom mend the fol l ow i ng books:

MOS Programming Manual by MOS M i c rocomputers

SY6500/MCS6500 Microcomputer Family Programming Manual by SYN E RT E K
6502 Assembly Language Programming by Lance Leventhal
6502 Software Design by Leo Scanlon
6502 Software Gourmet Guide and Cookbook by Robert F i n d l ey

AT A R I pu b l i cations:

ATARI DOS I I Reference Manual

ATARI Technical Users Notes

Introduction 3
 2

ASSEMBLER EXECUTION

COMMAND LINE The Macro Asse m b l er is ac cessed by the AT ARI DOS 11 Menu option L. W hen DOS
SYNTAX asks for a f i l ename to load, type:

AMAC mm1a

Once AMAC is loaded into memory, it w i l l ask you to "E nter sou rce f i l ename and
opti ons." The sou rce f i l ename m u st a lways be specif ied. Any options you wish to
use shou l d fol low the f i l ename, sepa rated by e i ther a com ma or space. The com­
m and l ine is te rm inated by a carri age retu rn. The comm and l ine cannot be edited
u s ing the c u rsor control keys.

The gene ral form of the com mand l ine is: < f i l espec > opt1 , . . optn. W here
< f i l espec > is the source f i l e to be ass e m b l ed and is of the form
< dev i ce > : < f i lename > . < extension > . The above command l ine cou ld have
been typed with any m ixture of u pper- or lowercase c haracters. The asse m b l er wi l l
convert a l l comm and l ine characters to uppercase before interpretation.

COMMAND LINE The 'opt1 , . . optn' are optiona l paramete rs (in any order) c hosen from this l i st:
OPTIONS
H = Dn: G enerate object output f i l e to the specif ied disk drive
(Defau l t is H Dn:
= where n may be 1 , 2 , 3, or 4. I f no f i l ename is spec ified, the
where n is the object f i l e wi l l be named with the input source f i l ename
same disk drive as and the extension, OBJ .
the sou rce f i le)

H = < f i l espec > Write object code to < f i l espec > .

H =O Do not generate any object code.

L = P: L i st output to printer.

L = Dn: L ist output to spec if ied disk drive (n = 1 , 2, 3, or 4). L i st

f i lename has the input sou rce f i l ename and the extens ion
PRN .

L = S: Output l isting to the sc reen.

L = O (Defau l t' Do not produce l isting for this assem b l y.

O=n Preset the v a l u e of the run address of the object program .

Spec ify ing "O = n" on the com mand l ine is exactly l ike
the statem ent " E N D n" found at the end of an assem b l y
program.

O = O (Defa u l t) Set the value of the run address to zero.

Assembler Execution 5
 PS = n (Defa u l t is Set page s ize to < n > sou rce l i nes per page. Page s i ze
PS = 63) must be l ess than 1 27 . When page size is l ess than 1 0, no
title or s u btitle l i nes nor page ejects are printed i n the l ist
f i le, and a fu 11 c ross-refere nce is d i sa l l owed.

PS = O Do not print title and su btitle l i nes and page ej ects to l i st

f i l e for this assembly.

S = < f i l espec > Spec ify systext f i le. The S option may be repeated. The
user may specify as many systexts as des i red, so long as
combi ned number of systexts and l i nk f i les does not ex­
ceed the f i l e l imit of 40 .

s U se the defa u l t systext D : S Y S T E XT . A ST.

S = O (Defau l t) Spe c i fy no systext for t h i s assembly.

R=F G enerate fu l l refe rence map. L ist a l l global symbols and

their references on the f i l e spec if ied by the L parameter.

R=S G e nerate short reference map. L i st a l l global symbols and

the i r va l u es o n l y on the f i l e spec if ied by the L parameter.

R = O (Defa u l t) Do not generate reference map.

SL = n Set the l i ne length. Maximum le ngth of the l i ne output to

(Defa u l t is the l ist f i le w i l l be < n > characters; the rest of the l i ne is
S L = 80 for P: and d iscarded i f < n > is greate r than the device l i ne
S L = 38 for S:) l ength.

A l l numeric argument v a l u es (for 0 = n , PS = n, and S L = n) may be specif ied ac­

c o rd i n g to the general syntax for n umbers. I n particu l ar, a n exp l i c it rad ix (dec ima l ,
b i nary, octa l , or hexadecimal) can b e used. Refer t o Section 4 , "N umbers," f o r rad ix
spec ification.

All l owercase l etters on the command l i ne a re converted to u ppercase before i nter­

pretation.

COMMAND LINE D : T E S T I T.ASM

EXAMPLES w i l l read input f i l e D1 : T E ST I T.ASM (D: imp l ies D1 :), no l isting w i l l be prod u ced, and
the AT ARI b i nary format obj ect f i l e w i l l be D1 : T E S T I T.O BJ .

D : T E ST I T.ASM H = O R = F L = S:
w i l l assemble D1 : T E S T I T.ASM, suppress object f i le generation, and send a l isting
with f u l l reference map to the s c reen.

D2 : T E S T I T.ASM H = D: L = D2: R = F 0 = $200

The assembler w i l l assemb l e the f i l e D2 : T E S T I T.ASM generat i ng the obj ect f i l e
D 1 : T E ST I T. O BJ , a n d w i l l prod u ce a l i sting and fu l l reference map i n
D2:T E ST I T. P RN. I n add ition, it w i l l a l so set the r u n add ress t o $200.

6 Assembler Execution
 02 : T E S T I T.ASM S S = D 2 : M SY S . AST L = P: R = F H = O: 0 = $1 700
The assem b l e r w i l l process the two systext f i les 01 : S Y S T E XT. AST and
02:MSYS. AST, assemb le the file 02:TEST I T .ASM, produce the object f i l e
0 1 : T E S T I T . O B J w i t h a run add ress o f $1 700, a n d p r i n t a l isting w i t h fu l l refe rence
map on the pri nter.

U S ER INT ERFACE The assemb ler execution may be prematu rely termin ated by press i n g the
key . When output l isting is d i rected to the screen, its execution can be tempora ri
ha lted by simu ltaneously press i n g the key and the 1 key. Press i n g those two
keys aga i n w i l l restart exec ution.

I f a d isk-write error happens (usua l ly d isk or d i rectory fu l l) , the offe n d i n g file (ob­
ject or I ist f i l e) is erased, an error message is issued to the screen, and f u rther at­
tempts to write to the f i l e are suppressed. Assemb ly then cont i n ues norma l l y.

Assembly time errors are pri nted to the screen as we l l as to the l ist f i l e.

Assembler Execution 7
 3

FILE USAGE

SOURCE You can specify sou rce i n put f i les by u s i n g the:

INPUT FILES
• F i rst command l i ne argument
• Systext f i l e argument (S parameter)
• L I N K pseudo-i nstruction
• I N C L U D E pseudo-i nstru ction

A l l i n put f i les must be i n P rogram-Text E d itor format. They c o n s ist of a l i n e or

l i nes of ATASC I I characters term i n ated by AT A SC I I E nd-of- L i nes < E O L > .

SYST EM A system text f i l e (systext) is a n assemb ly l a ngu age f i le of symbols and macro
T EXT FILES def i n itions. The programmer can predef i n e symbols here for many d ifferent pro­
grams. Some examp les are:

• ATASC l l control characters (BS, TAB, E SC, E O L , .. )

• Addresses (entry poi nts i nto C I O, S I O, and cha n n e l l ocations)
• Macros

If an assembly error is encou ntered whi l e sca n n i ng a systext f i l e, the assembler

aborts w ith a n error message.

OBJECT The object output f i l e ge nerated by the assemb l e r has a defau lt f i l e exte n s i o n of
0 BJ and is in AT A R I b i na ry format. Refer to the ATARI DOS II Reference Manual
OUT PUT FILE
for deta i l spec i f i cations of b i n a ry format.

LISTING FILE The output l i sti ng of the source prog ram gene rated by the assem b l e r has a
defa u lt exte n s i o n of P R N .

The Macro Assemb ler has a f lexible set o f l i sti n g control pseudo-ops wh i ch a l l ows
the user to generate o n l y the desired program content.

Page head i n g (u n l ess su ppressed via PS = 0) conta ins the assembler vers i o n and
page n umber as we l l as optional u ser-spec if ied title information (see T I T L E and
S U BTT L pseudo-ops).

The L I ST pseudo-op (or L command l i ne argument) controls whi ch source l i nes are
l isted. E ach code l i ne l isted beg i n s w ith 20 col umns of i n formation generated by
the assembl er.

Col umn 1 of the l isti n g output is reserved exc l u s ively for errors; a l isti n g free of
assembly errors w i l l not have any printing in col umn 1 . A n error c o u nt is reported
at the end of the assembly. (See Section 1 0, E rror Codes.")
"

File Usage 9
SOURCE LISTING 1 2

FORMAT 1 23456789.1 2 3456789.

E add r# hhhhhhhhhh L i n e that generates code.
R add r = vvvv E Q U , S E T, I F , etc.
R - L i ne that is s k i pped.
0 a d d r = vvvv # Location a n d o r i g i n cou nters a re u neq u a l .
R add r
+ hhhhhhhhhh Mac ro-generated l i ne.
add r hhhh /\ad d r Desti nation address of PC rel ative j u mps.

Column Description
1 E rror flag or b l a n k . See Section 1 0 for the mea n ing of error f l ags.

2 Blank.

3-6 Address l ocation of this i nstruction (va l u e of the l ocation cou nter).

6 - s i g n means l i n e not assembled d u e to IF . . . E LS E . L i n e o n l y l i sted i f

L I ST F i n effect.

7 # sign means the l ocation and o r i g i n cou nters a re u neq u a l .

8 + s ign means assembler-generated l i ne. L i n e l i sted if L I ST M i n

effect.

9-1 8 hhhhhhhhhh is the resu ltant code. Up to f ive bytes are listed. If L I ST
G or D is i n effect, m u l t i p l e l i nes w i l l be l isted w ith u p to f ive bytes
on each.

1 1 -1 4 vvvv = v a l u e of express i o n .

1 9-20 Always b l a n k .

21 -80 Sou rce statement.

SAMPLE LISTING 1 /0 E Q U AT E S
= 009B EOL = $9B
= 0030 I OC B 3 = $30
= 0340 ICH I D = $0340
= 0341 I C DN O = I CH I D + 1
= 0342 I CCOM = I C DN0 + 1
= 0343 I C STA = I CCOM+1
= 0344 I C BA L = I C STA + 1
= 0345 I C BAH = I C BA L + 1
= 0346 I C PT L = I C BA H + 1
= 0347 I C PT H = I C PT L +1
= 0348 ICBLL = I C PT H +1
= 0349 ICBLH = ICBLL + 1
= 034A I CAX1 ICBLH + 1
= 034B I CAX2 = I CAX1 +1

10 File Usage
 = 0003 O PEN = $03
= 0005 CETREC = $05
= 0009 PUT REC = $09
= OOOC C LOSE = $0C
= 0004 O REA D = $04
= 0008 OW R I T = $08
= 0088 EOF = $88
= E456 C I OV = $E456
= 0040 I OC B4 = $40
'

; F I RST I N I T THE I OC B FOR OPEN

0000# = 5000 O RC $5000

;DATA REG I O N
5000 4432 3A5445 ;N AME1 DB 'D2 :TEST1 ',EO L
= 0050 BUF1 SZ 80
= 5009 BUF1 *

5009 = 5059 O RC * + B UF1 SZ

5059 5032 3A9 B N AME2 DB 'P2:',EO L
5050 A230 START L OX # I OC B3
505F A900 L DA #LOW NAME1
5061 904403 STA I C BA L,X
5064 A950 L DA #H I CH NAME1
5066 9 04503 STA IC BAH,X
5069 A900 L DA #0
506 B 9D4B03 STA ICAX2,X
'

;"OPEN" THE D I S K

506E A903 L DA #O PEN

5070 904203 STA ICCOM,X
5073 2056E4 JSR CIOV
5076 BC4303 L DY I C STA,X
5079 1 003 /\507E BPL L1
507 B 4CA250 JM P ERR2
'

;CHA N NEL 4 I S P R I NTER

'

507E A240 L1 LDX # I OC B4

5080 A959 L DA #LOW NAME2
5082 904403 STA I C BAL,X
5085 A950 L DA #H I CH NAME2
5087 904503 STA IC BAH,X
508A A908 LDA #OW R I T
508( 9D4A03 STA ICAX1 ,X
508F A900 L DA #0
5091 9D4 B03 STA ICAX2,X
,

;"OPEN" THE P R I NTER

5094 A903 LDA #O PEN

5096 9 04203 STA I CCOM,X
5099 2056E4 J SR C I OV
509( BC4303 LDY ICSTA,X
509F 1 004 /\50A5 BPL T P1 0

File Usage 11
 '

;ERROR - J U ST B R K

SOA1 00 ERR1 BRK

SOA2 00 ERR2 BRK
SOA3 00 ERR3 BRK
SOA4 00 ERR4 BRK
'

;SETU P TO READ A RECORD

SOAS A230 T P1 0 LDX #I OCl33

SOA7 A90S LDA #CETREC
SOA9 9D4203 STA I CCOM,X
SOAC A909 LDA # LOW BU F1
SOAE 9D4403 STA I C BAL,X
SOB1 A9SO L DA #H I GH B UF1
SOB3 9D4S03 STA I C BAH,X
'

;READ RECO RDS

'

SOB6 A9SO LOO P LDA # LOW B UF1 SZ

SOBB 9D4B03 STA I C B L L,X
SO BS A900 LDA #H I GH BUF1 SZ
SO B D 9D4903 STA I C B LH,X
soco 20S6E4 JSR C I OV
SOC6 1 004 /\SOCC BPL P R NTR
'

;NEC STATU S ON READ - EOF

'

SOCB COBB TP20 C PY #EOF

SOCA DOD7 /\SOA3 BNE ERR3
'

; P R I NT A RECORD

socc B D4B03 PRNTR LDA I C B LL,X

SOCF A240 LDX # I OC B4
SOD1 9D4B03 STA I C B LL,X
SOD4 A230 L DX # I OCB3
SOD6 B D4903 STA I C B LH,X
SOD9 A240 L DX # I OC B4
SODS 9D4903 STA I C B LH,X
SODE A909 L DA #PUTREC
SOEO 9D4203 STA I CCOM,X
SOE3 A909 LDA # LOW B UF1
SOES 9D4403 STA I C BAL,X
SOE8 A9SO LDA #H IGH BU F1
SOEA 9D4S03 STA I C BAH,X
SOED 20S6E4 JS R C I OV
SOFO BC4303 LDY I C STA,X
SOF3 1 003 /\SOFB BPL L3
SOFS 4CA4SO JMP ERR4
SOFB A230 L3 L DX # I OC B3
SOFA BC4303 LDY I C STA,X
SOF D COBB C PY #EOF
SOFF F003 /\S1 04 BEQ L2
S1 01 4CASSO JM P TP1 0

12 File Usage
51 04 A90C L2 L OA #C LOSE
51 06 904203 STA I CCOM,X
51 09 2056 E 4 J SR C I OY
51 0C A90C LOA #C L O S E
51 0 E A230 L OX # I OC B3
51 1 0 904203 STA ICCOM,X
51 1 3 2056 E 4 J SR C I OV
51 1 6 00 BRK
51 1 7 E ND

No E R RORS, 39 l a bels, $A3E6h f ree.

B UF1 5009 1 #36 2/28 2/30 2/60 3/ 2

B UF1 SZ 0050 1 #35 1 /37 2/35 2/37
C I OV E456 1 #2 5 1 /51 2/1 2 2/39 3/ 4 3/1 8 3/2 3
CLOSE oooc 1 #21 3/1 6 3/20
E OF 0088 1 #24 2/45 3/1 2
EOL 009 B 1 #3 1 /34 1 /38
n E R R1 50A1 2#1 8
E R R2 50A2 1 /54 2#1 9
E R R3 50A3 2#20 2/46
E R R4 50A4 2#21 3/ 8
G ET R E C 0005 1 #1 9 2/26
I CAX1 034A 1 #1 5 1 /1 6 2/ 4
I CAX2 034 B 1 #1 6 1 /45 2/ 6
I C BA H 0345 1 #1 0 1 /1 1 1 /43 2/ 2 2/31 3/ 3
I C BA L 0344 1# 9 1 /1 0 1 /41 1 /60 2/29 2/61
I C BLH 0349 1 #1 4 1 /1 5 2/38 2/54 2/56
ICBLL 0348 1 #1 3 1 /1 4 2/36 2/50 2/52
I CCOM 0342 1# 7 1/ 8 1 /50 2/1 1 2/27 2/59 3/1 7
3/22
I C DNO 0341 1# 6 1/ 7
ICH I D 0340 1# 5 1/ 6
I CPT H 0347 1 #1 2 1 /1 3
I C PT L 0346 1 #1 1 1 /1 2
I C STA 0343 1# 8 1/ 9 1 /52 2/1 3 2/40 3/ 6 3/1 1
I OC B3 0030 1# 4 1 /39 2/25 2/53 3/1 0 3/21
IOC B4 0040 1 #26 1 /58 2/51 2/55
L1 507E 1 /53 1 #58
L2 51 04 3/1 3 3#1 6
L3 50F8 3/ 7 3#1 0
n LOOP 50 B6 2#35
NAM E 1 5000 1 #34 1 /40
NAM E 2 5059 1 #38 1 /59 1 /61
OPEN 0003 1 #1 8 1 /49 2/1 0
nOREAD 0004 1 #2 2
OWR I T 0008 1 #2 3 2/ 3
PRNTR 50CC 2/41 2#50
PUTREC 0009 1 #20 2/58
nSTART 5050 1 #39
T P1 0 50A5 2/1 4 2#25 3/1 4
nTP20 50C8 2#45

File Usage 13
SYM BOL When R S is sel ected, the short symbol map is printed at the end of the p rogram
=

MAP FORMAT l isting. For each symbol name in the program, the fol lowing is pri n ted:

sa symbol hhhh, where:

< s > is b l a n k or "s" for a name i nt rodu ced in a systext f i le.

< a > is either b l a n k or
U = u ndef i ned, or
D doubly defi ned, or
=

n = not referenced.
< symbo l > is the name of the symbo l .

< hhhh > is the symbol v a l u e i n hexadec i m a l , or " m ac" if the n a m e is a macro.
Four symbo ls are p r i n ted on each l i ne, u s i ng the defau l t l i ne l e ngth.

Whe n R F is sel ected, the fu l l c ross-reference map f o l l ows the sou rce l isting. O n
=

each l i ne, i n add ition t o the R S i nformation above, c ross-reference i nformation i s

=

l isted. E ach reference has the form:

ppp/11

where < ppp > equals page nu mber and < II > equals l i ne n u mber. For a defin ition
reference, the I is rep l a ced by #.

N ames begi n n i ng w i th a : ( l oc a l symbols) and a? ( u s u a l l y macro invented) are not

i n c l uded in e i ther type of symbol map output.

Symbo l s def ined i n a systext f i l e appear in the c ross-reference only if they are used
d u ri n g the assembly; they a re f l agged w ith an s.

14 File Usage
 4

LANGUAGE STRUCTURE

A Macro Assembler sou rce program consists of a seq uence of statements, com­
ments, and def i n itions. Statements are the fu ndamental units of assembly. Com­
ments do not affect assembler operat ion or object output. Def i n itions may be con­
d ition a l l y asse mbled, saved for later assembly, or repeated.

A l l characters in a statement are co nverted to u ppercase except those in the com­

ment f i e l d .

STAT EM ENTS A statement is d iv ided i nto three f i e l ds: a labe l f i e l d , a n operation f i e l d , and a
variable f i e l d .

LABEL FIELD

The l abel f i e l d beg i ns w i th the f i rst chara cter of the statement and is term i n ated by
a b l a n k or an end of statement. If a c o l o n (:) is the l ast character of the l abe l f ield, i t
is d isc arded . For exa m p l e:

SYM BX: AOC M E M,X ;comment

SYM BX is the defi ned l abel .

OPERATION FIELD

The operation f i e l d beg i ns w i th the f i rst nonbl ank character after the l abe l f i e l d
and te rm i nates w i th the next b l a n k character. Machine op codes, pseudo-ops, a n d
macro c a l ls a l l o c c u r i n the ope ration f i e l d . I f this f i e l d is em pty, the variable f ield
m ust be em pty al so. For exa m p l e:

SYM BX: ADC M E M, X ; com ment

ADC is the machine op code.

VARIABLE FIELD

The variab l e f i e l d beg i ns w i th the f i rst character after the operation f i e l d and is ter­
m i nated by an end of statement. Variab les, expressions, and other argu ments used
by the operation f i e l d appear in this f i e l d . For exa m p l e:

SYM BX: ADC M E M, X ;comment

M E M, X is the variable.

Language Structure 15
STAT EM ENT A statement is ter m i n ated by:
T ERMINATION
Beg i n n i ng of comment (;), or
E nd-of- L i ne, or
Logical end of statement mark (!).

SYM BX: ADC M E M,X ;comment

SYM BY: ADC M E M,X
SYM BZ: ASL ASL ASL ASL ; 4 statements

In the last exa m p l e (SYM BZ), one source l i ne conta ins four statements. Three of
them are ter m i nated w ith an !, the l ast by a ;. I dentical object code wou l d be
generated if the ! were repl aced by E nd-of- L i n e < E O L > . When an ! and a ; o c c u r
i ns i de q u ota tion marks, they do n o t fu nction as sep arators.

COMM ENTS A comment beg i n s w ith a ; fol l ow i n g the variable f i e l d of a statement. A com ment
affects ne ither the assembler operation nor the obj ect code generated .

Com ments that beg i n i n c o l u m n 1 are fu l l-l ine comments; they beg i n with a ; or an
* . ( P l ease note that a n * s ignif ies a comment only when found in c o l u m n 1 - col­
umn 1 of i n put is l isted at col u m n 21 on an output l i sting.) A comment is ter­
m i n ated by E O L .

LA B E L: LOA 1 29 ;This is a "comment."

;This is a fu l l-l ine comment.
* This is a nother f u l l- l i ne comment.
F RO G : ST A M E M,X This is not a legal comment.
;(above comment needs a ;)

DEFINITIONS Def i n itions beg i n with spec i f i c types of statements (MACRO, E CHO, I F). The end of
a def i n ition is dependent on what sta rted the def i n ition, for exam p l e, E N DM is
used to ter m i nate MACRO and E C H O def i n itions, whi l e E N D I F term i n ates a n I F
range.

SYM BOLS AND A symbol is a seq u ence of characters that identifies a v a l u e o r a m a c ro. The f i rst
character c a n not be a d igit. Symbols may be any length, but they m u st be u n iq u e i n
NAM ES
the f i rst s i x characters. The fol lowing characters may b e used in a symbol name:

A-Z The u ppercase l etters of the al phabet

a-z The l owercase l etters of the a l phabet (converted to u ppercase by the
assembler
May o n ly be f i rst character ind icating a local symbol
If f i rst character, then the symbol is exc l u ded from the refe rence map
@ Additional a l pha extension. C a n not be f i rst character of an identifier,
s i nce it is a l so a prefix for octal n u mbers.
0-9 D igits

16 Language Structure
 The underl ine c haracter (_) may oc cur i n a name as written but is d i scarded.
Lowercase l etters are mapped i nto the corres pond i ng upperc ase. When a colon oc­
curs as the first c h aracter in a name, it denotes a name local to the current PROC
(see PROC pseudo-op in Section 6). A colon at the end of a name in the l abel field is
i n terpreted as a ter m i n ator but in any other position, it is ignored .

Examples:

E R RO R_S ;the assemb ler ignores _ , label is

ERRORS
JM P RESTART ;the assemb l er uses f irst 6
characters: 'REST AR'
TEST LDA COUN T
BNE E rrorS ; 'ErrorS' converted to E R R O RS
: LOCA L: DEC ;: loca l : is a l ocal symbol

NU M B ERS A number can be in a ny one of three forms, depe n d i ng on the prefix.

Prefix Base

% 2 B i n ary
@ 8 Octal
$ 16 H exade c i m a l

The lack of a prefix i m p l ies dec i m al.

D igits greater than the radix are not a l l owed. The under l i ne character (_) is
ignored .

The Macro Assembler prov ides constant convers ion formatt i ng for 6-byte real
numbers as specif ied in the current AT A R I BAS I C Real numbers are not v a l i d ex­
pression argume nts i n variable f i e l ds. (See " REA L6," pseudo-op i n Section 6).

Examples:

B l NV A L EQU %1 0 001 01 0
OCTVA L EQU @ 21 2
H EXVAL EQU $8A

CHARACT ER The assembler accepts AT ASC I I characters $20-$7E as valid characters. A char­
acter string cons ists of any sequence of c haracters surrounded by s i ngle quotation
STRINGS
marks ('n . . . n'). W i t h i n a stri ng, a s i ngle quotation m a rk c h aracter is represented by
two success ive s i ngle quotation marks.

Character str i ngs can be used i n the T I T LE and SUBTTL statements, as a DB or DC

subf ield, or as opera nds of rel ational operators.

The LSTR operator returns the l ength of a character string (see "Express ions" i n this
section).

Language Structure 17
 Examples:

TITLE 'Sam p l e E xpressions'

DB 'This is a ST R I N C .',$9B
DB 'Control characters are i l l egal i n a long stri ng'
DB $9B
;Nonpri ntab l e characters may be represented
;by using their hexad e c i m a l va lues,' ,
;such as $9B for E O L',
ow $2766, 'bp', ' B P' ;2-byte va lues
LOA #43 ;a dec i m a l number
ADC #'C' ;an AT ASC 11 c h a racter
CMP #'''' ;an AT ASC I I character

EXPRESSIONS A n expression cons ists of operands combi ned with operators to produce a va lue.
Operators of equa l precedence are evaluated l eft to right. B rackets can be used to
override the order of eva luation, s i n ce 6502 i nstructions use parentheses for i n­
d i rect address i ng. E xpress ions a re eva luated us i ng 1 6-bit twos c o m p lement (un­
signed) arithmetic. Overf l ow is ignored.

Real numbers are not v a l i d argume nts i n express ions.

Examples:

DB 'H ere are some fancy express ions:'

DB 43 + 2 2 shl 3 mod 6
DB 'Q' + R E F1 xor [99 and R E F2]
AND l ow ['ZZ' - ['A' xor 'a' + ['A' xor 'a'] shl 8]]
ow rev [ * 0 - * L]

OP ERANDS A n operand is either a symbol , an expression e n c l osed i n brackets, a number, a

character stri ng, or one of the fol l ow i ng spec i a l elements:

* current location counter

*L same as *
*O current value o f origin counter
*P current position counter number of defi ned byte

See LOC and ORC pseudo-ops for further d iscuss ion of * L and * O. Refer to the
VFD pseudo-op for deta i l s on * P.

The com parison operators return a value of zero for false and $ F F F F for true.
Numeric tests treat va lues as uns igned, so that [ -1 < 0 ] w i l l produce the a nswer
f a l se. Character string tests use the AT ASC 11 col l a t i ng sequence.

18 Language Structure
Operators

+ Sum or positive sign

D i fference or negative sign
Multi ply
I D ivide
NOT Bit-by-bit comp lement
AND Logical product, conjunction
& Logical product, conjunction (same as A N D)
OR Logi c a l sum, d isjun ction, i n c l usive O R
XOR Logical d i fference, i nequiva lence, exc lus ive O R
EQ Equa l i ty
<> NE I nequa l i ty
< LT Less than
< = LE Less than or equal to
> CT Greater than
>= CE G reater than or equal to
SHL S h i ft left n bits
SHR Shift right n bits
HIGH Unary, h igh value to 8-b it field = x I 256
LOW Unary, l ow value to 8-b it f ie l d = x MOD 256
MOD Modulus function
REV Unary Reverse = (( LOW x) left and right SHL 8) + ( H I G H x)
DEF Test symbol prev iously defined
LSTR Return the length of a character string

Precedence Levels

Highest B rackets
HIGH LOW DEF REV LSTR
I MOD SHL SHR
*

+ unary
+ b i n a ry
<> < <= > >= NE EQ LT LE CT CE
NOT
& AND
Lowest OR XOR

Lang uage S tructure 19

 5

MACRO FACILITY

A macro is a seq uence of source statements that are saved and then assembled
through a m a c ro c a l l . A macro c a l l cons ists of a reference to a ma cro name in the
operation f i eld of a statement. It often i n c l udes actual para meters to be
subst ituted for formal parameters in the macro code seq u e nce, so that code
generated can vary with each assembly of the def i n ition.

Use of a macro req u ires two steps: def i n ition of the macro and reference to the
macro.

MACRO A macro definition cons ists of th ree parts: head i ng, body, and term inator.
DEFINITION
Heading A macro definition starts with the name of the macro and the
substitute parameter names in the variable f ie l d .

Body T h e body begins w i t h t h e f i rst statement after t h e head i ng that is

not a comment l i ne. The body cons ists of a ser ies of i nstru ctions.
All i nstru ctions other than E N D, i n c l ud i ng other macro def i n itions
and c a l ls, are l egal w i t h i n the body. H owever, a defin ition w i t h i n
.
a def i n ition is n o t def i ned u nt i l t h e outer defin ition is c a l led.
Therefore, a n i n ner def i n ition can not be c a l led d irectly.
Substitute parameters can o c c u r anywhere in the body. T hey are
pref ixed by a percent sign (%):

%1 f irst parameter
%2 second

%9 n i nth parameter
%K 4 hex d ig i ts, represe nting the serial nu mber
of this macro c a l l
%L the labe l f i e l d of the macro ca l l
% M = the name o f the m a c ro
%% repl aced by a s i ngle percent
=

Terminator A macro def i n ition is term i nated by a n E N DM pseu d o-i nstru ction.
The assembler cou nts the nesting l evel of MAC RO/ E C H O and
E N DM pairs occurring i n a macro body, so that the definition is
term i nated o n ly by the correspond i ng E N DM.

Note: The E N DM pseudo-op m u st be preceded by a tab (�) c haracter. Press

emmmJ to get the tab character.

Macro Facility 21
MACRO CALL A prev i ously def ined macro is c a l l ed when its name occurs i n the operation f i e l d of
a statement. If actua l parameters appear i n the cal l , they are substituted for the
correspo n d i n g formal parameter in the macro body w ithout eva luation. O n l y after
the e n t i re body has been expanded does assembly resume. T hus the statements
generated by the macro may themselves contain further macro c a l l s or def i n itions,
with the nesting l i m ited only by ava i l able memory.

Note: When writing recurs ive m a c ros, take care in the cod i ng of the term i n ation
condition(s). A macro that repeated l y c a l ls itse l f w i l l cause the assembler to ter­
m i nate (eventual l y) with the message "Memory Overf l ow ."

CODE The E C H O pseudo- i n struction is used to repeat a code sequence. I t is written

s i m i larly to a m a c ro def i n ition but w it h the fol lowing d i fferences: hea d i n g is E C HO,
DU PLICATION
not MACRO; no parameters are involved; the variable f ield of the E C H O statement
spec ifies how m a ny times the body is to be repeated. E N DM is a l so used to ter­
m i n ate an E C H O seque nce (see E C H O pseudo-op).

NESTING E C H O , MACRO, and I F blocks m ay be nested in compl etely arbitrary fashion, sub­
ject o n l y to the constraint that it be properly nested; i.e., each block must be con­
tai ned w i t h i n the surround i n g block.

22 Macro Facility
 6

PSEUDO-OPERATIONS

The Macro Assembler prov ides a comprehens ive set of pseu do-operations (pseudo­
ops) that perm its you to control the assembly process.

For ease of comprehension, the fol l ow i ng notations are u sed i n this m a n u a l :

iglab means the l abel f i eld is ignored by the pseudo-op

<exp> means that an expression is requ ired

[exp] means that an expression may a ppear, at your option

{exp} means that the item i n side the braces { } may appear zero or
m ore t i mes

ASS ERT CHECK ASSEMBLY CON DITION

iglab AS S E RT < exp >

where: iglab ignored l abe l field

exp any l egal expression: N onzero i m p l ies true
Zero i m p l ies false

A SS E RT a l l ows you to c heck for and f l ag i l logical assembly cond itions such as i n­
correct parameter v a l u es, programs that are too l arge, and u ndef i ned symbo l s .

The expression is eva l u ated and a P error w i l l b e generated if t h e expression is f a l se;

i.e., if the expression eva l u ates to zero.

The expression is not exam i ned in Pass 1 of the assembl er, so A SSERT can correctly
check any condition. Forward referen ces i n the expression are eva l u ated correctly.

Examples:

To c heck that the location cou nter i n a given piece of code is w i t h i n bou nds, i n this
case be l ow $2000, add the fol lowing l i ne at the end of the assembly:

AS S E RT * < $2000;test for l i m i t exceeded

If the location cou nter reac hes $2000, a P error w i l l ge nerate.

If you are writing a u t i l ity subroutine and wish to c heck that a req u ired symbo l ic
defin ition has been s u p p l ied by the user of the subroutine, you m ight code:

Pseudo-Operations 23
 A S S E RT D E F [SYM B1 ]

I f the req uired symbol SYMB1 is not defined by the user wit h i n the assemb ly, a P er­
ror w i l l be generated. N ote that the c heck for symbol definition is postponed u nt i l 1I
after Pass 1 , a l lowing you t o define SYMB1 a nywhere i n t h e source code.

DB DEFINE BYTE

LA B E L : DB < exp > . . . , < exp >

where: < exp > = any l ega l expression, v a l u e, or stri ng

DB a l l ows you to directly specify the content of indiv i d u a l bytes of memory.

A string wil l generate as many bytes as it has characters; the f i rst character wil l be
the first byte generated. Characters in the string generate their 7-bit ATA S C I I codes
without parity.

DB is used to i n ters perse code w ith text strings and for data tables.

The l abel field is signif i cant; it wil l address the first byte generated.

Examples:

PNCHRS: DB ' , ./; @ @ < > ? + !' '#$%&' ( ) * = + (tm):-[] @ ',O

' _

DB $80
DB LA B, LA B2 ,3,$46,$0A F,'xX',1 7 + QVA L * 4,'coffee'

DC DEFINE CHARACTER

LA B E L : D C < exp > . . . , < exp >

w here: < exp > is any legal expression , val ue, or string

DC operates l ike DB, but the h i gh-order bit (parity bit) of the last byte of each ex­
pression is set.

DC is used j u st l ike D B . The o n l y difference is the pa rity bit of the l ast byte of each
term.

Examples:

TBLHDR DC ' This is a table of offsets'

A D R LST DC 1 28, $36, $1 5, @ 21 , 1 59

OS DEFINE SPACE �

L A B E L: OS < exp1 6 >

where: < exp1 6 > = any l egal expression, val ue, or string

OS a l l ows you to reserve l a rge b l oc k s of memory. The expression < exp1 6 > wil l be
eva l u ated as a n u n signed 1 6-bit v a l u e, and that v a l u e w i l l be used to inc remen t the
assembler's inte rnal o rig i n and location cou nters.

24 Pseudo-Operations
 Mem ory a l l ocated is not init i a l ized, and w i l l conta i n u n k nown va l u es at program
execu tion time. The l a bel f i e l d is s i g n i f i cant; it w i l l add ress the f i rst memory byte
al l ocated.

DS reserves space for use at execution ti me; it can be used to "s kip over" a n ex­
isting piece of ROM or prov ide for u n i n i t i a l ized data storage.

Example:

STORG: DS 256 ; a l l ocate 256 bytes

ow DEFINE WORD

LABEL: DW < exp1 6 > .. , < exp1 6 >

< exp1 6 > = any express ion o r va l u e o r 1 to 2
c h a racter string
w here: < exp1 6 > = any expression, val ue, or string

DW defines the contents of b l ocks of mem ory. Val ues and exp ressio ns in the
operand fie ld a re computed as u ns igned 16-bit va l u es and pl aced in memory as a
m a c h i n e word; the asse m b l e r p l a ces the Least S i g nif icant Byte (LS B) f i rst, fol l owed
by the Most S i gnificant Byte (MSB).

The l abel f ie l d is s i gnificant; it w i l l add ress the first byte gene rated .

DW is i ntended to b u i l d tables of 1 6-bit val ues.

Examples:
Tab l e of Add resses
DW PWRON ; Power on
DW MSTRST ;Master reset
DW SYSCAL ;System cal i b rate
DW RE CAL ;Reca librat ion
DW PWRDN ; Power down
DW BUTTON ; Button press
DW E M E RG ;E mergency shutdown
DW ACTN1 ,ACTN2,ACTN3 ;Action n u m bers 1,2,3
DW 0 ;E nd of tab l e

ECHO... ENDM ECHO BLOCK

LA B E L: ECHO < exp >

E N DM

w here: < exp > = n u m e ric express ion

ECHO . . . E N DM is a simple code-d u p l ication facility . Code between an ECHO and

its E N DM w i l l be assemb led as m a ny ti mes as specified by the < exp > .

The l abel f i e l d is s i g n ifica nt; it add resses the v a l u e of * O w hen the E C H O pseudo­
op is encou ntered.

Pseudo-Operations 25
 An E C H O . . . E N DM construct may not exceed 255 repetitions; 0 (ze ro) repetitions
mea ns the ECHO . E N DM code is s k i pped. E C H O . . . E N DM is convenient for
repetitious cod i n g problems. A n E C H O E N DM seq u ence is much easier to
create and ma i ntain than, say, 1 27 repetitions of a 6-l i ne proced u re.

Note: The E N DM pseudo-op must be preceded by a tab (�) character.

Example:

; The fol l owing example w i l l c reate a table

; of 20 entries of 4 bytes each and
; i n i tial ize each entry to a value of
; $1 0 37 00 00.

TABLE: ECHO 20 ;20 times

DB $1 0, $37, $00, $00
E N DM ;E nd table

EJ ECT EJECT PAGE

iglab E JE CT
ig l a b = ignored label fie l d

E J E CT forces a page eject i n the assembly listing if the listi ng is c u r rently tu rned on.

E J ECT can be used anyw here i n a n assembly sou rce program.

The T I T L E pseudo-op sets the internal tit le string and forces an E J E CT.

Example:

E J E CT

END EN D PROGRAM

LA B E L: E N D [exp]

E N D te l l s the assemb ler where to stop assemb ly and beg i n the c ross-reference
map. The optio n a l address f i e l d express ion specif ies the ru n address for a n object
program.

E N D must be the l ast statement of the last link f i l e of an assembly.

The l abel f i e l d is significant, and add resses the v a l u e of the i ntern a l *O cou nter
when the E N D is processed.

Example:

FREE SP: END ;end of program

26 Pseudo-Operations
EQU or EQUATE VALUE TO SYMBOL
LA B E L : EQU < exp1 6 >
LA B E L : < exp1 6 >

where: < exp1 6 > = 1 6-bit expression or val ue or

1 to 2 c ha racter string

EQU defi nes the symbol on the l eft as the value of the 1 6-bit expression in the
operand f i e l d .

E Q U c reates symbols (labe l s) for u s e with other assembler i nstructions. U n like S E T,

E Q U defi nes a f ixed v a l u e to a symbol that can not be changed d u r i n g the
assembly.

The operand < exp1 6 > must be an abso l u te v a l u e at the time of eva l u ati on; any
symbols used i n the expression must have been prev iously defined .

Examples:

TSTC H R EQU '$'

TS2C H R : EQU '@'
ZAP EQU $900
ZO N K : ZAP * 2

ERR FORCE ERROR FLAG

E R R a l l ows you to force an assemb ly error. The add ress f i e l d is ignored. When the
assemb l e r detects an imposs i b l e or u ndesira b l e condition at assemb ly time, E R R
a l l ows this to be f l agged .

Examples:

I F * > 4000h
E RR ; Program too long
ENDIF

IF ... ENDIF, ig l a b I F < exp >

IF... ELSE ... ENDIF < code for special s ituation >
iglab E N D IF

ig l a b I F < exp >

< assemb l y code >
iglab E LS E
< assembly code >
iglab E NDIF

where: < exp > expression : nonzero = > true

zero = > f a l se

Pseudo-Operations 27
 I F . . . E N D I F and I F .. . E L S E . . . E N D I F control textual i n put to the assembler. At
assembly time, <exp > is eva l u ated and the res u l t determines w here the assembler
w i l l resume assemb l i ng the input file.

W henever a s i n g l e program shou ld be configured as two (or more) d istinct versio ns,
I F . . . E N D I F and I F . . . E LS E . . . E N D I F can test assembly-time v a l u es and assemble
only the appropriate sou rce l i nes.

E x press ion <exp > va l u es for an I F must be numeric; strings greater than two
c ha racters a re not a l l owed.

I F . . . E N D I F and I F . . . E L S E . . . E N D I F constru cts are " nestable"; depth of nesting

is l imited only by memory space avai l ab l e at assembly time.

Any " l abel" in the l a bel f i e l d is ignored; a desc r i ptive name can be p l aced here to
he l p associate an I F w ith its E LS E (if u sed) and E N D I F .

Examples:

IF 1 ;1 is nonzero, therefore true

J SR O UTM
JM P BOOT ;these two I ines wil I be assemb led
ENDIF
LABE L: IF DEF X ;Cond ition
J SR PAT H1 ;LA B E L is ignored, but
LA B E L : JMP E LSE ;ass ists readabi I ity.
JM P PAT H 2
ENDIF

INCLUDE INCLUDE ANOTHER SOURCE FILE

LA B E L : I N C L U D E <fil espec >

where: <f i l espec > = < D n : f i l en ame.ext > , n can be 1 , 2, 3, or 4

I NC L U D E spec ifies a nother f i l e to be i n c l u ded i n the assembly as if the co ntents of

the referen ced file appea red in place of the I N C L U D E statement itse l f . The in c l u­
ded file may conta i n other I NC L U D E stateme nts. The list ing of code in I NC L U D E
f i les i s contro l led by the I option o f the L I ST pseudo-op. (See I N C L U D E examp le.)

I N C L U D E a l l ows you to d ivide l a rge programs into manageable p ieces for ease of
ed iting, common use of librar ies, f i l e man i p u l ations, and so forth.

Example:

The comma nd line

D : I N C L D E X.ASM
combined w ith the f o l l ow i ng, file setu p:

< I N C L D E X.ASM contents >

TITLE ' I N C L U D E example'
ORG $1 00
I NCLUDE D : L1
I NCLUDE D:L2
I NC L U D E D 2 : L3.ACD
; * * * E nd I NC L D E X.ASM

28 Pseudo-Operations
 < D: L1 contents >
LOA L1 VAL
; * * * E nd L1 . ASM

< D : L2 contents >

L OA L2VA L
;* * * E nd L2 .ASM

< D 2 : L 3 . A C D contents >

L1 VAL DB '* '
L2VA L DB 0
END ; Stop assemb ly here.
; * * * E nd L3.ACD

This would i n put to the assembler the fo l l owing seque n ce of code:

TITLE ' I N C L U D E exam p l e'

ORC $1 00
LOA L1 VAL
· * * * E nd L 1 .ASM
LOA L2VA L
; * * * E nd L2.ASM
L1 VAL DB '*'
L2VA L DB 0
END ;Stop assemb ly here.
; * * * E nd L3.ACD
·* * * E nd I N C L D E X.ASM

LINK LINK TO ANOTHER SOURCE FILE

ig l a b LINK < filespec >

w here: < filespec > = < D n : filename.ext > , n can be 1 , 2, 3, or 4

The L I N K pseudo-op is sim i l a r to the I N C L U D E facil ity, except that link f i les are not
assem b l ed until the assemb ler reaches the end of the current i n put f i l e. W henever
a L I N K pseudo-op is found, it is stored away for processing a l ong with any other
L I N K statements encountered when the current file is f i nished processing.

E ac h source f i l e that contains links to other files w i l l be completely processed, and

its links wil l then be processed in order of occurrence. Any l i n k that contains
sub l i n k s wil l be processed i n a n identica l manner; link f i les may nest arbitra r i l y
deep, as long as t h e total number of files does n o t exceed 40.

If A, Q, S, T, U, and X a re assemb ly-code files, and if A l i nks to Q, S, and X, and S

links to T, and T l i nks to U, then the order of assembly w i l l be:

A, Q, S, T, U, X.

If the < fi l espec > extension is missing, it defaults to the exten s i o n used in the cur­
rent i n put file; i.e., the f i l e that contains the L I N K pseudo-op.

Pseudo-Operations 29
 Examples:

Link D2: PA RT1 ;Assemble f i le ' D2 : PA RT1 '

; u s i n g the same extension as

;the pr imary f i l e
LINK D : U T I L.ACD
B LO R P : LINK D 2 : PART2. ASM ;' B L O R P' is ignored

L I N K a l l ows you to d ivide l a rge programs i nto managea ble p ieces for ease of
editi ng, common use of l i braries, f i l e manipu l ations, and so forth. The L I N K fac i l ity
supports l i n k i ng a c ross d i skettes, so the entire source program does not have to be
conta i n ed on the same d i skette.

Example:

The comma nd l i ne

AMAC D : L I N K E C . ASM

combi ned with the fol l ow i n g l i n k f i l e setup:

< L I N K E C . ASM contents >

TITLE 'L I N K example'
ORC $1 00
LINK D : L1
LINK D : L2
LINK D 2 : L3.AC D
'·* * * E ndx L I N K E C . asm

< D : L1 c ontents >

L DA L1 VA L
·* * * E ndx L1 . asm
< D : L2 contents >
LDA L2VAL
'·* * * E ndx L2 . asm

< D 2 : L3.AC D contents >

L1 VAL DB '*'
L2VAL DB 0
END ;Stop assembly here.
·* * * E ndx L3.acd

wou l d i n p u t to the assembler the fol lowing seq u ence of code:

TITLE ' L I N K example'

ORC $1 00
·* * * E ndx L I N K E C . asm
LOA L1 VAL
'·* * * E ndx L1 . asm
LOA L2VAL
·* * *
'
E ndx L 2 . asm
L1 V A L DB '*'
L2VAL DB 0
END ;Stop assembly here.
'·* * * E ndx L3. acd

30 Pseudo-Operations
LIST OUTPUT LISTING CONTROL

iglab L I ST *
iglab L I ST < opt > . . , < opt >

w here: < opt > = optional minus sign fo l l owed by one of the fo l l ow i ng.

C L ist l ist i n g controls: EJ ECT, PAGE, S PACE, S U BTTL, and T I TLE l i nes (Defau l t
OFF )

D L ist detailed code: i . e . , l ist every byte gene rated by D B , DW, VF D, mu l ti-l i n e
statements, a n d s o forth.

F L ist code sk i pped by IF . . E N D I F or IF .. ELSE . ..E N D I F . (Defau l t O N )

G List all generated code: i.e., l ist every byte p l a ced i n the output object f i le,
regard l ess of origin. Ove rrides -L. (Defa u l t OFF.)

L ist code i n I N C L U DE f i l es. (Defa u l t OFF .)

L Master L I ST control. When -L option is i n effect, noth i n g is l isted except l i nes

with errors, or when -L is overridden by the G option. (Defa u l t O N .)

M L ist a l l l i nes gene rated by macro refe rences. (Defau l t O N .)

R Acc umu l ate cross-referen ces. (Defau l t O N .)

S List code referenced i n a systext f i l e. (Defau l t OFF.)

L I ST contro ls the l isting produ ced d u r i n g an assembly. H owever when an L = O

comma nd l i ne option is selected, L I ST pseudo-op has no effect. The variable-f ield
a rgument to L I ST must be a n * , or a set of options.

The LI ST pseudo-op ope rates on a sta c k : each e l ement of the stack is a set of op­
tion f l ags. The f l ag on top of the stack controls the content of the l isti n g produced.
Eac h c a l l to the L I ST pseudo-op w i l l push, or pop, a f l ag on or from the stack.

" L I ST * " means pop the l ist-o ption stac k .

" L I ST M" means make a copy of t h e c u r rent f l ag, sett i n g t h e M-f lag t o O N , a n d
p u s h t h e new f l a g sett ing onto t h e stack.

L I ST has obvious ap pl i c ations for detai led l isting of new l y wr itten code, deta i l ed
of u n tested macro expansions, and suppress i n g the I ist i n g of I i brary code.
I ist i n g

Example:

A common code l i brary may conta i n a set of routi nes a l l having the fol lowing I F
b l oc k a t the begi n n i n g:

IF I L I ST = 0 ;if common code l ist tu rned off

L I ST -L, -R ;no l isti ng, no references
ENDIF

Pseudo-Operations 31
 Assume that the g l obal symbol I L I ST eq u a l s zero. A new f l ag sett i n g is pushed onto
the L I ST o ption stack; the options (-L, -R) specify no l i sting is to be pri nted, and no
c ross-reference accumu l ation is to be done.

E ac h common code rou t i n e a l so has this I F . . . E N D I F at its end:

IF I L I ST = 0 ;if common code listing was off

L I ST * ;go back to origin a l l i st options
E NDIF

N ow that the common code routine has been assemb l ed, the L I ST optio n stack w i l l
b e popped. T h i s retu rns the L I ST option stack t o its condition before the libra ry was
assembled.

LOC SET LOCATION COUNTER

LABE L: LOC < exp1 6 >

where: < exp1 6 > 1 6-bit expression or v a l u e

L O C sets t h e location cou nter. The expression i s eva l u ated as a n u n sig ned 1 6-bit
va l u e and assigned to the Macro Assemb l e r's i nternal location cou nter ( * L).

Code gene rated while the internal LOC cou nter (* L or * ) does not eq u a l the internal
ORC cou nter ( * 0) w i l l be f l agged with # in c o l umn 7 of the list i ng.

The l abel field is s i gnificant; the l abel def ined there wi l l be set to the va l u e of *L
before * L is changed to < exp1 6 > .

LOC assists you i n generating self-over l ay i n g programs. Code generated that way
can be positi oned anywhere in memory (using O RC), and the code w i l l assemble as
if it was l ocated at the add ress expressed in the LOC statement. Of cou rse, the code
must be moved at ru n time to the address spec ified in its LOC statement before it
can be exec uted.

Code assem b l ed in one p l ace for exec u tion e l sewhere can be especia l ly handy for
ROM-resident software, when pieces of code a re copied f rom ROM to RAM before
execution.

LOC is a l so usef u l for enhancing the readabil ity of data tab les for code conversion .
T h e fo l l owing examp l e is a tab l e o f external B C D codes. T h e location cou nter is set
to the ATASCll v a l u e of the first c ha racter in the table. I n that way, the location
field of the assembly listing contains an AT ASC I I v a l u e and the generated code
field contains its associ ated external BCD v a l u e .

Examples:
; E xample of using LOC to enhance readabil ity of
;l istings. The location cou nte r wil l be set to
;the ATASC l l v a l u e that corresponds to the first
;entry of a ta b l e of external BCD val ues.

0000 5000 O RC $5000

5000 0041 # LOC 'A'

32 Pseudo-Operations
 0041 # 61 E BC T B L : DB $61 ;The LOC f i e l d of the l i sting
0042# 62 DB $62 ;conta ins the ATASC l l v a l u e
0043# 63 DB $63 ;wh i c h corresponds to the
0044# 64 DB $64 ;exte rnal BCD v a l u e in the
0045# 65 DB $65 ;gene rated code fie l d .

END

N o E R RORS, 1 labe l s , $2403 f ree.

n E BC T B L 0041 1# 8

;E xample of code to be assembled at $2000

to be
;tra nsferred to a ROM at $0FOOO

= 0500 CO U N T EQU $0500 ;RAM wor k i n g

storage
0000 = 2000 O RC $2000
2000 = FOOO# LOC $0FOOO
FOOO# A907 LDA #07
F002# 8 DOOOS STA CO U N T
FOOS# 4COAFO JM P L1
F008# EA NOP
F009# EA NOP
FOOA# C E OOOS L1 DEC COUNT
FOOD# EA NOP
FOO E# END

N o E R RORS, 2 l a be l s , $23F7 free.

COU N T 0500 1# 4 1/ 8 1 /1 2
L1 FOOA 1/ 9 1 #.1 2

MACRO . . . ENDM MACRO DEFINITION

MACN AM: MACRO parm1 , . . . , parmn

< body >
E N DM ;end of MAC NAM definition

w here: < body > = any des i red text w h i c h may i n c l ude:
%1 . . %9 parameters number 1 . . . 9
%K hexadecimal number of this macro c a l l
%L l abel f ie l d of macro c a l l
%M name of the macro

MACRO . . . E N DM is the macro definition construct.

The symbo l s in the variab l e field represent su bstituta b l e paramete rs. The symbol
names are for doc umentation purposes o n l y and may not appear in the body of the
macro.

Pa rameters w ithin the macro are represented by %x, where x is rep l aced with a
d e c imal digit (1 -9). %K with i n the body wil l be repl aced with the serial number of
the macro c a l l as f o u r hexadecimal d igits. %L with i n the body w i l l be repl aced
with the label f ie l d of the macro c a l l . %M w ithin the body wil l be rep l aced with the
macro c a l l .

Pseudo-Operations 33
 The l abel f i e l d is si gnificant; it denotes the name of the macro d u r i n g an assembly.

Note: The E N DM pseudo-op must be preceded by a tab (�) c haracter.

M a c ros may generate l i nes w h i c h turn o u t to be macro c a l l s . Thus, a macro may

d i rectly or i n d i rectly call itself. Care must be taken so that s u c h a "recu rsive
mac ro" does not c a l l itself i ndef i n itely.

Macros can be u sed to gene rate many copies of a proced u re with different internal
consta nts, o r in conju nction with VF D to assemble fancy mac h i n e op c odes (see
V F D pseudo-op). There a re many other potential uses for macros; these examples
are o n l y i ntended to demonstrate some of these uses.

Example:

One way to f i n d the number of bits needed to conta i n a va l u e is to compute the

logarithm base 2 of the val ue. To do that at assembly time, we can use recu rsive
macro c a l l s to ac hieve a loo p i n g effect. N ote that the condition tested on VAL en­
su res that the series of nested ca lls must eventu a l l y term i nate.

COM P U T E SYM = Log 2

LOG 2 : MAC RO SYM,VAL
IF [%2] > 1
LOG2 %1 ,[%2]/2
%1 : SET %1 + 1
E LS E
%1 : SET 0
ENDIF
E N DM

Example:

;mac ro to take the high n i b b l e f rom a memory location

;and the l ow n i b b l e f rom the acc umulator, storing the
;res ult i n the accumul ator

N P ACK: MAC RO ADDR

EOR %1
AND #OF
EOR %1
E N DM

Example:

I t is sometimes necessary to be able to c reate a symbol name that is d ifferent for

each call of a macro. T he %K implicit parameter featu re provides the mea ns to do
this. In the f o l l owing mac ro, a u n iq u e jump-target l abel is c reated o n each c a l l .
N ote that all the labe ls begin with the ? character s o that they w i l l not c l u tter u p
the symbol table map.

Set accumu l ator = 0 if sign bit is set.

PARVA L : MACRO
BMI ?%k
LOA #0
?%K:
E N DM

34 Pseudo-Operations
ORC ORIGIN COUNTER

LABEL: ORG < exp1 6 >

where: < exp1 6 > any abso l u te, prev i o u s l y defined 1 6-bit
v a l u e or expression

O RG sets the add ress of the f i rst byte of a piece of code (or data) to a physical loca­
tion in memory.

The label f i eld is sig n i f i cant; it wil l address the v a l u e of * L, before < exp1 6 > is
eva l u ated .

The O RG command can be used i n a program as often as des i red . O RG c a n n ot

c h ange the c u rrent U S E b l o c k . (See U S E pseudo-op.) O RG c hanges the b l oc k­
rel ative v a l u e of the or igin and location counters of the c u r rent U S E b l o c k .

O RG is a lmost a l ways used a t t h e begin ning of a n assembly t o def ine the starting
pos ition in memory of the res u l tant code. If not exp l i cit ly set by ORG (or the 0 =
comma nd- line parameter), the defa u l t v a l u e of the origin and location cou nters is
zero.

Example:

PROG : ORG $1 00 ;Assemble at location $01 00

SOC K : ORG *O ;assign * O to * O and * L

PROC... EPROC DEFINE LOCAL SYMBOL RANGE

LA B E L : PROC
< body >
E PROC

PROC te l l s the assembler that the fol lowing code is a proced u re that may contain
local symbols. A l o c a l symbol is a symbol that begins with a c o l o n (:). It does not
appear in the c ross-reference map and c a n n ot be referenced ou tside of the PROC
range.

The l a be l field is significant; it addresses the value of the * O cou nter when the
PROC statement is processed.

PROC shou l d be the first instruction of any proced u re that contains l oc a l symbol s .

A PROC i s terminated b y E PROC or the next PROC.

When assembling l a rge programs w here symbol table space is at a premi um, l ocal
symbo l s can be used w henever appropriate to red u c e memory req uirements.

Example:

I N I T: PROC ;proced u re
LOA #0 ; let A = O
LOY #0 ; Y indexes t h rough memory
: Loop: STA ( B E G M E M),Y ; : Loop: is l o c a l symbol
I NY ;-won't appear in c ross- reference
BN E : LOOP ;Write 256 l ocations

Pseudo-Operations 35
REAL6 DEFINE REAL NUMBER VALUE

LA B E L : R E AL6 < f pnum >

w here: < f pnum > is a f l oating point number

R E AL6 prov ides c onstant conversion into 6-byte real numbers as supported by the
AT A R I operating system.

The l a bel is s ig n i f i cant because it denotes the starting location of 6 bytes of the
converted number.

Example:

Pl: R E AL6 3.1 41 59

S ET DEFINE VALUE FOR SYMBOL

LA B E L: SET < exp >

where: < exp > = numeric express ion

The S E T pseudo-op defines a symbol to a va lue representing the 1 6-bit expression

of the operand f ie l d . SET works just l i ke EQU, except that LA B E Ls defined with S E T
may b e redefined .

The expression i n the variable fie ld must be an absolute value at the time of
eva luation . Any symbols used must have been previous ly def i ned.

Example:

TSTVAL SET 027 h

DB TSTVAL

TSTVAL SET 099h

T STVAL SET 063h

S PACE OUTPUT BLANK LINES TO LISTING

iglab S PAC E < exp1 >

iglab S PA C E < exp1 > , < exp2 >

where: < exp1 > , < exp2 > = unsigned, numeric expressions

S PA C E p l aces blank lines in a listi ng. I f S PA C E has one argument, it wil l output that
many b l a n k lines o n l y if doing so w i l l not exceed the length of the current page. I f
< exp1 > l i nes wil l not f i t on the current page, SPACE wil l force a n E J E CT.

36 Pseudo-Operations
 If S PAC E has two arguments, they a re both eva luated and < exp1 > b l a n k l i nes w i l l
be p l aced i n the (currently on) list ing only if the current page wil I have < exp2 >
l i nes l eft afterwards. I f the current page does not have that suff ic ient room, S PA C E
wil l force a n E J E CT.

S PAC E is useful when inserted just before a sma l l procedure if X i s the l ength of the
p rocedure (X lines),

S PAC E 4,X
< procedure >

w i l l output 4 l i nes to the l isting if the procedure w i l l sti l l fit on the current page. I f
the spac i ng a n d the p rocedure wil l not f i t on the current page, S PA C E w i l l force a n
EJ ECT.

SU BTTL DEFINE SECON D LINE O F OUTPUT LISTING

ig l a b S U BTTL < string >

w here: < string > = any string u p to 32 c ha racters

S U BTT L al l ows you to s pecify second ary tit l e information. S U BTTL without a
< string > a rgume nt is ignored. To erase the current subtitle, use an empty string.

Example:

T I TLE 'Section 8 - Pseudo-Ops'

S U BTTL 'SU BTTL syntax and descri ption'
S U BTTL ' ' ; erase current subtit le

TITLE DEFINE FIRST LINE OF OUTPUT LISTING

ig l a b T I T L E < string >

w here: < stri ng > = any string up to 32 c ha racters

T I T L E a l l ows you to set/reset the assemb l er's internal page-head ing string. T I T L E
w ith a string argument wil l place that str i ng i n the page header (see "Sample
Listi ng," Section 3). If the str i ng contains zero c h a racters, the page header is reset
to empty. T I T L E without a string a rgument does not a l ter the current page header.

The f i rst c a l l to T I T L E * wil l not eject a listi ng page; suc cess ive c a l l s w i l l always
force an E J E CT after any arguments are processed .

T I T L E is commo n l y pl aced at the begin n i ng of each file used in an assembly. E ac h

linked f i l e wil l begin assembly on a f res h page, topped w i t h an appropriate header
·

to des c ribe its general contents.

Example:

TITLE 'XO N C . asm - I nterface Subroutines.'

Pseudo-Operat ions 37
USE DEFINE BLOCK AREA

iglab USE name

U S E esta b l ishes a new " U S E b l ock" or res u m es use of a prev i o u s l y esta b l ished
b l o c k . The block in use is the block i nto w h i c h code is su bsequently assemb led. A
p rogram may conta i n u p to 60 d i fferent U S E blocks. The assem b l e r is respo n s i b l e
for computing t h e length and actu al o r i g i n o f e a c h b l o c k . O r i g i n s a r e assigned to
each b l oc k in the order they are f i rst encountered.

Asso c i ated with each USE block are regi sters to m a i ntain the last v a l ues of the
o r i g i n and pos ition counters ( * 0 and * P). See O RC and VFD for a description of
those cou nters. I n it i a l ly, the va l u es of these cou nters defa u l t to zero for each U S E
b l oc k . T h e v a l u e of t he location c o u n ter (* L) is not saved, b u t set eq u a l t o the v a l u e
of the o r i g i n cou nter. I f a L O C h a d been i n effect prev i o u s ly, resett i n g of the loca­
tion cou nter to prod u ce the desired res u l ts is the respon s i b i l i ty of the programmer.

USE a l l ows the programmer to specify consecu tive pieces of code i n d i scontiguous
source segments. It i s more conven ient than using ORC .

Example:

USE BTA B L ;(at beg i n n i n g of program)

BTA B L : ;define base of j u m p vector
USE * ;(retu rn to norm a l org)

NXLAB: L OX Someth i n g
USE BTA B L
DW NXLAB ;add address to j u m p vector
USE *
STX Addr ; more

USE BTA B L ;(at end of program)

DW 0 ; m ark end of vector
USE *
END

VFD VARIABLE FIELD DEFINITION

LA B E L: VFD < Fexp > \ < exp > , . . . , < Fexp > \ < exp >

w here: 1 < < Fexp > <

= 16 =

< exp > any n u m e r i c express ion

=

VFD defi nes variable f ields. E ac h < Fexp > denotes a f i e l d width. E ac h < exp >
denotes an express ion to be p l aced i nto that f ie l d; < exp > val u es that exceed the i r
asso c i ate < Fexp > f ie l d w i d t h va l u es a r e tru n cated t o m a t c h t h e < Fexp > v a l ue.

N egative v a l ues a re eva l u ated w ith u n s i gned twos-comp lement arithmetic. For ex­
a m p l e , -32768 is 32768 and -1 w i l l be represented by 65 535 . The resu ltant val ues are
tru n cated to match the < Fexp > f i e l d width.

38 Pseudo-Operations
V F D m a n ipu l ates the pos ition cou nter (* Pl to keep track of the bits rem a i n i ng i n a
byte at the end of a V F D pseudo-op. I f the next pseudo-op en c o u n tered is a nother
V F D , the next f i e l d generated w i l l beg i n with the u n used b its left in the c u rrent
byte. If the next code-generat ing pseudo-op is not V F D, the assem b l e r w i l l pad out
the u n u sed byte f ield with zeros.

V F D a l l ows you to specify arb itrar i l y c o m p l ex data fields without regard to byte or
word boundaries.

Example:

M V I N ST : V F D 2 \01 , 3 \ D DD,3\SSS

VFD can be used t h i s way i nside MACRO-E N DM constru cts to assem b l e code for
unusual processors, spec i a l peri pheral c h i ps, and so forth.

Example:

SPEC: VFD 7\ @43,9 \ 1 '&&'

VFD 1 3 \$429

S P E C is a l a bel point to a 29-b it field def i n ition. The f i rst 7 b its conta i n the va l u e 43
octa l . The next 9 b its conta i n the tru n cated string &&. The next 1 3 b its conta i n the
va l u e 429 hexadec i m a l . The * P cou nter c u rrently poi nts i nto the fourth byte after
S P E C , with 3 bits l eft in the c u rrent byte .

Pseudo-Operations 39
 7

PSEUDO-OP QUICK REFERENCE

iglab A SS E RT < exp > ;Check asse m b l y condition

LA B E L: DB < exp > , < exp > ; Define bytes
LA B E L : DB ' A BC D E ','f',$00 ; Define long strings
LA B E L: DC 'ABCDE' ; D B with 80h added onto the last byte
LA B E L: OS < exp > ; Define space
LA B E L: ow < exp > , < exp > ; Define words
LA B E L: ow 'Xu',1 2 34,'y' ; Define 1- o r 2-c haracter strings
LA B E L : ECHO < ex p > ; D u pl icate code < exp > times
iglab E J E CT ; Page eject
iglab E LS E ; P a rt of conditional assembly
LA B E L : END [exp] ; E nd of asse m b l y
iglab ENDIF ;Termi nate range of I F
iglab E N DM ;Termi nate MACRO o r E C H O
iglab E P ROC ;Termi nates l oc a l symbol range
LA B E L : EQU < exp > ; Define L A B E L eq u a l s < exp >
iglab E RR ; Force error f l ag
iglab IF < exp > ; Begin conditional assem bly
LA B E L : I NCLUDE < f i lespec > ; I n c l ude a nother sou rce f i l e
iglab LINK < f i lespec > ; I nc l ude a nother sou rce f i l e
a t the e n d o f this sou rce f i l e
iglab L I ST < opt > ; < opt > = I i s t control option
iglab L I ST *
; Pop I ist control stack
LA B E L : LOC < exp > ;Set l ocation cou nter
N AM E : MACRO < pa rms > ; Begin m a c ro def i n ition
LA B E L : ORG < exp > ; Set o r i g i n cou nter
LA B E L : PROC ; Begin l o c a l symbol range
LA B E L : R E AL6 < exp > ;6-byte real constant conversion
LA B E L : SET < exp > ; Reset LA B E L to < exp >
iglab SPACE < exp1 > , < exp2 > ; S pace < exp1 > l i nes if < exp2 > l i nes
l eft on this page
iglab S U BTTL 'text' ; Set l isting s u btitle
iglab TITLE 'text' ; Set l isting title
iglab USE < name > ; U se b l oc k d e c l a ration
LA B E L : VFD < exp > < exp > , . . ;Variable field def i n ition
LA B E L : < exp > ;Synonym for E Q U

< exp > = req u i red express ion

[exp] = optional express ion
'text' = stri ngs
< f i l espec > = < device > : < f i lename > . < extens i o n >
i g l ab = i gnored l abel

Pseudo-Op Quick Reference 41

 8

INSTRUCTION MNEMONICS

T he i nstru ction m ne m o n i cs prov ided by the M a c ro Assem b l e r are identical to the

sta ndard m ne m o n i cs defined by MOS Technol ogy, with these except ions:

• Q u otation marks denoting character str i ngs m u st be properly paired . (Some

6502 assem b l ers a l l ow an u nterm i nated q u ote for a 1 -c ha racter string.)
• In this assem bl er, the sym bols < and > a re b i n ary operators ( l ess than and
greater than). Some 6502 asse m b l ers define these sym bols as u n ary operators
(high and l ow). See Section 4 for operator def i n itions.

Examples:

AMAC MOS
CMP #' ? ' CMP #' ?
L OX #high E X P LOX # > EXP
L OY # l ow E X P LOY # < EXP

Notation

dd B-bit. s igned d i s p l acement:

-1 2B < = dd < = + 1 2 7
mmmm 1 6-bit address express ion
nn B-bit constant: 0 < = n n < = 2 5 5
rel 1 6-bit add ress with i n :
*-1 26 < = re l < = * + 1 29
zz Page 0 location: 0 < = zz < = 255

HEX OP CODE ADDRESS REMARKS

DATA MOV E M E N T

Regi ster to regi ster transfer.

AA TAX ;Tra nsfer A to X
AB TAY ; T ransfer A to Y
BA TSX ; T ra nsfe r S to X
BA TXA ; T ra nsfer X to A
9A TXS ;Transfer X to S
9B TYA ; Transfer Y to A

Load constant i nto register.

A9 L OA #nn
A2 L OX #nn
AO L OY #nn

Instruction Mnemonics 43
 Load regi ster from memory.
AS LOA zz
BS L OA zz,X
A1 LOA (zz,X)
B1 L OA (zz),Y
AD LOA mmmm
BO LOA m m m m,X
B9 LOA mmmm,Y
A6 LOX zz
B6 L OX zz,Y
AE L OX mmmm
BE LOX m m m m,Y
A4 L OY zz
B4 LOY zz,X
AC LOY mmmm
BC L OY mm mm,X

Store register i nto mem ory.

BS STA zz
9S STA zz,X
B1 STA (zz,X)
91 STA (zz),Y
BD STA mmmm
90 STA m m m m,X
99 STA mm mm,Y
B6 STX zz
96 STX zz,Y
BE STX mmmm
B4 STY zz
94 STY zz,X
BC STY mmmm

Stack l oad/stores.
4B PHA ; Pu s h acc u m u l ator
OB PHP ; P u s h processor status
6B PLA ; Pop a c cu m u l ator
2B PLP ; Pop processor status

DYA D I C A R I T H M E T I C

A d d operand a n d carry.
69 ADC #nn
6S ADC zz
7S ADC zz,X
61 ADC (zz,X)
71 ADC (zz),Y
60 ADC mmmm
70 ADC m m m m, X
79 ADC mm mm,Y

44 Instruction Mnemonics
 S u btract operand and borrow.
E9 S BC #nn
ES S BC zz
FS S BC zz,X
E1 S BC (zz,X)
F1 S BC (z z),Y
ED S BC mmmm
FD S BC mmmm,X
F9 S BC m m m m ,Y

Com pare B-bit operand with acc u m u l ator.

Set f l ags as if su btracting, but do not a l ter acc u m u l ator.
C9 CMP #nn
cs CMP zz
DS CMP zz,X
C1 CMP (z z,X)
D1 CMP (zz),Y
CD CMP mmmm
DD CMP mmmm,X
D9 CMP m m m m ,Y

Com pare B-bit operand with i ndex register.

EO CPX #nn
E4 C PX zz
EC C PX mmmm
co CPY #nn
C4 CPY zz
cc CPY mmmm

MONAD I C ARITHMETIC

Decrement b y 1.
C6 DEC zz
D6 DEC zz,X
CE DEC mmmm
DE DEC mmmm,X
CA DEX
BB DEY

I nc rement b y 1.
E6 I NC zz
F6 I NC zz,X
EE I NC mmmm
FE I NC mmmm,X
EB I NX
CB I NY

Arithmetic contro l .
1B CLC ;C lear carry f l ag
DB CLD ;C lear dec i ma l m ode
BB CLY ; Set overf l ow f l ag
3B SEC ; Set c a r ry f l ag
F8 SED ; Set d e c i m a l mode

Ins truction Mnemonics 45

 DYA D I C LOG I CA L/ BOO L E A N O P E RAT I O N S

8-b i t logical prod u ct, c o n j u n ction.

29 AN D #nn
25 AND zz
35 AN D zz,X
21 AND (zz, X)
31 AN D (zz),Y
2D AND mmmm
3D AN D mmmm,X
39 AND mmmm,Y

Log ical s u m , d i sj u n ction, i n c l u sive O R .

09 ORA #nn
05 O RA zz
15 ORA zz,X
01 O RA (zz,X)
11 O RA (zz),Y
OD ORA mmmm
1D O RA mmmm,X
19 ORA m m m m, Y

Log i c a l d i fference, i n eq u ivalence, exc l u s ive O R .

49 E OR #nn
45 EOR zz
55 EOR zz,X
41 EOR (zz, X)
51 EOR (zz),Y
4D EOR mmm m
SD EOR m m m m, X
59 EOR mmmm,Y

Logical com pare.

Set fl ags as fol l ows:
Z = 1 i f A A N D mem = 0
Z = O if A A N D mem = 1
S = bit 7 of mem
V = bit 6 of mem
(mem mmmm or z z).

24 BIT zz
2C BIT mmmm

ROTAT E A N D S H I FT

Arithmetic sh ift l eft.

OA ASL A
06 ASL zz
16 ASL zz,X
OE ASL mmmm
1E ASL mmmm,X

46 Instruction Mnemonics
 Log ical s h ift right.
4A LSR A
46 LSR zz
56 LSR zz,X
4E LSR mmmm
SE LSR mmmm,X

Rotate left.
2A ROL A
26 ROL zz
36 ROL zz,X
2E ROL mmmm
3E ROL mmmm,X

Rotate right.
6A RO R A
66 RO R zz
76 ROR zz,X
6E ROR mmmm
7E ROR mmmm,X

J U M PS
90 BCC ;If ca rry c l ear
BO BCS ;If carry set
FO BEQ ;If eq u a l ( = O)
30 BMI ;If m inus
DO BN E ;If n o t eq u a l ( < > 0)
10 BPL ;If plus
50 BVC ;If overf l ow c l ear
70 BVS ;If overflow set
4C JMP mmmm
6C JMP ( m m mm)

C A L L S U BROU T I N E
00 BRK ; Software i nterru pt
20 JSR mmmm ; J u m p su brou t i n e

R E T U R N FROM S U BROU T I N E
40 RTI ; Retu rn f rom i nterrupt
60 RTS ; R et u r n f rom s u b routi ne

M I SC E L L A N E O U S C P U CONTROL
58 CLI ;Clear interrupt mask ( E I )
EA NOP
78 SE I ; Set i n terrupt mask ( D I )

Instruction Mnemonics 47
 9

USING T H E ATARI MACRO ASS E M BL E R

WIT H T H E ATARI ASS E M BL E R E DITO R
SOURC E FIL E S

I f you have a source p rogram that has been devel oped u s i n g the AT A R I Asse m b l e r
E d i to r c a rtridge, and y o u w a n t t o use t h e Macro Asse m b l e r t o assem b l e i t , y o u w i l l
have t o b e aware o f the f o l l ow i n g d ifferen ces:

• The Macro Asse m b l e r does not accept l i ne n u m bers.

• The = for E Q U m u st be em bedded between at l east two b l a n ks.
• Comments m ust be preceded by a sem i c o l o n .
• The fo l l owing pseudo-ops are recogn ized by the Macro Assem bl er:
. BYTE is eq u ival ent to D B
. E N D is eq u ival ent t o E N D
. PAC E i s eq u ivalent to T I T L E
. S K I P is eq u ival ent to S PA C E
. WO R D is eq u ivalent t o DW
• T he fo l l ow i ng are not recognized by the Macro Assem b ler:
BYTE
WORD
• The Macro Asse m b l e r d oes not recogn ize * = for sett i n g the origin c o u n te r;
use ORC inste a d .
• A l l stri ngs m u st b e bracketed b y q u otat ion m a rks ( " ) for t h e Macro
Asse m b ler to interpret them properly.

Using the A TA R I Macro Assembler with the A TAR I Assembler Editor Source Files 49
 10

ER RO R CODES

E rrors a re f l agged by a s i ng l e-letter code i n c o l u m n one of the output l isti ng. L i nes
conta i n i ng errors are a lways wri tten to the screen, regard l ess of the output sel ec­
tion.

A Add ress error. I nstru ction spec if ied does not su pport the addres s i n g m ode
specif ied.

D D u p l icate l a bel error. The last one defined is used.

E E xpress ion error. An express ion on the sou rce l i ne i n the add ress f ield is
u n recogn izable.

F B ad nest i ng of control statements. Bad nesti ng of I F . . . E LS E . . . E N D I F

statements. When this occu rs o n the E N D l i ne, i t means a n I F was not ter­
m i nated.

I nstru ction f ield not recogn ized. T h ree N O P bytes a re gene rated .

L Label field not recogn ized. T hree N O P bytes are generated.

M MACRO statement error. I m proper macro def i n i tion.

N E rror in n u m ber: d igit exceeds rad ix; v a l u e exceeds 1 6 b its, and so forth.

0 Stack table overf l ow occu rred i n eva l u at i n g expression; user s h o u l d

s i m p l ify expression. T o o many L I N K f i l es. T o o many PROCs. T o o m a ny
U S E b l ocks.

P P rogrammer-fo rced error. See A SS E RT and E R R pseudo-ops.

R E xpress ion i n variable f i e l d not computable.

S Syntax error i n statement. Too many or too few add ress s u bf ie l d s .

U Reference to an u ndefi ned sym bo l .

V E xpress ion overf l ow: res u l tant v a l u e is tru n cated.

W N ot w ith i n V F D f ield width (1 < = width < = 1 6).

Y M i s p l aced instruction: extraneous E N DM . When t h i s o c c u rs on the E N D

l i ne, i t means a MACRO o r E C H O was not term i n ated . Make s u re that
E N OM is preceded by a tab (..,.. ) c haracter.

Error Codes 51
 LIMITED 90-DAY WARRANTY
ON ATARI® HOME COMPUTE R PRODUCTS

ATARI, INC ("ATA R I " ) warrants to the original consumer purchaser that this ATA RI Home Computer Product (not i nc l ud i n g computer pro­
grams) shall be free from any defects in material or workmansh i p for a period of 90 days from the date of purchase. If any such defect is
d i scovered wit h i n the warranty period, ATA R l ' s sole obligation w i l l be to repa i r or replace, at its election, the Computer Product free of
charge on receipt of the unit (charges prepaid, if mai led or s h i pped) with proof of date of purchase sati sfactory to ATAR I at any authorized
ATARI Computer Service Center. For the location of an authorized ATA RI Computer Service Center nea rest you,

call toll-free: In California (800) 672-1 430 or write to: Atari, I nc.
Continental U . S . (800) 538-8737 Customer Service/Field Su pport
1 340 Bordeaux Drive
S u n nyvale, CA 94086

YOU MUST RETURN DEFECTIVE COMPUTER PRODUCTS TO AN AUTHORIZED ATARI COMPUTER S E RV I C E C E NTER FOR I N ­
WARRANTY REPA I R.

This warranty shall not apply if the Computer Product: (i) has been m i sused or shows signs of excessive wear, (i i ) has been damaged by be­
i ng used with any products not supplied by ATA R I , or ( i i i ) has been damaged by being serviced or modified by anyone other than a n
authorized ATARI Computer Service Center.

ANY APPLICABLE I M P L I E D WARRANTIES, I N C LU D I NG WARRANTI ES OF M E RC H A NTA B I L ITY A N D FITNESS FOR A PARTICU LAR PU R­
POSE, ARE H EREBY LIMITED TO N I N ETY DAYS FROM T H E DATE OF PU RCHASE. CON S EQU ENTIAL OR I NC I D E NTAL DAMAG ES
RESULTING FROM A BREACH OF ANY APPLICABLE EXPRESS O R I M P L I E D WARRANTIES ARE H E REBY EXC L U D E D . Some states do not
a l low l i m itations on how long an i m p l i ed warranty lasts or do not a l l ow the exclusion or l i m itation of i ncidental or consequential damages,
so the above l i m itations or exclusions may not apply to you.

This warranty gives you specific legal rights and you may also have other rights which vary from state to state.

DISCLAIME R OR WARRANTY
ON ATARI COMPUTER PROGRAMS

A l l ATARI computer programs are d i stri buted on an "as is" basis without warranty of any ki n d . The entire risk as to the qual ity and perfor­
mance of such programs is with the purchaser. Should the programs prove defective following t he i r p u rchase, the purchaser and not the
man ufacturer, distributor, or reta i l er assumes the entire cost of a l l necessary servicing or repa i r .

ATARI shall have no liabi l ity or responsi bil ity to a p u rchaser, customer, or any other person or entity with respect to any l i abil ity, loss, o r
damage caused d i rectly or i n d i rectly b y computer programs sold b y ATA R I . T h i s d i sc l a i m e r i nc l udes b u t i s not l i m ited to any i nterruption of
service, loss of busi ness or antici patory profits, or consequential damages resulting from the use or operation of such computer programs.

RE PA I R SERVICE

If your ATARI Home Computer Product req ui res repa i r other than under warranty, please contact your local authorized ATAR I Computer
Service Center for repa i r i nformation.

IMPORTANT: If you ship your ATA RI Home Computer Prod uct, package it securely and ship it, cha rges prepaid and i ns u red, by parcel post
or U n ited Parcel Service.