          A NEW OVERLAY MODULE FOR NEWDOS/80 VERSION 2
             JKL Routine with TRS-80 Graphic Blocks
     for the EPSON RX80 / FX80 and Centronics 739 Printers

                     by Joachim Kelterbaum
         (Frankenstr. 305, 4300 Essen 1, West Germany)

        Many NEWDOS/80 users find it quite convenient to be
able to get a screen dump to printer just by pressing the J-K-L
keys.  However, since the TRS-80 uses graphic blocks that are
not usually included in the character generators of printers,
it is not possible to make full use of this facility.  Some
printers, though, are able to do dot image graphics, and this
provides a means to simulate the TRS-80 graphic blocks.  In the
following article, a way will be shown to implement this
facility on NEWDOS/80 version 2 for the Epson RX80 / FX80 /
MX80 III printers.
        The first part of this article will deal with some
general aspects of the function of the DOS overlay loader.  In
the second part I'll explain the JKL module itself.  Part three
will deal with a method of incorporating a self-written overlay
into the system.

                 Function of the Overlay Loader

        Certainly you know that NEWDOS/80 is a sophisticated
operating system.  Such degree of sophistication would by no
means be possible if all of the system's functions were located
in RAM at all times (you could do that, but there would be very
little room left for user programs).  The solution to this
problem is the overlay technique.  This is accomplished in the
following manner:
        There is only one part of the system (SYS0/SYS)
permanently resident while NEWDOS/80 operates.  In addition,
there are approximately 20 overlay modules (SYS1/SYS to
SYS21/SYS), of which only one is resident at a time.  There are
2 overlay areas (the DOS overlay area at 4D00H-51FFH, and the
secondary overlay area - used mostly by BASIC - at
5200H-6FFFH).
        Each time a certain overlay is needed by the system,
the DOS overlay loader - part of SYS0/SYS - will load this
module to the overlay area (if that module is not loaded
already).  The module used before will simply be 'overlayed'.
I suppose that you can well imagine that this particular
function of the DOS is of vital importance to the system.  This
might be the reason why the function of the overlay loader is
hardly documented in the manual.  Obviously, the authors of
NEWDOS/80 - as well as of the other systems - do not want us to
fool around with the system.
        On the other hand, this overlay area is an ideal place
to put programs which do not use up any room in the user RAM
and which are practically invisible to the system.  But how can
one make use of this area?
        The answer to this is surprisingly simple.  There are
only 2 instructions needed: LD A,<code> ; RST 28H.  <code> is a
1-byte constant which must meet the following conditions:
        At least one of the high order three bits (bits 7, 6,
or 5) must be set.  The low order five bits (bits 4 through 0)
tell the system where in the directory the needed module is
located.
        To make it easier to understand the following, you
should turn on your computer and use the DFS (Display File
Sectors) option of SUPERZAP to display File Relative Sector
(FRS) 0 of DIR/SYS.  Normally (depending on your particular
PDRIVE setting) this is disk sector 170 on a single-sided,
single-density 40 track disk.
        FRS 0 is the GAT sector telling the system which tracks
are formatted and which ones are already allocated to files.
It also contains the disk name, date, and the AUTO command (if
used).  FRS 1 is the HIT sector.  This is used by the system as
a hash table for quickly finding a certain file on this disk.
Starting from FRS 2 the directory entries begin.  In the
relative position 0 (top row) you always find BOOT/SYS.  If you
turn to FRS 3 you will find DIR/SYS in the top row having
relative position 1.  The top row of FRS 4 will show the file
SYS0/SYS (relative position 2) and so on.  Once you have
reached FRS 9 of the DIR/SYS file (relative position 7 - in the
case of a disk that was formatted using the standard PDRIVE
parameter of DDGA=2, this is the end of the DIR/SYS file), you
can start over with FRS 2.  Now you count the entries in the
second row, starting with relative position 8 (SYS6/SYS will be
found there).  Exactly these position numbers are the values
you have to use in the constant <code> (low order 5 bits).  As
there will only be 5 bits decoded by the overlay loader you can
only address up to 32 overlay modules this way (actually only
30, since BOOT/SYS and DIR/SYS occupy the first two positions).
Let me give an example of an overlay call:
        If you wanted to call SYS5/SYS (DEBUG), you'd find this
entry at position 7 in the directory.  If you remember to set
one of the high order three bits (bit 7 in this case), your
value for code should be 1000 0111B = 87H.  So it is sufficient
to execute the following instructions for an overlay call to
DEBUG: LD A,87H ; RST 28H.
        Exactly this method will be used to load our
self-written JKL module.  You will find the details in section
three of this article.
        I must say a few words on what conditions a /SYS module
