IBM Network Card FTP Adapter User Manual

HP NonStop Data Transformation Engine  
FTP Adapter Reference Guide  
Abstract  
This manual provides information about using the HP NonStopData Transformation  
Engine (NonStop DTE) FTP adapter on the NonStop server.  
Product Version  
NonStop Data Transformation Engine 6.7.1  
Version Updates (RVUs)  
N/A  
Part Number  
528264-001  
Published  
June 2004  
 
Contents  
About This Document  
Related References........................................................................................... 5  
Chapter 1 - FTP Adapter  
Overview ....................................................................................................... 6  
System Requirements........................................................................................ 6  
About Sockets ............................................................................................ 7  
Access to International VANs ............................................................................... 7  
Chapter 2 - Command Alias  
Chapter 3 - FTP Commands  
List of Commands............................................................................................. 9  
Account (-AC or -ACCT)................................................................................ 11  
Audit (-A or -AUDIT).................................................................................... 11  
Certificate Authority (-CA)............................................................................ 12  
Client Certificate (-CERT)............................................................................. 12  
Client Certificate Password (-CPASS) ............................................................... 12  
Code Page Local (-CPL)................................................................................ 13  
Code Page Remote (-CPR)............................................................................. 13  
Firewall Connection Method URL (-FW or -FIREWALL) ........................................... 14  
Adapter Behavior when -FIREWALL Command Present .......................................... 16  
URL Syntax............................................................................................... 17  
FTP URL (-URL).......................................................................................... 19  
Ignore (-I or -IGNORE).................................................................................. 21  
Keep Server (-KS)....................................................................................... 21  
List Option (-LS)......................................................................................... 22  
Make Directory (-MKD)................................................................................. 23  
Passive Mode (-PV or -PASV).......................................................................... 23  
Port Mode (-PT or -PORT) ............................................................................. 23  
Private Key (-PKEY) .................................................................................... 24  
Private Key Password (-KPASS)....................................................................... 24  
Quantity (-QTY)......................................................................................... 24  
Site (-SITE)............................................................................................... 25  
SSL Encryption Strength (-STR)....................................................................... 26  
SSL Protocol (-SPROTO)................................................................................ 26  
Stage (-STG or -STAGE)................................................................................ 26  
System (-SYS)............................................................................................ 27  
Trace (-T or -TRACE)................................................................................... 28  
Chapter 4 - Syntax Summary  
Data Sources..................................................................................................29  
Data Targets..................................................................................................30  
Using FTP Adapter Commands.............................................................................31  
Examples................................................................................................. 31  
URL Syntax....................................................................................................31  
URL Encoding.................................................................................................33  
F T P A d a p t e r R e f e r e n c e G u i d e  
3
 
Contents  
Chapter 5 - Troubleshooting  
Adapter Audit Log ...........................................................................................34  
Adapter Trace File...........................................................................................35  
Appendix A - Return Codes and Error Messages  
Messages.......................................................................................................37  
Index  
F T P A d a p t e r R e f e r e n c e G u i d e  
4
 
About This Document  
This document contains detailed information about using the FTP Adapter. For  
general information regarding using any of the Mercator Resource adapters, see  
the Resource Adapters Reference Guide.  
This document assumes that the reader knows the Windows environment, has  
used the Mercator Design Studio, and understands words such as mapping, type  
trees, and other basic Mercator terminology.  
Related References  
For more information about all products or about topics frequently discussed in  
this document, refer to the Mercator Online Library or the SDK Online Library.  
Related Reference  
Description  
Resource Adapters Reference Guide  
Using resource adapters as map sources  
and map targets in general. Specific  
information for each adapter can be found  
in their respective reference guide.  
F T P A d a p t e r R e f e r e n c e G u i d e  
5
 
Chapter 1 - FTP Adapter  
This chapter introduces the File Transfer Protocol (FTP) adapter. You can use this  
adapter with a Command Server, Event Server, Platform API, or map in a map  
rule.  
Overview  
Use the FTP adapter to transport data. When source data arrives at its target, it  
often must be transformed into a different format in order for a receiving  
application to use it successfully.  
If you have the Command Server, Event Server, or Platform API on one platform,  
you can use the FTP adapter to retrieve or send data to another platform.  
Note The adapter can connect to any FTP server that complies with RFC 959. To take  
full advantage of the adapter’s capabilities, the server should conform to RFC  
1123. Those servers that are noncompliant may generate errors in the adapter.  
System Requirements  
The minimum system requirements and operating system requirements for the  
FTP adapter are detailed in the release notes. It is assumed that a Command  
Server has already been installed on the computer where the adapter is to be  
installed for run-time purposes.  
See the Getting Started book for details about the installation program.  
In addition, the following are additional requirements for installing and running the  
FTP adapter:  
The FTP adapter must be installed in the same directory as the Command  
Server for your specific platform.  
TCP/IP must be installed on the machine where the adapter is installed.  
The machine where the FTP adapter is installed must be able to access the  
desired FTP servers over a TCP/IP network.  
F T P A d a p t e r R e f e r e n c e G u i d e  
6
 
Chapter 1 - FTP Adapter  
Access to International VANs  
About Sockets  
Windows (NT) or BSD (UNIX) Sockets must be installed on the client computer.  
The Sockets installation must support TCP/IP.  
The client computer must be able to access an appropriate server. Test this as  
follows:  
! telnet target-ip 25  
! telnet target-ip 110  
(to test a SMTP e-mail target)  
(to test a POP3 e-mail source)  
where target-ipis the server IP address. If the test is successful, you receive a  
welcome message from the server. Shut down the session by typing QUIT and  
pressing Enter.  
Note You might not be able to see what you are typing on the screen.  
Access to International VANs  
Access to international VANs is available when using the FTP adapter. The FTP  
adapter can be used rather than the VAN adapter when communicating with a  
Commerce Manager post office. For detailed configuration information, see the  
Partner Manager Reference Guide.  
F T P A d a p t e r R e f e r e n c e G u i d e  
7
 
