FTP Client Engine
Library for Visual Basic
Programmer's Manual
(FCE4VB)
Version 2.7
July 10, 2008
This software is provided as-is.
There are no warranties, expressed or implied.
Copyright (C) 2008
All rights reserved
MarshallSoft Computing, Inc.
Post Office Box 4543
Huntsville AL 35815
Voice : 1.256.881.4630
email : info@marshallsoft.com
web : www.marshallsoft.com
MARSHALLSOFT is a registered trademark of MarshallSoft Computing.
1 Introduction
1.1 Features2 Library Overview
1.2 Documentation Set
1.3 Example Program
1.4 Installation
1.5 Uninstalling
1.6 Pricing
1.7 Updates
2.1 Dynamic Link Libraries3 Compiler Issues
2.2 Keycode
2.3 Dynamic Strings
2.4 Using the FCE Library
2.5 FCE4VB Class
2.6 VB.NET and Visual Studio
2.7 VBA Applications
2.8 Power Builder
2.9 Adding FCE4VB to A Project
2.10 Error Display
3.1 Visual Basic Makefiles4 Example Programs
3.2 Compiling FCE
3.3 Compiling Example Programs
4.1 FCEVER5 Revision History
4.2 GET
4.3 WINFTP
4.4 SPEED
4.5 HELLO
4.6 LIST
4.7 PROXY
4.8 MGET
4.9 MPUT
4.10 MDTM
The FTP Client Engine for Visual Basic (FCE4VB) library is a toolkit that allows software developers to quickly develop FTP client applications in Visual Basic and Visual Studio / VB.NET.
The FTP Client Engine (FCE) uses the Windows API to provide direct and simple control of the FTP protocol. The FCE component library can be used for both anonymous and private FTP sessions.
A straightforward interface provides the capability to easily build Visual Basic FTP software applications to connect to any FTP server, navigate its directory structure, list files, upload files, rename files, delete files, append files, and download files using the FTP protocol.
This FTP Client Engine Programmers Manual provides information need to compile and run programs in a Visual Basic programming environment.
The FTP Client Engine for Visual Basic component library supports and has been tested with all versions of Microsoft Visual Basic including Visual Studio .NET. FCE4VB includes numerous Visual Basic examples. All Visual Basic programs will compile using VB-4.0 through VB-6.0. Visual Studio VB.Net examples are also included.
FCE4VB runs under all versions of 32-bit Windows (Windows 95, Windows 98, Windows ME, Windows 2000, Windows 2003, Windows NT, Windows XP and Windows Vista). The FTP Client Engine SDK DLL (SEE32.DLL) can also be used from any development environment (Visual Basic, VB .NET, Delphi, Visual FoxPro, COBOL, Xbase++, dBase, PowerBASIC, etc.) capable of calling the Windows API.
FCE4VB functions can also be called from Visual Basic for Applications (VBA) environments such as Excel, Microsoft Office, and Access. FCE4VB also works with Power Builder.
When comparing the FTP Client Engine component library against our competition, note that:
MarshallSoft also has versions of the FTP Client Engine Library for C/C++ (FCE4C), Delphi (FCE4D), PowerBASIC (FCE4PB), Visual FoxPro (FCE4FP), Visual dBASE (FCE4DB), and Xbase++ (FCE4XB). All versions of FCE use the same DLL (FCE32.DLL). However, the examples provided for each version are written for the specified computer language.
All versions of the FTP Client Engine Library (FCE) can be downloaded from our web site at http://www.marshallsoft.com/ftp-client-library.htm
Some of the many features of the FTP Client Engine component library are as follows:
The complete set of documentation consists of three manuals in two formats. This is the first manual (FCE_4VB) in the set.
Each manual comes in two formats:
The FCE_4VB Programmer's Manual is the language specific (Visual Basic) manual dealing with compiler and programming issues such as installation and example programs. Read this manual first.
The FCE User's Manual (FCE_USR) discusses basic FTP processing as well as language independent programming issues such as application notes and includes purchasing and license information. Read this manual second.
The FCE Reference Manual (FCE_REF) contains details on each individual FCE function.
All manuals can also be viewed online at http://www.marshallsoft.com/fce4vb.htm
The following example demonstrates the use of some of the FTP Client Engine library functions:
' 32-bit VB code segment
Dim Code As Long
' attach FCE
Code = fceAttach(1, FCE_KEY_CODE)
If Code < 0 Then
Print "Error connecting"
Exit Sub
End If
' connect to server
Code = fceConnect(0, "ftp.marshallsoft.com", "anonymous",
"msc@traveller.com")
' change to proper directory
Code = fceSetServerDir(0, "pub/other")
' set to ASCII xfer mode
Code = fceSetMode(0, ASC("A"))
' download the file
Code = fceGetFile(0, "products.txt")
' QUIT
Code = fceClose(0)
Code = fceRelease()
In the example program above, fceConnect is called to connect to the FTP server as user "anonymous" and password "msc@traveller.com".
The server directory is changed to "pub/other", the transfer mode is set to ASCII, and the file "products.txt" is downloaded. Lastly, the connection to the FTP server is closed and FCE is released.
Refer to the FCE Reference Manual (FCE_REF) for individual function details. Access online at http://www.marshallsoft.com/fce_ref.htm
VB 4.0, VB 5.0 and VB 6.0 project filenames end with "32.vbp" and VB.NET and Visual Studio project filenames end with "vbproj." For example,
FCEVER32.VBP --- Project file for 32-bit Visual Basic (VB_4.0,5.0,6.0).
FCEVER32.VBPROJ --- Project file for VB.NET / Visual Studio
Note that the Windows registry is not modified.
Uninstalling FCE4VB is very easy. FCE does not modify the registry or any Windows system files.
First, run UNINSTAL.BAT, which will delete FCE32.DLL from the Windows directory, typically C:\WINDOWS for Windows 95/98/Me/XP/Vista or C:\WINNT for Windows NT/2000.
Second, delete the FCE project directory created when FCE4VB was installed.
A developer's license for FCE4VB can be purchased for $115 ($295 with ANSI C source code to the DLL). Purchasing details can be found in Section 1.3, "How to Purchase", of the FCE User's Manual (FCE_USR). (http://www.marshallsoft.com/fce_usr.htm#Section_1.3)
When a developer license is purchased for FCE, the developer will be sent a registered DLL plus a license file (FCEExxxx.LIC). The license file can be used to update the registered DLL for a period of one year from purchase. Updates can be downloaded from
http://www.marshallsoft.com/oem.htm
After one year, your license must be updated if you want to be able to download updates. Your license can be updated for $30 if ordered within one year of the original purchase (or previous update). Between one year and three years, licenses can be updated for $55. After three years, updates are $75.
Note that the registered DLL's never expire.
Updates to the source code can be purchased for $100 in addition to the cost of the update ($30 or $55).
Also see file UPDATES.TXT.
The FTP Client Engine library is implemented as a dynamic link library (DLL). A DLL is characterized by the fact that it need not be loaded until required by an application program and that only one copy of the DLL is necessary regardless of the number of application programs that use it. Contrast this to the traditional static library that is bound to each and every application that uses it at link time.
An important advantage that DLL's have over other "popular" library formats such as VBX or OCX is that DLL's are callable by all Windows applications. Since DLL's are the building blocks of the Windows Operating System, they will not be replaced by a "newer technology".
FCE32.DLL has a keycode encoded within it. The keycode is a 9 or 10 digit decimal number (unless it is 0), and will be found in the file KEYCODE.BAS (and KEYCODE.VB). The keycode for the evaluation version is 0. The developer will receive a new key code after registering. SETUP copies your keycode to the /APPS sub-directory (folder). The KEYCODE is passed to fceAttach.
If the error message (value -74) is returned when calling fceAttach, it means that the keycode in the application does not match the keycode in the DLL. After registering, it is best to remove the evaluation version of the FCE DLL from the Windows search.
The Visual Basic language uses a technique known as "garbage collection" to manage string space at runtime and may be called internally at any time by the Visual Basic runtime, asynchronous to what you may be doing in your code.
When passing a string buffer to a DLL function into which text will be copied, it is strongly recommended that the local string be allocated immediately before use. For example, a string buffer is passed to the user defined dllGetMessage function , which copies a text message into it. Note that SPACE$(80) is called immediately before dllGetMessage.
Dim Code As Integer
Dim Buffer As String * 80
' allocate buffer just before call to dllGetMessage
Buffer = SPACE$(80)
' copy message into 'Buffer'
Code = dllGetMessage(Buffer, 80)
' message text is now in 'Buffer'
This technique is not necessary for passing a string to a DLL function, only when passing a buffer to a DLL into which data is to be placed by the DLL function.
The FTP Client Engine component library has been tested on multiple computers running Windows 95/98/Me/NT/2000/2003/XP/Vista and Windows NT/2000..
The FCE4VB library has been tested with all versions of Microsoft Visual Basic including Visual Studio .NET. The SETUP installation program will copy the DLL to the Windows directory. Refer to Section 1.4 "Installation". After SETUP is run, the FCE4VB files are copied to the directory specified (default \FCE4VB). Three sub-directories are created, as follows:
DOCS - All documentation files
APPS - All example code
DLLS - All DLL's
The FCE class "fceClass" (fceClass.cls) is a Visual Basic class wrapper for making calls to FCE32.DLL. The class name for each function is the same as the DLL function except the leading "fce" is replaced by "f".
Those functions that return strings do so by use of the "String Result" property. Instantiate fceClass as any other class in Visual Basic:
Dim C As New fceClass
Also see the FCE4VB Reference Manual (FCE_REF), the example project "HELLO32" and the file fceClass.txt.
The use of fceClass is limited to Visual Basic 5.0 and above since previous versions of Visual Basic do not support classes.
There are a few differences between VB 4/5/6 and VB.NET/Microsoft Visual Studio that affect writing programs that use FCE.
Variables that are declared "As Long" in VB 4/5/6 are declared "As Integer" in Visual Studio / VB.Net.
Fixed length strings are not supported in Visual Studio / VB.Net. When calling any FCE function that can return a string (fceGetString for example), memory for the string variable must be allocated first. For example:
Buffer = Space(80)
Code = fceGetString(0, FCE_GET_REGISTRATION, Buffer, 80)
Some VB functions must be fully qualified. For example, instead of LEFT, use Microsoft.VisualBasic.Left
The module FCE32.VB (not FCE32.BAS) must be included in all VB.Net programs. See the HELLO.VB example program.
The FTP Client Engine component library can be used with Microsoft VBA applications such as EXCEL, ACCESS, and Microsoft Office.
Start EXCEL (or other 32-bit Office VBA program such as MS Publisher, WORD or ACCESS), then enter design mode. Enable the "Controls Toolbox", choose "Tools" on the menu bar, then "Customize", and then check "Control Toolbox". From the control toolbox, choose and position a "Command Button". This will create code that looks like
Private Sub CommandButton1_Click()
End Sub
Replace the generated code with MODULE32.BAS. The easiest way to do this is to paste from the clipboard. Edit the 'HostName' in this code, using the name of the computer (or IP address in dotted decimal notation) where the server application (see SERVER.VBP) is running. Exit design mode and then press the command button to start this example program.
Also see VBA modules DNLOAD32.BAS (which downloads a file) and UPLOAD32.BAS (which uploads a file).
FCE can also be used with Power Builder applications. See PBUILDER.TXT for more information.
FCE.PBI : Power Builder declaration file.
Copy FCE32.BAS (if running VB 4/5/6), or FCE32.VB (if running VB.Net) to the same directory (folder) as the application program to which you want to add FCE code. You will find these files in the APPS directory (folder) created when you ran SETUP, usually C:\FCE4VB\APPS.
Open an existing project with "File", "Open Project". Then choose "Insert", "Module", then add FCE32.BAS and KEYCODE.BAS to the project. If prompted to add "DAO 2.50 Object Library", choose "no". FCE functions can now be called from your VB program.
Open an existing project with "File", "Open Project". Then choose "Project", "Add Module", then add FCE32.VB and KEYCODE.VB to the project. FCE functions can now be called from your Visual Studio / VB.NET program.
The error message text associated with FCE error codes can be displayed by calling fceErrorText. Each sample program contains examples of error processing.
The FTP Client Engine for Visual Basic component library supports and has been tested with all versions of 32-bit Microsoft Visual Basic (VB 4, VB 5, VB 6 and Microsoft Visual Studio VB.NET).
The first Visual Basic for Windows (version 3.0) uses a text file known as a "Visual Basic makefile" (.MAK) to list all the file components necessary to compile a program. Beginning in version 4.0, the "Visual Basic Project file" (.VBP) was added. Both formats are "project files".
FCE32.DLL is written in standard ANSI C (FCE32.C), and has been compiled using Microsoft Visual C/C++ with the STDCALL and DECLSPEC compiler keywords. Source code for the FCE library is provided in the registered version (if ordered) only.
For more information on the C/C++ version of FCE, download the latest version of FCE4C from our web site at http://www.marshallsoft.com/fce4c.htm
The example programs can be compiled from the Visual Basic development environment using the provided Visual Basic makefiles. Choose "File", then "Open Project" from the main VB menu.
The example program code is stored inVB 4.0 (WIN32) format. Project files end with "32.VBP" (e.g.: FCEVER32.VBP). All 32-bit versions of VB (VB4 and above) can open files stored in VB 4.0 format.
When saving the example programs in VB version 5.0 or VB 6.0 format, answer "no" if asked to add the "Microsoft DAO v2.5 library".
Compile and run FCEVER32 as the first example. FCEVER does not require a TCP/IP connection.
Several example programs are included in FCE4VB. There is also an example program (HELLO), which uses the VB class "fceClass".
Each example program (except HELLO) comes with a VB makefile. Project files end with "32.VBP" (e.g.: FCEVER32.VBP).
The first example program FCEVER displays the FCE library version number and registration string. It does not require a connection. Open project FCEVER32.VBP.
Before writing your own programs, compile and run several of the example programs.
There is also an example program (HELLO32), which uses the VB class "fceClass".
The first example program is the program FCEVER (FCE Version) that displays the FCE library version number and registration string.
The project files are:
FCEVER32.VBP : for VB 4.0 and above.
FCEVER.VBPROJ : for VB.Net (Visual Studio)..
GET is an example FTP application that connects to our FTP server anonymously and downloads the file "fce-new.txt".
The project files are:
GET32.VBP : for VB 4.0 and above.
GET.VBPROJ : for VB.Net (Visual Studio).
WINFTP is an example FTP application that can be used to connect to a FTP server and upload, download, and delete files. WINFTP also demonstrates how to implement an upload/download progress bar.
The server, user, and password strings are read from the file WINFTP.INI when WINFTP begins execution, but can be changed at runtime before connecting to the FTP server.
The project file is:
WINFTP32.VBP : for VB 4.0 and above.
WINFTP.VBPROJ : for VB.Net (Visual Studio).
SPEED is a download speed test program. Note that the write buffer size is increased to 4096 (default is 1024) and the sleep time is reduced to 0 (default is 10 milliseconds):
Code = fceSetInteger(0, FCE_SET_WRITE_BUFSIZE, 4096)
Code = fceSetInteger(0, FCE_SET_SLEEP_TIME, 0)
The project file is:
SPEED32.VBP : for VB 4.0 and above.
The HELLO32 example program connects to a specified FTP server and verifies that it is responding to commands. HELLO32 uses the class fceClass, and therefore requires Visual Basic version 5.0 or higher.
The HELLO.VB program is the VB.NET equivalent of HELLO32. Also read section 2.5 "VB.Net" above.
The project files are:
HELLO32.VBP : for VB 5.0 and above.
HELLO.VBPROJ : for VB.NET
The LIST example program connects to a specified FTP server and lists all files by field. Before compiling, edit LIST32.FRM with the appropriate FTP parameters.
The project file is:
LIST32.VBP : for VB 4.0 and above.
The PROXY example program connects to a FTP server through a proxy server using the "USER@SERVER" protocol.
The project file is:
PROXY32.VBP : for VB 4.0 and above.
Refer to the FCE User's Manual (FCE_USR) for a discussion of proxy servers and proxy protocols; Section 3.7 "Proxy Servers" and Section 3.87 "Proxy Protocols" of the FCE User's Manual (FCE_USR). (http://www.marshallsoft.com/fce_usr.htm#Section_3.7). The text file PROXY2.TXT in the \DOCS sub-directory provides information.
The MGET example program downloads files according to a wildcard pattern using "?" and "*" characters. Also see the MPUT example program.
The project file is:
MGET32.VBP : for VB 4.0 and above.
The MGET example program downloads files according to a wildcard pattern using "?" and "*" characters. Also see the MGET example program.
The project file is:
MGET32.VBP : for VB 4.0 and above.
The MDTM example program requests the "File Modification Time" for a file. However, not all FTP servers support the MDTM command.
The project file is:
MDTM32.VBP : for VB 4.0 and above.
FCE4VB can be used with any VBA application. See section 2.7 "VBA Applications"
The FTP Client Engine DLL (FCE32.DLL) is written in ANSI C. All language versions of FCE (C/C++, Delphi, Visual Basic, PowerBASIC, FoxPro, dBase, Xbase++, COBOL, and FORTRAN) use the same identical DLLs.
Version 1.2: August 16, 1999
Initial release of the Visual Basic version of FCE.
Version 2.0: May 3, 2000
Version 2.1: January 15, 2001.
Version 2.2: September 25, 2001.
Version 2.3: November 26, 2002.
Version 2.4: April 30, 2004.
Version 2.5: July 22, 2005.
Version 2.6: January 24, 2007
Version 2.7: July 10, 2008