SFtp SQL Server Reference Documentation

SFtp

Current Version: 11.6.0
Requires Chilkat Bundle License

Chilkat.SFtp

Transfer, list, manage, and synchronize files over SFTP.

Chilkat.SFtp is Chilkat's main class for secure file transfer over SSH. It provides SSH connection and authentication, SFTP subsystem initialization, uploads, downloads, directory listings, remote file management, file attributes, handle-based file access, recursive synchronization, bandwidth throttling, proxy support, host key fingerprinting, SSH algorithm controls, and detailed diagnostics.

SSH + SFTP setup

Connect to an SSH server, authenticate with password or key-based credentials, then initialize the SFTP subsystem before file operations.

Upload and download

Transfer files using simple path-based APIs, in-memory data, streams, or handle-based methods when lower-level control is needed.

Directory and file management

List directories, create and remove folders, rename files, delete files, inspect attributes, and work with remote paths.

Sync-tree operations

Upload or download directory trees and synchronize local and remote folder structures.

Security controls

Verify host keys, control accepted SSH algorithms, use private keys, and configure proxy or network settings when required.

Diagnostics and reliability

Use detailed error text, session logs, progress callbacks, bandwidth limits, and timeout settings to troubleshoot real-world server behavior.

Common pattern: Connect, authenticate, initialize SFTP, perform file operations using remote paths or handles, close any open handles, and disconnect. Use handle-based APIs for precise control, and synchronization methods for recursive folder transfers.

For an extended overview, see SFtp Class Overview.

Object Creation

DECLARE @hr int
DECLARE @sFtp int
EXEC @hr = sp_OACreate 'Chilkat.SFtp', @sFtp OUT
IF @hr <> 0
BEGIN
    PRINT 'Failed to create ActiveX component'
    RETURN
END

-- ... use @sFtp ...

EXEC @hr = sp_OADestroy @sFtp

T-SQL uses the Chilkat ActiveX through the OLE Automation stored procedures. They must be enabled once on the server (EXEC sp_configure 'Ole Automation Procedures', 1; RECONFIGURE;), and the Chilkat ActiveX registered must match the bitness of the SQL Server instance (64-bit for a 64-bit SQL Server). To bind to a specific major version of Chilkat, append the major version number to the ProgID, such as sp_OACreate 'Chilkat.SFtp.11' for Chilkat v11.*.*.

sp_OACreate returns an object token (an int) that is passed as the first argument of every sp_OAMethod, sp_OAGetProperty and sp_OASetProperty call, and released with sp_OADestroy. Objects returned by methods (such as an HttpResponse or JsonObject) are also tokens received through an int OUT parameter; they must likewise be destroyed, and the OUT parameter is NULL when the method fails to return an object. Objects passed as arguments are passed by their token. When an OLE Automation procedure itself fails (non-zero @hr), sp_OAGetErrorInfo describes the error.

Data types: strings are nvarchar(4000); integers, booleans (1 or 0) and object tokens are int; dates are datetime. In the signatures on this page, @success, @iResult, @sResult and the like are the OUT variables receiving a method's return value, @iValue / @sValue receive or supply a property value, and the remaining @ variables are the method's arguments in order.

A string returned through an OUT parameter is limited to 4000 characters. For longer values, retrieve the result as a result set into a table variable instead of an OUT parameter, for example DECLARE @tmp TABLE (outputLine ntext) followed by INSERT INTO @tmp EXEC sp_OAGetProperty @sFtp, 'LastErrorText'. See string length limitations for strings returned by sp_OAMethod calls.

Methods that pass or return raw byte arrays are not shown on this page, because varbinary(max) values cannot be exchanged through sp_OAMethod (see varbinary(max) limitation). Use the BinData-based alternatives (methods ending in Bd) or the base64 / hex string-encoded variants instead. Binary properties (such as LastBinaryResult) can be retrieved as a result set into a table variable, as shown in their signatures. Asynchronous (*Async) methods and event callbacks are not available from SQL Server.

Properties

AbortCurrent
EXEC sp_OAGetProperty @sFtp, 'AbortCurrent', @iValue OUT
EXEC sp_OASetProperty @sFtp, 'AbortCurrent', @iValue
Introduced in version 9.5.0.58

Set to 1 to request that the currently running Chilkat operation abort. Both synchronous and asynchronous operations can be canceled; a synchronous call may be interrupted by setting this property from another thread.

When the abort is observed, the current method returns failure and Chilkat resets this property to 0. If no method is running, it is reset when the next method begins.

top
AuthFailReason
EXEC sp_OAGetProperty @sFtp, 'AuthFailReason', @iValue OUT
Introduced in version 9.5.0.52

Contains the result code from the most recent call to AuthenticatePw, AuthenticatePk, AuthenticatePwPk, or a corresponding secure-string authentication method.

ValueMeaning
1Transport failure: communication was lost, or a network read or write failed or timed out.
2Invalid private key: the key format, key type, or key contents are not suitable for public-key authentication.
3No mutually supported authentication method is available.
4SSH authentication protocol error: an unexpected or invalid message was received.
5The server rejected the supplied password or private key.
6The SSH session is already authenticated.
7The server requires a password change. See PasswordChangeRequested.
Read this property immediately after an authentication method fails. Also inspect LastErrorText for detailed diagnostics.
Lifetime: A later successful authentication does not necessarily reset this value. Consult it only immediately after an authentication method returns 0; do not use an older value to describe the current session.

top
BandwidthThrottleDown
EXEC sp_OAGetProperty @sFtp, 'BandwidthThrottleDown', @iValue OUT
EXEC sp_OASetProperty @sFtp, 'BandwidthThrottleDown', @iValue
Introduced in version 9.5.0.49

Specifies the approximate maximum download rate, in bytes per second. The default is 0, which disables download throttling.

Bandwidth throttling is approximate. Actual throughput can vary because of network latency, SSH framing, buffering, and server behavior.

top
BandwidthThrottleUp
EXEC sp_OAGetProperty @sFtp, 'BandwidthThrottleUp', @iValue OUT
EXEC sp_OASetProperty @sFtp, 'BandwidthThrottleUp', @iValue
Introduced in version 9.5.0.49

Specifies the approximate maximum upload rate, in bytes per second. The default is 0, which disables upload throttling.

Bandwidth throttling is approximate. Actual throughput can vary because of network latency, SSH framing, buffering, and server behavior.

More Information and Examples
SFTP Upload with Bandwidth Throttling
top
ClientIdentifier
EXEC sp_OAGetProperty @sFtp, 'ClientIdentifier', @sValue OUT
EXEC sp_OASetProperty @sFtp, 'ClientIdentifier', @sValue

Specifies the SSH client-identification string sent when a connection is established. The default begins with SSH-2.0-Chilkat_ followed by the Chilkat version, for example SSH-2.0-Chilkat_11.6.0.

The value should begin with SSH-2.0-. A server may disconnect if the identification string is invalid.

top
ClientIpAddress
EXEC sp_OAGetProperty @sFtp, 'ClientIpAddress', @sValue OUT
EXEC sp_OASetProperty @sFtp, 'ClientIpAddress', @sValue

This property is normally left unset. Set it only on a multihomed computer when the application must bind the outgoing connection to a specific local network interface.

Specify a numeric IPv4 or IPv6 address, not a hostname. When the property is empty, the operating system automatically chooses the local address.

top
ConnectTimeoutMs
EXEC sp_OAGetProperty @sFtp, 'ConnectTimeoutMs', @iValue OUT
EXEC sp_OASetProperty @sFtp, 'ConnectTimeoutMs', @iValue

Specifies the maximum number of milliseconds allowed for the remote endpoint to accept the TCP connection.

This setting covers TCP connection establishment. After the socket is connected, receive and transfer inactivity are governed by IdleTimeoutMs and method-specific timeouts.

top
DebugLogFilePath
EXEC sp_OAGetProperty @sFtp, 'DebugLogFilePath', @sValue OUT
EXEC sp_OASetProperty @sFtp, 'DebugLogFilePath', @sValue

If set to a file path, this property logs the LastErrorText of each Chilkat method or property call to the specified file. This logging helps identify the context and history of Chilkat calls leading up to any crash or hang, aiding in debugging.

Enabling the VerboseLogging property provides more detailed information. This property is mainly used for debugging rare instances where a Chilkat method call causes a hang or crash, which should generally not happen.

Possible causes of hangs include:

  • A timeout property set to 0, indicating an infinite timeout.
  • A hang occurring within an event callback in the application code.
  • An internal bug in the Chilkat code causing the hang.

More Information and Examples
Example showing how to use DebugLogFilePath.
top
DisconnectCode
EXEC sp_OAGetProperty @sFtp, 'DisconnectCode', @iValue OUT

Contains the RFC 4253 reason code from the most recent SSH DISCONNECT message received from the server. A value of 0 means no server-provided disconnect code is available.

CodeSymbolic name
1SSH_DISCONNECT_HOST_NOT_ALLOWED_TO_CONNECT
2SSH_DISCONNECT_PROTOCOL_ERROR
3SSH_DISCONNECT_KEY_EXCHANGE_FAILED
4SSH_DISCONNECT_RESERVED
5SSH_DISCONNECT_MAC_ERROR
6SSH_DISCONNECT_COMPRESSION_ERROR
7SSH_DISCONNECT_SERVICE_NOT_AVAILABLE
8SSH_DISCONNECT_PROTOCOL_VERSION_NOT_SUPPORTED
9SSH_DISCONNECT_HOST_KEY_NOT_VERIFIABLE
10SSH_DISCONNECT_CONNECTION_LOST
11SSH_DISCONNECT_BY_APPLICATION
12SSH_DISCONNECT_TOO_MANY_CONNECTIONS
13SSH_DISCONNECT_AUTH_CANCELLED_BY_USER
14SSH_DISCONNECT_NO_MORE_AUTH_METHODS_AVAILABLE
15SSH_DISCONNECT_ILLEGAL_USER_NAME

See DisconnectReason for the server-provided descriptive text.

top
DisconnectReason
EXEC sp_OAGetProperty @sFtp, 'DisconnectReason', @sValue OUT

Contains the descriptive text sent with the most recent server SSH DISCONNECT message. See DisconnectCode for the corresponding RFC 4253 reason code.

The text is supplied by the server and can be empty or generic. An ordinary TCP loss or a local disconnect does not necessarily produce an SSH disconnect reason.

top
EnableCache
EXEC sp_OAGetProperty @sFtp, 'EnableCache', @iValue OUT
EXEC sp_OASetProperty @sFtp, 'EnableCache', @iValue

Controls whether Chilkat caches remote file sizes and attributes requested by GetFileSize32, GetFileSize64, GetFileSizeStr, GetFileCreateTimeStr, GetFileLastAccessStr, GetFileLastModifiedStr, GetFileOwner, GetFileGroup, GetFilePermissions. The default is 0.

When enabled, requesting one attribute by filename causes the complete attribute set for that file to be cached. Later attribute requests for the same filename can be satisfied without another server round trip.

