
                          P I K A S M -----------

Pikasm   is   an   assembler-editor  by  T.R.C.  featuring  data
compression,  a  64-column  editor,  conditional assembly, block
operations  and  other  conveniences. Many of Pikasm's functions
are  little  known,  and this manual serves to explain them. The
manual is organised as follows: editor, main menu, assembler,
configuration.

Pikasm  1.5  is  the  first  version for esxDOS, allowing direct
reading  and writing of source files on an SD/CF card. It builds
on Pikasm 1.1+, i.e. the version enhanced by Pevosoft with block
handling  and search. Version 1.5 is optimised in some functions
and  in  the  speed  of  character  printing,  includes  an init
(configurator)  and is stripped of the routines for working with
magnetic tape, which are replaced by esxDOS calls. Importing and
exporting  files  with  tape  emulation  is  easily available in
esxDOS  by  other  means,  using  a range of commands and system
utilities,  e.g.  directly  in the NMI/LFN Browser or in LnxCopy
for eZX/MB.

A  separate  utility  has  been  split  off  from the Pikasm+Mon
version,  a  dot  command  for esxDOS: .PIK2GENS, which converts
source files of the older GENS assembler into Pikasm format.


                           1. EDITOR
                           ---------

The  editor has 64 characters on 22 lines. The last-but-one line
shows the tab stops, the last line then shows:
 -  CAPS  LOCK  on  - file length - free space up to the working
 RAMTOP (in Workspace) - start of the source code (the Workspace
 boundary) - the value of the 16-bit system variable OPT.

1.1 Instructions

Instructions  are  typed  on the line with the cursor, and we do
not have to keep to the tab stops - the program always lines the
row up by itself.

Each line may start with a label (max 8 characters long). If the
label is omitted, at least one space must be inserted (otherwise
the  instruction  would be taken as a label). The exceptions are
the empty line and the comment line (prefix ;).

Then  follows  the  instruction itself (e.g. LD, NOP, ADD) or an
assembler pseudo-instruction.

Pikasm   handles   all   Z80  instructions,  including  all  the
~undocumented~ ones. These are:
      1) Instructions  working  with  the halves of registers IX
         and  IY,  which  we  write  as LX,HX,LY and HY (e.g. LD
         A,LX).  The  program  handles  prefix  errors  (e.g. LD
         LX,LY).
      2) The  left  shift  that  puts 1 into the zeroth bit. The
         program accepts both the SLL and the SLIA notation.
      3) Bit  instructions and shift instructions with transfer.
         These  are  RL,RR,RLC,RRC,SLA,SRA,SRL,SLL,SLIA,RES,SET.
         Interestingly,  the  program  also assembles BIT, which
         however   performs   no  transfer.  Notation  e.g.  RES
         6,C,(IX+10).

