;
                                 CONCAT.COM                                   

             Size (recs) CRC   Version    Author/Latest Issue      Disk
               5k (38)   7F7E  1.0        Gene Pizzetta 4/90       Z3COM3

  1- Syntax  2- Options  3- Usage  4- Error Codes  5- Notes                   



   CONCAT concatenates  two or  more  source  files into  a  destination file,
similar to PIP.   Unlike PIP, however, CONCAT accepts both named directory and
drive/user specifications,  which allows elaborate  concatenations  with input
files pulled from various drives and user areas.   For ZCPR3 only.
:1

  Syntax   CONCAT {dir:}outfile={dir:}infile {{dir:}infile {...}} {/options}

   Any file without a DU or DIR spec is assumed to be on the current du:.  

:2
 Options - 1/3 

   A - Append mode.   Appends source files to  end  of target file, which must 
       exist.   This  mode bypasses  some  of  CONCAT's safety  features  (see 
       below).
  
   D - Insert date and time.   The current system date and time is inserted at
       the head of the new output file, or, in append mode, at the  end of the 
       existing file before any files are appended.  This option is incompati-
       ble with the O option.

   O - Object file mode (CONCAT ignores  ^Z characters).   The default is text 
       file mode, checking  for ^Z  (the CP/M end-of-file character).   Object 
       file mode is provided because some  hard-disk backup programs can split
       large files across two or more floppy disks.  This option is incompati-
       ble with the D option.
 Options - 2/3 

   Q - Toggle quiet mode.   Normally CONCAT prints the name of the output file 
       on the screen, and then the name of each source file as it is read.  If
       a configuration byte  at 111h is  set to  a non-zero value, CONCAT will 
       default to quiet operation, printing only error messages.  The Q option
       toggles operation to the non-default  mode.  Regardless of the state of
       the configuration byte,  CONCAT defaults to  quiet  mode  if  the ZCPR3 
       quiet flag is set.   In that case the  Q option will likewise toggle to 
       the non-default (verbose) mode.  

   S - Disk space checking.   Before any files are  opened,  CONCAT checks the
       amount of free space on  the target  disk and then  checks the sizes of 
       the source files to determine if there is  room to complete the concat-
       enation or append.   If there is  not  sufficient disk space,  an error 
       message is  printed and  the  operation is  cancelled.   File sizes are 
       measured in records,  which  are converted to  kilobytes  after all the 
       input files' sizes are added together.   Also,  another record is added 
       to the total file size calculation  if the  D  option is  chosen,  even 
       though that option could add only a  maximum of 60 bytes to the result-
       ing output file.   In addition,  disk space is determined in kilobytes, 
       based on the disk's allocation block size.  
 Options - 3/3 

       Because of these limitations,  it is possible for  CONCAT to  be fooled 
       into thinking that there is not enough disk space for the concatenation
       (or, especially, append) even though adequate free space exists.  More-
       over, space checking adds  a second or more to  CONCAT's  running time, 
       depending on the number of source  files  involved  and on  whether the 
       various source drives are already logged in.   For these reasons, a new 
       option allows  bypassing disk space  checking for those impatient souls 
       with more guts than brains.   A  configuration byte at  119h determines 
       whether CONCAT will check  disk space by default before doing anything.
       A non-zero value turns this feature off.  The S option will then toggle
       space checking back on.
:3
 Usage - 1/2 

   CONCAT requires an output file and at least one source file.   Actually, it 
can be used as  a simple file-copy utility,  but that's not its purpose.   The 
same filename may be given  repeatedly in the source file list.  An equal sign 
separates the output  file from the source files.   Commas or spaces, or both,
separate multiple source files.

   While the equal sign is required, it may be separated from the filenames by
one or more spaces.  The same applies to commas, if they are used; i.e, 

     concat newfile.txt=file1.txt,file2.txt,file3.txt,file4,txt
works the same as
     concat newfile.txt = file1.txt, file2.txt ,file3.txt , file4.txt
which works the same as
     concat newfile.txt = file1.txt file2.txt file3.txt, file4.txt

   A filename cannot begin with  a slash unless it  is preceded by a DU or DIR 
specification; otherwise, CONCAT will think it has found an option list.
 Usage - 2/2 

   If another file has the same name as the output file, it will be renamed to
filetype BAK.   CONCAT initially creates the  output file  with  a filetype of 
$$$.   After the copy is successfully completed,  any existing  BAK is erased,
the new BAK file created, and the output file renamed to the correct filetype.

   An invalid option (anything other than "O") will be ignored.

   CONCAT is re-entrant for use  with the GO command,  although  that  type of 
operation has not been extensively tested.
 APPEND Mode 

   In Append mode (option A) CONCAT bypasses several safety features,  so  use
it with caution.  For instance, no temporary file or BAK file is created.  The
target (output) file must already exist, but it can be zero-length.  On error,
the output file is closed after appending  any text that  was  read before the
error occurred.  The output file is not erased.

   It's  a good idea to make sure you  have sufficient disk space before using
Append because your original source file will be irrevocably changed if CONCAT
runs out of space before it is finished.

   Do not attempt to Append  a file to itself.   You're not likely to be happy
with the results.  Use concatenation mode instead.

   If you would like to  be  able to Append without using the A option, set up 
an alias as follows:

   APPEND   CONCAT $* /A
 Date String - 1/2 

   The time and date string is  inserted  only  once  for  each  invocation of 
CONCAT.   If concatenation is  used,  the date appears at the beginning of the
newly created  file.   If the  append option  is  selected,  the  date appears 
between the original (target) file and  the  first  appended file.   In  other
words,  if several files  are appended in  a single operation,  only the first
file is preceded by the date string.

   This option is  provided primarily for those  who  want to  append to a log
file on a regular basis, but still keep track of the time period to which each
section of the file pertains.

   The strings sent prior to and subsequent to the date and time string may be
configured.  In the distributed version they are:

   PREFIX:  <CR><LF>"--- [ "
   SUFFIX:  " ] ---"<CR><LF><CR><LF>

Thus the date will appear as:   --- [ 3/08/90  13:46 ] ---
 Date String - 2/2 

   In the first sector of the COM file are two  31-byte  buffers where the two
strings may  be re-configured.   The strings must end with  a null byte.   The
buffers are preceded by the ASCII flags "PREFIX>" and "SUFFIX>".

   For instance,  you might want to insert control characters that would cause
your printer to print the date and time in boldface. 
:4
 ERROR Codes 

   If an error occurs, such as a source file not found,  the incomplete output
file is erased, the ZCPR3 error flag is  set  and an error handler is invoked,
if one is running.  The error flag values are set as follows:

           8   ambiguous or missing output or source filename
          10   source or target file not found or not given
          11   disk or directory full (write error)
           4   all other errors

   For safety reasons,  invalid or incompatible options  are considered errors
(options D and O  are incompatible).   Using  the D option without  a resident
clock also yields an error.   Error messages  are  output  without  regard for 
quiet mode.
:5
 CONCAT Notes - 1/2 

   a. Version 1.0 updates (4/24/90):

      - S option toggles disk space checking.
      - An error sets the error flag and invokes the error handler,  if one is 
        running.  
      - Normally the console is checked for a character every time a sector of
        an input file is read.   If the character is a ^C, then CONCAT cancels
        the operation, just as if  an  error occurred,  erasing the incomplete
        output file.   ^C has no effect in Append mode, however.   A file that
        is being appended to is irrevocably changed  as soon  as a single byte 
        is appended to it.  Rather than leave such a file in an unknown condi-
        tion, CONCAT ignores any ^C's and continues appending until the job is
        finished.
      - Name by which CONCAT was invoked is  displayed by the  usage  message.
        Also, the current state of the two toggle options (Q, S) is displayed.
 CONCAT Notes - 2/3 

   b. Version 0.8 updates (3/8/90):
      - Added D (date) option.   Date string prefix and suffix  may be config-
        ured.  Minor bug fixed which caused temporary file not to be erased if
        the first input file was  not found.   Now  senses  size  of  TPA  and
        dynamically sets the size of the output buffer up to a maximum of 32k.
        Invalid options are no longer ignored, but now cause an error.

   c. Version 0.7 updates (12/17/89):
      - Added A (append) option, which bypasses several of CONCAT's safety
        features.  Also, a few more optimizations.

   d. Version 0.6 updates (12/3/89):
      - minor changes for setting error flag.
      - corrects serious error in detecting top of memory.

   e. Version 0.5 updates (11/25/89):
      - adds quiet option and error flag support.
      - fixes parser bug that allowed a null output filename.
      - now closes output file on error before erasing it.
 CONCAT Notes - 3/3 

   f. Version 0.4 updates (11/12/89):
      - adds large output buffer.  
      - corrects error in parsing filespec in current user.
      - commas no longer required in command line syntax.

   g. Version 0.3 updates (9/19/89):
      - First preliminary release.
