NAME

SRB - Perl extension for using SRB.

SYNOPSIS

        use SRB;
        
        $srb = SRB->new();
        $srblogin = $srb->login();
        if($srblogin){
                @results = $srb->funcname(paramname=>$paramvalue);      
        }else{
                print "Error could not log in";
        }

DESCRIPTION

        Contains subroutines for logging into srb and running SRB commands

EXAMPLES

        use SRB;
        
        $srb = SRB->new();
        $srblogin = $srb->login();
        if($srblogin){
                #File Listing
                my @ls_res = srb->ls(dir=>'/home')
                #Cat file
                my @cat_res = $srb->cat(file=>'/home/test.txt');
        }else{
                print "Error could not log in";
        }

SEE ALSO

Cog::lib::Cog::Globus::Job, Cog::lib::Cog::Globus::RSL, Cog::lib::Cog::Globus::Run, Cog::lib::Cog::Globus::URLCopy, Cog::lib::Cog::MDS::Search, Cog::lib::Cog::Security::Cacl, Cog::lib::Cog::Security::Myproxy, Cog::lib::Cog::Security::Proxy, Cog::src::Config, CogUtil::lib::CogUtil::Log, CogUtil::lib::CogUtil::UnixRun, Gridport::lib::Gridport::Authentication, Gridport::lib::Gridport::FileTransfer, Gridport::lib::Gridport::Job, Gridport::lib::Gridport::ProxyForward, Gridport::lib::Gridport::SRB, NWS::lib::NWS, SRB::lib::SRB

AUTHOR

        Cathie Mills, cmills@sdsc.edu
        Maytal Dahan, maytal@tacc.utexas.edu
        Stephen Mock, mock@sdsc.edu

SUBROUTINES

new

Description: Initializes SRB error string and returns SRB object

Parameters: None

Usage:
$srb = SRB->new();

Returns: SRB object

login

Description: Logs the user in to SRB. It searches to make sure the environment variables are set or passed in and verifies login by running a SRB command

Description:
searches for the envs
logs the user into srb
verifies login

Parameters: Values may be set as environment variables or you can pass in the environment variables as key value pairs to the subroutine.

 These are the environment variables that must be set
 in order to be logged in to SRB:
                X509_USER_PROXY 
                mdasDomainName 
                srbUser 
                srbHost 
                mdasDomainHome 
                AUTH_SCHEME 
                SERVER_DN 
                GLOBUS_INSTALL_PATH 
                srbPort 
                srbHomeDir

Usage:
$log_stat = SRB->login();
$log_stat = SRB->login(srbUser=>``sampleuser'');
$log_stat = SRB->login(srbUser=>``sampleuser'',srbHost=>``host'');
Any combonation of parameters may be sent as envs or params, but the
params will override the envs if a var is sent both ways.

Returns: 1 if login successful
0 if unsuccessful and sets error string so call get_error(); to get the error that occured in login.

createUser (Requires Admin account on MCAT)

Description: Creates a new user on the specified MCAT Parameters: name = username pass = password domain = srb domain type = srb user type adddress = users mailing address phone = users phone email = user's email auth = GSI_AUTH dn = user's dn from certificate Usage:

loadSRBEnvs (INTERNAL)

Description: Searches for the user's env's to make sure they are set. Parameters: none Usage: internal use only $self->loadSRBEnvs Returns: 1 if all the environment variables are set 0 if the user is missing enviroment variables

testSRBlogin (INTERNAL)

Description: Ensures user is logged in, that the user has all the SRB environment variables set. Parameters: None Usage: internal use only $self->testSRBlogin() Returns: 1 if test login successful 0 if test login unsuccessful 


=cut

sub testSRBlogin{

        my $self = shift;
        ### config ##
        my $cmd = $SRB_LOCATION . "/" . "Sls /home";
        my $res = `$cmd 2>&1`;
        my $SRB_ERROR = "";
        my $retval = 1;
        if($? != 0){
                $self->{'error'} = $? . " " . $res;
                $retval = 0;
        }
        if($res =~ /Error acquiring credentials/i){
                $retval = 0;
        }
        return $retval; 
}

ls

Description: Does an ls on the users srb directory. This assumes that the user is already 'logged in' to srb. Can also do recursive ls by passing an additional parameter recursive and can do an ls -l by pasing a long_list equal to 1. Can also list the meta information associated with a file or directory

Examples:

 #ls a directory
 @ls_res = $srb->ls(dir=>'/home')
 #ls -l
 @ls_res = $srb->ls(dir=>'/home', long_list=>'1')
 #recursive ls
 @ls_res = $srb->ls(dir=>'/home',recursive=>'1')
 #recursive ls -l
 @ls_res = $srb->ls(dir=>'/home',recursive=>'1', long_list=>"1")
 #list meta information
 @ls_meta = $srb->ls(meta=>"1",dir=>"/home");

Returns: An array that is the results of the ls

mkdir

Description: makes a directory in the specified location that is passed in.

Parameters: dir - the directory to make

Usage: $srb->mkdir(dir=>'/home/testdir');

Returns: undefined if the mkdir is sucessful or the results of the mkdir.

get

Description: Does a get command to get a file from the source file located in srb and put it in the destination file passed in.

 You can also specify a source_dir and destination dir and it 
 will put the whole source directory from srb in the destination 
 directory.
 You can also specify an overwrite option that will 
 force overwrite the files if they exist in the source directory.
 Now you can call srb_get with wild cards - just make your normal 
 call to srb_get and add the '*' to the path or filename

