1 Introduction

1.1 Features
1.2 Documentation Set
1.3 Example Program
1.4 Installation
1.5 Uninstalling
1.6 Pricing
1.7 Updates

2 Library Overview

2.1 Dynamic Link Libraries
2.2 Keycode
2.3 Win32 STDCALL and DECLSPEC
2.4 Adding FCE To Your Program

3 Compiler Issues

3.1 Compiling Example Programs
3.2 PowerBASIC Console Compiler (PBCC)
3.3 PowerBASIC DLL Compiler (PBDLL)
3.4 PowerBASIC Windows Compiler (PBWIN)
3.5 Compiling FCE Source

4 Example Programs

4.1 FCEVER
4.2 GET
4.3 LIST
4.4 FIELDS
4.5 FTP
4.6 PROXY
4.7 PROXY2
4.8 MGET
4.9 MPUT
4.10 SPEED
4.11 WinVER
4.12 WinGET

5 Revision History

1 Introduction

The FTP Client Engine for PowerBASIC (FCE4PB) is a component library of functions providing direct control of the FTP protocol from a PowerBASIC application. The FCE component library can be used for both anonymous and private FTP sessions.

A simple interface allows connecting to any FTP server, navigating its directory structure, listing files, sending files, deleting files, and receiving files using the FTP protocol.

The FTP Client Engine for PowerBASIC supports and has been tested with all versions of the PowerBASIC Console Compiler (PBCC), PowerBASIC DLL Compiler (PBDLL), and PowerBASIC Windows Compiler (PBWIN). FCE4PB includes several example programs that demonstrate FTP processing to help software developers easily build software applications using FCE4PB.

FCE4PB is implemented as a Win32 DLL (Dynamic Link Library). FCE4PB can be used with Windows 95/98/Me/XP/2003 and NT/2000. The FTP Client Engine SDK DLL (FCE32.DLL) can also be used from any language (C/C++, Visual Basic, WORD, ACCESS, EXCEL, Delphi, Visual FoxPro, Visual dBase, Xbase++, COBOL, Fortran, as well as WORD, ACCESS, EXCEL) capable of calling the Windows 32-bit API.

When comparing FTP Client Engine against our competition, note that:

• FCE4PB is a standard Windows DLL (NOT an OCX or ActiveX control) and is much smaller than a comparable OCX or ActiveX control.
• FCE4PB does NOT depend on ActiveX or Microsoft Foundation Class (MFC) libraries or similar "support" libraries.
• FCE is fully threadable.
• The FCE functions can be called from applications not capable of using controls.

MarshallSoft also has versions of the FTP Client Engine Library for C/C++ (FCE4C), Delphi (FCE4D), Visual Basic (FCE4VB), Visual FoxPro (FCE4FP), Visual dBASE (FCE4DB), and Xbase++ (FCE4XB). All versions of FCE use the same DLLs (FCE16.DLL or FCE32.DLL). However, the examples provided for each version are written for the specified computer 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 Library for PowerBASIC are as follows:

• Connect to any (anonymous or private) FTP server.
• Get a list of files (names or long format) on the server.
• Navigate the server directories.
• Specify ASCII or BINARY transfer mode.
• Download files (with wildcard support).
• Upload files (with wildcard support).
• Delete files.
• Rename files.
• Append files.
• Create and remove server directories.
• Support for PROXY servers.
• Supports passive mode (use with firewalls).
• Supports multiple concurrent FTP sessions.
• Resume file transfers from any offset.
• Change files names while being up/downloaded.
• Can parse long directory listings.
• Can specify the FTP or data port.
• Can set minimum and maximum response waits.
• Supports file appending.
• Supports S/KEY password encryption.
• Use on Internet or your own intranet (LAN).
• Royalty free distribution with your compiled application.
• Can be purchased with or without source code.
• Updates are free for one year (Updates to source code are separate).
• Evaluation version is fully functional.

1.2 Documentation Set

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

• FCE4PB Programmer's Manual (FCE_4PB.DOC, FCE_4PB.TXT, FCE_4PB.HTM)
• FCE User's Manual (FCE_USR.DOC, FCE_USR.TXT, FCE_USR.HTM)
• FCE Reference Manual (FCE_REF.DOC, FCE_REF.TXT, FCE_REF.HTM)

Each manual comes in three formats:

• Microsoft Word (files ending in .DOC). The best format for printing manuals.
• Hyper Text (files ending in .HTM). Use any web browser to read.
• ASCII Text (files ending in .TXT).

The FCE_4PB Programmer's Manual is the language specific (PowerBASIC) 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.

The FCE Reference Manual (FCE_REF) contains details on each individual FCE function.

Use Microsoft Word or Microsoft WordPad to print the document files. All manuals can also be viewed online at http://www.marshallsoft.com/fce4pb.htm

1.3 Example Program

The following PBCC example demonstrates the use of some of the FTP Client library functions:

     $INCLUDE "FCE32.PBI"
     $INCLUDE "KEYCODE.PBI"
   
     FUNCTION PbMain() AS LONG
     Dim Code As Integer
     Dim Srvr AS ASCIIZ * 50
     Dim User AS ASCIIZ * 50
     Dim Pass AS ASCIIZ * 50
     Dim Temp As Asciiz * 128
   
     ' Set FTP parameters
   
     Srvr = "ftp.marshallsoft.com"
     User = "anonymous"
     Pass = "you@traveller.com"
   
     ' attach FCE
     Code = fceAttach(1, %FCE_KEY_CODE)
     If Code < 0 Then
       PRINT "Cannot attach FCE" & Str$(Code)
       Return
     End If
   
     ' Connect to FTP server
     PRINT "Connecting to ";Srvr;" as user '";User;"' ...";
   
     Code = fceConnect(0, Srvr, User, Pass)
     IF Code < 0 THEN
       PRINT "Error" & Str$(Code)
       Code = fceRelease()
       Exit Function
     ELSE
       PRINT " We are connected!"
     END IF
   
     ' close and exit
     Code = fceClose(0)
     Code = fceRelease()
   
     END FUNCTION
   

In the example program above, fceConnect is called to connect to the FTP server as user "anonymous" and password "you@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. Access online at http://www.marshallsoft.com/fce_ref.htm

1.4 Installation

1. Before installation of FCE4PB, your PowerBASIC compiler (PBCC, PBDLL, or PBWIN) should already be installed on your system and tested.
   
   
2. Unzip FCE4PB26.ZIP (or FCExxxx.ZIP where xxxx is your Customer ID).
   
   
3. Run the installation program SETUP.EXE that will install all FCE4PB files, including copying FCE32.DLL to your Windows directory. No Windows system files are modified.
   
   
4. You're ready to run! Compile and run FCEVER.BAS or WinVER.BAS first.

     PBCC FCEVER

Note that the Windows registry is not modified.

1.5 Uninstalling

Uninstalling FCE4PB is very easy. FCE does not modify the registry.

First, run UNINSTAL.BAT, which will delete FCE32.DLL from your Windows directory, typically C:\WINDOWS for Windows 95/98/Me/XP or C:\WINNT for Windows NT/2000.

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

1.6 Pricing

A developer's license for FCE4PB 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)

1.7 Updates

When you register FCE4PB 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, your license must be updated if you want to be able to download updates. Your license can be updated for $30 if ordered within one year of the original purchase (or previous update). After one year, licenses can be updated for $55.

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

Also see file UPDATES.TXT.

2 Library Overview

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

2.1 Dynamic Link Libraries

The FTP Client Engine library is implemented as a dynamic link library (DLL). 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.2 Keycode

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.PBI. The keycode for the evaluation 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 evaluation version of the FCE DLL's from the Windows search path.

2.3 Win32 STDCALL and DECLSPEC

FCE32 is written in ANSI C and is compiled using the STDCALL and DECLSPEC keywords. This means that FCE4PB 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 program capable of calling the Windows API provided that the proper declaration file is used.

2.4 Adding FCE To Your Program

In order to add FCE to your PowerBASIC program, add

     $INCLUDE "FCE32.PBI"
     $INCLUDE "KEYCODE.PBI"

after any other $INCLUDE statements. Then add

     Code = fceAttach(%FCE_KEY_CODE)
     If Code < 0 Then
       '... display error code to user here...
       EXIT FUNCTION
     END IF

as the fist executed FCE function.

Also refer to the example programs.

3 Compiler Issues

The FTP Client Engine for PowerBASIC supports and has been tested with all versions of the PowerBASIC Console Compiler (PBCC), PowerBASIC DLL Compiler (PBDLL), and PowerBASIC Windows Compiler (PBWIN). Be sure to read the comments at the beginning of each example program.

3.1 Compiling Example Programs

Most example programs are compiled at the command line with the PowerBASIC Console Compiler:

• PBCC FCEVER.BAS
• PBCC LIST.BAS
• PBCC FIELDS.BAS
• PBCC WINFTP.BAS
• PBCC PROXY.BAS
• PBCC MGET.BAS
• PBCC MPUT.BAS
• PBCC SPEED.BAS

Other example programs (WinVER.BAS and WinGET ) are designed to be compiled using the PowerBASIC Windows (PW/WIN) compiler. See Section 4, "Example programs", for more information on the example programs.

3.2 PowerBASIC Console Compiler (PBCC)

Most of the example programs are written for the PowerBASIC Console Compiler (PBCC). Be sure to read the comments at the beginning of each example program. Also see Section 4.0 "Example Programs" below.

3.3 PowerBASIC DLL Compiler (PBDLL)

FCE functions can be called from programs written for the PowerBASIC DLL Compiler (PBDLL). The same DLL (FCE32.DLL) is used for both PowerBASIC and Visual Basic. FCE functions are defined in FCE32.PBI for PowerBASIC and in FCE32.BAS for Visual Basic. The Visual Basic version can be downloaded from www.marshallsoft.com/fce4vb.htm

3.4 PowerBASIC Windows Compiler (PBWIN)

FCE functions can be called from programs written for the PowerBASIC Windows Compiler (PBWIN). There are no differences in how FCE functions are called in programs written in any of the Windows PowerBASIC compilers.

Refer to the WinVER.BAS and WinGET.BAS example programs.

3.5 Compiling FCE Source

FCE32.DLL is written in standard ANSI C (FCE32.C), and has been compiled using Microsoft Visual C/C++ with the STDCALL and DECLSPEC compiler keywords. Source code for the FCE library is provided in the registered version (if ordered) only.

For more information on the C/C++ version of FCE, download the latest version of FCE4C from our web site at http://www.marshallsoft.com/fce4c.htm

4 Example Programs

Several example programs are included in FCE4PB. Their primary purpose is to demonstrate how to call FCE functions. Be sure to read the comments at the beginning of each example program

All of the example programs (except WinVER.BAS and WinGET.BAS) are compiled using the PowerBASIC Console Compiler (PBCC). However, FCE4PB functions can also be called from PowerBASIC DLL Compiler (PBDLL) programs or PowerBASIC for Windows (PBWIN) programs.

Note that the INCLUDE files FCE32.PBI and KEYCODE.PBI are referenced by all PowerBASIC programs and should normally be in the same directory as the application code. However, the value of the keycode found in KEYCODE.PBI can be pasted directly into the call to fceAttach, in which case the file KEYCODE.PBI is not needed.

Before writing your own programs, compile and run the example programs.

41 FCEVER

The first example (PBCC) program is the program FCEVER (FCE Version) that displays the FCE library version number and registration string.

Compile with:

     PBCC FCEVER.BAS

4.2 GET

The GET (PBCC) example program connects to our FTP server anonymously and downloads the file "fce-new.txt".

Compile with:

     PBCC GET.BAS

4.3 LIST

The LIST (PBCC) example program connects to a specified FTP server and lists all files.

Note that LIST could be modified to take all parameters from any source (command line, file, etc.).

Compile with:

     PBCC LIST.BAS

4.4 FIELDS

The FIELDS example (PBCC) program connects to a specified FTP server and lists all files by field. Before compiling, edit FIELDS.BAS with the appropriate FTP parameters.

Note that FIELDS could be modified to take all parameters from any source (command line, file, etc.).

Compile with:

     PBCC FIELDS.BAS

4.5 FTP

FTP.BAS is an example (PBCC) FTP application that can be used to connect to an FTP server and upload, download, and delete files. FTP is a general purpose FTP client. All parameters are entered by the user at runtime.

Compile with:

     PBCC FTP.BAS

4.6 PROXY

The PROXY example (PBCC) program connects to an FTP server through a proxy server using the "USER@SERVER" protocol, also known as the "remote user" protocol..

Refer to the FCE User's Manual (FCE_USR) for a discussion of proxy servers. Section 3.7 "Proxy Server", of the FCE User's Manual (FCE_USR). http://www.marshallsoft.com/fce_usr.htm#Section_3.7

Before compiling, the proxy server and proxy port must be specified in PROXY.BAS.

Note that PROXY could be modified to take all parameters from any source (command line, file, etc.).

Compile with:

     PBCC PROXY.BAS

4.7 PROXY2

The PROXY example (PBCC) program connects to an FTP server through a proxy server using the "USER after Logon" protocol, also known as the "double login protocol".

Refer to the FCE User's Manual (FCE_USR) for a discussion of proxy servers. Section 3.7 "Proxy Server" of the FCE User's Manual (FCE_USR). http://www.marshallsoft.com/fce_usr.htm#Section_3.7

Before compiling, the proxy server and proxy port must be specified in PROXY2.BAS.

Note that PROXY2 could be modified to take all parameters from any source (command line, file, etc.).

Compile with:

     PBCC PROXY2.BAS

4.8 MGET

The MGET example (PBCC) program downloads files according to a wildcard pattern (using '?' and '*' characters). Note that MGET could be modified to take all parameters from any source (command line, file, etc.).

Compile with:

     PBCC MGET.BAS

4.9 MPUT

The MPUT example (PBCC) program uploads files according to a wildcard pattern (using '?' and '*' characters). Note that MPUT could be modified to take all parameters from any source (command line, file, etc.).

Compile with:

     PBCC MPUT.BAS

4.10 SPEED

The SPEED example (PBCC) 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.

     PBCC SPEED.BAS

4.11 WinVER

The WinVER example program is a PowerBASIC PB/WIN program that displays the FCE version number, build number, and registration string. This program is the PBWIN equivalent of the PBCC program FCEVER.BAS.

Compile with the "PowerBASIC Compiler for Windows IDE"

4.12 WinGET

The WinVER example program is a PowerBASIC PB/WIN program that connects to our FTP server at ftp://ftp.marshallsoft.com anonymously and downloads the file "fce-new.txt". This program is the PBWIN equivalent of the PBCC program GET.BAS.

Compile with the "PowerBASIC Compiler for Windows IDE"

5 Revision History

The FTP Client Engine DLL (FCE32.DLL) is written in ANSI C. All language versions of FCE (C/C++, Delphi, Visual Basic, PowerBASIC, FoxPro, dBase, Xbase++, COBOL, and Fortran) use the same identical DLLs.

Version 1.2: August 20, 1999

The initial release of the PB version of FCE.

Version 2.0: June 8, 2000

• WriteBufferSize default reduced to 512.
• Added %FCE_GET_LINE_COUNT to fceGetString.
• Rename file being downloaded by specifying "oldname:newname" for file name.
• Added %FCE_SET_DATA_PORT to fceSetInteger.
• Password not used if specified password has zero length.
• fceSetLocalDir verifies that local directory is writable.

