'\" t
.\"     Title: pegasus-rc-client
.\"    Author: [see the "Authors" section]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 11/09/2018
.\"    Manual: Pegasus Manual
.\"    Source: Pegasus 4.4.0
.\"  Language: English
.\"
.TH "PEGASUS\-RC\-CLIENT" "1" "11/09/2018" "Pegasus 4\&.4\&.0" "Pegasus Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
pegasus-rc-client \- shell client for replica implementations
.SH "SYNOPSIS"
.sp
.nf
\fBpegasus\-rc\-client\fR [\fB\-D\fR\fIproperty=value\fR[\&...]] [\fB\-V\fR]
                  [\fB\-c\fR \fIfn\fR] [\fB\-p\fR \fIk=v\fR]
                  [[\fB\-f\fR \fIfn\fR]|[\fB\-i\fR|\fB\-d\fR \fIfn\fR]|[\fIcmd\fR [\fIargs\fR]]
.fi
.SH "DESCRIPTION"
.sp
The shell interface to replica catalog implementations is a prototype\&. It determines from various property setting which class implements the replica manager interface, and loads that driver at run\-time\&. Some commands depend on the implementation\&.
.SH "OPTIONS"
.sp
Any option will be displayed with its long options synonym(s)\&.
.PP
\fB\-D\fR\fIproperty=value\fR
.RS 4
The
\fB\-D\fR
option allows an experienced user to override certain properties which influence the program execution, among them the default location of the user\(cqs properties file and the PEGASUS home location\&. One may set several CLI properties by giving this option multiple times\&. The
\fB\-D\fR
option(s) must be the first option on the command line\&. A CLI property take precedence over the properties file property of the same key\&.
.RE
.PP
\fB\-c\fR \fIfn\fR, \fB\-\-conf\fR \fIfn\fR
.RS 4
Path to the property file
.RE
.PP
\fB\-f\fR \fIfn\fR, \fB\-\-file\fR \fIfn\fR
.RS 4
The optional input file argument permits to enter non\-interactive bulk mode\&. If this option is not present, replica manager specific commands should be issued on the command\-line\&. The special filename hyphen (\-) can be used to read from pipes\&.
.sp
Default is to use an interactive interface reading from
\fIstdin\fR\&.
.RE
.PP
\fB\-i\fR \fIfn\fR, \fB\-\-insert\fR \fIfn\fR
.RS 4
The optional input file argument permits insertion of entries from the Replica Catalog in a bulk mode, wherever supported by the underlying implementation\&. This is highly, useful when interfacing with the Globus RLS as the backend, and one wants to inserts millions of entries in it\&.
.sp
Each line in the file denotes one mapping of the format
\fB<lfn> <pfn> [k=v [\&.\&.]]\fR
.RE
.PP
\fB\-d\fR \fIfn\fR, \fB\-\-delete\fR \fIfn\fR
.RS 4
The optional input file argument permits deletion of entries from the Replica Catalog in a bulk mode, wherever supported by the underlying implementation\&. This is highly, useful when interfacing with the Globus RLS as the backend, and one wants to delete millions of entries from it\&.
.sp
Each line in the file denotes one mapping of the format:
\fB<lfn> <pfn> [k=v [\&.\&.]]\fR
.RE
.PP
\fB\-p\fR \fIk=v\fR, \fB\-\-pref\fR \fIk=v\fR
.RS 4
This option may be specified multiple times\&. Each specification populates instance preferences\&. Preferences control the extend of log information, or the output format string to use in listings\&.
.sp
The keys
\fBformat\fR
and
\fBlevel\fR
are recognized as of this writing\&.
.sp
There are no defaults\&.
.RE
.PP
\fIcmd [args]\fR
.RS 4
If not in file\-driven mode, a single command can be specified with its arguments\&.
.sp
Default is to use interactive mode\&.
.RE
.PP
\fB\-V\fR, \fB\-\-version\fR
.RS 4
displays the version of Pegasus you are using\&.
.RE
.SH "RETURN VALUE"
.sp
Regular and planned program terminations will result in an exit code of 0\&. Abnormal termination will result in a non\-zero exit code\&.
.SH "FILES"
.PP
\fB$PEGASUS_HOME/etc/properties\fR
.RS 4
contains the basic properties with all configurable options\&.
.RE
.PP
\fB$HOME/\&.pegasusrc\fR
.RS 4
contains the basic properties with all configurable options\&.
.RE
.PP
\fBpegasus\&.jar\fR
.RS 4
contains all compiled Java bytecode to run the replica manager\&.
.RE
.SH "ENVIRONMENT VARIABLES"
.PP
\fBPEGASUS_HOME\fR
.RS 4
is the suggested base directory of your the execution environment\&.
.RE
.PP
\fBJAVA_HOME\fR
.RS 4
should be set and point to a valid location to start the intended Java virtual machine as
\fI$JAVA_HOME/bin/java\fR\&.
.RE
.PP
\fBCLASSPATH\fR
.RS 4
should be set to contain all necessary files for the execution environment\&. Please make sure that your
\fICLASSPATH\fR
includes pointer to the replica implementation required jar files\&.
.RE
.SH "PROPERTIES"
.sp
The complete branch of properties \fIpegasus\&.catalog\&.replica\fR including itself are interpreted by the prototype\&. While the \fIpegasus\&.catalog\&.replica\fR property itself steers the backend to connect to, any meaning of branched keys is dependent on the backend\&. The same key may have different meanings for different backends\&.
.PP
\fBpegasus\&.catalog\&.replica\fR
.RS 4
determines the name of the implementing class to load at run\-time\&. If the class resides in
\fIorg\&.griphyn\&.common\&.catalog\&.replica\fR
no prefix is required\&. Otherwise, the fully qualified class name must be specified\&.
.RE
.PP
\fBpegasus\&.catalog\&.replica\&.url\fR
.RS 4
is used by the RLS|LRC implementations\&. It determines the RLI / LRC url to use\&.
.RE
.PP
\fBpegasus\&.catalog\&.replica\&.file\fR
.RS 4
is used by the SimpleFile implementation\&. It specifies the path to the file to use as the backend for the catalog\&.
.RE
.PP
\fBpegasus\&.catalog\&.replica\&.db\&.driver\fR
.RS 4
is used by a simple rDBMs implementation\&. The string is the fully\-qualified class name of the JDBC driver used by the RDBMS implementer\&.
.RE
.PP
\fBpegasus\&.catalog\&.replica\&.db\&.url\fR
.RS 4
is the JDBC URL to use to connect to the database\&.
.RE
.PP
\fBpegasus\&.catalog\&.replica\&.db\&.user\fR
.RS 4
is used by a simple rDBMS implementation\&. It constitutes the database user account that contains the
\fIRC_LFN\fR
and
\fIRC_ATTR\fR
tables\&.
.RE
.PP
\fBpegasus\&.catalog\&.replica\&.db\&.password\fR
.RS 4
is used by a simple RDBMS implementation\&. It constitutes the database user account that contains the
\fIRC_LFN\fR
and
\fIRC_ATTR\fR
tables\&.
.RE
.PP
\fBpegasus\&.catalog\&.replica\&.chunk\&.size\fR
.RS 4
is used by
\fBthe pegasus\-rc\-client\fR
for the bulk insert and delete operations\&. The value determines the number of lines that are read in at a time, and worked upon at together\&.
.RE
.SH "COMMANDS"
.sp
The command line tool provides a simplified shell\-wrappable interface to manage a replica catalog backend\&. The commands can either be specified in a file in bulk mode, in a pipe, or as additional arguments to the invocation\&.
.sp
Note that you must escape special characters from the shell\&.
.PP
\fBhelp\fR
.RS 4
displays a small resume of the commands\&.
.RE
.PP
\fBexit\fR, \fBquit\fR
.RS 4
should only be used in interactive mode to exit the interactive mode\&.
.RE
.PP
\fBclear\fR
.RS 4
drops all contents from the backend\&. Use with special care!
.RE
.PP
\fBinsert <lfn> <pfn> [k=v [\&...]]\fR
.RS 4
inserts a given
\fBlfn\fR
and
\fBpfn\fR, and an optional
\fBsite\fR
string into the backend\&. If the site is not specified, a
\fInull\fR
value is inserted for the
\fBsite\fR\&.
.RE
.PP
\fBdelete <lfn> <pfn> [k=v [\&...]]\fR
.RS 4
removes a triple of
\fBlfn\fR,
\fBpfn\fR
and, optionally,
\fBsite\fR
from the replica backend\&. If the site was not specified, all matches of the
\fBlfn\fR
\fBpfn\fR
pairs will be removed, regardless of the
\fBsite\fR\&.
.RE
.PP
\fBlookup <lfn> [<lfn> [\&...]]\fR
.RS 4
retrieves one or more mappings for a given
\fBlfn\fR
from the replica backend\&.
.RE
.PP
\fBremove <lfn> [<lfn> [\&...]]\fR
.RS 4
removes all mappings for each
\fBlfn\fR
from the replica backend\&.
.RE
.PP
\fBlist [lfn <pat>] [pfn <pat>] [<name> <pat>]\fR
.RS 4
obtains all matches from the replica backend\&. If no arguments were specified, all contents of the replica backend are matched\&. You must use the word
\fBlfn\fR,
\fBpfn\fR
or
\fB<name>\fR
before specifying a pattern\&. The pattern is meaningful only to the implementation\&. Thus, a SQL implementation may chose to permit SQL wild\-card characters\&. A memory\-resident service may chose to interpret the pattern as regular expression\&.
.RE
.PP
\fBset [var [value]]\fR
.RS 4
sets an internal variable that controls the behavior of the front\-end\&. With no arguments, all possible behaviors are displayed\&. With one argument, just the matching behavior is listed\&. With two arguments, the matching behavior is set to the value\&.
.RE
.SH "DATABASE SCHEMA"
.sp
The tables are set up as part of the PEGASUS database setup\&. The files concerned with the database have a suffix \fI\-rc\&.sql\fR\&.
.SH "AUTHORS"
.sp
Karan Vahi <vahi at isi dot edu>
.sp
Gaurang Mehta <gmetha at isi dot edu>
.sp
Jens\-S\&. Vöckler <voeckler at isi dot dot edu>
.sp
Pegasus Team \m[blue]\fBhttp://pegasus\&.isi\&.edu/\fR\m[]