home *** CD-ROM | disk | FTP | other *** search
/ CP/M / CPM_CDROM.iso / jsage / znode3 / uploads / z3help43.lbr / CONCAT.HZP / CONCAT.HLP
Encoding:
Text File  |  1993-06-07  |  22.8 KB  |  432 lines

  1. ;
  2.                                  CONCAT.COM                                   
  3.  
  4.              Size (recs) CRC   Version    Author/Latest Issue      Disk
  5.                7k (56)   C5BD  1.6        Gene Pizzetta 11/91      Z3COM3
  6.  
  7.   1- Syntax  2- Options  3- Usage  4- Err Codes  5- Configuration  6- Notes   
  8.  
  9.  
  10.    CONCAT is a ZCPR3 utility that concatenates two or more source files into a
  11. new file,  similar to PIP,  or appends them to an existing file.   Both  named
  12. directory  (DIR) and  drive/user  (DU)  specifications  can be used,  allowing
  13. elaborate concatenations with input files  pulled from various drives and user
  14. areas.   Input and output redirection is also provided.   The file create date
  15. stamp is transferred to the new file in concatenation mode.
  16. :1
  17.  
  18.   Syntax   CONCAT {dir:}outfile = {dir:}infile {{dir:}infile {...}} {/options}
  19.  
  20.    Any file without a DU or DIR  specification is assumed to be in the current
  21. drive/user.   CON:, LST:, or AUX: can replace the output file specification to
  22. redirect output to the console, the printer,  or the auxiliary device (punch).
  23. CON: and AUX: can also replace one of the input file specifications for redir-
  24. ected input from the console or the auxiliary device (reader).
  25. :2
  26.  Options - 1/4 
  27.  
  28.    A - Append mode.   Appends the source files to the end of an existing file.
  29.        This mode bypasses some of CONCAT's safety features  (see  below).   To
  30.        preserve the original file create stamp, file stamp transfer (F option)
  31.        is turned off if A is used.  Append mode is turned off if output redir-
  32.        ection is used.
  33.   
  34.    C - Concatenates the source files into  a new file.   [Default]
  35.        
  36.    O - Object (binary) file mode,  which causes  CONCAT to ignore ^Z  (end-of-
  37.        file) characters and concatenate or append files on  record boundaries.
  38.        Object file mode is provided because some hard-disk backup programs can
  39.        break large files across  two or  more floppy disks.   The  FSPLIT file 
  40.        splitting utility  also  allows  splitting  binary  files.  Option O is 
  41.        incompatible with the D and I options,  so those options are automatic-
  42.        ally turned off if O is used.
  43.  
  44.    T - Text file mode,  which causes CONCAT to  concatenate or append files at
  45.        the CP/M end-of-file character (^Z).   [Default]
  46.  Options - 2/4 
  47.  
  48.    D - Insert the system date and time into the destination file.  The current
  49.        system date and time is  inserted at  the  head  of  the  new file when
  50.        concatenating,  or at the end of the existing file before any files are
  51.        added when appending.   This  option  is incompatible with the O option
  52.        and is automatically turned off if the O option is selected.
  53.  
  54. I{s} - Insert a divider string into  the  destination  file before each source
  55.        file is concatenated or  appended.  If  the  option is  followed  by  a 
  56.        string, that string will be used; otherwise, an internal default string 
  57.        is inserted.   The string delimiter  (the first character following the
  58.        "I" can be any non-alphanumeric  character.   The  two  delimiters must
  59.        always be present, even if no string is included,  unless I is the last
  60.        option on the command line.   The divider string will not appear at the
  61.        head of the first file.   This option is incompatible with the O option
  62.        and is automatically turned off if the O option is selected.
  63.  Options - 3/4 
  64.  
  65.    Q - Toggle quiet mode.  Normally the destination filename is printed to the
  66.        screen, and then the name of each  source  file as it is read.   CONCAT
  67.        can be configured,  however,  to default to quiet mode,  printing  only
  68.        error messages.  The Q option toggles to the non-default mode.  Regard-
  69.        less of the configured state,  CONCAT  defaults to  quiet  mode if  the
  70.        ZCPR3 quiet flag is  set.  In that  case  the  Q  option  will likewise
  71.        toggle to the non-default  (verbose) mode.   Quiet mode is turned on if
  72.        output is redirected to the console (CON:).
  73.  
  74.    H - Filter high bits and control characters.   The most significant  bit of
  75.        each character is zeroed and control characters are removed  (excepting
  76.        horizontal tabs,  carriage returns,  line feeds, and form feeds).  This
  77.        option is most useful when redirecting output to the console  (CON:) or
  78.        to the printer (LST:).
  79.  
  80.    S - Toggle disk space  checking.   Normally,  before  any  file  operations
  81.        begin, the destination drive is  checked  to  make sure there is enough
  82.        free space to successfully  complete the  append or  concatenation.  If
  83.        you're impatient  and  maybe  a  little  foolhardy,  you can turn space
  84.        checking off with this option.   Space checking is turned off if redir-
  85.        ected output is used, since it would be superfluous.
  86.  Options - 4/4 
  87.  
  88.    F - Toggle file date stamp transferring.  In concatenation mode CONCAT will
  89.        transfer to the destination file the create date stamp of a source file
  90.        with the same  name,  or if none  have the same name,  the stamp of the
  91.        first source file.   If you  would  prefer  that  the new file have the
  92.        current date,  you can turn  off  stamp  transferring with this option.
  93.        Date stamp transfer is turned off in  append  mode  or  when redirected
  94.        output is used.
  95.  
  96.    P - Toggle screen and printer paging.   Paging has no  effect  except  when
  97.        output is redirected to the  console  (CON:) or to  the printer (LST:).
  98.        If paging is in effect for console output,  each time the  screen fills
  99.        CONCAT will wait for  a  keypress  before  continuing.   If  paging  is
  100.        turned off, console output can  still be paused  with ^S.  If paging is
  101.        active for printer output,  a form feed will be output to skip over the
  102.        perforations.   The number of lines on the  screen  or  printer page is
  103.        obtained from the environment.
  104. :3
  105.  Usage - 1/3 
  106.  
  107.    An output file and at least one source  (input)  file is  required,  except
  108. when redirection is used.  Actually, CONCAT can be used as  a simple file-copy
  109. utility,  but that's not its purpose.   The same filename may be given repeat-
  110. edly in the source file list.   An equal sign separates the  output  file from
  111. the source files.   Commas or spaces, or both, separate multiple source files.
  112.  
  113.    A relaxed command line is allowed.   While the  equal  sign is required, it
  114. may be separated from the filenames by one or  more spaces.   The same applies
  115. to commas, if they are used; i.e, 
  116.  
  117.      CONCAT NEWFILE.TXT=FILE1.TXT,FILE2.TXT,FILE3.TXT,FILE4,TXT
  118. works the same as
  119.      CONCAT NEWFILE.TXT=FILE1.TXT FILE2.TXT FILE3.TXT FILE4.TXT
  120. which works the same as
  121.      CONCAT NEWFILE.TXT = FILE1.TXT, FILE2.TXT ,FILE3.TXT , FILE4.TXT
  122. which works the same as
  123.      CONCAT NEWFILE.TXT = FILE1.TXT FILE2.TXT FILE3.TXT, FILE4.TXT
  124.  Usage - 2/3 
  125.  
  126.    A filename cannot begin with  a slash unless it  is preceded by a DU or DIR
  127. specification (actually,  a colon alone will work).   Otherwise,  CONCAT  will
  128. think it has found an option list.
  129.  
  130.    In concatenation mode,  if  another  file  has  the same name as the output
  131. file, it will be renamed to filetype BAK.  CONCAT initially creates the output
  132. file with a filetype of $$$.   After the  copy is  successfully completed, any
  133. existing BAK file is erased, the new BAK file is created,  and the output file
  134. is renamed to the correct filetype.
  135.  
  136.    CONCAT is re-entrant for use with the GO command.
  137.  
  138.    The console is checked for a character everytime  a  sector  (128 bytes) of
  139. input is read, from disk.   If the character is a ^C, ^K, or ^X, or just plain
  140. C, K, or  X, then CONCAT cancels the operation,  just as if an error occurred,
  141. erasing the incomplete output file.   This feature,  however, will not work in
  142. Append mode or during redirected console input (see below).
  143.  Usage - 3/3 
  144.  
  145.    If CONCAT is called without a command tail or with an option of two slashes
  146. (//), a nor so brief help screen will be displayed.   The actual name by which
  147. CONCAT was invoked is displayed on the syntax line.  Also, the current effects
  148. of the command line options are displayed, depending on your configuration.
  149.  Append Mode - 1/2 
  150.  
  151.    In append mode (option A) CONCAT by-passes several safety features,  so use
  152. it with caution.  For instance, no temporary file or BAK file is created.  The
  153. target (output) file must already exist, but it can be zero-length.  On error,
  154. the output file is closed after  appending  any  text that was read before the
  155. error occurred.  The output file is not erased.
  156.  
  157.    Do not attempt to append a file to itself.   You're  not likely to be happy
  158. with the results.  Use concatenation mode instead.
  159.  
  160.    Append mode cannot be aborted  short of  opening  the  disk  drive  door or
  161. reseting your  computer  (but don't do it).   A  target  file  is  irrevocably
  162. changed as soon as a single byte is appended to it.   Rather than leave such a
  163. file in an unknown condition,  CONCAT  ignores any abort attempt and continues
  164. appending until the job is finished.  For the same reason it is inadvisable to
  165. bypass space checking when using append.
  166.  Append Mode - 2/2 
  167.  
  168.    If you would like to be able to  append without using the A option,  set up
  169. an ARUNZ alias script as follows:
  170.  
  171.      APPEND    CONCAT $* /A
  172.  
  173. Of course,  you could also  make append the  default and use the C option when
  174. you want to concatenate.
  175.  Disk Space Checking - 1/2 
  176.  
  177.    Before any files are opened,  CONCAT checks the amount of free space on the
  178. target disk and then  checks the  sizes of the  source  files  to determine if 
  179. there is  room to  complete  the  concatenation  or  append.   If there is not
  180. sufficient disk space,  an  error  message  is  printed  and  the operation is
  181. cancelled.
  182.  
  183.    File sizes are measured in records,  which are converted to kilobytes after
  184. all the input files' sizes are added together.   Also, another record is added
  185. to the total file size calculation if the D or I options are chosen.  Redirec-
  186. ted input is not included in  the  calculation  at  all.   Disk  free space is
  187. determined in kilobytes, based on the disk's allocation block size.
  188.  
  189.    These limitations make it possible for  CONCAT to  be  fooled into thinking
  190. that there is not enough disk  space  even  though adequate free space exists.
  191. Moreover,  space  checking can  add  several seconds to CONCAT's running time,
  192. depending on the number of source files involved  and  on  whether the various
  193. drives are already logged in.
  194.  Disk Space Checking - 2/2 
  195.  
  196.    For the above reasons,  the S  option allows  bypassing disk space checking
  197. for those impatient souls with  more  guts than brains.   Also,  CONCAT can be
  198. configured to bypass space checking by default.  The S option will then toggle
  199. space checking back on.
  200.  File Date Stamping   
  201.  
  202.    The method for transferring file date stamps is not obvious for a concaten-
  203. ation utility.  CONCAT gives the destination file the create date of the first
  204. file in the source file list, unless there is a source file with the same name
  205. as the destination file.   In that case the destination file will be given the
  206. create date stamp of the file with the same name.
  207.  Date String 
  208.  
  209.    If the D option is  given,  the  time and date string is inserted only once
  210. for each invocation of CONCAT.   If concatenation is used, the date appears at
  211. the beginning of the newly created file.   If the  append  option is selected,
  212. the date appears  between the  original  file and the first appended file.  If
  213. several files are  appended in  a  single  operation,  only  the first file is
  214. preceded by the date string.
  215.  
  216.    This option is provided  primarily for those  who  want  to append to a log 
  217. file on a regular basis, but still keep track of the time period to which each 
  218. section of the file pertains.
  219.  
  220.    The strings sent prior to and subsequent to the date and time string may be
  221. configured to your liking.  In the distributed version they are:
  222.      PREFIX:   "^M^J--- [ "
  223.      SUFFIX:   " ] ---^M^J^M^J"
  224.  
  225. Thus the date will appear as:    --- [ March 8, 1990  1:46 pm ] ---
  226.  
  227.    You may change the two strings to your liking with ZCNFG.   The strings can
  228. be up to 20 bytes long.
  229.  Divider String - 1/2 
  230.  
  231.    If the I option is given, a divider string is inserted between each file as
  232. it is concatenated or appended.  The  I  option may be followed by a string to
  233. be used as the divider.   Certain  "escape sequences"  may be  included in the
  234. string to enter characters that cannot otherwise be used:
  235.  
  236.      ^c   insert character c as a control character
  237.      %>   insert the following characters in lower-case
  238.      %<   insert the following characters in upper-case
  239.      %D   insert a delete character
  240.      %S   insert a semi-colon
  241.      %^   insert a carat character
  242.      %%   insert a percent character
  243.  
  244.    All other characters will be inserted as entered, except that alpha charac-
  245. ters default to upper-case in the absence of the "%>" sequence.  CONCAT can be
  246. configured to default to lower-case, if desired.  If carriage returns and line
  247. feeds are desired,  they must be given  ("^M" and "^J".   The string may be as
  248. long as the remaining command line allows.
  249.  Divider String - 2/2 
  250.  
  251.    The string delimiters (the first and last characters of the string)  may be
  252. any non-alphanumeric character.  They are not sent to the output.
  253.  
  254.    If the I option is not followed by a  string,  but  by  only  two delimiter
  255. characters in succession,  an  internal default divider string  will  be used.
  256. The default divider as distributed is:
  257.  
  258.      <CR><LF>"----"<CR><LF>
  259.  
  260.    This is a duplicate of the divider inserted into  FOR  files used on remote
  261. systems.
  262.  
  263.    The default divider string may be changed to your liking using ZCNFG.   The
  264. divider can be up to 76 bytes long.
  265.  Redirecting Input and Output - 1/3 
  266.  
  267.    Output can be redirected to the console,  the  printer,  or  the  auxiliary
  268. device by substituting "CON:", "LST:", or "AUX:" for the output file specific-
  269. ation.   Input can be  redirected  from the console or the auxiliary device by
  270. substituting "CON:" or "AUX:" for an input file specification.
  271.  
  272.    CON: output can be paged or  continuous.   If  paging is  selected,  CONCAT
  273. waits for a keypress each time the screen fills.   Output  can  also be paused
  274. with ^S.   The number of screen lines is  obtained  from  the environment.  In
  275. many cases the H option should be used to filter out control and 8-bit charac-
  276. ters, which could cause strange things to  happen to your screen.   CON: input
  277. allows no editing.   Input is automatically echoed to the  screen, but control
  278. characters (except carriage return, line feed,  backspace, bell, and null) are
  279. expanded to "^c".   They are sent to  the  output  as-is,  however.   A  ^Z is
  280. entered when input is completed.   If more than one line is  entered,  both  a
  281. carriage return and a line feed must be typed.  CONCAT can be configured, how-
  282. ever, to automatically add a line feed after a carriage return.
  283.  Redirecting Input and Output - 2/3 
  284.  
  285.    LST: output can also be paged or continuous.  If paging is selected, CONCAT
  286. sends a form feed to the printer as each page fills, to skip over the perfora-
  287. tions of continuous forms.   The number of lines per page is obtained from the
  288. environment.  For obvious reasons LST: cannot be used for input.  The H filter
  289. option may be useful here, also.
  290.  
  291.    AUX: input/output  was  known as  "punch" (PUN:) and  "reader" (RDR:) under
  292. CP/M 2.2.   Auxiliary is the name used under CP/M Plus and ZSDOS.   It is less
  293. useful than CON: and LST:, but AUX: output, at least, does have its uses.  For
  294. instance,
  295.      CONCAT AUX: = CON:
  296. can be used to send commands to a modem for such things as dialing a number of
  297. setting up the default parameters in  non-volatile  RAM.   Or,  if you need to
  298. burn an EPROM,
  299.      CONCAT AUX: = CON:, MYFILE.HEX
  300. allows sending commands to the  EPROM  programmer and then, when ^Z is entered
  301. to end console input, a hex file is automatically uploaded.
  302.  Redirecting Input and Output - 3/3 
  303.  
  304.    The biggest problem with  AUX:  input is  determining  when input  has com-
  305. pleted.   There is no auxiliary status routine in the  DOS to determine when a
  306. character is ready,  so  CONCAT  will wait  forever if it requests a character
  307. from AUX: and no character is sent.  Resetting the computer is the only way to
  308. recover.   For that reason, the  AUX:  input  routine  looks for a termination
  309. character in the input stream,  which  can  be  configured  to any value.  The
  310. default is ^Z (1Ah).  If AUX: output is used, CONCAT will also send the termi-
  311. nation character as the last character in the stream.
  312.  
  313.    The O (object file) option is valid with  redirected input and output,  but
  314. because of the limitations of AUX: discussed above,  it's of no practical use-
  315. fulness.
  316.  
  317.    Directories named  "CON",  "LST", or  "AUX" will cause no problems.  CONCAT
  318. checks for a valid file specification  before it  considers the possibility of
  319. redirected input or output.   Remembering that should explain why  an "invalid
  320. directory" message will be issued if  "CON:MYFILE"  is on the command line and
  321. there is no CON directory.  Or the message might say "missing source filename"
  322. if CONCAT finds a console input specification misspelled "COM:".
  323. :4
  324.  Error Codes - 1/2 
  325.  
  326.    If an error occurs,  such as a source file not found, the incomplete output
  327. file is erased (except in  append  mode)  and the  ZCPR3 program error flag is
  328. set.  The error flag values are set as follows:
  329.  
  330.       2 = invalid directory specification
  331.       8 = ambiguous or missing filename (output or source)
  332.      10 = source or target file not found
  333.      11 = disk or directory full (write error)
  334.      12 = insufficient memory
  335.      19 = invalid command line option
  336.     FFh = user abort (optional)
  337.       4 = all other errors
  338.  
  339.    An error also causes CONCAT to invoke the error handler, if one is running.
  340. These same codes are passed to the error handler.
  341.  Error Codes - 2/2 
  342.  
  343.    For safety reasons invalid  options  are  considered  errors.   Using the D
  344. option without a  resident  clock  also  yields an error.   Error messages are
  345. displayed without regard for quiet mode.
  346.  
  347.    Whether a user abort (via ^C,  etc.)  generates an  error is a configurable
  348. option.   Invoking the error  handler  after  aborting  CONCAT  can  be useful
  349. because it will allow cancelling any  active  SUB  or ZEX batch job,  but some
  350. people may not want the minor inconvenience of having to  also abort the error
  351. handler.
  352. :5
  353.  Configuration 
  354.  
  355.    Using ZCNFG and the  accompanying  CONCATnn.CFG file, several configuration
  356. options can be set to your liking.   (Do  not change the name of the CFG file,
  357. so that ZCNFG can  always  find  it,  even if you  change  the  name of CONCAT
  358. itself.)
  359.  
  360.    The configuration options include  setting  several  defaults:  verbose  or
  361. quiet operation,  concatenation  or  append  operating  mode,  text  or object
  362. (binary) file mode, checking for adequate disk space or not,  transferring the
  363. file date stamp or not, etc.  American or European date format and military or
  364. civilian time for the  D  option can also be  set,  along  with  several other
  365. parameters.   In addition,  the date prefix and suffix strings and the default
  366. divider string can be changed.
  367.  
  368.    Full details for the  configuration  options  are  given  on the ZCNFG help
  369. screens.
  370. :6
  371.  CONCAT Notes - 1/3 
  372.  
  373.    a. Vs 1.6 updates (11/11/91, Gene Pizzetta):
  374.       - A few hours after release of 1.5,  I discovered  that redirected input
  375.         produced an error if space checking was on and  CON:  or  AUX: was the
  376.         only input specification.  Such is life; it has been fixed.
  377.       - In addition, entering control  characters  during  console input could
  378.         cause strange things to happen to the screen.   Console input echo now
  379.         uses CCOUT which displays control characters them as "^c",  except for
  380.         carriage return,  linefeed,  backspace,  bell,  and null.   Redirected
  381.         console output is not automatically filtered.
  382.  
  383.    b. Vs 1.5 updates (11/7/91, Gene Pizzetta):
  384.       - Many changes.  Now accepts  "CON:",  "LST:",  or  "AUX:" in place of a
  385.         destination file for redirected output to console, printer,  or auxil-
  386.         iary device (punch).  
  387.       - Output to console and  printer can be  paged  by  using  the  new  "P"
  388.         command line option.  
  389.       - Also accepts "CON:" and  "AUX:" in place of a source file for redirec-
  390.         ted input from console or auxiliary device (reader).  Redirected input
  391.         must end with a ^Z.  
  392.  CONCAT Notes - 2/3 
  393.  
  394.       - Can be configured to output  a  line  feed after every carriage return
  395.         during CON: input.  
  396.       - New "H" option causes high  bits to be reset and control characters to
  397.         be removed from the output stream.  
  398.       - Option I changed so it does  not  have  to  be  at end of option list:
  399.         first character after the I is taken to be a  delimiter and the string
  400.         ends when a second occurrence  of the delimiter is found or at the end
  401.         of the command line.  The delimiter must be non-alphanumeric.  
  402.       - Several new, more specific error messages.  
  403.       - User abort with  ^C  can  be  configured to set the error flag or not.
  404.       - Date/time prefix and suffix  strings  (option D)  and  divider  string
  405.         (option I) can now be configured with ZCNFG.
  406.       - Replaced VLIB routines with ZSLIB HV routines to save space. 
  407.       - Made several code  changes  and  deletions,  and added some additional 
  408.         library routines to improve efficiency.  
  409.       - Now aborts with ^C, ^K, or ^X,  or their upper- or lower-case counter-
  410.         parts.
  411.  CONCAT Notes - 3/3  
  412.  
  413.    c. Vs 1.4 updates (5/28/91, Gene Pizzetta):
  414.       - Bug Fix:   For want of an "OR A", the European date for the  D  option
  415.         did not work.  It does now.
  416.  
  417.    d. Vs 1.3 updates (2/23/91, Gene Pizzetta(:
  418.       - Bug Fix:  Option I was also toggling option F (a missing RET).  
  419.       - Bug fix:  The file date stamp was not being written properly for files
  420.         larger than one  physical  extent  (FCB is  now  being  re-initialized
  421.         before writing stamp).  
  422.       - Option I now accepts divider string on  command  line, using  standard
  423.         ECHO-type escape sequences.   Option  I  MUST be the last command line
  424.         option given!
  425.  
  426.    c. Vs 1.2 updates (2/11/91, Bruce Morgen):
  427.       - Uses the CPR parser whenever possible to further enhance invalid  dir-
  428.         ectory reporting, otherwise use ZPRSFN as in Version 1.1.  New routine
  429.         is at Zparse:.  
  430.       - Fixed a string at JUL: that befuddled poor old M80.  
  431.       - Did some not-terribly-significant code tweaks.
  432.