*WEB/FTP: Interface with FTP Server

Description

The *web/ftp utility is used to interface with a server that is running an FTP server program. It can be used to send files to, receive files from, delete files from, or get a directory listing from an FTP server.

As of PxPlus 2020, the *web/ftp utility can communicate with an FTP server using any of the following:

• File transfer protocol (FTP)

• Implicit file transfer protocol over SSL/TLS (FTPS)

• Explicit file transfer protocol over SSL/TLS (FTPES)

• Secure file transfer protocol (SFTP)   (Requires the use of Curl Options)

To specify which protocol to use, see Protocol.

An easier way to use secure FTP (SFTP) is to use the *web/sftp utility, which does not require knowing any curl options. See Interface with SFTP Server.

Note:
As of PxPlus 2017, the *web/ftp utility can use curl, the URL data transfer command line tool, which can significantly improve speed. The curl utility is included in the Windows installation of PxPlus. On many UNIX/Linux systems, the curl utility comes with the OS.

On UNIX/Linux systems where you want to use the faster *web/ftp, check that curl is installed and is in the path by running the curl -V command from the Command line.

  •  If the response is curl version information, this confirms that curl is installed and is in the path; therefore, the faster *web/ftp will work.

  •  If the response is an error stating that curl cannot be found, then you need to install it, or if already installed, add the location of curl to the path.

  •  If curl is not found, the *web/ftp utility defaults to the original slower version.

To find and install a version of curl, visit https://curl.haxx.se/download.html.

Formats

1.	CALL "*web/ftp;send", ftpserver$, user$, password$, timeout, files_to_send$, upload_dir$, case$, result$
2.	CALL "*web/ftp;receive", ftpserver$, user$, password$, timeout, files_to_receive$, download_dir$, case$, result$
3.	CALL "*web/ftp;delete", ftpserver$, user$, password$, timeout, files_to_delete$, case$, result$
4.	CALL "*web/ftp;list", ftpserver$, user$, password$, timeout, recursion, result$

(The "*web/ftp;list" command was added in PxPlus 2016 Update 0001.)
(The "*web/ftp;delete" command was added in PxPlus 2018.)

Where:

ftpserver$	(Input) Contains the name of the FTP server. It should be in the form of SERVER;SOCKET. Example: ftp.pvx.com;21 An FTP sub-directory can be appended to the SERVER portion. See Important Note. Important Note: The sub-directory path must URL encode any special URL characters (except for slashes). Example: "ftp.pvx.com/home/myapp/Help"+CVS("?","ASCII:URL") If no socket number is specified, then a default FTP number of 21 is used. Maximum length of ftpserver$ is 128 characters. The communication protocol is determined by which prefix is used with the server URL. See Protocol. Additional curl options can be specified after the server URL. See Curl Options. (TLS support for FTP was added as of PxPlus 2020.)
user$	(Input) Contains the user ID. Maximum length of user$ is 64 characters.
password$	(Input) Contains the user password. Maximum length of password$ is 64 characters.
timeout	(Input) If non-zero, this parameter specifies the timeouts for sending directly to an FTP Server. If zero, the timeout value is set to 60 seconds. (Only values greater than zero have an effect with PxPlus version 4.15 or higher.)
files_to_send$	(Input) List of the files to send to an FTP Server or a pattern matching the files to send to an FTP server. Maximum length of files_to_send$ is 32,000 characters. See Usage Details. Note: files_to_send$ cannot be null.
files_to_receive$	(Input) List of the files to receive from an FTP Server or a pattern matching the files to receive from an FTP server. Maximum length of files_to_receive$ is 32,000 characters. See Usage Details. Note: files_to_receive$ cannot be null.
files_to_delete$	(Input) List of the files to delete from an FTP Server or a pattern matching the files to delete from an FTP server. Maximum length of files_to_delete$ is 32,000 characters. See Usage Details. Note: files_to_delete$ cannot be null. (files_to_delete$ was added in PxPlus 2018.)
upload_dir$	(Input) Contains the path and the directory name on an FTP Server to use to store files. If null, the upload directory is the root directory of the FTP Server.
download_dir$	(Input) Contains the path and the directory name on a client machine to use to store files. If null, the download directory is the working directory of the machine.
case$	(Input) Possible values are: "U" Converts all file and directory names to uppercase "L" Converts all file and directory names to lowercase "" Does not change file and directory names
recursion	(Input) If non-zero, the directory listing returned will include the listing of all sub-directories as well. If zero, the directory listing will only list the current directory.
result$	(Output) If doing a LIST (see Format 4 above), the program loads this variable with the directory list results. If an error is encountered while sending, receiving, deleting or listing files, then the program loads this variable with a textual description of the problem and exits with an error. If one (or more) of the sending/receiving file names is invalid, then all remaining files that can be sent/received will be transferred, and those which cannot be transferred will be returned in the result$ field.

