home *** CD-ROM | disk | FTP | other *** search
/ CP/M / CPM_CDROM.iso / cpm / utils / arc-lbr / lsweep13.doc < prev    next >
Text File  |  1994-07-13  |  9KB  |  203 lines
  1. *****************************************************************
  2.                        Documentation for:
  3.  
  4.                            LSWEEP.COM
  5.                               v1.1
  6.  
  7.                    A Program For Manipulating
  8.                       Novosielski Libraries
  9.                         (i.e. LBR Files)
  10.  
  11.                            Joe Vogler
  12.                          January 8, 1984
  13.                     (Written in BDS C v1.50)
  14. *****************************************************************
  15.    This program is in the public domain and may be used or 
  16. modified freely.  It may not be sold.  Significant portions of 
  17. this program were borrowed from:
  18.  
  19.      Gary P. Novosielski     (LDIR.C, LTYPE.C)
  20.      Dick Greenlaw           (USQ.C)
  21.      Bob Mathias             (TYPESQ.C)
  22.  
  23. No portion of this program be incorporated into another program 
  24. if that program is to be sold for profit.
  25. *****************************************************************
  26.  
  27. INTRODUCTION
  28. ============
  29.  
  30.    LSWEEP stands for Library SWEEPer.  To the user, it looks a 
  31. lot like SWEEP, DISK76, NSWEEP, or WASH.  That is because I wrote 
  32. it to be that way. Instead of file names, the user scans a list 
  33. of member names.  When the user enters a command, it operates on 
  34. the 'current' selection.  That is the last member name displayed 
  35. by LSWEEP.  Available commands are VIEW, EXTRACT, HELP, and EXIT.  
  36.    VIEW is analagous to TYPE.  If the file is squeezed, the file 
  37. is unsqueezed before it is displayed.
  38.    EXTRACT is a combination of the '-e' command of Lu (Library 
  39. Utility) and UNSqueeze.  If the member is squeezed, EXTRACT will 
  40. create an unsqueezed file with the pre-squeeze name.
  41.    Quite honestly, if you have used the programs mentioned above, 
  42. you should feel comfortable with LSWEEP.
  43.  
  44.  
  45. HOW TO USE LSWEEP
  46. =================
  47.  
  48.    The program is run this way:
  49.  
  50.      A> lsweep <lbrname> [<lbrname> ..... <lbrname>]<cr>
  51.  
  52. Example:
  53.  
  54.      A> lsweep justone<cr>
  55.      A> lsweep onesy twosy threesy<cr>
  56.      A> lsweep b:this c:that another d:last<cr>
  57.  
  58.    You can name as many Libraries as you can fit on the command 
  59. line.  You can specify Libraries on different drives.  You must 
  60. specify at least one Library.  The program will 'process' the 
  61. Library names in the order specified.  When you are done with 
  62. one, it continues on to the next, or exits after the last one.You 
  63. can  also use wildcards.   This was not the case with v1.0.   The 
  64. wildcards are expanded by the program.   You'll get lots of  non-
  65. library names if you forget to use '.LBR' when using wildcards.
  66.    For each Library, he program builds a list of member names & 
  67. file sizes and displays one after another, as you hit the RETURN 
  68. key (or any key not set up as a command key).  There are only 
  69. three command keys:
  70.  
  71.     ? - Displays HELP menu
  72.     V - Views the 'current' member
  73.     E - Extracts the 'current' member
  74.     X - eXits the current Library and proceeds to 
  75.         the next one or quits, if there are no more.
  76.  
  77.    When viewing a file, the program pauses every 16 lines.  The 
  78. number was chosen to suit me, since I like to read in paragraphs 
  79. and paragraphs don't end on 22-line boundaries.  When the display 
  80. pauses, you can continue a line at a time by pressing the space 
  81. key.   You can advance another 16 lines by pressing any other 
  82. key, except for Control-X.  That selection will abort the View 
  83. and return you to the menu.  When you return, the current member 
  84. is the same one you just viewed.  I did this because you cannot 
  85. yet go backwards through the menu.   
  86.    Extraction can be directed to any drive.  The program asks for 
  87. a drive.  This is one of the two 'opportunities' you have to 
  88. abort the program with a Control-C.  Hit return for the default 
  89. drive.  You will have to remember which drive is the default.
  90.    Extraction ALWAYS creates an UNSQUEEZED version of the member.   
  91. Future modifications will include a COPY command which will allow 
  92. you to decide whether to unsqueeze. If the member was not 
  93. squeezed, the member is copied verbatim.
  94.    Also, the program doesn't respect files with the same names as 
  95. those it wants to create.  Again, future mods may include 
  96. verification before deleting a file.
  97.    When a file is EXTRACTED, the entire contents of the original 
  98. are sent to the external file.  I have done some testing and have 
  99. found that the files make by LSWEEP have the same CRC's as the 
  100. source members  (See LIMITATIONS).
  101.  
  102. LIMITATIONS
  103. ===========
  104.  
  105.    Thats just about it.  Now for the things that the program 
  106. should do but does not yet.
  107.  
  108.    1. The files created are not verified (e.g. using CRC).  I 
  109. have done a bit of testing and found that the CRC's of the files 
  110. LSWEEP creates are the same as the originals.  The soundness of 
  111. your system will most probably determine how reliable LSWEEP is 
  112. in this respect.
  113.    2.  No tagging of members.
  114.    3.  No going backwards through the menu.  If you overshoot, 
  115. you have to continue around the ring.  
  116.    4.  You cannot direct file output to other user areas.  This 
  117. is probably the next thing I will do.
  118.    5.  It would be nice if the program allowed you to 'log' onto 
  119. another Library, instead of proceeding through the command line 
  120. arguments.  This is my second todo.
  121.    6.  LSWEEP offers absolutely no way to modify the Library 
  122. itself.  This 'feature' was given conciously.  I see no reason to 
  123. attempt to rewrite LU.
  124.    7.  The unsqueeze routines are written in C.  If the new 
  125. assembler unsqueeze code had been used, the program would run 
  126. much faster and the code size would be reduced several Kbytes.
  127.  
  128.  
  129.    I make no apologies for the above 'deficiencies'.  The program 
  130. is much better than nothing.  If you reeeealy want something 
  131. else, modify it.  You might let me know what your intentions are;  
  132. no sense in two people working on the same improvement.
  133.  
  134.  
  135. HOW TO MODIFY
  136. =============
  137.  
  138.    The source for LSWEEP10 includes these files:
  139.  
  140.                   LSWP1.C   LSWP1I.C   LSWP1H.C
  141.  
  142. The main file, LSWP1, has #include directives to pull in the 
  143. others.  After modifying, recompile only the file that you 
  144. changed.  If you modify the header file LSWP1H.C, then you need 
  145. to recompile LSWP1.C and LSWP1H.C.  To recompile the programs:
  146.  
  147.         A> CC lswp1
  148.         A> CC lswp1i
  149.  
  150.    The link step is done this way:
  151.  
  152.                 A> CLINK lswp1 lswp1i [-n]
  153.  
  154. The '-n' option causes the COM file to exit without a warm boot.
  155.  
  156.  
  157. BACKGROUND
  158. ==========
  159.  
  160.    This program was inspired by the recent infusion of new Public 
  161. Domain programs which function like WASH and SWEEP.  I use LBR 
  162. files extensively.  Every time I used SWEEP, or its look-alikes, 
  163. I would imagine that I had a program that would work the same way 
  164. on Libraries.
  165.    It is somewhat inconvenient to deal with Libraries.  Consider 
  166. just how much trouble it is to extract a Library member that is 
  167. squeezed.  First, the member must be extracted with LU.  Then, it 
  168. must be unsqueezed.  Now, there are three versions of the member 
  169. on your system:  the Library member, a squeezed (external) file 
  170. and an ASCII file.  What a pain!
  171.    Since I had modified the original C language version of LDIR 
  172. (1), I felt comfortable enough to do it myself.  The first step 
  173. was to modify the C language version of LTYPE so that it created 
  174. a disk file instead of dumping the text to the screen.  I almost 
  175. stopped there.  It looked pretty nice having a program that would 
  176. EXTRACT a squeezed Library member and UNsqueeze it at the same 
  177. time.  After some thought, I came back to the basic problem:  my 
  178. new program was another batch program.  If anything went wrong, I 
  179. would have to run the program again.
  180.    So the reasonable thing to do was to combine LDIR and LTYPE to 
  181. form a program that would:
  182.  
  183.      1. Build a list of members for the user.
  184.      2. Use the entries in the list as pointers to members.
  185.      3. Type squeezed and unsqueezed files on the screen.
  186.      4. Extract those members, unsqueezing if necessary.
  187.  
  188.    The main function is a slightly modified version of the LDIR 
  189. main.  The real changes are in DIRLIST.  Fortunately, READDIR was 
  190. already setup to create a memory image of the Library's 
  191. directory.  It was only necessary to change some of the call 
  192. argument names to correspond to LDIR and to keep track of what 
  193. the user had asked the program to do.  QCAT and ACAT were 
  194. modified to allow directing output to disk or screen.  The SWITCH 
  195. done for each character is probable slowing down the program, but 
  196. I doubt that the effect is severe.
  197.  
  198.  
  199. NOTES
  200. -----
  201. (1) - See CATLBR.LBR on Rio Lobo RCP/M, Kingwood, TX  
  202. (713)358-7104.
  203.