Version 1.06 8th Release
Copyright (c) 1988-90, MJ Poczynek

DOCUMENTATION

The Ultimate Master File List Generator/Analyser
for Files.Bbs compatable systems.

FidoNet 1:244/113
AlterNet 89:481/2
Hamilton, Ontario, CANADA
BBS : (416)560-5546, HST 14.4K
Voice : 549-1189, 549-4477, 549-2696







Introduction
============

Every BBS should have a master FILES listing available.

FILES is used to generate a Master File List (or MFL) for
use as the "FILES" listing sent by a FidoNet Standard BBS
(Bulletin Board System) apon file request. But you do not
have to be in a network to use FILES.

To use FILES your BBS must support the FILES.BBS industry
standard, this includes QuickBBS, Fido, Remote Access,
and several other bulletin boards. This is the only
requirement for FILES to work. If you file request a MFL
from another BBS it is your duty to offer the same, and
FILES is the ultimate tool to allow you to offer just that.
FILES works especially well with QuickBBS as this is what
I'm currently running in cooperation with the D'Bridge front
end mailer.

When FILES has completed its work you will end up with a
complete list of files including the Filename, Size, and
Description. Optionally you will be able to include
the Date of the File, the approximate transfer time (at
300, 1200, or 2400 Baud), as well as a few statistics
(Quantity of files, Averages, etc.). With this in mind
FILES is still amazingly quick, I compile over 1300
entries from over 27 file areas in less then 35 seconds.

Most Sysops will ARC/ZIP the MFL into a file usually named
according to his or her node number. For instance I use
"244_113.ZIP". In my ZIP file I include the MFL as
"244_113.LST". This includes the header and footer files
which offer information about my system as well as "special
file names" and "function requests". Naming the MFL in
accordance with your node number saves confusion. Too many
times have I gotten a hold of a list called "ALLFILES.TXT"
and not knowing which BBS it was from. Some Sysops don't
even include there node number or place of origin in the
list.

Even if you are not a member of a network, place your MFL in
your download area for your users. I'm sure they will
appreciate a complete listing of files available on your
system as well as a few interesting statistics.

I feel you will find FILES more then just another run of
the mill Master File List Generator.


Licensing Aggreement
====================

You are hereby granted a license to use, share, copy, and
distribute FILES and its documentation, provided that this
notice, and the Copyright information is not removed and/or
altered in any way form. No fee or consideration is to be
charged for the distribution. FILES is provided on an AS-IS
basis without warranty of any kind expressed or implied. The
entire risk as to quality and performance of FILES rests
solely with the user. In no event will the author be liable
to you for any damages, consequential or inconsequential.
By operating FILES, you acknowledge you have read and under-
tand this agreement and agree to be bound by its terms and
conditions.


Features Overview
=================

o WORKS WITH ANY BBS that uses the FILES.BBS standard inclu-
ding Fido, Opus, QuickBBS, Remote Access, and many more.

o VERY FLEXABLE AND EASY TO SET-UP. Will handle the simpl-
est to the most complex applications. FILES will compile
as many areas as you require, there is no limit.

o FANTASTIC COLOURFUL USER INTERFACE makes compiling your
MFL very exciting.

o OPTION TO ADD A HEADER AND FOOTER FILE. Your "FILES" acr-
hive no longer has to be several different files. FILES
allows you to include a header and footer file with every
MFL.

o Runs under DOS 2.x, 3.x, and 4.x. From the DOS prompt or
through a batch file. Being a VERY STABLE program you
don't have to worry about midnight crashes.

o SELECTABLE OUTPUT LIST FILENAME. Call the output file
anything you wish.

o USES THE QUICKBBS FLSEARCH.CTL FILE for quick and easy
installation.

o Optionally exclude the FILE DATE, ROUND FILE SIZES to the
nearest kilobyte (K), add a nice STATISTICAL REPORT to
every MFL, SKIP REMARK lines, and LABEL AREAS.

o FILES will now allow you to COUNT UP TO 5 DIFFERENT FILE-
NAME EXTENTIONS plus missing files. Super for GIF, MAC,
TXT, ARC, and ZIP files.

