RCVFILE        Receive one or more files

<< Click to Display Table of Contents >>

Navigation:  Robo-FTP User's Guide > Script Programming > Script Commands > All Script Commands >

RCVFILE        Receive one or more files

Syntax:

RCVFILE

[ file name ]  [ /options ]

 

RCVFILE

[ file name ]  /as [ new name ]  [ /options ]

Arguments:

[ file name ]

Robo-FTP will request the specified filename, which must be provided as either a variable or string, from the current remote directory on the server. If you wish to request the file from some location other than the current remote directory, use the /from option. If you would prefer that the downloaded file be assigned a filename that is different from the one on the server, use the /as option.

 

[ new name ]

Variable or string defining the file or path name for the local copy of [ file name] as it is received.

Options:

/allowerrors

This option prevents RCVFILE from failing when doing a multi-file download (i.e., using wildcards) when a local and/or FTP site file I/O error occurs (e.g., a file is read-only or file access is denied). The command continues and the total number of I/O errors are saved in the %downloaderrors variable. This option may not be used together with the /integrity option.

 

/as

This option is used to specify a new name for the downloaded file that is different from the original server-side file name. This option may not be combined with the /ap option.

 

/copydirs

Receives file(s) to a local directory that corresponds to the remote directory path portion of the [ file name ] argument. Local directories are created if necessary. The destination directory is calculated relative to the current remote working directory so this option requires the received file(s) be located either in the remote working directory or a subdirectory thereof. This option is commonly used when variables like %sitepath or %ftpdifffilepath are passed to the [ file name ] argument. This option may not be used with the /flat option. The SYNC command is available to synchronize local and remote folders en mass.

 

/delete

Delete [ file name ] from the FTP site after it has been successfully received; directories are not deleted.

 

/emptydirs

Normally RCVFILE with the /subdirs option will not create empty local folders if there are no files in the corresponding directory on the FTP site. You can alter this behavior and allow empty folders to be created by including this option. This option is permitted only with the /subdirs option.

 

/flat

Normally RCVFILE with the /subdirs option will duplicate all or part of the FTP site directory structure on the local PC as it transfers files it finds as it traverses subdirectories on the FTP site. Specify this option if you wish all files found on the FTP site to be written to the current local working folder . No new local folders will be created. Beware that files found with duplicate names are overwritten.

 

/from

Receives file(s) from the provided remote directory instead of from the current remote working directory. Relative remote directories such as "../" can also be used.

 

/iflarger

Do not overwrite the local file if it is smaller than, or the same size as, the file being received from an FTP site.

 

/ifnewer

Do not overwrite the local file if the file date and time is newer than, or the same as, the file being received from an FTP server.

 

/ifnotexist

Do not overwrite a local file of the same name if it already exists.

 

/ifnsamesz

Do not overwrite a local file of the same name if it already exists and it is exactly the same size as the file on the FTP site.

 

/integrity=xx

Use file integrity checking as the files are downloaded  (FTP and FTPS servers only).  This option may not be used together with the /allowerrors option.

 

/localdate

After downloading the server file, change the server file’s last modified date to match the date and time of the corresponding local file.

 

/lower

Convert file / path name to lower case before locating it on the server for retrieval.

 

/maxrate=xx

Specify the approximate maximum download rate (in Kbps) to limit the bandwidth used by Robo-FTP when receiving file(s). The rate specified here (if non-zero) overrides the default transfer rate that may have been specified when defining a site using the Robo-FTP Configurator.

 

/mirror

Mirrors files by size and date. The destination will be replaced by the source file only if the source file is larger or newer than the destination file.

 

/nostatus

Do not display receive file status dialog box; use of this option may improve file transfer performance.

 

/nounderscores

Replace underscore characters embedded in file names found on the FTP site with space characters before saving the file on the local PC (see /nospaces option on the SENDFILE command).

 

/resume

Attempt to restart a file transfer from the point of interruption; use this option if the transfer of a large file fails and you wish to resume the transfer from the point of interruption rather than retrieving the entire file. This option cannot be used with any of the overwrite control options (e.g., /iflarger, /ifnotexist).

 

/resumeany

This option is deprecated. It is now the same as /resume.

 

/serverdate

When saving the local file, change the file’s last modified date to match the date and time of the corresponding file on the server.

 

/skip_changing

When [ file name ] refers to a single file, this option causes the command to ignore any file if its size is not stable for one second. Otherwise, when [ file name ] contains wildcards and the TMPNAME command is in effect, a directory listing is done prior to any downloads. The size of each individual file matching the wildcard is immediately compared against the stored directory listing, without any one second delay. If the file's size has changed, the file will be skipped.

 