Parameters: source_file - the file to get dest_file - the destination for the file source_dir - the location of the source directory to get dest_dir - the location to put the directory overwrite - allows to overwrite files

Usage: $srb->get(source_file=>'/home/test.txt',dest_file='/users/us/blah.txt') $srb->get(source_file=>'/home/test.txt',dest_file='/users/us/blah.txt', overwrite=>'1') $srb->get(source_dir=>'/home',dest_dir='/users/test') $srb->get(source_dir=>'/home',dest_dir='/users/test', overwrite=>'1')

Returns: the results of the get command

put

Description: puts the source file in srb in the specified destination directory. Can also make a source file be a * then it will grap all the files in that dir. Also has an overwrite that will do an srb rm it does not handle the use of * in the source file.

Parameters: source file - the file to put in to SRB destination dir - the destination directory in SRB to put the file in. overwrite - if the same file exists in the destination directory the overwrite the old file

Usage: srb->put(source_file=>'test.txt', dest_dir=>'/home'); srb->put(source_file=>'/usr/*', dest_dir=>'/home'); srb->put(source_file=>'/usr/file', dest_dir=>'/home',overwrite=>'1');

Returns: the results of the put

rm

Description: Removes a file or directory in SRB

Parameters: file - the file to remove from SRB OR dir - the directory to remove from SRB

Usage: #Remove a file @rm_res = $srb->rm(file=>'/home/test.txt'); #Remove a directory @rm_res = $srb->rm(dir=>'/home/user/test_dir');

Returns: An array with the results from rm

cat

Description: Does a cat on a file located in srb

Parameters: file - the file to cat

Usage: $srb->cat(file=>'/home/test.txt');

Returns: an array with the file contents or an error string that the file does not exist.

file_exists

Description: checks if a file exists in SRB

Parameters:
file - the file to check for existance

Usage: $srb->file_exists(file=>'/home/test.txt');

Returns: returns a 1 if exists and a 0 if it doesn't exist.

status

Description: Tests if SRB is up

Parameters: None

Usage: $srb->status();

Returns: returns 1 if up or 0 if down or -1 if the user is not logged in.

get_homedir

Description: Gets the users home directory from the SRB environment

Parameters: None 


Usage:
 $srb->get_homedir();

Returns: a string that is the users home dir

dir_exists

Description: Checks if a directory in srb exists

Parameters: dir - the directory to check for existance

Usage: $srb->dir_exists(dir=>'/home');

Returns: 1 if exists and 0 if it doesn't

move

Description: Moves source file to destination

Parameters: src - the source file to move dest - the destination for the file

Usage: @mv_res = $srb->move(src=>'/home/cmills.sdsc/lala',dest=>'/home/cmills.sdsc/dorayme');

Returns: Nothing if successful

chmod

Description: Change the access controls on a dataset or collection

Paramaters: user - that you are changing permissions for domain - your SRB domain eg. sdsc access - Access permits allowed are write (w), read (r), all (a), annotate (t) and none (n) obj - make sure to use the full path

Options: -r grants/changes access permits recursively for collection and sub-collections under it. -d grants/changes access permits for datasets only. -c grants/changes access permits for collections only. -a adds auditing feature for the access permission granted for datasets. auditing works only if the audit_flag is turned on when compiling the MCAT Server.

Usage: @res = $srb->chmod(options=>'', user=>'mdahan',domain=>'sdsc', access=>'a',obj=>'/home/cmills.sdsc/input_test1.txt'); NOTE: It seems like this command can't be used with datasets that are part of containers

Returns: an array that is the chmod results

copy

Description: Copies a file

Parameters: container src dest resource - required for now replica_num pathname

Options: f force copying even if object exists. a force copying all replica of the target object. r copy collections recursively.

Usage:

Returns: an array that is the results from the copy

put_meta

Description: Adds metadata to a specified file or directory

Parameters: file - specify a file to add metadata OR dir - the dir to add metadata attribute - the attribute name of the metadata value - the value of the metadata unit - the unit of the value

Usage:

 #put file 
 @res = $srb->put_meta(file=>'/home/cmills.sdsc/file',attribute=>'length',value=>'15',units=>'cm');
 #put dir
 @res = $srb->put_meta(dir=>'/home/cmills.sdsc/testdir',attribute=>'length',value=>'15',units=>'cm');

Results: an array with the put meta results

rm_meta

Description: remove metadata from a specified file

Parameters: file - specify a file to remove metadata from attribute - the attribute name of the metadata value - the value of the metadata unit - the unit of the value

Usage: @res = $srb->rm_meta(file=>'/home/cmills.sdsc/file',attribute=>'length',value=>'15',units=>'cm');

Returns: an array with the results of the remove metadata command

get_meta

Description: get meta data from the specified file the arguments can be a=attributes v=value or u=units or any combonation of the above to get the files metadata attributes, values and units or any combo of that. NOTE: works only on files

Usage: @res = $srb->get_meta(file=>'/home/cmills.sdsc/filename',arguments=>'avu'); @res = $srb->get_meta(dir=>'/home/cmills.sdsc/filename',arguments=>'avu'); the arguments can be a=attributes v=value or u=units or any combonation of the above. As of now this command works only on files

Returns: An array - each item in the array will contain the data for a specific attribute - the attribute value and unit will be space delimeted and only those requested will be there

getColl

Description:
Get data on a file

Parameter:
There are several options

Usage:
my @results = $srb->getColl(options=>``options'');

getD

Description:
Get data on a file

Parameter:
There are several options

Usage:
my @results = $srb->getD(options=>``options'');

get_error

Description: Get value of error string

Parameters: None

Usage: my $err = $srb->get_error();