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 / BEEHIVE / ZSUS / Z3HELP-6.LBR / ZA.LBR / ZCNFG.HZP / ZCNFG.HLP
Text File  |  2000-06-30  |  16KB  |  317 lines
  1. ;
  2.                                   ZCNFG.COM                                   
  3.  
  4.              Size (recs) CRC   Version    Author/Latest Issue      Disk
  5.                6k (46)   7D11  1.4        Al Hawley 11/89          Z3COM20
  6.  
  7.   1- Syntax  2- Configuration Displays  3- Notes  4- .CFG files  5- CFGLIB    
  8.  
  9.    ZCNFG is  a universal configuration utility which configures option data in
  10. executable files.  This is done by changing data  at  known  addresses  in the 
  11. first page  of program code.   ZCNFG  performs  this  editing  function  in  a 
  12. particularly convenient way.  Data options are displayed in one or more menus.
  13. The current selection for  each  option  is  displayed  as  part  of  the menu 
  14. information.  HELP screens can be invoked for assistance in selecting options.
  15.  
  16.    ZCNFG is universal because it uses  an  overlay file (.CFG) to  provide the 
  17. menu layout(s), Help screen(s), and data specifying the location and nature of
  18. each option.   An appropriate overlay must be  present for the target program; 
  19. ZCNFG loads it automatically or as a result of a command line specification.
  20. :1
  21.  
  22.    Syntax   ZCNFG [du/dir:]<nam1>[.<ex1>] [du/dir:][<nam2>][.<ex2>]
  23.  
  24.             ZCNFG  or  ZCNFG [/[/]]    <--  help screen (? may replace the /)
  25.  
  26.             du/dir: defaults to the current drive and user
  27.             <nam1> is the Executable file to configure.
  28.             <nam2> is the configuration overlay file.
  29.             <ex1>  defaults to COM, <ex2> defaults to CFG
  30.  
  31.  
  32.             Example:  ZCNFG ZCNFG      <--  configures itself.
  33.  
  34.    Items in brackets are optional;  defaults  are used when  they  are omitted
  35. from the command line.  
  36.  
  37.    A related configuration data file must be present to provide Screen layout, 
  38. Menus, and configuration data.
  39. :2
  40.  Configuration Displays - 1/2 
  41.  
  42.    ZCNFG configuration displays may take one of two forms.  The first consists
  43. of a  simple  ON/OFF 'toggle' or  reversible setting.   When you select one of 
  44. the menu options by pressing the letter  preceding  it, its  status is toggled  
  45. between the condition  displayed and  an  alternate function,  and your screen 
  46. depicts the new condition.  
  47.  
  48.    The other type of configuration is  for  programs  containing  configurable
  49. 'values' such as drive or filename specifications.  Simple ON/OFF toggles  are
  50. followed by a YES or NO status message  and  selecting  a toggle option simply  
  51. reverses the  YES  or  NO  message.   For  other options,  ZCNFG  prompts  for 
  52. additional information, displaying changes as they are made.
  53.  Configuration Displays - 2/2 
  54.  
  55. ZCNFG handles the following kinds of data:
  56.  
  57.        Logical toggle of any bit in a byte
  58.        Change the value of a byte with display/entry in Decimal
  59.        Change the value of a word with display/entry in Decimal
  60.        Change the value of a byte with display/entry in HEX
  61.        Change the value of a word with display/entry in HEX
  62.        Replace a string of ASCII characters
  63.        Replace or modify a DU specification
  64.        Replace or modify a Z3-style File Specification
  65.  
  66.    An acceptable range for numeric values can  be specified for  each  byte or 
  67. word value; values outside  that  range  will  not be  entered  in  the target 
  68. program.  The range is displayed for each item.   This is useful for entry of, 
  69. for example, a buffer size or  a ZCPR3 system file number.   The  last two are 
  70. useful for editing a default filespec.
  71. :3
  72.  ZCNFG Notes 
  73.  
  74.    a. Vs 1.4 updates:
  75.       - Reconfigured to allow for 256-byte  configuration  block in the target
  76.         program. 
  77.       - Added screen and cursor controls which become effective if  a Z-System
  78.         is  present.   ZCNFG functions  in  a  CP/M  system  without terminal-
  79.         specific functions.  
  80.       - Removed the option to use '$'  terminated  strings in the  .CFG files.
  81.         All strings must  be  null terminated.   This  change  was required to
  82.         accommodate the V4 VLIB routines  which do  not  accept the '$' string
  83.         terminator.
  84. :4
  85.  .CFG File 
  86.  
  87. The Configuration Overlay source file contains the following main sections:
  88.  
  89.          DEFINITIONS
  90.          MENU DATA STRUCTURE
  91.          CASE TABLE(s)
  92.          SCREEN IMAGE(s)
  93.          DATA FOR ALTERNATE SCREEN IMAGE FIELDS
  94.          HELP SCREEN DATA
  95.  DEFINITIONS 
  96.  
  97.  
  98.    This section defines symbols and macros used in  the balance of  the source 
  99. file.   Functions,  offsets,  screen locations, data, and local data addresses 
  100. are symbolically defined by EQU statements.   Two macros  are  provided in the 
  101. example file MODELCFG.SRC which greatly simplify the  construction of the case 
  102. tables.
  103.  MENU DATA STRUCTURE - 1/2 
  104.  
  105.  
  106. The first three code generating lines in the file MUST be:
  107.  
  108.           RST  0
  109.           DW   MENUA     ;or whatever label you use for menua:
  110. menua:    DW   LASTM,NEXTM,SCREENA,CASEA,HELPA
  111.  
  112. LASTM and NEXTM are pointers in a doubly linked circular queue of records like 
  113. that at menua:.   There is one record for each menu screen displayed by ZCNFG. 
  114. If there is only one menu screen (the case for many target program implementa-
  115. tions) then LASTM and NEXTM will both  be  replaced  with MENUA.  For  n  menu 
  116. screens, added menu records would be required.  For example:
  117.  
  118. menua:    DW   menun,menui,SCREENa,CASEa,HELPa
  119.           ....
  120. menui:    DW   menua,menun,SCREENi,CASEi,HELPi
  121.           ....
  122. menun:    DW   menui,menua,SCREENn,CASEn,HELPn
  123.  MENU DATA STRUCTURE - 2/2 
  124.  
  125.  
  126.    There is no requirement imposed  for  location  of  menu  records after the 
  127. first one (menua). ZCNFG finds the MENUA record at the specified offset in the 
  128. configuration overlay (offset is 3).  Any others are located through the links 
  129. LASTM and NEXTM.
  130.  
  131.    The RST 0 instruction is present to prevent this file  from being inadvert-
  132. ently executed.  A RET instruction could also be used here in many cases.
  133.  
  134.    The DW statement containing the symbolic address of the first  menu  record 
  135. is  used  for  run-time relocation  of pointers in  the  menu records and CASE 
  136. tables.
  137.  
  138.  CASE TABLE(s) - 1/7 
  139.  
  140.    There is one CASE table  for  each  menu screen.  The case table is labeled 
  141. and the label is  an entry in the associated  menu  record.   Each  case table 
  142. contains  a series  of records:  one record for each configurable item  in the 
  143. menu display,  and  one  initial  2-byte entry  which  specifies the number of 
  144. records present and the number of bytes in each record.  Since variable length 
  145. records are not implemented in ZCNFG,  the  record  length byte is always 0AH. 
  146. Here is the structure of each CASE record:
  147.  
  148. letter:   ds   1    ;ASCII code for the menu selector.
  149. function: ds   2    ;16 bit function number
  150. offset:   ds   2    ;16 bit offset of config data in target pgm.
  151. bdata:    ds   1    ;8 bit data required by function.
  152. scrnloc:  ds   2    ;16 bit address for data in the screen image.
  153. pdata:    ds   2    ;16 bit address of data required by function.
  154.  
  155. Menu items are  selected  by console input  of  a  visible character, letter:.
  156. Typical entries for letter: are "db 'A'", "db '1'", etc.
  157.  CASE TABLE(s) - 2/7 
  158.  
  159. function: defines one  of a  set of standard modifications that can be made to 
  160. data in the target program configuration area and to the ZCNFG screen display.
  161. For example, function 0 toggles  a  bit in  a  specified byte;  the associated 
  162. field in the menu display may toggle  between 'YES' and 'NO'.   The latter are 
  163. strings  whose address is  given  at 'pdata:',  so you have control of what is 
  164. displayed.   If you wished,  the display in this case  might be '1' and '0' or 
  165. 'True' and 'False'.
  166.  
  167. name:     function: used for:
  168.  
  169. switch       0      toggle bit <bdata> in the byte at <offset>
  170. text         1      edit <bdata> characters with UC conversion
  171. duspec       2      edit a byte pair as a DU specification
  172. hexrad       3      edit a configuration byte/word in HEX.
  173. decrad       4      edit a configuration byte/word in DECIMAL
  174. textlc       5      edit <bdata> characters, both UC and LC
  175. filesp       6      edit a Z3 filespec or filespec fragment
  176. togl3        7      rotate a bit in the 3 low bits at <offset>
  177. togltf       8      toggle byte at <offset> between 0 and 0ffH
  178.  CASE TABLE(s) - 3/7 
  179.  
  180. offset: specifies  the  relative  address  of  the  data  item  in  the target 
  181. program that is to  be configurable with  this menu selection.   'offset' is a 
  182. word (16 bit) quantity, even though  its  value  may  be  limited to the range 
  183. 0-7fH.
  184.  CASE TABLE(s) - 4/7 
  185.  
  186. bdata: is a byte whose value implies the size of the data in the configuration 
  187. block and how it  is  to  be  interpreted.   Functions 1 and 5,  for  example, 
  188. require bdata to specify the length  of  the text field  in  the configuration 
  189. block.  ZCNFG will abort with a diagnostic error message if the value of bdata 
  190. found in the CFG file is inappropriate for the function specified.
  191.  
  192. name:     function: 'bdata' entry required
  193.  
  194. switch       0      bit position to toggle, lsb = 0, msb = 7
  195. text         1      number of characters to replace
  196. duspec       2      0 for (A..P)=(0..15), 1 for (A..P)=(1..16)
  197. hexrad       3      1 for byte, 2 for word config data
  198. decrad       4      1 for byte, 2 for word config data
  199. textlc       5      number of characters to edit
  200. filesp       6      0= FN.FT, 1=Drive, 2=DU, 3=Full filespec
  201. togl3        7      7 ( = 00000111B)
  202. togltf       8      1  (one byte gets toggled 00/ff)
  203.  CASE TABLE(s) - 5/7 
  204.  
  205. scrnloc: is the address in the screen image at  which the ASCII representation 
  206. of the configuration data for  this  menu item is to  be  displayed.   This is 
  207. normally a label in the screen image source described below.
  208.  CASE TABLE(s) - 6/7 
  209.  
  210. pdata: is the address of data  used  by a function.   Some of the functions do
  211. not require this data.  In those instances, the value entered in this field is
  212. ignored, and is  normally 0000.   The following table shows what each function 
  213. requires of the 'pdata' field.
  214.  
  215. name:     function: 'pdata:' entry required
  216. switch       0      address of 2 null terminated strings
  217. text         1      0
  218. duspec       2      0
  219. hexrad       3      0 or address of min/max data words
  220. decrad       4      0 or address of min/max data words
  221. textlc       5      0
  222. filesp       6      0
  223. togl3        7      address of 3 null terminated strings
  224. togltf       8      address of 2 null terminated strings
  225.  CASE TABLE(s) - 7/7 
  226.  
  227. The min/max data words are a pair of 16 bit  values  which contain the minimum 
  228. and maximum  values  allowed  for  the  current  item  being configured.   For 
  229. example, Z3 system file numbers  are from 1 to 4.   The  data  provided in the 
  230. configuration file for this case would be:
  231.  
  232. sfilmm:   DW   1,4       ;minimum value first! Do NOT use DB!
  233.  
  234. SCRNLOC and PDATA are addresses within  the configuration file.   Because they 
  235. are relocated when the overlay is  loaded  by ZCNFG,  they  may  NOT designate 
  236. absolute addresses outside the overlay.   (For PDATA,  0 does not  specify  an 
  237. address.  It means that there are no limits for this numeric data item.)
  238.  SCREEN IMAGE(s) - 1/2 
  239.  
  240.    The screen image is  a  set  of DB statements that  specify  enough spaces, 
  241. data,  and CR,LF characters to 'paint' 18 lines of  the screen.   The  other 6 
  242. lines of a 24-line screen are taken up by the prompt message and user response
  243. lines at the bottom of the screen.
  244.  
  245.    The first statement of the screen image is labeled.   That label is part of 
  246. the MENU record, identified as SCREENa,  SCREENi,  etc. in  the description of 
  247. the menu record structure above.   Screen images are illustrated in the sample 
  248. *.SRC files.
  249.  
  250.    The 'data' just  mentioned comprises titles,  borders, and the text of menu 
  251. items that does not change.   Fields in  which  configurable  data  is  to  be 
  252. displayed  are  filled  with  spaces.   Such  fields  are  usually  made  into 
  253. independent labeled DB statements.  The label for such a statement is an entry
  254. in the case table record as 'scrnloc'.
  255.  SCREEN IMAGE(s) - 2/2 
  256.  
  257.    The entire  screen  image is  terminated  by  a  binary  zero ( db 0 or its 
  258. equivalent).  See the discussion below under 'HELP SCREEN DATA'.
  259.  
  260. TIP:  Don't forget to  put  the  menu item  selection characters in the screen 
  261. image near the data to be referenced!  This is how the user knows which key to
  262. press for a particular item..
  263.  DATA FOR SCREEN IMAGE FIELDS - 1/2 
  264.  
  265.    Functions 1, 2, 5, and 6 ignore any entries in the pdata: field.   They get 
  266. their data from the keyboard only.
  267.  
  268.    Two kinds of  data  structures  are  referenced by pointers at  pdata:  for 
  269. functions 0, 3, 4, 7, and 8.
  270.  
  271.    The first type  is composed of  DB statements that  define  null terminated 
  272. ASCII strings.   These strings appear in the menu to show the current state of 
  273. the configuration item addressed by this case  table record.   'yndata' in the 
  274. *.SRC example files is typical.   Note that  the order in  which  the  strings 
  275. occur is important: the one corresponding to 'true' comes first.  This type of
  276. data is required by functions 0, 7, and 8.
  277.  DATA FOR SCREEN IMAGE FIELDS - 2/2 
  278.  
  279.    The second type is  a DW data statement containing two  words.   The  first 
  280. word is a minimum value and  the second  is  a  maximum for  the  numeric data 
  281. addressed by this case.   This type is  used  with  functions 3 and 4 (HEX and 
  282. DECimal data).  If the POINTER value in pdata: is 0000h then no range checking
  283. will occur.   When Min/Max values are given,  they are displayed in the proper 
  284. radix in the prompt  line.   If the user attempts to enter a value outside the 
  285. indicated range, his entry is ignored.
  286.  HELP SCREEN DATA - 1/2 
  287.  
  288.    Help screens are accessed  via the '?' or '/' at the menu prompt.   A  help 
  289. screen should be provided for each menu,  even if  it contains  no more than a 
  290. 'help not available' message.  The help screen may be omitted if a 0000h entry
  291. is made in the MENU record (HELPa, HELPi, HELPn).  That causes ZCNFG to ignore
  292. help request (/ or ?) from the menu served by that record.
  293.  
  294.    Help screens are, like screen images, a block of DB statements which define
  295. the text to be displayed.   Help screens may be longer than  24 lines.   ZCNFG 
  296. counts lines and executes a display pause  for each screen-full of text.   You 
  297. control the  content  of successive displays by  adding  or removing line feed 
  298. characters in the DB statements.
  299.  
  300.    The entire block of ASCII text that comprises a HELP display,  which may be 
  301. displayed in multiple  screens,  is terminated with a binary zero (NOT a '$'). 
  302. This convention permits the use of  the $ character in  your  screen displays. 
  303. Since some early configuration files use the $ as  a terminator,  ZCNFG may be 
  304. configured to recognize that  character  as  the  terminator,  rather than the 
  305. null.  Such non-standard configuration should be temporary only.
  306.  HELP SCREEN DATA - 2/2 
  307.  
  308.    The help screen for each menu is labeled.   That label is  an entry (HELPa, 
  309. etc.) in the associated MENU record.
  310. :5
  311.                                  CFGLIB.REL
  312.  
  313.              Size (recs) CRC   Version    Author/Latest Issue      Disk
  314.                2k (10)   42B6  n/a        Al Hawley 12/88          Z3COM20
  315. ==============================================================================
  316.  
  317. CFGLIB contains the library routines for linking .CFG files.