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 Library Overview

2.1 Keycode
2.2 Dynamic Link Libraries
2.3 Win32 STDCALL and DECLSPEC
2.4 FTP Parameters
2.5 FCE Declaration File
2.6 Dynamic Strings
2.7 Adding FCE to a Project

3 Compiler Issues

3.1 INCLUDE Files
3.2 Compiling and Linking Programs
3.3 Xbase++ Compiler

4 Example Programs

4.1 FCEVER
4.2 GET
4.3 LIST
4.4 FIELDS
4.5 FTP
4.6 FTP2
4.7 WINFTP
4.8 PROXY
4.9 MGET
4.10 MPUT
4.11 SPEED

4 Revision History

1 Introduction

The FTP Client Engine for Xbase++ (FCE4XB) is a component library of functions providing direct control of the FTP protocol from an Xbase++ application. The FCE component library can be used for both anonymous and private FTP sessions.

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

The FTP Client Engine for Xbase++ supports and has been tested with all versions of Alaska Xbase++ + version v1.3 through and Xbase++ v1.9. FCE4XB includes several example programs that demonstrate FTP processing to help software developers easily build Xbase++ software applications using the FTP protocol.

A Dynamic Link Library (FCE32.DLL) is provided. FCE4XB can be used with Windows 95/98, Me, XP, 2000, 2003 and NT. The FTP Client Engine SDK DLL (FCE32.DLL) can also be used from any language (C/C++, .NET, PowerBASIC Console Compiler, Delphi, Visual FoxPro, Visual Basic, VB.NET, Visual dBASE, COBOL, Fortran, etc. as well as WORD, ACCESS, EXCEL) capable of calling the Windows API.

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