o ALIGN FILENAME EXTENTIONS for a much neater look.

o COMPUTE AVERAGE TRANSFER TIMES for a file. What a great
asset to the long distance caller.

o PROGRESS GRAPH lets you know something is happening.

o And MUCH, MUCH, MORE ... Check it out! It only takes a
couple minutes to install. Make your MFL available to your
BBS users, not just by file requesting (my MFL has been
downloaded several hundred times). Very popular.


Just a few comments I have received
===================================

... "Everyone I know uses FILES, there is just nothing that
compares to it."

... "I was really surprised to see what I could do to spruce
up my master file list with the use of FILES."

... "An incredible package, makes all other master file list
compilers look like a joke, amazingly fast!"


Archive Contents
================

The complete FILES package includes the following files
(no pun intended). If your package is incomplete or you
want the insure you have the latest version don't hesistate
to file request my BBS or log-on.

FILESnnn.EXE ... Where nnn is the version number. This would
be the main executable file. This is the
actual FILES program that does all the
work.

FILESnnn.DOC ... The complete documentation.

FILES.CFG ...... The sample configuration file.

244_113.LST .... My sample output from FILES.

HEADER ......... Sample Header file.

FOOTER ......... Sample Footer file.

FLSEARCH.CTL ... Sample QuickBBS file search file format.


To get started QUICKLY!
=======================

If you're like me and just like to get a program up and
running without reading 100,000 pages of documentation then
FILES is your kind of program. To get FILES up and running
FAST, simply edit FILES.CFG and FLSEARCH.CTL then run
FILESnnn.EXE to make the MFL. Simple isn't it? For those
of you that wish to take advantage of every single powerful
command please read on.


Installation
============

To set-up FILES, all you have to do is place FILES.CFG in the
same directory as the FILES program (FILESnnn.EXE). This
may be in a sub-directory or your BBS directory. You may
either edit the example that has been provided or create
your own. "FILES.CFG" is the default configuration file
name, you may use the "/F=" command line parameter to use an
alternate filename (discussed later).

The structure of the configuration file is as follows :

////////////////////////////////////////////////////////////
;
; FILES.CFG
;
; Configuration for "FILES" Master File Generator/Analyser
; Copyright (c) 1988-90, MJ Poczynek
; All keywords may not be present in this example
;
OUTPUTFILE E:\FILES\244_113.LST ; Name of MFL
AREALIST C:\FLSEARCH.CTL ; List of File Areas
; HEADER \HEADER.TXT ; Header File?
; FOOTER FOOTER.TXT ; Footer File?
; NODATE ; Don't DATE files
; NOREPORT ; Don't add report
; ROUNDIT ; Round to nnnK
; SUMMARY ; Print Stats
; SKIPREM ; Don't print comments
; LABEL ; Label Area
COUNT ZIP MAC GIF TXT ARC ; Count these extentions
SECURITY 1000 ; Use areas w/1000 or less
; ALIGN ; Align file extentions
XFERTIME 1200 ; Estimate Xfer time
;
////////////////////////////////////////////////////////////


Where :


OUTPUTFILE
----------

The name of the file you wish to create, in
otherwords the finished Master File List. If this
keyword is omitted the default file name is "FILES.TXT".
It is suggested that you use your node number as your
MFL's name but it doesn't matter to FILES. For example I
use "244_113.LST". This filename must of coarse abide by
DOS rules.


AREALIST
--------

The name of the file that lists the DOS paths where all
your file areas are located. This is the same
format as the QuickBBS "FLSEARCH.CTL" file. The format
is as follows :

//////////////////////////////////////////////////////////
;
; FLSEARCH.CTL
;
C:\FILES\TERM 5 Terminals
C:\FILES\BBS 5 BBS_Programs
C:\FILES\COMM 10 General_Communications
; ^
; The underscore represents a space in this control file.
;
//////////////////////////////////////////////////////////

The above file contains the Path to the Area, the
access level for a user to access the area, and the
title of the area. If you are not running in a
QuickBBS enviroment and wish to use the Area Name
parameter simply supply a dummy parameter for the
access level. A trailing backslash is optional in
the "Path to Area" parameter as far as FILES is
concerned.


