next up previous contents
Next: bulkCopyAndRegisterFile Up: Management Commands Previous: copyAndRegisterFile   Contents

Command Line Tool

usage: edg-replica-manager copyAndRegisterFile sourceFileName [options]
Copy a file to grid-aware storage and register it in the grid catalog. Upon
successful completion this call returns the GUID of this file that can be
used to retrieve it again.
 -d,--destination-file <file>    The destination file name (SURL) or
                                 destination SE host. If it is not given,
                                 the closeSE is found from the info
                                 services and an automatic file name is
                                 used as an SURL.
 -l,--logical-file-name <file>   The logical file name to register this
                                 file with. Has to start with 'lfn:'. If it
                                 is not given, the only way to find a file
                                 is through the GUID that is returned by
                                 this call.
 -n,--streams <#streams>         The number of parallel streams to use.
                                 Defaults to 8. This only has an effect if
                                 the protocol supports parallel streams.
                                 Currently the only protocol to do so is
                                 gsiftp.
 -p,--protocol <protocol>        The protocol to be used for transfer.
                                 Defaults to gsiftp.
 Arguments:
  sourceFileName        The file to copy and register. It should be a fully
                        qualified URI. Possible schemes are: file, gsiftp,
                        http, https, ftp.

The copyAndRegisterFile call performs the task of copying a file into grid-aware storage and registering the copy in the Replica Catalog as an atomic operation. This is the preferred method to `bring files into the grid'.

The same could be done by issuing copyFile and registerFile in sequence, but since copyFile may not have an SE or SURL as its destination, the user would need to specify a valid transport file name (using gridftp for example) to a location that happens to be the proper location for the file and then register it using registerFile. That is much more error prone and cumbersome than this method.

As a rule, copyFile should be used to copy files around to non-grid aware storage, or to simply copy files out of the grid (i.e. the source may be grid-aware but not the destination).

registerFile should be used to register files that are already in the grid-aware store before it was made grid-aware or to register files that appear there through other means (like new data files). If the files that need to be put into the grid are not yet in their grid-aware location, copyAndRegisterFile is the most robust method to use.

Semantics

copyAndRegisterFile also handles all the possible failures if the registration should fail after the copy has taken place (i.e. the copied file is registered using another name or if that is not possible it is actually removed again). If the destination already exists, the operation fails.

Re-registrations of existing data files are possible by issuing copyFile and registerFile in sequence as specified above, or by copying the file `out' using copyFile and re-registering it again using this method but storing it with a different name. If users really want to do a re-registration resulting in having more than one GUID for the same data (of course not for the same file), it can be done this way but we knowingly make this operation difficult so that people don't have more than one GUID referring to the same data by mistake.

Since only files on Storage Elements may be registered, -destination-file must refer to a Storage Element just like for replicateFile. The difference to replicateFile is that the latter requires the sourceFileName to be a valid grid file descriptor, i.e. either an LFN, GUID or other SURL, while copyAndRegisterFile does explicitly forbid such sources and accepts only non-grid files. For files already in the grid, replicateFile must be used.

The call returns the GUID of the new entry.

Arguments

sourceFileName
The file to be registered. It must be accessible through this name using the specified protocol in the URI. The sourceFileName may be:

Options

destination-file
The physical destination file. destination-file may be specified in three different ways:

logical-file-name
The logical (file) name to be used in the catalog to find the file again. If this option is omitted, only the GUID returned by this call will be available to retrieve the file.

protocol
The protocol to be used. If it is omitted, the default protocol for the given SE is used.

streams
The number of parallel streams to be used for the copy. If omitted, the default is used for the given protocol.

Return value

The call returns 0 on success and -1 on failure. It also prints the GUID that this file was registered with on stdout.

Errors

The call can fail for many reasons. Some of the reasons are:


next up previous contents
Next: bulkCopyAndRegisterFile Up: Management Commands Previous: copyAndRegisterFile   Contents
2004-06-14