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 / ZCFG.HZP / ZCFG.HLP
Text File  |  1991-10-16  |  22KB  |  428 lines
  1. ;
  2.                      WRITING CONFIGURATION (CFG) FILES 
  3.  
  4.                                     FOR
  5.  
  6.                                  Z C N F G
  7.  
  8.  
  9.                       I -->  Introduction            
  10.                       D -->  Definitions             
  11.                       O -->  Overlay Header          
  12.                       M -->  Menu Pointer List       
  13.                       T -->  Case Table              
  14.                       S -->  Screen Image            
  15.                       F -->  Field Data for Screens   
  16.                       H -->  Help Screen Image Data   
  17.                       U -->  Using ZCNFG             
  18. :I
  19. INTRODUCTION
  20.  
  21. Configuration (CFG) files are complex but they need not be difficult to 
  22. write.  The easiest way to write a CFG file is to start with the source 
  23. code for a CFG file that you have already used and like, and use it for a 
  24. model.  Most recent libraries for ZCPR3 utilities contain both a CFG file 
  25. and its source code.  The file ZCNFG21.LBR contains several files that you 
  26. will find useful in understanding and implementing a configuration file:
  27.  
  28.      ZCNFGMDL.Z80   a sample configuration file.
  29.      ZCNFGCFG.LBR   the configuration source for ZCNFG
  30.           (includes Alias MCFG.COM, for making CFG files)
  31.      ZCNFGOVL.DOC   step by step instructions for making ZCNFG.CFG
  32.  
  33. It is extremely useful to study a working CFG source file to see how the 
  34. structures covered here work in practice.  Print out the source code for a 
  35. model CFG file and refer to it as you use this help file.
  36. The Configuration File
  37.  
  38. The configuration (CFG) file is an overlay loaded at run time by ZCNFG.  It 
  39. contains the data required by ZCNFG to allow a user to configure the 
  40. operation of a specific target program file.  The overlay conventionally 
  41. has the same name as the file to be configured, and a filetype of CFG.  It 
  42. is created by assembly of a standard Z80 source file to produce a binary 
  43. image.  An Origin (ORG) statement is not required in the source file 
  44. because the image is automatically relocated during loading at run time.  
  45. The relocation depends on the OVERLAY HEADER being present as the first 
  46. code producing item in the source file.  This requirement is discussed in
  47. the sections on 'OVERLAY HEADER' and 'MENU POINTER LIST'. 
  48. Configuration Functions
  49.  
  50. A common configuration function is a choice based on the value of a byte 
  51. (zero/non-zero) in the target program.  Such bytes appear in the ZCNFG menu 
  52. as 'YES' or 'NO' (or any other set of descriptive terms you like), and are 
  53. toggled when that menu item is selected.  ZCNFG can also:
  54.  
  55.        Toggle any bit in a byte (8 YES/NO choices)
  56.        Rotate a bit within a field of bits in a byte (multiple choice)
  57.        Change the value of a byte with display/entry in HEX or Decimal
  58.        Change the value of a word with display/entry in HEX or Decimal
  59.        Replace a string of printable ASCII characters
  60.        Replace a single ASCII character (including non printable)
  61.        Replace or modify a DU specification
  62.        Replace or modify a Z3-style File Specification
  63.  
  64. You can specify an acceptable range for numeric values for each byte or 
  65. word value.  Values outside that range will not be entered in the target 
  66. program.  The range is displayed for each item if it has been specified.  
  67. This is useful for entry of, for example, a buffer size or a ZCPR3 system 
  68. file number.  The last two are useful for editing a default filespec.
  69. The CFG File Structure
  70.  
  71. The CFG source file contains the following main sections:
  72.  
  73.          DEFINITIONS
  74.          OVERLAY HEADER
  75.          MENU POINTER LIST for first menu
  76.          CASE TABLE for first menu
  77.          SCREEN IMAGE for first menu
  78.          HELP SCREEN(s) for first menu
  79.          FIELD DATA for SCREEN IMAGES
  80.  
  81. When more than one menu is needed, four sections are repeated:
  82.  
  83.          MENU POINTER LIST for each additional menu
  84.          CASE TABLE for each additional menu
  85.          SCREEN IMAGE for each additional menu
  86.          HELP SCREEN(s) for each additional menu
  87.  
  88. See the main menu for details of each of these sections.
  89. Target Program Structure
  90.  
  91. The program for which the CFG configuration overlay file is being written 
  92. is called the Target Program.  All configurable data in the Target Program 
  93. must be located in the first page (256 bytes) of the program.  The Target 
  94. should contain the name of the default CFG file at relative location 0DH 
  95. (right after the Z34 header).  ZCNFG examines up to 8 bytes and will assume 
  96. a possible filename if it is terminated with enough spaces to make 8 bytes 
  97. or if it is terminated by null, $, or High-bit-set for the last character.  
  98. In other words, if the string looks like a legal file name, it is taken as 
  99. the name portion of the overlay filespec.
  100.  
  101.      TIP: Don't try to save bytes by terminating the CFG filename before 
  102.      the 8 bytes allowed. Put the filename left justified in a field of 8 
  103.      blanks.  That way, there is room for configuration of the filename 
  104.      itself!
  105.  
  106. The object of this strategy is to permit normal invocation with an implied 
  107. overlay filespec.  If the target program contains the name of its overlay 
  108. file as described, the overlay is very likely to be found even if the 
  109. target program has been renamed.
  110. :D
  111. DEFINITIONS
  112.  
  113. This section defines symbols and macros used in the balance of the source 
  114. file.  
  115.  
  116. Functions provided by ZCNFG are referenced by function number.  These 
  117. function numbers are given names in CFGDEF.LIB via EQU statements.  By 
  118. including this file in your source, the names can be used as entries in CASE 
  119. tables. Function names are only used in your source; change them if you like.
  120.  
  121. You must provide offsets in the configuration page for configurable items; 
  122. this is best accomplished by defining them symbolically  (EQU statements) for 
  123. ease in constructing the CASE tables.  
  124.  
  125. CFGDEF.LIB includes two macro definitions which greatly simplify the 
  126. construction of case tables.  Their use is illustrated in ZCNFGCFG.LBR and 
  127. the other overlay model files. 
  128. :O
  129. OVERLAY HEADER
  130.  
  131. The first three code generating lines in the file MUST be:
  132.  
  133.           RST  0
  134.           DW   MENUA     ;or whatever label you use for menua:
  135. MENUA:    DW   LASTM,NEXTM,SCREENA,CASEA,HELPA
  136.  
  137. The RST 0 instruction is present to prevent this file from being 
  138. inadvertently executed.  A RET instruction could also be used here in many 
  139. cases.
  140.  
  141. The DW statement containing the symbolic address of the first menu record 
  142. is used for run-time relocation of pointers in the menu records and CASE 
  143. tables.
  144.  
  145. The list of five symbols which follow at MENUA: comprise the MENU POINTER 
  146. LIST for the first menu.  This list must be located here at offset 3 in the 
  147. file because ZCNFG uses it in connection with the value in the preceding DW 
  148. statement for relocation of all pointers when this overlay is loaded.
  149. :M
  150. MENU POINTER LIST
  151.  
  152. LASTM and NEXTM are pointers in a doubly linked circular queue of records 
  153. like that at MENUA:.  There is one record for each menu screen displayed by 
  154. ZCNFG.  If there is only one menu screen (the case for many target program 
  155. implementations) then LASTM and NEXTM will both be replaced with MENUA.  
  156. For n menu screens, added menu records are required.  For example:
  157.  
  158.   MENUb:    DW   MENUn,MENUi,SCREENb,CASEb,HELPb
  159.               ....
  160.   MENUi:    DW   MENUb,MENUn,SCREENi,CASEi,HELPi
  161.             ....
  162.   MENUn:    DW   MENUi,MENUa,SCREENn,CASEn,HELPn
  163.  
  164. There is no requirement imposed for location of menu records after the 
  165. first one (MENUA).  ZCNFG finds the MENUA record at the specified offset in 
  166. the configuration overlay (offset is 3).  Any others are located through 
  167. the links LASTM and NEXTM. For the same reason, all other sections in the
  168. overlay file may be in any order that you feel appropriate.
  169.  
  170. :T
  171. CASE TABLE(s)
  172.  
  173. There is one CASE table for each menu screen. The case table is labeled and 
  174. the label is an entry in the associated menu record.  Each case table 
  175. contains a series of records: one record for each configurable item in the 
  176. menu display, and one initial 2-byte entry which specifies the number of 
  177. records present and the number of bytes in each record.  Since variable 
  178. length records are not implemented in ZCNFG, the record length byte is 
  179. always 0AH.  Here is the structure of a CASE TABLE:
  180.  
  181.      CASE0:  DB (RCRD0X-RCRD00)/0AH  ;number of records
  182.              DB 0AH                  ;record length
  183.      RCRD00: ds 10                   ;first CASE record
  184.              ....
  185.      RCRD0n: DS 10
  186.              ....
  187.              DS 10                   ;last CASE record
  188.      RCRD0X:                         ;empty label for length expression
  189.  
  190. Here is the structure of each CASE record:
  191.  
  192.      ITEM:     ds   1    ; ASCII character for the menu item selection.
  193.      FUNCTION: ds   2    ; 16 bit function number.
  194.      OFFSET:   ds   2    ; 16 bit offset of config data in target pgm.
  195.      BDATA:    ds   1    ;  8 bit data required by function.
  196.      SCRNLOC:  ds   2    ; 16 bit address for data in the screen image.
  197.      PDATA:    ds   2    ; 16 bit address of data required by function.
  198.  
  199.  
  200. ITEM is the ASCII character input from the console by the user to 
  201. select a menu item.  Typical characters are "db 'A'", "db '1'", etc.
  202.  
  203. OFFSET specifies the relative address of the data item in the target 
  204. program that is to be configurable with this menu selection.  OFFSET is a 
  205. word (16 bit) quantity, even though its value is in the range 0-ffH.
  206.  
  207. SCRNLOC is the address in the screen image at which the ASCII 
  208. representation of the configuration data for this menu item is to be 
  209. displayed.  This is a label in the screen image source described below. 
  210.  
  211. FUNCTION defines one of a set of standard modifications that can be made 
  212. to data in the target program configuration area and to the ZCNFG screen 
  213. display.  For example, function 0 toggles a bit in a specified byte; the 
  214. associated field in the menu display may toggle between 'YES' and 'NO'.  
  215. The latter are strings whose address is given at PDATA, so you have control 
  216. of what is displayed.  If you wished, the display in this case might be '1' 
  217. and '0' or 'True' and 'False'.
  218.  
  219.      Name     Function   Purpose
  220.      ------   --------   ------------------------------------------
  221.      SWITCH       0      Toggle bit <bdata> in the byte at <offset>
  222.      TEXT         1      Edit <bdata> characters with UC conversion
  223.      DUSPEC       2      Edit a byte pair as a DU specification
  224.      HEXRAD       3      Edit a configuration byte/word in HEX.
  225.      DECRAD       4      Edit a configuration byte/word in DECIMAL
  226.      TEXTLC       5      Edit <bdata> characters, both UC and LC
  227.      FILESP       6      Edit a Z3 filespec or filespec fragment
  228.      TOGL3        7      Rotate a bit in an n-bit field of the byte 
  229.                          at <offset>. If n=3: 001B/010B/100B
  230.      TOGLTF       8      Toggle byte at <offset> between 0 and 0ffH 
  231.      ASCIIC       9      Replace byte with single byte keystroke
  232.  
  233. BDATA is a byte whose value implies the size of the data in the 
  234. configuration block or how it is to be interpreted.   Functions 1 (TEXT) and 
  235. 5 (TEXTLC), for example, require BDATA to specify the length of the text 
  236. field in the configuration block.  ZCNFG will abort with a diagnostic error 
  237. message if the value of BDATA found in the CFG file is inappropriate for the 
  238. function specified.
  239.  
  240.      Name     Function   BDATA entry required
  241.      ------   --------   ------------------------------------------
  242.      SWITCH       0      Bit position to toggle, lsb = 0, msb = 7
  243.      TEXT         1      Number of characters to edit with UC conversion
  244.      DUSPEC       2      0 for (A..P)=(0..15), 1 for (A..P)=(1..16)
  245.      HEXRAD       3      1 for byte, 2 for word config data
  246.      DECRAD       4      1 for byte, 2 for word config data
  247.      TEXTLC       5      Number of characters to edit (UC and LC)
  248.      FILESP       6      0= FN.FT, 1=Drive, 2=DU, 3=Full filespec
  249.      TOGL3        7      7 (=00000111B) Mask for a 3 bit field at bit 0
  250.      TOGLTF       8      1  (one byte gets toggled 00/ff)
  251.      ASCIIC       9      1  (one byte gets replaced)
  252.  
  253. Data for Function 7 is explained in the next screen.
  254. BDATA FOR FUNCTION 7
  255.  
  256. FUNCTION 7 actually rotates a bit in a field of n bits, where n is 2 to 8.  
  257. BDATA for this function is a mask whose bits are set (1) corresponding to the 
  258. field required.  Only one bit is set in the field, and each invocation of 
  259. function 7 rotates that bit left one position in the field. TOGL3 uses this 
  260. bit position to select 1 of n strings to display; the target program uses the 
  261. bit position to select 1 of n alternate action/configuration choices. In the 
  262. example on the previous screen, the bit field has 3 values: 001, 010, and 
  263. 100.  Other bits in the byte are unaffected. Here are some examples of valid 
  264. mask bytes and the associated bit fields produced:
  265.  
  266.      00011000  ...01... , ...10...      (.. are unaffected bits)
  267.      00111000  ..001... , ..010... , ..100...
  268.      11110000  0001.... , 0010.... , 0100.... , 1000....
  269.  
  270. Bit fields must be contiguous. The following are examples of invalid masks:
  271.  
  272.      11000011 , 1011100 , 00110110 
  273.  
  274. PDATA (see below) points to a list of strings. There must be as many strings 
  275. there as there are set bits in the bit mask.
  276.  
  277. PDATA is the address of data within the configuration file used by a 
  278. function.  Because it is relocated when the overlay is loaded by ZCNFG, it 
  279. may NOT designate an absolute address outside the overlay.  
  280.  
  281. The following table shows the PDATA entry required by each function: 
  282.  
  283.      Name     Function   PDATA entry required
  284.      ------   --------   ------------------------------------
  285.      SWITCH       0      Address of 2 null terminated strings
  286.      TEXT         1      0 or address of a terminator byte
  287.      DUSPEC       2      0
  288.      HEXRAD       3      0 or address of min/max data words
  289.      DECRAD       4      0 or address of min/max data words
  290.      TEXTLC       5      0 or address of a terminator byte
  291.      FILESP       6      0
  292.      TOGL3        7      Address of n null terminated strings
  293.      TOGLTF       8      Address of 2 null terminated strings
  294.      ASCIIC       9      0
  295. :S
  296. SCREEN IMAGE
  297.  
  298. The Screen Image is a set of DB statements that specify enough spaces, 
  299. data, and CR,LF characters to 'paint' 18 lines of the screen.  The other 
  300. 6 lines of a 24-line screen are taken up by the prompt message and user 
  301. response lines at the bottom of the screen.
  302.  
  303. The first statement of the screen image is labeled.  That label is part of 
  304. the MENU record, identified as SCREENa, SCREENi, etc, in the description of 
  305. the menu record structure above.  Screen images are illustrated in the 
  306. model CFG source file ZCNFGMDL.Z80.
  307.  
  308. The screen image data comprise titles, borders and the text of menu items 
  309. that does not change.  Fields in which configurable data is to be displayed 
  310. are filled with spaces and must be at least as long as the configurable 
  311. data (See next screen for field lengths).  Such fields are usually labeled 
  312. DB statements.  The label is an entry in the case table record at SCRNLOC. 
  313. The entire screen image is terminated by a binary zero. 
  314.  
  315. Data from the configuration block is translated to human-readable form on 
  316. the screen. The space required in the screen image is summarized in the
  317. following table. Use these field sizes to avoid a scrambled display.
  318.  
  319.      Name     Function   Minimum Field Length in Screen Image
  320.      ------   --------   ------------------------------------
  321.      SWITCH       0      Length of null terminated data strings
  322.      TEXT         1      Length specified in BDATA
  323.      DUSPEC       2      3  (examples: 'A15', ' B3')
  324.      HEXRAD       3      2 for byte data, 4 for word data
  325.      DECRAD       4      3 for byte data, 5 for word data
  326.      TEXTLC       5      Length specified in BDATA
  327.      FILESP       6      16 for DU:FN.FT, 12 for FN.FT only
  328.      TOGL3        7      Length of null terminated data strings
  329.      TOGLTF       8      Length of null terminated data strings
  330.      ASCIIC       9      3 (examples: "  A", " ^X", "DEL")
  331.  
  332. Alternate data strings in the CFG file for functions 0, 7, and 8 must 
  333. be filled to the same length to avoid unwanted characters in the display.
  334.  
  335.  
  336. The easiest way by far to prepare a screen image is to create a text file 
  337. using a screen oriented editor like ZMATE, WordStar, or ZDE in non-document 
  338. mode. Make the image just like you want it to appear, including the spaces 
  339. for ASCII configuration data to be displayed. Fill those fields with 
  340. visible fill characters so you can see them. When the display is as you 
  341. want it, INSERT an unique character before each field. (an accent mark (`) 
  342. or tilde (~) is usually unique.) That character will be recognized by 
  343. TEXT2DB as the place to create a label instead of the mark. Now running 
  344. TEXT2DB on the text file will create a file of DB statements which have 
  345. been labeled with unique labels where they are required.  These labels 
  346. are the ones which you transfer to the associated CASE table records. 
  347. (See also the section 'HELP SCREEN DATA'.) 
  348.  
  349.      TIP:  Don't forget to put the menu ITEM selection characters in the 
  350.      screen image near the data to be referenced!  This is how the user 
  351.      knows which key to press for a particular item.
  352. :F
  353. FIELD DATA FOR SCREENS
  354.  
  355. Functions 2 (DUSPEC), 6 (FILESP) and 9 (ASCIIC) get their data from the 
  356. keyboard. Functions 1 and 5 use a pointer at PDATA, described later.
  357.  
  358. Two kinds of data structures are referenced by pointers at PDATA for the 
  359. other functions.  The first type of data is required by functions 0 
  360. (SWITCH), 7 (TOGL3) and 8 (TOGLTF).  It is composed of DB statements that 
  361. define null terminated ASCII strings.  These strings appear in the menu to 
  362. show the current state of the configuration item addressed by this case 
  363. table record.  T3MSG for function 7 (TOGL3) and YNDATA for function 8 
  364. (TOGLTF) are two examples.  Messages at each label must be of the same 
  365. length and may include 01h and 02h to control standout video:
  366.  
  367.      YNDATA:      DB   1,'YES',2,0     ; Displayed when value is 0FFh
  368.                   DB   1,' NO',2,0     ; Displayed when value is 000h
  369.  
  370. Example from ZMAC for BDATA = 00000111 (n = 3 bit field)
  371.      T3MSG:       DB   '.LALL',0 ; List ALL MACROS if value is 001B   
  372.                   DB   '.SALL',0 ; Suppress MACROS if value is 010B   
  373.                   DB   '.XALL',0 ; List MACRO code if value is 100B   
  374.  
  375. The second type of data is range data required by numeric data input 
  376. functions 3 (HEXRAD) and 4 (DECRAD).  The MIN/MAX data words are a pair of 
  377. 16 bit (DW) values which contain the minimum and maximum values allowed for 
  378. the current item being configured.  Do NOT use DB!  The first word is a 
  379. minimum value and the second is a maximum for the numeric data addressed by 
  380. this case.  If the POINTER value in PDATA is 0000h, then no range checking 
  381. will occur.  When MIN/MAX values are given, they are displayed in the 
  382. proper radix in the prompt line.  If the user attempts to enter a value 
  383. outside the indicated range, his entry is ignored.  
  384.  
  385. For example, Z3 system file numbers are from 1 to 4.  The data provided in 
  386. the configuration file for this case would be:
  387.  
  388.      SFILMM:      DW   1        ; Minimum value first
  389.                   DW   4        ; Maximum value second
  390.  
  391. Functions 1 and 5 use the data byte at PDATA to specify an optional
  392. terminator for the string in the configuration block. If PDATA is 0 then
  393. there is no terminator. Otherwise, PDATA points to a byte in the CFG file
  394. (DB statement).  This byte is normally 0 or '$'.
  395. :H
  396. HELP SCREEN DATA
  397.  
  398. Help screens are accessed via the '?' or '/' at the menu prompt.  A help 
  399. screen should be provided for each menu, even if it contains no more than a 
  400. 'help not available' message.  The help screen may be omitted if a 0000h 
  401. entry is made in the MENU record (HELPa, HELPi, HELPn).  That causes ZCNFG 
  402. to ignore help request (/ or ?) from the menu served by that record.
  403.  
  404. The help screen for each menu is labeled.  That label is an entry (HELPa, 
  405. etc.) in the associated MENU record.
  406.  
  407. Help screens are, like screen images, a block of DB statements which define 
  408. the text to be displayed.  Help screens may be longer than 24 lines.  ZCNFG 
  409. counts lines and executes a display pause for each screen-full of text.  
  410. You can control the content of successive displays by adding or removing 
  411. line feed characters in the DB statements.  But there is an easier way, 
  412. introduced in ZCNFG version 1.8.  A colon or ASCII formfeed as the very 
  413. first character of a line is a signal to ZCNFG to start a new screen.  The 
  414. colon or FF is not sent to the screen, but invokes paging.
  415.  
  416. The entire block of ASCII text that comprises a HELP display, which may be 
  417. displayed in multiple screens, is terminated with a binary zero (NOT a 
  418. '$').  This convention permits the use of the $ character in your screen 
  419. displays. 
  420.  
  421. The easiest way to prepare help screens is with your text editor.  Put a 
  422. colon or formfeed (^L) at the beginning of a line where a screen break is 
  423. desired.  Remember that screens are about 22 lines long.  You can then run 
  424. a utility such as TXT2DB to convert the text file into a DB file for 
  425. inclusion into your CFG source file.  Make sure that TEXT2DB has been 
  426. configured to terminate the file with a null.
  427. :U:ZCNFG.HLP
  428.