@comment Tell Emacs to use -*-texinfo-*- mode
@comment $Id: transfer.tex,v 2.3 91/09/01 23:04:52 royce Exp $

@node File Transfers, Miscellaneous, Shells vs. the Desktop, Top
@chapter File Transfers
@cindex File transfers

As you've probably guessed by now, Fnordadel is oriented
towards the discussion type of @sc{bbs}ing (i.e.: message oriented rather than
file transfer oriented).  Still, Fnordadel prides itself on being
flexible, and a decent level of file transfer features is supported.

@node File Directories, Protocols, File Transfers, File Transfers
@section File Directories
@cindex File directories
@cindex Directories

Fnordadel permits a room to have attached to it a directory on the storage
device; users may be able to upload files to this directory, or download
files from this directory, or both.  (These attributes are changed by editing
the room; see @ref{Sysop room-editing commands}.)  Users may also read the
contents of the directory in either a short format (@code{.R(ead) D(irectory)})
or a long format (@code{.R(ead) E(xtended-directory)}).  The short form
prints out the filenames and sizes, whereas the long form adds the date stamp
of the files and an optional description.
@xref{Multi-key file reading commands}.

The file descriptions are kept in each directory in a
file called @file{.fdr}.  This file is added to whenever a user uploads a
file to the directory, and it is also editable with a text editor.
It consists of lines of the form
@example
<@var{filename}> <@var{description}>
@end example
@noindent
where the two fields are separated by whitespace (spaces and/or tabs).
The lines must be alphabetically sorted; that is, the line for
@file{foobar.zoo} must come after the line for @file{blort.lzh} and so on.

If you add files to a directory manually (by copying
them in using a shell or the Desktop) then the @file{.fdr} file will,
obviously, not be updated.  You may want to do so manually so
as to provide some sort of help for your downloading-mad users.

@node Protocols, The File Browser, File Directories, File Transfers
@section Protocols

Fnordadel supports the following protocols for file
transfers:
@cindex File transfer protocols
@cindex Protocols
@cindex Transfer protocols
@table @asis
@item Xmodem
The standard 128-byte packet prototol.  Invoke
this protocol using @code{.R(ead) X(modem) F(ile) @dots{}}
or @code{.E(nter) X(modem) F(ile) @dots{}}.

@item Ymodem
Xmodem with 1K (1024 byte) packets.  Yes, we
know this is a misnomer, but it's historical.
(Translation: ``We didn't put it in, someone
else did@dots{}'')  Invoke this protocol using
@code{.R(ead) Y(modem) F(ile) @dots{}} or @code{.E(nter)
Y(modem) F(ile) @dots{}}.

@item Ymodem batch
This is true Ymodem---1K packets with
batch transfers (i.e., you can send more than
one file at once, and the software keeps track
of filenames and stuff).  Fnordadel supports
this for general use in downloads only; it
will do Ymodem batch uploads only when a user
with Sysop or Co-Sysop status is logged in.  Invoke this
protocol using @code{.R(ead) Y(modem) B(atch file) @dots{}}
or @code{.E(nter) Y(modem) B(atch file) @dots{}}.

@item WXmodem
This is a windowed packet protocol which is
not widely used, and the implementation residing
in Fnordadel is known to be weak; we've never
even touched it.  We don't even have a terminal
program which supports it, so we can't test it
except with itself, which is hardly rigorous.
Maybe try it if you can.  Invoke this protocol
by using @code{.R(ead) W(Xmodem) @dots{}} or @code{.E(nter)
W(Xmodem) @dots{}}.

@item Vanilla @sc{ascii}
This is a straight @sc{ascii} transfer terminated with two @samp{^X}
(@samp{Ctrl-X}) characters.  It is useful for modems with their own error
correction, or for other times when you want a plain transfer (say, for
uploading a message directly from the editor of a terminal package, or
some such.)  It is invoked with @code{.R(ead) V(anilla) @dots{}} or
@code{.E(nter) V(anilla) @dots{}}.

@item @sc{ascii}
This is a straight @sc{ascii} transfer with no error
checking or distinguishing features.  It just
blorts out the file.  This ``protocol'' is unlike the
others in that it cannot be specifically invoked in
a command, and it is available only with @code{.R(ead)};
invoke it by using @code{.R(ead) F(ile)}.
@end table

You may also enable any number of additional file transfer
protocols using doors; see @ref{Protocol doors}.

The actual mechanism for file transfers is documented in this manual in
@ref{Multi-key file entry commands}, and @ref{Multi-key file reading commands},
among other places, and in the online help files.  Note that the transfer
protocols can be used to transfer more than just files; in particular, they
can be used to upload messages into and download messages from the message
base.

@node The File Browser,  , Protocols, File Transfers
@section The File Browser
@cindex Browser, file
@cindex File browser