• FCE4XB is a standard Windows DLL (NOT an OCX or ActiveX control) and is much smaller than a comparable OCX or ActiveX control.
• FCE4XB 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.

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 DLLs (FCE16.DLL or 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

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 uploaded/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 encryption.
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 (FCE4XB) in the set.

• FCE4XB Programmer's Manual (FCE_4XB.DOC, FCE_4XB.TXT, FCE_4XB.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_4XB Programmer's Manual is the language specific (Xbase++) 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/fce4xb.htm

1.3 Example Program

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

     #INCLUDE "DLL.CH"
     #INCLUDE "KEYCODE.CH"
     #INCLUDE "FCE32.CH"
   
     #define TEMP_SIZE 128
     #define DATA_SIZE 5000
   
     Procedure Main()
     FTPserver = "ftp.marshallsoft.com" + Chr(0)
     FTPuser = "anonymous" + Chr(0)
     FTPpass = "msc@traveller.com" + Chr(0)
     FTPdirectory = "pub/oem" + Chr(0)
     FTPfilename = "fce-new.txt" + Chr(0)
     * attach FCE
     Code = XfceAttach(1, FCE_KEY_CODE)
     if Code < 0
       ? "Cannot attach FCE ", Code
       return
     endif
     * connect to FTP server
     ? "Connecting to ", FTPserver
     Code = XfceConnect(0, FTPserver, FTPuser, FTPpass)
     if Code < 0
       DisplayError(Code)
       Code = XfceRelease()
       return
     endif
     ? "Connected. Now downloading file..."
     * change to proper directory
     Code = XfceSetServerDir(0, @FTPdirectory)
     * set to ASCII xfer mode
     Code = XfceSetMode(0, ASC("A"))
     * download the file
     Code = XfceGetFile(0, @FTPfilename)
     if Code <= 0
        DisplayError(Code)
     else
        ? "File downloaded."
     endif
     * log off
     Code = XfceClose(0)
     Code = XfceRelease()
     ? "Logged off."
     return
   
     Procedure DisplayError(ErrCode)
     TempBuffer = SPACE(TEMP_SIZE)
     Code = XfceErrorText(0,ErrCode,@TempBuffer,TEMP_SIZE)
     ? Left(TempBuffer,Code)
     return
   

In the example program above, XfceConnect is called to connect to the FTP server as user "anonymous" and password "msc@traveller.com". Note that functions defined for Xbase++ begin with 'X'. All strings passed to FCE functions must be prefixed with the '@' character.

The server directory is changed to "pub/other", the transfer mode is set to ASCII, and the file "fce-new.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

1.4 Installation

1. Before installation of FCE4XB, your Xbase++ compiler (any version) should already be installed on your system and tested.
   
   
2. Unzip FCE4XB26.ZIP (demo version) or FCExxxx.ZIP (registered version; xxxx is the Customer ID).
   
   
3. Run the installation program SETUP.EXE which will install all FCE4XB files, including copying FCE32.DLL to your Windows directory. The Windows directory is typically C:\WINDOWS for Windows 95/98/Me/XP/2003 or C:\WINNT for Windows NT/2000. No Windows system files are modified.
   
   
4. You are ready to compile and run! For a quick start, load the project file FCEVER.PRG.

Note that the Windows registry is not modified.

1.5 Uninstalling

Uninstalling FCE4XB 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/ME/XP/2003 or C:\WINNT for Windows NT/2000.

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

1.6 Pricing

A developer's license for FCE4XB 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 FCE4XB 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
   

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.

2 Library Overview

2.1 Keycode

The FCE32.DLL has a keycode encoded within it. Your keycode is a 9 or 10 digit decimal number (unless it is 0), and will be found in the file KEYCODE.CH. 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 XfceAttach, 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 from the Window's search path.

2.2 Dynamic Link Libraries

The FTP Client Engine library is implemented as a dynamic link library (DLL). Both Win16 and Win32 DLLs are included. 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".

2.3 Win32 STDCALL and DECLSPEC

FCE32 is written in ANSI C and is compiled using the STDCALL and DECLSPEC keywords. This means that FCE4PB uses the same calling conventions and file naming conventions as the Win32 API. In particular, function names are NOT decorated. There are no leading underscores nor trailing "@size" added to function names.

The FCE32.DLL functions may be called by any Windows application capable of calling the Windows API provided that the proper declaration file is used.

2.4 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.5 FCE Declaration File

All FCE functions are declared in the FCE declaration file FCE32.CH. This file can be copied to the Xbase++ INCLUDE directory (where Xbase++ can find it) if so desired.

Note that each function is declared with the prefix character of 'X'.

2.6 Dynamic Strings

A string in the C language (in which FCE and Windows are written) consists of a pointer to the first byte of a character buffer in which a zero byte ends the string characters.

When passing a string to a FCE function, it is best to always append the Chr(0) character to the end of the string. This will guarantee than the FCE functions will be able to detect the end of the string. The example in Section 1.2 above illustrates this.

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.

     * allocate buffer just before call to dllGetMessage
     Buffer = SPACE(80)
     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.7 Adding FCE to a Project

It is straightforward to add FCE to Xbase++ programs.  First, add
   
     #INCLUDE "KEYCODE.CH"
     #INCLUDE "FCE32.CH"
   
after any other $INCLUDE statements in the Xbase++ program.

Then add

     nCode = fceAttach(1, FCE_KEY_CODE)
     If nCode < 0 Then
       ? "Cannot attach FCE"
       return
     endif

as the first executed FCE function.

The keycode (contained in KEYCODE.CH) is 0 for the evaluation version and is a 9-digit number for the purchased version. Rather than include KEYCODE.CH as shown above, the keycode can be pasted directly into the call to seeAttach.

Lastly, link your program with FCE32.LIB. Refer to the example programs in the APPS subdirectory.

3 Compiler Issues

3.1 INCLUDE Files

All example programs include two files; KEYCODE.CH and FCE32.CH. The file FCE32.CH contains all the necessary constants and function declarations for FCE4XB, while the file KEYCODE.CH contains your key code, as discussed in Section 2.2.

The Xbase++ include file DLL.CH is also required. For example,

     #INCLUDE "DLL.CH"
     #INCLUDE "KEYCODE.CH"
     #INCLUDE "FCE32.CH"

3.1 Compiling and Linking Programs

Before compiling any of the example programs, edit each program with your FTP user parameters, as shown in the example program in Section 2.4 above. Server names can be IP addresses (in decimal dot notation) or the host name.

For more information on host names and FTP user parameters, refer to the FCE User's Manual (FCE_USR). See Section 4.0 below, "Example Programs", for more details on each of the example programs.

To compile and link console mode programs such as LIST.PRG, use:

     xpp list.prg
     alink /subsystem:console winftp.obj fce32.lib

To compile and link windows GUI programs, such as WINFTP.PRG, use:

     xpp winftp.prg
     alink /subsystem:windows winftp.obj fce32.lib

3.2 Xbase++ Compiler

If you don't have the Alaska Software Xbase++ compiler, you can find it on the web at

     http://www.alaska-software.com

4 Example Programs

Each example program, with the exception of FCEVER.PRG and WINFTP.PRG, must be edited with your FTP protocol parameters (Section 2.4) before compiling.

Refer to Section 3.2 above for information on compiling and linking the example programs.

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

4.1 FCEVER

The first example program is the program FCEVER (FCE Version) which displays the FCE library version number and registration string. 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.

     xpp fcever.prg
     alink /subsystem:console fcever.obj fce32.lib

4.2 GET

The GET example program connects to our FTP server anonymously and downloads the file "fce-new.txt".

     xpp get.prg
     alink /subsystem:console get.obj fce32.lib

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

     xpp list.prg
     alink /subsystem:console list.obj fce32.lib

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

     xpp fields.prg
     alink /subsystem:console fields.obj fce32.lib

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

     xpp ftp.prg
     alink /subsystem:console ftp.obj fce32.lib

4.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 Section 4, "Theory of Operation", in the FCE User's Manual (FCE_USR) (http://www.marshallsoft.com/fce_usr.htm#Section_4

Edit FTP.PRG with your FTP server name (or IP address), user name, and password before compiling

     xpp ftp2.prg
     alink /subsystem:console ftp2.obj fce32.lib

4.7 WINFTP

The WINFTP example program is a Windows GUI example rather than a Windows console mode program. The Forms Designer (XPPFD.EXE) was used to create the forms code, after which the FCE code was added.

WINFTP is a general purpose FTP client. The WINFTP application can be used to connect to an FTP server and upload, download, and delete files. All necessary FTP parameters are entered at runtime.

     xpp winftp.prg
     alink /subsystem:windows winftp.obj fce32.lib

4.8 PROXY

The PROXY example program connects to an 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.

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

     xpp proxy.prg
     alink /subsystem:console proxy.obj fce32.lib

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

     xpp mget.prg
     alink /subsystem:console mget.obj fce32.lib

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

Note that most FTP servers do not allow anonymous users to upload files.

     xpp mput.prg
     alink /subsystem:console mput.obj fce32.lib

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

     xpp speed.prg
     alink /subsystem:console speed.obj fce32.lib

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

Version 2.0: May 18, 2000

• The initial release of the Xbase++ version of FCE.

Version 2.1: February 13, 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 25, 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 20, 2002.

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

Version 2.4: June 22, 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).
• Added ShowProgess function to WINFTP.PRG

Version 2.5: July 26, 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 example program.

Version 2.6: February 27, 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.