TFTP5 is a non-visual object designed to help download and upload files from/to an FTP Server.

 

More generally it allows you to:

 

l    navigate within the Server sub-directories

l    list, create, delete, rename files and directories with commands similar to DOS commands

l    upload files or groups of files

l    download files or groups of files

l    check a log of your FTP activities

l    visualize the progress of your upload and download operations

l    use wildcards characters (* and ?) in most method arguments

 

TFTP5 is particularly useful if you need to automate repetitive tasks of updating files on a remote Server, or need to programmatically move files between your applications and a remote Server.

 

Note that TFTP5 uses the following freeware royalty free ActiveX component: ChilkatFTP which is delivered with APL+Win Objects™. Visit http://www.chilkatsoft.com if you want to know more about ChilkatFTP.

 

Instanciating TFTP5

 

Before you may use TFTP5, you must have properly installed APL+Win Objects™. A proper installation of APL+Win Objects™ automatically registers the ChilkatFTP.dll component.

 

If you are just copying the OBJECTS6.w3 workspace to another computer and want to use TFTP5 there, you should manually register the ChilkatFTP DLL.

 

To do so, after having loaded the OBJECTS6.w3 workspace, you should register the ChilkatFTP DLL. Register the ChilkatFTP DLL as follows:

 

      'oo'Œwi'Register' 'c:\aplwin\objects\chilkatftp.dll'

 

where you should replace c:\aplwin\objects with the name of the directory where you have installed APL+Win Objects™.

 

To create an instance of TFTP5, use the following command:

 

      'ftp'Œwi'*Create' 'TFTP5'
ftp

 

Connecting to the FTP Server

 

You need 4 pieces of information to get connected to an FTP server:

 

l    a user name

l    a password

l    a host name

l    a port

 

You need that your user name and password be declared on the Server as a valid FTP user or you may connect with a User Name of 'Anonymous' and an empty password. Once connected, you, as an FTP User, have access to a subpart of the Server disk, starting at a given sub-directory associated with your user name.

 

Once these prerequisites are fulfilled, to connect to an FTP Server, use the Connect method:

 

Example:

 

      'ftp'Œwi'Connect' 'username' 'password' 'www.lescasse.com'
1

 

The Connect method returns 1 if you succeeded to get connected, 0 otherwise.

 

Note that I have replaced my real FTP user name by username and my password by password for security reasons. Be sure to not prefix the Connect method with a * since you would be calling the object native XConnect method which would break since it does not accept any argument.

 

It is very likely that you would like to avoid exposing your user name and password when connecting to an FTP Server. For this purpose, you might prefer to use the ConnectMe method.

 

The ConnectMe method assumes that you have written a User Command (or APL function) called CMDCONNECTME similar to the following one:

 

    ’ CMDCONNECTME A
[1]   Œwi'*xUserName' 'username'
[2]   Œwi'*xPassword' 'password'
[3]   Œwi'*xHostname' 'www.lescasse.com'
[4]   Œwi'*xPort'21
    ’

 

where you should replace 'username' by your FTP user name and 'password' by your FTP password.

 

Once you have saved such a CMDCONNECTME function in your User Command File with the following command:

 

      ]usave CMDCONNECTME

 

you may get connected to your FTP Server with the following simple command:

 

      'ftp'Œwi'ConnectMe'
1

 

which does not expose your user name and password. As for the Connect command the ConnectMe command returns 1 if the command succeeded, 0 otherwise.

 

If you don't have a user account on an FTP server you may try to get connected as an anonymous user. To do so, simply use a user name of anonymous and no password.

 

Example:

 

      'ftp'Œwi'Connect' 'anonymous' '' 'www.genweb.net'
1

 

As an anonymous user you are however generally limited to browsing and download capabilities.

 

Checking if you are connected to the FTP Server

 

At any time you may use the isconnected property to check if you are connected to the FTP Server. This property returns 1 if you are connected, 0 otherwise.

 

      'ftp'Œwi'isconnected'

0

 

Disconnecting from an FTP Server

 

Use the Close or Disconnect method to disconnect from an FTP Server (both methods are equivalent):

 

      'ftp'Œwi'Disconnect'

 

This method does not return any result.

 

Please note that you do not need to disconnect before you reconnect to another Server: however this is better practice.

 

