perm filename PUPFTP.PUB[S,NET] blob sn#831049 filedate 1986-12-18 generic text, type C, neo UTF8
C00001 00001
C00003 00002	.COMMENT -----------------------------------------------------------------
C00012 00004	.Comment- .COMMANDS .CASE .SWITCHES
C00023 00006	.Comment- .MULTIPLE .WILD
C00028 00007	.Comment- .RETRIEVE .GET .STORE .SEND .PUT
C00037 00008	.Comment- .DELETE .LIST .STAT .NLST
C00048 00010	.Comment- .USER .LOGIN .ACCOUNT .ACCT .ALIAS .CWD .XCWD
C00052 00011	.Comment- .EXIT .QUIT .BYE .XIND .HELP
C00057 ENDMK
.COMMENT -----------------------------------------------------------------;
.COMMENT	THIS FILE is also used by PUPFTP to generate HELP message
.COMMENT	by following the E directory to particular labels and
.COMMENT	filtering PUBness.  HELP.FAI[1,TVR] is the routine that
.COMMENT	does this.
.COMMENT	Make sure things between a .label: and .HELPEND is honest
.COMMENT	and reflects the current version.
.COMMENT	Make sure all non-PUB text stays justified.  If you insert
.COMMENT	more PUBness, you may have to add {COMMENT ...
.COMMENT					  } to make things line up.
.COMMENT	If you don't understand, get TVR to change it for you.
.COMMENT	If you change a section, please go run PUPFTP and do a
.COMMENT	HELP command for that section.
.COMMENT	P.S.:  PUB.UPD[S,DOC] is recommended reading.
.COMMENT -----------------------------------------------------------------;
.MACRO HELPEND ⊂ Comment This macro is used to mark end of HELP text; ⊃
.MACRO MORE ⊂ Comment This macro is used to break up HELP text; ⊃
.		 END
.		 COMMAND1 ⊃
.		  GROUP
.		  TURN OFF "←→"; TURN ON "{"
.		  AT "Synonym" ⊂ TURN ON "→"; }→Syn{}onym{ ⊃;
.	       ⊃
.		   SKIP 1
.		   INDENT 0,8
.		   PREFACE 0
.		   TURN ON "∂"
.		   AT 8 ⊂ " " ⊃
.		   AT "/" A " " ⊂ BREAK; "≡/A∂8"
.				  ⊃
.		 ⊃
.SITENAME ← "SAIL"				COMMENT I'm dreaming here;
.TURN ON "{"
.TURN ON "≡" FOR "α"				COMMENT Quotes next character;
.DATE ← DAY & " " & MONTH & " " & YEAR		COMMENT Use better convention;
.  END
.BEGIN CENTER					COMMENT Temporary title page;
PUPFTP - Ethernet FTP
.  SKIP 2
.    SKIP 1
Note:  This copy is intended for online use only.
.    SKIP 1
.    SKIP 1
A version suitable for printing could be made upon request.
.    SKIP 2
.    END
.  END
.COMMENT Don't do this until AFTER title page starts;
.comment	EVERY HEADING(PUPFTP,{DATE},|{"Page " PAGE!}|);
.comment PUB bug!  Gets "Undefined identified ELSE", but only if EVERY HEADING;
.comment is done after BEGIN CENTER!!!!;
.  PAGE ← PAGE + 1				COMMENT "Off by 1";
.  END

PUPFTP is a program to transfer files over an Ethernet connection.  It can
both store and retrieve files from a remote file system, as well as do other
file management operations, such as deletion, renaming files, and listing
directories.  It is capable of transferring multiple files on a single
command when given 'wild card' file names.  It can also take commands from
a command file, or from the line typed; to the system to invoke PUPFTP.

PUPFTP is different from Internet FTP.  The Internet protocol uses TELNET
based commands and communicates data on a separate link.  PUPFTP uses
special marks to separate commands and data, and has property list based
commands.  Like the Internet version, the default mode for data transfer
is text, unless the remote host supports 36-bit bibary file transfers.
PUPFTP in text mode also defaults to a different end of line convention
than is used on WAITS, and this must be avoided if sending files formatted
for the LPT or XGP.

SAIL users should prefer Internet FTP when possible, since it is generally
faster.  CCRMA users must use PUPFTP, since CCRMA does not support the
Internet protocols.


In the following documentation, the term 'local' refers to the site on
which you are running PUPFTP and the term 'remote' (or 'foreign') refers
to the other computer system that to which PUPFTP is connected.  Keep this
especially in mind when you are using CHAT to communicate with a system
and then that system's PUPFTP to connect to the system on which you are
running CHAT!

.}The manual is organized first by topic and then by command.
.}The first line of a command description look like this:
{Comment}HELP for a command will begin with something like this:{;}

	ACCOUNT name					Synonym: ACCT