Chapter 2 - Command Alias  
Specify adapter commands by using a command string on the command line or by  
creating a command file that contains adapter commands. The command syntax  
is:  
-IA[alias]card_num  
-OA[alias]card_num  
In the command syntax, -IAis the Input Source Override execution command  
and -OAis the Output Target Override execution command, alias is the adapter  
alias, and card_num is the number of the map card. The FTP adapter alias and  
corresponding execution commands are listed below.  
Adapter  
Alias  
As Input  
As Output  
FTP  
-IAFTPcard_num  
-OAFTPcard_num  
FTP  
F T P A d a p t e r R e f e r e n c e G u i d e  
8
 
Chapter 3 - FTP Commands  
This chapter describes the functions and use of the FTP commands and their  
options.  
List of Commands  
The following table lists valid commands for the FTP adapter, the command  
syntax, and whether the command is supported () for use with data sources,  
targets, or both.  
Name  
Syntax  
Source Target  
-ACCT account_id  
-AUDIT[+][S] [full_path]  
Account  
Audit  
-CA filename  
Certificate Authority  
Note Only available if Security Option is  
installed.  
-CERT filename  
Client Certificate  
Note Only available if Security Option is  
installed.  
-CPASS password  
Client Certificate  
Password  
Note Only available if Security Option is  
installed.  
-CPL code_page_name  
Code Page Local  
(OS/390, z/OS only)  
-CPR code_page_name  
Code Page Remote  
(OS/390, z/OS only)  
-FIREWALL FTP://firewall_URL  
Firewall Connection  
Method URL  
-URL FTP://ftp_URL  
FTP URL  
Ignore  
-IGNOREerror_code[:error_code…]  
F T P A d a p t e r R e f e r e n c e G u i d e  
9
 
Chapter 3 - FTP Commands  
List of Commands  
Name  
Syntax  
Source Target  
-KS  
Keep Server  
List Option  
Make Directory  
Passive Mode  
Port Mode  
-LS sort_type  
-MKD  
-PASV  
-PORT  
-PKEY filename  
Private Key  
Note Only available if Security Option is  
installed.  
-KPASS password  
Private Key Password  
Note Only available if Security Option is  
installed.  
-QTY number  
Quantity  
Site  
-SITE command_text  
-STR {WEAK|STRONG|ANY}  
SSL Encryption  
Strength  
Note Only available if Security Option is  
installed.  
-SPROTO  
{SSLv2|SSLv3|SSLv23|TLSv1}  
SSL Protocol  
Note Only available if Security Option is  
installed.  
-STAGE [file_name]  
Stage  
System  
Trace  
-SYS {WIN32|UNIX|UNKNOWN}  
-TRACE[+][S|V] [full_path]  
F T P A d a p t e r R e f e r e n c e G u i d e  
10  
 
Chapter 3 - FTP Commands  
List of Commands  
Account (-AC or -ACCT)  
If required for logon, use the Account adapter command (-ACor -ACCT) to specify  
the account for connecting to an FTP server. If the account is required for logon,  
account_idmust be specified.  
-ACCT account_id  
Option  
Description  
account_id  
Specify the account for connecting to an FTP server.  
Audit (-A or -AUDIT)  
Use the Audit adapter command (-Aor -AUDIT) to produce a log file in the map  
directory where the adapter is installed with the default name m4ftp.log. The log  
file records audit information detailing files sent or received from each host,  
elapsed time, file size, and retry count for each file.  
-AUDIT[+][S] [full_path]  
Option  
Description  
+
Append audit information to the existing log file. If a  
log file does not exist, one is created.  
S
Summary mode. Record only minimal information in  
the log file.  
full_path  
Create audit file with the specified name in the  
specified directory. By default, the directory is where  
the map is located and the file name is m4ftp.log.  
F T P A d a p t e r R e f e r e n c e G u i d e  
11  
 
Chapter 3 - FTP Commands  
List of Commands  
Certificate Authority (-CA)  
Use the Certificate Authority adapter command (-CA) to specify the file from  
which to load trusted CA certificates.  
-CA filename  
Option  
Description  
filename  
Specify the file from which to load the trusted CA  
certificates.  
Client Certificate (-CERT)  
Use the Client Certificate adapter command (-CERT) to specify the file containing  
the client certificate (if used).  
-CERT filename  
Option  
Description  
filename  
Specify the file containing the client certificate.  
Client Certificate Password (-CPASS)  
Use the Client Certificate Password adapter command (-CPASS) to specify the  
password for the client certificate (if password protected).  
-CPASS password  
Option  
Description  
password  
Specify the password for the client certificate.  
F T P A d a p t e r R e f e r e n c e G u i d e  
12  
 
Chapter 3 - FTP Commands  
List of Commands  
Code Page Local (-CPL)  
Use the Code Page Local adapter command (-CPL) to specify the code page of the  
data on the local system (the system on which Mercator is running).  
Use this command in conjunction with the TYPE=ASCII feature of the –URL  
command. This command must be used if the Code Page Remote adapter  
command (-CPR) is specified.  
This command is only valid on OS/390 and z/OS systems. The default value is the  
default EBCDIC code page for your system.  
-CPL code_page_name  
Option  
Description  
code_page_name  
Specify the code page name of the data on the  
local system.  
See IBM publication "OS/390: C/C++ Run-Time Library Reference" (SC28-1663)  
function __atoe_lor go to http://publibz.boulder.ibm.com/cgi-  
bin/bookmgr_OS390/BOOKS/EDCLB130/3.50?SHELF=CBCBS130&DT=200206201  
75922 for more information.  
Code Page Remote (-CPR)  
Use the Code Page Remote adapter command (-CPR) to specify the code page of  
the data on the remote system to which, or from which the data is being  
transferred.  
Use this command in conjunction with the TYPE=ASCII feature of the –URL  
command. This command must be used if the Code Page Local adapter command  
(-CPL) is specified.  
This command is only valid on OS/390 and z/OS systems. The default value is ISO  
8859-1.  
-CPR code_page_name  
Option  
Description  
code_page_name  
Specify the code page name of the data on the  
local system.  
F T P A d a p t e r R e f e r e n c e G u i d e  
13  
 
