MarshallSoft

FTP Client Engine
Library for Xbase++


Programmer's Manual


(FCE4XB)


Version 3.0

October 22, 2009



This software is provided as-is.
There are no warranties, expressed or implied.



Copyright (C) 2009
All rights reserved



MarshallSoft Computing, Inc.
Post Office Box 4543
Huntsville AL 35815


web : www.marshallsoft.com


MARSHALLSOFT is a registered trademark of MarshallSoft Computing.



TABLE OF CONTENTS


1 Introduction
1.1 Features
1.2 Documentation Set
1.3 Using the FCE Library
1.4 Error Display
1.5 Example Program
1.6 Installation
1.7 Uninstalling
1.8 Pricing
1.9 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.12 MDTM
5 Revision History

1 Introduction

The FTP Client Engine for Xbase++ (FCE4XB library is a toolkit that allows software developers to quickly develop FTP client applications in Alaska Xbase++.

The FTP Client Engine (FCE) is a DLL library that uses the Windows API to provide direct and simple control of the FTP protocol. The FCE component library can be used for both anonymous and private FTP sessions.

A straightforward interface provides the capability to easily build Xbase++ software applications to connect to any FTP server, navigate its directory structure, list files, upload files, rename files, delete files, append files, and download files using the FTP protocol.

The FTP Client Engine Programmers Manual provides information need to compile and run programs in an Alaska Xbase++ programming environment.

The FTP Client Engine for Xbase++ supports and has been tested with all versions of Alaska Xbase++ (Xbase++ v1.3 through Xbase++ v1.9). FCE4XB includes several example programs that demonstrate FTP processing from an Xbase++ application.

FCE4XB runs under all versions of 32-bit Windows (Windows 95, Windows 98, Windows ME, Windows 2000, Windows 2003, Windows NT, Windows XP and Windows Vista) and 64-bit Windows (Windows Vista 64). A Win32 DLL is provided with FCE4XB (a Win32 DLL is available). The FTP Client Engine SDK DLL's (FCE32.DLL and FCE64.DLL) can also be used from any development environment (Visual Basic, C++, Delphi, Visual FoxPro, COBOL, Visual FoxPro, dBase, PowerBASIC, etc.) capable of calling the Windows API.

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

MarshallSoft also has versions of the FTP Client Engine Library for C/C++ (FCE4C), Visual Basic (FCE4VB), Delphi (FCE4D), PowerBASIC (FCE4PB), Visual FoxPro (FCE4FP), and Visual dBASE (FCE4DB). All versions of FCE use the same DLLs (FCE32.DLL and FCE64.DLL). However, the examples provided for each version are written for the specified programming 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.2 Documentation Set

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

Each manual comes in two formats:

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.

All manuals can also be viewed online at http://www.marshallsoft.com/fce4xb.htm

1.3 Using the FCE Library

The FTP Client Engine component library (FCE) has been tested on multiple computers running Windows 95/98/Me/NT/2000/2003/XP/Vista and Windows NT/2000.

The FCE4XB library has been tested with all versions of 32-bit Alaska Xbase++. The FCE32.DLL functions may be called by any Windows application program capable of calling the Windows API provided that the proper declaration file is used. FCE64.DLL is available to use with Win64 applications.

The SETUP installation program will copy the DLL to the Windows directory. Refer to Section 1.5 "Installation". After SETUP is run, the FCE4XB files are copied to the directory specified (default \FCE4XB). Three sub-directories are created, as follows:

     DOCS - All documentation files
     APPS - All example code
     DLLS - All DLL's

1.4 Error Display

The error message text associated with FCE error codes can be displayed by calling fceErrorText. Each sample program contains examples of error processing. Also see the file fceErrors.txt for a list of all FCE error codes

1.5 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 = "you@your_isp.com" + Chr(0)
     FTPdirectory = "pub/test" + Chr(0)
     FTPfilename = "fceErrors.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.6 Installation

  1. Before installation of FCE4XB, an Xbase++ compiler (any version) should already be installed on the system and tested.

  2. Unzip FCE4XB30.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 the Windows directory. The Windows directory is typically C:\WINDOWS for Windows 95/98/Me/XP/2003/Vista 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.7 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/Vista or C:\WINNT for Windows NT/2000.

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

1.8 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)

Registration includes one year of free updates and technical support.

1.9 Updates

When a developer license is purchased for FCE4XB, the developer will be sent a registered DLL plus a license file (FCExxxx.LIC, where xxxx is your Customer ID). The license file can be used to update the registered DLL for a period of one year from purchase. Updates can be downloaded from

   
     http://www.marshallsoft.com/oem.htm
   

After one year, the developer license must be updated to be able to download updates. A developer license can be updated for $30 if ordered within one year of the original purchase (or previous update). Between one year and three years, licenses can be updated for $55. After three years, updates are $75.

Note that the registered DLL never expires.

Updates to the source code can be purchased for $100 in addition to the cost of the update ($30/ $55/$75).

Also see file UPDATES.TXT.

2 Library Overview

2.1 Keycode

FCE32.DLL has a keycode encoded within it. The 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 evaluation version is 0. The developer will receive a new key code after registering. SETUP copies the keycode to the /APPS sub-directory (folder). The KEYCODE is passed to fceAttach.

If the error message (value -74) is returned when calling fceAttach, it means that the keycode in the application does not match the keycode in the DLL. After registering, it is best to remove the evaluation version of the FCE DLL from the Windows search.

2.2 Dynamic Link Libraries

The FTP Client Engine library is implemented as a dynamic link library (DLL). A Win32 DLL is 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 FCE4XB 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:

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 the 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 fceAttach.

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

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

All example programs will work with all versions of Alaska Xbase++. Each has been tested and shows how to correctly use FCE functions. It suggested that the developer compile and run the example programs before developing an application using FCE4XB .
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.1 above for information on compiling and linking the example programs.

4.1 FCEVER

The first example program is the program FCEVER (FCE Version) that 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 the 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 the 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 the 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 the 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.7 "Proxy Server", of the FCE User's Manual (FCE_USR). http://www.marshallsoft.com/fce_usr.htm#Section_3.7

     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 the 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

4.12 MDTM

The MDTM example program requests the "File Modification Time" for a file. However, not all FTP servers support the MDTM command.

     xpp mdtm.prg
     alink /subsystem:console mdtm.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

Version 2.1: February 13, 2001.

Version 2.2: October 25, 2001.

Version 2.3: December 20, 2002.

Version 2.4: June 22, 2004.

Version 2.5: July 26, 2005.

Version 2.6: February 27, 2007

Version 2.7: July 23, 2008

Version 3.0: October 22, 2009

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