Regular Connection Mode
In this mode the source path, or paths, and the destination path are passed to the ascp transfer engine using command line parameters. Therefore the only limit on the number of paths that can be specified in a single transfer is the command line's command limit (varies by OS).
In Regular Connection Mode the interpretation of source and destination mimics the UNIX 'cp' and 'scp' commands. The idea is that the source is copied into the destination if the destination already exists and the source is copied as the destination if the designation does not exist.
One issue with this approach is that you need to know the state of the file system to determine what exactly will happen once you start a transfer. Imagine that you use command cp file1 file2 in a UNIX environment, this command would create a new file called file2. However, if a directory named file2 was present it would create a new file named file1 inside the file2 directory. This is what happens with Regular Connection Mode.
The Create Path Option is available in all Aspera APIs, which will create the destination path if it does not already exist. In Regular Connection Mode with the Create Path Option enabled the destination path is always treated as a directory and created if not present. However, if the Create Path Option is disabled a 'destination directory path does not exist' message would be returned or logged.
When Multiple Source Paths are specified the destination path is always interpreted as a directory and all the source paths are transferred into the destination directory.
Persistent Connection Mode
In this mode no paths are specified on the command line while invoking ascp. However, extra parameters are added to the command line that causes ascp to start and wait for the managing application to provide the source and destination paths. Once ascp is waiting any number of source paths can be given to ascp to transfer. When you are done sending data you must explicitly close the connection.
In Persistent Connection Mode the Regular Connection mode issue is no longer present. If the source is a file the destination path is interpreted as a file and if the source is a directory the destination path is interpreted as a directory. Therefore, if a source is a file and the passed destination already exists as a directory an error will be thrown.
To help visualize this improvement, consider the following example:
src: /tmp/file1, dst: /tmp/file2 - This will create file2 if it does not exist and will overwrite file2 if it does exist (unless overwrite policy specifies otherwise). However, if a directory named file2 exists an error will be thrown.
src: /tmp/dir1, dst: /tmp/dir2 - This will cause an error if a file with name dir2 already exists at the destination.
The Create Path Option is only applied after interpreting the path as explained above. Multiple Paths are allowed, the path handling explained above is applied to each source/destination pair.
Each user on an Aspera server can optionally have a directory in the document root. If used, this user can upload or download from that directory (including subdirectories). If a user has a document root directory, all paths are interpreted to be relative to the document root. For example, if the document root is set to /home/user, the path /myDir/myFile would be interpreted as would be /home/user/myDir/myFile.
Document roots are setup on Aspera Server and Client Side paths are always treated as absolute paths. However, when initiating transfers using Aspera Web Services both the local and remote endpoints are Aspera Servers and document root configuration is available on both ends. You can enforce document root on the transfer initiating end in the Web Services. for more information refer to the <LocalLocation> tag options.