.** File Name: Manual2/txt
.** 03/24/82
>* Instruction manual for Disc ZEN,  Laurie Shields.  20/04/81
>C=N J=N FR=N LM=6 RM=78 TM=2 BM=64 PN=10
FS>J=N FR=N C=Y
PAGE P>##
Disk and Cassette Commands

Cassette source files are in ZEN's special block format, with checksums to verify the accuracy of a tape read.

During cassette input, incoming data are loaded into available RAM.  If large cassette files are handled, note their size before using any special drivers or filters in high memory, so that available memory will not be exceeded.

R      READ DISK Source file, after prompting for a filespec.
       The file can be in either ZEN or Edtasm format.  If the file is
       in Edtasm format, ZEN converts it and adds colons after
       the labels.  The algorithm ZEN uses for this process assumes
       that the Edtasm file is formatted entirely by tabs.  If
       spaces are used instead, colons may not be accurately inserted.

       Re-recording the file in ZEN format usually reduces disk space by 30 to 60%.

W      WRITE DISK Source file.  The entire in-memory source file
       is written to disk, after a prompt for a filespec.  If the file
       already exists, the new one replaces the existing one.   Otherwise,
       a new file is created.

WA     WRITE ASCII writes a core-image ASCII text file (Electric
       Pencil format) from START address to END address inclusive, with
       a zero EOF byte.  This is useful for retrieving Pencil or Scripsit text lost
       through re-boots, etc., or for re-setting ZEN's text pointers.

RS     READ SOURCE reads a source file from cassette.

RO     READ OBJECT reads an object tape and loads it into memory.
       Object files are stored at their load address.  ZEN does NOT
       prevent the System tape from loading over ZEN's code.
       The execution address is stored at 5632H, the address of the
       default parameter for a Jump command.  The value stored there
       is also found in the user PC in the Xamine register display.

       Both modes prompt for a filename, and then search for
       the file.

       A default response to the filename request causes
       ZEN to skip the name check and read the first file it       finds.
       When the file is located, the letter "L" replaces the cursor.
       Any checksum errors cause the message, BAD READ, to
       display; the tape then stops.  Cassette filenames are
       stored at 5423H when they are read, so use Q5423H if required.

       After a source file has been read, the new file size is
       displayed.  If the Source file exceeds available RAM the error
       message MEMORY FULL is displayed and loading stops.

VS & VO     VERIFY checks that a file on cassette contains no errors.
       Use this command just like the READ, but only
       the object execution address is loaded into memory.

RE     READ EDTASM reads an Edtasm cassette source file, and ignores
       the line number bytes.  Line numbers are displayed in the
       top right hand corner of the video screen.  After reading, ZEN places
       the necessary colons ":" after the labels.

VE     VERIFY EDTASM.  While Edtasm tapes cannot be verified in the
       fullest sense (they are not recorded with checksums), this
       command checks the identifying byte at the start of the tape
       and displays the filename.  If the tape is not in Edtasm format, ZEN responds with "HUH?".


WS     WRITE SOURCE file to cassette.

WO     WRITE OBJECT file to cassette.  Prompts appear for the file name,
       plus the start, stop and execution addresses.

DI     DIRECTORY display defaults to drive 0 if no drive number
       is included, e.g.  DI<ENTER> is equivalent to DI0<ENTER>.
       The program code for valid DOS CALLs for this command
       needs to be customised for the Model 1 standard 35-track, the
       Model 3 TRSDOS and for Newdos80 Ver2.  Use of this command on
       other DOS's has unpredictable results.
       Review the Appendix on the various options included with
       CUSTOM/ZEN for adapting ZEN to your system.


Notes on converting Edtasm files.

Little change in an Edtasm file is needed after it is read by ZEN.  The most common changes are:

i)   Execution address.  Edtasm     END     START
                          ZEN       EXEC    START
                                    END