Example:

 

      'ftp'Œwi'Connect' 'anonymous' '' 'www.genweb.net'
1
  
      'ftp'Œwi'dir'
 bin\ 0 0 0
 etc\ 0 0 0
 lib\ 0 0 0
 pub\ 0 0 0
  
      'ftp'Œwi'ConnectMe'
1
  
      'ftp'Œwi'dir'
 AdminScripts\ 0 0 0
 catalog.wci\  0 0 0
 ftproot\      0 0 0
 iissamples\   0 0 0
 mailroot\     0 0 0
 scripts\      0 0 0
 wwwroot\      0 0 0

 

Root Directory, Relative and Absolute File Names

 

As an FTP user you have access to a subpart of the Server directories starting at a given directory: this directory is called your FTP Root Directory.

 

You cannot see or reach any parent or sibling directory of your FTP Root Directory. In all the following examples, I'll be using one of my FTP accounts to my server. This account gives me access to the directory c:\inetpub on my server and to all of its subdirectories.

 

With most TFTP5 commands you may use relative or absolute files names. You may change directories on the remote server using the Chdir method. The remote directory you are in at a given time is called the current remote directory. Thus, just after having connected to an FTP Server, the current remote directory is the FTP Root Directory. In our examples it will therefore be: c:\inetpub

 

If I query what is the current remote directory using the Chdir method it will report it as being / because it is the Root of what I am allowed to see on the server.

 

      'ftp'Œwi'Chdir'
/

 

Let's assume there is a directory called: c:\inetpub\ftproot\ftp\temp on my server and a file named: c:\inetpub\ftproot\ftp\temp\picutil.w3

 

I can reach this file as follows:

 

      'ftp'Œwi'Dir' '/ftproot/ftp/temp/picutil.w3'
picutil.w3 710050 20020119 15500

 

or:

 

      'ftp'Œwi'Dir' 'ftproot/ftp/temp/picutil.w3'
picutil.w3 710050 20020119 15500

 

or move the current directory to the /ftproot/ftp and reach the file with a relative path starting from the /ftproot/ftp directory:

 

      'ftp'Œwi'Chdir' '/ftproot/ftp'
1
  
      'ftp'Œwi'Dir' 'temp/picutil.w3'
picutil.w3 710050 20020119 15500

 

Although the current directory is now /ftproot/ftp (i.e. c:\inetpub\ftproot\ftp) I could still reach the file with an absolute path name:

 

      'ftp'Œwi'Dir' '/ftproot/ftp/temp/picutil.w3'
picutil.w3 710050 20020119 15500

 

but no longer with:

 

      'ftp'Œwi'Dir' 'ftproot/ftp/temp/picutil.w3'
¯1

 

The Dir method returned ¯1 since I have specified a relative file name from /ftproot/ftp i.e. /ftproot/ftp/ftproot/ftp/temp/picutil.w3

 

If you do not feel comfortable changing remote directories and working with current directories and relative remote file names, it is advisable and safer to always use absolute file and directory names i.e. always start remote file names with a /. In our examples, this would mean always starting from the Root directory / (c:\inetpub).

 

Browsing Remote Directories

 

You can use the Dir and Chdir methods to list files in the FTP Server remote directories and to change the current remote directory.

 

Example:

 

      'ftp'Œwi'dir'
 AdminScripts\ 0 0 0
 catalog.wci\  0 0 0
 ftproot\      0 0 0
 iissamples\   0 0 0
 mailroot\     0 0 0
 scripts\      0 0 0
 wwwroot\      0 0 0
  
      'ftp'Œwi'Chdir'
/

 

This returns the current remote directory. Remember that your FTP user account already points to the directory to which you have access on the server (your FTP Root Directory). In our examples the FTP Root Directory is: C:\inetpub

 

      'ftp'Œwi'Chdir' 'ftproot'
1
  
      'ftp'Œwi'Chdir'
/ftproot

 

The above examples first move the current directory to /ftproot and then reports it. After the first command the current remote directory has become: c:\inetpub\ftproot

 

The Chdir method returns 1 if successful and 0 otherwise.

 

      'ftp'Œwi'Chdir' 'ftproot'
0

 

