1 Introduction

1.1 Features
1.2 Documentation Set
1.3 Example Program
1.4 Installation
1.5 Uninstalling
1.6 Pricing
1.7 Updates

2 Compiler Issues

2.1 Keycode
2.2 INCLUDE Files
2.3 dBASE 5.6 and 5.7
2.4 dBASE 7.0 and above
2.5 Compiling dBASE Programs
2.6 Compiling dBASE Projects
2.7 Passing Strings to FCE
2.8 Null Terminated Strings
2.9 FTP Parameters
2.10 Compiling to an Executable

3 Example Programs

3.1 FCEVER
3.2 GET
3.3 LIST
3.4 FTP
3.5 FTP2
3.6 WINFTP
3.7 FIELDS
3.8 PROXY
3.9 MGET
3.10 MPUT
3.11 SPEED

4 Revision History

1 Introduction

The FTP Client Engine for Visual dBASE (FCE4DB) is a component library of functions providing direct control of the FTP protocol from a Visual dBASE application. The FCE component library 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.

The FTP Client Engine for Visual dBASE supports and has been tested with Visual dBase 5.7 and 7.0. FCE4DB includes several example programs, including standard .PRG programs and .WFM forms based programs that demonstrate FTP processing to help software developers easily build software applications using FCE4DB.

Both Win16 and Win32 DLLs (Dynamic Link Libraries) are provided. FCE4DB can be used with Windows 95/98, Me, XP, 2000 and NT. The FTP Client Engine SDK 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 Basic, COBOL, Fortran, etc.) capable of calling the Windows API.

When comparing the FTP Client Engine library (FCE) against our competition, note that:

• FCE4DB 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.
• FCE4DB 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.

Check http://www.marshallsoft.com for the latest version of our FTP software.

1.1 Features

Some of the many features of the FTP Client Engine component library are as follows:

1. Connect to any (anonymous or private) FTP server.
2. Get a list of files (names or long format) on the server.
3. Navigate the server directories.
4. Specify ASCII or BINARY transfer mode.
5. Download files (with wildcard support).
6. Upload files (with wildcard support).
7. Delete files.
8. Rename files.
9. Create and remove server directories.
10. Support for PROXY servers.
11. Supports passive mode (use with firewalls).
12. Supports multiple concurrent FTP sessions.
13. Resume file transfers from any offset.
14. Change files names while being up/downloaded.
15. Can parse long directory listings.
16. Can specify the FTP or data port.
17. Can set minimum and maximum response waits.
18. Supports file appending.
19. Supports S/KEY password authentication
20. Use on Internet or your own intranet (LAN).
21. Royalty free distribution with your compiled application.
22. Can be purchased with or without source code
23. Updates are free for one year (Updates to source code are separate).
24. Evaluation version is fully functional.

1.2 Documentation Set

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

• FCE4DB Programmer's Manual (FCE_4DB.DOC, FCE_4DB.TXT, FCE_4DB.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_4DB Programmer's Manual is the language specific (Visual dBase) 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 FTP in general 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.

Use Microsoft Word or Microsoft WordPad to print the document files. All manuals can also be viewed online at http://www.marshallsoft.com/fce4db.htm

1.3 Example Program

The following example demonstrates the use of some of the FTP Client Engine functions:

     #INCLUDE C:\TEMP\FCE32.CC
     #INCLUDE C:\TEMP\KEYCODE.CC
   
     FTPserver = "ftp.marshallsoft.com" + Chr(0)
     FTPuser = "anonymous" + Chr(0)
     FTPpass = "msc@traveller.com" + Chr(0)
   
     #define TEMP_SIZE 128
     #define DATA_SIZE 5000
   
     Code = fceAttach(1, FCE_KEY_CODE
     if Code < 0
       ? "Cannot attach FCE ", Code
       return
     endif
     ? "Connecting to ", FTPserver
     Code = fceConnect(0, FTPserver, FTPuser, FTPpass)
     if Code < 0
       TempBuffer = SPACE(TEMP_SIZE)
       Code = fceErrorText(0,Code,TempBuffer,TEMP_SIZE)
       ? Left(TempBuffer,Code)
       Code = fceRelease()
       return
     endif
     ? "Connected. Now getting file list."
     DataBuffer = SPACE(DATA_SIZE)
     Code = fceGetList(0, FCE_FULL_LIST, DataBuffer, DATA_SIZE)
     if Code <= 0
       TempBuffer = SPACE(TEMP_SIZE)
       Code = fceErrorText(0,Code,TempBuffer,TEMP_SIZE)
       ? Left(TempBuffer,Code)
     else
       ? Left(DataBuffer,Code)
     endif
     Code = fceClose(0)
     Code = fceRelease()
   ? "Logged off."
     return

In the example program above, fceConnect is called to connect to the FTP server as user "anonymous" and password "msc@traveller.com".

Next, a full file listing is requested. 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

1.4 Installation

1. Before installation of FCE4DB, your Visual dBase compiler (any version) should already be installed on your system and tested.
   
   
2. Unzip FCE4DB26.ZIP (demo version) or FCExxxx.ZIP (registered version; xxxx is the Customer ID).
   
   
3. Run the installation program SETUP.EXE which will install all FCE4DB files, including copying FCE32.DLL and FCE16.DLL to your Windows directory. The Windows directory is typically C:\WINDOWS for Windows 95/98/Me/XP or C:\WINNT for Windows NT/2000. No Windows system files are modified.
   
   
4. Edit the example programs (.PRG and .WFM):
   
   

• Set the location of the include files KEYCODE.CC and FCE32.CC (or FCE16.CC).
• Change the server name, user, and password as necessary.
  
  

5. You're ready to run! Compile and run FCEVER.PRG as a test of your installation.

Note that the Windows registry is not modified.

1.5 Uninstalling

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

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

Second, delete the FCE project directory created when FCE4DB was installed.

1.6 Pricing

A developer's license for FCE4DB can be registered for $115 ($295 with ANSI C source code to the DLLs). 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)

1.7 Updates

When you register FCE4DB 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, 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). After one year, licenses can be updated for $55.

