FTP Uploads with 4D
By Steve Hussey CEO Alto Stratus LLC
Technical Note 99-54
Technical Notes for Technical Notes for 99-12-December 1999
Introduction
This technical note shows you how to use the FTP commands to build a ftp client that will allow a user to connect to a FTP site and then upload files to the site – all from within a 4D application. The included sample application is cross-platform.
Note: you will need access to a suitable FTP site with access privileges that will allow you to create directories/upload files. The code will need to be adapted slightly to specify the site details before use.
What is FTP?
The File Transfer Protocol ( FTP) is a series of protocols that originated in 1971. It is the primary means of transferring documents and applications from one computer to another on the internet. The File Transfer Protocol provides a means for different computer systems to exchange files. For example, an FTP site can be hosted on Unix, MacOS, or Windows. Client applications can also run on a variety of platforms, and can log onto any FTP server in order to upload or download text or binary files irrespective of whether the FTP server and client are based on the same operating system.
Requirements
4D v6.0.x with PDM's Internet Toolkit or 4D v6.5 with the Internet Commands plug-in installed. The 4D v6.5 installer installs the Internet Commands in the new universal 4DX folder.
An internet connection: the connection can be a dial up connection via modem or a full time connection. If you are using a dial-up ( modem) connection on Mac OS you can force a connection to open. If you are using a dial-up ( modem) connection on Windows you will need to have an open connection before connecting to a FTP site.
The 4D installer installs the Internet Commands plug-in inside the new universal plug-in folder:
| On Mac OS this is in the System:Preferences:ACI:Mac4DX folder. |
| On Windows this is in the C:\Windows\ACI\Win4DX folder. |
Plug-ins installed in the new universal folder are automatically accessible to all copies of 4D v6.5/4D Server v6.5 installed on that computer. They do not appear in the 'normal' Mac4DX/Win4DX folders.
File Paths
When specifying pathnames in FTP commands, you must treat file locations on the FTP site as Unix directories, even if you know the FTP host to be Mac OS or Windows running FTP server software. Whatever the platform, the FTP server software will internally convert the Unix pathname to the format it requires to serve its documents.
However the paths to folders/directories and files on your own computer (the source) must follow the conventions of your platform.
Why Use 4D to FTP Files?
Since there are so many free or low cost FTP clients available for both Mac OS and Windows why should anyone bother writing a FTP client using 4D?
| Perhaps you wish to build your own custom interface. |
| You may need to download files to store in a 4D database. |
| You could monitor a site for new files on a timed basis. |
| Perhaps you have multiple files to upload to multiple sites. |
| You may wish to implement deferred transfer: upload files at night or at the week-end when connection charges are lower or more bandwidth is available. |
| For security purposes you may wish to control access to outgoing file transfer. Using passwords you could control uploading of files by user name, department, group or destination. |
| If you need to access sites that have heavy traffic, you may be refused connections: a 4D solution can be programmed to try again at periodic intervals. |
The Process
Uploading files consists of a few simple steps:
| Connect to the site – this usually requires a user name (often 'anonymous') and a password (frequently your email address). |
| Navigate to a specific directory or create one. |
| Upload file[s]. |
| Navigate to other directories if required. |
| Disconnect to free up a connection for other users. |
The Code
The code starts with the TRAN_Upload method:
`<< PM: TRAN_Upload
`<<
`<< Called By:
`<< Calls:
`<< Created: 12/11/99 Steve Hussey, Alto Stratus LLC shush@harborside.com
`<< Modified:
`<<<<< Declarations >>>>>
Declare variables and arrays:
C_TEXT ($FTP_Site; $FTP_Name; $FTP_Password)
ARRAY TEXT (names; 0)
ARRAY LONGINT (sizes; 0)
ARRAY INTEGER (kinds; 0)
ARRAY DATE (modDates; 0)
ARRAY BOOLEAN (FTP_OK; 0)
Request the site details from the user:
$FTP_Site := Request ("FTP site (e.g., ftp.site.com)?") `Enter the path name to the ftp site and subfolders
If (ok=1)
$FTP_Name := Request ("User Logon Name (or anonymous?"; "anonymous")
If (ok=1)
$FTP_Password := Request ("Password (or email address for anonymous")
If (ok=1)
`The test for (ok=1) allows the user to cancel at any stage.
`The next section of code determines the platform:
PLATFORM PROPERTIES ($Platform) ` Mac OS or Win?
Case of
: ($Platform<=2) `<< Mac OS
$Delimiter := ":"
: ($Platform>2) `<< Windows
$Delimiter := "/"
End case
The delimiter character is set according to the source platform. This will be used for specifying the path to the uploads and uploads sent folders. The Uploads folder stores the files you want uploaded. After a succesful upload each file is moved to the Uploads Sent folder.
$Struct:= Structure file `<< Find the path to the folder that contains this application $Path:= HFS_Extract_File_Name ($Struct; "Path")
HFS_Extract_File_Name extracts either the path name or file name for the specified path:
`<< PM: UTIL_Extract_File_Name `<< Created : 7/29/99 for ACI US by Steve Hussey, `<< Alto Stratus LLC shush@harborside.com `<< Modified : `<< Purpose : `<< Assumptions: `$1 = Path + File Name `$2 = "Path" or "File" $OriginalPath := $1 $Path := $1 $Result := $2 PLATFORM PROPERTIES ($Platform) If ($Platform<3) $PathDelimiter := ":" ` Mac OS Else $PathDelimiter := "\" ` Windows End if $Length := Length ($Path) While (Position ($PathDelimiter; $Path[[$Length]])#1) $Length := $Length-1 $Path := Substring ($Path; 1; $Length) End while $File := Substring ($OriginalPath; (Length ($Path)+1); Length ($OriginalPath)) Case of : ($Result="Path") $0 := $Path : ($Result="File") $0 := $File End case
Next the path to the application folder is built, and from that the path to the Uploads folder:
$Struct := Structure file `<< Find the path to the folder that contains this application $Path := HFS_Extract_File_Name ($Struct; "Path") $FullPath := $Path+"Uploads"
On Mac OS you need to ensure that the TCP drivers are loaded; for Windows there is no way to do this from 4D. For Windows users you may wish to display an alert allowing the user to open a connection:
$Err := FTP_Init `<< Load Mac TCP drivers - required for Mac OS only
FTP_Init does this:
`<< PM: FTP_Init
`<<
`<< Called By:
`<< Calls:
`<< Created : 7/01/99 for ACI US by Steve Hussey,
`<< Alto Stratus LLC shush@harborside.com
`<< Modified :
`<< Purpose :
`<< Assumptions:
`<<<<< Declarations >>>>>
$0 := 0
`<<<<< Start >>>>>
PLATFORM PROPERTIES ($Platform)
Case of
: ($Platform<=2) `<< Mac OS
$0 := IT_MacTCPInit
: ($Platform>2)
`<< TCP connection needs to be open on Windows
text_Alert_Msg := "Make sure that you have an open TCP/PPP connection to the internet."
WND_Cntr (240; 160; 5; "Alert"; "WND_Cls")
DIALOG ([Application_Preference]; "Alert_dlg")
CLOSE WINDOW
If (ok=1)
$0 := 0
Else
$0 := 1
End if
End case
If no error was generated, then the connection is established:
If ($Err=0) `<< Continue if no error
$Err := FTP_Connect ($FTP_Site; $FTP_Name; $FTP_Password)
The FTP_Connect code:
`<< PM: FTP_Connect `<< `<< Created: 12/11/99 Steve Hussey, Alto Stratus LLC shush@harborside.com `<< Modified: `<< Purpose: C_TEXT ($WelcomeText; $1; $2; $3; $FTP_Site; $FTP_Name; $FTP_Password) `<<<<< Constants >>>>> $FTP_Site := $1 $FTP_Name := $2 $FTP_Password := $3 $0 := FTP_Login ($FTP_Site; $FTP_Name; $FTP_Password; FTP_ID; $WelcomeText) `<< Log on to the ftp site `FTP_ID contains the ftp session ID which will be used later `Any welcome message is returned into the variable $WelcomeText
FTP_ID now contains the ftp session reference number.
Now you can create a new directory, if required:
If ($Err=0)
$TargetPath := "//Test_Upload/" `Modify as required
$Err := FTP_MakeDir (FTP_ID; $TargetPath)
Note: you can only create a new directory if your user name and password privileges allow it. This operation can fail for many reasons. The most obvious are:
| You do not have user privileges for creating new directories. |
| The destination disk is full ort write protected. |
| An OS error on the detsination drive. |
The next step is to create a list of the files in the Uploads folder: these are the files that need to be uploaded:
DOCUMENT LIST ($FullPath; arytext_Documents)
The array arytext_Documents contains a list of the files to be uploaded: its size is (obviously) the number of files to upload. This array can be looped through, one element at a time, and a full path to the file built:
For ($File; 1; Size of array (arytext_Documents))
Build the path: remember that the delimiter is platform specific:
$DocPath := $Path+"Uploads"+$Delimiter+arytext_Documents{$File}
The target path delimiter is always Unix format:
$DestPath := $TargetPath+"/"+arytext_Documents{$File} `Unix format delimiters!
Upload the file:
$Err := FTP_Send (FTP_ID; $DocPath; $DestPath; 1) `<< Display progress dialog
| FTP_ID is the session ID. |
| $DocPath is the source (platofrm specific) path. |
| $DestPath is the target path (Unix format). |
| 1 indicates that a progress dialog should be displayed. |
The files can either be deleted or moved to another location after a successful upload:
If ($err=0) `<< 'Delete' uploaded files by moving them to the 'sent' folder $MovePath := $Path+"Uploads Sent"+$Delimiter MOVE DOCUMENT ($DocPath; $MovePath) End if End for
After finishing it is 'good manners' (or good Netiquette) to disconnect and free up the connection for other users.
$Err := FTP_Logout (ftp_ID)
The remaining code:
Else
ALERT ("Error connecting to ftp site.")
End if
Else
ALERT ("Error initializing TCP/PPP drivers.")
End if
End if
End if
End if
Closing thoughts
All ftp sites use Unix format delimiters
| Target paths always Unix style. |
| Your computer uses platform specific formats. (This can be a little confusing at times.) |
Anonymous connections are often limited
FTP servers often limit the number of connections to avoid the server crashing under excessive load. Anonymous connections in particular are often very restricted. This means that even though you should be able to connect to the site as you have the user logon name and password for anonymous connection: your connection attempt may be refused.
You should check for this condition, and either inform the user, or wait for a period of time and then try again.
Connections can be slow
Even though you may have a T1 connection that does not mean that the ftp site can accept the data at your transmission speed. It may be slow due to an excessive number of connections, or it may be connected with a slower physical connection.
Connection can be terminated by host
An overloaded ftp host may drop connections unexpectedly. A connection that has started may not complete.
Give feedback on progress to the user
You may wish to give the user more feedback.
Before Using The Sample Database
You will need access to a suitable ftp site with access privileges that will allow you to create directories/upload files. The code will need to be adapted slightly to specify the site details before use.
Any files you wish to upload should be placed in the uploads folder before running the application: alternatively you could adapt the code to allow the user to select folders/directories or files for uploading.