Pseudo-instructions  are  not processor instructions; they serve
mainly to control the assembly. They are:
      DB       Define  bytes. This directive must be followed by
               at   least   one  expression  <-255,255>.  (Note:
               several items are separated by commas (,)).
      DW       Define  words. This directive must be followed by
               at least one expression <-65535,65535>.
      Special types of expression are:
          Char:  Written  between  two  apostrophes.  Prefixes /
                 (slash) and ^ (arrow, power) are possible - see
                 text.
          Text:  Written between two double quotes, may be up to
                 47  characters  long.  Lowercase  and uppercase
                 letters  and  extended-mode  characters  can be
                 written. To insert a char+128 (e.g. a stopper),
                 write  the  prefix ^ before the char (e.g. ^a).
                 To  write  the  char ^ itself, use the prefix /
                 (/^). The prefix / also allows inserting other
                 codes:
                    //  = slash
                    /"  = double quote
                    /n  = chr 13, enter
                    /l  = chr 6, left
                    /0  = chr 0
          Sequence: A sequence of hex numbers introduced by a
                 colon  (e.g.  :AB0F). To include a character in
                 the  sequence, use the prefix ". For a char+128
                 use the prefix ^.
          Word:  To  insert a word among a row of bytes, use the
                 prefix >.
          Byte:  To  insert  a byte into a row of words, use the
                 prefix <.
      DS      Define space. Sets the number of reserved bytes in
              memory.  The  second  expression then sets what to
              fill the space with (e.g. DS 230 = 230 free bytes,
              DS  15,#ff  =  fifteen 255s). If you do not give a
              fill character, the reserved bytes are skipped and
              left unchanged.
      ORG     Start  of  assembly. This directive sets where the
              code  will  be  assembled  to.  An optional second
              parameter gives the address of the actual assembly
              (e.g. ORG 16384,50000 stores code that runs in the
              screen from address 50000).
      EQU     Assignment.  This  directive assigns the label the
              value  given  by the expression on the right (e.g.
              DESET EQU 10)
      OPT     Set local Options. See Options.
      OPSET   Set  certain local Options. An OR of the parameter
              with the local Options is performed.
      OPRES   Clear  certain local Options. A CPL and AND of the
              parameter with the local Options is performed.
      OPXHG   Toggle  certain  local  Options.  An  XOR  of  the
              parameter with the local Options is performed.
      ENTER   Entry point. This command sets the entry point for
              the  RUN  command (see later). The parameter gives
              the  address  directly;  without  a  parameter the
              current counter value is used (= ENTER $).
      IF      Condition.   Marks   the   start   of  conditional
              assembly.  If the expression is evaluated as true,
              the  part  of the program up to ENDIF (or ELSE) is
              assembled. If the expression is false, the part up
              to  ENDIF  is  ignored  (or the part after ELSE is
              assembled).
      ELSE    If  the  expression after IF was true, the part of
              the  program  up  to this command is assembled and
              the  following  part  is  ignored  up to the ENDIF
              command.  In  the  opposite case the first part is
              ignored and the second assembled.
      ENDIF   End of condition.
      BRON    Break  on.  Parameter  as  for  ENTER.  From  this
              command up to the BROFF command (or the end of the
              program),   jumps  into  Pikasm  allowing  program
              interruption  are stored in the resulting code. It
              must, however, be called from Pikasm (Run). Useful
              for   debugging  programs  (ability  to  interrupt
              infinite  loops).  At  final assembly, however, do
              not  forget  to turn this command off. Also beware
              of  problems  with  e.g.  JR  NZ,$+3  and  similar
              "absolute" constructions.
      BROFF   Break  off.  Turns  off  the  insertion of control
              jumps  into  the  code. By default it is on at the
              end of the program.

1.2 Operators and value notation

If   the   instruction   requires  it,  operands  (and  possibly
parameters)  follow  on  the  line. Expressions are an essential
part  of  operands  and parameters. An expression is basically a
sequence of labels (or values) and operators.

The operators are:
      1) unary. They work with only one parameter.
          . (dot)         Logical negation             (CPL)
          - (minus)       Opposite value               (NEG)
          + (plus)        can be omitted
          \ (backslash)   High byte
          / (slash)       Low byte
      2) binary. They stand between two expressions.
          + (plus)        Sum
          - (minus)       Difference
          * (asterisk)    Multiplication
          / (slash)       Division                     (DIV)
          \ (backslash)   Remainder after division     (MOD)
          & (and)         Bitwise AND
          | (pipe)        Bitwise OR
          ~ (tilde)       Bitwise XOR
          && (2x and)     And also, logical AND
          || (2x pipe)    Or, logical OR
          ~~ (2x tilde)   Exclusive or, logical XOR
          >               Greater than
          <               Less than
          >=              Greater than or equal
          <=              Less than or equal
          =               Equality
          <>              Inequality
          << (shift)      Rotate left (e.g. 10<<2)     (SLA)
          >>              Rotate right by N bits       (SRL)

     Note: beware of left-to-right evaluation (2+3*4 = 20)

Besides  labels, expressions also contain concrete values. There
are several ways of writing them.

     Prefix    Value
     None      Normal decimal notation
       #       Hexadecimal notation (e.g. #28FF)
       %       Binary notation (e.g. %01011000)

A  special  case  is  writing a single-byte value as a character
(see  also  DB,DW).  The  required  character  is placed between
apostrophes (').

Do  not  confuse  this with text, which is placed between double
quotes  (")  and  may  contain several characters. E.g. 'a' is a
normal  value equal to 97 and can be used in all expressions. In
contrast,   "a"   is   text   and   can  only  be  used  in  the
pseudo-instructions DB and DW.

Another  specialty  is  the  address  counter  $ (string). It is
always equal to the current address.

1.3 Control keys

The  editor  itself  has  a  range of useful built-in functions,
controlled by control keys:
 CS+1 ......   Move cursor left by tab stops.
 CS+SPACE      Move cursor right by tab stops.
 CS+8          Move cursor right.
 CS+5          Move cursor left.
 CS+7          Move cursor up.
 CS+6          Move cursor down.
 CS+2 (CAPS)   Toggle lowercase/uppercase.
 CS+3          Insert a space. The rest of the line moves right.
 CS+4          Delete  the char at the cursor position. The line
               moves left.
 CS+0          Delete the char to the left and move cursor left.
 CS+9          Insert one line before the current line.
 ENTER         Insert  one  line after the current line + cursor
               moves to the new line.
 CS+SS (EXT.)  Enter the menu.
 SS+W          Delete the current line.
 SS+Q          Remember the current line.
 SS+E          Insert the last remembered line.

Note.  If  data  is  lost at the end of a line after it is sent,
Pikasm indicates this with a coloured attribute.

1.4 Editor error messages

When  using ENTER, CS+7, CS+6, CS+9 and CS+SS, Pikasm checks the
syntax  of  the completed line. If something is not in order, it
prints one of the error messages:

Illegal character   An invalid character appears in the label of
                    the instruction or in the operands.
Bad operands        The  instruction  has operand(s) that do not
                    belong to it.
Label too long      A label longer than 8 characters was used or
                    declared.
Is a reserved word  A  label  was  used  or declared with a name
                    identical to a register designation.
Bad mnemonics       A   nonsensical  instruction.  E.g.  "joined
                    together" as LDA,1 etc.
Not closed          Missing quotes ending the text.
Character error     Use  of  the  prefix  / in text with a wrong
                    parameter.
Prefix error        An  instruction  operating with registers IX
                    or IY is not assemblable, e.g. ADD IX,IY.
Out of memory       Not  enough  free  memory,  need to increase
                    Workspace.

During  the  execution  of  some  editor  commands the following
errors may also arise:

Interrupted                Break   during   I/O   operations  or
                           interruption  of  a program with BRON
                           on.
Printer sequence invalid   The  character sequence being entered
                           does not have correct syntax.
Ramtop too low             Incorrectly set Workspace.
Invalid request            Attempt to RUN with an unknown ENTER,
                           or an error in block operations.

During  esxDOS  LOAD  and SAVE operations the following messages
may appear:

File not found             Load: the file does not exist.
                           Save: the target directory/path
                                 does not exist
Disk full                  Not enough space on the card
Out of memory              Load  only:  the file does not fit in
                           RAM  (behind  source + symbols, below
                           Workspace)
File exists, overwrite?    Save  only:  prompt  to overwrite the
                           file
Disk error                 another error


                         2. MAIN MENU
                         ------------

Pressing CS+SS switches us between the editor and the main menu.
The menu offers functions that are invoked by pressing the first
letter.

 2.1 Menu commands

 Asm           Start the assembly. See Assembler.
 Run           Run  the  program  from  the address given in the
               ENTER  directive.  (Not  possible  if  there were
               errors  during  assembly  or  no  entry point was
               entered.)
 Bas           Return to BASIC.
 Cpy           Copy a block.
 Del           Delete a block.
 Fnd           Search (mainly for labels).
 Nxt           Search for the next occurrence.
 Loa           Load (append) a file by the given name.
               A relative or absolute directory path may precede
               the file name, e.g.: SRC/SIPKA.SRC
 Sav           Save a file with the given name.
 Qpt           Sequence of characters sent to the printer at the
               starts  and  ends  of  pages  and  lines. Printer
               output is via channel #3.
 Opt           Options for the assembler. It is a 16-bit number
               whose set bits have these meanings:
               Value     Bit       Meaning
               1         0         At  the end of the listing an
                                   alphabetically sorted list of
                                   all labels is produced
               2         1         The  resulting  code  is  not
                                   physically stored
               4         2         No listing is produced
               8         3         Output to the printer
               16        4         Assembly   is   done   behind
                                   Workspace
               32        5         The    placement    of    the
                                   resulting code is not checked
               64        6         Output to the printer (as 3)
               128       7         Line numbers are not printed
               256       8         On error, jump to the editor
               512       9         Ignore the following text
               1024      10        Unused
               2048      11        Address listing in hex
               4096      12        Show   the   actual   storage
                                   address
               8192      13        Listing of the generated code
               16384     14        On  error  and  bit 8, do not
                                   wait for a keypress
               32768     15        For   Pikasm's  internal  use
                                   (Bron/Broff)
 Tab           Change  the  tab stops. Note: the program ignores
               the tab change as far as the placement of labels,
               instructions   and   operands   in  the  line  is
               concerned.
 Wrk           Set   the   top  of  the  source  space  (end  of
               Workspace, boundary of text+labels / start of the
               free space)
 Min           Lowest possible setting of the Workspace boundary
               (lowering  it  according  to  the  filled  text +
               labels).
               Min cannot be used before a valid assembly has
               produced a defined label table.
 Xlr           Erase all source text.

 In CS+SS mode the following paging keys also work:
  5, left      start of text
  6, down      one page forward
  7, up        one page backward
  8, right     end of text

2.2 Copying a block of lines

The  function  works  with a line block - when marking, only the
line  the  cursor is on matters, not its column position. In the
bottom line a menu appears:
   COPY > Frst Last Dest Quit 5B 8E 6+ 7- curs

You  can  move  through the text with the paging keys 5/6/7/8 or
with  the cursor keys. The block is marked in three steps, which
must be done in the following order:
      F (Frst)   Marks the first line of the block.
      L (Last)   Marks the last line of the block.
      D (Dest)   Marks  the  destination  line. After pressing D
                 the block is copied.

The  destination  must  not lie inside the selected block; the Q
(Quit) key can cancel the operation at any time without any
change.

2.3 Delete block

The  Del  command turns on the line-block deletion mode. As with
Copy, it works on whole lines. In the bottom line a menu
appears:
   DELETE > Frst Last Quit 5B 8E 6+ 7- curs

      F (Frst)   Marks the first line of the block.
      L (Last)   Marks   the  last  line  of  the  block.  After
                 pressing L the block is deleted at once.
      Q (Quit)   Cancels the operation without any change.


                          3. ASSEMBLER
                          ------------

Pikasm's  assembler  has  two  passes.  During  the  first,  the
assembler builds a table of labels and their values. During this
pass the following error messages may occur:

  Duplicate declaration:XXXXXXXX
         The  label  XXXXXXXX  appears  in  the  program and was
         defined more than once.
  Expression not defined
         An undefined expression was used in a
         pseudo-instruction.
  No table space
         Not  enough  free memory to build the label table. (the
         Workspace value must be increased)
  IF overflow
         More  than 15 IF commands nested into each other appear
         in the program.
  IF underflow
         More ENDIF commands than IFs.
  More IFs than ENDIFs
         Not all IF blocks are terminated with ENDIF.

After the first pass finishes, Pikasm announces:
      -1st pass finished..

and  the  second  pass  begins.  In  the  second pass the actual
program is generated. During this pass the following message may
appear:

  Bad ORG
         An  attempt  to  physically  write a byte into the area
         from  the  start  of  Pikasm  up to Workspace. Both the
         check  and  the  physical  write can be turned off with
         bits 1 and 5 (see Options).
  Out of range
         The  expression  takes  a  value  outside  the  allowed
         interval:  <-255,255>  byte,  <-65535,65535>  word  and
         <-128,127> relative addressing of jumps and index
         registers.

After the second pass finishes, Pikasm prints:
  Non defined symbols:

and  there  follows  a list of all labels that were not defined.
All  operations  with these labels are assembled as if the label
had the value 0.

If you have set bit 0 in Options, the assembler also prints:
  Defined symbols:

and  an alphabetical list of all defined labels. Finally we also
learn that
  2nd pass finished. Workspace used: x/y

where x is the number of bytes used for the working label table
and
    y is the number of free bytes from the end of the source
    text
up to the Workspace boundary.

The  form-feed  at  the  end  of assembly will be appreciated by
printer owners.

The  assembly  can  be  paused at any time by pressing SPACE and
then  ended  with the Q key (message 'Interrupted' and a jump to
the editor). Anything else continues the assembly.


                          4. CONFIGURATION
                          ----------------

The  loader  file  PIKASM15.COD  is  run  in the screen area. It
installs  the  actual  Pikasm executable, the file PIKASM15.BIN,
into  which it applies the values of the variables from the file
PIKASM15.CFG. These are:

colours
   PAPER=0
   INK=6
   BRIGHT=1

the working-space boundary (also settable from the menu, Wrk)
   WORKSPACE=54000

some bits of the OPT variable (also settable from the menu, Opt)
   LIST_SYMBOLS=1
   SUPPR_STORE=0
   SUPPR_LIST=1
   PRINTER=0
   BEHIND_WS=0
   NOADDRCHECK=0
   PRINT_FLUSH=0
   NOLINENUMS=0
   SHOWERRORS=1
   LIST_HEX=0
   NOLISTPAUSE=1

In  preparation  is the option to change the font, the character
routine and, very probably, the graphics mode (hires) as well.

PIKASM15.CFG may also be stored in the /SYS/CONFIG directory.


                          (C) RAXOFT Praha 02.32 a.m. 15.10.1990
                    also SOFTWARE 2000 OF CERES-SOFT 03.02.1991
                              extended by SCjoe in July 2026
