Simtel MSDOS 1992 June/SIMTEL_0692.cdr/msdos/bbs/qlist2.arc/QLIST.DOC

Text File | 1989-03-03 | 18KB | 389 lines

                              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    [phone]
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