Words entirely in upper case stand for themselves and are usually command
names.  Words entirely in lower case stand for what they describe; for
example, 'name' stands for the account name that you would like to use.
'Synonym' refers to alternate names for the command which are included for
people who may be accustomed to an FTP program on a different system.
{Comment}Type HELP COMMANDS for more information.{;}
A command consists of a command name, optionally followed by switches and
arguments, if any.  The command name may be abbreviated to as few
characters as are needed to uniquely specify the command.  However, new
commands might be added in the future.  Therefore, it is recommended that
in command files that at least four letters be used, as the first four
letters will be guaranteed to be unambiguous.  Switches immediately
follow the command name without any intervening spaces{
{Comment			  		     } (HELP SWITCHES for
{Comment} more information){;}.

For most commands, the remainder of the command line is passed to the
remote system with little or no interpretation.  A few commands may also
reference a local file, which is separated from the rest of the command by
an arrow ('←' or '→') or an equal sign ('=').  Local files must precede
remote files in the command line since PUPFTP makes no assumptions about
the format that the remote system uses for file names.  Local files are
referred to as follows:

{}	device:filename.extension[project,programmer]

Where most of these fields may be omitted.  There must be either a
'filename' or a 'device' field and some devices, notatably DSK and UDPs,
require a filename.  Note that 'device' and 'filename' are limited to six
characters and the other fields to three characters, and in general, these
characters should be letters or digits.  If 'project' and 'programmer' are
omitted, then the default (that is, your current ALIAS) directory is used.

Command names and local file names may be in upper, lower, or mixed case.
However, some systems, notably UNIX, may care about what case is supplied
for things like remote file names, user names, and passwords.


*** Switches are not implemented yet. ***

A switch is something that may optionally be given to change the way a
command works.  Switches consist of a slash ('/') immediately followed by
a letter.  Except when specify global switches upon opening a connection,
all switches must immediately follow the name of the command (not after
files or other parameters).  A switch may also have a minus sign ('-')
between the slash and the letter which usually inverts the function of the
switch.  For example,


permit overwriting of TEST.TXT without asking for confirmation, while


requires confirmation.

To connect to a system which is a 'server' (a VAX, PDP-10, or other large
machine), you run PUPFTP and give it a host name.  On a system which is a
'user' (or personal machine) like an ALTO, you may have to start up an FTP
program before attempting a connection.  You may specify the host name on
the WAITS monitor command line by:

	R PUPFTP;host-name

For example, 'R PUPFTP;IFS' would connect you to the host called IFS (Interim
File Server.)

A 'host-name' is something that refers to a particular system connected
via the Ethernet.  It must be spelled out in full as the host name to host
number translation is obtained from a host on the Ethernet which does not
support abbreviation.

If for some reason the host name doesn't seem to work, and you know the
host number, you may give that instead.  The format to specify a numeric
host is:

	R PUPFTP;host-number#
	R PUPFTP;network-number#host-number#

These numbers are in octal.  For example, 'R PUPFTP;50#200#' is an
alternative way to connect to SUNet's IFS.

*** The following is not implemented yet.

When establishing a connection, you may also specify global switches which
are in effect for the duration of the connection.  They are included
immediately after the host name in the WAITS monitor command.  For example,


will save a typescript of your interactions with the IFS on a file called
FTP.LOG on your default (that is, your ALIAS) directory.  The global switches
currently defined are:

/L	Save typescript on FTP.LOG
/A	Append typescript to FTP.LOG instead of replacing it as ≡/L does.
/V	Always ask for confirmations.
/-V	Never ask for confirmations.

The default is not to save a typescript and to ask for confirmation under
certain circumstances which are documented under the individual commands.


Most commands expect confirmation before completing an action.  This is
different from Internet FTP, which only asks for confirmation when
overwriting a file.  There are several reasons for this.  First, many
commands can transfer more than one file and the user may not want all of
the possibilities.  Second, most other PUPFTP implementations request
confirmations, and so many users will be expecting an opportunity to
verify that they really want to do an operation.

The program expects confirmation when it prints one of the following:

	(New file)
	(Old file)

To confirm or reject, type one of the following:

{}	Accept:	<return> or <space>
{}	Reject:	<rubout> (also called <bs> on some terminals)
{}	Abort:	<altmode>

.comment When it types (New file) or (Old file), you may also type a file name to use;
.comment instead.;
When you type <altmode>, the entire command is aborted.  If the command
involves a large number of files, it may take a while for PUPFTP to cancel
all of the pending requests.

When implemented, you will be able to use the switches /-V or /O to
suppress some or all confirmations.

.Comment- .MULTIPLE .WILD;

Most systems which are 'servers' require a user name and password before
you are permitted to access any files.  This may be supplied in the USER
command, which will also ask for a password with echoing turned off
(assuming you have a full duplex terminal or display).
.comment Alternately, this information may be obtained from a file,;
.comment which is also descrined in the USER command.;

{}CAUTION:  At the current time, systems running UNIX are sensitive to case,
that is, if the user name is lower case (which is almost always true),
then it must be supplied to PUPFTP in lower case.


Some commands may operate on more than one file.  STORE can always do
multiple files, and RETRIEVE, LIST and DELETE may if the remote system
supports this.  Normally, multiple files are specified by 'wild card' file
names.  This permits one or more fields (depending on implementation) to
be partially specified or unspecified.  '*' means match anything in a
particular field, and also matches the period ('.') separating the
extension from the rest of the file name.  For example:


will store all files having the extension 'FAI' on the directory '[1,BAR]'.
An example of a partially specified field is:


which will store all files with 'PUP' as their first three letters and any
extension.  Since '*' can also match a period separating the extension, we
could have also simply said 'STORE UDP1:PUP*'.

{}CAUTION: The meaning of '*' is different in PUPFTP than it is for
Internet FTP.   'FOO*' will match both 'FOOMAC' and 'FOO.MAC', which most
WAITS users may not expect.  Use 'FOO*.' to insure that the extension is

Wild cards may also be used for directory names.  For example:

	RETRIEVE <*Doc*>*.Press

Note that in both cases, the directory is only used on the end of the
transfer where the file(s) are read.   That is, '[*,XYZ]' only applies
on the local end of the STORE and '<*Doc*>' only applies on the remote
end of the RETRIEVE.  On the other end of each of those transfers, the
normal default directory is used.  That is, on a STORE, PUPFTP parses
the full file name, including directory, and but only sends the file
name and extension of the file being transferred to the other end.

PUPFTP does not attempt to parse the file name on a RETRIEVE; instead, it
simply sends it.  The remote system separates the device and directory
information and returns a file name which may be used as a local file
name, subject, of course, to the WAITS restriction of six characters for a
file name and three characters for an extension.
	RETR local-file←remote-file			Synonym: GET
	RETR file

The RETRIEVE command (usually abbreviated as RETR) transfers files from
the remote system to the local system{" (" SITENAME ")"
{comment 			   ;}.  The first form is used to transfer
single files, usually giving them a different name on the remote system.
The second form is used when the same file name is intended for both
systems.  However, the local system{ " (" SITENAME ")"
{comment			  ;} only uses the first six characters
for the file name and the first three characters for the extension.  For
example, ETHERNET.PRESS would be written by WAITS as ETHERN.PRE and would
be overwritten by ETHERNET.PRESENTATION if both files are retrieved using
the second form.

A retrieve may refer to multiple files, by means of 'wild card' file names.
What a wild card file name can be depends upon what the remote system
implements.  Usually, the character '*' is taken to match any number of
characters, including the '.' used to separate the extension from the rest
of the file name.  At the present time, wild cards may only be used in the
second form or in the remote file part of the first form.
.comment If '*' is used in the local-file part of the first form, then
.comment the first one is replaced by the filename part of the remote file
.comment and the second one is replaced by its extension.

Transfers using 'wild card' file names will require confirmation for each
file transferred.  <RETURN> accepts a file, and <RUBOUT> (sometimes called
<BS> or <DEL>) rejects a file.  <ALTMODE> (sometimes called <ESCAPE>)
aborts the entire command.

The default mode for transfer is type Text, byte size 8.{
.comment However, if no TYPE command has been given, it will use whatever
.comment type the remote system supplies with the file.{;
{comment					      ;}  See the TYPE
command for more information on possible types and byte sizes.

.skip 1
The following switches may be given in a future implemention:

/V	Verify.  Always asks for confirmation from the terminal.
/-V	Never asks.
/O	Overwrite OK, don't ask for confirmation
/N	Never overwrite existing files.
/U	Update.  Transfer file if file already exists, but has an
	older creation date than the remote file.
/W(?)	Similar to ≡/U, except that it transfers files which do not exist,
	or have been written more recently.

	STORE local-file→remote-file			Synonyms: PUT, SEND
	STORE file

The STORE command transfers files from the local system {"(" SITENAME ") "
{comment					      ;}to the remote
system.  The first form is used to transfer a single file, usually giving
it a different name on the remote system.  The second form is used when
the same file name is intended for both systems.  However, the local
system truncates the file name to six characters and the extension to
three character, and no more than these are given to the remote system as
a file specification.  The first form must be used if you want the remote
file to have longer file names than are used locally.  Note that some
systems, such as UNIX, expect their file names in lower case, and the
first form must be used for those sites.

The STORE command may also transfer multiple files via 'wild card' file
names.  A file name may include one or more instances of '*'s.  '*' matches
zero or more instances of any character found in a file name including '.'
but excluding '['.  This means that '*MAC' will match FOO.MAC and FOOMAC,
and is different from the way it works in the COPY program.  Use '*.'  if
you want to match all files having no extension.  '?' will match exactly
one instance of any character, including '.' but not '['.  For now, wild
cards may only be used in the second form of STORE, that is, using the same
file for both local and remote systems.

Transfers require confirmation for each file transferred.  When you are
asked, the file name printed is the name under which the file will be
stored on the remote system.  <RETURN> accepts a file, and <RUBOUT>
(sometimes called <BS> or <DEL>) rejects a file.  <ALTMODE> (sometimes
called <ESCAPE>) aborts the whole command.

The default mode for transfer is Type Text, Bytesize 8.{
.comment However, if no TYPE command has been given, heuristics will be used
.comment to determine in which mode to write the file.{;
{comment					      ;}  See the TYPE
command for more information.

You may use '=' in place of '→' (right arrow).  The right arrow is intended
as a reminder that this command uses an unconventional ordering of source
and destination files.

{}Note: Under the current protocol, the program cannot detect the overwriting
of an existing file on the remote system without doing an extra directory
command to explicitly find out if the file already exists.  This might be
implemented in a future version of PUPFTP if this proves to be a problem
and fixing the protocol is not feasible.

.skip 1
The following switches may be given in a future implemention:

/V	Verify.  Always asks for confirmation from the terminal.
/-V	Never asks.

{}Note: Many options available in RETRIEVE are not currently available in
STORE.  This is because the STORE command does not presently know if the
file already exists on the remote system.
	DELETE file

The DELETE command (often abbreviated as DELE) is used to delete (remove)
files from a remote system.  It may be used to delete a single file or
multiple files if the remote system implements 'wild card' file

Deletions require confirmation, which is taken from the terminal.  When
you are asked, the file name to be deleted is printed.  <RETURN> accepts
a file, and <RUBOUT> (sometimes called <BS> or <DEL>) rejects a file.
<ALTMODE> (labeled <ESCAPE> on some terminals) aborts the entire command.

{}Note: Version numbers are implementation dependent, and not all systems
operate the same way.  On some systems, DELETE will delete the oldest
version, on other systems will delete the most recent, and still other
system may delete all versions.  The SUNet IFS deletes the oldest version,
but you should check the documentation for the system you are using to find
out what it does with version numbers.

The following switches may be given in a future implemention:

/V	Verify, the default.  Always asks for confirmation from the
	terminal. If there is no terminal, the deletion will not take
	place.  This is intended for command files where the user must
	confirm all deletions.
/-V	Never asks.  Use this in command files.

	LIST file					Synonym: STAT
	NLST file

The LIST and NLST commands type on the terminal what files exist on the
remote system.  NLST only prints the file names while LIST also prints the
size and date last written for each of the requested files.

The file specification may include 'wild cards'.  So, to list everything
in the directory (on most systems, at least), you can say 'LIST *'.  Note
that if you do not supply some kind of file specification, the result is
undefined.  If no directory is specified, then the alias (set by the ALIAS
or CWD command) is used as the directory.  If the alias directory also has
not been specified, then the user name is used for the directory; and if
neither has been specified, the result is undefined.

Lacking in this command is the ability to send the output to a file instead
of the terminal.  This will be implemented in a later version of PUPFTP.

The following switches may be given in a future implemention to affect what
is printed.

/T	Type of file
/L	Length of file (in bytes)
/D	Date of creation
/R	Read date
/W	Write date
/A	Author
/E	Print everything

	TYPE TEXT					Synonyms: ASCII, TEXT

.comment The TYPE command is used to specify the type of data transfer to be used.;
.comment Type TEXT is the default in the absence of other information, which is;
.comment sometimes supplied by the remote host during RETRIEVE operations.  and is;
.comment determinated by heuristic on STORE.;
Type TEXT is the default in the absence of a TYPE specification.  The TYPE
command used to force transfers to be a particular type.  At the present
time, this is required to transfer binary files.

The command 'TYPE TEXT' may be abbreviated as the command 'TEXT' or
'ASCII'.  Text files are sent over the Ethernet with a byte size of 8, but
only 7 bits per character are used locally.  This means that you cannot
transfer 8-bit ASCII text files (i.e., files containing characters with the
'200 on) to SAIL in text mode.  SOS line numbers are removed when files are
stored, and the SAIL character set is converted into a somewhat more
conventional ASCII arrangement.  Nulls are also removed on both storing
and retrieving in text mode.

In addition, CRLF's are converted into single CR's on text stores and back
from CR's to CRLF's on text retrieves unless specified otherwise by the
EOL command.

Because of the conversion of CRLF's and the suppression of nulls, .XGP
files and anything else that contains overprinting or nulls will not be
preserved by a TEXT type transfer.

Type BINARY is similar to type LOCAL in Internet FTP, except that the
representation is different during transfer. Because of that difference,
the file may be stored in a different representation on a machine with a
different word size than if received from the Internet.  Available byte
sizes are 8, 32, 36, and 72.  Byte size 72 sends two PDP-10 words as nine
8 bit bytes.

A number of types available on Internet FTP are not available in PUPFTP.
Types P and E are not supported by the protocol, and type L is not
implemented at the present time.

{}Note: Checking is done to make sure the data you are sending is compatible
with the byte size you are using.  In particular, a transfer will be aborted
if a text transfer is received with the 8th bit set, if any of the low order
4 bits are on in PDP-10 word on a store of byte size 8 or 16, or if 36 bit data
is received with the unused part of the first byte non-zero.  This is to
ensure the integrity of the data you are transferring.  Type X is the
same as Type Binary except that this checking is suppressed.

SAIL character conversion is as follows:

      Graphic	Local	Remote	Name

	_	'30	'137	Underline
	←	'137	'30	Left arrow
	≠	'33	'32	Not-equals
      <ALT>	'175	'33	<ALT> (or <ESCAPE>)
	}	'176	'175	Right brace
	~	'32	'176	Tilde

This is the same mapping that is used on font files between SAIL and MIT
except that '≡↑' is not mapped.


The TENEX command is shorthand for TYPE B, BYTESIZE 36, EOL-CONVENTION CRLF.
Use this when transferring data files to/from a PDP-10 or other 36 bit host.
You may also want to use this to transfer text to another WAITS site, but
probably not to another PDP-10.

	USER name					Synonym: LOGIN

The USER command sets what the remote system will be given as a user name
when any file operations are done.  Note that PUPFTP does not actually use
this information until a transaction is attempted.  Therefore, it also
asks for a password, in case it will be needed.  The password is requested
with echoing turned off.

As well as providing access control, the user name also specifies the
default directory for the remote system.  This default is overriden by
specifying an explicit directory name in a command, or by the ALIAS

.skip 1
The following is planned but not implemented.

If the USER command is read from a command file, then it first looks in
FTP.INI on the current directory, then FTP.INI in your 'master' directory
(i.e. FTP.INI[1,FOO]) to see if there is a password listed corresponding to
the name given in the command.  If it does not find a match, then it asks
for the password from the terminal.

{}CAUTION: If FTP.INI is to be used, it should have protection of 077 and it
is recommended that it be kept on an area that does not belong to any
groups.  Even so, DO NOT consider passwords stored there as secure.

	ACCOUNT name					Synonym: ACCT

The ACCOUNT command sets the account string to be used with the user name
(and password) on systems that require such things.  At the time of this
writing, no machine on the Ethernet is known to the author to require this.
.comment Maybe i lie here.  SUMEX's PUPFTP might require it, but we're;
.comment not connected to them yet.;


	ALIAS name					Synonyms: CWD, XCWD

The ALIAS command is used to specify a default directory for file references
on the remote system.  No special privileges are given other than those
associated with the name and password supplied by the USER command.  It
merely avoids the necessity of typing the directory name every time.  The
directory name given to the ALIAS command overrides the name given in the
USER command, but is overridden by an explicit directory name in a file

.Comment- .EXIT .QUIT .BYE .XIND .HELP;

	QUIT						Synonyms: BYE, EXIT

QUIT closes the Ethernet connection and exits to the monitor.  It does not
abort any transfer in progress and in fact this command will not be seen
until any transfer in progress has completed.  (At the moment, the best
thing to do with a hung connection is to hit <CALL> [or <control>C if you
are not on a DD or III] and typing RESET to the monitor.)

	XIND local-file

The XIND command allow PUPFTP to take commands from a file instead of the
terminal.  You may include a device name if you wish (default is DSK).  If
an error occurs, input from the file is suspended, and may be continued by
giving the XIND command without supplying a file name.

	HELP topic

The HELP command prints information about a command or other topic from the
PUPFTP manual.  For example, HELP HELP will print this paragraph.  NOTE:
The topic may not be abbreviated.  HELP with no arguments will print most of
the command names (but not the alternate names, such as EXIT as a synonym
for QUIT).

Some of the help messages are quite long.  Do the following to stop typeout
for a while:

			Stop			Start

	Non-display	<CONTROL>B (alpha)	(same)
	DM		<HOLD>			(same)

<control>X means hold down the CONTROL key (sometimes labeled CTRL) and at
the same time, hit the key marked X.

{comment}Other topics are:{;}
	Unimplemented commands

The following Internet FTP commands are not supported by the PUP FTP



.comment Strictly for HELP;
{comment}The command you have requested is not in service at this time.{;}
The following Internet FTP commands have not been implemented yet: