FTP Client Engine

Users Manual


(FCE_USR)


Version 2.0

May 3, 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 USA


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
1.2 User Support
1.3 ASP Ombudsman
1.4 Ordering
2 Library Overview
2.1 Dynamic Link libraries
2.2 GUI and Console Mode
2.3 Using the Library
2.4 Key Codes
3 Using FTP
3.1 FTP Basics
3.2 Anonymous Access
3.3 Passive Mode
3.4 Socket Address In Use Error
3.5 Auto Dial
3.6 Proxy Servers
4 Theory of Operation
4.1 Indirect Method
4.2 Direct Method
5 Versions of FCE
5.1 Shareware Version
5.2 Student Version
5.3 Professional Version
6 Using FCE with Other Languages
7 Problems
8 Legal Issues
8.1 Registration
8.2 License
8.3 Warranty
9 Summary
9.1 FCE Function Summary
9.2 FCE Error Return Code List

1 Introduction

This manual applies to the FTP Client Engine (FCE) for all supported languages.

We have versions of FCE for C/C++ (FCE4C), Delphi (FCE4D), Visual Basic (FCE4VB), PowerBASIC (FCE4PB), Visual FoxPro (FCE4FP), Visual dBase (FCE4DB), Alaska Xbase++ (FCE4XB), and COBOL (FCE4CB). All versions of FCE use the same DLLs (FCE16.DLL or FCE32.DLL).

We also have declaration files and example programs for a few other languages.

1.1 Documentation Set

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

Each manual comes in three formats:

The FCE4x Programmer’s Manual is the language specific manual. All language dependent programming issues are discussed in this manual. Language specific manuals are as follows:

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.

Use Microsoft Word 97/99 or Microsoft WordPad to print the document files.

1.2 User Support

We want you to be successful in developing your applications using FCE! We are committed to providing the best library that we can. If you have any suggestions or comments, please let us know.

If you are having a problem using FCE, refer to section 7.0 "Problems". If you still cannot resolve your problem, email us at

support@marshallsoft.com

You can also reach us at 256-881-4630 between 7:00 AM and 7:00 PM CST Monday through Friday. You can also often reach us on Saturday.

The latest versions of our products are available on our web site at

http://www.marshallsoft.com

and on our anonymous FTP site at

ftp://ftp.marshallsoft.com/pub

Registered users can update to the latest DLL’s at

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

The MarshallSoft Computing newsletter "Comm Talk" is published quarterly on our web site. It discusses various communications problems and solutions using our products as well as related information.

1.3 ASP Ombudsman

MarshallSoft Computing, Inc. is a member of the Association of Shareware Professionals (ASP). ASP wants to make sure that the shareware principle works for you. If you are unable to resolve a shareware- related problem with an ASP member by contacting the member directly, ASP may be able to help. The ASP Ombudsman can help you resolve a dispute or problem with an ASP member, but does not provide technical support for members' products. Please write to the ASP Ombudsman at 157-F Love Ave., Greenwood, IN 26142 USA, FAX 317-888-2195, or send email to omb@asp-shareware.org.


1.4 Ordering

The professional version of FCE may be registered for $95 (US dollars) for email delivery. The professional version DLL is also branded internally with your company name.

The fastest and easiest way to order is on our web site at

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

You can also order by completing INVOICE.TXT and emailing (orders@marshallsoft.com), mailing (see our address at top), or faxing (256-880-0925) it to us.

Multiple copy discounts (3 or more) and site licenses are available. Please call for details.

We accept American Express, VISA, MasterCard, Discover, checks in US dollars drawn on a US bank, International Postal Money Orders, and purchase orders (POs) within the USA from recognized US schools and companies listed in Dun & Bradstreet.

For credit card orders, be sure to include the account number, the expiration date, the exact name on the card, and the complete card billing address (the address to which the credit card bill is mailed- not the bank’s). Please include card holder's signature on faxed orders.

Print the file INVOICE.TXT if a "Pro Forma" invoice is needed. The registered package includes:

  1. Win16 & Win32 FCE Libraries w/o shareware screens.
  2. Telephone and email support for one year.

1.4.2 Academic Discount

We offer an "academic price" of 40% off the normal price for prepaid email orders to faculty and full time students currently enrolled in any accredited high school, college, or university. To qualify for the discount, your school must have a web site and you must have an email address at your school.

