-*-Text-*-

File: FTP	Node: TOP	Up: (DIR)	Next: BASIC

Description of FTP commands, as of 2/5/77

FTP is a utility program for transferring files over the ARPA network.
The name of the program comes from the name of the protocol used
(File Transfer Protocol).

* Menu:

* BASIC::	The basic FTP commands.
* TYPE IN::	FTP's typein conventions.
* LESS::	Some less useful commands.
* DEFAULTS::	How FTP does file name defaulting.
* RARE::	The rarely used commands.
* JCL::		Giving FTP commands from DDT.
* XFILE::	Command files.
* INFERIOR::	Programs can use FTP as a subroutine.


File: FTP,  Node: BASIC,  Previous: TOP,  Up: TOP,  Next: TYPE IN

The Most Useful FTP Commands:
 Note that unambiguous abbreviations may be used for command and
 host names.  See the Next node for how to edit your input.

CONNECT <host>	Connects to a foreign host.  Use the name of the host
		or its (octal) numeric address.  A pre-existing
		connection will be flushed.
		FTP prompts with "$$" when it is not connected to
		a foreign host, and with "$" when a connection exists.

<host>		Is equivalent to CONN <host>.

HOSTS		Lists the names of hosts which FTP knows

LOGIN <name>	Logs in at foreign host (if needed by that host)
		If you get an error message implying that you are not
		logged in, this is where to start.  Sometimes FTP
		will figure out by itself that logging in is what you
		have to do;  then it will ask for for a user name,
		send it, and go ahead with the operation you had
		already requested.

TEN		Mode command for pdp10 36 bit binary files.
		(May also be used for pdp10 ascii files if you don't
		mind extraneous characters at the end of the file)
		NOTE: This is the DEFAULT mode when communicating with
		another PDP10.  You can specify it explicitly, also,
		with any computer (although some may not accept it).
		It is an abbreviation for TYPE I and BYTE 36

TEXT		Mode command for Network ASCII data transmission.
		This mode is the DEFAULT when communicating with a
		machine that is not a PDP10.  It is an abbreviation
		for TYPE A and BYTE 8.

GET or RETRIEVE	Transfers a file from foreign host to here.
		Asks for local name (end with CR) and then foreign name.

PUT or STORE	Transfers a file from here to foreign host.
  or SEND	Asks for local name (end with CR) and then foreign name.

APPEND		Appends a local file onto a file at the foreign host.
		Arguments are local file (not changed by the operation)
		followed by the foreign file (which will be created if
		it does not exist), as for PUT.

TRANSFER <host1><file1>=<host2><file2>
		Transfers <file2> at <host2> to <file1> at <host1>.
		Two foreign hosts can't be used, though;  one of
		<host1> and <host2> must be the local host's name.
		Abbreviations are allowed:  You can leave out the
		name of the local host (omitting the altmode as well),
		as in TRAN FOO BAR=MCFOO BAR or TRAN MCFOO BAR=X Y,
		and if the two filespecs are identical either one may
		be omitted, as in TRAN FOO BAR=MC which is equivalent
		to TRAN FOO BAR=MCFOO BAR.
		NOTE:  "_" is equivalent to "=".  To include a "=" or
		"_" or a ^Q in a filename in a TRAN command, precede
		it with a ^Q (which will be gobbled up as a quote).
		^Q's followed by other characters (not _, = or ^Q)
		will NOT be absorbed by TRAN (so you can use them to
		quote at other levels, with hosts that understand it).

QUIT		Closes connection to foreign host, and then exit from FTP

^C		Is the same as QUIT - no CR is needed.
		Any command may be terminated with a ^C instead of a
		CR, in which case that command will be followed by
		a QUIT (unless it encounters an error).

DISC		Closes connection to foreign host.  You may then connect
		to another host, or QUIT, or ^Z...

HELP or ?	Types a list of commands, with brief descriptions.

File: FTP,  Node: TYPE IN,  Up: TOP,  Previous: BASIC,  Next: DEFAULTS

Type-in Conventions:

You can use Rubout to delete one character, ^D, ^G or ^U to
cancel an entire line, and ^L to redisplay the current line
as typed so far.  Commands with no arguments should be terminated
with a CR.  When giving a command with arguments, you can
separate the command name from the first argument with either
a space or a CR (if you use CR, FTP will tell you what sort
of argument is expected).  When a command requires several
arguments, the arguments are separated with CRs.  Command names may be
abbreviated as long as the abbreviations are unambiguous.

You can use a ^C instead of CR to terminate a line.  That
causes FTP to return to DDT, killing itself, after the current
command is finished (as long as it does not get an error).
If you plan to disown a FTP while it is transferring, you should
end the last command with a ^C so that the FTP will go away
when it is finished;  otherwise it might hang around for an hour
until ITS kills it.

You can use ^N instead of CR to terminate a line.  This is not
especially useful when you are typing on the TTY, but it is
useful when passing commands from DDT, since it allows you to
put several lines' worth of input into the one line that DDT lets
you send.

File: FTP,  Node: DEFAULTS,  Up: TOP,  Previous: TYPE IN,  Next: LESS

Filename Defaulting:

Local filenames default "stickily", so that each file's device,
sname, and first and second filenames all default to the last
such names specified for a local file.
Giving a null argument for the local file will cause the default
file to be used.
When you specify only one filename, it is the first filename,
and ">" is used as the second.
The initial default directory is your working directory.

If you wish to include a space, colon, or semicolon in a local
filename (or in a foreign filename if the foreign site is an ITS),
precede it with a ^Q.  The same technique is used for including
a = or _ or ^Q anywhere in a pathname, in the TRAN command.

File: FTP,  Node: LESS,  Previous: DEFAULTS,  Up: TOP,  Next: RARE

Less useful commands:

DELETE <file>	Deletes the specified file at the foreign host.

RENAME <oldname>
       <newname>
		Renames the file <oldname> at the foreign host to be
		called <newname>.  Separate the two names with a CR.

DIRECTORY <dir> or
LISTF <dir>	Types out a listing of the foreign host's directory <dir>.
		Some hosts may also allow you to specify a filename,
		in which case info on that file will be given.

LISTB <dir>	Types out a brief listing of a foreign directory.
		It is like LISTF except that only the filenames are
		typed - no other info on the files.

LISTL <dir>	Types out a listing of the directory <dir> at
		the local host.

CWD <dir>	Sets the foreign default directory to <dir>

DEFAULTS <filenames>
		Sets the local filename defaults to <filenames>.
		Note:  the local defaults are sticky;  each local
		filename's names default to the last filenames
		specified for a local file.

File: FTP,  Node: RARE,  Previous: LESS,  Up: TOP,  Next: JCL

Rarely Useful Commands:

STATUS <arg>	Asks for a status message from the foreign host.
		The meaning of <arg> is site-dependent.  ITS sites
		don't implement the command at all.

QUOTE <command>	Sends <command> directly to the foreign host over
		the TELNET connection.  Used if the foreign host
		implements some simple command that FTP doesn't know
		about itself.  It won't work for commands that do
		anything hairy (such as use the data connection at
		all) since FTP doesn't expect it to do that.

SOAK		Waits for and describes one reply from the server.
		This is never necessary with any of the normal
		FTP commands, since they know when to wait for
		replies.

DEBUG		Toggles the switch which says whether to print expected
		replies from the server (unexpected replies such as
		error messages and notices to the user are always
		printed).  The DEBUG switch also causes reply codes
		to be given with all replies, not just error messages.

PASS <password>	Sends a password to a foreign host.  Note that after
		a LOGIN command, if a password is needed, FTP will
		usually be able to figure that out;  it will ask you
		for the password and send it automatically, so you
		need not explicitly give a PASSWORD command.

ACCT <account>	Sends an account number to the foreign host.  Note
		that if after a LOGIN command an account number is
		needed, FTP will usually figure that out and just
		ask you for it.  So you usually won't need to give
		an explicit ACCT command.

ALLOCATE <size>	Sends the foreign host the estimated size of a file
		you are about to send it (measured in bytes).  Most
		hosts don't need ALLOCATE commands since they can
		allocate file storage dynamically.

TYPE <type>	Says what transfer type to use.  Of the many types
		specified in the FTP protocol, only A (ASCII) and
		I (Image) are implemented on ITS.  You usually
		would rather use the TEXT or TEN commands, since
		they specify the two most useful combinations of
		TYPE and BYTE.

BYTE <size>	Says what byte size to use for transfers.  The only
		byte sizes implemented on ITS for FTP'ing are 8,
		32 and 36.  In any case, you should usually use the
		TEXT and TEN commands for mode-setting.

ICPSOCKET <number>
		Causes FTP to try to connect to servers using socket
		<number> rather than socket 3, the standard FTP server
		listen socket.  Useful for testing experimental
		versions of the server, not actually installed yet.

SILENT		Tells FTP not to type out on the terminal at all.
		This remains in effect until FTP tries to read input
		from the terminal.  It does not affect printing in a
		script file.

PROCEED		Tells FTP to continue running without the terminal.
		FTP accomplishes this by valretting a ^P command.  A
		SILENT is done automatically.  This command is illegal
		when commands are being read from the terminal, unless
		TTY input was actually translated to a file.

DISOWN		Tells FTP to continue running disowned.  Just like
		PROCEED except that the FTP is disowned as well as
		^P'd.

VALRET		Returns to FTP's superior with a .BREAK 16,100000
		(which does not kill the FTP).  The FTP can be
		proceeded, or it can be given new JCL and restarted.

File: FTP,  Node: JCL,  Up: TOP,  Previous: RARE,  Next: XFILE

Giving FTP commands from DDT:

If you do :FTP <command> and <command> contains an = or a _,
FTP automatically does a TRAN command with <command>
as arguments.  After that transfer completes, FTP
kills itself.  For example, :FTP FOO BAR=MC will
transfer FOO BAR from MC to the local host, leaving
you back in DDT.

If the command string from DDT does not contain an = or a _,
it is simply executed as an FTP command.  FTP will then read
more commands from the TTY, since one FTP command (unless it
is TRAN) is not usually enough for a whole transaction.


File: FTP,  Node: XFILE,  Up: TOP,  Previous: JCL,  Next: INFERIOR

Command Files:

XFILE <file>	Tells FTP to open <file> and read commands from it.
		Commands in an execute file look just like commands
		typed on the TTY.  Linefeeds are ignored, so you ought
		to use CRLF between lines.  Any error (such as a
		failure to establish a connection or a failure to find
		a file) causes reading from the command file to be
		discontinued.

SCRIPT <file>	Tells FTP to open <file> and print init everything
		that appears on the TTY.  If there is no command file
		(commands are still being read from the TTY) then
		output continues to go to the TTY as well as the
		script file.  If there is a command file and a script
		file, then nothing is output to the TTY.  If you wish
		to have an FTP run without your attention, you need to
		have both a script file and a command file.

ESCRIPT		Tells FTP to stop using a script file.  If there is a
		script file open, it is closed.  This isn't necessary
		if you are doing a QUIT or ^C.

One reasonable way to operate is to give FTP a SCRIPT command and then
an XFILE command from the TTY, and then ^P the FTP.  If the command
file does not do a QUIT then when it is finished you will be told
that "FTP wants the TTY".  Alternatively, the command file might
contain a PROCEED command which would do the ^P automatically.

File: FTP,  Node: INFERIOR,  Up: Top,  Previous: XFILE

Use of FTP as a Subroutine

  You can invoke FTP as an inferior to transfer some files as long as
you provide it with a source of commands and a place to list its
commands and replies.  The command source can be provided either by
translating TTY input to a file, or by giving an XFILE command as JCL.
A file for listing can be provided either by translating TTY output to
a file or by including a SCRIPT command in the JCL.  If you are not
interested in looking at the output (you trust that the foreign hosts
will be available, etc) then you can use NUL: as an output sink.  The
SILENT command may be helpful in suppressing inconvenient typeout that
might occur before you have both a command file and a script file set
up.  Either way, you do not need to give FTP actual ownership of the
TTY.

  If you wish to include all the commands in the JCL string, there is
no need for a command file.  There will still be a need for a script
file, however.  Multiple commands in JCL are separated either with
CRLF or with ^N.  Note, however, that commands that came from the JCL
will not be echoed to the script file, while commands from an XFILE or
a translated TTY will be echoed.

  If you did not translate TTY input (you gave a XFILE or put all the
commands in the JCL) then on any error FTP will execute a .BREAK 16,
which specifies that type-ahead is to be discarded.  If you are not
watching the FTP replies, this can be used as an indication that there
was recently an error.

  If you wish to use a single FTP job for several operations, not all
at once, the VALRET command is useful.  It makes FTP stop and return
control to its superior with a .BREAK 16,100000, without altering any
of its state variables.  The VALRET command should go in the command
stream at the end of the commands for a single run.  After the FTP
returns, it can be proceeded (to continue with commands from the same
source) or it can be given some fresh JCL and restarted from its
normal starting address.
