home *** CD-ROM | disk | FTP | other *** search
/ ftp.wwiv.com / ftp.wwiv.com.zip / ftp.wwiv.com / pub / MISC / DEMO510.ZIP / SLPACK3.INS / SLPACK.DOC < prev    next >
Text File  |  1999-01-25  |  15KB  |  370 lines
  1.  
  2.                                   SLPACK
  3.               Searchlight Message Base Pack/Optimize Utility
  4.                         Version 4.5e, Apr, 1996
  5.                  (c) Copyright 1996 Searchlight Software
  6.  
  7.  
  8. Version/Update Log:
  9. -------------------
  10. Version 4.5e: This version is updated to allow Spinnaker users to renumber
  11. conferences without invalidating the Spinnaker high message pointers. (Both
  12. the Searchlight BBS and Spinnaker user files are updated).
  13.  
  14. Version 4.5d: We rewrote the pack and repair procedures so that they can
  15. work on any size conference. For large conferences, SLPACK uses EMS memory
  16. or a disk swap file to store its working data. If you run SLPACK on a very
  17. large conference, be sure to make the maximum amount of EMS memory available
  18. at your DOS prompt.
  19.  
  20. The pack procedure has been updated to fix a problem with crosslinked
  21. messages. In previous versions, crosslinked messages were not properly
  22. handled by SLPACK and could lead to unrepairable internal problems. The
  23. new versions of SLPACK and REPAIR deal with this problem correctly.
  24.  
  25. You should notice a performance increase with SLPACK, especially on larger
  26. conferences. We also added an easier to read display with percentages
  27. instead of raw data counts.
  28.  
  29. * NOTE * : As has always been the case, running SLPACK on a corrupt
  30. conference will result in an even more corrupt conference. To avoid this,
  31. use the /S switch when you run SLPACK unless you are sure that the
  32. conference is not corrupt (or you are prepared to restore it from a backup
  33. if there is a problem). You can use the REPAIR /C function to quickly
  34. check a conference for errors before packing it (see REPAIR.DOC for more
  35. information). Do not use SLPACK to repair conferences that are known to
  36. be corrupt; use the REPAIR program for that.
  37.  
  38.  
  39. Version 4.5: Fixed a bug in the message pack procedure which could corrupt
  40. conferences on rare occasion.  
  41.  
  42. Version 4.0, May, 1994: SLPACK is updated to include more efficient file 
  43. management procedures that were developed for Searchlight 4.0. This should 
  44. yield a significant speed improvement. There are no functional changes.  
  45.  
  46. Version 3.5, February, 1994: This version of SLPACK is updated to include 
  47. support for alias names, which allows it to maintain proper personal message 
  48. pointers when packing conferences that use alias names.  
  49.  
  50. Version 3.0, March 1993: This is a recompilation for distribution with 
  51. Searchlight 3.0. No functional changes have been made.  
  52.  
  53. Version 2.25, October, 1992: This is a minor bug fix version. Previous 
  54. versions did not correctly dispose of used memory, which could result in an 
  55. "Error 203" or "Error 204" message after some time when packing multiple 
  56. conferences with the /A option. This version works correctly.  
  57.  
  58. In order to improve screen displays, record and message numbers are updated 
  59. once per second during packing operations, rather than continuously.  
  60.  
  61.  
  62. INTRODUCTION
  63. ------------
  64. SLPACK is a message base packing and optimization utility for Searchlight 
  65. 2.15 and later message conferencess. SLPACK operates on conference header 
  66. (HDR) and/or message (MSG) files, and performs three main tasks: 
  67.  
  68. (1) Optimization -- Records in the data files are physically sorted into
  69.     sequential order, improving access times.
  70.  
  71. (2) Packing -- Unused records are purged from the data files and the files
  72.     are physically shrunk to release unused disk space back to DOS.
  73.  
  74. (3) Renumbering -- Messages can optionally be renumbered in sequential order
  75.     starting with 1, when packing the conference header files.
  76.  
  77. SLPACK is a command-line driven program; it can operate on one, several, or 
  78. all conferences at once. Command line options are shown below.
  79.  
  80.  
  81. SYNTAX
  82. ------
  83. The command line syntax for running SLPACK is as follows:
  84.  
  85.   SLPACK [Options...] [Conferences...]
  86.  
  87. "Options" can be one or more of the option switches described below, and 
  88. "Conferencess" can be one or more valid conference names. Conference names 
  89. are required unless the /A (All) switch is used. If no options or conference 
  90. names are specified, then SLPACK displays a brief summary of its options: 
  91.  
  92.   /M       Pack message (MSG) files only
  93.   /H       Pack header (HDR) files only
  94.   /R       Renumber messages on conference
  95.   /N       Skip confirmation prompt
  96.   /A       Pack all conferences
  97.   /S       Scan conferences before packing
  98.   /Fn[,m]  Free records for header [,message] files
  99.   /Pn      Pack only if 1st message >= n
  100.  
  101. Note: Before running SLPACK, please see the CAUTION section below.
  102.  
  103.  
  104. OPTIONS
  105. -------
  106. Option /M -- Pack Message Files Only
  107.  
  108. If the /M switch is given, SLPACK will pack only the message (*.MSG) files 
  109. associated with the given conferences. Otherwise, both the header and message 
  110. files are packed.
  111.  
  112. The message file is usually larger than the header file; therefore, packing 
  113. the message file only provides a good deal of optimization in a shorter 
  114. amount of time than if both files are packed. However, packing the header 
  115. file is required if you want to renumber messages.
  116.  
  117. Example: SLPACK /M GENERAL SLBBS-R
  118.  
  119.  
  120. Option /H -- Pack Header Files Only
  121.  
  122. This option causes just the header files of the specified conferences to be 
  123. packed and optimized. Message files are not affected.
  124.  
  125. Example: SLPACK /H GENERAL SLBBS-R
  126.  
  127.  
  128. Option /R -- Renumber Messages
  129.  
  130. The renumber option causes messages to be renumbered sequentially, with the 
  131. first message number equal to 1 and the last number equal to the number of 
  132. messages on the conference.
  133.  
  134. Renumbering can only occur if the header file is packed; no renumbering will 
  135. take place if the /M option is also selected.
  136.  
  137. The renumber option also causes the high message pointers contained in the 
  138. conference's member files to be updated.
  139.  
  140. Example: SLPACK /R GENERAL SLBBS-R
  141.  
  142.  
  143. Option /N -- Skip Confirmation Prompt
  144.  
  145. When /N is NOT specified, SLPACK displays a warning message before it begins 
  146. to run, and requires that you type "Y" and "Enter" to continue. If the /N 
  147. switch is specified, this confirmation prompt is skipped.
  148.  
  149. Use /N when you run SLPACK in an unattended environment (such as in a batch 
  150. file or as part of an event).
  151.  
  152. Example: SLPACK /R /N SLBBS-R
  153.  
  154.  
  155. Option /A -- Pack All Conferences
  156.  
  157. The /A switch causes SLPACK to operate on all conferences in your system, 
  158. instead of just the conferencess specified on the command line. When /A is 
  159. used, no conference names need be specified.
  160.  
  161. Example: SLPACK /R /N /A
  162.  
  163.  
  164. Option /S -- Scan Conferences Before Packing
  165.  
  166. When the /S switch is enabled, SLPACK does a repair scan (equivalent to the 
  167. F3 utility functions in the Config program) before packing each file. 
  168.  
  169. This option is recommended, especially when running SLPACK in an unattended 
  170. mode (such as when SLPACK is part of an event). Packing a conference involves 
  171. rearranging every record in the file; files which contain even one bad 
  172. pointer or corrupt record can result in the entire conference becoming 
  173. corrupt and even in SLPACK aborting. Using the /S switch assures that each 
  174. conference file is checked for consistency before it is packed.  
  175.  
  176. If you are reasonably sure that a conference is not corrupted, you can omit 
  177. the /S switch, which will speed up SLPACK.
  178.  
  179. Note that the /S switch is not a substitute for making a backup; it is 
  180. always recommended that a backup of the files to be packed be made before 
  181. running SLPACK.
  182.  
  183.  
  184. Option /Fn[,m] -- Specify Free Record Counts
  185.  
  186. The /F command, which is followed by one or two numeric parameters, 
  187. specifies the number of free records to be appended to the end of the header 
  188. and message files after packing is complete.
  189.  
  190. By default, SLPACK removes all free records from these files when it packs 
  191. them; if /F is specified, then SLPACK appends the requested number of free 
  192. records to the end of the files. Preallocated free records help reduce file 
  193. fragmentation and increase speed when saving new messages to the file.
  194.  
  195. In the header file, 1 free record equals 1 message. In the message file, 1 
  196. free record equals approximately 250 characters of text if compression is 
  197. not used, or about 350 characters if compression is turned on.
  198.  
  199. Note that free record parameters have no effect unless the respective file 
  200. is actually packed.
  201.  
  202. Example: SLPACK /F30,100 SLBBS-R     (30 free header & 100 free message recs)
  203.          SLPACK /F40 /H SLBBS-R      (40 free header records)
  204.          SLPACK /F0,200 /M SLBBS-R   (200 free message records)
  205.  
  206.  
  207. Option /Pn -- Check 1st Message Before Packing
  208.  
  209. If the /P option is used, followed by a numeric parameter, then SLPACK only 
  210. packs conferences where the first message on the conference is greater than 
  211. or equal to the parameter given. For example, if /P100 is specified on the 
  212. command line, then only conferences where the first message on the 
  213. conference is equal to or greater than 100 are packed.  
  214.  
  215. Used in conjunction with the /R option, /P allows you to monitor conferences 
  216. which have high turnover volumes and renumber these conferences only when 
  217. the oldest message number reaches a certain level. For example, suppose you 
  218. have a conference which can contain a maximum of 1000 messages, has auto-
  219. purge enabled, and you prefer that the highest message number does not 
  220. exceed 1500. To accomplish this automatically, you could execute the 
  221. following command on a regular basis: 
  222.  
  223.   SLPACK /R /P500 SLBBS-R
  224.  
  225. The value of "500" is chosen for the /P parameter because 500 plus the 
  226. conference maximum messages (1000) equals the message number preference of 
  227. 1500. It should be noted that if messages are deleted from the conference 
  228. (other than the earliest messages) or if purge protection is enabled for any 
  229. message, then the high message number may exceed 1500 before the lowest 
  230. message number exceeds 500 and the renumber operation takes place.
  231.  
  232.  
  233. MESSAGES
  234. --------
  235. SLPACK will display the following progress messages as it runs:
  236.  
  237. Packing Conference: NAME
  238. Packing/Renumbering Conference: NAME
  239.  
  240.   The "Packing" or "Packing/Renumbering" message tells you which conference 
  241.   is currently being packed or renumbered.  
  242.  
  243. Performing Safety Scan...
  244.  
  245.   If the /S switch is used, this message appears while SLPACK is performing
  246.   the initial repair scan of the file before packing it.
  247.  
  248. Header File: Reading, Sorting, Done.
  249.  Rebuilding Indexes:
  250.  Rebuilding Threads:
  251. Rebuilding Free List:
  252.  
  253.   These messages follow the progress of the header file repacking, if that
  254.   option has been selected. 
  255.  
  256. Expanding to nnn Free Records...
  257.  
  258.   If the /F option is used, this message appears to report that the file
  259.   is being expanded.
  260.  
  261. Updating Member Records...
  262.  
  263.   This message appears during a renumber (/R) function while the member
  264.   file is being updated.
  265.  
  266. Msg File: Reading, Sorting, Done.
  267. Rebuilding Free List:
  268. Expanding to nnn Free Records...
  269.  
  270.   These messages follow the progress of the message file packing process.
  271.   The "Expanding" message appears only if a free record count for the 
  272.   message file has been specified with /F.
  273.  
  274. Skipped (1st message number = nnn)
  275.  
  276.   This message indicates that a particular conference is not being packed, 
  277.   because the /P parameter has been used and the first message on the 
  278.   conference is less than the target value.
  279.  
  280. Insufficient Memory Available (nnn bytes needed)
  281.  
  282.   Not enough memory is available to pack this conference. See memory 
  283.   requirements, below.
  284.  
  285. Cannot Open Conference:
  286.  
  287.   Indicates that the conference cannot be opened. Check the conference name 
  288.   and its data files path.  
  289.  
  290.  
  291. CAUTIONS
  292. --------
  293. SLPACK rewrites and rearranges the entire message and header files of the 
  294. conferencess it packs. Because of the way in which it operates, SLPACK is 
  295. extremely sensitive to power failures, corrupt files, bad disk sectors, and 
  296. other such problems which may occur during its operation. In order to 
  297. prevent data loss, we stronly urge you to follow these precautions: 
  298.  
  299. (1) BACK-UP ALL CONFERENCE FILES BEFORE PACKING THEM. If an error occurs 
  300.     during SLPACK's operation, it should be assumed that the conference 
  301.     which was open at the time of the error is corrupted, and needs to be 
  302.     restored from the backup copy.  
  303.  
  304. (2) Do not disturb SLPACK once it begins to run. Any attempt to abort SLPACK 
  305.     will result in a corrupted conference. The same is true if SLPACK should 
  306.     be interrupted by a system failure such as a reboot, power failure, bad 
  307.     disk sector, etc.  
  308.  
  309. (3) In multinode systems, no other nodes should be active while SLPACK is 
  310.     running. Either shut your other nodes down manually or, if SLPACK runs 
  311.     as an event, make sure the other nodes are idle while it runs.
  312.  
  313. (4) SLPACK will fail if it tries to pack a conference which contains corrupted
  314.     data files and the /S command line switch is not specified. Should 
  315.     this occur, try to repair the conference via the SETUP program repair 
  316.     functions. If this fails, then restore the conference from a backup file, 
  317.     and pack it again, specifying the /S switch on the SLPACK command line.
  318.  
  319.  
  320. EXIT CODES
  321. ----------
  322. SLPACK will return one of three exit codes (errorlevels) when it completes:
  323.  
  324. Errorlevel 0 -- Indicates that no errors occured and all requested 
  325.   operations were carried out successfully.
  326.  
  327. Errorlevel 1 -- Indicates that SLPACK has done nothing, for one of the 
  328.   following reasons:
  329.  
  330.    A. No command line parameters were specified.
  331.    B. SLPACK could not open the CONFIG.SL2 file. Be sure that CONFIG.SL2
  332.       is either in the current directory, or pointed to by SET SLBBS=.
  333.    C. You answered "N" to the confirmation prompt.
  334.  
  335. Errorlevel 2 -- Indicates that one or more operations failed, because of 
  336.   the following reasons:
  337.  
  338.   A. Can't open conference: a conference name given on the command line was
  339.      incorrect, or the conference files could not be located and opened.
  340.   B. Not enough RAM for requested operation. See RAM note below.
  341.  
  342. Note that Errorlevel 2 errors do not cause SLPACK to terminate immediately. 
  343. It will continue to run and process as many conferencess as possible.
  344.  
  345.  
  346. RAM REQUIREMENTS
  347. ----------------
  348. SLPACK requires a significant amount of memory to pack large message bases. 
  349. If insufficient memory is available to pack a particular conference, SLPACK 
  350. will skip that conference and display an error message. It will also exit with 
  351. an error level of 2.
  352.  
  353. Here is how you can compute the memory required to pack a particular 
  354. conference:
  355.  
  356.   (1) Take the DOS file size of the header (*.HDR) file, subtract 8332,
  357.       and divide by 256. If you are using the renumber (/R) option, multiply
  358.       this result by 6. Otherwise, multiply it by 2.
  359.  
  360.   (2) Take the DOS file size of the message (*.MSG) file, subtract 140,
  361.       and divide by 128.
  362.  
  363.   (3) Take THE LARGER OF the two numbers above and add 67,000. This is the
  364.       approximate amount of free DOS memory that needs to be available 
  365.       before you can run SLPACK on this conference.
  366.  
  367.  
  368. ------
  369.  
  370.