FTP Client Engine
Library for Xbase++
Programmer's Manual
(FCE4XB)
Version 2.0
May 18, 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 INCLUDE Files3 Example Programs
2.2 Compiling and Linking Programs
2.3 Dynamic Strings
2.4 FTP Parameters
2.5 Key Codes
2.6 FCE Declaration File
2.7 Xbase++ Compiler
3.1 FCEVER4 Revision History
3.2 LIST
3.3 FIELDS
3.4 GETPRO
3.5 FTP
3.6 FTP2
3.7 WINFTP
FCE4XB is the easiest way to write FTP applications in Xbase++! FCE can be used for both anonymous and private FTP sessions.
With FCE4XB, you can write GUI or console mode programs that easily:
Seven example programs are included, demonstrating FTP functions. All programs will compile using any version of Xbase++.
A Dynamic Link Library (FCE32.DLL) is provided. FCE4XB can be used with Windows 3.X, 95/98, 2000 and NT. The FCE4XB 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:
The complete set of documentation consists of three manuals in three formats. This is
the first manual
(FCE4XB) 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:
#INCLUDE "DLL.CH"
#INCLUDE "KEYCODE.CH"
#INCLUDE "FCE32.CH"
#define TEMP_SIZE 128
#define DATA_SIZE 5000
Procedure Main()
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 = 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".
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.
Note that the Windows registry is not modified.
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 3.1/95/98 or C:\WINNT for Windows NT.
Second, delete the FCE project directory created when installing FCE4XB.
FCE4XB may be registered for $95. See the section "Ordering" in the FCE User’s Manual (FCE_USR) for details on ordering.
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
After one year, licenses can be updated for $30 for email delivery.
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.5 below.
The Xbase++ include file DLL.CH is also required. For example,
#INCLUDE "DLL.CH" #INCLUDE "KEYCODE.CH" #INCLUDE "FCE32.CH"
xpp list.prg
alink /subsystem:console winftp.obj fce32.lib
To compile and link windows GUI programs, say WINFTP.PRG, use
xpp winftp.prg
alink /subsystem:windows winftp.obj fce32.lib
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.
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.
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.
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'.
If you don't have the Alaska Software Xbase++ compiler, you can find it on the web at
http://www.alaska-software.com
Each example program, with the exception of FCEVER.PRG and WINFTP.PRG, must be edited with your FTP protocol parameters before compiling. Refer to the SEE User's Manual (SEE_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.
The first example program is the program FCEVER (FCE Version) which displays the FCE library version number and registration string.
xpp fcever.prg
alink /subsystem:console fcever.obj fce32.lib
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
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
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".
xpp getpro.prg
alink /subsystem:console getpro.obj fce32.lib
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
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
xpp ftp2.prg
alink /subsystem:console ftp2.obj fce32.lib
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 a 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
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