                                                Created by Coyot Fri  10-17-97

LOCATE v1.10 file monitoring utility user manual
Contents:

1. GNU public license and copyright notice
2. Basic information
3. Basic usage
4. Help on all switches and configuration
5. Hints
6. Errorlevels
7. Thanx
8. Revision history


1. GNU public license and copyright notice
==========================================

This software is to be distributed under the terms of GNU General Public
License (text included in GNU.TXT file). The only thing I wish to add is
that I'd like to get some feedback from you users.
[inet e-mail: coyot@pinknet.cz
snail mail: Viktor Urban, K Netlukam 957, 10400 Prague, Czech Republic]


2. Basic information
====================

This utility was written with one basic purpose in mind. File finding FAST!
I noticed that most of files I'm looking for time to time aren't anything
brand new, they've been on my disks for some time and that's why I forgot
where exactly they are.
So I tried the concept of unix (linux) tool 'locate' on DOS based systems. Not
only it works, but it works fast! The basic principle is that you don't need to
scan all your diskspace every time you want to find something. Usually it's
better to have a database of your files and just refresh it time to time.
(That's what unix locate command does - scan a database that they recommend
refreshing every week.)

A good thing about DOS version of locate is that it runs pretty very fast.
[Time to scan info about 5000 files was on a disk-cached P133 about 1.5 sec.
and finding in the database is usually much faster.]


3. Basic usage
==============

System requirements:
170kB free conventional memory should do fine, but I didn't do any thorough
testing.
I tested it on MS-DOS 6.22 system, but I guess that it should work all right
on older versions. Unfortunately I cannot do the testing, although I'm willing
to try LOCATE under win95. But only God knows what the LFN system will do.

Creating a database of your system doesn't take any long time, so it's
a good idea to place it in some batch script that you run once a day
automatically. [There's a lot of ways how to arrange that.]

Once you have the database, the easiest way to use is locate <searchstring>.
There are many options for both creating database and scanning it, most of
them both as commandline switches and options in configuration file.

There are two modes of operation - creating a database using /c or /u switches
(/c creates new, /u updates existing). Remember: /c or /u switch MUST be the
very first switch on the command-line, else it will be ignored!
Once the /c or /u switch is detected, all other switches are treated as
create_mode switches (they have different meaning than in find_mode).
Updating database means that LOCATE will read header of an existing database and
take settings from there, overriding settings from BOTH command line and INI
file. (Affected options are: driveletters to search and fields (date, time,
size) to include in database).


Find mode is used by default with no extra switch required.

So, the most common setup looks like this:

First, you run LOCATE /c [other create_mode switches]
Then you may use LOCATE /u [other create_mode switches] to update current
database (best automatically in ONCEADAY.BAT or similar file).
[See below for more info on update]

And every time you need to find something, you run
LOCATE [find options] searchstring [more searchstrings]
[Note that options and searchstrings may be mixed, but all options will affect
all search results.]

Everything, that begins with a slash ('/'), is treated like switch
[and when not defined to switch any option, then it is ignored]
Everything else is treated as searchstring

LOCATE does always a conjunction of searchstrings. It will try to match search
parameters one-by-one to every record of database, so the results are NOT
grouped by searchstring, instead their order corresponds to order of records in
database.


4. Help on all switches and configuration
=========================================

Although the INI file seems to be self-explanatory, I'll spend some time
explaining it's contents....

As in every good config file, there's a comment character, hash '#'
Every line, that begins with a hash, is treated like comment (aka ignored)
Options MUST have the following syntax (all spaces will be ignored)
OPTION=VALUE

Options are divided into two sections, although they can get mixed.
Options regarding creating databases are these:

CDATE=boolean (yes,no,1,0)
CTIME=boolean
CSIZE=boolean
These three affect, whether there will be date, time and size column in the
database. (The Pathname column is there always)

VERBOSITY=0|1|2
Verbosity level 0 means that there's absolutely no output to screen while
creating the database, except error messages (unaccessible drives etc.)
Level 1 (default) will print a dot for every directory being browsed
Level 2 will print every directory pathname and final statistics.

DRIVES=ABCD..Z | ALL
This option tells LOCATE, which drive letters to scan.
[Note that before scanning, LOCATE tests read access to each drive and will only
scan those it can read from. Unaccessible drive will cause an error message to
appear, but will not stop the processing.]
This option can have a special value ALL, that will cause LOCATE to attempt
to get last drive letter (environment variable LASTDRIVE, if not defined,
assumes 'Z') and scan all letters between C and lastdrive....

UPDATE=boolean
Update will force LOCATE to check existing database and take all create options
(drives to search and fields to include) from it's very first line. LOCATE will
ignore INI setting and cmdline parameters for those options. If set to YES, can
be overriden by the /c switch from cmdline, so that LOCATE will create a new
database rather than updating the existing one.

COMPACT=boolean
Using compact database results in ommitting duplicate directory names in
the database, thus making the database file smaller (the deeper your directory
tree is, the bigger savings here). Yet the original option of full pathname of
every file was left there, as it sometimes can be useful for manual viewing and
processing of the database. The database type is marked in it's header.


Options in find mode

FDATE=boolean
FSIZE=boolean
FTIME=boolean
These three affect how much information will be printed from database for
matching files. If the database doesn't contain selected information, those
options are automatically overridden to NO. [The first line of database contains
a header line, describing the contents... DON'T mess with it!]

PAUSE=n
Pause causes LOCATE to interrupt listing of matching files every n lines,
waiting for a keypress. Putting 0 there disables Pause totally.

OUTFILE=[Drive:][\path\]filename.ext
Here you can specify pathname to a file, where locate should place it's output.
This default setting is used only if the /o option (that invokes output to file)
has no filename as argument.

QUIET=boolean
In quiet mode, no regular output goes to screen. Very useful in script runs,
where you output to a file and do not want anything to appear on the screen.

FILEOUTPUT=boolean
Outputting to the default output file (see above) can be enabled here.
Note that LOCATE will overwrite, not append to, existing file.
[May add a switch for that later...]
And, also note that enabling output to file DOESN'T disable output to screen.

FDRIVES=ABCD..Z | ALL
Here you can restrict output only to files on selected drives.
[LOCATE will, of course, detect, which drives are scanned in the current
database]
Useful if you have indexed i.e. some backup CD disc, but usually don't care
about those files... so that you specify to not scan database records for drive
R: by default and only when you'll positively want to find a file even on that
CD, you'll use command-line switch '/dall'

FILENAMEONLY=boolean
Enabling this option causes LOCATE to scan only the filename from records in
database (in fact, it scans everything past last '\' in every record, but unless
you've messed with the data file, there should be nothing but filenames.)

WHOLEWORDS=boolean
This option causes LOCATE to match searchstrings only by full directory
name or filename (without extension). So, typing 'locate /w dos' will report all
files from the directory DOS and all files called DOS.*, but not files like
DOSPRMPT.PIF or DOSAPP.FON etc.


Command-line options:
        [where * is either (y,Y,+ or nothing) or (n,N,-)]

/u        Update database. Must be the FIRST switch. Ignores INI and cmdline
          settings for drives, size, time and date, instead takes settings from
          existing database.
/c        Create database. Must be the FIRST switch
/a*       Include date [in database when after /c or /u, otherwise in output]
/t*       Include time                    ""
/s*       Include size                    ""
/dX       Drive letters to use (for scanning with /c or /u and, otherwise for
          finding in database file), where X is one or more driveletters, not
          separated at all, or ALL to use all drives available.
/v        verbose level 2 (see above) (only with /c)
/q        with /c gives verbose level 0 (see above)
          in finding mode no screen output [only final stat appears]
/pn       Pause output after every n lines (0 means no pause)
         If n is ommited, default is 23
/o[file]  Send output to file, if not specified, default used (see above)
/f*       Search only filename part of database for searchstrings
/n[+|-|=]size   Will display only those files, that match any of the
                searchstrings AND filesize criteria.
                /n=0 will show only files with zero length,
                /n+1024 will show only files greater than 1kB
                /n-1024 will show only files smaller than 1kB

/w*       Wholewords search
/m*       Comma delimited format is used for output file.
/h<path>  Path to LOCATE.DAT database, needed if it's not the same directory
          as the EXE.
          Works also in create mode. This is useful for creating and using
          multiple databases, ie. using .BAT files.


5. Hints
========

All parameters are case INsensitive...

All parameters MUST start with '/' or '-'
[everything other is treated as searchstring!!!]

Order of parameters (except for /c) doesn't matter at all, only remember one
thing: If you use two parameters that contradict each other, the latter wins.
There's one little trick: Using locate /c(/u) /v /q will cause it to display no
notification of it's progress, but show final statistics!

If you want to use more databases (ie. default one for local harddisks,
another one for network drives and yet another for a CD drive), do this:
Create some .BAT files (or 4DOS/NDOS aliases) like:
        NETFIND.BAT     locate %& /hC:\NET\
        CDFIND.BAT      locate %& /hC:\CD\
where the paths will point to different directories, where the databases will be
kept. Afterwards, whenever you run NETFIND.BAT, locate will look in C:\NET\
directory for it's database. Similarly NETFIND /c will create a database there.

UPD.BAT contains 4DOS update command to put i.e. into AUTOEXEC.BAT or 4START.BAT
to update database automatically at bootup, if the database file is older than
specified amount of days.

If you want to include for example several CD-ROM disc listings in your
database, do the following: [supposing E: is your CD-ROM drive letter]
1)   locate /c /dE [other options]
2)   Now copy locate.dat to i.e. locate.1
3)   Edit the new copy, delete! the first line with header and do a global
     replace command in your editor: Find E:\, Replace with i.e. G:\
4)   Repeat this with every CD disc, each time choosing a different filename and
     different letter to replace G:\, but using the same other options (a,s,t)
5)   When this is done, delete the last locate.dat. Then merge all edited files
     into one (You should have now one big file with listing of all the discs,
     each under different letter.)
6)   The last thing you have to do (and better write some cool script for that)
     would be: run locate on all your hard disk drives. THEN change the header
     of this file to add those fake driveletters your CDs have been signed in
     step 3) AND somehow append the big CD listing file to your actual
     LOCATE.DAT. If you set default finding options to your harddrives, you will
     not be bothered by output from those CDs, unless you run: locate
     searchstring /dALL

     Hope you understand what I mean...


6. Errorlevels
==============

Locate will set dos ERRORLEVEL to a non-zero value every time it fails to
function normally. The errorlevels are:
1  Help page invoked
2  Error opening INI file for reading
3  Error opening database file for reading
4  Error opening database file for writing
5  Error opening output file for writing
6  No search string specified in find mode
7  Disk I/O error occurred
8  Filesize search invoked with non-numeric arguments
9  Filesize search invoked on database that doesn't contain the size column


7. Thanx
========
This bit of software was born in pain, as I'm not really a programmer.
I wish to thank mainly to my friend Tuttle [tuttle@pinknet.cz],
who's helped much with the optimization of code and also testing.
Another thorough tester and user, who deserves to be mentioned, is
Ludek Vasta [ludek@vse.cz], net-admin at my Uni.
And, of course, thank you all for using this product and thank twice you all
who cared to send in a mail or postcard.


8. Revision history
===================
v 1.10  A major upgrade, overworking numeric operations to work along with text
        searchstrings.
        Added compact option for database creation, saving disk space.
        Reworked the TXT again.
        Added a little of foolproof checking etc.

v 1.04  Inverted output of date field to yyyy-mm-dd, so the database file
        and output files could be sorted by date easily.
        Corrected this damn TXT.

v 1.03  Added /u switch, fixed compatibility with NoWell Netware 4.01,
        speed optimization.

v 1.02  Added /m switch, finished the damn TXT, removed a few little bugs

v 1.01  Reworked help, added /w switch

v 1.00  Some error checking was improved, so the home-tested and used beta
        version could be released...
