1 Introduction

1.1 Documentation Set
1.2 Example Program
1.3 Installation
1.4 Uninstalling
1.5 Ordering
1.6 Updates

2 Compiler Issues

2.1 Visual Basic Makefiles
2.2 Compiling Programs
2.3 FCE4VB Class
2.4 Dynamic Strings
2.5 Key Code

3 Example Programs

3.1 FCEVER
3.2 WINFTP
3.3 GETPRO
3.4 HELLO
3.5 LIST

4 Revision History

1 Introduction

FCE4VB is the easiest way to write FTP applications in Visual Basic! FCE can be used for both anonymous and private FTP sessions.

A simple interface allows connecting to a FTP server, navigating its directory structure, listing files, sending files, deleting files, and receiving files using the FTP protocol.

With FCE4VB, you can write GUI or console mode programs that easily:

• Connect to any FTP server.
• Get a list of files on the server.
• Navigate the server directories.
• Specify ASCII or BINARY transfer mode.
• Download files.
• Upload files.
• Delete files.
• Create and remove server directories.

FCE4VB supports all versions of Visual Basic.

Both Win16 and Win32 DLLs (Dynamic Link Libraries) are provided. FCE4VB can be used with Windows 3.X, 95/98,2000 and NT. The FCE4VB DLLs (FCE16.DLL and FCE32.DLL) can also be used from any language (C/C++, WORD, ACCESS, EXCEL, PowerBASIC Console Compiler, Delphi, Visual FoxPro, Visual dBase, COBOL, Fortran, etc.) capable of calling the Windows API.

When comparing FCE against our competition, note that:

• FCE4VB is a standard Windows DLL (NOT an OCX or ActiveX control) and is much smaller than a comparable OCX or ActiveX control.
• Both WIN16 and WIN32 DLLs are included.
• FCE4VB does NOT depend on ActiveX or Microsoft Foundation Class (MFC) libraries or similar "support" libraries.
• The WIN32 version of FCE is fully threadable.
• The FCE functions can be called from applications not capable of using controls.

1.1 Documentation Set

The complete set of documentation consists of three manuals in three formats. This is the first manual (FCE4VB) in the set.

• FCE4VB Programmer’s Manual (FCE4VB.DOC, FCE4VB.TXT, FCE4VB.HTM)
• FCE User’s Manual (FCE_USR.DOC, FCE_USR.TXT, FCE_USR.HTM)
• FCE Reference Manual (FCE_REF.DOC, FCE_REF.TXT, FCE_REF.HTM)

Each manual comes in three formats:

• Microsoft Word (files ending in .DOC). The best format for printing manuals.
• Hyper Text (files ending in .HTM). Use any web browser to read.
• ASCII Text (files ending in .TXT).

The FCE User’s Manual (FCE_USR) discusses FTP processing as well as language independent programming issues. Read this manual after reading the FCE4x Programmer’s Manual. The FCE Reference Manual (FCE_REF) contains details on each individual FCE function

1.2 Example Program

The following example demonstrates the use of some of the 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.

1.3 Installation

1. Before installation of FCE4VB, your Visual Basic compiler (any version) should already be installed on your system and tested.
   
   
2. Create your FCE4VB project directory, copy the FCE4VB archive, and then unzip the archive.
   
   
3. Run INSTALL.BAT which will copy FCE32.DLL (for VB 4.0, 5.0, and 6.0) or FCE16.DLL (for VB 3.0) to either C:\WINDOWS or C:\WINNT.
   
   
4. You're ready to run! Win16 programs (VB 3.0) end with "16", while Win32 programs (VB 4.0, 5.0, & up) end with "32". For example,

FCEVER16.MAK --- Makefile for 16-bit Visual Basic.
FCEVER32.MAK --- Makefile for 32-bit Visual Basic.

Note that the Windows registry is not modified.

1.4 Uninstalling

Uninstalling FCE4VB is very easy. FCE does not modify the registry.

First, run UINSTALL.BAT, which will delete FCE16.DLL and FCE32.DLL from your Windows directory, typically C:\WINDOWS for Windows 3.1/95/98 or C:\WINNT for Windows NT.

Second, delete the FCE project directory created when installing FCE4VB.

1.5 Ordering

FCE4VB may be registered for $95. See Section 1.4 "Ordering" in the FCE User’s Manual (FCE_USR) for details on ordering.

1.6 Updates

When you register FCE4VB you will receive a set of registered DLLs plus a license file (FCExxxx.LIC) that can be used to update your registered DLL’s for a period of one year from purchase. Updates can be downloaded from

