IBM FTP Adapter User Manual

HP NonSt op D at a Tr an sf or m ation 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 Published

528264-001 June 2004

Document History

Part

Product Version Published

Number

528264-001 NonStop Data Transformation Engine

6.7.1

June 2004

FTP Adapter Reference Guide

About This Document

Related References........................................................................................... 5

Chapter 1 - FTP Adapter

Overview ....................................................................................................... 6

System Requirements........................................................................................ 6

About Socket s ............................................................................................ 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 o r -AUDIT).................................................................................... 1 1

Certificate Authority (-CA)............................................................................12

Client Cert if icate (-CERT).............................................................................12

Client Cert if icate Password (-CPAS S) ............................................................... 12

Code Page Loca l (-C PL)................................................................................13

Code Page Remote (-C PR).............................................................................13

Firewall Connection Method URL (-FW or -FIREWA LL) ...........................................14

Adapter Behav io r wh en -F IREWALL Command Present ..........................................16

URL Syntax...............................................................................................17

FTP URL (-URL)..........................................................................................19

Ignore (-I or -IGNORE)..................................................................................21

Keep Server (-K S) .......................................................................................21

List Option (-LS)......................................................................................... 2 2

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 (-SI TE)...............................................................................................25

SSL Encryption Strength (-STR).......................................................................2 6

SSL Protocol (-S PROTO)................................................................................26

Stage (-STG or -STAGE)................................................................................ 26

System (-SY S)............................................................................................ 27

Trace (-T or -TRA CE )...................................................................................28

Chapter 4 - Syntax Summary

Data Source s..................................................................................................29

Data Target s..................................................................................................30

Using FTP Adapt e r Comm a n ds.............................................................................31

Examples .................................................................................................31

URL Syntax....................................................................................................31

URL Encodin g.................................................................................................33

FTP Adapter Reference Guide

Contents

Chapter 5 - Troubleshooting

Appendix A - Return Codes and Error Messages

Index

Adapter Audit Log ...........................................................................................34

Adapter Trace File...........................................................................................35

Messages.......................................................................................................37

FTP Adapter Reference Guide

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 W indows environment, has used the Mercator Design St udio, 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.

FTP Adapter Reference Guide

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 adapt er are detailed in t he release no tes. 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 FT P adapter is installed must be able to access the

desired FTP servers over a TCP/IP network.

FTP Adapter Reference Guide

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 thi s as

follows:

telnet target-ip 25 (to test a SMTP e-mail target)

telnet target-ip 110 (to test a POP3 e-mail source)

where welcome message from the server. Shut down the sessi on by typi ng QUIT and

pressing Enter.

Note You might not be able to see what you are typing on the screen.

target-ip is the server IP address. If the test is successful, you receive a

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 Gui de.

FTP Adapter Reference Guide

Chapter 2 - Command Alias

Speci fy adapter commands by using a command string on the command line or by creatin g a command file that contains adapter commands. The command s yntax is:

-IA[alias]card_num

-OA[alias]card_num

In the command syntax, and

-OA is the Output Target Override execution command, alias is the adapter

alias, and card_num is the nu mber of the map card. The FTP adapter alias and corresponding execution commands are listed below.

Adapter Alias As Input As Output

FTP

FTP -IAFTPcard_num -OAFTPcard_num

-IA is the Input Source Override execution command

FTP Adapter Reference Guide

Chapter 3 - FTP Commands

This chapter describes the functions and use of the FTP commands and their options.

List of Comma nds

The following table lists valid commands for the FTP adapter, the command syntax, an d whether t he command i s supported (√) for use with data sources,

targets, or both.

Name Syntax Source Target

Account Audit Certificate Authority

Client Certificate

Client Certificate Password

Code Page Local

(OS/390, z/OS only)

Code Page Remote

(OS/390, z/OS only)

Firewall Connection Method UR L

-ACCT account_id

-AUDIT[+][S] [full_path]

-CA filename

Note Only available if Security Option is

installed.

-CERT filename

Note Only available if Security Option is

installed.

-CPASS password

Note Only available if Security Option is

installed.

-CPL code_page_name

-CPR code_page_name

-FIREWALL FTP://firewall_URL

√ √ √ √ √ √

√ √

FTP URL Ignore

-URL FTP://ftp_URL

-IGNORE error_code[:error_code…]

FTP Adapter Reference Guide

√ √ √ √

Chapter 3 - FTP Commands List of Commands

Name Syntax Source Target

Keep Server List Option Make Directory Passive Mode Port Mode Private Key

Private Ke y Password

Quantity Site SSL Encryption

Strength

-KS

-LS sort_type

-MKD

-PASV

-PORT

-PKEY filename

Note Only available if Security Option is

installed.

-KPASS password

Note Only available if Security Option is

installed.

-QTY number

-SITE command_text

-STR {WEAK|STRONG|ANY}

Note Only available if Security Option is

installed.

√ √ √ √ √ √ √ √ √ √ √ √

√ √

√ √ √ √ √

SSL Protocol

Stage System Trace

-SPROTO {SSLv2|SSLv3|SSLv23|TLSv1}

Note Only available if Security Option is

installed.

-STAGE [file_name]

-SYS {WIN32|UNIX|UNKNOWN}

-TRACE[+][S|V] [full_path]

FTP Adapter Reference Guide

√ √

√

√ √ √ √

Chapter 3 - FTP Commands List of Commands

Account (-AC or -ACCT)

If required for logon, use the Account adapter command (-AC or -ACCT) to specify the account for connecting to an FTP server. If the account is required for logon,