/skip_changing_seconds=xx

Ignore any file if its size is not stable for the specified number of seconds. Values between 1 and 60 are allowed.

 

/subdirs

Descend into all directories beneath current or specified server directory, and retrieve the files therein; the corresponding folder structure is created on the local PC if it does not exist.

 

/timeout=xx

Specifies a communications time-out period in seconds; when xx is 0, there is no time-out. A %datetime value can also be given as an argument instead of a number of seconds.

 

/type=xx

The type of FTP file transfer to perform: ASCII, BIN, or EBCDIC; if this option is omitted type BIN is used unless Robo-FTP is connected to a Managed Site, in which case the site's Default Transfer Mode is used.

 

/tz=xx

Set the number of hours to add or subtract to the timestamp of server files when comparing them to local files with the /ifnewer or /serverdate options. This value is expressed as a positive or negative integer. This option is unnecessary if the remote site supports the /precisetime option of the FTPLOGON command. This option is functionally equivalent to calling the TIMEZONE command so this adjustment persists after the execution of the current line of script. This option is deprecated in favor of the TIMEZONE command.

 

/upper

Convert file / path name to upper case before locating it on the server for retrieval.

 

 

The RCVFILE command requests that specified file(s) be sent by the FTP site to Robo-FTP. Upon completion of the command, the %downloadcount script variable contains the total number of files downloaded and the %downloadsize script variable contains the size in bytes of the most recent file downloaded. If the /allowerrors option is specified, the count of any file I/O errors is recorded in the %downloaderrors variable.

 

When connected to HTTP/HTTPS sites you may encounter situations where the name of a resource on the remote site contains characters that are reserved, unsafe, or otherwise unprintable.  In these situations, web servers allow you to "percent encode" the required character by replacing it with a percent sign and the two digit hexadecimal representation of the character's position in the ASCII character set.

 

The following command requests a file named “file name” be sent from the current FTP site directory to be saved as a file with the same name in Robo-FTP’s working folder:

 

RCVFILE "file name"

 

When relative path names are specified, as in the following command, a file is retrieved from the current FTP site directory and is saved in the local folder specified by the relative path. In the following example, a file named "file name" is downloaded from the FTP site and saved with the same name in a local folder named “localdir” relative to Robo-FTP’s current working folder.

 

RCVFILE "localdir\file name"

 

If you wish to obtain files from a different remote directory, use the FTPCD command to navigate the folders on the site accordingly before issuing the RCVFILE command. For example, the following command requests a file named “file name” be sent from a remote directory named “serverdir” to be saved in Robo-FTP working folder:

 

FTPCD "serverdir"

RCVFILE "filename"

 

If the remote site has no files matching the “file name” argument $ERROR_NO_FILES_FOUND will be returned unless the the “file name” argument contains a wildcard pattern in which case $ERROR_FILE_RCV_ERROR will be returned.

 

The /as option allows you to request a certain file be sent by an FTP site that is saved as a different file name on the local system. Consider the following example.

 

RCVFILE "serverfile" /as "localfile" /type=BIN

 

The /from option allows you to receive a file or files from a provided remote directory, removing the need to call FTPCD beforehand. In the following example, the /from option is used to download a file from "/remote/sub/dir" and places it in "local/sub/dir":

 

RCVFILE "local/sub/dir/file.txt" /from="remote/sub/dir/file.txt"

 

In the example above, we repeat "file.txt" twice. In such a case where the local filename and remote filename are the same, we can use a simpler syntax, specifying only the remote directory to achieve the same result as the previous example (here we assume that file.txt already exists in the remote directory "remote/sub"):

 

RCVFILE "local/sub/dir/file.txt" /from="remote/sub/dir"

 

The /from option cannot be combined with the /subdirs or /as options. However, the /from option can also be used to achieve the same functionality as the /as option in providing a different local filename. In this case, the remote filename must be explicitly stated:

 

RCVFILE "local/sub/dir/localname.txt" /from="remote/sub/dir/file.txt"

 

Wildcards are supported by /from, in which case the wildcard pattern in [ file name ] must exactly match the wildcard pattern passed to /from. Consider this example, where the /from option is used to download all .txt files from a remote directory, placing them in the given local directory:

 

RCVFILE "local/*.txt" /from="remote/sub/dir/*.txt"

 

