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 [=][,...] [BIAS] (brackets denote optional items) is the optional output file name are input file(s) is a hex load offset. (If you don't know what this means, you don't need it.) 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.