ii)  Alter AF,AF' to AF,AF.  Use the G command:
     Z>G
     Change>AF,AF'
     To>AF,AF

iii) Change reserved words such as LOAD, END etc. to LOADX, ENDX
     or similar wording.

iv)  ZEN does not support Edtasm's DEFL to redefine a label.

v)   Edtasm's mathematical operators < and > are more easily
     implemented with ZEN's divide and multiply, eg., /2 and *2.

vi)  Deletion of the disk filename from the first line where it appears
     as a label.


Source Pointer Commands

Since Z80 assembly language is line oriented, ZEN's Editor is also line, rather than character, oriented.  ZEN maintains an internal pointer to the CURRENT LINE in the source file; the current line is always the last one displayed or printed.

The following commands all move the source pointer.

T     TARGET, pointer moves to the parameter line number.
      Example ...  T25 <ENTER> makes line 25 the current line.

B     BASE, pointer moves to end of file.

D     DOWN, pointer moves to the end-of-file (parameter) lines.
      Example ...  D37 <ENTER> moves pointer down 37 lines.
      The default parameter has a value of one, so D is
      equivalent to D1.  The T, D, U and Shift P commands, which take an
      iteration (number of cycles) parameter, all have the default value of 1.

U     UP, pointer moves up (parameter) lines.
      Example ...  U37 <ENTER> moves the pointer up 37 lines.
      The up and down arrows also scroll one line at a time.

P     PRINT, displays (parameter) lines on the video display.  The last
      line displayed is the new current line.  P by itself
      clears the video screen and displays 15 lines.
      Example ...  P37 <ENTER> prints 37 lines to the video screen
      in scrolling mode, without clearing the screen first.

SHIFT P     LINEPRINT, as for PRINT, but outputs to the printer.

L     LOCATE, finds an arbitrary target string in the source file.
      Example ...  LBIT 7, (HL)
      Moves the pointer to the first line containing the string
      'BIT 7, (HL)' makes it the current line and displays it.  The file
      is searched downwards from the current line.  If the string is
      not located the pointer is at EOF.
      There are no restrictions on the string content.
      L without a parameter defaults to the prevous search string.


Source Edit Commands

Z     ZAP erases (parameter) lines from the file, starting with
      the current one.
      Example ...  Z37 <ENTER> deletes the current and next 36
      lines from the text.

E     ENTER enters text continuously into the file.  On entry the
      line number is displayed as a prompt.  Type in a line of text,
      terminating with the <ENTER> key.  The next line number is then
      displayed.   To exit from the command, type a period
      (".") as the first (and only) character of the line.
      You can enter text anywhere in the file.  Text is inserted at the
      current line with the old current line, and all following lines
      move down.

N     NEW lets you add to the end, or edit, the current line.
      Entering a comma key has the same effect as keying N <ENTER>.

G     GLOBAL replaces a search text string with a replacement.
      Without a parameter, eg., G<ENTER>, the in-memory file is
      searched.  Where a numeric parameter is supplied, eg., G3<ENTER>, only three
      lines are searched, starting at the current line.

      Example ...  G<ENTER>
                   Change>Cassette<ENTER>
                   To>CTR80<ENTER>

      This causes every instance of "Cassette" in
      the source file to be changed to "CTR80," with a reduction in
      file size of three bytes for each change.

      Example ...  G1<ENTER>
                   Change>HL<ENTER>
                   To>BC<ENTER>
      Causes BC to replace HL in the current line only
      (since the parameter 1 was used), so if the current line
      were LD HL,1234 then it would become LD BC,1234.

With practice, the G1 command sequence is adequate for text alterations when the simple edit via "N" or "," are not suitable.  G1 also permits writing source code in a shorthand form, with subsequent expansion to full assembler mnemonics, eg.:

h START
d DEST
b LEN
LDIR
etc
Then use G to Change>h To> LD HL,
  "   "  "  "    "   d  "  LD DE,
  "   "  G  "    "   b  "  LD BC,
