HP NonStop Data Transformation Engine HTTP Adapter Reference Guide Abstract This manual provides information about using the HP NonStop™ Data Transformation Engine (NonStop DTE) FTP adapter on the HP NonStop server. Product Version NonStop Data Transformation Engine 6.7.
Document History Part Number Product Version Published 528265-001 NonStop Data Transformation Engine 6.7.
Contents About This Document Related References........................................................................................... 5 Chapter 1 - HTTP Adapter Overview ....................................................................................................... 6 Known Limitations ............................................................................................ 6 System Requirements ........................................................................................
Contents Chapter 5 - Troubleshooting Adapter Trace File........................................................................................... 29 Sample Adapter Trace File................................................................................. 29 Appendix A - Return Codes and Error Messages Messages.......................................................................................................
About This Document This document contains detailed information about using the HTTP 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 - HTTP Adapter This chapter introduces the Hypertext Transfer Protocol (HTTP) adapter. The HTTP adapter provides support for Proxy servers and Secure Socket Layer (SSL) protocol, which is required to process HTTPS (secure) URLs. . Overview The HTTP adapter is used to transfer data to and from an HTTP(S) web server. If you have a Command Server, an Event Server, or Platform API on one platform, you can use the HTTP adapter to transfer data to an HTTP(S) Web server on another platform.
Chapter 1 - HTTP Adapter Automatic HTTP Event Management Automatic HTTP Event Management The HTTP adapter allows the Event Server to directly process HTTP input events without compromising the integrity of the firewall. The enhanced HTTP functionality consists of an HTTP adapter listener for the HTTP adapter and a new Event Agent. The Event Agent can be deployed inside the firewall or safely outside the firewall.
Chapter 2 - Command Alias You can 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 HTTP adapter alias and corresponding execution commands are listed below.
Chapter 3 - HTTP Commands This chapter describes the functions and use of the HTTP commands and their options. List of Commands The following table lists valid commands for the HTTP adapter, the command syntax, and whether the command is supported (√) for use with data sources, targets, or both. Name Syntax Certificate Authority -CA filename Source Target √ √ √ √ √ √ Note: This option is only available if the Security Option is installed.
Chapter 3 - HTTP Commands Name Syntax Modified Since Private Key List of Commands Source Target -MODIFIED http-date √ √ -PKEY filename √ √ √ √ Note: This option is only available if the Security Option is installed. Private Key Password -KPASS password Note: This option is only available if the Security Option is installed.
Chapter 3 - HTTP 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 - HTTP Commands List of Commands From (-FROM) Use the From adapter command (-FROM) to specify the e-mail address of a contact person. The contact person is alerted when there is a problem with requests from the adapter. -FROM address Option Description address Specify the e-mail address of a contact person Header (-HDR) Use the Header adapter command (-HDR) to send message headers from data in a map file or to return message headers to the map file.
Chapter 3 - HTTP Commands List of Commands HTTP(S) URL (-URL) The HTTP(S) URL adapter command (-URL) is required for connection. Specify the URL to connect to the HTTP(S) server. You must specify a file name for the file to be transferred. -URL {HTTP|HTTPS}://[user[:pass]@][host[:port]][/dir[/file]] Option Description HTTP The HTTP application protocol HTTPS The HTTPS application protocol Note: This option is only available if you have the Security Option installed.
Chapter 3 - HTTP Commands List of Commands The URL does not need to be completely ‘URL-encoded’. You only need to use escape characters for tokens specifically used in a URL, as shown in the following table.
Chapter 3 - HTTP Commands List of Commands Inline Output (-INLINE) The purpose of the Inline Output adapter command (-INLINE) is to append data to the end of a URL. -INLINE You can use this command to submit a long query string to a form that uses method=GET. In the example below, the GET function has three arguments. The third argument is optional. GET ( "HTTP", "-URL HTTP://[www.yahoo.com/cgi-bin/search?] INLINE", "widgets" ) Result: Gets the URL http://www.yahoo.com/cgi-bin/search?widgets.
Chapter 3 - HTTP Commands List of Commands Option Description method_name Transfer method used in an HTTP request Modified Since (-MOD or -MODIFIED) Use the Modified Since adapter command (-MOD or -MODIFIED) to generate the If-Modified-Since header information used during a GET request. The HTTP adapter then adds the date to the request. -MODIFIED http-date Option Description http-date Dates supported by RFC 1123 and RFC 850.
Chapter 3 - HTTP Commands List of Commands Private Key (-PKEY) Use the Private Key adapter command (-PKEY) to specify the file containing the client private key (if used). -PKEY filename Option Description filename Specify the file containing the client private key. Note If a client certificate is used for establishing an HTTP SSL connection, then both -CERT and -PKEY must appear on the command line.
Chapter 3 - HTTP Commands List of Commands Proxy URL (-PROXY) Use the Proxy URL adapter command (-PROXY) to specify the URL to connect to a proxy server. You must specify a file name for the file to be transferred. -PROXY {HTTP|HTTPS}://[user[:pass]@][host[:port]][/dir[/file]] Option Description HTTP The HTTP application protocol HTTPS The HTTPS application protocol user Specify the user name to connect to the proxy server.
Chapter 3 - HTTP Commands List of Commands Session (-SESSION) Use the Session adapter command (-SESSION) to coordinate an HTTP request and response. This is a required command. -SESSION session_id [*] Option Description session_id Specify the session identifier, used for matching purposes. When receiving the HTTP request in a map, this contains the agent-assigned identifier. This identifier must be returned in the HTTP response.
Chapter 3 - HTTP Commands List of Commands SOCKS URL (-SOCKS) Use the SOCKS URL adapter command (-SOCKS) to connect to a SOCKS proxy server. -SOCKS {socks4|socks5}://[user[:pass]@][host[:port]] Option Description socks4 Specify SOCKS protocol version 4. socks5 Specify SOCKS protocol version 5. user Specify the user name to connect to the SOCKS server. pass Specify the password that authenticates the user name. host Specify the SOCKS server name or address.
Chapter 3 - HTTP Commands List of Commands WEAK Use exportable encryption only. ANY 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 HTTPS URLs. If -SPROTO is not specified, the SSL Protocol defaults to SSLv23. -SPROTO {SSLv2|SSLv3|SSLv23|TLSv1} Option Description SSLv2 Specify SSL protocol version 2. SSLv3 Specify SSL protocol version 3.
Chapter 3 - HTTP 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 m4http.mtr in the map directory where the adapter is installed. The file contains information detailing HTTP adapter activity. -TRACE [+][S|V][full_path] Option Description + Append trace information to the existing log file. S Summary mode. Default value. Record only minimal information in the log file. V Verbose mode.
Chapter 4 - Syntax Summary This chapter presents the HTTP syntax summary and how it is used.
Chapter 4 - Syntax Summary Data Targets Data Targets The following is the command syntax of the HTTP adapter commands used for data targets: -URL {HTTP|HTTPS}://[user[:pass]@][host[:port]][/dir[/file]] [-CA filename] [-CERT filename] [-CPASS password] [-FROM address] [-HDR[+][I]] [-IGNORE error_code[:error_code]] [-INLINE] [-KPASS password] [-LSN seconds] [-METHOD [method_name]] [-MODIFIED http-date] [-PKEY filename] [-PROXY {HTTP|HTTPS}://[user[:pass]@][host[:port]][/dir[/file]]] [-REDIRECT limit] [-SESS
Chapter 4 - Syntax Summary Example Files Example Files To access an example for this adapter, click Start > Programs > Mercator version number > Design Studio > Examples and navigate to Resource Adapters. The following examples can be found in this directory. ♦ Using the Map Designer, select HTTP from the Source setting in an Input Card dialog box.
Chapter 4 - Syntax Summary Example Files where adaptercommands are the HTTP adapter commands in the List of Commands. The format for specifying a command file is: M4HTTP_OPT=@filename.txt where filename.txt is the file containing HTTP adapter commands. Always precede the command file name with @. HTTP Header Adapter Command (–HDR) Example Process cookies by mapping Set-Cookie headers to Cookie headers. This example uses the Header adapter command (–HDR), Http.mtt type tree, and HTTPGetCookie map.
Chapter 4 - Syntax Summary Example Files Create a Type Tree In this example, the group type Message contains the components needed for the HTTPGetCookie map. The group type Header(s) contains the item type HeaderName and HeaderText. Configure the Map Input and Output Cards The HTTPGetCookie map input and output cards specify the Http.mtt file as its type tree in the TypeTree setting. Both the input and output cards use the group type Message from that type tree in the TypeName setting.
Chapter 4 - Syntax Summary Example Files Enter the Map Rules The HTTPGetCookie map output card specifies a functional map named xCookieExtractor, which searches for Set Cookie headers. If a Set-Cookie header is found, the map changes it to Cookie, and submits cookie parameters such as a user name and password.
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 if you encounter problems using the HTTP adapter for data sources or targets for a map. If you run a map that uses the adapter and encounter problems or do not receive the expected results, use the adapter trace file (.mtr) as a troubleshooting tool.
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 HTTP adapter for sources or targets. Note Adapter return codes with positive numbers are warning codes that indicate a successful operation.
Index Event Agent, 7 event management. See Event Agent examples, 27 –HDR command, 26 HTTP adapter, 25 -IGNORE command, 14 SOCKS, 20 trace file, 29 . .log, 29 .mtr, 29 A alias, 8 audit log, 29 automatic HTTP event management.
Index S RFC 2109 (request for comments), 26 T TCP/IP, 6 Timeout (-TIMEOUT) adapter commands, 21 Trace (-T or -TRACE) adapter command, 22 trace file, 29 example of, 29 troubleshooting, 29 trace file, 29 Type (-TY or -TYPE) adapter commands, 22 S Session (-SESSION) adapter commands, 19 SOCKS URL (-SOCKS) adapter commands, 20 SSL Encryption Strength (-STR) adapter command, 20 SSL Protocol (-SPROTO) adapter command, 21 syntax summary, 23 system requirements, 6 H TTP Ad apter R eference Guide 32
