There are two main types of special cases that you.may face when making connections:
• Handling poor-quality network connections
• Connecting to servers that use nontraditional ports for FfP access
Handling Poor Quality Connections
The CFFTP tag provides two attributes that can be used to compensate for poor-quality network connections:
TIMEOUT Specifies the number of seconds to wait for a connection (or operation) to complete before timing out (or giving up). By default, the timeout is set to 30 seconds.
RETRYCOUNT Specifies the number of times a connection (or operation) should be retried if it fails. By default, this is set to one retry.
Generally, if you have a poor-quality connection to a specific FTPserver, it is useful to use these two attributes in the following ways::
• Try setting the TIMEOUT value to several minutes instead of the default 30 seconds. Setting it to 300 sec~as, for instance, should be sufficient for all but the worst connections; if a conne~!ion or operation requires a TIMEOUT value greater than 300 seconds, then the performance of that connection will probably be so poor as to render the connection practically useless.
• Try setting the RETRYCOUNT slightly higher: for instance, to 2 or 3 instead of the default 1. If you find you need a higher value, you probably have a more fundamental problem that needs to be addressed, such as FfP server configuration.
Connecting to Servers That Use Nonraditional Ports
All Internet protocols, including FfP,use d,efault ports to establish connections been two machines. In the case of the FfP, this port is port 21- However, in some cases, an FIP server will be configured to use a different port from the default to establish connections. This is often done for security reasons to protect the FT1′ server from attacks from the Internet. At other times, multiple FTP servers may be running on one machine, and each will use its own unique port.
If you need to connect to a server using a nontraditional port, you need to add the PORT attribute to your CFFTP tag. For instance, to connect to a server running on port 8000, simply use PORT=8000 in your CFFTP tag.
As with any other type of network service, there are many ways in which an attempt to use the service can fail. These can range from server failure or misconfiguration to poor or nonexistent network connections to an incorrect usemame or password. The CFFTPtag provides mechanisms for catching and reacting to these errors. The
STOPONERROatRtribute enables errors to be handled in two ways:
• When the attribute is set to YES,processing stops when an error condition is .encountered, and the ColdFusion server displays a relevant error message, like the one.
• When the attribute is set to NO,processing continues and information about the error is placed into three variables, which can then be analyzed and reacted to by the code in a ColdFusion template.
Handling Errors in Your Template
If you opt to.set STOPONERROtoRNO,then you will be provided with the following variables that can be used to check whether an error has OCCUITe9and, if necessary, to react to the error:
CFFTP. Succeeded Indicates whether the CFFTPtag completed the requested task successfully. Possible values are YESor NO.
CFFTP.ErrorText Provides a text message describing the error.
CFFTP. ErrorCode Provides a numerical error code
0 Operation succeeded
1 System error (OS or FTP protocol error)
2 An Internet session could not be established
3 FTP session could not be opened
4 File transfer mode not recognized
5 Search connection could not be established
6 Invoked operation valid only during a search
7 Invalid timeout value
8 Invalid port number
9 Not enough memory to allocate system resources
10 Cannot read contents of local file
11 Cannot write to local file
12 .A Cannot open remote face for reading
13 Cannot read remote file
14 Cannot open local file for writing
15 Cannot write to remote file
16 Unknown ‘error
18 File already exists
21 Invalid retry count specified
By simply applying these variables, you can react to errors as necessary without confronting the user with ColdFusion error messages.
Here you see how the CFFTP. Succeeded variable can be used to handle FrP-related errors in a simple way. By placing the appropriate code where indicated by the comments, it is possible to display the error message as desired, or to programmatically react to the error message. In the following example, the error message is displayed for the user by using the CFFTP.ErrorText variable: