Z C N F G C O N F I G U R A T I O N E D I T O R FOR ZCPR and CP/M EXECUTABLE FILES by A. E. HAWLEY COPYRIGHT NOTICE ZCNFG and its documentation are copyrighted (C) 1988 by A. E. Hawley. All rights are reserved. A. E. Hawley 6032 Chariton Ave. Los Angeles, CA. 90056 (213) 649-3575 (voice) Ladera Z-node:(213) 670-9465 (modem) ZCNFG CONFIGURATION UTILITY INTRODUCTION ZCNFG is a universal configuration utility for programs like ZMAC, MCOPY, BYE, ZFILER, and many others. The behavior of such programs is designed to be modified by users without reassembly. This is done by changing data at known addresses in the first page of program code. ZCNFG performs this editing function in a particularly convenient way. Data options are displayed in one or more menus. The current selection for each option is displayed as part of the menu information. HELP screens can be invoked for assistance in selecting options. The most common configuration options are logical choices based on the value of a byte (zero or non-zero). Such choices appear in the ZCNFG menu as 'YES' or 'NO' (or any other set of terms you like), and may be toggled when that menu item is selected. ZCNFG readily handles the following kinds of data: Logical toggle of any bit in a byte Change the value of a byte with display/entry in Decimal Change the value of a word with display/entry in Decimal Change the value of a byte with display/entry in HEX Change the value of a word with display/entry in HEX Replace a string of ASCII characters Replace or modify a DU specification Replace or modify a Z3-style File Specification An acceptable range for numeric values can be specified for each byte or word value; values outside that range will not be entered in the target program. The range is displayed for each item. This is useful for entry of, for example, a buffer size or a ZCPR3 system file number. The last two are useful for editing a default filespec. ZCNFG is universal because it uses an overlay file to provide the menu layout(s), Help screen(s), and data specifying the location and nature of each option. An appropriate overlay must be present for the target program; ZCNFG loads it automatically or as a result of a command line specification. The generation of overlays is discussed below for those who wish to make such files for their own use. ZCNFG is a CP/M compatible Z-system utility. If ZCPR3/33/34 is present, then ZCPR facilities are used to take advantage of the TCAP and named directories. INVOCATION Just type ZCNFG's name to get a help screen that explains how to invoke ZCNFG. Any form of the following invocation will work. ZCNFG or ZCNFG [/[/]] <== ? may replace the / To configure a target file when the overlay file is on the currently logged directory, use: ZCNFG This example implies that the name of the overlay file is the same as that of the target file and may be found in the current directory. The overlay may also be explicitly declared. An explicit declaration takes precedence over an implied one. If the DU portion is missing, then the default directory is used. If the filetype is missing, then a filetype of .CFG is assumed. Implied filespec: Explicit filespec: ZCNFG FS ZCNFG FS _ FS where: FS = [DU: | DIR:][][.] and underline (_) means space,tab, or comma The first filespec (FS) defines the target program that is to be configured. The second filespec defines the associated overlay file. As implied, all parts of both specifications are optional; if everything is omitted the help screen will be displayed. The default overlay filetype extension is .CFG. You can, of course, use ZCNFG to change its own defaults; CFG could be changed to CNF, for example. If the configuration overlay file cannot be found with the specs supplied, then the search is repeated in the Alternate DU. That directory is one of the configurable defaults within ZCNFG itself. If the overlay file is still not found, then ZCNFG attempts to obtain the name of the overlay from the target programs data area and repeats the search in the current and in the alternate directories. The target program is searched at relative location 0DH (right after the Z34 header) for a legal file name. Up to 8 bytes are examined. A possible filename will be assumed if it is terminated with enough spaces to make 8 bytes or if it is terminated by null, $, or High-bit-set for the last character. If the string looks like a legal file name, it is taken as the name portion of the overlay filespec. The object of the above strategy is to permit normal invocation with an implied overlay filespec. If the target program contains the name of its overlay file as described, the overlay is very likely to be found even if the target program has been renamed. .pa THE CONFIGURATION FILE The configuration file is an overlay loaded at run time by ZCNFG. The overlay conventionally has the same name as the file to be configured, and a filetype of .CFG. It is created by assembly of a standard Z80 source file to produce a binary image. The alias MAKECFG.COM automates the process for ZMAC and ZMACLNK.It is not necessary to set an Origin (ORG) in the source file because the image is automatically relocated during loading at run time. The relocation depends on the initial MENU DATA being present as the first code producing item in the source file, as described below. The Configuration Overlay source file contains the following main sections: DEFINITIONS MENU DATA STRUCTURE CASE TABLE(s) SCREEN IMAGE(s) DATA FOR ALTERNATE SCREEN IMAGE FIELDS HELP SCREEN DATA The sections are discussed below. See files like *.SRC in this library for implementation examples. DEFINITIONS This section defines symbols and macros used in the balance of the source file. Functions, offsets, screen locations, data, and local data addresses are symbolically defined by EQU statements. Two macros are provided in the example file MODELCFG.SRC which greatly simplify the construction of the case tables. MENU DATA STRUCTURE The first three code generating lines in the file MUST be: RST 0 DW MENUA ;or whatever label you use for menua: menua: DW LASTM,NEXTM,SCREENA,CASEA,HELPA LASTM and NEXTM are pointers in a doubly linked circular queue of records like that at menua:. There is one record for each menu screen displayed by ZCNFG. If there is only one menu screen (the case for many target program implementations) then LASTM and NEXTM will both be replaced with MENUA. For n menu screens, added menu records would be required. For example, menua: DW menun,menui,SCREENa,CASEa,HELPa .... menui: DW menua,menun,SCREENi,CASEi,HELPi .... menun: DW menui,menua,SCREENn,CASEn,HELPn There is no requirement imposed for location of menu records after the first one (menua). ZCNFG finds the MENUA record at the specified offset in the configuration overlay (offset is 3). Any others are located through the links LASTM and NEXTM. The RST 0 instruction is present to prevent this file from being inadvertently executed. A RET instruction could also be used here in many cases. The DW statement containing the symbolic address of the first menu record is used for run-time relocation of pointers in the menu records and CASE tables. CASE TABLE(s) There is one CASE table for each menu screen. The case table is labeled and the label is an entry in the associated menu record. Each case table contains a series of records: one record for each configurable item in the menu display, and one initial 2-byte entry which specifies the number of records present and the number of bytes in each record. Since variable length records are not implemented in ZCNFG, the record length byte is always 0AH. Here is the structure of each CASE record: letter: ds 1 ;ASCII code for the menu selector. function: ds 2 ;16 bit function number offset: ds 2 ;16 bit offset of config data in target pgm. bdata: ds 1 ;8 bit data required by function. scrnloc: ds 2 ;16 bit address for data in the screen image. pdata: ds 2 ;16 bit address of data required by function. Menu items are selected by console input of a visible character, letter:. Typical entries for letter: are "db 'A'", "db '1'", etc. 'function:' defines one of a set of standard modifications that can be made to data in the target program configuration area and to the ZCNFG screen display. For example, function 0 toggles a bit in a specified byte; the associated field in the menu display may toggle between 'YES' and 'NO'. The latter are strings whose address is given at 'pdata:', so you have control of what is displayed. If you wished, the display in this case might be '1' and '0' or 'True' and 'False'. name: function: used for: switch 0 toggle bit in the byte at text 1 edit characters with UC conversion duspec 2 edit a byte pair as a DU specification hexrad 3 edit a configuration byte/word in HEX. decrad 4 edit a configuration byte/word in DECIMAL textlc 5 edit characters, both UC and LC filesp 6 edit a Z3 filespec or filespec fragment togl3 7 rotate a bit in the 3 low bits at togltf 8 toggle byte at between 0 and 0ffH .cp 6 'offset:' specifies the relative address of the data item in the target program that is to be configurable with this menu selection. 'offset' is a word (16 bit) quantity, even though its value may be limited to the range 0-7fH. bdata: is a byte whose value implies the size of the data in the configuration block and how it is to be interpreted. Functions 1 and 5, for example, require bdata to specify the length of the text field in the configuration block. ZCNFG will abort with a diagnostic error message if the value of bdata found in the CFG file is inappropriate for the function specified. name: function: 'bdata' entry required switch 0 bit position to toggle, lsb = 0, msb = 7 text 1 number of characters to replace duspec 2 0 for (A..P)=(0..15), 1 for (A..P)=(1..16) hexrad 3 1 for byte, 2 for word config data decrad 4 1 for byte, 2 for word config data textlc 5 number of characters to edit filesp 6 0= FN.FT, 1=Drive, 2=DU, 3=Full filespec togl3 7 7 ( = 00000111B) togltf 8 1 (one byte gets toggled 00/ff) 'scrnloc:' is the address in the screen image at which the ASCII representation of the configuration data for this menu item is to be displayed. This is normally a label in the screen image source described below. 'pdata:' is the address of data used by a function. Some of the functions do not require this data. In those instances, the value entered in this field is ignored, and is normally 0000. The following table shows what each function requires of the 'pdata' field. name: function: 'pdata:' entry required switch 0 address of 2 null terminated strings text 1 0 duspec 2 0 hexrad 3 0 or address of min/max data words decrad 4 0 or address of min/max data words textlc 5 0 filesp 6 0 togl3 7 address of 3 null terminated strings togltf 8 address of 2 null terminated strings The min/max data words are a pair of 16 bit values which contain the minimum and maximum values allowed for the current item being configured. For example, Z3 system file numbers are from 1 to 4. The data provided in the configuration file for this case would be: sfilmm: DW 1,4 ;minimum value first! Do NOT use DB! SCRNLOC and PDATA are addresses within the configuration file. Because they are relocated when the overlay is loaded by ZCNFG, they may NOT designate absolute addresses outside the overlay. (For PDATA, 0 does not specify an address. It means that there are no limits for this numeric data item.) SCREEN IMAGE(s) The screen image is a set of DB statements that specify enough spaces, data, and CR,LF characters to 'paint' 18 lines of the screen. The other 6 lines of a 24-line screen are taken up by the prompt message and user response lines at the bottom of the screen. The first statement of the screen image is labeled. That label is part of the MENU record, identified as SCREENa, SCREENi, etc. in the description of the menu record structure above. Screen images are illustrated in the sample *.SRC files. The 'data' just mentioned comprises titles, borders, and the text of menu items that does not change. Fields in which configurable data is to be displayed are filled with spaces. Such fields are usually made into independent labeled DB statements. The label for such a statement is an entry in the case table record as 'scrnloc'. The entire screen image is terminated by a binary zero ( db 0 or its equivalent). See the discussion below under 'HELP SCREEN DATA'. TIP: Don't forget to put the menu item selection characters in the screen image near the data to be referenced! This is how the user knows which key to press for a particular item.. DATA FOR SCREEN IMAGE FIELDS Functions 1, 2, 5, and 6 ignore any entries in the pdata: field. They get their data from the keyboard only. Two kinds of data structures are referenced by pointers at pdata: for functions 0, 3, 4, 7, and 8. The first type is composed of DB statements that define null terminated ASCII strings. These strings appear in the menu to show the current state of the configuration item addressed by this case table record. 'yndata' in the *.SRC example files is typical. Note that the order in which the strings occur is important: the one corresponding to 'true' comes first. This type of data is required by functions 0, 7, and 8. The second type is a DW data statement containing two words. The first word is a minimum value and the second is a maximum for the numeric data addressed by this case. This type is used with functions 3 and 4 (HEX and DECimal data). If the POINTER value in pdata: is 0000h then no range checking will occur. When Min/Max values are given, they are displayed in the proper radix in the prompt line. If the user attempts to enter a value outside the indicated range, his entry is ignored. HELP SCREEN DATA Help screens are accessed via the '?' or '/' at the menu prompt. A help screen should be provided for each menu, even if it contains no more than a 'help not available' message. The help screen may be omitted if a 0000h entry is made in the MENU record (HELPa, HELPi, HELPn). That causes ZCNFG to ignore help request (/ or ?) from the menu served by that record. Help screens are, like screen images, a block of DB statements which define the text to be displayed. Help screens may be longer than 24 lines. ZCNFG counts lines and executes a display pause for each screen-full of text. You control the content of successive displays by adding or removing line feed characters in the DB statements. The entire block of ASCII text that comprises a HELP display, which may be displayed in multiple screens, is terminated with a binary zero (NOT a '$'). This convention permits the use of the $ character in your screen displays. Since some early configuration files use the $ as a terminator, ZCNFG may be configured to recognize that character as the terminator, rather than the null. Such non-standard configuration should be temporary only. The help screen for each menu is labeled. That label is an entry (HELPa, etc.) in the associated MENU record.