Scripting: programming transfers in NFTP

Alert: New scripting interface in version 1.60!

Attention! Since version 1.60, the scripting interface (running nftp -@commandfile.txt) was completely redesigned. The old one, with +URL to download and -URL to upload was very primitive, so scrapping is probably a good thing. New stuff looks and works much better. Therefore if you were using NFTP prior to 1.60 to run download/upload scripts, please take time to read about new command set and change your scripts. Sorry for inconvenience caused by transition; I hope it will be for good.

Using scripting

To use scripting feature of NFTP, you first have to decide what actions you need to perform, see if they can be done with existing system (and complain to me if they can't be done), write script which just a plain text file with arbitrary name (say, script.txt) and then run nftp -@script.txt. Let's take a look at the example. Suppose you want to download file 00index.txt from the hobbes mirror at crydee.sai.msu.ru and put it into the d:\hobbes directory (Hobbes.NMSU.EDU is the biggest OS/2 software repository). Then you create the following daily-hobbes.txt file:
# downloading current index of fresh files on Hobbes (v.1)
open crydee.sai.msu.ru
cd /packages/os2.hobbes/incoming
lcd d:\hobbes
get 00index.txt
quit
Don't forget to create d:\hobbes directory, then run nftp -@daily-hobbes.txt. Voila! The 00index.txt file is here! When running the script for the first time, you might want to omit or comment out (with #) the last line, quit, to see what NFTP did and how. You may look at the results (screenshot of actual control connection).

Few more words about syntax in the script file. The first word is always name of the command (see list of commands below). The arguments are separated from the command name by arbitrary amount of spaces or tabs. You can't break the command and continue it on the next line, but the limit on the line length is rather large. Empty lines are ignored, and lines starting with # are considered to be comments.

If you did try to perform the above test, you might have noticed some inconveniences: if you forgot to create d:\hobbes, NFTP would stop at the lcd d:\hobbes command; if you run the script for the second time, NFTP would complain about file 00index.txt (it already exists and will be skipped). You could add a command to create directory d:\hobbes to script (lmkdir d:\hobbes) before lcd d:\hobbes and a command to remove the index file (ldelete 00index.txt) before downloading. However, these commands will fail when directory already exists and file does not. To prevent this stupid circle, we have to use another command, set errorstop. The enhanced daily-hobbes.txt file looks like:

# downloading current index of fresh files on Hobbes (v.2)
open crydee.sai.msu.ru
cd /packages/os2.hobbes/incoming
set errorstop 0
lmkdir d:\hobbes
set errorstop 1
lcd d:\hobbes
set errorstop 0
ldelete 00index.txt
set errorstop 1
get 00index.txt
quit
As you probably have guessed, we turned off stopping on errors while creating directory d:\hobbes and deleting file 00index.txt from it.

Commands in the script file

Below is the list of commands implemented in NFTP version 1.60. Note that command names are case sensitive; use open and not Open or OPEN!

[ ascii | binary | cd | close | delete | get | lcd | ldelete | lmkdir | lrename | lreread | lrmdir | logfile | mget | mirror | mkdir | mput | open | put | quit | quote | rename | reread | rmdir | set ]

ascii
Switch transfer mode to ascii.

binary
Switch transfer mode to binary. This is the default mode, and you only need to issue this command after ascii.

cd directory
Change directory on the server. Examples:
cd /
cd /pub/comp/os/Be
cd ..

close
Closes connection to server. Typically, you should not need this command (just use quit).

delete filename
Deletes filename on remote. Use rmdir to delete empty directories. Re-reads directory after action has been taken. Filename can contain wildcard patterns (*, ?). Examples:
delete nftp153o.zip

get filename
Download filename into the current directory. The local name will be the same as remote. If you need to rename it, you can do it later with lrename command; if you need to set specific local directory, use lcd. You need to be connected to execute this command (see open). Specifying pathnames instead of simple file names will not work. Also note that in many cases remote filename is case sensitive. Example:
get nftp153o.zip

lcd directory
Change local directory. On systems with drive letters, you can specify them. Forward and backward slashes are equivalent. Examples:
lcd /tmp/outgoing
lcd d:\download

ldelete filename
Deletes local filename. Use lrmdir to delete empty directories. Re-reads directory after action has been taken. Filename can contain wildcard patterns (*, ?), and it should not include path. Example:
ldelete nftp153o.zip

lmkdir directory
Create local directory. Access rights (on Unix) are determined by current value of umask. Example:
lmkdir daily-download

lrename oldname newname
Rename local file from oldname to newname. Cannot move file between filesystems (drive letter on OS/2, Windows; mount points under Unix, BeOS).

lreread
Re-read local directory contents. Typically you don't need this command as NFTP refreshes its local listing after operations which create/delete/update local files.

lrmdir directory
Delete local directory. If the directory is not empty, it will not be deleted. Example:
lrmdir daily-download

logfile filename
Record control connection history into the filename during execution of a script. The file is appended if exists and created if it doesn't; it never gets overwritten. To stop logging, use "none" as name of the file. Examples:
logfile d:\log\transfers
logfile none

mget template
Download files matching template into the current directory. Two wildcard characters are allowed in the template: "*" which will match to arbitrary number of characters (including zero) and "?" which will match exactly one character. Note that when no files match specified template this is not considered as error. You need to be connected to execute this command (see open). Example:
mget nftp*

mirror download | upload
Syncronizes local directory with remote (download) or remote directory with local (upload). Example:
mirror download

mkdir directory
Create directory on remote. Example:
mkdir newupload

mput template
Upload files matching template into the current directory. Two wildcard characters are allowed in the template: "*" which will match to arbitrary number of characters (including zero) and "?" which will match exactly one character. Note that when no files match specified template this is not considered as error. You need to be connected to execute this command (see open). Example:
put nftp-1.6?-*.*
open URL
Connect to site represented by URL. It may include username and password, if necessary, otherwise anonymous is assumed. You can put the directory into the URL, or set it later with cd. Typically, this is the first command in the script. Examples:
open ftp.cdrom.com
open ftp://crydee.sai.msu.ru/pub/comp/os/os2
open asv@crydee.sai.msu.ru
open asv:password@crydee.sai.msu.ru

put filename
Upload filename into the current directory. The remote name will be the same as local. If you need to rename it, you can do it later with rename command; if you need to set specific remote directory, use cd. You need to be connected to execute this command (see open). Specifying pathnames instead of simple file names will not work. Example:
put nftp153o.zip
Note that this command is case sensitive even on systems which do not have true case sensitivity in their filesystems. E.g., on HPFS both nftp153o.zip and NFTP153O.ZIP are valid names for the same file, but NFTP will only look for file with specified case. This is to prevent problems with uploading files to remote servers with case sensitive filesystems. For example, if you specify put NFTP153O.ZIP instead of put nftp153o.zip, you'll end up in remote name being NFTP153O.ZIP which might be not what you want. Therefore you have to ensure that the case is correct in the put statement. On FAT under OS/2, which is not case sensitive at all, all filenames are assumed to be in lowercase.

quit
Exit NFTP, closing connection if necessary.

quote command
Send arbitrary command to server. Note that server response code is ignored, so even if you will issue invalid command to server, NFTP will still think that everything went OK. Example:
quote site umask 077

rename oldname newname
Rename remote file from oldname to newname.

reread
Re-read directory on the server. Useful for forcing updating file list after upload, delete, etc.

rmdir directory
Delete directory on remote. If the directory is not empty, it will not be deleted. Example:
rmdir newupload

set variable value
Set variable to value. See next paragraph about available variables and their values.
[ ascii | binary | cd | close | delete | get | lcd | ldelete | lmkdir | lrename | lreread | lrmdir | logfile | mget | mirror | mkdir | mput | open | put | quit | quote | rename | reread | rmdir | set ]

Variables

Currently implemented variables and their possible values:

VariableValueExplanation
errorstop 1Stop at errors on subsequent commands. Default
0Ignore errors on subsequent commands. Script syntax errors still cause abort
errorexit 1Exit NFTP on error (it is recommended to turn on logging with logfile to see what has happened)
0Stay in control connection when error during script execution happens. Default
mirror.delete-unmatched 1delete unmatched files when mirroring
0leave unmatched files when mirroring
mirror.include-subdirs 1change into subdirectories when mirroring
0do not change into subdirectories when mirroring


NFTP home page // Send comment