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