home *** CD-ROM | disk | FTP | other *** search
/ Black Box 4 / BlackBox.cdr / bbs_ra / alst_170.arj / AL.DOC < prev    next >
Text File  |  1991-06-07  |  23KB  |  681 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.                                  AvaiList 1.70
  23.  
  24.                               Friday, June 7, 1991
  25.  
  26.  
  27.                                   USER MANUAL
  28.  
  29.  
  30.                    Copyright (c) 1988-1991 Andrew D. Farmer.
  31.                               All rights reserved.
  32.  
  33.  
  34.  
  35.                                License Statement
  36.  
  37.  
  38.           The AvaiList package is protected by both Canadian copyright 
  39.           law and international treaty provisions.
  40.  
  41.           AvaiList is provided as is, without warranty of any kind, 
  42.           either expressed or implied.  Andrew D. Farmer only 
  43.           guarantees that AvaiList will occupy disk space.
  44.  
  45.           In no event shall Andrew D. Farmer be liable to you or 
  46.           anyone else for any damages, including any lost profits, 
  47.           lost savings or other incidental or consequential damages 
  48.           arising out of the use or inability to use this program.
  49.  
  50.           All Andrew D. Farmer products are trademarks or registered 
  51.           trademarks of Andrew D. Farmer.
  52.  
  53.  
  54.           ------------------------------------------------------------
  55.  
  56.           Unregistered copies of AvaiList require you to manually
  57.           enter a numeric sequence before it will execute, but the
  58.           software is =not= crippled, nor does it quit working after
  59.           a period of time.  It is 100% fully fuctional as provided.
  60.  
  61.           The unregistered version is yours to keep. It is not public  
  62.           domain, shareware or freeware, it is simply free of charge. 
  63.  
  64.           You can use it as long as you do not use it within a
  65.           commercial environment.  It doesn't matter if you are
  66.           making money by using it or not, if you are using it within
  67.           commercial walls, you must register your copy.
  68.  
  69.           If you wish to register your copy of AvaiList, see the file
  70.           REGISTER.AL (which should have been contained in the same
  71.           archive as this file) for details.
  72.  
  73.           ------------------------------------------------------------
  74.  
  75.  
  76.                                    Chapter 1
  77.  
  78.                                     Preface
  79.  
  80.  
  81.      1.1  Archive
  82.  
  83.           The program archive, ALST_170.ARJ, should have included the
  84.           following files:
  85.  
  86.               AL.CFG        -  Sample configuration file.
  87.               AL.DOC        -  This user manual.
  88.               AL.EXE        -  The main program.
  89.               AL170.NEW     -  Release notes.
  90.               REGISTER.AL   -  Registration details.
  91.  
  92.  
  93.      1.2  System requirements
  94.  
  95.           Although it is possible to run AvaiList on a system with 
  96.           less than the following equipment, the following should be 
  97.           considered the realistic minimum with which you can get by:
  98.  
  99.               A 100% IBM BIOS compatible computer system with at least 
  100.               256K of available RAM.
  101.  
  102.               MS-DOS or PC-DOS version 3.10 or greater.
  103.  
  104.           Note that only approx 125K of AvaiList will remain in
  105.           memory when it spawns the archiver.
  106.  
  107.  
  108.  
  109.                                    Chapter 2
  110.  
  111.                                  Support Files
  112.  
  113.  
  114.      2.1  Header file, AL.HDR
  115.  
  116.           AvaiList will search for this file in the default
  117.           directory.  If found, the entire contents of the file will
  118.           be placed at the top of the master and newfile lists.
  119.  
  120.           You may select a different name (or directory) for the file
  121.           by using the HEADER configuration keyword or the -h command
  122.           line switch.
  123.  
  124.  
  125.      2.2  Extra info file, AL.EXI
  126.  
  127.           AvaiList will search for this file in the default
  128.           directory.  If found, the entire contents of the file will
  129.           be placed into the master and newfile lists between the
  130.           header information and the first area listing.
  131.  
  132.           This file can be extremely handy for listing such things as
  133.           magic file names or password restrictions.
  134.  
  135.           You may select a different name (or directory) for the file
  136.           by using the EXTRA configuration keyword or the -e command
  137.           line switch.
  138.  
  139.  
  140.      2.3  Directory descriptions, DIR.BBS
  141.  
  142.           This is the 'file of last resort' for area descriptions.
  143.           If AvaiList doesn't find the area's description anywhere
  144.           else, it will look for this file in the file area
  145.           directory.
  146.  
  147.           The first line of DIR.BBS is used as the description for
  148.           that block of area. If the DIR.BBS file is not found, then
  149.           the Drive:\Path is used as the description.
  150.  
  151.  
  152.  
  153.      2.4  File list, FILES.BBS
  154.   
  155.           AvaiList will search for this file in each of the specified
  156.           file area directories.  FILES.BBS is expected to list all
  157.           of the files that you wish placed into the master list.  If
  158.           a FILES.BBS file is not found in the directory, then a line
  159.           stating that no files were found in the area is placed into
  160.           the master list.
  161.  
  162.           You may change the name of the filelist by using the
  163.           LISTNAME configuration keyword.
  164.     
  165.           Each line of the files.bbs file is analyzed separately.  If
  166.           the character in column one (1) is a hyphen (-) or a space
  167.           ( ), and you have not used the NOCOMMENTS configuration
  168.           keyword, then the line is simply copied wholesale into the
  169.           master list.  Otherwise the 1st contiguous block of
  170.           characters is assumed to be the filename and the rest of
  171.           the line is assumed to be the description.  The lines will
  172.           be output to the Master List in the form:
  173.  
  174.               filename  size-in-bytes  file-date-stamp  description
  175.  
  176.           You can disable the listing of file-date-stamp by using the
  177.           NODATE configuration keyword.
  178.  
  179.           If the filename does not exist in the directory, then
  180.           STORED will appear in the size-in-bytes area and OFF-LINE
  181.           will appear in the file-date-stamp area.  If you use NODATE
  182.           to suppress the file-date-stamp, then non-existent files
  183.           will be listed with the word OFFLINE in the size-in-bytes
  184.           area.
  185.  
  186.           AvaiList supports the use of wildcards in files.bbs.  If
  187.           more than one file in the directory matches the filename
  188.           listed in files.bbs, then the master list will contain
  189.           separate entries, including file size and date stamp, for
  190.           each file matching the filespec.  The single description
  191.           will be used for all the matching entries.
  192.  
  193.  
  194.  
  195.                                    Chapter 3
  196.  
  197.                                  Configuration
  198.  
  199.  
  200.           The configuration file, AL.CFG by default, must be located
  201.           in the current directory when AvaiList is run.
  202.  
  203.           You  may select a different path, or filename, for your
  204.           configuration file by using the -c command line switch.
  205.  
  206.           Configuration commands are also outlined, with brief
  207.           descriptions, in the sample AL.CFG that should have been
  208.           contained in the same archive as this user manual.
  209.  
  210.  
  211.      3.1  Schedule tags
  212.  
  213.           A schedule tag is the word SCHED followed by a tag of up to
  214.           12 characters in length.  Any options enabled above the
  215.           first sched tag will be treated as global settings and
  216.           information under each sched tag will be local to that
  217.           schedule only.  There is no limit to the number of
  218.           schedules that can be present in one configuration file.
  219.  
  220.           A schedule is defined as everything under a schedule tag
  221.           until another SCHED line in found, or EOF is reached.  If
  222.           you do not have a schedule tag in your config file,
  223.           AvaiList will simply treat the entire configuration file as
  224.           one schedule.
  225.  
  226.           If you *do* specify Schedule(s) there are some rules:
  227.  
  228.               The SCHED keyword must begin in solumn 1 and there must
  229.               be one (and only one) space between the SCHED keyword
  230.               and the tag name.
  231.  
  232.               The LOGFILE and SYSOPNAME keywords must be in the
  233.               global area.
  234.  
  235.               The OUTFILE, NEWFILE, SYSTEM and AREA keywords must be
  236.               in a local schedule... they cannot be in the global
  237.               area.
  238.  
  239.               All other options may be in either global or local
  240.               areas.
  241.  
  242.               See entry on the -s command line switch, in chapter 4.
  243.  
  244.  
  245.  
  246.      3.2  Configuration statements, A to Z
  247.  
  248.           In the following list, [square brackets] indicate required
  249.           modifiers and <angle brackets> indicate optional modifiers.
  250.  
  251.  
  252.           ARCHIVE [archiver command line]
  253.     
  254.               This turns archive mode on, it will cause the finished
  255.               master list, and newfile list if selected, to be
  256.               archived into a file using the same trunk name as the
  257.               raw output list.
  258.  
  259.               You must provide the complete archiver command line
  260.               that AvaiList should pass to DOS.  Example: LHA A /MN.
  261.  
  262.  
  263.           AREA [path to file area] <description>
  264.  
  265.               This tells AvaiList what areas to scan to create the
  266.               master and newfile lists, it is required unless the
  267.               SYSTEM keyword is used.
  268.  
  269.               You may optionally specify the description of the area
  270.               after the path, this description will override any
  271.               description found in the DIR.BBS file.
  272.  
  273.               There may be up to 200 AREA statements specified.
  274.  
  275.  
  276.           BOXTYPE [#]
  277.  
  278.               Allows you to select what sort of box will be used in
  279.               the output lists.  Boxtype's 1 through 4 use IBM-PC
  280.               characters, therefore to disable the use of the IBM
  281.               extended character set you must use a boxtype of 0.
  282.               The default boxtype is 4.
  283.  
  284.               BoxTypes are:
  285.  
  286.                0    1    2    3    4        0 = Hatches (Non-IBM)
  287.               ---  ┌─┐  ╔═╗  ╓─╖  ╒═╕       1 = Single Rule
  288.                    │ │  ║ ║  ║ ║  │ │       2 = Double Rule
  289.               ---  └─┘  ╚═╝  ╙─╜  ╘═╛       3 = Single Top, Double Sides
  290.                                             4 = Double Top, Single Sides
  291.  
  292.  
  293.           CENTERTITLE
  294.  
  295.               This causes AvaiList to center the title of each area.
  296.               Centering entails expanding the 'box' to the entire
  297.               width of the list and centering the title within the
  298.               box.
  299.  
  300.  
  301.           EXTRA [filespec]
  302.    
  303.               Allows you to override the default extra info file
  304.               name, AL.EXI.
  305.  
  306.  
  307.           FLAGCHAR [char]
  308.  
  309.               Allows you to select what identification character to
  310.               use for flaging  NEW files.  Default action is to use
  311.               an asterix (*).
  312.  
  313.  
  314.           FLAGNEW <days>
  315.  
  316.               This keyword turns newfile flagging on, all files less
  317.               than 7 days old will have the FLAGCHAR placed beside
  318.               its entry in the master list.
  319.  
  320.               If you plan on using the NEWFILE keyword to create an
  321.               output list of new files, it should be noted that this
  322.               keyword is a pre-requisite for use of the NEWFILE
  323.               keyword.
  324.  
  325.               The optional modifier 'days' can be any number between
  326.               1 and 99.  This sets the maximum number of days old a
  327.               file can be and still get flagged as new.  As stated
  328.               above, the default value is 7 days.
  329.  
  330.  
  331.           HEADER [filespec]
  332.    
  333.               Allows you to override the default header file name,
  334.               AL.HDR.
  335.  
  336.  
  337.           KILLOFFLINE
  338.  
  339.               By default, any files that are listed in the files.bbs,
  340.               but do not reside in the directory are listed in the
  341.               list along with a comment that they are off-line.  If
  342.               this keyword is used, those 'missing' files will simply
  343.               be ignored (not placed into the list in any form).
  344.  
  345.  
  346.           LISTNAME [filespec]
  347.  
  348.               Allows you to override the default listname, FILES.BBS.
  349.  
  350.  
  351.           LOGFILE [filespec]
  352.  
  353.               Causes AvaiList to keep a LogFile of all activity, and
  354.               store it in the file specified by 'filespec'.
  355.  
  356.  
  357.           NEWFILE [filespec]
  358.  
  359.               When this keyword is used in conjunction with the
  360.               FLAGNEW keyword, it causes an output list of new files
  361.               to be created using the filename specified by
  362.               'filespec'.
  363.  
  364.  
  365.           NOCOMMENTS
  366.  
  367.               If this keyword is used, then all of the comments in
  368.               files.bbs will NOT be copied to the master list, but
  369.               instead will simply be ignored.
  370.  
  371.               Note that comments lines will NEVER be included in the
  372.               newfile list.
  373.  
  374.  
  375.           NODATE
  376.    
  377.               This keyword turns OFF the listing of the date for each
  378.               file.  If this keyword is not used, then the DOS date
  379.               for the file will automatically be placed into the
  380.               master and newfile lists.
  381.  
  382.  
  383.           NOSPACECHECK
  384.  
  385.               By default, AvaiList will refuse to run if there is
  386.               less than 250K free on the drive where the master list
  387.               is to be created.  This keyword will disable that disk
  388.               space check.
  389.  
  390.  
  391.           NOTOTAL
  392.  
  393.               Causes the total number of files and total bytes in
  394.               each area NOT to be reported at the end of that area's
  395.               listing in the master list.  Default action WILL report
  396.               these totals.
  397.    
  398.  
  399.           OUTFILE [filespec]
  400.  
  401.               This is the name of the file to use for generating the
  402.               master List.  This keyword is NOT optional -- it must
  403.               be provided for execution to occur.
  404.  
  405.  
  406.           SHOWORPHAN
  407.  
  408.               This causes orphaned files to be placed into the master
  409.               list and, if applicable, the newfile list.  An orphan
  410.               file is a file that resides in the directory, but is
  411.               not listed in the files.bbs file.
  412.  
  413.  
  414.           SYSOPNAME [Name]
  415.  
  416.               This is the name of the sysop of your system.  This
  417.               keyword is NOT optional - it must be provided for
  418.               execution to occur.
  419.  
  420.  
  421.           SYSTEM [type] [path] [priv]
  422.  
  423.               This calls upon AvaiList to use it's built-in support
  424.               for Opus 1.0x, Opus 1.1x, Maximus, RemoteAccess and
  425.               QuickBBS areas data files.  It will use the data file
  426.               to obtain file area paths and descriptions.
  427.  
  428.               'type' is OPUS103, OPUS110, MAX, RA or QUICK.
  429.  
  430.               'path' is the path/filename of the respective areas
  431.               data file.  If you specify MAX, RA or QUICK you must
  432.               provide the complete path and filename to the area data
  433.               file.  If you specify OPUS103 or OPUS110 you only
  434.               specify the path (no filename) to the SystemXX files.
  435.  
  436.               'priv' is the maximum privilege level that should be
  437.               included in the listings.  Only areas with this priv
  438.               level, or below, will be included.
  439.  
  440.               If you specify OPUS103, the maximum priv level is TWIT,
  441.               DISGRACE, NORMAL, PRIVIL, EXTRA, ASSTSYSOP or SYSOP.
  442.  
  443.               If you specify OPUS110 or MAX, the maximum priv level
  444.               is TWIT, DISGRACE, LIMITED, NORMAL, WORTHY, PRIVIL,
  445.               FAVORED, EXTRA, CLERK, ASSTSYSOP or SYSOP.
  446.  
  447.               If you specify RA or QUICK, the maximum priv level is a
  448.               numeric value in the range 0 to 32767.
  449.  
  450.               Examples:
  451.  
  452.                   SYSTEM  OPUS103  C:\Opus\                Extra
  453.                   SYSTEM  OPUS110  C:\Opus\                Worthy
  454.                   SYSTEM  MAX      C:\Max\Areas.Dat        Clerk
  455.                   SYSTEM  RA       C:\RA\Files.Ra          150
  456.                   SYSTEM  QUICK    C:\Quick\FLSearch.Ctl   65
  457.  
  458.               Note that any area that has an associated 'baricade'
  459.               file will be ignored.
  460.  
  461.               The use of the SYSTEM keyword will override any 'Area'
  462.               keywords.
  463.  
  464.  
  465.  
  466.           UUCP
  467.  
  468.               This causes AvaiList to use a Unix/UUCP style listing
  469.               format.  This is significantly different than the
  470.               standard format -- the path (in UNIX format) is shown
  471.               for each area, the BOXTYPE is forced to be 0,
  472.               NOCOMMENTS is forced to be true and filenames are shown
  473.               in lower case.
  474.  
  475.               There are other differences that will become obvious if
  476.               you try out the UUCP statement.
  477.  
  478.  
  479.           VERBOSE
  480.  
  481.               Causes a long 'Runtime Configuration' screen to be
  482.               presented to you when AvaiList is executed.
  483.  
  484.  
  485.           WRAPDESC <offset>
  486.  
  487.               By default AvaiList will truncate Files.Bbs
  488.               descriptions so that the entire line in the list is a
  489.               maximum of 79 characters in length.  Using this keyword
  490.               will cause long descriptions to be wrapped onto the
  491.               following line(s), and properly formated, instead.
  492.  
  493.               You may optionally specify an additive offset, in the
  494.               range 1 to 9, for the indent.  For instance, if you
  495.               specify an offset of 6, AvaiList will indent the 2nd
  496.               (3rd, etc) line(s) the number of characters nessesary
  497.               to match the 'description' portion of line 1 =PLUS= 6
  498.               characters (which is just coincidently the number that
  499.               was specified <grin>).
  500.  
  501.               This is quite useful if you have a download stats
  502.               reporter that inserts data into Files.Bbs -- for
  503.               example: If the program inserts "[  3] " (sans quotes)
  504.               at the begining of each Files.Bbs line, you would want
  505.               to use an additive offset of 6.
  506.  
  507.  
  508.  
  509.                                    Chapter 4
  510.  
  511.                                     AvaiList
  512.  
  513.  
  514.           The executable, AL.EXE, is ready to run once you have
  515.           completed your AL.CFG file.
  516.  
  517.  
  518.      4.1  Video mode
  519.  
  520.           Screen writes are made using calls to the undocumented BIOS
  521.           interrupt 29h.  Output in not redirectable.
  522.  
  523.           Note that interrupt 29h calls are DESQview 'friendly'.
  524.  
  525.  
  526.      4.2  Command line syntax
  527.  
  528.           AvaiList can be executed without any command line options,
  529.           but a number of specialized features are available from the
  530.           command line.
  531.           
  532.           Command line switches muse be preceded with either a dash
  533.           (-) or the DOS 'Switch Char', which is normally a slash (/).
  534.  
  535.  
  536.           Syntax/Usage:  AL <optional switches>
  537.  
  538.  
  539.           -?
  540.  
  541.               Display the syntax/usage screen, then abort with
  542.               nothing done.
  543.  
  544.           -Cconfigfile
  545.  
  546.               By default AvaiList will search for AL.CFG in the
  547.               default directory,  you may override this by specifying
  548.               a configuration file with this switch.
  549.  
  550.         
  551.           -Efilespec
  552.    
  553.               Allows you to override the default extra info file
  554.               name, AL.EXI.
  555.  
  556.  
  557.           -Hfilespec
  558.    
  559.               Allows you to override the default header file name,
  560.               AL.HDR.
  561.  
  562.  
  563.           -Llogfile
  564.  
  565.               Causes AvaiList to keep a log file of all activity, and
  566.               store it in the file specified by 'logfile'.
  567.  
  568.  
  569.           -Nfilespec
  570.  
  571.               When this switch is used, it will override the NEWFILE
  572.               from the configuration file.
  573.  
  574.  
  575.           -Ofilespec
  576.  
  577.               When this switch is used, it will override the OUTFILE
  578.               from the configuration file.
  579.  
  580.  
  581.           -Stag
  582.  
  583.               Tells AvaiList which schedule tag to execute.  If not
  584.               specified =all= tags will execute.
  585.  
  586.  
  587.           -V
  588.  
  589.               Causes a long 'Runtime Configuartion' screen to be
  590.               presented to you.
  591.  
  592.  
  593.      4.3  Errorlevels
  594.  
  595.           The following are the 3 possible errorlevels that AvaiList
  596.           can exit with:
  597.  
  598.           Errorlevel 2            Not enough disk space to proceed.
  599.                                   
  600.           Errorlevel 1            Fatal error - program abortion.
  601.  
  602.           Errorlevel 0            Successful completion.
  603.  
  604.  
  605.  
  606.                                    Appendix A
  607.  
  608.                                  Program Support
  609.  
  610.  
  611.           Technical support is only provided to individuals that have
  612.           registered AvaiList, but the author reserves the right to
  613.           make exceptions.
  614.  
  615.           If you have any questions, concerns or reports of unexpected 
  616.           behavior in the software, the author can be contacted in the 
  617.           following ways:
  618.  
  619.  
  620.           Electronic:
  621.  
  622.               FidoNet:     1:163/115 or 1:163/301
  623.  
  624.               Internet:    adf@aficom.ocunix.on.ca
  625.  
  626.               UUCP:        ...!aficom!adf
  627.  
  628.  
  629.           Surface:
  630.  
  631.               Andrew D. Farmer
  632.               P.O.Box 11087, Station H
  633.               Nepean, Ontario
  634.               K2H 7T8  CANADA
  635.  
  636.  
  637.  
  638.  
  639.                                    Appendix B
  640.  
  641.                            Thanks for all the fish...
  642.  
  643.  
  644.           I would like to take this opportunity to thank all the
  645.           people that helped to make AvaiList 1.70 what it is. They
  646.           tested the pants off it, they contributed many excellent
  647.           feature ideas and, above all, they are a great bunch of
  648.           people who deserve extra credit for putting up with my
  649.           attitude.  <grin>
  650.  
  651.           I present my Beta Testers (alphabetically):
  652.  
  653.           Bruce Bodger, Scott Dudley, Tom Hall, Jesse Hollington, 
  654.           Dave Hunter, George Peace, John Souvestre, Ken Wilson.
  655.  
  656.           Special thanks to Joaquim Homrighausen for providing a fair
  657.           amount of the wording used in the license statement.
  658.  
  659.  
  660.  
  661.                                 Closing comments    
  662.  
  663.  
  664.           I have tried to make this documentation as complete as 
  665.           possible, but there are always some small things that slip 
  666.           through the cracks and aren't documented, or aren't 
  667.           documented correctly.  I apologize in advance for any such 
  668.           errors that may occur.
  669.    
  670.           I hope that you enjoy using AvaiList and that it provides 
  671.           you with the features you need.
  672.  
  673.           AvaiList is still very much 'in development' and I am
  674.           always open to feature suggestions, so please feel free to
  675.           let me know if you have some ideas that would make AvaiList
  676.           even better.
  677.  
  678.           Andrew D. Farmer
  679.           Ottawa, Ontario
  680.           June 7, 1991
  681.