etc., to suit yourself.


ZEN always checks for available memory before each replacement.  If a new end-of-source file would conflict with Himem, the replacment mode is canceled.  The address above Himem that would have been used is displayed, and the line where the replacement was scheduled becomes the current line and is displayed.

Keying <ENTER> in response to either the search or replacement text causes ZEN to exit the replacement mode.

NOTE:  Although line numbers are displayed with most commands, you need not ever enter them yourself.  Line numbers are displayed as a positional guide for you.  The numbers are computed dynamically by ZEN, and not stored with the text.

NOTE:  If you exced available memory, the Memory Full error message is displayed.  However, the file is not changed.


Monitor and Debugger Commands

J     JUMP transfers control to a user program at the parameter
      address supplied.
      A prompt then requests a breakpoint address.
      Both parameters have default values.

      By keying J <ENTER>, execution commences at the existing User
      Program Counter, which is displayed.  The default reponse to
      the breakpoint request means that no breakpoint is set.

      If you supply a breakpoint address then the byte at that address
      is saved and a RST 38H instruction is inserted there.
      When the breakpoint is encountered, control is transferred back to
      ZEN via the REENTRY vector to the TRAP handler where the
      original code is replaced.  The entire Z80 machine state is
      saved at TRAP time and restored to the machine at JUMP time.


      The REENTRY vector also allows you to terminate user programs
      even if you don't set a breakpoint.
      Including the code CALL REENTRY in your programs gives
      multiple breakpoints for de-bugging.  The address of the next
      instruction is saved in the UPC, so it is only necessary to key J <ENTER>
      with no breakpoint to continue execution until the next
      CALL REENTRY is encountered.  This technique is preferred when
      the user program employs ROM or DOS calls as the RST 38H code is
      not used.

      REENTRY is located at 5631H

      ZEN won't replace the CALL as it is able to distinguish between
      this and a genuine breakpoint (a CALL is needed, not a JP,
      to leave the program counter on the stack).

      J0<ENTER> generates a complete reboot of the system.

      The full command sequence to Jump to a user program at 8000H and
      return, without executing the code at 8011H, is as follows:
      J8000H<ENTER>
      Brkpnt>8011H<ENTER>
      This returns to ZEN.  Keying X<ENTER> displays the
      Z80 register values from the point just prior to the code at 8011H.
      To continue execution at 8011H and break at 8020H:
      J<ENTER>
      ZEN displays 8011
      Brkpnt>8020H<ENTER>, etc.


C     COPY copies a block of memory, from START to STOP
      ADDRESSes inclusively, to a DESTINATON ADDRESS.
      The copy is "intelligent" so overlapping areas of memory can be
      copied safely.


F     FILL fills a memory block, from START to STOP
      ADDRESSes inclusively, with a DATA constant.
      During Copy and Fill no check is made on whether the memory
      receiving area is correctly storing the data.


X     XAMINE displays the Z80 user machine state.
      All registers are displayed and labelled.
      The main registers are on the top line and the alternate
      registers are on the second line.
      The value shown for the PC register is the default address for
      the Jump command, and the SP register shows the User Stack
      location that will be used during debugging.


M     MODIFY lets you examine and modify memory contents.  If you
      supply an address parameter, the display starts at that
      address.  MODIFY takes a default of the CURRENT OBJECT
      POINTER, which is an object pointer similar to the source
      current line pointer.

      The address and the byte at that address are displayed
      in hex followed by a prompt for a parameter.  The default
      response causes a step to the next address.  Entering
      a parameter causes that byte to be replaced with your
      parameter.  Your parameter is erased on the video display,
      the new value is displayed and ZEN steps to the next address.

      To exit, type in a period (".") as the parameter.
      The current object pointer is left pointing at the last byte
      displayed.

      ZEN checks after each modification and exits to command mode
      on an error, eg., an attempt to modify ROM.

Q     QUERY displays a block of memory in hex and ASCII.
      This command also takes the current object
      pointer as the default parameter.  
      Memory is displayed as eight lines of eight bytes; each line
      comprises four fields:

      1     Address
      2     Eight bytes in hex
      3     Eight bytes literal with Bit 7 stripped
      4     Eight bytes literal with Bit 7 untouched

      Bit 7 is stripped in field three to show text that has this
      bit set high.  Field four displays these characters as graphics.

      Control characters (less than 20H and greater than 0BFH) are
      converted to periods and displayed on the video screen.

      The current object pointer is left pointing at one greater
      than the last byte displayed.

SHIFT Q     LINEPRINT QUERY is as above, but with output to the printer.


The Assembler

ZEN expects source statements to follow the syntax defined in the Zilog Z80 Assembly Language Programming Manual.  Each line of the source file is divided into four or fewer fields:

MESSAGE: LD HL, GREETING; Say hello

Label
.  . .  . Operator
.  . .  . .  . .  . Operand(s)
.  . .  . .  . .  . .  . .  . .  Comment

The divisions in a statement are conceptual because they need not be positioned in distinct fields.  If the correct separators (spaces, commas, etc.) are used, ZEN accepts statements in free format.

COMMENTS      Comments are ignored by the assembler.  They are preceeded
              by a semi-colon ";" and are terminated by end of line <ENTER>.

OPERATORS     There are 74 generic operators (CALL,LD,JP,etc.).
              In addition there are the PSEUDO-OPS described later.

OPERANDS      The number of operands in a statement depends upon
              the operator.  Examples:

              NOP     No operands
              JP      One operand
              BIT     Two operands
              JR      One or two (JR SYMBOL or JR Z,SYMBOL)

              Operands may be:
              Register names (A,B,DE,IX, etc.)
              Condition codes (Z,NZ,C,M,etc.)
              Numbers

              The number group is the most complex.  The following
              are accepted as numbers:

              ASCII Literals
              The assembler generates the ordinal value of any
              character enclosed in single or double quotes.

              Numbers
              Decimal, hex and octal bases are accepted with decimal
              the default.  Hex numbers are "H" postfixed and octal
              numbers are "O" postfixed.
              Numbers must begin with a digit; a leading zero is
              sufficient.

              Symbols
              These are explained in detail later.

              Program Counter
              This is the internal variable which simulates the
              runtime PC.
              It is accessed by using $ (dollar).


The Assembler

OPERANDS  The preceeding data types may also be
          elements of an expression formed using the infix
          mathematical operators:

          +  Addition                 /  Division
          -  Subtraction              &  Logical AND
          *  Multiplication           .  Logical OR


          An expression can be used anywhere that a simple number can
          be used.  The following are all valid:

          LD DE, START*2-782
          LD A,"P".8OH
          JR NC,$-5

          Expressions are evaluated strictly left to right with no
          precedence ordering.  Arithmetic is unsigned 16 bit integer
          and overflow will be ignored.
          Elements in an expression need not be delimited by separators,
          as the math operators are implied separators.  


LABELS    A label marks a statement.  Each time you use
          an operator like JP, CALL, etc.  you need a way of specifying
          the destination as an operand.  Assembly language allows you
          to use a symbolic name as a label.  BASIC is an example of
          a language without this facility; in BASIC, the line numbers act
          as labels.  Symbols will be explained in greater detail next.


Symbols

A symbol is a name with an associated value.  The name is used in place of an explicit stated value.  A symbol's value is declared to the assembler in one of two ways:

1     By placing it at the start of a statement.  The assembler assigns
      the value of the program counter to it.

2     By using the EQU pseudo-op.  This allows you to assign your own
      value to a symbol.

      Example      BACKSPACE: EQU 8

Whichever method is used, a symbol must be postfixed with a colon ":" when declared.  A symbol must begin with a letter but may contain letters or numbers after that.  Letters may be upper or lower case.  ZEN allows symbols of any length although symbols longer than seven characters make listings unpredictable.

