home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Professional / OS2PRO194.ISO / os2 / com / bbs / downsrt / source / downsort.scr < prev    next >
Text File  |  1991-06-16  |  77KB  |  1,746 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 tables for host uploads from OS/2 3270-sessions
  11. .* ==========================================================
  12. .dm on3270 on
  13. .if &$SYS ne pc .ti 31 10  78 13  be 30  80 31  15 21  64 23
  14. .if &$SYS ne pc .ti 76 12  77 22  30 32  24 33  6a 11
  15. .if &$SYS ne pc .ti ff 10  17 13  23 30  28 31  9d 21  22 23
  16. .if &$SYS ne pc .ti 8e 12  06 22  72 32  29 33  70 11
  17. .if &$SYS ne pc .ti ba b0 bb 6a
  18. .dm off
  19. .*
  20. .* ╔═╦════╗  ┌─┬────┐
  21. .* ╠═╬════╣  ├─┼────┤
  22. .* ║ ║    ║  │ │    │
  23. .* ╚═╩════╝  └─┴────┘
  24. .*
  25. .dm off3270 on
  26. .if &$SYS ne pc .ti 31 31 78 78 be be 80 80 15 15 64 64
  27. .if &$SYS ne pc .ti 76 76 77 77 30 30 24 24 6a 6a
  28. .if &$SYS ne pc .ti ff ff 17 17 23 23 28 28 9d 9d 22 22
  29. .if &$SYS ne pc .ti 8e 8e 06 06 72 72 29 29 70 70
  30. .if &$SYS ne pc .ti ba ba bb bb
  31. .dm off
  32. .aa on3270  on3270
  33. .aa off3270 off3270
  34. .* ==========================================================
  35. .*
  36. .nameit symbol=VERSION text='5'.
  37. .nameit symbol=SUBVERS text='1'.
  38. .nameit symbol=SUFFIX  text=' '.
  39. .*
  40. .*
  41. :title.DOWNSORT
  42. Maximus CBCS DOWNload file SORT and List Utility (OS/2 and DOS)
  43. Version &VERSION..&SUBVERS.&SUFFIX.
  44. :etitle.
  45. :author.Rob Hamerling
  46. :date.
  47. :address.
  48. Vianen, The Netherlands
  49. Phone: ++31-3473-72136 (voice)
  50. FIDO-net: 2&colon.512/4.1098
  51. :eaddress.
  52. :docprof rhrfrule=none
  53. language=english figlist=nopage tlist=nopage ftsep=no
  54. layout=2 fbc=no toc='*3' ldrdots=yes.
  55. :revision id=rev51 run=yes.
  56. :eprolog.
  57. :frontm.
  58. :tipage.
  59. :toc.
  60. :body.
  61. .* ==============================================================
  62. :h1.About DOWNSORT
  63. :p.DOWNSORT was started a few years ago as a program for my own use when
  64. I was SYSOP of the Bulletin Board PC-Square, to get overviews of my
  65. download material for the users.
  66. The program name is related to the SORTing of the collection of
  67. DOWNloadable files, in DOWNward time-stamp sequence and a Bulletin
  68. was the only list that was produced at that time.
  69. Also PC-Square was running BinkleyTerm and OPUS under DOS, and
  70. file-requesting was not so popular then.
  71. :p.Now PC-Square runs with OS/2, BinkleyTerm and MAXIMUS CBCS,
  72. and I'm not the SYSOP anymore but still strongly involved.
  73. As a contribution to PC-Square and the large international Bulletin
  74. Board community of MAXIMUS CBCS boards,
  75. I decided to upgrade my DOWNSORT program to the current software.
  76. But at the same time a lot of improvements and extensions have been
  77. made: many user-configurable options for many more output formats
  78. then the original DOWNSORT.
  79. :rev refid=rev51.
  80. :p.The only dependency of DOWNSORT on MAXIMUS CBCS is a parameter-file
  81. AREA.DAT, which is usually created with a MAXIMUS utility (SILT(P)),
  82. which itself can be used without actually running MAXIMUS!
  83. This is the way I work for testing DOWNSORT.
  84. :erev refid=rev51.
  85. :p.:hdref refid=ahis. gives an impression of the history.
  86. :p.DOWNSORT is now developed in an OS/2 environment, but it is
  87. distributed as 'family'-application: it runs under OS/2 and DOS.
  88. .* --------------
  89. :h2.Registration and Shareware Fee
  90. :p.DOWNSORT is a $ 0.00 Shareware Program.
  91. This means (to me) that you respect the commonly known rules for
  92. shareware, but you don't have to pay me anything.
  93. :p.Registration is voluntary: please send me a netmail message with your
  94. name and (net-)address if you are a regular user of DOWNSORT as SYSOP.
  95. That gives me an impression of the usage and the impact of changes to
  96. DOWNSORT.
  97. :p.If you tell me that you are running DOWNSORT on your Bulletin Board
  98. as service to your users, I'll add your name to the reference list in
  99. :hdref refid=ause. (if you like).
  100. .* --------------
  101. :h2.Warranty
  102. :p.For this price?
  103. You must be kidding!
  104. But I'll listen to your complaints and suggestions, and if time
  105. permits, I'll work on the improvements you suggest.
  106. .* --------------
  107. :h2.Acknowledgements
  108. :p.I would like to thank all users that contributed with constructive
  109. remarks and encouraging appraisals.
  110. Without doubt Emmanuel Sandorfi of 2&colon.320/5 holds the record in
  111. number of suggestions and amount of additionally required programming
  112. effort.
  113. He also provided some additional title-fonts (2 and 3).
  114. :p.I also would like to thank the regular users (SYSOP's of Bulletin
  115. Boards) who made DOWNSORT much more popular than I ever dreamed of!
  116. A collection of geographically dispersed Boards can be found in
  117. :hdref refid=ause..
  118. .* =============================================
  119. :h1.What DOWNSORT can do for you
  120. :p.DOWNSORT is a utility to make overviews of available download files
  121. for Bulletin Board Systems (usually running MAXIMUS CBCS).
  122. The overviews differ in sort sequence, purpose of use and size.
  123. :p.A report is produced for files that could not be listed for any
  124. reason.
  125. .* ------------------------
  126. :h2.Purpose and Objectives
  127. :p.DOWNSORT is designed for the following purposes:
  128. :ol.
  129. :li.Produce different overviews of files which are available for
  130. download by users of the Bulletin Board and by File Requestors.
  131. QUICK and EASY retrieval is the main goal for the lists.
  132. Therefore many lists-types and within a type several variations
  133. should be available: versatility for SYSOP and users.
  134. :li.Report files which are not listed in FILES.BBS, or which privilege
  135. (individual or its area) prevents it from being reported.
  136. This might be caused by several circumstances:
  137. :ul compact.
  138. :li.a file belongs to a collection (area) with a higher privilege than
  139. the selected report privilege (typically the upload area, but also
  140. restricted collections for selected users).
  141. :li.a file appears in FILES.BBS after a &caret.Px-sequence that
  142. specifies a :hp2.higher:ehp2. privilege than the selected report
  143. privilege (newly uploaded files in a combined up- and download
  144. directory).
  145. :li.an typing-error has been made in the filename.ext in FILES.BBS or a
  146. file has been renamed without updating FILES.BBS.
  147. :li.a file is not listed in FILES.BBS on purpose by SYSOP, to prevent
  148. it being downloaded other than by CO-SYSOP.
  149. :eul.
  150. :li.Must be able to run unattended (typically overnight).
  151. :li.Should not disclose files to users (file-requesters) without
  152. positive agreement by SYSOP.
  153. :eol.
  154. .* --------------------
  155. :h2 id=funcs.Functional Description
  156. :p.The program DOWNSORT may create several types of outputfiles.
  157. .*
  158. :h3.File-dates and HPFS
  159. :p.One of the function of DOWNSORT is sorting on file date.
  160. Since the introduction of HPFS in OS/2 version 1.2, there is not one
  161. single file-date anymore!
  162. A file on an HPFS volume has different values for:
  163. :ul compact.
  164. :li.Creation date
  165. :li.LastAccess date
  166. :li.LastWrite date
  167. :eul.
  168. :p.The date you see normally in DIR-listings is the LastWrite date.
  169. Most SYSOPs will have noticed that ZMODEM uploads and file-attaches
  170. give file-dates corresponding to the (LastWrite-) date of the sending
  171. system.
  172. And most utilities handle only this 'single' date.
  173. That means that 'old' (ZMODEM-) uploaded files are generally not on top
  174. of the acquisition lists.
  175. :p.But HPFS stores the date of arrival on your system (Creation) as
  176. well.
  177. DOWNSORT handles this Creation date since version 4.7, although the
  178. lists (see below) contain the 'old fashioned' LastWrite date.
  179. This has the following consequences:
  180. :ul compact.
  181. :li.A new acquisition is on top of lists (if that list is sorted on
  182. date), and are marked in the lists as new
  183. (flag for an 'age' of a week or a month).
  184. :li.The listed file-date is the 'ordinary' date.
  185. So users can judge for themselves if the file is 'new' for them as well.
  186. :eul.
  187. :note.The LastAccess date is not very relevant for the purposes of
  188. DOWNSORT, although SYSOP may see when it was last downloaded.
  189. .* ----------------------------------------
  190. :h2.File reports (list types)
  191. :p.DOWNSORT can produce several types of output reports,
  192. mostly indicated by type of list.
  193. Below follows for each type of list e general description.
  194. .* ----
  195. :h3.ORPHAN report
  196. :p.This is a list of all files in download directories for which
  197. there is no entry in the corresponding FILES.BBS file.
  198. The report contains date, area-name and area-path of the orphan.
  199. The entries are sorted on area and filename.
  200. Not reported are MAXIMUS system files like:
  201. FILES.?BS, *.BAK, DIR.?BS and SYSTEM*.?BS.
  202. :note.If there is an entry for a file in FILES.BBS without a
  203. description, the file is NOT considered to be an Orphan!
  204. .*
  205. :h3.BBS-list
  206. :p.This is a list of downloadfiles that came recently available
  207. (DOWNSORT.BBS).
  208. The list may be sorted on date (newest first) or on filename.
  209. It contains compiled MECCA control sequences, for direct use in
  210. MAXIMUS bulletins: a user-privilege sensitive list!
  211. It might be a good idea to put a translated &lbrk.onexit&rbrk. string,
  212. which translates to &lbrk.&caret.OFpath&rbrk. (without the brackets!).
  213. When a user exits from the BBS-list bulletin, it will fall back to the
  214. exit-bulletin.
  215. :p.The length of the file (number of file-entries) may be limited by
  216. parameters:
  217. :ul compact.
  218. :li.file-count
  219. :li.maximum privilege
  220. :eul.
  221. :p.(never more than available within the privilege limit).
  222. If neither specified it will contain all available files in all download
  223. directories.
  224. :p.To make it a complete MAXIMUS bulletin-file a user-provided header is
  225. included preceding the list and a trailer at the end of the list.
  226. Header and trailer can be built by SYSOP, and may contain any
  227. information and bulletin-control sequences (a sample is provided).
  228. .*
  229. :h3.NEW-list
  230. :p.Basically the same list as above, but in simple ASCII format
  231. and without inclusion of header and trailer files.
  232. :p.This list is suitable for file-requestors as brief overview of the
  233. latest additions, updates or replacements.
  234. .*
  235. :h3.ALL-list
  236. :p.A list of all downloadfiles by area in alphabetical sequence (per
  237. area) on filename.
  238. Files of the same area are listed in groups, separated by imbedded
  239. headers with area-name, -description, and -privilege.
  240. Actual status information is provided in the area-header as well:
  241. area-filecount and -bytecount, and latest acquisition (date and
  242. file-name).
  243. :p.At the end a SUMMARY report shows per area the area-title,
  244. file-count and byte-count, and totals.
  245. :p.This list may be limited by the privilege parameter, but is not
  246. affected by the specification of filecount-limit.
  247. The numbers in area-header and summary report show only what is
  248. available for the particular privilege.
  249. .*
  250. :h3.IPF-list
  251. :p.Same contents, but different format of ALL-list, only useful for
  252. OS/2 users (OS/2 version 1.2+ under Presentation Manager).
  253. This file has the format of an input-file for the Information
  254. Presentation Facility Compiler (IPFC).
  255. .*
  256. :h3.GBL-list
  257. :p.Similar to ALL-list,
  258. but where ALL-list gives the files in groups per area, the GBL-list
  259. ignores area-boundaries and gives a single group, sorted on filename.
  260. For each file the area is mentioned.
  261. There is no area-summary.
  262. :p.SYSOP may choose which of both is suitable to make available to
  263. users, and which to use for himself (or even both).
  264. The GBL-list is especially useful to check on duplicates over area's.
  265. The GBL-list is not limited by the filecount parameter.
  266. .*
  267. :h3.FILES.BBS
  268. :p.A new "FILES.BBS" type of file may be (re-)created for every area.
  269. The contents of the file-information will be about the same as
  270. the original FILES.BBS, but with the following notes:
  271. :ul compact.
  272. :li.A header is generated with area-name, -title, and -privilege.
  273. Also the total amount of files and bytes and the most recently acquired
  274. new file in this area is part of the header information.
  275. :li.The entries are sorted on filename for all files with a privilege
  276. up to and including the area-privilege.
  277. :li.Files can have a privilege other than the area-privilege when the
  278. original FILES.BBS file does contain &caret.Pp-sequences ('p' being a
  279. privilege letter).
  280. This construction will be rebuilt by DOWNSORT.
  281. Files with a higher privilege than the area-privilege will follow
  282. after a compiled MECCA-sequence (&caret.Pp) in the new FILES.BBS.
  283. DOWNSORT respects these indicators when reading FILES.BBS,
  284. so all file-privilege information is retained.
  285. This ensures no accidental loss of file-information, and the regular
  286. user won't see more than he should.
  287. :li.Wild-card specifications are not propagated to the new FILES.BBS.
  288. :li.The file description is kept internally as a single string of
  289. maximum 240 characters.
  290. When creating FILES.BBS files, this will be the file format (single
  291. record per file-entry).
  292. The original FILES.BBS may contain a (long) single string
  293. description, or multiple (short) multiline descriptions.
  294. When encountering multiline descriptions in input-FILES.BBS, DOWNSORT
  295. concatenates the separate description lines with a single intermediate
  296. space up to a maximum of 240 bytes.
  297. This will be the output format if the FIL-list is requested.
  298. :rev refid=rev51.
  299. :li.All comments and alignments you may have worked on for many hours
  300. is discarded!
  301. :erev refid=rev51.
  302. :eul.
  303. :p.See for naming conventions and placements :hdref refid=hcmd..
  304. .*  -----------------------------
  305. :h2.General notes about the lists
  306. :ol.
  307. :li.Dates are marked with a 'new'-indicator: a '*' if the file
  308. is only since a week on this system, and a '+' if it is since a month.
  309. Filedates later than the current system date are marked '-' (negative
  310. age).
  311. :li.In every outputfile the filename, MAXIMUS-area name, file-size and
  312. -date, and file-description from FILES.BBS is listed.
  313. A report-line will never display more than 79 characters.
  314. :p.The file-description will be multi-line in ALL-, IPF- and GBL-list
  315. if it is longer than would fit on the standard 79-position line, a
  316. word-wrapping technique is used for readability (line-split on word
  317. boundary).
  318. The description is truncated at end of line in BBS-list and NEW-list.
  319. :p.The -T option will force truncation of the description in all reports,
  320. the -W option will allow multi-line descriptions in all reports.
  321. :p.If a filename is found in FILES.BBS, but no accompanying description,
  322. a "--- no description available ---" will be put in place.
  323. A replacing text may be specified with DOWNSORT.CFG.
  324. :p.Files for which there is no entry in the FILES.BBS (Orphans) are
  325. treated as Hidden files, which are only listed in the reports if the
  326. Hidden privilege is specified.
  327. For a way to override this see: :hdref refid=orphan..
  328. :rev refid=rev51.
  329. :note.If you want the orphans to appear in FILES.BBS (or in any other
  330. report), you MUST also request an ORP-list!
  331. :erev refid=rev51.
  332. :li.The BBS-list contains MAXIMUS authorisation controls
  333. (&caret.PLp-sequences), corresponding to the privilege of the area or the
  334. individual file.
  335. So it is not necessary to make different files for different categories
  336. of MAXIMUS users, even with the default privilege-limit SYSOP a
  337. user will not see the files he/she is not supposed to know about.
  338. :p.NEW- and ALL-lists do not contain any privilege information,
  339. the files (or complete area's) above the specified privilege are simply
  340. not listed, however multiple lists can be produced for different
  341. categories of users (based on privilege).
  342. :eol.
  343. .* ==============================================
  344. :h1.How to use DOWNSORT
  345. :p.This chapter tells you how to install DOWNSORT,
  346. how to customise the configuration file and what you might specify on
  347. the commandline.
  348. :p.A sample configuration file (in :hdref refid=acfg.) is part of the
  349. package.
  350. It contains a lot of comments (in Binkley and MAXIMUS  style)
  351. to help you with the changes.
  352. .* --------------------------
  353. :h2 id=inst.Installation
  354. :p.With the following directions you should be able to setup and run
  355. DOWNSORT after very short time.
  356. :ol.
  357. :li.Make a separate directory for DOWNSORT, and make it the current
  358. default directory every time you run DOWNSORT.
  359. The separate directory is a recommendation, not a requirement!
  360. :li.Copy the files DOWNSORT.EXE and DOWNSORT.CFG
  361. from the DOWNSORT package into this directory.
  362. :li.Modify (edit) the file DOWNSORT.CFG to specify your environment and
  363. list requirements.
  364. The sample file contains comments to help you with this process.
  365. Most specifications are obvious.
  366. AreaDat is the most important parameter:
  367. DOWNSORT won't do anything useful if it cannot find this MAXIMUS
  368. file.
  369. See :hdref refid=acfg. for a printed sample.
  370. :li.You may give DOWNSORT a first shot by just using its name
  371. on the commandline, with the parameter -H.
  372. This will show a brief HELP-screen with the possible commandline
  373. parameter specifications.
  374. :li.All reports will be created in the DOWNSORT directory
  375. (unless you specified 'fpath' for the FILES.BBS output).
  376. Browse the lists to see if you like the contents and titles, and modify
  377. the CFG-file to your convenience.
  378. :eol.
  379. .* --------------------------
  380. :h2 id=hcmd.Commandline parameters
  381. :p.This paragraph deals only with the commandline parameters!
  382. :p.NOTE: Parameters from DOWNSORT.CFG are processed first, commandline
  383. parameters may complete and (partly) override those in the configuration
  384. file.
  385. :p.For how to read the command syntax diagram see OS/2 reference manual.
  386. :xmp.
  387. :cgraphic scale='1.1'.
  388. :on3270.
  389.                                       ┌────────────────────────┐
  390.                                       v                        │
  391.  ──┬─────────┬─┬────────┬─ DOWNSORT ────┬────────────────────┬─┴─────┤
  392.    └─ drive ─┘ └─ path ─┘               ├─ @filespec ────────┤
  393.                                         ├─ BBS ─┬──────┬─────┤
  394.                                         │       └─ &colon.p ─┘     │
  395.                                         ├─ NEW ─┬───────┬────┤
  396.                                         │       └─ &colon.pp ─┘    │
  397.                                         ├─ ALL ─┬───────┬────┤
  398.                                         │       └─ &colon.pp ─┘    │
  399.                                         ├─ IPF ─┬───────┬────┤
  400.                                         │       └─ &colon.pp ─┘    │
  401.                                         ├─ GBL ─┬───────┬────┤
  402.                                         │       └─ &colon.pp ─┘    │
  403.                                         ├─ ORP ──────────────┤
  404.                                         ├─ FIL ─┬──────────┬─┤
  405.                                         │       └─ &colon.fpath ─┘ │
  406.                                         ├─ nnn ──────────────┤
  407.                                         ├──┬─ /T ─┬──────────┤
  408.                                         │  └─ /W ─┘          │
  409.                                         ├──┬─ /A ─┬──────────┤
  410.                                         │  ├─ /D ─┤          │
  411.                                         │  └─ /K ─┘          │
  412.                                         ├──┬─ /H ─┬──────────┤
  413.                                         │  ├─ /Q ─┤          │
  414.                                         │  └─ /V ─┘          │
  415.                                         └──── /X ────────────┘
  416. :off3270.
  417. :ecgraphic.
  418. :exmp.
  419. .*
  420. :parml tsize=12 termhi=9.
  421. :pt.@filespec
  422. :pd.The character '@' followed by a complete
  423. :hp2.file specification:ehp2. of the
  424. :hp2.DOWNSORT configuration file:ehp2.
  425. (see :hdref refid=hcfg. for details).
  426. This file will be used to specify processing parameters.
  427. If the file cannot be read, only the commandline parameters are used.
  428. :p.NOTE: The use of a configuration file is mandatory when the file
  429. AREA.DAT is not in the default directory when running DOWNSORT.
  430. :p.Default: DOWNSORT.CFG in current default directory.
  431. .*
  432. :pt.BBS
  433. :pd.Create the BBS-list: DOWNSORT.BBS.
  434. :p.Default: DOWNSORT.BBS will not be created.
  435. .*
  436. :pt.NEW
  437. :pd.Create NEW-list(s): DOWNSORT.N&tilde.p,
  438. where 'p' is the appropriate privilege class (see below).
  439. :p.Default: DOWNSORT.N&tilde.p will not be created.
  440. .*
  441. :pt.ALL
  442. :pd.Create ALL-list(s): DOWNSORT.A&tilde.p,
  443. where 'p' is the appropriate privilege class (see below).
  444. :p.nnn-limit does not apply to ALL-list.
  445. :p.Default: DOWNSORT.A&tilde.p will not be created.
  446. .*
  447. :pt.IPF
  448. :pd.Create IPF-list(s): DOWNSORT.I&tilde.p,
  449. where 'p' is the appropriate privilege class (see below).
  450. :p.nnn-limit does not apply to IPF-list.
  451. :p.Default: DOWNSORT.I&tilde.p will not be created.
  452. .*
  453. :pt.GBL
  454. :pd.Create GBL-list(s): DOWNSORT.G&tilde.p,
  455. where 'p' is the appropriate privilege class (see below).
  456. :p.nnn-limit does not apply to GBL-list.
  457. :p.Default: DOWNSORT.G&tilde.p will not be created.
  458. .*
  459. :pt.ORP
  460. :pd.Create ORP-list: DOWNSORT.ORP (orphan report, if any orphans).
  461. :rev refid=rev51.
  462. :p.If an orphan report is not requested, no other report will contain
  463. any orphan information, even when 'Hidden' is specified as reporting
  464. level.
  465. :erev refid=rev51.
  466. :p.Default: DOWNSORT.ORP will not be created.
  467. .*
  468. :pt.FIL
  469. :pd.Create FILES.BBS type of files for each area.
  470. :p.The specification does not apply to FILES.BBS, a privilege-limit
  471. cannot be specified and defaults to SYSOP.
  472. Another privilege limit can be specified however by means of the
  473. configuration file.
  474. :p.For each individual area the following convention will be used
  475. for the name and place of the FILES.BBS list (in this sequence):
  476. :ol compact.
  477. :li.If the "FIL&colon." parameter specifies a directory-path, then for
  478. each area the :hp2.output:ehp2. file "FILES.ac" is put in the specified
  479. directory ('ac' is 1 or 2 char area-code).
  480. Previous files with the same name will be discarded.
  481. :li.If "ListFile" is specified in AREA.CTL, then that name and path will
  482. be used.
  483. :li.Otherwise the file FILES.BBS: will be put in the directory with the
  484. download files.
  485. :eol.
  486. :p.For situations 2 and 3 existing files will be renamed to .BAK
  487. (older .BAK files will be discarded).
  488. :p.Default: FILES.BBS-type of files will not be generated.
  489. .*
  490. :pt.fpath
  491. :pd.Optional directory path specification for FILES.BBS-output.
  492. See the "FIL&colon." parameter for usage.
  493. :p.Default: none
  494. .*
  495. :pt.nnn
  496. :pd.Maximum number of files to be reported in the BBS- and NEW-list(s).
  497. A maximum value of 32767 can be specified,
  498. it does not apply to ALL-, IPF- and GBL-list.
  499. :p.Default: all files up to and including the (specified or default)
  500. privilege class will be listed for all types of lists.
  501. .*
  502. :pt.p
  503. :pd.Single privilege character.
  504. :p.Lists only download files with a privilege of up to and including
  505. privilege 'p'.
  506. The indicator must be the first character of an existing MAXIMUS
  507. privilege level (T, D, L, N, W, P, F, E, C, A, S, H).
  508. No error-message is given for an invalid privilege character,
  509. there will simply be no file-list for an invalid character!
  510. :p.For the BBS-list only a single privilege character is allowed,
  511. the listfile is always called: DOWNSORT.BBS.
  512. :p.Default: S  (SYSOP):  files of all privilege levels will be listed,
  513. except HIDDEN files (with real Hidden privilege or files for which no
  514. entry could be found in FILES.BBS).
  515. .*
  516. :pt.pp
  517. :pd.Multiple privilege characters (minumum 0, maximum 10).
  518. :p.Make for every valid specified privilege level a download-list
  519. with files of a privilege of up to and including privilege 'p'.
  520. The indicator must be the first character of an existing MAXIMUS
  521. privilege level.
  522. No error-message is given for an invalid privilege character,
  523. there will simply be no file-list for an invalid character!
  524. :p.Applies to ALL-, IPF- and NEW-lists, these are called
  525. DOWNSORT.A&tilde.p and DOWNSORT.N&tilde.p respectively, were 'p'
  526. represents the applicable privilege character.
  527. :p.Default: S  (SYSOP):  files of all privilege levels will be listed,
  528. except HIDDEN files (with real Hidden privilege or files for which no
  529. entry could be found in FILES.BBS).
  530. .*
  531. :pt./T /W
  532. :pd.Action to be taken if the file description would cause the
  533. reportline to exceed 79 characters:
  534. :ul compact.
  535. :li.T&rbl.-&rbl.:hp4.t:ehp4.runcate the description
  536. :li.W&rbl.-&rbl.:hp4.w:ehp4.rap the description and provide as many
  537. reportlines as needed to show the complete description.
  538. :eul.
  539. :p.Default: -T for NEW-list and BBS-list, -W for ALL-, IPF- and GBL-list.
  540. .*
  541. :pt./A /D /K
  542. :pd.Sort method for BBS-list and NEW-list.
  543. :ul compact.
  544. :li.A&rbl.-&rbl.Sort the files :hp4.a:ehp4.lphabetically on filename.
  545. :li.D&rbl.-&rbl.Sort the files on reversed :hp4.d:ehp4.ate sequence
  546. (newest file on top of list).
  547. :li.K&rbl.-&rbl.:hp4.k:ehp4.eep lines in sequence of FILES.BBS.
  548. :eul.
  549. :p.When the -A option is selected, an additional header-line will appear
  550. in the BBS-list and NEW-list, indicating the latest acquisition.
  551. This line is not needed when these lists are sorted on date, since the
  552. the latest acquisition will be on top of the list!
  553. :p.The -K option is only useful in situations where the files are
  554. primarily grouped on AREA, i.c. ALL-, IPF- and FIL-list.
  555. :p.Default: -D
  556. .*
  557. :pt./H /Q /V
  558. :pd.Operating mode
  559. :ul compact.
  560. :li.H&rbl.-&rbl.:hp4.h:ehp4.elp:  display screen with essential
  561. information about running DOWNSORT, such as the command syntax.
  562. In that case the program will not undertake any other action.
  563. :li.Q&rbl.-&rbl.:hp4.q:ehp4.uiet:  display only start and
  564. finish-message, and error messages which prevent the program from
  565. proceeding normally.
  566. :li.V&rbl.-&rbl.:hp4.v:ehp4.erbose:  display a lot of progress messages.
  567. :eul.
  568. If neither -Q nor -V is specified, than the number of console messages
  569. will be 'intermediate': more than -Q, but less than -V.
  570. :p.Default: none
  571. .*
  572. :pt./X
  573. :pd.Exclude Privilege Indications
  574. :ul compact.
  575. :li.X&rbl.-&rbl.e:hp4.x:ehp4.clude privilege indications in all list-types.
  576. Some SYSOPs want to hide any kind of privilege-system for users and
  577. file-requesters of their Bulletin Board System.
  578. With the -X option specified all privilege indications will be
  579. suppressed.
  580. :note.This does not apply to the compiled MECCA privilege controls in
  581. the BBS-list!
  582. :eul.
  583. :p.Default: none (privilege indications will be reported).
  584. .*
  585. :eparml.
  586. :ol.
  587. :li.All commandline parameters are optional, may be specified in any
  588. sequence and are case independent.
  589. :li.Parameters from the configuration file are processed before those
  590. from the commandline.
  591. This has some side-effects, like:
  592. :ul compact.
  593. :li.If you specify a specific list in DOWNSORT.CFG, it will be created
  594. anyhow, whatever you specify on the commandline.
  595. :li.However, if you specify privilege values on the commandline, only
  596. the commandline values will be used, and none from the configuration
  597. file.
  598. :li.Commandline parameters have a global meaning, and are applied to all
  599. lists (if applicable).
  600. For example: if you specify '-A' on the commandline, all lists will be
  601. sorted alphabetically on filename.
  602. :eul.
  603. :li.Parameters that can be specified with the configuration file only,
  604. and cannot be overridden with a commandline parameter are:
  605. :ul compact.
  606. :li.BLOCK title text, font and BLOCK title suppression
  607. :li.Subtitle lines
  608. :li.Filename and individual list-options
  609. :li.Privilege for FILES.BBS output
  610. :eul.
  611. :li.Even when specified on the commandline, or in DOWNSORT.CFG,
  612. the Orphan-report will be generated only if there are any orphans,
  613. and then the specified parameters apply.
  614. :li.The IPF-list has to be processed by the Information Presentation
  615. Facility Compiler (IPFC).
  616. This compiler is part of the IBM Programmers Development Toolkit version
  617. 1.2 and 1.3 (maybe also in some other toolkit).
  618. The following command has to be issued:
  619. :xmp.
  620.     IPFC  DOWNSORT.IPF  /INF
  621. :exmp.
  622. :p.The option "/INF" is essential (but not documented!) to obtain
  623. a viewable file.
  624. Be also sure to have the file DOWNSORT.BMP in your current default
  625. directory, or in DPATH, as this will be imbedded by the IPF-compiler.
  626. The result of the compilation is a file DOWNSORT.INF, which can be
  627. VIEWed with the following command:
  628. :xmp.
  629.     VIEW  DOWNSORT
  630. :exmp.
  631. :note.
  632. :ul compact.
  633. :li.The names "DOWNSORT", "IPF" and "INF" are used here as sample,
  634. actually the filename depends on the specification in the DOWNSORT
  635. configuration file, the extensions are the IPFC defaults.
  636. :rev refid=rev51.
  637. :li.If VIEW gives 'garbled' columns and hardly readable block-titles,
  638. then it is most likely that you did not install (or removed) the
  639. standard fonts that are delivered with OS/2.
  640. Start the 'control panel utility', select 'installation', 'add fonts'.
  641. Specify in the 'from'-field C:\OS2\DLL (see HELP of control panel).
  642. Now choose at least 1 non-proportional font.
  643. :erev refid=rev51.
  644. :eul.
  645. :eol.
  646. .* --------------------------
  647. :h2 id=hcfg.Configuration file
  648. :p.Almost all processing options may be specified in an optional
  649. configuration file, which can be specified with a commandline parameter.
  650. The configuration file is a somewhat more convenient way to
  651. specify processing parameters, and allows even more customisation.
  652. It is a good place for the more static parameters of your environment,
  653. commandline parameters are nice to create quickly 'another' list
  654. or a different format (for example wrapped or truncated descriptions).
  655. The parameters are only mentioned here for completeness,
  656. see :hdref refid=acfg. for a documented specification sample
  657. of a configuration file.
  658. .* -----------
  659. :h3.Parameters with global scope
  660. :p.The parameters below influence the execution of DOWNSORT,
  661. or have impact on every list (if it is applicable for that list).
  662. :ul compact.
  663. :li.File Specification of the MAXIMUS CBCS file 'AREA.DAT'.
  664. :li.List title with BLOCK-characters.
  665. :li.Font for the BLOCK title.
  666. :li.Pre-titles, Sub-titles and Bottom-lines in 'text' format
  667. :li.Descriptive text of orphans and files without a description
  668. in the input FILES.BBS files.
  669. :li.Maximum number of entries in NEW-list and BBS-list.
  670. :eul.
  671. .* -----------
  672. :h3.Parameters with local scope
  673. :p.The parameters below are sub-parameters of the xxxFileList keyword.
  674. :ul compact.
  675. :li.Up to 10 privileges for NEW-, GBL-, ALL- and IPF-list (each
  676. resulting in a separate list).
  677. :li.Alternate output filename (in stead of the default DOWNSORT).
  678. :li.Directory for the :hp2.output:ehp2. FILES.BBS-lists
  679. :li.Maximum number of file entries in NEW-list and BBS-list
  680. :li.File-entry sort sequence (filename or date).
  681. :li.Wrap or Truncate long file descriptions.
  682. :li.Title Font selection.
  683. :li.Suppression of privilege indications in NEW-, ALL-, IPF- and
  684. GBL-lists.
  685. :rev refid=rev51.
  686. :li.Include textfile in NEW-, ALL-, IPF- and GBL-lists, and in FILES.bbs.
  687. :erev refid=rev51.
  688. :eul.
  689. :p.A sample configuration file (DOWNSORT.CFG) is provided.
  690. A listing of this file is imbedded as :hdref refid=acfg..
  691. It contains a complete specification with comments on:
  692. :ul compact.
  693. :li.which options are available
  694. :li.how to specify the options
  695. :eul.
  696. :p.Read and modify the file as you like.
  697. Copy the sample file to a save place before you start modifying the
  698. original DOWNSORT.CFG!
  699. :p.NOTE: The parameters from DOWNSORT.CFG are processed first, then
  700. commandline parameters, which may complete and will (partly) override
  701. those in the configuration file.
  702. .* -------------------------
  703. :h2.Usability hints
  704. .*
  705. :h3.Specification of AREA.DAT
  706. :p.A MAXIMUS file 'AREA.DAT' is absolutely required by DOWNSORT.
  707. :rev refid=rev51.
  708. It is however not necessary to run MAXIMUS itself,
  709. the AREA.DAT file is created with SILT(P) from the MAXIMUS package.
  710. You can use this utility without the other MAXIMUS stuff.
  711. In fact I do that myself (NOT running a MAXIMUS board)!
  712. :erev refid=rev51.
  713. If you run DOWNSORT in directory without AREA.DAT, then you
  714. have several options:
  715. :ul compact.
  716. :li.You might add a COPY statement in your batch-file to copy AREA.DAT
  717. with every run into your DOWNSORT directory.
  718. :li.You might use the "@path" parameter to specify
  719. the complete filespec of AREA.DAT ("drive&colon.\directory\file.ext").
  720. :li.You may use DOWNSORT.CFG for the filespec of AREA.DAT.
  721. :eul.
  722. :p.The latter is recommended.
  723. :p.Currently DOWNSORT does not allow to select the contents of the lists
  724. on area-code.
  725. The :hp2.'@path':ehp2. allows you to specify a different AREA.DAT file
  726. than the one that is used by your MAXIMUS.
  727. With SILT you may build a special AREA.DAT for exclusive use by
  728. DOWNSORT, with different, less, or more directories!
  729. :p.If DOWNSORT reports a memory constraint
  730. (see also :hdref refid=perf.),
  731. you may use this technique as circumvention: leave out one or more of
  732. the file area's and rerun DOWNSORT with the alternate AREA.DAT
  733. specification.
  734. .*
  735. :h3.Location of FILES.BBS
  736. :p.For input DOWNSORT uses either the ListFile specification in
  737. AREA.DAT, or the download directory to locate the file with
  738. file-descriptions (generally known as FILES.BBS).
  739. :p.The destination of FILES.BBS-files is not by definition the same as
  740. the origin!
  741. When specified with the "FIL&colon."-parameter (or in the configuration
  742. file), the output may be located in a different directory than the
  743. original input FILES.BBS.
  744. Manual checking or post-processing by some other program may follow
  745. DOWNSORT, after which the files might be put back on the MAXIMUS
  746. specified position.
  747. .*
  748. :h3.Privilege control
  749. :p.The default file privilege to be shown is SYSOP.
  750. :p.Files without a matching filename-entry in FILES.BBS are treated as
  751. Hidden.
  752. That means that by default these files will not be listed,
  753. unless the 'H' privilege is used on the report-request specification.
  754. All files with a higher privilege than the specified (or defaulted)
  755. report-privilege will not appear in the report.
  756. .*
  757. .*
  758. :h3 id=orphan.Orphan report
  759. :p.The Orphan report will be generated only if there are any orphans
  760. detected.
  761. In that case it overwrites a possibly present old DOWNSORT.ORP file.
  762. :p.A way of suppressing Orphan-reporting is to include a "*.*"
  763. entry :hp2.at the end:ehp2. of FILES.BBS.
  764. This has two effects:
  765. :ul compact.
  766. :li.In the sense of DOWNSORT orphans do not exist anymore:
  767. there is a matching entry in FILES.BBS for every file.
  768. :li.The description of this entry will replace the hard-code text
  769. "----no-description-----".
  770. You may specify your own text in DOWNSORT.CFG.
  771. :eul.
  772. .*
  773. :h3.Duplicates
  774. :p.No test on duplicates is done, this means:
  775. :ul compact.
  776. :li.If a downloadpath is encountered more than once, the files will
  777. appear that many times in the outputlist (depending on the
  778. area-privilege!)
  779. :li.If a filename.ext is encountered more than once in different
  780. subdirectories, it will appear that many times in the outputlist.
  781. The file-privilege reflects that of the area where the file belongs to
  782. (unless overridden by a &caret.Px modifier in FILES.BBS).
  783. :eul.
  784. .*
  785. .*
  786. :rev refid=rev51.
  787. :h3.Headers, Titles and Include files
  788. :p.There are several ways to custimise the appearance of the lists for
  789. DOWNSORT.
  790. All items in the following list are optional, but the sequence in the
  791. reports is fixed and as listed:
  792. :dl tsize=12 termhi=2.
  793. :dt.Pre-Title
  794. :dd.Up to 20 lines as very first lines of your lists
  795. (sometimes called Top-title).
  796. Any text may be specified.
  797. Leading '~'-characters (tilde) will be treated as full-size required
  798. blanks, mainly to manually align (center) the text in these lines.
  799. There is no automatic centering.
  800. You may have to experiment a little.
  801. :dt.TITLE
  802. :dd.A short title (8-12 characters), that will appear as 'magnified' big
  803. BLOCK-letters.
  804. There are 4 block-fonts to choose from.
  805. Not all characters are supported and lower-case will be translated to
  806. upper-case.
  807. The '~'-character (tilde) will be treated as full-size required blank,
  808. the '`'-character (accent-grave) as half-size required blank.
  809. :p.If not specified, a default title is generated as DOWNSORTxy, where
  810. xy stands for the current version of DOWNSORT.
  811. However even this title may be suppressed by specifying TitleFont 0 in
  812. the configuration file.
  813. :dt.Include-file
  814. :dd.A text-file to be included as is.
  815. There will be no manipulation of the contents of this file.
  816. This include-file may be all you need to obtain a fully custimised list.
  817. For the IPF-list it may (and probably should) contain IPF tags.
  818. :dt.Sub-Title
  819. :dd.Up to 20 lines.
  820. These are treated like the Pre-Title lines.
  821. :dt.BottomTitle
  822. :dd.Up to 20 lines as very last lines of the lists.
  823. These follow my 'signature'.
  824. The lines follow the same treatment as Pre-Title lines.
  825. :edl.
  826. :p.The BLOCK-title and Pre-, Sub-, and Botton-titles are used for all
  827. reports identically, there is no such thing as an 'individual' title
  828. specification for each report.
  829. However the Include-file may be different for each report.
  830. :note.Exceptions:
  831. :ol.
  832. :li.None of the above does apply to the BBS-list.
  833. As it will generally be desirable to imbed (compiled) MECCA control
  834. sequences in this type of lists, this report will include dedicated top
  835. and bottom files (if available in the current default directory).
  836. These files must be called DOWNSORT.HDR (header) and DOWNSORT.TRL
  837. (trailer).
  838. :li.The ORPHAN report will not contain any sort of user-titles.
  839. :li.The FILES.bbs files will not use any of the title-specifications,
  840. but may use an Include-file.
  841. :eol.
  842. :p.:hp2.Recommendation:ehp2.&colon. File-requestors appreciate a header
  843. with a clear indication of the source of the reports.
  844. Many Bulletin Boards use FILES or ALLFILES as 'magic' name,
  845. but that is not very distinctive if you collect lists of different
  846. boards!
  847. :note.Specification details and samples can be found in DOWNSORT.CFG.
  848. :erev refid=rev51.
  849. .*
  850. .*
  851. :h3.Privileges with File Request
  852. :p.If you run a mailer like BinkleyTerm, which makes a distinction
  853. between 'unknown', 'known' and 'password-protected' users, you could
  854. generate multiple download lists with different privilege indictor,
  855. depending if you allow these categories to request different file
  856. collections a sample of this kind of environment is given in
  857. :hdref refid=sampl..
  858. :p.This is not needed for DOWNSORT.BBS, since this file has imbedded
  859. privilege control sequences for MAXIMUS users.
  860. But you should specify a sufficiently high privilege for the BBS-list to
  861. satisfy your most valuable users!
  862. .* -------------------------------
  863. :h2 id=sampl.Sample specifications and usage
  864. :p.Assume you are runnung MAXIMUS with BinkleyTerm as front end mailer.
  865. Suppose you make a distinction for file-requestors between Unknown, Known
  866. and Password-Protected (e.g. corresponding to Disgrace, Normal and
  867. Privileged MAXIMUS users).
  868. .* ------
  869. :h3.DOWNSORT specification sample
  870. :p.You should have a specification like this:
  871. :xmp scale='1.2'.
  872.   DOWNSORT bbs&colon.p new&colon.dnp all&colon.dnp 100
  873. :exmp.
  874. :p.In addition to or in place of the specifications in DOWNSORT.CFG,
  875. this specification produces the following lists:
  876. :ul.
  877. :li.Orphan report (only if there are any orphans).
  878. :li.DOWNSORT.BBS with 100 entries for MAXIMUS users of category Privil.
  879. Users with a lower privilege will actually see a shorter list
  880. if the file contains Privil entries.
  881. :li.For file requestors of the magic filename FILES a list,
  882. a list with all files
  883. (with optional titles via DOWNSORT.CFG specifications):
  884. :ul compact.
  885. :li.DOWNSORT.A&tilde.D for UNKNOWN file-requestors
  886. :li.DOWNSORT.A&tilde.N for KNOWN file-requestors
  887. :li.DOWNSORT.A&tilde.P for Password Protected file-requestors
  888. :eul.
  889. :p.Note that each list is a complete list of what is available to
  890. the user of the specific privilege class,
  891. but your system will generally contain more files than listed for
  892. UNKNOWN and KNOWN users!
  893. :li.For file requests of the magic filename NEWFILES a list
  894. of the 100 most recent additions to your system
  895. (with optional titles via DOWNSORT.CFG specifications):
  896. :ul compact.
  897. :li.DOWNSORT.N&tilde.D for UNKNOWN file-requestors
  898. :li.DOWNSORT.N&tilde.N for KNOWN file-requestors
  899. :li.DOWNSORT.N&tilde.P for Password Protected file-requestors
  900. :eul.
  901. :p.Note that each list is 100 entries long, but the contents will
  902. generally not be quite the same
  903. :rev refid=rev51.
  904. (depending on your privilege strategy).
  905. :erev refid=rev51.
  906. :eul.
  907. :p.In general: files, which the requestor is not supposed to know about
  908. due to his privilege status, will not be on his/her list!
  909. :note.The counters on top of the lists indicate what your system has
  910. available in total (including higher privileges), so a clever
  911. user/file-requester may come up with the question how that is possible:
  912. explain that he/she has to earn a higher privilege level!
  913. .* ------
  914. :h3.BinkleyTerm specification sample
  915. :p.In Binkley.Cfg you should specify for requests of FILES:
  916. :xmp scale='1.1'.
  917.   Avail        Downsort.A&tilde.d
  918.   KnownAvail   Downsort.A&tilde.n
  919.   ProtAvail    Downsort.A&tilde.p
  920. :exmp.
  921. :p.Furthermore you may need to specify different OKFILEs:
  922. .cp 5
  923. :xmp scale='1.1'.
  924.   OKFile       Download.N
  925.   KnownReqList Download.K
  926.   ProtReqList  Download.P
  927. :exmp.
  928. .cp 16
  929. :p.And in each of the appropriate filerequest authorisation files
  930. you should specify the appropriate file-spec:
  931. :fig place=inline width=page depth=1 frame=none.
  932. :cgraphic scale='1.1'.
  933. :on3270.
  934.  
  935.  ╔═══════════╦══════════════╦═══════════════╦═══════════════╗
  936.  ║       in: ║ OKFile       ║ KnownReqList  ║ ProtReqList   ║
  937.  ║           ║ (Download.N) ║ (Download.K)  ║ (Download.P)  ║
  938.  ║ for:      ║              ║               ║               ║
  939.  ╠═══════════╬══════════════╬═══════════════╬═══════════════╣
  940.  ║ .....     ║ .........    ║ ...........   ║  ........     ║
  941.  ║ @NEWFILES ║ Downsort.N&tilde.d ║ Downsort.N&tilde.n  ║  Downsort.N&tilde.p ║
  942.  ║ @FILES    ║ Downsort.A&tilde.d ║ Downsort.A&tilde.n  ║  Downsort.A&tilde.p ║
  943.  ║ .....     ║ .........    ║ ...........   ║  ........     ║
  944.  ╚═══════════╩══════════════╩═══════════════╩═══════════════╝
  945. :off3270.
  946. :ecgraphic.
  947. :efig.
  948. :p.This will result in sending of the appropriate NEW-list to every
  949. requester of the magic filename: NEWFILES.
  950. If you use the second magic filename, then the Avail-lines in
  951. Binkley.Cfg are not needed, and you might prefer this way.
  952. :p.Of course if the privilege level of all download area's is the same,
  953. this construction is not needed,
  954. but in that case it is unlikely that you have specified KnownAvail and
  955. ProtAvail!
  956. .* -----------------------------
  957. :h2.Dependencies and restrictions
  958. :ul.
  959. :li.Applies to MAXIMUS CBCS 1.00 and 1.02.
  960. :li.Requires OS/2 or DOS 3.0+.
  961. :li.To convert the IPF-list into VIEW-able format (downsort.INF), the
  962. IPF-Compiler under OS/2 is required.
  963. :li.The input FILES.BBS files are assumed to contain only filename.ext
  964. (the regular 8.3 format, no support for OS/2 1.2+ HPFS format),
  965. the remainder of the line is considered as file description.
  966. The filename should be left-aligned (start in position 1).
  967. :p.If a privilege modifier (&caret.Px) is encountered in FILES.BBS
  968. then 'x' will become the privilege of all subsequent files (it assumes
  969. &caret.Px on a SEPARATE line, the REST OF THE LINE IS IGNORED!).
  970. Heading, comments and blank lines in FILES.BBS are ignored.
  971. The modified privilege might be higher (generally the case) or lower
  972. than the area-privilege.
  973. :eul.
  974. .* -------------------------------
  975. :h2.Wishlist
  976. :p.DOWNSORT is not finished!
  977. There are a number of wishes and requirements of users and myself to
  978. include in future releases.
  979. I list them below not in any particular order, but some seem to be more
  980. important than others (but that differs from SYSOP to SYSOP).
  981. And some are more easy to implement than others, and that depends mainly
  982. on the author!
  983. :ul.
  984. :li.Follow the MAXIMUS development (changing AREA.DAT and other
  985. structures), and support several versions simultaneously.
  986. I'll try to make DOWNSORT independent of MAXIMUS-versions.
  987. I'm thinking of parsing AREA.CTL, in stead of using AREA.DAT,
  988. as suggested by Scott Dudley himself.
  989. :li.Automatic removal of 'bad' files (like .BAK-files, obsolete files,
  990. files that are not in FILES.BBS), maybe move them to a special
  991. BAD&us.FILE directory.
  992. :li.User-configurable options for:
  993. :ul compact.
  994. :li.week and month indicators
  995. :li.indicator for continuation lines in wrapped descriptions
  996. :li.font in AREA-header and Summary in ALL-list, and in FILES.BBS
  997. :eul.
  998. :li.Add &lbrk.selectable&rbrk. MECCA control in FILES.BBS, like in the
  999. BBS-list.
  1000. :li.Logging to file in stead of console, obtaining a history file
  1001. of DOWNSORT usage.
  1002. :li.File-selection with MAXIMUS CBCS key/lock parameters in addition or
  1003. in stead of privilege levels.
  1004. :li.Selection of files in reports on area, or group of area's.
  1005. :li.Support for use of 'barricaded' areas and key/lock.
  1006. :li.Selection of NEW-list on basis of oldest date or time-period.
  1007. :li.Another list: with the format of IPF-list but the contents of
  1008. NEW-list.
  1009. :rev refid=rev51.
  1010. :li.Preserve comments and formattings of FILES.BBS files when
  1011. rebuilding these files.
  1012. :erev refid=rev51.
  1013. :eul.
  1014. .* -------------------------------
  1015. :rev refid=rev.
  1016. :h2.Known Problems
  1017. :p.Although I try to prevent the cause of them, there are problem reports:
  1018. :ul.
  1019. :li.Some unidentified characters somewhere between block- and sub-title.
  1020. :eul.
  1021. :erev refid=rev51.
  1022. .* ===============================================
  1023. :h1.Packaging
  1024. :p.DOWNSORT is distributed in 2 archives:
  1025. :ul.
  1026. :li.A file "DWNSRTxy.ZIP", containing all material you need to run
  1027. DOWNSORT, including documentation, formatted for browsing or printing
  1028. (formfeed is the only printer-control).
  1029. :li.A file "DWNSRSxy.ZIP", containing all SOURCE material.
  1030. :eul.
  1031. :note.'xy' is the version indication,
  1032. for example DWNSRT&VERSION.&SUBVERS..ZIP is the version
  1033. &VERSION..&SUBVERS. (RUN-time) package.
  1034. .* -----------------
  1035. :h2.RUN-time material
  1036. :dl tsize=20 termhi=3 compact.
  1037. :dt.WHATSNEW.&VERSION.&SUBVERS.
  1038. :dd.Summary of amendments to version &VERSION..&SUBVERS. of DOWNSORT.
  1039. :dt.DOWNSORT.EXE
  1040. :dd.Execution module for DOS and OS/2 (Family Application)
  1041. :dt.DOWNSORT.DOC
  1042. :dd.Documentation (this file!).
  1043. :dt.DOWNSORT.CFG
  1044. :dd.Sample configuration file.
  1045. This file contains comment lines with extensive instructions how to
  1046. specify the parameters in the file.
  1047. :dt.DOWNSORT.HDR
  1048. :dd.Sample BBS-list header.
  1049. You may use this header, which is only imbedded in the BBS-list,
  1050. to imbed text and/or MECCA-sequences.
  1051. A good candidate for the latter would be &lbrk.onexit&rbrk.,
  1052. which translates to &caret.OFpath.
  1053. See the sample DOWNSORT.HDR file!
  1054. :dt.DOWNSORT.TRL
  1055. :dd.Sample BBS-list trailer.
  1056. :dt.DOWNSORT.BMP
  1057. :dd.Bitmap for the IPF-list, to be included by the IPF compiler.
  1058. :rev refid=rev51.
  1059. :dt.DOWNSORT.INC
  1060. :dd.Sample Include-file for the reports, referenced in DOWNSORT.CFG.
  1061. :erev refid=rev51.
  1062. :dt.HPFSDATE.EXE
  1063. :dd.Program to display all three timestamps of a file on an HPFS volume,
  1064. and optionally reset the CREATION date to LASTWRITE date
  1065. (helpful after moving or copying of files).
  1066. Start the program without options to display command syntax and help.
  1067. :dt.README.1ST
  1068. :dd.The actual contents of the package (produced with PKUNZIP -V),
  1069. added to the ZIP-file after this was created with the foregoing files
  1070. of this archive.
  1071. This gives at least some authentication!
  1072. :edl.
  1073. .* ---
  1074. :h2.Source material
  1075. :dl tsize=20 termhi=3 compact.
  1076. :dt.DOWNSORT.C
  1077. :dd.Source of mainline and global variable definitions.
  1078. :dt.DOWNCOL.C
  1079. :dd.Source of data collection functions.
  1080. :dt.DOWNFNT.C
  1081. :dd.Source of font definition and formatting function.
  1082. :dt.DOWNPAR.C
  1083. :dd.Source of parameter processing functions.
  1084. :dt.DOWNRPT1.C
  1085. :dd.Source of output report functions (except what is in DOWNRPT2.C)
  1086. :dt.DOWNRPT2.C
  1087. :dd.Source of output report functions for ALL-list and IPF-list.
  1088. :dt.DOWNSRV.C
  1089. :dd.Source of miscellaneous services functions.
  1090. :dt.DOWNSORT.H
  1091. :dd.Header file, with external definitions of global variables.
  1092. :dt.DOWNSORT.SCT
  1093. :dd.Unformatted documentation file.
  1094. This file includes formatting tags in BOOKMASTER style for printing on
  1095. whatever devices are supported (like IBM page printers).
  1096. This format is compatible and can be formatted on an IBM host system
  1097. with DCF (SCRIPT) as well.
  1098. :rev refid=rev51.
  1099. The file can also processed by the IPF-compiler (just ignore the
  1100. warnings and error-messages!).
  1101. You may have to 'repair' the file of the Toolkit version 1.1 with symbols
  1102. (APSYMBOL.APS) in the IPFC directory: e.g. '&.titde.' should be
  1103. '&.tilde.', and all symbols should end with a full-stop (.), such as
  1104. '&.box34.'.
  1105. The IBM Toolkit 1.2/1.3 is distributed without these errors.
  1106. :erev refid=rev51.
  1107. :dt.AREA&us.MAX.H
  1108. :dd.Header file with union specification of AREA.DAT for different
  1109. versions of MAXIMUS (as far as the layout of AREA.DAT is concerned).
  1110. :dt.AREA&us.100.H
  1111. :dd.Header file with :hp2.guessed:ehp2. layout of AREA.DAT for MAXIMUS
  1112. CBCS version 1.00.
  1113. :dt.AREA&us.102.H
  1114. :dd.Header file with layout of AREA.DAT of MAXIMUS CBCS
  1115. version 1.02.
  1116. :dt.DOWNSORT.DEF
  1117. :dd.LINK definition file.
  1118. :dt.DOWNSORT.MAK
  1119. :dd.MAKE file.
  1120. :dt.README.1ST
  1121. :dd.The actual contents of the package (produced with PKUNZIP -V),
  1122. added to the ZIP-file after this was created with the foregoing files
  1123. of this archive.
  1124. This gives at least some authentication!
  1125. :edl.
  1126. .* ---------------------
  1127. :h2.Availability
  1128. :p.The most recent version of DOWNSORT is always downloadable and
  1129. file-requestable from Bulletin Board "PC-Square" of the Dutch IBM
  1130. employee PC club.
  1131. Search or request DWNSRT??.* to be independent of the version and
  1132. compression method!
  1133. :p.FIDO-net address:  2&colon.512/4; phone:  31-79-424107 (USR HST-DS).
  1134. :p.DOWNSORT is distributed in area SDSMAX of the international Shareware
  1135. Distribution System.
  1136. :p.There is a fair chance you may find a recent version on one of
  1137. the other bulletin boards, listed in :hdref refid=ause..
  1138. .* ===================================================================
  1139. :h1.Internals
  1140. .* ------
  1141. :h2.Development Environment
  1142. :p.DOWNSORT has been developed with IBM C/2 compiler version 1.1, under
  1143. IBM OS/2 Extended Edition 1.3 with Program Development Toolkit version
  1144. 1.2/1.3 as COMPACT memory model.
  1145. :rev refid=rev51.
  1146. :p.DOWNSORT has been tested for MAXIMUS CBCS 1.00 and 1.02,
  1147. with the following Operating Systems:
  1148. :ul compact.
  1149. :li.IBM PC/DOS versions 4.0 and 5.0 (pre-release)
  1150. :li.IBM OS/2 versions 1.3 and 2.0 (pre-release)
  1151. :li.DOS-box of IBM OS/2 versions 1.3 and 2.0 (pre-release)
  1152. :eul.
  1153. :erev refid=rev51.
  1154. .* ---------------------------
  1155. :h2.Program Organisation
  1156. :p.The program is organised as follows:
  1157. :ul.
  1158. :li.Initialisation:
  1159. :ul compact.
  1160. :li.Read configuration file.
  1161. :li.Process commandline parameters.
  1162. :eul.
  1163. :p.The commandline parameters will override configuration file
  1164. parameters.
  1165. :li.Read AREA.DAT file to collect download pathnames (assumes AREA.DAT
  1166. is in current directory).
  1167. :rev refid=rev51.
  1168. :li.For all file-area's with a privilege not exceeding any list-request:
  1169. :erev refid=rev51.
  1170. :ul.
  1171. :li.Read subdirectory (with find-file-first/next function).
  1172. Take only Normal files: ignore directory entries, Hidden and System
  1173. files and volume labels.
  1174. Also ignore MAXIMUS-files with the following specifications: FILES.?BS,
  1175. *.BAK, DIR.?BS and SYSTEM*.?BS
  1176. :li.For all regular file-entries found in subdirectory:
  1177. :ul compact.
  1178. :li.Get filename.ext, attribute, date, time, size (timestamp will be
  1179. 'last-time-written').
  1180. :li.Get file-description from FILES.BBS file.
  1181. The path to the FILES.BBS file is (1) obtained from the "ListFile"
  1182. specification in MAXIMUS AREA.DAT file, or (2) if not specified from the
  1183. "DownLoad" specification (among the download files).
  1184. :li.Get file privilege 1) from area, 2) from FILES.BBS file.
  1185. :rev refid=rev51.
  1186. :li.When no orphan reporting is required, then drop the orphan entries.
  1187. :erev refid=rev51.
  1188. :eul.
  1189. :eul.
  1190. :li.For the ORP-list:
  1191. :p.If any orphan found, and the orphan-report is requested, create the
  1192. orphan report, with the file-entries sorted on (1) area and (2)
  1193. filename.
  1194. :li.For the BBS-list:
  1195. :ul compact.
  1196. :li.Sort the files primarily on descending file-timestamp (and secundary
  1197. on file-name and area-code).
  1198. :li.Resort the first files on filename if requested.
  1199. :li.Create output file for sorted list of filenames, -descriptions, etc.
  1200. The file is placed in the current subdirectory (which generally will be
  1201. the MAXIMUS directory) with the name DOWNSORT.BBS.
  1202. :li.Copy a headerfile (for a customised MAXIMUS bulletin).
  1203. :li.Put files in formatted outputfile (filename, area#, date, size,
  1204. description), but only if description is found in FILES.BBS.
  1205. Skip files with privilege higher than commandline (or default)
  1206. parameter.
  1207. Precede each line with a privilege-control sequence (&caret.PLx string)
  1208. so that MAXIMUS users below the specified max-priv-level do effectively
  1209. see only the files they can download.
  1210. :li.Include a trailerfile in the outputfile (for a custimised Bulletin).
  1211. :li.Report non-listed files on standard output device (which might be
  1212. re-directed to printer or disk-file).
  1213. :eul.
  1214. :li.If requested, put the above file collection (also in reverse
  1215. date-sequence) in DOWNSORT.N&tilde.p with similar contents and layout as
  1216. DOWNSORT.BBS, but without BBS-control sequences, and without including a
  1217. header and trailer file.
  1218. Produce a list for the default privilege (HIDDEN), or one for each
  1219. specified privilege.
  1220. :li.If requested, re-sort files on area and then filename, and create
  1221. DOWNSORT.A&tilde.p, containing all files (respecting the privilege
  1222. restrictions!).
  1223. Area's with zero files within the applicable privilege limit will not
  1224. be listed at all (will seem non-existing!).
  1225. Produce a list for the default privilege (SYSOP), or one for each
  1226. specified privilege.
  1227. :p.At the end of the list, an area summary report is generated.
  1228. :li.If requested, re-sort files on filename only, and create
  1229. DOWNSORT.GBL.
  1230. :li.If requested, re-sort files on area, privilege and filename, and
  1231. create for each area a FILES.BBS-type of file.
  1232. :eul.
  1233. :p.NOTE: the program firstly reads a directory for existing files
  1234. (not Hidden- or System-files, and not Subdirectory or Volumelabel),
  1235. and then reads FILES.BBS to assign a description to each file.
  1236. This means:
  1237. :ul compact.
  1238. :li.If more than 1 matching file-specification in FILES.BBS of the
  1239. involved area is found (note that wild-card specifications in FILES.BBS
  1240. are supported!), than the :hp2.first matching description:ehp2. from
  1241. FILES.BBS will appear in the lists
  1242. (new in version 4.5, was 'last' previous versions).
  1243. :li.Files for which no description is found in FILES.BBS will get
  1244. "---no description available---"
  1245. (or the replacement string you specified in DOWNSORT.CFG)
  1246. in the user reports.
  1247. :li.Files for which no matching filename in FILES.BBS is found will
  1248. be listed in the Orphan report (DOWNSORT.ORP).
  1249. :p.In special cases this might become a very large list.
  1250. For example if you collect files in a single directory for different
  1251. area's, all the files of 'the other' areas are reported as orphan.
  1252. This will happen for every area, so each file might even be reported
  1253. many times as orphan!
  1254. Since the Orphan-list is now optional (from version 5.0 on), this list
  1255. can be suppressed.
  1256. :p.Filenames of Orphans appear only in the other reports when the
  1257. FileList request explicitly specifies the Hidden privilege.
  1258. :eul.
  1259. .* -----------
  1260. :h2.Main Data Organisation
  1261. :p.Data structure for access to file information via:
  1262. :ol compact.
  1263. :li.array of file-pointers (for file-sort!)
  1264. :li.pointerchain in file-info structures
  1265. :li.file structure contains pointer to file-description
  1266. :li.file-structure contains pointer to area-information
  1267. :li.Array of area-information
  1268. :eol.
  1269. :p.The structures are shown in :figref refid=data..
  1270. :fig id=data place=inline width=page depth=1 frame=none.
  1271. :cgraphic scale='1.1'.
  1272. :on3270.
  1273.  
  1274. ╔══════╗
  1275. ║  dm  ║
  1276. ╚══════╝
  1277.     │         Array of pointers to structures with file info
  1278.     │      ╔═══════════╦════════════╦═════════════ . . . ══════╗
  1279. (1) └─────>║ *file&lbrk.0&rbrk.  ║  *file&lbrk.1&rbrk.  ║ *file&lbrk.2&rbrk.                 ║
  1280.            ╚═══════════╩════════════╩═════════════ . . . ══════╝
  1281.                  │           │            │
  1282. (2)              v           v            v
  1283. ╔══════╗     ╔══════╗     ╔══════╗     ╔══════╗
  1284. ║  ca  ║ ──> ║ next ║ ──> ║ next ║ ──> ║ next ║ ──> . . .
  1285. ╚══════╝     ╠══════╣     ╠══════╣     ╠══════╣
  1286.  (first-     ║ file-║     ║ file-║     ║ file-║
  1287.  element)    ║ info ║     ║ info ║     ║ info ║    . . .
  1288.              ║ &lbrk.0&rbrk.  ║     ║ &lbrk.1&rbrk.  ║     ║ &lbrk.2&rbrk.  ║
  1289.              ╚══════╝     ╚══════╝     ╚══════╝
  1290.                  │ │         │  │wildcards│ │
  1291.                  │ └──┐      │  └──┐      │ │
  1292.                  │    │      │ ┌──────────┘ │
  1293. (3)              v    │      v v   │ ┌──────┘
  1294.              ╔══════╗ │   ╔══════╗ │ │
  1295.              ║file- ║ │   ║file- ║ │ │(files of
  1296.              ║descr ║ │   ║descr ║ │ │ same area)   . . .
  1297.              ╚══════╝ │   ╚══════╝ │ │
  1298.                       │            │ │
  1299. (4)                   v            v v
  1300.               ╔════════════╦═════════════╦════════ . . . ══════╗
  1301. (5) ┌────────>║  area&lbrk.0&rbrk.   ║   area&lbrk.1&rbrk.   ║                     ║
  1302.     │         ╚════════════╩═════════════╩════════ . . . ══════╝
  1303.     │              array of structures of download info
  1304. ╔══════╗
  1305. ║ area ║
  1306. ╚══════╝
  1307. :off3270.
  1308. :ecgraphic.
  1309. :figcap.Schematic overview of DOWNSORT's in-storage database.
  1310. :efig.
  1311. :note.The area-array cannot be sorted itself: this would invalidate the
  1312. pointers in the file-information records!
  1313. :p.The block character image is basically a 10x7 matrix
  1314. (10 vertical and 7 horizontal 'pixels').
  1315. :rev refid=rev51.
  1316. The pixel-array takes two rows at a time, so that each character
  1317. can be represented with 5 rows of 7 horizontal 'double-pixels'.
  1318. :erev refid=rev51.
  1319. Each pixel is displayed as a solid block.
  1320. :fig place=inline width=page depth=1 frame=none.
  1321. :cgraphic scale='1.1'.
  1322. :on3270.
  1323.          1 2 3 4 5 6 7
  1324.         ╔═╦═╦═╦═╦═╦═╦═╗
  1325.         ║-║-║-║-║-║-║-║   line 1    (lower + upper)
  1326.         ╠═╬═╬═╬═╬═╬═╬═╣
  1327.         ║-║-║-║-║-║-║-║        2    (lower + upper)
  1328.         ╠═╬═╬═╬═╬═╬═╬═╣
  1329.         ║-║-║-║-║-║-║-║        3    (lower + upper)
  1330.         ╠═╬═╬═╬═╬═╬═╬═╣
  1331.         ║-║-║-║-║-║-║-║        4    (lower + upper)
  1332.         ╠═╬═╬═╬═╬═╬═╬═╣
  1333.         ║-║-║-║-║-║-║-║        5    (lower + upper)
  1334.         ╚═╩═╩═╩═╩═╩═╩═╝
  1335. :off3270.
  1336. :ecgraphic.
  1337. :efig.
  1338. :p.Each line is represented by a structure of seven 3-bit fields
  1339. Each 3-bit field represents a basic element:
  1340. :xmp scale='1.1'.
  1341.  value    char       description
  1342.    0                 (blank)
  1343.    1     &BOXBOT.           lower half
  1344.    2       &BOXTOP.         upper half
  1345.    3         &BOX.       lower+upper halves
  1346.    4       &box34.         gray pattern
  1347.    5     &BOXLEFT.           left part of upper and lower half
  1348.    6       &BOXRIGHT.         right part of upper and lower half
  1349.    7         &box14.       gray pattern
  1350.    8      &box12.          gray pattern for not-supported characters
  1351. :exmp.
  1352. :p.The pitch is variable ('proportional font': a variable number of
  1353. horizontal pixels).
  1354. Three fonts are provided with different character-image and size:
  1355. :ol compact.
  1356. :li.6x5 (three lines of max 5 characters)
  1357. :li.10x7 (five lines of max 7 characters)
  1358. :li.8x7 (four lines of max 7 characters)
  1359. :li.10x7 (reverse video image of the 8x7 font)
  1360. :eol.
  1361. :p.Not all ASCII characters are represented in the font tables!
  1362. .* -----------
  1363. :h2 id=perf.Storage and Performance
  1364. :p.As a rough estimate of the memory requirements of DOWNSORT,
  1365. use sum of the following elements:
  1366. :ul.
  1367. :li.Program: about 70KB
  1368. :li.Each area: 300 Bytes
  1369. :li.Each file: 64 Bytes for each file (excl. file descriptions)
  1370. :li.The sum of the description texts (on average 80 Bytes?)
  1371. :eul.
  1372. :p.There is a theoretical limit on the number of files that can be
  1373. processed by DOWNSORT: about 16000 files.
  1374. I suppose you'll reach other limits first, for example stack-space.
  1375. DOWNSORT has been built with a 'guess' about needed stack space.
  1376. The author would appreciate to receive a report for a better estimate.
  1377. :p.Processor performance was an issue for large file-area's before
  1378. version 4.5 of DOWNSORT in the data-collection process.
  1379. That has been partly rewritten in version 4.5 and significantly improved.
  1380. Fastest execution will always be obtained when the input FILES.BBS is
  1381. already sorted on filename.
  1382. .* --------------------------------
  1383. :appendix.
  1384. :h1 id=ahis.History of changes
  1385. :p.The paragraphs below show a brief history of changes in DOWNSORT
  1386. (most recent revisions on top of list!).
  1387. :p.DOWNSORT for MAXIMUS CBCS was developed from an OPUS equivalent
  1388. (by the same author).
  1389. Its pre-MAXIMUS history is not really important here and therefore has
  1390. been omitted.
  1391. However the name DOWNSORT has been maintained, so to prevent confusion,
  1392. the version number is inherited (the last version for OPUS was 3.1).
  1393. .*
  1394. :rev refid=rev51.
  1395. :h2.Version 5.1
  1396. :ul compact.
  1397. :li.Since the ORPhan report is optional (changed with version 5.0),
  1398. orphan entries could and now will be removed from internal storage
  1399. during the information collection phase of DOWNSORT, but
  1400. :hp2.only when no orphan-list is requested:ehp2.!
  1401. This is especially useful for the situation where a single large
  1402. directory contains the files of several area's, and whereby the file
  1403. descriptions are contained in different FILES.BBS files.
  1404. Normally this will result in reporting lots of duplicate orphans
  1405. (according to the definition of 'orphan' in DOWNSORT!).
  1406. With this change memory utilisation is lower and sorting faster.
  1407. :li.Another change of this kind: area's with a privilege exceeding
  1408. any reporting privilege are not scanned anymore.
  1409. Apart from lower memory utilisation, this might be useful for CDROM and
  1410. slow disk(ette) systems.
  1411. :li.The maximum number of Top-, Sub- and Bottom-Title lines has been
  1412. extended to 20.
  1413. :li.In addition all lists may now include a 'logo'-file with a new -I
  1414. parameter on the individual report request specification (see sample
  1415. DOWNSORT.CFG).
  1416. The file will be copied into the list without any editing or
  1417. translation.
  1418. It will be positioned directly behind the block-title and before the
  1419. subtitle (if any).
  1420. For example: you may include your BBS-logo or a picture of your system
  1421. configuration, or anything else you want to tell the file-requestors of
  1422. FILES, ALLFILES and/or NEWFILES.
  1423. The IPF-list may also include IPF tags, with artwork, etc.
  1424. It may even include other files itself!
  1425. For FILES.BBS the contents of this Include-file will immediately follow
  1426. the 'standard' header.
  1427. :li.All block-fonts have now a new special character <`> (reversed
  1428. quote), which will be 'printed' as blank (space) with :hp2.half:ehp2.
  1429. the width of a normal character.
  1430. This is useful for fine-alignment (e.g. manually centering) the
  1431. BLOCK-title.
  1432. :li.The chapter on 'titles and headers' has been rewritten to clarify
  1433. the use of all title-options, :hp2.please read it!:ehp2..
  1434. :li.In the SUMMARY of ALL- and IPF-lists the areas themselves
  1435. are not sorted anymore, but presented in sequence of AREAS.CTL
  1436. specification.
  1437. This is based on the assumption that the file area's are in some kind of
  1438. 'natural' order in AREAS.CTL (or maybe it is time to do that now!).
  1439. :li.Descriptions in FILES.BBS are now (again) aligned on column 14 of
  1440. the FILES.bbs file records.
  1441. :li.IPF-list again a little more user-friendly (linking of area's).
  1442. :li.A number of improvements have been applied to the executiontime
  1443. messages (when running in VERBOSE mode).
  1444. :eul.
  1445. :erev refid=rev51.
  1446. .*
  1447. :h2.Version 5.0
  1448. :ul compact.
  1449. :li.Improved IPF-formatting: more colorful, builtin word-wrapping of
  1450. VIEW used for file descriptions (better VIEWable under OS/2 1.3!).
  1451. It should now also compile without errors/warnings.
  1452. Compiling (with IPFC) takes significantly longer however!
  1453. :li.The IPF-list of large filearea's (>200 files) split into parts of
  1454. 200 files to prevent files being left unlisted.
  1455. :li.Top-level title in FileLists shows file-count and byte-count as
  1456. available within the privilege of the list.
  1457. Thus it indicates what is really AVAILable to the user!
  1458. Area-count omitted in lists which are not area-oriented.
  1459. :li.ORPHAN report made OPTIONAL (must be specified to get it!).
  1460. :eul.
  1461. .*
  1462. :h2.Version 4.9
  1463. :ul compact.
  1464. :li.Added a new list-format: IPF-list, similar to ALL-list, but meant to
  1465. be made a VIEWable file ('book') under OS/2 Presentation Manager.
  1466. :li.Sourcefile DOWNRPT.C splitted into 2 parts.
  1467. :li.Correction in FILES.BBS header (to prevent the "offline" msg).
  1468. :li.Now also FILES.BBS output can be kept in original sequence with the
  1469. K(eep)-option.
  1470. :li.Added the X-option: all 'written' privilege indications in the lists
  1471. can now be suppressed: the user is then not aware of any
  1472. privilege-system!
  1473. :li.Header-lines of all lists now more consistent in sequence.
  1474. :li.The 'I'- and '1'-characters in fonts 3 and 4 have been widened to 5
  1475. colums (was 3 colums, but that looked too 'narrow').
  1476. :li.The documentation has been extended with a list of Bulletin Boards,
  1477. of which the SYSOPs have reported being a regular user of DOWNSORT.
  1478. :li.Distribution has been changed: run-time and source material now in a
  1479. separate archive files (DWNSRTxy.ZIP and DWNSRSxy.ZIP).
  1480. :eul.
  1481. .*
  1482. :h2.Version 4.8
  1483. :ul compact.
  1484. :li.A 'KEEP' parameter (-K) added to allow the files to remain in
  1485. original sequence of FILES.BBS.
  1486. This option is now only valid for ALL-list (later for FIL-list too).
  1487. :li.Documentation change: for multi-line file descriptions a
  1488. continuation line must start with at least 1 blank-character,
  1489. followed by at least 1 significant (non-blank) character.
  1490. :li.Repaired bug in sort on filedate for FIL-lists.
  1491. :eul.
  1492. .*
  1493. :h2.Version 4.7
  1494. :ul compact.
  1495. :li.Sorting of files on HPFS volumes (OS/2 1.2) now takes into account
  1496. the file CREATION-date (= arrival date on your system).
  1497. Sort will take the most recent of Creation and LastWrite.
  1498. The 'old fashioned' LastWrite date (indicating the age of the file)
  1499. is displayed in the lists!
  1500. This feature is only effective under OS/2 from release 1.2 for files
  1501. on an HPFS volume.
  1502. :li.Use of DOSOPEN() from OS/2 Program Development Toolkit (allows for
  1503. better multi-session and LAN support).
  1504. :li.New font added: reverse video image of font3,
  1505. and related changes in font generation function.
  1506. :li.Added separation lines in FILES.BBS like in ALL-list.
  1507. :li.Tiny adjustment to date formatting: year 2000 and later will be
  1508. displayed as 2-digit numbers.
  1509. :eul.
  1510. .*
  1511. :h2.Version 4.6
  1512. :ul compact.
  1513. :li.Downsort will try to locate and read a configuration file allowing
  1514. even more processing options
  1515. (by default DOWNSORT.CFG in current directory).
  1516. An extensively documented sample is accompanying the DOWNSORT package.
  1517. No additional document-reading needed to run DOWNSORT for the first time.
  1518. The introduction of this feature makes some commandline parameters
  1519. superfluous, and allows more flexibility, like:
  1520. :ul compact.
  1521. :li.In addition to a number of global parameters,
  1522. each list has a 'local' set of formatting parameters for
  1523. sort-sequence, description wrapping, title-font, maximum number of
  1524. entries (NEW and BBS only).
  1525. The individual parameters can be set only via the configuration file.
  1526. :li.Specification of AREA.DAT and "title" not possible anymore on the
  1527. commandline, now only by means of the configuration file.
  1528. :li.A "@filespec" commandline option now used for specification of
  1529. the configuration file (makes the use of different files for different
  1530. purposes possible).
  1531. :eul.
  1532. :li.Multiline FILES.BBS input now supported.
  1533. Automatic conversion to long descriptions provided when requesting
  1534. FILES.BBS (re-)creation.
  1535. :li.Multiple GBL-lists can now be generated, like ALL-list.
  1536. Difference between ALL-list and GBL-list is only the grouping by
  1537. in area's, and the area-summary in ALL-list.
  1538. SYSOP may decide which of both serves the users best.
  1539. :li.User supplied pre-title, sub-title and bottomlines now supported
  1540. for NEW, ALL and GBL-lists,
  1541. as well as replacement text for '---no-description---' and
  1542. '---orphan---' in the lists.
  1543. :li.BLOCK-title font user-configurable and BLOCK-title can now be
  1544. suppressed.
  1545. :li.NEW-list and GBL-list have an additional header-line telling the
  1546. maximum file-privilege shown in the list.
  1547. :li.FILES.BBS has now column header, and a user-specified privilege limit
  1548. applies also to FILES.BBS
  1549. (orphans now only listed when explicitly requested with 'Hidden').
  1550. :li.The HELP-screen is now only shown :hp2.on request:ehp2. via a
  1551. commandline parameter (-H).
  1552. :eul.
  1553. .*
  1554. :h2.Version 4.5
  1555. :ul compact.
  1556. :li.FILES.BBS-files may be (re-)created now in DOWNSORT-style
  1557. (like the ALL-list format).
  1558. Read carefully the information about this option in the
  1559. report description!
  1560. :li.An ORPHAN-report is now produced always (not requestable) and
  1561. independent from other reports.
  1562. It replaces the reporting of ORPHANs to the console formerly done during
  1563. creation of the BBS-list.
  1564. :li.The BBS-list is no longer produced by default, it should be
  1565. specifically requested now, like the other user-reports.
  1566. :li.The BBS-list and NEW-list may now be sorted on filename,
  1567. and for that reason also these lists will have an age indicator 'week'
  1568. or 'month' old appended to the file date.
  1569. :li.'Verbose' and 'Quiet' operating mode are possible now: many more or
  1570. much less console messages with one of these specifications,
  1571. than regularly.
  1572. :li.Performance improvement obtained in data collection process,
  1573. significant especially for large area's.
  1574. :li.Filename matching process changed (one of the reasons of the
  1575. performance improvement): :hp2.first:ehp2. matching filename is
  1576. used now to assign the file description to a file.
  1577. :li.Title block-font is now proportional, and two fonts are added.
  1578. The fonts are not (yet) user selectable.
  1579. :li.A path to the appropriate AREA.DAT file may be specified now
  1580. (@path).
  1581. :li.The possible specification of "ListFile" in AREA.CTL is recognised
  1582. now (in stead of assuming FILES.BBS in the download directory).
  1583. :li.Added display of an "I-am-busy" indicator during the
  1584. collection of file information (processing FILES.BBS input).
  1585. :li.Added display of date and time of report-creation to bottom of
  1586. file lists (except FILES.BBS files), and also the total elapsed time on
  1587. console.
  1588. :li.Fixed bug in detection of newest file, which in rare situations
  1589. pointed to a file outside the privilege group.
  1590. :li.Added HELP-screen when no commandline parameters specified, or on
  1591. request (-H commandline parameter).
  1592. :li.'Signature' at bottom of lists extended.
  1593. :li.Documentation extended for all the new features, and a little
  1594. re-organised.
  1595. :li.Internal data structure for file-information changed for improved
  1596. storage utilisation.
  1597. :li.Time has come to split source into several modules!
  1598. :eul.
  1599. .*
  1600. :h2.Version 4.4
  1601. :ul compact.
  1602. :li.Support for different versions of MAXIMUS (1.00 and 1.02), with
  1603. respect to the layout of AREA.DAT.
  1604. :li.Multi-line file descriptions now supported, with word-wrap and an
  1605. option to select or deselect it in different reports.
  1606. :li.Extended AREA-header in ALL-list with area-privilege indicator,
  1607. and latest acquisition (date and file-spec).
  1608. :li.Added indicators '*' and '+' in GBL- and ALL-list for files of
  1609. 1-week and 1-month old respectively.
  1610. :li.Added "--- no description available ---" in lists if filename found
  1611. in FILES.BBS, but there is no description there.
  1612. :li.Added "****** ORPHAN *******" in description field of
  1613. files, for which there is no entry in FILES.BBS.
  1614. :li.Files that are reported to the console as "not listed", now also
  1615. display the area, (pseudo-) privilege and file description (or "no
  1616. description" or "ORPHAN" whatever is applicable).
  1617. :li.Changed default file-report privilege into SYSOP.
  1618. Hidden files will not show up, unless specifically asked for!
  1619. :li.More characters supported as BLOCK-characters (including '/' and
  1620. '\').
  1621. :li.Fixed a bug in routines for NEW-, BBS- and ALL-list, which
  1622. occasionally gave addressing violations (in the OS/2 version).
  1623. :li.A related change in the data structure of the file-information for
  1624. the file-description decreases storage utilisation, taking advantage
  1625. of wild-card specifications in FILES.BBS as supported by MAXIMUS.
  1626. :li.Fast growing wishlist added to documentation!
  1627. :eul.
  1628. .*
  1629. :h2.Version 4.3
  1630. :ul compact.
  1631. :li.GBL-list added: a complete list of the download base (back from 4.0
  1632. and earlier versions of DOWNSORT, where it was called ALL!).
  1633. :li.An AREA-summary report has been added to ALL-list.
  1634. :li.ALL-list now also displays total bytecount per area.
  1635. :li.A default title will be generated if none is specified.
  1636. :li.Routine for generating block routines replaced.
  1637. :li.Block character '/' (slash) replaced by '|' (vertical bar).
  1638. :eul.
  1639. .*
  1640. :h2.Version 4.2
  1641. :ul compact.
  1642. :li.DOWNSORT.BBS and DOWNSORT.NEW are not produced any longer by
  1643. default.
  1644. Each list-type must now be specifically requested by BBS, NEW, or
  1645. ALL on the commandline.
  1646. :li.Multiple ALL-lists and NEW-lists may be produced now.
  1647. Each of these may contain files of different (maximum) privilege level.
  1648. This makes it possible to have overviews for different classes of users.
  1649. :li.A report title for the ALL- and NEW-lists may be specified, and will
  1650. be printed in BLOCK-characters.
  1651. :li.A remark has been added to the top of DOWNSORT.BBS that the list may
  1652. seem shorter due to privilege restrictions.
  1653. :li.Longer file-description where there is space for it (ALL-list).
  1654. :li.Requirement of filenames in FILES.BBS to be UPPERcase dropped.
  1655. :li.Documentation extended and re-formatted.
  1656. :li.Some more re-shuffling of code (for maintenance purposes)!
  1657. :eul.
  1658. .*
  1659. :h2.Version 4.1
  1660. :ul compact.
  1661. :li.Bug-repairs in filename-matching routine.
  1662. :li.SORT changed for DOWNSORT.ALL: sort on name within area, gives an
  1663. alphabetical list per download area.
  1664. :li.File descriptions now left aligned, regardless its position in
  1665. FILES.BBS.
  1666. :li.Group-title (of file-area) copied from AREA.DAT in ALL.
  1667. :li.Files excluded from the lists are now more generally: FILES.?BS,
  1668. DIR.?BS  and  SYSTEM*.?BS
  1669. :li.Parameter added to hide files above a maximum privilege-level.
  1670. :li.Files without description are treated as Hidden, these will appear
  1671. in the lists when 'H' is selected (note: by default!).
  1672. :li.Improved sort organisation (pointers in stead of structures).
  1673. :li.Minor changes and additions to lists (beautification?).
  1674. :li.Some minor internal re-organisation.
  1675. :eul.
  1676. .*
  1677. :h2.Version 4.0
  1678. :ul compact.
  1679. :li.New setup for MAXIMUS CBCS Bulletin Board environment, this version
  1680. does not support OPUS' file system!
  1681. :li.Support of non-numeric (two-character) area code.
  1682. :li.Support of wild-characters in the file-name part of the records in
  1683. the description-files (FILES.BBS), as allowed by MAXIMUS.
  1684. :li.The file DOWNSORT.NEW (not ".TXT") will be produced always (error in
  1685. previous documentation), but now without TXT2COM formatting characters,
  1686. since there is not (yet) a suitable alternative under OS/2.
  1687. :eul.
  1688. .* =============================
  1689. :h1 id=ause.Who use DOWNSORT?
  1690. :p.PC-Square may be considered as the home-base of DOWNSORT.
  1691. The most recent version is always available there
  1692. (file-requests between 07:00 and 24:00 local time).
  1693. :xmp keep=off.
  1694. :hp2.
  1695. PC-Square           Marcel Stikkelman     Zoetermeer, Netherlands
  1696. 2&colon.512/4                                   31-79-424107
  1697. :p.The following SYSOPs have reported using DOWNSORT on their
  1698. respective boards:
  1699.  
  1700. OS/2-MANiA          Emmanuel Sandorfi     Paris, France
  1701. 2&colon.320/5                                   33-1-64090640
  1702.  
  1703. :rev refid=rev51.
  1704. OS/2 TASK BBS       Rene Carlsen          Skagen, Denmark
  1705. 2&colon.231/85                                  45-98451070
  1706.  
  1707. Paradigmus Maximus  John Taylor           London, UK
  1708. 2&colon.253/68                                  44-81-566-5393
  1709. :erev refid=rev51.
  1710.  
  1711. Fernwood            Emitt Dove            Branford CT, USA
  1712. 1&colon.141/209                                 1-203-483-0348
  1713.  
  1714. :rev refid=rev51.
  1715. Bell's Theorem      Jeremy Buhler         Houston TX, USA
  1716. 1&colon.106/7674                                1-713-777-0633
  1717. :erev refid=rev51.
  1718.  
  1719. OS/2 Shareware      Pete Norloff          Fairfax VA, USA
  1720. 1&colon.109/347                                 1-703-385-4325
  1721.  
  1722. Singing Bear        John Tarbox           Wilmington DE, USA
  1723. 1&colon.150/130                                 1-302-984-2238
  1724.  
  1725. La Jungle BBS       Stephane Seguin       Quebec, Canada
  1726. 1&colon.163/116                                 1-819-595-4917
  1727.  
  1728. :rev refid=rev51.
  1729. 3M Australia        Graham Stair          Sydney, NSW Australia
  1730. 3&colon.711/409                                 61-2-498-9184
  1731. :erev refid=rev51.
  1732. :ehp2.
  1733. :exmp.
  1734. :p.I have received reports from others.
  1735. Too many for this list, which is just meant to point to a system
  1736. in your neighbourhood(?).
  1737. You may either logon to one of these boards, or perform a file-request
  1738. of 'FILES' or 'ALLFILES' to get an impression of DOWNSORT's
  1739. capabilities.
  1740. .* =============================
  1741. :h1 id=acfg.Sample Configuration File
  1742. :xmp keep=off.
  1743. .im \c2\downsort\downsort.cfg
  1744. :exmp.
  1745. :euserdoc.
  1746.