FTPConnect

Syntax

FTPConnect (serveraddr,username,password[,port,errorprotocoltext,secure {Default zero insecure;1 secure;2 use AUTH TLS},verify {Default kTrue}, charset {Default kUniTypeAuto}]) Returns socket

Description

Note: The flag is set according to whether Omnis was able to make a call to this external command.

This Web command is multi-threaded, allowing another thread to execute in the multi-threaded server while it runs. Note that the same socket cannot safely be used concurrently by more than one thread.

FTPConnect establishes a connection to the specified FTP server.

ServerAddr is an Omnis Character field containing the hostname or IP address of the FTP server.

Username is an Omnis Character field containing the user ID with which the command will log on to the server.

Password is an Omnis Character field containing the password for the user ID.

Port is an optional number or service name, which identifies the TCP/IP port of the FTP server. If you omit this parameter or pass an empty value, it defaults to the standard FTP port (21 for non-secure or AUTH TLS secure connections, or 990 for other secure connections). If you use a service name, the lookup for the service will occur locally.

ErrorProtocolText is an optional Omnis Character field parameter, into which FTPGetConnect places the protocol exchange that occurred on the control connection to the FTP server, if an error occurred. Note that you can use the command FTPGetLastStatus to obtain the protocol exchange in the case when a connection is successfully established.

Secure is an optional Boolean* parameter which indicates if a secure connection is required to the server. Pass kTrue for a secure connection, in which case the built-in security technology will be used, so on Windows ‘Secure Channel’ (Schannel) is used, on macOS ‘Secure Transport’ is used, and on Linux OpenSSL is used.

*FTPConnect also supports an alternative secure option, if you pass secure with the value 2, the connection is initially not secure, but after the initial exchange with the server, FTPConnect issues an AUTH TLS FTP command to make the connection secure if the server supports it (see RFC 4217 for details), followed by further commands necessary to set up the secure connection. Authentication occurs after a successful AUTH TLS command.

Note that if you use either of the secure options, all data connections are also secure, and all data transfer uses passive FTP.

AUTH TLS is the standard recommended mechanism for FTPS, and is referred to as explicit FTPS. The other secure form of FTP supported by this command is referred to as implicit FTPS, and is no longer recommended; however, we provide support for implicit FTPS to cater for servers which do not support explicit FTPS.

FTPS resumes the TLS session for data connections. In addition, it automatically sends PBSZ and PROT commands to the server after establishing a secure control connection.

Verify is an optional Boolean parameter which is only significant when Secure is not kFalse. When Verify is kTrue, the command instructs the installed SSL library to verify the server's identity using its certificate; if the verification fails, then the connection will not be established. You can pass Verify as kFalse, to turn off this verification; in this case, the connection will still be encrypted, but there is a chance the server is an impostor. In order to perform the verification, the installed SSL library uses the Certificate Authority Certificates in the cacerts sub-folder of the secure folder in the Omnis folder. If you use your own Certificate Authority to self-sign certificates, you can place its certificate in the cacerts folder, and the installed SSL library will use it after you restart Omnis.

Charset specifies the character set used for exchanging pathnames with the FTP server, and for exchanging file character data with the FTP server. Charset can either be kUniTypeAuto, kUniTypeUTF8, kUniTypeNativeCharacters, kUniTypeAnsi..., kUniTypeISO8859_..., or kUniTypeOEM.

If you specify kUniTypeAuto, after FTPConnect establishes a connection, it sends a FEAT command to the server to determine if the server supports UTF8. If the server supports UTF8, then the connection uses UTF8 as the charset, otherwise it uses kUniTypeNativeCharacters.

Socket is an Omnis Long Integer field, which receives the result of the command. If the command successfully establishes a connection and logs on to the server, Socket has a value >= 0; you pass this value to the other FTP commands, to execute requests on this connection. Possible error codes are listed in the Web Command Error Codes Appendix.

Example

FTPConnect (iServerAddress,iUserName,iPassword) Returns iFTPSocket
If  iFTPSocket<0
  FTPGetLastStatus (iServerReplyText) Returns lErrCode
  OK message FTP Error {[con("An error occurred logging on to ",iServerAddress," - Details follow",kCr,iServerReplyText)]}
End If