home *** CD-ROM | disk | FTP | other *** search
/ ftp.barnyard.co.uk / 2015.02.ftp.barnyard.co.uk.tar / ftp.barnyard.co.uk / cpm / walnut-creek-CDROM / BEEHIVE / OS / SUPRDOS2.ARC / ZASM.DOC < prev   
Text File  |  1990-09-21  |  25KB  |  703 lines
  1. Documentation for Z80MR
  2.  
  3.  
  4. Introduction
  5.  
  6. Z80MR is a Z80 macro assembler with syntax closely following RMAC and MAC.
  7. It assembles standard Z80 mnemonics into an Intel Hex format. The resulting
  8. file (which has a .HEX extension) can be translated to a .COM file with
  9. LOAD.COM (on your CP/M disk that you received with your Kaypro) if it ORG's
  10. at 100 (hex). If it ORG's elsewhere the .HEX file may be read into memory
  11. and manipulated with DDT.COM.
  12.  
  13. Running Z80MR
  14.  
  15. The file to be assembled must have the extent *.AZM.  The syntax to
  16. load the assembler is Z80MR <filename> without the extent.
  17.  
  18. Why Z80
  19.  
  20. The assembler you received with your Kaypro (ASM.COM) is an 8080 assembler.
  21. The Kaypro actually runs a Z80 c.p.u. The reason this is possible is that
  22. the Z80 actually runs all of the 8080 instructions but in addition there
  23. are more instructions unknown to the 8080. The extra instructions were 
  24. designed for increased speed, easier programming, and more compact code.
  25. For this reason it is to your best advantage to program in Z80 code for
  26. the Kaypro.
  27.  
  28. Z80 Mnemonics
  29.  
  30. Z80 mnemonics are a great improvement to 8080. Thought was given to
  31. logical, universal mnemonics that are much easier to remember and use. I
  32. learned assembly language on the 8080 and resisted the change to Z80 at
  33. first. But after using Z80 mnemonics for a short time I became very
  34. unwilling to  do anything with 8080 code. Now I run almost every 8080
  35. program that comes in through a 8080 to Z80 translating program
  36. (XLATE2.COM). Even if you are writing programs for the 8080 it is still far
  37. easier to  write in Z80 mnemonics. There is a special listing command that
  38. flags Z80- only instructions for this very reason (described later). 
  39.  
  40. Macros
  41.  
  42. Macros are a way of writing subroutines in assembly language and then 
  43. calling the subroutine by entering the 'macro name' into the source. The
  44. macro may be called as many times as necessary anywhere in the program.
  45. When the assembler is operated, the lines of source code that make up the
  46. macro will be inserted into the file by the assembler. Note that using
  47. a macro does not reduce the size of the object code that is produced since
  48. all the lines of code that make up the macro definition are assembled into
  49. the object file at assembly time. This is called expanding the macro. By
  50. using the *MACLIST ON option, the lines of code produced by the expansion
  51. of a macro are listed in the .PRN file. Then the code can be examined and
  52. at times optimized in certain locations. 
  53.  
  54.  
  55. Assembler Syntax
  56.  
  57.  
  58. Components and General Form of Assembly Language Programs
  59.  
  60. The structure of an assembly language program is more important to an
  61. assembler than the actual instructions you write. A program that would run
  62. beautifully can fail to assemble if the syntax is not correct. A program
  63. with no errors at assembly time is not guaranteed to run correctly ( or as
  64. expected ). The assemblers report of 0 errors means that it understood all
  65. of the instructions you entered, not that your program is logically correct.
  66.  
  67. Fields
  68.  
  69. Assemblers are almost always field oriented some to a greater degree than
  70. others. A field is a flexible position in the line of code with respect to
  71. the right margin. This assembler recognizes 4 fields in an assembly language
  72. source line.
  73.  
  74.  
  75. label        operation    operand         comment
  76.  
  77.  
  78. The assembler knows when it has reached the end of a field when it sees a
  79. 'field delimiter'. This can be a space or a tab for this assembler though
  80. some require tabs so it is a good habit to always use tab characters as
  81. delimiters.
  82.  
  83. Label Field
  84.  
  85. A symbol is a word used to represent a number. Symbols that refer to 
  86. addresses are called labels. The assignment of a number to a label can
  87. either be defined as the lines below
  88.  
  89. TEN    EQU    10
  90. START    EQU    100H
  91.  
  92. or calculated by the assembler as an address for branching instructions.
  93.  
  94. START:    JP    FINISH
  95.     NOP
  96.     NOP
  97. FINISH:    JP    START
  98.  
  99. Also notice that the label is optional and is only for the programmers
  100. conveniance.
  101.  
  102. Labels must appear in the label field. Some assemblers allow you to indent
  103. labels but this one won't.
  104.  
  105.  
  106.     START    EQU    100H
  107. START:    JP    FINISH 
  108.  
  109. Will give you a problem. The EQU must be in the operation field and the
  110. label in the label field.
  111.  
  112. Most assemblers require that the undefined labels be terminated in a
  113. colon but this assembler does not require a colon for symbols in column 1.
  114.  
  115. START    JP    FINISH
  116.  
  117. will not generate an error but colons are another good habit and also
  118. make your code more readable.
  119.  
  120. This assembler only examines the first six characters of any label or symbol
  121. so that if the following labels were used in the same program
  122.  
  123. FINISH1    EQU    1000H
  124. FINISH2    EQU    2000H
  125.  
  126. A 'D' error (duplicate symbols) would be generated.
  127.  
  128. Operation and Operand Fields
  129.  
  130. The operation field follows the label field and may either contain a Z80
  131. op code mnemonic, an assembler directive (or pseudo op), or a macro call.
  132. Assembler directives and macros are described later in this file. This
  133. field will usally contain the mnemonic for a Z80 instruction. Some Z80
  134. instructions only use this field while others contain an operand which
  135. will be located in the operand field.
  136.  
  137.  
  138. GOBACK:    OR    A
  139.     RET    Z
  140.     LD    A,0FFH
  141.     RET
  142.  
  143. The way Z80 mnemonics were designed, the number of nmenonics in the operation
  144. portion of instructions is kept to a minimum since the operands really
  145. distinguish the differences between similar instructions. The first line
  146. above is a good example of this. The operation is an 'OR' operation on
  147. the number in the accumulator (implied) with another register. It makes
  148. sense that the operand should be the register containing the other number
  149. in the 'OR' operation. In Z80 assembly language this is the case. The first
  150. line OR's the accumulator with the accumualator (used to see if the
  151. accumulator contains a 0). Notice that the second line uses the operand
  152. field to contain the condition for a conditional jump (in this case the
  153. zero flag). The third line uses the operand field to contain both the
  154. target register for a load and the number to load. The last line is an
  155. unconditional return which uses the same operator (RET) as the conditional
  156. return but does not use the operand field because there are no conditons
  157. to place there. This structure makes Z80 programs much more readable
  158. than 8080 programs as well as making the instructions easier to remember.
  159. The following is the same code written with 8080 mnemonics. Notice the
  160. different philosophy on the use of the fields.
  161.  
  162. GOBACK:    ORA
  163.     RETZ
  164.     MVI    A,0FFH
  165.     RET
  166.  
  167. Also the LD command in the Z80 is used for all data moves while 8080 users
  168. must remember a different mnemonic for different types of moves.
  169.  
  170.     8080            Z80
  171.  
  172.     MOV    H,A        LD    H,A
  173.     MVI    H,00        LD    H,00
  174.     LXI    H,0000        LD    HL,0000
  175.  
  176.  
  177. The Comment Field
  178.  
  179. Comments are not limited to the comment field and can actually be the entire
  180. line. All assemblers recognize the semicolon as the beginning of a comment
  181. and most ignore the rest of the line. For compatability between assemblers
  182. it is a good to begin comments with a semicolon. But for this assembler 
  183. the following methods of inserting comments are good syntax.
  184.  
  185. 1. Beginning a line with an '*' in column one causes the assembler to ignore
  186. therest of the line except if one of the assembler commands (described below)
  187. immediately follows the asterisk (no embedded spaces).
  188.  
  189. 2. A semicolon will cause the assembler to consider everything following it
  190. to be considered a comment.
  191.  
  192. 3. The first blank encountered following the beginning of the operand field
  193. will cause the assembler to consider the rest of the line to be considered
  194. a comment.
  195.  
  196. ******************************************
  197. ;An adventure in Comments
  198. * A short tale
  199.  
  200. START:    JP    FINISH        ; finish this story
  201.     NOP              ASM can't handle this
  202. FINISH: RET     Thats all folks
  203.  
  204. Would assemble with no errors. Comments do not appear in the object code.
  205.  
  206.  
  207. Numbers and Bases
  208.  
  209. The assembler will accept numbers in HEX (base 16) BINARY (base 2) or
  210. DECIMAL. Hex numbers must end with an H and binary numbers must end in
  211. a B. Decimal numbers should have no suffix letter. When a HEX digit begins
  212. with a letter, the letter should be preceded with a 0.
  213.  
  214.     LD    A,0F3H
  215.     OR    01001000B
  216.     LD    HL,4000H+28
  217.         
  218.  
  219.  
  220.  
  221. Commanding the Assembler
  222.  
  223. The primary responsibility of the assembler is to translate Z80 mnemonics
  224. into object code. The assembler also recognizes certain commands and
  225. directives that the programmer can use to manipulate the assembler's output.
  226. These are often referred to as 'pseudo-ops'. This assembler requires these
  227. pseudo-ops to be in upper case.  A description of these commands follows:
  228.  
  229. ORG    <expr>    ; Sets the origin of the code or section of code. Actually
  230.         ; it sets the reference number that the assembler uses to
  231.         ; generate addresses for labels and instructions.
  232.         ; <expr> could be a number or a previously defined symbol.
  233.         ; e.g.    ORG    0
  234.         ;       ORG    START
  235.  
  236. END    <symb>    ; Determines the end of an assembly language program. <symb>
  237.         ; if present describes the first executable instruction of
  238.         ; the program.
  239.  
  240. DW    wordlist
  241. DEFW    wordlist
  242.         ; Both of these have identical meanings. In assembly language
  243.         ; programs, 8 bit values are called bytes and 16 bit
  244.         ; values are called words. Addresses are assembled with the
  245.         ; most significant byte (MSB) following the least significant
  246.         ; byte (LSB) because this is how the microprocessor handles
  247.         ; these values. The DW pseudo-op allows us to describe these
  248.         ; values in the way we are used to (MSB first) and still
  249.         ; assemble correctly for the processor.
  250.         ;    DW    8000H
  251.         ;             will assemble the same as 
  252.         ;    DB    00H
  253.         ;     DB    80H
  254.         ;
  255.         ; If more than one word is to follow a DW following values
  256.         ; should be seperated by commas
  257.         ; e.g.    DW    8000H,0F000H,0000H
  258.         ; The wordlist can also be symbols
  259.         ; e.g.    START:    JP    FINISH
  260.         ;        DW    START,FINISH
  261.         ;      FINISH:    JP    START
  262.  
  263. DDB    wordlist
  264.         ; This pseudo-op is a way of assembling 16 bit values with
  265.         ; the MSB first (opposite of DW).
  266.         ;    DDB    8000H
  267.         ;            will assemble the same as
  268.         ;    DB    80H
  269.         ;    DB    00H
  270.  
  271. DB    bytelist
  272. DEFB    bytelist
  273. DEFM    bytelist
  274. DATA    bytelist
  275.         ; These four pseudo-ops have identical meanings. The bytelist
  276.         ; can be one byte or multiple bytes seperated with commas.
  277.         ; The bytes can be any mix of symbols, ascii characters in
  278.         ; quotes, or numbers on the same line. This is familiar
  279.         ; code in Kaypro programs:
  280.         ;
  281.         ;ESC    EQU    1BH
  282.         ;CLRSCR    EQU    1AH
  283.         ;CRLF    DDB    0D0AH
  284.         ;
  285.         ;    ORG    100H    
  286.         ;
  287.         ;    LD    DE,MES
  288.         ;    LD    C,9
  289.         ;    CALL    5
  290.         ;    RET
  291.         ;
  292.         ;MES:    DB    CLRSCR
  293.         ;    DB       ESC,'=',12+20H,12+20H
  294.         ;    DB    '*Your Message Here *',CRLF
  295.         ;    DB    '*Or Here*','$'
  296.         ;
  297.         ;    END
  298.         ;
  299.         ; If you've been waiting for an example to enter assemble
  300.         ; and run, try this one out. Just enter it (with out the
  301.         ; semicolons of course) assemble it and run it as described
  302.         ; in AZM-COM.DOC.
  303.         ;
  304.         ; The program clears the screen, positions the cursor at
  305.         ; row 12 column 12 and prints the message using the BDOS
  306.         ; function 9 (print string).   
  307.         ;
  308.         ; The symbol CLRSCR is defined by an EQU to the hex code to
  309.         ; clear the screen on the Kaypro (^Z).
  310.         ;
  311.         ; The cursor positioning sequence on the Kaypro consists of
  312.         ; the two lead-in characters (escape and an equals sign) and
  313.         ; then the row+20H and the column+20H.
  314.         ;
  315.         ; Since the next bytes are just a carriage return, line feed
  316.         ; pair the second part of the message will appear at the
  317.         ; left side of the screen. We could include extra DB's to
  318.         ; position the cursor anywhere on the screen if we like.
  319.         ;
  320.         ; BDOS function 9 (summoned by loading a 9 in the C register
  321.         ; and calling 0005H) prints the characters it finds at the
  322.         ; address in the DE registers until it sees a '$'.
  323.         
  324. DS    n
  325. DEFS    n    ; Reserve data space ( n bytes ). This is used to position
  326.         ; allocate or label data storage space in a program. n is
  327.         ; a number describing the number of bytes reserved.
  328.         ;    DS    16
  329.         ; Reserves 16 bytes. The next instruction will be located
  330.         ; 16 bytes from the location counter when the DS was 
  331.         ; encountered.
  332.         
  333. label    EQU    <expr>
  334.         ;
  335.         ; The EQU sets the label equal to the expression. The
  336.         ; label should not be terminated with a colon when used
  337.         ; with an EQU pseudo-op. The label can be any symbol
  338.         ; (byte or word) and the <expr> a number in any of the
  339.         ; following forms:
  340.         ;        SWEET    EQU    16       ;decimal
  341.         ;        SWEET    EQU    10H       ;hex
  342.         ;        SWEET    EQU    00010000B  ;binary
  343.         ;
  344.         ; With this assembler the EQU must be located in the
  345.         ; operation field. 
  346.         ; A label defined with an EQU cannot be redefined later
  347.         ; in the program.
  348.  
  349. label    DEFL    <expr>
  350.         ;
  351.         ; This assigns the value of the <expr> to the label like
  352.         ; the EQU pseudo-op but a label defined with a DEFL can
  353.         ; be redefined later in the program.
  354.  
  355. *INCLUDE    <filename>
  356. *INCLUDE <filename>
  357.         ; This pseudo-op causes the assembler to stop assembling
  358.         ; lines in the file it is presently in and read in the
  359.         ; file <filename>. It then begins assembling lines in this
  360.         ; included file until it reaches the end of the file when
  361.         ; it returns to the original file and resumes assembling
  362.         ; lines in it once more. The <filename> can be any CPM
  363.         ; filename.ext though if the extent is left off it looks
  364.         ; for the given filename with an extent of .LIB. The asterisk
  365.         ; must appear in column 1 with the word INCLUDE immediately
  366.         ; following with no embedded spaces.
  367.         ;
  368.         ;*INCLUDE    DRIVER.AZM    ; will begin assembly on
  369.         ; the file DRIVER.AZM
  370.         ;*INCLUDE Z80MACRO    ; will begin assembly on
  371.         ; the file Z80MACRO.LIB    
  372.         ;
  373.  
  374. Conditional Assembly Pseudo-Ops............................................
  375.  
  376. IF    <expr>
  377. ELSE
  378. ENDIF
  379.     Conditional assembly is a way of writing a single program so that
  380.     it can be assembled different ways or with different options by
  381.     only changing a couple of lines of codes. When the assembler
  382.     encounters an IF pseudo-op it evaluates the symbol <expr>. IF
  383.     <expr> is non-zero it assembles the following lines until it reaches
  384.     an ELSE or an ENDIF. If <expr> is 0 the lines are ignored until
  385.     the assembler encounters an ELSE or an ENDIF. If the ELSE is
  386.     encounter the assembler begins assembling lines again. The ENDIF
  387.     pseudo-op causes the assembler to resume assembling all lines.
  388.     You can not have an IF without an ENDIF.
  389.  
  390.     Any of these pseudo-ops must appear in the operation field. 
  391.  
  392. TRUE    EQU    0FFH
  393. FALSE    EQU    0
  394. KPRO2    EQU    TRUE
  395. KPRO10    EQU    FALSE
  396.     
  397.     IF    KPRO2
  398.     
  399. BITPRT    EQU    1CH
  400.  
  401.     ELSE
  402.  
  403. BITPRT    EQU    14H
  404.  
  405.     ENDIF
  406.  
  407.  
  408. Operators..................................................................
  409.  
  410. Operators allow the programmer to make the assembler do arithmetic and
  411. logical operations. They are usually used to manipulate operands or
  412. generate symbols. Some of them are used to create tests for conditional
  413. assembly. There should be no embedded spaces when using these operators as
  414. the first blank encountered terminates the operand field. The operands
  415. may be symbols or numbers in any of the bases. The operators supported
  416. by this assembler are:
  417.  
  418. Arithmetic Operators
  419.  
  420.     +        ; arithmetic addition.
  421.  
  422.     -        ; arithmetic subtraction
  423.  
  424.     *        ; arithmetic multiplication
  425.  
  426.     /        ; arithmetic division (truncating the result)
  427.  
  428. Logical Operators (Bit Manipulation)
  429.  
  430.     &
  431.     ( or .AND. )    ; logical AND operation
  432.  
  433.     ^ 
  434.     ( or .OR. )    ; logical OR operation
  435.  
  436.     .XOR.        ; logical exclusive OR operation
  437.  
  438.     \
  439.     ( or .NOT. )    ; logical inversion
  440.  
  441.     .SHR.        ; shift left operand to right by right operand
  442.  
  443.     .SHL.        ; shift left operand to left by right operand 
  444.  
  445.     .HIGH.        ; byte value is assigned the high byte of a
  446.             ; 16 bit value
  447.  
  448.     .LOW.        ; byte value is assigned the low byte of a 16
  449.             ; bit value
  450.  
  451.  
  452. Conditional Assembly Operators ( return    TRUE or FALSE to IF )
  453.  
  454.     =
  455.     ( or .EQU. )    ; logical equivalence
  456.  
  457.     >
  458.     ( or .GT. )    ; greater than
  459.     .UGT.        ; unsigned greater than
  460.  
  461.     <
  462.     ( or .LT. )    ; less than
  463.     .ULT.        ; unsigned less than
  464.              
  465.  
  466.  
  467. Listing Options Pseudo-Ops.................................................
  468.  
  469. There are a number of listing options. All of these options only effect
  470. the print file (.PRN). The options include some for debugging as well as
  471. some for the actual format of the file on the page. The .PRN file is the
  472. basic tool assembly language programmers have for examining the output of
  473. the assembler. The pseudo-ops beginning with an asterisk must begin in
  474. column 1.
  475.  
  476. *EJECT
  477. ( or EJEC )    ; The next line of the listing should be placed at the top
  478.         ; of the next page.
  479.  
  480. *HEADING    ; Place the text ( following this command ) on the top of
  481.         ; each page. Usually used to date the listing file.
  482.  
  483. TITLE 'text'    ; Place the text in the quotation marks (either double or
  484.         ; single on the top of each page in the listing file.
  485.  
  486. SPAC n        ; Leave n blank lines in the listing. Used to leave white
  487.         ; space in the file with out using a page break.
  488.  
  489. *LIST ON
  490. *LIST OFF    ; Turn the listing on or off. This is usually used to omit
  491.         ; long comments or certain sections from the .PRN file.
  492.  
  493. *MACLIST ON
  494. *MACLIST OFF    ; Turn the expansion of macros on or off. Seeing how the
  495.         ; macros are being expanded is handy for optimizing code
  496.         ; but can waste paper when that is no longer the area of
  497.         ; interest.
  498.  
  499. LIST options
  500. NLIST options    ; These pseudo-ops allow you to turn any of the supported
  501.         ; listing file options on (LIST) or off (NLIST) without
  502.         ; changing the other options. Both of these pseudo-ops
  503.         ; must be followed with one or more of the following option
  504.         ; letters. If these pseudo-ops is used some options are
  505.         ; on by default ( marked with (on) in the following list.
  506.         ;
  507.         ; A     ; List all bytes in DB, DW, DDB, etc. Otherwise
  508.         ;    ; only the bytes that can fit in one line are
  509.         ;    ; included in the listing ( others are implied ).
  510.         ; B    ; Place symbol table into object file.
  511.         ; G    ; Place system generated symbols into object files
  512.         ; I (on); List lines of conditional code following a false
  513.         ;    ; conditional. If off only the code actually 
  514.         ;       ; assembled is listed.
  515.         ; M (on); Expand macros in listing files
  516.         ; O (on); Produce an object module. That is show the bytes
  517.         ;       ; being generated by the assembler otherwise just
  518.         ;       ; the source and (optionally) macro expansions.
  519.         ; R     ; use absolute displacement for JR and DJNZ
  520.         ; S (on); List source code in listing file
  521.         ; T (on); List symbol table in listing file
  522.         ; X     ; Generate and list cross references in listing file
  523.         ; Z    ; Generate an error for Z80 only opcodes. Allows you
  524.         ;    ; to write in Z80 mnemonics for an 8080 processor.
  525.  
  526. :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  527. Error Reporting
  528. :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  529.  
  530. When the assembler is unable to understand what you are instructing it to
  531. do it generates an error message. These are almost always due to typo's or
  532. bad form. It displays the error code below and the line the error was found
  533. on to the console and also displays the error codes in the listing file. 
  534.  
  535.      D    ; Duplicate symbol definition. You will see this error
  536.         ; message if you do any of the following:
  537.         ;     Use the same symbol twice.
  538.         ;        FORMATX
  539.         ;        FORMATC
  540.         ;        will generate an error (only 6 significant
  541.         ;        characters).
  542.         ;    Upper and lower case symbols with the same letters
  543.         ;        FORMAT:
  544.         ;        format:
  545.         ;        are identical to the assembler.
  546.         ;    Assigning a different value to a symbol that was
  547.         ;        previously defined with a EQU pseudo-op.
  548.         ;        If you are going to reassign use DEFL.
  549.  
  550.     E    ; Relocation error. I believe this occurs if the assembler
  551.         ; cannot reassign an address as expected.
  552.  
  553.     F    ; Format Error. You will see this if you break any of the
  554.         ; rules regarding field use and macro format.
  555.  
  556.     K    ; Keyword error. This means you tried to use one of the
  557.         ; assemblers reserved words or pseudo-ops as a symbol.
  558.         ;    ORG:    JP    END
  559.         ;        NOP
  560.         ;    END:    JP    ORG
  561.         ;     is in very bad taste.
  562.  
  563.     L    ; Label error. The attempt to assign a value to a lable was
  564.         ; unsuccessful. Also remember that labels do not end in a 
  565.         ; colon when preceding EQU.
  566.         ;    START:    EQU    100H    ; is bad news
  567.         ;    START    EQU    100H    ; is perfect
  568.  
  569.     M    ; Missing label. The symbol you are using was never defined.
  570.  
  571.     N    ; Macro nesting error. Macros can be nested (that is a macro
  572.         ; can call another macro) but if the nesting gets to deep
  573.         ; the assembler will quit and give you one of these. Also,
  574.         ; you can only call macros that were previously defined.
  575.  
  576.     O    ; Op code error. If you see this, look in the operation and
  577.         ; operand fields. Consult the mnemonic table. People 
  578.         ; switching over from 8080 will see a few of these.
  579.  
  580.     P    ; Phase error. A 2 pass assembler builds a symbol table on
  581.         ; the first pass and generates the object code on the second.
  582.         ; If a number that it calculates for a symbol on the first
  583.         ; pass does not agree with a number it generates in the
  584.         ; pass this error is shown check the symbols in the line
  585.         ; the error appeared.
  586.  
  587.     Q    ; Questionable operand. Actually theres no question about it
  588.         ; it is a bad operand. Typo's give you these as well as 
  589.         ; blowing op code format. Usally easy to find your mistake.
  590.  
  591.     S    ; Syntax error. You broke one of the syntax rules described
  592.         ; above.
  593.  
  594.     T    ; Symbol table full. Not much you can do with this except
  595.         ; pare down the code.
  596.  
  597.     U    ; Undefined symbol. You used a symbol but forgot to define
  598.         ; it in with an EQU.
  599.  
  600.     V    ; Value error. Usually means you are trying to do a 16
  601.         ; bit operation with an 8 bit number or the other way 
  602.         ; around.
  603.  
  604.  
  605. Macros
  606.  
  607. The macro is a powerful method of writing assembly language programs. It 
  608. makes it possible to write assembly language programs in a way that resembles
  609. higher level languages. In fact by creating a library of macros you are
  610. in essence creating your own language, and your own compiler.
  611.  
  612. Often times in assembly language (particularly writing for CP/M) each program
  613. contains source lines that are used again and again in other programs. By
  614. using macros the routines only need to be written once and then may be called
  615. in any program. The best thing about a macro library is that only the macros
  616. that are called produce object code. So there is no penalty in having a macro
  617. library that is large and complete even if you are only going to call one
  618. macro.
  619.  
  620. Macros have a form that is unique and must be followed closely for correct
  621. results. The general form of a macro is
  622.  
  623. name    MACRO    #parameter1,#parameter2,....
  624.     instruction
  625.     instruction
  626.     instruction
  627.     .
  628.     .
  629.     .
  630.     ENDM
  631.  
  632. The name is the symbol that will be used to invoke the macro. MACRO is a
  633. keyword that will indicate to the assembler that a macro is being defined.
  634. The parameters always must begin with a '#' sign in macros and they are
  635. seperated by commas. The instruction can be Z80 instructions, or any of the
  636. assembler commands listed above incuding conditionals. The instruction can
  637. also be another macro call (called nested macros) but only if the nested
  638. macro has been already defined. The ENDM keyword tells the assembler that it
  639. has reached the end of the code that must be assembled when this macro is
  640. called. Do not use a colon behind the macro name.
  641.  
  642. The previous message program example can be rewritten to look like this
  643. with macros.
  644.  
  645.       ORG    100H
  646.  
  647. *INCLUDE Z80MACRO
  648.  
  649.     BDOS    PRNSTR,MES
  650.     RET
  651.  
  652. MES:    DB    ESC,'=',12+20H,12+20H
  653.     DB    '*Your message here*'
  654.     DDB    CRLF
  655.     DB    '*Or here*'     
  656.     END
  657.  
  658. With the following macro library called Z80MACRO.LIB
  659.  
  660.  
  661. ;Call Bdos function #FUNCT using paramater contained in #DE
  662.  
  663. ESC    EQU    1BH        ; ascii escape
  664. CRLF    EQU    0D0AH        ; ascii    carriage return line feed
  665. PRNSTR    EQU    9
  666.  
  667. BDOS    MACRO    #FUNCT,#DE
  668.     LD    C,#FUNCT    ; FUNCTION NUMBER GOES TO C
  669.     LD    DE,#DE        ; GET PARAMETER
  670.     CALL    5        ; CALL BDOS
  671.     ENDM
  672.  
  673. We could also rewrite the cursor positioning sequence into a macro. Note
  674. how just this small example can save us time in future programs. Also, the
  675. macro library is a great place to keep frequently used symbols like ESC and
  676. CRLF.
  677.  
  678. But what about using address symbols in macros? How can we avoid the 'D'
  679. error if we call the macro more than once. The other keyword unique to
  680. macros is LOCAL. This makes the assembler generate its own unique label
  681. every time the macro is expanded in a program. Following the word LOCAL
  682. ( which must be on the second line of the macro ) are the symbols we want
  683. the compiler to generate unique labels for. These symbols must also be
  684. proceded with a '#' sign.
  685.  
  686. AJUMP    MACRO
  687.     LOCAL    #ADR_Z,#BACK
  688.     OR    A
  689.     JR    Z,#ADR_Z
  690.     LD    A,40H
  691.     JR    #BACK
  692. #ADR_Z:    LD    A,04H
  693. #BACK:    LD    DE,0
  694.     ENDM
  695.  
  696. The macro itself is not really useful but it is correct and shows the use
  697. of local labels.
  698.  
  699. A,04H
  700. #BACK:    LD    DE,0
  701.     ENDM
  702.  
  703. The macro itself is not really useful but it is correc