must meet in order to be loaded correctly by the overlay
loader:
        The module is a normal machine code routine which has
to reside in one piece on disk (no additional extents allowed).
The format of the module is the usual load file format which
for example is produced by EDTASM.  There has to be a start
address stated in the END statement.  This address will be
jumped to after loading the file via RST 28H.  The file need
not be positioned within the overlay areas (of course, if you
choose to have it load elsewhere, you must make sure that that
area of memory is somehow "reserved", so that you overlay
module won't overwrite another program already in memory).  If
you end your module with a RET instruction, a return will be
made to the calling routine (i.e.  the address on top of the
stack).
        If what you have just read encourages you to
experiment, please, do so on a backup system!!!  It is quite
likely that you will get some errors in the beginning.  These
errors will sometimes be 'honoured' by a destroyed system.  So,
be careful!!!

                   Function of the JKL Module

        You'll find the source code of the JKL module at the
end of this article.  First the printer is initialized, so that
the standard settings of 10 Characters Per Inch and 12 dots
linefeed will be used.  After this the first line of the video
RAM is loaded into the two buffers BUFTXT and BUFGRF.  The
buffer BUFTXT will now be modified to contain only printable
ASCII codes - i.e. graphic codes above 7FH will be replaced by
20H and control codes 00H-1FH will be shifted up by 40H so
they'll appear on the printer just like the characters being
displayed by the TRS-80 character generator (the one normally
supplied with the Radio Shack Model I lowercase modification,
which duplicates the uppercase character set for ASCII codes
00H-1FH).  In the buffer BUFGRF all codes below 80H will be
replaced by 80H.  This way we have a separation of text and
graphics.
        Now the program functions in the following manner: If a
line only consisted of text codes, this text will be printed
and a 12 dot linefeed will be done.  If there were graphics,
then first those graphics will be printed.  As it is not
possible to do a reverse linefeed with the MX80 III, only the
upper 2 blocks of that row are printed.  Then a 1 dot linefeed
is done.  After this the text is printed and a 7 dot linefeed
is done.  In a third phase the lower blocks of the graphics are
printed and a 4 dot linefeed is done.  This makes a full 12 dot
high line of mixed graphics and text.
        The whole procedure is repeated for all 16 video lines.
Finally, the printer is reset to normal again and a return to
the calling program (usually DOS or BASIC) is done.
        Though this procedure of a JKL-dump sounds quite
complicated, it works surprisingly fast.

  Hints for Installation of the Module to the NEWDOS/80 System

        After you have typed in the source using EDTASM or a
similar program, save it as SYSJKL/CMD on a working diskette.
Now, make a copy of your (naked) system on a different diskette
(COPY,0,1,,FMT,CBF,/SYS or similar).  Boot this system.  Now
you have to install a file at a particular position in the
directory (see section 1 of this article).  We will use
position number 1DH = 29 in this example.  To create a file
entry in position 1DH proceed as follows:
        (The method described here is not the most elegant one,
but it's the safest)
        Create several files using the CREATE command
(CREATE S0:0 ; CREATE S1:0 etc.).  Now use SUPERZAP's DFS
option again to display DIR/SYS.  Find the entry at position 29
(this will be found starting at FRS 7, byte 60H).  Write down
the name of this entry.  If there is no entry at this position,
continue creating files.
        Now, boot your system again and rename that file at
position 29 to SYSJKL/SYS.
        Finally, you can purge all those files that are not
needed any longer.  If you execute a DIR 0 now, you'll find
that SYSJKL/SYS is present as a normal visible file.  This does
not look very professional for a /SYS module.  Use SUPERZAP
again to change the first 2 bytes of the directory entry of
SYSJKL/SYS to 5FH, 20H.  Now, your file will only be displayed
by DIR 0 /SYS.  Now, copy the file SYSJKL/CMD to SYSJKL/SYS
onto your new system diskette and you're all set.
        The /SYS module is installed now, but your system will
not recognize that it is there.  In the Model I version of
NEWDOS/80, the normal JKL routine is located in SYS3/SYS,
FRS 4, starting at byte 96H (byte 73H on the Model III version
of NEWDOS/80).  At this place we apply the call to our own
module: LD A,9DH ; RST 28H, which is 3EH, 9DH, EFH.  Once you
have zapped those three bytes, your module will work.
        Boot your system and try it.  Don't forget to copy
BASIC/CMD as well as all other programs you need to your new
system.
        Happy JKL-ing!
                                            Joachim Kelterbaum


NOTE:  This disk contains two versions of this program:
EPSONJKL/ASM, for use with Epson and compatible printers, and
CENTRJKL/ASM, for use with Centronics 739 printers.  The
Centronics 739 version is not commented.
 