REQUEST
DOCUMENT FROM url
|
|||
|
|
WITH
[with-clause] |
|
|
|
|
RETURN
[return-clause] |
|
|
RESPONSE
http-response-code
|
|||
[GIVING natural-error-number] |
|||
This document covers the following topics:
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
The REQUEST DOCUMENT statement is used to retrieve and
upload documents on the internet as described in
REQUEST
DOCUMENT in Statements for Internet and XML
Access in the Programming Guide.
For information on Unicode support, see REQUEST DOCUMENT in the Unicode and Code Page Support documentation.
For technical reasons, HTTPS is supported under z/OS only.
Cookies are not supported and are ignored.
Operand Definition Table:
| Operand | Possible Structure | Possible Formats | Referencing Permitted | Dynamic Definition | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
url
|
C | S | A | yes | no | ||||||||||||||
http-response-code |
S | I4 | yes | yes | |||||||||||||||
natural-error-number |
S | I4 | yes | no | |||||||||||||||
Syntax Element Description:
| Syntax Element | Description | |
|---|---|---|
url
|
Location of Document:
If You cannot embed an Internet Protocol Version 4 (IPv4) address into an IPv6 address. |
|
with-clause |
WITH Clause:
See |
|
return-clause |
RETURN Clause:
See |
|
http-response-code |
RESPONSE:
See also HTTP/HTTPS Responses Redirected and Denied. For a list of possible HTTP/HTTPS status codes, refer to the RFC 2616 memorandum published by the World Wide Web Consortium (W3C). |
|
natural-error-number |
GIVING
Option: natural-error-number
contains the 4-digit Natural error number if the request could not be
performed.
|
|
[USER
user-id]
|
[PASSWORD
user-password]
|
[HEADER {[NAME]
header-name-out
[VALUE] header-value-out}
...]
|
[DATA {ALL outbound-document
[ENCODED [[IN]
CODEPAGE code-page-out]]
|
|{[NAME] variable-name-out
[VALUE] variable-value-out}
...}]
|
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:
| Operand | Possible Structure | Possible Formats | Referencing Permitted | Dynamic Definition | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
user-id
|
C | S | A | yes | no | ||||||||||||||
user-password
|
C | S | A | yes | no | ||||||||||||||
header-name-out
|
C | S | A | yes | no | ||||||||||||||
header-value-out
|
C | S | A | N | P | I | F | D | T | L | yes | no | |||||||
outbound-document
|
C | S | A | U | N | P | I | F | B | D | T | L | yes | no | |||||
code-page-out
|
C | S | A | yes | no | ||||||||||||||
variable-name-out
|
C | S | A | yes | no | ||||||||||||||
variable-value-out
|
C | S | A | N | P | I | F | D | T | L | yes | no | |||||||
Syntax Element Description:
| Syntax Element | Description | |
|---|---|---|
user-id
|
USER:
|
|
user-password
|
PASSWORD:
|
|
header-name-out
|
HEADER NAME/VALUE Option:
header-name-out:
Header names must not contain a carriage return (CR), a line feed
(LF) or a colon (:). This will not be checked by the header-value-out:
Header values are not allowed to contain CR/LF. This will not be
checked by the See also Automatically Generated Headers. |
|
outbound-document
|
DATA ALL Option:
|
|
code-page-out |
DATA ALL ENCODED Option:
Data transfer with the
If the outbound document contains an encoding (XML) or a charset
(HTML) attribute, we recommend that the value of the Example: If an outbound XML document contains the attribute
encoding |
|
variable-name-out
|
DATA NAME/VALUE Option:
Restriction:
If |
|
[HEADER [ALL
header-all-in]
[[NAME] header-name-in
[VALUE] header-value-in
...]]
|
[PAGE
inbound-document
[ENCODED [[FOR
TYPES mime-type ...]
[IN] CODEPAGE
code-page-in]]]
|
Operand Definition Table:
| Operand | Possible Structure | Possible Formats | Referencing Permitted | Dynamic Definition | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
header-all-in
|
S | A | yes | yes | |||||||||||||||
header-name-in
|
C | S | A | yes | no | ||||||||||||||
header-value-in
|
S | A * | A | N | P | I | F | B | D | T | L | yes | yes | ||||||
inbound-document
|
S | A | U | B | yes | yes | |||||||||||||
mime-type
|
C | S | A | yes | no | ||||||||||||||
code-page-in |
C | S | A | yes | no | ||||||||||||||
This clause can be used to specify return information for the headers and/or the document.
Syntax Element Description:
| Syntax Element | Description | |
|---|---|---|
header-all-in |
HEADER ALL Option:
The first line contains the status information and all following lines contain the headers as pairs of name and value. The names always end in a colon (:) and the values end in a line feed (LF). Internally, all carriage returns/line feeds (CR/LF) are transformed into line feeds (LF). |
|
header-name-in
|
HEADER NAME/VALUE Option:
|
|
inbound-document |
PAGE Option:
|
|
code-page-in |
PAGE ENCODED Option:
Data transfer with the If necessary,
If the value of
Note: For examples of using the |
|
mime-type |
PAGE ENCODED FOR TYPES Option:
As a response of an HTTP/HTTPS request, incoming data may contain
binary data (for example, image/gif) or character data (for example,
text/html). Together with the response, the If the returned MIME type contains an encoding,
If the returned MIME type does not contain an encoding, then
If the returned MIME type does not contain an encoding, then an
additional check is performed if the returned MIME type matches one of the
types given with |
|
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.
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:
WITH HEADER |
WITH DATA |
RETURN HEADER |
RETURN PAGE |
|
| HEAD | o | - | x | - |
|---|---|---|---|---|
| POST | o | x | o | x |
| GET | o | - | o | x |
| PUT | o | DATA ALL
* |
o | o |
In addition to the standard REQUEST-METHODs
mentioned above, the methods DELETE, PATCH,
OPTIONS and TRACE can be specified in a
REQUEST-METHOD header.
| o | Optional. Operand can be optionally specified. |
| - | Operand cannot be specified. |
| x | Operand is always specified. |
| * | Only applies to DATA ALL and not
DATA NAME VALUE.
|
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
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:
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).
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.
URL encode the following unsafe characters when you request web pages to avoid server failures:
| Unsafe Character | URL Encoding |
|---|---|
| the tab character | %09 |
| the space character | %20 |
| [ | %5B |
| \ | %5C |
| ] | %5D |
| ^ | %5E |
| ` | %60 |
| { | %7B |
| | | %7C |
| } | %7D |
| ~ | %7E |
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:
| Reserved Character | URL Encoding |
|---|---|
| " | %22 |
| # | %23 |
| % | %25 |
| & | %26 |
| + | %2B |
| , | %2C |
| / | %2F |
| : | %3A |
| < | %3C |
| = | %3D |
| > | %3E |
| ? | %3F |
| @ | %40 |
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:
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.
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.
Note:
There is an example dialog V5-RDOC for this statement
in the example library SYSEXV.
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
REQUEST DOCUMENT FROM "http://pcnatweb:8080"
RETURN
PAGE #Resultxml
RESPONSE #rc
REQUEST DOCUMENT FROM "http://pcnatweb" RESPONSE #rc
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
REQUEST DOCUMENT FROM "http://pcnatweb/test.txt"
WITH
DATA ALL #document
RETURN
PAGE #Resultxml
RESPONSE #rc
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
REQUEST DOCUMENT FROM "http://[2BFC:5022:4081:0000::C:41]:8080"
RETURN
PAGE #Resultxml
RESPONSE #rc
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.
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.
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,*)