account_id must 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 (-A or -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.

full_path

Summary mode. Record only minimal information in the log file.

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.

FTP Adapter Reference Guide

Chapter 3 - FTP Commands List of Commands

Certificate Authority (-CA)

Use the Certifi c ate Authorit y 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 comman d (-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 Passw ord (- 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.

FTP Adapter Reference Guide

Chapter 3 - FTP Commands List of Commands

Code Page Local (-CPL)

Use the Code Page Local adapter c ommand (-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 command. This command must be used if the Code Page Remote adapter

command ( This command is only valid on OS/390 and z/OS systems. The default value is the

default EBCDIC code page for your system.

See IBM publication "OS/390: C/C++ Run-Time Library Reference" (SC28-1663) function

bin/bookmgr_OS390/BOOKS/EDCLB130/3.50?SHELF=CBCBS130&DT=200206201 75922 for more information.

-CPR) is specified.

-CPL code_page_name

Option Description

code_page_name

Specify the code page name of the data on the local system.

__atoe_l or go to http://publibz.boulder.ibm.com/cgi-

–URL

Code Page Remote (-CPR)

Use the Code Page Remote adapter command (-CPR) to specify the code page o f 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

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

FTP Adapter Reference Guide

Specify the code page name of the data on the local system.

–URL

Chapter 3 - FTP Commands List of Commands

Firewall Connection Method UR L (-FW or -FIREWALL)

If required for connection, use the Firewall Connection Method URL (-FW or -

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 ♦ USERLOGON or USER

♦ USERLOGONFW or 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

paramete r must be followed by @ i f you are also specifying

fw_host.

fw_host

:fw_port The name (or number) of the port to use for connection.

/method

The name (or address) of the proxy server to which to connect.

Required value. The method dictates how the firewall connection is established based on a combination of the connection information provided using

FTP URL). Select one of the following Methods, which specifies the corresponding Connection Information.

Method Connection Information

–FIREWALL (for proxy server URL) and –URL (for

OPEN

OPEN ftp_host, USER ftp_user, PASS

ftp_pass

FTP Adapter Reference Guide

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 USERFW

USER ftp_user@ftp_host, PASS ftp_pass USER ftp_user@ftp_host fw_user,

PASS ftp_pass

USERFWPASS

USER ftp_user@fw_user@ftp_host, PASS ftp_pass@fw_pass

USERLOGON or USER

USERLO GON FW or USERFW

Note TRANSPARENT is 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 FT P variables sh own in the Connection Information

column.

USER fw_user, PASS fw_pass, USER ftp_user@ftp_host, PASS ftp_pass

USER fw_user@ftp_host, PASS fw_pass, USER ftp_user, PASS ftp_pass

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 FT P://jbond:007@fire/userlogon

See URL Syntax and URL Encoding for more information.

Adapter Behavior when -FIREWA LL 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.

FTP Adapter Reference Guide

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

♦ Issue the

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

USER command over the connection. PASS command over the connection.

/method specified in the last part of the

-FIREWALL command.

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:

FTP Adapter Reference Guide

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

USERLOGON or 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

USERLOGONFW or 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 be excluded. The scheme-specific data starts with a double slash ( that it complies with the common Internet scheme syntax. The different

components obey the following rules:

user:password@, :password, :port, and /url_path may

//) to indicate

FTP Adapter Reference Guide

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:/ /H ome Machine/FTP Files

Tokens Replaced with

% (percent) %25 @ (at) %40 / (forward slash) %2F : (colon) %3A ; (semicolon) %3B & (ampersand) Escape not needed, use as is # (pound) Escape not needed, use as is 8-bit or control characters Escape not needed, use as is

FTP Adapter Reference Guide

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:

ftp_user

:ftp_pass

ftp_host

:ftp_port dir/…

filename

;type=xfer_type

Specify as a connection to an FTP server. If not specified, FTP: is assumed, along with the //. Anoth er

/ is required to separ ate the user and host par ameters

from file and transfer type, if specified. Specify the user name to connect to the FTP server.

Unless you are also specifying a password, this paramete r must be followed by @ if you specify

ftp_host.

Specify the password that authenticates the user name. This parameter must be followed by @ if you are also

specifying Specify the FTP server name or address to which to

connect. If not specified, the default of localhost is assumed.

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.

Specify the name of the target file. This is required for an adapter target bu t optional for an adapter source. If not specified, all files in the path are retrieved.

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:

ftp_host.

A[len][!] ASCII

len specifies the optional record length to which to pad

or truncate the record. ! indicates no line terminator for the record(s).

FTP Adapter Reference Guide

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

len paramete r to pad the record correc tly.

I L8 D D1 D2 D3

Note An additional forward slas h (/) is required to separate the user and host

parameters from file and transfer type, if specified.

Append the transferred data to the existing file.

Image ( binary) Local 8-bit types (usually equivalent to I) Directory (file names only ) Directory (file names only ) Direc tory (server-defined fo rmat) Directory (easily parsed line format, as

defined in Internet draft draft-bernstein- eplf-02.txt)

Direc tory (machine-readable list format as defined in Internet draft draft-ietf- ftpext-m1st-02.txt)

Example

The following is an example of t he input card co mmand in the Map Designer:

-T –URL FTP://sales@host/c:/forms/myfile.txt

The command causes the myfile.txt named

file to report adapter activity information during the FTP process.

sales. The –T adapter command specifies that t he adapter create a trace

FTP Adapter Reference Guide

file to be retrieved from a remote host

Chapter 3 - FTP Commands List of Commands

Ignore (-I or -IG NORE)

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

For example, if you specified the command:

-I 450:55 0

the adapter ignores errors of type 450 (file busy) and errors of type 550 (file not available) and return s a zero-length fil e to the map. A list of error codes appears in RFC 959 (beginning on page 37 of the document at

http://www.ietf.org/rfc/rfc0959.txt).

Speci fy the FTP erro r codes to be ignored by the adapter. A colon (:) mus t separate multiple error

codes.

Keep S erver (-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 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.

GET mapping

This is an optional command.

For example:

KS -URL ftp:// user:pass@server/file.txt

FTP Adapter Reference Guide

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 ( 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 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 file s in the specified order ♦ FTP server ignores the option and lists the files in the default order ♦ FTP server rejects the option and the adapt er returns an e rror

For example:

-LS command value to a remote FTP server as an

-URL) adapter

-URL ftp://testftp:test@host/mydir –ls tr

-LS command is issued by the adapter before any file transfer, so that its

The results are used to control the order of the file transfer. In the example above, all

files from

mydir would be t ransferred, the oldest file being transfe rred first.

Allowable command options i nclude:

Option Description

t r 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.

Sorts by time stamp. Reverses the order of sort. Reverses the order of sort by time s tamp. Same as -LS tr.

FTP Adapter Reference Guide

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 exist, the

–MKD command creates the new directory.

PUT operation belongs in a directory that does not

If the points to a directory that does not exist, the adapter will fail.

This is an optional command.

For example:

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.

–MKD command is not specified and the file specified on a PUT operation

-MKD

PUT(“FTP”, “-URL ftp://jdoe:secret@server1/some/folder/data.txt

-MKD”, “Some data”)

Passive Mod e (-PV or -PASV)

The Passive Mode adapter command (-PV or -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 met hod for security reasons. By default, the adapter attempts to connect using passive mode. If unsuccessful,

the adapte r uses Port Mode; see the Port Mode adapter command ( passive mode connection, the server listens for the connection and dictates where

the adapter is to connect.

-PT). During a

-PASV

Note Older servers might not support passive mode.

Port Mode (-PT or -PORT)

The Port Mode adapter command (-PT or -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.

FTP Adapter Reference Guide

Chapter 3 - FTP Commands List of Commands

By default, the adapter first tries to connect using passive mode; see the Passive Mode adapter command (

During a port mode connection, the adapter listens for the connection and dictates where the server is to connect.

-PORT

-PV). If the adapter is unsuccessful, it uses port mode.

Private Key (-PKEY)

The Pri vate 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 ad apter command (-KPASS) to specify the passwor d for the client privat e key (if password protected).

-KPASS password

Option Description

password

Specify the password for the client private key.

Quanti ty (- 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 – messages, but the total number of messages returned by the adapter will not

exceed the value specified by the

–QTY command.

QTY

If not specified, the default quantity is the FetchUnit size of the burst.

-QTY number

FTP Adapter Reference Guide

Chapter 3 - FTP Commands List of Commands

Option Description

number

Note If you want the maximum number of files retrieved in burst mode to be infinite,

then you must set the –QTY command opti on number to 'S' and specify "-LSN 0" on the command line. The –LSN command is currently unsupported, however, it must be used in conjunction with the –QTY command in this scenario only.

The nu mber of files to be retrieved by the adapter.

Site (-SIT E)

Use the Site adapter command (-SITE) to send an FT P server specific site command to the FTP server software.

-SITE ‘command_text’

Option Description

‘command_text’

For example:

Specify the FTP-serve r-specific site command (enclosed in single quotes) to send to the FTP server software

-SIT E ‘namefmt=1’

sends the 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

prompt:

Note The command specified by -SITE is executed prior to the files being transferred.

NAMEFMT command to an AS/400 FTP server before files are

ftp>

quote HELP SITE or quote SITE HELP.

FTP Adapter Reference Guide

Chapter 3 - FTP Commands List of Commands

SSL Enc ryption 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 Description

STRONG WEAK ANY

Use strong (non-exportable) encrypti on only. Use exportable encryption only. Use any available encryption.

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 Description

SSLv2 SSLv3 SSLv23 TLSv1

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 (-ST G or -STAG E )

Use the Stage adapter command (-STG or -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.

FTP Adapter Reference Guide

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 i s deleted and the temporary file is renamed. For this process to succe ed you must have access rights associated with your user ID to delete and rename files, and if the optional file name ( (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 successful ly.

file_name) is omitted the server must provide a correct Store Unique

-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 dir comm and 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

UNKNOWN

The server follows UNIX conventions. For example, directories in pathnames are separated by a forward slash (/).

Because the platform is not known, exercise generic code. Do not perform anything that is specific to a platform.

FTP Adapter Reference Guide

Chapter 3 - FTP Commands List of Commands

Trace (-T or -TRACE)

Use the Trace adapter c ommand (-T or -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

full_path

Note Because summary mode is the default, using -TRACES provides the same output

as –TRACE.

Append trace information to the existing log file. Summary mode. Record only minimal information only

in the log file. This is the default value. Verbose mode. Record in the log file all activity

occurring while the adapter is retrieving data. If not specified, summary mode assumed.

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.

FTP Adapter Reference Guide

Chapter 4 - Syntax Summary

This chapter discusses the FTP syntax summary and ho w 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]]

FTP Adapter Reference Guide

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]]

FTP Adapter Reference Guide

Chapter 4 - Syntax Summary Using FTP Adapter Commands

Using FTP Adapter Commands

Use the adapter commands from t he Map Designer or I ntegration Flow Designer as the data source of an input map card and as the data target for an output map card. You c an also use the adapter on the comm and line or in a map rule us ing the functions

GET, PUT, or RUN.

The FTP adapter requires the GET > Source > Command and PUT > Target > Command settings.

See Chapter 3 - FTP Commands for more information on FTP adapte r c ommands 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

-URL adapter comm and for the

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 be excluded. The scheme-specific data start with a double slash ( that it complies with the common Internet scheme syntax. The component conforms to the following rules:

user:password@, :password, :port, and /url_path may

//) to indicate

user:password

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 n ame and password are followed by

FTP Adapter Reference Guide

Chapter 4 - Syntax Summary URL Syntax

an at sign ( characters must be encoded. See URL Encoding.

The

url_path of an FTP URL has the following syntax:

cwd1/cwd2/.../cwdN/name;type= xfer_type

where xfer_type is one of the characters omitted. The omitted, including the

cwd1 through cwdN and name are (possibly e n coded) strings an d

cwdx and name parts may be empty. The whole url_path may be

@). Within the user and password field, any :, @, or /

a, i, or d. The part ;type= xfer_type may be

/, delimiting it from the prefix containing user, password,

host, and port.

url_path is interpreted as a series of FTP commands as follows:

The

♦ Each

(change working directory) command.

♦ If the typecode is “

argument and interpret the results as a file directory listing.

♦ Otherwise, perform a

then access the file named

cwd element is to be sequentially supplied as the argument to a CWD

d”, perform a NLST (name list) command with name as the

TYPE command with xfer_type as the argument and

name (for exam ple, using the RETR command).

Note The xfer_type argument has been extended beyond what is supported by the

RFC, specifically the D1, D2, D3, and D4 sections. Also, host:port may be excluded, although it is rarely useful to do so; host defaults to localhost.

FTP Adapter Reference Guide

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 Mach ine/FTP Files”

Tokens Replaced with

FTP Adapter Reference Guide

Chapter 5 - Troubleshoo ting

For information about error code s and mess ages returned by the adap ters, see

Appendi x A - Return Co des and Error Messages.

Various troubleshooting tools are avai lable 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)

Adapt e r 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 adapt er command

name is m4ftp.log and is loc ated in the map directory. S ee the Trace( adapter command for more information.

The adapter audit log contains information includi ng the:

♦ host identifier ♦ files sent or received ♦ size of each file ♦ elapsed time ♦ retry count for each file

(–AUDIT). The default log

-T)

Sample FTP Adapter Audit Log

BEGIN MER CA TO R FTP AUDIT Receivi ng fro m Host: localh ost Filename Filesize Time Retry

-------------------------------- ---------- ---- ----rollback.gif 183 KBytes 000s 0 END MERCA TO R FT P AUDIT

FTP Adapter Reference Guide

Chapter 5 - Troubleshooting Adapter Trace File

Adapter Trace File

The adapter trace file contains detailed informatio n provided by the adapter and records the actions taking place such as connections establishe d and statements executed. The trace file is produced during the adapter execution and can be used as a debugging aid. To produce a t race file for the adapter, u se the (

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

Mercato r FT P Ad apter, Versi on 6.0(560) Copyright © 1999-2000, Mercator Software, Inc. Built for WIN32 - INTEL on Mar 23 2000 at 15: 13: 00 by BocaBuild. Mercato r Co mm and 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 Start ed 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 eva luation period. For cont inued 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- file at that time, the system will wait until it is complete (S) >220- before automatically disconnecting you. (S) >220 (S) <USER sls

>331 Pass wo rd required for sl s. (S) <PASS sls

>230 User sls log ged in. (S) <SYST

>215 UNIX Type: L8 (S) Setting AIX/UNIX-specific parame ters. <CWD /d:

>250 CWD co mm an d 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. Connect in g to ‘127.0.0.1’ . Socket Op en ed . Connected. <RETR rollback.gif

>150 Open in g BI NARY mode data connectio n for rollback.gif (187714 bytes). (S)

-TRACE)

FTP Adapter Reference Guide

Chapter 5 - Troubleshooting Adapter Trace File

(187714 bytes received) Socket Cl os ed . Connect io n cl osed. >226 Transfer Complete. (S) <QUIT

>221 Good by e. (S) Socket Cl os ed . Connect io n cl osed. Winsock Client ID 1 disabled. Read 1877 14 byt es from /d: /rol lback.gif. Data in E: \1 67 .t mp kept. Run Compl et ed at 08: 49: 39.742 on 03/28/00 .

FTP Adapter Reference Guide

Appendix A - Return Codes and Error

Messages

Return codes and messages are returned whe n the particular activity completes. Return codes and messages may al so be re corded 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 retu rn codes with po sitive numbers are warning codes that indi cate a

successful operation. Adapter return codes with negative numbers are error codes that indicate a failed operation.

Return Code Message

0 OK

-1 Insufficient memory to continue

-1 Library Initialization Failed

-2 Invalid Entry Point. (AIX adapters only)

-3FTP Could not load adapter

-3 Error Sending Data

-4 Error Receiving Data

-5 FTP: Insufficient memory to continue 1 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

-1 FTPRecv() failed

-1 FTPSend() failed

-101 No URL was specified

FTP Adapter Reference Guide

Appendix A - Return Codes and Error Messages Messages

Return Code Message

-102 Invalid SSL protocol

-103 Invalid SSL algorithm strength

-104 Code page values invalid for this system

-105 Unable to initialize code page descripton

-106 Specify both –CPR and –CPL or neither

-107 Code page translation results in unequal character counts

-108 Iconv() failed to convert all characters

-600 Internal Error: Resource Manager Error

-??? ???? where -??? Is an error code returned from the server, made negative and where ???? is a serversupplied error message

FTP Adapter Reference Guide

Index

.log file, 34 .mtr, 34

Account (-AC or -ACCT) adapter command, 11 adapter trace file, 35 alias, 8 Audit (-A or -AUDIT) adapter command, 11 audit log, 34

Certificate Authority (-CA) adapter comm and , 12 Client Certificate (-CERT) ad apter command, 12 Client Certificate Password (-CPASS) adapter

command, 12 Code Page Loc a l (-CPL) adapter command, 13 Code Page Rem ote (-CPR) adap ter com ma nd , 13 commands

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 Loc a l (-CPL), 13

Code Page Rem ote (-CPR), 13

Firewall (-FW or -FIREWALL), 14

FTP URL (-URL), 19

Ignore (-I or -IGNORE, 21

Keep Server (-KS), 21

List Option (-LS), 22

Make Directory (-MKD), 23

Passive Mode (-P or -PASV), 23

Port Mode (-PORT), 24

Private Key ( -PKE Y), 24

Private Key Password (-KPASS), 24

Quantity (-QTY), 24

Site (-SITE), 25

SSL Encryptio n Strength (-STR), 26

SSL Protocol (-SPROTO), 26

Stage (-STG or -STAGE), 26

syntax su mmary, 29

System (-SYS), 27

Trace (-T or -TRACE), 28

debugging

trace file, 35

error codes, 21 error messages, 37 examples

audit log, 34 Firewall Connection Method URL, 15 FTP adapter commands, 31 FTP URL, 20 trace file, 35 URL encoding, 33

Firewall Conn e cti on Method URL (-FW or -

FIREWALL) adapter command, 14

FTP adapter, 6

Ignore (-I or -IGNORE) adapter command, 21 international VANs, 7

–KS adapter command, 21

log file, 34 –LS adapter command, 22

–MKD adapter command, 23

Passive Mode (-PV or -PASV) adap ter com ma nd ,

23 Port Mode (-PORT) adapter co mmand, 24 Private Key ( -PKE Y) adapter command, 24 Private Key Password (-KPASS) adap ter

command, 24

Quantity (-QTY) adapter command, 24

related references, 5 return codes, 37

FTP Adapter Reference Guide

Index S

Site (-SITE) adapter command, 25 Socket information, 7 SSL Encryptio n Strength (-STR) adapter

command, 26 SSL Protocol (-SPROTO) adapter command, 26 Stage (-STG or -STAGE) adapter co mmand, 26 syntax su mmary, 29

System (-SYS) adapter command, 27 system requirements, 6

Trace (-T) adapter command, 28 trace file, 35 troubleshooting, 34

trace file, 35

FTP Adapter Reference Guide

IBM FTP Adapter User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

Contents

About This Document

Index