Caching applies only when a remote path is used, not when an open handle is used. Call ClearCache when remote metadata may have changed.

top
EnableCompression
EXEC sp_OAGetProperty @sFtp, 'EnableCompression', @iValue OUT
EXEC sp_OASetProperty @sFtp, 'EnableCompression', @iValue
Introduced in version 9.5.0.56

Controls whether SSH compression may be negotiated. The default is 0.

Some older servers advertise compression but fail when it is enabled. If the server disconnects during or immediately after connection or authentication, try leaving this property 0.

top
EnableSecrets
EXEC sp_OAGetProperty @sFtp, 'EnableSecrets', @iValue OUT
EXEC sp_OASetProperty @sFtp, 'EnableSecrets', @iValue
Introduced in version 11.5.0

Enables automatic resolution of secret specification strings from secure operating-system storage. The default is 0.

When 1, supported password properties and authentication methods may receive a value beginning with !! instead of a literal credential. Chilkat resolves the secret from Windows Credential Manager on Windows or Apple Keychain on macOS.

Secret specification format:

!![appName|]service[|domain]|username

This feature applies to HttpProxyPassword, SocksPassword, AuthenticatePw, and AuthenticatePwPk.

More Information and Examples
More Detailed Information About EnableSecrets
top
FilenameCharset
EXEC sp_OAGetProperty @sFtp, 'FilenameCharset', @sValue OUT
EXEC sp_OASetProperty @sFtp, 'FilenameCharset', @sValue

Specifies the character encoding used for SFTP filenames. During InitializeSftp, Chilkat automatically sets this property when the server supplies a filename-charset extension.

When the property is empty, incoming and outgoing filenames use UTF-8. Otherwise, Chilkat uses the specified charset, such as utf-8, iso-8859-1, or windows-1252.

Use an explicit charset only when required by the server. UTF-8 is the normal SFTP filename encoding.

top
ForceCipher
EXEC sp_OAGetProperty @sFtp, 'ForceCipher', @sValue OUT
EXEC sp_OASetProperty @sFtp, 'ForceCipher', @sValue

Restricts SSH cipher negotiation to a single cipher. Leave this property empty to use Chilkat's normal preference order. For broader algorithm control, use SetAllowedAlgorithms.

Cipher nameFamily
chacha20-poly1305@openssh.comChaCha20-Poly1305 authenticated encryption
aes128-ctr, aes192-ctr, aes256-ctrAES in CTR mode
aes128-cbc, aes192-cbc, aes256-cbcAES in CBC mode
aes128-gcm@openssh.com, aes256-gcm@openssh.comAES-GCM authenticated encryption
twofish128-cbc, twofish256-cbcTwofish in CBC mode
blowfish-cbcBlowfish in CBC mode
If the server does not support the selected cipher, Connect fails.

top
ForceV3
EXEC sp_OAGetProperty @sFtp, 'ForceV3', @iValue OUT
EXEC sp_OASetProperty @sFtp, 'ForceV3', @iValue

Controls SFTP protocol-version negotiation. The default is 1, which forces use of SFTP v3 even when the server supports a newer version.

Set this property to 0 before InitializeSftp when the application needs features introduced in SFTP v4, v5, or v6. After initialization, read ProtocolVersion to determine the negotiated version.

top
HostKeyAlg
EXEC sp_OAGetProperty @sFtp, 'HostKeyAlg', @sValue OUT
EXEC sp_OASetProperty @sFtp, 'HostKeyAlg', @sValue

Specifies the preferred host-key algorithm used during SSH connection establishment. The default is DSS; set it to RSA only when required for compatibility with a particular server.

Normally this property should be left unchanged.

top
HostKeyFingerprint
EXEC sp_OAGetProperty @sFtp, 'HostKeyFingerprint', @sValue OUT

Contains the connected server's host-key fingerprint in Chilkat's legacy MD5 format. The value is set after a successful SSH connection.

ssh-rsa 2048 68:ff:d1:4e:6c:ff:d7:b0:d6:58:73:85:07:bc:2e:d5
ssh-ed25519 256 c8:73:22:c7:82:aa:09:f1:1c:4e:99:8a:a0:62:a7:87
For new applications, use GetHostKeyFP with SHA256. Compare the fingerprint with a value obtained from a trusted source before sending credentials.
The value is cleared by Disconnect. Obtain and validate it while the SSH connection is active.

More Information and Examples
SFTP Host Key Fingerprint
top
HttpProxyAuthMethod
EXEC sp_OAGetProperty @sFtp, 'HttpProxyAuthMethod', @sValue OUT
EXEC sp_OASetProperty @sFtp, 'HttpProxyAuthMethod', @sValue

Specifies the authentication method used by an HTTP proxy. Matching is case-insensitive.

ValueBehavior
emptyAutomatically negotiate a supported method.
BasicUse HTTP Basic authentication.
NTLMUse NTLM authentication.

top
HttpProxyDomain
EXEC sp_OAGetProperty @sFtp, 'HttpProxyDomain', @sValue OUT
EXEC sp_OASetProperty @sFtp, 'HttpProxyDomain', @sValue

Specifies the optional Windows domain used for NTLM authentication with an HTTP proxy. This property is ignored for Basic authentication.

top
HttpProxyHostname
EXEC sp_OAGetProperty @sFtp, 'HttpProxyHostname', @sValue OUT
EXEC sp_OASetProperty @sFtp, 'HttpProxyHostname', @sValue

Specifies the hostname or numeric IP address of an HTTP proxy used to establish the SSH connection.

Set this property together with HttpProxyPort. A configured SOCKS proxy takes precedence when SocksVersion is 4 or 5.

top
HttpProxyPassword
EXEC sp_OAGetProperty @sFtp, 'HttpProxyPassword', @sValue OUT
EXEC sp_OASetProperty @sFtp, 'HttpProxyPassword', @sValue

Specifies the password used to authenticate with an HTTP proxy.

top
HttpProxyPort
EXEC sp_OAGetProperty @sFtp, 'HttpProxyPort', @iValue OUT
EXEC sp_OASetProperty @sFtp, 'HttpProxyPort', @iValue

Specifies the HTTP proxy port. Common values include 8080 and 3128.

The proxy is used when HttpProxyHostname is nonempty, this property is nonzero, and SocksVersion is 0.

top
HttpProxyUsername
EXEC sp_OAGetProperty @sFtp, 'HttpProxyUsername', @sValue OUT
EXEC sp_OASetProperty @sFtp, 'HttpProxyUsername', @sValue

Specifies the username used to authenticate with an HTTP proxy.

top
IdleTimeoutMs
EXEC sp_OAGetProperty @sFtp, 'IdleTimeoutMs', @iValue OUT
EXEC sp_OASetProperty @sFtp, 'IdleTimeoutMs', @iValue

Specifies the maximum period, in milliseconds, during which an SFTP operation may make no progress while sending or receiving data. The default is 30000 (30 seconds).

Set this property to 0 to allow an operation to wait indefinitely.

top
IncludeDotDirs
EXEC sp_OAGetProperty @sFtp, 'IncludeDotDirs', @iValue OUT
EXEC sp_OASetProperty @sFtp, 'IncludeDotDirs', @iValue

Controls whether ReadDir and ReadDirListing include the special . and .. directory entries. The default is 0.

This property controls only the special directory entries . and ... It does not exclude ordinary hidden filenames such as .gitignore or .profile.

top
InitializeFailCode
EXEC sp_OAGetProperty @sFtp, 'InitializeFailCode', @iValue OUT

Contains the RFC 4254 channel-open failure code when InitializeSftp cannot open the SFTP session channel. The initial value is 0.

CodeSymbolic name
1SSH_OPEN_ADMINISTRATIVELY_PROHIBITED
2SSH_OPEN_CONNECT_FAILED
3SSH_OPEN_UNKNOWN_CHANNEL_TYPE
4SSH_OPEN_RESOURCE_SHORTAGE

top
InitializeFailReason
EXEC sp_OAGetProperty @sFtp, 'InitializeFailReason', @sValue OUT

Contains the descriptive text associated with InitializeFailCode when InitializeSftp cannot open the SFTP session channel. The text is supplied by the server and may be empty or generic.

top
IsConnected
EXEC sp_OAGetProperty @sFtp, 'IsConnected', @iValue OUT

Returns 1 when Chilkat's last known state indicates that the underlying SSH transport is connected. This means Connect succeeded; it does not mean authentication or InitializeSftp has completed.

This property is passive and does not perform network I/O. A silent network failure or a peer close may remain undetected until an operation reads from or writes to the socket.

To actively test whether the connection is still writable, call SendIgnore and check its return value. The server does not reply to an SSH IGNORE message.

top
KeepSessionLog
EXEC sp_OAGetProperty @sFtp, 'KeepSessionLog', @iValue OUT
EXEC sp_OASetProperty @sFtp, 'KeepSessionLog', @iValue

Controls whether SSH and SFTP protocol traffic is accumulated in SessionLog. The default is 0.

Session logging is intended for diagnostics and grows as activity continues. Disable it when no longer needed and treat the resulting log as potentially sensitive.

top
LastBinaryResult
INSERT INTO @tmp EXEC sp_OAGetProperty @sFtp, 'LastBinaryResult'

This property is mainly used in SQL Server stored procedures to retrieve binary data from the last method call that returned binary data. It is only accessible if Chilkat.Global.KeepBinaryResult is set to 1. This feature allows for the retrieval of large varbinary results in an SQL Server environment, which has restrictions on returning large data via method calls, though temp tables can handle binary properties.

top
LastErrorHtml
EXEC sp_OAGetProperty @sFtp, 'LastErrorHtml', @sValue OUT

Provides HTML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.

top
LastErrorText
EXEC sp_OAGetProperty @sFtp, 'LastErrorText', @sValue OUT

Provides plain text information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.

More Information and Examples
Concept of LastErrorTextLastErrorText Standard Information
top
LastErrorXml
EXEC sp_OAGetProperty @sFtp, 'LastErrorXml', @sValue OUT

Provides XML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.

top
LastMethodSuccess
EXEC sp_OAGetProperty @sFtp, 'LastMethodSuccess', @iValue OUT
EXEC sp_OASetProperty @sFtp, 'LastMethodSuccess', @iValue

Indicates the success or failure of the most recent method call: 1 means success, 0 means failure. This property remains unchanged by property setters or getters. This method is present to address challenges in checking for null or Nothing returns in certain programming languages. Note: This property does not apply to methods that return integer values or to boolean-returning methods where the boolean does not indicate success or failure.

top
LastStatusCode
EXEC sp_OAGetProperty @sFtp, 'LastStatusCode', @iValue OUT
Introduced in version 9.5.0.85

Contains the numeric code from the most recently received SFTP SSH_FXP_STATUS response. This is not necessarily the status of the most recently called method. Methods that return a handle, attributes, or data can complete without receiving a new status response, leaving an older value unchanged. A successful method can therefore leave a previous nonzero status code in this property.

