CONCAT Version 1.6 Gene Pizzetta November 11, 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. Input and output redirection is also provided. The 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. 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 redirected input from the console or the auxiliary device (reader). 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. Append mode is turned off if output redirection 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. 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, 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"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. H Filter high bits and control characters. The most significant bit of each character is zeroed and control characters are removed (excepting norizontal 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:). 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. 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. 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 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 (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). If CONCAT is called without a command tail or with an option of 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. 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. 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. 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. 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 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. The biggest problem with AUX: input is determining when input has completed. 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 termination 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 usefulness. 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:". 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. 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. 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: "^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: 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 ("^M" and "^J". The string may be as long as the remaining command line allows. 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: "----" 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. 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 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. 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. 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. HISTORY: For version history, see accompanying history file. 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