;
                                 FSPLIT.COM                                   

             Size (recs) CRC   Version    Author/Latest Issue      Disk
               4k (32)   C17A  1.0        Gene Pizzetta 1/91       Z3COM7

  1- Usage  2- Date Stamping  3- Errors  4- Config  5- Notes  6- Examples     


   FSPLIT is a ZCPR3 utility that splits a file into  several pieces by record
count,  by line count,  or at a marker character within the file.   Text files
will not be split in the middle of a line,  but  object (binary) files will be
split exactly on record boundaries.   Under ZDDOS and ZSDOS create date stamps
are transferred to the new files.
:1

    Syntax   FSPLIT {dir:}infile {dir:}{outfile} {{/}options}

   A source filename is required.   If no  destination filename is given,  the
generated files will have the same name as the source file.   The filetypes of
the destination files will begin with  001 and increment from there (002, 003,
etc.).   If no  DIR or DU is given,  the current drive/user is assumed.  File-
names beginning with a slash must be preceded by a DU specification.
 Options - 1/4 

   If no outfile or destination directory is  given,  the options must be pre-
ceded by a slash.

    nnn   Output file size in records or lines (in decimal).  As 
          distributed, the default is 256, which is 32 kilobytes 
          in records, or around 16 kilobytes in lines.

     R    Splits file by record (sector) count.  Unless the O 
          option is given, the resulting files will be at least 
          one record longer than the size given, because once the 
          maximum file size is reached, FSPLIT will look for a 
          line feed before making the split.  (As distributed, 
          this is the default.)

     K    File size is in kilobytes.  This is not an alternate 
          method, but merely multiplies the file size by 8.  It's 
          intended to make command line entry of the file size a 
          little easier.  If this option is given, the R option 
          is also set automatically.
 Options - 2/4 
 
     L    Splits file by line count.  Lines are counted by 
          looking for line feeds, including line feeds with their 
          high bit set that are sometimes found in WordStar 
          document files.

     M    Splits the file when a ^P marker tag is found.  Markers 
          can be placed in the file with a text editor and then 
          FSPLIT used to divide the file at the marked locations. 
          The combination is faster than allowing the editor 
          itself to divide the file.

     T    Text file.  This option allows use of the L and M 
          options.  The file is split only at the end of a line 
          (see R, above) and the CP/M end-of-file character is 
          observed.  (As distributed, this is the default.)

     O    Object (binary) file.  This option also sets the R 
          option automatically and causes files to be split 
          exactly on a record boundary.  The CP/M end-of-file 
          character (^Z) is ignored.
 Options - 3/4 

     Q    Toggles current quiet mode setting.  Quiet mode is set 
          by the ZCPR3 quiet flag or by a configuration option.  
          The quiet flag is given priority, if it is set.  Option 
          Q toggles the current mode.
 Options - 4/4 

   As distributed, FSPLIT defaults to options R and T.

   The output files will  usually  be  one record larger than the record count
given on the command line because the file will not be  split until the end of
the line being read when the maximum record count is reached and then at least
one ^Z must be inserted.   Files  with  long  lines  exceeding 125 characters,
however, may sometimes require two or more  records  beyond the maximum record
count.  With the K option this overrun is partially compensated for by setting
the record count at one less than the  maximum  required  for  the given kilo-
bytes.

   With the O option the file is split  at the exact end of a record and no ^Z
is inserted, so those files will always be the exact length requested.

   In most cases text files will be the  FSPLIT sources,   but occasionally it
may be desirable to split a very large binary  (object) for storage or to move
it on floppy disks to  another  machine.   In  those  cases  always  use the O
option.  The resulting files can be re-combined using CONCAT or PIP with their
O options.
:2 
 Date Stamping  

  If the original file has a create file stamp,  then the stamp will be trans-
ferred to the new files.   Unlike some other  utilities,  a blank create stamp
will not be transferred.   In that case,  if the original file has a modifica-
tion date, that modification date will become the create date of the new file.
Otherwise,  the new file's create stamp will be the current date.   Date stamp
transfer will work only under ZSDOS and ZDDOS.
:3
 Errors  

   If "//" or a null command tail is given,  FSPLIT will display a brief usage
message.   All other errors cause invocation of the error  handler,  if one is
installed.   In addition,  the program error flag will be set to standard ZCPR
3.4 error codes:  

    2, invalid directory
    8, ambiguous or missing filename
    9, bad numerical expression
   10, source file not found
   11, disk full
   12, insufficient memory
   19, invalid option
    4, any other error
:4
 Configuration 

   Any of  FSPLIT's  command  line  options,  except option K, can be made the
defaults by using ZCNFG and  the  configuration  file,  FSPLITnn.CFG.   Do not
change the name of the CFG file or ZCNFG will not be able to find it  automat-
ically.

   Configuration options are explained in detail on the ZCNFG help screens.
:5
 FSPLIT Notes 

   a. FSPLIT is based on SPLIT45.  Although  SPLIT45 is very versatile,  it is
      cumbersome to use for simple  file  splitting  and it does not recognize 
      user areas.   A command-line driven file  splitter was needed that could 
      be configured for most common uses and be quick and simple to use.   And
      it had to be a Z utility, of course.
:6
 Examples of Use - 1/2 

     a. fsplit att5ess.man /64k
          Splits ATT5ESS.MAN into multiple files of 64 kilobytes 
          each, named ATT5ESS.001, ATT5ESS.002, etc.

     b. fsplit att5ess.man b3:5ess-man 512
          Splits ATT5ESS.MAN into multiple files of about 512 
          records each in directory B3, named 5ESS-MAN.001, 5ESS- 
          MAN.002, etc.

     c. fsplit fileman.mmp a: 336ko
          Splits binary file FILEMAN.MMP into multiple files of 
          336 kilobytes each on drive A, named FILEMAN.001, 
          FILENAM,002, etc.

     d. fsplit gwtw.txt /l
          Splits GWTW.TXT into multiple files of 256 lines (the 
          default) in the current directory, named GWTW.001, 
          GWTW.002, etc.
 Examples of Use - 2/2 

     e. fsplit edit:mybook.txt chapter /m
          Splits MYBOOK.TXT in named directory EDIT each time a 
          ^P is found into multiple files in the current 
          directory, named CHAPTER.001, CHAPTER.002, etc.
          