Protocol

The protocol that is used is determined by the prefix of the server URL.

Example:

ftps://files.server.com

If the prefix is omitted, FTP will be used.

Depending on the protocol used, additional curl options may be specified. See Curl Options below.

(TLS support for FTP was added as of PxPlus 2020.)

Curl Options

When using FTPS, FTPES or SFTP, additional curl options may be specified at the end of the server URL (separated with a space). This allows anyone familiar with curl to have more control over communication with the FTP server.

Important Note:

Caution must be used when specifying additional curl options, as they are passed "as is" to curl. Incorrect or conflicting options will cause the utility not to work.

Any of the following curl options may be used:

Curl Option	Description
-k	Allow untrusted certificates or self-signed certificates.
--cacert file_path	Specify custom CA certificate store as opposed to PxPlus-supplied CA certificate store.
--key kep_path	Private key for SSH authentication (SFTP).
--pass passphrase	Passphrase for the private key.

Example:

ftpes://files.server.com -k

This example uses the curl option -k to allow untrusted certificates or self-signed certificates.

(The use of curl options for FTPS, FTPES or SFTP was added as of PxPlus 2020.)

Usage Details

files_to_send$ / files_to_receive$ / files_to_delete$

Wild characters are accepted in file names (unless MSK( ) regular expression pattern matching is enabled):

	?	Any one character
	*	Any number of any characters

Arguments can contain more than one file name. File names should be separated using one of the following: $8A$, $0A$, $0D0A$, or ; (semi-colon).

Note:
If you have a directory or filename that includes one of the wildcard or separator characters, you cannot reference that path directly in the files list, as that character will be interpreted as a wildcard. You need to use MSK( ) mode and escape any special characters.

Example:

If the filename is "Help?", then:

     files_to_send$="Help\?|M"

A number of options may be specified after a file name. Options should be separated from the file name by a | (pipe). Options are:

Transfer Type	A = ASCII mode  B = Binary mode (default)	Ignored in files_to_delete$.
Overwrite (if the file already exists on the FTP Server)	0 = Always overwrite (default) 1 = Never overwrite  2 = Overwrite if the file being sent is newer	Ignored in files_to_delete$.
Recursion	R = Recursion ON  "" = Recursion OFF (default)	In files_to_delete$, only applies to pattern matching. If a directory is specified, it must recursively delete it regardless of this option.
Regular Expression Pattern Matching	M = Enable MSK( ) regular expression pattern matching "" = Wildcard pattern matching (default)

Example:

file_name1|A1;c:\tmp\*.*|B0R;C:\\reports\\report[0-9]+\.(pdf|doc|docx)|2M

In this example, file_name1 will be transferred in ASCII; it will not be transferred if it currently exists. The directory c:\tmp and all files with it will be transferred in binary and will always overwrite any existing file of the same name. It will also recurse through all sub-directories of c:\tmp and transfer all files in every sub-directory. All files in c:\reports that start with the name report, end with a number and have the extension .pdf, .doc or .docx will be transferred as binary and only if newer (if it already exists).

(File list option "M" that allows full MSK pattern matching was added in PxPlus 2016 Update 0001.)

See Also

MSK( ) Scan String for Mask
Interface with SFTP Server