CodeSymbolic name
0SSH_FX_OK
1SSH_FX_EOF
2SSH_FX_NO_SUCH_FILE
3SSH_FX_PERMISSION_DENIED
4SSH_FX_FAILURE
5SSH_FX_BAD_MESSAGE
6SSH_FX_NO_CONNECTION
7SSH_FX_CONNECTION_LOST
8SSH_FX_OP_UNSUPPORTED
9SSH_FX_INVALID_HANDLE
10SSH_FX_NO_SUCH_PATH
11SSH_FX_FILE_ALREADY_EXISTS
12SSH_FX_WRITE_PROTECT
13SSH_FX_NO_MEDIA
14SSH_FX_NO_SPACE_ON_FILESYSTEM
15SSH_FX_QUOTA_EXCEEDED
16SSH_FX_UNKNOWN_PRINCIPAL
17SSH_FX_LOCK_CONFLICT
18SSH_FX_DIR_NOT_EMPTY
19SSH_FX_NOT_A_DIRECTORY
20SSH_FX_INVALID_FILENAME
21SSH_FX_LINK_LOOP
22SSH_FX_CANNOT_DELETE
23SSH_FX_INVALID_PARAMETER
24SSH_FX_FILE_IS_A_DIRECTORY
25SSH_FX_BYTE_RANGE_LOCK_CONFLICT
26SSH_FX_BYTE_RANGE_LOCK_REFUSED
27SSH_FX_DELETE_PENDING
28SSH_FX_FILE_CORRUPT
29SSH_FX_OWNER_INVALID
30SSH_FX_GROUP_INVALID
31SSH_FX_NO_MATCHING_BYTE_RANGE_LOCK

See LastStatusMessage for the server-provided message text.

Use each method's documented return value as the primary success test. Read this property immediately after a relevant SFTP failure when the server status provides additional detail.

top
LastStatusMessage
EXEC sp_OAGetProperty @sFtp, 'LastStatusMessage', @sValue OUT
Introduced in version 9.5.0.85

Contains the message text from the most recently received SFTP SSH_FXP_STATUS response. The wording is server-dependent.

This property can remain unchanged across later successful methods that do not receive a new status response. See LastStatusCode for the numeric code.

top
LastStringResult
EXEC sp_OAGetProperty @sFtp, 'LastStringResult', @sValue OUT

In SQL Server stored procedures, this property holds the string return value of the most recent method call that returns a string. It is accessible only when Chilkat.Global.KeepStringResult is set to TRUE. SQL Server has limitations on string lengths returned from methods and properties, but temp tables can be used to access large strings.

More Information and Examples
Long Strings Returned by ActiveX Methods in SQL Server
top
LastStringResultLen
EXEC sp_OAGetProperty @sFtp, 'LastStringResultLen', @iValue OUT

The length, in characters, of the string contained in the LastStringResult property.

top
MaxPacketSize
EXEC sp_OAGetProperty @sFtp, 'MaxPacketSize', @iValue OUT
EXEC sp_OASetProperty @sFtp, 'MaxPacketSize', @iValue

Specifies the maximum packet length used by the underlying SSH transport. The default is 32768 bytes.

Normally this property should remain unchanged.

top
PasswordChangeRequested
EXEC sp_OAGetProperty @sFtp, 'PasswordChangeRequested', @iValue OUT

Indicates that the server rejected password authentication because the account password must be changed. This property is set by AuthenticatePw and AuthenticatePwPk.

When 1, call the authentication method again and pass the old and new passwords in this form:

|oldPassword|newPassword|

top
PreferIpv6
EXEC sp_OAGetProperty @sFtp, 'PreferIpv6', @iValue OUT
EXEC sp_OASetProperty @sFtp, 'PreferIpv6', @iValue

Controls the preferred address family when DNS resolution returns both IPv4 and IPv6 addresses. The default is 0, which prefers IPv4. Set it to 1 to prefer IPv6.

top
PreserveDate
EXEC sp_OAGetProperty @sFtp, 'PreserveDate', @iValue OUT
EXEC sp_OASetProperty @sFtp, 'PreserveDate', @iValue

Controls whether path-based upload and download methods preserve source timestamps on the destination. The default is 0.

Last-modified time is preserved when supported by the negotiated SFTP version and destination filesystem. SFTP v3 represents these times with whole-second precision and does not provide a creation-time attribute; creation-time preservation requires a later protocol version and server support.

This property does not apply to low-level transfers performed by opening a remote handle, reading or writing the data, and then closing the handle.

top
ProtocolVersion
EXEC sp_OAGetProperty @sFtp, 'ProtocolVersion', @iValue OUT

Contains the SFTP protocol version negotiated by InitializeSftp, normally a value from 3 through 6.

Chilkat and the server exchange their highest supported versions, and the session uses the lower compatible version. Features unavailable in older versions are identified throughout this reference documentation.

The initial value is 0. After a successful initialization, the negotiated value can remain populated after Disconnect and during a later connection before SFTP is initialized again. Do not use this property alone to determine whether an SFTP channel is currently open.

top
ReadDirMustMatch
EXEC sp_OAGetProperty @sFtp, 'ReadDirMustMatch', @sValue OUT
EXEC sp_OASetProperty @sFtp, 'ReadDirMustMatch', @sValue
Introduced in version 9.5.0.53

Specifies a semicolon-separated list of filename patterns. When nonempty, ReadDir and ReadDirListing include only entries matching at least one pattern.

  • * matches zero or more characters.
  • Matching is case-insensitive.
  • ? and bracket expressions such as [0-9] are not wildcard operators.
  • Surrounding whitespace and empty entries between semicolons are ignored.
*.xml; *.txt; *.csv

top
ReadDirMustNotMatch
EXEC sp_OAGetProperty @sFtp, 'ReadDirMustNotMatch', @sValue OUT
EXEC sp_OASetProperty @sFtp, 'ReadDirMustNotMatch', @sValue
Introduced in version 9.5.0.53

Specifies a semicolon-separated list of filename patterns. When nonempty, ReadDir and ReadDirListing exclude entries matching any pattern. Exclusion is applied after ReadDirMustMatch.

  • * matches zero or more characters.
  • Matching is case-insensitive.
  • ? and bracket expressions such as [0-9] are not wildcard operators.
  • Surrounding whitespace and empty entries between semicolons are ignored.
*.tmp; *.bak; *.log

top
ServerIdentifier
EXEC sp_OAGetProperty @sFtp, 'ServerIdentifier', @sValue OUT
Introduced in version 9.5.0.71

Contains the SSH server-identification string received during connection establishment. For example:

SSH-2.0-OpenSSH_8.9p1 Ubuntu-3ubuntu0.16
The last received identifier can remain populated after Disconnect. Use IsConnected to determine whether the SSH transport is currently connected.

top
SessionLog
EXEC sp_OAGetProperty @sFtp, 'SessionLog', @sValue OUT

Contains the in-memory SSH/SFTP protocol log. Enable logging by setting KeepSessionLog to 1.

This property contains log text, not a file path. Call ClearSessionLog to clear it.

top
SocksHostname
EXEC sp_OAGetProperty @sFtp, 'SocksHostname', @sValue OUT
EXEC sp_OASetProperty @sFtp, 'SocksHostname', @sValue

Specifies the SOCKS proxy hostname or IPv4 address. This property is used only when SocksVersion is 4 or 5.

top
SocksPassword
EXEC sp_OAGetProperty @sFtp, 'SocksPassword', @sValue OUT
EXEC sp_OASetProperty @sFtp, 'SocksPassword', @sValue

Specifies the SOCKS5 password when username/password authentication is required. SOCKS4 does not use a password, so this property is ignored when SocksVersion is 4.

top
SocksPort
EXEC sp_OAGetProperty @sFtp, 'SocksPort', @iValue OUT
EXEC sp_OASetProperty @sFtp, 'SocksPort', @iValue

Specifies the SOCKS proxy port. The default is 1080. This property is used only when SocksVersion is 4 or 5.

top
SocksUsername
EXEC sp_OAGetProperty @sFtp, 'SocksUsername', @sValue OUT
EXEC sp_OASetProperty @sFtp, 'SocksUsername', @sValue

Specifies the SOCKS proxy username. For SOCKS4 it is sent as the user ID; for SOCKS5 it is used with SocksPassword for username/password authentication.

top
SocksVersion
EXEC sp_OAGetProperty @sFtp, 'SocksVersion', @iValue OUT
EXEC sp_OASetProperty @sFtp, 'SocksVersion', @iValue

Selects whether and how a SOCKS proxy is used.

ValueBehavior
0Do not use a SOCKS proxy. This is the default.
4Connect through a SOCKS4 proxy.
5Connect through a SOCKS5 proxy.

top
SoRcvBuf
EXEC sp_OAGetProperty @sFtp, 'SoRcvBuf', @iValue OUT
EXEC sp_OASetProperty @sFtp, 'SoRcvBuf', @iValue

Specifies the socket receive-buffer size. The default is 4194304 bytes. Normally this property should remain unchanged.

When download throughput is unexpectedly low, testing a larger value may help. Values should generally be multiples of 4096.

More Information and Examples
More Information about TCP performance and Buffer Sizes
top
SoSndBuf
EXEC sp_OAGetProperty @sFtp, 'SoSndBuf', @iValue OUT
EXEC sp_OASetProperty @sFtp, 'SoSndBuf', @iValue

Specifies the socket send-buffer size. The default is 262144 bytes. Normally this property should remain unchanged.

When upload throughput is unexpectedly low, testing values such as 524288 or 1048576 may help. Values should generally be multiples of 4096.

More Information and Examples
More Information about TCP performance and Buffer Sizes
top
SyncCreateAllLocalDirs
EXEC sp_OAGetProperty @sFtp, 'SyncCreateAllLocalDirs', @iValue OUT
EXEC sp_OASetProperty @sFtp, 'SyncCreateAllLocalDirs', @iValue
Introduced in version 9.5.0.76

Controls whether SyncTreeDownload creates empty remote directories locally. The default is 1.

When 0, a local directory is created only when it is needed to contain a downloaded file.

When 1, an empty remote directory is created locally even when no file beneath it is downloaded.

More Information and Examples
SFTP Sync Download Tree w/ Must-Match Filename Constraints
top
SyncDirectives
EXEC sp_OAGetProperty @sFtp, 'SyncDirectives', @sValue OUT
EXEC sp_OASetProperty @sFtp, 'SyncDirectives', @sValue
Introduced in version 9.5.0.58

Specifies comma-separated directives that modify SyncTreeUpload or SyncTreeDownload. The default is an empty string.

DirectiveEffect
UploadIgnoreLocalOpenFailuresDuring upload synchronization, skip local files that cannot be opened, such as files held with exclusive access by another process.

top
SyncMustMatch
EXEC sp_OAGetProperty @sFtp, 'SyncMustMatch', @sValue OUT
EXEC sp_OASetProperty @sFtp, 'SyncMustMatch', @sValue

Specifies a semicolon-separated list of wildcard filename patterns. SyncTreeUpload and SyncTreeDownload transfer only files matching at least one pattern.

This filter applies to filenames, not directory names encountered while recursively traversing a tree.

*.xml;*.txt;*.csv
Use * to match zero or more characters. Separate multiple patterns with semicolons.

More Information and Examples
SFTP Sync Download Tree w/ Must-Match Filename Constraints
top
SyncMustMatchDir
EXEC sp_OAGetProperty @sFtp, 'SyncMustMatchDir', @sValue OUT
EXEC sp_OASetProperty @sFtp, 'SyncMustMatchDir', @sValue
Introduced in version 9.5.0.76

Specifies a semicolon-separated list of wildcard directory-name patterns. SyncTreeUpload and SyncTreeDownload enter only directories matching at least one pattern.

xml;txt;data_*
Use * to match zero or more characters. Separate multiple patterns with semicolons.

More Information and Examples
SFTP Sync Download Tree w/ Must-Match Directory Constraints
top
SyncMustNotMatch
EXEC sp_OAGetProperty @sFtp, 'SyncMustNotMatch', @sValue OUT
EXEC sp_OASetProperty @sFtp, 'SyncMustNotMatch', @sValue

Specifies a semicolon-separated list of wildcard filename patterns. SyncTreeUpload and SyncTreeDownload skip files matching any pattern.

This filter applies to filenames, not directory names encountered while recursively traversing a tree.

*.tmp;*.bak;*.log
Use * to match zero or more characters. Separate multiple patterns with semicolons.

top
SyncMustNotMatchDir
EXEC sp_OAGetProperty @sFtp, 'SyncMustNotMatchDir', @sValue OUT
EXEC sp_OASetProperty @sFtp, 'SyncMustNotMatchDir', @sValue
Introduced in version 9.5.0.76

Specifies a semicolon-separated list of wildcard directory-name patterns. SyncTreeUpload and SyncTreeDownload skip directories matching any pattern.

temp;cache;archive_*
Use * to match zero or more characters. Separate multiple patterns with semicolons.

top
TcpNoDelay
EXEC sp_OAGetProperty @sFtp, 'TcpNoDelay', @iValue OUT
EXEC sp_OASetProperty @sFtp, 'TcpNoDelay', @iValue

Controls the TCP_NODELAY socket option. The default is 0. Set it to 1 to disable the Nagle algorithm and reduce delays when many small packets are sent.

top
UncommonOptions
EXEC sp_OAGetProperty @sFtp, 'UncommonOptions', @sValue OUT
EXEC sp_OASetProperty @sFtp, 'UncommonOptions', @sValue
Introduced in version 9.5.0.73

Provides comma-separated compatibility, security, and synchronization options for uncommon scenarios. The default is an empty string and is appropriate for most applications.

KeywordEffect
ForceUserAuthRsaSha1Force legacy ssh-rsa/SHA-1 signatures for RSA user authentication. Set before connecting.
ProtectFromVpnOn Android, bypass an installed or active VPN.
NoSyncDownloadEmptyFilesPrevent empty files from being downloaded by SyncTreeDownload.
no-weak-mac-algsRemove weaker SHA-1, MD5, and RIPEMD-160 MAC algorithms from the offered list.
+ssh-hmac-etmRe-enable OpenSSH Encrypt-then-MAC algorithms disabled by default as a Terrapin mitigation.
+chacha20-poly1305@openssh.comRe-enable chacha20-poly1305@openssh.com, disabled by default as a Terrapin mitigation.

top
UploadChunkSize
EXEC sp_OAGetProperty @sFtp, 'UploadChunkSize', @iValue OUT
EXEC sp_OASetProperty @sFtp, 'UploadChunkSize', @iValue

Specifies the chunk size, in bytes, used by UploadFile and UploadFileByName. The default is 32000.

If an upload fails because the local operating system aborts the connection, try a smaller value such as 4096. Smaller chunks can reduce throughput.

top
UserAuthBanner
EXEC sp_OAGetProperty @sFtp, 'UserAuthBanner', @sValue OUT
EXEC sp_OASetProperty @sFtp, 'UserAuthBanner', @sValue
Introduced in version 9.5.0.88

Contains a user-authentication banner received from the server. Check this property after StartKeyboardAuth or another authentication attempt and display it to the user when appropriate.

When no banner is available, the property returns an empty string.

top
UtcMode
EXEC sp_OAGetProperty @sFtp, 'UtcMode', @iValue OUT
EXEC sp_OASetProperty @sFtp, 'UtcMode', @iValue

Controls the time zone used by date/time getters. When 1, returned values are expressed in UTC. When 0 (the default), returned values are converted to the local time zone.

UtcMode = 0: Fri, 21 Nov 1997 09:55:06 -0600
UtcMode = 1:  Fri, 21 Nov 1997 15:55:06 GMT

top
VerboseLogging
EXEC sp_OAGetProperty @sFtp, 'VerboseLogging', @iValue OUT
EXEC sp_OASetProperty @sFtp, 'VerboseLogging', @iValue

If set to 1, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. The default value is 0. Verbose logging should only be used for debugging. The potentially large quantity of logged information may adversely affect peformance.

top
Version
EXEC sp_OAGetProperty @sFtp, 'Version', @sValue OUT

Version of the component/library, such as "10.1.0"

More Information and Examples
How to get the Chilkat version at runtime.
top
XferByteCount
EXEC sp_OAGetProperty @sFtp, 'XferByteCount', @iValue OUT
Introduced in version 9.5.0.71

Contains the current transfer byte count for an upload or download in progress. An application can read this property while an asynchronous transfer is running.

For SyncTreeUpload and SyncTreeDownload, the value is cumulative across all files processed by the operation. Use XferByteCount64 when a 64-bit count is required.

top

Methods

AuthenticatePk
EXEC sp_OAMethod @sFtp, 'AuthenticatePk', @success OUT, @username, @privateKey

Authenticates the connected SSH session using public-key authentication. username identifies the server account, and privateKey must contain the corresponding private key. The matching public key must already be authorized for that account on the server.

Call Connect first. After a failure, inspect AuthFailReason and LastErrorText.

Returns 1 for success, 0 for failure.

More Information and Examples
SFTP Authenticate with a Private KeyUse PuTTY Key for SFTP AuthenticationAWS Transfer for SFTP (Amazon S3)Generate RSA Key for SFTP
top
AuthenticatePw
EXEC sp_OAMethod @sFtp, 'AuthenticatePw', @success OUT, @login, @password

Authenticates the connected SSH session using login and password.

1. Connect
2. AuthenticatePw or AuthenticatePk
3. InitializeSftp

If the server requests a password change, see PasswordChangeRequested. After a failure, inspect AuthFailReason and LastErrorText.

A rejected password does not necessarily close the SSH connection. The application may retry authentication on the same connected session. After a later success, an older AuthFailReason value can remain populated.

Returns 1 for success, 0 for failure.

More Information and Examples
SFTP Authenticate with a Password
top
AuthenticatePwPk
EXEC sp_OAMethod @sFtp, 'AuthenticatePwPk', @success OUT, @username, @password, @privateKey

Authenticates with a server that requires both a password and a private key. username identifies the account, password supplies the password, and privateKey supplies the private key.

Most servers require either password or public-key authentication rather than both. After a failure, inspect AuthFailReason and LastErrorText.

Returns 1 for success, 0 for failure.

More Information and Examples
SFTP Authenticate with Password and Private KeySFTP Auth Failure Reason (AuthenticatePwPk)
top
AuthenticateSecPw
EXEC sp_OAMethod @sFtp, 'AuthenticateSecPw', @success OUT, @login, @password
Introduced in version 9.5.0.71

Works like AuthenticatePw, but receives login and password in SecureString objects.

Returns 1 for success, 0 for failure.

More Information and Examples
SFTP Authenticate with a SecureString PasswordSFTP Authenticate Secure
top
AuthenticateSecPwPk
EXEC sp_OAMethod @sFtp, 'AuthenticateSecPwPk', @success OUT, @username, @password, @privateKey
Introduced in version 9.5.0.71

Works like AuthenticatePwPk, but receives username and password in SecureString objects. privateKey supplies the private key.

Returns 1 for success, 0 for failure.

More Information and Examples
SFTP Authenticate with a SecureString Password and Private Key
top
ClearCache
EXEC sp_OAMethod @sFtp, 'ClearCache', NULL

Clears the internal remote file-attribute cache used when EnableCache is 1.

More Information and Examples
Clear the SFTP File-Attribute Cache
top
ClearSessionLog
EXEC sp_OAMethod @sFtp, 'ClearSessionLog', NULL

Clears the in-memory text stored in SessionLog.

More Information and Examples
Clear the SFTP Session Log
top
CloseHandle
EXEC sp_OAMethod @sFtp, 'CloseHandle', @success OUT, @handle

Closes the remote file or directory handle specified by handle. The handle must have been returned by OpenFile or OpenDir.

Handles are specific to one initialized SFTP session. Close each handle exactly once. Closing an empty, invalid, or already-closed handle returns 0. A handle must never be reused after disconnecting or replacing the connection.

Returns 1 for success, 0 for failure.

More Information and Examples
Close a Remote SFTP File or Directory HandleSFTP Upload from Local Filesystem
top
Connect
EXEC sp_OAMethod @sFtp, 'Connect', @success OUT, @domainName, @port

Establishes an SSH connection to domainName on TCP port port. The host may be a DNS name or numeric IPv4 or IPv6 address; SSH servers commonly listen on port 22.

A successful connection establishes the SSH transport only. Next call an authentication method, then call InitializeSftp.
1. Connect
2. AuthenticatePw, AuthenticatePk, or another authentication method
3. InitializeSftp
4. Perform SFTP operations

Supported negotiation algorithms include:

CategoryAlgorithms
Host keyssh-ed25519, rsa-sha2-256, rsa-sha2-512, ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, ecdsa-sha2-nistp521, ssh-rsa, ssh-dss
Key exchangecurve25519-sha256, curve25519-sha256@libssh.org, NIST ECDH, Diffie-Hellman group 1/14/16/18, and group-exchange SHA-1/SHA-256
CiphersAES CTR/CBC/GCM, Twofish CBC, Blowfish CBC, and optionally chacha20-poly1305@openssh.com
MACSHA-2, SHA-1, RIPEMD-160, MD5, and optionally OpenSSH Encrypt-then-MAC variants
Compressionnone, zlib, and zlib@openssh.com
Connection failures can occur before SSH negotiation because of firewalls, endpoint security, routing, network ACLs, proxy configuration, or server policy.
Calling while connected: A new successful Connect replaces the existing SSH connection. The previous SFTP subsystem and all handles from it are no longer usable. Authenticate and call InitializeSftp for the new connection.

Returns 1 for success, 0 for failure.

More Information and Examples
Connect to an SFTP Server
top
ConnectThroughSsh
EXEC sp_OAMethod @sFtp, 'ConnectThroughSsh', @success OUT, @sshConn, @hostname, @port
Introduced in version 9.5.0.55

Connects to hostname on port through the already connected and authenticated Ssh object in sshConn.

application  →  first SSH server  →  destination SSH/SFTP server

