
Ron's Week'n'ADAM -September 2, 1997 by Ron Mitchell 

I have committed the ultimate transgression, for which there will 
be consequences no doubt.  I've taken the regal double blue back-
ground from Marcel de Kogel's home page and applied it to my  486 
DX4/120  as  wallpaper.  It serves to remind me which computer  I 
really like best.  Besides,  the result is quite impressive, if I 
do  say so myself.  Even with Windows 95 shortcuts plastered  all 
over it, it shows through well.

Enough of that.  There's been some re-organizing going on  around 
here over the past few days. I've ditched the 80 column Hazeltine 
1510  monitor  that has served my number one ADAM so well  for  7 
years  and  replaced it with a Cybernex XL87D.  The Cybernex  was 
connected  to the PMC,  and the PMC was connected to CPM  3,  and 
since David Cobley (dcobley@island.net) gave me another PMC  that 
was connected to an HP150 terminal and also to CPM 3,  the Cyber
nex  was  deemed more suitable for my 80 column TDOS ops and  the 
Hazeltine got fired.

This  bombshell  of  breaking news will generate  about  as  much 
interest as a penny in a bank vault,  but it gave me an opportun-
ity to review a few things.  They seem worth sharing. TDOS termi-
nal overlays quite frequently mess things up,  but if you have  a 
list  of  escape-codes for your terminal,  and a working copy  of 
SPZ,  or MLOAD,  you can do something about it. The CP/M and TDOS 
worlds are definately not 'plug and play',  but then what is?  In 
my  'snake pit' there are three 80 column terminals that  can  be 
used  with TDOS and either an Orphanware serial port or a  Micro-
Innovations MIB2 or MIB3.  The Hazeltine is in a storage cupboard 
unplugged, so make that two. These terminals, having been made by 
different manufacturers,  operate in a different manner from each 
other,  in that the programming required to control their various 
functions is not uniform between them. The terminals have what is 
known as a set of 'escape codes' which control functions such as:

     clearing the screen

     homing the cursor

     positioning the cursor

     turning off and on the inverse video

     turning off and on the half intensity video

     turning off and on the flash function

     deleting all characters from the cursor to the end of the line

     deleting all characters from the cursor to the end of the page

     cursor down, up, right, left

     saving the cursor positon

     recalling the cursor position

These are only a few, but they are the basic ones. Some terminals
give the programmer control over pre-set fields on the screen,  a 
choice of fonts and spacing, and more.

The  'escape codes' are usually made up of strings of characters, 
beginning with the 'escape' character,  27 ASCII or 1B Hex, foll-
owed by one or more other letters,  numbers or symbols.  And  so, 
the  process  of  clearing the screen on my Thomson CSF  and  the 
Cybernex requires that my program send the characters,  1B 45 Hex 
or ESCAPE E

The moment the terminal sees the ESCAPE character,  it knows that 
the sequence which follows is not meant to be put on the  screen, 
but rather to act as a control function.

So  much for the theory.  In practice,  what it means is that al-
though  the hundreds of CP/M programs available might run  on  an 
ADAM,  they  probably will not do so unless one of two things has 
occurred:


  1)      The programmer wrote them on an ADAM using exactly the 
          same terminal as the user has.

  2)      A choice of terminal overlays has been provided with the
          program in the form of 'patches' or an accompanying 
          installation program.

Without the proper terminal overlay,  your CP/M program might not 
interface  properly with your terminal,  and the results will  be 
visually unpretty.  Meanwhile, back in the snake pit, the Thomson 
CSF, which uses HEATH control codes, and the Cybernex were close, 
but not quite close enough.  How did I know that?  Well,  I tried 
running  MAINT.COM  that had been configured for  the  Hazeltine, 
that's  how.  The Hazeltine doesn't even use 1B Hex as an  ESCAPE 
character.  It  uses the ~ or tilde character plus a sequence  of 
hex characters. The resulting mess was not useful in the least.

So  then I tried running on the Cybernex a version  of  MAINT.COM 
that  had  been overlaid for my HEATH-like Thomson CSF  terminal. 
This time MAINT at least looked like MAINT, although there was no 
inverse highlighting. Fortunately, since I have terminal documen-
tation for both terminals,  I was able to discover why. The HEATH 
codes for inverse on and inverse off are:

                1B 70 Hex and 1B 71 Hex respectively.

