CONCAT Version 1.1 Gene Pizzetta February 2, 1991 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. USAGE: 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. OPTIONS: A slash before the option list is required. A Append mode. Appends the source files to the end of an existing file. This mode by-passes 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. This is the default mode of the release version. 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. My 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 automatically 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). This is the default file mode of the 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. 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. 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. CONCAT requires an output file and at least one source (input) 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 filename from the source filenames. Commas or spaces, or both, separate multiple source filenames. 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 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). 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: 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. 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 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. 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: "--- [ " SUFFIX: " ] ---"LF> Thus the date will appear as: --- [ March 8, 1990 1:46 pm ] --- 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: "----" 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. 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. 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. HISTORY: Version 1.1 -- February 2, 1991 -- 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. Version 1.0 -- April 24, 1990 -- Gene Pizzetta All known bugs fixed, including one that caused problems when no alternate video strings were installed in the TCAP. A special thanks to Howard Goldstein for his efforts to uncover problems and make sure this version works as intended. Version 0.9 -- April 8, 1990 -- 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. Version 0.8 -- March 8, 1990 -- Gene Pizzetta Added D (date) option. Date string prefix and suffix may be configured (see above). Corrected minor bug which caused the 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. (CONCAT and its data area have become too large for a static 32K output buffer, what with RSX's, et al.) Invalid options are no longer ignored, but now cause an error. Version 0.7 -- December 17, 1989 -- Gene Pizzetta Added A (append) option, which by-passes several of CONCAT's safety features. Also, a few more optimizations. Version 0.6 -- December 3, 1989 -- Gene Pizzetta Minor changes in setting error flag. Corrected serious error in detecting top of memory, found by Howard Goldstein, who also suggested several changes to make the code more efficient. Thanks, Howard. Version 0.5 -- November 25, 1989 -- Gene Pizzetta Added Q (quiet) option and error flag support. Fixed parser bug that allowed a null output filename. Now closes output file on error before erasing it, a bug discovered by Howard Goldstein. Version 0.4 -- November 12, 1989 -- Gene Pizzetta Added large output buffer. Corrected error in parsing filespec in current user. Relaxed command line syntax: commas no longer required. Now obeys quiet flag. Version 0.3 -- September 19, 1989 -- Gene Pizzetta First preliminary release. If you find any bugs or have any suggestions, I'd like to hear them. Gene Pizzetta 481 Revere St. Revere, MA 02151 Voice: (617) 284-0891 Newton Centre Z-Node: (617) 965-7259 Ladera Z-Node Central: (213) 670-9465