Chapter 3 - FTP Commands  
List of Commands  
Firewall Connection Method URL (-FW or -FIREWALL)  
If required for connection, use the Firewall Connection Method URL (-FWor -  
FIREWALL) command to specify the URL for the proxy server (firewall). One of the  
following connection methods must be specified:  
OPEN  
SITE  
TRANSPARENT  
USER  
USERFW  
USERFWPASS  
USERLOGONor USER  
USERLOGONFWor USERFW  
-FIREWALL FTP://[fw_user[:fw_pass]@][fw_host[:fw_port]]/method  
Option  
Description  
fw_user  
Specify the user name to connect to the proxy server. Unless you  
are also specifying a password, this parameter must be followed by  
@if you specify fw_host.  
:fw_pass Specify the password that authenticates the user name. This  
parameter must be followed by @if you are also specifying  
fw_host.  
fw_host  
The name (or address) of the proxy server to which to connect.  
:fw_port The name (or number) of the port to use for connection.  
/method  
Required value. The method dictates how the firewall connection is  
established based on a combination of the connection information  
provided using –FIREWALL(for proxy server URL) and –URL(for  
FTP URL). Select one of the following Methods, which specifies the  
corresponding Connection Information.  
Method  
Connection Information  
OPEN  
OPEN ftp_host, USER ftp_user, PASS  
ftp_pass  
F T P A d a p t e r R e f e r e n c e G u i d e  
14  
 
Chapter 3 - FTP Commands  
List of Commands  
Option  
Description  
SITE  
USER fw_user, PASS fw_pass, SITE  
ftp_host,  
USER ftp_user, PASS ftp_pass  
TRANSPARENT  
USER fw_user, PASS fw_pass, USER  
ftp_user,  
PASS ftp_pass  
USER  
USER ftp_user@ftp_host, PASS ftp_pass  
USERFW  
USER ftp_user@ftp_host fw_user,  
PASS ftp_pass  
USERFWPASS  
USER ftp_user@fw_user@ftp_host,  
PASS ftp_pass@fw_pass  
USER fw_user, PASS fw_pass,  
USER ftp_user@ftp_host, PASS ftp_pass  
USERLOGONor  
USER  
USER fw_user@ftp_host, PASS fw_pass,  
USER ftp_user, PASS ftp_pass  
USERLOGONFWor  
USERFW  
Note TRANSPARENTis the only method that directly connects to the FTP server; all  
other methods connect to the firewall. See the FTP URL (-URL) adapter command  
for more information on the FTP variables shown in the Connection Information  
column.  
Example  
The following command uses the USERLOGON(or USER) method to connect to the  
proxy server fire (no port specified) with a user name of jbond and password of  
007:  
-FW FTP://jbond:007@fire/userlogon  
See URL Syntax and URL Encoding for more information.  
Adapter Behavior when -FIREWALL Command Present  
A firewall is used in order to isolate (restrict) some computers from reaching other  
computers.  
If a firewall comes into discussion, only a small part of the FTP adapter is aware of  
the presence of the firewall.  
F T P A d a p t e r R e f e r e n c e G u i d e  
15  
 
Chapter 3 - FTP Commands  
List of Commands  
Without a firewall the start of a file transfer begins with:  
Establish a Socket connection to the remote host.  
Issue the USERcommand over the connection.  
Issue the PASScommand over the connection.  
When a firewall is present (used) more steps are performed in the beginning of  
the transfer of the files.  
These steps are dependent on the /methodspecified in the last part of the  
-FIREWALLcommand.  
OPEN  
Establish a Socket connection to the firewall host  
Issue the following command over the connection in this order:  
OPEN ftp_host  
USER ftp_user  
PASS ftp_pass  
SITE  
Establish a Socket connection to the firewall host  
Issue the following command over the connection in this order:  
USER fw_user  
PASS fw_pass  
SITE ftp_host  
USER ftp_user  
PASS ftp_pass  
TRANSPARENT  
Establish a Socket connection to the remote host  
Issue the following command over the connection in this order:  
USER fw_user  
PASS fw_pass  
USER ftp_user  
PASS ftp_pass  
USERFW  
Establish a Socket connection to the firewall host  
Issue the following command over the connection in this order:  
F T P A d a p t e r R e f e r e n c e G u i d e  
16  
 
