COMET SOURCE CREATOR
                    Geoff Bridges  July 1998

 This program is a utility to convert a CODE file into a  source
file which can be loaded into the COMET assembler.

  On running the program you will be prompted for three items of
data, the filename of the CODE file, the length of the code  and
the origin address of the code. Pressing  RETURN  at  the  first
prompt will give a directory of the disk.

 If there are more than one screen of directory entries pressing
SPACE at the scroll prompt will hold the  directory  listing  at
the current screen and return to the entry prompt.

  The file length can be up to 24k in  length;  if  the  desired
code file is greater than this then it should be split into  two
or more sections and decoded seperately.

  The origin address entered should be  the  memory  address  to
which the code is loaded (or paged) to for execution. This  will
be from 0 to 65535 and you may have to check the BASIC loader to
find the correct address.

  If the code length is too  long  and  has  to  be  split  into
shorter blocks then I suggest an overlap of approximatly  10  to
12 bytes as starting a disassembly part way through  a  mnemonic
will give incorrect results. Using an overlap helps  to  'match'
the code. Also remember to adjust the origin address to  reflect
the split code block.
  The selected Code file is then loaded into memory and is first
scanned to find and create any labels,  these  are  then  sorted
into assending order. The final operation is to disassemble  the
code and to tokenise it into a  form  acceptable  to  the  COMET
assembler.

  After tokenisation the program  will  display  the  number  of
labels used, the number of COMET workpages required to load  the
source code and  the  final  address  used.  You  will  then  be
prompted to save the code to a disc. The filename used  will  be
the original filename entered with a ".s" file extention added.

 If the source code  exceeds  the label buffer (1000 labels)  or
the COMET workpage allocation (24 pages) then the operation will
be aborted and an error message will be given.

  The COMET source created is in a  similar  form  to  a  normal
disassembler  listing,  showing  a  label  if  appropiate,   the
assembly language mnenomic, the bytes used and  the  ASCII  text
form of the bytes. Any text outside of the range 32 to 128  will
be indicated by a full-stop (.). All bytes are in  hex  notation
except for IX/IY displacements which are indicated in decimal.

  All addresses which are greater than the origin start  address
and below origin start + code length will be converted in  to  a
label. Any addresses outside the above range will  be  indicated
as a hex word ie. &1234.

  A created label is the hex word  preceded  by  a character ie.
A5678.

  Relative jumps (JR c,n; DJNZ n etc) will also be converted  in
to a label. Where a label refers to a byte  within  a  mnemonic,
not the first byte of a mnemonic as in the  example  below,  the
address relating to the first byte will be used.

  A3456:       LD A,number
               LD (A3457),&FF

  In the example the code is loading the address &3457 with  the
value &FF and as the converter program creates a label  for  the
start of the mnemonic line COMET will find an error if the  code
is assembled. In these cases the second line should be rewritten
as follows
               LD (A3456+1),&FF

  No attempt is made to decipher data tables  or  text  messages
and these will be decoded  as  Z80  mnemonics  as  in  a  normal
disassembler.

  The program was written as I needed to alter  a  code  routine
from SPECTRUM to SAM. My first method  was  to  disassemble  the
code and print it out.

 I then retyped the whole thing back into COMET and then,  after
debugging the inevitable typing errors I was able  to  make  the
alterations I wanted. As  this  was  a  rather  slow  process  I
altered a BASIC disassembler to tokenise the  code  to  a  COMET
format. This was faster than the above process but still  rather
slow, about 1 hour for approximatly 10k of  code.  It  was  also
bugged and gave some incorrect decoded output.  I  then  rewrote
the whole thing into machine code and now a code file of  approx
16k takes around 4 minutes to decode.  The  exact  time  depends
upon the number of labels created  and  the  code  length.  Also
'normal' mnemonics  take less time than extended (IY, IX, CB, ED
etc.) codes.

  Finally, as the COMET source code created can be very large it
is advisable to use the program from a full reset  or  switch-on
condition. This will also ensure the area  used  for  the  COMET
code is 'clean' before tokenisation!

              ------------------------------------