DRAFT. EXPECT SOME OMISSIONS AND INACCURACIES
-------------------------------------------------------------------------------

NFTP : New File Transfer Protocol Client Version 0.60
Copyright (C) 1994-1996 Sergey Ayukov

-------------------------------------------------------------------------------
Home page of NFTP. Check it for new versions, updates etc.

Contents

  1. Introduction
  2. Installation
  3. Quick start
  4. Usage
        o Launching NFTP
        o Logging in and out
        o Navigating remote site and local directories
        o Transferring files
  5. Keyboard commands summary
        o General keyboard commands
        o Control connection window
        o File listing (remote and local)
        o Entry fields
        o Bookmark list
        o Built-in file viewer
  6. Known bugs and limitations
  7. Troubleshooting
  8. Licensing information
  9. Registration
 10. Contacting the author

Version history
-------------------------------------------------------------------------------

INTRODUCTION

NFTP is a text-mode ftp client for OS/2. Comparing to popular ncftp, it has a
number of enhancements:

   *  remote directory view is fully scrollable with minimum keystrokes
     required;
   *  remote directory contents is cached during one session - you'll never
     have to wait for retrieving the same listing;
   *  marking files for download/upload: you don't need to type filenames at
     all;
   *  remote file viewing is more simple and intelligent;
   *  you can see client-server negotiation (even complete history during all
     run);
   *  NFTP has batch progress indicator (you see how long will take entire
     operation if more than one file was selected to transfer);
   *  file selection is simple and allows to view remote files while marking
     others to transfer;
   * one can skip files during transfer while continuing to download/upload the
     rest;
   *  sorting remote directories by name, size, date/time.

The biggest advantages over majority of PM ftp clients (like FTP-PM, sftp etc.)
are the ability to 'reget' (continue transfer after interruption), speed of
simple and effective text-mode interface, small memory requirements.

In my opinion, LW-FTP while being very elegant is useless due to big overhead
of Workplace Shell object creation/deletion (I haven't found it usable on my
486DX4/100, 32MB system with Matrox Millennium).

The drawback, however, is that NFTP isn't free as ncftp although registration
fee is only US$ 20 -- and you'll get support by e-mail at this price!
-------------------------------------------------------------------------------

INSTALLATION

  1. Requirements are
        o  OS/2 2.x or later;
        o  TCP/IP stack: IBM TCP/IP 2.0 for OS/2, OS/2 Warp Connect, OS/2 Warp
          Internet Access Kit;
        o  HPFS formatted drive to be able to download files which are not
          8.3-compliant.
        o  In addition, you also have to install emx runtime package. If you
          don't have it installed, file "emx.dll" is supplied with this version
          of NFTP. Copy it into any directory listed in your LIBPATH. The
          latest version of emx runtime support package can be found at the
          following ftp servers:
          ftp.uni-stuttgart.de:/pub/systems/os2/emx-0.9b/emxrt.zip
          ftp.sai.msu.su:/pub/os2/programming/emx-0.9b/emxrt.zip
          Instructions on installing it can be found in emxrt.zip archive.
  2. Installation.

     Unpack archive nftp*.zip into some directory and run install.cmd. After
     answering some question necessary files will be copied to the directory
     you specified and your WPS desktop will hold two new objects -- "NFTP"
     (executable) and "NFTP Manual". You probably already done that because
     you're reading that "NFTP Manual"!

     If you want to install NFTP by hand (without install.cmd), copy all files
     into the directory of your choice (eg, "d:\apps\tcpip\nftp"), load
     nftp.ini into your favourite ASCII text editor (eg, TEDIT shipped with
     Warp) and insert your e-mail address (it will be used as a password for
     anonymous logins) at the appropriate place (line

               anonymous-password="your-e-mail-address"


     ). I also suggest to decide where you will keep your bookmarks and
     transfer history and set corresponding variables accordingly. If you like
     to launch programs from desktop, create program object for NFTP. Put
     supplied nftp.mrk file into the directory which you've chosen in nftp.ini.

     install.cmd creates Workplace shell object to run NFTP. This feature can
     be useful even you die-hard command-line user. NFTP can run in a
     fullscreen session or in a VIO window. Installation script sets it to run
     in a window, and window will not be closed automatically after exit --
     this can help to diagnose problems. Turn it off when everything works as
     expected.

