BFIND.TXT                            1                         Mar 10, 2001

WinXX NOTICE:  As with  most  DOS-based  utilities,  this  program  doesn't
understand the weird subdirectories,  long  filenames,  invalid  characters
that are possible under Windows.  This is not a bug.  It's just the way DOS
applications work.  For compatibility reasons,  most  versions  of  Windows
maintain a short filename for each file (in WinNT,  you  can  probably  say
"DIR /X" in DOS to find them).  The short filenames are the ones  with  "~"
characters in them (like "MYFILE~1.TXT").  The  short  filenames  are  what
these utilities will process.

The BFIND.EXE program adds Boolean logic to DOS's FIND  command.   In  most
ways, it's identical to the FIND command except:

  * Adds AND, OR, NOT, and XOR options to searches (finding all lines  with
    "Apples" or "Bananas", for example).
  * Allows you to specify the starting column of the desired string.
  * Adds a pause (/P) option to have the output pause every 24 lines.
  * Avoids need to include the search string in quotation marks so you  can
    use the program more easily in batch commands.
  * The input file specification can include standard DOS wildcards  or  an
    external file (@listfile) containing the files to be processed, e.g:
          BFIND /I "SOUND" *.TXT > TEMP.X
  * Allows you to recurse through child subdirectories.
  * Allows you to skip the by-file heading information ("----- filename").
  * Can avoid showing file name header if no  hits  in  the  file  (/-EMPTY
    option).
  * Handles DOS text files (lines end with CR/LF), Mac  text  files  (lines
    end with CR), or Unix text files (lines end with LF).
  * Should be able  to  handle  input  files  with  line  lengths  of  5000
    characters or more.  Should skip the remainder, allowing you to use the
    wildcards more easily.
  * Allows you to remove  non-text  characters  from  the  output  or  even
    specify your own character-translation file for them.
  * Pressing escape stops the program early.

The only FIND feature that BFIND does  *not*  support  is  the  ability  to
specify multilple single input files without  using  wildcards  ("FIND  ...
BRUCE.TXT BRUCEINI.TXT" works using the FIND command--"BFIND ...  BRUCE.TXT
BRUCEINI.TXT" does not work).  In addition, you cannot do piping into BFIND
(for example:  "DIR | BFIND ..." does not work).

The DOS FIND command allows you to find lines in a text file which  contain
a given string.  You can also have the program tell you how many lines  met
the search criteria without actually viewing them which is an ideal way  to
find out how many times a given string appears in your file.  You can  even
use FIND to tell you how many total lines are  in  a  given  file  just  by
requesting a string that you know will  never  appear  in  your  file  like
"#X$S$" and using the /C (count) parameter.

BFIND adds to these capabilities.  It gives you the power of AND, OR,  NOT,
and XOR, allowing you to find any line, for  example,  that  contains  both
"Apples" and  "Oranges"  or  to  present  any  lines  that  contain  either
"Bananas" and "Pears".  In addition, you can do column-specific  searching,
finding only those lines, say, that contain "PRINT" beginning in column 10.

BFIND allows you to specify wildcards for the input file.  You can also put
the list of file names to process in a text file and tell BFIND to  process
the files listed therein.

BFIND.TXT                            2                         Mar 10, 2001

Defining Character-Translations (The Filter Table):

BFIND allows you to translate specified characters as  the  text  is  read.
This is useful on output, when, for example, the text might contain  things
like page eject characters and you are rerouting the output to  a  printer;
the page eject characters would, of course, cause lots of extra pages to be
printed.

There is a default character-translation table built into the program which
you can request by passing in the parameter "/FILTER".  In this  case,  all
characters between decimal 32 and 126 as well as decimal 9 (the  tab)  keep
their original values and everything else get translated as a space.   This
leaves you with the following characters:

        (tab) (space)                   !"#$%&'()*+,-./
        0123456789                      :;<=>?@
        ABCDEFGHIJKLMNOPQRSTUVWXYZ      [\]^_`
        abcdefghijklmnopqrstuvwxyz      {|}~

Alternatively, you can create  your  own  filter  file  and  invoke  it  by
specifying the "/FILTER=filename" parameter.  The filters can  be  in  your
standard *.INI file (for example, BFIND.INI) if  desired.   If  it  becomes
large, however, you might want to move it to its own filename.

The filter table is an ASCII text file which consists of a series of  lines
in the following format:

        inchar = outchar

where "inchar" is the character to change from  and  "outstr"  is  what  to
change the character to.  Both portions can consist  of  regular  non-space
ASCII text characters (like "A" or "z") as well as hexadecimal  values  (in
the form &Hxx) or decimal values  (in  the  form  \nnn).   Both  sides  can
reference a single character (exactly one character  is  always  translated
into exactly one character).  You cannot use  a  space  or  equal  sign  in
either  "inchar"   or   "outchar";   use   the   hexadecimal   or   decimal
representations instead.  The table does not have to be  in  any  specified
order.  Lines can end with "/*" followed by a comment if you want.

Hexadecimal and decimal equivalents are explained in BRUCEHEX.TXT.

Examples:

        a    = A       /* Translate lowercase "a" into capital "A"
        \032 = _       /* Translate space (decimal 032, &H20 too) into
                          underscore
        \027 = \032    /* Translate escape character to a space

Some leading characters in INI files are  treated  specially  within  Wayne
Software programs.   INI  lines  that  begin  with  any  of  the  following
characters may lead to odd results:  "[", "/", "&", "\", ";", ":", "<", and
",".  To avoid problems, use hexadecimal  or  decimal  representations  for
these characters.  For example, use \047 or &H2F if you  want  to  override
the definition of "/".


BFIND.TXT                            3                         Mar 10, 2001

Specifying parameters:

Parameters for this program can be set in the  following  ways.   The  last
setting encountered always wins:
  - Read from an *.INI file (see BRUCEINI.TXT file),
  - Through the use of an environmental variable (SET BFIND=whatever), or
  - From the command line (see "Syntax" below)


Syntax:

    BFIND [ /V | /-V ] [ /C | /-C ] [ /N | /-N ] [ /I | /-I ] [ /P | /Pn ]
      [ /-HEADER ] [ /-EMPTY ] [ /FILTER | /FILTER=filename ]
      [ /LINES { line1-line2 | line1 linect } ... ]
      [ /ATTR=attribs ] [ /S ] [ /W | /W0 | /-W ]
      [ /MONO ] [ /Iinitfile | /INULL ] [ /-ENV ] [ /? ] [ /?HEX ]
      { search } { filespec | @listfile } [ >filename ]

where:

"/V" says to  find  those  items  that  do  NOT  match  the  specification.
Initially defaults to "/-V".

"/-V" says to find those items that DO match the  specification.   This  is
initially the default.

"/C" says to show the count of  the  items  found  (no  individual  lines).
Initially defaults to "/-C".  One use for the "/C" parameter  is  to  count
the number of lines in a file; search for all  lines  that  do  *not*  (/V)
contain a totally improbable string and then tally them.  For example:

        BFIND /V /C "&^&^&#" MYFILE.TXT

"/-C" says to skip counting the items.  This is initially the default.

"/N" says to number the output lines.  Initially defaults to "/-N".

"/-N" says to skip numbering the  output  lines.   This  is  initially  the
default.

"/I" says to make it a case-insensitive search.  So a  search  for  "Apple"
will find "APPLE", "apple", ApPle", etc.

"/-I" is the opposite of /I and is typically the  default.   A  search  for
"Apple" will not find "APPLE".

"/P" says to pause the output  every  (typically)  23  lines.   Pausing  is
actually based on the screen size; if you specify /P and start the  program
in EGA 43-line or VGA 50-line mode, the program will subtract two from that
and use that as the pause value.  Initially defaults to /-P.

"/-P" says to not bother pausing the output display.  This is initially the
default.


BFIND.TXT                            4                         Mar 10, 2001

"/-HEADER" says to skip the normal -----infile  output  line  that  appears
before the results of the output.

"/HEADER" says to include the headers.  This is initially the default.  The
header lines look like this:

     --------- C:\VBDOS\BFIND.BAS

"/EMPTY" says that the -----infile header information is to be  shown  even
if the file doesn't have any hits in it.  This is initially the default.

"/-EMPTY" says to only show the -----infile header information if the  file
has hits.  Initially defaults to "/EMPTY".

"/FILTER" specifies  that  the  program  is  to  replace  with  spaces  all
non-printable  characters  from  the  input  file(s).   See  the  "Defining
Character-Translations"   discussion   above.    Initially   defaults    to
"/-FILTER".

"/-FILTER" says to not bother removing the nonprintable characters from the
output.  This is initially the default.

"/FILTER=filename" specifies that  a  filter  is  to  be  applied  and  all
character replacements are in  the  file  "filename".   See  the  "Defining
Character-Translations" discussion above.

"/LINES line1-line2" says to restrict the  search  to  lines  between  line
numbers line1 and line2 inclusive.  You can have multiple line requests  in
any order such as "/LINES 1-10 90-100 30-50".  The routine skips all  lines
after  the  largest  line  number  is  encountered.   Defaults  to  "/LINES
1-9999999".

"/LINES line1 linect" says to restrict the search to lines  beginning  with
line1 and continuing for a total of linect lines.  So  "/LINES  10  20"  is
actually the same as "/LINES 10-29".

"/ATTR=attribs" allows you to specify a combination of attributes that  you
want considered.  You can specify  any  combination  of  R  (read-only),  H
(hidden), S (system), or A (archive bit).  Precede  any  character(s)  with
"-" to exclude instead of include.  Unlike with the DOS  DIR  command,  the
inclusions and exclusions are subject to  "OR"  conditions;  /ATTR=HS  will
retrieve any file that is either hidden or a system file or both.  You  can
specify "/ATTR=ALL"  to  specify  that  all  files  are  to  be  processed.
Initially defaults to  /ATTR=-H-S-R  (skip  hidden,  system,  or  read-only
files).

"/S" processes files in  subdirectories  off  the  specified  subdirectory.
Initially defaults to "/-S".

"/W" says to pause with a "Press any key to  continue"  message  after  the
program finishes if any hits were found.   This  parameter  is  ignored  if
redirection out is being used.


BFIND.TXT                            5                         Mar 10, 2001

"/W0" says to pause afterward whether any hits were found or not.  This  is
initially the default if the program is run under Windows3.1 or  Windows95.
BFIND won't detect if you're running  under  Windows  NT  though;  you  can
manually specify this parameter if the window closes up on you  before  you
can read the results.  This parameter is  ignored  if  redirection  out  is
being used.

"/-W" says to not pause afterward at all.  This is initially the default if
the program is run under DOS or Windows NT.

"/MONO" (or "/-COLOR") does not try to override screen  colors.   Initially
defaults to "/COLOR".

"/COLOR" (or "/-MONO") allows screen colors  to  be  overridden.   This  is
initially the default.

"/Iinitfile" says to  read  an  initialization  file  with  the  file  name
"initfile".  The file specification *must* contain a period.  Initfiles are
described in the BRUCEINI.TXT file.  Initially defaults to "/IBFIND.INI".

"/INULL" says to skip loading the initialization file.

"/ENV" says to look for %var% occurrences in the command line  and  try  to
resolve any apparent environmental variable references.   See  BRUCEINI.TXT
for more information.  This is initially the default.

"/-ENV" says to skip resolving apparent %var% occurrences  in  the  command
line.  Initially defaults to "/ENV".

"/?" or "/HELP" shows you the syntax for the  command.   (Unlike  with  the
other Wayne Software commands, "HELP" is not supported  since  the  program
takes this as your search string.)

"/?HEX" gives you a hexadecimal and decimal conversion table.

"search" is described below.

"filespec" tells the routine which file or files are to be processed.   The
specification can include path and wildcards if desired.  One thing I  find
useful with wildcards is that  is  allows  me  to  create  an  output  that
concatenates all of the input  files  together  with  the  typical  headers
(/HEADER) that separate each portion.   This  requires  searching  for  all
lines in a file so you need to use the /V option and look for an improbable
string.  For example, to concatenate all *.TXT files together as a new file
called TEMP.NEW and have the little header between each, say this:

        BFIND /V "&#$#" *.TXT > TEMP.NEW

"@listfile" allows you to have a variety of file specifications saved in  a
text file named "listfile".  Each line in the file should  consist  of  one
file specification, each of which can  include  a  path  and  wildcards  if
desired.  Blank lines and lines  beginning  with  semi-colons,  colons,  or
quotes are ignored.  An example using this is provided at the end  of  this
documentation.


BFIND.TXT                            6                         Mar 10, 2001

">filename" redirects the  output  to  a  text  file.   This  automatically
invokes the /-P option.  This is useful for saving  the  found  lines  into
another file.  For example:

        BFIND "Bruce" TEMP.TXT > TEMP2.TXT


For search, the syntax is:

  [ ( ]... search_item [ boolean [ ( ]... search_item [ ) ]...] [ ) ]...

where:

  ( and )     are used to group items
  search_item is shown below
  boolean     is AND, OR, or XOR (NOT is included with search_item)

for search_item, the syntax is:

  [ NOT ]  "string" [ column ]

where:

  NOT         is obvious
  string      the string to search; the quotation marks are typically not
              required unless the string contains a space or a reserved
              word or begins with a slash ("/")
  column      is the column in which the string must be found.

So, let's cover some examples:

        BFIND "Bugs Bunny" OR "Elmer Fudd" TEST.TXT

Quotes are needed around a string if it begins with a slash:

        BFIND "/1997" TEST.TXT

Finds any lines in the file TEST.TXT  containing  either  "Bugs  Bunny"  or
"Elmer Fudd" in them.

        BFIND (Apples or Oranges) AND NOT Pears TEST2.TXT

Finds any lines in the file TEST2.TXT which contain the words  "Apples"  or
"Oranges" in them and ignores any lines containing "Pears".  Note that  the
quotes around the search words are not required unless  the  words  include
spaces or unless they could be confused with some other  keywords.   "BFIND
OR OR AND TEST3.TXT" might cause the program to get confused since "OR" and
"AND", which you want to look for, are also keywords.

        BFIND /C "Bugs Bunny" AND Martians TEST.TXT

Gives you a total for the number of lines containing both "Bugs Bunny"  and
"Martians".


BFIND.TXT                            7                         Mar 10, 2001

The search string can include any text characters.   It  can  also  contain
ASCII codes, created either using the  Alt  key  in  combination  with  the
numeric keypad (for example, Alt-228 to get a Sigma character) or  else  by
embedding a hexadecimal code (in the form &Hxx) or a decimal code  (in  the
form \nnn) in the text.  (Do not use  &Hxx  from  the  command  line  under
Windows NT.) These codes are  described  in  the  BRUCEHEX.TXT  file.   For
example, to find the smiley face  character  in  a  file  called  TEST.TXT,
either of the following work:

        BFIND "" TEST.TXT
        BFIND \001 TEST.TXT

Note that the /FILTER parameter takes effect when the file is  *read*,  not
written.  If you are doing a search for non-text characters, you  will  not
find them if you have /FILTER in effect.  /-FILTER is the default anyway.

If you search for more than one word  without  using  a  Boolean  operator,
BFIND presumes  you  wanted  the  words  searched  with  an  "AND"  Boolean
operator.  So this:

        BFIND Print Form *.TXT

is the same thing as saying:

        BFIND Print AND Form *.TXT

If you wanted to search for the *phrase* "Print Form", you'd have to say:

        BFIND "Print Form" *.TXT

You can press the Esc key to abort the search early.

BFIND, unlike FIND, typically doesn't require the search string  to  be  in
quotes.  As a result, you can create  a  text  file  (presume  it's  called
C:\BAT\PHONE.TXT) containing phone numbers or something and then  create  a
batch file (like PHONE.BAT) that looks like this:

        BFIND %1 %2 %3 %4 %5 C:\BAT\PHONE.TXT

When you want to find a phone number, you just say "PHONE name".  This is a
little more natural that using FIND which would require  that  you  enclose
the name in quotes.  You can still use the Boolean operators in BFIND;  the
batch file above would allow up to five parameters.


BFIND.TXT                            8                         Mar 10, 2001

If you have multiple phone books, use the @listfile  option  in  the  batch
file.  For example, I have four  phone  files  I  search;  a  personal  one
(PHONES.TXT),  a  list  of  e-mail  addresses  (PHONMAIL.TXT),  a  list  of
work-related  phone  numbers   that   are   distributed   to   the   office
(EBBPHONE.TXT), and an office list (OBAPHONE.TXT).  My @listfile is  called
C:\MINE\PHONE.LST and contains these lines:

        c:\mine\phones.txt
        c:\mine\phonmail.txt
        c:\mine\ebbphone.txt
        c:\mine\obaphone.txt

My PHONE.BAT file contains this line:

        BFIND /I /P /-EMPTY %1 %2 %3 %4 @C:\MINE\PHONE.LST


Return codes:

BFIND returns the following ERRORLEVEL codes:
        0 = no problems, string found
        1 = no problems, string not found
      250 = operation aborted by pressing Escape
      255 = syntax problems, file not found, or /? requested


BFIND.TXT                            9                         Mar 10, 2001

Author:

This program was written by Bruce Guthrie of Wayne Software.   It  is  free
for use and redistribution provided relevant documentation is kept with the
program, no changes are made to the program or documentation, and it is not
bundled with commercial programs or charged  for  separately.   People  who
need to bundle it in for-sale packages must pay a $50 registration  fee  to
"Bruce Guthrie" at the following address.

Additional information about this and other Wayne Software programs can  be
found in the file BRUCE.TXT which should be included in  the  original  ZIP
file.  The recent change  history  for  this  and  the  other  programs  is
provided in the HISTORY.ymm file which should be in the same ZIP file where
"y" is replaced by the last digit of the year and "mm"  is  the  two  digit
month of the release; HISTORY.611 came out in November 1996.

The ZIP file that contained this program and its  associated  documentation
files is named with a two-digit year followed by  a  two-digit  month.   So
BFND0001.ZIP came out in January 2000.

Comments and suggestions can be sent to the  following.   Realistically,  I
will not be revising this DOS-based program  much  in  the  future  but  it
doesn't hurt to suggest things anyway.

                Bruce Guthrie
                Wayne Software
                113 Sheffield St.
                Silver Spring, MD 20910

                e-mail: WayneSof@erols.com   fax: (301) 588-8986
                http://www.erols.com/waynesof

Please provide an Internet e-mail address on all correspondence.