Chapter 3 - FTP Commands  
List of Commands  
USER ftp_user@ftp_host fw_user  
PASS ftp_pass  
USER ftp_user  
PASS ftp_pass  
USERFWPASS  
Establish a Socket connection to the firewall host  
Issue the following command over the connection in this order:  
USER ftp_user@fw_user@ftp_host  
PASS ftp_pass@fw_pass  
USERLOGONor USER  
Establish a Socket connection to the firewall host  
Issue the following command over the connection in this order:  
USER fw_user  
PASS fw_pass  
USER ftp_user@ftp_host  
PASS ftp_pass USER  
USERLOGONFWor USERFW  
Establish a Socket connection to the firewall host  
Issue the following command over the connection in this order:  
USER fw_user@ftp_host  
PASS fw_pass  
USER ftp_user  
PASS ftp_pass  
URL Syntax  
Because the syntax for the rest of the URL varies depending on the scheme  
selected, URL schemes that involve the direct use of an IP-based protocol for a  
specified host on the Internet use a common syntax for the scheme-specific data:  
//user:password@host:port/url_path  
Some or all parts of user:password@, :password, :port, and /url_pathmay  
be excluded. The scheme-specific data starts with a double slash (//) to indicate  
that it complies with the common Internet scheme syntax. The different  
components obey the following rules:  
F T P A d a p t e r R e f e r e n c e G u i d e  
17  
 
Chapter 3 - FTP Commands  
List of Commands  
user  
An optional user name. Some schemes such as FTP allow the  
specification of a user name.  
password An optional password. If present, it follows the user name, separated  
by a colon. The user name and password are followed by an at-sign  
(@). Within the user and password field, any :, @, or /characters  
must be encoded.  
The URL does not need to be completely URL-encoded. You only need to use  
escape characters for tokens specifically used in an FTP URL as shown in the  
following table. Any FTP URL that contains spaces must be enclosed in quotes; for  
example:  
-FIREWALL FTP://Home Machine/FTP Files  
Tokens  
Replaced with  
% (percent)  
@ (at)  
%25  
%40  
/ (forward slash)  
: (colon)  
%2F  
%3A  
; (semicolon)  
& (ampersand)  
# (pound)  
%3B  
Escape not needed, use as is  
Escape not needed, use as is  
Escape not needed, use as is  
8-bit or control characters  
F T P A d a p t e r R e f e r e n c e G u i d e  
18  
 
Chapter 3 - FTP Commands  
List of Commands  
FTP URL (-URL)  
The FTP URL adapter command (-URL)is required for connection to an FTP  
server. Specify the file name(s) to be retrieved (adapter source) or  
created/appended (adapter target).  
-URL [FTP:[//]][ftp_user[:ftp_pass]@][ftp_host[:ftp_port]]  
[/[/]][dir/[dir/…]] [filename][;type=xfer_type[+]]  
Option  
Description  
FTP:  
Specify as a connection to an FTP server. If not  
specified, FTP:is assumed, along with the //. Another  
/is required to separate the user and host parameters  
from file and transfer type, if specified.  
ftp_user  
Specify the user name to connect to the FTP server.  
Unless you are also specifying a password, this  
parameter must be followed by @if you specify  
ftp_host.  
:ftp_pass  
Specify the password that authenticates the user name.  
This parameter must be followed by @if you are also  
specifying ftp_host.  
ftp_host  
Specify the FTP server name or address to which to  
connect. If not specified, the default of localhost is  
assumed.  
:ftp_port  
dir/…  
The port name or number to use for connection  
Specify the directory path for the file. The ellipsis ()  
indicates this field can repeat, depending on your  
directory structure.  
filename  
Specify the name of the target file. This is required for  
an adapter target but optional for an adapter source. If  
not specified, all files in the path are retrieved.  
;type=xfer_type  
Specify the transfer type or mode. The supported  
transfer types vary from server to server. Depending on  
the server, there may be additional or omitted transfer  
types. Valid transfer types are:  
A[len][!] ASCII  
lenspecifies the optional record length to which to pad  
or truncate the record.  
!indicates no line terminator for the record(s).  
F T P A d a p t e r R e f e r e n c e G u i d e  
19  
 
Chapter 3 - FTP Commands  
List of Commands  
Option  
Description  
Note When sending an FTP request to the AS/400, the  
file must first be created on the AS/400 in order for the  
lenparameter to pad the record correctly.  
I
Image (binary)  
L8  
D
Local 8-bit types (usually equivalent to I)  
Directory (file names only)  
Directory (file names only)  
Directory (server-defined format)  
D1  
D2  
D3  
Directory (easily parsed line format, as  
defined in Internet draft draft-bernstein-  
eplf-02.txt)  
D4  
Directory (machine-readable list format as  
defined in Internet draft draft-ietf-  
ftpext-m1st-02.txt)  
+
Append the transferred data to the existing file.  
Note An additional forward slash (/) is required to separate the user and host  
parameters from file and transfer type, if specified.  
Example  
The following is an example of the input card command in the Map Designer:  
-T –URL FTP://sales@host/c:/forms/myfile.txt  
The command causes the myfile.txt file to be retrieved from a remote host  
named sales. The Tadapter command specifies that the adapter create a trace  
file to report adapter activity information during the FTP process.  
F T P A d a p t e r R e f e r e n c e G u i d e  
20  
 
Chapter 3 - FTP Commands  
List of Commands  
Ignore (-I or -IGNORE)  
The Ignore command (-I or -IGNORE) allows specified FTP error codes to be  
ignored by the adapter.  
-IGNORE error_code[:error_code…]  
Option  
Description  
error_code  
Specify the FTP error codes to be ignored by the  
adapter. A colon (:) must separate multiple error  
codes.  
For example, if you specified the command:  
-I 450:550  
the adapter ignores errors of type 450 (file busy) and errors of type 550 (file not  
available) and returns a zero-length file to the map. A list of error codes appears  
in RFC 959 (beginning on page 37 of the document at  
Keep Server (-KS)  
Use the Keep Server adapter command (-KS) to specify in a map rule that when  
retrieving a file from an FTP server, it should not be deleted after transfer.  
This option should be used if this behavior is desired when using the GETmapping  
function. When invoking the adapter from an input card, the same behavior can be  
accomplished through the card property, OnSuccess, by setting it to Keep.  
This is an optional command.  
-KS  
For example:  
-KS -URL ftp://user:pass@server/file.txt  
F T P A d a p t e r R e f e r e n c e G u i d e  
21  
 
Chapter 3 - FTP Commands  
List of Commands  
List Option (-LS)  
Use the List Option adapter command (-LS) to allow files to be retrieved based on  
a user supplied sorting preference.  
This command is used in conjunction with the existing FTP URL (-URL) adapter  
command and supports a subset of FTP options that control the order in which the  
files are transferred.  
This is an optional command.  
-LS sort_type  
The adapter passes the -LScommand value to a remote FTP server as an  
argument when it lists the files in the directory. One of three events happens at  
this point:  
FTP server accepts the option and lists the files in the specified order  
FTP server ignores the option and lists the files in the default order  
FTP server rejects the option and the adapter returns an error  
For example:  
-URL ftp://testftp:test@host/mydir –ls tr  
The -LScommand is issued by the adapter before any file transfer, so that its  
results are used to control the order of the file transfer. In the example above, all  
files from mydirwould be transferred, the oldest file being transferred first.  
Allowable command options include:  
Option  
Description  
t
Sorts by time stamp.  
r
Reverses the order of sort.  
Reverses the order of sort by time stamp.  
Same as -LStr.  
tr  
rt  
All other list options result in the error message: invalid ls option that is  
logged in the adapter trace file.  
Note The List Option (-LS) command options, (t, r, tr, and rt) may be ignored by  
some ftp servers.  
F T P A d a p t e r R e f e r e n c e G u i d e  
22  
 
Chapter 3 - FTP Commands  
List of Commands  
Make Directory (-MKD)  
Use the Make Directory adapter command (-MKD) to create a directory. For  
example, if a file specified in a PUToperation belongs in a directory that does not  
exist, the –MKDcommand creates the new directory.  
If the –MKDcommand is not specified and the file specified on a PUToperation  
points to a directory that does not exist, the adapter will fail.  
This is an optional command.  
-MKD  
For example:  
-MKD”, Some data”)  
will force jdoe/some and then the jdoe/some/folder to be created. A new file  
called data.txt will be added to this new directory.  
Passive Mode (-PV or -PASV)  
The Passive Mode adapter command (-PVor -PASV) specifies that you only try  
passive mode for the FTP data connection. Passive mode is primarily useful for  
firewalls and is a preferred connection method for security reasons.  
By default, the adapter attempts to connect using passive mode. If unsuccessful,  
the adapter uses Port Mode; see the Port Mode adapter command (-PT). During a  
passive mode connection, the server listens for the connection and dictates where  
the adapter is to connect.  
-PASV  
Note Older servers might not support passive mode.  
Port Mode (-PT or -PORT)  
The Port Mode adapter command (-PTor -PORT) specifies that you only try port  
mode for the FTP data connection. This is an older connection method and may be  
the only way to connect on older servers.  
F T P A d a p t e r R e f e r e n c e G u i d e  
23  
 
Chapter 3 - FTP Commands  
List of Commands  
By default, the adapter first tries to connect using passive mode; see the Passive  
Mode adapter command (-PV). If the adapter is unsuccessful, it uses port mode.  
During a port mode connection, the adapter listens for the connection and dictates  
where the server is to connect.  
-PORT  
Private Key (-PKEY)  
The Private Key adapter command (-PKEY) specifies the file containing the client  
private key (if used).  
-PKEY filename  
Option  
Description  
filename  
Specify the file containing the client private key.  
Private Key Password (-KPASS)  
Use the Private Key Password adapter command (-KPASS) to specify the  
password for the client private key (if password protected).  
-KPASS password  
Option  
Description  
password  
Specify the password for the client private key.  
Quantity (-QTY)  
Use the Quantity command (-QTY) to capture the number of files to be retrieved  
by the adapter.  
If you are running in burst mode, each burst may return less than –QTY  
messages, but the total number of messages returned by the adapter will not  
exceed the value specified by the –QTYcommand.  
If not specified, the default quantity is the FetchUnit size of the burst.  
-QTY number  
F T P A d a p t e r R e f e r e n c e G u i d e  
24  
 
Chapter 3 - FTP Commands  
List of Commands  
Option  
Description  
The number of files to be retrieved by the adapter.  
number  
Note If you want the maximum number of files retrieved in burst mode to be infinite,  
then you must set the –QTYcommand option numberto 'S' and specify "-LSN 0"  
on the command line. The –LSNcommand is currently unsupported, however, it  
must be used in conjunction with the –QTYcommand in this scenario only.  
Site (-SITE)  
Use the Site adapter command (-SITE) to send an FTP server specific site  
command to the FTP server software.  
-SITE ‘command_text  
Option  
Description  
command_text’  
Specify the FTP-server-specific site command  
(enclosed in single quotes) to send to the FTP server  
software  
For example:  
-SITE ‘namefmt=1’  
sends the NAMEFMTcommand to an AS/400 FTP server before files are  
transferred.  
To see what commands are accepted by the server use a BSD-based command  
line client (typically the FTP command installed with your Windows or UNIX  
operating system) and log in to the server and type the following from the ftp>  
prompt: quote HELP SITE or quote SITE HELP.  
Note The command specified by -SITEis executed prior to the files being transferred.  
F T P A d a p t e r R e f e r e n c e G u i d e  
25  
 
Chapter 3 - FTP Commands  
List of Commands  
SSL Encryption Strength (-STR)  
The SSL Encryption Strength (-STR) command can be either WEAK (only use  
weak algorithms) or STRONG (only use strong algorithms). If not specified, any  
available algorithm is used (if STRONG is not available then WEAK is used). If the  
export version of the libraries is used, only weak algorithms are available and this  
command is ignored.  
-STR {WEAK|STRONG|ANY}  
Option  
STRONG  
WEAK  
Description  
Use strong (non-exportable) encryption only.  
Use exportable encryption only.  
Use any available encryption.  
ANY  
SSL Protocol (-SPROTO)  
Use the SSL Protocol adapter command (-SPROTO) to set the Secure Socket Layer  
(SSL) protocol level. SSL enables the adapter to process FTPS URLs. If -SPROTO is  
not specified, the SSL Protocol defaults to SSLv23.  
-SPROTO {SSLv2|SSLv3|SSLv23|TLSv1}  
Option  
SSLv2  
SSLv3  
SSLv23  
TLSv1  
Description  
Specify SSL protocol version 2.  
Specify SSL protocol version 3.  
Specify SSL protocol version 2 or version 3.  
Specify Transport Layer Security (TLS) protocol version 1.  
Stage (-STG or -STAGE)  
Use the Stage adapter command (-STGor -STAGE) to accomplish the following:  
To specify that uploaded data should be staged in a temporary or shadow file.  
To prevent partial updates of a file to be transferred. This is especially  
important if the FTP server processes uploads in an automated fashion.  
F T P A d a p t e r R e f e r e n c e G u i d e  
26  
 
Chapter 3 - FTP Commands  
List of Commands  
During an upload, the FTP server generates a uniquely-named temporary file.  
When the transfer has completed successfully, the original file is deleted and the  
temporary file is renamed. For this process to succeed you must have access  
rights associated with your user ID to delete and rename files, and if the optional  
file name (file_name) is omitted the server must provide a correct Store Unique  
(STOU) response. The adapter issues a warning if the server response cannot be  
interpreted. It is recommended that you run a preliminary test to ensure that the  
process completes successfully.  
-STAGE [file_name]  
Option  
Description  
file_name  
Specify a unique file name for the temporary file. This  
option is especially useful if a server does not supply  
unique file names.  
System (-SYS)  
Use the System adapter command (-SYS) to specify the system type when the  
adapter cannot accurately determine the system type of the FTP server.  
Note The FTP server system type is not necessarily the same as the operating system  
of the machine it is running on. Some Windows FTP servers use UNIX conventions.  
If in doubt, consult your server documentation or use the dircommand and then  
view the results.  
-SYS {WIN32|UNIX|UNKNOWN}  
Option  
Description  
WIN32  
The server follows Windows conventions. For example,  
directories in pathnames are separated by a backward  
slash (\).  
UNIX  
The server follows UNIX conventions. For example,  
directories in pathnames are separated by a forward  
slash (/).  
UNKNOWN  
Because the platform is not known, exercise generic  
code. Do not perform anything that is specific to a  
platform.  
F T P A d a p t e r R e f e r e n c e G u i d e  
27  
 
Chapter 3 - FTP Commands  
List of Commands  
Trace (-T or -TRACE)  
Use the Trace adapter command (-Tor -TRACE) to produce a diagnostics file with  
the default name m4ftp.mtr in the map directory where the adapter is installed.  
The file records trace information detailing the FTP adapter activity.  
-TRACE[+][S|V] [full_path]  
Option  
Description  
+
S
Append trace information to the existing log file.  
Summary mode. Record only minimal information only  
in the log file. This is the default value.  
V
Verbose mode. Record in the log file all activity  
occurring while the adapter is retrieving data. If not  
specified, summary mode assumed.  
full_path  
Create trace file with the specified name in the  
specified directory. By default, the directory is where  
the map is located and the file name is m4ftp.mtr.  
Note Because summary mode is the default, using -TRACESprovides the same output  
as –TRACE.  
F T P A d a p t e r R e f e r e n c e G u i d e  
28  
 
Chapter 4 - Syntax Summary  
This chapter discusses the FTP syntax summary and how it is used.  
Data Sources  
The following is the command syntax of the FTP adapter commands used for data  
sources:  
-URL [FTP:[//]][ftp_user[:ftp_pass]@][ftp_host[:ftp_port]]  
[/[/]][dir/[dir/]] [filename][;type=xfer_type[+]]  
[-ACCT account_id]  
[-AUDIT[+][S] [full_path]]  
[-CERT filename]  
[-CPASS password]  
[-CPL code_page_name]  
[-CPR code_page_name]  
[-FIREWALL  
FTP://[fw_user[:fw_pass]@][fw_host[:fw_port]]/method]  
[-IGNORE error_code[:error_code…]]  
[-KPASS password]  
[-KS]  
[-LS sort_type]  
[-MKD ]  
[-PASV]  
[-PKEY filename]  
[-PORT]  
[-QTY number]  
[-SITE command_text]  
[-SPROTO {SSLv2|SSLv3|SSLv23|TLSv1}]  
[-STR {WEAK|STRONG|ANY}]  
[-SYS {WIN32|UNIX|UNKNOWN}]  
[-TRACE[+][S|V] [full_path]]  
F T P A d a p t e r R e f e r e n c e G u i d e  
29  
 
Chapter 4 - Syntax Summary  
Data Targets  
Data Targets  
The following is the command syntax of the FTP adapter commands used for data  
targets:  
-URL [FTP:[//]][ftp_user[:ftp_pass]@][ftp_host[:ftp_port]]  
[/[/]][dir/[dir/]] [filename][;type=xfer_type[+]]  
[-ACCT account_id]  
[-AUDIT[+][S] [full_path]  
[-CA filename]  
[-CERT filename]  
[-CPASS password]  
[-CPL code_page_name]  
[-CPR code_page_name]  
[-FIREWALL  
FTP://[fw_user[:fw_pass]@][fw_host[:fw_port]]/method]  
[-IGNORE error_code{:error_code…}]  
[-KPASS password]  
[-KS]  
[-LS sort_type]  
[-MKD ]  
[-PASV]  
[-PKEY filename]  
[-PORT]  
[-SITE command_text]  
[-SPROTO {SSLv2|SSLv3|SSLv23|TLSv1}]  
[-STAGE [file_name]  
[-STR {WEAK|STRONG|ANY}]  
[-SYS {WIN32|UNIX|UNKNOWN}]  
[-TRACE[+][S|V] [full_path]]  
F T P A d a p t e r R e f e r e n c e G u i d e  
30  
 
Chapter 4 - Syntax Summary  
Using FTP Adapter Commands  
Using FTP Adapter Commands  
Use the adapter commands from the Map Designer or Integration Flow Designer  
as the data source of an input map card and as the data target for an output map  
card. You can also use the adapter on the command line or in a map rule using  
the functions GET, PUT, or RUN.  
The FTP adapter requires the -URLadapter command for the  
GET > Source > Command and PUT > Target > Command settings.  
See Chapter 3 - FTP Commands for more information on FTP adapter commands  
and their syntax. For general information about commands, refer to the Resource  
Adapters Reference Guide.  
Examples  
To retrieve the file mine.txt, located on the host computer (no port specified)  
under c:\forms with no user name or password specified, enter the following  
command:  
-URL FTP://host/c:/forms/mine.txt  
The command example would retrieve the entire contents of the forms directory  
(because the file name is omitted) from the host computer:  
-URL FTP://host/c:/forms/  
URL Syntax  
The syntax for the rest of the URL varies depending on the scheme selected. URL  
schemes that involve the direct use of an IP-based protocol for a specified host on  
the Internet use the following common syntax for scheme-specific data:  
//user:password@host:port/url_path  
Some or all parts of user:password@, :password, :port, and /url_path may  
be excluded. The scheme-specific data start with a double slash (//) to indicate  
that it complies with the common Internet scheme syntax. The user:password  
component conforms to the following rules:  
user  
An optional user name. Some schemes allow the specification of a  
user name.  
password An optional password. When present, it follows the user name and is  
separated by a colon. The user name and password are followed by  
F T P A d a p t e r R e f e r e n c e G u i d e  
31  
 
Chapter 4 - Syntax Summary  
URL Syntax  
an at sign (@). Within the user and password field, any :, @, or /  
characters must be encoded. See URL Encoding.  
The url_pathof an FTP URL has the following syntax:  
cwd1/cwd2/.../cwdN/name;type= xfer_type  
where cwd1through cwdNand nameare (possibly encoded) strings and  
xfer_typeis one of the characters a, i, or d. The part ;type=xfer_type may be  
omitted. The cwdxand nameparts may be empty. The whole url_pathmay be  
omitted, including the /, delimiting it from the prefix containing user, password,  
host, and port.  
The url_pathis interpreted as a series of FTP commands as follows:  
Each cwdelement is to be sequentially supplied as the argument to a CWD  
(change working directory) command.  
If the typecode is “d”, perform a NLST(name list) command with nameas the  
argument and interpret the results as a file directory listing.  
Otherwise, perform a TYPEcommand with xfer_typeas the argument and  
then access the file named name(for example, using the RETRcommand).  
Note The xfer_typeargument has been extended beyond what is supported by the  
RFC, specifically the D1, D2, D3, and D4 sections. Also, host:portmay be  
excluded, although it is rarely useful to do so; hostdefaults to localhost.  
F T P A d a p t e r R e f e r e n c e G u i d e  
32  
 
Chapter 4 - Syntax Summary  
URL Encoding  
URL Encoding  
The URL does not need to be completely ‘URL-encoded’. You only need to use  
escape characters for tokens specifically used in an FTP URL, as shown in the  
following table. Any FTP URL that contains spaces must be enclosed in quotes; for  
example:  
-URL “FTP://Home Machine/FTP Files”  
Tokens  
Replaced with  
% (percent)  
@ (at)  
%25  
%40  
/ (forward slash)  
: (colon)  
%2F  
%3A  
; (semicolon)  
& (ampersand)  
# (pound)  
%3B  
Escape not needed, use as is  
Escape not needed, use as is  
8-bit or control characters Escape not needed, use as is  
F T P A d a p t e r R e f e r e n c e G u i d e  
33  
 
Chapter 5 - Troubleshooting  
For information about error codes and messages returned by the adapters, see  
Appendix A - Return Codes and Error Messages.  
Various troubleshooting tools are available in case of problems using the FTP  
adapter for data sources or targets for a map. For example, if you attempt to run  
a map that uses the FTP adapter and encounter problems or do not receive the  
expected results, use the following adapter troubleshooting tools:  
adapter audit log (.log)  
adapter trace file (.mtr)  
Adapter Audit Log  
The adapter audit log is a text file created during the adapter execution that  
records information about the events that occurred during the adapter activity. To  
produce an adapter audit log, use the adapter command (–AUDIT). The default log  
name is m4ftp.log and is located in the map directory. See the Trace(-T)  
adapter command for more information.  
The adapter audit log contains information including the:  
host identifier  
files sent or received  
size of each file  
elapsed time  
retry count for each file  
Sample FTP Adapter Audit Log  
BEGIN MERCATOR FTP AUDIT  
Receiving from Host: localhost  
Filename  
Filesize Time Retry  
-------------------------------- ---------- ---- -----  
rollback.gif  
183 KBytes 000s  
0
END MERCATOR FTP AUDIT  
F T P A d a p t e r R e f e r e n c e G u i d e  
34  
 
Chapter 5 - Troubleshooting  
Adapter Trace File  
Adapter Trace File  
The adapter trace file contains detailed information provided by the adapter and  
records the actions taking place such as connections established and statements  
executed. The trace file is produced during the adapter execution and can be used  
as a debugging aid. To produce a trace file for the adapter, use the (-TRACE)  
adapter command. The default adapter trace file name is m4ftp.mtr and is  
located in the map directory. See the Audit adapter command for more  
information.  
Sample FTP Adapter Trace File  
Mercator FTP Adapter, Version 6.0(560)  
Copyright © 1999-2000, Mercator Software, Inc.  
Built for WIN32 - INTEL on Mar 23 2000 at 15: 13: 00 by BocaBuild.  
Mercator Command Server is ‘C:\Mercator6.0\mercnt.exe’.  
Retry Count is 0. Retry Interval is 0. Rollback is OFF.  
Fetch Unit is 0. Burst Mode is OFF  
Run Started at 08: 49: 38.911 on 03/28/00.  
>220- (S)  
>220-This is a demo version of the Vermillion FTP Daemon, licensed only for (S)  
>220-a 30 day evaluation period. For continued use, you must purchase a (S)  
>220-license. For more information or to download the latest version, please (S)  
>220-visit Arcane Software on the web at ‘http: //www.arcanesoft.com’. (S)  
>220- (S)  
>220-Note: This session is limited to 15 minutes. If you are transferring a (S)  
>220-  
>220-  
file at that time, the system will wait until it is complete (S)  
before automatically disconnecting you. (S)  
>220 (S)  
<USER sls  
>331 Password required for sls. (S)  
<PASS sls  
>230 User sls logged in. (S)  
<SYST  
>215 UNIX Type: L8 (S)  
Setting AIX/UNIX-specific parameters.  
<CWD /d:  
>250 CWD command successful. (S)  
<TYPE I  
>200 Type set to I. (S)  
<PASV  
>227 Entering passive mode (127,0,0,1,8,230) (S)  
Using port ‘2278’ for the connection.  
Connecting to ‘127.0.0.1’.  
Socket Opened.  
Connected.  
<RETR rollback.gif  
>150 Opening BINARY mode data connection for rollback.gif (187714 bytes). (S)  
F T P A d a p t e r R e f e r e n c e G u i d e  
35  
 
Chapter 5 - Troubleshooting  
Adapter Trace File  
(187714 bytes received)  
Socket Closed.  
Connection closed.  
>226 Transfer Complete. (S)  
<QUIT  
>221 Goodbye. (S)  
Socket Closed.  
Connection closed.  
Winsock Client ID 1 disabled.  
Read 187714 bytes from /d: /rollback.gif.  
Data in E: \167.tmp kept.  
Run Completed at 08: 49: 39.742 on 03/28/00.  
F T P A d a p t e r R e f e r e n c e G u i d e  
36  
 
Appendix A - Return Codes and Error  
Messages  
Return codes and messages are returned when the particular activity completes.  
Return codes and messages may also be recorded as specified in the audit logs,  
trace files, execution summary files, etc.  
Messages  
The following is a listing of all the codes and messages that can be returned as a  
result of using the FTP adapter for sources or targets.  
Note Adapter return codes with positive numbers are warning codes that indicate a  
successful operation. Adapter return codes with negative numbers are error codes  
that indicate a failed operation.  
Return Code Message  
0
OK  
-1  
-1  
-2  
-3FTP  
-3  
-4  
-5  
1
Insufficient memory to continue  
Library Initialization Failed  
Invalid Entry Point. (AIX adapters only)  
Could not load adapter  
Error Sending Data  
Error Receiving Data  
FTP: Insufficient memory to continue  
No data provided. Create on content specified: no  
data sent.  
2
Could not interpret STOU response! Target file will  
not be renamed.  
-1  
FTP Setup failed  
FTPRecv() failed  
FTPSend() failed  
No URL was specified  
-1  
-1  
-101  
F T P A d a p t e r R e f e r e n c e G u i d e  
37  
 
Appendix A - Return Codes and Error Messages  
Messages  
Return Code Message  
-102  
-103  
-104  
-105  
-106  
-107  
Invalid SSL protocol  
Invalid SSL algorithm strength  
Code page values invalid for this system  
Unable to initialize code page descripton  
Specify both –CPR and –CPL or neither  
Code page translation results in unequal character  
counts  
-108  
-600  
-???  
Iconv() failed to convert all characters  
Internal Error: Resource Manager Error  
????  
where -??? Is an error code returned from the  
server, made negative and where ???? is a server-  
supplied error message  
F T P A d a p t e r R e f e r e n c e G u i d e  
38  
 
Index  
.
.log file, 34  
.mtr, 34  
E
error codes, 21  
error messages, 37  
examples  
audit log, 34  
A
Firewall Connection Method URL, 15  
FTP adapter commands, 31  
FTP URL, 20  
trace file, 35  
URL encoding, 33  
Account (-AC or -ACCT) adapter command, 11  
adapter trace file, 35  
alias, 8  
Audit (-A or -AUDIT) adapter command, 11  
audit log, 34  
F
C
Firewall Connection Method URL (-FW or -  
FIREWALL) adapter command, 14  
FTP adapter, 6  
Certificate Authority (-CA) adapter command, 12  
Client Certificate (-CERT) adapter command, 12  
Client Certificate Password (-CPASS) adapter  
command, 12  
Code Page Local (-CPL) adapter command, 13  
Code Page Remote (-CPR) adapter command, 13  
commands  
I
Ignore (-I or -IGNORE) adapter command, 21  
international VANs, 7  
Account (-AC or -ACCT), 11  
Audit (-A or -AUDIT), 11  
K
Certificate Authority (-CA), 12  
Client Certificate (-CERT), 12  
Client Certificate Password (-CPASS), 12  
Code Page Local (-CPL), 13  
Code Page Remote (-CPR), 13  
Firewall (-FW or -FIREWALL), 14  
FTP URL (-URL), 19  
–KS adapter command, 21  
L
log file, 34  
–LS adapter command, 22  
M
Ignore (-I or -IGNORE, 21  
Keep Server (-KS), 21  
–MKD adapter command, 23  
List Option (-LS), 22  
Make Directory (-MKD), 23  
Passive Mode (-P or -PASV), 23  
Port Mode (-PORT), 24  
Private Key (-PKEY), 24  
Private Key Password (-KPASS), 24  
Quantity (-QTY), 24  
Site (-SITE), 25  
P
Passive Mode (-PV or -PASV) adapter command,  
23  
Port Mode (-PORT) adapter command, 24  
Private Key (-PKEY) adapter command, 24  
Private Key Password (-KPASS) adapter  
command, 24  
SSL Encryption Strength (-STR), 26  
SSL Protocol (-SPROTO), 26  
Stage (-STG or -STAGE), 26  
syntax summary, 29  
Q
Quantity (-QTY) adapter command, 24  
System (-SYS), 27  
Trace (-T or -TRACE), 28  
R
related references, 5  
return codes, 37  
D
debugging  
trace file, 35  
F T P A d a p t e r R e f e r e n c e G u i d e  
39  
 
Index  
S
System (-SYS) adapter command, 27  
system requirements, 6  
S
Site (-SITE) adapter command, 25  
Socket information, 7  
T
SSL Encryption Strength (-STR) adapter  
command, 26  
SSL Protocol (-SPROTO) adapter command, 26  
Stage (-STG or -STAGE) adapter command, 26  
syntax summary, 29  
Trace (-T) adapter command, 28  
trace file, 35  
troubleshooting, 34  
trace file, 35  
F T P A d a p t e r R e f e r e n c e G u i d e  
40  
 

Graco Stroller Model Type 7431 User Manual
Haier Flat Panel Television 32T51 User Manual
Harbor Freight Tools Power Roller 93359 User Manual
Healthrider Home Gym HREX04980 User Manual
HP Hewlett Packard Laptop 4530s User Manual
HP Hewlett Packard Laptop ZV5000 User Manual
HP Hewlett Packard Network Card NC110T User Manual
HTC Cell Phone Touch Cruise User Manual
Huffy Fitness Equipment 111 500 User Manual
Hunter Fan Outdoor Ceiling Fan 21425 User Manual