http://www.marshallsoft.com/oem.htm

After one year, licenses can be updated for $30 for email delivery.

2 Compiler Issues

2.1 Visual Basic Makefiles

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".

In order to allow our example programs to be compiled by all versions of Visual Basic, we use the Visual Basic makefile format. However, after loading, the examples can be saved in whatever format desired.

2.2 Compiling Programs

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 in VB 3.0 (WIN16) and VB 4.0 (WIN32) formats. All project files (except StatProj) end in "16.MAK" (e.g.: FCEVER16.MAK) or "32.MAK" (e.g.: FCEVER32.MAK) .

After opening a project, VB 5.0 (and VB 6.0) users can save the project files in the VB 5.0 (or VB 6.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 FCEVER16 (or FCEVER32) as the first example. FCEVER does not require a TCP/IP connection.

2.3 FCE4VB Class

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 "StatProj" 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.

2.4 Dynamic Strings

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.

2.5 Key Codes

FCE16.DLL and FCE32.DLL have a keycode encoded within them. Your keycode is a 9 or 10 digit decimal number (unless it is 0), and will be found in the file KEYCODE.BAS. The keycode for the shareware version is 0. You will receive a new key code when registering.

If you get an error message (value -74) when calling fceAttach, it means that the keycode in your application does not match the keycode in the DLL. After registering, it is best to remove the shareware version of the FCE DLL's from the Windows search path.

3 Example Programs

Several example programs are included in FCE4VB. Separate versions for Win16 and Win32 are included. There is also an example program (StatProj) which uses the VB class "fceClass".

Each example program (except StatProj) comes with a VB makefile. WIN16 makefile names end with "16.MAK" (e.g.: FCEVER16.MAK) while WIN32 makefiles end with "32.MAK" (e.g.: FCEVER32.MAK).

The first example program FCEVER displays the FCE library version number and registration string. It does not require a connection. Open project FCEVER16.MAK or FCEVER32.MAK.

Before writing your own programs, compile and run several of the example programs.

Several example programs are included in FCE4VB. Separate versions for Win16 (FCEVER16, GETPRO16, WINFTP16) and Win32 (FCEVER16, GETPRO16, WINFTP16) are included.

There is also an example program (HELLO32) which uses the VB class "fceClass".

Each example program (except HELLO32) comes with a VB makefile. WIN16 makefile names end with "16.MAK" (e.g.: FCEVER16.MAK) while WIN32 makefiles end with "32.MAK" (e.g.: FCEVER32.MAK).

Before writing your own programs, compile and run the example programs.

3.1 FCEVER

The first example program is the program FCEVER (FCE Version) which displays the FCE library version number and registration string. The project makefiles are:

FCEVER16.MAK : for VB 3.0.

FCEVER32.MAK : for VB 4.0 and above.

3.2 WINFTP

WINFTP is an example FTP application which can be used to connect to a FTP server and upload, download, and delete files. WINFTP is a general purpose FTP client.

See WINFTP.TXT for more details.

The project makefiles for WINFTP are:

WINFTP16.MAK : for VB 3.0.

WINFTP32.MAK : for VB 4.0 and above.

3.3 GETPRO

GETPRO is an example program that connects to the MarshallSoft FTP server at

ftp://ftp.marshallsoft.com

and downloads the file PRODUCTS.TXT from the server directory

pub/other

The project makefiles are:

GETPRO16.MAK : for VB 3.0.

GETPRO32.MAK : for VB 4.0 and above.

3.4 HELLO32

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 project file is:

HELLO32.VBP : for VB 5.0 and above.

3.5 LIST

The LIST example program connects to a specified FTP server and lists all files by field. Before compiling, edit LIST16.FRM and LIST32.FRM with the appropriate FTP parameters.

The project files are:

LIST16.MAK : for VB 3.0.

LIST32.MAK : for VB 4.0 and above.

4 Revision History

The FTP Client Engine DLLs (FCE16.DLL and FCE32.DLL) are written in ANSI C. All language versions of FCE (C/C++, Delphi, Visual Basic, PowerBASIC, FoxPro, dBase, Xbase++, and COBOL) use the same identical DLLs.

Version 1.2: August 16, 1999

The initial release of the VB version of FCE.

Version 2.0: May 3, 2000

• WriteBufferSize default reduced to 512.
• Added FCE_GET_LINE_COUNT to fceGetString.
• Rename file being downloaded by specifying "oldname:newname" for file name.
• Added FCE_SET_DATA_PORT to fceSetInteger.