home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 2 BBS / 02-BBS.zip / dwnsrs59.zip / DOWNSORT.SCR < prev    next >
Text File  |  1993-12-19  |  100KB  |  2,276 lines
  1. :userdoc sec='Maximus Download File Sort and List Utility (OS/2 and DOS)'
  2. .*
  3. .* For printing: use Bookmaster profile.
  4. .*
  5. .* This file also compilable by IPFC (just ignore the errors!).
  6. .*
  7. :prolog.
  8. .*
  9. .* ==========================================================
  10. .* Translate macros for IBM host printing
  11. .*
  12. .dm on3270 on
  13. .if &$SYS ne pc .ti ╔  10 ╦  13 ╗  30 ╠  31 ╬  21 ╣  23
  14. .if &$SYS ne pc .ti ╚  12 ╩  22 ╝  32 ═  33 ║  11
  15. .if &$SYS ne pc .ti ┌  10 ┬  13 ┐  30 ├  31 ┼  21 ┤  23
  16. .if &$SYS ne pc .ti └  12 ┴  22 ┘  32 ─  33 │  11
  17. .if &$SYS ne pc .ti ╓  10 ╥  13 ╖  30 ╟  31 ╫  21 ╢  23
  18. .if &$SYS ne pc .ti ╙  12 ╨  22 ╜  32
  19. .if &$SYS ne pc .ti ╒  10 ╤  13 ╕  30 ╞  31 ╪  21 ╡  23
  20. .if &$SYS ne pc .ti ╘  12 ╧  22 ╛  32
  21. .if &$SYS ne pc .ti   35   25   26   36
  22. .if &$SYS ne pc .ti [  b0 ]  6a
  23. .dm off
  24. .*  ╔═╦════╗   ┌─┬────┐   ╓─╥───╖   ╒═╤═══╕      right arrow
  25. .*  ╠═╬════╣   ├─┼────┤   ╟─╫───╢   ╞═╪═══╡      left arrow
  26. .*  ║ ║    ║   │ │    │   ║ ║   ║   │ │   │      up arrow
  27. .*  ╚═╩════╝   └─┴────┘   ╙─╨───╜   ╘═╧═══╛      down arrow
  28. .dm off3270 on
  29. .if &$SYS ne pc .ti ╔ ╔ ╦ ╦ ╗ ╗ ╠ ╠ ╬ ╬ ╣ ╣ ╚ ╚ ╩ ╩ ╝ ╝ ═ ═ ║ ║
  30. .if &$SYS ne pc .ti ┌ ┌ ┬ ┬ ┐ ┐ ├ ├ ┼ ┼ ┤ ┤ └ └ ┴ ┴ ┘ ┘ ─ ─ │ │
  31. .if &$SYS ne pc .ti ╓ ╓ ╥ ╥ ╖ ╖ ╟ ╟ ╫ ╫ ╢ ╢ ╙ ╙ ╨ ╨ ╜ ╜
  32. .if &$SYS ne pc .ti ╒ ╒ ╤ ╤ ╕ ╕ ╞ ╞ ╪ ╪ ╡ ╡ ╘ ╘ ╧ ╧ ╛ ╛
  33. .if &$SYS ne pc .ti            
  34. .if &$SYS ne pc .ti [ [ ] ]
  35. .dm off
  36. .*
  37. .* Bookmaster tags voor deze macro's:
  38. .*
  39. .aa on3270 on3270
  40. .aa off3270 off3270
  41. .* ==========================================================
  42. .*
  43. .nameit symbol=VERSION text='5'.
  44. .nameit symbol=SUBVERS text='9'.
  45. .nameit symbol=SUFFIX  text=' '.
  46. .*
  47. :revision id=59 run=yes.
  48. .*
  49. :title.DOWNSORT
  50. &rbl.
  51. Maximus CBCS DOWNload file SORT and List Utility
  52. &rbl.
  53. Version &VERSION..&SUBVERS.&SUFFIX. (OS/2 and DOS)
  54. :etitle.
  55. :author.Rob Hamerling
  56. :date.
  57. :address.
  58. Vianen, The Netherlands
  59. Phone: ++31-3473-72136 (voice)
  60. FIDO-net: 2&colon.512/4.1098
  61. :eaddress.
  62. :docprof rhrfrule=none
  63.          language=english
  64.          figlist=nopage
  65.          tlist=nopage
  66.          ftsep=no
  67.          layout=2
  68.          fbc=no
  69.          toc=12
  70.          ldrdots=yes.
  71. :eprolog.
  72. :frontm.
  73. :tipage.
  74. :toc.
  75. :body.
  76. .* ==============================================================
  77. .* Contact addresses (beta-testers)
  78. .* Lody Caenen             2:280/801  BBS: 075-704045    voice: 075-158305
  79. .* Gerard van Essen                   BBS:               voice:
  80. .* Winston van Oosterhout  2:512/63   BBS: 01680-30617   voice:
  81. .* ==============================================================
  82. :h1.About Downsort
  83. :p.Downsort was originated in 1987 as a program for my own use when
  84. I was SYSOP of the Bulletin Board PC-Square (2:512/4), to automatically
  85. generate daily overviews of my download material for the users.
  86. The program name is related to the SORTing of the collection of
  87. DOWNloadable files, in DOWNward time-stamp sequence and an online
  88. Bulletin was the only list that was produced at that time.
  89. PC-Square was running BinkleyTerm and OPUS under DOS, and
  90. file-requesting was not so popular then.
  91. :p.Now PC-Square runs with OS/2, BinkleyTerm and MAXIMUS CBCS.
  92. I'm not SYSOP anymore but still strongly involved.
  93. As a contribution to PC-Square and the large international Bulletin
  94. Board community of MAXIMUS CBCS boards, and in the highly appreciated
  95. spirit of BinkleyTerm, I decided to upgrade my Downsort program to the
  96. current software.
  97. During the past years a lot of improvements and extensions have been
  98. made&colon. many user-configurable options for many more output formats
  99. then the original Downsort.
  100. :p.The only dependency of Downsort on MAXIMUS CBCS is a parameter-file
  101. AREA.DAT, which is usually created with a MAXIMUS utility (SILT(P)),
  102. which itself can be used without actually running MAXIMUS!
  103. This is the way I work for testing of Downsort.
  104. :p.:hdref refid=ahis. gives an impression of recent history.
  105. :p.Downsort is now developed in an OS/2 environment, but it is
  106. distributed as 'family'-application: it runs under OS/2 and DOS.
  107. Recently a 32-bits version for OS/2 2.0 has been added for OS/2 2.0 and up.
  108. :p.Downsort is in its 7-th year of development and has entered a period
  109. where life becomes more and more complicated.
  110. While adding new features, I have tried to maintain compatibility.
  111. This is a main cause of complications.
  112. Maybe in one of the newer versions I have to leave this compatibility in
  113. favour of maintainability and user-friendliness.
  114. In anticipation of this, please do not use undocumented features, or
  115. styles of usage that are not described in this document.
  116. .* --------------
  117. :rev refid=59.
  118. :h2.Quick start
  119. :p.I appreciate that you are eager to use Downsort.
  120. You don't have to make a comprehensive study of this document.
  121. But please read the comments in Downsort.Cfg before making the changes you
  122. consider appropriate.
  123. :p.And before reporting supposed bugs or missing features, please continue
  124. to read this document!
  125. :erev refid=59.
  126. .* --------------
  127. :h2.Registration and Shareware Fee
  128. :p.Downsort is a $ 0.00 Shareware (Freeware) Program.
  129. This means (to me) that you respect the commonly known rules for
  130. shareware, but you don't have to pay me anything.
  131. :p.Registration is voluntary&colon. please send me a netmail message
  132. with your name and (net-)address if you are a regular user of Downsort
  133. as SYSOP.
  134. That gives me an impression of the usage and the impact of changes to
  135. Downsort.
  136. :p.If you tell me that you are running Downsort on your Bulletin Board
  137. as service to your users, and you appreciate to be mentioned, I'll add
  138. your name to the reference list in :hdref refid=ause..
  139. .* --------------
  140. :h2.Warranty
  141. :p.For this price?
  142. You must be kidding!
  143. But I'll listen to your complaints and suggestions, and if time permits,
  144. I'll work on the improvements you suggested.
  145. .* --------------
  146. :h2.Acknowledgements
  147. :p.I would like to thank all users that contributed with constructive
  148. remarks and encouraging appraisals.
  149. Without doubt Emmanuel Sandorfi, former SYSOP of 2&colon.320/5, holds
  150. the record in number of suggestions and amount of additionally required
  151. programming effort.
  152. He also provided some additional title-fonts (2 and 3).
  153. :p.I also would like to thank the regular users (SYSOP's of Bulletin
  154. Boards) who made Downsort much more popular than I ever dreamed of!
  155. A collection of geographically dispersed Boards can be found in
  156. :hdref refid=ause..
  157. .* =============================================
  158. :h1.Overview
  159. :p.Downsort is a program to make lists of available download files
  160. for Bulletin Board Systems, especially MAXIMUS CBCS.
  161. The different types of lists are each for a specific audience
  162. (online bulletin board user, file-requestor, SYSOP) and purpose
  163. (all files, recent acquisitions).
  164. Within each type there are many ways to customise the contents
  165. (selection on user-privilege or user-interest), and format
  166. (sort-sequence of files, titles, logo, etc).
  167. :p.Downsort can produce the following report-types :fnref refid=usys.
  168. for you:
  169. :fn id=usys.For the target audience the distiction between 'user' and
  170. 'sysop' is strictly the author's view!
  171. :efn.
  172. (:hp2.all these can be produced in one run:ehp2.).
  173. :ul.
  174. .*
  175. :li.user-lists
  176. :ul compact.
  177. :li.BBS-list, a colorful overview for :hp2.online:ehp2. users of
  178. MAXIMUS CBCS
  179. :li.NEW-list of the most recent files
  180. (as a response to a file-request of 'NEWFILES')
  181. :li.ALL-list for a complete overview in a file-group per area
  182. (as a response to a filerequest of 'FILES' of 'ALLFILES')
  183. :li.IPF-list similar contents as ALL-list, but in a different
  184. presentation format (VIEW-able under OS/2)
  185. :li.GBL-list for a complete overview over the area-boundaries,
  186. as an alternative for ALL-list if you don't want to bother
  187. file-requestors with your area-structure
  188. :eul.
  189. .*
  190. :li.SYSOP lists:
  191. :ul compact.
  192. :li.ORPHAN-report as a help with management of the contents of your
  193. area's and directories, and to correct possible upload problems or
  194. inconsistencies
  195. :li.DUP-list for a list of duplicate filenames as a help to control your
  196. disk-space and with version management.
  197. :li.OKFile for (Binkley) File Requests.
  198. :li.EMI-list for a list of new file arrivals to be included in an
  199. announcement message.
  200. :li.Updated FILES.BBS files
  201. :eul.
  202. .*
  203. :eul.
  204. :p.The lists can be generated for different privilege levels,
  205. and be customised to a very high extend to present your system as you
  206. like it to be seen by your users (headers, log, etc).
  207. At the same time Maximus (and OPUS) conventions are reflected in the
  208. way the file information is presented.
  209. :p.A sample of most of these lists can be found in :hdref refid=lsmp..
  210. :p.In short: Downsort is a very versatile tool to manage your database
  211. of files, both in an OS/2 and DOS environment.
  212. .* ------------------------
  213. :h2.Purpose and Objectives
  214. :p.Downsort is designed for the following purposes:
  215. :ol.
  216. :li.Produce different overviews of files which are available for
  217. download by online users of the Bulletin Board and by File Requestors.
  218. QUICK and EASY file retrieval is the main goal for the lists.
  219. Therefore many lists-types and within a type several variations
  220. should be available for SYSOP and users.
  221. :li.Should not disclose files to users (file-requesters) without
  222. positive agreement by SYSOP.
  223. :li.Detect discrepancies between the contents of FILES.BBS and the
  224. corresponding download directory, such as:
  225. :ul compact.
  226. :li.The directory contains so called :hp2.orphan:ehp2.-files, which have
  227. no descriptive entry in FILES.BBS.
  228. :li.FILES.BBS contains entries of which the file in not in the directory
  229. (is 'offline').
  230. This may be on purpose!
  231. :eul.
  232. :li.Must be able to be run unattended (typically overnight).
  233. The file-access privilege system of a Bulletin Board System like Maximus
  234. CBCS should be respected by the reports.
  235. :eol.
  236. .* ==============================================
  237. :h1 id=guide.User's Guide
  238. :p.This chapter explains the possibilities of Downsort.
  239. Parameter specifications will be covered in :hdref refid=specs..
  240. .* --------------------------------
  241. :h2.Initial setup
  242. :p.When you are going to use Downsort for the first time, you have to
  243. make a number of decisions.
  244. Below you'll find a kind of check-list, which is setup to help you with
  245. a logical sequence of tasks to make the use of Downsort succesful.
  246. It does NOT give detailed specifications, these can be found in
  247. :hdref refid=specs..
  248. :p.The specifications will be put into a configuration file
  249. Downsort.CFG, which may contain information about:
  250. :ol.
  251. .*
  252. :li.Data Collection
  253. :p.File information will be collected from:
  254. :ul compact.
  255. :li.Privilege and download path-information from AREA.DAT
  256. :li.Actual file-information from download directories
  257. :li.FILES.BBS files for file descriptions
  258. :eul.
  259. .*
  260. :li.List Type Selection
  261. :p.Downsort can produce the following report types for you (all in one run).
  262. :ul compact.
  263. :li.ORPHAN-report for SYSOP use only
  264. :li.BBS-list for :hp2.online:ehp2. users of MAXIMUS CBCS
  265. :li.NEW-list(s) for a list of the most recent files
  266. :li.ALL-list(s) for a complete overview in a file-group per area
  267. :li.IPF-list(s) same as ALL-list, but in a different presentation format
  268. (VIEW-able under OS/2,
  269. there is a special IP2-list for OS/2 2.0).
  270. :li.GBL-list(s) for a complete overview over area-boundaries
  271. :li.DUP-list(s) for a list of possibly duplicate filenames
  272. :li.OKFile(s) for (Binkley) File Requests
  273. :li.EMIFile(s) to for a list of file arrivals over the last period
  274. :li.Updated FILES.BBS files
  275. :eul.
  276. .*
  277. :li.File selection
  278. :p.Reporting of file-information can be limited by:
  279. :ul compact.
  280. :li.Reporting privilege: only those files up to a certain privilege
  281. level will be listed
  282. :li.Area INclude or EXclude: for sub-selection for special interest
  283. groups
  284. :rev refid=59.
  285. :li.Maximus area key/lock system
  286. :li.Explicit exclusion by specification of filespecs (wildcards)
  287. :erev refid=59.
  288. :li.Number of files or period (days, weeks or months) to be reported
  289. :eul.
  290. .*
  291. :li.List Customisation
  292. :p.The layout of the lists can be jazzed-up with:
  293. :ul compact.
  294. :li.BLOCK-title and its font
  295. :li.TopTitle, SubTitle, BottomTitle, Include (logo-) file
  296. :li.Sorting sequence of area's in ALL-list (unsorted, name, include)
  297. :li.Sorting sequence of files (unsorted, date, filename)
  298. :li.Truncation, or wrapping and indenting of file descriptions
  299. :li.Area- or file-privilege information
  300. :li.Message and Warning texts
  301. :li.Handling of Avatar codes in comment lines (strip or mimic).
  302. :eul.
  303. :p.All in the language which suites your audience best.
  304. :eol.
  305. :p.The sample Downsort.CFG file (see :hdref refid=acfg.) contains
  306. defaults and a brief information to help you with the
  307. parameter specifications.
  308. :p.Below you can find some more explanation.
  309. .* ----------------------------
  310. :h2.Data Collection
  311. .*
  312. :h3.AREA.DAT
  313. :p.A MAXIMUS file 'AREA.DAT' is absolutely required by Downsort.
  314. It is however not necessary to run MAXIMUS yourself,
  315. the AREA.DAT file is created with SILT(P) from the MAXIMUS package.
  316. You can use this utility without the other MAXIMUS stuff.
  317. In fact I do that myself (NOT running a MAXIMUS board)!
  318. If you run Downsort in a directory without AREA.DAT, then you should use
  319. specify the filespec for AREA.DAT.
  320. It allows also to specify a different AREA.DAT file than the one that is
  321. used by your MAXIMUS.
  322. :p.With SILT(P) you may build a special AREA.DAT for exclusive use by
  323. Downsort, with different, less, or even more directories!
  324. Probably much more convenient is the use of AreaINclude or
  325. AreaEXclude in Downsort.CFG to limit the contents of the lists to
  326. a group of area's, that you want to report together, while you use the
  327. regular AREA.DAT.
  328. A combination of a 'special' AREA.DAT and AreaIN/EXcludes is another
  329. option to obtain areagroups.
  330. :p.Remember: The combination of area privilege in AREA.DAT and the
  331. report-privilege specification in Downsort.CFG may restrict the contents
  332. of reports.
  333. AreaINclude is subordinate to this and will work only for the collection
  334. of area's within these privilege limits.
  335. :rev refid=59.
  336. Area-selection on Maximus' userkey may be another restriction.
  337. :p.In addition files may explicitly excluded during the data collection
  338. process by specification of a number of filespecifications (wildcards
  339. allowed).
  340. :erev refid=59.
  341. :p.If Downsort reports a memory constraint (see also :hdref refid=perf.),
  342. you may use these techniques as circumvention: exclude one or more of
  343. the file area's and rerun Downsort.
  344. .*
  345. :h3.FILES.BBS
  346. :p.Downsort uses the information in AREA.DAT to locate the description
  347. files, usually called FILES.BBS.
  348. So either the ListFile specification in AREA.DAT, or the download
  349. directory to locate them (Maximus default).
  350. .* -----------------------------------
  351. :h2.List Type Selection
  352. :p.Downsort can produce several types of output reports,
  353. indicated by type of list.
  354. The following list types are available
  355. :rev refid=59.
  356. (all list types may be generated in multiple variants within one run of
  357. Downsort, i.c. with a single directory scan!).
  358. :erev refid=59.
  359. .* ---
  360. :h3 id=orphan.ORPHAN-list
  361. :p.This is a list of all files in download directories for which
  362. there is no entry in any FILES.BBS file of all areas which have this
  363. directory specified as download path.
  364. The report contains date, area-name and area-path of the orphan.
  365. The entries are sorted on area and filename.
  366. :rev refid=59.
  367. :p.Not reported are the files that match all FileEXclude specifications.
  368. Normally you would exclude FILES.*, *.BAK, DIR.?BS and SYSTEM*.?BS.
  369. :erev refid=59.
  370. :p.If you have more than 1 area pointing to the same download directory,
  371. but with different FILES.BBS files, the orphans are reported for the
  372. first of these areas only.
  373. :note.If there is an entry for a file in FILES.BBS without a
  374. description, the file is NOT considered to be an Orphan!
  375. .* ---
  376. :h3.BBS-list
  377. :p.This is a list of downloadfiles that became recently available
  378. on your system.
  379. File selection is on date, but for presentation the list may be sorted
  380. on date, newest first or on filename.
  381. :p.The list contains compiled MECCA control sequences, for direct use in
  382. MAXIMUS bulletins: a user-privilege sensitive list!
  383. It might be a good idea to put a translated &lbrk.onexit&rbrk. string,
  384. which translates into: &caret.OFpath.
  385. When a user exits from the BBS-list bulletin, it will fall back to the
  386. exit-bulletin.
  387. :p.The length of the file (number of file-entries) may be limited by
  388. parameters:
  389. :ul compact.
  390. :li.file-count
  391. :li.file age in days, weeks or months (30 days)
  392. :li.maximum privilege
  393. :eul.
  394. :p.(never more than available within the privilege limit).
  395. If neither specified it will contain all available files in all download
  396. directories.
  397. :p.To make it easy for you to build a complete MAXIMUS bulletin-file a
  398. user-provided header is included preceding the list and a trailer at the
  399. end of the list.
  400. Header and trailer can be built by SYSOP, and may contain any
  401. information and bulletin-control sequences (a sample is provided).
  402. .* ---
  403. :h3.NEW-list
  404. :p.Basically the same list as above, but in simple ASCII format.
  405. This list is suitable for regular file-requestors as brief overview
  406. of the latest additions, updates or replacements.
  407. .* ---
  408. :h3 id=emi.EMI-list
  409. :p.Basically the same as NEW-list, but more compact:
  410. :ul compact.
  411. :li.contains file also file-time and exact filesize in bytes.
  412. :li.Description wrapping (if used) is overlapping the file-details
  413. except filename (may be justified with indentation).
  414. :eul.
  415. :p.The EMI-list is especially suitable to generate file-arrival messages
  416. (the output should be included by another program).
  417. .* ---
  418. :h3.ALL-list
  419. :p.A list of all downloadfiles by area.
  420. Files of the same area are listed in groups, separated by imbedded
  421. headers with area-name, -description, and -privilege.
  422. Actual status information is provided in the area-header as well:
  423. area-filecount and -bytecount, and latest acquisition (date and
  424. file-name).
  425. :p.At the end a SUMMARY report shows per area: area-title,
  426. file-count, byte-count, and totals.
  427. :p.The size of this list is limited only by the privilege parameter.
  428. The numbers in area-header and summary report show only what is
  429. available for the particular privilege.
  430. .* ---
  431. :h3.IPF- and IP2-list
  432. :p.Same contents as ALL-list but in a different format.
  433. Only useful for users that run OS/2 (OS/2 version 1.2+ under
  434. Presentation Manager).
  435. This file has the format of an input-file for the Information
  436. Presentation Facility Compiler (IPFC).
  437. :p.There is a separate form of this list (called IP2-list) for OS/2 2.0.
  438. It produces information that can be compiled only with the accompanying
  439. IPF Compiler of the OS/2 2.0 Toolkit.
  440. The result however can be VIEWed under OS/2 1.3!
  441. .* ---
  442. :h3.GBL-list
  443. :p.Similar to ALL-list,
  444. but where ALL-list gives the files in groups per area, the GBL-list
  445. ignores area-boundaries and gives a single group.
  446. It contains an extra column with the area-code for each file, there is
  447. no area-summary.
  448. :p.SYSOP may choose which of both is suitable to make available to
  449. users, and which to use for himself (or even both).
  450. :p.The GBL-list can be used in stead of the ALL-list if your users
  451. prefer searching in the list without having to bother about
  452. area-organisation.
  453. Although one of the original purposes of the GBL-list was checking for
  454. duplicate files, there is now also a special report for this particular
  455. purpose (see :hdref refid=dup.).
  456. .* ---
  457. :h3 id=dup.DUP-list
  458. :p.Simple report of :hp2.possibly:ehp2. duplicate files over the area's.
  459. The format is basically the same as the GBL-list, but only files with
  460. the :hp2.same filename:ehp2. are reported.
  461. 'Offline' files are included in the check, orphans are not!
  462. :p.Please note that the DUP-list may not always contain what you expect.
  463. It can be more or less, for example:
  464. :ul compact.
  465. :li.Downsort looks primarily at filenames only (extension is of second
  466. importance, path is completely ignored).
  467. :li.You may have explicitly excluded area's from the search.
  468. :li.You may have excluded area's by privilege: Downsort completely
  469. ignores area's with a higher privilege than any report asked for.
  470. :li.You have duplicates in 'orphan'-state.
  471. :eul.
  472. :p.These circumstances may give 'false' signals or hide duplicates!
  473. :p.All duplicate files within the privilige-range will be reported,
  474. even when a counterpart has a higher privilege or are orphan (and thus will
  475. not be reported in the DUP-list)!
  476. You may need a file-finder-utility to search for the 'partner'-file
  477. in one of the directories with a higher privilege.
  478. :p.There are very few other parameters applicable to this list.
  479. File descriptions may be specified as truncated or wrapped.
  480. All user-titles are left out and only a sort on filename is
  481. supported.
  482. :p.Suppression of reporting files with equal filenames and different
  483. extensions is possible with the "NonDupEXT" keyword in Downsort.Cfg.
  484. You specify pairs of extensions.
  485. Two files with equal filename and one of each having an extension specified
  486. as 'pair' will not be reported as duplicate.
  487. For example, if you specify:
  488. :xmp.
  489.    NonDupEXT  SDN  SDA
  490. :exmp.
  491. then file pairs xyz.SDN and xyz.SDA will not be reported in the DUP-list.
  492. :p.This pair-exclusion can also be used for more than 2 extensions, but
  493. the exclusion works only for pairs of files.
  494. So then you must specify as many pairs as can be formed.
  495. For example if you want to exclude file combinations like xyz.IDX
  496. xyz.DAT and xyz.EXT, then you should specify:
  497. :xmp.
  498.    NonDupEXT  IDX DAT  IDX EXT  DAT EXT
  499. :exmp.
  500. :warning.The check on duplicates by Downsort works only when you specify all
  501. possible pairs of extensions!
  502. If you fail to specify any possible pair, the Dup-list may contain false
  503. signals.
  504. :ewarning.
  505. :p.Multiple pairs may be specified on a line, and multiple lines are
  506. allowed.
  507. .* ---
  508. :h3 id=okf.OKFile
  509. :p.List filespecifications for file-requests in BinkleyTerm style.
  510. The generated paths in the list obey the following rules:
  511. :ul.
  512. :li.the area-privilege is within the privilege limit of the report
  513. :li.the area is not excluded (by areaEXclude)
  514. :li.the area has at least 1 file within the privilege limit of the
  515. report
  516. :eul.
  517. :p.The paths are sorted on area-name (although the area-name is not part
  518. of the list).
  519. There is no check on duplicate paths.
  520. :p.The list is not jazzed-up with titles, etc, but a file may be included in
  521. front of the list if specified on the OKFileList in Downsort.CFG (see :hdref
  522. refid=acfg.).
  523. This option allows you to insert a list of 'magic' names in the OKFile.
  524. :p.Two formats are available:
  525. :ul compact.
  526. :li.SHORT format with lines in the format "filepath\*.*".
  527. This is the regular format for BinkleyTerm and other mailers.
  528. :li.LONG format with lines in the format: "@filespec  filepath\filespec".
  529. All files have a 'magic'-name assigned and there are no generic file
  530. specifications in the OKFileList.
  531. This prevents directory searches for BinkleyTerm for each file request.
  532. :eul.
  533. :note.Some newer versions of BinkleyTerm can use the file base of Maximus
  534. to find a file even faster.
  535. .* ---
  536. :h3 id=filbbs.Rebuild FILES.BBS
  537. :p.New "FILES.BBS" type of file may be (re-)created, one for every area.
  538. The contents of the file-information will be about the same as
  539. the original FILES.BBS, but with the following notes:
  540. :ul compact.
  541. :li.A header is generated with area-name, -title, and -privilege.
  542. Also the total amount of files and bytes and the most recently acquired
  543. new file in this area is part of the header information.
  544. :li.Files with a privilege up to and including the area-privilege
  545. are listed first.
  546. :li.Files can have a privilege other than the area-privilege when the
  547. original FILES.BBS file contains &caret.Pp-sequences ('p' being a
  548. privilege letter).
  549. This construction will be rebuilt by Downsort.
  550. Files with a higher privilege than the area-privilege will follow
  551. after a compiled MECCA-sequence (&caret.Pp) in the new FILES.BBS.
  552. Downsort respects these indicators when reading FILES.BBS,
  553. so all file-privilege information is retained.
  554. This ensures no accidental loss of file-information, and the regular
  555. user won't see more than he should.
  556. :li.Wild-card specifications in the original FILES.BBS are not
  557. propagated to the new FILES.BBS.
  558. :li.The file description is kept internally as a single string
  559. of about 2 KBytes (Maximus 2.0 supports up to 240 bytes!)
  560. When creating FILES.BBS files, this will be the file format (single
  561. record per file-entry).
  562. The original FILES.BBS may contain a (long) single string
  563. description, or multiple (short) multiline descriptions.
  564. When encountering multi-line descriptions in input-FILES.BBS, Downsort
  565. concatenates the separate description lines with a single intermediate
  566. space up to a maximum of 2 KBytes.
  567. This will be the output format if the FIL-list is requested.
  568. :li.Comments in FILES.BBS will be preserved :hp3.only:ehp3.
  569. when the Keep-Sequence option is used (specify /K on the FilFileList
  570. line of Downsort.Cfg).
  571. :eul.
  572. :p.Special attention is requested for the following:
  573. :ul compact.
  574. :li.The first 8 lines, :hp2.if comments:ehp2. (starting with a
  575. '-'-character), are discarded.
  576. These lines are assumed to be the standard header for FILES.BBS of Downsort.
  577. :li.Downsort from version 5.7 recognises its own headerlines with the
  578. characters: <-><&delta.><&delta.><backspace><backspace> for each of its
  579. header-lines, and will skip all lines starting with this sequence during the
  580. data collection phase, even when encountered after line 8.
  581. :li.You can include your own file with the /I-option on the FILFilePath
  582. line in Downsort.Cfg in the header of FILES.BBS.
  583. All lines in the include-file for FILES.BBS output will be prefixed by
  584. Downsort with the 5-character sequence mentioned above to make sure that
  585. these will also be 'refreshed' by Downsort.
  586. :eul.
  587. :p.The destination of FILES.BBS-files is not by definition the same as
  588. the origin!
  589. When specified with the "FIL&colon."-parameter (or in the configuration
  590. file), the output may be located in a different directory than the
  591. original input FILES.BBS.
  592. :p.When the output is directed to a separate directory, the files will
  593. be named as follows:
  594. :dl tsize=14 termhi=2.
  595. :dt.FILES.ac
  596. :dd.when :hp2.all:ehp2. areanames (areacodes) of the selected areas in a
  597. single run of Downsort are 3 bytes or less.
  598. :dt.areaname.BBS
  599. :dd.when :hp2.any:ehp2. areaname is longer than 3 bytes.
  600. :edl.
  601. :p.The format of the header will be slightly different.
  602. Font specification (/Fx in FILFileList) works for the second case only.
  603. :p.Manual checking or post-processing by some other program may follow
  604. Downsort, after which the files might be put back on the MAXIMUS
  605. specified position.
  606. .* ------------------------------
  607. :h2 id=select.Data Selection
  608. :rev refid=59.
  609. :p.During the data collection phase of Downsort, files are selected on
  610. several criteria.
  611. Generally speaking not more information is collected than needed for all
  612. lists in a single run of Downsort.
  613. :p.During the list creation phase a further file selection may take place.
  614. :p.Apart form the short OK-list, all lists are created from the file
  615. information.
  616. This means for example that if a selection is such that no files of a
  617. certain area fall within the list criteria, the area will not appear in any
  618. list.
  619. :erev refid=59.
  620. .* ---
  621. :h3.Privilege control
  622. :p.The default file privilege to be shown in the lists is SYSOP.
  623. All files with a higher privilege than the specified (or defaulted)
  624. report-privilege will not appear in the lists.
  625. :p.Files without a matching filename-entry in FILES.BBS are treated as
  626. Hidden.
  627. That means that by default these files will not be listed,
  628. unless the 'H' privilege is used on the report-request specification.
  629. :p.If you run a mailer like BinkleyTerm and support file-requests, you
  630. lack the extensive privilege system like Maximus.
  631. The only distiction BinkleyTerm makes with file-request is
  632. 'unknown', 'known' and 'password-protected'.
  633. You may generate multiple download lists with different privilege
  634. indictor, depending if you allow these categories to request different
  635. file collections a sample of this kind of environment is given in
  636. :hdref refid=sampl..
  637. :p.This is not needed for Downsort.BBS, since this file has imbedded
  638. privilege control sequences for MAXIMUS users.
  639. But you should specify a sufficiently high privilege for the BBS-list to
  640. satisfy your most valuable users!
  641. .* ---
  642. :h3.AREA selection
  643. :rev refid=59.
  644. :p.There are several ways to perform area selection:
  645. :ol.
  646. :li.AREA.DAT file needs not be the regular complete AREA.DAT used by your
  647. online Maximus system.
  648. :li.AreaINclude and/or AreaEXclude statements may select groups of area's
  649. by name from the used AREA.DAT file.
  650. :li.Individual list specifications may further reduce the lists on file
  651. privilege and userkeys.
  652. The latter makes use of the Maximus feature called 'key/locks'.
  653. :eol.
  654. :erev refid=59.
  655. :p.You should realise that this is the latest selection during the data
  656. collection phase.
  657. Area-privilege selection has taken place already before AreaIN/EXclude,
  658. or UserKeys are processed.
  659. So make sure you specified a sufficiently high report-privilege to get
  660. the proper areas into the group.
  661. :rev refid=59.
  662. :note.During the reporting phase you may further restrict file-reporting
  663. with privilege, userkeys or time period!
  664. :erev refid=59.
  665. .* ---
  666. :rev refid=59.
  667. :h3.Filename selection
  668. :p.A completely separate selection is possible on filename.
  669. Downsort scans download directories and collects data of all files
  670. (except those with the hidden or system attribute).
  671. With the keyword FileEXclude in Downsort.cfg, you may indicate which files
  672. you want to exclude from processing by Downsort, based on filename.
  673. With one or more filespecs, wildcards allowed, all files with matching
  674. filespec will be excluded during the data collection phase, regardless of
  675. the area.
  676. The current implementation supports only the traditional 8.3 filename.ext
  677. format, no long names and no explicit path.
  678. :p.In versions of Downsort before 5.9 the hardcoded specification of
  679. certain 'system' files has been removed, and these filespecs should now be
  680. specified in Downsort.cfg.
  681. The sample Downsort.cfg does contain these specifications.
  682. I suggest to leave that line asis and add one or more new lines for your own
  683. use.
  684. :warning.FileEXcluded files will even not appear in the FILES.BBS (re-)created
  685. by Downsort!
  686. :ewarning.
  687. :erev refid=59.
  688. .* ---
  689. :h3.Report length
  690. :p.For lists that are meant to show the latest file-information only
  691. (BBS-, NEW- and ALL-list), the length of the list can be limited to
  692. a maximum number of file-entries or to file-age in days, weeks or
  693. months.
  694. .*
  695. .* ------------------------------
  696. :h2.List Customisation
  697. .*
  698. :h3.Headers, Titles and Include files
  699. :p.There are several ways to custimise the appearance of the lists for
  700. Downsort.
  701. All items in the following list are optional, but the sequence in the
  702. reports is fixed and as listed:
  703. :dl tsize=12 termhi=2.
  704. :dt.Pre-Title
  705. :dd.Lines that should appear as the very first lines of your lists.
  706. Any text may be specified.
  707. Leading '&tilde.'-characters (tilde) will be treated as full-size required
  708. blanks, mainly to manually align (center) the text in these lines.
  709. There is no automatic centering.
  710. You may have to experiment a little.
  711. :dt.TITLE
  712. :dd.A short title (8-12 characters), that will be magnified to big
  713. BLOCK-letters.
  714. There are 4 block-fonts to choose from.
  715. Not all characters are supported and lower-case will be translated to
  716. upper-case.
  717. The '&tilde.'-character (tilde) will be treated as full-size required
  718. blank, the '&grave.'-character (accent-grave) as half-size required
  719. blank.
  720. :p.If not specified, a default title is generated as Downsortxy, where
  721. xy stands for the current version of Downsort.
  722. :dt.TitleFont
  723. :dd.Number of the font to be used for the BLOCK title.
  724. If specified as 0, the BLOCK-title will NOT be generated at all.
  725. :dt.Include-file
  726. :dd.A text-file to be included.
  727. There will be no manipulation of the contents of this file.
  728. This include-file may be all you need to obtain a fully custimised list.
  729. For the IPF-list this include file will most likely have to contain IPF
  730. tags for proper formatting,
  731. for the OK-file it will be a list of 'magic' name entries.
  732. :dt.Sub-Title
  733. :dd.Lines that should appear immediately following the block-title.
  734. :dt.BottomTitle
  735. :dd.Lines that should appear as very last lines of the lists.
  736. These follow my 'signature'.
  737. :edl.
  738. :p.The BLOCK-title and Pre-, Sub-, and Bottom-titles are used for all
  739. reports identically, there is no such thing as an 'individual' title
  740. specification for each report.
  741. However the Include-file may be different for each report.
  742. If you want to build more than 1 list but with different 'headings'
  743. or no headings at all, you better forget the Title-options.
  744. In stead make heading-files and use the Include option of the individual
  745. list specifications.
  746. :note.Exceptions:
  747. :ol.
  748. :li.None of the above does apply to the BBS-list.
  749. As it will generally be desirable to imbed (compiled) MECCA control
  750. sequences in this type of lists, this report will include dedicated top
  751. and bottom files (if available in the current default directory).
  752. These files must be called Downsort.HDR (header) and Downsort.TRL
  753. (trailer).
  754. :li.The ORPHAN report will not contain any user-titles.
  755. :li.The FILES.bbs files will not use any of the title-specifications,
  756. but may use an Include-file.
  757. :eol.
  758. :p.:hp2.Recommendation:ehp2.&colon. File-requestors appreciate a header
  759. with a clear indication of the source of the reports.
  760. Many Bulletin Boards use FILES or ALLFILES as 'magic' name,
  761. but that is not very distinctive if you collect lists of different
  762. boards!
  763. So use Downsort's facilities to generate a block-title with your
  764. system-name, or an include file with some kind of logo.
  765. :note.Specification details and samples can be found in Downsort.CFG.
  766. :p.Some SYSOPs do not like to confront their users with privileges.
  767. In most headers there will be a line with the reporting privilege.
  768. This may be suppressed.
  769. .* ---
  770. :h3.File Sorting
  771. :p.The file-entries in the lists can be sorted on different keys:
  772. :ul.
  773. :li.Filedate
  774. :li.Filename
  775. :li.Sequence of FILES.BBS
  776. :eul.
  777. :p.The default sorting sequence depends on the type of list.
  778. Some lists do not support some of these sorting keys.
  779. :note.File sorting has a local scope.
  780. It can be specified for to each listtype individually.
  781. .* ---
  782. :h3.Area Sorting
  783. :p.The order in which the areas are presented in the lists can be
  784. specified:
  785. :ul compact.
  786. :li.Order of AREA.DAT
  787. :li.Sorted alphabetically on areaname
  788. :li.Order of areaINclude statement in Downsort.Cfg
  789. :li.Groupname-order
  790. :eul.
  791. :p.The Groupname-order is a special order based on a popular naming
  792. convention for areas.
  793. Many SYSOPs use areanames with a group-name or -letter followed by a
  794. sequence number.
  795. With groupname sorting the areaname is split - if possible - into a
  796. groupname (if the first character is not be numeric) and a sequence number
  797. (if the last part of areaname is numeric).
  798. Primary sort key is groupname, secundary sortkey is sequence number.
  799. If the first character of the area-name is numeric, the groupname
  800. is empty, and if the last part of the areaname is not numeric, the
  801. second key is empty.
  802. :p.If the ordering does not match your more complicated area naming
  803. convention, you can always fallback on a properly sequenced AREA.DAT,
  804. or on areaINclude sequence.
  805. :p.If Include-order is specified, but AreaINclude is not, then the
  806. order falls back to Group-order.
  807. :p.The area-order specification has a global scope.
  808. It applies to every lists where the areaname is significant, including
  809. summaries in ALL- and IPF-lists.
  810. :p.Default sorting order is 'Group'.
  811. .* ---
  812. :h3.Warnings, Indications, Descriptions and Comments
  813. :ul.
  814. :li.There are two options for long file descriptions
  815. (those that do not fit on a 80-character line):
  816. :ul compact.
  817. :li.Truncation at end-of-line
  818. :li.Wrapping to multiple lines
  819. :eul.
  820. :p.Both options are available for all lists,
  821. but the defaults vary with the type of the report.
  822. If wrapping is used indentation of continuation lines.
  823. .*
  824. :li.Orphan description:
  825. Text that will be reported in the description column of a file, when
  826. for this file no entry in FILES.BBS could be located.
  827. :p.Default: "--- Orphan ---".
  828. .*
  829. :li.Not-Found description:
  830. Text for the description column when the file-entry was found in
  831. FILES.BBS, but there was no description present.
  832. :p.Default: "--- no description available ---".
  833. .*
  834. :li.Offline description:
  835. Text that will replace file-size and file-date, when an entry for this
  836. file was found in FILES.BBS, but the file could not be located in the
  837. download directory.
  838. :p.Default: "** offline **".
  839. .*
  840. :li.Comments in FILES.BBS (mostly used for additional description for
  841. groups of files) will be listed when no sorting is specified (the /K
  842. option for ALL-, IPF- and FIL-lists).
  843. :p.When Downsort encounters Avatar screen handling codes in FILES.BBS
  844. these are stripped of or partially imitated in the output lists (unless
  845. AVAstrip&rbl.No is specified in Downsort.Cfg).
  846. Typical screen handling commands (cursor movement, color settings) are just
  847. stripped, ohers (repeating characters of patterns) are imitated.
  848. .*
  849. :li.Size of a VIEW-page in IPF-list:
  850. The IPF-list of area's with more than 250 file entries will be splitted
  851. into 'parts' to prevent the IPF-compiler message 'page size exceeded'.
  852. But if you have many long descriptions, or wish smaller parts, the
  853. page-size can be altered with a parameter on the IpfFileList line in
  854. Downsort.CFG.
  855. :p.Default: 250.
  856. .*
  857. :eul.
  858. .* ---------------------------
  859. :h2.Miscellaneous report information
  860. .* ---
  861. :h3.File Information in Lists
  862. :ol.
  863. :li.Dates are marked with a 'new'-indicator: a '*' if the file
  864. is only since a week on this system, and a '+' if it is since a month.
  865. Filedates later than the current system date are marked '-' (negative
  866. age).
  867. :li.In every outputfile the filename, MAXIMUS-area name, file-size and
  868. -date, and file-description from FILES.BBS is listed.
  869. A report-line will never display more than 79 characters.
  870. :p.The file-description will be multi-line in ALL-, IPF- and GBL-list
  871. if it is longer than would fit on the standard 79-position line, a
  872. word-wrapping technique is used for readability (line-split on word
  873. boundary).
  874. The description is truncated at end of line in BBS-list and NEW-list.
  875. :p.The -T option will force truncation of the description in all reports,
  876. the -W option will allow multi-line descriptions in all reports.
  877. When wrapping is used, continuation lines will normally be aligned
  878. on the start position of the desription.
  879. This may be modified with an indentation option.
  880. :p.If a filename is found in FILES.BBS, but no accompanying description,
  881. a "--- no description available ---" will be put in place.
  882. An alternative text may be specified with Downsort.CFG.
  883. :p.Files for which there is no entry in the FILES.BBS (Orphans) are
  884. treated as Hidden files, which are only listed in the reports if the
  885. Hidden privilege is specified.
  886. :note.If you want the orphans to appear in FILES.BBS (or in any other
  887. report), you MUST also request an ORP-list!
  888. :li.'OFFLINE" in stead of file-size and file-date is reported if
  889. FILES.BBS contains an file-entry while the file is not in the
  890. corresponding directory.
  891. :li.The BBS-list contains MAXIMUS authorisation controls
  892. (&caret.PLp-sequences), corresponding to the privilege of the area or the
  893. individual file.
  894. So it is not necessary to make different files for different categories
  895. of MAXIMUS users, even with the default privilege-limit SYSOP a
  896. user will not see the files he/she is not supposed to know about.
  897. :p.Other lists do not contain any privilege information,
  898. the files (or complete area's) above the specified privilege are simply
  899. not listed, however multiple lists can be produced for different
  900. categories of users (based on privilege).
  901. :eol.
  902. .* ---
  903. :h3.File Dates
  904. :p.One of the function of Downsort is sorting on file date.
  905. Since the introduction of HPFS in OS/2 version 1.2, there is not one
  906. single file-date anymore!
  907. A file on an HPFS volume has different values for:
  908. :ul compact.
  909. :li.Creation date
  910. :li.LastAccess date
  911. :li.LastWrite date
  912. :eul.
  913. :p.The date you see normally in DIR-listings is the LastWrite date.
  914. Most SYSOPs will have noticed that ZMODEM uploads and file-attaches
  915. give file-dates corresponding to the (LastWrite-) date of the sending
  916. system.
  917. And most utilities handle only this 'single' date.
  918. That means that old ZMODEM-uploaded files are generally not on top
  919. of the acquisition lists.
  920. :p.But HPFS stores the date of arrival on your system (Creation) as
  921. well.
  922. Downsort handles the Creation date for sorting, but the lists (see
  923. below) contain the 'old fashioned' LastWrite date.
  924. This has the following consequences:
  925. :ul compact.
  926. :li.A new acquisition is on top of lists, if that list is sorted on
  927. date, and are marked in the lists as new by a flag for an 'age' of a
  928. week or a month.
  929. :li.The listed file-date is the 'ordinary' date.
  930. So users can judge for themselves if the file is 'new' for them as well.
  931. :eul.
  932. :note.The LastAccess date is not very relevant for the purposes of
  933. Downsort, although SYSOP may see when it was last downloaded.
  934. :p.Downsort is delivered with a simple DIR-like utility 'HPFSDATE' to
  935. show the three dates of a file on a HPFS volume.
  936. :rev refid=59.
  937. :p.Files with 'future' file dates will be indicated with a '-' flag in the
  938. lists.
  939. These files will never appear in: BBS-, NEW-, and EMI-lists.
  940. :erev refid=59.
  941. .* ---
  942. :h3.Duplicate Filenames
  943. :p.Duplicate filenames are checked if the DUP-list is requested,
  944. and they will be reported only in the DUP-list.
  945. So duplicates may appear in the regular user-lists, which means:
  946. :ul compact.
  947. :li.If a filename.ext is encountered more than once in different
  948. subdirectories of FILES.BBS files, it will appear that many times in the
  949. outputlist.
  950. The file-privilege reflects that of the area where the file belongs to,
  951. unless overridden by a &caret.Px modifier in FILES.BBS.
  952. :li.It may happen that a file is reported as orphan in one area,
  953. and as duplicate in another.
  954. It is likely that the file is found in a common download directory of
  955. more than one area but it is described in the FILES.BBS of a 'secundary'
  956. area, but with the wrong extension.
  957. :note.Duplicate file reporting may be influenced with the 'NonDupExt'
  958. specification, see :hdref refid=dup..
  959. :eul.
  960. .* ==============================================
  961. :h1 id=specs.Parameter Specifications
  962. :p.This chapter tells you how to customise the configuration file and
  963. what you might specify on the commandline.
  964. :p.A sample configuration file (in :hdref refid=acfg.) is part of the
  965. package.
  966. It contains a brief comments (in Binkley and MAXIMUS style) to help you.
  967. .* --------------------------
  968. :h2 id=hcmd.Commandline parameters
  969. :p.This paragraph deals only with the commandline parameters!
  970. :xmp.
  971. :rev refid=59.
  972. :cgraphic scale='1.1'.
  973. :on3270.
  974.  
  975.   [drive:][path]  DOWNSORT  [@filespec] [/H | /Q | /V]
  976.  
  977. :off3270.
  978. :ecgraphic.
  979. :exmp.
  980. :erev refid=59.
  981. .*
  982. :dl tsize=12 termhi=2.
  983. :dt.@filespec
  984. :dd.The character '@' followed by a complete
  985. :hp2.file specification:ehp2. of the
  986. :hp2.Downsort configuration file:ehp2.
  987. (see :hdref refid=hcfg. for details).
  988. This file will be used to specify processing parameters.
  989. :p.NOTE: The specification of a configuration file is mandatory when the
  990. file AREA.DAT is not in the default directory when running Downsort.
  991. :p.Default: Downsort.CFG in current default directory.
  992. .*
  993. :dt./H /Q /V
  994. :dd.Operating mode
  995. :ul compact.
  996. :li.H&rbl.-&rbl.:hp4.H:ehp4.elp:  display screen with essential information
  997. about running Downsort, such as the command syntax.
  998. In that case the program will not undertake any other action.
  999. :li.Q&rbl.-&rbl.:hp4.Q:ehp4.uiet:  display only start and finish-message,
  1000. and error messages which prevent the program from proceeding normally.
  1001. :li.V&rbl.-&rbl.:hp4.V:ehp4.erbose:  display a lot of progress messages.
  1002. :eul.
  1003. If neither -Q nor -V is specified, than the number of console messages
  1004. will be 'intermediate': more than -Q, but less than -V.
  1005. :p.Default: none
  1006. .*
  1007. :edl.
  1008. .* --------------------------
  1009. :h2 id=hcfg.Configuration file Parameters
  1010. :p.All processing options are specified in the configuration file.
  1011. The parameters are only mentioned here for completeness,
  1012. see :hdref refid=acfg. for a documented specification sample
  1013. of a configuration file.
  1014. .* -----------
  1015. :h3.Parameters with global scope
  1016. :p.The parameters below influence the execution of Downsort,
  1017. or have impact on :hp2.every:ehp2. list (if it is applicable for that
  1018. list).
  1019. :ul compact.
  1020. :li.File Specification of the MAXIMUS CBCS file 'AREA.DAT'.
  1021. :rev refid=59.
  1022. :li.Area selection by name
  1023. :li.Area and File selection by 'cumulative' privilege and/or Maximus'
  1024. key/lock
  1025. :li.Explicit file exclusion
  1026. :erev refid=59.
  1027. :li.Sorting order of areas
  1028. :li.List title with BLOCK-characters.
  1029. :li.Pre-titles, Sub-titles and Bottom-lines in 'text' format
  1030. :li.Descriptive text of orphans, files without a description
  1031. and files for which an entry is found in FILES.BBS, but could not
  1032. be found in the corresponding download directory.
  1033. :eul.
  1034. .* -----------
  1035. :h3.Parameters with local scope
  1036. :p.The parameters below are sub-parameters of the xxxFileList keyword.
  1037. :ul compact.
  1038. :rev refid=59.
  1039. :li.List privilege
  1040. :li.Userkeys for a list
  1041. :erev refid=59.
  1042. :li.Alternate output filename (in stead of the default Downsort).
  1043. :li.Directory for the :hp2.output:ehp2. FILES.BBS-lists
  1044. :li.Maximum number of file entries in NEW- and BBS-list
  1045. :li.File-entry sort sequence (filename or date).
  1046. :li.Wrap or Truncate long file descriptions, and Indentation of continuation
  1047. lines.
  1048. :li.Title Font selection.
  1049. :li.Suppression of privilege indications.
  1050. :li.Include textfile in NEW-, ALL-, IPF- and GBL-lists, and in FILES.bbs.
  1051. :eul.
  1052. :rev refid=59.
  1053. :p.Downsort can generate any number of lists in a single run.
  1054. If you are clever with Maximus key/lock manipulations, you will master
  1055. Downsort quickly to make the proper selections.
  1056. :erev refid=59.
  1057. :p.A sample configuration file is provided.
  1058. A listing of this file is imbedded as :hdref refid=acfg..
  1059. It contains a complete specification with comments on:
  1060. :ul compact.
  1061. :li.which options are available
  1062. :li.how to specify the options
  1063. :eul.
  1064. :p.Read and modify the file as you like.
  1065. Copy the sample file to a save place before you start modifying the
  1066. original Downsort.CFG!
  1067. .* ---------------------------------
  1068. :h2.Compiling the IPF lists
  1069. :p.IPF-lists have to be processed by the Information Presentation
  1070. Facility Compiler (IPFC).
  1071. This compiler is part of the IBM Programmers Development Toolkit version
  1072. 1.2/1.3.
  1073. For the IP2-list the IBM OS/2 2.0 or 2.1 Toolkit is needed.
  1074. The following command has to be issued:
  1075. :xmp.
  1076.     IPFC  Downsort.IPF  /INF
  1077. :exmp.
  1078. :p.The option "/INF" is needed to obtain a VIEWable file, if not specified
  1079. a .HLP file will be generated.
  1080. Be sure to have the file Downsort.BMP in your current default directory, or
  1081. in DPATH, as this will be imbedded by the IPF-compiler.
  1082. The result of the compilation is a file Downsort.INF, which can be VIEWed
  1083. with the following command:
  1084. :xmp.
  1085.     VIEW  Downsort
  1086. :exmp.
  1087. :p.The names "Downsort", "IPF" and "INF" are used here as sample,
  1088. actually the filename depends on the specification in the Downsort
  1089. configuration file, the extensions are the IPFC defaults.
  1090. :p.If VIEW gives garbled columns and hardly readable block-titles,
  1091. then it is most likely that you did not install (or removed) the
  1092. standard fonts that are delivered with OS/2.
  1093. Start the 'control panel utility', select 'installation', 'add fonts'.
  1094. Specify in the 'from'-field C&colon.\OS2\DLL (see HELP of control panel).
  1095. Now choose at least 1 non-proportional font.
  1096. :note.IPFC has a number of restrictions that you may encounter, especially
  1097. when you try to compile large lists:
  1098. :ul compact.
  1099. :li.A "Page is too big" message, generally resulting in other errors or
  1100. warnings to appear as well, means that the 16000 words limit is exceeded.
  1101. A file may not contain more than 16000 :hp2.different:ehp2. items
  1102. (character strings between blanks or punctuation marks).
  1103. There is nothing else you can do than make the list smaller
  1104. (see :hdref refid=select. for suggestions).
  1105. Sometimes a TRAP 000D occurs with very big lists if you ignore these
  1106. error messages.
  1107. :li.Sometimes also "invalid nesting of &colon.cgraphics tag" is
  1108. displayed.
  1109. Just ignore these!
  1110. :eul.
  1111. .* =====================================================
  1112. :h1 id=sampl.Sample of Getting organised
  1113. :p.Assume you are runnung MAXIMUS with BinkleyTerm as front end mailer.
  1114. Suppose you make a distinction for file-requestors between Unknown, Known
  1115. and Password-Protected (e.g. corresponding to Disgrace, Normal and
  1116. Privileged MAXIMUS users).
  1117. .* ----------------------------------------------
  1118. :h2.Downsort
  1119. :rev refid=59.
  1120. :p.Your downsort.cfg file might contain among others the following
  1121. specifications:
  1122. :xmp scale='1.1'.
  1123.   BBSFileList  p     3W
  1124.   NEWFileList  d     2m
  1125.   NEWFileList  n     2m
  1126.   NEWFileList  p     2m
  1127.   ALLFileList  d
  1128.   ALLFileList  n
  1129.   ALLFileList  p
  1130.   OKFileList   p
  1131.   OKFileList   n
  1132.   OKFileList   d
  1133. :erev refid=59.
  1134. :exmp.
  1135. :p.This specification will produce the following lists:
  1136. :ul.
  1137. :li.Downsort.BBS with the last three weeks additions to your system, for
  1138. users of category Privil.
  1139. Note: Users with a lower privilege will actually see a shorter list if the
  1140. file contains Privil entries, since each line contains a privilege control
  1141. sequence.
  1142. :li.For file requests of the magic filename NEWFILES a list of the last 2
  1143. months additions to your system.
  1144. :ul compact.
  1145. :li.Downsort.N&tilde.D for UNKNOWN file-requestors
  1146. :li.Downsort.N&tilde.N for KNOWN file-requestors
  1147. :li.Downsort.N&tilde.P for Password Protected file-requestors
  1148. :eul.
  1149. :p.Note that each NEW-list contains only the most recent files, but the
  1150. contents will generally not be quite the same (depending on your privilege
  1151. strategy).
  1152. :li.For file requestors of the magic filename FILES a list,
  1153. a list with all files
  1154. (with optional titles via Downsort.CFG specifications):
  1155. :ul compact.
  1156. :li.Downsort.A&tilde.D for UNKNOWN file-requestors
  1157. :li.Downsort.A&tilde.N for KNOWN file-requestors
  1158. :li.Downsort.A&tilde.P for Password Protected file-requestors
  1159. :eul.
  1160. :p.Note that each list is a complete list of what is available to the user
  1161. of the specific privilege class, but your system will generally contain more
  1162. files than listed for UNKNOWN and KNOWN users!
  1163. :li.For your mailer you'll have:
  1164. :ul compact.
  1165. :li.Downsort.O&tilde.D for UNKNOWN file-requestors
  1166. :li.Downsort.O&tilde.N for KNOWN file-requestors
  1167. :li.Downsort.O&tilde.P for Password Protected file-requestors
  1168. :eul.
  1169. :eul.
  1170. :p.In general: files, which the requestor is not supposed to know about
  1171. due to his privilege status, will not be on his/her list!
  1172. :note.The counters on top of the lists indicate what your system has
  1173. available in total (including higher privileges), so a clever
  1174. user/file-requester may come up with the question how that is possible:
  1175. explain that he/she has to earn a higher privilege level!
  1176. .* ------
  1177. :h2.BinkleyTerm
  1178. :p.In Binkley.Cfg you should specify for requests of FILES:
  1179. :xmp scale='1.1'.
  1180.   Avail        Downsort.A&tilde.d
  1181.   KnownAvail   Downsort.A&tilde.n
  1182.   ProtAvail    Downsort.A&tilde.p
  1183. :exmp.
  1184. :p.Furthermore you need to specify different OKFILEs, for example:
  1185. .cp 5
  1186. :rev refid=59.
  1187. :xmp scale='1.1'.
  1188.   OKFile       Downsort.O&tilde.d
  1189.   KnownReqList Downsort.O&tilde.n
  1190.   ProtReqList  Downsort.O&tilde.p
  1191. :exmp.
  1192. :erev refid=59.
  1193. .cp 16
  1194. :p.In each of the appropriate filerequest authorisation files you should
  1195. specify the appropriate file-spec:
  1196. :xmp.
  1197. :cgraphic scale='1.1'.
  1198. :on3270.
  1199.  
  1200.  ╔═══════════╦══════════════╦═══════════════╦═══════════════╗
  1201.  ║       in: ║ OKFile       ║ KnownReqList  ║ ProtReqList   ║
  1202.  ║           ║ (Download.N) ║ (Download.K)  ║ (Download.P)  ║
  1203.  ║ for:      ║              ║               ║               ║
  1204.  ╠═══════════╬══════════════╬═══════════════╬═══════════════╣
  1205.  ║ .....     ║ .........    ║ ...........   ║  ........     ║
  1206.  ║ @NEWFILES ║ Downsort.N&tilde.d ║ Downsort.N&tilde.n  ║  Downsort.N&tilde.p ║
  1207.  ║ @FILES    ║ Downsort.A&tilde.d ║ Downsort.A&tilde.n  ║  Downsort.A&tilde.p ║
  1208.  ║ .....     ║ .........    ║ ...........   ║  ........     ║
  1209.  ╚═══════════╩══════════════╩═══════════════╩═══════════════╝
  1210. :off3270.
  1211. :ecgraphic.
  1212. :exmp.
  1213. :p.This will result in sending of the appropriate NEW-list to every
  1214. requester of the magic filename: NEWFILES.
  1215. If you use the second magic filename, then the Avail-lines in
  1216. Binkley.Cfg are not needed, and you might prefer this way.
  1217. :p.Of course if the privilege level of all download area's is the same,
  1218. this construction is not needed,
  1219. but in that case it is unlikely that you have specified KnownAvail and
  1220. ProtAvail!
  1221. :p.Downsort may create a set of OK-files for you.
  1222. The privilege system of MAXIMUS CBCS is used to select the download
  1223. paths in this list.
  1224. .* ===============================================
  1225. :h1.Packaging
  1226. .* ---------------------
  1227. :h2.Availability
  1228. :p.The most recent version of Downsort is always downloadable and
  1229. file-requestable from Bulletin Board "PC-Square" of the Dutch IBM
  1230. employee PC club.
  1231. Search or request DWNSRT??.* to be independent of the version and
  1232. compression method!
  1233. :p.FIDO-net address:  2&colon.512/4; phone:  31-79-424107 (USR HST-DS).
  1234. :rev refid=59.
  1235. :p.Downsort is originally distributed in area FWBBS of the Fernwood
  1236. collection, and may also be distributed via SDSMAX.
  1237. :erev refid=59.
  1238. :p.There is a fair chance you may find a recent version on one of
  1239. the other bulletin boards, listed in :hdref refid=ause..
  1240. :p.Downsort is distributed in 2 archives:
  1241. :ul.
  1242. :li.A file "DWNSRTxy.ZIP", containing all material you need to run
  1243. Downsort, including documentation, formatted for browsing or printing
  1244. (formfeed is the only printer-control).
  1245. :li.A file "DWNSRSxy.ZIP", containing all SOURCE material.
  1246. :eul.
  1247. :note.'xy' is the version indication,
  1248. for example DWNSRT&VERSION.&SUBVERS..ZIP is the version
  1249. &VERSION..&SUBVERS. runtime package.
  1250. .* -----------------
  1251. :h2.RUN-time material
  1252. :dl tsize=20 termhi=3 compact.
  1253. :dt.WHATSNEW.&VERSION.&SUBVERS.&SUFFIX.
  1254. :dd.Summary of amendments to version &VERSION..&SUBVERS. of Downsort.
  1255. :dt.DOWNSORT.EXE
  1256. :dd.Execution module for OS/2 and DOS (Family Application)
  1257. :dt.DOWN386.EXE
  1258. :dd.32-bits execution module for OS/2 (2.0 and higher).
  1259. :dt.DOWN386.ICO
  1260. :dd.ICON file for DOWN386.EXE.
  1261. :dt.DOWNSORT.DOC
  1262. :dd.Documentation (this file!).
  1263. :dt.DOWNSORT.CFG
  1264. :dd.Sample configuration file.
  1265. This file contains comment lines with extensive instructions how to
  1266. specify the parameters in the file.
  1267. :dt.DOWNSORT.HDR
  1268. :dd.Sample BBS-list header.
  1269. You may use this header, which is only imbedded in the BBS-list,
  1270. to imbed text and/or MECCA-sequences.
  1271. A good candidate for the latter would be &lbrk.onexit&rbrk.,
  1272. which translates to &caret.OFpath.
  1273. See the sample Downsort.HDR file!
  1274. :dt.DOWNSORT.TRL
  1275. :dd.Sample BBS-list trailer.
  1276. :dt.DOWNSORT.BMP
  1277. :dd.Bitmap for the IPF-list, to be included by the IPF compiler.
  1278. :dt.DOWNSORT.INC
  1279. :dd.Sample Include-file for the reports, referenced in Downsort.CFG.
  1280. :dt.DOWNSORT.MAG
  1281. :dd.Sample list of magic names to be included in OKFile(s).
  1282. See BinkleyTerm documentation for details of its format and contents.
  1283. :dt.HPFSDATE.EXE
  1284. :dd.Program to display all three timestamps of a file on an HPFS volume,
  1285. and optionally reset the CREATION date to LASTWRITE date
  1286. (helpful after moving or copying of files).
  1287. Start the program without options to display command syntax and help.
  1288. A 32-bits version for OS/2 2.0+ is included with the name HPFSD386.EXE.
  1289. :dt.PACKING.LST
  1290. :dd.The actual contents of the package (produced with PKUNZIP -V),
  1291. added to the ZIP-file after this was created with the foregoing files
  1292. of this archive.
  1293. This gives at least some authentication!
  1294. :edl.
  1295. .* ---
  1296. :h2.Source material
  1297. :dl tsize=20 termhi=3 compact.
  1298. :dt.DOWNSORT.C
  1299. :dd.Mainline.
  1300. :dt.DOWNCOL.C
  1301. :dd.Data collection functions.
  1302. :dt.DOWNFNT.C
  1303. :dd.Font definition and formatting functions.
  1304. :dt.DOWNPAR.C
  1305. :dd.Processing functions for commandline and Downsort.CFG parameters.
  1306. :dt.DOWNRPT1.C
  1307. :dd.Functions for NEW-, BBS- and EMI-list.
  1308. :dt.DOWNRPT2.C
  1309. :dd.Functions for the IPF-lists.
  1310. :dt.DOWNRPT3.C
  1311. :dd.Functions for the SYSOP-oriented lists, like ORPhan-, OK-, and
  1312. DUPlicate-lists, as well as FILES.BBS files.
  1313. :dt.DOWNRPT4.C
  1314. :dd.Functions for the ALL- and GBL-lists.
  1315. :dt.DOWNSRV.C
  1316. :dd.Miscellaneous services functions.
  1317. :dt.DOWNVARS.C
  1318. :dd.Constants and global variables.
  1319. :dt.DOWNSORT.H
  1320. :dd.Header file, with external definitions of global variables.
  1321. :dt.DOWNFPRO.H
  1322. :dd.Common (global) function prototypes.
  1323. :dt.DOWNSORT.SCR
  1324. :dd.Unformatted documentation file.
  1325. This file includes formatting tags in BOOKMASTER style for printing on
  1326. whatever devices are supported (like IBM page printers).
  1327. This format is compatible and can be formatted on an IBM host system
  1328. with DCF (SCRIPT) as well.
  1329. The file can also processed by the IPF-compiler (just ignore the
  1330. warnings and error-messages!).
  1331. :dt.DOWNSORT.DEF
  1332. :dd.LINK definition file for OS/2 (1.3 and 2.0+)
  1333. :dt.DOWN386.MAK
  1334. :dd.MAKE file for DOWN386.EXE with OS/2 2.1, C/C++ Tools Version 2 and
  1335. OS/2 2.1 Toolkit.
  1336. :dt.DOWNSORT.MAK
  1337. :dd.MAKE file for DOWNSORT.EXE OS/2 1.3, MS C-compiler 6.00a.
  1338. The program development toolkit (OS/2 1.2/1.3) is needed when using IBM C/2
  1339. 1.1 compiler.
  1340. :dt.PACKING.LST
  1341. :dd.The actual contents of the package (produced with PKUNZIP -V),
  1342. added to the ZIP-file after this was created with the foregoing files
  1343. of this archive.
  1344. This gives at least some authentication!
  1345. :edl.
  1346. .* --------------------------
  1347. :h2 id=inst.Installation
  1348. :p.With the following directions you should be able to setup and run
  1349. Downsort in a very short time.
  1350. :ol.
  1351. :li.Make a separate directory for Downsort, and make it the current
  1352. default directory every time you run Downsort.
  1353. The separate directory is a recommendation, not a requirement!
  1354. :li.Copy the files Downsort.EXE and Downsort.CFG
  1355. from the Downsort package into this directory.
  1356. :li.Modify (edit) the file Downsort.CFG to specify your environment and
  1357. list requirements.
  1358. The sample file contains comments to help you with this process.
  1359. Most specifications are obvious.
  1360. AreaDat is the most important parameter:
  1361. Downsort won't do anything useful thing if it cannot find this MAXIMUS
  1362. file.
  1363. See :hdref refid=acfg. for a printed sample.
  1364. :li.You may give Downsort a first shot by just using its name
  1365. on the commandline, with the command parameter -H.
  1366. This will show a brief HELP-screen with the possible commandline
  1367. parameter specifications.
  1368. :li.All reports will be created in the Downsort directory
  1369. (unless you specified 'fpath' for the FILES.BBS output).
  1370. Browse the lists to see if you like the contents and titles, and modify
  1371. the CFG-file to your convenience.
  1372. :eol.
  1373. .* -----------------------------
  1374. :h2.Dependencies and restrictions
  1375. :ul.
  1376. :li.Applies to MAXIMUS CBCS 2.0
  1377. :li.Requires OS/2 or DOS 3.0+.
  1378. :li.To convert the IPF-list into VIEW-able format, the IPF-Compiler of the
  1379. OS/2 Program Development Toolkit is required (for the IP2-list the
  1380. corresponding OS/2 2.0 or 2.1 version of this compiler)
  1381. :li.The input FILES.BBS files are assumed to contain only filename.ext
  1382. (the regular 8.3 format, no support for OS/2 HPFS extended format),
  1383. the remainder of the line is considered as file description.
  1384. The filename should be left-aligned (start in position 1).
  1385. :p.If a privilege modifier (&caret.Px) is encountered in FILES.BBS
  1386. then 'x' will become the privilege of all subsequent files (it assumes
  1387. &caret.Px on a SEPARATE line, the REST OF THE LINE IS IGNORED!).
  1388. Heading, comments and blank lines in FILES.BBS are ignored,
  1389. unless /K is specified on the FilFileList line of Downsort.Cfg.
  1390. In that case comments following line 8 (the standard header created by
  1391. Downsort) or headerlines from a previous run are preserved.
  1392. The modified privilege might be higher (generally the case) or lower
  1393. than the area-privilege.
  1394. :eul.
  1395. .* -----------
  1396. :h2 id=perf.Storage and Performance
  1397. :p.As a rough estimate of the memory requirements of Downsort,
  1398. use sum of the following elements:
  1399. :ul.
  1400. :li.Program: about 100KB
  1401. :li.Each area: 300 Bytes
  1402. :li.Each file: 48 Bytes for each download file (excluding file
  1403. descriptions and excluding orphans if no orphan-list requested)
  1404. :li.The sum of the file description texts (average 80 bytes/file?)
  1405. :li.The sum of the comments in FILES.BBS if -K option specified
  1406. :eul.
  1407. :p.If you hit a memory shortage (only applicable wiht DOS!), then you could
  1408. do one or more of the following:
  1409. :ul compact.
  1410. :li.Use AreaEXclude or AreaINclude to make a selection of groups
  1411. (for example make separate OS/2 and a DOS file-lists).
  1412. Downsort will not collect information of 'excluded' areas.
  1413. :li.If you have many orphans: get rid of them or do not generate an
  1414. orphan report.
  1415. Downsort releases orphan-memory during the data collection phase as soon
  1416. as it knows that a file is an orphan.
  1417. :li.If you have many comment-lines in your FILES.BBS: do not specify /K
  1418. for ALL- and IPF-lists AND do not activate the FILFilePath parameter in
  1419. Downsort.Cfg.
  1420. Downsort will ignore comments in FILES.BBS when it does not need them
  1421. for reporting.
  1422. :eul.
  1423. .* -------------------------------
  1424. :h2.Problems
  1425. :p.Although I try to prevent the cause of them, there are some
  1426. unresolved problems in the current version of Downsort:
  1427. :ul.
  1428. :li.Currently no unresolved problems are known.
  1429. :eul.
  1430. .* ---------------------------------------
  1431. :h2.Wishlist
  1432. :p.Downsort is not finished!
  1433. There are a number of wishes and requirements of users and myself to
  1434. include in future releases.
  1435. I list them below not in any particular order, but some seem to be more
  1436. important than others, that differs from SYSOP to SYSOP.
  1437. And some are more easy to implement than others, which depends mainly
  1438. on the author!
  1439. Some wishes don't even make it to be listed below and are implemented
  1440. immediately!
  1441. :ul compact.
  1442. :li.Follow the MAXIMUS development (changing AREA.DAT and other
  1443. structures), and support several versions simultaneously.
  1444. :li.User-configurable options for:
  1445. :ul compact.
  1446. :li.week and month indicators
  1447. :li.indicator for continuation lines in wrapped descriptions
  1448. :li.&lbrk.selectable&rbrk. MECCA control in FILES.BBS
  1449. :eul.
  1450. :li.Logging to file in stead of stdout to obtain a history file
  1451. of Downsort usage.
  1452. :rev refid=59.
  1453. :hp2.(may be done wiht redirection!).
  1454. :erev refid=59.
  1455. :li.Support for use of 'barricaded' areas.
  1456. :li.List with the format of IPF-list but the contents of NEW-list.
  1457. :li.Automatic removal of 'bad' files (like .BAK-files, obsolete files,
  1458. files that are not in FILES.BBS), maybe move them to a special
  1459. BAD&us.FILE directory.
  1460. Entries in FILES.BBS should be removed accordingly.
  1461. :eul.
  1462. :p.Remember: Was there ever a time that all your wishes were fulfilled?
  1463. That was the most boring time of your life, wasn't it?
  1464. .* ===================================================================
  1465. :h1.Internals
  1466. .* ------
  1467. :h2.Development Environment
  1468. :p.The family-version of Downsort (for OS/2 1.3 and DOS) is compiled with
  1469. MicroSoft C compiler version 6.00a, with the IBM OS/2 Programming Tools and
  1470. Information (generally called the OS/2 Toolkit) under IBM OS/2 Extended
  1471. Edition 1.3 as COMPACT memory model.
  1472. The generated code is at 80286 level (Compiler option /G2), since I
  1473. believe that only very few Bulletin Boards do use an XT these days.
  1474. :p.The 32-bit OS/2 2.0+ only version of Downsort is compiled with IBM
  1475. C/C++ Tools version 2 and the OS/2 2.1 Toolkit.
  1476. :p.There is only a single set of source files.
  1477. A compiler variable takes care of the selection between 1.3 and 2.1
  1478. calls where necessary.
  1479. :p.Downsort has been tested for MAXIMUS CBCS 2.0, with the following
  1480. Operating Systems:
  1481. :ul compact.
  1482. :li.IBM OS/2 versions 1.3 and 2.1
  1483. :li.IBM PC/DOS version 6.1
  1484. :eul.
  1485. .* ---------------------------
  1486. :h2.Program Organisation
  1487. :p.The program is organised as follows:
  1488. :ul.
  1489. :li.Initialisation:
  1490. :ul compact.
  1491. :li.Read configuration file.
  1492. :li.Process commandline parameters.
  1493. :eul.
  1494. :p.Commandline parameters may override configuration file parameters.
  1495. :li.Read AREA.DAT file to collect download pathnames
  1496. (only of those area's that will participate this time).
  1497. :li.For each file-area with a privilege not exceeding any list-request:
  1498. :ul.
  1499. :li.Read subdirectory (with find-file-first/next function).
  1500. Take only Normal files: ignore directory entries, Hidden and System
  1501. files and volume labels.
  1502. Also ignore files with the following specifications: FILES.*,
  1503. *.BAK, DIR.?BS and SYSTEM*.?BS.
  1504. :li.For all regular file-entries found in subdirectory:
  1505. :ul compact.
  1506. :li.Get filename.ext, attribute, date, time, size.
  1507. :li.Get file-description from FILES.BBS file.
  1508. The path to the FILES.BBS file is (1) obtained from the "ListFile"
  1509. specification in MAXIMUS AREA.DAT file, or (2) if not specified from the
  1510. "DownLoad" specification (among the download files).
  1511. :li.Add files with explicit path specifications.
  1512. :li.Get file privilege 1) from area, 2) from FILES.BBS file if higher.
  1513. :li.When no orphan reporting is required, then drop orphan entries
  1514. area-by-area.
  1515. :eul.
  1516. :eul.
  1517. :li.For the ORP-list:
  1518. :p.If any orphan found, and the orphan-report is requested, create the
  1519. orphan report, with the file-entries sorted on (1) area and (2)
  1520. filename.
  1521. :li.For the BBS-list:
  1522. :ul compact.
  1523. :li.Sort the files primarily on descending file-timestamp (and secundary
  1524. on file-name and area-code).
  1525. :li.Resort the first files on filename if requested.
  1526. :li.Create output file for sorted list of filenames, -descriptions, etc.
  1527. The file is placed in the current subdirectory (which generally will be
  1528. the MAXIMUS directory) with the name Downsort.BBS.
  1529. :li.Copy a headerfile (for a customised MAXIMUS bulletin).
  1530. :li.Put files in formatted outputfile (filename, area#, date, size,
  1531. description), but only if description is found in FILES.BBS.
  1532. Skip files with privilege higher than commandline (or default)
  1533. parameter.
  1534. Precede each line with a privilege-control sequence (&caret.PLx string)
  1535. so that MAXIMUS users below the specified max-priv-level do effectively
  1536. see only the files they can download.
  1537. :li.Include a trailerfile in the outputfile (for a custimised Bulletin).
  1538. :li.Report non-listed files on standard output device (which might be
  1539. re-directed to printer or disk-file).
  1540. :eul.
  1541. :li.If requested, put the above file collection in Downsort.N&tilde.p
  1542. with similar contents and layout as Downsort.BBS, but without
  1543. BBS-control sequences, and without including a header and trailer file.
  1544. Produce a list for the default privilege (HIDDEN), or one for each
  1545. specified privilege.
  1546. :li.If requested, re-sort files on area and then filename or date, and
  1547. create Downsort.A&tilde.p, containing all files (respecting the
  1548. privilege restrictions!).
  1549. Area's with zero files within the applicable privilege limit will not
  1550. be listed at all (will seem non-existing!).
  1551. Produce a list for the default privilege (SYSOP), or one for each
  1552. specified privilege.
  1553. :p.At the end of the list, an area summary report is generated.
  1554. :li.If requested, re-sort files on filename or date only, and create
  1555. Downsort.GBL.
  1556. :li.If requested, re-sort files on area, privilege and filename, and
  1557. create for each area a FILES.BBS-type of file.
  1558. :li.If requested generate a list of probably DUPlicate files.
  1559. :li.If requested generate a list of download-paths: the OK-file
  1560. (not: it will contain only the paths that participated in this run.
  1561. :eul.
  1562. :p.NOTE: the program firstly reads a directory for existing files
  1563. (not Hidden- or System-files, and not Subdirectory or Volumelabel),
  1564. and then reads FILES.BBS to assign a description to each file.
  1565. This means:
  1566. :ul compact.
  1567. :li.If more than 1 matching file-specification in FILES.BBS of the
  1568. involved area is found (note that wild-card specifications in FILES.BBS
  1569. are supported!), than the :hp2.first matching description:ehp2. from
  1570. FILES.BBS will appear in the lists
  1571. (new in version 4.5, was 'last' in previous versions of Downsort).
  1572. :li.Files for which no description is found in FILES.BBS will get
  1573. "---no description available---"
  1574. (or the replacement string you specified in Downsort.CFG)
  1575. in the user reports.
  1576. :li.Files for which no matching filename in FILES.BBS is found will
  1577. be listed in the Orphan report (Downsort.ORP).
  1578. :p.Files for which there is an entry in FILES.BBS, but a corresponding
  1579. file is not found in the directory will be reported as 'offline'.
  1580. :p.In special cases this might become a very large list.
  1581. For example if you collect files in a single directory for different
  1582. area's, all the files of 'the other' areas are reported as orphan.
  1583. This will happen for every area, so each file might even be reported
  1584. many times as orphan!
  1585. Since the Orphan-list is now optional (from version 5.0 on), this list
  1586. can be suppressed.
  1587. :p.Filenames of Orphans appear only in the other reports when the
  1588. FileList request explicitly specifies the Hidden privilege.
  1589. :eul.
  1590. .* -----------
  1591. :h2.Main Data Organisation
  1592. :h3.Area and File Information
  1593. :p.Data structure for access to file information via:
  1594. :ol compact.
  1595. :li.array of file-pointers (for file-sort!)
  1596. :li.pointerchain in file-info structures
  1597. :li.file structure contains pointer to file-description
  1598. :li.file-structure contains pointer to area-information
  1599. :li.Array of area-information
  1600. :eol.
  1601. :p.The organisation is shown in the following figure.
  1602. :xmp.
  1603. :cgraphic scale='1.1'.
  1604. :on3270.
  1605.  
  1606. ╔══════╗
  1607. ║  dm  ║
  1608. ╚══════╝
  1609.     │         Array of pointers to structures with file info
  1610.     │      ╔═══════════╦════════════╦═════════════ . . . ══════╗
  1611. (1) └─────>║ *file&lbrk.0&rbrk.  ║  *file&lbrk.1&rbrk.  ║ *file&lbrk.2&rbrk.                 ║
  1612.            ╚═══════════╩════════════╩═════════════ . . . ══════╝
  1613.                  │           │            │
  1614. (2)              v           v            v
  1615. ╔══════╗     ╔══════╗     ╔══════╗     ╔══════╗
  1616. ║  ca  ║ ──> ║ next ║ ──> ║ next ║ ──> ║ next ║ ──> . . .
  1617. ╚══════╝     ╠══════╣     ╠══════╣     ╠══════╣
  1618.  (first-     ║ file-║     ║ file-║     ║ file-║
  1619.  element)    ║ info ║     ║ info ║     ║ info ║    . . .
  1620.              ║ &lbrk.0&rbrk.  ║     ║ &lbrk.1&rbrk.  ║     ║ &lbrk.2&rbrk.  ║
  1621.              ╚══════╝     ╚══════╝     ╚══════╝
  1622.                  │ │         │  │wildcards│ │
  1623.                  │ └──┐      │  └──┐      │ │
  1624.                  │    │      │ ┌──────────┘ │
  1625. (3)              v    │      v v   │ ┌──────┘
  1626.              ╔══════╗ │   ╔══════╗ │ │
  1627.              ║file- ║ │   ║file- ║ │ │(files of
  1628.              ║descr ║ │   ║descr ║ │ │ same area)   . . .
  1629.              ╚══════╝ │   ╚══════╝ │ │
  1630.                       │            │ │
  1631. (4)                   v            v v
  1632.               ╔════════════╦═════════════╦════════ . . . ══════╗
  1633. (5) ┌────────>║  area&lbrk.0&rbrk.   ║   area&lbrk.1&rbrk.   ║                     ║
  1634.     │         ╚════════════╩═════════════╩════════ . . . ══════╝
  1635.     │              array of structures of area information
  1636. ╔══════╗
  1637. ║ area ║
  1638. ╚══════╝
  1639. :off3270.
  1640. :ecgraphic.
  1641. :exmp.
  1642. :p.Schematic overview of Downsort's in-storage database.
  1643. :note.The area-array cannot be sorted itself: this would invalidate the
  1644. pointers in the file-information records!
  1645. .* ---
  1646. :h3.Block fonts
  1647. :p.The block character image is basically a 10x7 matrix
  1648. (10 vertical and 7 horizontal 'pixels').
  1649. The pixel-array takes two rows at a time, so that each character
  1650. can be represented with 5 rows of 7 horizontal 'double-pixels'.
  1651. Each pixel is displayed as a solid block.
  1652. :xmp.
  1653. :cgraphic scale='1.1'.
  1654. :on3270.
  1655.          1 2 3 4 5 6 7
  1656.         ╔═╦═╦═╦═╦═╦═╦═╗
  1657.         ║-║-║-║-║-║-║-║   line 1    (lower + upper)
  1658.         ╠═╬═╬═╬═╬═╬═╬═╣
  1659.         ║-║-║-║-║-║-║-║        2    (lower + upper)
  1660.         ╠═╬═╬═╬═╬═╬═╬═╣
  1661.         ║-║-║-║-║-║-║-║        3    (lower + upper)
  1662.         ╠═╬═╬═╬═╬═╬═╬═╣
  1663.         ║-║-║-║-║-║-║-║        4    (lower + upper)
  1664.         ╠═╬═╬═╬═╬═╬═╬═╣
  1665.         ║-║-║-║-║-║-║-║        5    (lower + upper)
  1666.         ╚═╩═╩═╩═╩═╩═╩═╝
  1667. :off3270.
  1668. :ecgraphic.
  1669. :exmp.
  1670. :p.Each line is represented by a structure of seven 3-bit fields
  1671. Each 3-bit field represents a basic element:
  1672. :xmp scale='1.1'.
  1673.  value    char       description
  1674.    0                 (blank)
  1675.    1     &BOXBOT.           lower half
  1676.    2       &BOXTOP.         upper half
  1677.    3         &BOX.       lower+upper halves
  1678.    4       &box34.         gray pattern
  1679.    5     &BOXLEFT.           left part of upper and lower half
  1680.    6       &BOXRIGHT.         right part of upper and lower half
  1681.    7         &box14.       gray pattern
  1682.    8      &box12.          gray pattern for not-supported characters
  1683. :exmp.
  1684. :p.The pitch is variable ('proportional font': a variable number of
  1685. horizontal pixels).
  1686. Four fonts are provided with different character-image and size:
  1687. :ol compact.
  1688. :li.6x5 (three lines of max 5 characters)
  1689. :li.10x7 (five lines of max 7 characters)
  1690. :li.8x7 (four lines of max 7 characters)
  1691. :li.10x7 (reverse video image of the 8x7 font)
  1692. :eol.
  1693. :p.The following characters are supported in block-fonts:
  1694. :xmp.
  1695.    UPPER case  A..Z
  1696.    LOWER case  a..z  (but will be presented in UPPER case)
  1697.    Digits 0..9
  1698.    _  *  |  .  [  ]  (  )  /  \  -  and space
  1699.    Not-supported characters are displayed as blank.
  1700.    The '~'-character (tilde) represents a full width space,
  1701.    the '`'-character (reverse quote) a half width space.
  1702. :exmp.
  1703. .* --------------------------------
  1704. :appendix.
  1705. :h1 id=ahis.History of changes
  1706. :p.The paragraphs below show a brief history of changes in Downsort
  1707. (most recent revisions on top of list!).
  1708. :p.Downsort for MAXIMUS CBCS was developed from an OPUS equivalent
  1709. (by the same author).
  1710. Its pre-MAXIMUS history is not really important here and therefore has
  1711. been removed.
  1712. However the name Downsort has been maintained, so to prevent confusion,
  1713. the version number is inherited (the last version for OPUS was 3.1).
  1714. .*
  1715. :h2.Version 5.9
  1716. :p.:hp3.Please read also the commentlines marked '5.9' in Downsort.Cfg!:ehp3.
  1717. :ul compact.
  1718. :li.Considerable changes in parameter specifications:
  1719. :ul compact
  1720. :li.Support of most commandline:ehp3. parameters :hp3.removed:ehp2.!
  1721. :li.Support for keywords 'MaxNewFiles' and 'TitleFont' in Downsort.Cfg
  1722. also removed: use xxxFileList for individual specifications for each list.
  1723. :li.Multiple 'xxxFileList' lines in Downsort.Cfg are supported now:
  1724. :ul compact.
  1725. :li.You may now specify as many xxxFileLists with the same(!) or different
  1726. list types as you need.
  1727. :li.Each xxxFileList, regardless of same or different list, will generate
  1728. one and only one list according to its own set of parameters.
  1729. :li.Only a single privilege is now accepted per xxxFileList line, but this
  1730. may now be accompanied by 'userkeys'; specification in the form: p/kkk.
  1731. :eul.
  1732. :li.File sort sequence (GROUP-sort) added for NEWFileList: primary sort on
  1733. area, then on filename.
  1734. Each group will be preceeded in the list by a line with areaname and
  1735. description.
  1736. GROUP-sort works also for ORPHAN-lists, but is for all other lists synonym
  1737. with ALPHA.
  1738. :eul.
  1739. :li.The contents of ALLFileList can now be limited by file-age, so it can
  1740. be called a NEWFileList in the format of ALLFileList or vice versa.
  1741. But the SUMMARY-report ignores the file age limitation!
  1742. :li.FILES.BBS-files will be (re-)generated also when area does not contain
  1743. any files.
  1744. :li.Full support of Maximus' key/lock mechanism for filearea selection.
  1745. Key-characters follow the xxxFileList privilege, separated with a slash,
  1746. exactly the same as the area privilege specification in MAX.CTL.
  1747. The privilege line in area heading will now also show the arealocks.
  1748. :li.With the new keyword 'FileEXclude' you can define filespecs (with
  1749. wildcards) of files which should not appear in any list.
  1750. :li.Tired of the complaints about specification limits, I removed
  1751. most of these.
  1752. For example now unlimited number of title-lines, areaIN/EXclude strings,
  1753. non-duplicate file extensions, xxxFileList lines, etc.
  1754. :li.AreaINclude and AreaEXclude can now be used simultaneously.
  1755. :li.Files with 'future' date will be excluded from NEW-, BBS- and EMI-lists
  1756. (special feature for certain CDROMs!).
  1757. :li.All block fonts now support same characterset (fonts 3 and 4 have been
  1758. extended with the characters supported in fonts 1 and 2), and specification
  1759. of block-font parameter now honored in all lists.
  1760. Default font for all lists changed to 3.
  1761. :li.Performance improvements with sorts on filedate, and during directory
  1762. scan (the latter only of 32-bits version).
  1763. :li.bugfixes:
  1764. :ul compact.
  1765. :li.Filedates beyond 2037(!) could cause empty BBS-, NEW- and EMI-FileLists.
  1766. :li.No 'duplicates' with only case differences in short OKList anymore.
  1767. :eul.
  1768. :li.Downsort's companion program HPFSDATE (and the 32-bit version HPFSD386)
  1769. can now reset the creationdate of files also in other than current working
  1770. directory.
  1771. :eul.
  1772. .*
  1773. :h2.Version 5.8
  1774. :ul compact.
  1775. :li.Now an 'unlimited' number of files is supported, dependent only of
  1776. available memory (virtual memory under OS/2!).
  1777. Limit was 16350 files!
  1778. :li.Continuation lines of file descriptions can now be indented, for example
  1779. to align text when download counter fields are used in the description.
  1780. See Sample Downsort.Cfg file for details.
  1781. :li.All filenames now translated to upper case and also reported in upper
  1782. case in the lists.
  1783. :li.Downsort's FILES.BBS 'header prefix' slightly changed for better screen
  1784. presentation to online Maximus users.
  1785. :li.Some cosmetic improvements in IPF-lists.
  1786. :li.File size now reported in max 4 digits: KBytes or MBytes, depending on
  1787. size, except in overviews.
  1788. :li.Bug fixes:
  1789. :ul compact.
  1790. :li.Several problems with 32-bits version related to occurances of filenames
  1791. with lower case characters solved by translating filenames to upper case.
  1792. :li.Continuation lines in BBS-list will have now required privilege-prefix!
  1793. :li.Comments from FILES.BBS now correctly and completely represented in
  1794. ALL-list, even with AVAstrip active.
  1795. :li.Explicit path specifications in FILES.BBS work now correctly.
  1796. :eul.
  1797. :eul.
  1798. :note.This will be the last version with 'extended' commandline parameters.
  1799. List specification parameters will disappear, specification of a
  1800. configuration file and some others, like 'run quiet/verbose', will remain.
  1801. .*
  1802. :h2.Version 5.7
  1803. :ul compact.
  1804. :li.A 32-bit version (OS/2 2.0+ only) added to runtime package, no
  1805. functional differences with the family version.
  1806. :li.ICON file DOWN386.ICO added for the 32-bit version of Downsort.
  1807. :li.Long areanames (8 characters) are now supported in all reports.
  1808. :li.Changed naming convention of 'FILES.BBS' output files when area's
  1809. with 'long' (more than 3 character) names are used.
  1810. :li.The "FILES.BBS"-type of output (selected with FILFileList in
  1811. Downsort.Cfg) now produces a slightly different header.
  1812. Downsort recognises its own header and an included-file without
  1813. 'multiplication'-effects.
  1814. :li.Explicit path specifications of files in FILES.BBS are now supported.
  1815. As a consequence:
  1816. :ul compact.
  1817. :li.The long format of OK-FileList will contain this explicit path
  1818. in stead of the filearea path.
  1819. :li.It seems more appropriate to list the pathspec in the DUP-FileList
  1820. rather than the file description.
  1821. :eul.
  1822. :hp2.Generic filenames (wildcard specifications) are NOT supported
  1823. (yet)!:ehp2.
  1824. :li.File size and date can be included in FILES.BBS output with the '-L'
  1825. option on the FILFileList line in Downsort.Cfg.
  1826. :li.A new keyword 'NonDupEXT' allows suppression of reporting a file as
  1827. 'duplicate' when it is a member of a pair of files with specified
  1828. extensions.
  1829. Example xyz.SDN and xyz.SDA can be excluded from DupFileList.
  1830. :li.Doc-file now also included as provisional .INF file for OS/2 VIEW.
  1831. :li.Improved Avatar stripping.
  1832. :li.Bug fix for long 'new'-filelist periods (>32000 days).
  1833. :li.Separation between progress signals (stdout) and error messages (stderr)
  1834. and other 'internal' changes:
  1835. :li.Preparations made to remove most commandline parameters.
  1836. It has been redundant for a long time.
  1837. Every Downsort specification on the commandline can also be made via
  1838. Downsort.Cfg.
  1839. Exception: Specification of a configuration file will remain possible!
  1840. Good arguments may change this intention, so please object if I am
  1841. overlooking something.
  1842. :eul.
  1843. .*
  1844. :h2.Version 5.6
  1845. :ul compact.
  1846. :li.In stead of the regular OKFile format (path\*.*), there is now also
  1847. an option (/L) to produce a LONG format of the OKFile, containing
  1848. explicitly all files within privilege with complete file-specification
  1849. (path\filename.ext).
  1850. Useful for file-requests at systems with large directories, and
  1851. especially with CDROM's.
  1852. With this option in effect, the *.* entries will not be generated, so
  1853. file requests are only honored with EXACT filenames: wildcard
  1854. specifications do not work anymore!
  1855. :li.Improved display of long areanames (>3 char) in ALL- and
  1856. IPF-lists.
  1857. :li.Avatar codes may be stripped from comment lines in reports.
  1858. :li.Missing include-files are now only reported when running Downsort in
  1859. -V(erbose) mode.
  1860. :li.Some bug fixes (some of them causing Trap 000D under OS/2):
  1861. :ul compact.
  1862. :li.If 'downsort.cfg' not found, return code 2 is reported, and
  1863. downsort.cfg now closed at end of file.
  1864. :li.Output of FILES.BBS could be erraneous when also IP2-list selected.
  1865. :li.Limit of 217 active area's now relieved (this limit was not
  1866. documented!).
  1867. :li.Improved handling of parameters of FILFilePath-line in the sample
  1868. Downsort.Cfg file.
  1869. Also the explanatory comments are revised.
  1870. :eul.
  1871. :li.'-'-character now precedes the formfeed character in newly created
  1872. FILES.BBS files (version 5.6h+).
  1873. :li.Downsort source is now compilable with IBM C-Set/2 compiler and IBM
  1874. OS/2 2.0 toolkit to obtain a real 32-bit version for OS/2 2.0+.
  1875. :eul.
  1876. .*
  1877. :h2.Version 5.5
  1878. :ul compact.
  1879. :li.Finally(!) a sort capability for area-sequence.
  1880. Areas can now be presented in order of AREA.DAT ('K'eep original
  1881. sequence), sorted on areaname ('A'lphabetically), sorted in
  1882. alphanumeric ('G'roup) sequence or in order of areaINclude ('I').
  1883. The group-sequence is useful with a popular naming convention whereby the
  1884. areaname starts with one or more letters followed by one or more digits.
  1885. Names starting with a digit will be sorted as if it were all numeric,
  1886. and will be sorted accordingly.
  1887. :li.NEW-, BBS-list and EMI-list (see below) can now also be limited in
  1888. length by file-age (period specification in number of Days, Weeks or
  1889. Months).
  1890. :li.A new list-type introduced: EMI-list (new file EMIsions).
  1891. I is a simple list, comparable to NEW-list.
  1892. It has a more compact format, and gives also file-time and the file-size
  1893. (in exact bytes).
  1894. It is especially useful to generate messages with file arrivals
  1895. over the last period (in combination with a period specification).
  1896. :li.Readability improvements in IP2-list.
  1897. :li.Documentation extended with sample output for new users of Downsort.
  1898. :li.Some bug-fixes:
  1899. :ul compact.
  1900. :li.Compares of path- and area-names now case INdependent
  1901. :li.Memory allocation error during collection of comments in FILES.BBS
  1902. :li.Index out-of-range in report preparation phase
  1903. :li.Processing of /K-option for areas with FILES.BBS but otherwise empty.
  1904. :eul.
  1905. :eul.
  1906. .*
  1907. :h2.Version 5.4
  1908. :ul compact.
  1909. :li.Inline comments in FILES.BBS will be reproduced now!
  1910. When AND ONLY WHEN the /K option is specified for All- or IPF-list, or
  1911. for FILFilePath, the original existing comments in FILES.BBS are
  1912. copied into All- or IPF-list or newly created FILES.BBS files.
  1913. So note: /K means now: Keep sequence of FILES.BBS
  1914. :hp2.and Keep comments in FILES.BBS:ehp2. and other lists that support
  1915. the /K option (ALL-, IPF and IP2-list).
  1916. :note./K is now the default sort parameter for FILFilePath, so that you do
  1917. not loose your comments accidently.
  1918. :li.Downsort's interpretation of the meaning of 'orphan' changed a
  1919. little: an 'orphan' is from now on defined as a file for which there is
  1920. no description in any FILES.BBS of all areas pointing to the same
  1921. directory.
  1922. This may reduce improper(?) orphan-reporting by previous versions of
  1923. Downsort considerably when you have physically a single large directory
  1924. of which the files are grouped logically in different areas with separate
  1925. FILES.BBS files.
  1926. :li.Duplicate download directories in OK-files will be suppressed.
  1927. :li.Area-summaries in ALL- and IPF-lists are again sorted alphabetically
  1928. on area-name.
  1929. :li.A check during the data collection phase on maximum supported file
  1930. entries (16350) has been added to prevent problems when exceeding this
  1931. limit.
  1932. :li.Orphan entries in FILES.BBS are now preceeded with '&caret.PS' in
  1933. stead of the unsupported '&caret.PH' (bug fix).
  1934. :li.Some specific adaptations for version 2.0:
  1935. :ul compact.
  1936. :li.All files conforming to filespec 'FILES.*' will not be reported
  1937. anymore.
  1938. :li.Area code will be handled as 9 character string: area-name!
  1939. But in some reports it will be truncated to the first 3 or 4 characters.
  1940. :li.AreaINclude and AreaEXclude are used as 'prefix'.
  1941. Area-name specifications will be treated as group-names:
  1942. you can include or exclude groups of areas starting with the same
  1943. characters.
  1944. :li.The /b, /t, /bt or /tb flag in FILES.BBS will not appear in the
  1945. lists, but only when it appears immediately after the filename.
  1946. It is not stripped from FILES.BBS.
  1947. :eul.
  1948. :li.As experiment a new list has been added: IP2FileList.
  1949. It is a copy if IPF-list, but uses some new formatting features offered
  1950. by the IPF-compiler of the OS/2 2.0-beta toolkit (i.c. &colon.table.).
  1951. The result is a faster generation, but above al a faster compilation
  1952. and a better VIEW.
  1953. VIEWing under OS/2 1.2 or 1.3 is still possible!
  1954. :eul.
  1955. .*
  1956. :h2.Version 5.3
  1957. :ul compact.
  1958. :li.New report added: DUP-list, a simple list, for SYSOP-use only, that
  1959. shows (possibly) duplicate fileNAMES over the area's (the file-extension
  1960. is not considered in the comparison).
  1961. :li.Another new report: OKFile in BinkleyTerm style.
  1962. A list of download paths within privilege, with option to include magic
  1963. names.
  1964. :li.IpfFileList line in Downsort.Cfg now also allows specification of
  1965. the IPF pagesize (maximum number of file-entries per VIEW 'page' or
  1966. 'part').
  1967. :li.Progress signals streamlined, /Q is really silent now!
  1968. :li.Fixed bug which caused Trap 000D under OS/2 (protection violation)
  1969. under some rare conditions.
  1970. The restriction that first area may not be empty or not contain only
  1971. orphans has been removed with this change.
  1972. :li.Support for MAXIMUS CBCS 1.00 removed: only version 1.02 is
  1973. supported (and most likely 2.00 as well).
  1974. :li.Downsort's change-history before version 5.0 removed from
  1975. documentation.
  1976. :li.Use of MicroSoft C Compiler 6.00a: more free memory for DOS users
  1977. (also because of slightly improved program structuring).
  1978. :eul.
  1979. .*
  1980. :h2.Version 5.2
  1981. :ul compact.
  1982. :li.Area selection is now possible within Downsort.
  1983. Two new keywords are provided in Downsort.CFG:
  1984. :hp2.AreaINclude:ehp2. to make reports for selected download area's,
  1985. :hp2.AreaEXclude:ehp2. to omit area's from the reports.
  1986. These keywords have only effect within the collection that would
  1987. otherwise have been reported completely (restricted by AREA.DAT and
  1988. report privilege).
  1989. :li.FILES.BBS has now a peer relation with the directory in stead of
  1990. being subordinate, in Downsort terms of course.
  1991. Filenames and their description in FILES.BBS for which there is no
  1992. corresponding file in the download directory, are now NOT ignored
  1993. anymore.
  1994. In stead the file is reported as 'offline' (on the columns for file-date
  1995. and -size).
  1996. You may replace the word 'offline' with an alternative text.
  1997. :li.Bug repaired that caused some files to be treated as orphan under
  1998. certain rare circumstances.
  1999. And a correction of an error in 'end-of-line' test/search on several
  2000. places.
  2001. :li.As already 'promised' in 5.1, the Area-summary in ALL-list is now in
  2002. order of AREA.DAT.
  2003. :li.Reorganised the documentation to obtain a more logical sequence of
  2004. subjects.
  2005. Due to the growing number of options of Downsort, it became more and
  2006. more difficult to see the trees through the wood.
  2007. I added a number of paragraphs, especially for new users.
  2008. It can be useful for YOU too!
  2009. :eul.
  2010. .*
  2011. :h2.Version 5.1
  2012. :ul compact.
  2013. :li.Since the ORPhan report is optional (changed with version 5.0),
  2014. orphan entries could and now will be removed from internal storage
  2015. during the information collection phase of Downsort, but
  2016. :hp2.only when no orphan-list is requested:ehp2.!
  2017. This is especially useful for the situation where a single large
  2018. directory contains the files of several area's, and whereby the file
  2019. descriptions are contained in different FILES.BBS files.
  2020. Normally this will result in reporting lots of duplicate orphans
  2021. (according to the definition of 'orphan' in Downsort!).
  2022. With this change memory utilisation is lower and sorting faster.
  2023. :li.Another change of this kind: area's with a privilege exceeding
  2024. any reporting privilege are not scanned anymore.
  2025. Apart from lower memory utilisation, this might be useful for CDROM and
  2026. slow disk(ette) systems.
  2027. :li.The maximum number of Top-, Sub- and Bottom-Title lines has been
  2028. extended to 20.
  2029. :li.In addition all lists may now include a 'logo'-file with a new -I
  2030. parameter on the individual report request specification (see sample
  2031. Downsort.CFG).
  2032. The file will be copied into the list without any editing or
  2033. translation.
  2034. It will be positioned directly behind the block-title and before the
  2035. subtitle (if any).
  2036. For example: you may include your BBS-logo or a picture of your system
  2037. configuration, or anything else you want to tell the file-requestors of
  2038. FILES, ALLFILES and/or NEWFILES.
  2039. The IPF-list may also include IPF tags, with artwork, etc.
  2040. It may even include other files itself!
  2041. For FILES.BBS the contents of this Include-file will immediately follow
  2042. the 'standard' header.
  2043. :li.All block-fonts have now a new special character <`> (reversed
  2044. quote), which will be 'printed' as blank (space) with :hp2.half:ehp2.
  2045. the width of a normal character.
  2046. This is useful for fine-alignment (e.g. manually centering) the
  2047. BLOCK-title.
  2048. :li.The chapter on 'titles and headers' has been rewritten to clarify
  2049. the use of all title-options, :hp2.please read it!:ehp2..
  2050. :li.In the SUMMARY of ALL- and IPF-lists the areas themselves
  2051. are not sorted anymore, but presented in sequence of AREAS.CTL
  2052. specification.
  2053. This is based on the assumption that the file area's are in some kind of
  2054. 'natural' order in AREAS.CTL (or maybe it is time to do that now!).
  2055. :li.Descriptions in FILES.BBS are now (again) aligned on column 14 of
  2056. the FILES.bbs file records.
  2057. :li.IPF-list again a little more user-friendly (linking of area's).
  2058. :li.A number of improvements have been applied to the executiontime
  2059. messages (when running in VERBOSE mode).
  2060. :eul.
  2061. .*
  2062. :h2.Version 5.0
  2063. :ul compact.
  2064. :li.Improved IPF-formatting: more colorful, builtin word-wrapping of
  2065. VIEW used for file descriptions (better VIEWable under OS/2 1.3!).
  2066. It should now also compile without errors/warnings.
  2067. Compiling (with IPFC) takes significantly longer however!
  2068. :li.The IPF-list of large filearea's (>200 files) split into parts of
  2069. 200 files to prevent files being left unlisted.
  2070. :li.Top-level title in FileLists shows file-count and byte-count as
  2071. available within the privilege of the list.
  2072. Thus it indicates what is really AVAILable to the user!
  2073. Area-count omitted in lists which are not area-oriented.
  2074. :li.ORPHAN report made OPTIONAL (must be specified to get it!).
  2075. :eul.
  2076. .*
  2077. .* =============================
  2078. :h1 id=ause.World-wide use of Downsort
  2079. :p.PC-Square may be considered as the home-base of Downsort.
  2080. The most recent version is always available there
  2081. (file-requests honoured between 07:00 and 24:00 local time).
  2082. :xmp keep=off.
  2083. :hp2.
  2084. PC-Square               Marcel Stikkelman     Zoetermeer, Netherlands
  2085. 2&colon.512/4                                       31-79-424107
  2086. :p.Among many others, the following SYSOPs have reported running Downsort
  2087. to make file collection lists for their users, and have a recent version
  2088. available for download or file request.
  2089.  
  2090. OS/2 TASK               Rene Carlsen          Skagen, Denmark
  2091. 2&colon.230/910                                     45-98-451070
  2092.  
  2093. Paradigmus Maximus      John Taylor           London, UK
  2094. 2&colon.253/68                                      44-81-566-5393
  2095.  
  2096. Ursus Fremens Rexx      Colin Adams           Preston, UK
  2097. 2&colon.255/121                                     44-772-828975
  2098.  
  2099. Chat                    Lody Caenen           Koog aan de Zaan, Netherlands
  2100. 2&colon.280/801                                     31-75-704045
  2101.  
  2102. Runnin' with the Devil  Stefano Sonzogni      Treviglio BG, Italy
  2103. 2&colon.331/205                                     39-363-303567
  2104.  
  2105. Castillo Centro         Santiago Crespo       Madrid, Spain
  2106. 2&colon.341/24                                      34-1-5477210
  2107.  
  2108. Fernwood                Emmitt Dove           Branford CT, USA
  2109. 1&colon.141/109                                     1-203-483-0348
  2110.  
  2111. The Planet Earth        Joel Lambert          Bridgeport CT, USA
  2112. 1&colon.141/455                                     1-203-335-7742
  2113.  
  2114. OS/2 Shareware          Pete Norloff          Fairfax VA, USA
  2115. 1&colon.109/347                                     1-703-385-4325
  2116.  
  2117. Singing Bear            John Tarbox           Wilmington DE, USA
  2118. 1&colon.150/130                                     1-302-984-2238
  2119.  
  2120. La Jungle BBS           Stephane Seguin       Quebec, Canada
  2121. 1&colon.163/116                                     1-819-595-4917
  2122.  
  2123. The Choice BBS          Mark Woolworth        Las Vegas NV, USA
  2124. 1&colon.209/710                                     1-702-253-6527
  2125.  
  2126. 3M Australia            Graham Stair          Pymble, NSW Australia
  2127. 3&colon.711/409                                     61-2-498-9184
  2128.  
  2129. Serendipity Inc         Poe Lim               Cowra, NSW Australia
  2130. 3&colon.623/630                                     61-63-41-1859
  2131. .*
  2132. .* HCC FIDO Groningen-1  Johan Schaaphok  Groningen
  2133. .* 1:153/738             John Cathie      New Westminster, B.C. Canada
  2134. .* 2:245/8               Peter Kaszanics                 , Germany
  2135. .* 2:234/99              Iver Thuessen s                 , Denmark
  2136. :ehp2.
  2137. :exmp.
  2138. :p.I have received reports from others.
  2139. Too many for this list, which is just meant to point to a system
  2140. in your neighbourhood(?).
  2141. You may either logon to one of these boards, or perform a file-request
  2142. of 'FILES' or 'ALLFILES' to get an impression of Downsort's
  2143. capabilities.
  2144. .* =============================
  2145. :h1 id=lsmp.Sample Lists
  2146. :p.Below follow a number of samples of list layouts and contents.
  2147. Not shown are the BBS-, and IPF-lists, since these are screen- rather
  2148. than paper-oriented, with their specific formatting and color settings.
  2149. :p.The dates and sizes in these lists have been manipulated!
  2150. .* ---------
  2151. :h2.ALL-list
  2152. :xmp keep=on.
  2153. :on3270.
  2154.  
  2155. ═══════════════════════════════════════════════════════════════════════════════
  2156.  █▀▀▀▀▀▀   █  ║ OS/2 - Fernwood - New Acquisitions
  2157.  █▄▄▄▄▄   ▄█  ║ Available: 143 files (0.0 MB)
  2158.  ██       ██  ║ Privilege: Disgrace
  2159.  ██       ██  ║ Newest: XLIST233.ZIP  3-22-91  (avail:  7-26-91)
  2160. ───────────────────────────────────────────────────────────────────────────────
  2161. Filename      Size   Date    Description
  2162. ──────────── ───── ───────── ──────────────────────────────────────────────────
  2163. AAFONTS.ZIP     1K  3-22-91  Text from IBM regarding Anti-aliased Fonts.
  2164. AFP_120.LZH     1K  3-22-91  Areafix 1.2 for OS/2.  Permits systems that do
  2165.                              echomail with yours to change their complement of
  2166.                              areas independently.
  2167. :off3270
  2168. :exmp.
  2169. .* ---------
  2170. :h2.GBL-list
  2171. :xmp keep=on.
  2172. :on3270.
  2173.  
  2174. (Sun Jan 05 15:05) Available: 508 files (0 MB)
  2175.                    Maximum privilege shown: Sysop
  2176.                    Newest: BIGBRO.ZIP  3-22-91 (avail:  7-26-91)
  2177.                    Date flag: new on this system since: * = 1 week, + = 1 month
  2178.  
  2179. Filename       Area    Size   Date    Description
  2180. ──────────── ──────── ───── ───────── ─────────────────────────────────────────
  2181. 2COLDIR.ZIP        F3    1K  3-22-91  DoubleDir for OS/2
  2182. 2MONITOR.ZIP       F4    1K  3-22-91  Source and .EXE for running 2 monitors.
  2183. :off3270.
  2184. :exmp.
  2185. .* ---------
  2186. :h2.NEW-list
  2187. :xmp keep=on.
  2188. :on3270.
  2189.  
  2190. (Sun Jan 05 16:14) Last 10 months newest of a total of 508 files (0 MB)
  2191.                    Maximum privilege shown: Sysop
  2192.                    Newest: BIGBRO.ZIP dd  3-22-91 (avail:  7-26-91)
  2193.                    Date flag: new on this system since: * = 1 week, + = 1 month
  2194.  
  2195. Filename       Area    Size   Date    Description
  2196. ──────────── ──────── ───── ───────── ─────────────────────────────────────────
  2197. 2COLDIR.ZIP        F3    1K  3-22-91  DoubleDir for OS/2
  2198. 2MONITOR.ZIP       F4    1K  3-22-91  Source and .EXE for running 2 monitors.
  2199. 8514.PAT           F4    1K  3-22-91  Patch to get 32x32 icons on 8514/a
  2200. :off3270.
  2201. :exmp.
  2202. .* ---------
  2203. :h2.EMI-list
  2204. :xmp keep=on.
  2205. :on3270.
  2206.  
  2207. (Tue Jan 14 21:55) Last 44 weeks newest emissions
  2208.  
  2209. --Filename-- --Date--  -Time-  -Bytes-  ---Description---
  2210. DUMMY.DAT    10-11-91   9:45p       31  Dummy file for Downsort tests +
  2211.              continuation line
  2212. PSOS2.ZIP     3-22-91  11:46p        2  View OS/2 Information on PM like
  2213.              Threads & Process, Memory used, and more.
  2214. :off3270.
  2215. :exmp.
  2216. .* ---------
  2217. :h2.FILES.BBS
  2218. :xmp keep=on.
  2219. :on3270.
  2220.  
  2221. - █▀▀▀▀▀▀   █  ║ OS/2 - Fernwood - New Acquisitions
  2222. - █▄▄▄▄▄   ▄█  ║ Available: 143 files (0.0 MB)
  2223. - ██       ██  ║ Privilege: Disgrace
  2224. - ██       ██  ║ Newest: XLIST233.ZIP  3-22-91 (avail:  7-26-91)
  2225. -──────────────────────────────────────────────────────────────────────────────
  2226. -Filename      Size    Date     Description
  2227. -─────────── ─────── ───────── ────────────────────────────────────────────────
  2228. AAFONTS.ZIP   Text from IBM regarding Anti-aliased Fonts.
  2229. AFP_120.LZH   Areafix 1.2 for OS/2.  Permits systems that do echomail . . . .
  2230. :off3270.
  2231. :exmp.
  2232. :note.File date and size are provided dynamically by Maximus CBCS!
  2233. .* ---------
  2234. :h2.OKfile
  2235. :h3.Short format (default)
  2236. :xmp keep=on.
  2237. @files G:\File\File01\allfiles.zip
  2238. @avail G:\File\File01\allfiles.zip
  2239. @newfiles G:\File\File01\newfiles.zip
  2240. G:\File\Fernwood\*.*
  2241. G:\File\Max\*.*
  2242. :exmp.
  2243. .*
  2244. :h3.LONG format (-L)
  2245. :xmp keep=on.
  2246. @files G:\File\File01\allfiles.zip
  2247. @avail G:\File\File01\allfiles.zip
  2248. @newfiles G:\File\File01\newfiles.zip
  2249. @DWNSRT55.ZIP G:\File\Fernwood\DWNSRT55.ZIP
  2250. @DWNSRT56.ZIP G:\File\Fernwood\DWNSRT56.ZIP
  2251. @MAXSRT10.ZIP G:\File\Max\MAXSRT10.ZIP
  2252. @MAXSRT11.ZIP G:\File\Max\MAXSRT11.ZIP
  2253. :exmp.
  2254. .* ---------
  2255. :h2.ORPhan list
  2256. :xmp keep=on.
  2257. :on3270.
  2258.  
  2259. ═══════════════════════════════════════════════════════════════════════════════
  2260.   Area    Filename      Date    FilePath
  2261. ──────── ──────────── ───────── ───────────────────────────────────────────────
  2262.       F1 123R3UPD.ZIP  3-22-91  G:\File\Fernwood\
  2263.       F1 4019DRVR.ZIP  3-22-91  G:\File\Fernwood\
  2264. :off3270.
  2265. :exmp.
  2266. .* =============================
  2267. :h1 id=acfg.Sample Configuration File
  2268. :xmp keep=off
  2269. :cgraphic scale='0.9'.
  2270. :on3270.
  2271. .im downsort.cfg
  2272. :off3270.
  2273. :ecgraphic.
  2274. :exmp.
  2275. :euserdoc.
  2276.