The Fnordadel file browser is an addition not found on any other
Citadel variants that we know of.  If offers users a way to step through the
list of files in a directory room one at a time, and do things with them.
Many other types of @sc{bbs}es have such functionality, and we decided it was
time for a Citadel to be able to claim the same thing, for those who want to
do file transfer stuff as well as discussion.

Because we try to make commands consistent, the file browser is
called up in the same fashion that the one-at-a-time message reading option
is invoked, namely using the @code{M(ore)} modifier:
@example
.R(ead) M(ore) D(irectory) [@var{optional file mask}]
.R(ead) M(ore) E(xtended directory) [@var{optional file mask}]
@end example
@noindent
Both of the above commands produce exactly the same result, which is
to display the first file in the directory that matches the given file mask
(if there is one).  Following the file name display (which looks just like
the entry for that file in the normal @code{.R(ead) E(xtended directory)}
listing),
the browser prompt is displayed.  Here's what you might see:
@example
callbaud.sys    2588 | 91Apr28 | Highly esoteric BBS usage stats.

Browse cmd:
@end example
Note that other command options might be useful in conjunction with
the browser mode option @code{M(ore)}.  Two good examples are
@code{-(before)} and @code{+(after)}.
These commands cause the
system to ask for a date in standard Citadel format (e.g. @samp{91May20},
or just
@samp{May20} to assume the current year).  You can also just hit @samp{<CR>}
to tell the
system to use the date of your last call.  Fnordadel then merrily crunches
through the directory and only lists those files before or after the date.

Hitting @samp{?} at the browser prompt produces the following list of
commands:
@cindex Browser menu
@example
[A]- view this entry again
[B]ackup to previous file
[C]lear batch list
[H]eader listing of ARC, LZH, ZOO file
[M]ark this file for batch transfer
[N]ext file (also <SPACE>, <CR>)
[U]nmark a file
[V]iew batch list
e[X]it the browser (also [Q]uit, [S]top)
@end example

@table @code
@item [A]- view this entry again
This command will redisplay the current file description, in case it
was somehow removed from view and the user forgot what it was.

@item [B]ackup to previous file
This command will back up one entry and redisplay the preceeding file
description, if there is one.

@item [C]lear batch list
This command wipes out the entire batch list.  There is
currently no way to take out just one file name from the list; if
you really don't want to transfer it, you'll have to @code{[C]lear} the
list and start over.

@item [H]eader listing of ARC, LZH, ZOO file
This command is quite useful for helping decide whether a given archive
file is worth downloading.  If the description isn't enough, this will
show the archive's table of contents, like the @samp{.RH} command would.
The @samp{.arc} file format is supported internally with Fnordadel, but
for @samp{.lzh} and @samp{.zoo} files (or any others) to work, the Sysop
must have set up some doors.  @xref{Archiver doors}.

@item [M]ark this file for batch transfer
This command adds the currently-displayed file to an internal
list of files to be batch downloaded by the user, presumably using
the @code{.R(ead) Y(modem) B(atch file)} command.  After a file is marked,
the total size of all marked files is shown.  The browser will not permit
a user to mark more files than the daily download limit allows.

Normally, the @samp{.RYB} command
needs the user to enter a file mask indicating which files are to be
transferred.  However, if there is a batch list in existence, the
user can just hit @samp{<CR>} after entering @samp{.RYB},
and the system will prompt
for the transfer of all files in the batch list.  The batch list will
not stop the user from explicitly transferring other files if desired,
by doing @samp{.RYB @var{filename}}.  @xref{Multi-key file reading commands}.

The batch list may contain a collection of files from any
series of directory rooms.  The user can go from room to room, adding
interesting files to the list, until he has everything wanted.  Then
one massive @samp{.RYB <@samp{<CR>}>} command will take them all.
(Assuming the user has enough download credit available, of course.  See
the @code{download}
@vindex download
parameter in @file{ctdlcnfg.doc}, and @ref{Daily download limit}.)

@item [N]ext file (also <SPACE>, <CR>)
This command advances to the next file that matches the given
file mask, if any.  If there are no files remaining, the browser
exits and the user is returned to the room prompt.  Any marked files
may now be transferred.  To view the current batch list, it is
necessary to re-enter the browser.

@item [U]nmark a file
This command allows a user to unmark an individual file.  The user will
be prompted for the file name to unmark, and if it is present in the batch
list, it will be removed.

@item [V]iew batch list
The @code{[V]iew} command does just that, allows the user to view
the current batch list.  There are three columns of information
(source room, file name and file size), followed by the total size of
all marked files.  Here's an example:
@example
RT stats                callbaud.sys    2588
Foo room                bigfile.foo     100000
Total marked file size = 102588 bytes.
@end example

@item e[X]it the browser (also [Q]uit, [S]top)
this command immediately exits the browser and returns the
user to the room prompt.
@end table