whereas...

The Cybernex codes for that function are:

                1B 68 Hex and 1B 69 Hex

So close, but not close enough.


There are three ways of patching your TDOS or CP/M program. The
first is to use a program by Night Owl Software,  available where 
good CP/M utilities are sold (or given away as the case may  be), 
called  MLOAD.COM.  MLOAD  takes  one or more  source  files  and 
creates an output file. The source files will normally be; a) the 
file  to be patched,  and b) the appropriate overlay in Intel hex 
format.  So let's say,  for the sake of arguement, that you had a 
generic TDOS system file that you want to make compatible with my 
Cybernex terminal.  Let's further assume that my terminal overlay 
is called CYBERTRM.HEX,  and that the TDOS system file is  called 
80TDOS45.COM. The syntax would be:

        MLOAD 80TDOS45.COM=80TDOS45.COM,CYBERTRM.HEX

The  output  file produced would be called 80TDOS45.COM,  but  it 
would be with the Cybernex terminal codes.

Many  CP/M  programs are written in such a way as to  provide  an 
area for this overlay code in a standard position such that MLOAD 
knows  exactly where to put it.  All user needs to do is to  make 
sure  that  terminal overlay written in a  standard  format,  and 
assembled into an Intel HEX file is onhand.  In this manner, with 
MLOAD, the user can use the same terminal overlay for many diffe-
rent programs.

Unfortunately,  some  authors  think they can  invent  a  rounder 
wheel,  so they use non-standard methods of providing video cont-
rol. In this case, you first have to know where the terminal code 
is.  And secondly, you need a means of changing it, byte by byte. 
This is where you need the services of a good disk editor such as 
SuperZAP  (SPZ36.COM).  You can use a program such as SuperZAP to 
locate  the  area within the target program  where  the  terminal 
escape  codes are located,  and then simply go in and change them 
pursuant to your terminal documentation.

The third method of changing the terminal overlay within a  prog-
ram is to use a debug utility such as DDT, ZDDT, or Z8E to change 
the code. In this case, you would need to do a screen dump of all 
code  beginning at 0100H to locate the area to be patched.  In my 
experience,  this method is not as easy as using SuperZAP, but if 
you know what you are looking for, and approximately where it is, 
you can find it and change it,  byte by byte. You are looking for 
strings of code beginning with the hex characters 1B.  Unless  of 
course,  you're  a Hazeltine fan...  in which case you're looking 
for sequences beginning with 7E. Clear as mud, I know.

None of this is new of course;  the knowledge has been around for 
years. What I'd really like to impart however, my experience over 
the past two or three days,  is that there are some pointers that 
will make your life easier as you try to do this overly 'thing'.

1)      Never work on your original file. You may need to go back
        to it. Work on a copy of the file, preferably on another 
        disk.

2)      The overlay patch areas for terminal control is most often
        located at the beginning of a program, usually within the 
        first two hundred bytes. It can be recognized as a area 
        where there are a lot of "1B" sequences, and there may also 
        be more '0s' than anything else. Patch  areas are seldom 
        full.  They will probably begin with  0's and end with 0's 
        and it will usually be quite easy to tell  where the 
        programmer's code resumes following a patch area.

3)      It's all very well to say that you need your terminal
        documentation. If you've picked up some old venerable 
        cyclops at a garage sale or used junk store, you might 
        not have the docs to go with it. Frequently, if you go 
        online and ask the hobbyist community out there (such as
        the CP/M FIDO echo or the .alt.comp.os.cpm newsgroup) 
        somebody will have heard of your terminal and will have 
        the escape sequences for it.


In conclusion, it should be said that this is an area of TDOS and 
CP/M  knowledge  that  is not difficult to master,  and  where  a 
little perseverance and curiosity can go a long way.  Your payoff 
in  getting the terminal codes right for your programs  and  your 
system  is  that there are indeed hundreds of CP/M  programs  out 
there which are now pretty much free for the asking.


