home *** CD-ROM | disk | FTP | other *** search
- ;
- 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.