FTP Client Engine Library for Delphi
Programmer's Manual
(FCE4D)
Version 2.0
June 5, 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.
1 Introduction
1.1 Documentation Set2 Compiler Issues
1.2 Example Program
1.3 Installation
1.4 Uninstalling
1.5 Ordering
1.6 Updates
2.1 Delphi Versions3 Example Programs
2.2 Compiling Programs
2.3 Using the FCE Unit
2.4 Using the FCEW Unit
2.5 Key Code
3.1 VER_PGM4 Revision History
3.2 LIST_PGM
3.3 FLD_PGM
3.4 GET_PGM
3.5 FTP_PGM
3.6 FTP2_PGM
3.7 FTPW_PGM
FCE4D is the easiest way to write FTP applications in Delphi! 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 FCE4D, you can write GUI or console mode programs that easily:
FCE4D supports all versions of Delphi.
Both Win16 and Win32 DLLs (Dynamic Link Libraries) are provided. FCE4D can be used with Windows 3.X, 95/98,2000 and NT. The FCE4D DLLs (FCE16.DLL and FCE32.DLL) can also be used from any language (C/C++, WORD, ACCESS, EXCEL, PowerBASIC Console Compiler, Visual Basic, Visual FoxPro, Visual dBase, Xbase++, COBOL, Fortran, etc.) capable of calling the Windows API.
When comparing FCE against our competition, note that:
The complete set of documentation consists of three manuals in three formats. This is
the first manual
(FCE4D) 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 FCE4x Programmer’s Manual. The FCE Reference Manual (FCE_REF) contains details on each individual FCE function
The following example demonstrates the use of some of the library functions using the FCEW.PAS unit.
var Code : Integer; begin {attach FCE} Code := fAttach(1, FCE_KEY_CODE) if Code < 0 then begin {Error attaching FCE} exit end; {connect to FTP server} Code := fConnect(0,'ftp.marshallsoft.com','anonymous','msc@traveller.com'); if Code < 0 then begin {Error code returned} exit end; {quit} fClose(0); fRelease() end;
In the example program above, fConnect is called to connect to the FTP server as user "anonymous" and password "msc@traveller.com".
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.
INSTAL16 -- for Win16 (Delphi 1) INSTAL32 -- for Win32 (Delphi 2 and above)
Alternatively, one can run INSTALL.BAT:
INSTALL 16 -- for Win16 INSTALL 32 -- for Win32
The INSTALL.BAT program (called by INSTAL16.BAT or INSTAL32.BAT) copies FCE32.DLL (or FCE16.DLL) to either C:\WINDOWS (for Windows 3.1/95/98) or C:\WINNT (for Windows NT 4.0 and Windows 2000).
Note that the Windows registry is not modified.
Uninstalling FCE4D 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/2000.
Second, delete the FCE project directory created when installing FCE4D.
FCE4D may be registered for $95. See the section "Ordering" in the FCE User’s Manual (FCE_USR) for details on ordering.
When you register FCE4D 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.
Applications written with Delphi link with the same identical DLL's as for applications written in all other supported languages, such as C/C++ and Visual Basic.
The first release of Borland Delphi (version 1) generated Win16 code. Therefore, applications written using Delphi 1 must link with FCE16.DLL.
One very significant limitation of Delphi 1 is that strings are limited to 255 bytes. This limitation makes using the FCE wrapper unit (section 2.4) FCEW.PAS difficult. For this reason, it is suggested that FCE functions be called directly rather than through FCEW in any situation in which strings may be larger than 255 characters.
Delphi version 2 and above generates Win32 code. Therefore, applications written using Delphi 2 will link with FCE32.DLL. Strings can be up to 2GB rather than 255 bytes as in Delphi 1.
Delphi 2 seems to have a problem with some of the PChar string functions. Although the default is "large strings", some of the string functions (such as StrPCopy) copy only 255 bytes. The MYSTRING.PAS unit contains a replacement unit to use instead of StrPCopy.
Delphi 3 also has some problems with PChar string functions such as StrPCopy. See above section.
There are no know Delphi problems impacting our example programs in Delphi version 4 and above. Applications written using Delphi 4 and above will link with FCE32.DLL.
The example programs are compiled from the Delphi development environment using the provided Delphi project files (*.DPR). Be sure to run the install program (INSTAL16.BAT or INSTAL32.BAT) before compiling. Recall that Delphi 1 generates a Win16 application while Delphi 2 and above generates a Win32 application.
The example programs will compile and run with any version of Delphi. They have each been tested using Delphi 1 through Delphi 5.
Respond with "OK" to the message "Cannot find resource file..." and it will be properly rebuilt.
See section 3 "Example Programs" for more details on each of the example programs.
FCE4D may also be used with "Borland Pascal for Windows".
The FCE is written in ANSI C (like Windows itself). In C, strings are zero terminated. Note the manner in which strings are passed to FCE functions.
var Text : String; Host : PChar; begin {allocate Memory (128 bytes) and copy string to it} GetMem(Host, 128); StrPCopy(Host, 'ftp.marshallsoft.com'); {pass Host to FCE function} Code := fceConnect(0,Host,...); {free Memory} FreeMem(Host, 128); end;
FCE buffers can also be converted to Delphi strings with StrPas. For example:
Text := StrPas(Host);
Also see section 2.4 "Using the FCEW Unit", in which the calls to GetMem and FreeMem are done in FCEW.PAS rather than in your application.
The FCEW.PAS module is a "wrapper" unit for FCE.PAS that allows you to pass Delphi strings directly rather than having to first convert them to PCHAR variables.
Compare the example program FTPW_PGM.PAS to FTP_PGM.PAS. Observe that FTPW_PAS.PAS has "uses fcew" while FTP_PGM.PAS has "uses fce".
Note that FCEW.PAS is easier to use while FCE.PAS has less overhead.
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.PAS. 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.
Several example programs are included in FCE4D. Before writing your own programs, compile and run the example programs.
You must run either INSTAL16 or INSTAL32 to copy the proper units and DLLs before compiling any of the example programs.
Compile and run the VER_PGM example first, in order to verify that you have installed FCE4D correctly and that you can use the FCE DLL (FCE16.DLL or FCE32.DLL).
The VER_PGM (Version Program) example program displays the FCE library version number and registration string. A TCP/IP connection is not required.
The project files are:
VER_PRJ.DPR : Project file.
VER_PGM.PAS : Program file.
VER_PGM.DFM : Delphi Form file.
The LIST_PGM example program connects to a FTP server and displays a listing of all files in the FTP server root directory.
The project files are:
LIST_PRJ.DPR : Project file.
LIST_PGM.PAS : Program file.
LIST_PGM.DFM : Delphi Form file.
The FLD_PGM example program is the same as the LIST_PGM example, except that it lists each line (in the listing of all files) by field.
The project files are:
FLD_PRJ.DPR : Project file.
FLD_PGM.PAS : Program file.
FLD_PGM.DFM : Delphi Form file.
The GET_PGM example program connects to the MarshallSoft FTP server at ftp://ftp.marshallsoft.com and downloads the file PRODUCTS.TXT from server directory "pub/other".
The project files are:
GET_PRJ.DPR : Project file.
GET_PGM.PAS : Program file.
GET_PGM.DFM : Delphi Form file.
The FTP_PGM example program is a FTP application which can be used to connect to any FTP server and list, upload, download, and delete files, as well as navigate the server directory structure.
The project files are:
FTP_PRJ.DPR : Project file.
FTP_PGM.PAS : Program file.
FTP_PGM.DFM : Delphi Form file.
The FTP2_PGM example program is the same program as FTP_PGM except that it operates in "direct mode" so that it can display the progress of uploads and downloads. Refer to the FCE User's Manual (FCE_USR) for more information on direct mode.
The project files are:
FTP2_PRJ.DPR : Project file.
FTP2_PGM.PAS : Program file.
FTP2_PGM.DFM : Delphi Form file.
The FTPW_PGM example program is the same program as FTP_PGM except that it calls functions in unit FCEW (which in turn call FCE functions) rather than FCE functions directly.
The project files are:
FTPW_PRJ.DPR : Project file.
FTPW_PGM.PAS : Program file.
FTPW_PGM.DFM : Delphi Form file.
The FTP Client Engine DLLs (FCE16.DLL and FCE32.DLL) are written in ANSI C. All language versions of FCE (C/C++, Visual Basic, Delphi, PowerBASIC, FoxPro, dBase, Xbase++, and COBOL) use the same identical DLLs.
Version 1.2: September 29, 1999
Version 2.0: June 5, 2000