;                                  CONCAT 
                                Version 1.8

                               Gene Pizzetta
                             October 31, 1993

A ZCPR3 utility that concatenates two or more source files into a new file, 
similar to PIP, or appends them to an existing file.  Named directory (DIR) 
and drive/user (DU) specs can be used, allowing elaborate concatenations 
with files pulled from various drives and user areas.  Input and output 
redirection is available.

           U  Usage                         R  Redirecting Input/Output
           O  Options                       E  Errors

           A  Append Mode                   D  Date String
           F  File Date Stamp Transfer      I  Divider String
           S  Disk Space Checking           C  Configuration

           H  History                       B  Bug Reports
:U

                                   USAGE 


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


Any file without a DU or DIR specification is assumed to be in the current 
directory.  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 replace one of the input file specifications 
for redirected input from the console or the auxiliary device (reader).

An output file and at least one source (input) file are 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 
repeatedly in the source file list.  An equal sign ("=") separates the 
destination filename from the source filenames.  Commas or spaces, or both, 
separate multiple source filenames.

USAGE (continued)

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.  For example,
     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

The option list is also relaxed.  See "Options" for the details.

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.

USAGE (continued)

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.

If CONCAT is called without a command tail or with one or two slashes (//), 
a not 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.
:O

                                  OPTIONS 


A leading slash is always required when options are given on the command 
line.

 Operating Modes: 

     A    Append mode.  Appends the source files to the end of an existing 
          file.  This mode by-passes some of CONCAT's safety features.  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 redirection is used.

     C    Concatenation mode.  Concatenates the source files into a new 
          file.  This is the default mode of the release version.

OPTIONS (continued)


 File Modes:

     O    Object (binary) file mode.  This mode 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 automatically turned off if O is 
          used.

     T    Text file mode.  This mode causes CONCAT to concatenate or append 
          files at the CP/M end-of-file character (^Z).  This is the 
          default file mode of the release version.

OPTIONS (continued)

 Other Options:

     D    Insert date.  Inserts 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 divider string.  Inserts a string into the destination 
          file before each source file is added.  If the option is followed 
          by a string ("s"), 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 (continued)

     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:).

     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.  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) state.  Quiet mode is turned on if output is redirected 
          to the console (CON:).

OPTIONS (continued)

     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 redirected output is used, since it would be 
          superfluous.

     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.  
          Under Z3Plus no date stamp transfers are done, so the F option is 
          unavailable.

OPTIONS (continued)

     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.

The option list must the last command line parameter and must begin with a 
slash, but it can contain additional slashes and spaces.  For example,
     /ADI""S
works the same as
     /A D I'' S
which works the same as
     /A/D/I$$/S
which works the same as
     /A /DI///S
The first two slashes following the I option above are string delimiters.
:R

                       REDIRECTING INPUT AND OUTPUT 

Output can be redirected to the console, the printer, or the auxiliary 
device by substituting "CON:", "LST:", or "AUX:" for the output file 
specification.  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 
characters, 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, however, to automatically add a line feed after a 
carriage return.

REDIRECTING INPUT AND OUTPUT (continued)

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 
perforations 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 
or 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 (continued)

The real problem with AUX: input is determining when input has completed.  
There is no 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.  Rebooting is the only way to recover.  CONCAT's 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 termination character as the last 
character in the stream.

The O (object file) option is valid with redirected input and output, but 
it's of no practical use with AUX:.

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:".
:E

                                  ERRORS 

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 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
    255   user abort (optional)
      4   all other errors

The error handler, if one is running, will be invoked for all errors.

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.

ERRORS (continued)

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.
:A

                                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.

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 (continued)

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
Even when calling CONCAT via this APPEND alias, you can still include 
additional options on the command line.  Of course, you can also make 
append the default and use the C option when you want to concatenate.
:F

                            FILE DATE STAMPING 

The method for transferring file date stamps is not obvious for a 
concatenation 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.

If the source has a modify date but no create date, the modify date will be 
transferred to the create date of the destination instead, so that the only 
date available is preserved.

File stamp transfer is always off in append mode and when CONCAT is running 
under Z3PLUS.
: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 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.  
Redirected 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. 
Or, with redirected input, CONCAT may think there is plenty of space when 
there isn't.  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 (continued)

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

                                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 and keep track of the time items are appended.

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 against the left margin 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.
:I

                              DIVIDER STRING 

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 
characters 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 as "^M" and "^J".  
The string may be as long as the remaining command line allows.

DIVIDER STRING (continued)

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 only by 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.  It 
can be up to 76 bytes long.
:C

                               CONFIGURATION 

CONCAT is distributed ready to use on ZCPR3 and Z3Plus systems, but a large 
number of configuration options are available.

Configuration requires ZCNFG and the accompanying CONCATnn.CFG file.  It is 
best not to change the name of the CFG file because the name insures ZCNFG 
finding the correct CFG file to match your version of CONCAT.

Configuration includes setting defaults for options available via the 
command line: 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.  Other settings are 
permanent and cannot be changed from the command line:  date format 
(American, European, or Japanese), time format (military or civilian), 
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.
:H

                                  HISTORY 


For CONCAT's version history, see the accompanying history file.
:B

                        BUG REPORTS AND SUGGESTIONS 

Please report any bugs as soon as possible, and make suggestions at your 
leisure:

                  Gene Pizzetta
                  481 Revere St.
                  Revere, MA 02151

                  Voice:  (617) 284-0891
                  Newton Centre Z-Node:  (617) 965-7259
                  Ladera Z-Node Central:  (310) 670-9465
