\begindata{text,538387028}
\textdsversion{12}
\template{help}
\define{global
}
\chapter{Datacat: Concatenate ATK Datastream Files

}
\section{What Datacat is

}\leftindent{
Datacat is a non-interactive application, similar to the Unix 
\italic{\helptopic{cat}} program, specially designed to concatenate ATK 
datastream files.  \italic{cat }cannot be used to concatenate ATK files; 
you must use datacat.  A new feature of datacat is the ability to make use 
of master files that include the names of other files to be included in 
datacat's output. You can also use datacat to "clean up" ATK files that 
have been improperly assembled (using \italic{cat}, for example.)


}
\section{How Datacat works


}\leftindent{Datacat takes a list of one or more files and concatenates 
them by creating a text object and then inserting the contents of the named 
files into it.  If the named files are text, then their contents are simply 
concatenated, and if the files contain insets/objects other than text, then 
those insets will be added into the text as subobjects.  Newlines are added 
between files if they do not already exist.

}

\section{Using Datacat

}\leftindent{
To concatenate two or more files, type the command "datacat" followed by 
the names of the files you want to concatenate, using spaces to separate 
the filenames:


\typewriter{datacat\italic{ file1 file2 . . .}}


The output will go to the standard output. If not diverted, the raw 
datastream will appear in the command window.



To concatenate two or more files into one file, type:


\typewriter{datacat -o \italic{outputFile file1 file2} . . .}


where\italic{ outputFile} is the name of the file that will contain the 
concatenated files.

It is safe to make \italic{outputFile} the same as one of the input files; 
\italic{outputFile} will not be overwritten until all of the input files 
are read in.


Datacat has a \bold{-q} (quiet) flag, that tells it to run quietly without 
printing the ATK version message. This should be useful to those who write 
shell scripts that call datacat. There is also a \bold{-v} (verbose) flag 
that causes datacat to report on the files as it concatenates them.


}
\section{Including Other Files}


\leftindent{When given the \bold{-i} flag, datacat will search through the 
files it is passed for lines of the form


@include(filename)


}\leftindent{Datacat \bold{-i} will interpret all of the instances of this 
and include the named files in its output.  The included filename can be 
either an absolute name that begins with the '/' character or a filename 
relative to the current file being processed.  For example, an include line 
can have one of these forms:


@include(../../foo/bar.d)

@include(/etc/motd)

@include(foo/bar/bar.d)


The \bold{-I} flag does the same as the \bold{-i} flag, except that it will 
also look for @include lines in the included files themselves.


}
\section{Cleaning Up Files}


\leftindent{The \bold{-c} flag causes datacat to "clean" each file as it 
reads it. If the file is a normal text file or a valid ATK datastream file, 
this has no effect. However, if the file contains two or more ATK objects 
illegally stuck together, or has ATK objects that are placed after or 
between sections of normal text, datacat will sort them out and concatenate 
them properly in the output.


This is especially helpful for files that have been created by the "Append 
to File" menu option in Messages. Such files are in an odd format, 
particularly if they contain multiple messages, and are difficult to edit. 
Datacat \bold{-c} can read these files and output normal ATK text files.


When given the \bold{-c} switch, datacat can act as a filter, reading from 
standard input. To do this, use - as one of the filenames after the 
\bold{-c} switch. For example, you could concatenate several ATK files in a 
directory using the command


\typewriter{cat infile* | datacat -c - > outputfile}


Using cat on ATK files would normally be bad, but in this case, datacat 
will clean up the input stream and send a valid ATK file to outputfile.



}\section{Quick Reference}

\leftindent{
\typewriter{datacat [ -q ] [ -v ] [ -i ] [ -I ] [ -c ] [ -o 
\italic{outputfile} ] [ [-] \italic{file1 file2 file3 ... }]}


-q : Quiet operation

-v : Verbose operation

-i : Include files listed in @include() statements

-I : Include files recursively

-c : Clean up input files

-o : Send output to \italic{outputfile}

\italic{file1, file2, file3....} : List of files to read in

- : Read from standard input (must use -c switch)


}\section{Program Author}

\leftindent{
Tom Neuendorffer}


\section{Related tools}  \



\leftindent{Select (highlight) one of the italicized names and choose "Show 
Help on Selected Word" from the pop-up menu to see the help file for:


\italic{\helptopic{cat}

\helptopic{text}

\helptopic{insets}


}For more information on ATK datastream, see the ATK Programmer's Manual 
chapter on the class\italic{ dataobject.}}


\begindata{bp,538210560}
\enddata{bp,538210560}
\view{bpv,538210560,0,0,0}
Copyright 1992 Carnegie Mellon University and IBM.  All rights reserved.

\smaller{\smaller{$Disclaimer: 

Permission to use, copy, modify, and distribute this software and its 

documentation for any purpose is hereby granted without fee, 

provided that the above copyright notice appear in all copies and that 

both that copyright notice, this permission notice, and the following 

disclaimer appear in supporting documentation, and that the names of 

IBM, Carnegie Mellon University, and other copyright holders, not be 

used in advertising or publicity pertaining to distribution of the software 

without specific, written prior permission.



IBM, CARNEGIE MELLON UNIVERSITY, AND THE OTHER COPYRIGHT HOLDERS 

DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING 

ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS.  IN NO EVENT 

SHALL IBM, CARNEGIE MELLON UNIVERSITY, OR ANY OTHER COPYRIGHT HOLDER 

BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY 

DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, 

WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS 

ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE 

OF THIS SOFTWARE.

 $

}}\enddata{text,538387028}