-------------------------------------------------------------------------------

QUICK START

After installation, run nftp.exe (from command line or WPS object). If you're
launching NFTP from WPS object created by installation script you will be asked
to enter "FTP server to log in"; simply press ENTER now. You should see list of
bookmarks on the screen. Use cursor keys to select one of them and press ENTER.
If everything is set up right, you'll see client-server negotiation and then
finally list of files and directories on the ftp server you've chosen. Hit
SPACE to view control connection window (and it is scrollable!), TAB to view
local files/directories. Return to remote directory view by pressing space/tab
another time. Move pointer with cursor keys, press ENTER on a directory to
enter it. Select files to download with INSERT or simply press F5 to transfer
single file. To upload file to server, switch to local files view (with TAB),
select file(s) and press SHIFT+F5. To view local or remote file, move pointer
to it and press F3 (of course, remote file will be downloaded first -- that
will probably take some time). Navigating in the viewer is simple and
intuitive: scroll file with cursor keys. Press F10 to log off and exit NFTP.
-------------------------------------------------------------------------------

USAGE: LAUNCHING NFTP

You often already know where the file you need right now is located. Let's
suppose, say, you want to retrieve RFC 959 from

       src.doc.ic.ac.uk:/pub/rfc/

Launch nftp in the following fashion:

       nftp  src.doc.ic.ac.uk:/pub/rfc

or

       nftp  src.doc.ic.ac.uk/pub/rfc


After logging in into src.doc.ic.ac.uk nftp will change directory for you to
/pub/rfc. You will then locate required file and download it.

