.** File Name: Manual 1/txt
.** 03/24/82
.** disc=disk,orientated=oriented,.    =.  ,debuger=debugger,
.** in-memory (some), disk-based (some)
>TM=2 BM=64
FS> J=N FR=N C=Y
PAGE P>##
>TM=2 BM=64
FS> J=N FR=N C=Y
PAGE P>##
>LM=6 RM=78 C=Y


Z E N:  An EDITOR - ASSEMBLER - DEBUGGER

for the

TRS 80 Models 1 & 3 (DISK or CASSETTE)


>C=N J=Y FR=N

1. Introduction

The disk-based ZEN editor-assembler-debugger is a powerful user-oriented assembler for the TRS80.  ZEN can assemble  linked multiple source files directly from disk or from an in-memory file.  Object code output can be sent to disk or cassette, or loaded to memory.  The assembler list file can be sent to the video screen, to a printer, or to an ASCII disk file.  Source files can be read or written with Scripsit or Electric Pencil, and ZEN can read disk or cassette files written in Edtasm format.

Extensive monitor and debugger commands are available.  There are facilities to edit memory, jump to machine code programs, examine registers, read and verify system tapes etc.

The original ZEN was written for cassette by John Hawthorne of AVALON SOFTWARE.  A copy of his instruction manual follows these introductory notes.  Laurie Shields adapted ZEN to the TRS-80 Disk Operating System and added extra commands to it.  These notes are also by Laurie Shields.

Warning:  Each original recording of ZEN contains an identifying serial number in the program code.  Illegal copies can be traced to the original purchaser.


2. Using ZEN

ZEN consists of four machine-code programs in one package: 

(a) A text editor to generate, modify, record and read, from disk or tape, the source code file for the assembler.

(b) An assembler that converts the source file, written in Z80 mnemonics, into Z80 machine-code instructions; these can be recorded on disk or tape, printed or loaded into memory.

(c) A monitor to inspect the Z80 memory in Hex and ASCII, with the option to alter values in RAM.

(d) A debugger to use in creating a 'Jump' to a machine-code program in memory, given a previously set breakpoint.  Control returns to ZEN and the Z80 register values just before the breakpoint can be inspected.


3. The Editor

The Editor is activated by keying "E."  ZEN responds with a line number and awaits further input (like the Auto Line Number command in BASIC).  If a source file does not already exist, then line numbers start at 1.  Otherwise, the Editor begins at the current line number and moves other lines down to make room for the new entries.
>C=Y

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
*          To end the Editor mode, type a period "."      *
*   as the first and only character of the next line.     *
*       Pressing the <BREAK> key has NO effect.           *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
>C=N

Line numbering is automatic and is transparent to the operator.  Unlike Edtasm, renumbering is not needed if extra lines are added to the source file.

During assembly, ZEN formats the output to the video and printer.  The source code does not have to be entered in tabular or field format.  ZEN has two modes of presenting in-memory text on the video:

 1. In the normal mode, ZEN examines each line to see if it contains a label; if not, ZEN inserts four extra spaces between the line number and the first character.

 2. Second, ZEN presents each line of text exactly as it occurs in memory.  No line numbers or extra spaces are added.

Type a "Y" to alternate (toggle) between the two display modes.

Freely formatted source code is accepted by ZEN.  The only requirements are:

 1. Enter a colon (":")  after a label, and

 2. Enter a <SPACE> between the opcode and the operand.

This compact form of text entry, together with the virtual line numbers, uses memory and disk space more efficiently than other assemblers.

Once an in-memory source file exists, commands are available for moving up or down the file, to the top or bottom of the file, or to the screen or printer.  A line with an error can be corrected (zapped) with the "Z" command, or edited with an "N" (for New).

The letter "P," followed by <ENTER>, clears the video screen and displays 15 lines of code starting with the current line.  The last line displayed becomes the new current line when another "P" is entered.

To aid source file manipulation, the five keys listed below are acted on immediately when ZEN is in the command mode.  No <ENTER> is required.  These commands must be typed as the first keystroke following the Z> prompt.

Up arrow       :    Up one line.
Shift Up arrow :    Top of source code.
Down arrow     :    Down one line.
Clear          :    Clear the video.
Comma          :    Edit current line.


Since ZEN does not require tabs between fields (a space is sufficient), the right arrow key is always treated as a space.   Left arrow and shift left arrow respond as in BASIC for text editing.  ZEN uses only the published keyboard, video and printer drivers.  High memory is respected except when source files are read from cassette.

ZEN supports lower case text in the source code, but on the Model 1 a separate lowercase driver is needed.

Source files are read with the "R" commands from disk or cassette, both in the original ZEN and in the Edtasm or MON3 symbolic dump formats.  Once in memory, a source file is saved by writing it to disk or tape with the "W" command.

Whenever a file is to be written or read, ZEN prompts for a filespec or a filename as appropriate.

Disk source files are compatible with "Electric Pencil" and "Scripsit."  Either program can prepare or edit source files.  ZEN will also write or edit BASIC programs saved in ASCII format.  When the file created by ZEN is loaded into BASIC, the difference in end-of-file markers between ZEN and Basic often causes a Syntax Error message; however, it can be safely ignored.

ZEN's editor is limited to lines of 90 or fewer characters.  ZEN will read, display and write text lines of any length from disk.  However, do NOT use the "N" or "," forms of EDITing on lines that exceed 90 bytes.

The Global Replacement editing can be used on text with lines of any length.


4. The Assembler

After the command A (to assemble), ZEN gives the prompt:  Source File>.  If the assembly is to be from the in-memory text then press <ENTER>.  Otherwise, any text entry is treated as a filespec(s), where spaces are regarded as delimiters.  When the output option is entered, assembly proceeds from memory or disk.  If assembly is from disk, ZEN displays the filespec as files are opened for input.  If the first file is opened without error then the in-memory file is killed; the pointers are needed to process the incoming source code.  Only one text line at a time is held in the buffer during assembly, so it is possible to assemble almost limitless amounts of source code.  Scripsit (10K object code) can be assembled on a 16K single drive 35 track single density system.

The Assembler makes two passes through the source file.  On the first pass, ZEN constructs a reference table of the labels and the values they will acquire in the final object code.  The space initially set aside by ZEN (200H bytes) for the symbol table may be inadequate.  If so, ZEN stops on the first pass and displays the message "Full."  To correct this situation, use the "I" command to increase the memory allocation and re-assemble the program.

To create extra space, the entire source file is moved higher in memory.  ZEN checks the availability of RAM before executing the "I" command.

ZEN also rejects illegal instructions in the source file.  The offending line is displayed, with an related error message.  When ZEN's first pass is successful, it generates the final object code on the second pass.

The option selected after the "A" command determines whether the second pass output will go to the video, the printer, a listing file to disk, or from object code to cassette or disk.

NOTE:   ZEN uses the following formats that may be slightly
        different from other assemblers.

  (i)   EX AF,AF  not EX AF,AF'

  (ii)  Negative offsets to the index registers IX and IY should be
        shown as such, not with a positive offset of a negative
        value,  i.e. IX-10H instead of IX+0F0H.


After assembly, the "S" command generates a listing of the labels and values in the Symbol Table.

The "X"' command also generates a complete cross reference listing of all the labels and the references to them in the in-memory source file.


5. The Monitor

The Monitor has four commands, Q, M, C & F, which allow manipulation of the TRS80 RAM.

 1. Q plus a starting Hex value (e.g. Q7000H <ENTER>), will display, in Hex and ASCII, 64 bytes of memory starting at 7000H.

 2. Modify,  M7000H<ENTER>, displays the current contents of address 7000H, waits for the new value from the keyboard and then goes to the next byte.  Entering a "." or an invalid numeric input, terminates the Modify command.

A block of memory can be filled with a data value with the "F" command or copied from one address to another with the "C" command.  

Try the following:

Z>F<ENTER>
Start>3C00H<ENTER>
Stop>3FFFH<ENTER>
Data>201<ENTER>

MON3 users will recognize that "Q" functions like a combined A & H command.  "F" is equivalent to MON3's Z (zero) and "C" is the same as MON3's M (move).  Note that ZEN has the extra advantage of accepting decimal values.


6. Directory

DIdrive<ENTER> (NO embedded spaces or colons) instructs ZEN to read and display all non-system, visible disk files.  Differences in directory handling between TRSDOS on the Model 1 and 3, and between TRSDOS and NEWDOS80, require ZEN to be customized to each system.

CUSTOM/ZEN, a BASIC program, is included on the program disk if any changes are needed.  Details on its use are given in the Appendix.


7. High Memory

The Model 3 TRSDOS uses a different address than the Model 1 to store the high-memory pointer.  This change is also made by CUSTOM/ZEN.

When ZEN is initialized, it copies the DOS high-memory value to its own two-byte storage LIMIT (55C9H) and then checks that it is non zero.  If it is zero, then memory is examined (in a non-destructive fashion) and the address of the highest responding byte in Ram is stored in LIMIT.  ZEN uses this value for all memory operations except cassette input.  Any attempt to exceed the value generates an error, giving the address above LIMIT that an attempt was made to use.  The user can then reset to Level 2 if required, and re-enter ZEN by SYSTEM and  /22079 (563F Hex), and operate in a non-DOS environment.

ZEN can be re-entered from DOS from DEBUG (use G563F) or by typing ZEN <ENTER>, * .


8. Printer Driver

ZEN uses the TRS80 ROM printer driver at 4025H.  Lines per page (4028H) are set at 66 only once -- on entering ZEN -- and are restored to the original value if the command "O" (Operating System) is executed.

When ZEN displays its command loop prompt, "Z>," the line counter at 4029H is set at 64 (bottom of a page), awaiting the formfeed from ZEN that preceeds any output using the E option.


9. Starting Up

Load the disk, and after DOS READY key "ZEN<ENTER>."  The title page is displayed on the video, and the program waits for a key input.   At this initial stage, ZEN responds differently to the following keys:

* = Examine memory for text using ZEN's pointers.

S = Examine memory for text using Scripsit's pointers.

Start and end of recovered text displayed in both cases.

The first command is equivalent to Basic *.  It is useful to re-boot the system including one caused by a de-bugging operation that goes wrong.

The second technique is a quick way to transfer text from Scripsit to ZEN.  It is also useful if Scripsit "crashes" with text in memory that has not been saved.  Scripsit's text is stored some 4000 bytes higher in memory than ZEN's normal usage.  So, using the S option, ZEN's symbol table is increased by that amount.

There are at least three versions of Scripsit for the Model 3.  Text starts at a different address in each version.  If you know where text starts in your version, the following patch will be useful:

PATCH ZEN/CMD (ADD=5232,FIND=627F,CHNG=xxxx), where xxxx is the text start address in the usual Z80 back-to-front format.

The video screen clears and ZEN displays the command-loop prompt:

Z>

ZEN now waits for a command.  Good Luck!  L.S.

Laurie Shields Software, 151 Longedge Lane, Wingerworth CHESTERFIELD, Derbys, England. S42 6PR.  Tel 0246 75568
>C=Y J=N LM=8


COMMAND SET
>C=N

Global Commands:

A ... Assemble
H ... Howbig                   I ... Increase numeric
K ... Kill                     S ... Sort character
O ... Operating system         XR .. Cross Reference


Cassette Commands:

RE .. Read   Edtasm            RO .. Read   Object
RS .. Read   Source
WO .. Write  Object            WS .. Write  Source
VE .. Verify Edtasm            VO .. Verify Object
VS .. Verify Source


Disk Commands:

R ... Read   source            W ... Write  source
WA .. Write  ASCII             DI .. Directory  numeric


Source Pointer Commands:

T ... Target numeric           U ... Up     numeric  also up-arrow
B ... Base                     D ... Down   numeric also down-arrow
L ... Locate string            P ... Print  numeric
p ... Line-print  numeric


Source Edit Commands:

E ... Enter Editor             N ... New  also comma
Z ... Zap   numeric            G ... Global  numeric


Debugger Commands:

C ... Copy                     F ... Fill
M ... Modify numeric           Q ... Query  numeric
J ... Jump  numeric            q ... Query to printer
X ... Xamine registers


Switches:

Y ... Toggle display format    y ... Toggle page pause

>LM=6
User Input

All user input to ZEN is via an intermediate text buffer, and no action is taken until <ENTER> is pressed, UNLESS:

You press the up or down arrows for scrolling, the comma for editing a line, or the clear key.  These keys are acted on immediately.

