---------------------------------------------------------------------
| AvaiList 1.60 |
| |
| USER MANUAL |
| |
| Copyright (c) 1988-1990 Andrew D. Farmer. All Rights Reserved. |
---------------------------------------------------------------------

----------------------
THE LEGAL BUSINESS
----------------------

AvaiList is only guaranteed to take up space on your disk drive. Use
it at your own risk. No warranty is stated or implied. The author
shall not be responsible for any damages resulting from it's use,
directly or indirectly.

AvaiList is distributed as a Freely Available Copyrighted Program, no
fee may be charged for distribution and the distribution archive is
not to be tampered with or altered in ANY way. It may be repackaged
using a different archival method as long as the contents of the
archive are the same as that of the distribution kit.

AT NO TIME are files to be added to the archive that were not in the
original distribution archive and AT NO TIME is an archive comment to
be added to the archive.

With the exception of archiving method, AvaiList cannot be distributed
in a modified form of any sort.

While AvaiList is freely available for use in non-corporate environs,
donations to the author will always be gratefully accepted.

If you plan on running AvaiList in a corporate or profit making envir-
onment, contact the author about licencing.

The Author may be contacted at the following addresses:

Network: 1:163/115@fidonet

Surface: Andrew D. Farmer
P.O.Box 11087 Station H
Nepean, Ontario
K2H 7T8 CANADA


-------------------------------------------
THE DISTRIBUTION ARCHIVE (ALST_160.ZIP)
-------------------------------------------

This archive should have included the following files:

AVAILIST.DOC - The Documentation, you read it as we speak.
AVAILIST.CFG - Sample Configuration File.
AVAILIST.EXE - The Executable Program.
WHATSNEW.160 - Release Notes.


--------------------------------------------------
THE CONFIGURATION FILE (DEFAULT: AVAILIST.CFG)
--------------------------------------------------

You may select a different name (or Path) for your Configuration file
by using the -C command line switch.

A note about Schedule Tags:

A Sched tag is the word SCHED followed by a tag of up to 12
Characters in length. Any Options enabled above the first Sched Tag
will be treated as Global settings and information under each Sched
tag will be local to that Schedule only. There is no limit the
number of Schedules that can be present in one Configuration file. A
Schedule is defined as everything under a Schedule Tag until another
SCHED line in found, or EOF is reached. If you do not have a
schedule tag in your config file, AvaiList will behave exactly as it
does with previous versions. The SCHED keyword must begin in Column 1
and there must be one (and only one) space between the SCHED keyword
and the Tag name.

If you *do* specify Schedule(s) there are some rules:

1) The LOGFILE keyword must be in the Global area.

2) The OUTFILE, NEWFILE, OPUS103 and AREA keywords must be in a
Local schedule. They cannot be in the Global area.

3) All other options may be in either Global or Local areas.

4) See the entry on the -S command line switch, below.


Other Configuration File Keywords are:


* AREA [PathToFileArea]

This tells AvaiList what areas to scan to create the Master and New
File Lists, it is required unless the OPUS103 keyword is used.

You may optionally specify the description of the area after the
path, this description will override any description found in the
DIR.BBS file.

There may be up to 200 AREA statements specified.


* ARCHIVE

This turns Archive Mode On, it will cause the finished Master
List, and NewFile list if selected, to be Archived into an Arc
file using the same trunk name as the Master File, and the
Extention of the Archiver Used.

The modifier 'arc_cmd' is one of the following: ARC, DWC, LHARC,
ARCA, PKARC, PKPAK, PAK, ZIP or ZOO. If no 'arc_cmd' modifier is
specified it will default to using LHARC.


* BOXTYPE [#]

Allows you to selct what sort of Box will be used in the Output
lists. BoxType's 1 through 4 use IBM-PC characters, therefore to
disable the use of the IBM Extended Character set you must use a
BoxType of 0. The default BoxType is 4.

BoxTypes are:

0 1 2 3 4 0 = Hatches (Non-IBM)
--- 1 = Single Rule
2 = Double Rule
--- 3 = Single Top, Double Sides
4 = Double Top, Single Sides


* EXTRA [filespec]

Allows you to override the default 'Extra Info' File Name.


* FLAGCHAR [Char]

Allows you to select what identification character to use for
flaging of NEW files. Default action is to use an asterix (*).


* FLAGNEW

This keyword turns NewFile flagging on. If this keyword is used,
all files less than 7 days old will have an asterix (*) placed
beside its entry in the Master List.

If you plan on using the NEWFILE keyword to create an output
list of New Files, it should be noted that this FLAGNEW keyword
is a pre-requisite for use of the NEWFILE keyword.

The Optional modifier 'days' can be any number between 1 and 99.
This sets the maximum number of days old a file can be and still
get flagged as new. As stated above, the default value is 7
days, use this modifier to change that default.


* HEADER [filespec]

Allows you to override the default 'Header' File Name.


* KILLOFFLINE

By default, any files that are listed in the Files.Bbs, but do
not reside in the directory are listed in the list along with a
comment that they are off-line. If this keyword is used, those
'missing' files will simply be ignored, and not placed into the
list in any form.


* LOGFILE [filespec]

Causes AvaiList to keep a LogFile of all activity, and store it
in the file specified by 'filespec'.


* MOVE

When this keyword is used in conjunction with the ARCHIVE command,
it will cause the finished Master List to be Moved to the Archive
instead of simply being added. In other words it deletes the
original after Archiving.


* NEWFILE [filespec]

When this keyword is used in conjunction with the FLAGNEW keyword,
it causes an Output List of New Files to be created along with the
Master List. If this keyword is used, the 'filespec' is NOT
optional and must be provided for execution to occur.


* NOBIGTITLE

When this keyword is used it causes the Title for the area (as
taken from DIR.BBS or AREA statements in the config file) to be
left as it was entered by the user. Default action is to auto-
matically upper case said title.


* NOCOMMENTS

Comment Control keyword. If this keyword is used, then all of the
comments in Files.Bbs will NOT be copied to the Master List, but
instead will simply be ignored. Note: Comments lines will NEVER
be included in the New File List.


* NODATE

This keyword turns OFF the listing of the Date for each file. If
this keyword is not used, then the DOS Date for the file will be
automatically placed in the Master and NewFile Lists. Use this
keyword to disable that automatic addition.


* NOSPACECHECK

SOCIAL STATEMENT: I STRONGLY SUGGEST YOU DO NOT USE THIS KEYWORD

By default, AvaiList will refuse to run if there is less than
250K free on the Drive where the Master List is to be created.
This keyword will disable that disk space check.


* NOTOTAL

Causes the total number of Files & Bytes in each area NOT to be
reported at the end of that area's listing in the Master List.
Default action WILL report these totals.

This keyword has no effect on any NewFile list being produced.


* OUTFILE [filespec]

This is the name of the file to use for generating the Master
List. This keyword is NOT optional and must be provided for
execution to occur.


* SHOWORPHAN

Include Orphan files in the Master and NewFile Lists. An Orphan
file is a file that resides the directory, but is not listed in
the Files.Bbs file.

AvaiList will Skip any Files with the extention of .BBS or .BAK
in deciding if an Orphan exists.


* OPUS103 [PathToSystemFiles]

Causes AvaiList to search the Opus v1.03 System files for Path
Information. It will use ALL the areas it finds. AvaiList will
NEVER read Area 0, and will only search through the System files
until it detects a gap in the files (ie: it will only read the
System files one by one until it hits a number that doesn't have
a corresponding System??.Bbs file), this allows you to 'Hide' an
area, by placing a 'dead' area before it.

NOTE: The use of this keyword will over-ride any 'Area' keywords
in the Configuration file.


* VERBOSE

Causes AvaiList to run off at the mouth. If used a long 'Runtime
Configuartion' screen will be presented to you.


* WRAPDESC

By default AvaiList will truncate Files.Bbs descriptions so
that the entire line in the list is a maximum of 79 characters
in length. Using this option will cause AvaiList to wrap long
comments onto the following line(s), and properly format them.


See the sample AvaiList.Cfg file for more information on its usage.


-----------------
SUPPORT FILES
-----------------

* AVAILIST.HDR

AvaiList will search for this file in the default directory. If
found, the entire contents of the file will be placed at the Top of
the Master and NewFile Lists.

You may select a different name (or directory) for the file by using
the HEADER Configuration keyword.


* AVAILIST.EXI

AvaiList will search for this file in the default directory. If
found, the entire contents of the file will be placed into the
Master List between the the AvaiList.Hdr Information and the
Directory-by-Directory Listings.

This file can be extremely handy for listing such things as magic
file names or password restrictions.

You may select a different name (or directory) for the file by using
the EXTRA Configuration keyword.

Please note that this file WILL NOT be placed into NewFile Lists.


* DIR.BBS

If there is no Description specified in the AREA statement in the
Config file, then AvaiList will search for DIR.BBS in each of the
specified File Area Directories. The first line of DIR.BBS is used as
the Header for that block of Files. If the DIR.BBS file is not found
in the directory, then the Drive:\Path is used as the title.


* FILES.BBS

AvaiList will search for this file in each of the specified File
Area Directories. The FILES.BBS is used for a list of Files to place
into the Master List. If a FILES.BBS file is not found in the dir-
ectory, then 'No Files' is placed into the Master List.

Each Line of the Files.Bbs file is analyzed separately, if the
character in Column one (1) is a Hyphen (-) or a Space ( ), and you
have NOT used the NOCOMMENTS command, then the line is simply copied
wholesale into the Master List. Otherwise the 1st contiguous block
of characters is assumed to be the File Name and the Rest of the line
is assumed to be the Description. The lines will be Output to the
Master List in the form:

FileName Size-in-bytes File-Date-Stamp Description

You can disable the listing of File-Date-Stamp by using the NODATE
command, see the section "Configuration File" for more information.

If the FileName does not exist in the directory, then STORED will
appear in the Size-in-bytes area and OFF-LINE will appear in the
File-Date-Stamp area. If you use NODATE to suppress the File-Date-
Stamp, then non-existent files will be listed with the word OFFLINE
in the Size-in-bytes area.

I have also coded support for those that like to use wildcards in
Files.Bbs files. If more than one file in the directory matches the
FileName listed in Files.Bbs, then the Master List will contain
separate entries, including FileSize and DateStamp, for each file
matching the FileSpec. The single Description will be used for ALL
the matching entries.


-----------------------
COMMAND LINE SYNTAX
-----------------------

Syntax/Usage: AvaiList

The command Line switches may be placed in any order as long as they
are prefixed with either a / or a - symbol. Switches Listed in angle
brackets are optional. If no switches are used, a Syntax Summary will
be presented to you.


Switches are:

* -?

Display the Syntax/Usage screen, then abort with nothing done.


* -CConfigFile

By default AvaiList will search for AvaiList.Cfg in the default
directory, you may over-ride this by specifying a Configuration
File with this switch.


* -Efilespec

Allows you to override the default 'Extra Info' File Name.


* -Hfilespec

Allows you to override the default 'Header' File Name.


* -Llogfile

Causes AvaiList to keep a LogFile of all activity, and store it
in the file specified by 'logfile'.


* -Nfilespec

When this switch is used, it will over-ride the NEWFILE from the
Configuration File.


* -Ofilespec

When this switch is used, it will over-ride the OUTFILE from the
Configuration File.


* -Stag

Tells AvaiList which Schedule Tag to execute. If not specified
*all* tags will execute.


* -V

Causes AvaiList to run off at the mouth. If used a long 'Runtime
Configuartion' screen will be presented to you.


--------------------
EXIT ERRORLEVELS
--------------------

There are 3 possible ErrorLevels that AvaiList can return to DOS upon
program completion or abortion. They are as follows:

* ErrorLevel 2 - Not Enough Disk Space to Proceed.
* ErrorLevel 1 - Fatal Error, Program abortion occurs.
* ErrorLevel 0 - Successful Completion of AvailList.


------------------
CLOSING NATTER
------------------

I believe I have outlined everything in this documentation. I may have
left something out, and probably have. I expect I'll remember an
important one as soon as this release is on it's way through Software
Distribution ;-).

If you have any problems you can't fix or questions you can't answer
then please contact me via NetMail or surface mail. I will always do
my best to support my software, but it is, by definition un-supported.
I will answer queries as time allows, please be patient when awaiting
a reply.

Andrew Farmer
Ottawa, Canada
December 6, 1990

----------------------------------------------------------------------