home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 2 BBS / 02-BBS.zip / dwnsrt64.zip / DOWNSORT.DOC < prev    next >
Text File  |  1998-01-16  |  173KB  |  4,133 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.                                                                            
  17.  
  18.                                                                    DOWNSORT
  19.                                                                            
  20.                            Maximus CBCS DOWNload file SORT and List Utility
  21.                                                                            
  22.                                                 Version 6.4k (OS/2 and DOS)
  23.                                                                            
  24.  
  25.  
  26.  
  27.                                                            January 16, 1998
  28.  
  29.  
  30.                                                               Rob Hamerling
  31.  
  32.                                                     Vianen, The Netherlands
  33.                                                    FIDO-net: 2:280/804.1098
  34.                                               E-mail: RobH@capitolonline.nl
  35.  
  36.                  Maximus Download File Sort and List Utility (OS/2 and DOS)
  37.  
  38.  
  39.  
  40.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  41.     
  42.     
  43.     
  44.     CONTENTS
  45.  
  46.  
  47.       1.0 Introduction  . . . . . . . . . . . . . . . . . . . . . . . . . 1
  48.       1.1 History   . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
  49.       1.2 Purpose and Objectives  . . . . . . . . . . . . . . . . . . . . 2
  50.       1.3 Quick start   . . . . . . . . . . . . . . . . . . . . . . . . . 2
  51.       1.4 Registration and Shareware Fee  . . . . . . . . . . . . . . . . 3
  52.       1.5 Warranty and Support  . . . . . . . . . . . . . . . . . . . . . 4
  53.       1.6 Acknowledgements  . . . . . . . . . . . . . . . . . . . . . . . 4
  54.  
  55.       2.0 User's Guide  . . . . . . . . . . . . . . . . . . . . . . . . . 5
  56.       2.1 Initial setup   . . . . . . . . . . . . . . . . . . . . . . . . 5
  57.       2.2 Runtime considerations  . . . . . . . . . . . . . . . . . . . . 6
  58.       2.3 Data Collection   . . . . . . . . . . . . . . . . . . . . . . . 7
  59.         2.3.1 FAREA.DAT   . . . . . . . . . . . . . . . . . . . . . . . . 7
  60.         2.3.2 Download Directory  . . . . . . . . . . . . . . . . . . . . 8
  61.         2.3.3 FILES.BBS   . . . . . . . . . . . . . . . . . . . . . . . . 8
  62.       2.4 List Type Selection   . . . . . . . . . . . . . . . . . . . . . 8
  63.         2.4.1 ALL-list  . . . . . . . . . . . . . . . . . . . . . . . . . 8
  64.         2.4.2 GBL-list  . . . . . . . . . . . . . . . . . . . . . . . . . 9
  65.         2.4.3 HTM-list and HTN-list   . . . . . . . . . . . . . . . . . . 9
  66.         2.4.4 IPF-list and IPN-list  . . . . . . . . . . . . . . . . . . 10
  67.         2.4.5 BBS-list   . . . . . . . . . . . . . . . . . . . . . . . . 10
  68.         2.4.6 NEW-list   . . . . . . . . . . . . . . . . . . . . . . . . 11
  69.         2.4.7 TOP-list   . . . . . . . . . . . . . . . . . . . . . . . . 11
  70.         2.4.8 ORPHAN-list  . . . . . . . . . . . . . . . . . . . . . . . 11
  71.         2.4.9 DUP-list   . . . . . . . . . . . . . . . . . . . . . . . . 11
  72.         2.4.10 OKFile  . . . . . . . . . . . . . . . . . . . . . . . . . 12
  73.         2.4.11 USR-list  . . . . . . . . . . . . . . . . . . . . . . . . 13
  74.         2.4.12 Rebuild FILES.BBS   . . . . . . . . . . . . . . . . . . . 14
  75.       2.5 Data Selection   . . . . . . . . . . . . . . . . . . . . . . . 15
  76.         2.5.1 Access Control String  . . . . . . . . . . . . . . . . . . 15
  77.         2.5.2 AREA selection   . . . . . . . . . . . . . . . . . . . . . 15
  78.         2.5.3 Filename selection   . . . . . . . . . . . . . . . . . . . 16
  79.         2.5.4 Report length  . . . . . . . . . . . . . . . . . . . . . . 16
  80.       2.6 List Customisation   . . . . . . . . . . . . . . . . . . . . . 16
  81.         2.6.1 Headers, Titles and Include files  . . . . . . . . . . . . 16
  82.         2.6.2 File Sorting   . . . . . . . . . . . . . . . . . . . . . . 18
  83.         2.6.3 Area Sorting   . . . . . . . . . . . . . . . . . . . . . . 18
  84.         2.6.4 Warnings, Indications, Descriptions and Comments   . . . . 18
  85.         2.6.5 Import of File_Id.Diz  . . . . . . . . . . . . . . . . . . 19
  86.       2.7 Miscellaneous report information   . . . . . . . . . . . . . . 20
  87.         2.7.1 File Information in Lists  . . . . . . . . . . . . . . . . 20
  88.         2.7.2 File Dates   . . . . . . . . . . . . . . . . . . . . . . . 21
  89.         2.7.3 File Age   . . . . . . . . . . . . . . . . . . . . . . . . 22
  90.         2.7.4 Duplicate Filenames  . . . . . . . . . . . . . . . . . . . 22
  91.  
  92.       3.0 Parameter Specifications   . . . . . . . . . . . . . . . . . . 24
  93.       3.1 Commandline parameters   . . . . . . . . . . . . . . . . . . . 24
  94.       3.2 Configuration file Parameters  . . . . . . . . . . . . . . . . 24
  95.         3.2.1 Parameters with global scope   . . . . . . . . . . . . . . 25
  96.         3.2.2 Parameters with local scope  . . . . . . . . . . . . . . . 25
  97.       3.3 Compiling the IPF lists  . . . . . . . . . . . . . . . . . . . 26
  98.  
  99.  
  100.     
  101.                                                                Contents  ii
  102.  
  103.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  104.     
  105.     
  106.     
  107.       4.0 Sample of Getting organised  . . . . . . . . . . . . . . . . . 27
  108.       4.1 Downsort   . . . . . . . . . . . . . . . . . . . . . . . . . . 27
  109.       4.2 BinkleyTerm  . . . . . . . . . . . . . . . . . . . . . . . . . 28
  110.  
  111.       5.0 Packaging and Installation   . . . . . . . . . . . . . . . . . 29
  112.       5.1 Availability   . . . . . . . . . . . . . . . . . . . . . . . . 29
  113.       5.2 RUN-time material  . . . . . . . . . . . . . . . . . . . . . . 29
  114.       5.3 Source material  . . . . . . . . . . . . . . . . . . . . . . . 30
  115.       5.4 Installation   . . . . . . . . . . . . . . . . . . . . . . . . 30
  116.       5.5 Dependencies and restrictions  . . . . . . . . . . . . . . . . 31
  117.       5.6 Storage and Performance  . . . . . . . . . . . . . . . . . . . 31
  118.       5.7 Problems   . . . . . . . . . . . . . . . . . . . . . . . . . . 32
  119.       5.8 Wishlist   . . . . . . . . . . . . . . . . . . . . . . . . . . 32
  120.  
  121.       6.0 Internals  . . . . . . . . . . . . . . . . . . . . . . . . . . 33
  122.       6.1 Development Environment  . . . . . . . . . . . . . . . . . . . 33
  123.       6.2 Program Organisation   . . . . . . . . . . . . . . . . . . . . 33
  124.       6.3 Main Data Organisation   . . . . . . . . . . . . . . . . . . . 35
  125.         6.3.1 Area and File Information  . . . . . . . . . . . . . . . . 35
  126.         6.3.2 Block fonts  . . . . . . . . . . . . . . . . . . . . . . . 36
  127.  
  128.       Appendix A.  History of changes  . . . . . . . . . . . . . . . . . 38
  129.       7.1 Version 6.4  . . . . . . . . . . . . . . . . . . . . . . . . . 38
  130.       7.2 Version 6.3  . . . . . . . . . . . . . . . . . . . . . . . . . 39
  131.       7.3 Version 6.2  . . . . . . . . . . . . . . . . . . . . . . . . . 40
  132.       7.4 Version 6.1  . . . . . . . . . . . . . . . . . . . . . . . . . 42
  133.       7.5 Version 6.0  . . . . . . . . . . . . . . . . . . . . . . . . . 44
  134.  
  135.       Appendix B.  World-wide use of Downsort  . . . . . . . . . . . . . 47
  136.  
  137.       Appendix C.  Sample Lists  . . . . . . . . . . . . . . . . . . . . 48
  138.       9.1 ALL-list   . . . . . . . . . . . . . . . . . . . . . . . . . . 48
  139.       9.2 GBL-list   . . . . . . . . . . . . . . . . . . . . . . . . . . 48
  140.       9.3 NEW-list   . . . . . . . . . . . . . . . . . . . . . . . . . . 48
  141.       9.4 FILES.BBS  . . . . . . . . . . . . . . . . . . . . . . . . . . 49
  142.       9.5 ORPhan list  . . . . . . . . . . . . . . . . . . . . . . . . . 49
  143.  
  144.       Appendix D.  Downsort for non-Maximus users  . . . . . . . . . . . 50
  145.  
  146.       Appendix E.  Sample Configuration File   . . . . . . . . . . . . . 52
  147.  
  148.  
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.     
  164.                                                               Contents  iii
  165.  
  166.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  167.     
  168.     
  169.     
  170.     PREFACE
  171.  
  172.     DOWNSORT is a program which can produce many kinds of lists of
  173.     available download files for Bulletin Board Systems especially but not
  174.     restricted to running MAXIMUS, and it can maintain your FILES.BBS
  175.     files.  There is a 32-bits version for OS/2 Warp and a 16-bits version
  176.     that runs undoe both DOS and OS/2.
  177.  
  178.     The different types of lists are each for a specific audience (online
  179.     bulletin board users, file-requestors, SYSOP) or purpose (allfiles,
  180.     recent acquisitions, warning lists for duplicates and orphans, OKfiles,
  181.     etc.).
  182.  
  183.     Within each type there are many ways to customize the contents and
  184.     format
  185.  
  186.     The following list-types are supported:
  187.  
  188.     ■  user-lists
  189.        ∙  ALL-list with a complete overview per filearea ('ALLFILES'),
  190.           including an hierarchical division and area summary.
  191.        ∙  GBL-list for a file-overview without area grouping.
  192.        ∙  IPF-formats of ALL-list and NEW-list with 'hypertext' technique.
  193.        ∙  HTML-formats of ALL-list and NEW-list, also with hypertext links.
  194.        ∙  NEW-list with the most recent files ('NEWFILES').
  195.        ∙  BBS-list, like a NEW-list but in compiled MEC format with a
  196.           colorful overview for online users.
  197.        ∙  TOP-nnn download list of most frequently downloaded files.
  198.  
  199.     ■  SYSOP-lists:
  200.        ∙  FILES.BBS: updated, sorted and with a 'typical' header.
  201.        ∙  ORPHAN-list as a help with file management.
  202.        ∙  DUP-list with a list of duplicate files.
  203.        ∙  OKFile for file-requests.
  204.        ∙  USR-list: with a user-specified line contents and layout.
  205.           Macro-like variables represent actual file- and area-items to be
  206.           shown.  Ideal to build REXX procedures for file maintenance, but
  207.           can be used for many other purposes.
  208.  
  209.     The lists can be customized to a very high extend to present your
  210.     system as you desire it to be seen by your users, such as BLOCK titles,
  211.     insertion of customised texts, file- and area-selections, special
  212.     handling of areas on CDROM, different sorting regimes, import of
  213.     file-descriptions from File_Id.Diz, variable line lenghts with text
  214.     wrapping or truncation, etc, etc..
  215.  
  216.     An unlimited number of lists in any combination can be produced in a
  217.     single run of Downsort.  Downsort does its job extremely fast, and is
  218.     designed to work with very large file collections.
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.     
  227.                                                                 Preface  iv
  228.  
  229.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  230.     
  231.     
  232.     
  233.     1.0 INTRODUCTION
  234.  
  235.     This chapter is to make you familiar with Downsort.  Some history,
  236.     objectives, and other 'background' information are provided.
  237.  
  238.  
  239.     1.1 HISTORY
  240.  
  241.     Downsort was originated in 1987 as a program for personal use.  I
  242.     founded the Bulletin Board PC-Square and as SYSOP I wanted a daily
  243.     overview of my download material for the users in the form a Bulletin.
  244.     The program name is related to the SORTing of the collection of
  245.     DOWNloadable files, in DOWNward time-stamp sequence and an online
  246.     Bulletin was the only list that was produced at that time.  PC-Square
  247.     was running BinkleyTerm and OPUS under DOS, and file-requesting was not
  248.     so popular then.
  249.  
  250.     Now PC-Square runs with OS/2, BinkleyTerm and MAXIMUS CBCS.  I'm not
  251.     SYSOP anymore but still strongly involved.  As a contribution to
  252.     PC-Square and the large community of international SYSOPs running
  253.     Bulletin Boards with MAXIMUS CBCS, and in the highly appreciated spirit
  254.     of BinkleyTerm, I decided to upgrade my Downsort program to the current
  255.     software.  During the past years a lot of improvements and extensions
  256.     have been made: many user-configurable options for many more output
  257.     formats then the original Downsort.
  258.  
  259.     The only dependency of Downsort on MAXIMUS CBCS is a parameter-file
  260.     FAREA.DAT, which is created with a MAXIMUS utility (SILT[P]), and which
  261.     itself can be used without actually running MAXIMUS!  If you like
  262.     Downsort, but don't run Maximus, see "Appendix D.  Downsort for
  263.     non-Maximus users" on page 50  for an suggested procedure in this case.
  264.  
  265.     "Appendix A.  History of changes" on page 38 gives an impression of
  266.     recent history.
  267.  
  268.     Downsort is developed in an OS/2 environment, and the 32-bits version
  269.     is the primary program (OS/2 version 2.0 or newer).  But a
  270.     'family'-application is available too, which runs under all versions of
  271.     OS/2 and DOS!
  272.  
  273.     Downsort is in its 10-th year of development and has entered a period
  274.     where life becomes more and more complicated.  While adding new
  275.     features, I have tried to maintain compatibility.  This is a main cause
  276.     of complications.  Maybe in one of the newer versions I have to leave
  277.     this compatibility in favour of maintainability and user-friendliness.
  278.     In anticipation of this, please do not use undocumented features (if
  279.     there are!), or styles of usage that are not described in this
  280.     document.  On the other hand, don't be shy in experimenting with the
  281.     many possible combinations of parameters and list formats to obtain the
  282.     format that you and your users like the most!
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.     
  290.                                                             Introduction  1
  291.  
  292.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  293.     
  294.     
  295.     
  296.     1.2 PURPOSE AND OBJECTIVES
  297.  
  298.     Downsort is designed for the following purposes:
  299.  
  300.     1. Produce different overviews of files which are available for
  301.        download by online users of the Bulletin Board and by
  302.        File-requestors.  QUICK and EASY file retrieval is the main goal for
  303.        the lists.  Therefore many list-types and within a type several
  304.        variations should be available for SYSOP and users.
  305.  
  306.     2. Should not disclose files to users (file-requesters) without
  307.        positive agreement by SYSOP.
  308.  
  309.     3. Detect discrepancies between the contents of FILES.BBS and the
  310.        corresponding download directory, such as:
  311.  
  312.        ■  The directory contains so called orphan-files, which have no
  313.           descriptive entry in FILES.BBS.
  314.  
  315.        ■  FILES.BBS contains entries of which the file is in not in the
  316.           directory (is 'offline').  This may be on purpose!
  317.  
  318.     4. Must be able to be run unattended (typically overnight).
  319.  
  320.  
  321.  
  322.     1.3 QUICK START
  323.  
  324.     I understand that you are eager to use Downsort and are reluctant to
  325.     make a comprehensive study of this document.  You are lucky: for a
  326.     first impression this is not needed.  If you have Maximus installed,
  327.     you can run Downsort without any commandline parameters or
  328.     configuration file.  This will produce a default output file
  329.     ALLFILES.LST.
  330.  
  331.     If this does not work, then you can take either of the following
  332.     actions:
  333.  
  334.     ■  Start Downsort from the directory in which the Maximus control file
  335.        FAREA.DAT is located.
  336.     ■  Set the environment variable 'MAXIMUS' with the pathspec of Maximus'
  337.        master control file MAX.PRM (this is where FAREA.DAT is located
  338.        too).
  339.     ■  Provide an ASCII file named Downsort.Cfg in the directory from where
  340.        you start Downsort.  This file needs a single line like:
  341.  
  342.          FAREADAT   d:\MAX\FAREA.DAT
  343.  
  344.        Specify the correct drive and path for your Maximus main directory!
  345.  
  346.     Now look at the results and gradually make yourself familiar with the
  347.     vast amount of other features of Downsort by reading the sample
  348.     Downsort.Cfg, which contains all possible parameters with for each a
  349.     brief explanation.
  350.  
  351.  
  352.     
  353.                                                             Introduction  2
  354.  
  355.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  356.     
  357.     
  358.     
  359.     Before reporting supposed bugs or missing features, please read this
  360.     document and the file 'DOWNSORT.FAQ' carefully!
  361.  
  362.  
  363.     1.4 REGISTRATION AND SHAREWARE FEE
  364.  
  365.     Downsort is a Shareware product with a modest fee of 15 US-dollars.
  366.  
  367.     I hate restrictions in features (cripple-ware), and other tricks to
  368.     stimulate users to register, but I have strong suspicion that
  369.     registration is far below the actual use.  Therefore Downsort tries to
  370.     stimulate registration in a very modest way.  Downsort is uncrippled,
  371.     full featured, but I may eventually decide to quit further work on
  372.     Downsort if the registration response remains considerably below
  373.     alledged actual use.
  374.  
  375.     I want to avoid the excessive fees relative to the Shareware
  376.     contribution that banks commonly charge for international money
  377.     transfers or cheques to be made payable, and the services of credit
  378.     card companies are not free of charge too.  To keep the shareware
  379.     contribution to a reasonable minimum, I urge you to send a short "thank
  380.     you for Downsort" letter with carefully hidden 15 US-Dollars in
  381.     banknotes (no cheques please).  You will be obliged to perform this
  382.     incredibly pleasant task only once, and what is 15 dollars on a
  383.     lifetime?  You may grasp the chance to tell me your strictly private
  384.     opinion about Downsort or to report your requirements or remarks!
  385.  
  386.     Please address your letter to:
  387.  
  388.      R. Hamerling
  389.      Hogelandseweg 67
  390.      4132 CV  Vianen
  391.      The Netherlands
  392.  
  393.     The equivalent of 15 US-Dollars in banknotes of another currency is
  394.     welcome too, but please only in a 'strong' currency (Deutsche Marken,
  395.     UK-pounds, Francs Françaises, etc.), please round up for exchange
  396.     rates!  For those of you with a Dutch bank account it may be more
  397.     convenient to pay the fee (25 Guilders) into the Postbank on my account
  398.     2087285.
  399.  
  400.     Soon after your money has arrived you will receive a personal 'key'
  401.     which will change the signature of Downsort as proof that you are a
  402.     registered user.
  403.  
  404.     If you are running Downsort on your Bulletin Board as service to your
  405.     users, and have it available for download and/or file-request, and you
  406.     appreciate to be mentioned, I'll be happy to add your name and system
  407.     to the reference list.
  408.  
  409.  
  410.  
  411.  
  412.  
  413.  
  414.  
  415.     
  416.                                                             Introduction  3
  417.  
  418.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  419.     
  420.     
  421.     
  422.     1.5 WARRANTY AND SUPPORT
  423.  
  424.     The regular warranty for Shareware applies: none.  If you read the
  425.     summary of changes you must conclude that I listen to your complaints
  426.     and suggestions.
  427.  
  428.     Requests for new features or changes are welcome.  However your
  429.     registration status takes part in my decision to accept these and
  430.     assign their priority.
  431.  
  432.     I am monitoring the international echos 'MUFFIN' and 'OS2BBS'.  You may
  433.     find discussions of general interest concerning Downsort there.
  434.  
  435.  
  436.     1.6 ACKNOWLEDGEMENTS
  437.  
  438.     I would like to thank the many users and testers that contributed with
  439.     constructive remarks and encouraging appraisals.
  440.  
  441.     I also would like to thank the regular users (SYSOP's of Bulletin
  442.     Boards) who made Downsort much more popular than I ever dreamed of!  A
  443.     collection of geographically dispersed Boards can be found in "Appendix
  444.     B.  World-wide use of Downsort" on page 47.
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469.  
  470.  
  471.  
  472.  
  473.  
  474.  
  475.  
  476.  
  477.  
  478.     
  479.                                                             Introduction  4
  480.  
  481.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  482.     
  483.     
  484.     
  485.     2.0 USER'S GUIDE
  486.  
  487.     This chapter explains the features of Downsort.  Parameter
  488.     specifications will be covered in "3.0 Parameter Specifications" on
  489.     page 24.
  490.  
  491.  
  492.     2.1 INITIAL SETUP
  493.  
  494.     When you are going to use Downsort for the first time, you have to make
  495.     a number of decisions.  Below you'll find a kind of check-list, which
  496.     is setup to help you with a logical sequence of tasks to make the use
  497.     of Downsort succesful.  It does NOT give detailed specifications, these
  498.     can be found in "3.0 Parameter Specifications" on page 24.  The
  499.     specifications will be put into a configuration file such as the sample
  500.     'Downsort.Cfg', which contains information about:
  501.  
  502.     1. Data Collection
  503.  
  504.        File information will be collected from:
  505.        ■  Download path-information and area attributes from FAREA.DAT.
  506.        ■  File information from download directories.
  507.        ■  FILES.BBS files for file descriptions.
  508.  
  509.     2. File selection
  510.  
  511.        Reporting of file-information can be limited by:
  512.        ■  Area group with a set of areaINcludes and/or areaEXcludes for
  513.           selection for special interest groups.
  514.        ■  Explicit exclusion by specification of filespecs (wildcards).
  515.        ■  Number of files or period (days, weeks or months) to be reported.
  516.        ■  Exclusion of CDROM-based areas with "CDROM NoList"
  517.  
  518.     3. List Customisation
  519.  
  520.        The layout of the lists can be jazzed-up with:
  521.        ■  BLOCK-title(s) and BLOCK-font.
  522.        ■  Use of high-ASCII characters in Downsort's headers.
  523.        ■  TopTitle, SubTitle, BottomTitle, Include (logo-) file.
  524.        ■  Sorting sequence of areas (unsorted, name, group,
  525.           include-sequence).
  526.        ■  Sorting sequence of files (unsorted, filename, filedate).
  527.        ■  Truncation, wrapping and indenting of file descriptions.
  528.        ■  Import of file description from File_id.Diz.
  529.        ■  Customised Message- and Warning-texts in the language which
  530.           suites your audience best.
  531.        ■  Handling of Avatar codes in comment lines (strip or mimic).
  532.  
  533.     4. List Type Selection
  534.  
  535.        Downsort can produce the following report types for you (all in one
  536.        run).
  537.        ■  BBS-list for online users of MAXIMUS.
  538.        ■  NEW-list(s) for a list of the most recent files.
  539.        ■  ALL-list(s) for a complete overview in a file-group per area.
  540.  
  541.     
  542.                                                             User's Guide  5
  543.  
  544.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  545.     
  546.     
  547.     
  548.        ■  GBL-list(s) for a complete overview over area-boundaries.
  549.        ■  TOP-list(s) to show the most frequently Downloaded files.
  550.        ■  IPF-list(s) same as ALL-list, but in a different presentation
  551.           format (VIEW-able under OS/2).
  552.        ■  HTM-list(s) same as ALL-list and NEW-list, but in a HTML-format
  553.           viewable by any HTML browser.
  554.        ■  DUP-list(s) for a list of possibly duplicate filenames.
  555.        ■  ORPHAN-report for SYSOP use.
  556.        ■  OKFile(s) for File-requests.
  557.        ■  USRFile(s) for special purposes, designed to create .CMD or .BAT
  558.           files for maintenance of file-areas by Sysop.
  559.        ■  Updated FILES.BBS files.
  560.  
  561.     The sample Downsort.Cfg file (see "Appendix E.  Sample Configuration
  562.     File" on page 52) contains defaults and explanations to help you with
  563.     the parameter specifications.
  564.  
  565.     Below you'll find a more detailed instruction.
  566.  
  567.  
  568.     2.2 RUNTIME CONSIDERATIONS
  569.  
  570.     You may want to know something about the conventions and use of files
  571.     and directories by Downsort.
  572.  
  573.     ■  All files that are used for read-only are opened 'shared'.  So even
  574.        when a file is in use (e.g. by Maximus or Squish), it can be
  575.        accessed by Downsort without causing problems for others.
  576.  
  577.     ■  When a Maximus-related specification is missing Downsort uses
  578.        defaults, and if necessary searches for additional information first
  579.        in the current directory and if not found in the Maximus base
  580.        directory (e.g. FAREA.DAT, COMPRESS.CFG).
  581.  
  582.     ■  If no explicit configuration file is specified on the commandline,
  583.        then 'DOWNSORT.CFG' is first searched in the current directory, then
  584.        in the 'home'-directory of Downsort (from where it is started), then
  585.        in the home directory of Maximus.
  586.  
  587.        Note: Under DOS the actual home-directory of Downsort will not be
  588.        found if it is not the current directory or not in the PATH
  589.        environment variable.
  590.  
  591.     ■  Include files (specified with the -I parameter on the xxxFileList
  592.        line) are first searched in the current directory, then in the
  593.        home-directory of Downsort.
  594.  
  595.     ■  When generating an IPF-list Downsort copies DOWNSORT.BMP from its
  596.        home-directory to the destination directory of the IPF list.  For
  597.   |    the HTM-List it copies DOWNSORT.GIF to the destination directory.
  598.  
  599.   | ■  Although multiple occurences of Downsort may run at the same time,
  600.   |    in some cases this is not desired.  Downsort offers 2 ways to handle
  601.   |    concurrency:
  602.   |    ∙  After startup a file DOWNSORT.BSY is created in Downsort's home
  603.  
  604.     
  605.                                                             User's Guide  6
  606.  
  607.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  608.     
  609.     
  610.     
  611.   |       directory (or the current directory).  You can test for the
  612.   |       existence of this file to prevent concurrent execution if you
  613.   |       think this is undesirable.  However this method is not fail-safe
  614.   |       with system crashes: the file DOWNSORT.BSY may exists even when
  615.   |       Downsort is not active.
  616.   |    ∙  The 32-bit OS/2 version detects by itself if another instance of
  617.   |       Downsort is running in the system.  The keyword 'WaitTime' in
  618.   |       Downsort.Cfg is used to decide what to do if this is the case:
  619.   |       -  A negative value means proceed, don't care about concurrency:
  620.   |          ignore other active instances of Downsort.  This is the
  621.   |          default.
  622.   |       -  A zero value forces this Downsort to terminate immediately if
  623.   |          any other Downsort is running (rc 640).
  624.   |       -  A positive value lets this instance of Downsort wait up to the
  625.   |          specified number of seconds until another Downsort in the
  626.   |          system terminates.  When this happens within the specified
  627.   |          period, the current instance will resume normally, otherwise
  628.   |          this instance will terminate (rc 640).
  629.  
  630.   |       Most of the time, but certainly if you let Downsort update your
  631.   |       Files.Bbs, it is recommended to have only one active Downsort at
  632.   |       a time!
  633.  
  634.     It is recomended to put Downsort in its own directory, have all your
  635.     configuration and include files in this directory and run Downsort with
  636.     this directory as the current default directory.
  637.  
  638.  
  639.     2.3 DATA COLLECTION
  640.  
  641.  
  642.  
  643.     2.3.1 FAREA.DAT
  644.  
  645.     A MAXIMUS file 'FAREA.DAT' is required by Downsort.  However it is not
  646.     mandatory to run MAXIMUS!  See "Appendix D.  Downsort for non-Maximus
  647.     users" on page 50 for a suggested procedure to use Downsort without
  648.     running Maximus.
  649.  
  650.     If you run Downsort in a directory without FAREA.DAT, or FAREA.DAT
  651.     cannot be found via the 'MAXIMUS' environment variable, then you should
  652.     specify the filespec for FAREA.DAT.  This allows you to specify a
  653.     different FAREA.DAT file than the one that is used by your MAXIMUS!
  654.     With SILT[P] you may build a special FAREA.DAT for exclusive use by
  655.     Downsort, with different, less, or even more directories!  Probably
  656.     much more convenient is the use of AreaGroups with AreaINclude and/or
  657.     AreaEXclude in Downsort.Cfg to limit the contents of the lists to a
  658.     group of areas, that you want to report together, while you use the
  659.     regular FAREA.DAT.
  660.  
  661.     In addition files may explicitly excluded during the data collection
  662.     process by specification of a number of filespecifications (wildcards
  663.     allowed).
  664.  
  665.  
  666.  
  667.     
  668.                                                             User's Guide  7
  669.  
  670.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  671.     
  672.     
  673.     
  674.     If Downsort reports a memory constraint (only expected under DOS, see
  675.     also "5.6 Storage and Performance" on page 31), you may use these
  676.     techniques as circumvention: exclude one or more of the file areas and
  677.     rerun Downsort.
  678.  
  679.  
  680.     2.3.2 DOWNLOAD DIRECTORY
  681.  
  682.     Information about file existence, size and date is collected by
  683.     scanning the download directory of an area.  The Download Path is
  684.     obtained from FAREA.DAT.
  685.  
  686.     CDROM-based areas may be excluded from a scan: data collection is slow
  687.     and the information does not change.
  688.  
  689.  
  690.     2.3.3 FILES.BBS
  691.  
  692.     Downsort uses the information in FAREA.DAT to locate the description
  693.     files, usually called FILES.BBS.  So either the ListFile specification
  694.     in FAREA.DAT, or the download directory to locate them (Maximus
  695.     default).
  696.  
  697.  
  698.     2.4 LIST TYPE SELECTION
  699.  
  700.     Downsort can produce several types of output reports, indicated by type
  701.     of list.  The following list types are available (all list types may be
  702.     generated in multiple variants within one run of Downsort, i.c. with a
  703.     single directory scan!).
  704.  
  705.  
  706.     2.4.1 ALL-LIST
  707.  
  708.     A list of all downloadfiles by area.  Files of the same area are listed
  709.     in groups, separated by imbedded headers with area-name, and
  710.     -description.  Actual status information is provided in the area-header
  711.     as well: area-filecount and -bytecount, and latest acquisition (date
  712.     and file-name).
  713.  
  714.     At the end a SUMMARY report shows per area: area-title, file-count,
  715.     byte-count, and totals.
  716.  
  717.     The list can be limited by number or period, so that it effectively
  718.     gets the same contents as a NEW-files, but in the format of an
  719.     ALL-files list.  The numbers in area-header and summary report show
  720.     only what is available for the particular privilege.
  721.  
  722.     You might copy the summary report in ALLFiles to a separated file.  A
  723.     REXX-procedure 'DOWNSUM.CMD' is provided to do this automatically for
  724.     you.
  725.  
  726.  
  727.  
  728.  
  729.  
  730.     
  731.                                                             User's Guide  8
  732.  
  733.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  734.     
  735.     
  736.     
  737.     2.4.2 GBL-LIST
  738.  
  739.     Similar to ALL-list, but where ALL-list gives the files in groups per
  740.     area, the GBL-list ignores area-boundaries and gives a single group.
  741.     It contains an extra column with the area-code for each file.  It
  742.     contains no area-summary.
  743.  
  744.     SYSOP may choose which of both is suitable to make available to users,
  745.     and which to use for himself (or even both).
  746.  
  747.     The GBL-list can be used in stead of the ALL-list if your users prefer
  748.     searching in the list without having to bother about area-organisation.
  749.     Although one of the original purposes of the GBL-list was checking for
  750.     duplicate files, there is also a special report for this particular
  751.     purpose (see "2.4.9 DUP-list" on page 11).
  752.  
  753.  
  754.     2.4.3 HTM-LIST AND HTN-LIST
  755.  
  756.     The HTM-list has the same contents as ALL-list but in a different
  757.     format.  The HTN-list is the equivalent of the NEW-list.  Useful for
  758.     user who are familiar with HTML-file browsers.
  759.  
  760.     Note: For performance reasons the output of HTMFileList is split in an
  761.     overview part and a file for each division and area, with hyperlinks.
  762.     The name of the sublists are <$cxxyyyy>.HTM, in which:
  763.  
  764.     c    Letter 'A' for area-lists and 'D' for division indexes.
  765.     xx   Division level (hexadecimal)
  766.     yyyy Record number in FAREA.DAT (Downsort internal value)
  767.  
  768.     These files are stored in the same directory as the main list-file.
  769.     This has some minor inconveniences if you want to
  770.  
  771.         generate several HTMFileLists and
  772.         keep all the files together.
  773.  
  774.     Better specify a separate directory for each of the HTMFileLists you
  775.     generate with Downsort.
  776.  
  777.     A file Downsort.Gif will be imbedded on the title-page of each HTM
  778.     List.  This is in addition to what you specify with title-lines and
  779.     include file.  A sample Downsort.Gif is provided, the name is
  780.     hard-coded but you may replace the contents with your own logo.  During
  781.     the generation of HTM-files this file is copied to the destination
  782.   | directory (if specified) of the generated HTM-list.
  783.  
  784.   | If you are running an Internet server and want to use the HTMFileList
  785.   | to generate download commands, then you need to use the LinkPathSubst
  786.   | keyword.  With this keyword a hypertext reference is generated for
  787.   | every file in the list, and the original path is translated into a
  788.   | reference to a resource on an Internet setver.  You may have hypertext
  789.   | links for one group of areas on one server while having links to
  790.   | another server for other areas.
  791.  
  792.  
  793.     
  794.                                                             User's Guide  9
  795.  
  796.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  797.     
  798.     
  799.     
  800.   | Examples:
  801.  
  802.   |     original file on your BBS     Internet server resource specification
  803.   |     -------------------------     ---------------------------------------
  804.   |     d:\files\dwnsrt64.zip         http://www.server-1/bbs/dwnsrt64.zip
  805.   |     d:\files\doc\max\max.prn      ftp://www.server-2/bbs/doc/max/max.prn
  806.  
  807.   | To support this, you need to specify in Downsort.Cfg:
  808.  
  809.   |     LinkPathSubst   d:\files   http:/www.server-1/bbs
  810.   |     LinkPathSubst   e:\files   ftp:/www.server-2/bbs
  811.  
  812.   | The need only to specify the prefix 'difference', and you may specify
  813.   | as many LinkPathSubst keywords as needed in Downsort.Cfg, one per line.
  814.   | In case of 'overlapping' path specifications, specify for the orginal
  815.   | path the most significant (longest) string first.  If no matching
  816.   | original path is found, then no reference is generated.
  817.  
  818.   | After Downsort generated the HTMFileList for the first time, you want
  819.   | to browse this list to check if the resource references are as desired!
  820.  
  821.  
  822.     2.4.4 IPF-LIST AND IPN-LIST
  823.  
  824.     Same contents as ALL-list and NEW-list but in a different format.
  825.  
  826.     Useful for users who are familiar with VIEW under OS/2 (version 1.2 or
  827.     higher under Presentation Manager).  This file has the format of an
  828.     input-file for the Information Presentation Facility Compiler (IPFC).
  829.     Downsort produces information that can be compiled only with the IPF
  830.     Compiler of the OS/2 Program development Toolkit (2.0 or higher).  The
  831.     result however can be VIEWed under OS/2 1.3!
  832.  
  833.  
  834.     2.4.5 BBS-LIST
  835.  
  836.     This is a list of downloadfiles that became recently available on your
  837.     system.  File selection is on date, but for presentation the list may
  838.     be sorted on date, newest first or on filename.
  839.  
  840.     The list contains compiled MECCA control sequences, for direct use in
  841.     MAXIMUS bulletins: It might be a good idea to put a translated [onexit]
  842.     string, which translates into: ^OFpath.  When a user exits from the
  843.     BBS-list bulletin, it will fall back to the exit-bulletin.
  844.  
  845.     The length of the file (number of file-entries) may be limited by
  846.     parameters:
  847.  
  848.     ■  file-count
  849.     ■  file age in days, weeks or months (30 days)
  850.  
  851.     If neither specified it will contain all available files in all
  852.     download directories.
  853.  
  854.  
  855.  
  856.     
  857.                                                            User's Guide  10
  858.  
  859.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  860.     
  861.     
  862.     
  863.     To make it easy for you to build a complete MAXIMUS bulletin-file a
  864.     user-provided header is included preceding the list and a trailer at
  865.     the end of the list.  Header and trailer can be built by SYSOP, and may
  866.     contain any information and bulletin-control sequences (a sample is
  867.     provided).
  868.  
  869.  
  870.     2.4.6 NEW-LIST
  871.  
  872.     Basically the same list as the BBS-list, but in simple text format.
  873.     This list is suitable for regular file-requestors as brief overview of
  874.     the latest additions, updates or replacements.
  875.  
  876.  
  877.     2.4.7 TOP-LIST
  878.  
  879.     If you have a download count field in your file descriptions in
  880.     Files.Bbs in the form of [nnn] or (nnn), then Downsort can produce a
  881.     list with the most frequently downloaded files.
  882.  
  883.     Downsort does not update these download count fields!
  884.  
  885.  
  886.     2.4.8 ORPHAN-LIST
  887.  
  888.     This is a list of all files in download directories for which there is
  889.     no entry in any FILES.BBS file of all areas which have this directory
  890.     specified as download path.  The report contains date, area-name and
  891.     area-path of the orphan.  The entries are sorted on area and filename.
  892.  
  893.     Not reported are the files that match all FileEXclude specifications.
  894.     Normally you would exclude FILES.*, *.BAK, DIR.?BS and SYSTEM*.?BS.
  895.  
  896.     If you have more than 1 area pointing to the same download directory,
  897.     but with different FILES.BBS files, the orphans are reported for the
  898.     first of these areas only.
  899.  
  900.     Note: If there is an entry for a file in FILES.BBS without a
  901.     description, the file is NOT considered to be an Orphan!
  902.  
  903.  
  904.     2.4.9 DUP-LIST
  905.  
  906.     Simple report of possibly duplicate files over the areas.  The format
  907.     is basically the same as the GBL-list, but only files with the same
  908.     filename are reported.  'Offline' files are included in the check,
  909.     orphans are not!
  910.  
  911.     With the 'DupNameSize' keyword in Downsort.Cfg you may indicate how
  912.     many characters have to be considered in the compare of the filename.
  913.     The default is the whole filename (8 characters), extension and path
  914.     are always excluded from the compare.  If you specify a smaller number,
  915.     then you may catch version-numbers, which are generally put at the end
  916.     of the name.  For example: if you specify MaxDupName 6, then
  917.     DWNSRT59.ZIP and DWNSRT60.ZIP are reported as duplicate, while this
  918.  
  919.     
  920.                                                            User's Guide  11
  921.  
  922.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  923.     
  924.     
  925.     
  926.     would not be the case if the default of 8 was used for the filename
  927.     compare.
  928.  
  929.     Please note that the DUP-list may not always contain what you expect.
  930.     It can be more or less, for example:
  931.  
  932.     ■  Downsort looks primarily at filenames only (extension is of second
  933.        importance, an explicit path is ignored).
  934.     ■  You may have explicitly excluded areas from the search.
  935.     ■  You have duplicates in 'orphan'-state.
  936.  
  937.     These circumstances may give 'false' signals or hide duplicates!  You
  938.     may need a file-finder-utility to search for the 'partner'-file in one
  939.     of the directories with a higher privilege.
  940.  
  941.     There are only a few other parameters applicable to this list.  The
  942.     output is sorted on filename, unless you specify a different sorting
  943.     regime (date or area, and within area on filename of FILES.BBS
  944.     sequence).  All user-titles are left out.
  945.  
  946.     Suppression of reporting files with equal filenames and different
  947.     extensions is possible with the "NonDupEXT" keyword in Downsort.Cfg.
  948.     You specify pairs of extensions.  Two files with equal filename and one
  949.     of each having an extension specified as 'pair' will not be reported as
  950.     duplicate.  For example, if you specify:
  951.  
  952.        NonDupEXT  SDN  SDA
  953.  
  954.     then file pairs xyz.SDN and xyz.SDA will not be reported in the
  955.     DUP-list.
  956.  
  957.     This pair-exclusion can also be used for more than 2 extensions, but
  958.     the exclusion works only for pairs of files.  So then you must specify
  959.     as many pairs as can be formed.  For example if you want to exclude
  960.     file combinations like xyz.IDX xyz.DAT and xyz.EXT, then you should
  961.     specify:
  962.  
  963.        NonDupEXT  IDX DAT  IDX EXT  DAT EXT
  964.  
  965.     Warning: The check on duplicates by Downsort works only when you
  966.     specify all  possible pairs of extensions!  If you fail to specify any
  967.     possible pair, the Dup-list may contain false signals.
  968.  
  969.     Multiple pairs may be specified on a line, and multiple lines are
  970.     allowed.
  971.  
  972.  
  973.     2.4.10 OKFILE
  974.  
  975.     List of path specifications for file-requests.  Each outputline has the
  976.     format:
  977.  
  978.     <downpath>\*.*
  979.  
  980.  
  981.  
  982.     
  983.                                                            User's Guide  12
  984.  
  985.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  986.     
  987.     
  988.     
  989.     in which <downpath> is the directory that contains downloadable files.
  990.     The lines are sorted on pathspec of the download directory.
  991.  
  992.     Titles etc. do not apply, but a file may be included, which will
  993.     generally be a list of 'magic' names and corresponding filespec.
  994.  
  995.     Note: Newer versions of BinkleyTerm can use the file base of Maximus to
  996.     find a file even faster by specifying:
  997.  
  998.     *<maximus>\maxfiles.idx
  999.  
  1000.     Note: The former 'long' type of OKfile list of Downsort version 6.2 or
  1001.     older cannot be created with an OKFileList anymore.  In stead you could
  1002.     use the USRFileList.  The sample Downsort.Cfg contains an example of
  1003.     this format.
  1004.  
  1005.  
  1006.     2.4.11 USR-LIST
  1007.  
  1008.     A very versatile list with a 'user specified format'.  It is primarily
  1009.     designed to build a batch-file for file maintenance purposes, with a
  1010.     single output line per file.  But of course you may use it for any
  1011.     purpose that suites you.
  1012.  
  1013.     You specify a 'model-line' or 'template', that may contain any text and
  1014.     some symbolic variables that represent the values of some file
  1015.     information items:
  1016.  
  1017.     %$    Access Control String of the File Area
  1018.     %2    Duplicate flag: 1=no duplicate file, 2=duplicate file
  1019.     %A    Areaname (fully qualified, INcluding division prefixes)
  1020.     %C    File Creation date
  1021.     %D    most recent of Lastwrite and Creation Date of the file
  1022.     %F    Filename.ext
  1023.     %H    File age in days (most recent of lastWrite and Creation Date is
  1024.           taken).
  1025.     %N    File Download count (value of nnn in [nnn] from file description
  1026.           in FILES.BBS).  If no [nnn] found, the value of %N will be 0.
  1027.     %P    Path specification of download directory
  1028.     %S    File Size
  1029.     %U    Unqualified areaname (EXcluding division prefixes)
  1030.     %W    File lastWrite date (see "2.7.2 File Dates" on page 21)
  1031.     %Z    File lastAccess date (see "2.7.2 File Dates" on page 21)
  1032.  
  1033.     This type of list is designed to offer a user-controlled two-stage file
  1034.     maintenance.  Just an example: if you want to get rid of all files
  1035.     older than 2 years, you let Downsort produce REXX-procedure with for
  1036.     each file a line as follows:
  1037.  
  1038.        if %H > 730 then erase %P%F
  1039.  
  1040.     Of course you may limit the output-list with area-group, etc., like all
  1041.     regular xxxFileLists of Downsort.  And if you think Downsort might
  1042.     generate too many or too few of these statements, you can always have a
  1043.     manual check and modify the list before actually executing the
  1044.  
  1045.     
  1046.                                                            User's Guide  13
  1047.  
  1048.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  1049.     
  1050.     
  1051.     
  1052.     procedure!  It may help if you expand the USRmodel statement with a
  1053.     REXX-comment, like:
  1054.  
  1055.       if %H>730 erase %P%F   /* LastWriteDate=%W  CreationDate=%C */
  1056.  
  1057.  
  1058.  
  1059.     2.4.12 REBUILD FILES.BBS
  1060.  
  1061.     New "FILES.BBS" type of file may be (re-)created, one for every area.
  1062.     The contents of the file-information will be about the same as the
  1063.     original FILES.BBS, but with the following notes:
  1064.  
  1065.     ■  A header is generated with area-name, -title and optionally the
  1066.        Access Control String of the area.  Also the total amount of files
  1067.        and bytes and the most recently acquired file in this area is part
  1068.        of the header information.  The header will look a bit different if
  1069.        any area has a long name (more than 3 characters) than when all
  1070.        areas have short names.
  1071.     ■  Wild-card specifications in the original FILES.BBS are not
  1072.        propagated to the new FILES.BBS.
  1073.     ■  The file description is kept internally as a single string of about
  1074.        2 KBytes (Maximus 3.00 supports up to 1024 bytes!)  When creating
  1075.        FILES.BBS files, this will be the file format (single record per
  1076.        file-entry).  The original FILES.BBS may contain a single line
  1077.        description, or multi-line descriptions.  When encountering
  1078.        multi-line descriptions in input-FILES.BBS, Downsort concatenates
  1079.        the separate description lines with a single intermediate space up
  1080.        to a maximum of 2 KBytes.  This will be the output format.
  1081.     ■  Comments in FILES.BBS will be preserved only when the Keep-Sequence
  1082.        option is used (specify /K on the FilFilePath line of Downsort.Cfg).
  1083.  
  1084.     Special attention is requested for the following:
  1085.  
  1086.     ■  Downsort from version 5.7 recognises its own headerlines with the
  1087.        characters: <-><δ><backspace><backspace><blank> for each of its
  1088.        header-lines, and will skip all lines starting with this sequence
  1089.        during the data collection phase.
  1090.     ■  You can include your own file with the /I-option on the FILFilePath
  1091.        line in Downsort.Cfg in the header of FILES.BBS.  All lines in the
  1092.        include-file for FILES.BBS output will be prefixed by Downsort with
  1093.        the 5-character sequence mentioned above to make sure that these
  1094.        will also be 'refreshed' each time you run Downsort.
  1095.     ■  The destination of FILES.BBS-files is not by definition the same as
  1096.        the origin!  An output path can be specified in the configuration
  1097.        file.  If you don't specify an output-path on the FILFilePath line
  1098.        in Downsort.Cfg, the output will replace the original FILES.BBS (the
  1099.        old will be renamed to FILES.BAK).  If you specify an output path
  1100.        the output will be put in the specified directory and the filenames
  1101.        will have the format "areaname.BBS".
  1102.  
  1103.        Entries of 'offline' files can be removed with Downsort.
  1104.  
  1105.     Manual checking or post-processing by some other program may follow
  1106.     Downsort, after which the files might be put back on the MAXIMUS
  1107.  
  1108.     
  1109.                                                            User's Guide  14
  1110.  
  1111.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  1112.     
  1113.     
  1114.     
  1115.     specified position.
  1116.  
  1117.  
  1118.     2.5 DATA SELECTION
  1119.  
  1120.     During the data collection phase of Downsort, files are selected on
  1121.     several criteria.  Generally speaking not more information is collected
  1122.     than needed for all lists in a single run of Downsort.
  1123.  
  1124.     During the list creation phase a further file selection may take place.
  1125.  
  1126.     All lists are primarily created from the file information.  This means
  1127.     for example that if a selection is such that no files of a certain area
  1128.     fall within the list criteria, the files of that area will not appear
  1129.     in any list.
  1130.  
  1131.  
  1132.     2.5.1 ACCESS CONTROL STRING
  1133.  
  1134.     MAXIMUS has a suffisticated access control system for online users.
  1135.     Although Downsort up to version 6.1 supported privilege and lock
  1136.     control to 'simulate' the access of different users, it does not
  1137.     anymore.  The even more suffisticated access control in MAX version
  1138.     3.00 is considered a bit of overkill for the relatively simple task of
  1139.     Downsort: create couple of file-lists!  Nevertheless different lists
  1140.     can be made for different user-classes with the area-grouping, and the
  1141.     Access Control String can be shown to users, even to those users that
  1142.     have not access to some areas of which the list gives the contents.
  1143.  
  1144.  
  1145.     2.5.2 AREA SELECTION
  1146.  
  1147.     There are several ways to perform area selection:
  1148.  
  1149.     1. With "CDROM NoList" you may exclude all CDROM-based areas from the
  1150.        collection phase, so these will not be reported in any list.  The
  1151.        FileArea specification should contain the "Type CD" or the
  1152.        equivalent "Type Slow Staged Readonly" to be handled by Downsort as
  1153.        CDROM drive.
  1154.  
  1155.     2. With AreaGroup definitions with individual sets of AreaINclude
  1156.        and/or AreaEXclude statements you define logical groups of areas by
  1157.        name.  For each individual list you may select a single group.
  1158.  
  1159.     3. FAREA.DAT file needs not be the regular complete FAREA.DAT used by
  1160.        your online Maximus system.
  1161.  
  1162.     You should realise that the selection has the above sequence: Make sure
  1163.     you don't restrict the collection phase too much.  The list
  1164.     specifications may further reduce the contents of each list.
  1165.  
  1166.  
  1167.  
  1168.  
  1169.  
  1170.  
  1171.     
  1172.                                                            User's Guide  15
  1173.  
  1174.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  1175.     
  1176.     
  1177.     
  1178.     2.5.3 FILENAME SELECTION
  1179.  
  1180.     Downsort scans download directories and collects data of all files
  1181.     (except those with the hidden or system attribute).  With the keyword
  1182.     FileEXclude in Downsort.Cfg, you may indicate which files you want to
  1183.     exclude from processing by Downsort, based on filename.  With one or
  1184.     more filespecs, wildcards allowed, all files with matching filespec
  1185.     will be excluded during the data collection phase, regardless of the
  1186.     area.  The current implementation supports only the traditional 8.3
  1187.     filename.ext format, no long names and no explicit path.
  1188.  
  1189.     In versions of Downsort before 5.9 the hardcoded specification of
  1190.     certain 'system' files has been removed, and these filespecs should now
  1191.     be specified in Downsort.Cfg.  The sample Downsort.Cfg does contain
  1192.     these specifications.  I suggest to leave that line asis and add one or
  1193.     more new lines for your own use.  Warning: FileEXcluded files will even
  1194.     not appear in the FILES.BBS  (re-)created by Downsort!
  1195.  
  1196.  
  1197.  
  1198.     2.5.4 REPORT LENGTH
  1199.  
  1200.     For lists that are meant to show the latest file-information only
  1201.     (BBS-, NEW-, ALL-, and TOP-list), the length of the list can be limited
  1202.     to a maximum number of file-entries or to file-age in days, weeks or
  1203.     months.
  1204.  
  1205.  
  1206.     2.6 LIST CUSTOMISATION
  1207.  
  1208.  
  1209.  
  1210.     2.6.1 HEADERS, TITLES AND INCLUDE FILES
  1211.  
  1212.     There are several ways to customize the appearance of the lists for
  1213.     Downsort.  All items in the following list are optional, but the
  1214.     sequence in the reports is fixed and as listed:
  1215.  
  1216.     Pre-Title   Lines that should appear as the very first lines of your
  1217.                 lists.  Any text may be specified.  ' ~'-characters (tilde)
  1218.                 will be treated as full-size required blanks, and
  1219.                 ('`')-characters (open quote) as half-size required blanks,
  1220.                 mainly to manually align (center) the text in these lines.
  1221.                 There is no automatic centering.  You may have to
  1222.                 experiment a little.
  1223.  
  1224.     TITLE       A number of short titles (8-12 characters per line), that
  1225.                 will be magnified to big BLOCK-letters.  There are 5
  1226.                 block-fonts to choose from.  Not all characters are
  1227.                 supported and lower-case will be translated to upper-case.
  1228.                 Tilde and open-quote translation will take place here also.
  1229.                 Multiple lines for a block-title can be specified.  There
  1230.                 is no default block-title.
  1231.  
  1232.     Include-file A text-file to be included.  There will be no manipulation
  1233.  
  1234.     
  1235.                                                            User's Guide  16
  1236.  
  1237.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  1238.     
  1239.     
  1240.     
  1241.                 of the contents of this file.  This include-file may be all
  1242.                 you need to obtain a fully customized list.  For the
  1243.                 IPF-list this include file will most likely have to contain
  1244.                 IPF tags for proper formatting, for the HTM-list it should
  1245.                 have HTM formatting tags, for the OK-file it will be a list
  1246.                 of 'magic' name entries.
  1247.  
  1248.     Sub-Title   Lines that should appear immediately following the
  1249.                 block-title.  If an include-file is specified, this will be
  1250.                 included between title and sub-title.
  1251.  
  1252.     BottomLine  Line(s) that should appear at the end of the list.  These
  1253.                 will be followed by the 'signature' of Downsort (date,
  1254.                 version, etc,).
  1255.  
  1256.     With 'TitleFont' you specify the font to be used for the BLOCK title.
  1257.     If specified as 0, the BLOCK-title will NOT be generated at all.
  1258.  
  1259.     The BLOCK-title and Pre-, Sub-, and Bottom-titles are used for all
  1260.     reports identically, there is no such thing as an 'individual' title
  1261.     specification for each report.  However the Include-file may be
  1262.     different for each report.  If you want to build more than 1 list but
  1263.     with different 'headings' or no headings at all, you better forget the
  1264.     Title-options.  In stead make heading-files and use the Include option
  1265.     of the individual list specifications.
  1266.  
  1267.     Note: Exceptions:
  1268.  
  1269.     1. None of the above does apply to the BBS-list.  As it will generally
  1270.        be desirable to imbed (compiled) MECCA control sequences in this
  1271.        type of lists, this report will include dedicated top and bottom
  1272.        files (if available in the current default directory).  These files
  1273.        must be called Downsort.HDR (header) and Downsort.TRL (trailer).
  1274.  
  1275.     2. The ORPHAN and DUPLICATE report will not contain any user-titles.
  1276.  
  1277.     Recommendation: File-requestors appreciate a header with a clear
  1278.     indication of the source of the reports.  Many Bulletin Boards use
  1279.     FILES or ALLFILES as 'magic' name for file requests, but that is not
  1280.     very distinctive when collecting lists of different boards!  So use
  1281.     Downsort's facilities to generate a block-title with your system-name,
  1282.     or an include file with some kind of logo.
  1283.  
  1284.     Note: Specification details and samples can be found in Downsort.Cfg.
  1285.  
  1286.     Some SYSOPs do not like to confront their users with access control.
  1287.     In most headers there will be a line with the Access Control String.
  1288.     This may be suppressed.
  1289.  
  1290.  
  1291.  
  1292.  
  1293.  
  1294.  
  1295.  
  1296.  
  1297.     
  1298.                                                            User's Guide  17
  1299.  
  1300.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  1301.     
  1302.     
  1303.     
  1304.     2.6.2 FILE SORTING
  1305.  
  1306.     The file-entries in the lists can be sorted on different keys:
  1307.  
  1308.     ■  Filedate
  1309.  
  1310.     ■  Filename
  1311.  
  1312.     ■  Sequence of FILES.BBS
  1313.  
  1314.     The default sorting sequence depends on the type of list.  Some lists
  1315.     do not support all of these sorting keys.
  1316.  
  1317.     Note: File sorting has a local scope.  It can be specified for to each
  1318.     listtype individually.
  1319.  
  1320.  
  1321.     2.6.3 AREA SORTING
  1322.  
  1323.     The order in which the areas are presented in the lists can be
  1324.     specified:
  1325.  
  1326.     ■  Order of FAREA.DAT
  1327.     ■  Alphabetically: sorted on unqualified areaname
  1328.     ■  Order of areaINclude statements in the Areagroup
  1329.     ■  Group-order: sorted on fully qualified areaname
  1330.     ■  Keep order of FAREA.DAT, implies no sorting.
  1331.  
  1332.     The difference between 'alphabetic' and 'group' sort is the use of the
  1333.     areaname.  With 'alphabetic' sort the areaname is taken without the
  1334.     division prefix (if you have any), while the 'group'-sort takes the
  1335.     fully qualified name, and effectively sorts areas alphabetically on
  1336.     then on areaname itself.
  1337.  
  1338.     If Include-order is specified, but you did not specify an AreaGroup
  1339.     with AreaINclude statements, then the order falls back to 'Keep'-order:
  1340.     sequence of Farea.Dat.
  1341.  
  1342.     The AreaOrder specification has a global scope.  It applies to every
  1343.     lists where the areaname is significant, including summaries in ALL-,
  1344.     IPF-lists and HTML-lists.
  1345.  
  1346.     Default sorting order is 'Group'.
  1347.  
  1348.  
  1349.     2.6.4 WARNINGS, INDICATIONS, DESCRIPTIONS AND COMMENTS
  1350.  
  1351.     ■  There are two options for long file descriptions (those that do not
  1352.        fit on a single line):
  1353.        ∙  Truncation at end-of-line
  1354.        ∙  Wrapping to multiple lines
  1355.  
  1356.        Both options are available for all lists (except Files.Bbs output!),
  1357.        but the defaults vary with the type of the report.  If wrapping is
  1358.        specified continuation lines will start in the same column as the
  1359.  
  1360.     
  1361.                                                            User's Guide  18
  1362.  
  1363.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  1364.     
  1365.     
  1366.     
  1367.        description on the first line unless a non-zero indentation is
  1368.        specified.
  1369.  
  1370.     ■  Orphan description: Text that will be reported in the description
  1371.        column of a file, when for this file no entry in FILES.BBS could be
  1372.        located.
  1373.  
  1374.        Default: "---------- Orphan ---------".
  1375.  
  1376.     ■  Not-Found description: Text for the description column when the
  1377.        file-entry was found in FILES.BBS, but there was no description
  1378.        present.
  1379.  
  1380.        Default: "--- no description available ---".
  1381.  
  1382.     ■  Offline description: Text that will replace file-size and file-date,
  1383.        when an entry for this file was found in FILES.BBS, but the file
  1384.        could not be located in the download directory.
  1385.  
  1386.        Default: " - offline - ".
  1387.  
  1388.     ■  Comments in FILES.BBS (mostly used for additional description for
  1389.        groups of files) will be listed when no sorting is specified (the /K
  1390.        option for ALL-, IPF-, HTM- and FIL-lists).
  1391.  
  1392.        When Downsort encounters Avatar screen handling codes in FILES.BBS
  1393.        these are stripped of or partially imitated in the output lists
  1394.        (unless AVAstrip No is specified in Downsort.Cfg).  Typical screen
  1395.        handling commands (cursor movement, color settings) are just
  1396.        stripped, others (repeating characters of patterns) are imitated.
  1397.  
  1398.     ■  Size of a VIEW-page in IPF-list: The IPF-list of areas with more
  1399.        than 200 file entries will be splitted into 'parts' to prevent the
  1400.        IPF-compiler message 'page is too big'.  But if you have many long
  1401.        descriptions, or wish smaller parts, the page-size can be altered
  1402.        with a parameter on the IPFFileList line in Downsort.CFG.
  1403.  
  1404.        Default: 200.
  1405.  
  1406.     ■  Pages size of HTML-formatted lists: For HTM-list the same applies as
  1407.        to IPF lists.
  1408.  
  1409.  
  1410.  
  1411.     2.6.5 IMPORT OF FILE_ID.DIZ
  1412.  
  1413.     The File_id.Diz contents of an archive, if present, can be imported.
  1414.     With the keyword DIZimport you can select if import should take place
  1415.     when the description in Files.Bbs is missing, shorter than you like,
  1416.     allways or never.  The original descriptions in Files.Bbs are
  1417.     preserved, unless you perform an inplace rebuild of Files.Bbs AND the
  1418.     import selection criterium is met AND File_Id.Diz was imported
  1419.     succesfully.  Remember that you can build new Files.Bbs files in
  1420.     another directory than the original and if you choose to replace
  1421.     Files.Bbs Downsort copies the current Files.Bbs into Files.Bak, so you
  1422.  
  1423.     
  1424.                                                            User's Guide  19
  1425.  
  1426.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  1427.     
  1428.     
  1429.     
  1430.     can recover if you don't like the results.
  1431.  
  1432.     The type of archive will be determined with the help of a special
  1433.     configuration file 'Compress.Cfg'.  This is the same as used by
  1434.   | Maximus, Squish and some other programs of the Maximus family.  An
  1435.   | optimised version is provided as 'Compress.Dwn', which may be activated
  1436.   | via the 'CompressCfg' keyword in Downsort.Cfg.  The corresponding
  1437.     extract programs will be called by Downsort and thus must be available
  1438.   | in the current PATH for succesful use of this feature of Downsort.  The
  1439.   | unarchivers must also be of the proper type: the OS/2 version of
  1440.   | Downsort will check the program type and will reject improper types
  1441.   | (like DOS and Presentation Manager programs).  If a DOS-program is
  1442.   | specified it will issue an error message and will not import
  1443.   | File_Id.Diz from the corresponding archive.
  1444.  
  1445.   | There is no check under DOS!  It is pretty unlikely that A DOS user
  1446.   | will specify an OS/2 unarchiver!  But in that case the import of
  1447.   | File_Id.Diz will just fail.
  1448.  
  1449.     The imported contents of File_Id.Diz may be modified slightly by
  1450.     Downsort.  Only the first 2 KB bytes are read, then linefeeds and some
  1451.     other 'nasty' characters are removed and consecutive blanks reduced to
  1452.     a single blank.
  1453.  
  1454.     You must realise that extracting File_Id.Diz significantly reduces the
  1455.     speed of Downsort, especially the 'Force' option!
  1456.  
  1457.  
  1458.     2.7 MISCELLANEOUS REPORT INFORMATION
  1459.  
  1460.  
  1461.  
  1462.     2.7.1 FILE INFORMATION IN LISTS
  1463.  
  1464.     1. Dates are marked with a 'new'-indicator: a '*' if the file is only
  1465.        since a week on this system, and a '+' if it is since a month.
  1466.        Filedates later than the current system date are marked '-'
  1467.        (negative age).
  1468.  
  1469.     2. In every outputfile the filename, MAXIMUS-area name, file-size and
  1470.        -date, and file-description from FILES.BBS is listed.  A report-line
  1471.        will never display more than 79 characters (or the explictly
  1472.        specified linelength by means of the -L parameter).
  1473.  
  1474.        The file-description will be multi-line in ALL-, IPF-, HTM- and
  1475.        GBL-list if it is longer than would fit on the line, a word-wrapping
  1476.        technique is used for readability (line-split on word boundary).
  1477.        The description is truncated at end of line in BBS-list and
  1478.        NEW-list.
  1479.  
  1480.        The -T option will force truncation of the description in all
  1481.        reports, the -W option will allow multi-line descriptions in all
  1482.        reports.  When wrapping is used, continuation lines will normally be
  1483.        aligned on the start position of the description.  This may be
  1484.        modified with an indentation option.
  1485.  
  1486.     
  1487.                                                            User's Guide  20
  1488.  
  1489.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  1490.     
  1491.     
  1492.     
  1493.        If a filename is found in FILES.BBS, but no accompanying
  1494.        description, a "--- no description available ---" will be put in
  1495.        place.  An alternative text may be specified with Downsort.CFG.
  1496.  
  1497.        Files for which there is no entry in the FILES.BBS (Orphans) will
  1498.        not appear in regular lists.  You may specify the 'Orphan Adopt'
  1499.        flag (-O) to force these being listed, but it is considered good
  1500.        practice only with FILFilePath.  Downsort will report the file with
  1501.        a file description, to be specified with the OrphanDesc keyword in
  1502.        Downsort.Cfg.  As a result of specification of -O in FILFileList,
  1503.        any following runs will list these files as regular files (the
  1504.        orphans were adopted, weren't they?).  Filedate selection is ignored
  1505.        for orphans, but AreaGroup is respected.
  1506.  
  1507.        Note: If you want the orphans to appear, you MUST also generate an
  1508.        ORP-list in the same Downsort run!
  1509.  
  1510.     3. '- offline -" in stead of file-size and file-date is reported if
  1511.        FILES.BBS contains an file-entry while the file is not in the
  1512.        corresponding directory.
  1513.  
  1514.     4. With "CDROM NoScan" you can suppress the scan of directories on
  1515.        CDROM.  In that case the files in the area will be reported only
  1516.        with the information in Files.Bbs.  If a filearea on CDROM has
  1517.        also the "DateList" attribute, then Downsort tries to collect the
  1518.        date and size information from Files.Bbs, otherwise filesize and
  1519.        filedate are zero (the date will be reported as 00-00-80).
  1520.        Currently Downsort supports only one format: first filesize then
  1521.        filedate, and filedate must be in American format 'mm/dd/yy' (any
  1522.   |    separator character).  The reason is that the date format
  1523.   |    information is not in FAREA.DAT but in MAX.PRM, which is not used by
  1524.   |    Downsort.
  1525.  
  1526.   |    On output Downsort reconstructs the DateList format of Files.Bbs.
  1527.   |    With version 6.3 of Downsort the -L parameter is not supported
  1528.   |    anymore.
  1529.  
  1530.   |    Note: filedate are in Files.Bbs and consequently you have specified
  1531.   |    the area for Maximus as 'Type DateList', then you should specify
  1532.   |    'CDROM NOSCAN' in Downsort.Cfg.  You may want to force Downsort to
  1533.   |    add filesize and filedate in Files.Bbs by omitting 'CDROM NOSCAN',
  1534.   |    but you should do this only once!
  1535.  
  1536.  
  1537.  
  1538.     2.7.2 FILE DATES
  1539.  
  1540.     One of the functions of Downsort is sorting on file date.  Since the
  1541.     introduction of HPFS in OS/2 version 1.2, there is not one single
  1542.     file-date anymore!  A file on an HPFS volume has different values for:
  1543.  
  1544.     ■  Creation date
  1545.     ■  LastAccess date
  1546.     ■  LastWrite date
  1547.  
  1548.  
  1549.     
  1550.                                                            User's Guide  21
  1551.  
  1552.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  1553.     
  1554.     
  1555.     
  1556.     The date you see normally in DIR-listings is the LastWrite date.  Most
  1557.     SYSOPs will have noticed that ZMODEM-uploads and file-attaches give
  1558.     file-dates corresponding to the (LastWrite-) date of the sending
  1559.     system.  And most utilities handle only this 'single' date.  That means
  1560.     that old ZMODEM-uploaded files are generally not on top of the
  1561.     acquisition lists.
  1562.  
  1563.     But HPFS stores the date of arrival on your system (Creation) as well.
  1564.     Downsort handles most recent of Creation and LastWrite date for
  1565.     sorting, but the lists (see below) contain the 'old fashioned'
  1566.     LastWrite date.  This has the following consequences:
  1567.  
  1568.     ■  A new acquisition is on top of lists, if that list is sorted on
  1569.        date, and are marked in the lists as new by a flag for an 'age' of a
  1570.        week or a month.
  1571.     ■  The listed file-date is the 'ordinary' date.  So users can judge for
  1572.        themselves if the file is 'new' for them as well.
  1573.  
  1574.     Note: The LastAccess date is not very relevant for the purposes of
  1575.     Downsort, although SYSOP may see when it was last downloaded.
  1576.  
  1577.     Downsort is delivered with a simple DIR-like utility 'HPFSDATE' to show
  1578.     the three dates of a file on a HPFS volume.
  1579.  
  1580.     Files with 'future' file dates will be indicated with a '-' flag in the
  1581.     lists.  These files will never appear in: BBS-, and NEW-lists.
  1582.  
  1583.  
  1584.     2.7.3 FILE AGE
  1585.  
  1586.     The age of a file is the calculated difference between local system
  1587.     date and most recent of LastWrite date and Creation Date, truncated to
  1588.     a whole number of days.  A file that arrived today is 0 days old, but
  1589.     at 00:01 a file that arrived 2 minutes ago is already 1 day old.  This
  1590.     effect is visible on HPFS volumes under OS/2 (see "2.7.2 File Dates" on
  1591.     page 21)  On FAT volumes the age of a file will generally be a
  1592.     different value.
  1593.  
  1594.     The accuracy of the calculation relies on the proper setting of your
  1595.     system clock.  Since local time is used the setting of the timezone
  1596.     will not be of influence.
  1597.  
  1598.  
  1599.     2.7.4 DUPLICATE FILENAMES
  1600.  
  1601.     Duplicate filenames will be checked only if the DUP-list is generated.
  1602.     And duplicates will be reported only in the DUP-list.  So duplicate
  1603.     file may appear in regular user-lists, which means:
  1604.  
  1605.     ■  If a filename.ext is encountered more than once in different
  1606.        subdirectories of download files, it will appear that many times in
  1607.        the outputlist.
  1608.     ■  It may happen that a file is reported as orphan in one area, and as
  1609.        duplicate in another.  It is likely that the file is found in a
  1610.        common download directory of more than one area but it is described
  1611.  
  1612.     
  1613.                                                            User's Guide  22
  1614.  
  1615.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  1616.     
  1617.     
  1618.     
  1619.        in the FILES.BBS of a 'secundary' area, but with the wrong
  1620.        extension.
  1621.  
  1622.     Downsort.Cfg gives you some control over detection of duplicates:
  1623.  
  1624.     ■  With the 'NonDupExt' keyword you may suppress certain duplicates.
  1625.     ■  With 'DupNameSize' you may specify how many characters of the
  1626.        filename have to be taken into consideration.
  1627.  
  1628.     See "2.4.9 DUP-list" on page 11 for more details.
  1629.  
  1630.  
  1631.  
  1632.  
  1633.  
  1634.  
  1635.  
  1636.  
  1637.  
  1638.  
  1639.  
  1640.  
  1641.  
  1642.  
  1643.  
  1644.  
  1645.  
  1646.  
  1647.  
  1648.  
  1649.  
  1650.  
  1651.  
  1652.  
  1653.  
  1654.  
  1655.  
  1656.  
  1657.  
  1658.  
  1659.  
  1660.  
  1661.  
  1662.  
  1663.  
  1664.  
  1665.  
  1666.  
  1667.  
  1668.  
  1669.  
  1670.  
  1671.  
  1672.  
  1673.  
  1674.  
  1675.     
  1676.                                                            User's Guide  23
  1677.  
  1678.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  1679.     
  1680.     
  1681.     
  1682.     3.0 PARAMETER SPECIFICATIONS
  1683.  
  1684.     This chapter tells you how to customize the configuration file and what
  1685.     you might specify on the commandline.
  1686.  
  1687.     A sample configuration file (in "Appendix E.  Sample Configuration
  1688.     File" on page 52) is part of the package.  It is annotated to help you
  1689.     with the specification of parameters.
  1690.  
  1691.  
  1692.     3.1 COMMANDLINE PARAMETERS
  1693.  
  1694.     This paragraph deals only with the commandline parameters!
  1695.  
  1696.  
  1697.       [drive:][path]  DOWNSORT  [@filespec] [-H | -Q | -V] [-Ixx]
  1698.  
  1699.  
  1700.     @filespec   The character '@' followed by a complete file
  1701.                 specification of the Downsort configuration file(see "3.2
  1702.                 Configuration file Parameters" for details).  This file
  1703.                 will be used to specify processing parameters.
  1704.  
  1705.                 NOTE: The specification of a configuration file is
  1706.                 mandatory when it is not in the default directory or not
  1707.                 named 'Downsort.Cfg'.
  1708.  
  1709.                 Default: Downsort.Cfg in current default directory.
  1710.  
  1711.     -H -Q -V -Ixx Operating mode
  1712.                 ■  H - Help:  display screen with essential information
  1713.                    about running Downsort, such as the command syntax.  In
  1714.                    that case the program will not take any other action.
  1715.                 ■  Q - Quiet: display only start and finish-message, and
  1716.                    error messages which prevent the program from proceeding
  1717.                    normally.
  1718.                 ■  V - Verbose:  display a lot of progress messages.
  1719.                 If neither -Q nor -V is specified, than the number of
  1720.                 console messages will be 'intermediate': more than -Q, but
  1721.                 less than -V.
  1722.  
  1723.     Ixx - Idle: run Downsort in priority class IDLE, level 'xx' (number in
  1724.                 the range 1..31, default 16).  Applies only to 32-bits OS/2
  1725.                 version.
  1726.  
  1727.                 Default: none
  1728.  
  1729.  
  1730.  
  1731.     3.2 CONFIGURATION FILE PARAMETERS
  1732.  
  1733.     All processing options are specified in the configuration file.  The
  1734.     parameters are only mentioned here for completeness, see "Appendix E.
  1735.     Sample Configuration File" on page 52 for a documented specification
  1736.     sample of a configuration file.
  1737.  
  1738.     
  1739.                                                Parameter Specifications  24
  1740.  
  1741.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  1742.     
  1743.     
  1744.     
  1745.     3.2.1 PARAMETERS WITH GLOBAL SCOPE
  1746.  
  1747.     The parameters below influence the execution of Downsort, or have
  1748.     impact on every list (if it is applicable for that list).
  1749.  
  1750.     ■  Specification of the MAXIMUS CBCS file 'FAREA.DAT'.
  1751.     ■  Exclusion of FileAreas on CDROM (or suppression of directory scan).
  1752.     ■  Import of File-Id.Diz.
  1753.     ■  Explicit file exclusion.
  1754.     ■  Definition of areagroups with areaINclude and areaEXclude
  1755.        combination, specifying generic names of areas of groups of areas
  1756.     ■  Sort order of areas.
  1757.     ■  List title(s) with BLOCK-characters.
  1758.     ■  Use of high-ASCII characters in headers and BLOCK-titles.
  1759.     ■  Pre-titles, Sub-titles and Bottom-lines in 'text' format.
  1760.     ■  Descriptive text of orphans, files without a description and files
  1761.        for which an entry is found in FILES.BBS, but could not be found in
  1762.        the corresponding download directory.
  1763.     ■  Duplicate filename restriction.
  1764.     ■  Stripping of AVATAR graphics sequences from file descriptions and
  1765.        comments in FILES.BBS.
  1766.  
  1767.  
  1768.  
  1769.     3.2.2 PARAMETERS WITH LOCAL SCOPE
  1770.  
  1771.     The parameters below are sub-parameters of the xxxFileList keyword.
  1772.  
  1773.     ■  Area selection by name of an areagroup.
  1774.     ■  Output filename or directory for the output FILES.BBS-lists.
  1775.     ■  Maximum number of file entries in NEW- and BBS-list.
  1776.     ■  File-entry sort sequence (filename or date).
  1777.     ■  Automatic removal of file entries from FILES.BBS of 'not-found'
  1778.        files.
  1779.     ■  Wrap or Truncate long file descriptions, and Indentation of
  1780.        continuation lines.
  1781.     ■  Title Font selection.
  1782.     ■  Suppression of Access Control String.
  1783.     ■  Include textfile in NEW-, ALL-, TOP-, IPF-, HTM- and GBL-lists, and
  1784.        in FILES.bbs.
  1785.  
  1786.     Downsort can generate any number of lists in a single run.
  1787.  
  1788.     A sample configuration file is provided.  A listing of this file is
  1789.     imbedded as "Appendix E.  Sample Configuration File" on page 52.  It
  1790.     contains a complete specification with comments on:
  1791.  
  1792.     ■  which options are available
  1793.     ■  how to specify the options
  1794.  
  1795.     Read and modify the file as you like.  Copy the sample file to a safe
  1796.     place before you start modifying the original Downsort.Cfg!
  1797.  
  1798.  
  1799.  
  1800.  
  1801.     
  1802.                                                Parameter Specifications  25
  1803.  
  1804.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  1805.     
  1806.     
  1807.     
  1808.     3.3 COMPILING THE IPF LISTS
  1809.  
  1810.     IPF-lists have to be processed by the Information Presentation Facility
  1811.     Compiler (IPFC).  This compiler is part of the IBM Programmers
  1812.     Development Toolkit.  You will need version 2.0 or higher.  The
  1813.     following command has to be issued:
  1814.  
  1815.         IPFC  Downsort.IPF  /INF
  1816.  
  1817.     The option "/INF" is needed to obtain a VIEWable file, if not specified
  1818.     a .HLP file will be generated.  Be sure to have the file Downsort.BMP
  1819.     in your current default directory, or in DPATH, as this will be
  1820.     imbedded by the IPF-compiler.  The result of the compilation is a file
  1821.     Downsort.INF, which can be VIEWed with the following command:
  1822.  
  1823.         VIEW  Downsort
  1824.  
  1825.     The names "Downsort", "IPF" and "INF" are used here as sample, actually
  1826.     the filename depends on the specification in the Downsort configuration
  1827.     file, the extensions are the IPFC defaults.
  1828.  
  1829.     If VIEW gives garbled columns and hardly readable block-titles, then it
  1830.     is most likely that you did not install the standard fonts that are
  1831.     delivered with OS/2 (or removed non-proportional fonts).  Start the
  1832.     'control panel utility', select 'installation', 'add fonts'.  Specify
  1833.     in the 'from'-field C:\OS2\DLL (see HELP of control panel).  Now choose
  1834.     at least 1 non-proportional font.
  1835.  
  1836.     Note: IPFC has a number of restrictions that you may encounter,
  1837.     especially when you try to compile large lists:
  1838.  
  1839.     ■  A "Page is too big" message, generally resulting in other errors or
  1840.        warnings to appear as well, means that the 16000 words limit is
  1841.        exceeded.  A file may not contain more than 16000 different items
  1842.        (character strings between blanks or punctuation marks).  There is
  1843.        nothing else you can do than make the list smaller (see "2.5 Data
  1844.        Selection" on page 15 for suggestions).  Sometimes a TRAP 000D
  1845.        occurs with very big lists if you ignore these error messages.
  1846.     ■  Sometimes also "invalid nesting of cgraphics tag" is displayed.
  1847.        Just ignore these!
  1848.  
  1849.  
  1850.  
  1851.  
  1852.  
  1853.  
  1854.  
  1855.  
  1856.  
  1857.  
  1858.  
  1859.  
  1860.  
  1861.  
  1862.  
  1863.  
  1864.     
  1865.                                                Parameter Specifications  26
  1866.  
  1867.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  1868.     
  1869.     
  1870.     
  1871.     4.0 SAMPLE OF GETTING ORGANISED
  1872.  
  1873.     Assume you are runnung MAXIMUS with BinkleyTerm as front end mailer.
  1874.     Suppose you make a distinction for file-requestors between Unknown,
  1875.     Known and Password-Protected (e.g. corresponding to Demoted(Disgrace),
  1876.     Normal and Privileged MAXIMUS users).
  1877.  
  1878.  
  1879.     4.1 DOWNSORT
  1880.  
  1881.     Your downsort.cfg file might contain among others the following
  1882.     specifications:
  1883.  
  1884.     ;                   Assume all areanames with 'normal' ACS start with 'N'
  1885.     ;                   and with 'Privil' ACS start with 'P', higher with 'S'
  1886.     AreaGroup Demoted
  1887.       AreaEXclude N P S
  1888.     AreaGroup Normal
  1889.       AreaEXclude N S
  1890.     AreaGroup Privil
  1891.       AreaEXclude S
  1892.  
  1893.       NEWFileList   Newfiles.Prv  -2m  -SPrivil
  1894.       NEWFileList   Newfiles.Nml  -2m  -sNormal
  1895.       NEWFileList   Newfiles.Dem  -2m  -sDemoted
  1896.       ALLFileList   Allfiles.Prv       -sPrivil
  1897.       ALLFileList   Allfiles.Nml       -sNormal
  1898.       ALLFileList   Allfiles.Dem       -sDemoted
  1899.  
  1900.     This specification will produce the following lists:
  1901.  
  1902.     ■  For file requests of the magic filename NEWFILES a list of the last
  1903.        two months additions to your system.
  1904.        ∙  Newfiles.Dem for unknown file-requestors
  1905.        ∙  Newfiles.Nml for known file-requestors
  1906.        ∙  Newfiles.Prv for Password Protected file-requestors
  1907.  
  1908.        Note that each NEW-list contains only the most recent files, but the
  1909.        contents will generally not be quite the same (depending on your
  1910.        areaIN/EXclude specifications).
  1911.  
  1912.     ■  For file requestors of the magic filename FILES a list with all
  1913.        files (with optional titles via Downsort.CFG specifications):
  1914.        ∙  Allfiles.Dem for unknown file-requestors
  1915.        ∙  Allfiles.Nml for known file-requestors
  1916.        ∙  Allfiles.Prv for Password Protected file-requestors
  1917.  
  1918.        Note that each list is a complete list of what is available to the
  1919.        user of the specific privilege class, but your system will generally
  1920.        contain more files than listed for unknown and known users!
  1921.  
  1922.     In general: files, which the requestor is not supposed to know about
  1923.     due to his access class, will not be on his/her list!
  1924.  
  1925.     Note: The counters on top of the lists indicate what your system has
  1926.  
  1927.     
  1928.                                             Sample of Getting organised  27
  1929.  
  1930.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  1931.     
  1932.     
  1933.     
  1934.     available in total (including higher access classes), so a clever
  1935.     user/file-requester may come up with the question how that is possible:
  1936.     explain that he/she has to earn higher a access class!
  1937.  
  1938.  
  1939.     4.2 BINKLEYTERM
  1940.  
  1941.     In Binkley.Cfg (version 5.9+) you should specify for requests of FILES:
  1942.  
  1943.       Avail        Allfiles.dem
  1944.       KnownAvail   Allfiles.nml
  1945.       ProtAvail    Allfiles.prv
  1946.  
  1947.     You will need an OKfile, which contains something like:
  1948.  
  1949.       *d:\max\maxfiles.idx
  1950.  
  1951.     And have specified the appropriate user access specifications in
  1952.     Binkley.Cfg, like for example:
  1953.  
  1954.       MaxReq        10
  1955.       KnownSec      30
  1956.       ProtMaxTime   50
  1957.  
  1958.     This will result in sending of the appropriate ALLFILES list to every
  1959.     requester of the magic filename: FILES.
  1960.  
  1961.     Of course if the access control string of all download areas is the
  1962.     same, this construction is not needed, but in that case it is unlikely
  1963.     that you have specified KnownAvail and ProtAvail!
  1964.  
  1965.  
  1966.  
  1967.  
  1968.  
  1969.  
  1970.  
  1971.  
  1972.  
  1973.  
  1974.  
  1975.  
  1976.  
  1977.  
  1978.  
  1979.  
  1980.  
  1981.  
  1982.  
  1983.  
  1984.  
  1985.  
  1986.  
  1987.  
  1988.  
  1989.  
  1990.     
  1991.                                             Sample of Getting organised  28
  1992.  
  1993.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  1994.     
  1995.     
  1996.     
  1997.     5.0 PACKAGING AND INSTALLATION
  1998.  
  1999.     This chapter contains information about availability, deliverables,
  2000.     installation and dependencies of Downsort.
  2001.  
  2002.  
  2003.     5.1 AVAILABILITY
  2004.  
  2005.     The most recent version of Downsort is available on the authors
  2006.     homepage: http://users.capitolonline.nl/~nlco5907 on Internet.
  2007.  
  2008.     Downsort will also be distributed in area FWBBS of the Fernwood
  2009.     collection, and to Maximus Support system of Gary Gilmore (see the
  2010.     FidoNet nodelist or search for its homepage on Internet).
  2011.  
  2012.     There is a fair chance you may find a recent version on one of the
  2013.     bulletin boards listed in "Appendix B.  World-wide use of Downsort" on
  2014.     page 47.
  2015.  
  2016.     All you need to run Downsort is bundled in a single archive:
  2017.     "DWNSRTxy.ZIP".  This includes documentation, formatted for browsing or
  2018.     printing (formfeed is the only printer-control) and a sample
  2019.     Downsort.Cfg.
  2020.  
  2021.     Note: 'xy' is the version indication, for example
  2022.     DWNSRT&VERSION.&SUBVERS..ZIP is the version &VERSION..&SUBVERS. runtime
  2023.     package.
  2024.  
  2025.     Also the latest TEST version is available on the authors homepage.  The
  2026.     betatest-archive contains only a 32-bits OS/2-only .EXE-file, the file
  2027.     Downsort.Cfg and a WHATSNEW.xyz file.
  2028.  
  2029.  
  2030.     5.2 RUN-TIME MATERIAL
  2031.  
  2032.     DOWNSORT.DOC        Documentation (this file!).
  2033.     REGISTER.TXT        Chapter of DOWNSORT.DOC concerning the registration
  2034.                         process.
  2035.     WHATSNEW.&VERSION.&SUBVERS.k Summary of amendments to version
  2036.                         &VERSION..&SUBVERS. of Downsort.
  2037.     DOWNSORT.EXE        32-bits execution module for OS/2 (2.0 and higher).
  2038.     DOWNSRT1.EXE        Execution module for OS/2 and DOS (Family
  2039.                         Application)
  2040.     DOWNSORT.ICO        ICON file for DOWNSORT.EXE.
  2041.     DOWNSORT.CFG        Extensively annotated configuration file (still a
  2042.                         'sample').  This file contains comment lines with
  2043.                         instructions how to specify the parameters in the
  2044.                         file.
  2045.     DOWNSORT.HDR        Sample BBS-list header.  You may use this header,
  2046.                         which is only imbedded in the BBS-list, to imbed
  2047.                         text and/or MECCA-sequences.  A good candidate for
  2048.                         the latter would be [onexit], which translates to
  2049.                         ^OFpath.
  2050.     DOWNSORT.TRL        Sample BBS-list trailer.
  2051.     DOWNSORT.BMP        Bitmap for IPF-lists, to be included by the IPF
  2052.  
  2053.     
  2054.                                              Packaging and Installation  29
  2055.  
  2056.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  2057.     
  2058.     
  2059.     
  2060.                         compiler.
  2061.     DOWNSORT.GIF        GIF-file for HTML-lists, included by the browser.
  2062.     DOWNSORT.INC        Sample Include-file for the reports, referenced in
  2063.                         Downsort.Cfg.
  2064.     DOWNSORT.MAG        Sample list of magic names to be included in
  2065.                         OKFile(s).  See BinkleyTerm documentation for
  2066.                         details of its format and contents.
  2067.     DOWNSORT.REX        Sample include file for the USRFileList (REXX
  2068.   |                     prefix).
  2069.   | COMPRESS.DWN        A modified version of the regular 'Compress.Cfg'
  2070.   |                     delivered with Maximus, Squish and other programs.
  2071.   |                     The parameters in Compress.Dwn are optimised for
  2072.   |                     use by Downsort.
  2073.     DOWNSUM.CMD         REXX procedure to split the summary from the
  2074.                         ALLFileList report.
  2075.     HPFSDATE.EXE        Program to display all three timestamps of a file
  2076.                         on an HPFS volume, and optionally reset the
  2077.                         CREATION date to LASTWRITE date (helpful after
  2078.                         moving or copying of files).  Start the program
  2079.                         without options to display command syntax and help.
  2080.                         It is a 32-bits version, for OS/2 2.0+.
  2081.     PACKING.LST         The actual contents of the package (produced with
  2082.                         PKUNZIP -V), added to the ZIP-file after this was
  2083.                         created with the foregoing files of this archive.
  2084.                         This gives at least some authentication!
  2085.  
  2086.     After registration you will receive your personal 'Downsort.Key' file,
  2087.     and a file with an instruction how to install and check its proper
  2088.     working.
  2089.  
  2090.  
  2091.     5.3 SOURCE MATERIAL
  2092.  
  2093.     The source of Downsort is not distributed anymore since version 6.0.
  2094.     The amount of code I ever received as suggested additions or changes is
  2095.     disappointingly small.
  2096.  
  2097.  
  2098.     5.4 INSTALLATION
  2099.  
  2100.     With the following directions you should be able to setup and run
  2101.     Downsort in a very short time.
  2102.  
  2103.     1. Make a separate directory for Downsort, and make it the current
  2104.        default directory every time you run Downsort.  This is a
  2105.        recommendation, not a requirement!
  2106.  
  2107.     2. Unpack the whole Downsort package in this directory.
  2108.  
  2109.     3. Modify (edit) the file Downsort.Cfg to specify your environment and
  2110.        list requirements.  The sample file contains comments to help you
  2111.        with this process.  See "Appendix E.  Sample Configuration File" on
  2112.        page 52 for a printed sample of 'Downsort.Cfg'.  Most specifications
  2113.        are rather obvious.  FareaDat is the most important parameter:
  2114.        Downsort won't do anything useful thing if it cannot find this
  2115.  
  2116.     
  2117.                                              Packaging and Installation  30
  2118.  
  2119.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  2120.     
  2121.     
  2122.     
  2123.        MAXIMUS file.
  2124.  
  2125.     4. You may give Downsort a first shot by just using its name on the
  2126.        commandline, with the command parameter -H or -?.  This will show a
  2127.        brief HELP-screen with the possible commandline parameter
  2128.        specifications.
  2129.  
  2130.  
  2131.  
  2132.     5.5 DEPENDENCIES AND RESTRICTIONS
  2133.  
  2134.     ■  Applies to MAXIMUS CBCS 3.0
  2135.  
  2136.     ■  Requires OS/2 or DOS 3.0+.
  2137.  
  2138.     ■  To convert the IPF-list into VIEW-able format, the IPF-Compiler of
  2139.        the OS/2 Program Development Toolkit is required.
  2140.  
  2141.     ■  The input FILES.BBS files are assumed to contain only
  2142.        [path\]filename.ext (the regular 8.3 format, no support for OS/2
  2143.        HPFS extended format), the remainder of the line is considered as
  2144.        file description.  The filename should be left-aligned (start in
  2145.        position 1).  Heading, comments and blank lines in FILES.BBS are
  2146.        ignored, unless /K is specified on the FilFilePath line of
  2147.        Downsort.Cfg.  In that case comments following the header from a
  2148.        previous run are preserved.
  2149.  
  2150.  
  2151.  
  2152.     5.6 STORAGE AND PERFORMANCE
  2153.  
  2154.     As a rough estimate of the memory requirements of Downsort, use sum of
  2155.     the following elements:
  2156.  
  2157.     ■  Program: about 120KB
  2158.  
  2159.     ■  Each area: 200 Bytes
  2160.  
  2161.     ■  Each file: 48 Bytes for each download file (excluding file
  2162.        descriptions and excluding orphans if no orphan-list is generated)
  2163.  
  2164.     ■  The sum of the file description texts (average 80 bytes/file?)
  2165.  
  2166.     ■  The sum of the comments in FILES.BBS if -K option specified
  2167.  
  2168.     If you hit a memory shortage (DOS real memory!), then you could do one
  2169.     or more of the following:
  2170.  
  2171.     ■  Use AreaGroups with appropriate AreaEXclude or AreaINclude to make a
  2172.        selection of groups (for example make separate OS/2 and a DOS
  2173.        file-lists).  Downsort will not collect information from 'excluded'
  2174.        areas.
  2175.     ■  If you have many orphans: get rid of them or do not generate an
  2176.        orphan report.  Downsort releases orphan-memory during the data
  2177.        collection phase as soon as it knows that a file is an orphan.
  2178.  
  2179.     
  2180.                                              Packaging and Installation  31
  2181.  
  2182.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  2183.     
  2184.     
  2185.     
  2186.     ■  If you have many comment-lines in your FILES.BBS: do not specify /K
  2187.        for ALL- and IPF-lists AND do not activate the FILFilePath parameter
  2188.        in Downsort.Cfg.  Downsort will ignore comments in FILES.BBS when it
  2189.        does not need them for reporting.
  2190.  
  2191.  
  2192.  
  2193.     5.7 PROBLEMS
  2194.  
  2195.     The following known unresolved problems are in this version:
  2196.  
  2197.     ■  none
  2198.  
  2199.  
  2200.  
  2201.     5.8 WISHLIST
  2202.  
  2203.     Downsort is not finished!  There are a number of wishes and
  2204.     requirements of users and myself to include in future releases.  I list
  2205.     them below not in any particular order, but some seem to be more
  2206.     important than others, that differs from SYSOP to SYSOP.  And some are
  2207.     more challenging than others, which depends mainly on the author!  Some
  2208.     wishes don't even make it to be listed below and are implemented
  2209.     immediately!
  2210.  
  2211.     ■  Follow the MAXIMUS development (changes in FAREA.DAT and related
  2212.        structures).
  2213.     ■  User-configurable options for:
  2214.        ∙  week and month indicators
  2215.        ∙  indicator for continuation lines in wrapped descriptions
  2216.        ∙  [selectable] MECCA control in FILES.BBS
  2217.        ∙  font selection for short area-headers
  2218.        ∙  'template' for FILES.BBS headers
  2219.     ■  Logging to file in stead of stdout to obtain a history file of
  2220.        Downsort usage (can now be done with redirection!).
  2221.     ■  Option to keep format of descriptions (for DIZ-imports, ANSI
  2222.        controls) in stead of wrapping continuation lines.
  2223.     ■  Automatic removal of 'bad' files (like .BAK-files, obsolete files,
  2224.        files that are not in FILES.BBS), maybe move them to a special
  2225.        BAD_FILE directory.  Entries in FILES.BBS should be removed
  2226.        accordingly.
  2227.     ■  Conditional file-include, especially for FILES.BBS output.
  2228.     ■  Provide formatting of Files.Bbs with a user-specified template for
  2229.        both header and detail lines.
  2230.     ■  Support for a 'schedule' (e.g. daily 'newfiles', weekly 'allfiles').
  2231.     ■  Support for UNC notation (for LAN configurations).
  2232.     ■  Builtin mechanism to prevent multiple copies of Downsort to run
  2233.        simultaneously (OS/2 version).
  2234.  
  2235.     Remember: Was there ever a time that all your wishes were fulfilled?
  2236.     That was the most boring time of your life, wasn't it?
  2237.  
  2238.  
  2239.  
  2240.  
  2241.  
  2242.     
  2243.                                              Packaging and Installation  32
  2244.  
  2245.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  2246.     
  2247.     
  2248.     
  2249.     6.0 INTERNALS
  2250.  
  2251.      For those of you who are interested how Downsort works and maybe as
  2252.     help for problem determination, this chapter contains some information
  2253.     about Downsort's internal organisation.
  2254.  
  2255.  
  2256.     6.1 DEVELOPMENT ENVIRONMENT
  2257.  
  2258.     There is only a single set of source files.  A compiler variable takes
  2259.     care of the selection between 16- and 32-bits functions where
  2260.     necessary.
  2261.  
  2262.     The 32-bit OS/2 2.0+ only version of Downsort is compiled with IBM
  2263.     C/C++ Tools version 2 and the OS/2 Warp Toolkit.  This version will
  2264.     only run on systems with OS/2 2.0 or higher.
  2265.  
  2266.     The 16-bits family-version of Downsort (for OS/2 1.3 and DOS) is
  2267.     compiled with MicroSoft C compiler version 6.00a.  The generated code
  2268.     is at 80286 level (Compiler option /G2).
  2269.  
  2270.     Downsort has been tested with the following Operating Systems:
  2271.  
  2272.     ■  IBM OS/2 Warp version 3.0
  2273.     ■  IBM PC/DOS version 6.3
  2274.  
  2275.     Before release of any new version, Downsort will have been tested by
  2276.     others on other systems!
  2277.  
  2278.  
  2279.     6.2 PROGRAM ORGANISATION
  2280.  
  2281.     The program is organised as follows:
  2282.  
  2283.     ■  Initialisation:
  2284.        ∙  Read configuration file.
  2285.        ∙  Process commandline parameters.
  2286.        ∙  Perform some cross checking and cumulation
  2287.  
  2288.     ■  Read FAREA.DAT file to collect download pathnames (only of those
  2289.        areas that will participate this time).
  2290.  
  2291.     ■  For each file-area within the area selection criteria:
  2292.  
  2293.        ∙  Read the download subdirectory (with find-file-first/next
  2294.           function).  Take only Normal files: ignore directory entries,
  2295.           Hidden and System files and volume labels.  Exclude files that
  2296.           are specified with the FileEXclude specifications.
  2297.  
  2298.        ∙  For all regular file-entries found in subdirectory:
  2299.           -  Get filename.ext, attribute, date, time, size.
  2300.           -  Obtain file-description from FILES.BBS file.  The path to the
  2301.              FILES.BBS file is (1) obtained from the "ListFile"
  2302.              specification in MAXIMUS FAREA.DAT file, or (2) if not
  2303.              specified from the "DownLoad" specification (among the
  2304.  
  2305.     
  2306.                                                               Internals  33
  2307.  
  2308.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  2309.     
  2310.     
  2311.     
  2312.              download files).
  2313.           -  Add files with explicit path specifications.  Inport
  2314.              File_Id.Diz file if required.
  2315.           -  If there is no orphan reporting required in this run drop
  2316.              orphan entries area-by-area.
  2317.  
  2318.     ■  For the ORP-list:
  2319.  
  2320.        If any orphan found, and the orphan-report is generated, create the
  2321.        orphan report, with the file-entries sorted on (1) area and (2)
  2322.        filename.
  2323.  
  2324.     ■  For the BBS-list:
  2325.        ∙  Sort the files primarily on descending file-timestamp (and
  2326.           secundary on file-name and area-code).
  2327.        ∙  Re-sort the first files on filename if so specified.
  2328.        ∙  Create output file for sorted list of filenames, -descriptions,
  2329.           etc.  The file is placed in the current subdirectory (which
  2330.           generally will be the MAXIMUS directory) with the name
  2331.           Downsort.BBS.
  2332.        ∙  Copy a headerfile (for a customized MAXIMUS bulletin).
  2333.        ∙  Put files in formatted outputfile (filename, area#, date, size,
  2334.           description), but only if description is found in FILES.BBS.
  2335.        ∙  Include a trailerfile in the outputfile (for a customized
  2336.           Bulletin).
  2337.        ∙  Report non-listed files on standard output device (which might be
  2338.           re-directed to printer or disk-file).
  2339.  
  2340.     ■  If specified, put the above file collection in Newfiles.p with
  2341.        similar contents and layout as Downsort.BBS, but without BBS-control
  2342.        sequences, and without including a header and trailer file.
  2343.  
  2344.     ■  If so specified, re-sort files on area and then filename or date,
  2345.        and create an Allfiles list, containing all files
  2346.  
  2347.        At the end of the list, an area summary report is generated.
  2348.  
  2349.     ■  If so specified, re-sort files on filename or date only, and create
  2350.        a GLOBAL file-list, which is an ALLFILES list without area-headers.
  2351.  
  2352.     ■  Generate a list of probably DUPlicate files if specified.
  2353.  
  2354.     ■  Generate a list of download-paths (the OK-file) if specified.
  2355.        (note: it will contain only the paths that participate in this run).
  2356.  
  2357.     ■  If so specified, re-sort files on area and filename, and create for
  2358.        each area a FILES.BBS-type of file.
  2359.  
  2360.     NOTE: Downsort firstly reads a directory for existing files (not
  2361.     Hidden- or System-files, and not Subdirectory or Volumelabel), and then
  2362.     reads FILES.BBS to assign a description to each file.  This means:
  2363.  
  2364.     ■  If more than 1 matching file-specification in FILES.BBS of the
  2365.        involved area is found (note that wild-card specifications in
  2366.        FILES.BBS are supported!), than the first matching description from
  2367.  
  2368.     
  2369.                                                               Internals  34
  2370.  
  2371.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  2372.     
  2373.     
  2374.     
  2375.        FILES.BBS will appear in the lists (new in version 4.5, was 'last'
  2376.        in previous versions of Downsort).
  2377.     ■  Files for which no description is found in FILES.BBS will get "---no
  2378.        description available---" (or the replacement string you specified
  2379.        in your Downsort.Cfg) in the user reports (not in a newly created
  2380.        Files.Bbs).
  2381.     ■  Files for which no matching filename in FILES.BBS is found will be
  2382.        listed in the Orphan report (Downsort.ORP).
  2383.  
  2384.        Files for which there is an entry in FILES.BBS, but a corresponding
  2385.        file is not found in the directory will be reported as 'offline'.
  2386.  
  2387.        In special cases this might become a very large list.  For example
  2388.        if you collect files in a single directory for different areas, all
  2389.        the files of 'the other' areas are reported as orphan.  This will
  2390.        happen for every area, so each file might even be reported many
  2391.        times as orphan!  Since the Orphan-list is now optional (from
  2392.        version 5.0 on), this list can be suppressed.
  2393.  
  2394.        Filenames of Orphans appear only in the other reports when the
  2395.        Adoptflag (-O) is specified.
  2396.  
  2397.  
  2398.  
  2399.     6.3 MAIN DATA ORGANISATION
  2400.  
  2401.  
  2402.  
  2403.     6.3.1 AREA AND FILE INFORMATION
  2404.  
  2405.     Data structure for access to file information via:
  2406.  
  2407.     1. array of file-pointers (for file-sort!)
  2408.     2. pointerchain in file-info structures
  2409.     3. file structure contains pointer to file-description
  2410.     4. file-structure contains pointer to area-information
  2411.     5. Array of area-information
  2412.  
  2413.  
  2414.  
  2415.  
  2416.  
  2417.  
  2418.  
  2419.  
  2420.  
  2421.  
  2422.  
  2423.  
  2424.  
  2425.  
  2426.  
  2427.  
  2428.  
  2429.  
  2430.  
  2431.     
  2432.                                                               Internals  35
  2433.  
  2434.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  2435.     
  2436.     
  2437.     
  2438.  
  2439.     ┌──────┐
  2440.     │  dm  │
  2441.     └──────┘
  2442.         │         Array of pointers to structures with file info
  2443.         │      ┌───────────┬────────────┬───────────── . . . ──────┐
  2444.     (1) └─────>│ *file[0]  │  *file[1]  │ *file[2]                 │
  2445.                └───────────┴────────────┴───────────── . . . ──────┘
  2446.                      │           │            │
  2447.     (2)                                     
  2448.     ┌──────┐     ┌──────┐     ┌──────┐     ┌──────┐
  2449.     │  ca  │ ──> │ next │ ──> │ next │ ──> │ next │ ──> . . .
  2450.     └──────┘     ├──────┤     ├──────┤     ├──────┤
  2451.      (first-     │ file-│     │ file-│     │ file-│
  2452.      element)    │ info │     │ info │     │ info │    . . .
  2453.                  │ [0]  │     │ [1]  │     │ [2]  │
  2454.                  └──────┘     └──────┘     └──────┘
  2455.                      │ │         │  │wildcards│ │
  2456.                      │ └──┐      │  └──┐      │ │
  2457.                      │    │      │ ┌──────────┘ │
  2458.     (3)              v    │      v v   │ ┌──────┘
  2459.                  ┌──────┐ │   ┌──────┐ │ │
  2460.                  │file- │ │   │file- │ │ │(files of
  2461.                  │descr │ │   │descr │ │ │ same area)   . . .
  2462.                  └──────┘ │   └──────┘ │ │
  2463.                           │            │ │
  2464.     (4)                                
  2465.                       ┌──────┐      ┌──────┐      ┌──────┐
  2466.            chain of   │ next │ ───> │ next │ ───> │ next │ ──> . . .
  2467.          area records ├──────┤      ├──────┤      ├──────┤
  2468.                       │ area-│      │ area-│      │ area-│
  2469.                       │ info │      │ info │      │ info │     . . .
  2470.                       │ [0]  │      │ [1]  │      │ [2]  │
  2471.                       └──────┘      └──────┘      └──────┘
  2472.     (5)                                             
  2473.                           │             │             │
  2474.                  ┌───────────┬─────────────┬───────────── . . . ──────┐
  2475.         ┌───────>│ *area[0]  │   *area[1]  │ *area[2]                 │
  2476.         │        └───────────┴─────────────┴───────────── . . . ──────┘
  2477.         │         Array of pointers to structures with area info
  2478.     ┌──────┐
  2479.     │  aa  │
  2480.     └──────┘
  2481.  
  2482.     Schematic overview of Downsort's in-storage database.
  2483.  
  2484.  
  2485.     6.3.2 BLOCK FONTS
  2486.  
  2487.     The block character image is basically a 10x7 matrix (10 vertical and 7
  2488.     horizontal 'pixels').  The pixel-array takes two rows at a time, so
  2489.     that each character can be represented with 5 rows of 7 horizontal
  2490.     'double-pixels'.  Each pixel is displayed as a solid block.
  2491.  
  2492.  
  2493.  
  2494.     
  2495.                                                               Internals  36
  2496.  
  2497.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  2498.     
  2499.     
  2500.     
  2501.              1 2 3 4 5 6 7
  2502.             ┌─┬─┬─┬─┬─┬─┬─┐
  2503.             │-│-│-│-│-│-│-│   line 1    (lower + upper)
  2504.             ├─┼─┼─┼─┼─┼─┼─┤
  2505.             │-│-│-│-│-│-│-│        2    (lower + upper)
  2506.             ├─┼─┼─┼─┼─┼─┼─┤
  2507.             │-│-│-│-│-│-│-│        3    (lower + upper)
  2508.             ├─┼─┼─┼─┼─┼─┼─┤
  2509.             │-│-│-│-│-│-│-│        4    (lower + upper)
  2510.             ├─┼─┼─┼─┼─┼─┼─┤
  2511.             │-│-│-│-│-│-│-│        5    (lower + upper)
  2512.             └─┴─┴─┴─┴─┴─┴─┘
  2513.  
  2514.     Each line is represented by a structure of seven 3-bit fields Each
  2515.     3-bit field represents a basic element:
  2516.  
  2517.      value    char       description
  2518.        0                 (blank)
  2519.        1     ▄           lower half
  2520.        2       ▀         upper half
  2521.        3         █       lower+upper halves
  2522.        4       ▓         gray pattern
  2523.        5     ▌           left part of upper and lower half
  2524.        6       ▐         right part of upper and lower half
  2525.        7         ░       gray pattern
  2526.        8      ▒          gray pattern for not-supported characters
  2527.      9..32               pseudo graphics characters for the open font (5).
  2528.  
  2529.     The pitch is variable ('proportional font': a variable number of
  2530.     horizontal pixels).  Four fonts are provided with different
  2531.     character-image and size:
  2532.  
  2533.     1. 6x5 (three lines of max 5 characters)
  2534.     2. 10x7 (five lines of max 7 characters)
  2535.     3. 8x7 (four lines of max 7 characters)
  2536.     4. 10x7 (reverse video image of the 8x7 font)
  2537.     5. 6x7 (three lines of max 7 characters 'open' characters)
  2538.  
  2539.     The following characters are supported in block-fonts:
  2540.  
  2541.        UPPER case  A..Z
  2542.        LOWER case  a..z  (but will be presented in UPPER case)
  2543.        Digits 0..9
  2544.        _  *  |  .  :  [  ]  (  )  /  \  -  and space
  2545.        Not-supported characters are displayed as space.
  2546.        The ' '-character (blank) represents a 3/4 width space
  2547.        The '~'-character (tilde) a full width space
  2548.        the '`'-character (reverse quote) a half width space
  2549.  
  2550.  
  2551.  
  2552.  
  2553.  
  2554.  
  2555.  
  2556.  
  2557.     
  2558.                                                               Internals  37
  2559.  
  2560.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  2561.     
  2562.     
  2563.     
  2564.     APPENDIX A.  HISTORY OF CHANGES
  2565.  
  2566.     The paragraphs below show a brief history of changes in Downsort.
  2567.  
  2568.     Downsort for MAXIMUS CBCS was developed from an OPUS equivalent (by the
  2569.     same author).  The name 'Downsort' has been maintained, to prevent
  2570.     confusion, the version number is inherited (the last version for OPUS
  2571.     was 3.1).
  2572.  
  2573.  
  2574.     7.1 VERSION 6.4
  2575.  
  2576.     ■  Format of area-lists in HTMFilelist simplified: was table, is now
  2577.        definition list (for better browser performance with long
  2578.        file-lists).
  2579.     ■  Added possibility to add a hyperlink for files in HTML-lists.  The
  2580.        specification for this link is in the form of a path substitution of
  2581.        the local BBS-path by an Internet-resource.  It allows local access
  2582.        as well as HTTP or FTP file transfer.
  2583.     ■  The 32-bits OS/2 version has now a builtin facility to check on
  2584.        concurrent execution, and a new keyword 'WaitTime' to decide what to
  2585.        do when another Downsort is active in the system.  Choices are:
  2586.        proceed, terminate, or wait a user-specified number of seconds.
  2587.     ■  Added support to retrieve file information with both relative and
  2588.        absolute pathname specifications in Farea.Dat.
  2589.     ■  Support for 'Type DateList' uncoupled from 'Type CD'.  This means:
  2590.        of all fileareas with DateList filedate and size is collected from
  2591.        the corresponding Files.Bbs file.  An exception is described in
  2592.        Downsort.FAQ.
  2593.     ■  Extended Downsort.FAQ for online CDROMs.
  2594.     ■  An annotated 'Compress.Dwn' is now included.  This is a modified
  2595.        'Compress.Cfg' as used by Maximus, Squish and others, optimized for
  2596.        use by Downsort.
  2597.     ■  Added specification for PKZIP 2.50 in Compress.Dwn.
  2598.     ■  Removed automatic migration of registration key (6.2 to 6.3 format).
  2599.     ■  Verbose screen output (with -v commandline option) gives some more
  2600.        details of used options and full paths of used configuration files.
  2601.     ■  Startup message added with timestamp for logging purposes.
  2602.     ■  Removed 'summaries of changes' from Downsort.Doc of before version
  2603.        6.0.
  2604.  
  2605.     Bug fixes and internal improvements
  2606.  
  2607.     ■  AreaPaths for sorts and compares now handled upper-case.
  2608.     ■  For file description lines in Files.Bbs with explicit path
  2609.        specifications filesize and filedate are now extracted from
  2610.        Files.Bbs when the area has the Maximus' ListFile area-attribute (no
  2611.        directory access anymore and filesize and filedate not anymore
  2612.        duplicated when rebuilding Files.Bbs).
  2613.     ■  Of a combination of two files where one has a hyphen in the name and
  2614.        the other the same characters up till the hyphen (e.g. 'MM' and
  2615.        MM-xx') the first ('MM') was reported erroneously as orphan, but
  2616.        anymore (bug with a very long beard!!).
  2617.     ■  Import of empty File_Id.Diz now handled as if not present.
  2618.     ■  Intermediate File_Id.Diz's removed even with read-only attributes.
  2619.  
  2620.     
  2621.                                         Appendix A.  History of changes  38
  2622.  
  2623.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  2624.     
  2625.     
  2626.     
  2627.     ■  In OS/2-version of Downsort the unarchivers for File_Id.Diz are
  2628.        type-checked for callability by Downsort (no type-check in the
  2629.        DOS-version!).
  2630.     ■  Semaphore file Downsort.Bsy now kept open until end of run to
  2631.        prevent accidental removal by another process while Downsort is
  2632.        running.
  2633.     ■  Added private stub in OS/2-version to point to DOWNSRT1 for DOS
  2634.        users.
  2635.  
  2636.     Please read also the lines marked '6.4' in Downsort.Cfg.
  2637.  
  2638.     Note: Registered users that skipped version 6.3 should run 6.3 once to
  2639.     have their registration key file updated (see also summary of changes
  2640.     for version 6.3).
  2641.  
  2642.  
  2643.     7.2 VERSION 6.3
  2644.  
  2645.     ■  Defaults and behaviour of Downsort changed for better (first time)
  2646.        use.  The environment variable 'MAXIMUS' is used to locate some
  2647.        system files.
  2648.     ■  2 new list-types added: HTML formatted versions of ALLFILES and
  2649.        NEWFILES.  These are basically the same as IPF- and IPN-lists, but
  2650.        formatted with HTML-tags to be displayed with WebExplorer (tested
  2651.        with 1.1f) or any HTML browser with support for HTML 3.0.  A
  2652.        GIF-file 'Downsort.Gif' is included for the title-page.
  2653.     ■  Import of File_Id.Diz contents now supported.  With the keyword
  2654.        'DIZimport' you can select the cases in which you want import:
  2655.        never, always, with missing description or when it is too short.
  2656.        See section 'Import of File_Id.Diz' in Downsort.Doc for details.
  2657.     ■  New keyword to skip directory scanning of areas on CDROM or to
  2658.        completely ignore these (Maximus: "Type CD").
  2659.     ■  If an area is of "Type DateList" then file size and date will be
  2660.        extracted from the corresponding Files.Bbs files.
  2661.     ■  New keyword to suppress the use of high-ASCII characters by Downsort
  2662.        in headers and BLOCK titles.
  2663.     ■  If the configuration file DOWNSORT.CFG is not found or specified, a
  2664.        default ALLFILES.LST is generated (provided FAREA.DAT is found).
  2665.     ■  Output linelength can now be specified per list individually as
  2666.        extension of the -T and -W parameters.
  2667.     ■  The -L option is not available anymore.  For Files.Bbs the filesize
  2668.        and date will be part of the output if area is of "Type CD
  2669.        DateList".
  2670.     ■  The description in Files.Bbs will not be replaced with a 'dummy'
  2671.        text anymore but can be replaced with the contents of File_Id.Diz.
  2672.     ■  Changes in some layouts for presentation of division hierarchy, in
  2673.        particular the ALLFileList summary.
  2674.     ■  SPLITSUM.CMD improved and renamed to DOWNSUM.CMD.
  2675.     ■  Changed 'Downsort.Key' encoding algorithm.  'Downsort.Key' will be
  2676.        updated automatically (if not 'read-only'!).  Make a copy of the old
  2677.        key to allow fallback to 6.2!
  2678.     ■  Change in Downsort's signature for more apparent registration proof.
  2679.     ■  Added a file DOWNSORT.FAQ for some frequently asked questions and
  2680.        the answers, mainly concerning unexpected or undesired behaviour of
  2681.        Downsort.
  2682.  
  2683.     
  2684.                                         Appendix A.  History of changes  39
  2685.  
  2686.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  2687.     
  2688.     
  2689.     
  2690.     ■  Added some sections in Downsort.Doc about:
  2691.        ∙  "Runtime considerations" to explain the use of configuration
  2692.           files
  2693.        ∙  the calculation of file age
  2694.     ■  The functional extensions made that Downsort grew over the infamous
  2695.        64KB boundary for the (16-bits) code segment.  This forces a
  2696.        selection of a 'large' memory model, which made DOWNSRT1.EXE grow
  2697.        more than proportional compared to version 6.2.
  2698.  
  2699.     Bug fixes
  2700.  
  2701.     ■  Listed files in IPNFileList now obey the specifications.
  2702.     ■  Solved runtime error R6001 in DOS environment.
  2703.     ■  Sorts where the filename is involved changed to case-dependent!
  2704.        Lower case filenames are converted to upper case during data
  2705.        collection, and the case-independent sort gave a wrong sequence,
  2706.        especially with filenames containing the underscore character.
  2707.     ■  Corrections in calculation of file-age: now takes into account
  2708.        leap-year and timezone.
  2709.     ■  All file dates now accepted (limit to year 2057 removed).
  2710.     ■  'Offline' files not reported anymore in lists with limit on
  2711.        file-age.
  2712.     ■  Correction in some sorts: performance improvement!
  2713.     ■  Correction in handling of explicit path spec in Files.Bbs.
  2714.     ■  Semaphore file 'Downsort.Bsy' now more consistently removed, also
  2715.        under some error-conditions.
  2716.  
  2717.  
  2718.  
  2719.     7.3 VERSION 6.2
  2720.  
  2721.     Note: This version of Downsort supports Maximus version 3!!  Downsort
  2722.     6.1 is the last version to support Maximus version 2.
  2723.  
  2724.     ■  Downsort is now shareware and requires registration and fee after a
  2725.        trial period of 45 days.  See chapter "Registration and Shareware
  2726.        Fee" for how to register.
  2727.     ■  A new format "IPNFileList" is available: a NEWFileList in
  2728.        IPF-Format.  All features and switches that apply to NEWFileList are
  2729.        valid.  Group sorting (parameter -g) is recommended to show
  2730.        divisions.
  2731.     ■  Another new list type "TOPFileList" added.  If you maintain a
  2732.        download counter in the file description part of FILES.BBS in the
  2733.        format '[nnn]' (numeric value between brackets as first part of the
  2734.        description), this may be useful to generate a list of most
  2735.        frequently downloaded files.  Note: Downsort itself only reads the
  2736.        download counter (does not update it).
  2737.     ■  The code for IPFFileList (for IPFC of OS/2 1.2/1.3) has been removed
  2738.        and IP2FileList has been renamed to IPFFileList.  So you need at
  2739.        least an IPFC of the level of OS/2 2.0 (IPFC version 2).
  2740.     ■  The OK-FileList now only can build 'short' OKfiles (one line per
  2741.        directory).  To create a 'long' format of an OK-FileList (with a
  2742.        'magic' name for each file), you'll need USRFileList.  See the
  2743.        sample in Downsort.Cfg.
  2744.     ■  The EMI-FileList is not supported anymore.
  2745.  
  2746.     
  2747.                                         Appendix A.  History of changes  40
  2748.  
  2749.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  2750.     
  2751.     
  2752.     
  2753.     ■  New 'open' BLOCK-title font added (-F5).
  2754.     ■  Fullstop-character or colon (':') added to all block fonts.
  2755.     ■  Commandline option '/Ixx' added to let Downsort execute in IDLE
  2756.        priority class level 'xx' (number in range 1..31, default 16).
  2757.        Applies only to the 32-bits OS/2 version.
  2758.     ■  Areanames not limited to 8 characters anymore.
  2759.     ■  The Orphan-Adoption flag '-O' is now active for all lists.
  2760.        Specification of the '-O' flag will show orphans in the list, but
  2761.        for real 'adoption' you have to specify the flag in FILFilePath!
  2762.     ■  Remove flag '-R' is now active for all lists.  If specified
  2763.        'offline' files will not be reported.
  2764.     ■  Truncate (-T) or Wrap (-W) flags now also applicable to FILFileList.
  2765.        The maximum length of FILES.BBS lines will be 1024 bytes (the
  2766.        maximum supported by Maximus 3.00).  This is more Maximus friendly
  2767.        and may avoid problems with FB[P]  and MAXFILES.IDX.
  2768.     ■  A couple of other 'cosmetic' list improvements.
  2769.     ■  More robust parameter checking to prevent obviously duplicate,
  2770.        missing or conflicting specifications.  If available with the
  2771.        particular check, messages will contain the line number of the used
  2772.        'Downsort.Cfg' that contains the possible error.
  2773.     ■  When selecting an undefined areagroup with xxxFileList the list will
  2774.        be empty in stead of containing all areas.
  2775.     ■  Improved error handling.  One improvement is that the 'semaphore'
  2776.        file Downsort.Bsy is always removed before termination, even with
  2777.        Ctrl-Break and internal error conditions.
  2778.     ■  All code for support of privilege and userkeys/locks has been
  2779.        removed.  The major consequences are:
  2780.        ∙  Area selection can only be obtained with AreaGroup and
  2781.           areaIN/EXclude specifications.
  2782.        ∙  If migrating from an earlier version of Downsort you need to
  2783.           remove the Privilege/Keys specifications on the xxxFileList lines
  2784.           in Downsort.Cfg!
  2785.        ∙  The '-X' xxxFileList parameter controls now the display of the
  2786.           Access Control String (ACS) in stead of the 'privilege/lock'
  2787.           values.
  2788.     ■  The explanation of areaIN/EXclude in the sample Downsort.Cfg has
  2789.        been significantly entended to help you better with the area
  2790.        selection specifications.
  2791.     ■  Changes in USRmodel variables:
  2792.        ∙  '%A' variable in the USRmodel specification now presents the
  2793.           fully qualified areaname, including division prefixes.
  2794.        ∙  A new '%U' variable presents the unqualified areaname (without
  2795.           division prefixes).
  2796.        ∙  The '%$'-variable in USRmodel will now display the ACS of the
  2797.           file area.
  2798.     ■  New appendix in Downsort.Doc with an example how non_MAXIMUS users
  2799.        could use Downsort.
  2800.     ■  By lack of even a single response UCOPY is omitted from the Downsort
  2801.        package.  It remains available on request as a separate package.
  2802.     ■  The ability of MAX 3.00 to work with areadivisions made it necessary
  2803.        to change the format of some lists.
  2804.        ∙  Downsort will generally use fully qualified areanames including
  2805.           the division-names, such as "Etc.Gen.Misc".  Your areaIN/EXclude
  2806.           specifications should use fully qualified names as well, or just
  2807.           file-divisions if you like (use the terminating '.'-character).
  2808.  
  2809.     
  2810.                                         Appendix A.  History of changes  41
  2811.  
  2812.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  2813.     
  2814.     
  2815.     
  2816.           Remember: all areaIN/EXclude specification strings are used as
  2817.           prefixes.
  2818.        ∙  In lists with the areaname on each line only the unqualified
  2819.           areaname without division-prefix (with a maximum of 10
  2820.           characters, was 8) will be used.  The unqualified areaname is
  2821.           also used in places where the areaname is to be listed in
  2822.           BLOCK-characters (limited by linelength).
  2823.        ∙  In lists with the areaname in a normal text-mode header, the
  2824.           fully qualified areaname including the divisions will be used.
  2825.        ∙  If you specify a destination directory for FILFileList, then
  2826.           Downsort will use the unqualified areaname to create an
  2827.           "Areaname.BBS" file for every participating area.  Beware of
  2828.           duplicate areanames that might be generated in this way, maybe
  2829.           also as result of truncating long areanames to 8 characters (to
  2830.           keep Downsort working for FAT volumes).
  2831.        ∙  Some formatting flags have different defaults to anticipate on
  2832.           the long fully qualified names.
  2833.        ∙  'AreaOrder' has changed:
  2834.           -  'Alphabetic' will take the unqualified name (without the
  2835.              division prefixes).
  2836.           -  'Group' will take the qualified name (including the division
  2837.              prefixes).
  2838.           -  The feature of previous versions of Downsort to 'split' a
  2839.              trailing numeric suffix from the areaname to obtain a 'proper'
  2840.              sequence has been abandoned.  If you still use sequence
  2841.              numbers in areanames and you want them sorted 'numerically',
  2842.              please ensure they have equal length by inserting leading
  2843.              zeroes.  For example if you use areanames like: ABC1, ABC2,
  2844.              ... ABC9, ABC10, ... etc, rename these into ABC01, ABC02, ...
  2845.              ABC09, ABC10, etc.
  2846.  
  2847.     Bug fixes
  2848.  
  2849.     ■  The last file description in FILES.BBS will now also disappear when
  2850.        the area has become empty and the '-R' option has been specified
  2851.        with FILFilePath.
  2852.     ■  AreaGroup definitions are now OK (trailing blanks and end-of-line
  2853.        characters were not always removed correctly).
  2854.  
  2855.  
  2856.  
  2857.     7.4 VERSION 6.1
  2858.  
  2859.     Note: This version is still designed for Maximus version 2.0, but is
  2860.     MAX 3.00 aware and will run safely under MAX 3.00.  If you have
  2861.     migrated to MAX 3.0, run SILT[P] with the -2s option to generate the
  2862.     MAX 2.0 compatible FAREA.DAT file in addition to the regular MAX 3
  2863.     control files.
  2864.  
  2865.     See also the commentlines marked '6.1' in Downsort.Cfg, and read the
  2866.     warning at the end of this paragraph!
  2867.  
  2868.     ■  When errors occur while re-building an existing FILES.BBS file, the
  2869.        backup file (created by Downsort) will be restored by Downsort
  2870.        itself.
  2871.  
  2872.     
  2873.                                         Appendix A.  History of changes  42
  2874.  
  2875.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  2876.     
  2877.     
  2878.     
  2879.     ■  Downsort will create a 'semaphore' file DOWNSORT.BSY in the current
  2880.        directory at start-up and removes it just before termination.  Other
  2881.        processes may test the existence of this file.  For example you
  2882.        might put a check in a Maximus menu to decide not to enter the
  2883.        file-menu while Downsort is running and possibly updating FILES.BBS.
  2884.        Or you may avoid running more than 1 copy of Downsort at the same
  2885.        time.  Downsort itself does not check on the semaphore file!
  2886.     ■  USRmodel specification changes:
  2887.        ∙  USRmodel statement should specify a name only
  2888.        ∙  The line immediately following it is taken as the model-string
  2889.        ∙  USRFileList should now specify the name of the USRmodel with -U
  2890.           option
  2891.     ■  USRFileLIst extended with '%$' (file privilege), '%L' (file Lock
  2892.        string) and '%N' (download count, if present in format of '[nnn]' in
  2893.        file description) and '%Z' (last-access date)
  2894.     ■  Dates will now always have 8 characters (leading space-character is
  2895.        now a leading zero).
  2896.  
  2897.        Multiple 'Title'-lines may now be specified for multi-line BLOCK
  2898.        titles.
  2899.     ■  Orphan files were always adopted in FILES.BBS, but listed after a
  2900.        ^PS line (files after that line had SYSOP privilege).  This feature
  2901.        of Downsort has changed on popular demand:
  2902.        ∙  Orphans will not be added to FILES.BBS anymore by default.
  2903.           Specify the new '/O' ('Orphan-adoption') flag on FILFilePath line
  2904.           to have orphans added to FILES.BBS (=adoption!) like before.
  2905.        ∙  A line with '^PS' will not be inserted anymore in front of
  2906.           orphan-lines.  This prevents that entries which are added to the
  2907.           bottom of FILES.BBS by other programs (e.g. TICK) will
  2908.           incorrectly be marked as SYSOP-only files.  But if Downsort
  2909.           inserts orphans (if you use the /O-switch), it will be at the end
  2910.           of Files.Bbs, and therefore orphans will obtain the privilege of
  2911.           the 'regular' files at the end of Files.Bbs, which might be
  2912.           higher than the area-privilege.
  2913.     ■  ALLFileList will contain a formfeed for the Summary report.  A REXX
  2914.        procedure 'DOWNSUM.CMD' is provided to extract the summary report
  2915.        from this list.
  2916.     ■  For FidoNet nodes only, betatest versions of Downsort are now
  2917.        available by file request from <digiThalys> BBS.  See the section
  2918.        "Availability" in Downsort.Doc for details.
  2919.     ■  Bug fixes:
  2920.        ∙  No more 'split' line with privilege/lock in FILES.BBS with long
  2921.           area-names.
  2922.        ∙  Total bytecounts exceeding 4 GB will be reported now correctly.
  2923.        ∙  The /R option for FILFilePath will now also remove entries in
  2924.           FILES.BBS of areas without downloadable files.
  2925.        ∙  %P in USRmodel will now substitute the explicit path of those
  2926.           files that have a path specification in FILES.BBS (in stead of
  2927.           the path of the download directory).
  2928.        ∙  Some 'cosmetic' improvements like the version number of Warp,
  2929.           which will now correctly be reported as 3.0 (in stead of 2.30).
  2930.  
  2931.     WARNING: This version is planned to be the last version of Downsort
  2932.     that:
  2933.  
  2934.  
  2935.     
  2936.                                         Appendix A.  History of changes  43
  2937.  
  2938.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  2939.     
  2940.     
  2941.     
  2942.     1. will run under OS/2 1.x.  A 32-bit OS/2 2.00+ only and a DOS-only
  2943.        version will be distributed.
  2944.     2. will support MAX 2.0 (the next version will only support MAX 3.00+).
  2945.     3. will support EMI-, OK-, and IPF- (the OS/2 1.x variant) FileLists.
  2946.        I think these variants are obsolete.  The OKfile, if anyone may
  2947.        still use it, can easily be built with USRFileList, the current
  2948.        Downsort.Cfg contains already an example.  So for this type of list
  2949.        you could already convert today!
  2950.  
  2951.     This is a PLAN!  Please signal me if you expect to become victim of an
  2952.     undesired change!
  2953.  
  2954.  
  2955.     7.5 VERSION 6.0
  2956.  
  2957.     This version contains some major enhancements and extensions.  With the
  2958.     change of the major version number I permitted myself some minor
  2959.     incompatibilities with previous versions!
  2960.  
  2961.     ■  Some filenames changed towards OS/2 2.1 as default operating system.
  2962.  
  2963.        description       oper_sys     old filename    new filename
  2964.        ────────────────  ────────     ────────────    ────────────
  2965.        Downsort 32-bits  OS/2 2.0+    DOWN386.EXE     DOWNSORT.EXE
  2966.        Downsort 16-bits  DOS+OS/2     DOWNSORT.EXE    DOWNSRT1.EXE
  2967.        Icon-file         OS/2 2.0+    DOWN386.ICO     DOWNSORT.ICO
  2968.        Hpfsdate 32-bits  OS/2 2.0+    HPFSD386.EXE    HPFSDATE.EXE
  2969.        Hpfsdate 16-bits  OS/2 1.3     HPFSDATE.EXE    HPFSDAT1.EXE
  2970.  
  2971.        But of course you may rename these modules for your own use as you
  2972.        like!
  2973.     ■  Introduction of AREAGROUPs.  Definition of a group of areas as a
  2974.        logical entity.  The main purpose of this feature is to be able to
  2975.        generate an even larger variety of lists in a single run of
  2976.        Downsort.  The contents of each group is defined with areaIN/EXclude
  2977.        statements, individually and most likely different for each group.
  2978.        In any xxxFileList line you may select (-Sgroup) one of the defined
  2979.        groups to generate an xxxFileList for a 'special interest group'.
  2980.        Downsort does not collect file-data it won't need, such as from
  2981.        areas that will not appear in any list of a particular run.  The
  2982.        AreaGroup facility can be a relief for DOS-users that suffer from
  2983.        memory problems when large file collections are to be listed.
  2984.     ■  xxxFileList can and should(!) now specify complete filename.ext for
  2985.        every list.  A complete path may be specified, it must be an
  2986.        existing directory.  Beware of duplicate names, and of possible
  2987.        sharing violations when another program is accessing one of the
  2988.        outputfiles while Downsort is running: the output will then not be
  2989.        created.
  2990.     ■  Duplicate download filename detection can now be on (first)
  2991.        part of filename.  New keyword "DupNameSize" specifies number of
  2992.        significant characters.  The header of DUPFileList output shows now
  2993.        some of the parametersettings.
  2994.     ■  DUPFileList can now also be sorted on file-date or area, and within
  2995.        area on filename or FILES.BBS sequence ('keep').
  2996.     ■  Specifying a font does not have influence anymore on the appearance
  2997.  
  2998.     
  2999.                                         Appendix A.  History of changes  44
  3000.  
  3001.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  3002.     
  3003.     
  3004.     
  3005.        of areaheaders with the 'short' format (areanames of 3 characters or
  3006.        less) in ALL- and GBL-FileList, and output of FILFilePath).  This
  3007.        font is now (temporary?) hardcoded: Font 3.
  3008.     ■  Several changes to FILFilePath processing:
  3009.        ∙  FILFilePath should NOT specify a privilege parameter anymore!
  3010.        ∙  If FILFilePath specifies a path, the outputfiles will now always
  3011.           have the format "path\areaname.BBS" (the format "FILES.ac" has
  3012.           been abandoned).
  3013.        ∙  First 8 comment lines, if not a Downsort header, are not
  3014.           discarded aymore.  But beware: migrating from a version of
  3015.           Downsort older than 5.7 may result in pseudo duplicate headers!
  3016.        ∙  Multiple FILFilePath lines may be specified with individual
  3017.           parameters, most likely in combination with AreaGroup selection.
  3018.           Useful when you want FILES.BBS for some areas formatted
  3019.           differently than for other areas such as include file, sorting
  3020.           method, output path.  Beware not to specify 'overlapping' groups
  3021.           to prevent overwriting output of one FILFilePath by another.
  3022.        ∙  File entries in FILES.BBS of which the file is not found
  3023.           (reported by Downsort as 'offline') can now be removed from
  3024.           FILES.BBS with the '-R' flag on the FILFilePath report line.
  3025.           Removed entries will still be reported in other reports as
  3026.           'offline', but will disappear with the next run of Downsort.
  3027.     ■  A new list type 'USRFileList' has been added.  It is designed to
  3028.        build batch files with a user-specifiable 'model'-format.  File
  3029.        information can be inserted in this model via symbolic variables.
  3030.        Only existing files are listed, 'not-found' entries in FILES.BBS,
  3031.        commentlines and orphans are skipped.  With the USR-list Downsort
  3032.        offers a two-stage file maintenance: a build-phase and an
  3033.        execute-phase.  Consider the output of phase 1 as the 'advise'-list
  3034.        for phase-2.  You can modify the batch-file before executing it.
  3035.        See the bottom of the sample Downsort.Cfg for some more details.
  3036.     ■  Program history removed from documentation of versions older than
  3037.        5.5.
  3038.     ■  Downsorts hardcode bottom-lines now report Operating System version
  3039.        sub-number in two digits (e.g. OS/2 2.11)
  3040.     ■  Bug fixes:
  3041.        ∙  IPFFileList and IP2FileList now really include user-file if
  3042.           specified!
  3043.        ∙  A large block of commentlines (containing more than 2 KBytes) in
  3044.           FILES.BBS does not cause a abnormal termination of Downsort
  3045.           anymore.
  3046.        ∙  Removed insertion of extraneous blank line in FILES.BBS and
  3047.           ALLFileList for empty areas.
  3048.        ∙  Sort on file-age now again correctly on most recent of Creation
  3049.           date and LastWrite date (was problem only with HPFS volumes).
  3050.        ∙  FileExclude statement now accepts really multiple strings on a
  3051.           line!
  3052.        ∙  Long OKFileList will now contain existing files only.
  3053.        ∙  Explicit path specifications in FILES.BBS will now be retained,
  3054.           even if the file could not be located (in which case the path was
  3055.           lost!).
  3056.        ∙  Keys/locks reported in header of FILES.BBS output with privilege.
  3057.     ■  A file search and copy utility 'UCOPY' has been added.  It relies on
  3058.        Downsort's long OKFileList, but otherwise it is a self-contained
  3059.        program.  Its main function is to offer a fast file search, select
  3060.  
  3061.     
  3062.                                         Appendix A.  History of changes  45
  3063.  
  3064.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  3065.     
  3066.     
  3067.     
  3068.        and copy.  It performs its task via a long OKfiles (one of the
  3069.        facilities of Downsort).  See the UCOPY.DOC in UCOPY.ZIP for more
  3070.        details.
  3071.     ■  The source will not be distributed anymore (lack of interest!).
  3072.  
  3073.  
  3074.  
  3075.  
  3076.  
  3077.  
  3078.  
  3079.  
  3080.  
  3081.  
  3082.  
  3083.  
  3084.  
  3085.  
  3086.  
  3087.  
  3088.  
  3089.  
  3090.  
  3091.  
  3092.  
  3093.  
  3094.  
  3095.  
  3096.  
  3097.  
  3098.  
  3099.  
  3100.  
  3101.  
  3102.  
  3103.  
  3104.  
  3105.  
  3106.  
  3107.  
  3108.  
  3109.  
  3110.  
  3111.  
  3112.  
  3113.  
  3114.  
  3115.  
  3116.  
  3117.  
  3118.  
  3119.  
  3120.  
  3121.  
  3122.  
  3123.  
  3124.     
  3125.                                         Appendix A.  History of changes  46
  3126.  
  3127.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  3128.     
  3129.     
  3130.     
  3131.     APPENDIX B.  WORLD-WIDE USE OF DOWNSORT
  3132.  
  3133.     The most recent released version and the latest beta-test version are
  3134.     available on the authors homepage:
  3135.     http://users.capitolonline.nl/~nlco5907
  3136.  
  3137.     Among many others, the following SYSOPs have reported running Downsort
  3138.     to make file collection lists for their users, and have a recent
  3139.     version available for download or file-request:
  3140.  
  3141.     1:141/209     Fernwood            Emmitt Dove       Branford CT, USA
  3142.     1:109/347     OS/2 Shareware      Pete Norloff      Fairfax VA, USA
  3143.     1:163/116     La Jungle BBS       Stephane Seguin   Hull QC, Canada
  3144.     1:221/177     K-W Amateur Radio   Fred Hicks        Kitchener ON, Canada
  3145.     1:244/440     Bob's Bored/2       Robert Ensing     Hamilton ON, Canada
  3146.     1:250/2       Kariko BS-BBS       Kari Suomela      North York ON, Canada
  3147.     1:382/1201    HUB/2               John Dierdorf     Austin TX, USA
  3148.     2:254/211     The Cray BBS        Bill Hayles       Foots Cray, UK
  3149.     2:280/801     Chat                Lody Caenen       Koog a/d Zaan, NL
  3150.     2:280/804     PCSquare            Lody Caenen       Koog a/d Zaan, NL
  3151.     2:292/522     I.C.S./2            Mario Lermite     Mechelen, Belgium
  3152.     2:331/205     Runnin' w the Devil Stefano Sonzogni  Treviglio BG, Italy
  3153.     2:2448/620    Plejaden Caffee     Axel Cordt        Bochum, Germany
  3154.     2:2476/14     Logo/2              Dieter Ringhofer  Neckarwestheim, Germany
  3155.     3:623/630     Serendipity Inc     Poe Lim           Cowra, NSW Australia
  3156.     3:711/409     3M Australia        Graham Stair      Pymble, NSW Australia
  3157.     3:772/20      IBM NZ Ltd Gate     Terry Bowden      Auckland, New Zealand
  3158.  
  3159.     I have received reports from others.  Too many for this list, which is
  3160.     just meant to point to a system in your neighbourhood(?).  You may
  3161.     either logon to one of these boards, or perform a file-request of
  3162.     'FILES' or 'ALLFILES' to get an impression of Downsort's capabilities.
  3163.  
  3164.  
  3165.  
  3166.  
  3167.  
  3168.  
  3169.  
  3170.  
  3171.  
  3172.  
  3173.  
  3174.  
  3175.  
  3176.  
  3177.  
  3178.  
  3179.  
  3180.  
  3181.  
  3182.  
  3183.  
  3184.  
  3185.  
  3186.  
  3187.     
  3188.                                 Appendix B.  World-wide use of Downsort  47
  3189.  
  3190.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  3191.     
  3192.     
  3193.     
  3194.     APPENDIX C.  SAMPLE LISTS
  3195.  
  3196.     Below follow a number of samples of list layouts and contents.  Not
  3197.     shown are the BBS-, and IPF-lists, since these are screen- rather than
  3198.     paper-oriented, with their specific formatting and color settings.
  3199.  
  3200.     The dates and sizes in these lists have been manipulated!
  3201.  
  3202.  
  3203.     9.1 ALL-LIST
  3204.  
  3205.  
  3206.     ════════════════════════════════════════════════════════════════════════════
  3207.      █▀▀▀▀▀▀   █  ║ OS/2 - Fernwood - New Acquisitions
  3208.      █▄▄▄▄▄   ▄█  ║ Available: 143 files (0.0 MB)
  3209.      ██       ██  ║
  3210.      ██       ██  ║ Newest: XLIST233.ZIP  3-22-91  (avail:  7-26-91)
  3211.     ────────────────────────────────────────────────────────────────────────────
  3212.     Filename      Size   Date    Description
  3213.     ──────────── ───── ───────── ───────────────────────────────────────────────
  3214.     AAFONTS.ZIP     1K  3-22-91  Text from IBM regarding Anti-aliased Fonts.
  3215.     AFP_120.LZH     1K  3-22-91  Areafix 1.2 for OS/2.  Permits systems that do
  3216.                                  echomail with yours to change their complement
  3217.                                  of areas independently.
  3218.  
  3219.  
  3220.  
  3221.     9.2 GBL-LIST
  3222.  
  3223.  
  3224.     (Sun Jan 05 15:05) Available: 508 files (0 MB)
  3225.                        Newest: BIGBRO.ZIP  3-22-91 (avail:  7-26-91)
  3226.                        Date flag: new on this system since: * = 1 week, + = 1 month
  3227.  
  3228.     Filename       Area    Size   Date    Description
  3229.     ──────────── ──────── ───── ───────── ──────────────────────────────────────
  3230.     2COLDIR.ZIP  F3          1K  3-22-91  DoubleDir for OS/2
  3231.     2MONITOR.ZI  F4          1K  3-22-91  Source and .EXE for running 2 monitors
  3232.  
  3233.  
  3234.  
  3235.     9.3 NEW-LIST
  3236.  
  3237.  
  3238.     (Sun Jan 05 16:14) Last 10 months newest of a total of 508 files (0 MB)
  3239.                        Newest: BIGBRO.ZIP dd  3-22-91 (avail:  7-26-91)
  3240.                        Date flag: new on this system since: * = 1 week, + = 1 month
  3241.  
  3242.     Filename       Area    Size   Date    Description
  3243.     ──────────── ──────── ───── ───────── ──────────────────────────────────────
  3244.     2COLDIR.ZIP  F3          1K  3-22-91  DoubleDir for OS/2
  3245.     2MONITOR.ZIP F4          1K  3-22-91  Source and .EXE for running 2 monitors
  3246.     8514.PAT     F4          1K  3-22-91  Patch to get 32x32 icons on 8514/a
  3247.  
  3248.  
  3249.  
  3250.     
  3251.                                               Appendix C.  Sample Lists  48
  3252.  
  3253.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  3254.     
  3255.     
  3256.     
  3257.     9.4 FILES.BBS
  3258.  
  3259.  
  3260.       █▀▀▀▀▀▀   █  ║ OS/2 - Fernwood - New Acquisitions
  3261.       █▄▄▄▄▄   ▄█  ║ Available: 143 files (0.0 MB)
  3262.       ██       ██  ║
  3263.       ██       ██  ║ Newest: XLIST233.ZIP  3-22-91 (avail:  7-26-91)
  3264.      ───────────────────────────────────────────────────────────────────────────
  3265.      Filename      Size    Date     Description
  3266.      ─────────── ─────── ───────── ─────────────────────────────────────────────
  3267.     AAFONTS.ZIP   Text from IBM regarding Anti-aliased Fonts.
  3268.     AFP_120.LZH   Areafix 1.2 for OS/2.  Permits systems that do echomail . . .
  3269.  
  3270.     The header prefix that Downsort uses for Files.Bbs files are not shown,
  3271.     but what the remote user would see of it.
  3272.  
  3273.     File date and size are provided dynamically by Maximus CBCS!
  3274.  
  3275.  
  3276.     9.5 ORPHAN LIST
  3277.  
  3278.  
  3279.     ════════════════════════════════════════════════════════════════════════════
  3280.       Area    Filename      Date    FilePath
  3281.     ──────── ──────────── ───────── ────────────────────────────────────────────
  3282.     F1       123R3UPD.ZIP  3-22-91  G:\File\Fernwood\
  3283.     F1       4019DRVR.ZIP  3-22-91  G:\File\Fernwood\
  3284.  
  3285.  
  3286.  
  3287.  
  3288.  
  3289.  
  3290.  
  3291.  
  3292.  
  3293.  
  3294.  
  3295.  
  3296.  
  3297.  
  3298.  
  3299.  
  3300.  
  3301.  
  3302.  
  3303.  
  3304.  
  3305.  
  3306.  
  3307.  
  3308.  
  3309.  
  3310.  
  3311.  
  3312.  
  3313.     
  3314.                                               Appendix C.  Sample Lists  49
  3315.  
  3316.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  3317.     
  3318.     
  3319.     
  3320.     APPENDIX D.  DOWNSORT FOR NON-MAXIMUS USERS
  3321.  
  3322.     This appendix tries to help potential users of Downsort who do not
  3323.     actually run Maximus with creating the minimum environment to run
  3324.     Downsort.  For a more extensive setup you may require the file MAX.DOC
  3325.     from the Maximus archives.  The names that are mentioned below for
  3326.     drives and directories are examples!
  3327.  
  3328.     1. Create a directory 'MAX' on one of your drives (let's say 'd:').
  3329.  
  3330.     2. Build in this directory a file 'MAX.CTL' with the following
  3331.        contents:
  3332.  
  3333.             System Section
  3334.                   Path System     d:\max\
  3335.             End System Section
  3336.             Session Section
  3337.                   FileData        Farea
  3338.             End Session Section
  3339.             Include farea.ctl
  3340.  
  3341.     3. Create in this directory also a file FAREA.CTL with the following
  3342.        contents:
  3343.  
  3344.             Filearea UTIL
  3345.                      Desc            Utilities for DOS
  3346.                      Download        d:\Dos\util\
  3347.             End Filearea
  3348.  
  3349.             Filearea UTIL2
  3350.                      Desc            Utilities for OS/2 from HOBBES CDROM
  3351.                      Download        g:\32bit\sysutils\
  3352.                      FileDesc        d:\32bit\sysutils\descript.ion
  3353.             End Filearea
  3354.  
  3355.        Of course this should be changed and extended to reflect your actual
  3356.        file-base, but start with only a few areas to see if it works.  Note
  3357.        that for the first area the directory 'd:\Dos\util\' is assumed to
  3358.        contain a file 'FILES.BBS' with the file-descriptions, while the
  3359.        second area explicitly points for this information to a file with a
  3360.        different name.  Explicit specification is needed if a file with the
  3361.        name 'FILES.BBS' is not in the download directory itself.
  3362.  
  3363.     4. Per filearea you need a text file with file descriptions, generally
  3364.        called FILES.BBS (which is the default for Downsort).  Each line
  3365.        should contain a 'filename.ext' followed by a descriptive text for
  3366.        this file (up to 1024 bytes), for example:
  3367.  
  3368.         DWNSRT&VERSION.&SUBVERS..ZIP Maximus CBCS DOWNload file SORT and list util
  3369.  
  3370.        The filename should start in position 1.
  3371.  
  3372.     5. Obtain SILT[P] from a Maximus 3.00 runtime archive, or from a
  3373.        friendly Maximus Sysop (SILTP.EXE if you run OS/2, SILT if your run
  3374.        DOS), and put it also in this directory or in one of your 'PATH'
  3375.  
  3376.     
  3377.                             Appendix D.  Downsort for non-Maximus users  50
  3378.  
  3379.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  3380.     
  3381.     
  3382.     
  3383.        directories.
  3384.  
  3385.     6. Make "d:\max" the current default directory and run SILTP with:
  3386.  
  3387.             SILTP max -af
  3388.  
  3389.        This will create the required file 'FAREA.DAT' (use SILT if you run
  3390.        DOS!).
  3391.  
  3392.     7. Create in this directory a file Downsort.Cfg or take the provided
  3393.        sample file and modify it as desired.
  3394.  
  3395.     8. Put DOWNSORT.EXE in "d:\max", or in one of your 'PATH' directories.
  3396.  
  3397.     Now you are ready to run Downsort.
  3398.  
  3399.  
  3400.  
  3401.  
  3402.  
  3403.  
  3404.  
  3405.  
  3406.  
  3407.  
  3408.  
  3409.  
  3410.  
  3411.  
  3412.  
  3413.  
  3414.  
  3415.  
  3416.  
  3417.  
  3418.  
  3419.  
  3420.  
  3421.  
  3422.  
  3423.  
  3424.  
  3425.  
  3426.  
  3427.  
  3428.  
  3429.  
  3430.  
  3431.  
  3432.  
  3433.  
  3434.  
  3435.  
  3436.  
  3437.  
  3438.  
  3439.     
  3440.                             Appendix D.  Downsort for non-Maximus users  51
  3441.  
  3442.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  3443.     
  3444.     
  3445.     
  3446.     APPENDIX E.  SAMPLE CONFIGURATION FILE
  3447.  
  3448.     ;
  3449.     ;      ██▐███   █▐███  ██   ██ ██▐███ ██▐████  █▐███  ██▐███  ██▐████
  3450.     ;      ██   ██ ██   ██ ██   ██ ██  ██ ██      ██   ██ ██   ██   ▐██
  3451.     ;      ██   ██ ██   ██ ██ █ ██ ██  ██ ██▐████ ██   ██ ██▐███    ▐██
  3452.     ;      ██   ██ ██   ██ ██ █ ██ ██  ██      ██ ██   ██ ██ █      ▐██
  3453.     ;      ██▐███   █▐███   █▐███  ██  ██ ██▐████  █▐███  ██  ██    ▐██
  3454.     ;                                                                  (font 2)
  3455.     ;
  3456.     ;
  3457.     ; ▄▀▀▀▄ ▄▀▀▀▄ █▄  █ █▀▀▀▀ ▀█▀ ▄▀▀▀▄ █   █ █▀▀▀▄ ▄▀▀▀▄ ▀▀█▀▀ ▀█▀ ▄▀▀▀▄ █▄  █
  3458.     ; █     █   █ █▀█▄█ █▄▄    █  █  ▄▄ █   █ █▄▄▄▀ █▄▄▄█   █    █  █   █ █ ▀▄█
  3459.     ; ▀▄▄▄▀ ▀▄▄▄▀ █  ▀█ █     ▄█▄ ▀▄▄▄▀ ▀▄▄▄▀ █ ▀▄▄ █   █   █   ▄█▄ ▀▄▄▄▀ █   █
  3460.     ;                                                                  (font 1)
  3461.     ;
  3462.     ;
  3463.     ;                   █▀▀▀▀▀▀   █     █       █▀▀▀▀▀▀
  3464.     ;                   █▄▄▄▄▄▄   █▄    █▄      █▄▄▄▄▄▄
  3465.     ;                   ██        ██    ██      ██
  3466.     ;                   ██        ██    ██▄▄▄▄▄ ██▄▄▄▄▄
  3467.     ;                                                                  (font 3)
  3468.     ;                                            (font 4 is reverse video of 3)
  3469.     ;
  3470.     ;
  3471.     ;  ┌╦══╦┐    ┌╦  ╦┐ ┌╦══╦┐ ┌╦═╦═╦┐ ┌╦══╦┐ ┌╦══╦┐ ┌╦    ┌╦╦╦┐ ┌╦══╦┐ ┌╦══╦┐
  3472.     ;  │╠═╦╩┘ ┌┐ │╠══╣│ │╠══╣│ │║ ║ ║│ │╠═    │╠═╦╩┘ │║      ║   │║  ║│ │║ ═╦┐
  3473.     ;  └╩ ╚═┘ └┘ └╩  ╩┘ └╩  ╩┘ └╩   ╩┘ └╩══╩┘ └╩ ╚═┘ └╩═╩┘ └╩╩╩┘ └╩  ╩┘ └╩══╩┘
  3474.     ;                                                                  (font 5)
  3475.     ;
  3476.     ;        *******  Sample Configuration File for DOWNSORT  *******
  3477.     ;
  3478.     ;    DOWNSORT is designed to make many lists in almost any combination
  3479.     ;             in a single run with different groups of file areas.
  3480.     ;
  3481.     ; ┌──────────────────────────────────────────────────────────────────────┐
  3482.     ; │  This configuration file may look complicated for first time users.  │
  3483.     ; │  But Downsort needs no parameters for a default ALLFILES list!!!     │
  3484.     ; │  Just run DOWNSORT, and read chapter 'Quick Start' in Downsort.Doc!  │
  3485.     ; └──────────────────────────────────────────────────────────────────────┘
  3486.     ;
  3487.     ;  Rules for parameter specifications in a configuration file:
  3488.     ;  ──────────────────────────────────────────────────────────
  3489.     ;   - Lines are free format: leading and spacing blanks are ignored.
  3490.     ;   - All parameters for a specific keyword should be on a single line.
  3491.     ;   - For unsupported keywords a warning message is issued.
  3492.     ;   - Of mutually exclusive options only the last will take effect.
  3493.     ;   - Lines with a valid keyword but without any parameter, are handled as
  3494.     ;     comment lines and are ignored.
  3495.     ;   - Empty lines or lines with '%', '*' or ';' as first non-blank character
  3496.     ;     are considered to contain comments only and are ignored.
  3497.     ;   - Invalid or not-recognised parameters may be ignored without notice.
  3498.     ;
  3499.     ;    Downsort can be invoked with a commandline parameter specifying another
  3500.     ;    than the default configuration filename 'Downsort.Cfg', for example:
  3501.  
  3502.     
  3503.                                  Appendix E.  Sample Configuration File  52
  3504.  
  3505.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  3506.     
  3507.     
  3508.     
  3509.     ;         DOWNSORT @SPECIAL.CFG
  3510.     ;    (the '@' prefix denotes that a configuration filespec is following)
  3511.     ;
  3512.     ; ────────────────────────────────────────────────────────────────────────
  3513.     ;
  3514.     ;    RegName  The name for which you registered, enclosed in double quotes.
  3515.     ;    -------  Unregistered use of Downsort is permitted for up to 45 days.
  3516.     ;             See the file 'Register.Doc' for registration instructions.
  3517.  
  3518.       RegName     "Rob Hamerling"
  3519.  
  3520.     ; WaitTime    Maximum number seconds to wait on another Downsort.
  3521.     ; --------    Determines what to do if another active Downsort is running
  3522.     ;6.4          when this instance of Downsort is started:
  3523.     ;6.4            negative  - Proceed: ignore activity of other Downsorts
  3524.     ;6.4               0      - Terminate immediately (rc 640)
  3525.     ;6.4            positive  - Wait for at most this number of seconds.
  3526.     ;6.4                        Resume when no other Downsort(s) active anymore
  3527.     ;6.4                        within this period, otherwise terminate (rc 640).
  3528.     ;6.4          Default: -1
  3529.     ;6.4
  3530.     ;6.4          Note: Decision made after processing configuration file.
  3531.  
  3532.     ; WaitTime    0
  3533.  
  3534.     ; ──────────────────────────────────────────────
  3535.     ;  Specifications for the data collection phase
  3536.     ; ──────────────────────────────────────────────
  3537.     ;
  3538.     ; FareaDat     Path specification of your 'FAREA.DAT' file.
  3539.     ; --------     FAREA.DAT is built by Maximus' SILT[P] (-a, -af or -x option).
  3540.     ;              Default: FAREA.DAT in current directory, or otherwise in
  3541.     ;                       MAXIMUS base directory (environment var. 'Maximus').
  3542.  
  3543.     ; FareaDat     d:\max3\farea.dat
  3544.  
  3545.     ; AreaGroup    Defines a logical name for a group of fileareas or divisions.
  3546.     ; ---------    AreaGroups are used to build lists for groups of fileareas.
  3547.     ;              With AreaINclude and or AreaEXclude keywords following this
  3548.     ;              AreaGroup keyword, the collection of areas for this group
  3549.     ;              is defined. The groups are independent: areas may be member
  3550.     ;              of more than one group, other areas may not be in any group.
  3551.     ;              A new AreaGroup keyword closes the previous.
  3552.     ;              During data collection only the required areas are scanned.
  3553.     ;              WARNING: If at least one list does NOT specify an areagroup,
  3554.     ;                       file info of ALL area's is collected, which may
  3555.     ;                       significantly downgrade the performance of Downsort,
  3556.     ;                       especially when CDROM drives are involved!
  3557.     ;              NOTE: Areagroups are only meaningful in combination with a
  3558.     ;                    '-S' specification on an xxxFileList line (see below)!
  3559.  
  3560.     ; AreaINclude  Select areas to be INCLUDED in the group.
  3561.     ; AreaEXclude  Select areas to be EXCLUDED from the group.
  3562.     ; -----------  Character strings define which filedivisions and/or
  3563.     ;              fileareas have to be INcluded in or EXcluded from the group.
  3564.  
  3565.     
  3566.                                  Appendix E.  Sample Configuration File  53
  3567.  
  3568.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  3569.     
  3570.     
  3571.     
  3572.     ;              The strings are used as PREFIX. All areanames that start with
  3573.     ;              the specified string are considered 'matching' the
  3574.     ;              specification. The FULLY QUALIFIED areanames (including
  3575.     ;              FileDivision prefixes!) are considered.
  3576.     ;              You may specify multiple strings on a line, separated by one
  3577.     ;              or more blanks, and as many lines as needed. AreaINclude
  3578.     ;              and AreaEXclude keywords may appear in any sequence in
  3579.     ;              an AreaGroup. All comparisons are case-INsensitive.
  3580.     ;
  3581.     ;              The following rules determine which areas will be member of
  3582.     ;              an AreaGroup:
  3583.     ;              - If only areaINclude is specified for a group, then ONLY
  3584.     ;                the areas of which the name matches with any areaINclude
  3585.     ;                string will be member of this group.
  3586.     ;              - If only areaEXclude is used for a group then ALL areas
  3587.     ;                will be included EXCEPT those areas of which the name
  3588.     ;                matches with any areaEXclude string.
  3589.     ;              - If both areaINclude and areaEXclude are specified for a
  3590.     ;                group, then all areaINcludes precede any areaEXclude.
  3591.     ;              - If neither areaINclude nor areaEXclude is specified
  3592.     ;                then the group is empty.
  3593.  
  3594.     ;              Hints for the use of AreaGroups:
  3595.     ;              - If you don't use areaINclude, you probably want to
  3596.     ;                areaEXclude 'Sysop', 'Upload', 'Inbound', etc.
  3597.     ;                More generally: remember to areaEXclude those areas that
  3598.     ;                you normally want to hide for all users!
  3599.     ;              - You would normally use one of both keywords. Using them
  3600.     ;                both is only meaningful if the areaEXclude strings are
  3601.     ;                more restrictive (longer) then the areaINclude strings.
  3602.     ;                See for an example the AreaGroup 'HOB' below:
  3603.     ;                Suppose you have fileareas named HC000 to HC999
  3604.     ;                in a filedivision Hob (denoting the HOBBES CDROM),
  3605.     ;                then the group HOB would select the files from
  3606.     ;                areas HC000 to HC039, but NOT those ending with a '9'.
  3607.     ;              - 'CDROM NoList' has precedence over AreaInclude!
  3608.  
  3609.       AreaGroup  OS2
  3610.          AreaINclude  OS2. FW.
  3611.       AreaGroup  nonOS2
  3612.          AreaEXclude  OS2. FW. SYSOP. UPLOAD INBOUND
  3613.     ; AreaGroup  HOB
  3614.     ;    AreaINclude  Hob.hc00  Hob.hc01  Hob.hc02  Hob.hc03
  3615.     ;    AreaEXclude  Hob.hc009 Hob.hc019 Hob.hc029 Hob.hc039
  3616.  
  3617.     ; FileEXclude  Select FILES to be excluded from all(!) lists.
  3618.     ; -----------  By default all files in all (selected) areas will be
  3619.     ;              included, unless you use this keyword.
  3620.     ;              Specify 8.3 filename.ext type of strings, wildcards are
  3621.     ;              allowed and honored. Don't specify quotes.
  3622.     ;              The selection is case-insensitive and is independent of area.
  3623.     ;              You may specify multiple filespecs on a line, separated
  3624.     ;              by one or more blanks, and as many lines as needed.
  3625.  
  3626.       FileExclude  FILES.*    *.BAK        SYSTEM*.?BS   DIR.?BS
  3627.  
  3628.     
  3629.                                  Appendix E.  Sample Configuration File  54
  3630.  
  3631.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  3632.     
  3633.     
  3634.     
  3635.       FileExclude  00INDEX.*  WILDCAT.TXT  DESCRIPT.ION  TEST*.*
  3636.  
  3637.     ; CDROM        Areas that are located on CDROM can be handled differently
  3638.     ; -----        than areas on other media. A Filearea must have been
  3639.     ;              specified for Maximus with "Type CD" to be recognised
  3640.     ;              as such by Downsort.
  3641.     ;              One of two values is accepted:
  3642.     ;                NoScan  - No directory-scan will be performed.
  3643.     ;                          Filenames and the description in Files.Bbs will
  3644.     ;                          be included in the lists.
  3645.     ;                          When the area is specified with "Type CD DateList"
  3646.     ;                          and Files.Bbs contains filesize and filedate,
  3647.     ;                          the values of Files.Bbs will be used.
  3648.     ;                          Otherwise files will be reported as 'offline',
  3649.     ;                          filedate will be '01 Jan 1980' and filesize 0.
  3650.     ;                NoList  - CDROM-areas will be completely ignored.
  3651.     ;
  3652.     ;              Default: no special handling of CDROM-areas.
  3653.  
  3654.     ; CDROM  NoScan
  3655.  
  3656.     ; DIZimport    Import a file-description from the file File_Id.Diz in
  3657.     ; ---------    an archive. This will become the description in all lists.
  3658.     ;                No     - No import, leave descr. asis (even when missing!)
  3659.     ;                Yes    - Import only when no description in Files.Bbs
  3660.     ;                Force  - Import always: substitute existing description
  3661.     ;                nn     - Numeric value for the length of the existing
  3662.     ;                         description to force import of File_Id.Diz
  3663.     ;                         (if length smaller than nn then force import)
  3664.     ;              Default: No
  3665.  
  3666.     ; DIZimport    No
  3667.  
  3668.     ; CompressCfg  Filespec of configuration file for archive utilities.
  3669.     ; -----------  It can be the same as used by Maximus and Squish for archiver
  3670.     ;6.4           specifications. An optimised file 'Compress.Dwn' is provided.
  3671.     ;              The file is only needed with DIZimport activity.
  3672.     ;              See Maximus or Squish documentation for specification details.
  3673.     ;              Default: Compress.Cfg in current directory, or otherwise in
  3674.     ;                       Maximus base directory (environment var. 'Maximus').
  3675.     ;6.4                    If not found, DizImport is effectively 'No'.
  3676.  
  3677.       CompressCfg  Compress.Dwn
  3678.  
  3679.  
  3680.     ;  ───────────────────────────────────────────────────────────────────────
  3681.     ;  List-specifications with a global scope,
  3682.     ;  common parameters that apply to all lists.
  3683.     ;  ───────────────────────────────────────────────────────────────────────
  3684.     ;  Title:      Short string that will be displayed in BLOCK-characters
  3685.     ;  -----       on top of NEW, TOP, IPF, IPN, GBL and ALL, but not in
  3686.     ;              BBS, ORP, DUP, USR and FILES.BBS.
  3687.     ;              An unlimited number of 'Title'-lines may be specified.
  3688.     ;              The '`'-character (reverse quote) is translated into a half
  3689.     ;              width space, the '~'-character into a full width space.
  3690.  
  3691.     
  3692.                                  Appendix E.  Sample Configuration File  55
  3693.  
  3694.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  3695.     
  3696.     
  3697.     
  3698.     ;              Default: <none>
  3699.  
  3700.       Title        ~DownSort
  3701.       Title        ~~~from
  3702.       Title        ~Holland
  3703.  
  3704.     ;  PreTitle    Lines to be displayed immediately before the BLOCK-title.
  3705.     ;  --------    The lines will be copied as is. Leading blanks will be
  3706.     ;              skipped, no wrapping or truncation will be applied for
  3707.     ;              'long' lines. '~' (tilde) characters are translated to blanks
  3708.     ;              An unlimited number of PreTitle lines may be specified.
  3709.     ;              Empty PreTitle lines are ignored. To space lines in your
  3710.     ;              headers specify a PreTitle with a tilde.
  3711.  
  3712.       PreTitle     ~
  3713.       PreTitle     ~~~~~~~<─────────── P R E S E N T I N G ─────────────>
  3714.       PreTitle     ~
  3715.  
  3716.     ;  SubTitle    Lines to be displayed below the BLOCK-title.
  3717.     ;  --------    The same rules apply as for PreTitle.
  3718.     ;              Note: If an include file is specified on the xxxFileList
  3719.     ;              line, then this is inserted between block title and subtitle!
  3720.     ;              Default: <none>
  3721.  
  3722.       SubTitle     ~
  3723.       SubTitle     ~<────────────────────────────────────────────────────────>
  3724.       SubTitle     ~  Overview of downloadable files on this magnificent BBS
  3725.       SubTitle     ~<────────────────────────────────────────────────────────>
  3726.       SubTitle     ~
  3727.  
  3728.     ;  BottomLine  Lines to be displayed at the end of the filelist.
  3729.     ;  ----------  The same rules apply as for PreTitle.
  3730.     ;              Default: <none>
  3731.  
  3732.       BottomLine   ~
  3733.       BottomLine   ~~~~~~<──── How do you like DOWNSORT, folks? ────>
  3734.       BottomLine   ~
  3735.  
  3736.     ; DupNameSize  Indicates the number of characters of the fileNAME that are
  3737.     ; -----------  maximally to be compared to consider a name 'duplicate'.
  3738.     ;              Allows version numbers to be detected, for example:
  3739.     ;              with "DupNameSize 7" DWNSRT63.ZIP and DWNSRT64.ZIP will
  3740.     ;              appear as duplicates in the DupFileList report.
  3741.     ;              Default: 8
  3742.  
  3743.     ; DupNameSize  8
  3744.  
  3745.     ; NonDupEXT    Suppress reporting as 'duplicate' if 2 files with equal
  3746.     ; ---------    filenames but unequal extensions are defined as 'pair'.
  3747.     ;              The example specification below has the effect that files of
  3748.     ;              any pair "xyz.SDA" and "xyz.SDN"  ("xyz": any filename) will
  3749.     ;              not be listed in DupFileList.
  3750.     ;               -  Files with equal filename AND equal extension will
  3751.     ;                  still be reported as duplicate even when the extension
  3752.     ;                  is one of a 'NonDupEXT' pair!
  3753.  
  3754.     
  3755.                                  Appendix E.  Sample Configuration File  56
  3756.  
  3757.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  3758.     
  3759.     
  3760.     
  3761.     ;               -  Multiple extensions must be specified in as many pairs
  3762.     ;                  as can be formed (3 extension 3 pairs; 4 ext. 6 pairs;
  3763.     ;                  etc, e.g: for Nodelists:  DAT EXT  DAT IDX  EXT IDX).
  3764.     ;              You may specify multiple extension-pairs on a line
  3765.     ;              (separate the extensions with blanks), and as many lines
  3766.     ;              as needed. Wildcards are not supported.
  3767.     ;              Default: no suppression
  3768.  
  3769.       NonDupEXT    SDN SDA ZIP ARJ JPG GIF
  3770.  
  3771.     ; OrphanDesc   Description text of 'orphan' (file without entry in FILES.BBS)
  3772.     ; NotFoundDesc Description text of file without description in FILES.BBS.
  3773.     ; ------------ The description will replace the default text.
  3774.     ;              Up to 45 characters may be specified.
  3775.  
  3776.     ; OrphanDesc   ********  Orphan  *********
  3777.     ; NotFoundDesc *** Missing description ***
  3778.  
  3779.     ; OfflineDesc  When a filespecification is found in FILES.BBS but the file
  3780.     ; -----------  is not found in the corresponding download directory, this
  3781.     ;              text replaces the filesize and date (right aligned).
  3782.     ;              Up to 14 characters are accepted.
  3783.  
  3784.       OfflineDesc  [-archived-]
  3785.  
  3786.     ; AVAstrip     You may wish to strip off AVATAR graphics characters from
  3787.     ; --------     the contents of your FILES.BBS files.
  3788.     ;              Specify 'No' to deactivate stripping
  3789.     ;              ==> Works ONLY for COMMENT lines in ALL- and IPF-lists.
  3790.     ;                  remember: comments are only listed with KEEPSEQ.
  3791.     ;              Default: Yes
  3792.  
  3793.     ; AVAstrip     Yes
  3794.  
  3795.     ; HighASCII    Downsort generates some high-ASCII characters in its titles
  3796.     ; --------     and headers. Specify 'No' if you don't want these. Special
  3797.     ;              characters will then be substituted by a low-ASCII equivalent.
  3798.     ;              Note: Applies only to text generated by Downsort,
  3799.     ;                    not to file-descriptions, included files, etc..
  3800.     ;              Default: Yes
  3801.  
  3802.     ; HighASCII    Yes
  3803.  
  3804.     ; LinkPathSubst  Link Path Substitution
  3805.     ;6.4           This allows use of HTMFileList on an Internet server with
  3806.     ;6.4           download facility by 'clicking' the filename.
  3807.     ;6.4           With the keyword LinkPathSubst Downsort replaces (part of) the
  3808.     ;6.4           original filepath by a prefix referencing an Internet resource.
  3809.     ;6.4           Specification of this keyword in combination with a matching
  3810.     ;6.4           path prefix, has 2 effects:
  3811.     ;6.4           - a hypertext link will be generated
  3812.     ;6.4           - specified first part of BBS-filepath is replaced by the
  3813.     ;6.4             Internet resource reference.
  3814.     ;6.4           In case of 'overlapping' original paths, specify the most
  3815.     ;6.4           significant strings first. See some examples below.
  3816.  
  3817.     
  3818.                                  Appendix E.  Sample Configuration File  57
  3819.  
  3820.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  3821.     
  3822.     
  3823.     
  3824.     ;6.4           In the reference string backslashes are replaced by slashes.
  3825.     ;6.4           Default: No hypertext links on file level.
  3826.     ;
  3827.     ;                prefix original path .. to be substituted by
  3828.     ;                ====================    ====================
  3829.     ; LinkPathSubst  d:\files                http://server1.bbs
  3830.     ; LinkPathSubst  e:\download             ftp://server2.dl
  3831.     ; LinkPathSubst  ..\files\               ftp://server1/diskF/files/
  3832.     ; LinkPathSubst  i:\cdrom                ///i:/cdrom
  3833.  
  3834.     ; AreaOrder    Order in which areas have to be sorted in the lists.
  3835.     ;              Selection can be: Alpha   - Alphabetic order of areaname
  3836.     ;                                Group   - Group (FileDivision) order
  3837.     ;                                Include - order of areaINclude
  3838.     ;                                Keep    - Keep order of FAREA.DAT
  3839.     ;              Specify one of these type (first letter is sufficient).
  3840.     ;              Where areanames are involved in sorts, the sequence will be
  3841.     ;              according to AreaOrder. With 'Group' the areas will be sorted
  3842.     ;              alphabetically in sequence of the fully qualified areaname,
  3843.     ;              (including division prefixes), with 'Alpha' areas will be
  3844.     ;              in sequence of the unqualified areaname (ignoring divisions).
  3845.     ;              'Group' and 'Keep' will make division boundaries visible.
  3846.     ;              Note: 'Include' uses the AreaInclude specifications, which
  3847.     ;              are prefixes. Areas matching the same AreaInclude string
  3848.     ;              will be sorted in 'Keep' sequence.
  3849.     ;              Default: Group
  3850.  
  3851.     ; AreaOrder    Group
  3852.  
  3853.     ; ───────────────────────────────────────────────────────────────────────────
  3854.     ; Specification of individual List parameters.
  3855.     ; Some may override settings of the global common parameters.
  3856.     ; Abey this sequence: first global common, then specific parameters!
  3857.     ; ───────────────────────────────────────────────────────────────────────────
  3858.     ;
  3859.     ; xxxFileList:  Create a File lists of type 'xxx' (1 list per keyword)
  3860.     ;
  3861.     ; xxx ────┐          ┌── Specification of output
  3862.     ;         │          │
  3863.     ;         │          │        ┌── Additional options for
  3864.     ;                   │        │   each list individually:
  3865.     ;    ┌── ALL         │        │
  3866.     ;    ┌── BBS         │        │ -A     Alphabetic sort on filename
  3867.     ;    ┌── DUP         │        │ -Cn    Continuation-line indent
  3868.     ;    ┌── GBL         │        │ -D     Date sort (descending)
  3869.     ;    ┌── HTM         │        │ -F#    Font number for BLOCK title (1..5)
  3870.     ;    ┌── HTN         │        │ -G     Group (division) sort
  3871.     ;    ┌── IPF         │        │ -If    Imbed filespec
  3872.     ;    ┌── IPN         │        │ -K     Keep original FILES.BBS sequence
  3873.     ;    ┌── NEW         │        │ -O     Orphans to be reported / adopted
  3874.     ;    ┌── OK          │        │ -R     Remove 'not-found' file descriptions
  3875.     ;    ┌── ORP         │        │ -Sg    Select areagroup 'g'
  3876.     ;    ┌── TOP         │        │ -T[n]  Truncate file descriptions
  3877.     ;    ┌── USR         │        │ -Um    USRmodel logical name selection
  3878.     ;    │               │        │ -W[n]  Wrap file descriptions
  3879.  
  3880.     
  3881.                                  Appendix E.  Sample Configuration File  58
  3882.  
  3883.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  3884.     
  3885.     
  3886.     
  3887.     ;    │               │        │ -X     eXclude display of ACS in headers
  3888.     ;    │               │        │ nnn[P] entries limit: number or period
  3889.     ;    │               │        │        ('P' = Days | Weeks | Months)
  3890.     ;                           
  3891.     ;   ═══─═══════  ════════  ════════════════════════════════
  3892.     ;   xxxFileList  PathSpec [Option-1] [Option-2] . . . [Option-n]
  3893.     ;
  3894.     ;      The output 'PathSpec' is mandatory for each list.
  3895.     ;
  3896.     ;  The following options may be specified (in any sequence):
  3897.     ;     -A   sort files Alphabetically on filename (within area)
  3898.     ;     -D   sort files on Date/time of the files
  3899.     ;     -G   sort files on Group (division) name
  3900.     ;     -K   Keep sequence of files as they appear in FILES.BBS.
  3901.     ;          Note: not all sorts apply to all list types (but most do)
  3902.     ;
  3903.     ;     -Cn  Continuation Indentation of description: relative position
  3904.     ;          of description on second and following lines if wrapped
  3905.     ;          descriptions are used. 'n' will normally be the width of
  3906.     ;          a download counter field.
  3907.     ;          May be specified negative for left-indentation (e.g. -C-16)!
  3908.     ;
  3909.     ;     -F#  BLOCK title font. Choose for '#' a number from 1 to 5.
  3910.     ;          Valid numbers:   1 .. Simple font             (5x6 pattern)
  3911.     ;                           2 .. Pseudo-Stencil Font     (7x10 pattern)
  3912.     ;                           3 .. ROBoComputer Font       (7x8 pattern)
  3913.     ;                           4 .. Reversed Video RoboComp (7x8 pattern)
  3914.     ;                           5 .. Wide open font          (7x6 pattern)
  3915.     ;          See some samples of the fonts in the top of this file.
  3916.     ;          Default font is 3, which is hard coded in some parts of the lists.
  3917.     ;          By specification of '-F' or 'F0', you may suppress block titles
  3918.     ;          (maybe also on places where you still want 'm, experiment!).
  3919.     ;
  3920.     ;     -If  Imbed userfile ('f' is file-spec) immediately following the
  3921.     ;          block-title (if any). The contents of the file is included without
  3922.     ;          any translation, so beware of special characters and effects like
  3923.     ;          formatting (word-wrap) especially in IPF- and HTML-lists!
  3924.     ;          NOTEs: - does not apply to lists of 'Sysop'-type (like DUP, ORP)
  3925.     ;                 - BBSFileList imbeds always DOWNSORT.HDR and DOWNSORT.TRL
  3926.     ;
  3927.     ;     -O   Orphans to be reported in xxxFileList or adopted in FILES.BBS.
  3928.     ;          Definition: 'Orphans' are files in a download directory that
  3929.     ;          have no entry in the corresponding FILES.BBS.
  3930.     ;          The entries will get the 'OrphanDesc' and will be reported in any
  3931.     ;          xxxFileList when the flag -O is specified. But it has effect only
  3932.     ;          when also an ORPFileList is requested!
  3933.     ;          Default: orphans will NOT be listed or adopted.
  3934.     ;
  3935.     ;     -R   Remove 'offline' file-entries.
  3936.     ;          Definition: 'Offline' files have an entry in FILES.BBS, but are
  3937.     ;          not in the download directory of the corresponding area.
  3938.     ;          These files will be listed with 'offline' in the size/date field.
  3939.     ;          When you specify '-R' the file will not appear in the list, and
  3940.     ;          when specified on xxxFilePath, it will be removed from Files.Bbs.
  3941.     ;          Default: list and do not remove 'offline' file entries.
  3942.  
  3943.     
  3944.                                  Appendix E.  Sample Configuration File  59
  3945.  
  3946.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  3947.     
  3948.     
  3949.     
  3950.     ;
  3951.     ;     -Sg  Select AreaGroup for the list. 'g' should be a name defined with
  3952.     ;          AreaGroup keyword. The list will only contain areas of the
  3953.     ;          specified group. If the specified group is not defined the list
  3954.     ;          will be empty. If no group is selected the list will contain ALL
  3955.     ;          areas.
  3956.     ;          Default: Include all areas.
  3957.     ;
  3958.     ;     -T[n] Causes Truncation of long descriptions so that linelength will
  3959.     ;          not be exceeded and each file-entry will take just a single line.
  3960.     ;     -W[n] Causes Wrapping of long descriptions: the report will contain
  3961.     ;          as many lines as needed for the complete file description.
  3962.     ;          Both -T and -W may be followed by a number to specify the required
  3963.     ;          linelength (minimum 69, maximum 2000).
  3964.     ;6.4       Default 79 (ORP, DUP, IPF: 255; FILES.BBS, HTML: 1024)
  3965.     ;
  3966.     ;     -Um  USRmodel-name to be selected for USRFileList.
  3967.     ;          'm' should be the name of one of the specified USRmodel statements.
  3968.     ;          Default: nothing (no list generated).
  3969.     ;
  3970.     ;     -X   eXclude ACS reporting the area-headers.
  3971.     ;
  3972.     ;   nnn[P] Limit the number of file-entries to a maximum of 'nnn'.
  3973.     ;          If followed by Period-indicator ('D', 'W' or 'M') the list is
  3974.     ;          limited not by number, but by file-AGE in Days, Weeks or Months.
  3975.     ;          NOTEs: - the Period-letter does not apply to IPF-lists
  3976.     ;                 - ALL-lists can only be limited by period (not by number).
  3977.     ;                 - 'nnn' denotes maximum number of files on a VIEW-page.
  3978.  
  3979.     ; AllFileList  Allfiles.Lst
  3980.     ; AllFileList  list\Allfiles.new   2m -a -w -f5 -x           -IDownsort.Inc
  3981.     ; AllFileList  list\Allfiles.hob      -k -W         -sHOB    -IDownsort.Inc
  3982.     ; AllFileList  list\Allfiles.dos      -k -W         -snonOS2 -IDownsort.Inc
  3983.     ; BbsFileList  list\Bulletin.bbs   3w -d -w     -x
  3984.     ; DupFileList  list\Dupes.psq
  3985.     ; GblFileList  list\GblFiles.psq      -a -w   -c6            -IDownsort.Inc
  3986.       HtmFileList  list1\HTMfiles.htm     -a -w         -sOS2
  3987.     ; HtnFileList  list2\HTNfiles.htm 200 -k -w         -sOS2
  3988.     ; IpfFileList  list\Allfiles.Ipf  200 -k -w         -sOS2
  3989.     ; IpnFileList  list\Newfiles.Ipf   6w -g    -f1     -sOS2
  3990.     ; NewFileList  list\Newfiles.psq   2m -g -t -f2 -x -t -l1000
  3991.     ; OKFileList   list\Okfile.psq                               -iDownsort.mag
  3992.     ; OrpFileList  list\Orphans.psq       -g
  3993.     ; TopFileList  list\TOPfiles.psq   30 -a -w
  3994.  
  3995.     ;  NOTE: The IPF-list has the format of an INPUT-file for the Information
  3996.     ;        Presentation Facility Compiler (IPFC).
  3997.     ;        It should be compiled with:  "IPFC  Allfiles.IPF  /INF".
  3998.     ;        This will produce a file called Allfiles.INF, which is ready
  3999.     ;        to be viewed with the command:   VIEW  Allfiles
  4000.     ;        Note: For copyright reasons the IPFC compiler is not distributed
  4001.     ;              with DOWNSORT. It can be obtained with the IBM program
  4002.     ;              development toolkit for OS/2, and is part of many OS/2
  4003.     ;              compilers.
  4004.  
  4005.  
  4006.     
  4007.                                  Appendix E.  Sample Configuration File  60
  4008.  
  4009.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  4010.     
  4011.     
  4012.     
  4013.     ; ───────────────────────────────────────────────────────────────────────────
  4014.     ; USRFileList   Create a list of 'user format' lines with file information.
  4015.     ; -----------   It is designed to build batch-files for file maintenance.
  4016.     ;               The format of each line is a variable string. It is given a
  4017.     ;               name with the USRmodel keyword. The corresponding format is
  4018.     ;               the line immediately following the name (use no space-lines!).
  4019.     ;               The format-string may contain symbolic variables that will be
  4020.     ;               replaced by the actual value of file- or area-information
  4021.     ;               as follows:
  4022.     ;                %$ - ACS (Access Control String) of file area
  4023.     ;                %2 - duplicate file flag: '2' if duplicate file, '1' if not
  4024.     ;                %A - Areaname (fully qualified including division prefixes)
  4025.     ;                %C - file Creation date (fixed 8 characters)
  4026.     ;                %D - most recent of lastwrite and creation Date of file
  4027.     ;                %F - Filename.ext
  4028.     ;                %H - File-age in days
  4029.     ;                %N - Download count (from [nnn] in FILES.BBS file-desc)
  4030.     ;                %P - Path specification of the file's download directory
  4031.     ;                %S - file Size
  4032.     ;                %U - Unqualified areaname (without division prefix)
  4033.     ;                %W - file lastWrite date
  4034.     ;                %Z - file lastaccess date
  4035.     ;               Notes: - unknown symbolic variables are not substituted
  4036.     ;                      - to obtain '%' on the outputline specify: '%%'
  4037.     ;
  4038.     ;               A number of example statements as suggestions:
  4039.     ;               - The first USRmodel builds a batch file (REXX) to move
  4040.     ;                 Fernwood files from their original directory to a directory
  4041.     ;                 with areaname as the subdirectory-name of G:\Fernwood\.
  4042.     ;               - The second model will erase files older than 2 years but
  4043.     ;                 only when downloaded less than 5 times.
  4044.     ;               - The third model is a specification for a 'long' OKfile.
  4045.     ;               - The fourth model contains all symbolic variables
  4046.     ;                 supported by Downsort for USRFileList.
  4047.  
  4048.       USRmodel move
  4049.     move '%P%F G:\Fernwood\%U\'
  4050.       USRmodel old
  4051.     if %H > 730 & %N < 5 then  erase '%P%F'   /* check filedate: %D */
  4052.       USRmodel ok
  4053.     @%F %P%F
  4054.       USRmodel all
  4055.     %%$=%$ %%2=%2 %%A=%A %%C=%C %%D=%D %%F=%F %%H=%H %%N=%N %%P=%P %%S=%S %%U=%U %%W=%W %%Z=%Z
  4056.  
  4057.     ;  USRFileList  list2\usrlist1.cmd  -G  -Umove  -sOS2    -Idownsort.rex
  4058.     ;  USRFileList  list2\usrlist2.cmd  -G  -Uold            -Idownsort.rex
  4059.     ;  USRFileList  list2\usrlist3.OK   -a  -Uok
  4060.     ;  USRFileList  list2\usrlist4.all  -G  -Uall   -sOS2
  4061.  
  4062.     ; ─────────────────────────────────────────────────────────────────────────
  4063.     ;  Below follow the specifications for manipulating/rebuilding FILES.BBS
  4064.     ; ─────────────────────────────────────────────────────────────────────────
  4065.     ; FILFilePath  - First parameter is [optional] PATH-specification of
  4066.     ; -----------    destination directory of generated 'FILES.BBS' files.
  4067.     ;                Use for the pathspec the format:  drive:\path\
  4068.  
  4069.     
  4070.                                  Appendix E.  Sample Configuration File  61
  4071.  
  4072.     Maximus Download File Sort and List Utility (OS/2 and DOS)
  4073.     
  4074.     
  4075.     
  4076.     ;                If pathspec is specified the output-files will be called
  4077.     ;                "areaname.BBS" (any filedivision prefix removed). Long
  4078.     ;                areanames will be truncated to the first 8 characters.
  4079.     ;                If pathspec is not specified the MAXIMUS path specification
  4080.     ;                will be used (FileList parameter if used in Maximus'
  4081.     ;                FAREA.CTL, or otherwise Files.Bbs in the Download directory).
  4082.     ;              - Many but not all flags as defined for the other lists
  4083.     ;                apply to the FILES.BBS-output of Downsort, for example:
  4084.     ;                 - File-descriptions will be wrapped or truncated to
  4085.     ;                   lines with a maximum length of 1024 characters.
  4086.     ;                   Default: Wrap
  4087.     ;                 - Title specifications are ignored.
  4088.     ;                 - Entries can be sorted, but then you will loose your
  4089.     ;                   comments: -K (Keep sequence and comments!) is default.
  4090.     ;                 - Avatar codes will not be touched.
  4091.     ;              - When using group selection ('-Sg') and multiple FILFilePaths,
  4092.     ;                beware not to overwrite previous output (e.g. define and
  4093.     ;                use mutually exclusive groups, such as the OS2 and nonOS2
  4094.     ;                example above).
  4095.  
  4096.     ;  FILFilePath   list3\   -a    -R
  4097.  
  4098.     ; ────────────────────────────────────────────────────────────────────────
  4099.     ;
  4100.     ; End of sample Downsort.Cfg as provided with the orginal Downsort package.
  4101.     ;
  4102.  
  4103.  
  4104.  
  4105.  
  4106.  
  4107.  
  4108.  
  4109.  
  4110.  
  4111.  
  4112.  
  4113.  
  4114.  
  4115.  
  4116.  
  4117.  
  4118.  
  4119.  
  4120.  
  4121.  
  4122.  
  4123.  
  4124.  
  4125.  
  4126.  
  4127.  
  4128.  
  4129.  
  4130.  
  4131.  
  4132.     
  4133.                                  Appendix E.  Sample Configuration File  62