home *** CD-ROM | disk | FTP | other *** search
/ Simtel MSDOS - Coast to Coast / simteldosarchivecoasttocoast.iso / textutil / breakup.doc < prev    next >
Text File  |  1994-03-07  |  5KB  |  101 lines
  1. 23-Apr-86 19:32:57-PST,5277;000000000001
  2. Date: Wed, 23 Apr 86 20:04:12 EST
  3. From: Edward_Vielmetti%UMich-MTS.Mailnet@MIT-MULTICS.ARPA
  4. To: info-ibmpc@USC-ISIB.ARPA
  5. Subject: Breakup.doc
  6.  
  7.  
  8.                          Documentation for BREAKUP
  9.                              December, 1983
  10.                               Charles Roth
  11.  
  12.  
  13.       BREAKUP is a utility for "breaking up" large files on MSDOS systems.  It
  14.  is intended primarily as a companion utility for The FinalWord editor, but it
  15.  may have other uses as well.  BREAKUP was written in C by Charles Roth, and
  16.  is in the public domain.
  17.  
  18.       Many text editors for microcomputers can only deal with files of a
  19.  certain maximum size.  We know, by Murphy's Law, that some files will
  20.  always be larger than any given size.  Thus, there is a need to be able
  21.  to break up large files in a convenient way.  Also, when moving a collection
  22.  of files from one machine to another, it is sometimes easier to concatenate
  23.  all of the files together, ship them as one file, and then break them up
  24.  again.
  25.  
  26.       BREAKUP uses Unix-ish command arguments to allow the user to break up
  27.  a file in a variety of ways.  Each "command" is actually a pair of
  28.  arguments that specify the next place to break the file.  The user can tell
  29.  BREAKUP to break after so many bytes, or after so many lines, or when a
  30.  particular string is encountered.  The general syntax looks like:
  31.  
  32.  BREAKUP  File.Ext  -C1 A1  -C2 A2  -C3 A3   etc....
  33.  
  34.  where "file.ext" is the name of the file to be broken, and each "-Cn An" pair
  35.  specifies a breaking point (as described below).  The pieces of the broken-up
  36.  file are put in the files File.000, File.001, and so on.  Note that there is
  37.  usually one more file than the number of breaking points specified.
  38.  
  39.       The command specifiers for the "-Cn An" pairs are:
  40.  
  41.  -B  nnnn     Break after nnnn Bytes, where nnnn is a decimal number
  42.  -L  nnnn     Break after nnnn Lines, where nnnn is a decimal number
  43.  -S  string   Break after the next occurrence of "string"
  44.  -LB nnnn     Break at the first end-of-line after nnnn bytes
  45.  -LS string   Break at the first end-of-line after next occurrence of "string"
  46.  -R           Repeat the last command specifier indefinitely
  47.  
  48.  
  49.       EXAMPLES:
  50.  
  51.       BREAKUP  File.Ext  -b 1000  -b 1000
  52.  breaks "file.ext" into three pieces.  File.000 would contain the first 1000
  53.  bytes, File.001 would contain the second 1000 bytes, and File.002 would
  54.  contain everything else that was in File.Ext.
  55.  
  56.       BREAKUP  File.Ext -l 1000 -r
  57.  would chop File.Ext after every 1000 lines.  (The last piece might be
  58.  smaller than 1000 lines, of course.)
  59.  
  60.       BREAKUP  File.Ext -l 200  -s Mom  -s "Apple Pie"
  61.  breaks File.Ext at 3 points: at the (end of the) 200th line; at the next
  62.  occurrence of the string "Mom" in the text; and at the first occurrence of
  63.  the string "Apple Pie" after "Mom".  (Quotes are optional and are not part
  64.  of the string searched for.  They are required if the string contains one
  65.  or more blanks.)
  66.  
  67.       NOTES:
  68.  
  69.       1) Breaking at a point is inclusive.  That is, breaking at 200 bytes
  70.  means the first piece will contain the 200th byte.  Ditto for lines and
  71.  strings, i.e. breaking at "Mom" means the piece will end with "Mom".
  72.  
  73.       2) The size of a file in bytes has two slightly different meanings.
  74.  To programs written in C (BREAKUP, FinalWord) the end of a line is marked by
  75.  a single character.  Inside MSDOS, the end of a line is marked by the two
  76.  characters Carriage-Return and Line-Feed.  Thus, breaking off at piece at
  77.  100 bytes may result in a file that (according to DIR) is slightly larger.
  78.  
  79.       3) The -s strings may include control characters.   Of course, you
  80.  can't just type the control characters as part of the -s string; MSDOS will
  81.  try and interpret them right away.  So instead, BREAKUP uses a special
  82.  notation (borrowed from the C language) for control characters that always
  83.  begins with a "\" (backslash).  Similarly, since " and \ already mean
  84.  something special, we must have a way to represent a single " or \.
  85.  These special notations are listed below.
  86.       \ddd      is the character with the OCTAL value ddd.  Must be 3 digits.
  87.       \\        is a single backslash
  88.       \"        is a double-quote character
  89.       \n        is a newline (end-of-line character)
  90.  The last sequence is particularly useful.  Breaking at -s "\nA" would mean
  91.  "break at the next place where there is an A at the beginning of the line".
  92.  Warning: do NOT try to break about a null character, i.e. \000.  Since the
  93.  C string routines use \0 as a string terminator, BREAKUP will not understand
  94.  its use as a breakpoint.
  95.  
  96.       4) BREAKUP prints out the filenames of the pieces as they are produced.
  97.  You can redirect this output to a file, if you wish, by placing
  98.                  >filename
  99.  after the list of breakpoint specifiers.  (You do not need MSDOS 2.x to do
  100.  this.)
  101.