Input can be edited with the BACKSPACE (left arrow) and Shift Left Arrow (line clear) keys.  The right arrow is interpreted as a space.  Other user control keys may have a visible effect on the video screen, but they are not recognized by ZEN.

Command keys use letter(s).  Sometimes, the commands accept an optional parameter.  If a command requires more than one parameter, you are specifically prompted for it.

Numeric parameters may be Decimal (default), Hex ("H" postfix) or Octal ("O" postfix).

The default command of <ENTER> by itself, clears the video screen.

If the command syntax requires more than just the command letter, an example is displayed.  Otherwise, the command is the letter followed by the <ENTER> key.


Global Commands

H     HOWBIG:  displays the start and end addresses of the source
      file and also the highest available byte in RAM.


K     KILL:  erases the source file from memory.  After a KILL the start
      and end addresses of the file are equal.  This is also the state
      of the file when ZEN is initially entered.


A     ASSEMBLE:  assembles the source file from start of file to the
      END pseudo-op.  On entry you are prompted for the 
      source file location.   Default means the file is in-memory, otherwise any
      input is treated as a chain of filespecs separated by spaces.
      Second, ZEN will prompt for an output option, these are:

      V     VIDEO       (List to video).
      E     EXTERNAL    (List to external printer).
      F     FILE        (List to disk file ASCII format).
      C     CASSETTE    (System format).
      D     DISK        (Command file format).

      The default option produces no output.  This is the fastest mode;
      use it until all source errors are eliminated.  If the cassette or disk options are chosen you will be prompted 
      for either a filename or filespec.  If an execution address is
      not included in the source code ZEN defaults to 1A19H for
      cassette output and 402DH for disk output.  Under the F option the
      output list file is identical to the external printer list file,
      except the "top of form" codes are suppressed.

      When large programs (4k plus) are assembled to cassette,        it is better to assemble to disk and then use the
      MYSOSIS CMDFILE package to transfer from disk to cassette.  This
      technique is essential with larger programs.  Otherwise, the electrical
      noise from the disks ends up as glitches on the tape!

      Using the "F" option with Assemble, Sort and Xreference generates
      pure ASCII text disk files readable by ZEN, Scripsit and Pencil.
      When combined with Listoff and Liston, this option can save
      a considerable amount of time and paper during program
      development.  Beware of the possible error caused by
      loading object code direct to memory and then reading in the /LST
      file, which of course is much larger than the source file and
      clobbering the object code before debugging it.

      If ZEN is used to examine a listing file, use the "Y" command to
      switch off ZEN's auto line numbering.


S     SORT, alphabetically sorts the symbol table built during the
      previous assembly.  Adding a selector letter to the command
      restricts the display to symbols beginning with that letter.

      Example ... SG <ENTER> will give all labels beginning with G.

      On entry you will be prompted for an output option, these are:

      V     VIDEO    (the default option)
      E     EXTERNAL (printer)
      F     FILE     (disk)


XR    CROSS REFERENCE generates a list of the stored labels

      in the Symbol Table, their hexadecimal value, the line number of
      their occurrence and all references to them in the in-memory
      source file.  Output options are the same as SORT's.

      No selector letter is allowed.  It's all or nothing.


I     INCREASE increases the memory set aside for the symbol table
      by the numeric parameter, if there is enough memory
      available for the moved source file.  Otherwise, an error message
      is displayed.  It shows where the EOF would have resulted.

      Example ... I3000<ENTER> gives an increase of 3000 bytes to the
      symbol table and a corresponding reduction to the text buffer.


Notes on ZEN's symbol table -vs- OTHER assemblers.

Other TRS80 assemblers allocate fixed eight-byte blocks (16 by MYSOSIS) for symbols and their values.  This restricts them to labels of six character maximum (14 for MYSOSIS) with the other two bytes for the value.

This greatly simplifies their table lookup algorithms but of course is wasteful of memory as the full 8 or 16 bytes are used even for short labels.

ZEN, however, only allocates the number of bytes required by the length of the label, plus two for the value.  This permits labels of any length and maximizes the use of memory.  This feature is of less importance with the disk-based ZEN, but offers great advantage to the cassette 16K user.
 LD HL,CODE
LD BC,3
LDIR
LD DE,(UPC)
DEC DE
TRAP2: