HP NonStop Data Transformation Engine
FTP Adapter Reference Guide
Abstract
This manual provides information about using the HP NonStop™ Data 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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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)
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
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
Download from Www.Somanuals.com. All Manuals Search And Download.
|