FTP Service User's Guide

Version 1.0.3

Last updated: December 6, 2010

Table of Contents

Overview

Installation and Configuration

FTP URL Path

Request Syntax

  • HELP
  • GET
  • PUT
  • DIR
  • VERSION
    •  Error Code Reference

    Overview

    The FTP (File Transfer Protocol) service is an external STAF service written in Java. The purpose of the FTP service is to provide client side FTP functionality that can be used to access remote FTP servers. This service only provides a few basic FTP capabilities:

    The STAF FTP service uses the FTP client support provided in Java to provide lower level FTP protocol handling via the java.net.URL class. The advantage to using this library is that it comes with Java and is public and documented. The disadvantages are that it implements RFC1738 rather than the newer RFC959 specification, and FTP URLs require that the connection close after every operation which is not very efficient for transferring many small files, and it lacks several useful features.

    Note that JavaWorld conducted a formal review of FTP client libraries that are available here.

    Installation and Configuration

    1. Install Java 1.4 or later.

    2. Install STAF 3.0.0 or later by following the installation instructions in the STAF documentation.

    3. Install the FTP service:

      Download the FtpV103.zip/tar file from Get STAF Services into a local directory (e.g. C:/STAF/services or /usr/local/staf/services) and extract it.

    4. Configure the FTP service:

      Add the following statement to your STAF.cfg file:

      SERVICE <Service Name> LIBRARY JSTAF EXECUTE <Service Jar File Name>

      where:

      Examples:

      SERVICE FTP LIBRARY JSTAF EXECUTE {STAF/Config/STAFRoot}/services/ftp/STAFFTP.jar

      SERVICE FTP LIBRARY JSTAF EXECUTE C:/STAF/services/ftp/STAFFTP.jar

      Or, you can dynamically add the FTP service using the SERVICE service's ADD SERVICE request.

    FTP URL Path

    The GET, PUT, and DIR requests have a URLPATH option whose value is a url-path for a FTP Uniform Resource Locator (URL). The FTP URL scheme is used to designate files and directories on Internet hosts accessible using the FTP protocol. The syntax for a url-path as defined by RFC 1738 is: 
      <cwd1>/<cwd2>/.../<cwdN>/<name>
    where <cwd1> through <cwdN> and <name> are (possibly encoded) strings. The <cwdx> parts may be empty. Also, the <name> part should be empty for a DIR request. The url-path is interpreted as a series of FTP commands as follows:

    Within a name or CWD component, the characters "/" and ";" are reserved and must be encoded. The components are decoded prior to their use in the FTP protocol. In particular, if the appropriate FTP sequence to access a particular file requires supplying a string containing a "/" as an argument to a CWD or RETR command, it is necessary to encode each "/".

    For example on a GET request, the url-path %2Fetc/myfile.txt is interpreted by executing "CWD /etc" and then "RETR myfile.txt". This has a different meaning from url-path etc/filefile.txt which would "CWD etc" and then "RETR myfile.txt"; the initial "CWD" might be executed relative to the default directory for the user that you used to login to the FTP host server. On the other hand, url-path /etc/myfile.txt, would "CWD " with a null argument, then "CWD etc", and then "RETR myfile.txt".

    Request Syntax

    The FTP service provides the following requests:

    HELP

    HELP displays the request options and how to use them.

    Syntax

    HELP

    Security

    This request requires at least trust level 1.

    Results

    The result buffer contains the Help messages for the request options for the FTP service.

    Examples

    GET

    The GET command downloads a file in binary mode from the remote FTP host and stores it on the STAF FTP service machine.

    Syntax

    GET HOST <Host> [PORT <Port>] URLPATH <FTP URL File Path> FILE <Name>
    [USER <Name> PASSWORD <Password>]

    HOST specifies the host name or IP address of the FTP server where the file you want to download resides. This option will resolve variables.

    PORT specifies the port number to which the TCP connection is made on the remote FTP host machine. If the port is not specified, the default port for the ftp protocol is used instead. This option will resolve variables.

    URLPATH specifies the FTP URL path to a file on the remote FTP host server that you want to download. See FTP URL Path for more information on the syntax for a FTP URL Path. This option will resolve variables.

    FILE specifies the fully-qualified name of the file on the STAF FTP service machine where you want to store the file downloaded from the remote FTP host. This option will resolve variables.

    USER specifies the user name that will be used in conjunction with specified password to login to the FTP host. The default is anonymous (to attempt an anonymous login to the FTP server). This option will resolve variables.

    PASSWORD specifies the password that will be used in conjunction with the specified user name to login to the FTP host. The default is the registered name of the STAF FTP service followed by "@" and the logical name (e.g. host name) of the machine submitting the request to the FTP service. This option will resolve variables.

    A valid user and password is required to login to the FTP host.

    Security

    This command requires trust level 4.

    Results

    On a successful return, the result buffer will be empty.

    Examples

    PUT

    The PUT command uploads a file in binary mode from the STAF FTP service machine to a remote FTP host server.

    Syntax

    PUT HOST <Host> [PORT <Port>] URLPATH <FTP URL File Path> FILE <Name>
    [USER <Name> PASSWORD <Password>]

    HOST specifies the host name or IP address of the FTP server where you want a upload a file to. This option will resolve variables.

    PORT specifies the port number to which the TCP connection is made on the remote FTP host machine. If the port is not specified, the default port for the ftp protocol is used instead. This option will resolve variables.

    URLPATH specifies the FTP URL path to a file on the remote FTP host server that you want to upload. See FTP URL Path for more information on the syntax for a FTP URL Path. This option will resolve variables.

    FILE specifies the fully-qualified name of the file on the STAF FTP service machine that you want to upload to the remote FTP host server. This option will resolve variables.

    USER specifies the user name that will be used in conjunction with specified password to login to the FTP host. The default is anonymous (to attempt an anonymous login to the FTP server). This option will resolve variables.

    PASSWORD specifies the password that will be used in conjunction with the specified user name to login to the FTP host. The default is the registered name of the STAF FTP service followed by "@" and the logical name (e.g. host name) of the machine submitting the request to the FTP service. This option will resolve variables.

    A valid user and password is required to login to the FTP host.

    Security

    This command requires trust level 4.

    Results

    On a successful return, the result buffer will be empty.

    Examples

    DIR

    The DIR command is used to list the contents of a directory on a remote FTP host server.

    Syntax

    DIR HOST <Host> [PORT <Port>] URLPATH <FTP URL Directory Path>
    [USER <User Name> PASSWORD <Password>]

    HOST specifies the host name or IP address of a FTP server. This option will resolve variables.

    PORT specifies the port number to which the TCP connection is made on the remote FTP host machine. If the port is not specified, the default port for the ftp protocol is used instead. This option will resolve variables.

    URLPATH specifies the FTP URL path to a directory on the remote FTP host server that you want to list the contents of. See FTP URL Path for more information on the syntax for a FTP URL Path. This option will resolve variables.

    USER specifies the user name that will be used in conjunction with specified password to login to the FTP host. The default is anonymous (to attempt an anonymous login to the FTP server). This option will resolve variables.

    PASSWORD specifies the password that will be used in conjunction with the specified user name to login to the FTP host. The default is the registered name of the STAF FTP service followed by "@" and the logical name (e.g. host name) of the machine submitting the request to the FTP service. This option will resolve variables.

    A valid user and password is required to login to the FTP host.

    Security

    This command requires trust level 2.

    Results

    Upon successful return, the result buffer will contain a string containing a list of the contents of the directory. The format of this string will vary depending on the operating system of your FTP host server. Because the format varies, the results are returned as is, without any attempt to parse the contents.

    Examples

    For the following examples, the FTP host server, server1.company.com, is a Linux machine.

    For the following examples, the FTP host server, os2server, is a OS/2 machine (to show how the format of the list directory results varies by operating system).

    VERSION

    VERSION displays the FTP Service version.

    Syntax

    VERSION

    Security

    This request requires at least trust level 1.

    Results

    The result is the version number of the FTP service.

    Examples

    Error Code Reference

    In addition to the common STAF return codes, the following service return codes are defined for the FTP service:
     
    Error Code Meaning  Comment 
    4001 FTP host connection error Could not open a connection to the specified FTP host. Additional information about the error is provided in the result.