home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 35 Internet / 35-Internet.zip / rxftp.zip / rxftp.doc < prev    next >
Text File  |  1993-09-09  |  9KB  |  231 lines
  1.  
  2.  
  3.                                  rxFtp
  4.  
  5.          Rexx Function Package for TCP/IP FTP for OS/2 2.0
  6.  
  7.                            by Patrick Mueller
  8.  
  9.    (c) Copyright International Business Machines Corporation 1993.
  10.    All rights Reserved.
  11.  
  12. ----------------------------------------------------------------------
  13. what is rxFtp?
  14. ----------------------------------------------------------------------
  15.  
  16. rxFtp is a REXX function package providing access to the OS/2
  17. TCP/IP FTP API as provided by the IBM TCP/IP product, version
  18. 1.2.1.
  19.  
  20. The function package assumes you know how to use the FTP program.
  21. The function names in the package closely resemble FTP subcommands.
  22.  
  23. This function package requires the OS/2 TCP/IP product, version 1.2.1
  24. or higher. A specific DLL for the OS/2 TCP/IP product, version 2.0, is
  25. included.
  26.  
  27. ----------------------------------------------------------------------
  28. installation and removal
  29. ----------------------------------------------------------------------
  30.  
  31. The rxFtp rexx function package is contained in the file rxFtp.dll.
  32. This file needs to be placed in a directory along your LIBPATH.  To get
  33. access to the functions in the rxFtp function package, execute the
  34. following rexx code:
  35.  
  36.    rc = RxFuncAdd("FtpLoadFuncs","rxFtp","FtpLoadFuncs")
  37.    rc = FtpLoadFuncs()
  38.  
  39. If you want to use the 32-bit FTP functions available in TCP/IP for OS/2
  40. Version 2.0, rename the "rxftp32.dll" file to "rxftp.dll".
  41.  
  42. You may not use both the 16-bit and 32-bit versions at the same time as
  43. they have the same function names.
  44.  
  45. To unload the DLL, you should first call the FtpDropFuncs()
  46. function, then exit all CMD.EXE shells.  After exiting all the
  47. command shells, the DLL will be dropped by OS/2 and can be deleted
  48. or replaced.
  49.  
  50. ----------------------------------------------------------------------
  51. Parameters and Return Values
  52. ----------------------------------------------------------------------
  53.  
  54. ----------------------------------------------------------------------
  55. Return values
  56. ----------------------------------------------------------------------
  57.  
  58.   o Set errors
  59.  
  60.     The following functions return Set error codes:
  61.  
  62.        FtpSetUser
  63.        FtpSetBinary
  64.  
  65.     The return code is 1 if the string passed in are valid, 0 if not.
  66.     FtpSetBinary() should be passed an abbreviation of "BINARY" or
  67.     "ASCII" (thus, "b", "as", "BIN", etc).
  68.  
  69.  
  70.   o FTP errors
  71.  
  72.     The rest of the functions (all the functions but the Set functions)
  73.     return ftp error conditions.
  74.  
  75.     It will have one of the following values (or a numeric value if the
  76.     number isn't one of these documented values):
  77.  
  78.       "0"              - successful call
  79.       "-1"             - Error during FTP function call
  80.  
  81.     If the function returns a "-1" for a return code, the variable FTPERRNO
  82.     will be set to one of the following values:
  83.  
  84.       "FTPSERVICE"     - unknown service
  85.       "FTPHOST"        - unknown host
  86.       "FTPSOCKET"      - unable to obtain socket
  87.       "FTPCONNECT"     - unable to connect to server
  88.       "FTPLOGIN"       - login failed
  89.       "FTPABORT"       - transfer aborted
  90.       "FTPLOCALFILE"   - problem openning local file
  91.       "FTPDATACONN"    - problem initializing data connection
  92.       "FTPCOMMAND"     - command failed
  93.       "FTPPROXYTHIRD"  - proxy server does not support third party transfers
  94.       "FTPNOPRIMARY"   - no primary connection for proxy transfer
  95.  
  96. ----------------------------------------------------------------------
  97. Functions Reference
  98. ----------------------------------------------------------------------
  99.  
  100.    -------------------------------------------------------------------
  101.    FtpLoadFuncs
  102.    -------------------------------------------------------------------
  103.  
  104.       rc = FtpLoadFuncs(quiet)
  105.  
  106.       Loads all the functions in the rxFtp package.
  107.  
  108.       If ANY parameters are passed to this function, it will bypass
  109.       the program/author/copyright information normally displayed.
  110.       All parameters are ignored (except to determine whether or not
  111.       to bypass displaying the information).
  112.  
  113.    -------------------------------------------------------------------
  114.    FtpDropFuncs
  115.    -------------------------------------------------------------------
  116.  
  117.       rc = FtpDropFuncs()
  118.  
  119.       Drops all the functions in the rxFtp package.
  120.  
  121.    -------------------------------------------------------------------
  122.    FtpVersion
  123.    -------------------------------------------------------------------
  124.  
  125.       rc = FtpVersion(variable)
  126.  
  127.       Returns the version of RxFtp that you are running in the variable
  128.       "variable".
  129.  
  130.    -------------------------------------------------------------------
  131.    Set Functions
  132.    -------------------------------------------------------------------
  133.    FtpSetUser(host,userid,password<,account>)
  134.    FtpSetBinary("Binary" | "Ascii")
  135.  
  136.       FtpSetUser() sets the host, userid, and password for the
  137.       remote host that most of the other functions require.
  138.       FtpSetBinary() sets the default text translation
  139.       for functions that can use this.  This Binary or Ascii setting
  140.       can be overriden by any function that takes it as an option
  141.       parameter.
  142.  
  143.       Note that the host, userid, password, and account are retained
  144.       during the life of the process.  If you are using the RxFtp
  145.       package within a .CMD file run the OS/2 prompt, this means the
  146.       life of the CMD.EXE process.  You may want to 'blank' out the
  147.       password (at least) when you are finished, to prevent unauthorized
  148.       access to a host you previously used.
  149.  
  150.    -------------------------------------------------------------------
  151.    File Functions
  152.    -------------------------------------------------------------------
  153.    FtpAppend(localFile,remoteFile[,"Binary" | "Ascii"])
  154.    FtpDelete(remoteFile)
  155.    FtpGet(localFile,remoteFile[,"Binary" | "Ascii"])
  156.    FtpPut(localFile,remoteFile[,"Binary" | "Ascii"])
  157.    FtpPutUnique(localFile,remoteFile[,"Binary" | "Ascii"])
  158.    FtpRename(oldFile,newFile)
  159.  
  160.       These functions perform work on files.  The function should
  161.       be obvious, except for FtpPutUnique() which insures the remote
  162.       file created is unique, and does not overwrite the name of a
  163.       file which already exists.
  164.  
  165.    -------------------------------------------------------------------
  166.    Directory List Functions
  167.    -------------------------------------------------------------------
  168.    FtpLs(pattern,stem)
  169.    FtpDir(pattern,stem)
  170.  
  171.       These functions return directory list information in the
  172.       stemmed variable passed in.  FtpLs() returns 'short' form;
  173.       FtpDir() returns 'long' form.  The Stem value should be
  174.       a string with a "." at the end.  When the function completes,
  175.       the variable stem || ".0" will be set to the number of stem
  176.       variables returned, which are set in variables stem || ".1",
  177.       stem || ".2", etc.
  178.  
  179.    -------------------------------------------------------------------
  180.    Directory Functions
  181.    -------------------------------------------------------------------
  182.    FtpPwd(variable)
  183.    FtpChDir(directory)
  184.    FtpMkDir(directory)
  185.    FtpRmDir(directory)
  186.  
  187.       These functions work with directories.  The function should be
  188.       obvious.  FtpPwd() returns the name of the current directory on
  189.       the remote host if no error occurred in the variable "variable"
  190.  
  191.    -------------------------------------------------------------------
  192.    Logoff Function
  193.    -------------------------------------------------------------------
  194.    FtpLogoff()
  195.  
  196.       This function should be called to terminate all ftp sessions.
  197.  
  198.    -------------------------------------------------------------------
  199.    Miscellaneous Functions
  200.    -------------------------------------------------------------------
  201.    FtpQuote(quote)
  202.    FtpSite(site)
  203.    FtpSys(variable)
  204.  
  205.        FtpQuote() and FtpSite() pass information to server as the
  206.        "site" and "quote" commands do.
  207.  
  208.        FtpSys() returns the name of the operating system that server
  209.        is running if no error occurred in the variable "variable"
  210.  
  211.    -------------------------------------------------------------------
  212.    Proxy Function
  213.    -------------------------------------------------------------------
  214.    FtpProxy(host,userid,password,account,pFile,rFile[,"Binary" | "Ascii"])
  215.  
  216.        FtpProxy() copies a file from the named host/userid/password/account
  217.        (account may be empty) to the host specified with the Set functions.
  218.        pFile is name of the file on the named host/userid/password/account,
  219.        rFile is the file on the host specified with the Set functions.
  220.  
  221. ----------------------------------------------------------------------
  222. Utilities Provided
  223. ----------------------------------------------------------------------
  224.  
  225.    miniftp.cmd
  226.    ------------
  227.  
  228.    A test program demonstrating the use of the rxFtp package.
  229.  
  230.  
  231.