<!-- Generated by TechWriter Professional 5.06 (02-Jul-99) -->
<HEAD><TITLE>!FTPc User Manual</TITLE></HEAD>
<BODY TEXT="#000000" BGCOLOR="#F0F0E0">
<H1 ALIGN=CENTER>!FTPc</H1>
<P>
!FTPc is an internet <A HREF="#ftp">ftp</A> client for Risc OS. It is a program which enables you to <A HREF="#upload">upload</A> and <A HREF="#download">download</A> files to and from your <A HREF="#webspace">webspace</A> and download files from the numerous ftp <A HREF="#host">hosts</A> on the net.
<LI><B><I><A HREF="#host">Host</A></I></B> is the name of an ftp site (e.g. <I>ftp.acorn.co.uk<B>) </B></I>you wish to connect to. If you have <A HREF="#webspace">webspace</A> this would be the address of your webspace which for freeserve is <I>uploads.webspace.freeserve.net.</I> If the host requires a different port to than the default one ftp to then it should be added to the end of the host name like this <I>ftp.acorn.co.uk:1234</I> where 1234 is the port number - note the semi colon. It is unusual to use a different port number to the default.
<LI><B><I>Path</I></B> is the directory you want to go to after connecting. A / is used to separate the directories e.g. <I>/pub/acorn/</I> - Omiting the final / will result in the final object being highlighted. e.g <I>/pub/acorn/file</I> will change the directory to <I>/pub/acorn</I> and highlight <I>file.</I>
<LI><B><I>User</I></B> is your user name. If you don't have a user name leave it blank and <I>anonymous</I> will be used. This may give you access to download files from certain sites.
<LI><B><I>Password</I></B> where you enter your password. If you have set the user to <I>anonymous</I> (or left it blank) then you should enter your email address here. Leaving the password blank results in a default email address being used which should work ok.
<LI><B><I>Account</I></B> is probably only used for commercial sites so unless you know otherwise leave it blank.
<LI><B><I>Proxy - Type </I></B>is the type of proxy server you are using there are 4 possible settings:
<UL>
<LI><I>0 - None</I> : You are not using a proxy, or want to disable the default proxy for this connection.
<LI><I>1 - USER</I> : You are connected to a proxy which uses the USER command to connect to the Host you want to connect to.
<LI><I>2 - SITE </I>: You are connected to a proxy which uses the SITE command to connect to the Host you want to connect to.
<LI><I>3 - OPEN</I> : You are connected to a proxy which uses the SITE command to connect to the Host you want to connect to.
</UL>
<LI><B><I>Proxy -Default</I></B> sets the proxy to the default proxy
<LI><B><I>Proxy - Host</I></B> is the host name of your proxy server. If you need to specify a different port number just add :port to the end of the name eg ftp.demon.co.uk:1234
<LI><B><I>Proxy - User</I></B> is used if you need to login to the proxy otherwise leave blank.
<LI><B><I>Proxy - Password</I></B> is used if you need to login to the proxy otherwise leave blank.
<LI><B><I>Passive</I></B> makes FTPc use the PASV command when making data connection. see <A HREF="#Passive">Passive connections</A>
</UL>
<H4><A NAME="Using_the_filer">Using the filer</A></H4>
The filer is used in a similar way to a disc filer with drag and drop etc. however there are the following differences:
<UL>
<LI>Changing directories lists the new one in the same window, so to move objects to another directory highlight the files and enter the target directory in the <I>Move to</I> <A HREF="#dialogue_box">dialogue box</A>.
<LI><I>New Directory</I>, <I>Change Directory</I>, <I>Rename</I> and <I>Move to</I> dialogue boxes use the remote filing system syntax. i.e <I>dir1/dir2/dir3/file</I>, <I>file.txt</I>, <I>dir1/file.html</I>
When files/directories are <A HREF="#upload">uploaded</A> any <B>/</B> is changed to a <B>.</B> so <I>Ftp/zip</I> is changed to <I>Ftp.zip </I> and a hard space is changed to a space. Any directories that don't exist are automatically created.
<P>
You can stop the upload process with by selecting <I>Abort</I> in the main menu which will close the connection and reconnect to the same directory.
<A HREF="#download">Downloaded</A> files have any <B>.</B> changed to a <B>/</B> so <I>Ftp.zip</I> will become <I>Ftp/zip</I> and a space is changed to a hard space. Care must be taken as the file name will be truncated if the filing system where you drop the files does not support file names of that length. You can download with a different name via the <I>SaveAs</I> <A HREF="#dialogue_box">dialogue box</A>. The new file name uses normal Risc OS filing system naming system.
<H4><A NAME="Moving_around_the_host">Moving around the host</A></H4>
<P>
You can change directories by double clicking on a directory (<IMG SRC="Images/UserManual/Pic8.gif" ALT="" ALIGN=MIDDLE HEIGHT=18 WIDTH=18>) or entering the path in the change directory <A HREF="#dialogue_box">dialogue box</A> on the main menu. You should enter the path using the syntax of the host e.g. <I>archive/dir/dir1</I>. Double clicking on a link (<IMG SRC="Images/UserManual/Pic3.gif" ALT="" ALIGN=MIDDLE HEIGHT=18 WIDTH=18>) will change directories if it points to a directory otherwise it will pop up a <I>Saveas</I> dialogue box.
<P>
To move back click <I>Adjust</I> on the close icon,select <B><I>Open parent</I></B> from the main menu or double click on <IMG SRC="Images/UserManual/Pic5.gif" ALT="" ALIGN=MIDDLE HEIGHT=18 WIDTH=18> .
<P>
<B>Note:</B> Files which don't have extensions are marked type Data these <I>may</I> be typed automatically after downloading by inspection of the file.
<H4><A NAME="Managing_your_remote_disc_space">Managing your remote disc space</A></H4>
<P>
You can delete, rename, move filing system objects and create directories. When entering names in the <A HREF="#dialogue_box">dialogue boxes</A> they should be in the remote filing system syntax and not Risc OS filing system syntax, so if you want to rename <I>index.htm</I> to <I>anyfile.txt</I> you should write <I>anyfile.txt</I> in the <I>rename</I> dialogue box.
<P>
To move a group of files into a subdirectory of a directory you should select the files and enter <I>directory/subdirectory</I> in the <I>Move to</I> dialogue box.
<P>
Clicking on <I>Change Directory</I> refreshes the listing or changes the directory to / if the current directory no longer exists.
<P>
Note: The <I>SaveAs</I> dialogue box is the only one which requires Risc OS filing system syntax
<H4><A NAME="Logging_off">Logging off</A></H4>
<P>
Just close the filer window
<H4><A NAME="Newer">Newer</A></H4>
<P>
The <I>Newer</I> option on the <I>Option</I> menu allows you to specify the date from which files will be uploaded. eg If you set the date to when you last uploaded, only files created/modified after that date will be uploaded when a group of files/directories are dragged into the window
The option is set by selecting <I>Set</I> and removed by unticking <I>Newer</I> on the <I>Option</I> submenu. <I>Reset</I> changes the time to the current time.
<P>
Please note the time/date you set is your local time and this time is compared to the time stamp of the file on your computer. You may be connected to a computer in a different time zone in which case the time appearing in the FTPc window after uploading may not be what you expect.
<H4><A NAME="Status_log">Status log</A></H4>
<P>
When you log on to an ftp site a lot of servers send information which you may find useful. This option allows you to read this information. It is also useful for <A HREF="#Site_specific_commands">Site</A> commands which return information.
<P>
Selecting status log will load a list of previous commands and replies (as seen in the status bar at the bottom of the main window) into a text editor. Only the last 16kbytes of status information is recorded.
<P>
Lines starting with a 3digit number are messages sent by the server others are sent to the server by FTPc.
<H4><A NAME="Site_specific_commands">Site specific commands</A></H4>
<P>
The remote host <A HREF="#server">server</A> <I>may</I> have a set of commands available which are dependant on the site you are connected to. These include commands such as CHMOD on a unix server and SETTYPE on an acorn server. These are generally tools to manage your remote site. The details of which are beyond this document.
<P>
There are 3 ways to enter <I>Site</I> commands in FTPc. Enter it as if from a command line, apply a list of commands to a selection and apply a list of commands to each uploaded file/directory
<P>
<B>Note:</B>
<UL>
<LI>What commands, if any, are available are dependant on the remote host server and not this program.
<LI>You can see the information returned from commands such as HELP by selecting <I>Status log...</I> on the main menu
<LI>Some servers don't support SITE commands at all
</UL>
<H5>Applying general site commands</H5>
<P>
You can send a Site command by selecting <I>Site...</I> on the main menu, typing in your Site command and selecting <I>Do </I>or press <return>. The displayed directory is your current working directory.
<H5>Applying a Site command to the selection</H5>
<P>
On the <I>Selection</I> submenu is another <I>Site</I> entry. Following the arrow allows you to enter a list of Site commands which will be applied to each selection in turn. In the text if you:
<UL>
<LI>Start a command with -f it will only be applied to selected files
<LI>Start a command with -d it will only be applied to selected directories
<LI>Use %f in a command it will be replaced by the selected file or directory
<LI>Use %t in a command it will be replaced by the RISC OS file type of the selection as determined by the mimemap module. If %t is used it is only applied to files so -f is not needed.
<LI>Want more than 1 command to be applied just separate them with a comma.
</UL>
<P>
If you dont want the command applied recursively (ie applied to subdirectory contents) untick <I>Recurse</I>.
<P>
You can set the default text for this dialogue box on a site by site basis by adding
to a user menu entry. (The text in inverted commas is your list of commands)
<H5>Applying Site commands to all uploaded files/directories</H5>
<P>
The other place you can enter a <I>Site</I> command is on the <I>Options</I> submenu. This allows you to apply a series of site commands to all uploaded files/directories. You could, for example, set permissions or set the file type on all uploaded files /directories - remember that the available commands depend on the type of server you are connected to.
<P>
The text you enter is the same as for <I>applying a command to the selection</I> (see above) except that the RISC OS file type is determined by the file type of the uploaded file.
<P>
The <I>Options</I> submenu will show a tick against the <I>Site...</I> entry when it is set/active.
<P>
This option is also applied to directories created with <I>New Directory.</I>
<P>
You can set the default text for this dialogue box on a site by site basis by adding
<PRE>
site_on_upload = "chmod 644 %f,settype %f %d"
</PRE>
<P>
to a user menu entry. (The text in inverted commas is your list of commands). If this option is included in the menu entry, the <I>Site...</I> command on the <I>Options</I> submenu will be selected (ie the option will be active)
<H4><A NAME="Abort">Abort</A></H4>
<P>
The abort command on the main menu allows you to stop the current operation.
<P>
Aborting may take some time to take place. If you abort during downloading it may not happen until the download of the file is complete - this depends on the site connected to.
If a filer window is open but it is not connected the menu will show <I>Reconnect</I>. When selected an attempt will be made to reconnect to the same site and directory that the window was connected to before the connection failed. If it wasn't previously connected it will attempt to connect again using the connection details.
<P>
If the filer window is connected the menu will show <I>New Connection</I>. A new window will open and an attempt will be made to connect to the same host and directory as the original window.
<P>
<B>Note:</B> The two connections are not aware of each other so a change in one will not be reflected in the other. Selecting <I>Change directory</I> on the main menu will refresh a directories display if required.
<H4><A NAME="Resume">Resume</A></H4>
<P>
You can resume the transfer of a file if the server you are connected to supports it. To use this facility you
<UL>
<LI>Locate the file in the FTPc viewer window
<LI>Select resume on the filer menu
<LI>Locate that partially transfered file on your hard disk and drag it to the viewer window
<LI>Select the button will now show either <I>upload</I> or <I>download</I> depending on the direction of transfer. If the local file is larger than the remote file then it will be <I>upload</I> otherwise it will be <I>download</I>.
</UL>
<P>
If you altered the transfer type for the original transfer you will need to alter it again before selecting the <I>upload/download</I> button.
<P>
It is recommended that you do your transfers in <I>binary</I> mode as there are other issues with resuming in <I>ascii</I> mode which may cause problems.
<P>
If resume is supported you should be able to continue some time later (the next day for example) as long as the remote file hasn't changed in the meantime.
<H4><A NAME="User_menu">User menu</A></H4>
<P>
User menu's can be created in a text editor and the type set to <I>FTPc</I> (077)
<P>
The first line of the file should be Menu and the lines following describe the menu entries.
name="Open a download directory" value="$.downloads" type="file"
# multiline example note the ; on all but the last line
# of the entry (blank lines and comments are ignored)
name = "Colin's Web site";
value = "ftp://user:password@some.net.site/";
# set the default Site on Upload
site_on_upload = "settype %f %t";
site_selection = "chmod 644 %f";
line = "on"
# run a program
name="my program" value="$.some_program";
type="file"
</PRE>
<H5>Entries in detail</H5>
<UL>
<LI>The inverted commas in each options text entry are necessary
<LI>each entry consists of:
<UL>
<LI><I>name = "some text"</I> where <I>some text</I> is what you see on the menu
<LI><I>value = "some text"</I> where <I>some text</I> is the ftp <A HREF="#URL_section">URL</A> you connect to when you click on that menu entry.
<LI>The following options are also available
<UL>
<LI><I>line = "on" </I>which places a dotted line beneath that menu entry
<LI><I>type = "file"</I> which will treat the <I>value </I>text<I> </I>as a file object and will run that object when the menu entry is selected. or open a directory if <I>value</I> text is a directory name.
<LI><I>default = "true"</I> which sets the entry which will be selected if the iconbar icon is clicked with <I>Adjust.</I> This allows you to connect to your favourite ftp site by clicking adjust on the iconbar icon. (you could also have it open a directory for downloading)
<LI><I>site_on_upload = "list of site commands"</I> see <A HREF="#Site_specific_commands">Site Specific Commands</A>
<LI><I>site_selection = "list of site commands" </I>see <A HREF="#Site_specific_commands">Site Specific Commands</A>
</UL>
<LI>You can add a comment by starting the line with a # or |
<LI>Blank lines are ignored
<LI>You can use more than one line in an entry if you end all but the last line in an entry with a ;
</UL>
<LI>The default <I>Proxy Server</I> can be overridden by including <B>-proxy </B>at the end of the value (inside the inverted commas) - see <A HREF="#Proxies,_Gateways_and_Firewalls">Proxies, Gateways and firewalls</A>
</UL>
<H5>Changing the default user menu</H5>
<P>
You can change the default user menu by:
<UL>
<LI>Modifying <I>Default</I> inside the <I>!FTPc</I> directory. Take care about putting your passwords in this file because giving away a copy of the program will result in you giving away your passwords.
<LI>Creating a new menu file called <I>Default</I> and put it in <I><choices$dir>.FTPc</I> directory - <I>choices$dir</I> is <I>$.!Boot.Choices</I> if you are using the Acorn !Boot application
<LI>Creating a new menu file anywhere and double click on it - you can change the menu while the program is running.
</UL>
<H4><A NAME="URL_section">URL's</A></H4>
<P>
!FTPc supports Ants and Acorns <A HREF="#URL">URL</A> systems. This means that FTPc will be loaded and run if an ftp URL is clicked on in an application or when a <A HREF="#URI">URI</A> file containing a ftp URL is double clicked on.
<P>
The general form of the ftp URL is:
<P ALIGN=CENTER>
<I>ftp://user:password@host:port/path</I>
<P>
where user,password, port and path are optional.
<P>
The URL could be as simple as
<P ALIGN=CENTER>
<I>ftp://host</I>
<P>
when you would be logged in anonymously to the root directory of the host
<P>
If the URL was
<P ALIGN=CENTER>
<I>ftp://user@host</I>
<P>
then you would be prompted for the password. You will also be prompted for, a user if you miss that out but supply a password, and a host if you miss that out.
<P>
The first / in the path is ignored so
<P ALIGN=CENTER>
<I>ftp://user@host/dir1/dir2/</I>
<P>
specifies a relative path <I>dir1/dir2/</I> and
<P ALIGN=CENTER>
<I>ftp://user@host//dir1/dir2/</I>
<P>
specifies an absolute path <I>/dir1/dir2/.</I>
<P>
If the path ends in a / then the connection will be opened at the specified directory - if the directory is not found this defaults to the root directory.
<P>
If the path doesn't end in a / then the connection is opened at the directory specified up to the last / and the leaf name is highlighted in that directory if it is found.
<P>
Note: Path names are case sensitive.
<P>
<B>Writing URI files</B>
<P>
Write the URL in a text editor - eg <I>ftp://ftp.xemplar.co.uk/acorn/</I> - save it and set its file type to URI. For my web site I may write something like
which when double clicked on will prompt me for my password before connecting to my web site and changing the directory.
<P>
<B>Using URL's with !Browse</B>
<P>
If running a URI file results in !Browse being run, this is to do with the order in which !FTPc and !Browse are seen - shouldn't be a problem in the same directory
Setting passive mode makes FTPc use the PASV command for data connections. This should only be required on certain sites or if you are masquerading through a firewall and the firewall isn't set up for non PASV ftp access. Some sites do not accept Passive connections. It does no harm to try connecting with this option set if the FTPc connection doesn't work with it unset.
<P>
You can set the passive mode by ticking <I>Passive</I> on the connection dialogue box or adding <I>-passive</I> to a URL in the user menu
<I>name="another web site" value="ftp://ftp.hensa.co.uk/pub/acorn/ -passive"</I>
<H4><A NAME="Proxies,_Gateways_and_Firewalls">Proxies, Gateways and Firewalls</A></H4>
<P>
This section covers access through Proxies, Gateways and Firewalls which are basically different terms for the same thing.
<P>
If you have a local network where access to the internet is through a proxy server you can access ftp hosts on the internet as follows (if the server allows it):
<P>
There are 3 types of proxy supported USER, OPEN and SITE these refer to the commands FTPc uses to access the host you want through the proxy server
<B><I></I></B>
<P>
The <I>USER</I> type of proxy equivalent to the type used in versions of FTPc prior to 1.20 (except now when the proxy is set the destination host details are entered as if you were not using the proxy).
<I></I>
<P>
You may need a username/password for the proxy in which case I'd expect your Network administrator to tell you. He may also tell you which of the proxy types to use otherwise its a question if trial and error.
<I></I>
<P>
If you always use a proxy you can modify the file !FTPc.!Setup so that
<P>
<I>ProxyServer</I> is set to your proxy address. The format of the ProxyServer option is
connects to <I>ftp.demon.co.uk</I> through the proxy <I>local.proxy.name </I>which is a type 1 (USER) proxy
<H4><A NAME="Fine_Tuning">Fine Tuning</A></H4>
<P>
If you are using FTPc on a Network you may be able to improve the speed slightly by setting the variables <I>FileBufferSize</I> and <I>ExtraPollEvery</I> in !FTPc.!Setup. Note this file can go in Choices:FTPc directory if you prefer - as can your default menu.
<P>
Some Harddiscs are slow when transfering small amounts of data but speed up considerably when transfering large amounts of data. This can also be apparent if you have ADFSBuffers set to 0. <I>FileBufferSize</I> allows you to set the size of the file buffer (in Kb) used by FTPc. eg
<P ALIGN=CENTER>
<I>FileBufferSize: 256</I>
<P>
<B>Note: </B>a file buffer is created for every connection so a large buffer size may take up a lot of memory
<P>
The other speed bottleneck is the frequency at which the program multitasks. This isn't a problem for modem users as multitasking will occur whilst waiting for data but on networks you seldom wait for data so you need to specify the amount of data that will be transferred before you multitask. This is done by setting <I>ExtraPollEvery</I> which specified the number of Kb to be transfered before the program multitasks. eg
<P ALIGN=CENTER>
<I>ExtraPollEvery: 256</I>
<I></I>
<P>
If you set this too high the program will hardly multitask
<H4><A NAME="Problems">Problems</A></H4>
<P>
<B>URI's don't work</B>
<P>
I you don't have Ant or Acorn internet software you'll need Acorns URI module which can be found at <A HREF="http://www.acorn.com/browser/uri/URI.arc">http://www.acorn.com/browser/uri/URI.arc</A> and should be put in System:Modules.Network
<P>
<B>Site created on hard disc doesn't work when downloaded</B>
<P>
Remember the remote site is case sensitive.
<P>
Don't use spaces in filenames - FTPc will change <alt><space> in a file name to spaces when uploading so your links in HTML should have spaces in them. However when testing these files on your hard disc Browse will not do this conversion. It is best to avoid spaces they were only really added for downloading.
<H4><A NAME="Finer_points_of_Ftp">Finer points of Ftp</A></H4>
<UL>
<LI>Due to differences in filing systems it should be noted that <A HREF="#upload">uploading</A> a file loses its Risc OS file type. When <A HREF="#download">downloading</A> !FTPc will attempt to set the file type from the .<I>ext</I> of the remote file name if the mimemap module is present. Failing this it will attempt to recognise <I>arc</I>, <I>zip</I> and <I>text</I> files from their contents otherwise it sets a <I>data</I> type. It is recommended that all files put on the remote host have a .<I>ext</I> which means ending them in <I>/ext</I> in the Risc OS filer or changing the names once on the remote host.
<LI>Ftp allows uploading files in either a Binary or ASCII format. ASCII format modifies the files on transfer both at this end and at the other end of the connection. Unfortunately no information is stored with the file to say what format it was saved with. I would recommend you transfer files in Binary and this is the only way to guarantee the correct transfer of non text files but !FTPc allows you to set the <I>Transfer type</I> to either Binary, Ascii or Auto where:
<UL>
<LI><I>Binary</I> transfers the files bit for bit
<LI><I>Ascii</I> sends files in a standard text format and when loading translates them back to the Risc OS text format. This transfer method is only of use with text files.
<LI><I>Auto</I> this method will use .<I>ext</I> of the file to detemine the transfer type. (requires mimemap module)
<TD>Transfer files from the remote host to your computer.
<TR><TD><I><A NAME="fso">filing system objects</A></I>
<TD>These are the files, directories or links which can be created on filing systems although the ftp proces does not allow for the creation of links.
<TR><TD><I><A NAME="ftp">ftp</A></I>
<TD>File transfer protocol - procedure by which two computers can communicate with the intention of transferring files
<TR><TD><I><A NAME="host">host</A></I>
<TD>Another name for a computer
<TR><TD><I><A NAME="link">link</A></I>
<TD>A marker in a directory which points to a file or another directory. This is a feature of the remote filing system and not available on RiscOS.
<TR><TD><I>proxy</I>
<TD>Server through which all requests to access remote sites go.
<TR><TD><I>server</I>
<TD>Program running on remote host which <I>serves</I> you your files and responds to your commands
<TR><TD><I>upload</I>
<TD>Transfer files from your computer to the remote host.
<TR><TD><I><A NAME="URL">URL</A></I>
<TD>Uniform Resource Locator - a description of where and how to find a resource on the net
<TR><TD><I><A NAME="URI">URI</A></I>
<TD>Uniform Resource Identifier - a description of a resource on the net. To most people it is the same as a URL but it is the file not the location
<TR><TD><I><A NAME="webspace">webspace</A></I>
<TD>Disc space on a host which is permanently connected to the Internet. If you have a dialup account this would be allocated to you by your service provider.