HEADER
------

Simply a text file which may contain information about
your BBS, your Name, hours ect. The MFL is simply
appended to this file. The default is no header file.


FOOTER
------

The same as HEADER but is placed at the end of the
MFL.


NODATE
------

Instructs FILES not to specify the File Dates in the MFL.
This may save a bit of space.


NOREPORT
--------

Instructs FILES not to put the little report on the
bottom of the MFL. If this parameter is omitted the report
will be compiled along with the MFL.


ROUNDIT
-------

Instructs FILES to round all file sizes to a 3-digit
integer. So rather then printing "156296" FILES will
print "152K" since a kilobyte is 1024 bytes. If the
File size is less then 1K, Files will indicate "1K".


SUMMARY
-------

Prints a few statistics at the end of a completed area
including Total Entries and # of bytes.


XFERTIME
--------

Allows you to include the approximate XModem transfer
time at 300, 1200, or 2400 baud.

Syntax :

XFERTIME n

Where n is 300, 1200, or 2400.

ie.

XFERTIME 2400


SKIPREM
-------

Causes FILES to ignore comment lines and not
print them to the MFL. Comment lines begin with either
a Space or a Dash.


LABEL
-----

Instructs FILES to label all the areas in the MFL with the
File Area Title from the FLSEARCH.CTL file, if the title
is not available the path will be used. I suggest that
SKIPREM and LABEL are used together.


COUNT
-----

Allows FILES to count the number of entries in the MFL
with a certain extention. Up to 5 extentions may be
specified.

Syntax :

COUNT MAC ARC GIF

This would count all files with the DOS extension ".MAC",
".ARC", and ".GIF". These totals will be placed in the
report. Missing files are automatically included.


SECURITY
--------

Allows the QuickBBS user to use his or her existing
FLSEARCH.CTL file without modification or reduplication.

Syntax :

SECURITY 1000

This would make files use all the areas specified in the
FLSEARCH.CTL with a security level less or equal to 1000.
With the SECURITY option disabled FILES uses the value
of 32000, which is the highest possible security level in
a QuickBBS system.


ALIGN
-----

Instructs FILES to align all the file extentions in one
column. For example :

Without the Align Parameter the MFL would have output
something like this :

/////////////////////////////////////////////////
FILES103.ZIP 60087 Master File List Generator.
TEST.ZIP 221098 Test File.
/////////////////////////////////////////////////

With the align parameter :

/////////////////////////////////////////////////
FILES103.ZIP 60087 Master File List Generator.
TEST .ZIP 221098 Test File.
/////////////////////////////////////////////////

^ Notice how the extention is lined up in the
second example.


WINDOW
------

This should speed up FILES somewhat but eliminating five
second delays on "Registered Version" and "Process comple-
ted" windows at the start and end of the program. This
command is available only to Registered users. Delays may
be longer for non-registered versions.


MAXIMUM
-------

Older versions had a limit of only 200 file areas. FILES
v1.06 and better now allow the user to vary the amount of
file areas from 1 to 1000. The default value being 200,
you may find that you save a bit of memory by decreasing
the MAXIMUM parameter, although in most cases this would
not be nessesary. I suggest against decreasing this value
as FILES may crash if you add more file areas.


OFFLINE
-------

Tells FILES to use the word "Offline" rather then "Missing"
for non-existant files. This seems to be the trend in
QuickBBS wording.


NEW
---

Now you can highlight those files which are newer then x
days with the "NEW" parameter.

Syntax :

NEW 30

This would mark all files with an "*" that are up to 30
days old.


MONTH
-----

If you're are one of those people that gets annoyed when
you have to figure out if "02-04-90" means "February the
forth" or "April the second" then the "MONTH" parameter
is for you.

"MONTH" converts dates like "02-04-90" to "FE-04-90" for a
much easier date to read. When clarity is important, use
this command.


To Execute FILES
================

Simply type the name of the .EXE file at the DOS prompt
followed by the optional command line switches. Usually
FILES will be named something simular to "FILESnnn"
where nnn is the version. FILES would usually be executed
every night in your BBS cleanup routine to keep the list
accurate.

For example FILES ver 1.06 would be named "FILES106.EXE".


Command Line Switches
=====================

Alternate Configuration Filename /F=[d:][path][filespec]
---------------------------------------------------------

Use an alternate Configuration file name other then the
default of "FILES.CFG".

Syntax :

C> FILES100 /F=D:\QUICKBBS\NEW.CTL

or

C> FILES100 /F=NEW.CTL

The second example would assume NEW.CTL is in the default
directory.

Using the "/F=" parameter also allows you to place the
control file in a separate directory away from the main
FILES program.


Program Version ID /V
----------------------

Causes FILES display the Copyright notice and the
program version then return to the DOS prompt. This is
for ID purposes only. FILES is protected with various
encryption routines to protect against file editors.
Placing "VER" in the configuration file gives the same
result.


Conclusion and Registration Information
=======================================

FILES represents a great deal of work and planning. If you
feel this program meets your needs please send your donation
of $15.00 drawable on a Canadian bank to :

Michael J. Poczynek
1381 King Street East
Hamilton, Ontario, CANADA
L8M 1H6

Along with the following information :

////////////////////////////////////////////////////////////

REGISTRATION FORM FOR FILES
===========================

Full Name (first & last) ..................................

Address : ........................... Apartment# : ......

City : ........................ Zip/Postal : ........

Country : __ Canada __ USA or Other ...................

Home Phone : (...) ...- .... Office Phone : (...)...-.....

BBS Name (Exact wording, as this is what will appear at the
bottom of your completed MFL)

............................................................

Network Node number(s) : ................. Fido/Alter/Other?

Is it OK to send the Numeric Key to your node number :
__ YES __ NO, send it via the mail.

Does your BBS operate 24 hrs/day? If not please state hours

__ YES __ NO. Hours : ..................................

What BBS software are you running :

__ QuickBBS __ RemoteAccess __ Fido __ Opus

Other ......................................................

////////////////////////////////////////////////////////////

In turn you will receive a numeric key to be installed in
your FILES.CFG (or same) file which will allow you to remove
the "Unregistered Version" screen as well as print "Regi-
stered to : your BBS name" on the bottom of the completed
MFL by using the "WINDOW" command. Support freeware, send
your contribution today!

Numeric keys will be sent out via Netmail or general postal
service. Keys are non-transferable.

If you have any suggestions or problems please do not
hesistate to drop me a note via matrix mail or general
postal service. Long distance replies may be picked up one
week later if sent via Netmail.

I like to have the source code available for all the
programs I run, therefore I'm offering the QuickBASIC
v4.0 source as well as the Assembler routines for only $80.

