;
                                 CONCAT.COM                                   

             Size (recs) CRC   Version    Author/Latest Issue      Disk
               7k (56)   C5BD  1.6        Gene Pizzetta 11/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.   Input and output redirection is also provided.   The 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  specification is assumed to be in the current
drive/user.   CON:, LST:, or AUX: can replace the output file specification to
redirect output to the console, the printer,  or the auxiliary device (punch).
CON: and AUX: can also replace one of the input file specifications for redir-
ected input from the console or the auxiliary device (reader).
:2
 Options - 1/4 

   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.  Append mode is turned off if output redir-
       ection is used.
  
   C - Concatenates the source files into  a new file.   [Default]
       
   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 those options are automatic-
       ally turned off if O is used.

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

   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{s} - Insert a divider string into  the  destination  file before each source
       file is concatenated or  appended.  If  the  option is  followed  by  a 
       string, that string will be used; otherwise, an internal default string 
       is inserted.   The string delimiter  (the first character following the
       "I" can be any non-alphanumeric  character.   The  two  delimiters must
       always be present, even if no string is included,  unless I is the last
       option on the command line.   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/4 

   Q - Toggle quiet mode.  Normally the destination filename is printed to 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.  Regard-
       less 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.   Quiet mode is turned on if
       output is redirected to the console (CON:).

   H - Filter high bits and control characters.   The most significant  bit of
       each character is zeroed and control characters are removed  (excepting
       horizontal tabs,  carriage returns,  line feeds, and form feeds).  This
       option is most useful when redirecting output to the console  (CON:) or
       to the printer (LST:).

   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.   Space checking is turned off if redir-
       ected output is used, since it would be superfluous.
 Options - 4/4 

   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.
       Date stamp transfer is turned off in  append  mode  or  when redirected
       output is used.

   P - Toggle screen and printer paging.   Paging has no  effect  except  when
       output is redirected to the  console  (CON:) or to  the printer (LST:).
       If paging is in effect for console output,  each time the  screen fills
       CONCAT will wait for  a  keypress  before  continuing.   If  paging  is
       turned off, console output can  still be paused  with ^S.  If paging is
       active for printer output,  a form feed will be output to skip over the
       perforations.   The number of lines on the  screen  or  printer page is
       obtained from the environment.
:3
 Usage - 1/3 

   An output file and at least one source  (input)  file is  required,  except
when redirection is used.  Actually, CONCAT can be used as  a simple file-copy
utility,  but that's not its purpose.   The same filename may be given repeat-
edly 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 (actually,  a colon alone will work).   Otherwise,  CONCAT  will
think it has found an option list.

   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  (128 bytes) of
input is read, from disk.   If the character is a ^C, ^K, or ^X, or just plain
C, K, or  X, 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 or during redirected console input (see below).
 Usage - 3/3 

   If CONCAT is called without a command tail or with an option of two slashes
(//), a nor so brief help screen will be displayed.   The actual name by which
CONCAT was invoked is displayed on the syntax line.  Also, the current effects
of the command line options are displayed, depending on your configuration.
 Append Mode - 1/2 

   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.

   Append mode cannot be aborted  short of  opening  the  disk  drive  door or
reseting your  computer  (but don't do it).   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 abort attempt and continues
appending until the job is finished.  For the same reason it is inadvisable to
bypass space checking when using append.
 Append Mode - 2/2 

   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.  Redirec-
ted input is not included in  the  calculation  at  all.   Disk  free 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 

   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:   "^M^J--- [ "
     SUFFIX:   " ] ---^M^J^M^J"

Thus the date will appear as:    --- [ March 8, 1990  1:46 pm ] ---

   You may change the two strings to your liking with ZCNFG.   The strings can
be up to 20 bytes long.
 Divider String - 1/2 

   If the I option is given, a divider string is inserted between each file as
it is concatenated or appended.  The  I  option may be followed by a string to
be used as the divider.   Certain  "escape sequences"  may be  included in the
string to enter characters that cannot otherwise be used:

     ^c   insert character c as a control character
     %>   insert the following characters in lower-case
     %<   insert the following characters in upper-case
     %D   insert a delete character
     %S   insert a semi-colon
     %^   insert a carat character
     %%   insert a percent character

   All other characters will be inserted as entered, except that alpha charac-
ters default to upper-case in the absence of the "%>" sequence.  CONCAT can be
configured to default to lower-case, if desired.  If carriage returns and line
feeds are desired,  they must be given  ("^M" and "^J".   The string may be as
long as the remaining command line allows.
 Divider String - 2/2 

   The string delimiters (the first and last characters of the string)  may be
any non-alphanumeric character.  They are not sent to the output.

   If the I option is not followed by a  string,  but  by  only  two delimiter
characters in succession,  an  internal default divider string  will  be used.
The default divider as distributed is:

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

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

   The default divider string may be changed to your liking using ZCNFG.   The
divider can be up to 76 bytes long.
 Redirecting Input and Output - 1/3 

   Output can be redirected to the console,  the  printer,  or  the  auxiliary
device by substituting "CON:", "LST:", or "AUX:" for the output file specific-
ation.   Input can be  redirected  from the console or the auxiliary device by
substituting "CON:" or "AUX:" for an input file specification.

   CON: output can be paged or  continuous.   If  paging is  selected,  CONCAT
waits for a keypress each time the screen fills.   Output  can  also be paused
with ^S.   The number of screen lines is  obtained  from  the environment.  In
many cases the H option should be used to filter out control and 8-bit charac-
ters, which could cause strange things to  happen to your screen.   CON: input
allows no editing.   Input is automatically echoed to the  screen, but control
characters (except carriage return, line feed,  backspace, bell, and null) are
expanded to "^c".   They are sent to  the  output  as-is,  however.   A  ^Z is
entered when input is completed.   If more than one line is  entered,  both  a
carriage return and a line feed must be typed.  CONCAT can be configured, how-
ever, to automatically add a line feed after a carriage return.
 Redirecting Input and Output - 2/3 

   LST: output can also be paged or continuous.  If paging is selected, CONCAT
sends a form feed to the printer as each page fills, to skip over the perfora-
tions of continuous forms.   The number of lines per page is obtained from the
environment.  For obvious reasons LST: cannot be used for input.  The H filter
option may be useful here, also.

   AUX: input/output  was  known as  "punch" (PUN:) and  "reader" (RDR:) under
CP/M 2.2.   Auxiliary is the name used under CP/M Plus and ZSDOS.   It is less
useful than CON: and LST:, but AUX: output, at least, does have its uses.  For
instance,
     CONCAT AUX: = CON:
can be used to send commands to a modem for such things as dialing a number of
setting up the default parameters in  non-volatile  RAM.   Or,  if you need to
burn an EPROM,
     CONCAT AUX: = CON:, MYFILE.HEX
allows sending commands to the  EPROM  programmer and then, when ^Z is entered
to end console input, a hex file is automatically uploaded.
 Redirecting Input and Output - 3/3 

   The biggest problem with  AUX:  input is  determining  when input  has com-
pleted.   There is no auxiliary status routine in the  DOS to determine when a
character is ready,  so  CONCAT  will wait  forever if it requests a character
from AUX: and no character is sent.  Resetting the computer is the only way to
recover.   For that reason, the  AUX:  input  routine  looks for a termination
character in the input stream,  which  can  be  configured  to any value.  The
default is ^Z (1Ah).  If AUX: output is used, CONCAT will also send the termi-
nation character as the last character in the stream.

   The O (object file) option is valid with  redirected input and output,  but
because of the limitations of AUX: discussed above,  it's of no practical use-
fulness.

   Directories named  "CON",  "LST", or  "AUX" will cause no problems.  CONCAT
checks for a valid file specification  before it  considers the possibility of
redirected input or output.   Remembering that should explain why  an "invalid
directory" message will be issued if  "CON:MYFILE"  is on the command line and
there is no CON directory.  Or the message might say "missing source filename"
if CONCAT finds a console input specification misspelled "COM:".
:4
 Error Codes - 1/2 

   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
    FFh = user abort (optional)
      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.
 Error Codes - 2/2 

   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.

   Whether a user abort (via ^C,  etc.)  generates an  error is a configurable
option.   Invoking the error  handler  after  aborting  CONCAT  can  be useful
because it will allow cancelling any  active  SUB  or ZEX batch job,  but some
people may not want the minor inconvenience of having to  also abort the error
handler.
:5
 Configuration 

   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  setting  several  defaults:  verbose  or
quiet operation,  concatenation  or  append  operating  mode,  text  or object
(binary) file mode, checking for adequate disk space or not,  transferring the
file date stamp or not, etc.  American or European date format and military or
civilian time for the  D  option can also be  set,  along  with  several other
parameters.   In addition,  the date prefix and suffix strings and the default
divider string can be changed.

   Full details for the  configuration  options  are  given  on the ZCNFG help
screens.
:6
 CONCAT Notes - 1/3 

   a. Vs 1.6 updates (11/11/91, Gene Pizzetta):
      - A few hours after release of 1.5,  I discovered  that redirected input
        produced an error if space checking was on and  CON:  or  AUX: was the
        only input specification.  Such is life; it has been fixed.
      - In addition, entering control  characters  during  console input could
        cause strange things to happen to the screen.   Console input echo now
        uses CCOUT which displays control characters them as "^c",  except for
        carriage return,  linefeed,  backspace,  bell,  and null.   Redirected
        console output is not automatically filtered.

   b. Vs 1.5 updates (11/7/91, Gene Pizzetta):
      - Many changes.  Now accepts  "CON:",  "LST:",  or  "AUX:" in place of a
        destination file for redirected output to console, printer,  or auxil-
        iary device (punch).  
      - Output to console and  printer can be  paged  by  using  the  new  "P"
        command line option.  
      - Also accepts "CON:" and  "AUX:" in place of a source file for redirec-
        ted input from console or auxiliary device (reader).  Redirected input
        must end with a ^Z.  
 CONCAT Notes - 2/3 

      - Can be configured to output  a  line  feed after every carriage return
        during CON: input.  
      - New "H" option causes high  bits to be reset and control characters to
        be removed from the output stream.  
      - Option I changed so it does  not  have  to  be  at end of option list:
        first character after the I is taken to be a  delimiter and the string
        ends when a second occurrence  of the delimiter is found or at the end
        of the command line.  The delimiter must be non-alphanumeric.  
      - Several new, more specific error messages.  
      - User abort with  ^C  can  be  configured to set the error flag or not.
      - Date/time prefix and suffix  strings  (option D)  and  divider  string
        (option I) can now be configured with ZCNFG.
      - Replaced VLIB routines with ZSLIB HV routines to save space. 
      - Made several code  changes  and  deletions,  and added some additional 
        library routines to improve efficiency.  
      - Now aborts with ^C, ^K, or ^X,  or their upper- or lower-case counter-
        parts.
 CONCAT Notes - 3/3  

   c. Vs 1.4 updates (5/28/91, Gene Pizzetta):
      - Bug Fix:   For want of an "OR A", the European date for the  D  option
        did not work.  It does now.

   d. Vs 1.3 updates (2/23/91, Gene Pizzetta(:
      - Bug Fix:  Option I was also toggling option F (a missing RET).  
      - Bug fix:  The file date stamp was not being written properly for files
        larger than one  physical  extent  (FCB is  now  being  re-initialized
        before writing stamp).  
      - Option I now accepts divider string on  command  line, using  standard
        ECHO-type escape sequences.   Option  I  MUST be the last command line
        option given!

   c. Vs 1.2 updates (2/11/91, Bruce Morgen):
      - Uses the CPR parser whenever possible to further enhance invalid  dir-
        ectory reporting, otherwise use ZPRSFN as in Version 1.1.  New routine
        is at Zparse:.  
      - Fixed a string at JUL: that befuddled poor old M80.  
      - Did some not-terribly-significant code tweaks.