After this method succeeds, authenticate separately with the destination server and call InitializeSftp. All destination traffic is carried through the first SSH connection.

Returns 1 for success, 0 for failure.

More Information and Examples
Connect to an SFTP Server Through a Jump HostMultiple Hop SSH to SFTP
top
ContinueKeyboardAuth
EXEC sp_OAMethod @sFtp, 'ContinueKeyboardAuth', @sResult OUT, @response
Introduced in version 9.5.0.88

Continues keyboard-interactive authentication by submitting response for the prompts returned by StartKeyboardAuth.

For a single prompt, pass the response text directly. For multiple prompts, pass XML in this form:

<response>
  <response1>response to first prompt</response1>
  <response2>response to second prompt</response2>
  ...
</response>

The returned XML indicates authentication success, authentication failure, or another infoRequest containing additional prompts.

<success>success message</success>

<error>error message</error>

Returns NULL on failure

More Information and Examples
Continue SFTP Keyboard-Interactive Authentication
top
CopyFileAttr
EXEC sp_OAMethod @sFtp, 'CopyFileAttr', @success OUT, @localFilename, @remoteFilename, @isHandle

Copies supported timestamps and attributes from the local file at localFilename to the remote item identified by remoteFilename.

Set isHandle to 1 when remoteFilename contains an open SFTP handle; otherwise set it to 0 for a remote path.

Negotiated SFTP versionAttributes copied
SFTP v3 and earlierLast-modified time and last-access time
SFTP v4 and v5Last-modified time, last-access time, and creation time
SFTP v6 and laterThe preceding timestamps plus read-only, hidden, archive, compressed, and encrypted flags
The remote server and filesystem determine whether all requested attributes can be applied. Last-access time may change when the server accesses the file, and compressed or encrypted flags may not have the same effect on every server.

Returns 1 for success, 0 for failure.

More Information and Examples
Copy Local File Attributes to a Remote SFTP File
top
CreateDir
EXEC sp_OAMethod @sFtp, 'CreateDir', @success OUT, @path

Creates the remote directory specified by path. Parent directories are not necessarily created automatically.

Returns 1 for success, 0 for failure.

More Information and Examples
Create a Remote Directory on an SFTP Server
top
Disconnect
EXEC sp_OAMethod @sFtp, 'Disconnect', NULL

Closes the current SSH/SFTP connection. All remote file and directory handles from that session become invalid and must not be reused.

The object remains reusable. A later session must call Connect, authenticate again, and call InitializeSftp before performing SFTP operations.

Some properties retain values from the previous session after disconnect, including the negotiated protocol version, server identifier, and last SFTP status. Treat these as historical values rather than evidence of a live session.
More Information and Examples
Disconnect from an SFTP Server
top
DownloadBd
EXEC sp_OAMethod @sFtp, 'DownloadBd', @success OUT, @remoteFilePath, @binData
Introduced in version 9.5.0.62

Downloads the remote file at remoteFilePath and appends its bytes to binData.

Existing data in binData is preserved. Clear it first when replacement rather than append behavior is required.

Returns 1 for success, 0 for failure.

More Information and Examples
Download Bytes from an SFTP Server (BinData)SFTP Upload and Download to a BinData Object
top
DownloadFile
EXEC sp_OAMethod @sFtp, 'DownloadFile', @success OUT, @handle, @toFilename

Streams the remote file identified by handle to the local filesystem path toFilename. The handle must have been returned by OpenFile.

The transfer is streamed and is not limited by available memory. Close the remote handle when the download is complete.

This method downloads the entire remote file beginning at byte offset 0. It does not begin at the handle's current sequential read position.

Returns 1 for success, 0 for failure.

More Information and Examples
Download from an SFTP Server Using an Open Handle
top
DownloadFileByName
EXEC sp_OAMethod @sFtp, 'DownloadFileByName', @success OUT, @remoteFilePath, @localFilePath

Downloads the remote file at remoteFilePath to the local filesystem path localFilePath.

When PreserveDate is 1, Chilkat preserves the remote file's last-modified time.

An absolute remote path begins with / and is relative to the server filesystem root. A relative path is interpreted relative to the authenticated user's home directory.
If the local destination file exists, it is truncated before the download.

Returns 1 for success, 0 for failure.

More Information and Examples
Download a File from an SFTP ServerUnderstanding SFTP Absolute FilePaths
top
DownloadSb
EXEC sp_OAMethod @sFtp, 'DownloadSb', @success OUT, @remoteFilePath, @charset, @sb
Introduced in version 9.5.0.62

Downloads the remote file at remoteFilePath, decodes it using charset, and appends the text to sb.

Existing text in sb is preserved. Clear it first when replacement rather than append behavior is required.

Returns 1 for success, 0 for failure.

More Information and Examples
Download Text from an SFTP Server (StringBuilder)SFTP Upload and Download to a StringBuilder Object
top
Eof
EXEC sp_OAMethod @sFtp, 'Eof', @success OUT, @handle

Returns 1 when the most recent read for handle received the SFTP end-of-file status.

Reading exactly through the final byte does not set EOF immediately. The next read returns successfully with zero bytes, sets LastStatusCode to SSH_FX_EOF, and causes this method to return 1.

An empty, malformed, or already-closed handle can also cause this method to return 1. Use LastReadFailed and the read method's result to distinguish a normal EOF from a handle or read failure.
More Information and Examples
Detect End-of-File on a Remote SFTP File
top
FileExists
EXEC sp_OAMethod @sFtp, 'FileExists', @iResult OUT, @remotePath, @followLinks
Introduced in version 9.5.0.67

Checks the remote item at remotePath. When followLinks is 1, a symbolic link is followed and the target type is returned.

Return valueMeaning
-1Unable to determine the result. Inspect LastErrorText.
0The path does not exist.
1A regular file exists.
2A directory exists.
3A symbolic link exists. This is possible only when followLinks is 0.
4A special filesystem entry exists.
5An entry of unknown type exists.
6A socket exists.
7A character device exists.
8A block device exists.
9A FIFO exists.
Positive values correspond to SFTP filesystem entry types. Some types are platform-dependent.
For a dangling symbolic link, followLinks = 0 returns 3 for the link itself, while followLinks = 1 returns 0 because the target does not exist.
More Information and Examples
Check if a Remote File or Directory ExistsCheck if File Exists
top
Fsync
EXEC sp_OAMethod @sFtp, 'Fsync', @success OUT, @handle
Introduced in version 9.5.0.71

Requests that the server flush pending data for the open file identified by handle to stable storage.

This method uses the OpenSSH fsync@openssh.com extension and succeeds only when the server supports that extension.

Returns 1 for success, 0 for failure.

More Information and Examples
Flush an SFTP File to Stable Storage (Fsync)SFTP Fsync -- Flush an Open File on the Server
top
GetFileCreateTimeStr
EXEC sp_OAMethod @sFtp, 'GetFileCreateTimeStr', @sResult OUT, @pathOrHandle, @bFollowLinks, @bIsHandle

Returns the remote file's creation date and time. pathOrHandle may contain a remote path or a handle returned by OpenFile. Set bIsHandle to 1 for a handle and 0 for a path.

When bFollowLinks is 1, the server follows a symbolic link and returns metadata for its target.

SFTP v3 and earlier do not provide a file creation time.

The result is an RFC 822 formatted string, for example Fri, 21 Nov 1997 09:55:06 -0600.

Returns NULL on failure

More Information and Examples
Get a Remote File's Creation Time
top
GetFileGroup
EXEC sp_OAMethod @sFtp, 'GetFileGroup', @sResult OUT, @pathOrHandle, @bFollowLinks, @bIsHandle

Returns the remote file's group ownership. pathOrHandle may contain a remote path or a handle returned by OpenFile. Set bIsHandle to 1 for a handle and 0 for a path.

When bFollowLinks is 1, the server follows a symbolic link and returns metadata for its target.

With SFTP v3 and earlier, the result is the decimal numeric GID because textual group names are not supported.

Returns NULL on failure

More Information and Examples
Get a Remote File's Group
top
GetFileLastAccessStr
EXEC sp_OAMethod @sFtp, 'GetFileLastAccessStr', @sResult OUT, @pathOrHandle, @bFollowLinks, @bIsHandle

Returns the remote file's last-access date and time. pathOrHandle may contain a remote path or a handle returned by OpenFile. Set bIsHandle to 1 for a handle and 0 for a path.

When bFollowLinks is 1, the server follows a symbolic link and returns metadata for its target.

The result is an RFC 822 formatted string, for example Fri, 21 Nov 1997 09:55:06 -0600.

Returns NULL on failure

More Information and Examples
Get a Remote File's Last-Access Time
top
GetFileLastModifiedStr
EXEC sp_OAMethod @sFtp, 'GetFileLastModifiedStr', @sResult OUT, @pathOrHandle, @bFollowLinks, @bIsHandle

Returns the remote file's last-modified date and time. pathOrHandle may contain a remote path or a handle returned by OpenFile. Set bIsHandle to 1 for a handle and 0 for a path.

When bFollowLinks is 1, the server follows a symbolic link and returns metadata for its target.

The result is an RFC 822 formatted string, for example Fri, 21 Nov 1997 09:55:06 -0600.

Returns NULL on failure

More Information and Examples
Get a Remote File's Last-Modified Time
top
GetFileOwner
EXEC sp_OAMethod @sFtp, 'GetFileOwner', @sResult OUT, @pathOrHandle, @bFollowLinks, @bIsHandle

Returns the remote file's owner. pathOrHandle may contain a remote path or a handle returned by OpenFile. Set bIsHandle to 1 for a handle and 0 for a path.

When bFollowLinks is 1, the server follows a symbolic link and returns metadata for its target.

With SFTP v3 and earlier, the result is the decimal numeric UID because textual owner names are not supported.

Returns NULL on failure

More Information and Examples
Get a Remote File's Owner
top
GetFilePermissions
EXEC sp_OAMethod @sFtp, 'GetFilePermissions', @iResult OUT, @pathOrHandle, @bFollowLinks, @bIsHandle

Returns the remote item's complete POSIX mode value. pathOrHandle may contain a remote path or a handle returned by OpenFile. Set bIsHandle to 1 for a handle and 0 for a path. When bFollowLinks is 1, the server follows a symbolic link and returns metadata for its target.

The returned integer includes both the file-type bits and permission bits. For example:

Regular file, mode 0664: octal 0100664, decimal 33204
Regular file, mode 0600: octal 0100600, decimal 33152
Regular file, mode 0644: octal 0100644, decimal 33188

Mask with octal 07777 to obtain permission and special bits, or 0777 for only the traditional owner/group/other read, write, and execute bits. See SetPermissions to change the permissions.

More Information and Examples
Get a Remote File's POSIX PermissionsSFTP Get/Set File Permission
top
GetFileSize32
EXEC sp_OAMethod @sFtp, 'GetFileSize32', @iResult OUT, @pathOrHandle, @bFollowLinks, @bIsHandle

Returns the remote file's size in bytes as a 32-bit integer. pathOrHandle may contain a remote path or a handle returned by OpenFile. Set bIsHandle to 1 for a handle and 0 for a path.

