CONCAT Version 1.0 Gene Pizzetta April 24, 1989 CONCAT concatenates -- or appends -- two or more source files to a destination file, similar to PIP. Unlike PIP, however, CONCAT accepts both named directory (DIR) and drive/user (DU) specifications, which allows elaborate concatenations with input files pulled from various drives and user areas. CONCAT runs under ZCPR3 only. 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 Append mode. Appends sources files to end of target file, which must exist. This mode by-passes 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 new output file or, in append mode, at the end of the existing file before any files are appended. This option is incompatible 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 incompatible with the D option. Q Toggle quiet mode. Normally CONCAT prints the names 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 Toggle disk space checking. Normally CONCAT checks the destination drive to make sure there is enough free space to successfully complete the operation. Option S toggles the feature off. If a configuration byte at 119h is set to a non-zero value, however, CONCAT will not check disk space before copying the files. If the configuration byte is set, then the S option will toggle space checking back on. 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. 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. 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 on the screen. The actual name by which CONCAT was invoked is displayed in the usage message. Also, the current state of the two configurable toggle options (Q and S) is 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. 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 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 option is chosen, even though that option could add only a maximum of 75 bytes to the resulting output file. In addition, disk space is determined in kilobytes, based on the disk's allocation block size. 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. Moreover, 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 the above reasons, the S 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. DATE STRING: 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 to your liking. In the distributed version they are: PREFIX: "--- [ " SUFFIX: " ] ---"LF> Thus the date will appear as: --- [ 3/08/90 13:46 ] --- In the first sector of the COM file are two 31-byte buffers where you may change the two strings to your liking. The strings must end with a null byte. The buffers are located at 121h and 147h and 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, although tnen they might not display very well on your screen. ERROR CODES: If an error occurs, such as a source file not found, the incomplete output file is erased and the ZCPR3 program error flag is set. The error flag values are set as follows: 8 = ambiguous or missing filename (output or source) 10 = source or target file not found 11 = disk or directory full (write error) 4 = all other errors In addition to setting the program error flag, 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 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. HISTORY: 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. This is probably that last CONCAT version for a while, unless a bug is found or reported, or unless someone has a suggestion for a useful enhancement. If you find any bugs or have any suggestions, I'd like to hear them. Gene Pizzetta 481 Revere Street Revere, MA 02151 Newton Centre Z-Node: (617) 965-7259 GEnie: E.PIZZETTA Voice: (617) 284-0891