home *** CD-ROM | disk | FTP | other *** search
/ ftp.barnyard.co.uk / 2015.02.ftp.barnyard.co.uk.tar / ftp.barnyard.co.uk / cpm / walnut-creek-CDROM / ENTERPRS / CPM / UTILS / S / ZCNFG21.LBR / ZCNFGHLP.LBR / ZCNFGOVL.DZC / ZCNFGOVL.DOC
Text File  |  1991-10-24  |  8KB  |  173 lines
  1.                       MAKING ZCNFG OVERLAY FILES
  2.                               Al Hawley
  3.  
  4.  
  5. ZCNFG needs a configuration overlay file for each target program
  6. that will be configured. The overlay files are by default recognized
  7. by ZCNFG when the file extension is '.CFG' and the filname is the
  8. same as that of the target program. If the name of the overlay is
  9. included in the target program at offset 0DH from the start of the
  10. program, then ZCNFG will use that name directly without mention on
  11. the invoking command line. The structure of configuration overlays
  12. is described in detail in ZCNFG.HLP. You should have it available
  13. for reference when using this implementation note.
  14.  
  15. This memo describes a procedure by which configuration overlays
  16. can be made with minimum effort and confusion. Carson Wilson has
  17. contributed a file (ZCNFGMDL.ZZ0) which is an excellent description
  18. of configuration overlays. You should study that file along with
  19. this one; you may wish to use IT to make your first configuration
  20. overlay. For multiple screens and a complex configuration, use of
  21. the following techniques will save time and aggravation, however.
  22. It is assumed that the target program contains configurable data 
  23. within the first 256 bytes of the program (for ZCNFG13 and earlier
  24. the limit is the first 128 bytes). 
  25. You will need the following programming tools:
  26.  
  27. 1. A text editor which can produce straight ASCII files. I use PMATE
  28. or WordStar in non-document mode. Many others are satisfactory. Use
  29. it to produce MENU and HELP SCREEEN images (.TXT files) and for
  30. assembler source files.
  31.  
  32. 2. A Relocating Macro Assembler and associated Linker. I used ZMAC
  33. and ZML for the procedures given below. The SLR and Microsoft will
  34. work with very few changes. Others can be used, but may require
  35. some changes to pseudo-op names.
  36.  
  37. 3. The TEXT2DB program, available from ZNODEs and other bulletin
  38. boards. This program converts a .txt file to an assembler source
  39. file of DB statements. MENU images require labels on some of these
  40. DB statements where fields in the image are to be programatically
  41. updated; TEXT2DB generates such labels according to your desires.
  42.  
  43. 4. An alias, MCFG.COM, is provided in this library to generate
  44. the final .CFG file. A similar alias can be written for use by
  45. an assembler/linker other than ZMAC/ZML.
  46.  
  47. 5. CNFGDEF.LIB which contains the Function and Macro definitions
  48. required for the code in ZCCFG.
  49.  
  50. The file names given as examples are part of ZCNFGCFG.LBR, the
  51. complete configuration overlay source for ZCNFG itself.
  52.  
  53. To make the overlay file, the following command is used:
  54.  
  55.     >MCFG ZCCFG ZCNFG
  56.  
  57. ZCCFG.SRC is the source file for the overlay and ZCNFG.CFG is
  58. the file produced. The MCFG alias invokes ZMAC to assemble the
  59. source file and then (if there are no errors) ZML to link the 
  60. resulting REL file to make the final .CFG file. The structure of
  61. ZCCFG is:
  62.  
  63.     <Program offset definitions>
  64.     INCLUDE CNFGDEF        ;ZCNFG related definitions
  65.     rst    0        ;first byte of code in the overlay
  66.     dw    menu1        ;required reference for relocation
  67. menu1:    dw    menu1,menu1,........(etc. see ZCCFG.SRC)
  68. case11:    <The CASE TABLE for the first menu screen>
  69. scrn1:    INCLUDE ZCSCR1
  70. help1:    INCLUDE ZCHLP1
  71.     ...
  72.     <DATA structures used by CASE tables>
  73.     end
  74.  
  75. If the configuration options are numerous enough to require
  76. several menu screens, then menu1:, case11:, scrn1:, and help1:
  77. are simply repeated for each screen with appropriate changes in
  78. labels, of course. (See ZCNFG.HLP)
  79.  
  80. To make a configuration overlay, start with the Screen Image(s),
  81. then make the CASE table(s), then the HELP files.
  82.  
  83. SCREEN Images
  84.  
  85. Use your editor to make the screen exactly as you want it to appear.
  86. Fields in the image that change during operation of ZCNFG such as
  87. 'YES'/' NO' or a place for numbers should be filled in with some
  88. visible character. I use 'zzz...' or the ASCII string that just fills
  89. the field. These are fields destined to be marked for labeling by
  90. TEXT2DB. There will be one such field for each configurable item
  91. in the target program configuration block.
  92.  
  93. The last five lines of a menu screen are reserved for use by ZCNFG.
  94. Thus, for a 24 line screen the menu itself must be 18 lines or less,
  95. including blank lines at the top of the screen.
  96.  
  97. After you are satisfied with the screen layout, INSERT an accent 
  98. character (`) before each such field. Then replace the dummy 
  99. characters in each field with spaces. The accent character is the 
  100. que that TEXT2DB uses to generate a label for that field. The
  101. label generated is of the form AAAnnn, where AAA is alphabetic and
  102. 'nnn' is a decimal number. You specify the first label for TEXT2DB
  103. to use; subsequent labels have the numeric part incremented so that
  104. each generated label is unique. The command
  105.  
  106.     TEXT2DB ZCSCR1 .LIB /SSCR100
  107.  
  108. generates ZCSCR1.LIB from ZCSCR1.TXT. The labels in the output file
  109. are SCR100:, SCR101:, etc. You will be using these labels when you
  110. generate the CASE table in the next step. If there are many of them,
  111. you may wish to make a printed copy of the .LIB file for reference.
  112.  
  113. CASE table
  114.  
  115. In this example, the Case Table is part of ZCCFG.SRC. If it is very
  116. large or if there are several such tables (for multiple screens),
  117. then you might wish to make an INCLUDE file of this one, too.
  118.  
  119. The case table is assembly source code prepared with a text editor.
  120. The details of its structure are described in ZCNFG.HLP. You will be
  121. filling in the argument list for one of the macros in CNFGDEF.LIB for
  122. each entry in the case table. These arguments are mostly symbols which
  123. are labels in the SCREEN (ZCSCR1.LIB), labels in the DATA area, 
  124. symbolic offsets in the target program, and parameters that tell ZCNFG
  125. what to do with the configuration data and screen field for each
  126. configuration item. The symbols used for ZCNFG parameters are defined
  127. in CNFGDEF.LIB. Detailed information for each field is in ZCNFG.HLP.
  128.  
  129. Two macros are provided which you can use to make Case Table records,
  130. BITMAP and VECTOR. The only difference between them is the treatment
  131. of the 6th bye of the record, 'bdata'. For function 0, this byte
  132. specifies the bit to be toggled in a configuration byte. The bit to
  133. be toggled corresponds to the bit that is set in bdata. The BITMAP
  134. macro simply translates an easier-to-enter number from 0 to 7 into
  135. a byte with exactly one bit set in the correct location. So, it is
  136. best to use the BITMAP macro for function 0, and the VECTOR macro
  137. for other functions. The use of tabs and spaces in the macro argument
  138. list is useful to keep the Case Table entries formatted so you can
  139. easily keep track of the identity of each argument; each argument type
  140. has its own column. 
  141.  
  142. Construction of the Case Table(s) is the most exacting task you will
  143. perform. Once you 'get the hang of it', it goes pretty fast.
  144.  
  145. The HELP screens
  146.  
  147. The files ZCHLP1.TXT and ZCHLP1.LIB are examples of the help screens
  148. you include in the .CFG file for the user to reference during a
  149. configuration session. There must be a help screen for each Menu,
  150. even if it only contains a 'HELP not available' message.
  151.  
  152. A help file may be as long as you wish. ZCNFG displays the help text
  153. with paging and a prompt on the bottom line of the screen. Each page
  154. is 22 lines long (2 lines are reserved for the prompt). A colon (':')
  155. as the first character on a line will force a new page. The colon is
  156. not displayed by ZCNFG versions after v1.8, but will be displayed by
  157. earlier versions (and ignored as a pageing signal). You can use this
  158. function to avoid having paragraphs split between screens, and you 
  159. can provide a space at the top of each screen. 
  160.  
  161. To generate the .lib file from the .txt file, use TEXT2DB. Since there
  162. are no labels in the help file, the /S option is not needed. Here's
  163. the command that generated ZCHLP1.LIB
  164.  
  165.     TEXT2DB ZCHLP1   .LIB
  166.  
  167. That's it. Now assemble and link!
  168.  
  169. -A tip about .TXT files-
  170. Don't throw them away! When you want to make changes to the .CFG
  171. file, you will save a lot of time by just modifying the old .TXT
  172. file and regenerating the .LIB file! 
  173.