Also see file UPDATES.TXT.

2 Compiler Issues

FCE4DB can be compiled with 16-bit Visual dBase (dBase 5.6 and 5.7) or with 32-bit Visual dBase (dBase 7.0 and above).

2.1 Keycode

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.CC. The keycode for the evaluation 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 evaluation version of the FCE DLL's from the Windows search path.

2.2 INCLUDE Files

All example programs include two files: KEYCODE.CC and FCE32.CC (or FCE16.CC). The file FCE32.CC (or FCE16.DLL) contains all the necessary constants and function declarations for FCE4DB, while the file KEYCODE.CC contains your key code, as discussed in section 2.7 below.

There are three recommended ways to handle these INCLUDE files in dBASE programs.

1. Copy the INCLUDE files to your compiler's INCLUDE directory.
2. Edit the INCLUDE statements (in each program) with their physical location.
3. Replace the INCLUDE statements (in each program) by their contents.

2.3 Visual dBASE 5.6 and 5.7

Visual dBASE 5.6 and 5.7 create 16-bit applications, and use the 16-bit FCE DLL, namely FCE16.DLL. Copy the 16-bit CC file FCE16.CC to your compiler's INCLUDE directory.

2.4 Visual dBASE 7.0 and above

Visual dBASE 7.0 and above create 32-bit applications, and use the 32-bit DLL, FCE32.DLL. Copy the 32-bit CC file FCE32.CC to your compiler's INCLUDE directory.

2.5 Compiling dBASE Programs

Visual dBase programs end with the extension ".PRG". Before compiling any of the example programs, edit each file with your Internet TCP/IP parameters. Programs can be edited within any text editor, and compiled from the VDB (Visual dBase) command window with the COMPILE command (e.g.: COMPILE LIST.PRG) or executed from the VDB command window with the DO command (e.g.: DO LIST.PRG).

To open a program within the Visual dBase source editor, choose "File", then "Open". When the "Open File" dialog box appears, choose "Programs" for "Files of Type", then choose the program (*.PRG) to open. Lastly, choose "Open in Source Editor" for "Action" and push the "Open" button.

After editing the source program with your internet (or TCP/IP) parameters, you are ready to compile. From the dBase menu bar, choose "Build", then "Compile". To run choose, "Run". The VDB command window must be displayed in order to see the output.

2.6 Compiling dBASE Projects

Visual dBase projects consist of several types of files such as forms, reports, data modules, etc. The project file itself ends with the extension of ".PRJ".

There is one example Visual dBase project WINFTP. Open WINFTP by choosing "File", then "Open Project" from the dBase menu bar. To compile WINFTP, choose "Build" from the menu bar, then "Rebuild All". This will create WINFTP.EXE, which can be executed by choosing "Execute winftp.exe" from the "Build" menu bar pulldown, or from the Windows command line prompt.

2.7 Passing Strings to FCE

Strings passed to FCE functions must be terminated with Chr(0) since this is the way the Windows API (written in ANSI C) handles strings.

For example:

Server = "ftp.marshallsoft.com" + Chr(0)

2.8 Null Terminated Strings

