.\" 
.\" $Id:$
.\"
.TH PQ2 1 "Version 5" "ROOT" 
.\" NAME should be all caps, SECTION should be 1-8, maybe w/ subsection
.\" other parms are allowed: see man(7), man(1)
.SH NAME
pq2 \- The command line interface to a dataset meta-repository based on ROOT files
.SH SYNOPSIS
.B pq2
action
.I "options"
.SH "DESCRIPTION"
This manual page documents briefly the
.BR pq2
program.
.PP
.B pq2
is a
.B ROOT
application providing an interface to a dataset meta-repository based on ROOT files;
the repository can be accessed via the local file
system or a remote file server daemon or a PROOF facility.
.PP
When working with a local or remote file system, \fIpq2\fR instantiates a \fITDataSetManagerFile\fR class
on the specified local or remote directory. Remote access is done via the \fITFile\fR interface, so any
implementation of \fITFile\fR supported by the installation can in principle be used.
When working with PROOF server the \fITProof\fR dataset manager interface is used to access the dataset
repository attached to the PROOF cluster.
.SH ACTIONS
.TP
ls
list compact information about all or a sample dataset.
.TP
ls-files
list compact information about all the files of a given dataset.
.TP
ls-files-server
list the file content of a dataset on a given server or list of servers.
.TP
info-server
display compact information about the datasets on a given server or a set of servers.
.TP
ana-dist
analyse the file distribution of a dataset (or a set of datasets) over the file
servers, either in terms of files or of file sizes. The output is a text file with
the the file movements needed to make the file distribution even in the chosen
metrics to be used in input to pq2-redistribute.
Optionally the internal objects can be saved so that they can be used as starting
point for a subsequent run. Also an histogram and a plot can be saved to visualize
the file distribution.
.TP
put
register one or more datasets.
.TP
rm
remove one or more datasets.
.TP
verify
scan the content one or more datasets.
.TP
cache
display or clear the local cache content.

.SH COMMON OPTIONS
Some of the options listed below have a slight different meaning
depending on the action. Please refer to the man pages of the script interfaces to the actions for more
details (see below).
.TP
\fB-d\fR <\fIdataset\fR>
For all action but \fIput\fR, the dataset to be processed. For listing actions the wildcards '*' is supported.
For action \fIput\fR, \fIdataset\fR is the path to the file with the list of files in the dataset or
directory with the files containing the file lists of the datasets to be registered; in the first case wildcards '*'
can be specified in the file name, i.e. '<dir>/fil*' is ok but '<dir>/*/file' is not.
In all cases the name of the dataset is the name of the file finally used.
.TP
\fB-u\fR <\fIserverurl\fR>
URL of the PROOF master or data server providing the information; for data servers, it must include the directory.
Can also be specified via the environment variables PQ2PROOFURL or PQ2DSSRVURL (see ENVIRONMENT VARIABLES)."
.TP
\fB-o\fR <\fIoptions\fR>
Specify a string of options to be passed to the instance actuatlly performing the action; the exact meaning is action
dependent.
.TP 
\fB-s\fR <\fIservers\fR>
Specify a server or a comma-separated list of servers to be used in the analysis when required by the action.
.TP 
\fB-k\fR
Keep the temporary files created during the analysis under $TMPDIR
.TP 
\fB-v\fR
Verbose mode
.SH OPTIONS for action verify
The options listed below apply only to action 'verify'
.TP
\fB-r\fR <\fIredirector\fR>
Force re-location of the files via the specified redirector; useful after a file redistribution on the same file
server.
.SH OPTIONS for action ana-dist
The options listed below apply only to action 'ana-dist'
.TP
\fB-m\fR <\fImetrics\fR>
Defines the metrics to be used in the distribution analysis. The possibilities supported currently are: 'F' to use
the number of files, and 'S' to use the file size.
.TP
\fB-f\fR <\fIresult file\fR>
Defines the file where to save the result of the analysis; by the default the result is send to the screen.
The output contains one line per each file that needs to be moved with the format 'file source destination' where 'file' is the file name, 'source' is the source server URL and 'destination' is the destination server URL.
.TP
\fB--outfile\fR <\fIoutput file\fR>
Defines the file where to save the output of the analysis in binary form (ROOT file); this output can be used as starting
point for a next run, allowing to run over many datasets in separate steps.
.TP
\fB--infile\fR <\fIinput file\fR>
Defines the ROOT file from where to fetch the output of a previous run (saved with --outfile).
.TP
\fB-i\fR <\fIignored servers\fR>
Specify a server or a comma-separated list of servers to be ignored in the analysis; this allows to exclude, for example,
the redirector.
.TP 
\fB-e\fR <\fIexcluded servers\fR>
Specify a server or a comma-separated list of servers to be excluded from the target servers; this can be used, for example,
to determine the files movements to drain a server.
.TP 
\fB--plot\fR [<\fIplot file\fR>]
Defines the file with the output plot with the original distribution with the server names and the +-10% limits;
the extension (if known) defines the format; the default format is 'png' and the default name 'plot.png'.
The plot can also be obtained directly from a binary output file (saved with '--outfile <outfile>.root') but
just specifying '--infile <outfile>.root --plot'

.SH "ENVIRONMENT VARIABLES"
See \fIsetup-pq2\fR(1).
.SH "SEE ALSO"
\fIsetup-pq2\fR(1), \fIpq2-ls\fR(1), \fIpq2-ls-files\fR(1), \fIpq2-ls-files-server\fR(1),
\fIpq2-info-server\fR(1), \fIpq2-ana-dist\fR(1),
\fIpq2-put\fR(1), \fIpq2-verify\fR(1), \fIpq2-rm\fR(1), \fIpq2-cache\fR(1)
.PP
For more information on the \fBROOT\fR system, please refer to 
.UR http://root.cern.ch/
.I http://root.cern.ch
.UE
.SH "ORIGINAL AUTHORS"
Gerardo Ganis for the ROOT team.
.SH "COPYRIGHT"
This library is free software; you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as
published by the Free Software Foundation; either version 2.1 of the
License, or (at your option) any later version.
.P
This library is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Lesser General Public License for more details.
.P
You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
.SH AUTHOR 
This manual page was originally written by Gerardo Ganis <gerardo.ganis@cern.ch>, for ROOT version 5.