FTP Client Engine
Library for Visual dBase


Programmer's Manual


(FCE4DB)


Version 2.0

May 11, 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 Compiling dBase Programs
2.2 Compiling dBase Projects
2.3 Dynamic String Storage
2.4 Passing Strings to FCE
2.5 Key Code
3 Example Programs
3.1 FCEVER
3.2 LIST
3.3 GETPRO
3.4 FTP
3.5 FTP2
3.6 WINFTP
3.7 FIELDS
4 Revision History

1 Introduction

FCE4DB is the easiest way to write FTP applications in Visual dBase! FCE can be used for both anonymous and private FTP sessions.

The FTP Client Engine (FCE) is a library of functions providing direct control of the FTP protocol. With FCE4DB, you can write programs that easily:

FCE4DB supports and has been tested with Visual dBase 5.7 and 7.0. Several example programs are provided, including standard .PRG programs and .WFM forms based programs.

Both Win16 and Win32 DLLs (Dynamic Link Libraries) are provided. FCE4DB can be used with Windows 3.X, 95/98,2000 and NT. The FCE4DB DLLs (FCE16.DLL and FCE32.DLL) can also be used from any language (C/C++, WORD, ACCESS, EXCEL, PowerBASIC Console Compiler, Delphi, Visual FoxPro, Visual Basic, 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 (FCE4DB) 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 FCE4DB 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 C:\TEMP\FCE32.CC
#INCLUDE C:\TEMP\KEYCODE.CC
FTPserver = "ftp.marshallsoft.com" + Chr(0)
FTPuser = "anonymous" + Chr(0)
FTPpass = "msc@traveller.com" + Chr(0)
#define TEMP_SIZE 128
#define DATA_SIZE 5000
Code = fceAttach(1, FCE_KEY_CODE
if Code < 0
  ? "Cannot attach FCE ", Code
  return
endif
? "Connecting to ", FTPserver
Code = fceConnect(0, FTPserver, FTPuser, FTPpass)
if Code < 0
  TempBuffer = SPACE(TEMP_SIZE)
  Code = fceErrorText(0,Code,TempBuffer,TEMP_SIZE)
  ? Left(TempBuffer,Code)
  Code = fceRelease()
  return
endif
? "Connected. Now getting file list."
DataBuffer = SPACE(DATA_SIZE)
Code = fceGetList(0, FCE_FULL_LIST, DataBuffer, DATA_SIZE)
if Code <= 0
  TempBuffer = SPACE(TEMP_SIZE)
  Code = fceErrorText(0,Code,TempBuffer,TEMP_SIZE)
  ? Left(TempBuffer,Code)
else
  ? Left(DataBuffer,Code)
endif
Code = fceClose(0)
Code = fceRelease()
? "Logged off."
return

In the example program above, fceConnect is called to connect to the FTP server as user "anonymous" and password "msc@traveller.com".

Next, a full file listing is requested. 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 FCE4DB, your Visual dBase compiler (any version) should already be installed on your system and tested.

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

  3. Run INSTALL.BAT which will copy FCE32.DLL (for 32-bit dBase) and FCE16.DLL (for 16-bit dBase) to either C:\WINDOWS or C:\WINNT.

  4. Edit the example programs (.PRG and .WFM):

  1. You're ready to run! Win16 programs (dBase 5.7) end with "16", while Win32 programs (dBase 7) end with "32". For example,

FCEVER16.PRG --- "FCE Version" program for 16-bit Visual dBase. FCEVER32.PRG --- "FCE Version" program for 32-bit Visual dBase.

Note that the Windows registry is not modified.

1.4 Uninstalling

Uninstalling FCE4DB 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.

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

1.5 Ordering

FCE4DB may be registered for $95. See Section 1.4 "Ordering" in the FCE User’s Manual (FCE_USR) for details on ordering.

1.6 Updates

When you register FCE4DB 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 Compiling dBase Programs

Visual dBase programs end with the extension ".PRG". Before compiling any of the example programs, edit each file with your Internet TCP/IP parameters. Programs can be edited within any text editor, and compiled from the VDB (Visual dBase) command window with the COMPILE command (e.g.: COMPILE LIST.PRG) or executed from the VDB command window with the DO command (e.g.: DO LIST.PRG) .

To open a program within the Visual dBase source editor, choose "File", then "Open". When the "Open File" dialog box appears, choose "Programs" for "Files of Type", then choose the program (*.PRG) to open. Lastly, choose "Open in Source Editor" for "Action" and push the "Open" button.

After editing the source program with your internet (or TCP/IP) parameters, you are ready to compile. From the dBase menu bar, choose "Build", then "Compile". To run choose, "Run". The VDB command window must be displayed in order to see the output.

2.2 Compiling dBase Projects

Visual dBase projects consist of several types of files such as forms, reports, data modules, etc. The project file itself ends with the extension of ".PRJ".

There is one example Visual dBase project WINFTP. Open WINFTP by choosing "File", then "Open Project" from the dBase menu bar. To compile WINFTP, choose "Build" from the menu bar, then "Rebuild All". This will create WINFTP.EXE, which can be executed by choosing "Execute winftp.exe" from the "Build" menu bar pulldown, or from the Windows command line prompt.

2.3 Dynamic String Storage

When calling a FCE function which returns information in a string buffer, allocate the necessary memory immediately before the call. For example:

TempBuffer = SPACE(TEMP_SIZE)
Code = fceErrorText(0,Code,TempBuffer,TEMP_SIZE)

2.4 Passing Strings to FCE

Append a null character to the end of all strings passed to FCE functions. For example

Server = "ftp.marshallsoft.com" + Chr(0)

2.5 Key Codes

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

3 Example Programs

Edit each example program (*.PRG) with your Internet TCP/IP specifications before compiling. Visual dBase 16-bit programs end with "16.PRG" while 32-bit programs end with "32.PRG".

Refer to section 2 above for help in compiling the example programs.

3.1 FCEVER

The FCEVER ("FCE Version") program (FCEVER16.PRG and FCEVER32.PRG) displays the DLL version, build number, and registration string. This is the first program to try. It does not require a TCP/IP (Internet) connection. Run FCEVER from the VDB command window with "DO".

3.2 LIST

The LIST program (LIST16.PRG and LIST32.PRG) connects to the MarshallSoft FTP site at "ftp.marshallsoft.com" as user "anonymous" with password "msc@traveller.com". Change the password to your email address before compiling. Run LIST.PRG from the command window.

After connecting, LIST gets the list of all files on the server at the base FTP directory level, then logs off.

3.3 GETPRO

GETPRO (GETPRO16.PRG and GETPRO32.PRG) is an example program that connects to the MarshallSoft FTP server at

ftp://ftp.marshallsoft.com

and downloads the file PRODUCTS.TXT from the server directory

pub/other

3.4 FTP

The FTP program (FTP16.PRG and FTP32.PRG) is a generic FTP program that can perform the most basic FTP functions such as listing and downloading files. Note that there are many FCE functions not implemented in the FTP.PRG example. Run FTP.PRG from the VDB command window.

3.5 FTP2

The FTP2 program (FTP2_16.PRG and FTP2_32.PRG) is identical to FTP except that it uses fceDriver when downloading and uploading files. Refer to Section 4, "Theory Of Operation", in the FCE User's Manual (FCE_USR). Run FTP2.PRG from the VDB command window.

3.6 WINFTP

The WINFTP program (WINFTP16.WFM and WINFTP32.PRG) is similar to the FTP program, except that it uses the Visual dBase form. To compile WINFTP16.FRM, choose "Open" from under "File" on the Visual dBase 5.7 menu bar. To compile WINFTP32.FRM, choose "Open Project" from under "File" on the Visual dBase 7 menu bar.

Note that code at the beginning of WINFTP32.WFM

     #INCLUDE C:\TEMP\FCE32.CC
     #INCLUDE C:\TEMP\KEYCODE.CC
     #define TEMP_SIZE 128
     #define DATA_SIZE 5000
must be re-inserted manually after modifying the file with the dBase form designer. Do the same for WINFTP16.WFM.

3.7 FIELDS

The FIELDS program (FIELDS16.PRG and FIELDS32.PRG) connects to the MarshallSoft FTP site at "ftp.marshallsoft.com" as user "anonymous" with password "msc@traveller.com". Change the password to your email address before compiling. Run FIELDS from the command window. The FIELDS program is similar to the LIST program. After connecting, FIELDS gets the list of all files on the server at the base FTP directory level, and lists each field as a separate string.

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

Version 1.2: October 15, 1999

The initial release of the dBase version of FCE.

Version 2.0: May 11, 2000