FTP Client Engine
Library for Visual FoxPro


Programmer's Manual


(FCE4FP)


Version 2.0

May 24, 2000



This software is provided as-is.
There are no warranties, expressed or implied.



Copyright (C) 2000
All rights reserved



MarshallSoft Computing, Inc.
Post Office Box 4543
Huntsville AL 35815



Voice : 256-881-4630

FAX : 256-880-0925

email : info@marshallsoft.com

web : www.marshallsoft.com



MarshallSoft is a member of the Association of Shareware Professionals

MARSHALLSOFT is a registered trademark of MarshallSoft Computing.



TABLE OF CONTENTS


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 INCLUDE Files
2.2 Compiling Programs
2.3 Dynamic Strings
2.4 Compiling to an Executable
2.5 FTP Parameters
2.6 Key Codes
3 Example Programs
3.1 FCEVER
3.2 LIST
3.3 FIELDS
3.4 GETPRO
3.5 FTP
3.6 FTP2
4 Revision History

1 Introduction

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

With FCE4FP, you can write Visual FoxPro programs that easily:

Seven example programs are included, demonstrating FTP functions. All programs will compile using any version of Visual FoxPro.

A Dynamic Link Library (FCE32.DLL) is provided. FCE4FP can be used with Windows 95/98, 2000 and NT. The FCE4FP DLL (FCE32.DLL) can also be used from any language (C/C++, Visual Basic, PowerBASIC Console Compiler, Delphi, Visual FoxPro, Visual dBase, Xbase++, COBOL, Fortran, etc.) capable of calling the Windows API.

When comparing FCE against our competition, note that:

1.1 Documentation Set

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

Each manual comes in three formats:

The FCE User’s Manual (FCE_USR) discusses FTP processing as well as language independent programming issues. Read this manual after reading the FCE4FP 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:

#INCLUDE FCE32CON.FOX
#INCLUDE KEYCODE.FOX
DECLARE INTEGER fceAttach in FCE32.DLL INTEGER Chan,  LONG KeyCode
DECLARE INTEGER fceClose in FCE32.DLL INTEGER Chan
DECLARE INTEGER fceConnect in FCE32.DLL INTEGER Chan, STRING @Server, STRING @User,
                                        STRING @Pass
DECLARE INTEGER fceErrorText in FCE32.DLL INTEGER Chan, INTEGER Code, STRING @Buffer,
                                        INTEGER BufLen
DECLARE INTEGER fceGetFile in FCE32.DLL INTEGER Chan, STRING @FileName
DECLARE INTEGER fceRelease in FCE32.DLL
DECLARE INTEGER fceSetMode in FCE32.DLL INTEGER Chan, INTEGER Mode
DECLARE INTEGER fceSetServerDir in FCE32.DLL INTEGER Chan, STRING @DirName
FTPserver = "10.0.0.1" + Chr(0)
FTPuser = "mike" + Chr(0)
FTPpass = "mike" + Chr(0)
FTPdirectory = "pub/other" + Chr(0)
FTPfilename = "products.txt" + Chr(0)
* attach FCE
Code = fceAttach(1, FCE_KEY_CODE)
if Code < 0
  ? "Cannot attach FCE ", Code
  return
endif
* connect to FTP server
? "Connecting to ", FTPserver
Code = fceConnect(0, @FTPserver, @FTPuser, @FTPpass)
if Code < 0
  DisplayError(Code)
  Code = fceRelease()
  return
endif
? "Connected. Now downloading file..."
* change to proper directory
Code = fceSetServerDir(0, @FTPdirectory)
* set to ASCII xfer mode
Code = fceSetMode(0, ASC("A"))
* download the file
Code = fceGetFile(0, @FTPfilename)
if Code <= 0
   DisplayError(Code)
else
   ? "File downloaded."
endif
* log off
Code = fceClose(0)
Code = fceRelease()
? "Logged off."
return
Procedure DisplayError(ErrCode)
TempBuffer = SPACE(128)
Code = fceErrorText(0,ErrCode,@TempBuffer,128)
? Left(TempBuffer,Code)
return

In the example program above, the file "products.txt" is downloaded from server directory "pub/other".

Refer to the FCE Reference Manual (FCE_REF) for individual function details.

1.3 Installation

  1. Before installation of FCE4FP, your Visual FoxPro compiler should already be installed on your system and tested.

  2. Create your FCE4FP project directory, copy the FCE4FP archive, and then unzip the archive.

  3. Run INSTALL.BAT which will copy FCE32.DLL to either C:\WINDOWS or C:\WINNT.

  4. Edit each example program with your FTP parameters (see section 2.5).

  5. You're ready to compile and run!