All strings returned from FCE functions are null terminated. That is, the end of the string is delimited by a Chr(0) character. These strings may be converted for dBase in one of two ways: (1) if the length of the string is known, use the dBase LEFT function: For example,

     * get server IP address
     TempBuffer = SPACE(TEMP_SIZE)
     Code = fceGetString(0, FCE_GET_SERVER_IP, TempBuffer, TEMP_SIZE)
     if Code > 0
       ? "Server IP ", LEFT(TempBuffer, Code)
     endif

If the length of the null terminated string is not known, use the dBase AT function to find the position of Chr(0). For example,

     Offset = fceMatchFile(ListBuffer,Offset,NameBuffer,128,FTPpattern,1)
   
     P = AT(Chr(0), NameBuffer)
     ? "Downloading file " + Left(NameBuffer, P-1)

2.9 FTP Parameters

There are two types of FTP connections: private and anonymous. However, some FTP servers do not accept anonymous connections.

Three parameters are necessary in order to connect to an FTP server, as follows:

• Host name (or IP address) of the FTP server.
• User name.
• User password.

For private connections, the users account name and password must be specified.

For anonymous connections, the user name is "anonymous" and the password is the user's email address.

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

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

2.10 Compiling to an Executable

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

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

     BUILD PROJECT C:\FCE4DB\APPS\FCEVER FROM C:\FCE4DB\APPS\FCEVER
     BUILD EXE C:\FCE4DB\APPS\FCEVER FROM C:\FCE4DB\APPS\FCEVER
   

3 Example Programs

Several example programs are included in FCE4DB. Refer to Section 2 above for help in compiling the example programs.

All example programs end with ".PRG", except for the FORM example (WINFTP), which ends with ".WFM".

3.1 FCEVER

The FCEVER ("FCE Version") program (FCEVER.PRG) displays the DLL version, build number, and registration string. This is the first program to try. Its purpose is to display the current version of the FCE DLL as well as to verify that FCE32.DLL is being found and loaded by Windows. It does not require a TCP/IP (Internet) connection. Run FCEVER from the VDB command window with "DO".

3.2 GET

GET is an FTP client that connects to our FTP server anonymously and downloads the file "fce-new.txt". After compiling, start GET from the command line.

3.3 LIST

The LIST program (LIST.PRG) connects to the MarshallSoft FTP site at "ftp.marshallsoft.com" as user "anonymous" with password "msc@traveller.com". Change the password to your email address before compiling. Run LIST.PRG from the command window.

After connecting, LIST gets the list of all files on the server at the base FTP directory level, then logs off.

3.4 FTP

The FTP program (FTP.PRG) is a generic FTP program that can perform the most basic FTP functions such as listing and downloading files. Note that there are many FCE functions not implemented in the FTP.PRG example. Run FTP.PRG from the VDB command window.

3.5 FTP2

The FTP2 program (FTP2.PRG) is identical to FTP except that it uses fceDriver when downloading and uploading files. Refer to Section 4, "Theory Of Operation", in the FCE User's Manual (FCE_USR) (http://www.marshallsoft.com/fce_usr.htm#Section_4

Run FTP2.PRG from the VDB command window.

3.6 WINFTP

The WINFTP program (WINFTP.PRG) is similar to the FTP program, except that it uses the Visual dBase form. To compile WINFTP.FRM from dBase 5.6/5.7, choose "Open" from under "File" on the Visual dBase 5.7 menu bar. To compile WINFTP.FRM from dBase 7.0 and above, choose "Open Project" from under "File" on the Visual dBase 7menu bar.

Note that code at the beginning of WINFTP.WFM

     #INCLUDE C:\TEMP\FCE32.CC
     #INCLUDE C:\TEMP\KEYCODE.CC

     #define TEMP_SIZE 128
     #define DATA_SIZE 35000

must be re-inserted manually after modifying the file with the dBase form designer.

3.7 FIELDS

The FIELDS program (FIELDS.PRG) connects to the MarshallSoft FTP site at "ftp.marshallsoft.com" as user "anonymous" with password "msc@traveller.com". Change the password to your email address before compiling. Run FIELDS from the command window.

The FIELDS program is similar to the LIST program. After connecting, FIELDS gets the list of all files on the server at the base FTP directory level, and lists each field as a separate string.

3.8 PROXY

The PROXY example program connects to a FTP server through a proxy server using the "USR@SERVER" protocol. Edit PROXY.PRG with your FTP server name (or IP address), user name, and password before compiling.

Refer to the FCE User's Manual (FCE_USR) for a discussion of proxy servers. Section 3.6 "Proxy Server", of the FCE User's Manual (FCE_USR). http://www.marshallsoft.com/fce_usr.htm#Section_3.6

3.9 MGET

The MGET example program downloads files according to a wildcard pattern (using '?' and '*' characters). Edit MGET.PRG with your FTP server name (or IP address), user name, and password before compiling.

3.10 MPUT

The MPUT example program uploads files according to a wildcard pattern (using '?' and '*' characters). Edit MPUT.PRG with your FTP server name (or IP address), user name, and password before compiling.

3.11 SPEED

The SPEED example program connects to the MarshallSoft FTP server at ftp://ftp.marshallsoft.com and downloads a test file from the MarshallSoft FTP server and displays the time required. Use this program to see how long it takes to download files from FTP servers.

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 dBase, PowerBASIC, FoxPro, dBase, Xbase++, and COBOL) use the same identical DLLs.

Version 1.2: October 15, 1999

• The initial release of the dBase version of FCE.

Version 2.0: May 11, 2000

• WriteBufferSize default set 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.

Version 2.1: February 8, 2001.

• Increased buffer size from 64 to 128 bytes for LocalDir and ServerDir.
• WriteBufferSize default increased to 512.
• Password not used if specified password has zero length.
• fceSetLocalDir() verifies that local directory is writable.
• Added FCE_SET_APPEND_MODE.
• Allow 128 character filenames.
• Added FCE_RENAME_DELIMITER to fceSetInteger().
• Corrected fceGetStatus(Chan, FCE_CONNECT_STATUS)
• Added FCE_SET_CLIENT_OFFSET and FCE_SET_SERVER_OFFSET.
• Rename file being up/downloaded by specifying "oldname:newname" for file.
• Added FCE_GET_LOCAL_IP to fceGetString.
  
  
  

Version 2.2: October 16, 2001.

• Default write buffer size increased from 512 to 1024 (WIN32 only).
• Added fceMatchFile function (used in multi-file uploads and downloads).
• Specify "User" as Chr(0) [in fceConnect] to skip USER and PASS processing.
• Performance improvements.
• Added MGET and PROXY example programs.

Version 2.3: December 12, 2002.

25. Added FCE_SET_BLOCKING_MODE to control blocking (default ON) while connecting.
26. Size of command buffer in fceCommand increased from 64 to 128 bytes.
27. "WARNING: 226/250 not seen" written to log file rather than returning error.
28. Added FCE_GET_ERROR_LINE.
29. fceCommand sends CRLF with command in one network write.
30. Added fceFileLength function.
31. fceExtract handles line # 0.
32. Added FCE_GET_QUEUE_ZERO (returns # times fceQueueLoad returns 0).
33. Fixed problem with long server offsets (replaced "REST %d" with "REST %ld") in 16-bit version.
34. Changed to 32 channels & 128 data ports (random time bits no longer used).
35. fceGetList returns error if receive buffer is too small.

Version 2.4: June 1, 2004.

• Added FCE_SET_CONNECT_WAIT_IN_SECS.
• Added FCE_SET_MAX_RESPONSE_WAIT_IN_SECS.
• Added FCE_SET_MAX_LINE_WAIT_IN_SECS.
• FCE_NOT_COMPLETED returned if code 226 (or 250) not returned by control socket (in 2 tries).
• Number data ports changed to 2048 per channel for 1 and 2 channels
• Number data ports changed to 512 data ports per channel for 3 to 8 channels
• Number data ports changed to 128 data ports per channel for 9 to 32 channels
• DataPort mask corrected to 0x7FFF
• Added fceGetLocalFList function to get list of files in local directory.
• Added fceGetLocalFSize function to get the size of a file in the local directory.
• Added new MPUT and MGET example programs (using wildcards).

Version 2.5: July 28, 2005.

• LocalDir always stored with backslash as last character.
• fceWriteSocket makes up to 12 attempts to write.
• Add FCE_AUTO_LOG_CLOSE and FCE_CLOSE_LOG_FILE
• Adjusted wait time-outs.
• Added FCE_NO_GREETING error.
• Improved operation of fceGetInteger(Chan, FCE_GET_CONNECT_STATUS).
• Added GET.PRG example program.
• Added fceShortToByte and fceByteToShort functions

Version 2.6: February 16, 2007

• Maximum PUT buffer size increased from 8K to 16K (16384)
• Recoded sleep wait in fceWriteSocket for improved upload performance.
• Added internal memory allocation debugging.
• Added GET_FULL_RESPONSE
• Close control socket whenever fceConnect fails (fixes socket leak problem).
• Added FCE_SET_FIRST_DATA_PORT and FCE_SET_LAST_DATA_PORT to fceSetInteger.
• Maximum data port extended to 65535.
• Added FCE_HIDE_PASSWORD to fceSetInteger.
• Added S/KEY authentication
• Added fceGetTicks()
• Added FCE_STATUS_BEFORE_WRITE to fceSetInteger.

Check http://www.marshallsoft.com for the latest version of our FTP software.