Q L I S T
QuickBBS On-Line File Lister
Version 2.0
(c) Copyright 1988, 1989 by Richard Lovett
Kansas City, Mo.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
This program is public domain. No fee is requested, and
QLIST can be freely copied and distributed as long as it is
not sold or used in a commercial application. However, the
author retains a copyright and all of its associated rights
and privileges.
I wish to acknowledge the work of Dan Barrett of CORE BBS
(619-295-2912), whose QFL (QuickBBS File Lister) inspired me
to write QLIST. I have made liberal use of concepts from QFL,
but have put several additional features into QLIST that I hope
make it more useful.
Files that should be in this .ARC or .ZIP file are:
QLIST.EXE ----- The executable program
QLIST.DOC ----- This file
If you would like to repay me for the use of this program, let me
know how you like QLIST or what changes you'd like to see. Worse
than no payment for a program is no feedback.
VERSION HISTORY:
Ver. 1.0 -- Sept. 88 -- First public release.
Ver. 1.1 -- 9/19/88 --- Added features to generate statistics
on total files, total bytes and bytes
free in a file list.
Ver. 2.0 -- 3/1/89 ---- Made the file compression commands more
flexible to accomodate PKZIP and
future file compression programs. Fixed a
bug that caused filenames beginning with
a digit to be dropped from lists.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
QLIST produces an on-line list of all or part of the files on a
QuickBBS or Fido-Net bulletin board system. By means of a QBBS
or Fido event (in which the BBS exists to DOS at a predetermined
time and errorlevel and triggers a batch file), QLIST can be
set to produce this list -- or several different lists -- automat-
ically as often as you wish. My QBBS board executes QLIST at 1 a.m.
daily.
QLIST is keyed to security levels. Users will get a list of only
the files they have access to. You can have QLIST create lists for
as many different access levels as you want, and QLIST will store
each of them in whatever directory you specify. QLIST also can
compress the lists for easier downloading, using the file compres-
sion program of your choice.
QLIST requires three external files:
1. FLSEARCH.CTL. If you are a QuickBBS sysop, you know the purpose
of this file and how to create it. For the non-QBBS sysop,
FLSEARCH.CTL is a text file you create that contains paths and
privilege levels for each of the QBBS files subdirectories. If
you are a Fido-Net sysop, read below for instructions on
creating FLSEARCH.CTL. QLIST must be in the same directory as
FLSEARCH.CTL.
2. QLIST.CTL. This is another text file you create. It is a
setup file that tells QLIST what to do. QLIST.CTL must be in
the same directory as QLIST.
3. FILES.BBS. You probably have one of these files in each of
your BBS files subdirectories. QLIST uses FILES.BBS to know
what files are in each subdirectory, and also uses the
descriptions you have given to each file.
If QLIST cannot find FLSEARCH.CTL or QLIST.CTL, it will halt with an
error message. If it cannot find a FILES.BBS file in a particular
directory, it won't stop, but it won't produce a list of the files
in that directory. Conversely, QLIST will not include any files in
the output file that aren't listed in FILES.BBS.
You can run QLIST from the DOS command line by making sure the directory
containing QLIST and QuickBBS is the default and then typing "QLIST"
(without the quote marks) at the DOS prompt. Or, as indicated earlier,
you can include QLIST in a batch file.
When run, QLIST reads data from QLIST.CTL in order to know what lists
you want created, what privilege levels each list is associated with,
and the name and path of the output file for each list. QLIST then
reads data from FLSEARCH.CTL and matches security levels in each of
its file areas with the security levels you specified in QLIST.CTL.
For each list you specify in QLIST.CTL, QLIST creates a list of
all files with a security level equal to or less than the level you
desire, gives it a filename you specify, and puts it in whatever
subdirectory you want. You also have the option for QLIST to
compress the output file, and to erase the original afterward.
------------------
CREATING QLIST.CTL
------------------
QLIST.CTL is an ASCII text file that consists largely of keywords
(special commands), some followed by other text or commands. The
sample QLIST.CTL file below should make it clear how to write one.
There are 14 keywords. (As of Ver. 2, these include three new keywords
-- COMPRESS, COMMAND and COMPFILE -- and the keyword ARC has been
dropped.) The keywords can be typed in uppercase or lowercase, but
they should be flush left (no leading spaces) and should have at least
one space following them. The keywords are:
HEADER -- Header lines are printed at the top of the file list
and can include your BBS name, phone number, sysop name and
whatever else you want. You can have up to 10 header lines,
each up to 79 characters long. Each line will be centered.
Any text following the word HEADER will be put in the file. If
you want a blank line in the heading, just type HEADER on a line
by itself.
FOOTER -- Works the same as a header but is printed at the end of
the file. You can have up to 10 footer lines, each 79 or fewer
characters. Footer lines will be written flush left rather than
centered.
TARGET -- This is the full path and filename of the list file
that QLIST will create. You will want to make sure you put this
file in a subdirectory (file area) accessible to callers with the
security level you specify for this particular list.
SECURITY -- Whatever number you type after this keyword will
govern which of your BBS file areas will be listed in a
particular QLIST list. If you enter 5, QLIST will include all
file areas with a security of 5 or less. Numeric security levels
will mean more to QBBS sysops than to Fido sysops, but for purposes
of QLIST, both systems can use numeric privilege levels. (See the
section on FLSEARCH.CTL below.)
COMMENTS -- QLIST parses through the FILES.BBS file in each file
area that will be part of a list, and includes some of that
information in the output file. Most sysops put headings and
comments in their FILES.BBS files along with the filenames and
descriptions. If you put the keyword COMMENTS in a setup, those
extra lines will be included in the output. The default is to
leave them out.
If comments are omitted, that also omits any heading you may
have typed into FILES.BBS to tell users which file area is
being listed, etc. In that case, QLIST gets the name of the
file area from FLSEARCH.CTL. (The underline characters that
represent spaces in FLSEARCH.CTL will be converted to spaces.)
If comments are included, QLIST assumes that one or more of the
comment lines in FILES.BBS constitutes the heading, and will
not generate its own from FLSEARCH.CTL.
Similarly, if you include comments, QLIST assumes you have
included in FILES.BBS a header along the lines of:
FILENAME SIZE DATE DESCIPTION
-------- ---- ---- ------------------------------
Therefore, it will not generate its own. However, if COMMENTS is
not specified in the setup, QLIST will provide such a heading for
you.
MISSING -- If a filename is shown in FILES.BBS that doesn't exist
on disk, you can choose whether to have QLIST include that
filename and description in the output list. The default is
to show only files that actually exist. But if for some reason
you want missing files to show, include the keyword MISSING in
the setup. As with QuickBBS itself, QLIST will print "MISSING"
instead of the number of bytes for that file.
COMPRESS -- If you include this keyword in a setup, QLIST will
use your favorite file compression program (PKARC, PKZIP,
ARC5-1, etc.) to compress the output file. The word COMPRESS
*must* be followed by one or more spaces and then the full
path\filename of your file compression program. You also must be
sure to include COMMAND and COMPFILE commands in your setup.
COMMAND -- This keyword should be followed by one or more spaces
and then the command string you wish to pass to the file
compression program. The string can be up to 80 characters
long and can include full paths, switches and wildcards. This
is the same string you would type on the DOS command line
following the name of the compression program if you were
executing a compression from the DOS prompt. For example, if you
wanted to compress a file at the DOS prompt using PKZIP.EXE, you
might type:
PKZIP -a NEWFILE.ZIP C:\QUICK\BBSFILES.LST -ea4 -eb4
The command string passed to PKZIP in this example is
"-a NEWFILE.ZIP C:\QUICK\BBSFILES.LST -ea4 -eb4". That is what
you would type following the keyword COMMAND if using QLIST.
COMPFILE -- This keyword should be followed by one or more spaces
and then the full path\filename of the compressed file that
will result from executing the compression program. In the
above example, NEWFILE.ZIP is the name of the file after
compressing.
Before creating a compressed file, QLIST will first check to
see if a compressed file of the same name exists; if so, that
file will be erased. Otherwise, the compression program
(depending on which one your're using) might add the new list
to the old compressed file.
ERASE -- After QLIST compresses a list file, the original
file normally will be preserved. If you include the keyword
ERASE in your setup, QLIST will delete the original output
file. If you specify ERASE but not COMPRESS in your setup,
ERASE will be ignored. Otherwise, you'd have no original
output file and no compressed version either!
NOERROR -- QLIST generates an error file on disk called QLIST.ERR
if it has any problems. This is a text file that you can read in
order to find out why QLIST isn't producing the file lists you
intended. If there are problems you don't correct, this file
could grow after a while. Putting NOERROR in QLIST.CTL disables
the error file. Then your only indication of what's going wrong
will be on-screen error messages while QLIST is running. (They
duplicate what's printed in QLIST.ERR.)
NOTOTALS -- At the end of each output file, QLIST prints the total
number of files and the total bytes in the list. If you don't
want this information in the file, putting the keyword NOTOTALS
in QLIST.CTL will disable these entries.
FREE -- If you want QLIST to show at the end of the output file
how many bytes free remain on the disk drive containing QLIST,
put this keyword in QLIST.CTL. The file will then contain a line
just before the footers saying, "Space available -- xxx bytes",
giving the appropriate number. If your BBS files are spread across
more than one disk drive, the FREE command will give an inaccurate
reading. The default is to omit the bytes-free line.
END -- This marks the end of a setup and must be the last line in
the setup.
Any line in QLIST.CTL that does not begin with a keyword will be
ignored, so you can include blank lines and comments as you wish.
-----------------------
A SAMPLE QLIST.CTL FILE
-----------------------
** Sample QLIST.CTL file **
These three lines are a comment because they don't start with a keyword.
Keywords can be in caps or lowercase, or a mixture. (Note: keywords
should be flush left.)
HEADER City Hall BBS
HEADER Richard Lovett, Sysop
HEADER Operating at 300/1200 baud, 24 hrs./7 days a week
HEADER (816) 274-2603
HEADER The first municipally operated public bulletin board in America
HEADER and still the best.
HEADER --------------------------------------------------------------------
HEADER
(The header line immediately above will be a blank line)
NOERROR (This turns off the error file)
{ --------- all of the above need only appear once in QLIST.CTL ---------- }
*** This is setup #1 ****
TARGET C:\quick\lists\allfiles.lst
SECURITY 5
COMMENTS
MISSING
FOOTER For news you can use, watch Channel 25 on American Cablevision.
NOTOTALS (Total files & total bytes will not be shown in this list)
END
*** This is the second setup -- you could have many more ***
TARGET C:\QUICK\BBSFILES.LST
SECURITY 20
;MISSING This line is merely a comment because ";" is not part of a keyword
COMPRESS C:\UTILITY\PKZIP.EXE
COMMAND -a c:\quick\bbsfiles.zip c:\quick\bbsfiles.lst -ea4 -eb4
{ note that the path\file below duplicates the destination filename above}
COMPFILE c:\quick\bbsfiles.zip
ERASE (This erases BBSFILES.LST after BBSFILES.ZIP is created)
FREE (This adds a "Space available" statement)
END
------------------------
SAMPLE FLSEARCH.CTL FILE
------------------------
For the benefit of a non-QBBS sysop, FLSEARCH.CTL is an ASCII text file
that QuickBBS uses to search file directories when a caller asks for a
list of new files since he or she last called. QLIST uses FLSEARCH.CTL
for a different purpose: to know what file areas (subdirectories)
should be included in a particular on-line list.
Every line in FLSEARCH.CTL contains three elements, each separated by one
or more spaces. They must be in the following order and are not case
sensitive (either caps or lowercase is okay):
1. The full path to a file area
2. The minimum security level (privilege) associated with that area.
3. A name for the area. Any spaces in the name must be replaced
with underline characters. (QLIST will remove the underlines
later when it puts the name in a file list.)
An example FLSEARCH.CTL file:
C:\QUICK\SERVICES 5 Area_A_--_City_Services
C:\QUICK\LISTS 5 Area_B_--_Handy_Lists
C:\QUICK\RESERVED 20 Area_C_--_Privileged_Area
C:\QUICK\SYSOP 100 Area_Z_--_Sysop's_Private_Area
QuickBBS uses numeric security levels, whereas Fido-Net uses the
privilege levels TWIT, DISGRACE, NORMAL, PRIVEL, EXTRA and SYSOP. For
purposes of QLIST, a Fido sysop can assign an arbitrary security level
number to each of the file areas in FLSEARCH.CTL. "Normal" users could
have, say, level 5. "Privel" users could be level 20, "Extra" users 50
and "Sysop" users 100. These levels will not affect Fido in any way and
will only be used by QLIST. Don't use numbers bigger than 32767.
So, in the above FLSEARCH.CTL example and using the security levels just
suggested, "Normal" Fido users would have access to areas A and B;
"Privel" users would have access to A, B and C; and the sysop would have
access to all areas.
Assuming the above QLIST.CTL and FLSEARCH.CTL files are used, QLIST
would first generate a list of all the files in C:\QUICK\SERVICES and
C:\QUICK\LISTS and would name the resulting file ALLFILES.LST and put it
in the C:\QUICK\LISTS\ subdirectory, which (to state the obvious) is
one of the file areas accessible to level-5 users.
(** NOTE: It would be up to you to put an entry manually in
C:\QUICK\LISTS\FILES.BBS to indicate the presence of ALLFILES.LST.)
ALLFILES.LST would contain any comments that happened to be in the
FILES.BBS files in those subdirectories, and any filenames in
FILES.BBS that didn't exist on disk would be listed anyway. No
totals would be shown at the bottom of the list.
The program would then generate a list of all the files in
C:\QUICK\SERVICES, C:\QUICK\LISTS and C:\QUICK\RESERVED, name the
output file BBSFILES.LST and put it in the C:\QUICK\ subdirectory.
Comments in the various FILES.BBS files would not be included (because
the reserved word MISSING is commented out), and BBSFILES.LST would be
compressed after its creation. (Its name would then be BBSFILES.ZIP.)
The original BBSFILES.LST would then be erased. The list would
include a line at the bottom showing the total number of files in the
list and their total bytes (because NOTOTALS was not in the setup). A
line showing upload space available also would be added (because of
the presence of the keyword FREE).
Both ALLFILES.LST and BBSFILES.LST would contain the header and footer
information given at the top of the setup file. Files in C:\QUICK\SYSOP\
would not show up in either list because that area has a security level
of 100, higher than the maximum security specified in the two setups.
(A third setup for the sysop's use could include the level-100 files.)
I hope QLIST proves useful to you. I would consider releasing the Turbo
Pascal Ver. 4.0 source code to QBBS sysops on a case-by-case basis.
Feel free to contact me if you have any comments or suggestions about
the program:
Richard Lovett
6649 Oak
Kansas City, Mo. 64113
City Hall BBS (816-274-2603)
CompuServe ID: 75425,666
Send net-mail via Transient Technologies,
Fido-Net node 1:280/302
3/89
diately above will be a blank line)
N