Natural for Mainframes	Version 8.2.6 for Mainframes	SEARCH   CONTENTS   |   PDF BOOKS   |   HOME   UP   PREV   NEXT

This document covers the following topics:

• Function

• Syntax Description

• Automatically Generated Headers

• URL Encoding for Special Characters

• HTTP/HTTPS Responses Redirected and Denied

• Examples

For an explanation of the symbols used in the syntax diagram, see Syntax Symbols.

Related Statement: PARSE XML

Belongs to Function Group: Internet and XML

Function

The REQUEST DOCUMENT statement is used to retrieve and upload documents on the internet as described in REQUEST DOCUMENT in the Programming Guide. See also Statements for Internet and XML Access.

For information on Unicode support, see REQUEST DOCUMENT in the Unicode and Code Page Support documentation.

Restrictions for Protocol Types

For technical reasons, HTTPS is supported under z/OS only.

No Support for Cookies

Cookies are not supported and are ignored.

Syntax Description

Operand Definition Table:

Syntax Element Description:

with-clause

The with-clause is used to specify optional user/password, header and data details for the request.

An empty with-clause (that is, no value specified after WITH) is ignored.

Operand Definition Table:

Syntax Element Description:

return-clause

Operand Definition Table:

This clause can be used to specify return information for the headers and/or the document.

Syntax Element Description:

Automatically Generated Headers

For an HTTP request, some headers are required, for example: request method or content type. These headers will be automatically generated depending on the parameters given with the REQUEST DOCUMENT statement.

Note:
It is possible to overwrite the automatically generated headers. Natural will not check them for errors. Unexpected errors may occur.

• HTTP Request Method

• Content Type

HTTP Request Method

The REQUEST DOCUMENT statement supports the following HTTP request methods: HEAD, POST, GET and PUT.

The following table shows the HTTP request method generated depending on the given operands:

Explanation:

Content Type

The request method POST requires a content-type header for the HTTP request. If no content type is explicitly specified, Natural inserts the following default content-type header into the request:

application/x-www-form-urlencoded

URL Encoding for Special Characters

When sending POST data with the content type application/x-www-form-urlencoded, certain characters must be represented by means of URL encoding, which means substituting the character with %hexadecimal-character-code. Some basic details are given here:

• Non-ASCII Characters

• Unsafe Characters

• Reserved Characters

For full details of when and why URL encoding is necessary, refer to the memorandums RFC 1630, RFC 1738 and RFC 1808 published by the World Wide Web Consortium (W3C).

Non-ASCII Characters

All non-ASCII characters (that is, valid ISO 8859/1 characters that are not also ASCII characters) must be URL encoded, for example, the file köln.html would appear in an URL as k%F6ln.html.

Unsafe Characters

URL encode the following unsafe characters when you request web pages to avoid server failures:

Reserved Characters

Some characters have special meanings in URLs, such as the colon (:) that separates the URL scheme from the rest of the URL, the double slash (//) that indicates that the URL conforms to the Common Internet Scheme syntax and the percent sign (%). Generally, when these characters appear as parts of file names, they must be URL encoded to distinguish them from their special meaning in URLs (this is a simplification, refer to the RFCs mentioned earlier for full details).

Reserved characters are:

HTTP/HTTPS Responses Redirected and Denied

For a list of HTTP/HTTPS status codes, refer to the RFC 2616 memorandum published by the World Wide Web Consortium (W3C).

The following special considerations apply to the HTTP responses for redirected and denied requests:

• Response 301 - 303 (Redirected)

• Response 401 (Denied/Unauthorized)

Response 301 - 303 (Redirected)

The HTTP response codes 301, 302 and 303 mean that the URL where the requested document resides has changed and that the request was therefore redirected to another URL. As a response, the return header with the name LOCATION will be displayed. This header contains the URL where the requested page has moved to. A new REQUEST DOCUMENT request can be used to retrieve the page moved.

HTTP browsers redirect automatically to the new URL, but the REQUEST DOCUMENT statement does not handle redirection automatically.

Response 401 (Denied/Unauthorized)

The HTTP response code 401 means that the requested page can only be accessed if a valid user ID and password are provided with the request. As a response, the return header with the name WWW-AUTHENTICATE will be delivered with the REALM needed for this request.

HTTP browsers normally display a dialog with user ID and password, but with the REQUEST DOCUMENT statement, no dialog is displayed.

Examples

• Example 1 - General Request

• Example 2 - Simple GET Request (no data)

• Example 3 - Simple HEAD Request (no return page)

• Example 4 - Simple POST Request (default request method)

• Example 5 - Simple PUT Request (with DATA ALL)

• Example 6 - REQUEST DOCUMENT with Proxy Authorization

• Example 7 - GET Request for an IPv6 Address on Port Number 8080

• Example 8 - RETURN PAGE ENCODED Clause

• Example 9 - RETURN HEADER NAME VALUE with Array Definition

Note:
There is an example dialog V5-RDOC for this statement in the example library SYSEXV.

Example 1 - General Request

REQUEST DOCUMENT FROM "http://bolsap1:5555/invoke/sap.demo/handle_RFC_XML_POST" 
  WITH
    USER #User PASSWORD #Password
    DATA
    NAME 'XMLData'       VALUE #Queryxml
    NAME 'repServerName' VALUE 'NT2'
  RETURN
    PAGE #Resultxml
RESPONSE #rc

Example 2 - Simple GET Request (no data)

REQUEST DOCUMENT FROM "http://pcnatweb:8080"
  RETURN
    PAGE #Resultxml
RESPONSE #rc

Example 3 - Simple HEAD Request (no return page)

REQUEST DOCUMENT FROM "http://pcnatweb"
RESPONSE #rc

Example 4 - Simple POST Request (default request method)

REQUEST DOCUMENT FROM "http://pcnatweb/cgi-bin/nwwcgi.exe/sysweb/nat-env"
  WITH 
    DATA 
    NAME 'XMLData'       VALUE #Queryxml
    NAME 'repServerName' VALUE 'NT2'
  RETURN
    PAGE #Resultxml
RESPONSE #rc

Example 5 - Simple PUT Request (with DATA ALL)

REQUEST DOCUMENT FROM "http://pcnatweb/test.txt"
  WITH 
    DATA ALL     #document
  RETURN
    PAGE #Resultxml
RESPONSE #rc

Example 6 - REQUEST DOCUMENT with Proxy Authorization

DEFINE DATA
LOCAL
1 #URL              (A) DYNAMIC
1 #PAGE             (A) DYNAMIC
1 #HTTPSTAT         (I4)
1 #PATH             (A) DYNAMIC
1 #NAME             (A) DYNAMIC
1 #VALUE            (A) DYNAMIC
1 #USERID           (A8)
1 #PASSWORD         (A8)
1 #AUTHHDR          (A) DYNAMIC
1 #CREDENTIALS      (A) DYNAMIC
1 #PADDCHAR         (A2/0:2) INIT  <' ','==','='>
1 #LENGTH           (I4)
1 #FACTOR           (I4)
1 #REMAINDER        (I4)
/*
/* #USR4210
1 PARM-FUNCTION  (A2) INIT <'BA'>
1 PARM-RC        (I4)
1 PARM-ERRTXT    (A72)
1 PARM-A         (A) DYNAMIC
1 PARM-B         (B) DYNAMIC
1 PARM-RFC       (B1)
END-DEFINE
**
ASSIGN #URL = 'http://www.softwareag.com/corporate/default.asp'
REQUEST DOCUMENT FROM #URL
  RETURN PAGE #PAGE ENCODED CODEPAGE ' '
  RESPONSE #HTTPSTAT
*************************************************************
** HTTP response 407 means that the proxy server requires  **
** the client to identify itself!                          **
*************************************************************
IF #HTTPSTAT = 407  
  INPUT           'Please enter userid and password' (AD=I) /
  'Userid  :' #USERID / 'Password:' #PASSWORD
  ASSIGN #AUTHHDR = 'Proxy-Authorization'
  COMPRESS #USERID ':' #PASSWORD INTO PARM-B  LEAVING NO
*************************************************************
** Convert credentials to ASCII                            **
*************************************************************
  MOVE ENCODED PARM-B TO PARM-B
   CODEPAGE 'ASCII'
*************************************************************
** ENCODE CREDENTIALS WITH BASE64                          **
*************************************************************
** BASE64 demands that the length of the encoded string is **
** a multiple of 3. If encoding length does not match this **
** the encoded string has to be padded with '=' characters.**
** Since USR4210 does not support padding of the base64    **
** string with trailing '=' characters, we have to do this **
** ourselves.                                              **
*************************************************************
  CALLNAT 'USR4210N' PARM-FUNCTION PARM-RC PARM-ERRTXT PARM-B PARM-A
    PARM-RFC
*
  #LENGTH := *LENGTH(PARM-A)
  WRITE PARM-A (AL=40) #LENGTH EJECT
  DIVIDE 3 INTO #LENGTH GIVING #FACTOR REMAINDER #REMAINDER
  COMPRESS  PARM-A #PADDCHAR(#REMAINDER)
    INTO #CREDENTIALS LEAVING NO
*************************************************************
** Build Proxy-Authorization HTTP header                   **
*************************************************************
  COMPRESS 'Basic '  #CREDENTIALS
    INTO #CREDENTIALS
  ASSIGN #AUTHHDR = 'Proxy-Authorization'
*************************************************************
** Repeat HTTP request with valid client identification    **
*************************************************************
  REQUEST DOCUMENT FROM #URL
   WITH HEADER NAME #AUTHHDR VALUE #CREDENTIALS
    RETURN PAGE #PAGE ENCODED CODEPAGE ' '
    RESPONSE #HTTPSTAT
END-IF
END

Example 7 - GET Request for an IPv6 Address on Port Number 8080

REQUEST DOCUMENT FROM "http://[2BFC:5022:4081:0000::C:41]:8080" 
  RETURN
    PAGE #Resultxml
RESPONSE #rc

Example 8 - RETURN PAGE ENCODED Clause

1. Server returns a header 'Content-type: text/html;charset=UTF-8'

   Program Code Example 1:

   ... 
   RETURN PAGE inbound-document

   Resulting Processing:

   inbound-document remains UTF-8 encoded.

   Program Code Example 2:

   ... 
   RETURN PAGE inbound-document ENCODED [...]

   Resulting Processing:

   inbound-document is converted from UTF-8 to the default code page regardless of whether code-page-in and mime-type are specified: When a valid encoding is returned in the content-type header, mime-type and code-page-in are ignored.

2. Server returns a header 'Content-type: text/xml'

   Program Code Example 1:

   ... 
   RETURN PAGE inbound-document ENCODED

   Resulting Processing:

   inbound-document remains unconverted since the content-type header does not contain a valid encoding.

   Program Code Example 2:

   ... 
   RETURN PAGE inbound-document ENCODED FOR TYPES 'text/xml' IN CODEPAGE 'USASCII'

   Resulting Processing:

   inbound-document is converted from USASCII code page to the default code page. In this case, conversion is done according to the programmers assumption about the encoding of the received page.

   Program Code Example 3:

   ... 
   RETURN PAGE inbound-document ENCODED FOR TYPES 'text/html' 
       IN CODEPAGE ' '

   Resulting Processing:

   inbound-document remains unconverted since the MIME type 'text/html', specified in mime-type, does not match the MIME type 'text/xml', returned in the content-type header.

   Program Code Example 4:

   ... 
   RETURN PAGE inbound-document ENCODED IN CODEPAGE ' '

   Resulting Processing:

   inbound-document is converted from the default code page, specified with subparameter RDCP of profile parameter XML, to the default code page.

   Note:
   The default value for the RDCP subparameter, which applies if nothing has been explicitly specified, is ISO-8859-1. See also XML - Activate PARSE XML and REQUEST DOCUMENT Statements in the Parameter Reference.

Example 9 - RETURN HEADER NAME VALUE with Array Definition

DEFINE DATA        
LOCAL
1 #FROM      (A) DYNAMIC
1 #HEADER    (A) DYNAMIC
1 #PAGE      (A) DYNAMIC
1 #COOKIES (A20/1:3,1:4,2:5)
1 #RC      (I4)
END-DEFINE
ASSIGN #FROM = 'http://www.myserver.com'
REQUEST DOCUMENT FROM #FROM
   RETURN
        HEADER NAME 'Set-Cookie' VALUE #COOKIES(1,2:3,3)
        PAGE   #PAGE  
        RESPONSE #RC 
PRINT #COOKIES(*,*,*)
END

In the example program above, invalid array definitions (with multiple dimensions) would be:

RETURN HEADER NAME 'Set-Cookie' VALUE #COOKIES(1:3,2:3,3)
RETURN HEADER NAME 'Set-Cookie' VALUE #COOKIES(*,2,*)

www.softwareag.com

Copyright © 1979-2016 Software AG, Darmstadt, Germany.

SEARCH   CONTENTS   |   PDF BOOKS   |   HOME   UP   PREV   NEXT