When ordering, ask for the "academic discount", or enter "student at" (or "faculty at") and your schools web site address (URL) in the comments field of the order form on our web site order page . Your order will be sent to your email address at your school.

This offer is not retroactive and cannot be used with any other discount. Products bought with academic pricing can not be used for any commercial purpose.

1.4.3 Disk Only

When ordering FCE, a 3.5" HD disk can be purchased for $5 for delivery to the, US, Canada, and Mexico. For all other destinations, the disk is $8.

See INVOICE.TXT or http://www.marshallsoft.com/order.htm

1.4.4 Disk and Printed Manuals

Printed manuals (see Section 1.1 "Documentation Set") are the same as in the FCE archive. Printed manuals can be purchased for $20 for delivery to the US, Canada, and Mexico. For all other destinations, printed manuals are $25. Printed manuals also comes with a 3.5" HD disk.

See INVOICE.TXT or http://www.marshallsoft.com/order.htm

2 Library Overview

2.1 Dynamic Link Libraries

FCE includes both Win16 [FCE16.DLL] and Win32 [FCE32.DLL] dynamic link libraries (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 a static library which is bound at link time to each and every application that uses it.

2.2 GUI and Console Mode

FCE functions can be called from WIN32 console mode programs as well as GUI programs. A "console mode" program is a Windows 95/98/NT/2000 WIN32 command line program running in a command window. Although console mode programs look like DOS programs, they are WIN32 programs which have access to the entire Windows address space.

2.3 Using the Library

The first FCE function that should be called is fceAttach, which initializes the FCE library and allocates necessary resources. fceAttach is typically called in the initialization section of your application.

After fceAttach is called, you are ready to connect to a FTP server with fceConnect. Once connected, you are ready to call the other FCE functions.

After completing your FTP session, the connection to the server can be closed with fceClose. The fceClose function should not be called if the previous fceConnect failed.

Before exiting your application, fceRelease should be called. fceRelease should not be called if fceAttach failed.

The best way to get familiar with FCE is to try out one of the example programs. The example programs are described in the FCE4x Programmer's Manual:

2.4 Key Codes

When you register FCE, you will receive a new set of DLL's and a key code for your DLL's. Pass this keycode as the second argument to fceAttach. The keycode will be found in the file named "KEYCODE". The keycode for the shareware version is 0.

3 Using FTP

3.1 FTP Basics

The FTP (File Transfer Protocol) protocol is defined by Internet document RFC 959. It is used to copy files between a FTP client and a FTP server over a TCP/IP connection using well known port 21.

In order to connect to a FTP server, the server name (or IP address), the user name, and the user password must be known. This is known as private (or protected) access.

3.2 Anonymous Access

Some FTP servers allow "anonymous" access, which is usually download only. The convention for anonymous access is to use the word "anonymous" for the user name, and the callers email address for the password. Many FTP servers will also accept "ftp" instead of "anonymous".

3.3 Passive Mode

FCE supports "Passive" mode. Passive mode means that the server specifies the data port rather than the client when listing or transferring files. Using passive mode is often necessary to get past a firewall.

Passive mode is an optional FTP command, so that although most FTP servers support passive mode, there are some that do not. Passive mode can be enabled by calling:

fceSetInteger(Chan, FCE_SET_PASSIVE, 1)

The use of passive mode is recommended when possible.

3.4 "Socket Address Already In Use" Error.

The FTP protocol specifies that data sockets are reserved after use for some fixed period of time. This means that a data socket cannot be immediately re-used. When making multiple calls to list or transfer files, FCE will increment the data socket number. However, if you terminate and then restart your application while the FTP server still has your last data socket reserved, and attempt to list or transfer files, you will get the error "socket address already in use". There are three solutions to this problem:

  1. Wait a minute or so, then try again.
  2. Use PASSIVE mode [fceSetInteger(Chan, FCE_SET_PASSIVE, 1)].
  3. Specify the port yourself by calling fceSetInteger(Chan, FCE_SET_DATA_PORT, port-number) .

3.5 Auto Dial

3.5.1 Auto Dial for Windows 95/98/2000.

To allow Dial-Up Networking (DUN) to dial up your ISP when you access the Winsock (WIN32 only):

  1. Open the DUN folder in "My Computer", and choose "Connections/Settings" from menu bar. Uncheck "prompt for information before dialing" and choose "Don't prompt to use Dial-Up Networking".

  2. Use the Windows REGEDIT program to change value "00 00 00 00" to the value "00 00 00 01" in the Windows Registry for the entry

HKEY_CURRENT_USER/Software/Microsoft/Windows/CurrentVersion/InternetSettings/EnableAutod i al

  1. Use the Windows REGEDIT program to change value "00 00 00 00" to the value "00 00 00 01" in the Windows Registry for the entry

HKEY_CURRENT_USER/Software/Microsoft/Windows/CurrentVersion/InternetSettings/EnableAutod i sconnect.

  1. Use the Windows REGEDIT program to change value "14 00 00 00" to the value "01 00 00 00" in the Windows Registry for the entry

HKEY_CURRENT_USER/Software/Microsoft/Windows/CurrentVersion/InternetSettings/DisconnectI d leTime

This changes the idle time (until disconnect) from 20 minutes (hex 14) to one minute.

3.5.2 Auto Dial for Windows NT 4

Windows NT users can control auto dialing by editing the setting in the "Dial-Up Networking" (DUN) window. Choose "More", "User Preferences", then "Appearance".

The Dial-Up Networking window can also be displayed by executing RASPHONE.EXE.

3.5.3 MarshallSoft DUN Dialer

The MarshallSoft DUN Dialer (MDD) can dial up (and hang up) under program control. MDD works under any Windows 32-bit operating system. For more information, see the MDD product page at www.marshallsoft.com/mdd4c.htm.

3.6 Proxy Servers

Connecting to a proxy server is no different from connecting to any other FTP server. You must know the IP address of the proxy server and the user name and password assigned by the proxy server. However, you may need to connect using a proxy specified port, rather than the standard well known FTP port of 21. Refer to the documentation for your specific proxy server.

4 Theory Of Operation

The FTP Client Engine is state driven. This means that each call to FCE functions (that access the server) is broken down into sequential steps, each of which can be performed within a second or so. There are two ways in which FCE is used: (1) indirect use of the state engine, and (2) direct use of the state engine.

4.1 Indirect Method

The first (or "indirect") way to use the FCE library is to allow all FCE function calls to automatically call the FCE driver (fceDriver) before returning. This is the default way that FCE operates.

The major advantage of this approach is that each FCE function returns only after it has completely finished. The disadvantage of this approach is that some functions may run for a considerable amount of time during which time the calling application must wait.

Refer to the sample program GETPRO for an example of this approach.

4.2 Direct Method

The second (or "direct") way that the FCE state driver is used is to call it (fceDriver) directly. In order to operate this way, the function fceSetInteger must be called which sets the AUTO_CALL flag to off:

fceSetInteger(Chan, FCE_AUTO_CALL_DRIVER, 0)

After the above statement is executed, the state driver (fceDriver) must be called after all other FCE functions that access the server. For example (pseudo code example),

... enable direct mode (disable indirect mode).
fceSetInteger(Chan, FCE_AUTO_CALL_DRIVER, 0)
... connect to server.
Code = fceConnect(...)
If Code < 0 Then
 ... handle error here.
End If
... run the driver.
Loop
  ... call the driver
  Code = fceDriver(Chan)
  If Code < 0 Then
    ... handle error here.
    Exit Loop
  End If
  If Code = 0 Then
    ... fceDriver has finished.
    Exit Loop
  End If
  ... display progress or do other processing here.
End Loop
... enable indirect mode (disable direct mode).
fceSetInteger(Chan, FCE_AUTO_CALL_DRIVER, 1)

The major advantage of the direct approach is that the calling application can perform other work such as reporting the progress of large downloads. The disadvantage is the extra code that must be written to call fceDriver.

Refer to the sample program WINFTP for an example of this approach.

5 Versions of FCE

The FTP Client Engine (FCE) library is available in three versions. All three versions have identical functionality.

5.1 Shareware Version

The shareware version can be differentiated from the other two versions by:

  1. The shareware reminder screen is displayed at startup.

  2. The shareware version may not be used for commercial purposes.

5.2 Student Version

The student version can be differentiated from the other two versions by:

  1. There is no shareware reminder screen.

  2. The Student version may not be used for commercial purposes.

5.3 Professional Version

The professional version can be differentiated from the other two versions by:

  1. There is no shareware reminder screen.

  2. The DLL is branded with your company name.

  3. Your branded DLLs may be distributed with your compiled applications.

The professional version may be distributed with your application as specified by the software license. See Section 1.4 "Ordering" for details on ordering.

6 Using FCE with Other Languages

We have versions of FCE for C/C++ (FCE4C), Delphi (FCE4D), Visual Basic (FCE4VB), PowerBASIC (FCE4PB), Visual FoxPro (FCE4FP), Visual dBase (FCE4DB), Alaska Xbase++ (FCE4XB), and COBOL (FCE4CB). All versions of FCE use the same DLLs (FCE16.DLL or FCE32.DLL).

The FTP Client Engine DLL’s can also be used with any application written in any language capable of calling the Windows (3.1, 95/98/2000, NT) API. FCE16.DLL is required for all Win16 (Windows 3.1) applications, and FCE32.DLL is required for all Win32 (Windows 95/98/2000/NT) applications.

Declaration files have been defined by the following languages:

C/C++                   FCE.H
Visual Basic            FCE16.BAS and FCE32.BAS
VBA (Excel, Access,…)   FCE32.BAS
PowerBASIC              FCE32.BAS [not the same as above]
Borland Delphi          FCE16.PAS and FCE32.PAS
Fujitsu COBOL           FCE32.CBI
ABSOFT FORTRAN          FCE32.INC
Visual FoxPro           FCE32.FOX
Visual dBase            FCE16.CC and FCE32.CC
Alaska Xbase++          FCE32.CH
Additional declaration files will be added. Give us a call if you need a declaration not listed above. If you have interfaced FCE to an unusual language, email us the declaration file!

7 Problems

First, be sure you are passing the proper key code. Refer to section 2.4 "Key Code". Before attempting to run any of the example programs, you should already be able to connect to the Internet (or your TCP/IP LAN) and run your normal FTP client, such as the Microsoft command line FTP client FTP.EXE (in the Windows directory). If you have trouble connecting to a FTP server, try using the IP address instead of the server name. If using the IP address works but the server name does not, the problem lies with the Domain Name System (DNS) lookup. If this does not solve your connection problem, try connecting using TELNET, located in the Windows directory. If you cannot get your application to run properly, first compile and run the example programs. If you call us to report a possible bug in the library, the first thing we will ask is if the example programs run correctly. Be sure to test the code returned from all FCE functions. Then, call fceErrorText to get the text associated with the error code. For example (C Example):
Code = fceConnect(0,"ftp.marshallsoft.com","mike", "mike");
if(Code<0)
  {static char Buffer[64];
   fceErrorText(0,Code,Buffer,64);
   printf("Error %d: %s\n", Code, Buffer);
  }
Another good idea is turn on logging by calling fceSetString(Chan, FCE_LOG_FILE, logfilename) If you encounter a problem that you cannot resolve, email us at support@marshallsoft.com. If you still get the shareware screen after registering, the problem is that Windows is finding the shareware DLL before the registered DLL. The solution is to delete (or zip up) all shareware versions of the FCE16.DLL and FCE32.DLL and run the INSTALL program. If you get "error -74" when calling fceAttach, the problem is that the keycode passed to fceAttach does not match the keycode in the DLL's. This is caused by (1) using the shareware keycode (value = 0) with the registered DLL, or (2) using the registered keycode with the shareware DLL. Be sure to review Section 3 "Using FTP".

8 Legal Issues

8.1 Registration

See section 1.4 "Ordering" for information on ordering.

8.2 License

MarshallSoft Computing, Inc. grants the registered user of FCE the right to use one copy of the FCE DLL's on a single computer in the development of any software product. The user may not use the library on more than one computer at the same time. The "student" ($57) registered DLL's may not be distributed under any circumstances, nor may they be used for any commercial purpose. The "professional" ($95) registered DLL's may be distributed (without royalty) in object form only, as part of the user's compiled application. The registered DLL's may NOT be distributed as part of any software development system (compiler or interpreter) without our express written permission. When you register, you will be sent a "key code" which enables access to the registered DLL's. You may NOT distribute or make known this key code. (see Section 2.4 "Key Code").

8.3 Warranty

MARSHALLSOFT COMPUTING, INC. DISCLAIMS ALL WARRANTIES RELATING TO THIS SOFTWARE, WHETHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, AND ALL SUCH WARRANTIES ARE EXPRESSLY AND SPECIFICALLY DISCLAIMED. NEITHER MARSHALLSOFT COMPUTING, INC. NOR ANYONE ELSE WHO HAS BEEN INVOLVED IN THE CREATION, PRODUCTION, OR DELIVERY OF THIS SOFTWARE SHALL BE LIABLE FOR ANY INDIRECT, CONSEQUENTIAL, OR INCIDENTAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE SUCH SOFTWARE EVEN IF MARSHALLSOFT COMPUTING, INC. HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES OR CLAIMS. IN NO EVENT SHALL MARSHALLSOFT COMPUTING, INC.'S LIABILITY FOR ANY SUCH DAMAGES EVER EXCEED THE PRICE PAID FOR THE LICENSE TO USE THE SOFTWARE, REGARDLESS OF THE FORM OF THE CLAIM. THE PERSON USING THE SOFTWARE BEARS ALL RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE. Some states do not allow the exclusion of the limit of liability for consequential or incidental damages, so the above limitation may not apply to you. This agreement shall be governed by the laws of the State of Alabama and shall inure to the benefit of MarshallSoft Computing, Inc. and any successors, administrators, heirs and assigns. Any action or proceeding brought by either party against the other arising out of or related to this agreement shall be brought only in a STATE or FEDERAL COURT of competent jurisdiction located in Madison County, Alabama. The parties hereby consent to in personam jurisdiction of said courts.

9 Summary

9.1 FCE Function Summary

Refer to the FCE Reference Manual (FCE_REF) for detailed information on the FCE functions. A one line summary of each function follows. There are 24 functions in the FCE library.
fceAbort                Abort FTP session.
fceAttach               Attach (initialize) FCE for use.
fceClose                Close connection opened with fceConnect.
fceConnect              Connect to FTP server.
fceDelFile              Delete file on server.
fceDelServerDir Delete server directory.
fceDriver               FCE direct mode driver.
fceErrorText    Get text associated with error code.
fceExtract              Extract line from LIST buffer.
fceGetFile              Download (receive) file.
fceGetInteger   Get FCE integer parameter.
fceGetList              Get list of files on server.
fceGetLocalDir  Get local directory.
fceGetServerDir Get server directory.
fceGetString    Get FCE string parameter.
fceHello                Send "NOP" command.
fceMakeServerDir        Create directory on server.
fcePutFile              Upload (transmit) file to server.
fceRelease              Release FCE.
fceSetInteger   Set FCE integer parameter.
fceSetLocalDir  Set local directory.
fceSetMode              Set XFER mode (ASCII or Binary).
fceSetServerDir Set server directory.
fceSetString    Set FCE parameter string.

9.2 FCE Error Return Code List

The complete list of FCE error codes follows.
FCE_ABORTED             Internal checksum fails!
FCE_ALREADY_ATTACHED    Already attached.
FCE_BAD_STATUS_FLAG     Bad status flag passed to fceStatus.
FCE_CANNOT_ALLOC        Cannot allocate memory.
FCE_CANNOT_COMPLY       Cannot comply.
FCE_CANNOT_CREATE_SOCK  Cannot create socket.
FCE_CHAN_OUT_OF_RANGE   Channel out of range.
FCE_CONNECT_ERROR       Error attempting to connect.
FCE_EOF                 Socket has been closed.
FCE_SERVER_ERROR        FTP server returned error.
FCE_INVALID_SOCKET      Invalid socket.
FCE_IS_BLOCKING         WINSOCK is currently blocking.
FCE_NO_HOST             No host name.
FCE_NO_SERVER           Cannot find FTP server.
FCE_NO_SOCK_ADDR        No available sockaddr structures.
FCE_NOT_ATTACHED        Must call fceAttach first.
FCE_NOT_SERVER          Illegal chars in server name.
FCE_PASS_NULL_ARG       PASSWORD not specified.
FCE_SERVER_NULL_ARG     SERVER not specified.
FCE_TIMED_OUT           Socket timed out.
FCE_USER_NULL_ARG       USER name not specified.
FCE_MODE_NOT_AB         Must specify 'A' or 'B' for mode.
FCE_LISTEN_ERROR        Listen error.
FCE_LISTENER_SILENT     No response on listener socket.
FCE_ACCEPT_SILENT       Timed out waiting for accept.
FCE_SOCK_READ_ERROR     Socket read error.
FCE_SOCK_WRITE_ERROR    Socket write error.
FCE_CANNOT_OPEN         Cannot open file.
FCE_PASV_ERROR          Cannot find PASV port.
FCE_NOT_COMPLETED       LIST/GET/PUT not completed.