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.
Document History Part Number Product Version Published 528264-001 NonStop Data Transformation Engine 6.7.
Contents About This Document Related References........................................................................................... 5 Chapter 1 - FTP Adapter Overview ....................................................................................................... 6 System Requirements ........................................................................................ 6 About Sockets ............................................................................................
Contents Chapter 5 - Troubleshooting Adapter Audit Log ........................................................................................... 34 Adapter Trace File........................................................................................... 35 Appendix A - Return Codes and Error Messages Messages.......................................................................................................
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.
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.
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 (to test a SMTP e-mail target) ! telnet target-ip 110 (to test a POP3 e-mail source) where target-ip is the server IP address. If the test is successful, you receive a welcome message from the server.
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, -IA is the Input Source Override execution command and -OA is 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.
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 Account -ACCT account_id √ √ Audit -AUDIT[+][S] [full_path] √ √ Certificate Authority -CA filename √ √ √ √ √ √ Note Only available if Security Option is installed.
Chapter 3 - FTP Commands List of Commands Name Syntax Source Target Keep Server -KS √ √ List Option -LS sort_type √ √ Make Directory -MKD √ √ Passive Mode -PASV √ √ Port Mode -PORT √ √ Private Key -PKEY filename √ √ √ √ Note Only available if Security Option is installed. Private Key Password -KPASS password Note Only available if Security Option is installed.
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.
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).
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.
Chapter 3 - FTP Commands List of Commands Firewall Connection Method URL (-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).
Chapter 3 - FTP Commands Option List of Commands 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 USERLOGON or USER USER fw_user, PASS fw_pass, USER ftp_user@ftp_host, PASS ftp_pass USERLOGONFW or USERFW USER fw_user@ftp_host,
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 USER command over the connection. ♦ Issue the PASS command 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 /method specified in the last part of the -FIREWALL command.
Chapter 3 - FTP Commands USER PASS USER PASS List of Commands ftp_user@ftp_host fw_user ftp_pass ftp_user 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 PASS USER PASS fw_user fw_pass ftp_user@ftp_host ftp_pass USER USERL
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.
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 //.
Chapter 3 - FTP Commands Option List of Commands 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 parameter to pad the record correctly. I L8 D D1 D2 D3 Image (binary) D4 Directory (machine-readable list format as defined in Internet draft draft-ietfftpext-m1st-02.
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.
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.
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 PUT operation belongs in a directory that does not exist, the –MKD command creates the new directory. If the –MKD command is not specified and the file specified on a PUT operation points to a directory that does not exist, the adapter will fail. This is an optional command.
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).
Chapter 3 - FTP Commands List of Commands Option Description number The number of files to be retrieved by the adapter. Note If you want the maximum number of files retrieved in burst mode to be infinite, then you must set the –QTY command option 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.
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 Description STRONG Use strong (non-exportable) encryption only.
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.
Chapter 3 - FTP Commands List of Commands Trace (-T or -TRACE) Use the Trace adapter command (-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 + Append trace information to the existing log file. S Summary mode. Record only minimal information only in the log file. This is the default value.
Chapter 4 - Syntax Summary This chapter discusses the FTP syntax summary and how it is used.
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] [
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 -URL adapter command for the GET > Source > Command and PUT > Target > Command settings.
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_path of an FTP URL has the following syntax: cwd1/cwd2/.../cwdN/name;type= xfer_type where cwd1 through cwdN and name are (possibly encoded) strings and xfer_type is one of the characters a, i, or d. The part ;type= xfer_type may be omitted. The cwdx and name parts may be empty.
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.
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 (.
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.
Chapter 5 - Troubleshooting Adapter Trace File (187714 bytes received) Socket Closed. Connection closed. >226 Transfer Complete. (S) 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.
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.
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, ma
Index . E .log file, 34 .
Index S System (-SYS) adapter command, 27 system requirements, 6 S Site (-SITE) adapter command, 25 Socket information, 7 SSL Encryption Strength (-STR) adapter command, 26 SSL Protocol (-SPROTO) adapter command, 26 Stage (-STG or -STAGE) adapter command, 26 syntax summary, 29 T Trace (-T) adapter command, 28 trace file, 35 troubleshooting, 34 trace file, 35 FTP Adapter Reference Guide 40