RCVFILE - Receive one or more files

Syntax:	RCVFILE	[ file name ] [ /options ]
	RCVFILE	[ file name ] /as [ new name ] [ /options ]
Arguments:	[ file name ]	Optional variable or string defining a local file or path name where the file received is written; if no path is defined Robo-FTP’s working folder is used or when the /as option is specified. Wildcards are not permitted when connected to a HTTP/HTTTPS site.
	[ 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.
	/as	This option specifies a different file name on the local system for the file being received.
	/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.
	/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.
	/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.
	/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	Same as /resume except the file transfer will restart from the beginning automatically if Robo-FTP determines that a broken transfer cannot be resumed from the point of failure. This option cannot be used with any of the overwrite control options (e.g., /iflarger, /ifnotexist).
	/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.
	/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 already exist; [ file name ] must be either the * or . wildcard pattern in order to descend into subdirectories on an FTP site.
	/timeout=xx	Time-out in seconds to wait for a receive file operation to start; if xx is 0, Robo-FTP waits indefinitely.
	/type=xx	The type of FTP file transfer to perform: ASCII, BIN, or EBCDIC; if this option is omitted, the default file transfer type set when the FTP site was defined is used; if the FTP site has not been previously defined, type BIN is used.

When connecting to a HTTP/HTTPS site, only the following options are valid with the RCVFILE command: /allowerrors, /as, /delete, /lower, /nounderscores, /timeout=xx, /upper

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.

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:

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.

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

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.

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.

If a given FTP site is hosted on a Unix system and the server file was last written to six (6) or more months prior to the current date, the comparison is based on the stored month, day, and year - but the server file time is assumed to be 12:00 AM (since the actual time is not available to Robo-FTP for comparison purposes).

If you are not using the TIMEZONE script command, you may specify the /tz option with the /ifnewer option to account for differences in timezones between Robo-FTP and the FTP site. This is important for accurate file date and time stamp comparisons. For example, if you are using Robo-FTP in the Central U.S. timezone and the FTP site is located in the Eastern U.S. timezone there is a one-hour difference between the file system times of Robo-FTP’s PC and the FTP site. To allow for this in the RCVFILE command with the /ifnewer option, the command would look like the following which indicates that the FTP site is one hour ahead:

Further, if the FTP site is located in the Pacific U.S. timezone 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 command would look like the following which indicates that the FTP site is two hours behind:

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, then these are compared to verify the integrity of the file. If these do not match then an error is returned. (NOTE: Not all servers support this option.) The possible algorithm are:

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

The /resume and /resumeany options implement 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 RCVFILE command fails if /resume is specified, or the entire file is retransmitted if /resumeany is specified.

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.

The /maxrate option is not available with Robo-FTP’s standard FTP mode. To enable this functionality, select AltFTP mode for non-secure FTP transfers, or one of the SFTP or FTPS modes modes for secure transfers. For example, the limit a download to 100Kbps, you’d specify the following command.

The /type option overrides the default set for a given FTP site. EBCDIC file transfer mode is not permitted unless IBM Host Features mode is enabled.

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 in the current FTP site directory and all subdirectories are downloaded.

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.

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.

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.

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.