Chdir returns 0 since there is no ftproot subdirectory under /ftproot.

 

      'ftp'Œwi'Chdir' 'ftp/lescasse'
1

 

We are now positioned at: c:\inetpub\ftproot\ftp\lescasse

 

We could have achieved the same current remote directory change in one FTP command:

 

      'ftp'Œwi'Chdir' '/ftproot/ftp/lescasse'
1

 

If you do not start the Chdir method parameter with a /, then you are moving to a directory relative to the current remote directory. Example:

 

      'ftp'Œwi'Chdir'
/ftproot/ftp/lescasse
  
      'ftp'Œwi'Chdir'
/ftproot/ftp/lescasse
  
      'ftp'Œwi'Chdir' '..'
1
  
      'ftp'Œwi'Chdir'
/ftproot/ftp
  
      'ftp'Œwi'Chdir' 'lescasse'
1
  
      'ftp'Œwi'Chdir'
/ftproot/ftp/lescasse
  
      'ftp'Œwi'Chdir' '../mai'
1
  
      'ftp'Œwi'Chdir'
/ftproot/ftp/mai
  
      'ftp'Œwi'Chdir' '../lescasse'
1

 

At any time you can use the Dir method to list existing files and sub-directories in the current remote directory:

 

      'ftp'Œwi'Dir'
 disk3.zip      1024012 19980122 0
 docwin35.zip    331144 19990411 0
 MAPI.w3          66278 20020127 0
 objects.zip    3449114 20000410 0
 objects11.zip  3367039 20000123 0
 objects25.exe  3843383 20020202 0
 objects25p.exe 3870606 20020202 0
 objectsp.exe   3571307 20000409 0
 objectsp11.exe 3415483 20000123 0
 Office.w3        13730 20011207 0
 PARAMS.w3        12814 20020219 0
 patrick.zip      42038 19990518 0
 PICUTIL.w3       99870 20020602 0
 playmidi.zip     29079 19980122 0
 printf.zip      185205 20011221 0
 resnames.w3      14846 19980122 0
 RESUTIL.w3      258266 20020602 0
 schannel.dll    113424 19980513 0
 STPROC.w3        24974 20020106 0
 wBackup.exe    2821354 20020128 0

 

The 3 numeric columns reported by Dir are:

 

l    file size

l    file date

l    file time (sometimes 0)

 

Note that these columns always contain 0's for files which represent subdirectories.

 

The Dir command is similar to the DOS Dir command and accepts an argument with wildcard characters to select only certain files:

 

      'ftp'Œwi'Dir' '*.exe'
 objects25.exe  3843383 20020202 0
 objects25p.exe 3870606 20020202 0
 objectsp.exe   3571307 20000409 0
 objectsp11.exe 3415483 20000123 0
 wBackup.exe    2821354 20020128 0
  
      'ftp'Œwi'Dir' 'obj??????.*'
 objects11.zip 3367039 20000123 0
 objects25.exe 3843383 20020202 0

 

Creating Remote Directories

 

To create a directory on the FTP Server, use the Mkdir method.

 

      'ftp'Œwi'Chdir' '/ftproot/ftp'
1
  
      'ftp'Œwi'Chdir'
/ftproot/ftp
  
      'ftp'Œwi'Mkdir' 'temp'
1
  
      'ftp'Œwi'Dir'
 apl2000\   0 0 0
 aplbook\   0 0 0
 causeway\  0 0 0
 eurowin\   0 0 0
 forefront\ 0 0 0
 incoming\  0 0 0
 lescasse\  0 0 0
 mai\       0 0 0
 temp\      0 0 0
 wise\      0 0 0

 

In the above example we have created the following remote directory: c:\inetpub\ftproot\ftp\temp

 

Note that we have specified a directory (temp) relative to the current remote directory which was: c:\inetpub\ftproot\ftp

 

We could as well have used an absolute path starting at the FTP Root Directory:

 

      'ftp'Œwi'Mkdir' '/ftproot/ftp/temp'

 

Renaming Remote Files

 

To rename remote files, use the Ren method. You may not rename more than one file at a time (you cannot use wildcard characters with this method). The Ren 1st argument is the old file name and its 2nd argument is the new file name. You may use relative and/or absolute file names for both of the arguments.

 

