home *** CD-ROM | disk | FTP | other *** search
/ Simtel MSDOS 1995 October / Simtel-MSDOS-Oct1995-CD2.iso / starter / nusq110.doc < prev    next >
Text File  |  1986-08-31  |  20KB  |  490 lines

  1.  
  2.  
  3.           NUSQ - File unsqueeze utility
  4.  
  5.           Documentation for CP/M-86 and MS-DOS
  6.      versions 1.11 (CP/M-86), 1.10 & 1.10D (MS-DOS)
  7.          Cliff Sharp   October 21, 1984
  8.  
  9.                DOCUMENTATION TOPICS
  10.  
  11.     OVERVIEW            IN CASE OF TROUBLE
  12.     COMMAND MODE            PROGRAM MESSAGES
  13.     INTERACTIVE MODE        ANNOUNCEMENT
  14.     INSTALLATION             HISTORY
  15.  
  16.  
  17.  
  18.                 OVERVIEW
  19.  
  20.      NUSQ  is  a  utility for expanding squeezed files    to  their
  21. original uncompressed state.   Two separate versions of NUSQ  are
  22. available,  one  for  CP/M-86  and one for the    MS-DOS    operating
  23. system.
  24.  
  25.      NUSQ has two operating modes.  In the command mode, a single
  26. instruction to NUSQ is passed from the command line which invokes
  27. NUSQ.  The command mode requires less effort to use when you have
  28. only  one file to unsqueeze,  or when the names of the files  you
  29. wish  to unsqueeze can all be specified by one    "wildcard"  name.
  30. However,  when    you  have more than one file to unsqueeze  and    a
  31. "wildcard" won't do the job right,  or when the files you want to
  32. unsqueeze are on more than one disk,  the interactive mode allows
  33. you to specify only those files which you want processed, without
  34. reloading the program every time.   In the interactive mode, NUSQ
  35. executes one command, then waits for another.
  36.  
  37.      MS-DOS versions of NUSQ including and subsequent to 1.10 can
  38. use date and time information encoded in files squeezed with NSQ.
  39. This  means  that  a file squeezed with NSQ, 'modemed' to another
  40. location, and unsqueezed with NUSQ  (version  1.10D  or  greater)
  41. will  retain  the date and time of ORIGIN instead of DESTINATION.
  42. NSQ encodes this information at the END of the squeezed file,  so
  43. such files retain compatibility with earlier unsqueeze programs.
  44.  
  45.      See the installation section of this document for details on
  46. how  to  implement this feature in NUSQ.  Any files squeezed with
  47. NSQ (versions 2.01 or higher) will have the  necessary  date  and
  48. time information encoded in them.
  49.  
  50.  
  51.               COMMAND MODE
  52.  
  53.      To unsqueeze only one file, the command mode invocation
  54.  
  55.             A>nusq nerts.aqm
  56.  
  57. will unsqueeze the file NERTS.AQM.  You don't need to specify the
  58. name of the output file (in fact, you can't); the name was stored
  59. within    the file at the time it was squeezed,  and that name will
  60. be  used  to  create  the new file.   (If you  want  to  name  it
  61. differently after you have unsqueezed it,  use the REName command
  62. when NUSQ is finished.)
  63.  
  64.      You  can  unsqueeze all squeezed files on a single  disk  by
  65. issuing the command
  66.  
  67.               A>nusq *.?q?
  68.  
  69. Theoretically at least,  all file squeezers create an output file
  70. whose name is the same as that of the original file,  except that
  71. the  filename extension field is modified by changing the  middle
  72. letter to a "Q".  (If a file has no filetype, a 'QQQ' is appended
  73. for  the file type for the encoded file.   When a file    has  been
  74. renamed  after    being  squeezed,  this    might not  be  the  case;
  75. hopefully,  the  person who renamed it remembered the "Q".)   The
  76. "wildcard" file specification shown above tells NUSQ to unsqueeze
  77. any  file it finds (on the default disk) which has a "Q"  in  the
  78. filename  extension;  that  should  get NUSQ to  unsqueeze  every
  79. squeezed  file on the disk.   NUSQ will display the name of  each
  80. file it finds, and the name of the output file it produces, as it
  81. proceeds:
  82.  
  83.           NERTS.AQM -> NERTS.ASM
  84.           ORGPLOTZ.DQC -> ORGPLOTZ.DOC
  85.  
  86.      Because  NUSQ checks the first two bytes of each input  file
  87. for a valid Squeeze Signature (0FF76 hex), it is possible to say:
  88.  
  89.                 nusq *.*
  90.  
  91. and  get the same results as with "nusq *.?q?".   It  is  faster,
  92. however,  to use the *.?q? method, as that will preclude a lot of
  93. unnecessary file openings.
  94.  
  95.     NUSQ  will also accept more than one filename on the  command
  96. line:
  97.  
  98.           A>nusq nerts.aqm orgplotz.dqc frop.cq
  99.  
  100.      To  use a different disk for output than for input,  end the
  101. command line with just the drive designation. Example:
  102.  
  103.               A>nusq giggle.tqt b:
  104.  
  105. will  write the output file (ostensibly GIGGLE.TXT) on drive  B:.
  106. You will find that NUSQ is very forgiving, as:
  107.  
  108.               A>nusq b: giggle.tqt
  109.  
  110. will accomplish the same thing.  (Note the space between 'b:' and
  111. 'giggle'!)
  112.  
  113.  
  114.  
  115.              INTERACTIVE MODE
  116.  
  117.      Let's  suppose now that you have a large number of  squeezed
  118. files on your disk,  and you only want to unsqueeze some of them.
  119. Unless    you  can specify only those files by using  a  "wildcard"
  120. name,  you'll  probably  find it easier to achieve your  goal  by
  121. using  the interactive mode of NUSQ.   Another instance where  it
  122. would  be easier to use interactive mode is one where  the  files
  123. you wish to unsqueeze are on more than one disk, in more than one
  124. drive.    The command
  125.  
  126.                  A>nusq
  127.  
  128. displays the startup message, then prompts for command input with
  129. an asterisk ("*").
  130.  
  131. NUSQ  Version x.xx
  132. Dave Rand, Paul Homchick and Cliff Sharp  xx/xx/xx
  133. Use: NUSQ afn [afn afn ...] [destination drive:]
  134. *_
  135.  
  136. (The underline shows the cursor position; my name appears only in
  137. the  MS-DOS  version.)     At the asterisk,  you    type  a  filename
  138. ("wildcards"  are allowed here,  too).     NUSQ will unsqueeze  the
  139. file,  then  print  the asterisk prompt again and wait    for  more
  140. commands.   When  you're finished and want to exit NUSQ,  a blank
  141. line or ^C will return you to the operating system.
  142.  
  143.      As  distributed,  NUSQ  won't write over  an  existing  file
  144. without  the user confirming the operation.   Something very like
  145. the following will happen:
  146.  
  147.       A>nusq foo.bqr
  148.  
  149.       nusq: FOO.BQR -> FOO.BAR already exists,
  150.         Overwrite <Y>es, <N>o? overwriting...
  151.  
  152. In this case the user answered "Y" at the question mark, and NUSQ
  153. went  ahead  with the operation.   If "N" is  the  response,  the
  154. unsqueeze  operation is aborted,  and the program goes on to  the
  155. next item in the list (or exits, if the list is empty).
  156.  
  157.  
  158.  
  159.               INSTALLATION
  160.  
  161. Two user-configurable options are provided:  Confirm Before Over-
  162. write, and Select Date Option.
  163.  
  164. As  distributed,  NUSQ    v1.04 will ask    for  confirmation  before
  165. overwriting  a file,  and will use the current date and time when
  166. creating the output file.
  167.  
  168. If  you  would rather have NUSQ write over  existing  files  with
  169. wanton abandon,  without pausing and asking for confirmation, use
  170. DEBUG.COM to patch location 0103H to be 00H instead of 0FFH.   An
  171. example of this patch:
  172.  
  173.           A>debug b:nusq.com
  174.           -e103
  175.           xxxx:0103 FF.00
  176.           -w
  177.           Writing YYYY bytes
  178.           -q
  179.  
  180.           A>
  181.  
  182.  
  183. Select Date Option allows you four choices for the way the output
  184. file is dated.    As distributed, NUSQ will date the output file in
  185. the same manner as most other programs do, i.e. the date and time
  186. shown  in  directory displays will be the date and time at  which
  187. you unsqueezed the file.   You may change this option by changing
  188. the  byte  at  location  0104H (which you can  do  by  using  the
  189. instructions above and the values you will see in a moment, using
  190. the  instructions  shown  above  but  substituting  104  for  103
  191. wherever  103  appears).   Copies of NUSQ patched in this  manner
  192. will display a 'D' after the version number,  signifying that the
  193. input file date option has been enabled, i.e. "1.10D".
  194.  
  195. The available options are:
  196.  
  197.      0) Leave it to DOS
  198.      1) Output file gets the same date/time as the input file
  199.      2) If the squeezed file contains the special date/time
  200.       signature inserted by NSQ at squeeze time, use the
  201.       date/time contained in that signature: otherwise,
  202.       use the current date/time
  203.      3) If the squeezed file contains the special date/time
  204.       signature inserted by NSQ at squeeze time, use the
  205.       date/time contained in that signature: otherwise,
  206.       use the same date/time as the input file
  207.  
  208.  
  209. If you would like the unsqueezed file to retain the same date and
  210. time  shown for the input file (option 1),  patch 0104H  to  0FH. 
  211. For option 2,  patch 0104H to 0F0H;  for option 3, patch 0104H to
  212. 0FFH.
  213.  
  214. Following is a table that trys to explain these options:
  215.  
  216. option   value    use current   use input file    use encoded 
  217.  
  218. 0.        00         yes             -               -
  219. 1.        0F          -             yes              -
  220. 2.        F0          -              -              yes
  221. 3.        FF          -        do this second   try this first
  222.  
  223. There  is  a reason for our distributing NUSQ with the    date/time
  224. options  disabled.   If  you have a backup utility (usually  this
  225. applies  to  a "hard" disk) that uses the file date and  time  to
  226. determine  whether  or    not a file should be  backed  up,  it  is
  227. possible  that    using the input file date could cause loss  of    a
  228. file  by  having  an 'old' date on a 'new'  file,  and    losing    a
  229. backup.  If you are unsure whether this applies to you, leave the
  230. date/time options unchanged until you can find out.
  231.  
  232.  
  233.  
  234.                IN CASE OF TROUBLE
  235.  
  236.      First,  no  matter HOW sure you are that you're doing things
  237. correctly,  try another method of using NUSQ.    If you tried com-
  238. mand mode without luck,  try the interactive mode; if you were in
  239. the interactive mode when it bombed, try command mode.    Make sure
  240. you try at least one command that is just like one shown in  this
  241. document  (but,  of course,  use the name of your file instead of
  242. NERTS or ORGPLOTZ) before you conclude that things are awry.
  243.  
  244.      Occasionally,  for one reason or another,    it's possible  to
  245. get a bad copy of a program or file; transmission errors and disk
  246. errors    have  been  known to cause many problems.   (If  you  can
  247. successfully unsqueeze at least one squeezed file,  you  probably
  248. have  a good copy of the program;  if so,  your copy of the  file
  249. you're  trying to unsqueeze may be the culprit.)  The best way to
  250. tell  if  this is the case is to use a utility like CRCK  on  the
  251. original copy of the offending file/program, and on your copy; if
  252. the numbers you get don't match,  you most likely have a bad copy
  253. of the file/program you checked and should obtain another copy of
  254. it.  (Check the new copy, too, when you get it.)
  255.  
  256.      This  may sound silly,  but do you have the correct  version
  257. for your operating system?  If you try to run the CP/M-86 version
  258. under  MS-DOS,    strange things may happen;  same for  the  MS-DOS
  259. version under CP/M-86.    Also, try using TYPE to actually type the
  260. executable  file  on  your screen;  you'll most  likely  see  the
  261. author's  name.   (See the history later in this document to  see
  262. who wrote what.)
  263.  
  264.      If all that checks out,  the logical next step is to compare
  265. notes  with someone locally to see if anyone else is experiencing
  266. problems.  The system operator ("sysop") of the system from which
  267. you obtained the software can usually be of help if you tell  him
  268. which  version    you're using (CP/M-86 or MS-DOS) and the name  of
  269. the file you're trying unsuccessfully to unsqueeze.  Alternative-
  270. ly,  you  can  leave  a message addressed to  "ALL"  on  a  local
  271. bulletin  board;  usually  some helpful person will jump in  with
  272. suggestions.   Remember, there are no silly questions, only silly
  273. mistakes.
  274.  
  275.      If you've tried all this,  and you're still sure you have    a
  276. problem,  then it's last-resort time.  Contact the author of your
  277. version of the program.   His name,  and a way to contact him, is
  278. in the very beginning of the NUSQ.COM file; TYPE NUSQ.COM and you
  279. should see it.     (If that doesn't work,  use DDT,  SID or DEBUG.)
  280. This  is  by far the slowest method of    resolving  problems,  and
  281. people    who contact program authors with problems caused by oper-
  282. ator error are usually looked upon unfavorably,  so do this  only
  283. if  all  else fails.   Be sure to include the name of the  system
  284. where  you  got your copy of the program,  the name of    the  file
  285. you're trying to unsqueeze and the place where you got the  file,
  286. and  a description of what went wrong.     It might also be nice to
  287. know the names of any people who have tried to help you with your
  288. problem so far.
  289.  
  290.  
  291.  
  292.             PROGRAM MESSAGES
  293.  
  294. Output drive = x:
  295.  
  296.      You  selected a disk drive different from the one containing
  297. the original file for the output file to be created on.
  298.  
  299.  
  300. No file(s) found.
  301.  
  302.      No  files meeting the filename specification you  gave  were
  303. found on the disk you indicated they would be on.  Try reentering
  304. the file specification,  or check to make sure you are specifying
  305. the correct drive and/or disk.     Also,    if you are using wildcard
  306. characters ('*',  '?') in the specification,  make sure the usage
  307. is correct.
  308.  
  309.  
  310. Out of memory. Use more specific filenames.
  311.  
  312.      NUSQ  is operating in a small workspace,  and  the  wildcard
  313. file  specification  you gave has found a large number of  files. 
  314. The  storage  for  all these filenames has  eaten  away  so  much
  315. workspace that NUSQ has no room left in which to unsqueeze any of
  316. the files.   Give NUSQ a filename specification which will find a
  317. smaller  number of files,  so that more unsqueezing workspace  is
  318. available.   (Users  with 96K or more memory will probably  never
  319. see this message.)
  320.  
  321.  
  322. xxxxxxxx.xxx is not a squeezed file.
  323.  
  324.      Squeezed  files  are marked with a  particular  "signature": 
  325. (FF76), NUSQ did not find this signature. Either the beginning of
  326. this file has been damaged,  somebody is being cute and is trying
  327. to invent new "standards", or this file is really not a  squeezed
  328. file.
  329.  
  330.  
  331. xxxxxxxx.xxx already exists,
  332.       Overwrite <Y>es, <N>o?
  333.  
  334.      A    file already exists which has the same name as that given
  335. in  the  squeezed  file for creating  the  output  file.   A  'Y'
  336. response  will cause NUSQ to overwrite the existing file;  a  'N'
  337. answer    will cause NUSQ not to unsqueeze this file.   If you want
  338. to unsqueeze this file without destroying the old, existing file,
  339. rename the existing file before running NUSQ again.
  340.      This  message  will  not  appear if  NUSQ    was  modified  to
  341. overwrite with wanton abandon (see DEBUG instructions preceding).
  342.  
  343.  
  344. Cannot create output file. Aborting.
  345.  
  346.      Either  this disk has so many files on it that there  is  no
  347. room  left  for  a  new directory  entry,  or  (with  MS-DOS  2.x
  348. versions) a subdirectory exists with the same name that NUSQ must
  349. use for the output file.  In any event, you will probably need to
  350. use  a different disk for the output file.   (See  the    preceding
  351. instructions.)
  352.  
  353.  
  354. File has illegal decode size. Aborting.
  355.  
  356.      Something    is  wrong with the input file;    either it is  not
  357. really a squeezed file,  or it has been modified or  damaged,  or
  358. (less  likely) the squeezer which created it did something wrong. 
  359. This file cannot be unsqueezed; try a new copy.
  360.  
  361.  
  362. Close failed...
  363.  
  364.      NUSQ  was unable to close the output file.   This is a  VERY
  365. unlikely  error,  and may mean either that your copy of  NUSQ  is
  366. damaged  or the copy of the operating system currently in  memory
  367. has  been corrupted somehow.   Try booting from a different disk,
  368. or try another copy of NUSQ.  If these fail, contact the author.
  369.  
  370.  
  371. ERROR - Checksums don't match in file xxxxxxxx.xxx
  372.  
  373.      Something is wrong with the input file;  either it has  been
  374. modified or damaged,  or (less likely) the squeezer which created
  375. it  did something wrong.   This file cannot be unsqueezed;  try a
  376. new copy.
  377.  
  378.  
  379. Disk full. Aborting and deleting output file.
  380.  
  381.      The  disk    on  which the output file is  being  written  has
  382. become full; there is no more disk space to contain the remainder
  383. of the file.  Create the output file on a different disk.
  384.  
  385.  
  386. Premature EOF on file... aborted.
  387.  
  388.      NUSQ has not found the special end-of-file (EOF) mark  which
  389. is present in every squeezed file.  Most likely, the last part of
  390. this file is missing.  This file cannot be unsqueezed.
  391.  
  392.  
  393.  
  394.               ANNOUNCEMENT
  395.  
  396.      A look at the signon message in interactive mode will reveal
  397. that NUSQ is the result of committee action.   Said committee was
  398. unable to agree on whether the source code should be  distributed
  399. as  public  domain  code;   consequently,   source  code  is  not
  400. available.
  401.  
  402.  
  403.  
  404.                  HISTORY
  405.  
  406.  
  407.      NUSQ is a file unsqueezer utility written entirely in assem-
  408. bly  language.     The  first file squeezer and unsqueezer  in  the
  409. public domain were written by Richard Greenlaw, in the C program-
  410. ming language.     A Z80 assembly language version was done by Gail
  411. Zacharias  at MIT in the Spring of 1983.   In late '83 Dave  Rand
  412. wrote  an  8080  version,  which went through  several    versions,
  413. culminating  in USQ120.COM.   Paul Homchick assumed the  task  of
  414. converting  Dave's  efforts  to 8086/8088 assembly  language  for
  415. execution  under CP/M-86 in early 1984,  and I    converted  Paul's
  416. version to run under MS-DOS a bit later.
  417.  
  418.  
  419.               CP/M VERSIONS
  420.  
  421.     1.08    January  28,  1984.   First released version
  422.         uploaded to Compuserve.
  423.  
  424.     1.09c    March  24,  1984.   Carriage Return on empty
  425.         line exits program.   Optimized  tree-walker
  426.         adapted  from    MS-DOS    version resulting in
  427.         15%  speed  increase.
  428.  
  429.     1.10    June  22,  1984.   Prior tree-walker was not
  430.         as optimized as we thought.  Further optimi-
  431.         zation borrowed from MS-DOS version, result-
  432.         ing in another 25% increase in speed.
  433.  
  434.     1.11    October 15, 1984.  Version 1.10 introduced a
  435.         bug  that  would  cause   a  'Premature EOF'
  436.         message  to  be  displayed  if  a legitimate
  437.         squeezed  file  used  every byte in the last
  438.         sector.  Now fixed.
  439.  
  440.  
  441.              MS-DOS VERSIONS
  442.  
  443.     1.00M    March 21, 1984.  Original version uploaded to
  444.         Compuserve.  Had  serious bug that  sometimes
  445.         resulted in short files with no warning.
  446.  
  447.     1.01M    March  31,  1984.   Carriage return on    empty
  448.         line at Command prompt ("*"),  now returns to
  449.         DOS  instead of giving another    prompt    line.
  450.         Short File BUG still in this version!
  451.  
  452.     1.02M    April 12,  1984. Fixed Random Block Write DOS
  453.         calls.    Files now unsqueeze to exact  length,
  454.         instead  of  128-byte multiples as  in    prior
  455.         versions.   Buffer  flush code fixed to elim-
  456.         inate short file bug.
  457.  
  458.     1.03 and 1.03D     June 22,  1984.  Decode routines re-
  459.         written  for a 30-percent increase in  speed.
  460.         Version 1.03D uses date and time of the input
  461.         file when creating output file; 1.03 does not
  462.         do so.    This date feature can be user config-
  463.         ured  by changing a byte at offset +4 in  the
  464.         .com  file.   See 'Installation,' above,  for
  465.         details.   Versions prior to this one  always
  466.         appended   a  1A  hex  to  the    end  of   the
  467.         unsqueezed  file.   This CP/M anachronism has
  468.         been removed in this version.
  469.  
  470.     1.04 and 1.04D     September 1, 1984.  Filename parsing
  471.         routine  changed to use MS-DOS "parse"    func-
  472.         tion call.  Prompt "No directory space" which
  473.         used  to appear when a file  create  function
  474.         failed    changed to read "Cannot create output
  475.         file",  because  MS-DOS 2.xx and  later  will
  476.         reject    the create request if a directory  by
  477.         the same name exists.
  478.  
  479.     1.10 and 1.10D     October  21,    1984.    "Bug"  fixed;
  480.         squeezed  files  which    were  100%   utilized
  481.         (i.e.,every last byte had  significant data),
  482.         and  which  were a multiple of 128 in length,
  483.         would  give a "Premature EOF"  error.    Added
  484.         date/time  handling  for  NSQ-created  files. 
  485.         Also  changed  input file handling to  handle
  486.         file lengths more accurately.
  487.  
  488. CP/M and CP/M-86 are trademarks of Digital Research, Inc.
  489. MS (as in MS-DOS) is a trademark of Microsoft, Inc.
  490.