;
                                 Z C N F G

                       Z-SYSTEM CONFIGURATION EDITOR
                                    FOR
                      ZCPR and CP/M EXECUTABLE FILES



                       I -->  Introduction          
                       C -->  Configuration Functions
                       Q -->  Quick Configuration   
                       S -->  Syntax                
                       D -->  Defaults in ZCNFG     
                       L -->  Locating CFG Files    
                       H -->  Hints for Usage       
                       W -->  Writing CFG Files     
:I
INTRODUCTION

ZCNFG is a universal configuration utility for programs like ZMAC, MCOPY, 
ZXD, 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.

ZCNFG is universal because it uses an overlay file to provide the menu 
layout(s), Help screen(s), and the data specifying the location and nature 
of each option.  An appropriate overlay must be present for each target 
program.  ZCNFG loads the overlay (CFG) file automatically or as a result 
of a command line specification.  The generation of overlays is discussed 
in the section on 'Writing CFG Files' for those who wish to write such 
files for their own use or for utilities they are writing.

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.  ZCNFG will automatically configure ZCPR3 type 1, type 3 and 
type 4 utilities.
                   A. E. Hawley  (213) 649-3575 (voice)     
                   Ladera Z-node:(213) 670-9465 (modem)
:C
CONFIGURATION FUNCTIONS

ZCNFG modifies bytes, words, and text strings in the configuration block 
of the target program.  The menu may show the data itself or a logical 
equivalent.  For example, toggling a byte between 0 and 0ffh may cause the 
screen display to toggle between 'YES" and 'NO' or some other pair that 
has meaning in the context of the target program.  The screen display, 
target addresses to modify, and data interpretation are controlled by 
information in the CFG file.  ZCNFG can also:

       Toggle any bit in a byte (8 YES/NO choices)
       Rotate a bit within a field of bits in a byte (multiple choice)
       Change the value of a byte with display/entry in HEX or Decimal
       Change the value of a word with display/entry in HEX or Decimal
       Replace a string of ASCII characters
       Replace or modify a DU specification
       Replace or modify a Z3-style File Specification

The menu prompt may include an acceptable range for numeric values; values 
outside that range will be ignored.  This prevents entry of inappropriate 
values for objects like a buffer size or a ZCPR3 system file number.  HELP 
screens from the CFG file can be invoked to explain configuration items. 
:Q
QUICK CONFIGURATION with ZCNFG

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 [/[/]]       <== ? may replace the /

To configure a target file when it and its overlay file are on the 
currently logged directory, use:

          ZCNFG <target filename>

This example assumes that the name of the overlay file is the same as the 
targets name or is named in the targets configuration area. 

In the more general case, the target file may be in any directory on your 
system.  You can use a full filespec form to tell ZCNFG where to find it. 
You can also do that for the overlay file, naming it and its location 
explicitly.  See SYNTAX for the full syntax and how you can take advantage 
of it to configure files easily and quickly.
:S
SYNTAX

Here is the command form used to configure file TFS:

        ZCNFG  TFS CFS LFS  or  TFS LFS CFS

  where:    TFS = [TDIR:] [TFN] [.TFT]  = file to configure     (TGT)
            CFS = [CDIR:] [CFN] [.CFT]  = configuration overlay (CFG)
            LFS = /[LDIR:][LFN][.LFT]   = LBR of CFG overlays
              or   [LDIR:][LFN].LBR

Each TGT file requires its own unique CFG file.
TDIR, CDIR, and LDIR specify Drive and User and may be one of the 
following forms: 

D:, U:, DU:, :, or (for Z-systems) DIR: 

TFN, CFN, and LFN are filenames for the TGT, CFG, and LBR files. 
TFT, CFT, and LFT are their filetypes.

As implied, all parts of the specifications are optional; if everything is 
omitted the help screen will be displayed.  The minimum meaningful command 
specifies TFN; the target filename is explicitly declared.  If it's not in 
the current directory, then you will also include one of the DIR forms so 
that ZCNFG can find the target file. Defaults exist for all other parts.

Example invocations with $$=A5:, ALT:=C15:, CDIR default is TDIR

ZCNFG TGT B:            ;seeks CFG in B5:
ZCNFG A15:TGT           ;seeks CFG in C15:CONFIG.LBR, A15:, C15:
ZCNFG TGT /CFG01        ;seeks CFG in C15:CFG01.LBR,  A5:,  C15:
ZCNFG TGT /B:           ;seeks CFG in B15:CONFIG.LBR, A5:,  C15:
ZCNFG TGT B3:CFG01.LBR  ;seeks CFG in B3:CFG01.LBR,   A5:,  C15:

The order in which the directories shown above are searched is given 
 in section L - Locating Overlay Files.

Other examples appear in the ZCNFG on-line HELP screen. (ZCNFG //)
:D
DEFAULTS USED BY ZCNFG

    Syntax Element      Default

        TDIR:           $$             (The current directory)
        CDIR:           $$ or TDIR:    (ZCNFG configuration option)
        LDIR:           ALT:           (see below)
        TFN             (none)         command line argument
        CFN             From TGT       (see below)
        LFN             CONFIG         (configurable)
        TFT             COM            (configurable)
        CFT             CFG            (configurable)
        LFT             LBR            (configurable)

ALT: is a configurable default within ZCNFG.  It is the directory in 
which CFG overlays are normally kept.  ALT: may be specified as an 
unambiguous DU or ambiguously (like B?: or ?15: or ??:).  The default 
used for an ambiguous ALT: is $$. ZCNFG is distributed with ALT:=??. 

CFN is taken from the TGT configuration page if possible.  If there is 
no recognizable name there, then ZCNFG uses TFN as the CFG filename. 
:L
LOCATING OVERLAY FILES

                THE CONFIGURATION FILENAME

The ZCNFG command form is:

ZCNFG TFS_[CDIR:] [CFN] [.CFT]              (see SYNTAX)

If you have specified CFN, then that is the name that ZCNFG will use.  If 
not, then ZCNFG looks in the target file configuration block for a filename 
and uses that. If there is no name there, then the name of the CFG file is 
assumed to be TFN. The CFT, if not included in the command, assumes the 
default filetype, .CFG.

If you specify CDIR (even a ':') in the CFS portion of the command tail, 
ONLY that directory will be searched for the CFG overlay file.  Note that 
either TDIR or the logged DU provides defaults for CDIR, as chosen during 
configuration of ZCNFG itself.

If you did NOT specify CDIR, ZCNFG searches 3 places for the CFG file:  
ALT:CONFIG.LBR, the ALT: directory itself, and either TDIR (the target 
directory) or the current directory. 
                   THE SEARCH PATH

Here is a summary of the search path used when CDIR is unspecified:

     COMMAND         CFN source             SEARCH PATH
     -------------   ---------       ---------------------------
     ZCNFG TFS       TFN             ALT:CONFIG.LBR, DDIR:,  ALT:
     ZCNFG TFS CFN   command line    ALT:CONFIG.LBR, DDIR:,  ALT:
     ZCNFG TFS       CFG block       ALT:CONFIG.LBR,  ALT:, DDIR:
  (DDIR is configured as TDIR or the current DIR)

CONFIG.LBR, if it exists, is always searched first.  The search order for 
the other two depends on the source of the CFN.  If it comes from the 
configuration block in the target then the ALT: directory is searched 
first.  If CFN comes from the command tail or the TFN, DDIR is searched 
first.

The object of this search strategy is to permit normal invocation with an 
implied overlay filespec.  The search path is arranged so that in normal 
use the CFG file will be found in the first path element.  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.
:H
HINTS ON USING ZCNFG

Each element of the search path requires a disk directory access.  To 
minimize these time consuming directory searches:

     Put all your .CFG files in one directory in a library named 
     CONFIG.LBR.  Use another name if you wish, but see below.

     If you don't use the LBR approach, put all the CFG files in one 
     directory.

     Configure ZCNFG, changing the ALTERNATE Directory to the one that 
     contains your CFG files.  If you don't like CONFIG as the library 
     name, change it to whatever you have named your library.  The result 
     is that normal invokations will only require ONE directory access to 
     find the CFG file.

When you're trying out a new CFG file, name its directory explicitly in the 
command tail.  Again, only one directory access. Speedy!
:W:ZCFG.HLP
