;
                                   XFOR.COM                                   

             Size (recs) CRC   Version    Author/Latest Issue      Disk
               4k (29)   7715  1.20       Gene Pizzetta 12/90      Z3COM27

  1- Usage  2- Config  3- RAS Opn  4- File Format  5- Notes  6- Examples      

   XFOR a is  ZCPR3  Extended  FOR utility for searching and displaying "----"
delimited file catalogs.  It provides for a command line source file specific-
ation, parsed by the CPR for remote system safety.  Alternately, an internally
configured default directory and filename can be used.   It uses  highlighting
and direct cursor addressing,  if available.   The error flag is set on error,
or if a matching string is not found.  It responds to "//" help option and can
be re-invoked with the GO command.   Optionally, XFOR can display a header for
Bill Tishey's  ZFILES.LST,  or  a  custom  header can be inserted.  Output can
be echoed to the printer.  Numerous configuration options can be set with with
ZCNFG.
:1

    Syntax   XFOR {{dir}:{fn.ft}} {/options} {string{|string{|...}}}


   If no filespec is given,  the internally configured drive/user and filename
will be used.   If a filespec is  given on the  command  line, a colon must be
included.   If only a DU or DIR is given,  the internal filename will be used.
If only a filename is given,  the internal  DU will be used.   As distributed,
the internal DU is configured for the currently logged directory.
 Options   A leading slash is required.  Options must follow the 
           file specification, if one is given.

     H    Toggle header  display  on  or off,  depending on the configured
          default.

     A    Use alternate header, the header not configured as the default.

     S    Toggle inserting a blank line between entries,  depending on the
          configured default.

     P    Pause display when screen fills.  This option will also suppress
          the  "Do you want screen paging?"  question,  if  XFOR  has been
          configured to "ASK".

     N    Suppress screen page  pausing,  which  also  suppresses variable
          screen page overlap.   If a header is  being displayed,  it will
          appear only at the beginning of the listing.   This  option will
          also  suppress  the  "Do you want screen paging?"  question,  if
          XFOR has been configured to "ASK".
 Options - 2/2 

     L    Output will be echoed to the printer.  If the wheel byte is off,
          however,  printer echo is not  available  and the option will be
          ignored.   Printer output echoes the  matching entries only;  no
          headers or other messages are sent to the printer and no format-
          ting is  done.   Automatic  screen  paging  is  disabled if this
          option is given, although ^S will still work.

     V    Suppress video highlighting.  No highlighting will be used, even
          if available in the TCAP.

 String Search - 1/3 

   Leading spaces in the first  search  string  on  the  command  line are not
significant.   To make leading spaces significant,  precede them with the  "|"
multiple string delimiter.   This  method  allows  looking  for " REN" without
finding "reference".

   Likewise,  because the slash is used as an option list delimiter,  a search
string beginning with a slash could be misinterpreted by the parser.   Looking
for file entries beginning with a slash  can be done reliably by preceding the
slash with "|" or by a question mark.

   Search strings may include the following special characters:

     |    separates multiple search strings.  The "|" is equal to 
          "OR"; that is, an entry will be found if it contains 
          any of the given search strings.

     \    matches the beginning of a line.  In a typical FOR 
          file the only word at the beginning of a line is a 
          filename, so this option can be used to avoid matching 
          words in the file description.
 String Search 2/3 

     ?    matches any single character, allowing primitive 
          wildcard searches.

   XFOR was intended to allow operation through an alias, so only one copy has
to be on line,  even  if  you  want  to  be  able  to use it to search several
catalogs.

   The program error flag is set if  XFOR  encounters any problems.   The flag
values correspond to those in  Z34ERR.LIB  (all values are below 14h),  except
that if no matching string is found, the flag is set to FFh.

   XFOR can be aborted at any time with ^C, ^K, ^X, C, K, or X.
 String Search - 3/3 

   A header for Bill Tishey's  ZFILES.LST can be  displayed at the top of each
screen page.  You can make this header display the default, or you can use the
command line options H and A,  depending  on  your  configuration.   XFOR also
provides  a  data  area  for  a  custom   alternate  header.   A  patch  file,
XFHEADER.Z80 is provided to allow the creation of the alternate header,  which
is then assembled to a  HEX file and loaded over the COM  file  using MLOAD or
MYLOAD.   If the TCAP allows, the header will be printed and maintained at the
top of the screen;  otherwise,  it will be  printed  at the beginning of every
screenful and  scrolled  up  the  screen.   The header is only printed once if
screen paging is disabled.
:2
 Configuration 

   XFOR has a large number of configuration options that  can be changed using 
ZCNFG and the included XFORnn.CFG file.   Do not  change  the  name of the CFG
file, so  that  ZCNFG  will always be able to find it,  even if you change the
name of XFOR.COM.

   The ZCNFG help  screens  are  an important  aid to configuring XFOR to your
liking, so read them carefully.
 Video Attributes 

   XFOR will run as distributed under any type of TCAP.   Video  attributes to
display the header,  if one is used,  and for the first line of displayed file 
entries.   Normally,  your TCAP  "standout"  string  will  be  used to set the
attributes for the first line of  each  entry.   If  an  extended  TCAP  is in
memory,  XFOR will attempt to display the header in reverse video.  If reverse
is not available, or if there is no extended TCAP, the standout string will be
used for the header, also.  If no attributes are available in your TCAP,  XFOR
will still work fine;  the header will be marked by right and left brackets at
each end.

   The attributes used for display of  the  header  and  the  first  lines  of
entries are configurable.
:3
 RAS Operation - 1/3 

   Sysops who cannot store TCAP information for individual users can eliminate
the terminal dependencies of  highlighting,  reverse  video,  and clearing the
screen by making sure those bytes  are null in  the generic TCAP.   (They  can
also be eliminated through configuration options).   The routines in XFOR will
not send the strings if they are not there,  so the screen will merely scroll.
In fact,  by using a null TCAP and changing some options with ZCNFG,  XFOR can 
be made to operate in the same manner as earlier FOR utilities,  although that
would eliminate some desirable enhancements.

   If XFOR is called with  a  filename  parameter from  an  alias  or from the
command line, the filename is parsed by the CPR, which for safety reasons does
not allow access to a directory above the maximum DU or to a drive excluded by
the drive vector in the environment.   To  access  a  directory  outside these
limits, configure it into the internal DU specification.   If the command line
filename parameter begins with a colon,  the internal DU specification will be
used.
 RAS Operation - 2/3 

   If the wheel is off,  XFOR will  exclude the filespec  parameter  from  the
usage screen display, under the assumption that either the  internally config-
ured filename or an alias will always be used and that the options  should not
be under the control of the remote user.   In addition,  a  few usage examples
will be displayed.   The theory for the  latter is that experienced users want
only a reminder of the syntax, but RAS users may need more information.

   Printer output is disabled if the  wheel  byte is  reset (off).   The other
options are still available,  even though they are not  displayed  on the help
screen.  If options are included in aliases that call XFOR,  then options will
not be available to remote users from the  command  line  (XFOR will only find
the first set of options).   If no options are to  be  included  in  the alias
script,  inserting  a single slash  with no options following it will have the
same effect.

   Sysops will probably want to  set  the  paging  option to ASK, so users can
request no  paging if they are  merely  reading  the  FOR file into their text
buffer.  Paging for many users is almost mandatory, however.  
 RAS Operation - 3/3 

   As distributed XFOR does not leave a blank line between entries.  Since the
first line of each entry is highlighted, the display is readable and many more
entries can be displayed.   Some people may prefer less clutter,  however,  so
XFOR can be configured to insert  a blank line by default.  The blank line may
be even more desirable if highlighting is not supported.
:4
 XFOR File Format  
 
   Most FOR files separate entries with a  series of  four  hyphens  ("----").
Actually, any  hyphen in the  first  column is  considered an entry separator.
Entries can be longer than a screen,  but a single  entry longer than about 8K
will cause XFOR to abort with an "incorrect format" message.

   XFOR was linked with the beta release of the version 4.3 libraries.
:5
 XFOR Notes - 1/4 

   a. This utility is a result of the  collective  ideas and complaints of the 
      group that hangs around Jay Sage's Newton Centre Z-Node.   The  idea for
      an enhanced  FOR came from Chris  McEwen,  who runs the Socrates Z-Node.  
      Bill Tishey reformatted his  ZFILES.LST so it  could  be read by FOR and
      offered several good ideas.   Jay Sage gave  valuable  advice on command
      line syntax.   Bob Dean was  a  well-spring  of suggestions.   They, and
      Howard Schwartz,  offered criticism and support that resulted in  a much
      better utility.  Thanks to you all.

   b. Version 1.2 updates (12/23/90, Gene Pizzetta):
      - Changed command line syntax at the request of Jay Sage:  Now an option
        list, preceded by a slash, can be included in the  command  line, just
        before the match string.  Options are:  H=display header; A=use alter-
        nate header; S=double-space between entries;  L=echo to printer (LST);
        V=turn off all  screen  attributes;  P=use  screen  paging;  and  N=no
        screen paging.  The last two will suppress the paging "ASK" configura-
        tion option.  The L option will suppress screen paging.
 XFOR Notes - 2/5 

   c. Version 1.1 updates (12/18/90, Gene Pizzetta):
      - Added CR, LF after paging question.  
      - Now uses BOUT instead of COUT in print loop, so tabs are expanded.  
      - Added printer output and  "+" command line option (must be last token, 
        preceded by a space). 
      - Made video attributes used for header and first  line of entry config-
        urable options.

   d. Vs 1.0 updates (12/15/90, Gene Pizzetta):
      - Variable screen overlap  and clearing  screen before each page are now
        configurable options.  
      - Changed method of making leading spaces significant;  now requires "|"
        at beginning of match string if leading spaces are to be significant.  
      - Uses direct cursor addressing and  clear-to-end-of-screen  string,  if
        available and if header is being displayed.  
      - Fixed bug that in some cases  caused  highlighting  not to be properly
        terminated on  an  Apple II+  (STNDEND must be called before sending a
        linefeed on that machine).  
 XFOR Notes - 3/5 

      - Fixed bug that sent the  program into  never-never-land if  the Kaypro
        4/10 TCAP from Z3TCAP27 was used.   (This was actually  a  bug in  the
        SETATR routine in VLIB versions 42 and 43,  but I have compensated for
        it.)  
      - Source filename parameter omitted  from syntax message for non-wheels,
        unless configured to always be omitted.
      - And, finally, documentation.

   c. Vs 0.2 updates (12/8/90, Gene Pizzetta):
      - A second beta release.   Name  changed to  XFOR to avoid conflict with
        ZMD utilities.  
      - Can be configured to page or not page output, or to ask the user which
        he wants.  
      - No longer responds to quiet flag, but quiet configuration still works.
      - Highlights first line of each entry if available from TCAP.
      - Uses reverse video for header line, if available.  
      - Sets correct  Z34 error codes in program error flag,  except no string
        match is FFh.  
      - Configurable to allow  blank  line  between entries or not if you want
        more entries on screen.  
 XFOR Notes - 4/5 

      - additional roll-your-own header.
      - Leading spaces now significant in search string.  
      - Adopted Jay Sage's suggested command line syntax:   if there's a colon
        in the first token, it's a filename; otherwise, use the internal file-
        name.  In addition,  XFOR will use the internal filename if the  colon
        is not followed by one,  and  will use the internal DU if the colon is
        not preceded by one.  
      - Now properly handles entries more than a screen-length.  
      - Entry buffer now handles single entries of up to 8K.

   d. Vs 0.1 updates (12/2/90, Gene Pizzetta):
      - A beta release,  based on Carson Wilson's FORZ 1.0 (8/5/87), which was
        a revised disassembly of Irv Hoff's FOR.COM.  
      - Sets the ZCPR program error flag if a matching string is not found.  
      - The "end of listing" and  "aborted"  messages suppressed if ZCPR quiet
        flag is set or if configured to default to quiet mode.  
      - Responds to "//" help option on command line.  
      - Re-initializes  its  data  buffers  so  it  can  be re-invoked with GO
        command.  
 XFOR Notes - 5/5 

      - Added command line source file specification.  If no DU or DIR spec is 
        given,  an internally configured default directory is used or,  if not
        configured,  the  current  logged  directory.   If no  command tail is
        given, defaults to configured internal filename.  
      - If reading an  improperly  formatted  file,  FORZ  kept  adding to the
        OutBuf until it  overwrote  the  system.   ZFOR instead aborts with an
        error message.  
      - Configurable with ZCNFG.
:6
 Examples of Use - 1/3 

   a. XFOR A1:ZFILES.LST /H
          XFOR displays all entries in ZFILES.LST in A1, using 
          the ZFILES header.

   b. XFOR
          XFOR displays all entries in the internally configured 
          file in the default directory or in the internally 
          configured directory.

   c. XFOR A1:ZFILES.LST /SN \REN
          XFOR will search ZFILES.LST in A1 for entries with 
          filenames beginning with "REN", inserting a blank line 
          between each entry and scrolling continuously.

   d. XFOR :ZFILES.LST REN
          XFOR will search ZFILES.LST in the default directory or 
          in the internally configured directory for entries with 
          a string containing "REN".  The search is not case- 
          sensitive.  The colon before the filename is required.
 Examples of Use - 2/3 

   e. XFOR :ZFILES.LST /L REN
          Same as above, except output will also be echoed to the 
          printer (if the wheel byte is on).  If the wheel byte 
          is off, the L option will be ignored.

   f. XFOR A1: | REN|\REN
          XFOR will search the internally configured file in A1 
          for an entry with a word beginning with "REN" or any 
          filename beginning with "REN".

   g. XFOR A?M|M?C
          XFOR will search the internally configured file in the 
          default directory or in the internally configured 
          directory for entries containing "ASM", "AQM", "AZM", 
          "MAC", "MQC", "MZC", etc.
 Examples of Use - 3/3 

   h. XFOR : C0:
          XFOR will search the internally configured file in the 
          default directory or in the internally configured 
          directory for entries containing "C0:".  In this case 
          the single colon is required so that XFOR will not 
          think "C0:" is a DU specification.
