home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Professional / OS2PRO194.ISO / os2 / com / bbs / downsrt / downsort.doc < prev    next >
Text File  |  1991-06-16  |  105KB  |  2,746 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.                                                                       DOWNSORT
  19.                Maximus CBCS DOWNload file SORT and List Utility (OS/2 and DOS)
  20.                                                                    Version 5.1
  21.  
  22.  
  23.  
  24.  
  25.                                                                  June 16, 1991
  26.  
  27.  
  28.                                                                  Rob Hamerling
  29.  
  30.                                                        Vianen, The Netherlands
  31.                                                 Phone: ++31-3473-72136 (voice)
  32.                                                         FIDO-net: 2:512/4.1098
  33.  
  34.                     Maximus Download File Sort and List Utility (OS/2 and DOS)
  35.  
  36.  
  37.  
  38.   Maximus Download File Sort and List Utility (OS/2 and DOS)
  39.  
  40.  
  41.  
  42.   CONTENTS
  43.  
  44.  
  45.     About DOWNSORT  . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
  46.     Registration and Shareware Fee  . . . . . . . . . . . . . . . . . . . . 1
  47.     Warranty  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
  48.     Acknowledgements  . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
  49.  
  50.     What DOWNSORT can do for you  . . . . . . . . . . . . . . . . . . . . . 3
  51.     Purpose and Objectives  . . . . . . . . . . . . . . . . . . . . . . . . 3
  52.     Functional Description  . . . . . . . . . . . . . . . . . . . . . . . . 3
  53.       File-dates and HPFS   . . . . . . . . . . . . . . . . . . . . . . . . 3
  54.     File reports (list types)   . . . . . . . . . . . . . . . . . . . . . . 4
  55.       ORPHAN report   . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
  56.       BBS-list  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
  57.       NEW-list  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
  58.       ALL-list  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
  59.       IPF-list  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
  60.       GBL-list  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
  61.       FILES.BBS   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
  62.     General notes about the lists   . . . . . . . . . . . . . . . . . . . . 6
  63.  
  64.     How to use DOWNSORT   . . . . . . . . . . . . . . . . . . . . . . . . . 8
  65.     Installation  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
  66.     Commandline parameters  . . . . . . . . . . . . . . . . . . . . . . . . 8
  67.     Configuration file   . . . . . . . . . . . . . . . . . . . . . . . . . 13
  68.       Parameters with global scope   . . . . . . . . . . . . . . . . . . . 13
  69.       Parameters with local scope  . . . . . . . . . . . . . . . . . . . . 13
  70.     Usability hints  . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
  71.       Specification of AREA.DAT  . . . . . . . . . . . . . . . . . . . . . 14
  72.       Location of FILES.BBS  . . . . . . . . . . . . . . . . . . . . . . . 15
  73.       Privilege control  . . . . . . . . . . . . . . . . . . . . . . . . . 15
  74.       Orphan report  . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
  75.       Duplicates   . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
  76.   |   Headers, Titles and Include files  . . . . . . . . . . . . . . . . . 16
  77.       Privileges with File Request   . . . . . . . . . . . . . . . . . . . 17
  78.     Sample specifications and usage  . . . . . . . . . . . . . . . . . . . 17
  79.       DOWNSORT specification sample  . . . . . . . . . . . . . . . . . . . 17
  80.       BinkleyTerm specification sample   . . . . . . . . . . . . . . . . . 18
  81.     Dependencies and restrictions  . . . . . . . . . . . . . . . . . . . . 19
  82.     Wishlist   . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
  83.     Known Problems   . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
  84.  
  85.     Packaging  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
  86.     RUN-time material  . . . . . . . . . . . . . . . . . . . . . . . . . . 21
  87.     Source material  . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
  88.     Availability   . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
  89.  
  90.     Internals  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
  91.     Development Environment  . . . . . . . . . . . . . . . . . . . . . . . 23
  92.     Program Organisation   . . . . . . . . . . . . . . . . . . . . . . . . 23
  93.     Main Data Organisation   . . . . . . . . . . . . . . . . . . . . . . . 25
  94.     Storage and Performance  . . . . . . . . . . . . . . . . . . . . . . . 27
  95.  
  96.     Appendix A.  History of changes  . . . . . . . . . . . . . . . . . . . 29
  97.  
  98.  
  99.                                                                   Contents  ii
  100.  
  101.   Maximus Download File Sort and List Utility (OS/2 and DOS)
  102.  
  103.  
  104.  
  105.   | Version 5.1  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
  106.     Version 5.0  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
  107.     Version 4.9  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
  108.     Version 4.8  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
  109.     Version 4.7  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
  110.     Version 4.6  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
  111.     Version 4.5  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
  112.     Version 4.4  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
  113.     Version 4.3  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
  114.     Version 4.2  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
  115.     Version 4.1  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
  116.     Version 4.0  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
  117.  
  118.     Appendix B.  Who use DOWNSORT?   . . . . . . . . . . . . . . . . . . . 35
  119.  
  120.     Appendix C.  Sample Configuration File   . . . . . . . . . . . . . . . 36
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139.  
  140.  
  141.  
  142.  
  143.  
  144.  
  145.  
  146.  
  147.  
  148.  
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.                                                                  Contents  iii
  163.  
  164.   Maximus Download File Sort and List Utility (OS/2 and DOS)
  165.  
  166.  
  167.  
  168.   ABOUT DOWNSORT
  169.  
  170.   DOWNSORT was started a few years ago as a program for my own use when I was
  171.   SYSOP of the Bulletin Board PC-Square, to get overviews of my download
  172.   material for the users.  The program name is related to the SORTing of the
  173.   collection of DOWNloadable files, in DOWNward time-stamp sequence and a
  174.   Bulletin was the only list that was produced at that time.  Also PC-Square
  175.   was running BinkleyTerm and OPUS under DOS, and file-requesting was not so
  176.   popular then.
  177.  
  178.   Now PC-Square runs with OS/2, BinkleyTerm and MAXIMUS CBCS, and I'm not the
  179.   SYSOP anymore but still strongly involved.  As a contribution to PC-Square
  180.   and the large international Bulletin Board community of MAXIMUS CBCS
  181.   boards, I decided to upgrade my DOWNSORT program to the current software.
  182.   But at the same time a lot of improvements and extensions have been made:
  183.   many user-configurable options for many more output formats then the
  184. | original DOWNSORT.
  185.  
  186. | The only dependency of DOWNSORT on MAXIMUS CBCS is a parameter-file
  187. | AREA.DAT, which is usually created with a MAXIMUS utility (SILT(P)), which
  188. | itself can be used without actually running MAXIMUS!  This is the way I
  189. | work for testing DOWNSORT.
  190.  
  191.   "Appendix A.  History of changes" on page 29 gives an impression of the
  192.   history.
  193.  
  194.   DOWNSORT is now developed in an OS/2 environment, but it is distributed as
  195.   'family'-application: it runs under OS/2 and DOS.
  196.  
  197.  
  198.   REGISTRATION AND SHAREWARE FEE
  199.  
  200.   DOWNSORT is a $ 0.00 Shareware Program.  This means (to me) that you
  201.   respect the commonly known rules for shareware, but you don't have to pay
  202.   me anything.
  203.  
  204.   Registration is voluntary: please send me a netmail message with your name
  205.   and (net-)address if you are a regular user of DOWNSORT as SYSOP.  That
  206.   gives me an impression of the usage and the impact of changes to DOWNSORT.
  207.  
  208.   If you tell me that you are running DOWNSORT on your Bulletin Board as
  209.   service to your users, I'll add your name to the reference list in
  210.   "Appendix B.  Who use DOWNSORT?" on page 35 (if you like).
  211.  
  212.  
  213.   WARRANTY
  214.  
  215.   For this price?  You must be kidding!  But I'll listen to your complaints
  216.   and suggestions, and if time permits, I'll work on the improvements you
  217.   suggest.
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.                                                              About DOWNSORT  1
  226.  
  227.   Maximus Download File Sort and List Utility (OS/2 and DOS)
  228.  
  229.  
  230.  
  231.   ACKNOWLEDGEMENTS
  232.  
  233.   I would like to thank all users that contributed with constructive remarks
  234.   and encouraging appraisals.  Without doubt Emmanuel Sandorfi of 2:320/5
  235.   holds the record in number of suggestions and amount of additionally
  236.   required programming effort.  He also provided some additional title-fonts
  237.   (2 and 3).
  238.  
  239.   I also would like to thank the regular users (SYSOP's of Bulletin Boards)
  240.   who made DOWNSORT much more popular than I ever dreamed of!  A collection
  241.   of geographically dispersed Boards can be found in "Appendix B.  Who use
  242.   DOWNSORT?" on page 35.
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.  
  272.  
  273.  
  274.  
  275.  
  276.  
  277.  
  278.  
  279.  
  280.  
  281.  
  282.  
  283.  
  284.  
  285.  
  286.  
  287.  
  288.                                                              About DOWNSORT  2
  289.  
  290.   Maximus Download File Sort and List Utility (OS/2 and DOS)
  291.  
  292.  
  293.  
  294.   WHAT DOWNSORT CAN DO FOR YOU
  295.  
  296.   DOWNSORT is a utility to make overviews of available download files for
  297.   Bulletin Board Systems (usually running MAXIMUS CBCS).  The overviews
  298.   differ in sort sequence, purpose of use and size.
  299.  
  300.   A report is produced for files that could not be listed for any reason.
  301.  
  302.  
  303.   PURPOSE AND OBJECTIVES
  304.  
  305.   DOWNSORT is designed for the following purposes:
  306.  
  307.   1. Produce different overviews of files which are available for download by
  308.      users of the Bulletin Board and by File Requestors.  QUICK and EASY
  309.      retrieval is the main goal for the lists.  Therefore many lists-types
  310.      and within a type several variations should be available: versatility
  311.      for SYSOP and users.
  312.  
  313.   2. Report files which are not listed in FILES.BBS, or which privilege
  314.      (individual or its area) prevents it from being reported.  This might be
  315.      caused by several circumstances:
  316.      ■  a file belongs to a collection (area) with a higher privilege than
  317.         the selected report privilege (typically the upload area, but also
  318.         restricted collections for selected users).
  319.      ■  a file appears in FILES.BBS after a ^Px-sequence that specifies a
  320.         higher privilege than the selected report privilege (newly uploaded
  321.         files in a combined up- and download directory).
  322.      ■  an typing-error has been made in the filename.ext in FILES.BBS or a
  323.         file has been renamed without updating FILES.BBS.
  324.      ■  a file is not listed in FILES.BBS on purpose by SYSOP, to prevent it
  325.         being downloaded other than by CO-SYSOP.
  326.  
  327.   3. Must be able to run unattended (typically overnight).
  328.  
  329.   4. Should not disclose files to users (file-requesters) without positive
  330.      agreement by SYSOP.
  331.  
  332.  
  333.  
  334.   FUNCTIONAL DESCRIPTION
  335.  
  336.   The program DOWNSORT may create several types of outputfiles.
  337.  
  338.  
  339.   FILE-DATES AND HPFS
  340.  
  341.   One of the function of DOWNSORT is sorting on file date.  Since the
  342.   introduction of HPFS in OS/2 version 1.2, there is not one single file-date
  343.   anymore!  A file on an HPFS volume has different values for:
  344.  
  345.   ■  Creation date
  346.   ■  LastAccess date
  347.   ■  LastWrite date
  348.  
  349.  
  350.  
  351.                                                What DOWNSORT can do for you  3
  352.  
  353.   Maximus Download File Sort and List Utility (OS/2 and DOS)
  354.  
  355.  
  356.  
  357.   The date you see normally in DIR-listings is the LastWrite date.  Most
  358.   SYSOPs will have noticed that ZMODEM uploads and file-attaches give
  359.   file-dates corresponding to the (LastWrite-) date of the sending system.
  360.   And most utilities handle only this 'single' date.  That means that 'old'
  361.   (ZMODEM-) uploaded files are generally not on top of the acquisition lists.
  362.  
  363.   But HPFS stores the date of arrival on your system (Creation) as well.
  364.   DOWNSORT handles this Creation date since version 4.7, although the lists
  365.   (see below) contain the 'old fashioned' LastWrite date.  This has the
  366.   following consequences:
  367.  
  368.   ■  A new acquisition is on top of lists (if that list is sorted on date),
  369.      and are marked in the lists as new (flag for an 'age' of a week or a
  370.      month).
  371.   ■  The listed file-date is the 'ordinary' date.  So users can judge for
  372.      themselves if the file is 'new' for them as well.
  373.  
  374.   Note: The LastAccess date is not very relevant for the purposes of
  375.   DOWNSORT, although SYSOP may see when it was last downloaded.
  376.  
  377.  
  378.   FILE REPORTS (LIST TYPES)
  379.  
  380.   DOWNSORT can produce several types of output reports, mostly indicated by
  381.   type of list.  Below follows for each type of list e general description.
  382.  
  383.  
  384.   ORPHAN REPORT
  385.  
  386.   This is a list of all files in download directories for which there is no
  387.   entry in the corresponding FILES.BBS file.  The report contains date,
  388.   area-name and area-path of the orphan.  The entries are sorted on area and
  389.   filename.  Not reported are MAXIMUS system files like: FILES.?BS, *.BAK,
  390.   DIR.?BS and SYSTEM*.?BS.
  391.  
  392.   Note: If there is an entry for a file in FILES.BBS without a description,
  393.   the file is NOT considered to be an Orphan!
  394.  
  395.  
  396.   BBS-LIST
  397.  
  398.   This is a list of downloadfiles that came recently available
  399.   (DOWNSORT.BBS).  The list may be sorted on date (newest first) or on
  400.   filename.  It contains compiled MECCA control sequences, for direct use in
  401.   MAXIMUS bulletins: a user-privilege sensitive list!  It might be a good
  402.   idea to put a translated [onexit] string, which translates to [^OFpath]
  403.   (without the brackets!).  When a user exits from the BBS-list bulletin, it
  404.   will fall back to the exit-bulletin.
  405.  
  406.   The length of the file (number of file-entries) may be limited by
  407.   parameters:
  408.  
  409.   ■  file-count
  410.   ■  maximum privilege
  411.  
  412.  
  413.  
  414.                                                What DOWNSORT can do for you  4
  415.  
  416.   Maximus Download File Sort and List Utility (OS/2 and DOS)
  417.  
  418.  
  419.  
  420.   (never more than available within the privilege limit).  If neither
  421.   specified it will contain all available files in all download directories.
  422.  
  423.   To make it a complete MAXIMUS bulletin-file a user-provided header is
  424.   included preceding the list and a trailer at the end of the list.  Header
  425.   and trailer can be built by SYSOP, and may contain any information and
  426.   bulletin-control sequences (a sample is provided).
  427.  
  428.  
  429.   NEW-LIST
  430.  
  431.   Basically the same list as above, but in simple ASCII format and without
  432.   inclusion of header and trailer files.
  433.  
  434.   This list is suitable for file-requestors as brief overview of the latest
  435.   additions, updates or replacements.
  436.  
  437.  
  438.   ALL-LIST
  439.  
  440.   A list of all downloadfiles by area in alphabetical sequence (per area) on
  441.   filename.  Files of the same area are listed in groups, separated by
  442.   imbedded headers with area-name, -description, and -privilege.  Actual
  443.   status information is provided in the area-header as well: area-filecount
  444.   and -bytecount, and latest acquisition (date and file-name).
  445.  
  446.   At the end a SUMMARY report shows per area the area-title, file-count and
  447.   byte-count, and totals.
  448.  
  449.   This list may be limited by the privilege parameter, but is not affected by
  450.   the specification of filecount-limit.  The numbers in area-header and
  451.   summary report show only what is available for the particular privilege.
  452.  
  453.  
  454.   IPF-LIST
  455.  
  456.   Same contents, but different format of ALL-list, only useful for OS/2 users
  457.   (OS/2 version 1.2+ under Presentation Manager).  This file has the format
  458.   of an input-file for the Information Presentation Facility Compiler (IPFC).
  459.  
  460.  
  461.   GBL-LIST
  462.  
  463.   Similar to ALL-list, but where ALL-list gives the files in groups per area,
  464.   the GBL-list ignores area-boundaries and gives a single group, sorted on
  465.   filename.  For each file the area is mentioned.  There is no area-summary.
  466.  
  467.   SYSOP may choose which of both is suitable to make available to users, and
  468.   which to use for himself (or even both).  The GBL-list is especially useful
  469.   to check on duplicates over area's.  The GBL-list is not limited by the
  470.   filecount parameter.
  471.  
  472.  
  473.  
  474.  
  475.  
  476.  
  477.                                                What DOWNSORT can do for you  5
  478.  
  479.   Maximus Download File Sort and List Utility (OS/2 and DOS)
  480.  
  481.  
  482.  
  483.   FILES.BBS
  484.  
  485.   A new "FILES.BBS" type of file may be (re-)created for every area.  The
  486.   contents of the file-information will be about the same as the original
  487.   FILES.BBS, but with the following notes:
  488.  
  489.   ■  A header is generated with area-name, -title, and -privilege.  Also the
  490.      total amount of files and bytes and the most recently acquired new file
  491.      in this area is part of the header information.
  492.   ■  The entries are sorted on filename for all files with a privilege up to
  493.      and including the area-privilege.
  494.   ■  Files can have a privilege other than the area-privilege when the
  495.      original FILES.BBS file does contain ^Pp-sequences ('p' being a
  496.      privilege letter).  This construction will be rebuilt by DOWNSORT.
  497.      Files with a higher privilege than the area-privilege will follow after
  498.      a compiled MECCA-sequence (^Pp) in the new FILES.BBS.  DOWNSORT respects
  499.      these indicators when reading FILES.BBS, so all file-privilege
  500.      information is retained.  This ensures no accidental loss of
  501.      file-information, and the regular user won't see more than he should.
  502.   ■  Wild-card specifications are not propagated to the new FILES.BBS.
  503.   ■  The file description is kept internally as a single string of maximum
  504.      240 characters.  When creating FILES.BBS files, this will be the file
  505.      format (single record per file-entry).  The original FILES.BBS may
  506.      contain a (long) single string description, or multiple (short)
  507.      multiline descriptions.  When encountering multiline descriptions in
  508.      input-FILES.BBS, DOWNSORT concatenates the separate description lines
  509.      with a single intermediate space up to a maximum of 240 bytes.  This
  510. |    will be the output format if the FIL-list is requested.
  511. | ■  All comments and alignments you may have worked on for many hours is
  512. |    discarded!
  513.  
  514.   See for naming conventions and placements "Commandline parameters" on page
  515.   8.
  516.  
  517.  
  518.   GENERAL NOTES ABOUT THE LISTS
  519.  
  520.   1. Dates are marked with a 'new'-indicator: a '*' if the file is only since
  521.      a week on this system, and a '+' if it is since a month.  Filedates
  522.      later than the current system date are marked '-' (negative age).
  523.  
  524.   2. In every outputfile the filename, MAXIMUS-area name, file-size and
  525.      -date, and file-description from FILES.BBS is listed.  A report-line
  526.      will never display more than 79 characters.
  527.  
  528.      The file-description will be multi-line in ALL-, IPF- and GBL-list if it
  529.      is longer than would fit on the standard 79-position line, a
  530.      word-wrapping technique is used for readability (line-split on word
  531.      boundary).  The description is truncated at end of line in BBS-list and
  532.      NEW-list.
  533.  
  534.      The -T option will force truncation of the description in all reports,
  535.      the -W option will allow multi-line descriptions in all reports.
  536.  
  537.  
  538.  
  539.  
  540.                                                What DOWNSORT can do for you  6
  541.  
  542.   Maximus Download File Sort and List Utility (OS/2 and DOS)
  543.  
  544.  
  545.  
  546.      If a filename is found in FILES.BBS, but no accompanying description, a
  547.      "--- no description available ---" will be put in place.  A replacing
  548.      text may be specified with DOWNSORT.CFG.
  549.  
  550.      Files for which there is no entry in the FILES.BBS (Orphans) are treated
  551.      as Hidden files, which are only listed in the reports if the Hidden
  552.      privilege is specified.  For a way to override this see: "Orphan report"
  553. |    on page 15.
  554.  
  555. |    Note: If you want the orphans to appear in FILES.BBS (or in any other
  556. |    report), you MUST also request an ORP-list!
  557.  
  558.   3. The BBS-list contains MAXIMUS authorisation controls (^PLp-sequences),
  559.      corresponding to the privilege of the area or the individual file.  So
  560.      it is not necessary to make different files for different categories of
  561.      MAXIMUS users, even with the default privilege-limit SYSOP a user will
  562.      not see the files he/she is not supposed to know about.
  563.  
  564.      NEW- and ALL-lists do not contain any privilege information, the files
  565.      (or complete area's) above the specified privilege are simply not
  566.      listed, however multiple lists can be produced for different categories
  567.      of users (based on privilege).
  568.  
  569.  
  570.  
  571.  
  572.  
  573.  
  574.  
  575.  
  576.  
  577.  
  578.  
  579.  
  580.  
  581.  
  582.  
  583.  
  584.  
  585.  
  586.  
  587.  
  588.  
  589.  
  590.  
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.  
  601.  
  602.  
  603.                                                What DOWNSORT can do for you  7
  604.  
  605.   Maximus Download File Sort and List Utility (OS/2 and DOS)
  606.  
  607.  
  608.  
  609.   HOW TO USE DOWNSORT
  610.  
  611.   This chapter tells you how to install DOWNSORT, how to customise the
  612.   configuration file and what you might specify on the commandline.
  613.  
  614.   A sample configuration file (in "Appendix C.  Sample Configuration File" on
  615.   page 36) is part of the package.  It contains a lot of comments (in Binkley
  616.   and MAXIMUS  style) to help you with the changes.
  617.  
  618.  
  619.   INSTALLATION
  620.  
  621.   With the following directions you should be able to setup and run DOWNSORT
  622.   after very short time.
  623.  
  624.   1. Make a separate directory for DOWNSORT, and make it the current default
  625.      directory every time you run DOWNSORT.  The separate directory is a
  626.      recommendation, not a requirement!
  627.  
  628.   2. Copy the files DOWNSORT.EXE and DOWNSORT.CFG from the DOWNSORT package
  629.      into this directory.
  630.  
  631.   3. Modify (edit) the file DOWNSORT.CFG to specify your environment and list
  632.      requirements.  The sample file contains comments to help you with this
  633.      process.  Most specifications are obvious.  AreaDat is the most
  634.      important parameter: DOWNSORT won't do anything useful if it cannot find
  635.      this MAXIMUS file.  See "Appendix C.  Sample Configuration File" on page
  636.      36 for a printed sample.
  637.  
  638.   4. You may give DOWNSORT a first shot by just using its name on the
  639.      commandline, with the parameter -H.  This will show a brief HELP-screen
  640.      with the possible commandline parameter specifications.
  641.  
  642.   5. All reports will be created in the DOWNSORT directory (unless you
  643.      specified 'fpath' for the FILES.BBS output).  Browse the lists to see if
  644.      you like the contents and titles, and modify the CFG-file to your
  645.      convenience.
  646.  
  647.  
  648.  
  649.   COMMANDLINE PARAMETERS
  650.  
  651.   This paragraph deals only with the commandline parameters!
  652.  
  653.   NOTE: Parameters from DOWNSORT.CFG are processed first, commandline
  654.   parameters may complete and (partly) override those in the configuration
  655.   file.
  656.  
  657.   For how to read the command syntax diagram see OS/2 reference manual.
  658.  
  659.  
  660.  
  661.  
  662.  
  663.  
  664.  
  665.  
  666.                                                         How to use DOWNSORT  8
  667.  
  668.   Maximus Download File Sort and List Utility (OS/2 and DOS)
  669.  
  670.  
  671.  
  672.                                         ┌────────────────────────┐
  673.                                         v                        │
  674.    ──┬─────────┬─┬────────┬─ DOWNSORT ────┬────────────────────┬─┴─────┤
  675.      └─ drive ─┘ └─ path ─┘               ├─ @filespec ────────┤
  676.                                           ├─ BBS ─┬──────┬─────┤
  677.                                           │       └─ :p ─┘     │
  678.                                           ├─ NEW ─┬───────┬────┤
  679.                                           │       └─ :pp ─┘    │
  680.                                           ├─ ALL ─┬───────┬────┤
  681.                                           │       └─ :pp ─┘    │
  682.                                           ├─ IPF ─┬───────┬────┤
  683.                                           │       └─ :pp ─┘    │
  684.                                           ├─ GBL ─┬───────┬────┤
  685.                                           │       └─ :pp ─┘    │
  686.                                           ├─ ORP ──────────────┤
  687.                                           ├─ FIL ─┬──────────┬─┤
  688.                                           │       └─ :fpath ─┘ │
  689.                                           ├─ nnn ──────────────┤
  690.                                           ├──┬─ /T ─┬──────────┤
  691.                                           │  └─ /W ─┘          │
  692.                                           ├──┬─ /A ─┬──────────┤
  693.                                           │  ├─ /D ─┤          │
  694.                                           │  └─ /K ─┘          │
  695.                                           ├──┬─ /H ─┬──────────┤
  696.                                           │  ├─ /Q ─┤          │
  697.                                           │  └─ /V ─┘          │
  698.                                           └──── /X ────────────┘
  699.  
  700.   @filespec   The character '@' followed by a complete file specification of
  701.               the DOWNSORT configuration file (see "Configuration file" on
  702.               page 13 for details).  This file will be used to specify
  703.               processing parameters.  If the file cannot be read, only the
  704.               commandline parameters are used.
  705.  
  706.               NOTE: The use of a configuration file is mandatory when the
  707.               file AREA.DAT is not in the default directory when running
  708.               DOWNSORT.
  709.  
  710.               Default: DOWNSORT.CFG in current default directory.
  711.   BBS         Create the BBS-list: DOWNSORT.BBS.
  712.  
  713.               Default: DOWNSORT.BBS will not be created.
  714.   NEW         Create NEW-list(s): DOWNSORT.N~p, where 'p' is the appropriate
  715.               privilege class (see below).
  716.  
  717.               Default: DOWNSORT.N~p will not be created.
  718.   ALL         Create ALL-list(s): DOWNSORT.A~p, where 'p' is the appropriate
  719.               privilege class (see below).
  720.  
  721.               nnn-limit does not apply to ALL-list.
  722.  
  723.               Default: DOWNSORT.A~p will not be created.
  724.   IPF         Create IPF-list(s): DOWNSORT.I~p, where 'p' is the appropriate
  725.               privilege class (see below).
  726.  
  727.  
  728.  
  729.                                                         How to use DOWNSORT  9
  730.  
  731.   Maximus Download File Sort and List Utility (OS/2 and DOS)
  732.  
  733.  
  734.  
  735.               nnn-limit does not apply to IPF-list.
  736.  
  737.               Default: DOWNSORT.I~p will not be created.
  738.   GBL         Create GBL-list(s): DOWNSORT.G~p, where 'p' is the appropriate
  739.               privilege class (see below).
  740.  
  741.               nnn-limit does not apply to GBL-list.
  742.  
  743.               Default: DOWNSORT.G~p will not be created.
  744. | ORP         Create ORP-list: DOWNSORT.ORP (orphan report, if any orphans).
  745.  
  746. |             If an orphan report is not requested, no other report will
  747. |             contain any orphan information, even when 'Hidden' is specified
  748. |             as reporting level.
  749.  
  750.               Default: DOWNSORT.ORP will not be created.
  751.   FIL         Create FILES.BBS type of files for each area.
  752.  
  753.               The specification does not apply to FILES.BBS, a
  754.               privilege-limit cannot be specified and defaults to SYSOP.
  755.               Another privilege limit can be specified however by means of
  756.               the configuration file.
  757.  
  758.               For each individual area the following convention will be used
  759.               for the name and place of the FILES.BBS list (in this
  760.               sequence):
  761.               1. If the "FIL:" parameter specifies a directory-path, then for
  762.                  each area the output file "FILES.ac" is put in the specified
  763.                  directory ('ac' is 1 or 2 char area-code).  Previous files
  764.                  with the same name will be discarded.
  765.               2. If "ListFile" is specified in AREA.CTL, then that name and
  766.                  path will be used.
  767.               3. Otherwise the file FILES.BBS: will be put in the directory
  768.                  with the download files.
  769.  
  770.               For situations 2 and 3 existing files will be renamed to .BAK
  771.               (older .BAK files will be discarded).
  772.  
  773.               Default: FILES.BBS-type of files will not be generated.
  774.   fpath       Optional directory path specification for FILES.BBS-output.
  775.               See the "FIL:" parameter for usage.
  776.  
  777.               Default: none
  778.   nnn         Maximum number of files to be reported in the BBS- and
  779.               NEW-list(s).  A maximum value of 32767 can be specified, it
  780.               does not apply to ALL-, IPF- and GBL-list.
  781.  
  782.               Default: all files up to and including the (specified or
  783.               default) privilege class will be listed for all types of lists.
  784.   p           Single privilege character.
  785.  
  786.               Lists only download files with a privilege of up to and
  787.               including privilege 'p'.  The indicator must be the first
  788.               character of an existing MAXIMUS privilege level (T, D, L, N,
  789.               W, P, F, E, C, A, S, H).  No error-message is given for an
  790.  
  791.  
  792.                                                        How to use DOWNSORT  10
  793.  
  794.   Maximus Download File Sort and List Utility (OS/2 and DOS)
  795.  
  796.  
  797.  
  798.               invalid privilege character, there will simply be no file-list
  799.               for an invalid character!
  800.  
  801.               For the BBS-list only a single privilege character is allowed,
  802.               the listfile is always called: DOWNSORT.BBS.
  803.  
  804.               Default: S  (SYSOP):  files of all privilege levels will be
  805.               listed, except HIDDEN files (with real Hidden privilege or
  806.               files for which no entry could be found in FILES.BBS).
  807.   pp          Multiple privilege characters (minumum 0, maximum 10).
  808.  
  809.               Make for every valid specified privilege level a download-list
  810.               with files of a privilege of up to and including privilege 'p'.
  811.               The indicator must be the first character of an existing
  812.               MAXIMUS privilege level.  No error-message is given for an
  813.               invalid privilege character, there will simply be no file-list
  814.               for an invalid character!
  815.  
  816.               Applies to ALL-, IPF- and NEW-lists, these are called
  817.               DOWNSORT.A~p and DOWNSORT.N~p respectively, were 'p' represents
  818.               the applicable privilege character.
  819.  
  820.               Default: S  (SYSOP):  files of all privilege levels will be
  821.               listed, except HIDDEN files (with real Hidden privilege or
  822.               files for which no entry could be found in FILES.BBS).
  823.   /T /W       Action to be taken if the file description would cause the
  824.               reportline to exceed 79 characters:
  825.               ■  T - truncate the description
  826.               ■  W - wrap the description and provide as many reportlines as
  827.                  needed to show the complete description.
  828.  
  829.               Default: -T for NEW-list and BBS-list, -W for ALL-, IPF- and
  830.               GBL-list.
  831.   /A /D /K    Sort method for BBS-list and NEW-list.
  832.               ■  A - Sort the files alphabetically on filename.
  833.               ■  D - Sort the files on reversed date sequence (newest file on
  834.                  top of list).
  835.               ■  K - keep lines in sequence of FILES.BBS.
  836.  
  837.               When the -A option is selected, an additional header-line will
  838.               appear in the BBS-list and NEW-list, indicating the latest
  839.               acquisition.  This line is not needed when these lists are
  840.               sorted on date, since the the latest acquisition will be on top
  841.               of the list!
  842.  
  843.               The -K option is only useful in situations where the files are
  844.               primarily grouped on AREA, i.c. ALL-, IPF- and FIL-list.
  845.  
  846.               Default: -D
  847.   /H /Q /V    Operating mode
  848.               ■  H - help:  display screen with essential information about
  849.                  running DOWNSORT, such as the command syntax.  In that case
  850.                  the program will not undertake any other action.
  851.               ■  Q - quiet:  display only start and finish-message, and error
  852.                  messages which prevent the program from proceeding normally.
  853.  
  854.  
  855.                                                        How to use DOWNSORT  11
  856.  
  857.   Maximus Download File Sort and List Utility (OS/2 and DOS)
  858.  
  859.  
  860.  
  861.               ■  V - verbose:  display a lot of progress messages.
  862.               If neither -Q nor -V is specified, than the number of console
  863.               messages will be 'intermediate': more than -Q, but less than
  864.               -V.
  865.  
  866.               Default: none
  867.   /X          Exclude Privilege Indications
  868.               ■  X - exclude privilege indications in all list-types.  Some
  869.                  SYSOPs want to hide any kind of privilege-system for users
  870.                  and file-requesters of their Bulletin Board System.  With
  871.                  the -X option specified all privilege indications will be
  872.                  suppressed.
  873.  
  874.                  Note: This does not apply to the compiled MECCA privilege
  875.                  controls in the BBS-list!
  876.  
  877.               Default: none (privilege indications will be reported).
  878.  
  879.   1. All commandline parameters are optional, may be specified in any
  880.      sequence and are case independent.
  881.  
  882.   2. Parameters from the configuration file are processed before those from
  883.      the commandline.  This has some side-effects, like:
  884.      ■  If you specify a specific list in DOWNSORT.CFG, it will be created
  885.         anyhow, whatever you specify on the commandline.
  886.      ■  However, if you specify privilege values on the commandline, only the
  887.         commandline values will be used, and none from the configuration
  888.         file.
  889.      ■  Commandline parameters have a global meaning, and are applied to all
  890.         lists (if applicable).  For example: if you specify '-A' on the
  891.         commandline, all lists will be sorted alphabetically on filename.
  892.  
  893.   3. Parameters that can be specified with the configuration file only, and
  894.      cannot be overridden with a commandline parameter are:
  895.      ■  BLOCK title text, font and BLOCK title suppression
  896.      ■  Subtitle lines
  897.      ■  Filename and individual list-options
  898.      ■  Privilege for FILES.BBS output
  899.  
  900.   4. Even when specified on the commandline, or in DOWNSORT.CFG, the
  901.      Orphan-report will be generated only if there are any orphans, and then
  902.      the specified parameters apply.
  903.  
  904.   5. The IPF-list has to be processed by the Information Presentation
  905.      Facility Compiler (IPFC).  This compiler is part of the IBM Programmers
  906.      Development Toolkit version 1.2 and 1.3 (maybe also in some other
  907.      toolkit).  The following command has to be issued:
  908.  
  909.       IPFC  DOWNSORT.IPF  /INF
  910.  
  911.      The option "/INF" is essential (but not documented!) to obtain a
  912.      viewable file.  Be also sure to have the file DOWNSORT.BMP in your
  913.      current default directory, or in DPATH, as this will be imbedded by the
  914.      IPF-compiler.  The result of the compilation is a file DOWNSORT.INF,
  915.      which can be VIEWed with the following command:
  916.  
  917.  
  918.                                                        How to use DOWNSORT  12
  919.  
  920.   Maximus Download File Sort and List Utility (OS/2 and DOS)
  921.  
  922.  
  923.  
  924.       VIEW  DOWNSORT
  925.  
  926.      Note:
  927.      ■  The names "DOWNSORT", "IPF" and "INF" are used here as sample,
  928.         actually the filename depends on the specification in the DOWNSORT
  929. |       configuration file, the extensions are the IPFC defaults.
  930. |    ■  If VIEW gives 'garbled' columns and hardly readable block-titles,
  931. |       then it is most likely that you did not install (or removed) the
  932. |       standard fonts that are delivered with OS/2.  Start the 'control
  933. |       panel utility', select 'installation', 'add fonts'.  Specify in the
  934. |       'from'-field C:\OS2\DLL (see HELP of control panel).  Now choose at
  935. |       least 1 non-proportional font.
  936.  
  937.  
  938.  
  939.   CONFIGURATION FILE
  940.  
  941.   Almost all processing options may be specified in an optional configuration
  942.   file, which can be specified with a commandline parameter.  The
  943.   configuration file is a somewhat more convenient way to specify processing
  944.   parameters, and allows even more customisation.  It is a good place for the
  945.   more static parameters of your environment, commandline parameters are nice
  946.   to create quickly 'another' list or a different format (for example wrapped
  947.   or truncated descriptions).  The parameters are only mentioned here for
  948.   completeness, see "Appendix C.  Sample Configuration File" on page 36 for a
  949.   documented specification sample of a configuration file.
  950.  
  951.  
  952.   PARAMETERS WITH GLOBAL SCOPE
  953.  
  954.   The parameters below influence the execution of DOWNSORT, or have impact on
  955.   every list (if it is applicable for that list).
  956.  
  957.   ■  File Specification of the MAXIMUS CBCS file 'AREA.DAT'.
  958.   ■  List title with BLOCK-characters.
  959.   ■  Font for the BLOCK title.
  960.   ■  Pre-titles, Sub-titles and Bottom-lines in 'text' format
  961.   ■  Descriptive text of orphans and files without a description in the input
  962.      FILES.BBS files.
  963.   ■  Maximum number of entries in NEW-list and BBS-list.
  964.  
  965.  
  966.  
  967.   PARAMETERS WITH LOCAL SCOPE
  968.  
  969.   The parameters below are sub-parameters of the xxxFileList keyword.
  970.  
  971.   ■  Up to 10 privileges for NEW-, GBL-, ALL- and IPF-list (each resulting in
  972.      a separate list).
  973.   ■  Alternate output filename (in stead of the default DOWNSORT).
  974.   ■  Directory for the output FILES.BBS-lists
  975.   ■  Maximum number of file entries in NEW-list and BBS-list
  976.   ■  File-entry sort sequence (filename or date).
  977.   ■  Wrap or Truncate long file descriptions.
  978.   ■  Title Font selection.
  979.  
  980.  
  981.                                                        How to use DOWNSORT  13
  982.  
  983.   Maximus Download File Sort and List Utility (OS/2 and DOS)
  984.  
  985.  
  986.  
  987. | ■  Suppression of privilege indications in NEW-, ALL-, IPF- and GBL-lists.
  988. | ■  Include textfile in NEW-, ALL-, IPF- and GBL-lists, and in FILES.bbs.
  989.  
  990.   A sample configuration file (DOWNSORT.CFG) is provided.  A listing of this
  991.   file is imbedded as "Appendix C.  Sample Configuration File" on page 36.
  992.   It contains a complete specification with comments on:
  993.  
  994.   ■  which options are available
  995.   ■  how to specify the options
  996.  
  997.   Read and modify the file as you like.  Copy the sample file to a save place
  998.   before you start modifying the original DOWNSORT.CFG!
  999.  
  1000.   NOTE: The parameters from DOWNSORT.CFG are processed first, then
  1001.   commandline parameters, which may complete and will (partly) override those
  1002.   in the configuration file.
  1003.  
  1004.  
  1005.   USABILITY HINTS
  1006.  
  1007.  
  1008.  
  1009.   SPECIFICATION OF AREA.DAT
  1010.  
  1011. | A MAXIMUS file 'AREA.DAT' is absolutely required by DOWNSORT.  It is
  1012. | however not necessary to run MAXIMUS itself, the AREA.DAT file is created
  1013. | with SILT(P) from the MAXIMUS package.  You can use this utility without
  1014. | the other MAXIMUS stuff.  In fact I do that myself (NOT running a MAXIMUS
  1015. | board)!  If you run DOWNSORT in directory without AREA.DAT, then you have
  1016.   several options:
  1017.  
  1018.   ■  You might add a COPY statement in your batch-file to copy AREA.DAT with
  1019.      every run into your DOWNSORT directory.
  1020.   ■  You might use the "@path" parameter to specify the complete filespec of
  1021.      AREA.DAT ("drive:\directory\file.ext").
  1022.   ■  You may use DOWNSORT.CFG for the filespec of AREA.DAT.
  1023.  
  1024.   The latter is recommended.
  1025.  
  1026.   Currently DOWNSORT does not allow to select the contents of the lists on
  1027.   area-code.  The '@path' allows you to specify a different AREA.DAT file
  1028.   than the one that is used by your MAXIMUS.  With SILT you may build a
  1029.   special AREA.DAT for exclusive use by DOWNSORT, with different, less, or
  1030.   more directories!
  1031.  
  1032.   If DOWNSORT reports a memory constraint (see also "Storage and Performance"
  1033.   on page 27), you may use this technique as circumvention: leave out one or
  1034.   more of the file area's and rerun DOWNSORT with the alternate AREA.DAT
  1035.   specification.
  1036.  
  1037.  
  1038.  
  1039.  
  1040.  
  1041.  
  1042.  
  1043.  
  1044.                                                        How to use DOWNSORT  14
  1045.  
  1046.   Maximus Download File Sort and List Utility (OS/2 and DOS)
  1047.  
  1048.  
  1049.  
  1050.   LOCATION OF FILES.BBS
  1051.  
  1052.   For input DOWNSORT uses either the ListFile specification in AREA.DAT, or
  1053.   the download directory to locate the file with file-descriptions (generally
  1054.   known as FILES.BBS).
  1055.  
  1056.   The destination of FILES.BBS-files is not by definition the same as the
  1057.   origin!  When specified with the "FIL:"-parameter (or in the configuration
  1058.   file), the output may be located in a different directory than the original
  1059.   input FILES.BBS.  Manual checking or post-processing by some other program
  1060.   may follow DOWNSORT, after which the files might be put back on the MAXIMUS
  1061.   specified position.
  1062.  
  1063.  
  1064.   PRIVILEGE CONTROL
  1065.  
  1066.   The default file privilege to be shown is SYSOP.
  1067.  
  1068.   Files without a matching filename-entry in FILES.BBS are treated as Hidden.
  1069.   That means that by default these files will not be listed, unless the 'H'
  1070.   privilege is used on the report-request specification.  All files with a
  1071.   higher privilege than the specified (or defaulted) report-privilege will
  1072.   not appear in the report.
  1073.  
  1074.  
  1075.   ORPHAN REPORT
  1076.  
  1077.   The Orphan report will be generated only if there are any orphans detected.
  1078.   In that case it overwrites a possibly present old DOWNSORT.ORP file.
  1079.  
  1080.   A way of suppressing Orphan-reporting is to include a "*.*" entry at the
  1081.   end of FILES.BBS.  This has two effects:
  1082.  
  1083.   ■  In the sense of DOWNSORT orphans do not exist anymore: there is a
  1084.      matching entry in FILES.BBS for every file.
  1085.   ■  The description of this entry will replace the hard-code text
  1086.      "----no-description-----".  You may specify your own text in
  1087.      DOWNSORT.CFG.
  1088.  
  1089.  
  1090.  
  1091.   DUPLICATES
  1092.  
  1093.   No test on duplicates is done, this means:
  1094.  
  1095.   ■  If a downloadpath is encountered more than once, the files will appear
  1096.      that many times in the outputlist (depending on the area-privilege!)
  1097.   ■  If a filename.ext is encountered more than once in different
  1098.      subdirectories, it will appear that many times in the outputlist.  The
  1099.      file-privilege reflects that of the area where the file belongs to
  1100.      (unless overridden by a ^Px modifier in FILES.BBS).
  1101.  
  1102.  
  1103.  
  1104.  
  1105.  
  1106.  
  1107.                                                        How to use DOWNSORT  15
  1108.  
  1109.   Maximus Download File Sort and List Utility (OS/2 and DOS)
  1110.  
  1111.  
  1112.  
  1113. | HEADERS, TITLES AND INCLUDE FILES
  1114.  
  1115. | There are several ways to custimise the appearance of the lists for
  1116. | DOWNSORT.  All items in the following list are optional, but the sequence
  1117. | in the reports is fixed and as listed:
  1118.  
  1119. | Pre-Title   Up to 20 lines as very first lines of your lists (sometimes
  1120. |             called Top-title).  Any text may be specified.  Leading
  1121. |             '~'-characters (tilde) will be treated as full-size required
  1122. |             blanks, mainly to manually align (center) the text in these
  1123. |             lines.  There is no automatic centering.  You may have to
  1124. |             experiment a little.
  1125.  
  1126. | TITLE       A short title (8-12 characters), that will appear as
  1127. |             'magnified' big BLOCK-letters.  There are 4 block-fonts to
  1128. |             choose from.  Not all characters are supported and lower-case
  1129. |             will be translated to upper-case.  The '~'-character (tilde)
  1130. |             will be treated as full-size required blank, the '`'-character
  1131. |             (accent-grave) as half-size required blank.
  1132.  
  1133. |             If not specified, a default title is generated as DOWNSORTxy,
  1134. |             where xy stands for the current version of DOWNSORT.  However
  1135. |             even this title may be suppressed by specifying TitleFont 0 in
  1136. |             the configuration file.
  1137.  
  1138. | Include-file A text-file to be included as is.  There will be no
  1139. |             manipulation of the contents of this file.  This include-file
  1140. |             may be all you need to obtain a fully custimised list.  For the
  1141. |             IPF-list it may (and probably should) contain IPF tags.
  1142.  
  1143. | Sub-Title   Up to 20 lines.  These are treated like the Pre-Title lines.
  1144.  
  1145. | BottomTitle Up to 20 lines as very last lines of the lists.  These follow
  1146. |             my 'signature'.  The lines follow the same treatment as
  1147. |             Pre-Title lines.
  1148.  
  1149. | The BLOCK-title and Pre-, Sub-, and Botton-titles are used for all reports
  1150. | identically, there is no such thing as an 'individual' title specification
  1151. | for each report.  However the Include-file may be different for each
  1152. | report.
  1153.  
  1154. | Note: Exceptions:
  1155.  
  1156. | 1. None of the above does apply to the BBS-list.  As it will generally be
  1157. |    desirable to imbed (compiled) MECCA control sequences in this type of
  1158. |    lists, this report will include dedicated top and bottom files (if
  1159. |    available in the current default directory).  These files must be called
  1160. |    DOWNSORT.HDR (header) and DOWNSORT.TRL (trailer).
  1161.  
  1162. | 2. The ORPHAN report will not contain any sort of user-titles.
  1163.  
  1164. | 3. The FILES.bbs files will not use any of the title-specifications, but
  1165. |    may use an Include-file.
  1166.  
  1167.  
  1168.  
  1169.  
  1170.                                                        How to use DOWNSORT  16
  1171.  
  1172.   Maximus Download File Sort and List Utility (OS/2 and DOS)
  1173.  
  1174.  
  1175.  
  1176. | Recommendation: File-requestors appreciate a header with a clear indication
  1177. | of the source of the reports.  Many Bulletin Boards use FILES or ALLFILES
  1178. | as 'magic' name, but that is not very distinctive if you collect lists of
  1179. | different boards!
  1180.  
  1181. | Note: Specification details and samples can be found in DOWNSORT.CFG.
  1182.  
  1183.  
  1184.   PRIVILEGES WITH FILE REQUEST
  1185.  
  1186.   If you run a mailer like BinkleyTerm, which makes a distinction between
  1187.   'unknown', 'known' and 'password-protected' users, you could generate
  1188.   multiple download lists with different privilege indictor, depending if you
  1189.   allow these categories to request different file collections a sample of
  1190.   this kind of environment is given in "Sample specifications and usage".
  1191.  
  1192.   This is not needed for DOWNSORT.BBS, since this file has imbedded privilege
  1193.   control sequences for MAXIMUS users.  But you should specify a sufficiently
  1194.   high privilege for the BBS-list to satisfy your most valuable users!
  1195.  
  1196.  
  1197.   SAMPLE SPECIFICATIONS AND USAGE
  1198.  
  1199.   Assume you are runnung MAXIMUS with BinkleyTerm as front end mailer.
  1200.   Suppose you make a distinction for file-requestors between Unknown, Known
  1201.   and Password-Protected (e.g. corresponding to Disgrace, Normal and
  1202.   Privileged MAXIMUS users).
  1203.  
  1204.  
  1205.   DOWNSORT SPECIFICATION SAMPLE
  1206.  
  1207.   You should have a specification like this:
  1208.  
  1209.     DOWNSORT bbs:p new:dnp all:dnp 100
  1210.  
  1211.   In addition to or in place of the specifications in DOWNSORT.CFG, this
  1212.   specification produces the following lists:
  1213.  
  1214.   ■  Orphan report (only if there are any orphans).
  1215.  
  1216.   ■  DOWNSORT.BBS with 100 entries for MAXIMUS users of category Privil.
  1217.      Users with a lower privilege will actually see a shorter list if the
  1218.      file contains Privil entries.
  1219.  
  1220.   ■  For file requestors of the magic filename FILES a list, a list with all
  1221.      files (with optional titles via DOWNSORT.CFG specifications):
  1222.      -  DOWNSORT.A~D for UNKNOWN file-requestors
  1223.      -  DOWNSORT.A~N for KNOWN file-requestors
  1224.      -  DOWNSORT.A~P for Password Protected file-requestors
  1225.  
  1226.      Note that each list is a complete list of what is available to the user
  1227.      of the specific privilege class, but your system will generally contain
  1228.      more files than listed for UNKNOWN and KNOWN users!
  1229.  
  1230.   ■  For file requests of the magic filename NEWFILES a list of the 100 most
  1231.  
  1232.  
  1233.                                                        How to use DOWNSORT  17
  1234.  
  1235.   Maximus Download File Sort and List Utility (OS/2 and DOS)
  1236.  
  1237.  
  1238.  
  1239.      recent additions to your system (with optional titles via DOWNSORT.CFG
  1240.      specifications):
  1241.      -  DOWNSORT.N~D for UNKNOWN file-requestors
  1242.      -  DOWNSORT.N~N for KNOWN file-requestors
  1243.      -  DOWNSORT.N~P for Password Protected file-requestors
  1244.  
  1245.      Note that each list is 100 entries long, but the contents will generally
  1246. |    not be quite the same (depending on your privilege strategy).
  1247.  
  1248.   In general: files, which the requestor is not supposed to know about due to
  1249.   his privilege status, will not be on his/her list!
  1250.  
  1251.   Note: The counters on top of the lists indicate what your system has
  1252.   available in total (including higher privileges), so a clever
  1253.   user/file-requester may come up with the question how that is possible:
  1254.   explain that he/she has to earn a higher privilege level!
  1255.  
  1256.  
  1257.   BINKLEYTERM SPECIFICATION SAMPLE
  1258.  
  1259.   In Binkley.Cfg you should specify for requests of FILES:
  1260.  
  1261.     Avail        Downsort.A~d
  1262.     KnownAvail   Downsort.A~n
  1263.     ProtAvail    Downsort.A~p
  1264.  
  1265.   Furthermore you may need to specify different OKFILEs:
  1266.  
  1267.     OKFile       Download.N
  1268.     KnownReqList Download.K
  1269.     ProtReqList  Download.P
  1270.  
  1271.   And in each of the appropriate filerequest authorisation files you should
  1272.   specify the appropriate file-spec:
  1273.  
  1274.  
  1275.  
  1276.  
  1277.  
  1278.  
  1279.  
  1280.  
  1281.  
  1282.  
  1283.  
  1284.  
  1285.  
  1286.  
  1287.  
  1288.  
  1289.  
  1290.  
  1291.  
  1292.  
  1293.  
  1294.  
  1295.  
  1296.                                                        How to use DOWNSORT  18
  1297.  
  1298.   Maximus Download File Sort and List Utility (OS/2 and DOS)
  1299.  
  1300.  
  1301.  
  1302.  
  1303.  
  1304.    ╔═══════════╦══════════════╦═══════════════╦═══════════════╗
  1305.    ║       in: ║ OKFile       ║ KnownReqList  ║ ProtReqList   ║
  1306.    ║           ║ (Download.N) ║ (Download.K)  ║ (Download.P)  ║
  1307.    ║ for:      ║              ║               ║               ║
  1308.    ╠═══════════╬══════════════╬═══════════════╬═══════════════╣
  1309.    ║ .....     ║ .........    ║ ...........   ║  ........     ║
  1310.    ║ @NEWFILES ║ Downsort.N~d ║ Downsort.N~n  ║  Downsort.N~p ║
  1311.    ║ @FILES    ║ Downsort.A~d ║ Downsort.A~n  ║  Downsort.A~p ║
  1312.    ║ .....     ║ .........    ║ ...........   ║  ........     ║
  1313.    ╚═══════════╩══════════════╩═══════════════╩═══════════════╝
  1314.  
  1315.   This will result in sending of the appropriate NEW-list to every requester
  1316.   of the magic filename: NEWFILES.  If you use the second magic filename,
  1317.   then the Avail-lines in Binkley.Cfg are not needed, and you might prefer
  1318.   this way.
  1319.  
  1320.   Of course if the privilege level of all download area's is the same, this
  1321.   construction is not needed, but in that case it is unlikely that you have
  1322.   specified KnownAvail and ProtAvail!
  1323.  
  1324.  
  1325.   DEPENDENCIES AND RESTRICTIONS
  1326.  
  1327.   ■  Applies to MAXIMUS CBCS 1.00 and 1.02.
  1328.  
  1329.   ■  Requires OS/2 or DOS 3.0+.
  1330.  
  1331.   ■  To convert the IPF-list into VIEW-able format (downsort.INF), the
  1332.      IPF-Compiler under OS/2 is required.
  1333.  
  1334.   ■  The input FILES.BBS files are assumed to contain only filename.ext (the
  1335.      regular 8.3 format, no support for OS/2 1.2+ HPFS format), the remainder
  1336.      of the line is considered as file description.  The filename should be
  1337.      left-aligned (start in position 1).
  1338.  
  1339.      If a privilege modifier (^Px) is encountered in FILES.BBS then 'x' will
  1340.      become the privilege of all subsequent files (it assumes ^Px on a
  1341.      SEPARATE line, the REST OF THE LINE IS IGNORED!).  Heading, comments and
  1342.      blank lines in FILES.BBS are ignored.  The modified privilege might be
  1343.      higher (generally the case) or lower than the area-privilege.
  1344.  
  1345.  
  1346.  
  1347.   WISHLIST
  1348.  
  1349.   DOWNSORT is not finished!  There are a number of wishes and requirements of
  1350.   users and myself to include in future releases.  I list them below not in
  1351.   any particular order, but some seem to be more important than others (but
  1352.   that differs from SYSOP to SYSOP).  And some are more easy to implement
  1353.   than others, and that depends mainly on the author!
  1354.  
  1355.   ■  Follow the MAXIMUS development (changing AREA.DAT and other structures),
  1356.      and support several versions simultaneously.  I'll try to make DOWNSORT
  1357.  
  1358.  
  1359.                                                        How to use DOWNSORT  19
  1360.  
  1361.   Maximus Download File Sort and List Utility (OS/2 and DOS)
  1362.  
  1363.  
  1364.  
  1365.      independent of MAXIMUS-versions.  I'm thinking of parsing AREA.CTL, in
  1366.      stead of using AREA.DAT, as suggested by Scott Dudley himself.
  1367.  
  1368.   ■  Automatic removal of 'bad' files (like .BAK-files, obsolete files, files
  1369.      that are not in FILES.BBS), maybe move them to a special BAD_FILE
  1370.      directory.
  1371.  
  1372.   ■  User-configurable options for:
  1373.      -  week and month indicators
  1374.      -  indicator for continuation lines in wrapped descriptions
  1375.      -  font in AREA-header and Summary in ALL-list, and in FILES.BBS
  1376.  
  1377.   ■  Add [selectable] MECCA control in FILES.BBS, like in the BBS-list.
  1378.  
  1379.   ■  Logging to file in stead of console, obtaining a history file of
  1380.      DOWNSORT usage.
  1381.  
  1382.   ■  File-selection with MAXIMUS CBCS key/lock parameters in addition or in
  1383.      stead of privilege levels.
  1384.  
  1385.   ■  Selection of files in reports on area, or group of area's.
  1386.  
  1387.   ■  Support for use of 'barricaded' areas and key/lock.
  1388.  
  1389.   ■  Selection of NEW-list on basis of oldest date or time-period.
  1390.  
  1391. | ■  Another list: with the format of IPF-list but the contents of NEW-list.
  1392.  
  1393. | ■  Preserve comments and formattings of FILES.BBS files when rebuilding
  1394. |    these files.
  1395.  
  1396.  
  1397.  
  1398.   KNOWN PROBLEMS
  1399.  
  1400.   Although I try to prevent the cause of them, there are problem reports:
  1401.  
  1402.   ■  Some unidentified characters somewhere between block- and sub-title.
  1403.  
  1404.  
  1405.  
  1406.  
  1407.  
  1408.  
  1409.  
  1410.  
  1411.  
  1412.  
  1413.  
  1414.  
  1415.  
  1416.  
  1417.  
  1418.  
  1419.  
  1420.  
  1421.  
  1422.                                                        How to use DOWNSORT  20
  1423.  
  1424.   Maximus Download File Sort and List Utility (OS/2 and DOS)
  1425.  
  1426.  
  1427.  
  1428.   PACKAGING
  1429.  
  1430.   DOWNSORT is distributed in 2 archives:
  1431.  
  1432.   ■  A file "DWNSRTxy.ZIP", containing all material you need to run DOWNSORT,
  1433.      including documentation, formatted for browsing or printing (formfeed is
  1434.      the only printer-control).
  1435.  
  1436.   ■  A file "DWNSRSxy.ZIP", containing all SOURCE material.
  1437.  
  1438.   Note: 'xy' is the version indication, for example DWNSRT51.ZIP is the
  1439.   version 5.1 (RUN-time) package.
  1440.  
  1441.  
  1442.   RUN-TIME MATERIAL
  1443.  
  1444.   WHATSNEW.51         Summary of amendments to version 5.1 of DOWNSORT.
  1445.   DOWNSORT.EXE        Execution module for DOS and OS/2 (Family Application)
  1446.   DOWNSORT.DOC        Documentation (this file!).
  1447.   DOWNSORT.CFG        Sample configuration file.  This file contains comment
  1448.                       lines with extensive instructions how to specify the
  1449.                       parameters in the file.
  1450.   DOWNSORT.HDR        Sample BBS-list header.  You may use this header, which
  1451.                       is only imbedded in the BBS-list, to imbed text and/or
  1452.                       MECCA-sequences.  A good candidate for the latter would
  1453.                       be [onexit], which translates to ^OFpath.  See the
  1454.                       sample DOWNSORT.HDR file!
  1455.   DOWNSORT.TRL        Sample BBS-list trailer.
  1456.   DOWNSORT.BMP        Bitmap for the IPF-list, to be included by the IPF
  1457. |                     compiler.
  1458. | DOWNSORT.INC        Sample Include-file for the reports, referenced in
  1459. |                     DOWNSORT.CFG.
  1460.   HPFSDATE.EXE        Program to display all three timestamps of a file on an
  1461.                       HPFS volume, and optionally reset the CREATION date to
  1462.                       LASTWRITE date (helpful after moving or copying of
  1463.                       files).  Start the program without options to display
  1464.                       command syntax and help.
  1465.   README.1ST          The actual contents of the package (produced with
  1466.                       PKUNZIP -V), added to the ZIP-file after this was
  1467.                       created with the foregoing files of this archive.  This
  1468.                       gives at least some authentication!
  1469.  
  1470.  
  1471.  
  1472.   SOURCE MATERIAL
  1473.  
  1474.   DOWNSORT.C          Source of mainline and global variable definitions.
  1475.   DOWNCOL.C           Source of data collection functions.
  1476.   DOWNFNT.C           Source of font definition and formatting function.
  1477.   DOWNPAR.C           Source of parameter processing functions.
  1478.   DOWNRPT1.C          Source of output report functions (except what is in
  1479.                       DOWNRPT2.C)
  1480.   DOWNRPT2.C          Source of output report functions for ALL-list and
  1481.                       IPF-list.
  1482.   DOWNSRV.C           Source of miscellaneous services functions.
  1483.  
  1484.  
  1485.                                                                  Packaging  21
  1486.  
  1487.   Maximus Download File Sort and List Utility (OS/2 and DOS)
  1488.  
  1489.  
  1490.  
  1491.   DOWNSORT.H          Header file, with external definitions of global
  1492.                       variables.
  1493.   DOWNSORT.SCT        Unformatted documentation file.  This file includes
  1494.                       formatting tags in BOOKMASTER style for printing on
  1495.                       whatever devices are supported (like IBM page
  1496.                       printers).  This format is compatible and can be
  1497.                       formatted on an IBM host system with DCF (SCRIPT) as
  1498. |                     well.  The file can also processed by the IPF-compiler
  1499. |                     (just ignore the warnings and error-messages!).  You
  1500. |                     may have to 'repair' the file of the Toolkit version
  1501. |                     1.1 with symbols (APSYMBOL.APS) in the IPFC directory:
  1502. |                     e.g. '&titde.' should be '&tilde.', and all symbols
  1503. |                     should end with a full-stop (.), such as '&box34.'.
  1504. |                     The IBM Toolkit 1.2/1.3 is distributed without these
  1505. |                     errors.
  1506.   AREA_MAX.H          Header file with union specification of AREA.DAT for
  1507.                       different versions of MAXIMUS (as far as the layout of
  1508.                       AREA.DAT is concerned).
  1509.   AREA_100.H          Header file with guessed layout of AREA.DAT for MAXIMUS
  1510.                       CBCS version 1.00.
  1511.   AREA_102.H          Header file with layout of AREA.DAT of MAXIMUS CBCS
  1512.                       version 1.02.
  1513.   DOWNSORT.DEF        LINK definition file.
  1514.   DOWNSORT.MAK        MAKE file.
  1515.   README.1ST          The actual contents of the package (produced with
  1516.                       PKUNZIP -V), added to the ZIP-file after this was
  1517.                       created with the foregoing files of this archive.  This
  1518.                       gives at least some authentication!
  1519.  
  1520.  
  1521.  
  1522.   AVAILABILITY
  1523.  
  1524.   The most recent version of DOWNSORT is always downloadable and
  1525.   file-requestable from Bulletin Board "PC-Square" of the Dutch IBM employee
  1526.   PC club.  Search or request DWNSRT??.* to be independent of the version and
  1527.   compression method!
  1528.  
  1529.   FIDO-net address:  2:512/4; phone:  31-79-424107 (USR HST-DS).
  1530.  
  1531.   DOWNSORT is distributed in area SDSMAX of the international Shareware
  1532.   Distribution System.
  1533.  
  1534.   There is a fair chance you may find a recent version on one of the other
  1535.   bulletin boards, listed in "Appendix B.  Who use DOWNSORT?" on page 35.
  1536.  
  1537.  
  1538.  
  1539.  
  1540.  
  1541.  
  1542.  
  1543.  
  1544.  
  1545.  
  1546.  
  1547.  
  1548.                                                                  Packaging  22
  1549.  
  1550.   Maximus Download File Sort and List Utility (OS/2 and DOS)
  1551.  
  1552.  
  1553.  
  1554.   INTERNALS
  1555.  
  1556.  
  1557.  
  1558.   DEVELOPMENT ENVIRONMENT
  1559.  
  1560.   DOWNSORT has been developed with IBM C/2 compiler version 1.1, under IBM
  1561.   OS/2 Extended Edition 1.3 with Program Development Toolkit version 1.2/1.3
  1562. | as COMPACT memory model.
  1563.  
  1564. | DOWNSORT has been tested for MAXIMUS CBCS 1.00 and 1.02, with the following
  1565. | Operating Systems:
  1566.  
  1567. | ■  IBM PC/DOS versions 4.0 and 5.0 (pre-release)
  1568. | ■  IBM OS/2 versions 1.3 and 2.0 (pre-release)
  1569. | ■  DOS-box of IBM OS/2 versions 1.3 and 2.0 (pre-release)
  1570.  
  1571.  
  1572.  
  1573.   PROGRAM ORGANISATION
  1574.  
  1575.   The program is organised as follows:
  1576.  
  1577.   ■  Initialisation:
  1578.      -  Read configuration file.
  1579.      -  Process commandline parameters.
  1580.  
  1581.      The commandline parameters will override configuration file parameters.
  1582.  
  1583.   ■  Read AREA.DAT file to collect download pathnames (assumes AREA.DAT is in
  1584. |    current directory).
  1585.  
  1586. | ■  For all file-area's with a privilege not exceeding any list-request:
  1587.  
  1588.      -  Read subdirectory (with find-file-first/next function).  Take only
  1589.         Normal files: ignore directory entries, Hidden and System files and
  1590.         volume labels.  Also ignore MAXIMUS-files with the following
  1591.         specifications: FILES.?BS, *.BAK, DIR.?BS and SYSTEM*.?BS
  1592.  
  1593.      -  For all regular file-entries found in subdirectory:
  1594.         -- Get filename.ext, attribute, date, time, size (timestamp will be
  1595.            'last-time-written').
  1596.         -- Get file-description from FILES.BBS file.  The path to the
  1597.            FILES.BBS file is (1) obtained from the "ListFile" specification
  1598.            in MAXIMUS AREA.DAT file, or (2) if not specified from the
  1599.            "DownLoad" specification (among the download files).
  1600. |       -- Get file privilege 1) from area, 2) from FILES.BBS file.
  1601. |       -- When no orphan reporting is required, then drop the orphan
  1602. |          entries.
  1603.  
  1604.   ■  For the ORP-list:
  1605.  
  1606.      If any orphan found, and the orphan-report is requested, create the
  1607.      orphan report, with the file-entries sorted on (1) area and (2)
  1608.      filename.
  1609.  
  1610.  
  1611.                                                                  Internals  23
  1612.  
  1613.   Maximus Download File Sort and List Utility (OS/2 and DOS)
  1614.  
  1615.  
  1616.  
  1617.   ■  For the BBS-list:
  1618.      -  Sort the files primarily on descending file-timestamp (and secundary
  1619.         on file-name and area-code).
  1620.      -  Resort the first files on filename if requested.
  1621.      -  Create output file for sorted list of filenames, -descriptions, etc.
  1622.         The file is placed in the current subdirectory (which generally will
  1623.         be the MAXIMUS directory) with the name DOWNSORT.BBS.
  1624.      -  Copy a headerfile (for a customised MAXIMUS bulletin).
  1625.      -  Put files in formatted outputfile (filename, area#, date, size,
  1626.         description), but only if description is found in FILES.BBS.  Skip
  1627.         files with privilege higher than commandline (or default) parameter.
  1628.         Precede each line with a privilege-control sequence (^PLx string) so
  1629.         that MAXIMUS users below the specified max-priv-level do effectively
  1630.         see only the files they can download.
  1631.      -  Include a trailerfile in the outputfile (for a custimised Bulletin).
  1632.      -  Report non-listed files on standard output device (which might be
  1633.         re-directed to printer or disk-file).
  1634.  
  1635.   ■  If requested, put the above file collection (also in reverse
  1636.      date-sequence) in DOWNSORT.N~p with similar contents and layout as
  1637.      DOWNSORT.BBS, but without BBS-control sequences, and without including a
  1638.      header and trailer file.  Produce a list for the default privilege
  1639.      (HIDDEN), or one for each specified privilege.
  1640.  
  1641.   ■  If requested, re-sort files on area and then filename, and create
  1642.      DOWNSORT.A~p, containing all files (respecting the privilege
  1643.      restrictions!).  Area's with zero files within the applicable privilege
  1644.      limit will not be listed at all (will seem non-existing!).  Produce a
  1645.      list for the default privilege (SYSOP), or one for each specified
  1646.      privilege.
  1647.  
  1648.      At the end of the list, an area summary report is generated.
  1649.  
  1650.   ■  If requested, re-sort files on filename only, and create DOWNSORT.GBL.
  1651.  
  1652.   ■  If requested, re-sort files on area, privilege and filename, and create
  1653.      for each area a FILES.BBS-type of file.
  1654.  
  1655.   NOTE: the program firstly reads a directory for existing files (not Hidden-
  1656.   or System-files, and not Subdirectory or Volumelabel), and then reads
  1657.   FILES.BBS to assign a description to each file.  This means:
  1658.  
  1659.   ■  If more than 1 matching file-specification in FILES.BBS of the involved
  1660.      area is found (note that wild-card specifications in FILES.BBS are
  1661.      supported!), than the first matching description from FILES.BBS will
  1662.      appear in the lists (new in version 4.5, was 'last' previous versions).
  1663.   ■  Files for which no description is found in FILES.BBS will get "---no
  1664.      description available---" (or the replacement string you specified in
  1665.      DOWNSORT.CFG) in the user reports.
  1666.   ■  Files for which no matching filename in FILES.BBS is found will be
  1667.      listed in the Orphan report (DOWNSORT.ORP).
  1668.  
  1669.      In special cases this might become a very large list.  For example if
  1670.      you collect files in a single directory for different area's, all the
  1671.      files of 'the other' areas are reported as orphan.  This will happen for
  1672.  
  1673.  
  1674.                                                                  Internals  24
  1675.  
  1676.   Maximus Download File Sort and List Utility (OS/2 and DOS)
  1677.  
  1678.  
  1679.  
  1680.      every area, so each file might even be reported many times as orphan!
  1681.      Since the Orphan-list is now optional (from version 5.0 on), this list
  1682.      can be suppressed.
  1683.  
  1684.      Filenames of Orphans appear only in the other reports when the FileList
  1685.      request explicitly specifies the Hidden privilege.
  1686.  
  1687.  
  1688.  
  1689.   MAIN DATA ORGANISATION
  1690.  
  1691.   Data structure for access to file information via:
  1692.  
  1693.   1. array of file-pointers (for file-sort!)
  1694.   2. pointerchain in file-info structures
  1695.   3. file structure contains pointer to file-description
  1696.   4. file-structure contains pointer to area-information
  1697.   5. Array of area-information
  1698.  
  1699.   The structures are shown in Figure 1 on page 26.
  1700.  
  1701.  
  1702.  
  1703.  
  1704.  
  1705.  
  1706.  
  1707.  
  1708.  
  1709.  
  1710.  
  1711.  
  1712.  
  1713.  
  1714.  
  1715.  
  1716.  
  1717.  
  1718.  
  1719.  
  1720.  
  1721.  
  1722.  
  1723.  
  1724.  
  1725.  
  1726.  
  1727.  
  1728.  
  1729.  
  1730.  
  1731.  
  1732.  
  1733.  
  1734.  
  1735.  
  1736.  
  1737.                                                                  Internals  25
  1738.  
  1739.   Maximus Download File Sort and List Utility (OS/2 and DOS)
  1740.  
  1741.  
  1742.  
  1743.  
  1744.  
  1745.   ╔══════╗
  1746.   ║  dm  ║
  1747.   ╚══════╝
  1748.       │         Array of pointers to structures with file info
  1749.       │      ╔═══════════╦════════════╦═════════════ . . . ══════╗
  1750.   (1) └─────>║ *file[0]  ║  *file[1]  ║ *file[2]                 ║
  1751.              ╚═══════════╩════════════╩═════════════ . . . ══════╝
  1752.                    │           │            │
  1753.   (2)              v           v            v
  1754.   ╔══════╗     ╔══════╗     ╔══════╗     ╔══════╗
  1755.   ║  ca  ║ ──> ║ next ║ ──> ║ next ║ ──> ║ next ║ ──> . . .
  1756.   ╚══════╝     ╠══════╣     ╠══════╣     ╠══════╣
  1757.    (first-     ║ file-║     ║ file-║     ║ file-║
  1758.    element)    ║ info ║     ║ info ║     ║ info ║    . . .
  1759.                ║ [0]  ║     ║ [1]  ║     ║ [2]  ║
  1760.                ╚══════╝     ╚══════╝     ╚══════╝
  1761.                    │ │         │  │wildcards│ │
  1762.                    │ └──┐      │  └──┐      │ │
  1763.                    │    │      │ ┌──────────┘ │
  1764.   (3)              v    │      v v   │ ┌──────┘
  1765.                ╔══════╗ │   ╔══════╗ │ │
  1766.                ║file- ║ │   ║file- ║ │ │(files of
  1767.                ║descr ║ │   ║descr ║ │ │ same area)   . . .
  1768.                ╚══════╝ │   ╚══════╝ │ │
  1769.                         │            │ │
  1770.   (4)                   v            v v
  1771.                 ╔════════════╦═════════════╦════════ . . . ══════╗
  1772.   (5) ┌────────>║  area[0]   ║   area[1]   ║                     ║
  1773.       │         ╚════════════╩═════════════╩════════ . . . ══════╝
  1774.       │              array of structures of download info
  1775.   ╔══════╗
  1776.   ║ area ║
  1777.   ╚══════╝
  1778.  
  1779.   Figure 1. Schematic overview of DOWNSORT's in-storage database.
  1780.  
  1781.   Note: The area-array cannot be sorted itself: this would invalidate the
  1782.   pointers in the file-information records!
  1783.  
  1784.   The block character image is basically a 10x7 matrix (10 vertical and 7
  1785. | horizontal 'pixels').  The pixel-array takes two rows at a time, so that
  1786. | each character can be represented with 5 rows of 7 horizontal
  1787. | 'double-pixels'.  Each pixel is displayed as a solid block.
  1788.  
  1789.  
  1790.  
  1791.  
  1792.  
  1793.  
  1794.  
  1795.  
  1796.  
  1797.  
  1798.  
  1799.  
  1800.                                                                  Internals  26
  1801.  
  1802.   Maximus Download File Sort and List Utility (OS/2 and DOS)
  1803.  
  1804.  
  1805.  
  1806.  
  1807.            1 2 3 4 5 6 7
  1808.           ╔═╦═╦═╦═╦═╦═╦═╗
  1809.           ║-║-║-║-║-║-║-║   line 1    (lower + upper)
  1810.           ╠═╬═╬═╬═╬═╬═╬═╣
  1811.           ║-║-║-║-║-║-║-║        2    (lower + upper)
  1812.           ╠═╬═╬═╬═╬═╬═╬═╣
  1813.           ║-║-║-║-║-║-║-║        3    (lower + upper)
  1814.           ╠═╬═╬═╬═╬═╬═╬═╣
  1815.           ║-║-║-║-║-║-║-║        4    (lower + upper)
  1816.           ╠═╬═╬═╬═╬═╬═╬═╣
  1817.           ║-║-║-║-║-║-║-║        5    (lower + upper)
  1818.           ╚═╩═╩═╩═╩═╩═╩═╝
  1819.  
  1820.   Each line is represented by a structure of seven 3-bit fields Each 3-bit
  1821.   field represents a basic element:
  1822.  
  1823.    value    char       description
  1824.      0                 (blank)
  1825.      1     ▄           lower half
  1826.      2       ▀         upper half
  1827.      3         █       lower+upper halves
  1828.      4       ▓         gray pattern
  1829.      5     ▌           left part of upper and lower half
  1830.      6       ▐         right part of upper and lower half
  1831.      7         ░       gray pattern
  1832.      8      ▒          gray pattern for not-supported characters
  1833.  
  1834.   The pitch is variable ('proportional font': a variable number of horizontal
  1835.   pixels).  Three fonts are provided with different character-image and size:
  1836.  
  1837.   1. 6x5 (three lines of max 5 characters)
  1838.   2. 10x7 (five lines of max 7 characters)
  1839.   3. 8x7 (four lines of max 7 characters)
  1840.   4. 10x7 (reverse video image of the 8x7 font)
  1841.  
  1842.   Not all ASCII characters are represented in the font tables!
  1843.  
  1844.  
  1845.   STORAGE AND PERFORMANCE
  1846.  
  1847.   As a rough estimate of the memory requirements of DOWNSORT, use sum of the
  1848.   following elements:
  1849.  
  1850.   ■  Program: about 70KB
  1851.  
  1852.   ■  Each area: 300 Bytes
  1853.  
  1854.   ■  Each file: 64 Bytes for each file (excl. file descriptions)
  1855.  
  1856.   ■  The sum of the description texts (on average 80 Bytes?)
  1857.  
  1858.   There is a theoretical limit on the number of files that can be processed
  1859.   by DOWNSORT: about 16000 files.  I suppose you'll reach other limits first,
  1860.   for example stack-space.  DOWNSORT has been built with a 'guess' about
  1861.  
  1862.  
  1863.                                                                  Internals  27
  1864.  
  1865.   Maximus Download File Sort and List Utility (OS/2 and DOS)
  1866.  
  1867.  
  1868.  
  1869.   needed stack space.  The author would appreciate to receive a report for a
  1870.   better estimate.
  1871.  
  1872.   Processor performance was an issue for large file-area's before version 4.5
  1873.   of DOWNSORT in the data-collection process.  That has been partly rewritten
  1874.   in version 4.5 and significantly improved.  Fastest execution will always
  1875.   be obtained when the input FILES.BBS is already sorted on filename.
  1876.  
  1877.  
  1878.  
  1879.  
  1880.  
  1881.  
  1882.  
  1883.  
  1884.  
  1885.  
  1886.  
  1887.  
  1888.  
  1889.  
  1890.  
  1891.  
  1892.  
  1893.  
  1894.  
  1895.  
  1896.  
  1897.  
  1898.  
  1899.  
  1900.  
  1901.  
  1902.  
  1903.  
  1904.  
  1905.  
  1906.  
  1907.  
  1908.  
  1909.  
  1910.  
  1911.  
  1912.  
  1913.  
  1914.  
  1915.  
  1916.  
  1917.  
  1918.  
  1919.  
  1920.  
  1921.  
  1922.  
  1923.  
  1924.  
  1925.  
  1926.                                                                  Internals  28
  1927.  
  1928.   Maximus Download File Sort and List Utility (OS/2 and DOS)
  1929.  
  1930.  
  1931.  
  1932.   APPENDIX A.  HISTORY OF CHANGES
  1933.  
  1934.   The paragraphs below show a brief history of changes in DOWNSORT (most
  1935.   recent revisions on top of list!).
  1936.  
  1937.   DOWNSORT for MAXIMUS CBCS was developed from an OPUS equivalent (by the
  1938.   same author).  Its pre-MAXIMUS history is not really important here and
  1939.   therefore has been omitted.  However the name DOWNSORT has been maintained,
  1940.   so to prevent confusion, the version number is inherited (the last version
  1941. | for OPUS was 3.1).
  1942.  
  1943.  
  1944. | VERSION 5.1
  1945.  
  1946. | ■  Since the ORPhan report is optional (changed with version 5.0), orphan
  1947. |    entries could and now will be removed from internal storage during the
  1948. |    information collection phase of DOWNSORT, but only when no orphan-list
  1949. |    is requested!  This is especially useful for the situation where a
  1950. |    single large directory contains the files of several area's, and whereby
  1951. |    the file descriptions are contained in different FILES.BBS files.
  1952. |    Normally this will result in reporting lots of duplicate orphans
  1953. |    (according to the definition of 'orphan' in DOWNSORT!).  With this
  1954. |    change memory utilisation is lower and sorting faster.
  1955. | ■  Another change of this kind: area's with a privilege exceeding any
  1956. |    reporting privilege are not scanned anymore.  Apart from lower memory
  1957. |    utilisation, this might be useful for CDROM and slow disk(ette) systems.
  1958. | ■  The maximum number of Top-, Sub- and Bottom-Title lines has been
  1959. |    extended to 20.
  1960. | ■  In addition all lists may now include a 'logo'-file with a new -I
  1961. |    parameter on the individual report request specification (see sample
  1962. |    DOWNSORT.CFG).  The file will be copied into the list without any
  1963. |    editing or translation.  It will be positioned directly behind the
  1964. |    block-title and before the subtitle (if any).  For example: you may
  1965. |    include your BBS-logo or a picture of your system configuration, or
  1966. |    anything else you want to tell the file-requestors of FILES, ALLFILES
  1967. |    and/or NEWFILES.  The IPF-list may also include IPF tags, with artwork,
  1968. |    etc.  It may even include other files itself!  For FILES.BBS the
  1969. |    contents of this Include-file will immediately follow the 'standard'
  1970. |    header.
  1971. | ■  All block-fonts have now a new special character <`> (reversed quote),
  1972. |    which will be 'printed' as blank (space) with half the width of a normal
  1973. |    character.  This is useful for fine-alignment (e.g. manually centering)
  1974. |    the BLOCK-title.
  1975. | ■  The chapter on 'titles and headers' has been rewritten to clarify the
  1976. |    use of all title-options, please read it!.
  1977. | ■  In the SUMMARY of ALL- and IPF-lists the areas themselves are not sorted
  1978. |    anymore, but presented in sequence of AREAS.CTL specification.  This is
  1979. |    based on the assumption that the file area's are in some kind of
  1980. |    'natural' order in AREAS.CTL (or maybe it is time to do that now!).
  1981. | ■  Descriptions in FILES.BBS are now (again) aligned on column 14 of the
  1982. |    FILES.bbs file records.
  1983. | ■  IPF-list again a little more user-friendly (linking of area's).
  1984. | ■  A number of improvements have been applied to the executiontime messages
  1985. |    (when running in VERBOSE mode).
  1986.  
  1987.  
  1988.  
  1989.                                            Appendix A.  History of changes  29
  1990.  
  1991.   Maximus Download File Sort and List Utility (OS/2 and DOS)
  1992.  
  1993.  
  1994.  
  1995.   VERSION 5.0
  1996.  
  1997.   ■  Improved IPF-formatting: more colorful, builtin word-wrapping of VIEW
  1998.      used for file descriptions (better VIEWable under OS/2 1.3!).  It should
  1999.      now also compile without errors/warnings.  Compiling (with IPFC) takes
  2000.      significantly longer however!
  2001.   ■  The IPF-list of large filearea's (>200 files) split into parts of 200
  2002.      files to prevent files being left unlisted.
  2003.   ■  Top-level title in FileLists shows file-count and byte-count as
  2004.      available within the privilege of the list.  Thus it indicates what is
  2005.      really AVAILable to the user!  Area-count omitted in lists which are not
  2006.      area-oriented.
  2007.   ■  ORPHAN report made OPTIONAL (must be specified to get it!).
  2008.  
  2009.  
  2010.  
  2011.   VERSION 4.9
  2012.  
  2013.   ■  Added a new list-format: IPF-list, similar to ALL-list, but meant to be
  2014.      made a VIEWable file ('book') under OS/2 Presentation Manager.
  2015.   ■  Sourcefile DOWNRPT.C splitted into 2 parts.
  2016.   ■  Correction in FILES.BBS header (to prevent the "offline" msg).
  2017.   ■  Now also FILES.BBS output can be kept in original sequence with the
  2018.      K(eep)-option.
  2019.   ■  Added the X-option: all 'written' privilege indications in the lists can
  2020.      now be suppressed: the user is then not aware of any privilege-system!
  2021.   ■  Header-lines of all lists now more consistent in sequence.
  2022.   ■  The 'I'- and '1'-characters in fonts 3 and 4 have been widened to 5
  2023.      colums (was 3 colums, but that looked too 'narrow').
  2024.   ■  The documentation has been extended with a list of Bulletin Boards, of
  2025.      which the SYSOPs have reported being a regular user of DOWNSORT.
  2026.   ■  Distribution has been changed: run-time and source material now in a
  2027.      separate archive files (DWNSRTxy.ZIP and DWNSRSxy.ZIP).
  2028.  
  2029.  
  2030.  
  2031.   VERSION 4.8
  2032.  
  2033.   ■  A 'KEEP' parameter (-K) added to allow the files to remain in original
  2034.      sequence of FILES.BBS.  This option is now only valid for ALL-list
  2035.      (later for FIL-list too).
  2036.   ■  Documentation change: for multi-line file descriptions a continuation
  2037.      line must start with at least 1 blank-character, followed by at least 1
  2038.      significant (non-blank) character.
  2039.   ■  Repaired bug in sort on filedate for FIL-lists.
  2040.  
  2041.  
  2042.  
  2043.   VERSION 4.7
  2044.  
  2045.   ■  Sorting of files on HPFS volumes (OS/2 1.2) now takes into account the
  2046.      file CREATION-date (= arrival date on your system).  Sort will take the
  2047.      most recent of Creation and LastWrite.  The 'old fashioned' LastWrite
  2048.      date (indicating the age of the file) is displayed in the lists!  This
  2049.      feature is only effective under OS/2 from release 1.2 for files on an
  2050.  
  2051.  
  2052.                                            Appendix A.  History of changes  30
  2053.  
  2054.   Maximus Download File Sort and List Utility (OS/2 and DOS)
  2055.  
  2056.  
  2057.  
  2058.      HPFS volume.
  2059.   ■  Use of DOSOPEN() from OS/2 Program Development Toolkit (allows for
  2060.      better multi-session and LAN support).
  2061.   ■  New font added: reverse video image of font3, and related changes in
  2062.      font generation function.
  2063.   ■  Added separation lines in FILES.BBS like in ALL-list.
  2064.   ■  Tiny adjustment to date formatting: year 2000 and later will be
  2065.      displayed as 2-digit numbers.
  2066.  
  2067.  
  2068.  
  2069.   VERSION 4.6
  2070.  
  2071.   ■  Downsort will try to locate and read a configuration file allowing even
  2072.      more processing options (by default DOWNSORT.CFG in current directory).
  2073.      An extensively documented sample is accompanying the DOWNSORT package.
  2074.      No additional document-reading needed to run DOWNSORT for the first
  2075.      time.  The introduction of this feature makes some commandline
  2076.      parameters superfluous, and allows more flexibility, like:
  2077.      -  In addition to a number of global parameters, each list has a 'local'
  2078.         set of formatting parameters for sort-sequence, description wrapping,
  2079.         title-font, maximum number of entries (NEW and BBS only).  The
  2080.         individual parameters can be set only via the configuration file.
  2081.      -  Specification of AREA.DAT and "title" not possible anymore on the
  2082.         commandline, now only by means of the configuration file.
  2083.      -  A "@filespec" commandline option now used for specification of the
  2084.         configuration file (makes the use of different files for different
  2085.         purposes possible).
  2086.   ■  Multiline FILES.BBS input now supported.  Automatic conversion to long
  2087.      descriptions provided when requesting FILES.BBS (re-)creation.
  2088.   ■  Multiple GBL-lists can now be generated, like ALL-list.  Difference
  2089.      between ALL-list and GBL-list is only the grouping by in area's, and the
  2090.      area-summary in ALL-list.  SYSOP may decide which of both serves the
  2091.      users best.
  2092.   ■  User supplied pre-title, sub-title and bottomlines now supported for
  2093.      NEW, ALL and GBL-lists, as well as replacement text for
  2094.      '---no-description---' and '---orphan---' in the lists.
  2095.   ■  BLOCK-title font user-configurable and BLOCK-title can now be
  2096.      suppressed.
  2097.   ■  NEW-list and GBL-list have an additional header-line telling the maximum
  2098.      file-privilege shown in the list.
  2099.   ■  FILES.BBS has now column header, and a user-specified privilege limit
  2100.      applies also to FILES.BBS (orphans now only listed when explicitly
  2101.      requested with 'Hidden').
  2102.   ■  The HELP-screen is now only shown on request via a commandline parameter
  2103.      (-H).
  2104.  
  2105.  
  2106.  
  2107.   VERSION 4.5
  2108.  
  2109.   ■  FILES.BBS-files may be (re-)created now in DOWNSORT-style (like the
  2110.      ALL-list format).  Read carefully the information about this option in
  2111.      the report description!
  2112.   ■  An ORPHAN-report is now produced always (not requestable) and
  2113.  
  2114.  
  2115.                                            Appendix A.  History of changes  31
  2116.  
  2117.   Maximus Download File Sort and List Utility (OS/2 and DOS)
  2118.  
  2119.  
  2120.  
  2121.      independent from other reports.  It replaces the reporting of ORPHANs to
  2122.      the console formerly done during creation of the BBS-list.
  2123.   ■  The BBS-list is no longer produced by default, it should be specifically
  2124.      requested now, like the other user-reports.
  2125.   ■  The BBS-list and NEW-list may now be sorted on filename, and for that
  2126.      reason also these lists will have an age indicator 'week' or 'month' old
  2127.      appended to the file date.
  2128.   ■  'Verbose' and 'Quiet' operating mode are possible now: many more or much
  2129.      less console messages with one of these specifications, than regularly.
  2130.   ■  Performance improvement obtained in data collection process, significant
  2131.      especially for large area's.
  2132.   ■  Filename matching process changed (one of the reasons of the performance
  2133.      improvement): first matching filename is used now to assign the file
  2134.      description to a file.
  2135.   ■  Title block-font is now proportional, and two fonts are added.  The
  2136.      fonts are not (yet) user selectable.
  2137.   ■  A path to the appropriate AREA.DAT file may be specified now (@path).
  2138.   ■  The possible specification of "ListFile" in AREA.CTL is recognised now
  2139.      (in stead of assuming FILES.BBS in the download directory).
  2140.   ■  Added display of an "I-am-busy" indicator during the collection of file
  2141.      information (processing FILES.BBS input).
  2142.   ■  Added display of date and time of report-creation to bottom of file
  2143.      lists (except FILES.BBS files), and also the total elapsed time on
  2144.      console.
  2145.   ■  Fixed bug in detection of newest file, which in rare situations pointed
  2146.      to a file outside the privilege group.
  2147.   ■  Added HELP-screen when no commandline parameters specified, or on
  2148.      request (-H commandline parameter).
  2149.   ■  'Signature' at bottom of lists extended.
  2150.   ■  Documentation extended for all the new features, and a little
  2151.      re-organised.
  2152.   ■  Internal data structure for file-information changed for improved
  2153.      storage utilisation.
  2154.   ■  Time has come to split source into several modules!
  2155.  
  2156.  
  2157.  
  2158.   VERSION 4.4
  2159.  
  2160.   ■  Support for different versions of MAXIMUS (1.00 and 1.02), with respect
  2161.      to the layout of AREA.DAT.
  2162.   ■  Multi-line file descriptions now supported, with word-wrap and an option
  2163.      to select or deselect it in different reports.
  2164.   ■  Extended AREA-header in ALL-list with area-privilege indicator, and
  2165.      latest acquisition (date and file-spec).
  2166.   ■  Added indicators '*' and '+' in GBL- and ALL-list for files of 1-week
  2167.      and 1-month old respectively.
  2168.   ■  Added "--- no description available ---" in lists if filename found in
  2169.      FILES.BBS, but there is no description there.
  2170.   ■  Added "****** ORPHAN *******" in description field of files, for which
  2171.      there is no entry in FILES.BBS.
  2172.   ■  Files that are reported to the console as "not listed", now also display
  2173.      the area, (pseudo-) privilege and file description (or "no description"
  2174.      or "ORPHAN" whatever is applicable).
  2175.   ■  Changed default file-report privilege into SYSOP.  Hidden files will not
  2176.  
  2177.  
  2178.                                            Appendix A.  History of changes  32
  2179.  
  2180.   Maximus Download File Sort and List Utility (OS/2 and DOS)
  2181.  
  2182.  
  2183.  
  2184.      show up, unless specifically asked for!
  2185.   ■  More characters supported as BLOCK-characters (including '/' and '\').
  2186.   ■  Fixed a bug in routines for NEW-, BBS- and ALL-list, which occasionally
  2187.      gave addressing violations (in the OS/2 version).
  2188.   ■  A related change in the data structure of the file-information for the
  2189.      file-description decreases storage utilisation, taking advantage of
  2190.      wild-card specifications in FILES.BBS as supported by MAXIMUS.
  2191.   ■  Fast growing wishlist added to documentation!
  2192.  
  2193.  
  2194.  
  2195.   VERSION 4.3
  2196.  
  2197.   ■  GBL-list added: a complete list of the download base (back from 4.0 and
  2198.      earlier versions of DOWNSORT, where it was called ALL!).
  2199.   ■  An AREA-summary report has been added to ALL-list.
  2200.   ■  ALL-list now also displays total bytecount per area.
  2201.   ■  A default title will be generated if none is specified.
  2202.   ■  Routine for generating block routines replaced.
  2203.   ■  Block character '/' (slash) replaced by '|' (vertical bar).
  2204.  
  2205.  
  2206.  
  2207.   VERSION 4.2
  2208.  
  2209.   ■  DOWNSORT.BBS and DOWNSORT.NEW are not produced any longer by default.
  2210.      Each list-type must now be specifically requested by BBS, NEW, or ALL on
  2211.      the commandline.
  2212.   ■  Multiple ALL-lists and NEW-lists may be produced now.  Each of these may
  2213.      contain files of different (maximum) privilege level.  This makes it
  2214.      possible to have overviews for different classes of users.
  2215.   ■  A report title for the ALL- and NEW-lists may be specified, and will be
  2216.      printed in BLOCK-characters.
  2217.   ■  A remark has been added to the top of DOWNSORT.BBS that the list may
  2218.      seem shorter due to privilege restrictions.
  2219.   ■  Longer file-description where there is space for it (ALL-list).
  2220.   ■  Requirement of filenames in FILES.BBS to be UPPERcase dropped.
  2221.   ■  Documentation extended and re-formatted.
  2222.   ■  Some more re-shuffling of code (for maintenance purposes)!
  2223.  
  2224.  
  2225.  
  2226.   VERSION 4.1
  2227.  
  2228.   ■  Bug-repairs in filename-matching routine.
  2229.   ■  SORT changed for DOWNSORT.ALL: sort on name within area, gives an
  2230.      alphabetical list per download area.
  2231.   ■  File descriptions now left aligned, regardless its position in
  2232.      FILES.BBS.
  2233.   ■  Group-title (of file-area) copied from AREA.DAT in ALL.
  2234.   ■  Files excluded from the lists are now more generally: FILES.?BS, DIR.?BS
  2235.      and  SYSTEM*.?BS
  2236.   ■  Parameter added to hide files above a maximum privilege-level.
  2237.   ■  Files without description are treated as Hidden, these will appear in
  2238.      the lists when 'H' is selected (note: by default!).
  2239.  
  2240.  
  2241.                                            Appendix A.  History of changes  33
  2242.  
  2243.   Maximus Download File Sort and List Utility (OS/2 and DOS)
  2244.  
  2245.  
  2246.  
  2247.   ■  Improved sort organisation (pointers in stead of structures).
  2248.   ■  Minor changes and additions to lists (beautification?).
  2249.   ■  Some minor internal re-organisation.
  2250.  
  2251.  
  2252.  
  2253.   VERSION 4.0
  2254.  
  2255.   ■  New setup for MAXIMUS CBCS Bulletin Board environment, this version does
  2256.      not support OPUS' file system!
  2257.   ■  Support of non-numeric (two-character) area code.
  2258.   ■  Support of wild-characters in the file-name part of the records in the
  2259.      description-files (FILES.BBS), as allowed by MAXIMUS.
  2260.   ■  The file DOWNSORT.NEW (not ".TXT") will be produced always (error in
  2261.      previous documentation), but now without TXT2COM formatting characters,
  2262.      since there is not (yet) a suitable alternative under OS/2.
  2263.  
  2264.  
  2265.  
  2266.  
  2267.  
  2268.  
  2269.  
  2270.  
  2271.  
  2272.  
  2273.  
  2274.  
  2275.  
  2276.  
  2277.  
  2278.  
  2279.  
  2280.  
  2281.  
  2282.  
  2283.  
  2284.  
  2285.  
  2286.  
  2287.  
  2288.  
  2289.  
  2290.  
  2291.  
  2292.  
  2293.  
  2294.  
  2295.  
  2296.  
  2297.  
  2298.  
  2299.  
  2300.  
  2301.  
  2302.  
  2303.  
  2304.                                            Appendix A.  History of changes  34
  2305.  
  2306.   Maximus Download File Sort and List Utility (OS/2 and DOS)
  2307.  
  2308.  
  2309.  
  2310.   APPENDIX B.  WHO USE DOWNSORT?
  2311.  
  2312.   PC-Square may be considered as the home-base of DOWNSORT.  The most recent
  2313.   version is always available there (file-requests between 07:00 and 24:00
  2314.   local time).
  2315.  
  2316.   PC-Square           Marcel Stikkelman     Zoetermeer, Netherlands
  2317.   2:512/4                                   31-79-424107
  2318.  
  2319.   The following SYSOPs have reported using DOWNSORT on their
  2320.   respective boards:
  2321.  
  2322.   OS/2-MANiA          Emmanuel Sandorfi     Paris, France
  2323.   2:320/5                                   33-1-64090640
  2324.  
  2325. | OS/2 TASK BBS       Rene Carlsen          Skagen, Denmark
  2326. | 2:231/85                                  45-98451070
  2327.  
  2328. | Paradigmus Maximus  John Taylor           London, UK
  2329. | 2:253/68                                  44-81-566-5393
  2330.  
  2331.   Fernwood            Emitt Dove            Branford CT, USA
  2332.   1:141/209                                 1-203-483-0348
  2333.  
  2334. | Bell's Theorem      Jeremy Buhler         Houston TX, USA
  2335. | 1:106/7674                                1-713-777-0633
  2336.  
  2337.   OS/2 Shareware      Pete Norloff          Fairfax VA, USA
  2338.   1:109/347                                 1-703-385-4325
  2339.  
  2340.   Singing Bear        John Tarbox           Wilmington DE, USA
  2341.   1:150/130                                 1-302-984-2238
  2342.  
  2343.   La Jungle BBS       Stephane Seguin       Quebec, Canada
  2344.   1:163/116                                 1-819-595-4917
  2345.  
  2346. | 3M Australia        Graham Stair          Sydney, NSW Australia
  2347. | 3:711/409                                 61-2-498-9184
  2348.  
  2349.   I have received reports from others.  Too many for this list, which is just
  2350.   meant to point to a system in your neighbourhood(?).  You may either logon
  2351.   to one of these boards, or perform a file-request of 'FILES' or 'ALLFILES'
  2352.   to get an impression of DOWNSORT's capabilities.
  2353.  
  2354.  
  2355.  
  2356.  
  2357.  
  2358.  
  2359.  
  2360.  
  2361.  
  2362.  
  2363.  
  2364.  
  2365.  
  2366.  
  2367.                                             Appendix B.  Who use DOWNSORT?  35
  2368.  
  2369.   Maximus Download File Sort and List Utility (OS/2 and DOS)
  2370.  
  2371.  
  2372.  
  2373.   APPENDIX C.  SAMPLE CONFIGURATION FILE
  2374.  
  2375.   ;
  2376.   ;      ██▐███   █▐███  ██   ██ ██▐███ ██▐████  █▐███  ██▐███  ██▐████
  2377.   ;      ██   ██ ██   ██ ██   ██ ██  ██ ██      ██   ██ ██   ██   ▐██
  2378.   ;      ██   ██ ██   ██ ██ █ ██ ██  ██ ██▐████ ██   ██ ██▐███    ▐██
  2379.   ;      ██   ██ ██   ██ ██ █ ██ ██  ██      ██ ██   ██ ██ █      ▐██
  2380.   ;      ██▐███   █▐███   █▐███  ██  ██ ██▐████  █▐███  ██  ██    ▐██
  2381.   ;                                                                   (font 2)
  2382.   ;
  2383.   ;
  2384.   ; ▄▀▀▀▄ ▄▀▀▀▄ █▄  █ █▀▀▀▀ ▀█▀ ▄▀▀▀▄ █   █ █▀▀▀▄ ▄▀▀▀▄ ▀▀█▀▀ ▀█▀ ▄▀▀▀▄ █▄  █
  2385.   ; █     █   █ █▀█▄█ █▄▄    █  █  ▄▄ █   █ █▄▄▄▀ █▄▄▄█   █    █  █   █ █ ▀▄█
  2386.   ; ▀▄▄▄▀ ▀▄▄▄▀ █  ▀█ █     ▄█▄ ▀▄▄▄▀ ▀▄▄▄▀ █ ▀▄▄ █   █   █   ▄█▄ ▀▄▄▄▀ █   █
  2387.   ;                                                                   (font 1)
  2388.   ;
  2389.   ;
  2390.   ;                   █▀▀▀▀▀▀   █     █       █▀▀▀▀▀▀
  2391.   ;                   █▄▄▄▄▄▄   █▄    █▄      █▄▄▄▄▄▄
  2392.   ;                   ██        ██    ██      ██
  2393.   ;                   ██        ██    ██▄▄▄▄▄ ██▄▄▄▄▄
  2394.   ;                                                                   (font 3)
  2395.   ;                                             (font 4 is reverse video of 3)
  2396.   ;
  2397.   ;  ┌─────────────────────────────────────────────────────────────────────────┐
  2398.   ;  │      Sample Configuration File for DOWNSORT by Rob Hamerling            │
  2399.   ;  └─────────────────────────────────────────────────────────────────────────┘
  2400.   ;
  2401.   ; NOTES: Leading blanks are skipped.
  2402.   ;        Lines with '%', '*' or ';' as first non-blank character are
  2403.   ;        considered as comment, as well as empty lines and lines with
  2404.   ;        a valid keyword, but without any parameter-value.
  2405.   ;
  2406.   ;        Don't put a comment string after a parameter specification!
  2407.   ;
  2408.   ;
  2409.   ; AreaDat:     Complete file-specification of your 'AREA.DAT'
  2410.   ; -------
  2411.   ;              AREA.DAT is made by MAXIMUS' SILT(P) with -a or -x
  2412.   ;              option the path is normally specified in MAX.CTL
  2413.   ;              with the option AreaDat in Session Section.
  2414.   ;              With the AreaDat you may specify any file that has
  2415.   ;              the SILT(P)-format. For example you may make a special
  2416.   ;              file for running DOWNSORT with a subset (selection)
  2417.   ;              of the normal MAXIMUS file-area's.
  2418.   ;              This might be useful for special usergroups.
  2419.   ;              Another reason may be the memory usage of DOWNSORT
  2420.   ;              under DOS. If you hit the boundary: make a subset.
  2421.   ;              Standard OS/2 / DOS naming applies.
  2422.  
  2423.   ; AreaDat        g:\c2\downsort\Area102.Dat
  2424.   AreaDat        g:\c2\downsort\area5124.dat
  2425.  
  2426.   ; TitleFont:   Reference number of the BLOCK-font you want for your Title.
  2427.   ; ---------
  2428.  
  2429.  
  2430.                                     Appendix C.  Sample Configuration File  36
  2431.  
  2432.   Maximus Download File Sort and List Utility (OS/2 and DOS)
  2433.  
  2434.  
  2435.  
  2436.   ;              Valid numbers:   1 .. Simple font             (5x6 pattern)
  2437.   ;                               2 .. Pseudo-Stencil Font     (7x10 pattern)
  2438.   ;                               3 .. ROBoComputer Font       (7x8 pattern)
  2439.   ;                               4 .. Reversed Video RoboComp (7x8 pattern)
  2440.   ;
  2441.   ;              NOTE: The fonts are based on the US-codepage (437).
  2442.   ;                    This will also work properly for 860 (Portugese),
  2443.   ;                    863 (Canadian-French) and 865 (Nordic).
  2444.   ;                    If codepage 850 (Multilingual) is active, the pattern
  2445.   ;                    will be adapted a little, see if you like it or not.
  2446.   ;                    The differences apply mainly to Font2.
  2447.   ;
  2448.   ;              The heading of this file shows font 2, 1 and 3 respectively.
  2449.  
  2450.   TitleFont      1
  2451.  
  2452.   ;  Title:      Short string that will be displayed in BLOCK-characters
  2453.   ;  -----       on top of all FileLists (except BBS-list).
  2454.   ;              You may specify this parameter also on the xxxFileList
  2455.   ;              parameter.
  2456.   ;
  2457.   ;              The BLOCK fonts are 'proportional', the following number of
  2458.   ;              characters will generally fit on a line:
  2459.   ;
  2460.   ;                 FontTitle   1     maximum characters: 13
  2461.   ;                    "      2 .. 4     "        "        8
  2462.   ;
  2463.   ;              No more than 20 characters are accepted as input.
  2464.   ;
  2465.   ;              If Title isn't specified, it will be DOWNSORT by default.
  2466.   ;              Not all characters are supported, and that may vary with
  2467.   ;              the font itself. All fonts support:
  2468.   ;
  2469.   ;                - UPPER case  A..Z
  2470.   ;                - LOWER case  a..z , but will be translated to UPPER case
  2471.   ;                - Digits 0..9
  2472.   ;                - - (hyphen), blank
  2473.   ;
  2474.   ;              In addition fonts 1 and 2 support the following characters:
  2475.   ;
  2476.   ;                   _  *  -  |  .  [  ]  (  )  /  \
  2477.   ;
  2478.   ;              Not-supported characters are displayed as blank.
  2479.   ;              The '~'-character (tilde) may be used as required blank,
  2480.   ; (5.1)        the '`'-character (reverse quote) as half width blank.
  2481.  
  2482.   ; Title          `DownSort
  2483.  
  2484.   ;  PreTitle    Lines to be displayed immediately before the BLOCK-title.
  2485.   ;  --------    The lines will be copied asis, however leading blanks are
  2486.   ;              skipped, no wrapping or truncation will be applied for
  2487.   ;              'long' lines, '~' (tilde) characters are translated to
  2488.   ; (5.1)        blanks. You may specify 20 PreTitles, excess is ignored.
  2489.   ;              Empty PreTitle lines are ignored and not counted.
  2490.   ;              There is no default pretitle.
  2491.  
  2492.  
  2493.                                     Appendix C.  Sample Configuration File  37
  2494.  
  2495.   Maximus Download File Sort and List Utility (OS/2 and DOS)
  2496.  
  2497.  
  2498.  
  2499.   ;              To create empty lines in your header specify a PreTitle
  2500.   ;              with a tilde.
  2501.  
  2502.   PreTitle       ~
  2503.   PreTitle       ~~~~~~~~<═════:═════ p r e - t i t l e ═════:═════>
  2504.   PreTitle       ~
  2505.  
  2506.   ;  SubTitle    Lines to be displayed immediately below the BLOCK-title.
  2507.   ; (5.1) -----  Maximum 20 SubTitles are accepted, and exactly the
  2508.   ;              same rules apply as for PreTitle.
  2509.   ;
  2510.  
  2511.   SubTitle       ~1
  2512.   SubTitle       ~2     <═════&═════ s u b - t i t l e ═════&═════>
  2513.   SubTitle       ~3 Overview of downloadable files on this magnificent Board
  2514.   SubTitle       ~4    Node number 1.234/56, modemspeeds: V.32/V.22bis
  2515.   SubTitle       ~5 ═══════════════════════════════════════════════════
  2516.   SubTitle       ~6                          ║
  2517.   SubTitle       ~7                          ║
  2518.   SubTitle       ~8                          ║
  2519.   SubTitle       ~9                          ║
  2520.   SubTitle       ~10                         ║
  2521.   SubTitle       ~11                         ║
  2522.   SubTitle       ~12                         ║
  2523.   SubTitle       ~13                         ║
  2524.   SubTitle       ~14                         ║
  2525.   SubTitle       ~15                         ║
  2526.   SubTitle       ~16                         ║
  2527.   SubTitle       ~17                         ║
  2528.   SubTitle       ~18                         ║
  2529.   SubTitle       ~19                         ║
  2530.   SubTitle       ~20                         V
  2531.   SubTitle       ~21     Should not appear: maximum is 20
  2532.  
  2533.   ;  BottomLine  Lines to be displayed at the end of the filelist.
  2534.   ; (5.1) -----  Maximum 20 BottomLines are accepted, and exactly the
  2535.   ;              same rules apply as for PreTitle and Subtitle.
  2536.   ;
  2537.  
  2538.   BottomLine     ~
  2539.   BottomLine     ~~~~~<════════════ b o t t o m : l i n e ══════════════>
  2540.   BottomLine     ~
  2541.   BottomLine     ~~~~~<══════ How do you like this DOWNSORT, folks? ══════>
  2542.   BottomLine     ~
  2543.  
  2544.   ; MaxNewFiles  Limit the number of file entries in BBS-list and NEW-list(s).
  2545.   ; -----------  It specifies the actual number of file entries that may
  2546.   ;              appear in NewFileList and BBSFileList.
  2547.   ;              If you specify more than one privilege (for NewFileList),
  2548.   ;              then each list will contain (max) the MaxNewFiles number
  2549.   ;              of file entries, but the collection of each may differ due
  2550.   ;              to Privilege considerations.
  2551.  
  2552.   MaxNewFiles    200
  2553.  
  2554.  
  2555.  
  2556.                                     Appendix C.  Sample Configuration File  38
  2557.  
  2558.   Maximus Download File Sort and List Utility (OS/2 and DOS)
  2559.  
  2560.  
  2561.  
  2562.   ; OrphanDesc   Description text of Orphan files.
  2563.   ; NotFoundDesc Description text of files without description in FILES.BBS.
  2564.   ; ------------ The description will replace the default hard-coded text.
  2565.   ;              Up to 45 characters may be specified.
  2566.   ;              The '~' (tilde) character will not be translated here!
  2567.  
  2568.   OrphanDesc     ~~~~~ !!!! Orphelin !!!! ~~~~~
  2569.   NotFoundDesc   +++ Ce fichier défie toute description! +++
  2570.  
  2571.   ; ══════════════════════════════════════════════════════════════════════
  2572.   ; Above were the parameters with a global effect: applicable to all
  2573.   ; lists or to the execution mode of DOWNSORT.
  2574.   ; Below follow list-specific parameters, which might override some of
  2575.   ; the settings of the global parameters.
  2576.   ; Leave this sequence: first global, then specific parameters!
  2577.   ; ══════════════════════════════════════════════════════════════════════
  2578.  
  2579.   ; xxxFileList:  Create one or more File lists of type 'xxx'.
  2580.   ;
  2581.   ;              ┌──────────── TWIT
  2582.   ; xxx ───┐     │┌─────────── DISGRACE      ┌─ FileName of the list
  2583.   ;             ││┌────────── LIMITED       │  (without extension,
  2584.   ;   ┌── ORP    │││┌───────── NORMAL        │  maximum 8 characters)
  2585.   ;   ┌── BBS    ││││┌──────── WHORTY        │
  2586.   ;   ┌── NEW    │││││┌─────── PRIVIL        │
  2587.   ;   ┌── ALL    ││││││┌────── FAVORED       │   ┌─ Additional options for
  2588.   ;   ┌── GBL    │││││││┌───── EXTRA         │   │  each list individually:
  2589.   ;   ┌── IPF    ││││││││┌──── CLERK         │   │
  2590.   ;   │          │││││││││┌─── ASSTSYSOP     │   │ -W  - Wrap Description
  2591.   ;   │          ││││││││││┌── SYSOP         │   │ -T  - Truncate Descr.
  2592.   ;   │          │││││││││││┌─ HIDDEN        │   │ -A  - Alpha sort on name
  2593.   ;   │          ││││││││││││                │   │ -D  - Date sort
  2594.   ;   │          ││││││││││││                │   │ -K  - Keep FILES.BBS seq
  2595.   ;   │          ││││││││││││                │   │ -If - Include_filespec
  2596.   ;   │          ││││││││││││     ┌──────────┘   │ nnn - NEW-entries limit
  2597.   ;   │          ││││││││││││     │              │ -Fn - Title font (0..4)
  2598.   ;   │          ││││││││││││     │              │ -X  - eXcl priv in headers
  2599.   ;             ││││││││││││                   
  2600.   ;  ═══─═══════   ════════  ════════════════════════════════
  2601.   ;  xxxFileList TDLNWPFECASH  FileName  Option-1 Option-2 . . . Option-n
  2602.   ;
  2603.   ;  If just xxxFileList is specified, the Level by default will be SYSOP
  2604.   ;                                    and the filename will be DOWNSORT.
  2605.   ;
  2606.   ;  For NEW-, GBL-, ALL- and IPF-list up to 10 privilege letters can
  2607.   ;  be specified and for each character a separate list-file will be
  2608.   ;  generated with the following extension:
  2609.   ;     NewFileList:   N~p
  2610.   ;     AllFileList:   A~p
  2611.   ;     IpfFileList:   I~p
  2612.   ;     GblFileList:   G~p
  2613.   ;  where 'p' is the privilege character.
  2614.   ;  For the BBS-list only 1 privilege character will be accepted.
  2615.   ;  The default filename (DOWNSORT) for each list can be overridden
  2616.   ;  with the [optional] third parameter on the xxxFileList line.
  2617.  
  2618.  
  2619.                                     Appendix C.  Sample Configuration File  39
  2620.  
  2621.   Maximus Download File Sort and List Utility (OS/2 and DOS)
  2622.  
  2623.  
  2624.  
  2625.   ;  If you do not specify any xxxFileList, only the Orphan report may be
  2626.   ;  generated.
  2627.   ;
  2628.   ;  Additionally some other parameters can be specified (in any sequence).
  2629.   ;
  2630.   ;    nnn  Limit the number of file-entries to maximal 'nnn'
  2631.   ;         applies only to BBS-list and NEW-list.
  2632.   ;
  2633.   ;    -A   Selects Alphabetic sort on filename
  2634.   ;    -D   Selects sort on Date/Time of the file
  2635.   ;    -K   Keep sequence of files in FILES.BBS
  2636.   ;         (ALL- and IPF-list, and newly generated FILES.BBS files).
  2637.   ;
  2638.   ;    -T   Causes Truncation of long descriptions (to about 50 characters)
  2639.   ;         so that only 1 line will appear per file-entry.
  2640.   ;    -W   Causes Wrapping of long descriptions: the report will contain
  2641.   ;         as many lines as needed for the complete description.
  2642.   ;
  2643.   ;    -If  Include userfile (f = file-spec) in report for NEW-, ALL-,
  2644.   ;(5.1)    IPF-, GBL-lists and FILES.bbs files. The file is included
  2645.   ;         without any translations, so beware of formatting (text-float)
  2646.   ;         in the IPF-list!
  2647.   ;
  2648.   ;    -X   eXclude privilege indications in NEW-, ALL-, IPF- and GBL-lists.
  2649.   ;
  2650.   ;    -Fn  ListTitle font. Choose for 'n': 1, 2, 3 or 4 (default is 2).
  2651.   ;         See some samples of the fonts in the top of this file.
  2652.   ;         If '0' (zero) specified, then NO BLOCK TITLE will be generated.
  2653.   ;
  2654.   ;  If an asterisk (*) is used as parameter value character, the hardcoded
  2655.   ;  default value will be used. If you specify mutually exclusive
  2656.   ;  options (-A or -D) or (-T or -W), then the last value on the line
  2657.   ;  will be effective.
  2658.   ;
  2659.   ;  NOTES 1. For ORPFileList the privilege parameter does not apply, but at
  2660.   ;  -----    least 1 character must be specified!
  2661.   ;        2. Invalid or not-recognised sub-parameters are ignored without
  2662.   ;           any warning!
  2663.  
  2664.   ;AllFileList    PCASH  Down_All      -k -T  -f1  -X  -Idownsort.inc
  2665.   AllFileList    a      Down_All      -k -W  -f1   -Idownsort.inc
  2666.   BBSFileList    a      Down_Bbs   23 -a     -F1   -Idownsort.inc
  2667.   GblFileList    a      Down_Gbl      -d     -F3   -Idownsort.inc
  2668.   IpfFileList     d     Down_Ipf      -a     -F4   -Idownsort.inc
  2669.   NewFileList    a      Down_New      -d -w  -f2   -Idownsort.inc
  2670.   ; OrpFileList    *      Down_Orp      -a     -f4
  2671.  
  2672.   ;  NOTE: The IPF-list has the format of an INPUT-file for the
  2673.   ;        Information Presentation Facility Compiler (IPFC), which is
  2674.   ;        part of the IBM OS/2 Toolkit 1.2+ and equivalent MicroSoft
  2675.   ;        package. This inputfile has to be processed by this compiler.
  2676.   ;        For the sample above with the command:
  2677.   ;             IPFC  DOWN_IPF.I~P  /INF
  2678.   ;        Be sure to have the file DOWNSORT.BMP in the default directory and
  2679.   ;        set the IPFC environment-variable (e.g. SET IPFC=E:\TOOLKT13\IPFC).
  2680.  
  2681.  
  2682.                                     Appendix C.  Sample Configuration File  40
  2683.  
  2684.   Maximus Download File Sort and List Utility (OS/2 and DOS)
  2685.  
  2686.  
  2687.  
  2688.   ;        IPFC will produce a file called DOWN_IPF.INF, which is ready
  2689.   ;        to be viewed with the command:
  2690.   ;             VIEW  DOWN_IPF
  2691.   ;        See the Toolkit documentation for details of IPFC.
  2692.   ;        IPFC is not distributed with the DOWNSORT package!
  2693.  
  2694.   ; FILFilePath  Maximum file privilege that any FILES.bbs should contain,
  2695.   ; -----------  the path specification of the FILES.bbs type of output.
  2696.   ;              Specify this in the format: drive:\directory\
  2697.   ;              If not specified the MAXIMUS path specification will be
  2698.   ;              used (ListFile parameter or Download-File directory).
  2699.   ;              Not all parameters of other lists (see above) apply to
  2700.   ;              the FILES.bbs lists (since it will not contain a TITLE
  2701.   ;              as the other lists and the file-description will be
  2702.   ;              kept on 1 (long) line).
  2703.  
  2704.   ; FILFilePath    a   g:\c2\downsort\filesbbs\  -a -Idownsort.inc
  2705.  
  2706.   ;
  2707.   ;  ═════════════════════════════════════════════════════════════════
  2708.   ;
  2709.   ;  Commandline parameters may supply additional options, and may
  2710.   ;  (partly) override the specifications in this configuration file.
  2711.   ;  Consider this file as your customised default setting for DOWNSORT,
  2712.   ;  and use commandline parameters only to make other lists on the fly.
  2713.   ;  There is nothing that you can specify with commandline parameters,
  2714.   ;  that you cannot specify in this configuration file!
  2715.   ;
  2716.  
  2717.  
  2718.  
  2719.  
  2720.  
  2721.  
  2722.  
  2723.  
  2724.  
  2725.  
  2726.  
  2727.  
  2728.  
  2729.  
  2730.  
  2731.  
  2732.  
  2733.  
  2734.  
  2735.  
  2736.  
  2737.  
  2738.  
  2739.  
  2740.  
  2741.  
  2742.  
  2743.  
  2744.  
  2745.                                     Appendix C.  Sample Configuration File  41
  2746.