home *** CD-ROM | disk | FTP | other *** search
/ CP/M / CPM_CDROM.iso / enterprs / cpm / utils / f / htc-ovl.lzh / HTC-OVL.DOC next >
Text File  |  1993-10-20  |  3KB  |  74 lines
  1.             ** Overlays with Hi-Tech C **
  2.  
  3.     The following procedure may be used to create overlays for use
  4. with Hi-Tech C. Although messy to compile and link, it results in a smaller
  5. TPA being used by a given program. Thus larger programs can be created: the
  6. only penalty is the time taken to load the overlay from disk.
  7.  
  8. 1. Creating the source files.
  9.     An overlay can be called from the main program using
  10.  
  11.     [value = ]ovloader(filename,argument);
  12.  
  13. where <filename> is a string containing the overlay's filename (without the
  14. .ovr extension) and <argument> is a single argument to the function. The
  15. result of the overlay may optionally be assigned to a value, as in any C
  16. function.
  17.  
  18.     The overlay may reference functions, global symbols etc. in the main
  19. program, but otherwise appears as a normal C program, except that the main
  20. function must be called ovmain() instead of main().
  21.  
  22. 2. Linking and producing the overlays.
  23.  
  24.     The main function must be linked first. Ensure that the modules
  25. ovloader.c and ovbgn.as (in that order) are linked as well, and request the
  26. compiler to produce a symbol table (-F option).
  27.     Once this has been completed, run the SYMTOAS program on the .SYM
  28. file (e.g. SYMTOAS TEST.SYM), and this will produce a file named MAIN.AS,
  29. containing the addresses from the main portion in assembler-source form.
  30. Then run ZAS on this (ZAS MAIN.AS), and this will produce a file named
  31. MAIN.OBJ. You will need this to link the overlays.
  32.     You will need to examine the MAIN.AS file, as you need the address
  33. of _ovbgn for the following step. Assume this is 01234h for the purposes
  34. of this explanation.
  35.     Compile the overlay(s) with the -C option to result in .OBJ files.
  36. Do not invoke the linker as this will result in many errors! When you have
  37. done this, make up a small ascii file (with wordstar etc.) to direct the
  38. linker. The format of this file should be as follows (NOTE: MUST be in lower
  39. case!):
  40.  
  41. -c01234h -ptext=01234h,data -otest1.ovr test1.obj <other modules as reqd> \
  42. main.obj 0:a:libc.lib
  43.  
  44. (assuming the overlay is to be test1.ovr, the source was test1.c). Other
  45. modules may be linked in as well. Note the use of the \ character to
  46. continue input onto the next line. Naturally, you should replace the '01234h'
  47. with the actual value of _ovbgn as obtained from the MAIN.AS file.
  48.  
  49.     Assume this file is named TEST.LNK. You are now ready to link the
  50. overlay. Use the command
  51.  
  52. LINK <TEST.LNK
  53.  
  54.     and it should rumble away to itself and complete. Note that you do
  55. not have to repeat the linking and loading of the main segment if you only
  56. change the overlay source: the same main.obj file may be used each time the
  57. overlay is re-linked. The TEST.LNK file should remain the same as well, but
  58. remember to alter it as necessary if you change the main program file.
  59.  
  60.     The OVBGN.AS file contains an equate to set the maximum overlay
  61. size: it is currently set to 5000h (20k). This should be sufficient for
  62. most purposes, but it may be lowered if your overlays are small. If you link
  63. the overlays with the -Mxxxx.MAP option in the .LNK file, a map of the
  64. overlay will be produced. Examination of this will show whether the max
  65. overlay size needs to be changed.
  66.  
  67.     Although messy, this process produces working overlays with Hi-Tech
  68. C. This compiler does seem to produce small, fast code for Z80 machines,
  69. and is probably worth persevering with.
  70.  
  71.             -- Ron Murray, 25/8/88
  72.  
  73.  
  74.