There are certain reserved keywords which cannot be used as symbols.  These are:

          Operator names, register names and condition code names.

NOTE:  All keywords are uppercase, so using the same name in lowercase is acceptable.


Pseudo-Ops

Pseudo-ops are additional operators which have no equivalent in the Z80 instruction set but are understood by the assembler.  They are used like the normal operators.

LISTOFF      Stops listing        (No operand)
LISTON       Cancels Listoff      (No operand)
END          End assembly         (No operand)
EXEC         Execution address    (One operand)
DS or DEFS   Define Storage       (One operand)
DW or DEFW   Define Word          (One operand)
EQU          Equate               (One operand)
ORG          Origin               (One operand)
LOAD         Load memory          (One operand)
OFFSET       Offset object code   (One operand)
DB or DEFB   Define Byte(s)       (Multiple operands)


END    This operator MUST be used to terminate assembly.  Failure do do
       so results in an error message and an incomplete assembly.

EXEC   Tells the assembler the execution address of the program if
       being output to cassette or disk.
       Default of 1A19H or 402DH assumed if not supplied.

DS     Skips a number of object bytes.  Commonly used to reserve
       space for a text buffer, stack, etc., where the object code
DEFS   doesn't need to be defined.

DW     Generates a word (two bytes) in the object file in reversed
DEFW   Order as required by the Z80 sixteen bit instructions.


Example ...  BUFFER: DW VALUE
             Makes the contents of location BUFFER equal to VALUE.

DB     Generates the value of the operand(s) in the object file,
DEFB   Takes as many operands as desired, separated by commas.

Example ...  DB 6, 93H,"T".80H, NEWLINE

       Each operand may be an expression; however, no expression
       can have a value exceeding 255D.  The program counter
       is increased after every operand as if each were on a
       separate line.
       The usual data types plus any operand may be an ASCII
       literal string.

Example ...  MESSAGE: DB"READY CASSETTE", NEWLINE

       Strings may be of any length  but, unlike single character ASCII
       literals, may not form part of an expression.  A string is
       formed in the same way as a single character literal, by
       enclosing it in matching quotes.  Note that single and double
       quotes are implied separators like the infix math operators.

       You may use a quote of either type as a literal by using the
       OPPOSITE type of quote as the delimiters.
EQU     Assigns a value to a symbol.

Example ...  NEWLINE: EQU 13

        The operand may, as usual, be an expression but the
        symbols you may use in the expression are restricted
        to operands that are capable of immediate resolution.
        The value of any symbol used in the expression must already be
        known to the assembler.  Forward referenced symbols will result
        in the UNDEFINED error flag.  

Example ...  NEWLINE: EQU BACKSPACE+5
             BACKSPACE: EQU NEWLINE-5

        This sequence is ILLEGAL because each symbol is defined in
        terms of the other.
        The "no forward reference" rule is designed to prevent
        such a mistake.

        In practice you will probably never encounter this situation,
        since most EQUATES have simple operands.

ORG     Defines the origin of the object file.  This operator may be
        re-used during assembly to produce sections of code
        at different locations.  The operand must conform to
        the "no forward reference rule for obvious reasons.

LOAD    Lets you load the object code into memory, at any address, as
        it is produced.  Note that the use of a subsequent ORG operator
        turns off the loading process;  each time you use a new origin
        you must specifically re-establish the LOAD command.

        The loading process is independent of the output
        option specified on entry to the assembler.  If the operator is
        not used, then no memory location outside ZEN is altered.


Note:   The LOAD instruction must not preceed the ORG pseudo-op.
        Since LOAD is independent of the ORG address, code
        can be generated for one location in memory and loaded
        into another.  After assembly the "C" command can be used to
        copy the code to its correct location.


OFFSET  Tells the assembler to add the value of the operand to all load
        addresses of object code, whether to cassette, disk or listing
        file.  Assembly defaults to an offset of zero and this
        pseudo-op may be ignored unless code must load at one
        address but execute following a move to another.

LISTOFF Tells the assembler to stop generating output to the video screen
        or printer.

LISTON  Re-establishes the listing process.  Assembly always starts in
        this mode.


Assembler Output

ZEN supports three list devices, the 64 character x 16 line video, an external printer and an ASCII format disk file.

ZEN generates completely formatted output to all three devices.
Listings are output as pages, with a delay between pages.
The pages are set at 15 lines to the video and 60 lines to the printer.

Pause Control:   Pressing any key except <BREAK> during the delay between pages stops the listing until another key is depressed.  If the key pressed is "X," ZEN returns to the command mode.  The pause control can be toggled on/off in the command mode with Shift Y (y on Model 3).  This speeds printer output if continuous stationery is being used.

Sort and Cross Reference outputs are similar to assembly listings, with pause control at the end of each page.

The accompanying extracts were produced by ZEN assembling its own source code with the "F" option and then using Scripsit to print the file.


Assembler Error Handling

If the assembler finds an error in the source code the following steps take place:

(1)  Assembly terminates.
(2)  An ERROR message is displayed.
(3)  The incorrect line becomes the editor current line.
(4)  The line is displayed.
(5)  Any open files are closed.
(6)  The command loop is re-entered.

Correct the error and assemble again.  In the virtual assembler mode, the error line is numbered relative to the beginning of the first file, although it is the only line in memory.


Error Messages

DOUBLE SYMBOL ...  The same symbol is declared more than once.
UNDEFINED .......  You have used an undefined symbol.
RESERVED ........  You have used a reserved keyword for a symbol.
SYMBOL ..........  An obligatory symbol is missing (eg., with EQU).
FULL ............  The symbol table is full  (Use I command).
EOF .............  You have forgotten END and have hit EOF.
ORG ! ...........  No origin specified.
HUH? ............  The line doesn't make sense.
OPERAND .........  Something is wrong with the operand......
                   Examples .....  LD A,256   (too big)
                                   BIT 9,B    (no bit 9)
                                   LD(DE),C   (illegal instruction)
                  Also any attempts to index or jump relative
                  out of range.

The assembler detects all incorrect statements.  The only incorrect statement which will damage ZEN is a LOAD over its code.


DOS and  ROM

ALL disk access is via the official published TRSDOS vectors: INIT, OPEN, READ, WRITE and CLOSE.  (Model 3 uses Directory Display).  The only ROM calls used are 2BH, 33H and 3BH.  The only other memory addresses that ZEN reads are 3840H (break key) and 4049H (4411H on Model 3) for Dos high memory.

All reads and writes to disk are in full sectors and are verified.

ZEN will handle any errors arising during disk accessing and display the appropriate error message.

The table on the following page compares all of the commands available at the command level in ZEN with the nearest equivalents in EDTASM and MON#3.


Copyright (C) 1981   Laurie Shields & Avalon Software.
       ZEN                   EDTASM           MON #3
       ===                   ======           ======
      A   Assemble             A

      B   Base                 P*

      C   Copy                                  M

 ! or D   Down                 !

      DI  Directory

      E   Enter Editor         I

      F   Fill                                  Z

      G   Global

      H   Howbig

      I   Increase S.T.

      J   Jump                                   J

      K   Kill                 D#:*

      L   Locate               F

      M   Modify                                E

 , or N   New line             R.

      O   Operating system

      P   Print                P

Shift P   Line print           H                Shift P

      Q   Query                                 H and A

      R   Read tape or disk    L                L

      S   Symbol table

      T   Target to line       P

 ! or U   Up                   !

      V   Verify tape

      W   Write tape or disk   W                P

      X   Examine registers

      XR  Cross reference      A/NO/NL

      Y   Toggle display format

      y   Toggle page pause

      Z   Zap                  D
 R
LD HL,0
LD A,16
MA61