Version 2.1: January 25, 2001.

• Increased buffer size from 64 to 128 bytes for LocalDir and ServerDir.
• WriteBufferSize default increased to 512.
• Password not used if specified password has zero length.
• fceSetLocalDir() verifies that local directory is writable.
• Added %FCE_SET_APPEND_MODE.
• Allow 128 character filenames.
• Added %FCE_RENAME_DELIMITER to fceSetInteger().
• Corrected fceGetStatus(Chan, %FCE_CONNECT_STATUS)
• Added %FCE_SET_CLIENT_OFFSET and %FCE_SET_SERVER_OFFSET.
• Rename file being up/downloaded by specifying "oldname:newname" for file.
• Added %FCE_GET_LOCAL_IP to fceGetString.
  
  
  

Version 2.2: October 2, 2001.

• Default write buffer size increased from 512 to 1024.
• Added fceMatchFile function (used in multi-file uploads and downloads).
• Specify "User" as Chr$(0) [in fceConnect] to skip USER and PASS processing.
• Performance improvements.
• Added MGET and PROXY example programs.

Version 2.3: January 3, 2003.

• Added %FCE_SET_BLOCKING_MODE to control blocking (default ON) while connecting.
• Size of command buffer in fceCommand increased from 64 to 128 bytes.
• "WARNING: 226/250 not seen" written to log file rather than returning error.
• Added %FCE_GET_ERROR_LINE.
• fceCommand sends CRLF with command in one network write.
• Added fceFileLength function.
• fceExtract handles line # 0.
• Added %FCE_GET_QUEUE_ZERO (returns # times fceQueueLoad returns 0).
• Changed to 32 channels & 128 data ports.
• fceGetList returns error if receive buffer is too small.

Version 2.4: May 13, 2004.

• Added %FCE_SET_CONNECT_WAIT_IN_SECS.
• Added %FCE_SET_MAX_RESPONSE_WAIT_IN_SECS.
• Added %FCE_SET_MAX_LINE_WAIT_IN_SECS.
• %FCE_NOT_COMPLETED returned if code 226 (or 250) not returned by control socket (in 2 tries).
• Number data ports changed to 2048 per channel for 1 and 2 channels
• Number data ports changed to 512 data ports per channel for 3 to 8 channels
• Number data ports changed to 128 data ports per channel for 9 to 32 channels
• DataPort mask corrected to 0x7FFF
• Added fceGetLocalFList function to get list of files in local directory.
• Added fceGetLocalFSize function to get the size of a file in the local directory.
• Added new MPUT and MGET example programs (using wildcards).
• Added HELLO example program for PB/WIN.
  
  
  

Version 2.5: July 29, 2005

• LocalDir always stored with backslash as last character.
• fceWriteSocket makes up to 12 attempts to write.
• Add FCE_AUTO_LOG_CLOSE and FCE_CLOSE_LOG_FILE
• Adjusted wait time-outs.
• Added FCE_NO_GREETING error.
• Improved operation of fceGetInteger(Chan, FCE_GET_CONNECT_STATUS).
• Added GET.BAS example program.
• Added fceShortToByte and fceByteToShort functions.

Version 2.6: February 13, 2007

• Maximum PUT buffer size increased from 8K to 16K (16384)
• Recoded sleep wait in fceWriteSocket for improved upload performance.
• Added internal memory allocation debugging.
• Added GET_FULL_RESPONSE
• Close control socket whenever fceConnect fails (fixes socket leak problem).
• Added FCE_SET_FIRST_DATA_PORT and FCE_SET_LAST_DATA_PORT to fceSetInteger.
• Maximum data port extended to 65535.
• Added FCE_HIDE_PASSWORD to fceSetInteger.
• Added S/KEY authentication
• Added fceGetTicks()
• Added FCE_STATUS_BEFORE_WRITE to fceSetInteger.