Note that the Windows registry is not modified.

1.4 Uninstalling

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

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

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

1.5 Ordering

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

1.6 Updates

When you register FCE4FP 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 INCLUDE Files

All example programs include two files; KEYCODE.FOX and FCE32CON.FOX. The file FCE32CON.FOX contains all the necessary constants for FCE4FP, while the file KEYCODE.FOX contains your key code, as discussed in section 2.6 below.

Since function declarations cannot be in an include file (at least through VFP version 5.0), they are listed in each program following the two include files. The complete list of function declarations is also in file FCE32FUN.FOX

2.2 Compiling Programs

The example programs are compiled from the Visual FoxPro development environment. Before running the example programs:

  1. Run the install program INSTALL.BAT.

  2. Edit each example program with your FTP parameters (see section 2.5), as shown in the example program in section 1.2 above. Server names can be IP addresses (in decimal dot notation) or the host name.

2.3 Dynamic Strings

The Visual FoxPro language use a technique known as "garbage collection" to manage string space at runtime, and may be called internally at any time by the FoxPro 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:

  Code = fceConnect(0,@Server,@User,@Password)
  if Code < 0
    * allocate buffer just before call
    Temp = SPACE(128)
    * put text in Temp
    Code = fceErrorText(1,Code,@Temp,128)
    ? Left(Temp,Code)
  endif

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.4 Compiling to an Executable

FoxPro programs end in ".PRG". They can be compiled to an executable using the FoxPro BUILD command.

For example, to create FCEVER.EXE from FCEVER.PRG in the C:\TEMP directory, type the following in the FoxPro command window:

BUILD PROJECT C:\TEMP\FCEVER FROM C:\TEMP\FCEVER
BUILD EXE C:\TEMP\FCEVER FROM C:\TEMP\FCEVER

FoxPro executables require VFP500.DLL and VFP5ENU.DLL (ENglish User), and may have to be copied from the VFP CDROM. If you are using an earlier or later version of FoxPro than version 5.0, substitute the appropriate DLL's for the above.

The FoxPro output display window will disappear as soon as your executable completes. In order to allow the user to control when the display window disappears, add the following code to your application, just before the final return.

?  " Type any key to exit..."
X = InKey(0)

2.5 FTP Parameters

Three parameters are required to connect to a FTP server. They are:

These FTP parameters are hard coded into most of the examples. However, these parameters could be read from the keyboard, from a file, etc., as well as being hard coded.

Refer to the FCE User's Manual (FCE_USR) for more information regarding FTP protocol parameters.

2.6 Key Codes

FCE32.DLL has a keycode encoded within it. Your keycode is a 9 or 10 digit decimal number (unless it is zero), and will be found in the file KEYCODE.FOX. The keycode for the shareware version is 0. You will receive a new key code when registering. Your keycode is not your customer ID (which is a 5 digit number).

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

Each example program, with the exception of FCEVER.PRG and GETPRO.PRG, must be edited with your FTP protocol parameters before compiling. Refer to the FCE User's Manual (FCE_USR) for details.

Refer to Section 2.1 above for information on compiling and linking the example programs. Before writing your own programs, compile and run the example programs.

3.1 FCEVER

This simple program displays the FCE version number, build number, and registration string taken from FCE32.DLL. The FCEVER program does not connect to your LAN (or the Internet).

This is the first program that you should compile and run.

3.2 LIST

The LIST example program logs onto the specified FTP server and lists all files. Edit LIST.PRG with your FTP server name (or IP address), user name , and password before compiling.

3.3 FIELDS

The FIELDS example program logs onto the specified FTP server and lists all files by field. Edit FIELDS.PRG with your FTP server name (or IP address), user name , and password before compiling.

3.4 GETPRO

The GETPRO example program connects to the MarshallSoft Computing web site at ftp.marshallsoft.com and downloads file "products.txt" from server directory "pub/other".

3.5 FTP

The FTP example program is a command line driven FTP client. Edit FTP.PRG with your FTP server name (or IP address), user name , and password before compiling

3.6 FTP2

The FTP2 example program is the same as the FTP.PRG example, except that it uses the FCE direct mode rather than FCE indirect mode. Refer to the Users Manual (FCE_USR) for more information on direct and indirect mode. Edit FTP.PRG with your FTP server name (or IP address), user name , and password before compiling.

4 Revision History

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

Version 2.0: May 24, 2000