PROGRAMMING IN ASSEMBLY LANGUAGE WITH KYAN PASCAL
by John R. Fachini

This installment of the assembly language column marks a change in the
direction the column will be taking.  Instead of trying to make half of each
column for beginners and half for more advanced users, I'm going to select a
topic of interest each issue and investigate exactly what's what with it.
Usually both novices and experienced programmers will benefit.  I don't mean to
leave the beginners out in the cold; this column, in a bi-monthly format, is
too short to teach beginners anything they can't learn from a good 6502 book.
I will, however, do my best to answer questions concerning the Kyan assembler
and compiler if you write.

The topic I've chosen for this issue was suggested by Tom Osber in San
Francisco, California.  He wanted to know about the AS (6502 assembler) that is
provided with the Kyan Pascal 2.0 package.  This discussion will include
working examples of assembler directives and macros also.  

The Kyan AS (6502 assembler) provided with Kyan Pascal 2.0 is included as part
of the package for two reasons.

	1.  To permit the programmer to include assembly code in Pascal sources, so
	that after the compiler has generated its macros, everything can be assembled
	into machine language.

	2.  To provide the user with a stand-alone, high power, easy-to-use assembler
	which adds to the programming capability with version 2.0.

In a future column we'll look at exactly how the compiler generates the macros
which represent your Pascal program; for now we'll pursue using the assembler
as a stand-alone facility.

At this point I'm going to assume a couple of things:  first, that you are
familiar with assembly code, and second, that you are familiar with some of the
terminology associated with assemblers.  If you're not, get out your Kyan
Pascal 2.0 manual and read Chapter V.

In any stand-along application, the assembler must first know the address of
where the program will be loaded and executed.  This is accomplished using the
ORG statement:

	ORG $800	;Program will load and run at memory location $800.

(Remember that only labels can start in column 1.)  The ORG has told the
assembler to generate machine code that will execute starting at $800 in main
memory.  The remark to the right of the ORG statement is separated by a
semi-colon (;).  This is a good programming practice:  always remark code,
especially code that is special purpose.

I said a second ago only labels can go in column 1.  True and false.  Remarks
can also go in column 1, as long as they start with a semi-colon.  Some
assemblers use an asterisk (*) in column 1 to represent a remark.  We use the
asterisk for something more important than that.  Remember:  only semi-colons
are used to protect remarks.

The next directive of interest is the EQU directive.  EQU assigns values to
labels.  Very often this makes for very easy reading of assembly language
programs.  For example, compare the next two lines:

	JSR $E456		;Call central I/O vector 

	JSR CIOV		;Same as above

Obviously CIOV is a lot more obvious than "$E456".  There's another good reason
for using labels in your program.  If you decide to move your assembly code to
another operating system, you only have to change one label definition and
re-assemble your source code.  If you reference memory locations by address
(ex. $E456), you'll have to change every reference to it before moving your
code to another system.

Note:  labels can be any length, but only the first 6 characters have
"significance".  For example, the labels "FlagItDone" and "FlagItUndone" are
considered the same by AS since "FlagIt" appears in both.  The assembler also
ignores the cases of characters, i.e., "XYZ" is the same label as "xyz".

The next two directives are used when you need to generate tables of bytes or
words in your assembly language code.  Observe:

Data 	DB    	1,2,3,4,5
           	DW     	$4000,CIOV

The "Data Byte" (DB) and "Data Word" (DW) directives generate bytes in memory
according to what follows.  The above declarations would generate the following
bytes at memory location "Data":

Data:	1     2     3     4     5     00     $40     $56     $E4

Notice that the "word" (2 byte) definitions are generated lo byte, hi byte.
This convention is used on the 6502 micro processor and subsequently is
maintained by the assembler whenever words are generated.

At times, it is necessary to know the lo byte or the hi byte of a label value.
This can be done using the >,<, and # directives:

	LDX #>CIOV		;Load X with #$56 (lo byte)
	LDY #<CIOV		;Load Y with #$E4 (hi byte)

The "Data Storage" (DS) directive will reserve the number of bytes indicated in
the object file.  For example:

	DS   6

will skip 6 bytes in the object file being generated.

The next two directives allow you to generate character codes as tables in
memory.  They are "ASCii" (ASC) and "STRing" (STR).  These directives perform
the same operation with one exception:  the string declared by STR starts with
a length byte (the number of characters in the string); ASC defines one byte
per character but does not generate a length byte.  For example:

Info ASC 'HELLO'		;Generate 5 bytes corresponding to the
				;ascii codes of the characters HELLO

More STR 'HELLO'		;Generate 6 bytes:
				;          first byte = 5
				;remaining 5 bytes are the ascii codes of the
				;characters HELLO

Another important assembler character is the * (asterisk).  The asterisk
represents the 'current value of the assembler's program counter'.  In other
words, the * represents the hexidecimal value of the memory location in which
the next instruction generated by the assembler will be put.  The initial value
of the * is set by the ORG directive.

The last directive we'll talk about in this issue is the MACRO directive.
Macros are code segments which can be installed in the source code by
referencing the macro name instead of typing the lines of code the macro is
defined as.  Another powerful feature of macros is their parameter passing
ability.  You can define a macro and use "parameters" to make the macro code
being generated specific to the memory locations or labels you need to
reference in "this" case of the macro in memory.  For example:

PrtChar		MACRO		;print a character
		LDA #&1		;Load A with first parameter in macro list
		ORA #$80
		JSR Cout
		ENDM			;Mark END-of-Macro

The "&1" represents the first parameter in the list used by the assembly code
source.  In the program, saying:

	PrtChar A

would generate assembly code as follows:

	LDA #A
	ORA #$80
	JSR Cout

Remember that Macros are NOT subroutines!!!!!!  They are intended to save you
typing if the same code is used many times.

There are more directives to be discussed, but these are enough to digest for
now.  Good luck.