Python API: sam v8_1_5
sam.storeFile()

Just having some fun...
This is the python interface to the command 'sam store'.
Command Description:

Store a file in the Fermi enstore robot (that is, a path in
/pnfs space).

If you are trying to replicate a file in any other location (i.e., in
a location that is not in /pnfs space), use the

   sam request file transfer

command!  The "sam store" command is SPECIFICALLY for putting
files into /pnfs space.

For retrials, or files that have already been declared to
SAM, add the "--resubmit" option.  If the "--resubmit" option
is NOT specified, the file will be declared to SAM before
storage.

The "--sourceFile" option is the path the the file (including
fileName) on the local system.

The "--descriptionFile" option is the path to the metadata
description file on the local machine.  If you are using the
python API, you may pass in the SamDataFile metadata object
directly.

The "--destinationPath" option is the target destination, which
must be a valid SAM location.  If you do not specify a destination,
SAM will choose one for you based upon the metadata you pass.
See the "sam get destination" command for information on the
autodest destination that would be chosen for your metadata.

The "--station" option determines which station's FSS will be
called upon to perform the file transfer.  (The station must be
able to communicate with the local node, of course).

The --temporaryTransferLocation option is a temporary/intermediate
location to transfer the file; This location must be accessible by
SAM station. When used, the file will be transfered to this location
using samcp before SAM transfers the file to final destination.
This is useful when the originating location of the transfer
cannot be accessed by SAM.

If the "--eraseSourceWhenDone" flag is passed, the original file
will be removed when the transfer is completed.

If the "--waitForCompletion" flag is passed, the returned
FileTransferStatus object will contain the status of the
transfer.  If this flag is not passed, the returned status
object will contain a status of "pending", and the user
will need to poll with the "get file transfer status" command
to determine if/when the file transfer completes.


A couple of examples using the PYTHON API:

   from Sam import sam
   from SamFile.SamDataFile import SamDataFile
   import SAM

   # declare and store a file:
   transferRequestId = sam.storeFile(station='myStationName',
                           sourceFile='/tmp/files/for/sam/myFileNameGoesHere.txt',
                           destinationPath='/pnfs/sam/dzero/logfiles/',
                           metadata=SamDataFile(fileName='myFileNameGoesHere.txt',
                                                fileType=SAM.DataFileType_NonPhysicsGeneric,
                                                fileSize='1000Kb',
                                                group='dzero'))

   # store a file that has already been declared to sam;
   #  do not wait for the results;
   #  erase the original when complete
   transferRequestId = sam.storeFile(station='myStationName',
                           sourceFile='/sam/cache/boo/alreadyDeclaredToSam',
                           destinationPath='/pnfs/sam/dzero/important/other/files/',
                           resubmit=1,
                           eraseSourceWhenDone=1)

   # store a file that already exists, and WAIT for the
   #  transfer to complete before returning to the caller
   transferRequestId = sam.storeFile(station='myStationName',
                           sourceFile='/tmp/files/mySamFileAreadyDeclared',
                           destinationPath='/pnfs/sam/dzero/other/stuff',
                           resubmit=1,
                           waitForCompletion=1)


Python Usage:
	from Sam import sam
	result = sam.storeFile(...)

Return value: SamStruct.FileTransferStatus.FileTransferStatus

Arguments are passed as keyword-value pairs, as in:
	 myfunc(arg1='myarg', arg2='anotherarg', d=1)

Argument Keyword Description:
	(*) indicates that this keyword is required
	>>> indicates that either the API object or the CLI equivalent (<<<) is required
====================================================================================================================================
    KEYWORD                    DATA TYPE            DESCRIPTION
------------------------------------------------------------------------------------------------------------------------------------
    c                          SamBoolean           automatically close all servants after each method call
    corbaCallTimeout           int                  time in seconds for CORBA method calls to return before timing out (default: 0; zero implies no timeout)
    d                          SamBoolean           debug mode
<<< descriptionFile            string               metadata description file, if the file must be declared
    destinationPath            string               destination location; must be a valid SAM location in the enstore robot
    eraseSourceWhenDone        SamBoolean           remove the original file when the transfer is complete
    group                      string               OBSOLETE, the group should be listed inside the metadata as of v6_4_0_1
>>> metadata                   SamDataFile          SamDataFile object containing the metadata for the file if it needs to be declared
    minPnfsFileStoreSize       SamSize              reject requests to transfer files smaller than this into enstore
    resubmit                   SamBoolean           indicates that this is a retrial, and the file does NOT need to be declared to SAM
    retryInterval              int                  retry interval base in seconds; will multiply this base times retryCount (default: 5)
    retryJitter                int                  retry jitter, random jitter added to base retry interval times retryCount (default: 5)
    retryMaxCount              int                  number of times to retry CORBA calls for retriable exceptions (default: 25; zero implies no retries)
    s                          SamBoolean           retrySilently mode (do not issue messages to stderr on proxy retries)
(*) sourceFile                 string               path to the file being stored, on the local machine
(*) station                    string               station (fss) which should perform the file transfer
    t                          SamBoolean           time-it mode (print additional info on timings)
    temporaryTransferLocation  string               Temporary (Intermediate) location to transfer the file; must be accessible by SAM station.
    v                          SamBoolean           verbose mode
    waitForCompletion          SamBoolean           wait, polling the FSS, until the file transfer has completed
====================================================================================================================================

Python API-only Keywords:
	'metadata': replaces descriptionFile

Must have at least one of:	
	(descriptionFile, metadata, resubmit) 

Mutually exclusive keywords:	
	(descriptionFile || metadata || resubmit) 

Environment Defaults:
	c = os.environ['SAM_PYAPI_AUTO_CLOSE_SERVANTS']
	corbaCallTimeout = os.environ['SAM_PYAPI_CORBA_CALL_TIMEOUT']
	minPnfsFileStoreSize = os.environ['SAM_MIN_PNFS_FILE_STORE_SIZE']
	retryInterval = os.environ['SAM_PYAPI_RETRY_INTERVAL']
	retryJitter = os.environ['SAM_PYAPI_RETRY_JITTER']
	retryMaxCount = os.environ['SAM_PYAPI_RETRY_MAX_COUNT']
	s = os.environ['SAM_PYAPI_RETRY_SILENTLY']
	station = os.environ['SAM_STATION']



See Also: