Methods, Properties, and Wildcards Overview

Use methods and properties to operate the Transfer Engine. Methods and properties are defined below.

Methods

A method can be described as a command or function that may accept arguments (parameters) and may return a certain type of value. For example:

Boolean Object.LocalExists(BSTR bstrName);

For this method, the type of the return value is Boolean. The command accepts an argument as a string value, here shown as BSTR (the type) and bstrName (a place holder for the argument).

In a program, you can execute a method and assign the return value to a variable all in one command. For example

Exists = MySite.LocalExists "c:\temp\file.txt"

The argument "c:\temp\file.txt exists" is passed to the method LocalExists as a string (reason for the quotes). The variable Exists is then populated with a 1 or a 0 which is, in essence, true or false. You can then perform actions in your script based on those results.

Properties

A property is simply an attribute of a function (another word for method) or object internal to the TE framework. All properties have default values. Methods that rely on these properties will use default values unless you specify otherwise.

Most of the time, you can assign a value to a property or retrieve its value into a variable. You can set a property much like a local variable to your script. For example

String Object.Protocol

The above property can accept a predefined set of string values or can be assigned to a variable to retrieve the currently selected value. The default in this case is "FTP."

You can assign a value to a property as follows:

MySite.Protocol = "FTPS"

Upon subsequent connections, the TE will attempt to login using FTP over SSL, rather then via FTP, the default attribute for this property.

Wildcard Masks

Wildcard masks are patterns of special characters used to filter file names. When a wildcard mask is matched against a file name, the two patterns are compared, letter-by-letter, from left to right until a mismatch occurs. If all the characters in both patterns compare positively, the file name matches the Wildcard Mask.

Wildcard Mask Characters

  • ? Will match any singe character

  • * Will match any sequence of characters (including no characters at all), terminated by the next character in the mask.

  • [ ] Will match any character in the character set enclose

  • If the opening bracket is followed by “!", will match any character NOT in the set.

Available Methods and Properties

Below are descriptions of the methods and properties available to use with the Transfer Engine.

AbortAsync

Use the AbortAsync method to stop an asynchronous task created previously by UploadAsync, DownloadAsync, or TransferURLAsync. Refer to those methods for more information.

HRESULT AbortAsync([in, defaultvalue(-1)] long taskIdx);

Syntax

Object.AbortAsync(long taskIdx)

Parameters

TaskIdx—This is a task index in the array of tasks created by the various asynchronous methods. The default value of taskIdx is - 1 which specifies all the asynchronous tasks in array.

  • TaskIdx should be between 0 and AsyncTaskNumber minus one.

Example

Copy 
Set MySite = CreateObject("CuteFTPPro.TEConnection")
MySite.Option("CleanupAsync") = False
'Initialize all necessary fields for MySite : host name, user, password, etc.
MySite.Connect
MySite.DownloadAsync "*.*", "c:\temp"
MsgBox "Number of tasks created: " & MySite.AsyncTaskNumber
If MySite.AsyncTaskNumber > 10 the
MsgBox "Aborting 11th task"
MySite.AbortAsync ( 10 ) 'abort task # 11 (one less then total, since
  starts from 0)
End if

You must set MySite.Option("CleanupAsync") = False so that all asynchronous tasks are counted. Otherwise, only the last asynchronous task launched will be referenced when calling the AbortAsync method.

AsyncTaskNumber

Use the AsyncTaskNumber property to return the number of tasks created by the UploadAsync, DownloadAsync and TransferURLAsync methods.

HRESULT AsyncTaskNumber([out, retval] long *pVal);

Syntax

Long Object.AsyncTaskNumber

Example

Copy 
Set MySite = CreateObject("CuteFTPPro.TEConnection")
'Initialize all necessary fields for MySite : host name, user, password, etc.
MySite.Option("CleanupAsync") = False
MySite.DownloadAsync "/path/*.*"
MsgBox "task number created" & MySite.AsyncTaskNumber

You must set MySite.Option("CleanupAsync") = False so that all asynchronous tasks are counted. Otherwise, only the last asynchronous task launched will be referenced when calling the AsyncTaskNumber property.

AutoRename

Use the AutoRename property to set or retrieve the renaming values prior to the transfer of a file or folder.

To configure the auto-rename rules, refer to the procedure in Rename Rules Settings.

HRESULT AutoRename([out, retval] BSTR *pVal);

HRESULT AutoRename([in] BSTR newVal);

Syntax

String MySite.AutoRename

Parameters

  • "ON"—AutoRename feature turned on

  • "OFF"—AutoRename feature turned off

Example

MySite.AutoRename = "ON"

CaseHandling

HRESULT CaseHandling([out, retval] long *pVal);

HRESULT CaseHandling([in] long newVal);

ClearCommandChannel

Use the ClearCommandChannel property to specify that the command channel should not be encrypted over SSL.

HRESULT ClearCommandChannel([out, retval] BOOL *pVal);

HRESULT ClearCommandChannel([in] BOOL newVal);

Syntax

long Object.ClearCommandChannel

Parameters

  • True— Your login is encrypted but as data transfers start, commands are not encrypted.

  • False—Your login and subsequent commands are encrypted. This is the default

Example

Copy 
MySite.Host = "host"
MySite.Protocol = "FTPS"
MySite.ClearCommandChannel = true '<-- CCC will be sent prior to the first data connection operation.
MySite.Connect

Configuration Notes

  • The default is false (encrypted), so only set this property if you wish to log in securely but send subsequent commands in the clear.

  • This property will only work if the remote server supports SSL and clear command channel connections (according to RFC 2228) and you have specified FTPS as the protocol type.

ClearDataConnection

Use the ClearDataConnection property to specify whether the data channel should be encrypted or not when using FTP over SSL.

HRESULT ClearDataConnection([out, retval] BOOL *pVal);

HRESULT ClearDataConnection([in] BOOL newVal);

Syntax

long Object.ClearDataConnection

Parameters

  • True—Your login is encrypted but data transfers are not. This is the default.

  • False—Your login and data transfers are encrypted.

Example

Copy 
Set MySite = CreateObject("CuteFTPPro.TEConnection")
MySite.Protocol = "FTPS"
MySite.ClearDataConnection = false 'encrypt FTP data channel

Configuration Notes

  • The default is true (encrypted), so only set this property if you wish to log in securely but transfer data in the clear.

  • This property will only work if the remote server supports SSL and clear data channel connections (PROT C command according to RFC 2228) and you have specified FTPS as the protocol type.

Close

Use the Close method to exit the Transfer Engine. You can include parameters to exit only on certain conditions.

HRESULT Close([in, defaultvalue("BSTR bstrCondition);

Syntax

Object.Close (BSTR bstrParameter)

Parameters

  • ""(default empty), "CLOSE", "EXIT"—Closes TE (all tasks will be stopped)

  • "EXITNOPENDING"—Closes TE if no pending tasks available

You can use any number of spaces or underscores inside these parameters. For example, "exit no pending" and "_EXIT_NO_PENDING_" are the same.

Example

Copy 
Set MySite = CreateObject("CuteFTPPro.TEConnection")
MySite.LocalFolder = "c:\temp"
MySite.TransferURLAsync "ftp://ftp.cuteftp.com/pub/cuteftp"
MySite.Close "EXITNOPENDING"

CombSupport

Use the CombSupport property to check if the server supports the COMB (multi-part upload) command.

HRESULT CombSupport([out, retval] BOOL *pVal);

Syntax

Boolean Object.CombSupport

Return values

  • -1—Server supports COMB

  • 0—Server does not support COMB

Example

Copy 
Set MySite = CreateObject("CuteFTPPro.TEConnection")
'Initialize all necessary fields for MySite : host name, user, password, etc.
If (not MySite.CombSupport) Then
MsgBox "This server doesn't support the COMB command!"
End if

Connect

Use the Connect method to log in to a remote server. Before calling it, set the protocol, host address (with the Host property), user name (with the Login property) and password (with the Password property) to establish a successful connection.

HRESULT Connect([out, retval] BOOL *pVal);

Syntax

Object.Connect

Example

Copy 
Set MySite = CreateObject("CuteFTPPro.TEConnection")
MySite.Protocol = "FTP"
MySite.Host = "ftp.cuteftp.net"
MySite.Login = "username"
MySite.Password = "password"
MySite.Connect

Any time you call a transfer function, the Connect method is called indirectly. It is recommended you explicitly invoke the Connect method, though it is not necessary. You can always use the IsConnected property to determine whether you are connected at any given time.

CreateLocalFolder

Use the CreateLocalFolder method to create a new folder (directory) on your local hard drive.

HRESULT CreateLocalFolder([in, defaultvalue("BSTR strName, [out, retval] BOOL *pVal);

Syntax

Object.CreateLocalFolder(BSTR strName)

Parameters

  • BstrName—This contains the folder's relative or absolute path.

Example

Copy 
Set MySite = CreateObject("CuteFTPPro.TEConnection")
MySite.CreateLocalFolder "c:\temp\New Folder"
Now check to see if it was created
MySite.LocalFolder = "c:\temp\New Folder"
currentdir = MySite.LocalFolder
MsgBox currentdir

CreateRemoteFolder

Use the CreateRemoteFolder method to create a new folder (directory) on a remote server.

HRESULT CreateRemoteFolder([in, defaultvalue("BSTR strName, [out, retval] BOOL *pVal);

Syntax

Object.CreateRemoteFolder(BSTR strName)

Parameters

  • BstrName—This contains the folder's relative or absolute path.

Example

Copy 
Set MySite = CreateObject("CuteFTPPro.TEConnection")
Initialize all necessary fields for MySite : host name, user, password, etc.
MySite.Connect
MySite.CreateRemoteFolder("/dir") 'creates /dir (because absolute path was used)
MySite.RemoteFolder = "/dir" 'now change to the newly create 'dir' folder
MySite.CreateRemoteFolder("dir2") 'creates /dir/dir2 (because relative path was used)

CreateSSHKeyPair

Used to create an SSH Key pair.

HRESULT CreateSSHKeyPair([in] long KeyAlgorithm, [in] long KeyBits, [in] BSTR bstrPassphrase, [in] BSTR bstrPrivateKeyFile, [out, retval] BOOL *pVal);

DataChannel

Use the DataChannel property to set or retrieve values for the method in which the data port is established for the data channel (PASV or PORT). The default is PORT.

HRESULT DataChannel([out, retval] BSTR *pVal);

HRESULT DataChannel([in] BSTR newVal);

Syntax

String Object.DataChannel

Parameters

  • "PORT"—The client specifies what port to use for the data connection

  • "PASV"—Lets the server specify the port used for the data connection port

  • "DEFAULT"—Uses the method defined in Global Options

Example

Copy 
Set MySite = CreateObject("CuteFTPPro.TEConnection")
MySite.Host = "ftp://ftp.cuteftp.com"
MySite.useProxy = "off"
MySite.DataChannel = "PASV"
MySite.RemoteCommand("LIST")
MySite.DataChannel = "PORT"
MySite.RemoteCommand("LIST")
MsgBox MySite.Log

Delay

Use the Delay property to set the delay between connection retry attempts (in seconds).

HRESULT Delay([out, retval] long *pVal);

HRESULT Delay([in] long newVal);

Syntax

int Object.Delay

Example

MySite.Delay = 90

You cannot use the Delay property with transfers; you can only use Delay with connections.

DeleteDestination

HRESULT DeleteDestination([out, retval] BOOL *pVal);

HRESULT DeleteDestination([in] BOOL newVal);

Parameters

  • 0 = Don't remove destination

  • 1 = Remove destination if source does not exist (default)

Disconnect

Use the Disconnect method to end an event in progress. It is normally used to stop a file transfer.

HRESULT Disconnect();

Syntax

Object.Disconnect()

Example

Copy 
Set MySite = CreateObject("CuteFTPPro.TEConnection")
MySite.TransferURLAsync
MySite.Disconnect

Configuration Notes

  • Disconnect is not the same as the standard FTP command QUIT. Instead it is simply a command to stop the current transfer task. You can issue a QUIT command prior to invoking Disconnect by using the RemoteCommand method.

  • A socket disconnect (more brutal than QUIT) to an FTP server occurs automatically after all transfers and other commands have finished. This is similar to the Connect command, which is implicitly called when a transfer method is invoked.

  • The example above uses the TransferURLAsync command to pass the TE an FTP file location to download. Since the TransferURLAsync command is asynchronous, you could called TransferURLAsync multiple times consecutively.

  • If you issue a Disconnect command after issuing multiple TransferURLAsync commands, the last called TransferURLAsync request is the one that is cancelled.

Download

Use the Download method to transfer a file or folder from a remote location to your local hard drive.

HRESULT Download([in, defaultvalue("BSTR bstrRemoteName, [in, defaultvalue("BSTR bstrLocalName, [in, defaultvalue(1)] long nParts, [out, retval] BOOL *pVal);

Syntax

Object.Download (BSTR strRemoteName ,BSTR strLocalName , long nMultiPartNumber)

Parameters

  • strLocalName—This is optional. Use this only if you want to change the destination name or path for the downloaded files or folder. You can use absolute or relative paths.

  • strRemoteName—This is the path to the remote item you are downloading. You can use absolute or relative paths with or without wildcards.

  • nMultiPartNumber—Use this to split the download into multiple parts. The default value = 1. The value specifies the number of parts used for the download.

Example

Copy 
Set MySite = CreateObject("CuteFTPPro.TEConnection")
'Specify user, pass, host, and connect as normal
MySite.Connect 'Recommended: call connect first
'next line changes to a predetermined folder so you can use a relative path in the download method
MySite.RemoteFolder = "/c:/Inetpub/ftproot/Temp/Temp/"
MsgBox (MySite.RemoteFolder) 'display current remote folder
MySite.Download "agent.ini", "c:\temp\agent1.ini"
'now verify downloaded ok
If CBool(MySite.LocalExists ("c:\temp\agent1.ini")) Then
MsgBox "File downloaded OK."
End If

Configuration Notes:

  • Setting the Multi-part download attribute can greatly increase the transfer speed for larger files under certain conditions. For example, the Site must support multiple concurrent connections from the same user and you must have significant bandwidth.

  • The Download method is a synchronous command, meaning it must finish executing before subsequent commands in your script can be called. Use the method DownloadAsync (which also supports Multi-part transfers) to asynchronously download files, which allows you to execute the rest of the script while the download(s) take place.

  • You cannot download and rename multiple files by specifying a wildcard in the strLocalName parameter. For example, MySite.Download "*.exe", "*.txt" will download all of the files in the current remote folder that end with *.exe to a local folder named "_.txt". That is, if you specify a wildcard, the wildcard character is replaced by an underscore ( _ ) character.

DownloadAsync

Use the DownloadAsync method to download a file or folder to the local hard drive asynchronously. An asynchronous download starts and then returns control to the script before the transfer finishes. This allows you to perform many simultaneous transfers because the method does not wait for the download to end. Immediately after you call this method subsequent methods in your script will be called, so be careful when timing certain events.

If DownloadAsync encounters a problem when trying to complete its task, it will not throw a COM, ATL, or VB error. DownloadAsync will also adhere to your max global and per Site settings.

HRESULT DownloadAsync([in, defaultvalue("BSTR strRemoteName, [in, defaultvalue("BSTR strLocalName, [in, defaultvalue(1)] long nParts, [out, retval] BOOL *pVal);

Syntax

Object.DownloadAsync(BSTR strRemoteName ,BSTR strLocalName , long nMultiPartNumber)

Parameters

  • strLocalName—This is optional, use it only if you want to change the destination name or path for the downloaded files or folder. You can use absolute or relative paths with or without wildcards.

  • strRemoteName—This is the path to the remote item you are downloading. You can use absolute or relative paths with or without wildcards.

  • nMultiPartNumber—Use this to split the download into multiple parts. The default value = 1. The value specifies the number of parts used for the download.

Example

Copy 
Set MySite = CreateObject("CuteFTPPro.TEConnection")
MySite.Host = "ftp.cuteftp.com"
MySite.Connect
MySite.DownloadAsync "/pub/cuteftp/english/*", "c:\temp" 'downloads all files in the pub/cuteftp folder

You can call the DownloadAsync method many times sequentially in a script. Each call, in turn, opens a new data connection to the specified server, enabling you to transfer multiple files simultaneously. This, combined with the ability to transfer the file in multiple parts, greatly increases the overall transfer speed and execution of your task.

ErrorDescription

Use the ErrorDescription property to get the string describing the last error condition. It may consist of some messages taken from the transfer log.

HRESULT ErrorDescription([in, defaultvalue(-1)] long taskIdx, [out, retval] BSTR *pVal);

Syntax

String Object.ErrorDescription (long taskIdx)

Parameter

  • TaskIdx—This is a task index in the array of tasks created by the various asynchronous methods. The default value of taskIdx is - 1 which specifies all the asynchronous tasks in array. TaskIdx should be between 0 and AsyncTaskNumber minus one.

Example

Copy 
Set MySite = CreateObject("CuteFTPPro.TEConnection")
MySite.Option("ThrowError") = false 'disable ATL exceptions
if cbool(MySite.Connect) then
MsgBox "Connected OK"
else
MsgBox "Error! " & MySite.ErrorDescription

FileOverWriteMethod

Use the FileOverWriteMethod to specify the action to take when transferring a file when a file with the same name exists. Refer to Smart Overwrite Settings for more information.

HRESULT FileOverWriteMethod([out, retval] BSTR* pVal);

HRESULT FileOverWriteMethod([in] BSTR newVal);

Parameters

  • "OVERWRITE"—Overwrite the file

  • "SKIP"—Do not transfer the file and leave the destination file as it is.

  • "RESUME"— Treat the file as an incomplete transfer. If the destination file is already a complete file, the transferred file replaces the destination file.

  • "RENAME"—Rename the file

  • "PROMPT"—Prompt before overwrtiting

  • "NUMERATE"—Create a copy of the file and add a number to the name

  • "USE_RULES"—Use the rules you define in the Overwrite Rules dialog box in Global Options to determine how to handle all files with matching names.

Examples

Copy 
'Display the current folder overwrite setting
MsgBox( MySite.FolderOverwriteMethod )
'Set folder overwrite to replace all
MySite.FolderOverwriteMethod = "FOLDER_REPLACE_ALL"

FileSize, FileTimeModified, FileType

Use the FileType, FileSize, and FileTimeModified properties to retrieve information about a particular item.

HRESULT FileSize([out, retval] BSTR *pVal);

HRESULT FileTimeModified([out, retval] BSTR *pVal);

HRESULT FileType([out, retval] long *pVal);

Syntax

long Object.FileType

long Object.FileSize

string Object.FileTimeModified

Return Values

  • For FileType:

    • 1—Directory

    • 2—File

    • 3—Link

  • For FileSize: the size in bytes of the file

  • For FileTimeModfied: mm/dd/yyyy hh:mm:ss

Example

Copy 
Set fserv = CreateObject("CuteFTPPro.TEConnection")
strRemote = "somefilename.ext"
if cbool(fserv.RemoteExists(strRemote)) then
MsgBox "Remote file/folder info: Type=" & fserv.FileType & ", Size=" & fserv.fileSize & ", Date=" & fserv.FileTimeModified & strNL & "(type:1-dir,2-file,3-link)"
else
MsgBox "Error! " & fserv.ErrorDescription
End If

FolderOverwriteMethod

Use the FolderOverwriteMethod to specify the action to take when transferring a file when a file with the same name exists. Refer to Smart Overwrite Settings for more information.

HRESULT FolderOverwriteMethod([out, retval] BSTR* pVal);

HRESULT FolderOverwriteMethod([in] BSTR newVal);

Parameters

  • "FOLDER_PROMPT"—Prompt before overwriting

  • "FOLDER_REPLACE_ALL"—Replace (overwrite) all

  • "FOLDER_USE_RULES"—Use the rules you define in the Overwrite Rules dialog box in Global Options to determine how to handle all folders with matching names.

Examples

Copy 
'Display the current overwrite setting
MsgBox( MySite.FileOverWriteMethod )
'Set file overwrite method to numerate
MySite.FileOverWriteMethod = "NUMERATE"

GetList

Use the GetList method to download folder listings.

HRESULT GetList([in] BSTR bstrPath, [in] BSTR bstrLocalFile, [in, defaultvalue("BSTR bstrFormat, [out, retval] BOOL *pVal);

Syntax

Object.GetList(BSTR bstrPath, BSTR bstrLocalFile, BSTR bstrFormat, BOOL *pVal)

Parameters

  • bstrPath—The remote path to be listed. Leave it empty if its the current path.

  • bstrLocalFile—Specifies a local file name where the listing can be saved.

  • bstrFormat—Can be used to format the listing. If left empty, a raw listing will be returned. You can specify %NAME, %DATE, and %SIZE as return values in a string.

Example

Copy 
Set MySite = CreateObject("CuteFTPPro.TEConnection")
MySite.Host = "ftp.cuteftp.com/pub"
MySite.Connect
MySite.GetList "", "c:\temp_list.txt" 'saves a raw listing for the default path to the file temp_list.txt
MsgBox MySite.GetResult 'retrieves and displays the listing

Example 2

Copy 
Set MySite = CreateObject("CuteFTPPro.TEConnection")
MySite.Host = "ftp.cuteftp.com"
MySite.Connect
MySite.GetList "/pub", "", "FILE NAME: %NAME" 'goes to pub folder, doesn't save the listing to file, and formats it as shown
MsgBox MySite.GetResult 'retrieves and displays the listing

Example 3

Copy 
Set MySite = CreateObject("CuteFTPPro.TEConnection")
MySite.Host = "ftp.cuteftp.com"
MySite.Connect
MySite.GetList "/pub", "", "NAME= %NAME SIZE= %SIZE DATE= %DATE"
MsgBox MySite.GetResult 'retrieves and displays the listing

GetList goes to pub folder, doesn't save the listing to file, and formats it as shown

GetResult is an optional method used only with GetList. It simply retrieves the data. Without GetResult the data is written to the buffer, or if defined in the parameters, the data is written to the log.

GetResult

HRESULT GetResult([in, defaultvalue("BSTR bstrReserved, [out, retval] BSTR * bstrResult);

HomeDir

Use the HomeDir property to return a string value containing the name of the server's home directory.

HRESULT HomeDir([out, retval] BSTR *pVal);

Syntax

String Object.HomeDir

Example

Copy 
Set MySite = CreateObject("CuteFTPPro.TEConnection")
'Initialize all necessary fields for MySite : host name, user, password, etc.
MsgBox "Home dir for server " + MySite.Host + " is: " + MySite.HomeDir

Host

Use the Host property to set or retrieve the value for the host name of a Site when you are connecting.

HRESULT Host([out, retval] BSTR *pVal);

HRESULT Host([in] BSTR newVal);

Syntax

int Object.Host

Example

Copy 
Set MySite = CreateObject("CuteFTPPro.TEConnection")
MySite.Protocol = "FTP"
MySite.Host = "ftp.ftp.net"
MySite.Port = 21
MySite.Login = "username"
MySite.Password = "password"

IgnoreLinks

Use the IgnoreLinks property when working with Unix servers. Use IgnoreLinks to set or retrieve the value that determines whether or not you want to bypass links.

HRESULT IgnoreLinks([out, retval] BOOL *pVal);

HRESULT IgnoreLinks([in] BOOL newVal);

Syntax

Bool Object.IgnoreLinks

Parameters

  • True—Skip symlinks during synchronization

  • False—Handle symlinks during synchronization as files or folders

Example

Mysite.IgnoreLinks = False

IsConnected

Use the IsConnected property to indicate whether or not you are presently connected to the remote Site.

HRESULT IsConnected([out, retval] BOOL *pVal);

Syntax

Boolean Object.IsConnected

Parameters

  • True—The Transfer Engine is currently connected to the server.

  • False—The Transfer Engine is not currently connected to the server.

Example

Copy 
Set MySite = CreateObject("CuteFTPPro.TEConnection")
If Cbool(MySite.IsConnected) Then
MsgBox "Connected to server:" + MySite.Host
End if

You can specify how long the Transfer Engine will leave the data connection open after a completed transfer.

IsPending

Use the IsPending property to determine whether a transfer is active or if it is already finished with success or error. This can be useful in combination with async commands or during an interactive script. The IsPending property will return a value of either true or false.

HRESULT IsPending([in, defaultvalue(-1)] long taskIdx, [out, retval] BOOL *pVal);

Syntax

Boolean Object.IsPending(long taskIdx)

Parameter

  • TaskIdx—This is a task index in the array of tasks created by the various asynchronous methods. [0.. AsyncTaskNumber minus one, or - 1 (last asynchronous task started)]

This has a default value (if nothing is specified) of ALL tasks. Therefore, IsPending will return true if any task is still pending. It will return false if none are pending.

Example 1

Copy 
Set MySite = CreateObject("CuteFTPPro.TEConnection")
'Regular connection code here:
MySite.Download inbound/*.*", "c:\temp"
If CBool(MySite.IsPending) Then
MsgBox "task is in working state" + MySite.Host
End if

Example 2

Here is another example that checks an asynchronous transfer and will return various transfer progress properties of each transfer while IsPending is true.

If you copy and paste this code, be aware that line breaks may be inserted into the code.

Copy 
Set MySite = CreateObject("CuteFTPPro.TEConnection")
MySite.Protocol = "FTP"
MySite.Port = "21"
MySite.Host = "ftp.url"
MySite.login = "loginname"
MySite.Password = "your pass"
MySite.Connect
MySite.Option("CleanupAsync") = False
' line break
strNL = (Chr(13) & Chr(10))
MySite.MaxConnections = 3
MySite.Option("ThrowError") = false
MySite.DownloadAsync "inbound/*.*", "c:\temp"
bContinue = true
while CBool(MySite.IsPending) and bContinue
str = "LOOP, Total: " & MySite.AsyncTaskNumber & strNL
for i = 0 to MySite.AsyncTaskNumber - 1 step 1
str = str & i & ": size: " & MySite.TransferredSize(i) & ", speed: " & MySite.Speed(i) & ", time left: " & MySite.TimeLeft(i) & ", status: " & MySite.Status(i) & strNL
next
str = str & "YES - continue loop, NO - stop tasks, CANCEL - exit loop"
nUserChoise = MsgBox(str, vbYesNocancel) 'press YES many time to see transfer progresses
if nUserChoise = vbCancel then
bContinue = false
elseif nUserChoise = vbNO then
MySite.AbortAsync 'abort all tasks
bContinue = false
end if
wend
str = "DONE, Total: " & MySite.AsyncTaskNumber & strNL
for i = 0 to MySite.AsyncTaskNumber - 1 step 1
str = str & i & ": size: " & MySite.TransferredSize(i) & ", speed: " & MySite.Speed(i) & ", time left: " & MySite.TimeLeft(i) & ", status: " & MySite.Status(i) & strNL
next
MsgBox str

Links

Use the Links property to both set and retrieve values for working with links on a remote server.

HRESULT Links([out, retval] BSTR *pVal);

HRESULT Links([in] BSTR newVal);

Syntax

String Object.Links

Parameters

  • "Resolve"—The TE will attempt to resolve the link prior to transfer.

  • "GetAsFile"—The TE will assume it's a file and transfer as is (This is used to avoid endless loops in a large multi-directory transfer).

Example

MySite.Links = "Resolve"

LocalExists

Use the LocalExists method to verify that a local file or folder exists.

HRESULT LocalExists([in, defaultvalue("BSTR bstrName, [out, retval] BOOL * bExists);

Syntax

Boolean Object.LocalExists(BSTR bstrName);

BstrName should be the full path.

Return Values

  • True—File or folder does exist.

  • False—File or folder does not exist.

Example

Copy 
Set MySite = CreateObject("CuteFTPPro.TEConnection")
'Initialize all necessary fields for MySite : host name, user, password, etc.
L = MySite.LocalExists("c:\temp\file.txt")
If (L) Then
MsgBox "File exists on local side"
Else
MsgBox "File doesn't exist on local side"
End if

LocalFilterExclude

Use the LocalFilterExclude property to set and retrieve the values for excluding local files or folders from transfers and listings. The string values may contain wildcards and you can add multiple filters by separating them with a semicolon.

HRESULT LocalFilterExclude([out, retval] BSTR *pVal);

HRESULT LocalFilterExclude([in] BSTR newVal);

Syntax

String Object.LocalFilterExclude

Example

MySite.LocalFilterExclude = "*.mp3;*.jpg"

If filter causes no file to be transferred, then no folders will be created.

LocalFilterInclude

Use the LocalFilterInclude property to set or retrieve the values for including local files or folders in transfers and listings. The string values may contain wildcards and you can add multiple filters by separating them with a semicolon ( : ).

HRESULT LocalFilterInclude([out, retval] BSTR *pVal);

HRESULT LocalFilterInclude([in] BSTR newVal);

Syntax

String Object.LocalFilterInclude

Example

MySite.LocalFilterInclude = "*.jpg;*.gif"

If a filter causes no file to be transferred then no folders will be created.

LocalFolder

Use the LocalFolder property to retrieve or set the current folder on your local hard disk. You can use relative or absolute paths.

HRESULT LocalFolder([out, retval] BSTR *pVal);

HRESULT LocalFolder([in] BSTR newVal);

Syntax

String Object.LocalFolder

Example

Object.LocalFolder = "c:\temp"

LocalRemove

Use the LocalRemove method to delete a local file or folder. Use the absolute path name for the item you want to delete.

HRESULT LocalRemove([in, defaultvalue("BSTR bstrName, [out, retval] BOOL *pVal);

Syntax

Object.LocalRemove(BSTR bstrName)

Parameters

  • BstrName—This contains the items full absolute path.

Example 1

Copy 
Set MySite = CreateObject("CuteFTPPro.TEConnection")
'Initialize all necessary fields for MySite : host name, user, password, etc.
MySite.LocalRemove "c:\temp\file.txt"

You can also use wild cards to replace the string value of bstrName. These wild card masks include "*", "?", and '\n" (new line symbol, also known as Chr(10) in VB).

Example 2

Copy 
Set MySite = CreateObject("CuteFTPPro.TEConnection")
'Initialize all necessary fields for MySite : host name, user, password, etc.
MySite.LocalFolder = "c:\temp"
MySite.LocalRemove("file.ext") 'removes if exact match
MySite.LocalRemove("*.obj") 'wild card match with a specific extension
MySite.LocalRemove("*.aaa" & Chr(10) & "*.bbb" & Chr(10) & "t*") 'various wildcard filters

LocalRename

Use the LocalRename method to rename a file or folder on your local hard disk.

HRESULT LocalRename([in] BSTR bstrFrom, [in] BSTR bstrTo, [out, retval] BOOL *pVal);

Syntax

Object.LocalRename(BSTR bstrFrom, BSTR bstrTo)

Parameters

  • BstrTo—This contains the folder's new name in its full absolute path.

  • BstrFrom—This contains the folder's old name in its full absolute path.

Example

Copy 
Set MySite = CreateObject("CuteFTPPro.TEConnection")
'Initialize all necessary fields for MySite : host name, user, password, etc.
MySite.LocalRename "c:\file.txt", "e:\temp\users\file.exe"

Make sure you specify the full source and destination path. If you had written the command as MySite.LocalRename "c:\file.txt", "file.exe", thinking it would rename it using relative paths, you might be surprised to find that your file has been moved to your profiles folder (system dependent). The LocalRename property is similar to a MOVE command issued through drag and drop with the added name change sequence.

Log

Use the Log property to return the entire log as a string which can be handled separately in your VB application or VB script.

HRESULT Log([in, defaultvalue(-1)] long taskIdx, [out, retval] BSTR *pVal);

Syntax

String Object.Log (long taskIdx)

Parameters

  • TaskIdx—This is the task index in the array of tasks created by asynchronous methods [0.. AsyncTaskNumber minus one, or - 1 (last asynchronous task started)]. It has a default value of -1 = current task.

Example

Copy 
Set MySite = CreateObject("CuteFTPPro.TEConnection")
MySite.Host = "ftp://ftp.cuteftp.com"
MySite.Connect
MsgBox MySite.Log

Login

Use the Login property to set or retrieve the value for the user name (login) you use to connect.

HRESULT Login([out, retval] BSTR *pVal);

HRESULT Login([in] BSTR newVal);

Syntax

String Object.Login

Example

Copy 
Set MySite = CreateObject("CuteFTPPro.TEConnection")
MySite.Protocol = "FTP"
MySite.Host = "ftp.cuteftp.com"
MySite.Login = "username"
MySite.Password = "password"
MySite.Connect

MaxConnections

Use the MaxConnections property to set or retrieve the most connections the script is allowed to open.

HRESULT MaxConnections([out, retval] long *pVal);

HRESULT MaxConnections([in] long newVal);

Syntax

long Object.MaxConnections

Example

Copy 
Set MySite = CreateObject("CuteFTPPro.TEConnection")
MySite.MaxConnections = 1 'restrict connections to 1

Option

Use the Option property to set or retrieve various settings, such as Auto-rename, include folder names when filtering, cache invalidation, error handling, cleaning up of asynchronous tasks, and to auto-close prompts.

HRESULT Option([in] BSTR bstrOptName, [out, retval] BOOL *pVal);

HRESULT Option([in] BSTR bstrOptName, [in] BOOL newVal);

Syntax

String Object.Option("[option name]") = true | false

Parameters

  • "ThrowError"—(defaults to True) - TE COM will call AtlReportError (showing a VB runtime error message box) on connection/transfer/IO/other error which will terminate script execution. If set to False, then if some transfer method fails the script will continue to the next command.

  • "AutoRename"—(defaults to False) - The same as the AutoRename property.

  • "CleanupAsync"—(defaults to True) - All task IDs accumulated by previous Async methods will be lost. If set to False, all task IDs will be added to the ones created by previous Async methods.

  • "InvalidateCache"—(defaults to True) - Remove cached file (containing listings) before uploading, downloading, renaming or deleting files. If false, then don't remove cached listing. You can obtain the specific file information when needed by using one of the file property methods. InvalidateCache optimizes LIST traffic.

  • "FilterDirs"—(defaults to True) - Apply filters to folder names. If set to False, then don't apply.

  • "AutoCloseMethod"—(default to 0) 1 - auto accept, 2 - auto reject, 0 - Don't accept (default). This handles hidden prompts (such as SSL Accept Cert Prompt when running a script while not logged in).

  • "AutoCloseDelay"—(default value is 60 seconds). Time delay before CuteFTP should perform the action specified by the AutoCloseMethod option.

  • "ConnectionTimeout"—'Display connection timeout value

Example 1

Copy 
MsgBox( MySite.Option("ConnectionTimeout") )
'Set connection timeout to 45 seconds
MySite.Option("ConnectionTimeout") = 45
ValidateFileIntegrity
'Display current value of ValidateFileIntegrity
MsgBox( MySite.Option("ValidateFileIntegrity") )
'Turn on ValidateFileIntegrity
MySite.Option("ValidateFileIntegrity") = 1
0=FALSE and 1=TRUE

Example 2

Copy 
Set MySite = CreateObject("CuteFTPPro.TEConnection")
MySite.Host = "ftp://ftp.cuteftp.com"
MySite.Option("FilterDirs")=False 'don't filter folder names
MySite.LocalFilterExclude= "TDImon; *.txt; *.vbs"
'now set the item names to exclude MySite.Upload "c:\test"
'uploads all of test including sub dirs.
'Even sub dirs that match the filter, such as TDIMon.
'If I had left FilterDirs=True, then the folter

'TDImond would not have been uploaded.

Example 3

Copy 
Set MySite = CreateObject("CuteFTPPro.TEConnection")
MySite.Host = "ftp://ftp.somestrangedomain.com"
MySite.Option("ThrowError") = false
if not CBool(MySite.Connect) then
MsgBox "Error : " & MySite.ErrorDescription
end if

Example 4

Copy 
Set MySite = CreateObject("CuteFTPPro.TEConnection")
MySite.Host = "ftps://ftp.asecuredomain.com"
MySite.Option("AutoCloseMethod") = 1
'will auto accept cert and continue
MySite.Option("AutoCloseDelay") = 5
'wait 5 seconds before accepting
MySite.Connect

Now connect to the secure Site. The TE will accept the server's SSL cert after 5 seconds and continue executing the rest of the script.

Password

Use the Password property to set or retrieve the value for the password you use to connect.

HRESULT Password([out, retval] BSTR *pVal);

HRESULT Password([in] BSTR newVal);

Syntax

String Object.Password

Example

Copy 
Set MySite = CreateObject("CuteFTPPro.TEConnection")
MySite.Protocol = "FTP"
MySite.Host = "ftp.ftp.net"
Object.Login = "username"
MySite.Password = "password"
MySite.Connect

Port

Use the Port property to set or retrieve the value for the Port on the server when you connect.

HRESULT Port([out, retval] long *pVal);

HRESULT Port([in] long newVal);

Syntax

int Object.Port

Example

Copy 
Set MySite = CreateObject("CuteFTPPro.TEConnection")
MySite.Protocol = "FTP"
MySite.Host = "ftp.cuteftp.com"
MySite.Port = 21
MySite.Login = "username"
MySite.Password = "password"
MySite.Connect
PromptDelete
HRESULT PromptDelete([out, retval] BOOL *pVal);
HRESULT PromptDelete([in] BOOL newVal);

Parameters

  • 0 = Don't prompt before removing

  • 1 = Prompt before removing (default)

Protocol

Use the Protocol property to set or retrieve the value for the protocol type.

HRESULT Protocol([out, retval] BSTR *pVal);

HRESULT Protocol([in] BSTR newVal);

Syntax

String Object.Protocol

Parameters

  • "FTP"—File Transfer Protocol

  • "FTPS"—FTP using SSL in explicit mode (standard port 21)

  • "FTPS_IMPLICIT"—Extension of FTP using SSL -- FTP using SSL in implicit mode (specific port)

  • "FTPS_AUTH_TLS"—AUTH TLS - Explicit

  • "SFTP"—Secure protocol based on SSH2

  • "FTP_SKEY_MD4"—Secure one time password login using MD4

  • "FTP_SKEY_MD5"—Secure one time password login using MD5

  • "HTTP"—Hypertext Transfer Protocol

  • "HTTPS"—HTTP with SSL

Example

Copy 
Set MySite = CreateObject("CuteFTPPro.TEConnection")
MySite.Protocol = "FTPS_IMPLICIT"
MySite.Host = "ftp.ftp.net" >
MySite.Port = 990
MySite.Login = "username"
MySite.Password = "password"
MySite.Connect

You can find more options for using SSL in ClearDataConnection.

ProxyInfo

Use the ProxyInfo property to set or retrieve FTP and HTTP proxy server configurations. Do not use this function if you do not connect through a proxy server.

HRESULT ProxyInfo([out, retval] BSTR *pVal);

HRESULT ProxyInfo([in] BSTR newVal);

Syntax

String Object.ProxyInfo

Authentication Parameters

  • "ftp://proxyusername:proxypassword@proxyhostname:proxyport"—For FTP proxies that require authentication.

  • "http://proxyusername:proxypassword@proxyhostname:proxyport"—For HTTP proxies that require authentication.

  • "ftp://proxyhostname:proxyport"—For FTP proxies that don't require Authentication.

  • "http://proxyhostname:proxyport"—For HTTP proxies that don't require Authentication.

  • Additional parameters

  • "proxyusername"—The user name for login to the proxy server

  • "proxypassword"—The password for login to the proxy server

  • "proxyhostname"—The proxy server address

  • "proxyport"—The proxy server connection port

Example 1

MySite.ProxyInfo = http://globalscape.com:8000 'use http proxy without authorization

Example 2

MySite.ProxyInfo = ftp://joeuser:maypass@globalscape.com:21 'use ftp proxy with authorization for user "joesuser" & password "mypass"

Example 3

Copy 
'retrieve the current value of SocksInfo (empty if none)
str = MySite.SocksInfo
'now display it
MsgBox str

Recursive

Use the Recursive property to set or retrieve the value that determines whether or not subfolders will be included in a transfer task. This property is used often in synchronization scripts.

HRESULT Recursive([out, retval] BOOL *pVal);

HRESULT Recursive([in] BOOL newVal);

Syntax

Bool Object.Recursive

Parameters

  • True—Include subfolders

  • False—Do not include subfolders

Example

Mysite.Recursive = True

RemoteCommand

Use the RemoteCommand method to send the server any supported command. This function acts like the raw input command found in CuteFTP.

There is no resume method; however, you can use the RemoteCommand method to send the APPE (Append) command to a server. APPE is the FTP command to resume a transfer.

The RemoteCommand method exists to allow you to pass any command to the server manually, even if that command is not natively supported through the TE API.

HRESULT RemoteCommand([in] BSTR bstrCmd, [out, retval] BOOL *pVal);

Syntax

Object.RemoteCommand(BSTR bstrCmd)

Examples

Copy 
MySite.RemoteCommand "APPE html/test.txt"
Set MySite = CreateObject("CuteFTPPro.TEConnection")
'Initialize all necessary fields for MySite : host name, user, password, etc.
MySite.RemoteCommand "PWD" 'sends a print working directory command

If you include the word "LIST", or "RETR", or "STOR" in bstrCmd then the Transfer Engine will open the data connection, perform the operation (to the buffer) and then discard it. You should use the GetList, Download or Upload methods to accomplish these tasks.

You can combine strings to perform custom commands. For example, if you wanted to do use CHMOD on a file, you could do as shown in the example below:

Copy 
'Initialize all necessary fields for MySite : host name, user, password, etc.
Set MySite = CreateObject("CuteFTPPro.TEConnection")
'full permissions
strMODE = "777"
'an input dialog with some default content
strFile = InputBox("Type in the file name below ", "CHMOD Dialog", "cftppro10.log")
'concatenate the values
strvar = "SITE CHMOD " & strMODE & " " & strFile
'send the command
MySite.RemoteCommand strvar

RemoteExists

Use the RemoteExists method to verify that a remote file or folder exists.

HRESULT RemoteExists([in, defaultvalue("BSTR bstrName, [out, retval] BOOL * bExists);

Syntax

Boolean Object.RemoteExists(BSTR bstrName)

BstrName should be the full path.

Return Values

  • true—File or folder does exist

  • false—File or folder does not exist

Example

Copy 
Set MySite = CreateObject("CuteFTPPro.TEConnection")
'Initialize all necessary fields for MySite : host name, user, password, etc.
R = MySite.RemoteExists( "/pub/user/file.txt")
If (R) Then
MsgBox "File exists on remote side"
Else
MsgBox "File doesn't exist on remote side"
End if

If using an "if not" conditional, use CBool instead of boolean as the return type.

Correct:

Copy 
if not CBool(MySite.RemoteExists(strRemote)) then
MsgBox "Error! " & MySite.ErrorDescription

Incorrect:

Copy 
if not MySite.RemoteExists(strRemote) then
MsgBox "Error! " & MySiteErrorDescription

RemoteFilterExclude

Use the RemoteFilterExclude property to set and retrieve the values for excluding remote files or folders from transfers and listings. The string values may contain wildcards and you can add multiple filters by separating them with a semicolon.

HRESULT RemoteFilterExclude([out, retval] BSTR *pVal);

HRESULT RemoteFilterExclude([in] BSTR newVal);

Syntax

String Object.RemoteFilterExclude

Example

Copy 
MySite.RemoteFilterExclude = "*.txt;*.swp"
MySite.Download "*.*"

The example will download all files except those with extensions of *.txt and *.swp.

If filter causes no file to be transferred then no folders will be created.

RemoteFilterInclude

Use the RemoteFilterInclude property to set or retrieve the values used to include remote files or folders in transfers and listings. The string values may contain wildcards and you can add multiple filters by separating them with a semicolon ";".

HRESULT RemoteFilterInclude([out, retval] BSTR *pVal);

HRESULT RemoteFilterInclude([in] BSTR newVal);

Syntax

String Object.RemoteFilterInclude

Example

MySite.RemoteFilterInlcude = "*.jpg;*.gif"

If filter causes no file to be transferred then no folders will be created.

RemoteFolder

Use the RemoteFolder property to retrieve or set the current remote folder. You can use absolute or relative paths.

HRESULT RemoteFolder([out, retval] BSTR *pVal);

HRESULT RemoteFolder([in] BSTR newVal);

Syntax

String Object.RemoteFolder

Example

Copy 
'Connect to site following previous samples
MySite.RemoteFolder = "/pub/cuteftp" 'Changes the remote folder to /pub/cuteftp (absolute paths used)
'subsequently
MySite.RemoteFolder = "test" 'Changes to the folder called "test" located in "/pub/cuteftp", using relative paths.

RemoteRemove

Use the RemoteRemove method to delete a remote file or folder. You can specify the file or folder with absolute or relative paths. If the command fails, make sure you have specified the correct path and that you have the appropriate permissions required to delete the item.

HRESULT RemoteRemove([in, defaultvalue("BSTR bstrName, [out, retval] BOOL *pVal);

Syntax

Object.RemoteRemove(BSTR bstrName)

Parameters

  • BstrName—This contains the folder's relative or absolute path.

Example

Copy 
Set MySite = CreateObject("CuteFTPPro.TEConnection")
'Initialize all necessary fields for MySite : host name, user, password, etc.
MySite.RemoteRemove "/pub/user1/file.txt"
MySite.RemoteRemove("file.ext") 'removes if exact match
MySite.RemoteRemove("*.obj") 'wild card match with a specific extension
MySite.RemoteRemove("*.aaa" & Chr(10) & "*.bbb" & Chr(10) & "t*") 'various wildcard filters

You can also use wild cards to replace the string value of bstrName. These wild card masks include "*", "?", and '\n" (new line symbol, also known as Chr(10) in VB).

RemoteRename

Use the RemoteRename method to rename a file or folder on the remote server.

HRESULT RemoteRename([in] BSTR bstrFrom, [in] BSTR bstrTo, [out, retval] BOOL *pVal);

Syntax

Object.RemoteRename(BSTR bstrFrom, BSTR bstrTo)

Parameters

  • BstrFrom—This contains the folder's old name in a relative or absolute path. The path must be the same in both parameters.

  • BstrTo—This contains the folder's new name in a relative or absolute path. The path must be the same in both parameters.

Example

Copy 
Set MySite = CreateObject("CuteFTPPro.TEConnection")
'Initialize all necessary fields for MySite : host name, user, password, etc.
MySite.RemoteRename "/pub/user1/file.txt", "/pub/user1/file3.txt"

RemoteSiteFilter

Use the RemoteSiteFilter property to specify a string which will be used as a filter parameter by the LIST command.

HRESULT RemoteSiteFilter([out, retval] BSTR *pVal);

HRESULT RemoteSiteFilter([in] BSTR newVal);

Syntax

string Object. RemoteSiteFilter

Example

Copy 
Set MySite = CreateObject("CuteFTPPro.TEConnection")
MySite. RemoteSiteFilter = "-l"

This will send a "List -l" command to the server.

Configuration Notes

Refer to Filtering Transfers for a table of LIST wildcards (parameters) and combinations that can be passed to the ls program running on a UNIX server.

RestSupport

Use the RestSupport property to check if the server supports the REST (resume download) command.

HRESULT RestSupport([out, retval] BOOL *pVal);

Syntax

Boolean Object.RestSupport

Return values

  • -1—Server supports REST.

  • 0—Server does not support REST.

Example

Copy 
Set MySite = CreateObject("CuteFTPPro.TEConnection")
'Initialize all necessary fields for MySite : host name, user, password, etc.
If (not cbool(MySite.RestSupport)) Then
MsgBox "This server doesn't support the REST command"
End if

Retries

Use the Retries property to retrieve or set the value for the maximum number of attempts the Transfer Engine should make to connect to a remote host.

HRESULT Retries([out, retval] long *pVal);

Syntax

int Object.Retries

Example

MySite.Retries = 10

You cannot use the Retries property with transfers; you can only use Retries with connections.

S2Sxfer

Use the S2Sxfer method to transfer a file from one remote Site to another. You must use absolute path names for the source and target folders.

HRESULT S2Sxfer([in] BSTR bstrSourceName, [in] BSTR bstrDestName, [in] BSTR bstrPeerHost, [in] BSTR bstrPeerLogin, [in] BSTR bstrPeerPassword, [in, defaultvalue(21)] long Port, [in, defaultvalue("ftpBSTR bstrPeerProtocol, [out, retval] BOOL *pVal);

Syntax

Boolean Object.S2Sxfer(BSTR bstrSourceName, BSTR bstrDestName, BSTR bstrPeerHost, BSTR bstrPeerLogin, BSTR bstrPeerPassword, long Port, BSTR bstrPeerProtocol);

Parameters

  • bstrSourceName—source file and folder name

  • bstrDestName—target file and folder name

  • bstrPeerHost—target host name

  • bstrPeerLogin—target login

  • bstrPeerPassword—target password

  • Port—target port

  • BstrPeerProtocol—target protocol (FXP can be applied for hosts with different protocols FTP, FTP-S)

Return values

true—Transfer was successful

false—Transfer failed

Example

Copy 
Set MySite = CreateObject("CuteFTPPro.TEConnection")
'Initialize all necessary fields for MySite : host name, user, password, etc.
MySite.Connect
MySite.S2Sxfer "/cftppro14.log", "/home/myfolder/cftppro14.log", "ftp.destinationhost.com", "username", "passwrd" 'everything else left as default

SocksInfo

Use the SocksInfo property to set or retrieve values for SOCKS4 or SOCKS5 servers. (SOCKS is a protocol for a TCP proxy across firewalls.)

HRESULT SocksInfo([out, retval] BSTR *pVal);

HRESULT SocksInfo([in] BSTR newVal);

Syntax

String Object.SocksInfo

Authentication Parameters

  • "socks4://socksusername:sockspassword@sockshostname:socksport"—For SOCKS4 servers that require authentication.

  • "socks5://socksusername:sockspassword@sockshostname:socksport"—For SOCKS5 servers that require authentication.

  • "socks4:// sockshostname:socksport"—For SOCKS4 servers that do not require authentication.

  • "socks5:// sockshostname:socksport"—For SOCKS5 servers that do not require authentication.

Additional parameters

  • "socksusername"—The user name or log in name to the SOCKS server.

  • "sockspassword"—The password for the SOCKS server.

  • "sockshostname"—The address and port for the SOCKS server.

Example 1

MySite.SocksInfo = "socks4//globalscape.com:1080" 'use socks4 without authorization

Example 2

MySite.SocksInfo = "socks5://joeuser:mypass@globalscape.com:1080" 'use socks5 with authorization for user "joeuser" with password "mypass"

Example 3

Copy 
'retrieve the current value of SocksInfo (empty if none)
str = MySite.SocksInfo
'now display it
MsgBox str

Speed

Use the Speed property to determine a transfer's progress and various other aspects of the transfer.

See also the TimeLeft, TimeElapsed, TotalSize, and TransferredSize properties below.

HRESULT Speed([in, defaultvalue(-1)] long taskIdx, [out, retval] long *pVal);

Syntax

long Object.Speed (long taskIdx) = bytes/second

Parameters

  • TaskIdx—This is the task index in the array of tasks created by asynchronous methods [0.. AsyncTaskNumber minus one, or - 1 (last asynchronous task started)] It has a default value of - 1 = current task.

Example

Copy 
Set MySite = CreateObject("CuteFTPPro.TEConnection")
'st all relavant host, login, pass, etc. properties
MySite.Host = host
MySite.Download "aaa", "c:\temp"
MsgBox "Size: " & MySite.TotalSize & ", speed: " & MySite.Speed & ", time: " & MySite.TimeElapsed

Status

Use the Status property to determine whether a transfer is active or it is already finished with success or error. This can be useful in combination with asynchronous commands or during an interactive script. The Status property will return a string.

HRESULT Status([in, defaultvalue(-1)] long taskIdx, [out, retval] BSTR *pVal);

Syntax

String Object.Status (long taskIdx)

Parameters

  • TaskIdx—This is the task index in the array of tasks created by asynchronous methods [0.. AsyncTaskNumber or - 1 (last started)]

Return Values

  • "WAIT"—Transfer action invoked but not initiated yet (followed by connecting)

  • "CANCELED"—Active transfer canceled by user

  • "FINISHED"—Transfer completed

  • "ERROR"—Error in transfer (any possible client or server error)

  • "SUSPENDED"—Added to queue but no transfer initiated yet

  • "SCHEDULED"—Item is scheduled for future transfer

  • "BLOCKED"—An internal status used for navigation and does not pertain to active or pending transfers. You can cancel any transfer requests in BLOCKED status without any ill effects.

  • "CHILDWAIT"—Condition when transfer item is waiting for a dependant item to finish transferring (*)

  • "SKIPPED"—Transfer skipped by user or automatically per overwrite rules

  • "CONNECTING"—Connecting to server (status right after WAIT)

  • "CANCELLING"—Cancel initiated but not completely stopped yet

  • "WORKING"—After connecting but before transferring. Could be opening data connection, or setting REST params, etc.

  • "TRANSFERRING"—File transfer in progress

  • "UNKNOWN"—Another string was returned other than one of the above. The string was unrecognized.

Example

Copy 
Set MySite = CreateObject("CuteFTPPro.TEConnection")
If not CBool(MySite.IsPending) Then
MsgBox "Task done, final status is " + MySite.Status
End if

Synchronize

Use the Synchronize method to perform one or two way mirrors of a remote and local folder's contents.

HRESULT Synchronize([in, defaultvalue("BSTR bstrRemoteName, [in, defaultvalue("BSTR bstrLocalName, [in, defaultvalue(0)] long nDirection, [in, defaultvalue(0)] long nAction, [in, defaultvalue(0)] long nCasehandling, [in, defaultvalue(TRUE)] BOOL bRecursive, [in, defaultvalue(TRUE)] BOOL bIgnoreLinks, [in, defaultvalue(FALSE)] BOOL bDelDestination, [in, defaultvalue(TRUE)] BOOL bPromptDel, [out, retval] BOOL *pVal);

Syntax

Object.Synchronize(BSTR bstrRemoteName, BSTR bstrLocalName, long nDirection, long nAction, long nCasehandling, BOOL bRecursive, BOOL bIgnoreLinks, BOOL bDelDestination, BOOL bPromptDel);

Parameters

Be sure to use absolute path names for both local and remote folder paths.

# Name Value
1 BstrRemoteName String value that specifies the absolute path name of the remote folder
2 BstrLocalName String value that specifies the absolute path name of the local folder
3 nDirection 0 = Mirror Local (make the remote look just like the local) 1 = Mirror Remote (make the local look just like the remote) 2 = Mirror Both
4 nAction

When nDirection = 2 (Mirror Both) 0 = Mirror the more recent file 1 = Mirror the larger file 2 = Prompt for matching file names 3 = Skip mirroring files with the same names

When nDirection = 0 or 1 (Mirror Local or Remote) 0 = Use Global Overwrite settings in the CuteFTP shell for matching filenames 1 = Always overwrite the file with a matching name 2 = Numerate the file (filename[1]) 3 = Skip
5 nCaseHandling 0 = Transfer first and skip the rest (default) 1 = Show rename prompt 2 = Numerate Note: This action applies when matching filenames are found and the only difference is the filename case.
6 bRecursive 0 = Don't sync subfolders 1 = Apply sync to subfolders (default)
7 bIgnoreLinks 0 = Don't ignore symbolic links 1 = Ignore symbolic links (default)
8 bDelDestination 0 = Don't remove destination 1 = Remove destination if source does not exist (default) Note: This action only applies to one-way mirroring. If a file exists in the destination that isn't in the source being mirrored, then delete the destination file.
9 bPromptDel 0 = Don't prompt before removing destination 1 = Prompt before removing destination (default) Note: Only applies to one-way mirroring when DelDestination is True.

Example

Copy 
'Simple synchronize using minimal parameters

Set MySite = CreateObject("CuteFTPPro.TEConnection")

'Don't forget to initialize all necessary fields for MySite : host name, user, password, etc.

MySite.Connect

MySite.Synchronize "/pub/myfolder", "C:\mysitesfiles", 0, 1

'This will perform a local mirror, overwriting any matching filename.

'Simple synchronize using minimal parameters

Set MySite = CreateObject("CuteFTPPro.TEConnection")

'Don't forget to initialize all necessary fields for MySite : host name, user, password, etc.

MySite.Connect

MySite.Synchronize "/pub/myfolder", "C:\mysitesfiles", 2, 0

'This will perform full mirror (both), overwriting older files when a matching filename is found.

'Slightly more complex synchronize routine used to synchronize bookmarks. Uses variables for the path names

strRemotePath = "\Favorites"

strLocalPath = "C:\Documents and Settings\username\Favorites"

'Don't forget to initialize all necessary fields for MySite : host name, user, password, etc.

MySite.Connect

If (Not (MySite.IsConnected)) Then

MsgBox "Unable to connect to server:" + MySite.Host

End if

MySite.Synchronize strRemotePath, strLocalPath, 2, 3, 0, 1, 1, 0, 1

'Performs a full mirror, skips matching filenames, transfers only the first file if multiple files are found with the same name but different case, applies to subfolders, ignores symbolic links, does not remove destination files if the source doesn't exist (N/A when dealing with dual mirror), and prompt prior to deleting anything (N/A when dealing with dual mirror).

'Alert me to the completed task

MsgBox "DONE!"

'Disconnects from the site when done

MySite.Disconnect

'Close the Transfer Engine process

MySite.Close

'A full synchronizaiton VB subroutine:

Sub Sync()

Dim MySite

Set MySite = CreateObject("CuteFTPPro.TEConnection")

strHost = "ftp.yourhost.com"

strPath = "/pub"

strLocalPath = "c:\temp\sync_test"

strHost = InputBox("Enter host", "CuteFTP", strHost)

strPath = InputBox("Enter remote path", "CuteFTP", strPath)

strLocalPath = InputBox("Enter local path", "CuteFTP", strLocalPath)

MySite.Host = strHost

MySite.CaseHandling = 1

MySite.Recursive = False

MySite.IgnoreLinks = True

MySite.DeleteDestination = False

MySite.PromptDelete = True

nUserChoise = MsgBox ("Mirror remote: " & strHost & strPath & " to local " & strLocalPath & " ?", vbYesNoCancel)

If nUserChoise = vbYes Then

MySite.Synchronize strPath, strLocalPath, 1, 0

else

nUserChoise = MsgBox ("Mirror local: " & strHost & strLocalPath & " to remote " & strPath & " ?", vbYesNoCancel)

If nUserChoise = vbYes Then

MySite.Synchronize strPath, strLocalPath, 0, 0

else

nUserChoise = MsgBox ("Mirror both: " & strHost & strPath & " <- > " & strLocalPath & " ?", vbYesNoCancel)

If nUserChoise = vbYes Then

MySite.Synchronize strPath, strLocalPath, 2, 1

else

End if

End if

End if

End Sub

TECommand

Use the TECommand method to pass various commands to the Transfer Engine component. If you leave the Transfer Engine running for a long time, it is recommended you include the DELETEFINISHED or DELETEALL in your scripts to occasionally empty the queue. The Transfer Engine does not empty the queue automatically.

HRESULT TECommand([in] BSTR bstrCommand);

Syntax

Object.TECommand(BSTR bstrParameter)

Parameters

  • "CLOSE" or "EXIT"—Closes the TE (all tasks will be stopped)

  • "EXITNOPENDING"—Closes the TE if no pending tasks are available

  • "UPDATESETTINGS"—Reloads settings from the registry (Note you can modify the registry from VBS)

  • "DELETEFINISHED"—Removes finished items from queue

  • "DELETEALL"—Removes all items from queue

You can use any number of spaces or underscores inside these parameters. For example, "update setting" and "_UPDATE_SETTINGS_" are the same.

If the Transfer Engine has several tasks, or must run for a long time, you should include the DELETEFINISHED command in your scripts to occasionally clear items from the queue.

Example

Copy 
Set MySite = CreateObject("CuteFTPPro.TEConnection")
MySite.TECommand("DELETEFINISHED")

TimeElapsed

Use the TimeElapsed property to determine a transfer's progress.

HRESULT TimeElapsed([in, defaultvalue(-1)] long taskIdx, [out, retval] long *pVal);

Syntax

long Object.TimeElapsed (long taskIdx) =seconds

Parameters

  • TaskIdx—This is the task index in the array of tasks created by asynchronous methods [0.. AsyncTaskNumber minus one, or - 1 (last asynchronous task started)] It has a default value of - 1 = current task.

Example

Copy 
Set MySite = CreateObject("CuteFTPPro.TEConnection")
'set all relavant host, login, pass, etc. properties
MySite.Host = host
MySite.Download "aaa", "c:\temp"
MsgBox "Size: " & MySite.TotalSize & ", speed: " & MySite.Speed & ", time: " & MySite.TimeElapsed

TimeLeft

Use the TimeLeft property to determine how many seconds are left before a transfer is complete.

HRESULT TimeLeft([in, defaultvalue(-1)] long taskIdx, [out, retval] long *pVal);

Syntax

long Object.TimeLeft (long taskIdx) = seconds

Parameters

  • TaskIdx—This is the task index in the array of tasks created by asynchronous methods [0.. AsyncTaskNumber minus one, or - 1 (last asynchronous task started)]. It has a default value of - 1 = current task.

Example

Copy 
Set MySite = CreateObject("CuteFTPPro.TEConnection")
'set all relavant host, login, pass, etc. properties
MySite.Host = host
MySite.Download "aaa", "c:\temp"
MsgBox "Size: " & MySite.TotalSize & ", speed: " & MySite.Speed & ", time: " & MySite.TimeElapsed

TotalSize

Use the TotalSize property to determine the total file size of a transfer.

See also TransferredSize below.

HRESULT TotalSize([in, defaultvalue(-1)] long taskIdx, [out, retval] BSTR *pVal);

Syntax

long Object.TotalSize (long taskIdx) = size in bytes

Parameters

  • TaskIdx—This is the task index in the array of tasks created by asynchronous methods [0.. AsyncTaskNumber minus one, or - 1 (last asynchronous task started)]. It has a default value of - 1 = current task.

Example

Copy 
Set MySite = CreateObject("CuteFTPPro.TEConnection")
'set all relavant host, login, pass, etc. properties
MySite.Host = host
MySite.Download "aaa", "c:\temp"
MsgBox "Size: " & MySite.TotalSize & ", speed: " & MySite.Speed & ", time: " & MySite.TimeElapsed

TransferredSize

Use the TransferredSize property to determine the size after a file has been transferred and possibly compressed.

HRESULT TransferredSize([in, defaultvalue(-1)] long taskIdx, [out, retval] BSTR *pVal);

Syntax

long Object.TransferredSize (long taskIdx) = size in bytes

Parameters

  • TaskIdx—This is the task index in the array of tasks created by asynchronous methods [0.. AsyncTaskNumber minus one, or - 1 (last asynchronous task started)]. It has a default value of - 1 = current task.

Example

Copy 
Set MySite = CreateObject("CuteFTPPro.TEConnection")
'set all relavant host, login, pass, etc. properties
MySite.Host = host 'set all relavant host, login, pass, etc. properties
MySite.Download "aaa", "c:\temp"
MsgBox "Size: " & MySite.TotalSize & ", speed: " & MySite.Speed & ", time: " & MySite.TimeElapsed

TransferType

Use the TransferType property to retrieve or set the value for the way the Transfer Engine should transfer files (ASCII, binary or auto).

HRESULT TransferType([out, retval] BSTR *pVal);

Syntax

String Object.TransferType

Parameters

  • "ASCII"—All files should be transferred in ASCII mode

  • "BINARY"—All files should be transferred in BINARY mode

  • "AUTO" (default)—The TE will reference an internal list editable from CuteFTP's Global Options to determine the proper transfer type for that particular file. For example, if the ASCII list contains a filter mask of "txt" then all files with extension ".txt" will be transferred in ASCII. If a file doesn't correspond to any mask in this list then it will be transferred in binary mode.

Example

Copy 
Object.TransferType = "AUTO"
'the Transfer Engine will use the shell's default settings to establish whether the transfer should occur in binary or ASCII.
'write file transfer code next

TransferURL

Use the TransferURL method to download files directly from a Web address.

HRESULT TransferURL([in] BSTR bstrRemoteName, [in, defaultvalue(1)] long nParts, [out, retval] BOOL *pVal);

Syntax

Object.TransferURL(BSTR bstrRemoteName, long nMultipartNumber)

Parameters

  • bstrRemoteName—This is a string value for the URL for the file transfer such as: (ftp://ftp.globalscape.com/pub/cuteftp/cuteftp.exe).

  • nMultipartNumber—This is optional and will split a file into parts for transfer. The default = 1.

Example

Copy 
Set MySite = CreateObject("CuteFTPPro.TEConnection")
MySite.TransferURL "ftp://ftp.globalscape.com/pub/cuteftp/cuteftp.exe"

The TE recognizes these URL formats:

  • ftp://user:pass@ ftp.sitename.com:port

  • ftp://user:pass@ ftp.sitename.com

  • ftp://user@ ftp.sitename.com

  • ftp:// ftp.sitename.com:port

  • ftp:// ftp.sitename.com

  • ftp://ftp.sitename.com/pub l: user p: pass ß l: user is a lowercase "L", not "one"

  • ftp://ftp.sitename.com/pub:44 l: user p: pass

  • ftp://ftp.sitename.com/pub port:44 l: user p: pass

  • ftp://ftp.sitename.com/pub l/p: user/pass

  • ftp://ftp.sitename.com/pub:44 l/p: user/pass

  • ftp://ftp.sitename.com/pub p:44 l/p: user/pass

  • ftp://ftp.sitename.com/pub port:44 l/p: user/pass

  • ftp://ftp.sitename.com/pub l: user p: pass

  • ftp://ftp.sitename.com/pub:44 l: user p: pass

  • ftp://ftp.sitename.com/pub p:44 l: user p: pass

  • ftp://ftp.sitename.com/pub port:44 l: user p: pass

TransferURLAsync

Use the TransferURLAsync method to start a download from a web address, and return control to the script immediately. This method does not wait for the transfer to end. You can use it to perform many simultaneous transfers.

  • The difference between this method and DownloadAsync is simply the ability to specify all of the necessary parameters in one command, rather than having to set the user name, port, host, etc. and then transfer a file.

  • Immediately after you call this method subsequent methods in your script will be called, so be careful when timing certain events.

  • If TransferURLAsync encounters a problem when trying to complete its task, it will not throw a COM, ATL, or VB error. TransferURLAsync will also adhere to your max global and per site settings. You can't use wildcards in this method.

HRESULT TransferURLAsync([in] BSTR bstrRemoteName, [in, defaultvalue(1)] long nParts, [out, retval] BOOL *pVal);

Syntax

Object.TransferURLAsync(BSTR bstrURL [, long nMultipartNumber])

Parameters

  • bstrURL—A string value for the URL for the file transfer (ftp://ftp.cuteftp.com/pub/cuteftp)

  • nMultipartNumber—An optional multipart parameter with default = 1

Example

Copy 
Set MySite = CreateObject("CuteFTPPro.TEConnection")
MySite.TransferURLAsync "ftp://ftp.cuteftp.com/pub/cuteftp/english"
'this will transfer the entire English CuteFTP directory from the CuteFTP.com ftp site.

Normal Formats Supported

  • ftp://user:pass@ ftp.sitename.com:port

  • ftp://user:pass@ ftp.sitename.com

  • ftp://user@ ftp.sitename.com

  • ftp:// ftp.sitename.com:port

  • ftp:// ftp.sitename.com

  • ftp://ftp.sitename.com/pub l: user p: pass ß l: user is a lowercase "L", not "one"

  • ftp://ftp.sitename.com/pub:44 l: user p: pass

  • ftp://ftp.sitename.com/pub port:44 l: user p: pass

  • ftp://ftp.sitename.com/pub l/p: user/pass

  • ftp://ftp.sitename.com/pub:44 l/p: user/pass

  • ftp://ftp.sitename.com/pub p:44 l/p: user/pass

  • ftp://ftp.sitename.com/pub port:44 l/p: user/pass

  • ftp://ftp.sitename.com/pub l: user p: pass

  • ftp://ftp.sitename.com/pub:44 l: user p: pass

  • ftp://ftp.sitename.com/pub p:44 l: user p: pass

  • ftp://ftp.sitename.com/pub port:44 l: user p: pass

Extended URL Formats

Aside from the standard URL formats shown above, additional specifiers may be used to denote the direction of transfer and download path. Use the extended format to perform site to site transfers, uploads, targeted downloads, and more.

The standard url ftp://user:pass@ftp.host.com will be used in the following examples:

  • Format: Normal URL transfer

    • MySite.TransferURLAsync "ftp://user:pass@ftp.host.com"

    • 'download site to the default download folder

  • Format: URL [space] "-->" [space] LPATH

    • MySite.TransferURLAsync "ftp://user:pass@ftp.host.com --> c:\temp"

    • 'download site to the c:\temp folder

  • Format: URL [space] "<--" [space] LPATH

    • MySite.TransferURLAsync "ftp://user:pass@ftp.host.com <-- c:\web"

    • 'upload files from c:\web to the site

  • Format: URL1 [space] "<->" [space] URL2

    • MySite.TransferURLAsync "ftp://user:pass@ftp.host.com <->

    • ftp://user2:pass2@ftp.host2.com" 'perform a site to site transfer

  • Format: URL [space] "<==" [space] LPATH

    • MySite.TransferURLAsync "ftp://user:pass@ftp.host.com <== c:\web"

    • 'synchronize (mirror local) the c:\web folder to the site

  • Format: URL [space] "==>" [space] LPATH

    • MySite.TransferURLAsync "ftp://user:pass@ftp.host.com ==> c:\web"

    • 'synchronize (mirror remote) the site to c:\web

  • Format: URL [space] "<=>" [space] LPATH

    • MySite.TransferURLAsync "ftp://user:pass@ftp.host.com <=> c:\web"

    • 'synchronize both local and remote (mirror both)

Upload

Use the Upload method to transfer a file or folder from a local hard drive to a remote server.

HRESULT Upload([in, defaultvalue("BSTR bstrLocalName, [in, defaultvalue("BSTR bstrRemoteName, [in, defaultvalue(1)] long nParts, [out, retval] BOOL *pVal);

Syntax

Object.Upload(BSTR strLocalName ,BSTR strRemoteName , long nMultiPartNumber)

Parameters

  • strRemoteName—This is optional; use it only if you want to change the destination name or path for the uploaded files or folders. You can use absolute or relative paths.

  • strLocalName—This is the path to the local item you are uploading. You can use absolute or relative paths with or without wildcards.

  • nMultiPartNumber—Use this to split the upload into multiple parts. The default value = 1. The value specifies the number of parts used for the download.

Example

Copy 
Set MySite = CreateObject("CuteFTPPro.TEConnection")
'Specify user, pass, host, and connect as normal...
MySite.Connect 'r;Recommended: call connect first
MySite.RemoteFolder = "Temp"
MySite.LocalFolder = "C:\123"
'using relative path, all files in folder 123 are uploaded to the folder Temp off the current folder on the server.
MySite.Upload "*.*"

Configuration Notes

  • You can only use multi-part uploads with servers that support the COMB command. Currently, only Globalscape EFT Server supports the COMB command.

  • Setting the Multi-part upload attribute can greatly increase the transfer speed for larger files under certain conditions. For example, the site must support multiple concurrent connections from the same user and you must have significant bandwidth.

  • The Upload method is a synchronous command, meaning it must finish executing before subsequent commands in your script can be called. Use the method UploadAsync (which also supports Multi-part transfers) to synchronously upload files, which allows you to execute the rest of the script while the upload(s) take place.

  • You cannot upload and rename multiple files by specifying a wildcard in the strRemoteName parameter. For example, MySite.Upload "*.exe", "*.txt" will upload all of the files in the current local folder that end with *.exe to a remote folder named "_.txt". That is, if you specify a wildcard, the wildcard character is replaced by an underscore ( _ ) character.

UploadAsync

Use the UploadAsync method to upload a file or folder to a remote server asynchronously. An asynchronous upload starts and then returns control to the script before the transfer finishes. This allows you to perform many simultaneous transfers because the method does not wait for the upload to end.

Immediately after you call this method subsequent methods in your script will be called, so be careful when timing certain events.

If UploadAsync encounters a problem when trying to complete its task, it will not throw a COM, ATL, or VB error. UploadAsync will also adhere to your max global and per site settings.

HRESULT UploadAsync([in, defaultvalue("BSTR strLocalName, [in, defaultvalue("BSTR strRemoteName, [in, defaultvalue(1)] long nParts, [out, retval] BOOL *pVal);

Syntax

Object.UploadAsync(BSTR strLocalName [,BSTR strRemoteName [, long nMultiPartNumber]])

Parameters

  • strRemoteName—This is optional, use it only if you want to change the destination name or path for the uploaded files or folders. You can use absolute or relative paths with or without wildcards.

  • strLocalName—This is the path to the local item you are uploading. You can use absolute or relative paths with or without wildcards.

  • nMultiPartNumber—Use this to split the upload into multiple parts. The default value = 1. The value specifies the number of parts used for the download.

Example

Copy 
Set MySite = CreateObject("CuteFTPPro.TEConnection")

'Initialize all necessary fields for MySite : host name, user, password, etc.

MySite.Connect

MySite.UploadAsync "c:\temp\*.vob", "/DVDFiles" 'uploads as many .vob files as concurrent connection settings allow

The multi-part parameter for the UploadAsync is currently limited to servers that support this operation, due to the need to recombine the files after the upload of each part has completed. Globalscape EFT Server supports this function.

UseProxy

Use the UseProxy property to retrieve or set the value for the type of SOCKS or proxy server that is being (or should be) used. Since OFF is the default, you don't need UseProxy for regular connections which do not pass through proxy or SOCKS servers.

HRESULT UseProxy([out, retval] BSTR *pVal);

HRESULT UseProxy([in] BSTR newVal);

Syntax

String Object.UseProxy

Parameters

  • "OFF"—Direct connection without any socks and proxy

  • "SOCKS"—SOCKS server only - the user must specify the SOCKS parameters by setting the SocksInfo property

  • "PROXY"—Proxy server only - the user must specify the proxy server parameters by setting the ProxyInfo property

  • "BOTH"—Use both SOCKS and proxy - the user should specify the appropriate information for both the proxy and the socks server with ProxyInfo and SocksInfo.

Example

Copy 
'specify that socks will be used, then configure SocksInfo
Object.UseProxy = "SOCKS"
Object.SocksInfo = "socks5://globalscape.com:1080"
'Rest of connection code follows

Wait

Use the Wait method to tell the Transfer Engine to hold all other tasks until a specific asynchronous task is completed. Then continue with the rest of the script.

HRESULT Wait([in, defaultvalue(-1)] long taskIdx, [in, defaultvalue(0)] long timeout, [out, retval] BSTR * pStatus);

Syntax

String Object.Wait (long taskIndex, long timeout)

Parameters

  • taskIndex—This is the task index in the asynchronous tasks array. The default = -1 (which is current task). It can range from 0 to the total number of tasks minus one.

  • timeout—Determines how long (in milliseconds) to wait for a finished, cancelled, or error status before continuing with the script.

Return Values

  • "CANCELLED"—Transfer was stopped by the user

  • "FINISHED"—Transfer was successfully finished

  • "ERROR"—There were errors during the transfer

  • "SKIPPED"—The transfer was skipped (file overwrite rules)

Example

Copy 
'Initialize all necessary fields for MySite : host name, user, password, etc.
Set MySite = CreateObject("CuteFTPPro.TEConnection")
MySite.TransferURLAsync "ftp://ftp.cuteftp.com/pub/cuteftp"
strResult = MySite.Wait
If (strResult = "ERROR") then
MsgBox "warning! An error has occurred!"
End if

Configuration Notes

  • The default timeout value for the Wait method is 21,805,184 milliseconds, or approximately 6 hours.

  • The maximum possible value for timeout is 2,147,483,647 milliseconds, or just under 25 days.

  • You can set the Wait method to never timeout by using a timeout value of 0 (zero).

  • For hints on Wait method timeouts, see Timeout strategies, below.

WriteToLOG

Use the WriteToLOG method to write a message directly to the connection log saved in the path set in CuteFTP's global options. It is useful for documenting events to aid in script debugging.

HRESULT WriteToLOG([in] BSTR bstr, [in, defaultvalue("statusBSTR bstrType);

Syntax

Object.WriteToLOG(BSTR bstr , BSTR bstrType)

Parameters

  • bstr—The log message.

  • bstrType—A log message, type: "STATUS", "ERROR", "NOTE", "COMMAND", "RAW". The default is "STATUS".

Example

Copy 
'Initialize all necessary fields for MySite : host name, user, password, etc.
Set MySite = CreateObject("CuteFTPPro.TEConnection")
MySite.TransferURLAsync "ftp://ftp.cuteftp.com/pub/cuteftp"
strResult = MySite.Wait
If (strResult = "FINISHED") then
MySite.WriteToLOG "Transfer successful!!"
MySite.WriteToLOG "Transfer successful!!", "error"
MySite.WriteToLOG "Transfer successful!!", "note"
End if
As result, the log will contain the following strings:
STATUS: > Transfer successful!!
ERROR: > Transfer successful!!
Note > Transfer successful!!

Timeout Strategies for the Wait Method

The default timeout value for the Wait method is 21,805,184 milliseconds, which is approximately 6 hours. The timeout value is a SIGNED LONG data type, meaning its maximum possible value is 2,147,483,647 milliseconds, which is roughly 596.5 hours or just under 25 days. This is likely enough time for even the slowest transfer.

The Wait method supports a "0" timeout value which means "keep waiting forever or until the transfer reaches a state of CANCELED, FINISHED, ERROR, SUSPENDED, SKIPPED, or BLOCKED."

You can also write scripts so that they check the condition of a transfer and if it is still in the "TRANSFERRING" state, to wait on it again.

Three timeout strategies for long transfer tasks

  1. Specify a large timeout value in the script call - Because the first parameter to the Wait method is a task index, this example uses a "-1" which means "current task." For this example, the timeout is set for 10 hours or, 10 * 60 * 60 * 1000 = 36000000 milliseconds.

    • Example: strResult = strataFTP.Wait( -1, 36000000 )

  1. After a Wait() function has timed out, check the STATUS of the transfer - In this scenario, use the program (or script) logic to keep trying after a Wait times out when the transfer is still in the TRANSFERRING state. In other words, your polling for the termination status has timed out, but not necessarily the transfer itself, so you keep going.

In the following example, you wait up to 10 hours for the transfer, and if that times out, you check the status of the transfer. If it is still TRANSFERRING, you do it again (please note the last two conditional statements):

Example 1

Copy 
Do
strResult = strataFTP.Wait( -1, 36000000 )
Loop While ( strResult <> "CANCELED") and ( strResult <> "FINISHED" ) and
( strResult <> "ERROR" ) and ( strResult <> "SKIPPED" ) and
( strResult <> "SUSPENDED" ) and ( strResult <> "BLOCKED" )

Alternatively, you can take the more positive outlook of continuing on while the transfer task is either WORKING, CONNECTING, or TRANSFERRING:

Example 2

Copy 
Do
strResult = strataFTP.Wait( -1, 36000000 )
Loop While ( strResult = "TRANSFERRING") or ( strResult = "WORKING" ) or
( strResult = "CONNECTING" )

  1. Wait forever, or until the transfer reaches some termination point. Most transfers eventually either FINISH or receive an error from the server; but there is a minor chance that the transfer in the queue is perpetually stuck in a "TRANSFERRING" state. This strategy might be considered a little riskier than the first two.

    • Example: strResult = strataFTP.Wait( -1, 0 )