% % File: DCOPY.TEX % Author: Bauer % DLM: % \input{read_general:[procedures]sesdfmt.tex} % Latex input file defining \newcommand{\revision} {A} % latest revision letter % (e.g., A, B) % (seldom changes) \newcommand{\version} {1} % latest version % UPDATE THE VERSION EACH TIME THE DOCUMENT IS CHANGED, INCREMENTING BY 1 % STARTING WITH VERSION 1 \newcommand{\runningtitle}{DCOPY (Delete/Copy) Tool} % title for top of page \newcommand{\control} { SCI88122A } % ST ScI control number \newcommand{\modname} {{\bf dcopy.tex}} % file name in library \newcommand{\modlibe} {{\bf read\_tools:[sogs]}} \thispagestyle{empty} % No header or number on first page \markright{\runningtitle \hspace{1.0in} \revision \hspace{0.1in} \version \hspace{0.5in}} \begin{document} \vspace*{1in} \begin{center} {\Large{\bf DCOPY Tool}}\footnote{This is module \modname{} in library \modlibe{}, printed \today} \\ \bigskip \begin{bf} \control \\ \revision\\ \bigskip \end{bf} \author \\ \bigskip \vspace*{2.0in} {\bf Abstract } \\ \bigskip \end{center} % FILL IN AN ABSTRACT % This is an abstract of the whole document. It should never be more than a % few sentences. The {\it DCOPY \/}tool is a modified version of the VMS COPY command that deletes a file in the destination directory before it copies into it. \clearpage % Table of Contents page \tableofcontents % note that you may need to ``LaTeX'' a document twice after editing in order % to structure the table of contents properly. \clearpage \section{Introduction} The {\it DCOPY, \/} or {\it Delete/Copy \/} tool is used to copy one or more files from a source directory to a destination directory. Before it copies the file to the destination directory, it checks for the existence of the file, and if it exists already AND the revision date of the existing file is older than the revision date on the file to be copied, {\it DCOPY \/} deletes the file. This is useful when disk space is tight on the destination device. A VMS DELETE/LOG is executed on the file being deleted so the delete mesage will appear on the terminal (and maybe log file). This MMS-style revision date checking can be easily turned off. Another feature of the {\it DCOPY \/} tool is that it works with logical searchlists. When the source file directory is specfied via a logical name searchlist, {\it only \/} the first version of a file is copied. The VMS COPY command does not handle searchlists in this manner. Read the section ``Logical Searchlist Example'' to see the difference. Once the file to be copied is determined, a VMS COPY/LOG is executed so that the output will appear at the terminal (or log file). \section{Invoking DCOPY} Use the following command to invoke the {\it DCOPY \/} tool: \bigskip \begin{verbatim} $ DCOPY [] \end{verbatim} \bigskip $<$Source-files$>$ is the name of the file to be copied. Wildcards are permmitted and a logical name may precede the filename. $<$Destination-directory$>$ is the name of the directory where files should be copied to, and where already existing files should be deleted from. Logical names are permitted. $<$Any-string-turns-off-date-checking$>$ is an optional third parameter that when specified, tells {\it DCOPY \/} not to perform revision-date checks on files that are going to be deleted on the destination directory. \subsection{DCOPY Command Symbol} The DCOPY symbol must be defined to execute a command procedure as follows: \bigskip \begin{verbatim} $ DCO*PY :== @sogstools:dcopy \end{verbatim} \bigskip in order for the above command description to function properly. \subsection{Examples} Some sample invocations follow: \$ DCOPY any\_dir:*.exe some\_other\_dir: \$ DCOPY file1.txt [-] NO\_DATE\_CHECK \$ DCOPY any\$dinosaur:file\%.txt sys\$login: \$ DCOPY/OUT=DCOPY.LOG any\$dinosaur:file\%.txt sys\$login: NO\_MMS \$ DCOPY file1.txt;1 [-.other\_dir] \clearpage \section{Logical Searchlist Example} Given the following directory/file layout: \begin{verbatim} any$dinosaur:[any_user]file1.txt;5 any$dinosaur:[any_user]file1.txt;4 any$dinosaur:[any_user]file3.txt;1 any$dinosaur:[any_user]file4.txt;3 any$dinosaur:[any_user]file7.txt;3 any$dinosaur:[any_user.dir1]file1.txt;5 any$dinosaur:[any_user.dir1]file2.txt;2 any$dinosaur:[any_user.dir1]file3.txt;1 any$dinosaur:[any_user.dir1.subdir1]file1.txt;6 any$dinosaur:[any_user.dir2]file5.txt;99 any$dinosaur:[any_user.dir2.subdir1]file7.txt;1 \end{verbatim} Given the logical searchlist definition: \begin{verbatim} $ define cop_dir any$dinosaur:[any_user.dir2.subdir1], - any$dinosaur:[any_user], - any$dinosaur:[any_user.dir1], - any$dinosaur:[any_user.dir2], - any$dinosaur:[any_user.dir1.subdir1] \end{verbatim} \clearpage And, given the following commands: \begin{verbatim} $ COPY copy_dir:f*.txt other_dir: $ DCOPY copy_dir:f*.txt other_dir: \end{verbatim} The following files will be copied from the VMS COPY command in the exact order specified: \begin{verbatim} any$dinosaur:[any_user.dir2.subdir1]file7.txt;1 any$dinosaur:[any_user]file1.txt;5 any$dinosaur:[any_user]file3.txt;1 any$dinosaur:[any_user]file4.txt;3 any$dinosaur:[any_user]file7.txt;3 any$dinosaur:[any_user.dir1]file1.txt;5 any$dinosaur:[any_user.dir1]file2.txt;2 any$dinosaur:[any_user.dir1]file3.txt;1 any$dinosaur:[any_user.dir2]file5.txt;99 any$dinosaur:[any_user.dir1.subdir1]file1.txt;6 \end{verbatim} The following files will be copied from the {\it DCOPY \/} command in the exact order specified: \begin{verbatim} any$dinosaur:[any_user.dir2.subdir1]file7.txt;1 any$dinosaur:[any_user]file1.txt;5 any$dinosaur:[any_user]file3.txt;1 any$dinosaur:[any_user]file4.txt;3 any$dinosaur:[any_user.dir1]file2.txt;2 any$dinosaur:[any_user.dir2]file5.txt;99 \end{verbatim} The VMS COPY command copies the first version of a file from any directory and that lower search list directory files will overwrite (with next highest version) the previous copied files. This would probably be a mess for most users. Notice that the {\it DCOPY \/} command handles the searchlist by copying only one version of a file - the first version encountered. This assumes that the logical name searchlist is set up so that the more important directories are first. \section{Restrictions/Limitations} This section lists any restrictions or limitations that the {\it DCOPY \/} tool has: \begin{enumerate} \item Lists of files are not permitted in the $<$Source-files$>$ parameter as is allowed with the VMS COPY command. \item No VMS COPY qualifiers are allowed - i.e. no \$ DCOPY/CONFIRM or \$ DCOPY/NOLOG, etc. However, since the {\it DCOPY \/} software is a DCL command procedure, \$ DCOPY/OUT=$<$some\_file$>$ will work. \item Trying to copy a file onto itself inorder to create the next higher version in the same directory will only cause that file to be deleted before it is copied. \end{enumerate} \end{document}