The /iflarger, /ifnsamesz, /ifnewer, and /ifnotexist options may be used to control the overwriting of local files. These options are all mutually exclusive. When using the /ifnewer option, the determination of the newest file is based on a comparison of the time and date each file was last written to. The file write time comparison is based only on the hour and minute.

 

Important

FTP sites hosted on Unix systems often return dates without times for any files that were last modified six (6) or more months prior to the current date. When connected to this type of FTP site, Robo-FTP assumes 12:00 AM since the actual time is not available for comparison purposes.

 

For the /iflarger, /ifnewer, and other /if... options, when multiple files are specified by a file mask (for example, "*.txt"), and some, but not all, files are successfully transferred, then no error will occur. If no files meet the criteria, then an $ERROR_NO_FILES_FOUND [1053] error will occur. If only a single file is specified for transfer, but the file is not transmitted due to the criteria not being met, then one of the following errors will occur, according to the particular option used:

 

$ERROR Constant Name

Code

Option for which it occurs

$ERROR_LOCAL_FILE_LARGEREQ

1237

/iflarger

$ERROR_LOCAL_FILE_NEWER

1232

/ifnewer

$ERROR_LOCAL_FILE_EXISTS

1238

/ifnotexist

$ERROR_FILES_SAME_SIZE

1234

/ifnsamesz

 

If you are not using the TIMEZONE script command, you may specify the /tz option with the /ifnewer option to account for differences in time zones between Robo-FTP and the remote server. This is important for accurate file date and time stamp comparisons. For example, if you are in the Central U.S. time zone and the remote server is located in the Eastern U.S. time zone then files created at the exact same moment will appear one hour older on the remote server. The syntax for subtracting one hour from the server time is as follows:

 

RCVFILE "serverfile" /ifnewer /tz=-1

 

Further, if the FTP site is located in the Pacific U.S. time zone there is a two-hour difference the other way between the file system times of Robo-FTP’s PC and the FTP site. To allow for this, the following syntax adds two hours to the server time:

 

RCVFILE "serverfile" /ifnewer /tz=+2

 

The /integrity option enables file integrity checking to be used during the download. When using file integrity checking, the checksum is calculated for both the server file and the local file, using the algorithm specified. These checksums are then compared to verify the integrity of the file.  If these do not match then an error is returned.  The /integrity option is only supported by FTP and FTPS servers that support the specified file hashing algorithm, and will not work on SFTP, HTTP, or any other type of server.  This option and the /allowerrors option are mutually exclusive.  The possible algorithms are:

 

none

integrity checking not done

CRC

64-bit hash

MD5

128-bit hash

SHA1

160-bit hash

SHA256

256-bit hash

SHA512

512-bit hash

 

Consider the following example where all files are download from the server with file integrity checking using the SHA256 algorithm.

 

RCVFILE "*" /integrity=SHA256

IFERROR= $ERROR_INTEGRITY_CHECKING_FAILED GOTO integrity_error

IFERROR!= $ERROR_SUCCESS GOTO other_download_error

DASHBOARDMSG "Download completed with no errors"

 

The /resume option implements the FTP restart (or resume) feature. When this option is specified, Robo-FTP assumes that an attempt is being made to resume a broken transfer on the specified file. Robo-FTP attempts to coordinate with the FTP site regarding the size and last modified date of the file to determine if the transfer can be resumed from the point of interruption. If so, only the unsent portion of the file is retrieved and appended to the incomplete portion received previously. If Robo-FTP determines that it is not safe to resume a transfer, the entire file is retransmitted. Not all FTP servers support resuming an interrupted transfer.

 

The /skip_changing and /skip_changing_seconds options are useful when there is a chance that a file being processed by Robo-FTP is also being modified by some other process.

 

The /lower and /upper options cause Robo-FTP to convert directory and/or file name(s)  specified by [ file name ] and [ new file ] to lower or upper case, respectively, before attempting to locate them on the FTP site for retrieval.

 

The /maxrate option causes Robo-FTP to limit the bandwidth used when downloading a file. The value, specified in Kbps, is an upper limit and the actual throughput will be something less than but close to the value specifed (assuming the connection is capable of sustaining a download at roughly the rate specified). This option overrides (if the rate specified is non-zero) any global transfer rate for the given FTP site that may may been specifed when the site was defined using the Robo-FTP Configurator. For example, to limit a download to 100Kbps, you’d specify the following command:

 

RCVFILE "serverfile" /maxrate=100

 