When bFollowLinks is 1, the server follows a symbolic link and returns metadata for its target.

Returns -1 when the size cannot be represented as a 32-bit integer. Use GetFileSize64 or GetFileSizeStr for large files.
More Information and Examples
Get a Remote File's Size (32-bit)SFTP Get Size of File on Server
top
GetFileSizeStr
EXEC sp_OAMethod @sFtp, 'GetFileSizeStr', @sResult OUT, @pathOrHandle, @bFollowLinks, @bIsHandle

Returns the remote file's size in bytes as a decimal string. pathOrHandle may contain a remote path or a handle returned by OpenFile. Set bIsHandle to 1 for a handle and 0 for a path.

When bFollowLinks is 1, the server follows a symbolic link and returns metadata for its target.

Returns NULL on failure

More Information and Examples
Get a Remote File's Size as a StringSFTP Get Size of File on Server
top
GetHostKeyFP
EXEC sp_OAMethod @sFtp, 'GetHostKeyFP', @sResult OUT, @hashAlg, @includeKeyType, @includeHashName
Introduced in version 9.5.0.92

Returns the connected server's host-key fingerprint using hashAlg. Common choices include SHA256, SHA384, SHA512, SHA1, and MD5.

includeKeyTypeincludeHashNameExample format
11ssh-rsa SHA256:L7sQgnpnoBwRoyIYXAFBs8SdSnwtyYmhXs1p/mQDK...
10ssh-rsa L7sQgnpnoBwRoyIYXAFBs8SdSnwtyYmhXs1p/mQDK...
01SHA256:L7sQgnpnoBwRoyIYXAFBs8SdSnwtyYmhXs1p/mQDK...
00L7sQgnpnoBwRoyIYXAFBs8SdSnwtyYmhXs1p/mQDK...
For server identity verification, compare a SHA-256 fingerprint with a value obtained from a trusted source before sending credentials.

Returns NULL on failure

More Information and Examples
Get the SFTP Server Host Key FingerprintSFTP Host Key Fingerprint
top
GetLastJsonData
EXEC sp_OAMethod @sFtp, 'GetLastJsonData', NULL, @json
Introduced in version 11.0.0

Populates json with supplemental details produced by the most recent method when such details are available. Many methods do not produce additional JSON information.

top
GetSyncedFiles
EXEC sp_OAMethod @sFtp, 'GetSyncedFiles', NULL, @strTab
Introduced in version 10.0.0

Appends to strTab the relative paths processed by the most recent SyncTreeUpload or SyncTreeDownload operation.

For downloads, entries can include local directories that were created. Directory paths end with / so they can be distinguished from file paths.

Existing entries in strTab are preserved.
Clear strTab first when only the latest synchronization results are wanted. Downloaded directory entries are reported with a trailing /; uploaded directory entries are reported without one.
More Information and Examples
Get the Files Transferred by an SFTP Sync
top
HardLink
EXEC sp_OAMethod @sFtp, 'HardLink', @success OUT, @oldPath, @newPath
Introduced in version 9.5.0.71

Creates a hard link from newPath to the existing remote file at oldPath.

This method uses the OpenSSH hardlink@openssh.com extension and succeeds only when the server supports that extension.
A successful hard link refers to the same underlying file. Modifying the existing file through either path changes the content observed through the other path.

Returns 1 for success, 0 for failure.

More Information and Examples
Create a Hard Link on an SFTP ServerSFTP HardLink - Create a Hard Link using the hardlink@openssh.com Extension
top
InitializeSftp
EXEC sp_OAMethod @sFtp, 'InitializeSftp', @success OUT

Opens the SFTP subsystem and negotiates the SFTP protocol version. Call this method after connecting and authenticating.

1. Connect
2. AuthenticatePw, AuthenticatePk, or another authentication method
3. InitializeSftp

After success, read ProtocolVersion to determine the negotiated SFTP version.

If opening the SFTP channel fails, inspect InitializeFailCode, InitializeFailReason, and LastErrorText.
Call this method only once for a given SSH connection. A second call on the same connection returns 0. After disconnecting or replacing the connection, authenticate the new connection and call this method again.

Returns 1 for success, 0 for failure.

More Information and Examples
Initialize the SFTP SubsystemError Explained: Received FAILURE response to subsystem request.
top
LastReadFailed
EXEC sp_OAMethod @sFtp, 'LastReadFailed', @success OUT, @handle

Returns 1 if the most recent read associated with handle failed; otherwise returns 0.

A normal end-of-file is not a read failure: the EOF read succeeds, returns zero bytes, and this method returns 0. For an empty, malformed, or already-closed handle, this method returns 1.

More Information and Examples
Check Whether the Last SFTP Read Failed
top
LastReadNumBytes
EXEC sp_OAMethod @sFtp, 'LastReadNumBytes', @iResult OUT, @handle

Returns the number of bytes received by the most recent read associated with handle.

The initial value for a newly opened handle is 0. A normal EOF read and a failed read report 0.

More Information and Examples
Get the Byte Count of the Last SFTP Read
top
OpenDir
EXEC sp_OAMethod @sFtp, 'OpenDir', @sResult OUT, @path

Opens the remote directory specified by path and returns a handle for reading its entries.

handle = OpenDir(path)
ReadDirListing(handle, dirObj)
CloseHandle(handle)

Remote paths use / as the separator. A path beginning with / is absolute; a relative path is interpreted relative to the authenticated user's home directory. An empty path refers to that default directory.

This method does not change a working directory. SFTP is not FTP and has no persistent current-directory command.

Returns NULL on failure

More Information and Examples
Open a Remote Directory on an SFTP ServerUnderstanding SFTP Absolute FilePathsSFTP Read Directory Listing
top
OpenFile
EXEC sp_OAMethod @sFtp, 'OpenFile', @sResult OUT, @remotePath, @access, @createDisposition

Opens or creates the remote file at remotePath and returns a handle for subsequent read or write operations. Close the handle with CloseHandle when finished.

access must be readOnly, writeOnly, or readWrite.

createDisposition is a comma-separated list. It must contain exactly one primary disposition:

Primary dispositionBehavior
createNewCreate a new file; fail if it already exists.
createTruncateCreate a new file, or open and truncate an existing file.
openExistingOpen an existing file; fail if it does not exist.
openOrCreateOpen the file if it exists, otherwise create it.
truncateExistingOpen and truncate an existing file; fail if it does not exist.

Additional optional keywords are:

OptionBehavior
appendDataWrite at the end of the file. Appends are not guaranteed to be atomic.
appendDataAtomicAppend atomically so concurrent appenders do not collide. SFTP v5 or later.
textModeRequest server text-mode processing and canonical newline conversion. SFTP v5 or later.
blockReadRequest exclusive read access. SFTP v5 or later.
blockWriteRequest exclusive write access. SFTP v5 or later.
blockDeletePrevent deletion while the handle is open. SFTP v5 or later.
blockAdvisoryMake the requested block modes advisory. SFTP v5 or later.
noFollowFail if the final path component is a symbolic link. SFTP v5 or later.
deleteOnCloseRequest deletion when the last handle is closed. SFTP v5 or later.
accessAuditAlarmInfoRequest privileges needed to read or write AUDIT or ALARM ACL entries. SFTP v5 or later.
accessBackupRequest backup/restore privileges that may bypass normal access checks. SFTP v5 or later.
backupStreamRead or write a server-specific backup stream. SFTP v5 or later.
Options marked SFTP v5 or later require ForceV3 to be 0 and a negotiated ProtocolVersion of at least 5.
An absolute remote path begins with /. A relative path is interpreted from the authenticated user's home directory. Some servers require a filename in the home directory to be written as ./filename.
Use only documented values: Some servers or Chilkat versions may tolerate an unknown access value, an unknown option, or conflicting primary dispositions, but the resulting behavior is unspecified. Supply one documented access value and exactly one primary disposition.
appendData forces writes to the end of the file, including explicit-offset writes. By itself it opens an existing file but does not create a missing file; combine it with an appropriate primary disposition when creation is required. Options defined for SFTP v5 or later must not be assumed to take effect when an older version is negotiated, even if the open request succeeds.

Returns NULL on failure

More Information and Examples
Open a Remote File on an SFTP ServerSFTP Upload from Local FilesystemUnderstanding SFTP Absolute FilePathsSFTP Where Did My Upload Go?SFTP Upload Large File in PartsSFTP Server Responds with SSH_FX_NO_SUCH_FILE
top
ReadDirListing
EXEC sp_OAMethod @sFtp, 'ReadDirListing', @success OUT, @handle, @dirObj
Introduced in version 11.0.0

Reads all remaining directory entries from handle, which must have been returned by OpenDir, and stores them in dirObj. Entries are returned in server order; Chilkat does not sort the listing.

After end-of-directory has been reached, another call on the same handle returns 1, adds no entries, and sets LastStatusCode to SSH_FX_EOF.

This method does not clear dirObj. Use a new or cleared SFtpDir object when an empty result must replace an earlier listing. Close the directory handle when finished.

Returns 1 for success, 0 for failure.

More Information and Examples
List a Remote Directory on an SFTP Server
top
ReadFileBd
EXEC sp_OAMethod @sFtp, 'ReadFileBd', @success OUT, @handle, @numBytes, @bd
Introduced in version 9.5.0.77

Reads up to numBytes bytes from the current position of the remote file identified by handle and appends them to bd. The handle must have been returned by OpenFile.

Fewer bytes can be read when end-of-file is reached. Repeat the call until Eof(handle) returns 1 to read the entire file incrementally.

This method shares the handle's sequential read position with ReadFileBytes and ReadFileText. Existing bytes in bd are preserved.
More Information and Examples
Read Bytes from a Remote SFTP File (BinData)
top
ReadFileText
EXEC sp_OAMethod @sFtp, 'ReadFileText', @sResult OUT, @handle, @numBytes, @charset

Reads up to numBytes bytes from the current position of handle, decodes the bytes using charset, and returns the resulting text.

See Supported Charsets.

The requested size is measured in bytes, not characters. With a multibyte encoding such as UTF-8 or Shift_JIS, the final character can be split across calls. For robust streaming, read raw bytes and decode with application-maintained state.
Multibyte boundaries: Chilkat does not retain an incomplete multibyte character between calls. If numBytes ends in the middle of a UTF-8 sequence, the first returned string ends with the incomplete bytes and the next call begins with the remaining bytes. Choose byte counts that end on character boundaries, or read bytes and perform streaming decoding in the application.

Returns NULL on failure

More Information and Examples
Read Text from a Remote SFTP File (Sequential)
top
ReadFileText32
EXEC sp_OAMethod @sFtp, 'ReadFileText32', @sResult OUT, @handle, @offset, @numBytes, @charset

Reads up to numBytes bytes from handle at the 32-bit byte offset, decodes the bytes using charset, and returns the resulting text.

See Supported Charsets.

The requested size is measured in bytes, not characters. With a multibyte encoding such as UTF-8 or Shift_JIS, the final character can be split across calls. For robust streaming, read raw bytes and decode with application-maintained state.

