Retrieve Method

Description

Retrieve (get) a complete file or part of a file starting at a specified position.

Syntax

Visual Basic
Public Sub Retrieve( _ ByVal RemoteFileName As String, _ Optional ByRef Result As Variant, _ Optional ByVal Marker As Long = 0, _ Optional ByVal MarkerHigh As Long = 0 _ )

Visual Basic

Public Sub Retrieve( _
   ByVal RemoteFileName As String, _
   Optional ByRef Result As Variant, _
   Optional ByVal Marker As Long = 0, _
   Optional ByVal MarkerHigh As Long = 0 _
)

Parameters

RemoteFileName: Specifies the remote file name (with path) to retrieve.
Result: Optional String specifying the (local) destination file name, or an undimensioned String, Byte array, or DartStream object that is dynamically expanded and filled with file data. If not specified or NULL, the FileName parameter (without path) is used as the local file name and put into the current default directory. If Type is ftpZip, and the file is a valid zip file, the file will be decompressed into the directory specified in Result or into the local directory if the value of Result is NULL.
Marker: Optional. Specifies the number of characters that should be skipped. If a file transfer was previously interrupted, the Marker parameter can be used to start at an exact location, so the entire file does not have to be transferred. See the Restart property for more information. If the server does not support restarts and you specify Marker, this method will retrieve the entire file and the Restart property will be set to False.
MarkerHigh: Optional Long. Use in conjunction with Marker to specify the number of bytes to be skipped in a large file. If a file transfer was previously interrupted, Marker and MarkerHigh can be used to start at an exact location greater than 2^31.

Remarks

Sequences and sends (if needed) the following commands (refer to the CommandConstants topic for more information on these commands):

ftpFileStructure
ftpPort or ftpPassive
ftpRestart
ftpRetrieve
ftpSize
ftpTransferMode
ftpType

The Progress and Progress64 events fire as file data and replies are received. If Timeout is greater than 0, Retrieve blocks until the file is received from the server or a ptTimeout error occurs. If Timeout is 0, this method immediately returns. In this case, if the Result parameter is used to capture the data, it must not go out of scope while the command completes (it must have file or global scope).

If Type is ftpZip and the file is a valid zip file, the file will be automatically decompressed into the local directory or the directory specified in Result. Be sure to use care when performing the operation. You will not be able to compare file names in your local directory to file names within the zip file, so any files with the same name will be automatically overwritten. The local directory is the current working directory for your application and can be changed by using the Visual Basic ChDir command. For more advanced zip functionality, please look at PowerTCP Zip Compression for ActiveX at www.dart.com.

MarkerHigh should be set to the value of the restart position divided by 2^31 (2147483648). Marker should be set to the remainder of this operation.

If you wish to use a DartStream object as Result, you must first add a reference to DartSock.dll.

Error Codes

This method may generate the following error code (refer to ErrorConstants for a complete list of error codes):

ptBlocked
ptConnectionAborted
ptConnectionReset
ptNetworkDown
ptNetworkReset
ptNoBufferSpace
ptProtocol (a protocol error was encountered)
ptNotConnected
ptTimeout
zipError

Example

This example demonstrates getting a file and storing it to a string.

Example (VB6)

Private Sub Command1_Click()
	On Error Goto OnError ' use intrinsic error handling
	Dim FileBuf As String ' local scope allowed because Timeout > 0
	Ftp1.Timeout = 1000
	' Get the data without storing it to file
	Ftp1.Retrieve "ftpchallenge.txt", FileBuf
	Text1.Text = FileBuf ' show to user
	Exit Sub
OnError: ' Any error jumps here
	Debug.Print "Error #" + CStr(Err.Number) + ": " + Err.Description
End Sub

This example demonstrates retrieving a zipped file and automatically decompressing it.

Example (VB6)

Private Sub Command1_Click()
	On Error Goto onError

	' Login to the server
	Ftp1.Login "MyServer", "MyUsername", "MyPass"
 
	' Specify the file type as ftpZip, this will cause it to be decompressed 
	' after transfer
	Ftp1.Type = ftpZip
	
	' Retrieve the zip file
	Ftp1.Retrieve "zipped.zip", ""

	' Logout
	Ftp1.Logout

	Exit Sub
onError:
	Debug.Print (Err.Description)
End Sub