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.



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 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 Example Programs
3.1 FCEVER
3.2 LIST
3.3 FIELDS
3.4 GETPRO
3.5 FTP
3.6 FTP2
3.7 WINFTP
4 Revision History

1 Introduction

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:

1.1 Documentation Set

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.

1.2 Example Program

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.

1.3 Installation

  1. Before installation of FCE4XB, your Xbase++ compiler should already be installed on your system and tested.

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

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

  4. You're ready to run!

Note that the Windows registry is not modified.

1.4 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 3.1/95/98 or C:\WINNT for Windows NT.

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

1.5 Ordering

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


2 Compiler Issues

2.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.5 below.

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

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

2.2 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 1.2 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 3.0 "Example Programs" for more details on each of the example programs. To compile and link console mode programs, say LIST.PRG, use
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

2.3 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.4 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.5 Key Codes

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


3 Example Programs

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.

3.1 FCEVER

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

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.

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

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.

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

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

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

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

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

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

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


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


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


Version 2.0: May 18, 2000