The command line format for NFTP is:

      nftp [hostname[[:[port]]directory]   [userid]


"hostname" is the name of ftp server ('src.doc.ic.ac.uk' in the above example),
":" can be omitted, "directory" is remote directory ('/pub/rfc' in the above
example), "port" is port number (don't use it if you don't know what's it). If
you have an account on ftp server (i.e. you're not anonymous user), you can
specify your userid in the command line. You will be asked for a password. An
important note -- there shouldn't be any spaces between hostname and directory!
Another examples are:

      nftp private.crlf.net:7500/users    (nonstandard port)
      nftp ftp/pub                        (domain suffix omitted)
      nftp 128.128.128.128:/mydir         (IP number instead of host name)
      nftp lnfm1.sai.msu.su/home/asv asv  (login with explicit directory)


Specifying directories in a command line is a pretty useful feature: when
you've found some reference, paste it directly into the command line (e.g.,
File Commander/2 1.4 allows this) and you'll get right into the place without
typing anything except 'Ctrl-Ins' and 'Shift-Ins'! Note that it's impossible to
specify filename on the command line -- use directory name, not file name (i.e.
/pub/rfc instead of pub/rfc/rfc959.txt.gz in the above example).

NFTP will try to use any text mode you have set before starting it. Modes with
80 columns work rather good, but do not expect this from 132-col or other
modes.
-------------------------------------------------------------------------------

USAGE: LOGGING IN AND OUT

NFTP has several ways to choose ftp server. First of all, you can specify it on
the command line as an argument (see previous chapter, "USAGE: LAUNCHING
NFTP"). Second, you can put server's hostname into the bookmark list if you
frequent this site. Third, you can open it manually -- press Ctrl-L (for
anonymous login) or Ctrl-N (for named login). to be continued
-------------------------------------------------------------------------------

USAGE: NAVIGATING REMOTE SITE AND LOCAL DIRECTORIES

-------------------------------------------------------------------------------

USAGE: TRANSFERRING FILES

-------------------------------------------------------------------------------

KEYBOARD COMMANDS SUMMARY

All interaction with NFTP is keyboard-based; there's no mouse support (and I am
not going to implement it -- at least now). This approach is somewhat tough for
novice user, but after some learning it gives the best results in terms of
usability and interaction speed. Here is the list of keystrokes ("hot keys");
it's divided into several sections each pertaining to specific mode of
operation or action classification.

                       GENERAL KEYBOARD COMMANDS
   Key                              Meaning
 Shift+F1 program information and general keyboard commands
    F1    brings context sensitive help
   F10    logoff from site and quit NFTP
  Ctrl-K  logoff from site
  Ctrl-B  open bookmark list and log to site from it
  Ctrl-L  login as anonymous into new site
  Ctrl-N  login with userid/password into new site
  Ctrl-V  display version information
  Ctrl-A  toggle state of autocontrol flag
  Ctrl-T  toggle ASCII/BINARY mode
  Ctrl-D  redraw screen (do not re-read remote dir)
  Alt-N   send NO OPERATION command (verify connection aliveness)
          use/inhibit NLST with flags (default is on). Some servers
  Alt-F   do not like NLST -lLa. Try if you see strange messages from
          server when retrieving directory listing. NOT RECOMMENDED.
Note that these commands are available almost always.
However, in many modes other keystrokes are also in play.

                   CONTROL CONNECTION WINDOW
    Key                           Meaning
 arrow keys move viewpoint
    Esc     bring you back to the end of history (same as End)
   Space    switches to directory view
   Alt-Q    send any string to server verbatim (quote)
   Alt-C    change to arbitrary directory

                      FILE LISTING VIEW (REMOTE OR LOCAL)
    Key                                  Meaning
                                  Navigating
 arrow keys move cursor around
   Ctrl-\   change to root directory
 Ctrl-PgUp  goto the directory level higher ("cd ..")
 Ctrl-PgDn  chdir to directory under cursor
   Enter    same as above
   Alt-C    change to arbitrary directory
   Space    switch to control connection
     F2     select drive letter -- local view only
                             Sorting file listing
  Ctrl-F3   sort directory by name, dirs first
  Ctrl-F5   sort directory by time, then name, dirs first
  Ctrl-F6   sort directory by size, then name, dirs first
  Ctrl-F7   remove sorting, return to original state
  Ctrl-F8   reverse current sort order
                               Marking/unmarking
 Ctrl-num+  mark all files in current directory
 Ctrl-num-  unmark all files in current directory
   Insert   mark/unmark file under cursor. Directory cannot be marked
                              Transferring files

     F5     download file under cursor or marked files (if any) -- remote view
            only

  Shift+F5  upload file under cursor or marked files (if any) -- local view
            only
                                 Viewing files
     F3     view file under cursor, use fast internal viewer
   Alt-F3   view file under cursor, use external viewer
                      Creating/deleting files/directories
     F7     make directory (you have to have permissions on remote)
     F8     delete file or directory under cursor
   Ctrl-R   re-read directory (refresh file list)
                                 Miscellaneous
     F4     save this place as a bookmark

                         ENTRY FIELDS
          Key                          Meaning
       Esc/Enter        abandon/confirm
 Left, Right, Home, End move cursor around
     Tab, Shift-Tab     move to next/previous field (if any)
     Del, Backspace     delete characters
Pressing any keys different from Left, Right, Home, End will clear the initial
string.
Password is not displayed (masked by asterisks).

              BOOKMARK LIST
    Key               Meaning
 arrow keys move cursor
   Enter    select bookmark
    Esc     abort (leave bookmark list)
    Del     delete bookmark
   Insert   create new bookmark

                         BUILT-IN FILE VIEWER
       Key                             Meaning
   arrow keys    scroll (note that you can scroll horizontally also)
 Ctrl-Left/Right scroll by 10 symbols horizontally
       Esc       exit viewer
-------------------------------------------------------------------------------

KNOWN BUGS AND LIMITATIONS

  1.  Only UNIX ftp servers and ftp servers with UNIX-like output are
     supported. E.g., Penguin FTPD is supported while Neologic Netsuite ftpd
     isn't. Other unsupported ftp servers include Windows NT ftpd, VMS servers,
     IBM TCP/IP for OS/2 ftpd. Most ftp servers in the world use wu-ftpd as
     their server software, so you shouldn't experience this trouble too often.
     Support for other servers will be added later.
  2.  When running with 'debug=1', your password will be recorded in debug
     tracefile -- beware!
  3.  When running with 'debug=1', run nftp off HPFS partition - debug file has
     long filename with two dots.
  4.  Performance with 10 Mb/sec Ethernet local transfers isn't spectacular.
     The programs wasn't tuned for this. I usually get about 250 Kb/sec on
     files large enough (say, 1-2 megs).
  5.  Error handling is still pretty primitive

-------------------------------------------------------------------------------

TROUBLESHOOTING

Q: nftp says "emx not found".
     A: You don't have emx runtime package installed. Read INSTALLATION section
     again.
Q: nftp crashes, saying "core dumped".
     A: If you can repeat situation, please send me details of your setup
     (nftp.ini, nftp.mrk, keystrokes which caused fault).

-------------------------------------------------------------------------------

LICENSING INFORMATION

NFTP comes without any warranty, express or implied.

NFTP is copyrighted by Sergey Ayukov.
-------------------------------------------------------------------------------

REGISTRATION

Registration fee will be US$ 20. For people living in Former Soviet countries
registration will cost only one postcard. For this price you'll get free
updates (i.e. all future versions of NFTP) and support from author by e-mail.
If you think that price is too high for this small utility, simply don't use
NFTP.

Nothing else here at the moment. The program isn't complete, so there's nothing
yet to pay for. Version 0.60 is free but time-limited (it will work until July
1, 1996).
-------------------------------------------------------------------------------

CONTACTING THE AUTHOR

You can reach me at asv@sai.msu.su.

Where to find new versions:

  1. anonymous ftp: ftp.sai.msu.su:/pub/os2/internet/ftp/
  2.  WWW: http://crydee.sai.msu.su/nftp
  3.  ftp-os2.cdrom.com, hobbes.nmsu.edu, ftp.leo.org

Note that first site is managed by myself so it always contains the latest
version while Hobbes and cdrom archives often become outdated.

Sorry for my English. I will gladly accept any corrections to this short
manual.
-------------------------------------------------------------------------------
Sergey Ayukov (asv@sai.msu.su)
-------------------------------------------------------------------------------

Version history

Version 0.1 (preview)
     First usable version. Used FTPAPI calls. Very slow; control connection
     messages cannot be seen. Wasn't exposed to public, although available.
Version 0.2 (preview)
     Got rid of FTPAPI. Full-scale socket programming of ftp control connection
     and data transfers. Introduced bookmarks.
Version 0.3 (preview)
     Never showed to public. The last version compiled with IBM CSet++. See
     0.4.
Version 0.4 (preview)
     Nearly the same as 0.3, but compiled with emx 0.9a + gcc 2.6.3. A handful
     of new features:
        o logging in and out without restarting entire program;
        o passworded entries in bookmark file;
        o quick directory change: if you know where to go, you won't need to
          traverse all intermediate dirs;
        o various bug fixes.
Version 0.5 (preview; close the beta stage)
     Bugfixes plus
        o ability to work in any 80xXX mode (25 <= XX)
        o online context sensitive help (press F1, Shift+F1)
        o code reorganization
        o some errors are handled (mostly login errors)
        o directory sorting by name, size, date/time
        o create directory on the remote, remove file(s) on the remote
        o preserving date/time of files downloaded
        o fast built-in file viewer
        o ability to invoke any ftp server command
        o better socket selecting scheme
     Will not work after 31 Dec 1995
Version 0.51 (preview; close the beta stage)
     I am sorry for releasing 0.5 so full of bugs... There was a lot of...
        o fixed couple of awful bugs (memory corruption) resulting in core
          dumps etc;
        o got rid of malloc (goodbye, flat memory space! welcome, 32-bit
          segments and memory protection!)
        o you can set nonstandard port in nftp.ini
Version 0.52
     Same as 0.51 but without 31 Dec limitation. Only to be distributed by SAMS
     Publishing.
Version 0.53
     Nearly the same as 0.52 but limited to 30 March 1996.
Version 0.60
     I am a bit short on time; 0.53 expires today, so some new features weren't
     tested much. Bugfixes and small improvements plus:
        o reget (restarting transfers)
        o uploading
        o IP numbers can be used instead of host names
        o "Q" and "S" work! you can skip files during transfer or stop
          download/upload
        o more intelligent networking (fixes some problems with dynamic IP)
        o changing local directory, viewing list of local files etc.
        o ability to specify arbitrary port (not in bookmarks though)
        o new bookmarks can be created with Insert key
        o installation program
        o documentation

Planned for next version:

   * remappable keys
   * more error recovery
   * more multithreading (view file while downloading etc)
   * improved installation/setup routines
   * bookmarks in the form of standard URLs
   * something else I haven't realized yet

Anyone needs PM version?
-------------------------------------------------------------------------------
Last updated: 2:54pm on 3/31/96
asv@sai.msu.su
