# FTP2
> [HTML Version](ftp2_sbr.htm)
_Updated January 2024; see History_
**xcall FTP2, host, user, password, localpath, hostfile, hostdir, opcode, status, port, \{,emsg, privkey, passphrase \}**
FTP2 provides the client side of FTP and SFTP file transfers. Similar to, and mostly upward compatible with the now deprecated [FTPDLX](ftpdlx_sbr.htm.md) (see "Migrating..." below), FTP2 offers additional features and support for the latest security patches and protocol updates.
**Parameters**
_host_ ([String](string.htm.md)) \[in\]
Specifies the name or IP address of the host computer you want to send files to or receive files from.
_user_ ([String](string.htm.md)) \[in\]
Specifies the user login name for the remote host. For anonymous FTP, use "anonymous"
_password_ ([String](string.htm.md)) \[in\]
Specifies the login password. For anonymous FTP, use your email address (e.g. myname@mydoman.com). Ignored when the _privkey_ argument is specified.
_localpath_ ([String](string.htm.md)) \[in\]
Native file specification for the local file, whether sending or receiving. If not fully qualified, it will be treated as relative to the current local login directory. For non-wildcard GET operations, it must include the target filename and extension. See Comments below for wildcarding, and [MX\_FSPEC](mx_fspec.htm.md) or the [function ](https://bitbucket.org/microsabio/soslib/src/master/907010/fnfqfs.bsi)[Fn'FQFS\$() in SOSLIB:\[907,10\]](https://bitbucket.org/microsabio/soslib/src/master/907010/fnfqfs.bsi) for converting DevPPN specs to native equivalents.
_hostfile_ ([String](string.htm.md)) \[in\]
May be the full pathspec of the remote file, or just the filename and extension. In the former case, leave _hostdir_ blank, otherwise specify the directory in _hostdir_. _hostfile_ is case sensitive. See _Comments_ below for wildcarding and deletions.
_hostdir_ ([String](string.htm.md)) \[in\]
If not blank, it is prepended to the _hostfile_ field to form the full pathspec of the remote file. _hostdir_ is case sensitive.
_opcode_ ([Num](num.htm.md)) \[in\]
Note that while most of the codes apply to both FTPDLX and FTP2, some apply—as indicated—only to one or the other. Table of Opcodes
| **Symbol ** | **Value** | **Description** |
|------|------|------|
| XFTPF\_GET | \&h00000000 | Transfer from server to client PC. |
| XFTPF\_PUT | \&h00000001 | Transfer from client PC to server. |
| XFTPF\_ASCII | \&h00000002 | ASCII transfer mode. Note that some FTP servers will ignore the ASCII option as a security precaution. |
| XFTPF\_NOERRMSG | \&h00000010 | Suppress error dialogs. |
| XFTPF\_PASSIVE | \&h00000020 | Passive transfer mode. This is often needed to get past firewall restrictions. |
| XFTPF\_NOBANNER | \&h00000040 | Suppress the transfer banner. |
| XFTPF\_SFTP | \&h00000100 | Use SFTP protocol instead of FTP. This requires a SSH2 service on the server side, typically at port 22. |
| XFTPF\_VERSION2 | \&h00001000 | Request FTP2. Automatically set. |
| XFTPF\_KEEPOPEN | \&h00002000 | Keep connection open. |
| XFTPF\_REUSE | \&h00004000 | Reuse previous connection if available. |
| XFTPF\_CLOSE | \&h00008000 | Close connection, no transfer. |
| XFTPF\_RMVEXT | \&h00000200 | Rename host file after transfer, removing the last extension. This may be useful to prevent the file from being accessed by the remote system until the transfer is complete. Since it removes the last extension, you probably want to set the host file to have two extensions, such as myfile.dat.up. After the transfer is complete, the file would be renamed to myfile.dat. |
| XFTPF\_DEL | \&h00100000 | Remote delete. |
| XFTPF\_RECURSE | \&h00200000 | Recurse subdirectories, with wildcards. |
| [XFTPF\_DIR](xftpf_dir.htm.md) | \&h00400000 | Output directory listing of remote directory into _localpath_. |
| [XFTPF\_RENAME](xftpf_rename.htm.md) | \&h00800000 | rename a remote file or directory |
| | | **The following are mutually exclusive (SFTP only); M=missing, N=newer, S=size.** |
| XFTPF\_SYNC\_ALL | \&h00000000 | All matching files. |
| XFTPF\_SYNC\_M | \&h01000000 | All files that don't exist in destination. |
| XFTPF\_SYNC\_MN | \&h02000000 | All files that don't exist in destination, or are newer in source. |
| XFTPF\_SYNC\_N | \&h03000000 | Only files that exist in both places but are newer in source. |
| XFTPF\_SYNC\_MS | \&h04000000 | All files that don't exist in destination or are different size. |
| XFTPF\_SYNC\_MNS | \&h05000000 | All files that don't exist in destination or are different size or newer. |
| XFTPF\_SYNC\_DELM | \&h0F000000 | With XFTPF\_DEL, only remote files not existing locally. |
| | | **This data was extracted from the definition file [ashell.def](ashell_def.htm.md)** |
_status_ (F,6) \[out\]
Return status. Greater than zero indicates success. In some cases, primarily wildcard operations with SFTP protocol, _status_ will return the number of files actually transferred or deleted. Negative values indicate errors as shown in the [ASHNET Status Codes](ashnetstatuscodes.htm.md).
_port_ ([Num](num.htm.md)) \[in\]
Specifies the control port to use when connecting to the remote FTP/SFTP server. The most typical ports are 21 for FTP and 22 for SFTP, but servers are free to change them for various security and firewall-related reasons. In any case the parameter must be explicitly set.
_emsg_ ([String](string.htm.md)) \[out\]
Will contain a debug trace in the case of an error. Since this can be lengthy, you should provide a string of at least 1500 bytes (or S,0) to contain it all. In the case of wildcard transfers or deletions using the SFTP protocol, on success it will contain a list of the files actually transferred or deleted.
_privkey_ ([String](string.htm.md)) \[in\])
contains the filespec of private key file in OpenSSH format. If specified and non-blank, FTPDLX will use public/private key authentication rather than standard password authentication.
_passphrase _([String](string.htm.md)) \[in\]
is the passphrase for the private key. May be omitted if the private key is not passphrase-protected.
**Comments**
The source file specification—in _localpath _or _hostfile_, depending on the direction of the transfer—may contain the "\*" wildcard. For example, /vm/miame/dsk0/007006/\*.dat, or /vm/miame/dsk0/007006/ab\*, or even c:\\vm\\miame\\dsk0\\007006\\cyxz\*.d\*.
When receiving files using a wildcard _hostfile_ specification, _localpath_ should be set to the base directory to receive the files. Setting _localpath_ to "" will result in them being received into the local root directory, which will likely fail due to permissions.
FTP2 is used in ZTXFER and ATSYNC if the /2 switch is specified.
The XFTPF\_SYNC _opcode_ options apply only to the SFTP protocol (XTFPF\_SFTP), and only come into play when a wildcard is specified in the relevant source argument and the destination is just a directory. The wildcard source argument acts as the first level of filtering on files to be transferred, with further filtering determined by the XFTPF\_SYNC\_xxx options.
Note that unlike most of the XFTPF\_xxx flags, which are coded as unique bits and thus could theoretically be combined in any way, provided it makes functional sense, the XFTPF\_SYNC\_xxx options are all mutually exclusive—i.e., choose only one. Also note that XFTPF\_SYNC\_DELM only applies in conjunction with XFTPF\_DEL.
When doing wildcard transfers or remote deletions, the status parameter returns on success the number of files transferred or deleted, rather than just zero. Also, the _emsg_ parameter in that case will contain a list of the files transferred or deleted, delimited by line breaks. See History notes below related to XFTPF\_DEL.
**Debugging**
In most cases, FTP2 will create a log file in the %TEMP% (Windows) or /tmp (Linux) directories named ashnet.log which may contain useful details. The same detailed error log information will be returned in _emsg_ on any error.
**Migrating from FTPDLX**
For the most part you can just change the name of the XCALL routine from FTPDLX to FTP2, but there are a few differences to watch out for:
• For non-wildcard transfers, FTP2 requires a complete filespec in _localpath, _including the filename and extension, whereas FTPDLX accepts a directory and will copy the filename from the source.
• FTP2 error messages are more like complete logs rather than the mere messages returned by FTPDLX. You may therefore need to increase the size of _emsg_ and possibly adjust the way you display or otherwise handle them.
• FTP2 ignores the debug flag (XFTPF\_DEBUG or \&h0080) and always writes error debugging information to the ashnet.log file (see Debugging) and to the _emsg_ parameter.
**See Also **
• [FTPDLX](ftpdlx_sbr.htm.md) (deprecated)
• Program [FTPTST in SOSLIB:\[907,33\]](https://bitbucket.org/microsabio/soslib/src/master/907033/ftptst.bp)
• [AG\_FTP](ag_ftp.htm.md); includes discussion of other file transfer alternatives
**History**
2024 January, A-Shell 7.0.1753: The GET operation now manually replicates the file.ext from the _hostfile_ parameter if the _localpath_ parameter doesn't contain one, eliminating one obstacle to switching from FTPDLX to FTP2. In most cases, the file.ext defaulting is handled by the FTP/SFTP service anyway, but there are scenarios, particularly with SFTP, where FTP2 was failing due to lack of an explicit file.ext in _localpath_.
FTP2TIMEOUT environment variable now affects SFTP as well as FTP connections. Also, XFTPF\_RMVEXT support added.
2021 December, A-Shell 6.5.1709, ASHNET 1.14.177: FTP2TIMEOUT environment variable now affects SFTP as well as FTP connections. Also, XFTPF\_RMVEXT support added.
2021 June, A-Shell 6.5.1703, ASHNET 1.4.174: XFTPF\_DEL now supports a complete filespec in _hostfile. _Previously it required the directory and filename to be split into _hostdir_ and _hostfile_.
2019 June, A-Shell 6.5.1662: Add opcodes [XFTPF\_DIR](xftpf_dir.htm.md) and [XFTPF\_RENAME](xftpf_rename.htm.md).
2017 February, A-Shell 6.3.1544: FTP2 now exposed to Linux via libashnet.so.1.9.157. Wildcards are now supported in the SFTP protocol; previously they were only supported for the FTP protocol. New _opcode_ options added.
2015 April, A-Shell 6.1.1406: Added FTP/SFTP remote delete.
2015 March, A-Shell 6.1.1405, [ASHNET](ashnet.htm.md) 1.7.147: you can now override the default timeout for FTP2 (60 seconds) by defining the environment variable FTP2TIMEOUT as the desired timeout in seconds, e.g. .SETENV FTP2TIMEOUT=10. Note that this is implemented entirely in [ASHNET](ashnet.htm.md).
2014 February, A-Shell 6.1.1379: Added routine to A-Shell.