I do plan to keep adding to this program so
stay tuned, I plan to make FILES the 'Best' Master File
List generator available (if it isn't already).


Where can I find the latest version of FILES?
=============================================

The latest version of FILES is available by requesting
'NEWFILES' from my system. FidoNet 1:244/113, or AlterNet
89:481/2, these numbers do change sometimes so just search
for my name, or the BBS name in the nodelist. File Request
hours are 0:00-NHM EST. As always I have a FILES listing
waiting for you as well!


Have an idea?
=============

Do you have an original idea for a program? Let me know
I'm always interested in taking on new programming projects.


Notes
=====

- Comments in a "FILES.BBS" are allowed by simply putting
a [Space], or a "-" (dash) as the first character on
the line. This abides to QuickBBS/Fido/Opus specs to the
best of my knowledge. The ";" must be used in all
control files for comments.


Hints & Tips
============

o To make things easier only the first three characters are
recognized by FILES. So instead of having to type the
keyword "LABEL" simply use "LAB" to save time and key-
strokes.

o Be sure to instruct your front end mailer to send your
prepared MFL when someone requests "FILES". Depending on
what mailer you are using the procedure may be different
therefore not discussed in this documentation.


Revision History
================

1.00 : First release, Dec 7/88.
----


1.01 : Second release, Jan 23/89.
----

- Refined the code to be faster.

- Added a little report at the end of the MFL.

- More logic implemented with Control files. Comments
are allowed by prefixing them with a ";", this is a
standard procedure with most control files used with
QuickBBS.

- Fixed a problem with missing files.

- FILES now tells the user how many entries are in each
"FILES.BBS" after the area has been processed.

- It no longer matters if there is a trailing backslash in
the File Area Path file.

- You may now have a "FOOTER" as well as a "HEADER"
file, this is is handy for legends, about the BBS,
etc.

- You now have the option to disallow a report by using
the "NOREPORT" keyword in your Configuration file.

- File Dates can be left out by using the "NODATE"
keyword.


1.02 : Third release, Feb 12/89.
----

- Now using QuickBASIC v4.5, which I might point out
has reduced the size of the EXE file.

- New advanced routines handle control files more
efficiently and allow the user to neatly space
parameters, add comments, etc.

- User may now specify an another name for the control
file with the "/F=" parameter on the command line.

- In the Configuration file the first 3 letters of the a
parameter may be used rather then the entire key
word.


1.03 : Forth release, April 2/89.
----

- "ROUNDIT" parameter allows the user to round all file
sizes to three digits and print in the MFL as "nnnK"
where nnn is the file size.

- "SUMMARY" parameter makes FILES print a small line of
statistics after each file area.

- A bug which made FILES crash if a Files.Bbs file was
missing is now fixed.

- FILES now takes advantage of the File Area Name
aspect of your "FLSEARCH.CTL", this is the third
parameter on the line.

- When FILES compiles the MFL it will use the Area Name
rather then the path if it's availible. This should
make things easier to follow.

- You may now include an estimated XModem transfer time
with the "XFERTIME" parameter following by the baud
rate (300, 1200, 2400).

- Just for reference my FidoNet Node Number has been
changed from 1:148/268 to 1:250/214 due to Net
reorganization.

- "SKIPREM" parameter will make cause FILES to not
print comment lines to the MFL.

- "LABEL" will label all the file areas.


1.04 : Fifth release, April 16/89.
----

- The "COUNT" parameter allows FILES to count the
number of entries in the MFL with a certain
extention. Up to 5 extentions may be specified.

- FILES now uses the security level option of the
"FLSEARCH.CTL" file.

- Fixed a bug with the ROUNDIT 0K problem pointed out
by Ben Kalika of The Sports Board.

- "ALIGN" will make FILES align all the file extentions in
one column.

- FILES will now tell the user how many bytes each file
area contains.


1.05 : Sixth release, May 30/89.
----

- FILES user interface has been improved.

- The documentation has been cleaned up.

- My node number has been changed again due to me
becomming the HUB, I will now use 1:250/201.

- FILES now converts values like 1.223785+E07 in the area totals
to kilobytes.


1.05B: Seventh release, April 15/90.
-----

- Simply included information about my new node number.


1.06 : Eighth release, ??????????????????????????????????????
----

- Indicated new node numbers on program.

- Improved and revised documentation. I feel the key to a
succesful program is proper instructions and reference
material.

- Added registration and "Process Complete" windows.

- FILES now requires a numeric key or prints "Unregister-
ed version" at the bottom of the MFL.

- "WINDOW" parameter which will get rid of all Windows.

- "MAXIMUM" parameter allows the user to allow FILES
compile more or less then 200 file areas.

- You now know how long it takes to compile your MFL in
number of seconds.

- A progress graph has been added to the bottom of the
display, each block represents a file being processed.
This handy addition allows you to actually watch the
files being processed.

- "OFFLINE" parameter for users who prefer "Offline" to
"Missing" for non-existant files. This seems to be the
in thing for the new QuickBBS, don't ask me why.

- "NEW" parameter allows the user to mark files newer
then x days old with an "*".

- As QuickBBS or FileDoor appear to sometimes want to
start writing the description at coloumn 15 rather then
the usual 14, FILES compensates for this and makes
everything appear neat on the completed MFL.

- "MONTH" parameter makes FILES change a file date like
"02-14-90" to "FE-14-90" which I feel makes things alot
easier to compute.


*EOF: Files106.Doc