Returns NULL on failure

More Information and Examples
Read Text at a 32-bit Offset from a Remote SFTP File
top
ReadFileText64s
EXEC sp_OAMethod @sFtp, 'ReadFileText64s', @sResult OUT, @handle, @offset, @numBytes, @charset

Reads up to numBytes bytes from handle at the byte offset supplied as decimal string offset, decodes the bytes using charset, and returns the resulting text.

See Supported Charsets.

The requested size is measured in bytes, not characters. With a multibyte encoding, the final character can be split across calls.

Returns NULL on failure

More Information and Examples
Read Text at a String Offset from a Remote SFTP File
top
ReadLink
EXEC sp_OAMethod @sFtp, 'ReadLink', @sResult OUT, @path
Introduced in version 9.5.0.71

Returns the target path stored in the symbolic link at remote path.

The returned value is the target string stored in the link. It is not automatically canonicalized and can be relative, absolute, or refer to a nonexistent target.

Returns NULL on failure

More Information and Examples
Read the Target of a Symbolic LinkSFTP ReadLink - Get the Target of a Symbolic Link on the Server
top
RealPath
EXEC sp_OAMethod @sFtp, 'RealPath', @sResult OUT, @originalPath, @composePath

Asks the server to canonicalize originalPath and returns the resulting absolute remote path.

For SFTP v5 or later, composePath may optionally modify or extend the original path; pass an empty string when no composition is needed. If composePath is absolute, it replaces originalPath.

SFTP v3 and v4 do not support path composition. On those versions, composePath is ignored and the method canonicalizes only originalPath.

Returns NULL on failure

More Information and Examples
Resolve an Absolute Remote Path with SFTP RealPath
top
RemoveDir
EXEC sp_OAMethod @sFtp, 'RemoveDir', @success OUT, @path

Deletes the remote directory specified by path.

Most SFTP servers require the directory to be empty before it can be removed.

Returns 1 for success, 0 for failure.

More Information and Examples
Remove a Remote Directory on an SFTP Server
top
RemoveFile
EXEC sp_OAMethod @sFtp, 'RemoveFile', @success OUT, @filename

Deletes the remote file specified by filename.

Returns 1 for success, 0 for failure.

More Information and Examples
Delete a Remote File on an SFTP ServerUnderstanding SFTP Absolute FilePaths
top
RenameFileOrDir
EXEC sp_OAMethod @sFtp, 'RenameFileOrDir', @success OUT, @oldPath, @newPath

Renames or moves a remote file or directory from oldPath to newPath.

oldPath: someDirA/filename
newPath: someDirB/abc/xyz/filename

Returns 1 for success, 0 for failure.

More Information and Examples
Rename or Move a Remote File or Directory
top
ResumeDownloadFileByName
EXEC sp_OAMethod @sFtp, 'ResumeDownloadFileByName', @success OUT, @remoteFilePath, @localFilePath

Resumes downloading remoteFilePath to the local filesystem path localFilePath. Chilkat uses only the existing local file size as the remote starting offset.

  • If the local file is missing or empty, a normal download is performed.
  • If it is smaller, the remaining remote bytes are appended after the existing local length.
  • If it is the same size or larger, the method treats the download as complete and does not truncate or verify the local content.
Important: The existing local bytes are not compared with the remote source. Before resuming, the application must ensure that the local file is the correct prefix of the remote file.

Returns 1 for success, 0 for failure.

More Information and Examples
Resume an Interrupted SFTP DownloadSFTP Resume Download Example
top
ResumeUploadFileByName
EXEC sp_OAMethod @sFtp, 'ResumeUploadFileByName', @success OUT, @remoteFilePath, @localFilePath

Resumes uploading the local file at localFilePath to remoteFilePath. Chilkat uses only the existing remote file size as the local starting offset.

  • If the remote file is missing or empty, a normal upload is performed.
  • If it is smaller, the remaining local bytes are appended after the existing remote length.
  • If it is the same size or larger, the method treats the upload as complete and does not truncate or verify the remote content.
Important: The existing remote bytes are not compared with the local source. Before resuming, the application must ensure that the remote file is the correct prefix of the local file.

Returns 1 for success, 0 for failure.

More Information and Examples
Resume an Interrupted SFTP UploadSFTP Resume Upload Example
top
SendIgnore
EXEC sp_OAMethod @sFtp, 'SendIgnore', @success OUT
Introduced in version 9.5.0.66

Sends an SSH IGNORE message. No SFTP file handle or channel is required.

The server does not send a reply, but a successful send helps verify that the SSH connection is still writable.

Returns 1 for success, 0 for failure.

More Information and Examples
Explaining SFTP RealPathSend an SSH IGNORE Message over SFTP
top
SetAllowedAlgorithms
EXEC sp_OAMethod @sFtp, 'SetAllowedAlgorithms', @success OUT, @json
Introduced in version 9.5.0.99

Configures the exact set of SSH algorithms permitted for subsequent connections using the settings in json.

Call this method before Connect. The connection fails when no mutually supported algorithm remains in a required category.

Returns 1 for success, 0 for failure.

More Information and Examples
SFTP Set Allowed SSH AlgorithmsSFTP Set Allowed Algorithms
top
SetCreateDt
EXEC sp_OAMethod @sFtp, 'SetCreateDt', @success OUT, @pathOrHandle, @isHandle, @createDateTime

Sets the remote file's creation date and time. pathOrHandle may contain a remote path or an open handle. Set isHandle to 1 for a handle and 0 for a path.

SFTP v3 and earlier do not support setting creation time.

createDateTime supplies the new value.

Returns 1 for success, 0 for failure.

top
SetCreateTimeStr
EXEC sp_OAMethod @sFtp, 'SetCreateTimeStr', @success OUT, @pathOrHandle, @bIsHandle, @dateTimeStr

Sets the remote file's creation date and time. pathOrHandle may contain a remote path or an open handle. Set bIsHandle to 1 for a handle and 0 for a path.

Pass the value in dateTimeStr as an RFC 822 formatted string, for example Fri, 21 Nov 1997 09:55:06 -0600.

SFTP v3 and earlier do not support setting creation time.

Returns 1 for success, 0 for failure.

More Information and Examples
Set a Remote File's Creation Time
top
SetLastAccessDt
EXEC sp_OAMethod @sFtp, 'SetLastAccessDt', @success OUT, @pathOrHandle, @isHandle, @accessDateTime

Sets the remote file's last-access date and time. pathOrHandle may contain a remote path or an open handle. Set isHandle to 1 for a handle and 0 for a path.

accessDateTime supplies the new value.

Returns 1 for success, 0 for failure.

top
SetLastAccessTimeStr
EXEC sp_OAMethod @sFtp, 'SetLastAccessTimeStr', @success OUT, @pathOrHandle, @bIsHandle, @dateTimeStr

Sets the remote file's last-access date and time. pathOrHandle may contain a remote path or an open handle. Set bIsHandle to 1 for a handle and 0 for a path.

Pass the value in dateTimeStr as an RFC 822 formatted string, for example Fri, 21 Nov 1997 09:55:06 -0600.

Returns 1 for success, 0 for failure.

More Information and Examples
Set a Remote File's Last-Access Time
top
SetLastModifiedDt
EXEC sp_OAMethod @sFtp, 'SetLastModifiedDt', @success OUT, @pathOrHandle, @isHandle, @modifiedDateTime

Sets the remote file's last-modified date and time. pathOrHandle may contain a remote path or an open handle. Set isHandle to 1 for a handle and 0 for a path.

modifiedDateTime supplies the new value.

Returns 1 for success, 0 for failure.

top
SetLastModifiedTimeStr
EXEC sp_OAMethod @sFtp, 'SetLastModifiedTimeStr', @success OUT, @pathOrHandle, @bIsHandle, @dateTimeStr

Sets the remote file's last-modified date and time. pathOrHandle may contain a remote path or an open handle. Set bIsHandle to 1 for a handle and 0 for a path.

Pass the value in dateTimeStr as an RFC 822 formatted string, for example Fri, 21 Nov 1997 09:55:06 -0600.

When SFTP v3 is negotiated, the stored timestamp has whole-second precision.

Returns 1 for success, 0 for failure.

More Information and Examples
Set a Remote File's Last-Modified Time
top
SetOwnerAndGroup
EXEC sp_OAMethod @sFtp, 'SetOwnerAndGroup', @success OUT, @pathOrHandle, @isHandle, @owner, @group

Sets the owner and group of the remote item identified by pathOrHandle. Set isHandle to 1 for an open handle and 0 for a remote path.

owner and group supply the new textual owner and group values.

SFTP v3 and earlier do not support textual owner and group names.

Returns 1 for success, 0 for failure.

More Information and Examples
Set a Remote File's Owner and Group
top
SetPermissions
EXEC sp_OAMethod @sFtp, 'SetPermissions', @success OUT, @pathOrHandle, @isHandle, @permissions

Sets the POSIX permission bits for the remote item identified by pathOrHandle. Set isHandle to 1 for an open handle and 0 for a remote path.

Pass the permission bits, not the file-type bits. In languages supporting octal integer literals, common values include 0600, 0644, and 0755. Their decimal equivalents are 384, 420, and 493.

After setting permissions, GetFilePermissions returns the complete mode, including the file-type bits. For example, setting 0644 on a regular file can subsequently return 0100644.

Returns 1 for success, 0 for failure.

More Information and Examples
Set a Remote File's POSIX PermissionsSFTP Get/Set File Permission
top
StartKeyboardAuth
EXEC sp_OAMethod @sFtp, 'StartKeyboardAuth', @sResult OUT, @login
Introduced in version 9.5.0.88

Begins keyboard-interactive authentication for login and returns XML describing the server's prompts.

<infoRequest numPrompts="N">
  <name>name_string</name>
  <instruction>instruction_string</instruction>
  <prompt1 echo="1_or_0">prompt_string</prompt1>
  ...
  <promptN echo="1_or_0">prompt_string</promptN>
</infoRequest>

The echo attribute indicates whether the response may be displayed while entered. A value of 0 normally identifies secret input such as a password.

If authentication immediately succeeds or fails, the result has one of these forms:

<success>success message</success>

<error>error message</error>

Returns NULL on failure

More Information and Examples
Start SFTP Keyboard-Interactive Authentication
top
SymLink
EXEC sp_OAMethod @sFtp, 'SymLink', @success OUT, @oldPath, @newPath
Introduced in version 9.5.0.71

Creates a symbolic link on the server. oldPath identifies the link target and newPath identifies the new symbolic-link path.

The server's SFTP implementation determines path interpretation and whether symbolic links are permitted.

Returns 1 for success, 0 for failure.

More Information and Examples
Create a Symbolic Link on an SFTP ServerSFTP SymLink - Create Symbolic Link on Server
top
SyncTreeDownload
EXEC sp_OAMethod @sFtp, 'SyncTreeDownload', @success OUT, @remoteRoot, @localRoot, @mode, @recurse

Synchronizes files from the remote directory remoteRoot to the local filesystem directory localRoot.

ModeBehavior
0Download all files.
1Download files that do not exist locally.
2Download files that are newer remotely or missing locally.
3Download only files that are newer remotely; do not download missing local files.
5Download files that are missing locally or differ in size.
6Mode 5 plus files that are newer remotely.
99Do not download; delete remote files that do not exist locally.

Set recurse to 1 to descend into subdirectories. An absolute remote path begins with /; a relative path is interpreted from the authenticated user's home directory.

Use GetSyncedFiles after the operation to retrieve the relative paths that were downloaded or created.

With SyncCreateAllLocalDirs set to 1, mode 0 creates empty remote directories locally. Mode 1 downloads only missing local files and preserves existing local files. Mode 99 deletes files from the remote tree that are absent locally; it does not delete extra local files.

Returns 1 for success, 0 for failure.

More Information and Examples
Synchronize an SFTP Directory Tree to LocalSFTP Download all Files in a DirectorySFTP Synchronize Directory Tree - Download
top
SyncTreeUpload
EXEC sp_OAMethod @sFtp, 'SyncTreeUpload', @success OUT, @localBaseDir, @remoteBaseDir, @mode, @bRecurse

Synchronizes files from the local filesystem directory localBaseDir to the remote directory remoteBaseDir.

ModeBehavior
0Upload all files.
1Upload files that do not exist remotely.
2Upload files that are newer locally or missing remotely.
3Upload only files that are newer locally; do not upload missing remote files.
4Upload files that are missing remotely or differ in size.
5Mode 4 plus files that are newer locally.

Set bRecurse to 1 to descend into subdirectories. An absolute remote path begins with /; a relative path is interpreted from the authenticated user's home directory.

Use GetSyncedFiles after the operation to retrieve the relative paths that were uploaded.

Mode 0 also creates empty remote directories. Mode 1 uploads only missing files and does not replace an existing remote file merely because the local file is newer; use mode 2 for missing-or-newer behavior. The filename and directory filters are applied during recursive traversal.

Returns 1 for success, 0 for failure.

More Information and Examples
Synchronize a Local Directory Tree to an SFTP ServerSFTP Upload - Synchronize Directory Tree
top
UploadBd
EXEC sp_OAMethod @sFtp, 'UploadBd', @success OUT, @binData, @remoteFilePath
Introduced in version 9.5.0.62

Uploads all bytes in binData to the remote file at remoteFilePath.

If the destination exists, it is truncated before the bytes are uploaded.

Returns 1 for success, 0 for failure.

More Information and Examples
Upload Bytes to an SFTP Server (BinData)SFTP Upload and Download to a BinData Object
top
UploadFile
EXEC sp_OAMethod @sFtp, 'UploadFile', @success OUT, @handle, @fromLocalFilePath

Streams the local filesystem file at fromLocalFilePath to the remote file identified by handle. The handle must have been returned by OpenFile.

Close the remote handle when the upload is complete.

The upload begins at the handle's current sequential write position. Existing bytes before that position are preserved unless the file was truncated when opened.

Returns 1 for success, 0 for failure.

More Information and Examples
Upload to an SFTP Server Using an Open HandleSFTP Upload from Local Filesystem
top
UploadFileByName
EXEC sp_OAMethod @sFtp, 'UploadFileByName', @success OUT, @remoteFilePath, @localFilePath

Uploads the local filesystem file at localFilePath to remoteFilePath.

When PreserveDate is 1, Chilkat preserves the local file's last-modified time on the remote file.

An absolute remote path begins with / and is relative to the server filesystem root. A relative path is interpreted relative to the authenticated user's home directory.
If the destination exists, it is truncated before the upload. A zero-byte local file creates or truncates the remote file to zero bytes. Missing remote parent directories are not created automatically.

Returns 1 for success, 0 for failure.

More Information and Examples
Upload a File to an SFTP ServerSFTP Simplified Upload Example
top
UploadSb
EXEC sp_OAMethod @sFtp, 'UploadSb', @success OUT, @sb, @remoteFilePath, @charset, @includeBom
Introduced in version 9.5.0.62

Encodes the text in sb using charset and uploads it to remoteFilePath.

Set includeBom to 1 to prepend a byte-order mark when the selected encoding supports one.

If the destination exists, it is truncated before the text is uploaded. For utf-8, setting includeBom to 1 prepends the three bytes EF BB BF; setting it to 0 omits them.

Returns 1 for success, 0 for failure.

More Information and Examples
Upload Text to an SFTP Server (StringBuilder)SFTP Upload and Download to a StringBuilder Object
top
WriteFileBd
EXEC sp_OAMethod @sFtp, 'WriteFileBd', @success OUT, @handle, @bd
Introduced in version 9.5.0.77

Appends all bytes in bd to the remote file identified by handle. The handle must have been returned by OpenFile.

Returns 1 for success, 0 for failure.

More Information and Examples
Write Bytes to a Remote SFTP File (BinData)SFTP Upload Large File in Parts
top
WriteFileText
EXEC sp_OAMethod @sFtp, 'WriteFileText', @success OUT, @handle, @charset, @textData

Encodes textData using charset and writes the resulting bytes at the current sequential write position for handle.

The position is maintained by Chilkat for the handle. Opening an existing file with openOrCreate positions sequential writes at the current end of the file. An explicit-offset write can change the position used by the next sequential write. When the file was opened with appendData, writes are forced to the end.

See Supported Charsets.

No byte-order mark or line ending is added unless it is present in the supplied text or produced by the selected encoding.

Returns 1 for success, 0 for failure.

More Information and Examples
Write Text to a Remote SFTP File (Sequential)
top
WriteFileText32
EXEC sp_OAMethod @sFtp, 'WriteFileText32', @success OUT, @handle, @offset32, @charset, @textData

Encodes textData using charset and writes the resulting bytes to handle at the 32-bit byte offset offset32.

After a successful explicit-offset write, the next sequential write begins immediately after the bytes written by this call. If the file was opened with appendData, the server appends and the explicit offset does not control placement.

See Supported Charsets.

offset32 must be nonnegative. A negative value can be interpreted as a very large unsigned offset. Writing beyond end-of-file can create a sparse file; whether the gap is sparse is determined by the server filesystem.
No byte-order mark or line ending is added unless it is present in the supplied text or produced by the selected encoding.

Returns 1 for success, 0 for failure.

More Information and Examples
Write Text at a 32-bit Offset in a Remote SFTP File
top
WriteFileText64s
EXEC sp_OAMethod @sFtp, 'WriteFileText64s', @success OUT, @handle, @offset64, @charset, @textData

Encodes textData using charset and writes the resulting bytes to handle at the byte offset supplied as decimal string offset64.

See Supported Charsets.

No byte-order mark or line ending is added unless it is present in the supplied text or produced by the selected encoding.

Returns 1 for success, 0 for failure.

More Information and Examples
Write Text at a String Offset in a Remote SFTP File
top

Deprecated

AccumulateBuffer
INSERT INTO @tmp EXEC sp_OAGetProperty @sFtp, 'AccumulateBuffer'
This property is deprecated. It will be removed in a future version.

Contains the bytes accumulated by AccumulateBytes. Each call to AccumulateBytes appends newly downloaded bytes to this buffer.

Call ClearAccumulateBuffer to remove all accumulated bytes before beginning a new accumulation sequence.

top
AccumulateBytes
EXEC sp_OAMethod @sFtp, 'AccumulateBytes', @iResult OUT, @handle, @maxBytes
This method is deprecated.

Reads up to maxBytes bytes from the remote file identified by handle and appends them to AccumulateBuffer. The handle must have been returned by OpenFile.

Returns the number of bytes appended. Fewer bytes can be returned when end-of-file is reached. Returns -1 if an error occurs.

top
Add64
EXEC sp_OAMethod @sFtp, 'Add64', @sResult OUT, @n1, @n2
This method is deprecated.

Adds two 64-bit integers supplied as decimal strings and returns the sum as a decimal string.

n1 and n2 are useful in environments that cannot represent 64-bit integer values directly.

Returns NULL on failure

top
ClearAccumulateBuffer
EXEC sp_OAMethod @sFtp, 'ClearAccumulateBuffer', NULL
This method is deprecated.

Removes all bytes from AccumulateBuffer. Call this before starting a new sequence of AccumulateBytes operations.

top
GetFileCreateDt
EXEC sp_OAMethod @sFtp, 'GetFileCreateDt', @ckDateTime OUT, @pathOrHandle, @bFollowLinks, @bIsHandle -- returns a CkDateTime object token
This method is deprecated.

Deprecated: Use GetFileCreateTimeStr instead.

Returns the remote file's creation date and time. pathOrHandle may contain a remote path or a handle returned by OpenFile. Set bIsHandle to 1 for a handle and 0 for a path.

When bFollowLinks is 1, the server follows a symbolic link and returns metadata for its target.

SFTP v3 and earlier do not provide a file creation time.

Returns NULL on failure

top
GetFileLastAccessDt
EXEC sp_OAMethod @sFtp, 'GetFileLastAccessDt', @ckDateTime OUT, @pathOrHandle, @bFollowLinks, @bIsHandle -- returns a CkDateTime object token
This method is deprecated.

Deprecated: Use GetFileLastAccessStr instead.

Returns the remote file's last-access date and time. pathOrHandle may contain a remote path or a handle returned by OpenFile. Set bIsHandle to 1 for a handle and 0 for a path.

When bFollowLinks is 1, the server follows a symbolic link and returns metadata for its target.

Returns NULL on failure

top
GetFileLastModifiedDt
EXEC sp_OAMethod @sFtp, 'GetFileLastModifiedDt', @ckDateTime OUT, @pathOrHandle, @bFollowLinks, @bIsHandle -- returns a CkDateTime object token
This method is deprecated.

Deprecated: Use GetFileLastModifiedStr instead.

Returns the remote file's last-modified date and time. pathOrHandle may contain a remote path or a handle returned by OpenFile. Set bIsHandle to 1 for a handle and 0 for a path.

When bFollowLinks is 1, the server follows a symbolic link and returns metadata for its target.

Returns NULL on failure

top
LastJsonData
EXEC sp_OAMethod @sFtp, 'LastJsonData', @jsonObject OUT -- returns a ChilkatJsonObject object token
Introduced in version 9.5.0.79
This method is deprecated.

Deprecated: Use GetLastJsonData instead.

Returns a JsonObject containing supplemental details produced by the most recent method when such details are available. Many methods do not produce additional JSON information.

Returns NULL on failure

top
ReadDir
EXEC sp_OAMethod @sFtp, 'ReadDir', @sFtpDir OUT, @handle -- returns a ChilkatSFtpDir object token
This method is deprecated and replaced by ReadDirListing

Deprecated: Use ReadDirListing instead.

Reads directory entries from the handle returned by OpenDir and returns an SFtpDir object containing the listing.

Returns NULL on failure

More Information and Examples
Transition from SFtp.ReadDir to SFtp.ReadDirListingSFTP Read Directory Listing
top