;
                                 CONCAT.COM                                   

             Size (recs) CRC   Version    Author/Latest Issue      Disk
               7k (50)   7999  1.1        Gene Pizzetta 2/91       Z3COM3

  1- Syntax  2- Options  3- Usage  4- Err Codes  5- Configuration  6- Notes   


   CONCAT is a ZCPR3 utility that concatenates two or more source files into a
new file,  similar to PIP,  or appends them to an existing file.   Both  named
directory  (DIR) and  drive/user  (DU)  specifications  can be used,  allowing
elaborate concatenations with input files  pulled from various drives and user
areas.  File create date stamp is transferred to the new file in concatenation
mode.
: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 the source files to the end of an existing file.
       This mode bypasses some of CONCAT's safety features  (see  below).   To
       preserve the original file create stamp, file stamp transfer (F option)
       is turned off if A is used.
  
   C - Concatenates the source files into  a new file.   [Default  for release
       version]
       
   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 (binary) file mode,  which causes  CONCAT to ignore ^Z  (end-of-
       file) characters and concatenate or append files on  record boundaries.
       Object file mode is provided because some hard-disk backup programs can
       break large files across  two or  more floppy disks.   The  FSPLIT file 
       splitting utility  also  allows  splitting  binary  files.  Option O is 
       incompatible with the D and I options, so the D and I options are auto-
       matically turned off if O is used.
 Options - 2/3 

   T - Text file mode,  which causes CONCAT to  concatenate or append files at
       the CP/M end-of-file character (^Z).   [Default for release version]

   D - Insert the system date and time into the destination file.  The current
       system date and time is  inserted at  the  head  of  the  new file when
       concatenating,  or at the end of the existing file before any files are
       added when appending.   This  option  is incompatible with the O option
       and is automatically turned off if the O option is selected.

   I - Insert a divider string into  the  destination  file before each source
       file is concatenated or  appended.   The divider string will not appear
       at the head of the first file.   This option is incompatible with the O
       option and is automatically turned off if the O option is selected.
 Options - 3/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.
       CONCAT can be configured, however,  to  default to quiet mode, printing
       only error messages.   The  Q  option  toggles to the non-default mode.
       Regardless of the configured state,  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 - Toggle disk space  checking.   Normally,  before  any  file  operations
       begin, the destination drive is  checked  to  make sure there is enough
       free space to successfully  complete the  append or  concatenation.  If
       you're impatient  and  maybe  a  little  foolhardy,  you can turn space
       checking off with this option.

   F - Toggle file date stamp transferring.  In concatenation mode CONCAT will
       transfer to the destination file the create date stamp of a source file
       with the same  name,  or if none  have the same name,  the stamp of the
       first source file.   If you  would  prefer  that  the new file have the
       current date, you can turn off stamp transferring with this option.
:3
 Usage - 1/3 

   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.

   A relaxed command line is allowed.   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
which works the same as
     concat newfile.txt = file1.txt file2.txt file3.txt, file4.txt
 Usage - 2/3 

   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.
Actually, a colon alone will work.

   In concatenation mode,  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 file is erased, the new BAK file is created,  and the output file
is renamed to the correct filetype.

   CONCAT is re-entrant for use with the GO command.

   The console is checked for a  character everytime a sector of input is read
from disk.  If the character is a ^C,  then CONCAT cancels the operation, just
as if an error occurred, erasing the incomplete  output file.   This  feature,
however, will not work in Append mode (see below).
 Usage - 3/3 

   If CONCAT is called without a command tail or with an option of two slashes
(//), a brief help screen will be displayed.   The actual name by which CONCAT
was invoked is displayed in this usage message.   Also, the current effects of
the configurable options (that is, all options but D and I) are displayed.
 Append Mode 

   In append mode (option A) CONCAT by-passes 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.

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

   Entering a ^C in Append mode has no  effect.   A target file is irrevocably
changed as soon as a single byte is appended to it.   Rather than leave such a
file in an unknown condition,  CONCAT ignores any ^C's and continues appending
until the job is finished.   For the  same  reason it is inadvisable to bypass
space checking when using append.

   If you would like to be able to  append without using the A option,  set up
an ARUNZ alias script as follows:
     APPEND    CONCAT $* /A
Of course,  you could also  make append the  default and use the C option when
you want to concatenate.
 Disk Space Checking - 1/2 

   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  concatenation  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 or I options are chosen.  In
addition,  disk  space is  determined  in  kilobytes,   based  on  the  disk's
allocation block size.

   These limitations make it possible for  CONCAT to  be  fooled into thinking
that there is not enough disk  space  even  though adequate free space exists.
Moreover,  space  checking can  add  several seconds to CONCAT's running time,
depending on the number of source files involved  and  on  whether the various
drives are already logged in.
 Disk Space Checking - 2/2 

   For the above reasons,  the S  option allows  bypassing disk space checking
for those impatient souls with  more  guts than brains.   Also,  CONCAT can be
configured to bypass space checking by default.  The S option will then toggle
space checking back on.
 File Date Stamping   

   The method for transferring file date stamps is not obvious for a concaten-
ation utility.  CONCAT gives the destination file the create date of the first
file in the source file list, unless there is a source file with the same name
as the destination file.   In that case the destination file will be given the
create date stamp of the file with the same name.
 Date String - 1/2 

   If the D option is  given,  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  file and the first appended file.  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 to your liking.  In the distributed version they are:
     PREFIX:   <CR><LF>"--- [ "
     SUFFIX:   " ] ---"<CR><LF><CR>LF>

Thus the date will appear as:

--- [ March 8, 1990  1:46 pm ] ---
 Date String - 2/2 

   You may change the two strings to your liking.  The strings can be up to 20
bytes long and must end with a null byte.   A  patch  file is distributed with
CONCAT to make it simple to load new strings if you wish.
 Divider String 

   If the I option is given, a divider string is inserted between each file as
it is concatenated or appended.  The divider string as distributed is:

     <CR><LF>"----"<CR><LF>

This is  a  duplicate of the  divider  inserted into  FOR files used on remote
systems.

   The divider string may be  changed to  your  liking  using the accompanying
patch file.  The divider string can be up to 80 bytes long and must end with a
null byte.
:4
 Error Codes 

   If an error occurs,  such as a source file not found, the incomplete output
file is erased (except in  append  mode)  and the  ZCPR3 program error flag is
set.  The error flag values are set as follows:

      2 = invalid directory specification
      8 = ambiguous or missing filename (output or source)
     10 = source or target file not found
     11 = disk or directory full (write error)
     12 = insufficient memory
     19 = invalid command line option
      4 = all other errors

   An error also causes CONCAT to invoke the error handler, if one is running.
These same codes are passed to the error handler.

   For safety reasons invalid  options  are  considered  errors.   Using the D
option without a  resident  clock  also  yields an error.   Error messages are
displayed without regard for quiet mode.
:5
 Configuration 

   The date prefix and suffix  strings and  the  divider string can be patched
into CONCAT with the CONCATPT.Z80 patch file,  which can be edited,  assembled
into a HEX file, and inserted into CONCAT with MLOAD.

   Using ZCNFG and the  accompanying  CONCATnn.CFG file, several configuration
options can be set to your liking.   (Do  not change the name of the CFG file,
so that ZCNFG can  always  find  it,  even if you  change  the  name of CONCAT
itself.)

   The configuration options include (1) default to verbose or quiet mode; (2)
default to concatenating or appending;  (3) default to text or object (binary)
mode;  (4) default to checking for adequate disk space or not;  (5) default to
file stamp transferring or not;  (6) use  American or European date format for
D option;  and (7) use civilian or military time  for D option.   Full details
for the configuration options are given on the ZCNFG help screens.
:6
 CONCAT Notes - 1/4 

   a. Version 1.1 updates (2/2/91, Gene Pizzetta):
      - Added error code 19  (invalid  option),  12  (memory overflow),  and 2
        (invalid directory) for error handler.  
      - Converted to Zilog mnemonics.  
      - Added check for ZCPR3 before doing anything.  
      - Several code optimizations.  
      - Most defaults made configurable using ZCNFG.  
      - Added C (concatenate) and T (text files) for normal defaults.  
      - File date stamping support:  outfile will have the same create date as
        first infile, unless a later infile has the same name as the outfile.
        Option F toggles file stamping on or off.  
      - Replaced ZFNAME,  which does not set the invalid  directory flag, with
        ZPRSFN parser, which sets it under *some* circumstances.  
      - Added modified civilian time  routine that  prints  "am" or "pm" after
        time string  and  modified  date  routine  that  outputs  American  or
        European date formats (configurable) for D option.  
      - Added I option to insert a divider string between files.
 CONCAT Notes - 2/4 

   b. 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 - 3/4 

   c. Version 0.9 updates (4/8/90, Gene Pizzetta):
      - Developmental version released for beta test only.  
      - Added disk space checking and S option to turn it off.  
      - Displays actual name of program in usage message.  
      - Invokes error handler on error.  
      - ^C aborts during concatenation, but not during append.

   d. Version 0.8 updates (3/8/90, Gene Pizzetta):
      - 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.

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

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

   g. Version 0.5 updates (11/25/89, Gene Pizzetta):
      - 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.

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

   i. Version 0.3 updates (9/19/89, Gene Pizzetta):
      - First preliminary release.