The /type option specifies the type of file transfer to perform. If this option is used while connected to a Managed Site, the specified value overrides the site's Default Transfer Mode. EBCDIC file transfer mode is not permitted unless IBM Host Features mode is enabled and should only be attempted after verifying /type=ascii produces unsatisfactory results with a given site. When connected to an SFTP site, using /type=ascii results in line feed (Unix line ending) being converted to carriage return/line feed (DOS line ending.) This is only useful when the remote system uses Unix-style line endings. The %servertype internal variable may help determine if this option is appropriate for your connection.

 

To receive files from an FTP site where the file name is unknown, or to receive all the files on the FTP site, use wildcards or use the GETSITEFILE command in conjunction with RCVFILE.

 

Use of the /nostatus option may improve file transfer throughput especially if you are receiving many small files and/or there are a large number of files in the FTP site directory. Use of this option suppresses the sending of an FTP LIST command for each file prior to retrieving it which can significantly reduce network traffic. Locally the only affect of using this option is the suppression of the file progress bar and cancel button which appear in the receive file status dialog box.

 

The /delete option automatically deletes the file on the FTP site after it has been successfully retrieved.

 

The /serverdate option instructs Robo-FTP to update the last modified date and time of the local file to match the date and time reported by the FTP site for the corresponding file that was just downloaded. The time of the file will be accurate to the minute (the seconds field is not updated). If the FTP site is hosted on a Unix system, the time saved for the local file is accurate only for files updated on the FTP site within the current year since the file time of older files is not available to Robo-FTP. The date of the last modification is always accurate. This option permits more accurate synchronization of local files and their counterparts on the FTP site, but should not be used if the actual date/time of the local file’s download is signficant.

 

The /localdate option instructs Robo-FTP to update the last modified date and time of the server file to match the date and time of the corresponding local file that was just downloaded. The time of the file will be accurate to the minute (the seconds field is not updated). If the FTP site is hosted on a Unix system, the time saved for the server file is accurate only for files updated on the FTP site within the current year since the file time of older files is not available to Robo-FTP. The date of the last modification is always accurate. This option permits more accurate synchronization of server files and their counterparts on the local machine, but should not be used if the original date/time of the server file is signficant.

 

Using wildcard characters and the /subdirs option, a script may retrieve the entire contents of an FTP site directory and all subdirectories, and have a corresponding folder structure reproduced on the local PC. In the following example, all files with an extension of .xml or .txt in the current FTP site directory and all subdirectories are downloaded.

 

RCVFILE "*.xml|*.txt" /subdirs

 

 

Important

When using the /subdirs option, the [ file name ] argument must be a file mask containing wildcards in order to successfully send files found in subdirectories.

 

 

Consider the following example where all the files in the current FTP site directory and all subdirectories are downloaded and then deleted from the FTP site after a successful transfer.

 

RCVFILE "*" /subdirs /delete

 

Important

For the /subdirs option to perform properly with wildcards, it is important that the contents of the FTP site directory structure not change (i.e., new files added or files deleted) while the RCVFILE command is active.

 

Important

Relative path names are not permitted in the RCVFILE command when the  /subdirs option is present. For example, "*.xml" is permitted, but "Site/*.xml" is not.

 

Important

The success of wildcard matching depends on Robo-FTP's ability to automatically read and understand the directory listings returned by the remote site. Most HTTP/HTTPS sites do not return listings in a supported format and many return no raw directory listings in response to HTTP GET requests based on slash-terminated URLs. Some respond to HEAD requests and are partially compatible. Some supported HTTP listing types like APACHE_DEFAULT include file sizes rounded to the nearest megabyte or kilobyte and are therefore not fully compatible. Contact technical support if you have an urgent need related to a raw directory listing format that is currently unsupported.

 

The /emptydirs and /flat options modify the default behavior of RCVFILE with the /subdirs option. With /emptydirs, empty directories found on the FTP site are not duplicated on the local PC. With /flat, all files found in directories and subdirectories on the FTP site are written to the current local working folder.

 

If the name of a remote file contains illegal filesystem characters (for example: \ / : * ? " < > |), all such characters are replaced by a space character in the name of the local file.

 

After any files have been downloaded, the %downloadfiles internal script variable is automatically populated with the filenames of all such files. The %deletefiles and %ftpdeletefiles variables are also cleared.

 

Note: When the TMPFILE command is active, the files downloaded by this command will have a different name until the transfer process is successfully completed.

 

 

Related command(s): SENDFILE, SYNC, TMPNAME, WORKINGDIR

See also: Using the %sitefile and %sitedir Variables, Using the %downloaderrors and %uploaderrors Variables, Using Wildcards, Using the %downloadfiles and %uploadfiles Variables, Using the %deletefiles and %ftpdeletefiles Variables