Oakland CPM Archive/oakcpm.iso/cpm/asmutl/asmhelp.lbr/CHAP3.TQT/CHAP3.TXT

Text File | 1985-03-22 | 6.0 KB | 124 lines

                              CHAP03.TXT
                         Version 1.03 01/29/85
                        Bonnell Frost 74076,223
                        Robert Flagg 72466,2332

                          Chapter 3  Overlays

         The  main part of many programs is generic code--it will
operate  in very many CP/M,  usually Z80 and almost always  8080,
environments. However, most computers are a little different from
others,  and  this  particularly applies  to  the  communications
software.  Ports,  initialization sequences,  and screen clearing
sequences  all are individual things.  Consequently programs need
some easy way to be customized. One practical solution is the use
of overlays to contain the custom code.

         An  overlay  must  have a close  relationship  with  the
program  being  customized.  In particular,  the  specific  entry
points in the overlay must be known to the main program, and they
must be rigidly adhered to if a sequence of different overlays is
to  be  written and used.  In addition,  any utilities  that  the
overlay uses in the main program must have known entry points  so
that  they can be called easily.  Examples of overlays are to  be
found  in  Irv  Hoff's MDM7XX programs and in  Ron  Fowler's  MEX
program.  These  public  domain programs are available  for  many
different   computers  thanks  to  the  customization  capability
provided by overlays.

         In  almost all cases the program to be modified with  an
overlay  must be written with that in mind.  In those  few  cases
where  an overlay was not considered in the initial construction,
the programmer generating the overlay must essentially  shoe-horn
it into a location in the original code to accomplish his purpose
without  doing  violence to the original  intention.  Writing  an
overlay of this later type is not to be undertaken lightly.

        There are two different common methods for applying over-
lays to programs.  The older,  more traditional,  method uses the
utility  program DDT supplied with CP/M by Digital Research.  DDT
can  be  formidable,  but its use in installing overlays  can  be
handled as a canned procedure, even to the point of using a -.SUB
file.  The  second  method,  simpler and  less  intimidating,  is
through use of one of the versions of Ron Fowler's  MLOAD.  Let's
first consider MLOAD.

         MLOAD  is  available as an .AQM file or as a  .COM  file
from many boards.  While copyrighted,  it is in the public domain
in  so far as non-commercial use is concerned.  The documentation
here is derived from that supplied in the code by  Fowler.  MLOAD
allows  one  to start with either a .COM file or a .HEX file  and
apply the desired overlay as a .HEX file. The resulting .COM file
can  be either named the same as the original or as a  completely
new name, as you desire. The syntax of use is as follows:
.PA
        MLOAD [<outfile>=]<file1>[,<file2>...] [BIAS]
                (brackets denote optional items)

                <outfile> is the optional output file name
                <filen> are input file(s)
                <BIAS> is a hex load offset. (If you don't know what
                        this means, you don't need it.)

                <file1> may be an optional non-HEX (i.e., .COM)
                        file to be patched by subsequent .HEX files.
                        A non-HEX extension must be given, can't
                        be assumed.

         Some examples:

                MLOAD MEX.COM,KPO-41
                This sequence applies the overlay KPO-41.HEX to MEX.COM
                and stores the result in MEX.COM.

                MLOAD MDM7TEST=MDM720,MDM7US
                This command string loads the file MDM720.HEX,
                applies the overlay MDM7US.HEX and stores the result
                as MDM7TEST.COM.

         Also, ZCPR-style DU specs can be used with MLOAD21:

                B3>MLOAD A4:NEWFILE=0:OLDFILE,B6:PATCH1,A8:PATCH2
                This string, issued from B3, generates NEWFILE.COM
                in A4 from OLDFILE.HEX in A0, PATCH1.HEX in B6, and
                PATCH2.HEX in A8.

         This last shenanigan is likely to to needed rarely.

         Now let us consider the use of DDT.  Here the  operation
is  done  interactively,  not  as a consequence of  entering  one
command string.  Also,  bear in mind that the cue for DDT is a -.
Files given to DDT must be complete with extension.  One  vanilla
example:

         DDT MEXNEW.HEX
         DDT VERS 2.2   <---returned by the command
         NEXT PC        <---returned by the command
         6500 0100      <---returned by the command
         -iKPO-41.HEX   <---specify overlay file
         -r             <---read it in
         -g0            <---exit from DDT

         WARM BOOT      <---system response

         A>SAVE 65H  MYMEX.COM  <---create .COM file from memory image.
                --OR--
         A>SAVE 101  MYHEX.COM

        A  few  more things must be considered.  The "i"  command
sets up the overlay file to be read, the "r" command reads it and
applies  it to the code already in memory from the invocation  of
DDT.  G0  starts an execution at location 0,  which results in  a
WARM  BOOT.  SAVE simply reads 65H 256-byte blocks of memory  and
saves it as a COM file.   The generic CP/M SAVE command does  not
understand  a  HEX length,  so that the 65H must be converted  to
decimal 101 for it. The 65H comes from the first two bytes of the
length given by DDT. If ZCPR is being used, 65H is a lot simpler.
SAVE is stupid;  it will save it as MYJUNK.JNK if that's what  is
specified.  Oh, yes, a simple HEX to decimal algorithm: 16*(first
byte)+second  byte,  where  the  bytes are expressed  in  decimal
(i.e., A is 10,E is 14.).  In this particular instance, since the
last two bytes of "LAST" are zero,  the SAVE count is one  higher
than necessary, but this is not important unless the same program
is modified repeatedly, growing by 256 bytes each time.
sidered.  T