SENDFILE - Send one or more files

Syntax:	SENDFILE	[ file name ] [ /options ]
	SENDFILE	[ file name ] [ /as \| /ap ] [ new name ] [ /options ]
Arguments:	[ file name ]	Variable or string defining a file or path name; if no path is defined Robo-FTP’s working folder is used; wildcard characters are permitted in the file name itself (not the path name portion) as long as the file name conforms to the 8.3 file naming convention.
	[ new name ]	Variable or string defining the name for [ file name ] on an FTP site; [ new name ] should be a file name only (no path is allowed); [ new name ] is only permitted immediately following the /as or /ap options.
Options:	/allowerrors	This option prevents SENDFILE from failing when doing a multi-file upload (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 %uploaderrors variable.
	/as	Specify a different file name on the FTP site for the file being sent; this option cannot be used with wildcard characters in [ file name ].
	/ap	Append [ file name ] to [ new name ] on the remote system; if [ new file ] does not exist on the remote site, it is automatically created; this option cannot be used with wildcard characters in either [ file name ] or [ new name ]; nor is the /resume or any of the /if… options permitted to be combined with this option. The /ap option differs from /append in that it requires the [ new name ] argument and allows [ file name ] to be appended to a file of a different name on the remote site.
	/append	Append [ file name ] to a file of the same name on the remote system; if the file does not exist on the remote site, it is automatically created; this option cannot be used with wildcard characters in [ file name ]; nor is the /resume or any of the /if… options permitted to be combined with this option. The /append option differs from /ap in that it does not require the [ new name ] argument and [ file name ] is always appended to a file of the same name on the remote site.
	/archive	Move the file to the designated archive folder after a successful transmission.
	/blocksize=xx	Change the maximum default block size used to read files from disk and the corresponding block size used for passing upload data to the Winsock API. The default value is 32,000 bytes. You may choose to increase or decrease this block size by way of experimentation to modify upload performance. The maximum block size is 819,200 bytes.
	/copydirs	Sends file(s) to a directory on the remote site that corresponds to the local directory path portion of the [ file name ] argument. Remote directories are created if necessary. The destination directory is calculated relative to the current local working directory so this option requires the sent file(s) be located either in the working directory or a subdirectory of the working directory. This option is commonly used when variables like %nextpath or %difffilepath 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.
	/delete	Delete [ file name ] after it has been successfully sent; local folders are not deleted.
	/emptydirs	Normally SENDFILE with the /subdirs will not create directories on the the FTP site if there are no files in a corresponding local folder. You can alter this behavior and allow empty directories to be created by including this option. This option is permitted only with the /subdirs option.
	/flat	Normally SENDFILE with the /subdirs option will duplicate all or part of the local PC folder structure on the FTP site as it transfers files it finds as it traverses local folders and subfolders. Specify this option if you wish all files found on the local PC to be written to the current directory on the FTP site. No new FTP site directories will be created. Beware that files found with duplicate names are overwritten.
	/ifarchive	Only send local file(s) that have the archive (backup) file attribute set. This attribute is reset if the file(s) are sent to the FTP site successfully.
	/iflarger	Do not overwrite the file on the FTP site if it is smaller than, or the same size as, the file being sent from the local PC.
	/ifnewer	Do not overwrite the file on the FTP site if the file date and time is newer than, or the same as, the file being sent from the local PC.
	/ifnotexist	Do not overwrite a file of the same name on the FTP site if it already exists.
	/ifnsamesz	Do not overwrite a file of the same name on the FTP site if it already exists and it is exactly the same size as the file being sent from the local PC.
	/integrity=xx	Use file integrity checking as the files are uploaded (FTP and FTPS servers only).
	/localdate	When saving the server file, change the file’s last modified date to match the date and time of the corresponding local file.
	/lower	Convert file or path name to lower case before saving it on the server.
	/maxrate=xx	Specify the approximate maximum upload rate (in Kbps) to limit the bandwidth used by Robo-FTP when sending 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.
	/nospaces	Replace space characters embedded in local file names with underscore characters before storing the file on the FTP site (for compatibility with FTP sites hosted on Unix servers) (see the /nounderscores option on the RCVFILE command).
	/nostatus	Do not display send file status dialog box.
	/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 resending 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	After sending a local file to the FTP site, change the local file’s last modified date to match the date and time of the corresponding file on the FTP site.
	/skip_changing	Ignore any file if its size is not stable for one second.
	/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 folders beneath the current or specified local folder and send the files therein; the corresponding directory structure is created on the FTP site if it does not exist.
	/timeout=xx	Specifies a communications time-out period in seconds; when xx is 0, there is no time-out.
	/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 saving it on the server.

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

This script command uploads one or more files to an FTP site. Upon completion of the command, the %uploadcount script variable contains the total number of files uploaded and the %uploadsize script variable contains the size in bytes of the most recent file uploaded. If the /allowerrors option is specified, the count of any file I/O errors is recorded in the %uploaderrors variable.

When uploading, the remote site automatically creates a file with the same name as the original. This behavior may be modified. When the /as option is used, the uploaded file is saved using the specified name; when the /ap or /append option is used the uploaded file is appended to an existing file of the same or a different name.

For example, the following command sends a file named “file name” from Robo-FTP’s current working folder to the current directory on the remote site:

The following command sends a file named “file name” from Robo-FTP’s current working folder to the current directory on the remote site and attempts to append it to an existing file on the remote site named “new_file name.”

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

Multiple files may be sent by using wildcard characters (*, ?) in the [ file name ] argument. Local files with the "hidden" or "system" attribute are ignored when SENDFILE searches for wildcard pattern matches. If necessary, execute the DOS attrib.exe command to change file attributes before using a wildcard pattern. Consider the following example in which all the files in a local directory are uploaded to a remote site:

Automatic transmission of multiple files may also be accomplished using the GETNEXTFILE command and a conditional looping structure within a script file.

The /archive option automatically moves a local file to an archive folder defined using the ARCHIVEDIR script command after it has been successfully sent. If a file by the same name exists in the archive folder, it is overwritten. Do not confuse this with the /ifarchive option which is used to send only local file(s) that have the archive (backup) file attribute set.

The /copydirs option modifies the destination archive folder in the same manner that it modifies the destination folder on the remote server.

The /delete option automatically deletes a local file after it has been successfully sent. The /subdirs option may be used to send the entire contents of a local folder and all subfolders, and have a corresponding directory structure reproduced on the FTP site. In the following example, all files with an extension of .html or .htm all subfolders of the current working folder are uploaded to the remote site.

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 a specified folder and all subfolders are uploaded and then deleted after being sent successfully.

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

Relative path names are not permitted in the SENDFILE command when the /subdirs option is present. For example, "c:\My Data\*" is permitted, but "My Data\*" is not.

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

The following example command results in a local file being sent and saved as a different file name on an FTP site.

There are two forms of the SENDFILE command that may be used to append data to a file on an FTP sites (including FTPS and SFTP sites.) The form using the /append option results in a file being appended to a file of the same name on the FTP site. The form using the /ap option may be used to append to a file with different name on the FTP site. If the file does not exist on the FTP site in either case, the file is created. The following examples show both syntax.

The /iflarger, /ifnsamesz, /ifnewer, and /ifnotexist options may be used to control if FTP site files are to be overwritten when sent by Robo-FTP. These options are 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 the server is unable to provide information about the size or last modified time of a given file, or if that functionality is disabled via FTPLOGON's /disable= option, then the /iflarger or /ifnewer options will be ignored, since there is insufficient data to determine if the local file is, in fact, larger or newer than the one on the server. In such a case, the SENDFILE command will send the file regardless of whether the criteria is met.

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:

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:

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:

The /integrity option enables file integrity checking to be used during the upload. 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. The possible algorithms are:

Consider the following example where all files from the current working directory are upload to the server with file integrity checking using the SHA256 algorithm.

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 sent and appended to the incomplete portion currently saved on the FTP site. 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. In this case, the SENDFILE command will fail and set %lasterror to $ERROR_CMD_NOT_SUPPORTED.

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 /nospaces option causes Robo-FTP to convert space characters found in local folder and file names to underscores before creating corresponding directories on the FTP site and when sending files. This resolves an incompatibility in file naming between Windows and Unix (Unix does not allow spaces in file names). For example, the following command would result in a file named my_test_file.txt being stored on the FTP site.

The /lower and /upper options cause Robo-FTP to convert local folder and file name(s) specified by [ file name ] and [ new file ] to lower or upper case, respectively, before creating corresponding directories on the FTP site and when sending files.

The /maxrate option causes Robo-FTP to limit the bandwidth used when uploading 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 an upload 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 an upload to 100Kbps, you’d specify the following command:

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 uploaded. The time of the file will be accurate to the minute (the seconds field is not updated). This option permits more accurate synchronization of local files and their counterparts on the FTP site, but should not be used if the original date/time of the local file 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 uploaded. The time of the file will be accurate to the minute (the seconds field is not updated). 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.

The /blocksize option changes the default read size of the SENDFILE command from 32,000 bytes to the specified value. In the following example, the block size is changed to 64,000 bytes. A higher or lower number may improve throughput performance based on experimentation in your network.

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 carriage return/line feed (DOS line ending) being converted to line feed (Unix 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.

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

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