BCI NET 2

home *** CD-ROM | disk | FTP | other *** search

/ BCI NET 2 / BCI NET 2.iso / archives / networking / amitcp / ftpget1_1.lha / FTPGet1_1 / FTPGet.DOC < prev next >

Wrap

Text File | 1995-03-01 | 17.0 KB | 389 lines

FTPGet v1.1 Automatic FTP for AmiTCP © 1995 Simon Dainty -={ Dedicated to Katrina Finch - IRC: KaT }=- ====================================================================== Contents: FTPGet v1.1 ====================================================================== Introduction: What is...? 1.0 FTPGet: 2.0 Installation ............................................... 2.1 How to...? ................................................. 2.2 Problems, problems ......................................... 2.3 Legalities... damn: 3.0 ...Forty Two: 4.0 A word in your shell-like .................................. 4.1 Past, present and future ................................... 4.2 ====================================================================== Introduction: What is...? Chapter 1.0 ====================================================================== The norm, where FTP is an issue is to boot a shell-based, or GUI- based, FTP client and perform any actions manually, whilst connected to a FTP site. From the FTP client you can remotely transfer files in both directions and wander through the site's directory hierarchy at your leisure. Excellent if you're browsing, but time consuming and often costly if you pay for your Internet access. With FTPGet you can specify which remote file(s) you desire and where to obtain them from, as commandline arguments, and FTPGet will then go about its business of transfering the specified files to your local machine - without your interaction. Everything is automatic. ====================================================================== FTPGet: Chapter 2.0 ====================================================================== FTPGet is basically a FTP receive tool that acts in roughly the same way as the 'get' FTP session instruction. You specify what files you require, what name they should be given on your local machine (with restrictions - see later for more information), and where the files should be obtained from - FTPGet will do the rest. ---------------------------------------------------------------------- FTPGet: Installation. Chapter 2.1 ---------------------------------------------------------------------- FTPGet is nothing other than a standard AmigaDOS Shell command, and with that it can be placed anywhere you deem fit. Probably the best location to copy FTPGet to is AmiTCP's 'bin' directory, if that is how your AmiTCP hierarchy is configured. Otherwise the C: directory is more than adequate. Placing FTPGet somewhere within your path offers the obvious benefits. Alternatively, you may wish to make FTPGet resident. This can be achieved by the normal method of using AmigaDOS's 'Resident' command. With respect to stack requirement, FTPGet should work just fine with the default Shell stack size of 4096 bytes. In most cases, installation constitutes nothing more than copying the FTPGet binary across to your favourite device, but there are several features of FTPGet that will require extra work before they can be applied. These "features" (for want of a better word) are detailed below, and require the setting of several environment variables before FTPGet may apply them... Because commandline arguments can be a pain in the butt at times, especially if a program requires many of them, FTPGet can be made to rely on several specific environment variables. In some AmiTCP configurations most of the below variables may already be present, but I think it is best to detail them anyways. USERNAME - The name of the currently logged in user. The value will usually be an alias, as opposed to the real name of the user. Eg, setenv USERNAME "izzy" This variable may already have been set by the login software of the local site. HOSTNAME - The name of the local machine from which the transfer session will be started. Eg, setenv HOSTNAME "ancient" DOMAINNAME - The domain where the machine is located. Because the HOSTNAME variable, as detailed above, contains the name of the local machine, the DOMAINNAME variable doesn't require the host name to be given. The entry should still be prefixed with a '.' separator, though. Eg, setenv DOMAINNAME ".demon.co.uk" LOCALDIR - FTPGet relies on the need to know where the remote files should be transfered to on the local site. In most cases, the local file name will be issued as a commandline argument, but this need not always be so. The "LOCALDIR" variable relates directly to the path name where remote files will be written to, and it must be terminated with either a '/', or a ':'. Eg, setenv LOCALDIR "DATA:ARCHIVES/" setenv LOCALDIR "TRASH:" FTPGet will use the "LOCALDIR" variable only if a local argument hasn't been offered at the program's outset. For the uninitiated, you set any required environment variables by using the AmigaDOS 'SetEnv' command, which should be located within your system's C directory. Making use of the above environment variables effectly means you can reduce the size of the commandline you need supply to no more than two arguments at the most - best case scenario: anonymous FTP and only one transfer. ---------------------------------------------------------------------- FTPGet: How to...? Chapter 2.2 ---------------------------------------------------------------------- FTPGet requires atleast two arguments to be passed to it from the commandline: The Fully Qualified Domain Name, or IP address, of the remote site you wish to FTP from, and the path and file name of atleast one remote file that you wish the receive. Below are listed all the valid commandline arguments FTPGet will accept. SITE - The FQDN, or IP address, of a remote FTP site. All files requested for transfer will, hopefully, be located here. USER - The login name to be given at the remote site when the user name has been requested. If this argument isn't specified, the default user name of "anonymous" will be assumed. If the user name is not accepted at the remote site you may be notified and FTPGet will abort with the respective error (see chapter 2.3). PASSWORD - Can also be abbrieviated to PASS at the commandline. When a password is requested from the remote site at login, the given password will be used to satisfy that request. If you don't specify a password at the commandline, a password string will be made up for you by using both the USERNAME, HOSTNAME and DOMAINNAME environment variables that were discussed in chapter 2.1. ACCOUNT - Can also be abbrieviated to ACT at the commandline. If the remote FTP site requires a session account, the accounting information that you specified for the ACCOUNT argument will be used. If the given account is not valid at the remote site you may be notified and the FTP session will abort. CWD - May also be specified as DIR. CWD acts in exactly the same way as the CWD (Current Working Directory) FTP session command. Basically put, all files transfered will be "pulled" from the remote site relative to the given argument, where the argument is a path at the remote FTP site. Applying the CWD keyword can, in some cases, cut down the required length of the commandline - and that can only be a Good Thing. REMOTE - This keyword and its argument must be specified, or no transfer will be possible. Obvious really. ;o] From here, you tell FTPGet which file, or files, you wish to FTP from the remote FTP server. Multiple files may be specified, but two rules must be respected: 1) If a LOCAL argument is given on the commandline (see below) that constitutes a file name, all received files will be written locally under that name. When FTP'ing multiple files, either make sure you specify a directory name as the LOCAL argument, or ignore the LOCAL argument totally. See the reference to the LOCAL keyword for more information. 2) If any error occurs whilst the transfer session is in progress, all pending transfers will be aborted. LOCAL - The optional name that the remote file will be written as when transfered to the local site. 1) If a fully qualified path name (a path name and a file name) is given as an argument, the file will be stored locally under that name, no matter what its remote name was. 2) If this argument is a path name, the received file will be written to the local path with the name of the remote file. 3) In the event that no LOCAL argument was specified on the commandline and the "LOCALDIR" environment variable exists, the path name held within will be used. If the environment variable cannot be found the current directory will be used instead. NOTE: Do NOT fall into the trap of specifying a fully qualified path name (a path and a file name) when you have given multiple REMOTE arguments! The end result will be nothing less than wasted transfers on your part, as each subsiquently received file will overwrite the previous transfer! TEXT - FTPGet will default to a file type of BINARY. The TEXT switch (when active) will tell FTPGet to receive all remote files as ASCII. As you have probably guessed, receiving "mixed" file types is NOT possible. If you require both BINARY and ASCII you will have to initiate two sessions - one for each type. Er, sorry. QUIET - Just as it says, don't bother displaying any output to the stdout. FTPGet will return a return code no matter what happens, so typing "get rc" at the Shell will inform you of FTPGet's success. A CTRL-C issued from the Shell where FTPGet was started will abort the current session. ---------------------------------------------------------------------- FTPGet: Problems, problems. Chapter 2.3 ---------------------------------------------------------------------- If, for some reason, FTPGet is unable to perform its duty - if the remote host can't be found for example, a specific return code shall be met. The value of the return code relates directly to a specific error within FTPGet, these errors are listed below: 0 - Everything went okay. Not an error, but what the Hell. 21 - Invalid arguments, in general. 22 - Invalid password argument. 23 - Couldn't open bsdsocket.library 24 - Remote site doesn't exist. 25 - Remote server not responding/unavailable. 26 - User name not accepted at remote site. 27 - Password not accepted at remote site. 28 - Account not accepted at remote site. 29 - The remote file does not exist. 30 - Cannot create the local file. 31 - Transfer aborted. Transfer error, or user hit CTRL-C. Error specific return codes can come in very useful, especially if FTPGet is to be ran from a script. ====================================================================== Legalities... damn: Chapter 3.0 ====================================================================== You use FTPGet completely at your *own* risk, no warranty is either expressed or implied. I cannot (and will not) be held responsible for any damages caused by FTPGet, no matter what the circumstance. Either use this program or ignore it, but don't blame me for *any* unwanted results. Although FTPGet is freely distributable, it still remains the copyright 1995 Simon P. Dainty. FTPGet is definitely not Public Domain, it is freely distributable FreeWare - there is a difference. Anyone wishing to obtain a copy has the right to a copy, for little or no charge. Whilst the continued distribution of FTPGet is the author's goal, he hopes that you will conform to the following agreement: 1) No files are added to, or removed from, the archive with respect to the original distribution, and no files are modified relative to their original state without the author's prior permission. 2) No charge, other than the cost of media duplication and shipping may be asked for this package unless the situation of that charge falls within item three (below). 3) If this package is to be included as a part of a commercial or ShareWare (or variant) distribution, or magazine coverdisk, the author would appreciate some form of prior notification. Public Domain compilations (CDs or floppy) are exempt from the above requirement. If you are a non-conformist, at least make the effort to appreciate what I've written above. =o) Above all though, have fun. ====================================================================== ...Forty Two: Chapter 4.0 ====================================================================== FTPGet was written in C, with the aid of Matt Dillon's DICE C package (version 2.07.57R) and was tested on a 3.0-based AGA Amiga, running AmiTCP v3.xbeta and bsdsocket.library version 2. I'd like to take this opportunity to thank Osma Ahvenlampi for his help in beta testing FTPGet. Mucho gracias amigo. Even though FTPGet is freely distributable, I'd like you to think of it as "World-a-Ware". If you find FTPGet to be useful, or you use FTPGet for any period of time, please do a little something to help the environment of OUR home. We are all ultimately responsible for the world that we live in, and we are equally responsible for those we share it with. We only have the one copy of Earth and without a back-up... ---------------------------------------------------------------------- ...Forty Two: A word in your shell-like. Chapter 4.1 ---------------------------------------------------------------------- With respect to bug fixes, bug reports, general updates (if any) and pure talkability, I can be contacted at any of the addresses listed below. You will also find me lurking in most all of the Amiga related Usenet groups, specifically the comp.sys.amiga.* groups as well as a good few Amiga specific FidoNet and AmigaNet echos. Internet mailbox: ftpget@ancient.demon.co.uk (Simon Dainty) Or, izzy@ancient.demon.co.uk (Simon Dainty) FidoNet and AmigaNet, via Dox's Amiga BBS (+44 01943 850340): 2:250/320.3 (Simon Dainty) 39:138/14.3 " " IRC: Izzy/Si. Snail mail: 25, Victor Road, Heaton, Bradford, West Yorkshire. BD9 4QN. England. Electronic mail is my most preferred form of communication. SYL, Izzy. "It's amazing - with the blink of an eye, you finally see the light. Oh-ho, it's amazing - when the moment arrives, that you know you'll be alright. Yeah, it's amazing and I'm saying a prayer for the desparate hearts tonight..." - AeroSmith: Amazing. ---------------------------------------------------------------------- ...Forty Two: Past, present and future. Chapter 4.2 ---------------------------------------------------------------------- 21-Feb-95: v1.0 - Initial release with no know bugs. 03-Mar-95: v1.1 - Added CWD commandline keyword, which allows you to specify a remote directory that relates to the base directory from where the given remote files will be addressed.