Example:

 

      'ftp'Œwi'Chdir' '/ftproot/ftp'
  
      'ftp'Œwi'Ren' '/ftproot/ftp/temp/picutil.w3' 'temp/picut.w3'

 

This example renames the /ftproot/ftp/temp/picutil.w3 file to /ftproot/ftp/temp/picut.w3. Note that we have used an absolute file name for the 1st argument and a relative file name for the 2nd argument.

 

Deleting Remote Files

 

Deleting remote files is done by using the Del method with or without wildcard characters (* and ?) much as you would do it under DOS. The result is the number of files which have been deleted.

 

Examples:

 

      'ftp'Œwi'Del' '/ftproot/ftp/temp/picutil.w3'
1

 

This first example removed one file (picutil.w3) in the following remote directory: c:\inetpub\ftproot\ftp\temp

 

      'ftp'Œwi'Chdir' '/ftproot/ftp/temp'
1
  
      'ftp'Œwi'Dir'
 Form1.frm     5680 20020119 3700
 Form1.frx       12 20020119 3700
 Project1.vbp   704 20020119 3700
 Project1.vbw    49 20020119 3700
 ZlibTool.ocx 53760 20020119 3700
  
      'ftp'Œwi'Del' 'Form*.*'
2

 

This second example removed 2 files (Form1.frm and Form1.frx) in the following remote directory: c:\inetpub\ftproot\ftp\temp.

 

Note that it is recommended to always use absolute path names when removing files. This would prevent you from erasing files from the wrong directory.

 

      'ftp'Œwi'Chdir' '/ftproot/ftp'
1
  
      'ftp'Œwi'Dir' 'temp'
 Project1.vbp   704 20020119 3700
 Project1.vbw    49 20020119 3700
 ZlibTool.ocx 53760 20020119 3700
  
      'ftp'Œwi'Del' 'temp/*.*'
3

 

This third example erased all remaining files (Project1.vbp, Project1.vbw and ZlibTool.ocx) in the following remote directory: c:\inetpub\ftproot\ftp\temp.

 

Deleting Remote Directories

 

To delete remote directories, use the Rmdir method. You cannot remove a directory if it still contains files: in that case first erase its files using the Del method and then use Rmdir to remove the directory.

 

Example:

 

      'ftp'Œwi'Del' '/ftproot/ftp/temp/*.*'
6
  
      'ftp'Œwi'Rmdir' '/ftproot/ftp/temp'
1

 

You can use relative or absolute path naming in the Rmdir argument.

 

Uploading Files to the FTP Server

 

Use the Upload method to upload one or more files to the FTP server:

 

      'ftp'Œwi'Upload' 'c:\temp\picutil.w3' '/ftproot/ftp/temp/picutil.w3'
1

 

The Upload 1st argument must be the local file name and the 2nd argument the remote file name. For the remote file name you may use either relative or absolute path names. The result of the Upload method is the number of file uploaded or ¯1 if the upload failed. By default, the Upload progress percentage is displayed in the APL session.

 

If you have used the handler property to define a global handler function for the TFTP5 object, then the progress percentage is not displayed in the APL session but you can use the onXPutProgress event to display the progress percentage (received in Œwarg) on a progress bar, for example.

 

Example:

 

      'ftp'Œwi'handler' 'TFTP5_Handlers'
  
   ’ TFTP5_Handlers;Z
[1]   …–(Œwi'*name'),'_',Œwevent
[2]   ftp_XPutProgress:
[3]      :if 0=½'ftppg'Œwi'*self'
[4]          Z„'ftppg'Œwi'*Create' 'TForm'('*size'65 300)('*border'16 512)
[5]          Z„'ftppg'Œwi'*caption'(' ','ftppg'Œwi'apptitle')
[6]          Z„'ftppg'Œwi'*.lpg1.Create' 'TLabel'('wherelc'   '>')
[7]          Z„'ftppg'Œwi'*.lpg2.Create' 'TLabel'('wherelc' '>' '=''>'¯2)
[8]          Z„'ftppg'Œwi'*.pgftp.Create' 'TProgress'('wherelc' '>' '=''>')
[9]          Z„'pgftp'Œwi'*Set'('fluid'1)('showpct'(255 255 255)(0 0 255))
[10]         'lpg1'Getso'Uploading: ',Œwi'*‘‘‘local'
[11]         'lpg2'Getso'To: ',(Œwi'*‘‘‘remote'),'...'
[12]         Z„'ftppg'Œwi'Show'
[13]     :end
[14]     :if Œwarg=100 ª 'lpg1' 'lpg2'Gets¨'Done!' '' ª :end
[15]     'pgftp'Gets Œwarg
[16]     :return
[17]  ftp_XGetProgress:
[18]     :if 0=½'ftppg'Œwi'*self'
[19]         Z„'ftppg'Œwi'*Create' 'TForm'('*size'65 300)('*border'16 512)
[20]         Z„'ftppg'Œwi'*caption'(' ','ftppg'Œwi'apptitle')
[21]         Z„'ftppg'Œwi'*.lpg1.Create' 'TLabel'('wherelc'   '>')
[22]         Z„'ftppg'Œwi'*.lpg2.Create' 'TLabel'('wherelc' '>' '=''>'¯2)
[23]         Z„'ftppg'Œwi'*.pgftp.Create' 'TProgress'('wherelc' '>' '=''>')
[24]         Z„'pgftp'Œwi'*Set'('fluid'1)('showpct'(255 255 255)(0 0 255))
[25]         'lpg1'Getso'Downloading: ',Œwi'*‘‘‘remote'
[26]         'lpg2'Getso'To: ',(Œwi'*‘‘‘local'),'...'
[27]         Z„'ftppg'Œwi'Show'
[28]     :end
[29]     :if Œwarg=100 ª 'lpg1' 'lpg2'Gets¨'Done!' '' ª :end
[30]     'pgftp'Gets Œwarg
[31]     :return
    ’
  
      'ftp'Œwi'Upload' 'c:\temp\picutil.w3' '/ftproot/ftp/temp/picutil.w3'
1

 

If you want to upload more than one file at a time you may use wildcard characters (* and ?) in the first Upload argument, but in this case the 2nd argument must be a remote file directory (not a file name).

 

Example:

 

      'ftp'Œwi'Upload' 'c:\temp\zipocx\*.*' '/ftproot/ftp/temp'
5

 

If the upload operation is successful the Upload method returns the number of uploaded files. If it fails, it returns ¯1.

 

Downloading files from the FTP Server

 

Downloading files from the FTP Server is very similar to the uploading operation described above. Invoke the Download method to get files from the server. You may either specify one remote file name (1st argument) to download to a local file name (2nd argument) or you may use wildcard characters (* and ?) to download a group of files (1st argument) to a local directory (2nd argument).

 

Example:

 

      'ftp'Œwi'Download' '/ftproot/ftp/temp/picutil.w3' 'c:\temp\picutil.w3'
1

 

Just like the Upload method, the Download method returns the number of downloaded files if the operation was successful or ¯1 if it failed. By default the progress percentage is displayed in the APL session. If you have defined a handler property for the TFTP5 object, the progress percentage is not displayed in the APL session and you may use the onXGetProgress event to display it on a form, for example in a progress bar. Œwarg contains the progress percentage.

 

You may download more than one files to a local directory by using wildcard characters.

 

Example:

 

      'ftp'Œwi'download' '/ftproot/ftp/temp/*.*' 'c:\temp\zipocx'
6

 

Remote Directory Content in XML Format

 

You may obtain a list of the files and directories contained in the current remote directory in XML format by using the XmlDir method.

 

      'ftp'Œwi'Chdir' '/wwwroot/classes/cfgraphs'
1
  
      'ftp'Œwi'Dir'
 Allaire\                  0        0 0
 areachart.class        9320 19981223 0
 barchart.class         8744 19981223 0
 item.class              733 19981223 0
 linechart.class        9368 19981223 0
 multibarchart.class    9311 19981223 0
 multibarchart3d.class 11251 19981223 0
 piechart.class         7787 19981223 0
  
 

      'ftp'Œwi'XmlDir'
<remoteDir>?
  <dir>Allaire</dir>
  <file>
    <name>areachart.class</name>
    <size>9320</size>
    <lastModTime m="12" d="23" y="1998" hh="0" mm="0" ss="0" />
  </file>
  <file>
    <name>barchart.class</name>
    <size>8744</size>
    <lastModTime m="12" d="23" y="1998" hh="0" mm="0" ss="0" />
  </file>
  <file>
    <name>item.class</name>
    <size>733</size>
    <lastModTime m="12" d="23" y="1998" hh="0" mm="0" ss="0" />
  </file>
  <file>
    <name>linechart.class</name>
    <size>9368</size>
    <lastModTime m="12" d="23" y="1998" hh="0" mm="0" ss="0" />
  </file>
  <file>
    <name>multibarchart.class</name>
    <size>9311</size>
    <lastModTime m="12" d="23" y="1998" hh="0" mm="0" ss="0" />
  </file>
  <file>
    <name>multibarchart3d.class</name>
    <size>11251</size>
    <lastModTime m="12" d="23" y="1998" hh="0" mm="0" ss="0" />
  </file>
  <file>
    <name>piechart.class</name>
    <size>7787</size>
    <lastModTime m="12" d="23" y="1998" hh="0" mm="0" ss="0" />
  </file>
</remoteDir>

 

FTP Activity Log

 

You may get a complete log of all your FTP commands including errors, since your last FTP connection by using the XmlLog method.

 

Example:

 

      'ftp'Œwi'XmlLog'
<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<ChilkatLog>
<CreateRemoteDir>
    <error>FTP Create Remote Dir failed</error>
    <fail_reason></fail_reason>
</CreateRemoteDir>
<PutFile>
    <error>PUT failed; cannot open remote file</error>
    <localFile>/ftproot/ftp/temp/picutil.w3</localFile>
    <failReason></failReason>
</PutFile>
<MPutFiles>
    <fileCount>5</fileCount>
    <totalByteCount>60205</totalByteCount>
    <filename>c:\temp\zipocx\Form1.frm</filename>
    <filename>c:\temp\zipocx\Form1.frx</filename>
    <filename>c:\temp\zipocx\Project1.vbp</filename>
    <filename>c:\temp\zipocx\Project1.vbw</filename>
    <filename>c:\temp\zipocx\ZlibTool.ocx</filename>
    <elapsedTimeInSeconds>5</elapsedTimeInSeconds>
</MPutFiles>
<GetFile>
    <error>FTP GET failed - cannot open remote file</error>
    <fail_reason></fail_reason>
</GetFile>
<MGetFiles>
    <pattern>/ftproot/ftp/temp/*.*</pattern>
    <localDir>c:\temp\zipocx</localDir>
    <fileCount>6</fileCount>
    <totalByteCount>770255</totalByteCount>
    <filename>Form1.frm</filename>
    <filename>Form1.frx</filename>
    <filename>picutil.w3</filename>
    <filename>Project1.vbp</filename>
    <filename>Project1.vbw</filename>
    <filename>ZlibTool.ocx</filename>
    <elapsedTimeInSeconds>17</elapsedTimeInSeconds>
</MGetFiles>
<RemoveRemoteDir>
    <error>FTP Remove Remote Dir failed</error>
    <fail_reason></fail_reason>
</RemoveRemoteDir>
<ChangeRemoteDir>
    <error>FTP Change Remote Dir failed</error>
    <fail_reason></fail_reason>
</ChangeRemoteDir>
<ChangeRemoteDir>
    <error>FTP Change Remote Dir failed</error>
    <fail_reason>The parameter is incorrect.</fail_reason>
</ChangeRemoteDir>
<ChangeRemoteDir>
    <error>FTP Change Remote Dir failed</error>
    <fail_reason>The parameter is incorrect.</fail_reason>
</ChangeRemoteDir>
<DeleteMatching>
    <pattern>Form*.*</pattern>
    <fileCount>2</fileCount>
    <filename>Form1.frm</filename>
    <filename>Form1.frx</filename>
    <elapsedTimeInSeconds>0</elapsedTimeInSeconds>
</DeleteMatching>
<DeleteMatching>
    <pattern>*.*</pattern>
    <fileCount>3</fileCount>
    <filename>Project1.vbp</filename>
    <filename>Project1.vbw</filename>
    <filename>ZlibTool.ocx</filename>
    <elapsedTimeInSeconds>0</elapsedTimeInSeconds>
</DeleteMatching>
<SaveXmlLog>
</SaveXmlLog>
</ChilkatLog>