\HeaderA{convertCdf}{Converts a CDF into the same CDF but with another format}{convertCdf}
\keyword{file}{convertCdf}
\keyword{IO}{convertCdf}
\begin{Description}\relax
Converts a CDF into the same CDF but with another format.
Currently only CDF files in version 4 (binary/XDA) can be written.
However, any input format is recognized.
\end{Description}
\begin{Usage}
\begin{verbatim}convertCdf(filename, outFilename, version="4", force=FALSE, ..., .validate=TRUE, verbose=FALSE)\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{filename}] The pathname of the original CDF file.
\item[\code{outFilename}] The pathname of the destination CDF file.
If the same as the source file, an exception is thrown.
\item[\code{version}] The version of the output file format.
\item[\code{force}] If \code{\LinkA{FALSE}{FALSE}}, and the version of the orignal CDF is the
same as the output version, the new CDF will not be generated,
otherwise it will.
\item[\code{...}] Not used.
\item[\code{.validate}] If \code{\LinkA{TRUE}{TRUE}}, a consistency test between the generated
and the original CDF is performed.  Note that the memory overhead
for this can be quite large, because two complete CDF structures
are kept in memory at the same time.
\item[\code{verbose}] If \code{\LinkA{TRUE}{TRUE}}, extra details are written while processing.
\end{ldescription}
\end{Arguments}
\begin{Value}
Returns (invisibly) \code{\LinkA{TRUE}{TRUE}} if a new CDF was generated, otherwise \code{\LinkA{FALSE}{FALSE}}.
\end{Value}
\begin{Section}{Benchmarking of ASCII and binary CDFs}
Binary CDFs are much faster to read than ASCII CDFs.  Here are some
example for reading complete CDFs (the differnce is even larger when
reading CDFs in subsets):
\Itemize{
\item HG-U133A (22283 units): ASCII 11.7s (9.3x), binary 1.20s (1x).
\item Hu6800 (7129 units): ASCII 3.5s (6.1x), binary 0.57s (1x).
}
\end{Section}
\begin{Section}{Confirmed convertions to binary (XDA) CDFs}
The following chip types have been converted using \code{convertCdf()}
and then verified for correctness using \code{compareCdfs()}:
ASCII-to-binary: HG-U133A, Hu6800.
Binary-to-binary: Test3.
\end{Section}
\begin{Author}\relax
Henrik Bengtsson (\url{http://www.braju.com/R/})
\end{Author}
\begin{SeeAlso}\relax
See \code{\LinkA{compareCdfs}{compareCdfs}}() to compare two CDF files.
\code{\LinkA{writeCdf}{writeCdf}}().
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
for (zzz in 0) {

# Find the small 'Test3' CDF file
cdfFile <- findCdf("Test3")
# Find any CDF file
if (is.null(cdfFile))
  cdfFile <- findCdf()
if (is.null(cdfFile))
  break

# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Create an identical CDF structure
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cdfHeader <- readCdfHeader(cdfFile)
outFile <- sprintf("%s-copy.cdf", cdfHeader$chiptype)
convertCdf(cdfFile, outFile, overwrite=TRUE, verbose=TRUE)

# Clean up
rm(cdfFile, pathname, cdfHeader)

} # for (zzz in 0)
\end{ExampleCode}
\end{Examples}

